@sequenceholdings/orm 0.1.1 → 0.1.3

package/README.md

@@ -1,11 +1,21 @@
 # @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 — the OpCo data layer. V2 namespaces define managed tables and
+read-only views in TypeScript, compile named GraphQL operations to persisted
+IR, and execute them through the governed Atlas Data API. Legacy v1 YAML
+namespaces remain supported during migration.
 
 Design source of truth: the "Sequence ORM: OpCo Data Layer" Notion page.
 
 This package is the pure core — no Atlas imports, no database access:
 
+- `authoring/` — TypeScript `defineTable` / `defineView` DSL. View queries use
+  Drizzle through `@sequenceholdings/orm/drizzle`; only normalized SQL and
+  dependencies enter canonical JSON.
+- `canonical/` — validated v2 table/view wire contract shared by CLI and Atlas.
+- `compiler-gql/`, `sdl/`, and `ir/` — read/write table operations plus
+  read-only keyed or keyless view queries compiled to persisted operation IR.
+
 - `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`)
@@ -13,7 +23,7 @@ This package is the pure core — no Atlas imports, no database access:
 - `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".
+- `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)
 
 Deploy with `seq-studio orm …` (see `@sequenceholdings/studio-cli`):