stitchkit 0.98.2 → 0.100.0

package/CHANGELOG.md

@@ -15,6 +15,69 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.100.0] — 2026-09-28
+
+### ⚠️ Breaking changes
+
+- `stitchkit/application`, `stitchkit/live` — watched reads now enforce finite
+  capacity by default: 1024 hub sources, 1024 hub subscribers, 1024 client keys
+  and 128 listeners per key. Excess admission is refused instead of retaining
+  unbounded state. Before: `createWatchHub({ read, watchable })` admitted an
+  unlimited number of hub sources/subscribers. After, for a larger workload:
+  `createWatchHub({ read, watchable, maxSources: 4096, maxSubscribers: 4096 })`.
+  Set `maxKeys` and `maxListenersPerKey` on `createWatchClient` when needed.
+  See ADR 0208 and the 0.100.0 migration in `docs/guide/upgrading.md`.
+
+**Who must act:** watch consumers whose hub or client exceeds these defaults.
+Choose explicit finite limits for the expected workload. Other consumers may
+keep their existing configuration; new session and delivery APIs are opt-in.
+
+### Added
+
+- `stitchkit` — `createSessionScope` fences requests and final delivery by login
+  lifetime; `createSessionCredentials` coordinates refresh and credential writes.
+- `stitchkit/application` — managed change subscriptions with bounded keys,
+  reconnect and periodic reconciliation; watch admission scopes and capacity limits;
+  optional outbox action checkpoints and a separate projection receipt.
+- `stitchkit/live`, `stitchkit/react` — session-scoped watch instances and explicit
+  watched-handle/cache bindings. Hub reconciliation can repair lost hints without
+  reconnect. Existing non-session watches and single-send outboxes remain supported.
+
+- `stitchkit/agent-runtime` — public `createModelInvocationLedger` for plain text
+  completions and shared agent provider receipts, with atomic idempotent admission,
+  verified caller context, explicit fallback attempts, transport correlation IDs,
+  provenance-aware usage and encrypted payload artifacts in the existing store.
+  Opt in with the runtime `invocations` option. See ADR 0206 and the
+  [migration example](docs/guide/agent-runtime.md#plain-completions-and-shared-invocation-receipts).
+
+### Fixed
+
+- `stitchkit/files`, `stitchkit/application` — exclusive locks and journal reclaim
+  guards identify the owning boot and process lifetime, so a PID reused after a
+  crash or reboot no longer impersonates an abandoned owner. Linux uses proc
+  start ticks and namespaces; macOS uses the packaged native kernel probe.
+  Unknown identity refuses takeover. Legacy records retain conservative PID
+  checks and require operator recovery when a live PID has been reused. See ADR 0210.
+
+## [0.99.0] — 2026-09-27
+
+### ⚠️ Breaking changes
+
+- `stitchkit/tools` — `flattenUnionInput` preserves object properties and typed
+  array items when discriminated-union variants share a field with different
+  structures. Flat mode no longer guarantees the absence of nested `anyOf`.
+  Before: a collided object/array field was `{ type: ['object', 'array'] }`.
+  After: `{ anyOf: [{ type: 'object', properties: ... }, { type: 'array', items: ... }] }`.
+  The containing union stays an object and the original contract still validates
+  execution. Schema consumers must traverse these nested alternatives; no
+  contract changes or global flatten opt-out are needed. This avoids provider
+  rejection of array schemas with missing `items`. See
+  [ADR 0205](docs/decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
+
+**Who must act:** users of `flattenUnionInput: true` whose schema walkers,
+snapshots or provider restrictions assume no nested `anyOf`. Other consumers
+only update the dependency; runtime input validation is unchanged.
+
 ## [0.98.2] — 2026-09-27
 
 ### Fixed

package/dist/agent-runtime/contained-darwin.d.ts

@@ -5,27 +5,10 @@
  */
 import { type Stats } from 'node:fs';
 import type { ContainedFileHandle } from './contained-files.js';
-export interface DarwinEntry {
-    name: string;
-    mode: number;
-    size: number;
-}
-export interface DarwinBinding {
-    openDirectoryAt(directory: number, name: string): number;
-    openFileAt(directory: number, name: string): number;
-    createFileAt(directory: number, name: string, mode: number): number;
-    createDirectoryAt(directory: number, name: string, mode: number): boolean;
-    statAt(directory: number, name: string): Omit<DarwinEntry, 'name'> | null;
-    listAt(directory: number): readonly DarwinEntry[];
-    renameAt(directory: number, source: string, target: string): void;
-    unlinkAt(directory: number, name: string): void;
-}
 export declare const FILE_TYPE_DIRECTORY = 16384;
 export declare const FILE_TYPE_REGULAR = 32768;
 export declare const FILE_TYPE_SYMLINK = 40960;
 export declare function modeIs(mode: number, type: number): boolean;
-export declare function hasFunctions(value: unknown, names: readonly string[]): boolean;
-export declare function loadDarwinBinding(): DarwinBinding;
 export declare class NumericFileHandle implements ContainedFileHandle {
     readonly fd: number;
     constructor(fd: number);

package/dist/agent-runtime/contained-darwin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contained-darwin.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/contained-darwin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAKL,KAAK,KAAK,EACX,MAAM,SAAS,CAAC;AAKjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAGD,eAAO,MAAM,mBAAmB,QAAW,CAAC;AAC5C,eAAO,MAAM,iBAAiB,QAAW,CAAC;AAC1C,eAAO,MAAM,iBAAiB,QAAW,CAAC;AAE1C,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9E;AAID,wBAAgB,iBAAiB,IAAI,aAAa,CA+BjD;AAED,qBAAa,iBAAkB,YAAW,mBAAmB;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM;IAA/B,YAAqB,EAAE,EAAE,MAAM,EAAI;IAEnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAIrB;IAED,IAAI,CACF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAMhC;IAED,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAIrB;CACF"}
+{"version":3,"file":"contained-darwin.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/contained-darwin.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAA2D,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D,eAAO,MAAM,mBAAmB,QAAW,CAAC;AAC5C,eAAO,MAAM,iBAAiB,QAAW,CAAC;AAC1C,eAAO,MAAM,iBAAiB,QAAW,CAAC;AAE1C,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,qBAAa,iBAAkB,YAAW,mBAAmB;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM;IAA/B,YAAqB,EAAE,EAAE,MAAM,EAAI;IAEnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAIrB;IAED,IAAI,CACF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAMhC;IAED,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAIrB;CACF"}

package/dist/agent-runtime/contained-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contained-write.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/contained-write.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAsD3B,0FAA0F;AAC1F,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAsChB"}
+{"version":3,"file":"contained-write.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/contained-write.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,mBAAmB,CAAC;AAsD3B,0FAA0F;AAC1F,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAsChB"}

package/dist/agent-runtime/invocation-attempt.d.ts

@@ -0,0 +1,22 @@
+import { type LanguageModel } from 'ai';
+import type { z } from 'zod';
+import type { createInvocationPayloads } from './invocation-payload.js';
+import type { InvocationProcessSchema, ModelInvocationAttemptContext, ModelInvocationRecord } from './invocation-schema.js';
+import type { AgentResolvedModel } from './models.js';
+/** Available inside the provider's fetch/transport; no time/model-name correlation. */
+export declare function currentModelInvocationAttempt(): ModelInvocationAttemptContext | undefined;
+export interface InvocationAttemptWriter {
+    identity: {
+        conversationId: string;
+        invocationId: string;
+        operationId: string;
+        runId?: string;
+    };
+    process: z.infer<typeof InvocationProcessSchema>;
+    payloads: ReturnType<typeof createInvocationPayloads>;
+    append(record: ModelInvocationRecord): Promise<void>;
+    onAttempt?(context: ModelInvocationAttemptContext): void | Promise<void>;
+}
+/** The single audited provider boundary, used by completion and the existing agent loop. */
+export declare function wrapInvocationModel(writer: InvocationAttemptWriter, selected: AgentResolvedModel, step: number, model?: LanguageModel): LanguageModel;
+//# sourceMappingURL=invocation-attempt.d.ts.map

package/dist/agent-runtime/invocation-attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-attempt.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/invocation-attempt.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,aAAa,EAAmD,MAAM,IAAI,CAAC;AACzF,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,KAAK,EACV,uBAAuB,EACvB,6BAA6B,EAC7B,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AASnD,uFAAuF;AACvF,wBAAgB,6BAA6B,IAAI,6BAA6B,GAAG,SAAS,CAGzF;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE;QACR,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;IACjD,QAAQ,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;IACtD,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,SAAS,CAAC,CAAC,OAAO,EAAE,6BAA6B,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,uBAAuB,EAC/B,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,aAA8B,GACpC,aAAa,CAsLf"}

package/dist/agent-runtime/invocation-failure.d.ts

@@ -0,0 +1,6 @@
+/** Receipt/storage/audit refusals belong to the runtime, never to the upstream provider. */
+export declare class InvocationReceiptError extends Error {
+    constructor(cause: unknown);
+}
+export declare function invocationAudit<T>(work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=invocation-failure.d.ts.map

package/dist/agent-runtime/invocation-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-failure.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/invocation-failure.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,KAAK,EAAE,OAAO,EAGzB;CACF;AACD,wBAAsB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAM3E"}

package/dist/agent-runtime/invocation-payload.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { AgentRuntimeStore } from './store.js';
+/** Serialize SDK payloads at the typed external boundary, retaining binary bytes privately. */
+export declare function invocationJson(value: unknown): z.JSONType;
+export declare function invocationHash(value: unknown): string;
+export declare function createInvocationPayloads(store: AgentRuntimeStore, key: Uint8Array, maxBytes: number): {
+    write(identity: {
+        conversationId: string;
+        invocationId: string;
+        operationId: string;
+        runId?: string;
+    }, value: unknown): Promise<{
+        artifactId: `${string}-${string}-${string}-${string}-${string}`;
+        sha256: string;
+    }>;
+    decrypt(conversationId: string, value: unknown): z.JSONType;
+};
+//# sourceMappingURL=invocation-payload.d.ts.map

package/dist/agent-runtime/invocation-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-payload.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/invocation-payload.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,cAc5C;AACD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIrD;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM;IAMR,KAAK,WACC;QACR,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,SACM,OAAO;;;;IA+BhB,OAAO,iBAAiB,MAAM,SAAS,OAAO;EAgCjD"}

package/dist/agent-runtime/invocation-read.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import type { createInvocationPayloads } from './invocation-payload.js';
+import type { AgentRuntimeStore } from './store.js';
+export declare const InvocationReadInputSchema: z.ZodObject<{
+    conversationId: z.ZodString;
+    fromSeq: z.ZodOptional<z.ZodInt>;
+    limit: z.ZodInt;
+}, z.core.$strict>;
+export declare function readInvocationRecords(store: AgentRuntimeStore, input: z.infer<typeof InvocationReadInputSchema>): Promise<{
+    items: {
+        seq: number;
+        occurredAt: string;
+        record: {
+            conversationId: string;
+            invocationId: string;
+            operationId: string;
+            runId?: string | undefined;
+            type: "invocation/started";
+            mode: "agent" | "completion";
+            trace: {
+                operationId: string;
+                purpose: string;
+                project: string;
+                parent?: {
+                    traceId: string;
+                    invocationId?: string | undefined;
+                } | undefined;
+                experiment?: string | undefined;
+                case?: string | undefined;
+                profile?: string | undefined;
+            };
+            caller: {
+                subject: string;
+            };
+            executingProcess: {
+                instanceId: string;
+                pid: number;
+                hostname: string;
+            };
+            fingerprint: string;
+            requested: {
+                models: string[];
+                payloadSha256: string;
+            };
+        } | {
+            conversationId: string;
+            invocationId: string;
+            operationId: string;
+            runId?: string | undefined;
+            attemptId: string;
+            step: number;
+            type: "provider/request";
+            requested: {
+                modelId: string;
+                provider: string;
+            };
+            executingProcess: {
+                instanceId: string;
+                pid: number;
+                hostname: string;
+            };
+            sent: {
+                modelId: string;
+                provider: string;
+                payloadSha256: string;
+                artifactId: string;
+                tools: number;
+            };
+        } | {
+            conversationId: string;
+            invocationId: string;
+            operationId: string;
+            runId?: string | undefined;
+            attemptId: string;
+            step: number;
+            type: "provider/response";
+            status: "cancelled" | "failed" | "succeeded";
+            effective: {
+                provider: string | null;
+                modelId: string | null;
+                responseId: string | null;
+            };
+            usage: {
+                inputTokens: {
+                    value?: number | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                };
+                outputTokens: {
+                    value?: number | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                };
+                reasoningTokens?: {
+                    value?: number | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                } | undefined;
+                cacheReadTokens?: {
+                    value?: number | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                } | undefined;
+                cacheWriteTokens?: {
+                    value?: number | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                } | undefined;
+                cost?: {
+                    value?: number | undefined;
+                    currency?: string | undefined;
+                    provenance: "computed" | "estimated" | "provider-reported" | "unavailable";
+                } | undefined;
+            };
+            artifactId: string;
+            payloadSha256: string;
+        } | {
+            conversationId: string;
+            invocationId: string;
+            operationId: string;
+            runId?: string | undefined;
+            type: "invocation/finished";
+            failure?: {
+                artifactId: string;
+                payloadSha256: string;
+            } | undefined;
+            status: "cancelled" | "failed" | "succeeded";
+        };
+    }[];
+    nextSeq?: number | undefined;
+}>;
+export declare function readInvocationPayload(store: AgentRuntimeStore, payloads: ReturnType<typeof createInvocationPayloads>, input: {
+    conversationId: string;
+    artifactId: string;
+}): Promise<z.JSONType>;
+//# sourceMappingURL=invocation-read.d.ts.map

package/dist/agent-runtime/invocation-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-read.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/invocation-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,eAAO,MAAM,yBAAyB;;;;kBAM3B,CAAC;AAEZ,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BjD;AAED,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,EACrD,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,uBAkBtD"}