knosky 0.5.0 → 0.6.0

package/core/comparison.mjs

@@ -0,0 +1,189 @@
+// KnoSky naive-vs-guided agent comparison protocol (SAT-458).
+// Defines the artifact schema and validators for a single comparison run:
+//   tokens (in + out), tool-calls, time-to-relevant-file, correctness
+// for both a naive agent and an identical task run with KnoSky guidance.
+// Pure Node stdlib, ESM — no new deps.
+
+import { PROTOCOL_VERSION } from './schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Artifact type constant
+// ---------------------------------------------------------------------------
+
+/** @type {string} */
+export const COMPARISON_ARTIFACT_TYPE = 'comparison-run';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when `p` is a relative-safe file path:
+ *   — non-empty string
+ *   — does not start with `/` (Unix absolute) or Windows drive letter
+ *   — contains no `..` path segment
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isRelativeSafePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  if (p.startsWith('/')) return false;
+  if (/^[A-Za-z]:[\\\/]/.test(p)) return false;
+  if (p.split(/[/\\]/).some(s => s === '..')) return false;
+  return true;
+}
+
+/**
+ * Validate one metric side object (either `naive` or `guided`).
+ * Returns an array of violation strings; empty means valid.
+ *
+ * @param {unknown} side
+ * @param {string}  label   — "naive" or "guided"
+ * @returns {string[]}
+ */
+function validateSide(side, label) {
+  const errors = [];
+
+  if (!side || typeof side !== 'object') {
+    errors.push(`${label} must be an object`);
+    return errors; // can't go further
+  }
+
+  // tokens_in: non-negative integer
+  if (!Number.isInteger(side.tokens_in) || side.tokens_in < 0) {
+    errors.push(`${label}.tokens_in must be a non-negative integer, got: ${JSON.stringify(side.tokens_in)}`);
+  }
+
+  // tokens_out: non-negative integer
+  if (!Number.isInteger(side.tokens_out) || side.tokens_out < 0) {
+    errors.push(`${label}.tokens_out must be a non-negative integer, got: ${JSON.stringify(side.tokens_out)}`);
+  }
+
+  // tool_calls: non-negative integer
+  if (!Number.isInteger(side.tool_calls) || side.tool_calls < 0) {
+    errors.push(`${label}.tool_calls must be a non-negative integer, got: ${JSON.stringify(side.tool_calls)}`);
+  }
+
+  // time_to_relevant_file_ms: null (never found) or non-negative number
+  const ttrf = side.time_to_relevant_file_ms;
+  if (ttrf !== null && !(typeof ttrf === 'number' && ttrf >= 0)) {
+    errors.push(
+      `${label}.time_to_relevant_file_ms must be null or a non-negative number, got: ${JSON.stringify(ttrf)}`,
+    );
+  }
+
+  // correct: boolean
+  if (typeof side.correct !== 'boolean') {
+    errors.push(`${label}.correct must be a boolean, got: ${JSON.stringify(side.correct)}`);
+  }
+
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// makeComparisonRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Construct a KnoSky `comparison-run` artifact envelope.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.task_id             Short identifier for this task.
+ * @param {string}   opts.task_description    Human-readable description of the task.
+ * @param {string[]} opts.target_files        Relative paths to the "relevant" files for this task.
+ * @param {object}   opts.naive               Metrics for the naive agent (no KnoSky guidance).
+ * @param {number}   opts.naive.tokens_in     Input tokens consumed.
+ * @param {number}   opts.naive.tokens_out    Output tokens produced.
+ * @param {number}   opts.naive.tool_calls    Total tool/function calls made.
+ * @param {number|null} opts.naive.time_to_relevant_file_ms  ms until first relevant-file hit, or null.
+ * @param {boolean}  opts.naive.correct       Whether the agent arrived at the correct answer.
+ * @param {object}   opts.guided              Same metric shape for the KnoSky-guided agent.
+ * @returns {object}
+ */
+export function makeComparisonRun({
+  task_id,
+  task_description,
+  target_files = [],
+  naive,
+  guided,
+} = {}) {
+  return {
+    knosky_protocol: PROTOCOL_VERSION,
+    artifact_type: COMPARISON_ARTIFACT_TYPE,
+    advisory: true,
+    generated_at: new Date().toISOString(),
+    task_id,
+    task_description,
+    target_files,
+    naive,
+    guided,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateComparisonRun
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a KnoSky `comparison-run` document.
+ * Collects every violation; `ok` is true only when `errors` is empty.
+ *
+ * @param {object} doc
+ * @returns {{ ok: boolean, errors: string[] }}
+ */
+export function validateComparisonRun(doc) {
+  const errors = [];
+
+  if (!doc || typeof doc !== 'object') {
+    return { ok: false, errors: ['doc must be an object'] };
+  }
+
+  if (doc.knosky_protocol !== PROTOCOL_VERSION) {
+    errors.push(
+      `knosky_protocol must be "${PROTOCOL_VERSION}", got: ${JSON.stringify(doc.knosky_protocol)}`,
+    );
+  }
+
+  if (doc.artifact_type !== COMPARISON_ARTIFACT_TYPE) {
+    errors.push(
+      `artifact_type must be "${COMPARISON_ARTIFACT_TYPE}", got: ${JSON.stringify(doc.artifact_type)}`,
+    );
+  }
+
+  if (doc.advisory !== true) {
+    errors.push(`advisory must be true, got: ${JSON.stringify(doc.advisory)}`);
+  }
+
+  // task_id: non-empty string
+  if (typeof doc.task_id !== 'string' || doc.task_id.length === 0) {
+    errors.push(`task_id must be a non-empty string, got: ${JSON.stringify(doc.task_id)}`);
+  }
+
+  // task_description: non-empty string
+  if (typeof doc.task_description !== 'string' || doc.task_description.length === 0) {
+    errors.push(
+      `task_description must be a non-empty string, got: ${JSON.stringify(doc.task_description)}`,
+    );
+  }
+
+  // target_files: non-empty array of relative-safe path strings
+  if (!Array.isArray(doc.target_files) || doc.target_files.length === 0) {
+    errors.push('target_files must be a non-empty array');
+  } else {
+    for (let i = 0; i < doc.target_files.length; i++) {
+      const p = doc.target_files[i];
+      if (typeof p !== 'string' || p.length === 0) {
+        errors.push(`target_files[${i}] must be a non-empty string`);
+      } else if (!isRelativeSafePath(p)) {
+        errors.push(`target_files[${i}] must be a relative path with no ".." segments: ${JSON.stringify(p)}`);
+      }
+    }
+  }
+
+  // naive and guided sides
+  for (const side of ['naive', 'guided']) {
+    errors.push(...validateSide(doc[side], side));
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/core/constants.mjs

@@ -0,0 +1,13 @@
+// Shared, dependency-free constants used by more than one core module.
+// Kept in its own file (no imports, no side effects) so any core/*.mjs can
+// import from it without creating a circular dependency between modules.
+
+// Upper bound for a plausible ledger sequence (git commit count). 1 billion
+// is far beyond any real repo's commit count and far below
+// Number.MAX_SAFE_INTEGER (~9e15), so it rejects implausible/attacker-
+// supplied values (e.g. 1e100) with no precision-loss risk of its own.
+// Enforced independently at two layers — core/freshness.mjs's
+// extractLedgerSeq (structural validation) and core/ledger.mjs's
+// checkAndAdvance (the persisted guard itself) — both import this single
+// source of truth so the two layers cannot silently diverge.
+export const MAX_PLAUSIBLE_LEDGER_SEQ = 1_000_000_000;

package/core/cross-repo.mjs

@@ -0,0 +1,111 @@
+// Cross-repo graph utilities (SAT-448): edge detection, boundary extraction, and rendering metadata.
+// Pure logic — no filesystem access, no new deps. Works on the in-memory city/byId structures
+// produced by retrieve.load() or any equivalent.
+//
+// A node's *repo* identity is determined by provenance.repo when present, falling back to
+// provenance.store (e.g. "fs", "gh:owner/repo") so existing city data stays fully compatible —
+// single-repo graphs have no cross-repo edges because every node shares the same store value.
+
+// ---------------------------------------------------------------------------
+// repoOf
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the repository identity of a node.
+ * Preference order:
+ *   1. node.provenance.repo  — explicit multi-repo label (new field, optional)
+ *   2. node.provenance.store — always present; used as the identity when repo is absent
+ *      (works correctly for single-repo graphs: all nodes share one store → no cross edges)
+ *
+ * Returns null if provenance is absent or malformed.
+ *
+ * @param {object} node
+ * @returns {string|null}
+ */
+export function repoOf(node) {
+  if (!node || typeof node !== 'object') return null;
+  const prov = node.provenance;
+  if (!prov || typeof prov !== 'object') return null;
+  if (typeof prov.repo === 'string' && prov.repo.length > 0) return prov.repo;
+  if (typeof prov.store === 'string' && prov.store.length > 0) return prov.store;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// isCrossRepoEdge
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when the edge (fromId → toId) crosses a repo boundary.
+ * An edge is cross-repo when repoOf(fromNode) !== repoOf(toNode) AND both are non-null.
+ * Edges where either endpoint is missing or has no repo identity are treated as same-repo
+ * (conservative: no false positives).
+ *
+ * @param {Map<string, object>} byId   — node map from retrieve.load()
+ * @param {string}              fromId
+ * @param {string}              toId
+ * @returns {boolean}
+ */
+export function isCrossRepoEdge(byId, fromId, toId) {
+  const src = byId.get(fromId);
+  const dst = byId.get(toId);
+  if (!src || !dst) return false;
+  const r1 = repoOf(src);
+  const r2 = repoOf(dst);
+  if (r1 === null || r2 === null) return false;
+  return r1 !== r2;
+}
+
+// ---------------------------------------------------------------------------
+// getCrossRepoEdges
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk every node's `links` array and return all edges that cross a repo boundary.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ from: string, to: string, fromRepo: string, toRepo: string }>}
+ */
+export function getCrossRepoEdges(ctx) {
+  const edges = [];
+  for (const node of (ctx.city.nodes || [])) {
+    if (!Array.isArray(node.links)) continue;
+    const fromRepo = repoOf(node);
+    if (fromRepo === null) continue;
+    for (const toId of node.links) {
+      const dst = ctx.byId.get(toId);
+      if (!dst) continue;
+      const toRepo = repoOf(dst);
+      if (toRepo === null) continue;
+      if (fromRepo !== toRepo) {
+        edges.push({ from: node.id, to: toId, fromRepo, toRepo });
+      }
+    }
+  }
+  return edges;
+}
+
+// ---------------------------------------------------------------------------
+// getRepoBoundaries
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a summary of every distinct repo present in the graph and its node membership.
+ *
+ * @param {object} ctx  — { city: { nodes: [] }, byId: Map }
+ * @returns {Array<{ repo: string, nodeIds: string[], count: number }>}
+ *            Sorted by count desc, then repo asc.
+ */
+export function getRepoBoundaries(ctx) {
+  /** @type {Map<string, string[]>} */
+  const byRepo = new Map();
+  for (const node of (ctx.city.nodes || [])) {
+    const r = repoOf(node);
+    if (r === null) continue;
+    if (!byRepo.has(r)) byRepo.set(r, []);
+    byRepo.get(r).push(node.id);
+  }
+  return [...byRepo.entries()]
+    .map(([repo, nodeIds]) => ({ repo, nodeIds, count: nodeIds.length }))
+    .sort((a, b) => b.count - a.count || String(a.repo).localeCompare(String(b.repo)));
+}

package/core/escalate.mjs

@@ -0,0 +1,68 @@
+// KnoSky HITL escalation gate (D-166 / SAT-467) — any P0/critical or ambiguous
+// review result must surface to Paul, never proceed silently.
+// D-166 (SAT-466): zero-P0/critical + all reviewers succeeded → auto-proceed-to-publish.
+// Pure function: no I/O, no external dependencies, safe to import anywhere.
+
+/**
+ * Decide whether a review result must be escalated to Paul, or may auto-publish.
+ *
+ * Rules (D-166 hitl gate, SAT-467 / SAT-466):
+ *   - One or more CRITICAL findings   → P0, escalate immediately.
+ *   - All reviewers failed             → ambiguous (no result at all), escalate.
+ *   - Any reviewer failed (degraded)   → ambiguous (result is incomplete), escalate.
+ *   - Zero criticals + zero failures + at least one reviewer ran
+ *                                      → canAutoPublish (D-166 pre-authorized path).
+ *
+ * @param {object}   opts
+ * @param {object[]} [opts.criticals]  CRITICAL findings ({ sev, file, hint, role }).
+ * @param {object[]} [opts.failed]     Failed reviewer records ({ role, err, ok: false }).
+ * @param {number}   [opts.total]      Total reviewer count dispatched this run.
+ * @returns {{ escalate: boolean, reasons: string[], paulMessage: string, canAutoPublish: boolean }}
+ *   escalate       — true iff the result must block and surface to Paul.
+ *   reasons        — human-readable list explaining why escalation was triggered
+ *                    (empty array when escalate === false).
+ *   paulMessage    — the block line to embed in the PR review body;
+ *                    non-empty iff escalate === true.
+ *   canAutoPublish — DATA ONLY, not an authorization by itself (D-173): true iff a clean
+ *                    review (zero criticals, zero reviewer failures, ≥1 reviewer ran)
+ *                    would satisfy D-166's pre-authorized-publish condition. Callers must
+ *                    NOT treat this as license to take an autonomous action (e.g. approving
+ *                    a PR, publishing a release) on its own -- it exists so a separately
+ *                    gated, narrowly-scoped release workflow can consume it for the actual
+ *                    SAT-437/D-166 publish decision. The general per-PR review script
+ *                    deliberately does NOT act on it -- see that script's own comments.
+ */
+export function shouldEscalateToPaul({ criticals = [], failed = [], total = 0 } = {}) {
+  const reasons = [];
+
+  // P0 / critical findings — must never pass silently
+  if (criticals.length > 0) {
+    reasons.push(`${criticals.length} CRITICAL finding(s)`);
+  }
+
+  const allFailed = total > 0 && failed.length === total;
+
+  if (allFailed) {
+    // No reviewer returned a result — outcome is unknowable (ambiguous)
+    reasons.push('all reviewers failed (no result — ambiguous)');
+  } else if (failed.length > 0) {
+    // At least one reviewer failed — remaining results are incomplete (ambiguous)
+    reasons.push(`${failed.length} of ${total} reviewer(s) failed (degraded — ambiguous)`);
+  }
+
+  const escalate = reasons.length > 0;
+
+  // D-166 (SAT-466): pre-authorized auto-publish path — zero criticals, all reviewers
+  // succeeded, and at least one reviewer actually ran.  Do NOT auto-publish when total
+  // is 0 (no-reviewer synthetic run) — that would be a silent pass with no evidence.
+  const canAutoPublish = !escalate && total > 0 && failed.length === 0;
+
+  return {
+    escalate,
+    reasons,
+    paulMessage: escalate
+      ? 'Merge blocked until CRITICAL items are resolved or dismissed by Paul.'
+      : '',
+    canAutoPublish,
+  };
+}

package/core/freshness.mjs

@@ -0,0 +1,194 @@
+// KnoSky ledger-anchored freshness attestation (SAT-444, SAT-474).
+//
+// Closes the clock-skew / key-resurrection gap by basing freshness on the
+// repository's commit count rather than wall-clock time.  A `ledger_seq`
+// is a monotone integer — the number of commits reachable from HEAD —
+// which cannot be fabricated by adjusting the system clock and can only
+// decrease when history is rewritten (the ledger-truncation attack caught
+// by the high-water-mark guard in core/ledger.mjs).
+//
+// SAT-474: validateFreshnessWithHwm() routes through the *persisted*
+// checkAndAdvance() guard (core/ledger.mjs) so that the rollback defence
+// survives process restarts.  validateFreshness() is retained for callers
+// that manage their own in-memory lastSeq (e.g. protocol-spec validation).
+// Pure Node stdlib, ESM — no third-party dependencies.
+
+import { execFileSync } from 'node:child_process';
+import { checkAndAdvance } from './ledger.mjs';
+import { MAX_PLAUSIBLE_LEDGER_SEQ } from './constants.mjs';
+
+// ---------------------------------------------------------------------------
+// extractLedgerSeq — read the ledger_seq stored in a city envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the `ledger_seq` from a city envelope or any artifact that carries
+ * one.  Returns null when absent, not a non-negative integer, or implausibly
+ * large (see MAX_PLAUSIBLE_LEDGER_SEQ).
+ *
+ * @param {object} obj  City envelope or comparable artifact object.
+ * @returns {number|null}
+ */
+export function extractLedgerSeq(obj) {
+  if (!obj || typeof obj !== 'object') return null;
+  const seq = obj.ledger_seq;
+  if (typeof seq !== 'number' || !Number.isInteger(seq) || seq < 0) return null;
+  if (seq > MAX_PLAUSIBLE_LEDGER_SEQ) return null;
+  return seq;
+}
+
+// ---------------------------------------------------------------------------
+// computeLedgerSeq — derive a ledger_seq from a git repo on disk
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the ledger_seq for `root` by counting all commits reachable from
+ * HEAD (`git rev-list --count HEAD`).  Returns 0 when git is unavailable or
+ * the directory has no commit history (e.g. a brand-new repo with no commits).
+ *
+ * @param {string} root  Absolute path to the git working tree.
+ * @returns {number}  Non-negative integer commit count.
+ */
+export function computeLedgerSeq(root) {
+  try {
+    const out = execFileSync(
+      'git',
+      ['rev-list', '--count', 'HEAD'],
+      { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    ).trim();
+    const n = parseInt(out, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+  } catch {
+    // No git / no commits / non-repo directory → 0  (safe: sequence starts fresh)
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// checkHighWaterMark — V13 guard against ledger-truncation attack
+// ---------------------------------------------------------------------------
+
+/**
+ * High-water-mark guard (V13).
+ *
+ * Returns `{ ok: true }` when `newSeq` is strictly greater than `lastSeq`,
+ * meaning the city has advanced — its ledger has grown (or this is the first
+ * load, indicated by `lastSeq === null`).
+ *
+ * Returns `{ ok: false, reason }` when `newSeq` is ≤ `lastSeq`, which means
+ * the ledger has been truncated or replayed — a potential key-resurrection or
+ * rollback attack.  Callers MUST treat stale/equal as suspicious.
+ *
+ * @param {number|null} lastSeq  Previously accepted ledger_seq, or null on
+ *                               first load (unconditionally accepted).
+ * @param {number|null} newSeq   Ledger_seq from the incoming artifact, or
+ *                               null when absent (treated as 0 — conservative).
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function checkHighWaterMark(lastSeq, newSeq) {
+  // Treat missing seq as 0 — conservative: an artifact with no ledger anchoring
+  // is as trustworthy as a brand-new repo.
+  const effective = (typeof newSeq === 'number' && Number.isInteger(newSeq) && newSeq >= 0)
+    ? newSeq
+    : 0;
+
+  // First load: no last seq to compare against — unconditionally accept.
+  if (lastSeq === null || lastSeq === undefined) {
+    return { ok: true };
+  }
+
+  if (typeof lastSeq !== 'number' || !Number.isInteger(lastSeq) || lastSeq < 0) {
+    // Corrupt lastSeq — treat it as 0 (reset the watermark)
+    return { ok: true };
+  }
+
+  if (effective > lastSeq) {
+    return { ok: true };
+  }
+
+  // equal: rolled back to same point (replay) or no new commits
+  // less: ledger truncation — history was rewritten
+  const direction = effective < lastSeq ? 'ledger truncated' : 'ledger not advanced';
+  return {
+    ok: false,
+    reason:
+      direction +
+      ': incoming ledger_seq ' + effective +
+      ' is not greater than last accepted ' + lastSeq +
+      ' — possible rollback or key-resurrection attack',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// validateFreshness — full attestation check for an incoming artifact
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the freshness of an incoming artifact against an optional stored
+ * high-water mark.
+ *
+ * Combines:
+ *  (1) structural check: `ledger_seq` is present and a non-negative integer
+ *  (2) V13 high-water-mark guard: `ledger_seq` must exceed the last accepted
+ *      value (pass `null` on first load to skip this check)
+ *
+ * @param {object}      artifact  City envelope or protocol artifact.
+ * @param {number|null} lastSeq   Last accepted ledger_seq (null = first load).
+ * @returns {{ ok: boolean, ledger_seq: number|null, errors: string[] }}
+ */
+export function validateFreshness(artifact, lastSeq = null) {
+  const errors = [];
+  const seq = extractLedgerSeq(artifact);
+
+  if (seq === null) {
+    errors.push('ledger_seq is missing or not a non-negative integer');
+  }
+
+  const hwm = checkHighWaterMark(lastSeq, seq);
+  if (!hwm.ok) {
+    errors.push(hwm.reason);
+  }
+
+  return { ok: errors.length === 0, ledger_seq: seq, errors };
+}
+
+// ---------------------------------------------------------------------------
+// validateFreshnessWithHwm — persisted-HWM variant (SAT-474)
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate freshness through the **persisted** high-water-mark guard
+ * (`core/ledger.mjs` `checkAndAdvance`).
+ *
+ * Unlike `validateFreshness`, this function reads and updates the HWM from
+ * `hwmPath` on disk, so the rollback defence is durable across process
+ * restarts.  Callers that previously maintained an in-memory `lastSeq` and
+ * passed it to `validateFreshness` should migrate to this function and a
+ * stable `hwmPath` in their data directory.
+ *
+ * Semantics of the persisted guard (from `checkAndAdvance`):
+ *   - seq STRICTLY LESS than HWM → rejected (anti-truncation guard)
+ *   - seq EQUAL to HWM           → accepted (idempotent replay)
+ *   - seq GREATER than HWM       → accepted and HWM advanced
+ *
+ * @param {object} artifact  City envelope or protocol artifact.
+ * @param {string} hwmPath   Path to the independently-persisted HWM file.
+ * @returns {{ ok: boolean, ledger_seq: number|null, errors: string[] }}
+ */
+export function validateFreshnessWithHwm(artifact, hwmPath) {
+  const errors = [];
+  const seq = extractLedgerSeq(artifact);
+
+  if (seq === null) {
+    errors.push('ledger_seq is missing or not a non-negative integer');
+    // Cannot call checkAndAdvance with a null seq — return early.
+    return { ok: false, ledger_seq: null, errors };
+  }
+
+  const result = checkAndAdvance(seq, hwmPath);
+  if (!result.ok) {
+    errors.push(result.error);
+  }
+
+  return { ok: errors.length === 0, ledger_seq: seq, errors };
+}

package/core/fs-indexer.mjs

@@ -7,6 +7,7 @@ import { execSync } from 'node:child_process';
 import { SCHEMA_VERSION, IGNORE_DEFAULTS, deriveCategories, serializeNode, validateCity, setRedactTerms, findSecrets } from './contract.mjs';
 import { extractImportSpecifiers, resolveSpec } from './edges.mjs';
 import { gitChurn } from './churn.mjs';
+import { computeLedgerSeq } from './freshness.mjs';
 
 const args = Object.fromEntries(process.argv.slice(2).map((a, i, arr) => a.startsWith('--') ? [a.slice(2), arr[i + 1]] : []).filter(Boolean));
 const ROOT = args.root && path.resolve(args.root);
@@ -163,10 +164,15 @@ const preList = preHits.map(h => h[0] + ':' + h[1]).join(', ');
 const nodes = raw.map(serializeNode);
 const catIds = [...new Set(nodes.map(n => n.category))].sort();
 const categories = deriveCategories(catIds);
+// Ledger-anchored freshness (SAT-444): monotone commit count, used as a
+// replay-resistant sequence number.  Consumers compare against the last
+// accepted ledger_seq (V13 high-water-mark guard) to detect rollbacks.
+const ledger_seq = computeLedgerSeq(ROOT);
 const city = {
   schema_version: SCHEMA_VERSION,
   generated_at: new Date().toISOString(),
   source: { kind: 'fs', ref: INCLUDE_ABS ? ROOT : path.basename(ROOT), rev: REV },
+  ledger_seq,
   categories, node_count: nodes.length, nodes,
 };