@private.me/xcontinuity 2.1.0

package/dist/adjudicator.js

@@ -0,0 +1,184 @@
+/**
+ * @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.
+ */
+import { ok, err } from '@private.me/shared';
+import { TRUST_TIER_RANK } from './types.js';
+import { continuityError } from './errors.js';
+import { effectiveTier } from './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)
+ */
+export class PolicyAdjudicator {
+    resolve(key, candidates) {
+        if (candidates.length === 0) {
+            return err(continuityError('NO_CANDIDATES', `No candidates for key "${key}"`));
+        }
+        if (candidates.length === 1) {
+            return ok({ winner: candidates[0], reason: 'single candidate' });
+        }
+        let winner = candidates[0];
+        let winnerTier = effectiveTier(winner);
+        for (let i = 1; i < candidates.length; i++) {
+            const candidate = candidates[i];
+            const candidateTier = effectiveTier(candidate);
+            const comparison = compareCandidates(winner, winnerTier, candidate, candidateTier);
+            if (comparison < 0) {
+                winner = candidate;
+                winnerTier = candidateTier;
+            }
+        }
+        const reason = buildReason(winner, winnerTier, candidates.length);
+        return ok({ winner, reason });
+    }
+}
+/**
+ * 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).
+ */
+export 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 err(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 ok({
+                    winner: groupResult.value.winner,
+                    reason: `consensus: ${bestGroup.count}/${totalVotes} votes (quorum=${quorum})`,
+                });
+            }
+            // No quorum — fall back to policy
+            return err(continuityError('QUORUM_NOT_MET', `Best group has ${bestGroup.count}/${totalVotes} votes, need ${quorum}`));
+        }
+        catch (e) {
+            return err(continuityError('CONSENSUS_FAILED', `Consensus failed: ${e instanceof Error ? e.message : String(e)}`));
+        }
+    }
+}
+/* ── 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 = TRUST_TIER_RANK[aTier] - 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)}`;
+}

package/dist/cascade.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @private.me/xcontinuity — Cascade / Sub-Agent Architecture
+ *
+ * Enables parent-child session hierarchies where child sessions
+ * inherit trust context from their parent. Proves that v2.0.0's
+ * trust substrate API composes correctly in multi-agent patterns.
+ *
+ * @since 2.1.0
+ */
+import type { Result } from '@private.me/shared';
+import type { TrustTier, StateStore } from './types.js';
+import type { ContinuityError } from './errors.js';
+import { SessionManager } from './session.js';
+import { TrustStore } from './ratification.js';
+import type { MissionGuard } from './mission.js';
+import { EnforcementLoop } from './enforcement.js';
+/** How trust tiers propagate from parent to child sessions. */
+export type TrustPropagation = 'inherit' | 'downgrade' | 'isolate';
+/** Configuration for cascade trust behavior. */
+export interface CascadePolicy {
+    /** How parent trust tiers propagate to children. Default: 'inherit'. */
+    readonly propagation: TrustPropagation;
+    /** Maximum trust tier a child can achieve. Default: 'ratified'. */
+    readonly maxChildTier: TrustTier;
+    /** Whether children can escalate violations to the parent. Default: true. */
+    readonly escalateToParent: boolean;
+    /** Maximum depth of the cascade tree. Default: 5. */
+    readonly maxDepth: number;
+}
+/** Default cascade policy. */
+export declare const DEFAULT_CASCADE_POLICY: CascadePolicy;
+/** Tracks a child session within a cascade. */
+export interface CascadeChild {
+    readonly childId: string;
+    readonly session: SessionManager;
+    readonly trustStore: TrustStore;
+    readonly policy: CascadePolicy;
+    readonly depth: number;
+    readonly createdAt: number;
+}
+/** Escalation record from a child cascade. */
+export interface CascadeEscalation {
+    readonly childId: string;
+    readonly agentId: string;
+    readonly violationCount: number;
+    readonly timestamp: number;
+    readonly action: import('./types.js').ProposedAction;
+}
+/**
+ * CascadeSession wraps a SessionManager with parent-child hierarchy.
+ * Child sessions inherit trust context from their parent based on CascadePolicy.
+ */
+export declare class CascadeSession {
+    private readonly session;
+    private readonly trustStore;
+    private readonly missionGuard?;
+    private readonly enforcementLoop?;
+    private readonly children;
+    private readonly parentId?;
+    private readonly depth;
+    private readonly policy;
+    private readonly defaultMaxAge?;
+    private readonly escalations;
+    constructor(session: SessionManager, trustStore: TrustStore, options?: {
+        missionGuard?: MissionGuard;
+        enforcementLoop?: EnforcementLoop;
+        parentId?: string;
+        depth?: number;
+        policy?: CascadePolicy;
+        defaultMaxAge?: number;
+    });
+    /** Get the underlying session manager. */
+    getSession(): SessionManager;
+    /** Get the trust store for this cascade node. */
+    getTrustStore(): TrustStore;
+    /** Get the cascade depth (0 = root). */
+    getDepth(): number;
+    /** Get the parent session ID (undefined for root). */
+    getParentId(): string | undefined;
+    /** Get all child IDs. */
+    getChildIds(): string[];
+    /** Get a child by ID. */
+    getChild(childId: string): CascadeChild | undefined;
+    /** Get escalation records from child sessions. */
+    getEscalations(): readonly CascadeEscalation[];
+    /**
+     * Spawn a child session that inherits trust context from this parent.
+     *
+     * The child's trust store is populated based on the cascade policy:
+     * - 'inherit': Child receives parent's trust entries at their current tier.
+     * - 'downgrade': Child receives entries downgraded one tier level.
+     * - 'isolate': Child starts with an empty trust store.
+     */
+    spawnChild(childAgentId: string, store: StateStore, childPolicy?: Partial<CascadePolicy>): Result<CascadeSession, ContinuityError>;
+    /**
+     * Merge a child's trusted state back into the parent.
+     * Only entries at or above 'inherited' tier are merged.
+     * The child session is closed after merging.
+     */
+    mergeChild(childId: string): Result<number, ContinuityError>;
+    /**
+     * Close all children and then this session.
+     */
+    closeAll(): void;
+    /** Number of active children. */
+    get childCount(): number;
+    private propagateTier;
+    private tierRank;
+}
+/** Configuration for the SubAgentCoordinator. */
+export interface CoordinatorConfig {
+    /** Maximum number of concurrent sub-agents. Default: 10. */
+    readonly maxAgents: number;
+    /** Default cascade policy for spawned agents. */
+    readonly defaultPolicy: CascadePolicy;
+    /** Whether to auto-merge child state on completion. Default: false. */
+    readonly autoMerge: boolean;
+}
+/** Default coordinator configuration. */
+export declare const DEFAULT_COORDINATOR_CONFIG: CoordinatorConfig;
+/**
+ * SubAgentCoordinator manages the lifecycle of sub-agent sessions
+ * within a cascade hierarchy. It provides:
+ * - Spawning with trust delegation
+ * - State merging with enforcement checking
+ * - Lifecycle management (close, cleanup)
+ */
+export declare class SubAgentCoordinator {
+    private readonly root;
+    private readonly config;
+    private readonly activeAgents;
+    constructor(root: CascadeSession, config?: Partial<CoordinatorConfig>);
+    /** Get the root cascade session. */
+    getRoot(): CascadeSession;
+    /** Get the count of active sub-agents. */
+    get activeCount(): number;
+    /**
+     * Spawn a sub-agent with trust delegation from the root.
+     */
+    spawn(agentId: string, store: StateStore, policy?: Partial<CascadePolicy>): Result<CascadeSession, ContinuityError>;
+    /**
+     * Complete a sub-agent and optionally merge its state back into the root.
+     */
+    complete(childId: string): Result<number, ContinuityError>;
+    /**
+     * Merge a specific sub-agent's state into the root (manual merge).
+     */
+    merge(childId: string): Result<number, ContinuityError>;
+    /**
+     * Close all sub-agents and the root session.
+     */
+    shutdown(): void;
+    /**
+     * Get all active sub-agent IDs.
+     */
+    getActiveIds(): string[];
+}

package/dist/cascade.js

@@ -0,0 +1,323 @@
+/**
+ * @private.me/xcontinuity — Cascade / Sub-Agent Architecture
+ *
+ * Enables parent-child session hierarchies where child sessions
+ * inherit trust context from their parent. Proves that v2.0.0's
+ * trust substrate API composes correctly in multi-agent patterns.
+ *
+ * @since 2.1.0
+ */
+import { ok, err } from '@private.me/shared';
+import { continuityError } from './errors.js';
+import { SessionManager } from './session.js';
+import { TrustStore } from './ratification.js';
+import { EnforcementLoop } from './enforcement.js';
+/** Default cascade policy. */
+export const DEFAULT_CASCADE_POLICY = {
+    propagation: 'inherit',
+    maxChildTier: 'ratified',
+    escalateToParent: true,
+    maxDepth: 5,
+};
+/**
+ * CascadeSession wraps a SessionManager with parent-child hierarchy.
+ * Child sessions inherit trust context from their parent based on CascadePolicy.
+ */
+export class CascadeSession {
+    session;
+    trustStore;
+    missionGuard;
+    enforcementLoop;
+    children = new Map();
+    parentId;
+    depth;
+    policy;
+    defaultMaxAge;
+    escalations = [];
+    constructor(session, trustStore, options) {
+        this.session = session;
+        this.trustStore = trustStore;
+        this.missionGuard = options?.missionGuard;
+        this.enforcementLoop = options?.enforcementLoop;
+        this.parentId = options?.parentId;
+        this.depth = options?.depth ?? 0;
+        this.policy = options?.policy ?? DEFAULT_CASCADE_POLICY;
+        this.defaultMaxAge = options?.defaultMaxAge;
+    }
+    /** Get the underlying session manager. */
+    getSession() {
+        return this.session;
+    }
+    /** Get the trust store for this cascade node. */
+    getTrustStore() {
+        return this.trustStore;
+    }
+    /** Get the cascade depth (0 = root). */
+    getDepth() {
+        return this.depth;
+    }
+    /** Get the parent session ID (undefined for root). */
+    getParentId() {
+        return this.parentId;
+    }
+    /** Get all child IDs. */
+    getChildIds() {
+        return Array.from(this.children.keys());
+    }
+    /** Get a child by ID. */
+    getChild(childId) {
+        return this.children.get(childId);
+    }
+    /** Get escalation records from child sessions. */
+    getEscalations() {
+        return this.escalations;
+    }
+    /**
+     * Spawn a child session that inherits trust context from this parent.
+     *
+     * The child's trust store is populated based on the cascade policy:
+     * - 'inherit': Child receives parent's trust entries at their current tier.
+     * - 'downgrade': Child receives entries downgraded one tier level.
+     * - 'isolate': Child starts with an empty trust store.
+     */
+    spawnChild(childAgentId, store, childPolicy) {
+        const mergedPolicy = { ...this.policy, ...childPolicy };
+        const childDepth = this.depth + 1;
+        if (childDepth > mergedPolicy.maxDepth) {
+            return err(continuityError('CONSTRAINT_VIOLATION', `Cascade depth ${childDepth} exceeds maximum ${mergedPolicy.maxDepth}`));
+        }
+        // Create child trust store
+        const childTrustStore = new TrustStore({
+            defaultMaxAge: this.defaultMaxAge,
+        });
+        // Propagate trust entries from parent to child
+        if (mergedPolicy.propagation !== 'isolate') {
+            const parentEntries = this.trustStore.all();
+            const propagated = [];
+            for (const entry of parentEntries) {
+                const childTier = this.propagateTier(entry.tier, mergedPolicy);
+                if (childTier && this.tierRank(childTier) <= this.tierRank(mergedPolicy.maxChildTier)) {
+                    propagated.push({
+                        key: entry.key,
+                        value: entry.value,
+                        provenance: entry.provenance,
+                        tier: childTier,
+                        contradictions: [],
+                        maxAge: entry.maxAge,
+                        ratifiedAt: childTier === 'ratified' ? entry.ratifiedAt : undefined,
+                    });
+                }
+            }
+            if (propagated.length > 0) {
+                childTrustStore.restore(propagated);
+            }
+        }
+        // Create child enforcement loop that escalates to parent
+        let childEnforcement;
+        if (this.missionGuard) {
+            const escalateToParent = mergedPolicy.escalateToParent;
+            childEnforcement = new EnforcementLoop(this.missionGuard, {
+                escalationThreshold: 3,
+                onEscalate: escalateToParent
+                    ? (result) => {
+                        this.escalations.push({
+                            childId: childAgentId,
+                            agentId: result.action.author,
+                            violationCount: result.violationCount ?? 0,
+                            timestamp: Date.now(),
+                            action: result.action,
+                        });
+                    }
+                    : undefined,
+            });
+        }
+        // Create child session
+        const childConfig = {
+            agentId: childAgentId,
+            store,
+            trustStore: childTrustStore,
+            missionGuard: this.missionGuard,
+            enforcementLoop: childEnforcement,
+        };
+        const childSession = SessionManager.create(childConfig);
+        const sessionId = childSession.session.sessionId;
+        const cascadeChild = new CascadeSession(childSession, childTrustStore, {
+            missionGuard: this.missionGuard,
+            enforcementLoop: childEnforcement,
+            parentId: this.session.session.sessionId,
+            depth: childDepth,
+            policy: mergedPolicy,
+            defaultMaxAge: this.defaultMaxAge,
+        });
+        this.children.set(sessionId, {
+            childId: sessionId,
+            session: childSession,
+            trustStore: childTrustStore,
+            policy: mergedPolicy,
+            depth: childDepth,
+            createdAt: Date.now(),
+        });
+        return ok(cascadeChild);
+    }
+    /**
+     * Merge a child's trusted state back into the parent.
+     * Only entries at or above 'inherited' tier are merged.
+     * The child session is closed after merging.
+     */
+    mergeChild(childId) {
+        const child = this.children.get(childId);
+        if (!child) {
+            return err(continuityError('SNAPSHOT_NOT_FOUND', `Child session "${childId}" not found`));
+        }
+        let merged = 0;
+        const childEntries = child.trustStore.all();
+        for (const entry of childEntries) {
+            if (this.tierRank(entry.tier) >= this.tierRank('inherited')) {
+                // Check parent enforcement before merging
+                if (this.enforcementLoop) {
+                    const check = this.enforcementLoop.check({
+                        author: child.session.session.agentId,
+                        type: 'write',
+                        key: entry.key,
+                        value: entry.value,
+                    });
+                    if (check.ok && check.value.decision !== 'allow') {
+                        continue; // Skip entries that violate parent constraints
+                    }
+                }
+                this.trustStore.write(entry.key, entry.value, entry.provenance);
+                merged++;
+            }
+        }
+        // Close child session
+        child.session.close();
+        this.children.delete(childId);
+        return ok(merged);
+    }
+    /**
+     * Close all children and then this session.
+     */
+    closeAll() {
+        for (const [, child] of this.children) {
+            child.session.close();
+        }
+        this.children.clear();
+        this.session.close();
+    }
+    /** Number of active children. */
+    get childCount() {
+        return this.children.size;
+    }
+    propagateTier(parentTier, policy) {
+        if (policy.propagation === 'isolate')
+            return null;
+        if (policy.propagation === 'inherit')
+            return parentTier;
+        // Downgrade: ratified -> inherited, inherited -> quarantined, quarantined -> null
+        if (parentTier === 'ratified')
+            return 'inherited';
+        if (parentTier === 'inherited')
+            return 'quarantined';
+        return null; // quarantined cannot be downgraded further
+    }
+    tierRank(tier) {
+        const ranks = {
+            ratified: 3,
+            inherited: 2,
+            quarantined: 1,
+        };
+        return ranks[tier];
+    }
+}
+/** Default coordinator configuration. */
+export const DEFAULT_COORDINATOR_CONFIG = {
+    maxAgents: 10,
+    defaultPolicy: DEFAULT_CASCADE_POLICY,
+    autoMerge: false,
+};
+/**
+ * SubAgentCoordinator manages the lifecycle of sub-agent sessions
+ * within a cascade hierarchy. It provides:
+ * - Spawning with trust delegation
+ * - State merging with enforcement checking
+ * - Lifecycle management (close, cleanup)
+ */
+export class SubAgentCoordinator {
+    root;
+    config;
+    activeAgents = new Map();
+    constructor(root, config) {
+        this.root = root;
+        this.config = { ...DEFAULT_COORDINATOR_CONFIG, ...config };
+    }
+    /** Get the root cascade session. */
+    getRoot() {
+        return this.root;
+    }
+    /** Get the count of active sub-agents. */
+    get activeCount() {
+        return this.activeAgents.size;
+    }
+    /**
+     * Spawn a sub-agent with trust delegation from the root.
+     */
+    spawn(agentId, store, policy) {
+        if (this.activeAgents.size >= this.config.maxAgents) {
+            return err(continuityError('CONSTRAINT_VIOLATION', `Maximum sub-agents (${this.config.maxAgents}) reached`));
+        }
+        const mergedPolicy = { ...this.config.defaultPolicy, ...policy };
+        const result = this.root.spawnChild(agentId, store, mergedPolicy);
+        if (!result.ok)
+            return result;
+        const child = result.value;
+        const childId = child.getSession().session.sessionId;
+        this.activeAgents.set(childId, child);
+        return ok(child);
+    }
+    /**
+     * Complete a sub-agent and optionally merge its state back into the root.
+     */
+    complete(childId) {
+        const child = this.activeAgents.get(childId);
+        if (!child) {
+            return err(continuityError('SNAPSHOT_NOT_FOUND', `Sub-agent "${childId}" not found in coordinator`));
+        }
+        let merged = 0;
+        if (this.config.autoMerge) {
+            const mergeResult = this.root.mergeChild(childId);
+            if (mergeResult.ok)
+                merged = mergeResult.value;
+        }
+        else {
+            child.getSession().close();
+        }
+        this.activeAgents.delete(childId);
+        return ok(merged);
+    }
+    /**
+     * Merge a specific sub-agent's state into the root (manual merge).
+     */
+    merge(childId) {
+        if (!this.activeAgents.has(childId)) {
+            return err(continuityError('SNAPSHOT_NOT_FOUND', `Sub-agent "${childId}" not found in coordinator`));
+        }
+        const result = this.root.mergeChild(childId);
+        if (result.ok) {
+            this.activeAgents.delete(childId);
+        }
+        return result;
+    }
+    /**
+     * Close all sub-agents and the root session.
+     */
+    shutdown() {
+        this.activeAgents.clear();
+        this.root.closeAll();
+    }
+    /**
+     * Get all active sub-agent IDs.
+     */
+    getActiveIds() {
+        return Array.from(this.activeAgents.keys());
+    }
+}