@abloatai/ablo 0.5.1 → 0.7.0

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,8 +44,14 @@ function resolveCasing(fn) {
 function camelToSnake(identifier) {
     return identifier.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
 }
-/** Base fields every synced model gets automatically */
-const baseFieldsSchema = z.object({
+/**
+ * Base fields every synced model gets automatically.
+ *
+ * Exported (internal) so `parseSchema` can rebuild a model's validator the
+ * same way `defineSchema` does — `baseFieldsSchema.merge(modelSchema)` — when
+ * reconstructing a `Schema` from its JSON form.
+ */
+export const baseFieldsSchema = z.object({
     id: z.string(),
     createdAt: z.date(),
     updatedAt: z.date(),
@@ -142,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
@@ -154,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.
@@ -163,26 +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, calls its `extract` against
- * the identity context, 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.
- *
- * Returns `[]` when the schema has no identity roles registered or
- * when no role's extractor 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 role.extract(identity)) {
-            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

@@ -0,0 +1,96 @@
+/**
+ * Schema ⇄ JSON
+ *
+ * A `Schema` is serializable except for client-only closures (Zod
+ * validators + computed getters). `serializeSchema` emits the plain-data
+ * JSON form; `parseSchema` reconstructs a working `Schema` from it.
+ *
+ * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
+ * type, two representations. A hosted multi-tenant server obtains a tenant's
+ * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
+ * is what travels over the control plane (`ablo schema push`) and is stored
+ * per `(tenant, version)`.
+ *
+ * What round-trips:
+ *   - all model routing/scoping metadata (typename, tableName, load,
+ *     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)
+ *
+ * What does NOT round-trip (client-only, server never needs it):
+ *   - `computed` getters (closures) — dropped
+ *   - exact Zod refinements — rebuilt as permissive validators from
+ *     `FieldMeta` (the server does no field-shape validation anyway)
+ */
+import type { FieldMeta } from './field.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, 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). 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;
+    readonly target: string;
+    readonly foreignKey: string;
+    readonly foreignKeyColumn: string;
+    readonly options?: Record<string, boolean>;
+    readonly orderBy?: string;
+}
+/** A model in JSON form. Everything on {@link ModelDef} except closures. */
+export interface ModelJSON {
+    readonly fields: Record<string, FieldMeta>;
+    readonly relations: Record<string, RelationJSON>;
+    readonly load: LoadStrategy;
+    readonly typename: string;
+    readonly tableName?: string;
+    readonly tenancy: Tenancy;
+    readonly scope?: boolean | string;
+    readonly grants?: GrantsRef;
+    readonly entityRoles?: readonly EntityRole[];
+    readonly bootstrapLimit?: number;
+    readonly bootstrapOrderBy?: string;
+    readonly mutable?: boolean;
+    readonly lazyObservable?: boolean;
+    readonly persist?: PersistOptions;
+    readonly autoFill?: readonly AutoFillRule[];
+    readonly requiredFields?: readonly string[];
+}
+/** The JSON form of a {@link Schema}. The `@ablo schema push` payload. */
+export interface SchemaJSON {
+    readonly v: typeof SCHEMA_JSON_VERSION;
+    readonly models: Record<string, ModelJSON>;
+    readonly identityRoles: readonly IdentityRole[];
+}
+/**
+ * Project a `Schema` to its JSON form. Drops the client-only closures
+ * (validators, `computed`); keeps everything the server and a faithful
+ * rebuild need. The result is plain data — `JSON.stringify`-safe.
+ */
+export declare function toSchemaJSON(schema: Schema<SchemaRecord>): SchemaJSON;
+/** Serialize a `Schema` to a JSON string (the `ablo schema push` payload). */
+export declare function serializeSchema(schema: Schema<SchemaRecord>): string;
+/**
+ * Reconstruct a working `Schema` from its JSON form. Validators are rebuilt
+ * permissively from field metadata (the server never validates field shapes);
+ * `computed` getters are absent. Everything the server reads — routing,
+ * scoping, relations, identity roles — is restored exactly.
+ */
+export declare function fromSchemaJSON(json: SchemaJSON): Schema<SchemaRecord>;
+/** Parse a `Schema` from a JSON string (inverse of {@link serializeSchema}). */
+export declare function parseSchema(json: string): Schema<SchemaRecord>;
+/**
+ * Stable content hash of a `Schema`'s JSON form. FNV-1a over a canonical
+ * (sorted-key) encoding — deterministic across runs and order-invariant, no
+ * `crypto` dependency. Used for connect-time version gating: the client sends
+ * the hash it was built against, the server compares it to the tenant's
+ * active schema hash. Not a security primitive.
+ */
+export declare function schemaHash(schema: Schema<SchemaRecord>): string;
+export {};

package/dist/schema/serialize.js

@@ -0,0 +1,231 @@
+/**
+ * Schema ⇄ JSON
+ *
+ * A `Schema` is serializable except for client-only closures (Zod
+ * validators + computed getters). `serializeSchema` emits the plain-data
+ * JSON form; `parseSchema` reconstructs a working `Schema` from it.
+ *
+ * This is the GraphQL `printSchema` / `buildSchema` model: one `Schema`
+ * type, two representations. A hosted multi-tenant server obtains a tenant's
+ * `Schema` by `parseSchema(json)` instead of an in-process import — the JSON
+ * is what travels over the control plane (`ablo schema push`) and is stored
+ * per `(tenant, version)`.
+ *
+ * What round-trips:
+ *   - all model routing/scoping metadata (typename, tableName, load,
+ *     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)
+ *
+ * What does NOT round-trip (client-only, server never needs it):
+ *   - `computed` getters (closures) — dropped
+ *   - exact Zod refinements — rebuilt as permissive validators from
+ *     `FieldMeta` (the server does no field-shape validation anyway)
+ */
+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). 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;
+    return {
+        type: rel.type,
+        target: rel.target,
+        foreignKey: rel.foreignKey,
+        foreignKeyColumn: rel.foreignKeyColumn,
+        options: options && Object.keys(options).length > 0 ? { ...options } : undefined,
+        orderBy: rel._orderBy,
+    };
+}
+function modelToJSON(def) {
+    const relations = {};
+    for (const [name, rel] of Object.entries(def.relations)) {
+        relations[name] = relationToJSON(rel);
+    }
+    return {
+        fields: def.fields,
+        relations,
+        load: def.load,
+        // `defineSchema` always resolves `typename` to the schema key when unset,
+        // so it is present on a built ModelDef; fall back defensively anyway.
+        typename: def.typename ?? '',
+        tableName: def.tableName,
+        tenancy: def.tenancy,
+        scope: def.scope,
+        grants: def.grants,
+        entityRoles: def.entityRoles,
+        bootstrapLimit: def.bootstrapLimit,
+        bootstrapOrderBy: def.bootstrapOrderBy,
+        mutable: def.mutable,
+        lazyObservable: def.lazyObservable,
+        persist: def.persist,
+        autoFill: def.autoFill,
+        requiredFields: def.requiredFields,
+    };
+}
+/**
+ * Project a `Schema` to its JSON form. Drops the client-only closures
+ * (validators, `computed`); keeps everything the server and a faithful
+ * rebuild need. The result is plain data — `JSON.stringify`-safe.
+ */
+export function toSchemaJSON(schema) {
+    const models = {};
+    for (const [key, def] of Object.entries(schema.models)) {
+        if (def.typename === '' || def.typename === undefined) {
+            // typename '' only happens for a malformed def; surface it loudly
+            // rather than ship a model the server can't route.
+            models[key] = { ...modelToJSON(def), typename: key };
+        }
+        else {
+            models[key] = modelToJSON(def);
+        }
+    }
+    return { v: SCHEMA_JSON_VERSION, models, identityRoles: schema.identityRoles };
+}
+/** Serialize a `Schema` to a JSON string (the `ablo schema push` payload). */
+export function serializeSchema(schema) {
+    return JSON.stringify(toSchemaJSON(schema));
+}
+// ── Parse ──────────────────────────────────────────────────────────────────
+/** Rebuild a Zod validator for a field from its metadata. Permissive by
+ * design — the server does no field-shape validation; this exists so a
+ * parsed `Schema` is structurally a real `Schema`. */
+function zodForField(meta) {
+    let base;
+    switch (meta.type) {
+        case 'string':
+            base = z.string();
+            break;
+        case 'number':
+            base = z.number();
+            break;
+        case 'boolean':
+            base = z.boolean();
+            break;
+        case 'date':
+            base = z.date();
+            break;
+        case 'enum':
+            base =
+                meta.enumValues && meta.enumValues.length > 0
+                    ? z.enum(meta.enumValues)
+                    : z.string();
+            break;
+        case 'json':
+        default:
+            base = z.unknown();
+            break;
+    }
+    return meta.isOptional ? base.optional() : base;
+}
+function relationFromJSON(rel) {
+    // The brand symbols on RelationDef are declare-only (no runtime
+    // presence), so a plain object with the runtime members satisfies every
+    // server-side reader. Cast through unknown to attach the nominal type.
+    return {
+        type: rel.type,
+        target: rel.target,
+        foreignKey: rel.foreignKey,
+        foreignKeyColumn: rel.foreignKeyColumn,
+        options: rel.options ?? {},
+        _orderBy: rel.orderBy,
+    };
+}
+function modelFromJSON(json) {
+    // `z.ZodRawShape` is a readonly index signature in Zod v4, so build a
+    // mutable record and cast once when handing it to `z.object`/`ModelDef`.
+    const shapeMut = {};
+    for (const [name, meta] of Object.entries(json.fields)) {
+        shapeMut[name] = zodForField(meta);
+    }
+    const shape = shapeMut;
+    const relations = {};
+    for (const [name, rel] of Object.entries(json.relations)) {
+        relations[name] = relationFromJSON(rel);
+    }
+    return {
+        schema: z.object(shape),
+        shape,
+        fields: json.fields,
+        relations,
+        load: json.load,
+        bootstrapLimit: json.bootstrapLimit,
+        bootstrapOrderBy: json.bootstrapOrderBy,
+        typename: json.typename,
+        persist: json.persist,
+        tableName: json.tableName,
+        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
+        // parsed schema (server-side) has none.
+        computed: undefined,
+        autoFill: json.autoFill,
+        requiredFields: json.requiredFields,
+    };
+}
+/**
+ * Reconstruct a working `Schema` from its JSON form. Validators are rebuilt
+ * permissively from field metadata (the server never validates field shapes);
+ * `computed` getters are absent. Everything the server reads — routing,
+ * scoping, relations, identity roles — is restored exactly.
+ */
+export function fromSchemaJSON(json) {
+    const models = {};
+    const validators = {};
+    for (const [key, modelJson] of Object.entries(json.models)) {
+        const def = modelFromJSON(modelJson);
+        models[key] = def;
+        validators[key] = baseFieldsSchema.merge(def.schema);
+    }
+    return {
+        models: models,
+        validators: validators,
+        identityRoles: json.identityRoles,
+    };
+}
+/** Parse a `Schema` from a JSON string (inverse of {@link serializeSchema}). */
+export function parseSchema(json) {
+    const parsed = JSON.parse(json);
+    if (parsed.v !== SCHEMA_JSON_VERSION) {
+        throw new Error(`parseSchema: unsupported schema-JSON version ${parsed.v} (expected ${SCHEMA_JSON_VERSION})`);
+    }
+    return fromSchemaJSON(parsed);
+}
+// ── Hash ─────────────────────────────────────────────────────────────────────
+/**
+ * Stable content hash of a `Schema`'s JSON form. FNV-1a over a canonical
+ * (sorted-key) encoding — deterministic across runs and order-invariant, no
+ * `crypto` dependency. Used for connect-time version gating: the client sends
+ * the hash it was built against, the server compares it to the tenant's
+ * active schema hash. Not a security primitive.
+ */
+export function schemaHash(schema) {
+    const canonical = canonicalJson(toSchemaJSON(schema));
+    let h = 0x811c9dc5;
+    for (let i = 0; i < canonical.length; i++) {
+        h ^= canonical.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** Stable JSON: object keys sorted recursively, `undefined` dropped. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}

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,

package/dist/schema/tenancy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tenancy — the single source of truth for how a model's rows are scoped to a
+ * tenant. This replaces three scattered mechanisms (a hardcoded
+ * `organization_id` literal, an `orgScoped` boolean, and a `scopedVia` ref) with
+ * one Zod discriminated union, resolved in one place and consumed everywhere
+ * (provision/RLS, introspection, runtime, CLI).
+ *
+ * Why a union: every consumer used to re-derive "how is this table scoped?" from
+ * a flag plus a literal — a missed branch was a silent cross-tenant scoping bug.
+ * A discriminated union makes the `switch` exhaustive, so the type system holds
+ * the isolation boundary, and the physical column name lives in exactly one
+ * place (the `column` variant) instead of being hardcoded across the codebase.
+ */
+import { z } from 'zod';
+/** Default physical tenancy column. The ONLY place this literal is canonical. */
+export declare const DEFAULT_ORG_COLUMN = "organization_id";
+/**
+ * Scope a table's rows through a parent table (for rows that carry no tenancy
+ * column of their own — e.g. `slide_layers` → slide → deck → org).
+ */
+export declare const scopedViaRefSchema: z.ZodObject<{
+    localKey: z.ZodString;
+    parentTable: z.ZodString;
+    parentKey: z.ZodOptional<z.ZodString>;
+    parentOrgColumn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ScopedViaRef = z.infer<typeof scopedViaRefSchema>;
+/** How a model's rows are scoped to a tenant. */
+export declare const tenancySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"column">;
+    column: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"parent">;
+    via: z.ZodObject<{
+        localKey: z.ZodString;
+        parentTable: z.ZodString;
+        parentKey: z.ZodOptional<z.ZodString>;
+        parentOrgColumn: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$strip>], "kind">;
+export type Tenancy = z.infer<typeof tenancySchema>;
+/**
+ * Ergonomic authoring shortcuts accepted on a model. These are *input only* —
+ * `resolveTenancy` normalizes them into the canonical {@link Tenancy} at
+ * model-build time, so they never reach the serialized JSON or any consumer.
+ */
+export interface TenancyInput {
+    tenancy?: Tenancy;
+    /** `false` → not tenant-scoped. */
+    orgScoped?: boolean;
+    /** Scope through a parent table. */
+    scopedVia?: ScopedViaRef;
+    /** Override the column name for a column-scoped model. */
+    orgColumn?: string;
+}
+/**
+ * Normalize authoring sugar into the one canonical {@link Tenancy}. Called once,
+ * at model-build, so `ModelDef`/`ModelJSON` and every consumer see only
+ * `tenancy`. Precedence: explicit `tenancy` → `scopedVia` → `orgScoped:false` →
+ * column (default or `orgColumn`).
+ */
+export declare function resolveTenancy(input: TenancyInput): Tenancy;
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export declare function tenancyColumn(t: Tenancy): string | null;