@ecoma-io/archkeep 0.22.2 → 0.24.0

package/src/governance/profile-registry.mjs

@@ -61,6 +61,7 @@
 import { readFileSync } from "node:fs";
 
 import { policyFrom } from "../config.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 
 /**
  * The top-level keys a profiles file may carry. `version` is checked AFTER
@@ -109,16 +110,6 @@ const BLOCK_KEYS = ["depConstraints", "moduleBoundaryOptions", "boundarySuppress
  */
 const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/u;
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /** A profile's declared block, kept ONLY for this command's own data. */
 export function listNames(registry) {
   return registry.profiles.map((profile) => profile.name);
@@ -304,23 +295,13 @@ export function resolveProfile(profiles, name, seen = new Set()) {
  * @param {string} path Absolute path of the profiles file.
  * @param {{readFile?: (path: string) => string|null}} [io] Injectable read,
  *   the same seam `../../options.mjs`'s readers take; answers `null` when the
- *   file is not there.
+ *   file is not there. Defaults to `defaultProfileIo.readFile` — the sync
+ *   `node:fs` read this module makes, the only place it touches the disk.
  * @returns {{profiles: object[]}}
  * @throws {Error} on a missing/unreadable/unparseable file, or on any
  *   profile-registry or reference-graph defect.
  */
-export function loadProfileRegistry(
-  path,
-  {
-    readFile = (p) => {
-      try {
-        return readFileSync(p, "utf8");
-      } catch {
-        return null;
-      }
-    },
-  } = {},
-) {
+export function loadProfileRegistry(path, { readFile = defaultProfileIo.readFile } = {}) {
   const text = readFile(path);
   if (text === null) {
     throw new Error(`archkeep: cannot read profiles file ${path}`);
@@ -363,3 +344,19 @@ export function profilePolicy(registryPath, profileName, sourceLabel, io = {}) {
   const effective = resolveProfile(registry.profiles, profileName);
   return policyFrom(effective, `${sourceLabel} (profile "${profileName}")`);
 }
+
+/**
+ * The default io: the sync `node:fs` read `loadProfileRegistry` makes, wrapped
+ * in the null-on-missing contract `../../options.mjs`'s readers share. This is
+ * the only place in this module the filesystem is named directly — a test
+ * injects a `readFile` and the module body never touches the disk on its own.
+ */
+const defaultProfileIo = Object.freeze({
+  readFile: (p) => {
+    try {
+      return readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
+});

package/src/governance/provenance-record.mjs

@@ -49,6 +49,7 @@
 
 import { ADR_STATUSES } from "./adr-registry.mjs";
 import { clockViolations } from "./clock.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 
 /** The only keys a validated `origin` may carry. */
 export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]);
@@ -63,17 +64,6 @@ export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]);
  *   `recordOrigin` produced it through the shared clock.
  */
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /**
  * Everything wrong with a raw `origin` record at READ time, as messages; empty
  * when it is well-formed. Shape only — an `on` committed in a declaration file

package/src/governance/reconcile-score.mjs

@@ -76,9 +76,6 @@ export const SEVERITY_ORDER = Object.freeze({
   unknown: Infinity,
 });
 
-/** A scored element's state, in the vocabulary the text and JSON reports share. */
-export const ELEMENT_STATES = Object.freeze(["match", "absent", "unexpected", "unknown"]);
-
 /**
  * A scored element.
  *

package/src/governance/row-schema.mjs

@@ -57,9 +57,7 @@
  */
 
 import { originViolations } from "./provenance-record.mjs";
-
-/** The shape of any `origin.on` producer. Re-exported for a row owner's own docs. */
-export { clockViolations as clockValidation } from "./clock.mjs";
+import { describe, isPlainObject } from "../values.mjs";
 
 /** The four governance keys a row may carry, in the order reports list them. */
 export const GOVERNANCE_ROW_KEYS = Object.freeze([
@@ -85,17 +83,6 @@ export const GOVERNANCE_ROW_KEYS = Object.freeze([
  * @property {string[]} [fitnessBindings] Fitness ids this row is bound to.
  */
 
-/** @type {(value: unknown) => value is Record<string, unknown>} */
-const isPlainObject = (value) =>
-  value !== null && typeof value === "object" && !Array.isArray(value);
-
-/** A value's type, for an error message that shows what was actually there. */
-function describe(value) {
-  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
-  if (value === null) return "null";
-  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
-}
-
 /**
  * Everything wrong with a row's `rationale`, `decisionRef`, or
  * `fitnessBindings` — the three string-shaped governance keys. `origin` has

package/src/governance/verdict.mjs

@@ -34,10 +34,13 @@
  *     claim the vocabulary makes and the hardest to disprove, so every other
  *     state exists to refuse it.
  *
- * The enforcer that makes the invariants executable lives in
- * `../report/evidence.mjs` (`buildDecision`) — this module owns the closed
- * vocabulary and its relation to the envelope's existing statuses, and the
- * report module owns the runtime check a command's counts go through.
+ * The enforcer that makes the invariants executable is `buildDecision`, in
+ * this file, beside the vocabulary it enforces — a vocabulary and the check
+ * that a verdict's evidence agrees with it are one subject, and splitting
+ * them across the report boundary had made the core verdict module
+ * (`../verdict.mjs`) depend on the presentation layer. `../report/evidence.mjs`
+ * re-exports `buildDecision` so the render-side callers keep their import
+ * path — a path, never a second implementation.
  */
 
 /** The four canonical verdict values. */
@@ -125,3 +128,164 @@ export function fitnessVerdict({ verdict, name, evidence, message, rows, notAppl
     ...(notApplicableReason === undefined ? {} : { notApplicableReason }),
   };
 }
+
+/**
+ * The decision builder: turns a command's verdict counts into the `decision`
+ * the envelope optionally carries, enforcing the five invariants the module
+ * header states in code rather than leaving them to a docs page a later
+ * command author might not read.
+ *
+ * This function decides nothing about whether a finding IS one — the command
+ * that built the envelope owns that. What it decides is whether the verdict
+ * and its evidence AGREE, and it throws when they do not, the same posture
+ * `../report/json.mjs`'s `jsonEnvelope` takes for the three consistency rules
+ * it enforces: a mismatch here is a bug in the command, not a fact about the
+ * workspace.
+ *
+ * The shape it produces:
+ *
+ *   {
+ *     verdict: "pass" | "fail" | "unknown" | "not_applicable",
+ *     reason?: string,                // always present for unknown
+ *     notApplicableReason?: string,   // always present for not_applicable
+ *     sampleTime?: string             // opt-in, never on a deterministic envelope
+ *   }
+ *
+ * A caller may pass `reason` for `unknown` — it names WHICH could-not-look
+ * condition fired (coverage incomplete, an unresolved intent boundary, a
+ * thrown analysis). Without it, `buildDecision` states the generic one. The
+ * reason field itself is always present on an `unknown` decision (I3).
+ *
+ * ## Determinism is the default
+ *
+ * The envelope this decision rides on is byte-deterministic
+ * (`docs/reference/json-output.md`: no timestamp, no random identifier). So
+ * `sampleTime` is OPT-IN by construction: a command passes it explicitly when
+ * it is an age/count capability (waivers, debt, health — the features
+ * `./clock.mjs` serves), and a command whose verdict must stay reproducible
+ * over an unchanged tree emits a decision with no time at all. That is how
+ * the determinism↔time tension is resolved — the clock is injectable (a test
+ * drives the same code with a fixed time), never asserted from the wall
+ * clock.
+ *
+ * ## One refusal per invariant
+ *
+ * I1 refuses a `pass` over incomplete coverage — the same refusal
+ * `jsonEnvelope` makes for `status: "ok"` over incomplete coverage, at the
+ * verdict layer — and a `pass` carrying findings. I2 refuses a `fail` that
+ * names no finding. I3 keeps a reason on every `unknown`, defaulting the
+ * generic one when the caller supplies none. I4 refuses a `not_applicable`
+ * without its `notApplicableReason`. I5 is I1's first check plus every caller
+ * choosing `unknown` wherever the run did not reach a verdict.
+ *
+ * `not_applicable` has no envelope status, so `buildDecision` reaches it only
+ * through an explicit `verdict` — the route a Fitness or Waiver capability
+ * takes. Engine behavior today never passes it: `jsonEnvelope` refuses a
+ * `decision.verdict` that contradicts the envelope's `status`, and no status
+ * maps to `not_applicable`, so the state is locked out of every envelope this
+ * release builds.
+ *
+ * @param {{
+ *   verdict?: "pass"|"fail"|"unknown"|"not_applicable",
+ *   status?: "ok"|"findings"|"no-verdict",
+ *   coverageComplete: boolean,
+ *   findings: number,
+ *   reason?: string|null,
+ *   notApplicableReason?: string|null,
+ *   sampleTime?: string
+ * }} run
+ * @returns {{verdict: string, reason?: string, notApplicableReason?: string,
+ *   sampleTime?: string}}
+ * @throws {Error} on any invariant violation (I1–I4).
+ */
+export function buildDecision(run) {
+  if (run.verdict === undefined && run.status === undefined) {
+    // No status, no explicit verdict — a builder called with neither is a
+    // programming error, not a fact about the workspace.
+    throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
+  }
+  const verdict = run.verdict ?? verdictForStatus(run.status);
+  if (
+    run.verdict !== undefined &&
+    run.status !== undefined &&
+    run.verdict !== verdictForStatus(run.status)
+  ) {
+    throw new Error(
+      `archkeep: refusing to build a decision where verdict "${run.verdict}" contradicts status ` +
+        `"${run.status}" — status implies ${verdictForStatus(run.status)}, and a decision that ` +
+        `disagrees with its own status would make one of the two a lie. ` +
+        `This is a bug in the command that built the decision.`,
+    );
+  }
+
+  // The `findings` count is the cardinal evidence number — a non-negative
+  // integer that the I1–I5 invariants all rely on. A missing, non-numeric, or
+  // negative value would silently falsify every comparison (`undefined > 0` is
+  // `false`), producing a clean verdict over a run whose counts were never set
+  // or are logically impossible — the exact silent direction this module exists
+  // to refuse.
+  if (typeof run.findings !== "number" || !Number.isFinite(run.findings) || run.findings < 0) {
+    throw new Error(
+      `archkeep: refusing to build a decision where findings is ${JSON.stringify(run.findings)} ` +
+        `— findings must be a non-negative number, or the verdict invariants cannot be enforced. ` +
+        `This is a bug in the command that built the decision.`,
+    );
+  }
+  if (verdict === "pass") {
+    if (run.coverageComplete !== true) {
+      throw new Error(
+        `archkeep: refusing to emit a "pass" decision over incomplete coverage ` +
+          `(coverage.complete: ${run.coverageComplete}) — a run that could not fully read the ` +
+          `tree can never pass. This is a bug in the command that built the decision.`,
+      );
+    }
+    if (run.findings > 0) {
+      throw new Error(
+        `archkeep: refusing to emit a "pass" decision with ${run.findings} finding(s) — ` +
+          `"pass" and "fail" cannot both be true of the same run. This is a bug in the command.`,
+      );
+    }
+    return withSampleTime({ verdict }, run.sampleTime);
+  }
+
+  if (verdict === "fail") {
+    if (run.findings < 1) {
+      throw new Error(
+        `archkeep: refusing to emit a "fail" decision with no findings — a failing verdict ` +
+          `must name what failed. This is a bug in the command that built the decision.`,
+      );
+    }
+    return withSampleTime({ verdict }, run.sampleTime);
+  }
+
+  if (verdict === "unknown") {
+    const reason =
+      run.reason ??
+      (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
+    return withSampleTime({ verdict, reason }, run.sampleTime);
+  }
+
+  // verdict === "not_applicable" (I4).
+  if (!run.notApplicableReason) {
+    throw new Error(
+      `archkeep: refusing to emit a "not_applicable" decision without notApplicableReason — ` +
+        `"did not apply" and "did not run" must never be indistinguishable. ` +
+        `This is a bug in the command that built the decision.`,
+    );
+  }
+  return withSampleTime({ verdict, notApplicableReason: run.notApplicableReason }, run.sampleTime);
+}
+
+/**
+ * Adds `sampleTime` to the decision only when the caller opted into time —
+ * the determinism rule in `buildDecision`'s header. Absent `sampleTime`, the
+ * decision object carries exactly the invariant-bearing fields and nothing
+ * more.
+ *
+ * @param {object} decision
+ * @param {string|undefined} sampleTime
+ * @returns {object}
+ */
+function withSampleTime(decision, sampleTime) {
+  return sampleTime === undefined ? decision : { ...decision, sampleTime };
+}

package/src/intent/intent-manifest.json

@@ -20,13 +20,13 @@
           "type": "architecture-test",
           "path": "src/conformance/boundary.test.mjs",
           "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers",
-          "sha256": "12d4e179f88de2622a41e56f42b2bab1c88a677ec2232430752138c57ba5fb18"
+          "sha256": "e4e24ed9f36e31126249c7d079b3656d17ac78ee4f12033321467ffa6666f033"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
           "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
-          "sha256": "7f566c06afbb175337529bd9bdc42465f8849498b932abf6a77fe0290a0cd13c"
+          "sha256": "b505e3a7476c64af4b2daeb106e2f9cb05be82e314604229d508dda04b629a98"
         }
       ],
       "status": "proven"
@@ -46,7 +46,7 @@
           "type": "source-evidence",
           "path": "src/lsp/diagnose.mjs",
           "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places — plus a document whose only positioned failure is an external disclosure, which was judged and so is not published (#603)",
-          "sha256": "72196def14055475ccb23284a3c5d34167535a506985b26fb95af097545cc740"
+          "sha256": "0edeb309a9bba49f4e82d8bf82982363ae9a20bfc04421b208961854b84acd41"
         },
         {
           "type": "source-evidence",
@@ -66,13 +66,13 @@
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes (three workspaces differing only in project tag fields compared byte-for-byte)",
-          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
+          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
         },
         {
           "type": "architecture-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "the gate walks every production analysis module and fails when judging vocabulary (judge/forbid/permit/allow/ban) appears in code",
-          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
+          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
         },
         {
           "type": "source-evidence",
@@ -104,13 +104,13 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         }
       ],
       "status": "proven"
@@ -130,7 +130,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
-          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
+          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
         }
       ],
       "status": "proven"
@@ -150,7 +150,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
-          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
+          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
         }
       ],
       "status": "proven"
@@ -230,7 +230,7 @@
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
           "assertion": "depConstraints verdicts from judgeEdge agree with evaluate in both directions (violating edge found by both, legal edge reported by neither); explain includes the same violations as evaluate at a given site",
-          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
+          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
         },
         {
           "type": "behavioral-test",
@@ -248,19 +248,19 @@
           "type": "source-evidence",
           "path": "src/commands/context-command.mjs",
           "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
-          "sha256": "72526cdaf038da4d9a50b33ab3cb30828713e62bbb891f4e2e51e008a403338e"
+          "sha256": "f906671ff4a5720d80ea5a3dab2779f1cfd3648fbc1e6a1f3a6d0e6efef21feb"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/impact.mjs",
           "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
-          "sha256": "38cff166a8944860c51a73316447ce789898751489d783e75fd6befbfd30be3c"
+          "sha256": "152a53a0010d8cbd51d11e3ce6268fa50d1e2bcacab3d7bcb38dbd53fc120bbf"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
-          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
+          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
         },
         {
           "type": "documentation",
@@ -286,7 +286,7 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison throughout; never localeCompare",
-          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
+          "sha256": "72a28c1edcbcb209f74bd10a1a3691e25aaa848bac4bd54aceeacf8d415c8f13"
         }
       ],
       "status": "proven"
@@ -312,13 +312,13 @@
           "type": "source-evidence",
           "path": "src/providers/moon.mjs",
           "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native",
-          "sha256": "232dd8e2cbe70c9149ba3a75a03dcebe0db355894c280964ebbf6a5a536b5567"
+          "sha256": "2b874da56bda5bc6cfcfb4a984556ace0eafe3a6a98d964c78204bd96cc30e48"
         },
         {
           "type": "behavioral-test",
           "path": "src/providers/moon.test.mjs",
           "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout",
-          "sha256": "084a0061b3236e680274d837fb2f12d27dd4b5a379040157f7afe2be5088e8ac"
+          "sha256": "906fcd38b82af875aecca2910231ec5d5bb551e2a6e7d452f35a0670326c8756"
         }
       ],
       "status": "proven"

package/src/lsp/diagnose.mjs

@@ -43,7 +43,7 @@
  */
 import { analyzeFile } from "../analysis/analyze.mjs";
 import { isExternalSiteFailure, projectOwning } from "../analysis/source-util.mjs";
-import { declaredEdgeViolationsForCheck } from "../commands/edge-constraints.mjs";
+import { declaredEdgeViolationsForCheck } from "../rules/edge-constraints.mjs";
 import { evaluate } from "../rules/index.mjs";
 
 import {
@@ -170,7 +170,7 @@ export function diagnoseDocument({ sourceFile, text, index, config }) {
   // Nx/`archkeep.json` `implicitDependencies` declaration — has no import site
   // behind it, so it never becomes an `importSites` record for the rule engine
   // to iterate. The CLI judges exactly those edges itself
-  // (`../commands/edge-constraints.mjs`'s `declaredEdgeViolationsForCheck`,
+  // (`../rules/edge-constraints.mjs`'s `declaredEdgeViolationsForCheck`,
   // `cli.mjs check`), and without the same fold here the editor would paint a
   // file clean while `check` exits 1 over the same declared edge — the
   // boundary rule that never runs, dressed as a clean tree. Only the violations

package/src/lsp/server.mjs

@@ -393,7 +393,7 @@ export function readWorkspaceOptions(root) {
   // A Moon root, checked only once neither marker file is there: a `.moon`
   // beside `nx.json` keeps falling to `readPluginOptions` below exactly as it
   // did, and `./workspace-index.mjs`'s `buildWorkspaceIndex` refuses the pair
-  // loudly through the one shared gate (`../commands/context.mjs`'s
+  // loudly through the one shared gate (`../providers/model-gate.mjs`'s
   // `requireSingleProjectModel`) rather than this function growing a second
   // copy of that refusal. `moonMarkerAt` is the same dispatcher the index and
   // the CLI read, so all three agree about which directory marks the tree —

package/src/lsp/workspace-index.mjs

@@ -134,7 +134,7 @@ import {
 import { nodeTypeOf, PROJECT_CONFIG_FILE } from "../providers/native/discover.mjs";
 import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
 import { nativeProvider } from "../providers/native/index.mjs";
-import { requireSingleProjectModel } from "../commands/context.mjs";
+import { requireSingleProjectModel } from "../providers/model-gate.mjs";
 import { mergeImportEdges, moonProvider } from "../providers/moon.mjs";
 
 export { PROJECT_CONFIG_FILE, nodeTypeOf, buildDependencies };
@@ -337,7 +337,7 @@ export function buildNodes(projects) {
  *   no project has no boundary to cross — a clean report, produced by not
  *   looking. Also when the root carries more than one project-model marker —
  *   a Moon directory beside `nx.json`/`archkeep.json`, both Moon spellings at
- *   once, or `nx.json` beside `archkeep.json` (`../commands/context.mjs`'s
+ *   once, or `nx.json` beside `archkeep.json` (`../providers/model-gate.mjs`'s
  *   `requireSingleProjectModel`, the same refusal `check` makes) — which
  *   config governs at all is a decision nobody made, refused the same way an
  *   unreadable `nx.json` is, through this function's caller in `./server.mjs`.
@@ -354,7 +354,7 @@ export function buildWorkspaceIndex({
   const files = listFiles(root);
   const readFile = (path) => readFileAt(root, path);
   // Which provider may judge this root at all — the SAME gate
-  // (`../commands/context.mjs`'s `requireSingleProjectModel`) the CLI reads
+  // (`../providers/model-gate.mjs`'s `requireSingleProjectModel`) the CLI reads
   // before any command runs, so a tree carrying a Moon directory beside
   // `nx.json`/`archkeep.json` is refused here exactly as `check` refuses it,
   // in the same words, from the one copy of the rule. Before the shared

package/src/options.mjs

@@ -322,7 +322,7 @@ export function readPluginOptions(workspaceRoot, { readFile = readFileOrNull } =
  * `nx.json` → `plugins[].options.tsConfig` and a native root states it on
  * `archkeep.json`'s own `tsConfig` field; Moon's own configuration carries no
  * plugin-options table, and a `archkeep.json` beside `.moon/` is refused
- * outright (`./commands/context.mjs`'s `requireSingleProjectModel`), so every
+ * outright (`./providers/model-gate.mjs`'s `requireSingleProjectModel`), so every
  * door to a stated name is shut. What is left is convention, and one name is
  * not enough of it: measured on a 94-project Vue Moon workspace whose `paths`
  * table lives in `tsconfig.json` with no `tsconfig.base.json` beside it, a

package/src/providers/model-gate.mjs

@@ -0,0 +1,59 @@
+/**
+ * The one gate deciding whether a workspace root may be judged at all: which
+ * project model it declares, and a loud refusal when it declares more than
+ * one.
+ *
+ * Lives in the providers layer because the decision it makes is a
+ * provider-selection decision — `../commands/context.mjs` composes a provider
+ * behind it, and `../lsp/workspace-index.mjs` branches on the same facts
+ * before choosing one — and neither face may hold a second copy of the rule.
+ * A second copy was exactly how the faces drifted apart once: the CLI refused
+ * a tree carrying a Moon directory beside `nx.json`/`archkeep.json` while the
+ * editor indexed it anyway — a clean diagnostic list over a tree nobody agreed
+ * could be judged (#223's silent shape, one level up).
+ */
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { NX_CONFIG_FILE } from "../options.mjs";
+import { ARCHKEEP_MODEL_FILE } from "./native/model.mjs";
+import { moonMarkerAt } from "./moon.mjs";
+
+/**
+ * The one gate deciding whether `root` may be judged at all: more than ONE
+ * project-model marker present is refused, naming what conflicts.
+ *
+ * Every entry point that picks a provider must answer this identically —
+ * `../commands/context.mjs`'s `resolveCommandContext` reads it before any
+ * command runs, and `../lsp/workspace-index.mjs`'s index build reads it before
+ * choosing a branch. Moon-versus-Moon coexistence (`.moon/` AND
+ * `.config/moon/`) is refused inside `./moon.mjs`'s `moonMarkerAt`, which this
+ * gate calls first; the cross-family pairs are refused here, all in the same
+ * terms: which model to judge against is a decision nobody made, not one this
+ * tool can make for them.
+ *
+ * @param {string} root
+ * @param {{exists?: (path: string) => boolean}} [io] Injectable existence
+ *   test (absolute paths), so a test drives this without a filesystem.
+ * @returns {{hasNx: boolean, hasNative: boolean, moonMarker: string|null}}
+ *   The facts a provider choice needs; `moonMarker` names whichever Moon
+ *   directory is present, `null` when neither spelling is.
+ * @throws {Error} when more than one marker is present.
+ */
+export function requireSingleProjectModel(root, { exists = existsSync } = {}) {
+  const moonMarker = moonMarkerAt(root, { exists });
+  const hasNx = exists(join(root, NX_CONFIG_FILE));
+  const hasNative = exists(join(root, ARCHKEEP_MODEL_FILE));
+  const refusal = (a, b) =>
+    new Error(
+      `archkeep: ${root} declares both ${a} and ${b} — this tool judges a workspace ` +
+        `against exactly one project model, and a tree carrying both is a decision nobody made ` +
+        `rather than one this tool can make for them. Remove whichever one is not the ` +
+        `workspace's real source of truth for projects and tags.`,
+    );
+  if (moonMarker !== null && hasNx) throw refusal(moonMarker, NX_CONFIG_FILE);
+  if (moonMarker !== null && hasNative) throw refusal(moonMarker, ARCHKEEP_MODEL_FILE);
+  if (hasNx && hasNative) throw refusal(NX_CONFIG_FILE, ARCHKEEP_MODEL_FILE);
+  return { hasNx, hasNative, moonMarker };
+}

package/src/providers/moon.mjs

@@ -31,6 +31,7 @@ import { existsSync } from "node:fs";
 import { delimiter, join, posix } from "node:path";
 
 import { environmentForTree, runProcess } from "../process.mjs";
+import { isEnoent } from "../errors.mjs";
 import { buildDependencies } from "./native/graph.mjs";
 
 /**
@@ -249,7 +250,7 @@ function resolveMoonEnv(workspaceRoot, { env = process.env, platform = process.p
  * - **Archkeep** (from Nx's `implicitDependencies`, and `archkeep.json`'s own
  *   row of that name): `type: "implicit"` means *a human declared this edge
  *   and there is no import behind it*. That is precisely why
- *   `../commands/edge-constraints.mjs`'s `declaredEdgeViolationsForCheck`
+ *   `../rules/edge-constraints.mjs`'s `declaredEdgeViolationsForCheck`
  *   exists — such an edge never becomes an `importSites` record, so
  *   `evaluate()` structurally cannot reach it and `check` judges it as an edge
  *   instead. `../commands/drift.mjs` and `../commands/discover.mjs` exclude
@@ -905,16 +906,15 @@ function resolveMoonCli(workspaceRoot, { resolveMoon = () => "moon" } = {}) {
  * `nxCli` guards against from the other direction, where only a
  * `MODULE_NOT_FOUND` earns the "not installed" story.
  *
- * `../process.mjs`'s `runProcess` wraps the child's failure and carries the
- * original on `cause`, so the code is read from there; the direct `code` is
- * read too, for a `run` seam that surfaces a spawn error unwrapped.
+ * The shape test itself is `../errors.mjs`'s `isEnoent` — the name stays
+ * because what this file asks is not "is this ENOENT" but "does this failure
+ * carry an install action".
  *
  * @param {unknown} error
  * @returns {boolean}
  */
 function isMoonBinaryMissing(error) {
-  const thrown = /** @type {{code?: unknown, cause?: {code?: unknown}}|null|undefined} */ (error);
-  return thrown?.code === "ENOENT" || thrown?.cause?.code === "ENOENT";
+  return isEnoent(error);
 }
 
 /**