@supacloud/db 0.10.0 → 0.12.0

package/NOTICE

@@ -1,22 +1,17 @@
 SupaCloud
 Copyright 2025 SupaCloud Contributors
 
-SupaCloud project-owned code in this revision is licensed under the GNU
-Affero General Public License, version 3 only (AGPL-3.0-only). The complete
-license is provided in LICENSE. This is not an "or later" grant.
+SupaCloud project-owned code in this revision is licensed under the Apache
+License, Version 2.0 (Apache-2.0). The complete license is provided in
+LICENSE.
 
 This program is distributed without any warranty; without even the implied
 warranty of merchantability or fitness for a particular purpose.
 
 Third-party components, incorporated upstream code, and their copyright,
-license and attribution notices retain their original terms. This notice
-does not replace those terms or claim ownership of third-party work.
+license and attribution notices retain their original terms. This notice does
+not replace those terms or claim ownership of third-party work.
 
-Earlier SupaCloud code was distributed under Apache-2.0 or MIT as indicated
-in its original files and package metadata. Previously granted permissions
-are not revoked by this change. The historical Apache-2.0 text is preserved
-in LICENSE-APACHE-2.0.txt. Retain any applicable upstream MIT notices as well.
-
-Before publishing this licensing change, maintainers must confirm authority
-to license the affected contributions and compatibility of incorporated
-third-party code. This notice is not evidence of contributor consent.
+Previously released SupaCloud versions retain the permissions granted with
+those versions. See the historical license files and release notices where
+applicable.

package/README.md

@@ -250,3 +250,12 @@ bun run typecheck
 bun run typecheck:test
 bun run build       # bun build --target node + tsc 声明文件
 ```
+
+## Database Source Defaults
+
+`supacloud-db assess|generate|check --root <project>` provides offline source-boundary
+assessment, RPC contracts and freshness checks. Use `database.sources.json` to
+separate Drizzle declarations, maintained function SQL, append-only migrations,
+derived contracts and audit output. `check` and `assess` never write or connect;
+`generate` only writes derived contracts and refuses changes to recorded migration
+history. See the repository's `docs/database-source-contracts.md` for adoption.

package/dist/rpc-source-contracts.d.ts

@@ -0,0 +1,17 @@
+export interface RpcParameter {
+    name: string;
+    sqlType: string;
+    optional: boolean;
+}
+export interface RpcSourceContract {
+    name: string;
+    identity: string;
+    parameters: RpcParameter[];
+    returnType: string;
+    callable: boolean;
+}
+/** Tracks explicit top-level DDL only; dynamic SQL and deployed parity need catalog verification. */
+export declare function migrationFunctionIdentities(sources: readonly string[]): Promise<Set<string>>;
+/** Source declarations, never an assertion about role inheritance or a deployed database. */
+export declare function rpcSourceContract(sql: string, role: string): Promise<RpcSourceContract>;
+export declare function renderRpcSourceTypes(contracts: readonly RpcSourceContract[]): string;

package/dist/source-contracts-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function databaseSourcesMain(args: string[]): Promise<number>;

package/dist/source-contracts-cli.js

@@ -0,0 +1,577 @@
+#!/usr/bin/env node
+
+// src/source-contracts-cli.ts
+import { existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// src/source-contracts.ts
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import * as ts from "@typescript/typescript6";
+
+// src/rpc-source-contracts.ts
+import { parse } from "libpg-query";
+function names(nodes = []) {
+  return nodes.map((node) => {
+    if (!("String" in node) || typeof node.String.sval !== "string")
+      throw new Error("Invalid SQL identifier");
+    return node.String.sval;
+  });
+}
+function typeName(type) {
+  if (!type?.names?.length)
+    throw new Error("Missing SQL type");
+  const parts = names(type.names);
+  if (parts[0] === "pg_catalog")
+    parts.shift();
+  const aliases = {
+    int2: "smallint",
+    int4: "integer",
+    int8: "bigint",
+    bool: "boolean",
+    float4: "real",
+    float8: "double precision",
+    varchar: "character varying",
+    timestamptz: "timestamp with time zone",
+    timestamp: "timestamp without time zone",
+    timetz: "time with time zone",
+    time: "time without time zone"
+  };
+  const value = parts.join(".");
+  return `${type.setof ? "SETOF " : ""}${aliases[value] ?? value}${type.arrayBounds?.length ? "[]" : ""}`;
+}
+function qualified(nodes) {
+  const parts = names(nodes);
+  if (parts.length !== 2 || parts.some((part) => !/^[a-z_][a-z0-9_$]*$/.test(part))) {
+    throw new Error("Use an explicit lowercase schema-qualified function name");
+  }
+  return parts.join(".");
+}
+async function migrationFunctionIdentities(sources) {
+  const identities = new Set;
+  const targetIdentity = (node) => {
+    if (!("ObjectWithArgs" in node) || node.ObjectWithArgs.args_unspecified)
+      throw new Error("Migration function changes require an explicit signature");
+    const target = node.ObjectWithArgs;
+    const types = (target.objargs ?? []).map((argument) => {
+      if (!("TypeName" in argument))
+        throw new Error("Invalid migration function type");
+      return typeName(argument.TypeName);
+    });
+    return `${qualified(target.objname)}(${types.join(", ")})`;
+  };
+  for (const source of sources) {
+    for (const { stmt } of (await parse(source)).stmts ?? []) {
+      if (!stmt)
+        continue;
+      if ("CreateFunctionStmt" in stmt && !stmt.CreateFunctionStmt.is_procedure) {
+        const fn = stmt.CreateFunctionStmt;
+        const types = (fn.parameters ?? []).flatMap((node) => {
+          if (!("FunctionParameter" in node))
+            throw new Error("Invalid migration parameter");
+          return ["FUNC_PARAM_OUT", "FUNC_PARAM_TABLE"].includes(node.FunctionParameter.mode ?? "") ? [] : [typeName(node.FunctionParameter.argType)];
+        });
+        identities.add(`${qualified(fn.funcname)}(${types.join(", ")})`);
+      } else if ("DropStmt" in stmt && stmt.DropStmt.removeType === "OBJECT_FUNCTION") {
+        for (const target of stmt.DropStmt.objects ?? [])
+          identities.delete(targetIdentity(target));
+      } else if ("RenameStmt" in stmt && stmt.RenameStmt.renameType === "OBJECT_FUNCTION") {
+        const rename = stmt.RenameStmt;
+        if (!rename.object || !rename.newname || !/^[a-z_][a-z0-9_$]*$/.test(rename.newname))
+          throw new Error("Invalid function rename");
+        const old = targetIdentity(rename.object);
+        identities.delete(old);
+        const schema = old.slice(0, old.indexOf("."));
+        identities.add(`${schema}.${rename.newname}${old.slice(old.indexOf("("))}`);
+      }
+    }
+  }
+  return identities;
+}
+async function rpcSourceContract(sql, role) {
+  const statements = (await parse(sql)).stmts ?? [];
+  const functions = statements.flatMap(({ stmt }) => stmt && ("CreateFunctionStmt" in stmt) ? [stmt.CreateFunctionStmt] : []);
+  const fn = functions[0];
+  if (functions.length !== 1 || !fn || fn.is_procedure)
+    throw new Error("Each source must declare exactly one function");
+  const name = qualified(fn.funcname);
+  const parameters = [];
+  let tableResult = false, unnamed = false;
+  for (const node of fn.parameters ?? []) {
+    if (!("FunctionParameter" in node))
+      throw new Error("Invalid function parameter");
+    const parameter = node.FunctionParameter;
+    if (["FUNC_PARAM_OUT", "FUNC_PARAM_TABLE"].includes(parameter.mode ?? "")) {
+      tableResult = true;
+      continue;
+    }
+    if (parameter.mode === "FUNC_PARAM_VARIADIC")
+      throw new Error("Variadic RPC contracts require a reviewed adapter");
+    if (parameter.mode === "FUNC_PARAM_INOUT")
+      tableResult = true;
+    unnamed ||= !parameter.name;
+    parameters.push({ name: parameter.name ?? "", sqlType: typeName(parameter.argType), optional: parameter.defexpr !== undefined });
+  }
+  const identity = `${name}(${parameters.map((parameter) => parameter.sqlType).join(", ")})`;
+  let publicGrant;
+  let directGrant = false;
+  for (const { stmt } of statements) {
+    if (!stmt)
+      throw new Error("Missing SQL statement");
+    if ("CreateFunctionStmt" in stmt)
+      continue;
+    if (!("GrantStmt" in stmt))
+      throw new Error("Function sources may contain only a function and its EXECUTE ACL");
+    const grant = stmt.GrantStmt;
+    if (grant.objtype !== "OBJECT_FUNCTION" || grant.targtype !== "ACL_TARGET_OBJECT")
+      throw new Error("Foreign ACL target");
+    if (grant.privileges?.some((privilege) => !("AccessPriv" in privilege) || privilege.AccessPriv.priv_name !== "execute")) {
+      throw new Error("Only EXECUTE function privileges are supported");
+    }
+    for (const target of grant.objects ?? []) {
+      if (!("ObjectWithArgs" in target) || target.ObjectWithArgs.args_unspecified)
+        throw new Error("Explicit ACL signature required");
+      const object = target.ObjectWithArgs;
+      const types = (object.objargs ?? []).map((argument) => {
+        if (!("TypeName" in argument))
+          throw new Error("Invalid ACL argument");
+        return typeName(argument.TypeName);
+      });
+      if (`${qualified(object.objname)}(${types.join(", ")})` !== identity)
+        throw new Error("ACL does not belong to this function");
+    }
+    if (!grant.is_grant && grant.grant_option)
+      continue;
+    for (const node of grant.grantees ?? []) {
+      if (!("RoleSpec" in node))
+        throw new Error("Invalid ACL role");
+      if (node.RoleSpec.roletype === "ROLESPEC_PUBLIC")
+        publicGrant = grant.is_grant === true;
+      if (node.RoleSpec.rolename === role)
+        directGrant = grant.is_grant === true;
+    }
+  }
+  const returns = tableResult ? "record" : typeName(fn.returnType);
+  const internal = unnamed || ["trigger", "event_trigger"].includes(returns);
+  if (!internal && publicGrant === undefined)
+    throw new Error(`Explicit PUBLIC EXECUTE grant/revocation required: ${identity}`);
+  return { name, identity, parameters, returnType: returns, callable: !internal && (publicGrant === true || directGrant) };
+}
+function tsType(sqlType) {
+  if (sqlType.startsWith("SETOF "))
+    return `Array<${tsType(sqlType.slice(6))} | null>`;
+  if (sqlType.endsWith("[]"))
+    return `Array<${tsType(sqlType.slice(0, -2))} | null>`;
+  if (["bigint", "numeric", "decimal"].includes(sqlType))
+    return "number | string";
+  if (["smallint", "integer", "real", "double precision"].includes(sqlType))
+    return "number";
+  if (sqlType === "boolean")
+    return "boolean";
+  if (sqlType === "void")
+    return "void";
+  if ([
+    "text",
+    "uuid",
+    "character varying",
+    "character",
+    "date",
+    "interval",
+    "timestamp with time zone",
+    "timestamp without time zone",
+    "time with time zone",
+    "time without time zone"
+  ].includes(sqlType))
+    return "string";
+  return "unknown";
+}
+function renderRpcSourceTypes(contracts) {
+  const groups = new Map;
+  for (const contract of contracts.filter((item) => item.callable)) {
+    groups.set(contract.name, [...groups.get(contract.name) ?? [], contract]);
+  }
+  const lines = [
+    "// Generated by supacloud-db. Source contracts only; decode untrusted responses.",
+    "export interface RpcDefinitions {"
+  ];
+  for (const [name, overloads] of [...groups].sort(([a], [b]) => a.localeCompare(b))) {
+    const shapes = overloads.map((overload) => {
+      const args = overload.parameters.length ? `{ ${overload.parameters.map((parameter) => `${JSON.stringify(parameter.name)}${parameter.optional ? "?" : ""}: ${tsType(parameter.sqlType)} | null`).join("; ")} }` : "Record<string, never>";
+      return `{ args: ${args}; result: ${tsType(overload.returnType)} | null }`;
+    });
+    lines.push(`  ${JSON.stringify(name)}: ${shapes.join(" | ")};`);
+  }
+  lines.push("}", "export type RpcName = keyof RpcDefinitions;", 'export type RpcArgs<Name extends RpcName> = RpcDefinitions[Name]["args"];', 'export type RpcResult<Name extends RpcName> = RpcDefinitions[Name]["result"];', "");
+  return lines.join(`
+`);
+}
+
+// src/source-contracts.ts
+var CONFIG = "database.sources.json";
+var GENERATOR = "supacloud-db/source-contracts/v1";
+var skip = new Set(["node_modules", ".git", ".worktrees", ".wt", "dist", "coverage", ".next", ".svelte-kit"]);
+var steps = [
+  "Keep the existing append-only migration directory and deployment ledger.",
+  "Review Drizzle declarations and per-function SQL against a local migration replay.",
+  "Add database.sources.json; replace ordinary audit dump consumers.",
+  "Run supacloud-db generate, review contracts, then add supacloud-db check to default checks.",
+  "Verify PostgreSQL definitions, ACL, RLS and behavior separately before deployment."
+];
+var hash = (value) => createHash("sha256").update(value).digest("hex");
+var slash = (value) => value.replaceAll("\\", "/");
+var within = (file, directory) => file === directory || file.startsWith(`${directory}/`);
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function pathValue(value) {
+  if (typeof value !== "string" || !value || isAbsolute(value) || value.includes("\\") || value.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error("Expected a normalized project-relative path");
+  }
+  return value;
+}
+function paths(value) {
+  if (!Array.isArray(value))
+    throw new Error("Expected a path list");
+  const result = value.map(pathValue);
+  if (new Set(result).size !== result.length)
+    throw new Error("Duplicate path");
+  return result;
+}
+function parseDatabaseSourcesConfig(value) {
+  if (!record(value) || value.version !== 1 || Object.keys(value).some((key) => !["version", "schema", "functions", "migrations", "contracts", "audit", "consumers", "auditConsumers", "role"].includes(key))) {
+    throw new Error("Invalid database.sources.json");
+  }
+  const schema = paths(value.schema), consumers = paths(value.consumers), auditConsumers = paths(value.auditConsumers);
+  if (!schema.length || !consumers.length || schema.some((file) => !file.endsWith(".ts")))
+    throw new Error("Select TypeScript schemas and consumer roots");
+  if (typeof value.role !== "string" || !/^[a-z_][a-z0-9_]*$/.test(value.role))
+    throw new Error("Select an explicit database role");
+  const config = {
+    version: 1,
+    schema,
+    consumers,
+    auditConsumers,
+    role: value.role,
+    functions: pathValue(value.functions),
+    migrations: pathValue(value.migrations),
+    contracts: pathValue(value.contracts),
+    audit: pathValue(value.audit)
+  };
+  const areas = [...schema, config.functions, config.migrations, config.contracts, config.audit];
+  for (const [index, area] of areas.entries()) {
+    if (areas.some((other, otherIndex) => index !== otherIndex && (within(area, other) || within(other, area)))) {
+      throw new Error("Schema, function, migration, contract and audit paths must be separate");
+    }
+  }
+  for (const consumer of consumers) {
+    if ([config.contracts, config.audit, config.migrations, config.functions].some((area) => within(consumer, area) || within(area, consumer))) {
+      throw new Error("Consumer roots must be separate from database artifacts");
+    }
+  }
+  if (auditConsumers.some((file) => !consumers.some((directory) => within(file, directory)) || !file.startsWith("scripts/") || !/\.[cm]?[jt]s$/.test(file))) {
+    throw new Error("Audit-only exceptions must name explicit files under scripts/");
+  }
+  return config;
+}
+async function exists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (record(error) && error.code === "ENOENT")
+      return false;
+    throw error;
+  }
+}
+async function safePath(root, file) {
+  pathValue(file);
+  let current = root;
+  for (const part of file.split("/")) {
+    current = join(current, part);
+    if (await exists(current) && (await lstat(current)).isSymbolicLink())
+      throw new Error(`Symlink path is not allowed: ${file}`);
+  }
+  return current;
+}
+async function filesUnder(root, directory, excluded = []) {
+  if (excluded.some((area) => within(directory, area)))
+    return [];
+  const base = directory ? await safePath(root, directory) : root;
+  if (!await exists(base))
+    return [];
+  const stat = await lstat(base);
+  if (stat.isFile())
+    return [directory];
+  const found = [];
+  for (const entry of (await readdir(base, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (skip.has(entry.name) || entry.name.startsWith(".env"))
+      continue;
+    const file = directory ? `${directory}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink())
+      throw new Error(`Symlink source is not allowed: ${file}`);
+    if (entry.isDirectory())
+      found.push(...await filesUnder(root, file, excluded));
+    else if (entry.isFile())
+      found.push(file);
+  }
+  return found;
+}
+function staticPaths(source) {
+  const bindings = new Map;
+  const collect = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      bindings.set(node.name.text, node.initializer);
+    }
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  const evaluate = (node, depth = 0) => {
+    if (depth > 12)
+      return;
+    if (ts.isStringLiteralLike(node))
+      return node.text;
+    if (ts.isIdentifier(node)) {
+      const binding = bindings.get(node.text);
+      return binding ? evaluate(binding, depth + 1) : undefined;
+    }
+    if (ts.isParenthesizedExpression(node))
+      return evaluate(node.expression, depth + 1);
+    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+      const left = evaluate(node.left, depth + 1), right = evaluate(node.right, depth + 1);
+      return left === undefined || right === undefined ? undefined : left + right;
+    }
+    if (ts.isTemplateExpression(node)) {
+      let value = node.head.text;
+      for (const span of node.templateSpans) {
+        const part = evaluate(span.expression, depth + 1);
+        if (part === undefined)
+          return;
+        value += part + span.literal.text;
+      }
+      return value;
+    }
+    if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+      const name = ts.isIdentifier(node.expression) ? node.expression.text : ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : "";
+      if (name === "URL")
+        return node.arguments?.[0] ? evaluate(node.arguments[0], depth + 1) : undefined;
+      if (name === "join" || name === "resolve") {
+        const parts = (node.arguments ?? []).map((argument) => evaluate(argument, depth + 1));
+        if (parts.every((part) => part !== undefined))
+          return parts.join("/");
+      }
+    }
+    return;
+  };
+  const references = [];
+  const visit = (node) => {
+    const value = evaluate(node);
+    if (value !== undefined)
+      references.push({ value, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1 });
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return references;
+}
+async function boundaryFindings(root, config, schemaInputs = []) {
+  const all = await filesUnder(root, "", config ? [config.audit, config.contracts, config.migrations] : ["output"]);
+  const dumps = new Set;
+  for (const file of all.filter((file) => file.endsWith(".sql"))) {
+    if (config && within(file, config.migrations))
+      continue;
+    const handle = await open(await safePath(root, file), "r");
+    let source;
+    try {
+      const buffer = Buffer.alloc(2048);
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+      source = buffer.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      await handle.close();
+    }
+    if (source.includes("-- PostgreSQL database dump") || /(?:^|\/)bootstrap\/schema\.sql$/.test(file))
+      dumps.add(file);
+  }
+  const consumers = all.filter((file) => /\.[cm]?[jt]sx?$/.test(file) && (config ? schemaInputs.includes(file) || config.consumers.some((directory) => within(file, directory)) : !within(file, "output") && !within(file, "generated")));
+  const findings = [];
+  for (const file of consumers) {
+    if (config?.auditConsumers.includes(file))
+      continue;
+    const source = ts.createSourceFile(file, await readFile(await safePath(root, file), "utf8"), ts.ScriptTarget.Latest, true);
+    const reported = new Set;
+    for (const reference of staticPaths(source)) {
+      const candidates = [
+        slash(relative(root, resolve(root, reference.value))),
+        slash(relative(root, resolve(root, dirname(file), reference.value)))
+      ];
+      if (candidates.some((candidate) => dumps.has(candidate) || config && (within(candidate, config.audit) || config.auditConsumers.some((script) => candidate === script || candidate === script.replace(/\.[cm]?[jt]s$/, "")))) || /(?:^|\/)bootstrap\/schema\.sql$/.test(reference.value)) {
+        if (reported.has(reference.line))
+          continue;
+        reported.add(reference.line);
+        findings.push({ file, line: reference.line, code: "audit-input", message: "Ordinary source references an audit dump or audit-only script; use maintained sources or migration replay." });
+      }
+    }
+  }
+  return findings;
+}
+function migrationInputs(value) {
+  if (!record(value) || value.generator !== GENERATOR || !Array.isArray(value.migrations))
+    throw new Error("Invalid previous contract manifest");
+  return value.migrations.map((item) => {
+    if (!record(item) || typeof item.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(item.sha256))
+      throw new Error("Invalid migration baseline");
+    return { path: pathValue(item.path), sha256: item.sha256 };
+  });
+}
+async function databaseSources(projectRoot, action = "check") {
+  const root = resolve(projectRoot);
+  const report = { version: 1, scope: "local-source-contracts", ok: false, findings: [], written: [], steps };
+  try {
+    if ((await lstat(root)).isSymbolicLink())
+      throw new Error("Project root must not be a symlink");
+    const configPath = await safePath(root, CONFIG);
+    const config = await exists(configPath) ? parseDatabaseSourcesConfig(JSON.parse(await readFile(configPath, "utf8"))) : undefined;
+    if (!config) {
+      report.findings.push(...await boundaryFindings(root));
+      report.findings.push({ file: CONFIG, code: "adoption-required", message: "No database source configuration; review the adoption steps before generating contracts." });
+      return report;
+    }
+    for (const directory of [config.functions, config.migrations, ...config.consumers]) {
+      if (!await exists(await safePath(root, directory)))
+        throw new Error(`Missing source directory: ${directory}`);
+    }
+    const inputs = new Map;
+    const input = async (file) => {
+      const text = await readFile(await safePath(root, file), "utf8");
+      inputs.set(file, hash(text));
+      return text;
+    };
+    await input(CONFIG);
+    for (const file of config.schema) {
+      await input(file);
+      const visitImports = async (path) => {
+        const tree = ts.createSourceFile(path, await input(path), ts.ScriptTarget.Latest, true);
+        const imports = [];
+        const visit = (node) => {
+          if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier) && node.moduleSpecifier.text.startsWith("."))
+            imports.push(node.moduleSpecifier.text);
+          ts.forEachChild(node, visit);
+        };
+        visit(tree);
+        for (const specifier of imports) {
+          const base = slash(relative(root, resolve(root, dirname(path), specifier)));
+          const candidates = [base, `${base}.ts`, `${base}/index.ts`];
+          let target;
+          for (const candidate of candidates) {
+            const full = await safePath(root, candidate);
+            if (await exists(full) && (await lstat(full)).isFile()) {
+              target = candidate;
+              break;
+            }
+          }
+          if (!target)
+            throw new Error(`Unresolved local schema import: ${path} -> ${specifier}`);
+          if ([config.audit, config.contracts, config.migrations, config.functions].some((area) => within(target, area))) {
+            throw new Error(`Schema imports a non-structure artifact: ${target}`);
+          }
+          if (!inputs.has(target))
+            await visitImports(target);
+        }
+      };
+      await visitImports(file);
+    }
+    report.findings.push(...await boundaryFindings(root, config, [...inputs.keys()]));
+    const migrations = [];
+    const migrationSql = [];
+    for (const file of (await filesUnder(root, config.migrations)).filter((file) => file.endsWith(".sql")).sort()) {
+      const text = await input(file);
+      migrations.push({ path: file, sha256: hash(text) });
+      migrationSql.push(text);
+    }
+    const contracts = [];
+    for (const file of (await filesUnder(root, config.functions)).filter((file) => file.endsWith(".sql")).sort()) {
+      try {
+        contracts.push(await rpcSourceContract(await input(file), config.role));
+      } catch (error) {
+        report.findings.push({ file, code: "function-contract", message: error instanceof Error ? error.message : "Invalid function source" });
+      }
+    }
+    if (new Set(contracts.map((item) => item.identity)).size !== contracts.length)
+      throw new Error("Duplicate function signature ownership");
+    const owned = new Set(contracts.map((item) => item.identity));
+    for (const identity of await migrationFunctionIdentities(migrationSql)) {
+      if (!owned.has(identity))
+        report.findings.push({
+          file: config.functions,
+          code: "unowned-function",
+          message: `Explicit migration function lacks a maintained source: ${identity}`
+        });
+    }
+    contracts.sort((a, b) => a.identity.localeCompare(b.identity));
+    const catalog = JSON.stringify({ version: 1, scope: report.scope, role: config.role, functions: contracts }, null, 2) + `
+`;
+    const types = renderRpcSourceTypes(contracts);
+    const generated = new Map([["rpc-catalog.json", catalog], ["rpc-types.ts", types]]);
+    const manifest = JSON.stringify({
+      generator: GENERATOR,
+      inputs: Object.fromEntries([...inputs].sort(([a], [b]) => a.localeCompare(b))),
+      migrations,
+      outputs: Object.fromEntries([...generated].map(([name, content]) => [name, hash(content)]))
+    }, null, 2) + `
+`;
+    const manifestPath = await safePath(root, `${config.contracts}/manifest.json`);
+    if (await exists(manifestPath)) {
+      const previous = migrationInputs(JSON.parse(await readFile(manifestPath, "utf8")));
+      if (previous.some((old, index) => old.path !== migrations[index]?.path || old.sha256 !== migrations[index]?.sha256)) {
+        report.findings.push({ file: config.migrations, code: "migration-rewritten", message: "Previously recorded migrations were removed, reordered or rewritten. Restore history; do not regenerate the baseline." });
+      }
+    }
+    generated.set("manifest.json", manifest);
+    for (const name of generated.keys())
+      await safePath(root, `${config.contracts}/${name}`);
+    if (action === "generate" && !report.findings.length) {
+      await mkdir(await safePath(root, config.contracts), { recursive: true });
+      for (const [name, content] of generated) {
+        const file = `${config.contracts}/${name}`, target = await safePath(root, file);
+        if (!await exists(target) || await readFile(target, "utf8") !== content) {
+          await writeFile(target, content);
+          report.written.push(file);
+        }
+      }
+    } else {
+      for (const [name, content] of generated) {
+        const file = `${config.contracts}/${name}`, target = await safePath(root, file);
+        if (!await exists(target) || await readFile(target, "utf8") !== content) {
+          report.findings.push({ file, code: "stale-contract", message: "Missing or stale generated contract; explicitly generate, review and commit." });
+        }
+      }
+    }
+    report.ok = report.findings.length === 0;
+  } catch (error) {
+    report.findings.push({ file: CONFIG, code: "invalid-source-project", message: error instanceof Error ? error.message : "Invalid source project" });
+  }
+  return report;
+}
+
+// src/source-contracts-cli.ts
+async function databaseSourcesMain(args) {
+  const [action, flag, root] = args;
+  if (!["assess", "check", "generate"].includes(action ?? "") || args.length !== 1 && (args.length !== 3 || flag !== "--root" || !root || root.startsWith("-"))) {
+    throw new Error("Usage: supacloud-db <assess|check|generate> [--root project]");
+  }
+  if (action !== "assess" && action !== "check" && action !== "generate")
+    throw new Error("Invalid action");
+  const report = await databaseSources(root ?? ".", action);
+  console.log(JSON.stringify(report, null, 2));
+  return action === "assess" || report.ok ? 0 : 1;
+}
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    process.exitCode = await databaseSourcesMain(process.argv.slice(2));
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Database source check failed");
+    process.exitCode = 1;
+  }
+}
+export {
+  databaseSourcesMain
+};

package/dist/source-contracts.d.ts

@@ -0,0 +1,27 @@
+export interface DatabaseSourcesConfig {
+    version: 1;
+    schema: string[];
+    functions: string;
+    migrations: string;
+    contracts: string;
+    audit: string;
+    consumers: string[];
+    auditConsumers: string[];
+    role: string;
+}
+export interface SourceFinding {
+    file: string;
+    code: string;
+    message: string;
+    line?: number;
+}
+export interface DatabaseSourcesReport {
+    version: 1;
+    scope: "local-source-contracts";
+    ok: boolean;
+    findings: SourceFinding[];
+    written: string[];
+    steps: string[];
+}
+export declare function parseDatabaseSourcesConfig(value: unknown): DatabaseSourcesConfig;
+export declare function databaseSources(projectRoot: string, action?: "assess" | "check" | "generate"): Promise<DatabaseSourcesReport>;