@ecoma-io/archkeep 0.20.1 → 0.22.0

package/cli.mjs

@@ -923,13 +923,20 @@ async function runDiff(options, { cwd, env }) {
     // the mechanism and the threat it closes.
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(`archkeep: diff complete → ${options.output}`);
+    // A refused run still writes the report — but "diff complete" would deny
+    // the refusal that report carries (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(`archkeep: diff complete → ${options.output}`);
+    }
   } else {
     env.out(report);
   }
 
-  // Diff is descriptive: 0 when it completes, never 1.
-  return EXIT.ok;
+  // Diff is descriptive: 0 when it completes, never 1 — and an incomplete
+  // head is the structured no-verdict envelope's exit 3, not a clean 0 (#608).
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -1003,19 +1010,31 @@ async function runDelta(options, { cwd, env }) {
     return usageError ? EXIT.usage : EXIT.error;
   }
 
+  // A coverage-refused compare (#608) answers every `--format` with the
+  // envelope: a withheld verdict has no findings, so there is no SARIF log
+  // and no text table to render — and `result.report.sarif` does not even
+  // exist on the refusal, which would crash the ternary below into a
+  // TypeError where the contract says exit 3.
   const report =
-    options.format === "json"
+    result.status === "no-verdict"
       ? result.report.json
-      : options.format === "sarif"
-        ? result.report.sarif
-        : result.report.text;
+      : options.format === "json"
+        ? result.report.json
+        : options.format === "sarif"
+          ? result.report.sarif
+          : result.report.text;
 
   if (options.output) {
     // Atomic, symlink-safe write — `writeOutputReport`'s own docstring owns
-    // the mechanism and the threat it closes.
+    // the mechanism and the threat it closes. A refused run still writes the
+    // report — but "delta complete" would deny the refusal it carries (#608).
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(`archkeep: delta complete → ${options.output}`);
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(`archkeep: delta complete → ${options.output}`);
+    }
   } else {
     env.out(report);
   }
@@ -1023,8 +1042,10 @@ async function runDelta(options, { cwd, env }) {
   // The event the run recorded, when `--event-out` was given — the store's
   // own `duplicate` answer, so a rerun over the same transition says so
   // instead of implying a second event was appended. Capture mode refuses the
-  // flag upstream; this line runs only for a compare.
-  if (result.eventWrite !== null) {
+  // flag upstream; this line runs only for a compare. Truthy, not `!== null`:
+  // a coverage-refused run (#608) returns no `eventWrite` key at all, and a
+  // truthiness test is the one form that reads both shapes safely.
+  if (result.eventWrite) {
     env.err(
       `archkeep: evolution event ${
         result.eventWrite.duplicate ? "duplicate, already recorded" : "recorded"
@@ -1105,16 +1126,24 @@ async function runDrift(options, { cwd, env }) {
     // `drift` has no `--config` flag (`DRIFT_FLAG_HELP`) — there is no
     // override to pass, only the workspace's un-overridden default to guard.
     if (!writeOutputReport(options.output, reportText, env, cwd, null)) return EXIT.error;
-    env.err(
-      `archkeep: ${result.drift.observed.projects} projects, ${result.drift.observed.edges} edges ` +
-        `→ ${options.output}`,
-    );
+    // A refused run carries no `drift` payload to summarize — the numbers
+    // would be `undefined` — so the stderr line names the refusal instead.
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: ${result.drift.observed.projects} projects, ${result.drift.observed.edges} edges ` +
+          `→ ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
 
-  // Drift is descriptive: 0 when the comparison completes, never 1.
-  return EXIT.ok;
+  // Drift is descriptive: 0 when the comparison completes, never 1 — and an
+  // incomplete analysis is the structured no-verdict envelope's exit 3
+  // (#608), not a clean 0.
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -1212,16 +1241,22 @@ async function runReconcile(options, { cwd, env }) {
     // `reconcile` has no `--config` flag (`RECONCILE_FLAG_HELP`) — there is no
     // override to pass, only the workspace's un-overridden default to guard.
     if (!writeOutputReport(options.output, reportText, env, cwd, null)) return EXIT.error;
-    env.err(
-      `archkeep: ${result.reconcile.observed.projects} projects, ${result.reconcile.observed.edges} edges ` +
-        `→ ${options.output}`,
-    );
+    // A refused run carries no `reconcile` payload to summarize (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: ${result.reconcile.observed.projects} projects, ${result.reconcile.observed.edges} edges ` +
+          `→ ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
 
-  // Reconcile is descriptive: 0 when the comparison completes, never 1.
-  return EXIT.ok;
+  // Reconcile is descriptive: 0 when the comparison completes, never 1 — and
+  // an incomplete analysis is the no-verdict envelope's exit 3 (#608).
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -1320,12 +1355,18 @@ async function runChange(options, { cwd, env }) {
     // the mechanism and the threat it closes.
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(
-      `archkeep: change ${result.changeIntent.reconciliation.verdict} ` +
-        `(+${result.changeIntent.reconciliation.matched.length} matched, ` +
-        `!${result.changeIntent.reconciliation.unexpected.length} undeclared, ` +
-        `?${result.changeIntent.reconciliation.missingExpected.length} unfulfilled) → ${options.output}`,
-    );
+    // A coverage-refused run carries no `changeIntent` payload to summarize
+    // (#608) — the refusal's own clause list is in the written report.
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: change ${result.changeIntent.reconciliation.verdict} ` +
+          `(+${result.changeIntent.reconciliation.matched.length} matched, ` +
+          `!${result.changeIntent.reconciliation.unexpected.length} undeclared, ` +
+          `?${result.changeIntent.reconciliation.missingExpected.length} unfulfilled) → ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
@@ -1396,22 +1437,29 @@ async function runWaivers(options, { cwd, env }) {
     // only glances at this confirmation must not see "N waivers on the
     // table" and conclude that is the whole surface when a
     // `boundarySuppressions` row with no `expiresAt` is hiding something the
-    // file --output just wrote down.
-    const suppressionNote =
-      result.waivers.suppressions.length > 0
-        ? `, ${result.waivers.suppressions.length} permanent suppression` +
-          `${result.waivers.suppressions.length === 1 ? "" : "s"}`
-        : "";
-    env.err(
-      `archkeep: ${result.waivers.waivers.length} waivers${suppressionNote} on the table ` +
-        `→ ${options.output}`,
-    );
+    // file --output just wrote down. A coverage-refused run carries no
+    // `waivers` payload at all (#608) — the line names the refusal instead.
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      const suppressionNote =
+        result.waivers.suppressions.length > 0
+          ? `, ${result.waivers.suppressions.length} permanent suppression` +
+            `${result.waivers.suppressions.length === 1 ? "" : "s"}`
+          : "";
+      env.err(
+        `archkeep: ${result.waivers.waivers.length} waivers${suppressionNote} on the table ` +
+          `→ ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
 
-  // Waivers is descriptive: 0 when the surface could be read, never 1.
-  return EXIT.ok;
+  // Waivers is descriptive: 0 when the surface could be read, never 1 — and
+  // an incomplete analysis is the no-verdict envelope's exit 3 (#608), the
+  // same tree `check` refuses.
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -1469,11 +1517,16 @@ async function runFitness(options, { cwd, env }) {
     // the mechanism and the threat it closes.
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(
-      `archkeep: ${result.fitness.functions.length} fitness function` +
-        `${result.fitness.functions.length === 1 ? "" : "s"} judged (${result.fitness.verdict}) ` +
-        `→ ${options.output}`,
-    );
+    // A coverage-refused run carries no `fitness` payload to summarize (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: ${result.fitness.functions.length} fitness function` +
+          `${result.fitness.functions.length === 1 ? "" : "s"} judged (${result.fitness.verdict}) ` +
+          `→ ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
@@ -1535,18 +1588,24 @@ async function runImpact(options, { cwd, env }) {
     // the mechanism and the threat it closes.
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(
-      `archkeep: ${result.impact.dependents.length} project` +
-        `${result.impact.dependents.length === 1 ? "" : "s"}` +
-        `${result.impact.dependents.length === 1 ? " depends" : " depend"} on ${projectName} ` +
-        `→ ${options.output}`,
-    );
+    // A coverage-refused run carries no `impact` payload to summarize (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: ${result.impact.dependents.length} project` +
+          `${result.impact.dependents.length === 1 ? "" : "s"}` +
+          `${result.impact.dependents.length === 1 ? " depends" : " depend"} on ${projectName} ` +
+          `→ ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
 
-  // Impact is descriptive: 0 when it completes, never 1.
-  return EXIT.ok;
+  // Impact is descriptive: 0 when it completes, never 1 — and an incomplete
+  // analysis is the no-verdict envelope's exit 3 (#608).
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 /**
  * `scenario`'s `run`: resolves the command context, reads the scenario file,
@@ -1606,13 +1665,20 @@ async function runScenario(options, { cwd, env }) {
 
   if (options.output) {
     if (!writeOutputReport(options.output, report, env, cwd, options.config)) return EXIT.error;
-    env.err(`archkeep: scenario for "${projectName}" complete → ${options.output}`);
+    // A refused run still writes the report — but "complete" would deny the
+    // refusal that report carries (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(`archkeep: scenario for "${projectName}" complete → ${options.output}`);
+    }
   } else {
     env.out(report);
   }
 
-  // Scenario is descriptive: 0 when it completes, never 1.
-  return EXIT.ok;
+  // Scenario is descriptive: 0 when it completes, never 1 — and an incomplete
+  // analysis is the no-verdict envelope's exit 3 (#608).
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -2259,16 +2325,22 @@ async function runDebt(options, { cwd, env }) {
     // the mechanism and the threat it closes.
     const reportText = report.endsWith("\n") ? report : `${report}\n`;
     if (!writeOutputReport(options.output, reportText, env, cwd, options.config)) return EXIT.error;
-    env.err(
-      `archkeep: ${result.ledger.total} debt entr` +
-        `${result.ledger.total === 1 ? "y" : "ies"} → ${options.output}`,
-    );
+    // A coverage-refused run carries no `ledger` payload to summarize (#608).
+    if (result.status === "no-verdict") {
+      env.err(`archkeep: no verdict — the coverage refusal is in the report → ${options.output}`);
+    } else {
+      env.err(
+        `archkeep: ${result.ledger.total} debt entr` +
+          `${result.ledger.total === 1 ? "y" : "ies"} → ${options.output}`,
+      );
+    }
   } else {
     env.out(report);
   }
 
-  // Debt is descriptive: 0 when the ledger completes, never 1.
-  return EXIT.ok;
+  // Debt is descriptive: 0 when the ledger completes, never 1 — and an
+  // incomplete analysis is the no-verdict envelope's exit 3 (#608).
+  return result.status === "ok" ? EXIT.ok : EXIT.error;
 }
 
 /**
@@ -2330,10 +2402,27 @@ async function runDiscover(options, { cwd, env }) {
   }
 
   if (options.writeIntent) {
+    // The one write that can turn a proposal into the law `check` gates on,
+    // so it refuses to replace: 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. Move or
+    // delete the file first — a step a human reviews.
+    if (existsSync(options.writeIntent)) {
+      env.err(
+        `archkeep: ${options.writeIntent} already exists, and a proposal must never ` +
+          `silently replace what is there. Move or delete the file first, then run this again.`,
+      );
+      return EXIT.error;
+    }
     try {
       const intentJson = JSON.stringify(proposalToIntent(result.proposal), null, 2) + "\n";
-      writeFileSync(options.writeIntent, intentJson, "utf-8");
+      // `wx` refuses the file materializing between the check above and this
+      // write, so the refusal above cannot be raced past.
+      writeFileSync(options.writeIntent, intentJson, { encoding: "utf-8", flag: "wx" });
       env.err(`archkeep: proposed architecture written to ${options.writeIntent}`);
+      env.err(
+        "archkeep: this file is a proposal, not the law — review it as a diff before it governs anything.",
+      );
     } catch (error) {
       env.err(`archkeep: failed to write intent file: ${error.message}`);
       return EXIT.error;
@@ -2799,8 +2888,9 @@ const DISCOVER_FLAG_HELP = Object.freeze([
     describe: Object.freeze([
       "Write the proposed components and rules to a valid",
       "architecture-intent.json file. Only valid with --propose;",
-      "the file is a candidate for drift/reconcile and must be",
-      "reviewed before use",
+      "refuses to overwrite a file that already exists — the file",
+      "is a candidate for drift/reconcile and must be reviewed",
+      "before use",
     ]),
   }),
   Object.freeze({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",

package/src/analysis/contract.md

@@ -160,16 +160,36 @@ which one it was:
 - A **literal package import that names no declared project** — an uninstalled
   third-party package, a dependency of some other workspace — is a normal,
   permanent state: a workspace with packages is not a missing workspace edge.
-  It stays a POSITIONED failure (`line`/`column` set), the "blind spot" that
-  does not fail the run.
+  It stays a POSITIONED failure (`line`/`column` set), the "blind spot", and
+  it carries `external: true`: the specifier asked the external dependency
+  universe, not the governed graph, and its resolvability is a property of
+  the installed dependency tree a workspace legitimately may not have (a
+  fresh clone, a trimmed install, the native self-check's `git archive`
+  copy). Disclosed, verdict-neutral — withholding over it would make a tree
+  permanently un-green over dependencies nobody crossed.
+- A **literal that references the workspace's own surface and still fails to
+  resolve** — a path-like specifier (`./`, `../`, `/`), a `#` subpath, a
+  `paths` alias — is the other positioned class, and the one that withholds
+  the run's verdict since the loud-coverage contract (#595): the resolver was
+  asked a concrete question about the governed graph and could not answer,
+  and #595's own reported shape (`#canary-review/index.mjs`, a subpath naming
+  a declared project) is exactly this class — `packageNameOf` keeps the `#`,
+  so the whole-file name test cannot catch it. `check` exits 3 over it
+  rather than reading as a pass.
 - A **dynamic import with a non-literal argument** — `import(somePath)`, or an
   `import()` whose argument is a template literal interpolating a variable — is
   the recurring permanent case. The site is real, the target is not knowable
   statically, and the honest answer is one record with `kind: "dynamic"`, the
   source text of the argument as `specifier`, and a POSITIONED failure
-  (`line`/`column` set). The rest of the file's imports were still judged; a
-  reader can see this one site in the report's blind-spot section and the run
-  does not fail on it.
+  (`line`/`column` set) carrying `dynamic: true`. The rest of the file's
+  imports were still judged; a reader can see this one site in the report's
+  blind-spot section. It does not withhold the verdict: a non-literal argument
+  is the language itself declaring the target computed at runtime, a limit
+  static analysis cannot close, so the run's pass claim covers the statically
+  judgeable surface. The `dynamic` field is what keeps the envelope builder
+  from reading this row as unjudged work (`report/json.mjs`'s completeness
+  law) — the permanent classes are disclosed alike and judged differently,
+  and the fields are the only things that tell them apart.
 
 Silently dropping any of them is how a boundary gets bypassed.
 
@@ -207,6 +227,13 @@ fails loudly rather than reporting an empty result that reads as "clean".
 
 `failures` carries `{ sourceFile, line, column, reason }`; `line`/`column` are
 `null` when the failure is about the file as a whole rather than one position.
+A positioned failure produced from a non-literal `import()`/`require()`
+argument additionally carries `dynamic: true`, and one produced from an
+unresolvable bare-package specifier carries `external: true` — the fields the
+verdict and envelope layers read to tell the declared dynamic limit and the
+external dependency universe apart from an unresolvable specifier that
+references the workspace's own surface, which is the class that withholds the
+verdict.
 Both arrays are always present and always arrays — a consumer never has to
 check for `undefined` before iterating.
 

package/src/analysis/source-util.mjs

@@ -351,6 +351,113 @@ export const refuseUnreadTree = (reader, failures) => {
  */
 export const isWholeFileFailure = (failure) => failure.line === null;
 
+/**
+ * Whether a positioned failure is the declared dynamic limit rather than an
+ * unresolvable specifier.
+ *
+ * Both are permanent blind spots — a site the run saw and could not judge —
+ * and both are disclosed identically (`coverage.blindSpots`, the report's
+ * blind-spot section). They part ways at the verdict: an unresolvable LITERAL
+ * specifier is a concrete question the resolver was asked and could not answer
+ * (#595 — a missing workspace edge at site granularity, an uninstalled
+ * dependency), so it withholds the run's verdict; a non-literal
+ * `import()`/`require()` argument is the language itself declaring the target
+ * computed at runtime, which static analysis cannot answer in principle —
+ * every config loader that opens a consumer-named file contains one — so it
+ * is a declared limit the run states and moves past. Measured on this
+ * repository's own tree: ten such sites in config loaders, unfixable without
+ * giving up the feature that makes them config loaders.
+ *
+ * The field is set only by the TypeScript/Vue analyzer, the one analyzer whose
+ * language has the construct; every other analyzer's positioned failures are
+ * literal specifiers by construction and never set it.
+ *
+ * @param {{ line: number|null, dynamic?: true }} failure
+ * @returns {boolean}
+ */
+export const isDynamicSiteFailure = (failure) => failure.dynamic === true;
+
+/**
+ * Whether a positioned failure is an unresolvable literal pointing at the
+ * EXTERNAL dependency universe — the bare-package class that neither withholds
+ * the verdict nor may.
+ *
+ * A bare specifier (`vitest`, `zod`, a scoped package) resolves against an
+ * installed dependency tree, and a workspace without that tree — a fresh
+ * clone, a trimmed install, the native self-check's `git archive` copy, which
+ * by design carries no `node_modules` — is a normal state. Withholding the
+ * verdict over it would make the tree permanently un-green over dependencies
+ * nobody crossed: measured, that is exactly what this repository's own
+ * required boundary gate did under the unqualified flip, 284 such rows on the
+ * native face alone. The marker rides the row (the TypeScript/Vue analyzer
+ * sets it; `isExternalUnresolvable` holds the class line there — path-like,
+ * `#` subpath and `paths`-alias specifiers never get it, so a workspace-edge
+ * question can never masquerade as external), and every verdict lane counts
+ * by its absence, the same mechanism the `dynamic` marker uses.
+ *
+ * Only the TypeScript/Vue analyzer sets the field today. The other analyzers'
+ * unresolvable literals keep withholding — including legitimately external
+ * coordinates (a JVM package coordinate naming an uninstalled library) —
+ * which is the over-loud direction and is tracked as its own issue rather
+ * than silently tolerated.
+ *
+ * @param {{ line: number|null, external?: true }} failure
+ * @returns {boolean}
+ */
+export const isExternalSiteFailure = (failure) => failure.external === true;
+
+/**
+ * The count of positioned failures that WITHHOLD the run's verdict —
+ * unresolvable literal specifiers that reference the workspace's own surface,
+ * dynamic declared limits and external bare-package sites excluded.
+ *
+ * The one number every verdict lane and refusal guard reads (#595, narrowed):
+ * `check`'s `coverage.complete` and no-verdict lane, the refusal every
+ * descriptive and refuse-class command raises over an unjudged site, and the
+ * envelope builder's completeness law all read this class and nothing else.
+ * Centralized here so the class line cannot drift between the fifteen call
+ * sites the way a repeated inline filter would.
+ *
+ * @param {{ line: number|null, dynamic?: true, external?: true }[]} failures
+ * @returns {number}
+ */
+export const unresolvableLiteralCount = (failures) =>
+  failures.filter(
+    (failure) =>
+      !isWholeFileFailure(failure) &&
+      !isDynamicSiteFailure(failure) &&
+      !isExternalSiteFailure(failure),
+  ).length;
+
+/**
+ * The `coverage.blindSpots` rows every command's coverage block carries: one
+ * row per positioned failure, ALL permanent classes, the run's disclosure of
+ * every site it saw and did not judge.
+ *
+ * Disclosure is deliberately wider than the verdict's withholding: a dynamic
+ * or external site never flips an exit, but it is still named here — the
+ * fields that separate the classes ride the row, which is what lets the
+ * envelope builder's completeness law (`report/json.mjs`) tell a declared
+ * limit and an external bare package from unjudged work without a second
+ * classification.
+ *
+ * @param {{ sourceFile: string, line: number|null, column: number|null,
+ *   reason: string, dynamic?: true, external?: true }[]} failures
+ * @returns {{ file: string, line: number, column: number, reason: string,
+ *   dynamic?: true, external?: true }[]}
+ */
+export const blindSpotRows = (failures) =>
+  failures
+    .filter((failure) => !isWholeFileFailure(failure))
+    .map(({ sourceFile, line, column, reason, dynamic, external }) => ({
+      file: sourceFile,
+      line,
+      column,
+      reason,
+      ...(dynamic ? { dynamic: true } : {}),
+      ...(external ? { external: true } : {}),
+    }));
+
 /**
  * One whole-file failure per source file, first reason kept.
  *

package/src/analysis/typescript.mjs

@@ -373,6 +373,57 @@ function namesDeclaredProject(specifier, workspace) {
   return workspace.projects.some((project) => project.name === name || project.name === specifier);
 }
 
+/**
+ * Whether an unresolvable LITERAL specifier points at the external dependency
+ * universe rather than at the workspace's own governed surface — the row class
+ * that the loud-coverage contract (#595, narrowed) discloses without
+ * withholding the verdict, marked `external: true` on the failure.
+ *
+ * Three shapes always reference the workspace surface and never get the
+ * marker, so a run cannot go quiet over an edge the graph should carry:
+ *
+ * - a path-like specifier (`./`, `../`, `/`): it names a file in the
+ *   workspace's own namespace, and failing to resolve it means that path
+ *   cannot be proven to exist — a broken import, which is loud on purpose;
+ * - a `#` subpath import: package-internal by definition, never an external
+ *   dependency. This is #595's own reported shape
+ *   (`#canary-review/index.mjs`): `packageNameOf` keeps the `#` prefix, so
+ *   the whole-file lane's name test cannot catch it, and without this branch
+ *   the subpath would silently read as external;
+ * - a `paths` alias: the mapping declares the prefix workspace-internal, so
+ *   a specifier under a failed alias is an unproven workspace edge. A `paths`
+ *   key with `*` matches by its prefix (`@app/*` catches `@app/x/y`); an
+ *   exact key matches exactly. (`baseUrl` alone is not consulted — its bare
+ *   results are npm-shaped and read as external.)
+ *
+ * Everything else — `vitest`, `zod`, a scoped package no `paths` row claims —
+ * resolves against an installed dependency tree, and a workspace without that
+ * tree installed (a fresh clone, a trimmed install, the native self-check's
+ * `git archive` copy, which by design carries no `node_modules`) is a normal
+ * state. Those are the rows the native self-check's 284 blind spots are made
+ * of, and treating them as verdict-withholding would make that required CI
+ * step permanently exit 3 over dependencies nobody crossed.
+ *
+ * @param {string} specifier The raw specifier as written.
+ * @param {ts.CompilerOptions} options The resolution options in force.
+ * @returns {boolean}
+ */
+function isExternalUnresolvable(specifier, options) {
+  if (
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith("/") ||
+    specifier.startsWith("#")
+  ) {
+    return false;
+  }
+  for (const key of Object.keys(options.paths ?? {})) {
+    const star = key.indexOf("*");
+    if (star === -1 ? key === specifier : specifier.startsWith(key.slice(0, star))) return false;
+  }
+  return true;
+}
+
 /** The dialect to parse `sourceFile` as; `lang` wins when the caller knows it. */
 function scriptKindFor(sourceFile, lang) {
   if (lang) return SCRIPT_KIND_BY_LANG[lang] ?? ts.ScriptKind.TS;
@@ -784,7 +835,7 @@ function parseFailures(sourceFile, workspaceRelativePath) {
  * nested `node_modules/`, which every package that declares its own
  * `dependencies` has; the branch below says why, with the measurement.
  *
- * @returns {{ resolved: object|null, reason: string|null }}
+ * @returns {{ resolved: object|null, reason: string|null, external?: boolean }}
  */
 function resolveSpecifier(specifier, sourceFile, workspace) {
   const context = contextFor(workspace);
@@ -905,6 +956,12 @@ function resolveSpecifier(specifier, sourceFile, workspace) {
     if (sibling === null) {
       return {
         resolved: null,
+        // A failed literal is classified here, where the resolution options
+        // are in scope: `external: true` marks the bare-package class the
+        // contract discloses without withholding (`isExternalUnresolvable`
+        // holds the class line). The failure-push site forwards the flag to
+        // the row, and every verdict lane counts withholds from its absence.
+        external: isExternalUnresolvable(specifier, context.options),
         reason: `TypeScript cannot resolve '${specifier}' from '${sourceFile}'`,
       };
     }
@@ -992,7 +1049,7 @@ export function analyzeTypeScript({ sourceFile, text, workspace, lang }) {
       // a grammar error there — and `import x = require(y)` is the form that
       // makes `require` the right word for it.
       const callee = site.callee ?? (site.kind === "dynamic" ? "import" : "require");
-      const { resolved, reason } = site.literal
+      const { resolved, reason, external } = site.literal
         ? resolveSpecifier(site.specifier, sourceFile, workspace)
         : {
             resolved: null,
@@ -1023,13 +1080,37 @@ export function analyzeTypeScript({ sourceFile, text, workspace, lang }) {
       // site failures — the "blind spot" the contract documents as legitimately
       // permanent (`report/text.mjs`'s `formatFailures` is where the report
       // explains the two, and `cli.mjs` counts `unchecked` by
-      // `failure.line === null`). A NON-LITERAL argument keeps its line/column
-      // for the same reason: it is genuinely not statically knowable.
+      // `failure.line === null`).
+      //
+      // The positioned rows then part ways by class, and the markers on the
+      // row are what every verdict lane counts by:
+      //
+      // - a positioned literal that still references the workspace's own
+      //   surface — path-like, `#` subpath, or a `paths` alias — carries NO
+      //   marker and withholds the run's verdict (#595, narrowed): a `#`
+      //   subpath naming a declared project is exactly the shape #595
+      //   reported, and `packageNameOf` keeps the `#`, so the whole-file
+      //   lane's name test above cannot catch it;
+      // - a positioned literal pointing at the bare-package universe carries
+      //   `external: true` (`isExternalUnresolvable` holds the class line)
+      //   and discloses without withholding — the native self-check's 284
+      //   bare rows are this class, and withholding them would make that
+      //   required CI step permanently exit 3;
+      // - a NON-LITERAL argument keeps its line/column for the same reason:
+      //   it is genuinely not statically knowable, and carries
+      //   `dynamic: true` (contract.md).
       if (reason) {
         result.failures.push(
           site.literal && namesDeclaredProject(site.specifier, workspace)
             ? fileFailure(sourceFile, reason)
-            : { sourceFile, line: line + 1, column: character + 1, reason },
+            : {
+                sourceFile,
+                line: line + 1,
+                column: character + 1,
+                reason,
+                ...(site.literal ? {} : { dynamic: true }),
+                ...(site.literal && external ? { external: true } : {}),
+              },
         );
       }
     }