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

package/src/context/context-source-registry.js

@@ -0,0 +1,95 @@
+/**
+ * Context Source Registry — Registration and lookup for context sources.
+ *
+ * Manages a collection of context sources (id → source mapping).
+ * Sources are plain objects with at least an `id` and `type` field.
+ *
+ * Keeps registration idempotent: re-registering the same id updates the source.
+ */
+
+/**
+ * @typedef {Object} ContextSource
+ * @property {string} id - Unique identifier for the source
+ * @property {string} type - Source type/category
+ */
+
+class ContextSourceRegistry {
+  constructor() {
+    /** @type {Map<string, ContextSource>} */
+    this._sources = new Map();
+  }
+
+  /**
+   * Register or update a context source.
+   * @param {ContextSource} source
+   * @returns {ContextSource} The registered source.
+   */
+  register(source) {
+    if (!source || typeof source.id !== "string" || !source.id) {
+      throw new TypeError("Source must have a non-empty string `id`");
+    }
+    this._sources.set(source.id, source);
+    return source;
+  }
+
+  /**
+   * Remove a source by id.
+   * @param {string} id
+   * @returns {boolean} true if removed, false if not found.
+   */
+  unregister(id) {
+    return this._sources.delete(id);
+  }
+
+  /**
+   * Retrieve a source by id.
+   * @param {string} id
+   * @returns {ContextSource | undefined}
+   */
+  get(id) {
+    return this._sources.get(id);
+  }
+
+  /**
+   * Check if a source is registered.
+   * @param {string} id
+   * @returns {boolean}
+   */
+  has(id) {
+    return this._sources.has(id);
+  }
+
+  /**
+   * List all registered sources.
+   * @returns {ContextSource[]}
+   */
+  list() {
+    return [...this._sources.values()];
+  }
+
+  /**
+   * List sources filtered by type.
+   * @param {string} type
+   * @returns {ContextSource[]}
+   */
+  listByType(type) {
+    return this.list().filter((s) => s.type === type);
+  }
+
+  /**
+   * Total number of registered sources.
+   * @returns {number}
+   */
+  get size() {
+    return this._sources.size;
+  }
+
+  /**
+   * Clear all sources.
+   */
+  clear() {
+    this._sources.clear();
+  }
+}
+
+export { ContextSourceRegistry };

package/src/context/context-sufficiency-gate.js

@@ -0,0 +1,120 @@
+import { TERMINAL_STATES } from "./context-lifecycle.js";
+import { CONTEXT_PURPOSE } from "./context-query-contract.js";
+
+export const SUFFICIENCY_LEVEL = Object.freeze({
+  INSUFFICIENT: "INSUFFICIENT",
+  PARTIAL: "PARTIAL",
+  SUFFICIENT: "SUFFICIENT",
+  COMPLETE: "COMPLETE",
+});
+
+export const SUFFICIENCY_DECISIONS = Object.freeze({
+  PROCEED: "PROCEED",
+  REQUEST_MORE: "REQUEST_MORE",
+  BLOCK: "BLOCK",
+});
+
+export const MIN_LAYER_COUNTS = Object.freeze({
+  [CONTEXT_PURPOSE.PLANNING]: 3,
+  [CONTEXT_PURPOSE.IMPLEMENTATION]: 2,
+  [CONTEXT_PURPOSE.INVESTIGATION]: 2,
+  [CONTEXT_PURPOSE.DEBUGGING]: 1,
+  [CONTEXT_PURPOSE.VALIDATION]: 1,
+  [CONTEXT_PURPOSE.REVIEW]: 2,
+  [CONTEXT_PURPOSE.RESUME]: 1,
+});
+
+const INCLUDE_HISTORY_PURPOSES = new Set([
+  CONTEXT_PURPOSE.DEBUGGING,
+  CONTEXT_PURPOSE.RESUME,
+  "REPLAN",
+  "AUDIT",
+]);
+
+const _isTerminal = (lifecycle) => TERMINAL_STATES.includes(lifecycle);
+
+export function checkSufficiency(items, purpose = CONTEXT_PURPOSE.PLANNING) {
+  if (!items || items.length === 0) {
+    return {
+      level: SUFFICIENCY_LEVEL.INSUFFICIENT,
+      missing: [{ reason: "NO_ACTIVE_CONTEXT", type: "context" }],
+      unresolvedCriticalUnknowns: [],
+      mandatoryIncluded: false,
+      activeItemCount: 0,
+      sufficient: false,
+    };
+  }
+
+  const includeHistory = INCLUDE_HISTORY_PURPOSES.has(purpose);
+  const activeItems = items.filter((item) => includeHistory || !_isTerminal(item.lifecycle));
+  const criticalUnknowns = items.flatMap((item) => item.unresolvedCriticalUnknowns || []);
+  const hasMandatory = items.some((item) => item.mandatoryIncluded === true);
+  const minCount = MIN_LAYER_COUNTS[purpose] || MIN_LAYER_COUNTS[CONTEXT_PURPOSE.PLANNING];
+
+  let level = SUFFICIENCY_LEVEL.INSUFFICIENT;
+
+  if (activeItems.length === 0) {
+    level = SUFFICIENCY_LEVEL.INSUFFICIENT;
+  } else if (criticalUnknowns.length > 0) {
+    level = SUFFICIENCY_LEVEL.PARTIAL;
+  } else if (activeItems.length >= minCount && hasMandatory) {
+    level = SUFFICIENCY_LEVEL.COMPLETE;
+  } else if (activeItems.length >= 1) {
+    level = SUFFICIENCY_LEVEL.SUFFICIENT;
+  }
+
+  return {
+    level,
+    missing: level === SUFFICIENCY_LEVEL.INSUFFICIENT
+      ? [{ reason: "INSUFFICIENT_ITEMS", type: "context", count: activeItems.length, required: minCount }]
+      : [],
+    unresolvedCriticalUnknowns: criticalUnknowns,
+    mandatoryIncluded: hasMandatory,
+    activeItemCount: activeItems.length,
+    sufficient: level !== SUFFICIENCY_LEVEL.INSUFFICIENT,
+  };
+}
+
+export class SufficiencyGate {
+  #purpose;
+  #minLevel;
+  #requireMandatory;
+
+  constructor(options = {}) {
+    this.#purpose = options.purpose || CONTEXT_PURPOSE.PLANNING;
+    this.#minLevel = options.minLevel || SUFFICIENCY_LEVEL.SUFFICIENT;
+    this.#requireMandatory = options.requireMandatory || false;
+  }
+
+  get purpose() { return this.#purpose; }
+  get minLevel() { return this.#minLevel; }
+  get requireMandatory() { return this.#requireMandatory; }
+
+  evaluate(items) {
+    const sufficiency = checkSufficiency(items, this.#purpose);
+    const levelOrder = [SUFFICIENCY_LEVEL.INSUFFICIENT, SUFFICIENCY_LEVEL.PARTIAL, SUFFICIENCY_LEVEL.SUFFICIENT, SUFFICIENCY_LEVEL.COMPLETE];
+    const actualRank = levelOrder.indexOf(sufficiency.level);
+    const minRank = levelOrder.indexOf(this.#minLevel);
+
+    let decision;
+    if (actualRank < levelOrder.indexOf(SUFFICIENCY_LEVEL.PARTIAL)) {
+      decision = SUFFICIENCY_DECISIONS.REQUEST_MORE;
+    } else if (actualRank < minRank) {
+      decision = this.#requireMandatory && !sufficiency.mandatoryIncluded
+        ? SUFFICIENCY_DECISIONS.BLOCK
+        : SUFFICIENCY_DECISIONS.REQUEST_MORE;
+    } else {
+      decision = SUFFICIENCY_DECISIONS.PROCEED;
+    }
+
+    return {
+      decision,
+      sufficiency,
+      metadata: {
+        gatePurpose: this.#purpose,
+        minLevel: this.#minLevel,
+        evaluatedAt: Date.now(),
+      },
+    };
+  }
+}

package/src/context/context-sufficiency-oracle.js

@@ -0,0 +1,167 @@
+/**
+ * Context Sufficiency Oracle (C04 — context-sufficiency-oracle)
+ *
+ * Independent ground-truth verifier for context selection. Given a task and
+ * a selected set of node IDs, computes the *required closure graph* — the
+ * minimal set of nodes transitively required via REQUIRES / DEPENDS_ON edges
+ * starting from the task — and verifies `selected ⊇ requiredClosure`.
+ *
+ * Independence: this module does NOT consult router heuristics, scoring
+ * weights, or admission classes. It only walks the context-graph via edges
+ * labeled REQUIRES or DEPENDS_ON, starting at the task node. Its verdict
+ * is an objective ground-truth that the selection-router must satisfy.
+ */
+
+import { EDGE_TYPES } from "./context-graph.js";
+
+/**
+ * @typedef {Object} OracleNode
+ * @property {string} id
+ * @property {string} [type]
+ * @property {string} [content]
+ */
+
+/**
+ * @typedef {Object} OracleEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {string} type
+ */
+
+/**
+ * @typedef {Object} OracleGraph
+ * @property {(id: string) => OracleNode|undefined} getNode
+ * @property {() => OracleEdge[]} getEdges
+ * @property {(id: string) => OracleEdge[]} getEdgesFrom
+ * @property {(id: string) => OracleEdge[]} getEdgesTo
+ */
+
+/**
+ * @typedef {Object} OracleResult
+ * @property {string} taskId
+ * @property {string[]} requiredClosure - sorted node IDs that must be present
+ * @property {string[]} selected       - input selected IDs (deduped, sorted)
+ * @property {string[]} missing        - required ⊖ selected
+ * @property {string[]} unused         - selected ⊖ required
+ * @property {boolean} sufficient      - missing.length === 0
+ * @property {Object}  stats
+ */
+
+/**
+ * Default edge types that participate in the required closure walk.
+ * Walking includes both outgoing (node → its requirements) and incoming
+ * (other nodes that declare they require this node) so the closure is
+ * symmetric under graph direction.
+ */
+const CLOSURE_EDGE_TYPES = new Set([
+  EDGE_TYPES.REQUIRES,
+  EDGE_TYPES.DEPENDS_ON,
+  "requires",
+  "depends_on",
+  "DEPENDENCY",
+]);
+
+/**
+ * Compute the required closure graph for a task — the minimal set of node
+ * IDs that any sufficient context MUST include.
+ *
+ * @param {string} taskId
+ * @param {OracleGraph} graph
+ * @returns {string[]} sorted node IDs
+ */
+export function computeRequiredClosure(taskId, graph) {
+  if (!taskId || typeof taskId !== "string") {
+    throw new TypeError("computeRequiredClosure: taskId must be a non-empty string");
+  }
+  if (!graph || typeof graph.getNode !== "function") {
+    throw new TypeError("computeRequiredClosure: graph with getNode() is required");
+  }
+  if (!graph.getNode(taskId)) {
+    throw new Error(`computeRequiredClosure: task '${taskId}' not in graph`);
+  }
+
+  const closure = new Set([taskId]);
+  const queue = [taskId];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const related = [
+      ...(graph.getEdgesFrom(current) || []),
+      ...(graph.getEdgesTo(current) || []),
+    ];
+
+    for (const edge of related) {
+      if (!CLOSURE_EDGE_TYPES.has(edge.type)) continue;
+      const nextId = edge.from === current ? edge.to : edge.from;
+      if (!nextId || closure.has(nextId)) continue;
+      closure.add(nextId);
+      queue.push(nextId);
+    }
+  }
+
+  return [...closure].sort();
+}
+
+/**
+ * Verify a selection against the oracle's required closure.
+ *
+ * @param {string} taskId
+ * @param {OracleGraph} graph
+ * @param {string[]|Set<string>} selected
+ * @returns {OracleResult}
+ */
+export function verifySufficiency(taskId, graph, selected) {
+  const required = computeRequiredClosure(taskId, graph);
+  const selectedSet = new Set(selected || []);
+  const requiredSet = new Set(required);
+
+  const missing = required.filter((id) => !selectedSet.has(id));
+  const unused = [...selectedSet].filter((id) => !requiredSet.has(id)).sort();
+
+  const nodeCount = (graph.getEdges ? graph.getEdges().length : 0);
+
+  return {
+    taskId,
+    requiredClosure: required,
+    selected: [...selectedSet].sort(),
+    missing,
+    unused,
+    sufficient: missing.length === 0,
+    stats: {
+      requiredCount: required.length,
+      selectedCount: selectedSet.size,
+      missingCount: missing.length,
+      unusedCount: unused.length,
+      graphEdgeCount: nodeCount,
+    },
+  };
+}
+
+/**
+ * Convenience: derive sufficiency boolean without constructing the full
+ * result object. Useful in test assertions.
+ */
+export function isSufficient(taskId, graph, selected) {
+  return verifySufficiency(taskId, graph, selected).sufficient;
+}
+
+/**
+ * Build a minimal oracle graph from a plain node/edge list. Helpful for tests
+ * and for callers that don't have a full graph instance.
+ *
+ * @param {{nodes: OracleNode[], edges: OracleEdge[]}} spec
+ * @returns {OracleGraph}
+ */
+export function buildOracleGraph(spec) {
+  const nodes = new Map((spec.nodes || []).map((n) => [n.id, n]));
+  const edges = spec.edges || [];
+
+  return {
+    getNode: (id) => nodes.get(id),
+    getEdges: () => edges.slice(),
+    getEdgesFrom: (id) => edges.filter((e) => e.from === id),
+    getEdgesTo: (id) => edges.filter((e) => e.to === id),
+  };
+}
+
+export const ORACLE_CLOSURE_EDGE_TYPES = [...CLOSURE_EDGE_TYPES];

package/src/context/context-telemetry.js

@@ -0,0 +1,176 @@
+/**
+ * Context Selection Telemetry (C03 — context-observability-v1)
+ *
+ * Emits one JSONL record per decision made by the context-router / builder.
+ * Each record is intended to be appended to `selection-log.jsonl` (or written
+ * via the writer injected through `setWriter`).
+ *
+ * Required fields per decision:
+ *   - timestamp (ISO)
+ *   - decisionId
+ *   - taskId
+ *   - per-node admission tier (MANDATORY | CONDITIONAL | OPTIONAL)
+ *   - per-node token estimate
+ *   - omitted vs selected counts
+ *   - budget breakdown (mandatory / conditional / optional)
+ *   - sufficiency status (level + decision)
+ */
+
+import { ADMISSION } from "./context-router.js";
+import { SUFFICIENCY_LEVEL, SUFFICIENCY_DECISIONS } from "./context-sufficiency-gate.js";
+
+const ISO_NOW = () => new Date().toISOString();
+
+let _writer = null;
+let _idCounter = 0;
+
+/**
+ * Inject a writer used to persist telemetry records.
+ * Should accept a complete serialized JSONL string (ending with '\n').
+ *
+ * @param {(line: string) => void} writer
+ */
+export function setWriter(writer) {
+  _writer = writer;
+}
+
+/**
+ * Reset internal state. Used in tests.
+ */
+export function _resetTelemetry() {
+  _writer = null;
+  _idCounter = 0;
+}
+
+/**
+ * @typedef {Object} TraceDecisionInput
+ * @property {string} taskId
+ * @property {string} [decision]
+ * @property {Array<{id:string, admission:string, tokenEstimate:number}>} [selected]
+ * @property {Array<{id:string, admission:string, reason:string}>} [omitted]
+ * @property {Array<{id:string, admission:string, tokenEstimate:number}>} [admitted]   // all nodes considered for admission before budgeting
+ * @property {{tokenBudget:number, tokensUsed:number, tokensAvailable:number}} [budget]
+ * @property {{level:string, decision?:string, activeItemCount?:number, missing?:Array}} [sufficiency]
+ * @property {Object} [extra]
+ */
+
+/**
+ * Record a selection decision. Emits a JSONL line and returns the structured record.
+ *
+ * @param {TraceDecisionInput} input
+ * @returns {Object} the telemetry record (also persisted to writer)
+ */
+export function recordDecision(input) {
+  const selected = input.selected || [];
+  const omitted = input.omitted || [];
+
+  const budgetBreakdown = computeBudgetBreakdown(selected, omitted, input.admitted || []);
+
+  const sufficiencyStatus = {
+    level: input.sufficiency?.level || SUFFICIENCY_LEVEL.INSUFFICIENT,
+    decision: input.sufficiency?.decision || SUFFICIENCY_DECISIONS.REQUEST_MORE,
+    sufficient: input.sufficiency?.level === SUFFICIENCY_LEVEL.SUFFICIENT
+      || input.sufficiency?.level === SUFFICIENCY_LEVEL.COMPLETE,
+  };
+
+  const record = {
+    schema: "context-selection-telemetry/v1",
+    timestamp: ISO_NOW(),
+    decisionId: `d_${(++_idCounter).toString(36)}`,
+    taskId: input.taskId,
+    decision: input.decision || "SELECT",
+    counts: {
+      considered: (input.admitted || []).length,
+      selected: selected.length,
+      omitted: omitted.length,
+    },
+    perNodeAdmission: selected.map((n) => ({
+      id: n.id,
+      tier: n.admission || ADMISSION.OPTIONAL,
+      tokenEstimate: n.tokenEstimate || 0,
+    })),
+    omittedNodes: omitted.map((n) => ({
+      id: n.id,
+      tier: n.admission || ADMISSION.OPTIONAL,
+      reason: n.reason || "BUDGET",
+    })),
+    budget: {
+      tokenBudget: input.budget?.tokenBudget || 0,
+      tokensUsed: input.budget?.tokensUsed || 0,
+      tokensAvailable: input.budget?.tokensAvailable || 0,
+      breakdown: budgetBreakdown,
+    },
+    sufficiency: sufficiencyStatus,
+    ...(input.extra ? { extra: input.extra } : {}),
+  };
+
+  if (typeof _writer === "function") {
+    try {
+      _writer(JSON.stringify(record) + "\n");
+    } catch {
+      // writer errors must never break selection — telemetry is best-effort.
+    }
+  }
+
+  return record;
+}
+
+/**
+ * Compute per-tier token breakdown for a selection decision.
+ *
+ * Mandatory tokens are reported from `selected` (mandatory nodes are never
+ * dropped). Conditional and optional counts aggregate from both selected and
+ * omitted lists so we can observe what was cut.
+ */
+export function computeBudgetBreakdown(selected, omitted, admitted) {
+  const init = () => ({
+    MANDATORY: { tokens: 0, count: 0 },
+    CONDITIONAL: { tokens: 0, count: 0 },
+    OPTIONAL: { tokens: 0, count: 0 },
+  });
+
+  const breakdown = init();
+
+  for (const n of selected || []) {
+    const tier = n.admission || ADMISSION.OPTIONAL;
+    breakdown[tier].tokens += n.tokenEstimate || 0;
+    breakdown[tier].count += 1;
+  }
+
+  for (const n of omitted || []) {
+    const tier = n.admission || ADMISSION.OPTIONAL;
+    breakdown[tier].count += 1;
+  }
+
+  // Record considered-but-either-included-or-cut counts to give observability
+  // over nodes that never made it through the admission stage.
+  const considered = { total: admitted.length };
+  breakdown.considered = considered;
+
+  return breakdown;
+}
+
+/**
+ * Convenience: persist a record + return it. Mirrors `recordDecision` but
+ * requires a writer to be set; throws otherwise. Used by hook-points where
+ * silent telemetry is undesirable (e.g. test fixtures asserting wiring).
+ */
+export function requireRecordDecision(input) {
+  if (typeof _writer !== "function") {
+    throw new Error("No telemetry writer configured. Call setWriter() first.");
+  }
+  return recordDecision(input);
+}
+
+export const SCHEMA = "context-selection-telemetry/v1";
+
+/**
+ * Read & parse a JSONL file. Exposed for tests / debugging. Always returns an
+ * array. Malformed lines are skipped (telemetry must never crash consumers).
+ */
+export function parseLog(text) {
+  if (!text) return [];
+  return text.split("\n").filter(Boolean).map((line) => {
+    try { return JSON.parse(line); } catch { return null; }
+  }).filter(Boolean);
+}