@vantageos/backend-doctor 0.1.14 → 0.3.0

package/dist/detectors/oracle-axis2.js

@@ -1,4 +1,5 @@
-import { isInventoryRow, readOracle, } from "../oracle.js";
+import { isInventoryRow, oracleLabel, readOracle, refuseWithoutOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
 // A written justification token turns a flagged divergence from a DEFECT the
 // author owes into a recorded, accepted divergence. It is the mechanical pole
 // that replaced "a human decides whether the divergence is sound": the control
@@ -7,22 +8,37 @@ import { isInventoryRow, readOracle, } from "../oracle.js";
 // are remediation-owed markers (R-28) — a fix still owed, NOT a justification —
 // so they do not satisfy this predicate; only an explicit JUSTIFIÉ/JUSTIFIED/
 // STATELESS/ACCEPTED token does.
+//
+// Anchored on the DOCUMENTED shape: the standard writes the token with a
+// trailing colon (`JUSTIFIÉ:` / `JUSTIFIED:` / `STATELESS:`), at a word
+// boundary. Two failures a bare substring match let through, both closed here:
+//   • a LEADING-letter negation — "UNJUSTIFIED" contains "JUSTIFIED", so the
+//     leading `(?<![A-Za-zÀ-ÿ-])` (not preceded by a letter OR a hyphen — a
+//     hyphen-joined negation like French `non-justifié:` clears a letter-only
+//     lookbehind, Eta #12 round-2) rejects it; and R-37's own output prints
+//     "N UNJUSTIFIED divergence(s)".
+//   • a token with NO colon — "not justified", "justified by design" — cleared
+//     the guard though the standard requires the colon; the trailing `\s*:`
+//     now rejects it. Only the recorded token form (`TOKEN:`) is a justification.
+// No trailing \b before the colon: an accented final letter (É in JUSTIFIÉ) is
+// not an ASCII word char, so \b would not match after it — the colon is the anchor.
+//
+// ONE regex, shared by every axis (oracle-row remediation cells here, and a
+// source-scan's nearby comment window in the SOURCE_STANDARD_PIN detectors) —
+// task k179jnhx: "Do not write a second token matcher; extract/share the
+// existing one." Two implementations of one predicate is the defect class the
+// fleet keeps filing.
+export const JUSTIFICATION_TOKEN_RE = /(?<![A-Za-zÀ-ÿ-])(JUSTIFI(É|E|ED)|STATELESS|ACCEPT(É|E|ED)|WONTFIX)\s*:/i;
+/** The oracle-row form: reads the row's remediation cell (`rbac_adjustment_needed`). */
 export function hasJustificationToken(r) {
     const cell = (r.by.rbac_adjustment_needed ?? "").trim();
-    // Anchored on the DOCUMENTED shape: the standard writes the token with a
-    // trailing colon (`JUSTIFIÉ:` / `JUSTIFIED:` / `STATELESS:`), at a word
-    // boundary. Two failures a bare substring match let through, both closed here:
-    //   • a LEADING-letter negation — "UNJUSTIFIED" contains "JUSTIFIED", so the
-    //     leading `(?<![A-Za-zÀ-ÿ-])` (not preceded by a letter OR a hyphen — a
-    //     hyphen-joined negation like French `non-justifié:` clears a letter-only
-    //     lookbehind, Eta #12 round-2) rejects it; and R-37's own output prints
-    //     "N UNJUSTIFIED divergence(s)".
-    //   • a token with NO colon — "not justified", "justified by design" — cleared
-    //     the guard though the standard requires the colon; the trailing `\s*:`
-    //     now rejects it. Only the recorded token form (`TOKEN:`) is a justification.
-    // No trailing \b before the colon: an accented final letter (É in JUSTIFIÉ) is
-    // not an ASCII word char, so \b would not match after it — the colon is the anchor.
-    return /(?<![A-Za-zÀ-ÿ-])(JUSTIFI(É|E|ED)|STATELESS|ACCEPT(É|E|ED)|WONTFIX)\s*:/i.test(cell);
+    return JUSTIFICATION_TOKEN_RE.test(cell);
+}
+/** The raw-text form — for a SOURCE-scan site with no oracle row: a nearby code
+ * comment window is that site's "remediation cell". Same regex, same word-
+ * boundary/negation guards; never a second matcher. */
+export function hasJustificationTokenInText(text) {
+    return JUSTIFICATION_TOKEN_RE.test(text);
 }
 // ---- R-7 read/write coherence divergence (INCOHERENT* table-aggregate flag) -
 // §18: "`INCOHERENT*` flag (mechanical); divergence justified (human)". The
@@ -152,13 +168,12 @@ export function findDivergences(rows) {
     return sites;
 }
 const R37_ID = "R-37 filled-neighbour divergence";
-const R37_ANCHOR = "oracle:vp-by-tool-day158.csv";
 /** Wrap the filled-neighbour compare into a Detector. `rowsProvider` is
  * injectable for tests; production reads the memoized real oracle. */
 export function makeR37(rowsProvider = readOracle) {
     return {
         id: R37_ID,
-        run: () => {
+        run: () => refuseWithoutOracle(R37_ID, () => {
             const all = findDivergences(rowsProvider());
             // MECHANICAL disposition: an unjustified divergence is the defect; a
             // divergence carrying a written per-tool justification token is accepted.
@@ -173,7 +188,7 @@ export function makeR37(rowsProvider = readOracle) {
                 const reason = `R-37: no UNJUSTIFIED filled-neighbour divergence across the oracle's per-table groups (${all.length} divergence(s), all carrying a written per-tool justification token, or none present). The mechanical compare is exhaustive and the disposition is decided by the token's presence, not a human verdict. ${breakdown}`;
                 return {
                     id: R37_ID,
-                    anchor: R37_ANCHOR,
+                    anchor: oracleLabel(),
                     state: "present",
                     verdict: reason,
                 };
@@ -183,12 +198,12 @@ export function makeR37(rowsProvider = readOracle) {
                 .map((s) => `${s.table}.${s.field}: ${s.toolA} "${s.valA.slice(0, 32)}" vs ${s.toolB} "${s.valB.slice(0, 32)}"`)
                 .join("; ");
             const reason = `R-37: ${sites.length} UNJUSTIFIED filled-neighbour divergence(s) across ${tables.size} tables — the mechanical compare names WHICH TWO TOOLS diverge on a shared contract field, and none carries a written per-tool justification token (JUSTIFIÉ:/JUSTIFIED: in rbac_adjustment_needed); each owes a fix or a recorded justification. This IS a violation, not an abstention. ${breakdown} Examples: ${examples}.`;
-            return {
+            return withCount({
                 id: R37_ID,
-                anchor: `oracle:vp-by-tool-day158.csv table=${sites[0].table}`,
+                anchor: `${oracleLabel()} table=${sites[0].table}`,
                 state: "non-conforming",
                 verdict: reason,
-            };
-        },
+            }, itemCount(sites.length));
+        }),
     };
 }

package/dist/detectors/predicates.d.ts

@@ -1,3 +1,4 @@
+import { type WriterTierTable } from "../oracle.js";
 import { type RulePredicate } from "./shared.js";
 /** Collapse a raw `surface` to one of the three canonical exposures, or null. */
 export declare function collapseSurface(raw: string): string | null;
@@ -11,6 +12,8 @@ export declare const r4: RulePredicate;
 export declare function collapseTier(raw: string): string | null;
 export declare const r5: RulePredicate;
 export declare const r9: RulePredicate;
+export declare const WRITER_TIERS: ReadonlySet<string>;
+export declare function makeR10(sideCar: () => WriterTierTable): RulePredicate;
 export declare const r10: RulePredicate;
 export declare const r12: RulePredicate;
 export declare const r13: RulePredicate;

package/dist/detectors/predicates.js

@@ -1,3 +1,10 @@
+// The eleven per-row first-wave predicates. Each transcribes its §15 "The
+// check" row and its §2 field mapping from the pinned standard, then applies
+// that predicate to the oracle rows. Structural R-14 and R-38 live in
+// structural.ts (they judge the inventory SCHEMA, not a row).
+import { basename } from "node:path";
+import { WRITER_TIER_NAME, readWriterTier } from "../oracle.js";
+import { hasJustificationToken } from "./oracle-axis2.js";
 import { LIST_VERBS, WRITE_VERBS, isMcpPublic } from "./shared.js";
 // ---- R-1 exposure declared ------------------------------------------------
 // §2 line 32: exposure -> `surface` = `public` (MCP surface) / `internal` /
@@ -175,10 +182,18 @@ export const r5 = {
         // no arg= in the boundary: NOW the identity-evidencing label may confirm.
         if (rbacEvidencesIdentity(r.by.rbac_qui))
             return { kind: "conform" };
-        // maps to a tier but the row evidences NEITHER identity nor arg — abstain, never a silent pass.
+        // maps to a tier but the row evidences NEITHER identity nor arg — flagged.
+        // judgement is retired (task k179jnhx, §23): the disposition is decided by
+        // the written justification token's PRESENCE in the remediation cell, never
+        // by a person's opinion of whether the ambiguity is sound. No token →
+        // non-conforming; a JUSTIFIÉ:/JUSTIFIED: token → present. could-not-judge
+        // is reserved for a row the instrument could not read (never reached here —
+        // this row parsed fine, the disposition is undecided-by-token, not unreadable).
+        if (hasJustificationToken(r))
+            return { kind: "conform" };
         return {
-            kind: "cnj",
-            note: `tier maps to ${tier} but rbac_qui="${r.by.rbac_qui}"/namespace_ou_org="${ns}" do not evidence identity-resolution; R-11 flags the locus`,
+            kind: "violate",
+            note: `tier maps to ${tier} but rbac_qui="${r.by.rbac_qui}"/namespace_ou_org="${ns}" do not evidence identity-resolution, and no written JUSTIFIÉ:/JUSTIFIED: token is recorded in the remediation cell (rbac_adjustment_needed="${(r.by.rbac_adjustment_needed ?? "").trim() || "<empty>"}"); R-11 flags the locus`,
         };
     },
 };
@@ -200,22 +215,81 @@ export const r9 = {
     },
 };
 // ---- R-10 writer authority, a distinct resolved tier ----------------------
-// §2 writer authority [shared] -> `rbac_qui`. §15: writer tier present, DISTINCT,
-// one of five. The oracle has a SINGLE `rbac_qui` column, so no write can carry
-// a writer tier distinct from its reader tier — the headline merge (R-14).
-export const r10 = {
-    ruleId: "R-10",
-    id: "R-10 writer authority, distinct tier",
-    check: "writer tier present, distinct from reader, one of five",
-    classify: (r) => {
-        if (!WRITE_VERBS.has(r.by.crud))
-            return { kind: "na" };
-        return {
-            kind: "violate",
-            note: "writer authority is not recorded as a field distinct from reader authority — both merged into the single `rbac_qui` column",
-        };
-    },
-};
+// §2 line 36: writer authority is "a **distinct** tier from the same set, resolved
+// from a verified identity"; §15 line 413: "writer tier present, distinct, one of
+// five"; line 63: "Reader and writer are two fields". DISTINCT is a property of
+// the FIELD, not of the value: the standard requires the writer tier to be
+// RECORDED apart from the reader tier so a `read=public write=admin` divergence
+// can be written — it nowhere forbids a tool whose writer tier happens to equal
+// its reader tier (an org member reading and writing its own org's rows). So an
+// equal VALUE conforms; a MERGED field (no separate record, or one cell naming
+// several tiers) violates.
+//
+// Material: the writer-tier side-car (src/oracle.ts WRITER_TIER_NAME), joined on
+// `outil`. Branches, per write row:
+//   side-car absent / unreadable           -> cnj, naming the file(s) looked at
+//   no side-car row for the tool           -> violate (tier absent)
+//   two rows with different tiers          -> violate (merged)
+//   tier empty / `?`                       -> violate (unknown)
+//   tier naming several tiers (a/b, a+b)   -> violate (merged)
+//   tier outside the five                  -> violate
+//   writer_gate empty or `mcp-scope:<t>`   -> cnj: the tier was not derived from
+//        a gate on a write door, so "resolved from a verified identity" is not
+//        evidenced by the side-car (never a silent pass)
+//   otherwise                              -> conform
+export const WRITER_TIERS = new Set([
+    "public",
+    "org-member",
+    "org-admin",
+    "fleet-internal",
+    "master",
+]);
+const UNKNOWN_TIER = new Set(["", "?", "unknown", "n/a", "tbd"]);
+const MERGED_TIER = /[/+,|&]|\s(and|or|et|ou)\s/i;
+export function makeR10(sideCar) {
+    return {
+        ruleId: "R-10",
+        id: "R-10 writer authority, distinct tier",
+        check: "writer tier recorded in its own field (side-car joined on `outil`), one of five, gated on a write door; equal-to-reader values conform (the field must be distinct, §2 line 36)",
+        classify: (r) => {
+            if (!WRITE_VERBS.has(r.by.crud))
+                return { kind: "na" };
+            const t = sideCar();
+            if (t.status === "absent")
+                return {
+                    kind: "cnj",
+                    note: `writer-tier side-car ${WRITER_TIER_NAME} ABSENT (${t.origin}; searched: ${t.searched.join(", ") || "<none>"}) — this oracle has write rows, so writer authority cannot be judged`,
+                };
+            if (t.status === "unreadable")
+                return { kind: "cnj", note: `writer-tier side-car ${t.path} unreadable — ${t.reason}` };
+            const file = basename(t.path);
+            const entries = t.byTool.get(r.by.outil) ?? [];
+            if (entries.length === 0)
+                return { kind: "violate", note: `no writer tier recorded for "${r.by.outil}" in ${file} — writer authority absent` };
+            const tiers = [...new Set(entries.map((e) => e.writer_tier))];
+            if (tiers.length > 1)
+                return {
+                    kind: "violate",
+                    note: `${file} records ${tiers.length} writer tiers for "${r.by.outil}" (${tiers.join(", ")}) — merged, not one tier`,
+                };
+            const tier = tiers[0];
+            if (UNKNOWN_TIER.has(tier.toLowerCase()))
+                return { kind: "violate", note: `writer_tier="${tier || "<empty>"}" for "${r.by.outil}" — unknown, not a tier` };
+            if (MERGED_TIER.test(tier))
+                return { kind: "violate", note: `writer_tier="${tier}" names several tiers — merged, not one tier` };
+            if (!WRITER_TIERS.has(tier))
+                return { kind: "violate", note: `writer_tier="${tier}" is none of the five tiers {${[...WRITER_TIERS].join(", ")}}` };
+            const gate = entries[0].writer_gate;
+            if (gate === "" || gate.startsWith("mcp-scope:"))
+                return {
+                    kind: "cnj",
+                    note: `writer_tier="${tier}" for "${r.by.outil}" rests on ${gate === "" ? "no writer_gate" : `the MCP-scope fallback "${gate}"`} — no write-door gate evidences resolution from a verified identity`,
+                };
+            return { kind: "conform" };
+        },
+    };
+}
+export const r10 = makeR10(readWriterTier);
 // ---- R-12 vector search declares namespace + topK -------------------------
 // §2 vector boundary -> `search_mecanisme`. §15: real namespace + numeric topK.
 export const r12 = {

package/dist/detectors/shared.js

@@ -1,4 +1,5 @@
-import { isInventoryRow, readOracle } from "../oracle.js";
+import { isInventoryRow, oracleLabel, readOracle, refuseWithoutOracle, } from "../oracle.js";
+import { itemCount, withCount } from "../violation-count.js";
 /** Run a predicate over a row set, tallying per-kind. */
 export function tally(spec, rows) {
     const t = { conform: 0, violate: 0, cnj: 0, na: 0, violations: [], unjudged: [] };
@@ -52,7 +53,7 @@ export function evaluate(spec, rows) {
             .join("; ")}. This is NOT a clean bill. ${breakdown}`;
         return {
             id: spec.id,
-            anchor: anchorFor(t.unjudged, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.unjudged, oracleLabel()),
             state: "could-not-judge",
             verdict: reason,
             reason,
@@ -63,16 +64,16 @@ export function evaluate(spec, rows) {
             .slice(0, 3)
             .map((v) => `row#${v.row.n} "${v.row.by.outil || v.row.by.table}" — ${v.note}`)
             .join("; ");
-        return {
+        return withCount({
             id: spec.id,
-            anchor: anchorFor(t.violations, "oracle:vp-by-tool-day158.csv"),
+            anchor: anchorFor(t.violations, oracleLabel()),
             state: "non-conforming",
             verdict: `${spec.ruleId}: ${t.violate} of ${applicable} applicable oracle rows VIOLATE (${spec.check}). ${breakdown} Examples: ${examples}.`,
-        };
+        }, itemCount(t.violate));
     }
     return {
         id: spec.id,
-        anchor: "oracle:vp-by-tool-day158.csv",
+        anchor: oracleLabel(),
         state: "present",
         verdict: `${spec.ruleId}: ${t.conform} applicable oracle rows conform (${spec.check}); 0 violations. ${breakdown}`,
     };
@@ -85,7 +86,7 @@ export function evaluate(spec, rows) {
 export function makeOracleDetector(spec, rowsProvider = readOracle) {
     return {
         id: spec.id,
-        run: () => evaluate(spec, rowsProvider()),
+        run: () => refuseWithoutOracle(spec.id, () => evaluate(spec, rowsProvider())),
     };
 }
 // ---- small shared classifiers over oracle vocabulary --------------------

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

@@ -0,0 +1,92 @@
+import * as ts from "typescript";
+import type { Tree } from "../../engine-types.js";
+export type SrcFile = Tree["files"][number];
+export interface Parsed {
+    rel: string;
+    sf: ts.SourceFile;
+}
+export declare function sourceOf(f: SrcFile): string;
+export declare function parseFile(f: SrcFile): Parsed;
+export declare function lineOf(n: ts.Node): number;
+/** Strip `await`, parentheses, `!` non-null, `as`/`satisfies` casts. */
+export declare function unwrap(e: ts.Expression): ts.Expression;
+/** A property read: `x.prop`, or `x["prop"]` (a string-literal element access
+ * is the same read, spelled differently). A computed key is not a read of a
+ * known property and gives undefined. */
+export declare function propRead(e: ts.Node): {
+    obj: ts.Expression;
+    name: string;
+} | undefined;
+/** The initializer of the NEAREST `const <id> = <init>` visible from `id`, or
+ * undefined (a parameter or a `let` in between shadows it, so does a
+ * destructure). Exactly one level: the caller never follows an alias of an
+ * alias. */
+export declare function constInit(id: ts.Identifier): ts.Expression | undefined;
+/** `e` as a property read, one const alias deep: `x.p`, `x["p"]`, or an
+ * identifier declared `const a = x.p` / `const a = x["p"]` (read as `x.p`). */
+export declare function propReadResolved(e: ts.Expression): {
+    obj: ts.Expression;
+    name: string;
+} | undefined;
+/** Visit every descendant of `n` (pre-order), NOT descending into nested
+ * function bodies when `ownOnly` is set. */
+export declare function walk(n: ts.Node, visit: (x: ts.Node) => void, ownOnly?: boolean): void;
+/** `a.b.c` as text, or undefined when the expression is not a dotted chain. */
+export declare function dotted(e: ts.Expression): string | undefined;
+/** The callee's last name: `ctx.db.patch` -> `patch`, `helper` -> `helper`. */
+export declare function calleeName(c: ts.CallExpression): string | undefined;
+export type Builder = "mutation" | "action" | "query" | "internalMutation" | "internalAction" | "internalQuery";
+export interface Registration {
+    name: string;
+    builder: Builder;
+    rel: string;
+    line: number;
+    /** the handler function (`handler: async (ctx, args) => {…}`). */
+    handler: ts.FunctionLikeDeclaration;
+    /** arg name -> referenced table, for `v.id("T")` / `v.optional(v.id("T"))`. */
+    argIdTable: Map<string, string>;
+}
+export declare function idTableOf(text: string): string | undefined;
+/** The ONE table a validator's text references through `v.id("T")` — through
+ * `v.optional`, `v.array`, or a nested `v.object` — or undefined when it names
+ * none or several. */
+export declare function singleIdTable(text: string): string | undefined;
+/** Every `export const NAME = <builder>({ … handler … })` of a file. */
+export declare function registrations(p: Parsed): Registration[];
+export interface FnDef {
+    name: string;
+    rel: string;
+    line: number;
+    fn: ts.FunctionLikeDeclaration;
+}
+/** Every top-level `function f` / `const f = (…) => …` across the parsed files. */
+export declare function indexFunctions(ps: Parsed[]): Map<string, FnDef[]>;
+/** Names of the plain-identifier functions a body calls. */
+export declare function calledNames(fn: ts.Node): Set<string>;
+/** A per-function boolean property closed over the call graph: `own(fn)` holds,
+ * or the function calls (by name) another function for which it holds. */
+export declare function closeOverCalls(idx: Map<string, FnDef[]>, own: (d: FnDef) => boolean): Set<string>;
+/** The tenant columns, as standard 2825122 §4 R-52 lists them:
+ * `orgId`/`tenantId`/`workspaceId`/`orgSlug` (vantage-peers stamps its agents
+ * under `orgSlug: client_org_mapping.clerkOrgSlug`). A `namespace` is NOT in this
+ * set: the standard counts it only when it is "checked against the caller's
+ * allowed prefixes", which is a property of the code around the table, not of
+ * the schema. `readSchema` records it apart (`SchemaTable.namespace`) and R-52
+ * decides it per table (cross-tenant-write.ts `namespaceDecisions`). */
+export declare const TENANT_COLUMNS: ReadonlySet<string>;
+/** The column that is a tenant column only where it is prefix-checked. */
+export declare const NAMESPACE_COLUMN = "namespace";
+export type TenantKind = "required" | "optional" | "none";
+export interface SchemaTable {
+    name: string;
+    /** from the TENANT_COLUMNS alone. */
+    tenant: TenantKind;
+    /** whether a `namespace` column exists and is optional — a tenant column
+     * only where the code checks it against the caller's allowed prefixes. */
+    namespace: TenantKind;
+    fields: string[];
+    /** field -> the table its `v.id("T")` references. */
+    idRef: Map<string, string>;
+}
+/** Read every `name: defineTable({...})` of a schema file. */
+export declare function readSchema(p: Parsed): Map<string, SchemaTable>;