@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/schema/residency.js

@@ -1,25 +0,0 @@
-/**
- * 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';

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

@@ -1,249 +0,0 @@
-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[];

package/dist/transaction/schema/roles.js

@@ -1,230 +0,0 @@
-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;
-}