p2party 0.14.2 → 0.14.7

package/lib/blindRendezvous/publicWindow.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Public windows, buckets, immutable chunks, and checkpoints (Section 4.3).
+ *
+ * The store's whole view is public geometry: a delivery profile, an ingress
+ * window, a size class, a chunk index, and opaque fixed-size objects. Nothing
+ * here takes a room-derived input, which is what lets every room in a profile
+ * share one bucket and makes unrelated rooms cover for each other rather than
+ * members of anything.
+ *
+ * Two clocks meet in this file and must never be substituted for one another:
+ * `IngressWindow` is carrier geometry, and `RoomLogicalWindow` is operation
+ * validity under immutable room policy. Profiles with different cadences carry
+ * the same operation without changing its validity or the reducer's result.
+ *
+ * Scope: geometry, hashing, the append slot mapping, RFC 9162 inclusion
+ * verification, and the descriptor-bound checkpoint predicates. The remaining
+ * Section 4.3 fault proofs are assembled from these parts by a caller that also
+ * holds the raw evidence: `checkpointsConflict` and `chainLinksSuccessor` are
+ * the descriptor-free halves, and `structurallyValidCheckpoint` supplies the
+ * descriptor join each proof requires of both of its checkpoints.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { StoreDescriptorV1 } from "./storeDescriptor";
+export interface PublicBucketV1 {
+    deliveryProfileHash: Uint8Array;
+    ingressWindow: bigint;
+    sizeClass: number;
+}
+export interface PublicChunkBodyV1 {
+    version: 1;
+    bucket: PublicBucketV1;
+    chunkIndex: bigint;
+    previousChunkHash: Uint8Array;
+    fixedObjects: readonly Uint8Array[];
+}
+export type PublicChunkV1 = PublicChunkBodyV1 & {
+    storeSignature: Uint8Array;
+};
+export interface PublicStoreCheckpointBodyV1 {
+    version: 1;
+    storeId: Uint8Array;
+    descriptorHash: Uint8Array;
+    deliveryProfileHash: Uint8Array;
+    ingressWindow: bigint;
+    chainStartIngressWindow: bigint;
+    previousCheckpointHash: Uint8Array;
+    finalizedChunkCount: number;
+    finalizedChunkRoot: Uint8Array;
+}
+export type PublicStoreCheckpointV1 = PublicStoreCheckpointBodyV1 & {
+    storeSignature: Uint8Array;
+};
+export interface PublicCheckpointChunkLeafV1 {
+    sizeClass: number;
+    chunkIndex: bigint;
+    publicChunkHash: Uint8Array;
+}
+export interface PublicCheckpointChunkInclusionProofV1 {
+    version: 1;
+    checkpointHash: Uint8Array;
+    leaf: PublicCheckpointChunkLeafV1;
+    leafIndex: number;
+    siblingHashes: readonly Uint8Array[];
+}
+/** The size-class geometry a profile fixes; the subset this module needs. */
+export interface PublicProfileGeometry {
+    readonly publicChunkObjectCount: number;
+    readonly cohortAllocationsPerWindow: number;
+    readonly roomSlotsPerClient: number;
+    readonly sizeClasses: readonly {
+        readonly id: number;
+        readonly appendScheduleLength: number;
+        readonly publicChunksPerWindow: number;
+    }[];
+}
+export declare class PublicWindowError extends Error {
+    readonly name = "PublicWindowError";
+    constructor(message: string);
+}
+export declare const ZERO32: Uint8Array;
+/** `IngressWindow(profile, now) = floor(now / profile.deliveryWindowMs)` */
+export declare const ingressWindow: (deliveryWindowMs: bigint, nowMs: bigint) => bigint;
+/**
+ * `RoomLogicalWindow(roomPolicy, now) = floor(now / logicalWindowMs)`
+ *
+ * Deliberately a separate function from `ingressWindow` despite the identical
+ * shape: substituting one for the other would let carrier geometry decide
+ * operation validity.
+ */
+export declare const roomLogicalWindow: (logicalWindowMs: bigint, nowMs: bigint) => bigint;
+/** `IngressWindowStart(w) = checkedMultiply(w, deliveryWindowMs)` */
+export declare const ingressWindowStartMs: (window: bigint, deliveryWindowMs: bigint) => bigint;
+/**
+ * Retention is inclusive and has one wire meaning: a bucket finalized in
+ * window `w` stays readable through the END of `w + carrierRetentionWindows`,
+ * and may be deleted only at or after the start of the window after that.
+ */
+export declare const bucketIsReadable: (bucketWindow: bigint, currentWindow: bigint, carrierRetentionWindows: number) => boolean;
+export declare const publicBucketId: (bucket: PublicBucketV1) => Promise<Uint8Array>;
+/** The transcript a store signs; the body only, never the signed form. */
+export declare const publicChunkSigningHash: (body: PublicChunkBodyV1) => Promise<Uint8Array>;
+/** The identity of a signed chunk, which is what a checkpoint leaf commits. */
+export declare const publicChunkHash: (chunk: PublicChunkV1) => Promise<Uint8Array>;
+export declare const publicStoreCheckpointSigningHash: (body: PublicStoreCheckpointBodyV1) => Promise<Uint8Array>;
+export declare const publicStoreCheckpointHash: (checkpoint: PublicStoreCheckpointV1) => Promise<Uint8Array>;
+/** The leaf preimage a checkpoint's Merkle tree is built over. */
+export declare const publicCheckpointChunkLeafInput: (leaf: PublicCheckpointChunkLeafV1) => Uint8Array;
+export interface AppendSlotCoordinates {
+    readonly chunkIndex: bigint;
+    readonly objectIndexWithinChunk: number;
+    readonly globalObjectOrdinal: number;
+    readonly roomSlotOrdinal: number;
+    readonly objectOrdinalWithinRoomSlot: number;
+}
+/**
+ * Where one admitted append lands, derived only from the signed lease ordinal
+ * and public profile geometry.
+ *
+ * This is the mapping a custody promise commits to, so it is a total function
+ * of public values: a store cannot move an object by claiming a different
+ * position, and a client can check the promise without asking anyone.
+ */
+export declare const appendSlotCoordinates: (geometry: PublicProfileGeometry, sizeClassId: number, allocationOrdinal: number, objectOrdinalWithinAllocation: number) => AppendSlotCoordinates;
+/**
+ * The checkpoint leaf index of one chunk: the profile-fixed sequence sorted by
+ * `(sizeClass, chunkIndex)`.
+ */
+export declare const profileChunkOrdinal: (geometry: PublicProfileGeometry, sizeClassId: number, chunkIndex: bigint) => number;
+/** `checkedSum(profile.sizeClasses[].publicChunksPerWindow)` */
+export declare const profileFinalizedChunkCount: (geometry: PublicProfileGeometry) => number;
+/**
+ * RFC 9162 Section 2.1.1 leaf hash: `HASH(0x00 || entry)`.
+ *
+ * The prefix bytes are the whole point — without them a leaf and an interior
+ * node could collide, which is the classic second-preimage attack on
+ * unprefixed Merkle trees.
+ */
+export declare const rfc9162LeafHash: (entry: Uint8Array) => Promise<Uint8Array>;
+/** RFC 9162 Section 2.1.1 interior node: `HASH(0x01 || left || right)`. */
+export declare const rfc9162NodeHash: (left: Uint8Array, right: Uint8Array) => Promise<Uint8Array>;
+/**
+ * RFC 9162 Merkle Tree Hash over a nonempty entry sequence.
+ *
+ * The empty case is rejected rather than returning `HASH()`: a checkpoint
+ * always commits the profile's complete fixed chunk sequence, so an empty
+ * input means the caller built the wrong sequence.
+ */
+export declare const rfc9162MerkleTreeHash: (entries: readonly Uint8Array[]) => Promise<Uint8Array>;
+/**
+ * The RFC 9162 audit path for one leaf: the sibling hashes from the leaf up.
+ *
+ * Exposed so a verifier can assert the received path has exactly this length —
+ * a missing or extra sibling is invalid, not merely unhelpful.
+ */
+export declare const rfc9162AuditPath: (entries: readonly Uint8Array[], leafIndex: number) => Promise<Uint8Array[]>;
+/** The exact number of siblings an RFC 9162 audit path has for `(index, n)`. */
+export declare const rfc9162AuditPathLength: (leafIndex: number, treeSize: number) => number;
+/** Recompute a root from a leaf and its audit path (RFC 9162 Section 2.1.3). */
+export declare const rfc9162RootFromAuditPath: (leafEntry: Uint8Array, leafIndex: number, treeSize: number, siblingHashes: readonly Uint8Array[]) => Promise<Uint8Array>;
+/**
+ * The complete leaf sequence a checkpoint commits: every chunk of every size
+ * class, sorted by `(sizeClass, chunkIndex)`, including all-dummy windows.
+ */
+export declare const checkpointLeafEntries: (geometry: PublicProfileGeometry, chunkHashBySizeClass: ReadonlyMap<number, readonly Uint8Array[]>) => Promise<Uint8Array[]>;
+export type InclusionVerdict = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly reason: string;
+};
+/**
+ * Verify that a signed chunk occupies its committed position in a checkpoint.
+ *
+ * The signature check is the caller's: it needs the store descriptor from
+ * Section 4.2 to know which key to trust. Everything that can be decided from
+ * the geometry and the hashes is decided here, and every cross-coordinate
+ * relocation is rejected — a store must not be able to move an object between
+ * classes, chunks, or windows and still produce a passing proof.
+ */
+export declare const verifyCheckpointChunkInclusion: (geometry: PublicProfileGeometry, checkpoint: PublicStoreCheckpointV1, chunk: PublicChunkV1, proof: PublicCheckpointChunkInclusionProofV1) => Promise<InclusionVerdict>;
+/**
+ * Two checkpoints for one store/profile/window that are not the same object.
+ *
+ * This is the descriptor-free half of `PublicCheckpointConflictProofV1`; a
+ * complete proof additionally joins each embedded descriptor. Canonical order
+ * is bytewise-lower checkpoint hash first, so one fault has one proof rather
+ * than two mirror images.
+ */
+export declare const checkpointsConflict: (first: PublicStoreCheckpointV1, second: PublicStoreCheckpointV1) => Promise<{
+    readonly conflicting: false;
+} | {
+    readonly conflicting: true;
+    readonly canonicalOrder: readonly [PublicStoreCheckpointV1, PublicStoreCheckpointV1];
+}>;
+/**
+ * The hash-linkage half of `ChainValidSuccessor`.
+ *
+ * Structural validity under each embedded descriptor is a separate Section 4.2
+ * check, and the specification is explicit that structural validity alone does
+ * not assert predecessor continuity — which is exactly what this decides.
+ */
+export declare const chainLinksSuccessor: (previous: PublicStoreCheckpointV1, next: PublicStoreCheckpointV1) => Promise<boolean>;
+/** At the chain start the predecessor hash is exactly `ZERO32`. */
+export declare const isChainStart: (checkpoint: PublicStoreCheckpointV1) => boolean;
+/**
+ * `StructurallyValidCheckpoint(descriptor, checkpoint, profile)`.
+ *
+ * Deliberately portable: it uses the descriptor embedded in the read or proof,
+ * and takes no input from local carrier authorization, catalog arrival order,
+ * or which descriptor the verifier considers "latest". Whether the frontend may
+ * *contact* that store is a separate local decision — conflating the two would
+ * make historical evidence depend on present-day policy, so a store could
+ * escape a proof by being removed from a catalog.
+ *
+ * `finalizationInstantUnixMs` is the instant the checkpoint was finalized, and
+ * the descriptor must have been valid then — not now.
+ *
+ * Of the specification's "profile-fixed count/root checks", only the count half
+ * is decided here. Recomputing `finalizedChunkRoot` needs the window's chunk
+ * hashes, which this predicate is never given; that is
+ * `verifyCheckpointChunkInclusion`, and nothing composes the two, so no single
+ * call asserts both halves. A checkpoint accepted here may still carry a root
+ * no chunk sequence produces.
+ *
+ * TODO(spec): the condition list in Section 4.3 does not name a version check,
+ * so `checkpoint.version` is not checked here, while `StoreDescriptorAuthentic`
+ * does name one and `validateStoreDescriptor` enforces it. Whether the version
+ * byte belongs to structural validity is a question for the specification, not
+ * one to settle by tightening this predicate; the current behaviour is pinned
+ * in tests/blindRendezvous/storeHonesty.test.ts.
+ */
+export declare const structurallyValidCheckpoint: (descriptor: StoreDescriptorV1, checkpoint: PublicStoreCheckpointV1, geometry: PublicProfileGeometry, finalizationInstantUnixMs: bigint, module?: LibCrypto) => Promise<InclusionVerdict>;
+/**
+ * `ChainValidSuccessor(previous, next)`: both structurally valid under their
+ * embedded descriptors, and linked.
+ *
+ * Structural validity alone deliberately does not assert continuity — that is
+ * what makes a missing predecessor detectable rather than assumed.
+ */
+export declare const chainValidSuccessor: (previous: PublicStoreCheckpointV1, previousDescriptor: StoreDescriptorV1, previousFinalizationUnixMs: bigint, next: PublicStoreCheckpointV1, nextDescriptor: StoreDescriptorV1, nextFinalizationUnixMs: bigint, geometry: PublicProfileGeometry, module?: LibCrypto) => Promise<InclusionVerdict>;
+/**
+ * One checkpoint exactly as a client observed it: the read itself, the
+ * descriptor embedded beside it, and the instant that window was finalized.
+ *
+ * Deliberately not a `...V1` name: this is an in-memory bundle of three
+ * already-frozen objects, not a wire shape the specification has registered.
+ */
+export interface ObservedStoreCheckpoint {
+    readonly checkpoint: PublicStoreCheckpointV1;
+    readonly descriptor: StoreDescriptorV1;
+    readonly finalizationInstantUnixMs: bigint;
+}
+/**
+ * What `verifyStoreCheckpointChain` detected. Exactly one outcome is blame-free
+ * besides success: `unverified-chain-gap` says the client did not observe
+ * enough, which the specification is explicit is not a fault.
+ */
+export type StoreCheckpointChainVerdict = {
+    readonly outcome: "chain-verified";
+    readonly storeId: Uint8Array;
+    readonly deliveryProfileHash: Uint8Array;
+    readonly chainStartIngressWindow: bigint;
+    readonly firstIngressWindow: bigint;
+    readonly headIngressWindow: bigint;
+    readonly headCheckpointHash: Uint8Array;
+    readonly startsAtChainStart: boolean;
+} | {
+    readonly outcome: "structurally-invalid-checkpoint";
+    readonly reason: string;
+    readonly index: number;
+} | {
+    readonly outcome: "not-one-store-profile-chain";
+    readonly reason: string;
+    readonly index: number;
+} | {
+    readonly outcome: "chain-start-conflict";
+    readonly reason: string;
+    readonly canonicalOrder: readonly [StoreDescriptorV1, StoreDescriptorV1];
+} | {
+    readonly outcome: "checkpoint-conflict";
+    readonly reason: string;
+    readonly canonicalOrder: readonly [
+        PublicStoreCheckpointV1,
+        PublicStoreCheckpointV1
+    ];
+} | {
+    readonly outcome: "chain-breach";
+    readonly reason: string;
+    readonly previous: PublicStoreCheckpointV1;
+    readonly next: PublicStoreCheckpointV1;
+} | {
+    readonly outcome: "unverified-chain-gap";
+    readonly reason: string;
+    readonly afterIngressWindow: bigint;
+    readonly beforeIngressWindow: bigint;
+};
+/**
+ * The sequence form of the Section 4.3 checkpoint checks: one entry point a
+ * store client can call over the run of checkpoints it actually holds.
+ *
+ * `chainValidSuccessor` remains the specified predicate for a single pair; this
+ * verifies each checkpoint's structure exactly once and then decides the
+ * pairwise questions, so a long run costs one signature verification per
+ * checkpoint rather than two.
+ *
+ * Blame is reported before absence. A store must not be able to bury an
+ * equivocation behind a hole in what the client happened to retain, so a
+ * conflict, chain-start conflict, or broken predecessor anywhere in the run
+ * outranks a missing window; only when no fault exists does a gap become the
+ * verdict.
+ *
+ * What a `chain-verified` verdict is not: it says the observed run is
+ * internally consistent and signed, over exactly the windows supplied. It is
+ * not a completeness, availability, or non-equivocation claim — a store that
+ * showed this client one branch and another client a different one is caught
+ * only when the two observations meet. Nor does it assert `finalizedChunkRoot`:
+ * `structurallyValidCheckpoint` cannot, and this composes that, not inclusion.
+ *
+ * A `chain-verified` verdict copies the bytes it reports, so it stays true
+ * after the buffers a store's reply was decoded into are reused. The conflict
+ * and breach verdicts deliberately do not: they carry the caller's own
+ * checkpoint and descriptor objects, because those are the exact halves the
+ * specification's proofs are built from, and copying them here would only
+ * hide that they must be retained unmutated to stay usable as evidence.
+ *
+ * Ordering the run is the caller's job: observations must arrive sorted by
+ * ingress window. A store cannot cause a violation of that, so it throws
+ * rather than returning a verdict that would read as a detected fault.
+ */
+export declare const verifyStoreCheckpointChain: (observations: readonly ObservedStoreCheckpoint[], geometry: PublicProfileGeometry, module?: LibCrypto) => Promise<StoreCheckpointChainVerdict>;

package/lib/blindRendezvous/retainedOperationStore.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Exact local persistence boundary for retained blind-rendezvous operations.
+ *
+ * This is a local storage schema, not a wire format and not part of the
+ * normative release registry. It preserves the exact canonical operation
+ * bytes needed by the existing operation validator and CoreReduce after a
+ * restart; it deliberately performs neither of those protocol validations.
+ *
+ * One immutable content row stores each exact operation once per room. A
+ * per-room/window manifest names the complete sorted unique room-wide row set
+ * visible at that historical decision boundary and fences its physical
+ * count/bytes. This intentionally simple representation makes omission and
+ * overcapacity explicit. A later database adapter may change its physical
+ * layout without changing this source-internal contract.
+ */
+export type RetainedOperationManifestCompletenessV1 = "complete" | "incomplete-overcapacity";
+/**
+ * Canonical local manifest for one room/window historical replay fence.
+ *
+ * `operationIds` names the complete room-wide unique retained-operation set,
+ * not an endpoint subset and not a decoded Core projection. Therefore the
+ * byte total charges a shared content row once regardless of how many window
+ * manifests reference it.
+ */
+export interface RetainedOperationWindowManifestV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly referenceWindow: bigint;
+    readonly retainThroughLogicalWindow: bigint;
+    readonly completeness: RetainedOperationManifestCompletenessV1;
+    readonly operationIds: readonly Uint8Array[];
+    readonly retainedOperationCount: number;
+    readonly retainedOperationBytes: bigint;
+    readonly maxRetainedValidOperationsPerRoom: number;
+    readonly maxRetainedValidOperationBytesPerRoom: bigint;
+    /** The first unique row rejected at the public capacity boundary. */
+    readonly firstRejectedOperationId: Uint8Array | null;
+}
+/**
+ * Immutable content-addressed row. Room membership is supplied only by the
+ * trusted outer-validation/store transition; this module can prove the
+ * OperationId/bytes relation but cannot infer RoomContextId from an operation.
+ */
+export interface RetainedOperationContentRowV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly operationId: Uint8Array;
+    readonly exactOperationBytes: Uint8Array;
+}
+export interface RetainedOperationWindowLocatorV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly referenceWindow: bigint;
+}
+/** Exact absence is replay-unavailable, never an empty complete manifest. */
+export type ExactRetainedOperationManifestRowV1 = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "present";
+    readonly exactManifestBytes: Uint8Array;
+    /** Non-reused adapter revision used to prevent ABA. */
+    readonly recordRevision: bigint;
+};
+/**
+ * Exact rows copied by one future read-only transaction.
+ *
+ * For a present manifest, `operations` must contain exactly one row for every
+ * named ID and no other row. Missing rows are represented by omission and fail
+ * validation; an absent manifest must have an empty row list.
+ */
+export interface RetainedOperationWindowExactCaptureV1 {
+    readonly manifest: ExactRetainedOperationManifestRowV1;
+    readonly operations: readonly RetainedOperationContentRowV1[];
+}
+export type ValidatedRetainedOperationWindowCaptureV1 = {
+    readonly kind: "unavailable";
+} | {
+    readonly kind: "available";
+    readonly exactManifestRow: Extract<ExactRetainedOperationManifestRowV1, {
+        readonly kind: "present";
+    }>;
+    readonly manifest: RetainedOperationWindowManifestV1;
+    readonly operations: readonly RetainedOperationContentRowV1[];
+};
+export interface InitializeRetainedOperationWindowOptionsV1 {
+    readonly roomContextId: Uint8Array;
+    readonly referenceWindow: bigint;
+    readonly retainThroughLogicalWindow: bigint;
+    readonly maxRetainedValidOperationsPerRoom: number;
+    readonly maxRetainedValidOperationBytesPerRoom: bigint;
+}
+export type PreparedRetainedOperationStoreMutationV1 = {
+    readonly kind: "initialize-window";
+    readonly exactNextManifestBytes: Uint8Array;
+} | {
+    readonly kind: "insert-operation-and-replace-manifest";
+    readonly operation: RetainedOperationContentRowV1;
+    readonly exactNextManifestBytes: Uint8Array;
+} | {
+    readonly kind: "mark-incomplete-overcapacity";
+    readonly firstRejectedOperationId: Uint8Array;
+    readonly exactNextManifestBytes: Uint8Array;
+};
+/**
+ * Closed future CAS request. The adapter compares the exact manifest
+ * bytes/revision and every expected content row before applying the mutation.
+ * Admission mutations additionally require the candidate content key to be
+ * absent; finding it without the matching manifest is a conflict/corruption,
+ * not an invitation to repair state heuristically.
+ */
+export interface RetainedOperationStoreCasRequestV1 {
+    readonly version: 1;
+    readonly locator: RetainedOperationWindowLocatorV1;
+    readonly expected: RetainedOperationWindowExactCaptureV1;
+    readonly candidateOperationId: Uint8Array | null;
+    readonly mutation: PreparedRetainedOperationStoreMutationV1;
+}
+export type RetainedOperationStoreCasResultV1 = {
+    readonly status: "committed";
+    readonly exactManifestRow: Extract<ExactRetainedOperationManifestRowV1, {
+        readonly kind: "present";
+    }>;
+} | {
+    readonly status: "conflict";
+    readonly fence: "manifest" | "operation";
+};
+/**
+ * Source-internal byte-store port for the later IndexedDB adapter.
+ *
+ * `readExactWindowCapture` must own all returned buffers and resolve only
+ * after its read transaction completes. `compareAndSwap` performs no crypto
+ * and awaits no promise while its write transaction is live.
+ *
+ * @internal
+ */
+export interface RetainedOperationStorePortV1 {
+    readExactWindowCapture(locator: RetainedOperationWindowLocatorV1): Promise<RetainedOperationWindowExactCaptureV1>;
+    compareAndSwap(request: RetainedOperationStoreCasRequestV1): Promise<RetainedOperationStoreCasResultV1>;
+}
+export type RetainedOperationAdmissionPlanV1 = {
+    readonly kind: "unavailable";
+} | {
+    readonly kind: "duplicate";
+} | {
+    readonly kind: "sticky-incomplete-overcapacity";
+    readonly firstRejectedOperationId: Uint8Array;
+} | {
+    readonly kind: "accept-operation";
+    readonly request: RetainedOperationStoreCasRequestV1;
+} | {
+    readonly kind: "mark-incomplete-overcapacity";
+    readonly request: RetainedOperationStoreCasRequestV1;
+};
+export declare class RetainedOperationStoreError extends Error {
+    readonly name = "RetainedOperationStoreError";
+    constructor(message: string);
+}
+/**
+ * Encode one strict local manifest. The descriptor is intentionally not
+ * exported and the bytes carry no interoperability or protocol provenance.
+ */
+export declare const encodeRetainedOperationWindowManifestV1: (value: RetainedOperationWindowManifestV1) => Uint8Array;
+/** Decode, own, and semantically validate one exact local manifest. */
+export declare const decodeRetainedOperationWindowManifestV1: (exactBytes: Uint8Array) => RetainedOperationWindowManifestV1;
+/**
+ * Own one content row and prove only its canonical bytes/OperationId
+ * association. This is not signature, room, policy, temporal, or Core
+ * validation.
+ */
+export declare const validateAndCopyRetainedOperationContentRowV1: (value: unknown) => Promise<RetainedOperationContentRowV1>;
+export declare const validateAndCopyRetainedOperationWindowExactCaptureV1: (value: unknown) => Promise<ValidatedRetainedOperationWindowCaptureV1>;
+/**
+ * Explicitly prepare a new empty complete window. This is the only path that
+ * turns expected absence into a manifest; replay reads never infer that an
+ * absent row means an empty room.
+ */
+export declare const prepareRetainedOperationWindowInitializationV1: (value: unknown) => RetainedOperationStoreCasRequestV1;
+/**
+ * Plan one deterministic retained-operation admission.
+ *
+ * The input capture is fully correlated before a candidate can affect state.
+ * Duplicate exact rows have zero resource delta. Once a manifest is
+ * incomplete, normal admission never parses a candidate or repairs/replaces
+ * the first-rejected witness; only a separate future full reconciliation may
+ * create a new complete manifest after capacity changes.
+ */
+export declare const planRetainedOperationAdmissionV1: (captureValue: unknown, candidateValue: unknown) => Promise<RetainedOperationAdmissionPlanV1>;

package/lib/blindRendezvous/roomInviteV2.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Version-safe invitation parsing.
+ *
+ * REQ-001 keeps the user-facing flow identical — one capability, one `/r`
+ * link, one QR code — while making the rendezvous version explicit in the
+ * fragment. Every deployed form (compact, `v1.`, 24-word, legacy hex) keeps its
+ * legacy-signaling meaning forever; blind rendezvous uses `v2.`.
+ *
+ * The two versions must never be silently interchangeable in either
+ * direction: an old client rejects `v2.` as unsupported rather than joining a
+ * different room, and a new client executes `v1.` only through the separately
+ * installed legacy-signaling adapter.
+ *
+ * This module deliberately does not parse whole URLs. The page extracts
+ * `location.hash` and passes the fragment in, exactly as today.
+ */
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+export declare const BLIND_ROOM_INVITE_VERSION = 2;
+export declare const BLIND_ROOM_INVITE_PREFIX = "v2.";
+/**
+ * Bound on the canonical policy carried by a policy-bearing v2 fragment.
+ *
+ * Status: PROPOSED. The release registry freezes the final value together with
+ * the binary policy codec; this bound only has to be large enough for a valid
+ * `RoomPolicyV4` and small enough to keep a shared link scannable as a QR code.
+ */
+export declare const MAX_INVITE_POLICY_BYTES = 512;
+export type LegacyRoomInviteV1 = {
+    version: 1;
+    capability: Uint8Array;
+};
+export type BlindRoomInviteV2 = {
+    version: 2;
+    form: "default";
+    capability: Uint8Array;
+} | {
+    version: 2;
+    form: "room-policy";
+    capability: Uint8Array;
+    roomPolicy: RoomPolicyV4;
+};
+export type ParsedRoomInvite = LegacyRoomInviteV1 | BlindRoomInviteV2;
+export declare class RoomInviteParseError extends Error {
+    readonly name = "RoomInviteParseError";
+    constructor(message: string);
+}
+/**
+ * Thrown when a v1 invitation is executed in a build without the optional
+ * legacy-signaling adapter. It is raised before any adapter or network work
+ * and before capability or identity disclosure, and it never maps v1 to v2.
+ */
+export declare class LegacySignalingAdapterUnavailableError extends Error {
+    readonly name = "LegacySignalingAdapterUnavailableError";
+    readonly code = "legacy-signaling-adapter-unavailable";
+    readonly inviteVersion = 1;
+    constructor();
+}
+/**
+ * Thrown when the legacy-named `signalingServerUrl` option is supplied with a
+ * v2 invitation but no exact trusted alias maps it to a signed store
+ * descriptor. Failing here is deliberate: silently ignoring the value or
+ * substituting the default store would send the user somewhere they did not
+ * ask for.
+ */
+export declare class BlindStoreAliasResolutionError extends Error {
+    readonly name = "BlindStoreAliasResolutionError";
+    readonly code = "blind-store-alias-unmapped";
+    readonly option = "signalingServerUrl";
+    constructor();
+}
+/**
+ * Parse a fragment into a closed versioned result, preserving the version.
+ *
+ * A leading `#` is accepted here and only here; it is not part of the
+ * canonical invitation.
+ */
+export declare const parseRoomInvite: (fragment: string) => ParsedRoomInvite;
+/** The capability-only default fragment: `v2.<43-character-base64url>`. */
+export declare const encodeBlindRoomInviteV2Default: (capability: Uint8Array) => string;
+/**
+ * The policy-bearing fragment used by the advanced-room flow, so a PIN, PQ, or
+ * cover choice survives sharing without appearing in an HTTP query.
+ */
+export declare const encodeBlindRoomInviteV2WithPolicy: (capability: Uint8Array, roomPolicy: RoomPolicyV4) => string;
+/**
+ * The room policy an invitation resolves to.
+ *
+ * A bare v2 invitation resolves to the frozen default rather than to whatever
+ * the current application default happens to be; a policy-bearing invitation
+ * resolves to its exact decoded policy with no defaults merged in.
+ */
+export declare const resolveInviteRoomPolicy: (invite: BlindRoomInviteV2) => RoomPolicyV4;