stitchkit 0.99.0 → 0.100.1

package/llms-full.txt

@@ -68,11 +68,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 44 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 45 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 44 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 45 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -82,7 +82,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 44 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 45 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -3245,6 +3245,47 @@ hour and drops again starts its next retry at `minDelayMs` rather than the
 ceiling it reached last time. Aborting the signal ends the iteration promptly,
 including in the middle of a wait.
 
+## Operations belong to a login lifetime
+
+Use `createSessionScope` when a client can log out or switch accounts. The scope is
+host-owned and context is immutable. Replace it for **every** login, even to the
+same account. Capture once for an entire compound operation:
+
+```ts
+import { createClient, createSessionScope } from 'stitchkit'
+
+const sessions = createSessionScope<{ accountId: string }>()
+const operation = sessions.replace({ accountId: 'account-a' })
+const client = createClient(contract, {
+  baseUrl,
+  fetch: operation.bindFetch(fetch, () => ({ Authorization: tokenFor(operation) })),
+})
+const value = await operation.run(() => client.read())
+operation.deliver(() => applyResult(value))
+```
+
+Capture before the first request, keep the same operation for a second request or
+one explicitly allowed auth retry, and guard the **actual** final transport send
+or local state change. An async delivery callback needs another check after its
+await; `deliver` itself is synchronous. Guard error delivery too. Cancellation is
+additional protection and cannot undo server effects. `SessionExpiredError` means
+discard the stale operation, not refresh a new user's credentials. For raw/stream
+responses, guard each consumed chunk and final delivery; `run` returning a stream
+does not mean its future contents have been consumed.
+
+`createSessionCredentials({ scope, refresh, storage })` coordinates the same scope.
+`login(context, credentials)` creates a generation, `read(operation)` resolves only
+that generation's credentials, and concurrent `refresh(operation)` shares one
+flight. `logout()` invalidates memory immediately and resolves after its ordered
+storage clear (or a newer login superseding that clear). Handle storage and capacity
+errors explicitly; a rejected write is not proof of durable login/logout. Refresh
+network work never holds the storage queue. Callers decide whether a failed command
+may be retried once; do not replay a multi-step callback or treat any `403` as expiry.
+
+This is per-instance coordination. Route all writes through it; shared tabs/processes
+need storage-level locking. Replace the local session counter and refresh queue when
+adopting these primitives instead of retaining two independent lifetimes.
+
 
 ==============================================================================
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
@@ -4847,7 +4888,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-09-26 16:00 +07:00
+updated: 2026-09-28 18:39 +07:00
 ---
 
 # Agent application runtime
@@ -5464,9 +5505,14 @@ has invoked a tool is never automatically replayed.
 `createAgentScheduleService` persists `at`, `after` and `every` input. Repeating
 schedules require an explicit IANA time zone. Dispatch uses a stable
 `schedule:<id>:<occurrence>` idempotency key, and restart lateness is recorded.
-Resolve `void` after durable admission; return `{ status: 'retry', reason }` for a
+Resolve after durable admission; return `{ status: 'retry', reason }` for a
 transient refusal or `{ status: 'terminal', reason }` to stop the entire schedule in
-`failed` state. Throws retry too. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
+`failed` state. Only those two shapes are failures: any other returned value — a
+queue length, a receipt — means the callback returned, so it delivered. Throws retry
+too. `maxAttempts` (default 1000, about sixteen hours at the retry ceiling) bounds
+one occurrence: a one-off schedule then becomes `failed`, a recurring one gives up
+that occurrence (`schedule/failed` with `skipped: true` and the `nextAt` it moves
+to) and keeps its cadence. A failure reason is kept to 1000 characters. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
 capped at 60 seconds and persisted across restart. `retryAt`, `attempts` and `lastError`
 show retry diagnostics; success resets them. `nextAt` and `lateByMs` retain the original
 occurrence time. Recurring schedules fire once after an idle stretch and advance to the
@@ -6273,6 +6319,108 @@ can provision those parents; the optional `cleanup(context)` removes them again,
 whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
 keeps working unchanged.
 
+## Plain completions and shared invocation receipts
+
+Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
+completion and an agent must share causal provider evidence. It uses the existing
+runtime store, not a second database. The completion path sends exactly one user
+prompt, no framework instructions and no tools. It never starts an agent loop.
+
+```ts
+import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
+
+const invocations = createModelInvocationLedger({
+  store, // the same AgentRuntimeStore object passed to createAgentRuntime
+  models, // an existing defineModelRegistry result
+  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
+  authorize: async ({ context, conversationId, action, trace }) => {
+    const session = await authenticate(context);
+    await authorizeConversation(session, conversationId, action, trace);
+    return { subject: session.subject }; // verified identity, never a body field
+  },
+});
+
+const completion = await invocations.complete({
+  conversationId: 'evaluation-42',
+  idempotencyKey: 'summary-case-3',
+  trace: {
+    operationId: 'summary-42', purpose: 'summarize', project: 'example',
+    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
+  },
+  prompt: 'Summarize these supplied facts.',
+  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
+  settings: { maxOutputTokens: 500 },
+  timeoutMs: 30_000,
+}, authenticatedContext);
+
+// Add to the existing createAgentRuntime configuration:
+const receiptConfig = {
+  ledger: invocations,
+  trace: ({ run }) => ({
+    operationId: run.id, purpose: 'assistant-turn', project: 'example',
+  }),
+};
+// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
+
+const page = await invocations.read({
+  conversationId: 'evaluation-42', limit: 100,
+}, authenticatedContext);
+// Continue with fromSeq: page.nextSeq while it is defined.
+```
+
+`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
+returns the existing ID without provider execution or replaying plaintext. Changed
+input, trace or caller under the same key is a conflict. Model attempts are explicit
+and bounded to eight; SDK retries are disabled. Only provider failures trigger the
+next attempt. Abort, audit refusal and configuration errors do not. An admitted call
+whose process died stays claimed: inspect the receipt before choosing a new key.
+
+The agent retains its existing prompt, tools and loop. Both modes produce
+`invocation/started`, `provider/request`, `provider/response` and
+`invocation/finished` records through `read`. Each attempt has its own ID; response
+usage is counted once and keeps `unavailable` distinct from measured zero. Requested
+registry selection, sent adapter identity and effective provider identity are
+separate. Effective identity is null when not reported. A gateway's hidden retries
+are not visible as additional attempts.
+
+`currentModelInvocationAttempt()` returns the causal context inside a provider's
+`fetch` callback or streamed read. Use it to join a host transport audit to
+`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
+`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
+SDK payload hashes are not represented as hashes of HTTP wire bytes.
+
+Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
+hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
+`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
+bytes and is copied at construction. Keep it outside the event store/backups; retain
+the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
+(range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
+that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
+the answer itself is never cut. A receipt that cannot be written never changes an
+outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
+answer keeps its `text`. Request headers
+are excluded. Protect existing agent history independently: enabling receipts does
+not encrypt its ordinary conversation records.
+
+The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
+must implement its once-only check and append atomically, returning the original
+event on a duplicate key scoped by conversation and kind. A factory without this
+capability refuses receipt setup. The driver-backed implementation finds the keyed
+event by its identity through the driver's optional `events.find` — one index probe
+in SQLite — so admission costs the same on a long conversation as on a new one; a
+custom driver without `find` falls back to paging the log in one transaction.
+`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
+Invocation payload artifacts are keyed by their artifact id the same way.
+
+### Migration from direct SDK completions
+
+**Who must act:** applications opting into shared completion/agent receipts.
+Replace the direct `generateText` call with `invocations.complete`, configure host
+authorization and a retained payload key, and pass the same ledger in the agent's
+`invocations` option. Use the returned invocation ID and the paginated `read` method
+for receipt queries; do not import runtime internals. Available since 0.100.0;
+existing runtime configurations need no migration.
+
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -6922,7 +7070,12 @@ refusals are explicit; accepted ordered frames are never evicted.
 The absolute path's parent must already exist and be operator-controlled. One manager owns it via
 an exclusive `.lock`; new files use mode `0600` by default. `maxFiles` includes the active file,
 and a non-newline startup tail is rotated intact rather than guessed or repaired. An abrupt process
-death may leave the lock for an operator to remove only after proving the former owner is gone.
+death may leave a lock. The default `refuse` policy leaves recovery to the operator;
+`lock: 'reclaim-stale'` compares machine, boot and process birth identity before
+recovery. A reused PID cannot impersonate a modern owner. Legacy records with a
+live PID, foreign namespaces and unavailable identity refuse automatic recovery;
+see the upgrading guide for quiescent legacy recovery. The same mechanism owns the
+short-lived reclaim guard.
 
 `flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
 durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
@@ -7253,6 +7406,62 @@ holder — after which the heartbeat wins and the lock is abandoned. Temporary f
 the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
 
+## Recovering change subscriptions
+
+`changeSubscriptionResource` is an optional resource over a consumer-owned driver.
+It uses a finite declared key set, subscribes before reading, reconciles after
+reconnect and periodically repairs lost hints. `reconcileIntervalMs` is explicit;
+notifications alone cannot prove freshness. Within a key, hints coalesce into one
+trailing read and a failed read retries with backoff. Use the supplied
+`context.commit(() => publish(value))` after awaits to reject an obsolete connection.
+
+Drivers implement `connect(signal)` and return `subscribe({ signal, hint,
+disconnected })` plus `close()`. Subscribe must establish the notification boundary
+before resolving. A database LISTEN driver owns its connection, channels, decoding
+and transaction ordering; no SQL or database driver is included here. The resource
+owns reconnect, deadlines and shutdown. Drivers must honor abort. If one ignores it,
+its slot remains occupied until settlement; deadlines cannot safely manufacture
+successful cleanup or permit an overlapping connection.
+
+For watched reads, set `reconcileIntervalMs` on the existing `createWatchHub` rather
+than building a second read loop. Its per-key machinery is shared with managed
+subscriptions. Limits default to 1024 sources and 1024 subscribers per hub; set
+explicit finite values for larger workloads. Supply a server-verified admission
+scope to `attach` and abort it on logout, permission revocation or session replacement.
+The read callback receives the trusted scope as its third argument. A client owner
+ID in arguments is not authentication.
+
+## Multi-action notification delivery
+
+Opt into `delivery: { version, actions, project }` on `createNotificationOutbox`.
+The pure `actions(payload)` selector runs at enqueue; the versioned plan remains
+fixed throughout retry. Each `send` receives its action and a stable idempotency
+key; return a small JSON receipt such as a remote message or uploaded object ID.
+An action that returned is confirmed and is never sent again: a result that is not
+JSON, or does not fit the state's byte budget, is kept as `receipt: null` with
+`unrecorded: 'not-json' | 'too-large'` and reported to `onError`.
+`project(notification, receipts)` applies all confirmed results locally and must
+be idempotent. Checkpoints and the final projection timestamp live in the existing
+atomic StateStore; completed receipts retain them within retention/byte limits.
+
+This supports, for example, text plus attachment delivery with a local timeline
+projection, or upload plus publication with a local asset index. These are protocol
+examples, not claims of deployed consumer adoption. A failure in projection does
+not repeat confirmed sends. A crash after remote success but before receipt commit
+is ambiguous: the provider must deduplicate the action key or reconcile its result.
+A projection can also repeat if its completion checkpoint is lost.
+
+A plan keeps its actions from enqueue, so an older version needs only its
+projection to finish: a new executor lists it in `retiredVersions: { v1: project }`
+until the queue has drained. A plan version the executor does not know is reported
+to `onError` as `NotificationPlanVersionError` and waits — at least a poll interval,
+spending no attempt, without `classify` — for a process that knows it: the other
+side of a rolling deploy, the version a rollback returns to, or this one once it
+lists the version. Whole-state file and memory stores
+remain supported. Atomic enqueue with an unrelated business transaction is not
+provided by this contract; retain the application's transactional adapter when that
+boundary is required. Send and projection callbacks own their external deadlines.
+
 
 ==============================================================================
 # Guide: Optional process sandbox  (docs/guide/sandbox.md)
@@ -9728,6 +9937,63 @@ through `emitTo`; a broadcast through `realtime.to(room).emit` reaches the
 socket immediately, replay or not, so keep room traffic whose order matters
 relative to the snapshot on the registry.
 
+## Session-scoped watches and query cache
+
+Pass the captured login operation as `createWatchClient(contract, { transport,
+session })`. It adds a lifetime nonce to watch keys and detaches on invalidation;
+a late frame for a previous login cannot match a new client's key on the same socket.
+Both client and server must support the new optional `WatchKey.instance` field.
+The nonce is not authorization: the server still admits a verified identity and
+uses `hub.attach(subscriber, { key: verifiedScope, signal: revocationSignal })`.
+The scope key must change with session and permission boundaries.
+
+One scope and one question share one source and one read, however many client
+instances watch it: the hub routes each frame to every instance under its own
+key. A new tab of the same session costs a route, not a read.
+
+### Capacity
+
+A hub admits at most `maxSources` sources (1024) and `maxSubscribers` attached
+subscribers (1024); a client holds at most `maxKeys` keys (1024) and
+`maxListenersPerKey` listeners per key (128). Every excess is a refusal, never
+unbounded state: `open` answers `{ accepted: false, reason }` — including for a
+subscriber attached over capacity, whose `attach` returns a watcher that refuses
+every `open` — and a client's `subscribe` throws. A client handle takes its key
+when it subscribes, so handles a render creates and never subscribes cost
+nothing. A connection handler that throws closes that connection and is logged;
+the server goes on. A subscriber attached over capacity is not tracked: its
+refusals stand until it reconnects.
+
+A read that fails sends its subscribers `unavailable` / `source-error` with the
+`code` and `message` of an `AppError`, which is written for its caller. Any other
+error reaches only the hub's `logger`; the browser reads `The watched read failed`. Set larger finite limits for larger workloads, and
+`reconcileIntervalMs` when a lost invalidation must recover without a reconnect.
+
+`createCacheBridge` can bind watched handles directly:
+
+```ts
+const bridge = createCacheBridge({
+  socket, queryClient, handlers: {}, session,
+  watched: [{
+    handle: watches.list({ folderId }),
+    queryKey: ['items', session.id, folderId],
+    state: frame => showWatchState(frame),
+  }],
+})
+bridge.connect()
+```
+
+A value updates that exact query; non-live state marks it stale while retaining its
+value. The existing phases (`opening`, `live`, `unavailable`, `resync-required`)
+remain the status model. Do not replace unavailable data with an empty collection.
+Session invalidation removes bound queries. Include the session identity in query
+keys and guard any application-level side effects with that same operation.
+
+Use existing shared watches for paginated lists and selected-detail queries; bind
+each exact argument set to its query key. No global domain/query registry or new
+UI components are needed. Reconnect and revision/delta recovery remain owned by the
+watch client; silent lost notifications are repaired by hub reconciliation.
+
 
 ==============================================================================
 # Guide: Live data  (docs/guide/live.md)
@@ -13035,6 +13301,75 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.100.0
+
+### watch capacity and session/live/delivery adoption
+
+**Who must act:** watch consumers exceeding 1024 hub sources, 1024 hub subscribers,
+1024 client keys or 128 listeners per key. These previously unbounded collections
+now refuse excess admission. Choose explicit positive finite limits, for example:
+
+```ts
+// Before: no hub-wide capacity bounds.
+createWatchHub({ read, watchable });
+// After: explicitly budget a larger workload.
+createWatchHub({ read, watchable, maxSources: 4096, maxSubscribers: 4096 });
+// Client limits are configured independently.
+createWatchClient({ ...clientConfig, maxKeys: 2048, maxListenersPerKey: 256 });
+```
+
+The remaining steps apply only to applications opting into session lifetimes,
+scoped watched reads, managed subscriptions or multi-action notification delivery.
+Existing clients within the limits and single-send outboxes need no migration.
+
+Replace local session generation counters with one `createSessionScope`; share it
+with `createSessionCredentials`. Guard transport attempts, complete asynchronous
+operations and final synchronous delivery. Route credential persistence through
+one coordinator. Keep provider-specific error classification and bounded command
+retry in the application. Coordination is per client instance.
+
+Upgrade both watch endpoints before enabling session-scoped watches: strict older
+servers reject the new optional `WatchKey.instance`. Server-verified scope controls
+sharing; the client instance is only routing identity. Bind exact watched handles
+to session-qualified cache keys. Existing delta/reconnect behavior stays in place.
+For applications needing more than 1024 hub sources/subscribers or client keys, set
+explicit finite capacity options. Enable a reconciliation interval when lost hints
+must recover without a reconnect.
+
+For multi-action outboxes, enqueue new items with a versioned delivery plan and
+return small JSON receipts from `send`. Existing queued single-send items should
+be drained before enabling a delivery executor on that queue, or migrated under
+the store's atomic transition. When a new executor version ships, list the old
+version's projection in `delivery.retiredVersions` until its queued items drain;
+a plan version with no executor waits, reported to `onError` as
+`NotificationPlanVersionError` (from 0.100.1).
+Make projection idempotent. Provider idempotency/reconciliation remains necessary
+for a crash between remote success and checkpoint. These APIs are available starting with 0.100.0.
+
+### exclusive lock recovery
+
+New lock and reclaim-guard records include `owner.process`: kernel boot identity,
+process birth token and namespace. `readDiagnosticJournalLockDiagnosis(error)`
+adds `identity` to distinguish matched lifetime evidence, PID reuse, a different
+boot, an absent PID, a legacy record or unavailable identity. Legacy `alive` only
+means the PID is present; it does not prove that the recorded writer still exists.
+
+**Who must act:** deployments recovering a legacy lock with a reused live PID,
+or bundling file-lock consumers into a standalone Darwin executable. Legacy
+records cannot safely infer their missing boot/start identity from `acquiredAt`.
+Stop all writers to that resource, verify exclusive ownership, preserve the old
+lock for incident evidence outside the active lock path, and restart with the
+new package. Never delete a lock merely because it is old. New acquisitions
+write the modern record; no journal data migration is needed.
+
+Darwin distributions must retain the package's architecture-matched native
+`.node` asset for process birth measurement, as for contained filesystem access.
+If native/proc identity cannot be read, new locks explicitly record null and
+recovery refuses rather than treating unknown ownership as death. From 0.100.1 a
+Linux kernel without time namespaces (before 5.6) records the PID namespace alone
+instead of null, so its locks recover like any other. Existing
+`refuse` policy and the separately configured ownerless-file grace are unchanged.
+
 ## Released migration: 0.99.0
 
 ### structural alternatives in flattened tool schemas
@@ -13050,13 +13385,20 @@ Colliding object/array fields retain their complete structural alternatives:
 { type: ['object', 'array'] }
 // After: structural alternatives live inside the property schema.
 { anyOf: [
-  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
   { type: 'array', items: {
     type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
   } },
+  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
 ] }
 ```
 
+Alternatives come in kind order, independent of variant order. The same shape
+covers every collision of different kinds, scalars included: `string` against
+`string[]` becomes `{ anyOf: [{ type: 'array', items: { type: 'string' } }, { type:
+'string' }] }`. A nullable field keeps `null` in each alternative's `type`, and
+differing nested object unions remain nested `anyOf` inside the alternatives. Update
+snapshots to this order.
+
 Traverse each nested alternative when inspecting schemas and regenerate schema
 snapshots. Verify the actual manifest with the chosen provider. Keep flatten
 enabled when a top-level discriminated union needs to be advertised as an
@@ -17000,6 +17342,32 @@ can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
 
 ---
 
+### Session lifetime and credential coordination
+
+`createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
+creates a new login lifetime (including same-account relogin), `capture()` returns
+its `SessionOperation<T>`, `clear()` invalidates it, `stop()` permanently closes
+the host, and `owns(operation)` answers whether an operation is this scope's current
+one — `current()` alone cannot tell an operation of another scope. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
+`assertCurrent()`. `run(callback)` checks both success and failure across an await;
+`deliver(callback)` admits a synchronous final send/state change or returns false.
+`bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
+the complete client call in `run` too: headers are not the response body boundary.
+Expired work throws `SessionExpiredError`, not a refresh instruction; when the work
+itself failed, that failure is its `cause`.
+
+`createSessionCredentials` accepts `SessionCredentialsConfig`:
+`scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
+`storage.clear()`, `maxPendingWrites` (128), `refreshTimeoutMs` (30000, at most one
+hour) and `storageTimeoutMs` (30000, at most one hour): a storage call past it
+rejects and frees the queue, so `logout()` still clears; when the late call settles,
+storage is written again from memory, or cleared when nobody is logged in. `SessionCredentials` provides `login`, `logout`, `read(operation)` and
+`refresh(operation)`. Concurrent refresh calls in one generation share the same
+promise. Logout invalidates memory before its returned persistence promise settles.
+Storage errors and queue-capacity refusals reject; callers must handle them. All
+writes must pass through the same instance. There is no cross-process/tab lock,
+provider error classifier or automatic retry of arbitrary application callbacks.
+
 ## `stitchkit/contract`
 
 The contract layer alone — browser-and-server safe. All of this is also exported
@@ -17140,6 +17508,14 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 
 ---
 
+### Session-scoped watch lifetime
+
+`WatchClientConfig.session` captures a `SessionOperation`; `maxKeys` (1024) and
+`maxListenersPerKey` (128) bound retained subscriptions; a handle takes its key on
+`subscribe`, which is where capacity refuses. Its lifetime nonce travels
+in optional `WatchKey.instance`, preventing old-session frames from matching a new
+client on the same socket. This is routing identity, never authorization.
+
 ## `stitchkit/primitives`
 
 Browser-and-server-safe declarations for facts an application wants to define once. See the
@@ -17528,7 +17904,7 @@ cutovers are covered by the executable
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
-| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — owner alive, another machine, or a lock this host cannot attribute — read off the thrown `EEXIST` |
+| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
 | `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |
@@ -17631,6 +18007,53 @@ vocabulary with an event topic declared `mode: 'decision'`.
 → [ADR 0152](../decisions/0152-a-keyspace-is-memory-that-nothing-reaches-before-it-is-durable.md),
 [ADR 0153](../decisions/0153-a-watched-read-is-one-read-per-question.md).
 
+### Managed change subscriptions and scoped watches
+
+`changeSubscriptionResource` (`stitchkit/application`) accepts
+`ChangeSubscriptionConfig`: `id`, unique `keys` (1–128, at most 256 characters each),
+`connect(signal)`, `reconcile(key, context)`, required `reconcileIntervalMs` (10 ms–1 h),
+optional `timeoutMs` (30000; 1 ms–1 h), `backoff`, and `onError`.
+`ChangeConnection` supplies `subscribe({ signal, hint, disconnected })`, which completes subscription
+before the first read; `close()` releases it. `ChangeReconciliation` exposes `signal`
+and a synchronous `commit(callback)` guard against late publication. Drivers must
+honor cancellation. Uncooperative work retains its slot until settled instead of
+allowing overlapping connections/reads. Errors reach `onError`; no raw payload or
+connection string is logged by this resource. Recovery runs after reconnect and
+periodically even when no notification arrives.
+
+`WatchHubConfig` adds `maxSources` (1024), `maxSubscribers` (1024), and optional
+`reconcileIntervalMs` (10 ms–1 h). `hub.attach(subscriber, scope?)` accepts a
+`WatchAdmissionScope` containing a **server-verified** `key` (1–512 characters) and
+revocation `signal`. The key separates sharing and is the optional third argument
+of `read(operation, args, scope)`; a key's `instance` routes frames and never
+separates sources. Attached over `maxSubscribers`, a subscriber gets a watcher whose
+`open` refuses with `Watch subscriber capacity exceeded`; `attach` does not throw
+for capacity. It must represent account, session and permissions;
+never trust a client-supplied owner ID as that scope.
+
+
+
+### Notification action and projection receipts
+
+`NotificationOutboxConfig.delivery` accepts `NotificationDeliveryConfig`:
+immutable executor `version`, pure `actions(payload)` plan selector (1–128 unique
+names, each at most 128 characters), and idempotent `project(notification, receipts)`.
+`send` receives optional `action` and stable `idempotencyKey`, and returns a JSON
+remote receipt (void becomes null). A result that is not JSON or does not fit the
+byte budget is kept as `receipt: null` with `unrecorded: 'not-json' | 'too-large'`;
+the action stays confirmed and is not sent again. `retiredVersions` maps earlier
+plan versions to their `NotificationProjection` so queued items drain after an
+executor upgrade; an unknown version is reported to `onError` as
+`NotificationPlanVersionError` and waits, spending no attempt and not consulting
+`classify`, for an executor that knows it. `NotificationDeliveryStateSchema` validates the
+optional `NotificationDeliveryState` on queued items and completed receipts:
+`version`, `actions`, `receipts` and optional `projectedAt`. Checkpoints share the
+existing atomic StateStore and lease fence. Receipt retention and serialized byte
+budgets still apply. Single-send configuration remains valid without `delivery`.
+A remote result lost before its checkpoint may be sent again; provider idempotency
+or reconciliation is required. A projection may repeat after a crash before its
+checkpoint. Business-transaction enqueue and durable quarantine are not implied.
+
 ## `stitchkit/application/grammy`
 
 Isolated optional-peer lifecycle adapters. Importing `stitchkit/application`
@@ -17808,7 +18231,7 @@ Server-only optional application runtime. See the
 | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
-| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure, bounded dispatch and fenced stable occurrence identity (ADR 0202) |
+| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure (any other returned value delivers), `maxAttempts` (default 1000) per occurrence — a one-off ends `failed`, a recurring schedule skips to its next slot — bounded dispatch and fenced stable occurrence identity (ADR 0202) |
 | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
 | `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
 | `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
@@ -17963,6 +18386,35 @@ Managed effects and operator telemetry additionally export `AgentToolFenceConfig
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.
 
+### Completion and agent invocation receipts
+
+`createModelInvocationLedger` constructs a `ModelInvocationLedger` from
+`ModelInvocationConfig`: the existing store and model registry, a 32-byte payload
+key, required host authorization, optional bounded payload size and `onAttempt`.
+`complete(input, context, signal?)` executes only the supplied prompt, with no tools
+or framework instructions; repeated keys return the existing invocation ID. It
+resolves `{ invocationId, outcome, text?, receiptError? }`: `receiptError` says a
+receipt could not be written and never changes `outcome` or drops `text`.
+`read(input, context)` returns a bounded event page shared by agent and completion;
+`readPayload(input, context)` requires a separate authorization action to decrypt
+one protected artifact. See the [guide and migration example](../guide/agent-runtime.md#plain-completions-and-shared-invocation-receipts).
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `CompletionInvocationInputSchema` / `CompletionInvocationInput` | schema/type | strict prompt, model-attempt list, deadline, idempotency key and trace input |
+| `ModelInvocationTraceSchema` / `ModelInvocationTrace` | schema/type | operation, purpose, project, parent trace and optional experiment/case/profile |
+| `ModelInvocationRecordSchema` / `ModelInvocationRecord` | schema/type | discriminated invocation start/finish and per-attempt requested/sent/effective evidence |
+| `ModelInvocationAttemptContext` | type | conversation, operation, invocation, attempt, step and optional agent run identity |
+| `currentModelInvocationAttempt` | function | returns causal IDs inside the provider transport; undefined outside an invocation |
+
+The runtime `invocations` option takes this ledger and a trace callback; it requires
+the same store and preserves the existing tool loop. `AgentRuntimeStore.appendEventOnce`
+is an optional atomic capability required by receipt admission, and
+`AgentRuntimeStore.findEventOnce` reads the event it wrote by kind and key. Built-in
+stores supply both; custom adapters must honor the once-only transaction contract.
+A driver's optional `events.find(transaction, { conversationId, eventId })` makes
+both one lookup instead of a scan of the conversation log.
+
 ## `stitchkit/agent-runtime/testing`
 
 Credential-free provider and concurrency fixtures for Bun and Node tests.
@@ -18639,7 +19091,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); 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` |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 
 ---
@@ -19019,6 +19471,14 @@ For the rationale behind these APIs — why `Bun.serve` and not a framework, why
 two context types, why thin wrappers — see the
 [Architecture Decisions](../decisions/).
 
+### Watched handles in the query cache
+
+`CacheBridgeConfig.watched` accepts `WatchCacheBinding` entries with `handle`,
+`queryKey` and optional `state(frame)` observer. Include the session in query keys.
+`CacheBridgeConfig.session` fences events and removes bound queries when that login
+ends. Watch loss marks a query stale without triggering an independent refetch;
+recovery belongs to the watched read.
+
 ## `stitchkit/agent-runtime/sandbox`
 
 Optional server-only namespace sandbox. Exports: