@vantageos/backend-doctor 0.1.0

package/dist/detectors/source/backfill.js

@@ -0,0 +1,211 @@
+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$/;
+// A migration module — a backfill lives here (convex/migrations.ts or a
+// convex/migrations/ folder).
+const MIGRATION_FILE = /migration/i;
+const TABLE_OPEN = /^\s*([A-Za-z0-9_]+)\s*:\s*defineTable\s*\(/;
+// a field line inside a defineTable block: `name: v.something(`.
+const FIELD_LINE = /^\s*[A-Za-z0-9_]+\s*:\s*v\./;
+// a foreign-key reference to ANOTHER table.
+const ID_REF = /v\.id\s*\(\s*["'`]([A-Za-z0-9_]+)["'`]\s*\)/;
+// any index-bearing method — the side-table signal.
+const HAS_INDEX = /\.(?:index|searchIndex|vectorIndex)\s*\(/;
+// a direct insert of a named table.
+const INSERT_OF = (table) => new RegExp(`ctx\\.db\\.insert\\s*\\(\\s*["'\`]${table}["'\`]`);
+// a query/paginate of a named table (loops the source rows).
+const QUERY_OF = (table) => new RegExp(`\\.(?:query|paginate)\\s*\\(\\s*["'\`]${table}["'\`]`);
+// a create-through-the-write-path reference in a test — a `createX` mutation the
+// fixture drives (directly or via `t.mutation(api.mod.createX, ...)`), the write
+// path that populates the derived structure as a side effect. Requires an
+// upper-case letter after `create` so `createdAt`/`created` never match.
+const CREATE_CALL = /\bcreate[A-Z][A-Za-z0-9_]*/;
+/** a test / __tests__ file — R-45's material (the opposite selection of
+ * isJudgeable, which EXCLUDES tests). */
+function isTest(f) {
+    return base(f.rel).endsWith(".test.ts") || f.rel.includes("__tests__");
+}
+/**
+ * Parse schema.ts defineTable blocks and select the DERIVED STRUCTURES: a thin
+ * side/junction table (≤4 fields) that carries a foreign-key v.id("<other>")
+ * AND is index-bearing. This is the junction / index-bearing side-table class
+ * R-44 names — deliberately NOT a rich domain table (tasks, missions) which
+ * carries many fields, and NOT a table that is its own FK target.
+ */
+export function derivedStructures(files) {
+    const out = [];
+    for (const f of files) {
+        if (!isJudgeable(f))
+            continue;
+        if (!SCHEMA_FILE.test(f.rel))
+            continue;
+        let name = "";
+        let openLine = 0;
+        let fields = 0;
+        let fkTarget = "";
+        let hasIndex = false;
+        const flush = () => {
+            if (!name)
+                return;
+            // a derived structure: thin, foreign-keyed, index-bearing, and its FK
+            // points at ANOTHER table (not itself).
+            if (fields > 0 &&
+                fields <= 4 &&
+                fkTarget &&
+                fkTarget !== name &&
+                hasIndex) {
+                out.push({ table: name, source: fkTarget, rel: f.rel, n: openLine });
+            }
+        };
+        for (const l of f.lines) {
+            const open = TABLE_OPEN.exec(l.raw);
+            if (open) {
+                flush();
+                name = open[1];
+                openLine = l.n;
+                fields = 0;
+                fkTarget = "";
+                hasIndex = false;
+                continue;
+            }
+            if (!name)
+                continue;
+            if (FIELD_LINE.test(l.raw))
+                fields += 1;
+            const id = ID_REF.exec(l.raw);
+            if (id && !fkTarget)
+                fkTarget = id[1];
+            if (HAS_INDEX.test(l.raw))
+                hasIndex = true;
+        }
+        flush();
+    }
+    return out;
+}
+// ===========================================================================
+// R-44 — a derived structure carries a same-delivery idempotent backfill.
+// ===========================================================================
+export function scanR44(files) {
+    const scan = emptyScan();
+    const derived = derivedStructures(files);
+    const migFiles = files.filter((f) => isJudgeable(f) && MIGRATION_FILE.test(f.rel));
+    for (const d of derived) {
+        const insertRe = INSERT_OF(d.table);
+        const queryRe = QUERY_OF(d.source);
+        const stem = d.table.toLowerCase();
+        let directInsert = false;
+        let loopsSource = false;
+        let referenced = false;
+        for (const f of migFiles) {
+            for (const l of f.lines) {
+                if (!code(l))
+                    continue;
+                if (insertRe.test(l.raw))
+                    directInsert = true;
+                if (queryRe.test(l.raw))
+                    loopsSource = true;
+                // a backfill function / identifier naming the derived table (the
+                // write may be via a helper, e.g. syncParticipantIndex).
+                if (l.raw.toLowerCase().includes(stem))
+                    referenced = true;
+            }
+        }
+        if (directInsert && loopsSource) {
+            scan.conform.push({
+                rel: d.rel,
+                n: d.n,
+                note: `derived structure ${d.table} has a backfill migration that loops the source table ${d.source} and inserts ${d.table} directly — populates existing rows`,
+            });
+        }
+        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)`,
+            });
+        }
+        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)`,
+            });
+        }
+        else {
+            scan.violate.push({
+                rel: d.rel,
+                n: d.n,
+                note: `derived structure ${d.table} (computed from ${d.source}) has NO backfill migration — it is populated only by the write path, so it is inert for every row that predates that path (R-44 inert-fix defect)`,
+            });
+        }
+    }
+    return scan;
+}
+export const R44 = srcDetector("R-44", "R-44 a derived structure carries a same-delivery idempotent migration that backfills it from existing source rows", "every derived structure (junction / index-bearing side table) has a backfill migration that populates it from the existing source rows", scanR44, "R-44: no derived structure (a thin, foreign-keyed, index-bearing side/junction table) matched in the scanned tree — cannot certify backfill coverage. NOT a clean bill.");
+// ===========================================================================
+// R-45 — a derived structure carries a test whose fixture bypasses the write
+// path and brackets the migration.
+// ===========================================================================
+export function scanR45(files) {
+    const scan = emptyScan();
+    const derived = derivedStructures(files);
+    const testFiles = files.filter(isTest);
+    for (const d of derived) {
+        const insertSourceRe = INSERT_OF(d.source);
+        const stem = d.table.toLowerCase();
+        const srcStem = d.source.toLowerCase();
+        let directSourceInsert = false;
+        let referencesSubject = false;
+        let hasCreateFixture = false;
+        for (const f of testFiles) {
+            for (const l of f.lines) {
+                if (!code(l))
+                    continue;
+                const low = l.raw.toLowerCase();
+                if (low.includes(stem) || low.includes(srcStem))
+                    referencesSubject = true;
+                if (insertSourceRe.test(l.raw))
+                    directSourceInsert = true;
+                if (CREATE_CALL.test(l.raw))
+                    hasCreateFixture = true;
+            }
+        }
+        if (directSourceInsert) {
+            // The decidable half of R-45 — a fixture constructs the source row WITHOUT
+            // the write path (a direct ctx.db.insert of the source table). Whether it
+            // brackets the migration before AND after is the human half; the fixture
+            // independence R-45's static half owns is present.
+            scan.conform.push({
+                rel: d.rel,
+                n: d.n,
+                note: `derived structure ${d.table}: a test constructs the source row ${d.source} via a direct ctx.db.insert (bypassing the write path) — the fixture-independence R-45 requires is present`,
+            });
+        }
+        else if (referencesSubject && hasCreateFixture) {
+            // The PR #1200 defect exactly: the subject is tested, but ONLY through the
+            // write path (create), so the suite is structurally incapable of failing
+            // on the pre-migration state.
+            scan.violate.push({
+                rel: d.rel,
+                n: d.n,
+                note: `derived structure ${d.table} is exercised by tests, but EVERY fixture is built through the write path (create) — no direct ctx.db.insert("${d.source}") bypass, so the suite cannot fail on the pre-migration (inert) state (R-45 defect)`,
+            });
+        }
+        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`,
+            });
+        }
+    }
+    return scan;
+}
+export const R45 = srcDetector("R-45", "R-45 a derived structure carries a test that constructs the source row without the write path and brackets the migration", "at least one test builds the source row via a direct ctx.db.insert (not create) and asserts before AND after the migration", scanR45, "R-45: no derived structure matched in the scanned tree — no fixture-independence to certify. NOT a clean bill.");
+/** In the form the orchestrator spreads into REGISTRY. */
+export const SOURCE_BACKFILL_DETECTORS = [
+    { detector: R44, ruleId: "R-44", standardPin: SOURCE_STANDARD_PIN },
+    { detector: R45, ruleId: "R-45", standardPin: SOURCE_STANDARD_PIN },
+];

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

@@ -0,0 +1,33 @@
+import type { Detector, Tree } from "../../engine-types.js";
+/** The standard all four are pinned against (short hash a9d7877b). */
+export declare const SOURCE_CONTRACT_STANDARD_PIN = "analysis/vantagepeers/backend-standard/backend-standard.md @ a9d7877b4947ed8ae61d234433debb2182a2ba44 (elpiarthera/ElPi-Corp) \u00A715";
+type SrcFile = Tree["files"][number];
+/** A registrable entry — structurally mirrors registry.ts's RegistryEntry so the
+ * orchestrator owns the integration; we do NOT import registry.ts. */
+export interface SourceDetectorEntry {
+    detector: Detector;
+    ruleId: string;
+    standardPin: string;
+}
+interface Site {
+    rel: string;
+    n: number;
+    note: string;
+}
+interface Scan {
+    conform: Site[];
+    violate: Site[];
+    cnj: Site[];
+}
+export declare function scanR11(files: SrcFile[]): Scan;
+export declare function scanR24(files: SrcFile[]): Scan;
+export declare function scanR25(files: SrcFile[]): Scan;
+export declare function scanR26(files: SrcFile[]): Scan;
+export declare const R11: Detector;
+export declare const R24: Detector;
+export declare const R25: Detector;
+export declare const R26: Detector;
+/** The four, in a form the orchestrator spreads into REGISTRY. */
+export declare const SOURCE_CONTRACT_DETECTORS: SourceDetectorEntry[];
+export declare function contractRootProbe(root: string): boolean;
+export {};

package/dist/detectors/source/contract.js

@@ -0,0 +1,385 @@
+// The FOUR SOURCE-TREE contract/isolation detectors — R-11, R-24, R-25, R-26.
+//
+// Same kind as the six in security.ts: each reads the REAL backend SOURCE the
+// engine hands it in `run(tree)` — it does NOT consult the oracle CSV. Every
+// predicate below is derived from the ACTUAL convex source at
+// /root/coding/vantage-memory/convex, NEVER from the standard's §15 prose. Where
+// the standard's illustration disagrees with the source, the SOURCE wins and the
+// detector records the stale line (see R-11's stale note).
+//
+// THE LAW (the one that caught R-5 and found §9a stale): a scan that matched no
+// applicable site abstains with a machine-readable reason — never a silent pass;
+// a concrete violation is a real file:line and outranks an abstain; every
+// zero-count branch names the real site it matched so the branch is reachable;
+// predicates read EXECUTING lines (never a comment-only line), so a neuter of the
+// guard lands on code.
+//
+// Three states only (present / non-conforming / could-not-judge), plus the
+// zero-applicable-site abstain that resolves to could-not-judge WITH a reason.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/** 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() {
+    return { conform: [], violate: [], cnj: [] };
+}
+/** basename of a `rel` path, lower-cased. */
+function base(rel) {
+    return (rel.split("/").pop() ?? rel).toLowerCase();
+}
+/** a source file we should judge — never a test or generated file. */
+function isJudgeable(f) {
+    const b = base(f.rel);
+    return !b.endsWith(".test.ts") && !f.rel.includes("__tests__") && !f.rel.includes("_generated/");
+}
+/** an EXECUTING line (not a comment-only line) — predicates read code, not prose. */
+function code(l) {
+    return !l.comment;
+}
+/** true when `rel` lives under a convex/ path (or IS a bare convex file name when
+ * the engine hands relative paths rooted at the convex dir). */
+function isConvex(f) {
+    return /(^|\/)convex\//.test(f.rel) || (!f.rel.includes("/") && f.rel.endsWith(".ts"));
+}
+/** index of the start of the enclosing top-level declaration (an export or a
+ * function) — a guard/index at the handler TOP is in scope for a site deep in the
+ * same handler, so scans bound their backward search here, not at a fixed window. */
+const DECL_HEAD = /^\s*export (const|default|async function|function)\b|^\s*(async )?function \w/;
+function enclosingStart(lines, i) {
+    for (let j = i; j >= 0; j--) {
+        if (code(lines[j]) && DECL_HEAD.test(lines[j].raw))
+            return j;
+    }
+    return 0;
+}
+/** exclusive end of the enclosing declaration — the next top-level head, else EOF. */
+function blockEnd(lines, i) {
+    for (let j = i + 1; j < lines.length; j++) {
+        if (code(lines[j]) && DECL_HEAD.test(lines[j].raw))
+            return j;
+    }
+    return lines.length;
+}
+/**
+ * Reduce a scan to ONE engine DetectorResult. Precedence for the SOURCE kind: a
+ * concrete VIOLATION site is decisive (a found bad site is never a silent pass);
+ * else any could-not-judge → could-not-judge WITH a reason; else any conform site
+ * → present; else zero applicable sites → could-not-judge naming the empty scan.
+ */
+function decide(ruleId, id, check, scan, emptyReason) {
+    const nC = scan.conform.length;
+    const nV = scan.violate.length;
+    const nJ = scan.cnj.length;
+    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 {
+            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)}.` : ""}`,
+        };
+    }
+    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)}.` : ""}`;
+        return { id, anchor: `${scan.cnj[0].rel}:${scan.cnj[0].n}`, state: "could-not-judge", verdict: reason, reason };
+    }
+    if (nC > 0) {
+        return {
+            id,
+            anchor: `${scan.conform[0].rel}:${scan.conform[0].n}`,
+            state: "present",
+            verdict: `${ruleId}: ${nC} applicable site(s) conform (${check}); 0 violations. ${breakdown} Conform: ${fmt(scan.conform)}.`,
+        };
+    }
+    return { id, anchor: "source:no-applicable-site", state: "could-not-judge", verdict: emptyReason, reason: emptyReason };
+}
+// ---------------------------------------------------------------------------
+// R-11 — isolation locus: the tenant boundary is an index-range predicate INSIDE
+// the query (`.withIndex(...).eq("<scopeKey>", ...)`), never a post-query handler
+// filter. (standard §15 line 400 / §17 line 501 — "40 filterByOrgScope(in-handler,
+// post-query) rows".)
+//
+// SOURCE READ (the LAW — derived from the ACTUAL handlers, not §17's count):
+//   - convex/messages.ts:282 and :422 — after merging instanceReceipts (queried
+//     by `by_instance_unread`) with roleReceipts (`by_recipient_unread`), the
+//     handler does `receipts = receipts.filter((r) => r.tenantId === args.tenantId)`.
+//     NO `.withIndex(... .eq("tenantId" ...))` precedes it — the comment itself
+//     admits "No tenant+instance index — JS filter". This is the R-11 defect.
+//   - convex/messages.ts:699 — `rows.filter((r) => r.tenantId === orgSlug)` IS
+//     preceded (line 691) by `.withIndex("by_tenant_created", q => q.eq("tenantId",
+//     orgSlug))`; it is a belt-and-suspenders pass over an already-indexed scope.
+//   - convex/messages.ts:958 and convex/briefingNotes.ts:310 — same shape: a
+//     post-query `.filter` on tenantId/orgId sitting AFTER a
+//     `.withSearchIndex(... .eq("tenantId"/"orgId", scope.orgSlug))`.
+//   - convex/tasks.ts (list) — uses `.withIndex` for every scope read; conform.
+//
+// STALE-LINE FINDING: §17 line 501 tallies "40 post-query isolation filters CAUGHT"
+// as though every filterByOrgScope row is a live defect. The CURRENT source has
+// remediated the majority — messages:699/958 and briefingNotes:310 now pair the
+// post-query filter with an adjacent index-range predicate on the SAME scope key
+// (belt-and-suspenders), so they are conform. Only the instance-merge branch
+// (messages:282/422), which has no tenant index, remains a true R-11 defect. The
+// SOURCE wins; the "40 CAUGHT" count is stale relative to the current handlers.
+//
+// PATTERN derived from the source: a line applying a `.filter(...)` whose predicate
+// references a scope key (tenantId | orgId | orgSlug | namespace) is CONFORM iff a
+// `.withIndex`/`.withSearchIndex` carrying `.eq("<sameScopeKey>", ...)` occurs in
+// the preceding code window; otherwise it is the post-query-filter VIOLATION.
+// ---------------------------------------------------------------------------
+const SCOPE_KEYS = ["tenantId", "orgId", "orgSlug", "namespace"];
+const SCOPE_FILTER = /\.filter\s*\(/;
+const INDEX_CALL = /\.(withIndex|withSearchIndex)\s*\(/;
+function scopeKeyOnFilterLine(raw) {
+    if (!SCOPE_FILTER.test(raw))
+        return null;
+    // only the arrow-predicate portion after `.filter(` counts as the filter body.
+    const body = raw.slice(raw.search(SCOPE_FILTER));
+    for (const k of SCOPE_KEYS) {
+        if (new RegExp(`\\b${k}\\b`).test(body))
+            return k;
+    }
+    return null;
+}
+/** true when the enclosing handler binds `key` as an index-range predicate before
+ * the post-query filter at line i. */
+function precededByIndexOnKey(lines, i, key) {
+    let sawIndex = false;
+    let sawEq = false;
+    for (let j = enclosingStart(lines, i); j < i; j++) {
+        const l = lines[j];
+        if (!code(l))
+            continue;
+        if (INDEX_CALL.test(l.raw))
+            sawIndex = true;
+        if (new RegExp(`\\.eq\\(\\s*["'\`]${key}["'\`]`).test(l.raw))
+            sawEq = true;
+    }
+    return sawIndex && sawEq;
+}
+export function scanR11(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvex(f))
+            continue;
+        for (let i = 0; i < f.lines.length; i++) {
+            const l = f.lines[i];
+            if (!code(l))
+                continue;
+            const key = scopeKeyOnFilterLine(l.raw);
+            if (!key)
+                continue;
+            if (precededByIndexOnKey(f.lines, i, key)) {
+                scan.conform.push({ rel: f.rel, n: l.n, note: `post-query .filter on ${key} paired with an adjacent .withIndex/.withSearchIndex .eq("${key}") — belt-and-suspenders over an indexed scope` });
+            }
+            else {
+                scan.violate.push({ rel: f.rel, n: l.n, note: `in-handler .filter on scope key ${key} with NO .withIndex on that key — post-query isolation filter (R-11 defect)` });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-24 — a filter-selected bulk-write defaults to a dry run and applies only on an
+// explicit confirm flag, with a caller-required guard. (standard §15 line 413.)
+//
+// SOURCE READ: convex/tasks.ts `bulkComplete` (export at line 2104):
+//   - line 2139 `const dryRun = args.dryRun !== false;` — defaults dryRun TRUE.
+//   - lines 2142-2145 `if (!dryRun && !args.callerOrchestrator) throw ... BULK_
+//     CALLER_REQUIRED` — the live path requires an explicit caller.
+//   - line 2234 `if (dryRun) { ... }` preview; line 2246 the mutate path behind
+//     `dryRun=false`.
+// PATTERN: a mutation whose export name contains "bulk" must, in its handler body,
+// (a) default dryRun safe (`args.dryRun !== false` / `args.dryRun ?? true`) and
+// (b) key writes behind that flag with a caller-required guard. (a) absent →
+// violation (a bulk-write that applies by default); (a) present but (b) absent →
+// could-not-judge (safe-by-default but no caller guard statically confirmed).
+// ---------------------------------------------------------------------------
+const DRYRUN_DEFAULT_SAFE = /dryRun\s*=\s*args\.dryRun\s*!==\s*false|args\.dryRun\s*\?\?\s*true|dryRun\s*=\s*args\.dryRun\s*===\s*true\s*\?[^:]*:\s*true/;
+const CALLER_GUARD = /!\s*dryRun\s*&&\s*!\s*args\.\w+|BULK_CALLER_REQUIRED|callerOrchestrator/;
+/** slice a file into top-level `export const NAME = ...` blocks. */
+function exportBlocks(lines) {
+    const heads = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!code(lines[i]))
+            continue;
+        const m = lines[i].raw.match(/^export const (\w+)\s*=/);
+        if (m)
+            heads.push({ name: m[1], idx: i });
+    }
+    return heads.map((h, k) => ({ name: h.name, start: h.idx, end: k + 1 < heads.length ? heads[k + 1].idx : lines.length }));
+}
+export function scanR24(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConvex(f))
+            continue;
+        for (const blk of exportBlocks(f.lines)) {
+            if (!/bulk/i.test(blk.name))
+                continue;
+            const body = f.lines.slice(blk.start, blk.end);
+            const isMutation = body.some((l) => code(l) && /\bmutation\s*\(/.test(l.raw));
+            if (!isMutation)
+                continue;
+            const defLine = body.find((l) => code(l) && DRYRUN_DEFAULT_SAFE.test(l.raw));
+            const guardLine = body.find((l) => code(l) && CALLER_GUARD.test(l.raw));
+            const anchorN = f.lines[blk.start].n;
+            if (!defLine) {
+                scan.violate.push({ rel: f.rel, n: anchorN, note: `bulk-write mutation "${blk.name}" does not default dryRun safe — applies by default (unbounded blast radius)` });
+            }
+            else if (!guardLine) {
+                scan.cnj.push({ rel: f.rel, n: defLine.n, note: `bulk-write "${blk.name}" defaults dryRun safe but no caller-required guard found on the live path — not statically confirmed` });
+            }
+            else {
+                scan.conform.push({ rel: f.rel, n: defLine.n, note: `bulk-write "${blk.name}" defaults dryRun true and gates apply behind an explicit flag + caller-required guard (line ${guardLine.n})` });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-25 — a minted storage address or a cross-boundary signed bundle is org-bound
+// and checked at BOTH mint and redemption (with an expiry on the minted URL).
+// (standard §15 line 414 / §16 line 258.)
+//
+// SOURCE READ:
+//   - MINT convex/kbMutations.ts `generateUploadUrl` — line 164
+//     `assertOrgArgs(args.orgId, ...)` precedes line 165
+//     `ctx.storage.generateUploadUrl()`: the mint is org-bound.
+//   - MINT convex/okfBundleNode.ts `exportOkfBundle` — line 314
+//     `assertCanExportNamespace(ctx, args.namespace)` precedes the getUrl mint at
+//     line 447; expiry via `ttlSeconds`/`urlExpiresAt` (lines 455-463) +
+//     scheduled deleteExpiredStorage.
+//   - REDEEM convex/okfBundleNode.ts `importOkfBundle` — line 888
+//     `assertCanImport(ctx, args.targetNamespace)` precedes the storage.get/fetch
+//     at lines 907/916: the redemption end is org-bound too.
+// PATTERN: a storage mint (`storage.generateUploadUrl` | `storage.getUrl` |
+// `storage.store`) or a redemption (`storage.get(` in an import handler) must have
+// an org-binding guard (assertOrgArgs | assertCanExport* | assertCanImport |
+// AUTH_NAMESPACE_DENIED | AUTH_NO_ORG) in the preceding window. Absent → violation.
+// A bundle-export mint (getUrl/store) org-bound but with NO expiry token in the
+// handler → could-not-judge (expiry not statically confirmed).
+// ---------------------------------------------------------------------------
+const MINT_TOKEN = /storage\.(generateUploadUrl|getUrl|store)\s*\(/;
+const REDEEM_TOKEN = /storage\.get\s*\(/;
+// org-binding guards seen in the real source: assertOrgArgs (kb), assertCan* (okf
+// export/import/validate all funnel through assertCanExportNamespace), and the
+// fail-closed error tokens they throw.
+const ORG_BIND_GUARD = /assertOrgArgs|assertCan\w+|AUTH_NAMESPACE_DENIED|AUTH_NO_ORG/;
+const EXPIRY_TOKEN = /ttl|expir|urlExpiresAt|DEFAULT_URL_TTL/i;
+function isArtifactFile(f) {
+    const b = base(f.rel);
+    return /^kb/.test(b) || /okfbundle/.test(b);
+}
+/** the enclosing handler binds the artifact to a verified org before line i. */
+function guardedBefore(lines, i) {
+    for (let j = enclosingStart(lines, i); j <= i; j++) {
+        if (code(lines[j]) && ORG_BIND_GUARD.test(lines[j].raw))
+            return lines[j].n;
+    }
+    return 0;
+}
+export function scanR25(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isArtifactFile(f))
+            continue;
+        for (let i = 0; i < f.lines.length; i++) {
+            const l = f.lines[i];
+            if (!code(l))
+                continue;
+            const isMint = MINT_TOKEN.test(l.raw);
+            const isRedeem = !isMint && REDEEM_TOKEN.test(l.raw);
+            if (!isMint && !isRedeem)
+                continue;
+            const guardLine = guardedBefore(f.lines, i);
+            if (!guardLine) {
+                scan.violate.push({ rel: f.rel, n: l.n, note: `${isMint ? "storage mint" : "bundle redemption"} with no org-binding guard (assertOrgArgs/assertCanExport/assertCanImport) in the preceding window` });
+                continue;
+            }
+            const isBundleMint = /storage\.(getUrl|store)\s*\(/.test(l.raw);
+            const hasExpiry = f.lines.slice(enclosingStart(f.lines, i), blockEnd(f.lines, i)).some((x) => code(x) && EXPIRY_TOKEN.test(x.raw));
+            if (isBundleMint && !hasExpiry) {
+                scan.cnj.push({ rel: f.rel, n: l.n, note: `bundle mint org-bound at line ${guardLine} but no expiry (ttl/urlExpiresAt) token found in the handler — expiry not statically confirmed` });
+            }
+            else {
+                scan.conform.push({ rel: f.rel, n: l.n, note: `${isMint ? "mint" : "redemption"} org-bound by guard at line ${guardLine}${isBundleMint ? " + expiry present" : ""}` });
+            }
+        }
+    }
+    return scan;
+}
+// ---------------------------------------------------------------------------
+// R-26 — a library-owned (component) table declares its boundary (authority tier +
+// boundary key) at the component seam; absent that declaration a component is used
+// fleet-internal/master only, never org-scoped on trust. (standard §15 line 415 /
+// §8 line 137 / §17 line 506.)
+//
+// SOURCE READ: convex/convex.config.ts is the mount seam —
+//   `app.use(rag)` and `app.use(agentEngine)`. Neither mount carries an
+//   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.
+// 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.
+// ---------------------------------------------------------------------------
+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;
+const R26_WINDOW = 6;
+function isConfigSeam(f) {
+    return /\.config\.ts$/.test(base(f.rel));
+}
+export function scanR26(files) {
+    const scan = emptyScan();
+    for (const f of files) {
+        if (!isJudgeable(f) || !isConfigSeam(f))
+            continue;
+        for (let i = 0; i < f.lines.length; i++) {
+            const l = f.lines[i];
+            if (!code(l))
+                continue;
+            const m = l.raw.match(MOUNT_CALL);
+            if (!m)
+                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));
+            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 {
+                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)` });
+            }
+        }
+    }
+    return scan;
+}
+// ---- detector wrappers ----------------------------------------------------
+function srcDetector(ruleId, id, check, scanFn, emptyReason) {
+    return { id, run: (tree) => decide(ruleId, id, check, scanFn(tree.files), emptyReason) };
+}
+export const R11 = srcDetector("R-11", "R-11 tenant isolation is an in-query index predicate, not a post-query filter", "a .filter on a scope key is paired with an adjacent .withIndex/.withSearchIndex .eq on that key", scanR11, "R-11: zero scope-key .filter sites matched in the scanned convex tree — cannot certify the isolation locus. NOT a clean bill.");
+export const R24 = srcDetector("R-24", "R-24 filter-selected bulk-write defaults to dry run", "a bulk-write mutation defaults dryRun true and gates apply behind an explicit flag + caller guard", scanR24, "R-24: zero bulk-write mutations matched in the scanned convex tree — cannot certify dry-run-by-default. NOT a clean bill.");
+export const R25 = srcDetector("R-25", "R-25 minted address / cross-boundary bundle org-bound at both ends", "a storage mint or bundle redemption is org-bound by an auth guard; a minted bundle URL expires", scanR25, "R-25: zero storage mint/redemption sites matched (kb*/okfBundle*) — cannot certify org-binding. NOT a clean bill.");
+export const R26 = srcDetector("R-26", "R-26 library-owned component declares its seam boundary", "each app.use(component) seam declares an authority tier + boundary key", scanR26, "R-26: no component mount seam (*.config.ts app.use) found — cannot certify the component seam contract. NOT a clean bill.");
+/** The four, in a form the orchestrator spreads into REGISTRY. */
+export const SOURCE_CONTRACT_DETECTORS = [
+    { detector: R11, ruleId: "R-11", standardPin: SOURCE_CONTRACT_STANDARD_PIN },
+    { detector: R24, ruleId: "R-24", standardPin: SOURCE_CONTRACT_STANDARD_PIN },
+    { detector: R25, ruleId: "R-25", standardPin: SOURCE_CONTRACT_STANDARD_PIN },
+    { detector: R26, ruleId: "R-26", standardPin: SOURCE_CONTRACT_STANDARD_PIN },
+];
+// Co-artifact reader retained for parity with security.ts's evalR36 shape — the
+// contract detectors are tree-only, but the orchestrator may pass a root probe.
+export function contractRootProbe(root) {
+    return existsSync(join(root, "convex", "convex.config.ts")) || existsSync(join(root, "convex.config.ts"));
+}