@abloatai/ablo 0.6.0 → 0.7.0

package/dist/schema/diff.d.ts

@@ -50,8 +50,14 @@ export interface IndexChange {
     readonly from: boolean;
     readonly to: boolean;
 }
+/** Physical column-name transition for a stable logical field. */
+export interface FieldColumnChange {
+    readonly from: string;
+    readonly to: string;
+}
 /** The facets of a single column that changed (Atlas-style bitmask, as data). */
 export interface FieldChanges {
+    readonly column?: FieldColumnChange;
     readonly type?: FieldTypeChange;
     readonly nullability?: NullabilityChange;
     readonly enumValues?: EnumValuesChange;

package/dist/schema/diff.js

@@ -65,8 +65,19 @@ function diffEnumValues(from, to) {
         return undefined;
     return { added, removed };
 }
-function diffField(prev, next) {
+function camelToSnake(identifier) {
+    return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+function columnNameOf(fieldName, meta) {
+    return meta.column ?? camelToSnake(fieldName);
+}
+function diffField(prevFieldName, nextFieldName, prev, next) {
     const changes = {};
+    const prevColumn = columnNameOf(prevFieldName, prev);
+    const nextColumn = columnNameOf(nextFieldName, next);
+    if (prevColumn !== nextColumn) {
+        changes.column = { from: prevColumn, to: nextColumn };
+    }
     if (prev.type !== next.type) {
         changes.type = { from: prev.type, to: next.type, cast: classifyCast(prev.type, next.type) };
     }
@@ -112,9 +123,16 @@ function diffModelFields(model, prev, next, fieldRenames) {
         const prevMeta = prev.fields[prevName];
         if (!prevMeta)
             continue;
-        const changes = diffField(prevMeta, nextMeta);
-        if (changes)
+        const changes = diffField(prevName, name, prevMeta, nextMeta);
+        if (changes?.column && renameByNewName.has(name)) {
+            // A hinted logical field rename already emits `rename_field`, whose
+            // lowering renames the physical column when needed. Do not emit a
+            // second `alter_field.column` for the same transition.
+            delete changes.column;
+        }
+        if (changes && Object.keys(changes).length > 0) {
             steps.push({ kind: 'alter_field', model, field: name, changes });
+        }
     }
     // Dropped (present in prev, not in next, and not renamed away).
     for (const name of Object.keys(prev.fields)) {

package/dist/schema/field.d.ts

@@ -31,6 +31,11 @@ export interface FieldMeta {
     isOptional: boolean;
     /** Whether the field was marked indexed via `.indexed()`. */
     isIndexed: boolean;
+    /**
+     * Physical database column name override. When absent, SQL layers derive
+     * the column from the field name using the active casing convention.
+     */
+    column?: string;
     /** For enums: the allowed values. */
     enumValues?: readonly string[];
 }
@@ -73,27 +78,21 @@ export declare function inferFieldMetaFromZod(schema: z.ZodType): FieldMeta;
  * `model.ts:inferMetaFromZod`.
  */
 export declare function resolveFieldMeta(schema: z.ZodType): FieldMeta;
+export type FieldBuilder<T extends z.ZodType> = T & {
+    indexed(): FieldBuilder<T>;
+    from(column: string): FieldBuilder<T>;
+};
 export declare const field: {
     /** String field */
-    readonly string: () => z.ZodString & {
-        indexed(): z.ZodString;
-    };
+    readonly string: () => FieldBuilder<z.ZodString>;
     /** Number field */
-    readonly number: () => z.ZodNumber & {
-        indexed(): z.ZodNumber;
-    };
+    readonly number: () => FieldBuilder<z.ZodNumber>;
     /** Boolean field */
-    readonly boolean: () => z.ZodBoolean & {
-        indexed(): z.ZodBoolean;
-    };
+    readonly boolean: () => FieldBuilder<z.ZodBoolean>;
     /** Date field */
-    readonly date: () => z.ZodDate & {
-        indexed(): z.ZodDate;
-    };
+    readonly date: () => FieldBuilder<z.ZodDate>;
     /** Enum field with constrained string values */
-    readonly enum: <const T extends readonly [string, ...string[]]>(values: T) => z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never> & {
-        indexed(): z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_2 ? { [k in keyof T_2]: T_2[k]; } : never>;
-    };
+    readonly enum: <const T extends readonly [string, ...string[]]>(values: T) => FieldBuilder<z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>>;
     /**
      * JSON field. Three call shapes:
      *
@@ -124,11 +123,9 @@ export declare const field: {
      * deck.metadataJson.icon  // 'presentation' (typed, with default)
      * ```
      */
-    readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> & {
-        indexed(): z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
-    };
+    readonly json: <T extends z.ZodType = z.ZodUnknown>(schemaOrShape?: T | z.ZodRawShape) => FieldBuilder<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     /** Indexed string field (shorthand for `field.string().indexed()`). */
-    readonly id: () => z.ZodString;
+    readonly id: () => FieldBuilder<z.ZodString>;
 };
 /** Mark a Zod schema as indexed for fast lookups (function form). */
 export declare function indexed<T extends z.ZodType>(schema: T): T;

package/dist/schema/field.js

@@ -142,7 +142,15 @@ export function inferFieldMetaFromZod(schema) {
         current instanceof z.ZodArray ||
         current instanceof z.ZodRecord ||
         current instanceof z.ZodUnion ||
-        current instanceof z.ZodUnknown) {
+        current instanceof z.ZodUnknown ||
+        // `z.custom<T>()` is an opaque, structurally-uninspectable blob —
+        // by construction the engine can't see its shape, which is exactly
+        // the JSON-blob pattern (ProseMirror docs, LayerData/LayerStyle maps,
+        // chart specs). Classifying it as `'string'` (the fallthrough default)
+        // gave these fields deep MobX observability instead of the intended
+        // `observable.ref` (see Ablo.ts registerProperty), producing the
+        // microtask-storm + nested-reactivity-drift bug on live updates.
+        current instanceof z.ZodCustom) {
         type = 'json';
     }
     return { type, isOptional, isIndexed: false, enumValues };
@@ -169,39 +177,44 @@ export function resolveFieldMeta(schema) {
         return attached;
     return inferFieldMetaFromZod(schema);
 }
-// ── Chainable field builders ──────────────────────────────────────────────
-//
-// Each builder returns the underlying Zod schema (so `z.object(shape)` still
-// works) with `.indexed()` added as a chainable method. `.optional()` and
-// `.nullable()` still come from Zod itself and preserve the description.
-/** Add `.indexed()` to a Zod schema without disturbing its type. */
-function withIndexed(schema, baseMeta) {
-    const described = schema.describe(encodeMeta({ ...baseMeta, isIndexed: false }));
-    described.indexed = () => {
-        return schema.describe(encodeMeta({ ...baseMeta, isIndexed: true }));
+function assertColumnName(column) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,62}$/.test(column)) {
+        throw new Error(`field.from(): invalid column identifier ${JSON.stringify(column)}`);
+    }
+}
+/** Add sync-engine chain methods to a Zod schema without disturbing its type. */
+function withFieldMethods(schema, meta) {
+    const described = schema.describe(encodeMeta(meta));
+    described.indexed = () => withFieldMethods(schema, { ...meta, isIndexed: true });
+    described.from = (column) => {
+        assertColumnName(column);
+        return withFieldMethods(schema, { ...meta, column });
     };
     return described;
 }
+function buildField(schema, baseMeta) {
+    return withFieldMethods(schema, { ...baseMeta, isIndexed: false });
+}
 export const field = {
     /** String field */
     string() {
-        return withIndexed(z.string(), { type: 'string' });
+        return buildField(z.string(), { type: 'string' });
     },
     /** Number field */
     number() {
-        return withIndexed(z.number(), { type: 'number' });
+        return buildField(z.number(), { type: 'number' });
     },
     /** Boolean field */
     boolean() {
-        return withIndexed(z.boolean(), { type: 'boolean' });
+        return buildField(z.boolean(), { type: 'boolean' });
     },
     /** Date field */
     date() {
-        return withIndexed(z.date(), { type: 'date' });
+        return buildField(z.date(), { type: 'date' });
     },
     /** Enum field with constrained string values */
     enum(values) {
-        return withIndexed(z.enum(values), { type: 'enum', enumValues: values });
+        return buildField(z.enum(values), { type: 'enum', enumValues: values });
     },
     /**
      * JSON field. Three call shapes:
@@ -245,7 +258,7 @@ export const field = {
             // Plain object shape → wrap in z.object() for the sub-property pattern
             inner = z.object(schemaOrShape);
         }
-        return withIndexed(inner, { type: 'json' });
+        return buildField(inner, { type: 'json' });
     },
     /** Indexed string field (shorthand for `field.string().indexed()`). */
     id() {

package/dist/schema/index.d.ts

@@ -21,12 +21,15 @@
  * ```
  */
 export { z } from 'zod';
-export { field, indexed, getFieldMeta, type FieldMeta } from './field.js';
+export { field, indexed, getFieldMeta, type FieldBuilder, type FieldMeta } from './field.js';
 export { relation, type RelationDef, type RelationType } from './relation.js';
-export { model, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, } from './model.js';
+export { tenancySchema, scopedViaRefSchema, resolveTenancy, tenancyColumn, DEFAULT_ORG_COLUMN, type Tenancy, type ScopedViaRef, type TenancyInput, } from './tenancy.js';
+export { model, scopeKindOf, type ModelDef, type ModelOptions, type LoadStrategy, type PersistOptions, type RelationRecord, type GrantsRef, } from './model.js';
 export { mutable, readOnly, type SugarOptions } from './sugar.js';
-export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, type IdentityRole, type IdentityContext, identityRole, extractIdentityIds, type IdentityRoleSource, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, type Schema, type SchemaRecord, type InferModel, type InferCreate, type InferModelNames, type BaseModelFields, type InsertValue, type UpsertValue, type UpdateValue, type DeleteId, type DefineSchemaOptions, type Casing, type CasingConvention, type CasingFn, composeEntitySyncGroups, type IdentityRole, type IdentityContext, type IdentityRoleSource, type EntityRole, type EntityContext, type EntityRoleSource, type RoleSource, type RoleContext, type SyncGroup, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, type SchemaJSON, type ModelJSON, type RelationJSON, } from './serialize.js';
-export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
+export { selectModels } from './select.js';
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, type ProvisionPlan, type MigrationPlan, } from './ddl.js';
+export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, type BackfillValue, type MigrationStep, type FieldChanges, type FieldColumnChange, type FieldTypeChange, type NullabilityChange, type EnumValuesChange, type IndexChange, type CastSafety, type FieldType, type RenameHints, type MigrationSignal, type MigrationClassification, type WarningCode, type BlockerCode, } from './diff.js';
 export { generateTypes } from './generate.js';
 export { query, defineQueries, type QueryDef, type QueryRecord, type Queries, type InferQueryInput, type InferQueryResult, } from './queries.js';

package/dist/schema/index.js

@@ -26,17 +26,23 @@ export { z } from 'zod';
 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';
 // Model builder
-export { model, } from './model.js';
+export { model, scopeKindOf, } from './model.js';
 // Intent-first shorthand: `mutable.lazy({...})` and friends. Read the
 // safety posture and load shape off the verb tokens; everything else
 // 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, identityRole, extractIdentityIds, } from './schema.js';
+export { defineSchema, composeIdentitySyncGroups, composeEntitySyncGroups, identityRole, entityRole, extractIdentityIds, extractEntityIds, syncGroup, syncGroupSchema, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './schema.js';
 // Schema ⇄ JSON (control-plane transport for hosted multi-tenant)
 export { serializeSchema, parseSchema, toSchemaJSON, fromSchemaJSON, schemaHash, } from './serialize.js';
-// Schema diff + migration planning (pure; SQL emission is server-side)
+// Schema projection — derive an app's subset from one canonical schema.
+export { selectModels } from './select.js';
+// Schema → Postgres DDL (pure; shared by the hosted server and the CLI)
+export { generateProvisionPlan, generateMigrationPlan, appSchemaName, camelToSnake, q, sqlType, } from './ddl.js';
+// Schema diff + migration planning (pure; SQL emission lowered by ddl.ts)
 export { diffSchema, classifyMigration, classifyCast, isAutoApplicable, isBlockerResolved, unresolvedBlockers, } from './diff.js';
 // Schema → TypeScript type emission (the `generate` half; pure)
 export { generateTypes } from './generate.js';

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[];