stitchkit 0.106.0 → 0.107.0

package/llms/{upgrading-0.96.0-0.106.0.txt → upgrading-0.98.0-0.107.0.txt}

@@ -1,14 +1,46 @@
-# Upgrading 0.96.0 → 0.106.0 — stitchkit docs slice
+# Upgrading 0.98.0 → 0.107.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.96.0 → 0.106.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.98.0 → 0.107.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.96.0 → 0.106.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.98.0 → 0.107.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.107.0
+
+### embedded native packaging names no paths
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) with
+`delivery: 'embedded'`. Companion delivery is unchanged.
+
+A standalone executable carries the Darwin addon inside itself, so the embedded form takes only
+`platform`, `architecture` and `delivery`. `entryPath` and `assetPath` were required before but
+changed nothing in the executable; passing them now is a type error and a schema refusal. The
+ready result names the embedded addon by `NativePackagingEmbeddedAsset` (`bytes`, `size`,
+`sha256`), without `outputPath`, since nothing is written beside the executable.
+
+1. Drop the two paths from the embedded call:
+
+   ```ts
+   // before
+   createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+     entryPath: 'cli.js', assetPath: 'native/darwin-arm64.node',
+   })
+   // after
+   createNativePackaging({ platform: 'darwin', architecture: 'arm64', delivery: 'embedded' })
+   ```
+
+   Search pattern: `delivery: 'embedded'`.
+2. Code that read `asset.outputPath` from an embedded result reads `bytes`, `size` and `sha256`
+   only; an annotation `NativePackagingOptions` / `NativePackagingResult` on an embedded call
+   becomes `NativePackagingEmbeddedOptions` / `NativePackagingEmbeddedResult`.
+3. Rebuild every artifact made without the plugin by 0.105.0–0.106.1: it carries the build
+   machine's package path (see [Darwin native assets in JS distributions](#darwin-native-assets-in-js-distributions)).
+
 ## Released migration: 0.106.0
 
 ### a stopped leader settles as stopped
@@ -609,13 +641,27 @@ Custom output layout uses the evolving build-only packaging contract in the
 Three deliveries have different rules: an ordinary npm install retains the package's
 native assets; a JS distribution must ship its complete output graph; a Bun compiled
 executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
-`bun build` carries the addon without a plugin; later releases carry it only when the build
-uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a compiled
-executable).
-The [native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe.
-Check the resulting artifact offline outside the build tree and `node_modules`, including
-process identity, live-owner lock refusal, dead-owner recovery and contained IO.
-A missing or corrupt addon remains `unavailable`, never evidence that an owner died.
+`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
+the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
+compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
+executable, but the loader never uses them, so their presence proves nothing.
+
+What an unpackaged bundle does depends on the release:
+
+- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
+  because the loader read `__dirname`. It looks for the addon there, so it works only on that
+  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
+- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
+  addon reports the Darwin backend `unavailable` with stage `packaging`.
+
+Only macOS is affected, and only process identity (`observeProcessInstance`,
+`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
+managed file boundary, atomic writes and the chunk spool never do. The
+[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
+shows how to check an artifact by its loader without running it on a Mac. Check the resulting
+artifact offline outside the build tree and `node_modules`, including process identity,
+live-owner lock refusal, dead-owner recovery and contained IO. A missing or corrupt addon
+remains `unavailable`, never evidence that an owner died.
 
 ### CLI: repeated options are refused
 
@@ -859,76 +905,3 @@ availability probe. A custom reader owns its limits and error handling.
 `-` remains literal data. TTY and empty EOF produce ordinary validation errors;
 explicit arguments skip stdin. JSONL stream/batch commands, MCP/serve and
 long-running handlers have no new deadline. See ADR 0203.
-
-## Released migration: 0.97.0
-
-### schedule delivery
-
-**Who must act:** consumers of `createAgentScheduleService`, exhaustive switches on
-`AgentSchedule.state`, and operators opening existing agent-runtime SQLite stores.
-
-- Stop old scheduler processes and back up SQLite before startup. The store migrates
-  transactionally to v4; old binaries cannot open it. Rollback uses the backup.
-- Handle `failed` as a terminal schedule state. To refuse future delivery (including
-  recurring delivery), return `{ status: 'terminal', reason: 'destination closed' }`.
-  The occurrence remains unadvanced; `schedule/failed` carries `terminal: true`.
-- A throw or `{ status: 'retry', reason: 'temporarily unavailable' }` retries the same
-  key after 1, 2, 4, 8, 16, 32, then 60 seconds. `nextAt` remains the original due time;
-  `retryAt`, `attempts` and `lastError` expose retry diagnostics. Success clears them.
-- Resolve `void` only after durable consumer admission. Honor the supplied `signal`:
-  dispatch has a 30-second deadline and a 60-second lease. Durable deduplication by
-  `idempotencyKey` is required even after abort or crash; do not implement sleeps in dispatch.
-- Stale/cancelled attempts emit no `schedule/fired` or `schedule/late`. Observe the
-  cancellation event instead of relying on a synthetic cancelled firing.
-
-```ts
-// before
-async function dispatch(request) {
-  if (await destinationClosed(request.conversationId)) throw new Error('closed')
-  await admit(request)
-}
-// after: use this callback as createAgentScheduleService({ dispatch, ... })
-async function dispatch(request) {
-  if (await destinationClosed(request.conversationId)) {
-    return { status: 'terminal', reason: 'destination closed' }
-  }
-  await admit({ ...request, signal: request.signal }) // durably deduplicates idempotencyKey
-}
-```
-
-## Released migration: 0.96.0
-
-### resource-context-admission
-
-One breaking change in `stitchkit/application`: `ManagedResourceContext` gains a
-required `admission`. Every context the kernel hands a resource already carries
-it; only a context built by hand needs it.
-
-1. **Give a hand-built resource context an `admission`.** **Who must act:** a
-   project whose tests call a resource's phase directly with a context object
-   they wrote themselves (`resource.close?.({ applicationId, signal, … })`).
-   The type checker names each one:
-
-   ```ts
-   // before
-   await resource.close?.({ applicationId: 'test', signal, now, reportHealth, use })
-   // after
-   await resource.close?.({
-     applicationId: 'test',
-     signal,
-     now,
-     reportHealth,
-     use,
-     admission: { acquire: () => null, acquireWhenAccepting: () => new Promise(() => {}) },
-   })
-   ```
-
-   A test that needs real admission starts the resource inside
-   `createApplication` instead.
-
-2. **Nothing to do for grammY polling, but know what changed.** **Who must
-   act:** nobody. `grammyPollingResource` now admits updates by batch: it does
-   not fetch while the application is not accepting, and finishes the batch in
-   hand before `bot.stop()`. A project that wrote its own `getUpdates`
-   transformer for this (waiting on `app.admission` before returning a batch)
-   deletes it; keeping both waits twice and is harmless.

package/llms/upgrading.txt

@@ -11,10 +11,10 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.96.0 → 0.106.0: `llms/upgrading-0.96.0-0.106.0.txt`
-- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
-- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
-- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
+- 0.98.0 → 0.107.0: `llms/upgrading-0.98.0-0.107.0.txt`
+- 0.72.0 → 0.97.0: `llms/upgrading-0.72.0-0.97.0.txt`
+- 0.59.0 → 0.71.0: `llms/upgrading-0.59.0-0.71.0.txt`
+- 0.37.0 → 0.58.0: `llms/upgrading-0.37.0-0.58.0.txt`
 
 # Upgrading stitchkit
 

package/llms-full.txt

@@ -74,12 +74,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 51 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 52 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 51 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 52 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -91,7 +91,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 51 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 52 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -8412,13 +8412,15 @@ so a helper started in the background races the leader:
 
 | launched by the leader as | after the leader exits |
 |---|---|
-| `setsid -f helper` (returns once the new session exists) | survives |
+| `setsid -f helper` | usually survives: `setsid -f` forks and returns at once, and the child calls `setsid()` a moment later, so a leader that exits immediately can still catch it in the group (13 of 300 launches under CPU load) |
 | `setsid helper &`, `(setsid helper &)`, `nohup helper &` | stopped: the leader usually exits before the background job has left the group |
+| a launch the leader waits on until the helper reports it has left the group | survives |
 | any of these under `descendants: 'leave'` | survives |
 
-Start a daemon so that the session exists before the leader returns (`setsid -f`, or the
-daemon's own double fork followed by the leader waiting for it), or declare `'leave'`. Declare
-`'leave'` only for a helper that has to outlive the command while staying in its group:
+Start a daemon so that the leader waits for the session to exist before it returns: the helper
+writes its pid, or prints a line, only after its own `setsid()`, and the leader waits for that.
+Or declare `'leave'`. Declare `'leave'` only for a helper that has to outlive the command while
+staying in its group:
 
 ```ts
 await runNativeCommand({
@@ -8583,23 +8585,46 @@ version: carry their reachable relative `.d.ts` closure, rather than emitting re
 instead emit declarations for only that DTO contract. Keep the library's manifest at runtime
 `dependencies: {}` and `peerDependencies: { zod: ... }` when that is its declared promise.
 
-The packaged Darwin loader names its addons by a path computed at run time, so a bundler
-never follows it: bundling `stitchkit/server`, `stitchkit/files` or `stitchkit/process` yields
-the same single JS file on every operating system, with no `.node` output, and
-`bun build --outfile` works. Such a bundle looks for the addon beside the original package
-files, never inside itself. Where that file is absent (an artifact moved to another machine)
-the Darwin backend is `unavailable`: process identity cannot be recorded, so a lock held by a
-crashed owner is not reclaimed. An artifact that must carry the Darwin addon uses the packaging
-plugin of the next section; it is the only way a static loader enters a bundle.
+The packaged Darwin loader computes its addon path at run time from its own file
+(`module.filename`), so a bundler never follows it: bundling `stitchkit/server`,
+`stitchkit/files` or `stitchkit/process` yields the same single JS file on every operating
+system, with no `.node` output, `bun build --outfile` works, and no path of the build machine
+becomes a literal of the artifact. A bundle has no installed package beside it, so without the
+packaging plugin it never loads the addon: the first call that needs it reports the Darwin backend
+`unavailable` with stage `packaging`, and the message names `createNativePackaging`. An artifact
+that must carry the Darwin addon uses the packaging plugin of the next section; it is the only way
+a static loader enters a bundle.
+
+Only these calls load the addon, and only on macOS: process identity (`observeProcessInstance`
+and `probeProcessOwner`), every exclusive lock (`withExclusiveLock` and what is built on it, such
+as the file state store and the diagnostic journal) and the contained file operations of the Agent
+coding tools. Without the addon a lock still works, but it cannot record or check its owner's
+identity, so a lock held by a crashed owner is not reclaimed. The managed file boundary
+(`createManagedFileBoundary` and the transfer tools built on it), atomic writes and the chunk
+spool never load it, on any operating system. The package is free of import side effects
+(`sideEffects: false`), so a bundle that imports only those parts carries no Darwin loader at all.
+
+Check an artifact by its loader, never by whether it holds `.node` bytes: Bun can copy the addon
+into a compiled executable even without the plugin, and the unpackaged loader does not use it.
+Search the artifact for `STITCHKIT_NATIVE_NOT_PACKAGED` in both latin1 and UTF-16LE, because Bun
+stores source text with non-ASCII characters as UTF-16. Present: the unpackaged loader is inside,
+and every call above refuses on macOS. Absent in a plugin build: the static loader is inside
+(`/$bunfs/root/darwin-<arch>-<hash>.node` in an executable, the companion path in a JS build).
+Absent without the plugin: nothing in the artifact needs the addon.
 
 ```sh
 bun build src/native.ts --target=bun --minify --outfile=dist/native.js
 ```
 
+That plain build serves Linux and the parts that never load the addon. A library whose consumers
+take locks or read process identity on macOS builds each native entry with the companion plugin of
+the next section (one entry per build, `naming.entry` equal to `entryPath`) and ships the addon it
+writes beside the entries.
+
 Qualify the complete output outside its build tree and installed dependency graph. Test process
 identity, live-owner refusal, dead-owner recovery and contained file operations in artifacts built
 with the packaging plugin, and check that an unpackaged build reports the backend `unavailable`
-rather than certifying a dead owner. Bun and Node package imports retain the same
+with stage `packaging` rather than certifying a dead owner. Bun and Node package imports retain the same
 lazy loader; importing a portable leaf does not load a Darwin addon on another OS. Test
 declarations too, and check that importing an unbundled Stitchkit leaf fails in a deliberately
 isolated library distribution. A separate schema-only entry must not import the native entry.
@@ -8607,7 +8632,9 @@ isolated library distribution. A separate schema-only entry must not import the
 If the Darwin backend cannot load, `observeProcessInstance` still returns `unavailable`.
 Its backend `Error` preserves the original `cause`; JSON serialization carries only the stable
 `DARWIN_BACKEND_UNAVAILABLE` code, architecture, safe message and failure stage
-(`architecture`, `resolve`, `load` or `surface`), plus a recognized native error code when present.
+(`architecture`, `packaging`, `resolve`, `load` or `surface`), plus a recognized native error code
+when present: `packaging` is a bundle built without the packaging plugin, with native code
+`STITCHKIT_NATIVE_NOT_PACKAGED`.
 It excludes stack, paths and nested cause. This backend diagnosis does not reclassify kernel
 failures or turn unavailable identity into proof that an owner is dead. If a runtime provides
 no recognized native error code, the stage stays `load`; the loader never infers errno from text.
@@ -8654,7 +8681,7 @@ for (const asset of native.assets) {
 }
 ```
 
-`entryPath` and `assetPath` are relative paths inside the application's output root, without
+In companion delivery, `entryPath` and `assetPath` are relative paths inside the application's output root, without
 absolute paths, traversal or overlapping file/directory paths. `assetPath` may contain `[hash]`,
 which becomes the first 16 hex digits of that addon's published SHA256: the digest is known before
 the build, so `addons/darwin-arm64-[hash].node` gives two installed versions of the package
@@ -8693,10 +8720,27 @@ process primitives without loading Darwin assets. Qualify the exact same JS byte
 Darwin arm64 and x64 machines, with both companions preserved through archive delivery.
 Build-machine architecture and cross-build success cannot establish universal native support.
 
-For a standalone executable use `delivery: 'embedded'` and the same plugin in `Bun.build`
-with `compile: { outfile: ... }`. Bun embeds the selected addon from the verified bytes the
-plugin holds, not from a second read of the file; `assets` identifies those bytes and their
-published digest for qualification, not a companion that must be installed beside the executable.
+For a standalone executable use `delivery: 'embedded'` and its plugin in `Bun.build` with
+`compile`. An executable carries the addon inside itself, so this form names no `entryPath` or
+`assetPath`; passing one is a type error and a schema refusal, never silently ignored:
+
+```ts
+const native = createNativePackaging({
+  platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+})
+if (native.state !== 'ready') throw new Error(native.code)
+const result = await Bun.build({
+  entrypoints: ['src/cli.ts'], minify: true,
+  compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+  plugins: [native.plugin],
+})
+if (!result.success) throw new AggregateError(result.logs, 'Build failed')
+```
+
+Bun embeds the selected addon from the verified bytes the plugin holds, not from a second read of
+the file, and the executable loads it from `/$bunfs/root/darwin-arm64-<hash>.node`. Its `assets`
+(`NativePackagingEmbeddedAsset`: `bytes`, `size`, `sha256`) identify those bytes and their
+published digest for qualification; there is nothing to write beside the executable.
 Cross-builds must select the requested architecture explicitly; the artifact must run on that target.
 The installed package must contain that target's addon. No automatic fallback/downgrade occurs.
 
@@ -15578,6 +15622,38 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.107.0
+
+### embedded native packaging names no paths
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) with
+`delivery: 'embedded'`. Companion delivery is unchanged.
+
+A standalone executable carries the Darwin addon inside itself, so the embedded form takes only
+`platform`, `architecture` and `delivery`. `entryPath` and `assetPath` were required before but
+changed nothing in the executable; passing them now is a type error and a schema refusal. The
+ready result names the embedded addon by `NativePackagingEmbeddedAsset` (`bytes`, `size`,
+`sha256`), without `outputPath`, since nothing is written beside the executable.
+
+1. Drop the two paths from the embedded call:
+
+   ```ts
+   // before
+   createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+     entryPath: 'cli.js', assetPath: 'native/darwin-arm64.node',
+   })
+   // after
+   createNativePackaging({ platform: 'darwin', architecture: 'arm64', delivery: 'embedded' })
+   ```
+
+   Search pattern: `delivery: 'embedded'`.
+2. Code that read `asset.outputPath` from an embedded result reads `bytes`, `size` and `sha256`
+   only; an annotation `NativePackagingOptions` / `NativePackagingResult` on an embedded call
+   becomes `NativePackagingEmbeddedOptions` / `NativePackagingEmbeddedResult`.
+3. Rebuild every artifact made without the plugin by 0.105.0–0.106.1: it carries the build
+   machine's package path (see [Darwin native assets in JS distributions](#darwin-native-assets-in-js-distributions)).
+
 ## Released migration: 0.106.0
 
 ### a stopped leader settles as stopped
@@ -16178,13 +16254,27 @@ Custom output layout uses the evolving build-only packaging contract in the
 Three deliveries have different rules: an ordinary npm install retains the package's
 native assets; a JS distribution must ship its complete output graph; a Bun compiled
 executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
-`bun build` carries the addon without a plugin; later releases carry it only when the build
-uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a compiled
-executable).
-The [native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe.
-Check the resulting artifact offline outside the build tree and `node_modules`, including
-process identity, live-owner lock refusal, dead-owner recovery and contained IO.
-A missing or corrupt addon remains `unavailable`, never evidence that an owner died.
+`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
+the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
+compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
+executable, but the loader never uses them, so their presence proves nothing.
+
+What an unpackaged bundle does depends on the release:
+
+- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
+  because the loader read `__dirname`. It looks for the addon there, so it works only on that
+  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
+- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
+  addon reports the Darwin backend `unavailable` with stage `packaging`.
+
+Only macOS is affected, and only process identity (`observeProcessInstance`,
+`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
+managed file boundary, atomic writes and the chunk spool never do. The
+[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
+shows how to check an artifact by its loader without running it on a Mac. Check the resulting
+artifact offline outside the build tree and `node_modules`, including process identity,
+live-owner lock refusal, dead-owner recovery and contained IO. A missing or corrupt addon
+remains `unavailable`, never evidence that an owner died.
 
 ### CLI: repeated options are refused
 
@@ -22731,7 +22821,7 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`); `stdio` (`'pipe'`, or `'inherit'` for the caller's descriptors, refusing the pipe-only options) and `group` (`'own'`, or `'caller'`: joins the caller's process group, stops only the leader, refuses `descendants` and a group stop); `onLeaderStarted({ pid })` (once, after the leader exists), `drainTimeoutMs` (bound on the pipes staying open after the leader exited, `COMMAND_CLEANUP`); an unknown key is refused by name, a removed one (`killGraceMs`) with its replacement |
 | `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal, `descendantsStopped` (members left in the group after the leader exited were stopped) and captured stdout/stderr bytes |
-| `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
+| `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason; COMMAND_CLEANUP means the command's resources were not proven closed, either past `cleanupTimeoutMs` after a stop or past `drainTimeoutMs` after the leader exited, and `cause` holds that bound's failure. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
 
 | `NativeCommandSettlement` | type | `exit` (the leader ended on its own), `stopped` (the command was stopped and the leader's exit after the stop observed: the stop's `cause` with `exitCode`/`signal`) or `error` (no exit observed), including synchronous native launch failure; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal; schema/pre-abort refusal creates no settlement obligation |
 | `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
@@ -22741,13 +22831,16 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 ## `stitchkit/files/packaging`
 
 `stitchkit/files/packaging` owns `createNativePackaging` and the types
-`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
+`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`,
+and for a standalone executable `NativePackagingEmbeddedOptions`, `NativePackagingEmbeddedAsset`,
+`NativePackagingEmbeddedResult`.
 It resolves the installed package's target/version, reads each selected addon once and checks it
 against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
 written when Stitchkit is built). Call it once per build and reuse the result.
-`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
-`assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of the addon's
-published SHA256;
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are the explicit inputs of
+companion delivery; embedded delivery takes `platform`, one `architecture` and `delivery` only, and
+refuses a path. `assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of
+the addon's published SHA256;
 `platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
 The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
 `missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or
@@ -22764,7 +22857,8 @@ and the published `size` and `sha256`.
 Targets must be unique; entry and all asset paths must be disjoint. One lazy loader chooses only
 the actual runtime architecture, with no fallback.
 Companion mode places external addons relative to the emitted entry; embedded mode gives
-Bun compile the verified bytes of the matching addon. Keep JS builds without splitting, preserve
-every output, and write each asset's `bytes` to its `outputPath`.
+Bun compile the verified bytes of the matching addon, and its asset (`bytes`, `size`, `sha256`)
+has no `outputPath`, because nothing is written beside the executable. Keep companion JS builds
+without splitting, preserve every output, and write each asset's `bytes` to its `outputPath`.
 This evolving entrypoint is a build dependency; runtime imports do not reach it.
 The detailed recipe is in [native IO](../guide/native-io.md#public-native-packaging).

package/llms.txt

@@ -56,15 +56,15 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 39.4 KB
-- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 2.8 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 42.5 KB
+- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.2 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.96.0 → 0.106.0**: [llms/upgrading-0.96.0-0.106.0.txt](llms/upgrading-0.96.0-0.106.0.txt) 46.6 KB
-- **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
-- **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
-- **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
+- **Upgrading 0.98.0 → 0.107.0**: [llms/upgrading-0.98.0-0.107.0.txt](llms/upgrading-0.98.0-0.107.0.txt) 45.9 KB
+- **Upgrading 0.72.0 → 0.97.0**: [llms/upgrading-0.72.0-0.97.0.txt](llms/upgrading-0.72.0-0.97.0.txt) 43.8 KB
+- **Upgrading 0.59.0 → 0.71.0**: [llms/upgrading-0.59.0-0.71.0.txt](llms/upgrading-0.59.0-0.71.0.txt) 45.6 KB
+- **Upgrading 0.37.0 → 0.58.0**: [llms/upgrading-0.37.0-0.58.0.txt](llms/upgrading-0.37.0-0.58.0.txt) 40.0 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.106.0",
+  "version": "0.107.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -30,6 +30,7 @@
     "url": "https://github.com/max-listov/stitchkit/issues"
   },
   "type": "module",
+  "sideEffects": false,
   "engines": {
     "bun": ">=1.2.0",
     "node": ">=22"
@@ -265,10 +266,10 @@
     "build:unlocked": "rm -rf dist && cp ../../CHANGELOG.md ./CHANGELOG.md && bun run build:js && chmod +x dist/entrypoints/bin/upgrade-cli.js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-browser-executes.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs && bun scripts/check-durability-port-standalone.mjs && bun scripts/check-declarations-strict.mjs",
     "dev": "bun run build:entrypoints -- --watch",
     "prepack": "bun ../../scripts/sync-package-readme.ts && bun ../../scripts/gen-llms.ts && bun run build",
-    "test": "bun test",
+    "test": "bun ../../scripts/test-leak-gate.ts -- bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
     "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
-    "consumer-lane": "bun scripts/consumer-lane/run.mjs",
+    "consumer-lane": "bun ../../scripts/test-leak-gate.ts -- bun scripts/consumer-lane/run.mjs",
     "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts",
     "bench:durable-store": "bun scripts/bench-durable-store.ts",
     "build:entrypoints": "bun scripts/generate-native-assets.ts && bun scripts/build-entrypoints.mjs"

package/dist/{index-cazts87s.js → index-07dcf2yn.js}

@@ -1,12 +1,12 @@
-import {
-  stagingPath
-} from "./index-j4zh647a.js";
 import {
   closeAfter,
   closeAfterSync,
   publishAtomicFile,
   publishAtomicFileSync
 } from "./index-b56nnscm.js";
+import {
+  stagingPath
+} from "./index-j4zh647a.js";
 
 // src/internal/atomic-file.ts
 import { closeSync, fchmodSync, fsyncSync, openSync, unlinkSync, writeSync } from "node:fs";

package/dist/{index-n1nszyk0.js → index-7jvwrjqa.js}

@@ -1,10 +1,10 @@
+import {
+  ApiError2
+} from "./index-kfjkb396.js";
 import {
   createTraceContext2,
   formatTraceparent2
 } from "./index-yex7eg1v.js";
-import {
-  ApiError2
-} from "./index-kfjkb396.js";
 import {
   isRecord,
   transportResult

package/dist/{index-cmzvhhtd.js → index-85qve8mq.js}

@@ -1,9 +1,9 @@
-import {
-  AppError2
-} from "./index-j9gxbztg.js";
 import {
   contractMethodFields
 } from "./index-1bx1xv1k.js";
+import {
+  AppError2
+} from "./index-j9gxbztg.js";
 import {
   typedEntries,
   callRuntimeHandler

package/dist/{index-rpzewktb.js → index-fynr93w4.js}

@@ -1,10 +1,10 @@
-import {
-  AppError2
-} from "./index-j9gxbztg.js";
 import {
   zodIssues2,
   formatZodError2
 } from "./index-1eeqpadm.js";
+import {
+  AppError2
+} from "./index-j9gxbztg.js";
 import {
   isRecord
 } from "./index-9jfdm5tg.js";

package/dist/{index-37asdw3a.js → index-k7qdkh3n.js}

@@ -1,6 +1,3 @@
-import {
-  unauthorized2
-} from "./index-j9gxbztg.js";
 import {
   deriveCodeChallenge2
 } from "./index-ap3gqe56.js";
@@ -8,6 +5,9 @@ import {
   bytesToBase64Url,
   base64UrlToBytes
 } from "./index-dwfv9a85.js";
+import {
+  unauthorized2
+} from "./index-j9gxbztg.js";
 import {
   safeJsonParse
 } from "./index-zsarb5xp.js";

package/dist/{index-x7w1z6pf.js → index-q4hjtyye.js}

@@ -1,15 +1,15 @@
 import {
   defineContract2
 } from "./index-fsw1ybf3.js";
+import {
+  bytesToBase64Url,
+  base64UrlToBytes
+} from "./index-dwfv9a85.js";
 import {
   AppError2,
   STITCH_ERROR_STATUS2,
   isStitchErrorCode2
 } from "./index-j9gxbztg.js";
-import {
-  bytesToBase64Url,
-  base64UrlToBytes
-} from "./index-dwfv9a85.js";
 import {
   typedEntries,
   transportResult,

package/dist/{index-7n68nmc6.js → index-y3nemndz.js}

@@ -1,10 +1,10 @@
-import {
-  resolveTraceContext2
-} from "./index-yex7eg1v.js";
 import {
   resolveSocketIp2,
   getClientInfo2
 } from "./index-kw1ws0cs.js";
+import {
+  resolveTraceContext2
+} from "./index-yex7eg1v.js";
 import {
   isUnsafeKey
 } from "./index-zsarb5xp.js";

package/dist/{index-12zsej7b.js → index-y70v24cw.js}

@@ -1,6 +1,3 @@
-import {
-  AppError2
-} from "./index-j9gxbztg.js";
 import {
   ShutdownOptionsSchema2
 } from "./index-q0th8q0z.js";
@@ -12,6 +9,9 @@ import {
 import {
   managedResourceDependencyId2
 } from "./index-50ejfz75.js";
+import {
+  AppError2
+} from "./index-j9gxbztg.js";
 
 // src/application/kernel-contract.ts
 import { z } from "zod";