ushman-ledger 0.3.0

package/dist/archive.js

@@ -0,0 +1,117 @@
+import { cp, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { create as createTar } from 'tar';
+import { createArchiveManifest, verifyArchiveFile, writeArchiveManifestFile, writePendingArchive, } from "./archive-journal.js";
+import { runLedgerDoctor } from "./doctor.js";
+import { updateManifestForArchive } from "./manifest-update.js";
+import { reconcileLedgerStateUnderLock } from "./recovery.js";
+import { readManifest, resolveLedgerPaths, saveManifest } from "./storage/filesystem.js";
+import { acquireLock } from "./storage/lock.js";
+const archiveTestHooks = new Map();
+const resolveWorkspaceKey = (workspaceRoot) => path.resolve(workspaceRoot);
+const getArchiveTestHooks = (workspaceRoot) => archiveTestHooks.get(resolveWorkspaceKey(workspaceRoot));
+export const setArchiveTestHooks = (workspaceRoot, hooks) => {
+    const key = resolveWorkspaceKey(workspaceRoot);
+    if (!hooks) {
+        archiveTestHooks.delete(key);
+        return;
+    }
+    archiveTestHooks.set(key, hooks);
+};
+const shouldIncludeArchivedPath = (sourcePath) => {
+    const baseName = path.basename(sourcePath);
+    return !baseName.endsWith('.lock') && !baseName.includes('.tmp.');
+};
+const createArchiveTarFile = async ({ hooks, outPath, stagingRoot, }) => {
+    if (hooks?.createTar) {
+        await hooks.createTar({ outPath, stagingRoot });
+        return;
+    }
+    await createTar({
+        cwd: stagingRoot,
+        file: outPath,
+        gzip: true,
+    }, ['ledger', 'archive-manifest.json']);
+};
+export const archiveLedger = async (workspaceRoot, outPath) => {
+    const paths = resolveLedgerPaths(workspaceRoot);
+    const resolvedOutPath = path.resolve(outPath);
+    if (resolvedOutPath === paths.root || resolvedOutPath.startsWith(`${paths.root}${path.sep}`)) {
+        throw new Error('Archive output path must be outside the ledger directory.');
+    }
+    const lock = await acquireLock(paths.manifestLockFile);
+    try {
+        const preparedState = await reconcileLedgerStateUnderLock(workspaceRoot);
+        const doctor = await runLedgerDoctor(workspaceRoot, { state: preparedState });
+        if (!doctor.ok) {
+            throw new Error(`Refusing to archive unhealthy ledger:\n${doctor.issues.join('\n')}`);
+        }
+        const stagingRoot = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-archive-'));
+        try {
+            const ledgerCopyRoot = path.join(stagingRoot, 'ledger');
+            await cp(paths.root, ledgerCopyRoot, {
+                filter: shouldIncludeArchivedPath,
+                recursive: true,
+            });
+            const archiveManifest = await createArchiveManifest(ledgerCopyRoot);
+            await writeArchiveManifestFile({
+                archiveManifest,
+                stagingRoot,
+            });
+            const createdAt = new Date().toISOString();
+            const hooks = getArchiveTestHooks(workspaceRoot);
+            const pendingArchivePath = await writePendingArchive({
+                archiveManifest,
+                createdAt,
+                outPath: resolvedOutPath,
+                workspaceRoot,
+            });
+            await hooks?.afterPendingArchiveWrite?.({
+                archiveManifest,
+                outPath: resolvedOutPath,
+                pendingArchivePath,
+            });
+            await mkdir(path.dirname(resolvedOutPath), { recursive: true });
+            await createArchiveTarFile({
+                hooks,
+                outPath: resolvedOutPath,
+                stagingRoot,
+            });
+            await hooks?.afterTarCreate?.({
+                archiveManifest,
+                outPath: resolvedOutPath,
+            });
+            await verifyArchiveFile({
+                archivePath: resolvedOutPath,
+                expectedArchiveManifest: archiveManifest,
+            });
+            await hooks?.afterArchiveVerify?.({
+                archiveManifest,
+                outPath: resolvedOutPath,
+            });
+            await lock.assertOwnership();
+            const currentManifest = await readManifest(workspaceRoot);
+            await saveManifest(workspaceRoot, updateManifestForArchive({
+                archive: {
+                    createdAt,
+                    integrityHash: archiveManifest.integrityHash,
+                    outPath: resolvedOutPath,
+                },
+                manifest: currentManifest,
+            }));
+            await hooks?.afterManifestSave?.({
+                archiveManifest,
+                outPath: resolvedOutPath,
+            });
+            await rm(pendingArchivePath, { force: true });
+            return { integrityHash: archiveManifest.integrityHash };
+        }
+        finally {
+            await rm(stagingRoot, { force: true, recursive: true });
+        }
+    }
+    finally {
+        await lock.release();
+    }
+};

package/dist/async.d.ts

@@ -0,0 +1,2 @@
+export declare const mapWithConcurrencyLimit: <Input, Output>(items: readonly Input[], limit: number, mapper: (item: Input, index: number) => Promise<Output>) => Promise<Output[]>;
+//# sourceMappingURL=async.d.ts.map

package/dist/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../src/async.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,GAAU,KAAK,EAAE,MAAM,EACvD,OAAO,SAAS,KAAK,EAAE,EACvB,OAAO,MAAM,EACb,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,KACxD,OAAO,CAAC,MAAM,EAAE,CAwBlB,CAAC"}

package/dist/async.js

@@ -0,0 +1,20 @@
+export const mapWithConcurrencyLimit = async (items, limit, mapper) => {
+    if (items.length === 0) {
+        return [];
+    }
+    const normalizedLimit = Math.max(1, Math.trunc(limit));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(normalizedLimit, items.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+        while (true) {
+            const currentIndex = nextIndex;
+            if (currentIndex >= items.length) {
+                return;
+            }
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    }));
+    return results;
+};

package/dist/blobs.d.ts

@@ -0,0 +1,10 @@
+export type StoredPatchBlob = {
+    readonly addedLines: number;
+    readonly blobSha256: string;
+    readonly bytes: number;
+    readonly removedLines: number;
+};
+export declare const storePatchBlob: (workspaceRoot: string, patchText: string) => Promise<StoredPatchBlob>;
+export declare const storePatchBlobFromFile: (workspaceRoot: string, patchPath: string) => Promise<StoredPatchBlob>;
+export declare const resolveBlobPath: (workspaceRoot: string, sha256: string) => string;
+//# sourceMappingURL=blobs.d.ts.map

package/dist/blobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,eAAe,GAAG;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAsBtG,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAE9G,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,eAAe,MAAM,EAAE,QAAQ,MAAM,WAAyC,CAAC"}

package/dist/blobs.js

@@ -0,0 +1,58 @@
+import { mkdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256File, sha256Hex } from "./json.js";
+import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
+const countPatchLines = (patchText) => {
+    let addedLines = 0;
+    let removedLines = 0;
+    let insideHunk = false;
+    for (const line of patchText.split(/\r?\n/u)) {
+        if (line.startsWith('@@')) {
+            insideHunk = true;
+            continue;
+        }
+        if (!insideHunk || line.startsWith('+++') || line.startsWith('---')) {
+            continue;
+        }
+        if (line.startsWith('+')) {
+            addedLines += 1;
+            continue;
+        }
+        if (line.startsWith('-')) {
+            removedLines += 1;
+        }
+    }
+    return { addedLines, removedLines };
+};
+const buildBlobPath = (workspaceRoot, sha256) => {
+    const paths = resolveLedgerPaths(workspaceRoot);
+    return path.join(paths.blobsDir, sha256.slice(0, 2), `${sha256}.patch`);
+};
+export const storePatchBlob = async (workspaceRoot, patchText) => {
+    const bytes = Buffer.byteLength(patchText, 'utf8');
+    const blobSha256 = sha256Hex(patchText);
+    const blobPath = buildBlobPath(workspaceRoot, blobSha256);
+    let shouldWrite = true;
+    try {
+        await stat(blobPath);
+        shouldWrite = (await sha256File(blobPath)) !== blobSha256;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    if (shouldWrite) {
+        await mkdir(path.dirname(blobPath), { recursive: true });
+        await writeAtomicTextFile(blobPath, patchText);
+    }
+    return {
+        ...countPatchLines(patchText),
+        blobSha256,
+        bytes,
+    };
+};
+export const storePatchBlobFromFile = async (workspaceRoot, patchPath) => {
+    return storePatchBlob(workspaceRoot, await readFile(patchPath, 'utf8'));
+};
+export const resolveBlobPath = (workspaceRoot, sha256) => buildBlobPath(workspaceRoot, sha256);

package/dist/builders.d.ts

@@ -0,0 +1,465 @@
+import { type LedgerRecord } from './schema/entry.ts';
+type BuildRecordInput<TRecord extends LedgerRecord> = Omit<TRecord, 'kind'> & {
+    readonly kind?: TRecord['kind'];
+};
+/** Build an `agent-patch` record, deriving structured payload fields later if only `diffPath` is supplied. */
+export declare const buildAgentPatchRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "agent-patch";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    rationale: string;
+    agent: {
+        name: string;
+        sessionId?: string | undefined;
+    };
+    kind: "agent-patch";
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+    diff?: {
+        addedLines: number;
+        blobSha256: string;
+        bytes: number;
+        removedLines: number;
+    } | undefined;
+    diffPath?: string | undefined;
+    payload?: {
+        diff?: string | undefined;
+        diffSha256?: string | undefined;
+        fileSha256After?: Record<string, string> | undefined;
+        fileSha256Before?: Record<string, string> | undefined;
+        hunks?: {
+            endLine: number;
+            path: string;
+            startLine: number;
+        }[] | undefined;
+        touchedPaths?: string[] | undefined;
+    } | undefined;
+};
+/** Build an `operator-patch` record, deriving structured payload fields later if only `diffPath` is supplied. */
+export declare const buildOperatorPatchRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "operator-patch";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    rationale: string;
+    kind: "operator-patch";
+    operator: {
+        name: string;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+    diff?: {
+        addedLines: number;
+        blobSha256: string;
+        bytes: number;
+        removedLines: number;
+    } | undefined;
+    diffPath?: string | undefined;
+    payload?: {
+        diff?: string | undefined;
+        diffSha256?: string | undefined;
+        fileSha256After?: Record<string, string> | undefined;
+        fileSha256Before?: Record<string, string> | undefined;
+        hunks?: {
+            endLine: number;
+            path: string;
+            startLine: number;
+        }[] | undefined;
+        touchedPaths?: string[] | undefined;
+    } | undefined;
+};
+/** Build a `stage-transition` record with a validated structured payload. */
+export declare const buildStageTransitionRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "stage-transition";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "stage-transition";
+    payload: {
+        endedAt: string;
+        exitCode: number;
+        stage: "seed" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize";
+        startedAt: string;
+        doctorBaselineId?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build an `operator-decision` record using the required structured payload shape. */
+export declare const buildOperatorDecisionRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "operator-decision";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "operator-decision";
+    payload: {
+        action: "bypass-doctor" | "skip-check" | "override-strip-decision" | "override-ship-state" | "manual-parity-assertion" | "ledger-hand-edit" | "escalation";
+        rationale: string;
+        checkId?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `validator-result` record and synthesize `payload.id` only when the caller omits it. */
+export declare const buildValidatorResultRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "validator-result";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "validator-result";
+    validator: "parity" | "characterize" | "equiv" | "verify" | "doctor";
+    verdict: "green" | "yellow" | "red";
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+    metrics?: Record<string, unknown> | undefined;
+    payload?: {
+        id?: string | undefined;
+    } | undefined;
+    resultPath?: string | undefined;
+};
+/** Build a `correction` record with validated linkage fields. */
+export declare const buildCorrectionRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "correction";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "correction";
+    rationale: string;
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+    payload?: {
+        correctsValidatorResultId?: string | undefined;
+    } | undefined;
+};
+/** Build a `strip-decision-reverted` record. */
+export declare const buildStripDecisionRevertedRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "strip-decision-reverted";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "strip-decision-reverted";
+    payload: {
+        rationale: string;
+        stripDecisionId: string;
+        invalidatedStages?: ("seed" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize")[] | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `descope-brief` record. */
+export declare const buildDescopeBriefRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "descope-brief";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "descope-brief";
+    payload: {
+        briefId: string;
+        reason?: string | undefined;
+        round?: number | undefined;
+        stripDecisionIds?: string[] | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `merge-return` record. */
+export declare const buildMergeReturnRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "merge-return";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "merge-return";
+    payload: {
+        returnId: string;
+        briefId?: string | undefined;
+        source?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `merge-return-rejected` record. */
+export declare const buildMergeReturnRejectedRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "merge-return-rejected";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "merge-return-rejected";
+    payload: {
+        returnId: string;
+        reason: string;
+        briefId?: string | undefined;
+        source?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `revert` record. */
+export declare const buildRevertRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "revert";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "revert";
+    payload: {
+        reason: string;
+        targetEntryId?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `rollback` record. */
+export declare const buildRollbackRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "rollback";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "rollback";
+    payload: {
+        reason: string;
+        targetEntryId?: string | undefined;
+        targetStage?: "seed" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+/** Build a `rework.test_retired` record. */
+export declare const buildReworkTestRetiredRecord: (input: BuildRecordInput<Extract<LedgerRecord, {
+    kind: "rework.test_retired";
+}>>) => {
+    emitter: {
+        tool: string;
+        version: string;
+        user?: string | undefined;
+    };
+    phase: "seed" | "capture" | "intake" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
+    summary: string;
+    kind: "rework.test_retired";
+    payload: {
+        removedBy: "operator" | "descope" | "decompose";
+        removedTestPath: string;
+        removedTestSymbols: string[];
+        sourceSymbolDeletedFrom: string;
+        briefId?: string | undefined;
+    };
+    details?: Record<string, unknown> | undefined;
+    idempotencyKey?: string | undefined;
+    links?: {
+        [x: string]: unknown;
+        affectedFiles?: string[] | undefined;
+        blobs?: string[] | undefined;
+        briefId?: string | undefined;
+        correctsLedgerId?: string | undefined;
+        gitRef?: string | undefined;
+        idempotencyKey?: string | undefined;
+        stripDecisionId?: string | undefined;
+        supersedesLedgerId?: string | undefined;
+        validatorVerdictId?: string | undefined;
+    } | undefined;
+};
+export {};
+//# sourceMappingURL=builders.d.ts.map