candor-ts 0.27.0 → 0.28.0

package/query-core.mjs

@@ -20,8 +20,15 @@ function siblings(prefix, predicate) {
   const dir = nodePath.dirname(prefix) || ".";
   const base = nodePath.basename(prefix);
   try {
+    // SORTED, because readdir order is filesystem ENUMERATION order — stable on one machine, divergent
+    // across filesystems and checkouts, and everything downstream of this list inherits it: the merge
+    // order of multi-report functions, the concatenation order of the ⟨0.28⟩ `unanalyzed` disclosure,
+    // which duplicate callgraph key wins Object.assign. rust (candor-report lib.rs), java (Query.java)
+    // and swift (FixCLI.swift) all sort here; this engine was the outlier, so two engines over an
+    // IDENTICAL tree could emit differently-ordered arrays and a byte-diffing consumer read a change
+    // where there was none.
     return fs.readdirSync(dir).filter((f) => f.startsWith(base + ".") && f.endsWith(".json") && predicate(f))
-      .map((f) => nodePath.join(dir, f));
+      .sort().map((f) => nodePath.join(dir, f));
   } catch { return []; }
 }
 // A sibling filename that is a real REPORT (not a callgraph sidecar, an encountered-crate ledger, a
@@ -50,6 +57,43 @@ export function hasReport(p) {
 // narrower one would answer about a report the gate never gated.
 const reportFilesAt = (prefix) => (fs.existsSync(`${prefix}.json`) ? [`${prefix}.json`] : siblings(prefix, isReport));
 
+// ⟨0.28⟩ SPEC §3.3.1 (3) — the FILES a gate `--report` locator names, for the verdict-sink guard:
+// `reportFilesAt`'s expansion (the SAME enumeration `loadGateReport` below reads — kept adjacent so the
+// guard and the loader cannot drift), plus each report's §2.2 sidecars. Exists because the guard
+// compared the sink against the raw locator TOKEN while the loader reads the token's EXPANSION.
+// MEASURED on this engine 2026-08-12:
+//
+//   gate --report r --policy P --gate-json r.json
+//       → armQueryGateJson wrote the refusal placeholder OVER the operator's report, the load then
+//         failed on the wreckage ("has no functions array"), and the exit-2 refusal document was
+//         written over it AGAIN. The no-`--report` discovery spelling (sink = the discovered
+//         `.candor/report.json`) destroyed the discovered report identically.
+//
+// THE SIDECARS RIDE ALONG (same clause: a report locator names the PAIR). The gate opens no sidecar —
+// that MUST NOT is `loadGateReport`'s — but a sink on the pair's other half is WORSE: the report loads
+// fine, the gate runs, and a REAL verdict lands on the callgraph at a success exit; `callers`/`tour`
+// then read a verdict document where the graph belongs. The segment list is the `isReport` denylist's
+// pair-carrying members: `gate` is excluded because `<stem>.gate.json` is the verdict sink's own
+// beside-the-report layout — the exact spelling `--gate-json` exists for, pinned by the control test —
+// and `encountered-*` because it is engine-local scan bookkeeping no query reads. Existing files only:
+// the guard protects data, and a sidecar not on disk has none to lose.
+const PAIRED_SIDECAR_SEGMENTS = ["calibrated", "callgraph", "hierarchy", "layerreach", "locs"];
+export function gateReportInputFiles(prefix) {
+  if (!prefix) return [];
+  const out = [];
+  for (const r of reportFilesAt(prefix)) {
+    if (r.endsWith(".json")) {
+      const stem = r.slice(0, -".json".length);
+      for (const seg of PAIRED_SIDECAR_SEGMENTS) {
+        const side = `${stem}.${seg}.json`;
+        if (fs.existsSync(side)) out.push(side);
+      }
+    }
+    out.push(r);
+  }
+  return out;
+}
+
 // Defend the queries against a partial/old-engine/hand-edited report: the §2 required fields are
 // defaulted, and a WRONG-TYPE field is coerced — a non-array `inferred` (e.g. the string "Net") must
 // NOT survive, or `new Set("Net")` iterates characters into {N,e,t} (a fabricated effect set). Array
@@ -244,6 +288,48 @@ export function gainsCoverage(curPrefix, basePrefix) {
   return out;
 }
 
+/**
+ * ⟨0.28⟩ SPEC §2 — AND THE SAME MUST CARRIES THE ⟨0.21⟩ MANIFEST, WHICH IS THE STRONGER CAVEAT.
+ *
+ * `gainsCoverage` above has carried the CURRENT report's `coverage` ledger into this verb since ⟨0.15⟩,
+ * for the reason §2 gives: *a "no gains" over an uncovered dep reads clean with false confidence*.
+ * MEASURED: the same verb, on the same report, in the same output, dropped `unanalyzed`.
+ * `coverage.uncovered` says *I could not see into this dependency*; `unanalyzed` says *I could not read
+ * this file of your own code*, and `analyzed.count: 0` says *I judged nothing at all*. The mechanism was
+ * already here and pointed at the weaker field.
+ *
+ * BOTH SIDES, DISCLOSED SEPARATELY, because a gains answer rests on TWO reports and they fail in
+ * different directions:
+ *   · an incomplete CURRENT means the gained set may be SHORT — effects the reader is not being told
+ *     about, which is the whole thing this alarm verb exists to name;
+ *   · an incomplete BASELINE means the comparison FLOOR is soft, so the existing-vs-new `origin` split
+ *     is unreliable and an effect that was always there can read as newly appeared.
+ * One combined flag would say "something here is incomplete" and leave a supply-chain reviewer unable to
+ * act on it. This is why gains does NOT use `absorbCompleteness` (which `containment <baseline>` does):
+ * that verb's answer is a single leak set the two manifests both qualify, while these two qualify
+ * different halves of the answer. The prefixed spelling mirrors the shape already used for coverage
+ * (`coverage` for the current, `coverageDelta` for the difference) rather than inventing a new one, and
+ * `incomplete`/`unanalyzed`/`baselineIncomplete`/`baselineUnanalyzed` are candor-scan's key names exactly
+ * (fe5d831) — this is a cross-engine wire surface.
+ *
+ * ONE READER (`reportCompleteness`) and ONE KEY SET (`completenessFields`), shared with the six
+ * descriptive verbs, so the ⟨0.24⟩ count-0 arm cannot be answered one way here and another there. Both
+ * halves are `{}` on a complete report, so an ordinary comparison stays byte-identical to ⟨0.27⟩.
+ *
+ * Verdict-preserving: no exit code moves. `gains` is advisory by default and `--strict` keys on the
+ * GAINED SET, which this does not touch.
+ */
+export const gainsCompletenessFields = (cur, base) => ({
+  ...completenessFields(cur),
+  ...Object.fromEntries(Object.entries(completenessFields(base))
+    .map(([k, v]) => [`baseline${k[0].toUpperCase()}${k.slice(1)}`, v])),
+});
+
+/** The prefix-level form — the `gainsCoverage` signature, for callers that hold two locators and no
+ *  completeness objects (the MCP `candor_gains` tool; the parity rule). */
+export const gainsCompleteness = (curPrefix, basePrefix) =>
+  gainsCompletenessFields(reportCompleteness(curPrefix), reportCompleteness(basePrefix));
+
 // The returned array carries a non-enumerable `hardFail` flag: true iff a report file was FOUND but
 // yielded NO trustworthy functions — a parse failure OR a malformed shape (a `null`/array/wrong-typed
 // doc, a non-array `functions`, all-junk entries). The loud CLI wrapper (loadReportOrDie) needs it to
@@ -296,14 +382,84 @@ export const claimsToHaveJudgedNothing = (parsed, fns) => {
 export function reportJudgedNothing(prefix) {
   const files = reportFilesAt(prefix);
   if (!files.length) return false;
-  return files.every((f) => {
-    let parsed;
-    try { parsed = JSON.parse(fs.readFileSync(f, "utf8")); } catch { return true; }   // unreadable → no claim
-    // The raw entries, read QUIETLY: this is an advisory, and its caller has already run the loud loader
-    // over the same bytes, so re-disclosing a malformed shape here would double every such line.
-    const raw = parsed && typeof parsed === "object" && parsed.functions !== undefined ? parsed.functions : parsed;
-    return claimsToHaveJudgedNothing(parsed, Array.isArray(raw) ? raw : []);
-  });
+  return files.every(fileClaimsJudgedNothing);
+}
+// The per-FILE question the two prefix-level readers above and below share — extracted so the boolean
+// (the gate's ANDed "did this locator judge anything at all") and the ⟨0.28⟩ disclosure (WHICH member
+// files judged nothing) cannot drift into two readings of the same integer.
+function fileClaimsJudgedNothing(f) {
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(f, "utf8")); } catch { return true; }   // unreadable → no claim
+  // The raw entries, read QUIETLY: this is an advisory, and its caller has already run the loud loader
+  // over the same bytes, so re-disclosing a malformed shape here would double every such line.
+  const raw = parsed && typeof parsed === "object" && parsed.functions !== undefined ? parsed.functions : parsed;
+  return claimsToHaveJudgedNothing(parsed, Array.isArray(raw) ? raw : []);
+}
+/** ⟨0.28⟩ The report FILES under a locator that say they judged nothing — one path per file, the shape
+ *  the disclosure carries (see `completenessFields`). PER FILE, not the ANDed prefix answer: a locator
+ *  naming several members must disclose EACH silent one by name (rust `report_completeness`, java
+ *  `ReportCompleteness` — "one label per report file declaring `analyzed.count: 0`").
+ *
+ *  A file that does not PARSE is excluded here and carried as `unreadable` instead — `judgedNothing` is
+ *  the report's OWN `analyzed.count: 0` assertion, and a file whose bytes cannot be read asserted
+ *  nothing. MEASURED (candor-spec conformance/gen_key_shapes.py corpus, 2026-08-12): over an intact
+ *  report with a corrupt `.dep` sibling, rust and swift answer `incomplete: true` alone while this
+ *  engine listed the corrupt file under `judgedNothing` — a fabricated claim about content nobody read,
+ *  and a consumer told "re-scan, that report reached no conclusion" when the repair is "that file is
+ *  corrupt". `fileClaimsJudgedNothing`'s own unreadable→true stays: `reportJudgedNothing` above is the
+ *  gate's ANDed fail-closed question, where "no readable claim" must never read as "judged something". */
+export function reportJudgedNothingFiles(prefix) {
+  return reportFilesAt(prefix).filter((f) => fileParses(f) && fileClaimsJudgedNothing(f) && !fileHasNoManifest(f));
+}
+
+/** ⟨0.28⟩ SPEC §2 — **THE THIRD ROW IS NOT THE FIRST ROW.** §2's three-row table distinguishes
+ *  `analyzed.count: 0` (row 1 — *nothing was judged*, a claim the report MAKES) from `analyzed` ABSENT
+ *  (row 3 — a pre-⟨0.21⟩ producer with no manifest at all, which claims nothing). MEASURED here
+ *  2026-08-12 over `{"candor":{…},"functions":[]}` with no `analyzed` key: this engine listed the file
+ *  under `judgedNothing` and its note said the report *"say[s] they JUDGED NOTHING (`analyzed.count:
+ *  0`)"*. **The report declares nothing.** The HEDGE is the right direction — row 3's own instruction is
+ *  *no manifest, no claim* — but the disclosure is FALSE, and this family rates a false disclosure worse
+ *  than a missing one (§3.4's `net-partner` finding: an engine reported "ignoring unknown config key"
+ *  while honouring it).
+ *
+ *  It is also a hole in ⟨0.28⟩'s own pin, which defines `judgedNothing` as *reports declaring
+ *  `analyzed.count: 0`*: putting a row-3 report there makes the key mean two things and loses the
+ *  distinction the table exists to draw. The REPAIRS differ — row 1 wants a scan that reaches a
+ *  conclusion, row 3 wants a producer that emits a manifest at all.
+ *
+ *  A legacy BARE ARRAY report has no envelope and therefore no manifest either, so it is row 3 too when
+ *  it is empty; when it LISTS entries it is not hedging at all (`claimsToHaveJudgedNothing` is false) and
+ *  never reaches this filter. Asked of the same parsed bytes as its two siblings so the three cannot
+ *  drift into three readings of one file. */
+const fileHasNoManifest = (f) => {
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(f, "utf8")); } catch { return false; }  // unreadable → `unreadable`
+  if (Array.isArray(parsed)) return true;                       // legacy bare array: no envelope, no manifest
+  return !!parsed && typeof parsed === "object" && !("analyzed" in parsed);
+};
+
+/** ⟨0.28⟩ The consulted report FILES carrying no `analyzed` key at all — SPEC §2's row 3, pinned to its
+ *  own key (`noManifest`) in the rung that introduced it. Only the files that are also HEDGING: a row-3
+ *  report that LISTS functions demonstrably judged units and said so the only way it could, and keeps the
+ *  standing it has always had (`claimsToHaveJudgedNothing`'s manifest-absent row). */
+export function reportNoManifestFiles(prefix) {
+  return reportFilesAt(prefix).filter((f) => fileParses(f) && fileHasNoManifest(f) && fileClaimsJudgedNothing(f));
+}
+
+/** ⟨0.28⟩ Does the file's TEXT parse at all — the line between "this report says X" and "this report
+ *  says nothing readable". Parse-only on purpose: shape defects inside a parsed document are judged per
+ *  key role (SPEC §2 ⟨0.24⟩) by the loaders, not here. */
+const fileParses = (f) => {
+  try { JSON.parse(fs.readFileSync(f, "utf8")); return true; } catch { return false; }
+};
+
+/** ⟨0.28⟩ The report FILES under a locator that could not be read at all — the THIRD cause, and it is a
+ *  cause of `incomplete` with NO wire key of its own (rust and swift both answer `incomplete: true` and
+ *  name the file on the human channel only; matching them is the point — one wire shape per state).
+ *  Before this arm existed, `reportUnanalyzed` skipped an unparseable member with a bare `catch` and the
+ *  corrupt file surfaced only through the judged-nothing mislabel above. */
+export function reportUnreadableFiles(prefix) {
+  return reportFilesAt(prefix).filter((f) => !fileParses(f));
 }
 
 // Load ONE report file → { entries, hardFail }. A read/parse throw, or an empty result over a doc that
@@ -356,6 +512,123 @@ export function reportUnanalyzed(prefix) {
   return out;
 }
 
+/**
+ * ⟨0.28⟩ SPEC §2 — THE SAME MANIFEST, READ FOR A *DESCRIPTIVE* VERB. `reportUnanalyzed` above was written
+ * for the ADVISORY verbs, because the clause it implements was written over the instance it was found in:
+ * "a report-consuming verb whose VERDICT could change". ⟨0.28⟩ corrects the clause to the condition that
+ * makes it true — the obligation binds **any verb whose output could be read as a negative finding about
+ * the code: a verdict, an EMPTY RESULT SET, or a ZERO COUNT**. MEASURED on this engine over the standard
+ * post-⟨0.28⟩ artifact (`analyzed.count: 0` + a non-empty `unanalyzed`, what an armed run leaves on disk):
+ *
+ *     where Fs     {"effect":"Fs","directly":[],"inherited":[]}    exit 0, no hedge
+ *     map          {}                                              exit 0, no hedge
+ *     blindspots   {"sources":[],"totalUnknown":0}                 exit 0, no hedge
+ *     reachable    {"entryPoints":0,"effects":{}}                  exit 0, no hedge
+ *     containment  {"contained":[],"ambient":{}}                   exit 0, no hedge
+ *     tour         {"reaches":[]}                                  exit 0, no hedge
+ *
+ * "no blind spots" out of a report whose own manifest names a file candor could not read. A consumer
+ * cannot distinguish *nobody performs Fs* from *nothing was examined*.
+ *
+ * ONE READER, TWO CAUSES, and the second cause is why this is a function rather than a call to
+ * `reportUnanalyzed` at six new sites:
+ *
+ *   · `unanalyzed` non-empty — candor could not READ a file of the target's own code;
+ *   · `analyzed.count: 0` — candor read what it read and JUDGED NOTHING. A report in that state carries
+ *     no `unanalyzed` at all (there is no unread FILE to name), so a manifest-only reader sees a complete
+ *     report and every verb answers `{}` over it just the same. SPEC §2 names both: *"a report-consuming
+ *     verb MUST re-disclose a non-empty `unanalyzed`, **and an `analyzed.count` of 0**, on the same
+ *     terms"*. Decided by `reportJudgedNothing` — the SAME predicate `gate --report`, the MCP gate and the
+ *     LSP already ask — so a report cannot be judged-nothing on one route and not on another.
+ *
+ * A report that is BOTH complete and has judged something yields `mustHedge() === false`, and every
+ * consumer below is then a no-op: an ordinary run stays byte-identical. That is not a nicety — a hedge on
+ * every run trains the reader to ignore it, the same reason ⟨0.15⟩ omits `coverage` when nothing is
+ * uncovered.
+ */
+export function reportCompleteness(prefix) {
+  // `judgedNothing` is the PER-FILE list, not the ANDed boolean the gate asks: the disclosure names
+  // WHICH report judged nothing, so a locator with one silent member among several still hedges — the
+  // semantics rust and java pin, and a repair the reader can aim (that file, not "somewhere here").
+  // ⟨0.28⟩ `unreadable`: the third cause, split out of the judged-nothing mislabel — see
+  // `reportUnreadableFiles`. It hedges the answer and names the file on the human channel only.
+  // ⟨0.28⟩ `noManifest`: SPEC §2's row 3, split out of the `judgedNothing` mislabel — see
+  // `reportNoManifestFiles`. It hedges like the others and carries its own wire key, because the two
+  // want different repairs and because `judgedNothing` is PINNED to "reports declaring `analyzed.count:
+  // 0`", which a row-3 report is not.
+  return { unanalyzed: reportUnanalyzed(prefix), judgedNothing: reportJudgedNothingFiles(prefix),
+           noManifest: reportNoManifestFiles(prefix), unreadable: reportUnreadableFiles(prefix) };
+}
+
+/**
+ * ⟨0.28⟩ Is there anything to disclose? **The trigger for an ANSWER, where a non-empty `unanalyzed` alone
+ * is the trigger for a VERDICT** — and the difference is an exit code, not a mood.
+ *
+ * `unverified --strict` / `fix-gate --strict` answer 2 ("the gate refuses over these bytes, so do I") off
+ * the `unanalyzed` arm — and ⟨0.28⟩ off the `unreadable` arm too, because `gate --report` REFUSES over a
+ * corrupt member (measured, exit 2) and §3.2's relation binds the exit as much as the document. ⟨0.24⟩
+ * ruled the count-0 arm explicitly the other way for exactly those bytes: it is *a disclosure, not an
+ * exit code* — `gate --report` exits 0 over a judged-nothing report, and a verb exiting 2 there would
+ * claim it got LESS far than the gate on identical input, the mirror of the over-claim the strict exit
+ * exists to prevent. So count-0 reaches both DISCLOSURE channels through this predicate and stops at the
+ * exit code; see `advisoryAnswer`, whose exit-bearing callers key `--strict` on manifest + unreadable.
+ */
+export const mustHedge = (c) => !!(c && (c.unanalyzed?.length || c.judgedNothing?.length
+                                         || c.noManifest?.length || c.unreadable?.length));
+
+/**
+ * ⟨0.28⟩ The disclosure KEYS, defined ONCE, for spreading into a verb's answer document — `{}` when there
+ * is nothing to disclose, so `{ ...data, ...completenessFields(c) }` is byte-identical to `data` on a
+ * complete report. (JS objects preserve insertion order, so the verb's own keys keep their pinned order
+ * and the caveat lands after them. candor-rust's first draft of this rung routed two verbs through a
+ * BTreeMap-backed serialiser to reach the same place and silently RE-SORTED both documents on ordinary
+ * runs — a disclosure rung must not reformat the answers it is disclosing about.)
+ *
+ * `incomplete: true` is the flag EITHER cause raises, so a consumer that only branches on it is safe under
+ * both; `judgedNothing`/`unanalyzed` name WHICH, because the two want different repairs — one wants a scan
+ * that can READ a file, the other a scan that reached a conclusion. Each is omitted when it does not
+ * apply, so a document raised by `unanalyzed` alone stays byte-identical to the pre-⟨0.28⟩ advisory shape.
+ *
+ * `judgedNothing` is the ARRAY OF REPORT PATHS, the shape rust, java and swift all emit — this engine
+ * first shipped `judgedNothing: true`, reusing the MCP gate tool's spelling, and a consumer doing
+ * `doc.judgedNothing.length` got a TypeError here while one doing `=== true` missed the other three.
+ * The array also answers a question the boolean cannot: WHICH report judged nothing, over a multi-report
+ * locator. The two spellings now deliberately differ because they are different surfaces: THIS key rides
+ * answer/advisory documents and is the cross-engine wire shape; the MCP gate tool's `judgedNothing: true`
+ * (mcp.mjs) is a flag on ONE gate verdict about ONE locator, where "which file" is carried by the
+ * adjacent ⟨0.24⟩ prose and no sibling engine serves that tool — the wire shape governs everywhere the
+ * engines can be diffed.
+ */
+export function completenessFields(c) {
+  if (!mustHedge(c)) return {};
+  // `unreadable` raises the flag and adds NO key of its own — measured, rust and swift answer
+  // `incomplete: true` alone over a corrupt sibling, and a third spelling here would be the
+  // judgedNothing three-way split again, minted by the engine that was fixing it.
+  // ⟨0.28⟩ `noManifest` is the third NAMED cause, `omitted when empty` like the other two, and it RAISES
+  // `incomplete` exactly as they do — the flag stays the one key a consumer may branch on alone and be
+  // safe under every cause. It is separate from `judgedNothing` because that key is pinned to "reports
+  // declaring `analyzed.count: 0`" and a row-3 report declares nothing: merging them would make one key
+  // mean two things and lose the distinction §2's three-row table exists to draw.
+  return { incomplete: true,
+           ...(c.unanalyzed?.length ? { unanalyzed: c.unanalyzed } : {}),
+           ...(c.judgedNothing?.length ? { judgedNothing: c.judgedNothing } : {}),
+           ...(c.noManifest?.length ? { noManifest: c.noManifest } : {}) };
+}
+
+/**
+ * ⟨0.28⟩ Union in a SECOND locator's manifest — for `containment <baseline>`, whose answer is a DIFFERENCE
+ * and is therefore unsound if EITHER side is partial, in opposite directions: a leak living in an unread
+ * file of the CURRENT tree is missed (a false all-clear), while one living in an unread file of the
+ * BASELINE reads as newly appeared (a fabricated leak, at exit 1). One merged object rather than two
+ * notes, because the keys are fixed and a second write would overwrite the first side's manifest.
+ */
+export const absorbCompleteness = (a, b) => ({
+  unanalyzed: [...(a.unanalyzed ?? []), ...(b.unanalyzed ?? [])],
+  judgedNothing: [...(a.judgedNothing ?? []), ...(b.judgedNothing ?? [])],
+  noManifest: [...(a.noManifest ?? []), ...(b.noManifest ?? [])],
+  unreadable: [...(a.unreadable ?? []), ...(b.unreadable ?? [])],
+});
+
 /**
  * ⟨0.24⟩ SPEC §3.2 — THE OMIT-`ok` RULE, IN ONE PLACE so `unverified`, `fix-gate`, `whatif` and any later
  * sibling cannot drift apart on it. Over a report declaring `unanalyzed`, an advisory verb emits
@@ -387,13 +660,38 @@ export function reportUnanalyzed(prefix) {
  * the BODY rather than taken as a third parameter, so a verb that computes the disclosure cannot forget to
  * declare it — the ⟨0.24⟩ measurement that the CLI and MCP had drifted on exactly this began with a second
  * channel forgetting to pass an argument.
+ *
+ * ⟨0.28⟩ THE THIRD TRIGGER: `judgedNothing` — SPEC §2's `analyzed.count: 0` row, which this function did
+ * not read. MEASURED: over a report that judged nothing, `unverified` answered `{ok: true, unverified: []}`
+ * — the verb whose whole job is *"your green gate is not provably green"* certifying a package it never
+ * examined, from a report that names no unread FILE to trip the manifest arm. `ok` goes for the same
+ * reason it goes above: neither boolean is honest, and `if (r.ok)` must fail safe.
+ *
+ * AND THE EXIT CODE DOES NOT MOVE, which is the load-bearing half. Both `--strict` callers compute their
+ * exit from the MANIFEST alone, never from this document, because ⟨0.24⟩ ruled count-0 explicitly the other
+ * way: *"A DISCLOSURE, NOT AN EXIT CODE"*. `gate --report` exits 0 over these bytes, and an advisory verb
+ * exiting 2 there would claim it got LESS far than the gate on identical input — the mirror of the
+ * over-claim the strict exit exists to prevent. (`mustHedge` is the same distinction, stated for a verb
+ * that has no exit code for it to matter to.)
  */
-export function advisoryAnswer(body, unanalyzed) {
+export function advisoryAnswer(body, unanalyzed, judgedNothing = [], unreadable = [], noManifest = []) {
   const unevaluated = body?.unevaluated;
-  if (!unanalyzed?.length && !unevaluated?.length) return body;  // COMPLETE: unchanged, byte for byte, `ok` and all.
+  if (!unanalyzed?.length && !unevaluated?.length && !judgedNothing?.length && !unreadable?.length
+      && !noManifest?.length)
+    return body;  // COMPLETE: unchanged, byte for byte, `ok` and all.
   const { ok, ...rest } = body;                          // eslint-disable-line no-unused-vars -- omitted BY DESIGN
+  // The array of report paths, same key and same shape as `completenessFields` — ONE wire spelling for
+  // this key across the answer and advisory documents (see the shape ruling there). `unreadable` withdraws
+  // `ok` and raises `incomplete` with NO key of its own, exactly as `completenessFields` rules it.
+  // ⟨0.28⟩ `noManifest` DOES get a key of its own — SPEC §2 pins it — and it rides here for the same
+  // reason `judgedNothing` does: an advisory verb's `ok` is a claim about the CODE, and a report that
+  // never emitted a manifest cannot support it (row 3: *no manifest, no claim*).
+  const judged = { ...(judgedNothing?.length ? { judgedNothing } : {}),
+                   ...(noManifest?.length ? { noManifest } : {}) };
   // Key order matches the gate's verdict document: the finding, then `unevaluated`, then the manifest.
-  return unanalyzed?.length ? { ...rest, incomplete: true, unanalyzed } : rest;
+  if (unanalyzed?.length) return { ...rest, incomplete: true, unanalyzed, ...judged };
+  return (judgedNothing?.length || noManifest?.length || unreadable?.length)
+    ? { ...rest, incomplete: true, ...judged } : rest;
 }
 
 export function loadReport(prefix) {
@@ -546,6 +844,31 @@ export function loadCallgraph(prefix) {
   return tagPartial(norm(cg), partial);
 }
 
+/**
+ * ⟨0.28⟩ The call graph EMBEDDED IN THE REPORT — each entry's §2 `calls` edges, keyed by fn. The
+ * fallback the graph verbs (`callers`/`impact`/`path`, CLI and MCP) run over when the §2.2 sidecar is
+ * absent, exactly as rust (callers.rs: "Fallback (no call-graph sidecar): build a graph from the
+ * report's effect-relevant `calls` edges and run the SAME query") and java do. Without it, a VALID
+ * report queried without its sidecar — a single hand-copied `report.json`, a locator §3.3.1 supports —
+ * answered `unanswerable` at exit 2 here while rust and java answered real callers at exit 0.
+ * `unanswerable` is for a graph that is genuinely ABSENT, not for one present by another route.
+ *
+ * EVERY entry is a key, even one with no calls — a leaf that performs its effect directly must still
+ * resolve as a target (rust's fallback map collects every entry). Same-named entries across merged
+ * workspace siblings UNION their edges (the effectsByFn lesson: last-wins silently drops a member's
+ * rows). Effect-relevant edges ONLY, so this graph under-approximates the sidecar: a pure fn appears at
+ * most as a CALLEE, never a key — which is why a no-match over the fallback is INCONCLUSIVE, not proof
+ * of absence (the callers verb keeps that distinction; rust corpus-audit #5).
+ */
+export function reportCallsGraph(fns) {
+  const g = {};
+  for (const e of fns) {
+    const prev = g[e.fn];
+    g[e.fn] = prev ? [...new Set([...prev, ...(e.calls ?? [])])] : [...(e.calls ?? [])];
+  }
+  return g;
+}
+
 // ---- the §3.1 match ladder: exact > segment-suffix > substring ------------------------------------
 function matchTier(name, q) {
   if (name === q) return 3;