@everystack/cli 0.4.99 → 0.4.102

package/CHANGELOG.md

@@ -4,6 +4,111 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.102] - 2026-10-23
+
+### Added
+
+- db:doctor reports lifecycle rows past the purge window
+- generated lifecycle functions carry manifests
+- db:pull verifies generated lifecycle objects
+
+### Fixed
+
+- restore uses set-based updates, not a subtransaction per row
+- drop a replaced primary key before altering its columns
+- match quoted trigger functions by parsed identifiers
+- db:pull renders the owner read pair as owner
+- the verifier leaves an author's own restore overload alone
+- allow author after-delete lifecycle triggers
+- detect constraint lifecycle trigger replacements
+- the verifier compares the declared delete rules with the live policies
+- an invalid --purge-after fails cleanly
+- check lifecycle restrict edges once, after the whole cascade
+- reconcile drops a removed trigger before the function it executes
+- a DELETE issued from inside a trigger on a lifecycle table is a soft delete
+- pull-verify names the older CLI's restrict pair as stale and points to db:apply
+- pull-verify drops only a whole pg_catalog qualifier from a trigger WHEN
+
+### Documentation
+
+- state the lifecycle restrict contract, multi-row order and the lifecycle-column rule
+- consumer triggers under a stamp or purge: qualified names, soft deletes, and the db:apply remedy for an older CLI's restrict pair
+- an older CLI's restrict function may report a missing manifest instead of stale; both say db:apply
+
+## [0.4.101] - 2026-10-22
+
+### Added
+
+- db:plan lists the functions, views and triggers db:apply will change
+- update names the .sst files it read when it finds no HOST_URL
+- external FK target, .references({ schema, table, column })
+- F7a relation options; hasMany dependent sets the child FK ON DELETE
+- relation display options and hasOne (F7b)
+- db:generate writes the model map; db:check fails when it is stale (F8)
+- the model map carries softDelete; the admin reads it instead of the preset's hand-written flag (A5)
+- hasMany dependent 'cascade' is ON DELETE CASCADE on the child's foreign key (D1)
+- lifecycle: true declares four generated columns (L1.1)
+- lifecycle gets a reserved owner role and hides deleted rows from read roles (L1.2a)
+- lifecycle triggers turn DELETE into a soft delete (L1.2b)
+- lifecycle restore, for whoever may delete the row (L1.3)
+- db:pull folds a lifecycle table back to lifecycle: true (L1.4)
+- a lifecycle parent's delete soft-deletes its cascade children in the same batch (L2 + L6, P1.2)
+- <t>_restore brings back the row's whole batch subtree on the root's authority (L3, P1.3)
+- Restore on a lifecycle resource restores its batch and previews it first (P1.5)
+- db:provision creates the reserved lifecycle role (P2.7)
+- a NOT NULL column has no clear control (N6)
+
+### Fixed
+
+- a disabled derived trigger is drift
+- import a non-public FK target by its qualified name
+- a plan that removes a function, view or trigger is not "Safe to apply"
+- key the pulled set on qualified names
+- db:pull --govern-roles round-trips custom-role policies and column grants (assoc F4)
+- db:pull refuses a no-USING column policy and escapes live predicates (assoc F4 review)
+- escape live text in db:pull's sql templates
+- escape the defineSql fallback's DROP FUNCTION template
+- db:pull refuses live names with no safe generated identifier or file name
+- db:pull escapes live text in // comments and walls every write inside its directory
+- a grant to a role named __proto__ is visible to db:plan, db:pull and the fingerprint
+- db:pull never renders a policy that admits no row as an ability
+- F3e review minors: catalog FK target, one target slot, derived refusal
+- F3e re-review: fail closed on a changed FK target; unambiguous comment
+- F7a review: derive dependent ON DELETE per set, never write a field spec
+- F7b review: mark display relations in drizzle, withhold only where/limit
+- F8 review: private SQL spellings, key collisions, T2 mock proof
+- run state DDL under the canonical search_path; read non-public enums as qualified
+- retype a column onto an enum through text, dropping the old default first
+- the map publishes the soft-delete field key, not a boolean (A5 review)
+- owned trigger functions deploy as a non-superuser; the lifecycle transition runs only on its own table (L1.2c)
+- the lifecycle pull fold keeps an author's restore overload and governs the reserved role at adoption (L1.4 review)
+- the lifecycle pull fold checks the reserved role's effective privileges and always names its unfolded grants (P1.0 review)
+- db:plan changes a primary key, and refuses to mint what it cannot express (P2.8)
+
+### Changed
+
+- fake timers for the two polling suites; generate the default cert once
+
+### Documentation
+
+- name the one runtime-vs-generated Drizzle difference a parent dependent creates
+- say which fingerprint inputs moved; mark the guard-only enum diff test
+- state precisely which policies admit no row and that a column grant under one is revoked
+
+## [0.4.100] - 2026-10-16
+
+### Added
+
+- check() takes an explicit constraint name; db:pull keeps a live name
+
+### Fixed
+
+- db:apply runs a rename-only plan
+
+### Documentation
+
+- a check folded into .validate() takes the field check name
+
 ## [0.4.99] - 2026-10-14
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.99",
+  "version": "0.4.102",
   "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.21"
+    "@everystack/model": "0.4.23"
   },
   "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.35"
+    "@everystack/server": "0.4.38"
   },
   "scripts": {
     "test": "jest",

package/src/cli/apply-execute.ts

@@ -73,6 +73,7 @@ import {
 import { validationPendingReason, pendingValidationsAreSafe } from './apply-refusals';
 import { ENSURE_RECONCILER_SQL, renderSchemaLogInsert, renderSchemaLogFingerprintUpdate } from './derived-apply';
 import { checkPlanPrecondition, planHash, defaultAclHash, type EdgePlan } from './edge-plan';
+import { renameEdgeVerdict } from './catalog-rename';
 import type { DescentLedgerRow, LedgerRead } from './git-descent';
 
 /**
@@ -477,7 +478,20 @@ export async function executeApplyPlan(
   }
 
   if (live === plan.toFingerprint) {
-    return { status: 'already-applied', liveFingerprint: live };
+    // The hash is blind to a catalog rename (a check is keyed by predicate, an index or key by
+    // content), so a plan of renames alone has from == to == live whether or not it ran. Only
+    // then do the names decide, read from the same snapshot as the lock. Not landed: fall
+    // through, and every gate below runs. Half landed, or in a shape the plan never predicted:
+    // stale. Everything else is today's idempotent re-apply.
+    const verdict = plan.fromFingerprint === plan.toFingerprint
+      ? renameEdgeVerdict(plan.statements, before)
+      : { verdict: 'not-renames' as const };
+    if (verdict.verdict === 'stale') {
+      const reason = `this plan is stale: ${verdict.reason}. Re-mint with db:plan.`;
+      await recordRefusal(runner, plan, live, 'rename edge', reason, options);
+      return { status: 'refused', liveFingerprint: live, reason };
+    }
+    if (verdict.verdict !== 'unsettled') return { status: 'already-applied', liveFingerprint: live };
   }
   const pre = checkPlanPrecondition(plan, live);
   if (!pre.ok) {

package/src/cli/authz-baseline.ts

@@ -83,7 +83,9 @@ export function buildStageBaseline(
   exemptions: readonly GrantExemption[],
   meta: { observedAt: string; fingerprint: string; fpVersion?: number },
 ): BaselineStage {
-  const grantees: Record<string, BaselineGrantee> = {};
+  // Null-prototype: a grantee is a live role name. On a plain object `grantees['__proto__'] ??=`
+  // reads Object.prototype, and the writes below would land ON Object.prototype.
+  const grantees: Record<string, BaselineGrantee> = Object.create(null);
   for (const e of exemptions) {
     const g = (grantees[e.grantee] ??= { privileges: [], tables: [], write: false });
     g.privileges = [...new Set([...g.privileges, ...e.privileges])].sort();
@@ -112,10 +114,10 @@ export function mergeBaseline(existing: AuthzBaseline | null, stage: string, ent
  * itself would make the review signal worthless.
  */
 export function renderBaseline(baseline: AuthzBaseline): string {
-  const stages: Record<string, BaselineStage> = {};
+  const stages: Record<string, BaselineStage> = Object.create(null);
   for (const stage of Object.keys(baseline.stages).sort()) {
     const s = baseline.stages[stage];
-    const grantees: Record<string, BaselineGrantee> = {};
+    const grantees: Record<string, BaselineGrantee> = Object.create(null);
     for (const g of Object.keys(s.grantees).sort()) {
       const { privileges, tables, write } = s.grantees[g];
       grantees[g] = { privileges: [...privileges].sort(), tables: [...tables].sort(), write };
@@ -182,7 +184,9 @@ export function checkAgainstBaseline(
 
   for (const grantee of Object.keys(observed).sort()) {
     const now = observed[grantee];
-    const then = recorded[grantee];
+    // Own keys only: the recorded baseline is JSON.parse'd, so a missing `__proto__` entry would
+    // read Object.prototype — truthy — and wave an unbaselined role through.
+    const then = Object.hasOwn(recorded, grantee) ? recorded[grantee] : undefined;
     if (!then) {
       violations.push({
         grantee,

package/src/cli/authz-compile.ts

@@ -20,7 +20,7 @@
  * Input is a `@everystack/model` ModelDescriptor (type-only — no runtime dep).
  */
 
-import { isColumnAbility, type ModelDescriptor, type Ability } from '@everystack/model';
+import { isColumnAbility, LIFECYCLE_OWNER_ROLE, type ModelDescriptor, type Ability } from '@everystack/model';
 import type { PolicyContract, TableContract, PolicyCommand } from './authz-contract';
 import { parenthesizeOnce, isBareCall } from './authz-contract';
 import { normalizeDeparsedExpr } from './deparse-normal';
@@ -284,17 +284,19 @@ const policyRole = (role: string): string => (isPseudoPublic(role) ? 'public' :
  * deduplicated, matching the introspected contract.
  */
 function compileColumnGrants(abilities: readonly Ability[]): Record<string, Record<string, string[]>> | undefined {
-  const out: Record<string, Record<string, Set<string>>> = {};
+  // Null-prototype maps, as on the introspected side (assembleContract): a role is a key, and
+  // '__proto__' passes the role-name guard, so a plain object would lose it.
+  const out: Record<string, Record<string, Set<string>>> = Object.create(null);
   for (const a of abilities) {
     if (!isColumnAbility(a)) continue;
     const role = granteeKey(a.condition.role ?? 'authenticated');
     const verb = a.action === 'read' ? 'SELECT' : 'UPDATE';
-    const cols = ((out[role] ??= {})[verb] ??= new Set<string>());
+    const cols = ((out[role] ??= Object.create(null) as Record<string, Set<string>>)[verb] ??= new Set<string>());
     for (const column of a.condition.columns!) cols.add(toSnakeCase(column));
   }
-  const grants: Record<string, Record<string, string[]>> = {};
+  const grants: Record<string, Record<string, string[]>> = Object.create(null);
   for (const [role, verbs] of Object.entries(out)) {
-    grants[role] = {};
+    grants[role] = Object.create(null);
     for (const [verb, columns] of Object.entries(verbs)) grants[role][verb] = [...columns].sort();
   }
   return Object.keys(grants).length ? grants : undefined;
@@ -438,6 +440,12 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
       ? viaPredicate(via)
       : null;
   const sdGuard = sdCol ? softDeleteGuard(sdCol) : null;
+  // A lifecycle model hides deleted rows from every read policy but the lifecycle role's own.
+  // Unlike softDelete there is no owner escape: the guard is AND-ed into each SELECT policy as
+  // compiled. A `manage` role's ALL policy is NOT guarded, on purpose: it sees deleted rows (to
+  // restore or purge them), exactly as it does under softDelete.
+  const lifecycleCol = model.lifecycle ? 'deleted_at' : null;
+  const lifecycleGuard = lifecycleCol ? softDeleteGuard(lifecycleCol) : null;
 
   // A "row-scoped" condition is either a direct owner or a transitive via.
   const rowScoped = (a: Ability): boolean => Boolean(a.condition.owner || a.condition.via);
@@ -534,6 +542,9 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
     name: string, command: PolicyCommand, roles: string[],
     using: string | null, check: string | null,
   ): void => {
+    if (lifecycleGuard && command === 'SELECT' && !roles.includes(LIFECYCLE_OWNER_ROLE)) {
+      using = andPredicates(lifecycleGuard, using) ?? lifecycleGuard;
+    }
     // Same normalization the live producer applies (authz-contract's `predicate`): a model
     // pulled on one PostgreSQL major carries that major's deparse spelling in its predicates,
     // and it must compare equal against a stage on another. One rule table, two producers.
@@ -823,6 +834,24 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
 
   policies.sort((a, b) => a.name.localeCompare(b.name));
 
+  // The lifecycle restore function inlines these DELETE rules and runs them as the lifecycle
+  // owner. Check the text as compiled, whatever produced it (via, ownerExpr, where, sql): a
+  // subquery would read with that role's privileges, and current_user/session_user would not
+  // name the caller. defineModel refuses the common spellings first with friendlier messages.
+  if (model.lifecycle) {
+    for (const p of policies) {
+      if (p.command !== 'DELETE' && p.command !== 'ALL') continue;
+      const offender = /\bselect\b|\bcurrent_user\b|\bsession_user\b/i.exec(p.using ?? '')?.[0];
+      if (!offender) continue;
+      throw new Error(
+        `${table}: policy ${p.name} (${p.command}) uses ${offender} on a lifecycle: true model. Restore runs this delete rule `
+        + `inside a SECURITY DEFINER function as the lifecycle owner, where a subquery reads with that role's privileges and `
+        + `current_user/session_user do not name the caller. Use a predicate on the row's own columns or the request claims `
+        + `(owner without ownerExpr, or a plain where).`,
+      );
+    }
+  }
+
   return {
     table,
     // The FORCE axiom: FORCE iff the write principal is subject to its own RLS
@@ -841,6 +870,30 @@ export function compileTableContract(model: ModelDescriptor, opts: CompileOption
   };
 }
 
+/**
+ * The table's DELETE rule per role: role -> the USING of every compiled DELETE or ALL policy
+ * naming that role, OR-ed (each parenthesized) when there are several. Read back from
+ * {@link compileTableContract}, so it is the policy rule by construction, never a second
+ * derivation. The lifecycle role is left out: it is the machinery, not an author's role.
+ * A policy with no USING admits nothing here, so it is skipped (fail closed).
+ */
+export function deleteRulePredicates(model: ModelDescriptor, opts: CompileOptions = {}): Record<string, string> {
+  const byRole = new Map<string, string[]>();
+  for (const p of compileTableContract(model, opts).policies) {
+    if ((p.command !== 'DELETE' && p.command !== 'ALL') || p.using == null) continue;
+    for (const role of p.roles) {
+      if (role === LIFECYCLE_OWNER_ROLE) continue;
+      byRole.set(role, [...(byRole.get(role) ?? []), p.using]);
+    }
+  }
+  const out: Record<string, string> = {};
+  for (const role of [...byRole.keys()].sort()) {
+    const preds = byRole.get(role)!;
+    out[role] = preds.length === 1 ? preds[0] : preds.map((p) => `(${p})`).join(' OR ');
+  }
+  return out;
+}
+
 /** The four DML privileges, sorted — the expansion of a `manage` ability. */
 const CRUD = ['DELETE', 'INSERT', 'SELECT', 'UPDATE'];
 
@@ -885,7 +938,8 @@ function compileGrants(
   abilities: readonly Ability[],
   privileges: Record<string, readonly string[]> = {},
 ): Record<string, string[]> {
-  const grants: Record<string, Set<string>> = {};
+  // Null-prototype, for the same reason as compileColumnGrants.
+  const grants: Record<string, Set<string>> = Object.create(null);
   const add = (role: string, verbs: readonly string[]): void => {
     const set = (grants[role] ??= new Set<string>());
     for (const v of verbs) set.add(v);
@@ -907,7 +961,7 @@ function compileGrants(
   for (const [role, privs] of Object.entries(privileges)) {
     if (privs.length) add(granteeKey(role), privs);
   }
-  const out: Record<string, string[]> = {};
+  const out: Record<string, string[]> = Object.create(null);
   for (const role of Object.keys(grants).sort()) out[role] = [...grants[role]].sort();
   return out;
 }

package/src/cli/authz-contract.ts

@@ -713,7 +713,7 @@ export function assembleSequenceGrants(rows: readonly SequenceAclRow[]): Sequenc
   for (const row of rows) {
     const entry = bySequence.get(row.sequence)
       ?? {
-        sequence: row.sequence, table: row.table, grants: {} as Record<string, string[]>,
+        sequence: row.sequence, table: row.table, grants: Object.create(null) as Record<string, string[]>,
         // Omitted rather than `false` on a serial sequence, so a contract read before this
         // field existed and one read after compare structurally equal.
         ...(truthy(row.is_identity) ? { identity: true } : {}),
@@ -766,15 +766,15 @@ 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 = {};
+  const tables: DefaultAclScope = Object.create(null);
+  const sequences: DefaultAclScope = Object.create(null);
   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] = {});
+    const byGrantee = scope[schema] ?? (scope[schema] = Object.create(null));
     byGrantee[grantee] = [...new Set([...(byGrantee[grantee] ?? []), String(row.privilege)])].sort();
   }
   return { tables, sequences };
@@ -796,8 +796,8 @@ export function parseSchemaAcl(text: string | null | undefined): Record<string,
   const s = String(text).trim();
   if (!s.startsWith('{') || !s.endsWith('}')) return null;
   const body = s.slice(1, -1);
-  if (body.trim() === '') return {};
-  const out: Record<string, string[]> = {};
+  if (body.trim() === '') return Object.create(null);
+  const out: Record<string, string[]> = Object.create(null);
   // Split items at top-level commas — a quoted region may contain commas.
   const items: string[] = [];
   let start = 0;
@@ -986,13 +986,19 @@ export interface ContractRows {
  * empty allowlist a diff would never flag. Only SECURITY DEFINER functions are
  * recorded: an INVOKER function runs as the caller under RLS and is not an
  * authorization decision point; a SECDEF function runs above RLS and is.
+ *
+ * Every map keyed by a live name (role, schema) is `Object.create(null)`. On a plain object
+ * `grants['__proto__'] = x` sets the prototype and adds no key, and PostgreSQL allows a quoted
+ * role named "__proto__": its grants vanished from this read, so the plan, the fingerprint and
+ * the pull could not see them. A null-prototype object serializes and iterates exactly like a
+ * plain one, so an ordinary database reads byte-identically.
  */
 export function assembleContract(rows: ContractRows): AuthzContract {
   const tables = new Map<string, TableContract>();
   for (const row of rows.rls) {
     if (IGNORED_SCHEMAS.has(row.schema)) continue;
     const { table, rls } = rlsRowToDescriptor(row);
-    tables.set(table, { table, rls, grants: {}, policies: [] });
+    tables.set(table, { table, rls, grants: Object.create(null), policies: [] });
   }
 
   // A grant or policy on a table the RLS enumerator didn't list (e.g. a view, excluded
@@ -1011,8 +1017,8 @@ export function assembleContract(rows: ContractRows): AuthzContract {
     const { table, grantee, privilege, column } = columnGrantRowToDescriptor(row);
     const t = tables.get(table);
     if (!t) continue;
-    const byGrantee = (t.columnGrants ??= {});
-    const byPriv = (byGrantee[grantee] ??= {});
+    const byGrantee = (t.columnGrants ??= Object.create(null) as Record<string, Record<string, string[]>>);
+    const byPriv = (byGrantee[grantee] ??= Object.create(null) as Record<string, string[]>);
     (byPriv[privilege] ??= []).push(column);
   }
 
@@ -1025,7 +1031,7 @@ export function assembleContract(rows: ContractRows): AuthzContract {
       const { table, role, privileges } = effectivePrivilegeRowToDescriptor(row);
       const t = tables.get(table);
       if (!t || privileges.length === 0) continue;
-      (t.effectivePrivileges ??= {})[role] = [...privileges].sort();
+      (t.effectivePrivileges ??= Object.create(null) as Record<string, string[]>)[role] = [...privileges].sort();
     }
   }
 
@@ -1053,10 +1059,10 @@ export function assembleContract(rows: ContractRows): AuthzContract {
   // is distinguishable from "we never looked".
   let schemaAcls: Record<string, Record<string, string[]>> | undefined;
   if (rows.schemaAcls) {
-    schemaAcls = {};
+    schemaAcls = Object.create(null) as Record<string, Record<string, string[]>>;
     for (const row of rows.schemaAcls) {
       if (IGNORED_SCHEMAS.has(row.schema)) continue;
-      schemaAcls[row.schema] = parseSchemaAcl(row.acl == null ? '{}' : String(row.acl)) ?? {};
+      schemaAcls[row.schema] = parseSchemaAcl(row.acl == null ? '{}' : String(row.acl)) ?? Object.create(null);
     }
   }
 
@@ -1212,9 +1218,12 @@ export function compareContracts(declared: AuthzContract, live: AuthzContract):
 
 function diffGrants(table: string, d: TableContract, l: TableContract, out: DriftFinding[]): void {
   const grantees = new Set([...Object.keys(d.grants), ...Object.keys(l.grants)]);
+  // Own keys only: a declared contract loaded with JSON.parse is a plain object, where a
+  // grantee the file lacks (`__proto__`, `constructor`) would read an Object.prototype member.
+  const held = (grants: Record<string, string[]>, g: string): string[] => (Object.hasOwn(grants, g) ? grants[g] : []);
   for (const g of grantees) {
-    const dp = (d.grants[g] ?? []).join(',');
-    const lp = (l.grants[g] ?? []).join(',');
+    const dp = held(d.grants, g).join(',');
+    const lp = held(l.grants, g).join(',');
     if (dp !== lp) {
       out.push({ subject: table, kind: 'grant', detail: `grant to ${g}: declared [${dp}], live [${lp}]` });
     }