stitchkit 0.104.0 → 0.104.1

package/CHANGELOG.md

@@ -15,6 +15,21 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.104.1] - 2026-10-04
+
+### Added
+
+- `stitchkit/files/packaging` — evolving build-only `createNativePackaging` resolves the
+  installed target addon, original SHA256 and a Bun-compatible plugin for custom companion
+  placement or embedded standalone delivery. Runtime leaves keep the same native owner;
+  archives, signing and installation policy remain application-owned. → ADR 0233
+
+### Documentation
+
+- The JS native-asset delivery migration first affected in 0.103.13 is explicit in the
+  [upgrade guide](docs/guide/upgrading.md#released-migration-010313), including single-file
+  packaging, complete output graphs and the distinct npm/JS/compiled delivery paths.
+
 ## [0.104.0] - 2026-10-04
 
 ### ⚠️ Breaking changes
@@ -112,6 +127,16 @@ native CLI commands and ordinary one-argument state transitions remain valid.
 
 ## [0.103.13] - 2026-10-04
 
+### ⚠️ Delivery migration
+
+- `stitchkit/process`, `stitchkit/files` and contained-file tools in Bun JS distributions:
+  the static Darwin addon graph adds companion assets. This delivery change was published
+  as a patch, although packagers assuming one output must migrate:
+  `--outfile=dist/native.js` → `--outdir=dist --entry-naming=native.js` and retain all outputs.
+  Ordinary npm imports keep their package assets; Bun compiled executables embed them.
+  **Who must act:** custom JS packagers and installers, including single-archive delivery.
+  [Migration](docs/guide/upgrading.md#released-migration-010313).
+
 ### Fixed
 
 - Darwin native process and contained-file backends retain a static addon dependency through

package/darwin-native.cjs

@@ -1,7 +1,5 @@
-/** A lazy, statically discoverable addon edge shared by Node and Bun consumers. */
+/** Generated from the owning native asset graph. Loading remains lazy. */
 module.exports = function loadDarwinAddon() {
-  // The catch also keeps non-Darwin builds independent of unavailable slices.
-  // Bun compile selects its target architecture and embeds that literal addon.
   try {
     if (process.arch === 'arm64') return require('./native/darwin-arm64.node');
     if (process.arch === 'x64') return require('./native/darwin-x64.node');

package/dist/entrypoints/contract.js

@@ -4,7 +4,7 @@ import {
   paginatedSchema2,
   encodeCursor2,
   decodeCursor2
-} from "../index-22rhg58f.js";
+} from "../index-hp9d77wk.js";
 import {
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES2,
   ContractStreamFrameSchema2

package/dist/entrypoints/files/packaging.d.ts

@@ -0,0 +1,3 @@
+export type { NativePackagingAsset, NativePackagingOptions, NativePackagingPlugin, NativePackagingResult, } from '../../files/native-packaging.js';
+export { createNativePackaging } from '../../files/native-packaging.js';
+//# sourceMappingURL=packaging.d.ts.map

package/dist/entrypoints/files/packaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packaging.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/files/packaging.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/entrypoints/files/packaging.js

@@ -0,0 +1,133 @@
+// src/files/native-packaging.ts
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z as z2 } from "zod";
+
+// src/files/native-packaging-layout.ts
+import { z } from "zod";
+var PackagePathSchema = z.string().min(1).refine((value) => !value.startsWith("/") && !/^[a-z]:/i.test(value) && !value.includes("\\") && value.split("/").every((part) => part !== ".." && part !== "." && part.length > 0), "Expected a relative package path without traversal");
+var NativeLayoutSchema = z.object({
+  formatVersion: z.literal(1),
+  loader: PackagePathSchema,
+  assets: z.object({ arm64: PackagePathSchema, x64: PackagePathSchema })
+});
+function nativeLoaderSource(assets) {
+  const quote = (value) => `'${JSON.stringify(value).slice(1, -1).replaceAll("'", "\\'")}'`;
+  const branches = Object.entries(assets).map(([architecture, asset]) => `    if (process.arch === ${quote(architecture)}) return require(${quote(asset)});`);
+  return [
+    "/** Generated from the owning native asset graph. Loading remains lazy. */",
+    "module.exports = function loadDarwinAddon() {",
+    "  try {",
+    ...branches,
+    "    throw new Error('Unsupported Darwin addon architecture');",
+    "  } catch (cause) {",
+    "    throw new Error('Darwin addon loading failed', { cause });",
+    "  }",
+    "};",
+    ""
+  ].join(`
+`);
+}
+
+// src/files/native-packaging.ts
+var OutputPathSchema = z2.string().min(1).refine((value) => !value.startsWith("/") && !/^[a-z]:/i.test(value) && !value.includes("\\") && value.split("/").every((part) => part !== ".." && part !== "." && part.length > 0), "Expected a relative output path without traversal");
+var OptionsSchema = z2.object({
+  platform: z2.string().min(1),
+  architecture: z2.string().min(1),
+  delivery: z2.enum(["companion", "embedded"]),
+  entryPath: OutputPathSchema.refine((value) => !value.includes("[") && !value.includes("]"), "Expected a fixed entry path without Bun naming templates"),
+  assetPath: OutputPathSchema
+}).refine((input) => input.entryPath !== input.assetPath && !input.entryPath.startsWith(`${input.assetPath}/`) && !input.assetPath.startsWith(`${input.entryPath}/`), "Entry and addon must have non-overlapping paths");
+var AssetSchema = z2.object({
+  sourcePath: z2.string(),
+  outputPath: z2.string(),
+  sha256: z2.string().regex(/^[a-f0-9]{64}$/)
+});
+var RefusalSchema = z2.object({
+  state: z2.enum(["unsupported", "missing"]),
+  platform: z2.string(),
+  architecture: z2.string(),
+  code: z2.enum(["NATIVE_TARGET_UNSUPPORTED", "NATIVE_ASSET_MISSING"])
+});
+function installedPackageRoot() {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0;depth < 64; depth++) {
+    if (existsSync(resolve(directory, "native-assets.json")))
+      return directory;
+    const parent = dirname(directory);
+    if (parent === directory)
+      break;
+    directory = parent;
+  }
+  throw new Error("Native packaging must run from its installed Stitchkit package");
+}
+function createNativePackaging(options) {
+  const input = OptionsSchema.parse(options);
+  if (input.platform !== "darwin" || input.architecture !== "arm64" && input.architecture !== "x64") {
+    return {
+      state: "unsupported",
+      platform: input.platform,
+      architecture: input.architecture,
+      code: "NATIVE_TARGET_UNSUPPORTED"
+    };
+  }
+  const root = installedPackageRoot();
+  const layout = NativeLayoutSchema.parse(JSON.parse(readFileSync(resolve(root, "native-assets.json"), "utf8")));
+  const manifest = z2.object({ name: z2.literal("stitchkit"), version: z2.string().min(1) }).parse(JSON.parse(readFileSync(resolve(root, "package.json"), "utf8")));
+  const loaderPath = resolve(root, layout.loader);
+  const sourcePath = resolve(root, layout.assets[input.architecture]);
+  let bytes;
+  try {
+    bytes = readFileSync(sourcePath);
+  } catch (cause) {
+    if (cause instanceof Error && "code" in cause && cause.code === "ENOENT") {
+      return {
+        state: "missing",
+        platform: input.platform,
+        architecture: input.architecture,
+        code: "NATIVE_ASSET_MISSING"
+      };
+    }
+    throw cause;
+  }
+  const outputSpecifier = relative(dirname(input.entryPath), input.assetPath).split("\\").join("/");
+  const specifier = input.delivery === "embedded" ? sourcePath : outputSpecifier.startsWith(".") ? outputSpecifier : `./${outputSpecifier}`;
+  const contents = nativeLoaderSource({ [input.architecture]: specifier });
+  return {
+    state: "ready",
+    platform: "darwin",
+    architecture: input.architecture,
+    packageVersion: manifest.version,
+    assets: [
+      {
+        sourcePath,
+        outputPath: input.assetPath,
+        sha256: createHash("sha256").update(bytes).digest("hex")
+      }
+    ],
+    plugin: {
+      name: "stitchkit-native-packaging",
+      setup(build) {
+        if (input.delivery === "companion") {
+          if (build.config.entrypoints.length !== 1)
+            throw new Error("Native companion packaging requires exactly one entrypoint");
+          if (build.config.splitting)
+            throw new Error("Native companion packaging requires splitting: false");
+          const naming = build.config.naming;
+          const entry = typeof naming === "string" ? naming : naming?.entry;
+          if (entry !== input.entryPath)
+            throw new Error("Native companion packaging naming.entry must match entryPath");
+        }
+        build.onLoad({ filter: /\.[cm]?js$/ }, (args) => args.path === loaderPath ? { contents, loader: "js" } : undefined);
+        if (input.delivery === "companion") {
+          build.onResolve({ filter: /./ }, (args) => args.importer === loaderPath && args.path === specifier ? { path: specifier, external: true } : undefined);
+        }
+      }
+    }
+  };
+}
+export {
+  createNativePackaging
+};

package/dist/entrypoints/index.js

@@ -80,7 +80,7 @@ import {
   paginatedSchema2,
   encodeCursor2,
   decodeCursor2
-} from "../index-22rhg58f.js";
+} from "../index-hp9d77wk.js";
 import {
   ManagedFilePathSchema2,
   ManagedFileRefSchema2

package/dist/entrypoints/node.js

@@ -33,7 +33,7 @@ import"../index-1bx1xv1k.js";
 import"../index-43p08g7t.js";
 import"../index-4s0fep5q.js";
 import"../index-ck71tbcf.js";
-import"../index-22rhg58f.js";
+import"../index-hp9d77wk.js";
 import"../index-xqhede6x.js";
 import {
   bindRealtimeServer2

package/dist/entrypoints/server.js

@@ -61,7 +61,7 @@ import {
 import"../index-43p08g7t.js";
 import"../index-4s0fep5q.js";
 import"../index-ck71tbcf.js";
-import"../index-22rhg58f.js";
+import"../index-hp9d77wk.js";
 import"../index-xqhede6x.js";
 import {
   createFileStateStore2
@@ -81,9 +81,6 @@ import {
   signJwt2,
   verifyPkce2
 } from "../index-wh0ecvyk.js";
-import {
-  deriveCodeChallenge2
-} from "../index-ap3gqe56.js";
 import {
   defineMultipartStream2,
   createMultipartStream2,
@@ -91,6 +88,9 @@ import {
   createImplement2,
   createScopedImplement2
 } from "../index-g2j7pnak.js";
+import {
+  deriveCodeChallenge2
+} from "../index-ap3gqe56.js";
 import {
   isWithinDir2,
   realPathWithinDir

package/dist/files/native-packaging-layout.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const NativeLayoutSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<1>;
+    loader: z.ZodString;
+    assets: z.ZodObject<{
+        arm64: z.ZodString;
+        x64: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** One lazy loader for package, companion and embedded delivery. */
+export declare function nativeLoaderSource(assets: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=native-packaging-layout.d.ts.map

package/dist/files/native-packaging-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-packaging-layout.d.ts","sourceRoot":"","sources":["../../src/files/native-packaging-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,eAAO,MAAM,kBAAkB;;;;;;;iBAI7B,CAAC;AAEH,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAmBnF"}

package/dist/files/native-packaging.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+declare const OptionsSchema: z.ZodObject<{
+    platform: z.ZodString;
+    architecture: z.ZodString;
+    delivery: z.ZodEnum<{
+        companion: "companion";
+        embedded: "embedded";
+    }>;
+    entryPath: z.ZodString;
+    assetPath: z.ZodString;
+}, z.core.$strip>;
+declare const AssetSchema: z.ZodObject<{
+    sourcePath: z.ZodString;
+    outputPath: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strip>;
+declare const RefusalSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        missing: "missing";
+        unsupported: "unsupported";
+    }>;
+    platform: z.ZodString;
+    architecture: z.ZodString;
+    code: z.ZodEnum<{
+        NATIVE_ASSET_MISSING: "NATIVE_ASSET_MISSING";
+        NATIVE_TARGET_UNSUPPORTED: "NATIVE_TARGET_UNSUPPORTED";
+    }>;
+}, z.core.$strip>;
+export type NativePackagingOptions = z.input<typeof OptionsSchema>;
+export type NativePackagingAsset = z.infer<typeof AssetSchema>;
+/** Structural Bun plugin protocol: declarations need no Bun runtime or ambient types. */
+export type NativePackagingPlugin = {
+    name: string;
+    setup: (build: {
+        config: {
+            splitting?: boolean;
+            naming?: string | {
+                entry?: string;
+            };
+            entrypoints: string[];
+        };
+        onLoad: (options: {
+            filter: RegExp;
+        }, callback: (args: {
+            path: string;
+        }) => {
+            contents: string;
+            loader: 'js';
+        } | undefined) => unknown;
+        onResolve: (options: {
+            filter: RegExp;
+        }, callback: (args: {
+            path: string;
+            importer: string;
+        }) => {
+            path: string;
+            external: boolean;
+        } | undefined) => unknown;
+    }) => void;
+};
+export type NativePackagingResult = z.infer<typeof RefusalSchema> | {
+    state: 'ready';
+    platform: 'darwin';
+    architecture: 'arm64' | 'x64';
+    packageVersion: string;
+    assets: NativePackagingAsset[];
+    plugin: NativePackagingPlugin;
+};
+/** Resolve this installed package's asset graph, without parsing downstream loader text. */
+export declare function createNativePackaging(options: NativePackagingOptions): NativePackagingResult;
+export {};
+//# sourceMappingURL=native-packaging.d.ts.map

package/dist/files/native-packaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-packaging.d.ts","sourceRoot":"","sources":["../../src/files/native-packaging.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAcxB,QAAA,MAAM,aAAa;;;;;;;;;iBAiBhB,CAAC;AACJ,QAAA,MAAM,WAAW;;;;iBAIf,CAAC;AACH,QAAA,MAAM,aAAa;;;;;;;;;;;iBAKjB,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AACnE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAE/D,yFAAyF;AACzF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,CAAC,KAAK,EAAE;QACb,MAAM,EAAE;YACN,SAAS,CAAC,EAAE,OAAO,CAAC;YACpB,MAAM,CAAC,EAAE,MAAM,GAAG;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC;YACrC,WAAW,EAAE,MAAM,EAAE,CAAC;SACvB,CAAC;QACF,MAAM,EAAE,CACN,OAAO,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,EAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,IAAI,CAAA;SAAE,GAAG,SAAS,KACjF,OAAO,CAAC;QACb,SAAS,EAAE,CACT,OAAO,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,EAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE;YACf,IAAI,EAAE,MAAM,CAAC;YACb,QAAQ,EAAE,MAAM,CAAC;SAClB,KAAK;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,OAAO,CAAA;SAAE,GAAG,SAAS,KAClD,OAAO,CAAC;KACd,KAAK,IAAI,CAAC;CACZ,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAC7B,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,GAC7B;IACE,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,YAAY,EAAE,OAAO,GAAG,KAAK,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,MAAM,EAAE,qBAAqB,CAAC;CAC/B,CAAC;AAaN,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAoF5F"}

package/llms/files-packaging.txt

@@ -0,0 +1,27 @@
+# stitchkit/files/packaging — 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: API reference: `stitchkit/files/packaging`  (docs/api/reference.md)
+
+Also read:
+- see `llms/process.txt` for the Native IO guide
+
+==============================================================================
+# API reference: `stitchkit/files/packaging`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/files/packaging`
+
+`stitchkit/files/packaging` owns `createNativePackaging` and the types
+`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
+It resolves the installed package's target/version and original addon SHA256.
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs.
+The result is `ready` with assets and a structural Bun plugin, or `unsupported`/`missing` with a safe code.
+Malformed options/metadata and other filesystem errors fail rather than masquerade as missing.
+Companion mode places an external addon relative to the emitted entry; embedded mode lets
+Bun compile retain the matching addon. Keep JS builds without splitting, preserve every output,
+and copy each original asset to its `outputPath` after verifying `sha256`.
+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/process.txt

@@ -15,7 +15,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-04 09:40 +07:00
+updated: 2026-10-04 20:04 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -293,6 +293,68 @@ no recognized native error code, the stage stays `load`; the loader never infers
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.
 
+## Public native packaging
+
+Custom archives and installers use `stitchkit/files/packaging` at **build time**.
+`createNativePackaging` resolves the installed version and target addon with its original SHA256;
+its Bun-compatible plugin integrates that asset with the same lazy native loader.
+The leaf is evolving. It requires no optional peer or Bun ambient declarations for Node imports.
+It must run unbundled from its installed package, never from an application's runtime artifact.
+This contract is available from 0.104.1; versions 0.103.13–0.104.0 use the complete-output recipe
+in the previous section.
+
+```ts
+import { createNativePackaging } from 'stitchkit/files/packaging'
+import { createHash } from 'node:crypto'
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const native = createNativePackaging({
+  platform: 'darwin', architecture: 'arm64', delivery: 'companion',
+  entryPath: 'app/native.js', assetPath: 'addons/owner.node',
+})
+if (native.state !== 'ready') throw new Error(native.code)
+const result = await Bun.build({
+  entrypoints: ['src/native.ts'], target: 'node', format: 'esm',
+  outdir: 'dist', naming: { entry: 'app/native.js' }, splitting: false,
+  plugins: [native.plugin],
+})
+if (!result.success) throw new AggregateError(result.logs, 'Build failed')
+// Preserve every result.outputs file under dist, then add the selected companion.
+for (const asset of native.assets) {
+  const bytes = readFileSync(asset.sourcePath)
+  if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256)
+    throw new Error('Native asset changed during build')
+  const destination = join('dist', asset.outputPath)
+  mkdirSync(dirname(destination), { recursive: true })
+  copyFileSync(asset.sourcePath, destination)
+}
+```
+
+`entryPath` and `assetPath` are relative paths inside the application's output root, without
+absolute paths, traversal or overlapping file/directory paths. `entryPath` is fixed, without
+Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
+and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
+Choose any application layout; the framework does not prescribe an app directory or installer.
+Keep every bundler output, then verify copied addon bytes against the original SHA256.
+Archive the complete output directory with an integrity manifest, unpack to a clean directory,
+verify the same hashes there, and run offline without the build tree or `node_modules`.
+A digest provides integrity, not authenticity: signature and trust policy remain application-owned.
+
+For a standalone executable use `delivery: 'embedded'` and the same plugin in `Bun.build`
+with `compile: { outfile: ... }`. Bun embeds the selected addon; `assets` identifies its
+original bytes for qualification, not a companion that must be installed 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.
+
+The API returns `unsupported` / `NATIVE_TARGET_UNSUPPORTED` for non-Darwin or unsupported
+architectures, and `missing` / `NATIVE_ASSET_MISSING` for a missing addon. Portable Linux libraries
+use their normal build, without a Darwin plugin; merely importing the build leaf loads no addon.
+Malformed inputs, unsupported metadata versions and other IO errors throw before packaging.
+Runtime missing/corrupt companions preserve the native `unavailable` result and safe stage/code
+from the existing observer; they never certify a dead owner. Preserve the raw cause internally.
+The plugin does not parse consumer JS or establish a second runtime native implementation.
+
 ## Qualification boundaries
 
 Native command cleanup owns the child before launch subscriptions are installed. Setup

package/llms/stitchkit.txt

@@ -70,6 +70,7 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
+| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |

package/llms/{upgrading-0.62.0-0.79.0.txt → upgrading-0.62.0-0.80.0.txt}

@@ -1,14 +1,60 @@
-# Upgrading 0.62.0 → 0.79.0 — stitchkit docs slice
+# Upgrading 0.62.0 → 0.80.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.62.0 → 0.79.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.62.0 → 0.80.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.62.0 → 0.79.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.62.0 → 0.80.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.80.0
+
+One thing, and only if you parse an async-operation snapshot.
+
+```bash
+rg -n "createAsyncOperationSnapshotSchema"
+```
+
+`progress` on a parsed snapshot used to be `unknown`. The factory built its
+object shapes with a conditional spread, and the narrowing inside it widened
+your schema back to a bare `ZodType`, so the emitted declaration threw the type
+argument away. It is now the output of the schema you configured.
+
+```ts
+const schema = createAsyncOperationSnapshotSchema({
+  progress: z.object({ done: z.number(), total: z.number() }),
+  failure: z.object({ code: z.string() }),
+})
+const snap = schema.parse(body)
+if (snap.phase === 'running') {
+  // before: `snap.progress` was `unknown` — this needed a cast or a narrow
+  // after:  it is `{ done: number; total: number } | undefined`
+  console.log(snap.progress?.done)
+}
+```
+
+**If you cast it**, delete the cast — it was working around the erased type.
+**If you assigned something else to it**, the compiler now refuses, and it was
+already a value the schema rejected at run time.
+
+**If you pass explicit type arguments**, the no-progress form takes one now, not
+two: the factory is two overloads. Pass none.
+
+```ts
+// before: createAsyncOperationSnapshotSchema<undefined, typeof Failure>({ failure: Failure })
+// after:  createAsyncOperationSnapshotSchema({ failure: Failure })
+```
+
+Nothing about parsing moves. A snapshot configured without `progress` still
+strips an unexpected `progress` rather than refusing it — that behaviour is why
+this is overloads and not one normalised key.
+
+**If you compile with `skipLibCheck: false`**, this is also the release that
+makes `stitchkit/tools/contract` compile at all: it carried five `TS2344`
+errors, one per phase, from the same conditional spread.
+
 ## Released migration: 0.79.0
 
 One thing, and only if you assert on the whole snapshot.

package/llms/{upgrading-0.80.0-0.104.0.txt → upgrading-0.81.0-0.104.0.txt}

@@ -1,16 +1,20 @@
-# Upgrading 0.80.0 → 0.104.0 — stitchkit docs slice
+# Upgrading 0.81.0 → 0.104.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.80.0 → 0.104.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.81.0 → 0.104.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.80.0 → 0.104.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.81.0 → 0.104.0  (docs/guide/upgrading.md)
 ==============================================================================
 
 ## Released migration: 0.104.0
 
+JS bundles carrying Darwin native capabilities also need the
+[delivery migration first affected in 0.103.13](#released-migration-010313).
+Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
+
 ### CLI runtime-tool construction
 
 **Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
@@ -126,6 +130,36 @@ signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ct
 an origin ignoring cancellation or an external provider stopped; keep resource leases until
 that work actually completes.
 
+## Released migration: 0.103.13
+
+### Darwin native assets in JS distributions
+
+**Who must act:** Bun JS builds using `--outfile`, copying only `outputs[0]`, custom
+single-file/archive packagers and installers delivering native process/files capabilities.
+First affected publication: **0.103.13**. It shipped as a patch; its changed delivery graph
+requires this migration despite unchanged API signatures.
+
+```sh
+# Before: one JS file was assumed to be the entire distribution.
+bun build src/native.ts --target=bun --outfile=dist/native.js
+# After: retain every output, with its relative path.
+bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
+```
+
+For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
+A single-file JS distribution cannot embed a native `.node` addon automatically.
+An archive may contain JS plus companion assets, materialized together before execution.
+Custom output layout uses the evolving build-only packaging contract in the
+[native IO guide](native-io.md#public-native-packaging).
+
+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`.
+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.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -1018,49 +1052,3 @@ compile error instead of building a URL with an unresolved segment. Measured
 across three consuming applications before release (373 endpoints with path
 segments), no explicit schema missed a field: the migration is deleting
 schemas that only repeated the path, or nothing.
-
-## Released migration: 0.80.0
-
-One thing, and only if you parse an async-operation snapshot.
-
-```bash
-rg -n "createAsyncOperationSnapshotSchema"
-```
-
-`progress` on a parsed snapshot used to be `unknown`. The factory built its
-object shapes with a conditional spread, and the narrowing inside it widened
-your schema back to a bare `ZodType`, so the emitted declaration threw the type
-argument away. It is now the output of the schema you configured.
-
-```ts
-const schema = createAsyncOperationSnapshotSchema({
-  progress: z.object({ done: z.number(), total: z.number() }),
-  failure: z.object({ code: z.string() }),
-})
-const snap = schema.parse(body)
-if (snap.phase === 'running') {
-  // before: `snap.progress` was `unknown` — this needed a cast or a narrow
-  // after:  it is `{ done: number; total: number } | undefined`
-  console.log(snap.progress?.done)
-}
-```
-
-**If you cast it**, delete the cast — it was working around the erased type.
-**If you assigned something else to it**, the compiler now refuses, and it was
-already a value the schema rejected at run time.
-
-**If you pass explicit type arguments**, the no-progress form takes one now, not
-two: the factory is two overloads. Pass none.
-
-```ts
-// before: createAsyncOperationSnapshotSchema<undefined, typeof Failure>({ failure: Failure })
-// after:  createAsyncOperationSnapshotSchema({ failure: Failure })
-```
-
-Nothing about parsing moves. A snapshot configured without `progress` still
-strips an unexpected `progress` rather than refusing it — that behaviour is why
-this is overloads and not one normalised key.
-
-**If you compile with `skipLibCheck: false`**, this is also the release that
-makes `stitchkit/tools/contract` compile at all: it carried five `TS2344`
-errors, one per phase, from the same conditional spread.

package/llms/upgrading.txt

@@ -11,8 +11,8 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.80.0 → 0.104.0: `llms/upgrading-0.80.0-0.104.0.txt`
-- 0.62.0 → 0.79.0: `llms/upgrading-0.62.0-0.79.0.txt`
+- 0.81.0 → 0.104.0: `llms/upgrading-0.81.0-0.104.0.txt`
+- 0.62.0 → 0.80.0: `llms/upgrading-0.62.0-0.80.0.txt`
 - 0.44.0 → 0.61.0: `llms/upgrading-0.44.0-0.61.0.txt`
 - 0.37.0 → 0.44.0: `llms/upgrading-0.37.0-0.44.0.txt`
 

package/llms-full.txt

@@ -61,6 +61,7 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
+| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
@@ -8130,7 +8131,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-04 09:40 +07:00
+updated: 2026-10-04 20:04 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -8408,6 +8409,68 @@ no recognized native error code, the stage stays `load`; the loader never infers
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.
 
+## Public native packaging
+
+Custom archives and installers use `stitchkit/files/packaging` at **build time**.
+`createNativePackaging` resolves the installed version and target addon with its original SHA256;
+its Bun-compatible plugin integrates that asset with the same lazy native loader.
+The leaf is evolving. It requires no optional peer or Bun ambient declarations for Node imports.
+It must run unbundled from its installed package, never from an application's runtime artifact.
+This contract is available from 0.104.1; versions 0.103.13–0.104.0 use the complete-output recipe
+in the previous section.
+
+```ts
+import { createNativePackaging } from 'stitchkit/files/packaging'
+import { createHash } from 'node:crypto'
+import { copyFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const native = createNativePackaging({
+  platform: 'darwin', architecture: 'arm64', delivery: 'companion',
+  entryPath: 'app/native.js', assetPath: 'addons/owner.node',
+})
+if (native.state !== 'ready') throw new Error(native.code)
+const result = await Bun.build({
+  entrypoints: ['src/native.ts'], target: 'node', format: 'esm',
+  outdir: 'dist', naming: { entry: 'app/native.js' }, splitting: false,
+  plugins: [native.plugin],
+})
+if (!result.success) throw new AggregateError(result.logs, 'Build failed')
+// Preserve every result.outputs file under dist, then add the selected companion.
+for (const asset of native.assets) {
+  const bytes = readFileSync(asset.sourcePath)
+  if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256)
+    throw new Error('Native asset changed during build')
+  const destination = join('dist', asset.outputPath)
+  mkdirSync(dirname(destination), { recursive: true })
+  copyFileSync(asset.sourcePath, destination)
+}
+```
+
+`entryPath` and `assetPath` are relative paths inside the application's output root, without
+absolute paths, traversal or overlapping file/directory paths. `entryPath` is fixed, without
+Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
+and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
+Choose any application layout; the framework does not prescribe an app directory or installer.
+Keep every bundler output, then verify copied addon bytes against the original SHA256.
+Archive the complete output directory with an integrity manifest, unpack to a clean directory,
+verify the same hashes there, and run offline without the build tree or `node_modules`.
+A digest provides integrity, not authenticity: signature and trust policy remain application-owned.
+
+For a standalone executable use `delivery: 'embedded'` and the same plugin in `Bun.build`
+with `compile: { outfile: ... }`. Bun embeds the selected addon; `assets` identifies its
+original bytes for qualification, not a companion that must be installed 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.
+
+The API returns `unsupported` / `NATIVE_TARGET_UNSUPPORTED` for non-Darwin or unsupported
+architectures, and `missing` / `NATIVE_ASSET_MISSING` for a missing addon. Portable Linux libraries
+use their normal build, without a Darwin plugin; merely importing the build leaf loads no addon.
+Malformed inputs, unsupported metadata versions and other IO errors throw before packaging.
+Runtime missing/corrupt companions preserve the native `unavailable` result and safe stage/code
+from the existing observer; they never certify a dead owner. Preserve the raw cause internally.
+The plugin does not parse consumer JS or establish a second runtime native implementation.
+
 ## Qualification boundaries
 
 Native command cleanup owns the child before launch subscriptions are installed. Setup
@@ -15258,6 +15321,10 @@ analytics policy belong to the application.
 
 ## Released migration: 0.104.0
 
+JS bundles carrying Darwin native capabilities also need the
+[delivery migration first affected in 0.103.13](#released-migration-010313).
+Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
+
 ### CLI runtime-tool construction
 
 **Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
@@ -15373,6 +15440,36 @@ signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ct
 an origin ignoring cancellation or an external provider stopped; keep resource leases until
 that work actually completes.
 
+## Released migration: 0.103.13
+
+### Darwin native assets in JS distributions
+
+**Who must act:** Bun JS builds using `--outfile`, copying only `outputs[0]`, custom
+single-file/archive packagers and installers delivering native process/files capabilities.
+First affected publication: **0.103.13**. It shipped as a patch; its changed delivery graph
+requires this migration despite unchanged API signatures.
+
+```sh
+# Before: one JS file was assumed to be the entire distribution.
+bun build src/native.ts --target=bun --outfile=dist/native.js
+# After: retain every output, with its relative path.
+bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
+```
+
+For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
+A single-file JS distribution cannot embed a native `.node` addon automatically.
+An archive may contain JS plus companion assets, materialized together before execution.
+Custom output layout uses the evolving build-only packaging contract in the
+[native IO guide](native-io.md#public-native-packaging).
+
+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`.
+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.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -21887,3 +21984,17 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | `observeProcessInstance` / `ProcessInstanceObservation` | function / type | Linux/Darwin lifetime observation; observed identity or unavailable with its original cause, never guessed absence |
 | `ProcessInstanceSchema` / `ProcessInstance` | schema / type | platform, boot ID, namespace and process start identity from the shared native reader |
 | `probeProcessOwner` / `ProcessOwnerEvidence` | function / type | compare lifetimes on one caller-established machine; matched, boot change, reused PID, gone, legacy or unavailable with cause |
+
+## `stitchkit/files/packaging`
+
+`stitchkit/files/packaging` owns `createNativePackaging` and the types
+`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
+It resolves the installed package's target/version and original addon SHA256.
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs.
+The result is `ready` with assets and a structural Bun plugin, or `unsupported`/`missing` with a safe code.
+Malformed options/metadata and other filesystem errors fail rather than masquerade as missing.
+Companion mode places an external addon relative to the emitted entry; embedded mode lets
+Bun compile retain the matching addon. Keep JS builds without splitting, preserve every output,
+and copy each original asset to its `outputPath` after verifying `sha256`.
+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

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 17.4 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 46.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 17.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 46.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
@@ -56,12 +56,13 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **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) 1.8 KB
 - **stitchkit/agent-runtime/harness-tools**: [llms/agent-runtime-harness-tools.txt](llms/agent-runtime-harness-tools.txt) 1.3 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 21.7 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 25.4 KB
+- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 1.5 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.80.0 → 0.104.0**: [llms/upgrading-0.80.0-0.104.0.txt](llms/upgrading-0.80.0-0.104.0.txt) 46.7 KB
-- **Upgrading 0.62.0 → 0.79.0**: [llms/upgrading-0.62.0-0.79.0.txt](llms/upgrading-0.62.0-0.79.0.txt) 43.7 KB
+- **Upgrading 0.81.0 → 0.104.0**: [llms/upgrading-0.81.0-0.104.0.txt](llms/upgrading-0.81.0-0.104.0.txt) 46.8 KB
+- **Upgrading 0.62.0 → 0.80.0**: [llms/upgrading-0.62.0-0.80.0.txt](llms/upgrading-0.62.0-0.80.0.txt) 45.4 KB
 - **Upgrading 0.44.0 → 0.61.0**: [llms/upgrading-0.44.0-0.61.0.txt](llms/upgrading-0.44.0-0.61.0.txt) 41.4 KB
 - **Upgrading 0.37.0 → 0.44.0**: [llms/upgrading-0.37.0-0.44.0.txt](llms/upgrading-0.37.0-0.44.0.txt) 14.7 KB
 

package/native-assets.json

@@ -0,0 +1,8 @@
+{
+  "formatVersion": 1,
+  "loader": "darwin-native.cjs",
+  "assets": {
+    "arm64": "native/darwin-arm64.node",
+    "x64": "native/darwin-x64.node"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.104.0",
+  "version": "0.104.1",
   "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",
@@ -49,7 +49,8 @@
     "llms",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "native-assets.json"
   ],
   "imports": {
     "#stitchkit-darwin-native": "./darwin-native.cjs"
@@ -246,6 +247,10 @@
     "./process": {
       "types": "./dist/entrypoints/process.d.ts",
       "import": "./dist/entrypoints/process.js"
+    },
+    "./files/packaging": {
+      "types": "./dist/entrypoints/files/packaging.d.ts",
+      "import": "./dist/entrypoints/files/packaging.js"
     }
   },
   "publishConfig": {
@@ -266,7 +271,7 @@
     "consumer-lane": "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/build-entrypoints.mjs"
+    "build:entrypoints": "bun scripts/generate-native-loader.ts && bun scripts/build-entrypoints.mjs"
   },
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2 || ^2.0.0",