@vantageos/backend-doctor 0.2.0 → 0.3.0

package/dist/detectors/source/backfill.js

@@ -1,3 +1,4 @@
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 import { base, code, emptyScan, isJudgeable, SOURCE_STANDARD_PIN, srcDetector, } from "./_scan.js";
 // A schema definition file — where defineTable declarations live.
 const SCHEMA_FILE = /schema\.ts$/;
@@ -104,7 +105,9 @@ export function scanR44(files) {
         let directInsert = false;
         let loopsSource = false;
         let referenced = false;
+        let migText = "";
         for (const f of migFiles) {
+            migText += `${f.lines.map((l) => l.raw).join("\n")}\n`;
             for (const l of f.lines) {
                 if (!code(l))
                     continue;
@@ -126,18 +129,39 @@ export function scanR44(files) {
             });
         }
         else if (directInsert) {
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table} has a migration inserting it, but no query/paginate of the source table ${d.source} is visible — coverage of existing source rows is not statically decidable (name the migration site)`,
-            });
+            // judgement retired (task k179jnhx, §23): flagged (no visible query/
+            // paginate of the source table); decides on the migration file's written
+            // JUSTIFIÉ:/JUSTIFIED: token, never a person's opinion of coverage.
+            if (hasJustificationTokenInText(migText)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a migration inserting it; no query/paginate of ${d.source} is visible, but the migration file carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a migration inserting it, but no query/paginate of the source table ${d.source} is visible, and no written JUSTIFIÉ:/JUSTIFIED: token in the migration file — coverage of existing source rows owes a fix or a recorded justification`,
+                });
+            }
         }
         else if (referenced) {
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table} has a backfill migration NAMED for it, but it writes the structure via a helper (no direct ctx.db.insert("${d.table}") in the migration) — its idempotence/coverage of existing source rows is not statically decidable (human verifies)`,
-            });
+            if (hasJustificationTokenInText(migText)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a backfill migration NAMED for it, writing the structure via a helper; the migration file carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table} has a backfill migration NAMED for it, but it writes the structure via a helper (no direct ctx.db.insert("${d.table}") in the migration), and no written JUSTIFIÉ:/JUSTIFIED: token in the migration file — idempotence/coverage owes a fix or a recorded justification`,
+                });
+            }
         }
         else {
             scan.violate.push({
@@ -154,10 +178,12 @@ export const R44 = srcDetector("R-44", "R-44 a derived structure carries a same-
 // R-45 — a derived structure carries a test whose fixture bypasses the write
 // path and brackets the migration.
 // ===========================================================================
+const R45_TOKEN_WINDOW = 6;
 export function scanR45(files) {
     const scan = emptyScan();
     const derived = derivedStructures(files);
     const testFiles = files.filter(isTest);
+    const byRel = new Map(files.map((f) => [f.rel, f]));
     for (const d of derived) {
         const insertSourceRe = INSERT_OF(d.source);
         const stem = d.table.toLowerCase();
@@ -200,13 +226,32 @@ export function scanR45(files) {
             });
         }
         else {
-            // No test reaches the subject at all — the test-independence property
-            // cannot be judged. A could-not-judge work-item, never a silent green.
-            scan.cnj.push({
-                rel: d.rel,
-                n: d.n,
-                note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path (and no create-only fixture to mark red) — its fixture-independence is not statically decidable; a human must verify a test brackets the migration before AND after`,
-            });
+            // No test reaches the subject at all — flagged. judgement retired
+            // (task k179jnhx, §23): the schema declaration's comment window is this
+            // site's remediation cell. No JUSTIFIÉ:/JUSTIFIED: token → non-conforming;
+            // token present → present, decided by the token's presence, never a
+            // person's opinion of whether the untested state is sound.
+            const declFile = byRel.get(d.rel);
+            const window = declFile
+                ? declFile.lines
+                    .slice(Math.max(0, d.n - 1 - R45_TOKEN_WINDOW), d.n - 1 + R45_TOKEN_WINDOW)
+                    .map((l) => l.raw)
+                    .join("\n")
+                : "";
+            if (hasJustificationTokenInText(window)) {
+                scan.conform.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path, but the schema declaration's comment window carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed`,
+                });
+            }
+            else {
+                scan.violate.push({
+                    rel: d.rel,
+                    n: d.n,
+                    note: `derived structure ${d.table}: no test constructs its source row ${d.source} without the write path (and no create-only fixture to mark red), and no written JUSTIFIÉ:/JUSTIFIED: token near its schema declaration — fixture-independence owes a test or a recorded justification`,
+                });
+            }
         }
     }
     return scan;

package/dist/detectors/source/contract.js

@@ -18,6 +18,8 @@
 // zero-applicable-site abstain that resolves to could-not-judge WITH a reason.
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { siteCount, withCount } from "../../violation-count.js";
+import { hasJustificationTokenInText } from "../oracle-axis2.js";
 /** The standard all four are pinned against (short hash a9d7877b). */
 export const SOURCE_CONTRACT_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) §15";
 function emptyScan() {
@@ -73,12 +75,12 @@ function decide(ruleId, id, check, scan, emptyReason) {
     const breakdown = `[conform=${nC} non-conforming=${nV} could-not-judge=${nJ}]`;
     const fmt = (s) => s.slice(0, 3).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}${nC ? ` Conform site(s): ${fmt(scan.conform)}.` : ""}`;
@@ -320,15 +322,19 @@ export function scanR25(files) {
 //   authority-tier / boundary-key declaration: rag has only an import comment; the
 //   agentEngine block documents durability/versioning ("long-task survival",
 //   "Pinned exactly at 0.1.0-alpha.2"), not an isolation contract. Per §8 an
-//   undeclared seam is non-conforming as an app-owned table with a blank field —
-//   but the DISPOSITION (whether the library's tables are in fact used
-//   fleet-internal/master only, which would justify the silence) is human. So the
-//   detector flags an undeclared mount as could-not-judge WITH a reason (never a
-//   silent pass); a mount whose window declares an authority tier + boundary key
-//   is conform.
+//   undeclared seam is non-conforming as an app-owned table with a blank field.
+// judgement retired (task k179jnhx, §23): whether the library's tables are in
+// fact used fleet-internal/master only (which would justify the silence) is no
+// longer a human disposition — it decides on the PRESENCE of a written
+// JUSTIFIÉ:/JUSTIFIED: token in the seam's comment window (that window IS this
+// site's remediation cell, the same mechanism R-7/R-8 use on an oracle row). No
+// token → non-conforming; token present → present. could-not-judge is reserved
+// for a seam the instrument could not read, never reached here (a parsed
+// app.use() call always resolves to one of the two).
 // PATTERN: each `app.use(<component>)` line in a *.config.ts seam is conform iff its
 // surrounding window (comments included — the seam contract is documented prose)
-// declares an authority tier + boundary key; else could-not-judge.
+// declares an authority tier + boundary key, OR carries a written justification
+// token; else non-conforming.
 // ---------------------------------------------------------------------------
 const MOUNT_CALL = /app\.use\s*\(\s*(\w+)/;
 const SEAM_CONTRACT = /authority tier|boundary key|isolation contract|org-scoped|fleet-internal|master-only|namespace-bound|tenant boundary/i;
@@ -350,14 +356,16 @@ export function scanR26(files) {
                 continue;
             const comp = m[1];
             // seam contract is documented as prose — scan ALL lines in the window.
-            const declared = f.lines
-                .slice(Math.max(0, i - R26_WINDOW), i + R26_WINDOW)
-                .some((x) => SEAM_CONTRACT.test(x.raw));
+            const window = f.lines.slice(Math.max(0, i - R26_WINDOW), i + R26_WINDOW);
+            const declared = window.some((x) => SEAM_CONTRACT.test(x.raw));
             if (declared) {
                 scan.conform.push({ rel: f.rel, n: l.n, note: `component "${comp}" mount declares an authority tier + boundary key at the seam` });
             }
+            else if (hasJustificationTokenInText(window.map((x) => x.raw).join("\n"))) {
+                scan.conform.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key, but the seam's comment window carries a written JUSTIFIÉ:/JUSTIFIED: token — accepted, not silently passed` });
+            }
             else {
-                scan.cnj.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key at the seam — usable fleet-internal/master only; org-scoped disposition needs a human ruling (§8)` });
+                scan.violate.push({ rel: f.rel, n: l.n, note: `component "${comp}" mounted with no stated authority tier / boundary key at the seam, and no written JUSTIFIÉ:/JUSTIFIED: token in the seam's comment window — usable fleet-internal/master only; §8 owes a fix or a recorded justification` });
             }
         }
     }

package/dist/detectors/source/cross-tenant-write.d.ts

@@ -0,0 +1,46 @@
+import * as ts from "typescript";
+import type { Detector } from "../../engine-types.js";
+import { type FnDef, type Parsed, type SchemaTable, type SrcFile } from "./_ast.js";
+import { type Scan, type SourceDetectorEntry } from "./_scan.js";
+export declare const R52_ID = "R-52 a write reaching a row with no tenant value through a caller-choosable value checks the target's tenant first";
+export declare function fleetOnlyExpr(e0: ts.Expression, isFleetHelper: (name: string) => boolean, isFleetLocal?: (name: string) => boolean): boolean;
+export interface R52Facts {
+    parsed: Parsed[];
+    schema: Map<string, SchemaTable> | undefined;
+    schemaRel: string | undefined;
+    callerChosen: Map<string, Set<string>>;
+    fns: Map<string, FnDef[]>;
+    readsTenant: Set<string>;
+    refusing: Set<string>;
+    /** helpers every truthy return of which is a fleet-scope decision. */
+    fleetOnly: Set<string>;
+    fleetRefusal: Set<string>;
+    singleTable: Map<string, string>;
+    /** helpers that hand their table argument to `db.normalizeId`. */
+    normalizers: Set<string>;
+    /** per table carrying a `namespace` and no required tenant column: whether
+     * that namespace is checked against the caller's allowed prefixes. */
+    namespace: Map<string, NamespaceDecision>;
+}
+/** Standard 2825122 R-52 counts a `namespace` as a tenant column only when it is
+ * "checked against the caller's allowed prefixes". Decided per table from the
+ * public doors (query/mutation/action) that read or write it:
+ *   checked    every door runs a prefix check (or refuses every non-master);
+ *   unchecked  no door does — the namespace is a label, the table is untenanted;
+ *   undecided  some do and some do not, or no public door reaches the table —
+ *              every site targeting it is could-not-judge, never green. */
+export interface NamespaceDecision {
+    verdict: "checked" | "unchecked" | "undecided";
+    why: string;
+}
+export declare function r52Facts(files: SrcFile[]): R52Facts;
+export interface R52Detail {
+    scan: Scan;
+    /** tables carrying no tenant value (none, or optional), as read from schema. */
+    untenanted: string[];
+    schemaRel: string | undefined;
+}
+export declare function scanR52(files: SrcFile[]): Scan;
+export declare function scanR52Detailed(files: SrcFile[]): R52Detail;
+export declare const R52: Detector;
+export declare const SOURCE_CROSS_TENANT_WRITE_DETECTORS: SourceDetectorEntry[];