stitchkit 0.103.8 → 0.103.9

package/dist/process/contract.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export declare const NativeCommandOptionsSchema: z.ZodObject<{
+    executable: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    envPolicy: z.ZodDefault<z.ZodEnum<{
+        ambient: "ambient";
+        "declared-only": "declared-only";
+    }>>;
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxOutputBytes: z.ZodOptional<z.ZodNumber>;
+    capture: z.ZodDefault<z.ZodBoolean>;
+    stdin: z.ZodOptional<z.ZodCustom<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>>;
+    maxStdinBytes: z.ZodDefault<z.ZodNumber>;
+    onOutput: z.ZodOptional<z.ZodCustom<(bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>, (bytes: Uint8Array, channel: 'stdout' | 'stderr', signal: AbortSignal) => void | Promise<void>>>;
+    killGraceMs: z.ZodDefault<z.ZodNumber>;
+    cleanupTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type NativeCommandOptions = z.input<typeof NativeCommandOptionsSchema>;
+export type ParsedNativeCommandOptions = z.output<typeof NativeCommandOptionsSchema>;
+declare const NativeCommandResultSchema: z.ZodObject<{
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    signal: z.ZodNullable<z.ZodString>;
+    stdout: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+    stderr: z.ZodInstanceOf<Uint8Array<ArrayBuffer>>;
+}, z.core.$strip>;
+export type NativeCommandResult = z.infer<typeof NativeCommandResultSchema>;
+export declare class NativeCommandError extends Error {
+    readonly code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP';
+    constructor(code: 'COMMAND_LIMIT' | 'COMMAND_UNAVAILABLE' | 'COMMAND_CLEANUP', message: string, options?: ErrorOptions);
+}
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/process/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/process/contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;gDAoBtB,UAAU,WACR,QAAQ,GAAG,QAAQ,UACpB,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;;;kBAgB7B,CAAC;AACL,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AACrF,QAAA,MAAM,yBAAyB;;;;;iBAK7B,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,qBAAa,kBAAmB,SAAQ,KAAK;aAEzB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB;IADnF,YACkB,IAAI,EAAE,eAAe,GAAG,qBAAqB,GAAG,iBAAiB,EACjF,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF"}

package/dist/process/group.d.ts

@@ -0,0 +1,6 @@
+import { NativeCommandError } from './contract.js';
+export declare function signalGroup(pid: number | undefined, signal: NodeJS.Signals): void;
+export declare function stopCommandGroup(pid: number | undefined, graceMs: number): Promise<void>;
+export declare function commandCleanupError(cause: unknown): NativeCommandError;
+export declare function waitForCommandClose<T>(closed: Promise<T>, timeoutMs: number): Promise<T>;
+//# sourceMappingURL=group.d.ts.map

package/dist/process/group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAOjF;AAYD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAExF"}

package/dist/tools/transfer/managed-file-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"managed-file-error.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/managed-file-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuB,MAAM,uBAAuB,CAAC;AAgBtE,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAkBnE;AAED,kGAAkG;AAClG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAE/D"}
+{"version":3,"file":"managed-file-error.d.ts","sourceRoot":"","sources":["../../../src/tools/transfer/managed-file-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuB,MAAM,uBAAuB,CAAC;AAmBtE,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAyBnE;AAED,kGAAkG;AAClG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAE/D"}

package/llms/files.txt

@@ -5,6 +5,9 @@
 
 Contains: API reference: `stitchkit/files`  (docs/api/reference.md)
 
+Also read:
+- see `llms/process.txt` for the Native IO guide
+
 ==============================================================================
 # API reference: `stitchkit/files`  (docs/api/reference.md)
 ==============================================================================
@@ -35,3 +38,8 @@ available from `stitchkit/contract`.
 | `CHUNK_SPOOL_ERROR_CODES` / `isChunkSpoolErrorCode` | const / function | every `ChunkSpoolErrorCode` as a frozen list, and the guard for one — map them onto the app's own error codes, or a spool refusal reaches its client as an unknown 500 |
 
 ---
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `AtomicFilePublicationError` | class | published=true with cleanup/directory-sync/directory-close phase |
+| `FileObservation` | type | observed descriptor dev/ino/size/nlink/mtimeMs/ctimeMs |

package/llms/primitives.txt

@@ -15,7 +15,7 @@ description: Declare lifecycle, access, exact values, audit, delivery and export
 type: guide
 status: active
 created: 2026-09-01
-updated: 2026-09-01
+updated: 2026-10-01 21:03 +07:00
 ---
 
 # Generic application primitives
@@ -108,6 +108,31 @@ of the application's existing async operation. The input, scope, metadata and to
 change. The application creates bytes and owns operation persistence; the managed-file boundary
 streams them.
 
+## Canonical JSON
+
+```ts
+import { canonicalJson } from 'stitchkit/primitives'
+
+const bytes = canonicalJson({ '2': 'two', '10': 'ten', optional: undefined, nested: [1, null] }, {
+  maxDepth: 20, maxNodes: 10_000, maxBytes: 64 * 1024,
+})
+// {"10":"ten","2":"two","nested":[1,null]}
+// Native crypto or browser WebCrypto hashes these same UTF-8 bytes.
+```
+
+`canonicalJson` использует единый serializer исторических digest: object keys в UTF-16 code-unit
+order, включая integer-like keys; array order сохраняется. Optional object members с undefined
+опускаются. Top-level/array undefined, sparse arrays, functions/symbols/BigInt, non-finite numbers,
+negative zero, cycles, user prototypes, accessors, non-enumerable/symbol members отказаны до
+serialization. Приложение валидирует свою schema первым; canonical boundary не заменяет её.
+
+Defaults: depth 100 (maximum 100), nodes 100 000, UTF-8 bytes 1 MiB. Превышение или не-JSON data —
+TypeError; неверные options — Zod validation error. Это browser-safe leaf без Node/Bun/crypto,
+agent-runtime/testing или optional peers. Native и browser используют один algorithm; hashing
+остаётся platform adapter. Переносите только serializer recursion, сохраняя proof schemas и
+verification boundary. Существующие внутренние historical normalization/digest fixtures не меняются;
+новый public boundary сознательно отказывает неоднозначным values вместо фиктивной совместимости.
+
 ==============================================================================
 # API reference: `stitchkit/primitives`  (docs/api/reference.md)
 ==============================================================================
@@ -156,3 +181,8 @@ schedules, transports and file generation remain application-owned.
 | `SourceText` / `SourceRisk` | _types_ | migration scanner input and exact path/line evidence |
 
 ---
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `canonicalJson` | function | bounded plain JSON, UTF-16 key sort, optional object members omitted |
+| `CanonicalJsonOptions` | type | inferred depth/node/UTF-8 bytes limits |

package/llms/process.txt

@@ -0,0 +1,167 @@
+# stitchkit/process — 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: Native IO  (docs/guide/native-io.md) · API reference: `stitchkit/process`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Native IO  (docs/guide/native-io.md)
+==============================================================================
+
+---
+title: Конечные команды и файловые гарантии
+description: Native IO для Bun и Node, с явно выбранной durability, безопасными bounds и caller lifetime.
+type: guide
+status: active
+created: 2026-10-01 20:44 +07:00
+updated: 2026-10-01 21:31 +07:00
+participants:
+  - role: authored
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-01 20:44 +07:00
+---
+
+# Native IO
+
+Примеры используют публичные imports и одинаково исполняются в Bun и Node ≥22.
+
+## Запись файла
+
+```ts
+import { writeFileAtomic, AtomicFilePublicationError } from 'stitchkit/files'
+
+try {
+  await writeFileAtomic('/srv/app/receipt.json', JSON.stringify({ id: 'receipt-1' }), {
+    replace: false,
+    mode: 0o600,
+    durability: 'directory',
+  })
+} catch (error) {
+  if (error instanceof AtomicFilePublicationError) {
+    // target уже виден. Проверьте receipt, прежде чем решать о повторе.
+    console.error(error.phase, error.cause)
+  } else throw error
+}
+await writeFileAtomic('/srv/app/state.json', '{"version":2}', {
+  replace: true, durability: 'directory',
+})
+```
+
+По умолчанию `replace: true`, `durability: 'file'`, `mode: 0o600`: existing вызовы сохраняют
+file-fsync и atomic replacement. `durability: 'none'` отключает sync; `'directory'` выполняет
+полную запись → exact descriptor chmod → file fsync → rename (replace) либо link (create) →
+удаление staging link → parent fsync. `writeFileAtomicSync` имеет те же options и порядок.
+Create отказывает с native `EEXIST` при существующем файле, symlink или concurrent winner.
+Никогда не переводите этот отказ в replace автоматически.
+
+`AtomicFilePublicationError.published === true` отличает видимость от неподтверждённого
+acknowledgement. `phase` — `cleanup`, `directory-sync` или `directory-close`; первичная причина
+сохранена в `cause`. Ошибка до publish оставляет прежний target. Cleanup вторичен к первичной ошибке.
+При create кратко существует второй hardlink; strict single-link reader вправе отказать в этом окне.
+
+Directory fsync — native POSIX/filesystem capability. Windows явно отказывает; иной filesystem
+может отказать при open/sync. Проверка на Linux не подтверждает поведение macOS, сетевой FS или
+сохранность при отключении питания. Состояние диска определяется гарантиями самой FS/ОС.
+`createManagedFileBoundary.write(..., { durable: true })` использует тот же publish owner и parent sync;
+его create по умолчанию остаётся create, а `replace: true` явно разрешает replacement.
+
+## Строгое чтение
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app', maxReadBytes: 64 * 1024 })
+const source = await files.read('receipt.json', {
+  rejectSymlinks: true, singleLink: true, stable: true, observe: true,
+})
+console.log(source.observation) // dev, ino, size, nlink, mtimeMs, ctimeMs
+const receipt = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(source.bytes))
+// schema.parse(receipt) и проверка digest принадлежат приложению.
+```
+
+Без новых options ответ сохраняет `{ ref, bytes }`, допускает trusted in-root symlink и hardlink.
+`rejectSymlinks` запрещает requested leaf, `singleLink` проверяет `nlink` открытого descriptor,
+`stable` сравнивает dev/ino/size/mtime/ctime/nlink вокруг byte read; `observe` добавляет metadata.
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_UNSAFE_LINK`, `FILE_TOO_LARGE`, `FILE_CHANGED`,
+`FILE_UNSUPPORTED` и `FILE_IO_ERROR` различаются. Abort сохраняет caller reason.
+Nonblocking open позволяет отказать FIFO без ожидания writer. Bytes ограничены во время чтения,
+включая рост файла, не только initial stat. Chunk allocation ≤ maxBytes+1+64 KiB, flatten ≤ maxBytes;
+FD закрывается при success, отказе, abort и IO error.
+Ошибка close сохраняет первичную ошибку чтения; после успешного чтения ошибка close возвращается caller.
+
+Root и ancestors принадлежат trusted actor. Эти options не дают descriptor-relative containment
+при hostile concurrent ancestor replacement. Отдельного переключателя «считать ancestors безопасными»
+нет: portable owner не предоставляет такую capability. Metadata stability не доказывает immutable
+snapshot против произвольного hostile writer; используйте application lock/immutable publication.
+
+## Команды
+
+```ts
+import { runNativeCommand } from 'stitchkit/process'
+
+const captured = await runNativeCommand({
+  executable: '/usr/bin/git', args: ['rev-parse', 'HEAD'], cwd: '/srv/app',
+  envPolicy: 'declared-only', env: { PATH: '/usr/bin:/bin' },
+  capture: true, maxOutputBytes: 4096, timeoutMs: 5000,
+})
+console.log(captured.exitCode, new TextDecoder().decode(captured.stdout))
+
+const lifetime = new AbortController()
+await runNativeCommand({
+  executable: '/usr/bin/git', args: ['status'], signal: lifetime.signal,
+  onOutput: async (bytes, channel, outputSignal) => {
+    outputSignal.throwIfAborted()
+    await output.write(bytes, channel, outputSignal) // application-owned bounded sink
+  },
+})
+```
+
+Команда требует caller signal или finite `timeoutMs` (1–2147483647 ms: native timer range; большее значение отказывается, не превращается в 1 ms). Streaming имеет caller lifetime, без скрытого
+60-second timeout или 1-MiB output limit. `capture` по умолчанию false; true требует
+`maxOutputBytes` для суммарных stdout+stderr. Лимит считает исходные bytes; API возвращает
+`Uint8Array`, не преобразует invalid UTF-8. Result содержит наблюдаемый `exitCode: number | null`
+и `signal: string | null`; signal termination не превращается в выдуманный exit code. `maxOutputBytes` может ограничивать и streaming.
+`stdin` — bytes с `maxStdinBytes` (default 1 MiB). `envPolicy` default `declared-only`: отсутствие env
+означает пустой environment; `ambient` явно разрешает наследование. Cwd/executable policy остаётся
+приложению; этот primitive запускает native executable и сам не создаёт shell.
+
+Вывод читается с backpressure отдельно для stdout/stderr: один выполняющийся sink на канал плюс
+bounded native Readable buffer; накопления всей истории при streaming нет. Callback получает
+lifetime signal. Abort освобождает ожидание даже игнорирующего signal callback, но не способен
+отменить сторонние действия, которые сам callback продолжит после abort. Sink обязан отменять свои
+IO, не сохранять бесконечную историю и не изменять shared descriptor flags. После abort новых
+callbacks owner не запускает. Normal completion ждёт всех bytes и sinks.
+
+Cleanup: POSIX process group, TERM, `killGraceMs` (default 100, maximum 10 000), затем KILL;
+`cleanupTimeoutMs` (default 2000, maximum 30 000) ограничивает ожидание close после сигналов.
+Сохраняется caller/sink причина; failure cleanup — `NativeCommandError` с `COMMAND_CLEANUP` и
+AggregateError cause. Даже вышедший parent не исключает helper, удерживающий pipe. Windows
+отказывает с `COMMAND_UNAVAILABLE`; потомок, самостоятельно покинувший группу через setsid,
+лежит за границей этой capability. Это one-shot execution, не PTY, supervisor или daemon host.
+
+## Механическая адаптация
+
+Atomic file wrapper заменяется одним вызовом `writeFileAtomic` с выбранными options. Bounded
+regular-file read заменяется `files.read`; JSON/schema, receipt conflicts, journal rotation и
+application locks сохраняются. Spawn/drain/capture/cancellation wrapper заменяется `runNativeCommand`;
+shell policy, command admission, логирование, redaction, bytes→text decoder и operator sink сохраняются.
+Длительные signal-only команды остаются streaming; bounded tar/capture получают свои явные limits.
+Импорт leaf не делает установку всего npm package маленькой; выбирайте dependency после измерения
+packed размера и dependency closure.
+
+==============================================================================
+# API reference: `stitchkit/process`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/process`
+
+Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
+| `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
+| `NativeCommandError` | class | COMMAND_LIMIT, COMMAND_UNAVAILABLE or COMMAND_CLEANUP with internal cause |

package/llms/stitchkit.txt

@@ -68,6 +68,7 @@ own, recorded as an ADR.
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no 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` | 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/tools.txt

@@ -409,6 +409,10 @@ where both exist the runtime's wins, because the run is recorded in its ledger.
 
 #### An effect in another system — `effect`, at most once
 
+Standalone callers must hold an application-owned exclusive execution lease for the conversation/run
+through the whole effect call. Sharing a ledger or separate ledger adapters is not an atomic claim;
+the runtime supplies its run lease. Process-local coalescing only covers the same ledger object.
+
 `step` records its result **after** the body, so a body cut short by a crash
 runs again. For sending a message or starting a turn at a provider, a repeat is
 worse than a loss. The engine's `effect` records the intent **before** it runs:
@@ -431,6 +435,20 @@ throws, or a `reconcile` that throws or overruns `reconcileTimeoutMs` (default
 call. The proof is JSON of at most 64 KiB — the identity the recipient assigned,
 not a payload. → [ADR 0200](../decisions/0200-an-effect-is-recorded-before-it-runs.md)
 
+Caller abort during reconcile releases the wait with `StepAbortedError`, leaves the intent and ignores
+a late result. A coalesced caller can cancel its own await without cancelling the shared owner;
+the first caller owns reconciliation handlers/deadline. `reconcileTimeoutMs` cannot exceed the native
+timer range (2147483647 ms). It does not turn cancellation into proof of absence. Neither `null` nor an absence digest
+proves that an earlier recipient request cannot complete later. Safe retries require recipient-side
+idempotency or a verified fence. See [ADR 0224](../decisions/0224-native-primitives-have-one-owner.md).
+
+Ledger reads are paged at 10 000 and incremental in one engine; a fresh engine replays the conversation
+and retains its durable keys. This is not a bounded outstanding index/direct terminal receipt store.
+For application delivery, `defineDomainEventDelivery` in `stitchkit/primitives` composes a caller-owned
+atomic outbox claim with delivered/retryable/terminal/unknown states, bounded dispatch count (default
+100). Storage retention, per-key lookup, recipient proof and transactions remain in that adapter;
+it is not an automatic cutover for a different reconciliation protocol.
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all

package/llms-full.txt

@@ -59,6 +59,7 @@ own, recorded as an ADR.
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no 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` | 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 |
@@ -3872,6 +3873,10 @@ where both exist the runtime's wins, because the run is recorded in its ledger.
 
 #### An effect in another system — `effect`, at most once
 
+Standalone callers must hold an application-owned exclusive execution lease for the conversation/run
+through the whole effect call. Sharing a ledger or separate ledger adapters is not an atomic claim;
+the runtime supplies its run lease. Process-local coalescing only covers the same ledger object.
+
 `step` records its result **after** the body, so a body cut short by a crash
 runs again. For sending a message or starting a turn at a provider, a repeat is
 worse than a loss. The engine's `effect` records the intent **before** it runs:
@@ -3894,6 +3899,20 @@ throws, or a `reconcile` that throws or overruns `reconcileTimeoutMs` (default
 call. The proof is JSON of at most 64 KiB — the identity the recipient assigned,
 not a payload. → [ADR 0200](../decisions/0200-an-effect-is-recorded-before-it-runs.md)
 
+Caller abort during reconcile releases the wait with `StepAbortedError`, leaves the intent and ignores
+a late result. A coalesced caller can cancel its own await without cancelling the shared owner;
+the first caller owns reconciliation handlers/deadline. `reconcileTimeoutMs` cannot exceed the native
+timer range (2147483647 ms). It does not turn cancellation into proof of absence. Neither `null` nor an absence digest
+proves that an earlier recipient request cannot complete later. Safe retries require recipient-side
+idempotency or a verified fence. See [ADR 0224](../decisions/0224-native-primitives-have-one-owner.md).
+
+Ledger reads are paged at 10 000 and incremental in one engine; a fresh engine replays the conversation
+and retains its durable keys. This is not a bounded outstanding index/direct terminal receipt store.
+For application delivery, `defineDomainEventDelivery` in `stitchkit/primitives` composes a caller-owned
+atomic outbox claim with delivered/retryable/terminal/unknown states, bounded dispatch count (default
+100). Storage retention, per-key lookup, recipient proof and transactions remain in that adapter;
+it is not an automatic cutover for a different reconciliation protocol.
+
 ### Typed MCP call metadata
 
 Contract handlers, runtime-tool handlers/factories, lifecycle and tool hooks all
@@ -8002,6 +8021,153 @@ workspace-relative or canonical `/workspace/...` paths. Unsupported policies mus
 be refused explicitly by the backend.
 
 
+==============================================================================
+# Guide: Native IO  (docs/guide/native-io.md)
+==============================================================================
+
+---
+title: Конечные команды и файловые гарантии
+description: Native IO для Bun и Node, с явно выбранной durability, безопасными bounds и caller lifetime.
+type: guide
+status: active
+created: 2026-10-01 20:44 +07:00
+updated: 2026-10-01 21:31 +07:00
+participants:
+  - role: authored
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-01 20:44 +07:00
+---
+
+# Native IO
+
+Примеры используют публичные imports и одинаково исполняются в Bun и Node ≥22.
+
+## Запись файла
+
+```ts
+import { writeFileAtomic, AtomicFilePublicationError } from 'stitchkit/files'
+
+try {
+  await writeFileAtomic('/srv/app/receipt.json', JSON.stringify({ id: 'receipt-1' }), {
+    replace: false,
+    mode: 0o600,
+    durability: 'directory',
+  })
+} catch (error) {
+  if (error instanceof AtomicFilePublicationError) {
+    // target уже виден. Проверьте receipt, прежде чем решать о повторе.
+    console.error(error.phase, error.cause)
+  } else throw error
+}
+await writeFileAtomic('/srv/app/state.json', '{"version":2}', {
+  replace: true, durability: 'directory',
+})
+```
+
+По умолчанию `replace: true`, `durability: 'file'`, `mode: 0o600`: existing вызовы сохраняют
+file-fsync и atomic replacement. `durability: 'none'` отключает sync; `'directory'` выполняет
+полную запись → exact descriptor chmod → file fsync → rename (replace) либо link (create) →
+удаление staging link → parent fsync. `writeFileAtomicSync` имеет те же options и порядок.
+Create отказывает с native `EEXIST` при существующем файле, symlink или concurrent winner.
+Никогда не переводите этот отказ в replace автоматически.
+
+`AtomicFilePublicationError.published === true` отличает видимость от неподтверждённого
+acknowledgement. `phase` — `cleanup`, `directory-sync` или `directory-close`; первичная причина
+сохранена в `cause`. Ошибка до publish оставляет прежний target. Cleanup вторичен к первичной ошибке.
+При create кратко существует второй hardlink; strict single-link reader вправе отказать в этом окне.
+
+Directory fsync — native POSIX/filesystem capability. Windows явно отказывает; иной filesystem
+может отказать при open/sync. Проверка на Linux не подтверждает поведение macOS, сетевой FS или
+сохранность при отключении питания. Состояние диска определяется гарантиями самой FS/ОС.
+`createManagedFileBoundary.write(..., { durable: true })` использует тот же publish owner и parent sync;
+его create по умолчанию остаётся create, а `replace: true` явно разрешает replacement.
+
+## Строгое чтение
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app', maxReadBytes: 64 * 1024 })
+const source = await files.read('receipt.json', {
+  rejectSymlinks: true, singleLink: true, stable: true, observe: true,
+})
+console.log(source.observation) // dev, ino, size, nlink, mtimeMs, ctimeMs
+const receipt = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(source.bytes))
+// schema.parse(receipt) и проверка digest принадлежат приложению.
+```
+
+Без новых options ответ сохраняет `{ ref, bytes }`, допускает trusted in-root symlink и hardlink.
+`rejectSymlinks` запрещает requested leaf, `singleLink` проверяет `nlink` открытого descriptor,
+`stable` сравнивает dev/ino/size/mtime/ctime/nlink вокруг byte read; `observe` добавляет metadata.
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_UNSAFE_LINK`, `FILE_TOO_LARGE`, `FILE_CHANGED`,
+`FILE_UNSUPPORTED` и `FILE_IO_ERROR` различаются. Abort сохраняет caller reason.
+Nonblocking open позволяет отказать FIFO без ожидания writer. Bytes ограничены во время чтения,
+включая рост файла, не только initial stat. Chunk allocation ≤ maxBytes+1+64 KiB, flatten ≤ maxBytes;
+FD закрывается при success, отказе, abort и IO error.
+Ошибка close сохраняет первичную ошибку чтения; после успешного чтения ошибка close возвращается caller.
+
+Root и ancestors принадлежат trusted actor. Эти options не дают descriptor-relative containment
+при hostile concurrent ancestor replacement. Отдельного переключателя «считать ancestors безопасными»
+нет: portable owner не предоставляет такую capability. Metadata stability не доказывает immutable
+snapshot против произвольного hostile writer; используйте application lock/immutable publication.
+
+## Команды
+
+```ts
+import { runNativeCommand } from 'stitchkit/process'
+
+const captured = await runNativeCommand({
+  executable: '/usr/bin/git', args: ['rev-parse', 'HEAD'], cwd: '/srv/app',
+  envPolicy: 'declared-only', env: { PATH: '/usr/bin:/bin' },
+  capture: true, maxOutputBytes: 4096, timeoutMs: 5000,
+})
+console.log(captured.exitCode, new TextDecoder().decode(captured.stdout))
+
+const lifetime = new AbortController()
+await runNativeCommand({
+  executable: '/usr/bin/git', args: ['status'], signal: lifetime.signal,
+  onOutput: async (bytes, channel, outputSignal) => {
+    outputSignal.throwIfAborted()
+    await output.write(bytes, channel, outputSignal) // application-owned bounded sink
+  },
+})
+```
+
+Команда требует caller signal или finite `timeoutMs` (1–2147483647 ms: native timer range; большее значение отказывается, не превращается в 1 ms). Streaming имеет caller lifetime, без скрытого
+60-second timeout или 1-MiB output limit. `capture` по умолчанию false; true требует
+`maxOutputBytes` для суммарных stdout+stderr. Лимит считает исходные bytes; API возвращает
+`Uint8Array`, не преобразует invalid UTF-8. Result содержит наблюдаемый `exitCode: number | null`
+и `signal: string | null`; signal termination не превращается в выдуманный exit code. `maxOutputBytes` может ограничивать и streaming.
+`stdin` — bytes с `maxStdinBytes` (default 1 MiB). `envPolicy` default `declared-only`: отсутствие env
+означает пустой environment; `ambient` явно разрешает наследование. Cwd/executable policy остаётся
+приложению; этот primitive запускает native executable и сам не создаёт shell.
+
+Вывод читается с backpressure отдельно для stdout/stderr: один выполняющийся sink на канал плюс
+bounded native Readable buffer; накопления всей истории при streaming нет. Callback получает
+lifetime signal. Abort освобождает ожидание даже игнорирующего signal callback, но не способен
+отменить сторонние действия, которые сам callback продолжит после abort. Sink обязан отменять свои
+IO, не сохранять бесконечную историю и не изменять shared descriptor flags. После abort новых
+callbacks owner не запускает. Normal completion ждёт всех bytes и sinks.
+
+Cleanup: POSIX process group, TERM, `killGraceMs` (default 100, maximum 10 000), затем KILL;
+`cleanupTimeoutMs` (default 2000, maximum 30 000) ограничивает ожидание close после сигналов.
+Сохраняется caller/sink причина; failure cleanup — `NativeCommandError` с `COMMAND_CLEANUP` и
+AggregateError cause. Даже вышедший parent не исключает helper, удерживающий pipe. Windows
+отказывает с `COMMAND_UNAVAILABLE`; потомок, самостоятельно покинувший группу через setsid,
+лежит за границей этой capability. Это one-shot execution, не PTY, supervisor или daemon host.
+
+## Механическая адаптация
+
+Atomic file wrapper заменяется одним вызовом `writeFileAtomic` с выбранными options. Bounded
+regular-file read заменяется `files.read`; JSON/schema, receipt conflicts, journal rotation и
+application locks сохраняются. Spawn/drain/capture/cancellation wrapper заменяется `runNativeCommand`;
+shell policy, command admission, логирование, redaction, bytes→text decoder и operator sink сохраняются.
+Длительные signal-only команды остаются streaming; bounded tar/capture получают свои явные limits.
+Импорт leaf не делает установку всего npm package маленькой; выбирайте dependency после измерения
+packed размера и dependency closure.
+
+
 ==============================================================================
 # Guide: Generic application primitives  (docs/guide/primitives.md)
 ==============================================================================
@@ -8012,7 +8178,7 @@ description: Declare lifecycle, access, exact values, audit, delivery and export
 type: guide
 status: active
 created: 2026-09-01
-updated: 2026-09-01
+updated: 2026-10-01 21:03 +07:00
 ---
 
 # Generic application primitives
@@ -8105,6 +8271,31 @@ of the application's existing async operation. The input, scope, metadata and to
 change. The application creates bytes and owns operation persistence; the managed-file boundary
 streams them.
 
+## Canonical JSON
+
+```ts
+import { canonicalJson } from 'stitchkit/primitives'
+
+const bytes = canonicalJson({ '2': 'two', '10': 'ten', optional: undefined, nested: [1, null] }, {
+  maxDepth: 20, maxNodes: 10_000, maxBytes: 64 * 1024,
+})
+// {"10":"ten","2":"two","nested":[1,null]}
+// Native crypto or browser WebCrypto hashes these same UTF-8 bytes.
+```
+
+`canonicalJson` использует единый serializer исторических digest: object keys в UTF-16 code-unit
+order, включая integer-like keys; array order сохраняется. Optional object members с undefined
+опускаются. Top-level/array undefined, sparse arrays, functions/symbols/BigInt, non-finite numbers,
+negative zero, cycles, user prototypes, accessors, non-enumerable/symbol members отказаны до
+serialization. Приложение валидирует свою schema первым; canonical boundary не заменяет её.
+
+Defaults: depth 100 (maximum 100), nodes 100 000, UTF-8 bytes 1 MiB. Превышение или не-JSON data —
+TypeError; неверные options — Zod validation error. Это browser-safe leaf без Node/Bun/crypto,
+agent-runtime/testing или optional peers. Native и browser используют один algorithm; hashing
+остаётся platform adapter. Переносите только serializer recursion, сохраняя proof schemas и
+verification boundary. Существующие внутренние historical normalization/digest fixtures не меняются;
+новый public boundary сознательно отказывает неоднозначным values вместо фиктивной совместимости.
+
 
 ==============================================================================
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
@@ -18804,6 +18995,12 @@ schedules, transports and file generation remain application-owned.
 
 ---
 
+| Export | Kind | Purpose |
+|---|---|---|
+| `canonicalJson` | function | bounded plain JSON, UTF-16 key sort, optional object members omitted |
+| `CanonicalJsonOptions` | type | inferred depth/node/UTF-8 bytes limits |
+
+
 ## `stitchkit/server`
 
 Server-only. Builds and runs the HTTP server, and carries the server primitives.
@@ -20380,6 +20577,12 @@ available from `stitchkit/contract`.
 
 ---
 
+| Export | Kind | Purpose |
+|---|---|---|
+| `AtomicFilePublicationError` | class | published=true with cleanup/directory-sync/directory-close phase |
+| `FileObservation` | type | observed descriptor dev/ino/size/nlink/mtimeMs/ctimeMs |
+
+
 ## `stitchkit/telegram`
 
 Peer-free server-only Telegram platform primitives — the Bot API's own
@@ -20907,3 +21110,15 @@ AI-only peer boundary. Existing custom tool callbacks need no new import.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAgentHarnessTools` / `AgentHarnessToolsConfig` | function / _type_ | async per-run full mount configuration (`services` plus all `AgentMountConfig` options); composes application lifecycle then runtime fence exactly once |
+
+
+## `stitchkit/process`
+
+Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
+| `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
+| `NativeCommandError` | class | COMMAND_LIMIT, COMMAND_UNAVAILABLE or COMMAND_CLEANUP with internal cause |