Prepare v0.2.5 release

.gitignore

@@ -89,7 +89,7 @@ yarn-debug.log*
 yarn-error.log*
 
 # Root-level npm lockfile (repo tooling only)
-package-lock.json
+/package-lock.json
 
 # NAPI-RS build artifacts
 bindings/typescript/target/

CHANGELOG.md

@@ -13,6 +13,20 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.2.5] — 2026-08-25
+
+Patch release for TypeScript package interoperability and SchemaRegistry guidance.
+
+### Changed
+
+- **TypeScript package exports**: the package now provides explicit CommonJS and ESM entrypoints with matching declarations, including ESM named imports.
+- **SchemaRegistry documentation**: added configuration, strict-mode, directory-loading, peer-integration, and TypeScript usage guidance.
+
+### Compatibility
+
+- CommonJS `require()` support remains available. The TypeScript package continues to require Node.js 20+.
+- No wire format, peer transport, or SchemaRegistry runtime behavior changed in this release.
+
 ## [0.2.4] — 2026-08-21
 
 Patch release for a compatible Rust lockfile refresh, including `h2` 0.4.18 on the schema HTTP resolver path.
@@ -228,7 +242,8 @@ First functional release. Transport, framing, schema validation, peer management
 - Transitive dependency duplication: `getrandom` (0.2 + 0.3) and `windows-sys` (0.60 + 0.61) via `jsonschema` dependency tree. No functional impact; tracked for supply chain awareness.
 - `cbindgen.toml` is present as a placeholder; the `ffi/` crate does not exist yet. Shipped in v0.1.1.
 
-[Unreleased]: https://github.com/3leaps/ipcprims/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/3leaps/ipcprims/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/3leaps/ipcprims/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/3leaps/ipcprims/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/3leaps/ipcprims/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/3leaps/ipcprims/compare/v0.2.1...v0.2.2

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.2.4"
+version = "0.2.5"
 edition = "2021"
 rust-version = "1.88.0"
 license = "MIT OR Apache-2.0"
@@ -23,11 +23,11 @@ categories = ["os", "network-programming"]
 
 [workspace.dependencies]
 # Internal dependencies
-ipcprims-transport = { version = "0.2.4", path = "crates/ipcprims-transport" }
-ipcprims-frame = { version = "0.2.4", path = "crates/ipcprims-frame" }
-ipcprims-schema = { version = "0.2.4", path = "crates/ipcprims-schema" }
-ipcprims-peer = { version = "0.2.4", path = "crates/ipcprims-peer" }
-ipcprims-ffi = { version = "0.2.4", path = "crates/ipcprims-ffi" }
+ipcprims-transport = { version = "0.2.5", path = "crates/ipcprims-transport" }
+ipcprims-frame = { version = "0.2.5", path = "crates/ipcprims-frame" }
+ipcprims-schema = { version = "0.2.5", path = "crates/ipcprims-schema" }
+ipcprims-peer = { version = "0.2.5", path = "crates/ipcprims-peer" }
+ipcprims-ffi = { version = "0.2.5", path = "crates/ipcprims-ffi" }
 
 # Core
 bytes = "1"

Makefile

@@ -507,7 +507,7 @@ version-set: ## Set explicit version (V=X.Y.Z)
 	@echo "$(V)" > $(VERSION_FILE)
 	@echo "Version set to $(V)"
 
-version-sync: ## Sync VERSION file to Cargo.toml and package.json
+version-sync: ## Sync VERSION file to Cargo.toml and TypeScript package manifests
 	@ver=$$(cat $(VERSION_FILE)); \
 	if command -v cargo-set-version >/dev/null 2>&1; then \
 		cargo set-version --workspace "$$ver"; \
@@ -530,6 +530,10 @@ version-sync: ## Sync VERSION file to Cargo.toml and package.json
 			fi; \
 		done; \
 		echo "[ok] Synced $$ts_root/npm/*/package.json to $$ver"; \
+		if [ -f "$$ts_root/package-lock.json" ]; then \
+			(cd "$$ts_root" && npm install --package-lock-only --ignore-scripts); \
+			echo "[ok] Synced $$ts_root/package-lock.json to $$ver"; \
+		fi; \
 	fi
 
 version-check: ## Validate version consistency across files

README.md

@@ -28,6 +28,7 @@ You're building software where multiple processes need to communicate locally 
 - **Cross-platform**: Unix domain sockets on Linux/macOS and Windows named pipes.
 - **Sync + Async (Tokio)**: Blocking sync API plus Tokio-native async API behind `async` feature flag. Windows sync named pipes use overlapped I/O for timeout enforcement; Windows async named pipes are also supported.
 - **Library-first**: Embed directly in Rust, Go, Python, or TypeScript. CLI is a diagnostic/demo tool.
+- **TypeScript module flexibility**: ESM named imports and CommonJS `require()` from a single Node-API package (Node.js 20+).
 
 ### Framed-by-Default: The Core Difference
 
@@ -132,6 +133,39 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+### As a TypeScript Library (ESM)
+
+The package supports ESM named imports and CommonJS `require()` from the same
+install. Node.js 20+ required.
+
+```ts
+import { AsyncListener, AsyncPeer, COMMAND } from "@3leaps/ipcprims";
+
+const listener = AsyncListener.bind("/tmp/ipcprims.sock", {
+  channels: [COMMAND],
+});
+
+const accepted = listener.accept();
+const client = await AsyncPeer.connect("/tmp/ipcprims.sock", [COMMAND]);
+const server = await accepted;
+
+await server.send(COMMAND, Buffer.from("hello"));
+const frame = await client.recvAsync();
+
+client.close();
+server.close();
+await listener.close();
+```
+
+CommonJS consumers keep working unchanged:
+
+```js
+const { Peer, COMMAND } = require("@3leaps/ipcprims");
+```
+
+See the [TypeScript binding guide](bindings/typescript/README.md) for async
+receivers, auth-token handling, and SchemaRegistry usage.
+
 ### As a CLI
 
 ```bash
@@ -227,7 +261,7 @@ The module follows sibling-repo layout conventions with `include/` (generated he
 
 ### TypeScript bindings
 
-TypeScript bindings scaffold is provided at `bindings/typescript` using Node-API (`ipcprims-napi`).
+The `@3leaps/ipcprims` package (Node-API) ships an explicit dual CommonJS/ESM surface with matching declaration files. ESM consumers can use named imports (`import { AsyncPeer, COMMAND } from "@3leaps/ipcprims"`) while CommonJS `require()` remains fully supported from the same package — no separate package or build step. Requires Node.js 20+. See the [TypeScript binding guide](bindings/typescript/README.md) for async peer, auth-token, and SchemaRegistry usage.
 
 ## Platform Support
 

RELEASE_CHECKLIST.md

@@ -15,7 +15,7 @@ This document walks maintainers through the build/sign/upload flow for each ipcp
 
 - [ ] Update `VERSION` file with new semver (e.g., `0.2.0`)
 - [ ] Sync version to all manifests: `make version-sync`
-  - Syncs `Cargo.toml` workspace, `Cargo.lock`, and all `bindings/typescript` `package.json` files
+  - Syncs the `Cargo.toml` workspace, `Cargo.lock`, TypeScript package manifests, and `bindings/typescript/package-lock.json`
   - **Do not skip**: version drift between `VERSION` and `Cargo.toml` is a hard failure in `make prepush`
 - [ ] Update `CHANGELOG.md` (move Unreleased section to new version heading)
   - **Do not skip footer links**: add `[X.Y.Z]` compare link and re-anchor `[Unreleased]` to compare from the new tag to `HEAD`
@@ -29,7 +29,7 @@ This document walks maintainers through the build/sign/upload flow for each ipcp
 
   1. Working tree clean check
   2. `make prepush` — fmt, clippy, tests, cargo-deny, **version consistency**
-  3. `make version-check` — full consistency: `VERSION`, `Cargo.toml`, all TypeScript packages
+  3. `make version-check` — full consistency: `VERSION`, `Cargo.toml`, TypeScript package manifests, and the TypeScript package lockfile
   4. Release notes exist at `docs/releases/vX.Y.Z.md`
   5. Local/remote sync (no unpushed or unpulled commits)
 

RELEASE_NOTES.md

@@ -6,6 +6,28 @@
 
 ---
 
+## v0.2.5 — 2026-08-25
+
+Patch release for TypeScript package interoperability and SchemaRegistry guidance.
+
+### Highlights
+
+- **CommonJS and ESM entrypoints**: `@3leaps/ipcprims` now exposes explicit conditional exports with matching declaration files. ESM consumers can use named imports while CommonJS `require()` remains supported.
+- **SchemaRegistry guide**: new documentation covers configuration defaults, strict-mode behavior, safe directory loading, Rust peer integration, CLI validation, and standalone TypeScript validation.
+
+### Compatibility
+
+- **Node.js**: the TypeScript package continues to require Node.js 20+.
+- **Runtime behavior**: no wire format, peer transport, or SchemaRegistry runtime behavior changed.
+
+### Known Issues
+
+- **NAPI-RS major update deferred**: `@napi-rs/cli` 3.x and Rust `napi`/`napi-derive` 3.x remain on 2.x.
+
+Full release details: [docs/releases/v0.2.5.md](docs/releases/v0.2.5.md)
+
+---
+
 ## v0.2.4 — 2026-08-21
 
 Patch release for a compatible Rust lockfile refresh, including `h2` 0.4.18 on the schema HTTP resolver path.
@@ -55,27 +77,3 @@ Fast-follow release for dependency hygiene, MSRV alignment, and TypeScript runti
 - **Transitive dep duplication**: `getrandom` (0.2 + 0.3) and `hashbrown` (0.16 + 0.17) remain via the current `jsonschema`/HTTP/TLS graph. No functional impact.
 
 Full release details: [docs/releases/v0.2.3.md](docs/releases/v0.2.3.md)
-
----
-
-## v0.2.2 — 2026-07-06
-
-**Breaking wire change for token-authenticated peers:** token-bearing handshakes now encode `auth_token` as bytes rather than a UTF-8 string. No-auth peers remain compatible because the field is omitted, but older token-authenticated peers that send string tokens fail closed. Upgrade both sides together when using token auth.
-
-This release adds the async TypeScript peer surface and hardens auth-token handling across Rust, C FFI, Go, and TypeScript bindings.
-
-### Highlights
-
-- **TypeScript async peer API**: `AsyncPeer`, `AsyncListener`, async receives, async channel receivers, and promise-based send/ping/shutdown are now backed by the Rust async peer implementation.
-- **Opaque token bytes**: Auth tokens now cross the Rust handshake, C ABI, Go bindings, and TypeScript bindings as byte buffers instead of strings.
-- **Zeroizing ownership**: ipcprims-owned token buffers use zeroizing storage; FFI token retrieval returns caller-owned bytes that must be released with the dedicated zeroizing token free function.
-- **Explicit server retrieval**: Server peers expose a distinct no-token state and clear stored token material after retrieval.
-- **Binding examples**: Go and TypeScript examples use constant-time comparison patterns with clean length-mismatch rejection before treating a peer as authenticated.
-
-### Compatibility
-
-- **Cross-version token-authenticated peers**: No known deployed cross-version token-authenticated peers exist for this release window; consumers using token auth should upgrade both sides together.
-
-Full release details: [docs/releases/v0.2.2.md](docs/releases/v0.2.2.md)
-
----

VERSION

@@ -1 +1 @@
-0.2.4
+0.2.5

bindings/typescript/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3leaps/ipcprims-darwin-arm64",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/3leaps/ipcprims.git",

bindings/typescript/npm/linux-arm64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3leaps/ipcprims-linux-arm64-gnu",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/3leaps/ipcprims.git",

bindings/typescript/npm/linux-x64-gnu/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3leaps/ipcprims-linux-x64-gnu",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/3leaps/ipcprims.git",

bindings/typescript/npm/linux-x64-musl/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3leaps/ipcprims-linux-x64-musl",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/3leaps/ipcprims.git",

bindings/typescript/npm/win32-x64-msvc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3leaps/ipcprims-win32-x64-msvc",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/3leaps/ipcprims.git",