@abloatai/ablo 0.6.0 → 0.7.0

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

package/dist/schema/schema.js

@@ -21,6 +21,11 @@
  */
 import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
+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, identityRoleSchema, entityRoleSchema, roleSchema, roleSourceSchema, scopeSchema, grantsRefSchema, } from './roles.js';
 function resolveCasing(fn) {
     if (fn === undefined)
         return (x) => x;
@@ -39,42 +44,6 @@ function resolveCasing(fn) {
 function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
-/**
- * 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 function extractIdentityIds(identity, source) {
-    const raw = identity[source.field];
-    if (source.multi) {
-        return Array.isArray(raw)
-            ? raw.filter((t) => typeof t === 'string' && t.length > 0)
-            : [];
-    }
-    return raw ? [String(raw)] : [];
-}
-/**
- * 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 function identityRole(spec) {
-    return {
-        kind: spec.kind,
-        template: spec.template,
-        source: { field: spec.source, multi: spec.multi ?? false },
-    };
-}
 /**
  * Base fields every synced model gets automatically.
  *
@@ -184,11 +153,15 @@ export function defineSchema(models, options) {
         // (identity) so this is a no-op when `casing` is unset — existing
         // consumers get the same behavior they had before the option landed.
         // When `casing: 'snake_case'` is set, every FK flips to its
-        // snake_case DB column name here and nowhere else. Server-side SQL
-        // compilers read the resolved value directly.
+        // snake_case DB column name here and nowhere else. A field-level
+        // `.from(column)` override wins over the convention, so legacy
+        // columns stay declared in the artifact instead of rediscovered by
+        // SQL compilers. Server-side SQL compilers read the resolved value
+        // directly.
         for (const relName of Object.keys(def.relations)) {
             const rel = def.relations[relName];
-            rel.foreignKeyColumn = casing(rel.foreignKey);
+            const fieldColumn = def.fields[rel.foreignKey]?.column;
+            rel.foreignKeyColumn = fieldColumn ?? casing(rel.foreignKey);
         }
         const typename = def.typename ?? name;
         const persist = def.persist
@@ -196,6 +169,7 @@ export function defineSchema(models, options) {
             : undefined;
         resolvedModels[name] = { ...def, typename, persist };
     }
+    validateSyncGroupSchema(resolvedModels);
     return {
         // Cast back to S: we only added values to optional fields that were
         // already part of ModelDef, so the shape is structurally unchanged.
@@ -205,30 +179,44 @@ export function defineSchema(models, options) {
     };
 }
 /**
- * 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."
+ * Validate the relation-driven sync-group declarations (`scope` / `grants`)
+ * at schema-build time, so a mistyped membership edge fails *here* — with a
+ * Stripe-shaped error (`code` + `param` + `doc_url`) pointing at the exact
+ * declaration — instead of silently mis-routing deltas at runtime.
  */
-export function composeIdentitySyncGroups(identity, schema) {
-    const out = new Set();
-    for (const role of schema.identityRoles) {
-        for (const id of extractIdentityIds(identity, role.source)) {
-            if (id)
-                out.add(role.template.replace('{id}', id));
+function validateSyncGroupSchema(models) {
+    for (const [name, def] of Object.entries(models)) {
+        // Shape-validate the `scope` declaration via the shared Zod schema.
+        if (def.scope !== undefined && !scopeSchema.safeParse(def.scope).success) {
+            throw new AbloValidationError(`Model "${name}": scope kind "${String(def.scope)}" must be a lowercase identifier (e.g. 'dataroom').`, { code: 'schema_scope_kind_invalid', param: `${name}.scope` });
+        }
+        if (!def.grants)
+            continue;
+        // Shape-validate the `grants` edge via the shared Zod schema before the
+        // cross-field (relation-exists / belongsTo) checks below.
+        if (!grantsRefSchema.safeParse(def.grants).success) {
+            throw new AbloValidationError(`Model "${name}": grants must be { subject, scope } naming two relations on this model.`, { code: 'schema_grants_shape_invalid', param: `${name}.grants` });
+        }
+        const relations = def.relations;
+        for (const role of ['subject', 'scope']) {
+            const relName = def.grants[role];
+            const rel = relations?.[relName];
+            if (!rel) {
+                throw new AbloValidationError(`Model "${name}": grants.${role} "${relName}" is not a relation on this model. ` +
+                    `Declare a \`belongsTo\` relation named "${relName}" first.`, { code: 'schema_grants_relation_missing', param: `${name}.grants.${role}` });
+            }
+            if (rel.type !== 'belongsTo') {
+                throw new AbloValidationError(`Model "${name}": grants.${role} "${relName}" must be a \`belongsTo\` relation ` +
+                    `(got "${rel.type}"). A membership edge points at a single subject/scope row.`, { code: 'schema_grants_relation_kind', param: `${name}.grants.${role}` });
+            }
+        }
+        // The scope edge must target a model that is actually a scope root —
+        // otherwise the resolved `<kind>:<id>` group is one nothing fans into.
+        const scopeRel = relations[def.grants.scope];
+        const target = models[scopeRel.target];
+        if (target && !target.scope) {
+            throw new AbloValidationError(`Model "${name}": grants.scope "${def.grants.scope}" targets "${scopeRel.target}", ` +
+                `which is not a scope root. Add \`scope: true\` to the "${scopeRel.target}" model.`, { code: 'schema_grants_target_not_scope_root', param: `${scopeRel.target}.scope` });
         }
     }
-    return Array.from(out);
 }

package/dist/schema/select.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `selectModels` — project a schema down to a subset of its models.
+ *
+ * The Prisma-style "one canonical schema, each app selects what it needs"
+ * primitive. Instead of re-declaring a model's fields in a second schema (which
+ * must then be kept shape-identical by hand), an app picks the models it
+ * subscribes to from the canonical schema. Field shapes, resolved FK columns,
+ * computeds, typenames, and identity roles all come from the source — so a
+ * subset is structurally incapable of drifting from the canonical definition.
+ *
+ * ```ts
+ * import { schema as full } from '@ablo/schema';
+ * import { selectModels } from '@abloatai/ablo/schema';
+ *
+ * // Vault subscribes to identity + dataroom content only.
+ * export const schema = selectModels(full, ['users', 'organizations', 'datarooms', 'folders', 'files']);
+ * ```
+ *
+ * Relations whose target falls outside the selected set are dropped — the
+ * subset only sees its own models. A dropped relation that carries `parent`
+ * scope-inheritance throws instead: silently losing it would mis-route a
+ * record's fan-out, so the selected set must be closed under `parent` edges.
+ */
+import type { Schema, SchemaRecord } from './schema.js';
+export declare function selectModels<S extends SchemaRecord, K extends keyof S & string>(schema: Schema<S>, keys: readonly K[]): Schema<Pick<S, K>>;

package/dist/schema/select.js

@@ -0,0 +1,55 @@
+/**
+ * `selectModels` — project a schema down to a subset of its models.
+ *
+ * The Prisma-style "one canonical schema, each app selects what it needs"
+ * primitive. Instead of re-declaring a model's fields in a second schema (which
+ * must then be kept shape-identical by hand), an app picks the models it
+ * subscribes to from the canonical schema. Field shapes, resolved FK columns,
+ * computeds, typenames, and identity roles all come from the source — so a
+ * subset is structurally incapable of drifting from the canonical definition.
+ *
+ * ```ts
+ * import { schema as full } from '@ablo/schema';
+ * import { selectModels } from '@abloatai/ablo/schema';
+ *
+ * // Vault subscribes to identity + dataroom content only.
+ * export const schema = selectModels(full, ['users', 'organizations', 'datarooms', 'folders', 'files']);
+ * ```
+ *
+ * Relations whose target falls outside the selected set are dropped — the
+ * subset only sees its own models. A dropped relation that carries `parent`
+ * scope-inheritance throws instead: silently losing it would mis-route a
+ * record's fan-out, so the selected set must be closed under `parent` edges.
+ */
+import { AbloValidationError } from '../errors.js';
+export function selectModels(schema, keys) {
+    const keep = new Set(keys);
+    const models = {};
+    const validators = {};
+    for (const key of keys) {
+        const def = schema.models[key];
+        if (!def) {
+            throw new AbloValidationError(`selectModels: "${String(key)}" is not a model in the source schema`, { code: 'invalid_schema', param: String(key) });
+        }
+        // Prune relations whose target isn't in the selected set. A pruned
+        // `parent` edge is a routing error, not a silent drop.
+        const relations = {};
+        for (const [relName, rel] of Object.entries(def.relations)) {
+            if (keep.has(rel.target)) {
+                relations[relName] = rel;
+                continue;
+            }
+            if (rel.options?.parent) {
+                throw new AbloValidationError(`selectModels: model "${String(key)}" has a parent relation "${relName}" → "${rel.target}", ` +
+                    `which is not in the selected set. Include "${rel.target}" so scope inheritance still routes.`, { code: 'invalid_schema', param: `${String(key)}.${relName}` });
+            }
+        }
+        models[key] = { ...def, relations };
+        validators[key] = schema.validators[key];
+    }
+    return {
+        models: models,
+        validators: validators,
+        identityRoles: schema.identityRoles,
+    };
+}

package/dist/schema/serialize.d.ts

@@ -13,8 +13,8 @@
  *
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, orgScoped, scopedVia, bootstrap hints, syncGroupFormat,
- *     persist, autoFill, requiredFields, lazyObservable)
+ *     mutable, orgScoped, scopedVia, bootstrap hints, scope, grants,
+ *     entityRoles, persist, autoFill, requiredFields, lazyObservable)
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)
@@ -25,12 +25,15 @@
  *     `FieldMeta` (the server does no field-shape validation anyway)
  */
 import type { FieldMeta } from './field.js';
-import type { ScopedViaRef, LoadStrategy, PersistOptions, AutoFillRule } from './model.js';
+import type { Tenancy } from './tenancy.js';
+import type { GrantsRef, LoadStrategy, PersistOptions, AutoFillRule } from './model.js';
 import type { RelationType } from './relation.js';
-import { type Schema, type SchemaRecord, type IdentityRole } from './schema.js';
+import { type Schema, type SchemaRecord, type IdentityRole, type EntityRole } from './schema.js';
 /** Current schema-JSON envelope version. Bump on a breaking change to the
- * JSON shape itself (not the user's schema). */
-declare const SCHEMA_JSON_VERSION: 1;
+ * JSON shape itself (not the user's schema). v2 replaced the per-model
+ * `syncGroupFormat` template string with structured `scope`/`grants`/
+ * `entityRoles` (relation-driven sync groups). */
+declare const SCHEMA_JSON_VERSION: 3;
 /** A relation in JSON form. Mirrors the serializable members of {@link RelationDef}. */
 export interface RelationJSON {
     readonly type: RelationType;
@@ -47,11 +50,12 @@ export interface ModelJSON {
     readonly load: LoadStrategy;
     readonly typename: string;
     readonly tableName?: string;
-    readonly orgScoped?: boolean;
-    readonly scopedVia?: ScopedViaRef;
+    readonly tenancy: Tenancy;
+    readonly scope?: boolean | string;
+    readonly grants?: GrantsRef;
+    readonly entityRoles?: readonly EntityRole[];
     readonly bootstrapLimit?: number;
     readonly bootstrapOrderBy?: string;
-    readonly syncGroupFormat?: string;
     readonly mutable?: boolean;
     readonly lazyObservable?: boolean;
     readonly persist?: PersistOptions;

package/dist/schema/serialize.js

@@ -13,8 +13,8 @@
  *
  * What round-trips:
  *   - all model routing/scoping metadata (typename, tableName, load,
- *     mutable, orgScoped, scopedVia, bootstrap hints, syncGroupFormat,
- *     persist, autoFill, requiredFields, lazyObservable)
+ *     mutable, orgScoped, scopedVia, bootstrap hints, scope, grants,
+ *     entityRoles, persist, autoFill, requiredFields, lazyObservable)
  *   - relations (incl. resolved `foreignKeyColumn`)
  *   - field metadata (names + type tags), from which validators are rebuilt
  *   - identity roles (already pure data)
@@ -27,8 +27,10 @@
 import { z } from 'zod';
 import { baseFieldsSchema, } from './schema.js';
 /** Current schema-JSON envelope version. Bump on a breaking change to the
- * JSON shape itself (not the user's schema). */
-const SCHEMA_JSON_VERSION = 1;
+ * JSON shape itself (not the user's schema). v2 replaced the per-model
+ * `syncGroupFormat` template string with structured `scope`/`grants`/
+ * `entityRoles` (relation-driven sync groups). */
+const SCHEMA_JSON_VERSION = 3;
 // ── Serialize ────────────────────────────────────────────────────────────────
 function relationToJSON(rel) {
     const options = rel.options;
@@ -54,11 +56,12 @@ function modelToJSON(def) {
         // so it is present on a built ModelDef; fall back defensively anyway.
         typename: def.typename ?? '',
         tableName: def.tableName,
-        orgScoped: def.orgScoped,
-        scopedVia: def.scopedVia,
+        tenancy: def.tenancy,
+        scope: def.scope,
+        grants: def.grants,
+        entityRoles: def.entityRoles,
         bootstrapLimit: def.bootstrapLimit,
         bootstrapOrderBy: def.bootstrapOrderBy,
-        syncGroupFormat: def.syncGroupFormat,
         mutable: def.mutable,
         lazyObservable: def.lazyObservable,
         persist: def.persist,
@@ -157,9 +160,10 @@ function modelFromJSON(json) {
         typename: json.typename,
         persist: json.persist,
         tableName: json.tableName,
-        orgScoped: json.orgScoped,
-        scopedVia: json.scopedVia,
-        syncGroupFormat: json.syncGroupFormat,
+        tenancy: json.tenancy,
+        scope: json.scope,
+        grants: json.grants,
+        entityRoles: json.entityRoles,
         mutable: json.mutable,
         lazyObservable: json.lazyObservable,
         // computed getters are closures and intentionally not serialized; a

package/dist/schema/sugar.d.ts

@@ -73,10 +73,27 @@ export interface SugarOptions<R extends RelationRecord = RelationRecord, C exten
      */
     scopedVia?: ModelOptions['scopedVia'];
     /**
-     * Template for participant scope derivation (e.g. `'matter:{id}'`).
-     * Omit for nested children whose access cascades from a parent.
+     * Override the row-local tenancy column name. See
+     * {@link ModelOptions.orgColumn}.
      */
-    syncGroupFormat?: string;
+    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'];
     /** Max rows loaded during bootstrap. Only applies to `.instant`. */
     bootstrapLimit?: number;
     /** Bootstrap sort order (e.g. `'created_at DESC'`). */

package/dist/schema/sugar.js

@@ -48,7 +48,11 @@ function build(shape, opts, baseline) {
         tableName: opts?.tableName,
         orgScoped: opts?.orgScoped,
         scopedVia: opts?.scopedVia,
-        syncGroupFormat: opts?.syncGroupFormat,
+        orgColumn: opts?.orgColumn,
+        tenancy: opts?.tenancy,
+        scope: opts?.scope,
+        grants: opts?.grants,
+        entityRoles: opts?.entityRoles,
         bootstrapLimit: opts?.bootstrapLimit,
         bootstrapOrderBy: opts?.bootstrapOrderBy,
         persist: opts?.persist,