@abloatai/transaction 0.37.0

package/dist/schema/residency.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A model's residency: which database its rows live in. This is a sibling axis
+ * to `tenancy`, which instead describes how rows are isolated within a single
+ * database.
+ *
+ *   - `tenant`  — the tenant data plane. For a customer-connected database this
+ *                 is the customer's own database, and provisioning creates these
+ *                 tables there.
+ *   - `control` — the coordination plane the engine owns: the change log,
+ *                 attribution, audit, and the like. These tables are never
+ *                 created in a customer's database.
+ *
+ * The name is `residency` rather than `plane` because "plane" already refers to
+ * the server's tenancy scope — organization, environment, and optionally
+ * project and sandbox. On the wire the serialized option is still keyed as
+ * `plane`, a frozen part of the wire format; only the TypeScript name differs.
+ *
+ * Declaring this boundary lets provisioning derive what a customer's database
+ * receives — the models whose residency is `tenant` — rather than hand-coding
+ * that list. Defaults to `tenant`.
+ */
+import { z } from 'zod';
+export declare const residencySchema: z.ZodEnum<{
+    tenant: "tenant";
+    control: "control";
+}>;
+export type ModelResidency = z.infer<typeof residencySchema>;
+/** Default residency for a model that doesn't declare one — the tenant data plane. */
+export declare const DEFAULT_RESIDENCY: ModelResidency;
+//# sourceMappingURL=residency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"residency.d.ts","sourceRoot":"","sources":["../../src/schema/residency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;;;EAAgC,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,EAAE,cAAyB,CAAC"}

package/dist/schema/residency.js

@@ -0,0 +1,26 @@
+/**
+ * A model's residency: which database its rows live in. This is a sibling axis
+ * to `tenancy`, which instead describes how rows are isolated within a single
+ * database.
+ *
+ *   - `tenant`  — the tenant data plane. For a customer-connected database this
+ *                 is the customer's own database, and provisioning creates these
+ *                 tables there.
+ *   - `control` — the coordination plane the engine owns: the change log,
+ *                 attribution, audit, and the like. These tables are never
+ *                 created in a customer's database.
+ *
+ * The name is `residency` rather than `plane` because "plane" already refers to
+ * the server's tenancy scope — organization, environment, and optionally
+ * project and sandbox. On the wire the serialized option is still keyed as
+ * `plane`, a frozen part of the wire format; only the TypeScript name differs.
+ *
+ * Declaring this boundary lets provisioning derive what a customer's database
+ * receives — the models whose residency is `tenant` — rather than hand-coding
+ * that list. Defaults to `tenant`.
+ */
+import { z } from 'zod';
+export const residencySchema = z.enum(['tenant', 'control']);
+/** Default residency for a model that doesn't declare one — the tenant data plane. */
+export const DEFAULT_RESIDENCY = 'tenant';
+//# sourceMappingURL=residency.js.map

package/dist/schema/residency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"residency.js","sourceRoot":"","sources":["../../src/schema/residency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAG7D,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAmB,QAAQ,CAAC"}

package/dist/schema/roles.d.ts

@@ -0,0 +1,250 @@
+import { z } from 'zod';
+/**
+ * Sync-group roles — the fan-out vocabulary, as typed data.
+ *
+ * A *sync group* is the unit the broadcast layer routes deltas on. On the wire
+ * it's a `kind:id` string, but that serialization is owned entirely by this
+ * module — callers never hand-write `'org:abc'`. Instead they declare a typed
+ * {@link Role} (`kind` + which field supplies the id) and the engine mints the
+ * branded {@link SyncGroup} string via {@link syncGroup}.
+ *
+ * Two reading directions, one shape:
+ *
+ *   • {@link IdentityRole} — "which groups may this *participant* subscribe to?"
+ *     Reads fields off an identity context (`organizationId`, `teamIds`).
+ *
+ *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
+ *     fields off the record itself (`id`, `reportId`), so the server can fan a
+ *     committed delta to the right entity streams regardless of what the
+ *     committer was subscribed to.
+ *
+ * Roles are pure data (no closures) so a `Schema` round-trips through the
+ * control plane and the reconstructed copy behaves identically.
+ */
+/**
+ * The branded wire form of a sync group: `${kind}:${id}`. Branded so a raw
+ * string can't masquerade as one — the only way to produce a `SyncGroup` is
+ * {@link syncGroup}. Because the brand is an intersection it's still assignable
+ * *to* `string`, so existing `string[]` plumbing keeps working unchanged.
+ */
+export declare const syncGroupSchema: z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">;
+export type SyncGroup = z.infer<typeof syncGroupSchema>;
+/**
+ * Mint a sync-group string. The single place the `kind:id` convention lives —
+ * if the wire format ever changes (structured columns, a different separator),
+ * it changes here and nowhere else.
+ */
+export declare function syncGroup(kind: string, id: string): SyncGroup;
+/**
+ * The caller-facing input form of a sync group. Accepts a {@link SyncGroup}
+ * from the constructor, a template literal of the right shape
+ * (`` `org:${orgId}` `` type-checks without importing the constructor), or the
+ * reserved `'default'` anchor. A plain string with no colon is a compile error,
+ * because it would match no group and silently subscribe to nothing.
+ */
+export type SyncGroupInput = SyncGroup | `${string}:${string}` | 'default';
+/**
+ * Runtime validation for {@link SyncGroupInput}, used wherever a group crosses a
+ * trust boundary such as minting a capability or an ephemeral key. A malformed
+ * group is rejected with `invalid_sync_group` rather than stored and left
+ * silently subscribed to nothing.
+ */
+export declare const syncGroupInputSchema: z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>;
+/** Runtime guard matching {@link SyncGroupInput}. */
+export declare function isSyncGroupInput(value: unknown): value is SyncGroupInput;
+/**
+ * The sync-group kinds the authentication provider mints directly onto an
+ * identity. This is a fixed vocabulary: add to this list rather than write a
+ * new namespace string inline.
+ *
+ *   - `org:<organizationId>`  — every member of the organization
+ *   - `user:<participantId>`  — the participant itself
+ *   - `project:<projectId>`   — every credential scoped to the project; the
+ *     organization's default project shares the organization's id
+ *
+ * Schema-declared roles ({@link identityRole} and {@link entityRole}) extend
+ * this vocabulary per application; the kinds here are the ones the engine
+ * reserves.
+ */
+export declare const IDENTITY_ANCHOR_KINDS: readonly ["org", "user", "project"];
+export type IdentityAnchorKind = (typeof IDENTITY_ANCHOR_KINDS)[number];
+/** Mint an engine-reserved identity anchor (typed wrapper over {@link syncGroup}). */
+export declare function identityAnchor(kind: IdentityAnchorKind, id: string): SyncGroup;
+/** Validates how a role pulls ids out of a context (identity or record). */
+export declare const roleSourceSchema: z.ZodObject<{
+    field: z.ZodString;
+    multi: z.ZodBoolean;
+}, z.core.$strip>;
+export type RoleSource = z.infer<typeof roleSourceSchema>;
+/** Back-compat alias — historical name for {@link RoleSource}. */
+export type IdentityRoleSource = RoleSource;
+/** Record-side name for {@link RoleSource}. */
+export type EntityRoleSource = RoleSource;
+/** Free-form context a role reads from. */
+export type RoleContext = Record<string, unknown>;
+/** The identity shape an {@link IdentityRole} reads from. */
+export type IdentityContext = RoleContext;
+/** The record shape an {@link EntityRole} reads from. */
+export type EntityContext = RoleContext;
+/**
+ * A sync-group role: a typed `kind` plus the field that supplies the id. The
+ * wire string is `${kind}:${id}`, built by the engine — there is deliberately
+ * no template/placeholder for the author to get wrong.
+ */
+export declare const roleSchema: z.ZodObject<{
+    kind: z.ZodString;
+    source: z.ZodObject<{
+        field: z.ZodString;
+        multi: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Role = z.infer<typeof roleSchema>;
+/**
+ * Identity-anchored role. Reads an identity field; `kind` names the group.
+ *
+ * ```ts
+ * identityRole({ kind: 'org',  source: 'organizationId' })
+ * identityRole({ kind: 'team', source: 'teamIds', multi: true })
+ * ```
+ */
+export type IdentityRole = Role;
+/**
+ * Record-anchored role. Reads a record field; `kind` names the group. A record
+ * can route to a group keyed by its own `id` *or* a foreign key like `reportId`.
+ *
+ * ```ts
+ * entityRole({ kind: 'report', source: 'id' })        // a report → report:<id>
+ * entityRole({ kind: 'report', source: 'reportId' })  // a block → its parent report
+ * ```
+ */
+export type EntityRole = Role;
+/** Validates an {@link IdentityRole}. */
+export declare const identityRoleSchema: z.ZodType<IdentityRole>;
+/** Validates an {@link EntityRole}. */
+export declare const entityRoleSchema: z.ZodType<EntityRole>;
+/**
+ * Validates a model's `scope` declaration: `true` (kind = typename) or an
+ * explicit lowercase kind string. The same vocabulary the roles use, so the
+ * whole sync-group declaration surface is Zod-validated, not hand-checked.
+ */
+export declare const scopeSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>;
+/**
+ * Validates a model's `grants` membership edge. Both values are relation names
+ * declared on the same model (`subject` → identity, `scope` → scope root); that
+ * the relations actually exist + are `belongsTo` is a cross-field check done in
+ * `defineSchema` where the relation map is in scope.
+ */
+export declare const grantsRefSchema: z.ZodObject<{
+    subject: z.ZodString;
+    scope: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The authoring form of a model's sync-group routing — the `groups: { ... }`
+ * option. One object collects the three independent routing controls. This is a
+ * separate concern from `policy`, which governs tenant isolation: `policy`
+ * decides who may read a row, while `groups` decides which change channels a row
+ * fans into.
+ *
+ * - `root`   — marks this model a scope root, so its records form the group
+ *   `<kind>:<id>` (the kind defaults to the typename).
+ * - `grants` — a membership edge granting an identity access to a scope root.
+ * - `roles`  — record-to-group roles keyed on a plain field rather than a
+ *   relation, such as inbox fan-out. Accepts a single role or an array.
+ */
+export declare const groupsInputSchema: z.ZodObject<{
+    root: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    grants: z.ZodOptional<z.ZodObject<{
+        subject: z.ZodString;
+        scope: z.ZodString;
+    }, z.core.$strip>>;
+    roles: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown>>, z.ZodArray<z.ZodType<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown, z.core.$ZodTypeInternals<{
+        kind: string;
+        source: {
+            field: string;
+            multi: boolean;
+        };
+    }, unknown>>>]>>;
+}, z.core.$strip>;
+export type GroupsInput = z.infer<typeof groupsInputSchema>;
+/** Build an identity-anchored role. `multi` defaults to `false`. */
+export declare function identityRole(spec: {
+    readonly kind: string;
+    /** Identity-context field to read. See {@link RoleSource.field}. */
+    readonly source: string;
+    /** Treat the field as an array of ids. See {@link RoleSource.multi}. */
+    readonly multi?: boolean;
+}): IdentityRole;
+/** Build a record-anchored role. `multi` defaults to `false`. */
+export declare function entityRole(spec: {
+    readonly kind: string;
+    /** Record field to read. See {@link RoleSource.field}. */
+    readonly source: string;
+    /** Treat the field as an array of ids. See {@link RoleSource.multi}. */
+    readonly multi?: boolean;
+}): EntityRole;
+/**
+ * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
+ * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
+ * with no `reportId`) is a silent no-op.
+ */
+export declare function extractRoleIds(context: RoleContext, source: RoleSource): readonly string[];
+/** Identity-side name for {@link extractRoleIds}. */
+export declare const extractIdentityIds: typeof extractRoleIds;
+/** Record-side name for {@link extractRoleIds}. */
+export declare const extractEntityIds: typeof extractRoleIds;
+/**
+ * Compose the sync groups an identity may subscribe to, from the schema's
+ * registered {@link IdentityRole}s. Returns `[]` when no role produces an id;
+ * the caller treats `[]` as "no scope", not "match everything".
+ */
+export declare function composeIdentitySyncGroups(identity: IdentityContext, schema: {
+    readonly identityRoles: readonly IdentityRole[];
+}): readonly SyncGroup[];
+/**
+ * Compose the sync groups a record belongs to, from the model's registered
+ * {@link EntityRole}s. Mirror of {@link composeIdentitySyncGroups}, reading the
+ * record instead of an identity. Returns `[]` when the model has no entity
+ * roles (the delta then fans on its base `org:`/`user:` groups only).
+ */
+export declare function composeEntitySyncGroups(record: EntityContext, def: {
+    readonly entityRoles?: readonly EntityRole[];
+}): readonly SyncGroup[];
+/**
+ * Narrow a client's requested sync-group set to the groups it is actually
+ * allowed to subscribe to. This helper is fully generic — it never inspects the
+ * group strings — so it lives beside the composition helpers above.
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-derived set,
+ *     which is this participant's default subscription scope.
+ *   - If the client requested some groups, keep only those that appear in the
+ *     identity-derived allowed set and drop the rest, reporting the dropped
+ *     groups through the optional `logDropped` callback.
+ *   - If nothing survives the filter, fall back to the full allowed set rather
+ *     than return `[]`, which would otherwise collapse to the server-side
+ *     `'default'` fallback and deliver no changes at all.
+ */
+export declare function intersectRequestedWithAllowed(args: {
+    readonly requested: readonly string[];
+    readonly allowed: readonly string[];
+    readonly logDropped?: (dropped: readonly string[]) => void;
+}): readonly string[];
+//# sourceMappingURL=roles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../../src/schema/roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,qFAEL,CAAC;AAExB,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAE7D;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,GAAG,SAAS,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,qIAAmD,CAAC;AAErF,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,qCAAsC,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,CAE9E;AAID,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB;;;iBAQ3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC5C,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAE1C,2CAA2C;AAC3C,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAClD,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC;AAC1C,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC;AAIxC;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;iBAGrB,CAAC;AAEH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC;AAEhC;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC;AAE9B,yCAAyC;AACzC,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,CAAc,CAAC;AACtE,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAc,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,WAAW,kDAGtB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;iBAG1B,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAI5B,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAY5D,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,IAAI,EAAE;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,YAAY,CAEf;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,UAAU,CAEb;AAID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,SAAS,MAAM,EAAE,CAQ1F;AAED,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,uBAAiB,CAAC;AACjD,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,uBAAiB,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE;IAAE,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GAC1D,SAAS,SAAS,EAAE,CAQtB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GACpD,SAAS,SAAS,EAAE,CAStB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CAC5D,GAAG,SAAS,MAAM,EAAE,CAYpB"}

package/dist/schema/roles.js

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+/**
+ * Sync-group roles — the fan-out vocabulary, as typed data.
+ *
+ * A *sync group* is the unit the broadcast layer routes deltas on. On the wire
+ * it's a `kind:id` string, but that serialization is owned entirely by this
+ * module — callers never hand-write `'org:abc'`. Instead they declare a typed
+ * {@link Role} (`kind` + which field supplies the id) and the engine mints the
+ * branded {@link SyncGroup} string via {@link syncGroup}.
+ *
+ * Two reading directions, one shape:
+ *
+ *   • {@link IdentityRole} — "which groups may this *participant* subscribe to?"
+ *     Reads fields off an identity context (`organizationId`, `teamIds`).
+ *
+ *   • {@link EntityRole} — "which groups does this *record* live in?" Reads
+ *     fields off the record itself (`id`, `reportId`), so the server can fan a
+ *     committed delta to the right entity streams regardless of what the
+ *     committer was subscribed to.
+ *
+ * Roles are pure data (no closures) so a `Schema` round-trips through the
+ * control plane and the reconstructed copy behaves identically.
+ */
+// ── Sync-group wire form (branded) ──────────────────────────────────────────
+/**
+ * The branded wire form of a sync group: `${kind}:${id}`. Branded so a raw
+ * string can't masquerade as one — the only way to produce a `SyncGroup` is
+ * {@link syncGroup}. Because the brand is an intersection it's still assignable
+ * *to* `string`, so existing `string[]` plumbing keeps working unchanged.
+ */
+export const syncGroupSchema = z
+    .templateLiteral([z.string().regex(/^[a-z][a-z0-9_]*$/), ':', z.string().min(1)])
+    .brand();
+/**
+ * Mint a sync-group string. The single place the `kind:id` convention lives —
+ * if the wire format ever changes (structured columns, a different separator),
+ * it changes here and nowhere else.
+ */
+export function syncGroup(kind, id) {
+    return `${kind}:${id}`;
+}
+/**
+ * Runtime validation for {@link SyncGroupInput}, used wherever a group crosses a
+ * trust boundary such as minting a capability or an ephemeral key. A malformed
+ * group is rejected with `invalid_sync_group` rather than stored and left
+ * silently subscribed to nothing.
+ */
+export const syncGroupInputSchema = z.union([z.literal('default'), syncGroupSchema]);
+/** Runtime guard matching {@link SyncGroupInput}. */
+export function isSyncGroupInput(value) {
+    return syncGroupInputSchema.safeParse(value).success;
+}
+// ── Identity anchors (closed vocabulary) ────────────────────────────────────
+/**
+ * The sync-group kinds the authentication provider mints directly onto an
+ * identity. This is a fixed vocabulary: add to this list rather than write a
+ * new namespace string inline.
+ *
+ *   - `org:<organizationId>`  — every member of the organization
+ *   - `user:<participantId>`  — the participant itself
+ *   - `project:<projectId>`   — every credential scoped to the project; the
+ *     organization's default project shares the organization's id
+ *
+ * Schema-declared roles ({@link identityRole} and {@link entityRole}) extend
+ * this vocabulary per application; the kinds here are the ones the engine
+ * reserves.
+ */
+export const IDENTITY_ANCHOR_KINDS = ['org', 'user', 'project'];
+/** Mint an engine-reserved identity anchor (typed wrapper over {@link syncGroup}). */
+export function identityAnchor(kind, id) {
+    return syncGroup(kind, id);
+}
+// ── Role source ─────────────────────────────────────────────────────────────
+/** Validates how a role pulls ids out of a context (identity or record). */
+export const roleSourceSchema = z.object({
+    /** The context field to read, e.g. `'organizationId'`, `'id'`, `'reportId'`. */
+    field: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'source must be a valid identifier'),
+    /**
+     * When `true`, `field` holds an array; every non-empty string element yields
+     * one group. When `false` (default), `field` is a scalar; truthy → one group.
+     */
+    multi: z.boolean(),
+});
+// ── Role (kind + source — no template string) ───────────────────────────────
+/**
+ * A sync-group role: a typed `kind` plus the field that supplies the id. The
+ * wire string is `${kind}:${id}`, built by the engine — there is deliberately
+ * no template/placeholder for the author to get wrong.
+ */
+export const roleSchema = z.object({
+    kind: z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "report"'),
+    source: roleSourceSchema,
+});
+/** Validates an {@link IdentityRole}. */
+export const identityRoleSchema = roleSchema;
+/** Validates an {@link EntityRole}. */
+export const entityRoleSchema = roleSchema;
+/**
+ * Validates a model's `scope` declaration: `true` (kind = typename) or an
+ * explicit lowercase kind string. The same vocabulary the roles use, so the
+ * whole sync-group declaration surface is Zod-validated, not hand-checked.
+ */
+export const scopeSchema = z.union([
+    z.boolean(),
+    z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "workspace"'),
+]);
+/**
+ * Validates a model's `grants` membership edge. Both values are relation names
+ * declared on the same model (`subject` → identity, `scope` → scope root); that
+ * the relations actually exist + are `belongsTo` is a cross-field check done in
+ * `defineSchema` where the relation map is in scope.
+ */
+export const grantsRefSchema = z.object({
+    subject: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'grants.subject must name a relation'),
+    scope: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'grants.scope must name a relation'),
+});
+/**
+ * The authoring form of a model's sync-group routing — the `groups: { ... }`
+ * option. One object collects the three independent routing controls. This is a
+ * separate concern from `policy`, which governs tenant isolation: `policy`
+ * decides who may read a row, while `groups` decides which change channels a row
+ * fans into.
+ *
+ * - `root`   — marks this model a scope root, so its records form the group
+ *   `<kind>:<id>` (the kind defaults to the typename).
+ * - `grants` — a membership edge granting an identity access to a scope root.
+ * - `roles`  — record-to-group roles keyed on a plain field rather than a
+ *   relation, such as inbox fan-out. Accepts a single role or an array.
+ */
+export const groupsInputSchema = z.object({
+    root: scopeSchema.optional(),
+    grants: grantsRefSchema.optional(),
+    roles: z.union([entityRoleSchema, z.array(entityRoleSchema)]).optional(),
+});
+// ── Factories ───────────────────────────────────────────────────────────────
+function makeRole(spec) {
+    return { kind: spec.kind, source: { field: spec.source, multi: spec.multi ?? false } };
+}
+/** Build an identity-anchored role. `multi` defaults to `false`. */
+export function identityRole(spec) {
+    return makeRole(spec);
+}
+/** Build a record-anchored role. `multi` defaults to `false`. */
+export function entityRole(spec) {
+    return makeRole(spec);
+}
+// ── Evaluation ──────────────────────────────────────────────────────────────
+/**
+ * Evaluate a {@link RoleSource} against a context. Absent or falsy fields yield
+ * `[]`, so a role whose field isn't present (a user with no `teamIds`, a record
+ * with no `reportId`) is a silent no-op.
+ */
+export function extractRoleIds(context, source) {
+    const raw = context[source.field];
+    if (source.multi) {
+        return Array.isArray(raw)
+            ? raw.filter((t) => typeof t === 'string' && t.length > 0)
+            : [];
+    }
+    return raw ? [String(raw)] : [];
+}
+/** Identity-side name for {@link extractRoleIds}. */
+export const extractIdentityIds = extractRoleIds;
+/** Record-side name for {@link extractRoleIds}. */
+export const extractEntityIds = extractRoleIds;
+/**
+ * Compose the sync groups an identity may subscribe to, from the schema's
+ * registered {@link IdentityRole}s. Returns `[]` when no role produces an id;
+ * the caller treats `[]` as "no scope", not "match everything".
+ */
+export function composeIdentitySyncGroups(identity, schema) {
+    const out = new Set();
+    for (const role of schema.identityRoles) {
+        for (const id of extractRoleIds(identity, role.source)) {
+            if (id)
+                out.add(syncGroup(role.kind, id));
+        }
+    }
+    return Array.from(out);
+}
+/**
+ * Compose the sync groups a record belongs to, from the model's registered
+ * {@link EntityRole}s. Mirror of {@link composeIdentitySyncGroups}, reading the
+ * record instead of an identity. Returns `[]` when the model has no entity
+ * roles (the delta then fans on its base `org:`/`user:` groups only).
+ */
+export function composeEntitySyncGroups(record, def) {
+    if (!def.entityRoles?.length)
+        return [];
+    const out = new Set();
+    for (const role of def.entityRoles) {
+        for (const id of extractRoleIds(record, role.source)) {
+            if (id)
+                out.add(syncGroup(role.kind, id));
+        }
+    }
+    return Array.from(out);
+}
+/**
+ * Narrow a client's requested sync-group set to the groups it is actually
+ * allowed to subscribe to. This helper is fully generic — it never inspects the
+ * group strings — so it lives beside the composition helpers above.
+ *
+ * Behaviour:
+ *   - If the client requested no groups, return the full identity-derived set,
+ *     which is this participant's default subscription scope.
+ *   - If the client requested some groups, keep only those that appear in the
+ *     identity-derived allowed set and drop the rest, reporting the dropped
+ *     groups through the optional `logDropped` callback.
+ *   - If nothing survives the filter, fall back to the full allowed set rather
+ *     than return `[]`, which would otherwise collapse to the server-side
+ *     `'default'` fallback and deliver no changes at all.
+ */
+export function intersectRequestedWithAllowed(args) {
+    const { requested, allowed, logDropped } = args;
+    if (requested.length === 0)
+        return allowed;
+    const allowedSet = new Set(allowed);
+    const accepted = [];
+    const dropped = [];
+    for (const g of requested) {
+        if (allowedSet.has(g))
+            accepted.push(g);
+        else
+            dropped.push(g);
+    }
+    if (dropped.length > 0 && logDropped)
+        logDropped(dropped);
+    return accepted.length > 0 ? accepted : allowed;
+}
+//# sourceMappingURL=roles.js.map

package/dist/schema/roles.js.map

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