@abloatai/ablo 0.35.0 → 0.36.0

package/dist/client/storeCluster.js

@@ -0,0 +1,118 @@
+/**
+ * The store cluster — what `humans()` constructs at `init` now that the
+ * plugin context carries the resolved url and the credential source
+ * (ADR 0016; docs/plans/package-split.md, sequence step 2): this client's
+ * runtime, the internal component graph, the registered model classes, and
+ * the `BaseSyncedStore` that orchestrates them. The engine consumes the
+ * cluster instead of constructing it; what remains in the composition root
+ * (credential lifecycle, ready(), model proxies, resources) migrates in
+ * later steps.
+ *
+ * The cluster rides the humans surface under {@link kStoreCluster}, a
+ * symbol: `layerPluginSurface` merges only string-keyed members onto the
+ * client, so the handoff never becomes public client API. When the plugin
+ * contract adopts context patches (the decoration end-state), this channel
+ * dissolves into them.
+ */
+import { shouldUseInMemoryPersistence } from '../transaction/persistence.js';
+import { noopObservability, browserOnlineStatus, defaultSessionErrorDetector, noopAnalytics, } from '../RuntimeContext.js';
+import { initRuntime } from '../context.js';
+import { alwaysOnline } from '../adapters/alwaysOnline.js';
+import { BaseSyncedStore } from '../BaseSyncedStore.js';
+import { SyncWebSocket } from '../sync/SyncWebSocket.js';
+import { createInternalComponents, } from './createInternalComponents.js';
+import { registerModelsFromSchema } from './modelRegistration.js';
+import { deriveConfigFromSchema } from './schemaConfig.js';
+import { createDefaultMutationExecutor } from './wsMutationExecutor.js';
+/**
+ * The private handoff slot on the humans surface. Symbol-keyed on purpose:
+ * surface members merge onto the client by string key, and the cluster is
+ * construction machinery, not client API.
+ */
+export const kStoreCluster = Symbol('ablo.humans.storeCluster');
+/**
+ * The contract types the connection as the core `WsTransport`; on the
+ * reactive path the factory constructs the materialising subclass with the
+ * default collaboration vocabulary, and this guard is where that knowledge
+ * becomes a type. A connection that is not the subclass means the cluster
+ * cannot be built here.
+ */
+function isReactiveSocket(transport) {
+    return transport instanceof SyncWebSocket;
+}
+/**
+ * Builds the cluster from what the context carries, or returns `null` when
+ * it does not carry enough (no connection, no resolved url, no credential
+ * source, or no schema on the options bag) — the same tolerance the
+ * presence stream established: `init` constructs what the context can
+ * support and no more. The reactive factory always supplies all four and
+ * treats a missing cluster as a configuration fault.
+ */
+export function buildStoreCluster(context) {
+    const options = context.options;
+    const { url, auth, transport, logger } = context;
+    if (!options?.schema || !url || !auth || !isReactiveSocket(transport)) {
+        return null;
+    }
+    const schema = options.schema;
+    // Config derives from the schema; caller-supplied overrides layer on top,
+    // caller winning per key.
+    const config = {
+        ...deriveConfigFromSchema(schema),
+        ...options.configOverrides,
+    };
+    // The default executor sends `{ type: 'commit', ... }` over the context's
+    // connection; before it opens, sends reject with the diagnosed not-ready
+    // error and the MutationQueue owns the retry. A caller-supplied executor
+    // still wins (test mocks, alternative transports).
+    const executor = options.mutationExecutor ?? createDefaultMutationExecutor(() => transport);
+    // This client's runtime — the instance the whole graph is constructed
+    // with, so two clients in one process never read each other's logger,
+    // config, or executor. `getModelMetadata` closes over this client's own
+    // registry (assigned once the graph exists below), never the
+    // active-registry global.
+    let registryForMetadata;
+    const runtime = {
+        logger,
+        observability: options.observability ?? noopObservability,
+        analytics: options.analytics ?? noopAnalytics,
+        sessionErrorDetector: options.sessionErrorDetector ?? defaultSessionErrorDetector,
+        onlineStatus: options.onlineStatus ??
+            (shouldUseInMemoryPersistence(options) ? alwaysOnline() : browserOnlineStatus),
+        config,
+        mutationExecutor: executor,
+        getModelMetadata: (name) => registryForMetadata?.getMetadata(name),
+    };
+    // The module-global bridge: code not yet constructed with an instance
+    // (model instances, the react hooks, the socket's context ports) still
+    // reads it. Last-writer-wins there, exactly as before the runtime became
+    // per-client. Retired reference by reference (docs/plans/package-split.md).
+    initRuntime(runtime);
+    const components = createInternalComponents({
+        schema,
+        url,
+        options,
+        auth,
+        runtime,
+    });
+    registryForMetadata = components.modelRegistry;
+    registerModelsFromSchema(schema, components.modelRegistry);
+    const store = new BaseSyncedStore({
+        syncClient: components.syncClient,
+        database: components.database,
+        objectPool: components.objectPool,
+        modelRegistry: components.modelRegistry,
+        syncWebSocket: transport,
+        schema,
+        url,
+        auth,
+        runtime,
+        // The resolved list, so the store's delta pipeline dispatches the
+        // declared stage handlers — including this plugin's own `apply`.
+        stagePlugins: context.plugins ?? [],
+    }, 
+    // Collaboration vocabulary is the application's: the SDK subscribes to
+    // the event types the caller declares and to nothing by default.
+    { collaborationEvents: options.collaborationEvents ?? [] });
+    return { runtime, components, store };
+}

package/dist/client/storeLifecycle.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The materialiser's lifecycle: the first credential mint, identity
+ * resolution, the credential-refresh machinery, and the idempotent `ready()`
+ * that drives the store's initialize generator to completion. Extracted from
+ * the composition root along the humans() seam (docs/plans/package-split.md):
+ * the engine wires it with the prelude's credential slice and consumes
+ * `ready`; resolved identity flows back through one callback, so the
+ * engine-side state it seeds (the self locals, the streams) stays with the
+ * engine.
+ */
+import type { SchemaRecord, Schema } from '../transaction/schema/schema.js';
+import type { ParticipantKind } from '../transaction/types/participant.js';
+import type { Logger } from '../transaction/logger.js';
+import type { AuthCredentialSource } from '../transaction/auth/credentialSource.js';
+import type { ApiKeySetter } from '../transaction/auth/apiKey.js';
+import type { AbloError } from '../transaction/errors.js';
+import type { InternalAbloOptions } from './options.js';
+import type { StoreCluster } from './storeCluster.js';
+/** What identity resolution settled, handed back for the engine to seed. */
+export interface IdentitySeed {
+    readonly userId: string;
+    readonly participantKind: ParticipantKind;
+    /** The resolved account scope; null until known. */
+    readonly accountScope: string | null;
+    readonly syncGroups: readonly string[];
+}
+export interface StoreLifecycle {
+    /**
+     * Drives initialization to completion: first mint, identity resolution,
+     * seeding, then the store's initialize generator. Idempotent — the first
+     * call starts it, later calls share the promise; a failed attempt clears
+     * the memo so retry triggers can re-bootstrap.
+     */
+    ready(): Promise<void>;
+    /** Stops the credential refresh scheduler, if identity resolution installed one. */
+    dispose(): void;
+}
+export interface StoreLifecycleDeps<S extends SchemaRecord> {
+    readonly cluster: StoreCluster;
+    readonly schema: Schema<S>;
+    readonly internalOptions: InternalAbloOptions<S>;
+    readonly authCredentials: AuthCredentialSource;
+    readonly credentialResolver: (() => Promise<string | null>) | null;
+    readonly configuredApiKey: string | ApiKeySetter | null;
+    readonly configuredAuthToken: string | null;
+    readonly url: string;
+    readonly kind: ParticipantKind;
+    readonly logger: Logger;
+    /** The engine's up-front options validation; a present error makes `ready()` reject with it. */
+    readonly validationError: AbloError | null;
+    /** Seeds resolved identity into the engine's own state: the self locals and the streams. */
+    readonly onIdentityResolved: (seed: IdentitySeed) => void;
+}
+/**
+ * Wires the credential machinery onto the cluster and returns the `ready`
+ * the client exposes. Wiring happens now — the refresh lifecycle, the
+ * lazy-query auth recovery, the executor binding, and the opt-in auto-start;
+ * the first mint waits for `ready()` so the first connection carries a
+ * token.
+ */
+export declare function startStoreLifecycle<S extends SchemaRecord>(deps: StoreLifecycleDeps<S>): StoreLifecycle;

package/dist/client/storeLifecycle.js

@@ -0,0 +1,231 @@
+/**
+ * The materialiser's lifecycle: the first credential mint, identity
+ * resolution, the credential-refresh machinery, and the idempotent `ready()`
+ * that drives the store's initialize generator to completion. Extracted from
+ * the composition root along the humans() seam (docs/plans/package-split.md):
+ * the engine wires it with the prelude's credential slice and consumes
+ * `ready`; resolved identity flows back through one callback, so the
+ * engine-side state it seeds (the self locals, the streams) stays with the
+ * engine.
+ */
+import { resolveParticipantIdentity } from '../transaction/auth/identity.js';
+import { AbloAuthenticationError, AbloConnectionError, toAbloError, } from '../transaction/errors.js';
+/**
+ * Wires the credential machinery onto the cluster and returns the `ready`
+ * the client exposes. Wiring happens now — the refresh lifecycle, the
+ * lazy-query auth recovery, the executor binding, and the opt-in auto-start;
+ * the first mint waits for `ready()` so the first connection carries a
+ * token.
+ */
+export function startStoreLifecycle(deps) {
+    const { cluster, schema, internalOptions, authCredentials, credentialResolver, configuredApiKey, configuredAuthToken, url, kind, logger, validationError, onIdentityResolved, } = deps;
+    const { store, components, runtime } = cluster;
+    const { bootstrapHelper, hydration, syncClient } = components;
+    // Hand the credential lifecycle to the client (refresher + proactive refresh
+    // timer + wake/online/focus re-mint). Installed once here so refresh works for
+    // any consumer of `Ablo({ auth })`, not only those who render `<AbloProvider>`.
+    // The first mint happens in `ready()` so the first connection carries a token.
+    //
+    // Long-lived server clients also get the pre-roll timer on windowless hosts
+    // (`proactiveInNode`): their socket must renew its `rk_` or `ek_` before the
+    // server's keepalive reaper closes it (4001 `credential_expired`). Two signals
+    // qualify — an agent or system participant, and an absolute endpoint-string
+    // `apiKey` (a relative one can't be fetched in Node, so an absolute URL is
+    // unambiguously a deliberate server client). User-kind clients in Node (an
+    // SSR/RSC module evaluating scaffolded browser code) stay reactive-only.
+    if (credentialResolver) {
+        const rawEndpoint = internalOptions.authEndpoint ?? internalOptions.apiKey;
+        const absoluteEndpoint = typeof rawEndpoint === 'string' && /^https?:\/\//i.test(rawEndpoint);
+        store.startCredentialLifecycle(credentialResolver, {
+            /* eslint-disable @typescript-eslint/no-deprecated -- `kind` gates the self-hosted proactive pre-roll; hosted path derives it from the apiKey scope */
+            proactiveInNode: internalOptions.kind === 'agent' ||
+                internalOptions.kind === 'system' ||
+                absoluteEndpoint,
+            /* eslint-enable @typescript-eslint/no-deprecated */
+        });
+    }
+    // Put the lazy-query lane on the same auth-recovery path as the WebSocket probe
+    // and the proactive pre-roll: a 401 on `/sync/query` re-mints via the store's
+    // single-flight lifecycle and replays once, instead of silently returning empty
+    // rows against an expired `ek_` until the next proactive tick. Late-bound
+    // because the coordinator is constructed before the store exists.
+    hydration.setCredentialRecovery((recovery) => store.recoverFromAuthRejection(recovery));
+    // Bind this client's executor to its MutationQueue explicitly. The queue
+    // already resolves it through this client's own `runtime`, so this is the
+    // same executor either way; the explicit binding also covers a queue that
+    // was constructed without the instance runtime (subclass and test paths).
+    syncClient.getMutationQueue().setMutationExecutor(runtime.mutationExecutor);
+    // Status is tracked in store.syncStatus (MobX observable) — the single
+    // source of truth. No duplicate closure variables.
+    let _readyPromise = null;
+    let _refreshScheduler = null;
+    async function ready() {
+        if (_readyPromise)
+            return _readyPromise;
+        if (validationError) {
+            _readyPromise = Promise.reject(validationError);
+            return _readyPromise;
+        }
+        _readyPromise = (async () => {
+            try {
+                // Mint the first access credential before we connect, so the initial
+                // WebSocket upgrade and bootstrap carry a valid bearer (no tokenless first
+                // connect that has to self-heal). Only when a refreshing resolver is wired
+                // and no static credential is already present. Follows the `apiKey`
+                // resolver contract: `null` means the login is gone (terminal — fail ready
+                // so the app shows sign-in); a throw means transient (rethrown; autoStart
+                // swallows it and the lifecycle's online/wake triggers retry).
+                if (credentialResolver && !authCredentials.getAuthToken()) {
+                    const token = await credentialResolver();
+                    if (!token) {
+                        throw new AbloAuthenticationError('Auth resolver returned null before connect — the user is not signed in.', { code: 'auth_no_credentials' });
+                    }
+                    authCredentials.setAuthToken(token);
+                }
+                // Resolve participant identity + scope. Three branches —
+                // hosted-cloud apiKey exchange, self-derived from capability
+                // token, or legacy explicit options. See `./identity.ts`.
+                const resolved = await resolveParticipantIdentity({
+                    options: internalOptions,
+                    internalOptions,
+                    url,
+                    kind,
+                    configuredApiKey,
+                    // Resolve identity against the live token, not the construction-time
+                    // `configuredAuthToken`. Consumers using a function `apiKey` never pass
+                    // `authToken` at construction — the lifecycle mints the first `ek_` or
+                    // `rk_` and calls `setAuthToken()` before `ready()`, which updates the
+                    // shared credential source. Reading the frozen `configuredAuthToken`
+                    // here made `/auth/identity` fire with no bearer (returning
+                    // `no_matching_provider` / `session_expired`) even though the token was
+                    // present. This reads the shared credential source, like every other
+                    // transport.
+                    configuredAuthToken: authCredentials.getAuthToken() ?? configuredAuthToken,
+                    bootstrapHelper,
+                    auth: authCredentials,
+                    logger,
+                });
+                const { userId, accountScope, teamIds, capabilityToken, syncGroups, participantKind, } = resolved;
+                // Fail-loud guard: detect the degenerate "no real sync groups
+                // resolved" state before opening the socket. It is the same class of bug as
+                // a sensible-looking default that's functionally broken: the
+                // SDK ends up subscribing only to the server-side
+                // `['default']` fallback, no
+                // delta has that tag, live fan-out silently never delivers.
+                // For human users (kind:'user') this is almost certainly a
+                // misconfiguration upstream — either the caller didn't pass
+                // `syncGroups`, or auth resolution didn't derive them, or
+                // both. Warn loudly so the next debugging session starts here
+                // instead of with "live updates don't work, hard reload fixes
+                // it."
+                const resolvedSyncGroups = syncGroups ?? [];
+                if (participantKind === 'user' &&
+                    (resolvedSyncGroups.length === 0 ||
+                        (resolvedSyncGroups.length === 1 && resolvedSyncGroups[0] === 'default'))) {
+                    // Actionable and not self-healing (no live updates until fixed):
+                    // kept at warn level for consumers; the low-level diagnostic
+                    // fields ride the debug log below.
+                    logger.warn('This client was started without sync groups, so it will not receive ' +
+                        'live updates. Pass `syncGroups` (for example ' +
+                        '`["org:<id>", "user:<id>"]`) or check that your auth provider supplies them.');
+                    logger.debug('degenerate syncGroups — details', { participantKind, resolvedSyncGroups });
+                }
+                // Seed the resolved identity into everything that filters or stamps
+                // by participant — the engine's self locals and its streams, through
+                // the one callback. This runs before the store connects, so no frame
+                // is ever filtered against the construction-time guess.
+                onIdentityResolved({
+                    userId,
+                    participantKind,
+                    accountScope,
+                    syncGroups: resolvedSyncGroups,
+                });
+                if (resolved.refreshScheduler) {
+                    _refreshScheduler = resolved.refreshScheduler;
+                }
+                // Drive the generator to completion. Each yielded promise is awaited
+                // then fed back — this is standard generator consumption.
+                //
+                // The store.initialize() generator updates store.syncStatus as it
+                // progresses (syncing → idle on success, error on failure), so the
+                // consumer's `sync.syncStatus` observable reflects real-time state.
+                // Resolve bootstrap mode: explicit option wins; otherwise
+                // agents default to 'none' (transactional participant — see
+                // option doc) and everyone else defaults to 'full'.
+                const resolvedBootstrapMode = internalOptions.bootstrapMode ?? (participantKind === 'agent' ? 'none' : 'full');
+                const gen = store.initialize({
+                    userId,
+                    organizationId: accountScope,
+                    teamIds,
+                    kind: participantKind,
+                    capabilityToken,
+                    syncGroups,
+                    bootstrapMode: resolvedBootstrapMode,
+                });
+                let current = gen.next();
+                while (!current.done) {
+                    const yielded = current.value;
+                    const settled = yielded instanceof Promise ? await yielded : yielded;
+                    current = gen.next(settled);
+                }
+                const result = current.value;
+                if (!result.success) {
+                    throw result.error
+                        ? toAbloError(result.error)
+                        : new AbloConnectionError('Sync engine initialization failed', {
+                            code: 'bootstrap_fetch_timeout',
+                        });
+                }
+                logger.info('Sync engine ready', { models: Object.keys(schema.models).length });
+            }
+            catch (err) {
+                // Coerce so the rejection a consumer awaiting `ready()` catches is
+                // always an AbloError — connection setup is held to the same
+                // never-leak-untagged contract as the model operations.
+                const error = toAbloError(err);
+                // Make sure syncStatus reflects the failure for observer() components
+                store.syncStatus.state = 'error';
+                store.syncStatus.error = error;
+                // Log the typed envelope (type + code + status), not just the bare
+                // message — so the console line names it as an Ablo error and carries
+                // the code (e.g. AbloAuthenticationError/identity_resolve_failed on a
+                // 401) instead of reading like an untagged failure.
+                logger.error('Sync engine failed to initialize', {
+                    type: error.type,
+                    code: error.code,
+                    httpStatus: error.httpStatus,
+                    error: error.message,
+                });
+                // Clear the memo so a future `ready()` re-attempts bootstrap instead of
+                // replaying this rejection forever. Bootstrap failures here are transient
+                // by nature — offline, an IndexedDB open timeout, a bootstrap fetch
+                // hiccup — and the early `if (_readyPromise) return _readyPromise` guard
+                // would otherwise hand every later caller this same dead promise, bricking
+                // the engine until a full page reload. Nulling it lets the provider's
+                // online/wake/retry triggers drive a clean re-bootstrap. (The terminal
+                // `validationError` branch above intentionally stays cached — config
+                // can't change without recreating the engine.)
+                _readyPromise = null;
+                throw error;
+            }
+        })();
+        return _readyPromise;
+    }
+    // Optional auto-start for convenience. Opt-in because silent background
+    // init has historically been the #1 source of "why isn't my data loading"
+    // bug reports. Explicit `await sync.ready()` is the default — errors
+    // surface immediately instead of being swallowed.
+    if (!validationError && internalOptions.autoStart) {
+        void ready().catch(() => {
+            // Error is captured in store.syncStatus; consumers should check
+            // `sync.syncStatus.state === 'error'` to detect failures.
+        });
+    }
+    return {
+        ready,
+        dispose() {
+            _refreshScheduler?.dispose();
+            _refreshScheduler = null;
+        },
+    };
+}

package/dist/context.d.ts

@@ -19,6 +19,19 @@ export declare function initRuntime(context: RuntimeContext): void;
  * so SDK files can import at module load time without crashing.
  */
 export declare function getContext(): RuntimeContext;
+/**
+ * The module-global runtime as an instance-shaped value — the bridge for code
+ * that is not yet constructed with its client's own `RuntimeContext`.
+ *
+ * Every member reads {@link getContext} at call time, so a context installed
+ * after construction is still picked up (tests construct first and
+ * `initRuntime` later). Classes take `runtime` as a constructor option with
+ * this as the default; a client that threads its own instance is isolated
+ * from other clients in the same process, a construction that doesn't is
+ * last-writer-wins exactly as before. Retired reference by reference as
+ * construction moves behind `humans()` (docs/plans/package-split.md).
+ */
+export declare const globalRuntime: RuntimeContext;
 /**
  * Check if the sync engine has been initialized.
  */

package/dist/context.js

@@ -27,6 +27,29 @@ export function getContext() {
     }
     return _context;
 }
+/**
+ * The module-global runtime as an instance-shaped value — the bridge for code
+ * that is not yet constructed with its client's own `RuntimeContext`.
+ *
+ * Every member reads {@link getContext} at call time, so a context installed
+ * after construction is still picked up (tests construct first and
+ * `initRuntime` later). Classes take `runtime` as a constructor option with
+ * this as the default; a client that threads its own instance is isolated
+ * from other clients in the same process, a construction that doesn't is
+ * last-writer-wins exactly as before. Retired reference by reference as
+ * construction moves behind `humans()` (docs/plans/package-split.md).
+ */
+export const globalRuntime = {
+    get logger() { return getContext().logger; },
+    get observability() { return getContext().observability; },
+    get analytics() { return getContext().analytics; },
+    get sessionErrorDetector() { return getContext().sessionErrorDetector; },
+    get onlineStatus() { return getContext().onlineStatus; },
+    get modelDebugLogger() { return getContext().modelDebugLogger; },
+    get mutationExecutor() { return getContext().mutationExecutor; },
+    get config() { return getContext().config; },
+    getModelMetadata: (name) => getContext().getModelMetadata(name),
+};
 /**
  * Check if the sync engine has been initialized.
  */

package/dist/core/index.d.ts

@@ -22,7 +22,7 @@ export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyRef
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
 export { postQuery, type PostQueryOptions } from '../query/client.js';
 export { computeFKDepthPriority } from '../client/schemaConfig.js';
-export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
+export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, MutationOptions, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
 export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
 /** @deprecated `BootstrapHelper` was renamed to {@link BootstrapFetcher}. This alias keeps

package/dist/docs/catalog.js

@@ -137,6 +137,9 @@ async function readDocsDirectory(dir, kind) {
     }
     return entries;
 }
+/** The H1 a page opens with, and the blockquote paragraph that follows it. */
+const H1_LINE = /^#[ \t]+(.+?)[ \t]*$/m;
+const PROMISE_BLOCKQUOTE = /^\s*\n((?:>.*\n)+)/;
 /**
  * Pull a page's title and promise line out of its markdown.
  *
@@ -145,10 +148,10 @@ async function readDocsDirectory(dir, kind) {
  * catalog never invents prose.
  */
 export function parseDocHeader(body) {
-    const heading = body.match(/^#[ \t]+(.+?)[ \t]*$/m);
+    const heading = H1_LINE.exec(body);
     const title = heading?.[1] ?? null;
-    const afterHeading = heading?.index === undefined ? body : body.slice(heading.index + heading[0].length);
-    const promise = afterHeading.match(/^\s*\n((?:>.*\n)+)/);
+    const afterHeading = heading === null ? body : body.slice(heading.index + heading[0].length);
+    const promise = PROMISE_BLOCKQUOTE.exec(afterHeading);
     const description = promise?.[1]
         ?.split('\n')
         .filter(Boolean)

package/dist/index.d.ts

@@ -26,7 +26,6 @@
  * Related surfaces live on their own import subpaths:
  *   @abloatai/ablo/schema   — defineSchema, model, z (Zod)
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
- *   @abloatai/ablo/testing  — test harnesses and fixtures
  *
  * Reads come in two flavors, distinguished by where the data is fetched from.
  * `ablo.<model>.retrieve({ id })` and `.list({ where })` are asynchronous reads
@@ -97,12 +96,15 @@ export type { WriteOptionsInput } from './transaction/resources/writeOptionsSche
 export type { OnStaleMode } from './transaction/coordination/schema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { staleNotificationSchema, readDependencySchema } from './transaction/coordination/schema.js';
+export { part } from './transaction/coordination/schema.js';
+export type { ClaimPart } from './transaction/coordination/schema.js';
+export type { ClaimField } from './transaction/resources/modelOperations.js';
 export type { StaleNotification, ReadDependency } from './transaction/coordination/schema.js';
 export { ClaimLog, formatClaim, formatConflict } from './coordination/ClaimLog.js';
 export type { ClaimLogEntry } from './coordination/ClaimLog.js';
 export type { ClaimEvent, ConflictEvent, SyncObservabilityProvider, } from './interfaces/index.js';
 export { noopObservability } from './RuntimeContext.js';
-export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+export { IDBOpenTimeoutError, isStorageOpenTimeout } from './stores/openIDBWithTimeout.js';
 export type { CommitLatencySample } from './transactions/mutations/commitLatency.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';

package/dist/index.js

@@ -26,7 +26,6 @@
  * Related surfaces live on their own import subpaths:
  *   @abloatai/ablo/schema   — defineSchema, model, z (Zod)
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
- *   @abloatai/ablo/testing  — test harnesses and fixtures
  *
  * Reads come in two flavors, distinguished by where the data is fetched from.
  * `ablo.<model>.retrieve({ id })` and `.list({ where })` are asynchronous reads
@@ -122,6 +121,9 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './tr
 // returns this notification so the caller can reconcile against the current
 // value and retry rather than discard its work.
 export { staleNotificationSchema, readDependencySchema } from './transaction/coordination/schema.js';
+// The claim-part marker: schema field names typecheck plainly on a claim
+// target; an app-defined part (a cell, a section) is named through `part()`.
+export { part } from './transaction/coordination/schema.js';
 // Collects claim events and stale-write collisions into an ordered list you can
 // print to inspect coordination, or read through `collisions()` to assert on in
 // tests. Pass `new ClaimLog()` as `Ablo({ observability })`.
@@ -132,7 +134,7 @@ export { noopObservability } from './RuntimeContext.js';
 // Detects a stuck local store: use these to recognize when the browser's
 // IndexedDB backing store fails to open in time, so your app can show a
 // recovery screen instead of hanging.
-export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
+export { IDBOpenTimeoutError, isStorageOpenTimeout } from './stores/openIDBWithTimeout.js';
 // A machine-readable manifest of the SDK's public verb and option names, bound
 // at compile time to the real types so the lists can never name a method or
 // option the API doesn't have. Useful for generating documentation or tooling

package/dist/query/client.d.ts

@@ -14,6 +14,7 @@
 import type { QueryBatch, QueryBatchResult } from './types.js';
 import { type RecoveryClass } from '../transaction/errorCodes.js';
 import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
 export interface PostQueryOptions {
     /**
      * Full base URL of the sync server including the `/api` prefix.
@@ -23,6 +24,8 @@ export interface PostQueryOptions {
     baseUrl: string;
     /** Timeout in ms for the fetch request. Default: 30000. */
     fetchTimeout?: number;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
     /**
      * Live bearer credential getter. Preferred over `capabilityToken` because it
      * is read per request, so token refreshes propagate without reconstructing

package/dist/query/client.js

@@ -15,7 +15,7 @@ import { z } from 'zod';
 import { translateHttpError } from '../transaction/errors.js';
 import { classifyRecovery } from '../transaction/errorCodes.js';
 import { withAuthHeaders } from '../transaction/auth/credentialSource.js';
-import { getContext } from '../context.js';
+import { globalRuntime } from '../context.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows, or an object for a bundled response.
@@ -50,6 +50,7 @@ const QueryBatchResultSchema = z
 export async function postQuery(options, batch) {
     const url = `${options.baseUrl}/sync/query`;
     const timeout = options.fetchTimeout ?? 30_000;
+    const runtime = options.runtime ?? globalRuntime;
     // At most two attempts: the original request, plus one replay after a
     // successful credential recovery (see `recoverCredential`). A second auth
     // rejection falls through to the log-and-empty path, so a wedged credential
@@ -97,7 +98,7 @@ export async function postQuery(options, batch) {
                         : 'access_credential_expiry';
                     const outcome = await options.recoverCredential(recovery);
                     if (outcome === 'retry') {
-                        getContext().logger.debug('[postQuery] credential recovered — replaying query once', {
+                        runtime.logger.debug('[postQuery] credential recovered — replaying query once', {
                             code: err.code ?? response.status,
                         });
                         continue;
@@ -109,8 +110,8 @@ export async function postQuery(options, batch) {
                 // `debug` line. The read stays empty until the underlying cause, such
                 // as auth or network, is resolved.
                 const models = batch.queries.map((q) => q.model).join(', ');
-                getContext().logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
-                getContext().logger.debug('[postQuery.error] query http failure', {
+                runtime.logger.warn(`Could not load ${models} — ${err.message} (code: ${err.code ?? response.status}). No results were returned.`);
+                runtime.logger.debug('[postQuery.error] query http failure', {
                     type: err.type,
                     code: err.code ?? response.status,
                     models,
@@ -123,7 +124,7 @@ export async function postQuery(options, batch) {
             if (!parsed.success) {
                 // A malformed server response isn't something the consumer can act on
                 // (server/protocol issue) → debug, gated like everything else.
-                getContext().logger.debug('[postQuery.error] malformed response', {
+                runtime.logger.debug('[postQuery.error] malformed response', {
                     issues: parsed.error.issues,
                 });
                 return { results: batch.queries.map(() => []) };

package/dist/react/AbloProvider.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import type { SchemaRecord } from '../transaction/schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { Claim, Peer } from '../transaction/types/streams.js';
+import type { Claim, Duration, Peer } from '../transaction/types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
 /**
@@ -116,6 +116,18 @@ export type { EngineParticipant, ParticipantScope, ParticipantStatus };
  */
 export interface UseJoinOptions {
     readonly scope?: ParticipantScope;
+    /**
+     * Lease TTL for the participant claim, as a compact duration (`'5m'`) or a
+     * number of seconds. The same dial and the same spelling as
+     * `ablo.<model>.join(ids, { ttl })` and every other lease in the SDK.
+     */
+    readonly ttl?: Duration;
+    /**
+     * @deprecated Use `ttl`. Removed in 0.37.0.
+     *
+     * The same rename as on `ParticipantJoinOptions`: one lease, and the seconds
+     * spelling was the one that misled, because it accepted duration strings too.
+     */
     readonly ttlSeconds?: number | string | null;
     /** Tear down + don't re-join while true. */
     readonly paused?: boolean;