@everystack/cli 0.4.97 → 0.4.99

package/src/cli/state-apply.ts

@@ -20,7 +20,7 @@
 import { execSync, execFileSync } from 'node:child_process';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type AuthzContract, type QueryRunner } from './authz-contract';
-import type { SessionRunner } from './session';
+import { borrowedSessionRunner, type SessionRunner } from './session';
 import { introspectSchema, type SchemaSnapshot } from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { generateMigrationSql, HELD_DROP_PREFIX } from './migration-generate';
@@ -28,13 +28,19 @@ import type { SequenceDescriptor } from '@everystack/model';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
 import {
   ENSURE_RECONCILER_SQL,
+  renderProvenanceUpsert,
   renderSchemaLogInsert,
   renderSchemaLogFingerprintUpdate,
   renderSchemaLogCompletionUpdate,
 } from './derived-apply';
+import { introspectDerived } from './derived-introspect';
+import { objectGrantDelta } from './derived-plan';
 import { isPureComment, statementBody, statementHead } from './sql-statement';
+import { splitFunctionIdentity } from './pg-argtypes';
+import type { StatePrerequisite } from './edge-plan';
 
 const NOTICE_PREFIX = '-- NOTICE';
+export const STATE_PREREQUISITE_DRIFT_PREFIX = 'state prerequisite drift:';
 
 export interface ClassifiedStatements {
   /** Real DDL (possibly carrying leading -- WARNING lines) — what apply runs. */
@@ -354,6 +360,18 @@ export function worktreeDirty(modelsPath: string, cwd: string = process.cwd()):
 }
 
 export interface StateApplyOptions {
+  /**
+   * Reviewed functions that must be absent and then created before this state batch. They join
+   * the same SQL request as the policy that needs them: a collision or a later DDL error rolls
+   * back both, rather than leaving a derived object ahead of the state it serves.
+   */
+  statePrerequisites?: readonly StatePrerequisite[];
+  /**
+   * An explicit write transaction over one pinned connection. Prerequisites need this because
+   * their DDL, the state edge, and their catalog-derived provenance must commit or roll back
+   * together. A session-only or pooled QueryRunner cannot make that promise.
+   */
+  transaction?: <T>(work: (runner: QueryRunner) => Promise<T>) => Promise<T>;
   actor?: string | null;
   gitRef?: string | null;
   planRef?: string | null;
@@ -406,6 +424,18 @@ export interface StateApplyOptions {
   skippedValidations?: readonly PendingValidation[];
 }
 
+const sqlLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+/** The catalog guard belongs in the batch, not in a preceding read: a concurrent creator then
+ * causes the whole batch to roll back instead of racing past an out-of-date plan. */
+export function renderStatePrerequisiteGuard(prerequisite: StatePrerequisite): string {
+  const { qualified, args } = splitFunctionIdentity(prerequisite.identity);
+  const dot = qualified.lastIndexOf('.');
+  const schema = dot === -1 ? 'public' : qualified.slice(0, dot);
+  const name = dot === -1 ? qualified : qualified.slice(dot + 1);
+  return `DO $everystack_prerequisite$\nBEGIN\n  IF EXISTS (\n    SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n     WHERE n.nspname = ${sqlLiteral(schema)}\n       AND p.proname = ${sqlLiteral(name)}\n       AND (SELECT COALESCE(string_agg(pg_catalog.format_type(t.oid, NULL), ', ' ORDER BY t.ord), '')\n              FROM unnest(p.proargtypes::oid[]) WITH ORDINALITY AS t(oid, ord)) = ${sqlLiteral(args ?? '')}\n  ) THEN\n    RAISE EXCEPTION ${sqlLiteral(`${STATE_PREREQUISITE_DRIFT_PREFIX} ${prerequisite.identity} is already present; the target changed since minting. Re-mint with db:plan.`)};\n  END IF;\nEND\n$everystack_prerequisite$`;
+}
+
 /** A `VALIDATE CONSTRAINT` that did not pass — the key is installed but still unproven. */
 export interface PendingValidation {
   /** The exact statement to re-run once the data satisfies the key. */
@@ -475,17 +505,24 @@ async function recordPendingValidations(
   }
 }
 
+/** Escape strings independently of standard_conforming_strings, including captured session values. */
+function renderLocalSearchPath(path: string): string {
+  const literal = "E'" + path.replace(/\\/g, '\\\\').replace(/'/g, "''") + "'";
+  return `SELECT pg_catalog.set_config('search_path', ${literal}, true)`;
+}
+
 export async function applyGeneratedStatements(
   runner: QueryRunner,
   statements: string[],
   options: StateApplyOptions = {},
 ): Promise<StateApplyResult> {
   const classified = classifyGeneratedStatements(statements);
+  const prerequisites = options.statePrerequisites ?? [];
   // Checks the caller withheld before calling. They are outstanding from the first line of this
   // function: the outcome written before the batch already counts them, and they come back in the
   // result whether or not any check actually ran here.
   const skipped: PendingValidation[] = [...(options.skippedValidations ?? [])];
-  if (classified.executable.length === 0) {
+  if (classified.executable.length === 0 && prerequisites.length === 0) {
     // No DDL to run — but a re-plan against keys a PREVIOUS apply already withheld still owes
     // the audit trail a row: the promise (docs/cli.md) is every apply lands in schema_log, and
     // an apply whose only content is "these keys are still unproven" is a real apply, not a
@@ -533,12 +570,91 @@ export async function applyGeneratedStatements(
   // `batchSql` is the batch that RAN IN THIS TRANSACTION — the checks are not in it. The record
   // written below is a record of what committed, and the checks had not been attempted at that
   // point; they join the row on the amendment, where their outcome is known.
-  const batchSql = batch.join('\n;\n');
+  const prerequisiteSql = prerequisites
+    .flatMap((prerequisite) => [renderStatePrerequisiteGuard(prerequisite), prerequisite.sql]);
+  // A SQL-language prerequisite may read a table this same state edge creates. PostgreSQL
+  // validates such bodies at CREATE time unless this transaction-local setting defers it.
+  let batchSql = [...(prerequisites.length > 0 ? ['SET LOCAL check_function_bodies = off'] : []), ...prerequisiteSql, ...batch].join('\n;\n');
   const validationSql = validations.join('\n;\n');
-  const fullSql = [batchSql, validationSql].filter((s) => s.length > 0).join('\n;\n');
   const started = now();
   try {
-    if (batch.length > 0) await runner(batchSql);
+    if (prerequisites.length > 0) {
+      if (!options.transaction) {
+        throw new Error('state prerequisites require a pinned write transaction; this apply lane cannot prove atomic provenance.');
+      }
+      await options.transaction(async (transactionRunner) => {
+        const [settings] = await transactionRunner("SELECT pg_catalog.current_setting('search_path') AS search_path");
+        const originalPath = settings?.search_path;
+        if (typeof originalPath !== 'string') throw new Error('could not capture prerequisite search_path; no state was applied.');
+        // Defaults and SQL-standard bodies bind names at CREATE time. Use the full declared
+        // path recorded at mint, then restore the exact connection setting before state DDL.
+        batchSql = ['SET LOCAL check_function_bodies = off', ...prerequisites.flatMap((prerequisite) => [
+          renderStatePrerequisiteGuard(prerequisite),
+          ...(prerequisite.searchPath === null ? [] : [renderLocalSearchPath(prerequisite.searchPath)]),
+          prerequisite.sql,
+          ...(prerequisite.searchPath === null ? [] : [renderLocalSearchPath(originalPath)]),
+        ]), ...batch].join('\n;\n');
+        await transactionRunner(batchSql);
+        // `defHash` is PostgreSQL's canonical deparse, so source text cannot predict it. Read it
+        // after the CREATE through the OPEN transaction, then write provenance before COMMIT.
+        const reread = async () => new Map((await introspectDerived(borrowedSessionRunner(transactionRunner)))
+          .objects.map((object) => [object.identity, object]));
+        let liveByIdentity = await reread();
+        const grantDelta = (prerequisite: StatePrerequisite) => {
+          const live = liveByIdentity.get(prerequisite.identity);
+          if (!live || live.grants === undefined) {
+            throw new Error(`state prerequisite ${prerequisite.identity} has no readable grant catalog; no provenance was written.`);
+          }
+          const contract = prerequisite.grantContract;
+          if (contract.owner && live.owner !== contract.owner) {
+            throw new Error(`state prerequisite ${prerequisite.identity} owner did not converge to ${contract.owner}; no provenance was written.`);
+          }
+          const delta = objectGrantDelta({ ...contract, identity: prerequisite.identity, kind: 'function' }, live);
+          if (!delta || delta.columnScoped || delta.suppressed.length > 0) {
+            throw new Error(`state prerequisite ${prerequisite.identity} grants cannot be verified; no provenance was written.`);
+          }
+          return delta.statements;
+        };
+        // CREATE inherits default ACLs, and ALTER OWNER can remove a declared builder grant.
+        // Settle from the actual catalog using the same grant diff as derived reconcile.
+        const settle = prerequisites.flatMap((prerequisite) => {
+          const statements = grantDelta(prerequisite);
+          const { owner, ownerMode } = prerequisite.grantContract;
+          return statements.length > 0 && owner && ownerMode === 'set-role'
+            ? [`SET ROLE ${owner}`, ...statements, 'RESET ROLE'] : statements;
+        });
+        if (settle.length > 0) {
+          const settleSql = settle.join('\n;\n');
+          batchSql += `\n;\n${settleSql}`;
+          await transactionRunner(settleSql);
+          liveByIdentity = await reread();
+        }
+        // A successful REVOKE can be a warning-only no-op. Only a second catalog read proves it.
+        for (const prerequisite of prerequisites) {
+          const remaining = grantDelta(prerequisite);
+          if (remaining.length > 0) {
+            throw new Error(`state prerequisite ${prerequisite.identity} grants did not converge: still needs ${remaining.join('; ')}. No provenance was written.`);
+          }
+        }
+        const provenanceSql = prerequisites.map((prerequisite) => {
+          const liveObject = liveByIdentity.get(prerequisite.identity);
+          if (!liveObject) {
+            throw new Error(`state prerequisite ${prerequisite.identity} was created but is not introspectable before commit; provenance was not recorded.`);
+          }
+          return renderProvenanceUpsert(
+            prerequisite.identity,
+            prerequisite.provenance.srcHash,
+            liveObject.defHash,
+            prerequisite.provenance.kind,
+            prerequisite.provenance.dropSql,
+            prerequisite.provenance.bodyHash,
+          );
+        });
+        await transactionRunner(provenanceSql.join('\n;\n'));
+      });
+    } else if (batchSql.length > 0) {
+      await runner(batchSql);
+    }
   } catch (err: any) {
     try {
       await runner(renderSchemaLogInsert({
@@ -606,7 +722,7 @@ export async function applyGeneratedStatements(
     try {
       await runner(renderSchemaLogCompletionUpdate(logId, {
         outcome: outcomeWith(pendingValidations.length),
-        sql: fullSql,
+        sql: [batchSql, validationSql].filter((s) => s.length > 0).join('\n;\n'),
         durationMs: now() - started,
       }));
     } catch { /* the memoir is best-effort; the row already says what committed */ }

package/src/cli/state-function-deps.ts

@@ -25,7 +25,20 @@ import type { QueryRunner } from './authz-contract';
 import type { SessionRunner } from './session';
 import type { SourceObject } from './derived-source';
 import { executeReconcile } from './commands/db-reconcile';
+import { introspectDerived } from './derived-introspect';
+import { planReconcile } from './derived-plan';
+import {
+  builderOwnerMode,
+  derivedSearchPath,
+  ownerPreflightRefusal,
+  ownerPreflightSql,
+  ownerRequirements,
+  renderReconcileSql,
+  renderEnsureObjectSchemas,
+} from './derived-apply';
 import { functionIdentity } from './pg-argtypes';
+import { quoteIdent } from './pg-ident';
+import type { StatePrerequisite } from './edge-plan';
 
 const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
@@ -48,6 +61,84 @@ export function stateReferencedFunctions(statements: readonly string[], declared
     && callPattern(o.schema, o.name).test(text));
 }
 
+/**
+ * The plan artifact's complete prerequisite list. Liveness is supplied by the command shell so
+ * this stays pure alongside `stateReferencedFunctions`: db:diff and unit tests can make the same
+ * decision without opening a database, while db:plan provides the target's exact identities.
+ */
+export function planStatePrerequisites(
+  statements: readonly string[],
+  declared: readonly SourceObject[],
+  present: ReadonlySet<string>,
+): StatePrerequisite[] {
+  const schemas = derivedSearchPath([...declared]);
+  const searchPath = schemas.length === 1 && schemas[0] === 'public'
+    ? null : schemas.map(quoteIdent).join(', ');
+  return stateReferencedFunctions(statements, declared)
+    .filter((functionObject) => !present.has(functionObject.identity))
+    .map((functionObject) => ({
+      identity: functionObject.identity,
+      sql: functionObject.sql,
+      expected: 'absent',
+      searchPath,
+      grantContract: {
+        attachments: functionObject.attachments.filter((a) => a.kind === 'grant'),
+        ...(functionObject.owner ? { owner: functionObject.owner } : {}),
+        ownerMode: 'set-role',
+      },
+      provenance: {
+        srcHash: functionObject.hash,
+        ...(functionObject.bodyHash ? { bodyHash: functionObject.bodyHash } : {}),
+        kind: 'function' as const,
+        ...(functionObject.drop ? { dropSql: functionObject.drop } : {}),
+      },
+    }));
+}
+
+/** Read the target's function identities for the plan's referenced declarations only. */
+export async function mintStatePrerequisites(
+  runner: QueryRunner,
+  session: SessionRunner,
+  statements: readonly string[],
+  declared: readonly SourceObject[],
+): Promise<StatePrerequisite[]> {
+  const referenced = stateReferencedFunctions(statements, declared);
+  if (referenced.length === 0) return [];
+  const live = await introspectDerived(session);
+  const present = new Set(live.objects.filter((o) => o.kind === 'function').map((o) => o.identity));
+  const missing = planStatePrerequisites(statements, declared, present);
+  if (missing.length === 0) return [];
+
+  // The artifact must carry the same owner and attachment SQL as a normal derived apply. The
+  // preflight chooses the safe mechanism from the target builder while minting, so apply only
+  // executes reviewed text and never re-decides a privilege boundary.
+  const parsed = { objects: [...declared], warnings: [] as string[] };
+  const identities = missing.map((p) => p.identity);
+  const combined = planReconcile(parsed, live, { only: identities });
+  const requirements = ownerRequirements(combined, parsed.objects);
+  let ownerMode = undefined;
+  if (requirements.length > 0) {
+    const rows = await runner(ownerPreflightSql(requirements));
+    const refusal = ownerPreflightRefusal(rows as any[]);
+    if (refusal) throw new Error(`could not mint state prerequisites: ${refusal}`);
+    ownerMode = builderOwnerMode(rows as any[]);
+  }
+
+  return missing.map((prerequisite) => {
+    const one = planReconcile(parsed, live, { only: [prerequisite.identity] });
+    const rendered = renderReconcileSql(one, parsed.objects, ownerMode);
+    if (rendered.record.length !== 1 || rendered.record[0] !== prerequisite.identity) {
+      throw new Error(`could not mint state prerequisite ${prerequisite.identity}: target changed while minting; re-run db:plan.`);
+    }
+    const source = referenced.find((o) => o.identity === prerequisite.identity)!;
+    return {
+      ...prerequisite,
+      sql: [...renderEnsureObjectSchemas([source]), ...rendered.statements].join('\n;\n'),
+      grantContract: { ...prerequisite.grantContract, ownerMode: ownerMode ?? 'set-role' },
+    };
+  });
+}
+
 const literal = (s: string): string => `'${s.replace(/'/g, "''")}'`;
 
 /**