@vantageos/backend-doctor 0.2.0 → 0.4.0

package/dist/detectors/source/service-account-claim.js

@@ -0,0 +1,491 @@
+// R-54 — a door the fleet service account can reach acts only inside an
+// organisation the transport verified for this call; a call that carries no
+// verified claim is refused, never served as master.
+//
+// Standard bacc54a §4 R-54 and its Detector spec, read literally:
+//   red (A)  a public door that resolves its caller through the organisation-scope
+//            resolver (so the service account resolves to master) and declares no
+//            claim argument (verifiedActor / verifiedOrg / verifiedPerson);
+//   red (B)  a door that declares a claim argument but has no refusal for the
+//            claimless service-account call: its claim is optional, and the absence
+//            of the claim leaves the call master;
+//   green    a claim argument together with a refusal for the claimless
+//            service-account call, or one of three listed exits:
+//              (a) service-account-only by purpose (requireServiceAccount, or
+//                  requireResolvedCaller with masterOnly AND mcpBoundOnly);
+//              (b) not reachable by the service account: the callers resolve only
+//                  through a verified session (requireOrgAdmin and its siblings, or
+//                  a bare getUserIdentity read) and the door never reaches the
+//                  organisation-scope resolver;
+//              (c) `fleet-wide: <reason of eight characters or more>` in the door's
+//                  source, stating why a whole-fleet reach is its purpose;
+//   could-not-judge  an action whose scope arrives through a run call, a
+//            resolver-shaped callee defined outside the scanned tree, a claim
+//            argument spread from a validator the scan cannot find, and a door
+//            registered through a wrapper whose context is not read here. Never a
+//            readable door.
+//
+// WHAT A REFUSAL IS. A `throw` (or a `return` of an object that says it refuses)
+// whose PATH CONDITION holds both the service-account state and the claim's
+// absence: every enclosing `if` of the throw contributes its condition (its
+// negation for an `else`), split on `&&` (on `||` for a negation). The atoms are
+// read by shape, not by spelling:
+//   service-account state   `scope.isMaster`, `isMcpBoundMaster(scope)`,
+//                           `scope.masterSource === "service-account"`, a
+//                           `serviceAccount`-named value;
+//   claim absence           `X === undefined`, `X == null`, `!X`, `typeof X ===
+//                           "undefined"` — or the negation of `X !== undefined`,
+//                           `X != null`, `X` — where X is CLAIM-DERIVED: it names
+//                           verifiedActor / verifiedOrg / verifiedPerson, a
+//                           parameter called `claim` or `verified*`, or a local
+//                           initialised from a claim-derived value (to a fixpoint).
+// A path that also requires the caller NOT to be the service account (`!isMaster`)
+// refuses the other population, so it is not a claimless-service-account refusal.
+// A claim that is mandatory for every caller (absence alone refuses) is bound.
+//
+// WHAT IS NOT READ. R-54 clause 2 (the claim confines every row the door reads or
+// writes) is not decided here: which rows a handler touches, and against which
+// tenant, is R-6 / R-52 / R-53 clause 2 (the target check). This detector decides
+// that a verified claim exists to confine to, and that its absence is refused.
+import * as ts from "typescript";
+import { calledNames, indexFunctions, lineOf, parseFile, registrations, unwrap, walk, } from "./_ast.js";
+import { decide, emptyScan, isJudgeable, } from "./_scan.js";
+export const R54_ID = "R-54 a door the service account can reach acts inside a transport-verified organisation; a claimless call is refused, never served as master";
+const R54_CHECK = "a door resolving its caller through the organisation-scope resolver declares a verified-claim argument and refuses the call that is the service account and carries no claim, or is service-account-only, session-only, or declared fleet-wide";
+export const R54_STANDARD_PIN = "vantagepeers/backend-standard/backend-standard.md @ bacc54a53d5f6f9f20e5254908e2b46807902faa §4 R-54";
+const CLAIMS = ["verifiedActor", "verifiedOrg", "verifiedPerson"];
+const PUBLIC_BUILDERS = new Set([
+    "query",
+    "mutation",
+    "action",
+]);
+const SCOPE_RESOLVER = "withOrgScope";
+/** `fleet-wide: <reason>` — the reason must be a real sentence, not a token. */
+export const FLEET_WIDE_MARKER = /fleet-wide:\s*(\S[^\n]{7,})/;
+/** A callee name that looks like it resolves a caller / scope. */
+const RESOLVER_SHAPED = /^(require|resolve|get|with|assert|check)[A-Za-z]*(Scope|Caller|Principal|Identity|Reader|Actor|Auth)[A-Za-z]*$/;
+/** Session-only gates: the caller is a verified session, never the service account. */
+const SESSION_GATES = new Set([
+    "requireOrgAdmin",
+    "requireOperatorAdminToCreateOrg",
+    "resolveOperatorAdmin",
+]);
+const SERVICE_STATE = /\bisMaster\b|\bisMcpBoundMaster\b|masterSource\s*===?\s*["']service-account["']|\bisServiceAccount\b|serviceAccount/i;
+const REFUSAL_RETURN = /refus|denied|unauthori[sz]ed|RBAC/i;
+// ---- args ------------------------------------------------------------------
+/** Top-level `const NAME = { … }` / `v.object({ … })` initialiser text, tree-wide. */
+function topLevelConsts(ps) {
+    const m = new Map();
+    for (const p of ps)
+        for (const st of p.sf.statements)
+            if (ts.isVariableStatement(st))
+                for (const d of st.declarationList.declarations)
+                    if (ts.isIdentifier(d.name) && d.initializer)
+                        m.set(d.name.text, d.initializer.getText(p.sf));
+    return m;
+}
+/** The registration's config object literal (`{ args, handler, … }`). */
+function configOf(r) {
+    for (let x = r.handler.parent; x; x = x.parent)
+        if (ts.isObjectLiteralExpression(x))
+            return x;
+    return undefined;
+}
+function readArgs(r, p, consts) {
+    const out = { claims: [], unresolved: [] };
+    const cfg = configOf(r);
+    const prop = cfg?.properties.find((x) => x.name && ts.isIdentifier(x.name) && x.name.text === "args");
+    if (!prop || !ts.isPropertyAssignment(prop))
+        return out;
+    const seen = new Set();
+    const visit = (text, depth) => {
+        for (const c of CLAIMS)
+            if (new RegExp(`\\b${c}\\s*:`).test(text) && !out.claims.includes(c))
+                out.claims.push(c);
+        for (const m of text.matchAll(/\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+            const n = m[1];
+            if (seen.has(n))
+                continue;
+            seen.add(n);
+            const body = consts.get(n);
+            if (body !== undefined && depth < 4)
+                visit(body, depth + 1);
+            else
+                out.unresolved.push(n);
+        }
+    };
+    const init = unwrap(prop.initializer);
+    if (ts.isIdentifier(init)) {
+        const body = consts.get(init.text);
+        if (body === undefined)
+            out.unresolved.push(init.text);
+        else
+            visit(body, 1);
+    }
+    else
+        visit(init.getText(p.sf), 0);
+    return out;
+}
+function closureOf(handler, idx) {
+    const nodes = [handler];
+    const calls = new Set();
+    const undefinedCalls = new Set();
+    const seen = new Set();
+    const queue = [handler];
+    while (queue.length) {
+        const n = queue.pop();
+        for (const c of calledNames(n)) {
+            calls.add(c);
+            if (seen.has(c))
+                continue;
+            seen.add(c);
+            const defs = idx.get(c);
+            if (defs === undefined) {
+                undefinedCalls.add(c);
+                continue;
+            }
+            for (const d of defs) {
+                nodes.push(d.fn);
+                queue.push(d.fn);
+            }
+        }
+    }
+    return { nodes, calls, undefinedCalls };
+}
+// ---- claim refusal -----------------------------------------------------------
+const isClaimName = (n) => /^verified(Actor|Org|Person)$/.test(n) || /^(claim|verified\w*)$/i.test(n);
+/** A callee that turns a claim into a value which is undefined exactly when the
+ * claim is absent (`resolveVerifiedOrg`, `resolveDoorVerifiedOrg`). A resolver
+ * that returns a SCOPE whatever the claim (`resolveVerifiedPerson` hands back the
+ * transport scope when no person is carried) is not one: its result is never
+ * undefined, so testing it says nothing about the claim. */
+const CLAIM_RESOLVER = /^resolve(Door)?Verified(Org|Actor)$|Claim$/;
+/** Is `e` the claim itself, or a value that is undefined exactly when the claim
+ * is absent? The claim; a property / element chain on it; a ternary, `??`, `||`
+ * or `&&` with a claim-derived operand; a claim resolver called on it. A value
+ * merely COMPUTED FROM the claim (a row read by its agent ID) is not: its absence
+ * is not the claim's absence. */
+function isClaimValue(e, tainted) {
+    const x = unwrap(e);
+    if (ts.isIdentifier(x))
+        return tainted.has(x.text) || isClaimName(x.text);
+    if (ts.isPropertyAccessExpression(x))
+        return (/^verified(Actor|Org|Person)$/.test(x.name.text) ||
+            isClaimValue(x.expression, tainted));
+    if (ts.isElementAccessExpression(x))
+        return isClaimValue(x.expression, tainted);
+    if (ts.isConditionalExpression(x))
+        return (isClaimValue(x.whenTrue, tainted) || isClaimValue(x.whenFalse, tainted));
+    if (ts.isBinaryExpression(x)) {
+        const op = x.operatorToken.kind;
+        if (op === ts.SyntaxKind.QuestionQuestionToken ||
+            op === ts.SyntaxKind.BarBarToken ||
+            op === ts.SyntaxKind.AmpersandAmpersandToken)
+            return isClaimValue(x.left, tainted) || isClaimValue(x.right, tainted);
+        return false;
+    }
+    if (ts.isCallExpression(x)) {
+        const callee = unwrap(x.expression);
+        const name = ts.isIdentifier(callee)
+            ? callee.text
+            : ts.isPropertyAccessExpression(callee)
+                ? callee.name.text
+                : undefined;
+        return (name !== undefined &&
+            CLAIM_RESOLVER.test(name) &&
+            x.arguments.some((a) => isClaimValue(a, tainted)));
+    }
+    return false;
+}
+function claimDerivedLocals(fn) {
+    const tainted = new Set();
+    if (ts.isFunctionLike(fn) &&
+        "parameters" in fn &&
+        Array.isArray(fn.parameters))
+        for (const prm of fn.parameters)
+            if (ts.isIdentifier(prm.name) && isClaimName(prm.name.text))
+                tainted.add(prm.name.text);
+    for (let pass = 0; pass < 4; pass++) {
+        let grew = false;
+        walk(fn, (x) => {
+            if (!ts.isVariableDeclaration(x) || !x.initializer)
+                return;
+            const names = [];
+            if (ts.isIdentifier(x.name))
+                names.push(x.name.text);
+            else if (ts.isObjectBindingPattern(x.name))
+                for (const e of x.name.elements)
+                    if (ts.isIdentifier(e.name))
+                        names.push(e.name.text);
+            const fromDestructure = ts.isObjectBindingPattern(x.name) &&
+                x.name.elements.some((e) => ts.isIdentifier(e.name) &&
+                    /^verified(Actor|Org|Person)$/.test(e.name.text));
+            if (fromDestructure || isClaimValue(x.initializer, tainted))
+                for (const n of names)
+                    if (!tainted.has(n)) {
+                        tainted.add(n);
+                        grew = true;
+                    }
+        });
+        if (!grew)
+            break;
+    }
+    return tainted;
+}
+/** Classify ONE atom that holds with truth value `holds` in the path. */
+function classify(atom, holds, claimDerived) {
+    const a = unwrap(atom);
+    if (ts.isPrefixUnaryExpression(a) &&
+        a.operator === ts.SyntaxKind.ExclamationToken)
+        return classify(a.operand, !holds, claimDerived);
+    if (ts.isBinaryExpression(a)) {
+        const op = a.operatorToken.kind;
+        const eq = op === ts.SyntaxKind.EqualsEqualsEqualsToken ||
+            op === ts.SyntaxKind.EqualsEqualsToken;
+        const ne = op === ts.SyntaxKind.ExclamationEqualsEqualsToken ||
+            op === ts.SyntaxKind.ExclamationEqualsToken;
+        if (eq || ne) {
+            const l = unwrap(a.left);
+            const r = unwrap(a.right);
+            const nullish = (e) => (ts.isIdentifier(e) && e.text === "undefined") ||
+                e.kind === ts.SyntaxKind.NullKeyword;
+            const bool = (e) => e.kind === ts.SyntaxKind.TrueKeyword
+                ? true
+                : e.kind === ts.SyntaxKind.FalseKeyword
+                    ? false
+                    : undefined;
+            if (bool(r) !== undefined || bool(l) !== undefined) {
+                const lit = (bool(r) ?? bool(l));
+                const subject = bool(r) !== undefined ? l : r;
+                return classify(subject, (eq ? holds : !holds) === lit, claimDerived);
+            }
+            if (nullish(r) || nullish(l)) {
+                const subject = nullish(r) ? l : r;
+                if (claimDerived(subject)) {
+                    // X === undefined holds => absent; X !== undefined holds => present
+                    const absent = eq ? holds : !holds;
+                    return absent ? "claim-absent" : "claim-present";
+                }
+            }
+            if (ts.isPropertyAccessExpression(l) &&
+                l.name.text === "masterSource" &&
+                ts.isStringLiteralLike(r) &&
+                r.text === "service-account") {
+                const is = eq ? holds : !holds;
+                return is ? "service" : "not-service";
+            }
+        }
+        return "other";
+    }
+    const text = a.getText();
+    if (claimDerived(a))
+        return holds ? "claim-present" : "claim-absent";
+    if (SERVICE_STATE.test(text))
+        return holds ? "service" : "not-service";
+    return "other";
+}
+/** Split `e` into the atoms that ALL hold when `e` is true (&&) or when it is
+ * false (||); anything else is one opaque atom. */
+function atomsOf(e, holds) {
+    const x = unwrap(e);
+    if (ts.isBinaryExpression(x)) {
+        const op = x.operatorToken.kind;
+        if (holds && op === ts.SyntaxKind.AmpersandAmpersandToken)
+            return [...atomsOf(x.left, true), ...atomsOf(x.right, true)];
+        if (!holds && op === ts.SyntaxKind.BarBarToken)
+            return [...atomsOf(x.left, false), ...atomsOf(x.right, false)];
+    }
+    if (ts.isPrefixUnaryExpression(x) &&
+        x.operator === ts.SyntaxKind.ExclamationToken)
+        return atomsOf(x.operand, !holds);
+    return [{ atom: x, holds }];
+}
+function pathFacts(t, fn, claimDerived) {
+    const facts = new Set();
+    for (let child = t, up = t.parent; up && child !== fn; child = up, up = up.parent) {
+        if (ts.isIfStatement(up)) {
+            const inThen = up.thenStatement === child;
+            const inElse = up.elseStatement === child;
+            if (!inThen && !inElse)
+                continue;
+            for (const { atom, holds } of atomsOf(up.expression, inThen))
+                facts.add(classify(atom, holds, claimDerived));
+        }
+    }
+    return facts;
+}
+function refusesClaimless(closure) {
+    for (const fn of closure.nodes) {
+        const tainted = claimDerivedLocals(fn);
+        const claimDerived = (e) => isClaimValue(e, tainted);
+        let found = false;
+        walk(fn, (x) => {
+            if (found)
+                return;
+            const refusal = ts.isThrowStatement(x) ||
+                (ts.isReturnStatement(x) &&
+                    x.expression !== undefined &&
+                    REFUSAL_RETURN.test(x.expression.getText()));
+            if (!refusal)
+                return;
+            const facts = pathFacts(x, fn, claimDerived);
+            // The path must say "no claim", optionally "and the caller is the service
+            // account", and nothing else: a refusal that also needs some other
+            // condition (a flag, a name, a present claim) refuses a narrower call.
+            if (!facts.has("claim-absent"))
+                return;
+            for (const f of facts)
+                if (f !== "claim-absent" && f !== "service")
+                    return;
+            found = true;
+        });
+        if (found)
+            return true;
+    }
+    return false;
+}
+const isConvexFile = (f) => /(^|\/)convex\//.test(f.rel);
+function statementOf(n) {
+    let x = n;
+    while (x.parent && !ts.isSourceFile(x.parent))
+        x = x.parent;
+    return x;
+}
+export function scanR54(files) {
+    const scan = emptyScan();
+    scan.notApplicable = [];
+    scan.doors = 0;
+    const ps = files
+        .filter((f) => isJudgeable(f) && isConvexFile(f))
+        .map(parseFile);
+    const idx = indexFunctions(ps);
+    const consts = topLevelConsts(ps);
+    for (const p of ps) {
+        for (const r of registrations(p)) {
+            if (!PUBLIC_BUILDERS.has(r.builder))
+                continue;
+            scan.doors++;
+            const site = (note) => ({
+                rel: r.rel,
+                n: r.line,
+                note: `${r.name}: ${note}`,
+            });
+            const stmt = statementOf(r.handler);
+            const fullText = p.sf.text.slice(stmt.getFullStart(), stmt.getEnd());
+            const closure = closureOf(r.handler, idx);
+            const args = readArgs(r, p, consts);
+            const marker = FLEET_WIDE_MARKER.exec(fullText);
+            if (marker) {
+                scan.conform.push(site(`exit (c): declared fleet-wide — ${marker[1].trim().slice(0, 160)}`));
+                continue;
+            }
+            const serviceOnly = closure.calls.has("requireServiceAccount") ||
+                closureHasMasterOnlyResolved(closure);
+            if (serviceOnly) {
+                scan.conform.push(site("exit (a): service-account-only by purpose (requireServiceAccount / requireResolvedCaller masterOnly+mcpBoundOnly)"));
+                continue;
+            }
+            const reaches = closure.calls.has(SCOPE_RESOLVER);
+            if (!reaches) {
+                const session = [...closure.calls].some((c) => SESSION_GATES.has(c)) ||
+                    closureReadsIdentity(closure);
+                if (session) {
+                    scan.conform.push(site("exit (b): callers resolve only through a verified session; the door never reaches the organisation-scope resolver"));
+                    continue;
+                }
+                if (r.builder === "action" && closureCallsRun(closure)) {
+                    scan.cnj.push(site("caller scope arrives through a run call (ctx.runQuery / ctx.runMutation); its resolution is not read here"));
+                    continue;
+                }
+                const foreign = [...closure.undefinedCalls].filter((c) => RESOLVER_SHAPED.test(c));
+                if (foreign.length) {
+                    scan.cnj.push(site(`caller resolution delegated to ${foreign.join(", ")}, defined outside the scanned tree`));
+                    continue;
+                }
+                scan.notApplicable.push(`${r.rel}:${r.name}`);
+                continue;
+            }
+            // The door reaches the scope resolver: the service account is master here.
+            if (args.claims.length === 0) {
+                if (args.unresolved.length) {
+                    scan.cnj.push(site(`args spread from ${args.unresolved.join(", ")}, which the scan cannot find; a claim argument may be among them`));
+                    continue;
+                }
+                scan.violate.push(site("(A) resolves its caller through the organisation-scope resolver (the service account is master here) and declares no claim argument (verifiedActor / verifiedOrg / verifiedPerson)"));
+                continue;
+            }
+            if (refusesClaimless(closure)) {
+                scan.conform.push(site(`claim-bound: accepts ${args.claims.join(", ")} and refuses the claimless service-account call`));
+                continue;
+            }
+            scan.violate.push(site(`(B) the claim is optional: accepts ${args.claims.join(", ")} but no branch refuses the claimless service-account call, so the absence of a claim leaves the call master`));
+        }
+        // A door registered through a wrapper is not read: say so, never skip it.
+        for (const st of p.sf.statements) {
+            if (!ts.isVariableStatement(st))
+                continue;
+            for (const d of st.declarationList.declarations) {
+                if (!d.initializer || !ts.isIdentifier(d.name))
+                    continue;
+                const init = unwrap(d.initializer);
+                if (!ts.isCallExpression(init))
+                    continue;
+                const callee = init.expression;
+                if (!ts.isIdentifier(callee))
+                    continue;
+                if (/^(query|mutation|action|internal\w+|httpAction)$/.test(callee.text))
+                    continue;
+                const cfg = init.arguments[0];
+                if (!cfg || !ts.isObjectLiteralExpression(cfg))
+                    continue;
+                const hasHandler = cfg.properties.some((x) => x.name && ts.isIdentifier(x.name) && x.name.text === "handler");
+                if (!hasHandler)
+                    continue;
+                scan.cnj.push({
+                    rel: p.rel,
+                    n: lineOf(d),
+                    note: `${d.name.text}: registered through the wrapper ${callee.text}; the caller resolution lives in the wrapper's context, which is not read here`,
+                });
+            }
+        }
+    }
+    return scan;
+}
+/** `ctx.runQuery(...)` / `ctx.runMutation(...)` are method calls, which
+ * calledNames (plain identifiers only) does not see. */
+function closureCallsRun(c) {
+    return c.nodes.some((n) => /\.run(Query|Mutation)\s*\(/.test(n.getText()));
+}
+/** `ctx.auth.getUserIdentity()` is a method call; calledNames sees plain
+ * identifiers only, so read the closure's text for the identity read. */
+function closureReadsIdentity(c) {
+    return c.nodes.some((n) => /\.getUserIdentity\s*\(/.test(n.getText()));
+}
+function closureHasMasterOnlyResolved(c) {
+    for (const n of c.nodes) {
+        let hit = false;
+        walk(n, (x) => {
+            if (ts.isCallExpression(x) &&
+                ts.isIdentifier(unwrap(x.expression)) &&
+                unwrap(x.expression).text === "requireResolvedCaller") {
+                const t = x.arguments.map((a) => a.getText()).join(",");
+                if (/masterOnly/.test(t) && /mcpBoundOnly/.test(t))
+                    hit = true;
+            }
+        });
+        if (hit)
+            return true;
+    }
+    return false;
+}
+export const R54 = {
+    id: R54_ID,
+    run: (tree) => {
+        const s = scanR54(tree.files);
+        const empty = `R-54: no applicable site — ${s.doors} public door(s) read in ${tree.files.filter((f) => isJudgeable(f) && isConvexFile(f)).length} convex file(s); ${s.notApplicable.length} resolve no caller at all (CR-1 / R-6 govern them) and none reaches the organisation-scope resolver or an exit. NOT a clean bill.`;
+        return decide("R-54", R54_ID, R54_CHECK, s, empty);
+    },
+};
+export const SOURCE_SERVICE_ACCOUNT_CLAIM_DETECTORS = [
+    { detector: R54, ruleId: "R-54", standardPin: R54_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-bacc54a.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-bacc54a.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-bacc54a.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.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";
 // ---------------------------------------------------------------------------
@@ -456,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];