@sequenceholdings/orm 2.0.0 → 2.1.1

package/README.md

@@ -5,12 +5,18 @@ 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.
 
+Sequence ORM is a workflow-agnostic platform primitive. The compiler and
+runtime own generic schema, policy, migration, and execution contracts;
+deployed namespaces own domain tables and operations. Primitive code must not
+branch on a namespace or product identity. See
+[Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+
 ## Install
 
 Install the CLI and SDK together:
 
 ```bash
-pnpm add -g @sequenceholdings/studio-cli@0.1.27 @sequenceholdings/orm@2.0.0
+pnpm add -g @sequenceholdings/studio-cli@0.3.0 @sequenceholdings/orm@2.1.1
 ```
 
 Create a namespace project:
@@ -32,15 +38,83 @@ seq-studio orm apply . -e <environment-name>
 ```
 
 `generate` writes `schema.graphql`, `operations.manifest.json`, cache policies,
-and typed consumer modules. Commit generated outputs and migrations with the
+and typed consumer modules. Generated SDL may contain up to 16 MiB of UTF-8
+text for the complete namespace; individual authored files retain a 1 MiB cap.
+Registration and reviewed migration exports are bounded to 64 MiB including
+canonical metadata, snapshots, documents, and migration statements.
+
+Commit generated outputs and migrations with the
 source that produced them.
 
+Owned `defineTable` contracts support named `checks` and referential actions
+on enforced `toOne` links or composite `foreignKeys`:
+
+```ts
+const reports = defineTable('reports', {
+  id: t.uuid().primaryKey(),
+  status: t.text().notNull(),
+}, {
+  checks: [{ name: 'reports_status_check', expression: "status IN ('draft', 'active')" }],
+})
+
+const runs = defineTable('runs', {
+  id: t.uuid().primaryKey(),
+  reportId: t.uuid().notNull(),
+}, {
+  links: { report: toOne(reports, { on: 'reportId', enforce: true, onDelete: 'cascade' }) },
+})
+```
+
+Check expressions use a validated subset of PostgreSQL predicates. See
+[database constraints](../../../docs/platform/orm-v2.md#database-integrity-constraints)
+for the supported operators, actions, migration behavior, and limitations.
+
 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
 
+### Guard dependent writes
+
+Mutation roots run in one transaction. To require a conditional write to
+succeed before committing dependent roots, add a fixed row-count assertion:
+
+```graphql
+mutation SaveDeal($id: uuid!, $revision: Int!, $title: String!) {
+  updateDeals(
+    where: { id: { _eq: $id }, revision: { _eq: $revision } }
+    _set: { title: $title }
+    _inc: { revision: 1 }
+  ) @assertAffectedRows(exactly: 1) {
+    returning { id revision }
+  }
+}
+```
+
+This example assumes a `deals` table with `id`, `title`, and integer `revision`
+columns and suitable write policies. The assertion uses the actual SQL write
+count even when `affectedRows` is not selected. A mismatch rolls back **all**
+roots and the operation journal with HTTP 409 `MUTATION_PRECONDITION_FAILED`.
+Missing, policy-hidden, and stale matches receive the same generic error.
+Ordinary mutations without this directive keep zero-match success semantics.
+
+`exactly` must be a literal integer from 0 through 2147483647. It cannot be a
+caller variable. Only mutation root fields may carry the directive, and a
+guarded root cannot also use `@include` or `@skip`. Policy and constraint
+failures retain their existing errors. This does not add automatic retries:
+when the domain permits retry, reread authorized state and recompute the write.
+Every writer affecting the invariant must participate in the revision protocol.
+
+Guarded operations use **IR v2**; older runtimes reject them. Upgrade the host
+compiler and executor together before registering guarded documents, regenerate
+SDL with the matching SDK, and only then activate consumers. Existing unguarded
+operations keep their IR v1 and operation hashes. This source addition requires
+a matching SDK release and host rollout; it is not a claim that the published
+Preview version already supports it.
+
+### Execute by name
+
 Operations execute by their generated manifest name, never by sending GraphQL
 text or SQL:
 
@@ -53,6 +127,10 @@ seq-studio orm execute GetOpenDeals . \
 `variables.json` must contain a JSON object. The platform validates variables,
 operation requirements, and row policies as the signed-in caller.
 
+Execute uses the `/_data/v2` endpoint by default. Set
+`SEQUENCE_ORM_ATLAS_EXECUTE_V2=1` to opt into Atlas's `/api/data/v2` endpoint.
+This client rollout switch does not bypass server feature flags or authorization.
+
 ## Public exports
 
 - `@sequenceholdings/orm/authoring` — namespace, table, policy, and view DSL
@@ -60,3 +138,17 @@ operation requirements, and row policies as the signed-in caller.
 - `@sequenceholdings/orm/drizzle` — supported Drizzle helpers for views
 - `@sequenceholdings/orm/codegen` — GraphQL Code Generator preset used by a
   scaffolded namespace
+
+The `@sequenceholdings/orm/client` entry point contains the persisted-operation
+executor and error types without importing compiler, migration, Node builtins,
+or third-party runtime dependencies. It is safe to bundle into browser and
+function applications. The Managed Functions SDK bundles this entry point so
+deployed functions do not install ORM's authoring dependencies.
+
+Use `createArtifactOrmExecutor` from `@sequenceholdings/artifact-studio` inside
+an authenticated Artifact, and `createFunctionOrmExecutor` from
+`@sequenceholdings/managed-functions/orm` inside a Managed Function. Both accept
+the generated JSON manifest and preserve the caller's governed data access.
+The host adapters supply authentication; they do not grant namespace access or
+register operations. Do not extract CLI credentials or invent a browser token
+provider to wire a generated client.