@abloatai/ablo 0.5.1 → 0.6.0

package/dist/schema/schema.d.ts

@@ -29,20 +29,23 @@ export type CasingFn = (jsField: string) => string;
 /** `defineSchema`'s casing option. Identity when unset. */
 export type Casing = CasingConvention | CasingFn;
 /**
- * The identity shape passed to {@link IdentityRole.extract}. Free-form
+ * 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 `extract` without translation.
+ * returns) straight to {@link extractIdentityIds} without translation.
  */
 export type IdentityContext = Record<string, unknown>;
 /**
- * Open registration of an identity-anchored sync-group. Each role
- * declares (a) a free-form `kind` label (purely for diagnostics), (b)
- * a `template` containing a single `{id}` placeholder, and (c) an
- * `extract` function that pulls the relevant ids out of an arbitrary
- * identity context.
+ * 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:
@@ -50,35 +53,74 @@ export type IdentityContext = Record<string, unknown>;
  * ```ts
  * defineSchema({ ... }, {
  *   identityRoles: [
- *     { kind: 'region',   template: 'region:{id}',
- *       extract: (i) => i.regionId ? [String(i.regionId)] : [] },
- *     { kind: 'customer', template: 'customer:{id}',
- *       extract: (i) => i.customerId ? [String(i.customerId)] : [] },
+ *     identityRole({ kind: 'region',   template: 'region:{id}',   source: 'regionId' }),
+ *     identityRole({ kind: 'customer', template: 'customer:{id}', source: 'customerId' }),
  *   ],
  * });
  * ```
  *
- * The server's `composeIdentitySyncGroups` walks every registered role
- * and produces the union — no hardcoded `org:` / `user:` / `team:`
- * anywhere in the engine.
+ * {@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 returned by `extract`. Example: `'org:{id}'` →
+     * 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;
     /**
-     * Extract zero or more ids from the resolved identity context. Pure
-     * function — must not allocate persistent state, must be safe to
-     * call once per request. Return an empty array when the role
-     * doesn't apply to this identity.
+     * 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 extract: (identity: IdentityContext) => readonly string[];
+    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 {
     /**
@@ -113,8 +155,14 @@ export interface DefineSchemaOptions {
 }
 /** A record of model names → model definitions */
 export type SchemaRecord = Record<string, ModelDef>;
-/** Base fields every synced model gets automatically */
-declare const baseFieldsSchema: z.ZodObject<{
+/**
+ * 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 declare const baseFieldsSchema: z.ZodObject<{
     id: z.ZodString;
     createdAt: z.ZodDate;
     updatedAt: z.ZodDate;
@@ -244,16 +292,19 @@ export declare function defineSchema<const S extends SchemaRecord>(models: S, op
 /**
  * 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.
+ * {@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 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."
+ * 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[];
-export {};

package/dist/schema/schema.js

@@ -39,8 +39,50 @@ 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({
+/**
+ * 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.
+ *
+ * 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(),
@@ -165,21 +207,25 @@ 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.
+ * {@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 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."
+ * 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 function composeIdentitySyncGroups(identity, schema) {
     const out = new Set();
     for (const role of schema.identityRoles) {
-        for (const id of role.extract(identity)) {
+        for (const id of extractIdentityIds(identity, role.source)) {
             if (id)
                 out.add(role.template.replace('{id}', id));
         }

package/dist/schema/serialize.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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, syncGroupFormat,
+ *     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 { ScopedViaRef, LoadStrategy, PersistOptions, AutoFillRule } from './model.js';
+import type { RelationType } from './relation.js';
+import { type Schema, type SchemaRecord, type IdentityRole } 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;
+/** 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 orgScoped?: boolean;
+    readonly scopedVia?: ScopedViaRef;
+    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. */
+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,227 @@
+/**
+ * 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, syncGroupFormat,
+ *     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). */
+const SCHEMA_JSON_VERSION = 1;
+// ── 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,
+        orgScoped: def.orgScoped,
+        scopedVia: def.scopedVia,
+        bootstrapLimit: def.bootstrapLimit,
+        bootstrapOrderBy: def.bootstrapOrderBy,
+        syncGroupFormat: def.syncGroupFormat,
+        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,
+        orgScoped: json.orgScoped,
+        scopedVia: json.scopedVia,
+        syncGroupFormat: json.syncGroupFormat,
+        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/sync/SyncWebSocket.d.ts

@@ -261,6 +261,23 @@ export interface CoreSyncEventMap {
      * Payload mirrors the wire frame's `payload`.
      */
     intent_rejected: [Record<string, unknown>];
+    /**
+     * Fair-queue frames (opt-in `queue: true` on `intent_begin`). `intent_acquired`
+     * means the target was free and the lease is ours immediately; `intent_queued`
+     * means the claim is waiting in line (carries `position`); `intent_granted`
+     * means it reached the head and the lease is now ours; `intent_lost` means a
+     * held/granted claim was taken away (TTL lapse on disconnect, revoke).
+     */
+    /**
+     * Per-entity wait-queue snapshot: `{ target, queue: Intent[] }` with each
+     * entry `status: 'queued'` + `position`. Broadcast to entity peers on every
+     * queue mutation — powers the reactive `ablo.<model>.queue(id)` read.
+     */
+    intent_queue: [Record<string, unknown>];
+    intent_acquired: [Record<string, unknown>];
+    intent_queued: [Record<string, unknown>];
+    intent_granted: [Record<string, unknown>];
+    intent_lost: [Record<string, unknown>];
 }
 /**
  * Collaboration event — app-specific real-time events (selection, cursors, etc.)

package/dist/sync/SyncWebSocket.js

@@ -10,7 +10,7 @@
 import { EventEmitter } from 'events';
 import { getContext } from '../context.js';
 import { flushOfflineQueueOnce } from './OfflineFlush.js';
-import { CapabilityError, SyncSessionError } from '../errors.js';
+import { AbloClaimedError, CapabilityError, SyncSessionError, } from '../errors.js';
 // ---------------------------------------------------------------------------
 // Ablo-specific collaboration events moved to apps/web/src/lib/sync/collaboration-events.ts
 // Consumers pass their own event types as TCollaboration generic parameter.
@@ -368,6 +368,24 @@ export class SyncWebSocket extends EventEmitter {
                                 errorCode === 'capability_invalid') {
                                 pending.reject(new CapabilityError(errorCode, errorMessage, requiredCapability));
                             }
+                            else if (errorCode === 'intent_conflict' ||
+                                errorCode === 'claim_conflict' ||
+                                errorCode === 'entity_claimed') {
+                                // Claim enforcement: another participant holds a live claim on
+                                // a targeted entity. Two server layers reject this — the Hub's
+                                // pre-commit lease check (`intent_conflict`, the code that
+                                // reaches clients in practice) and `executeCommit`'s deeper
+                                // guard (`entity_claimed`). Both mean "claimed", so both route
+                                // through the typed AbloClaimedError, letting callers
+                                // `instanceof AbloClaimedError` (or read `e.type` across worker
+                                // boundaries) and wait/bypass — symmetric with the
+                                // CapabilityError branch above, and with the HTTP commit path
+                                // (`translateHttpError`).
+                                pending.reject(new AbloClaimedError(errorMessage, {
+                                    code: errorCode === 'intent_conflict' ? 'claim_conflict' : errorCode,
+                                    httpStatus: 409,
+                                }));
+                            }
                             else {
                                 const rejection = new Error(errorMessage);
                                 if (errorCode)
@@ -448,6 +466,33 @@ export class SyncWebSocket extends EventEmitter {
                         this.emit('intent_rejected', message.payload ?? {});
                         break;
                     }
+                    case 'intent_acquired': {
+                        // Opt-in fair queue: the target was free, so the lease is ours
+                        // immediately (no waiting). Payload carries { intentId, target }.
+                        this.emit('intent_acquired', message.payload ?? {});
+                        break;
+                    }
+                    case 'intent_queue': {
+                        // Per-entity wait-queue snapshot for reactive `queue(id)`.
+                        this.emit('intent_queue', message.payload ?? {});
+                        break;
+                    }
+                    case 'intent_queued': {
+                        // Opt-in fair queue: our claim is waiting in line. Payload
+                        // carries { intentId, target, position }.
+                        this.emit('intent_queued', message.payload ?? {});
+                        break;
+                    }
+                    case 'intent_granted': {
+                        // Our queued claim reached the head — the lease is now ours.
+                        this.emit('intent_granted', message.payload ?? {});
+                        break;
+                    }
+                    case 'intent_lost': {
+                        // A held/granted claim was taken from us (TTL lapse, revoke).
+                        this.emit('intent_lost', message.payload ?? {});
+                        break;
+                    }
                     case 'delta': {
                         const p = message.payload;
                         if (p?.actionType || p?.modelName) {