@tearleads/client-sdk 0.1.63 → 0.1.65

package/stores/container-contents/syncAgent/index.js

@@ -0,0 +1,241 @@
+import { loadLocalContainerStates } from "../../../workflows/container-contents/localState.js";
+import { isDatabaseUnavailableError, registerContainerContentsSyncLane, } from "../../../workflows/container-contents/syncLane.js";
+import { createRestoredAccessReconciler } from "../accessRestorationSweep.js";
+import { primeStoreDocumentSubtree } from "../documentWork/documentRecovery.js";
+import { observeContainerBackgroundHydration } from "../hydration/backgroundHydration.js";
+import { refreshAllRemoteHydration, refreshRootRemoteHydration, } from "../hydration/remoteHydrationRefresh.js";
+import { requestContainerContentsRemoteHydration } from "../hydration/remoteHydrationRequest.js";
+import { hasStartupContainerSyncWork, scheduleStaleStartupRemoteHydration, } from "../hydration/startupHydration.js";
+import { refreshLocalContainerStates } from "../localRefresh.js";
+import { getContainerContentsStoreLogLabel } from "../logLabel.js";
+import { createRemoteContainerIngestionController } from "../remoteEvents/remoteContainerIngestion.js";
+import { handleContainerContentsRemoteEvents } from "../remoteEvents/remoteEventSync.js";
+import { consumePendingContainerContentsReconnectRefresh } from "../state.js";
+import { runContainerContentsStoreSyncIteration } from "./syncLaneIteration.js";
+function requestContainerContentsStoreSync(state) {
+    state.syncLane?.requestSync();
+}
+async function initializeContainerContentsStore(input) {
+    const { handleRemoteEvents, host, isCurrent, resumeRecoveryWork, scheduleSync, state, } = input;
+    const persistence = state.persistence;
+    const loadRuntime = state.runtime;
+    if (loadRuntime.infra.dbStatus !== "ready") {
+        return;
+    }
+    const localContainerStates = await loadLocalContainerStates({
+        persistence,
+        runtime: loadRuntime,
+    });
+    if (!isCurrent()) {
+        return;
+    }
+    for (const containerState of localContainerStates) {
+        state.containersById.set(containerState.container.id, containerState);
+    }
+    state.initialized = true;
+    const shouldScheduleStaleRootRecovery = await scheduleStaleStartupRemoteHydration({
+        isCurrent,
+        requestHydration: () => requestContainerContentsRemoteHydration({
+            host,
+            resumeRecoveryWork,
+            scheduleSync,
+            state,
+        }),
+        state,
+    });
+    if (!isCurrent()) {
+        return;
+    }
+    const runtime = state.runtime;
+    const hasPendingRestorationSweep = typeof runtime.auth.userId === "string" &&
+        (await persistence.listDormantMetadataSweepRequests(loadRuntime.infra.execSql, runtime.auth.userId)).length > 0;
+    if (!isCurrent()) {
+        return;
+    }
+    host.updateSnapshot();
+    handleRemoteEvents();
+    runtime.util.log(`${getContainerContentsStoreLogLabel(state)}: loaded ${state.containersById.size} container(s)`);
+    const currentRuntime = state.runtime;
+    if (currentRuntime.auth.isAuthenticated && currentRuntime.state.online) {
+        const hasStartupWork = shouldScheduleStaleRootRecovery ||
+            hasPendingRestorationSweep ||
+            (await hasStartupContainerSyncWork(state));
+        if (!isCurrent() || !hasStartupWork) {
+            return;
+        }
+        currentRuntime.util.log(shouldScheduleStaleRootRecovery
+            ? `${getContainerContentsStoreLogLabel(state)}: startup detected stale root recovery; scheduling lane pass`
+            : `${getContainerContentsStoreLogLabel(state)}: startup detected durable sync work; scheduling lane pass`);
+        scheduleSync();
+    }
+}
+function waitForStaleLocalRefreshBeforeInitialization(input) {
+    const { state } = input;
+    const activeRefresh = state.localContainerRefreshPromise;
+    if (!activeRefresh ||
+        (state.localContainerRefreshGeneration === state.lifecycleGeneration &&
+            state.localContainerRefreshStructuralGeneration ===
+                state.structuralGeneration)) {
+        return false;
+    }
+    const lifecycleGeneration = state.lifecycleGeneration;
+    state.initializeGeneration = lifecycleGeneration;
+    const releaseInitializationBarrier = () => {
+        if (state.initializePromise !== initializationBarrier) {
+            return;
+        }
+        state.initializePromise = null;
+        state.initializeGeneration = null;
+        if (state.runtime.infra.dbStatus === "ready") {
+            ensureContainerContentsStoreInitialized(input);
+        }
+    };
+    const initializationBarrier = activeRefresh.then(releaseInitializationBarrier, releaseInitializationBarrier);
+    state.initializePromise = initializationBarrier;
+    return true;
+}
+function ensureContainerContentsStoreInitialized(input) {
+    const { handleRemoteEvents, host, resumeRecoveryWork, scheduleSync, state } = input;
+    if (state.initialized || state.runtime.infra.dbStatus !== "ready") {
+        return;
+    }
+    if (state.initializePromise) {
+        return;
+    }
+    if (waitForStaleLocalRefreshBeforeInitialization(input)) {
+        return;
+    }
+    const lifecycleGeneration = state.lifecycleGeneration;
+    const persistence = state.persistence;
+    const execSql = state.runtime.infra.execSql;
+    const isCurrent = () => state.lifecycleGeneration === lifecycleGeneration &&
+        state.persistence === persistence &&
+        state.runtime.infra.execSql === execSql;
+    state.initializeGeneration = lifecycleGeneration;
+    const initializePromise = initializeContainerContentsStore({
+        handleRemoteEvents,
+        host,
+        isCurrent,
+        resumeRecoveryWork,
+        scheduleSync,
+        state,
+    })
+        .catch((error) => {
+        if (!isCurrent() || isDatabaseUnavailableError(error)) {
+            return;
+        }
+        throw error;
+    })
+        .finally(() => {
+        if (state.initializePromise !== initializePromise) {
+            return;
+        }
+        state.initializePromise = null;
+        state.initializeGeneration = null;
+        if (isCurrent()) {
+            consumePendingContainerContentsReconnectRefresh(state, input.refreshAfterReconnect);
+        }
+        else if (state.runtime.infra.dbStatus === "ready") {
+            ensureContainerContentsStoreInitialized(input);
+        }
+    });
+    state.initializePromise = initializePromise;
+}
+// Read the runtime lazily: updateRuntime replaces state.runtime, so a
+// reference captured at lane registration would report into a dead identity's
+// host. Returns the host's result: both callbacks are declared `=> void` but
+// may be async, and the lane reporter only catches a rejection it is handed.
+function logSyncLaneFailure(state, message, error) {
+    const { log, logError } = state.runtime.util;
+    return logError ? logError(message, error) : log(message);
+}
+function createHydrationRequester(input) {
+    return (options = {}) => requestContainerContentsRemoteHydration({
+        ...input,
+        followDiscoveredParentLanes: options.followDiscoveredParentLanes,
+        parentIds: options.parentIds,
+        resetAllLaneWatermarks: options.resetAllLaneWatermarks,
+    });
+}
+export function createContainerContentsStoreSyncAgent(input) {
+    const { host, state } = input;
+    const scheduleSync = () => requestContainerContentsStoreSync(state);
+    const remoteContainerIngestion = createRemoteContainerIngestionController({
+        host,
+        scheduleSync,
+        state,
+    });
+    const resumeRecoveryWork = remoteContainerIngestion.resumeInterruptedWork;
+    const requestHydration = createHydrationRequester({
+        host,
+        resumeRecoveryWork,
+        scheduleSync,
+        state,
+    });
+    const requestRefreshHydration = (options) => requestContainerContentsRemoteHydration({
+        ...options,
+        host,
+        resumeRecoveryWork,
+        scheduleSync,
+        state,
+    });
+    const scheduleHydration = (options) => observeContainerBackgroundHydration(state, requestHydration(options));
+    const refresh = (options) => refreshAllRemoteHydration({
+        // Explicit user refresh must rediscover children hidden by unsigned hints.
+        resetAllLaneWatermarks: options?.resetAllLaneWatermarks,
+        requestHydration: requestRefreshHydration,
+        state,
+    });
+    const handleRemoteEvents = () => handleContainerContentsRemoteEvents({
+        requestHydration,
+        scheduleSync,
+        state,
+    });
+    const reconcileRestoredAccess = createRestoredAccessReconciler({
+        requestHydration: requestRefreshHydration,
+        state,
+    });
+    state.syncLane = registerContainerContentsSyncLane({
+        domainScope: state.runtime.state.domainScope,
+        logError: (message, error) => logSyncLaneFailure(state, message, error),
+        run: () => runContainerContentsStoreSyncIteration({
+            host,
+            reconcileRestoredAccess,
+            requestRemoteReconciliation: (parentContainerId) => {
+                scheduleHydration({
+                    followDiscoveredParentLanes: false,
+                    parentIds: [parentContainerId],
+                });
+            },
+            state,
+        }),
+    });
+    return {
+        ensureInitialized: () => {
+            ensureContainerContentsStoreInitialized({
+                handleRemoteEvents,
+                host,
+                refreshAfterReconnect: refresh,
+                resumeRecoveryWork,
+                scheduleSync,
+                state,
+            });
+            void resumeRecoveryWork();
+        },
+        handleRemoteEvents,
+        ingestRemoteContainer: remoteContainerIngestion.ingest,
+        primeDocumentsForSharedSubtree: (rootContainerId, isCurrent) => primeStoreDocumentSubtree(state, rootContainerId, isCurrent),
+        refreshLocalContainers: () => refreshLocalContainerStates({ host, state }),
+        refresh,
+        refreshRootLane: (options) => refreshRootRemoteHydration({
+            includeActiveRootChildLane: options?.includeActiveRootChildLane,
+            parentIds: options?.parentIds,
+            requestHydration: requestRefreshHydration,
+            state,
+        }),
+        requestRemoteHydration: requestHydration,
+        scheduleRemoteHydration: scheduleHydration,
+        scheduleSync,
+    };
+}
+//# sourceMappingURL=index.js.map

package/stores/container-contents/syncAgent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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","sourcesContent":["import { loadLocalContainerStates } from \"../../../workflows/container-contents/localState\";\nimport type { RemoteContainerHydrationHost } from \"../../../workflows/container-contents/remoteHydration\";\nimport {\n  isDatabaseUnavailableError,\n  registerContainerContentsSyncLane,\n} from \"../../../workflows/container-contents/syncLane\";\nimport { createRestoredAccessReconciler } from \"../accessRestorationSweep\";\nimport { primeStoreDocumentSubtree } from \"../documentWork/documentRecovery\";\nimport { observeContainerBackgroundHydration } from \"../hydration/backgroundHydration\";\nimport {\n  type RemoteHydrationRefreshOptions,\n  refreshAllRemoteHydration,\n  refreshRootRemoteHydration,\n} from \"../hydration/remoteHydrationRefresh\";\nimport { requestContainerContentsRemoteHydration } from \"../hydration/remoteHydrationRequest\";\nimport {\n  hasStartupContainerSyncWork,\n  scheduleStaleStartupRemoteHydration,\n} from \"../hydration/startupHydration\";\nimport { refreshLocalContainerStates } from \"../localRefresh\";\nimport { getContainerContentsStoreLogLabel } from \"../logLabel\";\nimport { createRemoteContainerIngestionController } from \"../remoteEvents/remoteContainerIngestion\";\nimport { handleContainerContentsRemoteEvents } from \"../remoteEvents/remoteEventSync\";\nimport { consumePendingContainerContentsReconnectRefresh } from \"../state\";\nimport type {\n  ContainerContentsStoreSyncAgent,\n  ContainerContentsStoreSyncState,\n} from \"./syncAgentTypes\";\nimport { runContainerContentsStoreSyncIteration } from \"./syncLaneIteration\";\n\nexport type { ContainerState } from \"../../../workflows/container-contents/remoteHydration\";\nexport type {\n  ContainerContentsStoreRuntime,\n  ContainerContentsStoreSyncAgent,\n  ContainerContentsStoreSyncState,\n  RefreshRootLaneOptions,\n} from \"./syncAgentTypes\";\n\nfunction requestContainerContentsStoreSync(\n  state: ContainerContentsStoreSyncState,\n) {\n  state.syncLane?.requestSync();\n}\n\nasync function initializeContainerContentsStore(input: {\n  handleRemoteEvents: () => void;\n  host: RemoteContainerHydrationHost;\n  isCurrent: () => boolean;\n  resumeRecoveryWork: () => Promise<void>;\n  scheduleSync: () => void;\n  state: ContainerContentsStoreSyncState;\n}) {\n  const {\n    handleRemoteEvents,\n    host,\n    isCurrent,\n    resumeRecoveryWork,\n    scheduleSync,\n    state,\n  } = input;\n  const persistence = state.persistence;\n  const loadRuntime = state.runtime;\n  if (loadRuntime.infra.dbStatus !== \"ready\") {\n    return;\n  }\n\n  const localContainerStates = await loadLocalContainerStates({\n    persistence,\n    runtime: loadRuntime,\n  });\n  if (!isCurrent()) {\n    return;\n  }\n\n  for (const containerState of localContainerStates) {\n    state.containersById.set(containerState.container.id, containerState);\n  }\n\n  state.initialized = true;\n\n  const shouldScheduleStaleRootRecovery =\n    await scheduleStaleStartupRemoteHydration({\n      isCurrent,\n      requestHydration: () =>\n        requestContainerContentsRemoteHydration({\n          host,\n          resumeRecoveryWork,\n          scheduleSync,\n          state,\n        }),\n      state,\n    });\n  if (!isCurrent()) {\n    return;\n  }\n  const runtime = state.runtime;\n  const hasPendingRestorationSweep =\n    typeof runtime.auth.userId === \"string\" &&\n    (\n      await persistence.listDormantMetadataSweepRequests(\n        loadRuntime.infra.execSql,\n        runtime.auth.userId,\n      )\n    ).length > 0;\n  if (!isCurrent()) {\n    return;\n  }\n\n  host.updateSnapshot();\n  handleRemoteEvents();\n\n  runtime.util.log(\n    `${getContainerContentsStoreLogLabel(state)}: loaded ${state.containersById.size} container(s)`,\n  );\n\n  const currentRuntime = state.runtime;\n  if (currentRuntime.auth.isAuthenticated && currentRuntime.state.online) {\n    const hasStartupWork =\n      shouldScheduleStaleRootRecovery ||\n      hasPendingRestorationSweep ||\n      (await hasStartupContainerSyncWork(state));\n    if (!isCurrent() || !hasStartupWork) {\n      return;\n    }\n    currentRuntime.util.log(\n      shouldScheduleStaleRootRecovery\n        ? `${getContainerContentsStoreLogLabel(state)}: startup detected stale root recovery; scheduling lane pass`\n        : `${getContainerContentsStoreLogLabel(state)}: startup detected durable sync work; scheduling lane pass`,\n    );\n    scheduleSync();\n  }\n}\n\nfunction waitForStaleLocalRefreshBeforeInitialization(input: {\n  handleRemoteEvents: () => void;\n  host: RemoteContainerHydrationHost;\n  refreshAfterReconnect: () => Promise<boolean>;\n  resumeRecoveryWork: () => Promise<void>;\n  scheduleSync: () => void;\n  state: ContainerContentsStoreSyncState;\n}): boolean {\n  const { state } = input;\n  const activeRefresh = state.localContainerRefreshPromise;\n  if (\n    !activeRefresh ||\n    (state.localContainerRefreshGeneration === state.lifecycleGeneration &&\n      state.localContainerRefreshStructuralGeneration ===\n        state.structuralGeneration)\n  ) {\n    return false;\n  }\n\n  const lifecycleGeneration = state.lifecycleGeneration;\n  state.initializeGeneration = lifecycleGeneration;\n  const releaseInitializationBarrier = () => {\n    if (state.initializePromise !== initializationBarrier) {\n      return;\n    }\n    state.initializePromise = null;\n    state.initializeGeneration = null;\n    if (state.runtime.infra.dbStatus === \"ready\") {\n      ensureContainerContentsStoreInitialized(input);\n    }\n  };\n  const initializationBarrier = activeRefresh.then(\n    releaseInitializationBarrier,\n    releaseInitializationBarrier,\n  );\n  state.initializePromise = initializationBarrier;\n  return true;\n}\n\nfunction ensureContainerContentsStoreInitialized(input: {\n  handleRemoteEvents: () => void;\n  host: RemoteContainerHydrationHost;\n  refreshAfterReconnect: () => Promise<boolean>;\n  resumeRecoveryWork: () => Promise<void>;\n  scheduleSync: () => void;\n  state: ContainerContentsStoreSyncState;\n}) {\n  const { handleRemoteEvents, host, resumeRecoveryWork, scheduleSync, state } =\n    input;\n  if (state.initialized || state.runtime.infra.dbStatus !== \"ready\") {\n    return;\n  }\n  if (state.initializePromise) {\n    return;\n  }\n  if (waitForStaleLocalRefreshBeforeInitialization(input)) {\n    return;\n  }\n\n  const lifecycleGeneration = state.lifecycleGeneration;\n  const persistence = state.persistence;\n  const execSql = state.runtime.infra.execSql;\n  const isCurrent = () =>\n    state.lifecycleGeneration === lifecycleGeneration &&\n    state.persistence === persistence &&\n    state.runtime.infra.execSql === execSql;\n  state.initializeGeneration = lifecycleGeneration;\n  const initializePromise = initializeContainerContentsStore({\n    handleRemoteEvents,\n    host,\n    isCurrent,\n    resumeRecoveryWork,\n    scheduleSync,\n    state,\n  })\n    .catch((error: unknown) => {\n      if (!isCurrent() || isDatabaseUnavailableError(error)) {\n        return;\n      }\n\n      throw error;\n    })\n    .finally(() => {\n      if (state.initializePromise !== initializePromise) {\n        return;\n      }\n      state.initializePromise = null;\n      state.initializeGeneration = null;\n      if (isCurrent()) {\n        consumePendingContainerContentsReconnectRefresh(\n          state,\n          input.refreshAfterReconnect,\n        );\n      } else if (state.runtime.infra.dbStatus === \"ready\") {\n        ensureContainerContentsStoreInitialized(input);\n      }\n    });\n  state.initializePromise = initializePromise;\n}\n\n// Read the runtime lazily: updateRuntime replaces state.runtime, so a\n// reference captured at lane registration would report into a dead identity's\n// host. Returns the host's result: both callbacks are declared `=> void` but\n// may be async, and the lane reporter only catches a rejection it is handed.\nfunction logSyncLaneFailure(\n  state: ContainerContentsStoreSyncState,\n  message: string,\n  error: unknown,\n): unknown {\n  const { log, logError } = state.runtime.util;\n  return logError ? logError(message, error) : log(message);\n}\n\nfunction createHydrationRequester(input: {\n  host: RemoteContainerHydrationHost;\n  resumeRecoveryWork: () => Promise<void>;\n  scheduleSync: () => void;\n  state: ContainerContentsStoreSyncState;\n}): ContainerContentsStoreSyncAgent[\"requestRemoteHydration\"] {\n  return (options = {}) =>\n    requestContainerContentsRemoteHydration({\n      ...input,\n      followDiscoveredParentLanes: options.followDiscoveredParentLanes,\n      parentIds: options.parentIds,\n      resetAllLaneWatermarks: options.resetAllLaneWatermarks,\n    });\n}\n\nexport function createContainerContentsStoreSyncAgent(input: {\n  host: RemoteContainerHydrationHost;\n  state: ContainerContentsStoreSyncState;\n}): ContainerContentsStoreSyncAgent {\n  const { host, state } = input;\n  const scheduleSync = () => requestContainerContentsStoreSync(state);\n  const remoteContainerIngestion = createRemoteContainerIngestionController({\n    host,\n    scheduleSync,\n    state,\n  });\n  const resumeRecoveryWork = remoteContainerIngestion.resumeInterruptedWork;\n\n  const requestHydration = createHydrationRequester({\n    host,\n    resumeRecoveryWork,\n    scheduleSync,\n    state,\n  });\n  const requestRefreshHydration = (options: RemoteHydrationRefreshOptions) =>\n    requestContainerContentsRemoteHydration({\n      ...options,\n      host,\n      resumeRecoveryWork,\n      scheduleSync,\n      state,\n    });\n  const scheduleHydration = (\n    options?: Parameters<typeof requestHydration>[0],\n  ) => observeContainerBackgroundHydration(state, requestHydration(options));\n  const refresh: ContainerContentsStoreSyncAgent[\"refresh\"] = (options) =>\n    refreshAllRemoteHydration({\n      // Explicit user refresh must rediscover children hidden by unsigned hints.\n      resetAllLaneWatermarks: options?.resetAllLaneWatermarks,\n      requestHydration: requestRefreshHydration,\n      state,\n    });\n  const handleRemoteEvents = () =>\n    handleContainerContentsRemoteEvents({\n      requestHydration,\n      scheduleSync,\n      state,\n    });\n  const reconcileRestoredAccess = createRestoredAccessReconciler({\n    requestHydration: requestRefreshHydration,\n    state,\n  });\n\n  state.syncLane = registerContainerContentsSyncLane({\n    domainScope: state.runtime.state.domainScope,\n    logError: (message, error) => logSyncLaneFailure(state, message, error),\n    run: () =>\n      runContainerContentsStoreSyncIteration({\n        host,\n        reconcileRestoredAccess,\n        requestRemoteReconciliation: (parentContainerId) => {\n          scheduleHydration({\n            followDiscoveredParentLanes: false,\n            parentIds: [parentContainerId],\n          });\n        },\n        state,\n      }),\n  });\n\n  return {\n    ensureInitialized: () => {\n      ensureContainerContentsStoreInitialized({\n        handleRemoteEvents,\n        host,\n        refreshAfterReconnect: refresh,\n        resumeRecoveryWork,\n        scheduleSync,\n        state,\n      });\n      void resumeRecoveryWork();\n    },\n    handleRemoteEvents,\n    ingestRemoteContainer: remoteContainerIngestion.ingest,\n    primeDocumentsForSharedSubtree: (rootContainerId, isCurrent) =>\n      primeStoreDocumentSubtree(state, rootContainerId, isCurrent),\n    refreshLocalContainers: () => refreshLocalContainerStates({ host, state }),\n    refresh,\n    refreshRootLane: (options) =>\n      refreshRootRemoteHydration({\n        includeActiveRootChildLane: options?.includeActiveRootChildLane,\n        parentIds: options?.parentIds,\n        requestHydration: requestRefreshHydration,\n        state,\n      }),\n    requestRemoteHydration: requestHydration,\n    scheduleRemoteHydration: scheduleHydration,\n    scheduleSync,\n  };\n}\n"]}

package/stores/container-contents/syncAgent/metadataSyncSignal.js

@@ -0,0 +1,37 @@
+/**
+ * Convergence-safety helpers for the container-contents metadata sync lane.
+ *
+ * `syncSingleContainerMetadata` reads `forceReadSync` for a container, then
+ * awaits a network GET of the container's metadata document. A remote
+ * rename/move event delivered during that await re-queues the container's
+ * metadata id and advances that id's entry in `metadataSyncSignalSeqById`. If
+ * the pass then deleted the id unconditionally it would erase that fresh
+ * re-queue, leaving the structural projection (name/icon) stale until an
+ * unrelated later event re-armed it.
+ *
+ * The pass therefore snapshots the id's sequence before its GET and only clears
+ * the queued id when that id's sequence is unchanged at pass end. The sequence
+ * is tracked per metadata document id (not a single global counter) so a remote
+ * event for an unrelated container does not block clearing this one. Mirrors
+ * the document store's `remoteUpdateSignalSeq` clear (the document store is
+ * single-document, so it needs only one counter).
+ */
+import { sequenceUnchanged } from "../../../workflows/container-contents/syncLane.js";
+/** Read an id's current enqueue sequence, defaulting to 0 when never queued. */
+export function readMetadataSyncSeq(seqById, id) {
+    return seqById.get(id) ?? 0;
+}
+/** Advance an id's enqueue sequence (called when a remote event re-queues it). */
+export function bumpMetadataSyncSeq(seqById, id) {
+    seqById.set(id, readMetadataSyncSeq(seqById, id) + 1);
+}
+/**
+ * Delete `id` from the needs-sync queue only if no remote event re-queued that
+ * specific id since `consumedSeqById` was snapshotted at pass entry.
+ */
+export function clearMetadataSyncQueueIfUnchanged(input) {
+    if (sequenceUnchanged(readMetadataSyncSeq(input.seqById, input.id), input.consumedSeqById.get(input.id) ?? 0)) {
+        input.needingSync.delete(input.id);
+    }
+}
+//# sourceMappingURL=metadataSyncSignal.js.map

package/stores/container-contents/syncAgent/metadataSyncSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataSyncSignal.js","sourceRoot":"","sources":["metadataSyncSignal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AAEnF,gFAAgF;AAChF,MAAM,UAAU,mBAAmB,CACjC,OAAoC,EACpC,EAAU;IAEV,OAAO,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CACjC,OAA4B,EAC5B,EAAU;IAEV,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iCAAiC,CAAC,KAKjD;IACC,IACE,iBAAiB,CACf,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,EAC5C,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,CACzC,EACD,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;AACH,CAAC","sourcesContent":["/**\n * Convergence-safety helpers for the container-contents metadata sync lane.\n *\n * `syncSingleContainerMetadata` reads `forceReadSync` for a container, then\n * awaits a network GET of the container's metadata document. A remote\n * rename/move event delivered during that await re-queues the container's\n * metadata id and advances that id's entry in `metadataSyncSignalSeqById`. If\n * the pass then deleted the id unconditionally it would erase that fresh\n * re-queue, leaving the structural projection (name/icon) stale until an\n * unrelated later event re-armed it.\n *\n * The pass therefore snapshots the id's sequence before its GET and only clears\n * the queued id when that id's sequence is unchanged at pass end. The sequence\n * is tracked per metadata document id (not a single global counter) so a remote\n * event for an unrelated container does not block clearing this one. Mirrors\n * the document store's `remoteUpdateSignalSeq` clear (the document store is\n * single-document, so it needs only one counter).\n */\n\nimport { sequenceUnchanged } from \"../../../workflows/container-contents/syncLane\";\n\n/** Read an id's current enqueue sequence, defaulting to 0 when never queued. */\nexport function readMetadataSyncSeq(\n  seqById: ReadonlyMap<string, number>,\n  id: string,\n): number {\n  return seqById.get(id) ?? 0;\n}\n\n/** Advance an id's enqueue sequence (called when a remote event re-queues it). */\nexport function bumpMetadataSyncSeq(\n  seqById: Map<string, number>,\n  id: string,\n): void {\n  seqById.set(id, readMetadataSyncSeq(seqById, id) + 1);\n}\n\n/**\n * Delete `id` from the needs-sync queue only if no remote event re-queued that\n * specific id since `consumedSeqById` was snapshotted at pass entry.\n */\nexport function clearMetadataSyncQueueIfUnchanged(input: {\n  needingSync: Set<string>;\n  seqById: ReadonlyMap<string, number>;\n  consumedSeqById: ReadonlyMap<string, number>;\n  id: string;\n}): void {\n  if (\n    sequenceUnchanged(\n      readMetadataSyncSeq(input.seqById, input.id),\n      input.consumedSeqById.get(input.id) ?? 0,\n    )\n  ) {\n    input.needingSync.delete(input.id);\n  }\n}\n"]}

package/stores/container-contents/syncAgent/syncAgentTypes.d.ts

@@ -0,0 +1,81 @@
+import type { ContainerContentsPersistence } from "../../../workflows/container-contents/containerPersistence.js";
+import type { ContainerContentsProjectionUserKeyResolver } from "../../../workflows/container-contents/projectionKeys.js";
+import type { ContainerState, RemoteContainer } from "../../../workflows/container-contents/remoteHydration/index.js";
+import type { ContainerContentsStoreWorkflowRuntime } from "../../../workflows/container-contents/runtime.js";
+import type { ContainerContentsSyncLane } from "../../../workflows/container-contents/syncLane.js";
+export type ContainerContentsStoreRuntime = ContainerContentsStoreWorkflowRuntime;
+export interface RefreshRootLaneOptions {
+    readonly includeActiveRootChildLane?: boolean | undefined;
+    readonly parentIds?: ReadonlyArray<string | null> | undefined;
+}
+export interface ContainerContentsStoreSyncAgent {
+    ensureInitialized: () => void;
+    handleRemoteEvents: () => void;
+    ingestRemoteContainer: (remoteContainer: RemoteContainer) => Promise<void>;
+    primeDocumentsForSharedSubtree: (rootContainerId: string, isCurrent?: (() => boolean) | undefined) => Promise<void>;
+    refreshLocalContainers: () => Promise<void>;
+    refresh: (options?: {
+        resetAllLaneWatermarks?: boolean;
+    }) => Promise<boolean>;
+    refreshRootLane: (options?: RefreshRootLaneOptions) => Promise<boolean>;
+    requestRemoteHydration: (options?: {
+        followDiscoveredParentLanes?: boolean | undefined;
+        parentIds?: ReadonlyArray<string | null> | undefined;
+        resetAllLaneWatermarks?: boolean | undefined;
+    }) => Promise<void>;
+    scheduleRemoteHydration: () => void;
+    scheduleSync: () => void;
+}
+export interface ContainerContentsStoreSyncState {
+    containersById: Map<string, ContainerState>;
+    documentStoresNeedPriming: boolean;
+    initializeGeneration: number | null;
+    initializePromise: Promise<void> | null;
+    initialized: boolean;
+    localContainerRefreshPromise: Promise<void> | null;
+    localContainerRefreshGeneration: number | null;
+    localContainerRefreshStructuralGeneration: number | null;
+    localContainersNeedRefresh: boolean;
+    /** Invalidates asynchronous hydration work when this store is reset. */
+    lifecycleGeneration: number;
+    /** Invalidates structural work when its runtime or persistence is replaced. */
+    structuralGeneration: number;
+    /** Invalidates writes across write-relevant runtime ABA transitions. */
+    writeGeneration: number;
+    lastEventCount: number;
+    /**
+     * Update ids this client sent for container metadata documents, registered
+     * before the network await of each metadata sync pass. The author's own
+     * `document_update_created` echo consumes its ids here instead of arming a
+     * redundant forced read-sync; a genuine peer update always carries unknown
+     * ids and still forces one. Shared across all metadata docs in the store —
+     * update ids are globally unique.
+     */
+    locallyAcceptedMetadataUpdateIds: Set<string>;
+    logLabel?: string | undefined;
+    metadataDocumentIdsNeedingSync: Set<string>;
+    /**
+     * Per-metadata-document enqueue sequence. Bumped for a specific id whenever a
+     * remote event re-queues it in {@link metadataDocumentIdsNeedingSync}. A sync
+     * pass snapshots the id's sequence before its GET and only clears the id if it
+     * is unchanged at pass end, so a mid-pass re-queue of THIS container is not
+     * erased. Keyed per id (not a single global counter) so a remote event for an
+     * unrelated container does not force a redundant re-sync of this one. See
+     * `clearMetadataSyncQueueIfUnchanged`.
+     */
+    metadataSyncSignalSeqById: Map<string, number>;
+    containerParentIdsNeedingHydration: Set<string | null>;
+    persistence: ContainerContentsPersistence;
+    remoteHydrationPromise: Promise<void> | null;
+    remoteHydrationGeneration: number | null;
+    remoteHydrationStructuralGeneration: number | null;
+    remoteReconnectRefreshPending: boolean;
+    resolveProjectionUserKey: ContainerContentsProjectionUserKeyResolver;
+    /** True after this store has fully applied an authoritative root lane. */
+    rootLaneHydrated: boolean;
+    runtime: ContainerContentsStoreRuntime;
+    snapshot: {
+        ready: boolean;
+    };
+    syncLane: ContainerContentsSyncLane | null;
+}

package/stores/container-contents/syncAgent/syncAgentTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncAgentTypes.js","sourceRoot":"","sources":["syncAgentTypes.ts"],"names":[],"mappings":"","sourcesContent":["import type { ContainerContentsPersistence } from \"../../../workflows/container-contents/containerPersistence\";\nimport type { ContainerContentsProjectionUserKeyResolver } from \"../../../workflows/container-contents/projectionKeys\";\nimport type {\n  ContainerState,\n  RemoteContainer,\n} from \"../../../workflows/container-contents/remoteHydration\";\nimport type { ContainerContentsStoreWorkflowRuntime } from \"../../../workflows/container-contents/runtime\";\nimport type { ContainerContentsSyncLane } from \"../../../workflows/container-contents/syncLane\";\n\nexport type ContainerContentsStoreRuntime =\n  ContainerContentsStoreWorkflowRuntime;\n\nexport interface RefreshRootLaneOptions {\n  readonly includeActiveRootChildLane?: boolean | undefined;\n  // Extra parent lanes to re-list alongside the root lane. Used by the\n  // resync_required handler to re-list affected containers' parent lanes so a\n  // tombstone only visible there is still applied without the full crawl.\n  readonly parentIds?: ReadonlyArray<string | null> | undefined;\n}\n\nexport interface ContainerContentsStoreSyncAgent {\n  ensureInitialized: () => void;\n  handleRemoteEvents: () => void;\n  ingestRemoteContainer: (remoteContainer: RemoteContainer) => Promise<void>;\n  primeDocumentsForSharedSubtree: (\n    rootContainerId: string,\n    isCurrent?: (() => boolean) | undefined,\n  ) => Promise<void>;\n  refreshLocalContainers: () => Promise<void>;\n  refresh: (options?: { resetAllLaneWatermarks?: boolean }) => Promise<boolean>;\n  refreshRootLane: (options?: RefreshRootLaneOptions) => Promise<boolean>;\n  requestRemoteHydration: (options?: {\n    followDiscoveredParentLanes?: boolean | undefined;\n    parentIds?: ReadonlyArray<string | null> | undefined;\n    resetAllLaneWatermarks?: boolean | undefined;\n  }) => Promise<void>;\n  scheduleRemoteHydration: () => void;\n  scheduleSync: () => void;\n}\n\nexport interface ContainerContentsStoreSyncState {\n  containersById: Map<string, ContainerState>;\n  documentStoresNeedPriming: boolean;\n  initializeGeneration: number | null;\n  initializePromise: Promise<void> | null;\n  initialized: boolean;\n  localContainerRefreshPromise: Promise<void> | null;\n  localContainerRefreshGeneration: number | null;\n  localContainerRefreshStructuralGeneration: number | null;\n  localContainersNeedRefresh: boolean;\n  /** Invalidates asynchronous hydration work when this store is reset. */\n  lifecycleGeneration: number;\n  /** Invalidates structural work when its runtime or persistence is replaced. */\n  structuralGeneration: number;\n  /** Invalidates writes across write-relevant runtime ABA transitions. */\n  writeGeneration: number;\n  lastEventCount: number;\n  /**\n   * Update ids this client sent for container metadata documents, registered\n   * before the network await of each metadata sync pass. The author's own\n   * `document_update_created` echo consumes its ids here instead of arming a\n   * redundant forced read-sync; a genuine peer update always carries unknown\n   * ids and still forces one. Shared across all metadata docs in the store —\n   * update ids are globally unique.\n   */\n  locallyAcceptedMetadataUpdateIds: Set<string>;\n  logLabel?: string | undefined;\n  metadataDocumentIdsNeedingSync: Set<string>;\n  /**\n   * Per-metadata-document enqueue sequence. Bumped for a specific id whenever a\n   * remote event re-queues it in {@link metadataDocumentIdsNeedingSync}. A sync\n   * pass snapshots the id's sequence before its GET and only clears the id if it\n   * is unchanged at pass end, so a mid-pass re-queue of THIS container is not\n   * erased. Keyed per id (not a single global counter) so a remote event for an\n   * unrelated container does not force a redundant re-sync of this one. See\n   * `clearMetadataSyncQueueIfUnchanged`.\n   */\n  metadataSyncSignalSeqById: Map<string, number>;\n  containerParentIdsNeedingHydration: Set<string | null>;\n  persistence: ContainerContentsPersistence;\n  remoteHydrationPromise: Promise<void> | null;\n  remoteHydrationGeneration: number | null;\n  remoteHydrationStructuralGeneration: number | null;\n  remoteReconnectRefreshPending: boolean;\n  resolveProjectionUserKey: ContainerContentsProjectionUserKeyResolver;\n  /** True after this store has fully applied an authoritative root lane. */\n  rootLaneHydrated: boolean;\n  runtime: ContainerContentsStoreRuntime;\n  snapshot: { ready: boolean };\n  syncLane: ContainerContentsSyncLane | null;\n}\n"]}

package/stores/container-contents/syncAgent/syncLaneIteration.js

@@ -0,0 +1,237 @@
+import { syncPendingContainerCreateIntents } from "../../../workflows/container-contents/container-state/create/createIntentSync.js";
+import { syncPendingContainerMoveIntents } from "../../../workflows/container-contents/container-state/moveIntentSync.js";
+import { syncPendingDocumentMoveIntents, } from "../../../workflows/container-contents/documentMove/documentMoveIntentSync.js";
+import { syncContainerMetadataState } from "../../../workflows/container-contents/metadata/index.js";
+import { createContainerContentsDocumentsRuntime } from "../../../workflows/container-contents/runtime.js";
+import { openDocumentStore, requestDomainDocumentSync } from "../../documents/index.js";
+import { relinkDocumentStoreWithCommitSideEffect } from "../../documents/documentStore/internalRelink.js";
+import { DocumentRemoteWorkBusyError } from "../../documents/documentStore/sync/remoteWork.js";
+import { removeMissingSyncedContainerState } from "../containerState/missingSyncedContainerState.js";
+import { runContainerDocumentWork } from "../documentWork/index.js";
+import { primeStoreDocuments, recoverStoreStaleRoot, } from "../documentWork/documentRecovery.js";
+import { bumpMetadataSyncSeq, clearMetadataSyncQueueIfUnchanged, readMetadataSyncSeq, } from "./metadataSyncSignal.js";
+function requestContainerContentsStoreSync(state) {
+    state.syncLane?.requestSync();
+}
+function createRemoteSyncBlocker(runtime) {
+    return (organizationId) => runtime.util.isRemoteSyncBlocked?.(organizationId) ?? false;
+}
+function captureStructuralSyncGeneration(state, runtime) {
+    const activeContainerId = runtime.state.containerId;
+    const activeOrganizationId = runtime.auth.organizationId;
+    const lifecycleGeneration = state.lifecycleGeneration;
+    const structuralGeneration = state.structuralGeneration;
+    const domainScope = runtime.state.domainScope;
+    const execSql = runtime.infra.execSql;
+    const resolveProjectionUserKey = state.resolveProjectionUserKey;
+    const syncLane = state.syncLane;
+    return () => state.lifecycleGeneration === lifecycleGeneration &&
+        state.structuralGeneration === structuralGeneration &&
+        state.runtime.auth.organizationId === activeOrganizationId &&
+        state.runtime.state.containerId === activeContainerId &&
+        state.runtime.state.domainScope === domainScope &&
+        state.runtime.infra.execSql === execSql &&
+        state.resolveProjectionUserKey === resolveProjectionUserKey &&
+        state.syncLane === syncLane &&
+        !syncLane?.isDisposed?.();
+}
+function createContainerContentsStoreDocumentMoveHost(state, isCurrent) {
+    const runtime = state.runtime;
+    const domainScope = runtime.state.domainScope;
+    return {
+        documentWorkflowRuntime: (containerId) => createContainerContentsDocumentsRuntime(runtime, containerId),
+        openDocumentStore: ({ containerId, documentId, localId }) => {
+            const store = openDocumentStore(domainScope, localId, createContainerContentsDocumentsRuntime(runtime, containerId), documentId);
+            return {
+                assertCanRotateContentKey: () => store.assertCanRotateContentKey().catch((error) => {
+                    if (error instanceof DocumentRemoteWorkBusyError) {
+                        void error.whenIdle.then(() => {
+                            if (isCurrent())
+                                requestContainerContentsStoreSync(state);
+                        });
+                    }
+                    throw error;
+                }),
+                ensureInitialized: () => store.ensureInitialized(),
+                relink: ({ commitSideEffect, ...input }) => commitSideEffect
+                    ? relinkDocumentStoreWithCommitSideEffect(store, input, commitSideEffect)
+                    : store.relink(input),
+                requestSync: () => store.requestSync(),
+                updateRuntime: (nextRuntime) => store.updateRuntime(nextRuntime),
+            };
+        },
+    };
+}
+function syncPendingStoreDocumentMoves(input) {
+    return syncPendingDocumentMoveIntents({
+        host: createContainerContentsStoreDocumentMoveHost(input.state, input.isCurrent),
+        isCreatePending: input.isCreatePending,
+        isCurrent: input.isCurrent,
+        isRemoteSyncBlocked: input.isRemoteSyncBlocked,
+        state: input.state,
+    });
+}
+async function syncSingleContainerMetadata(input) {
+    const { containerState, encapsulationKeyPair, host, isCurrent, state } = input;
+    const metadataDocumentId = containerState.record.documentId;
+    // Snapshot this signal before the GET so a mid-pass event survives clearing.
+    const consumedSeqById = new Map();
+    if (typeof metadataDocumentId === "string") {
+        consumedSeqById.set(metadataDocumentId, readMetadataSyncSeq(state.metadataSyncSignalSeqById, metadataDocumentId));
+    }
+    const synced = await (input.syncContainerMetadata ?? syncContainerMetadataState)({
+        forceReadSync: typeof metadataDocumentId === "string" &&
+            state.metadataDocumentIdsNeedingSync.has(metadataDocumentId),
+        locallyAcceptedUpdateIds: state.locallyAcceptedMetadataUpdateIds,
+        isCurrent,
+        metadataState: containerState,
+        onDurableStateNeedsReload: () => {
+            const currentDocumentId = state.containersById.get(containerState.container.id)?.record.documentId;
+            if (typeof currentDocumentId === "string") {
+                state.metadataDocumentIdsNeedingSync.add(currentDocumentId);
+                bumpMetadataSyncSeq(state.metadataSyncSignalSeqById, currentDocumentId);
+            }
+            requestContainerContentsStoreSync(state);
+        },
+        persistence: state.persistence,
+        resolveProjectionUserKey: state.resolveProjectionUserKey,
+        runtime: state.runtime,
+        targetSecretKey: encapsulationKeyPair.secretKey,
+    });
+    if (!isCurrent() || !synced) {
+        return;
+    }
+    if ("missing" in synced) {
+        removeMissingSyncedContainerState(state, containerState, host.updateSnapshot);
+        return;
+    }
+    for (const id of [metadataDocumentId, synced.record.documentId]) {
+        if (typeof id === "string") {
+            clearMetadataSyncQueueIfUnchanged({
+                consumedSeqById,
+                id,
+                needingSync: state.metadataDocumentIdsNeedingSync,
+                seqById: state.metadataSyncSignalSeqById,
+            });
+        }
+    }
+    // syncContainerMetadataState settles its detached candidate into this live
+    // object while preserving any metadata edit that completed or queued during
+    // the remote pass. Do not install its returned detached record again here:
+    // doing so would overwrite that preserved live edit.
+    host.updateSnapshot();
+    if (synced.shouldRequestFollowupSync) {
+        requestContainerContentsStoreSync(state);
+    }
+}
+/**
+ * A folder whose create has not settled can carry a listed identity that
+ * adoption has not verified, or has refused. Folder moves, document moves and
+ * metadata edits wait for it; child and document creates wait in their own
+ * create paths.
+ */
+async function loadPendingCreatePredicate(state) {
+    const pending = await state.persistence.listPendingCreateIntents(state.runtime.infra.execSql);
+    const pendingIds = new Set(pending.map((intent) => intent.containerId));
+    return (containerId) => pendingIds.has(containerId);
+}
+export async function runContainerContentsStoreSyncIteration(input) {
+    const { host, reconcileRestoredAccess, requestRemoteReconciliation, state } = input;
+    const runtime = state.runtime;
+    const encapsulationKeyPair = runtime.crypto.encapsulationKeyPair;
+    if (runtime.infra.dbStatus !== "ready" ||
+        !state.snapshot.ready ||
+        !runtime.state.online ||
+        !runtime.auth.isAuthenticated ||
+        !encapsulationKeyPair) {
+        return;
+    }
+    const domainScope = runtime.state.domainScope;
+    const isCurrent = captureStructuralSyncGeneration(state, runtime);
+    await reconcileRestoredAccess(isCurrent);
+    if (!isCurrent()) {
+        return;
+    }
+    const isOrganizationBlocked = createRemoteSyncBlocker(runtime);
+    const createdContainerCount = await syncPendingContainerCreateIntents({
+        host,
+        isCurrent,
+        isRemoteSyncBlocked: isOrganizationBlocked,
+        requestRemoteReconciliation,
+        state,
+    });
+    if (!isCurrent()) {
+        return;
+    }
+    if (createdContainerCount > 0) {
+        state.documentStoresNeedPriming = true;
+        host.updateSnapshot();
+    }
+    const isCreatePending = await loadPendingCreatePredicate(state);
+    if (!isCurrent()) {
+        return;
+    }
+    const movedContainerCount = await syncPendingContainerMoveIntents({
+        host,
+        isCreatePending,
+        isCurrent,
+        isRemoteSyncBlocked: isOrganizationBlocked,
+        requestRemoteReconciliation,
+        state,
+    });
+    if (!isCurrent()) {
+        return;
+    }
+    if (movedContainerCount > 0) {
+        state.documentStoresNeedPriming = true;
+        host.updateSnapshot();
+        requestDomainDocumentSync(domainScope);
+        requestContainerContentsStoreSync(state);
+    }
+    for (const containerState of Array.from(state.containersById.values())) {
+        if (isCreatePending(containerState.container.id))
+            continue;
+        await syncSingleContainerMetadata({
+            containerState,
+            encapsulationKeyPair,
+            host,
+            isCurrent,
+            state,
+            syncContainerMetadata: input.syncContainerMetadata,
+        });
+        if (!isCurrent()) {
+            return;
+        }
+    }
+    // Root adoption notifies session consumers synchronously. Let container
+    // metadata converge first so a recovered system container is never exposed
+    // under its placeholder name when the active root changes.
+    await runContainerDocumentWork({
+        isCurrent,
+        onContextChanged: () => {
+            if (isCurrent()) {
+                requestContainerContentsStoreSync(state);
+            }
+        },
+        onDocumentsMoved: () => {
+            if (isCurrent()) {
+                requestDomainDocumentSync(domainScope);
+                requestContainerContentsStoreSync(state);
+            }
+        },
+        primeDocuments: () => primeStoreDocuments(state, isCurrent),
+        recoverStaleRoot: () => recoverStoreStaleRoot(state, isCurrent),
+        shouldPrimeDocuments: () => state.documentStoresNeedPriming,
+        // Document move intents live in the structural phase because they may
+        // target containers created locally in the same session, such as Trash.
+        // Root recovery rewrites stale endpoints and returns their intents to
+        // pending, so replay follows recovery in this same pass.
+        syncPendingDocumentMoves: () => syncPendingStoreDocumentMoves({
+            isCreatePending,
+            isCurrent,
+            isRemoteSyncBlocked: isOrganizationBlocked,
+            state,
+        }),
+    });
+}
+//# sourceMappingURL=syncLaneIteration.js.map