@xnetjs/sync 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,3203 @@
+import { DID, ContentId, PolicyEvaluator, AuthDecision } from '@xnetjs/core';
+import { UnifiedSignature, SignatureWire, SecurityLevel, EncryptedData, WrappedKey } from '@xnetjs/crypto';
+import { PQKeyRegistry, HybridKeyBundle } from '@xnetjs/identity';
+
+/**
+ * Lamport clock utilities for total ordering in distributed systems.
+ *
+ * Lamport timestamps provide a simple, single-integer logical clock that:
+ * - Guarantees total ordering of events (with tie-breaker)
+ * - Requires no coordination between nodes
+ * - Is trivial to merge (max + 1)
+ *
+ * Combined with author DID as tie-breaker, this gives deterministic
+ * ordering across all nodes without the complexity of vector clocks.
+ */
+
+/**
+ * A Lamport timestamp with author for deterministic tie-breaking.
+ *
+ * Two changes are ordered by:
+ * 1. Lamport time (lower = earlier)
+ * 2. Author DID string comparison (deterministic tie-breaker)
+ */
+interface LamportTimestamp {
+    /** Logical time - increments on each change */
+    time: number;
+    /** Author DID - used for deterministic tie-breaking */
+    author: DID;
+}
+/**
+ * A Lamport clock that tracks the current logical time.
+ * Each author maintains their own clock instance.
+ */
+interface LamportClock {
+    /** Current logical time */
+    time: number;
+    /** The author's DID */
+    author: DID;
+}
+/**
+ * Create a new Lamport clock for an author.
+ * Starts at time 0; first tick will produce time 1.
+ */
+declare function createLamportClock(author: DID): LamportClock;
+/**
+ * Tick the clock and return a new timestamp.
+ * This should be called when creating a new change.
+ *
+ * @param clock - The clock to tick
+ * @returns A tuple of [newClock, timestamp]
+ */
+declare function tick(clock: LamportClock): [LamportClock, LamportTimestamp];
+/**
+ * Update the clock after receiving a change from another node.
+ * Sets our time to max(ourTime, receivedTime) so next tick is greater.
+ *
+ * @param clock - Our local clock
+ * @param receivedTime - The Lamport time from the received change
+ * @returns Updated clock
+ */
+declare function receive(clock: LamportClock, receivedTime: number): LamportClock;
+/**
+ * Compare two Lamport timestamps for ordering.
+ *
+ * @returns
+ *   -1 if a < b (a happened before b)
+ *    1 if a > b (a happened after b)
+ *    0 if a === b (same timestamp - should be rare)
+ */
+declare function compareLamportTimestamps(a: LamportTimestamp, b: LamportTimestamp): -1 | 0 | 1;
+/**
+ * Check if timestamp a is strictly before timestamp b.
+ */
+declare function isBefore(a: LamportTimestamp, b: LamportTimestamp): boolean;
+/**
+ * Check if timestamp a is strictly after timestamp b.
+ */
+declare function isAfter(a: LamportTimestamp, b: LamportTimestamp): boolean;
+/**
+ * Serialize a Lamport timestamp to a string for storage/sorting.
+ * Format: {time-padded-16-digits}-{author}
+ *
+ * The padding ensures lexicographic string sorting matches numeric sorting.
+ */
+declare function serializeTimestamp(ts: LamportTimestamp): string;
+/**
+ * Parse a serialized Lamport timestamp.
+ */
+declare function parseTimestamp(serialized: string): LamportTimestamp;
+/**
+ * Get the maximum Lamport time from a list of timestamps.
+ * Useful for initializing a clock after loading existing changes.
+ */
+declare function maxTime(timestamps: LamportTimestamp[]): number;
+
+/**
+ * Change types for xNet sync primitives
+ *
+ * Change<T> is the universal unit of sync for both Yjs (CRDT) and
+ * event-sourced (records) data. It replaces SignedUpdate and RecordOperation
+ * with a single, generic type.
+ */
+
+/**
+ * Current protocol version for Change<T>.
+ *
+ * Version history:
+ * - 3: Multi-level cryptography with hybrid signatures (Ed25519 + ML-DSA)
+ * - 2: V2 compact format with abbreviated field names
+ * - 1: Initial versioned protocol (adds protocolVersion field)
+ * - 0/undefined: Legacy unversioned changes (backward compat)
+ */
+declare const CURRENT_PROTOCOL_VERSION = 3;
+/**
+ * A signed change with chain linkage and Lamport ordering.
+ * Generic T allows different payload types for different use cases:
+ * - YjsUpdate for rich text documents
+ * - RecordPayload for database operations
+ *
+ * Changes can optionally be part of a transaction batch, which groups
+ * related changes that should be applied atomically. This is important for:
+ * - Multi-node operations (move task between projects)
+ * - Undo/redo grouping
+ * - Audit trails ("user did X" as a single action)
+ * - Future blockchain integration (batch = transaction)
+ */
+interface Change<T = unknown> {
+    /**
+     * Protocol version of this change.
+     * - undefined: Legacy change (protocol v0, backward compat)
+     * - 1+: Versioned change with protocol version
+     *
+     * Used for version negotiation and migration paths.
+     */
+    protocolVersion?: number;
+    /** Unique change ID (nanoid) */
+    id: string;
+    /** Change type (e.g., 'yjs-update', 'create-item', 'update-item') */
+    type: string;
+    /** The actual change data */
+    payload: T;
+    /** Content-addressed hash of this change */
+    hash: ContentId;
+    /** Hash of the previous change in the chain (null for first) */
+    parentHash: ContentId | null;
+    /** DID of the author */
+    authorDID: DID;
+    /** Ed25519 signature of the hash */
+    signature: Uint8Array;
+    /** Wall clock timestamp (milliseconds) - for display, not ordering */
+    wallTime: number;
+    /** Lamport timestamp for ordering */
+    lamport: LamportTimestamp;
+    /**
+     * Groups changes that should be treated as a single atomic operation.
+     * All changes with the same batchId were created in one transaction.
+     * For undo/redo, the entire batch should be undone/redone together.
+     */
+    batchId?: string;
+    /**
+     * Position of this change within the batch (0-indexed).
+     * Ensures deterministic ordering when replaying.
+     */
+    batchIndex?: number;
+    /**
+     * Total number of changes in the batch.
+     * Receivers can wait for all changes before committing.
+     */
+    batchSize?: number;
+}
+/**
+ * An unsigned change (before hash and signature are computed).
+ * Used as input to signChange().
+ */
+interface UnsignedChange<T = unknown> {
+    protocolVersion?: number;
+    id: string;
+    type: string;
+    payload: T;
+    parentHash: ContentId | null;
+    authorDID: DID;
+    wallTime: number;
+    lamport: LamportTimestamp;
+    batchId?: string;
+    batchIndex?: number;
+    batchSize?: number;
+}
+/**
+ * Options for creating a change
+ */
+interface CreateChangeOptions<T> {
+    id: string;
+    type: string;
+    payload: T;
+    parentHash: ContentId | null;
+    authorDID: DID;
+    lamport: LamportTimestamp;
+    wallTime?: number;
+    batchId?: string;
+    batchIndex?: number;
+    batchSize?: number;
+}
+/**
+ * Create an unsigned change from options
+ */
+declare function createUnsignedChange<T>(options: CreateChangeOptions<T>): UnsignedChange<T>;
+/**
+ * Generate a unique batch ID for grouping changes in a transaction.
+ */
+declare function createBatchId(): string;
+/**
+ * Compute the hash of an unsigned change.
+ * The hash is computed over a canonical JSON representation with sorted keys.
+ *
+ * Version handling:
+ * - protocolVersion 0/undefined (legacy): hash without protocolVersion field
+ * - protocolVersion 1+: include protocolVersion in hash computation
+ */
+declare function computeChangeHash<T>(unsigned: UnsignedChange<T>): ContentId;
+/**
+ * Sign an unsigned change, producing a fully signed Change<T>.
+ *
+ * @param unsigned - The change to sign
+ * @param signingKey - Ed25519 private key (32 bytes)
+ * @returns Signed change with hash and signature
+ */
+declare function signChange<T>(unsigned: UnsignedChange<T>, signingKey: Uint8Array): Change<T>;
+/**
+ * Verify a change's signature against a public key.
+ *
+ * Protocol version handling:
+ * - Accepts changes with protocolVersion <= CURRENT_PROTOCOL_VERSION
+ * - Logs warning for future versions but still attempts verification
+ * - Never rejects based on version alone (graceful degradation)
+ *
+ * @param change - The change to verify
+ * @param publicKey - Ed25519 public key (32 bytes)
+ * @returns true if the signature is valid
+ */
+declare function verifyChange<T>(change: Change<T>, publicKey: Uint8Array): boolean;
+/**
+ * Verify that a change's hash is correct (not tampered).
+ * This re-computes the hash from the change data and compares.
+ *
+ * Handles both legacy (no protocolVersion) and versioned changes.
+ */
+declare function verifyChangeHash<T>(change: Change<T>): boolean;
+/**
+ * Create a unique change ID.
+ * Uses crypto.randomUUID for uniqueness.
+ */
+declare function createChangeId(): string;
+
+/**
+ * Hash chain utilities for managing linked changes.
+ *
+ * Changes form a hash chain where each change references its parent via
+ * parentHash. This enables:
+ * - Detecting forks (two changes with the same parent)
+ * - Validating chain integrity
+ * - Finding chain heads (latest changes)
+ */
+
+/**
+ * Result of validating a chain of changes
+ */
+interface ChainValidationResult {
+    /** Whether the chain is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+    /** Whether a fork was detected */
+    forkDetected?: boolean;
+    /** Hash where the fork occurred */
+    forkPoint?: ContentId;
+}
+/**
+ * Information about a fork in the chain
+ */
+interface Fork<T = unknown> {
+    /** The common ancestor hash where the fork occurred */
+    commonAncestor: ContentId;
+    /** Changes in the first branch (by Lamport timestamp) */
+    branch1: Change<T>[];
+    /** Changes in the second branch (by Lamport timestamp) */
+    branch2: Change<T>[];
+}
+/**
+ * Validate that a list of changes forms a valid hash chain.
+ * Checks:
+ * - All hashes are computed correctly (not tampered)
+ * - Parent references exist in the chain (or are null for roots)
+ *
+ * @param changes - The changes to validate
+ * @returns Validation result
+ */
+declare function validateChain<T>(changes: Change<T>[]): ChainValidationResult;
+/**
+ * Detect if there are any forks in the chain.
+ * A fork occurs when two different changes have the same parent.
+ *
+ * @param changes - The changes to check
+ * @returns Fork detection result
+ */
+declare function detectFork<T>(changes: Change<T>[]): {
+    hasFork: boolean;
+    forkPoints: ContentId[];
+};
+/**
+ * Get the head(s) of the chain - changes that are not parents of any other change.
+ * Multiple heads indicate a fork that needs resolution.
+ *
+ * @param changes - The changes to analyze
+ * @returns Array of head changes
+ */
+declare function getChainHeads<T>(changes: Change<T>[]): Change<T>[];
+/**
+ * Get the root(s) of the chain - changes with no parent (parentHash is null).
+ *
+ * @param changes - The changes to analyze
+ * @returns Array of root changes
+ */
+declare function getChainRoots<T>(changes: Change<T>[]): Change<T>[];
+/**
+ * Get the full ancestry of a change (all changes leading up to it).
+ *
+ * @param change - The change to get ancestry for
+ * @param allChanges - All available changes
+ * @returns Array of ancestor changes, from oldest to newest (excluding the input change)
+ */
+declare function getAncestry<T>(change: Change<T>, allChanges: Change<T>[]): Change<T>[];
+/**
+ * Find the common ancestor of two changes.
+ * Returns null if they have no common ancestor.
+ *
+ * @param a - First change
+ * @param b - Second change
+ * @param allChanges - All available changes
+ * @returns The common ancestor change, or null
+ */
+declare function findCommonAncestor<T>(a: Change<T>, b: Change<T>, allChanges: Change<T>[]): Change<T> | null;
+/**
+ * Get detailed fork information.
+ *
+ * @param changes - The changes to analyze
+ * @returns Array of Fork objects describing each fork
+ */
+declare function getForks<T>(changes: Change<T>[]): Fork<T>[];
+/**
+ * Sort changes in topological order (parents before children).
+ * Within the same level, sort by Lamport timestamp.
+ *
+ * @param changes - The changes to sort
+ * @returns Sorted changes array
+ */
+declare function topologicalSort<T>(changes: Change<T>[]): Change<T>[];
+
+/**
+ * Feature flag system for xNet protocol capabilities.
+ *
+ * Features are capabilities that can be negotiated between peers.
+ * Each feature has a protocol version where it was introduced, and may
+ * have dependencies on other features.
+ *
+ * Usage:
+ * ```typescript
+ * import { FEATURES, getEnabledFeatures, isFeatureEnabled } from '@xnetjs/sync'
+ *
+ * // Get features for a protocol version
+ * const features = getEnabledFeatures(2) // ['node-changes', 'yjs-updates', ...]
+ *
+ * // Check if a feature is enabled in a negotiated set
+ * if (isFeatureEnabled('schema-versioning', negotiatedFeatures)) {
+ *   // Use schema versioning
+ * }
+ * ```
+ */
+/**
+ * All known feature flag names.
+ * Defined as a union type to allow forward-references in FeatureConfig.
+ */
+type FeatureFlag = 'node-changes' | 'yjs-updates' | 'signed-yjs-envelopes' | 'batch-changes' | 'lamport-ordering' | 'hash-chains' | 'schema-versioning' | 'capability-negotiation' | 'peer-scoring' | 'schema-lenses' | 'unknown-preservation' | 'schema-inheritance' | 'federated-queries' | 'compressed-payloads';
+/**
+ * Feature configuration for a protocol capability.
+ */
+interface FeatureConfig {
+    /** Protocol version when this feature was introduced */
+    since: number;
+    /** Whether this feature is required (cannot be disabled) */
+    required: boolean;
+    /** Human-readable description */
+    description: string;
+    /** Features this one depends on (must be enabled if this is enabled) */
+    requires?: FeatureFlag[];
+    /** Features that conflict with this one (cannot both be enabled) */
+    conflicts?: FeatureFlag[];
+}
+/**
+ * Registry of all supported features.
+ *
+ * Features are organized by when they were introduced:
+ * - Protocol v1: Core sync primitives
+ * - Protocol v2: Schema versioning and capability negotiation
+ * - Protocol v3+: Future extensions
+ */
+declare const FEATURES: Record<FeatureFlag, FeatureConfig>;
+/**
+ * Array of all feature flag names.
+ */
+declare const ALL_FEATURES: FeatureFlag[];
+/**
+ * Get all features enabled at a given protocol version.
+ *
+ * @param protocolVersion - The protocol version to check
+ * @returns Array of feature flags enabled at this version
+ *
+ * @example
+ * ```typescript
+ * const v1Features = getEnabledFeatures(1)
+ * // ['node-changes', 'yjs-updates', 'signed-yjs-envelopes', ...]
+ *
+ * const v2Features = getEnabledFeatures(2)
+ * // [...v1Features, 'schema-versioning', 'capability-negotiation', ...]
+ * ```
+ */
+declare function getEnabledFeatures(protocolVersion: number): FeatureFlag[];
+/**
+ * Check if a feature is enabled in a negotiated feature set.
+ *
+ * @param feature - The feature to check
+ * @param enabledFeatures - The set of enabled features (from negotiation)
+ * @returns true if the feature is in the enabled set
+ *
+ * @example
+ * ```typescript
+ * const negotiated = ['node-changes', 'yjs-updates', 'schema-versioning']
+ * isFeatureEnabled('schema-versioning', negotiated) // true
+ * isFeatureEnabled('federated-queries', negotiated) // false
+ * ```
+ */
+declare function isFeatureEnabled(feature: FeatureFlag, enabledFeatures: readonly FeatureFlag[] | readonly string[]): boolean;
+/**
+ * Get required features for a protocol version.
+ * These features cannot be disabled during negotiation.
+ *
+ * @param protocolVersion - The protocol version to check
+ * @returns Array of required feature flags
+ */
+declare function getRequiredFeatures(protocolVersion: number): FeatureFlag[];
+/**
+ * Get optional features for a protocol version.
+ * These features can be enabled or disabled during negotiation.
+ *
+ * @param protocolVersion - The protocol version to check
+ * @returns Array of optional feature flags
+ */
+declare function getOptionalFeatures(protocolVersion: number): FeatureFlag[];
+/**
+ * Get the minimum protocol version required for a feature.
+ *
+ * @param feature - The feature to check
+ * @returns The protocol version when this feature was introduced
+ */
+declare function getFeatureVersion(feature: FeatureFlag): number;
+/**
+ * Check if a feature is available at a given protocol version.
+ *
+ * @param feature - The feature to check
+ * @param protocolVersion - The protocol version
+ * @returns true if the feature is available at this version
+ */
+declare function isFeatureAvailable(feature: FeatureFlag, protocolVersion: number): boolean;
+/**
+ * Result of validating a feature set.
+ */
+interface FeatureValidationResult {
+    valid: boolean;
+    errors: FeatureValidationError[];
+    warnings: FeatureValidationWarning[];
+}
+interface FeatureValidationError {
+    type: 'missing-dependency' | 'conflict' | 'version-mismatch' | 'missing-required';
+    feature: FeatureFlag;
+    message: string;
+    relatedFeature?: FeatureFlag;
+}
+interface FeatureValidationWarning {
+    type: 'deprecated' | 'experimental';
+    feature: FeatureFlag;
+    message: string;
+}
+/**
+ * Get the dependencies of a feature (features it requires).
+ *
+ * @param feature - The feature to check
+ * @returns Array of required features, or empty array if none
+ */
+declare function getFeatureDependencies(feature: FeatureFlag): FeatureFlag[];
+/**
+ * Get features that conflict with a given feature.
+ *
+ * @param feature - The feature to check
+ * @returns Array of conflicting features, or empty array if none
+ */
+declare function getFeatureConflicts(feature: FeatureFlag): FeatureFlag[];
+/**
+ * Get all transitive dependencies of a feature (recursive).
+ *
+ * @param feature - The feature to check
+ * @param visited - Set of already-visited features (for cycle detection)
+ * @returns Array of all required features (direct and transitive)
+ */
+declare function getAllDependencies(feature: FeatureFlag, visited?: Set<FeatureFlag>): FeatureFlag[];
+/**
+ * Validate a set of features for consistency.
+ *
+ * Checks for:
+ * - Missing required dependencies
+ * - Conflicting features
+ * - Required features that are missing
+ * - Version compatibility issues
+ *
+ * @param features - Array of features to validate
+ * @param protocolVersion - The protocol version context
+ * @returns Validation result with errors and warnings
+ */
+declare function validateFeatureSet(features: readonly FeatureFlag[], protocolVersion?: number): FeatureValidationResult;
+/**
+ * Compute the intersection of two feature sets.
+ * Used during negotiation to find common features.
+ *
+ * @param local - Local peer's features
+ * @param remote - Remote peer's features
+ * @returns Features present in both sets
+ */
+declare function intersectFeatures(local: readonly FeatureFlag[], remote: readonly FeatureFlag[] | readonly string[]): FeatureFlag[];
+/**
+ * Compute the difference between two feature sets.
+ * Returns features in `a` that are not in `b`.
+ *
+ * @param a - First feature set
+ * @param b - Second feature set
+ * @returns Features in a but not in b
+ */
+declare function diffFeatures(a: readonly FeatureFlag[], b: readonly FeatureFlag[] | readonly string[]): FeatureFlag[];
+/**
+ * Add all dependencies to a feature set (closure).
+ * Ensures the set is valid by including all required dependencies.
+ *
+ * @param features - Initial feature set
+ * @returns Feature set with all dependencies included
+ */
+declare function addDependencies(features: readonly FeatureFlag[]): FeatureFlag[];
+
+/**
+ * Version negotiation protocol for xNet peers.
+ *
+ * When two peers connect, they exchange capability information and
+ * negotiate a common set of features they both support. This allows:
+ * - Older clients to work with newer servers (backward compatibility)
+ * - Newer clients to work with older servers (graceful degradation)
+ * - Feature-specific behavior based on negotiated capabilities
+ *
+ * Usage:
+ * ```typescript
+ * import { VersionNegotiator, createLocalCapabilities } from '@xnetjs/sync'
+ *
+ * const negotiator = new VersionNegotiator()
+ * const local = createLocalCapabilities('did:key:z...', ['node-changes', 'yjs-updates'])
+ *
+ * // On receiving remote capabilities:
+ * const session = negotiator.negotiate(local, remoteCapabilities)
+ * if (session.success) {
+ *   if (session.canUse('schema-versioning')) {
+ *     // Use schema versioning
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Capabilities advertised by a peer during connection.
+ */
+interface PeerCapabilities {
+    /** Peer's DID */
+    peerId: string;
+    /** Maximum protocol version supported */
+    protocolVersion: number;
+    /** Minimum protocol version supported */
+    minProtocolVersion: number;
+    /** Features enabled on this peer */
+    features: FeatureFlag[];
+    /** Package version string (e.g., '0.5.0') */
+    packageVersion: string;
+    /** Schema IRIs this peer understands (optional) */
+    schemas?: string[];
+}
+/**
+ * Result of a successful negotiation.
+ */
+interface NegotiatedSession {
+    success: true;
+    /** Remote peer's ID */
+    peerId: string;
+    /** Agreed protocol version (highest common version) */
+    agreedVersion: number;
+    /** Features both peers support */
+    commonFeatures: FeatureFlag[];
+    /** Warnings about degraded functionality */
+    warnings: NegotiationWarning[];
+    /**
+     * Check if a feature can be used in this session.
+     */
+    canUse(feature: FeatureFlag): boolean;
+}
+/**
+ * Result of a failed negotiation.
+ */
+interface NegotiationFailure {
+    success: false;
+    /** Error code */
+    error: 'incompatible-versions' | 'missing-required-features' | 'invalid-capabilities';
+    /** Human-readable message */
+    message: string;
+    /** Local protocol version */
+    localVersion: number;
+    /** Remote protocol version */
+    remoteVersion: number;
+    /** Suggestion for resolving the issue */
+    suggestion: 'upgrade-client' | 'upgrade-hub' | 'upgrade-both' | 'contact-support';
+}
+/**
+ * Warning about potential issues in a negotiated session.
+ */
+interface NegotiationWarning {
+    type: 'degraded-features' | 'version-mismatch' | 'unknown-features';
+    message: string;
+    /** Features affected by this warning */
+    affectedFeatures?: FeatureFlag[];
+}
+/**
+ * Result type for negotiation (success or failure).
+ */
+type NegotiationResult = NegotiatedSession | NegotiationFailure;
+/**
+ * Create local capabilities for negotiation.
+ *
+ * @param peerId - Local peer's DID
+ * @param features - Features to advertise (defaults to all enabled at current version)
+ * @param options - Additional options
+ * @returns PeerCapabilities for this peer
+ */
+declare function createLocalCapabilities(peerId: string, features?: FeatureFlag[], options?: {
+    packageVersion?: string;
+    minProtocolVersion?: number;
+    schemas?: string[];
+}): PeerCapabilities;
+/**
+ * Parse capabilities from a handshake message.
+ * Handles missing or malformed fields gracefully.
+ *
+ * @param message - Raw handshake message
+ * @returns Parsed capabilities or null if invalid
+ */
+declare function parseCapabilities(message: unknown): PeerCapabilities | null;
+/**
+ * Handles version negotiation between peers.
+ *
+ * The negotiation process:
+ * 1. Find highest common protocol version
+ * 2. Check version ranges overlap
+ * 3. Find common feature set
+ * 4. Verify required features are present
+ * 5. Generate warnings for degraded functionality
+ */
+declare class VersionNegotiator {
+    /**
+     * Negotiate capabilities between local and remote peers.
+     *
+     * @param local - Local peer's capabilities
+     * @param remote - Remote peer's capabilities
+     * @returns Negotiated session or failure result
+     */
+    negotiate(local: PeerCapabilities, remote: PeerCapabilities): NegotiationResult;
+    /**
+     * Validate that a set of capabilities is well-formed.
+     *
+     * @param capabilities - Capabilities to validate
+     * @returns Validation result with errors if any
+     */
+    validateCapabilities(capabilities: PeerCapabilities): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Create a failure result with appropriate suggestion.
+     */
+    private createFailure;
+    /**
+     * Generate warnings about degraded functionality.
+     */
+    private generateWarnings;
+}
+/**
+ * Default negotiator instance for convenience.
+ */
+declare const defaultNegotiator: VersionNegotiator;
+
+/**
+ * Sync provider interfaces and types.
+ *
+ * A SyncProvider is responsible for connecting to the sync network,
+ * broadcasting changes to peers, and receiving changes from peers.
+ * Different implementations can use different transports (WebRTC, WebSocket, etc.)
+ */
+
+/**
+ * Connection status of a sync provider.
+ */
+type SyncStatus = 'disconnected' | 'connecting' | 'synced' | 'syncing' | 'error';
+/**
+ * Information about a connected peer.
+ */
+interface PeerInfo {
+    /** Unique peer identifier */
+    id: string;
+    /** Human-readable name (if available) */
+    name?: string;
+    /** When the peer connected */
+    connectedAt: number;
+    /** Last activity timestamp */
+    lastSeen: number;
+    /** Peer's advertised capabilities (after handshake) */
+    capabilities?: PeerCapabilities;
+    /** Negotiated session with this peer */
+    negotiatedSession?: NegotiatedSession;
+}
+/**
+ * Events emitted by sync providers.
+ */
+interface SyncProviderEvents<T = unknown> {
+    /** Fired when sync status changes */
+    'status-change': (status: SyncStatus) => void;
+    /** Fired when a single change is received from a peer */
+    'change-received': (change: Change<T>, peerId: string) => void;
+    /** Fired when multiple changes are synced */
+    'changes-synced': (changes: Change<T>[]) => void;
+    /** Fired when a peer connects */
+    'peer-connected': (peer: PeerInfo) => void;
+    /** Fired when a peer disconnects */
+    'peer-disconnected': (peerId: string) => void;
+    /** Fired on error */
+    error: (error: Error) => void;
+    /**
+     * Fired when a change with an unknown type is received.
+     * The change is still stored in the change log for forward compatibility,
+     * but cannot be processed by the current version.
+     */
+    'unknown-change-type': (change: Change<unknown>, peerId: string) => void;
+    /**
+     * Fired when capability negotiation completes with a peer.
+     * Includes the negotiated session with common features.
+     */
+    'negotiation-complete': (peerId: string, session: NegotiatedSession) => void;
+    /**
+     * Fired when capability negotiation fails with a peer.
+     * The peer will be disconnected after this event.
+     */
+    'negotiation-failed': (peerId: string, error: string, suggestion: string) => void;
+    /**
+     * Fired when operating with degraded features due to peer compatibility.
+     * Includes warnings about unavailable features.
+     */
+    'capability-degraded': (peerId: string, warnings: string[]) => void;
+}
+/**
+ * Event listener type for type-safe event handling.
+ */
+type SyncEventListener<T, E extends keyof SyncProviderEvents<T>> = SyncProviderEvents<T>[E];
+/**
+ * Base interface for all sync providers.
+ *
+ * Implementations include:
+ * - y-webrtc provider for Yjs documents
+ * - Custom provider for event-sourced records
+ * - Hybrid providers that support both
+ */
+interface SyncProvider<T = unknown> {
+    /** Current sync status */
+    readonly status: SyncStatus;
+    /** List of connected peer IDs */
+    readonly peers: string[];
+    /** Detailed information about connected peers */
+    readonly peerInfo: Map<string, PeerInfo>;
+    /** Local peer's capabilities */
+    readonly localCapabilities: PeerCapabilities;
+    /**
+     * Check if a feature can be used with a specific peer.
+     * Returns false if not negotiated or feature unavailable.
+     */
+    canUseFeature(peerId: string, feature: FeatureFlag): boolean;
+    /**
+     * Get the negotiated session for a peer.
+     * Returns undefined if not yet negotiated.
+     */
+    getNegotiatedSession(peerId: string): NegotiatedSession | undefined;
+    /**
+     * Connect to the sync network.
+     * This may involve signaling servers, DHT lookups, etc.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the sync network.
+     * Closes all peer connections gracefully.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Broadcast a change to all connected peers.
+     *
+     * @param change - The change to broadcast
+     */
+    broadcast(change: Change<T>): Promise<void>;
+    /**
+     * Request changes from a specific peer.
+     * Used for initial sync or catching up.
+     *
+     * @param peerId - The peer to request from
+     * @param since - Optional hash to request changes since
+     * @returns Array of changes
+     */
+    requestChanges(peerId: string, since?: string): Promise<Change<T>[]>;
+    /**
+     * Request changes from all connected peers.
+     * Useful for catching up after reconnection.
+     *
+     * @param since - Optional hash to request changes since
+     * @returns Array of unique changes (deduplicated)
+     */
+    requestChangesFromAll(since?: string): Promise<Change<T>[]>;
+    /**
+     * Subscribe to an event.
+     *
+     * @param event - Event name
+     * @param listener - Event listener
+     */
+    on<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+    /**
+     * Unsubscribe from an event.
+     *
+     * @param event - Event name
+     * @param listener - Event listener to remove
+     */
+    off<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+    /**
+     * Subscribe to an event for a single occurrence.
+     *
+     * @param event - Event name
+     * @param listener - Event listener
+     */
+    once<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+}
+/**
+ * Options for creating a sync provider.
+ */
+interface SyncProviderOptions {
+    /** Signaling server URL(s) */
+    signalingServers?: string[];
+    /** Room/topic name for peer discovery */
+    room: string;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+    /** Whether to auto-reconnect on disconnect */
+    autoReconnect?: boolean;
+    /** Maximum reconnection attempts */
+    maxReconnectAttempts?: number;
+    /** Reconnection delay in milliseconds */
+    reconnectDelay?: number;
+    /** Local peer's DID for capability advertisement */
+    localDID?: string;
+    /** Features to advertise (defaults to all enabled at current protocol version) */
+    enabledFeatures?: FeatureFlag[];
+    /** Minimum protocol version to accept from peers */
+    minProtocolVersion?: number;
+    /** Whether to reject peers with incompatible versions (default: false, just warn) */
+    strictVersionCheck?: boolean;
+    /** Package version string for debugging */
+    packageVersion?: string;
+}
+/**
+ * Abstract base class for sync providers with common functionality.
+ * Implementations can extend this to reduce boilerplate.
+ */
+declare abstract class BaseSyncProvider<T = unknown> implements SyncProvider<T> {
+    protected _status: SyncStatus;
+    protected _peers: Map<string, PeerInfo>;
+    protected _listeners: Map<string, Set<(...args: unknown[]) => unknown>>;
+    /** Local capabilities for negotiation */
+    protected _localCapabilities: PeerCapabilities;
+    /** Version negotiator instance */
+    protected _negotiator: VersionNegotiator;
+    /** Provider options */
+    protected _options: SyncProviderOptions;
+    constructor(options: SyncProviderOptions);
+    get status(): SyncStatus;
+    get peers(): string[];
+    get peerInfo(): Map<string, PeerInfo>;
+    get localCapabilities(): PeerCapabilities;
+    /**
+     * Check if a feature can be used with a specific peer.
+     */
+    canUseFeature(peerId: string, feature: FeatureFlag): boolean;
+    /**
+     * Get the negotiated session for a peer.
+     */
+    getNegotiatedSession(peerId: string): NegotiatedSession | undefined;
+    abstract connect(): Promise<void>;
+    abstract disconnect(): Promise<void>;
+    abstract broadcast(change: Change<T>): Promise<void>;
+    abstract requestChanges(peerId: string, since?: string): Promise<Change<T>[]>;
+    requestChangesFromAll(since?: string): Promise<Change<T>[]>;
+    on<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+    off<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+    once<E extends keyof SyncProviderEvents<T>>(event: E, listener: SyncProviderEvents<T>[E]): void;
+    protected emit<E extends keyof SyncProviderEvents<T>>(event: E, ...args: Parameters<SyncProviderEvents<T>[E]>): void;
+    protected setStatus(status: SyncStatus): void;
+    protected addPeer(id: string, name?: string): void;
+    protected removePeer(id: string): void;
+    protected updatePeerLastSeen(id: string): void;
+    /**
+     * Negotiate capabilities with a peer.
+     * Called when a peer connects and sends their capabilities.
+     *
+     * @param peerId - The peer's ID
+     * @param remoteCapabilities - The peer's advertised capabilities
+     * @returns Negotiation result (success or failure)
+     */
+    protected negotiateWithPeer(peerId: string, remoteCapabilities: PeerCapabilities): NegotiationResult;
+    /**
+     * Get features available with all connected peers.
+     * Returns the intersection of all negotiated feature sets.
+     */
+    getCommonFeatures(): FeatureFlag[];
+    /**
+     * Check if a feature can be used with all connected peers.
+     */
+    canUseFeatureWithAll(feature: FeatureFlag): boolean;
+}
+
+/**
+ * Signed Yjs Envelopes - Per-update signing and verification for Yjs sync messages
+ *
+ * Every outgoing Yjs update is wrapped in a signed envelope containing the author's DID
+ * and a multi-level signature (Ed25519 and/or ML-DSA-65) over the BLAKE3 hash of the
+ * update bytes plus metadata.
+ *
+ * V2 introduces:
+ * - Multi-level signature support (Level 0, 1, 2)
+ * - Document ID binding
+ * - Wire format with compact JSON encoding
+ *
+ * V1 is retained for backward compatibility.
+ */
+
+/**
+ * A signed envelope wrapping a Yjs update (V1 format).
+ * @deprecated Use SignedYjsEnvelopeV2 for new code
+ */
+interface SignedYjsEnvelopeV1 {
+    /** Raw Yjs update bytes */
+    update: Uint8Array;
+    /** Author's DID (did:key:...) */
+    authorDID: string;
+    /** Ed25519 signature over BLAKE3(update) */
+    signature: Uint8Array;
+    /** Wall clock timestamp (for ordering/debugging) */
+    timestamp: number;
+    /** Yjs clientID this author uses in this session */
+    clientId: number;
+}
+/**
+ * A signed envelope wrapping a Yjs update (V2 format with multi-level signatures).
+ */
+interface SignedYjsEnvelopeV2 {
+    /** Wire format version */
+    v: 2;
+    /** Raw Yjs update bytes */
+    update: Uint8Array;
+    /** Envelope metadata */
+    meta: {
+        /** Author's DID (did:key:...) */
+        authorDID: DID;
+        /** Yjs clientID this author uses in this session */
+        clientId: number;
+        /** Wall clock timestamp (ms since epoch) */
+        timestamp: number;
+        /** Document ID this update applies to */
+        docId: string;
+    };
+    /** Multi-level signature over BLAKE3(update + meta) */
+    signature: UnifiedSignature;
+}
+/**
+ * Wire format for SignedYjsEnvelopeV2 (compact JSON).
+ */
+interface SignedYjsEnvelopeWire {
+    v: 2;
+    /** Base64-encoded update bytes */
+    u: string;
+    /** Metadata */
+    m: {
+        /** Author DID */
+        a: string;
+        /** Client ID */
+        c: number;
+        /** Timestamp */
+        t: number;
+        /** Document ID */
+        d: string;
+    };
+    /** Signature (wire format) */
+    s: SignatureWire;
+}
+/**
+ * Union type for all envelope versions.
+ * Use `isV2Envelope()` to check the version.
+ */
+type SignedYjsEnvelope = SignedYjsEnvelopeV1 | SignedYjsEnvelopeV2;
+/**
+ * Result of envelope verification (V1 format).
+ * @deprecated Use EnvelopeVerificationResult for V2
+ */
+interface EnvelopeVerifyResult {
+    valid: boolean;
+    reason?: 'invalid_signature' | 'did_resolution_failed' | 'update_too_large';
+}
+/**
+ * Result of envelope verification (V2 format with details).
+ */
+interface EnvelopeVerificationResult {
+    valid: boolean;
+    level: SecurityLevel;
+    errors: string[];
+    authorDID: DID;
+    clientId: number;
+}
+/**
+ * Options for creating a signed envelope.
+ */
+interface CreateEnvelopeOptions {
+    /** Security level (default: 0 for Ed25519-only) */
+    level?: SecurityLevel;
+}
+/**
+ * Options for envelope verification.
+ */
+interface VerifyEnvelopeOptions {
+    /** PQ key registry for Level 1/2 verification */
+    registry?: PQKeyRegistry;
+    /** Expected document ID (optional, for extra validation) */
+    expectedDocId?: string;
+    /** Maximum age in ms (optional, for freshness check) */
+    maxAge?: number;
+    /** Minimum security level required */
+    minLevel?: SecurityLevel;
+    /** Verification policy */
+    policy?: 'strict' | 'permissive';
+}
+/**
+ * Check if an envelope is V2 format.
+ */
+declare function isV2Envelope(envelope: SignedYjsEnvelope): envelope is SignedYjsEnvelopeV2;
+/**
+ * Check if an envelope is V1 format.
+ */
+declare function isV1Envelope(envelope: SignedYjsEnvelope): envelope is SignedYjsEnvelopeV1;
+/**
+ * Sign a Yjs update using V1 format (Ed25519 only).
+ *
+ * @deprecated Use signYjsUpdateV2() for new code
+ *
+ * @param update - Raw Yjs update bytes
+ * @param authorDID - Author's DID (did:key:...)
+ * @param privateKey - Ed25519 private key (32 bytes)
+ * @param clientId - Yjs clientID for this session
+ * @returns SignedYjsEnvelopeV1 ready for transmission
+ */
+declare function signYjsUpdateV1(update: Uint8Array, authorDID: string, privateKey: Uint8Array, clientId: number): SignedYjsEnvelopeV1;
+/**
+ * Verify a V1 SignedYjsEnvelope.
+ *
+ * @deprecated Use verifyYjsEnvelopeV2() for V2 envelopes
+ */
+declare function verifyYjsEnvelopeV1(envelope: SignedYjsEnvelopeV1): EnvelopeVerifyResult;
+/**
+ * Sign a Yjs update using V2 format with multi-level signatures.
+ *
+ * @param update - Raw Yjs update bytes
+ * @param docId - Document ID this update applies to
+ * @param clientId - Yjs clientID for this session
+ * @param keyBundle - Key bundle for signing
+ * @param options - Signing options
+ * @returns SignedYjsEnvelopeV2 ready for transmission
+ *
+ * @example
+ * ```typescript
+ * const envelope = signYjsUpdateV2(update, 'doc-1', doc.clientID, keyBundle, { level: 1 })
+ * ws.send(encode({ type: 'sync-update', room, envelope: serializeYjsEnvelope(envelope) }))
+ * ```
+ */
+declare function signYjsUpdateV2(update: Uint8Array, docId: string, clientId: number, keyBundle: HybridKeyBundle, options?: CreateEnvelopeOptions): SignedYjsEnvelopeV2;
+/**
+ * Sign multiple updates in a batch using V2 format.
+ */
+declare function signYjsUpdateBatch(updates: Uint8Array[], docId: string, clientId: number, keyBundle: HybridKeyBundle, options?: CreateEnvelopeOptions): SignedYjsEnvelopeV2[];
+/**
+ * Verify a V2 SignedYjsEnvelope with multi-level signature support.
+ *
+ * @param envelope - The envelope to verify
+ * @param options - Verification options
+ * @returns Verification result with detailed errors
+ */
+declare function verifyYjsEnvelopeV2(envelope: SignedYjsEnvelopeV2, options?: VerifyEnvelopeOptions): Promise<EnvelopeVerificationResult>;
+/**
+ * Quick verification returning just boolean.
+ */
+declare function verifyYjsEnvelopeQuick(envelope: SignedYjsEnvelopeV2, options?: VerifyEnvelopeOptions): Promise<boolean>;
+/**
+ * Serialize V2 envelope to wire format.
+ */
+declare function serializeYjsEnvelope(envelope: SignedYjsEnvelopeV2): SignedYjsEnvelopeWire;
+/**
+ * Deserialize V2 envelope from wire format.
+ */
+declare function deserializeYjsEnvelope(wire: SignedYjsEnvelopeWire): SignedYjsEnvelopeV2;
+/**
+ * Calculate envelope size in bytes (approximate).
+ */
+declare function envelopeSize(envelope: SignedYjsEnvelopeV2): number;
+/**
+ * Sign a Yjs update, creating a SignedYjsEnvelope.
+ *
+ * This is the main API for signing updates. It creates a V1 envelope
+ * for backward compatibility when using simple Ed25519 keys, or a V2
+ * envelope when using a HybridKeyBundle.
+ *
+ * @overload V1 signature (legacy)
+ * @param update - Raw Yjs update bytes
+ * @param authorDID - Author's DID (did:key:...)
+ * @param privateKey - Ed25519 private key (32 bytes)
+ * @param clientId - Yjs clientID for this session
+ */
+declare function signYjsUpdate(update: Uint8Array, authorDID: string, privateKey: Uint8Array, clientId: number): SignedYjsEnvelopeV1;
+/**
+ * @overload V2 signature (multi-level)
+ * @param update - Raw Yjs update bytes
+ * @param docId - Document ID this update applies to
+ * @param clientId - Yjs clientID for this session
+ * @param keyBundle - Key bundle for signing
+ * @param options - Signing options
+ */
+declare function signYjsUpdate(update: Uint8Array, docId: string, clientId: number, keyBundle: HybridKeyBundle, options?: CreateEnvelopeOptions): SignedYjsEnvelopeV2;
+/**
+ * Verify a SignedYjsEnvelope (auto-detects version).
+ *
+ * For V1 envelopes, returns a simple valid/reason result.
+ * For V2 envelopes, returns a detailed verification result.
+ *
+ * @param envelope - The envelope to verify
+ * @param options - Verification options (V2 only)
+ */
+declare function verifyYjsEnvelope(envelope: SignedYjsEnvelopeV1): EnvelopeVerifyResult;
+declare function verifyYjsEnvelope(envelope: SignedYjsEnvelopeV2, options?: VerifyEnvelopeOptions): Promise<EnvelopeVerificationResult>;
+/**
+ * Type guard to check if a message contains a signed envelope.
+ */
+declare function hasSignedEnvelope(msg: unknown): msg is {
+    envelope: SignedYjsEnvelope;
+    [key: string]: unknown;
+};
+/**
+ * Check if a message is a legacy unsigned sync update.
+ */
+declare function isLegacyUpdate(msg: unknown): msg is {
+    data: Uint8Array;
+    [key: string]: unknown;
+};
+
+/**
+ * Yjs Update Size and Rate Limits
+ *
+ * Constants and utilities for preventing DoS via oversized or high-frequency Yjs updates.
+ */
+/** Maximum size of a single Yjs update (1MB) */
+declare const MAX_YJS_UPDATE_SIZE = 1048576;
+/** Maximum updates per second per connection */
+declare const MAX_YJS_UPDATES_PER_SECOND = 30;
+/** Maximum updates per minute per connection (sustained rate) */
+declare const MAX_YJS_UPDATES_PER_MINUTE = 600;
+/** Maximum document size (full state, 50MB) */
+declare const MAX_YJS_DOC_SIZE = 52428800;
+/** Chunk size for large initial syncs (256KB) */
+declare const YJS_SYNC_CHUNK_SIZE = 262144;
+/** Burst allowance above per-second limit */
+declare const YJS_RATE_BURST_ALLOWANCE = 10;
+/**
+ * Rate limiter configuration.
+ */
+interface RateLimiterConfig {
+    /** Maximum updates per second */
+    maxPerSecond: number;
+    /** Maximum updates per minute */
+    maxPerMinute: number;
+    /** Burst allowance above maxPerSecond */
+    burstAllowance: number;
+}
+/**
+ * Default rate limiter configuration.
+ */
+declare const DEFAULT_RATE_LIMITER_CONFIG: RateLimiterConfig;
+/**
+ * Extended config for rate limiter with cleanup options.
+ */
+interface YjsRateLimiterOptions extends Partial<RateLimiterConfig> {
+    /** How long until an entry is considered stale (default: 2 minutes) */
+    staleThresholdMs?: number;
+    /** Cleanup interval in ms (default: 30 seconds). Set to 0 to disable auto-cleanup. */
+    cleanupIntervalMs?: number;
+}
+/**
+ * Rate limiter for Yjs updates.
+ *
+ * Tracks per-peer update frequency and enforces both per-second and per-minute limits.
+ *
+ * @example
+ * ```typescript
+ * const limiter = new YjsRateLimiter()
+ *
+ * if (!limiter.allow(peerId)) {
+ *   // Reject update, rate limit exceeded
+ *   return { ok: false, reason: 'rate_exceeded' }
+ * }
+ * ```
+ */
+declare class YjsRateLimiter {
+    private secondWindows;
+    private minuteWindows;
+    private config;
+    private cleanupInterval;
+    private staleThresholdMs;
+    constructor(options?: YjsRateLimiterOptions);
+    /** Start periodic cleanup of stale entries. */
+    startCleanup(intervalMs?: number): void;
+    /** Stop periodic cleanup. */
+    stopCleanup(): void;
+    /** Remove entries whose windows have expired. Returns count removed. */
+    cleanupStale(): number;
+    /** Get number of tracked peers. */
+    get peerCount(): number;
+    /**
+     * Check if a peer can send another update.
+     *
+     * @param peerId - Peer identifier
+     * @returns true if allowed, false if rate-limited
+     */
+    allow(peerId: string): boolean;
+    /**
+     * Get current rate info for a peer (for debugging/monitoring).
+     */
+    getInfo(peerId: string): {
+        perSecond: number;
+        perMinute: number;
+    } | undefined;
+    /**
+     * Reset state for a disconnected peer.
+     */
+    remove(peerId: string): void;
+    /**
+     * Clear all state.
+     */
+    clear(): void;
+    /**
+     * Stop cleanup and clear all state.
+     */
+    destroy(): void;
+}
+/**
+ * Check if an update exceeds the size limit.
+ */
+declare function isUpdateTooLarge(update: Uint8Array, maxSize?: number): boolean;
+/**
+ * Check if a document state exceeds the size limit.
+ */
+declare function isDocumentTooLarge(state: Uint8Array, maxSize?: number): boolean;
+/**
+ * Calculate number of chunks needed for a large update.
+ */
+declare function calculateChunkCount(totalSize: number, chunkSize?: number): number;
+/**
+ * Split a large update into chunks.
+ */
+declare function chunkUpdate(update: Uint8Array, chunkSize?: number): Uint8Array[];
+/**
+ * Reassemble chunks into a single update.
+ */
+declare function reassembleChunks(chunks: Uint8Array[]): Uint8Array;
+
+/**
+ * Yjs State Integrity - Hash-at-Rest for Yjs document state
+ *
+ * Provides utilities to hash Yjs state on persist and verify on load,
+ * detecting storage-level corruption before it propagates.
+ */
+/**
+ * Compute a BLAKE3 hash of Yjs state bytes.
+ *
+ * @param state - Yjs state bytes (from Y.encodeStateAsUpdate)
+ * @returns Hex-encoded BLAKE3 hash
+ */
+declare function hashYjsState(state: Uint8Array): string;
+/**
+ * Verify that Yjs state bytes match an expected hash.
+ *
+ * @param state - Yjs state bytes to verify
+ * @param expectedHash - Expected hex-encoded BLAKE3 hash
+ * @returns true if hashes match, false if corrupted
+ */
+declare function verifyYjsStateIntegrity(state: Uint8Array, expectedHash: string): boolean;
+/**
+ * Error thrown when Yjs state is corrupted (hash mismatch).
+ */
+declare class YjsIntegrityError extends Error {
+    readonly docId: string;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    constructor(docId: string, expectedHash: string, actualHash: string);
+}
+/**
+ * Persisted Yjs document state with integrity hash.
+ */
+interface PersistedDocState {
+    /** The raw Yjs state (Y.encodeStateAsUpdate) */
+    state: Uint8Array;
+    /** BLAKE3 hex hash of state bytes */
+    hash: string;
+    /** When this was persisted */
+    persistedAt: number;
+    /** Number of updates merged since last snapshot */
+    updateCount: number;
+}
+/**
+ * Create a PersistedDocState from Yjs state bytes.
+ *
+ * @param state - Yjs state bytes
+ * @param updateCount - Number of updates in this state (default: 0)
+ * @returns PersistedDocState with computed hash
+ */
+declare function createPersistedDocState(state: Uint8Array, updateCount?: number): PersistedDocState;
+/**
+ * Verify a PersistedDocState's integrity.
+ *
+ * @param docId - Document ID (for error reporting)
+ * @param record - The persisted state record
+ * @throws YjsIntegrityError if hash doesn't match
+ */
+declare function verifyPersistedDocState(docId: string, record: PersistedDocState): void;
+/**
+ * Safely load Yjs state, verifying integrity if hash is present.
+ *
+ * @param docId - Document ID
+ * @param record - The persisted state record (may be legacy without hash)
+ * @returns The state bytes
+ * @throws YjsIntegrityError if hash exists and doesn't match
+ */
+declare function loadVerifiedState(docId: string, record: Partial<PersistedDocState> & {
+    state: Uint8Array;
+}): Uint8Array;
+/**
+ * Constants for compaction thresholds.
+ */
+/** Compact (re-encode and re-hash) after this many incremental updates */
+declare const COMPACTION_UPDATE_THRESHOLD = 100;
+/** Compact after this much time (ms) since last compaction */
+declare const COMPACTION_TIME_THRESHOLD = 3600000;
+/**
+ * Check if a document should be compacted.
+ *
+ * @param updateCount - Number of updates since last compaction
+ * @param persistedAt - When the state was last persisted
+ * @returns true if compaction is recommended
+ */
+declare function shouldCompact(updateCount: number, persistedAt: number): boolean;
+
+/**
+ * Yjs Peer Scoring - Track Yjs-specific misbehavior and auto-block repeat offenders
+ *
+ * Extends the concept of peer scoring with Yjs-specific metrics.
+ * Peers that repeatedly send invalid signatures, oversized updates, or exceed
+ * rate limits accumulate negative scores and are eventually auto-blocked.
+ */
+/**
+ * Yjs-specific peer metrics for tracking violations.
+ */
+interface YjsPeerMetrics {
+    /** Invalid Ed25519 signatures on Yjs envelopes */
+    invalidSignatures: number;
+    /** Updates exceeding size limit */
+    oversizedUpdates: number;
+    /** Updates exceeding rate limit */
+    rateExceeded: number;
+    /** Unsigned updates when signing required */
+    unsignedUpdates: number;
+    /** Updates from unattested clientIDs (Tier 3) */
+    unattestedClientIds: number;
+    /** Updates rejected by authorization policy */
+    unauthorizedUpdates: number;
+    /** Total valid updates (for ratio calculations) */
+    validUpdates: number;
+    /** First seen timestamp */
+    firstSeen: number;
+    /** Last violation timestamp */
+    lastViolation: number;
+}
+/**
+ * Violation types for peer scoring.
+ */
+type YjsViolationType = 'invalidSignature' | 'oversizedUpdate' | 'rateExceeded' | 'unsignedUpdate' | 'unattestedClientId' | 'unauthorizedUpdate';
+/**
+ * Action to take based on peer score.
+ */
+type PeerAction = 'allow' | 'warn' | 'throttle' | 'block';
+/**
+ * Optional telemetry collector interface for sync operations.
+ * Compatible with @xnetjs/telemetry TelemetryCollector.
+ */
+interface SyncTelemetry {
+    reportPerformance(metricName: string, durationMs: number, codeNamespace?: string): void;
+    reportUsage(metricName: string, value: number): void;
+    reportCrash(error: Error, context?: {
+        codeNamespace?: string;
+    }): void;
+    reportSecurityEvent(eventName: string, severity: 'low' | 'medium' | 'high' | 'critical'): void;
+}
+/**
+ * Configuration for Yjs peer scoring.
+ */
+interface YjsScoringConfig {
+    /** Points deducted per violation type */
+    penalties: {
+        invalidSignature: number;
+        oversizedUpdate: number;
+        rateExceeded: number;
+        unsignedUpdate: number;
+        unattestedClientId: number;
+        unauthorizedUpdate: number;
+    };
+    /** Score thresholds */
+    thresholds: {
+        warn: number;
+        throttle: number;
+        block: number;
+    };
+    /** Score recovery rate (points per tick of good behavior) */
+    recoveryRate: number;
+    /** Immediate block after N invalid signatures */
+    instantBlockAfter: number;
+    /**
+     * Optional telemetry collector for security events.
+     * When provided, YjsPeerScorer will report:
+     * - Security events for violations (invalid signatures, rate limits, etc.)
+     * - Usage metrics for peer actions (block, throttle, warn)
+     * - Performance metrics for score calculations
+     */
+    telemetry?: SyncTelemetry;
+}
+/**
+ * Default scoring configuration.
+ */
+declare const DEFAULT_YJS_SCORING_CONFIG: YjsScoringConfig;
+/**
+ * Peer scorer for Yjs-specific violations.
+ *
+ * Peers start at score 100. Violations deduct points based on severity.
+ * Score thresholds trigger different actions (warn, throttle, block).
+ *
+ * @example
+ * ```typescript
+ * const scorer = new YjsPeerScorer()
+ *
+ * // On violation:
+ * const action = scorer.penalize(peerId, 'invalidSignature')
+ * if (action === 'block') {
+ *   ws.close(4403, 'Blocked due to repeated violations')
+ * }
+ *
+ * // On valid update:
+ * scorer.recordValid(peerId)
+ *
+ * // Periodic recovery:
+ * setInterval(() => scorer.tick(), 60_000)
+ * ```
+ */
+declare class YjsPeerScorer {
+    private metrics;
+    private scores;
+    readonly config: YjsScoringConfig;
+    private telemetry?;
+    constructor(config?: Partial<YjsScoringConfig>);
+    /**
+     * Record a violation for a peer.
+     *
+     * @param peerId - Peer identifier
+     * @param reason - Type of violation
+     * @returns Action to take based on new score
+     */
+    penalize(peerId: string, reason: YjsViolationType): PeerAction;
+    /**
+     * Record a valid update (for ratio tracking + score recovery consideration).
+     */
+    recordValid(peerId: string): void;
+    /**
+     * Get current score for a peer.
+     * New peers start at 100.
+     */
+    getScore(peerId: string): number;
+    /**
+     * Get action for a given score.
+     */
+    getAction(score: number): PeerAction;
+    /**
+     * Get current action for a peer.
+     */
+    getPeerAction(peerId: string): PeerAction;
+    /**
+     * Recover scores over time (called periodically).
+     * Only recovers if no recent violations.
+     *
+     * @param recoveryWindow - Time in ms that must pass without violations (default: 60s)
+     */
+    tick(recoveryWindow?: number): void;
+    /**
+     * Get metrics for a peer (for debugging/monitoring).
+     */
+    getMetrics(peerId: string): YjsPeerMetrics | undefined;
+    /**
+     * Get all peer IDs with metrics.
+     */
+    getAllPeerIds(): string[];
+    /**
+     * Get all metrics (for monitoring endpoint).
+     */
+    getAllMetrics(): Map<string, YjsPeerMetrics>;
+    /**
+     * Remove all state for a disconnected peer.
+     */
+    remove(peerId: string): void;
+    /**
+     * Clear all state.
+     */
+    clear(): void;
+    /**
+     * Get violation ratio for a peer.
+     * Returns the ratio of violations to total operations.
+     */
+    getViolationRatio(peerId: string): number;
+    private getOrCreateMetrics;
+}
+
+/**
+ * Yjs authorization primitives: encrypted-at-rest state and peer auth gate.
+ */
+
+interface EncryptedYjsState {
+    nodeId: string;
+    version: 1;
+    encryptedState: Uint8Array;
+    nonce: Uint8Array;
+    stateVector: Uint8Array;
+    stateHash: Uint8Array;
+    checkpointedAt: number;
+    updatesSinceCheckpoint: number;
+}
+declare class YjsStateIntegrityError extends Error {
+    constructor(message?: string);
+}
+declare function encryptYjsState(state: Uint8Array, nodeId: string, contentKey: Uint8Array, options?: {
+    stateVector?: Uint8Array;
+    checkpointedAt?: number;
+    updatesSinceCheckpoint?: number;
+}): EncryptedYjsState;
+declare function decryptYjsState(encrypted: EncryptedYjsState, contentKey: Uint8Array): Uint8Array;
+declare function serializeEncryptedYjsState(state: EncryptedYjsState): Uint8Array;
+declare function deserializeEncryptedYjsState(bytes: Uint8Array): EncryptedYjsState;
+interface YjsAuthDecision {
+    allowed: boolean;
+    authorDID: DID;
+    cached: boolean;
+}
+interface YjsAuthGateOptions {
+    cacheTTL?: number;
+    now?: () => number;
+}
+declare class YjsAuthGate {
+    private readonly evaluator;
+    private readonly nodeId;
+    private static readonly DEFAULT_CACHE_TTL;
+    private readonly peerAuthCache;
+    private readonly cacheTTL;
+    private readonly now;
+    constructor(evaluator: PolicyEvaluator, nodeId: string, options?: YjsAuthGateOptions);
+    canApplyUpdate(envelope: Pick<SignedYjsEnvelopeV2, 'meta'>): Promise<YjsAuthDecision>;
+    invalidatePeer(did: DID): void;
+    invalidateAll(): void;
+}
+interface YjsCheckpointerOptions {
+    maxUpdates?: number;
+    maxAgeMs?: number;
+    now?: () => number;
+}
+declare class YjsCheckpointer {
+    private readonly maxUpdates;
+    private readonly maxAgeMs;
+    private readonly now;
+    constructor(options?: YjsCheckpointerOptions);
+    shouldCheckpoint(state: Pick<EncryptedYjsState, 'updatesSinceCheckpoint' | 'checkpointedAt'>): boolean;
+    checkpoint(input: {
+        state: Uint8Array;
+        nodeId: string;
+        contentKey: Uint8Array;
+        stateVector?: Uint8Array;
+    }): EncryptedYjsState;
+}
+declare function toEncryptedData(state: EncryptedYjsState): EncryptedData;
+
+/**
+ * Yjs authorized sync manager and provider.
+ */
+
+type GrantLikeNode = {
+    schemaId?: string;
+    properties?: Record<string, unknown>;
+};
+type GrantEvent = {
+    node?: GrantLikeNode | null;
+};
+interface YDocLike {
+    emit?: (event: string, args: unknown[]) => void;
+}
+interface YDocCodec<TDoc extends YDocLike = YDocLike> {
+    createDoc(nodeId: string): TDoc;
+    applyUpdate(doc: TDoc, update: Uint8Array, origin?: string): void;
+    encodeStateAsUpdate(doc: TDoc): Uint8Array;
+    encodeStateVector(doc: TDoc): Uint8Array;
+}
+type AuthorizedRoom<TDoc extends YDocLike = YDocLike> = {
+    nodeId: string;
+    doc: TDoc;
+    contentKey: Uint8Array;
+    authGate: YjsAuthGate;
+    authorizedPeers: Set<DID>;
+};
+type AuthorizedDoc<TDoc extends YDocLike = YDocLike> = {
+    doc: TDoc;
+    nodeId: string;
+    mode: 'read' | 'write';
+    contentKey: Uint8Array;
+    room?: AuthorizedRoom<TDoc>;
+    release: () => void;
+};
+interface AuthorizedStateAdapter {
+    getDocumentContent(nodeId: string): Promise<Uint8Array | null>;
+    setDocumentContent(nodeId: string, content: Uint8Array): Promise<void>;
+}
+interface GrantEventStore {
+    subscribe(listener: (event: GrantEvent) => void): () => void;
+}
+interface ContentKeyProvider {
+    getOrUnwrap(nodeId: string): Promise<Uint8Array>;
+}
+interface RecipientKeyResolver {
+    resolveBatch(dids: DID[]): Promise<Map<DID, Uint8Array>>;
+}
+interface AuthorizedSyncManagerOptions<TDoc extends YDocLike = YDocLike> {
+    authorDID: DID;
+    evaluator: PolicyEvaluator;
+    adapter: AuthorizedStateAdapter;
+    store: GrantEventStore;
+    keyProvider: ContentKeyProvider;
+    ydoc: YDocCodec<TDoc>;
+    publicKeyResolver?: RecipientKeyResolver;
+    onRotateContentKey?: (input: {
+        nodeId: string;
+        recipients: DID[];
+        wrappedKeys: Record<string, WrappedKey>;
+        contentKey: Uint8Array;
+    }) => Promise<void>;
+}
+declare class AuthorizedSyncManager<TDoc extends YDocLike = YDocLike> {
+    private readonly options;
+    private readonly rooms;
+    constructor(options: AuthorizedSyncManagerOptions<TDoc>);
+    acquire(nodeId: string, mode?: 'read' | 'write'): Promise<AuthorizedDoc<TDoc>>;
+    release(nodeId: string): void;
+    private joinRoom;
+    private wireRevocationEvents;
+    private handlePeerRevocation;
+}
+interface AuthorizedYjsSyncProviderOptions<TDoc extends YDocLike = YDocLike> {
+    nodeId: string;
+    doc: TDoc;
+    ydoc: Pick<YDocCodec<TDoc>, 'applyUpdate'>;
+    authGate: YjsAuthGate;
+    peerScorer?: YjsPeerScorer;
+    rateLimiter?: {
+        allow(peerId: DID): boolean;
+    };
+    verifyEnvelope?: (envelope: SignedYjsEnvelopeV2) => Promise<EnvelopeVerificationResult>;
+    onRejected?: (input: {
+        peerId: DID;
+        reason: 'rate-exceeded' | 'invalid-signature' | 'unauthorized';
+    }) => void;
+}
+declare class AuthorizedYjsSyncProvider<TDoc extends YDocLike = YDocLike> {
+    private readonly nodeId;
+    private readonly doc;
+    private readonly ydoc;
+    private readonly authGate;
+    private readonly peerScorer;
+    private readonly rateLimiter?;
+    private readonly verifyEnvelope;
+    private readonly onRejected?;
+    constructor(options: AuthorizedYjsSyncProviderOptions<TDoc>);
+    handleRemoteUpdate(envelope: SignedYjsEnvelopeV2): Promise<boolean>;
+}
+declare class AuthorizedYjsError extends Error {
+    readonly code: 'PERMISSION_DENIED';
+    readonly decision: AuthDecision;
+    constructor(code: 'PERMISSION_DENIED', decision: AuthDecision);
+}
+
+/**
+ * ClientID-to-DID Binding - Cryptographically bind Yjs clientIDs to DIDs
+ *
+ * Yjs assigns random integer clientIDs that have no cryptographic binding to
+ * the author's identity. This module provides signed attestations that bind
+ * a clientID to a DID for verifiable author attribution.
+ *
+ * V2 introduces multi-level signature support (Ed25519 and/or ML-DSA-65).
+ */
+
+/**
+ * A signed attestation binding a Yjs clientID to a DID (V1 format).
+ * @deprecated Use ClientIdAttestationV2 for new code
+ */
+interface ClientIdAttestationV1 {
+    /** The Yjs clientID being attested */
+    clientId: number;
+    /** The DID claiming this clientID */
+    did: string;
+    /** Ed25519 signature over BLAKE3(payload) */
+    signature: Uint8Array;
+    /** Session expiry (Unix timestamp seconds) */
+    expiresAt: number;
+    /** Room this attestation applies to */
+    room: string;
+}
+/**
+ * A signed attestation binding a Yjs clientID to a DID (V2 format with multi-level signatures).
+ */
+interface ClientIdAttestationV2 {
+    /** Wire format version */
+    v: 2;
+    /** The Yjs clientID being attested */
+    clientId: number;
+    /** The DID claiming this clientID */
+    did: DID;
+    /** When this binding was created (ms since epoch) */
+    timestamp: number;
+    /** Session expiry (Unix timestamp ms) */
+    expiresAt?: number;
+    /** Room this attestation applies to */
+    room: string;
+    /** Multi-level signature */
+    signature: UnifiedSignature;
+}
+/**
+ * Wire format for ClientIdAttestationV2.
+ */
+interface ClientIdAttestationWire {
+    v: 2;
+    c: number;
+    d: string;
+    t: number;
+    e?: number;
+    r: string;
+    s: SignatureWire;
+}
+/**
+ * Union type for all attestation versions.
+ */
+type ClientIdAttestation = ClientIdAttestationV1 | ClientIdAttestationV2;
+/**
+ * Result of attestation verification (V1 format).
+ */
+interface AttestationVerifyResult {
+    valid: boolean;
+    reason?: 'expired' | 'invalid_signature' | 'did_resolution_failed';
+}
+/**
+ * Result of attestation verification (V2 format with details).
+ */
+interface AttestationVerificationResult {
+    valid: boolean;
+    expired: boolean;
+    level: SecurityLevel;
+    errors: string[];
+}
+/**
+ * Options for creating an attestation.
+ */
+interface CreateAttestationOptions {
+    /** Expiration time in ms (optional) */
+    expiresInMs?: number;
+    /** Security level (default: 0 for Ed25519-only) */
+    level?: SecurityLevel;
+}
+/**
+ * Options for verifying an attestation.
+ */
+interface VerifyAttestationOptions {
+    /** PQ key registry for Level 1/2 verification */
+    registry?: PQKeyRegistry;
+    /** Minimum security level required */
+    minLevel?: SecurityLevel;
+}
+/**
+ * Check if an attestation is V2 format.
+ */
+declare function isV2Attestation(attestation: ClientIdAttestation): attestation is ClientIdAttestationV2;
+/**
+ * Check if an attestation is V1 format.
+ */
+declare function isV1Attestation(attestation: ClientIdAttestation): attestation is ClientIdAttestationV1;
+/**
+ * Create a signed clientID attestation (V1 format).
+ *
+ * @deprecated Use createClientIdAttestationV2() for new code
+ */
+declare function createClientIdAttestationV1(clientId: number, did: string, privateKey: Uint8Array, room: string, ttlSeconds?: number): ClientIdAttestationV1;
+/**
+ * Verify a V1 clientID attestation.
+ *
+ * @deprecated Use verifyClientIdAttestationV2() for V2 attestations
+ */
+declare function verifyClientIdAttestationV1(attestation: ClientIdAttestationV1): AttestationVerifyResult;
+/**
+ * Create a signed clientID attestation (V2 format with multi-level signatures).
+ *
+ * @param clientId - The Yjs clientID to attest
+ * @param room - The room this attestation applies to
+ * @param keyBundle - Key bundle for signing
+ * @param options - Creation options
+ * @returns Signed attestation
+ *
+ * @example
+ * ```typescript
+ * const attestation = createClientIdAttestationV2(doc.clientID, 'xnet-doc-abc', keyBundle)
+ * ws.send({ type: 'clientid-bind', room, attestation: serializeAttestation(attestation) })
+ * ```
+ */
+declare function createClientIdAttestationV2(clientId: number, room: string, keyBundle: HybridKeyBundle, options?: CreateAttestationOptions): ClientIdAttestationV2;
+/**
+ * Verify a V2 clientID attestation with multi-level signature support.
+ *
+ * @param attestation - The attestation to verify
+ * @param options - Verification options
+ * @returns Verification result with detailed errors
+ */
+declare function verifyClientIdAttestationV2(attestation: ClientIdAttestationV2, options?: VerifyAttestationOptions): Promise<AttestationVerificationResult>;
+/**
+ * Serialize V2 attestation to wire format.
+ */
+declare function serializeClientIdAttestation(attestation: ClientIdAttestationV2): ClientIdAttestationWire;
+/**
+ * Deserialize V2 attestation from wire format.
+ */
+declare function deserializeClientIdAttestation(wire: ClientIdAttestationWire): ClientIdAttestationV2;
+/**
+ * Create a signed clientID attestation.
+ *
+ * @overload V1 signature (legacy)
+ */
+declare function createClientIdAttestation(clientId: number, did: string, privateKey: Uint8Array, room: string, ttlSeconds?: number): ClientIdAttestationV1;
+/**
+ * @overload V2 signature (multi-level)
+ */
+declare function createClientIdAttestation(clientId: number, room: string, keyBundle: HybridKeyBundle, options?: CreateAttestationOptions): ClientIdAttestationV2;
+/**
+ * Verify a clientID attestation (auto-detects version).
+ */
+declare function verifyClientIdAttestation(attestation: ClientIdAttestationV1): AttestationVerifyResult;
+declare function verifyClientIdAttestation(attestation: ClientIdAttestationV2, options?: VerifyAttestationOptions): Promise<AttestationVerificationResult>;
+/**
+ * Interface for a per-room clientID map.
+ */
+interface ClientIdMap {
+    /** Look up DID by clientId */
+    getOwner(clientId: number): string | undefined;
+    /** Look up clientId by DID */
+    getClientId(did: string): number | undefined;
+    /** Register a verified attestation */
+    register(attestation: ClientIdAttestation): void;
+    /** Remove expired bindings */
+    cleanup(): void;
+    /** Get all active bindings */
+    getAll(): Array<{
+        clientId: number;
+        did: string;
+        expiresAt: number;
+    }>;
+    /** Check if a clientID is attested */
+    has(clientId: number): boolean;
+    /** Get the number of active bindings */
+    size(): number;
+}
+/**
+ * Implementation of ClientIdMap for tracking clientID->DID bindings.
+ *
+ * @example
+ * ```typescript
+ * const map = new ClientIdMapImpl()
+ *
+ * // On receiving attestation:
+ * const result = verifyClientIdAttestation(attestation)
+ * if (result.valid) {
+ *   map.register(attestation)
+ * }
+ *
+ * // On receiving update:
+ * const owner = map.getOwner(envelope.clientId)
+ * if (owner && owner !== envelope.authorDID) {
+ *   // ClientID claimed by different DID - reject!
+ * }
+ * ```
+ */
+declare class ClientIdMapImpl implements ClientIdMap {
+    private byClientId;
+    private byDid;
+    getOwner(clientId: number): string | undefined;
+    getClientId(did: string): number | undefined;
+    register(attestation: ClientIdAttestation): void;
+    cleanup(): void;
+    getAll(): Array<{
+        clientId: number;
+        did: string;
+        expiresAt: number;
+    }>;
+    has(clientId: number): boolean;
+    size(): number;
+    /**
+     * Get the count of non-expired entries without mutating state.
+     * This is useful for accurate counts but slower than size().
+     */
+    activeCount(): number;
+    /**
+     * Clear all bindings.
+     */
+    clear(): void;
+}
+/**
+ * Check if an update's clientID matches the expected owner.
+ *
+ * @param clientId - The clientID from the update
+ * @param authorDID - The DID from the envelope
+ * @param map - The clientID map
+ * @returns true if valid (matches or no binding exists), false if mismatch
+ */
+declare function validateClientIdOwnership(clientId: number, authorDID: string, map: ClientIdMap): boolean;
+
+/**
+ * YjsChange - Wrap Yjs updates in the Change<T> envelope for hash chain integration
+ *
+ * This provides the strongest security tier: Yjs updates become entries in the
+ * same per-node hash chain as NodeChanges. This gives rich text the same
+ * guarantees as structured data — signed, hashed, chain-linked, with a full
+ * audit trail of who typed what and when.
+ *
+ * See: docs/plans/plan03_4_1YjsSecurity/08-hash-chain-integration.md
+ */
+
+/**
+ * Change type identifier for Yjs changes.
+ */
+declare const YJS_CHANGE_TYPE = "yjs-update";
+/**
+ * Payload for a YjsChange - contains the batched Yjs update.
+ */
+interface YjsUpdatePayload {
+    /** The node this update belongs to */
+    nodeId: string;
+    /** Batched Yjs update bytes (one or more merged updates) */
+    update: Uint8Array;
+    /** Yjs clientID for this author (verified via Step 07) */
+    clientId: number;
+    /** Number of individual Yjs updates batched into this change */
+    updateCount: number;
+}
+/**
+ * A Yjs update wrapped in the Change<T> envelope.
+ * Gets: id, hash, parentHash, signature, authorDID, lamport, wallTime
+ */
+type YjsChange = Change<YjsUpdatePayload>;
+/**
+ * Unsigned version of YjsChange (before signing).
+ */
+type UnsignedYjsChange = UnsignedChange<YjsUpdatePayload>;
+/**
+ * Options for creating a YjsChange.
+ */
+interface CreateYjsChangeOptions {
+    /** The node this update belongs to */
+    nodeId: string;
+    /** Batched Yjs update bytes */
+    update: Uint8Array;
+    /** Yjs clientID for this author */
+    clientId: number;
+    /** Number of individual updates in this batch */
+    updateCount: number;
+    /** Author's DID */
+    authorDID: string;
+    /** Author's Ed25519 private key for signing */
+    privateKey: Uint8Array;
+    /** Hash of the previous change in the chain (null for first) */
+    parentHash: ContentId | null;
+    /** Lamport timestamp for ordering */
+    lamport: LamportTimestamp;
+    /** Optional wall time (defaults to Date.now()) */
+    wallTime?: number;
+}
+/**
+ * Create an unsigned YjsChange.
+ *
+ * @param options - Change options
+ * @returns Unsigned change ready for signing
+ */
+declare function createUnsignedYjsChange(options: Omit<CreateYjsChangeOptions, 'privateKey'>): UnsignedYjsChange;
+/**
+ * Create a signed YjsChange.
+ *
+ * @param options - Change options including private key
+ * @returns Signed YjsChange with hash and signature
+ *
+ * @example
+ * ```typescript
+ * const change = createYjsChange({
+ *   nodeId: 'page-123',
+ *   update: Y.encodeStateAsUpdate(doc),
+ *   clientId: doc.clientID,
+ *   updateCount: 5,
+ *   authorDID: identity.did,
+ *   privateKey: identity.privateKey,
+ *   parentHash: lastChangeHash,
+ *   lamport: { time: 42, did: identity.did }
+ * })
+ * ```
+ */
+declare function createYjsChange(options: CreateYjsChangeOptions): YjsChange;
+/**
+ * Type guard to check if a change is a YjsChange.
+ *
+ * @param change - Any change object
+ * @returns true if the change is a YjsChange
+ */
+declare function isYjsChange(change: Change<unknown>): change is YjsChange;
+/**
+ * Type guard to check if a change is a NodeChange (not a YjsChange).
+ * NodeChanges have 'properties' and 'schemaId' in their payload.
+ */
+declare function isNodeChange(change: Change<unknown>): boolean;
+/**
+ * Extract the nodeId from any change (works for both NodeChange and YjsChange).
+ */
+declare function getChangeNodeId(change: Change<unknown>): string | undefined;
+
+/**
+ * YjsBatcher - Batch Yjs updates for efficient hash chain integration
+ *
+ * Individual keystrokes generate ~5 updates/sec. Wrapping each in a full
+ * Change<T> is wasteful. Instead, batch updates over a configurable window.
+ *
+ * With 2-second batching:
+ * - Updates/sec: 5 → 0.5
+ * - Overhead/sec: 1KB → 100B
+ * - Signature ops/sec: 5 → 0.5
+ *
+ * See: docs/plans/plan03_4_1YjsSecurity/08-hash-chain-integration.md
+ */
+/**
+ * Configuration for the YjsBatcher.
+ */
+interface YjsBatcherConfig {
+    /** Batch window in milliseconds (default: 2000) */
+    batchWindowMs: number;
+    /** Max updates per batch before flush (default: 50) */
+    maxBatchSize: number;
+    /** Flush on paragraph break / Enter key (default: true) */
+    flushOnParagraph: boolean;
+}
+/**
+ * Default configuration for YjsBatcher.
+ */
+declare const DEFAULT_BATCHER_CONFIG: YjsBatcherConfig;
+/**
+ * Callback invoked when a batch is flushed.
+ *
+ * @param mergedUpdate - The merged Yjs update bytes (from Y.mergeUpdates)
+ * @param updateCount - Number of individual updates in this batch
+ */
+type BatchFlushCallback = (mergedUpdate: Uint8Array, updateCount: number) => void;
+/**
+ * Function that merges multiple Yjs updates into one.
+ * This is typically Y.mergeUpdates from the 'yjs' package.
+ */
+type MergeUpdatesFn = (updates: Uint8Array[]) => Uint8Array;
+/**
+ * YjsBatcher collects Yjs updates and flushes them in batches.
+ *
+ * This reduces the overhead of wrapping each update in a signed Change<T>
+ * while still maintaining a full audit trail.
+ *
+ * @example
+ * ```typescript
+ * import * as Y from 'yjs'
+ *
+ * const batcher = new YjsBatcher(
+ *   (mergedUpdate, count) => {
+ *     // Create a YjsChange from the merged update
+ *     const change = createYjsChange({
+ *       nodeId,
+ *       update: mergedUpdate,
+ *       updateCount: count,
+ *       ...
+ *     })
+ *     // Append to hash chain
+ *     store.appendChange(change)
+ *   },
+ *   { batchWindowMs: 2000 },
+ *   Y.mergeUpdates // Pass the merge function
+ * )
+ *
+ * // On each local Yjs update:
+ * doc.on('update', (update, origin) => {
+ *   if (origin !== 'remote') {
+ *     batcher.add(update)
+ *   }
+ * })
+ *
+ * // On component unmount:
+ * batcher.destroy()
+ * ```
+ */
+declare class YjsBatcher {
+    private pendingUpdates;
+    private flushTimer;
+    private config;
+    private onFlush;
+    private mergeUpdates;
+    private destroyed;
+    /**
+     * Create a new YjsBatcher.
+     *
+     * @param onFlush - Callback invoked when a batch is flushed
+     * @param config - Optional configuration overrides
+     * @param mergeUpdates - Function to merge updates (required - use Y.mergeUpdates from yjs)
+     */
+    constructor(onFlush: BatchFlushCallback, config?: Partial<YjsBatcherConfig>, mergeUpdates?: MergeUpdatesFn);
+    /**
+     * Add an update to the current batch.
+     *
+     * @param update - The Yjs update bytes
+     * @param isParagraphBreak - Whether this update is a paragraph break (Enter key)
+     */
+    add(update: Uint8Array, isParagraphBreak?: boolean): void;
+    /**
+     * Force flush the current batch.
+     * Safe to call even if there are no pending updates.
+     */
+    flush(): void;
+    /**
+     * Check if there are pending updates.
+     */
+    hasPending(): boolean;
+    /**
+     * Get the number of pending updates.
+     */
+    pendingCount(): number;
+    /**
+     * Destroy the batcher. Flushes any remaining updates.
+     * After destroy, add() calls will be ignored.
+     */
+    destroy(): void;
+    /**
+     * Check if the batcher has been destroyed.
+     */
+    isDestroyed(): boolean;
+    /**
+     * Reset or start the flush timer.
+     */
+    private resetTimer;
+}
+
+/**
+ * Serializer types for version-specific change encoding.
+ *
+ * Each protocol version may have a different wire format for changes.
+ * Serializers handle encoding and decoding for their specific version.
+ */
+
+/**
+ * Serialized change format.
+ * Can be either binary (Uint8Array) or JSON-compatible object.
+ */
+type SerializedChange = Uint8Array | Record<string, unknown>;
+/**
+ * Result of deserializing a change.
+ */
+interface DeserializeResult<T = unknown> {
+    success: true;
+    change: Change<T>;
+}
+interface DeserializeError {
+    success: false;
+    error: string;
+    /** Raw data that failed to deserialize */
+    rawData?: unknown;
+}
+type DeserializeOutcome<T = unknown> = DeserializeResult<T> | DeserializeError;
+/**
+ * Interface for version-specific change serializers.
+ *
+ * Each serializer handles:
+ * - Encoding changes for network transmission
+ * - Decoding changes from network
+ * - Validating change format
+ */
+interface ChangeSerializer {
+    /**
+     * Protocol version this serializer handles.
+     */
+    readonly version: number;
+    /**
+     * Human-readable name for this serializer.
+     */
+    readonly name: string;
+    /**
+     * Serialize a change for transmission.
+     *
+     * @param change - The change to serialize
+     * @returns Serialized data (binary or JSON object)
+     */
+    serialize<T>(change: Change<T>): SerializedChange;
+    /**
+     * Deserialize a change from received data.
+     *
+     * @param data - Raw data (binary or JSON object)
+     * @returns Deserialized change or error
+     */
+    deserialize<T = unknown>(data: SerializedChange): DeserializeOutcome<T>;
+    /**
+     * Check if this serializer can handle the given data.
+     * Used for format detection.
+     *
+     * @param data - Raw data to check
+     * @returns true if this serializer can deserialize the data
+     */
+    canDeserialize(data: unknown): boolean;
+}
+/**
+ * Options for serialization.
+ */
+interface SerializeOptions {
+    /**
+     * Whether to use binary encoding (more compact) or JSON (more readable).
+     * Default: true for production, false for debugging.
+     */
+    binary?: boolean;
+    /**
+     * Whether to include optional fields with default values.
+     * Default: false (omit default values).
+     */
+    includeDefaults?: boolean;
+}
+/**
+ * Registry for managing multiple serializer versions.
+ */
+interface SerializerRegistry {
+    /**
+     * Get serializer for a specific version.
+     */
+    get(version: number): ChangeSerializer | undefined;
+    /**
+     * Get the default (latest) serializer.
+     */
+    getDefault(): ChangeSerializer;
+    /**
+     * Register a serializer.
+     */
+    register(serializer: ChangeSerializer): void;
+    /**
+     * Get all registered versions.
+     */
+    getVersions(): number[];
+    /**
+     * Auto-detect serializer for incoming data.
+     */
+    detect(data: unknown): ChangeSerializer | undefined;
+}
+
+/**
+ * V1 Serializer - Original change format.
+ *
+ * Protocol v1 uses JSON encoding with the following characteristics:
+ * - protocolVersion field may be missing (legacy) or 1
+ * - Signature is base64 encoded
+ * - All fields use full names (no abbreviations)
+ *
+ * Wire format (JSON):
+ * {
+ *   protocolVersion?: 1,
+ *   id: string,
+ *   type: string,
+ *   payload: T,
+ *   hash: string,
+ *   parentHash: string | null,
+ *   authorDID: string,
+ *   signature: string (base64),
+ *   wallTime: number,
+ *   lamport: { time: number, did: string },
+ *   batchId?: string,
+ *   batchIndex?: number,
+ *   batchSize?: number
+ * }
+ */
+
+/**
+ * V1 Serializer implementation.
+ */
+declare class V1Serializer implements ChangeSerializer {
+    readonly version = 1;
+    readonly name = "V1 JSON Serializer";
+    serialize<T>(change: Change<T>): SerializedChange;
+    deserialize<T = unknown>(data: SerializedChange): DeserializeOutcome<T>;
+    canDeserialize(data: unknown): boolean;
+}
+/**
+ * Default V1 serializer instance.
+ */
+declare const v1Serializer: V1Serializer;
+
+/**
+ * V2 Serializer - Enhanced change format with schema versioning.
+ *
+ * Protocol v2 extends v1 with:
+ * - Required protocolVersion field (always 2)
+ * - Schema version in payload (_sv field)
+ * - Abbreviated field names for compact transmission
+ * - Support for binary payload compression (future)
+ *
+ * Wire format (JSON, abbreviated):
+ * {
+ *   v: 2,                        // protocolVersion
+ *   i: string,                   // id
+ *   t: string,                   // type
+ *   p: { ..., _sv?: string },    // payload with optional schema version
+ *   h: string,                   // hash
+ *   ph: string | null,           // parentHash
+ *   a: string,                   // authorDID
+ *   s: string,                   // signature (base64)
+ *   w: number,                   // wallTime
+ *   l: { t: number, a: string }, // lamport { time, author }
+ *   bi?: string,                 // batchId
+ *   bx?: number,                 // batchIndex
+ *   bs?: number                  // batchSize
+ * }
+ */
+
+/**
+ * V2 Serializer implementation.
+ * Uses abbreviated field names for more compact wire format.
+ */
+declare class V2Serializer implements ChangeSerializer {
+    readonly version = 2;
+    readonly name = "V2 Compact Serializer";
+    serialize<T>(change: Change<T>): SerializedChange;
+    deserialize<T = unknown>(data: SerializedChange): DeserializeOutcome<T>;
+    canDeserialize(data: unknown): boolean;
+    /**
+     * Add schema version to a payload.
+     * Used when serializing node changes with schema versioning.
+     */
+    static addSchemaVersion<T extends Record<string, unknown>>(payload: T, schemaVersion: string): T & {
+        _sv: string;
+    };
+    /**
+     * Extract schema version from a payload.
+     */
+    static getSchemaVersion(payload: unknown): string | undefined;
+}
+/**
+ * Default V2 serializer instance.
+ */
+declare const v2Serializer: V2Serializer;
+
+/**
+ * Serializer registry and exports.
+ *
+ * This module provides:
+ * - Version-specific serializers (V1, V2, V3)
+ * - A registry for managing serializers
+ * - Auto-detection for incoming data
+ * - Helper function for selecting serializer by version
+ *
+ * V3 is the default for new changes (multi-level signature support).
+ */
+
+/**
+ * Default serializer registry implementation.
+ */
+declare class DefaultSerializerRegistry implements SerializerRegistry {
+    private serializers;
+    private defaultVersion;
+    constructor(defaultVersion?: number);
+    get(version: number): ChangeSerializer | undefined;
+    getDefault(): ChangeSerializer;
+    register(serializer: ChangeSerializer): void;
+    getVersions(): number[];
+    detect(data: unknown): ChangeSerializer | undefined;
+}
+/**
+ * Default serializer registry instance.
+ */
+declare const serializerRegistry: DefaultSerializerRegistry;
+/**
+ * Get a serializer for a specific protocol version.
+ *
+ * @param version - Protocol version number
+ * @returns Serializer for that version, or undefined if not found
+ */
+declare function getSerializer(version: number): ChangeSerializer | undefined;
+/**
+ * Get the default serializer (for current protocol version).
+ */
+declare function getDefaultSerializer(): ChangeSerializer;
+/**
+ * Detect and deserialize a change from raw data.
+ * Automatically detects the format and uses appropriate serializer.
+ *
+ * @param data - Raw serialized data
+ * @returns Deserialized change or error
+ */
+declare function autoDeserialize<T = unknown>(data: SerializedChange): DeserializeOutcome<T>;
+/**
+ * Serialize a change using the appropriate serializer for its protocol version.
+ *
+ * @param change - Change to serialize
+ * @returns Serialized data
+ */
+declare function autoSerialize<T>(change: Change<T>): SerializedChange;
+/**
+ * Create a serializer registry with custom serializers.
+ *
+ * @param defaultVersion - Default protocol version to use
+ * @param serializers - Optional additional serializers to register
+ * @returns New serializer registry
+ */
+declare function createSerializerRegistry(defaultVersion?: number, serializers?: ChangeSerializer[]): SerializerRegistry;
+
+/**
+ * Change Handler Registry - Version-specific handlers for processing changes.
+ *
+ * This registry allows registering handlers by change type and version range,
+ * enabling backward-compatible processing of older change formats.
+ *
+ * @example
+ * ```typescript
+ * const registry = new ChangeHandlerRegistry()
+ *
+ * registry.register({
+ *   type: 'yjs-update',
+ *   minVersion: 1,
+ *   maxVersion: Infinity,
+ *   canHandle: (change) => change.type === 'yjs-update',
+ *   process: async (change, ctx) => { ... },
+ *   validate: (change) => ({ valid: true, errors: [] })
+ * })
+ *
+ * await registry.process(incomingChange, context)
+ * ```
+ */
+
+/**
+ * Result of validating a change.
+ */
+interface ValidationResult {
+    /** Whether the change is valid */
+    valid: boolean;
+    /** Error messages if validation failed */
+    errors: string[];
+}
+/**
+ * Context provided to change handlers during processing.
+ */
+interface HandlerContext {
+    /** Store an unknown change for later processing */
+    storeUnknown: (change: Change<unknown>) => Promise<void>;
+    /** Emit an event */
+    emit: (event: string, data: Record<string, unknown>) => void;
+    /** The author DID of the current user */
+    authorDID?: string;
+}
+/**
+ * Handler for processing a specific type and version range of changes.
+ */
+interface ChangeHandler<T = unknown> {
+    /** Change type this handler processes (e.g., 'yjs-update', 'record-create') */
+    type: string;
+    /** Minimum protocol version this handler supports (inclusive) */
+    minVersion: number;
+    /** Maximum protocol version this handler supports (inclusive, use Infinity for latest) */
+    maxVersion: number;
+    /**
+     * Check if this handler can process the given change.
+     * Called after type and version matching for additional checks.
+     */
+    canHandle(change: Change<unknown>): boolean;
+    /**
+     * Process the change and apply it to the store/state.
+     */
+    process(change: Change<T>, context: HandlerContext): Promise<void>;
+    /**
+     * Validate the change structure and content.
+     * Should check that all required fields are present and valid.
+     */
+    validate(change: Change<T>): ValidationResult;
+}
+/**
+ * Registry for version-specific change handlers.
+ *
+ * Handlers are matched by:
+ * 1. Change type (exact match)
+ * 2. Protocol version (within handler's min/max range)
+ * 3. Optional canHandle() for additional checks
+ *
+ * If no exact match is found, falls back to the newest handler that
+ * can process older versions (for backward compatibility).
+ */
+declare class ChangeHandlerRegistry {
+    private handlers;
+    private unknownTypeListeners;
+    private invalidChangeListeners;
+    /**
+     * Register a handler for a change type and version range.
+     */
+    register<T>(handler: ChangeHandler<T>): void;
+    /**
+     * Unregister all handlers for a type.
+     */
+    unregister(type: string): boolean;
+    /**
+     * Get the appropriate handler for a change.
+     * Returns null if no handler can process this change.
+     */
+    getHandler(change: Change<unknown>): ChangeHandler<unknown> | null;
+    /**
+     * Check if any handler can process this change.
+     */
+    canProcess(change: Change<unknown>): boolean;
+    /**
+     * Process a change using the appropriate handler.
+     */
+    process(change: Change<unknown>, context: HandlerContext): Promise<void>;
+    /**
+     * Get all registered handler types.
+     */
+    getTypes(): string[];
+    /**
+     * Get handlers for a specific type.
+     */
+    getHandlersForType(type: string): ChangeHandler<unknown>[];
+    /**
+     * Subscribe to unknown change type events.
+     */
+    onUnknownType(listener: (change: Change<unknown>) => void): () => void;
+    /**
+     * Subscribe to invalid change events.
+     */
+    onInvalidChange(listener: (change: Change<unknown>, errors: string[]) => void): () => void;
+    /**
+     * Clear all registered handlers.
+     */
+    clear(): void;
+    private notifyUnknownType;
+    private notifyInvalidChange;
+}
+/**
+ * Default global change handler registry instance.
+ */
+declare const changeHandlerRegistry: ChangeHandlerRegistry;
+/**
+ * Create a simple handler that accepts all versions.
+ */
+declare function createHandler<T>(type: string, process: (change: Change<T>, context: HandlerContext) => Promise<void>, validate?: (change: Change<T>) => ValidationResult): ChangeHandler<T>;
+/**
+ * Create a handler for a specific version range.
+ */
+declare function createVersionedHandler<T>(type: string, minVersion: number, maxVersion: number, process: (change: Change<T>, context: HandlerContext) => Promise<void>, validate?: (change: Change<T>) => ValidationResult): ChangeHandler<T>;
+/**
+ * Create a mock context for testing handlers.
+ */
+declare function createTestContext(overrides?: Partial<HandlerContext>): HandlerContext;
+/**
+ * A validation error with optional context.
+ */
+interface ValidationError {
+    /** Error code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Property path if applicable */
+    path?: string;
+}
+/**
+ * A validation warning (non-fatal issue).
+ */
+interface ValidationWarning {
+    /** Warning code */
+    code: string;
+    /** Human-readable message */
+    message: string;
+    /** Property path if applicable */
+    path?: string;
+}
+/**
+ * Events emitted during change processing.
+ */
+type HandlerEvent = {
+    type: 'unknownChangeType';
+    change: Change<unknown>;
+} | {
+    type: 'invalidChange';
+    change: Change<unknown>;
+    errors: string[];
+} | {
+    type: 'processed';
+    change: Change<unknown>;
+    duration: number;
+};
+/**
+ * Result of processing a change.
+ */
+interface ProcessResult {
+    /** Whether processing succeeded */
+    success: boolean;
+    /** Handler that processed the change (if any) */
+    handlerType?: string;
+    /** Processing duration in ms */
+    duration: number;
+    /** Errors if processing failed */
+    errors?: string[];
+}
+/**
+ * Statistics about the registry.
+ */
+interface RegistryStats {
+    /** Number of registered handler types */
+    typeCount: number;
+    /** Total number of handlers */
+    handlerCount: number;
+    /** Types with multiple version-specific handlers */
+    versionedTypes: string[];
+}
+
+/**
+ * Data Integrity Verification
+ *
+ * Utilities for verifying the integrity of change data, including:
+ * - Hash verification
+ * - Signature verification
+ * - Chain integrity checks
+ * - Detection of corruption and repair suggestions
+ *
+ * @example
+ * ```typescript
+ * const report = await verifyIntegrity(changes)
+ * if (report.issues.length > 0) {
+ *   console.log('Issues found:', report.issues)
+ *   if (report.repairable) {
+ *     console.log('All issues can be repaired')
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Types of integrity issues that can be detected.
+ */
+type IntegrityIssueType = 'hash-mismatch' | 'signature-invalid' | 'chain-broken' | 'missing-parent' | 'duplicate-id' | 'invalid-lamport' | 'future-timestamp';
+/**
+ * Possible repair actions for integrity issues.
+ */
+type RepairActionType = 'recompute-hash' | 'request-from-peers' | 'remove-duplicate' | 'mark-orphan' | 'none';
+/**
+ * A repair action that can be taken to fix an integrity issue.
+ */
+interface RepairAction {
+    type: RepairActionType;
+    description: string;
+    /** Whether this repair can be done automatically */
+    automatic: boolean;
+}
+/**
+ * An integrity issue found during verification.
+ */
+interface IntegrityIssue {
+    /** The change ID that has the issue */
+    changeId: string;
+    /** Type of issue */
+    type: IntegrityIssueType;
+    /** Human-readable description */
+    details: string;
+    /** Severity: error = data may be corrupted, warning = anomaly detected */
+    severity: 'error' | 'warning';
+    /** Suggested repair action (if any) */
+    repairAction?: RepairAction;
+}
+/**
+ * Result of an integrity verification.
+ */
+interface IntegrityReport {
+    /** Number of changes checked */
+    checked: number;
+    /** Number of changes that passed all checks */
+    valid: number;
+    /** List of issues found */
+    issues: IntegrityIssue[];
+    /** Whether all issues can be repaired */
+    repairable: boolean;
+    /** Summary statistics */
+    summary: {
+        errors: number;
+        warnings: number;
+        byType: Record<IntegrityIssueType, number>;
+    };
+    /** Time taken for verification (ms) */
+    durationMs: number;
+}
+/**
+ * Options for integrity verification.
+ */
+interface VerifyOptions {
+    /** Skip signature verification (faster but less thorough) */
+    skipSignatures?: boolean;
+    /** Skip hash verification */
+    skipHashes?: boolean;
+    /** Skip chain verification */
+    skipChain?: boolean;
+    /** Maximum future timestamp allowed (ms from now) */
+    maxFutureTimestamp?: number;
+    /** Progress callback */
+    onProgress?: (checked: number, total: number) => void;
+}
+/**
+ * Verify the integrity of a set of changes.
+ *
+ * Checks performed:
+ * 1. Hash verification - computed hash matches stored hash
+ * 2. Signature verification - Ed25519 signature is valid
+ * 3. Chain integrity - parent hashes exist and form valid chains
+ * 4. Duplicate detection - no duplicate change IDs
+ * 5. Timestamp validation - no future timestamps
+ */
+declare function verifyIntegrity(changes: Change<unknown>[], options?: VerifyOptions): Promise<IntegrityReport>;
+/**
+ * Quick integrity check - only verifies hashes, not signatures.
+ * Much faster but less thorough.
+ */
+declare function quickIntegrityCheck(changes: Change<unknown>[]): Promise<IntegrityReport>;
+/**
+ * Verify a single change.
+ */
+declare function verifySingleChange(change: Change<unknown>, options?: VerifyOptions): Promise<{
+    valid: boolean;
+    issues: IntegrityIssue[];
+}>;
+/**
+ * Find orphaned changes (changes whose parents are missing).
+ */
+declare function findOrphans(changes: Change<unknown>[]): Change<unknown>[];
+/**
+ * Find root changes (changes with no parent).
+ */
+declare function findRoots(changes: Change<unknown>[]): Change<unknown>[];
+/**
+ * Find head changes (changes that are not parents of any other change).
+ */
+declare function findHeads(changes: Change<unknown>[]): Change<unknown>[];
+/**
+ * Get the chain depth (longest path from any root to any head).
+ */
+declare function getChainDepth(changes: Change<unknown>[]): number;
+/**
+ * Attempt to repair issues that can be fixed automatically.
+ * Returns the repaired changes and any issues that couldn't be fixed.
+ */
+declare function attemptRepair(changes: Change<unknown>[], issues: IntegrityIssue[]): Promise<{
+    repaired: Change<unknown>[];
+    remainingIssues: IntegrityIssue[];
+    repairCount: number;
+}>;
+/**
+ * Generate a human-readable integrity report.
+ */
+declare function formatIntegrityReport(report: IntegrityReport): string;
+
+/**
+ * Deprecation System
+ *
+ * Tracks deprecated protocols, schemas, and features to help developers
+ * migrate away from outdated functionality before it's removed.
+ *
+ * @example
+ * ```typescript
+ * // Check for deprecation warnings
+ * const warnings = checkDeprecations({
+ *   protocolVersion: 0,
+ *   schemas: ['xnet://xnet.fyi/Task@1.0.0'],
+ *   features: ['legacy-auth']
+ * })
+ *
+ * for (const warning of warnings) {
+ *   console.warn(warning.message)
+ * }
+ * ```
+ */
+
+/**
+ * Schema IRI type (mirrors @xnetjs/data to avoid circular dependency).
+ * Format: xnet://namespace/Name@version
+ */
+type SchemaIRI = `xnet://${string}/${string}` | `xnet://${string}/${string}@${string}`;
+/**
+ * Type of deprecated item.
+ */
+type DeprecationType = 'protocol' | 'schema' | 'feature' | 'api';
+/**
+ * A deprecation notice for a protocol, schema, feature, or API.
+ */
+interface DeprecationNotice {
+    /** Type of deprecated item */
+    type: DeprecationType;
+    /** Identifier of the deprecated item */
+    subject: string;
+    /** Human-readable description */
+    description: string;
+    /** Version where this was deprecated */
+    deprecatedIn: string;
+    /** Version where this will be/was removed (if known) */
+    removedIn?: string;
+    /** What to use instead */
+    alternative?: string;
+    /** URL to migration documentation */
+    migrationGuide?: string;
+    /** Date when deprecated */
+    deprecatedDate?: string;
+    /** Date when removed/sunset (if known) */
+    sunsetDate?: string;
+}
+/**
+ * Context for checking deprecations.
+ */
+interface DeprecationContext {
+    /** Current protocol version in use */
+    protocolVersion?: number;
+    /** Schema IRIs currently in use */
+    schemas?: (SchemaIRI | string)[];
+    /** Features currently enabled */
+    features?: (FeatureFlag | string)[];
+    /** Package version */
+    packageVersion?: string;
+}
+/**
+ * A deprecation warning generated from context.
+ */
+interface DeprecationWarning {
+    /** The deprecation notice that triggered this warning */
+    notice: DeprecationNotice;
+    /** Human-readable warning message */
+    message: string;
+    /** Recommended action to take */
+    action: string;
+    /** Severity: 'warning' for deprecated, 'error' for removed */
+    severity: 'warning' | 'error';
+    /** Days until removal (if sunsetDate is known) */
+    daysUntilRemoval?: number;
+}
+/**
+ * Callback for deprecation events.
+ */
+type DeprecationCallback = (warning: DeprecationWarning) => void;
+/**
+ * Registry of all known deprecations.
+ *
+ * Add new entries here when deprecating functionality.
+ * This serves as both documentation and runtime checking.
+ */
+declare const DEPRECATIONS: DeprecationNotice[];
+/**
+ * Check for deprecation warnings based on current context.
+ *
+ * @param context - The current usage context to check
+ * @returns Array of deprecation warnings
+ *
+ * @example
+ * ```typescript
+ * const warnings = checkDeprecations({
+ *   protocolVersion: 0,
+ *   schemas: ['xnet://xnet.fyi/Task@1.0.0']
+ * })
+ *
+ * if (warnings.length > 0) {
+ *   console.warn('Deprecation warnings:', warnings)
+ * }
+ * ```
+ */
+declare function checkDeprecations(context: DeprecationContext): DeprecationWarning[];
+/**
+ * Default deprecation policy.
+ *
+ * - Minimum deprecation period: 6 months
+ * - Breaking changes require major version bump
+ * - Warnings logged to console in development
+ * - Errors thrown in strict mode for removed functionality
+ */
+declare const DEPRECATION_POLICY: {
+    /** Minimum time between deprecation and removal */
+    minimumDeprecationPeriodDays: number;
+    /** Whether to log warnings to console */
+    logWarnings: boolean;
+    /** Whether to throw errors for removed functionality */
+    strictMode: boolean;
+    /** Console logger for warnings */
+    logger: (message: string) => void;
+};
+/**
+ * Configure the deprecation policy.
+ */
+declare function configureDeprecationPolicy(options: Partial<typeof DEPRECATION_POLICY>): void;
+/**
+ * Log a deprecation warning (once per session).
+ *
+ * @param warning - The deprecation warning to log
+ */
+declare function logDeprecation(warning: DeprecationWarning): void;
+/**
+ * Check and log deprecation warnings for a context.
+ *
+ * @param context - The current usage context
+ * @returns Array of warnings (also logs them)
+ */
+declare function checkAndLogDeprecations(context: DeprecationContext): DeprecationWarning[];
+/**
+ * Clear the logged deprecations set (for testing).
+ */
+declare function clearLoggedDeprecations(): void;
+/**
+ * Get all deprecation notices of a specific type.
+ */
+declare function getDeprecationsByType(type: DeprecationType): DeprecationNotice[];
+/**
+ * Get a specific deprecation notice by subject.
+ */
+declare function getDeprecation(subject: string): DeprecationNotice | undefined;
+/**
+ * Check if a specific item is deprecated.
+ */
+declare function isDeprecated(subject: string): boolean;
+/**
+ * Check if a specific item has been removed.
+ */
+declare function isRemoved(subject: string): boolean;
+/**
+ * Register a new deprecation notice.
+ * Useful for applications to add their own deprecations.
+ */
+declare function registerDeprecation(notice: DeprecationNotice): void;
+/**
+ * Error thrown when using removed functionality in strict mode.
+ */
+declare class DeprecationError extends Error {
+    readonly warning: DeprecationWarning;
+    constructor(warning: DeprecationWarning);
+}
+/**
+ * Format deprecation warnings as a human-readable report.
+ */
+declare function formatDeprecationReport(warnings: DeprecationWarning[]): string;
+
+/**
+ * Periodic Integrity Monitor
+ *
+ * A background service that periodically checks data integrity and
+ * emits events when issues are detected.
+ *
+ * @example
+ * ```typescript
+ * const monitor = createIntegrityMonitor({
+ *   getChanges: () => storage.getAllChanges(),
+ *   intervalMs: 60000, // Check every minute
+ *   onIssues: (report) => {
+ *     console.warn('Integrity issues:', report.issues)
+ *   }
+ * })
+ *
+ * monitor.start()
+ * // ... later
+ * monitor.stop()
+ * ```
+ */
+
+/**
+ * Configuration for the integrity monitor.
+ */
+interface IntegrityMonitorConfig {
+    /** Function to retrieve all changes for verification */
+    getChanges: () => Promise<Change<unknown>[]> | Change<unknown>[];
+    /** Interval between checks in milliseconds (default: 5 minutes) */
+    intervalMs?: number;
+    /** Use quick check (skip signatures) for periodic checks */
+    quickCheck?: boolean;
+    /** Additional verification options */
+    verifyOptions?: VerifyOptions;
+    /** Called when issues are detected */
+    onIssues?: (report: IntegrityReport) => void;
+    /** Called after each check (including clean ones) */
+    onCheck?: (report: IntegrityReport) => void;
+    /** Called when an error occurs during check */
+    onError?: (error: Error) => void;
+    /** Whether to run a check immediately on start */
+    checkOnStart?: boolean;
+    /** Minimum number of changes before running checks */
+    minChangesForCheck?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Statistics from the integrity monitor.
+ */
+interface IntegrityMonitorStats {
+    /** Number of checks performed */
+    checksPerformed: number;
+    /** Number of issues found across all checks */
+    totalIssuesFound: number;
+    /** Time of last check */
+    lastCheckAt: Date | null;
+    /** Duration of last check in ms */
+    lastCheckDurationMs: number;
+    /** Result of last check */
+    lastReport: IntegrityReport | null;
+    /** Whether the monitor is currently running */
+    isRunning: boolean;
+    /** Whether a check is currently in progress */
+    isChecking: boolean;
+}
+/**
+ * The integrity monitor instance.
+ */
+interface IntegrityMonitor {
+    /** Start periodic monitoring */
+    start(): void;
+    /** Stop periodic monitoring */
+    stop(): void;
+    /** Run a check immediately (independent of the periodic schedule) */
+    checkNow(): Promise<IntegrityReport>;
+    /** Get current statistics */
+    getStats(): IntegrityMonitorStats;
+    /** Check if the monitor is running */
+    isRunning(): boolean;
+    /** Update configuration */
+    configure(config: Partial<IntegrityMonitorConfig>): void;
+}
+/**
+ * Create an integrity monitor instance.
+ */
+declare function createIntegrityMonitor(config: IntegrityMonitorConfig): IntegrityMonitor;
+/**
+ * Options for creating a React-friendly integrity monitor.
+ */
+interface ReactIntegrityMonitorOptions extends IntegrityMonitorConfig {
+    /** Emit state changes for React to observe */
+    onStateChange?: (stats: IntegrityMonitorStats) => void;
+}
+/**
+ * Create an integrity monitor with React-friendly state updates.
+ * This wraps the monitor to emit state changes that can be observed
+ * by React hooks.
+ */
+declare function createReactIntegrityMonitor(options: ReactIntegrityMonitorOptions): IntegrityMonitor;
+
+/**
+ * Security policy for operation-based security level selection.
+ *
+ * Different operations may warrant different security levels:
+ * - High-frequency, low-value ops (cursors) → Level 0 (fast)
+ * - Regular data ops → Level 1 (hybrid)
+ * - Critical ops (key rotation) → Level 2 (maximum)
+ */
+
+/**
+ * Security policy configuration.
+ */
+interface SecurityPolicy {
+    /** Default level for operations not explicitly configured */
+    default: SecurityLevel;
+    /** Per-operation type overrides */
+    overrides: Record<string, SecurityLevel>;
+}
+/**
+ * Common operation types for security level selection.
+ */
+type OperationType = 'cursor-update' | 'presence-update' | 'typing-indicator' | 'viewport-update' | 'awareness-update' | 'node-create' | 'node-update' | 'node-delete' | 'yjs-update' | 'comment-add' | 'key-rotation' | 'permission-grant' | 'permission-revoke' | 'identity-recovery' | 'share-create';
+/**
+ * Default security policy.
+ *
+ * Uses Level 0 (Ed25519-only) by default for performance.
+ * High-frequency ephemeral operations use Level 0.
+ * Regular operations inherit the default.
+ * Critical operations can be configured to use Level 1 or 2.
+ */
+declare const DEFAULT_SECURITY_POLICY: SecurityPolicy;
+/**
+ * Hybrid security policy for when PQ protection is desired.
+ *
+ * Uses Level 1 (hybrid) for regular operations.
+ * Still uses Level 0 for high-frequency ephemeral ops.
+ * Critical ops use Level 2 (PQ-only).
+ */
+declare const HYBRID_SECURITY_POLICY: SecurityPolicy;
+/**
+ * Maximum security policy for high-security environments.
+ *
+ * Uses Level 2 (PQ-only) for everything except ephemeral ops.
+ */
+declare const MAX_SECURITY_POLICY: SecurityPolicy;
+/**
+ * Get the security level for an operation type.
+ *
+ * @param operationType - The type of operation
+ * @param policy - Security policy to use (default: DEFAULT_SECURITY_POLICY)
+ * @returns The appropriate security level
+ *
+ * @example
+ * ```typescript
+ * // Get level for a cursor update (fast)
+ * const level = getSecurityLevel('cursor-update')  // 0
+ *
+ * // Get level for a node creation
+ * const level = getSecurityLevel('node-create')  // uses policy default
+ *
+ * // Use hybrid policy for PQ protection
+ * const level = getSecurityLevel('node-create', HYBRID_SECURITY_POLICY)  // 1
+ * ```
+ */
+declare function getSecurityLevel(operationType: string, policy?: SecurityPolicy): SecurityLevel;
+/**
+ * Check if an operation type is ephemeral (high-frequency, low-value).
+ *
+ * Ephemeral operations typically use Level 0 for performance.
+ */
+declare function isEphemeralOperation(operationType: string): boolean;
+/**
+ * Check if an operation type is critical (requires high security).
+ */
+declare function isCriticalOperation(operationType: string): boolean;
+/**
+ * Create a custom security policy.
+ *
+ * @example
+ * ```typescript
+ * const myPolicy = createSecurityPolicy({
+ *   default: 1,
+ *   overrides: {
+ *     'cursor-update': 0,
+ *     'key-rotation': 2
+ *   }
+ * })
+ * ```
+ */
+declare function createSecurityPolicy(options?: Partial<SecurityPolicy>): SecurityPolicy;
+/**
+ * Merge policies, with later policies taking precedence.
+ */
+declare function mergeSecurityPolicies(...policies: Partial<SecurityPolicy>[]): SecurityPolicy;
+
+export { ALL_FEATURES, type AttestationVerificationResult, type AttestationVerifyResult, type AuthorizedDoc, type AuthorizedRoom, type AuthorizedStateAdapter, AuthorizedSyncManager, type AuthorizedSyncManagerOptions, AuthorizedYjsError, AuthorizedYjsSyncProvider, type AuthorizedYjsSyncProviderOptions, BaseSyncProvider, type BatchFlushCallback, COMPACTION_TIME_THRESHOLD, COMPACTION_UPDATE_THRESHOLD, CURRENT_PROTOCOL_VERSION, type ChainValidationResult, type Change, type ChangeHandler, ChangeHandlerRegistry, type ChangeSerializer, type ClientIdAttestation, type ClientIdAttestationV1, type ClientIdAttestationV2, type ClientIdAttestationWire, type ClientIdMap, ClientIdMapImpl, type ContentKeyProvider, type CreateAttestationOptions, type CreateChangeOptions, type CreateEnvelopeOptions, type CreateYjsChangeOptions, DEFAULT_BATCHER_CONFIG, DEFAULT_RATE_LIMITER_CONFIG, DEFAULT_SECURITY_POLICY, DEFAULT_YJS_SCORING_CONFIG, DEPRECATIONS, DEPRECATION_POLICY, type DeprecationCallback, type DeprecationContext, DeprecationError, type DeprecationNotice, type DeprecationType, type DeprecationWarning, type DeserializeError, type DeserializeOutcome, type DeserializeResult, type EncryptedYjsState, type EnvelopeVerificationResult, type EnvelopeVerifyResult, FEATURES, type FeatureConfig, type FeatureFlag, type FeatureValidationError, type FeatureValidationResult, type FeatureValidationWarning, type Fork, type GrantEventStore, HYBRID_SECURITY_POLICY, type HandlerContext, type HandlerEvent, type IntegrityIssue, type IntegrityIssueType, type IntegrityMonitor, type IntegrityMonitorConfig, type IntegrityMonitorStats, type IntegrityReport, type LamportClock, type LamportTimestamp, MAX_SECURITY_POLICY, MAX_YJS_DOC_SIZE, MAX_YJS_UPDATES_PER_MINUTE, MAX_YJS_UPDATES_PER_SECOND, MAX_YJS_UPDATE_SIZE, type MergeUpdatesFn, type NegotiatedSession, type NegotiationFailure, type NegotiationResult, type NegotiationWarning, type OperationType, type PeerAction, type PeerCapabilities, type PeerInfo, type PersistedDocState, type ProcessResult, type RateLimiterConfig, type ReactIntegrityMonitorOptions, type RecipientKeyResolver, type RegistryStats, type RepairAction, type RepairActionType, type SecurityPolicy, type SerializeOptions, type SerializedChange, type SerializerRegistry, type SignedYjsEnvelope, type SignedYjsEnvelopeV1, type SignedYjsEnvelopeV2, type SignedYjsEnvelopeWire, type SyncEventListener, type SyncProvider, type SyncProviderEvents, type SyncProviderOptions, type SyncStatus, type UnsignedChange, type UnsignedYjsChange, V1Serializer, V2Serializer, type ValidationError, type ValidationResult, type ValidationWarning, type VerifyAttestationOptions, type VerifyEnvelopeOptions, type VerifyOptions, VersionNegotiator, type YDocCodec, type YDocLike, YJS_CHANGE_TYPE, YJS_RATE_BURST_ALLOWANCE, YJS_SYNC_CHUNK_SIZE, type YjsAuthDecision, YjsAuthGate, type YjsAuthGateOptions, YjsBatcher, type YjsBatcherConfig, type YjsChange, YjsCheckpointer, type YjsCheckpointerOptions, YjsIntegrityError, type YjsPeerMetrics, YjsPeerScorer, YjsRateLimiter, type YjsScoringConfig, YjsStateIntegrityError, type YjsUpdatePayload, type YjsViolationType, addDependencies, attemptRepair, autoDeserialize, autoSerialize, calculateChunkCount, changeHandlerRegistry, checkAndLogDeprecations, checkDeprecations, chunkUpdate, clearLoggedDeprecations, compareLamportTimestamps, computeChangeHash, configureDeprecationPolicy, createBatchId, createChangeId, createClientIdAttestation, createClientIdAttestationV1, createClientIdAttestationV2, createHandler, createIntegrityMonitor, createLamportClock, createLocalCapabilities, createPersistedDocState, createReactIntegrityMonitor, createSecurityPolicy, createSerializerRegistry, createTestContext, createUnsignedChange, createUnsignedYjsChange, createVersionedHandler, createYjsChange, decryptYjsState, defaultNegotiator, deserializeClientIdAttestation, deserializeEncryptedYjsState, deserializeYjsEnvelope, detectFork, diffFeatures, encryptYjsState, envelopeSize, findCommonAncestor, findHeads, findOrphans, findRoots, formatDeprecationReport, formatIntegrityReport, getAllDependencies, getAncestry, getChainDepth, getChainHeads, getChainRoots, getChangeNodeId, getDefaultSerializer, getDeprecation, getDeprecationsByType, getEnabledFeatures, getFeatureConflicts, getFeatureDependencies, getFeatureVersion, getForks, getOptionalFeatures, getRequiredFeatures, getSecurityLevel, getSerializer, hasSignedEnvelope, hashYjsState, intersectFeatures, isAfter, isBefore, isCriticalOperation, isDeprecated, isDocumentTooLarge, isEphemeralOperation, isFeatureAvailable, isFeatureEnabled, isLegacyUpdate, isNodeChange, isRemoved, isUpdateTooLarge, isV1Attestation, isV1Envelope, isV2Attestation, isV2Envelope, isYjsChange, loadVerifiedState, logDeprecation, maxTime, mergeSecurityPolicies, parseCapabilities, parseTimestamp, quickIntegrityCheck, reassembleChunks, receive, registerDeprecation, serializeClientIdAttestation, serializeEncryptedYjsState, serializeTimestamp, serializeYjsEnvelope, serializerRegistry, shouldCompact, signChange, signYjsUpdate, signYjsUpdateBatch, signYjsUpdateV1, signYjsUpdateV2, tick, toEncryptedData, topologicalSort, v1Serializer, v2Serializer, validateChain, validateClientIdOwnership, validateFeatureSet, verifyChange, verifyChangeHash, verifyClientIdAttestation, verifyClientIdAttestationV1, verifyClientIdAttestationV2, verifyIntegrity, verifyPersistedDocState, verifySingleChange, verifyYjsEnvelope, verifyYjsEnvelopeQuick, verifyYjsEnvelopeV1, verifyYjsEnvelopeV2, verifyYjsStateIntegrity };