@abloatai/ablo 0.12.0 → 0.14.0

package/dist/schema/tenancy.js

@@ -1,22 +1,36 @@
 /**
  * Tenancy — the single source of truth for how a model's rows are scoped to a
- * tenant. This replaces three scattered mechanisms (a hardcoded
- * `organization_id` literal, an `orgScoped` boolean, and a `scopedVia` ref) with
- * one Zod discriminated union, resolved in one place and consumed everywhere
- * (provision/RLS, introspection, runtime, CLI).
+ * tenant. There are exactly two layers here, and keeping them separate is the
+ * whole point:
  *
- * Why a union: every consumer used to re-derive "how is this table scoped?" from
- * a flag plus a literal — a missed branch was a silent cross-tenant scoping bug.
- * A discriminated union makes the `switch` exhaustive, so the type system holds
- * the isolation boundary, and the physical column name lives in exactly one
- * place (the `column` variant) instead of being hardcoded across the codebase.
+ *   1. The CANONICAL form — {@link Tenancy}, a Zod discriminated union. This is
+ *      what every consumer (provision/RLS, introspection, runtime, CLI) reads
+ *      and what crosses the wire in `ModelJSON`. One shape, exhaustively
+ *      switchable, so the type system holds the isolation boundary.
+ *   2. The AUTHORING form — {@link PolicyInput}, the `policy: { by }` option a
+ *      schema author writes. The name follows Postgres/Supabase RLS vocabulary:
+ *      a `policy` is the rule that decides which rows a tenant may read.
+ *      {@link resolvePolicy} maps it to the canonical {@link Tenancy} at
+ *      `model()`-build time (much as Supabase's `create policy` compiles to a
+ *      `pg_policy` row), so the authoring vocabulary never reaches the wire or
+ *      any consumer.
+ *
+ * Why one authoring option (`policy`) instead of the old
+ * `orgScoped`/`scopedVia`/`orgColumn` trio: those three were synonyms for one
+ * decision ("how is this row scoped?"), and the most dangerous of them
+ * (`orgScoped: false`) silently exposed a whole table cross-tenant. Collapsing
+ * them into a single discriminated union makes the opt-out (`{ by: 'none' }`) a
+ * loud, deliberate branch instead of a falsy flag — one concept, one name.
  */
 import { z } from 'zod';
 /** Default physical tenancy column. The ONLY place this literal is canonical. */
 export const DEFAULT_ORG_COLUMN = 'organization_id';
 /**
  * Scope a table's rows through a parent table (for rows that carry no tenancy
- * column of their own — e.g. `slide_layers` → slide → deck → org).
+ * column of their own — e.g. `slide_layers` → slide → deck → org). This is the
+ * CANONICAL `parent` payload; authors write the friendlier {@link PolicyInput}
+ * `{ by: 'parent', fk, parent }` shape, normalized into this by
+ * {@link resolvePolicy}.
  */
 export const scopedViaRefSchema = z.object({
     /** Column on THIS table pointing at the parent (e.g. `'team_id'`). */
@@ -28,7 +42,7 @@ export const scopedViaRefSchema = z.object({
     /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
     parentOrgColumn: z.string().min(1).optional(),
 });
-/** How a model's rows are scoped to a tenant. */
+/** How a model's rows are scoped to a tenant — the CANONICAL, wire-facing form. */
 export const tenancySchema = z.discriminatedUnion('kind', [
     /** Row-local tenancy column (default name `organization_id`, overridable). */
     z.object({ kind: z.literal('column'), column: z.string().min(1) }),
@@ -38,19 +52,75 @@ export const tenancySchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('none') }),
 ]);
 /**
- * Normalize authoring sugar into the one canonical {@link Tenancy}. Called once,
- * at model-build, so `ModelDef`/`ModelJSON` and every consumer see only
- * `tenancy`. Precedence: explicit `tenancy` → `scopedVia` → `orgScoped:false` →
- * column (default or `orgColumn`).
+ * The AUTHORING form of tenancy — what a schema author writes as the model's
+ * `policy` option (Postgres/Supabase RLS vocabulary: a policy is the rule that
+ * scopes which rows a tenant may read). A Zod discriminated union on `by`, so
+ * the three branches are mutually exclusive and the dangerous opt-out
+ * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
+ *
+ * - `{ by: 'column' }`            — row-local tenancy column (the default).
+ *   `column` overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`)
+ *   and `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are overrides.
+ * - `{ by: 'none' }`             — genuinely global / reference data. ⚠ Makes
+ *   the whole table readable cross-tenant — only correct for tenant-less tables.
+ */
+export const policyInputSchema = z.discriminatedUnion('by', [
+    z.object({
+        by: z.literal('column'),
+        /** Override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
+        column: z.string().min(1).optional(),
+    }),
+    z.object({
+        by: z.literal('parent'),
+        /** Column on THIS table pointing at the parent (e.g. `'slideId'`). */
+        fk: z.string().min(1),
+        /** Parent table name (e.g. `'slides'`). */
+        parent: z.string().min(1),
+        /** Column on the parent that `fk` references. Default `'id'`. */
+        parentKey: z.string().min(1).optional(),
+        /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+        parentTenantColumn: z.string().min(1).optional(),
+    }),
+    z.object({ by: z.literal('none') }),
+]);
+/**
+ * Normalize the authoring {@link PolicyInput} into the one canonical
+ * {@link Tenancy}. Called once, at `model()`-build, so `ModelDef`/`ModelJSON`
+ * and every consumer see only the canonical union. Omitting `policy` defaults
+ * to a row-local `organization_id` column.
+ */
+export function resolvePolicy(input) {
+    if (!input)
+        return { kind: 'column', column: DEFAULT_ORG_COLUMN };
+    switch (input.by) {
+        case 'column':
+            return { kind: 'column', column: input.column ?? DEFAULT_ORG_COLUMN };
+        case 'parent':
+            return {
+                kind: 'parent',
+                via: {
+                    localKey: input.fk,
+                    parentTable: input.parent,
+                    parentKey: input.parentKey,
+                    parentOrgColumn: input.parentTenantColumn,
+                },
+            };
+        case 'none':
+            return { kind: 'none' };
+    }
+}
+/**
+ * Read the canonical {@link Tenancy} off an already-built model def (or parsed
+ * `ModelJSON`), defaulting to a row-local `organization_id` column when absent.
+ *
+ * This is the READ-side helper — consumers (provision/RLS, membership resolver,
+ * DDL, CLI) call it to get a model's tenancy without re-deriving the default in
+ * each place. It is NOT the authoring normalizer; that's {@link resolveIsolation}.
  */
-export function resolveTenancy(input) {
-    if (input.tenancy)
-        return input.tenancy;
-    if (input.scopedVia)
-        return { kind: 'parent', via: input.scopedVia };
-    if (input.orgScoped === false)
-        return { kind: 'none' };
-    return { kind: 'column', column: input.orgColumn ?? DEFAULT_ORG_COLUMN };
+export function resolveTenancy(def) {
+    return def.tenancy ?? { kind: 'column', column: DEFAULT_ORG_COLUMN };
 }
 /** The physical tenancy column for a column-scoped model, else `null`. */
 export function tenancyColumn(t) {

package/dist/server/commit.d.ts

@@ -58,11 +58,16 @@ export interface CommitContext {
      */
     onBehalfOf?: ParticipantRef | null;
     /**
-     * FK to AgentCapabilityRoot.capabilityId. Non-null for agent / system commits
-     * authorized by a Biscuit; null for human-direct commits. Embedded in every
-     * delta so the audit chain "delta → capability → human" is one FK hop.
+     * Scoped credential id. Non-null for agent / system commits when the
+     * authorizing credential is known; null for human-direct commits.
      */
     capabilityId?: string | null;
+    /**
+     * Human user id at the root of the delegated authority chain. Stored directly
+     * on `sync_deltas` so audit triggers never need to join mutable credential
+     * tables while appending the hash chain.
+     */
+    delegationChainRootUserId?: string | null;
     /**
      * ApiKey row id when the caller authenticated with an API key. Used by the
      * idempotency cache and usage attribution. Null for session / capability

package/docs/api.md

@@ -124,10 +124,11 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
 | `id` | string | Unique identifier for the claim. |
 | `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
-| `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `reason` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
 | `heldBy` | string | Participant id holding the claim. |
 | `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
-| `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
+| `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
+| `expiresAt` | number | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
 
 ```json
 {
@@ -135,10 +136,10 @@ coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
   "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
   "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:report-writer",
   "participantKind": "agent",
-  "expiresAt": "1716580000000"
+  "expiresAt": 1716580000000
 }
 ```
 
@@ -175,12 +176,12 @@ Reads never block on a claim — to wait for a row to free up, `claim({ id })` i
 const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
-  claim.action;
+  claim.reason;
 }
 
 const handle = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'editing',
+  reason: 'editing',
   ttl: '2m',
 });
 await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });

package/docs/cli.md

@@ -24,18 +24,23 @@ direct-connector commands are tagged **Direct Postgres**.
 
 `ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
 **log in** or **create an account** and approve, and the CLI provisions a
-**test + live key pair** (90-day, restricted) and stores them locally. This
-mirrors `stripe login`.
+**test + live key pair** (90-day) and stores them locally. The test key is a
+sandbox `sk_test_` key; the live key is a restricted `rk_live_` key (read-only
+observation — `logs`, `status`), so a stolen config can't write to production.
+This mirrors `stripe login`.
 
 | Command                  | What it does                                                               |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
+| `ablo login --project <slug>` | Same, but scope (and mint) the pair to a project, and make it active. |
 | `ablo logout`            | Remove the stored keys.                                                    |
 | `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
 | `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
-Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
-log in — set `ABLO_API_KEY`, which always overrides the stored key.
+Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project
+then environment; the non-secret `config.json` holds only the active mode and
+project. In **CI**, don't log in — set `ABLO_API_KEY`, which always overrides
+the stored key.
 
 ## Test vs live
 
@@ -47,6 +52,39 @@ the sandbox by design.
 The schema, however, is **shared** across the org — pushing a schema (from
 either environment) defines the same models sandbox and production see; only the rows differ.
 
+## Projects
+
+An org can have multiple **projects**, each with its own isolated keys, schema,
+and data. Keys are scoped to a project **at mint** and never re-scoped, so the
+CLI keeps a separate credential profile per project — Stripe's
+`login --project-name` model. The active project (set with `projects use`)
+selects which profile every command authenticates with.
+
+| Command                       | What it does                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `ablo projects list`          | List the org's projects (marks the active one and the org-default).                |
+| `ablo projects create <slug>` | Create a project (`--name "Display Name"`). Its keys/schema/data are isolated.     |
+| `ablo projects use <slug>`    | Switch the active project. `ablo projects use default` returns to the org-default. |
+| `ablo login --project <slug>` | Mint and store a key pair for a project, and make it active.                       |
+
+Because keys are fixed to a project, `projects use` only changes which profile
+is active — it never re-scopes an existing key. Switch to a project you haven't
+logged into yet and the CLI tells you to mint one:
+
+```bash
+npx ablo projects use war-room
+#   ✓ now targeting project war-room (prj_…)
+#   No key stored for this project yet — run `ablo login --project war-room` to mint one.
+
+npx ablo login --project war-room   # mints + stores its key pair, keeps it active
+```
+
+If you run a project-scoped command (`push`, `dev`) while the active project has
+no key — but other projects do — the CLI **refuses** rather than silently
+deploying with the wrong project's credential, and names the fix
+(`ablo login --project <slug>`). In CI, an explicit `ABLO_API_KEY` bypasses
+profiles entirely: it acts in whatever project it was minted for.
+
 ## Commands
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
@@ -54,6 +92,7 @@ either environment) defines the same models sandbox and production see; only the
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
 | `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
 | `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |

package/docs/client-behavior.md

@@ -146,7 +146,7 @@ the latest row, then hands you the fresh row — so you can't overwrite a change
 see. Options on the claim:
 
 - default `claim` waits in the fair queue and re-reads before handing you the row;
-- `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
+- `{ queue: false }` rejects with `AbloClaimedError` instead of queuing;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
@@ -166,7 +166,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloValidationError` | Invalid input or unsupported request shape. |
 | `AbloServerError` | Server-side 5xx. Retry with backoff if the operation is idempotent. |
 | `AbloStaleContextError` | Write was based on stale `readAt` state. Re-read and retry. |
-| `AbloClaimedError` | An active claim conflicted with `{ wait: false }`, the queue was too deep, or a claim wait timed out. |
+| `AbloClaimedError` | An active claim conflicted with `{ queue: false }`, the queue was too deep, or a claim wait timed out. |
 
 ```ts
 import { AbloClaimedError } from '@abloatai/ablo';

package/docs/coordination.md

@@ -72,23 +72,23 @@ a model row. It's what `claim.state()` returns and what observers render.
 | `id` | `string` | The claim id (distinct from the target row id). |
 | `status` | `ClaimStatus` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'`. `active` = the holder; `queued` = waiting in line behind it. The other three are terminal states you only see on a claim you just finished — `committed` (released after a successful write), `expired` (TTL lapsed), `canceled` (released early). |
 | `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
-| `action` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `reason` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. Serialized on the wire as `action`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
 | `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
 | `position` | `number?` | 0-based place in the FIFO line — present only when `status: 'queued'` (`0` = next behind the holder). |
-| `createdAt` | `string?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
-| `expiresAt` | `string` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
+| `createdAt` | `number?` | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
+| `expiresAt` | `number` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
 
 ```jsonc
 {
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
-  "createdAt": "1748160000000",
-  "expiresAt": "1748160030000"
+  "createdAt": 1748160000000,
+  "expiresAt": 1748160030000
 }
 ```
 
@@ -129,9 +129,9 @@ so two claimers can't both think they won.
 | name | type | required | description |
 |---|---|---|---|
 | `id` | `string` | yes | The row id — same id as `retrieve` / `update`. |
-| `options.action` | `string` | no | Phase shown to observers (default `'editing'`). |
+| `options.reason` | `string` | no | Phase shown to observers (default `'editing'`). Serialized on the wire as `action`. |
 | `options.field` | `string` | no | Field-level target, for fine-grained claimed-state badges. |
-| `options.wait` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
+| `options.queue` | `boolean` | no | `true` (default) queues and waits for the lease. `false` is fail-fast — if another participant holds the row, reject immediately with `AbloClaimedError('entity_claimed')` instead of queuing (claim-or-skip, for work dedup where waiting would double-process). |
 | `options.maxQueueDepth` | `number` | no | Backpressure: reject with `AbloClaimedError('queue_too_deep')` instead of joining a line already `>= maxQueueDepth` deep. Omit to wait however deep the queue is. |
 | `options.ttl` | `Duration` | no | Crash-cleanup floor. Rarely set — the lease renews while your connection is alive, so it only matters once you go silent. |
 
@@ -209,7 +209,7 @@ is free.
 
 ```ts
 const who = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
-if (who) console.log(`${who.heldBy} is ${who.action}`);
+if (who) console.log(`${who.heldBy} is ${who.reason}`);
 ```
 
 Returns the active claim state when the row is held, or `null` when it's free:
@@ -219,10 +219,10 @@ Returns the active claim state when the row is held, or `null` when it's free:
   "id": "claim_8fJ2",
   "status": "active",
   "target": { "model": "weatherReports", "id": "report_stockholm" },
-  "action": "editing",
+  "reason": "editing",
   "heldBy": "agent:forecaster",
   "participantKind": "agent",
-  "expiresAt": "1748160030000"
+  "expiresAt": 1748160030000
 }
 ```
 
@@ -280,7 +280,7 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', action: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', reason: 'reviewing' });
 const report = claim.data;
 try {
   const ok = await reviewExternally(report);

package/docs/examples/agent-human.md

@@ -47,14 +47,14 @@ export async function markReady(reportId: string) {
   if (!report) return { status: 'not_found' };
 
   try {
-    // wait: false → don't queue behind a current holder. If a human already
+    // queue: false → don't queue behind a current holder. If a human already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
-    // agent yields instead of waiting. Omit it, or pass wait: true, to queue
-    // behind them. action → the label observers see while we work.
+    // agent yields instead of waiting. Omit it, or pass queue: true, to queue
+    // behind them. reason → the label observers see while we work.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      wait: false,
-      action: 'marking_ready',
+      queue: false,
+      reason: 'marking_ready',
     });
     const claimed = claim.data;
 
@@ -120,7 +120,7 @@ export function ReportRow({ report: serverReport }: Props) {
 - The claim is visible to everyone: the UI reads it synchronously with
   `claim.state({ id })`, and it also arrives over the live stream.
 - `claim({ id })` makes writers take turns instead of racing — with
-  `wait: false`, the agent simply yields when a human already holds the row.
+  `queue: false`, the agent simply yields when a human already holds the row.
 - The `update` made while the claim is held is stale-checked automatically, so a human's
   edit landing mid-run rejects the agent's write with a typed
   `AbloStaleContextError` instead of overwriting it.

package/docs/examples/ai-sdk-tool.md

@@ -43,7 +43,7 @@ const updateReport = tool({
     // The claim is released automatically when it goes out of scope.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      action: 'editing',
+      reason: 'editing',
       ttl: '2m',
     });
     const claimed = claim.data;

package/docs/examples/existing-python-backend.md

@@ -37,10 +37,8 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   weatherReports: model({
-    id: z.string(),
     location: z.string(),
     status: z.enum(['pending', 'ready']),
-    updatedAt: z.string(),
   }),
 });
 ```

package/docs/examples/nextjs.md

@@ -57,8 +57,8 @@ import { ablo } from '@/lib/ablo';
 export async function markReady(id: string) {
   await using claim = await ablo.weatherReports.claim({
     id,
-    wait: false,
-    action: 'marking_ready',
+    queue: false,
+    reason: 'marking_ready',
   });
   const claimed = claim.data;
 

package/docs/examples/scoped-agent.md

@@ -19,18 +19,18 @@ import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A deck's rows form the group `deck:<id>` (the kind comes from `scope`).
+    // A deck's rows form the group `deck:<id>` (the kind comes from `groups.root`).
     decks: model(
       { title: z.string() },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A slide has no group of its own. It inherits its deck's group via the
     // `parent` edge, so a slide write reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string(), body: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {

package/docs/examples/server-agent.md

@@ -38,8 +38,8 @@ export async function completeReport(reportId: string) {
 
   await using claim = await ablo.weatherReports.claim({
     id: reportId,
-    wait: false,
-    action: 'completing',
+    queue: false,
+    reason: 'completing',
   });
   const claimed = claim.data;
 
@@ -60,9 +60,9 @@ the server has accepted it.
 
 The two options on the claim:
 
-- `wait: false` — skip this record if another claim is already in progress,
+- `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. (The default queues.)
-- `action: 'completing'` — a human-readable label for what your worker is doing,
+- `reason: 'completing'` — a human-readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
 Because the worker uses the same schema and `claim()` as the UI, its writes sync

package/docs/identity.md

@@ -47,18 +47,20 @@ import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A scope root: its rows form the group `deck:<id>` (kind from `scope`).
+    // A scope root: its rows form the group `deck:<id>` (kind from `groups.root`).
+    // Tenant isolation defaults to a row-local `organization_id` column, so no
+    // `policy` is needed here.
     decks: model(
       { title: z.string(), status: z.enum(['draft', 'published']) },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A child: it has no group of its own; it inherits its deck's group via the
     // `parent` edge. A write to a slide reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {
@@ -208,13 +210,13 @@ You never write a sync-group string for a row. You declare a model's *place* in
 the entity graph and the engine derives the groups its rows fan out on. Three
 declarations, in order of how often you reach for them:
 
-**`scope` — this model is a scope root.** Its rows form a group of their own.
-The kind comes from the model's `typename` by default, or pass a string to set
-it explicitly (use the string form when the wire kind differs from the typename,
-e.g. typename `SlideDeck` but group `deck:<id>`):
+**`groups.root` — this model is a scope root.** Its rows form a group of their
+own. The kind comes from the model's `typename` by default, or pass a string to
+set it explicitly (use the string form when the wire kind differs from the
+typename, e.g. typename `SlideDeck` but group `deck:<id>`):
 
 ```ts
-decks: model({ title: z.string() }, {}, { orgScoped: true, scope: 'deck' });
+decks: model({ title: z.string() }, {}, { groups: { root: 'deck' } });
 // a deck row → group `deck:<id>`
 ```
 
@@ -232,7 +234,7 @@ slides: model(
     deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
     sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
   },
-  { orgScoped: true },
+  {},  // default policy: row-local organization_id
 );
 ```
 
@@ -241,8 +243,8 @@ slides: model(
 > some required FKs are mere references. Containment is a fact only you know, so
 > it's declared, exactly as it is in OpenFGA/Zanzibar.
 
-**`grants` — a membership edge.** On a join model (e.g. `dataroomMember`), it
-says "this row grants a *subject* access to a *scope root*." Both are relation
+**`groups.grants` — a membership edge.** On a join model (e.g. `dataroomMember`),
+it says "this row grants a *subject* access to a *scope root*." Both are relation
 names on the model. The server resolves it at connect time — for user `U`, it
 finds the scope-root groups `U` is a member of and adds them to `U`'s allowed
 set (Linear's `/sync/user_sync_groups`). Use this for sub-org sharing; plain
@@ -255,15 +257,19 @@ dataroomMember: model(
     member: relation.belongsTo('users', 'userId'),
     room: relation.belongsTo('datarooms', 'dataroomId'),
   },
-  { orgScoped: true, grants: { subject: 'member', scope: 'room' } },
+  { groups: { grants: { subject: 'member', scope: 'room' } } },
 );
 ```
 
 For the rare group keyed on a plain field rather than a relation (per-recipient
-inbox fan-out, say), there's an `entityRoles: [entityRole({ kind, source })]`
+inbox fan-out, say), there's a `groups: { roles: [entityRole({ kind, source })] }`
 escape hatch. For rows that inherit *tenancy* (not a sync group) through a
-foreign key without carrying `organization_id`, use `scopedVia` rather than
-`orgScoped: false` — the latter exposes the whole table cross-tenant. See
+foreign key without carrying `organization_id`, use `policy: { by: 'parent', fk,
+parent }` rather than opting out of isolation. The old `orgScoped: false`
+exposed the whole table cross-tenant, so `validate_schema` rejects the removed
+options as `tenancy-option-removed` errors and steers you to `policy: { by:
+'parent' }` (FK inheritance) or, for genuinely global reference data, the
+explicit `policy: { by: 'none' }`. See
 `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## How identity reaches Ablo — the proxy model
@@ -393,8 +399,8 @@ an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
-documents: model({ /* … */ }, {}, { orgScoped: true, scope: 'document' }),
-decks:     model({ /* … */ }, {}, { orgScoped: true, scope: 'deck' }),
+documents: model({ /* … */ }, {}, { groups: { root: 'document' } }),
+decks:     model({ /* … */ }, {}, { groups: { root: 'deck' } }),
 ```
 
 Then a run subscribes only to the entity groups for the rows it works on — a
@@ -484,9 +490,10 @@ an agent pointed at the entities it's working on. You **never hand-write**
    (it returns a participant handle with `.peers`). See
    [Coordination](./coordination.md).
 
-> **`scope` is the schema model option, not a client setting.** `scope: 'deck'`
-> in `model(...)` declares a scope root ([Half 2](#half-2--per-model-scope-row--group)) —
-> it names the group (`deck:<id>`) that the mechanisms above then subscribe to.
+> **`groups.root` is the schema model option, not a client setting.**
+> `groups: { root: 'deck' }` in `model(...)` declares a scope root
+> ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
+> (`deck:<id>`) that the mechanisms above then subscribe to.
 > There is no `Ablo({ scope })` constructor option. The lifecycle filter on
 > [`list()`](./api.md#model-methods) is a separate axis named **`state`**
 > (`'live' | 'archived' | 'all'`, GitHub's open/closed/all), precisely so it

package/docs/index.md

@@ -99,4 +99,3 @@ Three things stay true no matter how you use Ablo:
 - [README](../README.md) — product overview and first example.
 - [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
 - [Changelog](../CHANGELOG.md) — what shipped recently.
-- [Roadmap](./roadmap.md) — what's planned next.