stitchkit 0.101.3 → 0.103.0

package/CHANGELOG.md

@@ -15,6 +15,70 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.103.0] — 2026-09-30
+
+### ⚠️ Breaking changes
+
+- `stitchkit/application/diagnostic-journal` — **torn startup with `maxFiles: 1`
+  now throws `DiagnosticJournalRecoveryError` before deleting any evidence**.
+  Previously startup discarded the active file and continued. To preserve it,
+  `limits: { ...limits, maxFiles: 1 }` → `limits: { ...limits, maxFiles: 2 }`.
+  The acquired lock is released on refusal. → ADR 0219.
+- `stitchkit/application/diagnostic-journal` — **startup inspects retained files
+  and throws on inspection I/O failures**, instead of accepting unreadable
+  archives unchecked. Unreadable archive + successful startup → explicit
+  startup failure; restore the writer's read access before opening the journal.
+  Corrupt rows themselves are reported through recovery status. → ADR 0219.
+
+**Who must act:** operators using single-file retention with a potentially torn
+active file, or retaining archives the writer cannot read. Configure at least two
+slots for tail recovery and ensure read access to retained generations.
+
+### Added
+
+- `stitchkit/application/diagnostic-journal` — `readDiagnosticJournal` streams
+  finite file snapshots through an owner `eventSchema`, retaining at most
+  `maxLineBytes` of a row plus a fixed read chunk. It yields valid frames and
+  explicit anomalies with file, byte offset, line, reason and skipped-byte count;
+  filesystem errors throw separately. Complete frames without a final LF remain
+  readable with a tail warning. Symlinks and non-regular paths are refused.
+- `stitchkit/application` — schema-backed anomaly/read-result/recovery contracts
+  and `DiagnosticJournalRecoveryError`. Reviewed surface budgets increase by
+  seven pure exports here and two reader exports in the filesystem leaf. → ADR 0219.
+
+### Fixed
+
+- Diagnostic journal startup inspects active and retained generations under the
+  exclusive lock. `getStatus().recovery` reports bounded startup observations of
+  damaged rows; another start reconstructs them from the preserved files. A torn
+  active file still rotates intact under the configured retention policy.
+  With `maxFiles: 1`, startup throws `DiagnosticJournalRecoveryError` before
+  deleting active or archived evidence and releases the lock. Configure at least
+  two files to retain the torn file during recovery.
+- Diagnostic journal integer schemas use Zod's `.int()` without deprecated
+  `.safe()`; values outside the safe integer range remain rejected.
+
+## [0.102.0] — 2026-09-30
+
+### ⚠️ Breaking changes
+
+- `stitchkit/tools`, `stitchkit/tools/contract`, `stitchkit/cli` — **`view_file`
+  rejects JSON arrays encoded inside a `paths` string during input validation**,
+  before file or network access, with a hint to pass an array or one path.
+  Previously the text was accepted as one filename and failed with a misleading
+  media-extension refusal. `paths: '["image.png"]'` → `paths: ['image.png']`.
+  An encoded array inside an array element is refused too. Managed surfaces
+  return `VALIDATION_ERROR`; raw MCP reports an input-validation error. → ADR 0218.
+
+**Who must act:** callers that serialize the `paths` array into a string, or
+branch on the former media-extension error for that input. Pass a real array
+(or a single path string) and handle the validation error.
+
+### Fixed
+
+- `stitchkit/tools` — a local non-media extension refusal identifies the
+  caller's path and the extension it saw, without reading the file.
+
 ## [0.101.3] — 2026-09-29
 
 ### Fixed

package/dist/application/diagnostic-journal-contract.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { ExclusiveLockDiagnosis, ExclusiveLockOwner } from '../internal/exclusive-lock.js';
+export { type DiagnosticJournalFrame, DiagnosticJournalFrameSchema, } from './diagnostic-journal-frame.js';
 export declare const DiagnosticJournalLimitsSchema: z.ZodReadonly<z.ZodObject<{
     maxEventBytes: z.ZodNumber;
     maxPendingItems: z.ZodNumber;
@@ -78,6 +79,51 @@ export declare const DiagnosticJournalStatusSchema: z.ZodReadonly<z.ZodObject<{
     partialTails: z.ZodNumber;
     currentFileBytes: z.ZodNumber;
     retainedFiles: z.ZodNumber;
+    recovery: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        filesChecked: z.ZodNumber;
+        anomalies: z.ZodNumber;
+        skippedBytes: z.ZodNumber;
+        firstAnomaly: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+            file: z.ZodString;
+            offset: z.ZodNumber;
+            line: z.ZodNumber;
+            reason: z.ZodEnum<{
+                "invalid-event": "invalid-event";
+                "invalid-frame": "invalid-frame";
+                "invalid-json": "invalid-json";
+                "invalid-utf8": "invalid-utf8";
+                "nul-byte": "nul-byte";
+                "oversized-line": "oversized-line";
+                "unterminated-line": "unterminated-line";
+            }>;
+            position: z.ZodEnum<{
+                interior: "interior";
+                tail: "tail";
+            }>;
+            terminated: z.ZodBoolean;
+            skippedBytes: z.ZodNumber;
+        }, z.core.$strict>>>;
+        lastAnomaly: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+            file: z.ZodString;
+            offset: z.ZodNumber;
+            line: z.ZodNumber;
+            reason: z.ZodEnum<{
+                "invalid-event": "invalid-event";
+                "invalid-frame": "invalid-frame";
+                "invalid-json": "invalid-json";
+                "invalid-utf8": "invalid-utf8";
+                "nul-byte": "nul-byte";
+                "oversized-line": "oversized-line";
+                "unterminated-line": "unterminated-line";
+            }>;
+            position: z.ZodEnum<{
+                interior: "interior";
+                tail: "tail";
+            }>;
+            terminated: z.ZodBoolean;
+            skippedBytes: z.ZodNumber;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
     lastAcceptedSequence: z.ZodOptional<z.ZodNumber>;
     lastWrittenSequence: z.ZodOptional<z.ZodNumber>;
     lastSettledSequence: z.ZodOptional<z.ZodNumber>;
@@ -138,13 +184,6 @@ export declare const DiagnosticJournalCloseResultSchema: z.ZodReadonly<z.ZodObje
     pendingItems: z.ZodNumber;
 }, z.core.$strict>>;
 export type DiagnosticJournalCloseResult = z.infer<typeof DiagnosticJournalCloseResultSchema>;
-export declare const DiagnosticJournalFrameSchema: z.ZodReadonly<z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    epoch: z.ZodUUID;
-    sequence: z.ZodNumber;
-    event: z.ZodJSONSchema;
-}, z.core.$strict>>;
-export type DiagnosticJournalFrame = z.infer<typeof DiagnosticJournalFrameSchema>;
 export interface DiagnosticJournalWaitOptions {
     readonly signal?: AbortSignal;
     readonly timeoutMs?: number;

package/dist/application/diagnostic-journal-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostic-journal-contract.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"diagnostic-journal-contract.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-contract.ts"],"names":[],"mappings":"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"}

package/dist/application/diagnostic-journal-frame.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+export declare const DiagnosticJournalFrameSchema: z.ZodReadonly<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    epoch: z.ZodUUID;
+    sequence: z.ZodNumber;
+    event: z.ZodJSONSchema;
+}, z.core.$strict>>;
+export type DiagnosticJournalFrame = z.infer<typeof DiagnosticJournalFrameSchema>;
+//# sourceMappingURL=diagnostic-journal-frame.d.ts.map

package/dist/application/diagnostic-journal-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-journal-frame.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-frame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,4BAA4B;;;;;mBAQ5B,CAAC;AACd,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC"}

package/dist/application/diagnostic-journal-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostic-journal-manager.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,wBAAwB,EAG7B,KAAK,uBAAuB,EAI5B,KAAK,uBAAuB,EAK7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,8BAA8B,CAAC;AAEtC,UAAU,8BAA8B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAyDD,wBAAgB,8BAA8B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EACrE,MAAM,EAAE,8BAA8B,CAAC,MAAM,CAAC,EAC9C,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAiMpC"}
+{"version":3,"file":"diagnostic-journal-manager.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,wBAAwB,EAG7B,KAAK,uBAAuB,EAI5B,KAAK,uBAAuB,EAK7B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,8BAA8B,CAAC;AAEtC,UAAU,8BAA8B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAyDD,wBAAgB,8BAA8B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EACrE,MAAM,EAAE,8BAA8B,CAAC,MAAM,CAAC,EAC9C,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAkMpC"}

package/dist/application/diagnostic-journal-read-contract.d.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+export declare const DiagnosticJournalAnomalySchema: z.ZodReadonly<z.ZodObject<{
+    file: z.ZodString;
+    offset: z.ZodNumber;
+    line: z.ZodNumber;
+    reason: z.ZodEnum<{
+        "invalid-event": "invalid-event";
+        "invalid-frame": "invalid-frame";
+        "invalid-json": "invalid-json";
+        "invalid-utf8": "invalid-utf8";
+        "nul-byte": "nul-byte";
+        "oversized-line": "oversized-line";
+        "unterminated-line": "unterminated-line";
+    }>;
+    position: z.ZodEnum<{
+        interior: "interior";
+        tail: "tail";
+    }>;
+    terminated: z.ZodBoolean;
+    skippedBytes: z.ZodNumber;
+}, z.core.$strict>>;
+export type DiagnosticJournalAnomaly = z.infer<typeof DiagnosticJournalAnomalySchema>;
+export declare function createDiagnosticJournalReadResultSchema<SCHEMA extends z.ZodType>(eventSchema: SCHEMA): z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    file: z.ZodString;
+    offset: z.ZodNumber;
+    line: z.ZodNumber;
+    type: z.ZodLiteral<"frame">;
+    bytes: z.ZodNumber;
+    frame: z.ZodReadonly<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        epoch: z.ZodUUID;
+        sequence: z.ZodNumber;
+        event: SCHEMA;
+    }, z.core.$strict>>;
+}, z.core.$strict>>, z.ZodReadonly<z.ZodObject<{
+    type: z.ZodLiteral<"anomaly">;
+    anomaly: z.ZodReadonly<z.ZodObject<{
+        file: z.ZodString;
+        offset: z.ZodNumber;
+        line: z.ZodNumber;
+        reason: z.ZodEnum<{
+            "invalid-event": "invalid-event";
+            "invalid-frame": "invalid-frame";
+            "invalid-json": "invalid-json";
+            "invalid-utf8": "invalid-utf8";
+            "nul-byte": "nul-byte";
+            "oversized-line": "oversized-line";
+            "unterminated-line": "unterminated-line";
+        }>;
+        position: z.ZodEnum<{
+            interior: "interior";
+            tail: "tail";
+        }>;
+        terminated: z.ZodBoolean;
+        skippedBytes: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>>], "type">;
+export type DiagnosticJournalReadResult<SCHEMA extends z.ZodType> = z.output<ReturnType<typeof createDiagnosticJournalReadResultSchema<SCHEMA>>>;
+export declare const DiagnosticJournalRecoveryStatusSchema: z.ZodReadonly<z.ZodObject<{
+    filesChecked: z.ZodNumber;
+    anomalies: z.ZodNumber;
+    skippedBytes: z.ZodNumber;
+    firstAnomaly: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        file: z.ZodString;
+        offset: z.ZodNumber;
+        line: z.ZodNumber;
+        reason: z.ZodEnum<{
+            "invalid-event": "invalid-event";
+            "invalid-frame": "invalid-frame";
+            "invalid-json": "invalid-json";
+            "invalid-utf8": "invalid-utf8";
+            "nul-byte": "nul-byte";
+            "oversized-line": "oversized-line";
+            "unterminated-line": "unterminated-line";
+        }>;
+        position: z.ZodEnum<{
+            interior: "interior";
+            tail: "tail";
+        }>;
+        terminated: z.ZodBoolean;
+        skippedBytes: z.ZodNumber;
+    }, z.core.$strict>>>;
+    lastAnomaly: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        file: z.ZodString;
+        offset: z.ZodNumber;
+        line: z.ZodNumber;
+        reason: z.ZodEnum<{
+            "invalid-event": "invalid-event";
+            "invalid-frame": "invalid-frame";
+            "invalid-json": "invalid-json";
+            "invalid-utf8": "invalid-utf8";
+            "nul-byte": "nul-byte";
+            "oversized-line": "oversized-line";
+            "unterminated-line": "unterminated-line";
+        }>;
+        position: z.ZodEnum<{
+            interior: "interior";
+            tail: "tail";
+        }>;
+        terminated: z.ZodBoolean;
+        skippedBytes: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export type DiagnosticJournalRecoveryStatus = z.infer<typeof DiagnosticJournalRecoveryStatusSchema>;
+/** A single-file retention policy cannot preserve the torn file during startup rotation. */
+export declare class DiagnosticJournalRecoveryError extends Error {
+    readonly recovery: DiagnosticJournalRecoveryStatus;
+    constructor(recovery: DiagnosticJournalRecoveryStatus);
+}
+//# sourceMappingURL=diagnostic-journal-read-contract.d.ts.map

package/dist/application/diagnostic-journal-read-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-journal-read-contract.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-read-contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;mBAgB9B,CAAC;AACd,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,wBAAgB,uCAAuC,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EAC9E,WAAW,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8BAepB;AACD,MAAM,MAAM,2BAA2B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAC1E,UAAU,CAAC,OAAO,uCAAuC,CAAC,MAAM,CAAC,CAAC,CACnE,CAAC;AAEF,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBASrC,CAAC;AACd,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACnD,OAAO,qCAAqC,CAC7C,CAAC;AAEF,4FAA4F;AAC5F,qBAAa,8BAA+B,SAAQ,KAAK;aAC3B,QAAQ,EAAE,+BAA+B;IAArE,YAA4B,QAAQ,EAAE,+BAA+B,EAGpE;CACF"}

package/dist/application/diagnostic-journal-reader.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import { type DiagnosticJournalReadResult } from './diagnostic-journal-read-contract.js';
+export interface DiagnosticJournalReaderConfig<SCHEMA extends z.ZodType> {
+    /** Explicit operator-owned files, read in this order; missing files are I/O errors. */
+    readonly paths: readonly string[];
+    readonly eventSchema: SCHEMA;
+    /** Maximum JSONL body bytes retained in memory, excluding its LF. */
+    readonly maxLineBytes: number;
+    readonly signal?: AbortSignal;
+}
+/** One finite file snapshot at a time. Corrupt rows are data; filesystem failures throw. */
+export declare function readDiagnosticJournal<SCHEMA extends z.ZodType>(config: DiagnosticJournalReaderConfig<SCHEMA>): AsyncGenerator<DiagnosticJournalReadResult<SCHEMA>, void, unknown>;
+//# sourceMappingURL=diagnostic-journal-reader.d.ts.map

package/dist/application/diagnostic-journal-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-journal-reader.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-reader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,oCAAoC,CAAC;AAE5C,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO;IACrE,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAoFD,4FAA4F;AAC5F,wBAAuB,qBAAqB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,EACnE,MAAM,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC5C,cAAc,CAAC,2BAA2B,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAsFpE"}

package/dist/application/diagnostic-journal-recovery.d.ts

@@ -0,0 +1,4 @@
+import { type DiagnosticJournalRecoveryStatus } from './diagnostic-journal-read-contract.js';
+/** Disk evidence is the persistent source; only counters and two locations are retained. */
+export declare function inspectDiagnosticJournalRecovery(paths: readonly string[], maxLineBytes: number): Promise<DiagnosticJournalRecoveryStatus>;
+//# sourceMappingURL=diagnostic-journal-recovery.d.ts.map

package/dist/application/diagnostic-journal-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostic-journal-recovery.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-recovery.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,+BAA+B,EAErC,MAAM,oCAAoC,CAAC;AAG5C,4FAA4F;AAC5F,wBAAsB,gCAAgC,CACpD,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,+BAA+B,CAAC,CAuB1C"}

package/dist/application/diagnostic-journal-storage.d.ts

@@ -1,9 +1,11 @@
 import type { DiagnosticJournalFailurePhase, DiagnosticJournalLockPolicy } from './diagnostic-journal-contract.js';
+import { type DiagnosticJournalRecoveryStatus } from './diagnostic-journal-read-contract.js';
 export interface DiagnosticJournalStorageSnapshot {
     readonly currentFileBytes: number;
     readonly retainedFiles: number;
     readonly rotations: number;
     readonly partialTails: number;
+    readonly recovery?: DiagnosticJournalRecoveryStatus;
 }
 export interface DiagnosticJournalStorageAppendResult extends DiagnosticJournalStorageSnapshot {
     readonly rotated: boolean;

package/dist/application/diagnostic-journal-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostic-journal-storage.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-storage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oCACf,SAAQ,gCAAgC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,oCAAoC,CAAC,CAAC;IACzE,QAAQ,IAAI,gCAAgC,CAAC;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,KAAK,EAAE,6BAA6B;IADtD,YACkB,KAAK,EAAE,6BAA6B,EACpD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AA4CD,oFAAoF;AACpF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,wBAAwB,CAAC,CAsJnC"}
+{"version":3,"file":"diagnostic-journal-storage.d.ts","sourceRoot":"","sources":["../../src/application/diagnostic-journal-storage.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,6BAA6B,EAC7B,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,oCAAoC,CAAC;AAG5C,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,+BAA+B,CAAC;CACrD;AAED,MAAM,WAAW,oCACf,SAAQ,gCAAgC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,oCAAoC,CAAC,CAAC;IACzE,QAAQ,IAAI,gCAAgC,CAAC;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,KAAK,EAAE,6BAA6B;IADtD,YACkB,KAAK,EAAE,6BAA6B,EACpD,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF;AAED,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AA4CD,oFAAoF;AACpF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,wBAAwB,CAAC,CA8KnC"}

package/dist/entrypoints/application/diagnostic-journal.d.ts

@@ -18,4 +18,5 @@
  * → ADR 0156.
  */
 export { createDiagnosticJournal } from '../../application/diagnostic-journal.js';
+export { type DiagnosticJournalReaderConfig, readDiagnosticJournal, } from '../../application/diagnostic-journal-reader.js';
 //# sourceMappingURL=diagnostic-journal.d.ts.map

package/dist/entrypoints/application/diagnostic-journal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostic-journal.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/diagnostic-journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC"}
+{"version":3,"file":"diagnostic-journal.d.ts","sourceRoot":"","sources":["../../../src/entrypoints/application/diagnostic-journal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EACL,KAAK,6BAA6B,EAClC,qBAAqB,GACtB,MAAM,6CAA6C,CAAC"}