@abloatai/ablo 0.6.0 → 0.8.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,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

@@ -8,13 +8,13 @@
  * 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
+ * is what travels over the control plane (`ablo push`) and is stored
  * per `(tenant, version)`.
  *
  * 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,18 +50,19 @@ 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;
     readonly autoFill?: readonly AutoFillRule[];
     readonly requiredFields?: readonly string[];
 }
-/** The JSON form of a {@link Schema}. The `@ablo schema push` payload. */
+/** The JSON form of a {@link Schema}. The `ablo push` payload. */
 export interface SchemaJSON {
     readonly v: typeof SCHEMA_JSON_VERSION;
     readonly models: Record<string, ModelJSON>;
@@ -70,7 +74,7 @@ export interface SchemaJSON {
  * 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). */
+/** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
 export declare function serializeSchema(schema: Schema<SchemaRecord>): string;
 /**
  * Reconstruct a working `Schema` from its JSON form. Validators are rebuilt

package/dist/schema/serialize.js

@@ -8,13 +8,13 @@
  * 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
+ * is what travels over the control plane (`ablo push`) and is stored
  * per `(tenant, version)`.
  *
  * 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,
@@ -85,7 +88,7 @@ export function toSchemaJSON(schema) {
     }
     return { v: SCHEMA_JSON_VERSION, models, identityRoles: schema.identityRoles };
 }
-/** Serialize a `Schema` to a JSON string (the `ablo schema push` payload). */
+/** Serialize a `Schema` to a JSON string (the `ablo push` payload). */
 export function serializeSchema(schema) {
     return JSON.stringify(toSchemaJSON(schema));
 }
@@ -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,

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;

package/dist/schema/tenancy.js

@@ -0,0 +1,58 @@
+/**
+ * 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 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 const scopedViaRefSchema = z.object({
+    /** Column on THIS table pointing at the parent (e.g. `'team_id'`). */
+    localKey: z.string().min(1),
+    /** Parent table name (e.g. `'team'`). */
+    parentTable: z.string().min(1),
+    /** Column on the parent that `localKey` references. Default `'id'`. */
+    parentKey: z.string().min(1).optional(),
+    /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+    parentOrgColumn: z.string().min(1).optional(),
+});
+/** How a model's rows are scoped to a tenant. */
+export const tenancySchema = z.discriminatedUnion('kind', [
+    /** Row-local tenancy column (default name `organization_id`, overridable). */
+    z.object({ kind: z.literal('column'), column: z.string().min(1) }),
+    /** Scoped through a parent table's tenancy. */
+    z.object({ kind: z.literal('parent'), via: scopedViaRefSchema }),
+    /** Not tenant-scoped (global / reference data). */
+    z.object({ kind: z.literal('none') }),
+]);
+/**
+ * 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 function resolveTenancy(input) {
+    if (input.tenancy)
+        return input.tenancy;
+    if (input.scopedVia)
+        return { kind: 'parent', via: input.scopedVia };
+    if (input.orgScoped === false)
+        return { kind: 'none' };
+    return { kind: 'column', column: input.orgColumn ?? DEFAULT_ORG_COLUMN };
+}
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export function tenancyColumn(t) {
+    return t.kind === 'column' ? t.column : null;
+}