@everystack/model 0.4.17 → 0.4.18

package/CHANGELOG.md

@@ -0,0 +1,213 @@
+# Changelog
+
+All notable changes to `@everystack/model` are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+
+- automate the version-drift check — a manual note is not a gate
+
+## [0.4.18] - 2026-09-16
+
+### Added
+
+- auto-generated changelogs from conventional commits
+- version-guard the Model-derived wire payloads (provision, converge-ownership, reconcile)
+
+### Fixed
+
+- the shape-pin also covers enum value domains, not just field names
+- symmetric v-prefix in the mismatch message, restore db:provision's --direct detail
+
+## [0.4.17] - 2026-08-15
+
+### Fixed
+
+- compile owner-scoped `manage` to write policies + add `internal` flag for functions
+
+### Documentation
+
+- softDelete was documented nowhere a model author reads
+
+## [0.4.16] - 2026-08-12
+
+### Fixed
+
+- the softDelete guard asked about visibility, not about DELETE
+- close the gate findings — the rule was still one grant short
+
+## [0.4.15] - 2026-08-10
+
+### Added
+
+- defineFunction takes an owner
+- keep the index name the database already has
+- keep the foreign key constraint name too
+- capture GENERATED ALWAYS AS IDENTITY through the round trip
+- a view's owner is a privilege boundary too — declare it, build it
+
+### Fixed
+
+- db:pull reads the search_path, it does not invent one
+
+## [0.4.14] - 2026-08-08
+
+### Added
+
+- rls: false declares a grants-only table — row security as the database holds it
+
+## [0.4.13] - 2026-08-06
+
+### BREAKING CHANGES
+
+- a grant with no policy is spellable, and no longer renders as an ability
+
+### Added
+
+- a live EXECUTE grant is a fact, so let a function record one
+- db:pull renders trigger bindings, as standalone descriptors
+- record a relation's inexpressible grants instead of skipping the object
+
+## [0.4.12] - 2026-08-04
+
+### Added
+
+- writtenBy: 'functions' must have functions, checked at composition
+
+## [0.4.11] - 2026-08-04
+
+### Added
+
+- policyRoles — the policy's audience, not its grantees
+- field.pgType — a verbatim type is its own identity
+- make column grants first-class
+
+### Fixed
+
+- one definition of a public read, and writtenBy stops guessing
+
+## [0.4.10] - 2026-08-02
+
+### Added
+
+- the model can say REFERENCES, TRIGGER, TRUNCATE
+
+## [0.4.9] - 2026-08-02
+
+### Fixed
+
+- db:pull dropped the owner branch of a `public OR mine` read
+
+## [0.4.8] - 2026-08-01
+
+### Added
+
+- the authz vocabulary compiles what it declares
+- a function is identified by its name AND its argument types
+- a role the models cannot name keeps its grants, and is named on every run
+- stripping an undeclared grantee is destructive, and db:check verifies the baseline artifact (cli 0.4.41, model 0.4.7)
+
+### Fixed
+
+- soft-delete visibility is declared, never inferred from a column name
+
+## [0.4.5] - 2026-07-23
+
+### Added
+
+- db schema-move primitive — movedFrom marker → ALTER TABLE SET SCHEMA
+
+## [0.4.4] - 2026-07-17
+
+### Added
+
+- field.json() — the Postgres json type, distinct from jsonb
+
+## [0.4.3] - 2026-07-16
+
+### Added
+
+- canonical-sync artifact verbs (gap B)
+
+## [0.4.2] - 2026-07-16
+
+### Fixed
+
+- array field .default() takes a JS array, not a PG literal
+
+## [0.4.1] - 2026-07-10
+
+### Added
+
+- the loud undefined gate — a missing import is named at define time, never silently dropped
+
+## [0.4.0] - 2026-07-10
+
+### Added
+
+- field.defaultSql() — the raw-default escape hatch (Brick C)
+- the declarative derived layer — descriptor API + rejection rules (Brick B1a)
+- index identity sees everything CREATE INDEX can say (Brick E, read-model-everywhere)
+- typed reads — declared fields emit the derived layer into the generated schema (Brick B6a, read-model-everywhere)
+- descriptors go live in the verbs — the B3 wiring (read-model-everywhere)
+- the B2 gates — the read model is enforced, not just expressible (read-model-everywhere)
+- live drift + doctor — what the content hashes can't see (Brick B4, read-model-everywhere)
+- db:pull renders the derived layer — the consumer's migration tool (Brick B5, read-model-everywhere)
+- retire db/sql — descriptors are the single home (Brick B7, read-model-everywhere)
+- db:generate --dry-run + the journal remembers schema-out (Brick D, read-model-everywhere)
+- db:reconcile --rebaseline — the defHash-verified migration for source re-renders (red-team blocker, read-model-everywhere)
+
+### Fixed
+
+- adoption-path fixes from the red team (read-model-everywhere)
+- reconcile apply hardening — session guard, real CONCURRENTLY fallback (red team, read-model-everywhere)
+- reachability gate mirrors the grant compiler — private models reach their granted roles (red team, read-model-everywhere)
+
+## [0.3.6] - 2026-07-04
+
+### Added
+
+- losing data should be hard — classification, deprecated(), role-gated destructive (brick 9)
+
+## [0.3.5] - 2026-07-04
+
+### Added
+
+- via: transitive-owner RLS — own a child through its parent
+- toDrizzleTable — derive the runtime drizzle table from a Model
+- writtenBy + the FORCE axiom — RLS posture is a model property
+- per-model schema — a model declares the Postgres schema it lives in
+- private — a model can be generated without being an API resource
+- own dist.blobs as a v3 Model — schema + authz
+- own the notification_* tables as Models + array vocabulary
+- derive the FORCE-RLS carveouts from writtenBy — drop the hand-list
+- column-scoped grants + cross-schema FK / index emission
+- db:doctor functions teeth + derive every FORCE carveout
+- defineModule — a package's full DB slice (models + extensions + functions)
+- field.serial, field.real, field.doublePrecision; model 0.3.4
+- table-level renamedFrom — rename intent through the diff (brick 6)
+
+### Documentation
+
+- v3 (0.3.0) documentation review — accurate READMEs + guides
+- correct comments + README to the shipped 0.3.0 reality
+
+## [0.3.0] - 2026-06-27
+
+### Added
+
+- defineModel + handler-config derivation (v3 Phase 0)
+- renamedFrom — the opt-in column rename, so the diff preserves data
+- P3 field vocabulary — numeric, varchar, date
+- P3 enum — CREATE TYPE, pg_enum introspection, round-trip
+- P4a FK referential actions + tougher constraint parser
+- P2.1 table-level constraints — composite unique, multi-col check
+- P2.2 indexes — index() builder, round-trip
+- P4b foreignKey() table-level builder for composite FKs
+
+### Documentation
+
+- P7 add README — the v3 Model on-ramp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/model",
-  "version": "0.4.17",
+  "version": "0.4.18",
   "description": "Declare a table's schema, validation, and authorization once — compiled to migrations, RLS, and handler config",
   "license": "AGPL-3.0-only",
   "publishConfig": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {
@@ -20,6 +21,11 @@
       "source": "./src/drizzle.ts",
       "types": "./src/drizzle.ts",
       "default": "./src/drizzle.ts"
+    },
+    "./wire": {
+      "source": "./src/wire.ts",
+      "types": "./src/wire.ts",
+      "default": "./src/wire.ts"
     }
   },
   "peerDependencies": {

package/src/wire.ts

@@ -0,0 +1,239 @@
+/**
+ * @everystack/model/wire — the Model-derived WIRE CONTRACT.
+ *
+ * Three privileged ops actions take a payload the CLI computes FROM the Models barrel and ships to
+ * a deployed stage's ops Lambda: `db:provision`, `db:converge-ownership` (owner assignments) and
+ * `db:reconcile` (derived-object descriptors). The CLI on an operator's machine and the
+ * `@everystack/cli` bundled inside that Lambda are SEPARATE installs on independent release
+ * trains, so their idea of those payload shapes can drift — a field renamed, reinterpreted, or
+ * added with new required meaning rides through silently and lands as wrong ownership or a wrong
+ * derived object on a real database.
+ *
+ * This module is the fix's two halves:
+ *
+ *   1. THE SHAPES, declared ONCE. `@everystack/model` is the neutral package both sides already
+ *      reach (the CLI depends on it directly; the server reaches it through
+ *      `@everystack/cli/wire`, which re-exports this file). Before this, the CLI built these
+ *      payloads as inline object literals and the server declared its own matching interfaces —
+ *      two independent types that agreed by convention, plus one (`db:reconcile`'s `declared`)
+ *      that was `any[]` on the wire. Now there is one definition and both sides import it.
+ *
+ *   2. THE VERSION, `MODEL_WIRE_CONTRACT`. Types alone cannot police two independently installed
+ *      packages, so every one of those payloads carries `modelContract`, the server refuses on
+ *      anything but EXACT equality, and the CLI refuses before dispatch when a stage's `_health`
+ *      does not advertise the same integer. See MODEL_WIRE_CONTRACT below for the bump rule.
+ *
+ * TYPES AND THE CONSTANT ONLY — no logic lives here. The refusals are enforced where they are
+ * decided: `packages/server/src/model-wire.ts` (the server gate) and
+ * `packages/cli/src/cli/model-wire-lane.ts` (the CLI preflight).
+ *
+ * This is deliberately SEPARATE from `APPLY_CONTRACT_VERSION` (`@everystack/cli/apply`), which
+ * versions db:apply's PERSISTED plan artifact — written by `db:plan --out <file>` and applied
+ * later, possibly much later. This versions an EPHEMERAL payload computed and consumed in one
+ * round trip. Different lifecycles, different numbers; neither may be folded into the other.
+ */
+
+/**
+ * The Model-derived wire-contract version. Hand-bumped, checked for EXACT equality on both sides.
+ *
+ * BUMP IT whenever any type in this file changes shape — a field added, removed, renamed, retyped,
+ * or given a new required meaning. `__tests__/wire-shape.test.ts` pins every field of every type
+ * here and FAILS with that instruction if you change one without bumping, so the bump cannot be
+ * forgotten. That test is what makes exact-equality sustainable.
+ *
+ * Exact equality, never `>=`: a false refusal costs one redeploy (minutes, reversible), a false
+ * accept risks wrong ownership or a wrong derived object on a production database.
+ *
+ * v1 — the first version. Shapes as they stood when the guard was introduced.
+ */
+export const MODEL_WIRE_CONTRACT = 1;
+
+/**
+ * Every Model-derived wire payload carries this. The server refuses a payload whose `modelContract`
+ * is missing or unequal BEFORE it opens a connection; the CLI refuses to dispatch to a stage whose
+ * `_health` does not advertise the same integer.
+ *
+ * Missing is a REFUSAL, never a default: a caller that does not send the field is by definition on
+ * a version that predates the field, which is exactly the skew being guarded.
+ */
+export interface ModelWireEnvelope {
+  /** This CLI's MODEL_WIRE_CONTRACT. Absent = a CLI older than the handshake. */
+  modelContract?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Ownership — the db:provision / db:converge-ownership payloads.
+// ---------------------------------------------------------------------------
+
+/**
+ * One (owner, schema) pair the Models declare for a function/view/matview — the ENACT unit.
+ * Provision grants the operator membership in `owner` and grants `owner` CREATE on `schema`.
+ */
+export interface DeclaredOwner {
+  owner: string;
+  schema: string;
+}
+
+/** The derived-object kinds ownership can be reassigned for. */
+export type AdopteeKind = 'function' | 'view' | 'materialized view';
+
+/**
+ * One declared object to ADOPT — a function/view/matview the Models declare that already exists
+ * live under the wrong owner. Reassigning a SECURITY DEFINER object changes its runs-as identity
+ * at call time, which is why `secdef` rides the wire and why adoption needs `confirm`.
+ */
+export interface Adoptee {
+  /** Reassign target: `api.foo(integer)` for a function, `api.v_report` for a view/matview. */
+  identity: string;
+  schema: string;
+  name: string;
+  kind: AdopteeKind;
+  /** SECURITY DEFINER — functions only; always false for a view/matview. */
+  secdef: boolean;
+  /** The live owner (e.g. `postgres`). */
+  currentOwner: string;
+  /** The owner the Models declare. */
+  declaredOwner: string;
+  body?: string;
+}
+
+/** The `db:provision` payload's Model-derived half (the credentials half is server-local). */
+export interface ProvisionWirePayload extends ModelWireEnvelope {
+  /** The declared schema set, ordered and `public`-trailing — set as the ROLE default search_path. */
+  searchPath?: string[];
+  /** Accepted by the action's payload type; convergence itself runs as db:converge-ownership. */
+  declaredOwners?: DeclaredOwner[];
+  declaredObjects?: Adoptee[];
+  confirm?: boolean;
+}
+
+/** The `db:converge-ownership` payload — ENACT + ADOPT + the reader's read grants. */
+export interface OwnershipWirePayload extends ModelWireEnvelope {
+  declaredOwners?: DeclaredOwner[];
+  declaredObjects?: Adoptee[];
+  confirm?: boolean;
+  adminRole?: string;
+  /** Present = also converge the reader's read grants over `searchPath`. */
+  readerRole?: string;
+  searchPath?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Derived layer — the db:reconcile payload.
+// ---------------------------------------------------------------------------
+
+/** The declared derived kinds. `trigger` and `sql` carry the extra fields their edges need. */
+export type DerivedKind = 'function' | 'view' | 'materialized view' | 'trigger' | 'sql';
+
+/** A statement that belongs to a derived object: its index, comment, or grant. */
+export interface DerivedAttachment {
+  kind: 'index' | 'comment' | 'grant';
+  sql: string;
+}
+
+/**
+ * One compiled derived-object descriptor — the unit `db:reconcile` ships. The CLI's `SourceObject`
+ * IS this type (`packages/cli/src/cli/derived-source.ts` re-exports it), so there is one
+ * definition, not two that agree by convention. Field-by-field documentation lives with the
+ * compiler that produces them; what matters here is that the SHAPE is versioned by
+ * MODEL_WIRE_CONTRACT.
+ */
+export interface DerivedDescriptor {
+  kind: DerivedKind;
+  /** Schema name, defaulted to `public` when unqualified. */
+  schema: string;
+  name: string;
+  /** `schema.name` — the reconciler's join key against the live catalog.
+   *  (Triggers: `schema.table.name` — compound identity, joined against pg_trigger.) */
+  identity: string;
+  /** The CREATE statement as authored (no trailing semicolon). */
+  sql: string;
+  /** Indexes / comments / grants targeting this object, in source order. */
+  attachments: DerivedAttachment[];
+  /** sha256 of the normalized CREATE + attachments — comment/whitespace edits do not change it. */
+  hash: string;
+  /**
+   * sha256 of the normalized CREATE + attachments EXCEPT plain (non-column-scoped) grants — the
+   * "would a rebuild be required" hash. Equal across an authz-only change (plain grants moved, body
+   * unchanged), so the reconciler can route that to a bare GRANT delta instead of a matview rebuild.
+   * Column-scoped grants stay IN (attacl not introspected → they must rebuild). `hash` stays the
+   * full/stable formula for provenance compat; this is the additional discriminator.
+   */
+  bodyHash: string;
+  /** Source file this object came from (descriptors: the declared-models marker). */
+  file: string;
+  /** Position in the concatenated source — a valid dependency order by convention. */
+  seq: number;
+  /**
+   * kind 'function' only: the declared owning role.
+   *
+   * A SECURITY DEFINER function executes with its OWNER's rights, so this is a privilege
+   * boundary. The applier enacts it by running the CREATE under `SET ROLE <owner>` rather
+   * than following it with `ALTER … OWNER TO`: measured on PG16, once ownership has moved the
+   * builder gets "must be owner of function" on the next `CREATE OR REPLACE`, so the
+   * alter-after form works exactly once and breaks every re-run.
+   */
+  owner?: string;
+  /**
+   * kind 'function' only: the declared `SET search_path`, or the sentinel `'unpinned'`.
+   *
+   * It is already inside `sql`, so this is NOT in the hash and changes no fingerprint. It rides
+   * structurally so the differ can compare the declared pin against the LIVE catalog directly
+   * rather than only against a recorded hash. Without that, `--baseline` records a declared pin
+   * the database does not have and every later check reports zero actions, forever: measured,
+   * and it is how a model came to claim `search_path=pg_catalog` about a database with none
+   * while every gate stayed green.
+   *
+   * `undefined` means NOT DECLARED — a parser-era db/sql object, or an invoker function with no
+   * pin. The comparison is skipped there; absent evidence is not evidence.
+   */
+  searchPath?: string[] | 'unpinned';
+  /** kind 'sql' only: the declared PostgreSQL object kind (`'aggregate'`, …). */
+  objectKind?: string;
+  /** kind 'sql' only: the explicit DROP for kinds whose drop isn't derivable from the name. */
+  drop?: string;
+  /** kind 'trigger' only: the (possibly schema-qualified) table/view the trigger rides. */
+  table?: string;
+  /**
+   * Views/matviews: every declared `dependsOn` ref as an identity (models AND derived),
+   * sorted. B4's dependency drift verifies it against the live catalog's actual edges —
+   * "declared, then verified". Absent on kinds whose live edges pg_depend can't see.
+   */
+  declaredDeps?: string[];
+  /**
+   * kind 'function' only: the relations this function's SIGNATURE names — a `setof(ref)`
+   * return, or an argument/return type spelled as a declared table, view or matview.
+   *
+   * Distinct from `dependsOn`, and the distinction is load-bearing for the from-scratch build.
+   * A body reference is a FORWARD reference the build can defer (`check_function_bodies = off`
+   * is exactly that escape), so a function whose body reads a not-yet-created table still
+   * creates. A SIGNATURE reference is not deferrable: PostgreSQL resolves the return and
+   * argument types when the function is created, so `RETURNS SETOF stats_view.x_row` needs
+   * that view to exist already. `db:build` runs functions ahead of state (an RLS policy's
+   * predicate must resolve the function it calls) and uses this to hold back the ones that
+   * cannot go first; the compiler also orders the function after them.
+   *
+   * RELATIONS only — tables, views, matviews. A signature naming a declared ENUM, domain or
+   * composite type has the same problem and is NOT covered here, so it still fails in the
+   * ahead-of-state pass. Absent/empty means "names no declared relation", never "is safe".
+   *
+   * Not in the hash — it is derived from `sql`, so carrying it moves no fingerprint.
+   */
+  signatureDeps?: string[];
+}
+
+/** The `db:reconcile` payload — the declared derived layer plus the run's mode flags. */
+export interface ReconcileWirePayload extends ModelWireEnvelope {
+  /** The declared derived objects. Was `any[]` on the wire before this contract existed. */
+  declared?: DerivedDescriptor[];
+  /** `{ [newName]: oldName }` — table renames the reconciler must follow. */
+  renamedTables?: Record<string, string>;
+  apply?: boolean;
+  baseline?: boolean;
+  rebaseline?: boolean;
+  rebuild?: boolean;
+  overwriteDrift?: boolean;
+  only?: string[];
+  actor?: string | null;
+  gitRef?: string | null;
+}