connections-arkitect 0.3.4

package/src/checks/hosted/db-justify-existence.mjs

@@ -0,0 +1,237 @@
+// HOSTED check — the generic justify-existence governor for a live Postgres DB (distilled from
+// Connections' internal live-DB governor). Runs ONLY through the MCP vault (domain:"hosted" → skipped
+// standalone). Judges every table on the 3-axis model (exact DATA rows × external APP-CODE refs ×
+// internal DB refs) against the user's spine, and emits the 5 verdicts + a review-only remediation
+// block. READ-ONLY — it never mutates the DB.
+//
+// Gating: `gating: true` + severity does the work. Default severities top out at "warning" (advisory
+// governance), so the check never gates. With `hosted.failOnBounty: true` (or --fail-on-bounty),
+// CONDEMNED / PROVE-OR-DIE escalate to gating errors — the CI / pre-deploy posture.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createFinding } from "../../core/finding.mjs";
+import { walkFiles } from "../../core/fs-walk.mjs";
+import { loadSpine, resolveClaim } from "../../core/hosted/spine.mjs";
+import { judgeObject, verdictSeverity, VERDICT_RANK } from "../../core/hosted/judge.mjs";
+import { vaultRdsQuery } from "../../core/hosted/vault-exec.mjs";
+
+// Exact per-table row count (query_to_xml so one round trip covers every table) + physical size.
+// n_live_tup is an ANALYZE-dependent ESTIMATE — a stale-stats table would read 0 rows, judge "inert",
+// and earn a wrongful CONDEMNED; exactness is the whole point of the DATA axis.
+const TABLES_SQL = `
+  SELECT c.relname AS name,
+         (xpath('/row/cnt/text()', query_to_xml(format('SELECT count(*) AS cnt FROM public.%I', c.relname), false, true, '')))[1]::text::bigint AS rows,
+         pg_total_relation_size(c.oid) AS bytes
+  FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE n.nspname = 'public' AND c.relkind = 'r' ORDER BY c.relname`;
+const INTERNAL_SRC_SQL =
+  "select prosrc as src from pg_proc where pronamespace = 'public'::regnamespace " +
+  "union all select definition as src from pg_views where schemaname = 'public'";
+
+const SUPPORTED_KINDS = new Set(["aurora-postgres-data-api"]);
+const CODE_EXT = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".rs", ".go", ".rb", ".java", ".php", ".sql"]);
+
+export const audit = {
+  id: "db-justify-existence",
+  title: "Database — justify existence (hosted)",
+  category: "governance",
+  domain: "hosted",
+  outputContract: "parsed-findings",
+  requires: {},
+  gating: true,
+  defaultConfig: {},
+  async run(ctx) {
+    const { root, config, vault } = ctx;
+    const failOnBounty = config?.hosted?.failOnBounty === true || ctx.options?.failOnBounty === true;
+    const declared = config?.hosted?.targets || [];
+    const targets = declared.filter((t) => SUPPORTED_KINDS.has(t.kind));
+    const findings = [];
+
+    // A declared target the engine can't reach must be LOUD — silence here reads as "governed" when
+    // nothing was checked at all.
+    for (const t of declared.filter((t) => !SUPPORTED_KINDS.has(t.kind))) {
+      findings.push(
+        createFinding({
+          id: "db-unsupported-target",
+          title: `unsupported hosted target kind: ${t.kind ?? "(none)"}`,
+          severity: "warning",
+          resource: t.database || t.label || "(unnamed target)",
+          message: `hosted.targets entry has kind "${t.kind ?? "(none)"}" — supported: ${[...SUPPORTED_KINDS].join(", ")}. This target was NOT checked.`,
+        }),
+      );
+    }
+    if (!targets.length) return { failed: false, findings, report: findings.length ? renderReport(findings, [], 0) : "" };
+
+    const killOrders = [];
+    const refCounters = new Map(); // appCodeRoots-key → counter fn (memoized per distinct root set)
+    let bountyErrors = 0;
+
+    for (const target of targets) {
+      // The user's spine (the policy — their `your-checks/` for the hosted half). Per-target
+      // `target.spine` wins over the shared `hosted.spine`; paths are repo-relative.
+      const spinePath = target.spine || config?.hosted?.spine || null;
+      let spine = loadSpine({});
+      if (spinePath) {
+        try {
+          spine = loadSpine(JSON.parse(readFileSync(join(root, spinePath), "utf8")));
+        } catch (e) {
+          // A broken spine silently judging everything PROVE-OR-DIE is a policy outage — say so.
+          findings.push(
+            createFinding({
+              id: "db-spine-unreadable",
+              title: `spine unreadable: ${spinePath}`,
+              severity: "warning",
+              resource: target.database || spinePath,
+              message: `Could not read/parse spine "${spinePath}" (${String(e?.message || e).slice(0, 120)}). Every object in ${target.database} is being judged UNRECORDED.`,
+            }),
+          );
+        }
+      }
+      const rootsKey = JSON.stringify(spine.appCodeRoots || []);
+      if (!refCounters.has(rootsKey)) refCounters.set(rootsKey, makeAppRefCounter(root, spine.appCodeRoots, findings));
+      const appRefs = refCounters.get(rootsKey);
+
+      const tables = await vaultRdsQuery(vault, target, TABLES_SQL);
+      if (!tables.length) {
+        // Refuse to emit an all-clear from an empty read — 0 tables means the introspection failed or
+        // pointed at the wrong DB far more often than it means a genuinely empty schema.
+        const sev = failOnBounty ? "error" : "warning";
+        if (sev === "error") bountyErrors++;
+        findings.push(
+          createFinding({
+            id: "db-empty-introspection",
+            title: `introspection returned 0 tables: ${target.database}`,
+            severity: sev,
+            resource: `${target.database}`,
+            account: target.vaultInstance,
+            message: `Introspection of ${target.database} returned 0 tables — refusing to treat an empty read as an all-clear. Verify the target coordinates.`,
+          }),
+        );
+        continue;
+      }
+      const internalSrc = (await vaultRdsQuery(vault, target, INTERNAL_SRC_SQL)).map((r) => String(r.src ?? "")).join("\n");
+
+      for (const t of tables) {
+        const name = String(t.name);
+        const rows = Number(t.rows) || 0;
+        const dbRefs = countOccurrences(internalSrc, name);
+        const codeRefs = appRefs(name);
+        const alive = rows > 0 || dbRefs > 0 || codeRefs > 0;
+        const claim = resolveClaim(spine, name);
+        const verdict = judgeObject({
+          declared: claim.declared,
+          alive,
+          investigate: claim.investigate,
+          claimedRemove: claim.claimedRemove,
+        });
+        const sev = verdictSeverity(verdict, { failOnBounty });
+        if (!sev) continue; // JUSTIFIED
+        if (sev === "error") bountyErrors++;
+        findings.push(
+          createFinding({
+            id: "db-object-verdict",
+            title: `${verdict}: ${name}`,
+            severity: sev,
+            resource: `${target.database}.${name}`,
+            account: target.vaultInstance,
+            verdict,
+            message:
+              `${verdict} — rows=${rows}, app-refs=${codeRefs}, db-refs=${dbRefs}, declared=${claim.declared}` +
+              `${claim.claimedBy ? ` (by ${claim.claimedBy})` : ""}${claim.reason ? ` — ${claim.reason}` : ""}`,
+            fix: verdict === "PROVE-OR-DIE" ? `Add a spine claim for "${name}" or drop it.` : null,
+          }),
+        );
+        if (verdict === "CONDEMNED") {
+          killOrders.push(
+            `-- ${target.database}.${name}: CONDEMNED (rows=${rows}, app-refs=${codeRefs}, db-refs=${dbRefs})\n-- drop table if exists "${name}";  -- REVIEW + previewed read before running`,
+          );
+        }
+      }
+    }
+
+    findings.sort((a, b) => (VERDICT_RANK[a.verdict] ?? 9) - (VERDICT_RANK[b.verdict] ?? 9));
+    const warnings = findings.filter((f) => f.severity === "warning").length;
+    const report = findings.length ? renderReport(findings, killOrders, warnings) : "";
+    return { failed: bountyErrors > 0, findings, report };
+  },
+};
+
+function renderReport(findings, killOrders, warnings) {
+  return (
+    `# DB justify-existence\n\n${findings.map((f) => `- ${f.verdict ?? f.severity.toUpperCase()}  ${f.resource} — ${f.message}`).join("\n")}` +
+    (killOrders.length
+      ? `\n\n## Remediation — REVIEW + previewed read before running (never auto-executed)\n\n\`\`\`sql\n${killOrders.join("\n\n")}\n\`\`\``
+      : "") +
+    `\n\nErrors: ${findings.filter((f) => f.severity === "error").length}\nWarnings: ${warnings}\n`
+  );
+}
+
+// APP-CODE axis — count external references to a table name. Preferred transport: `git grep -w`
+// against the target repo (exact, unbounded, fast — the whole tracked tree, or the spine's
+// appCodeRoots as pathspecs). Fallback for non-git roots: an in-memory blob, bounded — and when the
+// bound truncates, it SAYS so (a silently-truncated axis reads as "unreferenced" and feeds wrongful
+// CONDEMNED verdicts).
+function makeAppRefCounter(root, appCodeRoots, findings) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, stdio: "pipe" });
+    const pathspecs = appCodeRoots && appCodeRoots.length ? appCodeRoots : [];
+    return (name) => {
+      try {
+        const out = execFileSync("git", ["grep", "-lw", "-e", name, "--", ...pathspecs], {
+          cwd: root,
+          encoding: "utf8",
+          maxBuffer: 64 * 1024 * 1024,
+        });
+        return out.split("\n").filter(Boolean).length;
+      } catch {
+        return 0; // git grep exits non-zero on zero matches
+      }
+    };
+  } catch {
+    /* not a git work tree — fall back to the bounded blob */
+  }
+  const { blob, truncated } = readCodeBlob(root, appCodeRoots);
+  if (truncated) {
+    findings.push(
+      createFinding({
+        id: "db-app-axis-truncated",
+        title: "app-code reference axis truncated",
+        severity: "warning",
+        resource: root,
+        message:
+          "Non-git root: the app-code scan hit its file budget before covering the repo — app-refs counts below may UNDERCOUNT. Set spine.appCodeRoots to the real code roots, or run inside a git work tree.",
+      }),
+    );
+  }
+  return (name) => countOccurrences(blob, name);
+}
+
+function readCodeBlob(root, appCodeRoots) {
+  const roots = appCodeRoots && appCodeRoots.length ? appCodeRoots.map((r) => join(root, r)) : [root];
+  let blob = "";
+  let budget = 4000;
+  let truncated = false;
+  for (const r of roots) {
+    for (const file of walkFiles(r)) {
+      if (!CODE_EXT.has(file.slice(file.lastIndexOf(".")))) continue;
+      if (budget-- <= 0) {
+        truncated = true;
+        break;
+      }
+      try {
+        blob += "\n" + readFileSync(file, "utf8");
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  }
+  return { blob, truncated };
+}
+
+function countOccurrences(haystack, name) {
+  if (!name) return 0;
+  const re = new RegExp(`\\b${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g");
+  const m = haystack.match(re);
+  return m ? m.length : 0;
+}

package/src/checks/hosted/db-required-roles.mjs

@@ -0,0 +1,76 @@
+// HOSTED check — required database ROLES exist. Generic breadth-class governance: an application
+// engine that runs `SET LOCAL ROLE <x>` (or grants through a role) on every call hard-fails EVERY
+// request the moment a database is stood up without that role — an outage class that only shows up
+// at runtime, on the newest plane, at the worst time. Declare the roles a target's engine depends on
+// and this check asserts they exist, per target:
+//
+//   "hosted": { "targets": [{ ..., "requiredRoles": ["app_user_role"] }] }
+//
+// No requiredRoles declared ⇒ silently inapplicable. READ-ONLY. Missing roles are definitively-broken
+// states: warning by default, gating errors under hosted.failOnBounty (the CI / pre-deploy posture).
+import { createFinding } from "../../core/finding.mjs";
+import { vaultRdsQuery } from "../../core/hosted/vault-exec.mjs";
+
+export const audit = {
+  id: "db-required-roles",
+  title: "Database — required roles exist (hosted)",
+  category: "governance",
+  domain: "hosted",
+  requires: {},
+  gating: true,
+  defaultConfig: {},
+  async run(ctx) {
+    const { config, vault } = ctx;
+    const failOnBounty = config?.hosted?.failOnBounty === true || ctx.options?.failOnBounty === true;
+    const targets = (config?.hosted?.targets || []).filter(
+      (t) => t.kind === "aurora-postgres-data-api" && Array.isArray(t.requiredRoles) && t.requiredRoles.length,
+    );
+    const findings = [];
+    let errors = 0;
+
+    for (const target of targets) {
+      const wanted = target.requiredRoles.map(String);
+      const inList = wanted.map((r) => `'${r.replace(/'/g, "''")}'`).join(", ");
+      let present;
+      try {
+        present = (await vaultRdsQuery(vault, target, `SELECT rolname FROM pg_roles WHERE rolname IN (${inList})`)).map((r) =>
+          String(r.rolname),
+        );
+      } catch (e) {
+        const sev = failOnBounty ? "error" : "warning";
+        if (sev === "error") errors++;
+        findings.push(
+          createFinding({
+            id: "db-roles-probe-failed",
+            title: `role probe failed: ${target.database}`,
+            severity: sev,
+            resource: target.database,
+            account: target.vaultInstance,
+            message: `Could not read pg_roles on ${target.database} (${String(e?.message || e).slice(0, 140)}) — required roles UNVERIFIED, not a pass.`,
+          }),
+        );
+        continue;
+      }
+      for (const role of wanted.filter((r) => !present.includes(r))) {
+        const sev = failOnBounty ? "error" : "warning";
+        if (sev === "error") errors++;
+        findings.push(
+          createFinding({
+            id: "db-required-role-missing",
+            title: `missing role: ${role} on ${target.database}`,
+            severity: sev,
+            resource: `${target.database} role ${role}`,
+            account: target.vaultInstance,
+            message: `Role "${role}" does not exist on ${target.database} — an engine that SETs/GRANTs through it fails EVERY call on this DB. Create the role before traffic does this for you.`,
+            fix: `CREATE ROLE "${role}"; -- plus the grants your engine's migration normally applies`,
+          }),
+        );
+      }
+    }
+
+    const report = findings.length
+      ? `# DB required roles\n\n${findings.map((f) => `- [${f.severity.toUpperCase()}] ${f.resource} — ${f.message}`).join("\n")}\n`
+      : "";
+    return { failed: errors > 0, findings, report };
+  },
+};

package/src/core/config.mjs

@@ -0,0 +1,50 @@
+// Workspace config loading — ONE implementation for every door (CLI + the MCP runner).
+//
+// Lookup order (first hit wins): <root>/.arkitect/arkitect.config.json (the tucked-away
+// per-workspace placement) then <root>/arkitect.config.json.
+//
+// `extends` (tsconfig/eslint-style): a config may list other config FILES (repo-root-relative) whose
+// contents it inherits — objects deep-merge with the extending file winning, arrays and scalars
+// replace. Lets a workspace layer its Architect config over an existing tool's config file instead of
+// duplicating it (the convergence case: inheriting a legacy engine's paths/checks config verbatim).
+// Chains resolve recursively; cycles are ignored rather than fatal.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+function deepMerge(base, over) {
+  if (Array.isArray(base) || Array.isArray(over) || typeof base !== "object" || typeof over !== "object" || !base || !over) {
+    return over === undefined ? base : over;
+  }
+  const out = { ...base };
+  for (const [k, v] of Object.entries(over)) out[k] = deepMerge(base[k], v);
+  return out;
+}
+
+function loadFile(root, rel, seen, errors) {
+  const abs = join(root, rel);
+  if (seen.has(abs)) return {}; // cycle — inherit nothing twice
+  seen.add(abs);
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(abs, "utf8"));
+  } catch (e) {
+    errors.push({ file: rel, error: String(e?.message || e) });
+    return {};
+  }
+  const bases = Array.isArray(raw.extends) ? raw.extends : raw.extends ? [raw.extends] : [];
+  let merged = {};
+  for (const b of bases) merged = deepMerge(merged, loadFile(root, b, seen, errors));
+  const { extends: _drop, ...own } = raw;
+  return deepMerge(merged, own);
+}
+
+/**
+ * Load the workspace's Architect config (with `extends` resolution).
+ * @returns {{ config: object, path: string|null, errors: Array<{file, error}> }}
+ */
+export function loadWorkspaceConfig(root) {
+  const errors = [];
+  const path = [join(".arkitect", "arkitect.config.json"), "arkitect.config.json"].find((p) => existsSync(join(root, p))) ?? null;
+  if (!path) return { config: {}, path: null, errors };
+  return { config: loadFile(root, path, new Set(), errors), path, errors };
+}

package/src/core/discovery.mjs

@@ -0,0 +1,41 @@
+// Auto-discovery — the heart of the core/extension model. A check is ANY .mjs that exports `audit`
+// with an `id` + `run()`. No registry to edit; the file IS the registration. We scan MULTIPLE roots in
+// priority order and merge: later roots OVERRIDE earlier by id, so a user's `your-checks/` check shadows
+// a core check of the same id (patch a core check without touching the core). The folder name = the group.
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { walkFiles } from "./fs-walk.mjs";
+
+export async function discoverAudits(roots) {
+  const byId = new Map();
+  const loadErrors = [];
+  const shadowed = [];
+  for (const root of roots) {
+    if (!root || !existsSync(root)) continue;
+    for (const file of walkFiles(root)) {
+      if (!file.endsWith(".mjs") || file.endsWith(".test.mjs")) continue;
+      let mod;
+      try {
+        mod = await import(pathToFileURL(file).href);
+      } catch (e) {
+        // A check that won't even load must be LOUD (crash≠silent-pass), never silently dropped.
+        loadErrors.push({ file, error: String(e?.message || e) });
+        continue;
+      }
+      // The canonical export is `audit`, but ANY audit-shaped export registers ({ id, run }) — and a
+      // file may export several (e.g. a defineX() factory producing a family). Zero wiring either way.
+      const candidates = [mod.audit, ...Object.values(mod).filter((v) => v !== mod.audit)];
+      for (const audit of candidates) {
+        if (!audit || typeof audit !== "object" || typeof audit.id !== "string" || typeof audit.run !== "function") continue;
+        if (byId.get(audit.id) === audit) continue; // same object exported under two names
+        if (byId.has(audit.id)) shadowed.push({ id: audit.id, by: file });
+        audit.__file = file;
+        audit.__group = basename(dirname(file));
+        audit.__root = root;
+        byId.set(audit.id, audit);
+      }
+    }
+  }
+  return { audits: [...byId.values()], loadErrors, shadowed };
+}

package/src/core/finding.mjs

@@ -0,0 +1,40 @@
+// The one Finding shape every check emits — for code AND hosted/infra checks. Distilled from arkitect's
+// normalized finding + risk scoring. A check may also return plain objects of this shape; createFinding
+// just fills defaults. Carries infra fields (resource/account/region) so the hosted half reuses it verbatim.
+
+export const SEVERITY = Object.freeze({ error: "error", warning: "warning", info: "info" });
+
+export function createFinding({
+  id,
+  title,
+  severity = "error",
+  file = null,
+  line = null,
+  message = "",
+  resource = null, // hosted: an ARN / table / bucket / role
+  account = null, // hosted: which cloud account
+  region = null,
+  verdict = null, // hosted: JUSTIFIED | WATCH | PROVE-OR-DIE | INVESTIGATE | CONDEMNED
+  fix = null, // a one-line suggested remediation
+} = {}) {
+  return { id, title, severity, file, line, message: message || title, resource, account, region, verdict, fix };
+}
+
+export function countSeverities(findings = []) {
+  let errors = 0,
+    warnings = 0,
+    infos = 0;
+  for (const f of findings) {
+    if (f.severity === "error") errors++;
+    else if (f.severity === "warning") warnings++;
+    else infos++;
+  }
+  return { errors, warnings, infos };
+}
+
+// Cheap risk ordering for the FIX_QUEUE — errors first, then by reachability hints. Kept deliberately
+// simple in Phase 1; the full arkitect risk axes (exposure × data × reachability × safety-net) land in Phase 2.
+export function riskRank(finding) {
+  const sev = finding.severity === "error" ? 0 : finding.severity === "warning" ? 1 : 2;
+  return sev;
+}

package/src/core/fs-walk.mjs

@@ -0,0 +1,24 @@
+// One filesystem walker, reused by discovery + every check (DRY). Skips the usual build/vendor dirs.
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { IGNORE_DIRS, isIgnoredDir } from "./project-detect.mjs";
+
+export function* walkFiles(dir, { ignore = IGNORE_DIRS, includeDotfiles = false } = {}) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (!includeDotfiles && e.name.startsWith(".")) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) {
+      // isIgnoredDir is the canonical generated-output matcher (names + dist-* family + Capacitor
+      // webDir copies); a custom `ignore` set ADDS to it, never re-admits build output.
+      if (!isIgnoredDir(e.name, p) && !ignore.has(e.name)) yield* walkFiles(p, { ignore, includeDotfiles });
+    } else {
+      yield p;
+    }
+  }
+}

package/src/core/hosted/judge.mjs

@@ -0,0 +1,42 @@
+// The generic "justify existence" judge — the 3-axis verdict system distilled from Connections' internal
+// live-DB governor, generalized so it works on ANY live resource (a DB table, an S3 bucket, an IAM role),
+// not just one schema.
+//
+// The model: judge each live object on DATA (rows) × APP-CODE refs × internal refs, against a
+// per-workspace "justify existence" spine. An object is JUSTIFIED only when it is BOTH
+//   • DECLARED — a human wrote down why it exists (a spine claim), AND
+//   • ALIVE    — something actually uses it (holds data, or is referenced by external code, or by another
+//                internal object).
+// An explicit spine verdict (INVESTIGATE / REMOVE) overrides the inference — so a squatter can't be
+// auto-justified by a loose prefix-claim, and a human kill-order is honored.
+
+// Ranked worst→best, for sorting kill-orders.
+export const VERDICT_RANK = Object.freeze({ CONDEMNED: 0, "PROVE-OR-DIE": 1, INVESTIGATE: 2, WATCH: 3, JUSTIFIED: 4 });
+
+/**
+ * Judge ONE object.
+ * @param {object} o
+ * @param {boolean} o.declared      - the spine claims this object (a recorded reason to exist)
+ * @param {boolean} o.alive         - anything references/uses it (rows > 0 OR external ref OR internal ref)
+ * @param {boolean} [o.investigate] - the spine explicitly flags it for human review (overrides)
+ * @param {boolean} [o.claimedRemove] - the spine explicitly orders removal (overrides)
+ * @returns {"JUSTIFIED"|"WATCH"|"PROVE-OR-DIE"|"INVESTIGATE"|"CONDEMNED"}
+ */
+export function judgeObject({ declared, alive, investigate = false, claimedRemove = false }) {
+  if (investigate) return "INVESTIGATE"; // explicit human flag wins
+  if (claimedRemove) return "CONDEMNED"; // explicit kill-order wins
+  if (declared && alive) return "JUSTIFIED"; // recorded AND used
+  if (declared && !alive) return "WATCH"; // recorded but inert — keep an eye on it
+  if (!declared && alive) return "PROVE-OR-DIE"; // used but no recorded reason — earn a spine entry or die
+  return "CONDEMNED"; // unrecorded AND inert
+}
+
+// Verdict → finding severity. This is a read-only GOVERNANCE judgment (recommends, never mutates), so by
+// default the strongest verdicts surface as warnings, the softer ones as info. JUSTIFIED produces no
+// finding. Bounty mode (`hosted.failOnBounty: true` / --fail-on-bounty) escalates CONDEMNED and
+// PROVE-OR-DIE to gating errors so the governor can gate a CI run or a DB-touching deploy.
+export function verdictSeverity(verdict, { failOnBounty = false } = {}) {
+  if (verdict === "CONDEMNED" || verdict === "PROVE-OR-DIE") return failOnBounty ? "error" : "warning";
+  if (verdict === "WATCH" || verdict === "INVESTIGATE") return "info";
+  return null; // JUSTIFIED
+}

package/src/core/hosted/spine.mjs

@@ -0,0 +1,63 @@
+// The "justify existence" SPINE — the user-extension space for the HOSTED half. The user declares WHY
+// each live object exists; the framework judges against it.
+// This is the hosted equivalent of `your-checks/`: the policy is the user's, the engine is the core's.
+//
+// Shape (justify-existence.json):
+// {
+//   "appCodeRoots": ["src", "services"],          // where to grep for external references (default: repo root)
+//   "features": [                                   // each feature CLAIMS the objects it owns
+//     { "name": "billing", "claims": ["invoices", "payment_*"] }
+//   ],
+//   "verdicts": { "legacy_temp": "REMOVE", "weird_table": "INVESTIGATE" }  // explicit overrides
+// }
+// A claim ending in `*` is a prefix claim; otherwise it's an exact name.
+//
+// A second, equivalent dialect is accepted so existing per-plane spines drop in unconverted:
+//   features:  { "id": "billing", "tables": ["invoices"], "tablePrefixes": ["payment"] }
+//   verdicts:  { "legacy_temp": { "verdict": "REMOVE", "reason": "superseded by X" } }
+// `tables` are exact claims, each `tablePrefixes` entry `p` becomes the prefix claim `p*`, and a verdict
+// object's `reason` is carried through to the finding message.
+
+export function loadSpine(json) {
+  const s = json && typeof json === "object" ? json : {};
+  const features = (Array.isArray(s.features) ? s.features : []).map((f) => ({
+    name: f?.name || f?.id || null,
+    claims: [
+      ...(Array.isArray(f?.claims) ? f.claims : []),
+      ...(Array.isArray(f?.tables) ? f.tables : []),
+      ...(Array.isArray(f?.tablePrefixes) ? f.tablePrefixes.map((p) => `${p}*`) : []),
+    ].filter((c) => typeof c === "string" && c.length),
+  }));
+  // Normalize verdict values: "REMOVE" | { verdict: "REMOVE", reason?: "…" } → { verdict, reason }.
+  const verdicts = {};
+  if (s.verdicts && typeof s.verdicts === "object") {
+    for (const [name, v] of Object.entries(s.verdicts)) {
+      if (typeof v === "string") verdicts[name] = { verdict: v.toUpperCase(), reason: null };
+      else if (v && typeof v === "object" && typeof v.verdict === "string")
+        verdicts[name] = { verdict: v.verdict.toUpperCase(), reason: v.reason ?? null };
+    }
+  }
+  return { appCodeRoots: Array.isArray(s.appCodeRoots) && s.appCodeRoots.length ? s.appCodeRoots : null, features, verdicts };
+}
+
+/**
+ * Resolve what the spine says about an object by name.
+ * Explicit `verdicts[name]` overrides any feature claim (so a prefix-claim can't auto-justify a squatter,
+ * and a human REMOVE/INVESTIGATE is honored).
+ * @returns {{ declared: boolean, investigate: boolean, claimedRemove: boolean, claimedBy: string|null, reason: string|null }}
+ */
+export function resolveClaim(spine, name) {
+  const override = spine.verdicts?.[name];
+  if (override?.verdict === "INVESTIGATE")
+    return { declared: true, investigate: true, claimedRemove: false, claimedBy: "verdicts", reason: override.reason ?? null };
+  if (override?.verdict === "REMOVE")
+    return { declared: true, investigate: false, claimedRemove: true, claimedBy: "verdicts", reason: override.reason ?? null };
+
+  for (const f of spine.features || []) {
+    for (const claim of f.claims || []) {
+      const matched = claim.endsWith("*") ? name.startsWith(claim.slice(0, -1)) : claim === name;
+      if (matched) return { declared: true, investigate: false, claimedRemove: false, claimedBy: f.name || claim, reason: null };
+    }
+  }
+  return { declared: false, investigate: false, claimedRemove: false, claimedBy: null, reason: null };
+}

package/src/core/hosted/vault-exec.mjs

@@ -0,0 +1,61 @@
+// Run a READ-ONLY query against the user's OWN cloud DB THROUGH the MCP vault — value-blind: the
+// credential never enters the model context; the MCP injects it server-side (the same seam deploy_static
+// uses). The `vault` handle is provided by the MCP-hosted runner. Standalone (`npx architect`, no MCP)
+// there is no vault, so hosted checks are skipped (see runner.mjs) — the code half still runs.
+//
+// target: { kind:"aurora-postgres-data-api", vaultInstance, resourceArn, secretArn, database, region? }
+
+export async function vaultRdsQuery(vault, target, sql) {
+  if (!vault || typeof vault.awsCall !== "function") {
+    throw new Error("hosted checks require the Connections MCP vault (no vault handle present)");
+  }
+  const res = await vault.awsCall({
+    instance: target.vaultInstance,
+    service: "rds-data",
+    region: target.region || "us-east-1",
+    method: "POST",
+    path: "/Execute",
+    body: JSON.stringify({
+      resourceArn: target.resourceArn,
+      secretArn: target.secretArn,
+      database: target.database,
+      sql,
+      includeResultMetadata: true,
+    }),
+  });
+  return parseRdsRecords(res);
+}
+
+// RDS Data API returns { records: [[{stringValue|longValue|…}, …], …], columnMetadata: [{name},…] }.
+// Flatten to plain {col: value} rows. Pure → unit-testable.
+export function parseRdsRecords(res) {
+  const body = typeof res?.body === "string" ? safeJson(res.body) : (res?.body ?? res);
+  if (!body || !Array.isArray(body.records)) return [];
+  const cols = (body.columnMetadata || []).map((c) => c.name);
+  return body.records.map((rec) => {
+    const row = {};
+    rec.forEach((cell, i) => {
+      row[cols[i] ?? i] = cellValue(cell);
+    });
+    return row;
+  });
+}
+
+function cellValue(cell) {
+  if (!cell || typeof cell !== "object") return cell;
+  if (cell.isNull) return null;
+  if ("stringValue" in cell) return cell.stringValue;
+  if ("longValue" in cell) return cell.longValue;
+  if ("doubleValue" in cell) return cell.doubleValue;
+  if ("booleanValue" in cell) return cell.booleanValue;
+  if ("blobValue" in cell) return cell.blobValue;
+  return null;
+}
+
+function safeJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}

package/src/core/index.mjs

@@ -0,0 +1,15 @@
+// Public API for check authors: `import { createFinding } from "connections-arkitect"`.
+export { createFinding, countSeverities, riskRank, SEVERITY } from "./finding.mjs";
+export { detectProject, checkAppliesToProject, IGNORE_DIRS } from "./project-detect.mjs";
+export { walkFiles } from "./fs-walk.mjs";
+export { discoverAudits } from "./discovery.mjs";
+export { runAudits } from "./runner.mjs";
+export { toSarif } from "./sarif.mjs";
+export { runFamilyConformance } from "./oracle/family-conformance.mjs";
+export { judgeObject, verdictSeverity, VERDICT_RANK } from "./hosted/judge.mjs";
+export { loadSpine, resolveClaim } from "./hosted/spine.mjs";
+export { vaultRdsQuery, parseRdsRecords } from "./hosted/vault-exec.mjs";
+export { runSurfaceSizeCoverageAudit, SURFACE_SIZE_COVERAGE_DEFAULTS } from "../engines/surface/surface-size-coverage-engine.mjs";
+export { selfUpdate, applyCoreManifest, isNewer, sha256Hex } from "../update/self-update.mjs";
+export { initWorkspace } from "./init.mjs";
+export { loadWorkspaceConfig } from "./config.mjs";