@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/sync/cloud-pull.js

@@ -4,127 +4,126 @@
  * Pulls data from cloud storage for manifests that have cloud-api configured.
  * Used at daemon startup to hydrate local state from cloud, and by the
  * sync job for bidirectional sync.
+ *
+ * An unreachable cloud is an error, not a skip, and every failure is recorded
+ * (sync state, the result) as its value-free facts, never a thrown text.
+ * A failure of the pull as a whole (sync state unreadable, adapter
+ * unresolvable) refuses typed: it is never answered as an empty result.
  */
+import { CapabilityError, CaughtFailureSchema, valueFreeFailure } from '@vibesdotdev/kernel';
 import { getLogger } from '@vibesdotdev/logging';
-const logger = getLogger('storage:cloud-pull');
-import { loadSyncState, saveSyncState, getManifestSyncState, computeHash, markSynced, markConflict, markError } from './sync-state.consumer.js';
+import { cloudAdapterOf, cloudStoreFor, SyncDocumentSchema, syncFailureLine } from "./cloud-document.js";
+import { loadSyncState, saveSyncState, getManifestSyncState, computeHash, markSynced, markConflict, markError } from "./sync-state.consumer.js";
 const LOG_PREFIX = '[cloud-pull]';
 /**
  * Pull data from cloud for all eligible manifests.
  * Called at daemon startup and periodically by the sync job.
  */
-export async function pullFromCloud(options = {}) {
+export async function pullFromCloud(runtime, options = {}) {
     const { manifestIds, force = false, dryRun = false } = options;
     const result = { pulled: 0, skipped: 0, conflicts: 0, errors: 0, details: [] };
-    try {
-        const { getVibesRuntime } = await import('@vibesdotdev/runtime');
-        const { StorageManifest } = await import('../manifest/base.js');
-        const runtime = getVibesRuntime();
-        // Find manifests with cloud-api support
-        const descriptors = runtime.query('storage/manifest').descriptors();
-        const eligible = descriptors.filter((d) => {
-            if (!d.allowedAdapters?.includes('storage.cloud-api'))
-                return false;
-            if (manifestIds?.length && !manifestIds.includes(d.id))
-                return false;
-            return true;
-        });
-        if (eligible.length === 0) {
-            logger.debug(`${LOG_PREFIX} No eligible manifests for cloud pull`);
-            return result;
-        }
-        const syncState = await loadSyncState();
-        // Resolve cloud adapter once
-        const cloudAdapter = await runtime
-            .query('storage/adapter')
-            .filter((d) => d.id === 'storage.cloud-api')
-            .resolve();
-        if (!cloudAdapter) {
-            logger.debug(`${LOG_PREFIX} Cloud adapter not available`);
-            return result;
-        }
-        const adapter = cloudAdapter;
-        for (const descriptor of eligible) {
-            try {
-                const pullResult = await pullManifest(descriptor, adapter, syncState, new StorageManifest(descriptor.id), { force, dryRun });
-                result.details.push(pullResult);
-                switch (pullResult.action) {
-                    case 'pulled':
-                        result.pulled++;
-                        break;
-                    case 'conflict':
-                        result.conflicts++;
-                        break;
-                    case 'error':
-                        result.errors++;
-                        break;
-                    default:
-                        result.skipped++;
-                }
-            }
-            catch (error) {
-                const msg = error.message;
-                logger.warn(`${LOG_PREFIX} Pull failed for ${descriptor.id}`, { error: msg });
-                markError(syncState, descriptor.id, msg);
-                result.details.push({ manifestId: descriptor.id, action: 'error', message: msg });
+    const logger = getLogger('storage:cloud-pull', runtime);
+    const eligible = runtime
+        .query('storage/manifest')
+        .descriptors()
+        .filter((descriptor) => descriptor.allowedAdapters.includes('storage.cloud-api'))
+        .filter((descriptor) => !manifestIds?.length || manifestIds.includes(descriptor.id));
+    if (eligible.length === 0) {
+        logger.debug(`${LOG_PREFIX} No eligible manifests for cloud pull`);
+        return result;
+    }
+    const adapter = await cloudAdapterOf(runtime);
+    if (!adapter) {
+        logger.debug(`${LOG_PREFIX} Cloud adapter not available`);
+        return result;
+    }
+    const syncState = await loadSyncState(runtime);
+    for (const descriptor of eligible) {
+        const detail = await pullManifest(descriptor, adapter, syncState, { force, dryRun, runtime });
+        result.details.push(detail);
+        switch (detail.action) {
+            case 'pulled':
+                result.pulled++;
+                break;
+            case 'conflict':
+                result.conflicts++;
+                break;
+            case 'error':
                 result.errors++;
-            }
+                // Persist so `storage sync status` surfaces the failure (status unhealthyCount / exit-1 contract).
+                markError(syncState, descriptor.id, detail.message ?? 'pull error');
+                break;
+            default:
+                result.skipped++;
         }
-        if (!dryRun) {
-            await saveSyncState(syncState);
-        }
-        logger.info(`${LOG_PREFIX} Pull complete`, {
-            pulled: result.pulled,
-            skipped: result.skipped,
-            conflicts: result.conflicts,
-            errors: result.errors
-        });
+    }
+    if (!dryRun)
+        await saveSyncState(syncState, runtime);
+    // debug — not info. Info was writing a completion line that polluted
+    // `storage sync pull --json` stdout (machine contract: single JSON doc).
+    logger.debug(`${LOG_PREFIX} Pull complete`, {
+        pulled: result.pulled,
+        skipped: result.skipped,
+        conflicts: result.conflicts,
+        errors: result.errors
+    });
+    return result;
+}
+/** One manifest's pull; any failure is that manifest's `error` outcome, carrying its facts. */
+async function pullManifest(descriptor, adapter, syncState, options) {
+    const manifestId = descriptor.id;
+    try {
+        return await pullManifestOrThrow(descriptor, adapter, syncState, options);
     }
     catch (error) {
-        logger.error(`${LOG_PREFIX} Pull failed`, error);
+        const failure = CaughtFailureSchema.parse(error);
+        return { manifestId, action: 'error', message: syncFailureLine('Pull failed:', valueFreeFailure(failure)), failure: valueFreeFailure(failure) };
     }
-    return result;
 }
-async function pullManifest(descriptor, adapter, syncState, localManifest, options) {
-    const { id: manifestId, namespace, schema } = descriptor;
-    const cloudConfig = descriptor.adapterConfig?.['storage.cloud-api'] ?? {};
-    adapter.configure(cloudConfig);
-    const store = adapter.documentStore(namespace, schema);
-    // Load remote
+async function pullManifestOrThrow(descriptor, adapter, syncState, options) {
+    const manifestId = descriptor.id;
+    // The pull runs on the runtime it was handed; the adapter resolves the
+    // descriptor's owner origin and credentials on it.
+    const store = await cloudStoreFor(adapter, descriptor, options.runtime);
+    // Load remote — unreachable cloud is an error, not a skip. Routines and
+    // `storage sync pull --json` must see exit non-zero when the target is down
+    // (same contract as sync-manifest's "Remote unreachable" on push).
     let remoteData;
     try {
-        remoteData = await store.load();
+        const loaded = await store.load();
+        remoteData = loaded === null ? null : SyncDocumentSchema.parse(loaded);
     }
-    catch {
-        return { manifestId, action: 'skipped', message: 'Cloud not reachable' };
+    catch (error) {
+        throw new CapabilityError('The cloud could not be reached for this manifest.', 'UNAVAILABLE', {
+            reason: 'cloud-pull-unreachable',
+            retryable: true,
+            details: { manifestId },
+            cause: CaughtFailureSchema.parse(error)
+        });
     }
-    if (!remoteData) {
+    if (remoteData === null)
         return { manifestId, action: 'skipped', message: 'No remote data' };
-    }
     const remoteHash = computeHash(remoteData);
     const prev = getManifestSyncState(syncState, manifestId);
-    // Load local for comparison
-    const localData = await localManifest.load();
-    const localHash = localData ? computeHash(localData) : null;
-    // Already in sync
+    const { StorageManifest } = await import("../manifest/base.js");
+    const localManifest = StorageManifest.fromId(manifestId, options.runtime);
+    const loadedLocal = await localManifest.load();
+    const localHash = loadedLocal === null ? null : computeHash(SyncDocumentSchema.parse(loadedLocal));
     if (localHash === remoteHash) {
         markSynced(syncState, manifestId, remoteHash, 'pull');
         return { manifestId, action: 'skipped', message: 'Already in sync' };
     }
-    // Check for conflicts
     const localChanged = localHash !== prev.localHash && localHash !== null;
     const remoteChanged = remoteHash !== prev.remoteHash;
     if (localChanged && remoteChanged && !options.force) {
         markConflict(syncState, manifestId, localHash ?? '', remoteHash);
         return { manifestId, action: 'conflict', message: 'Both sides changed' };
     }
-    // Pull remote → local
-    if (options.dryRun) {
+    if (options.dryRun)
         return { manifestId, action: 'pulled', message: '[dry-run] Would pull from cloud' };
-    }
     await localManifest.save(remoteData);
     markSynced(syncState, manifestId, remoteHash, 'pull');
-    logger.info(`${LOG_PREFIX} Pulled ${manifestId} from cloud`);
+    getLogger('storage:cloud-pull', options.runtime).info(`${LOG_PREFIX} Pulled ${manifestId} from cloud`);
     return { manifestId, action: 'pulled' };
 }
 //# sourceMappingURL=cloud-pull.js.map

package/dist/sync/cloud-pull.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-pull.js","sourceRoot":"","sources":["../../src/sync/cloud-pull.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cloud-pull.js","sourceRoot":"","sources":["../../src/sync/cloud-pull.ts"],"names":[],"mappings":"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"}

package/dist/sync/cloud-record-crud-config.d.ts

@@ -1,19 +1,9 @@
-/**
- * Resolve a record's cloud-API CRUD configuration from its descriptor.
- *
- * Reads `StorageRecordDescriptor` metadata only; consumed by storage core's
- * `record-sync-bridge`. Storage core owns it because adapters depend on core,
- * not the other way around.
- */
-import type { StorageRecordDescriptor } from '../schemas/record';
-export type CloudRecordCrudConfig = {
-    apiPath: string;
-    entityPath?: string;
-    listField?: string;
-    totalField?: string;
-    createMethod?: 'POST' | 'PUT';
-    updateMethod?: 'PUT' | 'PATCH';
-    deleteMethod?: 'DELETE';
-};
+import { type CloudRecordCrudConfig } from '../schemas/sync/crud.ts';
+export { CloudRecordCrudConfigSchema, NestedRecordConfigSchema, type CloudRecordCrudConfig } from '../schemas/sync/crud.ts';
+import type { StorageRecordDescriptor } from '../schemas/record/index.ts';
+/** A record's cloud-API CRUD metadata, as `adapterConfig['storage.cloud-api']` (or its `record` field) declares it. */
+/** The `record` field a cloud-api adapter config may nest the CRUD metadata under. */
+/** A record's cloud-API CRUD metadata, or undefined when it declares none. */
+export declare function cloudRecordCrudConfigOf(descriptor: StorageRecordDescriptor): CloudRecordCrudConfig | undefined;
 export declare function resolveCloudRecordCrudConfig(descriptor: StorageRecordDescriptor): CloudRecordCrudConfig;
 //# sourceMappingURL=cloud-record-crud-config.d.ts.map

package/dist/sync/cloud-record-crud-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-record-crud-config.d.ts","sourceRoot":"","sources":["../../src/sync/cloud-record-crud-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,MAAM,qBAAqB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B,YAAY,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IAC/B,YAAY,CAAC,EAAE,QAAQ,CAAC;CACxB,CAAC;AAEF,wBAAgB,4BAA4B,CAC3C,UAAU,EAAE,uBAAuB,GACjC,qBAAqB,CAkBvB"}
+{"version":3,"file":"cloud-record-crud-config.d.ts","sourceRoot":"","sources":["../../src/sync/cloud-record-crud-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC5H,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,KAAK,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAW5H,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE1E,uHAAuH;AAEvH,sFAAsF;AAGtF,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,uBAAuB,GAAG,qBAAqB,GAAG,SAAS,CAO9G;AAED,wBAAgB,4BAA4B,CAC3C,UAAU,EAAE,uBAAuB,GACjC,qBAAqB,CAUvB"}

package/dist/sync/cloud-record-crud-config.js

@@ -1,3 +1,5 @@
+import { CloudRecordCrudConfigSchema, NestedRecordConfigSchema } from "../schemas/sync/crud.js";
+export { CloudRecordCrudConfigSchema, NestedRecordConfigSchema } from "../schemas/sync/crud.js";
 /**
  * Resolve a record's cloud-API CRUD configuration from its descriptor.
  *
@@ -5,18 +7,24 @@
  * `record-sync-bridge`. Storage core owns it because adapters depend on core,
  * not the other way around.
  */
-export function resolveCloudRecordCrudConfig(descriptor) {
+import { CapabilityError } from '@vibesdotdev/kernel';
+/** A record's cloud-API CRUD metadata, as `adapterConfig['storage.cloud-api']` (or its `record` field) declares it. */
+/** The `record` field a cloud-api adapter config may nest the CRUD metadata under. */
+/** A record's cloud-API CRUD metadata, or undefined when it declares none. */
+export function cloudRecordCrudConfigOf(descriptor) {
     const remoteCrud = descriptor.remote?.adapter === 'storage.cloud-api' ? descriptor.remote.crud : null;
-    if (remoteCrud) {
+    if (remoteCrud)
         return remoteCrud;
-    }
     const raw = descriptor.adapterConfig?.['storage.cloud-api'];
-    const value = raw && typeof raw === 'object' && 'record' in raw ? raw.record : raw;
-    if (!value ||
-        typeof value !== 'object' ||
-        typeof value.apiPath !== 'string') {
-        throw new Error(`Record '${descriptor.id}' is missing storage.cloud-api remote CRUD metadata.`);
+    const nested = NestedRecordConfigSchema.safeParse(raw);
+    const parsed = CloudRecordCrudConfigSchema.safeParse(nested.success ? nested.data.record : raw);
+    return parsed.success ? parsed.data : undefined;
+}
+export function resolveCloudRecordCrudConfig(descriptor) {
+    const parsed = cloudRecordCrudConfigOf(descriptor);
+    if (!parsed) {
+        throw new CapabilityError(`Record '${descriptor.id}' is missing storage.cloud-api remote CRUD metadata.`, 'INVALID_INPUT', { reason: 'record-cloud-crud-missing', retryable: false, details: { recordId: descriptor.id } });
     }
-    return value;
+    return parsed;
 }
 //# sourceMappingURL=cloud-record-crud-config.js.map

package/dist/sync/cloud-record-crud-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-record-crud-config.js","sourceRoot":"","sources":["../../src/sync/cloud-record-crud-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,MAAM,UAAU,4BAA4B,CAC3C,UAAmC;IAEnC,MAAM,UAAU,GACf,UAAU,CAAC,MAAM,EAAE,OAAO,KAAK,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpF,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,UAAmC,CAAC;IAC5C,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,aAAa,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC5D,MAAM,KAAK,GACV,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,QAAQ,IAAI,GAAG,CAAC,CAAC,CAAE,GAA2B,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/F,IACC,CAAC,KAAK;QACN,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,EAC3D,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,WAAW,UAAU,CAAC,EAAE,sDAAsD,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,KAA8B,CAAC;AACvC,CAAC"}
+{"version":3,"file":"cloud-record-crud-config.js","sourceRoot":"","sources":["../../src/sync/cloud-record-crud-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAA8B,MAAM,yBAAyB,CAAC;AAC5H,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAA8B,MAAM,yBAAyB,CAAC;AAC5H;;;;;;GAMG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,uHAAuH;AAEvH,sFAAsF;AAGtF,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB,CAAC,UAAmC;IAC1E,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,KAAK,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACtG,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,MAAM,GAAG,GAAG,UAAU,CAAC,aAAa,EAAE,CAAC,mBAAmB,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,wBAAwB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,2BAA2B,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChG,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC3C,UAAmC;IAEnC,MAAM,MAAM,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,MAAM,IAAI,eAAe,CACxB,WAAW,UAAU,CAAC,EAAE,sDAAsD,EAC9E,eAAe,EACf,EAAE,MAAM,EAAE,2BAA2B,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,CAC/F,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/sync/local-first.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod/v4';
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+import { type LocalFirstPrincipal, type LocalFirstRemoteValue, type LocalFirstState } from '../schemas/sync/local-first.ts';
+export type { LocalFirstPrincipal, LocalFirstRemoteValue, LocalFirstState } from '../schemas/sync/local-first.ts';
+/** Owners must atomically check expectedVersion and deduplicate mutationId BEFORE that check.
+ * Callbacks bind the supplied principal, never a mutable ambient account. They must honor signal.
+ */
+export interface LocalFirstRemote<T> {
+    pull(context: {
+        principal: LocalFirstPrincipal;
+        signal: AbortSignal;
+    }): Promise<LocalFirstRemoteValue<T>>;
+    push(input: {
+        data: T | null;
+        mutationId: string;
+        expectedVersion: string | null;
+    }, context: {
+        principal: LocalFirstPrincipal;
+        signal: AbortSignal;
+    }): Promise<{
+        status: 'saved';
+        value: LocalFirstRemoteValue<T>;
+    } | {
+        status: 'conflict';
+        value: LocalFirstRemoteValue<T>;
+    }>;
+}
+/** One desired-state document, persisted before network IO. Feature owners retain wire semantics. */
+export declare class LocalFirstStorage<T> {
+    private readonly options;
+    private readonly manifest;
+    private readonly stateSchema;
+    private readonly remoteSchema;
+    private readonly principal;
+    private readonly lifetime;
+    private syncing;
+    constructor(options: {
+        id: string;
+        schema: z.ZodType<T>;
+        runtime: VibesRuntime;
+        principal: LocalFirstPrincipal;
+        remote: LocalFirstRemote<T>;
+    });
+    private assertActive;
+    private empty;
+    private change;
+    /** Read through the manifest's atomic store operation so another coordinator's writes are visible. */
+    read(): Promise<LocalFirstState<T>>;
+    write(data: T | null): Promise<LocalFirstState<T>>;
+    /** Atomic local read-modify-write; the transform must have no external side effects. */
+    update(transform: (data: T | null) => T | null): Promise<LocalFirstState<T>>;
+    /** Network failures reject but never discard the durable pending revision. Call on reconnect/resume. */
+    sync(): Promise<LocalFirstState<T>>;
+    private drain;
+    private reconcile;
+    /** Explicit user choice; keeping local creates a new CAS attempt against the observed remote version. */
+    resolveConflict(choice: 'local' | 'remote'): Promise<LocalFirstState<T>>;
+    /** Call before account/environment replacement. Late completions cannot mutate persisted state. */
+    dispose(): void;
+}
+//# sourceMappingURL=local-first.d.ts.map

package/dist/sync/local-first.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-first.d.ts","sourceRoot":"","sources":["../../src/sync/local-first.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,OAAO,EACN,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACpH,YAAY,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAElH;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1G,IAAI,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EACjF,OAAO,EAAE;QAAE,SAAS,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAC1E;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;KAAE,GACpD;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED,qGAAqG;AACrG,qBAAa,iBAAiB,CAAC,CAAC;IAQnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgC;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyB;IAClD,OAAO,CAAC,OAAO,CAA4C;gBAE9B,OAAO,EAAE;QACrC,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,OAAO,EAAE,YAAY,CAAC;QACtB,SAAS,EAAE,mBAAmB,CAAC;QAC/B,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;KAC5B;IAYD,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,KAAK;YAGC,MAAM;IAYpB,sGAAsG;IACtG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAEnC,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAIlD,wFAAwF;IACxF,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAQ5E,wGAAwG;IACxG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YAMrB,KAAK;YAML,SAAS;IA+BvB,yGAAyG;IACzG,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;IAWxE,mGAAmG;IACnG,OAAO,IAAI,IAAI;CACf"}

package/dist/sync/local-first.js

@@ -0,0 +1,121 @@
+import { z } from 'zod/v4';
+import { StorageManifest } from "../manifest/base.js";
+import { StorageManifestDescriptorSchema } from "../schemas/manifest-descriptor.js";
+import { LocalFirstPrincipalSchema, localFirstRemoteSchema, localFirstStateSchema } from "../schemas/sync/local-first.js";
+/** One desired-state document, persisted before network IO. Feature owners retain wire semantics. */
+export class LocalFirstStorage {
+    options;
+    manifest;
+    stateSchema;
+    remoteSchema;
+    principal;
+    lifetime = new AbortController();
+    syncing = null;
+    constructor(options) {
+        this.options = options;
+        this.principal = LocalFirstPrincipalSchema.parse(options.principal);
+        this.remoteSchema = localFirstRemoteSchema(options.schema);
+        this.stateSchema = localFirstStateSchema(options.schema);
+        const descriptor = StorageManifestDescriptorSchema.parse({
+            kind: 'storage/manifest', id: options.id, namespace: options.id, schema: this.stateSchema,
+            allowedAdapters: ['storage.idb'], defaultAdapter: 'storage.idb', scope: 'global'
+        });
+        this.manifest = new StorageManifest(descriptor, { runtime: options.runtime })
+            .partition(JSON.stringify([this.principal.environmentId, this.principal.accountId]));
+    }
+    assertActive() { this.lifetime.signal.throwIfAborted(); }
+    empty() {
+        return { data: null, revision: 0, baseVersion: null, pending: null, conflict: null };
+    }
+    async change(transform) {
+        this.assertActive();
+        let result = this.empty();
+        await this.manifest.update((current) => {
+            this.assertActive();
+            result = this.stateSchema.parse(transform(current ? this.stateSchema.parse(current) : this.empty()));
+            return result;
+        });
+        this.assertActive();
+        return result;
+    }
+    /** Read through the manifest's atomic store operation so another coordinator's writes are visible. */
+    read() { return this.change((current) => current); }
+    write(data) {
+        return this.update(() => data);
+    }
+    /** Atomic local read-modify-write; the transform must have no external side effects. */
+    update(transform) {
+        return this.change((current) => {
+            const data = transform(current.data);
+            return { ...current, data: data === null ? null : this.options.schema.parse(data), revision: current.revision + 1,
+                pending: { mutationId: crypto.randomUUID(), revision: current.revision + 1 } };
+        });
+    }
+    /** Network failures reject but never discard the durable pending revision. Call on reconnect/resume. */
+    sync() {
+        this.assertActive();
+        if (!this.syncing)
+            this.syncing = this.drain().finally(() => { this.syncing = null; });
+        return this.syncing;
+    }
+    async drain() {
+        let current;
+        do {
+            current = await this.reconcile();
+        } while (current.pending && !current.conflict);
+        return current;
+    }
+    async reconcile() {
+        const context = { principal: { ...this.principal }, signal: this.lifetime.signal };
+        let current = await this.read();
+        if (current.conflict)
+            return current;
+        // A pending mutation is replayed before pulling: the last push may have committed
+        // remotely but lost its response. The owner's mutation receipt resolves that ambiguity.
+        if (!current.pending) {
+            const beforePull = current;
+            const remote = this.remoteSchema.parse(await this.options.remote.pull(context));
+            this.assertActive();
+            current = await this.change((latest) => {
+                if (latest.pending)
+                    return latest.baseVersion === remote.version ? latest : { ...latest, conflict: remote };
+                if (latest.revision !== beforePull.revision || latest.baseVersion !== beforePull.baseVersion)
+                    return latest;
+                return { ...latest, data: remote.data, baseVersion: remote.version, revision: latest.revision + 1 };
+            });
+        }
+        if (!current.pending || current.conflict)
+            return current;
+        const pending = current.pending;
+        const response = await this.options.remote.push({ data: current.data,
+            expectedVersion: current.baseVersion, mutationId: pending.mutationId }, context);
+        this.assertActive();
+        const remote = this.remoteSchema.parse(response.value);
+        return this.change((latest) => {
+            if (latest.baseVersion !== current.baseVersion)
+                return latest;
+            if (response.status === 'conflict')
+                return { ...latest, conflict: remote };
+            if (response.status !== 'saved')
+                throw new Error('Invalid local-first synchronization response');
+            if (latest.pending?.mutationId !== pending.mutationId)
+                return { ...latest, baseVersion: remote.version };
+            return { ...latest, data: remote.data, baseVersion: remote.version, pending: null, conflict: null };
+        });
+    }
+    /** Explicit user choice; keeping local creates a new CAS attempt against the observed remote version. */
+    resolveConflict(choice) {
+        return this.change((current) => {
+            if (!current.conflict)
+                throw new Error('No synchronization conflict to resolve');
+            const remote = current.conflict;
+            return { ...current, data: choice === 'remote' ? remote.data : current.data,
+                baseVersion: remote.version, conflict: null,
+                pending: choice === 'remote' ? null : { mutationId: crypto.randomUUID(), revision: current.revision + 1 },
+                revision: current.revision + 1 };
+        });
+    }
+    /** Call before account/environment replacement. Late completions cannot mutate persisted state. */
+    dispose() { this.lifetime.abort(new Error('Local-first principal retired')); }
+}
+//# sourceMappingURL=local-first.js.map

package/dist/sync/local-first.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-first.js","sourceRoot":"","sources":["../../src/sync/local-first.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AAEpF,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,qBAAqB,EACJ,MAAM,gCAAgC,CAAC;AAcpH,qGAAqG;AACrG,MAAM,OAAO,iBAAiB;IAQA;IAPZ,QAAQ,CAAsC;IAC9C,WAAW,CAAgC;IAC3C,YAAY,CAAsC;IAClD,SAAS,CAAsB;IAC/B,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IAC1C,OAAO,GAAuC,IAAI,CAAC;IAE3D,YAA6B,OAM5B;QAN4B,YAAO,GAAP,OAAO,CAMnC;QACA,IAAI,CAAC,SAAS,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACpE,IAAI,CAAC,YAAY,GAAG,sBAAsB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC3D,IAAI,CAAC,WAAW,GAAG,qBAAqB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACzD,MAAM,UAAU,GAAG,+BAA+B,CAAC,KAAK,CAAC;YACxD,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW;YACzF,eAAe,EAAE,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ;SAChF,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,IAAI,eAAe,CAAqB,UAAU,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;aAC/F,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvF,CAAC;IAEO,YAAY,KAAW,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;IAC/D,KAAK;QACZ,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtF,CAAC;IACO,KAAK,CAAC,MAAM,CAAC,SAA8D;QAClF,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1B,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YACtC,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACrG,OAAO,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC;IACf,CAAC;IAED,sGAAsG;IACtG,IAAI,KAAkC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAEjF,KAAK,CAAC,IAAc;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,wFAAwF;IACxF,MAAM,CAAC,SAAuC;QAC7C,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9B,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC;gBAChH,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,EAAE,CAAC;QACjF,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,wGAAwG;IACxG,IAAI;QACH,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvF,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,KAAK;QAClB,IAAI,OAA2B,CAAC;QAChC,GAAG,CAAC;YAAC,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;QAAC,CAAC,QAAQ,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE;QACtF,OAAO,OAAO,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,SAAS;QACtB,MAAM,OAAO,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACnF,IAAI,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC;QACrC,kFAAkF;QAClF,wFAAwF;QACxF,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACtB,MAAM,UAAU,GAAG,OAAO,CAAC;YAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YAChF,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;gBACtC,IAAI,MAAM,CAAC,OAAO;oBAAE,OAAO,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAC5G,IAAI,MAAM,CAAC,QAAQ,KAAK,UAAU,CAAC,QAAQ,IAAI,MAAM,CAAC,WAAW,KAAK,UAAU,CAAC,WAAW;oBAAE,OAAO,MAAM,CAAC;gBAC5G,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACrG,CAAC,CAAC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,QAAQ;YAAE,OAAO,OAAO,CAAC;QACzD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI;YACnE,eAAe,EAAE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC;QAClF,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;YAC7B,IAAI,MAAM,CAAC,WAAW,KAAK,OAAO,CAAC,WAAW;gBAAE,OAAO,MAAM,CAAC;YAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,UAAU;gBAAE,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;YAC3E,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;YACjG,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,UAAU;gBAAE,OAAO,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YACzG,OAAO,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACrG,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,yGAAyG;IACzG,eAAe,CAAC,MAA0B;QACzC,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;YAC9B,IAAI,CAAC,OAAO,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YACjF,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;YAChC,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI;gBAC1E,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI;gBAC3C,OAAO,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE;gBACzG,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACnC,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,mGAAmG;IACnG,OAAO,KAAW,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC,CAAC;CACpF"}

package/dist/sync/record-sync-bridge.d.ts

@@ -1,5 +1,37 @@
-import type { StorageRecordDescriptor } from '../schemas/record';
-import type { SyncBridgeDescriptor } from '../schemas/sync-bridge-descriptor';
+import type { StorageRecordDescriptor } from '../schemas/record/index.ts';
+import type { SyncBridgeHookContext, SyncBridgeRemoteContext, SyncEntity } from '../schemas/sync-bridge-descriptor.ts';
+/** A record is syncable when it is enabled, allows the cloud adapter and declares remote CRUD metadata. */
 export declare function isSyncableStorageRecord(descriptor: StorageRecordDescriptor): boolean;
-export declare function createRecordSyncBridgeDescriptor(descriptor: StorageRecordDescriptor): SyncBridgeDescriptor;
+export declare function createRecordSyncBridgeDescriptor(descriptor: StorageRecordDescriptor): {
+    kind: "storage/sync-bridge";
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    source: {
+        runtimeKind: string;
+    };
+    target: {
+        apiPath: string;
+        entityPath: string | undefined;
+        listField: string | undefined;
+        totalField: string | undefined;
+        includeDeleted: boolean;
+    };
+    sync: {
+        direction: "bidirectional";
+        ownershipFilter: "all" | "user-only" | "system-only";
+        conflictStrategy: "local-wins" | "remote-wins" | "manual" | "newest";
+        sensitiveFields: string[];
+        idField: string;
+    };
+    collect: ({ runtime }: SyncBridgeHookContext) => Promise<Record<string, unknown>[]>;
+    toRemote: ((item: SyncEntity, context?: import("../index.ts").StorageRecordLocalSyncContext) => SyncEntity) | undefined;
+    fromRemote: ((item: SyncEntity) => SyncEntity) | undefined;
+    beforePush: ((record: SyncEntity, context: SyncBridgeRemoteContext) => Promise<void>) | undefined;
+    deleteRemote: ((record: SyncEntity, context: SyncBridgeRemoteContext) => Promise<void>) | undefined;
+    writePulled: (items: SyncEntity[], { runtime }: SyncBridgeHookContext) => Promise<void>;
+};
+/** Derives the local-only record descriptor used for inbound sync writes. Outbound delivery is suppressed. */
+export declare function createLocalRecordDescriptor(descriptor: StorageRecordDescriptor): StorageRecordDescriptor;
 //# sourceMappingURL=record-sync-bridge.d.ts.map

package/dist/sync/record-sync-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-sync-bridge.d.ts","sourceRoot":"","sources":["../../src/sync/record-sync-bridge.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACX,uBAAuB,EAGvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AA0B9E,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,uBAAuB,GAAG,OAAO,CASpF;AAED,wBAAgB,gCAAgC,CAC/C,UAAU,EAAE,uBAAuB,GACjC,oBAAoB,CA4DtB"}
+{"version":3,"file":"record-sync-bridge.d.ts","sourceRoot":"","sources":["../../src/sync/record-sync-bridge.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,uBAAuB,EAAqB,MAAM,4BAA4B,CAAC;AAC7F,OAAO,KAAK,EAAwB,qBAAqB,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,sCAAsC,CAAC;AAO7I,2GAA2G;AAC3G,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,uBAAuB,GAAG,OAAO,CAIpF;AAED,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;2BA0B3D,qBAAqB;;;0BAIV,UAAU,WAAW,uBAAuB;4BACxC,UAAU,WAAW,uBAAuB;yBAC7D,UAAU,EAAE,eAAe,qBAAqB;EAEtE;AAmDD,8GAA8G;AAC9G,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,uBAAuB,GAAG,uBAAuB,CAcxG"}