@abloatai/ablo 0.3.0

package/dist/sync/participants.d.ts

@@ -0,0 +1,114 @@
+import type { SyncWebSocket } from './SyncWebSocket.js';
+import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { ActiveIntent, Activity, EntityRef, Claim, IntentStream, Peer, PresenceStream, PresenceTarget } from '../types/streams.js';
+/**
+ * Scope accepted by participant APIs. The normal SDK shape is an
+ * entity target (`{ type, id }`). Raw sync-group strings remain an
+ * advanced transport escape hatch.
+ */
+export type ParticipantScope = EntityRef | readonly EntityRef[] | string | readonly string[] | {
+    readonly syncGroup: string;
+} | {
+    readonly syncGroups: readonly string[];
+} | Record<string, string | readonly string[] | undefined>;
+export type ParticipantStatus = 'idle' | 'connecting' | 'connected' | 'error' | 'disconnected';
+export interface EngineParticipant {
+    readonly presence: PresenceStream;
+    readonly intents: IntentStream;
+}
+export interface ParticipantJoinOptions {
+    /**
+     * Initial focus target: customer schema vocabulary, optionally
+     * narrowed to a path, field, or range. When `scope` is omitted,
+     * this also becomes the routing scope.
+     */
+    readonly target?: PresenceTarget;
+    /** Alias for `target` when the participant is joined to a broader scope. */
+    readonly focus?: PresenceTarget;
+    /**
+     * Routing scope. Can be one entity, many entities, or a raw
+     * sync-group escape hatch. Use this for "joined to folder, focused
+     * on file" shapes.
+     */
+    readonly scope?: ParticipantScope;
+    /** Present a narrower capability for this logical participant. */
+    readonly capabilityToken?: string;
+    /** Claim TTL, in seconds or a compact duration string (`30s`, `5m`). */
+    readonly ttlSeconds?: number | string | null;
+    /**
+     * Activity to announce immediately after the claim acks. Defaults to
+     * `reading` when `target` is present. Pass false to join silently.
+     */
+    readonly activity?: 'reading' | 'viewing' | 'editing' | false;
+    readonly detail?: string;
+}
+export interface ScopedPresence {
+    readonly self: Peer;
+    readonly focus: EntityRef | null;
+    readonly others: ReadonlyArray<Peer>;
+    update(activity: Activity): void;
+    reading(detail?: string): void;
+    reading(target: PresenceTarget, detail?: string): void;
+    viewing(detail?: string): void;
+    viewing(target: PresenceTarget, detail?: string): void;
+    editing(detail?: string): void;
+    editing(target: PresenceTarget, detail?: string): void;
+    idle(): void;
+    subscribe(listener: () => void): () => void;
+}
+export interface ScopedClaimOptions {
+    /** Override the participant's focus target for this one claim. */
+    readonly target?: PresenceTarget;
+    /** Free-form reason. Defaults to `'editing'`. Common: `'editing'`,
+     *  `'writing'`, `'reviewing'`, app-specific phases. */
+    readonly reason?: string;
+    /** TTL — server auto-expires the claim after this. */
+    readonly ttl?: import('../types/streams.js').Duration;
+}
+export interface ScopedIntents {
+    readonly focus: EntityRef | null;
+    readonly others: ReadonlyArray<ActiveIntent>;
+    /**
+     * Claim an exclusive intent on the participant's focus target (or
+     * an explicit override via `opts.target`). Single verb — the old
+     * `editing / writing / announce / claim(reason, opts)` overloads
+     * collapsed into this one method.
+     */
+    claim(opts?: ScopedClaimOptions): Claim;
+    onRejected(listener: Parameters<IntentStream['onRejected']>[0]): () => void;
+    subscribe(listener: () => void): () => void;
+}
+export interface ParticipantFocusOptions {
+    readonly activity?: 'reading' | 'viewing' | 'editing' | false;
+    readonly detail?: string;
+}
+export interface JoinedParticipant {
+    /** Current exact thing this participant is reading/editing. */
+    readonly target: EntityRef | null;
+    readonly focusTarget: EntityRef | null;
+    /** Transport scopes this participant is joined to for visibility/fan-out. */
+    readonly syncGroups: readonly string[];
+    readonly presence: ScopedPresence;
+    readonly intents: ScopedIntents;
+    readonly peers: ReadonlyArray<Peer>;
+    readonly claims: ReadonlyArray<ActiveIntent>;
+    focus(target: PresenceTarget, options?: ParticipantFocusOptions): JoinedParticipant;
+    leave(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface ParticipantManager {
+    join(target: PresenceTarget, options?: Omit<ParticipantJoinOptions, 'target'>): Promise<JoinedParticipant>;
+    join(options: ParticipantJoinOptions): Promise<JoinedParticipant>;
+}
+export interface ParticipantManagerConfig {
+    readonly ready: () => Promise<void>;
+    readonly getTransport: () => SyncWebSocket | null;
+    readonly presence: PresenceStream;
+    readonly intents: IntentStream;
+    readonly schema?: Schema<SchemaRecord>;
+}
+export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
+export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema<SchemaRecord>): string[];
+export declare function syncGroupFromEntityRef(ref: EntityRef, schema?: Schema<SchemaRecord>): string;
+export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
+export declare function createParticipantClaimId(): string;

package/dist/sync/participants.js

@@ -0,0 +1,336 @@
+export function createParticipantManager(config) {
+    return {
+        async join(input, overrides) {
+            const options = normalizeJoinOptions(input, overrides);
+            const target = options.focus ?? options.target
+                ? targetToEntityRef((options.focus ?? options.target))
+                : null;
+            const syncGroups = unique(resolveParticipantSyncGroups(options.scope ?? target ?? undefined, config.schema));
+            await config.ready();
+            const transport = config.getTransport();
+            if (!transport) {
+                throw new Error('Ablo participant join failed: WebSocket is not connected');
+            }
+            const claimId = createParticipantClaimId();
+            if (syncGroups.length > 0) {
+                await transport.sendClaim(claimId, syncGroups, {
+                    capabilityToken: options.capabilityToken,
+                    ttlSeconds: parseParticipantTtlSeconds(options.ttlSeconds),
+                });
+            }
+            const participant = createJoinedParticipant({
+                target,
+                syncGroups,
+                claimId,
+                transport,
+                presence: config.presence,
+                intents: config.intents,
+            });
+            if (target && options.activity !== false) {
+                const activity = options.activity ?? 'reading';
+                if (activity === 'editing') {
+                    participant.presence.editing(options.detail);
+                }
+                else if (activity === 'viewing') {
+                    participant.presence.viewing(options.detail);
+                }
+                else {
+                    participant.presence.reading(options.detail);
+                }
+            }
+            return participant;
+        },
+    };
+}
+export function resolveParticipantSyncGroups(scope, schema) {
+    if (!scope)
+        return [];
+    if (typeof scope === 'string')
+        return [scope];
+    if (Array.isArray(scope)) {
+        return scope.flatMap((entry) => typeof entry === 'string' ? [entry] : [syncGroupFromEntityRef(entry, schema)]);
+    }
+    const direct = scope;
+    if (isEntityScope(scope))
+        return [syncGroupFromEntityRef(scope, schema)];
+    if (typeof direct.syncGroup === 'string')
+        return [direct.syncGroup];
+    if (Array.isArray(direct.syncGroups)) {
+        return direct.syncGroups.filter((g) => typeof g === 'string');
+    }
+    const out = [];
+    for (const [key, value] of Object.entries(scope)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const id of value)
+                out.push(syncGroupFromSchemaKey(key, id, schema));
+        }
+        else {
+            out.push(syncGroupFromSchemaKey(key, value, schema));
+        }
+    }
+    return out;
+}
+export function syncGroupFromEntityRef(ref, schema) {
+    const match = findModelForEntityRef(ref, schema);
+    if (match?.def.syncGroupFormat) {
+        return renderSyncGroupFormat(match.def.syncGroupFormat, { id: ref.id });
+    }
+    return `${ref.type.toLowerCase()}:${ref.id}`;
+}
+function syncGroupFromSchemaKey(schemaKey, id, schema) {
+    const def = schema?.models?.[schemaKey];
+    if (def?.syncGroupFormat) {
+        return renderSyncGroupFormat(def.syncGroupFormat, { id });
+    }
+    return `${schemaKey}:${id}`;
+}
+function findModelForEntityRef(ref, schema) {
+    if (!schema?.models)
+        return null;
+    const wanted = ref.type.toLowerCase();
+    for (const [key, def] of Object.entries(schema.models)) {
+        const typename = def.typename ?? key;
+        if (typename.toLowerCase() === wanted || key.toLowerCase() === wanted) {
+            return { key, def };
+        }
+    }
+    return null;
+}
+function renderSyncGroupFormat(format, values) {
+    return format.replace(/\{([a-zA-Z_][a-zA-Z0-9_]*)\}/g, (_match, key) => {
+        const value = values[key];
+        return value === undefined ? `{${key}}` : value;
+    });
+}
+export function parseParticipantTtlSeconds(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (!value)
+        return undefined;
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(value.trim());
+    if (!match)
+        return undefined;
+    const amount = Number(match[1]);
+    const unit = match[2] ?? 's';
+    if (unit === 'ms')
+        return Math.max(1, Math.ceil(amount / 1000));
+    if (unit === 'm')
+        return Math.ceil(amount * 60);
+    if (unit === 'h')
+        return Math.ceil(amount * 3600);
+    return Math.ceil(amount);
+}
+export function createParticipantClaimId() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return `participant:${crypto.randomUUID()}`;
+    }
+    return `participant:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+}
+function normalizeJoinOptions(input, overrides) {
+    if (isTupleTarget(input) || isEntityScope(input)) {
+        return { ...overrides, target: input };
+    }
+    return { ...input, ...overrides };
+}
+function isTupleTarget(value) {
+    return (Array.isArray(value) &&
+        typeof value[0] === 'string' &&
+        typeof value[1] === 'string');
+}
+function isEntityScope(scope) {
+    return (typeof scope === 'object' &&
+        scope !== null &&
+        !Array.isArray(scope) &&
+        typeof scope.type === 'string' &&
+        typeof scope.id === 'string');
+}
+function targetToEntityRef(target) {
+    if (isTupleTarget(target))
+        return { type: target[0], id: target[1] };
+    return target;
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function createJoinedParticipant(args) {
+    const ownHandles = new Set();
+    let currentTarget = args.target;
+    let left = false;
+    const requireTarget = (target) => {
+        const resolved = target ? targetToEntityRef(target) : currentTarget;
+        if (!resolved) {
+            throw new Error('Participant action requires a structured target');
+        }
+        return resolved;
+    };
+    const setFocus = (target, options) => {
+        currentTarget = targetToEntityRef(target);
+        if (options?.activity === 'editing') {
+            scopedPresence.editing(options.detail);
+        }
+        else if (options?.activity === 'viewing') {
+            scopedPresence.viewing(options.detail);
+        }
+        else if (options?.activity === 'reading') {
+            scopedPresence.reading(options.detail);
+        }
+        return joined;
+    };
+    const resolvePresenceAction = (targetOrDetail, detail) => {
+        if (typeof targetOrDetail === 'string' || targetOrDetail === undefined) {
+            return { target: requireTarget(), detail: targetOrDetail ?? detail };
+        }
+        return { target: requireTarget(targetOrDetail), detail };
+    };
+    const scopedPresence = {
+        get self() {
+            return args.presence.self;
+        },
+        get focus() {
+            return currentTarget;
+        },
+        get others() {
+            return args.presence.others.filter((entry) => presenceMatchesParticipant(entry, currentTarget, args.syncGroups));
+        },
+        update(activity) {
+            args.presence.update(activity);
+        },
+        reading(targetOrDetail, detail) {
+            const action = resolvePresenceAction(targetOrDetail, detail);
+            args.presence.update({
+                ...activityFromTarget(action.target),
+                action: 'reading',
+                detail: action.detail,
+            });
+        },
+        viewing(targetOrDetail, detail) {
+            const action = resolvePresenceAction(targetOrDetail, detail);
+            args.presence.viewing(action.target, action.detail);
+        },
+        editing(targetOrDetail, detail) {
+            const action = resolvePresenceAction(targetOrDetail, detail);
+            args.presence.editing(action.target, action.detail);
+        },
+        idle() {
+            args.presence.idle();
+        },
+        subscribe(listener) {
+            return args.presence.subscribe(listener);
+        },
+    };
+    const track = (handle) => {
+        ownHandles.add(handle);
+        return {
+            id: handle.id,
+            revoke() {
+                ownHandles.delete(handle);
+                handle.revoke();
+            },
+            [Symbol.asyncDispose]: async () => {
+                ownHandles.delete(handle);
+                await handle[Symbol.asyncDispose]();
+            },
+        };
+    };
+    const scopedIntents = {
+        get focus() {
+            return currentTarget;
+        },
+        get others() {
+            return args.intents.others.filter((intent) => currentTarget ? targetsOverlap(intent.target, currentTarget) : true);
+        },
+        claim(opts) {
+            return track(args.intents.claim(requireTarget(opts?.target), {
+                reason: opts?.reason,
+                ttl: opts?.ttl,
+            }));
+        },
+        onRejected(listener) {
+            return args.intents.onRejected(listener);
+        },
+        subscribe(listener) {
+            return args.intents.subscribe(listener);
+        },
+    };
+    const leave = () => {
+        if (left)
+            return;
+        left = true;
+        for (const handle of Array.from(ownHandles)) {
+            handle.revoke();
+            ownHandles.delete(handle);
+        }
+        args.presence.idle();
+        if (args.syncGroups.length > 0) {
+            args.transport.sendRelease(args.claimId);
+        }
+    };
+    const joined = {
+        get target() {
+            return currentTarget;
+        },
+        get focusTarget() {
+            return currentTarget;
+        },
+        syncGroups: [...args.syncGroups],
+        presence: scopedPresence,
+        intents: scopedIntents,
+        get peers() {
+            return scopedPresence.others;
+        },
+        get claims() {
+            return scopedIntents.others;
+        },
+        focus: setFocus,
+        leave,
+        [Symbol.asyncDispose]: async () => {
+            leave();
+        },
+    };
+    return joined;
+}
+function activityFromTarget(target) {
+    return {
+        entityType: target.type,
+        entityId: target.id,
+        path: target.path,
+        range: target.range,
+        field: target.field,
+        meta: target.meta,
+    };
+}
+function presenceMatchesParticipant(entry, target, syncGroups) {
+    if (syncGroups.some((g) => entry.syncGroups.includes(g)))
+        return true;
+    if (!target)
+        return true;
+    return targetsOverlap({
+        type: entry.activity.entityType,
+        id: entry.activity.entityId,
+        path: entry.activity.path,
+        range: entry.activity.range,
+        field: entry.activity.field,
+        meta: entry.activity.meta,
+    }, target);
+}
+function targetsOverlap(a, b) {
+    if (a.type !== b.type || a.id !== b.id)
+        return false;
+    if (!hasSubtarget(a) || !hasSubtarget(b))
+        return true;
+    if (a.path && b.path && a.path !== b.path)
+        return false;
+    const fieldOverlaps = !a.field || !b.field || a.field === b.field;
+    const rangeOverlaps = !a.range || !b.range || rangesOverlap(a.range, b.range);
+    return fieldOverlaps && rangeOverlaps;
+}
+function hasSubtarget(target) {
+    return Boolean(target.path || target.field || target.range);
+}
+function rangesOverlap(a, b) {
+    return a.startLine <= b.endLine && b.startLine <= a.endLine;
+}

package/dist/sync/schemas.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Zod validation schemas for sync engine server responses.
+ *
+ * Validates data at the fetch boundary before it enters the sync engine.
+ * Uses .passthrough() so the server can add fields without breaking clients.
+ */
+import { z } from 'zod';
+export declare const ServerDeltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    operation: z.ZodOptional<z.ZodEnum<{
+        A: "A";
+        I: "I";
+        U: "U";
+        D: "D";
+        C: "C";
+        G: "G";
+        S: "S";
+        V: "V";
+    }>>;
+    action: z.ZodOptional<z.ZodEnum<{
+        A: "A";
+        I: "I";
+        U: "U";
+        D: "D";
+        C: "C";
+        G: "G";
+        S: "S";
+        V: "V";
+    }>>;
+    modelName: z.ZodString;
+    entityId: z.ZodOptional<z.ZodString>;
+    modelId: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$loose>;
+export type ValidatedServerDelta = z.infer<typeof ServerDeltaSchema>;
+export declare const BootstrapResponseSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        partial: "partial";
+        full: "full";
+    }>;
+    lastSyncId: z.ZodNumber;
+    models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodPipe<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodString, z.ZodNull]>, z.ZodTransform<unknown[], string | unknown[] | null>>>>;
+    deltas: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        operation: z.ZodOptional<z.ZodEnum<{
+            A: "A";
+            I: "I";
+            U: "U";
+            D: "D";
+            C: "C";
+            G: "G";
+            S: "S";
+            V: "V";
+        }>>;
+        action: z.ZodOptional<z.ZodEnum<{
+            A: "A";
+            I: "I";
+            U: "U";
+            D: "D";
+            C: "C";
+            G: "G";
+            S: "S";
+            V: "V";
+        }>>;
+        modelName: z.ZodString;
+        entityId: z.ZodOptional<z.ZodString>;
+        modelId: z.ZodOptional<z.ZodString>;
+        data: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$loose>>>;
+    deltaCount: z.ZodOptional<z.ZodNumber>;
+    failedModels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
+}, z.core.$loose>;
+export type ValidatedBootstrapResponse = z.infer<typeof BootstrapResponseSchema>;
+/**
+ * Validate a raw bootstrap response from the server.
+ * Logs validation failures via SyncObservability and throws a descriptive error.
+ */
+export declare function parseBootstrapResponse(raw: unknown): ValidatedBootstrapResponse;

package/dist/sync/schemas.js

@@ -0,0 +1,78 @@
+/**
+ * Zod validation schemas for sync engine server responses.
+ *
+ * Validates data at the fetch boundary before it enters the sync engine.
+ * Uses .passthrough() so the server can add fields without breaking clients.
+ */
+import { z } from 'zod';
+import { getContext } from "../context.js";
+import { AbloValidationError } from "../errors.js";
+// ─── Sync Action Types ───────────────────────────────────────────────────────
+// Mirror of SyncActionType from sync-engine/types.ts
+const SYNC_ACTION_VALUES = ['I', 'U', 'D', 'A', 'C', 'G', 'S', 'V'];
+// ─── Server Delta Schema ─────────────────────────────────────────────────────
+export const ServerDeltaSchema = z
+    .object({
+    id: z.number(),
+    operation: z.enum(SYNC_ACTION_VALUES).optional(),
+    action: z.enum(SYNC_ACTION_VALUES).optional(),
+    modelName: z.string(),
+    entityId: z.string().optional(),
+    modelId: z.string().optional(),
+    data: z.record(z.string(), z.unknown()).nullable().optional(),
+})
+    .passthrough();
+// ─── Model Value Schema ─────────────────────────────────────────────────────
+// Server model values arrive in multiple shapes depending on Go serialization:
+//   - Array: already-parsed JSON array (most common)
+//   - String: double-encoded JSON string from json.RawMessage
+//   - null: from PostgreSQL jsonb_agg with no matching rows
+// This schema normalizes all variants into unknown[] before downstream use.
+const ModelValueSchema = z
+    .union([z.array(z.unknown()), z.string(), z.null()])
+    .transform((val) => {
+    if (val === null)
+        return [];
+    if (typeof val === 'string') {
+        try {
+            const parsed = JSON.parse(val);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    return val;
+});
+// ─── Bootstrap Response Schema ───────────────────────────────────────────────
+export const BootstrapResponseSchema = z
+    .object({
+    type: z.enum(['full', 'partial']),
+    lastSyncId: z.number(),
+    models: z.record(z.string(), ModelValueSchema).optional(),
+    deltas: z.array(ServerDeltaSchema).optional(),
+    deltaCount: z.number().optional(),
+    failedModels: z.array(z.string()).optional(),
+    timestamp: z.number().default(() => Date.now()),
+})
+    .passthrough();
+// ─── Parse Helpers ───────────────────────────────────────────────────────────
+/**
+ * Validate a raw bootstrap response from the server.
+ * Logs validation failures via SyncObservability and throws a descriptive error.
+ */
+export function parseBootstrapResponse(raw) {
+    const result = BootstrapResponseSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+        getContext().observability.breadcrumb('Bootstrap response validation failed', 'sync.bootstrap', 'error', {
+            issues,
+            rawType: typeof raw,
+            rawKeys: raw && typeof raw === 'object' ? Object.keys(raw).join(',') : 'n/a',
+        });
+        throw new AbloValidationError(`Invalid bootstrap response: ${issues}`, {
+            code: 'bootstrap_response_schema_invalid',
+        });
+    }
+    return result.data;
+}

package/dist/testing/fixtures/bootstrap.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bootstrap response factories for sync engine tests.
+ *
+ * Creates well-formed bootstrap responses matching the server API.
+ */
+import type { BootstrapType } from '../../types/index.js';
+export interface BootstrapModelData {
+    [modelName: string]: Array<Record<string, unknown>>;
+}
+export interface BootstrapResponse {
+    type: BootstrapType;
+    lastSyncId: number;
+    models?: BootstrapModelData;
+    deltas?: Array<{
+        id: number;
+        modelName: string;
+        modelId: string;
+        action: string;
+        data: Record<string, unknown>;
+    }>;
+    deltaCount?: number;
+    failedModels?: string[];
+    timestamp: number;
+}
+/**
+ * Create a full bootstrap response (fresh snapshot from server).
+ */
+export declare function createFullBootstrapResponse(models: BootstrapModelData, lastSyncId?: number): BootstrapResponse;
+/**
+ * Create a partial bootstrap response (delta batch from lastSyncId).
+ */
+export declare function createPartialBootstrapResponse(deltas: BootstrapResponse['deltas'], lastSyncId: number): BootstrapResponse;
+/**
+ * Create a full bootstrap response with test model data pre-populated.
+ */
+export declare function createTestBootstrapResponse(options?: {
+    tasks?: Array<Record<string, unknown>>;
+    projects?: Array<Record<string, unknown>>;
+    slideDecks?: Array<Record<string, unknown>>;
+    slides?: Array<Record<string, unknown>>;
+    slideLayers?: Array<Record<string, unknown>>;
+    comments?: Array<Record<string, unknown>>;
+    lastSyncId?: number;
+    failedModels?: string[];
+}): BootstrapResponse;