@private.me/xcontinuity 2.1.0

package/dist/memory-session.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @private.me/xcontinuity — Session Memory Layer
+ *
+ * Orchestration layer over serializer + reverse-xorida + store.
+ * Maintains lastSplitState for incremental updates.
+ */
+import type { Result } from '@private.me/shared';
+import type { AgentState, StateMetadata, StateSnapshot, SplitState, SplitConfig, StateStore } from './types.js';
+import type { ContinuityError } from './errors.js';
+export declare class SessionMemory {
+    private lastSplitState;
+    private lastSnapshot;
+    private readonly store;
+    private readonly splitConfig;
+    constructor(store: StateStore, splitConfig?: SplitConfig);
+    /**
+     * Save agent state: serialize, split (incremental if possible), persist to store.
+     *
+     * @param state - Agent state to persist
+     * @param metadata - State metadata
+     * @returns The state snapshot (with stateId for later retrieval)
+     */
+    save(state: AgentState, metadata: StateMetadata): Promise<Result<StateSnapshot, ContinuityError>>;
+    /**
+     * Load agent state from store by stateId.
+     * If no stateId provided, uses the last saved state.
+     *
+     * @param stateId - Optional state ID to load (defaults to last saved)
+     * @returns Reconstructed AgentState
+     */
+    load(stateId?: string): Promise<Result<AgentState, ContinuityError>>;
+    /** Get the last split state (for inspection/testing). */
+    getLastSplitState(): SplitState | null;
+    /** Get the last snapshot (for inspection/testing). */
+    getLastSnapshot(): StateSnapshot | null;
+    /** Reset internal tracking state. */
+    reset(): void;
+}

package/dist/memory-session.js

@@ -0,0 +1,97 @@
+/**
+ * @private.me/xcontinuity — Session Memory Layer
+ *
+ * Orchestration layer over serializer + reverse-xorida + store.
+ * Maintains lastSplitState for incremental updates.
+ */
+import { ok, err } from '@private.me/shared';
+import { DEFAULT_SPLIT_CONFIG } from './types.js';
+import { continuityError } from './errors.js';
+import { serializeState, deserializeState } from './state-serializer.js';
+import { splitState, reconstructState, incrementalUpdate } from './reverse-xorida.js';
+export class SessionMemory {
+    lastSplitState = null;
+    lastSnapshot = null;
+    store;
+    splitConfig;
+    constructor(store, splitConfig = DEFAULT_SPLIT_CONFIG) {
+        this.store = store;
+        this.splitConfig = splitConfig;
+    }
+    /**
+     * Save agent state: serialize, split (incremental if possible), persist to store.
+     *
+     * @param state - Agent state to persist
+     * @param metadata - State metadata
+     * @returns The state snapshot (with stateId for later retrieval)
+     */
+    async save(state, metadata) {
+        // Serialize
+        const serResult = await serializeState(state, metadata);
+        if (!serResult.ok)
+            return serResult;
+        const snapshot = serResult.value;
+        // Split (incremental if we have a previous split)
+        let splitResult;
+        if (this.lastSplitState && this.lastSnapshot) {
+            splitResult = await incrementalUpdate(this.lastSplitState, this.lastSnapshot, snapshot);
+        }
+        else {
+            splitResult = await splitState(snapshot, this.splitConfig);
+        }
+        if (!splitResult.ok)
+            return splitResult;
+        // Persist to store
+        await this.store.putShares(splitResult.value);
+        // Update tracking
+        this.lastSplitState = splitResult.value;
+        this.lastSnapshot = snapshot;
+        return ok(snapshot);
+    }
+    /**
+     * Load agent state from store by stateId.
+     * If no stateId provided, uses the last saved state.
+     *
+     * @param stateId - Optional state ID to load (defaults to last saved)
+     * @returns Reconstructed AgentState
+     */
+    async load(stateId) {
+        const targetId = stateId ?? this.lastSplitState?.stateId;
+        if (!targetId) {
+            return err(continuityError('NO_SNAPSHOTS', 'No state ID provided and no previous save'));
+        }
+        const splitState = await this.store.getShares(targetId);
+        if (!splitState) {
+            return err(continuityError('SNAPSHOT_NOT_FOUND', `State ${targetId} not found in store`));
+        }
+        // Reconstruct from shares
+        const reconResult = await reconstructState(splitState.shares);
+        if (!reconResult.ok)
+            return reconResult;
+        // Deserialize the snapshot
+        const snapshot = {
+            stateId: reconResult.value.stateId,
+            metadata: splitState.metadata,
+            serializedBytes: reconResult.value.serializedBytes,
+            checksum: new Uint8Array(0), // Will be recomputed during deserialization
+        };
+        // Compute fresh checksum for verification
+        const { computeChecksum } = await import('./state-serializer.js');
+        const freshChecksum = await computeChecksum(reconResult.value.serializedBytes);
+        const verifiedSnapshot = { ...snapshot, checksum: freshChecksum };
+        return deserializeState(verifiedSnapshot);
+    }
+    /** Get the last split state (for inspection/testing). */
+    getLastSplitState() {
+        return this.lastSplitState;
+    }
+    /** Get the last snapshot (for inspection/testing). */
+    getLastSnapshot() {
+        return this.lastSnapshot;
+    }
+    /** Reset internal tracking state. */
+    reset() {
+        this.lastSplitState = null;
+        this.lastSnapshot = null;
+    }
+}

package/dist/mission.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @private.me/xcontinuity — Mission (Human-Anchored Goals)
+ *
+ * Ensures AI agents operate within human-defined boundaries.
+ *
+ * Components:
+ *   MissionAuthority — validates mission signatures, checks expiry/scope
+ *   MissionGuard — pre-write check against active mission constraints
+ *   AlignmentAdjudicator — wraps any Adjudicator, adding mission checks
+ */
+import type { Result } from '@private.me/shared';
+import type { MissionRecord, HardConstraint, ProposedAction, ConstraintResult, MemoryEntry, AdjudicatorResult } from './types.js';
+import type { ContinuityError } from './errors.js';
+import type { Adjudicator } from './adjudicator.js';
+/**
+ * Validates mission records and checks authority.
+ */
+export declare class MissionAuthority {
+    private activeMission;
+    /**
+     * Load a mission record after verifying its signature and validity.
+     */
+    loadMission(mission: MissionRecord): Promise<Result<void, ContinuityError>>;
+    /**
+     * Load a mission without signature verification (for testing or trusted sources).
+     */
+    loadTrustedMission(mission: MissionRecord): void;
+    /** Get the active mission. */
+    getActiveMission(): MissionRecord | null;
+    /** Clear the active mission. */
+    clearMission(): void;
+    /**
+     * Check if an action falls within the active mission's scopes.
+     */
+    isInScope(action: ProposedAction): Result<boolean, ContinuityError>;
+}
+/**
+ * Pre-write guard that evaluates actions against mission constraints.
+ */
+export declare class MissionGuard {
+    private readonly authority;
+    private readonly constraints;
+    constructor(authority: MissionAuthority);
+    /** Add a hard constraint. */
+    addConstraint(constraint: HardConstraint): void;
+    /** Remove a constraint by ID. */
+    removeConstraint(constraintId: string): boolean;
+    /** Get all active constraints. */
+    getConstraints(): readonly HardConstraint[];
+    /**
+     * Evaluate a proposed action against all constraints and mission scope.
+     *
+     * @returns ConstraintResult — allowed:true if all pass, or first violation
+     */
+    evaluate(action: ProposedAction): Result<ConstraintResult, ContinuityError>;
+}
+/**
+ * Adjudicator wrapper that adds mission constraint checking.
+ *
+ * Delegates resolution to the inner adjudicator, but rejects
+ * any winning entry that violates active mission constraints.
+ */
+export declare class AlignmentAdjudicator implements Adjudicator {
+    private readonly inner;
+    private readonly guard;
+    constructor(inner: Adjudicator, guard: MissionGuard);
+    resolve(key: string, candidates: readonly MemoryEntry[]): Result<AdjudicatorResult, ContinuityError>;
+}

package/dist/mission.js

@@ -0,0 +1,172 @@
+/**
+ * @private.me/xcontinuity — Mission (Human-Anchored Goals)
+ *
+ * Ensures AI agents operate within human-defined boundaries.
+ *
+ * Components:
+ *   MissionAuthority — validates mission signatures, checks expiry/scope
+ *   MissionGuard — pre-write check against active mission constraints
+ *   AlignmentAdjudicator — wraps any Adjudicator, adding mission checks
+ */
+import { ok, err } from '@private.me/shared';
+import { continuityError } from './errors.js';
+import { authorRefToPublicKey } from './provenance.js';
+/**
+ * Validates mission records and checks authority.
+ */
+export class MissionAuthority {
+    activeMission = null;
+    /**
+     * Load a mission record after verifying its signature and validity.
+     */
+    async loadMission(mission) {
+        // Check expiry
+        if (mission.expiresAt !== undefined && Date.now() > mission.expiresAt) {
+            return err(continuityError('AUTHORITY_EXPIRED', `Mission ${mission.missionId} has expired`));
+        }
+        // Verify signature
+        try {
+            const publicKey = await authorRefToPublicKey(mission.authority);
+            const encoder = new TextEncoder();
+            const missionBytes = encoder.encode(canonicalMissionString(mission));
+            const valid = await crypto.subtle.verify('Ed25519', publicKey, mission.signature.buffer, missionBytes.buffer);
+            if (!valid) {
+                return err(continuityError('INVALID_MISSION_SIGNATURE', `Mission ${mission.missionId} signature invalid`));
+            }
+        }
+        catch (e) {
+            return err(continuityError('INVALID_MISSION_SIGNATURE', `Signature verification failed: ${e instanceof Error ? e.message : String(e)}`));
+        }
+        this.activeMission = mission;
+        return ok(undefined);
+    }
+    /**
+     * Load a mission without signature verification (for testing or trusted sources).
+     */
+    loadTrustedMission(mission) {
+        this.activeMission = mission;
+    }
+    /** Get the active mission. */
+    getActiveMission() {
+        return this.activeMission;
+    }
+    /** Clear the active mission. */
+    clearMission() {
+        this.activeMission = null;
+    }
+    /**
+     * Check if an action falls within the active mission's scopes.
+     */
+    isInScope(action) {
+        if (!this.activeMission) {
+            return err(continuityError('NO_ACTIVE_MISSION', 'No mission loaded'));
+        }
+        // Check expiry
+        if (this.activeMission.expiresAt !== undefined && Date.now() > this.activeMission.expiresAt) {
+            return err(continuityError('AUTHORITY_EXPIRED', `Mission ${this.activeMission.missionId} has expired`));
+        }
+        // Empty scopes = all actions allowed
+        if (this.activeMission.scopes.length === 0) {
+            return ok(true);
+        }
+        // Check if action type or key matches any scope
+        const actionScope = `${action.type}:${action.key}`;
+        const inScope = this.activeMission.scopes.some(scope => actionScope.startsWith(scope) || action.type === scope || scope === '*');
+        return ok(inScope);
+    }
+}
+/**
+ * Pre-write guard that evaluates actions against mission constraints.
+ */
+export class MissionGuard {
+    authority;
+    constraints = [];
+    constructor(authority) {
+        this.authority = authority;
+    }
+    /** Add a hard constraint. */
+    addConstraint(constraint) {
+        this.constraints.push(constraint);
+    }
+    /** Remove a constraint by ID. */
+    removeConstraint(constraintId) {
+        const idx = this.constraints.findIndex(c => c.constraintId === constraintId);
+        if (idx === -1)
+            return false;
+        this.constraints.splice(idx, 1);
+        return true;
+    }
+    /** Get all active constraints. */
+    getConstraints() {
+        return this.constraints.slice();
+    }
+    /**
+     * Evaluate a proposed action against all constraints and mission scope.
+     *
+     * @returns ConstraintResult — allowed:true if all pass, or first violation
+     */
+    evaluate(action) {
+        // Check mission scope first
+        const scopeResult = this.authority.isInScope(action);
+        if (!scopeResult.ok)
+            return scopeResult;
+        if (!scopeResult.value) {
+            return ok({
+                allowed: false,
+                reason: `Action "${action.type}:${action.key}" is outside mission scope`,
+            });
+        }
+        // Evaluate each constraint
+        for (const constraint of this.constraints) {
+            const result = constraint.evaluate(action);
+            if (!result.allowed) {
+                return ok(result);
+            }
+        }
+        return ok({ allowed: true });
+    }
+}
+/**
+ * Adjudicator wrapper that adds mission constraint checking.
+ *
+ * Delegates resolution to the inner adjudicator, but rejects
+ * any winning entry that violates active mission constraints.
+ */
+export class AlignmentAdjudicator {
+    inner;
+    guard;
+    constructor(inner, guard) {
+        this.inner = inner;
+        this.guard = guard;
+    }
+    resolve(key, candidates) {
+        const result = this.inner.resolve(key, candidates);
+        if (!result.ok)
+            return result;
+        // Check if winning entry passes mission constraints
+        const action = {
+            author: result.value.winner.provenance?.author ?? '',
+            type: 'write',
+            key,
+            value: result.value.winner.value,
+        };
+        const guardResult = this.guard.evaluate(action);
+        if (!guardResult.ok)
+            return guardResult;
+        if (!guardResult.value.allowed) {
+            return err(continuityError('CONSTRAINT_VIOLATION', `Winner for "${key}" violates constraint: ${guardResult.value.reason}`));
+        }
+        return result;
+    }
+}
+/* ── Internal helpers ── */
+function canonicalMissionString(mission) {
+    return [
+        mission.missionId,
+        mission.goal,
+        mission.authority,
+        String(mission.issuedAt),
+        String(mission.expiresAt ?? ''),
+        [...mission.scopes].sort().join(','),
+    ].join('\0');
+}

package/dist/provenance.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @private.me/xcontinuity — Provenance (Ed25519 Signed Entries)
+ *
+ * Cryptographic provenance for chronicle entries using Ed25519 signatures
+ * via the Web Crypto API. Each entry can be signed by an agent, creating
+ * a verifiable chain of authorship and integrity.
+ *
+ * Uses native Web Crypto EdDSA (Node.js 16.9+, modern browsers).
+ * Zero external dependencies.
+ */
+import type { Result } from '@private.me/shared';
+import type { AuthorRef, MemoryEntry, ProvenanceRecord, StateValue } from './types.js';
+import type { ContinuityError } from './errors.js';
+/** Ed25519 key pair for signing and verification. */
+export interface Ed25519KeyPair {
+    readonly publicKey: CryptoKey;
+    readonly privateKey: CryptoKey;
+}
+/**
+ * Generate a new Ed25519 key pair for provenance signing.
+ */
+export declare function generateSigningKeyPair(): Promise<Ed25519KeyPair>;
+/**
+ * Export the public key as an AuthorRef (base64url-encoded 32-byte key).
+ */
+export declare function publicKeyToAuthorRef(publicKey: CryptoKey): Promise<AuthorRef>;
+/**
+ * Import an AuthorRef back to a CryptoKey for verification.
+ */
+export declare function authorRefToPublicKey(authorRef: AuthorRef): Promise<CryptoKey>;
+/**
+ * Produce canonical bytes for a memory entry, suitable for signing.
+ *
+ * Deterministic serialization: sorted keys, UTF-8 encoded.
+ * Format: `key\0type\0valueBytes\0timestamp`
+ */
+export declare function canonicalEntryBytes(key: string, value: StateValue, timestamp: number, parentHash?: Uint8Array): Uint8Array;
+/**
+ * Sign a memory entry, producing a ProvenanceRecord.
+ */
+export declare function signEntry(key: string, value: StateValue, privateKey: CryptoKey, publicKey: CryptoKey, parentHash?: Uint8Array): Promise<Result<ProvenanceRecord, ContinuityError>>;
+/**
+ * Verify a provenance record against the entry data and author's public key.
+ */
+export declare function verifyEntry(key: string, value: StateValue, provenance: ProvenanceRecord, publicKey: CryptoKey): Promise<Result<boolean, ContinuityError>>;
+/**
+ * Compute the SHA-256 hash of a provenance record for chain linking.
+ */
+export declare function hashProvenance(provenance: ProvenanceRecord): Promise<Uint8Array>;
+/**
+ * Verify a parent hash chain link: the parentHash in the current entry
+ * must equal the hash of the previous entry's provenance.
+ */
+export declare function verifyChainLink(current: MemoryEntry, previous: MemoryEntry): Promise<Result<boolean, ContinuityError>>;

package/dist/provenance.js

@@ -0,0 +1,182 @@
+/**
+ * @private.me/xcontinuity — Provenance (Ed25519 Signed Entries)
+ *
+ * Cryptographic provenance for chronicle entries using Ed25519 signatures
+ * via the Web Crypto API. Each entry can be signed by an agent, creating
+ * a verifiable chain of authorship and integrity.
+ *
+ * Uses native Web Crypto EdDSA (Node.js 16.9+, modern browsers).
+ * Zero external dependencies.
+ */
+import { ok, err } from '@private.me/shared';
+import { continuityError } from './errors.js';
+/**
+ * Generate a new Ed25519 key pair for provenance signing.
+ */
+export async function generateSigningKeyPair() {
+    const keyPair = await crypto.subtle.generateKey('Ed25519', true, ['sign', 'verify']);
+    return {
+        publicKey: keyPair.publicKey,
+        privateKey: keyPair.privateKey,
+    };
+}
+/**
+ * Export the public key as an AuthorRef (base64url-encoded 32-byte key).
+ */
+export async function publicKeyToAuthorRef(publicKey) {
+    const raw = await crypto.subtle.exportKey('raw', publicKey);
+    return uint8ToBase64Url(new Uint8Array(raw));
+}
+/**
+ * Import an AuthorRef back to a CryptoKey for verification.
+ */
+export async function authorRefToPublicKey(authorRef) {
+    const raw = base64UrlToUint8(authorRef);
+    return crypto.subtle.importKey('raw', raw.buffer, 'Ed25519', true, ['verify']);
+}
+/**
+ * Produce canonical bytes for a memory entry, suitable for signing.
+ *
+ * Deterministic serialization: sorted keys, UTF-8 encoded.
+ * Format: `key\0type\0valueBytes\0timestamp`
+ */
+export function canonicalEntryBytes(key, value, timestamp, parentHash) {
+    const encoder = new TextEncoder();
+    const keyBytes = encoder.encode(key);
+    const valueStr = canonicalValueString(value);
+    const valueBytes = encoder.encode(valueStr);
+    const tsBytes = encoder.encode(String(timestamp));
+    // Total: key + \0 + value + \0 + timestamp [+ \0 + parentHash]
+    const parentLen = parentHash ? 1 + parentHash.length : 0;
+    const total = keyBytes.length + 1 + valueBytes.length + 1 + tsBytes.length + parentLen;
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    buf.set(keyBytes, offset);
+    offset += keyBytes.length;
+    buf[offset++] = 0;
+    buf.set(valueBytes, offset);
+    offset += valueBytes.length;
+    buf[offset++] = 0;
+    buf.set(tsBytes, offset);
+    offset += tsBytes.length;
+    if (parentHash) {
+        buf[offset++] = 0;
+        buf.set(parentHash, offset);
+    }
+    return buf;
+}
+/**
+ * Sign a memory entry, producing a ProvenanceRecord.
+ */
+export async function signEntry(key, value, privateKey, publicKey, parentHash) {
+    try {
+        const timestamp = Date.now();
+        const canonical = canonicalEntryBytes(key, value, timestamp, parentHash);
+        const signature = new Uint8Array(await crypto.subtle.sign('Ed25519', privateKey, canonical.buffer));
+        const author = await publicKeyToAuthorRef(publicKey);
+        return ok({
+            author,
+            timestamp,
+            signature,
+            parentHash,
+        });
+    }
+    catch (e) {
+        return err(continuityError('INVALID_SIGNATURE', `Failed to sign entry: ${e instanceof Error ? e.message : String(e)}`));
+    }
+}
+/**
+ * Verify a provenance record against the entry data and author's public key.
+ */
+export async function verifyEntry(key, value, provenance, publicKey) {
+    try {
+        if (!provenance.author) {
+            return err(continuityError('MISSING_AUTHOR', 'Provenance record has no author'));
+        }
+        const canonical = canonicalEntryBytes(key, value, provenance.timestamp, provenance.parentHash);
+        const valid = await crypto.subtle.verify('Ed25519', publicKey, provenance.signature.buffer, canonical.buffer);
+        return ok(valid);
+    }
+    catch (e) {
+        return err(continuityError('INVALID_SIGNATURE', `Verification failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+}
+/**
+ * Compute the SHA-256 hash of a provenance record for chain linking.
+ */
+export async function hashProvenance(provenance) {
+    const encoder = new TextEncoder();
+    const authorBytes = encoder.encode(provenance.author);
+    const tsBytes = encoder.encode(String(provenance.timestamp));
+    const parentLen = provenance.parentHash ? provenance.parentHash.length : 0;
+    const total = authorBytes.length + 1 + tsBytes.length + 1 + provenance.signature.length + parentLen;
+    const buf = new Uint8Array(total);
+    let offset = 0;
+    buf.set(authorBytes, offset);
+    offset += authorBytes.length;
+    buf[offset++] = 0;
+    buf.set(tsBytes, offset);
+    offset += tsBytes.length;
+    buf[offset++] = 0;
+    buf.set(provenance.signature, offset);
+    offset += provenance.signature.length;
+    if (provenance.parentHash) {
+        buf.set(provenance.parentHash, offset);
+    }
+    const hash = await crypto.subtle.digest('SHA-256', buf.buffer);
+    return new Uint8Array(hash);
+}
+/**
+ * Verify a parent hash chain link: the parentHash in the current entry
+ * must equal the hash of the previous entry's provenance.
+ */
+export async function verifyChainLink(current, previous) {
+    if (!current.provenance?.parentHash) {
+        return ok(true); // No chain link to verify (root entry)
+    }
+    if (!previous.provenance) {
+        return err(continuityError('HASH_CHAIN_BREAK', `Previous entry "${previous.key}" has no provenance to hash`));
+    }
+    const expectedHash = await hashProvenance(previous.provenance);
+    const matches = constantTimeEqual(current.provenance.parentHash, expectedHash);
+    if (!matches) {
+        return err(continuityError('HASH_CHAIN_BREAK', `Parent hash mismatch for entry "${current.key}"`));
+    }
+    return ok(true);
+}
+/* ── Internal helpers ── */
+function canonicalValueString(value) {
+    if (value === null)
+        return 'null';
+    if (value instanceof Uint8Array)
+        return `bytes:${uint8ToBase64Url(value)}`;
+    if (typeof value === 'object')
+        return JSON.stringify(value, Object.keys(value).sort());
+    return String(value);
+}
+function uint8ToBase64Url(data) {
+    let binary = '';
+    for (let i = 0; i < data.length; i++) {
+        binary += String.fromCharCode(data[i]);
+    }
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlToUint8(b64url) {
+    const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}