@sequenceholdings/orm 0.1.2 → 2.0.0

package/README.md

@@ -1,37 +1,62 @@
 # @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.
+Sequence ORM v2 is a Preview SDK for TypeScript-defined governed data
+namespaces. You define tables, policies, and named GraphQL operations in source
+control; the platform compiles them into persisted operations and enforces the
+caller's access on every execution.
 
-Design source of truth: the "Sequence ORM: OpCo Data Layer" Notion page.
+## Install
 
-This package is the pure core — no Atlas imports, no database access:
+Install the CLI and SDK together:
 
-- `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 the platform service account attached to the function (its manifest's top-level `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)
+```bash
+pnpm add -g @sequenceholdings/studio-cli@0.1.27 @sequenceholdings/orm@2.0.0
+```
 
-Deploy with `seq-studio orm …` (see `@sequenceholdings/studio-cli`):
+Create a namespace project:
 
+```bash
+seq-studio orm init lending
+cd lending
+pnpm install
 ```
-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
+
+## Everyday workflow
+
+```bash
+# Edit sequence.config.ts, schema/*.ts, and graphql/**/*.ts.
+seq-studio orm generate .
+seq-studio orm validate .
+seq-studio orm plan . -e <environment-name>
+seq-studio orm apply . -e <environment-name>
 ```
 
-`--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.
+`generate` writes `schema.graphql`, `operations.manifest.json`, cache policies,
+and typed consumer modules. Commit generated outputs and migrations with the
+source that produced them.
+
+Use `apply --dry-run` to rehearse a migration against a disposable copy of the
+target environment's data. `apply --no-create` refuses to provision a missing
+namespace, which is useful for deployment checks.
+
+## Execute persisted operations
+
+Operations execute by their generated manifest name, never by sending GraphQL
+text or SQL:
 
 ```bash
-pnpm --filter @sequenceholdings/orm build
-pnpm --filter @sequenceholdings/orm test
+seq-studio orm execute GetOpenDeals . \
+  --variables-file variables.json \
+  -e <environment-name>
 ```
+
+`variables.json` must contain a JSON object. The platform validates variables,
+operation requirements, and row policies as the signed-in caller.
+
+## Public exports
+
+- `@sequenceholdings/orm/authoring` — namespace, table, policy, and view DSL
+- `@sequenceholdings/orm/client` — persisted-operation client utilities
+- `@sequenceholdings/orm/drizzle` — supported Drizzle helpers for views
+- `@sequenceholdings/orm/codegen` — GraphQL Code Generator preset used by a
+  scaffolded namespace