monomind 1.19.0 → 2.0.1

package/packages/@monomind/guidance/dist/temporal.js

@@ -1,660 +0,0 @@
-/**
- * Temporal Assertions and Validity Windows
- *
- * Bitemporal semantics for knowledge: distinguishes *assertion time* (when
- * something was recorded) from *validity time* (when the fact is/was/will be
- * true in the real world).
- *
- * The system tracks two independent timelines:
- * - Assertion time: when the assertion was recorded and when it was retracted
- * - Validity time: when the fact becomes true (validFrom) and stops being true
- *   (validUntil)
- *
- * Every assertion carries `validFrom`, `validUntil`, `assertedAt`, and
- * `supersededBy` fields. Status is computed dynamically from the current clock
- * and the assertion's lifecycle flags (retraction, supersession, expiration).
- *
- * TemporalStore:
- * - Creates assertions with explicit validity windows
- * - Retrieves assertions active at any point in time (past, present, future)
- * - Supports supersession chains (old fact replaced by new fact)
- * - Soft-delete via retraction (preserves full history)
- * - Conflict detection: finds multiple active assertions in the same namespace
- * - Export/import for persistence
- *
- * TemporalReasoner:
- * - High-level queries: whatWasTrue, whatIsTrue, whatWillBeTrue
- * - Change detection since a given timestamp
- * - Conflict detection at a point in time
- * - Forward projection of assertion validity
- *
- * @module @monomind/guidance/temporal
- */
-import { randomUUID } from 'node:crypto';
-// ============================================================================
-// Default Configuration
-// ============================================================================
-const DEFAULT_TEMPORAL_CONFIG = {
-    maxAssertions: 100_000,
-    autoExpireCheckIntervalMs: 60_000,
-};
-const SERIALIZATION_VERSION = 1;
-// ============================================================================
-// TemporalStore
-// ============================================================================
-/**
- * In-memory store for temporal assertions with bitemporal semantics.
- *
- * Assertions are indexed by ID and support supersession chains, retraction,
- * temporal queries (what was active at time T), and conflict detection.
- * Status is computed dynamically from the assertion's window and lifecycle
- * flags; callers never set status directly.
- */
-export class TemporalStore {
-    config;
-    assertions = new Map();
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_TEMPORAL_CONFIG, ...config };
-    }
-    /**
-     * Create a new temporal assertion.
-     *
-     * Records a claim with an explicit validity window. The assertion's status
-     * is computed automatically from the window and the current time.
-     *
-     * @param claim - The fact being asserted
-     * @param namespace - Grouping namespace
-     * @param window - Validity window (validFrom and validUntil)
-     * @param opts - Optional parameters (confidence, source, tags, metadata)
-     * @returns The newly created TemporalAssertion
-     */
-    assert(claim, namespace, window, opts = {}) {
-        const now = Date.now();
-        const assertion = {
-            id: opts.id ?? randomUUID(),
-            claim,
-            namespace,
-            window: {
-                validFrom: window.validFrom,
-                validUntil: window.validUntil,
-                assertedAt: now,
-                retractedAt: null,
-                supersededAt: null,
-            },
-            status: 'active', // placeholder; computed below
-            supersededBy: null,
-            supersedes: null,
-            confidence: clamp(opts.confidence ?? 1.0, 0, 1),
-            source: opts.source ?? 'system',
-            tags: opts.tags ? [...opts.tags] : [],
-            metadata: opts.metadata ? { ...opts.metadata } : {},
-        };
-        assertion.status = computeStatus(assertion, now);
-        this.assertions.set(assertion.id, assertion);
-        this.enforceCapacity();
-        return assertion;
-    }
-    /**
-     * Retrieve an assertion by ID.
-     *
-     * The returned assertion has its status recomputed against the current time.
-     *
-     * @param id - The assertion ID
-     * @returns The assertion, or undefined if not found
-     */
-    get(id) {
-        const assertion = this.assertions.get(id);
-        if (!assertion)
-            return undefined;
-        assertion.status = computeStatus(assertion, Date.now());
-        return assertion;
-    }
-    /**
-     * Get all assertions that were active at a specific point in time.
-     *
-     * An assertion is considered "active at time T" if:
-     * - Its validity window contains T (validFrom <= T and (validUntil is null or T < validUntil))
-     * - It has not been retracted
-     * - It has not been superseded
-     *
-     * @param pointInTime - The reference time (ms epoch)
-     * @param namespace - Optional namespace filter
-     * @returns Active assertions at the specified time
-     */
-    getActiveAt(pointInTime, namespace) {
-        const results = [];
-        for (const assertion of this.assertions.values()) {
-            if (namespace !== undefined && assertion.namespace !== namespace) {
-                continue;
-            }
-            const status = computeStatus(assertion, pointInTime);
-            if (status === 'active') {
-                // Update the stored status to reflect current time
-                assertion.status = computeStatus(assertion, Date.now());
-                results.push(assertion);
-            }
-        }
-        return results.sort((a, b) => b.window.assertedAt - a.window.assertedAt);
-    }
-    /**
-     * Get all assertions active right now.
-     *
-     * Convenience wrapper around `getActiveAt(Date.now())`.
-     *
-     * @param namespace - Optional namespace filter
-     * @returns Currently active assertions
-     */
-    getCurrentTruth(namespace) {
-        return this.getActiveAt(Date.now(), namespace);
-    }
-    /**
-     * Get the full history of a claim: all assertions (past and present) that
-     * share the same claim text and namespace, regardless of status.
-     *
-     * Results are ordered by assertedAt ascending (oldest first), giving a
-     * timeline of how the claim evolved.
-     *
-     * @param claim - The claim text to search for
-     * @param namespace - The namespace to search in
-     * @returns All matching assertions, oldest first
-     */
-    getHistory(claim, namespace) {
-        const now = Date.now();
-        const results = [];
-        for (const assertion of this.assertions.values()) {
-            if (assertion.claim === claim && assertion.namespace === namespace) {
-                assertion.status = computeStatus(assertion, now);
-                results.push(assertion);
-            }
-        }
-        return results.sort((a, b) => a.window.assertedAt - b.window.assertedAt);
-    }
-    /**
-     * Query assertions with multiple optional filters.
-     *
-     * All specified filters are ANDed together. Results are ordered by
-     * assertedAt descending (newest first).
-     *
-     * @param opts - Query filter options
-     * @returns Matching assertions
-     */
-    query(opts = {}) {
-        const now = Date.now();
-        const results = [];
-        for (const assertion of this.assertions.values()) {
-            assertion.status = computeStatus(assertion, now);
-            if (opts.namespace !== undefined && assertion.namespace !== opts.namespace) {
-                continue;
-            }
-            if (opts.pointInTime !== undefined) {
-                const statusAtTime = computeStatus(assertion, opts.pointInTime);
-                if (statusAtTime !== 'active')
-                    continue;
-            }
-            if (opts.status !== undefined && opts.status.length > 0) {
-                if (!opts.status.includes(assertion.status))
-                    continue;
-            }
-            if (opts.source !== undefined && assertion.source !== opts.source) {
-                continue;
-            }
-            if (opts.tags !== undefined && opts.tags.length > 0) {
-                const assertionTags = new Set(assertion.tags);
-                if (!opts.tags.every(t => assertionTags.has(t)))
-                    continue;
-            }
-            results.push(assertion);
-        }
-        return results.sort((a, b) => b.window.assertedAt - a.window.assertedAt);
-    }
-    /**
-     * Supersede an existing assertion with a new one.
-     *
-     * Marks the old assertion as superseded and creates a new assertion that
-     * declares it replaces the old one. The supersession chain is bidirectional:
-     * oldAssertion.supersededBy = newAssertion.id
-     * newAssertion.supersedes = oldAssertion.id
-     *
-     * @param oldId - ID of the assertion to supersede
-     * @param newClaim - The replacement claim text
-     * @param newWindow - The validity window for the replacement
-     * @param opts - Optional parameters for the new assertion
-     * @returns The new assertion, or undefined if the old one was not found
-     */
-    supersede(oldId, newClaim, newWindow, opts = {}) {
-        const old = this.assertions.get(oldId);
-        if (!old)
-            return undefined;
-        // Create the replacement assertion
-        const replacement = this.assert(newClaim, old.namespace, newWindow, opts);
-        // Link the chain
-        replacement.supersedes = oldId;
-        old.supersededBy = replacement.id;
-        old.window.supersededAt = replacement.window.assertedAt;
-        old.status = computeStatus(old, Date.now());
-        return replacement;
-    }
-    /**
-     * Retract an assertion (soft delete).
-     *
-     * The assertion is marked with a retractedAt timestamp and its status
-     * becomes 'retracted'. The assertion remains in the store for historical
-     * queries but is excluded from active truth queries.
-     *
-     * @param id - The assertion to retract
-     * @param _reason - Optional reason for retraction (stored in metadata)
-     * @returns The retracted assertion, or undefined if not found
-     */
-    retract(id, _reason) {
-        const assertion = this.assertions.get(id);
-        if (!assertion)
-            return undefined;
-        assertion.window.retractedAt = Date.now();
-        if (_reason !== undefined) {
-            assertion.metadata.retractedReason = _reason;
-        }
-        assertion.status = computeStatus(assertion, Date.now());
-        return assertion;
-    }
-    /**
-     * Get the full supersession timeline for an assertion.
-     *
-     * Follows the supersedes/supersededBy chain in both directions to build
-     * the complete lineage: all predecessors (oldest first) and all successors
-     * (newest last). Handles cycles by tracking visited IDs.
-     *
-     * @param id - The assertion to build a timeline for
-     * @returns The timeline, or undefined if not found
-     */
-    getTimeline(id) {
-        const assertion = this.assertions.get(id);
-        if (!assertion)
-            return undefined;
-        const now = Date.now();
-        assertion.status = computeStatus(assertion, now);
-        const visited = new Set([id]);
-        // Walk predecessors (what this assertion replaced)
-        const predecessors = [];
-        let currentId = assertion.supersedes;
-        while (currentId !== null) {
-            if (visited.has(currentId))
-                break;
-            visited.add(currentId);
-            const pred = this.assertions.get(currentId);
-            if (!pred)
-                break;
-            pred.status = computeStatus(pred, now);
-            predecessors.unshift(pred); // oldest first
-            currentId = pred.supersedes;
-        }
-        // Walk successors (what replaced this assertion)
-        const successors = [];
-        currentId = assertion.supersededBy;
-        while (currentId !== null) {
-            if (visited.has(currentId))
-                break;
-            visited.add(currentId);
-            const succ = this.assertions.get(currentId);
-            if (!succ)
-                break;
-            succ.status = computeStatus(succ, now);
-            successors.push(succ); // newest last
-            currentId = succ.supersededBy;
-        }
-        return { assertion, predecessors, successors };
-    }
-    /**
-     * Detect conflicting assertions: multiple assertions active at the same
-     * time in the same namespace.
-     *
-     * Returns groups of assertions that are simultaneously active, which may
-     * indicate contradictions that need resolution.
-     *
-     * @param namespace - The namespace to check
-     * @param pointInTime - The reference time (defaults to now)
-     * @returns Array of assertions that are concurrently active (empty if no conflicts)
-     */
-    reconcile(namespace, pointInTime) {
-        const refTime = pointInTime ?? Date.now();
-        const active = this.getActiveAt(refTime, namespace);
-        // A single or zero active assertions means no conflict
-        if (active.length <= 1)
-            return [];
-        return active;
-    }
-    /**
-     * Export all assertions for persistence.
-     *
-     * @returns Serializable store representation
-     */
-    exportAssertions() {
-        const now = Date.now();
-        const assertions = [];
-        for (const assertion of this.assertions.values()) {
-            assertion.status = computeStatus(assertion, now);
-            assertions.push({ ...assertion, metadata: { ...assertion.metadata } });
-        }
-        return {
-            assertions,
-            createdAt: new Date().toISOString(),
-            version: SERIALIZATION_VERSION,
-        };
-    }
-    /**
-     * Import previously exported assertions, replacing all current contents.
-     *
-     * @param data - Serialized store data
-     * @throws If the version is unsupported
-     */
-    importAssertions(data) {
-        if (data.version !== SERIALIZATION_VERSION) {
-            throw new Error(`Unsupported temporal store version: ${data.version} (expected ${SERIALIZATION_VERSION})`);
-        }
-        this.assertions.clear();
-        const now = Date.now();
-        for (const assertion of data.assertions) {
-            const imported = {
-                ...assertion,
-                tags: [...assertion.tags],
-                metadata: { ...assertion.metadata },
-            };
-            imported.status = computeStatus(imported, now);
-            this.assertions.set(imported.id, imported);
-        }
-    }
-    /**
-     * Remove expired assertions whose validity ended before the given timestamp.
-     *
-     * Only assertions with status 'expired' and validUntil before the cutoff
-     * are removed. Retracted and superseded assertions are preserved for
-     * historical traceability.
-     *
-     * @param beforeTimestamp - Remove assertions that expired before this time
-     * @returns Number of assertions pruned
-     */
-    pruneExpired(beforeTimestamp) {
-        let pruned = 0;
-        const now = Date.now();
-        for (const [id, assertion] of this.assertions) {
-            assertion.status = computeStatus(assertion, now);
-            if (assertion.status === 'expired' &&
-                assertion.window.validUntil !== null &&
-                assertion.window.validUntil < beforeTimestamp) {
-                this.assertions.delete(id);
-                pruned++;
-            }
-        }
-        return pruned;
-    }
-    /**
-     * Get the number of stored assertions.
-     */
-    get size() {
-        return this.assertions.size;
-    }
-    /**
-     * Get the current configuration.
-     */
-    getConfig() {
-        return { ...this.config };
-    }
-    /**
-     * Remove all assertions from the store.
-     */
-    clear() {
-        this.assertions.clear();
-    }
-    // ===== Private =====
-    /**
-     * Enforce the maximum assertion capacity by pruning the oldest expired
-     * assertions first.
-     */
-    enforceCapacity() {
-        if (this.assertions.size <= this.config.maxAssertions)
-            return;
-        const now = Date.now();
-        // Collect expired assertions sorted by validUntil ascending (oldest first)
-        const expired = [];
-        for (const [id, assertion] of this.assertions) {
-            const status = computeStatus(assertion, now);
-            if (status === 'expired' && assertion.window.validUntil !== null) {
-                expired.push({ id, validUntil: assertion.window.validUntil });
-            }
-        }
-        expired.sort((a, b) => a.validUntil - b.validUntil);
-        // Remove oldest expired until under capacity
-        let removed = 0;
-        const excess = this.assertions.size - this.config.maxAssertions;
-        for (const entry of expired) {
-            if (removed >= excess)
-                break;
-            this.assertions.delete(entry.id);
-            removed++;
-        }
-        // If still over capacity, remove oldest retracted
-        if (this.assertions.size > this.config.maxAssertions) {
-            const retracted = [];
-            for (const [id, assertion] of this.assertions) {
-                if (assertion.window.retractedAt !== null) {
-                    retracted.push({ id, retractedAt: assertion.window.retractedAt });
-                }
-            }
-            retracted.sort((a, b) => a.retractedAt - b.retractedAt);
-            const stillExcess = this.assertions.size - this.config.maxAssertions;
-            for (let i = 0; i < Math.min(stillExcess, retracted.length); i++) {
-                this.assertions.delete(retracted[i].id);
-            }
-        }
-    }
-}
-// ============================================================================
-// TemporalReasoner
-// ============================================================================
-/**
- * High-level temporal reasoning over a TemporalStore.
- *
- * Provides semantic queries like "what was true at time T", "what will be
- * true at time T", change detection, conflict detection, and forward
- * projection of assertion validity.
- */
-export class TemporalReasoner {
-    store;
-    constructor(store) {
-        this.store = store;
-    }
-    /**
-     * What was true at a past point in time?
-     *
-     * Returns all assertions that were active (valid, not retracted, not
-     * superseded) at the specified historical moment.
-     *
-     * @param namespace - The namespace to query
-     * @param pointInTime - The historical moment (ms epoch)
-     * @returns Assertions that were active at that time
-     */
-    whatWasTrue(namespace, pointInTime) {
-        return this.store.getActiveAt(pointInTime, namespace);
-    }
-    /**
-     * What is true right now?
-     *
-     * Returns all currently active assertions in the given namespace.
-     *
-     * @param namespace - The namespace to query
-     * @returns Currently active assertions
-     */
-    whatIsTrue(namespace) {
-        return this.store.getCurrentTruth(namespace);
-    }
-    /**
-     * What will be true at a future point in time?
-     *
-     * Returns assertions whose validity window includes the specified future
-     * time and that have not been retracted or superseded.
-     *
-     * @param namespace - The namespace to query
-     * @param futureTime - The future moment (ms epoch)
-     * @returns Assertions that will be active at that time
-     */
-    whatWillBeTrue(namespace, futureTime) {
-        return this.store.getActiveAt(futureTime, namespace);
-    }
-    /**
-     * Detect changes in a namespace since a given timestamp.
-     *
-     * Returns a list of changes ordered by their change time, including:
-     * - New assertions created after the timestamp
-     * - Assertions superseded after the timestamp
-     * - Assertions retracted after the timestamp
-     * - Assertions that expired after the timestamp
-     *
-     * @param namespace - The namespace to check
-     * @param sinceTimestamp - Only include changes after this time (ms epoch)
-     * @returns List of detected changes
-     */
-    hasChanged(namespace, sinceTimestamp) {
-        const changes = [];
-        const now = Date.now();
-        const all = this.store.query({ namespace });
-        for (const assertion of all) {
-            // New assertion
-            if (assertion.window.assertedAt > sinceTimestamp) {
-                changes.push({
-                    assertion,
-                    changeType: 'asserted',
-                    changedAt: assertion.window.assertedAt,
-                });
-            }
-            // Retracted
-            if (assertion.window.retractedAt !== null &&
-                assertion.window.retractedAt > sinceTimestamp) {
-                changes.push({
-                    assertion,
-                    changeType: 'retracted',
-                    changedAt: assertion.window.retractedAt,
-                });
-            }
-            // Superseded: we infer the supersession time from the successor's
-            // assertedAt, since the old assertion is marked superseded when the
-            // new one is created.
-            if (assertion.supersededBy !== null) {
-                const successor = this.store.get(assertion.supersededBy);
-                if (successor && successor.window.assertedAt > sinceTimestamp) {
-                    changes.push({
-                        assertion,
-                        changeType: 'superseded',
-                        changedAt: successor.window.assertedAt,
-                    });
-                }
-            }
-            // Expired: the assertion expired between sinceTimestamp and now
-            if (assertion.window.validUntil !== null &&
-                assertion.window.validUntil > sinceTimestamp &&
-                assertion.window.validUntil <= now &&
-                assertion.window.retractedAt === null &&
-                assertion.supersededBy === null) {
-                changes.push({
-                    assertion,
-                    changeType: 'expired',
-                    changedAt: assertion.window.validUntil,
-                });
-            }
-        }
-        return changes.sort((a, b) => a.changedAt - b.changedAt);
-    }
-    /**
-     * Detect conflicting (contradictory) assertions active at the same time
-     * in the same namespace.
-     *
-     * Returns all concurrently active assertions if there are two or more.
-     * An empty array means no conflicts.
-     *
-     * @param namespace - The namespace to check
-     * @param pointInTime - The reference time (defaults to now)
-     * @returns Conflicting assertions, or empty if no conflicts
-     */
-    conflictsAt(namespace, pointInTime) {
-        return this.store.reconcile(namespace, pointInTime);
-    }
-    /**
-     * Project an assertion forward: will it still be valid at a future time?
-     *
-     * Checks whether the assertion's validity window includes the future
-     * timestamp and the assertion has not been retracted or superseded.
-     *
-     * @param assertionId - The assertion to project
-     * @param futureTimestamp - The future time to check (ms epoch)
-     * @returns true if the assertion will be active at the future time
-     */
-    projectForward(assertionId, futureTimestamp) {
-        const assertion = this.store.get(assertionId);
-        if (!assertion)
-            return false;
-        const futureStatus = computeStatus(assertion, futureTimestamp);
-        return futureStatus === 'active';
-    }
-}
-// ============================================================================
-// Factory Functions
-// ============================================================================
-/**
- * Create a TemporalStore with optional configuration.
- *
- * @param config - Partial configuration; unspecified values use defaults
- * @returns A fresh TemporalStore
- */
-export function createTemporalStore(config) {
-    return new TemporalStore(config);
-}
-/**
- * Create a TemporalReasoner backed by the given store.
- *
- * @param store - The TemporalStore to reason over
- * @returns A fresh TemporalReasoner
- */
-export function createTemporalReasoner(store) {
-    return new TemporalReasoner(store);
-}
-// ============================================================================
-// Helpers
-// ============================================================================
-/**
- * Compute the temporal status of an assertion at a given reference time.
- *
- * Priority order:
- * 1. retracted (retractedAt is set)
- * 2. superseded (supersededBy is set)
- * 3. expired (validUntil <= referenceTime)
- * 4. active (validFrom <= referenceTime and window is open)
- * 5. future (validFrom > referenceTime)
- *
- * @param assertion - The assertion to evaluate
- * @param referenceTime - The time to compute status against (ms epoch)
- * @returns The computed TemporalStatus
- */
-function computeStatus(assertion, referenceTime) {
-    // Retraction takes absolute priority — only if it had occurred by referenceTime
-    if (assertion.window.retractedAt !== null && referenceTime >= assertion.window.retractedAt) {
-        return 'retracted';
-    }
-    // Supersession takes next priority — only if it had occurred by referenceTime
-    if (assertion.supersededBy !== null && assertion.window.supersededAt !== null && referenceTime >= assertion.window.supersededAt) {
-        return 'superseded';
-    }
-    // Check temporal position relative to validity window
-    const { validFrom, validUntil } = assertion.window;
-    if (validUntil !== null && referenceTime >= validUntil) {
-        return 'expired';
-    }
-    if (referenceTime >= validFrom) {
-        return 'active';
-    }
-    return 'future';
-}
-/**
- * Clamp a number to the range [min, max].
- */
-function clamp(value, min, max) {
-    return Math.min(max, Math.max(min, value));
-}
-//# sourceMappingURL=temporal.js.map