ushman-ledger 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -1,22 +1,12 @@
 # Changelog
 
-## [1.0.0] - 2026-05-14
-
-- Added structured patch payloads with touched paths, diff hashes, line hunks, and before/after file hashes.
-- Added UUIDv7-backed `validator-result` payload ids, structured `stage-transition` and `operator-decision` payloads, and the new first-class ledger kinds required by ushman v4.1 analytics.
-- Added cached `render --to=analytics-summary` output, legacy-entry read migration markers, and write-side builder helpers for the structured record kinds.
+## [1.0.1] - 2026-05-16
 
-### Breaking changes
+- Tightened the schema surface to the ledger primitives the v4 orchestrator actively uses.
 
-- New `operator-decision` writes must use the structured `payload.action` and `payload.rationale` fields.
-- Stored `validator-result` entries now persist `payload.id`; helper-side synthesis is only a temporary migration convenience.
-- Structured patch writes now enforce the machine-readable payload fields instead of accepting prose-only patch metadata.
-
-## [0.2.0] - 2026-05-14
+## [1.0.0] - 2026-05-14
 
-- Added durable `read-index.json` sidecar rebuilds and persisted coverage indexing for large-ledger scans.
-- Made archive creation crash-recoverable with pending archive journals and post-create tar verification.
-- Added archive recovery tests, read-index rebuild tests, and a manual scale benchmark harness.
+- First stable release: structured `operator-decision`, `strip-decision-reverted`, and `validator-result` payloads; durable read-index sidecar with crash-recoverable archive creation.
 
 ## [0.1.0] - 2026-05-12
 

package/README.md

@@ -5,11 +5,10 @@ Append-only workspace ledger library and CLI for ushman v4 workspaces.
 ## What it owns
 
 - Ledger entry schemas
-- Structured patch / validator / stage payloads for analytics consumers
 - Serialized manifest-safe entry writes
 - Content-hash idempotency
 - Patch blob storage
-- Retro / JSONL / timeline rendering
+- Retro / JSONL / timeline / dependency-graph rendering
 - Archive integrity output
 - Doctor and coverage helpers
 
@@ -59,7 +58,6 @@ await ledger.record(
 );
 
 await ledger.render({ to: 'retro' });
-await ledger.render({ to: 'analytics-summary' });
 await ledger.archive('/tmp/ledger.tgz');
 ```
 
@@ -74,20 +72,17 @@ ushman-ledger list --workspace=<ws> --json
 ushman-ledger render --workspace=<ws> --to=retro
 ushman-ledger render --workspace=<ws> --to=jsonl --out=/tmp/ledger.jsonl
 ushman-ledger render --workspace=<ws> --to=dependency-graph --out=/tmp/ledger.mmd
-ushman-ledger render --workspace=<ws> --to=analytics-summary
-ushman-ledger render --workspace=<ws> --to=analytics-summary --fresh
-ushman-ledger render --workspace=<ws> --to=analytics-summary --json
 ushman-ledger archive --workspace=<ws> --out=/tmp/ledger.tgz
 ushman-ledger doctor --workspace=<ws>
 ```
 
-Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `stage-transition`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `descope-brief`, `merge-return`, `merge-return-rejected`, `revert`, `rollback`, `rework.test_retired`
+Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`
 
 Valid phases: `capture`, `intake`, `seed`, `vendor-extract`, `cleanup`, `parity`, `characterize`, `equiv`, `analyze`, `recover`, `ship`, `migration`
 
 Valid note subkinds: `regression`, `automation`, `retro`, `operator`, `tooling-gap`
 
-Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `analytics-summary`
+Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`
 
 ## Workspace prerequisite
 
@@ -99,53 +94,12 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `an
 - With `idempotencyKey`, the key is authoritative within a phase. Reusing the same key with different content in the same phase returns the first recorded entry unchanged.
 - Stored entries copy the idempotency key into `links.idempotencyKey` for auditability.
 
-## Structured payloads
-
-- Patch entries (`agent-patch`, `operator-patch`) store `payload.touchedPaths`, `payload.fileSha256Before`, `payload.fileSha256After`, `payload.hunks`, `payload.diffSha256`, and `payload.diff`.
-- Stored `validator-result` entries require a UUIDv7 `payload.id`. Callers should provide it in normal operation; the write helpers only synthesize one during the migration window when legacy callers omit it.
-- `stage-transition` entries capture `{ stage, startedAt, endedAt, exitCode, doctorBaselineId? }` explicitly in the ledger.
-- `operator-decision` entries capture `{ action, checkId?, rationale }` in `payload`.
-- `rework.test_retired` is the structured way to retire a seed-emitted test from the pipeline corpus.
-- Legacy on-disk entries still read successfully. The library normalizes them into the current shape and marks them with `_legacy: true`.
-
-Example payloads:
-
-```json
-{
-  "kind": "stage-transition",
-  "payload": {
-    "stage": "cleanup",
-    "startedAt": "2026-05-14T12:00:00.000Z",
-    "endedAt": "2026-05-14T12:00:05.000Z",
-    "exitCode": 0
-  }
-}
-```
-
-```json
-{
-  "kind": "rework.test_retired",
-  "payload": {
-    "removedTestPath": "tests/pure/app.test.ts",
-    "removedTestSymbols": ["renderApp"],
-    "removedBy": "descope",
-    "sourceSymbolDeletedFrom": "src/app.ts"
-  }
-}
-```
-
-## Migration guide
-
-- Historical entries are not rewritten. Old on-disk entries continue to load through read-side normalization.
-- Normalized legacy entries are marked with `_legacy: true` so analytics can distinguish migrated reads from fully structured writes.
-- New writes are expected to use structured payloads. Temporary compatibility logic only remains for omitted `validator-result.payload.id` values.
-
-## Analytics summary
+## Payload shapes
 
-- `render --to=analytics-summary` emits a compact JSON envelope for downstream analytics consumers.
-- The summary is cached at `.lab/ledger/analytics-summary.json` and invalidates automatically when the ledger tip changes.
-- `render --to=analytics-summary --fresh` bypasses the cache and recomputes the envelope for one-off verification.
-- `render --to=analytics-summary --json` remains as a compatibility alias for `--fresh`.
+- `operator-decision` entries capture `{ action, checkId?, rationale }` in `payload`. `action` is one of `bypass-doctor`, `skip-check`, `override-strip-decision`, `override-ship-state`, `manual-parity-assertion`, `ledger-hand-edit`, `escalation`.
+- `strip-decision-reverted` entries capture `{ stripDecisionId, rationale, invalidatedStages? }`.
+- `correction` entries require `links.correctsLedgerId` pointing at the entry they correct.
+- Patch entries (`agent-patch`, `operator-patch`) store a `diff` blob reference and a `rationale`. Patch text is stored once under `.lab/ledger/blobs/` and shared by hash.
 
 ## Links and coverage
 
@@ -176,7 +130,6 @@ Example payloads:
 
 - `.lab/ledger/pending/` contains append journals that let the ledger recover incomplete writes after crashes. Do not edit these files by hand.
 - If startup or `doctor` reports a pending commit mismatch, re-open the ledger or rerun the command first so reconciliation can replay or discard the journal safely.
-- If `analytics-summary.json` is invalid or stale, rerun `ushman-ledger render --to=analytics-summary --fresh` to recompute it from the ledger tip.
 - If `doctor` reports manifest or blob corruption, fix the underlying entry/blob mismatch first and rerun `doctor` before attempting `archive`.
 
 ## Scan behavior
@@ -205,7 +158,6 @@ Example payloads:
 ```text
 <ws>/.lab/ledger/
   .manifest.lock
-  analytics-summary.json
   manifest.json
   read-index.json
   pending/

package/dist/archive-journal.d.ts

@@ -1,14 +1,14 @@
-import { z } from 'zod';
+import * as v from 'valibot';
 import type { LedgerManifest } from './schema/manifest.ts';
-export declare const ArchiveManifestSchema: z.ZodObject<{
-    fileHashes: z.ZodArray<z.ZodObject<{
-        path: z.ZodString;
-        sha256: z.ZodString;
-    }, z.core.$strip>>;
-    integrityHash: z.ZodString;
-    schemaVersion: z.ZodLiteral<"ushman-ledger-archive-manifest/v1">;
-}, z.core.$strip>;
-export type ArchiveManifest = z.infer<typeof ArchiveManifestSchema>;
+export declare const ArchiveManifestSchema: v.ObjectSchema<{
+    readonly fileHashes: v.ArraySchema<v.ObjectSchema<{
+        readonly path: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly sha256: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 64, undefined>]>;
+    }, undefined>, undefined>;
+    readonly integrityHash: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 64, undefined>]>;
+    readonly schemaVersion: v.LiteralSchema<"ushman-ledger-archive-manifest/v1", undefined>;
+}, undefined>;
+export type ArchiveManifest = v.InferOutput<typeof ArchiveManifestSchema>;
 export declare const collectFileHashes: (root: string, prefix?: string) => Promise<Array<{
     path: string;
     sha256: string;
@@ -40,7 +40,6 @@ export declare const reconcilePendingArchivesUnderLock: ({ manifest, workspaceRo
     readonly manifest: LedgerManifest;
     readonly workspaceRoot: string;
 }) => Promise<{
-    [x: string]: unknown;
     archives: {
         createdAt: string;
         integrityHash: string;
@@ -48,16 +47,28 @@ export declare const reconcilePendingArchivesUnderLock: ({ manifest, workspaceRo
     }[];
     createdAt: string;
     entryCount: number;
-    entryLocations: Record<string, {
-        phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
-        sequence: number;
-    }>;
-    idempotencyIndex: Record<string, Record<string, string>>;
+    entryLocations: {
+        [x: string]: {
+            phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+            sequence: number;
+        };
+    };
+    idempotencyIndex: {
+        [x: string]: {
+            [x: string]: string;
+        };
+    };
     lastSequence: number;
-    perPhaseCounts: Record<string, number>;
-    perPhaseLatest: Record<string, string>;
+    perPhaseCounts: {
+        [x: string]: number;
+    };
+    perPhaseLatest: {
+        [x: string]: string;
+    };
     schemaVersion: "ushman-ledger-manifest/v1";
     updatedAt: string;
     workspaceId: string;
+} & {
+    [key: string]: unknown;
 }>;
 //# sourceMappingURL=archive-journal.d.ts.map

package/dist/archive-journal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-journal.d.ts","sourceRoot":"","sources":["../src/archive-journal.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAW3D,eAAO,MAAM,qBAAqB;;;;;;;iBAIhC,CAAC;AASH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAyCpE,eAAO,MAAM,iBAAiB,GAC1B,MAAM,MAAM,EACZ,eAAW,KACZ,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAcjD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,YAAY,MAAM;;;;;;;EAO7D,CAAC;AA+DF,eAAO,MAAM,iBAAiB,GAAU,2CAGrC;IACC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,uBAAuB,EAAE,eAAe,CAAC;CACrD,kBA2BA,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,mCAG5C;IACC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,kBAMA,CAAC;AA4CF,eAAO,MAAM,mBAAmB,GAAU,yDAKvC;IACC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAgBA,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,kBAE1D,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAAU,8BAGrD;IACC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;;;;;;;;;;;;;;;;;;EA+CA,CAAC"}
+{"version":3,"file":"archive-journal.d.ts","sourceRoot":"","sources":["../src/archive-journal.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAC;AAG7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAW3D,eAAO,MAAM,qBAAqB;;;;;;;aAIhC,CAAC;AASH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAyC1E,eAAO,MAAM,iBAAiB,GAC1B,MAAM,MAAM,EACZ,eAAW,KACZ,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAcjD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,YAAY,MAAM;;;;;;;EAO7D,CAAC;AA+DF,eAAO,MAAM,iBAAiB,GAAU,2CAGrC;IACC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,uBAAuB,EAAE,eAAe,CAAC;CACrD,kBA2BA,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,mCAG5C;IACC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,kBAMA,CAAC;AA4CF,eAAO,MAAM,mBAAmB,GAAU,yDAKvC;IACC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAgBA,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,kBAE1D,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAAU,8BAGrD;IACC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CA,CAAC"}

package/dist/archive-journal.js

@@ -2,32 +2,32 @@ import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promise
 import os from 'node:os';
 import path from 'node:path';
 import { extract as extractTar } from 'tar';
-import { z } from 'zod';
+import * as v from 'valibot';
 import { sha256File, sha256Hex, stableStringify } from "./json.js";
 import { updateManifestForArchive } from "./manifest-update.js";
 import { resolveLedgerPaths, saveManifest, writeAtomicJsonFile } from "./storage/filesystem.js";
 const ARCHIVE_MANIFEST_SCHEMA_VERSION = 'ushman-ledger-archive-manifest/v1';
 const PENDING_ARCHIVE_SCHEMA_VERSION = 'ushman-ledger-pending-archive/v1';
-const ArchiveManifestFileHashSchema = z.object({
-    path: z.string().min(1),
-    sha256: z.string().length(64),
+const ArchiveManifestFileHashSchema = v.object({
+    path: v.pipe(v.string(), v.minLength(1)),
+    sha256: v.pipe(v.string(), v.length(64)),
 });
-export const ArchiveManifestSchema = z.object({
-    fileHashes: z.array(ArchiveManifestFileHashSchema),
-    integrityHash: z.string().length(64),
-    schemaVersion: z.literal(ARCHIVE_MANIFEST_SCHEMA_VERSION),
+export const ArchiveManifestSchema = v.object({
+    fileHashes: v.array(ArchiveManifestFileHashSchema),
+    integrityHash: v.pipe(v.string(), v.length(64)),
+    schemaVersion: v.literal(ARCHIVE_MANIFEST_SCHEMA_VERSION),
 });
-const PendingArchiveSchema = z.object({
+const PendingArchiveSchema = v.object({
     archiveManifest: ArchiveManifestSchema,
-    createdAt: z.string().datetime({ offset: true }),
-    outPath: z.string().min(1),
-    schemaVersion: z.literal(PENDING_ARCHIVE_SCHEMA_VERSION),
+    createdAt: v.pipe(v.string(), v.isoTimestamp()),
+    outPath: v.pipe(v.string(), v.minLength(1)),
+    schemaVersion: v.literal(PENDING_ARCHIVE_SCHEMA_VERSION),
 });
 const formatPendingArchiveId = (createdAt, outPath) => `${createdAt.replaceAll(':', '-').replaceAll('.', '-')}-${sha256Hex(outPath).slice(0, 12)}`;
 const buildPendingArchivePath = ({ createdAt, outPath, workspaceRoot, }) => path.join(resolveLedgerPaths(workspaceRoot).pendingArchivesDir, `${formatPendingArchiveId(createdAt, outPath)}.json`);
 const parsePendingArchiveText = (filePath, text) => {
     try {
-        return PendingArchiveSchema.parse(JSON.parse(text));
+        return v.parse(PendingArchiveSchema, JSON.parse(text));
     }
     catch (error) {
         throw new Error(`Invalid pending archive at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
@@ -35,7 +35,7 @@ const parsePendingArchiveText = (filePath, text) => {
 };
 const parseArchiveManifestText = (archivePath, text) => {
     try {
-        return ArchiveManifestSchema.parse(JSON.parse(text));
+        return v.parse(ArchiveManifestSchema, JSON.parse(text));
     }
     catch (error) {
         throw new Error(`Invalid archive manifest inside ${archivePath}: ${error instanceof Error ? error.message : String(error)}`);
@@ -58,7 +58,7 @@ export const collectFileHashes = async (root, prefix = '') => {
 };
 export const createArchiveManifest = async (ledgerRoot) => {
     const fileHashes = await collectFileHashes(ledgerRoot);
-    return ArchiveManifestSchema.parse({
+    return v.parse(ArchiveManifestSchema, {
         fileHashes,
         integrityHash: sha256Hex(stableStringify(fileHashes)),
         schemaVersion: ARCHIVE_MANIFEST_SCHEMA_VERSION,
@@ -125,7 +125,7 @@ export const verifyArchiveFile = async ({ archivePath, expectedArchiveManifest,
     }
 };
 export const writeArchiveManifestFile = async ({ archiveManifest, stagingRoot, }) => {
-    await writeFile(path.join(stagingRoot, 'archive-manifest.json'), `${stableStringify(ArchiveManifestSchema.parse(archiveManifest), true)}\n`, 'utf8');
+    await writeFile(path.join(stagingRoot, 'archive-manifest.json'), `${stableStringify(v.parse(ArchiveManifestSchema, archiveManifest), true)}\n`, 'utf8');
 };
 const readPendingArchive = async (filePath) => parsePendingArchiveText(filePath, await readFile(filePath, 'utf8'));
 const readPendingArchives = async (workspaceRoot) => {
@@ -163,7 +163,7 @@ export const writePendingArchive = async ({ archiveManifest, createdAt, outPath,
         outPath,
         workspaceRoot,
     });
-    await writeAtomicJsonFile(filePath, PendingArchiveSchema.parse({
+    await writeAtomicJsonFile(filePath, v.parse(PendingArchiveSchema, {
         archiveManifest,
         createdAt,
         outPath,