@private.me/xcontinuity 2.1.0

package/dist/ratification.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @private.me/xcontinuity — Ratification (TrustStore)
+ *
+ * Central store for trust-annotated memory entries.
+ * Integrates provenance (signing), trust tiers, chronicle (history),
+ * adjudicator (conflict resolution), and event hooks.
+ *
+ * Key flows:
+ *   write()  — store an entry with automatic trust tier assignment
+ *   ratify() — sign an entry, promoting it to 'ratified' tier
+ *   restore() — rebuild trust state from a chronicle
+ *   hypothesisMode() — sandbox for speculative writes
+ */
+import type { Result } from '@private.me/shared';
+import type { MemoryEntry, ProvenanceRecord, StateValue, TrustTier, TrustStoreEventType, TrustStoreEvent, TrustStoreListener } from './types.js';
+import type { ContinuityError } from './errors.js';
+import { Chronicle } from './chronicle.js';
+import type { Adjudicator } from './adjudicator.js';
+/** Configuration for creating a TrustStore. */
+export interface TrustStoreConfig {
+    /** Default adjudicator for conflict resolution. */
+    readonly adjudicator?: Adjudicator;
+    /** Default maxAge (TTL) for new entries (ms). Undefined = no decay. */
+    readonly defaultMaxAge?: number;
+}
+export declare class TrustStore {
+    private readonly entries;
+    private readonly chronicle;
+    private readonly adjudicator;
+    private readonly defaultMaxAge?;
+    private readonly listeners;
+    private sequenceCounter;
+    constructor(config?: TrustStoreConfig);
+    /**
+     * Write an entry to the trust store.
+     *
+     * Assigns trust tier based on provenance, checks for contradictions
+     * against the chronicle, and emits events.
+     */
+    write(key: string, value: StateValue, provenance?: ProvenanceRecord, signatureVerified?: boolean): Result<MemoryEntry, ContinuityError>;
+    /**
+     * Ratify an entry by signing it with Ed25519, promoting to 'ratified' tier.
+     */
+    ratify(key: string, privateKey: CryptoKey, publicKey: CryptoKey): Promise<Result<MemoryEntry, ContinuityError>>;
+    /**
+     * Read an entry, applying effective tier (decay + contradictions).
+     */
+    read(key: string): MemoryEntry | undefined;
+    /**
+     * Read an entry only if it meets a minimum trust tier.
+     */
+    readAtTier(key: string, minTier: TrustTier): MemoryEntry | undefined;
+    /** Check if a key exists in the store. */
+    has(key: string): boolean;
+    /** Delete an entry. */
+    delete(key: string): boolean;
+    /** Get all keys. */
+    keys(): string[];
+    /** Get all entries. */
+    all(): readonly MemoryEntry[];
+    /** Get the chronicle (read-only access). */
+    getChronicle(): Chronicle;
+    /** Get the entry count. */
+    get size(): number;
+    /**
+     * Restore trust state from an array of memory entries.
+     * Used to rebuild state after loading from persistence.
+     */
+    restore(entries: readonly MemoryEntry[]): void;
+    /**
+     * Create a hypothesis (sandbox) that can be committed or discarded.
+     *
+     * All writes in the hypothesis are isolated from the main store.
+     * Call commit() to merge into the main store, or discard() to abandon.
+     */
+    hypothesisMode(): Hypothesis;
+    /** Subscribe to trust store events. */
+    on<T extends TrustStoreEvent>(event: TrustStoreEventType, listener: TrustStoreListener<T>): void;
+    /** Unsubscribe from trust store events. */
+    off<T extends TrustStoreEvent>(event: TrustStoreEventType, listener: TrustStoreListener<T>): void;
+    /** Remove all event listeners. */
+    removeAllListeners(): void;
+    /** Emit an event to all registered listeners. */
+    private emit;
+    /** @internal Merge entries from a hypothesis into the main store. */
+    _mergeHypothesis(entries: Map<string, MemoryEntry>): void;
+}
+/**
+ * A sandboxed hypothesis for speculative writes.
+ *
+ * Changes are isolated until commit() is called.
+ * Memory is bounded — the hypothesis shares the parent's maxAge config.
+ */
+export declare class Hypothesis {
+    private readonly parent;
+    private readonly baseSnapshot;
+    private readonly changes;
+    private committed;
+    private discarded;
+    constructor(parent: TrustStore, baseSnapshot: Map<string, MemoryEntry>);
+    /** Write a speculative entry (isolated from main store). */
+    write(key: string, value: StateValue, tier?: TrustTier): MemoryEntry;
+    /** Read from hypothesis (falls back to base snapshot). */
+    read(key: string): MemoryEntry | undefined;
+    /** Commit all hypothesis changes into the main store. */
+    commit(): void;
+    /** Discard all hypothesis changes. */
+    discard(): void;
+    /** Check if the hypothesis has been finalized. */
+    get isFinalized(): boolean;
+    /** Get the number of speculative changes. */
+    get changeCount(): number;
+}

package/dist/ratification.js

@@ -0,0 +1,317 @@
+/**
+ * @private.me/xcontinuity — Ratification (TrustStore)
+ *
+ * Central store for trust-annotated memory entries.
+ * Integrates provenance (signing), trust tiers, chronicle (history),
+ * adjudicator (conflict resolution), and event hooks.
+ *
+ * Key flows:
+ *   write()  — store an entry with automatic trust tier assignment
+ *   ratify() — sign an entry, promoting it to 'ratified' tier
+ *   restore() — rebuild trust state from a chronicle
+ *   hypothesisMode() — sandbox for speculative writes
+ */
+import { ok, err } from '@private.me/shared';
+import { continuityError } from './errors.js';
+import { baselineTier, effectiveTier } from './trust.js';
+import { signEntry } from './provenance.js';
+import { Chronicle, detectContradiction } from './chronicle.js';
+import { PolicyAdjudicator } from './adjudicator.js';
+export class TrustStore {
+    entries = new Map();
+    chronicle = new Chronicle();
+    adjudicator;
+    defaultMaxAge;
+    listeners = new Map();
+    sequenceCounter = 0;
+    constructor(config = {}) {
+        this.adjudicator = config.adjudicator ?? new PolicyAdjudicator();
+        this.defaultMaxAge = config.defaultMaxAge;
+    }
+    /**
+     * Write an entry to the trust store.
+     *
+     * Assigns trust tier based on provenance, checks for contradictions
+     * against the chronicle, and emits events.
+     */
+    write(key, value, provenance, signatureVerified = false) {
+        const tier = baselineTier(provenance, signatureVerified);
+        const oldEntry = this.entries.get(key);
+        // Check for contradictions
+        const contradictions = [];
+        if (oldEntry !== undefined) {
+            if (detectContradiction(value, oldEntry.value)) {
+                contradictions.push(oldEntry.key);
+                this.emit('contradiction', {
+                    key,
+                    existing: oldEntry,
+                    incoming: { key, value, provenance, tier, contradictions, maxAge: this.defaultMaxAge },
+                });
+            }
+        }
+        const entry = {
+            key,
+            value,
+            provenance,
+            tier,
+            contradictions,
+            maxAge: this.defaultMaxAge,
+            ratifiedAt: tier === 'ratified' ? Date.now() : undefined,
+        };
+        this.entries.set(key, entry);
+        // Record in chronicle
+        const stateId = `entry-${this.sequenceCounter}`;
+        this.chronicle.appendWithContradictionCheck({
+            stateId,
+            sessionId: 'trust-store',
+            sequence: this.sequenceCounter++,
+            timestamp: Date.now(),
+            tags: [tier],
+            parentStateId: oldEntry ? `entry-${this.sequenceCounter - 2}` : undefined,
+        }, key, value, oldEntry?.value);
+        // Emit change event
+        this.emit('change', { key, oldEntry, newEntry: entry });
+        // Emit tier change if applicable
+        if (oldEntry && oldEntry.tier !== tier) {
+            this.emit('tierChange', {
+                key,
+                oldTier: oldEntry.tier,
+                newTier: tier,
+                reason: provenance ? 'provenance changed' : 'new write',
+            });
+        }
+        return ok(entry);
+    }
+    /**
+     * Ratify an entry by signing it with Ed25519, promoting to 'ratified' tier.
+     */
+    async ratify(key, privateKey, publicKey) {
+        const existing = this.entries.get(key);
+        if (!existing) {
+            return err(continuityError('ENTRY_NOT_FOUND', `No entry for key "${key}"`));
+        }
+        // Sign the entry
+        const signResult = await signEntry(key, existing.value, privateKey, publicKey, existing.provenance?.parentHash);
+        if (!signResult.ok)
+            return signResult;
+        const oldTier = existing.tier;
+        const ratified = {
+            ...existing,
+            provenance: signResult.value,
+            tier: 'ratified',
+            ratifiedAt: Date.now(),
+        };
+        this.entries.set(key, ratified);
+        if (oldTier !== 'ratified') {
+            this.emit('tierChange', {
+                key,
+                oldTier,
+                newTier: 'ratified',
+                reason: 'ratified by signing',
+            });
+        }
+        this.emit('change', { key, oldEntry: existing, newEntry: ratified });
+        return ok(ratified);
+    }
+    /**
+     * Read an entry, applying effective tier (decay + contradictions).
+     */
+    read(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        const effective = effectiveTier(entry);
+        if (effective !== entry.tier) {
+            // Update stored tier to reflect decay/contradictions
+            const updated = { ...entry, tier: effective };
+            this.entries.set(key, updated);
+            this.emit('tierChange', {
+                key,
+                oldTier: entry.tier,
+                newTier: effective,
+                reason: effective === 'inherited' ? 'TTL decay' : 'contradiction downgrade',
+            });
+            return updated;
+        }
+        return entry;
+    }
+    /**
+     * Read an entry only if it meets a minimum trust tier.
+     */
+    readAtTier(key, minTier) {
+        const entry = this.read(key);
+        if (!entry)
+            return undefined;
+        const tierRank = { ratified: 3, inherited: 2, quarantined: 1 };
+        if (tierRank[entry.tier] < tierRank[minTier])
+            return undefined;
+        return entry;
+    }
+    /** Check if a key exists in the store. */
+    has(key) {
+        return this.entries.has(key);
+    }
+    /** Delete an entry. */
+    delete(key) {
+        const existing = this.entries.get(key);
+        if (!existing)
+            return false;
+        this.entries.delete(key);
+        return true;
+    }
+    /** Get all keys. */
+    keys() {
+        return Array.from(this.entries.keys());
+    }
+    /** Get all entries. */
+    all() {
+        return Array.from(this.entries.values());
+    }
+    /** Get the chronicle (read-only access). */
+    getChronicle() {
+        return this.chronicle;
+    }
+    /** Get the entry count. */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Restore trust state from an array of memory entries.
+     * Used to rebuild state after loading from persistence.
+     */
+    restore(entries) {
+        this.entries.clear();
+        this.chronicle.clear();
+        this.sequenceCounter = 0;
+        for (const entry of entries) {
+            this.entries.set(entry.key, entry);
+            this.chronicle.append({
+                stateId: `entry-${this.sequenceCounter}`,
+                sessionId: 'trust-store',
+                sequence: this.sequenceCounter++,
+                timestamp: entry.provenance?.timestamp ?? Date.now(),
+                tags: [entry.tier],
+            });
+        }
+    }
+    /**
+     * Create a hypothesis (sandbox) that can be committed or discarded.
+     *
+     * All writes in the hypothesis are isolated from the main store.
+     * Call commit() to merge into the main store, or discard() to abandon.
+     */
+    hypothesisMode() {
+        // Snapshot current entries
+        const snapshot = new Map();
+        for (const [key, entry] of this.entries) {
+            snapshot.set(key, entry);
+        }
+        return new Hypothesis(this, snapshot);
+    }
+    /* ── Event System ── */
+    /** Subscribe to trust store events. */
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+    }
+    /** Unsubscribe from trust store events. */
+    off(event, listener) {
+        const set = this.listeners.get(event);
+        if (set) {
+            set.delete(listener);
+        }
+    }
+    /** Remove all event listeners. */
+    removeAllListeners() {
+        this.listeners.clear();
+    }
+    /** Emit an event to all registered listeners. */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (set) {
+            for (const listener of set) {
+                listener(payload);
+            }
+        }
+    }
+    /* ── Internal: used by Hypothesis ── */
+    /** @internal Merge entries from a hypothesis into the main store. */
+    _mergeHypothesis(entries) {
+        for (const [key, entry] of entries) {
+            const existing = this.entries.get(key);
+            this.entries.set(key, entry);
+            this.emit('change', { key, oldEntry: existing, newEntry: entry });
+            if (existing && existing.tier !== entry.tier) {
+                this.emit('tierChange', {
+                    key,
+                    oldTier: existing.tier,
+                    newTier: entry.tier,
+                    reason: 'hypothesis committed',
+                });
+            }
+        }
+    }
+}
+/**
+ * A sandboxed hypothesis for speculative writes.
+ *
+ * Changes are isolated until commit() is called.
+ * Memory is bounded — the hypothesis shares the parent's maxAge config.
+ */
+export class Hypothesis {
+    parent;
+    baseSnapshot;
+    changes = new Map();
+    committed = false;
+    discarded = false;
+    constructor(parent, baseSnapshot) {
+        this.parent = parent;
+        this.baseSnapshot = baseSnapshot;
+    }
+    /** Write a speculative entry (isolated from main store). */
+    write(key, value, tier = 'inherited') {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        const entry = {
+            key,
+            value,
+            tier,
+            contradictions: [],
+        };
+        this.changes.set(key, entry);
+        return entry;
+    }
+    /** Read from hypothesis (falls back to base snapshot). */
+    read(key) {
+        return this.changes.get(key) ?? this.baseSnapshot.get(key);
+    }
+    /** Commit all hypothesis changes into the main store. */
+    commit() {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        this.committed = true;
+        this.parent._mergeHypothesis(this.changes);
+    }
+    /** Discard all hypothesis changes. */
+    discard() {
+        if (this.committed || this.discarded) {
+            throw new Error('Hypothesis already finalized');
+        }
+        this.discarded = true;
+        this.changes.clear();
+    }
+    /** Check if the hypothesis has been finalized. */
+    get isFinalized() {
+        return this.committed || this.discarded;
+    }
+    /** Get the number of speculative changes. */
+    get changeCount() {
+        return this.changes.size;
+    }
+}

package/dist/reverse-xorida.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @private.me/xcontinuity — Reverse-XorIDA Core Crypto Layer
+ *
+ * The novel primitive: exploits XorIDA's linearity over GF(2) to perform
+ * incremental state updates at O(delta) cost instead of re-splitting entire state.
+ *
+ * Key insight: split(A XOR B) = split(A) XOR split(B)
+ *
+ * Therefore: newShares = oldShares XOR split(oldPadded XOR newPadded)
+ *
+ * HMAC must be recomputed fresh for the new state (not derived from delta).
+ */
+import type { Result } from '@private.me/shared';
+import type { StateSnapshot, StateShare, SplitState, SplitConfig, StateDelta } from './types.js';
+import type { ContinuityError } from './errors.js';
+/**
+ * Pad data for XorIDA splitting.
+ * Block size = nextOddPrime(n) - 1.
+ */
+export declare function padForSplit(data: Uint8Array, n: number): Uint8Array;
+/**
+ * Split a state snapshot into XorIDA threshold shares.
+ *
+ * Pipeline: pad -> HMAC -> split -> package as StateShare[]
+ *
+ * @param snapshot - Serialized state with checksum
+ * @param config - Split configuration (n, k)
+ * @returns SplitState containing all shares
+ */
+export declare function splitState(snapshot: StateSnapshot, config?: SplitConfig): Promise<Result<SplitState, ContinuityError>>;
+/**
+ * Reconstruct a state snapshot from threshold shares.
+ *
+ * Pipeline: validate -> reconstruct -> verify HMAC -> unpad -> return snapshot bytes
+ *
+ * @param shares - Array of k or more StateShares (uses first k)
+ * @returns Reconstructed StateSnapshot serialized bytes and checksum
+ */
+export declare function reconstructState(shares: readonly StateShare[]): Promise<Result<{
+    serializedBytes: Uint8Array;
+    stateId: string;
+}, ContinuityError>>;
+/**
+ * Compute the byte-level delta between two padded state arrays.
+ * Both arrays must be the same length.
+ *
+ * delta[i] = oldPadded[i] XOR newPadded[i]
+ */
+export declare function computeDelta(oldPadded: Uint8Array, newPadded: Uint8Array, fromStateId: string, toStateId: string, fromChecksum: Uint8Array, toChecksum: Uint8Array): Result<StateDelta, ContinuityError>;
+/**
+ * Apply delta shares to old split state via XOR.
+ *
+ * newShares[i].data = oldShares[i].data XOR deltaShares[i].data
+ *
+ * @param oldShares - Original shares
+ * @param deltaShares - Delta shares (from splitting the delta)
+ * @param newStateId - State ID for the new split state
+ * @param newMetadata - Metadata for the new state
+ * @param newHmacKey - Fresh HMAC key for the new state
+ * @param newHmacSignature - Fresh HMAC signature for the new padded state
+ */
+export declare function applyDeltaShares(oldShares: readonly StateShare[], deltaShares: Uint8Array[], newStateId: string, newHmacKey: Uint8Array, newHmacSignature: Uint8Array): Result<StateShare[], ContinuityError>;
+/**
+ * Perform an incremental state update using Reverse-XorIDA.
+ *
+ * Instead of re-splitting the entire new state:
+ * 1. Pad both old and new to the same block-aligned size
+ * 2. Compute delta = oldPadded XOR newPadded
+ * 3. Split the delta
+ * 4. XOR each old share with the corresponding delta share
+ * 5. Recompute HMAC fresh for the new padded state
+ *
+ * Falls back to fresh split when sizes differ significantly
+ * (incremental update only works when padded lengths match).
+ *
+ * @param oldSplitState - Previous split state
+ * @param oldSnapshot - Previous state snapshot
+ * @param newSnapshot - New state snapshot
+ * @returns Updated SplitState with new shares
+ */
+export declare function incrementalUpdate(oldSplitState: SplitState, oldSnapshot: StateSnapshot, newSnapshot: StateSnapshot): Promise<Result<SplitState, ContinuityError>>;
+/**
+ * Extension 1: Undo / Time-Travel
+ *
+ * Reverse a delta by re-applying it (XOR is its own inverse in GF(2)).
+ * Given shares at state B and the delta A→B, produces shares at state A.
+ *
+ * Math: shares_A = shares_B ⊕ deltaShares(A→B)
+ *       because: (A ⊕ Δ) ⊕ Δ = A  (XOR self-inverse)
+ */
+export declare function undoDelta(currentShares: readonly StateShare[], deltaShares: Uint8Array[], previousStateId: string, hmacKey: Uint8Array, hmacSignature: Uint8Array): Result<StateShare[], ContinuityError>;
+/**
+ * Extension 2: Branch
+ *
+ * Fork a split state into an independent branch by copying shares.
+ * The branch can diverge independently from the original.
+ *
+ * @param source - The split state to branch from
+ * @param branchStateId - New stateId for the branch
+ * @returns Independent copy of the split state
+ */
+export declare function branchState(source: SplitState, branchStateId: string): SplitState;
+/**
+ * Extension 3: Delta Squashing
+ *
+ * Combine multiple sequential deltas into a single delta.
+ * Exploits GF(2) associativity: Δ_total = Δ₁ ⊕ Δ₂ ⊕ ... ⊕ Δₙ
+ *
+ * @param deltas - Ordered array of deltas to squash (must form a chain)
+ * @returns Single squashed delta from first.fromStateId to last.toStateId
+ */
+export declare function squashDeltas(deltas: readonly StateDelta[]): Result<StateDelta, ContinuityError>;
+/**
+ * Extension 4: Blind Update
+ *
+ * Apply a delta to shares without seeing the plaintext state.
+ * The share holder never reconstructs the full state.
+ *
+ * Math: newShare_i = oldShare_i ⊕ deltaShare_i
+ *
+ * @param share - A single share to update
+ * @param deltaShareData - The corresponding delta share data
+ * @param newStateId - New state identifier
+ * @param newHmacKey - Fresh HMAC key
+ * @param newHmacSignature - Fresh HMAC signature
+ */
+export declare function blindUpdateShare(share: StateShare, deltaShareData: Uint8Array, newStateId: string, newHmacKey: Uint8Array, newHmacSignature: Uint8Array): Result<StateShare, ContinuityError>;
+/**
+ * Extension 5: Proactive Share Refresh
+ *
+ * Re-randomize shares while preserving reconstruction correctness.
+ * Generates a random mask, splits it, XORs with existing shares.
+ * The mask XORs to zero upon reconstruction, so the plaintext is unchanged.
+ *
+ * @param splitState - Current split state
+ * @returns Refreshed split state with re-randomized shares (same plaintext)
+ */
+export declare function refreshShares(state: SplitState): Promise<Result<SplitState, ContinuityError>>;
+/**
+ * Extension 6: Blind Equality Check
+ *
+ * Compare two split states for equality without reconstructing plaintext.
+ * Computes delta between corresponding shares — if all delta bytes are zero,
+ * the states are equal.
+ *
+ * @param a - First split state
+ * @param b - Second split state
+ * @returns true if both states encode the same plaintext
+ */
+export declare function blindEqual(a: SplitState, b: SplitState): Result<boolean, ContinuityError>;
+/**
+ * Extension 7: Network-Coded Sync
+ *
+ * Combine multiple shares during transit using XOR for bandwidth efficiency.
+ * The receiver can extract individual shares if they hold the complementary shares.
+ *
+ * coded = share_i ⊕ share_j
+ * share_i = coded ⊕ share_j  (if receiver already holds share_j)
+ *
+ * @param shares - Array of shares to combine
+ * @returns Single coded block (XOR of all input shares)
+ */
+export declare function networkCodeShares(shares: readonly StateShare[]): Result<Uint8Array, ContinuityError>;
+/**
+ * Decode a network-coded block using a held share.
+ *
+ * If coded = share_i ⊕ share_j, and you hold share_j:
+ *   share_i = coded ⊕ share_j
+ *
+ * @param codedBlock - The network-coded block
+ * @param heldShare - The share the receiver already holds
+ * @returns The extracted share data
+ */
+export declare function networkDecodeShare(codedBlock: Uint8Array, heldShare: StateShare): Result<Uint8Array, ContinuityError>;