@abloatai/transaction 0.37.0

package/dist/schema/serialize.js

@@ -0,0 +1,278 @@
+/**
+ * Schema ⇄ JSON.
+ *
+ * A `Schema` is fully serializable apart from its client-only closures — the
+ * Zod validators and computed getters. {@link serializeSchema} emits the
+ * plain-data JSON form and {@link parseSchema} reconstructs a working `Schema`
+ * from it: one `Schema` type with two representations.
+ *
+ * A hosted, multi-tenant server loads a tenant's schema with `parseSchema(json)`
+ * rather than importing it in process. The JSON is what `ablo push` sends and
+ * what the server stores per tenant and version.
+ *
+ * What round-trips:
+ *   - all model routing and scoping metadata: typename, tableName, load,
+ *     mutable, the `tenancy` descriptor, bootstrap hints, scope, grants,
+ *     entityRoles, the `conflict` disposition map, persist, autoFill,
+ *     requiredFields, and lazyObservable. The authoring shorthands (`policy`
+ *     and `groups`) are normalized into these canonical fields when the model
+ *     is built, so only the canonical fields cross here.
+ *   - relations, including the resolved `foreignKeyColumn`
+ *   - field metadata (names and type tags), from which validators are rebuilt
+ *   - identity roles
+ *
+ * What does not round-trip, because the server never needs it:
+ *   - computed getters, which are closures and are dropped
+ *   - exact Zod refinements, which are rebuilt as permissive validators from
+ *     {@link FieldMeta}; the server does no field-shape validation
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+import { buildFieldRefs } from './schema.js';
+import { relation, } from './relation.js';
+import { baseFieldsSchema, } from './schema.js';
+/** Current schema-JSON envelope version. Bump this on a breaking change to the
+ * JSON shape itself — not to a user's schema. */
+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,
+        plane: def.plane,
+        scope: def.scope,
+        grants: def.grants,
+        entityRoles: def.entityRoles,
+        conflict: def.conflict,
+        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,
+        ...(Object.keys(schema.sessionSettings).length > 0
+            ? { sessionSettings: schema.sessionSettings }
+            : {}),
+    };
+}
+/** Serialize a `Schema` to a JSON string (the `ablo 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) {
+    const setColumn = (definition) => {
+        // The builder normally derives this from schema casing. Serialized schemas
+        // already carry the resolved database column, so restore that runtime field.
+        Reflect.set(definition, 'foreignKeyColumn', rel.foreignKeyColumn);
+        return definition;
+    };
+    switch (rel.type) {
+        case 'belongsTo': {
+            const options = rel.options;
+            return setColumn(relation.belongsTo(rel.target, rel.foreignKey, {
+                ...(options?.index === undefined ? {} : { index: options.index }),
+                ...(options?.enrich === undefined ? {} : { enrich: options.enrich }),
+                ...(options?.defer === undefined ? {} : { defer: options.defer }),
+                ...(options?.parent === undefined ? {} : { parent: options.parent }),
+                ...(options?.fk === undefined ? {} : { fk: options.fk }),
+            }));
+        }
+        case 'hasMany':
+            return setColumn(relation.hasMany(rel.target, rel.foreignKey, rel.orderBy === undefined ? undefined : { orderBy: rel.orderBy }));
+        case 'hasOne':
+            return setColumn(relation.hasOne(rel.target, rel.foreignKey));
+    }
+}
+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,
+        // Absent in older artifacts → default `tenant`, matching the model builder
+        // and provisioning defaults so the round-trip stays stable.
+        plane: json.plane ?? 'tenant',
+        scope: json.scope,
+        grants: json.grants,
+        entityRoles: json.entityRoles,
+        // Absent in older artifacts → undefined, so the commit path falls through to
+        // the function registry or the engine default.
+        conflict: json.conflict,
+        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,
+        // A schema rebuilt from JSON carries references too — the shapes are here.
+        fields: buildFieldRefs(models),
+        validators: validators,
+        identityRoles: json.identityRoles,
+        sessionSettings: json.sessionSettings ?? {},
+    };
+}
+/** 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 AbloValidationError(`parseSchema: unsupported schema-JSON version ${parsed.v} (expected ${SCHEMA_JSON_VERSION})`, { code: 'schema_definition_invalid' });
+    }
+    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) {
+    return fnv1a(canonicalJson(toSchemaJSON(schema)));
+}
+/**
+ * Content hash of ONE serialized model — the unit of the semantic drift check.
+ * Two schemas agree on a model exactly when these match, which is what lets a
+ * client compare only the models it declares instead of welding itself to the
+ * whole-schema hash (where any additive push reads as drift). Computed over the
+ * model's `SchemaJSON` entry with the same canonicalization and hash as
+ * {@link schemaHash}, on both the client and the server's `GET /api/schema`.
+ */
+export function modelHash(modelJson) {
+    return fnv1a(canonicalJson(modelJson));
+}
+/** FNV-1a over an already-canonical string — shared by both hashes above. */
+function fnv1a(canonical) {
+    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(',')}}`;
+}
+//# sourceMappingURL=serialize.js.map

package/dist/schema/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/schema/serialize.ts"],"names":[],"mappings":"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"}

package/dist/schema/sugar.d.ts

@@ -0,0 +1,110 @@
+/**
+ * A concise, claim-first way to declare a model. Each verb is shorthand for a
+ * {@link model} call with two decisions already made, so a reader learns the two
+ * facts that matter most about an entity before scanning its fields:
+ *
+ *   - Writability: `mutable.*` lets clients send create, update, and delete
+ *     operations over the commit protocol. `readOnly.*` means the server owns the
+ *     model — its changes stream to clients as deltas, but clients cannot mutate it.
+ *   - Load strategy: `.instant` loads the model at bootstrap, `.lazy` loads it on
+ *     first access, and `.manual` loads it only when you query it explicitly.
+ *
+ * The two-token form (`mutable.lazy({...})`) states the safety claim in the first
+ * token and the load shape in the second. The plain {@link model} factory remains
+ * available; these verbs are a convenience layered over it.
+ *
+ * @example
+ * ```ts
+ * tasks: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Task', tableName: 'tasks',
+ *   relations: { ... },
+ *   computed: tasksComputed,
+ * }),
+ * ```
+ */
+import type { z } from 'zod';
+import { type ModelDef, type ModelOptions, type ComputedRecord, type RelationRecord } from './model.js';
+/**
+ * Options accepted by every sugar verb. A strict subset of
+ * {@link ModelOptions} — anything the verb infers (`mutable`, `load`,
+ * `lazyObservable`) is deliberately absent so the call site can't
+ * contradict its verb.
+ */
+export interface SugarOptions<R extends RelationRecord = RelationRecord, C extends ComputedRecord = ComputedRecord> {
+    /** Relations to other models. Same shape as `model()`'s second arg. */
+    relations?: R;
+    /** Computed getters installed on the model class prototype. */
+    computed?: C;
+    /**
+     * Wire `__typename` (PascalCase, e.g. `'Task'`). Defaults to the schema
+     * key via `defineSchema` — override when the wire shape differs from
+     * the camelCase schema key.
+     */
+    typename?: string;
+    /**
+     * The physical table name. Override it when the table name differs from the
+     * snake_case of the typename — for example, a `Member` type stored in a table
+     * named `'member'` rather than `'members'`.
+     */
+    tableName?: string;
+    /**
+     * The row-access policy for tenant isolation — the rule deciding who may read a
+     * row. A discriminated union on `by` (`column`, `parent`, or `none`). See
+     * {@link ModelOptions.policy}.
+     */
+    policy?: ModelOptions['policy'];
+    /**
+     * Sync-group routing — which delta *channels* a row fans into
+     * (`root` / `grants` / `roles`). See {@link ModelOptions.groups}.
+     */
+    groups?: ModelOptions['groups'];
+    /** Max rows loaded during bootstrap. Only applies to `.instant`. */
+    bootstrapLimit?: number;
+    /** Bootstrap sort order (e.g. `'created_at DESC'`). */
+    bootstrapOrderBy?: string;
+    /** IndexedDB persistence hints — see {@link ModelOptions.persist}. */
+    persist?: ModelOptions['persist'];
+    /**
+     * Defer MobX observability to first access. Override the verb's
+     * default when a `.lazy` model is small enough that eager MobX setup
+     * is fine, or a `.instant` model is hot enough to justify deferral.
+     */
+    lazyObservable?: boolean;
+}
+/**
+ * Client-writable entities. `mutable.*` is the opt-in signal for wire
+ * mutations via `commit` — equivalent to setting
+ * `{ mutable: true, load: X }` on `model()`.
+ *
+ * Pick the load suffix by data-access pattern:
+ *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.lazy`     — large collections fetched on first query
+ *     (Block, Message, Task)
+ */
+export declare const mutable: {
+    instant: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    lazy: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+};
+/**
+ * Server-managed entities. `readOnly.*` means clients subscribe to
+ * deltas but cannot emit mutations — any `commit` op for this model
+ * is rejected at the server with "Unknown model."
+ *
+ * Use for:
+ *   - Server-written state: `sync_deltas`, `presence`, version vectors
+ *   - Ingestion pipelines: digest entries, filing jobs
+ *   - Audit surfaces: anything where clients watch but only the server
+ *     writes
+ */
+export declare const readOnly: {
+    instant: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    lazy: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+    /**
+     * Internal-only: kept out of bootstrap and never written by clients. The
+     * strongest safety posture — use for tables the SDK must know about (for type
+     * inference) but that no client should be able to write. Rows still reach a
+     * client that reads the model, so this is a write boundary, not a read one.
+     */
+    internal: <Shape extends z.ZodRawShape, R extends RelationRecord = Record<string, never>, C extends ComputedRecord = Record<string, never>>(shape: Shape, opts?: SugarOptions<R, C>) => ModelDef<Shape, R, C>;
+};
+//# sourceMappingURL=sugar.d.ts.map

package/dist/schema/sugar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sugar.d.ts","sourceRoot":"","sources":["../../src/schema/sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,YAAY,CAC3B,CAAC,SAAS,cAAc,GAAG,cAAc,EACzC,CAAC,SAAS,cAAc,GAAG,cAAc;IAEzC,uEAAuE;IACvE,SAAS,CAAC,EAAE,CAAC,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChC,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAyBD;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;cAEhB,KAAK,SAAS,CAAC,CAAC,WAAW,EAC3B,CAAC,SAAS,cAAc,0BACxB,CAAC,SAAS,cAAc,iCAEjB,KAAK,SACL,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;WAMtB,KAAK,SAAS,CAAC,CAAC,WAAW,EAC3B,CAAC,SAAS,cAAc,0BACxB,CAAC,SAAS,cAAc,iCAEjB,KAAK,SACL,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;CAEzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ;cAEjB,KAAK,SAAS,CAAC,CAAC,WAAW,EAC3B,CAAC,SAAS,cAAc,0BACxB,CAAC,SAAS,cAAc,iCAEjB,KAAK,SACL,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;WAQtB,KAAK,SAAS,CAAC,CAAC,WAAW,EAC3B,CAAC,SAAS,cAAc,0BACxB,CAAC,SAAS,cAAc,iCAEjB,KAAK,SACL,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAGxB;;;;;OAKG;eAED,KAAK,SAAS,CAAC,CAAC,WAAW,EAC3B,CAAC,SAAS,cAAc,0BACxB,CAAC,SAAS,cAAc,iCAEjB,KAAK,SACL,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,KACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;CAEzB,CAAC"}

package/dist/schema/sugar.js

@@ -0,0 +1,84 @@
+/**
+ * A concise, claim-first way to declare a model. Each verb is shorthand for a
+ * {@link model} call with two decisions already made, so a reader learns the two
+ * facts that matter most about an entity before scanning its fields:
+ *
+ *   - Writability: `mutable.*` lets clients send create, update, and delete
+ *     operations over the commit protocol. `readOnly.*` means the server owns the
+ *     model — its changes stream to clients as deltas, but clients cannot mutate it.
+ *   - Load strategy: `.instant` loads the model at bootstrap, `.lazy` loads it on
+ *     first access, and `.manual` loads it only when you query it explicitly.
+ *
+ * The two-token form (`mutable.lazy({...})`) states the safety claim in the first
+ * token and the load shape in the second. The plain {@link model} factory remains
+ * available; these verbs are a convenience layered over it.
+ *
+ * @example
+ * ```ts
+ * tasks: mutable.lazy({ title: z.string() }, {
+ *   typename: 'Task', tableName: 'tasks',
+ *   relations: { ... },
+ *   computed: tasksComputed,
+ * }),
+ * ```
+ */
+import { model, } from './model.js';
+/** Internal helper — builds a ModelDef with baseline safety+load flags applied. */
+function build(shape, opts, baseline) {
+    return model(shape, { relations: (opts?.relations ?? {}), mutable: baseline.mutable,
+        load: baseline.load,
+        lazyObservable: opts?.lazyObservable ?? baseline.lazyObservable,
+        typename: opts?.typename,
+        tableName: opts?.tableName,
+        policy: opts?.policy,
+        groups: opts?.groups,
+        bootstrapLimit: opts?.bootstrapLimit,
+        bootstrapOrderBy: opts?.bootstrapOrderBy,
+        persist: opts?.persist,
+        computed: opts?.computed, });
+}
+/**
+ * Client-writable entities. `mutable.*` is the opt-in signal for wire
+ * mutations via `commit` — equivalent to setting
+ * `{ mutable: true, load: X }` on `model()`.
+ *
+ * Pick the load suffix by data-access pattern:
+ *   - `.instant`  — small, always-needed (Theme, Layout, StatusGroup)
+ *   - `.lazy`     — large collections fetched on first query
+ *     (Block, Message, Task)
+ */
+export const mutable = {
+    instant: (shape, opts) => 
+    // Reactive by default (see readonly.instant note): opt out with
+    // `lazyObservable: false` only for very large read-only list models.
+    build(shape, opts, { mutable: true, load: 'instant', lazyObservable: true }),
+    lazy: (shape, opts) => build(shape, opts, { mutable: true, load: 'lazy', lazyObservable: true }),
+};
+/**
+ * Server-managed entities. `readOnly.*` means clients subscribe to
+ * deltas but cannot emit mutations — any `commit` op for this model
+ * is rejected at the server with "Unknown model."
+ *
+ * Use for:
+ *   - Server-written state: `sync_deltas`, `presence`, version vectors
+ *   - Ingestion pipelines: digest entries, filing jobs
+ *   - Audit surfaces: anything where clients watch but only the server
+ *     writes
+ */
+export const readOnly = {
+    instant: (shape, opts) => 
+    // Reactive by default, like every variant: a remote delta that mutates a row
+    // in place must re-render reactive reads. Opt out per-model with
+    // `lazyObservable: false` for very large read-only lists where per-field
+    // atoms cost more than the QueryView's entry-replaced reactivity.
+    build(shape, opts, { mutable: false, load: 'instant', lazyObservable: true }),
+    lazy: (shape, opts) => build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
+    /**
+     * Internal-only: kept out of bootstrap and never written by clients. The
+     * strongest safety posture — use for tables the SDK must know about (for type
+     * inference) but that no client should be able to write. Rows still reach a
+     * client that reads the model, so this is a write boundary, not a read one.
+     */
+    internal: (shape, opts) => build(shape, opts, { mutable: false, load: 'lazy', lazyObservable: true }),
+};
+//# sourceMappingURL=sugar.js.map

package/dist/schema/sugar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sugar.js","sourceRoot":"","sources":["../../src/schema/sugar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,KAAK,GAKN,MAAM,YAAY,CAAC;AAqDpB,mFAAmF;AACnF,SAAS,KAAK,CAKZ,KAAY,EACZ,IAAoC,EACpC,QAAmE;IAEnE,OAAO,KAAK,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,CAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO;QACtF,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,cAAc,EAAE,IAAI,EAAE,cAAc,IAAI,QAAQ,CAAC,cAAc;QAC/D,QAAQ,EAAE,IAAI,EAAE,QAAQ;QACxB,SAAS,EAAE,IAAI,EAAE,SAAS;QAC1B,MAAM,EAAE,IAAI,EAAE,MAAM;QACpB,MAAM,EAAE,IAAI,EAAE,MAAM;QACpB,cAAc,EAAE,IAAI,EAAE,cAAc;QACpC,gBAAgB,EAAE,IAAI,EAAE,gBAAgB;QACxC,OAAO,EAAE,IAAI,EAAE,OAAO;QACtB,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,OAAO,EAAE,CAKP,KAAY,EACZ,IAAyB,EACF,EAAE;IACzB,gEAAgE;IAChE,qEAAqE;IACrE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAE9E,IAAI,EAAE,CAKJ,KAAY,EACZ,IAAyB,EACF,EAAE,CACzB,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;CAC5E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,OAAO,EAAE,CAKP,KAAY,EACZ,IAAyB,EACF,EAAE;IACzB,6EAA6E;IAC7E,iEAAiE;IACjE,yEAAyE;IACzE,kEAAkE;IAClE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAE/E,IAAI,EAAE,CAKJ,KAAY,EACZ,IAAyB,EACF,EAAE,CACzB,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAE5E;;;;;OAKG;IACH,QAAQ,EAAE,CAKR,KAAY,EACZ,IAAyB,EACF,EAAE,CACzB,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;CAC7E,CAAC"}

package/dist/schema/tenancy.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Defines how a model's rows are scoped to a tenant. Two forms live here, and the
+ * separation between them is deliberate:
+ *
+ *   1. The canonical form, {@link Tenancy} — a discriminated union that every
+ *      consumer reads (provisioning and row-level security, introspection, the
+ *      runtime, and the CLI) and the shape that crosses the wire in `ModelJSON`.
+ *      One exhaustively switchable shape, so the type system enforces the isolation
+ *      boundary.
+ *   2. The authoring form, {@link PolicyInput} — the `policy: { by }` option a
+ *      schema author writes. The name follows SQL row-level security, where a
+ *      policy is the rule that decides which rows a tenant may read.
+ *      {@link resolvePolicy} converts it to the canonical {@link Tenancy} when the
+ *      model is built, so the authoring vocabulary never reaches the wire or any
+ *      consumer.
+ *
+ * The canonical form is an exhaustively switchable discriminated union, so the type
+ * system enforces the isolation boundary at every consumer. The authoring form is a
+ * flat object whose `by` names the choice and whose per-branch rules are checked by a
+ * refinement — the opt-out from tenant scoping (`{ by: 'none' }`) and the
+ * source-derived case (`{ by: 'source' }`) are explicit, named values rather than
+ * falsy flags, important because `none` makes an entire table readable across tenants.
+ */
+import { z } from 'zod';
+/** The default physical tenancy column. This is the single canonical definition of that column name. */
+export declare const DEFAULT_ORG_COLUMN = "organization_id";
+/**
+ * Scopes a table's rows through a parent table, for rows that carry no tenancy
+ * column of their own (for example, blocks scoped through their section, report,
+ * and organization). This is the canonical `parent` payload; authors write the
+ * friendlier {@link PolicyInput} `{ by: 'parent', fk, parent }` form, which
+ * {@link resolvePolicy} normalizes into this.
+ */
+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 — the canonical, wire-facing form. */
+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>, z.ZodObject<{
+    kind: z.ZodLiteral<"source">;
+}, z.core.$strip>], "kind">;
+export type Tenancy = z.infer<typeof tenancySchema>;
+/**
+ * The authoring form of tenancy — what a schema author writes as the model's
+ * `policy` option. The name follows SQL row-level security, where a policy is the
+ * rule that decides which rows a tenant may read.
+ *
+ * The four choices `by` can take:
+ *
+ * - `{ by: 'column' }` — a row-local tenancy column (the default). `column`
+ *   overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`) and
+ *   `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are optional overrides.
+ * - `{ by: 'source' }` — derive the organization from the connected source that
+ *   registered the model, for a single-tenant connected database that carries no
+ *   `organization_id` column. The registration is the tenant boundary.
+ * - `{ by: 'none' }` — genuinely global or reference data. This makes the whole
+ *   table readable across tenants, so it is correct only for tables that have no tenant.
+ *
+ * The runtime schema is one flat object rather than a discriminated union: `by`
+ * selects the branch, and the {@link https://zod.dev | superRefine} pass enforces
+ * the per-branch field rules (`parent` requires `fk` and `parent`; the other three
+ * take no branch fields). The exported {@link PolicyInput} type is hand-written as a
+ * precise union so the compiler still requires the right fields per `by` — the flat
+ * schema validates at runtime, the union guides at author time, and the type guard
+ * below keeps the two from drifting.
+ */
+export declare const policyInputSchema: z.ZodObject<{
+    by: z.ZodEnum<{
+        none: "none";
+        source: "source";
+        column: "column";
+        parent: "parent";
+    }>;
+    column: z.ZodOptional<z.ZodString>;
+    fk: z.ZodOptional<z.ZodString>;
+    parent: z.ZodOptional<z.ZodString>;
+    parentKey: z.ZodOptional<z.ZodString>;
+    parentTenantColumn: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The precise authoring type. Hand-written rather than inferred from
+ * {@link policyInputSchema} so the compiler enforces the per-branch fields the flat
+ * runtime schema can only check at parse time — an author writing `{ by: 'parent' }`
+ * gets a type error for the missing `fk`/`parent`, not a runtime one.
+ */
+export type PolicyInput = {
+    by: 'column';
+    column?: string;
+} | {
+    by: 'parent';
+    fk: string;
+    parent: string;
+    parentKey?: string;
+    parentTenantColumn?: string;
+} | {
+    by: 'source';
+} | {
+    by: 'none';
+};
+/**
+ * Normalizes the authoring {@link PolicyInput} into the canonical {@link Tenancy}.
+ * Called once, when the model is built, so that `ModelDef`, `ModelJSON`, and every
+ * consumer see only the canonical union. Omitting `policy` defaults to a row-local
+ * `organization_id` column.
+ */
+export declare function resolvePolicy(input?: PolicyInput): Tenancy;
+/**
+ * Reads the canonical {@link Tenancy} off an already-built model definition (or a
+ * parsed `ModelJSON`), defaulting to a row-local `organization_id` column when it is
+ * absent.
+ *
+ * This is the read-side helper. Consumers — provisioning and row-level security, the
+ * membership resolver, DDL generation, and the CLI — call it to get a model's
+ * tenancy without re-deriving the default each time. It is not the authoring
+ * normalizer; that is {@link resolvePolicy}.
+ */
+export declare function resolveTenancy(def: {
+    tenancy?: Tenancy;
+}): Tenancy;
+/** The physical tenancy column for a column-scoped model, else `null`. */
+export declare function tenancyColumn(t: Tenancy): string | null;
+//# sourceMappingURL=tenancy.d.ts.map

package/dist/schema/tenancy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy.d.ts","sourceRoot":"","sources":["../../src/schema/tenancy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;iBAS7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,mFAAmF;AACnF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;2BAgBxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;iBAsD1B,CAAC;AAEL;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,EAAE,EAAE,QAAQ,CAAA;CAAE,GAChB;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAenB;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAoB1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAElE;AAED,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEvD"}