@sequenceholdings/orm 2.1.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/orm",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Sequence ORM v2 — TypeScript-defined governed tables and persisted GraphQL operations",
   "license": "UNLICENSED",
   "repository": {
@@ -28,9 +28,14 @@
       "require": "./dist/cli.cjs"
     },
     "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js",
-      "require": "./dist/client.cjs"
+      "import": {
+        "types": "./dist/client.d.ts",
+        "default": "./dist/client.js"
+      },
+      "require": {
+        "types": "./dist/client.d.cts",
+        "default": "./dist/client.cjs"
+      }
     },
     "./ir": {
       "types": "./dist/ir.d.ts",
@@ -85,13 +90,14 @@
     "README.md"
   ],
   "dependencies": {
-    "graphql": "^16.11.0",
-    "jiti": "^2.4.2",
+    "@supabase/pg-parser": "0.1.7",
     "drizzle-kit": "^0.31.9",
     "drizzle-orm": "^0.45.2",
+    "graphql": "^16.11.0",
+    "jiti": "^2.4.2",
     "js-yaml": "^4.3.2",
     "zod": "^4.1.13",
-    "@sequenceholdings/custom-roles-manifest": "0.1.0"
+    "@sequenceholdings/custom-roles-manifest": "0.2.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/codegen-gql/server-fns.cjs

@@ -45,8 +45,8 @@ export async function db${operationName}Full(variables: ${operationName}QueryVar
   return result;
 }`;
   } else if (type === 'mutation') {
-    return `export async function db${operationName}(variables: ${operationName}MutationVariables) {
-  const result = await executeOperation({ op: '${name}', variables });
+    return `export async function db${operationName}(variables: ${operationName}MutationVariables, options: { idempotencyKey?: string } = {}) {
+  const result = await executeOperation({ op: '${name}', variables, ...options });
 
   return result.${resultField};
 }`;

package/templates/orm-namespace/AGENTS.md

@@ -0,0 +1,10 @@
+# Sequence development
+
+Before every development task, read the live documentation for this project's
+target environment. Find the environment's URL with `seq-studio envs list`
+(or the project configuration), then open `<environment-url>/docs`.
+
+Start with that site's `/docs/llms.txt` index and follow the relevant pages as
+needed. The hosted docs are the single source of truth for platform usage;
+do not duplicate their instructions in this file. If docs access is blocked,
+open the same URL in the signed-in browser.

package/templates/orm-namespace/CLAUDE.md

@@ -1,82 +1 @@
-# Sequence ORM namespace
-
-This directory defines ONE Sequence ORM namespace: TypeScript table
-definitions with row-level policies, plus handwritten GraphQL operations.
-`seq-studio orm apply` pushes it to Atlas, which validates, compiles, and
-applies it. Your app never talks to Postgres — it calls the data plane with
-`{ op: <hash>, variables }` through the generated hooks/functions.
-
-## The loop
-
-1. Edit `schema/*.ts` (tables, columns, links, policies) and/or
-   `graphql/**/*.ts` (operations).
-2. `seq-studio orm generate` — refreshes `schema.graphql` + generated types.
-3. `seq-studio orm diff` — preview the migration for a schema change.
-4. `seq-studio orm apply -e <env>` — pushes. Schema changes write a reviewed
-   migration file into `migrations/`; operation-only edits take the fast path
-   (seconds, no migration).
-5. Commit `schema/`, `graphql/`, `schema.graphql`, `generated/`, and
-   `migrations/` together.
-
-## Hard rules
-
-- **Never hand-edit `migrations/`.** Migration files are generated by
-  `seq-studio orm apply`/`diff` and replayed verbatim by the server. Editing
-  or deleting a committed migration breaks the ledger.
-- **Never hand-edit `schema.graphql` or `generated/`.** Both are outputs of
-  `seq-studio orm generate`. To change the API surface, change `schema/*.ts`.
-- **No raw SQL.** There is no query escape hatch: every read/write is a
-  GraphQL document in `graphql/`, compiled at push time. For genuinely exotic
-  multi-statement writes, declare a table `action` — parameterized, gated,
-  audited.
-- **Every table needs row policies.** At minimum declare `read` plus either a
-  legacy `write` policy or split `insert` / `update` policies when create and
-  resolve are different actors. Policies are the row security boundary and are
-  compiled into every operation touching the table. There is no "no policy"
-  fallback — an unrestricted table must say so explicitly (`allow: true`
-  variant or a `true` policy) so the decision is reviewable.
-- **Exactly one `defineNamespace`** (in `sequence.config.ts`), and every
-  table module must call `defineTable` at import time — the CLI collects
-  registrations by importing your files.
-- **Renames need hints.** Renaming a column or table without
-  `.renamedFrom('old_name')` (column) / `renamedFrom` (table config) is a
-  DROP + CREATE — data loss. The diff will refuse ambiguous renames; add the
-  hint instead of forcing.
-- **Capabilities/roles are declared here, granted in the Permissions UI.**
-  Never hardcode user identities in policies; use `claim('sub')` /
-  `claim('org')` and grants.
-
-## Policy DSL quick reference
-
-```
-author_sub = claim('sub')                 -- row value vs caller claim
-org = claim('org') and status = 'open'    -- boolean algebra
-exists(deal, org = claim('org'))          -- traverse a declared link
-capability('deals-read')                  -- boolean grant check
-role('deal-manager')                      -- boolean role check
-```
-
-Variants widen access per grant (permissive union):
-
-```ts
-policies: {
-  read: {
-    default: "author_sub = claim('sub')",
-    variants: [
-      { when: "capability('deals-read')", policy: "org = claim('org')" },
-      { when: "role('deal-manager')", allow: true },
-    ],
-  },
-}
-```
-
-## GraphQL operations
-
-- Named operations only; one export per document; gate with
-  `@requires(capability: "…")` / `@requires(role: "…")`.
-- Dynamic filters are policy-bounded: `$where: <Table>BoolExp` /
-  `$orderBy` / whole-input write objects are validated against a
-  schema-derived whitelist and AND-ed with the table policy at runtime —
-  they can never widen access.
-- Joins follow declared links (`toOne` / `toMany` / `toPlatformUser`) — there
-  are no ad-hoc joins at query time. Declare the link, then select through it.
+@AGENTS.md

package/templates/orm-namespace/codegen.preset.d.cts

@@ -0,0 +1,7 @@
+import type { CodegenConfig } from '@graphql-codegen/cli'
+
+// The runtime shim loads the package's preset object. Derive its type from the
+// installed CLI so this declaration follows the consumer's codegen contract.
+type ConfiguredOutput = Exclude<CodegenConfig['generates'][string], unknown[]>
+declare const preset: Exclude<ConfiguredOutput['preset'], string | undefined>
+export = preset

package/templates/orm-namespace/codegen.ts

@@ -1,4 +1,5 @@
 import type { CodegenConfig } from '@graphql-codegen/cli'
+import preset from './codegen.preset.cjs'
 
 /**
  * graphql-codegen config. `seq-studio orm generate` writes ./schema.graphql
@@ -14,7 +15,7 @@ const config: CodegenConfig = {
   documents: ['graphql/**/*.ts'],
   generates: {
     './generated/': {
-      preset: './codegen.preset.cjs',
+      preset,
     },
   },
 }

package/templates/orm-namespace/graphql/example/queries.ts

@@ -4,9 +4,10 @@
  * variables }` — never query text, never SQL. Type names come from the
  * generated `schema.graphql` (`seq-studio orm generate`).
  *
- * Gate an operation with `@requires(capability: "…")` or
- * `@requires(role: "…")` — checked before execution, on top of the
- * table policies that are always compiled in.
+ * Gate an operation with `@requires(capability: "…")` — checked before
+ * execution, on top of the table policies that are always compiled in.
+ * Check capabilities, not roles: roles are created in Atlas and can change
+ * there.
  */
 
 export const GetOpenDeals = /* GraphQL */ `

package/templates/orm-namespace/package.json

@@ -11,7 +11,8 @@
   },
   "dependencies": {
     "@apollo/client": "^3.11.0",
-    "@sequenceholdings/orm": "^2.0.0",
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "@sequenceholdings/orm": "^2.2.0",
     "graphql": "^16.11.0"
   },
   "devDependencies": {

package/templates/orm-namespace/schema/tables.ts

@@ -8,7 +8,8 @@ import { defineEnum, defineTable, t, toMany, toOne, toPlatformUser } from '@sequ
  *
  * Every table carries its own row-level policies. The policy DSL:
  *   - `claim('sub')` / `claim('org')` — the caller's identity claims
- *   - `capability('x')` / `role('y')` — boolean grants, resolved per caller
+ *   - `capability('x')` — boolean grant, resolved per caller (check
+ *     capabilities, not roles: roles are created in Atlas and can change)
  *   - `exists(link, <predicate>)` — traverse a declared link
  *   - variants: `default` applies to everyone; each variant WIDENS access
  *     when its `when` guard matches (permissive union — grants only ever
@@ -39,7 +40,7 @@ export const deals = defineTable(
         default: "author_sub = claim('sub')",
         variants: [
           { when: "capability('deals-read')", policy: "org = claim('org')" },
-          { when: "role('deal-manager')", allow: true },
+          { when: "capability('deals-admin')", allow: true },
         ],
       },
       write: "author_sub = claim('sub')",

package/templates/orm-namespace/sequence.config.ts

@@ -3,9 +3,10 @@ import { defineNamespace } from '@sequenceholdings/orm/authoring'
 /**
  * The namespace config — exactly one per directory.
  *
- * Capabilities and roles are DECLARED here (verbatim custom-roles grammar);
- * who HOLDS them is granted later in the Permissions UI (FGA), never in code.
- * Table policies reference them with `capability('…')` / `role('…')`.
+ * Capabilities are DECLARED here (verbatim custom-roles grammar) — the
+ * contract your policies check with `capability('…')`. Roles that bundle
+ * them are created in Atlas (the namespace's Roles tab), and who HOLDS them
+ * is granted there too, never in code.
  */
 export default defineNamespace({
   // Rename me: the namespace becomes your Postgres schema (orm_<namespace>).
@@ -13,18 +14,13 @@ export default defineNamespace({
   description: 'Describe what this namespace stores and who uses it.',
   capabilities: {
     roles: {
-      definitions: {
-        'deal-manager': {
-          description: 'Full access to every deal in the namespace',
-          default: false,
-          inherits: [],
-          grants: ['deals-read'],
-        },
-      },
       capabilities: {
         'deals-read': {
           description: 'Read all deals in the caller org (instead of author-only)',
         },
+        'deals-admin': {
+          description: 'Read every deal in the namespace, in any org',
+        },
       },
     },
     uses: [],