@abloatai/ablo 0.6.0 → 0.8.0

package/dist/schema/model.d.ts

@@ -18,7 +18,10 @@
  */
 import { z } from 'zod';
 import type { RelationDef } from './relation.js';
+import type { EntityRole } from './roles.js';
 import { type FieldMeta } from './field.js';
+import { type Tenancy, type ScopedViaRef } from './tenancy.js';
+export type { ScopedViaRef, Tenancy } from './tenancy.js';
 /**
  * Controls when model data is loaded from the server.
  *
@@ -46,18 +49,15 @@ export interface PersistOptions {
     store?: string;
 }
 /**
- * Describes how to scope a table's rows via a parent table. See
- * {@link ModelOptions.scopedVia} for semantics and code emitted.
+ * Declares a membership edge on a join model. See {@link ModelOptions.grants}
+ * for semantics and how the server membership resolver reads it. Both fields
+ * name `belongsTo` relations declared on the same model.
  */
-export interface ScopedViaRef {
-    /** Column on THIS table that points at `parentKey` (e.g. `'team_id'`). */
-    localKey: string;
-    /** Parent table name (e.g. `'team'`, `'member'`). */
-    parentTable: string;
-    /** Column on the parent that `localKey` references. Default: `'id'`. */
-    parentKey?: string;
-    /** Column on the parent holding the tenant id. Default: `'organization_id'`. */
-    parentOrgColumn?: string;
+export interface GrantsRef {
+    /** Relation name pointing at the identity that gains access (e.g. `'user'`). */
+    subject: string;
+    /** Relation name pointing at the scope-root entity (e.g. `'dataroom'`). */
+    scope: string;
 }
 /** Options for model() */
 export interface ModelOptions {
@@ -120,18 +120,64 @@ export interface ModelOptions {
      */
     scopedVia?: ScopedViaRef;
     /**
-     * Template for the sync group this entity lives in. When set, the
-     * participant APIs can derive a transport scope from the entity id.
-     * The single `{id}` placeholder is substituted with the scope id.
+     * 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;
+    /**
+     * 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`).
+     *
+     * 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`).
      *
-     * Example: `syncGroupFormat: 'matter:{id}'` + `scope: { matters: 'acme-q3' }`
-     * yields a capability restricted to `sync_group: ['matter:acme-q3']`.
+     * ```ts
+     * // dataroomMember: { userId, dataroomId }
+     * grants: { subject: 'user', scope: 'dataroom' } // both are relation names
+     * ```
      *
-     * Leave unset for entities that aren't directly scopable (nested
-     * children whose access derives from their parent — e.g. a `redline`
-     * inside a `document` inside a `matter`).
+     * Not needed for org-level access — a `dataroom.organizationId` already routes
+     * via the `org:<id>` group. `grants` is only for sub-org membership.
      */
-    syncGroupFormat?: string;
+    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' })]
+     * ```
+     *
+     * 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[];
     /**
      * Whether clients may issue CREATE/UPDATE/DELETE mutations for this
      * model via the `commit` wire protocol. Default: false.
@@ -272,11 +318,15 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
     /** The actual database table name from Prisma @@map. See {@link ModelOptions.tableName}. */
     readonly tableName?: string;
     /** Whether the table has organization_id. See {@link ModelOptions.orgScoped}. */
-    readonly orgScoped?: boolean;
-    /** Parent-table scoping for rows with no organization_id. See {@link ModelOptions.scopedVia}. */
-    readonly scopedVia?: ScopedViaRef;
-    /** Template for participant scope derivation. See {@link ModelOptions.syncGroupFormat}. */
-    readonly syncGroupFormat?: string;
+    /** Canonical tenancy descriptor — the single source of truth, normalized from
+     *  the `orgScoped`/`scopedVia`/`orgColumn` authoring sugar at build. */
+    readonly tenancy: Tenancy;
+    /** Scope-root marker. See {@link ModelOptions.scope}. */
+    readonly scope?: boolean | string;
+    /** Membership edge granting identity → scope-root access. See {@link ModelOptions.grants}. */
+    readonly grants?: GrantsRef;
+    /** Explicit non-relational record→group roles (normalized to an array). See {@link ModelOptions.entityRoles}. */
+    readonly entityRoles?: readonly EntityRole[];
     /** Whether wire-level CREATE/UPDATE/DELETE is allowed. See {@link ModelOptions.mutable}. */
     readonly mutable?: boolean;
     /** Defer MobX setup until first observer access. See {@link ModelOptions.lazyObservable}. */
@@ -324,3 +374,15 @@ export interface ModelDef<Shape extends z.ZodRawShape = z.ZodRawShape, R extends
 export declare function model<Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, relations?: R, options?: ModelOptions & {
     computed?: C;
 }): ModelDef<Shape, R, C>;
+/**
+ * The sync-group kind a scope-root model mints, or `undefined` when the model
+ * isn't a scope root. `scope: true` derives the kind from the lowercased
+ * typename (`SlideDeck` → `slidedeck`); `scope: 'deck'` sets it explicitly
+ * (the form to use when the wire kind must differ from the typename). One place
+ * so the commit path, the membership resolver, and the participant join-side
+ * all agree on what a record's own group is.
+ */
+export declare function scopeKindOf(def: {
+    scope?: boolean | string;
+    typename?: string;
+}, fallbackKey: string): string | undefined;

package/dist/schema/model.js

@@ -18,6 +18,16 @@
  */
 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';
+/** Normalize the `entityRoles` option (single | array | undefined) to an array. */
+function normalizeEntityRoles(input) {
+    if (!input)
+        return undefined;
+    return Array.isArray(input) ? input : [input];
+}
 // ── Model factory ─────────────────────────────────────────────────────────
 /**
  * Define a model with a Zod shape and optional relations.
@@ -77,9 +87,16 @@ export function model(shape, relations, options) {
         typename: options?.typename,
         persist: options?.persist,
         tableName: options?.tableName,
-        orgScoped: options?.orgScoped,
-        scopedVia: options?.scopedVia,
-        syncGroupFormat: options?.syncGroupFormat,
+        // Normalize all tenancy authoring sugar into the one canonical descriptor.
+        tenancy: resolveTenancy({
+            tenancy: options?.tenancy,
+            orgScoped: options?.orgScoped,
+            scopedVia: options?.scopedVia,
+            orgColumn: options?.orgColumn,
+        }),
+        scope: options?.scope,
+        grants: options?.grants,
+        entityRoles: normalizeEntityRoles(options?.entityRoles),
         mutable: options?.mutable,
         lazyObservable: options?.lazyObservable,
         computed: options?.computed,
@@ -87,3 +104,16 @@ export function model(shape, relations, options) {
         requiredFields: options?.requiredFields,
     };
 }
+/**
+ * The sync-group kind a scope-root model mints, or `undefined` when the model
+ * isn't a scope root. `scope: true` derives the kind from the lowercased
+ * typename (`SlideDeck` → `slidedeck`); `scope: 'deck'` sets it explicitly
+ * (the form to use when the wire kind must differ from the typename). One place
+ * so the commit path, the membership resolver, and the participant join-side
+ * all agree on what a record's own group is.
+ */
+export function scopeKindOf(def, fallbackKey) {
+    if (!def.scope)
+        return undefined;
+    return (typeof def.scope === 'string' ? def.scope : (def.typename ?? fallbackKey)).toLowerCase();
+}

package/dist/schema/relation.d.ts

@@ -62,6 +62,23 @@ export interface BelongsToOptions {
     readonly index?: boolean;
     readonly enrich?: boolean;
     readonly defer?: boolean;
+    /**
+     * Marks the relation's target as this record's **parent** in the Zanzibar/
+     * ReBAC sense — the entity it lives in, that scope inherits *from*. Sync-group
+     * fan-out routes a record into its parent's group (directly, or transitively
+     * up a chain of `parent` edges), so a write reaches everyone subscribed to the
+     * owning entity — the same "access inherits from parent" rule OpenFGA/Zanzibar
+     * and filesystems use.
+     *
+     * A reference (provenance/template pointer like `sourceSlideId`, `templateId`)
+     * must NOT set this, or the record would leak into an unrelated scope.
+     * Optionality is NOT a proxy — many parent FKs are optional (a root folder, an
+     * inbox task) — so the parent edge must be declared, not inferred.
+     *
+     * Reads on the relation: `belongsTo('deck', 'deckId', { parent: true })` —
+     * "the deck is the parent."
+     */
+    readonly parent?: boolean;
 }
 declare const __relationType: unique symbol;
 declare const __relationTarget: unique symbol;

package/dist/schema/roles.d.ts

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+/**
+ * Sync-group roles — the fan-out vocabulary, as typed data.
+ *
+ * A *sync group* is the unit the broadcast layer routes deltas on. On the wire
+ * it's a `kind:id` string, but that serialization is owned entirely by this
+ * module — callers never hand-write `'org:abc'`. Instead they declare a typed
+ * {@link Role} (`kind` + which field supplies the id) and the engine mints the
+ * branded {@link SyncGroup} string via {@link syncGroup}.
+ *
+ * Two reading directions, one shape:
+ *
+ *   • {@link IdentityRole} — "which groups may this *participant* subscribe to?"
+ *     Reads fields off an identity context (`organizationId`, `teamIds`).
+ *
+ *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
+ *     fields off the record itself (`id`, `deckId`), so the server can fan a
+ *     committed delta to the right entity streams regardless of what the
+ *     committer was subscribed to.
+ *
+ * Roles are pure data (no closures) so a `Schema` round-trips through the
+ * control plane and the reconstructed copy behaves identically.
+ */
+/**
+ * The branded wire form of a sync group: `${kind}:${id}`. Branded so a raw
+ * string can't masquerade as one — the only way to produce a `SyncGroup` is
+ * {@link syncGroup}. Because the brand is an intersection it's still assignable
+ * *to* `string`, so existing `string[]` plumbing keeps working unchanged.
+ */
+export declare const syncGroupSchema: z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">;
+export type SyncGroup = z.infer<typeof syncGroupSchema>;
+/**
+ * Mint a sync-group string. The single place the `kind:id` convention lives —
+ * if the wire format ever changes (structured columns, a different separator),
+ * it changes here and nowhere else.
+ */
+export declare function syncGroup(kind: string, id: string): SyncGroup;
+/** Validates how a role pulls ids out of a context (identity or record). */
+export declare const roleSourceSchema: z.ZodObject<{
+    field: z.ZodString;
+    multi: z.ZodBoolean;
+}, z.core.$strip>;
+export type RoleSource = z.infer<typeof roleSourceSchema>;
+/** Back-compat alias — historical name for {@link RoleSource}. */
+export type IdentityRoleSource = RoleSource;
+/** Record-side name for {@link RoleSource}. */
+export type EntityRoleSource = RoleSource;
+/** Free-form context a role reads from. */
+export type RoleContext = Record<string, unknown>;
+/** The identity shape an {@link IdentityRole} reads from. */
+export type IdentityContext = RoleContext;
+/** The record shape an {@link EntityRole} reads from. */
+export type EntityContext = RoleContext;
+/**
+ * A sync-group role: a typed `kind` plus the field that supplies the id. The
+ * wire string is `${kind}:${id}`, built by the engine — there is deliberately
+ * no template/placeholder for the author to get wrong.
+ */
+export declare const roleSchema: z.ZodObject<{
+    kind: z.ZodString;
+    source: z.ZodObject<{
+        field: z.ZodString;
+        multi: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Role = z.infer<typeof roleSchema>;
+/**
+ * Identity-anchored role. Reads an identity field; `kind` names the group.
+ *
+ * ```ts
+ * identityRole({ kind: 'org',  source: 'organizationId' })
+ * identityRole({ kind: 'team', source: 'teamIds', multi: true })
+ * ```
+ */
+export type IdentityRole = Role;
+/**
+ * Record-anchored role. Reads a record field; `kind` names the group. A record
+ * can route to a group keyed by its own `id` *or* a foreign key like `deckId`.
+ *
+ * ```ts
+ * entityRole({ kind: 'deck', source: 'id' })      // a deck → deck:<id>
+ * entityRole({ kind: 'deck', source: 'deckId' })  // a layer → its parent deck
+ * ```
+ */
+export type EntityRole = Role;
+/** Validates an {@link IdentityRole}. */
+export declare const identityRoleSchema: z.ZodType<IdentityRole>;
+/** Validates an {@link EntityRole}. */
+export declare const entityRoleSchema: z.ZodType<EntityRole>;
+/**
+ * Validates a model's `scope` declaration: `true` (kind = typename) or an
+ * explicit lowercase kind string. The same vocabulary the roles use, so the
+ * whole sync-group declaration surface is Zod-validated, not hand-checked.
+ */
+export declare const scopeSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>;
+/**
+ * Validates a model's `grants` membership edge. Both values are relation names
+ * declared on the same model (`subject` → identity, `scope` → scope root); that
+ * the relations actually exist + are `belongsTo` is a cross-field check done in
+ * `defineSchema` where the relation map is in scope.
+ */
+export declare const grantsRefSchema: z.ZodObject<{
+    subject: z.ZodString;
+    scope: z.ZodString;
+}, z.core.$strip>;
+/** Build an identity-anchored role. `multi` defaults to `false`. */
+export declare function identityRole(spec: {
+    readonly kind: string;
+    /** Identity-context field to read. See {@link RoleSource.field}. */
+    readonly source: string;
+    /** Treat the field as an array of ids. See {@link RoleSource.multi}. */
+    readonly multi?: boolean;
+}): IdentityRole;
+/** Build a record-anchored role. `multi` defaults to `false`. */
+export declare function entityRole(spec: {
+    readonly kind: string;
+    /** Record field to read. See {@link RoleSource.field}. */
+    readonly source: string;
+    /** Treat the field as an array of ids. See {@link RoleSource.multi}. */
+    readonly multi?: boolean;
+}): EntityRole;
+/**
+ * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
+ * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
+ * with no `deckId`) is a silent no-op.
+ */
+export declare function extractRoleIds(context: RoleContext, source: RoleSource): readonly string[];
+/** Identity-side name for {@link extractRoleIds}. */
+export declare const extractIdentityIds: typeof extractRoleIds;
+/** Record-side name for {@link extractRoleIds}. */
+export declare const extractEntityIds: typeof extractRoleIds;
+/**
+ * Compose the sync groups an identity may subscribe to, from the schema's
+ * registered {@link IdentityRole}s. Returns `[]` when no role produces an id;
+ * the caller treats `[]` as "no scope", not "match everything".
+ */
+export declare function composeIdentitySyncGroups(identity: IdentityContext, schema: {
+    readonly identityRoles: readonly IdentityRole[];
+}): readonly SyncGroup[];
+/**
+ * Compose the sync groups a record belongs to, from the model's registered
+ * {@link EntityRole}s. Mirror of {@link composeIdentitySyncGroups}, reading the
+ * record instead of an identity. Returns `[]` when the model has no entity
+ * roles (the delta then fans on its base `org:`/`user:` groups only).
+ */
+export declare function composeEntitySyncGroups(record: EntityContext, def: {
+    readonly entityRoles?: readonly EntityRole[];
+}): readonly SyncGroup[];

package/dist/schema/roles.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+/**
+ * Sync-group roles — the fan-out vocabulary, as typed data.
+ *
+ * A *sync group* is the unit the broadcast layer routes deltas on. On the wire
+ * it's a `kind:id` string, but that serialization is owned entirely by this
+ * module — callers never hand-write `'org:abc'`. Instead they declare a typed
+ * {@link Role} (`kind` + which field supplies the id) and the engine mints the
+ * branded {@link SyncGroup} string via {@link syncGroup}.
+ *
+ * Two reading directions, one shape:
+ *
+ *   • {@link IdentityRole} — "which groups may this *participant* subscribe to?"
+ *     Reads fields off an identity context (`organizationId`, `teamIds`).
+ *
+ *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
+ *     fields off the record itself (`id`, `deckId`), so the server can fan a
+ *     committed delta to the right entity streams regardless of what the
+ *     committer was subscribed to.
+ *
+ * Roles are pure data (no closures) so a `Schema` round-trips through the
+ * control plane and the reconstructed copy behaves identically.
+ */
+// ── Sync-group wire form (branded) ──────────────────────────────────────────
+/**
+ * The branded wire form of a sync group: `${kind}:${id}`. Branded so a raw
+ * string can't masquerade as one — the only way to produce a `SyncGroup` is
+ * {@link syncGroup}. Because the brand is an intersection it's still assignable
+ * *to* `string`, so existing `string[]` plumbing keeps working unchanged.
+ */
+export const syncGroupSchema = z
+    .templateLiteral([z.string().regex(/^[a-z][a-z0-9_]*$/), ':', z.string().min(1)])
+    .brand();
+/**
+ * Mint a sync-group string. The single place the `kind:id` convention lives —
+ * if the wire format ever changes (structured columns, a different separator),
+ * it changes here and nowhere else.
+ */
+export function syncGroup(kind, id) {
+    return `${kind}:${id}`;
+}
+// ── Role source ─────────────────────────────────────────────────────────────
+/** Validates how a role pulls ids out of a context (identity or record). */
+export const roleSourceSchema = z.object({
+    /** The context field to read, e.g. `'organizationId'`, `'id'`, `'deckId'`. */
+    field: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'source must be a valid identifier'),
+    /**
+     * When `true`, `field` holds an array; every non-empty string element yields
+     * one group. When `false` (default), `field` is a scalar; truthy → one group.
+     */
+    multi: z.boolean(),
+});
+// ── Role (kind + source — no template string) ───────────────────────────────
+/**
+ * A sync-group role: a typed `kind` plus the field that supplies the id. The
+ * wire string is `${kind}:${id}`, built by the engine — there is deliberately
+ * no template/placeholder for the author to get wrong.
+ */
+export const roleSchema = z.object({
+    kind: z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "deck"'),
+    source: roleSourceSchema,
+});
+/** Validates an {@link IdentityRole}. */
+export const identityRoleSchema = roleSchema;
+/** Validates an {@link EntityRole}. */
+export const entityRoleSchema = roleSchema;
+/**
+ * Validates a model's `scope` declaration: `true` (kind = typename) or an
+ * explicit lowercase kind string. The same vocabulary the roles use, so the
+ * whole sync-group declaration surface is Zod-validated, not hand-checked.
+ */
+export const scopeSchema = z.union([
+    z.boolean(),
+    z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "dataroom"'),
+]);
+/**
+ * Validates a model's `grants` membership edge. Both values are relation names
+ * declared on the same model (`subject` → identity, `scope` → scope root); that
+ * the relations actually exist + are `belongsTo` is a cross-field check done in
+ * `defineSchema` where the relation map is in scope.
+ */
+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'),
+});
+// ── Factories ───────────────────────────────────────────────────────────────
+function makeRole(spec) {
+    return { kind: spec.kind, source: { field: spec.source, multi: spec.multi ?? false } };
+}
+/** Build an identity-anchored role. `multi` defaults to `false`. */
+export function identityRole(spec) {
+    return makeRole(spec);
+}
+/** Build a record-anchored role. `multi` defaults to `false`. */
+export function entityRole(spec) {
+    return makeRole(spec);
+}
+// ── Evaluation ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
+ * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
+ * with no `deckId`) is a silent no-op.
+ */
+export function extractRoleIds(context, source) {
+    const raw = context[source.field];
+    if (source.multi) {
+        return Array.isArray(raw)
+            ? raw.filter((t) => typeof t === 'string' && t.length > 0)
+            : [];
+    }
+    return raw ? [String(raw)] : [];
+}
+/** Identity-side name for {@link extractRoleIds}. */
+export const extractIdentityIds = extractRoleIds;
+/** Record-side name for {@link extractRoleIds}. */
+export const extractEntityIds = extractRoleIds;
+/**
+ * Compose the sync groups an identity may subscribe to, from the schema's
+ * registered {@link IdentityRole}s. Returns `[]` when no role produces an id;
+ * the caller treats `[]` as "no scope", not "match everything".
+ */
+export function composeIdentitySyncGroups(identity, schema) {
+    const out = new Set();
+    for (const role of schema.identityRoles) {
+        for (const id of extractRoleIds(identity, role.source)) {
+            if (id)
+                out.add(syncGroup(role.kind, id));
+        }
+    }
+    return Array.from(out);
+}
+/**
+ * Compose the sync groups a record belongs to, from the model's registered
+ * {@link EntityRole}s. Mirror of {@link composeIdentitySyncGroups}, reading the
+ * record instead of an identity. Returns `[]` when the model has no entity
+ * roles (the delta then fans on its base `org:`/`user:` groups only).
+ */
+export function composeEntitySyncGroups(record, def) {
+    if (!def.entityRoles?.length)
+        return [];
+    const out = new Set();
+    for (const role of def.entityRoles) {
+        for (const id of extractRoleIds(record, role.source)) {
+            if (id)
+                out.add(syncGroup(role.kind, id));
+        }
+    }
+    return Array.from(out);
+}

package/dist/schema/schema.d.ts

@@ -22,105 +22,14 @@
 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, identityRole, entityRole, extractIdentityIds, extractEntityIds, composeIdentitySyncGroups, composeEntitySyncGroups, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } 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). */
 export type CasingFn = (jsField: string) => string;
 /** `defineSchema`'s casing option. Identity when unset. */
 export type Casing = CasingConvention | CasingFn;
-/**
- * The identity shape an {@link IdentityRole} reads from. Free-form
- * `Record<string, unknown>` because each schema chooses what fields
- * its roles read — Ablo's roles read `organizationId`/`userId`/`teamIds`;
- * a tenant model with `regionId`/`customerId` is equally valid. The
- * server hands its resolved identity (whatever shape its AuthProvider
- * returns) straight to {@link extractIdentityIds} without translation.
- */
-export type IdentityContext = Record<string, unknown>;
-/**
- * Open registration of an identity-anchored sync-group. Each role is
- * pure data: (a) a free-form `kind` label (diagnostics only), (b) a
- * `template` with a single `{id}` placeholder, and (c) a `source`
- * declaring which identity field to read and how.
- *
- * Pure data on purpose — no closures. A `Schema` is then JSON-serializable
- * end to end, so the same schema object works in-process AND after being
- * sent to a hosted server over the control plane.
- *
- * No closed enum. A consumer whose identity shape is
- * `{ regionId, customerId }` registers:
- *
- * ```ts
- * defineSchema({ ... }, {
- *   identityRoles: [
- *     identityRole({ kind: 'region',   template: 'region:{id}',   source: 'regionId' }),
- *     identityRole({ kind: 'customer', template: 'customer:{id}', source: 'customerId' }),
- *   ],
- * });
- * ```
- *
- * {@link composeIdentitySyncGroups} walks every registered role and
- * produces the union — no hardcoded `org:` / `user:` / `team:` anywhere in
- * the engine.
- */
-export interface IdentityRole {
-    /** Free-form label for diagnostics/logging. Not parsed. */
-    readonly kind: string;
-    /**
-     * Sync-group template with a single `{id}` placeholder. Substituted
-     * once per id produced from `source`. Example: `'org:{id}'` →
-     * `'org:abc-123'`.
-     */
-    readonly template: string;
-    /** Which identity field to read, and whether it's an array. */
-    readonly source: IdentityRoleSource;
-}
-/**
- * Declarative, JSON-serializable description of how an {@link IdentityRole}
- * pulls ids out of an identity context.
- */
-export interface IdentityRoleSource {
-    /**
-     * The identity-context field to read, e.g. `'organizationId'` or
-     * `'teamIds'`. The value is coerced per {@link multi}.
-     */
-    readonly field: string;
-    /**
-     * When `true`, `field` holds an array; every non-empty string element
-     * yields one sync group. When `false` (default), `field` holds a single
-     * scalar; a truthy value yields exactly one group, falsy yields none.
-     */
-    readonly multi: boolean;
-}
-/**
- * Evaluate an {@link IdentityRoleSource} against an identity context.
- * The whole runtime behaviour of a role lives here, as data-driven logic —
- * `composeIdentitySyncGroups` calls this once per role. Absent or falsy
- * fields yield `[]`, so a role whose field isn't present (e.g. a user with
- * no `teamIds`) is a silent no-op.
- */
-export declare function extractIdentityIds(identity: IdentityContext, source: IdentityRoleSource): readonly string[];
-/**
- * Build an identity-anchored sync-group role. A thin, validated factory
- * over the {@link IdentityRole} data shape — `multi` defaults to `false`.
- *
- * ```ts
- * defineSchema({ ... }, {
- *   identityRoles: [
- *     identityRole({ kind: 'tenant', template: 'org:{id}',  source: 'organizationId' }),
- *     identityRole({ kind: 'member', template: 'team:{id}', source: 'teamIds', multi: true }),
- *   ],
- * });
- * ```
- */
-export declare function identityRole(spec: {
-    readonly kind: string;
-    readonly template: string;
-    /** Identity-context field to read. See {@link IdentityRoleSource.field}. */
-    readonly source: string;
-    /** Treat the field as an array of ids. See {@link IdentityRoleSource.multi}. */
-    readonly multi?: boolean;
-}): IdentityRole;
 /** Options for `defineSchema`. */
 export interface DefineSchemaOptions {
     /**
@@ -289,22 +198,3 @@ export type DeleteId<S extends Schema, ModelName extends keyof S['models']> = {
     id: string;
 };
 export declare function defineSchema<const S extends SchemaRecord>(models: S, options?: DefineSchemaOptions): Schema<S>;
-/**
- * Compose the canonical sync-group set this identity is allowed to
- * subscribe to, derived purely from the schema's registered
- * {@link IdentityRole}s. Walks every role, evaluates its `source` against
- * the identity context via {@link extractIdentityIds}, and substitutes each
- * id into the role's `template`. Output is stable, deduped, and never
- * includes a literal convention string from this function itself — the
- * convention lives 100% in the consumer's schema declaration.
- *
- * Reads only data off the schema (`identityRoles` is pure data), so it works
- * identically on an in-process `Schema` and one reconstructed from JSON on a
- * hosted server.
- *
- * Returns `[]` when the schema has no identity roles registered or when no
- * role's source produces an id. Caller decides what to do with `[]`; the
- * server's intersect-with-requested logic treats it as "no scope" rather
- * than "match everything."
- */
-export declare function composeIdentitySyncGroups(identity: IdentityContext, schema: Pick<Schema, 'identityRoles'>): readonly string[];