@abloatai/ablo 0.36.0 → 0.37.0

package/dist/transaction/log/syncDeltaRow.js

@@ -1,95 +0,0 @@
-/**
- * Zod schemas that describe the `sync_deltas` storage row — the durable record of
- * one committed change. The row is split into two slices by the concern each one
- * serves:
- *
- *   - {@link syncDeltaCoreSchema} — the sync-protocol slice: everything a client
- *     needs to reconstruct the change, plus the tenant key. This is a portable
- *     payload shape; it is not a statement that the row is physically stored in
- *     the customer's database.
- *   - {@link deltaAttributionSchema} — who made the change, and on whose authority.
- *
- * {@link syncDeltaRowSchema} composes both into the full stored row.
- * {@link DELTA_DATA_CLASSIFICATION} states which slices contain customer data,
- * while {@link DELTA_PHYSICAL_STORAGE} states where the runtime persists them.
- * Keeping those axes separate prevents a portable schema slice from being cited
- * incorrectly as a physical-residency guarantee.
- *
- * This is the stored shape. The delta broadcast to clients is a narrower projection
- * of it — see {@link import('../wire/delta.js').syncDeltaWireCoreSchema} — and
- * the field names here mirror those on that wire delta.
- */
-import { z } from 'zod';
-import { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, } from '../wire/delta.js';
-// ── Enumerations that mirror the corresponding Postgres enum types ────────────
-// `participant_kind` and `confirmation_state` are shared with the wire delta and
-// live at the wire layer (see `../wire/delta.js`); they are re-exported here so
-// code that imports them from `schema` keeps resolving.
-export { participantKindSchema, confirmationStateSchema } from '../wire/delta.js';
-/** `backfill_provenance` */
-export const backfillProvenanceSchema = z.enum(['exact', 'inferred', 'unknown']);
-/** A delta payload: the full post-mutation row (or null for deletes). */
-const deltaDataSchema = z.record(z.string(), z.unknown()).nullable();
-// ── Core — the sync-protocol slice ────────────────────────────────────────────
-/**
- * Everything a client needs to materialize the change, plus the tenant key. This
- * is the portable shape an authoritative WAL change or endpoint event carries.
- * The runtime persists the resulting full row in Ablo's tenant-scoped ordered
- * sync log; it is not written atomically with a direct application-row mutation.
- * `id`, `createdAt`, and `syncGroups` are assigned when the source change is
- * appended, so they are optional at the ingestion boundary.
- */
-export const syncDeltaCoreSchema = z.object({
-    /** Monotonically increasing sync id, assigned by the server when the delta is appended; absent on an outbox marker. */
-    id: z.union([z.bigint(), z.number()]).optional(),
-    /** The `action_type` column; its eight values are owned by the wire delta contract. */
-    actionType: syncDeltaActionSchema,
-    modelName: z.string().min(1),
-    modelId: z.string().min(1),
-    data: deltaDataSchema,
-    previousData: deltaDataSchema.optional(),
-    /** Routing keys that decide which subscribers receive this delta; computed by the server at append time. */
-    syncGroups: z.array(z.string()).optional(),
-    /** The committing organization id — the coarse-grained tenant-isolation boundary. */
-    organizationId: z.string().nullable(),
-    /** ISO 8601 timestamp, assigned by the server when the delta is appended. */
-    createdAt: z.string().optional(),
-    transactionId: z.string().nullable(),
-    /**
-     * Stable identity of the authoritative WAL row or endpoint event. It is
-     * nullable for hosted/legacy rows and is never exposed as the optimistic
-     * client transaction id.
-     */
-    sourceChangeId: z.string().min(1).nullable().optional(),
-});
-// ── Attribution — who made the change, and on whose authority ─────────────────
-export const deltaAttributionSchema = z.object({
-    /** The acting participant, recorded as a single column for compatibility; the structured pair below is the richer form. */
-    createdBy: z.string().nullable(),
-    actorId: z.string().nullable(),
-    actorKind: participantKindSchema.nullable(),
-    onBehalfOfId: z.string().nullable(),
-    onBehalfOfKind: participantKindSchema.nullable(),
-    capabilityId: z.string().nullable(),
-    delegationChainRootUserId: z.string().nullable().optional(),
-    confirmationState: confirmationStateSchema.nullable(),
-    backfillProvenance: backfillProvenanceSchema.nullable(),
-});
-// ── Full stored row, classification, and physical storage ─────────────────────
-/** The complete `sync_deltas` row: core and attribution combined. */
-export const syncDeltaRowSchema = syncDeltaCoreSchema.extend(deltaAttributionSchema.shape);
-/** Which slices contain retained customer row data versus control metadata. */
-export const DELTA_DATA_CLASSIFICATION = {
-    core: 'customer-data',
-    attribution: 'control-metadata',
-};
-/**
- * Where the current runtime physically persists each slice. Both live in
- * Ablo's tenant-scoped `sync_deltas` log. `core` contains full post-change row
- * payloads (and optional previous payloads), so `control` here must not be read
- * as "metadata only."
- */
-export const DELTA_PHYSICAL_STORAGE = {
-    core: 'control',
-    attribution: 'control',
-};

package/dist/transaction/logPosition.d.ts

@@ -1,97 +0,0 @@
-/**
- * Records where this client stands in the global delta order. It is a single
- * typed object holding three related but distinct positions, each with its own
- * rule for when it may advance. Keeping them separate is deliberate: collapsing
- * them into one counter is a classic source of sync bugs.
- *
- *   - `persisted` — the resume cursor. It advances only after deltas have
- *     committed to durable local storage. This is the value reconnect catch-up
- *     sends to the server, so it must never run ahead of what actually landed
- *     on disk; otherwise the server would skip deltas the client never stored.
- *
- *   - `applied` — the in-memory cursor: the last delta applied to the object
- *     pool. It drives the guards that deduplicate and reject replayed deltas.
- *     It may run ahead of `persisted`, because the pool is updated before the
- *     flush to disk, and behind what has merely been received, because
- *     bootstrap-queued deltas arrive before they are applied.
- *
- *   - `acked` — the highest server position acknowledged for this client's own
- *     commits. An acknowledgement at N means the server applied our write at N;
- *     the optimistic pool already reflects it, so for the entities we wrote we
- *     have effectively read through N even before the echo returns on the
- *     stream.
- *
- * One value is derived: `readFloor` is the greater of `applied` and `acked`,
- * and is the only position a snapshot or claim should stamp as its read point.
- * Using the raw stream cursor alone would make a claim taken right after a
- * confirmed write look stale against that write's own delta; using the raw
- * acknowledgement alone would be wrong for read-only clients. The maximum is
- * correct per entity, because a competing change to an entity we just wrote
- * necessarily lands above our acknowledgement and still rejects as stale.
- *
- * The validation schema is the state shape: the class holds exactly one
- * {@link LogPositionSnapshot} and merges monotonically into it, so snapshot
- * and restore share that shape and {@link parseLogPosition} is the single gate
- * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
- * being a known failure mode.
- */
-import { z } from 'zod';
-export declare const logPositionSchema: z.ZodObject<{
-    persisted: z.ZodNumber;
-    applied: z.ZodNumber;
-    acked: z.ZodNumber;
-}, z.core.$strip>;
-export type LogPositionSnapshot = z.infer<typeof logPositionSchema>;
-/**
- * Only the `persisted` cursor is stored durably; `applied` and `acked` are
- * not. On resume the object pool is rebuilt from the persisted state, so the
- * correct restore is simply to advance `persisted` to the stored value, which
- * also implies `applied`. `acked` starts at zero, because a past session's
- * acknowledgements carry no read authority and the offline queue
- * re-acknowledges its own replays.
- */
-/**
- * Validates an untrusted value, such as one loaded from disk, into a position
- * snapshot, or returns null when it does not match the schema.
- */
-export declare function parseLogPosition(value: unknown): LogPositionSnapshot | null;
-/**
- * The live sync position: one instance per client. Three producers each
- * advance their own cursor, and consumers read the result.
- */
-export declare class LogPosition {
-    #private;
-    /** Returns a copy of the current state in the schema's shape. */
-    snapshot(): LogPositionSnapshot;
-    get persisted(): number;
-    get applied(): number;
-    get acked(): number;
-    /** The position a snapshot or claim stamps as its read point: the greater of `applied` and `acked`. */
-    get readFloor(): number;
-    /**
-     * Records that deltas through `syncId` have committed to durable local
-     * storage. This also advances `applied`, since the flush applies each delta
-     * before or as it persists.
-     */
-    advancePersisted(syncId: number): void;
-    /** Records that a delta was applied to the in-memory object pool. */
-    advanceApplied(syncId: number): void;
-    /** Records that the server acknowledged one of this client's commits at the given position. */
-    noteAck(lastSyncId: number | undefined): void;
-    /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
-    restore(snapshot: LogPositionSnapshot): void;
-}
-/** @deprecated Renamed to {@link logPositionSchema}. Removed in 0.36.0. */
-export declare const syncPositionSchema: z.ZodObject<{
-    persisted: z.ZodNumber;
-    applied: z.ZodNumber;
-    acked: z.ZodNumber;
-}, z.core.$strip>;
-/** @deprecated Renamed to {@link LogPositionSnapshot}. Removed in 0.36.0. */
-export type SyncPositionSnapshot = LogPositionSnapshot;
-/** @deprecated Renamed to {@link parseLogPosition}. Removed in 0.36.0. */
-export declare const parseSyncPosition: typeof parseLogPosition;
-/** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
-export declare const SyncPosition: typeof LogPosition;
-/** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
-export type SyncPosition = LogPosition;

package/dist/transaction/logPosition.js

@@ -1,125 +0,0 @@
-/**
- * Records where this client stands in the global delta order. It is a single
- * typed object holding three related but distinct positions, each with its own
- * rule for when it may advance. Keeping them separate is deliberate: collapsing
- * them into one counter is a classic source of sync bugs.
- *
- *   - `persisted` — the resume cursor. It advances only after deltas have
- *     committed to durable local storage. This is the value reconnect catch-up
- *     sends to the server, so it must never run ahead of what actually landed
- *     on disk; otherwise the server would skip deltas the client never stored.
- *
- *   - `applied` — the in-memory cursor: the last delta applied to the object
- *     pool. It drives the guards that deduplicate and reject replayed deltas.
- *     It may run ahead of `persisted`, because the pool is updated before the
- *     flush to disk, and behind what has merely been received, because
- *     bootstrap-queued deltas arrive before they are applied.
- *
- *   - `acked` — the highest server position acknowledged for this client's own
- *     commits. An acknowledgement at N means the server applied our write at N;
- *     the optimistic pool already reflects it, so for the entities we wrote we
- *     have effectively read through N even before the echo returns on the
- *     stream.
- *
- * One value is derived: `readFloor` is the greater of `applied` and `acked`,
- * and is the only position a snapshot or claim should stamp as its read point.
- * Using the raw stream cursor alone would make a claim taken right after a
- * confirmed write look stale against that write's own delta; using the raw
- * acknowledgement alone would be wrong for read-only clients. The maximum is
- * correct per entity, because a competing change to an entity we just wrote
- * necessarily lands above our acknowledgement and still rejects as stale.
- *
- * The validation schema is the state shape: the class holds exactly one
- * {@link LogPositionSnapshot} and merges monotonically into it, so snapshot
- * and restore share that shape and {@link parseLogPosition} is the single gate
- * for anything loaded from disk — a corrupted cursor stored "ahead of reality"
- * being a known failure mode.
- */
-import { z } from 'zod';
-export const logPositionSchema = z.object({
-    /** The resume cursor; advances only after deltas persist to durable local storage. */
-    persisted: z.number().int().nonnegative(),
-    /** The in-memory cursor: the last delta applied to the object pool. */
-    applied: z.number().int().nonnegative(),
-    /** The highest server position acknowledged for this client's own commits. */
-    acked: z.number().int().nonnegative(),
-});
-/**
- * Only the `persisted` cursor is stored durably; `applied` and `acked` are
- * not. On resume the object pool is rebuilt from the persisted state, so the
- * correct restore is simply to advance `persisted` to the stored value, which
- * also implies `applied`. `acked` starts at zero, because a past session's
- * acknowledgements carry no read authority and the offline queue
- * re-acknowledges its own replays.
- */
-/**
- * Validates an untrusted value, such as one loaded from disk, into a position
- * snapshot, or returns null when it does not match the schema.
- */
-export function parseLogPosition(value) {
-    const result = logPositionSchema.safeParse(value);
-    return result.success ? result.data : null;
-}
-const ZERO = { persisted: 0, applied: 0, acked: 0 };
-/** Monotonic merge: each cursor only ever moves forward. */
-function advance(state, next) {
-    return {
-        persisted: Math.max(state.persisted, next.persisted ?? 0),
-        applied: Math.max(state.applied, next.applied ?? 0),
-        acked: Math.max(state.acked, next.acked ?? 0),
-    };
-}
-/**
- * The live sync position: one instance per client. Three producers each
- * advance their own cursor, and consumers read the result.
- */
-export class LogPosition {
-    #state = ZERO;
-    /** Returns a copy of the current state in the schema's shape. */
-    snapshot() {
-        return { ...this.#state };
-    }
-    get persisted() {
-        return this.#state.persisted;
-    }
-    get applied() {
-        return this.#state.applied;
-    }
-    get acked() {
-        return this.#state.acked;
-    }
-    /** The position a snapshot or claim stamps as its read point: the greater of `applied` and `acked`. */
-    get readFloor() {
-        return Math.max(this.#state.applied, this.#state.acked);
-    }
-    /**
-     * Records that deltas through `syncId` have committed to durable local
-     * storage. This also advances `applied`, since the flush applies each delta
-     * before or as it persists.
-     */
-    advancePersisted(syncId) {
-        this.#state = advance(this.#state, { persisted: syncId, applied: syncId });
-    }
-    /** Records that a delta was applied to the in-memory object pool. */
-    advanceApplied(syncId) {
-        this.#state = advance(this.#state, { applied: syncId });
-    }
-    /** Records that the server acknowledged one of this client's commits at the given position. */
-    noteAck(lastSyncId) {
-        if (lastSyncId !== undefined)
-            this.#state = advance(this.#state, { acked: lastSyncId });
-    }
-    /** Restores from an already-validated snapshot, for example on resume from disk. The merge is monotonic. */
-    restore(snapshot) {
-        this.#state = advance(this.#state, snapshot);
-    }
-}
-// ── Deprecated aliases (renamed from the sync/syncPosition module, 2026-07-17) ──
-// The position is a participant's place in the transaction log; the old names
-// said the consumer. Same class, same instanceof identity. Removed in 0.36.0.
-/** @deprecated Renamed to {@link logPositionSchema}. Removed in 0.36.0. */
-export const syncPositionSchema = logPositionSchema;
-/** @deprecated Renamed to {@link parseLogPosition}. Removed in 0.36.0. */
-export const parseSyncPosition = parseLogPosition;
-/** @deprecated Renamed to {@link LogPosition}. Removed in 0.36.0. */
-export const SyncPosition = LogPosition;

package/dist/transaction/logger.d.ts

@@ -1,16 +0,0 @@
-/**
- * The logging port the SDK writes through.
- *
- * A contract with no framework and no local state: credential exchange, commit,
- * and claim all need to log with no UI and no offline store present, so the port
- * belongs to the settlement core (ADR 0016). The consumer supplies the
- * implementation; the SDK ships a no-op default.
- */
-export interface Logger {
-    debug(message: string, ...args: unknown[]): void;
-    info(message: string, ...args: unknown[]): void;
-    warn(message: string, ...args: unknown[]): void;
-    error(message: string, ...args: unknown[]): void;
-}
-/** The no-op default — what the core logs through when no logger is wired. */
-export declare const noopLogger: Logger;

package/dist/transaction/logger.js

@@ -1,7 +0,0 @@
-/** The no-op default — what the core logs through when no logger is wired. */
-export const noopLogger = {
-    debug() { },
-    info() { },
-    warn() { },
-    error() { },
-};

package/dist/transaction/observability.d.ts

@@ -1,53 +0,0 @@
-/**
- * The observability the settlement core reports on its own behalf.
- *
- * Coordination outcomes — a claim changing state, a stale-write collision that
- * notified instead of aborting — happen with no UI and no local store anywhere,
- * so the core must be able to report them without depending on the consumer's
- * full provider (ADR 0016).
- *
- * This is deliberately the narrow set the core actually calls today. Widening it
- * later is non-breaking; the reactive engine's `ObservabilityProvider` extends
- * this interface, so a single implementation still satisfies both.
- */
-import type { ClaimEvent, ConflictEvent } from './coordination/events.js';
-export interface CoordinationObservability {
-    /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired). */
-    captureClaim(event: ClaimEvent): void;
-    /** Capture a notify-instead-of-abort stale-write collision. */
-    captureConflict(event: ConflictEvent): void;
-}
-/** Breadcrumb severity levels */
-export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
-/** Breadcrumb categories for sync engine lifecycle events */
-export type BreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.coordination' | 'sync.groups';
-export interface WebSocketErrorDetails {
-    context: string;
-    error?: string;
-    code?: number;
-    reason?: string;
-}
-/**
- * The observability the duplex transport reports on its own behalf: connection
- * lifecycle breadcrumbs and socket errors. A server-side agent holding a socket
- * for claim push has no store and no UI, so the transport must be able to
- * report without the consumer's full provider — the same reasoning as
- * {@link CoordinationObservability}, one layer down. The reactive engine's
- * `ObservabilityProvider` extends this interface, so a single implementation
- * satisfies both.
- */
-export interface TransportObservability {
-    /** Add a breadcrumb for sync lifecycle events */
-    breadcrumb(message: string, category: BreadcrumbCategory, level?: BreadcrumbLevel, data?: Record<string, string | number | boolean | undefined>): void;
-    /** Capture WebSocket error */
-    captureWebSocketError(details: WebSocketErrorDetails): void;
-}
-/**
- * Everything the duplex transport reports: its own lifecycle
- * ({@link TransportObservability}) plus the coordination outcomes that ride
- * the socket ({@link CoordinationObservability} — claim pushes and notified
- * collisions arrive as frames, so the transport is where they surface).
- */
-export type SocketObservability = TransportObservability & CoordinationObservability;
-/** The no-op default — what the transport reports through when nothing is wired. */
-export declare const noopSocketObservability: SocketObservability;

package/dist/transaction/observability.js

@@ -1,19 +0,0 @@
-/**
- * The observability the settlement core reports on its own behalf.
- *
- * Coordination outcomes — a claim changing state, a stale-write collision that
- * notified instead of aborting — happen with no UI and no local store anywhere,
- * so the core must be able to report them without depending on the consumer's
- * full provider (ADR 0016).
- *
- * This is deliberately the narrow set the core actually calls today. Widening it
- * later is non-breaking; the reactive engine's `ObservabilityProvider` extends
- * this interface, so a single implementation still satisfies both.
- */
-/** The no-op default — what the transport reports through when nothing is wired. */
-export const noopSocketObservability = {
-    breadcrumb() { },
-    captureWebSocketError() { },
-    captureClaim() { },
-    captureConflict() { },
-};

package/dist/transaction/persistence.d.ts

@@ -1,12 +0,0 @@
-/**
- * Local persistence modes. `'memory'` (the default everywhere outside the
- * browser) keeps the local graph in process memory; `'indexeddb'` adds
- * offline queueing and a reload-surviving cache in the browser.
- */
-export type AbloPersistence = 'memory' | 'indexeddb';
-export interface PersistenceOptions {
-    readonly persistence?: AbloPersistence | undefined;
-    readonly inMemory?: boolean | undefined;
-    readonly offline?: boolean | undefined;
-}
-export declare function shouldUseInMemoryPersistence(options: PersistenceOptions): boolean;

package/dist/transaction/persistence.js

@@ -1,11 +0,0 @@
-export function shouldUseInMemoryPersistence(options) {
-    if (typeof window === 'undefined')
-        return true;
-    if (options.persistence)
-        return options.persistence === 'memory';
-    if (typeof options.inMemory === 'boolean')
-        return options.inMemory;
-    if (options.offline === true)
-        return false;
-    return true;
-}