@private.me/xcontinuity 2.1.0

package/dist/session.js

@@ -0,0 +1,269 @@
+/**
+ * @private.me/xcontinuity — Session Manager
+ *
+ * Stateful controller combining all layers:
+ * - RuntimeMemory for ephemeral in-process state
+ * - SessionMemory for XorIDA-persisted state
+ * - Chronicle for ordered state history
+ *
+ * Status transitions: active -> suspended -> active (resume), active -> closed (terminal).
+ */
+import { ok, err } from '@private.me/shared';
+import { generateUUID } from '@private.me/crypto';
+import { DEFAULT_SPLIT_CONFIG } from './types.js';
+import { continuityError } from './errors.js';
+import { SessionMemory } from './memory-session.js';
+import { Chronicle } from './chronicle.js';
+export class SessionManager {
+    sessionRecord;
+    state;
+    memory;
+    chronicle;
+    trustStore;
+    missionGuard;
+    enforcementLoop;
+    sequenceCounter;
+    constructor(sessionRecord, memory, chronicle, trustStore, missionGuard, enforcementLoop) {
+        this.sessionRecord = sessionRecord;
+        this.state = {};
+        this.memory = memory;
+        this.chronicle = chronicle;
+        this.trustStore = trustStore;
+        this.missionGuard = missionGuard;
+        this.enforcementLoop = enforcementLoop;
+        this.sequenceCounter = 0;
+    }
+    /**
+     * Create a new continuity session.
+     *
+     * @param config - Session configuration (agentId, store, optional splitConfig)
+     * @returns SessionManager instance
+     */
+    static create(config) {
+        const sessionId = generateUUID();
+        const now = Date.now();
+        const splitConfig = config.splitConfig ?? DEFAULT_SPLIT_CONFIG;
+        const sessionRecord = {
+            sessionId,
+            agentId: config.agentId,
+            status: 'active',
+            splitConfig,
+            createdAt: now,
+            updatedAt: now,
+            snapshotCount: 0,
+        };
+        const memory = new SessionMemory(config.store, splitConfig);
+        const chronicle = new Chronicle();
+        // Extract trust substrate components (optional)
+        const trustConfig = config;
+        return new SessionManager(sessionRecord, memory, chronicle, trustConfig.trustStore, trustConfig.missionGuard, trustConfig.enforcementLoop);
+    }
+    /** Get the current session record. */
+    get session() {
+        return this.sessionRecord;
+    }
+    /** Get a copy of the current agent state. */
+    get currentState() {
+        return { ...this.state };
+    }
+    /**
+     * Merge a partial update into the current state.
+     * Only works when session is active.
+     */
+    updateState(patch) {
+        if (this.sessionRecord.status !== 'active') {
+            return err(continuityError(this.sessionRecord.status === 'closed' ? 'SESSION_CLOSED' : 'SESSION_SUSPENDED', `Cannot update state: session is ${this.sessionRecord.status}`));
+        }
+        // If enforcement loop is active, check each key in the patch
+        if (this.enforcementLoop) {
+            for (const [key, value] of Object.entries(patch)) {
+                const checkResult = this.enforcementLoop.check({
+                    author: this.sessionRecord.agentId,
+                    type: 'write',
+                    key,
+                    value: value,
+                });
+                if (checkResult.ok && checkResult.value.decision !== 'allow') {
+                    if (checkResult.value.decision === 'rewrite' && checkResult.value.rewrittenAction) {
+                        // Apply rewritten value instead
+                        patch = { ...patch, [key]: checkResult.value.rewrittenAction.value };
+                    }
+                    else {
+                        return err(continuityError('CONSTRAINT_VIOLATION', `State update blocked for key "${key}": ${checkResult.value.reason}`));
+                    }
+                }
+            }
+        }
+        // If trust store is present, route writes through it
+        if (this.trustStore) {
+            for (const [key, value] of Object.entries(patch)) {
+                this.trustStore.write(key, value);
+            }
+        }
+        this.state = { ...this.state, ...patch };
+        this.updateTimestamp();
+        return ok(undefined);
+    }
+    /**
+     * Replace the entire current state.
+     * Only works when session is active.
+     */
+    setState(state) {
+        if (this.sessionRecord.status !== 'active') {
+            return err(continuityError(this.sessionRecord.status === 'closed' ? 'SESSION_CLOSED' : 'SESSION_SUSPENDED', `Cannot set state: session is ${this.sessionRecord.status}`));
+        }
+        this.state = { ...state };
+        this.updateTimestamp();
+        return ok(undefined);
+    }
+    /**
+     * Persist current state as a XorIDA-split snapshot.
+     * Adds a chronicle entry for the snapshot.
+     *
+     * @param description - Optional human-readable description
+     * @param tags - Optional tags for filtering
+     * @returns StateSnapshot with stateId for later retrieval
+     */
+    async snapshot(description, tags) {
+        if (this.sessionRecord.status !== 'active') {
+            return err(continuityError(this.sessionRecord.status === 'closed' ? 'SESSION_CLOSED' : 'SESSION_SUSPENDED', `Cannot snapshot: session is ${this.sessionRecord.status}`));
+        }
+        const sequence = this.sequenceCounter++;
+        const snapshotTags = tags ?? [];
+        const parentStateId = this.chronicle.latest()?.stateId;
+        const metadata = {
+            agentId: this.sessionRecord.agentId,
+            sessionId: this.sessionRecord.sessionId,
+            sequenceNumber: sequence,
+            createdAt: Date.now(),
+            description,
+            tags: snapshotTags,
+        };
+        const result = await this.memory.save(this.state, metadata);
+        if (!result.ok)
+            return result;
+        // Add chronicle entry
+        const entry = {
+            stateId: result.value.stateId,
+            sessionId: this.sessionRecord.sessionId,
+            sequence,
+            timestamp: metadata.createdAt,
+            description,
+            tags: snapshotTags,
+            parentStateId,
+        };
+        this.chronicle.append(entry);
+        // Update session record
+        this.sessionRecord = {
+            ...this.sessionRecord,
+            snapshotCount: this.sessionRecord.snapshotCount + 1,
+            updatedAt: Date.now(),
+        };
+        return result;
+    }
+    /**
+     * Restore state from a specific snapshot.
+     * Sets the current state to the reconstructed state.
+     *
+     * @param stateId - The state ID to restore
+     * @returns Reconstructed AgentState
+     */
+    async restore(stateId) {
+        if (this.sessionRecord.status === 'closed') {
+            return err(continuityError('SESSION_CLOSED', 'Cannot restore: session is closed'));
+        }
+        const result = await this.memory.load(stateId);
+        if (!result.ok)
+            return result;
+        this.state = result.value;
+        this.updateTimestamp();
+        // If suspended, transition back to active
+        if (this.sessionRecord.status === 'suspended') {
+            this.sessionRecord = { ...this.sessionRecord, status: 'active' };
+        }
+        return ok({ ...result.value });
+    }
+    /**
+     * Restore the latest snapshot.
+     * Convenience method for restoring the most recent state.
+     */
+    async restoreLatest() {
+        const latest = this.chronicle.latest();
+        if (!latest) {
+            return err(continuityError('NO_SNAPSHOTS', 'No snapshots available to restore'));
+        }
+        return this.restore(latest.stateId);
+    }
+    /**
+     * Suspend the session. Persists current state before suspending.
+     * Can be resumed later.
+     */
+    async suspend() {
+        if (this.sessionRecord.status !== 'active') {
+            return err(continuityError(this.sessionRecord.status === 'closed' ? 'SESSION_CLOSED' : 'SESSION_SUSPENDED', `Cannot suspend: session is ${this.sessionRecord.status}`));
+        }
+        // Auto-snapshot before suspending
+        const snapResult = await this.snapshot('auto-suspend', ['suspend']);
+        if (!snapResult.ok)
+            return snapResult;
+        this.sessionRecord = {
+            ...this.sessionRecord,
+            status: 'suspended',
+            updatedAt: Date.now(),
+        };
+        return ok(undefined);
+    }
+    /**
+     * Resume a suspended session. Restores the latest snapshot.
+     */
+    async resume() {
+        if (this.sessionRecord.status !== 'suspended') {
+            if (this.sessionRecord.status === 'closed') {
+                return err(continuityError('SESSION_CLOSED', 'Cannot resume: session is closed'));
+            }
+            return err(continuityError('SESSION_ACTIVE', 'Session is already active'));
+        }
+        this.sessionRecord = {
+            ...this.sessionRecord,
+            status: 'active',
+            updatedAt: Date.now(),
+        };
+        return this.restoreLatest();
+    }
+    /**
+     * Close the session permanently. No further operations allowed.
+     */
+    close() {
+        if (this.sessionRecord.status === 'closed') {
+            return err(continuityError('SESSION_CLOSED', 'Session is already closed'));
+        }
+        this.sessionRecord = {
+            ...this.sessionRecord,
+            status: 'closed',
+            updatedAt: Date.now(),
+        };
+        return ok(undefined);
+    }
+    /** Get the chronicle for state history navigation. */
+    getChronicle() {
+        return this.chronicle;
+    }
+    /** Get the trust store (if configured). */
+    getTrustStore() {
+        return this.trustStore;
+    }
+    /** Get the mission guard (if configured). */
+    getMissionGuard() {
+        return this.missionGuard;
+    }
+    /** Get the enforcement loop (if configured). */
+    getEnforcementLoop() {
+        return this.enforcementLoop;
+    }
+    updateTimestamp() {
+        this.sessionRecord = {
+            ...this.sessionRecord,
+            updatedAt: Date.now(),
+        };
+    }
+}

package/dist/state-serializer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @private.me/xcontinuity — State Serialization
+ *
+ * Pipeline: AgentState -> TLV byte stream -> SHA-256 checksum -> StateSnapshot
+ *
+ * TLV format: [Type:1][Length:4 BE][Value:N] per entry.
+ * Key-value pairs: [keyLen:2 BE][key:UTF8][valueType:1][value:typed]
+ * Value types: STRING(0x01), NUMBER(0x02/float64 BE), BOOLEAN(0x03/1byte),
+ *              BYTES(0x04), NULL(0x05), JSON(0x06/UTF8).
+ */
+import type { Result } from '@private.me/shared';
+import type { AgentState, StateMetadata, StateSnapshot } from './types.js';
+import type { ContinuityError } from './errors.js';
+/**
+ * Serialize agent state and metadata into a TLV byte stream with SHA-256 checksum.
+ *
+ * @param state - Flat key-value state map
+ * @param metadata - State metadata (agentId, sessionId, sequence, etc.)
+ * @returns StateSnapshot with stateId, serialized bytes, and checksum
+ */
+export declare function serializeState(state: AgentState, metadata: StateMetadata): Promise<Result<StateSnapshot, ContinuityError>>;
+/**
+ * Deserialize a state snapshot back into an AgentState.
+ * Verifies SHA-256 checksum before returning.
+ *
+ * @param snapshot - StateSnapshot to deserialize
+ * @returns Reconstructed AgentState
+ */
+export declare function deserializeState(snapshot: StateSnapshot): Promise<Result<AgentState, ContinuityError>>;
+/**
+ * Compute SHA-256 checksum of data using Web Crypto API.
+ */
+export declare function computeChecksum(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Compare two AgentStates for equality by comparing sorted serialized keys and values.
+ */
+export declare function statesEqual(a: AgentState, b: AgentState): boolean;

package/dist/state-serializer.js

@@ -0,0 +1,294 @@
+/**
+ * @private.me/xcontinuity — State Serialization
+ *
+ * Pipeline: AgentState -> TLV byte stream -> SHA-256 checksum -> StateSnapshot
+ *
+ * TLV format: [Type:1][Length:4 BE][Value:N] per entry.
+ * Key-value pairs: [keyLen:2 BE][key:UTF8][valueType:1][value:typed]
+ * Value types: STRING(0x01), NUMBER(0x02/float64 BE), BOOLEAN(0x03/1byte),
+ *              BYTES(0x04), NULL(0x05), JSON(0x06/UTF8).
+ */
+import { ok, err } from '@private.me/shared';
+import { generateUUID } from '@private.me/crypto';
+import { CONTINUITY_TLV, VALUE_TYPE } from './types.js';
+import { continuityError } from './errors.js';
+const TEXT_ENCODER = new TextEncoder();
+const TEXT_DECODER = new TextDecoder();
+/* ── TLV Primitives ── */
+function encodeTlv(type, value) {
+    const entry = new Uint8Array(5 + value.length);
+    entry[0] = type;
+    const view = new DataView(entry.buffer, 1, 4);
+    view.setUint32(0, value.length);
+    entry.set(value, 5);
+    return entry;
+}
+function encodeUint32(n) {
+    const buf = new Uint8Array(4);
+    new DataView(buf.buffer).setUint32(0, n);
+    return buf;
+}
+function encodeFloat64(n) {
+    const buf = new Uint8Array(8);
+    new DataView(buf.buffer).setFloat64(0, n);
+    return buf;
+}
+function encodeString(s) {
+    return TEXT_ENCODER.encode(s);
+}
+function encodeKeyLen(key) {
+    const keyBytes = TEXT_ENCODER.encode(key);
+    const buf = new Uint8Array(2 + keyBytes.length);
+    new DataView(buf.buffer).setUint16(0, keyBytes.length);
+    buf.set(keyBytes, 2);
+    return buf;
+}
+/* ── Value Encoding ── */
+function encodeValue(value) {
+    if (value === null) {
+        return new Uint8Array([VALUE_TYPE.NULL]);
+    }
+    if (typeof value === 'string') {
+        const strBytes = TEXT_ENCODER.encode(value);
+        const buf = new Uint8Array(1 + strBytes.length);
+        buf[0] = VALUE_TYPE.STRING;
+        buf.set(strBytes, 1);
+        return buf;
+    }
+    if (typeof value === 'number') {
+        const buf = new Uint8Array(9);
+        buf[0] = VALUE_TYPE.NUMBER;
+        new DataView(buf.buffer).setFloat64(1, value);
+        return buf;
+    }
+    if (typeof value === 'boolean') {
+        return new Uint8Array([VALUE_TYPE.BOOLEAN, value ? 1 : 0]);
+    }
+    if (value instanceof Uint8Array) {
+        const buf = new Uint8Array(1 + value.length);
+        buf[0] = VALUE_TYPE.BYTES;
+        buf.set(value, 1);
+        return buf;
+    }
+    // Record<string, unknown> -> JSON
+    const jsonBytes = TEXT_ENCODER.encode(JSON.stringify(value));
+    const buf = new Uint8Array(1 + jsonBytes.length);
+    buf[0] = VALUE_TYPE.JSON;
+    buf.set(jsonBytes, 1);
+    return buf;
+}
+/* ── Value Decoding ── */
+function decodeValue(data) {
+    if (data.length === 0) {
+        return err(continuityError('INVALID_VALUE_TYPE', 'Empty value data'));
+    }
+    const typeCode = data[0];
+    const payload = data.subarray(1);
+    switch (typeCode) {
+        case VALUE_TYPE.NULL:
+            return ok(null);
+        case VALUE_TYPE.STRING:
+            return ok(TEXT_DECODER.decode(payload));
+        case VALUE_TYPE.NUMBER: {
+            if (payload.length < 8) {
+                return err(continuityError('DESERIALIZE_FAILED', 'Number value too short'));
+            }
+            return ok(new DataView(payload.buffer, payload.byteOffset, 8).getFloat64(0));
+        }
+        case VALUE_TYPE.BOOLEAN:
+            return ok(payload[0] === 1);
+        case VALUE_TYPE.BYTES:
+            return ok(new Uint8Array(payload));
+        case VALUE_TYPE.JSON: {
+            try {
+                return ok(JSON.parse(TEXT_DECODER.decode(payload)));
+            }
+            catch {
+                return err(continuityError('DESERIALIZE_FAILED', 'Invalid JSON value'));
+            }
+        }
+        default:
+            return err(continuityError('INVALID_VALUE_TYPE', `Unknown value type: 0x${typeCode.toString(16)}`));
+    }
+}
+/* ── Entry Encoding ── */
+function encodeEntry(key, value) {
+    const keyPart = encodeKeyLen(key);
+    const valuePart = encodeValue(value);
+    const combined = new Uint8Array(keyPart.length + valuePart.length);
+    combined.set(keyPart, 0);
+    combined.set(valuePart, keyPart.length);
+    return combined;
+}
+/* ── Metadata Encoding ── */
+function encodeMetadata(metadata) {
+    const parts = [];
+    parts.push(encodeTlv(CONTINUITY_TLV.AGENT_ID, encodeString(metadata.agentId)));
+    parts.push(encodeTlv(CONTINUITY_TLV.SESSION_ID, encodeString(metadata.sessionId)));
+    parts.push(encodeTlv(CONTINUITY_TLV.SEQUENCE_NUMBER, encodeUint32(metadata.sequenceNumber)));
+    parts.push(encodeTlv(CONTINUITY_TLV.TIMESTAMP, encodeFloat64(metadata.createdAt)));
+    if (metadata.description) {
+        parts.push(encodeTlv(CONTINUITY_TLV.DESCRIPTION, encodeString(metadata.description)));
+    }
+    for (const tag of metadata.tags) {
+        parts.push(encodeTlv(CONTINUITY_TLV.TAG, encodeString(tag)));
+    }
+    return concatParts(parts);
+}
+/* ── Public API ── */
+/**
+ * Serialize agent state and metadata into a TLV byte stream with SHA-256 checksum.
+ *
+ * @param state - Flat key-value state map
+ * @param metadata - State metadata (agentId, sessionId, sequence, etc.)
+ * @returns StateSnapshot with stateId, serialized bytes, and checksum
+ */
+export async function serializeState(state, metadata) {
+    try {
+        const parts = [];
+        // Encode metadata header
+        const metaBytes = encodeMetadata(metadata);
+        parts.push(encodeTlv(CONTINUITY_TLV.STATE_METADATA, metaBytes));
+        // Encode state entries (sorted by key for deterministic output)
+        const sortedKeys = Object.keys(state).sort();
+        for (const key of sortedKeys) {
+            const value = state[key];
+            if (value === undefined)
+                continue;
+            const entryBytes = encodeEntry(key, value);
+            parts.push(encodeTlv(CONTINUITY_TLV.STATE_ENTRY, entryBytes));
+        }
+        const serializedBytes = concatParts(parts);
+        const checksum = await computeChecksum(serializedBytes);
+        const stateId = generateUUID();
+        return ok({
+            stateId,
+            metadata,
+            serializedBytes,
+            checksum,
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : 'Unknown serialization error';
+        return err(continuityError('SERIALIZE_FAILED', msg));
+    }
+}
+/**
+ * Deserialize a state snapshot back into an AgentState.
+ * Verifies SHA-256 checksum before returning.
+ *
+ * @param snapshot - StateSnapshot to deserialize
+ * @returns Reconstructed AgentState
+ */
+export async function deserializeState(snapshot) {
+    // Verify checksum
+    const computed = await computeChecksum(snapshot.serializedBytes);
+    if (!bytesEqual(computed, snapshot.checksum)) {
+        return err(continuityError('CHECKSUM_MISMATCH', 'SHA-256 checksum verification failed'));
+    }
+    const state = {};
+    const data = snapshot.serializedBytes;
+    let offset = 0;
+    while (offset < data.length) {
+        if (offset + 5 > data.length) {
+            return err(continuityError('INVALID_TLV', 'Truncated TLV header'));
+        }
+        const type = data[offset];
+        const view = new DataView(data.buffer, data.byteOffset + offset + 1, 4);
+        const length = view.getUint32(0);
+        offset += 5;
+        if (offset + length > data.length) {
+            return err(continuityError('INVALID_TLV', `TLV value exceeds data at type 0x${type.toString(16)}`));
+        }
+        const value = data.subarray(offset, offset + length);
+        offset += length;
+        if (type === CONTINUITY_TLV.STATE_ENTRY) {
+            const entryResult = decodeEntry(value);
+            if (!entryResult.ok)
+                return entryResult;
+            const [key, val] = entryResult.value;
+            state[key] = val;
+        }
+        // Skip metadata and other TLV types during state reconstruction
+    }
+    return ok(state);
+}
+/**
+ * Compute SHA-256 checksum of data using Web Crypto API.
+ */
+export async function computeChecksum(data) {
+    // Copy to a clean ArrayBuffer to satisfy Web Crypto API typing
+    const copy = new Uint8Array(data.length);
+    copy.set(data);
+    const hash = await crypto.subtle.digest('SHA-256', copy.buffer);
+    return new Uint8Array(hash);
+}
+/**
+ * Compare two AgentStates for equality by comparing sorted serialized keys and values.
+ */
+export function statesEqual(a, b) {
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length)
+        return false;
+    for (let i = 0; i < keysA.length; i++) {
+        if (keysA[i] !== keysB[i])
+            return false;
+        const valA = a[keysA[i]];
+        const valB = b[keysB[i]];
+        if (!valuesEqual(valA, valB))
+            return false;
+    }
+    return true;
+}
+/* ── Helpers ── */
+function decodeEntry(data) {
+    if (data.length < 3) {
+        return err(continuityError('DESERIALIZE_FAILED', 'Entry too short'));
+    }
+    const keyLen = new DataView(data.buffer, data.byteOffset, 2).getUint16(0);
+    if (2 + keyLen > data.length) {
+        return err(continuityError('DESERIALIZE_FAILED', 'Key length exceeds entry'));
+    }
+    const key = TEXT_DECODER.decode(data.subarray(2, 2 + keyLen));
+    const valueData = data.subarray(2 + keyLen);
+    const valueResult = decodeValue(valueData);
+    if (!valueResult.ok)
+        return valueResult;
+    return ok([key, valueResult.value]);
+}
+function concatParts(parts) {
+    const totalLen = parts.reduce((sum, p) => sum + p.length, 0);
+    const result = new Uint8Array(totalLen);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (a instanceof Uint8Array && b instanceof Uint8Array) {
+        return bytesEqual(a, b);
+    }
+    if (typeof a === 'object' && typeof b === 'object' &&
+        !(a instanceof Uint8Array) && !(b instanceof Uint8Array)) {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return a === b;
+}

package/dist/store-memory.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @private.me/xcontinuity — In-Memory StateStore
+ *
+ * Simple Map-based implementation of the StateStore interface.
+ * Async interface allows future disk/network backends without API changes.
+ */
+import type { StateStore, SplitState } from './types.js';
+export declare class MemoryStateStore implements StateStore {
+    private readonly store;
+    putShares(splitState: SplitState): Promise<void>;
+    getShares(stateId: string): Promise<SplitState | null>;
+    deleteShares(stateId: string): Promise<void>;
+    listStateIds(): Promise<string[]>;
+    /** Number of stored split states (useful for testing). */
+    get size(): number;
+    /** Clear all stored split states. */
+    clear(): void;
+}

package/dist/store-memory.js

@@ -0,0 +1,29 @@
+/**
+ * @private.me/xcontinuity — In-Memory StateStore
+ *
+ * Simple Map-based implementation of the StateStore interface.
+ * Async interface allows future disk/network backends without API changes.
+ */
+export class MemoryStateStore {
+    store = new Map();
+    async putShares(splitState) {
+        this.store.set(splitState.stateId, splitState);
+    }
+    async getShares(stateId) {
+        return this.store.get(stateId) ?? null;
+    }
+    async deleteShares(stateId) {
+        this.store.delete(stateId);
+    }
+    async listStateIds() {
+        return Array.from(this.store.keys());
+    }
+    /** Number of stored split states (useful for testing). */
+    get size() {
+        return this.store.size;
+    }
+    /** Clear all stored split states. */
+    clear() {
+        this.store.clear();
+    }
+}