aiyou-dev 3.5.15

package/v3/@aiyou-dev/guidance/dist/truth-anchors.js

@@ -0,0 +1,488 @@
+/**
+ * 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 @aiyou-dev/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