ushman-ledger 0.3.0

package/dist/read-index.d.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { type LedgerEntry, type LedgerKind, type LedgerPhase } from './schema/entry.ts';
+import type { LedgerManifest } from './schema/manifest.ts';
+declare const ReadIndexEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        "tool-invocation": "tool-invocation";
+        "agent-patch": "agent-patch";
+        "operator-patch": "operator-patch";
+        "stage-transition": "stage-transition";
+        "operator-decision": "operator-decision";
+        "validator-result": "validator-result";
+        "runtime-event": "runtime-event";
+        note: "note";
+        correction: "correction";
+        "strip-decision-reverted": "strip-decision-reverted";
+        "descope-brief": "descope-brief";
+        "merge-return": "merge-return";
+        "merge-return-rejected": "merge-return-rejected";
+        revert: "revert";
+        rollback: "rollback";
+        "rework.test_retired": "rework.test_retired";
+    }>;
+    ts: z.ZodString;
+}, z.core.$strip>;
+declare const LedgerReadIndexSchema: z.ZodObject<{
+    coveredFiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    entries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "tool-invocation": "tool-invocation";
+            "agent-patch": "agent-patch";
+            "operator-patch": "operator-patch";
+            "stage-transition": "stage-transition";
+            "operator-decision": "operator-decision";
+            "validator-result": "validator-result";
+            "runtime-event": "runtime-event";
+            note: "note";
+            correction: "correction";
+            "strip-decision-reverted": "strip-decision-reverted";
+            "descope-brief": "descope-brief";
+            "merge-return": "merge-return";
+            "merge-return-rejected": "merge-return-rejected";
+            revert: "revert";
+            rollback: "rollback";
+            "rework.test_retired": "rework.test_retired";
+        }>;
+        ts: z.ZodString;
+    }, z.core.$strip>>>;
+    entryCount: z.ZodNumber;
+    lastEntryId: z.ZodNullable<z.ZodString>;
+    lastSequence: z.ZodNumber;
+    schemaVersion: z.ZodLiteral<"ushman-ledger-read-index/v1">;
+}, z.core.$strip>;
+export type LedgerReadIndex = z.infer<typeof LedgerReadIndexSchema>;
+export type ReadIndexEntry = z.infer<typeof ReadIndexEntrySchema>;
+export type ManifestEntryLocation = readonly [string, {
+    phase: LedgerPhase;
+    sequence: number;
+}];
+export declare const buildReadIndexFromManifest: (workspaceRoot: string, manifest: LedgerManifest) => Promise<{
+    coveredFiles: string[];
+    entries: {
+        id: string;
+        kind: "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";
+        ts: string;
+    }[];
+    entryCount: number;
+    lastEntryId: string | null;
+    lastSequence: number;
+    schemaVersion: "ushman-ledger-read-index/v1";
+}>;
+export declare const isReadIndexCurrent: (index: LedgerReadIndex, manifest: LedgerManifest) => boolean;
+export declare const readReadIndex: (workspaceRoot: string) => Promise<LedgerReadIndex | null>;
+export declare const saveReadIndex: (workspaceRoot: string, readIndex: LedgerReadIndex) => Promise<void>;
+export declare const ensureReadIndexUnderLock: (workspaceRoot: string, manifest: LedgerManifest) => Promise<{
+    coveredFiles: string[];
+    entries: {
+        id: string;
+        kind: "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";
+        ts: string;
+    }[];
+    entryCount: number;
+    lastEntryId: string | null;
+    lastSequence: number;
+    schemaVersion: "ushman-ledger-read-index/v1";
+}>;
+export declare const appendEntryToReadIndex: ({ entry, readIndex, sequence, }: {
+    readonly entry: LedgerEntry;
+    readonly readIndex: LedgerReadIndex;
+    readonly sequence: number;
+}) => {
+    coveredFiles: string[];
+    entries: {
+        id: string;
+        kind: "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";
+        ts: string;
+    }[];
+    entryCount: number;
+    lastEntryId: string | null;
+    lastSequence: number;
+    schemaVersion: "ushman-ledger-read-index/v1";
+};
+export declare const matchesReadIndexFilter: ({ filter, manifest, readIndexEntry, }: {
+    readonly filter: {
+        readonly kind?: LedgerKind;
+        readonly phase?: LedgerPhase;
+        readonly since?: string;
+    };
+    readonly manifest: LedgerManifest;
+    readonly readIndexEntry: ReadIndexEntry;
+}) => boolean;
+export {};
+//# sourceMappingURL=read-index.d.ts.map

package/dist/read-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-index.d.ts","sourceRoot":"","sources":["../src/read-index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAgB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAoB,MAAM,mBAAmB,CAAC;AACxH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAO3D,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;iBAIxB,CAAC;AAEH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBrB,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AA0HhG,eAAO,MAAM,0BAA0B,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAuB/F,CAAC;AAYF,eAAO,MAAM,kBAAkB,GAAI,OAAO,eAAe,EAAE,UAAU,cAAc,YAG1C,CAAC;AAE1C,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAWzF,CAAC;AAEF,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,EAAE,WAAW,eAAe,kBAGpF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc;;;;;;;;;;;EAiB7F,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,iCAIpC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B;;;;;;;;;;;CAYA,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,uCAIpC;IACC,QAAQ,CAAC,MAAM,EAAE;QACb,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CAC3C,YAeA,CAAC"}

package/dist/read-index.js

@@ -0,0 +1,210 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { mapWithConcurrencyLimit } from "./async.js";
+import { stableStringify } from "./json.js";
+import { LEDGER_KINDS, parseLedgerEntry } from "./schema/entry.js";
+import { readPhaseEntryText, resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
+const READ_INDEX_SCHEMA_VERSION = 'ushman-ledger-read-index/v1';
+const ENTRY_READ_BATCH_SIZE = 32;
+const ENTRY_READ_CONCURRENCY = 16;
+const ReadIndexEntrySchema = z.object({
+    id: z.string().min(1),
+    kind: z.enum(LEDGER_KINDS),
+    ts: z.string().datetime({ offset: true }),
+});
+const LedgerReadIndexSchema = z
+    .object({
+    coveredFiles: z.array(z.string()).default([]),
+    entries: z.array(ReadIndexEntrySchema).default([]),
+    entryCount: z.number().int().nonnegative(),
+    lastEntryId: z.string().min(1).nullable(),
+    lastSequence: z.number().int().nonnegative(),
+    schemaVersion: z.literal(READ_INDEX_SCHEMA_VERSION),
+})
+    .superRefine((value, ctx) => {
+    if (value.entryCount !== value.entries.length) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'entryCount must match entries.length',
+            path: ['entryCount'],
+        });
+    }
+    const expectedLastEntryId = value.entries.at(-1)?.id ?? null;
+    if (value.lastEntryId !== expectedLastEntryId) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'lastEntryId must match the final indexed entry',
+            path: ['lastEntryId'],
+        });
+    }
+});
+const parseReadIndexText = (filePath, text) => {
+    try {
+        return LedgerReadIndexSchema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`Invalid ledger read index at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const buildReadIndexEntry = (entry) => ({
+    id: entry.id,
+    kind: entry.kind,
+    ts: entry.ts,
+});
+const sortBySequence = (left, right) => left[1].sequence - right[1].sequence;
+const getManifestSequenceLocations = (manifest) => Object.entries(manifest.entryLocations).sort(sortBySequence);
+const mergeSortedUniquePaths = (existingPaths, additionalPaths) => {
+    if (additionalPaths.length === 0) {
+        return [...existingPaths];
+    }
+    const normalizedAdditionalPaths = [...new Set(additionalPaths)].sort((left, right) => left.localeCompare(right));
+    const mergedPaths = [];
+    let existingIndex = 0;
+    let additionalIndex = 0;
+    while (existingIndex < existingPaths.length || additionalIndex < normalizedAdditionalPaths.length) {
+        const existingPath = existingPaths[existingIndex];
+        const additionalPath = normalizedAdditionalPaths[additionalIndex];
+        if (existingPath === undefined) {
+            mergedPaths.push(...normalizedAdditionalPaths.slice(additionalIndex));
+            break;
+        }
+        if (additionalPath === undefined) {
+            mergedPaths.push(...existingPaths.slice(existingIndex));
+            break;
+        }
+        const comparison = existingPath.localeCompare(additionalPath);
+        if (comparison < 0) {
+            mergedPaths.push(existingPath);
+            existingIndex += 1;
+            continue;
+        }
+        if (comparison > 0) {
+            mergedPaths.push(additionalPath);
+            additionalIndex += 1;
+            continue;
+        }
+        mergedPaths.push(existingPath);
+        existingIndex += 1;
+        additionalIndex += 1;
+    }
+    return mergedPaths;
+};
+const buildReadIndex = ({ coveredFiles, entries, lastSequence, }) => LedgerReadIndexSchema.parse({
+    coveredFiles,
+    entries,
+    entryCount: entries.length,
+    lastEntryId: entries.at(-1)?.id ?? null,
+    lastSequence,
+    schemaVersion: READ_INDEX_SCHEMA_VERSION,
+});
+const readIndexedEntry = async ({ entryId, phase, workspaceRoot, }) => {
+    const text = await readPhaseEntryText(workspaceRoot, phase, `${entryId}.json`);
+    return parseLedgerEntry(JSON.parse(text));
+};
+const readIndexedEntryBatch = async ({ entryLocations, workspaceRoot, }) => mapWithConcurrencyLimit(entryLocations, ENTRY_READ_CONCURRENCY, async ([entryId, location]) => readIndexedEntry({
+    entryId,
+    phase: location.phase,
+    workspaceRoot,
+}));
+const collectCoveredFiles = (entry, coveredFiles) => {
+    if (entry.kind !== 'agent-patch' && entry.kind !== 'operator-patch') {
+        return;
+    }
+    for (const affectedFile of entry.links.affectedFiles ?? []) {
+        coveredFiles.add(affectedFile);
+    }
+};
+export const buildReadIndexFromManifest = async (workspaceRoot, manifest) => {
+    const orderedEntryLocations = getManifestSequenceLocations(manifest);
+    const entries = [];
+    const coveredFiles = new Set();
+    for (let index = 0; index < orderedEntryLocations.length; index += ENTRY_READ_BATCH_SIZE) {
+        const batch = orderedEntryLocations.slice(index, index + ENTRY_READ_BATCH_SIZE);
+        const resolvedEntries = await readIndexedEntryBatch({
+            entryLocations: batch,
+            workspaceRoot,
+        });
+        for (const entry of resolvedEntries) {
+            entries.push(buildReadIndexEntry(entry));
+            collectCoveredFiles(entry, coveredFiles);
+        }
+    }
+    return buildReadIndex({
+        coveredFiles: [...coveredFiles].sort((left, right) => left.localeCompare(right)),
+        entries,
+        lastSequence: manifest.lastSequence,
+    });
+};
+const hasMatchingTailEntry = (index, manifest) => {
+    if (manifest.lastSequence === 0) {
+        return index.lastEntryId === null;
+    }
+    if (!index.lastEntryId) {
+        return false;
+    }
+    return manifest.entryLocations[index.lastEntryId]?.sequence === manifest.lastSequence;
+};
+export const isReadIndexCurrent = (index, manifest) => index.entryCount === manifest.entryCount &&
+    index.lastSequence === manifest.lastSequence &&
+    hasMatchingTailEntry(index, manifest);
+export const readReadIndex = async (workspaceRoot) => {
+    const filePath = resolveLedgerPaths(workspaceRoot).readIndexFile;
+    try {
+        const text = await readFile(filePath, 'utf8');
+        return parseReadIndexText(filePath, text);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+};
+export const saveReadIndex = async (workspaceRoot, readIndex) => {
+    const filePath = resolveLedgerPaths(workspaceRoot).readIndexFile;
+    await writeAtomicTextFile(filePath, `${stableStringify(LedgerReadIndexSchema.parse(readIndex), true)}\n`);
+};
+export const ensureReadIndexUnderLock = async (workspaceRoot, manifest) => {
+    let currentReadIndex = null;
+    try {
+        currentReadIndex = await readReadIndex(workspaceRoot);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith('Invalid ledger read index')) {
+            throw error;
+        }
+    }
+    if (currentReadIndex && isReadIndexCurrent(currentReadIndex, manifest)) {
+        return currentReadIndex;
+    }
+    const rebuiltReadIndex = await buildReadIndexFromManifest(workspaceRoot, manifest);
+    await saveReadIndex(workspaceRoot, rebuiltReadIndex);
+    return rebuiltReadIndex;
+};
+export const appendEntryToReadIndex = ({ entry, readIndex, sequence, }) => {
+    const nextEntries = [...readIndex.entries, buildReadIndexEntry(entry)];
+    const nextCoveredFiles = entry.kind === 'agent-patch' || entry.kind === 'operator-patch'
+        ? mergeSortedUniquePaths(readIndex.coveredFiles, entry.links.affectedFiles ?? [])
+        : [...readIndex.coveredFiles];
+    return buildReadIndex({
+        coveredFiles: nextCoveredFiles,
+        entries: nextEntries,
+        lastSequence: sequence,
+    });
+};
+export const matchesReadIndexFilter = ({ filter, manifest, readIndexEntry, }) => {
+    const manifestLocation = manifest.entryLocations[readIndexEntry.id];
+    if (!manifestLocation) {
+        return false;
+    }
+    if (filter.phase && manifestLocation.phase !== filter.phase) {
+        return false;
+    }
+    if (filter.kind && readIndexEntry.kind !== filter.kind) {
+        return false;
+    }
+    if (filter.since && readIndexEntry.ts < filter.since) {
+        return false;
+    }
+    return true;
+};

package/dist/record.d.ts

@@ -0,0 +1,25 @@
+import { type LedgerEntry } from './schema/entry.ts';
+import type { LedgerManifest } from './schema/manifest.ts';
+type AppendRecordTestHooks = {
+    readonly afterEntryWrite?: (context: {
+        entry: LedgerEntry;
+    }) => Promise<void>;
+    readonly afterManifestSave?: (context: {
+        entry: LedgerEntry;
+    }) => Promise<void>;
+    readonly afterPendingCommitWrite?: (context: {
+        entry: LedgerEntry;
+        pendingCommitPath: string;
+    }) => Promise<void>;
+    readonly afterReadIndexSave?: (context: {
+        entry: LedgerEntry;
+    }) => Promise<void>;
+};
+export declare const setAppendRecordTestHooks: (workspaceRoot: string, hooks: AppendRecordTestHooks | null) => void;
+export declare const appendRecord: (workspaceRoot: string, input: unknown) => Promise<{
+    entry: LedgerEntry;
+    id: string;
+}>;
+export declare const readEntryById: (workspaceRoot: string, manifest: LedgerManifest, entryId: string) => Promise<LedgerEntry>;
+export {};
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAQA,OAAO,EAEH,KAAK,WAAW,EAQnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAW3D,KAAK,qBAAqB,GAAG;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpF,CAAC;AAuBF,eAAO,MAAM,wBAAwB,GAAI,eAAe,MAAM,EAAE,OAAO,qBAAqB,GAAG,IAAI,SAOlG,CAAC;AAgNF,eAAO,MAAM,YAAY,GACrB,eAAe,MAAM,EACrB,OAAO,OAAO,KACf,OAAO,CAAC;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAqF5C,CAAC;AAEF,eAAO,MAAM,aAAa,GACtB,eAAe,MAAM,EACrB,UAAU,cAAc,EACxB,SAAS,MAAM,KAChB,OAAO,CAAC,WAAW,CAUrB,CAAC"}

package/dist/record.js

@@ -0,0 +1,268 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveBlobPath, storePatchBlob } from "./blobs.js";
+import { sha256Hex, stableStringify } from "./json.js";
+import { updateManifestForEntry } from "./manifest-update.js";
+import { derivePatchPayloadFromDiffText } from "./patch-metadata.js";
+import { appendEntryToReadIndex, saveReadIndex } from "./read-index.js";
+import { reconcileLedgerStateUnderLock, removePendingCommit, writePendingCommit } from "./recovery.js";
+import { LedgerEntrySchema, OperatorDecisionPayloadSchema, PatchPayloadWriteSchema, parseLedgerEntry, parseLedgerRecord, ValidatorResultPayloadSchema, } from "./schema/entry.js";
+import { ensureLedgerDirectories, readManifest, resolveLedgerPaths, saveManifest, writeEntryFile, } from "./storage/filesystem.js";
+import { acquireLock } from "./storage/lock.js";
+import { createDeterministicUuidV7 } from "./uuid.js";
+const appendRecordTestHooks = new Map();
+const resolveWorkspaceKey = (workspaceRoot) => path.resolve(workspaceRoot);
+const getAppendRecordTestHooks = (workspaceRoot) => appendRecordTestHooks.get(resolveWorkspaceKey(workspaceRoot));
+const warnedDeprecations = new Set();
+const warnOnce = (key, message) => {
+    if (warnedDeprecations.has(key)) {
+        return;
+    }
+    warnedDeprecations.add(key);
+    process.emitWarning(message, {
+        code: key,
+        type: 'DeprecationWarning',
+    });
+};
+export const setAppendRecordTestHooks = (workspaceRoot, hooks) => {
+    const key = resolveWorkspaceKey(workspaceRoot);
+    if (!hooks) {
+        appendRecordTestHooks.delete(key);
+        return;
+    }
+    appendRecordTestHooks.set(key, hooks);
+};
+const readBlobText = async (workspaceRoot, diff) => readFile(resolveBlobPath(workspaceRoot, diff.blobSha256), 'utf8');
+const addIdempotencyMetadata = (record) => {
+    if (!record.idempotencyKey) {
+        return record;
+    }
+    return {
+        ...record,
+        links: {
+            ...record.links,
+            idempotencyKey: record.idempotencyKey,
+        },
+    };
+};
+const buildLogicalHash = (record) => {
+    if (record.idempotencyKey) {
+        return `key:${record.idempotencyKey}`;
+    }
+    return sha256Hex(stableStringify(record));
+};
+const fingerprintManifest = (manifest) => sha256Hex(stableStringify(manifest));
+const assertManifestFingerprint = async ({ expectedFingerprint, manifestPath, workspaceRoot, }) => {
+    const currentManifest = await readManifest(workspaceRoot);
+    const currentFingerprint = fingerprintManifest(currentManifest);
+    if (currentFingerprint !== expectedFingerprint) {
+        throw new Error(`Ledger manifest changed while holding ${manifestPath}; aborting append so recovery can replay safely.`);
+    }
+};
+const toEntryIdTimestamp = (timestamp) => timestamp.replaceAll(':', '-').replaceAll('.', '-');
+const buildEntryId = (entryWithoutId, sequence) => {
+    const bodyHash = sha256Hex(stableStringify(entryWithoutId));
+    return `${toEntryIdTimestamp(entryWithoutId.ts)}-${sequence.toString().padStart(8, '0')}-${bodyHash.slice(0, 12)}`;
+};
+const normalizeValidatorResultRecord = (record) => {
+    if (record.kind !== 'validator-result') {
+        return record;
+    }
+    const payloadId = record.payload?.id;
+    if (payloadId) {
+        return {
+            ...record,
+            payload: ValidatorResultPayloadSchema.parse(record.payload),
+        };
+    }
+    warnOnce('USHMAN_LEDGER_VALIDATOR_ID_COMPAT', 'validator-result records should provide payload.id. A compatibility UUIDv7 was synthesized for this append.');
+    return {
+        ...record,
+        payload: {
+            id: createDeterministicUuidV7({
+                seed: stableStringify(record),
+                timestamp: 0,
+            }),
+        },
+    };
+};
+const resolvePatchTextAndBlob = async ({ record, workspaceRoot, }) => {
+    if (record.diffPath) {
+        const patchText = await readFile(path.resolve(record.diffPath), 'utf8');
+        return {
+            patchText,
+            storedDiff: await storePatchBlob(workspaceRoot, patchText),
+        };
+    }
+    if (record.payload?.diff) {
+        const storedDiff = await storePatchBlob(workspaceRoot, record.payload.diff);
+        if (record.diff && record.diff.blobSha256 !== storedDiff.blobSha256) {
+            throw new Error(`Provided diff blob ${record.diff.blobSha256} does not match payload.diff hash ${storedDiff.blobSha256}.`);
+        }
+        return {
+            patchText: record.payload.diff,
+            storedDiff,
+        };
+    }
+    if (!record.diff) {
+        throw new Error(`${record.kind} records require payload.diff, diffPath, or diff metadata.`);
+    }
+    try {
+        const patchText = await readBlobText(workspaceRoot, record.diff);
+        return {
+            patchText,
+            storedDiff: record.diff,
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Patch blob ${record.diff.blobSha256} was not found. Store it first or use diffPath.`);
+        }
+        throw error;
+    }
+};
+const resolvePatchPayload = async ({ patchText, record, workspaceRoot, }) => {
+    const derivedPayload = await derivePatchPayloadFromDiffText({
+        patchText,
+        workspaceRoot,
+    });
+    const mergedPayload = PatchPayloadWriteSchema.parse({
+        ...derivedPayload,
+        ...record.payload,
+        diff: record.payload?.diff ?? patchText,
+        diffSha256: record.payload?.diffSha256 ?? derivedPayload.diffSha256,
+        fileSha256After: record.payload?.fileSha256After ?? derivedPayload.fileSha256After,
+        fileSha256Before: record.payload?.fileSha256Before ?? derivedPayload.fileSha256Before,
+        hunks: record.payload?.hunks ?? derivedPayload.hunks,
+        touchedPaths: record.payload?.touchedPaths ?? derivedPayload.touchedPaths,
+    });
+    return mergedPayload;
+};
+const resolvePatchRecord = async ({ record, workspaceRoot, }) => {
+    const { patchText, storedDiff } = await resolvePatchTextAndBlob({
+        record,
+        workspaceRoot,
+    });
+    const payload = await resolvePatchPayload({
+        patchText,
+        record,
+        workspaceRoot,
+    });
+    if (payload.diffSha256 !== storedDiff.blobSha256) {
+        throw new Error(`Patch payload hash ${payload.diffSha256} does not match stored blob hash ${storedDiff.blobSha256}.`);
+    }
+    return {
+        ...record,
+        diff: storedDiff,
+        links: {
+            ...record.links,
+            affectedFiles: [...new Set([...(record.links?.affectedFiles ?? []), ...payload.touchedPaths])],
+            blobs: [...new Set([...(record.links?.blobs ?? []), storedDiff.blobSha256])],
+        },
+        payload,
+    };
+};
+const normalizeRecord = async ({ record, workspaceRoot, }) => {
+    const normalizedRecord = normalizeValidatorResultRecord(record);
+    if (normalizedRecord.kind === 'agent-patch' || normalizedRecord.kind === 'operator-patch') {
+        return resolvePatchRecord({
+            record: normalizedRecord,
+            workspaceRoot,
+        });
+    }
+    return normalizedRecord.kind === 'operator-decision'
+        ? {
+            ...normalizedRecord,
+            payload: OperatorDecisionPayloadSchema.parse(normalizedRecord.payload),
+        }
+        : normalizedRecord;
+};
+export const appendRecord = async (workspaceRoot, input) => {
+    const parsed = parseLedgerRecord(input);
+    const recordWithMetadata = addIdempotencyMetadata(parsed);
+    const normalizedRecord = await normalizeRecord({
+        record: recordWithMetadata,
+        workspaceRoot,
+    });
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const lock = await acquireLock(paths.manifestLockFile);
+    try {
+        const { manifest, readIndex } = await reconcileLedgerStateUnderLock(workspaceRoot);
+        const manifestFingerprint = fingerprintManifest(manifest);
+        const keyedLogicalHash = parsed.idempotencyKey ? buildLogicalHash(recordWithMetadata) : null;
+        if (keyedLogicalHash) {
+            const existingId = manifest.idempotencyIndex[parsed.phase]?.[keyedLogicalHash];
+            if (existingId) {
+                return {
+                    entry: await readEntryById(workspaceRoot, manifest, existingId),
+                    id: existingId,
+                };
+            }
+        }
+        await lock.assertOwnership();
+        await assertManifestFingerprint({
+            expectedFingerprint: manifestFingerprint,
+            manifestPath: paths.manifestLockFile,
+            workspaceRoot,
+        });
+        const logicalHash = keyedLogicalHash ?? buildLogicalHash(normalizedRecord);
+        const existingId = manifest.idempotencyIndex[normalizedRecord.phase]?.[logicalHash];
+        if (existingId) {
+            return {
+                entry: await readEntryById(workspaceRoot, manifest, existingId),
+                id: existingId,
+            };
+        }
+        const nextSequence = manifest.lastSequence + 1;
+        const { idempotencyKey: _idempotencyKey, ...recordWithoutIdempotencyKey } = normalizedRecord;
+        const entryWithoutId = {
+            ...recordWithoutIdempotencyKey,
+            links: recordWithoutIdempotencyKey.links ?? {},
+            prevEntryId: manifest.perPhaseLatest[normalizedRecord.phase] ?? null,
+            schemaVersion: 'ushman-ledger-entry/v1',
+            ts: new Date().toISOString(),
+        };
+        const entry = LedgerEntrySchema.parse({
+            ...entryWithoutId,
+            id: buildEntryId(entryWithoutId, nextSequence),
+        });
+        const testHooks = getAppendRecordTestHooks(workspaceRoot);
+        const pendingCommitPath = await writePendingCommit({
+            entry,
+            logicalHash,
+            manifest,
+            workspaceRoot,
+        });
+        await testHooks?.afterPendingCommitWrite?.({ entry, pendingCommitPath });
+        await writeEntryFile(workspaceRoot, entry.phase, `${entry.id}.json`, entry);
+        await testHooks?.afterEntryWrite?.({ entry });
+        await lock.assertOwnership();
+        await assertManifestFingerprint({
+            expectedFingerprint: manifestFingerprint,
+            manifestPath: paths.manifestLockFile,
+            workspaceRoot,
+        });
+        await saveManifest(workspaceRoot, updateManifestForEntry({ entry, logicalHash, manifest }));
+        await testHooks?.afterManifestSave?.({ entry });
+        await lock.assertOwnership();
+        await saveReadIndex(workspaceRoot, appendEntryToReadIndex({
+            entry,
+            readIndex,
+            sequence: nextSequence,
+        }));
+        await testHooks?.afterReadIndexSave?.({ entry });
+        await removePendingCommit(pendingCommitPath);
+        return { entry, id: entry.id };
+    }
+    finally {
+        await lock.release();
+    }
+};
+export const readEntryById = async (workspaceRoot, manifest, entryId) => {
+    const location = manifest.entryLocations[entryId];
+    if (!location) {
+        throw new Error(`Ledger entry not found: ${entryId}`);
+    }
+    const text = await readFile(path.join(resolveLedgerPaths(workspaceRoot).phaseDir(location.phase), `${entryId}.json`), 'utf8');
+    return parseLedgerEntry(JSON.parse(text));
+};

package/dist/recovery.d.ts

@@ -0,0 +1,39 @@
+import { type LedgerReadIndex } from './read-index.ts';
+import { type LedgerEntry } from './schema/entry.ts';
+import type { LedgerManifest } from './schema/manifest.ts';
+export type PreparedLedgerState = {
+    readonly manifest: LedgerManifest;
+    readonly readIndex: LedgerReadIndex;
+};
+export declare const writePendingCommit: ({ entry, logicalHash, manifest, workspaceRoot, }: {
+    readonly entry: LedgerEntry;
+    readonly logicalHash: string;
+    readonly manifest: LedgerManifest;
+    readonly workspaceRoot: string;
+}) => Promise<string>;
+export declare const removePendingCommit: (filePath: string) => Promise<void>;
+export declare const reconcilePendingCommitsUnderLock: (workspaceRoot: string) => Promise<{
+    [x: string]: unknown;
+    archives: {
+        createdAt: string;
+        integrityHash: string;
+        outPath: string;
+    }[];
+    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>>;
+    lastSequence: number;
+    perPhaseCounts: Record<string, number>;
+    perPhaseLatest: Record<string, string>;
+    schemaVersion: "ushman-ledger-manifest/v1";
+    updatedAt: string;
+    workspaceId: string;
+}>;
+export declare const reconcileLedgerStateUnderLock: (workspaceRoot: string) => Promise<PreparedLedgerState>;
+export declare const loadLedgerState: (workspaceRoot: string) => Promise<PreparedLedgerState>;
+export declare const prepareLedgerState: (workspaceRoot: string) => Promise<void>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAKA,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,mBAAmB,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA0B3D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACvC,CAAC;AA0JF,eAAO,MAAM,kBAAkB,GAAU,kDAKtC;IACC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,oBAeA,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,kBAEzD,CAAC;AAEF,eAAO,MAAM,gCAAgC,GAAU,eAAe,MAAM;;;;;;;;;;;;;;;;;;;;EAyB3E,CAAC;AAEF,eAAO,MAAM,6BAA6B,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQtG,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,mBAAmB,CAQxF,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,kBAE7D,CAAC"}