v0.1.2

ipcprims v0.1.2

Release date: 2026-02-15
Lifecycle phase: alpha
License: MIT OR Apache-2.0

Summary

Release pipeline: multi-platform FFI build matrix, SBOM generation, and structured draft releases — matching the sysprims/docprims release pattern. Resolves the v0.1.1 known issue where release.yml was still the minimal v0.1.0 skeleton.

release.yml Rewrite

Complete rewrite from 4-job skeleton to 14 release-specific jobs (35 total including CI workflow_call).

Release Jobs

Job	Runner	Purpose
validate-version	ubuntu-latest	Tag matches VERSION file, outputs version
ci	(workflow_call)	Full CI suite (21 jobs)
verify-go-bindings-assets	ubuntu-latest	Verify prebuilt libs for 7 platforms in Go module
build-linux	ubuntu-latest (container)	4-target matrix (x64/arm64 x glibc/musl), CLI + FFI
build-macos	macos-latest	x64 + arm64, CLI + FFI, @rpath dylib fix
build-windows	windows-latest	MinGW/GNU x64, FFI only (CGo compat)
build-windows-arm64	windows-latest-arm64-s	MSVC arm64, FFI only (self-hosted)
build-windows-msvc	windows-latest	MSVC x64 shared-only, FFI only
cbindgen	ubuntu-latest (container)	Generate ipcprims.h C header
sbom	ubuntu-latest (container)	CycloneDX SBOM via syft
verify-ffi-shared-assets	ubuntu-latest	Verify shared libs present, no musl shared
package-ffi-bundle	ubuntu-latest	Structured bundle with 8 platform dirs + MANIFEST.json
publish-check	ubuntu-latest	cargo package --workspace dry-run
publish	ubuntu-latest	Draft GitHub release with all artifacts + platform table

CLI Artifacts (6 platforms)

Platform	Archive
Linux x64 (glibc)	ipcprims-<version>-linux-amd64.tar.gz
Linux x64 (musl)	ipcprims-<version>-linux-amd64-musl.tar.gz
Linux arm64 (glibc)	ipcprims-<version>-linux-arm64.tar.gz
Linux arm64 (musl)	ipcprims-<version>-linux-arm64-musl.tar.gz
macOS x64	ipcprims-<version>-darwin-amd64.tar.gz
macOS arm64	ipcprims-<version>-darwin-arm64.tar.gz

No Windows CLI — CLI requires Unix domain sockets (named pipe transport lands in v0.2.0).

FFI Bundle Structure

bundle/
  lib/
    linux-amd64/        static/ + shared/
    linux-amd64-musl/   static/ only
    linux-arm64/        static/ + shared/
    linux-arm64-musl/   static/ only
    darwin-amd64/       static/ + shared/
    darwin-arm64/       static/ + shared/
    windows-amd64/      static/ + shared/ (GNU + MSVC import libs)
    windows-arm64/      static/ + shared/ (MSVC)
  include/
    ipcprims.h
  MANIFEST.json
  VERSION
  LICENSE-MIT
  LICENSE-APACHE

Build Patterns

• Linux: cargo-zigbuild in goneat container, glibc 2.17 baseline for GNU targets, crt-static for musl
• macOS: native cross-compile x64+arm64, MACOSX_DEPLOYMENT_TARGET=11.0, install_name_tool -id @rpath/...
• Windows: real Windows runners required (ring needs MSVC lib.exe); MinGW/GNU for CGo compat, MSVC for arm64 and shared-only
• SBOM: syft CycloneDX in sbom-tools container

Peer Crate Windows Compilation

cfg-gated ipcprims-peer Unix-specific imports behind #[cfg(unix)] so ipcprims-ffi compiles on all Windows targets:

• connector.rs: UnixDomainSocket import gated; #[cfg(not(unix))] returns TransportError::Connect with Unsupported
• listener.rs: PeerListener struct uses #[cfg(unix)] socket / #[cfg(not(unix))] _unavailable: (); bind/accept return Unsupported
• Tests gated with #[cfg(all(test, unix))]
• No fake runtime support — non-Unix builds fail explicitly at the API boundary

This follows the IpcStreamInner::Unavailable placeholder pattern from ipcprims-transport. Full Windows implementation (named pipes) deferred to v0.2.0.

Adaptation from Brief

Windows x64 shared artifact names split into GNU and MSVC variants (ffi-shared-windows-amd64-gnu, ffi-shared-windows-amd64-msvc) to avoid upload-artifact name collision. Both are merged into bundle/lib/windows-amd64/shared/ in the final FFI bundle, preserving both import library variants for consumers.

Quality

• 122 tests passing (cargo test --workspace --all-features)
• Zero clippy warnings (--all-features)
• make prepush green (fmt + clippy + goneat lint + test + cargo deny)
• All dependencies permissively licensed
• actionlint passes on release.yml

Known Issues

• Go prebuilt libs: Not yet populated — go-bindings.yml must run before tagging to create prebuilt libs PR (d4-02 pre-tag checklist).
• Async API: Feature flags declared but no async code exists. Planned for v0.2.0.
• Transitive dep duplication: getrandom (0.2 + 0.3) and windows-sys (0.60 + 0.61) via jsonschema dep tree. No functional impact.

What's Next

• v0.1.2 pre-tag: Run go-bindings.yml via workflow_dispatch, merge prebuilt libs PR, then tag
• v0.2.0: Tokio-native async API, named pipe transport for Windows (full IpcStreamInner::NamedPipe variant), TCP transport (per DDR-0001), CLI P2 commands

Release 0.1.1

ipcprims v0.1.1

Release date: 2026-02-15
Lifecycle phase: alpha
License: MIT OR Apache-2.0

Summary

Infrastructure release: cross-language binding scaffolds (FFI, Go, TypeScript) and CI/release pipeline maturation. No new Rust API surface — bindings wrap the existing v0.1.0 API.

New Crates

Crate	Description
ipcprims-ffi	C-ABI exports (staticlib + cdylib) for listener, peer, frame, schema
ipcprims-napi	Node-API addon for @3leaps/ipcprims TypeScript package

Bindings

FFI (C-ABI)

• Crate: crates/ipcprims-ffi
• Outputs: static library (.a/.lib) and shared library (.so/.dylib/.dll)
• C header generated by cbindgen (ipcprims.h)
• Smoke test: tests/ffi/smoke.c
• CI job: build + header generation + C compile on Linux and macOS

Go

• Module: bindings/go/ipcprims (github.com/3leaps/ipcprims/bindings/go/ipcprims)
• API: Listener, Peer, SchemaRegistry, channel constants, Frame type
• FFI bridge: CGo with platform-specific build tags
• Stub bridge: compiles on all platforms, returns ErrFFIUnavailable without prebuilt libs
• CI job: go build, golangci-lint, go test on Linux and macOS
• Prep workflow: go-bindings.yml builds FFI for all platforms and creates PR with prebuilt libs

TypeScript

• Package: @3leaps/ipcprims at bindings/typescript
• API: Listener, Peer, SchemaRegistry, channel constants
• Runtime: NAPI-RS native addon with platform-specific optional dependencies
• Platforms: linux-x64-gnu, linux-x64-musl, linux-arm64-gnu, darwin-arm64, win32-x64-msvc
• CI job: build + test + typecheck on Linux and macOS
• Prebuild workflow: typescript-napi-prebuilds.yml builds .node files for all 5 platforms
• Publish workflow: typescript-npm-publish.yml with OIDC trusted publishing

CI Changes

New Jobs in ci.yml

Job	Runner	Description
windows-cross-check	ubuntu-latest	cargo check for 3 Windows targets (no SDK required)
test-musl	ubuntu-latest	Build + test on x86_64-unknown-linux-musl
ffi	ubuntu-latest, macos-latest	Build FFI crate, generate header, compile C smoke test
go-bindings	ubuntu-latest, macos-latest	Go build + lint + test
typescript-bindings	ubuntu-latest, macos-latest	NAPI build + test + typecheck

New Workflows

Workflow	Trigger	Purpose
go-bindings.yml	workflow_dispatch	Multi-platform FFI build + PR with prebuilt Go libs
typescript-bindings.yml	workflow_dispatch	Cross-platform TS test (4 OS + Alpine musl)
typescript-napi-prebuilds.yml	workflow_dispatch	Build .node prebuilds for 5 platforms
typescript-npm-publish.yml	workflow_dispatch	OIDC trusted npm publish

Release Infrastructure

• Download script: now fetches FFI bundles (ipcprims-ffi-*.tar.gz), C header (ipcprims.h), and SBOM (sbom-*.json)
• Upload script: now uploads FFI bundles, standalone header, and SBOM
• Checksum script: patterns include standalone headers, libraries, and JSON metadata
• RELEASE_CHECKLIST.md: Go pre-tag workflow and TypeScript post-signing publish steps
• Makefile: binding workflow instructions replace placeholder stubs

Tooling

• .github/actionlint.yaml: self-hosted runner label (ubuntu-latest-arm64-s)
• Root go.mod + go.work + internal/gowork/doc.go: repo-level Go workspace for golangci-lint compatibility
• .goneat/assess.yaml: Go linting note, shellcheck disabled (sysprims parity)

Fixes

• FFI map_peer_error: wildcard catch-all for Cargo workspace feature unification (prevents E0004 when ipcprims-napi activates PeerError::Schema across workspace)
• FFI ipc_schema_registry_free: suppressed needless_return lint on cfg-gated early return
• TypeScript test: replaced any types with typed NativePeer/NativeListener interfaces
• TypeScript loader: replaced && chain with optional chaining

Quality

• 118 tests passing (cargo test --workspace --all-features)
• Zero clippy warnings (--all-features)
• make prepush green (fmt + clippy + goneat lint + test + cargo deny)
• All dependencies permissively licensed

Known Issues

• release.yml: Still uses minimal v0.1.0 skeleton (validate + create GitHub release). Multi-platform build matrix with FFI bundle packaging planned for v0.1.2.
• Go prebuilt libs: Not yet populated — go-bindings.yml creates the PR. Stub bridge compiles but FFI calls return ErrFFIUnavailable without prebuilts.
• Async API: Feature flags declared but no async code exists. Planned for v0.2.0.
• Transitive dep duplication: getrandom (0.2 + 0.3) and windows-sys (0.60 + 0.61) via jsonschema dep tree. No functional impact.

What's Next

• v0.1.2: Release pipeline rewrite — multi-platform FFI build matrix, SBOM generation, structured FFI bundle packaging, draft release with all artifacts
• v0.2.0: Tokio-native async API, TCP transport (per DDR-0001), CLI P2 commands

Release 0.1.0

ipcprims v0.1.0

Release date: 2026-02-13
Lifecycle phase: alpha
License: MIT OR Apache-2.0

Summary

First functional release of ipcprims — permissively licensed, cross-platform IPC primitives with framed messaging, channel multiplexing, schema validation, peer management, and a diagnostic CLI.

Highlights

• Transport layer: Unix domain socket transport with bind/accept/connect, hardened permissions (0o600), automatic socket cleanup on drop
• Frame codec: Length-prefixed wire format with 2-byte magic ("IP"), 4-byte LE length, 2-byte LE channel ID; 8-byte header, 16 MiB default max payload
• Channel system: Built-in channels (CONTROL=0, COMMAND=1, DATA=2, TELEMETRY=3, ERROR=4) with user-defined range 256-65535
• Framed reader/writer: Sync FrameReader/FrameWriter wrapping any Read/Write stream; partial-read handling, WouldBlock propagation, configurable timeouts
• Schema validation: JSON Schema 2020-12 validation at the transport boundary via SchemaRegistry; strict mode (deny_unknown_fields), directory loading with symlink rejection and file-size limits
• Peer management: Handshake protocol over CONTROL channel with version negotiation, channel intersection, and optional auth token; Peer API with send/recv/recv_on/request patterns, bounded per-channel buffering, control flood protection, graceful shutdown
• CLI: 8 commands — listen, send, echo, info, doctor, envinfo, version (with --extended); --format json|table|pretty|raw, rsfulmen-aligned exit codes, tracing to stderr
• Security review: 5 accepted SDRs (schema validation scope, peer/transport hardening, registry boundaries, auth token handling, ordering/replay boundary)
• Dogfooding: End-to-end CLI behavior matrix with P0-P3 findings all remediated

Crates

Crate	Description
ipcprims-transport	Cross-platform IPC transport abstraction (UDS on Linux/macOS)
ipcprims-frame	Length-prefixed message framing with channel multiplexing
ipcprims-schema	Optional JSON Schema 2020-12 validation (behind schema feature)
ipcprims-peer	High-level peer connection management (behind peer feature)
ipcprims	Umbrella crate (re-exports) + CLI binary (behind cli feature)

CLI Commands

Command	Purpose
listen	Start a listener on a Unix domain socket
send	Connect and send a framed message (with --wait and --wait-timeout)
echo	Echo server for integration testing (with --validate for schema checks)
info	Connection diagnostics and peer status
doctor	Environment health check
envinfo	Build and platform metadata
version	Version with --extended provenance (git hash, target triple)

Exit Codes

Condition	Code
Success	0
Connection refused	1
Transport error	3
Health check failed	30
Permission denied	50
Schema validation / data invalid	60
Invalid arguments (usage)	64
Timeout	124
Internal error	125

Wire Format

+----------+---------+---------+-----------------+
| Magic 2B | Len 4B  | Chan 2B | Payload         |
| "IP"     | (LE)    | (LE)    | (Len bytes)     |
+----------+---------+---------+-----------------+

Wire format is frozen for the 0.x series.

Platform Support

Platform	Transport	Status
Linux x64/arm64 (glibc + musl)	UDS (abstract)	Primary
macOS arm64	UDS (filesystem)	Supported
Windows x64	Named pipes	Deferred to v0.2.0

Quality

• 118 tests passing (cargo test --workspace --all-features)
• Zero clippy warnings (--all-features)
• License-clean: all dependencies MIT/Apache-2.0/BSD/ISC (verified via cargo deny)
• Decision records: DDR-0001, DDR-0002, SDR-0001 through SDR-0005 (all Accepted)

Known Issues

• Async API: Feature flags (async) are declared but no async code exists yet. Planned for v0.2.0.
• Transitive dep duplication: getrandom (0.2 + 0.3) and windows-sys (0.60 + 0.61) appear as duplicates via the jsonschema dependency tree. No functional impact; tracked for supply chain awareness.
• FFI: cbindgen.toml is present as a placeholder; the ffi/ crate does not exist yet. Planned for v0.2.0.

What's Next (v0.2.0)

• Tokio-native async API behind async feature flag
• TCP transport behind feature flag (per DDR-0001)
• CLI P2 commands: connect --interactive, monitor, bench
• FFI crate + Go bindings

Decision Records

ID	Title	Status
DDR-0001	Transport Scope: IPC-First, Extensible	Accepted
DDR-0002	CLI Design Precepts	Accepted
SDR-0001	Schema Validation at IPC Boundary	Accepted
SDR-0002	Peer and Transport Hardening Defaults	Accepted
SDR-0003	Schema Registry Hardening Boundaries	Accepted
SDR-0004	auth_token and Peer Credentials Boundary	Accepted
SDR-0005	Ordering and Replay Boundary	Accepted