stitchkit 0.102.0 → 0.103.0

package/llms-full.txt

@@ -70,12 +70,12 @@ 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 47 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 48 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/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 47 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 48 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 |
@@ -85,11 +85,11 @@ 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 10 of the 47 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 11 of the 48 minors since 0.56.2, most recently 0.103.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 |
-| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — an exclusive bounded writer and snapshot reader with explicit anomalies |
 | `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -6622,7 +6622,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-09-04 14:11 +07:00
+updated: 2026-09-30 17:41 +07:00
 ---
 
 # Managed application kernel
@@ -7269,10 +7269,47 @@ 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
-waiter; the writer retains physical capacity until settlement. There is no reader or upload API.
-Use a durable application store or deployment-owned log collector when restart recovery, replay or
+waiter; the writer retains physical capacity until settlement. There is no upload or managed replay API.
+Use a durable application store or deployment-owned log collector when durable restart recovery, replay or
 aggregation is required. → [ADR 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
 
+For finite inspection, use the shared reader with an explicit oldest-to-newest list of existing
+files. Keep anomaly reporting outside the journal being inspected:
+
+```ts
+import { readDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+import { z } from 'zod'
+
+const eventSchema = z.object({
+  kind: z.enum(['resource_failed', 'recovery_started']),
+  resource: z.string().max(80),
+}).strict()
+
+for await (const row of readDiagnosticJournal({
+  paths: ['/var/lib/example/diagnostic.jsonl.1', '/var/lib/example/diagnostic.jsonl'],
+  eventSchema,
+  maxLineBytes: 4 * 1024,
+})) {
+  if (row.type === 'anomaly') internalLogger.warn(row.anomaly)
+  else inspectEvent(row.frame.event)
+}
+```
+
+The reader bounds memory by line size plus a fixed chunk, skips oversized/damaged rows with
+explicit anomalies, and still returns valid rows before and after them. `offset` is zero-based
+bytes; `line` is one-based. `position` distinguishes the file's tail from interior damage.
+A valid frame lacking its final LF yields a warning with `skippedBytes: 0` and its frame.
+Each file's size is captured at open; concurrent appends are excluded. Missing files, permissions,
+symlinks, non-regular files and mid-read truncation throw rather than masquerading as bad data.
+The caller owns file selection and coordination with an active rotator.
+
+Writer startup inspects retained and active files under its lock. On damage,
+`journal.getStatus().recovery` contains counts and first/last anomaly locations, reconstructed
+again on restart from the preserved bytes. This describes startup observations, not live
+continuous inspection. `maxFiles: 1` cannot preserve a torn active file by rotation and throws
+`DiagnosticJournalRecoveryError` before removing any evidence; configure at least two slots.
+Normal rotation retains the existing finite eviction policy. → [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+
 Shutdown performs one phase barrier at a time: stop admission everywhere,
 cancel future schedules, drain admitted work, then close in reverse stable
 topological order. Every hook shares the same grace deadline. Forced cleanup
@@ -14238,6 +14275,35 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.103.0
+
+### Diagnostic journal startup preserves torn evidence and inspects archives
+
+**Who must act:** operators using `maxFiles: 1` who can encounter a torn active
+file, or whose retained files are unreadable by the writer. Clean single-file
+journals continue to work; successful startup now requires read access to every
+retained generation.
+
+```ts
+import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+
+// Before: a torn active file could be discarded during startup.
+await createDiagnosticJournal({ ...config, limits: { ...config.limits, maxFiles: 1 } })
+// After: retain the torn file while the fresh writer starts in a new active file.
+await createDiagnosticJournal({ ...config, limits: { ...config.limits, maxFiles: 2 } })
+```
+
+With single-file retention, a torn active file throws `DiagnosticJournalRecoveryError`
+from `stitchkit/application`, carrying `recovery` observations and releasing its lock
+without deleting evidence. Inspection I/O errors also fail startup and release the
+lock; restore filesystem access rather than treating that failure as a bad JSON row.
+Normal rotation retains the configured finite eviction policy.
+
+For archive inspection, replace ad hoc line parsing with `readDiagnosticJournal`
+from the same filesystem leaf. Handle its `frame | anomaly` stream explicitly;
+missing files, permissions and unsafe paths still throw. See the
+[journal guide](application-kernel.md#bounded-local-diagnostic-journal).
+
 ## Released migration: 0.102.0
 
 ### `view_file` receives an array, not an array encoded as text
@@ -18916,9 +18982,13 @@ cutovers are covered by the executable
 | `DiagnosticJournalRefusalReasonSchema` / `DiagnosticJournalRefusalReason` | schema / _type_ | `closed \| failed \| invalid \| oversized \| item-capacity \| byte-capacity` |
 | `DiagnosticJournalFailurePhaseSchema` / `DiagnosticJournalFailurePhase` | schema / _type_ | internal `write \| rotation \| close` failure phase exposed only to status and the isolated observer |
 | `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
+| `DiagnosticJournalAnomalySchema` / `DiagnosticJournalAnomaly` | schema / _type_ | corrupt-row reason, file, zero-based byte offset, one-based line, tail/interior position and skipped bytes |
+| `createDiagnosticJournalReadResultSchema` / `DiagnosticJournalReadResult` | function / _type_ | owner-schema frame output or explicit anomaly; retains transformed event output types |
+| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts and first/last anomaly locations |
+| `DiagnosticJournalRecoveryError` | class | torn single-file startup refusal carrying recovery observations, preserving evidence and releasing its lock |
 
 `accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
-delivery. The journal has no reader/replay/upload API. See the
+delivery. Its filesystem reader is in the diagnostic-journal leaf; there is no managed replay/upload API. See the
 [guide](../guide/application-kernel.md#bounded-local-diagnostic-journal),
 [architecture](../architecture/diagnostic-journal.md) and [ADR
 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
@@ -19093,6 +19163,8 @@ snapshots; the adapter owns no SDK lifecycle, polling or delta state.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createDiagnosticJournal` | function | the bounded local journal: a file lock, a spawn to diagnose a stale one, and framed writes |
+| `readDiagnosticJournal` | function | bounded async stream of validated frames and explicit anomalies from finite snapshots of caller-selected files; I/O failures throw |
+| `DiagnosticJournalReaderConfig` | _type_ | normalized absolute `paths`, owner `eventSchema`, positive safe-integer `maxLineBytes` and optional cancellation `signal` |
 
 Its own entrypoint because of what it reaches — `node:child_process`,
 `node:fs`, `node:os`, `node:util` — with `promisify(execFile)` evaluated while

package/llms.txt

@@ -9,7 +9,7 @@ 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) 16.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 45.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 16.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 45.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.4 KB
@@ -31,11 +31,11 @@ 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) 46.0 KB → [llms/application.2.txt](llms/application.2.txt) 40.0 KB
+- **stitchkit/application**: [llms/application.txt](llms/application.txt) 37.9 KB → [llms/application.2.txt](llms/application.2.txt) 24.1 KB → [llms/application.3.txt](llms/application.3.txt) 27.3 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
-- **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.4 KB
+- **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.8 KB
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
@@ -55,7 +55,7 @@ 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.75.0 → 0.102.0**: [llms/upgrading-0.75.0-0.102.0.txt](llms/upgrading-0.75.0-0.102.0.txt) 44.8 KB
+- **Upgrading 0.75.0 → 0.103.0**: [llms/upgrading-0.75.0-0.103.0.txt](llms/upgrading-0.75.0-0.103.0.txt) 46.3 KB
 - **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.102.0",
+  "version": "0.103.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",

package/dist/index-h124epcf.js

@@ -1,103 +0,0 @@
-import {
-  isRecord
-} from "./index-9jfdm5tg.js";
-
-// src/application/diagnostic-journal-contract.ts
-import { z } from "zod";
-var PositiveSafeIntegerSchema = z.number().int().positive().safe();
-var FileModeSchema = z.number().int().min(0).max(511);
-var DiagnosticJournalLimitsSchema2 = z.object({
-  maxEventBytes: PositiveSafeIntegerSchema,
-  maxPendingItems: PositiveSafeIntegerSchema,
-  maxPendingBytes: PositiveSafeIntegerSchema,
-  maxFileBytes: PositiveSafeIntegerSchema,
-  maxFiles: PositiveSafeIntegerSchema
-}).strict().readonly();
-var DiagnosticJournalLockPolicySchema2 = z.enum(["refuse", "reclaim-stale"]);
-var DiagnosticJournalStateSchema2 = z.enum(["open", "draining", "closed", "failed"]);
-var DiagnosticJournalRefusalReasonSchema2 = z.enum([
-  "closed",
-  "failed",
-  "invalid",
-  "oversized",
-  "item-capacity",
-  "byte-capacity"
-]);
-var DiagnosticJournalRefusalCountersSchema = z.object({
-  closed: z.number().int().nonnegative(),
-  failed: z.number().int().nonnegative(),
-  invalid: z.number().int().nonnegative(),
-  oversized: z.number().int().nonnegative(),
-  "item-capacity": z.number().int().nonnegative(),
-  "byte-capacity": z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalFailurePhaseSchema2 = z.enum(["write", "rotation", "close"]);
-var DiagnosticJournalStatusSchema2 = z.object({
-  state: DiagnosticJournalStateSchema2,
-  epoch: z.uuid(),
-  limits: DiagnosticJournalLimitsSchema2,
-  lock: z.object({
-    policy: DiagnosticJournalLockPolicySchema2,
-    reclaimedStale: z.boolean()
-  }).strict().readonly(),
-  received: z.number().int().nonnegative(),
-  accepted: z.number().int().nonnegative(),
-  refused: z.number().int().nonnegative(),
-  refusals: DiagnosticJournalRefusalCountersSchema,
-  written: z.number().int().nonnegative(),
-  failedRecords: z.number().int().nonnegative(),
-  pendingItems: z.number().int().nonnegative(),
-  pendingBytes: z.number().int().nonnegative(),
-  inFlight: z.boolean(),
-  rotations: z.number().int().nonnegative(),
-  rotationFailures: z.number().int().nonnegative(),
-  partialTails: z.number().int().nonnegative(),
-  currentFileBytes: z.number().int().nonnegative(),
-  retainedFiles: z.number().int().nonnegative(),
-  lastAcceptedSequence: z.number().int().positive().optional(),
-  lastWrittenSequence: z.number().int().positive().optional(),
-  lastSettledSequence: z.number().int().positive().optional(),
-  lastFailure: z.object({
-    phase: DiagnosticJournalFailurePhaseSchema2,
-    sequence: z.number().int().positive().optional()
-  }).strict().readonly().optional()
-}).strict().readonly();
-var DiagnosticJournalSubmitResultSchema2 = z.discriminatedUnion("outcome", [
-  z.object({
-    outcome: z.literal("accepted"),
-    epoch: z.uuid(),
-    sequence: z.number().int().positive()
-  }).strict().readonly(),
-  z.object({
-    outcome: z.literal("refused"),
-    reason: DiagnosticJournalRefusalReasonSchema2
-  }).strict().readonly()
-]);
-var DiagnosticJournalWaitResultSchema2 = z.object({
-  outcome: z.enum(["settled", "timed-out", "cancelled"]),
-  state: DiagnosticJournalStateSchema2,
-  throughSequence: z.number().int().nonnegative(),
-  settledSequence: z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalCloseResultSchema2 = z.object({
-  outcome: z.enum(["closed", "timed-out", "cancelled"]),
-  state: DiagnosticJournalStateSchema2,
-  pendingItems: z.number().int().nonnegative()
-}).strict().readonly();
-var DiagnosticJournalFrameSchema2 = z.object({
-  schemaVersion: z.literal(1),
-  epoch: z.uuid(),
-  sequence: z.number().int().positive(),
-  event: z.json()
-}).strict().readonly();
-function parseDiagnosticJournalMode(mode) {
-  return FileModeSchema.parse(mode ?? 384);
-}
-function readDiagnosticJournalLockDiagnosis2(error) {
-  if (!isRecord(error))
-    return;
-  const diagnosis = error.journalLock;
-  return isRecord(diagnosis) ? diagnosis : undefined;
-}
-
-export { DiagnosticJournalLimitsSchema2, DiagnosticJournalLockPolicySchema2, DiagnosticJournalStateSchema2, DiagnosticJournalRefusalReasonSchema2, DiagnosticJournalFailurePhaseSchema2, DiagnosticJournalStatusSchema2, DiagnosticJournalSubmitResultSchema2, DiagnosticJournalWaitResultSchema2, DiagnosticJournalCloseResultSchema2, DiagnosticJournalFrameSchema2, parseDiagnosticJournalMode, readDiagnosticJournalLockDiagnosis2 };