@sequenceholdings/orm 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @sequenceholdings/orm
+
+Sequence ORM — the OpCo data layer. Tables, links, row policies, and actions are defined in YAML per namespace; the platform compiles them into Postgres tables with forced row-level security in the OpCo's Lakebase, serves them through the Atlas Data API, and generates a typed client.
+
+Design source of truth: the "Sequence ORM: OpCo Data Layer" Notion page.
+
+This package is the pure core — no Atlas imports, no database access:
+
+- `schema/` — zod schemas for the YAML definition surface (tables, columns, links, indexes, policies, actions)
+- `migrations/` — the committed migration workspace (`orm diff`, offline `--check` verification, destructive-statement classification)
+- `predicate/` — the policy expression grammar (`claim('…')`, `capability('…')`, comparisons, `and`/`or`/`not`)
+- `compiler/` — predicate AST and identifier/literal helpers → SQL fragments for policies and claims
+- `engine/` — namespace definitions → ordered migration plans (`hint` / `ddl` / `security` / `function`) plus drizzle-kit snapshots for the registry. Each declared action compiles to a `SECURITY INVOKER` Postgres function (`orm_<ns>.action_<name>`) created at apply, so the invoke path is a single `SELECT`; writes never run as client-rewritten statements. Apply also `PREPARE`s each executes statement so Postgres validates its columns/types (plpgsql function bodies defer that to first invoke), failing the apply on a bad reference. `executes` may be one statement or an ordered list (run atomically); `returns:` makes the function `RETURNS TABLE(...)` and hands back the RETURNING rows.
+- `loader.ts` — a namespace directory of `*.yaml` files → validated `NamespaceDefinition`
+- `hash.ts` — canonical content hash (key-order-insensitive) used for content-addressed registry versions
+- `client/` (`@sequenceholdings/orm/client`) — typed Data API client; fetch-only, no node builtins. `createOrmClient` acts as the caller (session bearer, or a managed function's delegated user token — the default); `createServiceOrmClient` is the loudly-named escalation that acts as a function's own per-function service account. See the `sequence-orm` skill → "two consumer modes".
+- `codegen/` — derives the client's wire types from the definitions; `apply` refreshes `types.gen.ts` on every successful run (there is no separate `generate` command — one verb owns the loop)
+
+Deploy with `seq-studio orm …` (see `@sequenceholdings/studio-cli`):
+
+```
+seq-studio orm apply [dir] -e <env>            # the everyday loop: author the migration, register, apply, refresh types
+seq-studio orm apply [dir] --dry-run -e <env>  # rehearse the migration on a copy of the env's real data, then discard it (no real apply)
+seq-studio orm plan [dir] -e <env>             # offline dry run — compiled SQL + registry status (no database, no writes)
+seq-studio orm diff [dir] [--check]            # write / verify the committed migration (--check is the offline CI gate)
+seq-studio orm validate [dir]                  # parse + content hash + the offline migration gate
+```
+
+`--dry-run` registers the version and rehearses its plan on a throwaway
+copy-on-write fork of the environment's live data — proving the migration
+survives real rows (a `NOT NULL` onto populated data, a constraint existing
+rows violate) — then discards the fork without applying for real.
+
+```bash
+pnpm --filter @sequenceholdings/orm build
+pnpm --filter @sequenceholdings/orm test
+```