@everystack/cli 0.4.93 → 0.4.95

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/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';