stitchkit 0.103.8 → 0.103.10

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)
 ==============================================================================
@@ -27,7 +30,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` (default 5000 ms, `null` disables age-based reclaim including guards); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
 | `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |
@@ -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,242 @@
+# 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-02 00:37 +07:00
+participants:
+  - role: authored
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-01 20:44 +07:00
+  - role: implemented
+    harness: Codex
+    model: GPT-6
+    at: 2026-10-02 00:08 +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 после сигналов.
+На Darwin временный `EPERM` при сигнале группе может означать zombies, ещё не убранные
+OS reaper. Повтор ограничен `cleanupTimeoutMs`; успех требует доставленного сигнала или
+`ESRCH`, постоянный отказ сохраняется в cause. Закрытие каждого owned pipe и выход leader
+наблюдаются отдельно, включая отсутствие общего `child.close` при teardown.
+Сохраняется 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.
+## Resource-scoped launchers and shared owners
+
+`onLeaderSettled(event, signal)` observes leader exit before inherited stdout/stderr pipes
+close. A resource owner can stop its external scope there, allowing pipe drain to complete.
+The callback runs once: `event.kind === 'exit'` carries observed `exitCode`/`signal`; a terminal
+failure uses `kind: 'error'` and preserves its cause. Unavailable executables, output sink
+failure and caller cancellation settle through the same owner. `cleanupTimeoutMs` bounds
+the callback after settlement starts; it never becomes a deadline for signal-only execution.
+Honor the settlement signal; arbitrary user promises cannot be forcibly cancelled.
+
+```ts
+await runNativeCommand({
+  executable: launcher,
+  args,
+  signal: scope.signal,
+  onOutput: (bytes, channel, signal) => scope.write(bytes, channel, signal),
+  onLeaderSettled: (event, signal) => scope.settle(event, signal),
+});
+```
+
+`observeProcessInstance(pid)` returns `observed` with a `ProcessInstance`, or `unavailable`
+with its cause. `probeProcessOwner(pid, recorded)` compares that evidence on the machine the
+caller established: `matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy` or
+`unavailable`. Missing/partial/denied evidence is not death. Supervisor tree fencing remains
+the caller's job; a PID lifetime is not proof that its whole workload stopped.
+
+An exclusive lock applies exact requested permissions through its creating descriptor,
+independent of umask. Default `0600` stays private. Shared `0640` requires a common group and
+traversable directories; another UID also needs directory write permission to reclaim a
+proven-dead owner's file. Set `ownerlessGraceMs: null` to refuse every age-only reclaim,
+including ownerless reclaim guards. The default remains 5000 ms for existing clients.
+Восстановление stale reclaim guard использует тот же lock owner и следующий guard:
+проверка inode и удаление выполняются под ним. Конкурирующий writer не обходит guard,
+пока прежнее удаление приостановлено; live и unknown lifetime evidence остаются отказом.
+
+## Libraries with a Zod-only runtime
+
+Public leaves keep optional peers out of their import closure. Installing `stitchkit` still
+installs the complete package and ky; selective imports alone do not avoid that installation.
+A library can use Stitchkit as a build dependency, bundle its selected public native imports,
+keep Zod external, and publish the resulting implementation with its library artifact.
+
+```ts
+// The library's build entry; all mechanisms remain owned by Stitchkit.
+export { canonicalJson } from 'stitchkit/primitives';
+export { writeFileAtomic, withExclusiveLock } from 'stitchkit/files';
+export { observeProcessInstance, probeProcessOwner, runNativeCommand } from 'stitchkit/process';
+```
+
+Bundle for Node-compatible execution with Zod external. Publish declarations from the same
+version: carry their reachable relative `.d.ts` closure, rather than emitting references to
+`stitchkit` that force clients to install it for types. A library exposing its own DTOs may
+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.
+
+Darwin consumers need the published native binaries at the bundled loader's relative native
+directory. A JS-only bundle is not portable evidence. Qualify the packed library outside its
+build tree in Bun and Node, test its declarations, and check that importing an unbundled
+Stitchkit leaf fails there. A separate schema-only entry must not import the native entry.
+
+This delivery removes a runtime kernel installation; it does not remove the build-time
+Stitchkit installation or create an independent lightweight npm package.
+
+==============================================================================
+# 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 |
+
+| `NativeCommandSettlement` | type | observed leader `exit` or terminal `error`; `onLeaderSettled` runs once before drain, bounded by cleanupTimeoutMs, with a cancellable settlement signal |
+| `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 |

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