@everystack/cli 0.4.93 → 0.4.96

package/src/cli/index.ts

@@ -332,7 +332,7 @@ Usage:
   everystack db:sync           [--database-url <url>] [--models <barrel>] [--schema-out <file.ts>] [--allow-drops] [--overwrite-drift] [--baseline] [--json]  Make the database match your checkout — one verb, both layers: apply the state diff (tables+authz, one transaction, verified by re-diff), reconcile the derived layer against the declared descriptors, report the resulting fingerprint vs the models' declared one. Dev databases only (direct connection required); DROPs held back unless --allow-drops; derived drift refuses unless --overwrite-drift; exit 1 when not converged
   everystack db:diff           --from-models <barrel> [--to-models db/models/index.ts] [--allow-drops] [--check] [--json]  The state edge between two declared states, NO database: the SQL db:generate would produce, computed purely — CI plan previews (--check exits 1 on a non-empty edge) and computed rollbacks (swap the flags)
   everystack db:plan           [--stage <name> [--direct] | --database-url <url>] [--models <barrel>] [--allow-drops] [--out db.plan.json | --out -] [--verbose]  Mint a verified edge against a target: asks the TARGET its fingerprint, diffs the models, writes ONE reviewable plan (edge + both endpoint fingerprints). Held drops refuse the mint (--allow-drops carries destruction explicitly). Read-only; plans are ephemeral, never committed. VENUES: --stage runs via the ops Lambda, which reads TWICE and refuses on disagreement — agreement there is a DETECTOR, not a verification. --stage --direct resolves the stage's operator connection from its IAM-gated ops Lambda, holds it in memory only, and reads ONCE over one session: the lane for a fingerprint you intend to trust, with the credential never on argv. --database-url is the local-dev venue (same read guarantee, but against a deployed stage it puts a privileged DSN on the command line) DEFAULT OUTPUT is the plain change list: '+' something is now true, '-' something is no longer true, and a '⚠ DESTRUCTIVE' line of its own when real data can be lost. Nothing else. --verbose restores the full internal report (edge summary, kind histogram, adoption and ownership reports, plan ref). The edge covers tables/columns/grants ONLY — it also reads (never mints) whether the DERIVED layer (functions/views/matviews/triggers) is out of sync with the target and warns if so, since db:apply always reconciles that layer regardless of --plan: an empty edge here does not mean the target fully matches the checkout
-  everystack db:apply          [--plan <file.plan.json>] [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--state-only] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>] [--verbose]  THE deploy verb — it does the WHOLE job: the reviewed plan (tables, columns, grants), then ALWAYS the functions, views, matviews and triggers, against the same target, reported as one receipt. With NO --plan it does the catch-up alone (this is what replaces running db:reconcile --apply by hand). --state-only skips the catch-up for the narrow case that wants the tables alone. A brownfield derived object the reconciler has never touched before (no provenance row) is SKIPPED, never guessed at, and that skip prints by default (not only under --verbose): 'N derived object(s) skipped ... db:reconcile --baseline' — a plain apply that only showed this under --verbose read as full success while such objects sat permanently unreconciled. If the plan lands and the catch-up then fails, the exit is non-zero and the message says the table/column changes are committed and safe and gives the rerun, which retries only the catch-up. Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit declaring the target's state (the fast-forward rule — it protects MERGED work: a commit on any ref that declares the live state and is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a declaring commit proven gone from every ref. When NO commit on ANY ref declares the live state — a database everystack never wrote, or one hand-edited since its last apply — the rule has nothing to protect: over a full, current clone that is PROVEN DRIFT, the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A shallow, partial, or behind-remote clone, or a models tree that will not compile, is UNVERIFIABLE and refuses with a fetch/prune runbook), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there DEFAULT OUTPUT is the receipt: the same change lines back, then 'Applied N changes.'. --verbose restores the endpoint and plan-ref line
+  everystack db:apply          [--plan <file.plan.json>] [--database-url <url>] [--stage <name>] [--models <barrel>] [--confirm] [--state-only] [--snapshot-ref <ref>] [--attest-lineage-lost <sha>] [--verbose]  THE deploy verb — it does the WHOLE job: the reviewed plan (tables, columns, grants), then ALWAYS the functions, views, matviews and triggers, against the same target, reported as one receipt. With NO --plan it does the catch-up alone (this is what replaces running db:reconcile --apply by hand). --state-only skips the catch-up for the narrow case that wants the tables alone. A brownfield derived object the reconciler has never touched before (no provenance row) is SKIPPED, never guessed at, and that skip prints by default (not only under --verbose): 'N derived object(s) skipped ... db:reconcile --baseline' — a plain apply that only showed this under --verbose read as full success while such objects sat permanently unreconciled. If the plan lands and the catch-up then fails, the exit is non-zero and the message says the table/column changes are committed and safe and gives the rerun, which retries only the catch-up. Run a reviewed plan: verify the target is EXACTLY where the plan started (live fingerprint == plan.from, else refuse — the concurrency lock), verify the checkout DESCENDS from the commit that last deployed the target (the fast-forward rule, read from schema_log and git ancestry — no historical tree is compiled: a deploying commit that is not an ancestor of HEAD refuses by name, escaped git-natively by fetch + merge/rebase + re-plan; --attest-lineage-lost <sha> waives it ONLY for a deploying commit proven gone from every ref. When no recorded apply matches the live state and nothing deployed is outside HEAD's history — a database everystack never wrote, or one hand-edited since its last apply — that is DRIFT: the reviewed plan is the ORIGIN, it applies with a loud warning, and the origin is recorded in schema_log so every later apply descends from it. A deploying commit this clone lacks refuses with a fetch runbook; an unreadable schema_log is UNVERIFIABLE and refuses), and for DESTRUCTIVE plans require --confirm always + a confirmed rollback point + the stage's approver set when declared (STS identity-verified). The STAGE lane (--stage without --direct) runs every catalog query in its own ops-Lambda invoke, so one read can be assembled from several containers: it reads the target TWICE and REFUSES when the two disagree (inconsistent containers), reports agreement as a NON-DETECTION (it cannot verify read consistency), and REFUSES a DESTRUCTIVE plan outright — destructive applies go over --database-url (direct) with the full ceremony. Every refusal that reaches the ops Lambda is recorded in schema_log. Apply as one transaction (plan_ref stamped), verify it landed exactly on plan.to; idempotent when already there DEFAULT OUTPUT is the receipt: the same change lines back, then 'Applied N changes.'. --verbose restores the endpoint and plan-ref line
   everystack db:build          --database-url <url> [--models <barrel>]  Build a database FROM the models and KEEP it — the fresh-database bootstrap a deleted migration folder is replaced BY. Runs the same compose db:check proves buildability with (extensions -> schemas -> contract roles -> declared functions -> state -> derived layer), against a real target, then reports MATCH. Venue is EXPLICIT: --database-url only, never the ambient environment, because this writes a whole schema. REFUSES a database that already holds objects — evolving an existing one is db:sync (dev) or db:plan -> db:apply (a stage). Contract roles are created NOLOGIN if absent, and roles are cluster-level
   everystack db:check          [--models <barrel>] [--schema-out <file.ts>] [--database-url <url>] [--json] [--verbose]  The CI gate, per PR: the merged declared state must COMPOSE (models load, no duplicate tables, descriptors compile), every exposed RLS-enabled table must declare a read path (no force-RLS-with-no-read landmine that goes dark on the superuser drop), and generated artifacts must MATCH regeneration byte-for-byte; with a scratch PostgreSQL it builds the state from scratch on an ephemeral database (created + dropped) and requires fingerprint MATCH. Exit 1 on any failure; never touches a real target DEFAULT OUTPUT is ONE line: 'Up to date.' or 'N changes pending. Run db:plan to review.'. --verbose restores every finding and the from-scratch build report
   everystack db:approvers      --stage <name> [--set "cto,arn:..."] [--remove]  Declare who can DESTROY: the stage's destructive-approver set (SSM parameter, admin-writable). Destructive db:apply runs are then identity-verified (STS) against it; --set '' disables destructive applies; --remove returns the stage to ceremony-only

package/src/cli/plain-output.ts

@@ -85,6 +85,12 @@ function oneLine(statement: string): string {
 
 const unquote = (name: string): string => name.replace(/"/g, '').trim();
 
+/** A GRANT's `TO …` / a REVOKE's `FROM …` list, every grantee: `admin, anon` — never `admin,`. */
+const GRANTEES = String.raw`((?:"[^"]+"|[\w$]+)(?:\s*,\s*(?:"[^"]+"|[\w$]+))*)`;
+const grantees = (list: string): string => list.split(',').map(unquote).join(', ');
+const GRANT_RE = new RegExp(String.raw`^GRANT\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+TO\s+` + GRANTEES, 'i');
+const REVOKE_RE = new RegExp(String.raw`^REVOKE\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+FROM\s+` + GRANTEES, 'i');
+
 /** `public.events` → `events`; `stats.runs` → `stats.runs`. The default schema is noise. */
 function rel(name: string): string {
   const clean = unquote(name).replace(/;$/, '');
@@ -193,11 +199,11 @@ export function describeChange(statement: string, opts: DescribeOptions = {}): P
   if ((m = /^DROP\s+POLICY\s+(?:IF\s+EXISTS\s+)?("[^"]+"|[\w$]+)\s+ON\s+([^\s;]+)/i.exec(s))) {
     return { symbol: '-', text: `remove policy ${unquote(m[1])} on ${rel(m[2])}` };
   }
-  if ((m = /^GRANT\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+TO\s+([^\s;]+)/i.exec(s))) {
-    return { symbol: '+', text: `grant ${unquote(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
+  if ((m = GRANT_RE.exec(s))) {
+    return { symbol: '+', text: `grant ${grantees(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
   }
-  if ((m = /^REVOKE\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+FROM\s+([^\s;]+)/i.exec(s))) {
-    return { symbol: '-', text: `revoke ${unquote(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
+  if ((m = REVOKE_RE.exec(s))) {
+    return { symbol: '-', text: `revoke ${grantees(m[3])}: ${privileges(m[1])} ${grantObject(m[2])}` };
   }
   // A "rebuild" — the same function coming back with a new body — is ONE update line. The
   // drop half is never shown: the object does not go away, its definition changes.
@@ -281,8 +287,8 @@ export function describeDestructive(statement: string): string {
   if ((m = /^DROP\s+TYPE\s+(?:IF\s+EXISTS\s+)?([^\s;]+)/i.exec(s))) {
     return `drops type ${rel(m[1])}`;
   }
-  if ((m = /^REVOKE\s+([\s\S]+?)\s+ON\s+([\s\S]+?)\s+FROM\s+([^\s;]+)/i.exec(s))) {
-    return `revokes ${privileges(m[1])} on ${grantObject(m[2])} from ${unquote(m[3])} — nothing declares it, so it cannot be put back`;
+  if ((m = REVOKE_RE.exec(s))) {
+    return `revokes ${privileges(m[1])} on ${grantObject(m[2])} from ${grantees(m[3])} — nothing declares it, so it cannot be put back`;
   }
   return oneLine(statement);
 }

package/src/cli/state-apply.ts

@@ -370,8 +370,8 @@ export interface StateApplyOptions {
   now?: () => number;
   /**
    * What descent decided, folded into the schema_log outcome as `applied — <note>`: a honoured
-   * `--attest-lineage-lost` waiver, or a PROVEN DRIFT origin (`descent: drift-origin proven
-   * (never-declared | hand-edited since … | applied from a DIRTY worktree at …)`) — the record that makes this row the origin every
+   * `--attest-lineage-lost` waiver, or a DRIFT origin (`descent: drift-origin
+   * never-declared (…) | hand-edited since … | applied from a DIRTY worktree at …`) — the record that makes this row the origin every
    * later apply descends from. Read at WRITE time (a getter, because the decision is made in the
    * descent step that runs before this). The witness query matches `applied%`, so an annotated
    * row is still a witness.

package/src/cli/state-function-deps.ts

@@ -0,0 +1,95 @@
+/**
+ * state-function-deps — the declared functions a pending STATE batch calls, created first.
+ *
+ * Sync and apply run STATE (tables, RLS, policies, grants) before the DERIVED layer
+ * (functions, views, matviews, triggers). That order is right for views and triggers, which
+ * read tables state creates. It is wrong for one edge: an RLS policy's predicate is resolved
+ * when the policy is CREATED, so `can('read', { where: sql\`has_permission()\` })` over a
+ * declared `has_permission()` fails on a fresh database with `function has_permission() does
+ * not exist` — the function only arrives in the second half.
+ *
+ * So the edge is followed, not the layers swapped: a declared function whose name appears in
+ * a pending state statement, and which the target does not have yet, is created BEFORE the
+ * state batch. Everything else keeps the ordinary order.
+ *
+ * The reference test is TEXT, on purpose. Predicates are already compiled and diffed as text,
+ * and a false positive is harmless: creating a missing function early is exactly what the
+ * ordinary pass would do a moment later.
+ *
+ * A function whose SIGNATURE names a declared relation (`RETURNS SETOF some_view`) cannot go
+ * first — PostgreSQL resolves argument and return types at creation, and the relation may be
+ * created by state or by a view later in the derived pass. It stays behind, as in db:build.
+ */
+
+import type { QueryRunner } from './authz-contract';
+import type { SessionRunner } from './session';
+import type { SourceObject } from './derived-source';
+import { executeReconcile } from './commands/db-reconcile';
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** A call to `schema.name(` or `name(`, quoted or not, not preceded by another qualifier. */
+function callPattern(schema: string, name: string): RegExp {
+  const q = (id: string) => `"?${escapeRe(id)}"?`;
+  return new RegExp(`(?:^|[^\\w$."])(?:${q(schema)}\\s*\\.\\s*)?${q(name)}\\s*\\(`, 'i');
+}
+
+/**
+ * The declared functions a state batch names by call — the pure half, no database.
+ * Only functions that CAN go first: no signature dependency on a declared relation.
+ */
+export function stateReferencedFunctions(statements: readonly string[], declared: readonly SourceObject[]): SourceObject[] {
+  if (statements.length === 0) return [];
+  const text = statements.join('\n');
+  return declared.filter((o) =>
+    o.kind === 'function'
+    && !o.signatureDeps?.length
+    && callPattern(o.schema, o.name).test(text));
+}
+
+const literal = (s: string): string => `'${s.replace(/'/g, "''")}'`;
+
+/**
+ * Create, before the state batch, the declared functions it calls that the target lacks.
+ * Returns the identities created (empty when nothing needed to move).
+ *
+ * The reconcile runs with the FULL declared set and `only` scoped to these identities, never a
+ * subset: a subset would read every other managed object as "removed from source" and drop it.
+ * A function that already exists is left to the ordinary after-state pass, so an existing
+ * database's replace/drift handling is unchanged by this.
+ *
+ * A SQL-language body that reads a table this same state batch creates is a forward reference,
+ * not an error: the reconcile runs its batch under `SET LOCAL check_function_bodies = off`.
+ */
+export async function createStateReferencedFunctions(
+  runner: QueryRunner,
+  session: SessionRunner,
+  statements: readonly string[],
+  declared: readonly SourceObject[],
+  options: { actor?: string | null; gitRef?: string | null; now?: () => number } = {},
+): Promise<string[]> {
+  const referenced = stateReferencedFunctions(statements, declared);
+  if (referenced.length === 0) return [];
+
+  const live = await runner(
+    `SELECT n.nspname AS schema, p.proname AS name FROM pg_proc p
+       JOIN pg_namespace n ON n.oid = p.pronamespace
+      WHERE p.proname IN (${[...new Set(referenced.map((o) => o.name))].map(literal).join(', ')})`,
+  );
+  const present = new Set(live.map((r: any) => `${r.schema}.${r.name}`));
+  const missing = referenced.filter((o) => !present.has(`${o.schema}.${o.name}`));
+  if (missing.length === 0) return [];
+
+  const run = await executeReconcile(runner, session, {
+    declared: [...declared],
+    only: missing.map((o) => o.identity),
+    apply: true,
+    actor: options.actor ?? null,
+    gitRef: options.gitRef ?? null,
+    now: options.now,
+  });
+  if (run.refusal) {
+    throw new Error(`could not create the functions the state batch calls (${missing.map((o) => o.identity).join(', ')}) before it: ${run.refusal}`);
+  }
+  return missing.map((o) => o.identity);
+}

package/src/exec.ts

@@ -11,7 +11,7 @@
 export { executeExec, assertNoTxnControl, execSha } from './cli/exec-execute';
 export type { ExecIntent, ExecOutcome, ExecuteExecOptions, ExecResult } from './cli/exec-execute';
 
-export { runExecInTx, SchemaChangedError, railStatements, EXEC_RAIL_DEFAULTS } from './cli/exec-run';
+export { runExecInTx, SchemaChangedError, LedgerWriteError, railStatements, EXEC_RAIL_DEFAULTS } from './cli/exec-run';
 export type { TxRunner, ExecStmtResult, ExecRails, RunExecInTxOptions } from './cli/exec-run';
 
 export { catalogDigestQuery } from './cli/exec-digest';