@ecoma-io/archkeep 0.24.1 → 0.26.0

package/src/commands/delta.mjs

@@ -105,10 +105,15 @@ import {
   serializeEvidenceSnapshot,
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { eventSnapshotSide } from "./history.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
+import { describe } from "../values.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 const require = createRequire(import.meta.url);
 /** @type {{name: string, version: string}} */
@@ -381,11 +386,15 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  *   a custom-rule-only introduced finding never reaches the VIOLATION
  *   predicate, so a classifications scan would read "accepted" on an exit-1
  *   run — the silent direction;
- * - everything else — a clean comparable capture (`ok`, `[]` classifications),
- *   an `ok` capture with a fact class (REPAIR, CHANGE, DRIFT,
- *   DECISION_CHANGE — each accepted by the vocabulary `classification` earns),
- *   or an `ok` capture holding a WAIVED violation (a waiver is a tracked
- *   acceptance — which is exactly what kept the gate `ok`) ⇒ `accepted`.
+ * - `ok` status — a clean comparable capture (`[]` classifications), an `ok`
+ *   capture with a fact class (REPAIR, CHANGE, DRIFT, DECISION_CHANGE — each
+ *   accepted by the vocabulary `classification` earns), or an `ok` capture
+ *   holding a WAIVED violation (a waiver is a tracked acceptance — which is
+ *   exactly what kept the gate `ok`) ⇒ `accepted`;
+ * - any OTHER status — a typo, a case- or whitespace-mangled spelling, an
+ *   absent field — THROWS naming the input, the input latch `verdictFor`
+ *   holds. There is no fourth status to fold, and folding a stranger to a
+ *   verdict would be the silent direction.
  *
  * The two refusals that can never reach this mapping — an unjudgeable head
  * and a provider mismatch — THROW before any event exists, so a delta that
@@ -394,12 +403,162 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
  *
  * @param {{status: "ok"|"findings"|"no-verdict"}} input
  * @returns {"accepted"|"rejected"|"no-verdict"}
+ * @throws {Error} On any `status` outside the three-verb contract, naming the
+ *   input.
  */
 export function deltaDisposition({ status }) {
   // used by its own test
   if (status === "no-verdict") return "no-verdict";
   if (status === "findings") return "rejected";
-  return "accepted";
+  if (status === "ok") return "accepted";
+  throw new Error(
+    `deltaDisposition: unknown delta status ${describe(status)} — expected "ok", "findings", ` +
+      `or "no-verdict". A status outside the delta verb's own contract has no disposition; ` +
+      `guessing one would be the silent direction. This is a bug in archkeep, not a fact about ` +
+      `the workspace.`,
+  );
+}
+
+/**
+ * The input latch for `deltaFold`: names the first counted bucket that is not
+ * an array, or `null` when every one is. A returned problem becomes the
+ * fold's refusal — never a throw, because the refusal is a fact about the run
+ * the command reports in-band, the same lane an `unknown` classification
+ * takes.
+ *
+ * Every bucket the COMMAND counts is validated, not only the ones the fold
+ * reads first: the custom-rule notes loop, the §1 mapping, `result.summary`
+ * and both report faces count the same buckets downstream of the fold, so a
+ * bucket that would crash or silently empty one of them is refused while
+ * there is still a verdict to withhold.
+ *
+ * @param {object} classification From `classifyDelta`.
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+ *   unknown: object[]}}|null} custom
+ * @returns {string|null}
+ */
+function deltaFoldInputProblem(classification, custom) {
+  const counted = [
+    ["classification.violations.introduced", classification?.violations?.introduced],
+    ["classification.violations.resolved", classification?.violations?.resolved],
+    ["classification.violations.unchanged", classification?.violations?.unchanged],
+    ["classification.violations.unknown", classification?.violations?.unknown],
+    ["classification.unresolvable.introduced", classification?.unresolvable?.introduced],
+    ["classification.unresolvable.resolved", classification?.unresolvable?.resolved],
+    ["classification.unresolvable.unchanged", classification?.unresolvable?.unchanged],
+    ["classification.unresolvable.unknown", classification?.unresolvable?.unknown],
+    ...(custom === null
+      ? []
+      : [
+          ["custom.judged", custom?.judged],
+          ["custom.skipped", custom?.skipped],
+          ["custom.removed", custom?.removed],
+          ["custom.findings.introduced", custom?.findings?.introduced],
+          ["custom.findings.resolved", custom?.findings?.resolved],
+          ["custom.findings.unchanged", custom?.findings?.unchanged],
+          ["custom.findings.unknown", custom?.findings?.unknown],
+        ]),
+  ];
+  for (const [name, value] of counted) {
+    if (!Array.isArray(value)) {
+      return `the delta fold counts "${name}", which is ${describe(value)} — a bucket that is not an array counts as empty in every lane, and an empty delta reads "no change". This is a bug in archkeep, not a fact about the workspace.`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The `delta` exit fold, lifted out of `deltaCommand` as a pure function so
+ * the mapping from classification buckets to the verdict is a fact a test can
+ * pin (`./change.mjs`'s `reconcileDisposition` is the arrangement's
+ * precedent). The lane order is the one `deltaCommand`'s header states:
+ * introduced-and-not-waived (violations and custom findings alike) →
+ * `findings`/1; else any unknown item → `no-verdict`/3; else `ok`/0.
+ *
+ * The input latch runs first: a bucket the fold cannot read is refused as a
+ * no-verdict whose single reason names it (`refused`), never folded past as a
+ * silently-empty count. The literals stay hand-rolled per site by decision —
+ * the carrier folds are the pinned baseline INV-2 names, not a table to be
+ * converged (`docs/architecture/refactor/AUTHORITY-MAP.md`).
+ *
+ * Pure and exported for the fold's own tests; `deltaCommand` is its only
+ * production caller.
+ *
+ * @param {object} classification From `classifyDelta`.
+ * @param {{judged: object[], skipped: object[], removed: string[],
+ *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+ *   unknown: object[]}}|null} custom
+ * @returns {{status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   decision: object, introducedWaived: number, refused?: undefined}|
+ *   {status: "no-verdict", exitCode: 3, decision: object, introducedWaived?: undefined,
+ *   refused: string}}
+ *   `introducedWaived` rides every judged lane because `result.summary`
+ *   reports it whichever lane fired; a refusal carries `refused` and no
+ *   counts, and is the one return whose `decision.reason` names a malformed
+ *   input rather than a fact about the trees.
+ */
+export function deltaFold(classification, custom) {
+  const problem = deltaFoldInputProblem(classification, custom);
+  if (problem !== null) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason: problem,
+      }),
+      refused: problem,
+    };
+  }
+  const { violations, unresolvable } = classification;
+  const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
+  const introducedNotWaived = violations.introduced.length - introducedWaived;
+  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
+  // `classifyCustomFindings` argues the by-construction absence), so every
+  // introduced one gates.
+  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
+  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
+  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
+
+  if (introducedNotWaived + customIntroduced > 0) {
+    return {
+      status: "findings",
+      exitCode: 1,
+      decision: buildDecision({
+        status: "findings",
+        coverageComplete: true,
+        findings: introducedNotWaived + customIntroduced,
+      }),
+      introducedWaived,
+    };
+  }
+  if (unknownCount > 0) {
+    return {
+      status: "no-verdict",
+      exitCode: 3,
+      decision: buildDecision({
+        status: "no-verdict",
+        coverageComplete: true,
+        findings: 0,
+        reason:
+          `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
+          (customUnknown > 0
+            ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
+            : "") +
+          `an item whose identity cannot be stated is never guessed into a bucket`,
+      }),
+      introducedWaived,
+    };
+  }
+  return {
+    status: "ok",
+    exitCode: 0,
+    decision: buildDecision({ status: "ok", coverageComplete: true, findings: 0 }),
+    introducedWaived,
+  };
 }
 
 /** First eight hex characters of a fingerprint, for prose that names one. */
@@ -448,8 +607,8 @@ const short = (fingerprint) =>
  *   `loadIntent`; absent intent ⇒ no ids, an in-band note says so), and the
  *   custom-rule host's two injectable seams, passed through to
  *   `customRulesForDelta`.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta?: object,
- *   coverage: object,
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
+ *   exitCode: 0|1|3, delta?: object, coverage: object,
  *   eventWrite?: {id: string, duplicate: boolean}|null,
  *   report: {text: string, json: string, sarif?: string}}>} `delta` carries
  *   the additive `classifications`/`affected` fields (design §1); `eventWrite`
@@ -569,16 +728,10 @@ export async function deltaCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
 
   // The event's structural signal: what moved between the two graphs the
@@ -588,10 +741,11 @@ export async function deltaCommand(
   // a second spelling of "changed". The head side is rebuilt by the same
   // `buildProjects`/`buildDependencies` the snapshot stores
   // (`./delta-snapshot.mjs`), which is what makes the two sides comparable.
-  const structuralDiff = computeDiff(baseline.graph, {
+  const headGraph = {
     projects: buildProjects(graph.nodes),
     dependencies: buildDependencies(graph.dependencies),
-  });
+  };
+  const structuralDiff = computeDiff(baseline.graph, headGraph);
   const structural = {
     projects: {
       added: structuralDiff.addedProjects.map((project) => project.name),
@@ -618,6 +772,25 @@ export async function deltaCommand(
   // same", and a policy change is disclosed, not folded into drift.
   const baseCommit = baseline.provenance?.commit;
   const headCommit = headProvenance?.commit;
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything below this line
+  // (custom rules, classification, intent, debt) reads the graphs too; the
+  // engine's purity is what keeps them honest today, but the WS-I adversarial
+  // audit named the seam: identity and diff agreeing must not rest on purity
+  // conventions alone when one structural line closes it.
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseline.graph.projects,
+    dependencies: baseline.graph.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraph.projects,
+    dependencies: headGraph.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const provenanceAdvanced =
     typeof baseCommit === "string" &&
     typeof headCommit === "string" &&
@@ -676,6 +849,48 @@ export async function deltaCommand(
       findings: { introduced: [], resolved: [], unchanged: [], unknown: [] },
     };
   }
+  // The exit fold, taken the moment both of its inputs are final: everything
+  // below — the custom-rule notes loop, the §1 mapping, `result.summary`, both
+  // report faces — counts the same buckets, and a malformed one must be
+  // refused HERE, in-band (no-verdict, exit 3, the bucket named), never
+  // counted past as a silently-empty bucket. The refusal withholds `delta`
+  // and the event exactly the coverage refusal does (#608): a comparison
+  // whose counts could not be read has no result to report.
+  const fold = deltaFold(classification, custom);
+  if (fold.refused !== undefined) {
+    const refusalCoverage = {
+      complete: true,
+      projects: Object.keys(graph.nodes).length,
+      analyzedFiles: analysis.analyzed,
+      imports: analysis.imports.length,
+      notAnalyzed: [],
+      blindSpots: blindSpotRows(analysis.failures),
+      notes: [fold.refused],
+    };
+    return {
+      status: fold.status,
+      exitCode: fold.exitCode,
+      coverage: refusalCoverage,
+      report: {
+        text: `delta: no verdict — ${fold.refused}\n`,
+        json: renderJson(
+          jsonEnvelope({
+            command: "delta",
+            context: { root, provider, marker, provenance: headProvenance },
+            status: fold.status,
+            exitCode: fold.exitCode,
+            coverage: refusalCoverage,
+            // The refusal-withheld payload, stated the way `coverageRefusal`
+            // states it: `jsonEnvelope` requires the key, the refusal has no
+            // result to report.
+            result: undefined,
+            decision: fold.decision,
+          }),
+        ),
+      },
+    };
+  }
+
   if (custom !== null) {
     for (const skipped of custom.skipped) {
       notes.push(`custom rule "${skipped.name}" was not classified — ${skipped.reason}`);
@@ -722,48 +937,10 @@ export async function deltaCommand(
     codeDrift,
   });
 
+  // The verdict, from the one fold — `deltaFold` above owns the lane order
+  // and the input latch; this destructure is the command's only hand in it.
   const { violations, unresolvable } = classification;
-  const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
-  const introducedNotWaived = violations.introduced.length - introducedWaived;
-  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
-  // `classifyCustomFindings` argues the by-construction absence), so every
-  // introduced one gates.
-  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
-  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
-  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
-
-  /** @type {"ok"|"findings"|"no-verdict"} */
-  let status;
-  /** @type {0|1|3} */
-  let exitCode;
-  let decision;
-  if (introducedNotWaived + customIntroduced > 0) {
-    status = "findings";
-    exitCode = 1;
-    decision = buildDecision({
-      status,
-      coverageComplete: true,
-      findings: introducedNotWaived + customIntroduced,
-    });
-  } else if (unknownCount > 0) {
-    status = "no-verdict";
-    exitCode = 3;
-    decision = buildDecision({
-      status,
-      coverageComplete: true,
-      findings: 0,
-      reason:
-        `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
-        (customUnknown > 0
-          ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
-          : "") +
-        `an item whose identity cannot be stated is never guessed into a bucket`,
-    });
-  } else {
-    status = "ok";
-    exitCode = 0;
-    decision = buildDecision({ status, coverageComplete: true, findings: 0 });
-  }
+  const { status, exitCode, decision, introducedWaived } = fold;
 
   const coverage = {
     complete: true,
@@ -878,13 +1055,18 @@ export async function deltaCommand(
       schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
       kind: "transition",
       source: "delta",
-      base: {
-        ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-        // The evidence ref is the baseline file this run actually compared
-        // against — a pointer into the evidence, never a graph.
-        evidence: baselinePath,
-      },
-      head: typeof headCommit === "string" ? { revision: headCommit } : {},
+      // Both sides were frozen through the ONE identity spelling
+      // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a
+      // revision when one is known, plus the snapshot identity of the graph
+      // the diff compared — never the baseline's storage path, which is
+      // machine-local and must not make the identity a per-machine property.
+      base: eventBase,
+      head: eventHead,
+      // The evidence ref is the baseline file this run actually compared
+      // against — a pointer into the evidence, never a graph, and disclosed
+      // OUTSIDE the identity: the tuple above names the state itself, so a
+      // relocated baseline is still the same event.
+      evidence: baselinePath,
       recordedAt: recordOrigin({
         by: "cli",
         tool: `archkeep:v${TOOL_VERSION}`,
@@ -928,6 +1110,7 @@ export async function deltaCommand(
 
   return {
     status,
+    exitCode,
     eventWrite,
     delta: result,
     coverage,
@@ -941,3 +1124,54 @@ export async function deltaCommand(
     },
   };
 }
+
+/**
+ * `delta --capture` as the CLI drives it: the shared preamble — command
+ * context, then the boundary law — resolved here, so `../../cli.mjs`'s
+ * driver only wires where the evidence text lands. The engine this returns
+ * from is `captureDelta` above, unchanged; the driver owns the write door.
+ *
+ * @param {{config: string|null}} options This run's parsed flags.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `captureDelta`'s result (`snapshot`, `text`),
+ *   unmodified.
+ */
+export async function captureBaseline(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // The snapshot's policy fingerprint needs the boundary config — the
+  // workspace's own `boundaryConfig` (profile-aware the same way `check` is,
+  // `resolvePolicy`), so the stored fingerprint agrees with a standalone
+  // `graph` fingerprint over the same workspace, kept in one place so a
+  // capture and a `graph` never disagree about the current policy.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  return captureDelta(commandContext, { config });
+}
+
+/**
+ * `delta` (compare) as the CLI drives it: the baseline path resolved from
+ * the single positional argument, then the shared preamble — command
+ * context, boundary law — so `../../cli.mjs`'s driver only wires options,
+ * IO seams, and where output lands. The engine this returns from is
+ * `deltaCommand` above, unchanged.
+ *
+ * @param {{config: string|null, eventOut: string|null, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the baseline file.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `deltaCommand`'s result, unmodified.
+ */
+export async function delta(options, { cwd, readGraph, listFiles }) {
+  const baselinePath = isAbsolute(options.paths[0])
+    ? resolve(options.paths[0])
+    : resolve(cwd, options.paths[0]);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // Same loading logic as `check` (`resolvePolicy`) — a `--config`
+  // overrides the workspace's own `boundaryConfig`, profile-aware the same
+  // way `check` is.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  return deltaCommand(baselinePath, commandContext, {
+    config,
+    eventOut: options.eventOut,
+  });
+}

package/src/commands/diff.mjs

@@ -42,12 +42,15 @@ import { readFileSync } from "node:fs";
 
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { computeRuleImpact } from "../rules/edge-constraints.mjs";
+import { isAbsolute, resolve } from "node:path";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 
 /**
  * Reads and validates a baseline snapshot from `path`.
@@ -236,6 +239,20 @@ function buildHeadSnapshot(commandContext) {
  * consumer wants to see: it is a real architectural event, not an
  * implementation detail.
  *
+ * This key is in-memory arithmetic and nothing else: `Map`/`Set` keys inside
+ * one run, never persisted and never emitted — only counts derived from
+ * those sets reach an envelope. The STORED spelling of edge identity is
+ * `edgeEvolutionIdentity` (`../governance/evolution-event.mjs`), the escaped
+ * `source>target:type` string evolution events carry, and the two spellings
+ * are deliberately not unified — each medium keeps exactly one identity
+ * constructor (`../../../../docs/adr/0008-snapshot-identity-per-family.md`;
+ * INV-6 in `../../../../docs/architecture/refactor/INVARIANTS.md`). An edge
+ * crosses from a structural diff into an event as its raw
+ * `{source, target, type}` triple, mapped through that function at the
+ * command boundary; a `\0`-joined key written into an event record would
+ * give one edge two spellings inside the store, and anything comparing
+ * identity strings across events would read them as different boundaries.
+ *
  * @param {{source: string, target: string, type: string}} edge
  * @returns {string}
  */
@@ -475,16 +492,10 @@ export function diffCommand(
   }
 
   if (meta.dirtyBaseline) {
-    coverage.notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    coverage.notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    coverage.notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    coverage.notes.push(dirtyHeadNote());
   }
 
   if (meta.policyChanged === true) {
@@ -564,3 +575,31 @@ export function diffCommand(
     },
   };
 }
+
+/**
+ * `diff` as the CLI drives it: the baseline path resolved from the single
+ * positional argument, then the shared preamble — command context, boundary
+ * law — so `../../cli.mjs`'s driver only wires options, IO seams, and where
+ * output lands (`./README.md`). The engine this returns from is
+ * `diffCommand` above, unchanged.
+ *
+ * @param {{format: string, output: string|null, config: string|null, paths: string[]}} options
+ *   This run's parsed flags; `paths[0]` is the baseline file.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `diffCommand`'s result, unmodified.
+ */
+export async function diff(options, { cwd, readGraph, listFiles }) {
+  const baselinePath = isAbsolute(options.paths[0])
+    ? options.paths[0]
+    : resolve(cwd, options.paths[0]);
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  // Load the boundary config when --config is given or when the workspace
+  // declares one, so rule-impact analysis is computed. Without a config,
+  // the diff reports only structural changes — same as before. A
+  // profile-selected workspace resolves the same way `check` does
+  // (`resolvePolicy`), so a policy edit under an unchanged profile NAME is
+  // still visible as a fingerprint change here.
+  const { config } = await resolvePolicy(options, commandContext, cwd);
+  return diffCommand(baselinePath, commandContext, { config });
+}

package/src/commands/discover.mjs

@@ -122,6 +122,43 @@ export function proposalToIntent(proposal) {
   };
 }
 
+/**
+ * Serialize a proposal into the exact bytes `--write-intent` plants at the
+ * target path — `proposalToIntent` rendered as stable, two-space JSON with a
+ * trailing newline, so the file a human reviews as a diff is the file
+ * `check` would read. Owned here, beside the conversion it renders, so the
+ * CLI's write door can never re-derive a second spelling of it.
+ *
+ * @param {object} proposal The proposal from `discoverCommand`'s result.
+ * @returns {string} The serialized intent document.
+ */
+export function intentJsonFromProposal(proposal) {
+  return JSON.stringify(proposalToIntent(proposal), null, 2) + "\n";
+}
+
+/**
+ * The `--write-intent` self-footgun refusal, decided beside the proposal it
+ * protects. A proposal is a suggestion; a file already at the target is a law
+ * (or a candidate someone holds), and silently overwriting it with a proposal
+ * is the adoption this command must never perform by itself — the same
+ * posture `--output`'s fixed-name table holds at the write door, specialized
+ * to the one target `discover` itself names. The CLI keeps the mechanics
+ * (the `wx` write, the stderr wording around it); the DECISION to refuse
+ * travels with the verb, the way `historyOutputRefusal` does for history.
+ *
+ * @param {string} target The `--write-intent` path as the user wrote it.
+ * @param {{exists: (path: string) => boolean}} io Injectable existence read —
+ *   the same seam style `loadNativeModel`'s `{readFile}` keeps.
+ * @returns {string|null} The refusal message, or `null` when the write may
+ *   proceed.
+ */
+export function intentWriteRefusal(target, { exists }) {
+  return exists(target)
+    ? `archkeep: ${target} already exists, and a proposal must never ` +
+        `silently replace what is there. Move or delete the file first, then run this again.`
+    : null;
+}
+
 /**
  * Runs the `discover` command: observes the workspace, optionally proposes the
  * candidate architecture over it, and returns the report.

package/src/commands/drift.mjs

@@ -77,6 +77,8 @@
  * intent produce byte-identical text and JSON.
  */
 import { blindSpotRows } from "../analysis/source-util.mjs";
+import { resolveCommandContext } from "./context.mjs";
+import { resolvePolicy } from "./policy.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
@@ -471,3 +473,46 @@ export async function driftCommand(commandContext, io = {}) {
     },
   };
 }
+
+/**
+ * `drift` as the CLI drives it: the shared preamble — command context, then
+ * the boundary law — resolved here so `../../cli.mjs`'s driver only wires
+ * options, IO seams, and where output lands (`./README.md`). The engine this
+ * returns from is `driftCommand` above, unchanged.
+ *
+ * The loaded policy — profile-aware the same way `check` is
+ * (`resolvePolicy`), `null` when the workspace declares none. Drift reads
+ * the intent's rows, and the fitness half of a row's `decisionRef` resolves
+ * against the ids THIS policy declares (F04), so the same policy that made
+ * the boundary law answerable to the model must answer here. `drift` has no
+ * `--config` (`DRIFT_FLAG_HELP`), so `config` is always the workspace's own
+ * default — resolvePolicy reads `options.config` as the override, hence
+ * `null` here, which selects the workspace's configured boundary law (or a
+ * profile, when one is registered).
+ *
+ * The failure is DEFERRED rather than thrown here. `drift`'s only reader of
+ * this policy is the non-verdict decisionRef axis, and only for rows that
+ * carry one, so a workspace with an intent and no boundary config was
+ * exiting 3 over a law drift would never have opened — a fifth refusal
+ * neither `docs/usage/drift.md` nor `reconcile`, which makes the same four,
+ * ever had. `driftCommand` rethrows it, unchanged, at the one site that
+ * reads the policy, so every workspace whose intent cites anything keeps the
+ * exact exit-3 it had.
+ *
+ * @param {{format: string, output: string|null, paths: string[]}} options
+ *   This run's parsed flags.
+ * @param {{cwd: string, readGraph?: Function, listFiles?: Function}} io The
+ *   seams a test injects, the same ones `check` takes.
+ * @returns {Promise<object>} `driftCommand`'s result, unmodified.
+ */
+export async function drift(options, { cwd, readGraph, listFiles }) {
+  const commandContext = resolveCommandContext({ cwd }, { readGraph, listFiles });
+  let config = null;
+  let configError = null;
+  try {
+    ({ config } = await resolvePolicy({ ...options, config: null }, commandContext, cwd));
+  } catch (error) {
+    configError = /** @type {Error} */ (error);
+  }
+  return driftCommand(commandContext, { config, configError });
+}