ushman-ledger 0.3.0

package/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md — ushman-ledger
+
+Read this before changing code in this package.
+
+## What this package is
+
+An append-only ledger library and CLI for ushman v4 workspaces. It owns ledger schemas, storage, rendering, archive integrity, and doctor/coverage helpers.
+
+## What this package is NOT
+
+- Not a pipeline orchestrator.
+- Not a markdown source of truth.
+- Not a general database abstraction.
+
+## Working rules
+
+- Keep runtime code pure Node and offline.
+- Exception: the CLI `--diff-from-git` convenience flag shells out to `git`; document and test any behavior that depends on it.
+- Preserve append-only semantics.
+- Every storage mutation must be atomic and recoverable after crashes.
+- Every new behavior ships with tests.
+
+## Read order
+
+1. `README.md`
+2. `src/schema/entry.ts`
+3. `src/storage/filesystem.ts`
+4. `src/record.ts`
+5. `src/handle.ts`
+6. `src/coverage.ts`
+7. `src/doctor.ts`
+8. `src/cli.ts`
+
+## Commands
+
+```bash
+bun test
+bun run lint
+bun run typecheck
+bun run build
+```

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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.
+
+### Breaking changes
+
+- 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
+
+- 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.
+
+## [0.1.0] - 2026-05-12
+
+- Initial implementation of `ushman-ledger`.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ragaeeb Haq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# ushman-ledger
+
+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
+- Archive integrity output
+- Doctor and coverage helpers
+
+## Install for local workspace development
+
+```bash
+bun install
+bun run build
+bun link
+
+cd ~/workspace/ushman
+bun link ushman-ledger
+```
+
+## Library API
+
+```ts
+import { buildValidatorResultRecord, openLedger } from 'ushman-ledger';
+
+const ledger = await openLedger('/path/to/workspace');
+
+await ledger.record({
+  emitter: { tool: 'ushman-cli', version: '1.0.0' },
+  kind: 'tool-invocation',
+  phase: 'capture',
+  summary: 'capture started',
+});
+
+await ledger.record({
+  agent: { name: 'codex-cli' },
+  diffPath: '/tmp/change.patch',
+  emitter: { tool: 'ushman-cli', version: '1.0.0' },
+  kind: 'agent-patch',
+  phase: 'cleanup',
+  rationale: 'Track a manual patch.',
+  summary: 'Apply websocket shim',
+});
+
+await ledger.record(
+  buildValidatorResultRecord({
+    emitter: { tool: 'ushman-doctor', version: '1.0.0' },
+    phase: 'cleanup',
+    summary: 'coverage gate passed',
+    validator: 'doctor',
+    verdict: 'green',
+  }),
+);
+
+await ledger.render({ to: 'retro' });
+await ledger.render({ to: 'analytics-summary' });
+await ledger.archive('/tmp/ledger.tgz');
+```
+
+## CLI
+
+```bash
+ushman-ledger record --workspace=<ws> --kind=tool-invocation --phase=capture --summary="capture started"
+ushman-ledger record --workspace=<ws> --kind=agent-patch --phase=cleanup --summary="capture git diff" --rationale="track working tree change" --diff-from-git=HEAD
+ushman-ledger record --workspace=<ws> --kind=operator-decision --phase=cleanup --summary="manual override" --action=ledger-hand-edit --check-id=manual-review --rationale="operator edited the ledger after audit"
+ushman-ledger note regression --workspace=<ws> --phase=cleanup --summary="runtime drift" --body=/tmp/note.md
+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 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`
+
+## Workspace prerequisite
+
+`openLedger()` and the CLI expect a valid ushman v4 workspace with `.lab/lab.json` already present.
+
+## Idempotency
+
+- Without `idempotencyKey`, records dedupe by their logical content hash.
+- 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
+
+- `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`.
+
+## Links and coverage
+
+- `links.affectedFiles` should contain normalized workspace-relative paths for files changed by an `agent-patch` or `operator-patch`.
+- Use forward slashes, do not prefix paths with `./`, and do not include trailing slashes or `..` segments.
+- Coverage only considers candidate workspace files modified after workspace initialization.
+- A modified file is considered covered when any patch entry lists it in `links.affectedFiles`.
+- Coverage is backed by a durable read index so repeated coverage runs do not rescan every patch entry.
+
+## Append chain and concurrency
+
+- Each phase is an append-only linked list through `prevEntryId`.
+- Manifest updates are serialized through a global ledger lock.
+- Appends use a pending-commit journal so entry files, the manifest, and the durable read index can be replayed after crashes.
+- Open, read, and append paths reconcile unfinished commits before serving ledger data.
+- Corrupt or stale manifest locks are reclaimed automatically with compare-and-swap style quarantine semantics.
+
+## Crash recovery
+
+- Pending commit journals live under `.lab/ledger/pending/`.
+- Pending archive journals live under `.lab/ledger/pending-archives/`.
+- Startup reconciliation replays journaled appends in manifest sequence order.
+- Startup reconciliation also rebuilds a missing or stale `read-index.json` from manifest sequence order.
+- Verified pending archives are adopted into the manifest on startup; corrupt or partial pending archives are deleted.
+- Stale temp files are cleaned for phase entries, the manifest, blobs, the read index, and render outputs.
+
+## Recovery & Troubleshooting
+
+- `.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
+
+- `list`, render, coverage, and doctor iterate entries in manifest sequence order.
+- Read paths use a durable `read-index.json` sidecar instead of resorting `manifest.entryLocations` on every scan.
+- `list --limit=<n>` keeps bounded memory and returns the last `n` matching entries in append order.
+- Limited reads can filter by `kind` and `since` from the durable read index before reading entry files.
+- Coverage file stats and doctor blob hashing use bounded concurrency instead of unbounded `Promise.all`.
+
+## Archive integrity
+
+- Archives are created as `.tgz` files using pure Node code.
+- Each archive includes `archive-manifest.json` with per-file SHA-256 hashes and an overall `integrityHash`.
+- `archive` writes a pending archive journal before tar creation, verifies the final tarball after creation, and only then appends archive metadata to the manifest.
+- `archive` refuses to run when `doctor` reports an unhealthy ledger.
+
+## Git diff capture
+
+- `--diff-from-git=<ref>` runs `git diff <ref>` against the workspace working tree.
+- The CLI times out `git diff` after 30 seconds and reports a usage error instead of hanging indefinitely.
+- This is the only CLI feature that depends on an external binary. `git` must be available in `PATH`.
+
+## Storage shape
+
+```text
+<ws>/.lab/ledger/
+  .manifest.lock
+  analytics-summary.json
+  manifest.json
+  read-index.json
+  pending/
+  pending-archives/
+  blobs/
+  render.md
+  render.timeline.html
+  <phase>/
+    <timestamp>-<sequence>-<hash>.json
+```
+
+## Validation
+
+```bash
+bun run lint
+bun run typecheck
+bun test
+bun run build
+bun run bench:scale
+```
+
+## Scale benchmark
+
+- `bun run bench:scale` creates a temporary workspace and benchmarks large-ledger paths for population, limited reads, repeated coverage, and repeated doctor runs.
+- Override the defaults with environment variables such as `LEDGER_BENCH_ENTRY_COUNT=100000` and `LEDGER_BENCH_CANDIDATE_FILE_COUNT=10000`.

package/dist/archive-journal.d.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+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 collectFileHashes: (root: string, prefix?: string) => Promise<Array<{
+    path: string;
+    sha256: string;
+}>>;
+export declare const createArchiveManifest: (ledgerRoot: string) => Promise<{
+    fileHashes: {
+        path: string;
+        sha256: string;
+    }[];
+    integrityHash: string;
+    schemaVersion: "ushman-ledger-archive-manifest/v1";
+}>;
+export declare const verifyArchiveFile: ({ archivePath, expectedArchiveManifest, }: {
+    readonly archivePath: string;
+    readonly expectedArchiveManifest: ArchiveManifest;
+}) => Promise<void>;
+export declare const writeArchiveManifestFile: ({ archiveManifest, stagingRoot, }: {
+    readonly archiveManifest: ArchiveManifest;
+    readonly stagingRoot: string;
+}) => Promise<void>;
+export declare const writePendingArchive: ({ archiveManifest, createdAt, outPath, workspaceRoot, }: {
+    readonly archiveManifest: ArchiveManifest;
+    readonly createdAt: string;
+    readonly outPath: string;
+    readonly workspaceRoot: string;
+}) => Promise<string>;
+export declare const removePendingArchive: (filePath: string) => Promise<void>;
+export declare const reconcilePendingArchivesUnderLock: ({ manifest, workspaceRoot, }: {
+    readonly manifest: LedgerManifest;
+    readonly 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;
+}>;
+//# sourceMappingURL=archive-journal.d.ts.map

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

@@ -0,0 +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"}

package/dist/archive-journal.js

@@ -0,0 +1,220 @@
+import { mkdtemp, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { extract as extractTar } from 'tar';
+import { z } from 'zod';
+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),
+});
+export const ArchiveManifestSchema = z.object({
+    fileHashes: z.array(ArchiveManifestFileHashSchema),
+    integrityHash: z.string().length(64),
+    schemaVersion: z.literal(ARCHIVE_MANIFEST_SCHEMA_VERSION),
+});
+const PendingArchiveSchema = z.object({
+    archiveManifest: ArchiveManifestSchema,
+    createdAt: z.string().datetime({ offset: true }),
+    outPath: z.string().min(1),
+    schemaVersion: z.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));
+    }
+    catch (error) {
+        throw new Error(`Invalid pending archive at ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+const parseArchiveManifestText = (archivePath, text) => {
+    try {
+        return ArchiveManifestSchema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        throw new Error(`Invalid archive manifest inside ${archivePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+};
+export const collectFileHashes = async (root, prefix = '') => {
+    const entries = await readdir(root, { withFileTypes: true });
+    const hashes = [];
+    for (const entry of entries) {
+        const relPath = prefix ? path.join(prefix, entry.name) : entry.name;
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            hashes.push(...(await collectFileHashes(fullPath, relPath)));
+            continue;
+        }
+        hashes.push({ path: relPath.replaceAll('\\', '/'), sha256: await sha256File(fullPath) });
+    }
+    hashes.sort((left, right) => left.path.localeCompare(right.path));
+    return hashes;
+};
+export const createArchiveManifest = async (ledgerRoot) => {
+    const fileHashes = await collectFileHashes(ledgerRoot);
+    return ArchiveManifestSchema.parse({
+        fileHashes,
+        integrityHash: sha256Hex(stableStringify(fileHashes)),
+        schemaVersion: ARCHIVE_MANIFEST_SCHEMA_VERSION,
+    });
+};
+const verifyArchiveManifest = ({ actualArchiveManifest, archivePath, expectedArchiveManifest, }) => {
+    if (stableStringify(actualArchiveManifest) !== stableStringify(expectedArchiveManifest)) {
+        throw new Error(`Archive manifest mismatch for ${archivePath}.`);
+    }
+};
+const verifyExtractedLedgerHashes = async ({ archivePath, expectedArchiveManifest, extractedRoot, }) => {
+    const actualLedgerRoot = path.join(extractedRoot, 'ledger');
+    const actualFileHashes = await collectFileHashes(actualLedgerRoot);
+    const actualIntegrityHash = sha256Hex(stableStringify(actualFileHashes));
+    if (stableStringify(actualFileHashes) !== stableStringify(expectedArchiveManifest.fileHashes)) {
+        throw new Error(`Archive payload mismatch for ${archivePath}.`);
+    }
+    if (actualIntegrityHash !== expectedArchiveManifest.integrityHash) {
+        throw new Error(`Archive integrity hash mismatch for ${archivePath}: expected ${expectedArchiveManifest.integrityHash}, found ${actualIntegrityHash}.`);
+    }
+};
+const verifyArchiveStructure = async ({ archivePath, extractedRoot, }) => {
+    const rootEntries = (await readdir(extractedRoot, { withFileTypes: true }))
+        .map((entry) => ({
+        isDirectory: entry.isDirectory(),
+        name: entry.name,
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    const expectedEntries = [
+        { isDirectory: false, name: 'archive-manifest.json' },
+        { isDirectory: true, name: 'ledger' },
+    ];
+    if (stableStringify(rootEntries) !== stableStringify(expectedEntries)) {
+        throw new Error(`Archive structure mismatch for ${archivePath}.`);
+    }
+};
+export const verifyArchiveFile = async ({ archivePath, expectedArchiveManifest, }) => {
+    const extractedRoot = await mkdtemp(path.join(os.tmpdir(), 'ushman-ledger-archive-verify-'));
+    try {
+        await extractTar({
+            cwd: extractedRoot,
+            file: archivePath,
+            gzip: true,
+        });
+        await verifyArchiveStructure({
+            archivePath,
+            extractedRoot,
+        });
+        const manifestText = await readFile(path.join(extractedRoot, 'archive-manifest.json'), 'utf8');
+        const actualArchiveManifest = parseArchiveManifestText(archivePath, manifestText);
+        verifyArchiveManifest({
+            actualArchiveManifest,
+            archivePath,
+            expectedArchiveManifest,
+        });
+        await verifyExtractedLedgerHashes({
+            archivePath,
+            expectedArchiveManifest,
+            extractedRoot,
+        });
+    }
+    finally {
+        await rm(extractedRoot, { force: true, recursive: true });
+    }
+};
+export const writeArchiveManifestFile = async ({ archiveManifest, stagingRoot, }) => {
+    await writeFile(path.join(stagingRoot, 'archive-manifest.json'), `${stableStringify(ArchiveManifestSchema.parse(archiveManifest), true)}\n`, 'utf8');
+};
+const readPendingArchive = async (filePath) => parsePendingArchiveText(filePath, await readFile(filePath, 'utf8'));
+const readPendingArchives = async (workspaceRoot) => {
+    const pendingArchivesDir = resolveLedgerPaths(workspaceRoot).pendingArchivesDir;
+    const pendingArchiveFiles = (await readdir(pendingArchivesDir, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => path.join(pendingArchivesDir, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+    return Promise.all(pendingArchiveFiles.map(async (filePath) => ({
+        filePath,
+        pendingArchive: await readPendingArchive(filePath),
+    })));
+};
+const hasTrackedArchive = (manifest, pendingArchive) => manifest.archives.some((archive) => archive.createdAt === pendingArchive.createdAt &&
+    archive.integrityHash === pendingArchive.archiveManifest.integrityHash &&
+    archive.outPath === pendingArchive.outPath);
+const archiveOutputExists = async (archivePath) => {
+    try {
+        await stat(archivePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+};
+const removePendingArchiveOutput = async (archivePath) => {
+    await rm(archivePath, { force: true });
+};
+export const writePendingArchive = async ({ archiveManifest, createdAt, outPath, workspaceRoot, }) => {
+    const filePath = buildPendingArchivePath({
+        createdAt,
+        outPath,
+        workspaceRoot,
+    });
+    await writeAtomicJsonFile(filePath, PendingArchiveSchema.parse({
+        archiveManifest,
+        createdAt,
+        outPath,
+        schemaVersion: PENDING_ARCHIVE_SCHEMA_VERSION,
+    }));
+    return filePath;
+};
+export const removePendingArchive = async (filePath) => {
+    await rm(filePath, { force: true });
+};
+export const reconcilePendingArchivesUnderLock = async ({ manifest, workspaceRoot, }) => {
+    let nextManifest = manifest;
+    let manifestChanged = false;
+    const pendingArchives = await readPendingArchives(workspaceRoot);
+    const processedArchivePaths = [];
+    for (const { filePath, pendingArchive } of pendingArchives) {
+        if (hasTrackedArchive(nextManifest, pendingArchive)) {
+            processedArchivePaths.push(filePath);
+            continue;
+        }
+        if (!(await archiveOutputExists(pendingArchive.outPath))) {
+            processedArchivePaths.push(filePath);
+            continue;
+        }
+        try {
+            await verifyArchiveFile({
+                archivePath: pendingArchive.outPath,
+                expectedArchiveManifest: pendingArchive.archiveManifest,
+            });
+            nextManifest = updateManifestForArchive({
+                archive: {
+                    createdAt: pendingArchive.createdAt,
+                    integrityHash: pendingArchive.archiveManifest.integrityHash,
+                    outPath: pendingArchive.outPath,
+                },
+                manifest: nextManifest,
+            });
+            manifestChanged = true;
+        }
+        catch (error) {
+            if (process.env.NODE_ENV !== 'test') {
+                const details = error instanceof Error ? error.message : String(error);
+                console.debug(`[ushman-ledger] removing invalid pending archive ${pendingArchive.outPath}: ${details}`);
+            }
+            await removePendingArchiveOutput(pendingArchive.outPath);
+        }
+        processedArchivePaths.push(filePath);
+    }
+    if (manifestChanged) {
+        await saveManifest(workspaceRoot, nextManifest);
+    }
+    await Promise.all(processedArchivePaths.map(async (filePath) => removePendingArchive(filePath)));
+    return nextManifest;
+};

package/dist/archive.d.ts

@@ -0,0 +1,30 @@
+import { type ArchiveManifest } from './archive-journal.ts';
+type ArchiveTestHooks = {
+    readonly afterArchiveVerify?: (context: {
+        archiveManifest: ArchiveManifest;
+        outPath: string;
+    }) => Promise<void>;
+    readonly afterManifestSave?: (context: {
+        archiveManifest: ArchiveManifest;
+        outPath: string;
+    }) => Promise<void>;
+    readonly afterPendingArchiveWrite?: (context: {
+        archiveManifest: ArchiveManifest;
+        outPath: string;
+        pendingArchivePath: string;
+    }) => Promise<void>;
+    readonly afterTarCreate?: (context: {
+        archiveManifest: ArchiveManifest;
+        outPath: string;
+    }) => Promise<void>;
+    readonly createTar?: (context: {
+        outPath: string;
+        stagingRoot: string;
+    }) => Promise<void>;
+};
+export declare const setArchiveTestHooks: (workspaceRoot: string, hooks: ArchiveTestHooks | null) => void;
+export declare const archiveLedger: (workspaceRoot: string, outPath: string) => Promise<{
+    integrityHash: string;
+}>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAIA,OAAO,EACH,KAAK,eAAe,EAKvB,MAAM,sBAAsB,CAAC;AAO9B,KAAK,gBAAgB,GAAG;IACpB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,eAAe,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,eAAe,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/G,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC1C,eAAe,EAAE,eAAe,CAAC;QACjC,OAAO,EAAE,MAAM,CAAC;QAChB,kBAAkB,EAAE,MAAM,CAAC;KAC9B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,eAAe,EAAE,eAAe,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5G,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F,CAAC;AAOF,eAAO,MAAM,mBAAmB,GAAI,eAAe,MAAM,EAAE,OAAO,gBAAgB,GAAG,IAAI,SAOxF,CAAC;AA8BF,eAAO,MAAM,aAAa,GAAU,eAAe,MAAM,EAAE,SAAS,MAAM;;EAyFzE,CAAC"}