@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/source/write-isolation.d.ts

@@ -1,5 +1,12 @@
 import type { Detector } from "../../engine-types.js";
-import { type Scan, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+import { type Scan, type Site, type SourceDetectorEntry, type SrcFile } from "./_scan.js";
+/** R-51's scan plus the public writes found OUTSIDE its scope (no no-org throw,
+ *  no typed-unauthorised return, no marker). The list never reaches a verdict. */
+export interface R51Scan {
+    scan: Scan;
+    outOfScope: Site[];
+}
 export declare function scanR51(files: SrcFile[]): Scan;
+export declare function scanR51Detailed(files: SrcFile[]): R51Scan;
 export declare const R51: Detector;
 export declare const SOURCE_WRITE_ISOLATION_DETECTORS: SourceDetectorEntry[];

package/dist/detectors/source/write-isolation.js

@@ -1,4 +1,5 @@
-import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
+import { SCOPE_REFUSED_RETURN } from "./isolation.js";
+import { code, decide, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, } from "./_scan.js";
 const CUSTOM_MUTATION_OPEN = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customMutation\s*\(/;
 const CUSTOM_QUERY_DEF = /(?:export\s+)?const\s+([A-Za-z0-9_]+)\s*=\s*customQuery\s*\(/;
 const FIRST_IDENT = /([A-Za-z_][A-Za-z0-9_]*)/;
@@ -6,7 +7,26 @@ const BASE_PUBLIC_MUTATION = "mutation";
 const BASE_INTERNAL_MUTATION = "internalMutation";
 // A no-org throw a write inherits: an org-keyed ConvexError, or a write/org gate
 // helper that throws when no org is resolved.
-const ORG_THROW = /throw\b[^;]*\b(?:NO_ORG|ORG_REQUIRED|RBAC_DENIED|no org|missing org|organization is required|not in (?:an )?org)/i;
+//
+// `RBAC_DENIED` is NOT in this vocabulary, and that is the standard's own line, not
+// a convenience. The pinned standard (backend-standard-4bcd605.md :652) says "a
+// mutation that refuses an unauthorised write via `requireOrgAdmin` throwing
+// `RBAC_DENIED` is **correct**", and R-51's own text (:655-656) keeps R-16's
+// `{code,field/scope,message}` refusal of a chosen unauthorised action correct and
+// names R-51's throw as NO_ORG (an org-keyed ConvexError or
+// requireWriteAccess/requireWorkspaceId/getEffectiveWorkspaceId). Counting every
+// RBAC_DENIED as a no-org throw contradicted both lines (isolation.ts header
+// :16-19 said CORRECT while this regex said RED). An RBAC_DENIED raised BECAUSE the
+// org is missing is still caught — by ORG_KEYED_GUARDED_THROW below, which reads
+// the CONDITION, not the code word.
+const ORG_THROW = /throw\b[^;]*\b(?:NO_ORG|ORG_REQUIRED|no org|missing org|organization is required|not in (?:an )?org)/i;
+// A throw (any code) whose governing `if` is an ORG-keyed absence test — the
+// no-org path itself, whatever the error string says:
+//   if (!scope.isMaster && scope.orgSlug === null) { throw new ConvexError("RBAC_DENIED…") }
+// The condition must test an org/workspace field for absence; an identity-absence
+// test (`if (!identity)`) is a caller with no credential at all, not the signed-in
+// pre-org shell R-51 protects, and is R-16's refusal.
+const ORG_KEYED_GUARDED_THROW = /if\s*\((?:[^()]|\([^()]*\))*?(?:!\s*(?:[A-Za-z_$][\w$]*\.)?(?:org|orgId|orgSlug|workspaceId|workspace)\b|\b(?:org|orgId|orgSlug|workspaceId)\s*(?:===|==)\s*(?:null|undefined))(?:[^()]|\([^()]*\))*\)\s*\{?\s*throw\b/i;
 const WRITE_GATE_HELPER = /\b(?:requireWriteAccess|requireWorkspaceId|requireOrgId|getEffectiveWorkspaceId|getOrgIdOrThrow|ensureCurrentOrg)\s*\(/;
 // a gate helper generally (any require*/ensure*/assert* access check in a wrapper).
 const GATE_HELPER = /\b(?:require|ensure|assert)[A-Z][A-Za-z0-9_]*\s*\(/;
@@ -59,12 +79,17 @@ function namedValueDomination(before) {
 function throwDomination(blockText) {
     const t1 = ORG_THROW.exec(blockText);
     const t2 = WRITE_GATE_HELPER.exec(blockText);
-    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY);
+    const t3 = ORG_KEYED_GUARDED_THROW.exec(blockText);
+    const throwIdx = Math.min(t1 ? t1.index : Number.POSITIVE_INFINITY, t2 ? t2.index : Number.POSITIVE_INFINITY, t3 ? t3.index : Number.POSITIVE_INFINITY);
     if (!Number.isFinite(throwIdx))
         return "none";
     const before = blockText.slice(0, throwIdx);
     if (namedValueDomination(before))
         return "dominated";
+    // Form C — the VP pre-org `if (scope.refused) return …` typed value (shared
+    // definition with R-50, isolation.ts SCOPE_REFUSED_RETURN).
+    if (SCOPE_REFUSED_RETURN.test(before))
+        return "dominated";
     if (!TYPED_EMPTY_RETURN.test(before))
         return "none";
     return NO_ORG_GUARD.test(before) ? "dominated" : "ambiguous";
@@ -169,6 +194,9 @@ function mutationBlock(lines, i) {
     return { lines: body, unterminated: seenOpen };
 }
 export function scanR51(files) {
+    return scanR51Detailed(files).scan;
+}
+export function scanR51Detailed(files) {
     const scan = emptyScan();
     const builders = discoverWriteBuilders(files);
     // Public writes that matched a definition opener but exhibit NO org-throw, NO
@@ -242,19 +270,28 @@ export function scanR51(files) {
                 .map((l) => l.raw)
                 .join("\n");
             const blockAll = block.lines.map((l) => l.raw).join("\n");
-            const throwsOnNoOrg = ORG_THROW.test(blockText) || WRITE_GATE_HELPER.test(blockText);
+            const throwsOnNoOrg = ORG_THROW.test(blockText) ||
+                WRITE_GATE_HELPER.test(blockText) ||
+                ORG_KEYED_GUARDED_THROW.test(blockText);
             const typedUnauth = TYPED_UNAUTH_RETURN.test(blockText);
             const hasMarker = CONTRACT_MARKER.test(blockAll);
             if (!throwsOnNoOrg && !typedUnauth && !hasMarker) {
-                // A bare public write with no visible org isolation. Not a gated
-                // subject — but recorded so a tree whose ENTIRE public-write surface
-                // is bare is judged (CNJ-with-sites) rather than falsely abstained.
+                // A public write that neither throws on the no-org path, nor returns a
+                // typed unauthorised result, nor carries a marker is NOT an R-51
+                // subject. The pinned standard's red (backend-standard-4bcd605.md :656,
+                // clause b) is "a bare public mutation whose no-org path THROWS" with
+                // the two readable absences; a write with no no-org throw cannot
+                // crash a pre-org shell, which is the whole of R-51. Whether such a
+                // write resolves its caller at all is CR-1's control
+                // (src/caller-resolution.ts), which drives the exit code — the
+                // instrument still goes red on an unguarded write, under the control
+                // whose question it is. Counted only to word the empty abstain.
                 ungated.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public mutation with no org-throw, no typed-unauthorized return, and no write-contract marker — an UNMARKED public write. No org-isolation handling and no client contract is visible in convex/; an instrument that abstains here protects nothing (a fully-unmarked write is exactly the surface a pre-org client shell can issue). NON-CONFORMING until the author isolates org via a fail-closed path, returns a typed unauthorized result, or records a write-contract marker`,
+                    note: `${fn}: public mutation with no no-org throw, no typed-unauthorized return, no write-contract marker — not an R-51 subject (standard 4bcd605 :656 red requires a no-org throw); caller resolution is CR-1's control`,
                 });
-                continue; // not a gated subject
+                continue; // not a subject
             }
             if (typedUnauth) {
                 // The write returns a shape on the no-org path — a pre-org client can render
@@ -295,7 +332,7 @@ export function scanR51(files) {
                 scan.cnj.push({
                     rel: f.rel,
                     n: block.lines[0].n,
-                    note: `${fn}: public mutation throws on the missing-org path AND carries a write-contract marker — the marker records a claim that a client cannot reach this write before an org exists, which convex/ cannot verify. R-51 refuses (a reviewer checks the marker's claim) — never a silent green`,
+                    note: `${fn}: public mutation throws on the missing-org path AND carries a write-contract marker — the marker records a claim that a client cannot reach this write before an org exists, which convex/ cannot verify. R-51 refuses (a reviewer checks the marker's claim) — never a silent green. Why R-50 accepts its marker and R-51 does not: the pinned standard decides it per rule — R-50's green includes a query that "documents a client contract" (4bcd605 :653), while R-51 lists "a write … that carries a write-contract marker whose unreachability claim the detector cannot verify" under could-not-judge, never green (4bcd605 :656)`,
                 });
             }
             else {
@@ -313,27 +350,24 @@ export function scanR51(files) {
             }
         }
     }
-    // A tree whose ENTIRE public-write surface is ungated (no throw / typed-unauth /
-    // marker on ANY write) leaves the scan otherwise empty. The legacy abstain then
-    // claimed "no public mutation matched" — FALSE when bare public writes exist, and
-    // a silent pass over a fully-ungated backend. Surface those writes as
-    // could-not-judge sites so the verdict is CNJ-with-sites, not a misleading empty
-    // abstain. Gated on "scan otherwise empty" so a tree that already produced
-    // subjects (VP: 7 marker CNJ) is byte-for-byte unchanged — the bare-write
-    // disposition in a mixed tree is out of this fix's scope.
-    // An UNMARKED bare public write (no throw / typed-unauth / marker) is
-    // NON-CONFORMING, never an abstention — whether the scan is otherwise empty (a
-    // fully-unmarked public-write surface) OR mixed (bare writes alongside
-    // gated/marker subjects). Laurent doctrine: "an instrument that cannot go red
-    // protects nothing; CNJ is for UNREADABLE input only." A bare write is fully
-    // READABLE — its two absences (no isolation, no contract) are the defect, not a
-    // could-not-read. Push to violate; the author's exit is a fail-closed path, a
-    // typed unauthorized return, or a recorded write-contract marker.
-    for (const u of ungated)
-        scan.violate.push(u);
-    return scan;
+    // Unmarked public writes are NOT pushed anywhere (standard 4bcd605 :656 — the red
+    // requires a no-org throw). Until 0.1.16 they were pushed to `violate`; that
+    // obligation is CR-1's now (a write resolving no caller is a CR-1 violation).
+    return { scan, outOfScope: ungated };
 }
-export const R51 = srcDetector("R-51", "R-51 a public mutation returns a typed unauthorized result on the no-org path, never an uncaught throw a pre-org client shell cannot render", "a public write either returns a typed unauthorized result / documents its client contract, or a human confirms a pre-org client cannot reach it — it never throws NO_ORG on a path an ordinary render can hit", scanR51, "R-51: no public mutation matched in the scanned tree — no write to certify. NOT a clean bill.");
+const R51_ID = "R-51 a public mutation returns a typed unauthorized result on the no-org path, never an uncaught throw a pre-org client shell cannot render";
+const R51_CHECK = "a public write either returns a typed unauthorized result / documents its client contract, or a human confirms a pre-org client cannot reach it — it never throws NO_ORG on a path an ordinary render can hit";
+export const R51 = {
+    id: R51_ID,
+    run: (tree) => {
+        const { scan, outOfScope } = scanR51Detailed(tree.files);
+        const n = outOfScope.length;
+        const empty = n > 0
+            ? `R-51: no R-51 subject in the scanned tree — ${n} public mutation(s) matched, none throws on the no-org path, returns a typed unauthorized result, or carries a write-contract marker (out of scope per standard 4bcd605 :656; caller resolution is CR-1's control). NOT a clean bill.`
+            : "R-51: no public mutation matched in the scanned tree — no write to certify. NOT a clean bill.";
+        return decide("R-51", R51_ID, R51_CHECK, scan, empty);
+    },
+};
 export const SOURCE_WRITE_ISOLATION_DETECTORS = [
     { detector: R51, ruleId: "R-51", standardPin: SOURCE_STANDARD_PIN },
 ];

package/dist/detectors/source/writesafety.js

@@ -131,20 +131,33 @@ export function scanR18(files) {
 //       them into one mutation "would game the regex without changing atomicity"
 //       (okfBundleNode importOkfBundle shape).
 // An action that would be flagged non-conforming may carry an `atomicity-exception:`
-// marker naming EXACTLY ONE of those two shapes. Per Eta's three conditions:
-//   COND 1 — the disposition is COULD-NOT-JUDGE, never conform. A marker records a
-//     CLAIM that reaches a human reviewer; it never closes the rule green (same as
-//     the R-51 marker, #141).
-//   COND 2 — the marker MUST name which shape it claims, because the two are checked
-//     differently and the reviewer must know which question to ask.
+// marker naming EXACTLY ONE of those two shapes. Per Eta's three conditions
+// (superseded on the disposition axis by task k179jnhx, §23 — judgement retired
+// as an acceptance kind, 2026-09-02):
+//   COND 1 — originally "the disposition is COULD-NOT-JUDGE, never conform: a
+//     marker records a CLAIM that reaches a human reviewer" (Eta ruling
+//     2026-08-31, mirroring the R-51 marker #141). The standard's §23 rewrite
+//     retires that disposition: a well-formed, COMPLETE claim (COND 2 + COND 3
+//     both satisfied — the shape named, and its checkable sub-conditions all
+//     present) IS the written justification the marker was always meant to
+//     record, exactly as JUSTIFIÉ:/JUSTIFIED: is elsewhere — so it now decides
+//     mechanically to PRESENT, never could-not-judge. An INCOMPLETE claim still
+//     buys nothing (COND 3, unchanged): the site stays non-conforming until the
+//     claim is well-formed.
+//   COND 2 — the marker MUST name which shape it claims, because the three are
+//     checked differently and the check must know which sub-conditions to ask for.
 //   COND 3 — the dangerous shape is (2): "unbounded loop, each write independently
 //     atomic" is a sentence anyone can write about a split invariant. So shape (2)
 //     is only honoured when the region ALSO names the loop (for/for-of/.forEach/.map)
 //     AND states the independence (no invariant spans two writes). A shape-(2) marker
 //     that names neither the loop nor the independence is INCOMPLETE — it does not buy
-//     could-not-judge; the site stays non-conforming until the claim is well-formed.
-// A well-formed marker → could-not-judge (the reviewer verifies the per-site claim).
-// No marker, an unknown shape, or an incomplete shape-(2) claim → non-conforming.
+//     present; the site stays non-conforming until the claim is well-formed.
+// A well-formed, COMPLETE marker → present (the claim itself is the recorded
+// justification; the control decides on the claim's structural completeness,
+// never on a person's opinion of whether it is sound).
+// No marker, an unknown shape, or an incomplete claim → non-conforming.
+// could-not-judge is reserved for a site the instrument could not read (never
+// reached here — every site below either parsed a marker or did not).
 // ---------------------------------------------------------------------------
 const ACTION_OPEN = /export\s+const\s+(\w+)\s*=\s*action\s*\(/;
 const NEXT_EXPORT = /export\s+const\s+\w+\s*=/;
@@ -232,16 +245,16 @@ export function scanR29(files) {
                             ? shapeReingest
                             : false;
                 if (shape && shapeComplete) {
-                    // COND 1: a well-formed marker yields COULD-NOT-JUDGE, never conform —
-                    // the claim is deferred to the reviewer, who verifies it per site.
-                    scan.cnj.push({
+                    // COND 1 (§23 rewrite, task k179jnhx): a well-formed, COMPLETE marker
+                    // is itself the written justification — decided mechanically, present.
+                    scan.conform.push({
                         rel: f.rel,
                         n: firstMut || openLine,
-                        note: `action ${inAction} issues ${count} ctx.runMutation calls AND carries an atomicity-exception marker claiming shape "${shape}" — ${shape === SHAPE_PER_ITEM_LOOP
+                        note: `action ${inAction} issues ${count} ctx.runMutation calls AND carries a COMPLETE atomicity-exception marker claiming shape "${shape}" — ${shape === SHAPE_PER_ITEM_LOOP
                             ? "the region names its loop and states the per-item writes are independently atomic (no invariant spans two)"
                             : shape === SHAPE_GATE_REINGEST
                                 ? "a leading gate runMutation, a supersede/dedup keyed on a stable namespace, and a recovering re-insert loop, with the convergence stated explicitly — a re-ingest of the same stable key converges on one current set"
-                                : "exactly two runMutations, the first a gate (require*/assert*/bind*) preceding a single atomic write, which R-29's <=1 bar has no room for"}. R-29 refuses (a reviewer verifies the claim per site) — never a silent green (Eta ruling 2026-08-31)`,
+                                : "exactly two runMutations, the first a gate (require*/assert*/bind*) preceding a single atomic write, which R-29's <=1 bar has no room for"}. The marker's structural completeness IS the written justification (§23) — decided by the claim's presence, never a person's opinion of it`,
                     });
                 }
                 else if (shape === SHAPE_GATE_REINGEST) {

package/dist/detectors/standard/_doc.d.ts

@@ -1,6 +1,6 @@
 import type { Detector, DetectorResult } from "../../engine-types.js";
 /** The vendored-fixture basename used as the anchor file for every doc site. */
-export declare const STANDARD_FILE = "backend-standard-4bcd605.md";
+export declare const STANDARD_FILE = "backend-standard-2825122.md";
 export declare const VENDORED_STANDARD_PATH: string;
 /** The standard all four are pinned against (short hash a9d7877b). */
 export declare const STANDARD_DOC_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A714/\u00A711/\u00A710/\u00A73";

package/dist/detectors/standard/_doc.js

@@ -2,7 +2,7 @@
 // detectors that read THE STANDARD ITSELF as their material — R-42, R-15, R-32,
 // R-39. Unlike the source-tree detectors (which read convex/ via `tree.files`)
 // and the oracle detectors (which read the CSV), these read the VENDORED standard
-// fixture `fixtures/backend-standard-4bcd605.md` — the material at the pin. The
+// fixture `fixtures/backend-standard-2825122.md` — the material at the pin. The
 // engine's contract types are DERIVED from engine-types.ts, never re-spelled.
 //
 // THE LAW (the one that caught R-5): every predicate is derived from the ACTUAL
@@ -12,8 +12,9 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { itemCount, withCount } from "../../violation-count.js";
 /** The vendored-fixture basename used as the anchor file for every doc site. */
-export const STANDARD_FILE = "backend-standard-4bcd605.md";
+export const STANDARD_FILE = "backend-standard-2825122.md";
 /** The vendored standard at the pin — DATA on the same footing as the oracle CSV.
  * Resolved locally (not via coverage.ts) so this module carries no import cycle
  * with registry.ts. Same file coverage.ts's VENDORED_STANDARD_PATH points at. */
@@ -136,12 +137,12 @@ export function decideDoc(ruleId, id, check, scan, emptyReason) {
         .map((x) => `${STANDARD_FILE}:${x.n} (${x.note})`)
         .join("; ");
     if (nV > 0) {
-        return {
+        return withCount({
             id,
             anchor: `${STANDARD_FILE}:${scan.violate[0].n}`,
             state: "non-conforming",
             verdict: `${ruleId}: ${nV} STATIC violation(s) in the standard document (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform: ${fmt(scan.conform)}.` : ""}`,
-        };
+        }, itemCount(nV));
     }
     if (nJ > 0) {
         const reason = `${ruleId}: static half clean (${nC} conform); ${nJ} site(s) owe a human/gate verdict — ${fmt(scan.cnj)}. This is NOT a clean bill: GREEN is the gate half surfaced per site, not the detection running. ${breakdown}`;

package/dist/detectors/standard/r41-frontier.js

@@ -24,6 +24,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { itemCount, withCount } from "../../violation-count.js";
 import { readStandard, STANDARD_FILE, toLines } from "./_doc.js";
 /** prefix → { the sibling fixture basename, its recorded upstream blob hash }.
  * The blob hash is the PINS.txt record — a vendored document that cannot be
@@ -154,12 +155,12 @@ export function decideR41(r) {
         const deadList = r.dead
             .map((c) => `${c.id} (cited ${site(c)}) not defined in ${SIBLING[c.prefix].file}`)
             .join("; ");
-        return {
+        return withCount({
             id: R41_ID,
             anchor: site(r.dead[0]),
             state: "non-conforming",
             verdict: `R-41: ${r.dead.length} DEAD POINTER(S) — a cited frontier id resolves to no definition in its sibling (a dead pointer is a red, not a note). ${counts} Dead: ${deadList}. Cited: ${citedList}.`,
-        };
+        }, itemCount(r.dead.length));
     }
     return {
         id: R41_ID,

package/dist/detectors/standard/r46-returns-validator.d.ts

@@ -23,6 +23,14 @@ export interface DocValidatorMatch {
     /** 1-based line span of the enclosing export — where a projection reason lives. */
     exportStartLine: number;
     exportEndLine: number;
+    /** 1-based line spans of every SHARED CONSTANT the export's `returns:` resolved
+     * through to reach this object (`returns: externalOpenReturns` →
+     * `const externalOpenReturns = v.object({…})`). A `returns-projection:` reason
+     * written on that constant governs every export that uses it. */
+    constSpans: {
+        start: number;
+        end: number;
+    }[];
 }
 export declare function extractDocMatches(name: string, text: string): DocValidatorMatch[];
 export declare function projectionReason(rawLines: string[], startLine: number, endLine: number): string | undefined;

package/dist/detectors/standard/r46-returns-validator.js

@@ -37,6 +37,7 @@
 //      (non-conforming / could-not-judge / present / absent) — no fifth state,
 //      no second mechanism: the detector reads the tree the engine hands it.
 import * as ts from "typescript";
+import { siteCount, withCount } from "../../violation-count.js";
 /** The standard this detector is pinned against (the re-pinned instrument pin). */
 export const R46_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §16 R-46";
 // ---------------------------------------------------------------------------
@@ -160,17 +161,35 @@ export function extractDocMatches(name, text) {
     const matches = [];
     const lineOf = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
     const constMap = new Map();
+    const constSpan = new Map();
     function collectConsts(node) {
         if (ts.isVariableStatement(node)) {
             for (const decl of node.declarationList.declarations) {
                 if (ts.isIdentifier(decl.name) && decl.initializer) {
                     constMap.set(decl.name.text, decl.initializer);
+                    constSpan.set(decl.name.text, {
+                        start: lineOf(node.getStart(sf)),
+                        end: lineOf(node.getEnd()),
+                    });
                 }
             }
         }
         ts.forEachChild(node, collectConsts);
     }
     collectConsts(sf);
+    /** The span of every const an expression resolves THROUGH (the chain a
+     * `returns: X` takes to reach its validator). */
+    function constChain(expr) {
+        const out = [];
+        let cur = expr;
+        for (let d = 0; d <= 10 && ts.isIdentifier(cur) && constMap.has(cur.text); d++) {
+            const span = constSpan.get(cur.text);
+            if (span)
+                out.push(span);
+            cur = constMap.get(cur.text);
+        }
+        return out;
+    }
     function resolve(expr, depth = 0) {
         if (depth > 10)
             return expr;
@@ -179,10 +198,11 @@ export function extractDocMatches(name, text) {
         }
         return expr;
     }
-    function walkForDocObjects(expr, out, exportName, alias, span, depth = 0) {
+    function walkForDocObjects(expr, out, exportName, alias, span, depth = 0, consts = []) {
         if (depth > 20)
             return;
         const nextAlias = ts.isIdentifier(expr) ? expr.text : alias;
+        const chain = [...consts, ...constChain(expr)];
         const resolved = resolve(expr);
         if (ts.isCallExpression(resolved) &&
             ts.isPropertyAccessExpression(resolved.expression)) {
@@ -207,11 +227,12 @@ export function extractDocMatches(name, text) {
                             line: lineOf(objArg.getStart(sf)),
                             exportStartLine: span.start,
                             exportEndLine: span.end,
+                            constSpans: chain,
                         });
                     }
                     for (const prop of objArg.properties) {
                         if (ts.isPropertyAssignment(prop)) {
-                            walkForDocObjects(prop.initializer, out, exportName, undefined, span, depth + 1);
+                            walkForDocObjects(prop.initializer, out, exportName, undefined, span, depth + 1, chain);
                         }
                     }
                 }
@@ -219,7 +240,7 @@ export function extractDocMatches(name, text) {
             }
             if (method === "union" || method === "array" || method === "optional") {
                 for (const arg of resolved.arguments) {
-                    walkForDocObjects(arg, out, exportName, nextAlias, span, depth + 1);
+                    walkForDocObjects(arg, out, exportName, nextAlias, span, depth + 1, chain);
                 }
                 return;
             }
@@ -348,18 +369,29 @@ export function scanR46(files) {
             }
             // include the contiguous leading-comment block above the export — the
             // natural place a `returns-projection:` reason is written for the read path.
-            let leadStart = m.exportStartLine;
-            while (leadStart > 1) {
-                const prev = (rawLines[leadStart - 2] ?? "").trim();
-                if (prev.startsWith("//") ||
-                    prev.startsWith("*") ||
-                    prev.startsWith("/*")) {
-                    leadStart -= 1;
+            // The same holds for every SHARED CONSTANT the export's `returns:` resolves
+            // through: a reason written on `const externalOpenReturns = v.object(…)`
+            // is the author's written reason for every export that returns it. A
+            // reason on an UNRELATED const (one this export does not resolve through)
+            // governs nothing here.
+            const withLead = (start) => {
+                let lead = start;
+                while (lead > 1) {
+                    const prev = (rawLines[lead - 2] ?? "").trim();
+                    if (prev.startsWith("//") ||
+                        prev.startsWith("*") ||
+                        prev.startsWith("/*")) {
+                        lead -= 1;
+                    }
+                    else
+                        break;
                 }
-                else
-                    break;
-            }
-            const reason = projectionReason(rawLines, leadStart, m.exportEndLine);
+                return lead;
+            };
+            const reason = projectionReason(rawLines, withLead(m.exportStartLine), m.exportEndLine) ??
+                m.constSpans
+                    .map((c) => projectionReason(rawLines, withLead(c.start), c.end))
+                    .find((r) => r !== undefined);
             if (reason) {
                 inventory.push({
                     rel: f.rel,
@@ -425,12 +457,12 @@ export function decideR46(cov) {
     }
     if (missing.length > 0) {
         const first = missing[0];
-        return {
+        return withCount({
             id: R46_ID,
             anchor: `${first.rel}:${first.line}`,
             state: "non-conforming",
             verdict: `R-46: ${missing.length} returns validator(s) enumerate a stored document but OMIT a schema-declared field with NO written projection reason (${R46_CHECK}). ${breakdown}\n=== coverage inventory ===\n${inventory}\n=== end inventory ===`,
-        };
+        }, siteCount(missing));
     }
     if (cov.findings.length > 0) {
         const first = cov.findings[0];

package/dist/detectors/structural.d.ts

@@ -1,14 +1,13 @@
 import type { Detector } from "../engine-types.js";
-import { type OracleRow } from "../oracle.js";
+import { type OracleRow, type WriterTierTable } from "../oracle.js";
 /**
  * R-14 — inventory-schema parity, contract → inventory, one direction.
  * A merged reader/writer authority column is "non-conforming by construction"
- * (§12). The oracle's column 9 `rbac_qui` is that single merged column.
+ * (§12). Writer authority is a separate column only when the side-car declares it.
  */
-export declare function makeR14(columns?: readonly string[]): Detector;
+export declare function makeR14(columns?: readonly string[], rowsProvider?: () => OracleRow[], sideCar?: () => WriterTierTable): Detector;
 /**
- * R-38 — the completeness gate over the thirteen §2 fields. The oracle cannot
- * satisfy the contract because reader and writer authority are not two separate
- * fields (both map to `rbac_qui`).
+ * R-38 — the completeness gate over the thirteen §2 fields. Writer authority is
+ * complete only when the side-car records a tier for every write tool.
  */
-export declare function makeR38(columns?: readonly string[], rowsProvider?: () => OracleRow[]): Detector;
+export declare function makeR38(columns?: readonly string[], rowsProvider?: () => OracleRow[], sideCar?: () => WriterTierTable): Detector;