@tearleads/client-sdk 0.1.15 → 0.1.17

package/workflows/principals/principalRecoveryDirectory.js

@@ -1,13 +1,25 @@
-import { KeyingVerificationError, serializeKeyingCanonicalJson, verifyPrincipalPolicyHistoryReferences, } from "../../internal/crypto/index.js";
+import { KeyingVerificationError, verifyPrincipalPolicyHistoryReferences, } from "../../internal/crypto/index.js";
 import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
 import { loadPrincipalHistoryReference } from "../../data/persistence/principalHistoryEvidencePersistence.js";
 import { parseOrganizationAuthorityDescriptor, } from "../../data/principals/organizationAuthorityDescriptor.js";
 import { principalHistoryEvidenceScopeId } from "../../data/principals/principalHistoryPrefixProtection.js";
+import { directoryHistoryProtection } from "../../data/principals/principalHistoryScopeProtection.js";
 import { loadVerifiedPrincipalHistoryPrefix } from "./principalHistoryRecoveryPrefix.js";
 import { PrincipalPolicyHistoryReadError, } from "./principalHistoryRecoveryTypes.js";
+import { reusePrincipalDiscoveryPage } from "./principalRecoveryDiscoveryPage.js";
 import { recoverPrincipalPolicyHistory } from "./recoverPrincipalPolicyHistory.js";
 export class PrincipalRecoveryDirectoryAdvanced extends Error {
 }
+function exactHead(state) {
+    return {
+        principalType: state.principalType,
+        principalId: state.principalId,
+        version: state.version,
+        stateHash: state.stateHash,
+        keyEpoch: state.keyEpoch,
+        keyFingerprint: state.keyFingerprint,
+    };
+}
 /** An unverified discovery read chooses a pin; recovery must authenticate it. */
 async function discoverDirectoryHead(input) {
     assertProjectionVerificationCurrent(() => !input.signal?.aborted && input.stillCurrent());
@@ -39,7 +51,11 @@ async function discoverDirectoryHead(input) {
         });
         if (!selected.ok)
             throw selected.error;
-        return { head: prefix.head, genesis: genesis.reference };
+        return {
+            head: prefix.head,
+            genesis: genesis.reference,
+            apiClient: input.apiClient,
+        };
     }
     for await (const result of input.apiClient.getPrincipalPolicyPages("organization", input.organizationId, { signal: input.signal })) {
         if (!result.ok)
@@ -52,6 +68,7 @@ async function discoverDirectoryHead(input) {
             first.principalId !== input.organizationId)
             throw new KeyingVerificationError("missing_dependency", "Organization directory discovery requires genesis");
         return {
+            apiClient: reusePrincipalDiscoveryPage(input.apiClient, result),
             genesis: {
                 principalType: first.principalType,
                 principalId: first.principalId,
@@ -72,26 +89,29 @@ async function discoverDirectoryHead(input) {
     }
     throw new KeyingVerificationError("missing_dependency", "Organization directory head is unavailable");
 }
-export async function recoverPolicyDirectory(input, references) {
+export async function recoverPolicyDirectory(input, references, selected) {
     const scoped = {
         ...input,
-        protection: {
-            localKey: input.protection.localKey,
-            context: serializeKeyingCanonicalJson([
-                "tearleads.sdk.principal-history.directory.v1",
-                input.protection.context,
-            ]),
-        },
+        protection: directoryHistoryProtection(input.protection),
     };
-    const { head: expectedHead, genesis } = await discoverDirectoryHead(scoped);
+    const { head: expectedHead, genesis, apiClient, } = selected
+        ? {
+            head: exactHead(selected.policy.state),
+            genesis: selected.policy.retainedHistory[0]?.state,
+            apiClient: input.apiClient,
+        }
+        : await discoverDirectoryHead(scoped);
+    if (genesis?.version !== 1)
+        throw new KeyingVerificationError("missing_dependency", "Organization directory recovery requires verified genesis");
     if (references.some((reference) => reference.version > expectedHead.version))
         throw new PrincipalRecoveryDirectoryAdvanced();
     const recovered = await recoverPrincipalPolicyHistory({
         ...scoped,
+        apiClient,
         expectedHead,
         retainedReferences: references.some((reference) => reference.version === 1)
             ? references
-            : [genesis, ...references],
+            : [exactHead(genesis), ...references],
     });
     let descriptor;
     try {

package/workflows/principals/principalRecoveryDirectory.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalRecoveryDirectory.js","sourceRoot":"","sources":["principalRecoveryDirectory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport {\n  type OrganizationAuthorityDescriptor,\n  parseOrganizationAuthorityDescriptor,\n} from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { principalHistoryEvidenceScopeId } from \"../../data/principals/principalHistoryPrefixProtection\";\nimport { loadVerifiedPrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport {\n  PrincipalPolicyHistoryReadError,\n  type RecoveredPrincipalPolicyHistory,\n  type RecoverPrincipalPolicyHistoryOptions,\n} from \"./principalHistoryRecoveryTypes\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\nexport type PrincipalRecoveryContext = Omit<\n  RecoverPrincipalPolicyHistoryOptions,\n  | \"expectedHead\"\n  | \"retainedReferences\"\n  | \"historyVerification\"\n  | \"loadExternalAuthority\"\n>;\n\nexport interface RecoveredPolicyDirectory\n  extends RecoveredPrincipalPolicyHistory {\n  readonly descriptor: OrganizationAuthorityDescriptor;\n}\n\nexport class PrincipalRecoveryDirectoryAdvanced extends Error {}\n\n/** An unverified discovery read chooses a pin; recovery must authenticate it. */\nasync function discoverDirectoryHead(input: PrincipalRecoveryContext): Promise<{\n  head: ReferencedPrincipalHead;\n  genesis: ReferencedPrincipalHead;\n}> {\n  assertProjectionVerificationCurrent(\n    () => !input.signal?.aborted && input.stillCurrent(),\n  );\n  if (input.offline) {\n    const principal = {\n      principalType: \"organization\" as const,\n      principalId: input.organizationId,\n    };\n    const scopeId = await principalHistoryEvidenceScopeId({\n      organizationId: input.organizationId,\n      head: principal,\n      protection: input.protection,\n    });\n    const prefix = await loadVerifiedPrincipalHistoryPrefix(\n      input,\n      principal,\n      scopeId,\n    );\n    if (!prefix)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory is unavailable offline\",\n      );\n    const history = prefix.verifier.finish(prefix.head);\n    if (!history.ok) throw history.error;\n    const genesis = await loadPrincipalHistoryReference({\n      execSql: input.execSql,\n      scopeId,\n      history: history.value,\n      version: 1,\n    });\n    const selected = await verifyPrincipalPolicyHistoryReferences({\n      history: history.value,\n      references: [genesis],\n    });\n    if (!selected.ok) throw selected.error;\n    return { head: prefix.head, genesis: genesis.reference };\n  }\n  for await (const result of input.apiClient.getPrincipalPolicyPages(\n    \"organization\",\n    input.organizationId,\n    { signal: input.signal },\n  )) {\n    if (!result.ok) throw new PrincipalPolicyHistoryReadError(result);\n    assertProjectionVerificationCurrent(\n      () => !input.signal?.aborted && input.stillCurrent(),\n    );\n    const state = result.data.currentState;\n    const first = result.data.previousStates[0]?.state ?? state;\n    if (\n      first.version !== 1 ||\n      first.principalType !== \"organization\" ||\n      first.principalId !== input.organizationId\n    )\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory discovery requires genesis\",\n      );\n    return {\n      genesis: {\n        principalType: first.principalType,\n        principalId: first.principalId,\n        version: first.version,\n        stateHash: first.stateHash,\n        keyEpoch: first.keyEpoch,\n        keyFingerprint: first.keyFingerprint,\n      },\n      head: {\n        principalType: \"organization\",\n        principalId: input.organizationId,\n        version: state.version,\n        stateHash: state.stateHash,\n        keyEpoch: state.keyEpoch,\n        keyFingerprint: state.keyFingerprint,\n      },\n    };\n  }\n  throw new KeyingVerificationError(\n    \"missing_dependency\",\n    \"Organization directory head is unavailable\",\n  );\n}\n\nexport async function recoverPolicyDirectory(\n  input: PrincipalRecoveryContext,\n  references: readonly ReferencedPrincipalHead[],\n): Promise<RecoveredPolicyDirectory> {\n  const scoped = {\n    ...input,\n    protection: {\n      localKey: input.protection.localKey,\n      context: serializeKeyingCanonicalJson([\n        \"tearleads.sdk.principal-history.directory.v1\",\n        input.protection.context,\n      ]),\n    },\n  };\n  const { head: expectedHead, genesis } = await discoverDirectoryHead(scoped);\n  if (references.some((reference) => reference.version > expectedHead.version))\n    throw new PrincipalRecoveryDirectoryAdvanced();\n  const recovered = await recoverPrincipalPolicyHistory({\n    ...scoped,\n    expectedHead,\n    retainedReferences: references.some((reference) => reference.version === 1)\n      ? references\n      : [genesis, ...references],\n  });\n  let descriptor: OrganizationAuthorityDescriptor;\n  try {\n    descriptor = parseOrganizationAuthorityDescriptor(\n      recovered.current.currentPayload.ciphertext,\n    );\n  } catch {\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Organization directory payload is invalid\",\n    );\n  }\n  if (descriptor.organizationId !== input.organizationId)\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Organization directory scope does not match\",\n    );\n  return { ...recovered, descriptor };\n}\n"]}
+{"version":3,"file":"principalRecoveryDirectory.js","sourceRoot":"","sources":["principalRecoveryDirectory.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  verifyPrincipalPolicyHistoryReferences,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { loadPrincipalHistoryReference } from \"../../data/persistence/principalHistoryEvidencePersistence\";\nimport {\n  type OrganizationAuthorityDescriptor,\n  parseOrganizationAuthorityDescriptor,\n} from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { principalHistoryEvidenceScopeId } from \"../../data/principals/principalHistoryPrefixProtection\";\nimport { directoryHistoryProtection } from \"../../data/principals/principalHistoryScopeProtection\";\nimport { loadVerifiedPrincipalHistoryPrefix } from \"./principalHistoryRecoveryPrefix\";\nimport {\n  PrincipalPolicyHistoryReadError,\n  type RecoveredPrincipalPolicyHistory,\n  type RecoverPrincipalPolicyHistoryOptions,\n} from \"./principalHistoryRecoveryTypes\";\nimport { reusePrincipalDiscoveryPage } from \"./principalRecoveryDiscoveryPage\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\nexport type PrincipalRecoveryContext = Omit<\n  RecoverPrincipalPolicyHistoryOptions,\n  | \"expectedHead\"\n  | \"retainedReferences\"\n  | \"historyVerification\"\n  | \"loadExternalAuthority\"\n>;\n\nexport interface RecoveredPolicyDirectory\n  extends RecoveredPrincipalPolicyHistory {\n  readonly descriptor: OrganizationAuthorityDescriptor;\n}\n\nexport class PrincipalRecoveryDirectoryAdvanced extends Error {}\n\nfunction exactHead(state: ReferencedPrincipalHead): ReferencedPrincipalHead {\n  return {\n    principalType: state.principalType,\n    principalId: state.principalId,\n    version: state.version,\n    stateHash: state.stateHash,\n    keyEpoch: state.keyEpoch,\n    keyFingerprint: state.keyFingerprint,\n  };\n}\n\n/** An unverified discovery read chooses a pin; recovery must authenticate it. */\nasync function discoverDirectoryHead(input: PrincipalRecoveryContext): Promise<{\n  head: ReferencedPrincipalHead;\n  genesis: ReferencedPrincipalHead;\n  apiClient: PrincipalRecoveryContext[\"apiClient\"];\n}> {\n  assertProjectionVerificationCurrent(\n    () => !input.signal?.aborted && input.stillCurrent(),\n  );\n  if (input.offline) {\n    const principal = {\n      principalType: \"organization\" as const,\n      principalId: input.organizationId,\n    };\n    const scopeId = await principalHistoryEvidenceScopeId({\n      organizationId: input.organizationId,\n      head: principal,\n      protection: input.protection,\n    });\n    const prefix = await loadVerifiedPrincipalHistoryPrefix(\n      input,\n      principal,\n      scopeId,\n    );\n    if (!prefix)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory is unavailable offline\",\n      );\n    const history = prefix.verifier.finish(prefix.head);\n    if (!history.ok) throw history.error;\n    const genesis = await loadPrincipalHistoryReference({\n      execSql: input.execSql,\n      scopeId,\n      history: history.value,\n      version: 1,\n    });\n    const selected = await verifyPrincipalPolicyHistoryReferences({\n      history: history.value,\n      references: [genesis],\n    });\n    if (!selected.ok) throw selected.error;\n    return {\n      head: prefix.head,\n      genesis: genesis.reference,\n      apiClient: input.apiClient,\n    };\n  }\n  for await (const result of input.apiClient.getPrincipalPolicyPages(\n    \"organization\",\n    input.organizationId,\n    { signal: input.signal },\n  )) {\n    if (!result.ok) throw new PrincipalPolicyHistoryReadError(result);\n    assertProjectionVerificationCurrent(\n      () => !input.signal?.aborted && input.stillCurrent(),\n    );\n    const state = result.data.currentState;\n    const first = result.data.previousStates[0]?.state ?? state;\n    if (\n      first.version !== 1 ||\n      first.principalType !== \"organization\" ||\n      first.principalId !== input.organizationId\n    )\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Organization directory discovery requires genesis\",\n      );\n    return {\n      apiClient: reusePrincipalDiscoveryPage(input.apiClient, result),\n      genesis: {\n        principalType: first.principalType,\n        principalId: first.principalId,\n        version: first.version,\n        stateHash: first.stateHash,\n        keyEpoch: first.keyEpoch,\n        keyFingerprint: first.keyFingerprint,\n      },\n      head: {\n        principalType: \"organization\",\n        principalId: input.organizationId,\n        version: state.version,\n        stateHash: state.stateHash,\n        keyEpoch: state.keyEpoch,\n        keyFingerprint: state.keyFingerprint,\n      },\n    };\n  }\n  throw new KeyingVerificationError(\n    \"missing_dependency\",\n    \"Organization directory head is unavailable\",\n  );\n}\n\nexport async function recoverPolicyDirectory(\n  input: PrincipalRecoveryContext,\n  references: readonly ReferencedPrincipalHead[],\n  selected?: RecoveredPolicyDirectory,\n): Promise<RecoveredPolicyDirectory> {\n  const scoped = {\n    ...input,\n    protection: directoryHistoryProtection(input.protection),\n  };\n  const {\n    head: expectedHead,\n    genesis,\n    apiClient,\n  } = selected\n    ? {\n        head: exactHead(selected.policy.state),\n        genesis: selected.policy.retainedHistory[0]?.state,\n        apiClient: input.apiClient,\n      }\n    : await discoverDirectoryHead(scoped);\n  if (genesis?.version !== 1)\n    throw new KeyingVerificationError(\n      \"missing_dependency\",\n      \"Organization directory recovery requires verified genesis\",\n    );\n  if (references.some((reference) => reference.version > expectedHead.version))\n    throw new PrincipalRecoveryDirectoryAdvanced();\n  const recovered = await recoverPrincipalPolicyHistory({\n    ...scoped,\n    apiClient,\n    expectedHead,\n    retainedReferences: references.some((reference) => reference.version === 1)\n      ? references\n      : [exactHead(genesis), ...references],\n  });\n  let descriptor: OrganizationAuthorityDescriptor;\n  try {\n    descriptor = parseOrganizationAuthorityDescriptor(\n      recovered.current.currentPayload.ciphertext,\n    );\n  } catch {\n    throw new KeyingVerificationError(\n      \"invalid_shape\",\n      \"Organization directory payload is invalid\",\n    );\n  }\n  if (descriptor.organizationId !== input.organizationId)\n    throw new KeyingVerificationError(\n      \"object_mismatch\",\n      \"Organization directory scope does not match\",\n    );\n  return { ...recovered, descriptor };\n}\n"]}

package/workflows/principals/principalRecoveryDiscoveryPage.js

@@ -0,0 +1,36 @@
+/** Reuse the discovery bytes as untrusted input to the ordinary verifier. */
+export function reusePrincipalDiscoveryPage(apiClient, discovery) {
+    const first = structuredClone(discovery);
+    const page = first.data;
+    const current = {
+        currentState: page.currentState,
+        currentPayload: page.currentPayload,
+        currentProjection: page.currentProjection,
+        currentGrants: page.currentGrants,
+        currentMemberEnvelopes: page.currentMemberEnvelopes,
+    };
+    return {
+        async *getPrincipalPolicyPages(principalType, principalId, options = {}) {
+            if (options.resume !== undefined ||
+                (options.afterVersion ?? 0) !== 0 ||
+                options.stateHash !== current.currentState.stateHash ||
+                principalType !== current.currentState.principalType ||
+                principalId !== current.currentState.principalId) {
+                yield* apiClient.getPrincipalPolicyPages(principalType, principalId, options);
+                return;
+            }
+            yield structuredClone(first);
+            const next = page.historyPage.nextAfterVersion;
+            if (next === null)
+                return;
+            // Resume binds every later page to these exact artifacts, including bytes
+            // outside the signed head. The API client's cursor/shape checks still run.
+            yield* apiClient.getPrincipalPolicyPages(principalType, principalId, {
+                ...options,
+                afterVersion: undefined,
+                resume: { current, afterVersion: next },
+            });
+        },
+    };
+}
+//# sourceMappingURL=principalRecoveryDiscoveryPage.js.map

package/workflows/principals/principalRecoveryDiscoveryPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryDiscoveryPage.js","sourceRoot":"","sources":["principalRecoveryDiscoveryPage.ts"],"names":[],"mappings":"AAGA,6EAA6E;AAC7E,MAAM,UAAU,2BAA2B,CACzC,SAAqD,EACrD,SAAsD;IAEtD,MAAM,KAAK,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG;QACd,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;QACzC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,sBAAsB,EAAE,IAAI,CAAC,sBAAsB;KACpD,CAAC;IACF,OAAO;QACL,KAAK,CAAC,CAAC,uBAAuB,CAAC,aAAa,EAAE,WAAW,EAAE,OAAO,GAAG,EAAE;YACrE,IACE,OAAO,CAAC,MAAM,KAAK,SAAS;gBAC5B,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,KAAK,CAAC;gBACjC,OAAO,CAAC,SAAS,KAAK,OAAO,CAAC,YAAY,CAAC,SAAS;gBACpD,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,aAAa;gBACpD,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,WAAW,EAChD,CAAC;gBACD,KAAK,CAAC,CAAC,SAAS,CAAC,uBAAuB,CACtC,aAAa,EACb,WAAW,EACX,OAAO,CACR,CAAC;gBACF,OAAO;YACT,CAAC;YACD,MAAM,eAAe,CAAC,KAAK,CAAC,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC;YAC/C,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO;YAC1B,0EAA0E;YAC1E,2EAA2E;YAC3E,KAAK,CAAC,CAAC,SAAS,CAAC,uBAAuB,CAAC,aAAa,EAAE,WAAW,EAAE;gBACnE,GAAG,OAAO;gBACV,YAAY,EAAE,SAAS;gBACvB,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE;aACxC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { ApiClient, RequestSuccess } from \"@tearleads/api-client\";\nimport type { PrincipalPolicyPageResponse } from \"@tearleads/validators/response\";\n\n/** Reuse the discovery bytes as untrusted input to the ordinary verifier. */\nexport function reusePrincipalDiscoveryPage(\n  apiClient: Pick<ApiClient, \"getPrincipalPolicyPages\">,\n  discovery: RequestSuccess<PrincipalPolicyPageResponse>,\n): Pick<ApiClient, \"getPrincipalPolicyPages\"> {\n  const first = structuredClone(discovery);\n  const page = first.data;\n  const current = {\n    currentState: page.currentState,\n    currentPayload: page.currentPayload,\n    currentProjection: page.currentProjection,\n    currentGrants: page.currentGrants,\n    currentMemberEnvelopes: page.currentMemberEnvelopes,\n  };\n  return {\n    async *getPrincipalPolicyPages(principalType, principalId, options = {}) {\n      if (\n        options.resume !== undefined ||\n        (options.afterVersion ?? 0) !== 0 ||\n        options.stateHash !== current.currentState.stateHash ||\n        principalType !== current.currentState.principalType ||\n        principalId !== current.currentState.principalId\n      ) {\n        yield* apiClient.getPrincipalPolicyPages(\n          principalType,\n          principalId,\n          options,\n        );\n        return;\n      }\n      yield structuredClone(first);\n      const next = page.historyPage.nextAfterVersion;\n      if (next === null) return;\n      // Resume binds every later page to these exact artifacts, including bytes\n      // outside the signed head. The API client's cursor/shape checks still run.\n      yield* apiClient.getPrincipalPolicyPages(principalType, principalId, {\n        ...options,\n        afterVersion: undefined,\n        resume: { current, afterVersion: next },\n      });\n    },\n  };\n}\n"]}

package/workflows/principals/principalRecoveryLocalPreference.js

@@ -0,0 +1,29 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
+import { PrincipalHistoryRecoveryRaceError } from "./principalHistoryRecoveryTypes.js";
+import { recoverWithPrincipalOutageFallback } from "./principalRecoveryOutage.js";
+/** Reuse exact current artifacts, or a proved historical page within a newer prefix. */
+export async function recoverWithPrincipalLocalPreference(recover, options, preferLocalCurrent) {
+    if (preferLocalCurrent && !options.offline) {
+        try {
+            const local = await recover({
+                ...options,
+                offline: true,
+            });
+            assertProjectionVerificationCurrent(options.stillCurrent);
+            if (options.historyPage ||
+                principalHeadMatchesReference(local.policy.state, options.reference))
+                return local;
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(options.stillCurrent);
+            if (!(error instanceof PrincipalHistoryRecoveryRaceError) &&
+                !(error instanceof KeyingVerificationError &&
+                    error.code === "missing_dependency"))
+                throw error;
+        }
+    }
+    return recoverWithPrincipalOutageFallback(recover, options);
+}
+//# sourceMappingURL=principalRecoveryLocalPreference.js.map

package/workflows/principals/principalRecoveryLocalPreference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principalRecoveryLocalPreference.js","sourceRoot":"","sources":["principalRecoveryLocalPreference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,6BAA6B,EAAE,MAAM,uDAAuD,CAAC;AACtG,OAAO,EAAE,iCAAiC,EAAE,MAAM,iCAAiC,CAAC;AACpF,OAAO,EAAE,kCAAkC,EAAE,MAAM,2BAA2B,CAAC;AAG/E,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,OAAmD,EACnD,OAAkE,EAClE,kBAA2B;IAE3B,IAAI,kBAAkB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC;gBAC1B,GAAG,OAAO;gBACV,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YACH,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC1D,IACE,OAAO,CAAC,WAAW;gBACnB,6BAA6B,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC;gBAEpE,OAAO,KAAK,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAC1D,IACE,CAAC,CAAC,KAAK,YAAY,iCAAiC,CAAC;gBACrD,CAAC,CACC,KAAK,YAAY,uBAAuB;oBACxC,KAAK,CAAC,IAAI,KAAK,oBAAoB,CACpC;gBAED,MAAM,KAAK,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,kCAAkC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport { PrincipalHistoryRecoveryRaceError } from \"./principalHistoryRecoveryTypes\";\nimport { recoverWithPrincipalOutageFallback } from \"./principalRecoveryOutage\";\nimport type { recoverScopedPrincipalPolicyHistory } from \"./recoverScopedPrincipalPolicyHistory\";\n\n/** Reuse exact current artifacts, or a proved historical page within a newer prefix. */\nexport async function recoverWithPrincipalLocalPreference(\n  recover: typeof recoverScopedPrincipalPolicyHistory,\n  options: Parameters<typeof recoverScopedPrincipalPolicyHistory>[0],\n  preferLocalCurrent: boolean,\n) {\n  if (preferLocalCurrent && !options.offline) {\n    try {\n      const local = await recover({\n        ...options,\n        offline: true,\n      });\n      assertProjectionVerificationCurrent(options.stillCurrent);\n      if (\n        options.historyPage ||\n        principalHeadMatchesReference(local.policy.state, options.reference)\n      )\n        return local;\n    } catch (error) {\n      assertProjectionVerificationCurrent(options.stillCurrent);\n      if (\n        !(error instanceof PrincipalHistoryRecoveryRaceError) &&\n        !(\n          error instanceof KeyingVerificationError &&\n          error.code === \"missing_dependency\"\n        )\n      )\n        throw error;\n    }\n  }\n  return recoverWithPrincipalOutageFallback(recover, options);\n}\n"]}

package/workflows/principals/principalRecoveryMemo.d.ts

@@ -0,0 +1,16 @@
+import { type ReferencedPrincipalHead } from "../../internal/crypto/index.js";
+import type { RecoveredPrincipalPolicyHistory } from "./principalHistoryRecoveryTypes.js";
+import { type PrincipalRecoveryContext, type RecoveredPolicyDirectory } from "./principalRecoveryDirectory.js";
+type Memo<T> = Map<string, Promise<{
+    value: T;
+    stillCurrent: () => boolean;
+}>>;
+export interface PrincipalRecoveryMemo {
+    readonly directories: Memo<RecoveredPolicyDirectory>;
+    readonly admins: Memo<RecoveredPrincipalPolicyHistory>;
+}
+export declare function createPrincipalRecoveryReader(input: PrincipalRecoveryContext, memo?: PrincipalRecoveryMemo): {
+    directory: (references: readonly ReferencedPrincipalHead[]) => Promise<RecoveredPolicyDirectory>;
+    admins: (expectedHead: ReferencedPrincipalHead, retainedReferences?: readonly ReferencedPrincipalHead[]) => Promise<RecoveredPrincipalPolicyHistory>;
+};
+export {};

package/workflows/principals/principalRecoveryMemo.js

@@ -1,5 +1,6 @@
-import { serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
+import { KeyingVerificationError, serializeKeyingCanonicalJson, } from "../../internal/crypto/index.js";
 import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { principalHeadMatchesReference } from "../../data/principals/organizationAuthorityDescriptor.js";
 import { recoverPolicyDirectory, } from "./principalRecoveryDirectory.js";
 import { recoverPrincipalPolicyHistory } from "./recoverPrincipalPolicyHistory.js";
 /** Only share authenticated results within one projection collection lifetime. */
@@ -19,28 +20,99 @@ async function memoPrincipalRecovery(memo, key, stillCurrent, work) {
     assertProjectionVerificationCurrent(stillCurrent);
     return result.value;
 }
+async function readMemoizedAdmins(input, memo, scope, expectedHead, retainedReferences) {
+    // Every recovered Current already retains its own exact head.
+    const references = retainedReferences.filter((reference) => !principalHeadMatchesReference(expectedHead, reference));
+    const key = (selected) => serializeKeyingCanonicalJson([
+        ...scope,
+        { ...expectedHead },
+        selected.map((reference) => ({ ...reference })),
+    ]);
+    const known = memo?.get(key([]));
+    let sourceCurrent = () => true;
+    const current = () => !input.signal?.aborted && input.stillCurrent() && sourceCurrent();
+    return memoPrincipalRecovery(memo, key(references), current, async () => {
+        const options = {
+            ...input,
+            expectedHead,
+            retainedReferences,
+            historyVerification: "direct-admins",
+            stillCurrent: current,
+        };
+        if (known) {
+            sourceCurrent = (await known).stillCurrent;
+            assertProjectionVerificationCurrent(current);
+            try {
+                // A freshly verified exact head only needs local proofs for additional
+                // citations; their signature and private-root checks still run.
+                return await recoverPrincipalPolicyHistory({
+                    ...options,
+                    offline: true,
+                });
+            }
+            catch (error) {
+                assertProjectionVerificationCurrent(current);
+                if (input.offline ||
+                    !(error instanceof KeyingVerificationError) ||
+                    error.code !== "missing_dependency")
+                    throw error;
+            }
+        }
+        return recoverPrincipalPolicyHistory(options);
+    });
+}
+async function readMemoizedDirectory(input, memo, key, references) {
+    const known = references.length > 0 ? memo?.get(key([])) : undefined;
+    let sourceCurrent = () => true;
+    const current = () => !input.signal?.aborted && input.stillCurrent() && sourceCurrent();
+    return memoPrincipalRecovery(memo, key(references), current, async () => {
+        if (!known)
+            return recoverPolicyDirectory(input, references);
+        const source = await known;
+        sourceCurrent = source.stillCurrent;
+        assertProjectionVerificationCurrent(current);
+        try {
+            // Add authenticated historical citations to this batch's exact directory
+            // view. A newer private prefix must not silently replace that view.
+            return await recoverPolicyDirectory({ ...input, offline: true, stillCurrent: current }, references, source.value);
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(current);
+            if (input.offline ||
+                !(error instanceof KeyingVerificationError) ||
+                error.code !== "missing_dependency")
+                throw error;
+        }
+        return recoverPolicyDirectory({ ...input, stillCurrent: current }, references, source.value);
+    });
+}
 export function createPrincipalRecoveryReader(input, memo) {
     const scope = [
         input.organizationId,
         input.protection.context,
         input.offline === true,
     ];
-    const current = () => !input.signal?.aborted && input.stillCurrent();
+    const directoryKey = (references) => serializeKeyingCanonicalJson([
+        ...scope,
+        references.map((reference) => ({ ...reference })),
+    ]);
     return {
-        directory: (references) => memoPrincipalRecovery(memo?.directories, serializeKeyingCanonicalJson([
-            ...scope,
-            references.map((reference) => ({ ...reference })),
-        ]), current, () => recoverPolicyDirectory(input, references)),
-        admins: (expectedHead, retainedReferences = []) => memoPrincipalRecovery(memo?.admins, serializeKeyingCanonicalJson([
-            ...scope,
-            { ...expectedHead },
-            retainedReferences.map((reference) => ({ ...reference })),
-        ]), current, () => recoverPrincipalPolicyHistory({
-            ...input,
-            expectedHead,
-            retainedReferences,
-            historyVerification: "direct-admins",
-        })),
+        directory: async (references) => {
+            const value = await readMemoizedDirectory(input, memo?.directories, directoryKey, references);
+            // Retaining extra citations does not prevent this authenticated directory
+            // from satisfying a later read with no selected historical references.
+            const unselectedKey = directoryKey([]);
+            const selected = memo?.directories.get(directoryKey(references));
+            if (memo &&
+                selected &&
+                references.length > 0 &&
+                !memo.directories.has(unselectedKey))
+                // Keep the original lease: its expiry requires a new batch, even if
+                // a later caller still has a live lease of its own.
+                memo.directories.set(unselectedKey, selected);
+            return value;
+        },
+        admins: (expectedHead, retainedReferences = []) => readMemoizedAdmins(input, memo?.admins, scope, expectedHead, retainedReferences),
     };
 }
 //# sourceMappingURL=principalRecoveryMemo.js.map

package/workflows/principals/principalRecoveryMemo.js.map

@@ -1 +1 @@
-{"version":3,"file":"principalRecoveryMemo.js","sourceRoot":"","sources":["principalRecoveryMemo.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AAEpG,OAAO,EAGL,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,6BAA6B,EAAE,MAAM,iCAAiC,CAAC;AAShF,kFAAkF;AAClF,KAAK,UAAU,qBAAqB,CAClC,IAAyB,EACzB,GAAW,EACX,YAA2B,EAC3B,IAAsB;IAEtB,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,OAAO,GAAG,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC;QAC5D,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACpD,IAAI,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjD,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,mCAAmC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IACzD,mCAAmC,CAAC,YAAY,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,KAA+B,EAC/B,IAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,KAAK,CAAC,cAAc;QACpB,KAAK,CAAC,UAAU,CAAC,OAAO;QACxB,KAAK,CAAC,OAAO,KAAK,IAAI;KACvB,CAAC;IACF,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,KAAK,CAAC,YAAY,EAAE,CAAC;IACrE,OAAO;QACL,SAAS,EAAE,CAAC,UAA8C,EAAE,EAAE,CAC5D,qBAAqB,CACnB,IAAI,EAAE,WAAW,EACjB,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAClD,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CAAC,sBAAsB,CAAC,KAAK,EAAE,UAAU,CAAC,CAChD;QACH,MAAM,EAAE,CACN,YAAqC,EACrC,qBAAyD,EAAE,EAC3D,EAAE,CACF,qBAAqB,CACnB,IAAI,EAAE,MAAM,EACZ,4BAA4B,CAAC;YAC3B,GAAG,KAAK;YACR,EAAE,GAAG,YAAY,EAAE;YACnB,kBAAkB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;SAC1D,CAAC,EACF,OAAO,EACP,GAAG,EAAE,CACH,6BAA6B,CAAC;YAC5B,GAAG,KAAK;YACR,YAAY;YACZ,kBAAkB;YAClB,mBAAmB,EAAE,eAAe;SACrC,CAAC,CACL;KACJ,CAAC;AACJ,CAAC","sourcesContent":["import {\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport type { RecoveredPrincipalPolicyHistory } from \"./principalHistoryRecoveryTypes\";\nimport {\n  type PrincipalRecoveryContext,\n  type RecoveredPolicyDirectory,\n  recoverPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\ntype Memo<T> = Map<string, Promise<{ value: T; stillCurrent: () => boolean }>>;\n\nexport interface PrincipalRecoveryMemo {\n  readonly directories: Memo<RecoveredPolicyDirectory>;\n  readonly admins: Memo<RecoveredPrincipalPolicyHistory>;\n}\n\n/** Only share authenticated results within one projection collection lifetime. */\nasync function memoPrincipalRecovery<T>(\n  memo: Memo<T> | undefined,\n  key: string,\n  stillCurrent: () => boolean,\n  work: () => Promise<T>,\n): Promise<T> {\n  assertProjectionVerificationCurrent(stillCurrent);\n  let pending = memo?.get(key);\n  if (!pending) {\n    pending = work().then((value) => ({ value, stillCurrent }));\n    memo?.set(key, pending);\n  }\n  const result = await pending.catch((error: unknown) => {\n    if (memo?.get(key) === pending) memo.delete(key);\n    throw error;\n  });\n  assertProjectionVerificationCurrent(result.stillCurrent);\n  assertProjectionVerificationCurrent(stillCurrent);\n  return result.value;\n}\n\nexport function createPrincipalRecoveryReader(\n  input: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const scope = [\n    input.organizationId,\n    input.protection.context,\n    input.offline === true,\n  ];\n  const current = () => !input.signal?.aborted && input.stillCurrent();\n  return {\n    directory: (references: readonly ReferencedPrincipalHead[]) =>\n      memoPrincipalRecovery(\n        memo?.directories,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          references.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () => recoverPolicyDirectory(input, references),\n      ),\n    admins: (\n      expectedHead: ReferencedPrincipalHead,\n      retainedReferences: readonly ReferencedPrincipalHead[] = [],\n    ) =>\n      memoPrincipalRecovery(\n        memo?.admins,\n        serializeKeyingCanonicalJson([\n          ...scope,\n          { ...expectedHead },\n          retainedReferences.map((reference) => ({ ...reference })),\n        ]),\n        current,\n        () =>\n          recoverPrincipalPolicyHistory({\n            ...input,\n            expectedHead,\n            retainedReferences,\n            historyVerification: \"direct-admins\",\n          }),\n      ),\n  };\n}\n"]}
+{"version":3,"file":"principalRecoveryMemo.js","sourceRoot":"","sources":["principalRecoveryMemo.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  KeyingVerificationError,\n  type ReferencedPrincipalHead,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { principalHeadMatchesReference } from \"../../data/principals/organizationAuthorityDescriptor\";\nimport type { RecoveredPrincipalPolicyHistory } from \"./principalHistoryRecoveryTypes\";\nimport {\n  type PrincipalRecoveryContext,\n  type RecoveredPolicyDirectory,\n  recoverPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport { recoverPrincipalPolicyHistory } from \"./recoverPrincipalPolicyHistory\";\n\ntype Memo<T> = Map<string, Promise<{ value: T; stillCurrent: () => boolean }>>;\n\nexport interface PrincipalRecoveryMemo {\n  readonly directories: Memo<RecoveredPolicyDirectory>;\n  readonly admins: Memo<RecoveredPrincipalPolicyHistory>;\n}\n\n/** Only share authenticated results within one projection collection lifetime. */\nasync function memoPrincipalRecovery<T>(\n  memo: Memo<T> | undefined,\n  key: string,\n  stillCurrent: () => boolean,\n  work: () => Promise<T>,\n): Promise<T> {\n  assertProjectionVerificationCurrent(stillCurrent);\n  let pending = memo?.get(key);\n  if (!pending) {\n    pending = work().then((value) => ({ value, stillCurrent }));\n    memo?.set(key, pending);\n  }\n  const result = await pending.catch((error: unknown) => {\n    if (memo?.get(key) === pending) memo.delete(key);\n    throw error;\n  });\n  assertProjectionVerificationCurrent(result.stillCurrent);\n  assertProjectionVerificationCurrent(stillCurrent);\n  return result.value;\n}\n\nasync function readMemoizedAdmins(\n  input: PrincipalRecoveryContext,\n  memo: Memo<RecoveredPrincipalPolicyHistory> | undefined,\n  scope: readonly (string | boolean)[],\n  expectedHead: ReferencedPrincipalHead,\n  retainedReferences: readonly ReferencedPrincipalHead[],\n) {\n  // Every recovered Current already retains its own exact head.\n  const references = retainedReferences.filter(\n    (reference) => !principalHeadMatchesReference(expectedHead, reference),\n  );\n  const key = (selected: readonly ReferencedPrincipalHead[]) =>\n    serializeKeyingCanonicalJson([\n      ...scope,\n      { ...expectedHead },\n      selected.map((reference) => ({ ...reference })),\n    ]);\n  const known = memo?.get(key([]));\n  let sourceCurrent = () => true;\n  const current = () =>\n    !input.signal?.aborted && input.stillCurrent() && sourceCurrent();\n  return memoPrincipalRecovery(memo, key(references), current, async () => {\n    const options = {\n      ...input,\n      expectedHead,\n      retainedReferences,\n      historyVerification: \"direct-admins\" as const,\n      stillCurrent: current,\n    };\n    if (known) {\n      sourceCurrent = (await known).stillCurrent;\n      assertProjectionVerificationCurrent(current);\n      try {\n        // A freshly verified exact head only needs local proofs for additional\n        // citations; their signature and private-root checks still run.\n        return await recoverPrincipalPolicyHistory({\n          ...options,\n          offline: true,\n        });\n      } catch (error) {\n        assertProjectionVerificationCurrent(current);\n        if (\n          input.offline ||\n          !(error instanceof KeyingVerificationError) ||\n          error.code !== \"missing_dependency\"\n        )\n          throw error;\n      }\n    }\n    return recoverPrincipalPolicyHistory(options);\n  });\n}\n\nasync function readMemoizedDirectory(\n  input: PrincipalRecoveryContext,\n  memo: Memo<RecoveredPolicyDirectory> | undefined,\n  key: (references: readonly ReferencedPrincipalHead[]) => string,\n  references: readonly ReferencedPrincipalHead[],\n) {\n  const known = references.length > 0 ? memo?.get(key([])) : undefined;\n  let sourceCurrent = () => true;\n  const current = () =>\n    !input.signal?.aborted && input.stillCurrent() && sourceCurrent();\n  return memoPrincipalRecovery(memo, key(references), current, async () => {\n    if (!known) return recoverPolicyDirectory(input, references);\n    const source = await known;\n    sourceCurrent = source.stillCurrent;\n    assertProjectionVerificationCurrent(current);\n    try {\n      // Add authenticated historical citations to this batch's exact directory\n      // view. A newer private prefix must not silently replace that view.\n      return await recoverPolicyDirectory(\n        { ...input, offline: true, stillCurrent: current },\n        references,\n        source.value,\n      );\n    } catch (error) {\n      assertProjectionVerificationCurrent(current);\n      if (\n        input.offline ||\n        !(error instanceof KeyingVerificationError) ||\n        error.code !== \"missing_dependency\"\n      )\n        throw error;\n    }\n    return recoverPolicyDirectory(\n      { ...input, stillCurrent: current },\n      references,\n      source.value,\n    );\n  });\n}\n\nexport function createPrincipalRecoveryReader(\n  input: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const scope = [\n    input.organizationId,\n    input.protection.context,\n    input.offline === true,\n  ];\n  const directoryKey = (references: readonly ReferencedPrincipalHead[]) =>\n    serializeKeyingCanonicalJson([\n      ...scope,\n      references.map((reference) => ({ ...reference })),\n    ]);\n  return {\n    directory: async (references: readonly ReferencedPrincipalHead[]) => {\n      const value = await readMemoizedDirectory(\n        input,\n        memo?.directories,\n        directoryKey,\n        references,\n      );\n      // Retaining extra citations does not prevent this authenticated directory\n      // from satisfying a later read with no selected historical references.\n      const unselectedKey = directoryKey([]);\n      const selected = memo?.directories.get(directoryKey(references));\n      if (\n        memo &&\n        selected &&\n        references.length > 0 &&\n        !memo.directories.has(unselectedKey)\n      )\n        // Keep the original lease: its expiry requires a new batch, even if\n        // a later caller still has a live lease of its own.\n        memo.directories.set(unselectedKey, selected);\n      return value;\n    },\n    admins: (\n      expectedHead: ReferencedPrincipalHead,\n      retainedReferences: readonly ReferencedPrincipalHead[] = [],\n    ) =>\n      readMemoizedAdmins(\n        input,\n        memo?.admins,\n        scope,\n        expectedHead,\n        retainedReferences,\n      ),\n  };\n}\n"]}

package/workflows/principals/recoverCurrentOrganizationPolicy.js

@@ -0,0 +1,33 @@
+import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
+import { ownPrincipalHistoryProtection } from "../../data/principals/principalHistoryProtection.js";
+import { createPrincipalRecoveryReader, } from "./principalRecoveryMemo.js";
+import { isPrincipalRecoveryOutage } from "./principalRecoveryOutage.js";
+/** Discover and verify current directory artifacts, including protected offline recovery. */
+export async function recoverCurrentOrganizationPolicy(options, memo) {
+    const input = {
+        ...options,
+        protection: ownPrincipalHistoryProtection(options.protection),
+    };
+    try {
+        let directory;
+        try {
+            directory = await createPrincipalRecoveryReader(input, memo).directory([]);
+        }
+        catch (error) {
+            assertProjectionVerificationCurrent(input.stillCurrent);
+            if (input.offline || !isPrincipalRecoveryOutage(error))
+                throw error;
+            directory = await createPrincipalRecoveryReader({ ...input, offline: true }, memo).directory([]);
+        }
+        assertProjectionVerificationCurrent(input.stillCurrent);
+        return {
+            current: directory.current,
+            policy: directory.policy,
+            dependencies: [],
+        };
+    }
+    finally {
+        input.protection.localKey.fill(0);
+    }
+}
+//# sourceMappingURL=recoverCurrentOrganizationPolicy.js.map

package/workflows/principals/recoverCurrentOrganizationPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverCurrentOrganizationPolicy.js","sourceRoot":"","sources":["recoverCurrentOrganizationPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mCAAmC,EAAE,MAAM,+CAA+C,CAAC;AACpG,OAAO,EAAE,6BAA6B,EAAE,MAAM,kDAAkD,CAAC;AAKjG,OAAO,EACL,6BAA6B,GAE9B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,6FAA6F;AAC7F,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,OAAiC,EACjC,IAA4B;IAE5B,MAAM,KAAK,GAAG;QACZ,GAAG,OAAO;QACV,UAAU,EAAE,6BAA6B,CAAC,OAAO,CAAC,UAAU,CAAC;KAC9D,CAAC;IACF,IAAI,CAAC;QACH,IAAI,SAAmC,CAAC;QACxC,IAAI,CAAC;YACH,SAAS,GAAG,MAAM,6BAA6B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,SAAS,CACpE,EAAE,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,mCAAmC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACxD,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YACpE,SAAS,GAAG,MAAM,6BAA6B,CAC7C,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAC3B,IAAI,CACL,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAClB,CAAC;QACD,mCAAmC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACxD,OAAO;YACL,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,YAAY,EAAE,EAAE;SACjB,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;AACH,CAAC","sourcesContent":["import { assertProjectionVerificationCurrent } from \"../../data/keyingProjectionVerification/types\";\nimport { ownPrincipalHistoryProtection } from \"../../data/principals/principalHistoryProtection\";\nimport type {\n  PrincipalRecoveryContext,\n  RecoveredPolicyDirectory,\n} from \"./principalRecoveryDirectory\";\nimport {\n  createPrincipalRecoveryReader,\n  type PrincipalRecoveryMemo,\n} from \"./principalRecoveryMemo\";\nimport { isPrincipalRecoveryOutage } from \"./principalRecoveryOutage\";\n\n/** Discover and verify current directory artifacts, including protected offline recovery. */\nexport async function recoverCurrentOrganizationPolicy(\n  options: PrincipalRecoveryContext,\n  memo?: PrincipalRecoveryMemo,\n) {\n  const input = {\n    ...options,\n    protection: ownPrincipalHistoryProtection(options.protection),\n  };\n  try {\n    let directory: RecoveredPolicyDirectory;\n    try {\n      directory = await createPrincipalRecoveryReader(input, memo).directory(\n        [],\n      );\n    } catch (error) {\n      assertProjectionVerificationCurrent(input.stillCurrent);\n      if (input.offline || !isPrincipalRecoveryOutage(error)) throw error;\n      directory = await createPrincipalRecoveryReader(\n        { ...input, offline: true },\n        memo,\n      ).directory([]);\n    }\n    assertProjectionVerificationCurrent(input.stillCurrent);\n    return {\n      current: directory.current,\n      policy: directory.policy,\n      dependencies: [],\n    };\n  } finally {\n    input.protection.localKey.fill(0);\n  }\n}\n"]}

package/workflows/principals/recoverPrincipalHistoryPage.js

@@ -0,0 +1,30 @@
+import { KeyingVerificationError } from "../../internal/crypto/index.js";
+import { loadRecoveredPrincipalHistoryPage, PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE, } from "./loadRecoveredPrincipalHistoryPage.js";
+import { PrincipalHistoryEvidenceUnavailableError } from "./principalHistoryRecoveryReferences.js";
+import { recoverPrincipalPolicyHistoryWithVersions } from "./recoverPrincipalPolicyHistory.js";
+/** Disposable page proof loss may replay signed pages once online, preserving durable pins. */
+export async function recoverPrincipalHistoryPage(options, beforeVersion) {
+    try {
+        return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);
+    }
+    catch (error) {
+        if (!(error instanceof PrincipalHistoryEvidenceUnavailableError))
+            throw error;
+        // A local-first display read must distinguish disposable proof damage
+        // from a durable fork or an invalid caller citation, which are not wrapped.
+        // Preserve that distinction so the online caller can replay signed pages.
+        if (options.offline)
+            throw new KeyingVerificationError("missing_dependency", "Principal history display proof is unavailable");
+    }
+    const first = Math.max(1, beforeVersion - PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE - 1);
+    await recoverPrincipalPolicyHistoryWithVersions(options, Array.from({ length: beforeVersion - first }, (_, index) => first + index));
+    try {
+        return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);
+    }
+    catch (error) {
+        throw error instanceof PrincipalHistoryEvidenceUnavailableError
+            ? error.verificationError
+            : error;
+    }
+}
+//# sourceMappingURL=recoverPrincipalHistoryPage.js.map

package/workflows/principals/recoverPrincipalHistoryPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoverPrincipalHistoryPage.js","sourceRoot":"","sources":["recoverPrincipalHistoryPage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EACL,iCAAiC,EACjC,mCAAmC,GACpC,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,wCAAwC,EAAE,MAAM,sCAAsC,CAAC;AAEhG,OAAO,EAAE,yCAAyC,EAAE,MAAM,iCAAiC,CAAC;AAE5F,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,OAA6C,EAC7C,aAAqB;IAErB,IAAI,CAAC;QACH,OAAO,MAAM,iCAAiC,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,wCAAwC,CAAC;YAC9D,MAAM,KAAK,CAAC;QACd,sEAAsE;QACtE,4EAA4E;QAC5E,0EAA0E;QAC1E,IAAI,OAAO,CAAC,OAAO;YACjB,MAAM,IAAI,uBAAuB,CAC/B,oBAAoB,EACpB,gDAAgD,CACjD,CAAC;IACN,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,CAAC,EACD,aAAa,GAAG,mCAAmC,GAAG,CAAC,CACxD,CAAC;IACF,MAAM,yCAAyC,CAC7C,OAAO,EACP,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,aAAa,GAAG,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC,CAC3E,CAAC;IACF,IAAI,CAAC;QACH,OAAO,MAAM,iCAAiC,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,YAAY,wCAAwC;YAC7D,CAAC,CAAC,KAAK,CAAC,iBAAiB;YACzB,CAAC,CAAC,KAAK,CAAC;IACZ,CAAC;AACH,CAAC","sourcesContent":["import { KeyingVerificationError } from \"@tearleads/crypto\";\nimport {\n  loadRecoveredPrincipalHistoryPage,\n  PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE,\n} from \"./loadRecoveredPrincipalHistoryPage\";\nimport { PrincipalHistoryEvidenceUnavailableError } from \"./principalHistoryRecoveryReferences\";\nimport type { RecoverPrincipalPolicyHistoryOptions } from \"./principalHistoryRecoveryTypes\";\nimport { recoverPrincipalPolicyHistoryWithVersions } from \"./recoverPrincipalPolicyHistory\";\n\n/** Disposable page proof loss may replay signed pages once online, preserving durable pins. */\nexport async function recoverPrincipalHistoryPage(\n  options: RecoverPrincipalPolicyHistoryOptions,\n  beforeVersion: number,\n) {\n  try {\n    return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);\n  } catch (error) {\n    if (!(error instanceof PrincipalHistoryEvidenceUnavailableError))\n      throw error;\n    // A local-first display read must distinguish disposable proof damage\n    // from a durable fork or an invalid caller citation, which are not wrapped.\n    // Preserve that distinction so the online caller can replay signed pages.\n    if (options.offline)\n      throw new KeyingVerificationError(\n        \"missing_dependency\",\n        \"Principal history display proof is unavailable\",\n      );\n  }\n  const first = Math.max(\n    1,\n    beforeVersion - PRINCIPAL_DISPLAY_HISTORY_PAGE_SIZE - 1,\n  );\n  await recoverPrincipalPolicyHistoryWithVersions(\n    options,\n    Array.from({ length: beforeVersion - first }, (_, index) => first + index),\n  );\n  try {\n    return await loadRecoveredPrincipalHistoryPage(options, beforeVersion);\n  } catch (error) {\n    throw error instanceof PrincipalHistoryEvidenceUnavailableError\n      ? error.verificationError\n      : error;\n  }\n}\n"]}

package/workflows/principals/recoverPrincipalPolicyHistory.d.ts

@@ -5,3 +5,5 @@ import { type RecoveredPrincipalPolicyHistory, type RecoverPrincipalPolicyHistor
  * Retain organization version 1 when the result will establish founder binding.
  */
 export declare function recoverPrincipalPolicyHistory(options: RecoverPrincipalPolicyHistoryOptions): Promise<RecoveredPrincipalPolicyHistory>;
+/** Internal bounded display selection; missing proof rows use the normal single rebuild. */
+export declare function recoverPrincipalPolicyHistoryWithVersions(options: RecoverPrincipalPolicyHistoryOptions, retainedVersions: readonly number[]): Promise<RecoveredPrincipalPolicyHistory>;

package/workflows/principals/recoverPrincipalPolicyHistory.js

@@ -1,4 +1,4 @@
-import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, verifyPrincipalPolicyCheckpoint, verifyPrincipalPolicyCurrent, } from "../../internal/crypto/index.js";
+import { createPrincipalPolicyHistoryVerifier, KeyingVerificationError, PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT, verifyPrincipalPolicyCheckpoint, verifyPrincipalPolicyCurrent, } from "../../internal/crypto/index.js";
 import { assertProjectionVerificationCurrent } from "../../data/keyingProjectionVerification/types.js";
 import { loadPrincipalPolicyCheckpoint } from "../../data/persistence/keyingCheckpointPersistence.js";
 import { preparePrincipalHistoryEvidencePage } from "../../data/persistence/principalHistoryEvidencePersistence.js";
@@ -221,7 +221,18 @@ async function recover(input, allowEvidenceRebuild = true) {
  * The result is a sparse current-policy capability; this does not advance app checkpoints.
  * Retain organization version 1 when the result will establish founder binding.
  */
-export async function recoverPrincipalPolicyHistory(options) {
+export function recoverPrincipalPolicyHistory(options) {
+    return recoverPrincipalPolicyHistoryWithVersions(options, []);
+}
+/** Internal bounded display selection; missing proof rows use the normal single rebuild. */
+export async function recoverPrincipalPolicyHistoryWithVersions(options, retainedVersions) {
+    if (!Array.isArray(retainedVersions) ||
+        retainedVersions.length + (options.retainedReferences?.length ?? 0) >
+            PRINCIPAL_HISTORY_PAGE_ENTRY_LIMIT ||
+        retainedVersions.some((version) => !Number.isSafeInteger(version) ||
+            version < 1 ||
+            version > options.expectedHead.version))
+        throw new KeyingVerificationError("invalid_shape", "Principal display history selection exceeds its bounded range");
     if (options.offline !== undefined && typeof options.offline !== "boolean")
         throw new KeyingVerificationError("invalid_shape", "Invalid principal history transport mode");
     if (!options.organizationId ||
@@ -235,6 +246,7 @@ export async function recoverPrincipalPolicyHistory(options) {
         historyVerification: options.historyVerification ?? "standard",
         expectedHead: structuredClone(options.expectedHead),
         retainedReferences: structuredClone(options.retainedReferences ?? []),
+        retainedVersions: [...retainedVersions],
         protection: ownPrincipalHistoryProtection(options.protection),
     };
     try {