@abloatai/ablo 0.9.2 → 0.9.3

package/dist/client/Ablo.d.ts

@@ -121,7 +121,7 @@ export interface AbloOptions<S extends SchemaRecord = SchemaRecord> {
      * Local persistence mode. Pass `indexeddb` only when you want offline
      * queueing and a reload-surviving browser cache.
      *
-     * @default 'volatile'
+     * @default 'memory'
      */
     persistence?: AbloPersistence;
     /**
@@ -250,7 +250,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     /** ObjectPool size limit (default: 10000) */
     maxPoolSize?: number;
     /**
-     * Local persistence mode. Defaults to `volatile` so Ablo behaves like a
+     * Local persistence mode. Defaults to `memory` so Ablo behaves like a
      * point solution for shared state instead of silently bolting IndexedDB
      * durability onto every browser consumer.
      *
@@ -262,7 +262,7 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
     offline?: boolean;
     /**
      * @deprecated Internal/testing escape hatch. Use `persistence` in
-     * production code. `true` maps to `volatile`; `false` maps to
+     * production code. `true` maps to `memory`; `false` maps to
      * `indexeddb` in browsers.
      */
     inMemory?: boolean;
@@ -463,6 +463,15 @@ export interface CommitCreateOptions {
     readonly idempotencyKey?: string | null;
     readonly readAt?: number | null;
     readonly onStale?: 'reject' | 'force' | 'flag' | 'merge' | null;
+    /**
+     * A claim handle from `ablo.<model>.claim({ id })` (or the HTTP claim
+     * surface). Same vocabulary as the per-model writes: the handle's
+     * snapshot watermark becomes the batch `readAt` default and `onStale`
+     * defaults to `'reject'`, so a commit that follows a claim is guarded
+     * against concurrent edits without re-stating the watermark by hand.
+     * Explicit `readAt`/`onStale` on the options win.
+     */
+    readonly claim?: ClaimHandle<Record<string, unknown>> | null;
     readonly operation?: CommitOperationInput;
     readonly operations?: readonly CommitOperationInput[];
     readonly wait?: CommitWait;

package/dist/client/Ablo.js

@@ -41,6 +41,7 @@ import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue,
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
+import { assertWriteOptions } from './writeOptionsSchema.js';
 // ── Config derivation from schema ─────────────────────────────────────────
 /**
  * Compute a create-priority map from schema `belongsTo` relations using
@@ -1065,6 +1066,12 @@ export function Ablo(options) {
             return intent;
         return intent?.id;
     }
+    function isClaimHandleValue(value) {
+        return (typeof value === 'object' &&
+            value !== null &&
+            value.object === 'claim' &&
+            typeof value.claimId === 'string');
+    }
     function normalizeCommitOperation(op, defaults) {
         const model = op.model ?? op.target?.model;
         if (!model) {
@@ -1341,10 +1348,26 @@ export function Ablo(options) {
     const commits = {
         async create(commitOptions) {
             await ready();
+            // Same runtime contract as the per-model writes — one schema.
+            assertWriteOptions({
+                idempotencyKey: commitOptions.idempotencyKey,
+                readAt: commitOptions.readAt,
+                onStale: commitOptions.onStale,
+                wait: commitOptions.wait,
+                intent: commitOptions.intent,
+            }, 'commits.create');
             const clientTxId = createClientTxId(commitOptions.idempotencyKey);
-            const operations = normalizeCommitOperations(commitOptions);
+            // A claim handle supplies the batch stale-guard defaults — same
+            // semantics as `ablo.<model>.update({ id, data, claim })`, so the
+            // two write doors speak one claim vocabulary. Explicit options win.
+            const claim = commitOptions.claim ?? null;
+            const operations = normalizeCommitOperations({
+                ...commitOptions,
+                readAt: commitOptions.readAt ?? claim?.readAt ?? null,
+                onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
+            });
             const wait = commitOptions.wait ?? 'confirmed';
-            const intentId = normalizeIntentId(commitOptions.intent);
+            const intentId = normalizeIntentId(commitOptions.intent) ?? claim?.claimId;
             void intentId; // The current wire clears intents by entity after commit.
             // Route through the TransactionQueue's commit lane so the call
             // tolerates WS disconnects: the envelope stays in memory until
@@ -1422,6 +1445,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {
@@ -1440,6 +1464,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {
@@ -1458,6 +1483,7 @@ export function Ablo(options) {
                     idempotencyKey: params.idempotencyKey,
                     readAt: params.readAt,
                     onStale: params.onStale,
+                    ...(isClaimHandleValue(params.claim) ? { claim: params.claim } : {}),
                     wait: params.wait,
                     operations: [
                         {

package/dist/client/ApiClient.js

@@ -8,6 +8,7 @@
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, translateHttpError, } from '../errors.js';
 import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, } from './auth.js';
 import { toSeconds } from '../utils/duration.js';
+import { assertWriteOptions } from './writeOptionsSchema.js';
 const DEFAULT_AGENT_LEASE = '10m';
 export function createProtocolClient(options) {
     const env = readProcessEnv();
@@ -223,15 +224,30 @@ export function createProtocolClient(options) {
     }
     const commits = {
         async create(commitOptions) {
+            // Same runtime contract as every other write door — one schema.
+            assertWriteOptions({
+                idempotencyKey: commitOptions.idempotencyKey,
+                readAt: commitOptions.readAt,
+                onStale: commitOptions.onStale,
+                wait: commitOptions.wait,
+                intent: commitOptions.intent,
+            }, 'commits.create');
             const clientTxId = createClientTxId(commitOptions.idempotencyKey);
-            const operations = normalizeCommitOperations(commitOptions);
+            // Same claim vocabulary as the WS client's `commits.create`: a handle
+            // supplies the batch stale-guard defaults; explicit options win.
+            const claim = commitOptions.claim ?? null;
+            const operations = normalizeCommitOperations({
+                ...commitOptions,
+                readAt: commitOptions.readAt ?? claim?.readAt ?? null,
+                onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
+            });
             const body = await requestJson('/v1/commits', {
                 method: 'POST',
                 idempotencyKey: clientTxId,
                 body: JSON.stringify({
                     clientTxId,
                     idempotencyKey: clientTxId,
-                    intent: normalizeIntentId(commitOptions.intent),
+                    intent: normalizeIntentId(commitOptions.intent) ?? claim?.claimId,
                     operations,
                 }),
             });
@@ -435,17 +451,33 @@ export function createProtocolClient(options) {
      * envelopes — this helper is the one-op, one-record path only.
      */
     async function mutateModel(action, modelName, id, data, options) {
+        assertWriteOptions(options && {
+            idempotencyKey: options.idempotencyKey,
+            readAt: options.readAt,
+            onStale: options.onStale,
+            wait: options.wait,
+            intent: options.intent,
+        }, `${modelName} ${action}`);
         const clientTxId = createClientTxId(options?.idempotencyKey);
         const encModel = encodeURIComponent(modelName);
         const path = action === 'create'
             ? `/v1/models/${encModel}`
             : `/v1/models/${encModel}/${encodeURIComponent(id)}`;
         const method = action === 'create' ? 'POST' : action === 'update' ? 'PATCH' : 'DELETE';
+        // A carried claim handle supplies the stale-guard defaults — one claim
+        // vocabulary across the WS proxy, `commits.create`, and these routes.
+        const claimHandle = typeof options?.claim === 'object' &&
+            options?.claim !== null &&
+            options.claim.object === 'claim' &&
+            typeof options.claim.claimId === 'string'
+            ? options.claim
+            : undefined;
+        const readAt = options?.readAt ?? claimHandle?.readAt;
         const requestBody = {
             idempotencyKey: clientTxId,
-            intent: normalizeIntentId(options?.intent),
-            onStale: options?.onStale,
-            readAt: options?.readAt,
+            intent: normalizeIntentId(options?.intent) ?? claimHandle?.claimId,
+            onStale: options?.onStale ?? (claimHandle?.readAt !== undefined ? 'reject' : undefined),
+            readAt,
         };
         if (action === 'create')
             requestBody.id = id;
@@ -503,11 +535,12 @@ export function createProtocolClient(options) {
         const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), { method: 'DELETE' }).then(() => undefined);
         async function claimImpl(params) {
             const claimId = await acquireClaim(params);
-            const { data } = await retrieveModel(name, { id: params.id });
+            const { data, stamp } = await retrieveModel(name, { id: params.id });
             const release = () => releaseClaim(params);
             return {
                 object: 'claim',
                 claimId,
+                readAt: stamp,
                 target: {
                     model: name,
                     id: params.id,

package/dist/client/createInternalComponents.js

@@ -42,7 +42,7 @@ export function createInternalComponents(input) {
     const database = new Database(modelRegistry, bootstrapHelper, {
         // Point-solution default: no browser-local durable store unless the
         // caller explicitly asks for it. Node/edge runtimes always use the
-        // volatile store because IndexedDB is unavailable there.
+        // in-memory store because IndexedDB is unavailable there.
         inMemory: shouldUseInMemoryPersistence(options),
     });
     const syncClient = new SyncClient(objectPool, database);

package/dist/client/createModelProxy.d.ts

@@ -212,6 +212,15 @@ export interface ClaimReorderParams<T = Record<string, unknown>> extends ClaimLo
 export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposable {
     readonly object: 'claim';
     readonly claimId: string;
+    /**
+     * Sync watermark of the held snapshot (`data` was read at this stamp).
+     * Writes that carry the handle — `update({ id, data, claim })` or
+     * `commits.create({ claim, ... })` — use it as the `readAt` stale guard,
+     * so a concurrent commit between snapshot and write is rejected instead
+     * of clobbered. Optional for wire/duck-type compat with externally
+     * constructed handles.
+     */
+    readonly readAt?: number;
     readonly target: {
         readonly model: string;
         readonly id: string;

package/dist/client/createModelProxy.js

@@ -17,6 +17,7 @@
 import { autorun } from 'mobx';
 import { AbloClaimedError, AbloValidationError, toAbloError, } from '../errors.js';
 import { Model, modelAsRow } from '../Model.js';
+import { assertWriteOptions } from './writeOptionsSchema.js';
 import { ModelScope } from '../types/index.js';
 const modelClientMeta = new WeakMap();
 export function getModelClientMeta(modelClient) {
@@ -76,6 +77,10 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     };
     const mutationOptions = (params) => {
         const { id: _id, data: _data, claim: _claim, ...rest } = params;
+        // THE write-options schema — runtime twin of the compile-time params.
+        // Catches plain-JS callers (`onStale: 'rejct'`) at the call site with
+        // a typed error instead of a silent no-op or a server 400.
+        assertWriteOptions(rest, `${schemaKey} write`);
         return rest;
     };
     const releaseClaim = async (id) => {
@@ -154,6 +159,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         return {
             object: 'claim',
             claimId: lease.id,
+            readAt: snapshot.stamp,
             target,
             action: options?.action ?? 'editing',
             ...(options?.description ? { description: options.description } : {}),
@@ -235,8 +241,6 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             return this.getAll(options).length;
         },
         create: guard(async (params) => {
-            // TODO(options-persistence): stash `params` alongside the
-            // queued transaction so idempotencyKey survives offline flush.
             const id = params.id ?? Model.generateId();
             const opts = mutationOptions(params);
             const claim = params.claim;
@@ -260,8 +264,15 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     maxQueueDepth: claim.maxQueueDepth,
                 });
             }
+            // Default `organizationId` from the client's identity exactly like the
+            // mutator path (`buildModelForCreate`) — without this, a caller that
+            // omits it creates an org-unscoped row on one write door but not the
+            // other. An explicit value in `data` still wins via the spread.
+            const orgDefault = params.data.organizationId ??
+                syncClient.getOrganizationId();
             const model = new ModelClass({
                 id,
+                ...(orgDefault != null ? { organizationId: orgDefault } : {}),
                 ...params.data,
                 createdAt: new Date(),
                 updatedAt: new Date(),
@@ -299,9 +310,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
             // watermark + lease so it's stale-rejected and attributed to the claim.
             const claimed = activeClaims.get(id);
             const opts = mutationOptions(params);
-            const handleIntent = isClaimHandle(params.claim)
-                ? { id: params.claim.claimId }
-                : undefined;
+            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
             const effective = claimed
                 ? {
                     wait: 'confirmed',
@@ -311,8 +320,18 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     ...opts,
                 }
                 : {
+                    // A carried handle engages the same stale guard as a claim this
+                    // proxy took itself — the watermark rides on the handle, so it
+                    // works across clients (HTTP-minted handles included).
+                    ...(handle?.readAt !== undefined
+                        ? {
+                            wait: 'confirmed',
+                            readAt: handle.readAt,
+                            onStale: 'reject',
+                        }
+                        : {}),
                     ...opts,
-                    ...(handleIntent ? { intent: handleIntent } : {}),
+                    ...(handle ? { intent: { id: handle.claimId } } : {}),
                 };
             // Local user update: `applyChanges` keeps change tracking ON so
             // the edited fields land in `modifiedProperties` and actually get
@@ -341,9 +360,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 throw new AbloValidationError(`Entity not found: ${registeredModelName}/${id}`, { code: 'entity_not_found' });
             const claimed = activeClaims.get(id);
             const opts = mutationOptions(params);
-            const handleIntent = isClaimHandle(params.claim)
-                ? { id: params.claim.claimId }
-                : undefined;
+            const handle = isClaimHandle(params.claim) ? params.claim : undefined;
             const effective = claimed
                 ? {
                     wait: 'confirmed',
@@ -353,8 +370,15 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                     ...opts,
                 }
                 : {
+                    ...(handle?.readAt !== undefined
+                        ? {
+                            wait: 'confirmed',
+                            readAt: handle.readAt,
+                            onStale: 'reject',
+                        }
+                        : {}),
                     ...opts,
-                    ...(handleIntent ? { intent: handleIntent } : {}),
+                    ...(handle ? { intent: { id: handle.claimId } } : {}),
                 };
             syncClient.delete(model, effective);
             await waitForMutation(model, effective);

package/dist/client/persistence.d.ts

@@ -1,4 +1,9 @@
-export type AbloPersistence = 'volatile' | 'indexeddb';
+/**
+ * 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;

package/dist/client/persistence.js

@@ -2,7 +2,7 @@ export function shouldUseInMemoryPersistence(options) {
     if (typeof window === 'undefined')
         return true;
     if (options.persistence)
-        return options.persistence === 'volatile';
+        return options.persistence === 'memory';
     if (typeof options.inMemory === 'boolean')
         return options.inMemory;
     if (options.offline === true)

package/dist/client/registerDataSource.d.ts

@@ -11,9 +11,9 @@ export interface RegisterDataSourceInput {
     readonly fetchImpl?: typeof fetch;
 }
 /**
- * POST the connection string to the self-serve direct connector route. Resolves
- * on success (the org is now a dedicated tenant pointed at this DB); throws an
- * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
- * surfaces it instead of silently bootstrapping against the wrong store.
+ * POST the connection string to the self-serve datasource route. Resolves on
+ * success (the org's data plane now points at this DB); throws an `AbloError`
+ * with `datasource_registration_failed` otherwise so `ready()` surfaces it
+ * instead of silently bootstrapping against the wrong store.
  */
 export declare function registerDataSource(input: RegisterDataSourceInput): Promise<void>;

package/dist/client/registerDataSource.js

@@ -1,12 +1,13 @@
 /**
- * Self-serve direct-Postgres connector registration.
- *
- * Historical note: this module name says "DataSource", but this path registers
- * a direct database URL. It is not the signed `dataSource(...)` endpoint path.
+ * Self-serve direct-kind datasource registration.
  *
  * When a client is constructed with `databaseUrl`, the SDK registers that
  * connection string BEFORE bootstrap so the server resolves the org's data plane
- * to that direct connector.
+ * to that direct connection.
+ *
+ * Targets the unified `POST /v1/datasources` resource; on a 404 (an older
+ * server without the unified route) it falls back to the legacy
+ * `POST /v1/datasource` alias so an SDK upgrade never strands registration.
  *
  * The org is derived server-side from the API key — the caller never sends an
  * organization id. The connection string is sent once over TLS and is never
@@ -15,36 +16,43 @@
  */
 import { AbloError } from '../errors.js';
 /**
- * POST the connection string to the self-serve direct connector route. Resolves
- * on success (the org is now a dedicated tenant pointed at this DB); throws an
- * `AbloError` with `datasource_registration_failed` otherwise so `ready()`
- * surfaces it instead of silently bootstrapping against the wrong store.
+ * POST the connection string to the self-serve datasource route. Resolves on
+ * success (the org's data plane now points at this DB); throws an `AbloError`
+ * with `datasource_registration_failed` otherwise so `ready()` surfaces it
+ * instead of silently bootstrapping against the wrong store.
  */
 export async function registerDataSource(input) {
     if (!input.apiKey) {
-        throw new AbloError('databaseUrl requires an apiKey to register the direct Postgres connector (the org is derived from the key).', { code: 'datasource_registration_failed' });
+        throw new AbloError('databaseUrl requires an apiKey to register the database connection (the org is derived from the key).', { code: 'datasource_registration_failed' });
     }
     const doFetch = input.fetchImpl ?? fetch;
-    const endpoint = `${input.baseUrl.replace(/\/+$/, '')}/v1/datasource`;
-    let response;
-    try {
-        response = await doFetch(endpoint, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                authorization: `Bearer ${input.apiKey}`,
-            },
-            body: JSON.stringify({
-                connectionString: input.databaseUrl,
-                ...(input.schema ? { schema: input.schema } : {}),
-            }),
-        });
-    }
-    catch (cause) {
-        throw new AbloError('Could not reach the Ablo API to register the direct Postgres connector.', {
-            code: 'datasource_registration_failed',
-            cause,
-        });
+    const base = input.baseUrl.replace(/\/+$/, '');
+    const body = JSON.stringify({
+        connectionString: input.databaseUrl,
+        ...(input.schema ? { schema: input.schema } : {}),
+    });
+    const post = async (endpoint) => {
+        try {
+            return await doFetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${input.apiKey}`,
+                },
+                body,
+            });
+        }
+        catch (cause) {
+            throw new AbloError('Could not reach the Ablo API to register the database connection.', {
+                code: 'datasource_registration_failed',
+                cause,
+            });
+        }
+    };
+    let response = await post(`${base}/v1/datasources`);
+    if (response.status === 404) {
+        // Older server without the unified resource — use the legacy alias.
+        response = await post(`${base}/v1/datasource`);
     }
     if (!response.ok) {
         let detail = '';
@@ -54,6 +62,6 @@ export async function registerDataSource(input) {
         catch {
             // ignore body read failures — the status alone is enough to fail loud
         }
-        throw new AbloError(`Direct Postgres connector registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
+        throw new AbloError(`Database connection registration failed (HTTP ${response.status}). ${detail}`, { code: 'datasource_registration_failed', httpStatus: response.status });
     }
 }

package/dist/client/writeOptionsSchema.d.ts

@@ -0,0 +1,50 @@
+/**
+ * THE write-options schema — one Zod schema for the write dialect every
+ * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
+ * HTTP model routes). Validated once at each public boundary so a plain-JS
+ * caller passing `onStale: 'rejct'` fails loudly at the call site with a
+ * typed `AbloValidationError`, not silently (or 400) at the server.
+ *
+ * Mirrors `source/contract.ts`: the schema is the runtime twin of the
+ * `MutationOptions` interface, with a compile-time drift guard at the
+ * bottom so the two can never silently diverge.
+ *
+ * Validation-only by design: callers keep their ORIGINAL options object.
+ * Zod's parse output strips unknown keys, and the `intent` slot legally
+ * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * `release`/`revoke` functions must survive — so we assert, never replace.
+ */
+import { z } from 'zod';
+export declare const onStaleModeSchema: z.ZodEnum<{
+    reject: "reject";
+    force: "force";
+    flag: "flag";
+    merge: "merge";
+}>;
+export declare const writeOptionsSchema: z.ZodObject<{
+    idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    wait: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        queued: "queued";
+    }>>;
+    readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        reject: "reject";
+        force: "force";
+        flag: "flag";
+        merge: "merge";
+    }>>>;
+    intent: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$loose>]>>>;
+    causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type WriteOptionsInput = z.infer<typeof writeOptionsSchema>;
+/**
+ * Assert a write-options bag against THE schema. Throws a typed
+ * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
+ * `param` pointing at the offending field) and returns nothing — the
+ * caller keeps its original object.
+ */
+export declare function assertWriteOptions(value: unknown, context?: string): void;

package/dist/client/writeOptionsSchema.js

@@ -0,0 +1,57 @@
+/**
+ * THE write-options schema — one Zod schema for the write dialect every
+ * door speaks (`ablo.<model>.create/update/delete`, `commits.create`, the
+ * HTTP model routes). Validated once at each public boundary so a plain-JS
+ * caller passing `onStale: 'rejct'` fails loudly at the call site with a
+ * typed `AbloValidationError`, not silently (or 400) at the server.
+ *
+ * Mirrors `source/contract.ts`: the schema is the runtime twin of the
+ * `MutationOptions` interface, with a compile-time drift guard at the
+ * bottom so the two can never silently diverge.
+ *
+ * Validation-only by design: callers keep their ORIGINAL options object.
+ * Zod's parse output strips unknown keys, and the `intent` slot legally
+ * carries live handles (`IntentLeaseHandle` / claim leases) whose
+ * `release`/`revoke` functions must survive — so we assert, never replace.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+export const onStaleModeSchema = z.enum(['reject', 'force', 'flag', 'merge']);
+export const writeOptionsSchema = z.object({
+    /** Server-side mutation_log cache key; `null` opts out of retry-safety. */
+    idempotencyKey: z.string().min(1).max(255).nullish(),
+    /** Human-readable audit tag, persisted to `mutation_log.label`. */
+    label: z.string().max(255).optional(),
+    /** Resolve when queued locally (default) or once the server confirms. */
+    wait: z.enum(['queued', 'confirmed']).optional(),
+    /** Stale guard: the sync watermark the caller's reasoning was based on. */
+    readAt: z.number().int().nonnegative().nullish(),
+    /** What the server does when the target moved past `readAt`. */
+    onStale: onStaleModeSchema.nullish(),
+    /** Claim/intent attribution — an id, or a live lease handle (loose: the
+     *  handle's `release`/`revoke` functions ride along untouched). */
+    intent: z.union([z.string(), z.looseObject({ id: z.string() })]).nullish(),
+    /** Dormant wire-compat field; always `null` from current clients. */
+    causedByTaskId: z.string().nullish(),
+});
+/**
+ * Assert a write-options bag against THE schema. Throws a typed
+ * `AbloValidationError` (`code: 'write_options_invalid'`, Stripe-style
+ * `param` pointing at the offending field) and returns nothing — the
+ * caller keeps its original object.
+ */
+export function assertWriteOptions(value, context) {
+    if (value == null)
+        return;
+    const result = writeOptionsSchema.safeParse(value);
+    if (result.success)
+        return;
+    const issue = result.error.issues[0];
+    const path = issue?.path.map(String).join('.') ?? '';
+    throw new AbloValidationError(`Invalid write options${context ? ` on \`${context}\`` : ''}${path ? ` at \`${path}\`` : ''}: ${issue?.message ?? 'failed validation'}.`, {
+        code: 'write_options_invalid',
+        ...(path ? { param: path } : {}),
+    });
+}
+const _writeOptionsContractInSync = [true, true];
+void _writeOptionsContractInSync;

package/dist/core/index.d.ts

@@ -1,36 +1,28 @@
 /**
  * @abloatai/ablo/core — Framework extension
  *
- * Only imported by SyncedStore.ts and ApplicationStore.ts —
- * the 2-3 files that extend or orchestrate the sync engine.
- * Regular model files and components should NOT import from here.
+ * Only imported by the handful of files that extend or orchestrate the
+ * sync engine (the app-shell store/provider stack, sync adapters, demo
+ * harnesses). Regular model files and components should NOT import from
+ * here — the consumer surface is `Ablo({ schema })` on the root.
+ *
+ * TRIMMED to what framework-level consumers actually import (verified by
+ * a monorepo-wide import scan). Everything else the engine defines stays
+ * module-private: if a new framework concern genuinely needs another
+ * primitive, add the export deliberately — don't re-widen the barrel.
  */
-export { BaseSyncedStore, type SyncStatus, type UserContext, type SyncedStoreConfig, type QueryResult, type SmartSyncOptions, type ModelConstructor, type ConcreteModelConstructor, BOOTSTRAP_CONFIG, } from '../BaseSyncedStore.js';
-export { SyncClient, type RehydrationStats } from '../SyncClient.js';
-export { Database, type BootstrapResult, type BootstrapRequirements } from '../Database.js';
+export { BaseSyncedStore, type ModelConstructor, type ConcreteModelConstructor, } from '../BaseSyncedStore.js';
+export { SyncClient } from '../SyncClient.js';
+export { Database } from '../Database.js';
 export { ObjectPool, ModelScope } from '../ObjectPool.js';
 export { Model } from '../Model.js';
-export { LazyReferenceCollection, type LazyCollectionOptions } from '../LazyReferenceCollection.js';
+export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyReferenceCollection.js';
+export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
-export { probeNetwork, type ProbeResult } from '../sync/NetworkProbe.js';
-export { ConnectionManager, type ConnectionState, type ConnectionEvent, type ConnectionCallbacks, type ConnectionManagerOptions, } from '../sync/ConnectionManager.js';
-export { ModelRegistry, getActiveRegistry, type ExtendedReferenceMetadata, type BackReferenceMetadata } from '../ModelRegistry.js';
 export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
-export { TransactionQueue } from '../transactions/TransactionQueue.js';
-export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
-export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, type SyncEngineContext, } from '../SyncEngineContext.js';
-export type { SyncEngineConfig, SyncLogger, SyncObservabilityProvider, SyncAnalytics, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, BreadcrumbLevel, SyncBreadcrumbCategory, TransactionFailureDetails, BootstrapFailureDetails, WebSocketErrorDetails, RollbackDetails, SpanAttributes, } from '../interfaces/index.js';
-export { SyncSessionError } from '../errors.js';
-export { QueryProcessor } from './QueryProcessor.js';
-export { QueryView, type QueryViewOptions } from './QueryView.js';
-export { ViewRegistry } from './ViewRegistry.js';
-export { ObjectStore } from '../stores/ObjectStore.js';
-export { NetworkMonitor } from '../NetworkMonitor.js';
-export { SyncWebSocket, type SyncDelta, type VersionVector, type BootstrapHint, type SyncGroupChangePayload, type BootstrapDataEvent, type PresenceUpdateEvent, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper, type BootstrapData, type BootstrapOptions, type BootstrapFetchResult } from '../sync/BootstrapHelper.js';
+export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
+export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
+export { BootstrapHelper } from '../sync/BootstrapHelper.js';
 export { createIntentStream, type AttachableIntentStream, type IntentStreamConfig, } from '../sync/createIntentStream.js';
 export { awaitIntentGrant, type GrantTransport, } from '../sync/awaitIntentGrant.js';
-export { OfflineTransactionStore, offlineTxStore, Priority } from '../sync/OfflineTransactionStore.js';
-export { PropertyType, LoadStrategy, MutationOperationType } from '../types/index.js';
-export type { PropertyMetadata, ReferenceMetadata, ModelMetadata, SyncAction, DeltaPacket, BootstrapMetadata, DatabaseMetadata, } from '../types/index.js';
-export type { ModelData } from '../BaseSyncedStore.js';
+export { LoadStrategy } from '../types/index.js';