@private.me/xcontinuity 2.1.0

package/dist/chronicle.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @private.me/xcontinuity — Chronicle (State History)
+ *
+ * Append-only ordered state history with navigation.
+ * Secondary index (Map stateId->index) for O(1) lookup.
+ * Query with filters: sessionId, time range, tags, limit/offset pagination.
+ */
+import type { Result } from '@private.me/shared';
+import type { ChronicleEntry, ChronicleQuery, StateValue } from './types.js';
+import type { ContinuityError } from './errors.js';
+/** Extended chronicle entry with contradiction and revision tracking. */
+export interface ChronicleContradiction {
+    /** The stateId of the new (incoming) entry. */
+    readonly incomingStateId: string;
+    /** The stateId of the existing (contradicted) entry. */
+    readonly existingStateId: string;
+    /** The key on which the contradiction was detected. */
+    readonly key: string;
+    /** Timestamp when the contradiction was detected. */
+    readonly detectedAt: number;
+}
+export declare class Chronicle {
+    private readonly entries;
+    private readonly indexByStateId;
+    /** Track the latest stateId for each key (for contradiction detection). */
+    private readonly latestByKey;
+    /** Detected contradictions. */
+    private readonly contradictions;
+    /** Append a new entry to the chronicle. */
+    append(entry: ChronicleEntry): void;
+    /**
+     * Append an entry and check for contradictions against the latest
+     * value for the same key. Returns detected contradictions (if any).
+     *
+     * @param entry - The chronicle entry
+     * @param key - The state key this entry represents
+     * @param value - The new value for the key
+     * @param existingValue - The most recent known value for the key (if any)
+     * @returns Array of contradictions detected (empty if none)
+     */
+    appendWithContradictionCheck(entry: ChronicleEntry, key: string, value: StateValue, existingValue?: StateValue): ChronicleContradiction[];
+    /** Get all detected contradictions. */
+    getContradictions(): readonly ChronicleContradiction[];
+    /** Get contradictions for a specific key. */
+    getContradictionsForKey(key: string): readonly ChronicleContradiction[];
+    /** Get the latest stateId recorded for a given key. */
+    getLatestForKey(key: string): string | undefined;
+    /** Get an entry by stateId. O(1) lookup. */
+    get(stateId: string): Result<ChronicleEntry, ContinuityError>;
+    /** Get the latest entry, or null if empty. */
+    latest(): ChronicleEntry | null;
+    /** Get entry at a specific sequence position. */
+    atSequence(sequence: number): Result<ChronicleEntry, ContinuityError>;
+    /** Get the parent entry (if parentStateId is set). */
+    parent(stateId: string): Result<ChronicleEntry, ContinuityError>;
+    /**
+     * Query chronicle entries with filters.
+     *
+     * @param query - Filter criteria (sessionId, time range, tags, limit/offset)
+     * @returns Matching entries ordered by timestamp
+     */
+    query(query?: ChronicleQuery): ChronicleEntry[];
+    /** Total number of entries. */
+    get length(): number;
+    /** Get all entries (readonly copy). */
+    all(): readonly ChronicleEntry[];
+    /** Clear all entries. */
+    clear(): void;
+}
+/**
+ * Detect whether two values for the same key contradict each other.
+ *
+ * Contradiction = values are structurally different.
+ * Identical values are not contradictions (they're confirmations).
+ */
+export declare function detectContradiction(newValue: StateValue, existingValue: StateValue): boolean;

package/dist/chronicle.js

@@ -0,0 +1,173 @@
+/**
+ * @private.me/xcontinuity — Chronicle (State History)
+ *
+ * Append-only ordered state history with navigation.
+ * Secondary index (Map stateId->index) for O(1) lookup.
+ * Query with filters: sessionId, time range, tags, limit/offset pagination.
+ */
+import { ok, err } from '@private.me/shared';
+import { continuityError } from './errors.js';
+export class Chronicle {
+    entries = [];
+    indexByStateId = new Map();
+    /** Track the latest stateId for each key (for contradiction detection). */
+    latestByKey = new Map();
+    /** Detected contradictions. */
+    contradictions = [];
+    /** Append a new entry to the chronicle. */
+    append(entry) {
+        const idx = this.entries.length;
+        this.entries.push(entry);
+        this.indexByStateId.set(entry.stateId, idx);
+    }
+    /**
+     * Append an entry and check for contradictions against the latest
+     * value for the same key. Returns detected contradictions (if any).
+     *
+     * @param entry - The chronicle entry
+     * @param key - The state key this entry represents
+     * @param value - The new value for the key
+     * @param existingValue - The most recent known value for the key (if any)
+     * @returns Array of contradictions detected (empty if none)
+     */
+    appendWithContradictionCheck(entry, key, value, existingValue) {
+        const detected = [];
+        const previousStateId = this.latestByKey.get(key);
+        if (previousStateId !== undefined && existingValue !== undefined) {
+            if (detectContradiction(value, existingValue)) {
+                const contradiction = {
+                    incomingStateId: entry.stateId,
+                    existingStateId: previousStateId,
+                    key,
+                    detectedAt: Date.now(),
+                };
+                detected.push(contradiction);
+                this.contradictions.push(contradiction);
+            }
+        }
+        this.latestByKey.set(key, entry.stateId);
+        this.append(entry);
+        return detected;
+    }
+    /** Get all detected contradictions. */
+    getContradictions() {
+        return this.contradictions.slice();
+    }
+    /** Get contradictions for a specific key. */
+    getContradictionsForKey(key) {
+        return this.contradictions.filter(c => c.key === key);
+    }
+    /** Get the latest stateId recorded for a given key. */
+    getLatestForKey(key) {
+        return this.latestByKey.get(key);
+    }
+    /** Get an entry by stateId. O(1) lookup. */
+    get(stateId) {
+        const idx = this.indexByStateId.get(stateId);
+        if (idx === undefined) {
+            return err(continuityError('ENTRY_NOT_FOUND', `Chronicle entry ${stateId} not found`));
+        }
+        return ok(this.entries[idx]);
+    }
+    /** Get the latest entry, or null if empty. */
+    latest() {
+        if (this.entries.length === 0)
+            return null;
+        return this.entries[this.entries.length - 1];
+    }
+    /** Get entry at a specific sequence position. */
+    atSequence(sequence) {
+        const entry = this.entries.find(e => e.sequence === sequence);
+        if (!entry) {
+            return err(continuityError('ENTRY_NOT_FOUND', `No entry with sequence ${sequence}`));
+        }
+        return ok(entry);
+    }
+    /** Get the parent entry (if parentStateId is set). */
+    parent(stateId) {
+        const entryResult = this.get(stateId);
+        if (!entryResult.ok)
+            return entryResult;
+        const entry = entryResult.value;
+        if (!entry.parentStateId) {
+            return err(continuityError('ENTRY_NOT_FOUND', `Entry ${stateId} has no parent`));
+        }
+        return this.get(entry.parentStateId);
+    }
+    /**
+     * Query chronicle entries with filters.
+     *
+     * @param query - Filter criteria (sessionId, time range, tags, limit/offset)
+     * @returns Matching entries ordered by timestamp
+     */
+    query(query = {}) {
+        let results = this.entries.slice();
+        if (query.sessionId) {
+            results = results.filter(e => e.sessionId === query.sessionId);
+        }
+        if (query.after !== undefined) {
+            results = results.filter(e => e.timestamp >= query.after);
+        }
+        if (query.before !== undefined) {
+            results = results.filter(e => e.timestamp <= query.before);
+        }
+        if (query.tags && query.tags.length > 0) {
+            const tagSet = new Set(query.tags);
+            results = results.filter(e => e.tags.some(t => tagSet.has(t)));
+        }
+        // Pagination
+        const offset = query.offset ?? 0;
+        const limit = query.limit ?? results.length;
+        return results.slice(offset, offset + limit);
+    }
+    /** Total number of entries. */
+    get length() {
+        return this.entries.length;
+    }
+    /** Get all entries (readonly copy). */
+    all() {
+        return this.entries.slice();
+    }
+    /** Clear all entries. */
+    clear() {
+        this.entries.length = 0;
+        this.indexByStateId.clear();
+        this.latestByKey.clear();
+        this.contradictions.length = 0;
+    }
+}
+/**
+ * Detect whether two values for the same key contradict each other.
+ *
+ * Contradiction = values are structurally different.
+ * Identical values are not contradictions (they're confirmations).
+ */
+export function detectContradiction(newValue, existingValue) {
+    // Null checks
+    if (newValue === null && existingValue === null)
+        return false;
+    if (newValue === null || existingValue === null)
+        return true;
+    // Uint8Array comparison
+    if (newValue instanceof Uint8Array && existingValue instanceof Uint8Array) {
+        if (newValue.length !== existingValue.length)
+            return true;
+        for (let i = 0; i < newValue.length; i++) {
+            if (newValue[i] !== existingValue[i])
+                return true;
+        }
+        return false;
+    }
+    // Type mismatch
+    if (typeof newValue !== typeof existingValue)
+        return true;
+    if (newValue instanceof Uint8Array || existingValue instanceof Uint8Array)
+        return true;
+    // Object comparison (deterministic JSON)
+    if (typeof newValue === 'object' && typeof existingValue === 'object') {
+        return JSON.stringify(newValue, Object.keys(newValue).sort())
+            !== JSON.stringify(existingValue, Object.keys(existingValue).sort());
+    }
+    // Primitive comparison
+    return newValue !== existingValue;
+}

package/dist/cjs/adjudicator.js

@@ -0,0 +1,189 @@
+"use strict";
+/**
+ * @private.me/xcontinuity — Adjudicator (Conflict Resolution)
+ *
+ * Resolves conflicts when multiple entries exist for the same key.
+ *
+ * Two implementations:
+ *   PolicyAdjudicator — deterministic local resolution (default)
+ *   ConsensusAdjudicator — multi-agent IXorIDA-backed resolution
+ *
+ * Deterministic tiebreaker (total ordering):
+ *   1. Highest trust tier
+ *   2. Newest timestamp
+ *   3. Lexicographically lowest author DID
+ *
+ * This guarantees two agents merging the same conflicting entries
+ * always pick the same winner — convergent merge without human input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConsensusAdjudicator = exports.PolicyAdjudicator = void 0;
+const shared_1 = require("@private.me/shared");
+const types_js_1 = require("./types.js");
+const errors_js_1 = require("./errors.js");
+const trust_js_1 = require("./trust.js");
+/**
+ * Policy-based adjudicator (default).
+ *
+ * Deterministic resolution using total ordering:
+ *   1. Highest effective trust tier (with decay applied)
+ *   2. Newest timestamp (higher = more recent)
+ *   3. Lexicographically lowest author DID (deterministic tiebreaker)
+ */
+class PolicyAdjudicator {
+    resolve(key, candidates) {
+        if (candidates.length === 0) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('NO_CANDIDATES', `No candidates for key "${key}"`));
+        }
+        if (candidates.length === 1) {
+            return (0, shared_1.ok)({ winner: candidates[0], reason: 'single candidate' });
+        }
+        let winner = candidates[0];
+        let winnerTier = (0, trust_js_1.effectiveTier)(winner);
+        for (let i = 1; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const candidateTier = (0, trust_js_1.effectiveTier)(candidate);
+            const comparison = compareCandidates(winner, winnerTier, candidate, candidateTier);
+            if (comparison < 0) {
+                winner = candidate;
+                winnerTier = candidateTier;
+            }
+        }
+        const reason = buildReason(winner, winnerTier, candidates.length);
+        return (0, shared_1.ok)({ winner, reason });
+    }
+}
+exports.PolicyAdjudicator = PolicyAdjudicator;
+/**
+ * Consensus-based adjudicator for multi-agent scenarios.
+ *
+ * Gathers views from participating agents via ViewProvider,
+ * then applies majority voting with policy fallback.
+ * Requires a quorum (> 50% of views must agree).
+ */
+class ConsensusAdjudicator {
+    viewProvider;
+    policyFallback = new PolicyAdjudicator();
+    constructor(viewProvider) {
+        this.viewProvider = viewProvider;
+    }
+    resolve(key, candidates) {
+        // Synchronous interface — consensus requires async gatherViews.
+        // For synchronous resolve(), fall back to policy adjudication.
+        // Use resolveAsync() for full consensus.
+        return this.policyFallback.resolve(key, candidates);
+    }
+    /**
+     * Async resolution with full multi-agent consensus.
+     *
+     * @param key - The contested key
+     * @param candidates - Local candidates
+     * @returns Consensus-resolved winner
+     */
+    async resolveAsync(key, candidates) {
+        try {
+            const views = await this.viewProvider.gatherViews(key);
+            if (views.length === 0) {
+                return this.policyFallback.resolve(key, candidates);
+            }
+            // Combine local candidates with remote views
+            const allEntries = [
+                ...candidates,
+                ...views.map(v => v.entry),
+            ];
+            if (allEntries.length === 0) {
+                return (0, shared_1.err)((0, errors_js_1.continuityError)('NO_CANDIDATES', `No candidates for key "${key}"`));
+            }
+            // Count votes by value (group entries with same effective value)
+            const voteGroups = groupByValue(allEntries);
+            const totalVotes = allEntries.length;
+            const quorum = Math.floor(totalVotes / 2) + 1;
+            // Find group with most votes
+            let bestGroup = voteGroups[0];
+            for (const group of voteGroups) {
+                if (group.count > bestGroup.count) {
+                    bestGroup = group;
+                }
+            }
+            if (bestGroup.count >= quorum) {
+                // Quorum reached — use the best entry from the winning group
+                const groupResult = this.policyFallback.resolve(key, bestGroup.entries);
+                if (!groupResult.ok)
+                    return groupResult;
+                return (0, shared_1.ok)({
+                    winner: groupResult.value.winner,
+                    reason: `consensus: ${bestGroup.count}/${totalVotes} votes (quorum=${quorum})`,
+                });
+            }
+            // No quorum — fall back to policy
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('QUORUM_NOT_MET', `Best group has ${bestGroup.count}/${totalVotes} votes, need ${quorum}`));
+        }
+        catch (e) {
+            return (0, shared_1.err)((0, errors_js_1.continuityError)('CONSENSUS_FAILED', `Consensus failed: ${e instanceof Error ? e.message : String(e)}`));
+        }
+    }
+}
+exports.ConsensusAdjudicator = ConsensusAdjudicator;
+/* ── Internal helpers ── */
+/**
+ * Compare two candidates using total ordering.
+ * Returns > 0 if a wins, < 0 if b wins, 0 if tied (shouldn't happen with DID tiebreaker).
+ */
+function compareCandidates(a, aTier, b, bTier) {
+    // 1. Higher tier wins
+    const tierDiff = types_js_1.TRUST_TIER_RANK[aTier] - types_js_1.TRUST_TIER_RANK[bTier];
+    if (tierDiff !== 0)
+        return tierDiff;
+    // 2. Newer timestamp wins
+    const aTime = a.provenance?.timestamp ?? 0;
+    const bTime = b.provenance?.timestamp ?? 0;
+    if (aTime !== bTime)
+        return aTime - bTime;
+    // 3. Lexicographically lowest author DID wins (deterministic tiebreaker)
+    const aAuthor = a.provenance?.author ?? '';
+    const bAuthor = b.provenance?.author ?? '';
+    if (aAuthor !== bAuthor) {
+        // Lower DID wins — so if a < b, a wins (return > 0)
+        return aAuthor < bAuthor ? 1 : -1;
+    }
+    return 0;
+}
+function buildReason(winner, tier, candidateCount) {
+    const parts = [`tier=${tier}`];
+    if (winner.provenance) {
+        parts.push(`author=${winner.provenance.author.slice(0, 8)}...`);
+        parts.push(`ts=${winner.provenance.timestamp}`);
+    }
+    return `policy: selected from ${candidateCount} candidates (${parts.join(', ')})`;
+}
+function groupByValue(entries) {
+    const groups = new Map();
+    for (const entry of entries) {
+        const valueKey = canonicalValueKey(entry.value);
+        const group = groups.get(valueKey);
+        if (group) {
+            group.push(entry);
+        }
+        else {
+            groups.set(valueKey, [entry]);
+        }
+    }
+    return Array.from(groups.values()).map(entries => ({
+        entries,
+        count: entries.length,
+    }));
+}
+function canonicalValueKey(value) {
+    if (value === null)
+        return 'null';
+    if (value instanceof Uint8Array) {
+        let s = 'bytes:';
+        for (let i = 0; i < value.length; i++)
+            s += String.fromCharCode(value[i]);
+        return s;
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value, Object.keys(value).sort());
+    }
+    return `${typeof value}:${String(value)}`;
+}