@vantageos/backend-doctor 0.2.0 → 0.3.0

package/dist/detectors/source/identity.d.ts

@@ -60,7 +60,14 @@ export interface LocalTaint {
  * RHS (`const t = orgSlug`) is NOT scope evidence on its own — the identifier's
  * own provenance is resolved one further, bounded, cycle-guarded hop (defect 3);
  * exhaustion is `cnj`, never a guess. */
-export declare function analyzeLocalTaint(h: Handler, local: string, isResolver?: (name: string) => boolean): LocalTaint;
+export declare function analyzeLocalTaint(h: Handler, local: string, isResolver?: ResolverTest, principalOf?: PrincipalTest): LocalTaint;
+/** Is `expr` the principal @vantageos/cloud-identity resolved and the door
+ * refused unless ok (package-principal.ts)? Returns the reason, else undefined. */
+export type PrincipalTest = (expr: string) => string | undefined;
+/** Is `name` an identity resolver? `call` is the whole `await name(…)` text,
+ * joined across the lines it spans, so a resolver anchored on one of its call
+ * arguments can read that argument. */
+export type ResolverTest = (name: string, call: string) => boolean;
 export declare const R6_GUARD_HELPERS: Readonly<Record<string, GuardHelperKind>>;
 interface HelperDef {
     rel: string;

package/dist/detectors/source/identity.js

@@ -1,4 +1,9 @@
-import { conditionalBoundaries, findHelperDefinitions, judgePredicateFunction, judgeResolverFunction, readHandlerGuards, summarizeValidator, topLevelFunctions, topLevelHelperCalls, } from "./guard-helper-flow.js";
+import { itemCount, siteCount, withCount } from "../../violation-count.js";
+import { parseFile } from "./_ast.js";
+import { conditionalBoundaries, findHelperDefinitions, judgePredicateFunction, judgeResolverFunction, readHandlerGuards, SCOPE_REFINERS, summarizeValidator, topLevelFunctions, topLevelHelperCalls, } from "./guard-helper-flow.js";
+import { IDENTITY_PACKAGE } from "./identity-by-id.js";
+import { packagePrincipals, } from "./package-principal.js";
+import { masterOnlyWrapperCredit, possessionGatedCredit } from "./r6-shapes.js";
 /** The standard both are pinned against (short hash a9d7877b), §15/§18. */
 export const IDENTITY_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15/§18";
 function emptyScan() {
@@ -63,12 +68,12 @@ function decide(ruleId, id, check, scan, emptyReason) {
         .map((x) => `${x.rel}:${x.n} (${x.note})`)
         .join("; ");
     if (nV > 0) {
-        return {
+        return withCount({
             id,
             anchor: `${scan.violate[0].rel}:${scan.violate[0].n}`,
             state: "non-conforming",
             verdict: `${ruleId}: ${nV} site(s) VIOLATE (${check}). ${breakdown} Violations: ${fmt(scan.violate)}.${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`,
-        };
+        }, siteCount(scan.violate));
     }
     if (nJ > 0) {
         const reason = `${ruleId}: ${nJ} site(s) could not be judged — ${fmt(scan.cnj)}. This is NOT a clean bill. ${breakdown}`;
@@ -147,7 +152,6 @@ export function splitMutationHandlers(f) {
 const R6_WRITE = /ctx\.db\.(?:insert|patch|replace|delete)\s*\(/;
 const R6_IDENTITY_GUARD = /getUserIdentity|resolveOrgId|resolveOrgContext|assertNamespaceAllowed|expectedOrgIdForNamespace|tenantSlug|organizationId|organizationSlug|AUTH_NO_ORG|AUTH_NAMESPACE_DENIED/;
 const R6_RESOURCE_GUARD = /assertTaskCallerAuthorized|RBAC_DENIED|\.createdBy\s*===|\.assignedTo\s*===|\.orchestratorId\s*===|callerOrchestrator\s*===\s*["']system["']|note\.createdBy/;
-const R6_BOUNDARY_ARG = /\b(?:createdBy|orgId|orgSlug|namespace|orchestratorId|ownerId|tenantId)\b/;
 // ---- WRITE-SITE provenance (blind spot 2) ---------------------------------
 //
 // Guard-PRESENCE alone cannot distinguish the historical tenant-write defect
@@ -288,8 +292,21 @@ function destructuredRhs(raw, local) {
  * RHS (`const t = orgSlug`) is NOT scope evidence on its own — the identifier's
  * own provenance is resolved one further, bounded, cycle-guarded hop (defect 3);
  * exhaustion is `cnj`, never a guess. */
-export function analyzeLocalTaint(h, local, isResolver) {
-    return analyzeLocalTaintInner({ ...h, lines: normalizeLines(h.lines) }, local, 0, new Set(), isResolver);
+export function analyzeLocalTaint(h, local, isResolver, principalOf) {
+    return analyzeLocalTaintInner({ ...h, lines: normalizeLines(h.lines) }, local, 0, new Set(), isResolver, principalOf);
+}
+/** The RHS starting on `codeLines[i]`, extended over the following lines until
+ * an opening `await <name>(` is balanced (bounded; unbalanced -> the line alone).
+ * Used ONLY to recognise a resolver call that spans lines — never to widen the
+ * scope test of an ordinary RHS. */
+function joinedAwaitedCall(rhs, codeLines, i) {
+    if (!/^\s*await\s+[A-Za-z_$][\w$]*\s*\(/.test(rhs))
+        return rhs;
+    let text = rhs;
+    const depthOf = (t) => (t.match(/\(/g) ?? []).length - (t.match(/\)/g) ?? []).length;
+    for (let j = i + 1; depthOf(text) > 0 && j < codeLines.length && j <= i + 40; j++)
+        text += `\n${codeLines[j].raw}`;
+    return depthOf(text) > 0 ? rhs : text;
 }
 /** `rhs` is exactly `await <name>(…)` closed on this line (nothing after the
  * call but `;`): the whole value is that function's return. */
@@ -310,7 +327,11 @@ function wholeAwaitedCall(rhs) {
     }
     return null;
 }
-function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
+function analyzeLocalTaintInner(h, local, depth, visited, isResolver, principalOf) {
+    // `local` IS an alias of a checked package principal (`const { principal }
+    // = who` after `if (!who.ok) throw`): the verified identity under a name.
+    if (principalOf?.(local))
+        return { fromArgs: 0, fromScope: 1, matched: 1, cnj: 0, fromResolver: 1 };
     let fromArgs = 0;
     let fromScope = 0;
     let matched = 0;
@@ -319,7 +340,7 @@ function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
     const esc = local.replace(/[$]/g, "\\$&");
     const assign = new RegExp(`(?:^|[^\\w.$])${esc}\\s*(?::[^=\\n]*)?=(?!=)`);
     const decl = new RegExp(`\\b(?:const|let|var)\\s+${esc}\\b`);
-    const classify = (rhs) => {
+    const classify = (rhs, call = rhs) => {
         // A BARE IDENTIFIER RHS carries no scope evidence on its own — its NAME
         // (even `orgSlug`) never counts as scope; the identifier's own provenance
         // decides, or the scan refuses (defect 3, Eta pole 2).
@@ -334,7 +355,7 @@ function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
             }
             const next = new Set(visited);
             next.add(local);
-            const sub = analyzeLocalTaintInner(h, bare, depth + 1, next, isResolver);
+            const sub = analyzeLocalTaintInner(h, bare, depth + 1, next, isResolver, principalOf);
             if (sub.matched === 0)
                 cnj++; // the referenced local has no resolvable assignment.
             else if (sub.fromScope > 0 && sub.fromArgs === 0)
@@ -348,8 +369,14 @@ function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
         // The whole value is the return of a function the tree shows to be an
         // identity RESOLVER (it returns the verified scope itself and refuses an
         // absent identity first): scope-derived, whatever arguments it was handed.
-        const called = isResolver ? wholeAwaitedCall(rhs) : null;
-        if (called && isResolver?.(called)) {
+        const called = isResolver ? wholeAwaitedCall(call) : null;
+        if (called && isResolver?.(called, call)) {
+            fromScope++;
+            fromResolver++;
+            return;
+        }
+        // A member read of a checked package principal (`who.principal.orgId`).
+        if (principalOf?.(rhs)) {
             fromScope++;
             fromResolver++;
             return;
@@ -367,10 +394,9 @@ function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
         else
             fromArgs++;
     };
-    for (const l of h.lines) {
-        if (!code(l))
-            continue;
-        const raw = l.raw;
+    const codeLines = h.lines.filter(code);
+    for (let i = 0; i < codeLines.length; i++) {
+        const raw = codeLines[i].raw;
         // The handler's own parameter destructured — the binding IS the argument.
         if (boundFromHandlerParam(raw, local)) {
             matched++;
@@ -390,7 +416,7 @@ function analyzeLocalTaintInner(h, local, depth, visited, isResolver) {
             continue;
         matched++;
         const rhs = isAssign ? raw.slice(raw.indexOf("=") + 1) : "";
-        classify(rhs);
+        classify(rhs, joinedAwaitedCall(rhs, codeLines, i));
     }
     return fromResolver > 0
         ? { fromArgs, fromScope, matched, cnj, fromResolver }
@@ -459,6 +485,50 @@ export const R6_GUARD_HELPERS = {
     requireFleetMaster: "master-only",
     requireServiceAccount: "master-only",
 };
+// ---- SCOPE REFINERS at the handler (a local assigned from one) ------------
+//
+// `const scope = await resolveVerifiedPerson(ctx, transportScope, args.verifiedPerson, …)`
+// read as caller-arg-derived (fromScope=0) because an argument is handed to the
+// call — the false R-6 accusation at vantage-peers 45e40c8 missions.ts:232. A
+// SCOPE_REFINERS call (guard-helper-flow.ts) is scope-derived when its
+// definition is READABLE in the scanned tree and the scope it is handed, at
+// `argIndex`, is itself a scope-derived local. Its other arguments never taint
+// its return. (A resolver such as `requireAuthenticatedCaller` stays judged on
+// its BODY by judgeResolverFunction, which now reads a refiner of a pure scope
+// as pure — recurringTasks.ts:216.)
+/** Top-level comma-separated arguments of the first `name(…)` call in `call`. */
+function callArguments(call, name) {
+    const at = call.search(new RegExp(`\\b${name}\\s*\\(`));
+    if (at === -1)
+        return null;
+    const open = call.indexOf("(", at);
+    const out = [];
+    let depth = 0;
+    let cur = "";
+    for (let i = open; i < call.length; i++) {
+        const ch = call[i];
+        if ("([{".includes(ch)) {
+            depth++;
+            if (depth === 1)
+                continue;
+        }
+        else if (")]}".includes(ch)) {
+            depth--;
+            if (depth === 0) {
+                if (cur.trim())
+                    out.push(cur.trim());
+                return out;
+            }
+        }
+        else if (ch === "," && depth === 1) {
+            out.push(cur.trim());
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    return null;
+}
 const sourceOf = (f) => f.lines.map((l) => l.raw).join("\n");
 /** Index every definition of an allowlisted helper in the tree. */
 export function indexGuardHelpers(files) {
@@ -712,6 +782,176 @@ function boundaryMemberRhs(writes, loc) {
     }
     return out.length ? out : null;
 }
+// ---- WHICH boundary field reaches a write from an ARGUMENT -----------------
+//
+// The last-resort accusation ("a boundary field taken from a caller argument
+// with no identity/resource guard") used to fire on ANY handler line carrying a
+// boundary token. vantage-peers 45e40c8 tasks.complete was accused for
+// `createdBy: fixPatternCreatedBy` where `fixPatternCreatedBy = task.assignedTo`
+// and `task = await ctx.db.get(args.taskId)` — a value read off the TARGET
+// resource, server-side, never the caller's argument. The accusation now needs
+// the boundary field's value, AT A WRITE, to come from the caller's arguments:
+//   - `field: args.x` directly, or a local whose assignments read `args` (one
+//     hop through renames, member reads and destructuring, bounded);
+//   - a local object handed to the write (`patch(id, obj)`) carrying the field
+//     in its literal or through `obj.field = …`;
+//   - `args` (or a rest/alias of it) spread or passed whole, when the args
+//     validator declares a boundary field the write does not override.
+// NOT the argument: a value read from the database (`ctx.db.get`/`.query`),
+// the return of an identity resolver, or anything with no `args` in its
+// provenance (`lastActedBy`, a server-computed actor). A local whose assignment
+// cannot be found stays an argument (the old, conservative reading).
+const R6_BOUNDARY_FIELD = "(?:createdBy|orgId|orgSlug|namespace|orchestratorId|ownerId|tenantId)";
+function boundaryFromArgument(h, writes, isResolver, principalOf) {
+    const codeLines = h.lines.filter(code);
+    const handlerAt = codeLines.findIndex((l) => /\bhandler\b/.test(l.raw));
+    const validator = codeLines
+        .slice(0, handlerAt === -1 ? 0 : handlerAt)
+        .map((l) => l.raw)
+        .join("\n");
+    const validatorFields = new Set([
+        ...validator.matchAll(new RegExp(`\\b(${R6_BOUNDARY_FIELD})\\s*:`, "g")),
+    ].map((m) => m[1]));
+    const body = codeLines.slice(Math.max(handlerAt, 0)).map((l) => l.raw);
+    const bodyText = body.join("\n");
+    const esc = (n) => n.replace(/[$]/g, "\\$&");
+    // assignments of `local` in the handler body: RHS texts (multi-line object
+    // literals and awaited calls joined), plus whether a handler param binds it.
+    const assignments = (local) => {
+        const out = [];
+        const assign = new RegExp(`(?:^|[^\\w.$])${esc(local)}\\s*(?::[^=\\n]*)?=(?!=)`);
+        for (let i = 0; i < body.length; i++) {
+            const raw = body[i];
+            if (boundFromHandlerParam(raw, local))
+                return "param";
+            const dr = destructuredRhs(raw, local);
+            if (dr !== null) {
+                out.push(dr);
+                continue;
+            }
+            if (!assign.test(raw))
+                continue;
+            let rhs = raw.slice(raw.indexOf("=") + 1);
+            const depth = (t) => (t.match(/[({[]/g) ?? []).length - (t.match(/[)}\]]/g) ?? []).length;
+            for (let j = i + 1; depth(rhs) > 0 && j < body.length && j <= i + 60; j++)
+                rhs += `\n${body[j]}`;
+            out.push(rhs);
+        }
+        return out;
+    };
+    const argFed = (local, seen) => {
+        if (local === "args")
+            return true;
+        if (principalOf?.(local))
+            return false; // an alias of a checked principal
+        if (seen.has(local) || seen.size > 6)
+            return false;
+        const next = new Set(seen).add(local);
+        const rhss = assignments(local);
+        if (rhss === "param")
+            return true;
+        if (rhss.length === 0)
+            return true; // not found: conservative, as before.
+        return rhss.some((rhs) => valueFromArgs(rhs, next));
+    };
+    const valueFromArgs = (expr, seen) => {
+        const e = expr
+            .trim()
+            .replace(/;+\s*$/, "")
+            .trim();
+        if (/^(?:await\s+)?ctx\.db\.(?:get|query)\b/.test(e))
+            return false; // a stored row
+        const called = wholeAwaitedCall(e);
+        if (called && isResolver(called, e))
+            return false; // the verified scope
+        if (principalOf?.(e))
+            return false; // a checked package principal
+        const root = /^([A-Za-z_$][\w$]*)(?:\s*(?:\.|\?\.|\[|$|\s+as\b|!))/.exec(e);
+        if (root &&
+            /^[A-Za-z_$][\w$]*(?:(?:\.|\?\.)[A-Za-z_$][\w$]*)*(?:\s+as\s+[\w<>[\]|. ]+|!)?$/.test(e))
+            return argFed(root[1], seen); // a local, or a member read of one
+        if (/\bargs\b/.test(e))
+            return true;
+        // any other expression: argument-fed only through a local it names.
+        for (const m of e.matchAll(/(?<![\w$.])([A-Za-z_$][\w$]*)\s*(?:\.|\?\.)/g))
+            if (m[1] !== "ctx" && argFed(m[1], seen))
+                return true;
+        return false;
+    };
+    const objectCarries = (text, seen) => {
+        // `field: <value>` up to the next top-level `,` / `}` / line end.
+        for (const m of text.matchAll(new RegExp(`(?:^|[{,\\s])(${R6_BOUNDARY_FIELD})\\s*:\\s*([^,}\\n]+)`, "gm")))
+            if (valueFromArgs(m[2], seen))
+                return true;
+        for (const m of text.matchAll(new RegExp(`(?:^|[{,])\\s*(${R6_BOUNDARY_FIELD})\\s*(?=[,}]|$)`, "gm")))
+            if (argFed(m[1], seen))
+                return true;
+        // spreads: `...args`, or `...x` with x an alias/rest of args.
+        for (const m of text.matchAll(/\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+            const x = m[1];
+            if (x === "args" || restOfArgs(x)) {
+                const pulled = x === "args" ? new Set() : pulledFromArgs(x);
+                const overridden = new Set([
+                    ...text.matchAll(new RegExp(`\\b(${R6_BOUNDARY_FIELD})\\s*[:,}]`, "g")),
+                ].map((k) => k[1]));
+                if ([...validatorFields].some((fld) => !pulled.has(fld) && !overridden.has(fld)))
+                    return true;
+            }
+            else if (localObjectCarries(x, seen))
+                return true;
+        }
+        return false;
+    };
+    const restOfArgs = (x) => new RegExp(`\\.\\.\\.\\s*${esc(x)}\\s*,?\\s*\\}\\s*=\\s*args\\b`).test(bodyText) ||
+        new RegExp(`\\b(?:const|let|var)\\s+${esc(x)}\\s*=\\s*args\\s*;?\\s*$`, "m").test(bodyText);
+    const pulledFromArgs = (x) => {
+        const m = new RegExp(`\\{([^}]*)\\.\\.\\.\\s*${esc(x)}\\s*,?\\s*\\}\\s*=\\s*args\\b`).exec(bodyText);
+        const out = new Set();
+        if (m)
+            for (const part of m[1].split(",")) {
+                const key = part.split(":")[0].split("=")[0].trim();
+                if (key)
+                    out.add(key);
+            }
+        return out;
+    };
+    // A local object handed to a write: its literal, and every `obj.field = v`.
+    const localObjectCarries = (obj, seen) => {
+        if (seen.has(`obj:${obj}`))
+            return false;
+        const next = new Set(seen).add(`obj:${obj}`);
+        const rhss = assignments(obj);
+        if (rhss !== "param")
+            for (const rhs of rhss)
+                if (rhs.trim().startsWith("{") && objectCarries(rhs, next))
+                    return true;
+        const memberSet = new RegExp(`\\b${esc(obj)}\\s*(?:\\.\\s*(${R6_BOUNDARY_FIELD})|\\[\\s*["'\`](${R6_BOUNDARY_FIELD})["'\`]\\s*\\])\\s*=(?!=)\\s*([^;\\n]+)`, "g");
+        for (const m of bodyText.matchAll(memberSet))
+            if (valueFromArgs(m[3], next))
+                return true;
+        return false;
+    };
+    for (const w of writes) {
+        if (new RegExp(`\\b${R6_BOUNDARY_FIELD}\\s*:\\s*args\\b`).test(w))
+            return true;
+        if (objectCarries(w, new Set()))
+            return true;
+        // the object handed to the write: its last top-level argument.
+        const m = /ctx\.db\.(?:insert|patch|replace)\s*\(([\s\S]*)\)\s*;?\s*$/.exec(w.trim());
+        const last = m ? m[1].split(",").pop()?.trim() : undefined;
+        if (last === "args") {
+            if (validatorFields.size > 0)
+                return true;
+        }
+        else if (last && /^[A-Za-z_$][\w$]*$/.test(last)) {
+            if (restOfArgs(last) && validatorFields.size > 0)
+                return true;
+            if (localObjectCarries(last, new Set()))
+                return true;
+        }
+    }
+    return false;
+}
 export function scanR6(files, rootIsConvex = false) {
     const scan = emptyScan();
     const helperIndex = indexGuardHelpers(files);
@@ -721,6 +961,11 @@ export function scanR6(files, rootIsConvex = false) {
             continue;
         // One shape for every argument read: `args["x"]` → `args.x`.
         const f = { ...raw, lines: normalizeLines(raw.lines) };
+        // Parsed once per file, and only when the file names the identity
+        // package: the checked-principal read (package-principal.ts) needs it.
+        const parsed = f.lines.some((l) => l.raw.includes(IDENTITY_PACKAGE))
+            ? parseFile(f)
+            : undefined;
         for (const h of splitMutationHandlers(f)) {
             // An internalMutation has NO client caller: its arguments come from
             // server code (a cron, a scheduler hop, another function), so "a
@@ -742,8 +987,6 @@ export function scanR6(files, rootIsConvex = false) {
                     guard = true;
                 if (R6_SCOPE_RESOLUTION.test(l.raw))
                     resolvesScope = true;
-                if (R6_BOUNDARY_ARG.test(l.raw))
-                    boundaryArg = true;
             }
             if (!writeLine)
                 continue; // not a write handler — R-6 does not govern it.
@@ -766,12 +1009,71 @@ export function scanR6(files, rootIsConvex = false) {
                 return fileSrc;
             };
             const resolvedBy = new Map();
-            const isResolver = (name) => {
+            const isResolver = (name, call) => {
                 const d = fns.resolver(name, f.rel);
-                if (d)
-                    resolvedBy.set(name, `${d.rel}:${d.f.line}`);
-                return !!d;
+                if (d) {
+                    resolvedBy.set(name, `identity resolver ${name}() (definition ${d.rel}:${d.f.line}), which returns the verified scope itself and refuses an absent identity on every path`);
+                    return true;
+                }
+                const spec = SCOPE_REFINERS[name];
+                if (!spec)
+                    return false;
+                const def = fns.lookup(name, f.rel);
+                const arg = callArguments(call, name)?.[spec.argIndex];
+                if (!def || !arg || !/^[A-Za-z_$][\w$]*$/.test(arg) || arg === "args")
+                    return false;
+                const t = analyzeLocalTaint(h, arg, isResolver);
+                if (!(t.fromScope > 0 && t.fromArgs === 0))
+                    return false;
+                resolvedBy.set(name, `named scope refiner ${name}() (definition ${def.rel}:${def.f.line}) handed the scope-derived local "${arg}"`);
+                return true;
             };
+            // The principal @vantageos/cloud-identity resolved, refused unless ok
+            // before the write (package-principal.ts): a verified-identity value.
+            const principals = parsed
+                ? packagePrincipals(parsed, h.name, writeLine)
+                : undefined;
+            const principalOf = principals
+                ? (expr) => {
+                    const why = principals.principalOf(expr);
+                    if (why)
+                        resolvedBy.set(`principal:${why}`, why);
+                    return why;
+                }
+                : undefined;
+            // The boundary-from-argument test reads the WRITE's provenance, never a
+            // boundary token anywhere in the handler (see boundaryFromArgument).
+            boundaryArg = boundaryFromArgument(h, writes, isResolver, principalOf);
+            // An awaited call, before the first write, to a function judged an
+            // identity resolver (it refuses an absent identity on every path and
+            // returns the verified scope) IS an identity guard, whatever arguments
+            // it is handed — vantage-peers 45e40c8 tasks.complete resolves its
+            // caller through requireAuthenticatedCaller before writing.
+            let resolverGuard;
+            {
+                const codeLines = h.lines.filter(code);
+                for (let i = 0; i < codeLines.length && !resolverGuard; i++) {
+                    if (codeLines[i].n >= writeLine)
+                        break;
+                    const m = /\bawait\s+([A-Za-z_$][\w$]*)\s*\(/.exec(codeLines[i].raw);
+                    if (!m || m[1] === "ctx")
+                        continue;
+                    const from = codeLines[i].raw.slice(m.index);
+                    const call = joinedAwaitedCall(from, codeLines, i);
+                    resolvedBy.clear();
+                    if (isResolver(m[1], call))
+                        resolverGuard = `${[...resolvedBy.values()].join(", ")} called at line ${codeLines[i].n}`;
+                }
+                resolvedBy.clear();
+            }
+            // Resolving the caller proves WHO writes, not that a boundary ARGUMENT
+            // is bound to them: the credit stands only when no argument reaches a
+            // boundary field at a write (a hollow master-only helper that returns the
+            // scope must not excuse `orchestratorId: args.orchestratorId`).
+            if (resolverGuard && !boundaryArg)
+                guard = true;
+            else
+                resolverGuard = undefined;
             const credits = [];
             // A boundary written straight from an argument a BINDING VALIDATOR
             // bound to the verified scope before the write: credited only when
@@ -794,10 +1096,19 @@ export function scanR6(files, rootIsConvex = false) {
             }
             let bound;
             for (const loc of boundaryLocals) {
+                const rhs = boundaryMemberRhs(writes, loc);
+                // Every write of `loc` reads the checked package principal
+                // (`orgId: who.principal.orgId`, `orgId: p.orgId` for an alias p).
+                const viaPrincipal = rhs && principals ? rhs.map((x) => principals.principalOf(x)) : [];
+                if (viaPrincipal.length > 0 && viaPrincipal.every((x) => x)) {
+                    anyDerived = true;
+                    resolvesScope = true;
+                    credits.push(`\`${rhs?.[0]}\` is ${viaPrincipal[0]}`);
+                    continue;
+                }
                 // A value a refusing predicate bound to the caller's scope before
                 // the write (`if (!P(scope, mission.orgId)) throw`), written
                 // unchanged: derived from the verified identity through the target.
-                const rhs = boundaryMemberRhs(writes, loc);
                 if (rhs) {
                     bound ??= predicateBoundValues(h, f, writeLine, fns, getSrc);
                     const by = rhs.map((x) => bound?.get(x));
@@ -809,10 +1120,16 @@ export function scanR6(files, rootIsConvex = false) {
                     }
                 }
                 resolvedBy.clear();
-                const a = analyzeLocalTaint(h, loc, isResolver);
+                const a = analyzeLocalTaint(h, loc, isResolver, principalOf);
                 if (a.fromResolver) {
                     resolvesScope = true;
-                    credits.push(`local "${loc}" is the return of identity resolver ${[...resolvedBy].map(([n, at]) => `${n}() (definition ${at})`).join(", ")}, which returns the verified scope itself and refuses an absent identity on every path`);
+                    const by = [...resolvedBy.entries()];
+                    const returned = by.filter(([k]) => !k.startsWith("principal:"));
+                    const read = by.filter(([k]) => k.startsWith("principal:"));
+                    if (returned.length > 0)
+                        credits.push(`local "${loc}" is the return of ${returned.map(([, v]) => v).join(", ")}`);
+                    if (read.length > 0)
+                        credits.push(`local "${loc}" reads ${read.map(([, v]) => v).join(", ")}`);
                 }
                 if (a.fromScope > 0) {
                     anyDerived = true;
@@ -933,7 +1250,7 @@ export function scanR6(files, rootIsConvex = false) {
                 scan.conform.push({
                     rel: f.rel,
                     n: writeLine,
-                    note: `${h.name}: boundary derived from a verified identity / target-resource guard`,
+                    note: `${h.name}: boundary derived from a verified identity / target-resource guard${resolverGuard ? ` — ${resolverGuard}` : ""}`,
                 });
             }
             else if (boundaryArg) {
@@ -944,11 +1261,23 @@ export function scanR6(files, rootIsConvex = false) {
                 });
             }
             else {
-                scan.cnj.push({
-                    rel: f.rel,
-                    n: writeLine,
-                    note: `${h.name}: writes with no identity/resource guard and no clearly caller-supplied boundary field — deferred, not statically confirmed`,
-                });
+                // Two shapes read in full from the AST before deferring: a FILE-LOCAL
+                // master-only wrapper dominating the write, and a possession-gated
+                // write of the one row a hashed argument selects (r6-shapes.ts).
+                const credit = masterOnlyWrapperCredit(raw, h.name) ??
+                    possessionGatedCredit(raw, h.name);
+                if (credit)
+                    scan.conform.push({
+                        rel: f.rel,
+                        n: writeLine,
+                        note: `${h.name}: ${credit}`,
+                    });
+                else
+                    scan.cnj.push({
+                        rel: f.rel,
+                        n: writeLine,
+                        note: `${h.name}: writes with no identity/resource guard and no clearly caller-supplied boundary field — deferred, not statically confirmed`,
+                    });
             }
             // A violation at a site calling a listed helper whose definition was
             // read and NOT honoured says why, so the reader is not left believing
@@ -1033,12 +1362,12 @@ const R16_CHECK = "a refusal throws a ConvexError with a stable UPPER_SNAKE_CASE
 /** Classify an R-6 live probe: a boundary-less write MUST be refused fail-closed. */
 export function classifyR6Live(id, tool, outcome) {
     if (outcome.kind === "accepted") {
-        return {
+        return withCount({
             id,
             anchor: `live:${tool}`,
             state: "non-conforming",
             verdict: `R-6 (live): tool "${tool}" ACCEPTED a write with no verified identity/boundary — fail-open.`,
-        };
+        }, itemCount(1));
     }
     if (/RBAC|AUTH|ORG|unauthori|denied|required|forbidden/i.test(outcome.message)) {
         return {
@@ -1070,12 +1399,12 @@ export function classifyR16Live(id, payload) {
         };
     }
     if (R16_REFUSAL_KW.test(payload)) {
-        return {
+        return withCount({
             id,
             anchor: "live:error-contract",
             state: "non-conforming",
             verdict: `R-16 (live): a triggered refusal carried NO structured code — opaque error contract (${payload.slice(0, 80)}).`,
-        };
+        }, itemCount(1));
     }
     const reason = `R-16 (live): could not trigger a classifiable refusal — the served response is neither a coded refusal nor a recognisable one. NOT a clean bill.`;
     return {

package/dist/detectors/source/jobs.js

@@ -1,3 +1,4 @@
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 import { base, code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
 // ---------------------------------------------------------------------------
 // R-19 — a table holding personal data declares a retention period AND exposes
@@ -300,11 +301,21 @@ export function scanR20(files) {
                 note: "background job declares no per-run bound (.take/_CAP/limit) — an unbounded run does not ship",
             });
         }
+        else if (hasJustificationTokenInText(f.lines.map((l) => l.raw).join("\n"))) {
+            // judgement retired (task k179jnhx, §23): a bound-but-unlogged job is
+            // flagged; the FILE's carried JUSTIFIÉ:/JUSTIFIED: token is the written
+            // justification — decided by presence, never a person's opinion of it.
+            scan.conform.push({
+                rel: f.rel,
+                n: boundLine,
+                note: "background job bounds its run; no outcome log (console.*) found, but the file carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed",
+            });
+        }
         else {
-            scan.cnj.push({
+            scan.violate.push({
                 rel: f.rel,
                 n: boundLine,
-                note: "background job bounds its run but no outcome log (console.*) found — observability not statically confirmed",
+                note: "background job bounds its run but no outcome log (console.*) found, and no written JUSTIFIÉ:/JUSTIFIED: token in the file — observability owes a fix or a recorded justification",
             });
         }
     }

package/dist/detectors/source/lifecycle.js

@@ -1,3 +1,4 @@
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 import { code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
 // An ADMIN-PROVISIONABLE resource: a config/template row an admin creates —
 // profiles, clients, tenants, templates, mappings, filter rules, allowlists.
@@ -114,6 +115,7 @@ export function scanR43(files) {
     const scan = emptyScan();
     const dels = deletePaths(files);
     const { creates, optOutFiles } = adminCreates(files);
+    const textByRel = new Map(files.map((f) => [f.rel, f.lines.map((l) => l.raw).join("\n")]));
     for (const c of creates.values()) {
         const del = dels.get(c.table);
         if (del) {
@@ -130,11 +132,21 @@ export function scanR43(files) {
                 note: `admin resource ${c.table} has no delete/GC path but carries a written out-of-scope reason (allow-no-delete-path) in ${c.rel}`,
             });
         }
+        else if (hasJustificationTokenInText(textByRel.get(c.rel) ?? "")) {
+            // judgement retired (task k179jnhx, §23): the file's carried
+            // JUSTIFIÉ:/JUSTIFIED: token IS the written out-of-scope reason,
+            // decided by presence, never by a person's opinion of soundness.
+            scan.conform.push({
+                rel: c.rel,
+                n: c.n,
+                note: `admin resource ${c.table} has no delete/GC path, but ${c.rel} carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+            });
+        }
         else {
-            scan.cnj.push({
+            scan.violate.push({
                 rel: c.rel,
                 n: c.n,
-                note: `admin resource ${c.table} is create/upsert-provisioned but exposes NO delete/GC path and carries no written out-of-scope reason — admin-resource lifecycle asymmetry (a resource you can create but never remove, orphaning any dependents)`,
+                note: `admin resource ${c.table} is create/upsert-provisioned but exposes NO delete/GC path and carries no written out-of-scope reason (allow-no-delete-path / JUSTIFIÉ: / JUSTIFIED:) — admin-resource lifecycle asymmetry owes a fix or a recorded justification`,
             });
         }
     }