@facilis.dev/ai 0.0.0-stage → 0.1.1

package/dist/rules/blocks.js

@@ -0,0 +1,64 @@
+/**
+ * Rule 7 `block-import-valid` (SPEC §9.3): every block the patch imports must match a
+ * registered `BlockManifest`. The block supply chain is retired (D-131, no `@facilis.dev/blocks`
+ * package ships), so in practice the manifest registers none and the guard rejects every block
+ * import; it stays in the rule set as the contract's reserved slot (§7.2/§7.3).
+ *
+ * The imports are the analyzer's FileFacts, so re-exports and dynamic imports are covered
+ * by the same AST truth the rest of validation uses.
+ */
+const DEFAULT_BLOCKS_PACKAGE = "@facilis.dev/blocks";
+/** The import names a block import introduces: named imports and default-import locals. */
+function namesOf(imported) {
+    if (imported.kind === "named" && imported.imported !== null)
+        return [imported.imported];
+    if (imported.kind === "default" && imported.local !== null)
+        return [imported.local];
+    return [];
+}
+/** The block name an import points at, or null when the specifier is not a block import. */
+function blockNameFromPath(specifier, packages) {
+    for (const pkg of packages) {
+        if (specifier === pkg)
+            return null;
+        if (specifier.startsWith(pkg + "/")) {
+            const name = specifier.slice(pkg.length + 1).split("/")[0];
+            return name === undefined || name.length === 0 ? null : name;
+        }
+    }
+    const segments = specifier.split("/");
+    const index = segments.indexOf("blocks");
+    if (index === -1)
+        return null;
+    const name = segments[index + 1];
+    return name === undefined || name.length === 0 ? null : name;
+}
+export function blockImportErrors(state, context) {
+    // Blocks are no longer configurable: the framework ships one reviewed package (D-067).
+    const packages = new Set([DEFAULT_BLOCKS_PACKAGE]);
+    const known = new Set(context.blocks.map((block) => block.name));
+    const errors = [];
+    const seen = new Set();
+    for (const facts of state.patchedFileFacts) {
+        for (const imported of facts.imports) {
+            const fromPackageRoot = packages.has(imported.specifier);
+            const pathName = blockNameFromPath(imported.specifier, packages);
+            const candidates = fromPackageRoot ? namesOf(imported) : pathName === null ? [] : [pathName];
+            for (const candidate of candidates) {
+                const key = facts.path + "\u0000" + candidate;
+                if (known.has(candidate) || seen.has(key))
+                    continue;
+                seen.add(key);
+                errors.push({
+                    rule: "block-import-valid",
+                    severity: "error",
+                    file: facts.path,
+                    message: 'Block import "' + candidate + '" does not match a registered BlockManifest.',
+                    fix_hint: "Import an existing block manifest, or stop importing it; do not create new blocks unprompted (SPEC §9.2 rule 5).",
+                    line: imported.source.line,
+                });
+            }
+        }
+    }
+    return errors;
+}

package/dist/rules/config-sync.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rule 16 `role-config-sync` (SPEC §9.3): changing roles or permissions in
+ * `facilis.config.ts` requires a new migration that updates the `role_permissions`
+ * seed. The table is a projection of the config (SPEC §5.3), so without the migration the
+ * live database silently disagrees with the code.
+ */
+import { type EffectiveState } from "../overlay.js";
+import type { FilePatch, ValidationError } from "../types.js";
+export declare function roleConfigSyncErrors(patches: readonly FilePatch[], state: EffectiveState): ValidationError[];

package/dist/rules/config-sync.js

@@ -0,0 +1,64 @@
+/**
+ * Rule 16 `role-config-sync` (SPEC §9.3): changing roles or permissions in
+ * `facilis.config.ts` requires a new migration that updates the `role_permissions`
+ * seed. The table is a projection of the config (SPEC §5.3), so without the migration the
+ * live database silently disagrees with the code.
+ */
+import { hasMigrationPatch, CONFIG_PATH } from "../overlay.js";
+import { normalizeProjectPath } from "../paths.js";
+function changedFacts(before, after) {
+    const changes = [];
+    for (const permission of after.permissions) {
+        if (!before.permissions.includes(permission))
+            changes.push('adds permission "' + permission + '"');
+    }
+    for (const permission of before.permissions) {
+        if (!after.permissions.includes(permission))
+            changes.push('removes permission "' + permission + '"');
+    }
+    const beforeRoles = JSON.stringify(before.roles);
+    const afterRoles = JSON.stringify(after.roles);
+    if (beforeRoles !== afterRoles)
+        changes.push("changes auth.roles");
+    if ((before.defaultRole ?? "") !== (after.defaultRole ?? "")) {
+        changes.push('changes defaultRole to "' + (after.defaultRole ?? "") + '"');
+    }
+    return changes;
+}
+export function roleConfigSyncErrors(patches, state) {
+    const touchesConfig = patches.some((patch) => {
+        return normalizeProjectPath(patch.path) === CONFIG_PATH && patch.action !== "delete";
+    });
+    if (!touchesConfig)
+        return [];
+    const errors = [];
+    const after = state.config;
+    // A config patch the scan cannot read is unverifiable: rule 16 fails closed instead of
+    // assuming "no auth change". The pre-patch source may be unparseable for the same
+    // reason, so the check is on the patched content itself.
+    if (!after.parsed) {
+        errors.push({
+            rule: "role-config-sync",
+            severity: "error",
+            file: CONFIG_PATH,
+            message: "The auth block of the patched facilis.config.ts could not be read, so the role/permission sync cannot be verified.",
+            fix_hint: "Keep the auth declaration as an object literal inside defineConfig so the validator can read it.",
+        });
+        return errors;
+    }
+    const changes = changedFacts(state.before.config, after);
+    if (changes.length === 0 || hasMigrationPatch(patches, state.migrationsDir))
+        return [];
+    errors.push({
+        rule: "role-config-sync",
+        severity: "error",
+        file: CONFIG_PATH,
+        message: "The patch " +
+            changes.slice(0, 3).join(", ") +
+            " but ships no migration updating role_permissions.",
+        fix_hint: "Add a migration under " +
+            state.migrationsDir +
+            "/ that reseeds role_permissions from the config (SPEC §5.3, rule 16).",
+    });
+    return errors;
+}

package/dist/rules/database.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Rules 10 `rls-on-scoped-table`, 14 `migration-generated` and 15
+ * `destructive-confirmed` (SPEC §9.3), read from the effective code schema.
+ *
+ * Only tables the project declares itself count (`source.file === db/schema.ts`): the
+ * framework tables re-exported from `@facilis.dev/auth` ship their own RLS and must not be
+ * re-flagged here. Scope is the analyzer's ScopeFact or a tenant/owner column property.
+ */
+import type { EffectiveState } from "../overlay.js";
+import type { FilePatch, ValidationError } from "../types.js";
+/**
+ * Rule 10: a schema rewrite is a complete re-emission of the schema, so every scoped table
+ * in the result must ship its RLS policy — .enableRLS() plus a policy (invariant 4). The
+ * check is not limited to new tables: dropping the policy from an existing scoped table is
+ * the same security regression.
+ */
+export declare function rlsErrors(state: EffectiveState): ValidationError[];
+/** Rule 14: a schema edit must ship a generated migration file (warning). */
+export declare function migrationWarnings(patches: readonly FilePatch[], state: EffectiveState): ValidationError[];
+/** The schema removals in a patch set (rule 15's predicate), for callers that need the
+ * fact without the finding (the IDE flags a write destructive, never blocks it). */
+export declare function destructiveChanges(state: EffectiveState): string[];
+/** Rule 15: dropping a table or column is destructive and must be confirmed. */
+export declare function destructiveErrors(state: EffectiveState, requiresConfirmation: boolean): ValidationError[];

package/dist/rules/database.js

@@ -0,0 +1,105 @@
+/**
+ * Rules 10 `rls-on-scoped-table`, 14 `migration-generated` and 15
+ * `destructive-confirmed` (SPEC §9.3), read from the effective code schema.
+ *
+ * Only tables the project declares itself count (`source.file === db/schema.ts`): the
+ * framework tables re-exported from `@facilis.dev/auth` ship their own RLS and must not be
+ * re-flagged here. Scope is the analyzer's ScopeFact or a tenant/owner column property.
+ */
+import { hasMigrationPatch, SCHEMA_PATH } from "../overlay.js";
+import { normalizeProjectPath } from "../paths.js";
+function error(rule, file, message, fix_hint) {
+    return { rule, severity: "error", file, message, fix_hint };
+}
+function warning(rule, file, message, fix_hint) {
+    return { rule, severity: "warning", file, message, fix_hint };
+}
+/** True when this patch set touches the project schema file (create, update or delete). */
+function touchesSchema(state) {
+    return state.patchedPaths.has(SCHEMA_PATH) || state.deletedPaths.has(SCHEMA_PATH);
+}
+function normalized(value) {
+    return value.replaceAll("_", "").replaceAll("-", "").toLowerCase();
+}
+/** A table is scoped when the analyzer saw a scope or a configured tenant/owner column. */
+function isScoped(table, tenantColumns, ownerColumns) {
+    if (table.scope !== null)
+        return true;
+    const names = new Set([...tenantColumns, ...ownerColumns].map(normalized));
+    return table.columns.some((column) => names.has(normalized(column.property)) || names.has(normalized(column.name)));
+}
+/**
+ * Rule 10: a schema rewrite is a complete re-emission of the schema, so every scoped table
+ * in the result must ship its RLS policy — .enableRLS() plus a policy (invariant 4). The
+ * check is not limited to new tables: dropping the policy from an existing scoped table is
+ * the same security regression.
+ */
+export function rlsErrors(state) {
+    if (!touchesSchema(state))
+        return [];
+    const errors = [];
+    for (const table of state.afterSchemaTables) {
+        if (!isScoped(table, state.config.tenantColumns, state.config.ownerColumns))
+            continue;
+        if (table.rlsEnabled && table.policies.length > 0)
+            continue;
+        errors.push(error("rls-on-scoped-table", SCHEMA_PATH, 'Scoped table "' + table.name + '" has no RLS policy in the patched db/schema.ts.', "Add .enableRLS() and a tenantIsolationPolicy()/ownerIsolationPolicy() (or pgPolicy) to the table in db/schema.ts (invariant 4)."));
+    }
+    return errors;
+}
+/** Rule 14: a schema edit must ship a generated migration file (warning). */
+export function migrationWarnings(patches, state) {
+    const touches = patches.some((patch) => {
+        const path = normalizeProjectPath(patch.path);
+        return path === SCHEMA_PATH && patch.action !== "delete";
+    });
+    if (!touches)
+        return [];
+    if (hasMigrationPatch(patches, state.migrationsDir))
+        return [];
+    return [
+        warning("migration-generated", SCHEMA_PATH, "The patch changes the schema without shipping a migration.", "Add the drizzle-kit generated migration (.sql) under " +
+            state.migrationsDir +
+            "/ in the same patch."),
+    ];
+}
+function removedColumns(before, after) {
+    const afterByName = new Map(after.map((table) => [table.name, table]));
+    const removed = [];
+    for (const table of before) {
+        const current = afterByName.get(table.name);
+        if (current === undefined || table.columns.length === 0 || current.columns.length === 0) {
+            continue;
+        }
+        const currentColumns = new Set(current.columns.map((column) => column.property));
+        for (const column of table.columns) {
+            if (!currentColumns.has(column.property))
+                removed.push(table.name + "." + column.property);
+        }
+    }
+    return removed;
+}
+/** The schema removals in a patch set (rule 15's predicate), for callers that need the
+ * fact without the finding (the IDE flags a write destructive, never blocks it). */
+export function destructiveChanges(state) {
+    const afterNames = new Set(state.afterSchemaTables.map((table) => table.name));
+    const droppedTables = state.beforeSchemaTables
+        .map((table) => table.name)
+        .filter((name) => !afterNames.has(name));
+    const droppedColumns = removedColumns(state.beforeSchemaTables, state.afterSchemaTables);
+    return [
+        ...droppedTables.map((name) => 'drops table "' + name + '"'),
+        ...droppedColumns.map((name) => 'drops column "' + name + '"'),
+    ];
+}
+/** Rule 15: dropping a table or column is destructive and must be confirmed. */
+export function destructiveErrors(state, requiresConfirmation) {
+    const changes = destructiveChanges(state);
+    if (changes.length === 0 || requiresConfirmation)
+        return [];
+    const shown = changes.slice(0, 3).join(", ");
+    const suffix = changes.length > 3 ? " (and " + (changes.length - 3) + " more)" : "";
+    return [
+        error("destructive-confirmed", SCHEMA_PATH, "Destructive schema change without confirmation: the patch " + shown + suffix + ".", "If the removal was not intended, re-emit the complete db/schema.ts keeping every existing table and column and add only the requested change. For a deliberate removal, set requires_confirmation to true and explain it in notes (SPEC §9.2 rule 9 / §9.3 rule 15)."),
+    ];
+}

package/dist/rules/i18n.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Rule 13 `i18n-keys-registered` (warning, SPEC §9.3): every static `t("key")` call in
+ * a patched file must have its key in the effective default-locale catalogue. Keys are
+ * literal facts from the analyzer: an interpolated key cannot be checked and guessing would
+ * produce false warnings.
+ */
+import { type EffectiveState } from "../overlay.js";
+import type { ValidationError } from "../types.js";
+export declare function i18nWarnings(state: EffectiveState): ValidationError[];

package/dist/rules/i18n.js

@@ -0,0 +1,40 @@
+/**
+ * Rule 13 `i18n-keys-registered` (warning, SPEC §9.3): every static `t("key")` call in
+ * a patched file must have its key in the effective default-locale catalogue. Keys are
+ * literal facts from the analyzer: an interpolated key cannot be checked and guessing would
+ * produce false warnings.
+ */
+import { LOCALES_PATH } from "../overlay.js";
+import { isScriptPath } from "../paths.js";
+export function i18nWarnings(state) {
+    const warnings = [];
+    if (!state.localesValid) {
+        warnings.push({
+            rule: "i18n-keys-registered",
+            severity: "warning",
+            file: LOCALES_PATH,
+            message: "The patched locales/en.json is not a valid JSON catalogue, so i18n keys cannot be verified.",
+            fix_hint: "Emit locales/en.json as a complete JSON object of key/value strings.",
+        });
+    }
+    const known = new Set(Object.keys(state.locales));
+    for (const facts of state.patchedFileFacts) {
+        if (!isScriptPath(facts.path))
+            continue;
+        const reported = new Set();
+        for (const call of facts.translationCalls) {
+            if (known.has(call.key) || reported.has(call.key))
+                continue;
+            reported.add(call.key);
+            warnings.push({
+                rule: "i18n-keys-registered",
+                severity: "warning",
+                file: facts.path,
+                message: 't("' + call.key + '") is not registered in locales/en.json.',
+                fix_hint: "Add the key to locales/en.json in the same patch, or reuse a registered key.",
+                line: call.source.line,
+            });
+        }
+    }
+    return warnings;
+}

package/dist/rules/imports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Rules 9 `no-raw-db-access` and 12 `import-resolves` (SPEC §9.3).
+ *
+ * Rule 9 keeps raw database clients inside `@facilis.dev/db` (invariant 5); drizzle operators
+ * and `drizzle-orm/pg-core` are the schema DSL and stay allowed. Rule 12 checks that every
+ * module reference resolves against the effective file set, the project's aliases and the
+ * packages package.json declares — no filesystem, no node_modules walk.
+ *
+ * Both read the analyzer's ImportFacts, so static imports, re-exports, dynamic imports and
+ * `require()` share the same AST truth.
+ */
+import type { EffectiveState } from "../overlay.js";
+import type { PatchContext, ValidationError } from "../types.js";
+export declare function rawDbAccessErrors(state: EffectiveState): ValidationError[];
+export declare function importResolveErrors(state: EffectiveState, context: PatchContext): ValidationError[];

package/dist/rules/imports.js

@@ -0,0 +1,194 @@
+/**
+ * Rules 9 `no-raw-db-access` and 12 `import-resolves` (SPEC §9.3).
+ *
+ * Rule 9 keeps raw database clients inside `@facilis.dev/db` (invariant 5); drizzle operators
+ * and `drizzle-orm/pg-core` are the schema DSL and stay allowed. Rule 12 checks that every
+ * module reference resolves against the effective file set, the project's aliases and the
+ * packages package.json declares — no filesystem, no node_modules walk.
+ *
+ * Both read the analyzer's ImportFacts, so static imports, re-exports, dynamic imports and
+ * `require()` share the same AST truth.
+ */
+import { normalizeProjectPath } from "../paths.js";
+const RAW_DRIVER = /^drizzle-orm\/(?:pglite|node-postgres|postgres-js|bun-sqlite|neon|vercel-postgres|aws-data-api|libsql|expo-sqlite|d1|op-sqlite|singlestore|tidb-serverless)$/;
+const RAW_CLIENTS = new Set(["@electric-sql/pglite", "postgres", "pg"]);
+const NODE_BUILTINS = new Set([
+    "assert",
+    "async_hooks",
+    "buffer",
+    "child_process",
+    "cluster",
+    "console",
+    "constants",
+    "crypto",
+    "dgram",
+    "diagnostics_channel",
+    "dns",
+    "domain",
+    "events",
+    "fs",
+    "http",
+    "http2",
+    "https",
+    "inspector",
+    "module",
+    "net",
+    "os",
+    "path",
+    "perf_hooks",
+    "process",
+    "punycode",
+    "querystring",
+    "readline",
+    "repl",
+    "stream",
+    "string_decoder",
+    "sys",
+    "timers",
+    "tls",
+    "trace_events",
+    "tty",
+    "url",
+    "util",
+    "v8",
+    "vm",
+    "wasi",
+    "worker_threads",
+    "zlib",
+]);
+const RESOLVABLE_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".css",
+    ".svg",
+];
+const HAS_EXTENSION = /\.[A-Za-z0-9]+$/;
+function error(rule, file, message, fix_hint, line) {
+    return {
+        rule,
+        severity: "error",
+        file,
+        message,
+        fix_hint,
+        ...(line === undefined ? {} : { line }),
+    };
+}
+/** Imports deduped per statement: a named-import clause produces one fact per name. */
+function statementImports(imports) {
+    const seen = new Set();
+    const unique = [];
+    for (const imported of imports) {
+        const key = imported.specifier + "\u0000" + imported.source.line;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(imported);
+    }
+    return unique;
+}
+export function rawDbAccessErrors(state) {
+    const errors = [];
+    for (const facts of state.patchedFileFacts) {
+        const imports = statementImports(facts.imports);
+        for (const imported of imports) {
+            if (!RAW_DRIVER.test(imported.specifier) && !RAW_CLIENTS.has(imported.specifier))
+                continue;
+            errors.push(error("no-raw-db-access", facts.path, 'Importing "' + imported.specifier + '" is a raw database client outside @facilis.dev/db.', "Go through the policy-scoped db the handler receives (invariant 5).", imported.source.line));
+        }
+        const rawDrizzleImport = imports.find((imported) => imported.specifier === "drizzle-orm");
+        if (rawDrizzleImport !== undefined && facts.calls.some((call) => call.name === "drizzle")) {
+            errors.push(error("no-raw-db-access", facts.path, "Constructing a raw drizzle() client is not allowed outside @facilis.dev/db.", "Use the policy-scoped db from the handler context; import operators from drizzle-orm instead (invariant 5).", rawDrizzleImport.source.line));
+        }
+    }
+    return errors;
+}
+function fileExists(files, base) {
+    const target = normalizeProjectPath(base);
+    if (target.length === 0)
+        return false;
+    if (files.has(target))
+        return true;
+    if (HAS_EXTENSION.test(target))
+        return false;
+    for (const extension of RESOLVABLE_EXTENSIONS) {
+        if (files.has(target + extension))
+            return true;
+        if (files.has(target + "/index" + extension))
+            return true;
+    }
+    return false;
+}
+function relativeBase(fromPath, specifier) {
+    const directory = fromPath.split("/").slice(0, -1);
+    const segments = [...directory, ...specifier.split("/")];
+    const resolved = [];
+    for (const segment of segments) {
+        if (segment.length === 0 || segment === ".")
+            continue;
+        if (segment === "..") {
+            resolved.pop();
+            continue;
+        }
+        resolved.push(segment);
+    }
+    return resolved.join("/");
+}
+function aliasBase(specifier, aliases) {
+    for (const alias of aliases) {
+        if (!specifier.startsWith(alias.prefix))
+            continue;
+        return normalizeProjectPath(alias.target + specifier.slice(alias.prefix.length));
+    }
+    return null;
+}
+function stripQuery(specifier) {
+    const cut = specifier.search(/[?#]/);
+    return cut === -1 ? specifier : specifier.slice(0, cut);
+}
+function packageNameOf(specifier) {
+    const parts = specifier.split("/");
+    if (specifier.startsWith("@"))
+        return parts.slice(0, 2).join("/");
+    return parts[0] ?? specifier;
+}
+export function importResolveErrors(state, context) {
+    const errors = [];
+    for (const facts of state.patchedFileFacts) {
+        for (const imported of statementImports(facts.imports)) {
+            const specifier = stripQuery(imported.specifier);
+            if (specifier.length === 0)
+                continue;
+            if (specifier.startsWith("node:") || NODE_BUILTINS.has(specifier))
+                continue;
+            if (/^[a-z][a-z0-9+.-]*:/i.test(specifier))
+                continue;
+            const relative = specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/");
+            if (relative) {
+                const base = specifier.startsWith("/")
+                    ? specifier.replace(/^\/+/, "")
+                    : relativeBase(facts.path, specifier);
+                if (fileExists(state.files, base))
+                    continue;
+            }
+            else {
+                const alias = aliasBase(specifier, context.aliases);
+                if (alias !== null) {
+                    if (fileExists(state.files, alias))
+                        continue;
+                }
+                else if (context.packages.includes(packageNameOf(specifier))) {
+                    continue;
+                }
+            }
+            errors.push(error("import-resolves", facts.path, 'Import "' + imported.specifier + '" does not resolve.', relative
+                ? "Point the import at a file that exists (or is created by this patch)."
+                : "Use a package declared in package.json; new dependencies need user approval.", imported.source.line));
+        }
+    }
+    return errors;
+}

package/dist/rules/job-relations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Rule 19 `job-table-declared` (SPEC §9.3, D-157 applied to jobs): a job's `dbTables` is an
+ * applied declaration.
+ *
+ * A job's `run(ctx)` always receives the system-scoped client (D-107), so its usage has no
+ * elevation dimension: every relation it reaches — tables and views — must be declared,
+ * following project-local helper calls, and a missing or unreadable declaration fails closed.
+ * The rule covers **all** effective jobs whose usage facts exist, not only the patched ones: a
+ * patch that edits a shared helper changes what untouched jobs touch, and must not bypass the
+ * declaration.
+ *
+ * Errors: undeclared, unresolved/dynamic relation, `db.execute` without `rawSql: true` and a
+ * declaration that cannot be read. Warning: declared but unused (suppressed when usage is
+ * opaque or raw SQL is present, where the declaration stays authoritative).
+ */
+import type { EffectiveState } from "../overlay.js";
+import type { ValidationError } from "../types.js";
+export interface JobTableDeclaredFindings {
+    readonly errors: ValidationError[];
+    readonly warnings: ValidationError[];
+}
+/** Rule 19 over the effective analysis (SPEC §9.3, D-157 applied to jobs). */
+export declare function jobTableDeclaredFindings(state: EffectiveState): JobTableDeclaredFindings;

package/dist/rules/job-relations.js

@@ -0,0 +1,84 @@
+/**
+ * Rule 19 `job-table-declared` (SPEC §9.3, D-157 applied to jobs): a job's `dbTables` is an
+ * applied declaration.
+ *
+ * A job's `run(ctx)` always receives the system-scoped client (D-107), so its usage has no
+ * elevation dimension: every relation it reaches — tables and views — must be declared,
+ * following project-local helper calls, and a missing or unreadable declaration fails closed.
+ * The rule covers **all** effective jobs whose usage facts exist, not only the patched ones: a
+ * patch that edits a shared helper changes what untouched jobs touch, and must not bypass the
+ * declaration.
+ *
+ * Errors: undeclared, unresolved/dynamic relation, `db.execute` without `rawSql: true` and a
+ * declaration that cannot be read. Warning: declared but unused (suppressed when usage is
+ * opaque or raw SQL is present, where the declaration stays authoritative).
+ */
+function lineOf(source) {
+    return source?.line;
+}
+function error(file, message, fixHint, line) {
+    return {
+        rule: "job-table-declared",
+        severity: "error",
+        file,
+        message,
+        fix_hint: fixHint,
+        ...(line === undefined ? {} : { line }),
+    };
+}
+function unusedWarning(job, name) {
+    return {
+        rule: "job-table-declared",
+        severity: "warning",
+        file: job.sourceFile,
+        message: 'dbTables declares "' + name + '" but the job never uses it.',
+        fix_hint: 'Remove "' + name + '" from dbTables, or use it: the declaration is enforced (D-157).',
+    };
+}
+/** Opaque usage or raw SQL keeps the declaration authoritative instead of warning. */
+function unusedSuppressed(usage) {
+    return usage.opaque || usage.rawSql.length > 0;
+}
+/** Rule 19 over the effective analysis (SPEC §9.3, D-157 applied to jobs). */
+export function jobTableDeclaredFindings(state) {
+    const errors = [];
+    const warnings = [];
+    for (const job of state.analysis.jobs) {
+        // A hand-built analysis may predate the fact: no usage facts, no check.
+        const usage = state.analysis.jobRelations[job.name];
+        if (usage === undefined)
+            continue;
+        const declared = job.dbTables === null ? null : new Set(job.dbTables);
+        if (declared === null) {
+            errors.push(error(job.sourceFile, 'Job "' + job.name + '" dbTables is missing or cannot be read statically.', "Declare dbTables on defineJob({...}): every table or view the run body touches ([] means none).", lineOf(job.source)));
+        }
+        else {
+            for (const use of usage.used) {
+                if (declared.has(use.name))
+                    continue;
+                errors.push(error(use.source.file, 'Relation "' + use.name + '" is used through the job db but not declared in dbTables.', 'Add "' +
+                    use.name +
+                    '" to dbTables (tables and views the run body touches), or stop using it.', lineOf(use.source)));
+            }
+        }
+        for (const source of usage.unresolved) {
+            errors.push(error(source.file, "A relation used through the job db cannot be resolved statically.", "Use a table or view binding imported from db/ instead of a dynamic expression.", lineOf(source)));
+        }
+        for (const source of usage.rawSql) {
+            if (job.rawSql === true)
+                continue;
+            errors.push(error(source.file, "db.execute() requires rawSql: true on the job definition.", job.rawSql === null
+                ? "Declare rawSql: true (or false) statically, or use the query builder."
+                : "Add rawSql: true to defineJob({...}), or use the query builder.", lineOf(source)));
+        }
+        if (declared !== null && !unusedSuppressed(usage)) {
+            const used = new Set(usage.used.map((use) => use.name));
+            for (const name of job.dbTables ?? []) {
+                if (used.has(name))
+                    continue;
+                warnings.push(unusedWarning(job, name));
+            }
+        }
+    }
+    return { errors, warnings };
+}

package/dist/rules/route-relations.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Rule 18 `route-table-declared` (SPEC §9.3, D-157): `dbTables` is an applied declaration.
+ *
+ * Every relation a handler reaches through `ctx.db`, `ctx.sudo` or `ctx.system` — tables
+ * and views — must be declared, following project-local helper calls. The rule covers **all**
+ * effective routes whose usage facts exist, not only the patched ones: a patch that edits a
+ * shared helper changes what untouched routes touch, and must not bypass the declaration.
+ *
+ * Errors: undeclared, unresolved/dynamic relation, `db.execute` without `rawSql: true`,
+ * elevation use outside its `tables` option. Warning: declared but unused (suppressed when
+ * usage is opaque or raw SQL is present, where the declaration stays authoritative).
+ */
+import type { EffectiveState } from "../overlay.js";
+import type { ValidationError } from "../types.js";
+export interface RouteTableDeclaredFindings {
+    readonly errors: ValidationError[];
+    readonly warnings: ValidationError[];
+}
+/** Rule 18 over the effective analysis (SPEC §9.3, D-157). */
+export declare function routeTableDeclaredFindings(state: EffectiveState): RouteTableDeclaredFindings;