causantic 0.2.0

package/dist/temporal/clock-compactor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-compactor.js","sourceRoot":"","sources":["../../src/temporal/clock-compactor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,QAAQ,EACR,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAA0B,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACnF,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAcvD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,YAAgC;IAEhC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,IAAI,SAAS,EAAE,CAAC,WAAW,IAAI,oBAAoB,CAAC;IAE/E,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,YAAY,EAAE,EAAE;YAChB,eAAe,EAAE,CAAC;YAClB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACnC,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,YAAY,GAAG,MAAM,wBAAwB,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE5F,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,4CAA4C;QAC5C,MAAM,QAAQ,GAAgB,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnD,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC/B,QAAQ,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC;YACvB,CAAC;QACH,CAAC;QACD,iBAAiB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACL,YAAY;QACZ,eAAe,EAAE,QAAQ,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM;QACtD,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,wBAAwB,CACrC,WAAmB,EACnB,OAAe,EACf,QAAqB,EACrB,MAAyB;IAEzB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IAEnB,sEAAsE;IACtE,mDAAmD;IACnD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC;;;;;GAKvB,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,OAAO,KAAK,CAAoC,CAAC;IAE1E,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,YAAY;YAAE,SAAS;QAEhC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,CAAC,CAAC,OAAO,IAAI,SAAS,CAAC;YAAE,SAAS;QAEtC,mCAAmC;QACnC,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAEnD,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,CAAC,+CAA+C;QAC9D,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,CAAC,qCAAqC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB;IAK/C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACjE,OAAO;QACP,KAAK;KACN,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,MAAM;QACzB,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QACvD,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;KACjD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,WAAmB;IAEnB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IACnB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE/C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC;;;;;GAKvB,CAAC,CAAC,GAAG,CAAC,WAAW,CAAoC,CAAC;IAEvD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,GAAG,CAAC,YAAY;YAAE,SAAS;QAEhC,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAE3C,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IACvD,MAAM,WAAW,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAgB,EAAE,CAAC;IAEjC,KAAK,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;QACpC,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,iBAAiB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACzC,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/temporal/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Temporal module exports.
+ */
+export * from './vector-clock.js';
+export * from './clock-compactor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/temporal/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/temporal/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/temporal/index.js

@@ -0,0 +1,6 @@
+/**
+ * Temporal module exports.
+ */
+export * from './vector-clock.js';
+export * from './clock-compactor.js';
+//# sourceMappingURL=index.js.map

package/dist/temporal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/temporal/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/temporal/vector-clock.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Vector clock implementation for D-T-D memory graph.
+ *
+ * D-T-D = Data-Transformation-Data: an abstract representation of any
+ * processing step as f(input) → output. The "T" can be any transformation:
+ * Claude reasoning, human thinking, tool execution, etc.
+ *
+ * This representation is conducive to graph-based reasoning without getting
+ * bogged down in compositional semantics, input/output types, or arities.
+ *
+ * Vector clocks capture logical causal distance (D-T-D hop count) instead of
+ * physical time. This is more meaningful for memory retrieval - especially
+ * with parallel thought streams that progress independently.
+ *
+ * Semantics:
+ * - Domain: Per-project (each project has its own clock set)
+ * - Entries: Per thought stream (main agent, human, each sub-agent)
+ * - Tick: Each D-T-D cycle increments that stream's clock entry
+ * - Reference clock: Element-wise max of all stream clocks
+ * - Sub-agent spawn: Inherits parent clock
+ * - Sub-agent debrief: Merges back via element-wise max
+ */
+/**
+ * A vector clock maps agent IDs to their tick counts.
+ */
+export interface VectorClock {
+    [agentId: string]: number;
+}
+/** Main UI agent identifier */
+export declare const MAIN_AGENT_ID = "ui";
+/** Human user agent identifier */
+export declare const HUMAN_AGENT_ID = "human";
+/**
+ * Create an empty vector clock.
+ */
+export declare function createClock(): VectorClock;
+/**
+ * Increment the tick count for a specific agent.
+ * Returns a new clock (immutable operation).
+ *
+ * @param clock - Current vector clock
+ * @param agentId - Agent to increment
+ * @returns New vector clock with incremented tick
+ */
+export declare function tick(clock: VectorClock, agentId: string): VectorClock;
+/**
+ * Merge two vector clocks by taking the element-wise maximum.
+ * Used when:
+ * - Sub-agent inherits parent clock at spawn
+ * - Parent merges sub-agent clock at debrief
+ * - Computing reference clock from all agent clocks
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns Merged vector clock with max of each entry
+ */
+export declare function merge(a: VectorClock, b: VectorClock): VectorClock;
+/**
+ * Calculate the hop count (logical distance) between an edge's clock
+ * and the current reference clock.
+ *
+ * Only entries present in both clocks contribute to the sum:
+ * - Agents that didn't exist at edge creation (not in edgeClock) are skipped
+ * - Agents that have since terminated (not in refClock) contribute 0
+ *
+ * This represents how many D-T-D cycles have occurred in the thought streams
+ * that were active when the edge was created and still exist now.
+ *
+ * @param edgeClock - Vector clock stamped on the edge
+ * @param refClock - Current reference clock for the project
+ * @returns Total hop count (sum of per-agent differences for shared entries)
+ */
+export declare function hopCount(edgeClock: VectorClock, refClock: VectorClock): number;
+/**
+ * Check if clock A happened before clock B.
+ * A happened before B if all entries in A are <= entries in B
+ * and at least one entry in A is < the corresponding entry in B.
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns true if a happened before b
+ */
+export declare function happenedBefore(a: VectorClock, b: VectorClock): boolean;
+/**
+ * Check if two clocks are concurrent (neither happened before the other, and not equal).
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns true if clocks are concurrent (not equal and incomparable)
+ */
+export declare function areConcurrent(a: VectorClock, b: VectorClock): boolean;
+/**
+ * Compare two clocks and return their causal relationship.
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns 'before' if a < b, 'after' if a > b, 'concurrent' if neither, 'equal' if same
+ */
+export declare function compare(a: VectorClock, b: VectorClock): 'before' | 'after' | 'concurrent' | 'equal';
+/**
+ * Get the total number of ticks across all agents.
+ * Useful for rough ordering when vector clocks are concurrent.
+ *
+ * @param clock - Vector clock
+ * @returns Sum of all tick counts
+ */
+export declare function totalTicks(clock: VectorClock): number;
+/**
+ * Serialize a vector clock to JSON string for database storage.
+ *
+ * @param clock - Vector clock to serialize
+ * @returns JSON string representation
+ */
+export declare function serialize(clock: VectorClock): string;
+/**
+ * Deserialize a vector clock from JSON string.
+ *
+ * @param json - JSON string or null
+ * @returns Deserialized vector clock (empty if null or invalid)
+ */
+export declare function deserialize(json: string | null | undefined): VectorClock;
+/**
+ * Clone a vector clock.
+ *
+ * @param clock - Clock to clone
+ * @returns New clock with same values
+ */
+export declare function clone(clock: VectorClock): VectorClock;
+/**
+ * Check if a clock is empty (no ticks recorded).
+ *
+ * @param clock - Vector clock to check
+ * @returns true if clock has no entries or all entries are 0
+ */
+export declare function isEmpty(clock: VectorClock): boolean;
+/**
+ * Get all agent IDs present in a clock.
+ *
+ * @param clock - Vector clock
+ * @returns Array of agent IDs
+ */
+export declare function getAgentIds(clock: VectorClock): string[];
+//# sourceMappingURL=vector-clock.d.ts.map

package/dist/temporal/vector-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-clock.d.ts","sourceRoot":"","sources":["../../src/temporal/vector-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,+BAA+B;AAC/B,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC,kCAAkC;AAClC,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;GAEG;AACH,wBAAgB,WAAW,IAAI,WAAW,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,WAAW,CAMjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,GAAG,MAAM,CAO9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAiBtE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAgBrE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,WAAW,EACd,CAAC,EAAE,WAAW,GACb,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,CAe7C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,CAmBxE;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAGnD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,CAExD"}

package/dist/temporal/vector-clock.js

@@ -0,0 +1,231 @@
+/**
+ * Vector clock implementation for D-T-D memory graph.
+ *
+ * D-T-D = Data-Transformation-Data: an abstract representation of any
+ * processing step as f(input) → output. The "T" can be any transformation:
+ * Claude reasoning, human thinking, tool execution, etc.
+ *
+ * This representation is conducive to graph-based reasoning without getting
+ * bogged down in compositional semantics, input/output types, or arities.
+ *
+ * Vector clocks capture logical causal distance (D-T-D hop count) instead of
+ * physical time. This is more meaningful for memory retrieval - especially
+ * with parallel thought streams that progress independently.
+ *
+ * Semantics:
+ * - Domain: Per-project (each project has its own clock set)
+ * - Entries: Per thought stream (main agent, human, each sub-agent)
+ * - Tick: Each D-T-D cycle increments that stream's clock entry
+ * - Reference clock: Element-wise max of all stream clocks
+ * - Sub-agent spawn: Inherits parent clock
+ * - Sub-agent debrief: Merges back via element-wise max
+ */
+import { createLogger } from '../utils/logger.js';
+const log = createLogger('vector-clock');
+/** Main UI agent identifier */
+export const MAIN_AGENT_ID = 'ui';
+/** Human user agent identifier */
+export const HUMAN_AGENT_ID = 'human';
+/**
+ * Create an empty vector clock.
+ */
+export function createClock() {
+    return {};
+}
+/**
+ * Increment the tick count for a specific agent.
+ * Returns a new clock (immutable operation).
+ *
+ * @param clock - Current vector clock
+ * @param agentId - Agent to increment
+ * @returns New vector clock with incremented tick
+ */
+export function tick(clock, agentId) {
+    return { ...clock, [agentId]: (clock[agentId] ?? 0) + 1 };
+}
+/**
+ * Merge two vector clocks by taking the element-wise maximum.
+ * Used when:
+ * - Sub-agent inherits parent clock at spawn
+ * - Parent merges sub-agent clock at debrief
+ * - Computing reference clock from all agent clocks
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns Merged vector clock with max of each entry
+ */
+export function merge(a, b) {
+    const result = { ...a };
+    for (const [id, ticks] of Object.entries(b)) {
+        result[id] = Math.max(result[id] ?? 0, ticks);
+    }
+    return result;
+}
+/**
+ * Calculate the hop count (logical distance) between an edge's clock
+ * and the current reference clock.
+ *
+ * Only entries present in both clocks contribute to the sum:
+ * - Agents that didn't exist at edge creation (not in edgeClock) are skipped
+ * - Agents that have since terminated (not in refClock) contribute 0
+ *
+ * This represents how many D-T-D cycles have occurred in the thought streams
+ * that were active when the edge was created and still exist now.
+ *
+ * @param edgeClock - Vector clock stamped on the edge
+ * @param refClock - Current reference clock for the project
+ * @returns Total hop count (sum of per-agent differences for shared entries)
+ */
+export function hopCount(edgeClock, refClock) {
+    let hops = 0;
+    for (const agentId of Object.keys(edgeClock)) {
+        // refClock[agentId] ?? 0: if agent terminated, contributes 0
+        hops += Math.max(0, (refClock[agentId] ?? 0) - edgeClock[agentId]);
+    }
+    return hops;
+}
+/**
+ * Check if clock A happened before clock B.
+ * A happened before B if all entries in A are <= entries in B
+ * and at least one entry in A is < the corresponding entry in B.
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns true if a happened before b
+ */
+export function happenedBefore(a, b) {
+    const allKeys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    let hasStrictlyLess = false;
+    for (const key of allKeys) {
+        const aVal = a[key] ?? 0;
+        const bVal = b[key] ?? 0;
+        if (aVal > bVal) {
+            return false; // a has a larger value, so a did not happen before b
+        }
+        if (aVal < bVal) {
+            hasStrictlyLess = true;
+        }
+    }
+    return hasStrictlyLess;
+}
+/**
+ * Check if two clocks are concurrent (neither happened before the other, and not equal).
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns true if clocks are concurrent (not equal and incomparable)
+ */
+export function areConcurrent(a, b) {
+    // First check if they're equal
+    const allKeys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    let hasAnyDifference = false;
+    for (const key of allKeys) {
+        if ((a[key] ?? 0) !== (b[key] ?? 0)) {
+            hasAnyDifference = true;
+            break;
+        }
+    }
+    if (!hasAnyDifference) {
+        return false; // Equal clocks are not concurrent
+    }
+    return !happenedBefore(a, b) && !happenedBefore(b, a);
+}
+/**
+ * Compare two clocks and return their causal relationship.
+ *
+ * @param a - First vector clock
+ * @param b - Second vector clock
+ * @returns 'before' if a < b, 'after' if a > b, 'concurrent' if neither, 'equal' if same
+ */
+export function compare(a, b) {
+    if (happenedBefore(a, b))
+        return 'before';
+    if (happenedBefore(b, a))
+        return 'after';
+    // Check if equal
+    const allKeys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    let isEqual = true;
+    for (const key of allKeys) {
+        if ((a[key] ?? 0) !== (b[key] ?? 0)) {
+            isEqual = false;
+            break;
+        }
+    }
+    return isEqual ? 'equal' : 'concurrent';
+}
+/**
+ * Get the total number of ticks across all agents.
+ * Useful for rough ordering when vector clocks are concurrent.
+ *
+ * @param clock - Vector clock
+ * @returns Sum of all tick counts
+ */
+export function totalTicks(clock) {
+    return Object.values(clock).reduce((sum, t) => sum + t, 0);
+}
+/**
+ * Serialize a vector clock to JSON string for database storage.
+ *
+ * @param clock - Vector clock to serialize
+ * @returns JSON string representation
+ */
+export function serialize(clock) {
+    return JSON.stringify(clock);
+}
+/**
+ * Deserialize a vector clock from JSON string.
+ *
+ * @param json - JSON string or null
+ * @returns Deserialized vector clock (empty if null or invalid)
+ */
+export function deserialize(json) {
+    if (!json)
+        return {};
+    try {
+        const parsed = JSON.parse(json);
+        // Validate it's an object with number values
+        if (typeof parsed === 'object' && parsed !== null) {
+            const clock = {};
+            for (const [key, value] of Object.entries(parsed)) {
+                if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+                    clock[key] = value;
+                }
+            }
+            return clock;
+        }
+        return {};
+    }
+    catch (err) {
+        log.warn(`Failed to deserialize clock: ${json}`, { error: err instanceof Error ? err.message : String(err) });
+        return {};
+    }
+}
+/**
+ * Clone a vector clock.
+ *
+ * @param clock - Clock to clone
+ * @returns New clock with same values
+ */
+export function clone(clock) {
+    return { ...clock };
+}
+/**
+ * Check if a clock is empty (no ticks recorded).
+ *
+ * @param clock - Vector clock to check
+ * @returns true if clock has no entries or all entries are 0
+ */
+export function isEmpty(clock) {
+    const values = Object.values(clock);
+    return values.length === 0 || values.every((v) => v === 0);
+}
+/**
+ * Get all agent IDs present in a clock.
+ *
+ * @param clock - Vector clock
+ * @returns Array of agent IDs
+ */
+export function getAgentIds(clock) {
+    return Object.keys(clock).filter((id) => clock[id] > 0);
+}
+//# sourceMappingURL=vector-clock.js.map

package/dist/temporal/vector-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-clock.js","sourceRoot":"","sources":["../../src/temporal/vector-clock.ts"],"names":[],"mappings":"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"}

package/dist/utils/angular-distance.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Angular distance utilities for embedding comparison.
+ *
+ * Angular distance = arccos(cosine_similarity) / pi
+ * Yields [0, 1] where 0 = identical, 1 = opposite.
+ * This is a proper metric (satisfies triangle inequality)
+ * and works well with HDBSCAN.
+ */
+/**
+ * Compute the dot product of two vectors.
+ */
+export declare function dot(a: number[], b: number[]): number;
+/**
+ * Compute the L2 norm of a vector.
+ */
+export declare function norm(a: number[]): number;
+/**
+ * Cosine similarity between two vectors. Returns [-1, 1].
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Angular distance between two vectors. Returns [0, 1].
+ * 0 = identical direction, 1 = opposite direction.
+ */
+export declare function angularDistance(a: number[], b: number[]): number;
+/**
+ * Compute pairwise angular distance matrix.
+ * Returns a flat number[][] suitable for HDBSCAN.
+ */
+export declare function distanceMatrix(embeddings: number[][]): number[][];
+//# sourceMappingURL=angular-distance.d.ts.map

package/dist/utils/angular-distance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular-distance.d.ts","sourceRoot":"","sources":["../../src/utils/angular-distance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAMpD;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAExC;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAOjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAGhE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,CAejE"}

package/dist/utils/angular-distance.js

@@ -0,0 +1,61 @@
+/**
+ * Angular distance utilities for embedding comparison.
+ *
+ * Angular distance = arccos(cosine_similarity) / pi
+ * Yields [0, 1] where 0 = identical, 1 = opposite.
+ * This is a proper metric (satisfies triangle inequality)
+ * and works well with HDBSCAN.
+ */
+/**
+ * Compute the dot product of two vectors.
+ */
+export function dot(a, b) {
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        sum += a[i] * b[i];
+    }
+    return sum;
+}
+/**
+ * Compute the L2 norm of a vector.
+ */
+export function norm(a) {
+    return Math.sqrt(dot(a, a));
+}
+/**
+ * Cosine similarity between two vectors. Returns [-1, 1].
+ */
+export function cosineSimilarity(a, b) {
+    const d = dot(a, b);
+    const na = norm(a);
+    const nb = norm(b);
+    if (na === 0 || nb === 0)
+        return 0;
+    // Clamp to [-1, 1] to handle floating point errors
+    return Math.max(-1, Math.min(1, d / (na * nb)));
+}
+/**
+ * Angular distance between two vectors. Returns [0, 1].
+ * 0 = identical direction, 1 = opposite direction.
+ */
+export function angularDistance(a, b) {
+    const cos = cosineSimilarity(a, b);
+    return Math.acos(cos) / Math.PI;
+}
+/**
+ * Compute pairwise angular distance matrix.
+ * Returns a flat number[][] suitable for HDBSCAN.
+ */
+export function distanceMatrix(embeddings) {
+    const n = embeddings.length;
+    const matrix = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            const d = angularDistance(embeddings[i], embeddings[j]);
+            matrix[i][j] = d;
+            matrix[j][i] = d;
+        }
+    }
+    return matrix;
+}
+//# sourceMappingURL=angular-distance.js.map

package/dist/utils/angular-distance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular-distance.js","sourceRoot":"","sources":["../../src/utils/angular-distance.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,UAAU,GAAG,CAAC,CAAW,EAAE,CAAW;IAC1C,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAC,CAAW;IAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,mDAAmD;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,CAAW,EAAE,CAAW;IACtD,MAAM,GAAG,GAAG,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,UAAsB;IACnD,MAAM,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAC5B,MAAM,MAAM,GAAe,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,CACxD,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACrB,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/B,MAAM,CAAC,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;YACxD,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/array-utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared array utility functions.
+ * Quickselect algorithm for finding k-th smallest element.
+ */
+/**
+ * Quickselect algorithm to find k-th smallest element.
+ * Average O(n), worst case O(n^2).
+ *
+ * Makes a copy of the array to avoid modifying the original.
+ *
+ * @param arr - Input array
+ * @param k - Zero-based index of the desired element
+ * @returns The k-th smallest element
+ */
+export declare function quickselect(arr: number[], k: number): number;
+/**
+ * In-place quickselect using median-of-three pivot selection.
+ */
+export declare function quickselectInPlace(arr: number[], left: number, right: number, k: number): number;
+/**
+ * Partition array around pivot value.
+ */
+export declare function partition(arr: number[], left: number, right: number, pivotIndex: number): number;
+/**
+ * Swap two elements in an array.
+ */
+export declare function swap(arr: number[], i: number, j: number): void;
+//# sourceMappingURL=array-utils.d.ts.map

package/dist/utils/array-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils.d.ts","sourceRoot":"","sources":["../../src/utils/array-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAahG;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAchG;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAI9D"}

package/dist/utils/array-utils.js

@@ -0,0 +1,67 @@
+/**
+ * Shared array utility functions.
+ * Quickselect algorithm for finding k-th smallest element.
+ */
+/**
+ * Quickselect algorithm to find k-th smallest element.
+ * Average O(n), worst case O(n^2).
+ *
+ * Makes a copy of the array to avoid modifying the original.
+ *
+ * @param arr - Input array
+ * @param k - Zero-based index of the desired element
+ * @returns The k-th smallest element
+ */
+export function quickselect(arr, k) {
+    if (arr.length === 0)
+        return 0;
+    if (k >= arr.length)
+        k = arr.length - 1;
+    const copy = arr.slice();
+    return quickselectInPlace(copy, 0, copy.length - 1, k);
+}
+/**
+ * In-place quickselect using median-of-three pivot selection.
+ */
+export function quickselectInPlace(arr, left, right, k) {
+    if (left === right)
+        return arr[left];
+    const mid = Math.floor((left + right) / 2);
+    if (arr[mid] < arr[left])
+        swap(arr, left, mid);
+    if (arr[right] < arr[left])
+        swap(arr, left, right);
+    if (arr[right] < arr[mid])
+        swap(arr, mid, right);
+    const pivotIndex = partition(arr, left, right, mid);
+    if (k === pivotIndex)
+        return arr[k];
+    if (k < pivotIndex)
+        return quickselectInPlace(arr, left, pivotIndex - 1, k);
+    return quickselectInPlace(arr, pivotIndex + 1, right, k);
+}
+/**
+ * Partition array around pivot value.
+ */
+export function partition(arr, left, right, pivotIndex) {
+    const pivotValue = arr[pivotIndex];
+    swap(arr, pivotIndex, right);
+    let storeIndex = left;
+    for (let i = left; i < right; i++) {
+        if (arr[i] < pivotValue) {
+            swap(arr, i, storeIndex);
+            storeIndex++;
+        }
+    }
+    swap(arr, storeIndex, right);
+    return storeIndex;
+}
+/**
+ * Swap two elements in an array.
+ */
+export function swap(arr, i, j) {
+    const temp = arr[i];
+    arr[i] = arr[j];
+    arr[j] = temp;
+}
+//# sourceMappingURL=array-utils.js.map

package/dist/utils/array-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array-utils.js","sourceRoot":"","sources":["../../src/utils/array-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,GAAa,EAAE,CAAS;IAClD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM;QAAE,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAExC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC;IACzB,OAAO,kBAAkB,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAa,EAAE,IAAY,EAAE,KAAa,EAAE,CAAS;IACtF,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC;IAErC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IACnD,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC;QAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAEjD,MAAM,UAAU,GAAG,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAEpD,IAAI,CAAC,KAAK,UAAU;QAAE,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,UAAU;QAAE,OAAO,kBAAkB,CAAC,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5E,OAAO,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAa,EAAE,IAAY,EAAE,KAAa,EAAE,UAAkB;IACtF,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC7B,IAAI,UAAU,GAAG,IAAI,CAAC;IAEtB,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,EAAE,CAAC;YACxB,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC;YACzB,UAAU,EAAE,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC7B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,IAAI,CAAC,GAAa,EAAE,CAAS,EAAE,CAAS;IACtD,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IACpB,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IAChB,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/utils/embedding-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared embedding serialization utilities.
+ * Used by vector-store and embedding-cache for SQLite BLOB storage.
+ */
+/**
+ * Serialize an embedding to a Buffer for SQLite storage.
+ *
+ * Uses Float32Array for efficient storage (4 bytes per dimension).
+ * A 1024-dimension embedding uses 4KB of storage.
+ *
+ * @param embedding - Array of floating point values
+ * @returns Buffer containing Float32Array binary representation
+ */
+export declare function serializeEmbedding(embedding: number[]): Buffer;
+/**
+ * Deserialize an embedding from a SQLite Buffer.
+ *
+ * Reconstructs the Float32Array from the raw buffer bytes,
+ * handling byte offset alignment properly.
+ *
+ * @param buffer - Buffer from SQLite BLOB column
+ * @returns Array of floating point values
+ */
+export declare function deserializeEmbedding(buffer: Buffer): number[];
+//# sourceMappingURL=embedding-utils.d.ts.map

package/dist/utils/embedding-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-utils.d.ts","sourceRoot":"","sources":["../../src/utils/embedding-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAO7D"}