stitchkit 0.98.2 → 0.100.0

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 43 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 43 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 43 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)
@@ -3959,14 +4000,15 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. When the kinds genuinely differ, the flat projection keeps
-every provable kind in a deterministic JSON Schema type array — for example
-`type: ['string', 'array']` — while dropping constraints that are not sound for
-all branches. Nested `oneOf` / `anyOf` values still contribute their provable
-base kinds without reintroducing union keywords. Only a branch whose kind is
+bare description. Scalar collisions keep every provable kind in a deterministic
+JSON Schema type array. If any alternative is an object or array, the property
+retains distinct structural alternatives in `anyOf`: object properties, typed
+array items, bounds and nullable values remain available to the model. The
+containing discriminated union still becomes one object; flat mode does not
+promise to remove every nested union keyword. Only a branch whose kind is
 actually unknowable, such as a free-form schema or unresolved reference, leaves
 the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
-and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
+and [0205](../decisions/0205-flat-tool-collisions-retain-structural-alternatives.md).
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -3975,8 +4017,8 @@ Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
 Use the default `flattenUnionInput: false` when the model must see the exact
-relationship between a discriminator and each branch. The flat type array is a
-sound set of possible JSON kinds, not a reconstruction of those correlations.
+relationship between a discriminator and each branch. Joined property schemas
+describe allowed values without reconstructing those correlations.
 
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the
@@ -6272,6 +6314,100 @@ 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 is capped at 1 MiB. 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 reads bounded
+pages under one transaction, without another table or database.
+
+### 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. This API is unreleased; it is
+not present in 0.99.0. Existing runtime configurations need no migration.
+
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -6921,7 +7057,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
@@ -7252,6 +7393,55 @@ 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.
+`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 new executor version must explicitly migrate or terminally classify incompatible
+queued plans. Existing `classify`/`onDropped` handles terminal items; a durable
+quarantine is the application's responsibility. 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)
@@ -9727,6 +9917,41 @@ 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.
+
+`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)
@@ -13034,6 +13259,99 @@ 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. Preserve executor versions until their queues drain.
+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. Existing
+`refuse` policy and the separately configured ownerless-file grace are unchanged.
+
+## Released migration: 0.99.0
+
+### structural alternatives in flattened tool schemas
+
+**Who must act:** applications using `flattenUnionInput: true` with schema
+walkers, snapshots or provider restrictions that assume there is no nested
+`anyOf`. Applications without that assumption need only update the dependency.
+
+Colliding object/array fields retain their complete structural alternatives:
+
+```ts
+// Before: loses both field vocabulary and array items.
+{ 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'],
+  } },
+] }
+```
+
+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
+object; do not erase `items` or introduce consumer-specific schema patches.
+The root object, discriminator enum, requiredness hints and strict runtime
+contract validation are unchanged. See ADR 0205.
+
 ## Released migration: 0.98.0
 
 ### automatic stdin availability
@@ -16970,6 +17288,28 @@ 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, and `stop()` permanently closes
+the host. 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.
+
+`createSessionCredentials` accepts `SessionCredentialsConfig`:
+`scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
+`storage.clear()`, `maxPendingWrites` (128), and `refreshTimeoutMs` (30000, at most one
+hour). `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
@@ -17110,6 +17450,13 @@ 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. 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
@@ -17498,7 +17845,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 |
@@ -17601,6 +17948,44 @@ 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)`. 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). `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`
@@ -17933,6 +18318,30 @@ 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.
+`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. Built-in stores
+supply it; custom adapters must honor its once-only transaction contract.
+
 ## `stitchkit/agent-runtime/testing`
 
 Credential-free provider and concurrency fixtures for Bun and Node tests.
@@ -18609,7 +19018,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 |
 
 ---
@@ -18989,6 +19398,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:

package/llms.txt

@@ -9,10 +9,10 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
-- **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
-- **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
-- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 44.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 37.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 15.7 KB
+- **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
+- **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
+- **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.1 KB
@@ -20,9 +20,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 9.3 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 42.7 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 44.3 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 43.4 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.4 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 41.3 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 32.0 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.4 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.1 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 33.8 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.2 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 4.1 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 4.9 KB
@@ -30,7 +30,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
 - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
 - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
-- **stitchkit/application**: [llms/application.txt](llms/application.txt) 44.6 KB → [llms/application.2.txt](llms/application.2.txt) 32.9 KB
+- **stitchkit/application**: [llms/application.txt](llms/application.txt) 46.6 KB → [llms/application.2.txt](llms/application.2.txt) 37.2 KB
 - **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 2.3 KB
 - **stitchkit/application/opentelemetry**: [llms/application-opentelemetry.txt](llms/application-opentelemetry.txt) 1.6 KB
 - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
@@ -52,9 +52,10 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.72.0 → 0.98.0**: [llms/upgrading-0.72.0-0.98.0.txt](llms/upgrading-0.72.0-0.98.0.txt) 44.8 KB
-- **Upgrading 0.59.0 → 0.71.0**: [llms/upgrading-0.59.0-0.71.0.txt](llms/upgrading-0.59.0-0.71.0.txt) 45.6 KB
-- **Upgrading 0.37.0 → 0.58.0**: [llms/upgrading-0.37.0-0.58.0.txt](llms/upgrading-0.37.0-0.58.0.txt) 40.0 KB
+- **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 44.3 KB
+- **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
+- **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
+- **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.98.2",
+  "version": "0.100.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",