@vibesdotdev/storage 0.0.2 → 1.0.0-rc.4

package/dist/sync/sync-state.browser.js

@@ -0,0 +1,136 @@
+/**
+ * Storage Sync State Tracking (Browser)
+ *
+ * Browser-scoped sibling of `sync-state.consumer`: same pure state transitions
+ * (from `sync-state.core`), but persistence is the handed runtime's browser
+ * host storage (`runtime/browser-host`) instead of `~/.vibes/sync-state.json`,
+ * and `computeHash` is a dependency-free JS hash. The hash is only used for
+ * within-scope change detection (local vs remote equality), so a stable
+ * non-cryptographic digest is sufficient.
+ *
+ * Browser-safe: no node/fs/crypto imports. A runtime that composes no browser
+ * host keeps its state in memory inside the root-owned `runtime/client`
+ * (`storage.sync-state`) — one store per runtime root, never a module-level
+ * one. A storage read or write that throws, and a stored state that is not
+ * valid, are typed failures, never a silent reset.
+ */
+import { CapabilityError, CaughtFailureSchema, getRuntimeBrowserHost, rootIdentityOf } from '@vibesdotdev/kernel';
+import { resolveSyncStateClient } from "./sync-state.client.js";
+import { SyncStateSchema } from "./schemas/sync-state.js";
+import { createDefaultState, stableJsonStringify } from "./sync-state.core.js";
+export { createDefaultState, createDefaultManifestState, getManifestSyncState, updateManifestSyncState, markSynced, markLocalAhead, markRemoteAhead, markConflict, markError, clearError, markAllPaused, HASH_VERSION } from "./sync-state.core.js";
+const STORAGE_KEY = 'vibes.storage.sync-state';
+/** The context id the runtime's browser host is selected under. */
+const BROWSER_HOST_CONTEXT_ID = 'runtime/browser-host';
+/** `runtime`'s root as the kernel knows it; a runtime double names no root and is refused. */
+function rootOf(runtime) {
+    const identity = rootIdentityOf(runtime);
+    if (!identity) {
+        throw new CapabilityError('The browser sync state is kept per runtime root; this runtime names no root.', 'INVALID_INPUT', {
+            reason: 'sync-state-runtime-unidentified',
+            retryable: false
+        });
+    }
+    return identity;
+}
+/** This root's sync-state client: the kernel-owned home of its fallback state. */
+async function clientOf(runtime) {
+    // A runtime double names no root and is refused before any resolution runs.
+    rootOf(runtime);
+    return resolveSyncStateClient(runtime);
+}
+/** Whether the runtime composes an enabled browser host (the declared fact, asked before resolving it). */
+function composesBrowserHost(runtime) {
+    return runtime.hasKind('context') && runtime.query('context').withId(BROWSER_HOST_CONTEXT_ID).enabled().descriptors().length > 0;
+}
+function storageUnavailable(operation, cause) {
+    return new CapabilityError('The browser storage holding the sync state cannot be used.', 'UNAVAILABLE', {
+        reason: 'sync-state-storage-unavailable',
+        retryable: false,
+        details: { operation },
+        cause
+    });
+}
+async function storeOf(runtime) {
+    if (!composesBrowserHost(runtime)) {
+        const client = await clientOf(runtime);
+        return {
+            get: () => client.memory.text,
+            set: (value) => {
+                client.memory.text = value;
+            }
+        };
+    }
+    const { storage } = await getRuntimeBrowserHost(runtime);
+    return {
+        get: () => {
+            try {
+                return storage.getItem(STORAGE_KEY);
+            }
+            catch (error) {
+                throw storageUnavailable('read', CaughtFailureSchema.parse(error));
+            }
+        },
+        set: (value) => {
+            try {
+                storage.setItem(STORAGE_KEY, value);
+            }
+            catch (error) {
+                throw storageUnavailable('write', CaughtFailureSchema.parse(error));
+            }
+        }
+    };
+}
+function corrupt(detail, cause) {
+    return new CapabilityError('The stored browser sync state is corrupt.', 'INTERNAL', {
+        reason: 'data-corrupt',
+        retryable: false,
+        details: { detail },
+        cause
+    });
+}
+/** The stored sync state: a fresh state when nothing is stored; stored text that is not a valid state is `data-corrupt`. */
+export async function loadSyncState(runtime) {
+    const raw = (await storeOf(runtime)).get();
+    if (raw === null)
+        return createDefaultState();
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw corrupt('json', CaughtFailureSchema.parse(error));
+    }
+    const result = SyncStateSchema.safeParse(parsed);
+    if (!result.success)
+        throw corrupt('schema', result.error);
+    return result.data;
+}
+/** Persist the sync state; a storage write that throws is a typed failure. */
+export async function saveSyncState(state, runtime) {
+    state.updatedAt = new Date().toISOString();
+    (await storeOf(runtime)).set(JSON.stringify(state));
+}
+/**
+ * Stable, dependency-free 53-bit hash (cyrb53) of the JSON form, returned as
+ * hex. Not cryptographic — used only for change detection within this scope.
+ */
+export function computeHash(data) {
+    const str = stableJsonStringify(data);
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < str.length; i++) {
+        const ch = str.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    const hash = 4294967296 * (2097151 & h2) + (h1 >>> 0);
+    return hash.toString(16).padStart(14, '0');
+}
+/** Save-hook policy of this scoped substrate. */
+export const afterSaveOptions = { skipWorkerHosts: false, skipWhenInSync: true };
+//# sourceMappingURL=sync-state.browser.js.map

package/dist/sync/sync-state.browser.js.map

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

package/dist/sync/sync-state.client.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Kernel-owned sync-state session state.
+ *
+ * One client per runtime root (`runtime/client`, id `storage.sync-state`),
+ * resolved through `getVibesClient` by both sync-state substrates
+ * (`sync-state.browser.ts`, `sync-state.consumer.ts`). It holds exactly the
+ * state that used to live in module-level WeakMaps: the browser substrate's
+ * in-memory fallback text, the consumer substrate's loaded-entry snapshots
+ * (a save overlays only what its caller changed since its load), and each
+ * root's saves in flight by state file (a save starts when the one before it
+ * settled). Owning it on the client keeps per-root isolation a kernel fact
+ * and lets disposal clear it.
+ *
+ * The universal `storage.plugin.ts` composes `syncStateClientPlugin` at boot, and a substrate handed a runtime
+ * that has not composed it (a direct module import on a bare test runtime)
+ * resolves it through `resolveSyncStateClient`, which registers the plugin on
+ * that runtime first — never a module-level store.
+ *
+ * Browser-safe: no node/fs/crypto imports — the kernel client base alone.
+ */
+import { BaseRuntimeClient } from '@vibesdotdev/kernel/client';
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+import type { SyncStateMemory } from '../schemas/sync-memory.ts';
+/** The runtime/client id this state lives under (same id as the `storage/sync-state` asset). */
+export declare const STORAGE_SYNC_STATE_CLIENT_ID = "storage.sync-state";
+export declare class SyncStateClient extends BaseRuntimeClient {
+    /** The browser substrate's in-memory text for a root that composes no browser host. */
+    readonly memory: SyncStateMemory;
+    /** The entries each loaded state held when it was read: a save overlays only what its caller changed since. */
+    readonly loadedEntries: WeakMap<{
+        version: 1;
+        updatedAt: string;
+        manifests: Record<string, {
+            manifestId: string;
+            localHash: string | null;
+            remoteHash: string | null;
+            lastLocalChange: string | null;
+            lastRemoteChange: string | null;
+            lastSyncAt: string | null;
+            lastSyncDirection: "push" | "pull" | null;
+            syncStatus: "conflict" | "in-sync" | "local-ahead" | "remote-ahead" | "paused" | "never-synced";
+            errorMessage: string | null;
+            hashVersion?: number | undefined;
+            itemHashes?: Record<string, string> | undefined;
+        }>;
+    }, Record<string, {
+        manifestId: string;
+        localHash: string | null;
+        remoteHash: string | null;
+        lastLocalChange: string | null;
+        lastRemoteChange: string | null;
+        lastSyncAt: string | null;
+        lastSyncDirection: "push" | "pull" | null;
+        syncStatus: "conflict" | "in-sync" | "local-ahead" | "remote-ahead" | "paused" | "never-synced";
+        errorMessage: string | null;
+        hashVersion?: number | undefined;
+        itemHashes?: Record<string, string> | undefined;
+    }>>;
+    /** This root's saves in flight, by state file: a save starts when the one before it settled. */
+    readonly saveTurns: Map<string, Promise<void>>;
+    protected onDispose(): void;
+}
+export default SyncStateClient;
+/** Registers the `storage.sync-state` runtime client on a runtime that has none. */
+export declare const syncStateClientPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+/**
+ * This root's sync-state client: the already-resolved one when the kernel
+ * cache is warm, otherwise the plugin is registered (idempotently — a runtime
+ * that composed `storage`/`storage.consumer` already holds the descriptor)
+ * and the client resolved through the kernel.
+ */
+export declare function resolveSyncStateClient(runtime: RuntimeRef): Promise<SyncStateClient>;
+//# sourceMappingURL=sync-state.client.d.ts.map

package/dist/sync/sync-state.client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state.client.d.ts","sourceRoot":"","sources":["../../src/sync/sync-state.client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EACH,iBAAiB,EAMpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGjE,gGAAgG;AAChG,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE,qBAAa,eAAgB,SAAQ,iBAAiB;IACrD,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAkB;IAElD,+GAA+G;IAC/G,QAAQ,CAAC,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAAoD;IAE1E,gGAAgG;IAChG,QAAQ,CAAC,SAAS,6BAAoC;cAEnC,SAAS,IAAI,IAAI;CAIpC;AAED,eAAe,eAAe,CAAC;AAE/B,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,6CAoBhC,CAAC;AAEH;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAS1F"}

package/dist/sync/sync-state.client.js

@@ -0,0 +1,78 @@
+/**
+ * Kernel-owned sync-state session state.
+ *
+ * One client per runtime root (`runtime/client`, id `storage.sync-state`),
+ * resolved through `getVibesClient` by both sync-state substrates
+ * (`sync-state.browser.ts`, `sync-state.consumer.ts`). It holds exactly the
+ * state that used to live in module-level WeakMaps: the browser substrate's
+ * in-memory fallback text, the consumer substrate's loaded-entry snapshots
+ * (a save overlays only what its caller changed since its load), and each
+ * root's saves in flight by state file (a save starts when the one before it
+ * settled). Owning it on the client keeps per-root isolation a kernel fact
+ * and lets disposal clear it.
+ *
+ * The universal `storage.plugin.ts` composes `syncStateClientPlugin` at boot, and a substrate handed a runtime
+ * that has not composed it (a direct module import on a bare test runtime)
+ * resolves it through `resolveSyncStateClient`, which registers the plugin on
+ * that runtime first — never a module-level store.
+ *
+ * Browser-safe: no node/fs/crypto imports — the kernel client base alone.
+ */
+import { createRuntimePlugin } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient, getVibesClient, runtimeClientPlugin, RuntimeClientDescriptorSchema, tryGetVibesClient } from '@vibesdotdev/kernel/client';
+/** The runtime/client id this state lives under (same id as the `storage/sync-state` asset). */
+export const STORAGE_SYNC_STATE_CLIENT_ID = 'storage.sync-state';
+export class SyncStateClient extends BaseRuntimeClient {
+    /** The browser substrate's in-memory text for a root that composes no browser host. */
+    memory = { text: null };
+    /** The entries each loaded state held when it was read: a save overlays only what its caller changed since. */
+    loadedEntries = new WeakMap();
+    /** This root's saves in flight, by state file: a save starts when the one before it settled. */
+    saveTurns = new Map();
+    onDispose() {
+        this.memory.text = null;
+        this.saveTurns.clear();
+    }
+}
+export default SyncStateClient;
+/** Registers the `storage.sync-state` runtime client on a runtime that has none. */
+export const syncStateClientPlugin = createRuntimePlugin({
+    id: 'storage.sync-state-client',
+    name: 'Storage Sync State Client',
+    description: 'Root-owned home of the storage sync-state session state (browser fallback text, loaded snapshots, save turns).',
+    descriptors: [RuntimeClientDescriptorSchema.parse({
+            id: STORAGE_SYNC_STATE_CLIENT_ID,
+            kind: 'runtime/client',
+            name: 'Storage Sync State'
+        })],
+    onRegister: async (runtime) => {
+        if (!runtime.hasKind('runtime/client'))
+            await runtime.registerPlugin(runtimeClientPlugin);
+        runtime.registerLoader('runtime/client', STORAGE_SYNC_STATE_CLIENT_ID, async () => ({
+            impl: SyncStateClient
+        }));
+    },
+    onDispose: async (runtime) => {
+        const client = runtime.query('runtime/client')
+            .withId(STORAGE_SYNC_STATE_CLIENT_ID).peek?.();
+        await client?.dispose();
+    }
+});
+/**
+ * This root's sync-state client: the already-resolved one when the kernel
+ * cache is warm, otherwise the plugin is registered (idempotently — a runtime
+ * that composed `storage`/`storage.consumer` already holds the descriptor)
+ * and the client resolved through the kernel.
+ */
+export async function resolveSyncStateClient(runtime) {
+    const warm = tryGetVibesClient(STORAGE_SYNC_STATE_CLIENT_ID, runtime);
+    if (warm)
+        return warm;
+    if (!runtime.hasKind('runtime/client')
+        || runtime.query('runtime/client')
+            .withId(STORAGE_SYNC_STATE_CLIENT_ID).descriptors().length === 0) {
+        await runtime.registerPlugin(syncStateClientPlugin);
+    }
+    return getVibesClient(STORAGE_SYNC_STATE_CLIENT_ID, runtime);
+}
+//# sourceMappingURL=sync-state.client.js.map

package/dist/sync/sync-state.client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-state.client.js","sourceRoot":"","sources":["../../src/sync/sync-state.client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EACH,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,6BAA6B,EAC7B,iBAAiB,EAEpB,MAAM,4BAA4B,CAAC;AAKpC,gGAAgG;AAChG,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAAoB,CAAC;AAEjE,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IACrD,uFAAuF;IAC9E,MAAM,GAAoB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAElD,+GAA+G;IACtG,aAAa,GAAG,IAAI,OAAO,EAAqC,CAAC;IAE1E,gGAAgG;IACvF,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEnC,SAAS;QAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACD;AAED,eAAe,eAAe,CAAC;AAE/B,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;IACxD,EAAE,EAAE,2BAA2B;IAC/B,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,gHAAgH;IAC7H,WAAW,EAAE,CAAC,6BAA6B,CAAC,KAAK,CAAC;YACjD,EAAE,EAAE,4BAA4B;YAChC,IAAI,EAAE,gBAAgB;YACtB,IAAI,EAAE,oBAAoB;SAC1B,CAAC,CAAC;IACH,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC7B,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;YAAE,MAAM,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QAC1F,OAAO,CAAC,cAAc,CAA2C,gBAAgB,EAAE,4BAA4B,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YAC7H,IAAI,EAAE,eAAe;SACrB,CAAC,CAAC,CAAC;IACL,CAAC;IACD,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAA2C,gBAAgB,CAAC;aACtF,MAAM,CAAC,4BAA4B,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAChD,MAAM,MAAM,EAAE,OAAO,EAAE,CAAC;IACzB,CAAC;CACD,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,OAAmB;IAC/D,MAAM,IAAI,GAAG,iBAAiB,CAAkB,4BAA4B,EAAE,OAAO,CAAC,CAAC;IACvF,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;WAClC,OAAO,CAAC,KAAK,CAA2C,gBAAgB,CAAC;aAC1E,MAAM,CAAC,4BAA4B,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,cAAc,CAAkB,4BAA4B,EAAE,OAAO,CAAC,CAAC;AAC/E,CAAC"}

package/dist/sync/sync-state.consumer.d.ts

@@ -1,23 +1,50 @@
 /**
  * Storage Sync State Tracking (Consumer)
  *
- * Tracks per-manifest sync state: hashes, timestamps, and conflict status.
- * Stored in ~/.vibes/sync-state.json via direct JSON I/O (intentionally
- * bypasses StorageManifest to avoid circular dependency).
+ * Persists the per-manifest sync state in `{vibesHome}/sync-state.json` through
+ * the handed runtime's filesystem kind (`filesystem/adapter`), intentionally
+ * bypassing StorageManifest to avoid a circular dependency. State transitions
+ * live in the environment-agnostic `sync-state.core` (shared with the browser
+ * path); this module owns only the consumer-scoped persistence and the hash.
  *
- * Consumer-scoped: uses host fs for persistence.
+ * Path roots: the handed runtime's `paths/roots` vibesHome (same contract as
+ * StorageRecord global scope / #894) — never bare `homedir()/.vibes`, and never
+ * an ambient runtime.
+ *
+ * Session state (the entries each loaded state held when it was read, and the
+ * saves in flight per state file) lives on the root-owned
+ * `runtime/client#storage.sync-state` (`SyncStateClient`), resolved through
+ * `getVibesClient` — never a module-level store.
+ *
+ * A save is atomic, owner-only and merged. Saves of one state file run one at a
+ * time per runtime root; each re-reads the file, overlays only the entries its
+ * caller changed since its load (so concurrent pushes and CLI runs keep each
+ * other's entries), writes a same-directory temporary file with mode 0600 and
+ * renames it over the state, so a failed write leaves the prior file intact.
+ */
+import { type RuntimeRef } from '@vibesdotdev/kernel';
+import { type SyncState } from './schemas/sync-state.ts';
+export type { SyncState, SyncStatus, ManifestSyncState } from './sync-state.core.ts';
+export { createDefaultState, createDefaultManifestState, getManifestSyncState, updateManifestSyncState, markSynced, markLocalAhead, markRemoteAhead, markConflict, markError, clearError, markAllPaused, mergeSyncStateSnapshots, HASH_VERSION, } from './sync-state.core.ts';
+/** What the sync-state store needs from the runtime it is handed: its roots, filesystem and lifecycle. */
+export type SyncStateRuntime = RuntimeRef;
+/**
+ * The persisted sync state. An absent file is a fresh state; a file that cannot
+ * be read or parsed is a typed failure, never silently reset.
+ */
+export declare function loadSyncState(runtime: SyncStateRuntime): Promise<SyncState>;
+/**
+ * Persist the sync state, merged over what the file holds now: the entries this
+ * caller changed since its load win, every other persisted entry is kept. The
+ * runtime comes second so the browser sibling's `saveSyncState(state)`
+ * satisfies the same module shape.
  */
-import { type SyncState, type ManifestSyncState } from './schemas/sync-state';
-export type { SyncState, SyncStatus, ManifestSyncState } from './schemas/sync-state';
-export declare function loadSyncState(): Promise<SyncState>;
-export declare function saveSyncState(state: SyncState): Promise<void>;
-export declare function getManifestSyncState(state: SyncState, manifestId: string): ManifestSyncState;
-export declare function updateManifestSyncState(state: SyncState, manifestId: string, update: Partial<ManifestSyncState>): void;
-export declare function markSynced(state: SyncState, manifestId: string, hash: string, direction: 'push' | 'pull'): void;
-export declare function markLocalAhead(state: SyncState, manifestId: string, localHash: string): void;
-export declare function markRemoteAhead(state: SyncState, manifestId: string, remoteHash: string): void;
-export declare function markConflict(state: SyncState, manifestId: string, localHash: string, remoteHash: string): void;
-export declare function markError(state: SyncState, manifestId: string, errorMessage: string): void;
-export declare function markAllPaused(state: SyncState): void;
-export declare function computeHash(data: unknown): string;
+export declare function saveSyncState(state: SyncState, runtime: SyncStateRuntime): Promise<void>;
+/** The SHA-256 (hex) of the value's stable JSON form: the change-detection digest sync state persists. */
+export declare function computeHash<TValue>(data: TValue): string;
+/** Save-hook policy of this scoped substrate. */
+export declare const afterSaveOptions: {
+    skipWorkerHosts: boolean;
+    skipWhenInSync: boolean;
+};
 //# sourceMappingURL=sync-state.consumer.d.ts.map

package/dist/sync/sync-state.consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-state.consumer.d.ts","sourceRoot":"","sources":["../../src/sync/sync-state.consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAmB,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG/F,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AA2BrF,wBAAsB,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC,CAaxD;AAED,wBAAsB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAUnE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAE5F;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAChC,IAAI,CAGN;AAED,wBAAgB,UAAU,CACzB,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,MAAM,GACxB,IAAI,CAWN;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAM5F;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAM9F;AAED,wBAAgB,YAAY,CAC3B,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAE1F;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAIpD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEjD"}
+{"version":3,"file":"sync-state.consumer.d.ts","sourceRoot":"","sources":["../../src/sync/sync-state.consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAKH,KAAK,UAAU,EAElB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAE1E,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EACH,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,uBAAuB,EACvB,UAAU,EACV,cAAc,EACd,eAAe,EACf,YAAY,EACZ,SAAS,EACT,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,YAAY,GACf,MAAM,sBAAsB,CAAC;AAI9B,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC;AAuE1C;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAKjF;AAqDD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB9F;AAED,0GAA0G;AAC1G,wBAAgB,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,iDAAiD;AACjD,eAAO,MAAM,gBAAgB;;;CAAmD,CAAC"}