@everystack/cli 0.4.105 → 0.4.107

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

@@ -63,7 +63,7 @@ import { resolveModelsPath } from '../models-path';
 import { resolveConfig, opsFunction } from '../config';
 import { resolveOperatorUrlViaStage } from '../direct-venue';
 import { lambdaQueryRunner, lambdaSessionRunner } from '../aws';
-import { lifecycleApplyRefusal } from '../lifecycle-preflight';
+import { lifecycleApplyReport, lifecycleProvisionFirst, lifecycleRolesOf, unclassifiedGranteesWarning } from '../lifecycle-preflight';
 import { loadModels } from './db-generate';
 import { loadDeclaredDerived, type DeclaredDerived } from '../declared-derived';
 import { introspectDerived } from '../derived-introspect';
@@ -71,7 +71,7 @@ import { planReconcile, type ReconcilePlan } from '../derived-plan';
 import { checkFails, buildReconcileReport } from './db-reconcile';
 import { governedRoleSet, ungovernedGrants } from '../authz-reconcile';
 import { readBaselineFile, checkAgainstBaseline, baselineRefusal } from '../authz-baseline';
-import { alterTypeStatementTargets, findAlterTypeDependents, renderAlterTypeRefusal } from '../alter-type-dependents';
+import { alterTypeStatementTargets, mintStateDependents, renderStateDependentLine } from '../alter-type-dependents';
 import { compileTableContract } from '../authz-compile';
 import { reportPipelineLastRun } from './pipeline-run';
 import { renderPlanReport } from '../plain-output';
@@ -238,9 +238,16 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
   }
 
   try {
-    const lifecycleNote = await lifecycleApplyRefusal(runner, models);
-    // db:plan only reads, so it mints the plan anyway; db:apply runs the same check and refuses.
-    if (lifecycleNote) warn(`db:apply will refuse this plan until each lifecycle finding below is fixed.\n${lifecycleNote}`);
+    // The modules' role declaration, as db:apply reads it. A barrel that does not compose leaves it
+    // undeclared here (the check as before); the paths that need the derived layer report the error.
+    const lifecycleRoles = lifecycleRolesOf(await loadDeclaredDerived(flags.models).catch(() => null));
+    // First, before anything else is said: what db:provision must create or fix. Nothing below
+    // can apply until it has run, and the fix is a verb, not SQL.
+    const provisionFirst = await lifecycleProvisionFirst(runner, models,
+      flags.stage ? `everystack db:provision --stage ${flags.stage}` : 'everystack db:provision --database-url <this database>');
+    if (provisionFirst) warn(provisionFirst);
+    const unclassified = unclassifiedGranteesWarning(models, lifecycleRoles);
+    if (unclassified) warn(unclassified);
     let snapshot: SchemaSnapshot;
     let contract: AuthzContract;
     if (dbSource.kind === 'url') {
@@ -313,22 +320,34 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       process.exit(1);
     }
 
+    // The lifecycle catalog check db:apply runs, over THIS plan: a finding the plan's own REVOKE
+    // removes is listed as resolved; the rest will block the apply. db:plan only reads, so it
+    // mints the plan anyway. Read after the mint because the plan is half of the answer.
+    const lifecycle = await lifecycleApplyReport(runner, models, lifecycleRoles, plan.statements);
+    if (lifecycle.resolved) info(lifecycle.resolved);
+    if (lifecycle.refusal) warn(`db:apply will refuse this plan until each lifecycle finding below is fixed.\n${lifecycle.refusal}`);
+
     // 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,
-    // with the dependents named, while there is still a live catalog to ask.
+    // The plan lane's contract: what it mints, it can apply. A SET DATA TYPE on a column a view
+    // or matview binds fails at apply ("cannot alter type of a column used by a view or rule").
+    // The declared ones ride on the plan: the state transaction drops them, changes the type and
+    // re-creates them from this checkout before COMMIT. Anything the platform cannot re-create
+    // refuses here, by name, while there is still a live catalog to ask.
     const alterTargets = alterTypeStatementTargets(plan.statements);
     if (alterTargets.length > 0) {
-      const blockedAlters = await findAlterTypeDependents(runner, alterTargets);
-      if (blockedAlters.length > 0) {
-        fail(`Mint refused: ${renderAlterTypeRefusal(blockedAlters)}`);
+      const dependents = await mintStateDependents(runner, session, alterTargets, declaredDerived?.objects ?? []);
+      if ('refusal' in dependents) {
+        fail(`Mint refused: ${dependents.refusal}`);
         process.exit(1);
       }
+      if (dependents.dependents.length > 0) {
+        plan.stateDependents = dependents.dependents;
+        for (const dependent of dependents.dependents) info(renderStateDependentLine(dependent));
+      }
     }
 
     // The class rides on the ARTIFACT, not only the terminal — a reviewer reading

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

@@ -32,7 +32,7 @@
 import type { QueryRunner } from '../authz-contract';
 import type { SourceObject } from '../derived-source';
 import { introspectDerived } from '../derived-introspect';
-import { catalogInputsFromModels, lifecycleReconcileRefusal } from '../lifecycle-preflight';
+import { catalogInputsFromModels, lifecycleReconcileRefusal, lifecycleRolesOf } from '../lifecycle-preflight';
 import { planReconcile, objectGrantDelta, TRIGGER_ENABLED_STATE, type ReconcilePlan, type ReconcileOptions } from '../derived-plan';
 import {
   renderReconcileSql,
@@ -84,6 +84,12 @@ export interface ExecuteOptions extends ReconcileOptions {
    * the check. `unknown` because the ops Lambda passes it straight off the wire.
    */
   applicationRoles?: unknown;
+  /**
+   * The modules' declared request roles and declared owners (LifecycleRoleDeclaration), beside
+   * applicationRoles. Optional: absent, the catalog check runs as before. `unknown` for the wire.
+   */
+  requestRoles?: unknown;
+  declaredOwners?: unknown;
   /**
    * The caller already ran lifecycleApplyRefusal with the full models, on this runner, in this
    * process (executeSync does, first thing), so the reconcile does not run the catalog check again.
@@ -159,7 +165,9 @@ export async function executeReconcile(
   // --rebaseline, --only, --overwrite-drift or none) refuses on it below; a plan-only run reports
   // it as a finding. See lifecycleCatalogRefusal for what it defends and from whom.
   const lifecycleGate = (): Promise<string | null> => (options.lifecyclePreflighted ? Promise.resolve(null)
-    : lifecycleReconcileRefusal(runner, parsed.objects, { applicationRoles: options.applicationRoles }));
+    : lifecycleReconcileRefusal(runner, parsed.objects, {
+      applicationRoles: options.applicationRoles, requestRoles: options.requestRoles, declaredOwners: options.declaredOwners,
+    }));
 
   if (!options.apply) {
     const lifecycleFindings = await lifecycleGate();
@@ -768,6 +776,7 @@ export async function dbReconcileCommand(flags: Record<string, string>): Promise
     // The lifecycle catalog check's roles, from the barrel's models. The tables come from the
     // declared transition triggers inside the reconcile, the same derivation the ops Lambda runs.
     applicationRoles: declared?.models ? catalogInputsFromModels(declared.models).applicationRoles : undefined,
+    ...lifecycleRolesOf(declared),
     renamedTables: declared?.renamedTables,
     baseline: flags.baseline === 'true',
     rebaseline: flags.rebaseline === 'true',

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

@@ -31,7 +31,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import type { ModelDescriptor } from '@everystack/model';
 import { introspectContract, type QueryRunner } from '../authz-contract';
-import { catalogInputsFromModels, lifecycleApplyRefusal, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError } from '../lifecycle-preflight';
+import { catalogInputsFromModels, lifecycleApplyReport, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecycleRolesOf, type LifecycleRoleDeclaration } from '../lifecycle-preflight';
 import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { generateMigrationSql, unmodeledTables } from '../migration-generate';
@@ -86,6 +86,8 @@ export interface SyncOptions {
   governedRoles?: string[];
   /** Pending table renames — trigger provenance migrates instead of drop+create. */
   renamedTables?: Record<string, string>;
+  /** The modules' role declaration (lifecycleRolesOf): what the lifecycle gates read beside the models. */
+  lifecycleRoles?: LifecycleRoleDeclaration;
   /** Injectable clock for tests. */
   now?: () => number;
 }
@@ -96,6 +98,8 @@ export interface SyncHooks {
   onStatePlan?: (statements: string[], classified: ClassifiedStatements, pass: number) => void;
   /** Fires after the state layer applied and verified, before the compute reconcile. */
   onStateDone?: (state: StateSyncOutcome) => void;
+  /** Fires before anything executes when the state diff's own REVOKEs resolve lifecycle findings (one line). */
+  onLifecycleResolved?: (line: string) => void;
 }
 
 export interface SyncRun {
@@ -138,6 +142,7 @@ async function syncOnce(
   options: SyncOptions,
   hooks: SyncHooks,
   pass: number,
+  preflight?: (statements: readonly string[]) => Promise<void>,
 ): Promise<SyncRun> {
   const current = await introspectSchema(session);
   const liveAuthz = await introspectContract(session, contractFunctionRow, FUNCTIONS_SQL);
@@ -145,6 +150,8 @@ async function syncOnce(
     allowDrops: options.allowDrops, liveAuthz, sequences: options.sequences,
     governedRoles: options.governedRoles, extensions: options.extensions,
   });
+  // Read-only, before anything is written: it needs the statements this pass will run.
+  await preflight?.(statements);
   const classified = classifyGeneratedStatements(statements);
   hooks.onStatePlan?.(statements, classified, pass);
   // A held drop of a key into a lifecycle table leaves a key the after-state catalog check refuses,
@@ -183,6 +190,8 @@ async function syncOnce(
     // The catalog check runs again here, after the state apply: a table this sync just created can
     // carry a finding (a default privilege, its owner) the check before the state apply could not see.
     applicationRoles: catalogInputsFromModels(models).applicationRoles,
+    requestRoles: options.lifecycleRoles?.requestRoles,
+    declaredOwners: options.lifecycleRoles?.declaredOwners,
   });
 
   const declaredFingerprint = fingerprintModels(models, { sequences: options.sequences }).hash;
@@ -240,13 +249,18 @@ export async function executeSync(
   hooks: SyncHooks = {},
 ): Promise<SyncRun> {
   // State runs before compute, so without this a lifecycle table would land with no transition trigger.
-  const lifecycleRefusal = await lifecycleApplyRefusal(runner, models);
-  if (lifecycleRefusal) throw new Error(lifecycleRefusal);
-  // Before anything is written, so before both places a pass creates derived objects (the
-  // functions the state batch calls, then the reconcile).
-  const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false });
-  if (ownerRefusal) throw new LifecycleFindingsError(ownerRefusal);
-  const first = await syncOnce(runner, session, models, options, hooks, 1);
+  // It reads the first pass's statements: a finding their own REVOKE removes is resolved, not refused
+  // (the state batch runs before the reconcile creates any lifecycle function, which re-checks).
+  const preflight = async (statements: readonly string[]): Promise<void> => {
+    const lifecycle = await lifecycleApplyReport(runner, models, options.lifecycleRoles, statements);
+    if (lifecycle.refusal) throw new Error(lifecycle.refusal);
+    if (lifecycle.resolved) hooks.onLifecycleResolved?.(lifecycle.resolved);
+    // Before anything is written, so before both places a pass creates derived objects (the
+    // functions the state batch calls, then the reconcile).
+    const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false, roles: options.lifecycleRoles });
+    if (ownerRefusal) throw new LifecycleFindingsError(ownerRefusal);
+  };
+  const first = await syncOnce(runner, session, models, options, hooks, 1, preflight);
   // The trigger is the STATE bar, not the combined verdict. The cause above is state-layer
   // only, so a compute refusal or an unadopted object cannot be settled by looking again —
   // retrying on those would make every brownfield sync pay a second full read (and print its
@@ -451,6 +465,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         sequences: declaredDb?.sequences,
         extensions: declaredDb?.extensions,
         renamedTables: declaredDb?.renamedTables,
+        lifecycleRoles: lifecycleRolesOf(declaredDb),
         allowDrops: flags['allow-drops'] === 'true',
         overwriteDrift: flags['overwrite-drift'] === 'true',
         baseline: flags.baseline === 'true',
@@ -482,6 +497,7 @@ export async function dbSyncCommand(flags: Record<string, string>): Promise<void
         onStateDone: () => {
           if (declaredDb?.objects.length) step('Reconciling the declared derived layer...');
         },
+        onLifecycleResolved: (line) => info(line),
       },
     );
 

package/src/cli/db-build.ts

@@ -18,7 +18,7 @@ import { compileDeclaredState } from './declared-diff';
 import { createUrlRunner } from './db-source';
 import { executeSync, buildSyncReport } from './commands/db-sync';
 import { executeReconcile } from './commands/db-reconcile';
-import { lifecycleApplyRefusal, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal } from './lifecycle-preflight';
+import { lifecycleApplyRefusal, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal, type LifecycleRoleDeclaration } from './lifecycle-preflight';
 
 const SAFE_NAME = /^[a-z_][a-z0-9_$]*$/;
 
@@ -101,6 +101,8 @@ export interface BuildOptions {
   extensions?: string[];
   actor?: string | null;
   gitRef?: string | null;
+  /** The modules' role declaration (lifecycleRolesOf): what the lifecycle gates read beside the models. */
+  lifecycleRoles?: LifecycleRoleDeclaration;
 }
 
 /**
@@ -184,7 +186,7 @@ export async function buildIntoDatabase(
     // Before the first derived write: the owners the reconcile will give the declared trigger
     // functions on lifecycle tables. This pass runs before executeSync, which judges them again
     // first thing, before its own state apply.
-    const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false });
+    const ownerRefusal = await lifecycleDeclaredOwnerRefusal(runner, session, options.declared ?? [], models, { stateApplied: false, roles: options.lifecycleRoles });
     if (ownerRefusal) throw new LifecycleFindingsError(ownerRefusal);
     const declaredFunctions = (options.declared ?? [])
       .filter((o) => o.kind === 'function' && !o.signatureDeps?.length);
@@ -192,7 +194,7 @@ export async function buildIntoDatabase(
       // The lifecycle catalog check, with the full models, before any lifecycle-owned function
       // lands: this pass declares functions only, so it carries no transition trigger for the
       // reconcile to read the lifecycle tables from. executeSync runs the same check again below.
-      const lifecycleRefusal = await lifecycleApplyRefusal(runner, models);
+      const lifecycleRefusal = await lifecycleApplyRefusal(runner, models, options.lifecycleRoles);
       if (lifecycleRefusal) throw new Error(lifecycleRefusal);
       await runner('SET check_function_bodies = off');
       try {
@@ -216,12 +218,13 @@ export async function buildIntoDatabase(
     const run = await executeSync(runner, session, models, {
       declared: options.declared,
       sequences: options.sequences,
+      lifecycleRoles: options.lifecycleRoles,
       actor: options.actor ?? 'db-build',
       gitRef: options.gitRef ?? null,
     });
     // Verification: the live catalog check again, over what the derived layer just made live. A
     // throw, so no caller (db:check's compose ring, the dev template, a test database) can miss it.
-    const post = await lifecyclePostApplyRefusal(session, models);
+    const post = await lifecyclePostApplyRefusal(session, models, options.lifecycleRoles);
     if (post) throw new LifecycleFindingsError(post);
     return {
       converged: run.converged,

package/src/cli/declared-derived.ts

@@ -12,7 +12,7 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
 import type { Module, ModelDescriptor, SequenceDescriptor, DerivedDescriptor } from '@everystack/model';
-import { linkModels, ModelLinkError, moduleGovernedRoles } from '@everystack/model';
+import { linkModels, ModelLinkError, moduleGovernedRoles, moduleRequestRoles } from '@everystack/model';
 import { compileDerived } from './derived-compile';
 import { lifecycleDerived } from './lifecycle-derived';
 import { compileTableRenames, compileTableMoves } from './schema-compile';
@@ -35,6 +35,13 @@ export interface DeclaredDerived {
   /** Roles the modules declare as governed beyond the ones the models name. A live grantee
    *  outside the governed set is exempted from reconciliation and ENUMERATED instead. */
   governedRoles: string[];
+  /**
+   * The roles a request can become (`roles: { request }`, the union across modules). Undefined
+   * when no module declares them: the lifecycle catalog check then runs exactly as before.
+   */
+  requestRoles?: string[];
+  /** Every `owner` a declared derived object names, across modules, sorted. */
+  declaredOwners: string[];
   /**
    * Postgres extensions the modules declare — the bootstrap the state layer needs before
    * anything that uses their types. Only the from-scratch compiler consumed these; the DIFF
@@ -194,6 +201,9 @@ export function composeDeclaredDerived(modules: Module[], modelsPath: string): D
       renamedTables: { ...compileTableRenames(models, {}), ...compileTableMoves(models, {}) },
       models,
       governedRoles: moduleGovernedRoles(modules),
+      requestRoles: moduleRequestRoles(modules),
+      declaredOwners: [...new Set(modules.flatMap((m) => m.derived)
+        .flatMap((d) => ('owner' in d && typeof d.owner === 'string' ? [d.owner] : [])))].sort(),
       extensions: [...new Set(modules.flatMap((m) => m.extensions ?? []))].sort(),
     };
   } catch (err) {

package/src/cli/derived-catchup.ts

@@ -35,7 +35,7 @@ import { MODEL_WIRE_CONTRACT, type ReconcileWirePayload } from '../wire';
 import { resolveConfig, opsFunction } from './config';
 import { invokeAction, lambdaQueryRunner, lambdaSessionRunner } from './aws';
 import { currentGitRef } from './state-apply';
-import { catalogInputsFromModels, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal } from './lifecycle-preflight';
+import { catalogInputsFromModels, lifecycleDeclaredOwnerRefusal, LifecycleFindingsError, lifecyclePostApplyRefusal, lifecycleRolesOf } from './lifecycle-preflight';
 
 /** Where the catch-up runs. The two lanes db:apply itself already has. */
 export type CatchUpVenue =
@@ -83,6 +83,8 @@ export interface CatchUpOptions {
    * Required for the same reason as `onRefusal`: only the caller knows what it wrote.
    */
   stateApplied: boolean;
+  /** Wall time, in ms, of each phase that ran: the owner gate and reconcile, then the post-check. */
+  onPhase?: (phase: 'derived' | 'post-checks', ms: number) => void;
 }
 
 export interface CatchUpOutcome {
@@ -118,10 +120,13 @@ export async function catchUpDerived(
     // The lifecycle catalog check's roles; the reconcile, here or in the ops Lambda, refuses
     // lifecycle-owned objects without them.
     applicationRoles: declared?.models ? catalogInputsFromModels(declared.models).applicationRoles : undefined,
+    // What the modules declare about the roles; optional on the wire (absent = the check as before).
+    ...lifecycleRolesOf(declared),
     actor: process.env.USER ?? null,
     gitRef: currentGitRef(),
   };
 
+  const derivedStarted = Date.now();
   // Before the first derived write, judge the owners the reconcile will give the declared trigger
   // functions on lifecycle tables.
   const config = venue.kind === 'stage' ? await resolveConfig(venue.stage) : undefined;
@@ -130,7 +135,7 @@ export async function catchUpDerived(
   // operator connection, while db:query may run on a reader.
   const operator: SessionRunner = (statements, opts) =>
     (venue.kind === 'direct' ? venue.session : lambdaSessionRunner(config!.region, opsFunction(config!)))(statements, opts);
-  const gate = await lifecycleDeclaredOwnerRefusal(reader, operator, objects, declared?.models ?? [], { stateApplied: opts.stateApplied });
+  const gate = await lifecycleDeclaredOwnerRefusal(reader, operator, objects, declared?.models ?? [], { stateApplied: opts.stateApplied, roles: lifecycleRolesOf(declared) });
   if (gate) throw new LifecycleFindingsError(gate);
 
   let run: ReconcileRun;
@@ -169,11 +174,14 @@ export async function catchUpDerived(
   // A refusal is not a soft outcome here. db:reconcile prints it and exits 1; the catch-up did
   // not land, so db:apply must say so and exit the same way.
   if (run.refusal) throw new CatchUpError(run.refusal);
+  opts.onPhase?.('derived', Date.now() - derivedStarted);
 
   // Verification: the live catalog check again, over what the reconcile just made live. On the
   // operator session, where the commit is: db:query may read a replica that has not caught up.
-  const post = await lifecyclePostApplyRefusal(operator, declared?.models ?? []);
+  const postStarted = Date.now();
+  const post = await lifecyclePostApplyRefusal(operator, declared?.models ?? [], lifecycleRolesOf(declared));
   if (post) throw new LifecycleFindingsError(post);
+  opts.onPhase?.('post-checks', Date.now() - postStarted);
 
   return { declared: objects.length, run, statements: run.applied ? (run.statements ?? []) : [] };
 }

package/src/cli/edge-plan.ts

@@ -53,8 +53,10 @@ import { compileTableRenames, compileTableMoves, compileRenames } from './schema
  * 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.
+ * v7 adds `stateDependents`: declared views and matviews a column type change binds, dropped and
+ * re-created inside the state transaction. A v6 reader would skip them and the ALTER would fail.
  */
-export const PLAN_VERSION = 6;
+export const PLAN_VERSION = 7;
 
 /**
  * The db:apply WIRE CONTRACT between the CLI and the ops Lambda — distinct from PLAN_VERSION,
@@ -119,8 +121,12 @@ export const PLAN_VERSION = 6;
  *
  * 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.
+ *
+ * v11 (milestone upgrade-no-hand-sql): the plan gained `stateDependents`, which the server drops
+ * before the state edge and re-creates after it, in the same transaction, with provenance. A v10
+ * stage would skip them, and its ALTER COLUMN TYPE would fail on the view that binds the column.
  */
-export const APPLY_CONTRACT_VERSION = 10;
+export const APPLY_CONTRACT_VERSION = 11;
 
 /** Classification counts (brick 9, decision 11): destructive = drops + narrowings + strips. */
 export interface PlanClassification {
@@ -167,6 +173,30 @@ export type StatePrerequisite = {
   };
 };
 
+/**
+ * A declared view or matview that binds a column this plan changes the type of. PostgreSQL refuses
+ * `ALTER COLUMN ... TYPE` while it exists, so the state transaction drops it (dependents first),
+ * runs the edge, and re-creates it from the reviewed checkout SQL before COMMIT: it is never absent.
+ * Listed in creation (dependency) order; the drops run in reverse.
+ */
+export type StateDependent = {
+  /** `schema.name`. */
+  identity: string;
+  kind: 'view' | 'materialized view';
+  /** The live definition hash read at mint. db:apply refuses, before any write, unless it still holds. */
+  expectedDefHash: string;
+  /** The exact DROP, without CASCADE: anything the mint did not see that depends on it fails the transaction. */
+  dropSql: string;
+  /** The exact schema preparation, CREATE, ownership, grant, comment and index SQL db:apply runs. */
+  sql: string;
+  /** As StatePrerequisite.searchPath. */
+  searchPath: string | null;
+  grantContract: StatePrerequisite['grantContract'];
+  provenance: { srcHash: string; bodyHash?: string; kind: 'view' | 'materialized view'; dropSql?: string };
+  /** Matview only: pg_total_relation_size at mint. The re-create repopulates it, inside the transaction. */
+  bytes?: number;
+};
+
 export interface EdgePlan {
   v: number;
   /** The target's exact live fingerprint at mint time — the lock. */
@@ -234,6 +264,8 @@ export interface EdgePlan {
    * before this field existed have none; an absent field means no prerequisite was recorded.
    */
   statePrerequisites?: readonly StatePrerequisite[];
+  /** Declared views and matviews the state transaction drops and re-creates around a type change. */
+  stateDependents?: readonly StateDependent[];
   executable: number;
   /** Executable statements that LOSE DATA (drops + narrowing type changes) — red, gated at apply. */
   destructive: number;