stitchkit 0.94.1 → 0.95.0

package/dist/entrypoints/application.js

@@ -1068,21 +1068,28 @@ function notificationOutboxResource(outbox, config = {}) {
   });
 }
 // src/application/process-lifecycle.ts
+import { z as z7 } from "zod";
+
+// src/application/process-lifecycle-transitions.ts
 import { z as z6 } from "zod";
 var LifecycleTerminationSchema = z6.enum([
   "active",
+  "draining",
   "clean",
   "forced",
+  "startup-failed",
   "hot-reload",
   "abnormal"
 ]);
+var timestamp = z6.string().datetime({ offset: true });
 var LifecycleRunSchema = z6.object({
   runId: z6.string().min(1).max(128),
   pid: z6.number().int().positive(),
   version: z6.string().min(1).max(256),
-  startedAt: z6.string().datetime({ offset: true }),
-  readyAt: z6.string().datetime({ offset: true }).nullable(),
-  stoppedAt: z6.string().datetime({ offset: true }).nullable(),
+  startedAt: timestamp,
+  readyAt: timestamp.nullable(),
+  unavailableAt: timestamp.nullable().default(null),
+  stoppedAt: timestamp.nullable(),
   termination: LifecycleTerminationSchema
 }).strict();
 var LifecycleStateSchema = z6.object({
@@ -1094,17 +1101,20 @@ var PreviousExitSchema = z6.enum([
   "hot-reload",
   "clean",
   "forced",
+  "startup-failed",
   "handoff",
   "abnormal"
 ]);
 var emptyState = () => ({ schemaVersion: 1, runs: [] });
 var epoch = (value) => Date.parse(value);
 var elapsed = (later, earlier) => Math.max(0, epoch(later) - epoch(earlier));
-function normalize(state, retain) {
+var isOpenRun = (run) => run.termination === "active" || run.termination === "draining";
+function normalizeLifecycleState(state, retain) {
   const parsed = LifecycleStateSchema.parse(state ?? emptyState());
   const runs = [...parsed.runs];
   for (let index = runs.length - 1;runs.length > retain && index >= 0; index -= 1) {
-    if (runs[index]?.termination !== "active")
+    const run = runs[index];
+    if (run && !isOpenRun(run))
       runs.splice(index, 1);
   }
   return { schemaVersion: 1, runs: runs.slice(0, retain) };
@@ -1113,15 +1123,45 @@ var UNKNOWN_VERSION = "unknown";
 function isVersionChange(previous, next) {
   return previous !== UNKNOWN_VERSION && next !== UNKNOWN_VERSION && previous !== next;
 }
+var RetainSchema = z6.number().int().min(1).max(1000);
+function previousExitOf(previous, run, overlap) {
+  if (!previous)
+    return "first-boot";
+  const ended = previous.termination;
+  if (ended !== "active" && ended !== "draining")
+    return ended;
+  if (previous.pid === run.pid)
+    return "hot-reload";
+  if (isVersionChange(previous.version, run.version) || overlap === "handoff")
+    return "handoff";
+  return previous.readyAt === null ? "startup-failed" : "abnormal";
+}
+function closeAbandoned(candidate, previous, previousExit, run, overlap) {
+  if (!isOpenRun(candidate))
+    return candidate;
+  const closed = { ...candidate, stoppedAt: run.startedAt };
+  if (candidate.pid === run.pid)
+    return { ...closed, termination: "hot-reload" };
+  if (overlap === "handoff")
+    return candidate;
+  if (candidate.runId === previous?.runId && previousExit === "handoff")
+    return candidate;
+  return {
+    ...closed,
+    termination: candidate.readyAt === null ? "startup-failed" : "abnormal"
+  };
+}
 function transitionProcessStart(source, input) {
-  const retain = z6.number().int().min(1).max(1000).parse(input.retain ?? 20);
-  const state = normalize(source, 1000);
+  const retain = RetainSchema.parse(input.retain ?? 20);
+  const overlap = input.sameVersionOverlap ?? "abnormal";
+  const state = normalizeLifecycleState(source, 1000);
   const run = LifecycleRunSchema.parse({
     runId: input.runId,
     pid: input.pid,
     version: input.version,
     startedAt: input.now,
     readyAt: null,
+    unavailableAt: null,
     stoppedAt: null,
     termination: "active"
   });
@@ -1129,31 +1169,10 @@ function transitionProcessStart(source, input) {
     throw new Error(`[stitchkit] lifecycle run id already exists: ${run.runId}`);
   }
   const previous = state.runs[0] ?? null;
-  let previousExit = "first-boot";
-  let downtimeMs = null;
-  if (previous?.stoppedAt) {
-    previousExit = previous.termination === "forced" || previous.termination === "abnormal" || previous.termination === "hot-reload" ? previous.termination : "clean";
-    downtimeMs = elapsed(run.startedAt, previous.stoppedAt);
-  } else if (previous) {
-    if (previous.pid === run.pid)
-      previousExit = "hot-reload";
-    else if (isVersionChange(previous.version, run.version))
-      previousExit = "handoff";
-    else
-      previousExit = input.sameVersionOverlap ?? "abnormal";
-  }
-  const runs = state.runs.map((candidate) => {
-    if (candidate.runId !== previous?.runId || candidate.termination !== "active")
-      return candidate;
-    if (previousExit === "hot-reload") {
-      return { ...candidate, stoppedAt: run.startedAt, termination: "hot-reload" };
-    }
-    if (previousExit === "abnormal") {
-      return { ...candidate, stoppedAt: run.startedAt, termination: "abnormal" };
-    }
-    return candidate;
-  });
-  const next = normalize({ schemaVersion: 1, runs: [run, ...runs] }, retain);
+  const previousExit = previousExitOf(previous, run, overlap);
+  const processGapMs = previous && !isOpenRun(previous) && previous.stoppedAt ? elapsed(run.startedAt, previous.stoppedAt) : null;
+  const runs = state.runs.map((candidate) => closeAbandoned(candidate, previous, previousExit, run, overlap));
+  const next = normalizeLifecycleState({ schemaVersion: 1, runs: [run, ...runs] }, retain);
   return {
     state: next,
     fact: {
@@ -1167,15 +1186,30 @@ function transitionProcessStart(source, input) {
       previousPid: previous?.pid ?? null,
       previousVersion: previous?.version ?? null,
       versionChanged: previous !== null && isVersionChange(previous.version, run.version),
-      downtimeMs
+      processGapMs
     }
   };
 }
+function findOpen(state, input) {
+  return state.runs.find((run) => run.runId === input.runId && run.pid === input.pid && isOpenRun(run));
+}
+function unavailability(state, target, readyAt) {
+  const older = state.runs.slice(state.runs.indexOf(target) + 1);
+  const served = older.find((run) => run.readyAt !== null);
+  if (!served)
+    return { downtimeMs: null, unavailableSince: null };
+  if (served.unavailableAt !== null) {
+    return {
+      downtimeMs: elapsed(readyAt, served.unavailableAt),
+      unavailableSince: served.unavailableAt
+    };
+  }
+  return isOpenRun(served) ? { downtimeMs: 0, unavailableSince: null } : { downtimeMs: null, unavailableSince: null };
+}
 function transitionProcessReady(source, input) {
-  const retain = input.retain ?? 20;
-  const state = normalize(source, retain);
-  const target = state.runs.find((run) => run.runId === input.runId && run.pid === input.pid && run.termination === "active");
-  if (!target) {
+  const state = normalizeLifecycleState(source, input.retain ?? 20);
+  const target = findOpen(state, input);
+  if (target?.termination !== "active") {
     return {
       state,
       fact: {
@@ -1184,6 +1218,8 @@ function transitionProcessReady(source, input) {
         pid: input.pid,
         readyAt: input.now,
         startupMs: 0,
+        downtimeMs: null,
+        unavailableSince: null,
         recorded: false
       }
     };
@@ -1200,14 +1236,45 @@ function transitionProcessReady(source, input) {
       pid: target.pid,
       readyAt,
       startupMs: elapsed(readyAt, target.startedAt),
+      ...unavailability(state, target, readyAt),
       recorded: target.readyAt === null
     }
   };
 }
+function transitionProcessDraining(source, input) {
+  const state = normalizeLifecycleState(source, input.retain ?? 20);
+  const target = findOpen(state, input);
+  if (target?.termination !== "active") {
+    return {
+      state,
+      fact: {
+        type: "draining",
+        runId: input.runId,
+        pid: input.pid,
+        unavailableAt: target ? target.unavailableAt : null,
+        recorded: false
+      }
+    };
+  }
+  const unavailableAt = target.readyAt === null ? null : input.now;
+  return {
+    state: {
+      schemaVersion: 1,
+      runs: state.runs.map((run) => run.runId === target.runId ? { ...run, termination: "draining", unavailableAt } : run)
+    },
+    fact: {
+      type: "draining",
+      runId: target.runId,
+      pid: target.pid,
+      unavailableAt,
+      recorded: true
+    }
+  };
+}
 function transitionProcessShutdown(source, input) {
-  const state = normalize(source, input.retain ?? 20);
-  const target = state.runs.find((run) => run.runId === input.runId && run.pid === input.pid && run.termination === "active");
-  const termination = input.forced ? "forced" : "clean";
+  const state = normalizeLifecycleState(source, input.retain ?? 20);
+  const target = findOpen(state, input);
+  const requested = input.forced ? "forced" : "clean";
   if (!target) {
     return {
       state,
@@ -1217,15 +1284,17 @@ function transitionProcessShutdown(source, input) {
         pid: input.pid,
         stoppedAt: input.now,
         uptimeMs: null,
-        termination,
+        termination: requested,
         recorded: false
       }
     };
   }
+  const termination = target.readyAt === null ? "startup-failed" : requested;
+  const unavailableAt = target.unavailableAt ?? (target.readyAt === null ? null : input.now);
   return {
     state: {
       schemaVersion: 1,
-      runs: state.runs.map((run) => run.runId === target.runId ? { ...run, stoppedAt: input.now, termination } : run)
+      runs: state.runs.map((run) => run.runId === target.runId ? { ...run, unavailableAt, stoppedAt: input.now, termination } : run)
     },
     fact: {
       type: "stopped",
@@ -1238,10 +1307,12 @@ function transitionProcessShutdown(source, input) {
     }
   };
 }
+
+// src/application/process-lifecycle.ts
 function createProcessLifecycleLedger(config) {
   const clock = config.clock ?? (() => new Date);
-  const pid = z6.number().int().positive().parse(config.pid ?? process.pid);
-  const retain = z6.number().int().min(1).max(1000).parse(config.retain ?? 20);
+  const pid = z7.number().int().positive().parse(config.pid ?? process.pid);
+  const retain = z7.number().int().min(1).max(1000).parse(config.retain ?? 20);
   const configuredRunId = config.runId;
   const nextRunId = typeof configuredRunId === "function" ? configuredRunId : configuredRunId === undefined ? () => crypto.randomUUID() : () => configuredRunId;
   let runId = nextRunId();
@@ -1285,6 +1356,20 @@ function createProcessLifecycleLedger(config) {
         publish(fact);
       return fact;
     },
+    async recordDraining() {
+      const fact = await config.store.update((state) => {
+        const transition = transitionProcessDraining(state, {
+          runId,
+          pid,
+          now: clock().toISOString(),
+          retain
+        });
+        return { state: transition.state, result: transition.fact };
+      });
+      if (fact.recorded)
+        publish(fact);
+      return fact;
+    },
     async recordShutdown(input) {
       const fact = await config.store.update((state) => {
         const transition = transitionProcessShutdown(state, {
@@ -1301,11 +1386,11 @@ function createProcessLifecycleLedger(config) {
       return fact;
     },
     async current() {
-      const state = normalize(await config.store.read(), retain);
+      const state = normalizeLifecycleState(await config.store.read(), retain);
       return state.runs.find((run) => run.runId === runId && run.pid === pid) ?? null;
     },
     async runs() {
-      return normalize(await config.store.read(), retain).runs;
+      return normalizeLifecycleState(await config.store.read(), retain).runs;
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -1340,6 +1425,9 @@ function lifecycleLedgerResource(ledger, config) {
     async activate() {
       await ledger.recordReady();
     },
+    async stopAdmission() {
+      await ledger.recordDraining();
+    },
     async close() {
       await stop(false);
     },
@@ -1349,27 +1437,27 @@ function lifecycleLedgerResource(ledger, config) {
   });
 }
 // src/application/revision-signal.ts
-import { z as z7 } from "zod";
-var NonNegativeSafeIntegerSchema = z7.number().int().nonnegative().safe();
-var PositiveSafeIntegerSchema2 = z7.number().int().positive().safe();
-var TimerDelaySchema = z7.number().int().positive().max(2147483647);
-var RevisionSignalStateSchema = z7.enum(["open", "closed"]);
-var RevisionSignalWaitOutcomeSchema = z7.enum([
+import { z as z8 } from "zod";
+var NonNegativeSafeIntegerSchema = z8.number().int().nonnegative().safe();
+var PositiveSafeIntegerSchema2 = z8.number().int().positive().safe();
+var TimerDelaySchema = z8.number().int().positive().max(2147483647);
+var RevisionSignalStateSchema = z8.enum(["open", "closed"]);
+var RevisionSignalWaitOutcomeSchema = z8.enum([
   "changed",
   "timed-out",
   "aborted",
   "closed",
   "capacity"
 ]);
-var RevisionSignalWaitResultSchema = z7.object({
+var RevisionSignalWaitResultSchema = z8.object({
   outcome: RevisionSignalWaitOutcomeSchema,
   revision: NonNegativeSafeIntegerSchema
 }).strict().readonly();
-var RevisionSignalAdvanceResultSchema = z7.object({
-  outcome: z7.enum(["advanced", "closed"]),
+var RevisionSignalAdvanceResultSchema = z8.object({
+  outcome: z8.enum(["advanced", "closed"]),
   revision: NonNegativeSafeIntegerSchema
 }).strict().readonly();
-var RevisionSignalSnapshotSchema = z7.object({
+var RevisionSignalSnapshotSchema = z8.object({
   state: RevisionSignalStateSchema,
   revision: NonNegativeSafeIntegerSchema,
   pending: NonNegativeSafeIntegerSchema,
@@ -1919,6 +2007,7 @@ export {
   transitionProcessStart,
   transitionProcessShutdown,
   transitionProcessReady,
+  transitionProcessDraining,
   sqliteKeyspaceBackend,
   readDiagnosticJournalLockDiagnosis,
   projectApplicationStatus,

package/dist/{index-7f68ghdn.js → index-8zja4pkf.js}

@@ -1775,6 +1775,27 @@ function markProviderOrigin(error) {
 function hasProviderOrigin(error) {
   return typeof error === "object" && error !== null && providerOrigin.has(error);
 }
+function markProviderStream(stream) {
+  const reader = stream.getReader();
+  return new ReadableStream({
+    async pull(controller) {
+      let read;
+      try {
+        read = await reader.read();
+      } catch (error) {
+        controller.error(isOwnInputRefusal(error) ? error : markProviderOrigin(error));
+        return;
+      }
+      if (read.done)
+        controller.close();
+      else
+        controller.enqueue(read.value);
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    }
+  });
+}
 
 // src/agent-runtime/run-operation-lifecycle.ts
 function createAgentRunOperationLifecycle(config) {
@@ -1840,7 +1861,8 @@ function createAgentRunOperationLifecycle(config) {
             }
             await startModelRequest(callId, step);
             try {
-              return await doStream();
+              const result = await doStream();
+              return { ...result, stream: markProviderStream(result.stream) };
             } catch (error) {
               throw isOwnInputRefusal(error) ? error : markProviderOrigin(error);
             }

package/llms/application.2.txt

@@ -290,11 +290,11 @@ cutovers are covered by the executable
 | `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
 | `StateStore` / `StateStoreUpdate` | _type_ | async atomic read/update boundary shared by durable application state machines |
 | `createProcessLifecycleLedger` / `ProcessLifecycleLedger` / `ProcessLifecycleLedgerConfig` | function / _type_ | durable bounded run history and typed fact subscription |
-| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state and termination vocabulary |
-| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, handoff and abnormal lifecycle facts |
-| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
-| `LifecycleTransition` / `TransitionStartInput` / `TransitionReadyInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs, the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
-| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness and shutdown |
+| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
 | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |

package/llms/application.txt

@@ -815,39 +815,74 @@ application-owned.
 ## Durable process facts and owner notifications
 
 `createProcessLifecycleLedger` records a bounded versioned list of process runs.
-Start, readiness and shutdown target both `runId` and `pid`, so hot reload and
-PID reuse cannot close the wrong generation. A start classifies what happened to
-the newest run before it, and the classification is decided by three facts —
-whether that run recorded its own exit, whether the pid is the same, and whether
-the version changed:
+Start, readiness, draining and shutdown target both `runId` and `pid`, so hot
+reload and PID reuse cannot close the wrong generation. `lifecycleLedgerResource`
+drives it from the kernel's phases: `start` records the start, `activate` the
+readiness, `stopAdmission` the drain — the run's `unavailableAt`, the moment it
+stops answering new work — and `close` / `force` the stop. A run that stops
+without ever becoming ready (a failed startup rolls back with `close` only)
+ends as `startup-failed`, not `clean`.
+
+A start classifies what happened to the newest run before it, and the
+classification is decided by four facts — whether that run recorded its own
+exit, whether the pid is the same, whether the version changed and whether it
+ever became ready:
 
 | newest run | same pid | version | `previousExit` | predecessor's `termination` |
 |---|---|---|---|---|
 | none | — | — | `first-boot` | — |
-| recorded `stoppedAt` | — | — | `clean` / `forced` / `abnormal` as recorded | unchanged |
-| still `active` | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
-| still `active` | no | changed | `handoff` | stays `active`; it records its own stop later |
-| still `active` | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+| recorded `stoppedAt` | — | — | `clean` / `forced` / `startup-failed` / `abnormal` as recorded | unchanged |
+| still open | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
+| still open | no | changed | `handoff` | stays open; it records its own stop later |
+| still open, was ready | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+| still open, never ready | no | same | `startup-failed` (default) | `startup-failed`, closed at the new start |
+
+Every other open run the start finds was abandoned too and is closed the same
+way — two crashes in a row leave two open runs, and both are closed, not only
+the newest. Open means `active` or `draining`.
 
 A version of `unknown` on either side is never a version change, so a dev build
 after a crashed release reads `abnormal`, not `handoff`. `forced` means the
 process itself acknowledged a kill; `abnormal` means a successor found it dead.
 
-The last row is a choice, and the default is the single-process deployment:
+### Downtime is the window nobody answered in
+
+`ReadyFact.downtimeMs` is `readyAt` of the new run minus `unavailableAt` of the
+last run that served — the predecessor's drain plus the successor's boot. A
+110 s forced drain followed by a 4 s boot is 114 s of downtime; the gap between
+the two processes alone would read 4 s before and after that defect was fixed.
+Runs that never became ready answered nobody, so the count passes them: after a
+failed start it still opens where the last serving run stopped answering. It is
+`0` when that run still answers (a handoff whose predecessor has not drained
+yet) and `null` on first boot and when the end was never timed — a crash or a
+hot reload records no `unavailableAt`. `unavailableSince` names the moment it is
+counted from. The gap between two processes is still there, under its own
+name: `StartFact.processGapMs` is the start minus the predecessor's recorded
+stop.
+
+The ledger records what the process says while it can say it. stitchkit never
+calls `process.exit` (ADR 0074), so a stop is recorded on the kernel's `close`
+or `force` path, both awaited. An application that exits the process on its
+own before its shutdown settles loses that last write; the successor then
+finds the run open and closes it as `abnormal`, keeping the `unavailableAt`
+already recorded — which is why the drain moment is written first, at
+`stopAdmission`, and the downtime survives a stop that was never recorded.
+
+The `abnormal` default is a choice, and it is the single-process deployment:
 one process per build, a new pid of the same build means the old one stopped
-answering. Where two processes of **one** build overlap on purpose — a
-cluster, a zero-downtime reload of the same build — pass
-`sameVersionOverlap: 'handoff'` to the ledger, and the predecessor stays
-`active` until it records its own shutdown. The cost of that setting is
-symmetric: a real crash under it is reported as a handoff and the dead run
-stays `active` in the ledger until retention drops it. The list is kept in the
-order the transitions wrote it — every write goes through one atomic update,
-so that order is the causal one, and a successor whose clock lags its
-predecessor still finds it at the head; `startedAt` is data, not the sort key.
-Retention (`retain`, default 20) drops finished runs first and an active one —
-a live handoff predecessor — only when nothing finished is left. Facts are
-published through the ledger's own subscription and resource value;
-`ApplicationEventSink` remains the strict application-state stream.
+answering. Where processes of **one** build overlap on purpose — a cluster, a
+zero-downtime reload of the same build — pass `sameVersionOverlap: 'handoff'`
+to the ledger, and every open run stays open until it records its own
+shutdown. The cost of that setting is symmetric: a real crash under it is
+reported as a handoff and the dead run stays open in the ledger until
+retention drops it. The list is kept in the order the transitions wrote it —
+every write goes through one atomic update, so that order is the causal one,
+and a successor whose clock lags its predecessor still finds it at the head;
+`startedAt` is data, not the sort key. Retention (`retain`, default 20) drops
+finished runs first and an open one — a live handoff predecessor — only when
+nothing finished is left. Facts are published through the ledger's own
+subscription and resource value; `ApplicationEventSink` remains the strict
+application-state stream.
 
 `createNotificationOutbox` is the transport-neutral durable delivery side. It
 persists before send, claims an item with an expiring lease, carries one stable

package/llms/stitchkit.txt

@@ -76,11 +76,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 39 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 40 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 21 of the 39 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 40 minors since 0.56.2, most recently 0.94.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 |
@@ -90,7 +90,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 7 of the 39 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 8 of the 40 minors since 0.56.2, most recently 0.95.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `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 |

package/llms/{upgrading-0.37.0-0.50.0.txt → upgrading-0.37.0-0.53.0.txt}

@@ -1,14 +1,36 @@
-# Upgrading 0.37.0 → 0.50.0 — stitchkit docs slice
+# Upgrading 0.37.0 → 0.53.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.37.0 → 0.50.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.50.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.37.0 → 0.53.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.53.0
+
+### Realtime `emit` returns `boolean` instead of `void`
+
+Every **call site** compiles and behaves exactly as before — the return value
+is new information (`true` = accepted by the transport, `false` = dropped
+while the browser client was disconnected), not a behavior change. What breaks
+is **implementing** the interfaces: a test mock or app-side adapter of
+`SocketIOClient` / `RealtimeClient` / `ValidatedRealtimeSocket` /
+`RealtimeServer` whose `emit` returns `void` no longer typechecks.
+
+```ts
+// before — a void mock satisfied the interface
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => {} }
+// after — report acceptance (true is what a live server-side emit reports)
+const mock: Pick<RealtimeClient<S, C>, 'emit'> = { emit: () => true }
+```
+
+While migrating, consider replacing hand-rolled `if (client.connected)` guards
+with the new honest surface: check `client.emit(...) === false`, or observe
+drops centrally with `onDroppedEmit`.
+
 ## Released migration: 0.50.0
 
 ### The factory's scope union now covers per-endpoint overrides