stitchkit 0.113.3 → 0.114.0

package/llms/{upgrading-0.61.0-0.74.0.txt → upgrading-0.62.0-0.78.0.txt}

@@ -1,14 +1,148 @@
-# Upgrading 0.61.0 → 0.74.0 — stitchkit docs slice
+# Upgrading 0.62.0 → 0.78.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.62.0 → 0.78.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.61.0 → 0.74.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.62.0 → 0.78.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.78.0
+
+Two mechanical edits. Find them both:
+
+```bash
+rg -n "createDecisionPipeline|createDiagnosticJournal" --glob '*.ts' --glob '*.tsx'
+```
+
+**1. `createDecisionPipeline` takes a deadline.**
+
+```ts
+// before
+createDecisionPipeline([policyA, policyB])
+// after
+createDecisionPipeline([policyA, policyB], { policyTimeoutMs: 2_000 })
+```
+
+Pick a number your slowest policy comfortably beats. There is no default on
+purpose: a policy that never settles hangs every caller of the operation it
+guards, and the framework has no basis for choosing that number for you.
+
+Past the deadline — and on a throw, and on a non-decision — the pipeline raises
+`DecisionPolicyError` naming the policy, with the trace so far. If you already
+catch that for a bad return value, you now catch two more cases with it.
+
+**2. `createDiagnosticJournal` moved.**
+
+```ts
+// before
+import { createDiagnosticJournal } from 'stitchkit/application'
+// after
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+```
+
+Only the factory moved. `DiagnosticJournalConfig`, every
+`DiagnosticJournal*Schema` and `readDiagnosticJournalLockDiagnosis` stay where
+they were.
+
+**If you restart resources**, nothing to change — but three things that did not
+work now do: a managed schedule can be restarted, a restarted keyspace accepts
+writes again, and a restarted managed server is actually shut down at exit. If
+you pass `managedServerResource` a server *instance*, a restart is now refused
+by name; pass a factory (`server: (context) => …`) to restart it.
+
+## Released migration: 0.77.0
+
+Two type renames, and only if you named them. Nothing runtime moved.
+
+```bash
+rg -n "EventDecision|EventUndecided" --glob '*.ts' --glob '*.tsx'
+```
+
+```ts
+// before
+import type { EventDecision, EventUndecided } from 'stitchkit/live'
+// after
+import type { PolicyDecision, UndecidedOutcome } from 'stitchkit/live'
+```
+
+The shapes are identical — `{ outcome: 'allow' } | { outcome: 'deny', reason } | { outcome: 'defer' }`
+and `'allow' | 'deny'`. If you only ever *return* decisions from listeners and never named the
+type, the search above finds nothing and there is nothing to do.
+
+They were renamed because `createDecisionPipeline` (new in this release) votes with exactly the
+same three outcomes, and two identical types under two names is the thing that makes a search for
+either one return half the truth.
+
+## Released migration: 0.76.0
+
+One change, and only if you hand `createWatchClient` a transport you wrote yourself.
+
+```bash
+rg -n "createWatchClient" --glob '*.ts'
+```
+
+If the `transport:` you pass is a bound realtime client — `bindRealtimeClient(...)` or
+`createRealtimeClient(...)` — there is nothing to do: it already carries
+`onConnectionChange`. If it is an object you assembled, add the fourth member:
+
+```ts
+onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void
+```
+
+It is required because the client recovers through it: on a drop it publishes
+`unavailable` to subscribers and forgets what was opened, and on a fresh
+connection it re-opens every key that still has a listener. Without it a watch
+stays "open" on the client after a server restart while the hub remembers
+nothing, and the face stops updating without saying so.
+
+## Released migration: 0.75.0
+
+Two mechanical renames and one option that has to move. Nothing about a passing
+request changes.
+
+### 1. A route group's `onRequest`
+
+```bash
+rg -n "hooks:\s*\{[^}]*onRequest" --glob '*.ts'
+```
+
+Any match **inside a `groups: [...]` entry** must move. The hook was accepted and
+never dispatched, so the behaviour you have today is "no hook"; the fix is to
+decide which one you meant:
+
+```ts
+// refuse before dispatch, for the whole server
+createServer({ groups, hooks: { onRequest: gate } });
+
+// gate this group once the endpoint is known
+groups: [{ pathPrefix: '/admin', services, hooks: { authorize: gate } }]
+```
+
+A group that still declares `onRequest` fails at startup with that message.
+
+### 2. The SQLite boundary type
+
+```bash
+rg -l "AgentRuntimeSqlite(Database|Statement|Value)" | xargs sed -i \
+  -e 's/AgentRuntimeSqliteDatabase/SqliteDatabase/g' \
+  -e 's/AgentRuntimeSqliteStatement/SqliteStatement/g' \
+  -e 's/AgentRuntimeSqliteValue/SqliteValue/g'
+```
+
+Type-only: the same three methods, the same structural compatibility with
+`bun:sqlite` and a `node:sqlite` wrapper, imported from the same entrypoints.
+`initializeAgentRuntimeSqlite` keeps its name — it really is the agent runtime's
+schema.
+
+### 3. Nothing else
+
+`stitchkit/live`, the watch hub, the keyspace and the trust fence are all
+additive. Adopt them when you want them; the guide is
+[Live data](./live.md).
+
 ## Released migration: 0.74.0
 
 One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
@@ -957,140 +1091,3 @@ exhaustively on any of those enums, add the arm** — that is the part of this
 release that can break a build rather than a behaviour. The record itself is
 kept: it is excluded from the projection, not deleted, so an operator can still
 see what was thrown away.
-
-## Released migration: 0.61.0
-
-Three behaviour changes between versions. None moves an export — the surface is
-strictly additive — and all three change what a running system does, which is
-what this heading is for.
-
-### A failed `start()` now drains before it rejects
-
-The rollback of a failed startup used to close every resource with a zero
-budget: it returned almost at once, by severing requests the server had already
-accepted. It now spends the application's shutdown budget, so a request already
-in flight is answered rather than killed.
-
-**What to check.** Nothing, if a failed startup has nothing in flight — the
-rollback still returns immediately. The case to think about is a request that
-never finishes: a hung upstream, a client ignoring a close frame, a streaming
-subscription. Under the default 30s grace and 5s force, a `start()` that used to
-reject in milliseconds can now take 35 seconds to reject.
-
-If a fast failure matters more than draining — a supervisor waiting to restart,
-a boot check in CI — declare a smaller budget. The same field is the default for
-`shutdown()` with no options, so this is one decision, not two:
-
-```ts
-// before
-createApplication({ id: 'app', resources })
-
-// after
-createApplication({
-  id: 'app',
-  resources,
-  shutdown: { gracePeriodMs: 5_000, forceTimeoutMs: 1_000 },
-})
-```
-
-The budget is a real bound: a `close` that never returns is abandoned when it
-runs out and reported as a `close` failure, and the startup error remains the
-`cause` of the `AggregateError` `start()` rejects with. → ADR 0107
-
-### A refused realtime frame now answers its sender
-
-A frame that fails the receiver's `args` schema used to be dropped where it
-landed. If the event carries an acknowledgement, the receiver now answers it
-with a reserved envelope and the sender's `request()` rejects at once with
-`RealtimeRequestRejectedError`. → ADR 0106
-
-**What to check before you upgrade one half of a distributed pair.** Look at the
-`ack` schemas on the OLDER peer:
-
-```ts
-// safe: a contract-first acknowledgement refuses the envelope, so the older
-// peer raises RealtimeRequestInvalidAcknowledgementError at once instead of
-// waiting out its deadline. Different error, still an error, and sooner.
-ack: z.object({ stored: z.boolean() })
-
-// NOT safe: a schema that validates nothing accepts the refusal AS A VALUE.
-// The older peer reads a refusal as a successful acknowledgement — silently.
-ack: z.unknown()
-ack: z.looseObject({})
-```
-
-If any acknowledgement on the older side is permissive, tighten it before the
-rollout, or upgrade both halves together.
-
-Also: the receiver now invokes the peer's raw acknowledgement callback for a
-refused frame, including when the peer is a plain Socket.IO client. That
-callback previously could not run on a refused frame and now can.
-
-`RealtimeRejectedEvent['reason']` gained `'rejected-by-peer'`. If you `switch`
-over it exhaustively with an `assertNever` default, that stops compiling — add
-the case.
-
-### Two smaller behaviour changes, easy to miss
-
-**`streamSSE`'s `cancel` no longer awaits the generator.** Teardown is now
-unordered relative to request completion. If your generator releases a resource
-in `return()`/`finally` — a temp file, a pooled connection — and anything
-downstream assumed that had finished by the time the response settled, it no
-longer has. Release in the generator's own `finally` and do not depend on the
-ordering.
-
-**A `socket.io-client` peer that cannot load no longer kills the process.** With
-`onConnectError` configured, the failure is delivered there with
-`terminal: true` instead of crashing. If your handler logs and moves on, you now
-have a live process whose client will never connect, where a supervisor used to
-restart it. Treat `terminal: true` as fatal if that is what you want.
-
-### `reportHealth` inside `start` is no longer discarded
-
-Becoming ready assigned `healthy` unconditionally, throwing away whatever a
-resource reported during `start`. It is now kept, and only a resource that
-reported nothing is assumed healthy.
-
-**How to find what this touches:** grep your `start` bodies for **every**
-`reportHealth` call, not only the ones reporting `degraded`. The old
-unconditional assignment was also a repair — a resource that reported
-`'unhealthy'` early in `start` and never corrected itself was quietly fixed up
-on the way to ready.
-
-Two cases, and they need opposite fixes.
-
-**1. A resource that is genuinely expected to start degraded** — up, but still
-dialling something external. `required` defaults to **`true`**, and readiness
-requires every required resource to be healthy, so such a resource now refuses
-the whole startup where before its report vanished. That is the invariant
-working as intended; what changed is that it can be reached. Say what it is:
-
-```ts
-// before: started, and its report was discarded
-defineManagedResource({ id: 'dialling', start: ({ reportHealth }) => reportHealth('degraded') })
-
-// after: says what it is, and does not gate the application
-defineManagedResource({ id: 'dialling', required: false, start: ({ reportHealth }) => reportHealth('degraded') })
-```
-
-**2. A resource that reported `'unhealthy'` early and became healthy later** —
-a pessimistic report before a connection settled. Here `required: false` is the
-**wrong** fix: it would hide a real failure. Report the recovery instead:
-
-```ts
-start: async ({ reportHealth }) => {
-  reportHealth('unhealthy')
-  await connect()
-  reportHealth('healthy')   // ← previously unnecessary; now it is the fix
-}
-```
-
-**Also check your health endpoint.** An **optional** resource reporting
-non-healthy during `start` now moves the application aggregate to `degraded`,
-where before it stayed `healthy`. A readiness probe that maps `degraded` to a
-non-200 will flip on upgrade — and a supervisor that restarts on that will loop.
-
-The refusals now say which of the two happened: a resource that was never
-healthy is told it "is not healthy" and pointed at `required: false`; one that
-was healthy and stopped is told it "lost readiness" and pointed at
-`onResourceFailure`.

package/llms/{upgrading-0.75.0-0.103.0.txt → upgrading-0.79.0-0.103.13.txt}

@@ -1,14 +1,95 @@
-# Upgrading 0.75.0 → 0.103.0 — stitchkit docs slice
+# Upgrading 0.79.0 → 0.103.13 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.75.0 → 0.103.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.79.0 → 0.103.13  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.75.0 → 0.103.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.79.0 → 0.103.13  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.103.13
+
+### Darwin native assets in JS distributions
+
+**Who must act:** Bun builds that import `stitchkit/server`, `stitchkit/files` or
+`stitchkit/process` (Linux-only server apps included) and use `--outfile`, copy only
+`outputs[0]`, or package a single file; custom single-file/archive packagers and installers
+delivering native process/files capabilities.
+First affected publication: **0.103.13**, through **0.104.2**. It shipped as a patch; its
+changed delivery graph requires this migration despite unchanged API signatures.
+
+In those versions every Bun bundle that reaches the lock or process-identity code,
+`stitchkit/server` included, carries both Darwin `.node` addons as extra outputs on every
+operating system. `bun build --outfile` then fails with
+`cannot write multiple output files without an output directory`, and `--outdir` writes the
+addons next to a Linux artifact. Releases after 0.104.2 resolve the default loader at run time,
+so these bundles are one JS file with no `.node` output again. The static loader exists only
+in a build that uses the `stitchkit/files/packaging` plugin.
+
+```sh
+# Before: one JS file was assumed to be the entire distribution.
+bun build src/native.ts --target=bun --outfile=dist/native.js
+# After: retain every output, with its relative path.
+bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
+```
+
+For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
+A single-file JS distribution cannot embed a native `.node` addon automatically.
+An archive may contain JS plus companion assets, materialized together before execution.
+Custom output layout uses the evolving build-only packaging contract in the
+[native IO guide](native-io.md#public-native-packaging).
+
+Three deliveries have different rules: an ordinary npm install retains the package's
+native assets; a JS distribution must ship its complete output graph; a Bun compiled
+executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
+`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
+the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
+compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
+executable, but the loader never uses them, so their presence proves nothing.
+
+What an unpackaged bundle does depends on the release:
+
+- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
+  because the loader read `__dirname`. It looks for the addon there, so it works only on that
+  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
+- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
+  addon reports the Darwin backend `unavailable` with stage `packaging`.
+
+Only macOS is affected, and only process identity (`observeProcessInstance`,
+`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
+managed file boundary, atomic writes and the chunk spool never do. The
+[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
+shows how to check an artifact by its loader without running it on a Mac. Check the resulting
+artifact offline outside the build tree and `node_modules`, including process identity,
+live-owner lock refusal, dead-owner recovery and contained IO. A missing or corrupt addon
+remains `unavailable`, never evidence that an owner died.
+
+### CLI: repeated options are refused
+
+**Who must act:** wrappers, aliases and scripts that append `--json`, `--profile X` or an
+application global to arguments the user may already have given, and anything that passes the
+same global twice.
+First affected publication: **0.103.13**. It shipped as a patch; the change in grammar needs
+this migration.
+
+A repeated option that is not an array field is an argument error:
+`--json --json` and `--profile a --profile b` fail with `--json was passed 2 times`. Before
+0.103.13 the last value won, for framework globals, application globals and repeated
+`kind: 'other'` fields alike. Array fields, and untyped passthrough fields that keep their
+raw-list grammar, still repeat.
+
+```sh
+# Before: a wrapper appended its default and the last value won.
+mytool deploy --profile staging "$@" --profile production
+# After: build the argument list once, so each option appears once.
+mytool deploy --profile "${PROFILE:-production}" "$@"
+```
+
+Dotted leaves such as `--filter.name` follow the same rule as their parent field. Declare a
+field as an array when repetition is meant.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -981,137 +1062,3 @@ that will never update again.
 **If you need a tool contract in a browser**, `stitchkit/tools/contract` now
 carries the async-operation helpers, its schemas and the view-file input/output
 without the runtime. `stitchkit/tools` still exports all of them.
-
-## Released migration: 0.78.0
-
-Two mechanical edits. Find them both:
-
-```bash
-rg -n "createDecisionPipeline|createDiagnosticJournal" --glob '*.ts' --glob '*.tsx'
-```
-
-**1. `createDecisionPipeline` takes a deadline.**
-
-```ts
-// before
-createDecisionPipeline([policyA, policyB])
-// after
-createDecisionPipeline([policyA, policyB], { policyTimeoutMs: 2_000 })
-```
-
-Pick a number your slowest policy comfortably beats. There is no default on
-purpose: a policy that never settles hangs every caller of the operation it
-guards, and the framework has no basis for choosing that number for you.
-
-Past the deadline — and on a throw, and on a non-decision — the pipeline raises
-`DecisionPolicyError` naming the policy, with the trace so far. If you already
-catch that for a bad return value, you now catch two more cases with it.
-
-**2. `createDiagnosticJournal` moved.**
-
-```ts
-// before
-import { createDiagnosticJournal } from 'stitchkit/application'
-// after
-import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
-```
-
-Only the factory moved. `DiagnosticJournalConfig`, every
-`DiagnosticJournal*Schema` and `readDiagnosticJournalLockDiagnosis` stay where
-they were.
-
-**If you restart resources**, nothing to change — but three things that did not
-work now do: a managed schedule can be restarted, a restarted keyspace accepts
-writes again, and a restarted managed server is actually shut down at exit. If
-you pass `managedServerResource` a server *instance*, a restart is now refused
-by name; pass a factory (`server: (context) => …`) to restart it.
-
-## Released migration: 0.77.0
-
-Two type renames, and only if you named them. Nothing runtime moved.
-
-```bash
-rg -n "EventDecision|EventUndecided" --glob '*.ts' --glob '*.tsx'
-```
-
-```ts
-// before
-import type { EventDecision, EventUndecided } from 'stitchkit/live'
-// after
-import type { PolicyDecision, UndecidedOutcome } from 'stitchkit/live'
-```
-
-The shapes are identical — `{ outcome: 'allow' } | { outcome: 'deny', reason } | { outcome: 'defer' }`
-and `'allow' | 'deny'`. If you only ever *return* decisions from listeners and never named the
-type, the search above finds nothing and there is nothing to do.
-
-They were renamed because `createDecisionPipeline` (new in this release) votes with exactly the
-same three outcomes, and two identical types under two names is the thing that makes a search for
-either one return half the truth.
-
-## Released migration: 0.76.0
-
-One change, and only if you hand `createWatchClient` a transport you wrote yourself.
-
-```bash
-rg -n "createWatchClient" --glob '*.ts'
-```
-
-If the `transport:` you pass is a bound realtime client — `bindRealtimeClient(...)` or
-`createRealtimeClient(...)` — there is nothing to do: it already carries
-`onConnectionChange`. If it is an object you assembled, add the fourth member:
-
-```ts
-onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void
-```
-
-It is required because the client recovers through it: on a drop it publishes
-`unavailable` to subscribers and forgets what was opened, and on a fresh
-connection it re-opens every key that still has a listener. Without it a watch
-stays "open" on the client after a server restart while the hub remembers
-nothing, and the face stops updating without saying so.
-
-## Released migration: 0.75.0
-
-Two mechanical renames and one option that has to move. Nothing about a passing
-request changes.
-
-### 1. A route group's `onRequest`
-
-```bash
-rg -n "hooks:\s*\{[^}]*onRequest" --glob '*.ts'
-```
-
-Any match **inside a `groups: [...]` entry** must move. The hook was accepted and
-never dispatched, so the behaviour you have today is "no hook"; the fix is to
-decide which one you meant:
-
-```ts
-// refuse before dispatch, for the whole server
-createServer({ groups, hooks: { onRequest: gate } });
-
-// gate this group once the endpoint is known
-groups: [{ pathPrefix: '/admin', services, hooks: { authorize: gate } }]
-```
-
-A group that still declares `onRequest` fails at startup with that message.
-
-### 2. The SQLite boundary type
-
-```bash
-rg -l "AgentRuntimeSqlite(Database|Statement|Value)" | xargs sed -i \
-  -e 's/AgentRuntimeSqliteDatabase/SqliteDatabase/g' \
-  -e 's/AgentRuntimeSqliteStatement/SqliteStatement/g' \
-  -e 's/AgentRuntimeSqliteValue/SqliteValue/g'
-```
-
-Type-only: the same three methods, the same structural compatibility with
-`bun:sqlite` and a `node:sqlite` wrapper, imported from the same entrypoints.
-`initializeAgentRuntimeSqlite` keeps its name — it really is the agent runtime's
-schema.
-
-### 3. Nothing else
-
-`stitchkit/live`, the watch hub, the keyspace and the trust fence are all
-additive. Adopt them when you want them; the guide is
-[Live data](./live.md).

package/llms/upgrading.txt

@@ -11,11 +11,11 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.103.13 → 0.113.0: `llms/upgrading-0.103.13-0.113.0.txt`
-- 0.75.0 → 0.103.0: `llms/upgrading-0.75.0-0.103.0.txt`
-- 0.61.0 → 0.74.0: `llms/upgrading-0.61.0-0.74.0.txt`
-- 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
-- 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`
+- 0.104.0 → 0.114.0: `llms/upgrading-0.104.0-0.114.0.txt`
+- 0.79.0 → 0.103.13: `llms/upgrading-0.79.0-0.103.13.txt`
+- 0.62.0 → 0.78.0: `llms/upgrading-0.62.0-0.78.0.txt`
+- 0.44.0 → 0.61.0: `llms/upgrading-0.44.0-0.61.0.txt`
+- 0.37.0 → 0.44.0: `llms/upgrading-0.37.0-0.44.0.txt`
 
 # Upgrading stitchkit