@private.me/xcontinuity 2.1.0

package/dist/trust.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @private.me/xcontinuity — Trust Tier Management
+ *
+ * Assigns and manages trust tiers for memory entries based on
+ * provenance verification, contradiction history, and temporal decay.
+ *
+ * Three tiers:
+ *   ratified (3)  — signed + verified by a known author
+ *   inherited (2) — unsigned from a trusted source, or decayed from ratified
+ *   quarantined (1) — unverified, contradicted, or failed verification
+ */
+import type { MemoryEntry, ProvenanceRecord, TrustTier } from './types.js';
+import { TRUST_TIER_RANK, DEFAULT_MAX_AGE } from './types.js';
+/**
+ * Determine the baseline trust tier for an entry based on its provenance.
+ *
+ * @param provenance - The provenance record (if present)
+ * @param signatureVerified - Whether the Ed25519 signature was verified
+ * @returns The baseline trust tier
+ */
+export declare function baselineTier(provenance: ProvenanceRecord | undefined, signatureVerified: boolean): TrustTier;
+/**
+ * Apply contradiction-based downgrade to a trust tier.
+ *
+ * Rules:
+ * - 0 contradictions: no change
+ * - 1+ contradictions on inherited: downgrade to quarantined
+ * - 1+ contradictions on ratified: downgrade to inherited
+ * - quarantined stays quarantined regardless
+ *
+ * @param currentTier - The current trust tier
+ * @param contradictionCount - Number of active contradictions
+ * @returns The adjusted trust tier
+ */
+export declare function applyContradictionDowngrade(currentTier: TrustTier, contradictionCount: number): TrustTier;
+/**
+ * Check whether a trust tier has decayed past its maxAge TTL.
+ *
+ * A ratified entry past its maxAge downgrades to inherited.
+ * Inherited and quarantined entries are not affected by decay.
+ *
+ * @param entry - The memory entry to check
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns true if the entry has expired and should be downgraded
+ */
+export declare function isDecayed(entry: MemoryEntry, now?: number): boolean;
+/**
+ * Apply temporal decay to a trust tier.
+ *
+ * @param entry - The memory entry to evaluate
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns The effective trust tier after decay
+ */
+export declare function applyDecay(entry: MemoryEntry, now?: number): TrustTier;
+/**
+ * Get the effective trust tier for an entry, considering both
+ * contradictions and temporal decay.
+ *
+ * @param entry - The memory entry
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns The effective trust tier
+ */
+export declare function effectiveTier(entry: MemoryEntry, now?: number): TrustTier;
+/**
+ * Compare two trust tiers. Returns positive if a > b, negative if a < b, 0 if equal.
+ */
+export declare function compareTiers(a: TrustTier, b: TrustTier): number;
+/**
+ * Check if tier `a` is strictly more trusted than tier `b`.
+ */
+export declare function isMoreTrusted(a: TrustTier, b: TrustTier): boolean;
+/**
+ * Get the least trusted tier from a list.
+ */
+export declare function leastTrusted(...tiers: TrustTier[]): TrustTier;
+export { TRUST_TIER_RANK, DEFAULT_MAX_AGE };

package/dist/trust.js

@@ -0,0 +1,121 @@
+/**
+ * @private.me/xcontinuity — Trust Tier Management
+ *
+ * Assigns and manages trust tiers for memory entries based on
+ * provenance verification, contradiction history, and temporal decay.
+ *
+ * Three tiers:
+ *   ratified (3)  — signed + verified by a known author
+ *   inherited (2) — unsigned from a trusted source, or decayed from ratified
+ *   quarantined (1) — unverified, contradicted, or failed verification
+ */
+import { TRUST_TIER_RANK, DEFAULT_MAX_AGE } from './types.js';
+/**
+ * Determine the baseline trust tier for an entry based on its provenance.
+ *
+ * @param provenance - The provenance record (if present)
+ * @param signatureVerified - Whether the Ed25519 signature was verified
+ * @returns The baseline trust tier
+ */
+export function baselineTier(provenance, signatureVerified) {
+    if (!provenance)
+        return 'inherited';
+    if (signatureVerified)
+        return 'ratified';
+    return 'quarantined';
+}
+/**
+ * Apply contradiction-based downgrade to a trust tier.
+ *
+ * Rules:
+ * - 0 contradictions: no change
+ * - 1+ contradictions on inherited: downgrade to quarantined
+ * - 1+ contradictions on ratified: downgrade to inherited
+ * - quarantined stays quarantined regardless
+ *
+ * @param currentTier - The current trust tier
+ * @param contradictionCount - Number of active contradictions
+ * @returns The adjusted trust tier
+ */
+export function applyContradictionDowngrade(currentTier, contradictionCount) {
+    if (contradictionCount <= 0)
+        return currentTier;
+    switch (currentTier) {
+        case 'ratified':
+            return 'inherited';
+        case 'inherited':
+            return 'quarantined';
+        case 'quarantined':
+            return 'quarantined';
+    }
+}
+/**
+ * Check whether a trust tier has decayed past its maxAge TTL.
+ *
+ * A ratified entry past its maxAge downgrades to inherited.
+ * Inherited and quarantined entries are not affected by decay.
+ *
+ * @param entry - The memory entry to check
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns true if the entry has expired and should be downgraded
+ */
+export function isDecayed(entry, now) {
+    if (entry.tier !== 'ratified')
+        return false;
+    if (entry.maxAge === undefined)
+        return false;
+    if (!Number.isFinite(entry.maxAge))
+        return false; // Infinity = no decay
+    const ratifiedAt = entry.ratifiedAt ?? entry.provenance?.timestamp ?? 0;
+    const elapsed = (now ?? Date.now()) - ratifiedAt;
+    return elapsed > entry.maxAge;
+}
+/**
+ * Apply temporal decay to a trust tier.
+ *
+ * @param entry - The memory entry to evaluate
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns The effective trust tier after decay
+ */
+export function applyDecay(entry, now) {
+    if (isDecayed(entry, now))
+        return 'inherited';
+    return entry.tier;
+}
+/**
+ * Get the effective trust tier for an entry, considering both
+ * contradictions and temporal decay.
+ *
+ * @param entry - The memory entry
+ * @param now - Current timestamp (ms). Defaults to Date.now().
+ * @returns The effective trust tier
+ */
+export function effectiveTier(entry, now) {
+    const afterDecay = applyDecay(entry, now);
+    return applyContradictionDowngrade(afterDecay, entry.contradictions.length);
+}
+/**
+ * Compare two trust tiers. Returns positive if a > b, negative if a < b, 0 if equal.
+ */
+export function compareTiers(a, b) {
+    return TRUST_TIER_RANK[a] - TRUST_TIER_RANK[b];
+}
+/**
+ * Check if tier `a` is strictly more trusted than tier `b`.
+ */
+export function isMoreTrusted(a, b) {
+    return TRUST_TIER_RANK[a] > TRUST_TIER_RANK[b];
+}
+/**
+ * Get the least trusted tier from a list.
+ */
+export function leastTrusted(...tiers) {
+    let min = 'ratified';
+    for (const t of tiers) {
+        if (TRUST_TIER_RANK[t] < TRUST_TIER_RANK[min]) {
+            min = t;
+        }
+    }
+    return min;
+}
+export { TRUST_TIER_RANK, DEFAULT_MAX_AGE };

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @private.me/xcontinuity — Type definitions and constants
+ *
+ * All types, interfaces, TLV type codes, and constants for the
+ * cryptographic state continuity substrate.
+ */
+export declare const CONTINUITY_TLV: {
+    /** State metadata header */
+    readonly STATE_METADATA: 128;
+    /** Agent identifier */
+    readonly AGENT_ID: 129;
+    /** Session identifier */
+    readonly SESSION_ID: 130;
+    /** Sequence number (uint32) */
+    readonly SEQUENCE_NUMBER: 131;
+    /** Timestamp (float64 ms) */
+    readonly TIMESTAMP: 132;
+    /** Tag string */
+    readonly TAG: 133;
+    /** State key-value entry */
+    readonly STATE_ENTRY: 134;
+    /** Key name (UTF-8) */
+    readonly ENTRY_KEY: 135;
+    /** Entry value (typed) */
+    readonly ENTRY_VALUE: 136;
+    /** Description string */
+    readonly DESCRIPTION: 137;
+    /** Checksum (SHA-256) */
+    readonly CHECKSUM: 138;
+};
+export type ContinuityTlvType = (typeof CONTINUITY_TLV)[keyof typeof CONTINUITY_TLV];
+export declare const VALUE_TYPE: {
+    readonly STRING: 1;
+    readonly NUMBER: 2;
+    readonly BOOLEAN: 3;
+    readonly BYTES: 4;
+    readonly NULL: 5;
+    readonly JSON: 6;
+};
+export type ValueTypeCode = (typeof VALUE_TYPE)[keyof typeof VALUE_TYPE];
+/** Primitive and structured values storable in agent state. */
+export type StateValue = string | number | boolean | Uint8Array | null | Record<string, unknown>;
+/** Flat key-value map representing agent state at a point in time. */
+export type AgentState = Record<string, StateValue>;
+/** Metadata attached to a state snapshot. */
+export interface StateMetadata {
+    readonly agentId: string;
+    readonly sessionId: string;
+    readonly sequenceNumber: number;
+    readonly createdAt: number;
+    readonly description?: string;
+    readonly tags: readonly string[];
+}
+/** A serialized state snapshot with integrity checksum. */
+export interface StateSnapshot {
+    readonly stateId: string;
+    readonly metadata: StateMetadata;
+    readonly serializedBytes: Uint8Array;
+    readonly checksum: Uint8Array;
+}
+/** Configuration for XorIDA threshold splitting. */
+export interface SplitConfig {
+    /** Total number of shares to produce. Default: 3. */
+    readonly n: number;
+    /** Minimum shares needed for reconstruction. Default: 2. */
+    readonly k: number;
+}
+/** Default split configuration: 3-of-2 threshold. */
+export declare const DEFAULT_SPLIT_CONFIG: SplitConfig;
+/** A single XorIDA share of a state snapshot. */
+export interface StateShare {
+    readonly stateId: string;
+    readonly index: number;
+    readonly n: number;
+    readonly k: number;
+    readonly data: Uint8Array;
+    readonly hmacKey: Uint8Array;
+    readonly hmacSignature: Uint8Array;
+}
+/** The complete split result containing all shares and metadata. */
+export interface SplitState {
+    readonly stateId: string;
+    readonly metadata: StateMetadata;
+    readonly shares: readonly StateShare[];
+    readonly n: number;
+    readonly k: number;
+    /** The padded byte length used for this split (needed for incremental updates). */
+    readonly paddedLength: number;
+}
+/** A byte-level delta between two padded state snapshots. */
+export interface StateDelta {
+    readonly fromStateId: string;
+    readonly toStateId: string;
+    readonly deltaBytes: Uint8Array;
+    readonly fromChecksum: Uint8Array;
+    readonly toChecksum: Uint8Array;
+}
+/** Session status lifecycle: active -> suspended -> active (resume), active -> closed (terminal). */
+export type SessionStatus = 'active' | 'suspended' | 'closed';
+/** A continuity session tracking agent state across time. */
+export interface ContinuitySession {
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly status: SessionStatus;
+    readonly splitConfig: SplitConfig;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly snapshotCount: number;
+}
+/** Configuration for creating a new session. */
+export interface SessionConfig {
+    readonly agentId: string;
+    readonly store: StateStore;
+    readonly splitConfig?: SplitConfig;
+}
+/** An entry in the ordered state history. */
+export interface ChronicleEntry {
+    readonly stateId: string;
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly timestamp: number;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly parentStateId?: string;
+}
+/** Query filters for chronicle entries. */
+export interface ChronicleQuery {
+    readonly sessionId?: string;
+    readonly after?: number;
+    readonly before?: number;
+    readonly tags?: readonly string[];
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** Async storage backend for XorIDA-split state. */
+export interface StateStore {
+    putShares(splitState: SplitState): Promise<void>;
+    getShares(stateId: string): Promise<SplitState | null>;
+    deleteShares(stateId: string): Promise<void>;
+    listStateIds(): Promise<string[]>;
+}
+/** A single entry in the runtime memory layer. */
+export interface RuntimeEntry {
+    readonly key: string;
+    readonly value: StateValue;
+    readonly accessCount: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/** Configuration for the runtime memory layer. */
+export interface RuntimeMemoryConfig {
+    /** Maximum number of entries before LRU eviction. Default: 1000. */
+    readonly maxEntries: number;
+}
+export declare const DEFAULT_RUNTIME_MEMORY_CONFIG: RuntimeMemoryConfig;
+/**
+ * Ed25519 public key identifier for an agent or authority.
+ * Encoded as base64url string of the 32-byte public key.
+ */
+export type AuthorRef = string;
+/** Trust classification for a memory entry. */
+export type TrustTier = 'ratified' | 'inherited' | 'quarantined';
+/** Numeric ranking for trust tier comparison (higher = more trusted). */
+export declare const TRUST_TIER_RANK: Record<TrustTier, number>;
+/** Cryptographic provenance record attached to a memory entry. */
+export interface ProvenanceRecord {
+    /** Author who created/signed this entry. */
+    readonly author: AuthorRef;
+    /** Timestamp of creation (ms since epoch). */
+    readonly timestamp: number;
+    /** Ed25519 signature over canonical entry bytes. */
+    readonly signature: Uint8Array;
+    /** SHA-256 hash of the parent entry (chain integrity). */
+    readonly parentHash?: Uint8Array;
+}
+/** A memory entry with trust metadata. */
+export interface MemoryEntry {
+    /** Entry key. */
+    readonly key: string;
+    /** Entry value. */
+    readonly value: StateValue;
+    /** Cryptographic provenance (present if signed). */
+    readonly provenance?: ProvenanceRecord;
+    /** Current trust tier. */
+    readonly tier: TrustTier;
+    /** Keys of contradicting entries detected by chronicle. */
+    readonly contradictions: readonly string[];
+    /** Optional TTL — entry auto-downgrades to inherited after maxAge ms. */
+    readonly maxAge?: number;
+    /** Timestamp when this entry was last verified/ratified. */
+    readonly ratifiedAt?: number;
+}
+/** A tracked belief with confidence and sourcing. */
+export interface TrackedBelief {
+    /** The claim being tracked. */
+    readonly claim: string;
+    /** Confidence level 0.0–1.0. */
+    readonly confidence: number;
+    /** AuthorRef of the source agent. */
+    readonly source: AuthorRef;
+    /** Current trust tier. */
+    readonly tier: TrustTier;
+}
+/** Default TTL for trust tier decay (30 days in ms). */
+export declare const DEFAULT_MAX_AGE: number;
+/** Resolution result from an adjudicator. */
+export interface AdjudicatorResult {
+    /** The winning entry. */
+    readonly winner: MemoryEntry;
+    /** Reason for the resolution. */
+    readonly reason: string;
+}
+/** View from a single agent for consensus adjudication. */
+export interface AgentView {
+    /** The agent providing this view. */
+    readonly author: AuthorRef;
+    /** The entry this agent holds for the contested key. */
+    readonly entry: MemoryEntry;
+}
+/** A human-anchored mission record with crypto-gated authority. */
+export interface MissionRecord {
+    /** Unique mission identifier. */
+    readonly missionId: string;
+    /** Human-readable goal description. */
+    readonly goal: string;
+    /** AuthorRef of the human authority who signed this mission. */
+    readonly authority: AuthorRef;
+    /** Ed25519 signature over canonical mission bytes. */
+    readonly signature: Uint8Array;
+    /** Mission creation timestamp (ms since epoch). */
+    readonly issuedAt: number;
+    /** Mission expiry timestamp (ms since epoch). Undefined = no expiry. */
+    readonly expiresAt?: number;
+    /** Scope tags limiting what this mission authorizes. */
+    readonly scopes: readonly string[];
+}
+/** A hard constraint that evaluates actions against mission boundaries. */
+export interface HardConstraint {
+    /** Unique constraint identifier. */
+    readonly constraintId: string;
+    /** Human-readable description of the constraint. */
+    readonly description: string;
+    /** Evaluate whether an action violates this constraint. */
+    evaluate(action: ProposedAction): ConstraintResult;
+}
+/** An action proposed by an agent, subject to constraint evaluation. */
+export interface ProposedAction {
+    /** The agent proposing the action. */
+    readonly author: AuthorRef;
+    /** Action type (write, delete, ratify, etc.). */
+    readonly type: string;
+    /** Target key being acted on. */
+    readonly key: string;
+    /** Proposed value (for write actions). */
+    readonly value?: StateValue;
+    /** Additional metadata. */
+    readonly metadata?: Record<string, unknown>;
+}
+/** Result of constraint evaluation. */
+export interface ConstraintResult {
+    /** Whether the action is allowed. */
+    readonly allowed: boolean;
+    /** Reason for denial (when allowed=false). */
+    readonly reason?: string;
+    /** Suggested alternative action (for rewrite). */
+    readonly suggestion?: ProposedAction;
+}
+/** Enforcement decision for a proposed action. */
+export type EnforcementDecision = 'allow' | 'reject' | 'rewrite' | 'escalate';
+/** Result from the enforcement loop. */
+export interface EnforcementResult {
+    /** The decision. */
+    readonly decision: EnforcementDecision;
+    /** The original action. */
+    readonly action: ProposedAction;
+    /** Reason for the decision (when not 'allow'). */
+    readonly reason?: string;
+    /** Rewritten action (when decision is 'rewrite'). */
+    readonly rewrittenAction?: ProposedAction;
+    /** Cumulative violation count for this agent (when decision is 'escalate'). */
+    readonly violationCount?: number;
+}
+/** Configuration for the enforcement loop. */
+export interface EnforcementConfig {
+    /** Number of violations before escalation. Default: 3. */
+    readonly escalationThreshold: number;
+    /** Callback invoked on escalation. */
+    readonly onEscalate?: (result: EnforcementResult) => void;
+}
+export declare const DEFAULT_ENFORCEMENT_CONFIG: EnforcementConfig;
+/** Event types emitted by TrustStore. */
+export type TrustStoreEventType = 'change' | 'contradiction' | 'tierChange' | 'escalation';
+/** Payload for a 'change' event. */
+export interface ChangeEvent {
+    readonly key: string;
+    readonly oldEntry?: MemoryEntry;
+    readonly newEntry: MemoryEntry;
+}
+/** Payload for a 'contradiction' event. */
+export interface ContradictionEvent {
+    readonly key: string;
+    readonly existing: MemoryEntry;
+    readonly incoming: MemoryEntry;
+}
+/** Payload for a 'tierChange' event. */
+export interface TierChangeEvent {
+    readonly key: string;
+    readonly oldTier: TrustTier;
+    readonly newTier: TrustTier;
+    readonly reason: string;
+}
+/** Payload for an 'escalation' event. */
+export interface EscalationEvent {
+    readonly action: ProposedAction;
+    readonly violationCount: number;
+}
+/** Union of all TrustStore event payloads. */
+export type TrustStoreEvent = ChangeEvent | ContradictionEvent | TierChangeEvent | EscalationEvent;
+/** TrustStore event listener callback. */
+export type TrustStoreListener<T extends TrustStoreEvent = TrustStoreEvent> = (event: T) => void;

package/dist/types.js

@@ -0,0 +1,56 @@
+/**
+ * @private.me/xcontinuity — Type definitions and constants
+ *
+ * All types, interfaces, TLV type codes, and constants for the
+ * cryptographic state continuity substrate.
+ */
+/* ── TLV Type Codes (0x80+ to avoid collision with shared TLV_TYPE 0x01-0x0d) ── */
+export const CONTINUITY_TLV = {
+    /** State metadata header */
+    STATE_METADATA: 0x80,
+    /** Agent identifier */
+    AGENT_ID: 0x81,
+    /** Session identifier */
+    SESSION_ID: 0x82,
+    /** Sequence number (uint32) */
+    SEQUENCE_NUMBER: 0x83,
+    /** Timestamp (float64 ms) */
+    TIMESTAMP: 0x84,
+    /** Tag string */
+    TAG: 0x85,
+    /** State key-value entry */
+    STATE_ENTRY: 0x86,
+    /** Key name (UTF-8) */
+    ENTRY_KEY: 0x87,
+    /** Entry value (typed) */
+    ENTRY_VALUE: 0x88,
+    /** Description string */
+    DESCRIPTION: 0x89,
+    /** Checksum (SHA-256) */
+    CHECKSUM: 0x8a,
+};
+/* ── Value Type Markers ── */
+export const VALUE_TYPE = {
+    STRING: 0x01,
+    NUMBER: 0x02,
+    BOOLEAN: 0x03,
+    BYTES: 0x04,
+    NULL: 0x05,
+    JSON: 0x06,
+};
+/** Default split configuration: 3-of-2 threshold. */
+export const DEFAULT_SPLIT_CONFIG = { n: 3, k: 2 };
+export const DEFAULT_RUNTIME_MEMORY_CONFIG = {
+    maxEntries: 1000,
+};
+/** Numeric ranking for trust tier comparison (higher = more trusted). */
+export const TRUST_TIER_RANK = {
+    ratified: 3,
+    inherited: 2,
+    quarantined: 1,
+};
+/** Default TTL for trust tier decay (30 days in ms). */
+export const DEFAULT_MAX_AGE = 30 * 24 * 60 * 60 * 1000;
+export const DEFAULT_ENFORCEMENT_CONFIG = {
+    escalationThreshold: 3,
+};

package/llms.txt

@@ -0,0 +1,43 @@
+# @private.me/xcontinuity — LLM Context
+
+> Cryptographic state continuity for AI agents — Reverse-XorIDA with trust substrate, provenance, and enforcement
+
+## Overview
+
+xcontinuity v2.0.0 provides cryptographic state continuity with a trust substrate for AI agents. Core primitive: Reverse-XorIDA exploits GF(2) linearity for O(delta) incremental state updates. Trust substrate adds Ed25519 provenance, trust tiers with TTL decay, conflict adjudication, mission-anchored enforcement, and ratification.
+
+## Key APIs
+
+- `SessionManager.create(config)` — Create session (optional trust substrate integration)
+- `session.updateState(patch)` — Merge patch (routes through enforcement + trust store if configured)
+- `session.snapshot(description?, tags?)` — Persist state as XorIDA shares
+- `session.restore(stateId)` — Reconstruct state from shares
+- `session.suspend()` / `session.resume()` — Pause and resume sessions
+- `TrustStore` — Trust-annotated entries with write/ratify/restore/hypothesisMode
+- `generateSigningKeyPair()` / `signEntry()` / `verifyEntry()` — Ed25519 provenance
+- `MissionGuard` — Human-anchored constraint evaluation
+- `EnforcementLoop` — Reject/rewrite/escalate with violation tracking
+- `PolicyAdjudicator` / `ConsensusAdjudicator` — Deterministic conflict resolution
+- `undoDelta` / `branchState` / `squashDeltas` — Algebraic extensions over GF(2)
+- `blindUpdateShare` / `refreshShares` / `blindEqual` — Zero-knowledge share operations
+- `Chronicle` — Ordered state history with contradiction detection
+
+## Trust Tiers
+
+ratified (signed + verified) → inherited (unsigned or decayed) → quarantined (invalid signature)
+TTL decay: ratified entries auto-downgrade to inherited after configurable maxAge (default 30 days)
+
+## Dependencies
+
+- @private.me/shared (Result<T,E>, ok(), err())
+- @private.me/crypto (XorIDA, HMAC, padding, UUID, base64)
+- Web Crypto API (Ed25519 — zero external crypto dependencies)
+
+## Error Handling
+
+All fallible functions return `Result<T, ContinuityError>`. Check `result.ok` before accessing `result.value`. 23 structured error codes across 7 families.
+
+## Resources
+
+- npm: https://npmjs.com/package/@private.me/xcontinuity
+- GitHub: https://github.com/xail-io/xail/tree/main/packages/xcontinuity