@abloatai/ablo 0.12.0 → 0.13.0

package/dist/schema/model.js

@@ -20,8 +20,10 @@ import { z } from 'zod';
 import { getFieldMeta, inferFieldMetaFromZod } from './field.js';
 // Tenancy is owned by `tenancy.ts` (single source of truth). `ScopedViaRef` is
 // re-exported so existing `import { ScopedViaRef } from './model'` call sites
-// keep resolving while consumers migrate.
-import { resolveTenancy } from './tenancy.js';
+// keep resolving. Authoring uses the `policy` option (`PolicyInput`, named for
+// Postgres/Supabase RLS), normalized to the canonical `Tenancy` by
+// `resolvePolicy` at build time.
+import { resolvePolicy } from './tenancy.js';
 import { DEFAULT_PLANE } from './plane.js';
 /** Normalize the `entityRoles` option (single | array | undefined) to an array. */
 function normalizeEntityRoles(input) {
@@ -88,17 +90,15 @@ export function model(shape, relations, options) {
         typename: options?.typename,
         persist: options?.persist,
         tableName: options?.tableName,
-        // Normalize all tenancy authoring sugar into the one canonical descriptor.
-        tenancy: resolveTenancy({
-            tenancy: options?.tenancy,
-            orgScoped: options?.orgScoped,
-            scopedVia: options?.scopedVia,
-            orgColumn: options?.orgColumn,
-        }),
+        // Axis 1 — normalize the `policy` authoring option into the one canonical
+        // tenancy descriptor (defaults to a row-local org column).
+        tenancy: resolvePolicy(options?.policy),
         plane: options?.plane ?? DEFAULT_PLANE,
-        scope: options?.scope,
-        grants: options?.grants,
-        entityRoles: normalizeEntityRoles(options?.entityRoles),
+        // Axis 2 — unpack the `groups` routing namespace into the wire fields the
+        // server reads (`scope`/`grants`/`entityRoles` on ModelDef/ModelJSON).
+        scope: options?.groups?.root,
+        grants: options?.groups?.grants,
+        entityRoles: normalizeEntityRoles(options?.groups?.roles),
         mutable: options?.mutable ?? true,
         lazyObservable: options?.lazyObservable,
         computed: options?.computed,

package/dist/schema/roles.d.ts

@@ -137,6 +137,55 @@ export declare const grantsRefSchema: z.ZodObject<{
     subject: z.ZodString;
     scope: z.ZodString;
 }, z.core.$strip>;
+/**
+ * The AUTHORING form of a model's sync-group routing — the `groups: { ... }`
+ * option. One namespaced object collects the three independent routing knobs
+ * that used to be flat, collision-prone model options (`scope` / `grants` /
+ * `entityRoles`). Distinct axis from `policy` (tenant isolation): the policy
+ * decides who may *read* a row, `groups` decides which delta *channels* a row
+ * fans into.
+ *
+ * - `root`   — mark this model a scope root; its records form `<kind>:<id>`
+ *   (kind defaults from typename). Was the flat `scope` option — renamed to
+ *   `root` so it no longer collides with the (now removed) `scopedVia` tenancy
+ *   sugar or the inner `grants.scope` relation name.
+ * - `grants` — a membership edge granting an identity access to a scope root.
+ * - `roles`  — explicit non-relational record→group roles (e.g. inbox fan-out
+ *   keyed on a plain field). Was `entityRoles`. Accepts one role or an array.
+ */
+export declare const groupsInputSchema: z.ZodObject<{
+    root: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    grants: z.ZodOptional<z.ZodObject<{
+        subject: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strip>>;
+    roles: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown>>, z.ZodArray<z.ZodType<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown>>>]>>;
+}, z.core.$strip>;
+export type GroupsInput = z.infer<typeof groupsInputSchema>;
 /** Build an identity-anchored role. `multi` defaults to `false`. */
 export declare function identityRole(spec: {
     readonly kind: string;

package/dist/schema/roles.js

@@ -112,6 +112,27 @@ export const grantsRefSchema = z.object({
     subject: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'grants.subject must name a relation'),
     scope: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'grants.scope must name a relation'),
 });
+/**
+ * The AUTHORING form of a model's sync-group routing — the `groups: { ... }`
+ * option. One namespaced object collects the three independent routing knobs
+ * that used to be flat, collision-prone model options (`scope` / `grants` /
+ * `entityRoles`). Distinct axis from `policy` (tenant isolation): the policy
+ * decides who may *read* a row, `groups` decides which delta *channels* a row
+ * fans into.
+ *
+ * - `root`   — mark this model a scope root; its records form `<kind>:<id>`
+ *   (kind defaults from typename). Was the flat `scope` option — renamed to
+ *   `root` so it no longer collides with the (now removed) `scopedVia` tenancy
+ *   sugar or the inner `grants.scope` relation name.
+ * - `grants` — a membership edge granting an identity access to a scope root.
+ * - `roles`  — explicit non-relational record→group roles (e.g. inbox fan-out
+ *   keyed on a plain field). Was `entityRoles`. Accepts one role or an array.
+ */
+export const groupsInputSchema = z.object({
+    root: scopeSchema.optional(),
+    grants: grantsRefSchema.optional(),
+    roles: z.union([entityRoleSchema, z.array(entityRoleSchema)]).optional(),
+});
 // ── Factories ───────────────────────────────────────────────────────────────
 function makeRole(spec) {
     return { kind: spec.kind, source: { field: spec.source, multi: spec.multi ?? false } };

package/dist/schema/schema.d.ts

@@ -23,7 +23,7 @@ import { z } from 'zod';
 import type { ModelDef, RelationRecord } from './model.js';
 import type { RelationDef } from './relation.js';
 import type { IdentityRole } from './roles.js';
-export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
+export { type IdentityRole, type IdentityRoleSource, type IdentityContext, type EntityRole, type EntityRoleSource, type EntityContext, type RoleSource, type RoleContext, type SyncGroup, type SyncGroupInput, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, type GroupsInput, } from './roles.js';
 /** The set of built-in casing conventions supported by `defineSchema`. */
 export type CasingConvention = 'snake_case' | 'camelCase';
 /** Plug point for custom conventions (e.g. mixed legacy databases). */

package/dist/schema/schema.js

@@ -25,7 +25,7 @@ import { scopeSchema, grantsRefSchema } from './roles.js';
 // Sync-group roles (identity + entity) live in `./roles.js`. Re-exported here
 // so the long-standing `@ablo/schema` / `./schema.js` import paths keep working
 // after the rehome — see roles.ts for the full vocabulary.
-export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
+export { identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './roles.js';
 function resolveCasing(fn) {
     if (fn === undefined)
         return (x) => x;

package/dist/schema/serialize.d.ts

@@ -13,8 +13,10 @@
  *
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, orgScoped, scopedVia, bootstrap hints, scope, grants,
- *     entityRoles, persist, autoFill, requiredFields, lazyObservable)
+ *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
+ *     grants, entityRoles, persist, autoFill, requiredFields, lazyObservable).
+ *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
+ *     `model()`-build; only the canonical wire fields cross here.
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)

package/dist/schema/serialize.js

@@ -13,8 +13,10 @@
  *
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, orgScoped, scopedVia, bootstrap hints, scope, grants,
- *     entityRoles, persist, autoFill, requiredFields, lazyObservable)
+ *     mutable, the canonical `tenancy` descriptor, bootstrap hints, scope,
+ *     grants, entityRoles, persist, autoFill, requiredFields, lazyObservable).
+ *     NOTE: the authoring sugar (`policy`/`groups`) is normalized away at
+ *     `model()`-build; only the canonical wire fields cross here.
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)

package/dist/schema/sugar.d.ts

@@ -63,37 +63,16 @@ export interface SugarOptions<R extends RelationRecord = RelationRecord, C exten
      */
     tableName?: string;
     /**
-     * Whether the table has an `organization_id` column. Default: `true`.
-     * Set `false` for system-scoped tables (subscriptions, teams, etc.).
+     * Row-access policy (tenant isolation / RLS) — who may *read* a row.
+     * Discriminated union on `by` (`column` | `parent` | `none`). See
+     * {@link ModelOptions.policy}.
      */
-    orgScoped?: boolean;
+    policy?: ModelOptions['policy'];
     /**
-     * Scope rows via a parent table when this table has no
-     * `organization_id` column. See {@link ModelOptions.scopedVia}.
+     * Sync-group routing — which delta *channels* a row fans into
+     * (`root` / `grants` / `roles`). See {@link ModelOptions.groups}.
      */
-    scopedVia?: ModelOptions['scopedVia'];
-    /**
-     * Override the row-local tenancy column name. See
-     * {@link ModelOptions.orgColumn}.
-     */
-    orgColumn?: ModelOptions['orgColumn'];
-    /** Canonical tenancy descriptor. See {@link ModelOptions.tenancy}. */
-    tenancy?: ModelOptions['tenancy'];
-    /**
-     * Mark this model a scope root — its records form the group `<kind>:<id>`
-     * (kind defaults from typename). See {@link ModelOptions.scope}.
-     */
-    scope?: ModelOptions['scope'];
-    /**
-     * Membership edge granting identity → scope-root access. Both fields are
-     * relation names on this model. See {@link ModelOptions.grants}.
-     */
-    grants?: ModelOptions['grants'];
-    /**
-     * Explicit non-relational record→group roles (e.g. inbox fan-out keyed on a
-     * field). See {@link ModelOptions.entityRoles}.
-     */
-    entityRoles?: ModelOptions['entityRoles'];
+    groups?: ModelOptions['groups'];
     /** Max rows loaded during bootstrap. Only applies to `.instant`. */
     bootstrapLimit?: number;
     /** Bootstrap sort order (e.g. `'created_at DESC'`). */

package/dist/schema/sugar.js

@@ -46,13 +46,8 @@ function build(shape, opts, baseline) {
         lazyObservable: opts?.lazyObservable ?? baseline.lazyObservable,
         typename: opts?.typename,
         tableName: opts?.tableName,
-        orgScoped: opts?.orgScoped,
-        scopedVia: opts?.scopedVia,
-        orgColumn: opts?.orgColumn,
-        tenancy: opts?.tenancy,
-        scope: opts?.scope,
-        grants: opts?.grants,
-        entityRoles: opts?.entityRoles,
+        policy: opts?.policy,
+        groups: opts?.groups,
         bootstrapLimit: opts?.bootstrapLimit,
         bootstrapOrderBy: opts?.bootstrapOrderBy,
         persist: opts?.persist,

package/dist/schema/sync-delta-row.d.ts

@@ -85,6 +85,7 @@ export declare const deltaAttributionSchema: z.ZodObject<{
         system: "system";
     }>>;
     capabilityId: z.ZodNullable<z.ZodString>;
+    delegationChainRootUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     confirmationState: z.ZodNullable<z.ZodEnum<{
         auto: "auto";
         previewed: "previewed";
@@ -129,6 +130,7 @@ export declare const syncDeltaRowSchema: z.ZodObject<{
         system: "system";
     }>>;
     capabilityId: z.ZodNullable<z.ZodString>;
+    delegationChainRootUserId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     confirmationState: z.ZodNullable<z.ZodEnum<{
         auto: "auto";
         previewed: "previewed";

package/dist/schema/sync-delta-row.js

@@ -67,7 +67,7 @@ export const syncDeltaCoreSchema = z.object({
     createdAt: z.string().optional(),
     transactionId: z.string().nullable(),
 });
-// ── Attribution — `control` plane (→ agent_capability_roots) ──────────────────
+// ── Attribution — `control` plane ─────────────────────────────────────────────
 export const deltaAttributionSchema = z.object({
     /** Legacy single-actor column, derived during the dual-write window. */
     createdBy: z.string().nullable(),
@@ -76,6 +76,7 @@ export const deltaAttributionSchema = z.object({
     onBehalfOfId: z.string().nullable(),
     onBehalfOfKind: participantKindSchema.nullable(),
     capabilityId: z.string().nullable(),
+    delegationChainRootUserId: z.string().nullable().optional(),
     confirmationState: confirmationStateSchema.nullable(),
     backfillProvenance: backfillProvenanceSchema.nullable(),
 });

package/dist/schema/tenancy.d.ts

@@ -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 declare 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 declare const scopedViaRefSchema: z.ZodObject<{
     localKey: z.ZodString;
@@ -25,7 +39,7 @@ export declare const scopedViaRefSchema: z.ZodObject<{
     parentOrgColumn: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ScopedViaRef = z.infer<typeof scopedViaRefSchema>;
-/** 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 declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"column">;
     column: z.ZodString;
@@ -42,25 +56,50 @@ export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "kind">;
 export type Tenancy = z.infer<typeof tenancySchema>;
 /**
- * Ergonomic authoring shortcuts accepted on a model. These are *input only* —
- * `resolveTenancy` normalizes them into the canonical {@link Tenancy} at
- * model-build time, so they never reach the serialized JSON or any consumer.
+ * 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 interface TenancyInput {
-    tenancy?: Tenancy;
-    /** `false` → not tenant-scoped. */
-    orgScoped?: boolean;
-    /** Scope through a parent table. */
-    scopedVia?: ScopedViaRef;
-    /** Override the column name for a column-scoped model. */
-    orgColumn?: string;
-}
+export declare const policyInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    by: z.ZodLiteral<"column">;
+    column: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    by: z.ZodLiteral<"parent">;
+    fk: z.ZodString;
+    parent: z.ZodString;
+    parentKey: z.ZodOptional<z.ZodString>;
+    parentTenantColumn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    by: z.ZodLiteral<"none">;
+}, z.core.$strip>], "by">;
+export type PolicyInput = z.infer<typeof policyInputSchema>;
 /**
- * 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`).
+ * 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 declare function resolveTenancy(input: TenancyInput): Tenancy;
+export declare function resolvePolicy(input?: PolicyInput): Tenancy;
+/**
+ * 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 declare function resolveTenancy(def: {
+    tenancy?: Tenancy;
+}): Tenancy;
 /** The physical tenancy column for a column-scoped model, else `null`. */
 export declare function tenancyColumn(t: Tenancy): string | null;

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

@@ -180,7 +180,7 @@ if (claim) {
 
 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' } });