@everystack/cli 0.4.105 → 0.4.107

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.107] - 2026-10-31
+
+### Added
+
+- db:plan names db:provision first when a lifecycle plan needs it
+- db:apply prints a wall time per phase
+- a type change under a declared view or matview mints and applies
+
+### Fixed
+
+- the lifecycle preflight accepts the grants the reviewed plan revokes
+- a re-created view's apply errors name it as a view
+- a grant the plan's REVOKE cannot remove stays a lifecycle finding
+- a destroy_log grant from another role names db:provision's REVOKE
+
+## [0.4.106] - 2026-10-31
+
+### Added
+
+- declare request roles with defineModule({ roles: { request } })
+
+### Fixed
+
+- a granted definer role is not a request role in the lifecycle check
+- lifecycle rule 2 judges schema owners and the deploy history tables
+- lifecycle reach counts mixed-option membership chains
+- move the database when an app role owns public through pg_database_owner
+- refuse an empty request-role list on the reconcile wire
+
+### Documentation
+
+- say why a granted owner counts, and document roles.request
+- state what an older server skips under the role declaration
+
 ## [0.4.105] - 2026-10-31
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.105",
+  "version": "0.4.107",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -145,7 +145,7 @@
     "structured-headers": "1.0.1",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
-    "@everystack/model": "0.4.25"
+    "@everystack/model": "0.4.26"
   },
   "peerDependencies": {
     "@everystack/server": ">=0.4.0",
@@ -192,7 +192,7 @@
     "react": "19.2.0",
     "ts-jest": "29.4.9",
     "zod": "3.25.67",
-    "@everystack/server": "0.4.41"
+    "@everystack/server": "0.4.42"
   },
   "scripts": {
     "test": "jest",

package/src/cli/alter-type-dependents.ts

@@ -13,6 +13,16 @@
  */
 
 import type { QueryRunner } from './authz-contract';
+import type { SessionRunner } from './session';
+import type { SourceObject } from './derived-source';
+import type { StateDependent } from './edge-plan';
+import { introspectDerived } from './derived-introspect';
+import { planReconcile } from './derived-plan';
+import {
+  builderOwnerMode, derivedSearchPath, ownerPreflightRefusal, ownerPreflightSql, ownerRequirements,
+  renderEnsureObjectSchemas, renderReconcileSql, type OwnerApplyMode,
+} from './derived-apply';
+import { quoteIdent, quoteQualified } from './pg-ident';
 
 export interface AlterTypeTarget {
   table: string;
@@ -94,3 +104,192 @@ export function renderAlterTypeRefusal(blocked: readonly BlockedAlterType[]): st
     `Route the type change through db:swap (rebuild + atomic rename), or drop and re-create the dependent derived objects around it (db:reconcile) — deliberately, not as an apply-time surprise.`,
   ].join('\n');
 }
+
+// ---------------------------------------------------------------------------
+// Declared dependents: dropped and re-created inside the state transaction.
+// ---------------------------------------------------------------------------
+
+/**
+ * Every view, matview or rule the targets' type changes force out: the ones that bind a target
+ * column, and, transitively, every view or matview whose rule reads one of those (a view on a
+ * view). PostgreSQL cannot drop the first without the second.
+ */
+export function dependentClosureSql(targets: readonly AlterTypeTarget[]): string {
+  const direct = targets.map((t) => {
+    const rel = quoteLiteral(t.table);
+    return `(d.refobjid = ${rel}::regclass AND d.refobjsubid = (SELECT attnum FROM pg_catalog.pg_attribute
+      WHERE attrelid = ${rel}::regclass AND attname = ${quoteLiteral(t.column)}))`;
+  }).join(' OR ');
+  return `WITH RECURSIVE closure(oid) AS (
+  SELECT r.ev_class FROM pg_catalog.pg_depend d JOIN pg_catalog.pg_rewrite r ON r.oid = d.objid
+   WHERE d.classid = 'pg_catalog.pg_rewrite'::regclass AND d.refclassid = 'pg_catalog.pg_class'::regclass
+     AND r.ev_class <> d.refobjid AND (${direct})
+  UNION
+  SELECT r.ev_class FROM closure c JOIN pg_catalog.pg_depend d ON d.refobjid = c.oid
+     AND d.refclassid = 'pg_catalog.pg_class'::regclass AND d.classid = 'pg_catalog.pg_rewrite'::regclass
+    JOIN pg_catalog.pg_rewrite r ON r.oid = d.objid
+   WHERE r.ev_class <> c.oid
+)
+SELECT DISTINCT cl.oid::bigint AS oid,
+  CASE cl.relkind WHEN 'v' THEN 'view' WHEN 'm' THEN 'materialized view' ELSE 'rule' END AS kind,
+  n.nspname::text || '.' || cl.relname::text AS identity,
+  pg_catalog.pg_total_relation_size(cl.oid)::bigint AS bytes
+FROM closure JOIN pg_catalog.pg_class cl ON cl.oid = closure.oid JOIN pg_catalog.pg_namespace n ON n.oid = cl.relnamespace
+ORDER BY 3`;
+}
+
+/**
+ * What else depends on the closure, which a plain DROP would refuse over (a function returning
+ * the view's row type) or remove silently (a trigger on a view). The closure's own rules and
+ * members are not counted: they are dropped and re-created with it.
+ */
+export function closureBlockersSql(oids: readonly number[]): string {
+  const list = `ARRAY[${oids.map((oid) => String(Math.trunc(oid))).join(', ')}]::oid[]`;
+  return `SELECT DISTINCT pg_catalog.pg_describe_object(d.classid, d.objid, d.objsubid) AS what,
+  pg_catalog.pg_describe_object(d.refclassid, d.refobjid, 0) AS on_what
+FROM pg_catalog.pg_depend d
+WHERE ((d.refclassid = 'pg_catalog.pg_class'::regclass AND d.refobjid = ANY(${list}))
+    OR (d.refclassid = 'pg_catalog.pg_type'::regclass AND d.refobjid IN (SELECT reltype FROM pg_catalog.pg_class WHERE oid = ANY(${list}))))
+  AND ((d.deptype = 'n'
+        AND NOT (d.classid = 'pg_catalog.pg_rewrite'::regclass AND (SELECT ev_class FROM pg_catalog.pg_rewrite WHERE oid = d.objid) = ANY(${list}))
+        AND NOT (d.classid = 'pg_catalog.pg_class'::regclass AND d.objid = ANY(${list})))
+    OR d.classid = 'pg_catalog.pg_trigger'::regclass)
+ORDER BY 1`;
+}
+
+/** `1.2 MB`, for the plan's matview line. */
+export function formatBytes(bytes: number): string {
+  const units = ['B', 'kB', 'MB', 'GB', 'TB'];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) { value /= 1024; unit += 1; }
+  return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+}
+
+/** The plan's line for one dependent. */
+export function renderStateDependentLine(d: Pick<StateDependent, 'identity' | 'kind' | 'bytes'>): string {
+  const cost = d.kind === 'materialized view' ? ` (repopulates ${formatBytes(d.bytes ?? 0)})` : '';
+  return `~ ${d.kind} ${d.identity}: dropped before the type change and re-created from the checkout in the same transaction${cost}`;
+}
+
+export type StateDependentsMint = { dependents: StateDependent[] } | { refusal: string };
+
+/**
+ * The declared views and matviews the targets' type changes force out, rendered for the state
+ * transaction, or a refusal naming what the platform cannot re-create:
+ *
+ *   - a dependent the models do not declare (nothing can re-create it from the checkout):
+ *     declare it in the models, which db:pull renders;
+ *   - a declared one whose live definition the reconciler cannot vouch for (drift, or never
+ *     reconciled): db:reconcile has the verb for each;
+ *   - something else depending on the closure (a function over a view's row type, a trigger on a
+ *     view), which a plain DROP would refuse over or silently remove.
+ *
+ * Read-only. Each create is the SQL a derived apply renders for that object.
+ */
+export async function mintStateDependents(
+  runner: QueryRunner,
+  session: SessionRunner,
+  targets: readonly AlterTypeTarget[],
+  declared: readonly SourceObject[],
+): Promise<StateDependentsMint> {
+  if (targets.length === 0) return { dependents: [] };
+  const rows = await runner(dependentClosureSql(targets));
+  if (rows.length === 0) return { dependents: [] };
+  const byIdentity = new Map(declared.map((o) => [o.identity, o]));
+  const where = targets.map((t) => `${t.table}."${t.column}"`).join(', ');
+  const undeclared = rows.filter((r: any) => r.kind === 'rule' || byIdentity.get(String(r.identity))?.kind !== r.kind);
+  if (undeclared.length > 0) {
+    return {
+      refusal: `This plan changes the type of ${where}, and PostgreSQL refuses that while a view or rule binds the column. `
+        + 'db:apply drops and re-creates the declared ones in the same transaction, but these are not declared, so nothing can re-create them:\n'
+        + undeclared.map((r: any) => `  ${r.kind} ${r.identity} is not declared`).join('\n')
+        + '\nFix: declare it in the models (db:pull renders it), then re-run db:plan.',
+    };
+  }
+  const blockers = await runner(closureBlockersSql(rows.map((r: any) => Number(r.oid))));
+  if (blockers.length > 0) {
+    return {
+      refusal: `This plan changes the type of ${where}. db:apply would drop and re-create ${rows.map((r: any) => `${r.kind} ${r.identity}`).join(', ')} around it, `
+        + 'but other objects depend on them, and a plain DROP would refuse over them or remove them:\n'
+        + blockers.map((b: any) => `  ${b.what} depends on ${b.on_what}`).join('\n')
+        + '\nRoute this type change through db:swap, or change the models so nothing else depends on these views first.',
+    };
+  }
+
+  // Creation order is the declared layer's dependency order; the drops run in reverse.
+  const order = new Map(declared.map((o, i) => [o.identity, i]));
+  const closure = rows
+    .map((r: any) => ({ identity: String(r.identity), kind: r.kind as StateDependent['kind'], bytes: Number(r.bytes) }))
+    .sort((a, b) => order.get(a.identity)! - order.get(b.identity)!);
+  const ids = new Set(closure.map((c) => c.identity));
+
+  const live = await introspectDerived(session);
+  const parsed = { objects: [...declared], warnings: [] as string[] };
+  // The reconciler's own verdict first: a hand-edited or never-reconciled view is not ours to
+  // re-create silently, and db:reconcile already has the verb for each.
+  const verdict = planReconcile(parsed, live, { only: [...ids] });
+  const drifted = verdict.drift.filter((d) => ids.has(d.identity)).map((d) => d.identity);
+  const unbaselined = verdict.needsBaseline.filter((id) => ids.has(id));
+  if (drifted.length + unbaselined.length > 0) {
+    return {
+      refusal: `This plan changes the type of ${where}, which db:apply handles by re-creating the declared views and matviews that bind it, `
+        + 'but the reconciler cannot vouch for some of them:\n'
+        + [...drifted.map((id) => `  ${id} differs from its record (hand-edited). Fix: db:reconcile --apply --overwrite-drift, or declare the live definition.`),
+          ...unbaselined.map((id) => `  ${id} was never reconciled. Fix: db:reconcile --baseline once you have verified it matches the models.`)].join('\n')
+        + '\nThen re-run db:plan.',
+    };
+  }
+
+  const liveById = new Map(live.objects.map((o) => [o.identity, o]));
+  // Rendered as the creates a derived apply would run against the catalog as it is after the
+  // drops: the closure absent.
+  const absent = {
+    ...live,
+    objects: live.objects.filter((o) => !ids.has(o.identity)),
+    edges: live.edges.filter((e) => !ids.has(e.dependent) && !ids.has(e.referenced)),
+  };
+  const combined = planReconcile(parsed, absent, { only: [...ids] });
+  const requirements = ownerRequirements(combined, parsed.objects);
+  let ownerMode: OwnerApplyMode = 'set-role';
+  if (requirements.length > 0) {
+    const preflight = await runner(ownerPreflightSql(requirements));
+    const refusal = ownerPreflightRefusal(preflight as any[]);
+    if (refusal) return { refusal: `could not plan the re-create of the views a type change binds: ${refusal}` };
+    ownerMode = builderOwnerMode(preflight as any[]);
+  }
+  const schemas = derivedSearchPath([...declared]);
+  const searchPath = schemas.length === 1 && schemas[0] === 'public' ? null : schemas.map(quoteIdent).join(', ');
+
+  return {
+    dependents: closure.map((c) => {
+      const source = byIdentity.get(c.identity)!;
+      const rendered = renderReconcileSql(planReconcile(parsed, absent, { only: [c.identity] }), parsed.objects, ownerMode);
+      if (rendered.record.length !== 1 || rendered.record[0] !== c.identity) {
+        throw new Error(`could not render the re-create of ${c.identity}: the target changed while minting; re-run db:plan.`);
+      }
+      const drop = `DROP ${c.kind === 'view' ? 'VIEW' : 'MATERIALIZED VIEW'} ${quoteQualified(c.identity)}`;
+      const owner = ownerMode === 'set-role' ? source.owner : undefined;
+      return {
+        identity: c.identity,
+        kind: c.kind,
+        expectedDefHash: liveById.get(c.identity)!.defHash,
+        dropSql: owner ? [`SET ROLE ${owner}`, drop, 'RESET ROLE'].join('\n;\n') : drop,
+        sql: [...renderEnsureObjectSchemas([source]), ...rendered.statements].join('\n;\n'),
+        searchPath,
+        grantContract: {
+          attachments: source.attachments.filter((a) => a.kind === 'grant'),
+          ...(source.owner ? { owner: source.owner } : {}),
+          ownerMode,
+        },
+        provenance: {
+          srcHash: source.hash,
+          ...(source.bodyHash ? { bodyHash: source.bodyHash } : {}),
+          kind: c.kind,
+          ...(source.drop ? { dropSql: source.drop } : {}),
+        },
+        ...(c.kind === 'materialized view' ? { bytes: c.bytes } : {}),
+      };
+    }),
+  };
+}

package/src/cli/apply-execute.ts

@@ -189,6 +189,12 @@ export interface ApplyPlanResult {
   liveFingerprint: string;
   reason?: string;
   logId?: number;
+  /**
+   * Wall time, in ms, of the two phases this function runs, on the statuses that reached the
+   * state transaction: everything before it (the lock, the gates, descent; `verifyMs`), and the
+   * transaction plus the landed-fingerprint read (`stateMs`). Optional on the wire.
+   */
+  phases?: { verifyMs: number; stateMs: number };
   /**
    * The keys the row check found orphans on, if any — data, for the caller's advisory (see
    * fk-orphan-advisory). Present on the paths that got as far as running the check, empty
@@ -465,6 +471,7 @@ export async function executeApplyPlan(
   plan: EdgePlan,
   options: ApplyPlanOptions = {},
 ): Promise<ApplyPlanResult> {
+  const started = Date.now();
   const { hash: live, snapshot: before, contract: beforeAuthz, ledger, ledgerRead } = await liveBaseAndLedger(session);
 
   // The endpoint is FULL (it carries the ungoverned live authz through), so it is compared against
@@ -596,16 +603,23 @@ 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.stateDependents?.length) {
+    const reason = `this plan re-creates ${plan.stateDependents.map((d) => `${d.kind} ${d.identity}`).join(', ')} around a column type change, but --state-only skips derived writes. Apply the reviewed plan without --state-only.`;
+    await recordRefusal(runner, plan, live, 'state dependents', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
   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 };
   }
 
+  const stateStarted = Date.now();
   let result: StateApplyResult;
   try {
     result = await applyGeneratedStatements(runner, toRun, {
       statePrerequisites: plan.statePrerequisites,
+      stateDependents: plan.stateDependents,
       transaction: options.transaction,
       ...(withheld.length > 0 ? { skippedValidations: withheld } : {}),
       actor: options.actor,
@@ -630,6 +644,7 @@ export async function executeApplyPlan(
   }
 
   const { hash: landed } = await liveBaseFingerprint(session);
+  const phases = { verifyMs: stateStarted - started, stateMs: Date.now() - stateStarted };
   if (result.logId !== undefined) {
     // The log stamps the RAW landed hash — the same flavor as `from` AND as the full `to`, so the
     // schema_log chain reads as one consistent series of live states.
@@ -645,6 +660,7 @@ export async function executeApplyPlan(
     return {
       status: 'validation-pending',
       liveFingerprint: landed,
+      phases,
       // The next move follows the CAUSE: bad rows are a data fix, a check that was cut off by a
       // clock is a lane change. See validationPendingReason.
       reason: validationPendingReason(result.pendingValidations),
@@ -660,6 +676,7 @@ export async function executeApplyPlan(
     return {
       status: 'verify-failed',
       liveFingerprint: landed,
+      phases,
       reason: `applied, but the target landed on ${landed.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
       ...(result.logId !== undefined ? { logId: result.logId } : {}),
       fkOrphans: orphans,
@@ -668,6 +685,7 @@ export async function executeApplyPlan(
   return {
     status: 'applied',
     liveFingerprint: landed,
+    phases,
     ...(result.logId !== undefined ? { logId: result.logId } : {}),
     fkOrphans: orphans,
   };

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

@@ -77,7 +77,7 @@ import { readStageStateTwice } from '../stage-read-consistency';
 import { renderApplyReceipt, renderCatchUpFailure } from '../plain-output';
 import { renderFkOrphanAdvisory, ownershipColumns } from '../fk-orphan-advisory';
 import { catchUpDerived, type CatchUpVenue } from '../derived-catchup';
-import { lifecycleApplyRefusal, lifecycleStateOnlyRefusal, LifecycleFindingsError } from '../lifecycle-preflight';
+import { lifecycleApplyRefusal, lifecycleRolesOf, lifecycleStateOnlyRefusal, LifecycleFindingsError, unclassifiedGranteesWarning } from '../lifecycle-preflight';
 import { buildReconcileReport } from './db-reconcile';
 import { step, success, fail, info, warn, line as printLine } from '../output';
 
@@ -238,6 +238,30 @@ export function catchUpRerunCommand(flags: Record<string, string>): string {
   return parts.join(' ');
 }
 
+/** Wall time, in ms, of each db:apply phase that ran. */
+export interface ApplyPhaseTimings {
+  verify?: number;
+  state?: number;
+  derived?: number;
+  postChecks?: number;
+}
+
+/**
+ * One line: the wall time of each phase that ran, in order, or null when none did. Printed beside
+ * the receipt, never inside it, so the receipt's contract is unchanged.
+ */
+export function renderPhaseTimings(phases: ApplyPhaseTimings): string | null {
+  const named: Array<[string, number | undefined]> = [
+    ['descent and fingerprint verify', phases.verify],
+    ['state transaction', phases.state],
+    ['derived catch-up', phases.derived],
+    ['post-checks', phases.postChecks],
+  ];
+  const ran = named.filter((entry): entry is [string, number] => entry[1] !== undefined);
+  if (ran.length === 0) return null;
+  return `phases: ${ran.map(([name, ms]) => `${name} ${(ms / 1000).toFixed(2)}s`).join(', ')}`;
+}
+
 /** What the catch-up did, or what to say about the fact that it did not. */
 type CatchUpReport = { ok: true; statements: string[] } | { ok: false; lines: string[] };
 
@@ -261,10 +285,12 @@ async function runCatchUp(
   applied: number,
   onRefusal: 'exit' | 'throw',
   declared?: Awaited<ReturnType<typeof loadDeclaredDerived>>,
+  phases?: ApplyPhaseTimings,
 ): Promise<CatchUpReport> {
   const verbose = flags.verbose === 'true';
   try {
     const outcome = await catchUpDerived(venue, {
+      ...(phases ? { onPhase: (phase: 'derived' | 'post-checks', ms: number) => { phases[phase === 'derived' ? 'derived' : 'postChecks'] = ms; } } : {}),
       ...(declared !== undefined ? { declared } : {}),
       ...(flags.models ? { models: flags.models } : {}),
       onStart: () => step('Catching the functions, views and triggers up to the checkout...'),
@@ -336,6 +362,7 @@ async function catchUpAfterApply(
   venue: CatchUpVenue,
   flags: Record<string, string>,
   declared?: Awaited<ReturnType<typeof loadDeclaredDerived>>,
+  phases?: ApplyPhaseTimings,
 ): Promise<CatchUpReport> {
   if (!LANDED.has(result.status)) return { ok: true, statements: [] };
   if (flags['state-only'] === 'true') return { ok: true, statements: [] };
@@ -345,7 +372,7 @@ async function catchUpAfterApply(
   const applied = result.status === 'already-applied'
     ? 0
     : classifyGeneratedStatements((plan.statements ?? []).filter((s) => !unapplied.has(s))).executable.length;
-  return runCatchUp(venue, flags, applied, 'throw', declared);
+  return runCatchUp(venue, flags, applied, 'throw', declared, phases);
 }
 
 /**
@@ -519,7 +546,11 @@ async function applyPlanViaStage(
   const { region } = config;
   const fn = opsFunction(config);
   const declared = await loadDeclaredDerived(flags.models);
-  const lifecycleRefusal = await lifecycleApplyRefusal(lambdaQueryRunner(region, fn), declared?.models ?? [])
+  const unclassified = unclassifiedGranteesWarning(declared?.models ?? [], lifecycleRolesOf(declared));
+  if (unclassified) warn(unclassified);
+  // The plan's own REVOKEs resolve the grant findings they remove: the state transaction runs them
+  // before the catch-up creates any lifecycle function, and the post-check reads the catalog after.
+  const lifecycleRefusal = await lifecycleApplyRefusal(lambdaQueryRunner(region, fn), declared?.models ?? [], lifecycleRolesOf(declared), plan.statements)
     ?? (flags['state-only'] === 'true' ? await lifecycleStateOnlyRefusal(lambdaQueryRunner(region, fn), declared?.models ?? []) : null);
   if (lifecycleRefusal) {
     fail(lifecycleRefusal);
@@ -535,6 +566,10 @@ async function applyPlanViaStage(
   // answered by two containers at two moments. Read the stage twice and refuse a
   // disagreement — the apply never starts. Deliberately OUTSIDE the try below: this
   // refusal must exit as itself, not as "Apply failed".
+  // Wall times as this CLI sees them: the reads, descent and authority before the write; the write
+  // invoke (the ops Lambda's own lock, gates and transaction); then the catch-up's two halves.
+  const phases: ApplyPhaseTimings = {};
+  const verifyStarted = Date.now();
   step('Reading the stage TWICE (state and authz are separate ops-Lambda invokes)...');
   const readSession = lambdaSessionRunner(region, fn);
   const readPair = await readStageStateTwice(readSession).catch((err: any) => {
@@ -626,6 +661,8 @@ async function applyPlanViaStage(
     }
 
     step('Applying in the ops Lambda (credential-free — the operator never holds a database URL)...');
+    const stateStarted = Date.now();
+    phases.verify = stateStarted - verifyStarted;
     const result: any = await invokeAction(region, fn, 'db:apply', {
       plan,
       // q1-contract-version direction A: the server refuses on exact mismatch, so a payload-key or
@@ -641,6 +678,7 @@ async function applyPlanViaStage(
       ...(flags['snapshot-ref'] ? { snapshotRef: flags['snapshot-ref'] } : {}),
       stage: flags.stage,
     });
+    phases.state = Date.now() - stateStarted;
     if (result?.error) {
       fail(`Apply failed: ${result.error}`);
       process.exit(1);
@@ -668,8 +706,10 @@ async function applyPlanViaStage(
   }
 
   // Then the functions, views and triggers — on the same stage, credential-free, always.
-  const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags, declared);
+  const catchUp = await catchUpAfterApply(landedResult!, plan, { kind: 'stage', stage: flags.stage }, flags, declared, phases);
   exitOnCatchUpFailure(catchUp);
+  const timings = LANDED.has(landedResult!.status) ? renderPhaseTimings(phases) : null;
+  if (timings) info(timings);
   const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
   const advisoryModels = await modelsForAdvisory(landedResult!, flags);
   reportApplyResult(landedResult!, plan, {
@@ -956,7 +996,10 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   const declaredDb = (): ReturnType<typeof loadDeclaredDerived> =>
     declaredDbPromise ??= loadDeclaredDerived(flags.models);
   // Read-only, before the rollback point: a refused apply must not first take a snapshot, backup or dump.
-  const lifecycleRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? [])
+  const unclassified = unclassifiedGranteesWarning((await declaredDb())?.models ?? [], lifecycleRolesOf(await declaredDb()));
+  if (unclassified) warn(unclassified);
+  // As on the stage lane: a finding this plan's own REVOKE removes is not a refusal.
+  const lifecycleRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? [], lifecycleRolesOf(await declaredDb()), plan.statements)
     ?? (flags['state-only'] === 'true' ? await lifecycleStateOnlyRefusal(runner, (await declaredDb())?.models ?? []) : null);
   if (lifecycleRefusal) {
     fail(lifecycleRefusal);
@@ -1083,6 +1126,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
 
   let landed: ApplyPlanResult | undefined;
   let catchUp: CatchUpReport = { ok: true, statements: [] };
+  const phases: ApplyPhaseTimings = {};
   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` : ''})`);
@@ -1113,7 +1157,7 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
       { verb: 'db:apply', actor: process.env.USER ?? 'unknown' },
       async () => {
         // Re-checked under the lease, where the writes happen.
-        const leasedRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? []);
+        const leasedRefusal = await lifecycleApplyRefusal(runner, (await declaredDb())?.models ?? [], lifecycleRolesOf(await declaredDb()), plan.statements);
         if (leasedRefusal) {
           fail(leasedRefusal);
           process.exit(1);
@@ -1175,7 +1219,8 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
         // they read, and no second operator can slip in between the two halves. Its failure
         // is carried out as a report, never thrown: the plan landed, and "rolled back" would
         // be a lie.
-        const report = await catchUpAfterApply(result, plan, { kind: 'direct', runner, session }, flags);
+        if (result.phases) Object.assign(phases, { verify: result.phases.verifyMs, state: result.phases.stateMs });
+        const report = await catchUpAfterApply(result, plan, { kind: 'direct', runner, session }, flags, undefined, phases);
         return { result, catchUp: report };
       },
     );
@@ -1195,6 +1240,8 @@ export async function dbApplyCommand(flags: Record<string, string>): Promise<voi
   }
 
   exitOnCatchUpFailure(catchUp);
+  const timings = LANDED.has(landed!.status) ? renderPhaseTimings(phases) : null;
+  if (timings) info(timings);
   const declaredGrantees = await declaredGranteesForReceipt(plan, flags);
   const advisoryModels = await modelsForAdvisory(landed!, flags);
   reportApplyResult(landed!, plan, {

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

@@ -41,6 +41,7 @@ import { resolveDbSource, type DbSource } from '../db-source';
 import { resolveModelsPath } from '../models-path';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived';
 import { loadModels } from './db-generate';
+import { lifecycleRolesOf } from '../lifecycle-preflight';
 import { step, success, fail, info, warn } from '../output';
 
 function requireUrl(flags: Record<string, string>, verb: string): string {
@@ -134,6 +135,7 @@ export async function dbTemplateRefreshCommand(flags: Record<string, string>): P
     const result = await executeTemplateRefresh(url, models, {
       declared: declaredDb?.objects,
       sequences: declaredDb?.sequences,
+      lifecycleRoles: lifecycleRolesOf(declaredDb),
       actor: process.env.USER ?? null,
       gitRef: currentGitRef(),
       seed: seedCommand === null ? null : (templateUrl) => {

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

@@ -26,7 +26,7 @@
 
 import type { ModelDescriptor } from '@everystack/model';
 import { buildIntoDatabase } from '../db-build';
-import { LifecycleFindingsError } from '../lifecycle-preflight';
+import { LifecycleFindingsError, lifecycleRolesOf } from '../lifecycle-preflight';
 import { createUrlRunner } from '../db-source';
 import { resolveModelsPath } from '../models-path';
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived';
@@ -124,6 +124,7 @@ export async function dbBuildCommand(flags: Record<string, string>): Promise<voi
       declared: declaredDb?.objects,
       sequences: declaredDb?.sequences,
       extensions: declaredDb?.extensions,
+      lifecycleRoles: lifecycleRolesOf(declaredDb),
       actor: process.env.USER ?? null,
       gitRef: currentGitRef(),
     });

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

@@ -44,6 +44,7 @@ import { findUnexportedModels, scanModelDirectory, type ModelFileScan } from '..
 import { loadDeclaredDerived, retiredSqlDirAnywhere, retiredSqlDirFlagRefusal, type DeclaredDerived } from '../declared-derived';
 import type { SequenceDescriptor } from '@everystack/model';
 import type { SourceObject } from '../derived-source';
+import { lifecycleRolesOf, unclassifiedGranteesWarning, type LifecycleRoleDeclaration } from '../lifecycle-preflight';
 import { findReadAuthzGaps, findNakedGrants } from '../authz-lint';
 import { findSelectGrantGaps } from '../select-grant-advisory';
 import { parseBaseline, renderBaseline, BASELINE_FILE } from '../authz-baseline';
@@ -125,6 +126,8 @@ export interface StaticCheckInput {
    * Absent (undefined) = the caller did not read it (older callers): no map finding at all.
    */
   modelMapSource?: string | null;
+  /** The modules' role declaration (lifecycleRolesOf). Its unclassified grantees are a warning. */
+  lifecycleRoles?: LifecycleRoleDeclaration;
 }
 
 export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
@@ -285,6 +288,11 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     }
   }
 
+  // A grantee the role declaration leaves unclassified counts as a request role in the lifecycle
+  // catalog check. Visible, never fatal: classifying it is the operator's call.
+  const unclassified = unclassifiedGranteesWarning(input.models, input.lifecycleRoles ?? {});
+  if (unclassified) findings.push({ level: 'warn', area: 'authz', message: unclassified });
+
   if (input.artifactSource === null && input.artifactOrigin === 'flag') {
     findings.push({
       level: 'fail',
@@ -369,7 +377,7 @@ export interface EphemeralComposeResult {
 export async function executeEphemeralCompose(
   adminUrl: string,
   models: ModelDescriptor[],
-  opts: { actor?: string | null; gitRef?: string | null; declared?: SourceObject[]; sequences?: SequenceDescriptor[]; extensions?: string[] } = {},
+  opts: { actor?: string | null; gitRef?: string | null; declared?: SourceObject[]; sequences?: SequenceDescriptor[]; extensions?: string[]; lifecycleRoles?: LifecycleRoleDeclaration } = {},
 ): Promise<EphemeralComposeResult> {
   const database = `escheck_${process.pid}_${Date.now()}`;
   await createDatabase(adminUrl, database);
@@ -378,6 +386,7 @@ export async function executeEphemeralCompose(
       declared: opts.declared,
       sequences: opts.sequences,
       extensions: opts.extensions,
+      lifecycleRoles: opts.lifecycleRoles,
       actor: opts.actor ?? 'db:check',
       gitRef: opts.gitRef ?? null,
     });
@@ -478,6 +487,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
     moduleModels: declaredDb?.models ?? null,
     baselineSource,
     modelMapPath: mapPath, modelMapSource,
+    lifecycleRoles: lifecycleRolesOf(declaredDb),
   });
   // Per-finding detail is the --verbose report. The quiet default answers the one question a
   // human asked — is anything pending? — and names the verb that shows it.
@@ -504,6 +514,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
         declared: declaredDb?.objects,
         sequences: declaredDb?.sequences,
         extensions,
+        lifecycleRoles: lifecycleRolesOf(declaredDb),
       });
       if (verbose) for (const line of ephemeral.report) info(`  ${line}`);
     } catch (err: any) {