@abloatai/ablo 0.12.0 → 0.14.0

package/dist/schema/index.js

@@ -27,7 +27,7 @@ export { field, indexed, getFieldMeta } from './field.js';
 // Relation builders
 export { relation } from './relation.js';
 // Tenancy — the single source of truth for how a model's rows are tenant-scoped.
-export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
+export { tenancySchema, scopedViaRefSchema, policyInputSchema, resolvePolicy, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, } from './tenancy.js';
 // Database plane — which DB a model's rows live in (`tenant` portable to a BYO
 // customer DB, `control` = Ablo's own). Sibling axis to `tenancy`.
 export { planeSchema, DEFAULT_PLANE } from './plane.js';
@@ -46,7 +46,7 @@ export { model, scopeKindOf, } from './model.js';
 // falls back to sensible defaults. See sugar.ts for the full pattern.
 export { mutable, readOnly } from './sugar.js';
 // Schema definition + type inference
-export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, syncGroupInputSchema, isSyncGroupInput, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, groupsInputSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
 // Schema projection — derive an app's subset from one canonical schema.

package/dist/schema/model.d.ts

@@ -18,10 +18,10 @@
  */
 import { z } from 'zod';
 import type { RelationDef } from './relation.js';
-import type { EntityRole } from './roles.js';
+import type { EntityRole, GroupsInput } from './roles.js';
 import { type FieldMeta } from './field.js';
-import { type Tenancy, type ScopedViaRef } from './tenancy.js';
-export type { ScopedViaRef, Tenancy } from './tenancy.js';
+import { type Tenancy, type PolicyInput } from './tenancy.js';
+export type { ScopedViaRef, Tenancy, PolicyInput } from './tenancy.js';
 import { type SchemaPlane } from './plane.js';
 /**
  * Controls when model data is loaded from the server.
@@ -95,49 +95,27 @@ export interface ModelOptions {
      */
     tableName?: string;
     /**
-     * Whether this model's table has an `organization_id` column. Default: true.
-     * When false, the bootstrap/read query omits the `WHERE organization_id = $1`
-     * tenant filter for this model.
+     * **Axis 1 — row-access policy (tenant isolation / RLS).** Decides who may
+     * *read* a row at all. Named after Postgres/Supabase, where a `policy` is the
+     * rule that scopes which rows a tenant sees. A discriminated union on `by` —
+     * one option replacing the old `orgScoped`/`scopedVia`/`orgColumn` trio:
      *
-     * ⚠ SECURITY — `orgScoped: false` makes the table GLOBALLY READABLE: every
-     * client of every tenant sees every row. It is ONLY correct for genuinely
-     * tenant-less tables (the `organizations` table itself, global lookups). If
-     * rows belong to a tenant through a foreign key but this table has no
-     * `organization_id` of its own, use {@link scopedVia} INSTEAD — reaching for
-     * `orgScoped: false` there silently exposes the entire table cross-tenant.
-     */
-    orgScoped?: boolean;
-    /**
-     * Scope rows via a parent table when THIS table has no
-     * `organization_id` column of its own, but rows still belong to a
-     * tenant via a foreign key (e.g. `memberRoles.member_id → member.id`,
-     * `teamMember.team_id → team.id`, `users.id ← member.user_id`).
-     *
-     * Emits, in place of the missing `organization_id = $1` clause:
-     *
-     *   WHERE <table>.<localKey> IN
-     *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-     *
-     * Use this INSTEAD of `orgScoped: false` for any `load: 'instant'`
-     * model whose rows would otherwise leak cross-tenant on bootstrap —
-     * dropping the filter entirely exposes the entire DB to every client.
+     * - `{ by: 'column' }` — row-local tenancy column (the DEFAULT when omitted).
+     *   `column` overrides the name (default `organization_id`).
+     * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key
+     *   when THIS table has no tenancy column of its own (e.g. `slide_layers` →
+     *   slide → deck → org). Emits, in place of `organization_id = $1`:
+     *   `WHERE <table>.<fk> IN (SELECT <parentKey> FROM <parent> WHERE
+     *   <parentTenantColumn> = $1)`. Use this for any `load: 'instant'` child
+     *   table that would otherwise leak cross-tenant on bootstrap.
+     * - `{ by: 'none' }` — genuinely global / reference data (the `organizations`
+     *   table itself, global lookups). ⚠ Makes the whole table readable
+     *   cross-tenant — only correct for tenant-less tables. Because it's an
+     *   explicit, named branch (not a falsy flag) it can't be reached by accident.
      *
-     * Identifiers must match the regular `[a-zA-Z_][a-zA-Z0-9_]*` shape;
-     * the SQL compiler validates them to keep this away from injection
-     * paths.
+     * Normalized into the canonical {@link Tenancy} by `resolvePolicy` at build.
      */
-    scopedVia?: ScopedViaRef;
-    /**
-     * Override the physical tenancy column name (default `organization_id`).
-     * Authoring sugar — normalized into the canonical {@link tenancy} descriptor.
-     */
-    orgColumn?: string;
-    /**
-     * Canonical tenancy descriptor. You normally don't set this — `orgScoped`,
-     * `scopedVia`, and `orgColumn` are normalized into it at build time. Set it
-     * directly only to author the union form explicitly.
-     */
-    tenancy?: Tenancy;
+    policy?: PolicyInput;
     /**
      * Which database plane this model's rows live in. `tenant` (default) =
      * the tenant data plane, emitted into a customer's BYO/dedicated DB by
@@ -146,53 +124,29 @@ export interface ModelOptions {
      */
     plane?: SchemaPlane;
     /**
-     * Marks this model as a **scope root** — a model that forms a sync group of
-     * its own. A scope-root record lives in the group `<kind>:<id>`, where `kind`
-     * defaults to the lowercased `typename` (so a `Deck` → `deck:<id>`). Pass a
-     * string to override the kind explicitly (`scope: 'matter'`).
-     *
-     * Replaces the old `syncGroupFormat` template string: there is no `{id}`
-     * placeholder to author — the engine mints the branded {@link SyncGroup} from
-     * `(kind, id)`. Child models inherit a root's group via their `belongsTo`
-     * relations (a `document` with `dataroomId` fans into `dataroom:<id>`), so
-     * only the root declares anything.
-     */
-    scope?: boolean | string;
-    /**
-     * Declares this model as a **membership edge** that grants an identity access
-     * to a scope root — the relation-driven equivalent of "this user can see that
-     * dataroom." Both values are *relation names* already declared on this model:
-     * `subject` is the `belongsTo` to the identity (e.g. a `user`), `scope` is the
-     * `belongsTo` to the scope-root entity (e.g. a `dataroom`).
+     * **Axis 2 — sync-group routing.** Decides which delta *channels* a row fans
+     * into. Orthogonal to {@link policy} (read access). One namespaced object
+     * replacing the old flat `scope`/`grants`/`entityRoles`:
      *
-     * The server's membership resolver reads this at connect time — for identity
-     * `U`, it queries `WHERE <subject FK> = U` and adds `<scopeKind>:<scope FK>`
-     * to the identity's subscribed groups (Linear's `/sync/user_sync_groups`).
+     * - `root` — mark this model a scope root; its records form the group
+     *   `<kind>:<id>` (kind defaults from the lowercased typename, e.g. `Deck` →
+     *   `deck:<id>`; pass a string to override, `root: 'matter'`). Child models
+     *   inherit a root's group via their `belongsTo` relations. Was `scope` —
+     *   renamed so it no longer collides with the old `scopedVia` tenancy sugar.
+     * - `grants` — a membership edge granting an identity access to a scope root.
+     *   Both values name `belongsTo` relations on this model (`subject` → identity,
+     *   `scope` → scope root). Only needed for sub-org sharing.
+     * - `roles` — explicit non-relational record→group roles (the inbox-fan-out
+     *   escape hatch, keyed on a plain field). Was `entityRoles`. One or many.
      *
      * ```ts
      * // dataroomMember: { userId, dataroomId }
-     * grants: { subject: 'user', scope: 'dataroom' } // both are relation names
-     * ```
-     *
-     * Not needed for org-level access — a `dataroom.organizationId` already routes
-     * via the `org:<id>` group. `grants` is only for sub-org membership.
-     */
-    grants?: GrantsRef;
-    /**
-     * Explicit record→group roles for routing that isn't relational — a group
-     * keyed on a plain field rather than the record's own id or a `belongsTo`
-     * scope root. The escape hatch for cases like per-recipient inbox fan-out:
-     *
-     * ```ts
-     * // a message routes to its addressee's inbox, keyed on `toId`
-     * entityRoles: [entityRole({ kind: 'inbox', source: 'toId' })]
+     * groups: { grants: { subject: 'user', scope: 'dataroom' } }
+     * // a message → its addressee's inbox, keyed on `toId`
+     * groups: { roles: [entityRole({ kind: 'inbox', source: 'toId' })] }
      * ```
-     *
-     * Prefer {@link scope} (self group) + `belongsTo` relations (parent groups)
-     * when the routing follows the relation graph — reach for `entityRoles` only
-     * when it genuinely doesn't.
      */
-    entityRoles?: EntityRole | readonly EntityRole[];
+    groups?: GroupsInput;
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
      * model via the `commit` wire protocol. Default: **true** — declaring a

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;