@tearleads/client-sdk 0.0.0-stage → 0.1.11

package/workflows/container-contents/staleRootRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleRootRecovery.js","sourceRoot":"","sources":["staleRootRecovery.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContainerContentsPersistence } from \"./containerPersistence\";\nimport type { ContainerState } from \"./remoteHydration\";\nimport { hasRemoteContainerMetadataState } from \"./remoteHydration/reconciliation\";\nimport type {\n  ContainerContentsRootAdopter,\n  ContainerContentsWorkflowRuntime,\n} from \"./runtime\";\n\nexport type StaleRootRecoveryStatus =\n  | \"already-adopted\"\n  | \"ambiguous\"\n  | \"context-changed\"\n  | \"not-needed\"\n  | \"reassigned\"\n  | \"unsupported\";\n\ninterface StaleRootRecoveryResult {\n  readonly candidateCount: number;\n  readonly reassigned: boolean;\n  readonly status: StaleRootRecoveryStatus;\n}\n\ninterface StaleRootRecoveryState {\n  readonly containersById: ReadonlyMap<string, ContainerState>;\n  readonly persistence: Pick<\n    ContainerContentsPersistence,\n    \"containerExists\" | \"reassignContainerDocuments\"\n  >;\n  readonly rootLaneHydrated: boolean;\n  readonly runtime: {\n    readonly adoptRootContainer?: ContainerContentsRootAdopter | undefined;\n    readonly auth: Pick<\n      ContainerContentsWorkflowRuntime[\"auth\"],\n      | \"defaultOrganizationId\"\n      | \"isAuthenticated\"\n      | \"organizationId\"\n      | \"userId\"\n      | \"rootContainerId\"\n    >;\n    readonly infra: Pick<ContainerContentsWorkflowRuntime[\"infra\"], \"execSql\">;\n    readonly state: Pick<\n      ContainerContentsWorkflowRuntime[\"state\"],\n      \"containerId\" | \"domainScope\"\n    >;\n  };\n}\n\nfunction hasSameRecoveryContext(\n  state: StaleRootRecoveryState,\n  input: {\n    domainScope: ContainerContentsWorkflowRuntime[\"state\"][\"domainScope\"];\n    defaultOrganizationId: string;\n    organizationId: string;\n    staleContainerId: string;\n    rootContainerId: string | null | undefined;\n    userId: string;\n  },\n): boolean {\n  return (\n    state.runtime.auth.isAuthenticated &&\n    state.runtime.auth.defaultOrganizationId === input.defaultOrganizationId &&\n    state.runtime.auth.organizationId === input.organizationId &&\n    state.runtime.auth.userId === input.userId &&\n    state.runtime.auth.rootContainerId === input.rootContainerId &&\n    state.runtime.state.containerId === input.staleContainerId &&\n    state.runtime.state.domainScope === input.domainScope\n  );\n}\n\nfunction listAuthoritativeRootCandidates(\n  state: StaleRootRecoveryState,\n  organizationId: string,\n): ContainerState[] {\n  return Array.from(state.containersById.values()).filter(\n    (containerState) =>\n      containerState.container.id === state.runtime.auth.rootContainerId &&\n      containerState.container.parentId === null &&\n      containerState.container.organizationId === organizationId &&\n      (containerState.container.systemSlot ?? null) === null &&\n      containerState.container.effectiveAccessLevel === \"admin\" &&\n      hasRemoteContainerMetadataState(containerState),\n  );\n}\n\n/**\n * Repairs the root identity left by a cold-cache login.\n *\n * Root reconciliation can delete the device-first local root without updating\n * the session's default container. Documents created afterward are projected\n * beneath that deleted id, so startup priming detects their writes but cannot\n * route them. Recovery is intentionally narrow: the stale id must be absent\n * from both the loaded topology and durable storage, and the active\n * organization must contain the session-acknowledged root after the root lane\n * has hydrated and verified its signed destination role. This recovery path only repairs document\n * references; structural container descendants remain owned by normal root\n * reconciliation. Durable reassignment deliberately precedes live session\n * adoption so consumers never observe the new root before its documents move.\n * If the live-session guard rejects that adoption, the idempotent reassignment\n * remains applied and the sync lane is re-armed to retry under the next runtime\n * snapshot.\n */\nexport async function recoverStaleSessionRoot(\n  state: StaleRootRecoveryState,\n  isCurrent: () => boolean = () => true,\n): Promise<StaleRootRecoveryResult> {\n  const staleContainerId = state.runtime.state.containerId;\n  const domainScope = state.runtime.state.domainScope;\n  const defaultOrganizationId = state.runtime.auth.defaultOrganizationId;\n  const organizationId = state.runtime.auth.organizationId;\n  const userId = state.runtime.auth.userId;\n  if (\n    !isCurrent() ||\n    !state.runtime.auth.isAuthenticated ||\n    !staleContainerId ||\n    !defaultOrganizationId ||\n    !organizationId ||\n    !userId ||\n    organizationId !== defaultOrganizationId ||\n    !state.rootLaneHydrated ||\n    state.containersById.has(staleContainerId)\n  ) {\n    return { candidateCount: 0, reassigned: false, status: \"not-needed\" };\n  }\n  const recoveryContext = {\n    domainScope,\n    defaultOrganizationId,\n    organizationId,\n    staleContainerId,\n    userId,\n    rootContainerId: state.runtime.auth.rootContainerId,\n  };\n\n  const storedContainerExists = await state.persistence.containerExists(\n    state.runtime.infra.execSql,\n    staleContainerId,\n  );\n  if (storedContainerExists) {\n    return { candidateCount: 0, reassigned: false, status: \"not-needed\" };\n  }\n  if (!isCurrent() || !hasSameRecoveryContext(state, recoveryContext)) {\n    return { candidateCount: 0, reassigned: false, status: \"context-changed\" };\n  }\n  if (state.containersById.has(staleContainerId)) {\n    return { candidateCount: 0, reassigned: false, status: \"not-needed\" };\n  }\n\n  const candidates = listAuthoritativeRootCandidates(\n    state,\n    defaultOrganizationId,\n  );\n  const [remoteRootState] = candidates;\n  if (!remoteRootState || candidates.length > 1) {\n    return {\n      candidateCount: candidates.length,\n      reassigned: false,\n      status: \"ambiguous\",\n    };\n  }\n  if (!state.runtime.adoptRootContainer) {\n    return { candidateCount: 1, reassigned: false, status: \"unsupported\" };\n  }\n  if (!isCurrent() || !hasSameRecoveryContext(state, recoveryContext)) {\n    return { candidateCount: 0, reassigned: false, status: \"context-changed\" };\n  }\n\n  await state.persistence.reassignContainerDocuments(\n    state.runtime.infra.execSql,\n    {\n      fromContainerId: staleContainerId,\n      stillCurrent: isCurrent,\n      toContainerId: remoteRootState.container.id,\n    },\n  );\n  if (!isCurrent() || !hasSameRecoveryContext(state, recoveryContext)) {\n    return { candidateCount: 1, reassigned: false, status: \"context-changed\" };\n  }\n  const adoptionResult = state.runtime.adoptRootContainer({\n    domainScope,\n    expectedContainerId: staleContainerId,\n    nextContainerId: remoteRootState.container.id,\n    organizationId,\n    userId,\n  });\n\n  return {\n    candidateCount: 1,\n    reassigned: true,\n    status:\n      adoptionResult === \"already-adopted\"\n        ? \"already-adopted\"\n        : adoptionResult\n          ? \"reassigned\"\n          : \"context-changed\",\n  };\n}\n"]}

package/workflows/container-contents/storedContainerState.js

@@ -0,0 +1,84 @@
+import { base64ToBytes, bytesToBase64 } from "../../internal/encoding/index.js";
+import { exportAllUpdates, importUpdates } from "../../internal/loro/index.js";
+import { createContainerMetadataDocument, getDefaultContainerName, readContainerMetadataValue, writeContainerMetadataValue, } from "../../data/containers/containerMetadataDocument.js";
+import { enqueuePendingContainerUpdate, } from "./containerPersistence.js";
+function createInitialContainerRecord(input) {
+    return {
+        accessEpoch: 1,
+        accessStateHash: null,
+        contentKeyBundle: null,
+        documentId: input.container.metadataDocumentId,
+        documentKekTargets: null,
+        documentManifestBundle: null,
+        id: input.container.id,
+        lastCommitLsn: null,
+        metadataUpdates: input.metadataUpdates,
+        snapshotEndVersion: "",
+    };
+}
+function metadataProjectionChanged(left, right) {
+    return left.icon !== right.icon || left.name !== right.name;
+}
+function replaySaveOptions(container) {
+    const localUpdatedAt = container.localUpdatedAt ?? container.updatedAt ?? null;
+    return localUpdatedAt ? { localUpdatedAt } : undefined;
+}
+export async function hydrateStoredContainerState(input) {
+    const { execSql, persistence, storedContainer } = input;
+    const { container } = storedContainer;
+    const doc = await createContainerMetadataDocument(container.id);
+    let nextContainer = container;
+    let nextRecord = storedContainer.record;
+    if (nextRecord?.metadataUpdates) {
+        importUpdates(doc, [base64ToBytes(nextRecord.metadataUpdates)]);
+        const metadata = readContainerMetadataValue(doc, getDefaultContainerName(container.parentId));
+        nextContainer = {
+            ...container,
+            icon: metadata.icon,
+            name: metadata.name,
+        };
+        if (metadataProjectionChanged(container, nextContainer)) {
+            await persistence.saveContainer(execSql, nextContainer, nextRecord, replaySaveOptions(container));
+        }
+    }
+    else {
+        writeContainerMetadataValue(doc, {
+            icon: container.icon,
+            name: container.name,
+        });
+        const initialUpdate = exportAllUpdates(doc);
+        nextRecord = createInitialContainerRecord({
+            container,
+            metadataUpdates: bytesToBase64(initialUpdate),
+        });
+        await persistence.saveContainer(execSql, nextContainer, nextRecord);
+        if (!container.metadataDocumentId) {
+            await enqueuePendingContainerUpdate(execSql, persistence, {
+                containerId: container.id,
+                update: initialUpdate,
+            });
+        }
+    }
+    return { container: nextContainer, doc, record: nextRecord };
+}
+/** Materialize a CAS winner without writing repair rows from a stale caller. */
+export async function materializeStoredContainerStateReadOnly(input) {
+    const { container, record } = input.storedContainer;
+    if (!record)
+        return null;
+    const doc = await createContainerMetadataDocument(container.id);
+    let nextContainer = container;
+    if (record.metadataUpdates) {
+        importUpdates(doc, [base64ToBytes(record.metadataUpdates)]);
+        const metadata = readContainerMetadataValue(doc, getDefaultContainerName(container.parentId));
+        nextContainer = { ...container, icon: metadata.icon, name: metadata.name };
+    }
+    else {
+        writeContainerMetadataValue(doc, {
+            icon: container.icon,
+            name: container.name,
+        });
+    }
+    return { container: nextContainer, doc, record };
+}
+//# sourceMappingURL=storedContainerState.js.map

package/workflows/container-contents/storedContainerState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storedContainerState.js","sourceRoot":"","sources":["storedContainerState.ts"],"names":[],"mappings":"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","sourcesContent":["import { base64ToBytes, bytesToBase64 } from \"@tearleads/encoding\";\nimport { exportAllUpdates, importUpdates } from \"@tearleads/loro\";\nimport {\n  createContainerMetadataDocument,\n  getDefaultContainerName,\n  readContainerMetadataValue,\n  writeContainerMetadataValue,\n} from \"../../data/containers/containerMetadataDocument\";\nimport type { ExecSql } from \"../../data/sqlite/sqlSchema\";\nimport {\n  type ContainerContentsPersistence,\n  type ContainerMetadataRecord,\n  enqueuePendingContainerUpdate,\n  type StoredContainerState,\n} from \"./containerPersistence\";\nimport type { ContainerState } from \"./remoteHydration/types\";\n\ntype SaveContainerOptions = Parameters<\n  ContainerContentsPersistence[\"saveContainer\"]\n>[3];\n\nfunction createInitialContainerRecord(input: {\n  container: StoredContainerState[\"container\"];\n  metadataUpdates: string;\n}): ContainerMetadataRecord {\n  return {\n    accessEpoch: 1,\n    accessStateHash: null,\n    contentKeyBundle: null,\n    documentId: input.container.metadataDocumentId,\n    documentKekTargets: null,\n    documentManifestBundle: null,\n    id: input.container.id,\n    lastCommitLsn: null,\n    metadataUpdates: input.metadataUpdates,\n    snapshotEndVersion: \"\",\n  };\n}\n\nfunction metadataProjectionChanged(\n  left: StoredContainerState[\"container\"],\n  right: StoredContainerState[\"container\"],\n): boolean {\n  return left.icon !== right.icon || left.name !== right.name;\n}\n\nfunction replaySaveOptions(\n  container: StoredContainerState[\"container\"],\n): SaveContainerOptions {\n  const localUpdatedAt =\n    container.localUpdatedAt ?? container.updatedAt ?? null;\n  return localUpdatedAt ? { localUpdatedAt } : undefined;\n}\n\nexport async function hydrateStoredContainerState(input: {\n  execSql: ExecSql;\n  persistence: ContainerContentsPersistence;\n  storedContainer: StoredContainerState;\n}): Promise<ContainerState> {\n  const { execSql, persistence, storedContainer } = input;\n  const { container } = storedContainer;\n  const doc = await createContainerMetadataDocument(container.id);\n  let nextContainer = container;\n  let nextRecord = storedContainer.record;\n\n  if (nextRecord?.metadataUpdates) {\n    importUpdates(doc, [base64ToBytes(nextRecord.metadataUpdates)]);\n    const metadata = readContainerMetadataValue(\n      doc,\n      getDefaultContainerName(container.parentId),\n    );\n    nextContainer = {\n      ...container,\n      icon: metadata.icon,\n      name: metadata.name,\n    };\n    if (metadataProjectionChanged(container, nextContainer)) {\n      await persistence.saveContainer(\n        execSql,\n        nextContainer,\n        nextRecord,\n        replaySaveOptions(container),\n      );\n    }\n  } else {\n    writeContainerMetadataValue(doc, {\n      icon: container.icon,\n      name: container.name,\n    });\n    const initialUpdate = exportAllUpdates(doc);\n    nextRecord = createInitialContainerRecord({\n      container,\n      metadataUpdates: bytesToBase64(initialUpdate),\n    });\n    await persistence.saveContainer(execSql, nextContainer, nextRecord);\n\n    if (!container.metadataDocumentId) {\n      await enqueuePendingContainerUpdate(execSql, persistence, {\n        containerId: container.id,\n        update: initialUpdate,\n      });\n    }\n  }\n\n  return { container: nextContainer, doc, record: nextRecord };\n}\n\n/** Materialize a CAS winner without writing repair rows from a stale caller. */\nexport async function materializeStoredContainerStateReadOnly(input: {\n  storedContainer: StoredContainerState;\n}): Promise<ContainerState | null> {\n  const { container, record } = input.storedContainer;\n  if (!record) return null;\n  const doc = await createContainerMetadataDocument(container.id);\n  let nextContainer = container;\n  if (record.metadataUpdates) {\n    importUpdates(doc, [base64ToBytes(record.metadataUpdates)]);\n    const metadata = readContainerMetadataValue(\n      doc,\n      getDefaultContainerName(container.parentId),\n    );\n    nextContainer = { ...container, icon: metadata.icon, name: metadata.name };\n  } else {\n    writeContainerMetadataValue(doc, {\n      icon: container.icon,\n      name: container.name,\n    });\n  }\n  return { container: nextContainer, doc, record };\n}\n"]}

package/workflows/container-contents/syncLane.d.ts

@@ -0,0 +1,12 @@
+import type { DomainScope } from "../../data/domainScope.js";
+import { type SyncLane } from "../../data/sync/syncCoordinator.js";
+export { sequenceUnchanged } from "../../data/sync/sequence.js";
+export { didRegainSyncPrerequisites, isDatabaseUnavailableError, } from "../../data/sync/syncCoordinator.js";
+export type ContainerContentsSyncLane = SyncLane;
+export declare const CONTAINER_CONTENTS_SYNC_LANE_KEY = "container-contents";
+export declare function registerContainerContentsSyncLane(input: {
+    readonly domainScope: DomainScope;
+    /** Host diagnostics sink; bare runtimes do not structure errors. */
+    readonly logError?: ((message: string, error: unknown) => void) | undefined;
+    readonly run: () => Promise<void>;
+}): ContainerContentsSyncLane;

package/workflows/container-contents/syncLane.js

@@ -0,0 +1,20 @@
+import { getOrCreateDomainSyncCoordinator, isDatabaseUnavailableError, } from "../../data/sync/syncCoordinator.js";
+export { sequenceUnchanged } from "../../data/sync/sequence.js";
+// Facade re-exports: container-contents stores must reach these shared sync
+// helpers through this workflow boundary, not by importing data/sync directly.
+export { didRegainSyncPrerequisites, isDatabaseUnavailableError, } from "../../data/sync/syncCoordinator.js";
+export const CONTAINER_CONTENTS_SYNC_LANE_KEY = "container-contents";
+export function registerContainerContentsSyncLane(input) {
+    return getOrCreateDomainSyncCoordinator(input.domainScope).registerLane(CONTAINER_CONTENTS_SYNC_LANE_KEY, {
+        label: "Container contents",
+        phase: "structural",
+        // Fixed literal: no container or identity id may reach a report. The
+        // mapped stack identifies which lane body threw. Returning the host's
+        // result hands a rejection to the lane reporter's wrapper; discarding it
+        // would surface as an unhandled rejection instead.
+        reportUnexpectedError: (error) => input.logError?.("Container contents: sync lane failed", error),
+        run: input.run,
+        shouldIgnoreError: isDatabaseUnavailableError,
+    });
+}
+//# sourceMappingURL=syncLane.js.map

package/workflows/container-contents/syncLane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncLane.js","sourceRoot":"","sources":["syncLane.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gCAAgC,EAChC,0BAA0B,GAE3B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC;AAGzC,MAAM,CAAC,MAAM,gCAAgC,GAAG,oBAAoB,CAAC;AAErE,MAAM,UAAU,iCAAiC,CAAC,KAKjD;IACC,OAAO,gCAAgC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,YAAY,CACrE,gCAAgC,EAChC;QACE,KAAK,EAAE,oBAAoB;QAC3B,KAAK,EAAE,YAAY;QACnB,qEAAqE;QACrE,sEAAsE;QACtE,yEAAyE;QACzE,mDAAmD;QACnD,qBAAqB,EAAE,CAAC,KAAK,EAAE,EAAE,CAC/B,KAAK,CAAC,QAAQ,EAAE,CAAC,sCAAsC,EAAE,KAAK,CAAC;QACjE,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,iBAAiB,EAAE,0BAA0B;KAC9C,CACF,CAAC;AACJ,CAAC","sourcesContent":["import type { DomainScope } from \"../../data/domainScope\";\nimport {\n  getOrCreateDomainSyncCoordinator,\n  isDatabaseUnavailableError,\n  type SyncLane,\n} from \"../../data/sync/syncCoordinator\";\n\nexport { sequenceUnchanged } from \"../../data/sync/sequence\";\n// Facade re-exports: container-contents stores must reach these shared sync\n// helpers through this workflow boundary, not by importing data/sync directly.\nexport {\n  didRegainSyncPrerequisites,\n  isDatabaseUnavailableError,\n} from \"../../data/sync/syncCoordinator\";\n\nexport type ContainerContentsSyncLane = SyncLane;\nexport const CONTAINER_CONTENTS_SYNC_LANE_KEY = \"container-contents\";\n\nexport function registerContainerContentsSyncLane(input: {\n  readonly domainScope: DomainScope;\n  /** Host diagnostics sink; bare runtimes do not structure errors. */\n  readonly logError?: ((message: string, error: unknown) => void) | undefined;\n  readonly run: () => Promise<void>;\n}): ContainerContentsSyncLane {\n  return getOrCreateDomainSyncCoordinator(input.domainScope).registerLane(\n    CONTAINER_CONTENTS_SYNC_LANE_KEY,\n    {\n      label: \"Container contents\",\n      phase: \"structural\",\n      // Fixed literal: no container or identity id may reach a report. The\n      // mapped stack identifies which lane body threw. Returning the host's\n      // result hands a rejection to the lane reporter's wrapper; discarding it\n      // would surface as an unhandled rejection instead.\n      reportUnexpectedError: (error) =>\n        input.logError?.(\"Container contents: sync lane failed\", error),\n      run: input.run,\n      shouldIgnoreError: isDatabaseUnavailableError,\n    },\n  );\n}\n"]}

package/workflows/container-contents/syncState.d.ts

@@ -0,0 +1,16 @@
+export type ContainerDocumentObjectSyncStatus = "synced" | "local-only" | "pending" | "error";
+export interface ContainerDocumentObjectSyncState {
+    lastError: string | null;
+    pendingAttachmentBytes: number;
+    pendingAttachmentCount: number;
+    pendingUpdateCount: number;
+    status: ContainerDocumentObjectSyncStatus;
+}
+export declare const syncedContainerDocumentObjectSyncState: ContainerDocumentObjectSyncState;
+export declare function createContainerDocumentObjectSyncState(input: {
+    lastError?: string | null | undefined;
+    localOnly?: boolean | undefined;
+    pendingAttachmentBytes?: number | null | undefined;
+    pendingAttachmentCount?: number | null | undefined;
+    pendingUpdateCount?: number | null | undefined;
+}): ContainerDocumentObjectSyncState;

package/workflows/container-contents/syncState.js

@@ -0,0 +1,28 @@
+export const syncedContainerDocumentObjectSyncState = {
+    lastError: null,
+    pendingAttachmentBytes: 0,
+    pendingAttachmentCount: 0,
+    pendingUpdateCount: 0,
+    status: "synced",
+};
+export function createContainerDocumentObjectSyncState(input) {
+    const lastError = input.lastError ?? null;
+    const pendingAttachmentBytes = input.pendingAttachmentBytes ?? 0;
+    const pendingAttachmentCount = input.pendingAttachmentCount ?? 0;
+    const pendingUpdateCount = input.pendingUpdateCount ?? 0;
+    if (!lastError &&
+        !input.localOnly &&
+        pendingAttachmentBytes === 0 &&
+        pendingAttachmentCount === 0 &&
+        pendingUpdateCount === 0) {
+        return syncedContainerDocumentObjectSyncState;
+    }
+    return {
+        lastError,
+        pendingAttachmentBytes,
+        pendingAttachmentCount,
+        pendingUpdateCount,
+        status: lastError ? "error" : input.localOnly ? "local-only" : "pending",
+    };
+}
+//# sourceMappingURL=syncState.js.map

package/workflows/container-contents/syncState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncState.js","sourceRoot":"","sources":["syncState.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,sCAAsC,GACjD;IACE,SAAS,EAAE,IAAI;IACf,sBAAsB,EAAE,CAAC;IACzB,sBAAsB,EAAE,CAAC;IACzB,kBAAkB,EAAE,CAAC;IACrB,MAAM,EAAE,QAAQ;CACjB,CAAC;AAEJ,MAAM,UAAU,sCAAsC,CAAC,KAMtD;IACC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,IAAI,CAAC;IAC1C,MAAM,sBAAsB,GAAG,KAAK,CAAC,sBAAsB,IAAI,CAAC,CAAC;IACjE,MAAM,sBAAsB,GAAG,KAAK,CAAC,sBAAsB,IAAI,CAAC,CAAC;IACjE,MAAM,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,IAAI,CAAC,CAAC;IAEzD,IACE,CAAC,SAAS;QACV,CAAC,KAAK,CAAC,SAAS;QAChB,sBAAsB,KAAK,CAAC;QAC5B,sBAAsB,KAAK,CAAC;QAC5B,kBAAkB,KAAK,CAAC,EACxB,CAAC;QACD,OAAO,sCAAsC,CAAC;IAChD,CAAC;IAED,OAAO;QACL,SAAS;QACT,sBAAsB;QACtB,sBAAsB;QACtB,kBAAkB;QAClB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;KACzE,CAAC;AACJ,CAAC","sourcesContent":["export type ContainerDocumentObjectSyncStatus =\n  | \"synced\"\n  | \"local-only\"\n  | \"pending\"\n  | \"error\";\n\nexport interface ContainerDocumentObjectSyncState {\n  lastError: string | null;\n  pendingAttachmentBytes: number;\n  pendingAttachmentCount: number;\n  pendingUpdateCount: number;\n  status: ContainerDocumentObjectSyncStatus;\n}\n\nexport const syncedContainerDocumentObjectSyncState: ContainerDocumentObjectSyncState =\n  {\n    lastError: null,\n    pendingAttachmentBytes: 0,\n    pendingAttachmentCount: 0,\n    pendingUpdateCount: 0,\n    status: \"synced\",\n  };\n\nexport function createContainerDocumentObjectSyncState(input: {\n  lastError?: string | null | undefined;\n  localOnly?: boolean | undefined;\n  pendingAttachmentBytes?: number | null | undefined;\n  pendingAttachmentCount?: number | null | undefined;\n  pendingUpdateCount?: number | null | undefined;\n}): ContainerDocumentObjectSyncState {\n  const lastError = input.lastError ?? null;\n  const pendingAttachmentBytes = input.pendingAttachmentBytes ?? 0;\n  const pendingAttachmentCount = input.pendingAttachmentCount ?? 0;\n  const pendingUpdateCount = input.pendingUpdateCount ?? 0;\n\n  if (\n    !lastError &&\n    !input.localOnly &&\n    pendingAttachmentBytes === 0 &&\n    pendingAttachmentCount === 0 &&\n    pendingUpdateCount === 0\n  ) {\n    return syncedContainerDocumentObjectSyncState;\n  }\n\n  return {\n    lastError,\n    pendingAttachmentBytes,\n    pendingAttachmentCount,\n    pendingUpdateCount,\n    status: lastError ? \"error\" : input.localOnly ? \"local-only\" : \"pending\",\n  };\n}\n"]}

package/workflows/container-contents/systemSlot.d.ts

@@ -0,0 +1,11 @@
+import { type ContainerSystemSlot } from "../../internal/validators/containerSystemSlot.js";
+export interface ContainerSystemSlotDefinition {
+    readonly namespace: string;
+    readonly projectorId?: string | undefined;
+    readonly slotId: string;
+    readonly version: number;
+}
+export declare function deriveContainerSystemSlot(input: {
+    readonly definition: ContainerSystemSlotDefinition;
+    readonly secretKey: Uint8Array;
+}): Promise<ContainerSystemSlot>;

package/workflows/container-contents/systemSlot.js

@@ -0,0 +1,19 @@
+import { formatContainerSystemSlot, } from "../../internal/validators/containerSystemSlot.js";
+const CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM = {
+    hash: "SHA-256",
+    name: "HMAC",
+};
+function systemSlotDerivationLabel(definition) {
+    return JSON.stringify({
+        namespace: definition.namespace,
+        projectorId: definition.projectorId ?? null,
+        slotId: definition.slotId,
+        version: definition.version,
+    });
+}
+export async function deriveContainerSystemSlot(input) {
+    const hmacKey = await crypto.subtle.importKey("raw", input.secretKey.slice(), CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM, false, ["sign"]);
+    const digest = await crypto.subtle.sign(CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM, hmacKey, new TextEncoder().encode(systemSlotDerivationLabel(input.definition)));
+    return formatContainerSystemSlot(new Uint8Array(digest));
+}
+//# sourceMappingURL=systemSlot.js.map

package/workflows/container-contents/systemSlot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemSlot.js","sourceRoot":"","sources":["systemSlot.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,yBAAyB,GAC1B,MAAM,2CAA2C,CAAC;AAEnD,MAAM,oCAAoC,GAAG;IAC3C,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,MAAM;CACJ,CAAC;AASX,SAAS,yBAAyB,CAChC,UAAyC;IAEzC,OAAO,IAAI,CAAC,SAAS,CAAC;QACpB,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,WAAW,EAAE,UAAU,CAAC,WAAW,IAAI,IAAI;QAC3C,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,OAAO,EAAE,UAAU,CAAC,OAAO;KAC5B,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,KAG/C;IACC,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CAC3C,KAAK,EACL,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,EACvB,oCAAoC,EACpC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CACrC,oCAAoC,EACpC,OAAO,EACP,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,yBAAyB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CACtE,CAAC;IAEF,OAAO,yBAAyB,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3D,CAAC","sourcesContent":["import {\n  type ContainerSystemSlot,\n  formatContainerSystemSlot,\n} from \"@tearleads/validators/containerSystemSlot\";\n\nconst CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM = {\n  hash: \"SHA-256\",\n  name: \"HMAC\",\n} as const;\n\nexport interface ContainerSystemSlotDefinition {\n  readonly namespace: string;\n  readonly projectorId?: string | undefined;\n  readonly slotId: string;\n  readonly version: number;\n}\n\nfunction systemSlotDerivationLabel(\n  definition: ContainerSystemSlotDefinition,\n): string {\n  return JSON.stringify({\n    namespace: definition.namespace,\n    projectorId: definition.projectorId ?? null,\n    slotId: definition.slotId,\n    version: definition.version,\n  });\n}\n\nexport async function deriveContainerSystemSlot(input: {\n  readonly definition: ContainerSystemSlotDefinition;\n  readonly secretKey: Uint8Array;\n}): Promise<ContainerSystemSlot> {\n  const hmacKey = await crypto.subtle.importKey(\n    \"raw\",\n    input.secretKey.slice(),\n    CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM,\n    false,\n    [\"sign\"],\n  );\n  const digest = await crypto.subtle.sign(\n    CONTAINER_SYSTEM_SLOT_HMAC_ALGORITHM,\n    hmacKey,\n    new TextEncoder().encode(systemSlotDerivationLabel(input.definition)),\n  );\n\n  return formatContainerSystemSlot(new Uint8Array(digest));\n}\n"]}

package/workflows/containers/child/carriedDescendantRekeys.js

@@ -0,0 +1,118 @@
+import { MAX_ROTATION_CONTAINER_REKEYS } from "../../../internal/validators/util/index.js";
+import { verifyContainerWriterProjection, } from "../../../data/keyingProjectionVerification.js";
+import { buildMaterializedContainerRekeyPlan } from "./rekey.js";
+import { rebaseContainerWriterProjection } from "./rekeyProjection.js";
+/**
+ * Re-root a served projection on the deepest not-yet-accepted proper ancestor
+ * among `speculativePaths`. Each carried plan's own path was built the same
+ * way, so the deepest one already holds every speculative level above it. The
+ * container's own path, when the batch rotates it too, is not an ancestor: the
+ * caller is re-planning that rotation, and it extends what sits above.
+ */
+export function rebaseOnDeepestAncestor(served, speculativePaths) {
+    let deepest = null;
+    let deepestIndex = -1;
+    for (const speculative of speculativePaths) {
+        const containerId = speculative.containerKeks.at(-1)?.containerId;
+        if (containerId === served.containerId)
+            continue;
+        const index = served.containerKeks.findIndex((kek) => kek.containerId === containerId);
+        if (index > deepestIndex) {
+            deepest = speculative;
+            deepestIndex = index;
+        }
+    }
+    if (!deepest)
+        return null;
+    const projection = rebaseContainerWriterProjection(served, deepest);
+    return projection ? { ancestor: deepest, projection } : null;
+}
+/**
+ * Sign one carried rekey against the path its batch will leave behind. The
+ * served projection is fetched by the caller; here it is verified, must sit
+ * below one of the rotated containers and in that container's organization,
+ * and is signed only if this signer holds its key and write access — which a
+ * member able to rotate the ancestor always does, since both inherit downward.
+ */
+export async function planCarriedDescendantRekey(input) {
+    // Pin the served head before signing beyond it. The batch is acknowledged
+    // against the latest durable pin, and a carried rekey is always past epoch
+    // 1, so a device that never pinned this container would otherwise reject
+    // its own batch after the server had committed it.
+    await verifyContainerWriterProjection({
+        execSql: input.execSql,
+        principalPolicyCache: input.principalPolicyCache,
+        projection: input.served,
+        resolveUserKey: input.resolveProjectionUserKey,
+        stillCurrent: input.stillCurrent,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+    });
+    const rebased = rebaseOnDeepestAncestor(input.served, input.rotated);
+    if (!rebased) {
+        throw new Error("Carried descendant rekey is not below the rotated container");
+    }
+    // A batch locks whatever organizations it names, so the server holds each
+    // to the rule on its own; a carried rekey belongs to the rotation it rides.
+    if (input.served.organizationId !== rebased.ancestor.organizationId) {
+        throw new Error("Carried descendant rekey is outside the rotated container's organization");
+    }
+    return buildMaterializedContainerRekeyPlan({
+        author: {
+            ...input.author,
+            organizationId: rebased.ancestor.organizationId,
+        },
+        execSql: input.execSql,
+        knownContainerKeks: input.knownContainerKeks,
+        // Nothing here is acknowledged yet: pins move only with the batch.
+        persistVerificationCheckpoints: false,
+        previousProjection: rebased.projection,
+        principalPolicyCache: input.principalPolicyCache,
+        replacementPrincipalPolicy: input.replacementPrincipalPolicy,
+        resolveProjectionUserKey: input.resolveProjectionUserKey,
+        stillCurrent: input.stillCurrent,
+        targetSecretKey: input.targetSecretKey,
+        warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,
+    });
+}
+/**
+ * Sign the descendant rekeys a rotation must commit with (#2340). The server
+ * refuses a rotation that would leave a level above a directly granted
+ * container pinned to a retired epoch, because the grantee could never re-key
+ * that level itself and its writes would wait on another device. It names the
+ * levels; this signs them, parent-first, each against the path the batch will
+ * leave behind rather than the one currently served.
+ *
+ * `requiredContainerIds` is a hint, never an authority: each container is
+ * fetched and verified here, and refused unless it sits below a rotation.
+ */
+export async function planCarriedDescendantRekeys(input) {
+    const plans = [];
+    const speculativePaths = [...input.rotated];
+    const knownContainerKeks = new Map(input.knownContainerKeks);
+    const planned = new Set();
+    for (const containerId of input.requiredContainerIds) {
+        if (plans.length >= MAX_ROTATION_CONTAINER_REKEYS)
+            break;
+        if (planned.has(containerId))
+            continue;
+        const served = await input.apiClient.getContainerWriterProjection(containerId);
+        if (!served) {
+            throw new Error("Carried descendant rekey projection is unavailable");
+        }
+        if (served.containerId !== containerId) {
+            throw new Error("Carried descendant rekey targets another container");
+        }
+        const plan = await planCarriedDescendantRekey({
+            ...input,
+            knownContainerKeks,
+            rotated: speculativePaths,
+            served,
+        });
+        planned.add(containerId);
+        plans.push(plan);
+        speculativePaths.push(plan.writerProjection);
+        knownContainerKeks.set(plan.plan.containerKeyEpochId, plan.containerKey);
+    }
+    return plans;
+}
+//# sourceMappingURL=carriedDescendantRekeys.js.map

package/workflows/containers/child/carriedDescendantRekeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"carriedDescendantRekeys.js","sourceRoot":"","sources":["carriedDescendantRekeys.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAM3E,OAAO,EAIL,+BAA+B,GAChC,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EAAE,mCAAmC,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC;AAkCpE;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAyC,EACzC,gBAA4C;IAK5C,IAAI,OAAO,GAA2B,IAAI,CAAC;IAC3C,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,KAAK,MAAM,WAAW,IAAI,gBAAgB,EAAE,CAAC;QAC3C,MAAM,WAAW,GAAG,WAAW,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC;QAClE,IAAI,WAAW,KAAK,MAAM,CAAC,WAAW;YAAE,SAAS;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,CAC1C,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,KAAK,WAAW,CACzC,CAAC;QACF,IAAI,KAAK,GAAG,YAAY,EAAE,CAAC;YACzB,OAAO,GAAG,WAAW,CAAC;YACtB,YAAY,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IACD,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,UAAU,GAAG,+BAA+B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpE,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,KAGC;IAED,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,mDAAmD;IACnD,MAAM,+BAA+B,CAAC;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;QAChD,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,cAAc,EAAE,KAAK,CAAC,wBAAwB;QAC9C,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,+BAA+B,EAAE,KAAK,CAAC,+BAA+B;KACvE,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,uBAAuB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,4EAA4E;IAC5E,IAAI,KAAK,CAAC,MAAM,CAAC,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,cAAc,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;IACJ,CAAC;IACD,OAAO,mCAAmC,CAAC;QACzC,MAAM,EAAE;YACN,GAAG,KAAK,CAAC,MAAM;YACf,cAAc,EAAE,OAAO,CAAC,QAAQ,CAAC,cAAc;SAChD;QACD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,kBAAkB,EAAE,KAAK,CAAC,kBAAkB;QAC5C,mEAAmE;QACnE,8BAA8B,EAAE,KAAK;QACrC,kBAAkB,EAAE,OAAO,CAAC,UAAU;QACtC,oBAAoB,EAAE,KAAK,CAAC,oBAAoB;QAChD,0BAA0B,EAAE,KAAK,CAAC,0BAA0B;QAC5D,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,+BAA+B,EAAE,KAAK,CAAC,+BAA+B;KACvE,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,KAIC;IAED,MAAM,KAAK,GAAqC,EAAE,CAAC;IACnD,MAAM,gBAAgB,GAAsB,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/D,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,WAAW,IAAI,KAAK,CAAC,oBAAoB,EAAE,CAAC;QACrD,IAAI,KAAK,CAAC,MAAM,IAAI,6BAA6B;YAAE,MAAM;QACzD,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,SAAS;QACvC,MAAM,MAAM,GACV,MAAM,KAAK,CAAC,SAAS,CAAC,4BAA4B,CAAC,WAAW,CAAC,CAAC;QAClE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,IAAI,MAAM,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,0BAA0B,CAAC;YAC5C,GAAG,KAAK;YACR,kBAAkB;YAClB,OAAO,EAAE,gBAAgB;YACzB,MAAM;SACP,CAAC,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7C,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { VerifiedPrincipalPolicy } from \"@tearleads/crypto\";\nimport type { ContainerWriterProjectionResponse } from \"@tearleads/validators/response\";\nimport { MAX_ROTATION_CONTAINER_REKEYS } from \"@tearleads/validators/util\";\nimport type {\n  ContainerMutationAuthor,\n  ContainerRekeyApi,\n  MaterializedContainerRekeyPlan,\n} from \"../../../data/containers/shared/types\";\nimport {\n  type PrincipalPolicyCache,\n  type ProjectionUserKeyResolver,\n  type ReferencedPrincipalPolicyWarmer,\n  verifyContainerWriterProjection,\n} from \"../../../data/keyingProjectionVerification\";\nimport type { ExecSql } from \"../../../data/sqlite/sqlSchema\";\nimport { buildMaterializedContainerRekeyPlan } from \"./rekey\";\nimport { rebaseContainerWriterProjection } from \"./rekeyProjection\";\n\n/** What a rotation needs in hand to sign the descendant rekeys it must carry. */\nexport interface CarriedRekeyPlanningInput {\n  readonly apiClient: Pick<ContainerRekeyApi, \"getContainerWriterProjection\">;\n  readonly author: ContainerMutationAuthor;\n  readonly execSql: ExecSql;\n  /**\n   * Keys the batch minted and has yet to commit, by epoch id. A rotation's\n   * successor is wrapped to recipients at heads the batch itself commits, so\n   * no wrap on a re-rooted path opens it for the signer before then; the key\n   * the signer just minted does, and its keyring then opens what sits below.\n   */\n  readonly knownContainerKeks?: ReadonlyMap<string, Uint8Array> | undefined;\n  /**\n   * Verified policies the batch itself commits, which the rebased paths cite\n   * before any store holds them; and the one each carried rekey cites anew.\n   */\n  readonly principalPolicyCache?: PrincipalPolicyCache | undefined;\n  readonly replacementPrincipalPolicy?: VerifiedPrincipalPolicy | undefined;\n  readonly resolveProjectionUserKey: ProjectionUserKeyResolver;\n  readonly stillCurrent?: (() => boolean) | undefined;\n  readonly targetSecretKey: Uint8Array;\n  readonly warmReferencedPrincipalPolicies?:\n    | ReferencedPrincipalPolicyWarmer\n    | undefined;\n}\n\n/** A rotated container's own path once its batch is accepted. */\nexport type SpeculativePath = Pick<\n  ContainerWriterProjectionResponse,\n  \"containerKeks\" | \"organizationId\" | \"path\" | \"policyEvidence\"\n>;\n\n/**\n * Re-root a served projection on the deepest not-yet-accepted proper ancestor\n * among `speculativePaths`. Each carried plan's own path was built the same\n * way, so the deepest one already holds every speculative level above it. The\n * container's own path, when the batch rotates it too, is not an ancestor: the\n * caller is re-planning that rotation, and it extends what sits above.\n */\nexport function rebaseOnDeepestAncestor(\n  served: ContainerWriterProjectionResponse,\n  speculativePaths: readonly SpeculativePath[],\n): {\n  ancestor: SpeculativePath;\n  projection: ContainerWriterProjectionResponse;\n} | null {\n  let deepest: SpeculativePath | null = null;\n  let deepestIndex = -1;\n  for (const speculative of speculativePaths) {\n    const containerId = speculative.containerKeks.at(-1)?.containerId;\n    if (containerId === served.containerId) continue;\n    const index = served.containerKeks.findIndex(\n      (kek) => kek.containerId === containerId,\n    );\n    if (index > deepestIndex) {\n      deepest = speculative;\n      deepestIndex = index;\n    }\n  }\n  if (!deepest) return null;\n  const projection = rebaseContainerWriterProjection(served, deepest);\n  return projection ? { ancestor: deepest, projection } : null;\n}\n\n/**\n * Sign one carried rekey against the path its batch will leave behind. The\n * served projection is fetched by the caller; here it is verified, must sit\n * below one of the rotated containers and in that container's organization,\n * and is signed only if this signer holds its key and write access — which a\n * member able to rotate the ancestor always does, since both inherit downward.\n */\nexport async function planCarriedDescendantRekey(\n  input: CarriedRekeyPlanningInput & {\n    readonly rotated: readonly SpeculativePath[];\n    readonly served: ContainerWriterProjectionResponse;\n  },\n): Promise<MaterializedContainerRekeyPlan> {\n  // Pin the served head before signing beyond it. The batch is acknowledged\n  // against the latest durable pin, and a carried rekey is always past epoch\n  // 1, so a device that never pinned this container would otherwise reject\n  // its own batch after the server had committed it.\n  await verifyContainerWriterProjection({\n    execSql: input.execSql,\n    principalPolicyCache: input.principalPolicyCache,\n    projection: input.served,\n    resolveUserKey: input.resolveProjectionUserKey,\n    stillCurrent: input.stillCurrent,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n  });\n  const rebased = rebaseOnDeepestAncestor(input.served, input.rotated);\n  if (!rebased) {\n    throw new Error(\n      \"Carried descendant rekey is not below the rotated container\",\n    );\n  }\n  // A batch locks whatever organizations it names, so the server holds each\n  // to the rule on its own; a carried rekey belongs to the rotation it rides.\n  if (input.served.organizationId !== rebased.ancestor.organizationId) {\n    throw new Error(\n      \"Carried descendant rekey is outside the rotated container's organization\",\n    );\n  }\n  return buildMaterializedContainerRekeyPlan({\n    author: {\n      ...input.author,\n      organizationId: rebased.ancestor.organizationId,\n    },\n    execSql: input.execSql,\n    knownContainerKeks: input.knownContainerKeks,\n    // Nothing here is acknowledged yet: pins move only with the batch.\n    persistVerificationCheckpoints: false,\n    previousProjection: rebased.projection,\n    principalPolicyCache: input.principalPolicyCache,\n    replacementPrincipalPolicy: input.replacementPrincipalPolicy,\n    resolveProjectionUserKey: input.resolveProjectionUserKey,\n    stillCurrent: input.stillCurrent,\n    targetSecretKey: input.targetSecretKey,\n    warmReferencedPrincipalPolicies: input.warmReferencedPrincipalPolicies,\n  });\n}\n\n/**\n * Sign the descendant rekeys a rotation must commit with (#2340). The server\n * refuses a rotation that would leave a level above a directly granted\n * container pinned to a retired epoch, because the grantee could never re-key\n * that level itself and its writes would wait on another device. It names the\n * levels; this signs them, parent-first, each against the path the batch will\n * leave behind rather than the one currently served.\n *\n * `requiredContainerIds` is a hint, never an authority: each container is\n * fetched and verified here, and refused unless it sits below a rotation.\n */\nexport async function planCarriedDescendantRekeys(\n  input: CarriedRekeyPlanningInput & {\n    readonly requiredContainerIds: readonly string[];\n    /** Each rotated container's own path once the batch is accepted. */\n    readonly rotated: readonly SpeculativePath[];\n  },\n): Promise<MaterializedContainerRekeyPlan[]> {\n  const plans: MaterializedContainerRekeyPlan[] = [];\n  const speculativePaths: SpeculativePath[] = [...input.rotated];\n  const knownContainerKeks = new Map(input.knownContainerKeks);\n  const planned = new Set<string>();\n  for (const containerId of input.requiredContainerIds) {\n    if (plans.length >= MAX_ROTATION_CONTAINER_REKEYS) break;\n    if (planned.has(containerId)) continue;\n    const served =\n      await input.apiClient.getContainerWriterProjection(containerId);\n    if (!served) {\n      throw new Error(\"Carried descendant rekey projection is unavailable\");\n    }\n    if (served.containerId !== containerId) {\n      throw new Error(\"Carried descendant rekey targets another container\");\n    }\n    const plan = await planCarriedDescendantRekey({\n      ...input,\n      knownContainerKeks,\n      rotated: speculativePaths,\n      served,\n    });\n    planned.add(containerId);\n    plans.push(plan);\n    speculativePaths.push(plan.writerProjection);\n    knownContainerKeks.set(plan.plan.containerKeyEpochId, plan.containerKey);\n  }\n  return plans;\n}\n"]}

package/workflows/containers/child/create.d.ts

@@ -0,0 +1,24 @@
+import type { ContainerWriterProjectionResponse } from "../../../internal/validators/response/index.js";
+import type { BuildContainerCreatePlanInput, ContainerCreatePlan, ContainerMutationAuthor, CreateRemoteContainerResult, MaterializedContainerCreatePlan } from "../../../data/containers/shared/types.js";
+import { type ProjectionVerificationOptions } from "../../../data/documents/shared/types.js";
+import type { ReferencedPrincipalPolicyWarmer } from "../../../data/keyingProjectionVerification.js";
+import type { ExecSql } from "../../../data/sqlite/sqlSchema.js";
+import { type RemoteContainerCreateInput } from "./createSubmission.js";
+export declare function buildContainerCreatePlan(input: BuildContainerCreatePlanInput): Promise<ContainerCreatePlan>;
+export declare function buildMaterializedContainerCreatePlan(input: {
+    author: ContainerMutationAuthor;
+    containerId?: string | undefined;
+    containerKey?: Uint8Array | undefined;
+    containerKeyEpochId?: string | undefined;
+    eventId?: string | undefined;
+    execSql?: ExecSql | undefined;
+    managedPrincipalGrant?: BuildContainerCreatePlanInput["managedPrincipalGrant"];
+    metadataDocumentId?: string | undefined;
+    systemSlot?: string | null | undefined;
+    parentProjection: ContainerWriterProjectionResponse;
+    parentSecretKey: Uint8Array;
+    signedAt?: string | undefined;
+    warmReferencedPrincipalPolicies?: ReferencedPrincipalPolicyWarmer | undefined;
+} & ProjectionVerificationOptions): Promise<MaterializedContainerCreatePlan>;
+export { childContainerWriterProjectionFromCreatePlan } from "./createProjection.js";
+export declare function createRemoteContainer(input: RemoteContainerCreateInput): Promise<CreateRemoteContainerResult | null>;