@everystack/cli 0.4.78 → 0.4.80

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.80] - 2026-09-07
+
+### BREAKING CHANGES
+
+- apply-contract v3 — the default-privilege lock is a server-run gate; redeploy the stage before the first staged db:apply after upgrading
+
+### Added
+
+- empty-edge summary names the ungoverned grantees, not 35 tables
+- carryUngovernedAuthz — the full-prediction merge helper (N3 step 1)
+- predictLiveState carryUngoverned — the full endpoint flavor (N3 step 2)
+- the plan `to` is the full endpoint, verified and disclosed (N3 steps 3-5)
+- a plan-created serial sequence is granted in the same plan
+- the plan locks the default-privilege posture it predicted from
+
+### Fixed
+
+- the full endpoint carries default privileges onto plan-created objects
+- bump apply-contract to v2 for the full endpoint; sharpen the empty-edge summary
+- db:check fails on a named artifact path with nothing at it
+
+### Documentation
+
+- the plan `to` flavor; test: condition (a) drop end-to-end (N3 step 6)
+- every db verb has a reference entry, and a test says so
+- the disclosed gap names what actually compiles, and a test pins it
+- the last two rollback-point sentences say what the code does; the retargeting edge is named
+
+## [0.4.79] - 2026-09-07
+
+### Removed
+
+- remove db:adopt — its proof was "would db:plan be empty", and db:plan answers that on the review surface
+
+### Added
+
+- db:pull ends with the on-ramp runbook; docs and help say the on-ramp is pull, commit, plan
+
+### Fixed
+
+- closing-gate round 1 — the as-is lane runs the shipped db:pull, the runbook is gated on --abilities live, the fixture proves live derivation, live-models.ts is gone
+
 ## [0.4.78] - 2026-09-07
 
 ### Fixed
@@ -941,6 +983,13 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ## [0.2.37] - 2026-06-17
 
+### Removed
+
+- remove onMutation callback — events replaces it
+- remove unused @everystack/jobs devDependency
+- remove secret auto-injection, skip SSR check for web-only updates
+- remove media asset pruning from update command
+
 ### Added
 
 - rename @everystack/updates → @everystack/cli, add db:migrate/db:seed, remove AdminSecret
@@ -992,7 +1041,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ### Fixed
 
 - normalize cache:purge --path to strip query params and ensure leading slash
-- remove unused @everystack/jobs devDependency
 - include updateId in register-web payload
 - psql Lambda-only queries, composite key notify, logging defaults
 - add AWS KVS + SigV4a as direct dependencies
@@ -1011,14 +1059,12 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 - drop GetFunctionConfiguration from log group resolution
 - detect export completion to prevent static pre-rendering hang
 - rewrite secrets for SST Ion, filter EXPO_PUBLIC_* only
-- remove secret auto-injection, skip SSR check for web-only updates
 - clear Metro transform cache on export
 - worker function discovery and log group resolution for SQS subscribers
 - replace infrastructure headers with single X-Server-Debug timestamp
 - version bumps and publish fixes for cli, server, jobs
 - invalidate stale config cache on schema change
 - fall back to outputs.json for custom-named media buckets
-- remove media asset pruning from update command
 - media-sync test uses same minimatch interop as source
 - discover the Router distribution by domain and SST tags
 - use minimatch's named export — the package ships types now
@@ -1027,7 +1073,6 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Changed
 
-- remove onMutation callback — events replaces it
 - migrate all package schemas to everyschema canonical tables
 - lazy-load AWS SDK imports for faster CLI startup
 - drop type module from all packages, switch Jest to CJS mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.78",
+  "version": "0.4.80",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/apply-execute.ts

@@ -38,7 +38,7 @@ import {
   COLUMN_GRANTS_SQL,
   EFFECTIVE_PRIVILEGES_SQL,
   SCHEMA_ACL_SQL,
-  SEQUENCE_ACLS_SQL,
+  SEQUENCE_ACLS_SQL, DEFAULT_ACL_SQL,
   type QueryRunner,
   type AuthzContract,
 } from './authz-contract';
@@ -56,10 +56,9 @@ import {
 } from './schema-introspect';
 import { FUNCTIONS_SQL, contractFunctionRow } from './security-catalog';
 import { fingerprintLive, FINGERPRINT_VERSION } from './schema-fingerprint';
-import { governedLiveFingerprint } from './edge-plan';
 import { applyGeneratedStatements } from './state-apply';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
-import { checkPlanPrecondition, planHash, type EdgePlan } from './edge-plan';
+import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
 import type { DescentLedgerRow } from './git-descent';
 
 /**
@@ -255,6 +254,9 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
     [
       COLUMNS_SQL, CONSTRAINTS_SQL, ENUMS_SQL, INDEXES_SQL, SEQUENCES_SQL, EXTENSIONS_SQL,
       RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, EFFECTIVE_PRIVILEGES_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, FUNCTIONS_SQL,
+      // The default-privilege posture the plan's `defaultAclHash` is checked against — read in
+      // the SAME session as the lock's state, so the two gates describe one instant.
+      DEFAULT_ACL_SQL,
       { sql: SCHEMA_LOG_WITNESS_SQL, allowFailure: true },
     ],
     INTROSPECTION_SESSION,
@@ -270,8 +272,9 @@ export async function liveBaseAndLedger(session: SessionRunner): Promise<LiveBas
     columnGrants: results[9] as any[], effectivePrivileges: results[10] as any[],
     schemaAcls: results[11] as any[], sequenceAcls: results[12] as any[],
     functions: (results[13] as any[]).map(contractFunctionRow),
+    defaultAcls: results[14] as any[],
   });
-  const ledger = mapLedgerRows(rowsOrEmpty(results[14]));
+  const ledger = mapLedgerRows(rowsOrEmpty(results[15]));
   return { hash: fingerprintLive(snapshot, contract).hash, snapshot, contract, ledger };
 }
 
@@ -284,15 +287,17 @@ export async function executeApplyPlan(
 ): Promise<ApplyPlanResult> {
   const { hash: live, snapshot: before, contract: beforeAuthz, ledger } = await liveBaseAndLedger(session);
 
-  // Two flavors, matched to what each check compares (see EdgePlan): the RAW
-  // hash for live-vs-live (the lock, the backup chain), the GOVERNED hash for
-  // declared-vs-live (already-applied here, verify-after below) — computed with
-  // the exact set the mint stamped on the plan. A plan minted before the field
-  // existed verifies raw, as it was minted.
-  const governed = plan.governedRoles ? new Set(plan.governedRoles) : undefined;
-  const governedLive = governed ? governedLiveFingerprint(before, beforeAuthz, governed) : live;
+  // The endpoint is FULL (it carries the ungoverned live authz through), so it is compared against
+  // the RAW live hash directly — the same flavor as `from`. A plan without that flavor predates
+  // the full endpoint (N3, milestone plan-endpoint-full): its `to` is a governed hash, and
+  // verifying the full live against it would false-fail AFTER the DDL landed. Refuse and re-mint.
+  if (plan.toFlavor !== 'full') {
+    const reason = 'this plan predates the full endpoint — its `to` is a governed fingerprint. Re-mint with db:plan.';
+    await recordRefusal(runner, plan, live, 'plan flavor', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
 
-  if (governedLive === plan.toFingerprint) {
+  if (live === plan.toFingerprint) {
     return { status: 'already-applied', liveFingerprint: live };
   }
   const pre = checkPlanPrecondition(plan, live);
@@ -301,6 +306,24 @@ export async function executeApplyPlan(
     return { status: 'refused', liveFingerprint: live, reason: pre.reason };
   }
 
+  // The lock covers object state. The default-privilege posture is not object state — `from`
+  // never hashed it — yet the FULL prediction consumed it for every object this plan creates.
+  // Compare it BEFORE any write: an ALTER DEFAULT PRIVILEGES since minting used to pass the
+  // lock, land the DDL, and fail verify-after post-DDL. A plan without the field predates the
+  // gate and cannot be checked; plans are minutes old, so refusing costs one re-mint.
+  if (plan.defaultAclHash === undefined) {
+    const reason = 'this plan predates the default privileges lock — it carries no defaultAclHash. Re-mint with db:plan.';
+    await recordRefusal(runner, plan, live, 'default privileges', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
+  if (defaultAclHash(beforeAuthz) !== plan.defaultAclHash) {
+    const reason =
+      'the default-privilege posture (ALTER DEFAULT PRIVILEGES) moved since minting — the plan predicted its endpoint ' +
+      'from the old one, so the objects it creates would land with grants it did not carry. Re-mint with db:plan.';
+    await recordRefusal(runner, plan, live, 'default privileges', reason, options);
+    return { status: 'refused', liveFingerprint: live, reason };
+  }
+
   if (options.checkDescent) {
     const descent = await options.checkDescent({ snapshot: before, contract: beforeAuthz, fingerprint: live, ledger });
     if (!descent.ok) {
@@ -347,19 +370,19 @@ export async function executeApplyPlan(
     ...(options.descentNote ? { descentNote: options.descentNote } : {}),
   });
 
-  const { hash: landed, snapshot: after, contract: afterAuthz } = await liveBaseFingerprint(session);
+  const { hash: landed } = await liveBaseFingerprint(session);
   if (result.logId !== undefined) {
-    // The log stamps the RAW landed hash — the same flavor as `from`, so the
+    // 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.
     await runner(renderSchemaLogFingerprintUpdate(result.logId, landed));
   }
 
-  const governedLanded = governed ? governedLiveFingerprint(after, afterAuthz, governed) : landed;
-  if (governedLanded !== plan.toFingerprint) {
+  // The full `to` equals the post-apply raw live hash, so verify-after compares them directly.
+  if (landed !== plan.toFingerprint) {
     return {
       status: 'verify-failed',
       liveFingerprint: landed,
-      reason: `applied, but the target landed on ${governedLanded.slice(0, 12)} — the plan predicted ${plan.toFingerprint.slice(0, 12)}. Investigate before touching this database again (db:fingerprint, db:generate).`,
+      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 } : {}),
     };
   }

package/src/cli/authz-contract.ts

@@ -357,6 +357,15 @@ export interface AuthzContract {
    * it did not read.
    */
   sequenceGrants?: SequenceGrantContract[];
+  /**
+   * Default privileges (`pg_default_acl`) that fire for objects the current role CREATES —
+   * `{ tables, sequences }`, each schema (`''` = all schemas) → grantee → sorted privileges. The
+   * FULL prediction folds the ungoverned slice onto plan-created objects: Postgres auto-grants
+   * them at creation, so a `to` endpoint without them false-verify-fails a successful CREATE
+   * apply on a brownfield BI stage. Absent means NOT MEASURED (older recorder, hand-built
+   * fixture) — the prediction then models no default ACL, as before.
+   */
+  defaultAcls?: { tables: DefaultAclScope; sequences: DefaultAclScope };
 }
 
 /**
@@ -682,6 +691,59 @@ export function assembleSequenceGrants(rows: readonly SequenceAclRow[]): Sequenc
   return [...bySequence.values()].sort((a, b) => a.sequence.localeCompare(b.sequence));
 }
 
+/**
+ * The default privileges (`ALTER DEFAULT PRIVILEGES`) that fire for TABLES and SEQUENCES the
+ * CURRENT role creates — so the prediction can model what a plan-CREATED object will carry.
+ *
+ * `pg_default_acl` is keyed by (defaclrole, defaclnamespace, defaclobjtype). An object created by
+ * role R in schema S receives the ACL for (R, S) AND for (R, all-schemas). We read the current
+ * role's rows only: everystack applies as one operator, so the creator IS the introspector. A
+ * NULL `defaclnamespace` means "every schema" — reported as an empty schema string so the
+ * resolver can union it with any specific schema. Objtype 'r' is a table, 'S' a sequence.
+ */
+export const DEFAULT_ACL_SQL = `
+SELECT
+  COALESCE(n.nspname, '') AS schema,
+  d.defaclobjtype AS objtype,
+  COALESCE(r.rolname, 'PUBLIC') AS grantee,
+  a.privilege_type AS privilege
+FROM pg_default_acl d
+LEFT JOIN pg_namespace n ON n.oid = d.defaclnamespace
+CROSS JOIN LATERAL aclexplode(d.defaclacl) a
+LEFT JOIN pg_roles r ON r.oid = a.grantee
+WHERE d.defaclrole = (SELECT oid FROM pg_roles WHERE rolname = current_user)
+  AND d.defaclobjtype IN ('r', 'S')
+  AND (n.nspname IS NULL OR (n.nspname NOT IN ('pg_catalog', 'information_schema') AND n.nspname NOT LIKE 'pg_%'))
+ORDER BY 1, 2, 3, 4;
+`.trim();
+
+export interface DefaultAclRow {
+  schema: unknown;
+  /** 'r' = table, 'S' = sequence. */
+  objtype: unknown;
+  grantee: unknown;
+  privilege: unknown;
+}
+
+/** schema (`''` = all schemas) → grantee → sorted privileges. */
+export type DefaultAclScope = Record<string, Record<string, string[]>>;
+
+/** Fold the per-privilege rows into { tables, sequences }, each schema → grantee → privileges. */
+export function assembleDefaultAcls(rows: readonly DefaultAclRow[]): { tables: DefaultAclScope; sequences: DefaultAclScope } {
+  const tables: DefaultAclScope = {};
+  const sequences: DefaultAclScope = {};
+  for (const row of rows) {
+    if (row.grantee == null || row.privilege == null) continue;
+    const scope = String(row.objtype) === 'S' ? sequences : String(row.objtype) === 'r' ? tables : null;
+    if (!scope) continue;
+    const schema = String(row.schema ?? '');
+    const grantee = String(row.grantee);
+    const byGrantee = scope[schema] ?? (scope[schema] = {});
+    byGrantee[grantee] = [...new Set([...(byGrantee[grantee] ?? []), String(row.privilege)])].sort();
+  }
+  return { tables, sequences };
+}
+
 /** The two privileges a schema ACL can carry, in aclitem letter form. */
 const SCHEMA_PRIV_LETTERS: Record<string, string> = { U: 'USAGE', C: 'CREATE' };
 
@@ -872,6 +934,8 @@ export interface ContractRows {
   schemaAcls?: SchemaAclRow[];
   /** SEQUENCE_ACLS_SQL. Optional — absent means not measured, never "no sequences". */
   sequenceAcls?: SequenceAclRow[];
+  /** DEFAULT_ACL_SQL. Optional — absent means not measured, never "no default privileges". */
+  defaultAcls?: DefaultAclRow[];
   /** Already-mapped function descriptors (from security-catalog's FUNCTIONS_SQL). */
   functions: { schema: string; name: string; securityDefiner: boolean; hasSearchPath: boolean; owner?: string; ownerBypassesRls?: boolean; ownerIsSuperuser?: boolean }[];
 }
@@ -966,6 +1030,7 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     ...(schemaAcls ? { schemaAcls } : {}),
     // Same absent-means-unmeasured contract as schemaAcls above.
     ...(rows.sequenceAcls ? { sequenceGrants: assembleSequenceGrants(rows.sequenceAcls) } : {}),
+    ...(rows.defaultAcls ? { defaultAcls: assembleDefaultAcls(rows.defaultAcls) } : {}),
   };
 }
 
@@ -978,8 +1043,8 @@ export async function introspectContract(
   // ONE session: the queries describe one moment under one pinned search_path.
   // Policy USING / WITH CHECK expressions deparse relative to that path, so a read spread
   // across connections can report authz drift that does not exist.
-  const [rls, policies, grants, columnGrants, effectivePrivileges, schemaAcls, sequenceAcls, fnRows] = await session(
-    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, EFFECTIVE_PRIVILEGES_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, functionsSql],
+  const [rls, policies, grants, columnGrants, effectivePrivileges, schemaAcls, sequenceAcls, defaultAcls, fnRows] = await session(
+    [RLS_SQL, POLICIES_SQL, GRANTS_SQL, COLUMN_GRANTS_SQL, EFFECTIVE_PRIVILEGES_SQL, SCHEMA_ACL_SQL, SEQUENCE_ACLS_SQL, DEFAULT_ACL_SQL, functionsSql],
     INTROSPECTION_SESSION,
   );
   return assembleContract({
@@ -990,6 +1055,7 @@ export async function introspectContract(
     effectivePrivileges: effectivePrivileges as EffectivePrivilegeRow[],
     schemaAcls: schemaAcls as SchemaAclRow[],
     sequenceAcls: sequenceAcls as SequenceAclRow[],
+    defaultAcls: defaultAcls as DefaultAclRow[],
     functions: (fnRows as any[]).map(mapFunctionRow),
   });
 }

package/src/cli/authz-reconcile.ts

@@ -89,6 +89,61 @@ export function ungovernedGrants(live: AuthzContract, governed: ReadonlySet<stri
   return out.sort((a, b) => a.grantee.localeCompare(b.grantee) || a.table.localeCompare(b.table));
 }
 
+/**
+ * A declared table's authz AFTER the edge lands — the FULL prediction's per-table building block.
+ *
+ * The reconciler converges the GOVERNED roles onto the declared contract and leaves every other
+ * (foreign) grantee alone. So the post-apply truth for a declared table is: the declared contract
+ * PLUS the live authz of the ungoverned roles. The governed prediction drops that second half; on
+ * a brownfield stage the foreign grants live on, so a `to` endpoint without them can never equal
+ * the post-apply full live hash (milestone plan-endpoint-full).
+ *
+ * Carried ONLY onto objects the declared target still has (condition (a) of the N2 ruling):
+ *  - table-level grants ride whole — the table is present by construction;
+ *  - a column grant rides only for the columns in `presentColumns`; a grant on a column the edge
+ *    DROPS is gone after apply, so carrying it would predict an endpoint the apply cannot reach —
+ *    a false verify-failed after the DDL already landed;
+ *  - a policy rides only when EVERY role it names is ungoverned. A policy touching a governed role
+ *    is the reconciler's to manage, so it is not carried here (if the reconciler leaves it, the
+ *    verify-after fails LOUD rather than being hidden).
+ *
+ * The declared (governed) grants always win over any live grant to the same role: a governed role
+ * whose live grant the models dropped must be REVOKED by the plan, never carried through.
+ */
+export function carryUngovernedAuthz(
+  declared: TableContract,
+  live: TableContract,
+  governed: ReadonlySet<string>,
+  presentColumns: ReadonlySet<string>,
+): TableContract {
+  const foreign = (role: string): boolean => !isGoverned(governed, role);
+
+  const grants: Record<string, string[]> = { ...declared.grants };
+  for (const [role, privileges] of Object.entries(live.grants)) {
+    if (foreign(role)) grants[role] = [...privileges];
+  }
+
+  const columnGrants: Record<string, Record<string, string[]>> = { ...(declared.columnGrants ?? {}) };
+  for (const [role, byPrivilege] of Object.entries(live.columnGrants ?? {})) {
+    if (!foreign(role)) continue;
+    const kept: Record<string, string[]> = {};
+    for (const [privilege, columns] of Object.entries(byPrivilege)) {
+      const present = columns.filter((c) => presentColumns.has(c));
+      if (present.length > 0) kept[privilege] = present;
+    }
+    if (Object.keys(kept).length > 0) columnGrants[role] = kept;
+  }
+
+  const carriedPolicies = live.policies.filter((p) => p.roles.length > 0 && p.roles.every(foreign));
+
+  return {
+    ...declared,
+    grants,
+    ...(Object.keys(columnGrants).length > 0 ? { columnGrants } : {}),
+    policies: [...declared.policies, ...carriedPolicies],
+  };
+}
+
 /**
  * The exemption report, one line per grantee — the shared rendering every surface prints.
  *
@@ -307,7 +362,18 @@ function reconcileSequenceGrants(
 export function emitReconcileSql(
   declared: AuthzContract,
   live: AuthzContract,
-  opts: { governedRoles?: ReadonlySet<string> } = {},
+  opts: {
+    governedRoles?: ReadonlySet<string>;
+    /**
+     * The serial sequences the SAME plan's data phase CREATES (a new serial table, a serial
+     * column added to an existing one) — reconciled as if live with no grants. Without them a
+     * created sequence got no governed grant until the NEXT plan: db:apply verified green and
+     * every INSERT by the governed holder failed `permission denied for sequence` for one plan
+     * cycle (milestone finish-0-4-x F1). They are emitted even when the live side never read
+     * sequences: the plan creates these, so there is no unread live state to misjudge.
+     */
+    createdSequences?: readonly SequenceGrantContract[];
+  } = {},
 ): string[] {
   // Condition C — two phases PER TABLE in one transaction: every access-REMOVING statement
   // (policy DROP, REVOKE, RLS ENABLE/FORCE) before every access-ADDING one (policy CREATE, GRANT,
@@ -325,7 +391,7 @@ export function emitReconcileSql(
   // Absent = the recorder never read sequences; skip the pass entirely rather than diff
   // against a set nobody measured. Grouped once, not re-scanned per table.
   const sequencesByTable = new Map<string, SequenceGrantContract[]>();
-  for (const seq of live.sequenceGrants ?? []) {
+  for (const seq of [...(live.sequenceGrants ?? []), ...(opts.createdSequences ?? [])]) {
     (sequencesByTable.get(seq.table) ?? sequencesByTable.set(seq.table, []).get(seq.table)!).push(seq);
   }
 

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

@@ -80,6 +80,15 @@ export interface StaticCheckInput {
   artifactPath: string;
   /** null = no generated schema artifact on disk. */
   artifactSource: string | null;
+  /**
+   * Where `artifactPath` came from — the same resolution db:generate records. An ABSENT artifact
+   * is only "nothing to match" at the untouched default (an app that never generated one). A path
+   * the operator named with `--schema-out`, or one the journal recorded, is a claim that an
+   * artifact lives there; its absence is the artifact gate vanishing, and must FAIL. Measured:
+   * `db:check --schema-out db/does-not-exist.ts` printed the note and passed with exit 0.
+   * Absent = default (older callers).
+   */
+  artifactOrigin?: 'flag' | 'recorded' | 'default';
   /** Set when a retired db/sql directory still carries .sql files — the tombstone
    *  message (with the migration path); a hard fail, never a shrug. */
   sqlDirRetired?: string | null;
@@ -250,7 +259,19 @@ export function runStaticChecks(input: StaticCheckInput): CheckFinding[] {
     }
   }
 
-  if (input.artifactSource === null) {
+  if (input.artifactSource === null && input.artifactOrigin === 'flag') {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — the path came from --schema-out, so an artifact is expected there. Fix the path, or run db:generate to write it. A named path with nothing at it is a gate that guards nothing.`,
+    });
+  } else if (input.artifactSource === null && input.artifactOrigin === 'recorded') {
+    findings.push({
+      level: 'fail',
+      area: 'artifact',
+      message: `no generated schema at ${input.artifactPath} — the migration journal records that path as the artifact (db:generate wrote it there). Restore it, run db:generate, or re-record with --schema-out.`,
+    });
+  } else if (input.artifactSource === null) {
     findings.push({
       level: 'note',
       area: 'artifact',
@@ -393,7 +414,7 @@ export async function dbCheckCommand(flags: Record<string, string>): Promise<voi
   } catch { /* no baseline — see above */ }
 
   const findings = runStaticChecks({
-    modelsPath, models, modelsError, modelFileScans, extensions, artifactPath, artifactSource, sqlDirRetired,
+    modelsPath, models, modelsError, modelFileScans, extensions, artifactPath, artifactSource, artifactOrigin: artifactRes.source, sqlDirRetired,
     sequences: declaredDb?.sequences, derived: declaredDb?.derived, derivedError,
     moduleModels: declaredDb?.models ?? null,
     baselineSource,

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

@@ -49,7 +49,7 @@ import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport } fr
 import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
-import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan';
+import { mintEdgePlan, planHash, buildPlanSummary, explainCarriedBy } from '../edge-plan';
 import { proveDescent, describeDriftOrigin, proveLineageLost, realLineageProbe, type ProveVerdict, type LineageProof } from '../git-descent';
 import { fingerprintLive, divergentSurfaces } from '../schema-fingerprint';
 import { predictLiveState } from '../edge-plan';
@@ -337,16 +337,22 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       await fs.writeFile(out, body, 'utf8');
     }
 
-    // An EMPTY edge between two different fingerprints reads as a contradiction. `from` is the
-    // target's full fingerprint (the concurrency lock at apply); `to` is the declared endpoint
-    // through the models' governed set. They differ by exactly what the plan leaves alone — name
-    // it, computed at mint from the two canonical forms, never stored on the plan.
-    const carriedBy = plan.statements.length === 0 && plan.fromFingerprint !== plan.toFingerprint
-      ? divergentSurfaces(
-        predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) }).canonical,
-        fingerprintLive(snapshot, contract).canonical,
-      )
-      : undefined;
+    // An EMPTY edge still has a story to tell, and the two cases tell DIFFERENT ones:
+    //  - `from == to`: the full endpoint carried the foreign grants through, so the plan is empty
+    //    AND equal. Name the ungoverned roles (condition (c)) — the operator must still see what
+    //    rides untouched and under which baseline.
+    //  - `from != to`: the FULL prediction failed to reproduce raw live — a real, unexplained
+    //    divergence. The foreign grants are ABSORBED into `to`, so they are NOT the cause; naming
+    //    them would misdirect. Name the divergent surface of the FULL prediction vs live instead.
+    const emptyEdge = plan.statements.length === 0;
+    const carriedBy = !emptyEdge
+      ? undefined
+      : plan.fromFingerprint === plan.toFingerprint
+        ? explainCarriedBy(exemptions, [])
+        : divergentSurfaces(
+          predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles), carryUngoverned: true }).canonical,
+          fingerprintLive(snapshot, contract).canonical,
+        );
     for (const line of buildPlanSummary(plan, carriedBy ? { carriedBy } : {})) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
 

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

@@ -38,6 +38,36 @@ import { fingerprintLive } from '../schema-fingerprint';
 import { ungovernedGrants, vestigialSequenceGrants, renderVestigialSequenceGrants, ALWAYS_GOVERNED, type GrantExemption } from '../authz-reconcile';
 import { buildStageBaseline, mergeBaseline, readBaselineFile, writeBaselineFile, BASELINE_FILE } from '../authz-baseline';
 import { introspectDerived, type DerivedCatalog } from '../derived-introspect';
+
+/**
+ * The on-ramp runbook, printed last so the operator is never left guessing what a pull is FOR.
+ *
+ * db:pull is the only way an existing database comes in. What happens next is decided by
+ * db:plan, not by a verb: an EMPTY plan means the committed Models declare the database as it
+ * is (adopted — descent proves the pull commit by recompile, and every later apply descends from
+ * it); a NON-EMPTY plan is the hardening edge, reviewed and applied as the origin. db:adopt used
+ * to bolt a proof onto this render; the proof was "would the plan be empty", so the verb is gone
+ * (cli 0.4.79) and this is what replaced it. Exported so a test pins the lines and the
+ * refusal-runbook lint reads them.
+ */
+export function pullOnRampRunbook(opts: { stage?: string; out?: string; abilities?: string }): string[] {
+  const target = opts.stage ? `--stage ${opts.stage}` : '--stage <name>';
+  const what = opts.out ? `the files in ${opts.out}` : 'these Models';
+  // Only a LIVE pull transcribes the database's own authz; only then can an empty plan mean
+  // "adopted as it is". A commented or public-read pull carries authored abilities — its plan is
+  // an edge to review (public-read on an existing database GRANTS public read of every table),
+  // never an adoption, and the runbook must not call it one (closing-gate review, 2026-09-07).
+  if (opts.abilities !== 'live') {
+    return [
+      `Next: author each model's abilities (db:check fails until every model declares) — for an EXISTING database, re-pull with --abilities live to derive them from the grants and policies already there. Then commit ${what} and run \`everystack db:plan ${target}\`: the plan is an edge to review, not an adoption of what is live.`,
+    ];
+  }
+  return [
+    `Next: commit ${what}, then \`everystack db:plan ${target}\`.`,
+    'EMPTY plan = adopted as it is: that commit declares the database, and every later db:apply descends from it. Nothing to apply.',
+    `NON-EMPTY plan = the hardening edge: review it, then \`everystack db:apply --plan <file> ${target}\`. No commit declares this database yet, so the reviewed plan is the ORIGIN — db:apply proves that and records it.`,
+  ];
+}
 import { introspectContract, type TableContract, type AuthzContract } from '../authz-contract';
 import { introspectTableOwners, buildOwnershipReport, renderOwnershipReport, type TableOwner } from '../authz-ownership';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
@@ -461,5 +491,6 @@ export async function dbPullCommand(flags: Record<string, string>): Promise<void
       note(`Committing this file ADOPTS those roles. Anything not in it — or anything that grows beyond it — refuses at db:plan.`);
     }
   }
+  for (const line of pullOnRampRunbook({ stage: flags.stage, out: flags.out, abilities })) note(line);
   process.exit(0);
 }