stitchkit 0.94.0 → 0.94.1

package/llms/application.2.txt

@@ -4,8 +4,272 @@
 > `llms.txt` in this package.
 
 Parts of this slice:
-- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
-- `llms/application.2.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
+- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
+==============================================================================
+
+---
+title: Application migration recipes
+description: Executable patterns for moving database, poller, queue and operational publishing lifecycle into the managed application kernel.
+type: architecture
+status: active
+created: 2026-08-24
+updated: 2026-08-24
+---
+
+# Application migration recipes
+
+These recipes are the migration companion to the
+[managed application kernel](./application-kernel.md). Their canonical source is
+the packed-consumer fixture
+[`application-migration-recipes.ts`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/application-migration-recipes.ts):
+the consumer lane installs the package tarball, typechecks that file and runs it
+only through `stitchkit/application` exports.
+
+## Database connection
+
+Wrap connection allocation and readiness in `start`, and make `close` safe after
+partial setup. Stitchkit invokes cleanup for every attempted start, including a
+start that allocates a client and then rejects.
+
+```ts
+const database = defineManagedResource({
+  id: 'database',
+  async start({ signal, reportHealth }) {
+    await databaseClient.connect(signal)
+    await databaseClient.assertReady()
+    reportHealth('healthy')
+  },
+  close: () => databaseClient.close(),
+})
+```
+
+The application still owns the client, ORM configuration, transactions,
+migrations and reconnect policy. The executable recipe deliberately fails after
+allocation and proves one rollback close.
+
+## Long-running poller
+
+Return separate readiness and completion promises. Readiness says dependants may
+start; completion represents the whole background lifetime.
+
+```ts
+const poller = defineManagedResource({
+  id: 'poller',
+  start: ({ signal }) => ({
+    ready: providerPoller.ready,
+    completion: providerPoller.run(signal),
+  }),
+  stopAdmission: () => providerPoller.stop(),
+  drain: () => providerPoller.completion,
+  close: () => providerPoller.close(),
+})
+```
+
+Completion before readiness fails startup and rolls back. Completion after
+readiness removes application readiness. Provider cursor persistence, retry,
+backoff and restart policy remain application/provider concerns.
+
+## Queue consumer
+
+Acquire the application lease only after provider delivery/claim. If admission
+is already closed, reject the delivery through the provider's own nack/requeue
+primitive. Work admitted before shutdown releases its lease after ack/nack and
+therefore participates in application drain.
+
+```ts
+async function handleDelivery(delivery: Delivery) {
+  const lease = app.admission.acquire()
+  if (!lease) return delivery.nack({ requeue: true })
+  try {
+    await processClaim(delivery.claim)
+    await delivery.ack()
+  } catch (error) {
+    await delivery.nack({ requeue: shouldRetry(error) })
+    throw error
+  } finally {
+    lease.release()
+  }
+}
+```
+
+Stitchkit owns only process-local admission accounting and drain. Durable claims,
+visibility timeouts, deduplication, idempotency and retry classification remain
+in the queue/product layer.
+
+## Operational publisher
+
+Project anonymous aggregate activity, then feed absolute snapshots into the
+latest-value sink. A slow transport holds one write plus one replaceable latest
+revision rather than an unbounded event queue.
+
+```ts
+const publisher = createApplicationSnapshotSink({
+  write: (snapshot) => monitoring.publish(snapshot),
+})
+const activity = createActivityProjection({
+  id: 'generation',
+  stages: ['queued', 'running'],
+})
+const unsubscribe = activity.subscribe((snapshot) => {
+  publisher.publish(snapshot)
+})
+
+// cleanup boundary
+unsubscribe()
+publisher.publish(activity.getSnapshot())
+await publisher.close()
+```
+
+The monitoring backend, transport retry and cross-process aggregation remain
+outside Stitchkit. The executable recipe blocks revision 0, coalesces
+intermediate revisions, explicitly admits the final absolute snapshot after
+unsubscribe and proves that `close()` flushes revision 3. Do not rely on an
+asynchronous subscriber callback racing cleanup: publish `getSnapshot()` before
+closing the outer sink, so any older or duplicate late delivery is rejected as
+stale instead of dropping the final state.
+
+## Bound a handler and a local worker with one lease policy
+
+Use a bounded admission when two entry paths consume the same finite local
+capacity. Composing it with `application.admission` keeps readiness and shutdown
+as the upstream gate:
+
+```ts
+const work = createBoundedAdmission({
+  upstream: app.admission,
+  policy: {
+    global: { maxConcurrent: 4 },
+    perKey: { maxConcurrent: 1, maxKeys: 1_000 },
+  },
+})
+
+const fromHttp = (key: string, signal: AbortSignal) =>
+  work.run(key, (context) => render(context.signal), { signal, timeoutMs: 20_000 })
+
+const fromWorker = (key: string) =>
+  work.run(key, (context) => reconcile(context.signal))
+```
+
+A timeout in `fromHttp` does not free a permit while `render` remains active.
+At shutdown call `work.stopAdmission()` with the other admission owners and
+await `work.drain(...)`; the result reports the actual remainder.
+
+## Replace ad-hoc output and progress queues
+
+Ordered output and replaceable progress are separate declarations:
+
+```ts
+const lines = createBoundedChannel<string>({
+  policy: 'ordered', maxItems: 100, maxBytes: 1_000_000,
+  sizeOf: (line) => new TextEncoder().encode(line).byteLength,
+})
+
+const state = createBoundedChannel<{ revision: number; percent: number }>({
+  policy: 'latest', maxItems: 1, maxBytes: 64,
+  sizeOf: () => 64,
+})
+
+const lineResult = lines.offer('one durable-in-process ordering unit')
+const stateResult = state.offer({ revision: 2, percent: 50 })
+```
+
+Handle `refused` from `lines` at the protocol boundary; do not turn it into
+implicit loss. A `coalesced` state result is expected latest-value behaviour,
+not evidence that an ordered event was delivered. Neither channel is durable;
+persist first when restart replay is required.
+
+## Handing a handle to the resources that depend on it
+
+`dependsOn` carries ordering. To carry the object as well, return a `value` from
+`start` and read it with `context.use(...)`. This replaces the module-local
+`let handle: T | null` with the guard the graph makes unreachable.
+
+```ts
+const database = defineManagedResource({
+  id: 'database',
+  start: async () => ({ value: await connect(env.DATABASE_URL) }),
+})
+
+const worker = defineManagedResource({
+  id: 'worker',
+  dependsOn: [database],
+  start(context) {
+    const db = context.use(database)   // Connection — not Connection | null
+  },
+})
+```
+
+Declare the dependency with the **resource** whenever you intend to read from
+it: that is the form `use` can type, and it stops the declaration and the read
+from drifting. A string still expresses order on its own.
+
+The value is published when `start` resolves and stays readable from `activate`
+and from the shutdown phases. `use` refuses a resource that was not declared in
+`dependsOn` — that only ever worked by luck of declaration order — and refuses a
+resource that published nothing, which the compiler refuses too. The executable
+recipe proves both the read and the refusal.
+
+## Managed HTTP server
+
+The main resource of a web backend, and the one whose ownership rule is
+counter-intuitive: give `managedServerResource` a **thunk** and it creates the
+server during `start`, after its dependencies are ready. Give it an
+already-listening server and it adopts that one instead.
+
+```ts
+const http = managedServerResource({
+  id: 'http',
+  dependsOn: [database],
+  server: (context) => {
+    const db = context.use(database)
+    return createServer({ port: env.PORT, services: createServices(db) })
+  },
+})
+
+const app = createApplication({ id: 'service', resources: [database, http] })
+await app.start()   // the port is bound; the snapshot means it
+```
+
+The server resource publishes its `ManagedServerHandle`, so anything that needs
+the running server — a Socket.IO attachment, a URL to log, a probe — reads it
+with `context.use(http)` rather than through a module-local.
+
+The factory itself receives `ManagedResourceContext` too. It can read only the
+dependencies declared on the server resource and shares the graph's startup
+signal. A dependency failure prevents the factory from binding; a factory
+rejection is rolled back without invoking the factory a second time.
+
+Do not spread this resource over your own `start` to control creation order:
+that shape exists only as a workaround for the version whose `start` was empty,
+and `dependsOn` now expresses the order directly. The executable recipe binds a
+real port, proves a request reaches it after `start()` resolves, and proves the
+port is closed after `shutdown()`.
+
+## Deletion checklist
+
+After the cutover, remove the old generic lifecycle path completely:
+
+- duplicate `process.on(...)` handlers and shutdown promise caches;
+- manual readiness waiters and resource close fan-out;
+- raw interval handles, overlap flags and timer drain code;
+- global in-flight counters and waiter sets replaced by application leases;
+- progress delta queues replaced by absolute snapshot publishing.
+
+Keep the product code that still owns durable state and policy:
+
+- database schema, transactions and migrations;
+- queue claims, ack/nack, deduplication and external-effect idempotency;
+- provider cursor, retry/backoff and credentials;
+- monitoring transport configuration and durable retention;
+- process exit code, hard-exit and deployment/supervisor policy.
+
+Run the old and new lifecycle paths separately during development if needed,
+but do not ship both. Before cutover, verify there is exactly one signal binding,
+one timer owner, one admission gate and one resource cleanup chain.
 
 ==============================================================================
 # API reference: `stitchkit/application`  (docs/api/reference.md)

package/llms/application.txt

@@ -5,8 +5,8 @@
 > Continues in `llms/application.2.txt`.
 
 Parts of this slice:
-- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
-- `llms/application.2.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
+- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -208,6 +208,12 @@ answered the question, and the answer stands. (It used to be overwritten — and
 the example above hides that, because `healthy` is the same value that
 overwrote it.)
 
+**Reporting the same health again is not a change.** A resource may confirm its
+health on a timer; a report with the value it already reported publishes
+nothing — no new revision, no `changedAt`, no subscriber call. A change of value
+publishes once, as does the first report that confirms the `healthy` the kernel
+assumed at readiness.
+
 **A resource is required unless you write `required: false`.** That default is
 what makes the next sentence bite.
 
@@ -878,267 +884,3 @@ so a scheduler stall on a loaded host cannot pull a live lock from under its
 holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
 the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
-
-==============================================================================
-# Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
-==============================================================================
-
----
-title: Application migration recipes
-description: Executable patterns for moving database, poller, queue and operational publishing lifecycle into the managed application kernel.
-type: architecture
-status: active
-created: 2026-08-24
-updated: 2026-08-24
----
-
-# Application migration recipes
-
-These recipes are the migration companion to the
-[managed application kernel](./application-kernel.md). Their canonical source is
-the packed-consumer fixture
-[`application-migration-recipes.ts`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/application-migration-recipes.ts):
-the consumer lane installs the package tarball, typechecks that file and runs it
-only through `stitchkit/application` exports.
-
-## Database connection
-
-Wrap connection allocation and readiness in `start`, and make `close` safe after
-partial setup. Stitchkit invokes cleanup for every attempted start, including a
-start that allocates a client and then rejects.
-
-```ts
-const database = defineManagedResource({
-  id: 'database',
-  async start({ signal, reportHealth }) {
-    await databaseClient.connect(signal)
-    await databaseClient.assertReady()
-    reportHealth('healthy')
-  },
-  close: () => databaseClient.close(),
-})
-```
-
-The application still owns the client, ORM configuration, transactions,
-migrations and reconnect policy. The executable recipe deliberately fails after
-allocation and proves one rollback close.
-
-## Long-running poller
-
-Return separate readiness and completion promises. Readiness says dependants may
-start; completion represents the whole background lifetime.
-
-```ts
-const poller = defineManagedResource({
-  id: 'poller',
-  start: ({ signal }) => ({
-    ready: providerPoller.ready,
-    completion: providerPoller.run(signal),
-  }),
-  stopAdmission: () => providerPoller.stop(),
-  drain: () => providerPoller.completion,
-  close: () => providerPoller.close(),
-})
-```
-
-Completion before readiness fails startup and rolls back. Completion after
-readiness removes application readiness. Provider cursor persistence, retry,
-backoff and restart policy remain application/provider concerns.
-
-## Queue consumer
-
-Acquire the application lease only after provider delivery/claim. If admission
-is already closed, reject the delivery through the provider's own nack/requeue
-primitive. Work admitted before shutdown releases its lease after ack/nack and
-therefore participates in application drain.
-
-```ts
-async function handleDelivery(delivery: Delivery) {
-  const lease = app.admission.acquire()
-  if (!lease) return delivery.nack({ requeue: true })
-  try {
-    await processClaim(delivery.claim)
-    await delivery.ack()
-  } catch (error) {
-    await delivery.nack({ requeue: shouldRetry(error) })
-    throw error
-  } finally {
-    lease.release()
-  }
-}
-```
-
-Stitchkit owns only process-local admission accounting and drain. Durable claims,
-visibility timeouts, deduplication, idempotency and retry classification remain
-in the queue/product layer.
-
-## Operational publisher
-
-Project anonymous aggregate activity, then feed absolute snapshots into the
-latest-value sink. A slow transport holds one write plus one replaceable latest
-revision rather than an unbounded event queue.
-
-```ts
-const publisher = createApplicationSnapshotSink({
-  write: (snapshot) => monitoring.publish(snapshot),
-})
-const activity = createActivityProjection({
-  id: 'generation',
-  stages: ['queued', 'running'],
-})
-const unsubscribe = activity.subscribe((snapshot) => {
-  publisher.publish(snapshot)
-})
-
-// cleanup boundary
-unsubscribe()
-publisher.publish(activity.getSnapshot())
-await publisher.close()
-```
-
-The monitoring backend, transport retry and cross-process aggregation remain
-outside Stitchkit. The executable recipe blocks revision 0, coalesces
-intermediate revisions, explicitly admits the final absolute snapshot after
-unsubscribe and proves that `close()` flushes revision 3. Do not rely on an
-asynchronous subscriber callback racing cleanup: publish `getSnapshot()` before
-closing the outer sink, so any older or duplicate late delivery is rejected as
-stale instead of dropping the final state.
-
-## Bound a handler and a local worker with one lease policy
-
-Use a bounded admission when two entry paths consume the same finite local
-capacity. Composing it with `application.admission` keeps readiness and shutdown
-as the upstream gate:
-
-```ts
-const work = createBoundedAdmission({
-  upstream: app.admission,
-  policy: {
-    global: { maxConcurrent: 4 },
-    perKey: { maxConcurrent: 1, maxKeys: 1_000 },
-  },
-})
-
-const fromHttp = (key: string, signal: AbortSignal) =>
-  work.run(key, (context) => render(context.signal), { signal, timeoutMs: 20_000 })
-
-const fromWorker = (key: string) =>
-  work.run(key, (context) => reconcile(context.signal))
-```
-
-A timeout in `fromHttp` does not free a permit while `render` remains active.
-At shutdown call `work.stopAdmission()` with the other admission owners and
-await `work.drain(...)`; the result reports the actual remainder.
-
-## Replace ad-hoc output and progress queues
-
-Ordered output and replaceable progress are separate declarations:
-
-```ts
-const lines = createBoundedChannel<string>({
-  policy: 'ordered', maxItems: 100, maxBytes: 1_000_000,
-  sizeOf: (line) => new TextEncoder().encode(line).byteLength,
-})
-
-const state = createBoundedChannel<{ revision: number; percent: number }>({
-  policy: 'latest', maxItems: 1, maxBytes: 64,
-  sizeOf: () => 64,
-})
-
-const lineResult = lines.offer('one durable-in-process ordering unit')
-const stateResult = state.offer({ revision: 2, percent: 50 })
-```
-
-Handle `refused` from `lines` at the protocol boundary; do not turn it into
-implicit loss. A `coalesced` state result is expected latest-value behaviour,
-not evidence that an ordered event was delivered. Neither channel is durable;
-persist first when restart replay is required.
-
-## Handing a handle to the resources that depend on it
-
-`dependsOn` carries ordering. To carry the object as well, return a `value` from
-`start` and read it with `context.use(...)`. This replaces the module-local
-`let handle: T | null` with the guard the graph makes unreachable.
-
-```ts
-const database = defineManagedResource({
-  id: 'database',
-  start: async () => ({ value: await connect(env.DATABASE_URL) }),
-})
-
-const worker = defineManagedResource({
-  id: 'worker',
-  dependsOn: [database],
-  start(context) {
-    const db = context.use(database)   // Connection — not Connection | null
-  },
-})
-```
-
-Declare the dependency with the **resource** whenever you intend to read from
-it: that is the form `use` can type, and it stops the declaration and the read
-from drifting. A string still expresses order on its own.
-
-The value is published when `start` resolves and stays readable from `activate`
-and from the shutdown phases. `use` refuses a resource that was not declared in
-`dependsOn` — that only ever worked by luck of declaration order — and refuses a
-resource that published nothing, which the compiler refuses too. The executable
-recipe proves both the read and the refusal.
-
-## Managed HTTP server
-
-The main resource of a web backend, and the one whose ownership rule is
-counter-intuitive: give `managedServerResource` a **thunk** and it creates the
-server during `start`, after its dependencies are ready. Give it an
-already-listening server and it adopts that one instead.
-
-```ts
-const http = managedServerResource({
-  id: 'http',
-  dependsOn: [database],
-  server: (context) => {
-    const db = context.use(database)
-    return createServer({ port: env.PORT, services: createServices(db) })
-  },
-})
-
-const app = createApplication({ id: 'service', resources: [database, http] })
-await app.start()   // the port is bound; the snapshot means it
-```
-
-The server resource publishes its `ManagedServerHandle`, so anything that needs
-the running server — a Socket.IO attachment, a URL to log, a probe — reads it
-with `context.use(http)` rather than through a module-local.
-
-The factory itself receives `ManagedResourceContext` too. It can read only the
-dependencies declared on the server resource and shares the graph's startup
-signal. A dependency failure prevents the factory from binding; a factory
-rejection is rolled back without invoking the factory a second time.
-
-Do not spread this resource over your own `start` to control creation order:
-that shape exists only as a workaround for the version whose `start` was empty,
-and `dependsOn` now expresses the order directly. The executable recipe binds a
-real port, proves a request reaches it after `start()` resolves, and proves the
-port is closed after `shutdown()`.
-
-## Deletion checklist
-
-After the cutover, remove the old generic lifecycle path completely:
-
-- duplicate `process.on(...)` handlers and shutdown promise caches;
-- manual readiness waiters and resource close fan-out;
-- raw interval handles, overlap flags and timer drain code;
-- global in-flight counters and waiter sets replaced by application leases;
-- progress delta queues replaced by absolute snapshot publishing.
-
-Keep the product code that still owns durable state and policy:
-
-- database schema, transactions and migrations;
-- queue claims, ack/nack, deduplication and external-effect idempotency;
-- provider cursor, retry/backoff and credentials;
-- monitoring transport configuration and durable retention;
-- process exit code, hard-exit and deployment/supervisor policy.
-
-Run the old and new lifecycle paths separately during development if needed,
-but do not ship both. Before cutover, verify there is exactly one signal binding,
-one timer owner, one admission gate and one resource cleanup chain.

package/llms/cli.2.txt

@@ -0,0 +1,80 @@
+# stitchkit/cli — stitchkit docs slice, part 2 of 2
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/cli.txt`: Guide: CLI  (docs/guide/cli.md)
+- `llms/cli.2.txt`: API reference: `stitchkit/cli`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/cli`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/cli`
+
+Server-only. Composes contract/runtime managed operations and CLI-only native
+commands into one command-line program. Light by design: needs neither the MCP
+SDK nor the `ai` peer.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createCli` | function | build and run a CLI from contracts — [guide](../guide/cli.md) |
+| `defineCliCommand` | function | define one Zod-typed CLI-only executable command with optional validated-result presentation/exit policy |
+| `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
+| `routeCliArgv` | function | select the command out of argv without duplicating the global-option grammar (advanced) |
+| `extractCliGlobalOptions` | function | lift the application's own global options out of argv before routing (advanced) |
+| `coerceJsonArgs` | function | the second half of `parseCliArgs` — parse array/object values a consumer sends itself, without the `stitchkit/tools` barrel |
+| `CliArgumentError` | class | the refusal `parseCliArgs` and the view flags raise; a CLI reports it and exits `2` |
+| `renderCliView` | function | compute an aggregate over a result (`--count-by`, `--sum`, `--top`, `--table`) — [guide](../guide/cli.md#aggregate-views) |
+| `createCliProfileStore` | function | named `0600` credential profiles resolved by name, with the never-substitute rule built in — [guide](../guide/cli.md#named-profiles) |
+| `CliProfileError` | class | an `AppError` refusing a named profile that is missing, unreadable or shared between users |
+| `renderCliInstaller` | function | generate the one-line installer from a build manifest, with the URL and digest substituted — [guide](../guide/cli.md#distribution-and-self-update) |
+| `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
+| `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
+| `assertCliPublishable` | function | refuse republishing one version from a different commit — takes one manifest or every manifest already published, because the promise a version makes does not stop at a channel boundary |
+| `rollbackCliUpdate` / `CliRollbackConfig` / `RolledBackCliUpdate` | function / _types_ | put the kept previous build back, digest-checked first and written by the same atomic rename the update uses |
+| `signCliManifest` / `verifyCliManifest` / `cliManifestSigningPayload` | function | Ed25519 over `{name, version, commit, builtAt, assets[]}` — every asset's digest included, so the chain closes on the file that executes |
+| `cliSignatureAccepted` / `CliSignatureVerdict` | function / _type_ | `valid` \| `unenforced` \| `missing` \| `unknown-key` \| `invalid`; `unenforced` keeps an unpinned build updating while making the absence of a check visible |
+| `CliTrustRoot` / `CliSigningKey` / `CliBuildSignature` / `CliBuildSignatureSchema` | _types_ / schema | the keys a build trusts, by id, and the detached signature a manifest carries |
+| `selectCliBuildAsset` | function | the asset for one target, or `undefined` |
+| `currentCliBuildTarget` | function | `{ platform, arch }` of the running process |
+| `formatCliBuildStamp` | function | one line saying what the running build is |
+| `compareCliVersions` | function | compare two versions, or `undefined` when they are not comparable |
+| `CliBuildManifestSchema` / `CliBuildManifest` | schema / _type_ | name, version, commit, build time and assets |
+| `CliBuildAssetSchema` / `CliBuildAsset` | schema / _type_ | one download; `size` and `sha256` describe the **decompressed** bytes |
+| `CliBuildTargetSchema` / `CliBuildTarget` | schema / _type_ | `{ platform, arch }` |
+| `CliBuildStampSchema` / `CliBuildStamp` | schema / _type_ | the version/commit/build time carried inside a binary |
+| `CliInstallerConfig` | _type_ | manifest, binary name, default install directory, and an optional `asset` — omit it for one script that selects the target by `uname` |
+| `CliUpdateCheckConfig` / `CliUpdateCheck` | _type_ | check inputs, and its four answers — `skipped`, `current`, `outdated`, `unknown` |
+| `CliUpdateApplyConfig` / `AppliedCliUpdate` | _type_ | apply inputs — including `verify`, run on an executable candidate beside the target before the backup and the replacement, within `verifyTimeoutMs` — and the replaced path, byte count and digest |
+| `CliProfileStore` / `CliProfileStoreConfig` / `ResolvedCliProfile` | _type_ | the profile store, its directory/schema/hint config, and one resolution |
+| `CliResultView` | _type_ | the requested view — `count`, `sum`, or `records` (ordered and/or table-rendered) |
+| `CliViewOutput` | _type_ | a JSON value, or the one human-facing text shape |
+| `CliGlobalOptionsParse` | _type_ | `{ argv, globals }` returned by `extractCliGlobalOptions` |
+| `CliArgvRoute` | _type_ | `{ command, commandArgv, topLevelHelp, version, error? }` returned by `routeCliArgv` |
+| `pollUntilDone` | function | the generic `--wait` poller (advanced) |
+| `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
+| `cliExitCode` | function | the exit code a result earns, from the same table, without writing anything — so an in-process run and the printed path cannot disagree |
+| `createCliInvoker` / `CliInvoker` / `CliInvokerConfig` / `CliInvocationResult` / `CliInvokerCommand` / `cliInvocationResult` | function / _types_ | compile the managed surface once and run parsed calls against it in process — no argv round-trip, no child process, no writing |
+| `defineCliStreamCommand` / `CliStreamCommandConfig` / `CliStreamAnswer` / `CliStreamHooks` / `runCliStream` | function / _types_ | one operation per JSON line of stdin, answered with the same `id`; a bad line answers and the stream continues |
+| `defineCliBatchCommand` / `CliBatchCommandConfig` | function / _type_ | the same loop, resumable: a recorded line replays, a line whose content changed under the same id is refused |
+| `readCliCheckpoint` / `writeCliCheckpoint` / `CliCheckpoint` / `CliCheckpointEntry` | function / _types_ | the batch's record — id plus a digest of the line, written by atomic rename after every line |
+| `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
+| `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
+| `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
+| `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
+| `CliCommandDefinition` | _type_ | native command definition union |
+| `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
+| `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |
+| `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
+| `CliCommandContext` | _type_ | parsed input, framework run options, the application's `globals` and stdout/stderr writers |
+| `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
+| `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
+| `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |
+| `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
+| `PollParams` | _type_ | params for `pollUntilDone` |
+| `CliWriters` | _type_ | stdout/stderr sinks for `emitResult` |
+| `EmitOptions` | _type_ | options for `emitResult` |
+
+---