@dogfood-lab/ingest 1.4.0 → 1.5.0

package/README.md

@@ -10,7 +10,7 @@
 
 Part of the [`testing-os`](https://github.com/dogfood-lab/testing-os) monorepo — the operating system for testing in the AI era.
 
-Runs on the receiving side of the dogfood loop. Receives `repository_dispatch` payloads from consumer repos, validates them through `@dogfood-lab/verify`, persists records under `records/`, and rebuilds the read-side indexes (`latest-by-repo.json`, `failing.json`, `stale.json`) atomically.
+Runs on the receiving side of the dogfood loop. Receives a submission (from a `repository_dispatch` payload or a file), validates it through `@dogfood-lab/verify`, persists the resulting record under `records/`, and rebuilds the read-side indexes (`latest-by-repo.json`, `failing.json`, `stale.json`).
 
 ## Install
 
@@ -20,49 +20,69 @@ npm install @dogfood-lab/ingest
 
 ## Usage — programmatic
 
+The package exports two functions: `ingest` (verify + persist + rebuild indexes) and `verifyOnly` (verify + report where it *would* land, write nothing).
+
 ```js
-import { run } from '@dogfood-lab/ingest';
+import { ingest, verifyOnly } from '@dogfood-lab/ingest';
+import { githubProvenance } from '@dogfood-lab/verify';
+
+const submission = JSON.parse(/* the dispatch payload's submission object */);
 
-const result = await run({
-  payloadPath: './incoming.json',
-  repoRoot: process.cwd(),
-  provenance: 'github',
+const result = await ingest(submission, {
+  repoRoot: process.cwd(),                  // testing-os repo root the record is written under
+  provenance: githubProvenance(process.env.GITHUB_TOKEN), // provider adapter from @dogfood-lab/verify
 });
 
-console.log(result.persisted_records);  // count of new records written
-console.log(result.indexes_rebuilt);    // boolean
-console.log(result.rejected);           // array of rejection reasons (if any)
+result.record;     // the verified record (null if rejected or a duplicate)
+result.path;       // where it was written (null if not written)
+result.written;    // boolean — did a new record land on disk?
+result.duplicate;  // boolean — was this run_id already persisted?
+```
+
+`verifyOnly(submission, options)` runs the same verification but never writes:
+
+```js
+const { record, would_persist_to, verify_only } = await verifyOnly(submission, { repoRoot, provenance });
+// verify_only === true; would_persist_to is the path ingest() would have used.
 ```
 
 ## Usage — CLI
 
 ```bash
-npx @dogfood-lab/ingest run --payload incoming.json --repo-root .
+node packages/ingest/run.js --provenance=github --file submission.json
 ```
 
-The CLI exits with structured exit codes:
+Flags:
+
+- `--file <path>` / `--payload <path>` — the submission JSON to ingest (both spellings accepted).
+- `--provenance=github` — confirm provenance against the GitHub Actions API (requires `GITHUB_TOKEN` / `GH_TOKEN`). **Production.**
+- `--provenance=stub` — accept the claimed provenance without an API call. **Test/dev only — refused in CI.**
+- `--verify-only` — verify and report, write nothing.
+
+Exit codes:
+
+- `0` — the record was accepted (and, without `--verify-only`, persisted).
+- `1` — the submission was verified but **not accepted** (rejected by a validator gate).
+- `2` — an operator/runtime fault (missing/unreadable `--file`, missing `--provenance`, missing token in CI, downstream I/O failure). Every exit-2 path emits a structured `logStage('error', …)` event first so a log grep finds the cause.
 
-- `0` — ok, all records persisted
-- `1` — user error (bad payload shape, missing files, invalid args)
-- `2` — runtime error (downstream validator failure, I/O failure)
-- `3` — partial success (some records persisted, some rejected)
+There is no exit code 3.
 
 ## Pipeline stages
 
 | Stage | Module | Output |
 |---|---|---|
-| 1. Load context | `load-context.js` | Reads existing `records/`, `policies/`, prior indexes into memory |
-| 2. Validate | delegates to `@dogfood-lab/verify` | Verdict per record: `ok` or `rejection_reasons[]` |
-| 3. Persist | `persist.js` | Two-phase atomic write to `records/<repo>/<record-id>.yaml` |
+| 1. Load context | `load-context.js` | Reads existing `records/`, `policies/`, and prior indexes into memory |
+| 2. Verify | delegates to `@dogfood-lab/verify` | A verdict: `accepted`, or `rejection_reasons[]` |
+| 3. Persist | `persist.js` | Atomic write to `records/<org>/<repo>/YYYY/MM/DD/run-<run_id>.json` |
 | 4. Rebuild indexes | `rebuild-indexes.js` | Regenerates `latest-by-repo.json`, `failing.json`, `stale.json` with crash-safe journaling |
 
-Each stage emits a structured event via `lib/log-stage.js` so the ingest loop is observable end-to-end. Failures at any stage carry a `code`, `message`, and `hint` per the testing-os structured error contract.
+Each stage emits a structured NDJSON event via `lib/log-stage.js` (carrying a `correlation_id`) so the ingest loop is observable end to end. Operator-facing faults carry a `code` / `message` / `hint` per the testing-os [error contract](https://dogfood-lab.github.io/testing-os/handbook/error-codes/).
 
 ## Concurrency + crash safety
 
-- **Per-repo locking**: advisory file lock via `@dogfood-lab/findings/lib/file-lock.js` — Windows-compatible (uses `linkSync` CAS, not `flock`).
-- **Atomic two-phase commit**: `lib/atomic-write.js` writes to a `.tmp-<pid>.json` shadow first, then renames into place with `renameWithRetry` for Windows AV scanner handle-release windows.
-- **Idempotent crash recovery**: `cleanupCrashedJournals` runs at every entry point; partial writes from previous crashes are detected and either completed or rolled back.
+- **Race-safe record claim:** `persist.js` claims the canonical record path with `openSync(path, 'wx')` (`O_EXCL`). The first writer wins; a concurrent writer for the same `run_id` loses the race and surfaces a `DuplicateRunIdError` — no torn or double-written record.
+- **Atomic publication:** records and indexes are written to a temp file and `renameWithRetry`'d into place (the retry absorbs the Windows AV-scanner / lock handle-release window).
+- **Crash-recovery for the index group:** the 3-index rebuild is a journaled commit-group; a crash mid-promote is reconciled by the next rebuild. A transiently-unreadable `records/` root or an empty scan over a previously-non-empty corpus is **refused** rather than allowed to overwrite good indexes with empty content (it emits an `index_rebuild_skipped` event instead).
 
 ## What testing-os ingest does NOT touch
 

package/anchor/cli.js

@@ -0,0 +1,185 @@
+/**
+ * anchor CLI handlers — the operator-facing surface for the three anchor verbs,
+ * wired into run.js: --anchor-compute, --anchor-post, --anchor-verify.
+ *
+ * Each handler returns `{ ok, exitCode, lines, event }` so run.js owns the actual
+ * console + logStage + process.exit (matching how `--verify-chain` is dispatched
+ * via verify-chain.js's verifyChain + formatChainResult). Handlers are
+ * operator-legible: no raw stack traces, structured exit codes.
+ *
+ * Off by default: nothing in the normal ingest/CI path calls these. They are
+ * operator-run only.
+ *
+ * Exit codes:
+ *   0  success (compute wrote/idempotent; post landed; verify all-clear)
+ *   1  a verification FAILURE (truncation detected, anchor mismatch) — fail loud
+ *   2  an operator/precondition error (bad algo, no seed, xrpl missing, etc.)
+ *
+ * Only --anchor-post reaches the network, and it lazily loads xrpl there; compute
+ * and verify never import xrpl.
+ */
+
+import { computeAnchor, recordAnchorPost } from './compute-root.js';
+import { verifyAnchorState } from './verify-anchor.js';
+import { postAnchor } from './post-anchor.js';
+import { ANCHOR_DEFAULTS, resolveTrustedAccounts } from './config.js';
+
+/**
+ * --anchor-compute: compute the next anchor and write its append-only manifest.
+ * Offline; never imports xrpl.
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts] - { mode, algo, network }
+ * @returns {{ ok: boolean, exitCode: number, lines: string[], event: object }}
+ */
+export function handleAnchorCompute(repoRoot, opts = {}) {
+  try {
+    const result = computeAnchor(repoRoot, opts);
+    if (result.empty) {
+      return {
+        ok: true,
+        exitCode: 0,
+        lines: [`anchor-compute: nothing to anchor — ${result.reason}`],
+        event: { stage: 'anchor_compute_complete', empty: true, reason: result.reason },
+      };
+    }
+    const m = result.manifest;
+    const lines = [
+      `anchor-compute: ${result.written ? 'wrote' : 'idempotent (already present)'} anchor seq ${m.anchor_seq}`,
+      `  algo:       ${m.algo}`,
+      `  leaf_count: ${m.leaf_count}`,
+      `  seq_range:  [${m.seq_range[0]}, ${m.seq_range[1]}]`,
+      `  root:       ${m.root}`,
+      `  head:       ${m.head_digest}`,
+      `  prev:       ${m.prev_anchor_root || '(genesis)'}`,
+      `  manifest:   ${result.path}`,
+    ];
+    for (const w of result.warnings || []) lines.push(`  WARNING: ${w}`);
+    return {
+      ok: true,
+      exitCode: 0,
+      lines,
+      event: {
+        stage: 'anchor_compute_complete',
+        anchor_seq: m.anchor_seq,
+        leaf_count: m.leaf_count,
+        root: m.root,
+        written: result.written,
+      },
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      exitCode: 2,
+      lines: [`anchor-compute failed: ${err.message}`],
+      event: { stage: 'error', failed_stage: 'anchor_compute', code: err.code ?? null, message: err.message },
+    };
+  }
+}
+
+/**
+ * --anchor-post: compute (if needed) + post the anchor to the XRP Ledger. Needs
+ * the optional xrpl package and XRPL_SEED. Lazily loads xrpl; a missing xrpl or
+ * missing seed exits 2 with an actionable message.
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts] - { mode, network, wsUrl, seed }
+ * @returns {Promise<{ ok: boolean, exitCode: number, lines: string[], event: object }>}
+ */
+export async function handleAnchorPost(repoRoot, opts = {}) {
+  const network = opts.network || ANCHOR_DEFAULTS.network;
+  try {
+    const receipt = await postAnchor(repoRoot, {
+      ...opts,
+      network,
+      // Production: persist the on-chain facts back into the manifest file.
+      deps: {
+        recordPost: (seq, facts) => recordAnchorPost(repoRoot, seq, facts),
+        ...(opts.deps || {}),
+      },
+    });
+    if (!receipt.ok) {
+      return {
+        ok: false,
+        exitCode: 1,
+        lines: [
+          `anchor-post: submission did NOT succeed (engine result: ${receipt.engine_result || 'unknown'}).`,
+          '  The anchor did NOT land on-chain. Retry when the network is reachable.',
+        ],
+        event: { stage: 'error', failed_stage: 'anchor_post', engine_result: receipt.engine_result },
+      };
+    }
+    return {
+      ok: true,
+      exitCode: 0,
+      lines: [
+        `anchor-post: anchored seq ${receipt.anchor_seq} on ${receipt.network}`,
+        `  tx:           ${receipt.tx_hash}`,
+        `  root:         ${receipt.root}`,
+        `  leaf_count:   ${receipt.leaf_count}`,
+        `  ledger_index: ${receipt.ledger_index ?? '(unavailable)'}`,
+        `  close_time:   ${receipt.close_time_iso ? receipt.close_time_iso + ' (on-chain clock)' : '(unavailable)'}`,
+      ],
+      event: {
+        stage: 'anchor_post_complete',
+        anchor_seq: receipt.anchor_seq,
+        tx_hash: receipt.tx_hash,
+        ledger_index: receipt.ledger_index,
+      },
+    };
+  } catch (err) {
+    // XRPL_NOT_INSTALLED / XRPL_SEED_INVALID / ANCHOR_NOTHING_TO_POST etc.
+    const hint = err.hint ? ` (${err.hint})` : '';
+    return {
+      ok: false,
+      exitCode: 2,
+      lines: [`anchor-post failed: ${err.message}${hint}`],
+      event: { stage: 'error', failed_stage: 'anchor_post', code: err.code ?? null, message: err.message },
+    };
+  }
+}
+
+/**
+ * --anchor-verify: run the truncation check (always, offline) and — when a
+ * fetched tx is supplied — the on-chain anchor verification. OFFLINE-HONEST: with
+ * no tx it reports "XRPL NOT verified" rather than passing the on-chain leg.
+ *
+ * @param {string} repoRoot
+ * @param {object} [opts] - { tx, trustedAnchorAccounts, memoType }
+ * @returns {{ ok: boolean, exitCode: number, lines: string[], event: object }}
+ */
+export function handleAnchorVerify(repoRoot, opts = {}) {
+  const trustedAnchorAccounts = resolveTrustedAccounts(opts.trustedAnchorAccounts);
+  const state = verifyAnchorState(repoRoot, {
+    tx: opts.tx,
+    trustedAnchorAccounts,
+    memoType: opts.memoType || ANCHOR_DEFAULTS.memoType,
+  });
+
+  const t = state.truncation;
+  const lines = [];
+  lines.push(`anchor-verify: ${state.ok ? 'PASS' : 'FAIL'}`);
+  lines.push(`  anchors:            ${t.anchor_count}`);
+  lines.push(`  chain entries:      ${t.chain_count} (head seq ${t.chain_head_seq ?? '(empty)'})`);
+  lines.push(`  anchored through:   seq ${t.anchored_through_seq ?? '(none)'} (≥ ${t.anchored_count} entries)`);
+  lines.push(`  truncation check:   ${t.ok ? 'OK' : 'FAILED'}`);
+  if (!t.ok) {
+    for (const f of t.failures) lines.push(`    - [${f.kind}] ${f.reason}`);
+  }
+  lines.push(`  XRPL on-chain:      ${state.xrpl_verified ? 'VERIFIED' : 'NOT verified'}`);
+  lines.push(`  ${state.note}`);
+
+  return {
+    ok: state.ok,
+    exitCode: state.ok ? 0 : 1,
+    lines,
+    event: {
+      stage: state.ok ? 'anchor_verify_complete' : 'error',
+      ...(state.ok ? {} : { failed_stage: 'anchor_verify' }),
+      truncation_ok: t.ok,
+      xrpl_verified: state.xrpl_verified,
+      anchored_through_seq: t.anchored_through_seq,
+      chain_head_seq: t.chain_head_seq,
+    },
+  };
+}

package/anchor/compute-root.js

@@ -0,0 +1,302 @@
+/**
+ * compute-root — Merkle-root the integrity chain entries for the partition to be
+ * anchored next, and write an append-only anchor manifest.
+ *
+ * Adapted from repomesh's compute-root.mjs to testing-os's chain.jsonl. The
+ * source ledger here is `indexes/integrity/chain.jsonl` (one line per persisted
+ * record: { seq, run_id, repo, status, path, submission_digest, prev_digest,
+ * persisted_at }). The Merkle LEAVES are the entries' `submission_digest` values
+ * for the partition being anchored — already 64-char hex, exactly the shape the
+ * RFC-6962 tree wants.
+ *
+ * ── Cadence (default SINCE-LAST) ────────────────────────────────────────────
+ * Each anchor covers exactly the chain entries appended SINCE the previous
+ * anchor manifest (prev-linked), NOT per-entry. Run anchor-compute + anchor-post
+ * once per release wave — the unit of attested work — not on a wall-clock timer:
+ *   - too FREQUENT (per-entry) floods the XRP Ledger with one-leaf anchors and
+ *     wastes tx fees;
+ *   - too RARE leaves a long window of only-locally-trusted (truncatable) entries.
+ * `--all` produces a single genesis snapshot over the whole chain instead.
+ *
+ * ── Truncation defense (the gap the offline chain cannot close) ──────────────
+ * The manifest records `leaf_count`, `seq_range: [from, to]`, and `head_digest`
+ * (the partition's last entry's submission_digest). Once that manifest's root is
+ * posted on-chain (post-anchor.js) and confirmed, a later chain that is SHORTER
+ * than the anchored (seq_range, leaf_count) is PROVABLY truncated:
+ * verify-anchor's verifyChainAgainstAnchors() asserts the live chain reaches at
+ * least the highest anchored `to` seq and carries at least the anchored count.
+ *
+ * This module is OFFLINE: it reads the chain and writes a manifest. It NEVER
+ * imports xrpl. Posting to the ledger is post-anchor.js's job.
+ */
+
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { merkleRootForAlgo } from './merkle.js';
+import { readChainManifest } from '../lib/chain-manifest.js';
+import { canonicalize } from '../lib/integrity.js';
+// Anchor manifests live in the shared backing store under indexes/integrity/, so
+// they obey the same torn-write doctrine as records/ + chain.jsonl: write via
+// temp+rename so a reader never sees a half-written manifest. Use the sibling
+// ingest helper (not the findings copy — importing it would close the workspace
+// dependency cycle, see CLAUDE.md).
+import { atomicWriteFileSync } from '../lib/atomic-write.js';
+
+/** Manifest format version — bump when the anchor manifest shape changes. */
+export const MANIFEST_VERSION = 1;
+
+/** Default Merkle algorithm for new anchors (second-preimage-safe RFC-6962). */
+export const DEFAULT_ALGO = 'sha256-merkle-v2';
+
+/** Soft cap: a since-last partition larger than this WARNS of a lapsed cadence. */
+export const OVERSIZED_PARTITION_LEAVES = 5000;
+
+/** Repo-root-relative directory holding the append-only anchor manifests. */
+export const ANCHORS_DIR_REL = 'indexes/integrity/anchors';
+
+/** Absolute path to the anchors directory for a given repo root. */
+export function anchorsDir(repoRoot) {
+  return join(repoRoot, 'indexes', 'integrity', 'anchors');
+}
+
+function sha256hex(str) {
+  return createHash('sha256').update(str, 'utf-8').digest('hex');
+}
+
+/**
+ * Read every anchor manifest in seq order. Anchor files are named
+ * `anchor-<NNNN>.json` (zero-padded anchor_seq) so a lexical sort is a seq sort.
+ * Returns [] when none exist.
+ *
+ * @param {string} repoRoot
+ * @returns {Array<object>} Parsed anchor manifests, ascending by anchor_seq.
+ */
+export function readAnchorManifests(repoRoot) {
+  const dir = anchorsDir(repoRoot);
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir)
+    .filter((f) => /^anchor-\d+\.json$/.test(f))
+    .sort();
+  const manifests = files.map((f) => JSON.parse(readFileSync(join(dir, f), 'utf-8')));
+  manifests.sort((a, b) => a.anchor_seq - b.anchor_seq);
+  return manifests;
+}
+
+/**
+ * Return the highest-seq anchor manifest, or null when none exist.
+ *
+ * @param {string} repoRoot
+ * @returns {object|null}
+ */
+export function readLastAnchor(repoRoot) {
+  const manifests = readAnchorManifests(repoRoot);
+  return manifests.length === 0 ? null : manifests[manifests.length - 1];
+}
+
+/**
+ * Select the chain entries this anchor will cover.
+ *
+ * since-last: entries whose `seq` is strictly greater than the highest seq the
+ *   previous anchor covered (`prevAnchor.seq_range[1]`). Genesis (no prev) covers
+ *   the whole chain.
+ * all: the whole chain (genesis snapshot), regardless of prior anchors.
+ *
+ * Pure: takes the already-read entries + prev anchor; no I/O. Exposed for tests.
+ *
+ * @param {Array<object>} entries - All chain entries (chain order).
+ * @param {object|null} prevAnchor - The previous anchor manifest, or null.
+ * @param {{ mode?: 'since-last'|'all' }} [opts]
+ * @returns {Array<object>} The partition entries.
+ */
+export function selectPartition(entries, prevAnchor, opts = {}) {
+  const mode = opts.mode === 'all' ? 'all' : 'since-last';
+  if (mode === 'all' || !prevAnchor) return entries;
+  const coveredThrough = prevAnchor.seq_range?.[1];
+  if (typeof coveredThrough !== 'number') return entries;
+  return entries.filter((e) => e.seq > coveredThrough);
+}
+
+/**
+ * Build the anchor manifest object for a partition. Pure — no I/O, no network.
+ * The `root` + `manifest_hash` are computed here; the network/close-time fields
+ * are filled by post-anchor.js after a successful on-chain submission.
+ *
+ * @param {object} params
+ * @param {number} params.anchorSeq - 0,1,2,… ordinal of this anchor.
+ * @param {Array<object>} params.partition - The chain entries this anchor covers.
+ * @param {object|null} params.prevAnchor - The previous anchor manifest, or null.
+ * @param {string} [params.algo] - Merkle algo (default v2).
+ * @param {string} [params.network] - 'testnet' | 'mainnet' (default testnet).
+ * @param {string} [params.computedAt] - ISO timestamp (default now).
+ * @returns {object} The anchor manifest (without on-chain post fields).
+ */
+export function buildAnchorManifest({
+  anchorSeq,
+  partition,
+  prevAnchor,
+  algo = DEFAULT_ALGO,
+  network = 'testnet',
+  computedAt = new Date().toISOString(),
+}) {
+  if (!Array.isArray(partition) || partition.length === 0) {
+    throw new Error('buildAnchorManifest: partition is empty — nothing to anchor');
+  }
+  const leaves = partition.map((e) => e.submission_digest);
+  for (const [i, leaf] of leaves.entries()) {
+    if (typeof leaf !== 'string' || !/^[0-9a-fA-F]{64}$/.test(leaf)) {
+      throw new Error(`buildAnchorManifest: chain entry[${i}] has a malformed submission_digest: ${leaf}`);
+    }
+  }
+  const root = merkleRootForAlgo(leaves, algo);
+  const seqFrom = partition[0].seq;
+  const seqTo = partition[partition.length - 1].seq;
+  const headDigest = partition[partition.length - 1].submission_digest;
+
+  // The manifest base is canonicalized + hashed so the on-chain memo can bind to
+  // it. Field order is irrelevant (canonicalize sorts keys); the hash is stable.
+  const base = {
+    anchor_seq: anchorSeq,
+    manifest_version: MANIFEST_VERSION,
+    algo,
+    root,
+    leaf_count: leaves.length,
+    seq_range: [seqFrom, seqTo],
+    head_digest: headDigest,
+    prev_anchor_root: prevAnchor ? prevAnchor.root : null,
+    network,
+  };
+  const manifestHash = sha256hex(canonicalize(base));
+  return { ...base, manifest_hash: manifestHash, computed_at: computedAt };
+}
+
+/**
+ * The append-only file path for an anchor of a given seq.
+ *
+ * @param {string} repoRoot
+ * @param {number} anchorSeq
+ * @returns {string}
+ */
+export function anchorManifestPath(repoRoot, anchorSeq) {
+  const padded = String(anchorSeq).padStart(4, '0');
+  return join(anchorsDir(repoRoot), `anchor-${padded}.json`);
+}
+
+/**
+ * Compute the next anchor for a repo root and write its append-only manifest.
+ *
+ * Reads the chain, selects the partition (since-last by default), builds the
+ * manifest (Merkle root + leaf_count + seq_range + head_digest, prev-linked to
+ * the prior anchor's root), and writes it to
+ * `indexes/integrity/anchors/anchor-<NNNN>.json`.
+ *
+ * Append-only: write-if-missing, fail-if-exists-with-different-content. An empty
+ * partition (nothing new since the last anchor) returns `{ empty: true }` and
+ * writes nothing.
+ *
+ * OFFLINE — never imports xrpl, never touches the network.
+ *
+ * @param {string} repoRoot - Absolute path to the testing-os repo root.
+ * @param {object} [opts]
+ * @param {'since-last'|'all'} [opts.mode='since-last']
+ * @param {string} [opts.algo='sha256-merkle-v2']
+ * @param {string} [opts.network='testnet']
+ * @returns {{ empty: boolean, manifest?: object, path?: string, written?: boolean, leaf_count?: number }}
+ */
+export function computeAnchor(repoRoot, opts = {}) {
+  const mode = opts.mode === 'all' ? 'all' : 'since-last';
+  const algo = opts.algo || DEFAULT_ALGO;
+  if (algo !== 'sha256-merkle-v1' && algo !== 'sha256-merkle-v2') {
+    const e = new Error(`Unknown anchor algo "${algo}" (expected sha256-merkle-v1 or sha256-merkle-v2)`);
+    e.code = 'ANCHOR_BAD_ALGO';
+    throw e;
+  }
+  const network = opts.network || 'testnet';
+
+  const entries = readChainManifest(repoRoot);
+  if (entries.length === 0) {
+    return { empty: true, reason: 'chain is empty — nothing to anchor' };
+  }
+
+  const existingAnchors = readAnchorManifests(repoRoot);
+  const prevAnchor = existingAnchors.length === 0 ? null : existingAnchors[existingAnchors.length - 1];
+  const anchorSeq = existingAnchors.length;
+
+  const partition = selectPartition(entries, prevAnchor, { mode });
+  if (partition.length === 0) {
+    return { empty: true, reason: 'no chain entries since the last anchor — nothing new to anchor' };
+  }
+
+  const warnings = [];
+  if (mode === 'since-last' && partition.length > OVERSIZED_PARTITION_LEAVES) {
+    warnings.push(
+      `since-last partition has ${partition.length} leaves (> ${OVERSIZED_PARTITION_LEAVES}); ` +
+      'the anchoring cadence has likely lapsed — anchor now, then anchor once per release wave.'
+    );
+  }
+
+  const manifest = buildAnchorManifest({ anchorSeq, partition, prevAnchor, algo, network });
+
+  const path = anchorManifestPath(repoRoot, anchorSeq);
+  mkdirSync(anchorsDir(repoRoot), { recursive: true });
+  const json = JSON.stringify(manifest, null, 2) + '\n';
+
+  let written = false;
+  if (existsSync(path)) {
+    // Append-only: an existing anchor at this seq must be byte-identical (modulo
+    // the volatile computed_at field, which we do not let block a re-run).
+    const existing = JSON.parse(readFileSync(path, 'utf-8'));
+    const stableEqual =
+      existing.root === manifest.root &&
+      existing.manifest_hash === manifest.manifest_hash &&
+      existing.leaf_count === manifest.leaf_count;
+    if (!stableEqual) {
+      const e = new Error(
+        `anchor manifest conflict at ${path}: an anchor for seq ${anchorSeq} already exists ` +
+        'with a different root/hash. Anchor manifests are append-only.'
+      );
+      e.code = 'ANCHOR_MANIFEST_CONFLICT';
+      throw e;
+    }
+  } else {
+    atomicWriteFileSync(path, json);
+    written = true;
+  }
+
+  return { empty: false, manifest, path, written, leaf_count: manifest.leaf_count, warnings };
+}
+
+/**
+ * Record the on-chain facts back into an anchor manifest file after a successful
+ * post. This is the production `recordPost` callback post-anchor.js invokes.
+ *
+ * Patches an `on_chain` block into the manifest at the given seq WITHOUT touching
+ * the root / leaf_count / seq_range / head_digest (those are the contract the
+ * memo committed to — they must never change after posting). Writing the on-chain
+ * receipt is the one mutation an anchor manifest accepts: it ADDS the proof of
+ * where the root landed, it does not alter what was committed.
+ *
+ * @param {string} repoRoot
+ * @param {number} anchorSeq
+ * @param {object} facts - { tx_hash, ledger_index, close_time_iso, wallet_address, network }
+ */
+export function recordAnchorPost(repoRoot, anchorSeq, facts) {
+  const path = anchorManifestPath(repoRoot, anchorSeq);
+  if (!existsSync(path)) {
+    const e = new Error(`cannot record post: no anchor manifest at ${path} (run anchor-compute first)`);
+    e.code = 'ANCHOR_MANIFEST_MISSING';
+    throw e;
+  }
+  const manifest = JSON.parse(readFileSync(path, 'utf-8'));
+  manifest.on_chain = {
+    tx_hash: facts.tx_hash ?? null,
+    ledger_index: facts.ledger_index ?? null,
+    close_time_iso: facts.close_time_iso ?? null,
+    wallet_address: facts.wallet_address ?? null,
+    network: facts.network ?? manifest.network,
+    posted_at: new Date().toISOString(),
+  };
+  atomicWriteFileSync(path, JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}

package/anchor/config.js

@@ -0,0 +1,44 @@
+/**
+ * Anchor configuration — network defaults and the trusted-anchor-account
+ * allowlist (the authorization root for verification).
+ *
+ * Any funded XRPL wallet can post a memo, so the trust does not come from the
+ * memo — it comes from REQUIRING the posting account to be on an allowlist the
+ * verifier controls. BUNDLED_TRUSTED_ACCOUNTS is pinned here so that even if a
+ * future config file is fetched/overridden remotely, the account check can never
+ * be silently turned off: the resolver UNIONs the bundled list with any
+ * operator-supplied accounts (a remote config can ADD, never DROP).
+ *
+ * The allowlist starts EMPTY by design: testing-os has not minted a production
+ * anchor wallet yet. An operator adds their funded wallet's classic address here
+ * (and/or passes it via the CLI) when they stand up real anchoring. Verification
+ * with an empty allowlist correctly FAILS the on-chain leg — fail closed, never
+ * trust an unlisted account.
+ */
+
+/** Bundled allowlist — pinned, can never be dropped by a remote override. */
+export const BUNDLED_TRUSTED_ACCOUNTS = Object.freeze([]);
+
+/** Default network and endpoints. testnet is the default; mainnet is documented. */
+export const ANCHOR_DEFAULTS = Object.freeze({
+  network: 'testnet',
+  wsUrl: {
+    testnet: 'wss://s.altnet.rippletest.net:51233',
+    mainnet: 'wss://xrplcluster.com',
+  },
+  memoType: 'testing-os-anchor-v1',
+});
+
+/**
+ * Resolve the trusted anchor accounts: the bundled fallback UNION any
+ * operator-supplied accounts. The bundled list can never be removed, so an
+ * operator-supplied list can only ADD authorized accounts, never disable the
+ * check.
+ *
+ * @param {string[]} [operatorAccounts] - Accounts supplied via CLI/config.
+ * @returns {string[]} The de-duplicated union.
+ */
+export function resolveTrustedAccounts(operatorAccounts = []) {
+  const extra = Array.isArray(operatorAccounts) ? operatorAccounts : [];
+  return [...new Set([...BUNDLED_TRUSTED_ACCOUNTS, ...extra])];
+}