@abloatai/ablo 0.36.0 → 0.37.1

package/dist/sync/participants.d.ts

@@ -1,132 +0,0 @@
-import type { JoinOptions } from '../transaction/resources/modelOperations.js';
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Schema } from '../transaction/schema/schema.js';
-import type { Claim, Activity, ClaimTarget, ClaimStream, Peer, PresenceStream, PresenceTarget } from '../transaction/types/streams.js';
-import type { AttachableClaimStream } from './createClaimStream.js';
-/**
- * The scope a participant can be joined to. The usual form is an entity target
- * (`{ type, id }`); raw sync-group strings are an advanced escape hatch for
- * addressing a transport scope directly.
- */
-export type ParticipantScope = ClaimTarget | readonly ClaimTarget[] | 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 claims: ClaimStream;
-}
-/**
- * The options for a participant join. It extends the public per-model
- * {@link JoinOptions} rather than restating its members, so the lease dial is
- * declared once, in the core, and this surface adds only what a lower-level
- * join can additionally say.
- */
-export interface ParticipantJoinOptions extends JoinOptions {
-    /**
-     * The initial focus target, named in your schema's vocabulary and optionally
-     * narrowed to a path, field, or range. When `scope` is omitted, this target
-     * also becomes the routing scope.
-     */
-    readonly target?: PresenceTarget;
-    /** Alias for `target` when the participant is joined to a broader scope. */
-    readonly focus?: PresenceTarget;
-    /**
-     * The routing scope: one entity, many entities, or a raw sync-group escape
-     * hatch. Use it for "joined to the folder, focused on one file" shapes,
-     * where the participant listens more broadly than its focus target.
-     */
-    readonly scope?: ParticipantScope;
-    /** Present a narrower capability for this logical participant. */
-    readonly capabilityToken?: string;
-    /**
-     * @deprecated Use `ttl`. Removed in 0.37.0.
-     *
-     * One lease, spelled two ways, and the seconds spelling was the one that
-     * misled: it accepted a duration string, so `ablo.<model>.join(ids, { ttl:
-     * '5m' })` reached this surface as `ttlSeconds: '5m'` — a field whose name
-     * asserts a unit its value did not carry. `ttl` takes the same values and is
-     * the spelling every other lease in the SDK already uses (`claim`'s `ttl`,
-     * `ClaimLeaseOptions.ttl`). The wire is unchanged: it has always carried
-     * seconds, and still does.
-     */
-    readonly ttlSeconds?: number | string | null;
-    /**
-     * The activity to announce as soon as the claim is acknowledged. Defaults to
-     * `reading` when a `target` is present. Pass `false` to join without
-     * announcing anything.
-     */
-    readonly activity?: 'reading' | 'viewing' | 'editing' | false;
-    readonly detail?: string;
-}
-export interface ScopedPresence {
-    readonly self: Peer;
-    readonly focus: ClaimTarget | null;
-    readonly others: readonly 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;
-    onChange(listener: () => void): () => void;
-}
-export interface ScopedClaimOptions {
-    /** Override the participant's focus target for this one claim. */
-    readonly target?: PresenceTarget;
-    /** Peer-visible description of the work. Defaults to `'editing'`. */
-    readonly description?: string;
-    /** How long the claim lives; the server expires it automatically after this. */
-    readonly ttl?: import('../transaction/types/streams.js').Duration;
-}
-export interface ScopedClaims {
-    readonly focus: ClaimTarget | null;
-    readonly others: readonly Claim[];
-    /**
-     * Takes an exclusive claim on the participant's focus target, or on an
-     * explicit target passed via `opts.target`. While the claim is held, other
-     * participants that request an overlapping target are rejected.
-     */
-    claim(opts?: ScopedClaimOptions): Claim;
-    onRejected(listener: Parameters<ClaimStream['onRejected']>[0]): () => void;
-    onChange(listener: () => void): () => void;
-}
-export interface ParticipantFocusOptions {
-    readonly activity?: 'reading' | 'viewing' | 'editing' | false;
-    readonly detail?: string;
-}
-export interface JoinedParticipant {
-    /** The exact entity this participant is currently reading or editing. */
-    readonly target: ClaimTarget | null;
-    readonly focusTarget: ClaimTarget | null;
-    /** The transport scopes this participant is joined to, which govern what it sees and receives. */
-    readonly syncGroups: readonly string[];
-    readonly presence: ScopedPresence;
-    readonly claims: ScopedClaims;
-    readonly peers: readonly Peer[];
-    readonly activeClaims: readonly Claim[];
-    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>;
-    /** The connection, host-built and stable for the client's lifetime. */
-    readonly transport: SyncWebSocket;
-    readonly presence: PresenceStream;
-    readonly claims: AttachableClaimStream;
-    readonly schema?: Schema;
-}
-export declare function createParticipantManager(config: ParticipantManagerConfig): ParticipantManager;
-export declare function resolveParticipantSyncGroups(scope: ParticipantScope | undefined, schema?: Schema): string[];
-export declare function syncGroupFromEntityRef(ref: ClaimTarget, schema?: Schema): string;
-export declare function parseParticipantTtlSeconds(value: number | string | null | undefined): number | undefined;
-export declare function createParticipantClaimId(): string;

package/dist/sync/participants.js

@@ -1,346 +0,0 @@
-import { scopeKindOf } from '../transaction/schema/model.js';
-import { AbloValidationError } from '../transaction/errors.js';
-import { subTarget, streamTarget, wireTarget, } from '../transaction/coordination/index.js';
-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();
-            // Not-connected joins surface through `sendClaim`'s diagnosed
-            // rejection below; a scopeless join needs no wire send at all.
-            const transport = config.transport;
-            const claimId = createParticipantClaimId();
-            if (syncGroups.length > 0) {
-                await transport.sendClaim(claimId, syncGroups, {
-                    capabilityToken: options.capabilityToken,
-                    // `ttl` is the spelling; `ttlSeconds` is the deprecated one, read
-                    // second so a caller passing both gets the current name honored.
-                    ttlSeconds: parseParticipantTtlSeconds(options.ttl ?? options.ttlSeconds),
-                });
-            }
-            const participant = createJoinedParticipant({
-                target,
-                syncGroups,
-                claimId,
-                transport,
-                presence: config.presence,
-                claims: config.claims,
-            });
-            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;
-}
-/**
- * The group kind for a model, in the wire dialect every plane shares: a
- * declared scope root wins; otherwise the lowercased typename — the same
- * token the commit plane and claim targets use (`wireModel`). Never the
- * camelCase schema key: the server validates inbound subscription groups
- * against a lowercase-only grammar, so a key like `reportBlocks` would be
- * rejected as malformed on subscribe — and even a lowercase key would put
- * this client in a different group than a peer who resolved the same row
- * through an entity ref, so the two would never see each other's claims.
- */
-function groupKindForModel(def, key) {
-    return scopeKindOf(def, key) ?? (def.typename ?? key).toLowerCase();
-}
-export function syncGroupFromEntityRef(ref, schema) {
-    const match = findModelForEntityRef(ref, schema);
-    const kind = match
-        ? groupKindForModel(match.def, match.key)
-        : ref.type.toLowerCase();
-    return `${kind}:${ref.id}`;
-}
-function syncGroupFromSchemaKey(schemaKey, id, schema) {
-    const def = schema?.models?.[schemaKey];
-    const kind = def ? groupKindForModel(def, schemaKey) : schemaKey.toLowerCase();
-    return `${kind}:${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;
-}
-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 AbloValidationError('Participant action requires a structured target', {
-                code: 'invalid_request',
-            });
-        }
-        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();
-        },
-        onChange(listener) {
-            return args.presence.onChange(listener);
-        },
-    };
-    const track = (handle) => {
-        ownHandles.add(handle);
-        return {
-            object: 'claim',
-            id: handle.id,
-            description: handle.description,
-            target: handle.target,
-            async release() {
-                ownHandles.delete(handle);
-                await handle.release?.();
-            },
-            revoke() {
-                ownHandles.delete(handle);
-                handle.revoke?.();
-            },
-            [Symbol.asyncDispose]: async () => {
-                ownHandles.delete(handle);
-                await handle[Symbol.asyncDispose]?.();
-            },
-        };
-    };
-    const scopedClaims = {
-        get focus() {
-            return currentTarget;
-        },
-        get others() {
-            return args.claims.others.filter((claim) => currentTarget ? targetsOverlap(claim.target, currentTarget) : true);
-        },
-        claim(opts) {
-            return track(args.claims.claim(requireTarget(opts?.target), {
-                description: opts?.description,
-                ttl: opts?.ttl,
-            }));
-        },
-        onRejected(listener) {
-            return args.claims.onRejected(listener);
-        },
-        onChange(listener) {
-            return args.claims.onChange(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,
-        claims: scopedClaims,
-        get peers() {
-            return scopedPresence.others;
-        },
-        get activeClaims() {
-            return scopedClaims.others;
-        },
-        focus: setFocus,
-        leave,
-        [Symbol.asyncDispose]: async () => {
-            leave();
-        },
-    };
-    return joined;
-}
-function activityFromTarget(target) {
-    return {
-        ...wireTarget(target),
-        ...subTarget(target),
-    };
-}
-function presenceMatchesParticipant(entry, target, syncGroups) {
-    if (syncGroups.some((g) => entry.syncGroups.includes(g)))
-        return true;
-    if (!target)
-        return true;
-    return targetsOverlap({
-        ...streamTarget(entry.activity),
-        ...subTarget(entry.activity),
-    }, 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/persistedPrefix.d.ts

@@ -1,12 +0,0 @@
-/**
- * Returns the highest sync id in the durable prefix of an ordered delta frame.
- *
- * A frame may span several IndexedDB stores, each committed in its own
- * transaction. Those transactions can succeed and fail independently. The
- * resume cursor may advance only through the first failed input: taking the
- * maximum id from any successful store would skip an earlier failed delta on
- * every later catch-up.
- */
-export declare function highestPersistedPrefixSyncId(deltas: readonly {
-    readonly syncId?: number | string;
-}[], persistedIndexes: ReadonlySet<number>): number;

package/dist/sync/persistedPrefix.js

@@ -1,22 +0,0 @@
-/**
- * Returns the highest sync id in the durable prefix of an ordered delta frame.
- *
- * A frame may span several IndexedDB stores, each committed in its own
- * transaction. Those transactions can succeed and fail independently. The
- * resume cursor may advance only through the first failed input: taking the
- * maximum id from any successful store would skip an earlier failed delta on
- * every later catch-up.
- */
-export function highestPersistedPrefixSyncId(deltas, persistedIndexes) {
-    let through = 0;
-    for (let index = 0; index < deltas.length; index += 1) {
-        if (!persistedIndexes.has(index))
-            break;
-        const raw = deltas[index]?.syncId;
-        const syncId = typeof raw === 'string' ? Number(raw) : raw;
-        if (typeof syncId === 'number' && Number.isFinite(syncId) && syncId > through) {
-            through = syncId;
-        }
-    }
-    return through;
-}

package/dist/sync/schemaDrift.d.ts

@@ -1,55 +0,0 @@
-/**
- * The semantic schema-drift classifier — the question that matters is not
- * "did the schema change at all?" (one whole-schema hash answers that, and
- * welds every client to every push) but "does THIS client use anything that
- * changed?". This module compares only the models the client declares against
- * the server's per-model surface (`GET /api/schema`), so:
- *
- *   - a purely additive server change (models this build never references) is
- *     SILENCE — deployed clients don't care what they don't use;
- *   - a model this build declares that the server doesn't have is named, with
- *     the push as the fix;
- *   - a shared model whose content differs is named, so "which field moved"
- *     is one `ablo status` away instead of a hash-guessing game.
- *
- * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
- */
-/** One model as the server's schema read-back reports it. */
-export interface ServerSchemaModel {
-    readonly key: string;
-    /** Per-model content hash; absent on servers older than this check. */
-    readonly hash?: string;
-}
-export type SchemaDriftFinding = 
-/** Every model this client declares exists server-side with matching content
- *  (the server may know more — that's an additive lead, not drift). */
-{
-    readonly kind: 'aligned';
-}
-/** Models this build declares that the server has no idea about — writes to
- *  them will be declined until the schema is pushed. */
- | {
-    readonly kind: 'unpushed';
-    readonly models: readonly string[];
-}
-/** Shared models whose content differs between this build and the server
- *  (may also carry unpushed models found alongside). */
- | {
-    readonly kind: 'changed';
-    readonly models: readonly string[];
-    readonly unpushed: readonly string[];
-}
-/** The server surface carries no per-model hashes (older server) — the
- *  caller falls back to the whole-hash comparison. */
- | {
-    readonly kind: 'unknown';
-};
-export declare function classifySchemaDrift(clientModels: Readonly<Record<string, string>>, serverModels: readonly ServerSchemaModel[]): SchemaDriftFinding;
-/**
- * The warning for a real, named divergence. Calm and specific: which models,
- * what that means for this client, and the one next step. Never speaks about
- * hashes — the point of the semantic check is that nobody has to compare hex.
- */
-export declare function describeSchemaDrift(finding: Extract<SchemaDriftFinding, {
-    kind: 'unpushed' | 'changed';
-}>, serverLabel: string): string;

package/dist/sync/schemaDrift.js

@@ -1,53 +0,0 @@
-/**
- * The semantic schema-drift classifier — the question that matters is not
- * "did the schema change at all?" (one whole-schema hash answers that, and
- * welds every client to every push) but "does THIS client use anything that
- * changed?". This module compares only the models the client declares against
- * the server's per-model surface (`GET /api/schema`), so:
- *
- *   - a purely additive server change (models this build never references) is
- *     SILENCE — deployed clients don't care what they don't use;
- *   - a model this build declares that the server doesn't have is named, with
- *     the push as the fix;
- *   - a shared model whose content differs is named, so "which field moved"
- *     is one `ablo status` away instead of a hash-guessing game.
- *
- * Pure and transport-free; the BootstrapFetcher owns fetching the surface.
- */
-export function classifySchemaDrift(clientModels, serverModels) {
-    if (serverModels.length > 0 && serverModels.every((m) => !m.hash)) {
-        return { kind: 'unknown' };
-    }
-    const server = new Map(serverModels.map((m) => [m.key, m.hash]));
-    const unpushed = [];
-    const changed = [];
-    for (const [key, hash] of Object.entries(clientModels)) {
-        const serverHash = server.get(key);
-        if (serverHash === undefined)
-            unpushed.push(key);
-        else if (serverHash !== hash)
-            changed.push(key);
-    }
-    if (changed.length > 0)
-        return { kind: 'changed', models: changed, unpushed };
-    if (unpushed.length > 0)
-        return { kind: 'unpushed', models: unpushed };
-    return { kind: 'aligned' };
-}
-/**
- * The warning for a real, named divergence. Calm and specific: which models,
- * what that means for this client, and the one next step. Never speaks about
- * hashes — the point of the semantic check is that nobody has to compare hex.
- */
-export function describeSchemaDrift(finding, serverLabel) {
-    if (finding.kind === 'unpushed') {
-        return (`Ablo: This build declares models the server at ${serverLabel} doesn't have yet ` +
-            `(${finding.models.join(', ')}). Writes to them will be declined until the schema is ` +
-            `pushed — run \`ablo push\` (and \`ablo status\` to confirm it targets this server).`);
-    }
-    const alsoUnpushed = finding.unpushed.length > 0 ? ` (${finding.unpushed.join(', ')} not pushed yet)` : '';
-    return (`Ablo: These models differ between this build and the server at ${serverLabel}: ` +
-        `${finding.models.join(', ')}${alsoUnpushed}. Reads and writes touching what changed may be ` +
-        `declined — \`ablo status\` shows the deployed shape; pushing your schema or deploying a ` +
-        `current build aligns them.`);
-}