@abloatai/ablo 0.26.0 → 0.28.0

package/dist/server/read-config.d.ts

@@ -1,67 +0,0 @@
-/**
- * `@abloatai/ablo/server` — per-model READ configuration the bootstrap
- * reader consumes. Host-side type config (physical table, tenancy column,
- * parent-scoping) — pure data, no `postgres` — so it lives in the server
- * subpath and feeds the `DataAdapter` read contract. The SQL that consumes it
- * (the bootstrap query builder) stays host-side.
- */
-/** A field→column mapping with an explicit post-`SELECT *` alias. */
-export interface ColumnOverride {
-    readonly field: string;
-    readonly column: string;
-    readonly alias: string;
-}
-export interface BootstrapModel {
-    name: string;
-    /**
-     * Additional names accepted for request-side lookup/filtering. In DB-canonical
-     * mode `name` stays the physical table name, while aliases cover generated
-     * compatibility names such as `WeatherReports` / `weatherReports`.
-     */
-    aliases?: readonly string[];
-    /**
-     * Schema key used by source endpoints. `name` remains the wire/result model
-     * name, usually the typename; source handlers are keyed by the developer's
-     * schema object (`files`, `slideLayers`, ...).
-     */
-    sourceModel?: string;
-    table: string;
-    syncGroups?: string[];
-    enabled?: boolean;
-    /** Max rows to return. Omit for unlimited. Maps to schema's bootstrapLimit. */
-    limit?: number;
-    /** SQL ORDER BY clause. Default: 'id'. Maps to schema's bootstrapOrderBy. */
-    orderBy?: string;
-    /** Whether the table has organization_id. Default: true. */
-    orgScoped?: boolean;
-    /** Physical tenancy column (default `organization_id`, configurable per model). */
-    orgColumn?: string;
-    /**
-     * Parent-table scoping for rows with no `organization_id` column. Mirrors the
-     * schema's `scopedVia` option. When set, the bootstrap query emits:
-     *
-     *   WHERE <table>.<localKey> IN
-     *     (SELECT <parentKey> FROM <parentTable> WHERE <parentOrgColumn> = $1)
-     *
-     * Applied IN ADDITION TO whatever `orgScoped` dictates — so a table can have
-     * its own `organization_id` AND further narrow via a parent, though the common
-     * use is `orgScoped: false` + `scopedVia` on tables that lack the column.
-     */
-    scopedVia?: {
-        localKey: string;
-        parentTable: string;
-        parentKey?: string;
-        parentOrgColumn?: string;
-    };
-    /** Client-facing field name → physical DB column for declared fields. */
-    fieldColumns?: Record<string, string>;
-    /** Physical-column aliases needed after SELECT * for `.from(...)` fields. */
-    columnOverrides?: readonly ColumnOverride[];
-    /**
-     * Physical columns the schema declares as `json` (`field.json()`). A json
-     * field stored in a TEXT column comes back from `row_to_json` as a serialized
-     * string; the bootstrap re-parses these so the wire is the canonical object
-     * regardless of physical column type (jsonb returns objects natively → no-op).
-     */
-    jsonColumns?: readonly string[];
-}

package/dist/server/read-config.js

@@ -1,8 +0,0 @@
-/**
- * `@abloatai/ablo/server` — per-model READ configuration the bootstrap
- * reader consumes. Host-side type config (physical table, tenancy column,
- * parent-scoping) — pure data, no `postgres` — so it lives in the server
- * subpath and feeds the `DataAdapter` read contract. The SQL that consumes it
- * (the bootstrap query builder) stays host-side.
- */
-export {};

package/dist/server/storage-mode.d.ts

@@ -1,8 +0,0 @@
-/** See module note — host-deployment vocabulary, never customer-facing. */
-export declare const storageModeSchema: z.ZodEnum<{
-    source: "source";
-    hosted: "hosted";
-    selfHosted: "selfHosted";
-}>;
-/** See module note — host-deployment vocabulary, never customer-facing. */
-export type StorageMode = z.infer<typeof storageModeSchema>;

package/dist/server/storage-mode.js

@@ -1,28 +0,0 @@
-/**
- * `@abloatai/ablo/server` — the storage-mode vocabulary the `DataAdapter`
- * contract supports. Analogous to Better Auth's adapter `id`/`adapterId`: a
- * diagnostic discriminator on the adapter, NOT a routing switch (routing goes
- * through the resolver/factory). The package owns this enum so the contract and
- * every host adapter agree on the closed set:
- *   - `hosted`     — Ablo's control-plane database.
- *   - `selfHosted` — the customer's database, same execution path as hosted.
- *   - `source`     — a customer-owned endpoint (credentialless ingestion).
- *
- * Deployment topology, not product vocabulary. Customers never see a
- * "storage mode" — their story is `ablo connect` (WAL replication: reads tail
- * their database's logical-replication stream, the data stays in their DB)
- * with the signed `dataSource()` endpoint as the marked fallback (ADR 0002,
- * docs/decisions/0002-read-path-logical-replication-vs-data-hosting.md).
- * The `databaseUrl` dial-in that this enum's `selfHosted` arm serves is
- * DEPRECATED pending the WAL read cutover — do not build on it.
- * This export exists for the sync-server host only.
- *
- * NOT `@internal`-tagged: tsconfig.build.json sets `stripInternal`, and these
- * symbols are re-exported by `server/index.ts` — tagging them strips them from
- * the emitted d.ts, leaving an empty `export {}` module behind a live
- * re-export. `skipLibCheck` masks the break and `StorageMode` silently
- * degrades to an error-any for every dist consumer (the sync-server host).
- */
-import { z } from 'zod';
-/** See module note — host-deployment vocabulary, never customer-facing. */
-export const storageModeSchema = z.enum(['hosted', 'source', 'selfHosted']);

package/dist/source/connector-protocol.d.ts

@@ -1,159 +0,0 @@
-/**
- * Data Source reverse-channel wire protocol.
- *
- * The `commit`/`load`/`list` leg of Data Source mode is normally an INBOUND
- * webhook (Ablo Cloud → your HTTPS endpoint). That requires a public URL, so it
- * doesn't work on `localhost` or inside a locked-down VPC with no inbound path.
- *
- * The reverse channel inverts the direction: the customer's connector dials OUT
- * to Ablo Cloud over a WebSocket and serves those same requests over the open
- * socket — the Stripe-CLI `stripe listen` pattern. This module defines the
- * frames that travel over that socket.
- *
- * Trust model is unchanged. A `request` frame carries the SAME Standard Webhooks
- * signature headers (`webhook-id` / `webhook-timestamp` / `webhook-signature`)
- * and the SAME raw body Ablo would have POSTed, so the connector verifies it
- * through the unchanged `verifyAbloSourceRequest`. Only the transport differs.
- *
- * Frames are validated with zod at the boundary (matching `contract.ts`): a
- * malformed frame is rejected at the edge, and every wire type is inferred from
- * one schema so the two sides can never silently drift.
- */
-import { z } from 'zod';
-/**
- * Wire-protocol version. Bumped on any breaking frame-shape change so an old
- * connector talking to a new server (or vice-versa) fails fast at `register`
- * instead of misparsing a frame mid-stream.
- */
-export declare const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
-/** Path the connector dials. Appended to the connector's `baseURL`. */
-export declare const SOURCE_CONNECTOR_WS_PATH = "/v1/source/listen";
-/**
- * Negotiated WebSocket subprotocol that marks a reverse-channel source
- * connector (vs. the SDK sync client's `ablo.sync.v1`). The server selects and
- * echoes back ONLY this value, never the token-bearing subprotocol — keeping the
- * credential out of ALB / proxy logs exactly like the sync socket does.
- */
-export declare const WS_SOURCE_SUBPROTOCOL = "ablo.source.v1";
-/**
- * Build the `Sec-WebSocket-Protocol` list a connector offers: the source
- * protocol plus the bearer credential (`ablo.bearer.<apiKey>`). Browsers can't
- * set an `Authorization` header on a WebSocket, so the API key rides as a
- * subprotocol — the same mechanism the SDK sync client uses, read server-side by
- * the shared `extractBearer`.
- */
-export declare function sourceConnectorSubprotocols(apiKey: string): string[];
-/**
- * Connector → server, first frame after the socket opens and authenticates.
- * Auth and source resolution happen at the WS handshake from the API key; this
- * frame only carries protocol negotiation + advisory metadata.
- */
-export declare const registerFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"register">;
-    protocolVersion: z.ZodNumber;
-    client: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type RegisterFrame = z.infer<typeof registerFrameSchema>;
-/**
- * Server → connector, acknowledges a successful `register`. Echoes the resolved
- * source identity so the connector can log/verify which source it is serving.
- */
-export declare const readyFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"ready">;
-    protocolVersion: z.ZodNumber;
-    sourceId: z.ZodOptional<z.ZodString>;
-    organizationId: z.ZodOptional<z.ZodString>;
-    environment: z.ZodOptional<z.ZodEnum<{
-        production: "production";
-        sandbox: "sandbox";
-    }>>;
-}, z.core.$strip>;
-export type ReadyFrame = z.infer<typeof readyFrameSchema>;
-/**
- * Server → connector, one drained `commit`/`load`/`list` request. `headers` and
- * `body` are byte-identical to what the inbound webhook path would have sent —
- * the connector replays them into a synthesized `Request` so the unchanged
- * handler verifies the signature exactly as in production.
- */
-export declare const requestFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"request">;
-    id: z.ZodString;
-    method: z.ZodLiteral<"POST">;
-    url: z.ZodString;
-    headers: z.ZodRecord<z.ZodString, z.ZodString>;
-    body: z.ZodString;
-}, z.core.$strip>;
-export type RequestFrame = z.infer<typeof requestFrameSchema>;
-/**
- * Connector → server, the handler's `Response` for one `request`. The server
- * resolves the pending request keyed by `id` and feeds `status`/`body` back to
- * the `SourceClient` as if an HTTP response had returned.
- */
-export declare const responseFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"response">;
-    id: z.ZodString;
-    status: z.ZodNumber;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    body: z.ZodString;
-}, z.core.$strip>;
-export type ResponseFrame = z.infer<typeof responseFrameSchema>;
-/**
- * Either direction, out-of-band failure not tied to a single request body
- * (auth rejected, unsupported protocol version, malformed frame). When `id` is
- * present the error pertains to that pending request and fails it; otherwise it
- * is a connection-level error.
- */
-export declare const errorFrameSchema: z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    id: z.ZodOptional<z.ZodString>;
-    code: z.ZodString;
-    message: z.ZodString;
-}, z.core.$strip>;
-export type ErrorFrame = z.infer<typeof errorFrameSchema>;
-export declare const connectorFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"register">;
-    protocolVersion: z.ZodNumber;
-    client: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"ready">;
-    protocolVersion: z.ZodNumber;
-    sourceId: z.ZodOptional<z.ZodString>;
-    organizationId: z.ZodOptional<z.ZodString>;
-    environment: z.ZodOptional<z.ZodEnum<{
-        production: "production";
-        sandbox: "sandbox";
-    }>>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"request">;
-    id: z.ZodString;
-    method: z.ZodLiteral<"POST">;
-    url: z.ZodString;
-    headers: z.ZodRecord<z.ZodString, z.ZodString>;
-    body: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"response">;
-    id: z.ZodString;
-    status: z.ZodNumber;
-    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    body: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"error">;
-    id: z.ZodOptional<z.ZodString>;
-    code: z.ZodString;
-    message: z.ZodString;
-}, z.core.$strip>], "type">;
-export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
-/** Thrown when an incoming frame fails to parse or validate. */
-export declare class ConnectorProtocolError extends Error {
-    readonly code = "source_connector_protocol_error";
-    constructor(message: string);
-}
-/** Serialize a frame for transmission. */
-export declare function encodeFrame(frame: ConnectorFrame): string;
-/**
- * Parse + validate an incoming frame. Accepts the string or binary payloads the
- * `ws` library / WebSocket `message` events deliver. Throws
- * `ConnectorProtocolError` on any malformed or unknown frame so callers can
- * reject the connection rather than act on garbage.
- */
-export declare function decodeFrame(raw: string | ArrayBuffer | Uint8Array): ConnectorFrame;

package/dist/source/connector-protocol.js

@@ -1,161 +0,0 @@
-/**
- * Data Source reverse-channel wire protocol.
- *
- * The `commit`/`load`/`list` leg of Data Source mode is normally an INBOUND
- * webhook (Ablo Cloud → your HTTPS endpoint). That requires a public URL, so it
- * doesn't work on `localhost` or inside a locked-down VPC with no inbound path.
- *
- * The reverse channel inverts the direction: the customer's connector dials OUT
- * to Ablo Cloud over a WebSocket and serves those same requests over the open
- * socket — the Stripe-CLI `stripe listen` pattern. This module defines the
- * frames that travel over that socket.
- *
- * Trust model is unchanged. A `request` frame carries the SAME Standard Webhooks
- * signature headers (`webhook-id` / `webhook-timestamp` / `webhook-signature`)
- * and the SAME raw body Ablo would have POSTed, so the connector verifies it
- * through the unchanged `verifyAbloSourceRequest`. Only the transport differs.
- *
- * Frames are validated with zod at the boundary (matching `contract.ts`): a
- * malformed frame is rejected at the edge, and every wire type is inferred from
- * one schema so the two sides can never silently drift.
- */
-import { z } from 'zod';
-import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
-/**
- * Wire-protocol version. Bumped on any breaking frame-shape change so an old
- * connector talking to a new server (or vice-versa) fails fast at `register`
- * instead of misparsing a frame mid-stream.
- */
-export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
-/** Path the connector dials. Appended to the connector's `baseURL`. */
-export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
-/**
- * Negotiated WebSocket subprotocol that marks a reverse-channel source
- * connector (vs. the SDK sync client's `ablo.sync.v1`). The server selects and
- * echoes back ONLY this value, never the token-bearing subprotocol — keeping the
- * credential out of ALB / proxy logs exactly like the sync socket does.
- */
-export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
-/**
- * Build the `Sec-WebSocket-Protocol` list a connector offers: the source
- * protocol plus the bearer credential (`ablo.bearer.<apiKey>`). Browsers can't
- * set an `Authorization` header on a WebSocket, so the API key rides as a
- * subprotocol — the same mechanism the SDK sync client uses, read server-side by
- * the shared `extractBearer`.
- */
-export function sourceConnectorSubprotocols(apiKey) {
-    return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
-}
-const headerRecord = z.record(z.string(), z.string());
-/**
- * Connector → server, first frame after the socket opens and authenticates.
- * Auth and source resolution happen at the WS handshake from the API key; this
- * frame only carries protocol negotiation + advisory metadata.
- */
-export const registerFrameSchema = z.object({
-    type: z.literal('register'),
-    protocolVersion: z.number().int(),
-    /**
-     * Advisory client identifier (e.g. `@abloatai/ablo@0.12.0`) for server-side
-     * logging. Not trusted for any decision.
-     */
-    client: z.string().optional(),
-});
-/**
- * Server → connector, acknowledges a successful `register`. Echoes the resolved
- * source identity so the connector can log/verify which source it is serving.
- */
-export const readyFrameSchema = z.object({
-    type: z.literal('ready'),
-    protocolVersion: z.number().int(),
-    sourceId: z.string().optional(),
-    organizationId: z.string().optional(),
-    environment: z.enum(['production', 'sandbox']).optional(),
-});
-/**
- * Server → connector, one drained `commit`/`load`/`list` request. `headers` and
- * `body` are byte-identical to what the inbound webhook path would have sent —
- * the connector replays them into a synthesized `Request` so the unchanged
- * handler verifies the signature exactly as in production.
- */
-export const requestFrameSchema = z.object({
-    type: z.literal('request'),
-    /** Correlation id; the matching `response` frame carries the same value. */
-    id: z.string().min(1),
-    method: z.literal('POST'),
-    /** Synthetic absolute URL used only to construct the `Request` object. */
-    url: z.string().min(1),
-    /** Signed Standard Webhooks headers + `Content-Type`. */
-    headers: headerRecord,
-    /** Raw JSON request body — exactly the bytes that were signed. */
-    body: z.string(),
-});
-/**
- * Connector → server, the handler's `Response` for one `request`. The server
- * resolves the pending request keyed by `id` and feeds `status`/`body` back to
- * the `SourceClient` as if an HTTP response had returned.
- */
-export const responseFrameSchema = z.object({
-    type: z.literal('response'),
-    id: z.string().min(1),
-    status: z.number().int(),
-    headers: headerRecord.optional(),
-    /** Raw JSON response body. */
-    body: z.string(),
-});
-/**
- * Either direction, out-of-band failure not tied to a single request body
- * (auth rejected, unsupported protocol version, malformed frame). When `id` is
- * present the error pertains to that pending request and fails it; otherwise it
- * is a connection-level error.
- */
-export const errorFrameSchema = z.object({
-    type: z.literal('error'),
-    id: z.string().min(1).optional(),
-    code: z.string().min(1),
-    message: z.string(),
-});
-export const connectorFrameSchema = z.discriminatedUnion('type', [
-    registerFrameSchema,
-    readyFrameSchema,
-    requestFrameSchema,
-    responseFrameSchema,
-    errorFrameSchema,
-]);
-/** Thrown when an incoming frame fails to parse or validate. */
-export class ConnectorProtocolError extends Error {
-    code = 'source_connector_protocol_error';
-    constructor(message) {
-        super(message);
-        this.name = 'ConnectorProtocolError';
-    }
-}
-/** Serialize a frame for transmission. */
-export function encodeFrame(frame) {
-    return JSON.stringify(frame);
-}
-/**
- * Parse + validate an incoming frame. Accepts the string or binary payloads the
- * `ws` library / WebSocket `message` events deliver. Throws
- * `ConnectorProtocolError` on any malformed or unknown frame so callers can
- * reject the connection rather than act on garbage.
- */
-export function decodeFrame(raw) {
-    const text = typeof raw === 'string' ? raw : decodeBinary(raw);
-    let parsed;
-    try {
-        parsed = JSON.parse(text);
-    }
-    catch {
-        throw new ConnectorProtocolError('Frame is not valid JSON');
-    }
-    const result = connectorFrameSchema.safeParse(parsed);
-    if (!result.success) {
-        throw new ConnectorProtocolError(`Invalid connector frame: ${result.error.message}`);
-    }
-    return result.data;
-}
-function decodeBinary(raw) {
-    const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
-    return new TextDecoder().decode(bytes);
-}

package/dist/transactions/OptimisticEchoTracker.d.ts

@@ -1,82 +0,0 @@
-/**
- * OptimisticEchoTracker — receive-layer reconciliation primitive.
- *
- * Tracks the set of transaction ids the client has applied locally
- * but the server has not yet confirmed. When a sync delta arrives
- * carrying a `transactionId` the tracker recognizes, the pool
- * mutation is suppressed (the optimistic write already reflects it).
- * Drained when the matching delta echo lands or when the originating
- * transaction is rolled back.
- *
- * Architectural framing: see
- * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. This is the
- * "discriminator at the apply layer" the doc names — without it the
- * authoritative-layer apply path blindly re-applies confirmations on
- * top of whatever optimistic state has since diverged, producing the
- * chart-delete flicker.
- *
- * Bounded by `maxSize` to defend against runaway growth from a
- * pathological "transactions never confirmed and never rolled back"
- * loop. When the bound is hit, the OLDEST id is evicted (FIFO via
- * insertion-ordered Map). Eviction means a future echo of that
- * transaction will be applied as a foreign mutation — no correctness
- * risk for the originating tab (the pool already reflects the local
- * write); the worst case is a single redundant pool re-set.
- */
-export interface OptimisticEchoTrackerOptions {
-    /**
-     * Hard upper bound on tracked ids. FIFO eviction beyond this. The
-     * default of 10_000 covers a 200-tab user mid-bulk-edit (each tab
-     * tracking dozens of unconfirmed transactions) with two orders of
-     * magnitude of headroom.
-     */
-    maxSize?: number;
-}
-export interface OptimisticEchoMetrics {
-    /** Total ids currently tracked. */
-    size: number;
-    /** Cumulative ids ever added since construction. */
-    totalAdded: number;
-    /** Cumulative successful echo matches (delta arrived → drained). */
-    hits: number;
-    /** Cumulative explicit rollback drains (transaction never made it). */
-    rollbacks: number;
-    /** Cumulative ids evicted due to maxSize pressure. */
-    evictions: number;
-}
-export declare class OptimisticEchoTracker {
-    private readonly ids;
-    private readonly maxSize;
-    private _totalAdded;
-    private _hits;
-    private _rollbacks;
-    private _evictions;
-    constructor(options?: OptimisticEchoTrackerOptions);
-    /**
-     * Mark a transaction as locally-applied. The next sync delta with a
-     * matching `transactionId` will be recognized as the server's
-     * confirmation of this same write. Idempotent — repeated calls with
-     * the same id are no-ops.
-     */
-    markPending(transactionId: string): void;
-    /**
-     * If the id is currently tracked, drain it and return true (signal
-     * to the caller: this is an echo, skip the pool mutation).
-     * Otherwise return false (foreign mutation, apply normally).
-     *
-     * Combined check+drain into one method to make the receive-path
-     * idiom hard to misuse: a separate `has` then `drain` would race
-     * if multiple deltas with the same id arrived in the same batch.
-     */
-    consumeEcho(transactionId: string | null | undefined): boolean;
-    /**
-     * Drain on rollback. The transaction was cancelled before a server
-     * confirmation arrived — no echo will ever come, so the pending
-     * entry would otherwise leak. Counts as a separate metric category
-     * so a spike of `rollbacks` (vs `hits`) signals network or
-     * server-side health issues.
-     */
-    drainOnRollback(transactionId: string): void;
-    getMetrics(): Readonly<OptimisticEchoMetrics>;
-    clear(): void;
-}

package/dist/transactions/OptimisticEchoTracker.js

@@ -1,104 +0,0 @@
-/**
- * OptimisticEchoTracker — receive-layer reconciliation primitive.
- *
- * Tracks the set of transaction ids the client has applied locally
- * but the server has not yet confirmed. When a sync delta arrives
- * carrying a `transactionId` the tracker recognizes, the pool
- * mutation is suppressed (the optimistic write already reflects it).
- * Drained when the matching delta echo lands or when the originating
- * transaction is rolled back.
- *
- * Architectural framing: see
- * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. This is the
- * "discriminator at the apply layer" the doc names — without it the
- * authoritative-layer apply path blindly re-applies confirmations on
- * top of whatever optimistic state has since diverged, producing the
- * chart-delete flicker.
- *
- * Bounded by `maxSize` to defend against runaway growth from a
- * pathological "transactions never confirmed and never rolled back"
- * loop. When the bound is hit, the OLDEST id is evicted (FIFO via
- * insertion-ordered Map). Eviction means a future echo of that
- * transaction will be applied as a foreign mutation — no correctness
- * risk for the originating tab (the pool already reflects the local
- * write); the worst case is a single redundant pool re-set.
- */
-const DEFAULT_MAX_SIZE = 10_000;
-export class OptimisticEchoTracker {
-    // Map (not Set) for O(1) FIFO eviction via insertion order.
-    // Value is unused; Map.keys() iterates in insertion order so
-    // `keys().next()` yields the oldest id.
-    ids = new Map();
-    maxSize;
-    // Metrics — internal counters; exposed via `getMetrics()`. Kept
-    // numeric (not BigInt) since cumulative-since-page-load fits well
-    // under Number.MAX_SAFE_INTEGER for any realistic session.
-    _totalAdded = 0;
-    _hits = 0;
-    _rollbacks = 0;
-    _evictions = 0;
-    constructor(options = {}) {
-        this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
-    }
-    /**
-     * Mark a transaction as locally-applied. The next sync delta with a
-     * matching `transactionId` will be recognized as the server's
-     * confirmation of this same write. Idempotent — repeated calls with
-     * the same id are no-ops.
-     */
-    markPending(transactionId) {
-        if (this.ids.has(transactionId))
-            return;
-        if (this.ids.size >= this.maxSize) {
-            const oldest = this.ids.keys().next().value;
-            if (oldest !== undefined) {
-                this.ids.delete(oldest);
-                this._evictions += 1;
-            }
-        }
-        this.ids.set(transactionId, true);
-        this._totalAdded += 1;
-    }
-    /**
-     * If the id is currently tracked, drain it and return true (signal
-     * to the caller: this is an echo, skip the pool mutation).
-     * Otherwise return false (foreign mutation, apply normally).
-     *
-     * Combined check+drain into one method to make the receive-path
-     * idiom hard to misuse: a separate `has` then `drain` would race
-     * if multiple deltas with the same id arrived in the same batch.
-     */
-    consumeEcho(transactionId) {
-        if (!transactionId)
-            return false;
-        if (!this.ids.has(transactionId))
-            return false;
-        this.ids.delete(transactionId);
-        this._hits += 1;
-        return true;
-    }
-    /**
-     * Drain on rollback. The transaction was cancelled before a server
-     * confirmation arrived — no echo will ever come, so the pending
-     * entry would otherwise leak. Counts as a separate metric category
-     * so a spike of `rollbacks` (vs `hits`) signals network or
-     * server-side health issues.
-     */
-    drainOnRollback(transactionId) {
-        if (this.ids.delete(transactionId)) {
-            this._rollbacks += 1;
-        }
-    }
-    getMetrics() {
-        return {
-            size: this.ids.size,
-            totalAdded: this._totalAdded,
-            hits: this._hits,
-            rollbacks: this._rollbacks,
-            evictions: this._evictions,
-        };
-    }
-    clear() {
-        this.ids.clear();
-    }
-}

package/dist/transactions/mutation-error-handler.d.ts

@@ -1,5 +0,0 @@
-/**
- * Shared error handler for mutation execution.
- * Logs to SyncObservability (unless offline + network error), then re-throws.
- */
-export declare function handleMutationError(error: unknown, context: string, schemaName: string, modelId: string): never;

package/dist/transactions/mutation-error-handler.js

@@ -1,39 +0,0 @@
-import { getContext } from "../context.js";
-/**
- * Shared error handler for mutation execution.
- * Logs to SyncObservability (unless offline + network error), then re-throws.
- */
-export function handleMutationError(error, context, schemaName, modelId) {
-    const errorInfo = { schemaName, modelId, rawError: error };
-    if (error instanceof Error) {
-        errorInfo.message = error.message;
-        errorInfo.name = error.name;
-        errorInfo.stack =
-            typeof error.stack === 'string' ? error.stack.split('\n').slice(0, 5) : undefined;
-    }
-    else if (error && typeof error === 'object') {
-        errorInfo.message =
-            error.message ??
-                error.error ??
-                'Unknown error';
-        errorInfo.code = error.code;
-        errorInfo.extensions = error.extensions;
-    }
-    else {
-        errorInfo.message = String(error);
-    }
-    const isOffline = !getContext().onlineStatus.isOnline();
-    const msg = errorInfo.message;
-    const isNetworkError = msg?.includes('Failed to fetch') ||
-        msg?.includes('Network request failed') ||
-        msg?.includes('NetworkError');
-    if (!isOffline || !isNetworkError) {
-        getContext().observability.captureTransactionFailure({
-            context,
-            error: error instanceof Error ? error : String(errorInfo.message ?? error),
-            modelName: schemaName,
-            modelId,
-        });
-    }
-    throw error;
-}