@tearleads/client-sdk 0.0.0-stage → 0.1.13

package/data/persistence/documents/types.d.ts

@@ -0,0 +1,322 @@
+import type { DocumentProjectorRegistryInput, StoredDocumentKind } from "../../documents/documentKinds.js";
+import type { DiscoveredDocumentInput, DocumentSummary } from "../../documents/documentSummary.js";
+import type { DocumentSyncPullContinuation } from "../../documents/shared/pullContinuation.js";
+import type { DocumentRecord as BaseDocumentRecord, PendingUpdateFields, PendingUpdateRecord } from "../../sqlite/documentPersistence.js";
+import type { ExecSql } from "../../sqlite/sqlSchema.js";
+export type { PendingUpdateRecord } from "../../sqlite/documentPersistence.js";
+export interface StoredDocumentRecord extends BaseDocumentRecord {
+    containerId: string | null;
+    documentKind?: StoredDocumentKind;
+    text: string;
+    title?: string;
+}
+export type DiscardDocumentToShellResult = {
+    discarded: false;
+} | {
+    discarded: true;
+    documentKind: StoredDocumentKind;
+};
+export interface PendingUpdateInsert extends PendingUpdateFields {
+    localId: string;
+}
+/**
+ * The identity a pending attachment upload reuses across attempts so a retry
+ * (next sync pass or after a restart) reproduces byte-identical encrypted bytes
+ * and resumes the same multipart stage instead of orphaning it. `contentKey` and
+ * the chunk `nonceSeed` are base64. `partSize`/`stageId` are filled in once the
+ * multipart stage has been opened and remain null before that.
+ */
+export interface PendingAttachmentUploadIdentity {
+    blobId: string;
+    contentKey: string;
+    contentKeyEpoch: number;
+    nonceSeed: string;
+    partSize: number | null;
+    plaintextSha256: string;
+    stageId: string | null;
+}
+export interface PendingAttachmentRecord {
+    byteLength: number;
+    contentSha256: string;
+    localId: string;
+    mimeType: string | null;
+    name: string;
+    slotId: string;
+    storageKey: string;
+    upload?: PendingAttachmentUploadIdentity | null;
+}
+export interface LocalAttachmentRecord {
+    blobId: string | null;
+    byteLength: number;
+    contentSha256: string;
+    detachedAt: string | null;
+    localId: string;
+    mimeType: string | null;
+    slotId: string;
+    storageKey: string;
+}
+export interface AttachmentStagingRows {
+    localAttachments: ReadonlyArray<LocalAttachmentRecord>;
+    pendingAttachments: ReadonlyArray<PendingAttachmentRecord>;
+}
+export interface AttachmentRemovalRows {
+    mode: "delete" | "detach";
+    slotId: string;
+    storageKey: string;
+}
+export interface DocumentHistoryRestoreState {
+    snapshot: string;
+    tailUpdates: readonly {
+        origin: "local" | "remote";
+        updateData: string;
+    }[];
+}
+export interface RelinkPersistedDocumentInput {
+    accessEpoch: number;
+    accessStateHash?: string | null;
+    containerId: string;
+    documentId: string | null;
+    localId: string;
+}
+export interface ContainerDocumentTombstoneInput {
+    containerId: string;
+    documentId: string;
+    /** Epoch of the verified head; apply refuses a head below local state. */
+    accessEpoch: number;
+    /** Verified head link set (omits `containerId`); apply needs signed evidence. */
+    linkedContainerIds: ReadonlyArray<string>;
+    updatedAt: string;
+}
+export type DocumentSummarySortDirection = "asc" | "desc";
+export type DocumentSummarySortKey = "kind" | "title" | "updated";
+export interface DocumentSummarySort {
+    readonly direction: DocumentSummarySortDirection;
+    readonly key: DocumentSummarySortKey;
+}
+export interface ListDocumentSummariesInput {
+    documentKind?: StoredDocumentKind | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    sort?: DocumentSummarySort | undefined;
+}
+export interface DocumentSummaryList {
+    readonly rows: ReadonlyArray<DocumentSummary>;
+    readonly totalCount: number;
+}
+export interface DocumentsPersistence {
+    /**
+     * The adapter guarantees that recovery checkpoint replacement, selection of
+     * covered local history, rejection of unproven ordinary pending rows, and
+     * quarantine of every queued checkpoint artifact share the guarded
+     * `commitDocumentMutation` transaction, which also advances the canonical
+     * recovery generation. An unrelated history tail not covered by the rebuild
+     * must abort that transaction.
+     */
+    readonly supportsAtomicRecoveryHistoryPruning: boolean;
+    /**
+     * Atomically create the canonical row, standard projections, and birth
+     * checkpoint. Returns null when another initializer already owns localId.
+     */
+    createDocumentWithHistoryCheckpoint: (execSql: ExecSql, document: StoredDocumentRecord, historyCheckpoint: {
+        endVersionVector: string;
+        snapshot: string;
+    }, options: {
+        pendingUpdate?: PendingUpdateFields;
+        /** Recheck volatile caller ownership inside the create transaction. */
+        stillCurrent?: (() => boolean) | undefined;
+        updatedAt?: string;
+    } | undefined, saveClientProjection: (transactionExecSql: ExecSql, updatedAt: string) => Promise<void>) => Promise<string | null>;
+    /**
+     * Conditionally commit one already-prepared mutation against the exact
+     * durable record it was derived from. The identity/progress comparison,
+     * attachment and history writes, accepted-queue settlement,
+     * canonical/projection save, and client projection callback must share one
+     * adapter transaction.
+     */
+    commitDocumentMutation: (execSql: ExecSql, input: {
+        acceptedPendingUpdateIds: readonly string[];
+        attachmentRemoval?: AttachmentRemovalRows | undefined;
+        attachmentStaging?: AttachmentStagingRows | undefined;
+        clearSyncFailure?: boolean | undefined;
+        document: StoredDocumentRecord;
+        expectedRecord: StoredDocumentRecord;
+        historyCheckpoint?: {
+            coveredTailIds: readonly string[];
+            endVersionVector: string;
+            pruneCoveredLocalState: boolean;
+            snapshot: string;
+        } | undefined;
+        historyUpdateOrigin?: "local" | "remote" | undefined;
+        historyUpdates?: readonly string[] | undefined;
+        pendingUpdate?: PendingUpdateFields | undefined;
+        settleAcceptedPendingOnConflict: boolean;
+        /**
+         * Recheck volatile caller ownership inside the adapter transaction,
+         * before any durable side effect. A false result aborts the commit.
+         */
+        stillCurrent?: (() => boolean) | undefined;
+        updatedAt?: string | undefined;
+    }, saveClientProjection: (transactionExecSql: ExecSql, updatedAt: string) => Promise<void>) => Promise<{
+        committed: true;
+        updatedAt: string;
+    } | {
+        committed: false;
+        currentRecord: StoredDocumentRecord | null;
+    }>;
+    /** Settle acknowledged rows only while the response's security identity survives. */
+    settleAcceptedPendingUpdates: (execSql: ExecSql, input: {
+        expectedRecord: StoredDocumentRecord;
+        pendingUpdateIds: readonly string[];
+    }) => Promise<StoredDocumentRecord | null>;
+    ensureSchema: (execSql: ExecSql) => Promise<void>;
+    listDocuments: (execSql: ExecSql) => Promise<DocumentSummary[]>;
+    listDocumentSummaries: (execSql: ExecSql, input?: ListDocumentSummariesInput) => Promise<DocumentSummaryList>;
+    listDocumentsByContainerIdsOrDocumentIds: (execSql: ExecSql, input: {
+        containerIds: ReadonlyArray<string>;
+        documentIds: ReadonlyArray<string>;
+    }) => Promise<DocumentSummary[]>;
+    findDocumentLocalIdsByContainerId: (execSql: ExecSql, containerId: string) => Promise<string[]>;
+    /**
+     * Select one local row for a remote document identity. Prefer any row with
+     * queued updates or a deferred-sync frontier, then break duplicates by
+     * updatedAt and localId descending.
+     */
+    findLocalIdByDocumentId: (execSql: ExecSql, documentId: string) => Promise<string | null>;
+    /** Canonical-row probe; false authorizes destructive orphan teardown. */
+    hasDocument: (execSql: ExecSql, localId: string) => Promise<boolean>;
+    /** Observe whether the canonical row still names the expected remote stream. */
+    documentIdentityMatches: (execSql: ExecSql, localId: string, expectedDocumentId: string | null, expectedRecoveryGeneration: number) => Promise<boolean>;
+    loadDocument: (execSql: ExecSql, localId: string) => Promise<StoredDocumentRecord | null>;
+    /** Read the canonical record and its history from one database snapshot. */
+    loadDocumentWithHistoryRestoreState: (execSql: ExecSql, localId: string) => Promise<{
+        document: StoredDocumentRecord | null;
+        historyRestoreState: DocumentHistoryRestoreState | null;
+    }>;
+    /** Read every document-store startup row from one database snapshot. */
+    loadDocumentStoreState: (execSql: ExecSql, localId: string) => Promise<{
+        document: StoredDocumentRecord | null;
+        historyRestoreState: DocumentHistoryRestoreState | null;
+        localAttachments: LocalAttachmentRecord[];
+        pendingAttachments: PendingAttachmentRecord[];
+    }>;
+    /**
+     * Atomically replace the exact rejected pull continuation with the durable
+     * recovery marker when every supplied sync-identity field still matches.
+     * Return the authoritative current record after the compare-and-set, or
+     * null when the canonical row no longer exists. A CAS loss returns the
+     * winning record so the live store can adopt its newer progress.
+     */
+    invalidatePullContinuation: (execSql: ExecSql, input: {
+        accessEpoch: number;
+        accessStateHash: string | null;
+        continuation: DocumentSyncPullContinuation;
+        contentKeyBundle: string | null;
+        documentId: string;
+        documentKekTargets: string | null;
+        documentManifestBundle: string | null;
+        lastCommitLsn: string | null;
+        localId: string;
+    }) => Promise<{
+        historyRestoreState: DocumentHistoryRestoreState | null;
+        record: StoredDocumentRecord;
+    } | null>;
+    loadDocumentContainer: (execSql: ExecSql, localId: string) => Promise<{
+        containerId: string | null;
+    } | undefined>;
+    saveDocument: (execSql: ExecSql, document: StoredDocumentRecord, options?: {
+        updatedAt?: string;
+    }) => Promise<string>;
+    /**
+     * Durable full-history support (checkpoint + append-only tail) — the ONLY
+     * persisted content source. REQUIRED: a persistence without these could
+     * report successful writes whose documents reopen empty.
+     */
+    appendHistoryUpdates: (execSql: ExecSql, input: {
+        localId: string;
+        origin: "local" | "remote";
+        updates: readonly string[];
+    }) => Promise<void>;
+    loadHistoryRestoreState: (execSql: ExecSql, localId: string) => Promise<DocumentHistoryRestoreState | null>;
+    readHistoryTailSize: (execSql: ExecSql, localId: string) => Promise<{
+        byteLength: number;
+        hasCheckpoint: boolean;
+        rowCount: number;
+    }>;
+    listHistoryTailEntries: (execSql: ExecSql, localId: string) => Promise<{
+        id: string;
+        updateData: string;
+    }[]>;
+    replaceHistoryCheckpoint: (execSql: ExecSql, input: {
+        coveredTailIds: readonly string[];
+        endVersionVector: string;
+        force?: boolean;
+        localId: string;
+        snapshot: string;
+        stillCurrent?: () => boolean;
+    }) => Promise<void>;
+    saveDocumentAndDeletePendingUpdates: (execSql: ExecSql, document: StoredDocumentRecord, pendingUpdateIds: readonly string[], options?: {
+        updatedAt?: string;
+    }) => Promise<string>;
+    deleteDocument: (execSql: ExecSql, localId: string) => Promise<void>;
+    /**
+     * Delete the canonical row and every side row only when its security identity
+     * still matches the captured record. The comparison, deletes, and client
+     * projection callback must share one write transaction.
+     */
+    deleteDocumentIfMatches: (execSql: ExecSql, expectedRecord: StoredDocumentRecord, deleteClientProjection: (transactionExecSql: ExecSql) => Promise<void>) => Promise<boolean>;
+    /**
+     * Delete orphaned side rows only if the canonical document is still absent.
+     * The absence check, row cleanup, and client projection callback must share
+     * one write transaction so a concurrent create is preserved.
+     */
+    deleteDocumentSideRowsIfAbsent: (execSql: ExecSql, localId: string, expectedDocumentId: string | null, deleteClientProjection: (transactionExecSql: ExecSql) => Promise<void>) => Promise<boolean>;
+    upsertDiscoveredDocument: (execSql: ExecSql, input: DiscoveredDocumentInput) => Promise<DocumentSummary>;
+    relinkPersistedDocument: (execSql: ExecSql, input: RelinkPersistedDocumentInput) => Promise<DocumentSummary | null>;
+    listPendingUpdates: (execSql: ExecSql, localId: string) => Promise<PendingUpdateRecord[]>;
+    rekeyPendingUpdate: (execSql: ExecSql, id: string) => Promise<string | null>;
+    listPendingAttachments: (execSql: ExecSql, localId: string) => Promise<PendingAttachmentRecord[]>;
+    listLocalAttachments: (execSql: ExecSql, localId: string) => Promise<LocalAttachmentRecord[]>;
+    /**
+     * Durably append the outgoing row and matching local-history tail entry.
+     * When expectations are supplied, compare the document identity and recovery
+     * generation with the canonical row inside that same mutation and return
+     * false on absence or mismatch. Adapters must not insert either row.
+     */
+    enqueuePendingUpdate: (execSql: ExecSql, pendingUpdate: PendingUpdateInsert, options?: {
+        expectedDocumentId: string | null;
+        expectedRecoveryGeneration: number;
+    }) => Promise<boolean>;
+    /** Replace a hydrated copy only if its observed durable slot and live document still match. */
+    saveHydratedAttachment: (execSql: ExecSql, input: {
+        attachment: LocalAttachmentRecord;
+        expectedStorageKey: string | null;
+        expectedSnapshotEndVersion: string | null;
+        stillCurrent: () => boolean;
+    }) => Promise<boolean>;
+    saveLocalAttachment: (execSql: ExecSql, attachment: LocalAttachmentRecord) => Promise<void>;
+    deleteLocalAttachment: (execSql: ExecSql, localId: string, slotId: string, storageKey: string) => Promise<void>;
+    markLocalAttachmentDetached: (execSql: ExecSql, localId: string, slotId: string, storageKey: string) => Promise<void>;
+    savePendingAttachment: (execSql: ExecSql, attachment: PendingAttachmentRecord) => Promise<void>;
+    deletePendingUpdate: (execSql: ExecSql, id: string) => Promise<void>;
+    deletePendingUpdates: (execSql: ExecSql, localId: string) => Promise<void>;
+    deletePendingAttachment: (execSql: ExecSql, localId: string, slotId: string, storageKey: string) => Promise<void>;
+    deletePendingAttachments: (execSql: ExecSql, localId: string) => Promise<void>;
+    /**
+     * Atomically convert a stuck document's local state to the
+     * freshly-discovered-share shell (see the SQL implementation's doc
+     * comment). The projector registry clears the document-kind client
+     * projection in the same transaction — those tables live with the app's
+     * projector definitions, so the CALLER'S registry is required (the default
+     * registry knows no app kinds, and a discard that silently kept a
+     * contact's or card's projected fields would leak the discarded values).
+     * The method itself is optional: implementations without the full document
+     * schema (container metadata, simple doubles) simply do not offer the
+     * discard escape hatch.
+     */
+    /**
+     * `expectedDocumentId` is revalidated against the loaded record inside the
+     * serialized mutation: a stale caller (or a relink that raced the request)
+     * must never discard a different identity's edits.
+     */
+    discardDocumentToShell?: (execSql: ExecSql, localId: string, expectedDocumentId: string, documentProjectors: DocumentProjectorRegistryInput) => Promise<DiscardDocumentToShellResult>;
+}

package/data/persistence/documents/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/data/persistence/documents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  DocumentProjectorRegistryInput,\n  StoredDocumentKind,\n} from \"../../documents/documentKinds\";\nimport type {\n  DiscoveredDocumentInput,\n  DocumentSummary,\n} from \"../../documents/documentSummary\";\nimport type { DocumentSyncPullContinuation } from \"../../documents/shared/pullContinuation\";\nimport type {\n  DocumentRecord as BaseDocumentRecord,\n  PendingUpdateFields,\n  PendingUpdateRecord,\n} from \"../../sqlite/documentPersistence\";\nimport type { ExecSql } from \"../../sqlite/sqlSchema\";\n\nexport type { PendingUpdateRecord } from \"../../sqlite/documentPersistence\";\n\nexport interface StoredDocumentRecord extends BaseDocumentRecord {\n  containerId: string | null;\n  documentKind?: StoredDocumentKind;\n  text: string;\n  title?: string;\n}\n\nexport type DiscardDocumentToShellResult =\n  | { discarded: false }\n  | {\n      discarded: true;\n      documentKind: StoredDocumentKind;\n    };\n\nexport interface PendingUpdateInsert extends PendingUpdateFields {\n  localId: string;\n}\n\n/**\n * The identity a pending attachment upload reuses across attempts so a retry\n * (next sync pass or after a restart) reproduces byte-identical encrypted bytes\n * and resumes the same multipart stage instead of orphaning it. `contentKey` and\n * the chunk `nonceSeed` are base64. `partSize`/`stageId` are filled in once the\n * multipart stage has been opened and remain null before that.\n */\nexport interface PendingAttachmentUploadIdentity {\n  blobId: string;\n  contentKey: string;\n  contentKeyEpoch: number;\n  nonceSeed: string;\n  partSize: number | null;\n  plaintextSha256: string;\n  stageId: string | null;\n}\n\nexport interface PendingAttachmentRecord {\n  byteLength: number;\n  contentSha256: string;\n  localId: string;\n  mimeType: string | null;\n  name: string;\n  slotId: string;\n  storageKey: string;\n  upload?: PendingAttachmentUploadIdentity | null;\n}\n\nexport interface LocalAttachmentRecord {\n  blobId: string | null;\n  byteLength: number;\n  // Plaintext digest of the bytes at `storageKey`. Compared with the digest\n  // the document content records for the slot: a held copy that differs is a\n  // validly signed served binding the document has not recorded (yet).\n  contentSha256: string;\n  // Set once the slot is unlinked from a synced document and cleared when the\n  // slot is written again. The record survives the unlink so the next sync can\n  // still detach the remote binding; `detachedAt` is what keeps the local read\n  // models from reporting the slot as a live blob reference in the meantime.\n  detachedAt: string | null;\n  localId: string;\n  mimeType: string | null;\n  slotId: string;\n  storageKey: string;\n}\n\nexport interface AttachmentStagingRows {\n  localAttachments: ReadonlyArray<LocalAttachmentRecord>;\n  pendingAttachments: ReadonlyArray<PendingAttachmentRecord>;\n}\n\nexport interface AttachmentRemovalRows {\n  mode: \"delete\" | \"detach\";\n  slotId: string;\n  storageKey: string;\n}\n\nexport interface DocumentHistoryRestoreState {\n  snapshot: string;\n  tailUpdates: readonly {\n    origin: \"local\" | \"remote\";\n    updateData: string;\n  }[];\n}\n\nexport interface RelinkPersistedDocumentInput {\n  accessEpoch: number;\n  accessStateHash?: string | null;\n  containerId: string;\n  documentId: string | null;\n  localId: string;\n}\n\nexport interface ContainerDocumentTombstoneInput {\n  containerId: string;\n  documentId: string;\n  /** Epoch of the verified head; apply refuses a head below local state. */\n  accessEpoch: number;\n  /** Verified head link set (omits `containerId`); apply needs signed evidence. */\n  linkedContainerIds: ReadonlyArray<string>;\n  updatedAt: string;\n}\n\nexport type DocumentSummarySortDirection = \"asc\" | \"desc\";\nexport type DocumentSummarySortKey = \"kind\" | \"title\" | \"updated\";\n\nexport interface DocumentSummarySort {\n  readonly direction: DocumentSummarySortDirection;\n  readonly key: DocumentSummarySortKey;\n}\n\nexport interface ListDocumentSummariesInput {\n  documentKind?: StoredDocumentKind | undefined;\n  limit?: number | undefined;\n  offset?: number | undefined;\n  sort?: DocumentSummarySort | undefined;\n}\n\nexport interface DocumentSummaryList {\n  readonly rows: ReadonlyArray<DocumentSummary>;\n  readonly totalCount: number;\n}\n\nexport interface DocumentsPersistence {\n  /**\n   * The adapter guarantees that recovery checkpoint replacement, selection of\n   * covered local history, rejection of unproven ordinary pending rows, and\n   * quarantine of every queued checkpoint artifact share the guarded\n   * `commitDocumentMutation` transaction, which also advances the canonical\n   * recovery generation. An unrelated history tail not covered by the rebuild\n   * must abort that transaction.\n   */\n  readonly supportsAtomicRecoveryHistoryPruning: boolean;\n  /**\n   * Atomically create the canonical row, standard projections, and birth\n   * checkpoint. Returns null when another initializer already owns localId.\n   */\n  createDocumentWithHistoryCheckpoint: (\n    execSql: ExecSql,\n    document: StoredDocumentRecord,\n    historyCheckpoint: {\n      endVersionVector: string;\n      snapshot: string;\n    },\n    options:\n      | {\n          pendingUpdate?: PendingUpdateFields;\n          /** Recheck volatile caller ownership inside the create transaction. */\n          stillCurrent?: (() => boolean) | undefined;\n          updatedAt?: string;\n        }\n      | undefined,\n    saveClientProjection: (\n      transactionExecSql: ExecSql,\n      updatedAt: string,\n    ) => Promise<void>,\n  ) => Promise<string | null>;\n  /**\n   * Conditionally commit one already-prepared mutation against the exact\n   * durable record it was derived from. The identity/progress comparison,\n   * attachment and history writes, accepted-queue settlement,\n   * canonical/projection save, and client projection callback must share one\n   * adapter transaction.\n   */\n  commitDocumentMutation: (\n    execSql: ExecSql,\n    input: {\n      acceptedPendingUpdateIds: readonly string[];\n      attachmentRemoval?: AttachmentRemovalRows | undefined;\n      attachmentStaging?: AttachmentStagingRows | undefined;\n      clearSyncFailure?: boolean | undefined;\n      document: StoredDocumentRecord;\n      expectedRecord: StoredDocumentRecord;\n      historyCheckpoint?:\n        | {\n            coveredTailIds: readonly string[];\n            endVersionVector: string;\n            pruneCoveredLocalState: boolean;\n            snapshot: string;\n          }\n        | undefined;\n      historyUpdateOrigin?: \"local\" | \"remote\" | undefined;\n      historyUpdates?: readonly string[] | undefined;\n      pendingUpdate?: PendingUpdateFields | undefined;\n      settleAcceptedPendingOnConflict: boolean;\n      /**\n       * Recheck volatile caller ownership inside the adapter transaction,\n       * before any durable side effect. A false result aborts the commit.\n       */\n      stillCurrent?: (() => boolean) | undefined;\n      updatedAt?: string | undefined;\n    },\n    saveClientProjection: (\n      transactionExecSql: ExecSql,\n      updatedAt: string,\n    ) => Promise<void>,\n  ) => Promise<\n    | { committed: true; updatedAt: string }\n    | { committed: false; currentRecord: StoredDocumentRecord | null }\n  >;\n  /** Settle acknowledged rows only while the response's security identity survives. */\n  settleAcceptedPendingUpdates: (\n    execSql: ExecSql,\n    input: {\n      expectedRecord: StoredDocumentRecord;\n      pendingUpdateIds: readonly string[];\n    },\n  ) => Promise<StoredDocumentRecord | null>;\n  ensureSchema: (execSql: ExecSql) => Promise<void>;\n  listDocuments: (execSql: ExecSql) => Promise<DocumentSummary[]>;\n  listDocumentSummaries: (\n    execSql: ExecSql,\n    input?: ListDocumentSummariesInput,\n  ) => Promise<DocumentSummaryList>;\n  listDocumentsByContainerIdsOrDocumentIds: (\n    execSql: ExecSql,\n    input: {\n      containerIds: ReadonlyArray<string>;\n      documentIds: ReadonlyArray<string>;\n    },\n  ) => Promise<DocumentSummary[]>;\n  findDocumentLocalIdsByContainerId: (\n    execSql: ExecSql,\n    containerId: string,\n  ) => Promise<string[]>;\n  /**\n   * Select one local row for a remote document identity. Prefer any row with\n   * queued updates or a deferred-sync frontier, then break duplicates by\n   * updatedAt and localId descending.\n   */\n  findLocalIdByDocumentId: (\n    execSql: ExecSql,\n    documentId: string,\n  ) => Promise<string | null>;\n  /** Canonical-row probe; false authorizes destructive orphan teardown. */\n  hasDocument: (execSql: ExecSql, localId: string) => Promise<boolean>;\n  /** Observe whether the canonical row still names the expected remote stream. */\n  documentIdentityMatches: (\n    execSql: ExecSql,\n    localId: string,\n    expectedDocumentId: string | null,\n    expectedRecoveryGeneration: number,\n  ) => Promise<boolean>;\n  loadDocument: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<StoredDocumentRecord | null>;\n  /** Read the canonical record and its history from one database snapshot. */\n  loadDocumentWithHistoryRestoreState: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<{\n    document: StoredDocumentRecord | null;\n    historyRestoreState: DocumentHistoryRestoreState | null;\n  }>;\n  /** Read every document-store startup row from one database snapshot. */\n  loadDocumentStoreState: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<{\n    document: StoredDocumentRecord | null;\n    historyRestoreState: DocumentHistoryRestoreState | null;\n    localAttachments: LocalAttachmentRecord[];\n    pendingAttachments: PendingAttachmentRecord[];\n  }>;\n  /**\n   * Atomically replace the exact rejected pull continuation with the durable\n   * recovery marker when every supplied sync-identity field still matches.\n   * Return the authoritative current record after the compare-and-set, or\n   * null when the canonical row no longer exists. A CAS loss returns the\n   * winning record so the live store can adopt its newer progress.\n   */\n  invalidatePullContinuation: (\n    execSql: ExecSql,\n    input: {\n      accessEpoch: number;\n      accessStateHash: string | null;\n      continuation: DocumentSyncPullContinuation;\n      contentKeyBundle: string | null;\n      documentId: string;\n      documentKekTargets: string | null;\n      documentManifestBundle: string | null;\n      lastCommitLsn: string | null;\n      localId: string;\n    },\n  ) => Promise<{\n    historyRestoreState: DocumentHistoryRestoreState | null;\n    record: StoredDocumentRecord;\n  } | null>;\n  // Read the authoritative container placement for a locally persisted document\n  // straight from its projection row. Returns `undefined` when no projection row\n  // exists yet (a first create/discovery persist), so a caller can distinguish\n  // that from a row that legitimately carries a null container (a document\n  // unlinked from every container). Container placement is owned by the\n  // link/tombstone/discovery layer, so a content-metadata persist reads this to\n  // avoid republishing a stale in-memory container.\n  loadDocumentContainer: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<{ containerId: string | null } | undefined>;\n  saveDocument: (\n    execSql: ExecSql,\n    document: StoredDocumentRecord,\n    options?: {\n      updatedAt?: string;\n    },\n  ) => Promise<string>;\n  /**\n   * Durable full-history support (checkpoint + append-only tail) — the ONLY\n   * persisted content source. REQUIRED: a persistence without these could\n   * report successful writes whose documents reopen empty.\n   */\n  appendHistoryUpdates: (\n    execSql: ExecSql,\n    input: {\n      localId: string;\n      origin: \"local\" | \"remote\";\n      updates: readonly string[];\n    },\n  ) => Promise<void>;\n  loadHistoryRestoreState: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<DocumentHistoryRestoreState | null>;\n  readHistoryTailSize: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<{\n    byteLength: number;\n    hasCheckpoint: boolean;\n    rowCount: number;\n  }>;\n  listHistoryTailEntries: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<{ id: string; updateData: string }[]>;\n  replaceHistoryCheckpoint: (\n    execSql: ExecSql,\n    input: {\n      coveredTailIds: readonly string[];\n      endVersionVector: string;\n      force?: boolean;\n      localId: string;\n      snapshot: string;\n      stillCurrent?: () => boolean;\n    },\n  ) => Promise<void>;\n  saveDocumentAndDeletePendingUpdates: (\n    execSql: ExecSql,\n    document: StoredDocumentRecord,\n    pendingUpdateIds: readonly string[],\n    options?: {\n      updatedAt?: string;\n    },\n  ) => Promise<string>;\n  deleteDocument: (execSql: ExecSql, localId: string) => Promise<void>;\n  /**\n   * Delete the canonical row and every side row only when its security identity\n   * still matches the captured record. The comparison, deletes, and client\n   * projection callback must share one write transaction.\n   */\n  deleteDocumentIfMatches: (\n    execSql: ExecSql,\n    expectedRecord: StoredDocumentRecord,\n    deleteClientProjection: (transactionExecSql: ExecSql) => Promise<void>,\n  ) => Promise<boolean>;\n  /**\n   * Delete orphaned side rows only if the canonical document is still absent.\n   * The absence check, row cleanup, and client projection callback must share\n   * one write transaction so a concurrent create is preserved.\n   */\n  deleteDocumentSideRowsIfAbsent: (\n    execSql: ExecSql,\n    localId: string,\n    expectedDocumentId: string | null,\n    deleteClientProjection: (transactionExecSql: ExecSql) => Promise<void>,\n  ) => Promise<boolean>;\n  upsertDiscoveredDocument: (\n    execSql: ExecSql,\n    input: DiscoveredDocumentInput,\n  ) => Promise<DocumentSummary>;\n  relinkPersistedDocument: (\n    execSql: ExecSql,\n    input: RelinkPersistedDocumentInput,\n  ) => Promise<DocumentSummary | null>;\n  listPendingUpdates: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<PendingUpdateRecord[]>;\n  rekeyPendingUpdate: (execSql: ExecSql, id: string) => Promise<string | null>;\n  listPendingAttachments: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<PendingAttachmentRecord[]>;\n  listLocalAttachments: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<LocalAttachmentRecord[]>;\n  /**\n   * Durably append the outgoing row and matching local-history tail entry.\n   * When expectations are supplied, compare the document identity and recovery\n   * generation with the canonical row inside that same mutation and return\n   * false on absence or mismatch. Adapters must not insert either row.\n   */\n  enqueuePendingUpdate: (\n    execSql: ExecSql,\n    pendingUpdate: PendingUpdateInsert,\n    options?: {\n      expectedDocumentId: string | null;\n      expectedRecoveryGeneration: number;\n    },\n  ) => Promise<boolean>;\n  /** Replace a hydrated copy only if its observed durable slot and live document still match. */\n  saveHydratedAttachment: (\n    execSql: ExecSql,\n    input: {\n      attachment: LocalAttachmentRecord;\n      expectedStorageKey: string | null;\n      expectedSnapshotEndVersion: string | null;\n      stillCurrent: () => boolean;\n    },\n  ) => Promise<boolean>;\n  saveLocalAttachment: (\n    execSql: ExecSql,\n    attachment: LocalAttachmentRecord,\n  ) => Promise<void>;\n  deleteLocalAttachment: (\n    execSql: ExecSql,\n    localId: string,\n    slotId: string,\n    storageKey: string,\n  ) => Promise<void>;\n  markLocalAttachmentDetached: (\n    execSql: ExecSql,\n    localId: string,\n    slotId: string,\n    storageKey: string,\n  ) => Promise<void>;\n  savePendingAttachment: (\n    execSql: ExecSql,\n    attachment: PendingAttachmentRecord,\n  ) => Promise<void>;\n  deletePendingUpdate: (execSql: ExecSql, id: string) => Promise<void>;\n  deletePendingUpdates: (execSql: ExecSql, localId: string) => Promise<void>;\n  deletePendingAttachment: (\n    execSql: ExecSql,\n    localId: string,\n    slotId: string,\n    storageKey: string,\n  ) => Promise<void>;\n  deletePendingAttachments: (\n    execSql: ExecSql,\n    localId: string,\n  ) => Promise<void>;\n  /**\n   * Atomically convert a stuck document's local state to the\n   * freshly-discovered-share shell (see the SQL implementation's doc\n   * comment). The projector registry clears the document-kind client\n   * projection in the same transaction — those tables live with the app's\n   * projector definitions, so the CALLER'S registry is required (the default\n   * registry knows no app kinds, and a discard that silently kept a\n   * contact's or card's projected fields would leak the discarded values).\n   * The method itself is optional: implementations without the full document\n   * schema (container metadata, simple doubles) simply do not offer the\n   * discard escape hatch.\n   */\n  /**\n   * `expectedDocumentId` is revalidated against the loaded record inside the\n   * serialized mutation: a stale caller (or a relink that raced the request)\n   * must never discard a different identity's edits.\n   */\n  discardDocumentToShell?: (\n    execSql: ExecSql,\n    localId: string,\n    expectedDocumentId: string,\n    documentProjectors: DocumentProjectorRegistryInput,\n  ) => Promise<DiscardDocumentToShellResult>;\n}\n"]}

package/data/persistence/keyingCheckpointAdvancePersistence.js

@@ -0,0 +1,200 @@
+import { KeyingVerificationError, verifyAccessManifestLocalCheckpoint, verifyPrincipalPolicyCheckpoint, } from "../../internal/crypto/index.js";
+import { keyingCheckpointTables, principalPolicyTables, } from "../sqlite/schema.js";
+import { getClientSQLitePersistenceRuntime, } from "../sqlite/sqlitePersistenceRuntime.js";
+import { ensureSqlTables } from "../sqlite/sqlSchema.js";
+import { storeDocumentPurgeCheckpointInTransaction, } from "./documentPurgeCheckpointPersistence.js";
+import { validateAccessManifestCheckpointEvidence } from "./keyingCheckpointEvidence.js";
+import { accessManifestObjectKey, loadStoredAccessManifestCheckpoint, loadStoredPrincipalPolicyCheckpoint, principalPolicyKey, upsertAccessManifestCheckpointInTransaction, upsertPrincipalPolicyCheckpointInTransaction, } from "./keyingCheckpointPersistence.js";
+import { assertContainerNotRetired } from "./principalGrantRetirementPersistence.js";
+import { assertPrincipalPolicyBundleStoredInTransaction, writePrincipalPolicyBundleInTransaction, } from "./principalPolicyPersistence.js";
+import { assertBundleMatchesVerifiedPolicy } from "./verifiedPrincipalPolicyBundle.js";
+function validateAccessAdvance(advance, localCheckpoint) {
+    const current = {
+        ...advance.head.checkpoint,
+        previousManifestHash: advance.head.manifest.previousManifestHash,
+    };
+    const predecessors = [...advance.predecessors].sort((left, right) => left.checkpoint.epoch - right.checkpoint.epoch);
+    if (localCheckpoint && current.epoch <= localCheckpoint.epoch) {
+        verifyAccessManifestLocalCheckpoint({
+            current,
+            localCheckpoint,
+            checkpointPredecessors: undefined,
+        });
+    }
+    validateAccessManifestCheckpointEvidence({
+        head: advance.head,
+        predecessors,
+        localCheckpoint,
+    });
+    verifyAccessManifestLocalCheckpoint({
+        current,
+        localCheckpoint,
+        checkpointPredecessors: predecessors.filter((manifest) => localCheckpoint !== null &&
+            manifest.checkpoint.epoch > localCheckpoint.epoch &&
+            manifest.checkpoint.epoch < current.epoch),
+    });
+    return {
+        checkpoint: advance.head.checkpoint,
+    };
+}
+async function validateAccessAdvances(tx, advances) {
+    const pending = new Map();
+    for (const advance of advances) {
+        await assertContainerNotRetired(tx, advance.head.checkpoint);
+        const key = accessManifestObjectKey(advance.head.checkpoint);
+        if (pending.has(key)) {
+            throw new KeyingVerificationError("equivocation", `projection declares multiple access checkpoint heads for ${key}`);
+        }
+        const localCheckpoint = await loadStoredAccessManifestCheckpoint(tx, advance.head.checkpoint);
+        pending.set(key, validateAccessAdvance(advance, localCheckpoint));
+    }
+    return pending;
+}
+function extendsObservedPolicy(head, candidate) {
+    const history = "retainedHistory" in head ? head.retainedHistory : head.history;
+    return (history?.some(({ state }) => state.principalType === candidate.principalType &&
+        state.principalId === candidate.principalId &&
+        state.version === candidate.version &&
+        state.stateHash === candidate.stateHash) ?? false);
+}
+async function validatePolicyAdvances(tx, policies) {
+    const policiesByPrincipal = new Map();
+    for (const policy of policies) {
+        const key = principalPolicyKey(policy);
+        const candidates = policiesByPrincipal.get(key) ?? [];
+        candidates.push(policy);
+        policiesByPrincipal.set(key, candidates);
+    }
+    const pending = new Map();
+    for (const key of [...policiesByPrincipal.keys()].sort()) {
+        const candidates = policiesByPrincipal.get(key) ?? [];
+        const maxVersion = Math.max(...candidates.map((policy) => policy.version));
+        const heads = candidates.filter((policy) => policy.version === maxVersion);
+        const head = heads[0];
+        if (!head) {
+            continue;
+        }
+        if (heads.some((candidate) => candidate.stateHash !== head.stateHash)) {
+            throw new KeyingVerificationError("equivocation", `principal policy declares conflicting heads for ${key}`);
+        }
+        for (const candidate of candidates) {
+            if (candidate.version === head.version) {
+                continue;
+            }
+            if (!extendsObservedPolicy(head, candidate)) {
+                throw new KeyingVerificationError("stale_predecessor", `principal policy head does not extend observed state for ${key}`);
+            }
+        }
+        const localCheckpoint = await loadStoredPrincipalPolicyCheckpoint(tx, head);
+        verifyPrincipalPolicyCheckpoint({
+            chain: "retainedHistory" in head ? head.retainedHistory : (head.history ?? []),
+            currentState: head.state,
+            localCheckpoint,
+        });
+        pending.set(key, head);
+    }
+    return pending;
+}
+async function writeAccessCheckpoints(tx, pending, updatedAt) {
+    for (const { checkpoint } of pending.values()) {
+        await upsertAccessManifestCheckpointInTransaction(tx, checkpoint, updatedAt);
+    }
+}
+async function writePolicyCheckpoints(tx, pending, updatedAt, organizationId) {
+    for (const policy of pending.values()) {
+        await upsertPrincipalPolicyCheckpointInTransaction(tx, policy.checkpoint, updatedAt, organizationId);
+    }
+}
+async function ensureKeyingCheckpointValidationTables(input) {
+    await ensureSqlTables(input.execSql, input.policies.length > 0
+        ? [...principalPolicyTables, ...keyingCheckpointTables]
+        : keyingCheckpointTables);
+}
+/** Re-checks verified candidates against durable pins without advancing them. */
+export async function validateKeyingCheckpointsAtomically(input) {
+    await ensureKeyingCheckpointValidationTables(input);
+    const validate = async (tx) => {
+        await validateAccessAdvances(tx, input.access);
+        await validatePolicyAdvances(tx, input.policies);
+    };
+    const runtime = getClientSQLitePersistenceRuntime(input.execSql);
+    if (input.stillCurrent) {
+        await runtime.guardedTransaction(validate, input.stillCurrent, {
+            behavior: "immediate",
+        });
+        return;
+    }
+    await runtime.transaction(validate, { behavior: "immediate" });
+}
+/**
+ * Re-check every verified projection candidate against the latest durable pins
+ * and advance the complete batch atomically. Signature verification and remote
+ * fetching happen before this short transaction; only checkpoint comparison
+ * and persistence are serialized here.
+ */
+export async function advanceKeyingCheckpointsAtomically(input) {
+    await ensureKeyingCheckpointValidationTables(input);
+    const updatedAt = new Date().toISOString();
+    const runtime = getClientSQLitePersistenceRuntime(input.execSql);
+    const advance = async (tx) => {
+        const access = await validateAccessAdvances(tx, input.access);
+        const policies = await validatePolicyAdvances(tx, input.policies);
+        await writeAccessCheckpoints(tx, access, updatedAt);
+        await writePolicyCheckpoints(tx, policies, updatedAt, input.organizationId);
+        if (input.documentPurgeCheckpoint) {
+            await storeDocumentPurgeCheckpointInTransaction(tx, input.documentPurgeCheckpoint, updatedAt);
+        }
+    };
+    if (input.stillCurrent) {
+        await runtime.guardedTransaction(advance, input.stillCurrent, {
+            behavior: "immediate",
+        });
+        return;
+    }
+    await runtime.transaction(advance, { behavior: "immediate" });
+}
+/**
+ * Persists each verified full policy bundle together with its durable head.
+ * This prevents a crash or bundle-write failure from leaving a checkpoint
+ * without the exact same-head payload and member-envelope evidence.
+ */
+export async function persistVerifiedPrincipalPolicyBundlesAtomically(input) {
+    const seen = new Set();
+    for (const entry of input.entries) {
+        const key = principalPolicyKey(entry.policy);
+        if (seen.has(key)) {
+            throw new KeyingVerificationError("duplicate_entry", `verified policy bundle batch repeats ${key}`);
+        }
+        seen.add(key);
+    }
+    await Promise.all(input.entries.map((entry) => assertBundleMatchesVerifiedPolicy(entry)));
+    await ensureSqlTables(input.execSql, [
+        ...principalPolicyTables,
+        ...keyingCheckpointTables,
+    ]);
+    const runtime = getClientSQLitePersistenceRuntime(input.execSql);
+    const persist = async (tx) => {
+        const policies = await validatePolicyAdvances(tx, input.entries.map((entry) => entry.policy));
+        for (const entry of input.entries) {
+            await writePrincipalPolicyBundleInTransaction(tx, entry.bundle, input.updatedAt, input.organizationId);
+            await assertPrincipalPolicyBundleStoredInTransaction(tx, entry.bundle);
+        }
+        await writePolicyCheckpoints(tx, policies, input.updatedAt, input.organizationId);
+        for (const policy of policies.values()) {
+            const checkpoint = await loadStoredPrincipalPolicyCheckpoint(tx, policy);
+            if (!checkpoint ||
+                checkpoint.version !== policy.version ||
+                checkpoint.stateHash !== policy.stateHash) {
+                throw new Error("Verified principal policy checkpoint was not persisted");
+            }
+        }
+    };
+    if (input.stillCurrent) {
+        await runtime.guardedTransaction(persist, input.stillCurrent, {
+            behavior: "immediate",
+        });
+        return;
+    }
+    await runtime.transaction(persist, { behavior: "immediate" });
+}
+//# sourceMappingURL=keyingCheckpointAdvancePersistence.js.map

package/data/persistence/keyingCheckpointAdvancePersistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyingCheckpointAdvancePersistence.js","sourceRoot":"","sources":["keyingCheckpointAdvancePersistence.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type AccessManifestCheckpoint,\n  type AnyVerifiedPrincipalPolicy,\n  KeyingVerificationError,\n  type VerifiedAccessManifestCheckpointEvidence,\n  type VerifiedPrincipalPolicy,\n  type VerifiedPrincipalPolicyCurrent,\n  verifyAccessManifestLocalCheckpoint,\n  verifyPrincipalPolicyCheckpoint,\n} from \"@tearleads/crypto\";\nimport type { PrincipalPolicyBundleResponse } from \"@tearleads/validators/response\";\nimport {\n  keyingCheckpointTables,\n  principalPolicyTables,\n} from \"../sqlite/schema\";\nimport {\n  type ClientSQLiteTransactionScope,\n  getClientSQLitePersistenceRuntime,\n} from \"../sqlite/sqlitePersistenceRuntime\";\nimport { type ExecSql, ensureSqlTables } from \"../sqlite/sqlSchema\";\nimport {\n  type DocumentPurgeCheckpoint,\n  storeDocumentPurgeCheckpointInTransaction,\n} from \"./documentPurgeCheckpointPersistence\";\nimport { validateAccessManifestCheckpointEvidence } from \"./keyingCheckpointEvidence\";\nimport {\n  accessManifestObjectKey,\n  loadStoredAccessManifestCheckpoint,\n  loadStoredPrincipalPolicyCheckpoint,\n  principalPolicyKey,\n  upsertAccessManifestCheckpointInTransaction,\n  upsertPrincipalPolicyCheckpointInTransaction,\n} from \"./keyingCheckpointPersistence\";\nimport { assertContainerNotRetired } from \"./principalGrantRetirementPersistence\";\nimport {\n  assertPrincipalPolicyBundleStoredInTransaction,\n  writePrincipalPolicyBundleInTransaction,\n} from \"./principalPolicyPersistence\";\nimport { assertBundleMatchesVerifiedPolicy } from \"./verifiedPrincipalPolicyBundle\";\n\nexport interface AccessManifestCheckpointAdvance {\n  readonly head: VerifiedAccessManifestCheckpointEvidence;\n  readonly predecessors: readonly VerifiedAccessManifestCheckpointEvidence[];\n}\n\ntype CheckpointPolicy =\n  | AnyVerifiedPrincipalPolicy\n  | VerifiedPrincipalPolicyCurrent;\n\ninterface KeyingCheckpointValidationInput {\n  readonly access: readonly AccessManifestCheckpointAdvance[];\n  readonly execSql: ExecSql;\n  readonly policies: readonly CheckpointPolicy[];\n  readonly stillCurrent?: (() => boolean) | undefined;\n}\n\ninterface VerifiedPrincipalPolicyBundleEntry {\n  readonly bundle: PrincipalPolicyBundleResponse;\n  readonly policy: VerifiedPrincipalPolicy;\n}\n\ninterface PendingAccessCheckpoint {\n  readonly checkpoint: AccessManifestCheckpoint;\n}\n\nfunction validateAccessAdvance(\n  advance: AccessManifestCheckpointAdvance,\n  localCheckpoint: AccessManifestCheckpoint | null,\n): PendingAccessCheckpoint {\n  const current = {\n    ...advance.head.checkpoint,\n    previousManifestHash: advance.head.manifest.previousManifestHash,\n  };\n  const predecessors = [...advance.predecessors].sort(\n    (left, right) => left.checkpoint.epoch - right.checkpoint.epoch,\n  );\n\n  if (localCheckpoint && current.epoch <= localCheckpoint.epoch) {\n    verifyAccessManifestLocalCheckpoint({\n      current,\n      localCheckpoint,\n      checkpointPredecessors: undefined,\n    });\n  }\n\n  validateAccessManifestCheckpointEvidence({\n    head: advance.head,\n    predecessors,\n    localCheckpoint,\n  });\n\n  verifyAccessManifestLocalCheckpoint({\n    current,\n    localCheckpoint,\n    checkpointPredecessors: predecessors.filter(\n      (manifest) =>\n        localCheckpoint !== null &&\n        manifest.checkpoint.epoch > localCheckpoint.epoch &&\n        manifest.checkpoint.epoch < current.epoch,\n    ),\n  });\n\n  return {\n    checkpoint: advance.head.checkpoint,\n  };\n}\n\nasync function validateAccessAdvances(\n  tx: ClientSQLiteTransactionScope,\n  advances: readonly AccessManifestCheckpointAdvance[],\n): Promise<Map<string, PendingAccessCheckpoint>> {\n  const pending = new Map<string, PendingAccessCheckpoint>();\n\n  for (const advance of advances) {\n    await assertContainerNotRetired(tx, advance.head.checkpoint);\n    const key = accessManifestObjectKey(advance.head.checkpoint);\n    if (pending.has(key)) {\n      throw new KeyingVerificationError(\n        \"equivocation\",\n        `projection declares multiple access checkpoint heads for ${key}`,\n      );\n    }\n    const localCheckpoint = await loadStoredAccessManifestCheckpoint(\n      tx,\n      advance.head.checkpoint,\n    );\n    pending.set(key, validateAccessAdvance(advance, localCheckpoint));\n  }\n\n  return pending;\n}\n\nfunction extendsObservedPolicy(\n  head: CheckpointPolicy,\n  candidate: CheckpointPolicy,\n): boolean {\n  const history =\n    \"retainedHistory\" in head ? head.retainedHistory : head.history;\n  return (\n    history?.some(\n      ({ state }) =>\n        state.principalType === candidate.principalType &&\n        state.principalId === candidate.principalId &&\n        state.version === candidate.version &&\n        state.stateHash === candidate.stateHash,\n    ) ?? false\n  );\n}\n\nasync function validatePolicyAdvances(\n  tx: ClientSQLiteTransactionScope,\n  policies: readonly CheckpointPolicy[],\n): Promise<Map<string, CheckpointPolicy>> {\n  const policiesByPrincipal = new Map<string, CheckpointPolicy[]>();\n  for (const policy of policies) {\n    const key = principalPolicyKey(policy);\n    const candidates = policiesByPrincipal.get(key) ?? [];\n    candidates.push(policy);\n    policiesByPrincipal.set(key, candidates);\n  }\n\n  const pending = new Map<string, CheckpointPolicy>();\n  for (const key of [...policiesByPrincipal.keys()].sort()) {\n    const candidates = policiesByPrincipal.get(key) ?? [];\n    const maxVersion = Math.max(...candidates.map((policy) => policy.version));\n    const heads = candidates.filter((policy) => policy.version === maxVersion);\n    const head = heads[0];\n    if (!head) {\n      continue;\n    }\n    if (heads.some((candidate) => candidate.stateHash !== head.stateHash)) {\n      throw new KeyingVerificationError(\n        \"equivocation\",\n        `principal policy declares conflicting heads for ${key}`,\n      );\n    }\n    for (const candidate of candidates) {\n      if (candidate.version === head.version) {\n        continue;\n      }\n      if (!extendsObservedPolicy(head, candidate)) {\n        throw new KeyingVerificationError(\n          \"stale_predecessor\",\n          `principal policy head does not extend observed state for ${key}`,\n        );\n      }\n    }\n\n    const localCheckpoint = await loadStoredPrincipalPolicyCheckpoint(tx, head);\n    verifyPrincipalPolicyCheckpoint({\n      chain:\n        \"retainedHistory\" in head ? head.retainedHistory : (head.history ?? []),\n      currentState: head.state,\n      localCheckpoint,\n    });\n    pending.set(key, head);\n  }\n\n  return pending;\n}\n\nasync function writeAccessCheckpoints(\n  tx: ClientSQLiteTransactionScope,\n  pending: ReadonlyMap<string, PendingAccessCheckpoint>,\n  updatedAt: string,\n): Promise<void> {\n  for (const { checkpoint } of pending.values()) {\n    await upsertAccessManifestCheckpointInTransaction(\n      tx,\n      checkpoint,\n      updatedAt,\n    );\n  }\n}\n\nasync function writePolicyCheckpoints(\n  tx: ClientSQLiteTransactionScope,\n  pending: ReadonlyMap<string, CheckpointPolicy>,\n  updatedAt: string,\n  organizationId?: string | undefined,\n): Promise<void> {\n  for (const policy of pending.values()) {\n    await upsertPrincipalPolicyCheckpointInTransaction(\n      tx,\n      policy.checkpoint,\n      updatedAt,\n      organizationId,\n    );\n  }\n}\n\nasync function ensureKeyingCheckpointValidationTables(\n  input: KeyingCheckpointValidationInput,\n): Promise<void> {\n  await ensureSqlTables(\n    input.execSql,\n    input.policies.length > 0\n      ? [...principalPolicyTables, ...keyingCheckpointTables]\n      : keyingCheckpointTables,\n  );\n}\n\n/** Re-checks verified candidates against durable pins without advancing them. */\nexport async function validateKeyingCheckpointsAtomically(\n  input: KeyingCheckpointValidationInput,\n): Promise<void> {\n  await ensureKeyingCheckpointValidationTables(input);\n  const validate = async (tx: ClientSQLiteTransactionScope) => {\n    await validateAccessAdvances(tx, input.access);\n    await validatePolicyAdvances(tx, input.policies);\n  };\n  const runtime = getClientSQLitePersistenceRuntime(input.execSql);\n  if (input.stillCurrent) {\n    await runtime.guardedTransaction(validate, input.stillCurrent, {\n      behavior: \"immediate\",\n    });\n    return;\n  }\n  await runtime.transaction(validate, { behavior: \"immediate\" });\n}\n\n/**\n * Re-check every verified projection candidate against the latest durable pins\n * and advance the complete batch atomically. Signature verification and remote\n * fetching happen before this short transaction; only checkpoint comparison\n * and persistence are serialized here.\n */\nexport async function advanceKeyingCheckpointsAtomically(input: {\n  readonly access: readonly AccessManifestCheckpointAdvance[];\n  readonly documentPurgeCheckpoint?: DocumentPurgeCheckpoint | undefined;\n  readonly execSql: ExecSql;\n  readonly organizationId?: string | undefined;\n  readonly policies: readonly CheckpointPolicy[];\n  readonly stillCurrent?: (() => boolean) | undefined;\n}): Promise<void> {\n  await ensureKeyingCheckpointValidationTables(input);\n  const updatedAt = new Date().toISOString();\n\n  const runtime = getClientSQLitePersistenceRuntime(input.execSql);\n  const advance = async (tx: ClientSQLiteTransactionScope) => {\n    const access = await validateAccessAdvances(tx, input.access);\n    const policies = await validatePolicyAdvances(tx, input.policies);\n\n    await writeAccessCheckpoints(tx, access, updatedAt);\n    await writePolicyCheckpoints(tx, policies, updatedAt, input.organizationId);\n    if (input.documentPurgeCheckpoint) {\n      await storeDocumentPurgeCheckpointInTransaction(\n        tx,\n        input.documentPurgeCheckpoint,\n        updatedAt,\n      );\n    }\n  };\n  if (input.stillCurrent) {\n    await runtime.guardedTransaction(advance, input.stillCurrent, {\n      behavior: \"immediate\",\n    });\n    return;\n  }\n  await runtime.transaction(advance, { behavior: \"immediate\" });\n}\n\n/**\n * Persists each verified full policy bundle together with its durable head.\n * This prevents a crash or bundle-write failure from leaving a checkpoint\n * without the exact same-head payload and member-envelope evidence.\n */\nexport async function persistVerifiedPrincipalPolicyBundlesAtomically(input: {\n  readonly entries: readonly VerifiedPrincipalPolicyBundleEntry[];\n  readonly execSql: ExecSql;\n  readonly organizationId?: string | undefined;\n  readonly stillCurrent?: (() => boolean) | undefined;\n  readonly updatedAt: string;\n}): Promise<void> {\n  const seen = new Set<string>();\n  for (const entry of input.entries) {\n    const key = principalPolicyKey(entry.policy);\n    if (seen.has(key)) {\n      throw new KeyingVerificationError(\n        \"duplicate_entry\",\n        `verified policy bundle batch repeats ${key}`,\n      );\n    }\n    seen.add(key);\n  }\n  await Promise.all(\n    input.entries.map((entry) => assertBundleMatchesVerifiedPolicy(entry)),\n  );\n  await ensureSqlTables(input.execSql, [\n    ...principalPolicyTables,\n    ...keyingCheckpointTables,\n  ]);\n\n  const runtime = getClientSQLitePersistenceRuntime(input.execSql);\n  const persist = async (tx: ClientSQLiteTransactionScope) => {\n    const policies = await validatePolicyAdvances(\n      tx,\n      input.entries.map((entry) => entry.policy),\n    );\n    for (const entry of input.entries) {\n      await writePrincipalPolicyBundleInTransaction(\n        tx,\n        entry.bundle,\n        input.updatedAt,\n        input.organizationId,\n      );\n      await assertPrincipalPolicyBundleStoredInTransaction(tx, entry.bundle);\n    }\n    await writePolicyCheckpoints(\n      tx,\n      policies,\n      input.updatedAt,\n      input.organizationId,\n    );\n    for (const policy of policies.values()) {\n      const checkpoint = await loadStoredPrincipalPolicyCheckpoint(tx, policy);\n      if (\n        !checkpoint ||\n        checkpoint.version !== policy.version ||\n        checkpoint.stateHash !== policy.stateHash\n      ) {\n        throw new Error(\n          \"Verified principal policy checkpoint was not persisted\",\n        );\n      }\n    }\n  };\n  if (input.stillCurrent) {\n    await runtime.guardedTransaction(persist, input.stillCurrent, {\n      behavior: \"immediate\",\n    });\n    return;\n  }\n  await runtime.transaction(persist, { behavior: \"immediate\" });\n}\n"]}

package/data/persistence/keyingCheckpointEvidence.js

@@ -0,0 +1,32 @@
+import { KeyingVerificationError, } from "../../internal/crypto/index.js";
+import { accessManifestObjectKey } from "./keyingCheckpointPersistence.js";
+/** Structural consistency applies even when local currency prevents acceptance. */
+export function validateAccessManifestCheckpointEvidence(input) {
+    const current = input.head.checkpoint;
+    const { predecessors, localCheckpoint } = input;
+    const hashByEpoch = new Map();
+    for (const predecessor of predecessors) {
+        if (accessManifestObjectKey(predecessor.checkpoint) !==
+            accessManifestObjectKey(current)) {
+            throw new KeyingVerificationError("object_mismatch", "access manifest checkpoint evidence belongs to another object");
+        }
+        const previousHash = hashByEpoch.get(predecessor.checkpoint.epoch);
+        if (previousHash && previousHash !== predecessor.manifestHash) {
+            throw new KeyingVerificationError("equivocation", `access manifest checkpoint evidence conflicts at epoch ${predecessor.checkpoint.epoch}`);
+        }
+        hashByEpoch.set(predecessor.checkpoint.epoch, predecessor.manifestHash);
+        if (predecessor.checkpoint.epoch === current.epoch &&
+            predecessor.manifestHash !== current.manifestHash) {
+            throw new KeyingVerificationError("equivocation", "access manifest checkpoint evidence conflicts with the declared head");
+        }
+        if (localCheckpoint &&
+            predecessor.checkpoint.epoch === localCheckpoint.epoch &&
+            predecessor.manifestHash !== localCheckpoint.manifestHash) {
+            throw new KeyingVerificationError("equivocation", "access manifest checkpoint evidence conflicts with the local checkpoint");
+        }
+        if (predecessor.checkpoint.epoch > current.epoch) {
+            throw new KeyingVerificationError("stale_predecessor", "access manifest checkpoint evidence is newer than the declared head");
+        }
+    }
+}
+//# sourceMappingURL=keyingCheckpointEvidence.js.map