@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/stores/container-contents/containerContentsStore.js

@@ -0,0 +1,190 @@
+import { getCachedContainerWriterProjection } from "../../workflows/container-contents/container-state/projectionCache.js";
+import { defaultContainerContentsPersistence, } from "../../workflows/container-contents/containerPersistence.js";
+import { persistContainerState } from "./containerStatePersistence.js";
+import { emptyTrash } from "./emptyTrashOperation.js";
+import { prepareContainerGroupRewrap, verifyContainerGroupRewrapCurrent, } from "./groupRewrapOperation.js";
+import { createChildContainer, deleteContainer, ensureSystemContainer, moveContainer, renameContainer, } from "./operations.js";
+import { purgeContainer } from "./purgeContainerOperation.js";
+import { invalidateRemoteContainerWrites } from "./remoteWriteGuards.js";
+import { chainRemoteContainerTask } from "./remoteWriteQueue.js";
+import { setContainerIcon } from "./setContainerIconOperation.js";
+import { shareContainerWithGroup, shareContainerWithUser, } from "./shareOperations.js";
+import { createContainerContentsStoreState, subscribeToContainerContentsStore, updateContainerContentsSnapshot, updateContainerContentsStorePersistence, updateContainerContentsStoreRuntime, } from "./state.js";
+import { createContainerContentsStoreSyncAgent, } from "./syncAgent.js";
+import { findRootContainerState } from "./systemContainerLookup.js";
+import { captureContainerWriteGeneration } from "./writeGeneration.js";
+const containerContentsStoresByScope = new WeakMap();
+function applyContainerContentsStoreOptions(state, syncAgent, options) {
+    if ("logLabel" in options) {
+        state.logLabel = options.logLabel;
+    }
+    if ("persistence" in options) {
+        updateContainerContentsStorePersistence(state, options.persistence ?? defaultContainerContentsPersistence, syncAgent);
+    }
+}
+function getCachedContainerWriterProjectionForStore(state, containerId) {
+    const containerState = state.containersById.get(containerId);
+    return containerState
+        ? getCachedContainerWriterProjection(containerState)
+        : null;
+}
+function createContainerContentsStoreSyncHost(state) {
+    return {
+        persistContainerState: (containerState, patch, updateView, saveOptions, mutationOptions) => persistContainerState(state, containerState, {
+            patch,
+            updateView,
+            saveOptions,
+            ...mutationOptions,
+        }),
+        requestDocumentPriming: () => {
+            state.documentStoresNeedPriming = true;
+        },
+        updateSnapshot: () => updateContainerContentsSnapshot(state),
+    };
+}
+// null marks an unknown mutation scope; [] delegates invalidation to actual writes.
+function chainContainerWrite(state, work, changedIds = null, movedId) {
+    const isCurrent = captureContainerWriteGeneration(state);
+    invalidateRemoteContainerWrites(state, changedIds, movedId);
+    state.writeChain = state.writeChain
+        .catch(() => null)
+        .then(() => {
+        if (!isCurrent())
+            return null;
+        invalidateRemoteContainerWrites(state, changedIds, movedId);
+        return work(isCurrent);
+    })
+        .then((node) => (isCurrent() ? node : null));
+    return state.writeChain;
+}
+// The group-rewrap builder verifies any required existing grant before capturing
+// the container KEK, then returns a check/rewrap pair. A verified non-match is
+// distinct from an unavailable preparation so security-critical callers can
+// no-op unrelated groups without failing open for a real grant.
+function createPrepareGroupRewrapMethod(state, syncAgent) {
+    return async (containerId, groupId, accessLevel, options) => {
+        const preparation = await chainRemoteContainerTask(state, syncAgent, null, (isCurrent) => prepareContainerGroupRewrap(state, containerId, groupId, accessLevel, options, isCurrent), containerId);
+        return preparation?.status === "prepared"
+            ? {
+                isCurrent: (expectedGroupHead, expectedContainerId, expectedOrganizationId) => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => verifyContainerGroupRewrapCurrent(state, containerId, groupId, accessLevel, expectedGroupHead, expectedContainerId, expectedOrganizationId, isCurrent), containerId),
+                rewrap: () => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => shareContainerWithGroup(state, syncAgent, containerId, groupId, accessLevel, {
+                    ...options,
+                    knownContainerKeks: preparation.knownContainerKeks,
+                    // A prepared re-wrap is grant-preserving by definition, so
+                    // it never mints a grant and never needs the chosen name.
+                    requireExistingGrant: true,
+                }, isCurrent), containerId, { preserveResultOnLocalWrite: true }),
+                status: "prepared",
+            }
+            : (preparation ?? null);
+    };
+}
+function createContainerSharingMethods(state, syncAgent) {
+    return {
+        shareWithUser: (containerId, userId) => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => shareContainerWithUser(state, syncAgent, containerId, userId, isCurrent), containerId, { preserveResultOnLocalWrite: true }),
+        shareWithGroup: (containerId, groupId, accessLevel, options) => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => shareContainerWithGroup(state, syncAgent, containerId, groupId, accessLevel, options, isCurrent), containerId, { preserveResultOnLocalWrite: true }),
+    };
+}
+function createDeleteContainerMethod(state, syncAgent) {
+    return (containerId) => {
+        const current = captureContainerWriteGeneration(state);
+        const remoteDelete = () => chainRemoteContainerTask(state, syncAgent, null, (isCurrent) => deleteContainer(state, syncAgent, containerId, isCurrent), containerId).then((node) => node !== null);
+        if (state.containersById.get(containerId)?.record.documentId)
+            return remoteDelete();
+        let promoted = false;
+        return chainContainerWrite(state, (isCurrent) => {
+            // Promotion can win while this local operation was queued. Hand it to
+            // the remote queue after releasing the local chain, before any HTTP I/O.
+            promoted = Boolean(state.containersById.get(containerId)?.record.documentId);
+            return promoted
+                ? Promise.resolve(null)
+                : deleteContainer(state, syncAgent, containerId, isCurrent);
+        }, [containerId]).then((node) => (promoted && current() ? remoteDelete() : node !== null));
+    };
+}
+function createEnsureSystemContainerMethod(state, syncAgent) {
+    return (systemSlot, name, options) => {
+        const work = (isCurrent) => ensureSystemContainer(state, syncAgent, systemSlot, name, options, isCurrent);
+        const rootId = findRootContainerState(state)?.container.id;
+        return options?.deferRemoteBootstrap
+            ? chainContainerWrite(state, work, [])
+            : chainRemoteContainerTask(state, syncAgent, null, work, rootId ? { rootId, systemSlot } : undefined);
+    };
+}
+export function createContainerWriteMethods(state, syncAgent) {
+    return {
+        ...createContainerSharingMethods(state, syncAgent),
+        createChild: (parentId, name) => chainContainerWrite(state, (isCurrent) => createChildContainer(state, syncAgent, parentId, name, isCurrent), [parentId]),
+        deleteContainer: createDeleteContainerMethod(state, syncAgent),
+        purgeContainer: (containerId, options) => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => purgeContainer(state, syncAgent, containerId, options, isCurrent), containerId),
+        emptyTrash: (trashContainerId, options) => chainRemoteContainerTask(state, syncAgent, false, (isCurrent) => emptyTrash(state, syncAgent, trashContainerId, options, isCurrent), trashContainerId),
+        ensureSystemContainer: createEnsureSystemContainerMethod(state, syncAgent),
+        moveContainer: (containerId, parentId) => chainContainerWrite(state, (isCurrent) => moveContainer(state, syncAgent, containerId, parentId, isCurrent), [containerId, parentId], containerId),
+        prepareGroupRewrap: createPrepareGroupRewrapMethod(state, syncAgent),
+        renameContainer: (containerId, name) => chainContainerWrite(state, (isCurrent) => renameContainer(state, syncAgent, containerId, name, isCurrent), [containerId]),
+        setContainerIcon: (containerId, icon) => chainContainerWrite(state, (isCurrent) => setContainerIcon(state, syncAgent, containerId, icon, isCurrent), [containerId]),
+    };
+}
+function createContainerContentsStoreEntry(initialRuntime, persistence = defaultContainerContentsPersistence, options = {}) {
+    const state = createContainerContentsStoreState(initialRuntime, options.persistence ?? persistence, options.logLabel);
+    const syncAgent = createContainerContentsStoreSyncAgent({
+        host: createContainerContentsStoreSyncHost(state),
+        state,
+    });
+    const writeMethods = createContainerWriteMethods(state, syncAgent);
+    return {
+        requestDocumentPriming: () => {
+            state.documentStoresNeedPriming = true;
+            syncAgent.scheduleSync();
+        },
+        store: {
+            ...writeMethods,
+            refresh: () => syncAgent.refresh({ resetAllLaneWatermarks: true }),
+            refreshRootLane: (options) => syncAgent.refreshRootLane(options),
+            // Force an on-demand local SQLite re-read (see the interface doc): arm the
+            // gate refreshLocalContainerStates otherwise requires, which the runtime
+            // auto-arms only on a context transition an on-demand caller cannot rely on.
+            refreshLocalContainers: () => {
+                state.localContainersNeedRefresh = true;
+                return syncAgent.refreshLocalContainers();
+            },
+            requestSync: () => syncAgent.scheduleSync(),
+            getCachedContainerWriterProjection: (containerId) => getCachedContainerWriterProjectionForStore(state, containerId),
+            getSnapshot: () => state.snapshot,
+            subscribe: (listener) => subscribeToContainerContentsStore(state, listener),
+            updateRuntime: (runtime) => updateContainerContentsStoreRuntime(state, runtime, syncAgent),
+        },
+        updateOptions: (nextOptions) => applyContainerContentsStoreOptions(state, syncAgent, nextOptions),
+    };
+}
+export function createContainerContentsStore(initialRuntime, persistence = defaultContainerContentsPersistence, options = {}) {
+    return createContainerContentsStoreEntry(initialRuntime, persistence, options)
+        .store;
+}
+export function getOrCreateContainerContentsStore(domainScope, runtime, options = {}) {
+    const existingEntry = containerContentsStoresByScope.get(domainScope);
+    if (existingEntry) {
+        existingEntry.updateOptions(options);
+        return existingEntry.store;
+    }
+    const nextEntry = createContainerContentsStoreEntry(runtime, defaultContainerContentsPersistence, options);
+    containerContentsStoresByScope.set(domainScope, nextEntry);
+    return nextEntry.store;
+}
+/**
+ * Arm the next structural pass's document-priming scan for a domain scope.
+ * Priming normally re-arms only on store creation and topology changes, so a
+ * caller that just tore down a document's local state uses this to have the
+ * still-listed server document re-created without waiting for an app
+ * restart. Returns false when the scope has no container-contents store yet;
+ * the startup priming pass covers that case.
+ */
+export function requestContainerContentsDocumentPriming(domainScope) {
+    const entry = containerContentsStoresByScope.get(domainScope);
+    if (!entry) {
+        return false;
+    }
+    entry.requestDocumentPriming();
+    return true;
+}
+//# sourceMappingURL=containerContentsStore.js.map

package/stores/container-contents/containerContentsStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerContentsStore.js","sourceRoot":"","sources":["containerContentsStore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DomainScope } from \"../../data/domainScope\";\nimport { getCachedContainerWriterProjection } from \"../../workflows/container-contents/container-state/projectionCache\";\nimport {\n  type ContainerContentsPersistence,\n  defaultContainerContentsPersistence,\n} from \"../../workflows/container-contents/containerPersistence\";\nimport { persistContainerState } from \"./containerStatePersistence\";\nimport { emptyTrash } from \"./emptyTrashOperation\";\nimport {\n  prepareContainerGroupRewrap,\n  verifyContainerGroupRewrapCurrent,\n} from \"./groupRewrapOperation\";\nimport {\n  createChildContainer,\n  deleteContainer,\n  ensureSystemContainer,\n  moveContainer,\n  renameContainer,\n} from \"./operations\";\nimport { purgeContainer } from \"./purgeContainerOperation\";\nimport { invalidateRemoteContainerWrites } from \"./remoteWriteGuards\";\nimport { chainRemoteContainerTask } from \"./remoteWriteQueue\";\nimport { setContainerIcon } from \"./setContainerIconOperation\";\nimport {\n  shareContainerWithGroup,\n  shareContainerWithUser,\n} from \"./shareOperations\";\nimport {\n  createContainerContentsStoreState,\n  subscribeToContainerContentsStore,\n  updateContainerContentsSnapshot,\n  updateContainerContentsStorePersistence,\n  updateContainerContentsStoreRuntime,\n} from \"./state\";\nimport {\n  type ContainerContentsStoreRuntime,\n  type ContainerContentsStoreSyncAgent,\n  createContainerContentsStoreSyncAgent,\n} from \"./syncAgent\";\nimport { findRootContainerState } from \"./systemContainerLookup\";\nimport type {\n  ContainerContentsStore,\n  ContainerContentsStoreOptions,\n  ContainerContentsStoreState,\n} from \"./types\";\nimport { captureContainerWriteGeneration } from \"./writeGeneration\";\n\nconst containerContentsStoresByScope = new WeakMap<\n  DomainScope,\n  ContainerContentsStoreEntry\n>();\n\ninterface ContainerContentsStoreEntry {\n  requestDocumentPriming: () => void;\n  store: ContainerContentsStore;\n  updateOptions: (options: ContainerContentsStoreOptions) => void;\n}\n\nfunction applyContainerContentsStoreOptions(\n  state: ContainerContentsStoreState,\n  syncAgent: ContainerContentsStoreSyncAgent,\n  options: ContainerContentsStoreOptions,\n): void {\n  if (\"logLabel\" in options) {\n    state.logLabel = options.logLabel;\n  }\n\n  if (\"persistence\" in options) {\n    updateContainerContentsStorePersistence(\n      state,\n      options.persistence ?? defaultContainerContentsPersistence,\n      syncAgent,\n    );\n  }\n}\n\nfunction getCachedContainerWriterProjectionForStore(\n  state: ContainerContentsStoreState,\n  containerId: string,\n) {\n  const containerState = state.containersById.get(containerId);\n  return containerState\n    ? getCachedContainerWriterProjection(containerState)\n    : null;\n}\n\nfunction createContainerContentsStoreSyncHost(\n  state: ContainerContentsStoreState,\n): Parameters<typeof createContainerContentsStoreSyncAgent>[0][\"host\"] {\n  return {\n    persistContainerState: (\n      containerState,\n      patch,\n      updateView,\n      saveOptions,\n      mutationOptions,\n    ) =>\n      persistContainerState(state, containerState, {\n        patch,\n        updateView,\n        saveOptions,\n        ...mutationOptions,\n      }),\n    requestDocumentPriming: () => {\n      state.documentStoresNeedPriming = true;\n    },\n    updateSnapshot: () => updateContainerContentsSnapshot(state),\n  };\n}\n\n// null marks an unknown mutation scope; [] delegates invalidation to actual writes.\nfunction chainContainerWrite(\n  state: ContainerContentsStoreState,\n  work: (isCurrent: () => boolean) => ContainerContentsStoreState[\"writeChain\"],\n  changedIds: readonly string[] | null = null,\n  movedId?: string,\n): ContainerContentsStoreState[\"writeChain\"] {\n  const isCurrent = captureContainerWriteGeneration(state);\n  invalidateRemoteContainerWrites(state, changedIds, movedId);\n  state.writeChain = state.writeChain\n    .catch(() => null)\n    .then(() => {\n      if (!isCurrent()) return null;\n      invalidateRemoteContainerWrites(state, changedIds, movedId);\n      return work(isCurrent);\n    })\n    .then((node) => (isCurrent() ? node : null));\n  return state.writeChain;\n}\n\ntype ContainerWriteMethods = Pick<\n  ContainerContentsStore,\n  | \"createChild\"\n  | \"deleteContainer\"\n  | \"emptyTrash\"\n  | \"ensureSystemContainer\"\n  | \"moveContainer\"\n  | \"prepareGroupRewrap\"\n  | \"purgeContainer\"\n  | \"renameContainer\"\n  | \"setContainerIcon\"\n  | \"shareWithGroup\"\n  | \"shareWithUser\"\n>;\n\n// The group-rewrap builder verifies any required existing grant before capturing\n// the container KEK, then returns a check/rewrap pair. A verified non-match is\n// distinct from an unavailable preparation so security-critical callers can\n// no-op unrelated groups without failing open for a real grant.\nfunction createPrepareGroupRewrapMethod(\n  state: ContainerContentsStoreState,\n  syncAgent: ReturnType<typeof createContainerContentsStoreSyncAgent>,\n): ContainerContentsStore[\"prepareGroupRewrap\"] {\n  return async (containerId, groupId, accessLevel, options) => {\n    const preparation = await chainRemoteContainerTask(\n      state,\n      syncAgent,\n      null,\n      (isCurrent) =>\n        prepareContainerGroupRewrap(\n          state,\n          containerId,\n          groupId,\n          accessLevel,\n          options,\n          isCurrent,\n        ),\n      containerId,\n    );\n    return preparation?.status === \"prepared\"\n      ? {\n          isCurrent: (\n            expectedGroupHead,\n            expectedContainerId,\n            expectedOrganizationId,\n          ) =>\n            chainRemoteContainerTask(\n              state,\n              syncAgent,\n              false,\n              (isCurrent) =>\n                verifyContainerGroupRewrapCurrent(\n                  state,\n                  containerId,\n                  groupId,\n                  accessLevel,\n                  expectedGroupHead,\n                  expectedContainerId,\n                  expectedOrganizationId,\n                  isCurrent,\n                ),\n              containerId,\n            ),\n          rewrap: () =>\n            chainRemoteContainerTask(\n              state,\n              syncAgent,\n              false,\n              (isCurrent) =>\n                shareContainerWithGroup(\n                  state,\n                  syncAgent,\n                  containerId,\n                  groupId,\n                  accessLevel,\n                  {\n                    ...options,\n                    knownContainerKeks: preparation.knownContainerKeks,\n                    // A prepared re-wrap is grant-preserving by definition, so\n                    // it never mints a grant and never needs the chosen name.\n                    requireExistingGrant: true,\n                  },\n                  isCurrent,\n                ),\n              containerId,\n              { preserveResultOnLocalWrite: true },\n            ),\n          status: \"prepared\" as const,\n        }\n      : (preparation ?? null);\n  };\n}\n\nfunction createContainerSharingMethods(\n  state: ContainerContentsStoreState,\n  syncAgent: ContainerContentsStoreSyncAgent,\n): Pick<ContainerWriteMethods, \"shareWithUser\" | \"shareWithGroup\"> {\n  return {\n    shareWithUser: (containerId, userId) =>\n      chainRemoteContainerTask(\n        state,\n        syncAgent,\n        false,\n        (isCurrent) =>\n          shareContainerWithUser(\n            state,\n            syncAgent,\n            containerId,\n            userId,\n            isCurrent,\n          ),\n        containerId,\n        { preserveResultOnLocalWrite: true },\n      ),\n    shareWithGroup: (containerId, groupId, accessLevel, options) =>\n      chainRemoteContainerTask(\n        state,\n        syncAgent,\n        false,\n        (isCurrent) =>\n          shareContainerWithGroup(\n            state,\n            syncAgent,\n            containerId,\n            groupId,\n            accessLevel,\n            options,\n            isCurrent,\n          ),\n        containerId,\n        { preserveResultOnLocalWrite: true },\n      ),\n  };\n}\n\nfunction createDeleteContainerMethod(\n  state: ContainerContentsStoreState,\n  syncAgent: ContainerContentsStoreSyncAgent,\n): ContainerContentsStore[\"deleteContainer\"] {\n  return (containerId) => {\n    const current = captureContainerWriteGeneration(state);\n    const remoteDelete = () =>\n      chainRemoteContainerTask(\n        state,\n        syncAgent,\n        null,\n        (isCurrent) =>\n          deleteContainer(state, syncAgent, containerId, isCurrent),\n        containerId,\n      ).then((node) => node !== null);\n    if (state.containersById.get(containerId)?.record.documentId)\n      return remoteDelete();\n    let promoted = false;\n    return chainContainerWrite(\n      state,\n      (isCurrent) => {\n        // Promotion can win while this local operation was queued. Hand it to\n        // the remote queue after releasing the local chain, before any HTTP I/O.\n        promoted = Boolean(\n          state.containersById.get(containerId)?.record.documentId,\n        );\n        return promoted\n          ? Promise.resolve(null)\n          : deleteContainer(state, syncAgent, containerId, isCurrent);\n      },\n      [containerId],\n    ).then((node) => (promoted && current() ? remoteDelete() : node !== null));\n  };\n}\n\nfunction createEnsureSystemContainerMethod(\n  state: ContainerContentsStoreState,\n  syncAgent: ContainerContentsStoreSyncAgent,\n): ContainerContentsStore[\"ensureSystemContainer\"] {\n  return (systemSlot, name, options) => {\n    const work = (isCurrent: () => boolean) =>\n      ensureSystemContainer(\n        state,\n        syncAgent,\n        systemSlot,\n        name,\n        options,\n        isCurrent,\n      );\n    const rootId = findRootContainerState(state)?.container.id;\n    return options?.deferRemoteBootstrap\n      ? chainContainerWrite(state, work, [])\n      : chainRemoteContainerTask(\n          state,\n          syncAgent,\n          null,\n          work,\n          rootId ? { rootId, systemSlot } : undefined,\n        );\n  };\n}\n\nexport function createContainerWriteMethods(\n  state: ContainerContentsStoreState,\n  syncAgent: ReturnType<typeof createContainerContentsStoreSyncAgent>,\n): ContainerWriteMethods {\n  return {\n    ...createContainerSharingMethods(state, syncAgent),\n    createChild: (parentId, name) =>\n      chainContainerWrite(\n        state,\n        (isCurrent) =>\n          createChildContainer(state, syncAgent, parentId, name, isCurrent),\n        [parentId],\n      ),\n    deleteContainer: createDeleteContainerMethod(state, syncAgent),\n    purgeContainer: (containerId, options) =>\n      chainRemoteContainerTask(\n        state,\n        syncAgent,\n        false,\n        (isCurrent) =>\n          purgeContainer(state, syncAgent, containerId, options, isCurrent),\n        containerId,\n      ),\n    emptyTrash: (trashContainerId, options) =>\n      chainRemoteContainerTask(\n        state,\n        syncAgent,\n        false,\n        (isCurrent) =>\n          emptyTrash(state, syncAgent, trashContainerId, options, isCurrent),\n        trashContainerId,\n      ),\n    ensureSystemContainer: createEnsureSystemContainerMethod(state, syncAgent),\n    moveContainer: (containerId, parentId) =>\n      chainContainerWrite(\n        state,\n        (isCurrent) =>\n          moveContainer(state, syncAgent, containerId, parentId, isCurrent),\n        [containerId, parentId],\n        containerId,\n      ),\n    prepareGroupRewrap: createPrepareGroupRewrapMethod(state, syncAgent),\n    renameContainer: (containerId, name) =>\n      chainContainerWrite(\n        state,\n        (isCurrent) =>\n          renameContainer(state, syncAgent, containerId, name, isCurrent),\n        [containerId],\n      ),\n    setContainerIcon: (containerId, icon) =>\n      chainContainerWrite(\n        state,\n        (isCurrent) =>\n          setContainerIcon(state, syncAgent, containerId, icon, isCurrent),\n        [containerId],\n      ),\n  };\n}\n\nfunction createContainerContentsStoreEntry(\n  initialRuntime: ContainerContentsStoreRuntime,\n  persistence: ContainerContentsPersistence = defaultContainerContentsPersistence,\n  options: ContainerContentsStoreOptions = {},\n): ContainerContentsStoreEntry {\n  const state = createContainerContentsStoreState(\n    initialRuntime,\n    options.persistence ?? persistence,\n    options.logLabel,\n  );\n  const syncAgent = createContainerContentsStoreSyncAgent({\n    host: createContainerContentsStoreSyncHost(state),\n    state,\n  });\n  const writeMethods = createContainerWriteMethods(state, syncAgent);\n\n  return {\n    requestDocumentPriming: () => {\n      state.documentStoresNeedPriming = true;\n      syncAgent.scheduleSync();\n    },\n    store: {\n      ...writeMethods,\n      refresh: () => syncAgent.refresh({ resetAllLaneWatermarks: true }),\n      refreshRootLane: (options) => syncAgent.refreshRootLane(options),\n      // Force an on-demand local SQLite re-read (see the interface doc): arm the\n      // gate refreshLocalContainerStates otherwise requires, which the runtime\n      // auto-arms only on a context transition an on-demand caller cannot rely on.\n      refreshLocalContainers: () => {\n        state.localContainersNeedRefresh = true;\n        return syncAgent.refreshLocalContainers();\n      },\n      requestSync: () => syncAgent.scheduleSync(),\n      getCachedContainerWriterProjection: (containerId) =>\n        getCachedContainerWriterProjectionForStore(state, containerId),\n      getSnapshot: () => state.snapshot,\n      subscribe: (listener) =>\n        subscribeToContainerContentsStore(state, listener),\n      updateRuntime: (runtime) =>\n        updateContainerContentsStoreRuntime(state, runtime, syncAgent),\n    },\n    updateOptions: (nextOptions) =>\n      applyContainerContentsStoreOptions(state, syncAgent, nextOptions),\n  };\n}\n\nexport function createContainerContentsStore(\n  initialRuntime: ContainerContentsStoreRuntime,\n  persistence: ContainerContentsPersistence = defaultContainerContentsPersistence,\n  options: ContainerContentsStoreOptions = {},\n): ContainerContentsStore {\n  return createContainerContentsStoreEntry(initialRuntime, persistence, options)\n    .store;\n}\n\nexport function getOrCreateContainerContentsStore(\n  domainScope: DomainScope,\n  runtime: ContainerContentsStoreRuntime,\n  options: ContainerContentsStoreOptions = {},\n): ContainerContentsStore {\n  const existingEntry = containerContentsStoresByScope.get(domainScope);\n  if (existingEntry) {\n    existingEntry.updateOptions(options);\n    return existingEntry.store;\n  }\n\n  const nextEntry = createContainerContentsStoreEntry(\n    runtime,\n    defaultContainerContentsPersistence,\n    options,\n  );\n  containerContentsStoresByScope.set(domainScope, nextEntry);\n  return nextEntry.store;\n}\n\n/**\n * Arm the next structural pass's document-priming scan for a domain scope.\n * Priming normally re-arms only on store creation and topology changes, so a\n * caller that just tore down a document's local state uses this to have the\n * still-listed server document re-created without waiting for an app\n * restart. Returns false when the scope has no container-contents store yet;\n * the startup priming pass covers that case.\n */\nexport function requestContainerContentsDocumentPriming(\n  domainScope: DomainScope,\n): boolean {\n  const entry = containerContentsStoresByScope.get(domainScope);\n  if (!entry) {\n    return false;\n  }\n\n  entry.requestDocumentPriming();\n  return true;\n}\n"]}

package/stores/container-contents/containerPurgeCore.js

@@ -0,0 +1,98 @@
+import { purgeContainerTree } from "../../workflows/container-contents/container-state/purgeTree.js";
+import { prepareContainerDocumentRotationSnapshot } from "./documentRotation.js";
+import { getContainerContentsStoreLogLabel } from "./logLabel.js";
+import { updateContainerContentsSnapshot } from "./state.js";
+/** @internal Reconciles any completed destructive prefix after expiry. */
+export async function refreshAfterStalePurge(input) {
+    const remoteParentIds = new Set();
+    for (const remoteDeletedContainerId of input.remoteDeletedContainerIds) {
+        const purgedState = input.containerStatesAtStart.get(remoteDeletedContainerId);
+        if (purgedState?.record.documentId) {
+            remoteParentIds.add(purgedState.container.parentId);
+        }
+    }
+    input.state.localContainersNeedRefresh = true;
+    await input.syncAgent.refreshLocalContainers();
+    let removedState = false;
+    for (const purgedContainerId of input.purgedContainerIds) {
+        const deletedState = input.containerStatesAtStart.get(purgedContainerId);
+        if (deletedState &&
+            input.state.containersById.get(purgedContainerId) === deletedState) {
+            input.state.containersById.delete(purgedContainerId);
+            removedState = true;
+        }
+    }
+    input.state.documentStoresNeedPriming = true;
+    if (removedState && input.state.initialized) {
+        updateContainerContentsSnapshot(input.state);
+    }
+    if (remoteParentIds.size > 0) {
+        await input.syncAgent.requestRemoteHydration({
+            followDiscoveredParentLanes: false,
+            parentIds: [...remoteParentIds],
+            resetAllLaneWatermarks: true,
+        });
+    }
+}
+// Shared core of the two recursive purge operations (purgeContainer and
+// emptyTrash): guard readiness and the remote-authority gate, run the
+// recursive purge engine, drop the purged containers from the tree, and log
+// the outcome. The operations differ only in target validation, whether the
+// root container itself survives, and how the result is described/judged.
+export async function runContainerPurge(state, syncAgent, containerId, options, isCurrent, operation) {
+    if (state.runtime.infra.dbStatus !== "ready" || !state.snapshot.ready) {
+        return false;
+    }
+    const targetState = state.containersById.get(containerId);
+    if (!targetState || !operation.validateTarget(targetState)) {
+        return false;
+    }
+    // Any remote container or document in the subtree needs the server, so require
+    // auth + online when the target itself is remote (a local-only subtree can be
+    // torn down offline, matching deleteContainer's gate).
+    const isRemoteContainer = Boolean(targetState.record.documentId);
+    if (isRemoteContainer &&
+        (!state.runtime.auth.isAuthenticated || !state.runtime.state.online)) {
+        return false;
+    }
+    const containerStatesAtStart = new Map(state.containersById);
+    const result = await purgeContainerTree({
+        containersById: state.containersById,
+        keepRootContainer: operation.keepRootContainer ?? false,
+        onProgress: options?.onProgress,
+        persistence: state.persistence,
+        prepareDocumentRotationSnapshot: (document) => prepareContainerDocumentRotationSnapshot(state.runtime, document),
+        resolveProjectionUserKey: state.resolveProjectionUserKey,
+        rootContainerId: containerId,
+        runtime: state.runtime,
+        signal: options?.signal,
+        stillCurrent: isCurrent,
+    });
+    if (!result) {
+        return false;
+    }
+    const purgedContainerIds = new Set(result.purgedContainerIds);
+    const hasUnsettledRemoteDelete = result.remoteDeletedContainerIds.some((containerId) => !purgedContainerIds.has(containerId));
+    if (!isCurrent() || hasUnsettledRemoteDelete) {
+        await refreshAfterStalePurge({
+            completedCount: result.completedCount,
+            containerStatesAtStart,
+            purgedContainerIds: result.purgedContainerIds,
+            remoteDeletedContainerIds: result.remoteDeletedContainerIds,
+            state,
+            syncAgent,
+        });
+        return false;
+    }
+    for (const purgedContainerId of result.purgedContainerIds) {
+        state.containersById.delete(purgedContainerId);
+    }
+    // Only re-render when something actually left the tree; a fully-failed or
+    // immediately-cancelled run changed nothing.
+    if (result.purgedContainerIds.length > 0) {
+        updateContainerContentsSnapshot(state);
+    }
+    state.runtime.util.log(`${getContainerContentsStoreLogLabel(state)}: ${operation.describeResult(targetState, result)}`);
+    return operation.didSucceed(result);
+}
+//# sourceMappingURL=containerPurgeCore.js.map

package/stores/container-contents/containerPurgeCore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerPurgeCore.js","sourceRoot":"","sources":["containerPurgeCore.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PurgeOptions } from \"../../workflows/container-contents/container-state/purgeProgress\";\nimport { purgeContainerTree } from \"../../workflows/container-contents/container-state/purgeTree\";\nimport { prepareContainerDocumentRotationSnapshot } from \"./documentRotation\";\nimport { getContainerContentsStoreLogLabel } from \"./logLabel\";\nimport { updateContainerContentsSnapshot } from \"./state\";\nimport type {\n  ContainerContentsStoreSyncAgent,\n  ContainerState,\n} from \"./syncAgent\";\nimport type { ContainerContentsStoreState } from \"./types\";\nimport type { ContainerWriteGuard } from \"./writeGeneration\";\n\ntype ContainerPurgeResult = NonNullable<\n  Awaited<ReturnType<typeof purgeContainerTree>>\n>;\n\n/** @internal Reconciles any completed destructive prefix after expiry. */\nexport async function refreshAfterStalePurge(input: {\n  completedCount: number;\n  containerStatesAtStart: ReadonlyMap<string, ContainerState>;\n  purgedContainerIds: readonly string[];\n  remoteDeletedContainerIds: readonly string[];\n  state: ContainerContentsStoreState;\n  syncAgent: ContainerContentsStoreSyncAgent;\n}): Promise<void> {\n  const remoteParentIds = new Set<string | null>();\n  for (const remoteDeletedContainerId of input.remoteDeletedContainerIds) {\n    const purgedState = input.containerStatesAtStart.get(\n      remoteDeletedContainerId,\n    );\n    if (purgedState?.record.documentId) {\n      remoteParentIds.add(purgedState.container.parentId);\n    }\n  }\n\n  input.state.localContainersNeedRefresh = true;\n  await input.syncAgent.refreshLocalContainers();\n  let removedState = false;\n  for (const purgedContainerId of input.purgedContainerIds) {\n    const deletedState = input.containerStatesAtStart.get(purgedContainerId);\n    if (\n      deletedState &&\n      input.state.containersById.get(purgedContainerId) === deletedState\n    ) {\n      input.state.containersById.delete(purgedContainerId);\n      removedState = true;\n    }\n  }\n  input.state.documentStoresNeedPriming = true;\n  if (removedState && input.state.initialized) {\n    updateContainerContentsSnapshot(input.state);\n  }\n  if (remoteParentIds.size > 0) {\n    await input.syncAgent.requestRemoteHydration({\n      followDiscoveredParentLanes: false,\n      parentIds: [...remoteParentIds],\n      resetAllLaneWatermarks: true,\n    });\n  }\n}\n\n// Shared core of the two recursive purge operations (purgeContainer and\n// emptyTrash): guard readiness and the remote-authority gate, run the\n// recursive purge engine, drop the purged containers from the tree, and log\n// the outcome. The operations differ only in target validation, whether the\n// root container itself survives, and how the result is described/judged.\nexport async function runContainerPurge(\n  state: ContainerContentsStoreState,\n  syncAgent: ContainerContentsStoreSyncAgent,\n  containerId: string,\n  options: PurgeOptions | undefined,\n  isCurrent: ContainerWriteGuard,\n  operation: {\n    describeResult: (\n      target: ContainerState,\n      result: ContainerPurgeResult,\n    ) => string;\n    didSucceed: (result: ContainerPurgeResult) => boolean;\n    keepRootContainer?: boolean | undefined;\n    validateTarget: (target: ContainerState) => boolean;\n  },\n): Promise<boolean> {\n  if (state.runtime.infra.dbStatus !== \"ready\" || !state.snapshot.ready) {\n    return false;\n  }\n\n  const targetState = state.containersById.get(containerId);\n  if (!targetState || !operation.validateTarget(targetState)) {\n    return false;\n  }\n\n  // Any remote container or document in the subtree needs the server, so require\n  // auth + online when the target itself is remote (a local-only subtree can be\n  // torn down offline, matching deleteContainer's gate).\n  const isRemoteContainer = Boolean(targetState.record.documentId);\n  if (\n    isRemoteContainer &&\n    (!state.runtime.auth.isAuthenticated || !state.runtime.state.online)\n  ) {\n    return false;\n  }\n  const containerStatesAtStart = new Map(state.containersById);\n\n  const result = await purgeContainerTree({\n    containersById: state.containersById,\n    keepRootContainer: operation.keepRootContainer ?? false,\n    onProgress: options?.onProgress,\n    persistence: state.persistence,\n    prepareDocumentRotationSnapshot: (document) =>\n      prepareContainerDocumentRotationSnapshot(state.runtime, document),\n    resolveProjectionUserKey: state.resolveProjectionUserKey,\n    rootContainerId: containerId,\n    runtime: state.runtime,\n    signal: options?.signal,\n    stillCurrent: isCurrent,\n  });\n  if (!result) {\n    return false;\n  }\n  const purgedContainerIds = new Set(result.purgedContainerIds);\n  const hasUnsettledRemoteDelete = result.remoteDeletedContainerIds.some(\n    (containerId) => !purgedContainerIds.has(containerId),\n  );\n  if (!isCurrent() || hasUnsettledRemoteDelete) {\n    await refreshAfterStalePurge({\n      completedCount: result.completedCount,\n      containerStatesAtStart,\n      purgedContainerIds: result.purgedContainerIds,\n      remoteDeletedContainerIds: result.remoteDeletedContainerIds,\n      state,\n      syncAgent,\n    });\n    return false;\n  }\n\n  for (const purgedContainerId of result.purgedContainerIds) {\n    state.containersById.delete(purgedContainerId);\n  }\n  // Only re-render when something actually left the tree; a fully-failed or\n  // immediately-cancelled run changed nothing.\n  if (result.purgedContainerIds.length > 0) {\n    updateContainerContentsSnapshot(state);\n  }\n  state.runtime.util.log(\n    `${getContainerContentsStoreLogLabel(state)}: ${operation.describeResult(targetState, result)}`,\n  );\n  return operation.didSucceed(result);\n}\n"]}

package/stores/container-contents/containerStateMap.js

@@ -0,0 +1,49 @@
+export class ContainerStateMap extends Map {
+    #mutationGenerationById = new Map();
+    #nextMutationGeneration = 0;
+    constructor(entries) {
+        super();
+        for (const [containerId, state] of entries ?? []) {
+            super.set(containerId, state);
+        }
+    }
+    clear() {
+        for (const containerId of this.keys()) {
+            this.recordMutation(containerId);
+        }
+        super.clear();
+    }
+    delete(containerId) {
+        const deleted = super.delete(containerId);
+        // An absent delete is still an authoritative tombstone observation. A
+        // local-refresh query that started before it must not install a stale row
+        // merely because no in-memory value existed for Map.delete to remove.
+        this.recordMutation(containerId);
+        return deleted;
+    }
+    set(containerId, state) {
+        this.recordMutation(containerId);
+        return super.set(containerId, state);
+    }
+    captureMutationGenerations() {
+        return new Map(this.#mutationGenerationById);
+    }
+    hasMutationAfter(containerId, baseline) {
+        return ((this.#mutationGenerationById.get(containerId) ?? 0) !==
+            (baseline.get(containerId) ?? 0));
+    }
+    recordMutation(containerId) {
+        this.#nextMutationGeneration += 1;
+        this.#mutationGenerationById.set(containerId, this.#nextMutationGeneration);
+    }
+}
+export function captureContainerStateMutationGenerations(states) {
+    return states instanceof ContainerStateMap
+        ? states.captureMutationGenerations()
+        : new Map();
+}
+export function containerStateMutatedAfter(states, containerId, baseline) {
+    return (states instanceof ContainerStateMap &&
+        states.hasMutationAfter(containerId, baseline));
+}
+//# sourceMappingURL=containerStateMap.js.map

package/stores/container-contents/containerStateMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerStateMap.js","sourceRoot":"","sources":["containerStateMap.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,iBAAkB,SAAQ,GAA2B;IACvD,uBAAuB,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7D,uBAAuB,GAAG,CAAC,CAAC;IAE5B,YAAY,OAA6C;QACvD,KAAK,EAAE,CAAC;QACR,KAAK,MAAM,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;YACjD,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAEQ,KAAK;QACZ,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACnC,CAAC;QACD,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAEQ,MAAM,CAAC,WAAmB;QACjC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC1C,sEAAsE;QACtE,0EAA0E;QAC1E,sEAAsE;QACtE,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACjC,OAAO,OAAO,CAAC;IACjB,CAAC;IAEQ,GAAG,CAAC,WAAmB,EAAE,KAAqB;QACrD,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,0BAA0B;QACxB,OAAO,IAAI,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC/C,CAAC;IAED,gBAAgB,CACd,WAAmB,EACnB,QAAqC;QAErC,OAAO,CACL,CAAC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;YACpD,CAAC,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CACjC,CAAC;IACJ,CAAC;IAEO,cAAc,CAAC,WAAmB;QACxC,IAAI,CAAC,uBAAuB,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAC9E,CAAC;CACF;AAED,MAAM,UAAU,wCAAwC,CACtD,MAAmC;IAEnC,OAAO,MAAM,YAAY,iBAAiB;QACxC,CAAC,CAAC,MAAM,CAAC,0BAA0B,EAAE;QACrC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,MAAmC,EACnC,WAAmB,EACnB,QAAqC;IAErC,OAAO,CACL,MAAM,YAAY,iBAAiB;QACnC,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAC/C,CAAC;AACJ,CAAC","sourcesContent":["import type { ContainerState } from \"../../workflows/container-contents/remoteHydration\";\n\nexport class ContainerStateMap extends Map<string, ContainerState> {\n  readonly #mutationGenerationById = new Map<string, number>();\n  #nextMutationGeneration = 0;\n\n  constructor(entries?: ReadonlyMap<string, ContainerState>) {\n    super();\n    for (const [containerId, state] of entries ?? []) {\n      super.set(containerId, state);\n    }\n  }\n\n  override clear(): void {\n    for (const containerId of this.keys()) {\n      this.recordMutation(containerId);\n    }\n    super.clear();\n  }\n\n  override delete(containerId: string): boolean {\n    const deleted = super.delete(containerId);\n    // An absent delete is still an authoritative tombstone observation. A\n    // local-refresh query that started before it must not install a stale row\n    // merely because no in-memory value existed for Map.delete to remove.\n    this.recordMutation(containerId);\n    return deleted;\n  }\n\n  override set(containerId: string, state: ContainerState): this {\n    this.recordMutation(containerId);\n    return super.set(containerId, state);\n  }\n\n  captureMutationGenerations(): ReadonlyMap<string, number> {\n    return new Map(this.#mutationGenerationById);\n  }\n\n  hasMutationAfter(\n    containerId: string,\n    baseline: ReadonlyMap<string, number>,\n  ): boolean {\n    return (\n      (this.#mutationGenerationById.get(containerId) ?? 0) !==\n      (baseline.get(containerId) ?? 0)\n    );\n  }\n\n  private recordMutation(containerId: string): void {\n    this.#nextMutationGeneration += 1;\n    this.#mutationGenerationById.set(containerId, this.#nextMutationGeneration);\n  }\n}\n\nexport function captureContainerStateMutationGenerations(\n  states: Map<string, ContainerState>,\n): ReadonlyMap<string, number> {\n  return states instanceof ContainerStateMap\n    ? states.captureMutationGenerations()\n    : new Map();\n}\n\nexport function containerStateMutatedAfter(\n  states: Map<string, ContainerState>,\n  containerId: string,\n  baseline: ReadonlyMap<string, number>,\n): boolean {\n  return (\n    states instanceof ContainerStateMap &&\n    states.hasMutationAfter(containerId, baseline)\n  );\n}\n"]}

package/stores/container-contents/containerStatePersistence.js

@@ -0,0 +1,57 @@
+import { installContainerMetadataRecord, persistContainerMetadataStateFromRuntime, } from "../../workflows/container-contents/metadata.js";
+import { removeMissingContainerState } from "./missingContainerState.js";
+import { updateContainerContentsSnapshot } from "./state.js";
+export async function persistContainerState(state, containerState, options = {}) {
+    const { expectedStateWhenMissing, isCurrent, updateView = true } = options;
+    const persisted = await persistContainerMetadataStateFromRuntime({
+        metadataState: containerState,
+        localMetadataPatch: options.localMetadataPatch,
+        localUpdate: options.localUpdate,
+        patch: options.patch ?? {},
+        persistence: state.persistence,
+        createIntentSettlement: options.createIntentSettlement,
+        moveIntentSettlement: options.moveIntentSettlement,
+        preserveDurableStructureWhenPending: options.preserveDurableStructureWhenPending,
+        runtime: state.runtime,
+        saveOptions: options.saveOptions,
+        stillCurrent: isCurrent,
+    });
+    if (isCurrent?.() === false) {
+        return { status: "stale-generation" };
+    }
+    if (!persisted) {
+        removeMissingContainerState(state, expectedStateWhenMissing ?? containerState);
+        return { status: "missing" };
+    }
+    containerState.container = persisted.container;
+    installContainerMetadataRecord(containerState, persisted.record);
+    if (persisted.mutationSuperseded || persisted.syncIdentitySuperseded) {
+        const cachedState = state.containersById.get(containerState.container.id);
+        if (cachedState && cachedState !== containerState) {
+            cachedState.container = containerState.container;
+            cachedState.doc = containerState.doc;
+            cachedState.metadataWriterProjection =
+                containerState.metadataWriterProjection;
+            installContainerMetadataRecord(cachedState, persisted.record);
+        }
+        // The requested structural mutation was not applied. Refresh from the
+        // authoritative state installed above, but make the caller fail explicitly
+        // so it cannot schedule sync or report the dropped mutation as successful.
+        updateContainerContentsSnapshot(state);
+        return { record: persisted.record, status: "identity-superseded" };
+    }
+    if (updateView) {
+        updateContainerContentsSnapshot(state);
+    }
+    return {
+        record: persisted.record,
+        status: "persisted",
+        ...(persisted.createIntentSettled
+            ? { createIntentSettled: true }
+            : {}),
+        ...(persisted.moveIntentSettled
+            ? { moveIntentSettled: true }
+            : {}),
+    };
+}
+//# sourceMappingURL=containerStatePersistence.js.map

package/stores/container-contents/containerStatePersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerStatePersistence.js","sourceRoot":"","sources":["containerStatePersistence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,wCAAwC,GACzC,MAAM,6CAA6C,CAAC;AAErD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,+BAA+B,EAAE,MAAM,SAAS,CAAC;AAwB1D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,KAAkC,EAClC,cAA8B,EAC9B,UAAwC,EAAE;IAE1C,MAAM,EAAE,wBAAwB,EAAE,SAAS,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC3E,MAAM,SAAS,GAAG,MAAM,wCAAwC,CAAC;QAC/D,aAAa,EAAE,cAAc;QAC7B,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,EAAE;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;QACtD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,mCAAmC,EACjC,OAAO,CAAC,mCAAmC;QAC7C,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY,EAAE,SAAS;KACxB,CAAC,CAAC;IACH,IAAI,SAAS,EAAE,EAAE,KAAK,KAAK,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IACxC,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,2BAA2B,CACzB,KAAK,EACL,wBAAwB,IAAI,cAAc,CAC3C,CAAC;QACF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC/B,CAAC;IACD,cAAc,CAAC,SAAS,GAAG,SAAS,CAAC,SAAS,CAAC;IAC/C,8BAA8B,CAAC,cAAc,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,SAAS,CAAC,kBAAkB,IAAI,SAAS,CAAC,sBAAsB,EAAE,CAAC;QACrE,MAAM,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1E,IAAI,WAAW,IAAI,WAAW,KAAK,cAAc,EAAE,CAAC;YAClD,WAAW,CAAC,SAAS,GAAG,cAAc,CAAC,SAAS,CAAC;YACjD,WAAW,CAAC,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC;YACrC,WAAW,CAAC,wBAAwB;gBAClC,cAAc,CAAC,wBAAwB,CAAC;YAC1C,8BAA8B,CAAC,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAChE,CAAC;QACD,sEAAsE;QACtE,2EAA2E;QAC3E,2EAA2E;QAC3E,+BAA+B,CAAC,KAAK,CAAC,CAAC;QACvC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,+BAA+B,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IACD,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,MAAM,EAAE,WAAW;QACnB,GAAG,CAAC,SAAS,CAAC,mBAAmB;YAC/B,CAAC,CAAC,EAAE,mBAAmB,EAAE,IAAa,EAAE;YACxC,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,SAAS,CAAC,iBAAiB;YAC7B,CAAC,CAAC,EAAE,iBAAiB,EAAE,IAAa,EAAE;YACtC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC","sourcesContent":["import {\n  installContainerMetadataRecord,\n  persistContainerMetadataStateFromRuntime,\n} from \"../../workflows/container-contents/metadata\";\nimport type { PersistContainerStateResult } from \"../../workflows/container-contents/remoteHydration\";\nimport { removeMissingContainerState } from \"./missingContainerState\";\nimport { updateContainerContentsSnapshot } from \"./state\";\nimport type { ContainerState } from \"./syncAgent\";\nimport type { ContainerContentsStoreState } from \"./types\";\n\ntype MetadataPersistenceInput = Parameters<\n  typeof persistContainerMetadataStateFromRuntime\n>[0];\n\ninterface PersistContainerStateOptions\n  extends Pick<\n    MetadataPersistenceInput,\n    | \"patch\"\n    | \"saveOptions\"\n    | \"localMetadataPatch\"\n    | \"localUpdate\"\n    | \"createIntentSettlement\"\n    | \"moveIntentSettlement\"\n    | \"preserveDurableStructureWhenPending\"\n  > {\n  expectedStateWhenMissing?: ContainerState | undefined;\n  isCurrent?: (() => boolean) | undefined;\n  updateView?: boolean | undefined;\n}\n\nexport async function persistContainerState(\n  state: ContainerContentsStoreState,\n  containerState: ContainerState,\n  options: PersistContainerStateOptions = {},\n): Promise<PersistContainerStateResult> {\n  const { expectedStateWhenMissing, isCurrent, updateView = true } = options;\n  const persisted = await persistContainerMetadataStateFromRuntime({\n    metadataState: containerState,\n    localMetadataPatch: options.localMetadataPatch,\n    localUpdate: options.localUpdate,\n    patch: options.patch ?? {},\n    persistence: state.persistence,\n    createIntentSettlement: options.createIntentSettlement,\n    moveIntentSettlement: options.moveIntentSettlement,\n    preserveDurableStructureWhenPending:\n      options.preserveDurableStructureWhenPending,\n    runtime: state.runtime,\n    saveOptions: options.saveOptions,\n    stillCurrent: isCurrent,\n  });\n  if (isCurrent?.() === false) {\n    return { status: \"stale-generation\" };\n  }\n  if (!persisted) {\n    removeMissingContainerState(\n      state,\n      expectedStateWhenMissing ?? containerState,\n    );\n    return { status: \"missing\" };\n  }\n  containerState.container = persisted.container;\n  installContainerMetadataRecord(containerState, persisted.record);\n  if (persisted.mutationSuperseded || persisted.syncIdentitySuperseded) {\n    const cachedState = state.containersById.get(containerState.container.id);\n    if (cachedState && cachedState !== containerState) {\n      cachedState.container = containerState.container;\n      cachedState.doc = containerState.doc;\n      cachedState.metadataWriterProjection =\n        containerState.metadataWriterProjection;\n      installContainerMetadataRecord(cachedState, persisted.record);\n    }\n    // The requested structural mutation was not applied. Refresh from the\n    // authoritative state installed above, but make the caller fail explicitly\n    // so it cannot schedule sync or report the dropped mutation as successful.\n    updateContainerContentsSnapshot(state);\n    return { record: persisted.record, status: \"identity-superseded\" };\n  }\n  if (updateView) {\n    updateContainerContentsSnapshot(state);\n  }\n  return {\n    record: persisted.record,\n    status: \"persisted\",\n    ...(persisted.createIntentSettled\n      ? { createIntentSettled: true as const }\n      : {}),\n    ...(persisted.moveIntentSettled\n      ? { moveIntentSettled: true as const }\n      : {}),\n  };\n}\n"]}

package/stores/container-contents/documentRecovery.js

@@ -0,0 +1,114 @@
+import { primeDocumentsForContainerSubtree, primeDocumentsForLoadedRoots, } from "../../workflows/container-contents/documentPriming.js";
+import { createContainerContentsDocumentsRuntime, } from "../../workflows/container-contents/runtime.js";
+import { recoverStaleSessionRoot } from "../../workflows/container-contents/staleRootRecovery.js";
+import { isDatabaseUnavailableError } from "../../workflows/container-contents/syncLane.js";
+import { openDocumentStore } from "../documents/index.js";
+import { getContainerContentsStoreLogLabel } from "./logLabel.js";
+const staleRootRecoveryLogState = new WeakMap();
+const rejectedAdoptionRuntime = new WeakMap();
+function createPrimeHost(runtime) {
+    return {
+        documentWorkflowRuntime: (containerId) => createContainerContentsDocumentsRuntime(runtime, containerId),
+        openDocumentStore: ({ documentId, localId, runtime, }) => openDocumentStore(runtime.state.domainScope, localId, runtime, documentId),
+    };
+}
+export async function primeStoreDocumentSubtree(state, rootContainerId, isCurrent = () => true) {
+    if (!isCurrent())
+        return;
+    const runtime = state.runtime;
+    await primeDocumentsForContainerSubtree({
+        containersById: state.containersById,
+        host: createPrimeHost(runtime),
+        isCurrent,
+        rootContainerId,
+        runtime,
+    });
+}
+export async function primeStoreDocuments(state, isCurrent = () => true) {
+    if (!isCurrent())
+        return;
+    const runtime = state.runtime;
+    // Consume the current signal before scanning. A topology/root reconciliation
+    // that lands during an awaited query can then re-arm the next pass without
+    // this pass erasing that newer signal when it completes.
+    state.documentStoresNeedPriming = false;
+    try {
+        const result = await primeDocumentsForLoadedRoots({
+            containersById: state.containersById,
+            host: createPrimeHost(runtime),
+            isCurrent,
+            organizationId: runtime.auth?.organizationId ?? null,
+            runtime,
+        });
+        if (!isCurrent()) {
+            state.documentStoresNeedPriming = true;
+            return;
+        }
+        runtime.util.log(`${getContainerContentsStoreLogLabel(state)}: document priming candidates=${result.candidateCount} roots=${result.rootCount} primed=${result.primedCount} orphaned=${result.orphanPrimedCount} unroutable=${result.unroutableCount}`);
+    }
+    catch (error) {
+        if (!isCurrent()) {
+            state.documentStoresNeedPriming = true;
+            return;
+        }
+        state.documentStoresNeedPriming = true;
+        throw error;
+    }
+}
+export async function recoverStoreStaleRoot(state, isCurrent = () => true) {
+    if (!isCurrent()) {
+        return "context-changed";
+    }
+    const runtime = state.runtime;
+    if (rejectedAdoptionRuntime.get(state) === runtime) {
+        return "not-needed";
+    }
+    let result;
+    try {
+        result = await recoverStaleSessionRoot({ ...state, runtime }, isCurrent);
+    }
+    catch (error) {
+        if (!isCurrent()) {
+            return "context-changed";
+        }
+        if (isDatabaseUnavailableError(error)) {
+            throw error;
+        }
+        const message = `${getContainerContentsStoreLogLabel(state)}: stale root recovery failed`;
+        if (state.runtime.util.logError) {
+            state.runtime.util.logError(message, error);
+        }
+        else {
+            state.runtime.util.log(message);
+        }
+        return "not-needed";
+    }
+    if (!isCurrent()) {
+        return "context-changed";
+    }
+    const message = `${getContainerContentsStoreLogLabel(state)}: stale root recovery status=${result.status} candidates=${result.candidateCount}`;
+    const previousLogState = staleRootRecoveryLogState.get(state);
+    const occurrenceCount = previousLogState?.message === message
+        ? previousLogState.occurrenceCount + 1
+        : 1;
+    staleRootRecoveryLogState.set(state, { message, occurrenceCount });
+    if (result.status !== "not-needed") {
+        if (occurrenceCount === 1) {
+            runtime.util.log(message);
+        }
+        else if ((occurrenceCount & (occurrenceCount - 1)) === 0) {
+            runtime.util.log(`${message} occurrences=${occurrenceCount}`);
+        }
+    }
+    if (result.status === "context-changed") {
+        rejectedAdoptionRuntime.set(state, runtime);
+    }
+    else {
+        rejectedAdoptionRuntime.delete(state);
+    }
+    if (result.reassigned) {
+        state.documentStoresNeedPriming = true;
+    }
+    return result.status;
+}
+//# sourceMappingURL=documentRecovery.js.map