@everystack/cli 0.4.105 → 0.4.107

package/src/cli/state-apply.ts

@@ -37,7 +37,7 @@ 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';
+import type { StateDependent, StatePrerequisite } from './edge-plan';
 
 const NOTICE_PREFIX = '-- NOTICE';
 export const STATE_PREREQUISITE_DRIFT_PREFIX = 'state prerequisite drift:';
@@ -366,6 +366,11 @@ export interface StateApplyOptions {
    * back both, rather than leaving a derived object ahead of the state it serves.
    */
   statePrerequisites?: readonly StatePrerequisite[];
+  /**
+   * Reviewed declared views and matviews a type change in this batch binds: dropped (dependents
+   * first) before it and re-created after it, in the same transaction, so they are never absent.
+   */
+  stateDependents?: readonly StateDependent[];
   /**
    * 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
@@ -518,6 +523,7 @@ export async function applyGeneratedStatements(
 ): Promise<StateApplyResult> {
   const classified = classifyGeneratedStatements(statements);
   const prerequisites = options.statePrerequisites ?? [];
+  const dependents = options.stateDependents ?? [];
   // 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.
@@ -583,7 +589,7 @@ export async function applyGeneratedStatements(
   const validationSql = validations.join('\n;\n');
   const started = now();
   try {
-    if (prerequisites.length > 0) {
+    if (prerequisites.length > 0 || dependents.length > 0) {
       if (!options.transaction) {
         throw new Error('state prerequisites require a pinned write transaction; this apply lane cannot prove atomic provenance.');
       }
@@ -591,39 +597,65 @@ export async function applyGeneratedStatements(
         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.');
+        const reread = async () => new Map((await introspectDerived(borrowedSessionRunner(transactionRunner)))
+          .objects.map((object) => [object.identity, object]));
+        // A dependent is re-created from the reviewed SQL, so it must still be the object the mint
+        // read. Checked inside the transaction, before any write.
+        if (dependents.length > 0) {
+          const before = await reread();
+          for (const dependent of dependents) {
+            if (before.get(dependent.identity)?.defHash !== dependent.expectedDefHash) {
+              throw new Error(`${STATE_PREREQUISITE_DRIFT_PREFIX} ${dependent.kind} ${dependent.identity} is not the one this plan was minted against; the target changed since minting. Re-mint with db:plan.`);
+            }
+          }
+        }
         // Defaults and SQL-standard bodies bind names at CREATE time. Use the full declared
         // path recorded at mint, then restore the exact connection setting; the state DDL
-        // that follows pins the canonical path itself.
-        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)]),
-        ]), ...stateBatch].join('\n;\n');
+        // that follows pins the canonical path itself. Dependents drop before the edge, children
+        // first, and come back after it, parents first, under their declared path.
+        batchSql = [
+          ...(prerequisites.length > 0 ? ['SET LOCAL check_function_bodies = off'] : []),
+          ...prerequisites.flatMap((prerequisite) => [
+            renderStatePrerequisiteGuard(prerequisite),
+            ...(prerequisite.searchPath === null ? [] : [renderLocalSearchPath(prerequisite.searchPath)]),
+            prerequisite.sql,
+            ...(prerequisite.searchPath === null ? [] : [renderLocalSearchPath(originalPath)]),
+          ]),
+          ...[...dependents].reverse().map((dependent) => dependent.dropSql),
+          ...stateBatch,
+          ...dependents.flatMap((dependent) => [renderLocalSearchPath(dependent.searchPath ?? originalPath), dependent.sql]),
+          ...(dependents.length > 0 ? [renderLocalSearchPath(originalPath)] : []),
+        ].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]));
+        const created: Array<{ identity: string; kind: 'function' | StateDependent['kind']; grantContract: StatePrerequisite['grantContract'];
+          provenance: { srcHash: string; bodyHash?: string; kind: string; dropSql?: string } }> = [
+          ...prerequisites.map((p) => ({ identity: p.identity, kind: 'function' as const, grantContract: p.grantContract, provenance: p.provenance })),
+          ...dependents.map((d) => ({ identity: d.identity, kind: d.kind, grantContract: d.grantContract, provenance: d.provenance })),
+        ];
         let liveByIdentity = await reread();
-        const grantDelta = (prerequisite: StatePrerequisite) => {
+        // A function is a state prerequisite; a re-created dependent is named as the view it is.
+        const objectLabel = (object: (typeof created)[number]): string =>
+          `${object.kind === 'function' ? 'state prerequisite' : object.kind} ${object.identity}`;
+        const grantDelta = (prerequisite: (typeof created)[number]) => {
           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.`);
+            throw new Error(`${objectLabel(prerequisite)} 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.`);
+            throw new Error(`${objectLabel(prerequisite)} owner did not converge to ${contract.owner}; no provenance was written.`);
           }
-          const delta = objectGrantDelta({ ...contract, identity: prerequisite.identity, kind: 'function' }, live);
+          const delta = objectGrantDelta({ ...contract, identity: prerequisite.identity, kind: prerequisite.kind }, live);
           if (!delta || delta.columnScoped || delta.suppressed.length > 0) {
-            throw new Error(`state prerequisite ${prerequisite.identity} grants cannot be verified; no provenance was written.`);
+            throw new Error(`${objectLabel(prerequisite)} 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 settle = created.flatMap((prerequisite) => {
           const statements = grantDelta(prerequisite);
           const { owner, ownerMode } = prerequisite.grantContract;
           return statements.length > 0 && owner && ownerMode === 'set-role'
@@ -636,16 +668,16 @@ export async function applyGeneratedStatements(
           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) {
+        for (const prerequisite of created) {
           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.`);
+            throw new Error(`${objectLabel(prerequisite)} grants did not converge: still needs ${remaining.join('; ')}. No provenance was written.`);
           }
         }
-        const provenanceSql = prerequisites.map((prerequisite) => {
+        const provenanceSql = created.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.`);
+            throw new Error(`${objectLabel(prerequisite)} was created but is not introspectable before commit; provenance was not recorded.`);
           }
           return renderProvenanceUpsert(
             prerequisite.identity,