ushman-ledger 1.2.0 → 1.2.2

package/ARCHITECTURE.md

@@ -0,0 +1,79 @@
+# ushman-ledger architecture
+
+This package owns append-only ledger persistence for ushman v4 workspaces. It does not orchestrate pipelines or act as a general database layer.
+
+## Core flow
+
+1. `openLedger()` validates the workspace and reconciles any pending crash-recovery state.
+2. `record()` normalizes the input, resolves any patch/blob payload, and acquires the manifest lock.
+3. A pending commit journal is written before the entry file, manifest update, and read-index update diverge.
+4. The entry file is written atomically into the phase directory.
+5. `manifest.json` is updated atomically.
+6. `read-index.json` is updated atomically.
+7. The pending journal is removed only after the manifest and read index are durable.
+
+The same reconciliation path is used by reads, writes, coverage, doctor, render, and archive entrypoints so callers do not need a separate recovery command.
+
+## Storage model
+
+`<workspace>/.lab/ledger/`
+
+- `manifest.json`: append-order metadata, per-phase pointers, idempotency index, and archive metadata.
+- `read-index.json`: durable lightweight scan index used by list/render/coverage/doctor.
+- `pending/`: append journals used to replay incomplete commits.
+- `pending-archives/`: archive journals used to adopt or discard incomplete archive writes.
+- `blobs/`: content-addressed patch payloads keyed by SHA-256.
+- `<phase>/`: append-only entry files per ledger phase.
+
+## Append semantics
+
+- Entries are immutable once written. Corrections use `correction` records linked to the original entry.
+- Each phase maintains its own `prevEntryId` chain so local append history is explicit and auditable.
+- Idempotency is logical-content based by default and can be overridden with an explicit `idempotencyKey`.
+- Patch payloads are de-duplicated by SHA-256 and stored once under `blobs/`.
+
+## Read path
+
+- `list`, render, coverage, and doctor iterate entries in manifest sequence order.
+- The durable read index avoids resorting `manifest.entryLocations` on every scan.
+- Limited reads filter from the read index first, then materialize only the last matching entries from disk.
+- Multiple readers can run concurrently. Writers serialize only around manifest mutation and recovery work that must observe a consistent durable state.
+
+## Recovery model
+
+- Atomic writes use temp files and rename.
+- Pending commit journals record the target sequence before the entry file and manifest can drift.
+- Startup reconciliation replays pending commits in manifest order, rebuilds missing or stale read indexes, adopts verified archives, and cleans stale temp files.
+- Manifest locks are reclaimed only after stale-owner checks, so a newer owner is not deleted during handoff.
+- Re-opening the ledger or rerunning any CLI command triggers the same recovery path; there is no separate manual recovery subcommand.
+
+## Scale and tuning
+
+The default scan contract is intentionally conservative and can be tuned with environment variables:
+
+- `USHMAN_LEDGER_SCAN_BATCH_SIZE`
+- `USHMAN_LEDGER_SCAN_CONCURRENCY`
+- `USHMAN_LEDGER_READ_INDEX_REBUILD_BATCH_SIZE`
+- `USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY`
+- `USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY`
+- `USHMAN_LEDGER_BLOB_HASH_CONCURRENCY`
+- `USHMAN_LEDGER_MAX_PATCH_BYTES`
+
+The benchmark entrypoint, `bun run bench:scale`, prints the active runtime config so measurements can be compared across different knob settings.
+
+## Operational ceilings
+
+- Manifest sequence numbers stop at `Number.MAX_SAFE_INTEGER`.
+- Patch/blob ingestion defaults to a 10 MiB ceiling unless `USHMAN_LEDGER_MAX_PATCH_BYTES` is raised.
+- Git diff capture is the only external-binary dependency and defaults to a 30 second timeout plus a 10 MiB stdout buffer.
+
+## Contributor map
+
+- `src/blobs.ts`: patch blob storage, size limits, and digest/path validation.
+- `src/record.ts`: append pipeline and idempotency behavior.
+- `src/recovery.ts`: pending journal replay, read-index rebuild, and temp cleanup.
+- `src/read-index.ts`: durable scan index construction and maintenance.
+- `src/list.ts`: manifest/read-index iteration logic.
+- `src/coverage.ts`: candidate file scan plus read-index-backed coverage calculation.
+- `src/doctor.ts`: integrity checks plus troubleshooting-oriented findings.
+- `src/cli.ts`: CLI argument handling and automation-facing output.

package/README.md

@@ -27,9 +27,21 @@ bun link ushman-ledger
 ## Library API
 
 ```ts
-import { buildValidatorResultRecord, openLedger } from 'ushman-ledger';
-
-const ledger = await openLedger('/path/to/workspace');
+import { readFile } from 'node:fs/promises';
+import {
+  appendCleanupWaveNote,
+  appendSemanticCleanupSummaryNote,
+  type BuildRecordInput,
+  buildChangeLogRecord,
+  buildValidatorResultRecord,
+  deriveFilesChangedFromPatch,
+  getLedgerRuntimeConfig,
+  openLedger,
+} from 'ushman-ledger';
+
+const workspaceRoot = '/path/to/workspace';
+const ledger = await openLedger(workspaceRoot);
+const patchText = await readFile('/tmp/change.patch', 'utf8');
 
 await ledger.record({
   emitter: { tool: 'ushman-cli', version: '1.0.0' },
@@ -48,6 +60,21 @@ await ledger.record({
   summary: 'Apply websocket shim',
 });
 
+await ledger.record(
+  buildChangeLogRecord({
+    emitter: { tool: 'ushman-cli', version: '1.0.0' },
+    filesChanged: deriveFilesChangedFromPatch(patchText),
+    hypothesis: 'Smaller schema modules keep the public API stable.',
+    kind: 'change-log',
+    parityStatus: 'green',
+    phase: 'cleanup',
+    rollbackPlan: 'Revert the schema split.',
+    smokeResult: 'pass',
+    subkind: 'semantic-cleanup',
+    summary: 'Split schema modules',
+  }),
+);
+
 await ledger.record(
   buildValidatorResultRecord({
     emitter: { tool: 'ushman-doctor', version: '1.0.0' },
@@ -58,9 +85,40 @@ await ledger.record(
   }),
 );
 
+await appendCleanupWaveNote(workspaceRoot, {
+  body: 'Split schema definitions out of the monolithic entry module.',
+  phase: 'cleanup',
+  summary: 'Wave 1',
+});
+
+await appendSemanticCleanupSummaryNote(workspaceRoot, {
+  body: 'The latest semantic cleanup summary shown in workspace-narrative-md.',
+  phase: 'migration',
+  summary: 'Latest summary',
+});
+
 await ledger.render({ to: 'retro' });
 await ledger.render({ to: 'migration-log-md' });
+await ledger.renderTo({ to: 'migration-log-md', out: '/tmp/migration-log.md' });
 await ledger.archive('/tmp/ledger.tgz');
+
+const config = getLedgerRuntimeConfig();
+console.log(`Using scan concurrency ${config.scanConcurrency}`);
+```
+
+Advanced builder wrappers can reuse the exported `BuildRecordInput<T>` helper type when they want the same input contract the built-in builders accept.
+
+Example:
+
+```ts
+import type { BuildRecordInput, LedgerRecord } from 'ushman-ledger';
+
+type RuntimeEventInput = BuildRecordInput<Extract<LedgerRecord, { kind: 'runtime-event' }>>;
+
+const buildRuntimeEventRecord = (input: RuntimeEventInput) => ({
+  ...input,
+  kind: 'runtime-event' as const,
+});
 ```
 
 ## CLI
@@ -68,6 +126,7 @@ await ledger.archive('/tmp/ledger.tgz');
 ```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=change-log --subkind=smoke --phase=cleanup --summary="scope git diff" --diff-from-git=HEAD --git-paths=src/main.ts,src/cli.ts --git-diff-timeout-ms=10000 --git-diff-max-buffer-bytes=20971520
 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 record --workspace=<ws> --kind=change-log --subkind=semantic-cleanup --phase=cleanup --summary="split schema modules" --diff=/tmp/change.patch --hypothesis="smaller schema modules keep the public API stable" --commands=$'bun test\nbun run typecheck' --smoke-result=pass --parity-status=green --rollback-plan="revert the schema split"
 ushman-ledger note regression --workspace=<ws> --phase=cleanup --summary="runtime drift" --body=/tmp/note.md
@@ -80,6 +139,7 @@ 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 archive --workspace=<ws> --out=/tmp/ledger.tgz
 ushman-ledger doctor --workspace=<ws>
+ushman-ledger doctor --workspace=<ws> --json
 ```
 
 Valid record kinds: `tool-invocation`, `agent-patch`, `operator-patch`, `operator-decision`, `validator-result`, `runtime-event`, `note`, `correction`, `strip-decision-reverted`, `change-log`
@@ -99,7 +159,15 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 - optional narrative fields: `hypothesis`, `commandsRun`, `smokeResult`, `smokeNotes`, `parityStatus`, `rollbackPlan`
 - `rollsBack`: required when `subkind=rollback`
 
+`deriveFilesChangedFromPatch()` is exported for library callers that want the same diff-to-file summary behavior as the CLI. Known limits:
+
+- It expects `diff --git` headers to delimit files.
+- It counts only textual hunk `+`/`-` lines, so binary or mode-only diffs can report zero line counts.
+- It keeps the post-image path when available and rejects diff blocks that cannot be mapped to normalized workspace-relative paths.
+
 `migration-log-md` renders only `change-log` entries. `workspace-narrative-md` renders only the dedicated narrative note subkinds.
+`render()` still returns a string for in-memory callers. `renderTo()` is the bounded-output alternative for large ledgers and can write to a callback or the canonical render file on disk.
+`renderTo()` writers receive sequential chunks, can return synchronously or asynchronously, and should throw only when the render should abort.
 
 ## Workspace prerequisite
 
@@ -167,8 +235,12 @@ Valid render targets: `retro`, `jsonl`, `timeline-html`, `dependency-graph`, `mi
 ## 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.
+- `--git-paths=<csv>` safely scopes `git diff` to literal normalized workspace-relative paths. The CLI passes them after `--`, so pathspec magic and shell token splitting are intentionally not supported here.
+- `--git-paths=<csv>` and `--files-changed=<csv>` do not support literal commas inside individual file names.
+- `--git-diff-timeout-ms=<ms>` and `--git-diff-max-buffer-bytes=<bytes>` override the default 30 second timeout and 10 MiB stdout buffer for the git diff helper.
+- The CLI reports usage errors for missing `git`, timed out git diffs, invalid scoped paths, and buffer overflows instead of surfacing raw child-process failures.
 - This is the only CLI feature that depends on an external binary. `git` must be available in `PATH`.
+- `--from-stdin` accepts structured JSON records only. Raw patch text still needs `--diff=<file>` or `--diff-from-git=<ref>`.
 
 ## Storage shape
 
@@ -200,5 +272,72 @@ 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.
+- `bun run bench:scale` creates a temporary workspace and benchmarks large-ledger paths for population, limited reads, repeated coverage, repeated doctor runs, and markdown render paths.
 - Override the defaults with environment variables such as `LEDGER_BENCH_ENTRY_COUNT=100000` and `LEDGER_BENCH_CANDIDATE_FILE_COUNT=10000`.
+- The benchmark prints the active ledger runtime tuning so large-ledger measurements can be tied back to the scan/rebuild settings that produced them.
+
+## Operational limits
+
+- The manifest sequence counter is capped at `Number.MAX_SAFE_INTEGER`. Appends fail before overflow so sequence ordering stays exact.
+- Patch/blob ingestion is capped at 10 MiB by default across `diffText`, `diffPath`, `storePatchBlob()`, and CLI git-diff capture. Raise `USHMAN_LEDGER_MAX_PATCH_BYTES` only when the larger diff size is intentional and operationally acceptable.
+- CLI git diff capture also defaults to a 30 second timeout and a 10 MiB stdout buffer. Use `--git-diff-timeout-ms` and `--git-diff-max-buffer-bytes` when a specific capture needs more headroom.
+
+## Runtime tuning
+
+- `USHMAN_LEDGER_SCAN_BATCH_SIZE`: batch size for list/render/doctor entry reads. Default `32`.
+- `USHMAN_LEDGER_SCAN_CONCURRENCY`: concurrent entry reads for list/render/doctor. Default `16`.
+- `USHMAN_LEDGER_READ_INDEX_REBUILD_BATCH_SIZE`: batch size used when rebuilding `read-index.json`. Defaults to `USHMAN_LEDGER_SCAN_BATCH_SIZE`.
+- `USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY`: concurrent entry reads used while rebuilding `read-index.json`. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
+- `USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY`: concurrent `stat()` calls during coverage scans. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
+- `USHMAN_LEDGER_BLOB_HASH_CONCURRENCY`: concurrent blob integrity hashes during `doctor`. Defaults to `USHMAN_LEDGER_SCAN_CONCURRENCY`.
+- `USHMAN_LEDGER_MAX_PATCH_BYTES`: maximum accepted patch/blob input size in bytes. Default `10485760`.
+
+All runtime tuning values must be positive integers. Invalid values fail fast with an explicit error so automation does not silently run with an unexpected fallback.
+
+## Doctor output
+
+- `ushman-ledger doctor` prints human-oriented findings with a stable finding code and a remediation step for each issue.
+- `ushman-ledger doctor --json` returns a machine-readable envelope with `checkedAt`, `ok`, `issueCount`, `issues`, and structured `findings`.
+- Each JSON finding includes a stable `code`, a human `message`, and a `remediation` string intended for operators and CI surfaces.
+
+Example:
+
+```bash
+ushman-ledger doctor --workspace="$WS" --json | jq '.findings[] | { code, message, remediation }'
+```
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for the current finding codes and the expected recovery flow.
+
+## Advanced usage
+
+Use a stable `idempotencyKey` to bracket a multi-step cleanup wave, then stream the migration log without buffering the whole render in memory:
+
+```ts
+import {
+  buildChangeLogRecord,
+  openLedger,
+} from 'ushman-ledger';
+
+const ledger = await openLedger(workspaceRoot);
+
+await ledger.record(
+  buildChangeLogRecord({
+    emitter: { tool: 'ushman-cli', version: '1.0.0' },
+    idempotencyKey: 'cleanup-wave-7',
+    kind: 'change-log',
+    phase: 'cleanup',
+    subkind: 'pre-change-checkpoint',
+    summary: 'Wave 7 checkpoint',
+  }),
+);
+
+await ledger.renderTo({
+  to: 'migration-log-md',
+  write: (chunk) => process.stdout.write(chunk),
+});
+```
+
+## Further reading
+
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [TROUBLESHOOTING.md](TROUBLESHOOTING.md)

package/TROUBLESHOOTING.md

@@ -0,0 +1,170 @@
+# ushman-ledger troubleshooting
+
+Start with:
+
+```bash
+ushman-ledger doctor --workspace="$WS"
+```
+
+For automation or CI:
+
+```bash
+ushman-ledger doctor --workspace="$WS" --json
+```
+
+The JSON report contains:
+
+- `ok`: overall health boolean
+- `issueCount`: number of findings
+- `issues`: legacy message-only list
+- `findings`: structured findings with `code`, `message`, `remediation`, and optional metadata
+
+The default human-readable output prints one finding per block:
+
+```text
+[finding-code] human-readable message
+Next step: remediation guidance
+```
+
+## Common findings
+
+### `manifest-entry-count-mismatch`
+
+Meaning: `manifest.json` disagrees with the number of durable entry files on disk.
+
+Action:
+- Re-open the ledger or rerun the failed command first so recovery can replay pending commits.
+- If the mismatch persists, compare `manifest.entryLocations` against the phase directories and repair the missing file or location.
+
+### `manifest-last-sequence-mismatch`
+
+Meaning: the manifest sequence counter no longer matches the durable append count.
+
+Action:
+- Finish recovery first.
+- If recovery is already clean, repair `manifest.lastSequence` so it matches the highest durable append sequence.
+
+### `manifest-entry-missing-on-disk`
+
+Meaning: the manifest references an entry id whose file is missing.
+
+Action:
+- Restore the missing entry file from a known-good copy, or repair the manifest location if it was edited incorrectly.
+- Do not archive until the manifest and disk agree.
+
+### `manifest-entry-location-missing`
+
+Meaning: an entry file exists on disk, but `manifest.entryLocations` has no location for that entry id.
+
+Action:
+- Repair `manifest.entryLocations` so the durable entry is reachable by phase and sequence.
+- Rerun `doctor` afterward to catch any follow-on sequence or latest-pointer drift.
+
+### `manifest-phase-mismatch`
+
+Meaning: an entry file exists, but the manifest points at the wrong phase.
+
+Action:
+- Restore the entry to the correct phase directory or repair `manifest.entryLocations`.
+
+### `manifest-per-phase-latest-mismatch`
+
+Meaning: `perPhaseLatest` does not point at the newest entry in that phase.
+
+Action:
+- Repair the manifest so the latest pointer matches the highest sequence entry in the phase.
+
+### `manifest-sequence-mismatch`
+
+Meaning: manifest sequence numbers are no longer contiguous or ordered.
+
+Action:
+- Repair `manifest.entryLocations` so sequence numbers are gap-free and monotonic.
+
+### `phase-prev-entry-mismatch`
+
+Meaning: an entry’s `prevEntryId` no longer matches the prior append in its phase chain.
+
+Action:
+- Restore the edited entry or repair the phase chain.
+- For content fixes, append a `correction` entry instead of rewriting history in place.
+
+### `blob-missing`
+
+Meaning: a patch/blob referenced by an entry is missing under `.lab/ledger/blobs/`.
+
+Action:
+- Restore the blob file or recreate the patch entry from the original diff.
+
+### `blob-corrupt`
+
+Meaning: the blob exists but its SHA-256 digest no longer matches the entry metadata.
+
+Action:
+- Restore the original blob content or recreate the patch entry from the original diff.
+
+### `blob-unreadable`
+
+Meaning: the blob exists but doctor could not read it to verify the digest.
+
+Action:
+- Fix the filesystem permission or transient I/O problem first.
+- Rerun `doctor` before attempting `archive`.
+
+### `change-log-smoke-failure-missing-rollback-plan`
+
+Meaning: a `change-log` entry recorded `smokeResult=fail` without documenting a rollback plan.
+
+Action:
+- Append a correction or follow-up `change-log` entry that documents the rollback path.
+
+### `change-log-rollback-missing-target`
+
+Meaning: a rollback `change-log` entry did not declare which ledger entry it reverts.
+
+Action:
+- Append a correction or replacement rollback entry with `rollsBack` populated.
+
+### `pre-change-checkpoint-stale`
+
+Meaning: a pre-change checkpoint aged past 24 hours without a follow-up entry using the same `idempotencyKey`.
+
+Action:
+- Append the follow-up change-log entry, or close the stale checkpoint with a correction entry explaining the abandoned work.
+
+### `open-issue-stale`
+
+Meaning: an `open-issue` note is older than 30 days and has no correction/supersession link.
+
+Action:
+- Append a correction or superseding note linking back to the old issue once the follow-up is complete.
+
+### `read-failure`
+
+Meaning: the ledger could not be parsed or reconciled cleanly before checks started.
+
+Action:
+- Fix invalid JSON in `manifest.json` or `read-index.json`.
+- Re-open the ledger afterward so reconciliation can rebuild any missing derived state.
+
+## Recovery workflow
+
+1. Re-open the ledger or rerun the failing ledger command once. Many issues resolve after reconciliation replays pending commits or rebuilds the read index automatically.
+2. Run `doctor --json` and capture the structured findings if the problem persists.
+3. Repair the lowest-level corruption first: missing entry file, missing blob, invalid manifest JSON, or stale manifest pointer.
+4. Rerun `doctor`.
+5. Only run `archive` after `doctor` returns `ok: true`.
+
+## Common operator scenarios
+
+### Ledger lock held by a dead process
+
+Rerun the original ledger command first. Lock reclamation happens during normal startup and append flows, so you usually do not need to delete lock files by hand.
+
+### Manifest and disk disagree after a crash
+
+Re-open the ledger first so pending commits can be replayed. If `doctor` still reports `manifest-entry-missing-on-disk` or `manifest-entry-location-missing`, repair the missing entry file or manifest location before archiving.
+
+### Manual ledger edits
+
+Prefer appending `correction` or `operator-decision` records instead of editing historical entry files directly. If historical files were edited already, use `doctor` to identify the damaged chain or manifest pointers before appending new records.

package/dist/blobs.d.ts

@@ -4,6 +4,9 @@ export type StoredPatchBlob = {
     readonly bytes: number;
     readonly removedLines: number;
 };
+export declare const assertValidBlobSha256: (sha256: string) => string;
+export declare const assertPatchTextWithinLimit: (patchText: string, sourceLabel: string) => number;
+export declare const readPatchTextFromFile: (patchPath: string) => Promise<string>;
 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;

package/dist/blobs.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"blobs.d.ts","sourceRoot":"","sources":["../src/blobs.ts"],"names":[],"mappings":"AA8CA,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,qBAAqB,GAAI,QAAQ,MAAM,WAKnD,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,WAAW,MAAM,EAAE,aAAa,MAAM,WAOhF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAU,WAAW,MAAM,oBAO5D,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,WAAW,MAAM,KAAG,OAAO,CAAC,eAAe,CAmBtG,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,WACN,CAAC"}

package/dist/blobs.js

@@ -1,49 +1,75 @@
-import { mkdir, readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { sha256File, sha256Hex } from "./json.js";
+import { sha256Hex } from "./json.js";
+import { getLedgerRuntimeConfig } from "./runtime-config.js";
 import { resolveLedgerPaths, writeAtomicTextFile } from "./storage/filesystem.js";
+import { forEachLine } from "./text-lines.js";
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/u;
 const countPatchLines = (patchText) => {
     let addedLines = 0;
     let removedLines = 0;
     let insideHunk = false;
-    for (const line of patchText.split(/\r?\n/u)) {
+    forEachLine(patchText, (line) => {
+        if (line.startsWith('diff --git ')) {
+            insideHunk = false;
+            return;
+        }
         if (line.startsWith('@@')) {
             insideHunk = true;
-            continue;
+            return;
         }
         if (!insideHunk || line.startsWith('+++') || line.startsWith('---')) {
-            continue;
+            return;
         }
         if (line.startsWith('+')) {
             addedLines += 1;
-            continue;
+            return;
         }
         if (line.startsWith('-')) {
             removedLines += 1;
         }
-    }
+    });
     return { addedLines, removedLines };
 };
+const formatPatchLimitError = ({ bytes, limitBytes, sourceLabel }) => `Patch input from ${sourceLabel} is ${bytes} bytes, exceeding the configured limit of ${limitBytes} bytes. Reduce the diff size or increase USHMAN_LEDGER_MAX_PATCH_BYTES.`;
 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) => {
+export const assertValidBlobSha256 = (sha256) => {
+    if (!SHA256_HEX_PATTERN.test(sha256)) {
+        throw new Error(`Invalid patch blob digest: ${sha256}. Expected a lowercase SHA-256 hex digest.`);
+    }
+    return sha256;
+};
+export const assertPatchTextWithinLimit = (patchText, sourceLabel) => {
+    const limitBytes = getLedgerRuntimeConfig().maxPatchBytes;
     const bytes = Buffer.byteLength(patchText, 'utf8');
+    if (bytes > limitBytes) {
+        throw new Error(formatPatchLimitError({ bytes, limitBytes, sourceLabel }));
+    }
+    return bytes;
+};
+export const readPatchTextFromFile = async (patchPath) => {
+    const fileStat = await stat(patchPath);
+    const limitBytes = getLedgerRuntimeConfig().maxPatchBytes;
+    if (fileStat.size > limitBytes) {
+        throw new Error(formatPatchLimitError({ bytes: fileStat.size, limitBytes, sourceLabel: patchPath }));
+    }
+    return readFile(patchPath, 'utf8');
+};
+export const storePatchBlob = async (workspaceRoot, patchText) => {
+    const bytes = assertPatchTextWithinLimit(patchText, 'inline diff text');
     const blobSha256 = sha256Hex(patchText);
     const blobPath = buildBlobPath(workspaceRoot, blobSha256);
-    let shouldWrite = true;
     try {
-        shouldWrite = (await sha256File(blobPath)) !== blobSha256;
+        await stat(blobPath);
     }
     catch (error) {
         const code = error.code;
         if (code !== 'ENOENT') {
             throw error;
         }
-    }
-    if (shouldWrite) {
-        await mkdir(path.dirname(blobPath), { recursive: true });
         await writeAtomicTextFile(blobPath, patchText);
     }
     return {
@@ -53,6 +79,6 @@ export const storePatchBlob = async (workspaceRoot, patchText) => {
     };
 };
 export const storePatchBlobFromFile = async (workspaceRoot, patchPath) => {
-    return storePatchBlob(workspaceRoot, await readFile(patchPath, 'utf8'));
+    return storePatchBlob(workspaceRoot, await readPatchTextFromFile(patchPath));
 };
-export const resolveBlobPath = (workspaceRoot, sha256) => buildBlobPath(workspaceRoot, sha256);
+export const resolveBlobPath = (workspaceRoot, sha256) => buildBlobPath(workspaceRoot, assertValidBlobSha256(sha256));

package/dist/builders.d.ts

@@ -1,5 +1,5 @@
 import { type LedgerRecord } from './schema/entry.ts';
-type BuildRecordInput<TRecord extends LedgerRecord> = Omit<TRecord, 'kind'> & {
+export type BuildRecordInput<TRecord extends LedgerRecord> = Omit<TRecord, 'kind'> & {
     readonly kind?: TRecord['kind'];
 };
 /** Build an `operator-decision` record with a validated structured payload. */
@@ -182,5 +182,4 @@ export declare const buildStripDecisionRevertedRecord: (input: BuildRecordInput<
     phase: "capture" | "intake" | "seed" | "vendor-extract" | "cleanup" | "parity" | "characterize" | "equiv" | "analyze" | "recover" | "ship" | "migration";
     summary: string;
 };
-export {};
 //# sourceMappingURL=builders.d.ts.map

package/dist/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IAC1E,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIrG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"AACA,OAAO,EAGH,KAAK,YAAY,EAIpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,gBAAgB,CAAC,OAAO,SAAS,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACnC,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,2BAA2B,GACpC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAM3E,CAAC;AAEP,yCAAyC;AACzC,eAAO,MAAM,0BAA0B,GACnC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAK1E,CAAC;AAEP,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CAItG,CAAC;AAEP,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIrG,CAAC;AAEP,gDAAgD;AAChD,eAAO,MAAM,gCAAgC,GACzC,OAAO,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;IAAE,IAAI,EAAE,yBAAyB,CAAA;CAAE,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAKjF,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmDA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AAiwBF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2DA,KAAK,UAAU,GAAG;IACd,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE;QACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,GAAG,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;CAC1C,CAAC;AA29BF,eAAO,MAAM,YAAY,GAAU,MAAM,SAAS,MAAM,EAAE,EAAE,UAAS,OAAO,CAAC,UAAU,CAAM,KAAG,OAAO,CAAC,MAAM,CAqC7G,CAAC;AAEF,eAAO,MAAM,IAAI,GAAU,OAAM,SAAS,MAAM,EAA0B,KAAG,OAAO,CAAC,MAAM,CAE1F,CAAC"}