@tearleads/client-sdk 0.1.61 → 0.1.63

package/workflows/container-contents/documentPriming/documentHydrationProbe.js

@@ -0,0 +1,146 @@
+import { HIDDEN_DOCUMENT_SUMMARY_KINDS } from "../../../data/documents/documentSummary.js";
+import { documentContainerProjectionTables, documentProjectionTables, documentTables, } from "../../../data/sqlite/schema.js";
+import { ensureSqlTables } from "../../../data/sqlite/sqlSchema.js";
+import { listContainerContentsSqlIdBatches } from "../documentQueries/sql.js";
+import { requestRemoteDocumentRuntimeTargetSync } from "./documentRuntimeTargetSync.js";
+const DOCUMENT_HYDRATION_PROBE_REQUEST_BATCH_SIZE = 8;
+const DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE = 64;
+function valuePlaceholders(values) {
+    return values.map(() => "?").join(", ");
+}
+function valueRows(values) {
+    return values.map(() => "(?)").join(", ");
+}
+function readProbeTarget(row) {
+    // These aliases are wholly internal SQL contracts; fail loudly if a query
+    // edit violates them instead of silently skipping a persisted document.
+    if (row === null || (typeof row !== "object" && typeof row !== "function")) {
+        throw new Error("Document hydration probe returned an invalid target");
+    }
+    const documentId = Reflect.get(row, "document_id");
+    const localId = Reflect.get(row, "local_id");
+    const projectedContainerId = Reflect.get(row, "projected_container_id");
+    const runtimeContainerId = Reflect.get(row, "container_id");
+    if (typeof documentId !== "string" ||
+        typeof localId !== "string" ||
+        typeof runtimeContainerId !== "string") {
+        throw new Error("Document hydration probe returned an invalid target");
+    }
+    return {
+        documentId,
+        localId,
+        preferredRuntimeContainer: projectedContainerId === runtimeContainerId,
+        runtimeContainerId,
+    };
+}
+async function listRemoteDocumentProbeBatchForContainerIds(input) {
+    const rows = await input.runtime.infra.execSql(`
+      WITH eligible_container_ids(container_id) AS (
+        VALUES ${valueRows(input.containerIds)}
+      )
+      SELECT
+        stored.local_id AS local_id,
+        stored.document_id AS document_id,
+        projection.container_id AS projected_container_id,
+        COALESCE(
+          projected_container.container_id,
+          MIN(linked_container.container_id)
+        ) AS container_id
+      FROM documents stored
+      INNER JOIN document_projection projection
+        ON projection.local_id = stored.local_id
+      LEFT JOIN eligible_container_ids projected_container
+        ON projected_container.container_id = projection.container_id
+      LEFT JOIN document_container_projection link
+        ON link.document_id = stored.document_id
+      LEFT JOIN eligible_container_ids linked_container
+        ON linked_container.container_id = link.container_id
+      WHERE stored.app_kind = 'documents'
+        AND stored.document_id IS NOT NULL
+        AND (? IS NULL OR stored.local_id > ?)
+        AND (
+          projected_container.container_id IS NOT NULL
+          OR linked_container.container_id IS NOT NULL
+        )
+        AND projection.document_kind NOT IN (${valuePlaceholders(HIDDEN_DOCUMENT_SUMMARY_KINDS)})
+      GROUP BY
+        stored.local_id,
+        stored.document_id,
+        projection.container_id,
+        projected_container.container_id
+      ORDER BY stored.local_id ASC
+      LIMIT ?
+    `, [
+        ...input.containerIds,
+        input.afterLocalId,
+        input.afterLocalId,
+        ...HIDDEN_DOCUMENT_SUMMARY_KINDS,
+        DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE,
+    ]);
+    return rows.map(readProbeTarget);
+}
+function mergeRemoteDocumentProbeTargets(batches) {
+    const targetsByLocalId = new Map();
+    for (const batch of batches) {
+        for (const target of batch) {
+            const existing = targetsByLocalId.get(target.localId);
+            if (existing === undefined ||
+                (target.preferredRuntimeContainer &&
+                    !existing.preferredRuntimeContainer) ||
+                (target.preferredRuntimeContainer ===
+                    existing.preferredRuntimeContainer &&
+                    target.runtimeContainerId < existing.runtimeContainerId)) {
+                targetsByLocalId.set(target.localId, target);
+            }
+        }
+    }
+    return [...targetsByLocalId.values()]
+        .sort((left, right) => left.localId < right.localId ? -1 : Number(left.localId > right.localId))
+        .slice(0, DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE);
+}
+async function listRemoteDocumentProbeBatch(input) {
+    const containerIds = [...input.listedContainerIds];
+    if (containerIds.length === 0) {
+        return [];
+    }
+    await ensureSqlTables(input.runtime.infra.execSql, [
+        ...documentTables,
+        ...documentProjectionTables,
+        ...documentContainerProjectionTables,
+    ]);
+    const batches = [];
+    for (const containerIdBatch of listContainerContentsSqlIdBatches(containerIds)) {
+        batches.push(await listRemoteDocumentProbeBatchForContainerIds({
+            afterLocalId: input.afterLocalId,
+            containerIds: containerIdBatch,
+            runtime: input.runtime,
+        }));
+    }
+    return mergeRemoteDocumentProbeTargets(batches);
+}
+/**
+ * Opens at most one bounded batch of visible, remote-backed local documents
+ * linked to an authoritatively listed container but absent from every full
+ * listing. Each store's ordinary sync pass owns its coded-404/403 verdict.
+ */
+export async function probeUndiscoveredRemoteDocumentBatch(input) {
+    const scanned = await listRemoteDocumentProbeBatch(input);
+    const candidates = scanned.filter((target) => !input.listedDocumentIds.has(target.documentId));
+    const targets = candidates.slice(0, DOCUMENT_HYDRATION_PROBE_REQUEST_BATCH_SIZE);
+    const requested = await requestRemoteDocumentRuntimeTargetSync({
+        host: input.host,
+        targets,
+    });
+    const hasUnrequestedCandidate = candidates.length > targets.length;
+    const scanPageMayContinue = scanned.length === DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE;
+    const done = !hasUnrequestedCandidate && !scanPageMayContinue;
+    const nextCursorTarget = hasUnrequestedCandidate
+        ? targets.at(-1)
+        : scanned.at(-1);
+    return {
+        done,
+        nextCursor: done ? null : (nextCursorTarget?.localId ?? null),
+        requestedCount: requested.size,
+    };
+}
+//# sourceMappingURL=documentHydrationProbe.js.map

package/workflows/container-contents/documentPriming/documentHydrationProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentHydrationProbe.js","sourceRoot":"","sources":["documentHydrationProbe.ts"],"names":[],"mappings":"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","sourcesContent":["import { HIDDEN_DOCUMENT_SUMMARY_KINDS } from \"../../../data/documents/documentSummary\";\nimport {\n  documentContainerProjectionTables,\n  documentProjectionTables,\n  documentTables,\n} from \"../../../data/sqlite/schema\";\nimport { ensureSqlTables } from \"../../../data/sqlite/sqlSchema\";\nimport { listContainerContentsSqlIdBatches } from \"../documentQueries/sql\";\nimport type {\n  ContainerContentsDocumentRuntimeTarget,\n  ContainerDocumentProbeHost,\n  ContainerDocumentQueriesRuntime,\n} from \"../documentQueries/types\";\nimport { requestRemoteDocumentRuntimeTargetSync } from \"./documentRuntimeTargetSync\";\n\nconst DOCUMENT_HYDRATION_PROBE_REQUEST_BATCH_SIZE = 8;\nconst DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE = 64;\n\ninterface DocumentHydrationProbeBatchResult {\n  readonly done: boolean;\n  readonly nextCursor: string | null;\n  readonly requestedCount: number;\n}\n\ntype RemoteDocumentProbeTarget = Omit<\n  ContainerContentsDocumentRuntimeTarget,\n  \"documentId\" | \"runtimeContainerId\"\n> & {\n  readonly documentId: string;\n  readonly preferredRuntimeContainer: boolean;\n  readonly runtimeContainerId: string;\n};\n\nfunction valuePlaceholders(values: ReadonlyArray<unknown>): string {\n  return values.map(() => \"?\").join(\", \");\n}\n\nfunction valueRows(values: ReadonlyArray<unknown>): string {\n  return values.map(() => \"(?)\").join(\", \");\n}\n\nfunction readProbeTarget(row: unknown): RemoteDocumentProbeTarget {\n  // These aliases are wholly internal SQL contracts; fail loudly if a query\n  // edit violates them instead of silently skipping a persisted document.\n  if (row === null || (typeof row !== \"object\" && typeof row !== \"function\")) {\n    throw new Error(\"Document hydration probe returned an invalid target\");\n  }\n  const documentId = Reflect.get(row, \"document_id\");\n  const localId = Reflect.get(row, \"local_id\");\n  const projectedContainerId = Reflect.get(row, \"projected_container_id\");\n  const runtimeContainerId = Reflect.get(row, \"container_id\");\n  if (\n    typeof documentId !== \"string\" ||\n    typeof localId !== \"string\" ||\n    typeof runtimeContainerId !== \"string\"\n  ) {\n    throw new Error(\"Document hydration probe returned an invalid target\");\n  }\n  return {\n    documentId,\n    localId,\n    preferredRuntimeContainer: projectedContainerId === runtimeContainerId,\n    runtimeContainerId,\n  };\n}\n\nasync function listRemoteDocumentProbeBatchForContainerIds(input: {\n  readonly afterLocalId: string | null;\n  readonly containerIds: ReadonlyArray<string>;\n  readonly runtime: ContainerDocumentQueriesRuntime;\n}): Promise<RemoteDocumentProbeTarget[]> {\n  const rows = await input.runtime.infra.execSql(\n    `\n      WITH eligible_container_ids(container_id) AS (\n        VALUES ${valueRows(input.containerIds)}\n      )\n      SELECT\n        stored.local_id AS local_id,\n        stored.document_id AS document_id,\n        projection.container_id AS projected_container_id,\n        COALESCE(\n          projected_container.container_id,\n          MIN(linked_container.container_id)\n        ) AS container_id\n      FROM documents stored\n      INNER JOIN document_projection projection\n        ON projection.local_id = stored.local_id\n      LEFT JOIN eligible_container_ids projected_container\n        ON projected_container.container_id = projection.container_id\n      LEFT JOIN document_container_projection link\n        ON link.document_id = stored.document_id\n      LEFT JOIN eligible_container_ids linked_container\n        ON linked_container.container_id = link.container_id\n      WHERE stored.app_kind = 'documents'\n        AND stored.document_id IS NOT NULL\n        AND (? IS NULL OR stored.local_id > ?)\n        AND (\n          projected_container.container_id IS NOT NULL\n          OR linked_container.container_id IS NOT NULL\n        )\n        AND projection.document_kind NOT IN (${valuePlaceholders(\n          HIDDEN_DOCUMENT_SUMMARY_KINDS,\n        )})\n      GROUP BY\n        stored.local_id,\n        stored.document_id,\n        projection.container_id,\n        projected_container.container_id\n      ORDER BY stored.local_id ASC\n      LIMIT ?\n    `,\n    [\n      ...input.containerIds,\n      input.afterLocalId,\n      input.afterLocalId,\n      ...HIDDEN_DOCUMENT_SUMMARY_KINDS,\n      DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE,\n    ],\n  );\n  return rows.map(readProbeTarget);\n}\n\nfunction mergeRemoteDocumentProbeTargets(\n  batches: ReadonlyArray<ReadonlyArray<RemoteDocumentProbeTarget>>,\n): RemoteDocumentProbeTarget[] {\n  const targetsByLocalId = new Map<string, RemoteDocumentProbeTarget>();\n  for (const batch of batches) {\n    for (const target of batch) {\n      const existing = targetsByLocalId.get(target.localId);\n      if (\n        existing === undefined ||\n        (target.preferredRuntimeContainer &&\n          !existing.preferredRuntimeContainer) ||\n        (target.preferredRuntimeContainer ===\n          existing.preferredRuntimeContainer &&\n          target.runtimeContainerId < existing.runtimeContainerId)\n      ) {\n        targetsByLocalId.set(target.localId, target);\n      }\n    }\n  }\n  return [...targetsByLocalId.values()]\n    .sort((left, right) =>\n      left.localId < right.localId ? -1 : Number(left.localId > right.localId),\n    )\n    .slice(0, DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE);\n}\n\nasync function listRemoteDocumentProbeBatch(input: {\n  readonly afterLocalId: string | null;\n  readonly listedContainerIds: ReadonlySet<string>;\n  readonly runtime: ContainerDocumentQueriesRuntime;\n}): Promise<RemoteDocumentProbeTarget[]> {\n  const containerIds = [...input.listedContainerIds];\n  if (containerIds.length === 0) {\n    return [];\n  }\n\n  await ensureSqlTables(input.runtime.infra.execSql, [\n    ...documentTables,\n    ...documentProjectionTables,\n    ...documentContainerProjectionTables,\n  ]);\n  const batches: RemoteDocumentProbeTarget[][] = [];\n  for (const containerIdBatch of listContainerContentsSqlIdBatches(\n    containerIds,\n  )) {\n    batches.push(\n      await listRemoteDocumentProbeBatchForContainerIds({\n        afterLocalId: input.afterLocalId,\n        containerIds: containerIdBatch,\n        runtime: input.runtime,\n      }),\n    );\n  }\n  return mergeRemoteDocumentProbeTargets(batches);\n}\n\n/**\n * Opens at most one bounded batch of visible, remote-backed local documents\n * linked to an authoritatively listed container but absent from every full\n * listing. Each store's ordinary sync pass owns its coded-404/403 verdict.\n */\nexport async function probeUndiscoveredRemoteDocumentBatch<TRuntime>(input: {\n  readonly afterLocalId: string | null;\n  readonly host: ContainerDocumentProbeHost<TRuntime>;\n  readonly listedContainerIds: ReadonlySet<string>;\n  readonly listedDocumentIds: ReadonlySet<string>;\n  readonly runtime: ContainerDocumentQueriesRuntime;\n}): Promise<DocumentHydrationProbeBatchResult> {\n  const scanned = await listRemoteDocumentProbeBatch(input);\n  const candidates = scanned.filter(\n    (target) => !input.listedDocumentIds.has(target.documentId),\n  );\n  const targets = candidates.slice(\n    0,\n    DOCUMENT_HYDRATION_PROBE_REQUEST_BATCH_SIZE,\n  );\n  const requested = await requestRemoteDocumentRuntimeTargetSync({\n    host: input.host,\n    targets,\n  });\n  const hasUnrequestedCandidate = candidates.length > targets.length;\n  const scanPageMayContinue =\n    scanned.length === DOCUMENT_HYDRATION_PROBE_SCAN_BATCH_SIZE;\n  const done = !hasUnrequestedCandidate && !scanPageMayContinue;\n  const nextCursorTarget = hasUnrequestedCandidate\n    ? targets.at(-1)\n    : scanned.at(-1);\n  return {\n    done,\n    nextCursor: done ? null : (nextCursorTarget?.localId ?? null),\n    requestedCount: requested.size,\n  };\n}\n"]}

package/workflows/container-contents/documentPriming/documentRuntimeTargetSync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentRuntimeTargetSync.js","sourceRoot":"","sources":["documentRuntimeTargetSync.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,8EAA8E;AAC9E,6CAA6C;AAC7C,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAEzC,KAAK,UAAU,wBAAwB,CAAmB,KAYzD;IACC,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC5C,MAAM,qBAAqB,GAAG,IAAI,GAAG,EAA2B,CAAC;IACjE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAElD,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,SAAS,EAAE;YAAE,OAAO,iBAAiB,CAAC;QAC3C,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,IACE,iBAAiB,CAAC,IAAI,GAAG,CAAC;YAC1B,iBAAiB,CAAC,IAAI,GAAG,8BAA8B,KAAK,CAAC,EAC7D,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7D,IAAI,CAAC,SAAS,EAAE;gBAAE,OAAO,iBAAiB,CAAC;QAC7C,CAAC;QAED,IAAI,OAAO,GAAG,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QACnE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;YACxE,qBAAqB,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAChE,CAAC;QAED,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC;YACzC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO;SACR,CAAC,CAAC;QACH,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACtC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAW,KAI1D;IACC,OAAO,wBAAwB,CAAC;QAC9B,GAAG,KAAK;QACR,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,EAAE,CAAC;gBACxC,KAAK,CAAC,WAAW,EAAE,CAAC;YACtB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sCAAsC,CAAW,KAIhE;IACC,OAAO,wBAAwB,CAAC;QAC9B,GAAG,KAAK;QACR,yEAAyE;QACzE,uEAAuE;QACvE,qEAAqE;QACrE,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,iBAAiB,EAAE;KACvD,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type {\n  ContainerContentsDocumentRuntimeTarget,\n  ContainerDocumentPrimeHost,\n  ContainerDocumentProbeHost,\n} from \"../documentQueries/types\";\n\n// Stores opened per macrotask. Opening is fire-and-forget, so yielding between\n// chunks keeps the main thread and serialized SQLite queue responsive while a\n// restored replica schedules a real backlog.\nconst DOCUMENT_STORE_OPEN_CHUNK_SIZE = 8;\n\nasync function requestRuntimeTargetSync<TRuntime, TStore>(input: {\n  readonly host: {\n    documentWorkflowRuntime: (containerId: string | null) => TRuntime;\n    openDocumentStore: (input: {\n      documentId: string | null;\n      localId: string;\n      runtime: TRuntime;\n    }) => TStore;\n  };\n  readonly isCurrent?: (() => boolean) | undefined;\n  readonly requestStoreSync: (store: TStore) => void;\n  readonly targets: ReadonlyArray<ContainerContentsDocumentRuntimeTarget>;\n}): Promise<ReadonlySet<string>> {\n  const requestedLocalIds = new Set<string>();\n  const runtimesByContainerId = new Map<string | null, TRuntime>();\n  const isCurrent = input.isCurrent ?? (() => true);\n\n  for (const target of input.targets) {\n    if (!isCurrent()) return requestedLocalIds;\n    if (requestedLocalIds.has(target.localId)) {\n      continue;\n    }\n    if (\n      requestedLocalIds.size > 0 &&\n      requestedLocalIds.size % DOCUMENT_STORE_OPEN_CHUNK_SIZE === 0\n    ) {\n      await new Promise<void>((resolve) => setTimeout(resolve, 0));\n      if (!isCurrent()) return requestedLocalIds;\n    }\n\n    let runtime = runtimesByContainerId.get(target.runtimeContainerId);\n    if (runtime === undefined) {\n      runtime = input.host.documentWorkflowRuntime(target.runtimeContainerId);\n      runtimesByContainerId.set(target.runtimeContainerId, runtime);\n    }\n\n    const store = input.host.openDocumentStore({\n      documentId: target.documentId,\n      localId: target.localId,\n      runtime,\n    });\n    requestedLocalIds.add(target.localId);\n    input.requestStoreSync(store);\n  }\n\n  return requestedLocalIds;\n}\n\nexport function requestDocumentRuntimeTargetSync<TRuntime>(input: {\n  readonly host: ContainerDocumentPrimeHost<TRuntime>;\n  readonly isCurrent?: (() => boolean) | undefined;\n  readonly targets: ReadonlyArray<ContainerContentsDocumentRuntimeTarget>;\n}): Promise<ReadonlySet<string>> {\n  return requestRuntimeTargetSync({\n    ...input,\n    requestStoreSync: (store) => {\n      if (store.getSnapshot?.().ready ?? true) {\n        store.requestSync();\n      }\n    },\n  });\n}\n\nexport function requestRemoteDocumentRuntimeTargetSync<TRuntime>(input: {\n  readonly host: ContainerDocumentProbeHost<TRuntime>;\n  readonly isCurrent?: (() => boolean) | undefined;\n  readonly targets: ReadonlyArray<ContainerContentsDocumentRuntimeTarget>;\n}): Promise<ReadonlySet<string>> {\n  return requestRuntimeTargetSync({\n    ...input,\n    // Unlike ordinary startup priming, a probe must survive a freshly opened\n    // store's initialization. requestRemoteSync records that intent before\n    // scheduling, so the first ready pass performs an HTTP revalidation.\n    requestStoreSync: (store) => store.requestRemoteSync(),\n  });\n}\n"]}

package/workflows/container-contents/documentPriming/index.js

@@ -0,0 +1,245 @@
+import { documentContainerProjectionTables, documentPlacementIntentTables, documentProjectionTables, documentTables, LOCAL_INTENT_LANES, } from "../../../data/sqlite/schema.js";
+import { ensureSqlTables } from "../../../data/sqlite/sqlSchema.js";
+import { listDocumentRuntimeTargetsForContainerSubtreeFromRuntime } from "../documentQueries/documentSubtreeQueries.js";
+import { getOrphanedDocumentQueryBind, getOrphanedDocumentWhereSql, } from "../documentQueries/orphanedDocumentSql.js";
+import { requestDocumentRuntimeTargetSync } from "./documentRuntimeTargetSync.js";
+// Documents that still NEED a store opened at prime time: local-only creates,
+// queued outbound updates/attachments, an outgoing-delta marker behind the
+// stored content frontier (a deferred tail; encoding inequality
+// over-approximates, which only re-primes a store the old behavior always
+// primed), a never-hydrated document (a freshly discovered share whose
+// content pull the primed lane performs), or a document with a recorded sync
+// failure (a refused revalidation leaves no queued work, so the failure row
+// is the only ticket that re-drives the store — the retry that clears on the
+// next clean pass). Fully-synced hydrated documents are
+// deliberately absent: priming exists to re-drive durable work, and opening a
+// store per settled document is what made a 1000-document boot a storm.
+const PENDING_PRIME_LOCAL_ID_SQL = `
+  SELECT stored.local_id AS local_id
+  FROM documents stored
+  WHERE stored.app_kind = 'documents'
+    AND (
+      stored.document_id IS NULL
+      OR stored.snapshot_end_version = ''
+      OR stored.pull_continuation IS NOT NULL
+      OR COALESCE(stored.pending_base_version, '') <> stored.snapshot_end_version
+      OR EXISTS (
+        SELECT 1
+        FROM document_history_updates pending
+        WHERE pending.app_kind = 'documents'
+          AND pending.local_id = stored.local_id
+          AND pending.update_id IS NOT NULL
+      )
+      OR stored.sync_failure_message IS NOT NULL
+      OR EXISTS (
+        SELECT 1
+        FROM document_pending_attachments attachment
+        WHERE attachment.local_id = stored.local_id
+      )
+    )
+`;
+const PENDING_PRIME_DOCUMENT_CANDIDATE_SQL = `
+  SELECT pending.local_id AS local_id
+  FROM (${PENDING_PRIME_LOCAL_ID_SQL}) pending
+  ORDER BY pending.local_id ASC
+`;
+// The structural startup probe and the priming worker share the same durable
+// predicate so they cannot disagree about what counts as document work.
+const STARTUP_DOCUMENT_SYNC_WORK_SQL = `
+  SELECT 1 AS present
+  WHERE EXISTS (${PENDING_PRIME_LOCAL_ID_SQL})
+    OR EXISTS (
+      SELECT 1
+      FROM local_intents intent
+      -- Blocked and parked denied moves count: blocked intents replay on
+      -- every scan (the blocking condition can heal after hydration), and
+      -- the once-per-launch replay makes denied moves retriable — so a
+      -- relaunch whose only durable work is either kind must still schedule
+      -- the structural pass that re-attempts it (row 7). Unavailable moves
+      -- are excluded: no pass ever replays them (#2278 #4).
+      WHERE intent.lane = '${LOCAL_INTENT_LANES.documentPlacement}'
+        AND intent.sync_status IN ('pending', 'blocked', 'denied')
+    )
+  LIMIT 1
+`;
+export async function hasStartupDocumentSyncWork(runtimeOrExecSql) {
+    const execSql = typeof runtimeOrExecSql === "function"
+        ? runtimeOrExecSql
+        : runtimeOrExecSql.infra.execSql;
+    await ensureSqlTables(execSql, [
+        ...documentTables,
+        ...documentProjectionTables,
+        ...documentPlacementIntentTables,
+    ]);
+    const rows = await execSql(STARTUP_DOCUMENT_SYNC_WORK_SQL);
+    return rows.length > 0;
+}
+async function listPrimeRequiredDocumentCandidatesFromRuntime(runtime) {
+    await ensureSqlTables(runtime.infra.execSql, [
+        ...documentTables,
+        ...documentProjectionTables,
+    ]);
+    const rows = await runtime.infra.execSql(PENDING_PRIME_DOCUMENT_CANDIDATE_SQL);
+    return rows.flatMap((row) => {
+        const localId = Reflect.get(row, "local_id");
+        if (typeof localId !== "string") {
+            return [];
+        }
+        return [{ localId }];
+    });
+}
+// A row with content but a NULL outgoing-delta marker is deliberately treated
+// as unsettled: the store persist path always sets the marker, so over-priming
+// is the safe direction.
+async function listPrimeRequiredLocalIdsFromRuntime(runtime) {
+    const candidates = await listPrimeRequiredDocumentCandidatesFromRuntime(runtime);
+    return new Set(candidates.map((candidate) => candidate.localId));
+}
+/**
+ * Last-link orphans (docs/sync-edge-cases.md row 3): the container cascade
+ * nulled their projection container and dropped their link rows, so no
+ * subtree listing can route them. Placements held for unsigned tombstones
+ * also qualify when every link is hidden; their link rows remain intact.
+ * These documents are primed with a null container
+ * scope instead — the documents runtime accepts one, and the document's own
+ * sync pass then resolves its fate against the server: 403 parks it (row 8),
+ * a coded 404 destroys it (row 1), and a local-only orphan's create attempt
+ * records a terminal failure row. Hidden document kinds stay excluded, and
+ * dangling non-null projections (a container row merely missing locally)
+ * stay with stale-root recovery, exactly as before.
+ *
+ * Organization neutrality: the null scope changes only the runtime's
+ * containerId — auth, crypto, and organization plumbing are identical to
+ * every container-scoped runtime this store already primes with, the sync
+ * pass derives billing and keying organizations from the document's own
+ * plan and manifest, and a cross-organization author fails closed at the
+ * sync layer's identity guard before anything is signed.
+ */
+const ORPHANED_PRIME_TARGET_SQL = `
+  SELECT stored.local_id AS local_id, stored.document_id AS document_id
+  FROM documents stored
+  INNER JOIN document_projection projection
+    ON projection.local_id = stored.local_id
+  WHERE stored.app_kind = 'documents'
+    AND ${getOrphanedDocumentWhereSql({
+    documentIdSql: "stored.document_id",
+    projectionAlias: "projection",
+})}
+  ORDER BY stored.local_id ASC
+`;
+/**
+ * Unattributed rows (empty/NULL organization) are always included: they are
+ * device-first documents created before authentication, which belong to this
+ * device's sole user and adopt the active organization when they create.
+ */
+async function listOrphanedDocumentPrimeTargets(runtime, organizationId) {
+    await ensureSqlTables(runtime.infra.execSql, [
+        ...documentTables,
+        ...documentProjectionTables,
+        ...documentContainerProjectionTables,
+    ]);
+    const rows = await runtime.infra.execSql(ORPHANED_PRIME_TARGET_SQL, getOrphanedDocumentQueryBind(organizationId));
+    return rows.flatMap((row) => {
+        const localId = Reflect.get(row, "local_id");
+        if (typeof localId !== "string") {
+            return [];
+        }
+        const documentId = Reflect.get(row, "document_id");
+        return [
+            {
+                documentId: typeof documentId === "string" ? documentId : null,
+                localId,
+                runtimeContainerId: null,
+            },
+        ];
+    });
+}
+export async function primeDocumentsForContainerSubtree(input) {
+    const isCurrent = input.isCurrent ?? (() => true);
+    if (!isCurrent())
+        return 0;
+    const [targets, primeRequiredLocalIds] = await Promise.all([
+        listDocumentRuntimeTargetsForContainerSubtreeFromRuntime({
+            containersById: input.containersById,
+            rootContainerId: input.rootContainerId,
+            runtime: input.runtime,
+        }),
+        input.primeRequiredLocalIds ??
+            listPrimeRequiredLocalIdsFromRuntime(input.runtime),
+    ]);
+    if (!isCurrent())
+        return 0;
+    const primed = await requestDocumentRuntimeTargetSync({
+        host: input.host,
+        isCurrent,
+        targets: targets.filter((target) => primeRequiredLocalIds.has(target.localId)),
+    });
+    return primed.size;
+}
+export async function primeDocumentsForLoadedRoots(input) {
+    const isCurrent = input.isCurrent ?? (() => true);
+    if (!isCurrent()) {
+        return {
+            candidateCount: 0,
+            orphanPrimedCount: 0,
+            primedCount: 0,
+            rootCount: 0,
+            unroutableCount: 0,
+        };
+    }
+    const candidates = await listPrimeRequiredDocumentCandidatesFromRuntime(input.runtime);
+    if (!isCurrent()) {
+        return {
+            candidateCount: candidates.length,
+            orphanPrimedCount: 0,
+            primedCount: 0,
+            rootCount: 0,
+            unroutableCount: candidates.length,
+        };
+    }
+    const rootContainerIds = Array.from(input.containersById.values()).flatMap((containerState) => containerState.container.parentId === null
+        ? [containerState.container.id]
+        : []);
+    const requiredLocalIds = new Set(candidates.map((candidate) => candidate.localId));
+    const primedLocalIds = new Set();
+    for (const rootContainerId of rootContainerIds) {
+        if (!isCurrent())
+            break;
+        const targets = await listDocumentRuntimeTargetsForContainerSubtreeFromRuntime({
+            containersById: input.containersById,
+            rootContainerId,
+            runtime: input.runtime,
+        });
+        if (!isCurrent())
+            break;
+        const primed = await requestDocumentRuntimeTargetSync({
+            host: input.host,
+            isCurrent,
+            targets: targets.filter((target) => requiredLocalIds.has(target.localId) &&
+                !primedLocalIds.has(target.localId)),
+        });
+        for (const localId of primed) {
+            primedLocalIds.add(localId);
+        }
+    }
+    const orphanTargets = (isCurrent() && input.organizationId
+        ? await listOrphanedDocumentPrimeTargets(input.runtime, input.organizationId)
+        : []).filter((target) => requiredLocalIds.has(target.localId) &&
+        !primedLocalIds.has(target.localId));
+    const orphanPrimed = await requestDocumentRuntimeTargetSync({
+        host: input.host,
+        isCurrent,
+        targets: isCurrent() ? orphanTargets : [],
+    });
+    for (const localId of orphanPrimed) {
+        primedLocalIds.add(localId);
+    }
+    return {
+        candidateCount: candidates.length,
+        orphanPrimedCount: orphanPrimed.size,
+        primedCount: primedLocalIds.size,
+        rootCount: rootContainerIds.length,
+        unroutableCount: candidates.filter((candidate) => !primedLocalIds.has(candidate.localId)).length,
+    };
+}
+//# sourceMappingURL=index.js.map

package/workflows/container-contents/documentPriming/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  documentContainerProjectionTables,\n  documentPlacementIntentTables,\n  documentProjectionTables,\n  documentTables,\n  LOCAL_INTENT_LANES,\n} from \"../../../data/sqlite/schema\";\nimport { ensureSqlTables } from \"../../../data/sqlite/sqlSchema\";\nimport { listDocumentRuntimeTargetsForContainerSubtreeFromRuntime } from \"../documentQueries/documentSubtreeQueries\";\nimport {\n  getOrphanedDocumentQueryBind,\n  getOrphanedDocumentWhereSql,\n} from \"../documentQueries/orphanedDocumentSql\";\nimport type {\n  ContainerContentsContainerSubtreeState,\n  ContainerContentsDocumentRuntimeTarget,\n  ContainerDocumentPrimeHost,\n  ContainerDocumentQueriesRuntime,\n} from \"../documentQueries/types\";\nimport { requestDocumentRuntimeTargetSync } from \"./documentRuntimeTargetSync\";\n\ninterface PrimeRequiredDocumentCandidate {\n  readonly localId: string;\n}\n\ninterface LoadedRootDocumentPrimeResult {\n  readonly candidateCount: number;\n  readonly orphanPrimedCount: number;\n  readonly primedCount: number;\n  readonly rootCount: number;\n  readonly unroutableCount: number;\n}\n\n// Documents that still NEED a store opened at prime time: local-only creates,\n// queued outbound updates/attachments, an outgoing-delta marker behind the\n// stored content frontier (a deferred tail; encoding inequality\n// over-approximates, which only re-primes a store the old behavior always\n// primed), a never-hydrated document (a freshly discovered share whose\n// content pull the primed lane performs), or a document with a recorded sync\n// failure (a refused revalidation leaves no queued work, so the failure row\n// is the only ticket that re-drives the store — the retry that clears on the\n// next clean pass). Fully-synced hydrated documents are\n// deliberately absent: priming exists to re-drive durable work, and opening a\n// store per settled document is what made a 1000-document boot a storm.\nconst PENDING_PRIME_LOCAL_ID_SQL = `\n  SELECT stored.local_id AS local_id\n  FROM documents stored\n  WHERE stored.app_kind = 'documents'\n    AND (\n      stored.document_id IS NULL\n      OR stored.snapshot_end_version = ''\n      OR stored.pull_continuation IS NOT NULL\n      OR COALESCE(stored.pending_base_version, '') <> stored.snapshot_end_version\n      OR EXISTS (\n        SELECT 1\n        FROM document_history_updates pending\n        WHERE pending.app_kind = 'documents'\n          AND pending.local_id = stored.local_id\n          AND pending.update_id IS NOT NULL\n      )\n      OR stored.sync_failure_message IS NOT NULL\n      OR EXISTS (\n        SELECT 1\n        FROM document_pending_attachments attachment\n        WHERE attachment.local_id = stored.local_id\n      )\n    )\n`;\n\nconst PENDING_PRIME_DOCUMENT_CANDIDATE_SQL = `\n  SELECT pending.local_id AS local_id\n  FROM (${PENDING_PRIME_LOCAL_ID_SQL}) pending\n  ORDER BY pending.local_id ASC\n`;\n\n// The structural startup probe and the priming worker share the same durable\n// predicate so they cannot disagree about what counts as document work.\nconst STARTUP_DOCUMENT_SYNC_WORK_SQL = `\n  SELECT 1 AS present\n  WHERE EXISTS (${PENDING_PRIME_LOCAL_ID_SQL})\n    OR EXISTS (\n      SELECT 1\n      FROM local_intents intent\n      -- Blocked and parked denied moves count: blocked intents replay on\n      -- every scan (the blocking condition can heal after hydration), and\n      -- the once-per-launch replay makes denied moves retriable — so a\n      -- relaunch whose only durable work is either kind must still schedule\n      -- the structural pass that re-attempts it (row 7). Unavailable moves\n      -- are excluded: no pass ever replays them (#2278 #4).\n      WHERE intent.lane = '${LOCAL_INTENT_LANES.documentPlacement}'\n        AND intent.sync_status IN ('pending', 'blocked', 'denied')\n    )\n  LIMIT 1\n`;\n\nexport async function hasStartupDocumentSyncWork(\n  runtimeOrExecSql:\n    | ContainerDocumentQueriesRuntime\n    | ContainerDocumentQueriesRuntime[\"infra\"][\"execSql\"],\n): Promise<boolean> {\n  const execSql =\n    typeof runtimeOrExecSql === \"function\"\n      ? runtimeOrExecSql\n      : runtimeOrExecSql.infra.execSql;\n  await ensureSqlTables(execSql, [\n    ...documentTables,\n    ...documentProjectionTables,\n    ...documentPlacementIntentTables,\n  ]);\n  const rows = await execSql(STARTUP_DOCUMENT_SYNC_WORK_SQL);\n  return rows.length > 0;\n}\n\nasync function listPrimeRequiredDocumentCandidatesFromRuntime(\n  runtime: ContainerDocumentQueriesRuntime,\n): Promise<PrimeRequiredDocumentCandidate[]> {\n  await ensureSqlTables(runtime.infra.execSql, [\n    ...documentTables,\n    ...documentProjectionTables,\n  ]);\n  const rows = await runtime.infra.execSql(\n    PENDING_PRIME_DOCUMENT_CANDIDATE_SQL,\n  );\n\n  return rows.flatMap((row) => {\n    const localId = Reflect.get(row, \"local_id\");\n    if (typeof localId !== \"string\") {\n      return [];\n    }\n    return [{ localId }];\n  });\n}\n\n// A row with content but a NULL outgoing-delta marker is deliberately treated\n// as unsettled: the store persist path always sets the marker, so over-priming\n// is the safe direction.\nasync function listPrimeRequiredLocalIdsFromRuntime(\n  runtime: ContainerDocumentQueriesRuntime,\n): Promise<ReadonlySet<string>> {\n  const candidates =\n    await listPrimeRequiredDocumentCandidatesFromRuntime(runtime);\n  return new Set(candidates.map((candidate) => candidate.localId));\n}\n\n/**\n * Last-link orphans (docs/sync-edge-cases.md row 3): the container cascade\n * nulled their projection container and dropped their link rows, so no\n * subtree listing can route them. Placements held for unsigned tombstones\n * also qualify when every link is hidden; their link rows remain intact.\n * These documents are primed with a null container\n * scope instead — the documents runtime accepts one, and the document's own\n * sync pass then resolves its fate against the server: 403 parks it (row 8),\n * a coded 404 destroys it (row 1), and a local-only orphan's create attempt\n * records a terminal failure row. Hidden document kinds stay excluded, and\n * dangling non-null projections (a container row merely missing locally)\n * stay with stale-root recovery, exactly as before.\n *\n * Organization neutrality: the null scope changes only the runtime's\n * containerId — auth, crypto, and organization plumbing are identical to\n * every container-scoped runtime this store already primes with, the sync\n * pass derives billing and keying organizations from the document's own\n * plan and manifest, and a cross-organization author fails closed at the\n * sync layer's identity guard before anything is signed.\n */\nconst ORPHANED_PRIME_TARGET_SQL = `\n  SELECT stored.local_id AS local_id, stored.document_id AS document_id\n  FROM documents stored\n  INNER JOIN document_projection projection\n    ON projection.local_id = stored.local_id\n  WHERE stored.app_kind = 'documents'\n    AND ${getOrphanedDocumentWhereSql({\n      documentIdSql: \"stored.document_id\",\n      projectionAlias: \"projection\",\n    })}\n  ORDER BY stored.local_id ASC\n`;\n\n/**\n * Unattributed rows (empty/NULL organization) are always included: they are\n * device-first documents created before authentication, which belong to this\n * device's sole user and adopt the active organization when they create.\n */\nasync function listOrphanedDocumentPrimeTargets(\n  runtime: ContainerDocumentQueriesRuntime,\n  organizationId: string,\n): Promise<ContainerContentsDocumentRuntimeTarget[]> {\n  await ensureSqlTables(runtime.infra.execSql, [\n    ...documentTables,\n    ...documentProjectionTables,\n    ...documentContainerProjectionTables,\n  ]);\n  const rows = await runtime.infra.execSql(\n    ORPHANED_PRIME_TARGET_SQL,\n    getOrphanedDocumentQueryBind(organizationId),\n  );\n  return rows.flatMap((row) => {\n    const localId = Reflect.get(row, \"local_id\");\n    if (typeof localId !== \"string\") {\n      return [];\n    }\n    const documentId = Reflect.get(row, \"document_id\");\n    return [\n      {\n        documentId: typeof documentId === \"string\" ? documentId : null,\n        localId,\n        runtimeContainerId: null,\n      },\n    ];\n  });\n}\n\nexport async function primeDocumentsForContainerSubtree<TRuntime>(input: {\n  containersById: ReadonlyMap<string, ContainerContentsContainerSubtreeState>;\n  host: ContainerDocumentPrimeHost<TRuntime>;\n  isCurrent?: (() => boolean) | undefined;\n  primeRequiredLocalIds?: ReadonlySet<string>;\n  rootContainerId: string;\n  runtime: ContainerDocumentQueriesRuntime;\n}): Promise<number> {\n  const isCurrent = input.isCurrent ?? (() => true);\n  if (!isCurrent()) return 0;\n  const [targets, primeRequiredLocalIds] = await Promise.all([\n    listDocumentRuntimeTargetsForContainerSubtreeFromRuntime({\n      containersById: input.containersById,\n      rootContainerId: input.rootContainerId,\n      runtime: input.runtime,\n    }),\n    input.primeRequiredLocalIds ??\n      listPrimeRequiredLocalIdsFromRuntime(input.runtime),\n  ]);\n  if (!isCurrent()) return 0;\n  const primed = await requestDocumentRuntimeTargetSync({\n    host: input.host,\n    isCurrent,\n    targets: targets.filter((target) =>\n      primeRequiredLocalIds.has(target.localId),\n    ),\n  });\n  return primed.size;\n}\n\nexport async function primeDocumentsForLoadedRoots<TRuntime>(input: {\n  containersById: ReadonlyMap<string, ContainerContentsContainerSubtreeState>;\n  host: ContainerDocumentPrimeHost<TRuntime>;\n  isCurrent?: (() => boolean) | undefined;\n  /**\n   * The store scope's organization. Orphan priming is bounded to it: each\n   * organization-scoped store resolves only its own orphans, matching the\n   * per-organization invariant subtree routing provides implicitly (a pass\n   * signed under another organization would fail the sync identity guard\n   * instead of resolving). Absent — unauthenticated or scope-less callers —\n   * orphan priming is skipped entirely.\n   */\n  organizationId?: string | null;\n  runtime: ContainerDocumentQueriesRuntime;\n}): Promise<LoadedRootDocumentPrimeResult> {\n  const isCurrent = input.isCurrent ?? (() => true);\n  if (!isCurrent()) {\n    return {\n      candidateCount: 0,\n      orphanPrimedCount: 0,\n      primedCount: 0,\n      rootCount: 0,\n      unroutableCount: 0,\n    };\n  }\n  const candidates = await listPrimeRequiredDocumentCandidatesFromRuntime(\n    input.runtime,\n  );\n  if (!isCurrent()) {\n    return {\n      candidateCount: candidates.length,\n      orphanPrimedCount: 0,\n      primedCount: 0,\n      rootCount: 0,\n      unroutableCount: candidates.length,\n    };\n  }\n  const rootContainerIds = Array.from(input.containersById.values()).flatMap(\n    (containerState) =>\n      containerState.container.parentId === null\n        ? [containerState.container.id]\n        : [],\n  );\n  const requiredLocalIds = new Set(\n    candidates.map((candidate) => candidate.localId),\n  );\n  const primedLocalIds = new Set<string>();\n\n  for (const rootContainerId of rootContainerIds) {\n    if (!isCurrent()) break;\n    const targets =\n      await listDocumentRuntimeTargetsForContainerSubtreeFromRuntime({\n        containersById: input.containersById,\n        rootContainerId,\n        runtime: input.runtime,\n      });\n    if (!isCurrent()) break;\n    const primed = await requestDocumentRuntimeTargetSync({\n      host: input.host,\n      isCurrent,\n      targets: targets.filter(\n        (target) =>\n          requiredLocalIds.has(target.localId) &&\n          !primedLocalIds.has(target.localId),\n      ),\n    });\n    for (const localId of primed) {\n      primedLocalIds.add(localId);\n    }\n  }\n\n  const orphanTargets = (\n    isCurrent() && input.organizationId\n      ? await listOrphanedDocumentPrimeTargets(\n          input.runtime,\n          input.organizationId,\n        )\n      : []\n  ).filter(\n    (target) =>\n      requiredLocalIds.has(target.localId) &&\n      !primedLocalIds.has(target.localId),\n  );\n  const orphanPrimed = await requestDocumentRuntimeTargetSync({\n    host: input.host,\n    isCurrent,\n    targets: isCurrent() ? orphanTargets : [],\n  });\n  for (const localId of orphanPrimed) {\n    primedLocalIds.add(localId);\n  }\n\n  return {\n    candidateCount: candidates.length,\n    orphanPrimedCount: orphanPrimed.size,\n    primedCount: primedLocalIds.size,\n    rootCount: rootContainerIds.length,\n    unroutableCount: candidates.filter(\n      (candidate) => !primedLocalIds.has(candidate.localId),\n    ).length,\n  };\n}\n"]}

package/workflows/container-contents/documentQueries/documentStructure.d.ts

@@ -0,0 +1,53 @@
+import type { DocumentSummary } from "../../../data/documents/documentSummary.js";
+import type { DocumentStructuralMutationHost, DocumentStructuralMutationRuntime, SetLinkedContainerIdsForDocument } from "./documentStructureTypes.js";
+export type { DocumentStructuralMutationHost, DocumentStructuralMutationRelinkInput, DocumentStructuralMutationRuntime, MergeDocumentSummary, SetLinkedContainerIdsForDocument, } from "./documentStructureTypes.js";
+export declare function canMutateDocumentLink(runtime: {
+    readonly auth: Pick<DocumentStructuralMutationRuntime["auth"], "isAuthenticated">;
+    readonly infra: Pick<DocumentStructuralMutationRuntime["infra"], "dbStatus">;
+    readonly state: Pick<DocumentStructuralMutationRuntime["state"], "online">;
+}): boolean;
+export declare function canMutateLocalDocumentLink(runtime: {
+    readonly infra: Pick<DocumentStructuralMutationRuntime["infra"], "dbStatus">;
+}): boolean;
+export declare function moveLocalDocumentLink<TRuntime>(params: {
+    expandNode: (nodeId: string) => void;
+    host: DocumentStructuralMutationHost<TRuntime>;
+    note: DocumentSummary;
+    runtime: DocumentStructuralMutationRuntime;
+    targetContainerId: string;
+}): Promise<DocumentSummary | null>;
+export declare function moveDocumentLink<TRuntime>(params: {
+    expandNode: (nodeId: string) => void;
+    host: DocumentStructuralMutationHost<TRuntime>;
+    note: DocumentSummary;
+    replaceLinkedContainers?: boolean | undefined;
+    runtime: DocumentStructuralMutationRuntime;
+    scheduleSync?: (() => void) | undefined;
+    setLinkedContainerIdsForDocument: SetLinkedContainerIdsForDocument;
+    targetContainerId: string;
+}): Promise<{
+    linksChanged: boolean;
+    note: DocumentSummary | null;
+}>;
+export declare function addDocumentLink<TRuntime>(params: {
+    host: DocumentStructuralMutationHost<TRuntime>;
+    note: DocumentSummary;
+    runtime: DocumentStructuralMutationRuntime;
+    scheduleSync?: (() => void) | undefined;
+    setLinkedContainerIdsForDocument: SetLinkedContainerIdsForDocument;
+    targetContainerId: string;
+}): Promise<DocumentSummary | null>;
+export declare function removeDocumentLink<TRuntime>(params: {
+    host: DocumentStructuralMutationHost<TRuntime>;
+    note: DocumentSummary;
+    removedContainerId: string;
+    runtime: DocumentStructuralMutationRuntime;
+    scheduleSync?: (() => void) | undefined;
+    setLinkedContainerIdsForDocument: SetLinkedContainerIdsForDocument;
+}): Promise<DocumentSummary | null>;
+export declare function activateDocumentLink<TRuntime>(params: {
+    host: DocumentStructuralMutationHost<TRuntime>;
+    note: DocumentSummary;
+    runtime: DocumentStructuralMutationRuntime;
+    targetContainerId: string;
+}): Promise<DocumentSummary | null>;