@abloatai/ablo 0.36.0 → 0.37.0

package/dist/sync/createClaimStream.d.ts

@@ -1,7 +0,0 @@
-/**
- * Moved to the settlement core (ADR 0016): claim push is coordination, and
- * coordination is the product — a contending agent wants `claim_granted`
- * pushed exactly as much as a person does. This path re-exports it so
- * existing importers stay unchanged.
- */
-export { createClaimStream, type ClaimTransport, type ClaimStreamConfig, type AttachableClaimStream, } from '../transaction/coordination/createClaimStream.js';

package/dist/sync/createClaimStream.js

@@ -1,7 +0,0 @@
-/**
- * Moved to the settlement core (ADR 0016): claim push is coordination, and
- * coordination is the product — a contending agent wants `claim_granted`
- * pushed exactly as much as a person does. This path re-exports it so
- * existing importers stay unchanged.
- */
-export { createClaimStream, } from '../transaction/coordination/createClaimStream.js';

package/dist/sync/createPresenceStream.d.ts

@@ -1,69 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import type { WsTransport } from '../transaction/transport/wsTransport.js';
-import type { PresenceStream } from '../transaction/types/streams.js';
-import type { ParticipantKind } from '../transaction/types/participant.js';
-/**
- * The wire capability the presence stream actually uses: subscribe to typed
- * inbound frames, check liveness, and send outbound frames. The duplex
- * `WsTransport` satisfies it — the same port shape the claim stream depends
- * on — so the stream can attach to whatever connection the host built,
- * without naming the engine's subclass.
- */
-export type PresenceTransport = Pick<WsTransport, 'subscribe' | 'isConnected' | 'send'>;
-export interface PresenceStreamConfig {
-    /** Identity used to filter our own echoed frames out of `others`. */
-    participantId: string;
-    /** Optional human label for the self entry. */
-    label?: string;
-    /** Sync groups the participant is broadcasting on. Used for the
-     *  initial `self` entry and for `othersIn(...)` filtering. */
-    syncGroups: readonly string[];
-    /** Marks `self` as an agent. Server is the source of truth for
-     *  peers' `isAgent`, but `self` is local — caller decides. */
-    isAgent?: boolean;
-}
-/** PresenceStream extended with engine-lifecycle hooks. */
-export interface AttachablePresenceStream extends PresenceStream {
-    /** Wire the stream to a now-ready transport. Calls before this are
-     *  buffered (self mutations only — no wire send). Idempotent. */
-    attach(transport: PresenceTransport): void;
-    /**
-     * Seeds the participant identity once the host resolves it. The stream can
-     * be built before identity is known — a hosted client learns who it is
-     * from its credential's scope during connect — and until then the
-     * construction-time values (possibly empty) would leave the `self` entry
-     * blank and let the participant's own echoed frames into `others`. Updates
-     * the `self` entry in place, so held references see the resolved identity.
-     */
-    setParticipant(participant: {
-        id: string;
-        kind?: ParticipantKind;
-        syncGroups?: readonly string[];
-    }): void;
-    /** Tear down listeners. Stream object stays usable as a no-op. */
-    dispose(): void;
-}
-export declare function createPresenceStream(config: PresenceStreamConfig, transport?: PresenceTransport | null): AttachablePresenceStream;

package/dist/sync/createPresenceStream.js

@@ -1,200 +0,0 @@
-/**
- * Creates a {@link PresenceStream} over a live sync connection. Presence is the
- * lightweight, ephemeral "who's here and what are they doing" view: each
- * participant broadcasts a status and an activity, and sees everyone else's.
- * The stream is built directly on the sync WebSocket and adds no second
- * connection. It is the sibling of {@link createClaimStream}, which reuses the
- * same presence frames.
- *
- * There are two ways to construct it:
- *
- *   1. Direct — pass an already-open `transport`, for example an agent worker
- *      or a test.
- *   2. Deferred — construct without a transport and call `attach(transport)`
- *      once the connection is ready. The returned stream object is stable from
- *      construction, so callers can hold the reference and let attachment
- *      happen later.
- *
- * Wire frames:
- *   • Outbound `presence_update` — `{ status, activity? }`. The server stamps
- *       `userId`, `kind`, `timestamp`, and `isAgent`, then broadcasts to the
- *       other participants on the same sync groups.
- *   • Inbound — the same frame, with `kind` one of `enter`, `update`, or
- *       `leave`.
- */
-import { asyncIteratorFrom } from '../transaction/utils/asyncIterator.js';
-import { participantKindFromWire } from '../transaction/coordination/schema.js';
-import { isTargetTuple, subTarget, wireTarget } from '../transaction/coordination/index.js';
-export function createPresenceStream(config, transport = null) {
-    const { label, syncGroups, isAgent = false } = config;
-    // Mutable: the host seeds the resolved identity via `setParticipant` once
-    // it is known; the own-echo filter always reads the current value.
-    let participantId = config.participantId;
-    // ── Self ─────────────────────────────────────────────────────────
-    const self = {
-        participantKind: isAgent ? 'agent' : 'user',
-        participantId,
-        label,
-        syncGroups: [...syncGroups],
-        activity: { entityType: 'Unknown', entityId: '', action: 'idle' },
-        lastActive: new Date().toISOString(),
-    };
-    // ── Others ───────────────────────────────────────────────────────
-    const othersById = new Map();
-    let othersSnapshot = Object.freeze([]);
-    const listeners = new Set();
-    const notifyListeners = () => {
-        othersSnapshot = Object.freeze(Array.from(othersById.values()));
-        for (const l of listeners) {
-            try {
-                l();
-            }
-            catch {
-                /* one bad listener doesn't break the others */
-            }
-        }
-    };
-    // ── Wire wiring ──────────────────────────────────────────────────
-    let attached = null;
-    const unsubs = [];
-    function attach(t) {
-        if (attached)
-            return; // idempotent
-        attached = t;
-        // Reconnect: clear roster (Hub sends fresh snapshot), re-announce
-        // own activity (peers don't auto-learn about us across reconnects).
-        unsubs.push(t.subscribe('connected', () => {
-            if (othersById.size > 0) {
-                othersById.clear();
-                othersSnapshot = Object.freeze([]);
-                notifyListeners();
-            }
-            if (self.activity.entityId)
-                sendUpdate(self.activity);
-        }));
-        // Inbound presence frames arrive in the wire vocabulary
-        // (userId / isAgent / timestamp); translate them into the shape this
-        // stream exposes (participantId / participantKind / lastActive).
-        unsubs.push(t.subscribe('presence_update', (event) => {
-            if (event.userId === participantId)
-                return; // own echo
-            if (!event.userId)
-                return;
-            switch (event.kind) {
-                case 'leave':
-                    if (othersById.delete(event.userId))
-                        notifyListeners();
-                    return;
-                // No `undefined` arm: every site that builds a presence frame stamps
-                // `kind`, and the schema now says so, so an unlabelled frame is not a
-                // shape the transport can hand us.
-                case 'enter':
-                case 'update': {
-                    const entry = {
-                        participantKind: participantKindFromWire(event.participantKind, event.isAgent),
-                        participantId: event.userId,
-                        syncGroups: event.syncGroups ?? [],
-                        activity: event.activity
-                            ? {
-                                ...wireTarget(event.activity),
-                                ...subTarget(event.activity),
-                                action: event.activity.action,
-                                ...(event.activity.detail !== undefined
-                                    ? { detail: event.activity.detail }
-                                    : {}),
-                            }
-                            : { entityType: 'Unknown', entityId: '', action: event.status },
-                        lastActive: event.timestamp
-                            ? new Date(event.timestamp).toISOString()
-                            : new Date().toISOString(),
-                    };
-                    othersById.set(event.userId, entry);
-                    notifyListeners();
-                    return;
-                }
-            }
-        }));
-        // If self was already mutated before attach, broadcast it now.
-        if (self.activity.entityId)
-            sendUpdate(self.activity);
-    }
-    if (transport)
-        attach(transport);
-    // ── Outbound ────────────────────────────────────────────────────
-    // Do not include `isAgent` in the payload. The server derives it
-    // authoritatively from the connection's identity, and letting a client
-    // self-declare it once caused human sessions to broadcast as agents to peers.
-    function sendUpdate(activity) {
-        if (!attached?.isConnected())
-            return; // no-op until connected
-        attached.send({
-            type: 'presence_update',
-            payload: { status: 'online', activity },
-        });
-    }
-    function doUpdate(activity) {
-        self.activity = activity;
-        self.lastActive = new Date().toISOString();
-        sendUpdate(activity);
-    }
-    function resolveTarget(target) {
-        if (isTargetTuple(target)) {
-            return { entityType: target[0], entityId: target[1], action: 'unknown' };
-        }
-        return {
-            ...wireTarget(target),
-            ...subTarget(target),
-            action: 'unknown',
-        };
-    }
-    const withVerb = (action) => (target, detail) => {
-        doUpdate({ ...resolveTarget(target), action, detail });
-    };
-    return {
-        self,
-        update: doUpdate,
-        editing: withVerb('editing'),
-        reading: withVerb('reading'),
-        viewing: withVerb('viewing'),
-        idle: () => {
-            doUpdate({ entityType: 'Unknown', entityId: '', action: 'idle' });
-        },
-        get others() {
-            return othersSnapshot;
-        },
-        othersIn: (syncGroup) => othersSnapshot.filter((e) => e.syncGroups.includes(syncGroup)),
-        onChange: (listener) => {
-            listeners.add(listener);
-            return () => {
-                listeners.delete(listener);
-            };
-        },
-        [Symbol.asyncIterator]() {
-            return asyncIteratorFrom((onChange) => {
-                listeners.add(onChange);
-                return () => {
-                    listeners.delete(onChange);
-                };
-            }, () => othersSnapshot);
-        },
-        attach,
-        setParticipant(participant) {
-            participantId = participant.id;
-            const writable = self;
-            writable.participantId = participant.id;
-            if (participant.kind)
-                writable.participantKind = participant.kind;
-            if (participant.syncGroups)
-                writable.syncGroups = [...participant.syncGroups];
-        },
-        dispose() {
-            for (const off of unsubs)
-                off();
-            unsubs.length = 0;
-            listeners.clear();
-            othersById.clear();
-            othersSnapshot = Object.freeze([]);
-            attached = null;
-        },
-    };
-}

package/dist/sync/createSnapshot.d.ts

@@ -1,29 +0,0 @@
-/**
- * Captures a {@link Snapshot} of a chosen set of entities, along with a
- * watermark, so a caller can detect when that state has gone stale. This is
- * what an LLM caller threads into a prompt: `stamp` flows into later writes as
- * `readAt`, so the server rejects a mutation premised on data that has since
- * changed; `signal` is an `AbortSignal` that fires as soon as any captured
- * entity receives a delta, so a mid-generation invalidation can abort the token
- * stream instead of producing output against stale context.
- *
- * It reads the current entity state from the in-memory pool, reads the engine's
- * current `lastSyncId` as the watermark, and subscribes to delta frames on the
- * existing sync connection — no second connection.
- */
-import type { InstanceCache } from '../InstanceCache.js';
-import type { Schema } from '../transaction/schema/schema.js';
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { Snapshot } from '../transaction/types/streams.js';
-export interface CreateSnapshotArgs<TSchema extends Schema = Schema, K extends keyof TSchema['models'] & string = keyof TSchema['models'] & string> {
-    pool: InstanceCache;
-    /** Live transport for delta subscriptions. May be null if the engine
-     *  hasn't connected yet — the snapshot still resolves with current
-     *  pool state, but `signal` won't fire until reconnect. */
-    transport: SyncWebSocket | null;
-    /** Returns the engine's current `lastSyncId`. Read at snapshot time
-     *  to stamp the watermark; not re-read after. */
-    getLastSyncId: () => number;
-    entities: Readonly<Record<K, string | readonly string[]>>;
-}
-export declare function createSnapshot<TSchema extends Schema, K extends keyof TSchema['models'] & string>(args: CreateSnapshotArgs<TSchema, K>): Snapshot<TSchema, K>;

package/dist/sync/createSnapshot.js

@@ -1,118 +0,0 @@
-/**
- * Captures a {@link Snapshot} of a chosen set of entities, along with a
- * watermark, so a caller can detect when that state has gone stale. This is
- * what an LLM caller threads into a prompt: `stamp` flows into later writes as
- * `readAt`, so the server rejects a mutation premised on data that has since
- * changed; `signal` is an `AbortSignal` that fires as soon as any captured
- * entity receives a delta, so a mid-generation invalidation can abort the token
- * stream instead of producing output against stale context.
- *
- * It reads the current entity state from the in-memory pool, reads the engine's
- * current `lastSyncId` as the watermark, and subscribes to delta frames on the
- * existing sync connection — no second connection.
- */
-import { AbloValidationError } from '../transaction/errors.js';
-import { Model, modelAsRow } from '../Model.js';
-/**
- * The snapshot result exposes `stamp`, `signal`, and `onChange` at its top
- * level, alongside one bucket per model. If a schema declares a model with one
- * of these names, the two would collide, so snapshot creation throws instead.
- */
-const RESERVED_SNAPSHOT_KEYS = new Set([
-    'stamp',
-    'signal',
-    'onChange',
-]);
-export function createSnapshot(args) {
-    const { pool, transport, getLastSyncId, entities } = args;
-    // ── Validate keys ────────────────────────────────────────────────
-    for (const key of Object.keys(entities)) {
-        if (RESERVED_SNAPSHOT_KEYS.has(key)) {
-            throw new AbloValidationError(`engine.snapshot: model key "${key}" collides with a reserved ` +
-                `snapshot field (stamp / signal / onChange). Rename the model ` +
-                'in your schema.', { code: 'snapshot_reserved_key' });
-        }
-    }
-    // ── Watermark ────────────────────────────────────────────────────
-    const stamp = getLastSyncId();
-    // ── Capture data + watched set ───────────────────────────────────
-    const watched = new Set(); // `${type}:${id}`
-    const data = {};
-    for (const [type, idOrIds] of Object.entries(entities)) {
-        const ids = Array.isArray(idOrIds)
-            ? idOrIds
-            : [idOrIds];
-        const bucket = {};
-        for (const id of ids) {
-            const m = pool.get(id);
-            // Only include if the model actually has the requested type —
-            // pool keys models globally by id, so `pool.get(id)` could
-            // return a different model that happens to share the id (rare,
-            // but type guards keep the surface honest).
-            if (m && m instanceof Model && m.getModelName() === type) {
-                bucket[id] = modelAsRow(m);
-            }
-            watched.add(`${type}:${id}`);
-        }
-        data[type] = bucket;
-    }
-    // ── Invalidation wiring ──────────────────────────────────────────
-    const listeners = new Set();
-    const controller = new AbortController();
-    const fireChange = (change) => {
-        if (!controller.signal.aborted) {
-            controller.abort(new Error('snapshot invalidated — underlying entity received a delta'));
-        }
-        for (const l of listeners) {
-            try {
-                l(change);
-            }
-            catch {
-                /* listener errors don't break siblings */
-            }
-        }
-    };
-    let unsubDelta = null;
-    if (transport) {
-        unsubDelta = transport.subscribe('delta', (delta) => {
-            const key = `${delta.modelName}:${delta.modelId}`;
-            if (!watched.has(key))
-                return;
-            // Every delta to a captured entity is reported as 'semantic' severity.
-            fireChange({
-                model: delta.modelName,
-                id: delta.modelId,
-                severity: 'semantic',
-            });
-        });
-    }
-    // ── Build the flat result ────────────────────────────────────────
-    const result = {
-        stamp,
-        signal: controller.signal,
-        onChange: (listener) => {
-            listeners.add(listener);
-            // The caller unsubscribes its own listener via the returned function.
-            // The underlying delta subscription lives for the snapshot's lifetime;
-            // there is no explicit dispose because a snapshot is short-lived (one
-            // LLM call's worth) and the subscription is cheap.
-            return () => {
-                listeners.delete(listener);
-                // Once the last listener is gone and the abort has fired, drop the
-                // delta subscription too — nothing is listening anymore.
-                if (listeners.size === 0 && controller.signal.aborted && unsubDelta) {
-                    unsubDelta();
-                    unsubDelta = null;
-                }
-            };
-        },
-    };
-    for (const [modelName, bucket] of Object.entries(data)) {
-        result[modelName] = bucket;
-    }
-    // Dynamic-shape boundary — `result` is built at runtime by iterating
-    // schema-derived buckets, so it structurally satisfies
-    // `Snapshot<TSchema, K>`. TS can't prove the static cast, but the
-    // runtime invariant holds.
-    return result;
-}

package/dist/sync/credentialLifecycle.d.ts

@@ -1,7 +0,0 @@
-/**
- * Moved to the settlement core with the duplex transport (ADR 0016): keeping
- * a long-lived socket's credential fresh is connection plumbing an agent needs
- * as much as a browser does. This path re-exports it so existing importers
- * stay unchanged.
- */
-export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, type CredentialRefreshOutcome, type CredentialRecoveryOutcome, type CredentialRefreshResult, type CredentialRefresher, type CredentialLifecycleContext, } from '../transaction/transport/credentialLifecycle.js';

package/dist/sync/credentialLifecycle.js

@@ -1,7 +0,0 @@
-/**
- * Moved to the settlement core with the duplex transport (ADR 0016): keeping
- * a long-lived socket's credential fresh is connection plumbing an agent needs
- * as much as a browser does. This path re-exports it so existing importers
- * stay unchanged.
- */
-export { DEFAULT_PREROLL_INTERVAL_MS, MIN_PREROLL_DELAY_MS, computePrerollDelayMs, CredentialLifecycle, } from '../transaction/transport/credentialLifecycle.js';

package/dist/sync/deltaPipeline.d.ts

@@ -1,114 +0,0 @@
-/**
- * The pipeline that takes incoming deltas from the server and lands them in
- * local state. It has four stages: deduplicating deltas by state signature,
- * per-delta bookkeeping and enqueue, a debounce for live traffic, and a flush
- * that writes to the local store and then the in-memory pool. Every call it
- * makes back into the surrounding store — resolving state fields, identifying
- * custom entities, deduplicating, flushing, handling sync-group changes —
- * routes through the {@link DeltaPipelineContext} interface, so a subclass that
- * overrides any of those hooks still takes effect. The atomic frame-apply entry
- * point lives on the store and drives this pipeline through {@link enqueueDelta}
- * and {@link flushPendingDeltas}.
- */
-import type { RuntimeContext } from '../RuntimeContext.js';
-import { ModelScope } from '../InstanceCache.js';
-import type { Model } from '../Model.js';
-import type { SyncDelta } from './SyncWebSocket.js';
-import type { ModelData } from '../transaction/types/modelData.js';
-import { type AbloPlugin, type AppliedChange } from '../transaction/plugin.js';
-/**
- * What the pipeline needs back from the surrounding store: the shared mutable
- * pipeline state (backed by the store's own fields through accessors), narrow
- * persistence and pool facades, and the store's overridable hooks, so a
- * subclass's overrides continue to take effect.
- */
-export interface DeltaPipelineContext {
-    /** The owning client's runtime. Defaults to the module-global bridge. */
-    readonly runtime?: RuntimeContext;
-    /**
-     * The installed plugins, whose declared stage handlers this pipeline
-     * dispatches at each boundary. Empty (or absent) on directly-constructed
-     * stores, where the store's own apply is the whole pipeline.
-     */
-    readonly stagePlugins?: readonly AbloPlugin[];
-    pendingDeltas: SyncDelta[];
-    batchTimer: ReturnType<typeof setTimeout> | null;
-    /** Queue for deltas arriving during an active bootstrap; null when none. */
-    readonly bootstrapDeltaQueue: SyncDelta[] | null;
-    readonly smartSyncOptions: {
-        readonly batchingDelay: number;
-        readonly maxBatchSize: number;
-    };
-    /** Pool-applied cursor (`syncClient.position.applied`). */
-    readonly highestProcessedSyncId: number;
-    /** Resume/ack cursor (`syncClient.position.persisted`). */
-    readonly lastAckedId: number;
-    onDeltaReceived(syncId: number, transactionId?: string, correlationId?: string): void;
-    advanceApplied(syncId: number): void;
-    advancePersisted(syncId: number): void;
-    processDeltaBatch(deltas: {
-        syncId?: number;
-        actionType: SyncDelta['actionType'];
-        modelName: string;
-        modelId: string;
-        data: ModelData | null;
-        transactionId?: string;
-    }[]): Promise<{
-        results: AppliedChange[];
-        persistedSyncId: number;
-    }>;
-    /** Applies persisted delta results to the in-memory pool, with the host's relation enrichment bound. */
-    applyDeltaBatchToPool(results: AppliedChange[]): void;
-    /** Acknowledges a sync id back to the server; a no-op when the socket is down. */
-    acknowledge(syncId: number): void;
-    readonly objectPool: {
-        get(id: string): Model | undefined;
-        add(model: Model, scope: ModelScope): void;
-        remove(id: string): boolean;
-        /** Full in-memory clear — the revocation-failure fallback (see
-         *  {@link handleGroupHandlerFailure}). */
-        clear(): void;
-    };
-    getStateFields(modelName: string): string[];
-    isCustomEntity(modelName: string): boolean;
-    createCustomEntity(modelName: string, modelId: string, data: Record<string, unknown>): Model | null;
-    deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[];
-    flushPendingDeltas(): Promise<void>;
-    handleFlushError(error: unknown): void;
-    handleSyncGroupChange(delta: SyncDelta): Promise<void>;
-    handleGroupRemoved(delta: SyncDelta): Promise<void>;
-    /** Host's re-bootstrap trigger — the revocation-failure fallback. */
-    forceFullRebootstrap(): void;
-    cascadeCancelTransactionsForDeletedParent(parentModelName: string, parentId: string): void;
-}
-/**
- * Handles a sync-group ('G' or 'S') delta whose handler rejected after the
- * applied watermark had already advanced. That delta will never be redelivered,
- * so a failed security clear — revoked data that must not stay cached — would
- * otherwise fail silently. The safe fallback is blunt: drop the whole in-memory
- * pool and force a full re-bootstrap, rebuilding local state from the server.
- * It never throws, because it runs inside the pipeline's fire-and-forget path.
- */
-export declare function handleGroupHandlerFailure(ctx: DeltaPipelineContext, delta: SyncDelta, error: unknown): void;
-/** Deduplicate deltas to the same entity — keep meaningful state transitions only */
-export declare function deduplicateDeltas(ctx: DeltaPipelineContext, deltas: SyncDelta[]): SyncDelta[];
-/**
- * Performs per-delta bookkeeping and enqueues the delta. Returns `true` when
- * the delta was pushed onto `pendingDeltas` — a regular batchable insert,
- * update, covering, or delete that a later flush must drain — and `false` when
- * it was skipped as a duplicate, deferred into the bootstrap queue, or handled
- * immediately (a 'G'/'S' sync-group change). It does not schedule the flush
- * itself; the caller chooses whether to debounce live traffic or flush a
- * catch-up frame atomically.
- */
-export declare function enqueueDelta(ctx: DeltaPipelineContext, delta: SyncDelta, options?: {
-    authoritative?: boolean;
-}): boolean;
-/** Debounce a flush for live single-delta traffic. */
-export declare function scheduleDeltaFlush(ctx: DeltaPipelineContext): void;
-/**
- * Flushes the queued deltas: deduplicates them, applies custom-entity deltas
- * straight to the pool, writes the rest to the local store and then the pool,
- * and advances the acknowledgement cursor once the store write has committed.
- */
-export declare function flushPendingDeltas(ctx: DeltaPipelineContext): Promise<void>;