claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/guidance/dist/temporal.js

@@ -0,0 +1,658 @@
+/**
+ * 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 @claude-flow/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,
+            },
+            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.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
+    if (assertion.window.retractedAt !== null) {
+        return 'retracted';
+    }
+    // Supersession takes next priority
+    if (assertion.supersededBy !== null) {
+        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