@ecoma-io/archkeep 0.24.1 → 0.26.0

package/src/governance/provenance-record.mjs

@@ -37,17 +37,8 @@
  * or a polluted prototype cannot smuggle keys into a validated origin. This
  * module builds nothing from untrusted keys; it validates and, at write time,
  * builds a fresh object with only the three permitted keys.
- * ## The decision-lifecycle record
- *
- * The same discipline extends from a row to a DECISION (an ADR id — the
- * stable handle later waves reference). `recordDecisionLifecycle` records one
- * lifecycle event — a status transition, a supersession, or a bindings
- * change — attributed by the same `origin` shape and the same clock door:
- * `by`/`tool` are required, and `on` comes from `recordOrigin` and nowhere
- * else. A record that records nothing (a no-op transition) is refused loudly.
  */
 
-import { ADR_STATUSES } from "./adr-registry.mjs";
 import { clockViolations } from "./clock.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 
@@ -175,146 +166,3 @@ export function recordOrigin({ by, tool, clock }) {
   // record, so two calls with the same clock are byte-identical.
   return { by, tool, on: clock.now() };
 }
-/**
- * The decision-lifecycle events one record can hold, each a single fact about
- * ONE decision (an ADR id — `docs/adr/NNN-slug.md` — the stable handle the
- * registry's `byId` map keys on). A decision's creation and every status
- * change, supersession, and bindings change is recorded as one of these.
- */
-export const DECISION_LIFECYCLE_KINDS = Object.freeze([
-  // used by its own test
-  "status-transition",
-  "supersession",
-  "bindings-change",
-]);
-
-/**
- * @typedef {object} DecisionLifecycleRecord
- * @property {"status-transition"|"supersession"|"bindings-change"} kind
- *   One recorded lifecycle event on one decision.
- * @property {string} decisionId The ADR id the event happened to — the stable
- *   handle the ADR registry keys on (`docs/adr/NNN-slug.md`).
- * @property {string|null} [from] status-transition: the status the decision
- *   left, or null when the event is the decision's creation (its proposed
- *   entry).
- * @property {string} [to] status-transition: the status the decision entered.
- * @property {string[]} [superseded] supersession: the ADR id(s) this decision
- *   replaced — `decisionId` is the RECORDING record, the successor.
- * @property {string[]} [added] bindings-change: constraint ids made
- *   enforceable.
- * @property {string[]} [removed] bindings-change: constraint ids unbound.
- * @property {OriginRecord} origin WHO recorded the event and with what tool —
- *   `on` produced by `recordOrigin`, the only door.
- */
-
-/**
- * Records one decision-lifecycle event, attributed by the same `origin`
- * discipline as a row: `by` and `tool` are required, and `on` comes from the
- * injected clock through `recordOrigin` — the only producer of an `on`, and
- * the refusal to run without one is its own, inherited here.
- *
- * The record carries ONLY the kind's own keys and the origin, built fresh, so
- * nothing from untrusted input rides along. A no-op event — a status
- * transition that changes nothing, a supersession naming no target, a
- * bindings change that adds and removes nothing — is refused loudly: a record
- * that records nothing would read as a transition that happened, the silent
- * direction this module exists to exclude.
- *
- * Statuses are validated against `ADR_STATUSES` (`./adr-registry.mjs`), the
- * single status vocabulary — a record can never attest a status the registry
- * could not hold.
- *
- * @param {{kind: "status-transition"|"supersession"|"bindings-change",
- *   decisionId: string,
- *   from?: string|null, to?: string,
- *   superseded?: string[],
- *   added?: string[], removed?: string[],
- *   origin: {by: string, tool: string},
- *   clock: import("./clock.mjs").Clock}} event
- * @returns {DecisionLifecycleRecord}
- * @throws {Error} on an unknown kind, a missing decisionId, a status outside
- *   the registry's `ADR_STATUSES`, a no-op event, or an invalid origin/clock.
- */
-export function recordDecisionLifecycle({
-  // used by its own test
-  kind,
-  decisionId,
-  from = null,
-  to,
-  superseded,
-  added,
-  removed,
-  origin,
-  clock,
-}) {
-  const violations = [];
-  if (!DECISION_LIFECYCLE_KINDS.includes(kind)) {
-    violations.push(
-      `kind: must be one of ${DECISION_LIFECYCLE_KINDS.join(", ")}, got ${describe(kind)}`,
-    );
-  }
-  if (typeof decisionId !== "string" || decisionId.trim() === "") {
-    violations.push(
-      `decisionId: must be a non-empty string naming the ADR, got ${describe(decisionId)}`,
-    );
-  }
-  if (kind === "status-transition") {
-    if (from !== null && !ADR_STATUSES.includes(from)) {
-      violations.push(
-        `from: must be null or one of ${ADR_STATUSES.join(", ")}, got ${describe(from)}`,
-      );
-    }
-    if (!ADR_STATUSES.includes(to)) {
-      violations.push(`to: must be one of ${ADR_STATUSES.join(", ")}, got ${describe(to)}`);
-    }
-    if (from !== null && from === to) {
-      violations.push(
-        `to: equals from (${JSON.stringify(from)}) — a status transition that changes nothing is not a recordable event`,
-      );
-    }
-  } else if (kind === "supersession") {
-    if (
-      !Array.isArray(superseded) ||
-      superseded.length === 0 ||
-      superseded.some((ref) => typeof ref !== "string" || ref.trim() === "")
-    ) {
-      violations.push("superseded: must be a non-empty array of ADR ids this decision replaced");
-    }
-  } else if (kind === "bindings-change") {
-    for (const [name, value] of [
-      ["added", added],
-      ["removed", removed],
-    ]) {
-      if (value !== undefined && !Array.isArray(value)) {
-        violations.push(`${name}: must be an array of constraint ids, got ${describe(value)}`);
-      } else if (
-        Array.isArray(value) &&
-        value.some((id) => typeof id !== "string" || id.trim() === "")
-      ) {
-        violations.push(`${name}: every entry must be a non-empty constraint id`);
-      }
-    }
-    const addedList = Array.isArray(added) ? added : [];
-    const removedList = Array.isArray(removed) ? removed : [];
-    if (addedList.length === 0 && removedList.length === 0) {
-      violations.push(
-        "added/removed: a bindings change that adds nothing and removes nothing is not a recordable event",
-      );
-    }
-  }
-  if (violations.length > 0) {
-    throw new Error(`decisionLifecycle: ${violations.join("; ")}`);
-  }
-  const eventFields =
-    kind === "status-transition"
-      ? { from, to }
-      : kind === "supersession"
-        ? { superseded }
-        : { added: added ?? [], removed: removed ?? [] };
-  return {
-    kind,
-    decisionId,
-    ...eventFields,
-    origin: recordOrigin({ by: origin?.by, tool: origin?.tool, clock }),
-  };
-}

package/src/governance/verdict.mjs

@@ -13,9 +13,17 @@
  *   `"findings"`   → `"fail"`
  *   `"no-verdict"` → `"unknown"`
  *
- * and `"not_applicable"` has no source status in this release — it is the
- * vocabulary for Fitness functions and Waivers (a follow-up capability),
- * never for engine behavior today.
+ * and `"not_applicable"` has no source status in this release — no envelope
+ * status maps to it, so it never rides an envelope. Engine behavior does emit
+ * it today, on the paths that cannot judge: the fitness registry answers it
+ * for a declared function whose `match` selects no observed project, and
+ * again for `coverage-minimum` on a path-scoped run, which no scoped run can
+ * judge; decision fitness derives it for a decision without authority; the
+ * boundary metrics answer it when there is no boundary config to judge
+ * against (`./metrics.mjs`). A
+ * custom rule may return it as its own verdict — the host requires a
+ * `notApplicableReason` (`../custom-rules/host.mjs`) — but no engine path
+ * answers it on a rule's behalf.
  *
  * ## The invariants, I1–I5
  *
@@ -41,8 +49,25 @@
  * (`../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.
+ *
+ * Layer: the verdict vocabulary and decision owner — `VERDICTS`, `isVerdict`,
+ * `verdictForStatus`, `fitnessVerdict`, and `buildDecision`. Its counterpart,
+ * `../verdict.mjs`, is the check lane built on top of `buildDecision` — the
+ * process's exit codes, the coverage clauses, and `verdictFor`, the per-lint
+ * verdict the `check` command words its envelope and its exit from. The two
+ * near-collision pairs cross that boundary, and the name decides which file
+ * a reader wants: `verdictForStatus` here looks one status up in a frozen
+ * map, while `../verdict.mjs`'s `verdictFor` folds a run's counts into
+ * status + exitCode; `VERDICT_FOR_STATUS` here is an independently frozen
+ * map, while `../verdict.mjs`'s `EXIT_FOR_STATUS` is derived from its own
+ * `EXIT`. Verdict vocabulary and decision construction live here; exit-code,
+ * coverage and check-lane concerns live there — and the layering stays
+ * one-directional (the check lane imports this module, never the reverse),
+ * so this module must not grow exit-code or coverage concerns.
  */
 
+import { describe, isNonEmptyString } from "../values.mjs";
+
 /** The four canonical verdict values. */
 export const VERDICTS = Object.freeze(["pass", "fail", "unknown", "not_applicable"]);
 
@@ -113,7 +138,7 @@ export function fitnessVerdict({ verdict, name, evidence, message, rows, notAppl
         `expected one of ${VERDICTS.join(", ")}.`,
     );
   }
-  if (verdict === "not_applicable" && notApplicableReason === undefined) {
+  if (verdict === "not_applicable" && !isNonEmptyString(notApplicableReason)) {
     throw new Error(
       `archkeep: fitness function "${name}" returned "not_applicable" without ` +
         `notApplicableReason — invariant I4: the reader must be told why the ` +
@@ -206,6 +231,21 @@ export function buildDecision(run) {
     throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
   }
   const verdict = run.verdict ?? verdictForStatus(run.status);
+  // The vocabulary latch. `verdictForStatus` cannot produce a stranger, so
+  // this refuses exactly the explicitly-passed verdicts — and it must run
+  // BEFORE the status-conflict check below, so a malformed verdict reports
+  // the vocabulary it violated rather than a conflict it never had. Without
+  // this latch, "perhaps", "PASS", `42` and `{}` fell through the
+  // pass/fail/unknown arms into the not_applicable one and SHIPPED whenever
+  // `notApplicableReason` happened to be truthy — a byte-legal decision
+  // about a workspace nobody judged.
+  if (!isVerdict(verdict)) {
+    throw new Error(
+      `archkeep: refusing to build a decision with verdict ${describe(run.verdict)} — ` +
+        `expected one of ${VERDICTS.join(", ")}. This is a bug in the command that ` +
+        `built the decision.`,
+    );
+  }
   if (
     run.verdict !== undefined &&
     run.status !== undefined &&
@@ -260,17 +300,32 @@ export function buildDecision(run) {
   }
 
   if (verdict === "unknown") {
+    // An absent reason (undefined/null) still defaults to the generic one —
+    // absence is not emptiness. A SUPPLIED reason must actually say
+    // something: "" and "   " are byte-present but semantically absent, and
+    // a non-string reason would ship a `typeof` artifact where the reader
+    // was promised a sentence (I3).
     const reason =
       run.reason ??
       (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
+    if (!isNonEmptyString(reason)) {
+      throw new Error(
+        `archkeep: refusing to emit an "unknown" decision with a ${describe(run.reason)} reason — ` +
+          `I3 requires a non-empty reason naming why no verdict was reached. ` +
+          `This is a bug in the command that built the decision.`,
+      );
+    }
     return withSampleTime({ verdict, reason }, run.sampleTime);
   }
 
-  // verdict === "not_applicable" (I4).
-  if (!run.notApplicableReason) {
+  // verdict === "not_applicable" (I4). The reason must be a string a reader
+  // could act on — the falsy check this replaces refused "" but SHIPPED
+  // "   " and non-strings, the same byte-present-semantically-absent hole.
+  if (!isNonEmptyString(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. ` +
+        `"did not apply" and "did not run" must never be indistinguishable, and a reason of ` +
+        `${describe(run.notApplicableReason)} tells the reader nothing. ` +
         `This is a bug in the command that built the decision.`,
     );
   }

package/src/intent/intent-manifest.json

@@ -25,7 +25,7 @@
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
-          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
+          "assertion": "commands/context.mjs imports providers — the designated orchestration path",
           "sha256": "b505e3a7476c64af4b2daeb106e2f9cb05be82e314604229d508dda04b629a98"
         }
       ],
@@ -40,7 +40,7 @@
           "type": "behavioral-test",
           "path": "src/report/json.test.mjs",
           "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement",
-          "sha256": "a371d36b89b10c5a4bda4d9e9a2e3bde114256c1377eb95699c9f0f195aabc4a"
+          "sha256": "8f587d3bd3f06519b90f760e7eafc091ca4e4cf26b67929ab180abe35c36c8f0"
         },
         {
           "type": "source-evidence",
@@ -52,7 +52,7 @@
           "type": "source-evidence",
           "path": "cli.mjs",
           "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look",
-          "sha256": "81abe8243660b3cca913ee903c1fc0bfcdb6a240640c5302f18848e6a9473fe6"
+          "sha256": "2b6590f4039464d3569727d0a73db61dd86c18648a519ee034ebcc2d845ecfc7"
         }
       ],
       "status": "proven"
@@ -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": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "749414363ef9991ae3697fc00ab5969751666867792d4bb4dbe528ec47ccd740"
         },
         {
           "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": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "749414363ef9991ae3697fc00ab5969751666867792d4bb4dbe528ec47ccd740"
         },
         {
           "type": "source-evidence",
@@ -84,7 +84,7 @@
           "type": "source-evidence",
           "path": "AGENTS.md",
           "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges",
-          "sha256": "3209154935cc1463127721203da74dc8bf8ba40258b182c5faa7345946611e38"
+          "sha256": "552b54c1956370f024ffeecec95c0e0941a0c66d4a14094045b444a25a27f913"
         }
       ],
       "status": "proven"
@@ -103,14 +103,20 @@
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
-          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
+          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped",
+          "sha256": "4f493421e11b012ce7b9c1b111155c8ebdbca6ab4ad3fa37221fbe1a465bef46"
+        },
+        {
+          "type": "source-evidence",
+          "path": "src/report/json.mjs",
+          "assertion": "SCHEMA_VERSION = 2 — the envelope's schemaVersion constant",
+          "sha256": "ac6db6e74b4ef7e54db12cc14ef57a7c5080ad081d7bf1273beb5ba543dcac24"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
-          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
+          "sha256": "4f493421e11b012ce7b9c1b111155c8ebdbca6ab4ad3fa37221fbe1a465bef46"
         }
       ],
       "status": "proven"
@@ -130,7 +136,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "4d44eea475cd4b06122a405718203d2e0018a163c1d42b17324400e7e4de5eea"
         }
       ],
       "status": "proven"
@@ -150,7 +156,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "4d44eea475cd4b06122a405718203d2e0018a163c1d42b17324400e7e4de5eea"
         }
       ],
       "status": "proven"
@@ -230,7 +236,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": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "749414363ef9991ae3697fc00ab5969751666867792d4bb4dbe528ec47ccd740"
         },
         {
           "type": "behavioral-test",
@@ -248,19 +254,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": "f906671ff4a5720d80ea5a3dab2779f1cfd3648fbc1e6a1f3a6d0e6efef21feb"
+          "sha256": "2d8a17dce1a5f4075ee02a7a8c1bdff94e70afe5cd609f63fe3cf6324f78aaf3"
         },
         {
           "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": "152a53a0010d8cbd51d11e3ce6268fa50d1e2bcacab3d7bcb38dbd53fc120bbf"
+          "sha256": "440f20017cceae4b13c6bc5c653c7a8b99511e0c062dcc7abfb18859f3f0520c"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "4d44eea475cd4b06122a405718203d2e0018a163c1d42b17324400e7e4de5eea"
         },
         {
           "type": "documentation",
@@ -286,7 +292,7 @@
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
           "assertion": "Plain string comparison throughout; never localeCompare",
-          "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
+          "sha256": "4f493421e11b012ce7b9c1b111155c8ebdbca6ab4ad3fa37221fbe1a465bef46"
         }
       ],
       "status": "proven"

package/src/lsp/server.mjs

@@ -60,12 +60,8 @@ import {
   TEXT_DOCUMENT_SYNC_KIND,
   uriToPath,
 } from "./protocol.mjs";
-import {
-  buildWorkspaceIndex,
-  listWorkspaceFiles,
-  PROJECT_CONFIG_FILE,
-  readWorkspaceFile,
-} from "./workspace-index.mjs";
+import { PROJECT_CONFIG_FILE } from "../providers/native/discover.mjs";
+import { buildWorkspaceIndex, listWorkspaceFiles, readWorkspaceFile } from "./workspace-index.mjs";
 
 /**
  * A project's own `package.json`, and the two spellings of its Module
@@ -232,8 +228,9 @@ const POLYGLOT_GRAPH_MANIFESTS = Object.freeze([
  * the annotations cached against the old one. The stale waiver then publishes
  * `[]` for a real violation for the rest of the session, which is the silent
  * direction exactly (`../../../../AGENTS.md`). `package.json` earns the entry a
- * second way as well: it is where `./workspace-index.mjs`'s `discoverProjects`
- * takes a project's NAME when its `project.json` states none, so an edit to it
+ * second way as well: it is where the static acquisition
+ * (`../providers/nx-static.mjs`'s `discoverProjects`) takes a project's NAME
+ * when its `project.json` states none, so an edit to it
  * can move a project in the graph and not only waive something in it.
  *
  * The polyglot graph manifests are here for that same argument one level out,