@ai2070/memex 0.9.0

package/src/integrity.ts

@@ -0,0 +1,378 @@
+import type {
+  GraphState,
+  MemoryItem,
+  Edge,
+  MemoryLifecycleEvent,
+  ScoreWeights,
+  ScoredItem,
+} from "./types.js";
+import { applyCommand } from "./reducer.js";
+import { getEdges, getChildren, getScoredItems } from "./query.js";
+import { uuidv7 } from "uuidv7";
+
+// ---------------------------------------------------------------------------
+// 1. Temporal forking — conflict detection & resolution
+// ---------------------------------------------------------------------------
+
+export interface Contradiction {
+  a: MemoryItem;
+  b: MemoryItem;
+  edge?: Edge;
+}
+
+/**
+ * Find all active CONTRADICTS edges and return the item pairs.
+ */
+export function getContradictions(state: GraphState): Contradiction[] {
+  const contradictEdges = getEdges(state, {
+    kind: "CONTRADICTS",
+    active_only: true,
+  });
+  const results: Contradiction[] = [];
+  for (const edge of contradictEdges) {
+    const a = state.items.get(edge.from);
+    const b = state.items.get(edge.to);
+    if (a && b) results.push({ a, b, edge });
+  }
+  return results;
+}
+
+/**
+ * Mark two items as contradicting each other.
+ * Creates a CONTRADICTS edge between them.
+ */
+export function markContradiction(
+  state: GraphState,
+  itemIdA: string,
+  itemIdB: string,
+  author: string,
+  meta?: Record<string, unknown>,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  return applyCommand(state, {
+    type: "edge.create",
+    edge: {
+      edge_id: uuidv7(),
+      from: itemIdA,
+      to: itemIdB,
+      kind: "CONTRADICTS",
+      author,
+      source_kind: "derived_deterministic",
+      authority: 1,
+      active: true,
+      meta,
+    },
+  });
+}
+
+/**
+ * Resolve a contradiction by marking the winner as superseding the loser.
+ * - Creates a SUPERSEDES edge (winner -> loser)
+ * - Lowers the loser's authority
+ * - Retracts the CONTRADICTS edge
+ */
+export function resolveContradiction(
+  state: GraphState,
+  winnerId: string,
+  loserId: string,
+  author: string,
+  reason?: string,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  let current = state;
+  const allEvents: MemoryLifecycleEvent[] = [];
+
+  // find and retract the CONTRADICTS edge(s) between them
+  // collect matching edges first to avoid iterating a map while mutating state
+  const toRetract: string[] = [];
+  for (const edge of current.edges.values()) {
+    if (
+      edge.kind === "CONTRADICTS" &&
+      edge.active &&
+      ((edge.from === winnerId && edge.to === loserId) ||
+        (edge.from === loserId && edge.to === winnerId))
+    ) {
+      toRetract.push(edge.edge_id);
+    }
+  }
+
+  for (const edgeId of toRetract) {
+    const r = applyCommand(current, {
+      type: "edge.retract",
+      edge_id: edgeId,
+      author,
+      reason,
+    });
+    current = r.state;
+    allEvents.push(...r.events);
+  }
+
+  if (toRetract.length === 0) {
+    throw new Error(
+      `No active CONTRADICTS edge between ${winnerId} and ${loserId}`,
+    );
+  }
+
+  // create SUPERSEDES edge
+  const r1 = applyCommand(current, {
+    type: "edge.create",
+    edge: {
+      edge_id: uuidv7(),
+      from: winnerId,
+      to: loserId,
+      kind: "SUPERSEDES",
+      author,
+      source_kind: "derived_deterministic",
+      authority: 1,
+      active: true,
+      meta: reason ? { reason } : undefined,
+    },
+  });
+  current = r1.state;
+  allEvents.push(...r1.events);
+
+  // lower loser's authority
+  const loser = current.items.get(loserId);
+  if (loser) {
+    const r2 = applyCommand(current, {
+      type: "memory.update",
+      item_id: loserId,
+      partial: { authority: loser.authority * 0.1 },
+      author,
+      reason,
+    });
+    current = r2.state;
+    allEvents.push(...r2.events);
+  }
+
+  return { state: current, events: allEvents };
+}
+
+// ---------------------------------------------------------------------------
+// 2. Observational continuity — stale detection & cascade
+// ---------------------------------------------------------------------------
+
+export interface StaleItem {
+  item: MemoryItem;
+  missing_parents: string[];
+}
+
+/**
+ * Find items whose parents have been retracted (missing from state).
+ */
+export function getStaleItems(state: GraphState): StaleItem[] {
+  const results: StaleItem[] = [];
+  for (const item of state.items.values()) {
+    if (!item.parents || item.parents.length === 0) continue;
+    const missing = item.parents.filter((pid) => !state.items.has(pid));
+    if (missing.length > 0) {
+      results.push({ item, missing_parents: missing });
+    }
+  }
+  return results;
+}
+
+/**
+ * Find items that depend on a specific item (directly or transitively).
+ */
+export function getDependents(
+  state: GraphState,
+  itemId: string,
+  transitive = false,
+): MemoryItem[] {
+  const direct = getChildren(state, itemId);
+  if (!transitive) return direct;
+
+  const visited = new Set<string>();
+  const result: MemoryItem[] = [];
+  const queue = [...direct];
+
+  while (queue.length > 0) {
+    const item = queue.pop()!;
+    if (visited.has(item.id)) continue;
+    visited.add(item.id);
+    result.push(item);
+    queue.push(...getChildren(state, item.id));
+  }
+
+  return result;
+}
+
+/**
+ * Cascade retraction: retract an item and all its transitive dependents.
+ */
+export function cascadeRetract(
+  state: GraphState,
+  itemId: string,
+  author: string,
+  reason?: string,
+): { state: GraphState; events: MemoryLifecycleEvent[]; retracted: string[] } {
+  const dependents = getDependents(state, itemId, true);
+  let current = state;
+  const allEvents: MemoryLifecycleEvent[] = [];
+  const retracted: string[] = [];
+
+  // retract dependents first (leaves before roots)
+  for (const dep of dependents.reverse()) {
+    if (!current.items.has(dep.id)) continue;
+    const r = applyCommand(current, {
+      type: "memory.retract",
+      item_id: dep.id,
+      author,
+      reason: reason ?? `parent ${itemId} retracted`,
+    });
+    current = r.state;
+    allEvents.push(...r.events);
+    retracted.push(dep.id);
+  }
+
+  // retract the item itself
+  if (current.items.has(itemId)) {
+    const r = applyCommand(current, {
+      type: "memory.retract",
+      item_id: itemId,
+      author,
+      reason,
+    });
+    current = r.state;
+    allEvents.push(...r.events);
+    retracted.push(itemId);
+  }
+
+  return { state: current, events: allEvents, retracted };
+}
+
+// ---------------------------------------------------------------------------
+// 3. Recognition vs discovery — identity / aliasing
+// ---------------------------------------------------------------------------
+
+/**
+ * Mark two items as referring to the same entity.
+ * Creates bidirectional ALIAS edges.
+ */
+export function markAlias(
+  state: GraphState,
+  itemIdA: string,
+  itemIdB: string,
+  author: string,
+  meta?: Record<string, unknown>,
+): { state: GraphState; events: MemoryLifecycleEvent[] } {
+  let current = state;
+  const allEvents: MemoryLifecycleEvent[] = [];
+
+  const r1 = applyCommand(current, {
+    type: "edge.create",
+    edge: {
+      edge_id: uuidv7(),
+      from: itemIdA,
+      to: itemIdB,
+      kind: "ALIAS",
+      author,
+      source_kind: "derived_deterministic",
+      authority: 1,
+      active: true,
+      meta,
+    },
+  });
+  current = r1.state;
+  allEvents.push(...r1.events);
+
+  const r2 = applyCommand(current, {
+    type: "edge.create",
+    edge: {
+      edge_id: uuidv7(),
+      from: itemIdB,
+      to: itemIdA,
+      kind: "ALIAS",
+      author,
+      source_kind: "derived_deterministic",
+      authority: 1,
+      active: true,
+      meta,
+    },
+  });
+  current = r2.state;
+  allEvents.push(...r2.events);
+
+  return { state: current, events: allEvents };
+}
+
+/**
+ * Get all items that are aliased to a given item (directly).
+ */
+export function getAliases(state: GraphState, itemId: string): MemoryItem[] {
+  const aliasEdges = getEdges(state, {
+    from: itemId,
+    kind: "ALIAS",
+    active_only: true,
+  });
+  const results: MemoryItem[] = [];
+  for (const edge of aliasEdges) {
+    const item = state.items.get(edge.to);
+    if (item) results.push(item);
+  }
+  return results;
+}
+
+/**
+ * Get the full alias group for an item (transitive closure).
+ */
+export function getAliasGroup(state: GraphState, itemId: string): MemoryItem[] {
+  const visited = new Set<string>();
+  const result: MemoryItem[] = [];
+  const queue = [itemId];
+
+  while (queue.length > 0) {
+    const id = queue.pop()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const item = state.items.get(id);
+    if (item) result.push(item);
+    const aliases = getEdges(state, {
+      from: id,
+      kind: "ALIAS",
+      active_only: true,
+    });
+    for (const edge of aliases) {
+      queue.push(edge.to);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Budget-aware probabilistic retrieval
+// ---------------------------------------------------------------------------
+
+export interface BudgetOptions {
+  budget: number; // total budget (e.g. token count, cost units)
+  costFn: (item: MemoryItem) => number; // cost per item
+  weights: ScoreWeights; // scoring weights
+  filter?: import("./types.js").MemoryFilter;
+}
+
+/**
+ * Retrieve the highest-scoring items that fit within a budget.
+ * Items are ranked by weighted score, then greedily packed.
+ */
+export function getItemsByBudget(
+  state: GraphState,
+  options: BudgetOptions,
+): ScoredItem[] {
+  const scored = getScoredItems(state, options.weights, {
+    pre: options.filter,
+  });
+
+  const results: ScoredItem[] = [];
+  let remaining = options.budget;
+
+  for (const entry of scored) {
+    const cost = options.costFn(entry.item);
+    if (cost <= remaining) {
+      results.push(entry);
+      remaining -= cost;
+    }
+    if (remaining <= 0) break;
+  }
+
+  return results;
+}

package/src/intent.ts

@@ -0,0 +1,311 @@
+import { uuidv7 } from "uuidv7";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type IntentStatus = "active" | "paused" | "completed" | "cancelled";
+
+export interface Intent {
+  id: string;
+  label: string;
+  description?: string;
+
+  priority: number; // 0..1
+  owner: string; // "user:laz", "agent:reasoner", "system:watchdog"
+  status: IntentStatus;
+
+  context?: Record<string, unknown>;
+  root_memory_ids?: string[];
+
+  meta?: Record<string, unknown>;
+}
+
+export interface IntentState {
+  intents: Map<string, Intent>;
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+export function createIntentState(): IntentState {
+  return { intents: new Map() };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createIntent(
+  input: Omit<Intent, "id" | "status"> & { id?: string; status?: IntentStatus },
+): Intent {
+  return {
+    ...input,
+    id: input.id ?? uuidv7(),
+    status: input.status ?? "active",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+export type IntentCommand =
+  | { type: "intent.create"; intent: Intent }
+  | {
+      type: "intent.update";
+      intent_id: string;
+      partial: Partial<Intent>;
+      author: string;
+      reason?: string;
+    }
+  | {
+      type: "intent.complete";
+      intent_id: string;
+      author: string;
+      reason?: string;
+    }
+  | {
+      type: "intent.cancel";
+      intent_id: string;
+      author: string;
+      reason?: string;
+    }
+  | { type: "intent.pause"; intent_id: string; author: string; reason?: string }
+  | {
+      type: "intent.resume";
+      intent_id: string;
+      author: string;
+      reason?: string;
+    };
+
+// ---------------------------------------------------------------------------
+// Lifecycle events
+// ---------------------------------------------------------------------------
+
+export interface IntentLifecycleEvent {
+  namespace: "intent";
+  type:
+    | "intent.created"
+    | "intent.updated"
+    | "intent.completed"
+    | "intent.cancelled"
+    | "intent.paused"
+    | "intent.resumed";
+  intent: Intent;
+  cause_type: string;
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class IntentNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Intent not found: ${id}`);
+    this.name = "IntentNotFoundError";
+  }
+}
+
+export class DuplicateIntentError extends Error {
+  constructor(id: string) {
+    super(`Intent already exists: ${id}`);
+    this.name = "DuplicateIntentError";
+  }
+}
+
+export class InvalidIntentTransitionError extends Error {
+  constructor(id: string, from: IntentStatus, to: string) {
+    super(`Invalid intent transition: ${id} from ${from} to ${to}`);
+    this.name = "InvalidIntentTransitionError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function stripUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) result[key] = value;
+  }
+  return result as Partial<T>;
+}
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+function setStatus(
+  state: IntentState,
+  id: string,
+  targetStatus: IntentStatus,
+  validFrom: IntentStatus[],
+  author: string,
+  causeType: string,
+  eventType: IntentLifecycleEvent["type"],
+): { state: IntentState; events: IntentLifecycleEvent[] } {
+  const existing = state.intents.get(id);
+  if (!existing) throw new IntentNotFoundError(id);
+  if (!validFrom.includes(existing.status)) {
+    throw new InvalidIntentTransitionError(id, existing.status, targetStatus);
+  }
+  const updated: Intent = { ...existing, status: targetStatus };
+  const intents = new Map(state.intents);
+  intents.set(id, updated);
+  return {
+    state: { intents },
+    events: [
+      {
+        namespace: "intent",
+        type: eventType,
+        intent: updated,
+        cause_type: causeType,
+      },
+    ],
+  };
+}
+
+export function applyIntentCommand(
+  state: IntentState,
+  cmd: IntentCommand,
+): { state: IntentState; events: IntentLifecycleEvent[] } {
+  switch (cmd.type) {
+    case "intent.create": {
+      if (state.intents.has(cmd.intent.id)) {
+        throw new DuplicateIntentError(cmd.intent.id);
+      }
+      const intents = new Map(state.intents);
+      intents.set(cmd.intent.id, cmd.intent);
+      return {
+        state: { intents },
+        events: [
+          {
+            namespace: "intent",
+            type: "intent.created",
+            intent: cmd.intent,
+            cause_type: cmd.type,
+          },
+        ],
+      };
+    }
+
+    case "intent.update": {
+      const existing = state.intents.get(cmd.intent_id);
+      if (!existing) throw new IntentNotFoundError(cmd.intent_id);
+      const { id: _id, status: _status, ...rest } = cmd.partial;
+      const updated: Intent = { ...existing, ...stripUndefined(rest) };
+      const intents = new Map(state.intents);
+      intents.set(cmd.intent_id, updated);
+      return {
+        state: { intents },
+        events: [
+          {
+            namespace: "intent",
+            type: "intent.updated",
+            intent: updated,
+            cause_type: cmd.type,
+          },
+        ],
+      };
+    }
+
+    case "intent.complete":
+      return setStatus(
+        state,
+        cmd.intent_id,
+        "completed",
+        ["active", "paused"],
+        cmd.author,
+        cmd.type,
+        "intent.completed",
+      );
+
+    case "intent.cancel":
+      return setStatus(
+        state,
+        cmd.intent_id,
+        "cancelled",
+        ["active", "paused"],
+        cmd.author,
+        cmd.type,
+        "intent.cancelled",
+      );
+
+    case "intent.pause":
+      return setStatus(
+        state,
+        cmd.intent_id,
+        "paused",
+        ["active"],
+        cmd.author,
+        cmd.type,
+        "intent.paused",
+      );
+
+    case "intent.resume":
+      return setStatus(
+        state,
+        cmd.intent_id,
+        "active",
+        ["paused"],
+        cmd.author,
+        cmd.type,
+        "intent.resumed",
+      );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Query
+// ---------------------------------------------------------------------------
+
+export interface IntentFilter {
+  owner?: string;
+  status?: IntentStatus;
+  statuses?: IntentStatus[];
+  min_priority?: number;
+  has_memory_id?: string;
+}
+
+export function getIntents(
+  state: IntentState,
+  filter?: IntentFilter,
+): Intent[] {
+  if (!filter) return [...state.intents.values()];
+
+  const results: Intent[] = [];
+  for (const intent of state.intents.values()) {
+    if (filter.owner !== undefined && intent.owner !== filter.owner) continue;
+    if (filter.status !== undefined && intent.status !== filter.status)
+      continue;
+    if (
+      filter.statuses !== undefined &&
+      !filter.statuses.includes(intent.status)
+    )
+      continue;
+    if (
+      filter.min_priority !== undefined &&
+      intent.priority < filter.min_priority
+    )
+      continue;
+    if (filter.has_memory_id !== undefined) {
+      if (
+        !intent.root_memory_ids ||
+        !intent.root_memory_ids.includes(filter.has_memory_id)
+      )
+        continue;
+    }
+    results.push(intent);
+  }
+  return results;
+}
+
+export function getIntentById(
+  state: IntentState,
+  id: string,
+): Intent | undefined {
+  return state.intents.get(id);
+}