opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.10

package/src/context/dependency-closure.js

@@ -0,0 +1,246 @@
+/**
+ * Context Router Dependency Closure — proper traversal without depth limits.
+ *
+ * Separates graph traversal from context admission.
+ * Traversal finds ALL dependencies; admission decides which enter the pack.
+ *
+ * Safety limits (for preventing explosion):
+ *   - maxNodes: maximum nodes to collect
+ *   - maxTraversalCost: maximum operations
+ *   - cycle detection via visited set
+ *
+ * These are SAFETY limits, not semantic limits.
+ */
+
+/**
+ * @typedef {Object} TraversalOptions
+ * @property {number} [maxNodes=100] - Safety limit for node count
+ * @property {number} [maxCost=1000] - Safety limit for traversal operations
+ * @property {string[]} [edgeTypes] - Edge types to follow (default: all)
+ */
+
+/**
+ * @typedef {Object} TraversalResult
+ * @property {string[]} nodes - Collected node IDs
+ * @property {number} cost - Actual traversal cost
+ * @property {boolean} limitReached - Whether safety limit was hit
+ * @property {string} limitType - Which limit was reached (if any)
+ */
+
+/**
+ * Traverse upstream dependencies from a node.
+ * Follows depends_on and produces edges until:
+ *   - no more edges
+ *   - cycle detected
+ *   - safety limit reached
+ *
+ * @param {Object} graph - Context graph
+ * @param {string} startNodeId - Starting node
+ * @param {TraversalOptions} options
+ * @returns {TraversalResult}
+ */
+export function traverseUpstream(graph, startNodeId, options = {}) {
+  const { maxNodes = 100, maxCost = 1000, edgeTypes } = options;
+
+  const visited = new Set();
+  const nodes = [];
+  let cost = 0;
+
+  const queue = [startNodeId];
+
+  while (queue.length > 0) {
+    cost++;
+    if (cost > maxCost) {
+      return {
+        nodes,
+        cost,
+        limitReached: true,
+        limitType: "maxCost",
+      };
+    }
+
+    if (nodes.length >= maxNodes) {
+      return {
+        nodes,
+        cost,
+        limitReached: true,
+        limitType: "maxNodes",
+      };
+    }
+
+    const nodeId = queue.shift();
+
+    if (visited.has(nodeId)) continue;
+    visited.add(nodeId);
+
+    const node = graph.getNode(nodeId);
+    if (!node) continue;
+
+    nodes.push(nodeId);
+
+    // Follow depends_on edges (upstream)
+    const dependsOn = graph.getEdgesFromByType
+      ? graph.getEdgesFromByType(nodeId, "depends_on")
+      : graph.getEdgesFrom(nodeId).filter((e) => e.type === "depends_on");
+
+    for (const edge of dependsOn) {
+      if (!visited.has(edge.to)) {
+        queue.push(edge.to);
+      }
+    }
+
+    // Follow produces edges (reverse direction - who produces this node)
+    const producesEdges = graph.getEdgesToByType
+      ? graph.getEdgesToByType(nodeId, "produces")
+      : graph.getEdgesTo(nodeId).filter((e) => e.type === "produces");
+
+    for (const edge of producesEdges) {
+      if (!visited.has(edge.from)) {
+        queue.push(edge.from);
+      }
+    }
+  }
+
+  return {
+    nodes,
+    cost,
+    limitReached: false,
+    limitType: null,
+  };
+}
+
+/**
+ * Traverse downstream effects from a node.
+ * Follows produces and depends_on edges in forward direction.
+ *
+ * @param {Object} graph - Context graph
+ * @param {string} startNodeId - Starting node
+ * @param {TraversalOptions} options
+ * @returns {TraversalResult}
+ */
+export function traverseDownstream(graph, startNodeId, options = {}) {
+  const { maxNodes = 100, maxCost = 1000 } = options;
+
+  const visited = new Set();
+  const nodes = [];
+  let cost = 0;
+
+  const queue = [startNodeId];
+
+  while (queue.length > 0) {
+    cost++;
+    if (cost > maxCost) {
+      return { nodes, cost, limitReached: true, limitType: "maxCost" };
+    }
+
+    if (nodes.length >= maxNodes) {
+      return { nodes, cost, limitReached: true, limitType: "maxNodes" };
+    }
+
+    const nodeId = queue.shift();
+
+    if (visited.has(nodeId)) continue;
+    visited.add(nodeId);
+
+    const node = graph.getNode(nodeId);
+    if (!node) continue;
+
+    nodes.push(nodeId);
+
+    // Follow produces edges (downstream)
+    const produces = graph.getEdgesFromByType
+      ? graph.getEdgesFromByType(nodeId, "produces")
+      : graph.getEdgesFrom(nodeId).filter((e) => e.type === "produces");
+
+    for (const edge of produces) {
+      if (!visited.has(edge.to)) {
+        queue.push(edge.to);
+      }
+    }
+
+    // Follow depends_on edges (reverse - who depends on this)
+    const dependsOnEdges = graph.getEdgesToByType
+      ? graph.getEdgesToByType(nodeId, "depends_on")
+      : graph.getEdgesTo(nodeId).filter((e) => e.type === "depends_on");
+
+    for (const edge of dependsOnEdges) {
+      if (!visited.has(edge.from)) {
+        queue.push(edge.from);
+      }
+    }
+  }
+
+  return {
+    nodes,
+    cost,
+    limitReached: false,
+    limitType: null,
+  };
+}
+
+/**
+ * Compute full dependency closure for a set of nodes.
+ * Combines upstream and downstream traversal.
+ *
+ * @param {Object} graph - Context graph
+ * @param {string[]} nodeIds - Starting nodes
+ * @param {TraversalOptions} options
+ * @returns {TraversalResult}
+ */
+export function computeDependencyClosure(graph, nodeIds, options = {}) {
+  const visited = new Set();
+  const allNodes = [];
+  let totalCost = 0;
+
+  for (const nodeId of nodeIds) {
+    const upstream = traverseUpstream(graph, nodeId, options);
+    const downstream = traverseDownstream(graph, nodeId, options);
+
+    for (const id of [...upstream.nodes, ...downstream.nodes]) {
+      if (!visited.has(id)) {
+        visited.add(id);
+        allNodes.push(id);
+      }
+    }
+
+    totalCost += upstream.cost + downstream.cost;
+
+    if (upstream.limitReached || downstream.limitReached) {
+      return {
+        nodes: allNodes,
+        cost: totalCost,
+        limitReached: true,
+        limitType: upstream.limitReached ? upstream.limitType : downstream.limitType,
+      };
+    }
+  }
+
+  return {
+    nodes: allNodes,
+    cost: totalCost,
+    limitReached: false,
+    limitType: null,
+  };
+}
+
+/**
+ * Check if traversal would hit safety limits.
+ * Useful for pre-flight checks.
+ *
+ * @param {Object} graph - Context graph
+ * @param {string} nodeId - Node to check
+ * @param {TraversalOptions} options
+ * @returns {{ safe: boolean, reason: string }}
+ */
+export function checkTraversalSafety(graph, nodeId, options = {}) {
+  const result = traverseUpstream(graph, nodeId, { ...options, maxNodes: 10, maxCost: 20 });
+
+  if (result.limitReached) {
+    return {
+      safe: false,
+      reason: `Traversal hits ${result.limitType} limit early (${result.cost} ops, ${result.nodes.length} nodes)`,
+    };
+  }
+
+  return { safe: true, reason: "Traversal within safety bounds" };
+}

package/src/context/page-fault-tracker.js

@@ -0,0 +1,275 @@
+/**
+ * Page-Fault Tracker (C06 — page-fault-measurement).
+ *
+ * Tracks context page-faults: when omitted context is later requested via
+ * `retrieveContext()` (i.e. the system has to fetch what it had previously
+ * chosen NOT to inject). Provides per-fault metrics: fetch count, tokens
+ * fetched, latency, and reason classification.
+ *
+ * Design:
+ *   - createPageFaultTracker() returns a tracker with:
+ *       recordOmission({id, tokens, reason})  — log that context was dropped
+ *       recordFetch({id, tokens, latencyMs, reason}) — log a subsequent fetch
+ *       recordFault(id, ...)                    — record a fault (alias)
+ *       snapshot()                              — current aggregate stats
+ *       reset()                                 — clear all state
+ *       faults()                                — list of recorded faults
+ *   - measurePageFaults(tracker, fetchFn) — runs an async fetch closure
+ *     against the tracker and returns the snapshot.
+ *
+ * Page fault definition: a fetch of an id that was previously omitted
+ * (recorded via recordOmission). If the id was never omitted, it's a
+ * regular fetch and is NOT counted as a fault.
+ *
+ * Reason taxonomy (extensible):
+ *   - "scope-overflow" — was trimmed because budget overflowed
+ *   - "relevance-threshold" — failed admission scoring threshold
+ *   - "explicit-omission" — manually dropped by selector
+ *   - "ttl-expired"     — context had aged out
+ *   - "unknown"         — no omission reason recorded
+ */
+
+export const FAULT_REASONS = Object.freeze({
+  SCOPE_OVERFLOW: "scope-overflow",
+  RELEVANCE_THRESHOLD: "relevance-threshold",
+  EXPLICIT_OMISSION: "explicit-omission",
+  TTL_EXPIRED: "ttl-expired",
+  UNKNOWN: "unknown",
+});
+
+/**
+ * @typedef {Object} OmissionRecord
+ * @property {string} id
+ * @property {number} tokens
+ * @property {string} reason
+ * @property {number} timestamp
+ */
+
+/**
+ * @typedef {Object} FaultRecord
+ * @property {string} id
+ * @property {number} tokens
+ * @property {number} latencyMs
+ * @property {string} reason
+ * @property {number} timestamp
+ * @property {string} omissionReason
+ */
+
+/**
+ * @typedef {Object} PageFaultSnapshot
+ * @property {number} omissionCount
+ * @property {number} fetchCount
+ * @property {number} faultCount
+ * @property {number} tokensOmitted
+ * @property {number} tokensFetched
+ * @property {number} tokensRefetched   - tokens fetched that were faults
+ * @property {number} totalLatencyMs
+ * @property {number} faultLatencyMs
+ * @property {Object} faultsByReason    - {reason: count}
+ * @property {Object} omissionsByReason  - {reason: count}
+ * @property {number} faultRate         - faultCount / fetchCount (0 if no fetches)
+ */
+
+/**
+ * @typedef {Object} PageFaultTracker
+ * @property {string[]} _ids
+ * @property {(record: OmissionRecord) => void} recordOmission
+ * @property {(record: {id: string, tokens?: number, latencyMs?: number, reason?: string}) => FaultRecord|null} recordFetch
+ * @property {(id: string, opts?: object) => FaultRecord|null} recordFault
+ * @property {() => OmissionRecord[]} omissions
+ * @property {() => FaultRecord[]} faults
+ * @property {() => PageFaultSnapshot} snapshot
+ * @property {() => void} reset
+ */
+
+/**
+ * Create a new page-fault tracker.
+ *
+ * @param {Object} [opts]
+ * @param {number} [opts.clock=() => Date.now()] - injectable clock for tests
+ * @returns {PageFaultTracker}
+ */
+export function createPageFaultTracker(opts = {}) {
+  const clock = typeof opts.clock === "function" ? opts.clock : () => Date.now();
+
+  /** @type {Map<string, OmissionRecord>} */
+  const omissions = new Map();
+  /** @type {FaultRecord[]} */
+  const faults = [];
+
+  /**
+   * Record that context `id` was omitted (not injected into the prompt).
+   * Calling recordOmission twice for the same id updates the prior record.
+   *
+   * @param {OmissionRecord} record
+   */
+  function recordOmission(record) {
+    if (!record || typeof record.id !== "string") {
+      throw new TypeError("recordOmission: record.id must be a string");
+    }
+    const entry = {
+      id: record.id,
+      tokens: typeof record.tokens === "number" ? record.tokens : 0,
+      reason: typeof record.reason === "string" ? record.reason : FAULT_REASONS.UNKNOWN,
+      timestamp: typeof record.timestamp === "number" ? record.timestamp : clock(),
+    };
+    omissions.set(entry.id, entry);
+  }
+
+  /**
+   * Record a fetch of context `id`. If `id` was previously omitted, this
+   * is a page fault and a FaultRecord is returned. Otherwise returns null.
+   *
+   * @param {{id: string, tokens?: number, latencyMs?: number, reason?: string, timestamp?: number}} record
+   * @returns {FaultRecord|null}
+   */
+  function recordFetch(record) {
+    if (!record || typeof record.id !== "string") {
+      throw new TypeError("recordFetch: record.id must be a string");
+    }
+    const id = record.id;
+    const omission = omissions.get(id);
+    if (!omission) return null;
+
+    const fault = {
+      id,
+      tokens: typeof record.tokens === "number" ? record.tokens : omission.tokens,
+      latencyMs: typeof record.latencyMs === "number" ? record.latencyMs : 0,
+      reason: typeof record.reason === "string" ? record.reason : FAULT_REASONS.UNKNOWN,
+      timestamp: typeof record.timestamp === "number" ? record.timestamp : clock(),
+      omissionReason: omission.reason,
+    };
+    faults.push(fault);
+    return fault;
+  }
+
+  /**
+   * Convenience alias for recordFetch.
+   *
+   * @param {string} id
+   * @param {{tokens?: number, latencyMs?: number, reason?: string}} [opts]
+   * @returns {FaultRecord|null}
+   */
+  function recordFault(id, opts = {}) {
+    return recordFetch({ id, ...(opts || {}) });
+  }
+
+  function snapshot() {
+    let tokensOmitted = 0;
+    let tokensFetched = 0;
+    let tokensRefetched = 0;
+    let totalLatencyMs = 0;
+    let faultLatencyMs = 0;
+    /** @type {Object<string, number>} */
+    const faultsByReason = {};
+    /** @type {Object<string, number>} */
+    const omissionsByReason = {};
+
+    for (const o of omissions.values()) {
+      tokensOmitted += o.tokens;
+      omissionsByReason[o.reason] = (omissionsByReason[o.reason] || 0) + 1;
+    }
+    for (const f of faults) {
+      tokensRefetched += f.tokens;
+      faultLatencyMs += f.latencyMs;
+      totalLatencyMs += f.latencyMs;
+      faultsByReason[f.reason] = (faultsByReason[f.reason] || 0) + 1;
+    }
+    const fetchCount = faults.length; // only faults count as fetches in this metric
+    const faultCount = faults.length;
+    const faultRate = fetchCount === 0 ? 0 : faultCount / fetchCount;
+
+    return {
+      omissionCount: omissions.size,
+      fetchCount,
+      faultCount,
+      tokensOmitted,
+      tokensFetched, // alias for tokensRefetched under fault-only mode
+      tokensRefetched,
+      totalLatencyMs,
+      faultLatencyMs,
+      faultsByReason,
+      omissionsByReason,
+      faultRate,
+    };
+  }
+
+  function reset() {
+    omissions.clear();
+    faults.length = 0;
+  }
+
+  return {
+    recordOmission,
+    recordFetch,
+    recordFault,
+    omissions: () => Array.from(omissions.values()),
+    faults: () => faults.slice(),
+    snapshot,
+    reset,
+  };
+}
+
+/**
+ * Run `fetchFn` against the tracker and return the resulting snapshot.
+ * Useful for instrumenting an existing retrieveContext() call.
+ *
+ * The fetchFn receives a wrapped retrieveContext that automatically calls
+ * recordFetch on every retrieval, attributing tokens/latency to faults when
+ * applicable.
+ *
+ * @param {PageFaultTracker} tracker
+ * @param {(retrieve: (id: string, opts?: object) => any) => Promise<any>|any} fetchFn
+ * @returns {Promise<PageFaultSnapshot>|PageFaultSnapshot}
+ */
+export function measurePageFaults(tracker, fetchFn) {
+  if (!tracker || typeof tracker.recordFetch !== "function") {
+    throw new TypeError("measurePageFaults: tracker required");
+  }
+  if (typeof fetchFn !== "function") {
+    throw new TypeError("measurePageFaults: fetchFn must be a function");
+  }
+  const wrapped = (id, opts = {}) => {
+    const start = (opts && typeof opts._start === "number") ? opts._start : Date.now();
+    const result = (opts && typeof opts._result === "object") ? opts._result : null;
+    const tokens = result && typeof result.tokens === "number"
+      ? result.tokens
+      : (opts && typeof opts.tokens === "number" ? opts.tokens : 0);
+    const latencyMs = result && typeof result.latencyMs === "number"
+      ? result.latencyMs
+      : Math.max(0, Date.now() - start);
+    return tracker.recordFetch({
+      id,
+      tokens,
+      latencyMs,
+      reason: (opts && opts.reason) || "unknown",
+    });
+  };
+  // NOTE: deliberately not async — returns snapshot directly.
+  // If fetchFn returns a Promise, the caller should await.
+  const out = fetchFn(wrapped);
+  if (out && typeof out.then === "function") {
+    return out.catch(() => {}).then(() => tracker.snapshot());
+  }
+  return tracker.snapshot();
+}
+
+/**
+ * Compute per-fault aggregates grouped by omission reason.
+ *
+ * @param {FaultRecord[]} records
+ * @returns {Object<string, {count: number, tokens: number, latencyMs: number}>}
+ */
+export function aggregateByReason(records) {
+  /** @type {Object<string, {count: number, tokens: number, latencyMs: number}>} */
+  const out = {};
+  if (!Array.isArray(records)) return out;
+  for (const r of records) {
+    const key = (r && r.omissionReason) || FAULT_REASONS.UNKNOWN;
+    if (!out[key]) out[key] = { count: 0, tokens: 0, latencyMs: 0 };
+    out[key].count += 1;
+    out[key].tokens += typeof r.tokens === "number" ? r.tokens : 0;
+    out[key].latencyMs += typeof r.latencyMs === "number" ? r.latencyMs : 0;
+  }
+  return out;
+}

package/src/context/prompt-engine.js

@@ -0,0 +1,74 @@
+import { countTokens } from './tokenizer.js';
+
+export function buildPrompt({ system, context, user }, options = {}) {
+  const maxTokens = options.maxTokens ?? Infinity;
+  const reservedForUser = options.reservedForUser ?? 0;
+
+  const parts = [];
+  if (system) parts.push({ role: 'system', content: system });
+  if (context) parts.push({ role: 'context', content: context });
+  if (user) parts.push({ role: 'user', content: user });
+
+  const contentFor = (p) => (typeof p.content === 'string' ? p.content : '');
+
+  // Calculate per-part token counts.
+  const withTokens = parts.map((p) => ({ ...p, tokens: countTokens(contentFor(p)) }));
+  const totalTokens = withTokens.reduce((s, p) => s + p.tokens, 0);
+
+  if (totalTokens <= maxTokens) {
+    return {
+      parts: withTokens.map((p) => ({ role: p.role, content: p.content })),
+      totalTokens,
+      truncated: false,
+    };
+  }
+
+  // Truncate lowest-priority parts first; system has highest priority.
+  // Process in reverse priority order so system is preserved.
+  const priorities = ['user', 'context'];
+  const resultParts = withTokens.map((p) => ({
+    role: p.role,
+    content: p.content,
+    tokens: p.tokens,
+  }));
+
+  let currentTokens = totalTokens;
+  for (const role of priorities) {
+    if (currentTokens <= maxTokens) break;
+    const idx = resultParts.findIndex((p) => p.role === role);
+    if (idx === -1) continue;
+    const part = resultParts[idx];
+    const remainingBudget = maxTokens - (currentTokens - part.tokens);
+    const minForUser = role === 'user' ? reservedForUser : 0;
+    const allowed = Math.max(0, remainingBudget - minForUser);
+    if (allowed >= part.tokens) continue;
+    if (allowed === 0) {
+      part.content = '';
+      part.tokens = 0;
+    } else {
+      // Truncate content by approximate char ratio (chars ~= 4 chars per token).
+      const charBudget = allowed * 4;
+      const truncated = contentFor(part).slice(0, charBudget);
+      part.content = truncated + (contentFor(part).length > charBudget ? '...' : '');
+      part.tokens = countTokens(part.content);
+    }
+    currentTokens = resultParts.reduce((s, p) => s + p.tokens, 0);
+  }
+
+  // If still over budget after user/context truncation, drop user content entirely.
+  // System is preserved whenever possible (last resort: empty if it alone exceeds budget).
+  if (currentTokens > maxTokens) {
+    const userIdx = resultParts.findIndex((p) => p.role === 'user');
+    if (userIdx !== -1) {
+      resultParts[userIdx].content = '';
+      resultParts[userIdx].tokens = 0;
+      currentTokens = resultParts.reduce((s, p) => s + p.tokens, 0);
+    }
+  }
+
+  return {
+    parts: resultParts.map((p) => ({ role: p.role, content: p.content })),
+    totalTokens: currentTokens,
+    truncated: true,
+  };
+}