monomind 1.19.0 → 2.0.0

package/packages/@monomind/guidance/dist/truth-anchors.js

@@ -1,488 +0,0 @@
-/**
- * Truth Anchor System
- *
- * Immutable, externally-signed facts that anchor the system to reality
- * beyond tool outputs and internal memory.
- *
- * A Truth Anchor is a fact that:
- * - Is immutable once recorded (cannot be overwritten or decayed)
- * - Is externally signed (by a human, hardware sensor, or external authority)
- * - Supersedes any internal belief that contradicts it
- * - Can be referenced but never mutated
- * - Has a verifiable signature chain
- *
- * TruthAnchorStore:
- * - Creates and signs new truth anchors with HMAC-SHA256
- * - Append-only storage (anchors are never mutated after creation)
- * - Retrieval by ID, time range, kind, attester, or tags
- * - Signature verification for individual anchors or the full store
- * - Supersession chain: new anchors can declare they supersede old ones
- * - Export/import for persistence and transfer
- * - Max 50,000 anchors with LRU eviction of expired ones only
- *
- * TruthResolver:
- * - Resolves conflicts between internal beliefs and truth anchors
- * - Memory conflict resolution (truth anchor always wins)
- * - Decision conflict resolution (constrains proposed actions)
- * - Topic-based ground truth retrieval with fuzzy tag matching
- *
- * @module @monomind/guidance/truth-anchors
- */
-import { createHmac, randomUUID } from 'node:crypto';
-// ============================================================================
-// Default Configuration
-// ============================================================================
-const DEFAULT_CONFIG = {
-    signingKey: '',
-    maxAnchors: 50_000,
-};
-// ============================================================================
-// Signing Helpers
-// ============================================================================
-/**
- * Compute the canonical string representation of an anchor for signing.
- *
- * Deterministic ordering ensures the same anchor always produces
- * the same signature regardless of property insertion order.
- */
-function canonicalize(anchor) {
-    return [
-        anchor.id,
-        anchor.kind,
-        anchor.claim,
-        anchor.evidence,
-        anchor.attesterId,
-        String(anchor.timestamp),
-        String(anchor.validFrom),
-        String(anchor.validUntil ?? 'null'),
-        anchor.supersedes.join(','),
-        anchor.tags.join(','),
-        JSON.stringify(anchor.metadata),
-    ].join('|');
-}
-/**
- * Produce an HMAC-SHA256 signature for the given data using the provided key.
- */
-function sign(data, key) {
-    return createHmac('sha256', key).update(data).digest('hex');
-}
-// ============================================================================
-// Truth Anchor Store
-// ============================================================================
-/**
- * Append-only store for truth anchors.
- *
- * Anchors are immutable once created. The store provides signing,
- * verification, querying, supersession, and capacity management
- * with LRU eviction of expired anchors only.
- */
-export class TruthAnchorStore {
-    config;
-    anchors = [];
-    indexById = new Map();
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-        if (!this.config.signingKey) {
-            throw new Error('TruthAnchorStore requires a signingKey in config. ' +
-                'Anchors cannot be created without a signing key.');
-        }
-    }
-    /**
-     * Create and sign a new truth anchor.
-     *
-     * The anchor is appended to the store and can never be mutated.
-     * If the store exceeds capacity, expired anchors are evicted
-     * starting from the oldest.
-     */
-    anchor(params) {
-        const now = Date.now();
-        const partial = {
-            id: randomUUID(),
-            kind: params.kind,
-            claim: params.claim,
-            evidence: params.evidence,
-            attesterId: params.attesterId,
-            timestamp: now,
-            validFrom: params.validFrom ?? now,
-            validUntil: params.validUntil ?? null,
-            supersedes: params.supersedes ?? [],
-            tags: params.tags ?? [],
-            metadata: params.metadata ?? {},
-        };
-        const signature = sign(canonicalize(partial), this.config.signingKey);
-        const truthAnchor = {
-            ...partial,
-            signature,
-        };
-        // Append (never mutate existing entries)
-        this.anchors.push(truthAnchor);
-        this.indexById.set(truthAnchor.id, this.anchors.length - 1);
-        // Enforce capacity by evicting expired anchors
-        this.enforceCapacity(now);
-        return truthAnchor;
-    }
-    /**
-     * Retrieve a truth anchor by its ID.
-     *
-     * Returns undefined if the anchor does not exist.
-     */
-    get(id) {
-        const index = this.indexById.get(id);
-        if (index === undefined)
-            return undefined;
-        return this.anchors[index];
-    }
-    /**
-     * Get all anchors that are valid at the given timestamp.
-     *
-     * An anchor is active when:
-     * - `validFrom <= timestamp`
-     * - `validUntil` is null (indefinite) or `validUntil > timestamp`
-     *
-     * Defaults to the current time if no timestamp is provided.
-     */
-    getActive(timestamp) {
-        const ts = timestamp ?? Date.now();
-        return this.anchors.filter(a => isActive(a, ts));
-    }
-    /**
-     * Query anchors with optional filters.
-     *
-     * All provided filters are ANDed together. An anchor must match
-     * every specified filter to be included in the result.
-     */
-    query(opts) {
-        return this.anchors.filter(a => {
-            if (opts.kind !== undefined && a.kind !== opts.kind)
-                return false;
-            if (opts.attesterId !== undefined && a.attesterId !== opts.attesterId)
-                return false;
-            if (opts.tags !== undefined && opts.tags.length > 0) {
-                const hasMatch = opts.tags.some(tag => a.tags.includes(tag));
-                if (!hasMatch)
-                    return false;
-            }
-            if (opts.validAt !== undefined && !isActive(a, opts.validAt))
-                return false;
-            return true;
-        });
-    }
-    /**
-     * Verify the HMAC-SHA256 signature of a single anchor.
-     *
-     * Recomputes the signature from the anchor's content and compares
-     * it to the stored signature. Returns true if they match.
-     */
-    verify(id) {
-        const anchor = this.get(id);
-        if (!anchor)
-            return false;
-        const { signature, ...rest } = anchor;
-        const expected = sign(canonicalize(rest), this.config.signingKey);
-        return timingSafeEqual(signature, expected);
-    }
-    /**
-     * Verify all anchors in the store.
-     *
-     * Returns a summary with the count of valid anchors and the
-     * IDs of any anchors whose signatures do not match.
-     */
-    verifyAll() {
-        let valid = 0;
-        const invalid = [];
-        for (const anchor of this.anchors) {
-            const { signature, ...rest } = anchor;
-            const expected = sign(canonicalize(rest), this.config.signingKey);
-            if (timingSafeEqual(signature, expected)) {
-                valid++;
-            }
-            else {
-                invalid.push(anchor.id);
-            }
-        }
-        return { valid, invalid };
-    }
-    /**
-     * Create a new anchor that supersedes an existing one.
-     *
-     * The old anchor remains in the store (immutable) but the new
-     * anchor's `supersedes` array includes the old anchor's ID.
-     * This creates a verifiable supersession chain.
-     *
-     * Throws if the old anchor ID does not exist.
-     */
-    supersede(oldId, params) {
-        const old = this.get(oldId);
-        if (!old) {
-            throw new Error(`Cannot supersede: anchor "${oldId}" not found`);
-        }
-        const supersedes = [...(params.supersedes ?? [])];
-        if (!supersedes.includes(oldId)) {
-            supersedes.push(oldId);
-        }
-        return this.anchor({
-            ...params,
-            supersedes,
-        });
-    }
-    /**
-     * Resolve a claim against an internal belief.
-     *
-     * Searches for active truth anchors whose claim matches the
-     * provided claim text. If a matching truth anchor exists and
-     * is currently valid, it wins over the internal belief.
-     *
-     * Returns the truth anchor if it exists, otherwise returns
-     * undefined (meaning the internal belief stands).
-     */
-    resolve(claim, _internalBelief) {
-        const now = Date.now();
-        const normalizedClaim = claim.toLowerCase().trim();
-        // Find active anchors whose claim matches
-        for (const anchor of this.anchors) {
-            if (!isActive(anchor, now))
-                continue;
-            if (anchor.claim.toLowerCase().trim() === normalizedClaim) {
-                return anchor;
-            }
-        }
-        return undefined;
-    }
-    /**
-     * Export all anchors for persistence or transfer.
-     *
-     * Returns a shallow copy of the anchor array. The individual
-     * anchor objects are returned as-is since they are immutable.
-     */
-    exportAnchors() {
-        return [...this.anchors];
-    }
-    /**
-     * Import anchors from an external source.
-     *
-     * Imported anchors are appended to the store. Duplicate IDs
-     * (anchors already in the store) are silently skipped.
-     * Capacity enforcement runs after import.
-     */
-    importAnchors(anchors) {
-        const now = Date.now();
-        for (const anchor of anchors) {
-            // Skip duplicates
-            if (this.indexById.has(anchor.id))
-                continue;
-            this.anchors.push(anchor);
-            this.indexById.set(anchor.id, this.anchors.length - 1);
-        }
-        this.enforceCapacity(now);
-    }
-    /**
-     * Get the total number of anchors in the store.
-     */
-    get size() {
-        return this.anchors.length;
-    }
-    // ===== Private =====
-    /**
-     * Enforce the maximum anchor capacity.
-     *
-     * Only expired anchors are evicted, starting from the oldest.
-     * If no expired anchors can be evicted and the store is still
-     * over capacity, the oldest expired anchors are removed first.
-     * Active (non-expired) anchors are never evicted.
-     */
-    enforceCapacity(now) {
-        if (this.anchors.length <= this.config.maxAnchors)
-            return;
-        // Collect indices of expired anchors (oldest first, array is append-only)
-        const expiredIndices = [];
-        for (let i = 0; i < this.anchors.length; i++) {
-            const a = this.anchors[i];
-            if (a.validUntil !== null && a.validUntil <= now) {
-                expiredIndices.push(i);
-            }
-        }
-        // Determine how many we need to evict
-        const excess = this.anchors.length - this.config.maxAnchors;
-        const toEvict = Math.min(excess, expiredIndices.length);
-        if (toEvict <= 0)
-            return;
-        // Build a set of indices to remove (oldest expired first)
-        const removeSet = new Set(expiredIndices.slice(0, toEvict));
-        // Rebuild the array and index, preserving order
-        const surviving = [];
-        this.indexById.clear();
-        for (let i = 0; i < this.anchors.length; i++) {
-            if (removeSet.has(i))
-                continue;
-            this.indexById.set(this.anchors[i].id, surviving.length);
-            surviving.push(this.anchors[i]);
-        }
-        // Replace contents (splice to preserve the same array reference)
-        this.anchors.length = 0;
-        for (const a of surviving) {
-            this.anchors.push(a);
-        }
-    }
-}
-// ============================================================================
-// Truth Resolver
-// ============================================================================
-/**
- * Resolves conflicts between internal system beliefs and externally
- * anchored truth.
- *
- * The fundamental principle: truth anchors always win. If a valid,
- * active truth anchor contradicts an internal belief, the anchor
- * takes precedence.
- */
-export class TruthResolver {
-    store;
-    constructor(store) {
-        this.store = store;
-    }
-    /**
-     * Check if any active truth anchor contradicts a memory value.
-     *
-     * Searches by namespace and key as tags, and by the memory value
-     * as a claim. If a truth anchor exists that covers the same topic,
-     * it wins over the internal memory.
-     */
-    resolveMemoryConflict(memoryKey, memoryValue, namespace) {
-        const now = Date.now();
-        const active = this.store.getActive(now);
-        // Search for anchors tagged with the namespace or memory key
-        const normalizedKey = memoryKey.toLowerCase().trim();
-        const normalizedNs = namespace.toLowerCase().trim();
-        const normalizedValue = memoryValue.toLowerCase().trim();
-        for (const anchor of active) {
-            const lowerTags = anchor.tags.map(t => t.toLowerCase());
-            // Check if the anchor is relevant to this memory entry
-            const tagMatch = lowerTags.includes(normalizedKey) ||
-                lowerTags.includes(normalizedNs) ||
-                lowerTags.includes(`${normalizedNs}:${normalizedKey}`);
-            if (!tagMatch)
-                continue;
-            // Check if the anchor's claim contradicts the memory value
-            const anchorClaim = anchor.claim.toLowerCase().trim();
-            if (anchorClaim !== normalizedValue) {
-                return {
-                    truthWins: true,
-                    anchor,
-                    reason: `Truth anchor "${anchor.id}" (${anchor.kind}) contradicts memory ` +
-                        `"${namespace}:${memoryKey}". Anchor claim: "${anchor.claim}" ` +
-                        `supersedes internal value: "${memoryValue}".`,
-                };
-            }
-        }
-        return {
-            truthWins: false,
-            reason: `No active truth anchor contradicts memory "${namespace}:${memoryKey}". ` +
-                `Internal belief stands.`,
-        };
-    }
-    /**
-     * Check if any active truth anchor constrains a proposed action.
-     *
-     * Searches for anchors whose claims or tags relate to the proposed
-     * action and its context. Returns a conflict resolution indicating
-     * whether the action is constrained.
-     */
-    resolveDecisionConflict(proposedAction, context) {
-        const now = Date.now();
-        const active = this.store.getActive(now);
-        const normalizedAction = proposedAction.toLowerCase().trim();
-        const contextKeys = Object.keys(context).map(k => k.toLowerCase());
-        for (const anchor of active) {
-            const lowerTags = anchor.tags.map(t => t.toLowerCase());
-            const lowerClaim = anchor.claim.toLowerCase();
-            // Check if the anchor is relevant: tags intersect with context keys
-            // or the action text appears in the claim
-            const tagOverlap = lowerTags.some(t => contextKeys.includes(t) || normalizedAction.includes(t));
-            const claimRelevance = lowerClaim.includes(normalizedAction) ||
-                normalizedAction.includes(lowerClaim);
-            if (!tagOverlap && !claimRelevance)
-                continue;
-            // The anchor is relevant -- it constrains this action
-            return {
-                truthWins: true,
-                anchor,
-                reason: `Truth anchor "${anchor.id}" (${anchor.kind}) constrains the ` +
-                    `proposed action "${proposedAction}". Anchor claim: "${anchor.claim}". ` +
-                    `Attested by: "${anchor.attesterId}".`,
-            };
-        }
-        return {
-            truthWins: false,
-            reason: `No active truth anchor constrains the proposed action ` +
-                `"${proposedAction}". Action may proceed.`,
-        };
-    }
-    /**
-     * Get all active truth anchors relevant to a topic.
-     *
-     * Uses fuzzy tag matching: a tag matches the topic if either
-     * the tag contains the topic or the topic contains the tag
-     * (case-insensitive). Also matches against the claim text.
-     */
-    getGroundTruth(topic) {
-        const now = Date.now();
-        const active = this.store.getActive(now);
-        const normalizedTopic = topic.toLowerCase().trim();
-        return active.filter(anchor => {
-            // Fuzzy tag match
-            const tagMatch = anchor.tags.some(tag => {
-                const lowerTag = tag.toLowerCase();
-                return lowerTag.includes(normalizedTopic) || normalizedTopic.includes(lowerTag);
-            });
-            // Claim text match
-            const claimMatch = anchor.claim.toLowerCase().includes(normalizedTopic);
-            return tagMatch || claimMatch;
-        });
-    }
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-/**
- * Check whether a truth anchor is active at a given timestamp.
- */
-function isActive(anchor, timestamp) {
-    if (anchor.validFrom > timestamp)
-        return false;
-    if (anchor.validUntil !== null && anchor.validUntil <= timestamp)
-        return false;
-    return true;
-}
-/**
- * Constant-time string comparison to prevent timing attacks on signatures.
- *
- * Compares two hex strings character by character, accumulating
- * differences without short-circuiting.
- */
-function timingSafeEqual(a, b) {
-    if (a.length !== b.length)
-        return false;
-    let mismatch = 0;
-    for (let i = 0; i < a.length; i++) {
-        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
-    }
-    return mismatch === 0;
-}
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Create a TruthAnchorStore with the given configuration.
- *
- * @param config - Must include `signingKey`. `maxAnchors` defaults to 50,000.
- */
-export function createTruthAnchorStore(config) {
-    return new TruthAnchorStore(config);
-}
-/**
- * Create a TruthResolver backed by the given store.
- */
-export function createTruthResolver(store) {
-    return new TruthResolver(store);
-}
-//# sourceMappingURL=truth-anchors.js.map