@everystack/cli 0.4.96 → 0.4.98

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.98] - 2026-09-27
+
+### Added
+
+- mint state function prerequisites
+- apply state prerequisites atomically
+
+### Fixed
+
+- version state prerequisites in plans
+- govern state prerequisites
+- defer state prerequisite body checks
+- verify prerequisite grants before commit
+- preserve prerequisite search paths
+
+## [0.4.97] - 2026-09-26
+
+### Fixed
+
+- revoke sessions when users are blocked
+- converge literal and owner policy predicates
+- precreate missing function overloads
+
+### Changed
+
+- reuse declared derived during apply
+
+## [0.4.96] - 2026-09-26
+
+### BREAKING CHANGES
+
+- defineModel refuses owner or via under a no-session audience
+
+### Fixed
+
+- a policy that calls a declared function builds in one run
+- refuse role: 'anon' combined with owner or via
+- db:pull never renders role: 'anon' with owner:
+
 ## [0.4.95] - 2026-09-26
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.96",
+  "version": "0.4.98",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -182,7 +182,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.33"
+    "@everystack/server": "0.4.34"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -56,7 +56,11 @@ import {
 } from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
-import { applyGeneratedStatements } from './state-apply';
+import {
+  applyGeneratedStatements,
+  STATE_PREREQUISITE_DRIFT_PREFIX,
+  type StateApplyResult,
+} from './state-apply';
 import {
   fkOrphanChecks,
   fkOrphanSql,
@@ -88,6 +92,8 @@ import type { DescentLedgerRow, LedgerRead } from './git-descent';
  */
 export interface ApplyPlanOptions {
   actor?: string | null;
+  /** Pinned write transaction for prerequisite DDL + state DDL + provenance. */
+  transaction?: <T>(work: (runner: QueryRunner) => Promise<T>) => Promise<T>;
   /** Defaults to the plan's own gitRef (the intent that minted it). */
   gitRef?: string | null;
   /**
@@ -149,15 +155,8 @@ export interface ApplyPlanOptions {
    * (which runs before the write) — the getter reads it at write time.
    */
   descentNote?: () => string | undefined;
-  /**
-   * Called with the statements about to run, AFTER every gate above has passed and BEFORE the
-   * batch — so a refused apply writes nothing through it. db:apply's direct lane uses it to
-   * create the declared functions a policy in the plan calls (state-function-deps.ts), which on
-   * a fresh target do not exist until the derived catch-up. Functions are not in the base
-   * fingerprint, so this moves neither the lock nor the verify-after endpoint. Omitted, the
-   * apply is unchanged (the ops-Lambda lane does not pass it).
-   */
-  beforeStateBatch?: (statements: readonly string[]) => Promise<unknown>;
+  /** State-only deliberately skips function writes, including plan prerequisites. */
+  stateOnly?: boolean;
 }
 
 export interface ApplyPlanResult {
@@ -542,25 +541,38 @@ export async function executeApplyPlan(
   // rewritten — the plan is an artifact under a content hash, and `planHash(plan)` below has to
   // keep naming the file the operator reviewed.
   const { statements: toRun, withheld } = withheldValidations(plan.statements, orphans);
+  if (options.stateOnly && plan.statePrerequisites?.length) {
+    const reason = 'this plan needs state prerequisites, but --state-only skips function writes. Apply the reviewed plan without --state-only, or satisfy the prerequisites and re-mint.';
+    await recordRefusal(runner, plan, live, 'state prerequisites', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
 
-  if (options.beforeStateBatch) await options.beforeStateBatch(toRun);
-
-  const result = await applyGeneratedStatements(runner, toRun, {
-    ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
-    actor: options.actor,
-    gitRef: options.gitRef ?? plan.gitRef,
-    planRef: planHash(plan),
-    fromFingerprint: live,
-    fpVersion: FINGERPRINT_VERSION,
-    dirty: options.dirty ?? false,
-    now: options.now,
+  let result: StateApplyResult;
+  try {
+    result = await applyGeneratedStatements(runner, toRun, {
+      statePrerequisites: plan.statePrerequisites,
+      transaction: options.transaction,
+      ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
+      actor: options.actor,
+      gitRef: options.gitRef ?? plan.gitRef,
+      planRef: planHash(plan),
+      fromFingerprint: live,
+      fpVersion: FINGERPRINT_VERSION,
+      dirty: options.dirty ?? false,
+      now: options.now,
     // The hash to stamp on the record written the moment the batch commits — the live state as
     // it is THEN, with any new key installed and not yet proven. The plan's own endpoint is
     // stamped below, after the last check has actually passed; predicting it here would put a
     // state the database is not in onto the row every later apply descends from.
     readFingerprint: async () => (await liveBaseFingerprint(session)).hash,
-    ...(options.descentNote ? { descentNote: options.descentNote } : {}),
-  });
+      ...(options.descentNote ? { descentNote: options.descentNote } : {}),
+    });
+  } catch (err: any) {
+    const message = String(err?.message ?? err);
+    if (!message.includes(STATE_PREREQUISITE_DRIFT_PREFIX)) throw err;
+    await recordRefusal(runner, plan, live, 'state prerequisites', message, options);
+    return { status: 'refused', liveFingerprint: live, reason: message };
+  }
 
   const { hash: landed } = await liveBaseFingerprint(session);
   if (result.logId !== undefined) {

package/src/cli/authz-compile.ts

@@ -77,6 +77,16 @@ function ownerPredicate(sqlColumn: string, type: string, claim: string, expr: st
   return `(${sqlColumn} = (${ce})::${castForType(type)})`;
 }
 
+// A hand-written predicate can spell the same inline JWT owner check as `owner:`.  Match only
+// that complete shape, then emit the one PostgreSQL form the structured shorthand uses.
+const HAND_WRITTEN_OWNER_RE =
+  /^\(?([a-z_][a-z0-9_]*)\s*=\s*\(\(current_setting\('request\.jwt\.claims'(?:::text)?,\s*true\)\)::jsonb\s*->>\s*'([a-z_]+)'(?:::text)?\)::([a-z]+)\)?$/i;
+
+function normalizeHandWrittenOwnerPredicate(text: string): string | null {
+  const match = HAND_WRITTEN_OWNER_RE.exec(text);
+  return match ? ownerPredicate(match[1], match[3], match[2]) : null;
+}
+
 /** The soft-delete guard, in deparser normal form: `(deleted_at IS NULL)`. */
 function softDeleteGuard(sqlColumn: string): string {
   return `(${sqlColumn} IS NULL)`;
@@ -315,7 +325,9 @@ function rawPredicate(value: unknown, where: string): string | null {
   // plan a DROP + CREATE that changed nothing. A bare call is the exception: the deparser
   // prints `has_permission()` with no outer parens, so wrapping it is that same churn.
   const t = text.trim();
-  return isBareCall(t) ? t : parenthesizeOnce(t);
+  const owner = normalizeHandWrittenOwnerPredicate(t);
+  if (owner) return owner;
+  return isBareCall(t) || t === 'true' || t === 'false' ? t : parenthesizeOnce(t);
 }
 
 /**

package/src/cli/commands/db-apply.ts

@@ -62,7 +62,6 @@ import path from 'node:path';
 import { resolveModelsPath } from '../models-path';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived } from '../declared-derived';
-import { createStateReferencedFunctions } from '../state-function-deps';
 import { compileTableContract } from '../authz-compile';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline';
@@ -620,6 +619,7 @@ async function applyPlanViaStage(
       actor: process.env.USER ?? null,
       gitRef: currentGitRef() ?? plan.gitRef,
       dirty: worktreeDirty(resolveModelsPath(flags.models)),
+      stateOnly: flags['state-only'] === 'true',
       descentVerdict,
       ...(descentAttested ? { descentAttested } : {}),
       ...(authorityVerdict ? { authorityVerdict } : {}),
@@ -1052,10 +1052,15 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   }
 
   step(connectingVia(dbSource));
-  const { runner, session, end } = await createUrlRunner(dbSource.url);
+  const { runner, session, transaction, end } = await createUrlRunner(dbSource.url);
 
   let landed: ApplyPlanResult | undefined;
   let catchUp: CatchUpReport = { ok: true, statements: [] };
+  // Both gates below need the declared derived bundle. Keep its existing lazy timing — the
+  // baseline gate is still the first reader — but never evaluate the models barrel twice.
+  let declaredDbPromise: ReturnType<typeof loadDeclaredDerived> | undefined;
+  const declaredDb = (): ReturnType<typeof loadDeclaredDerived> =>
+    declaredDbPromise ??= loadDeclaredDerived(flags.models);
   try {
     // The edge as hashes — internal bookkeeping, not what a reader came for. Verbose only.
   if (flags.verbose === 'true') info(`plan ${planHash(plan).slice(0, 12)}: ${plan.fromFingerprint.slice(0, 12)} → ${plan.toFingerprint.slice(0, 12)} (${plan.executable} statement(s)${plan.destructive ? `, ${plan.destructive} destructive` : ''})`);
@@ -1086,6 +1091,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
       async () => {
         const result = await executeApplyPlan(runner, session, plan, {
+          transaction,
           actor: process.env.USER ?? null,
           gitRef: currentGitRef() ?? plan.gitRef,
           ...(verifyAuthority ? { verifyAuthority } : {}),
@@ -1110,7 +1116,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           verifyAuthzBaseline: async ({ contract }) => {
             const stageName = flags.stage || 'local';
             const models = await loadModels(resolveModelsPath(flags.models));
-            const governedRoles = (await loadDeclaredDerived(flags.models))?.governedRoles ?? [];
+            const governedRoles = (await declaredDb())?.governedRoles ?? [];
             const declaredAuthz = { tables: models.map((m) => compileTableContract(m, {})), functions: [] };
             const exemptions = ungovernedGrants(contract, governedRoleSet(declaredAuthz, governedRoles));
             const violations = checkAgainstBaseline(await readBaselineFile(), stageName, exemptions);
@@ -1120,18 +1126,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
           },
           dirty: worktreeDirty(resolveModelsPath(flags.models)),
           descentNote: () => descentAttested,
-          // A declared function a policy in this plan calls must exist before the policy — on a
-          // fresh target it would otherwise arrive only with the catch-up below. Only the called,
-          // missing ones; --state-only asked for no derived writes, so it is skipped there.
-          ...(flags['state-only'] === 'true' ? {} : {
-            beforeStateBatch: async (statements: readonly string[]) => {
-              const declaredDb = await loadDeclaredDerived(flags.models);
-              const created = await createStateReferencedFunctions(runner, session, statements, declaredDb?.objects ?? [], {
-                actor: process.env.USER ?? null, gitRef: currentGitRef() ?? plan.gitRef,
-              });
-              if (created.length > 0) info(`created ${created.length} declared function(s) the plan's policies call, before the plan: ${created.join(', ')}`);
-            },
-          }),
+          stateOnly: flags['state-only'] === 'true',
           checkDescent: async (live: LiveState & { fingerprint: string; ledger: DescentLedgerRow[]; ledgerRead: LedgerRead }) => {
             step('Descent: proving the fast-forward rule against the schema_log ledger...');
             const result = await proveDescentForApply({

package/src/cli/commands/db-plan.ts

@@ -76,6 +76,7 @@ import { reportPipelineLastRun } from './pipeline-run';
 import { renderPlanReport } from '../plain-output';
 import { fkOrphanChecks, fkOrphanSql, fkOrphanFindings, checkOrphanRowShape } from '../fk-preflight';
 import { renderFkOrphanAdvisory, ownershipColumns } from '../fk-orphan-advisory';
+import { mintStatePrerequisites } from '../state-function-deps';
 import { step, success, fail, info, warn, line as printLine, reserveStdoutForData } from '../output';
 
 /**
@@ -308,6 +309,11 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
 
+    // The edge is pure, but this decision belongs to mint: only this command holds both the
+    // checkout's declared functions and the live catalog. Embedding the exact missing CREATEs
+    // lets every apply lane enact the reviewed answer without reading source again.
+    plan.statePrerequisites = await mintStatePrerequisites(runner, session, plan.statements, declaredDerived?.objects ?? []);
+
     // The plan lane's contract: what it mints, it can apply. A SET DATA TYPE on a
     // column a view/matview/rule binds would fail MID-TRANSACTION at apply
     // ("cannot alter type of a column used by a view or rule") — refuse at mint,

package/src/cli/db-source.ts

@@ -73,6 +73,8 @@ export interface UrlRunner {
    * so a caller typed against `SessionRunner` reads identically on either venue.
    */
   session: SessionRunner;
+  /** One pinned write transaction, for an edge that must inspect uncommitted catalog state. */
+  transaction: <T>(fn: (runner: QueryRunner) => Promise<T>) => Promise<T>;
   /** Close the client so the process can exit cleanly. */
   end: () => Promise<void>;
 }
@@ -154,6 +156,7 @@ export async function createUrlRunner(
   return {
     runner: async (query: string) => Array.from(await sql.unsafe(query)),
     session: sessionRunnerOver(sql),
+    transaction: async (fn) => sql.begin((tx: any) => fn(async (query: string) => Array.from(await tx.unsafe(query)))),
     end: () => sql.end({ timeout: 5 }),
   };
 }

package/src/cli/derived-plan.ts

@@ -155,7 +155,7 @@ export interface ReconcileOptions {
 
 const isRelation = (kind: DerivedKind): boolean => kind !== 'function';
 
-const ownerContext = (src: SourceObject, liveObj: LiveObject): GrantOwnerContext => ({
+const ownerContext = (src: Pick<SourceObject, 'owner'>, liveObj: LiveObject): GrantOwnerContext => ({
   ...(src.owner !== undefined ? { declared: src.owner } : {}),
   ...(liveObj.owner !== undefined ? { live: liveObj.owner } : {}),
 });
@@ -178,7 +178,7 @@ const ownerContext = (src: SourceObject, liveObj: LiveObject): GrantOwnerContext
  * failure to ADD access (availability), never to remove it.
  */
 export function objectGrantDelta(
-  src: SourceObject,
+  src: Pick<SourceObject, 'kind' | 'identity' | 'attachments' | 'owner'>,
   liveObj: LiveObject,
   liveGrants: Record<string, string[]> | undefined = liveObj.grants,
 ): (ObjectGrantDiff & { columnScoped: boolean }) | null {

package/src/cli/edge-plan.ts

@@ -25,6 +25,8 @@
  */
 
 import { createHash } from 'node:crypto';
+import type { Attachment } from './derived-source';
+import type { OwnerApplyMode } from './derived-apply';
 import type { ModelDescriptor } from '@everystack/model';
 import type { SchemaSnapshot, TableSchema } from './schema-introspect';
 import type { AuthzContract, SequenceGrantContract, DefaultAclScope } from './authz-contract';
@@ -39,7 +41,19 @@ import { fingerprintLive, fingerprintState, fingerprintModels, governedRolesForM
 import { compileDeclaredState } from './declared-diff';
 import { compileTableRenames, compileTableMoves, compileRenames } from './schema-compile';
 
-export const PLAN_VERSION = 2;
+/**
+ * v3 adds `statePrerequisites`: SQL definitions db:apply must establish before the state edge.
+ * v4 makes each prerequisite a complete, governed derived-object create and carries the source
+ * metadata needed to record canonical catalog provenance in the same transaction as the edge.
+ * v5 adds the declared grant contract and owner mode for post-create ACL settlement and
+ * verification. A v4 reader skips those checks and must not apply this artifact.
+ * v6 records each prerequisite's declared search path, restored before state DDL. A v5 reader
+ * can bind argument defaults to the wrong function and must not apply this artifact.
+ * A v3 reader does not know how to enact or record those prerequisites, so the file formats are
+ * not compatible. The existing db:apply version refusal makes the mismatch a re-mint before any
+ * write, rather than letting a peer silently omit part of the reviewed artifact.
+ */
+export const PLAN_VERSION = 6;
 
 /**
  * The db:apply WIRE CONTRACT between the CLI and the ops Lambda — distinct from PLAN_VERSION,
@@ -84,8 +98,28 @@ export const PLAN_VERSION = 2;
  * to remove, reintroduced silently across a version skew instead of refused cleanly. The BUMP
  * RULE covers exactly this: a field the CLIENT now depends on to decide something is part of the
  * contract. Peers refuse until the stage is redeployed.
+ *
+ * v6 (milestone plan-state-prerequisites-format): the plan in the payload gained
+ * `statePrerequisites`, definitions the server must establish before it applies the state edge.
+ * A v5 ops Lambda would not know to execute them and would silently skip a reviewed prerequisite
+ * before applying the rest of the plan. The BUMP RULE says that changed server work is part of
+ * the contract, so the peers refuse until the stage is redeployed.
+ *
+ * v7 (milestone atomic-state-prerequisites): the payload gained `stateOnly` and the ops Lambda
+ * refuses a prerequisite-bearing plan when it is true. A v6 Lambda would accept the request and
+ * create the prerequisite, contradicting `--state-only`'s promise to skip function writes.
+ *
+ * v8 (milestone governed-state-prerequisites): prerequisite application now records derived
+ * provenance before its transaction commits. A v7 ops Lambda could create a governed function
+ * without its provenance row, leaving the next catch-up to require a baseline.
+ *
+ * v9 settles and verifies prerequisite grants before commit. A v8 stage could leave an
+ * undeclared default EXECUTE grantee live while reporting a successful governed create.
+ *
+ * v10 applies the reviewed prerequisite search path and restores the transaction's original
+ * path before state DDL and grant verification. A v9 stage could bind defaults to other schemas.
  */
-export const APPLY_CONTRACT_VERSION = 5;
+export const APPLY_CONTRACT_VERSION = 10;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
@@ -107,6 +141,31 @@ export interface PlanClassification {
   unclassified?: number;
 }
 
+/** A definition that db:apply must establish before it applies the state edge. */
+export type StatePrerequisite = {
+  /** The function's full PostgreSQL identity: `schema.name(argtypes)`. */
+  identity: string;
+  /** The exact schema preparation, CREATE, ownership, grant, and comment SQL db:apply runs. */
+  sql: string;
+  /** The catalog condition db:apply must prove before it runs `sql`. */
+  expected: 'absent';
+  /** Full declared derived path, with quoted identifiers; null preserves the ambient all-public path. */
+  searchPath: string | null;
+  /** Reviewed grant declarations and the owner mechanism selected at mint. No source reload at apply. */
+  grantContract: {
+    attachments: Attachment[];
+    owner?: string;
+    ownerMode: OwnerApplyMode;
+  };
+  /** Source facts needed to record the catalog-derived provenance hash after this transaction creates it. */
+  provenance: {
+    srcHash: string;
+    bodyHash?: string;
+    kind: 'function';
+    dropSql?: string;
+  };
+};
+
 export interface EdgePlan {
   v: number;
   /** The target's exact live fingerprint at mint time — the lock. */
@@ -169,6 +228,11 @@ export interface EdgePlan {
   declaredFingerprint: string;
   /** The edge, in db:generate's statement grammar (no held drops — mint refuses them). */
   statements: string[];
+  /**
+   * Definitions that must exist before the state edge can land. Optional because plans minted
+   * before this field existed have none; an absent field means no prerequisite was recorded.
+   */
+  statePrerequisites?: readonly StatePrerequisite[];
   executable: number;
   /** Executable statements that LOSE DATA (drops + narrowing type changes) — red, gated at apply. */
   destructive: number;

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,6 +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, '\\$&');
 
@@ -47,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, "''")}'`;
 
 /**
@@ -72,12 +164,17 @@ export async function createStateReferencedFunctions(
   if (referenced.length === 0) return [];
 
   const live = await runner(
-    `SELECT n.nspname AS schema, p.proname AS name FROM pg_proc p
+    `SELECT n.nspname AS schema, p.proname AS name,
+            (SELECT COALESCE(string_agg(pg_catalog.format_type(t.oid, NULL), ', ' ORDER BY t.ord), '')
+               FROM unnest(p.proargtypes::oid[]) WITH ORDINALITY AS t(oid, ord)) AS args
+       FROM pg_proc p
        JOIN pg_namespace n ON n.oid = p.pronamespace
       WHERE p.proname IN (${[...new Set(referenced.map((o) => o.name))].map(literal).join(', ')})`,
   );
-  const present = new Set(live.map((r: any) => `${r.schema}.${r.name}`));
-  const missing = referenced.filter((o) => !present.has(`${o.schema}.${o.name}`));
+  const present = new Set(live.map((r: any) => functionIdentity(
+    String(r.schema), String(r.name), String(r.args).trim() ? String(r.args).split(',').map((arg) => arg.trim()) : [],
+  )));
+  const missing = referenced.filter((o) => !present.has(o.identity));
   if (missing.length === 0) return [];
 
   const run = await executeReconcile(runner, session, {