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

package/src/context/context-pack-authority.js

@@ -0,0 +1,157 @@
+/**
+ * Context Pack Source of Truth — clarifies authority between components.
+ *
+ * Defines clear responsibility boundaries:
+ *
+ *   Context Graph    = relationships (what connects to what)
+ *   Context Router   = WHAT context is needed (graph-based resolution)
+ *   Context Assembly = HOW to pack it (N0-N3 levels, budget, admission)
+ *   Context Selection = capsule retrieval (legacy, fallback only)
+ *
+ * Authority:
+ *   Router decides WHAT
+ *   Assembly decides HOW
+ *   Selection retrieves (no decisions)
+ */
+
+/**
+ * @typedef {"graph" | "router" | "assembly" | "selection"} Component
+ */
+
+/**
+ * @typedef {Object} AuthorityDecision
+ * @property {Component} component
+ * @property {string} decision
+ * @property {string} reason
+ * @property {number} timestamp
+ */
+
+/**
+ * Component responsibilities (canonical).
+ */
+export const RESPONSIBILITIES = {
+  graph: {
+    authority: "relationships",
+    description: "Stores and queries relationships between context nodes",
+    decisions: ["edge types", "node storage", "graph traversal primitives"],
+  },
+  router: {
+    authority: "what",
+    description: "Determines minimum sufficient context for a task",
+    decisions: [
+      "which nodes are required",
+      "dependency resolution",
+      "contradiction detection",
+      "sufficiency assessment",
+    ],
+  },
+  assembly: {
+    authority: "how",
+    description: "Packs context into N0-N3 levels within budget",
+    decisions: [
+      "level allocation (N0-N3)",
+      "budget partitioning",
+      "admission classes",
+      "final pack contents",
+    ],
+  },
+  selection: {
+    authority: "retrieval",
+    description: "Retrieves capsules from storage (legacy, no decisions)",
+    decisions: ["capsule lookup", "lifecycle filtering"],
+  },
+};
+
+/**
+ * Validate that a decision is within component's authority.
+ *
+ * @param {Component} component
+ * @param {string} decision
+ * @returns {{ valid: boolean, reason: string }}
+ */
+export function validateAuthority(component, decision) {
+  const resp = RESPONSIBILITIES[component];
+  if (!resp) {
+    return { valid: false, reason: `Unknown component: ${component}` };
+  }
+
+  const isAuthorized = resp.decisions.some(
+    (d) => decision.toLowerCase().includes(d.toLowerCase())
+  );
+
+  if (isAuthorized) {
+    return { valid: true, reason: `${component} has authority over ${decision}` };
+  }
+
+  return {
+    valid: false,
+    reason: `${component} does NOT have authority over ${decision}. Authorized: ${resp.decisions.join(", ")}`,
+  };
+}
+
+/**
+ * Create an authority decision record.
+ *
+ * @param {Component} component
+ * @param {string} decision
+ * @param {string} reason
+ * @returns {AuthorityDecision}
+ */
+export function recordDecision(component, decision, reason) {
+  return {
+    component,
+    decision,
+    reason,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Resolve authority conflict between two components.
+ *
+ * @param {Component} a
+ * @param {Component} b
+ * @param {string} decisionType
+ * @returns {{ winner: Component, reason: string }}
+ */
+export function resolveAuthorityConflict(a, b, decisionType) {
+  // Authority hierarchy: assembly > router > selection > graph
+  const hierarchy = ["assembly", "router", "selection", "graph"];
+
+  const idxA = hierarchy.indexOf(a);
+  const idxB = hierarchy.indexOf(b);
+
+  if (idxA === -1) return { winner: b, reason: `${a} not in hierarchy` };
+  if (idxB === -1) return { winner: a, reason: `${b} not in hierarchy` };
+
+  if (idxA < idxB) {
+    return { winner: a, reason: `${a} has higher authority than ${b} for ${decisionType}` };
+  }
+  return { winner: b, reason: `${b} has higher authority than ${a} for ${decisionType}` };
+}
+
+/**
+ * Generate authority report for a context pack assembly.
+ *
+ * @param {Object} context - Assembly context
+ * @returns {string} Formatted report
+ */
+export function generateAuthorityReport(context) {
+  const lines = ["[wam authority]"];
+
+  lines.push("  Graph: stores relationships");
+  lines.push("  Router: determines WHAT context is needed");
+  lines.push("  Assembly: determines HOW to pack it");
+  lines.push("  Selection: retrieves capsules (no decisions)");
+
+  if (context?.routerDecision) {
+    lines.push(`  Router decision: ${context.routerDecision}`);
+  }
+  if (context?.assemblyDecision) {
+    lines.push(`  Assembly decision: ${context.assemblyDecision}`);
+  }
+
+  return lines.join("\n");
+}
+
+export default RESPONSIBILITIES;

package/src/context/context-promotion.js

@@ -0,0 +1,172 @@
+/**
+ * Context Promotion — move items to higher-priority memory layers.
+ *
+ * Promotion examples: N3→N2, N2→N1, N1→N0, N3→N0, ARCHIVE→N3, etc.
+ *
+ * Side effects handled by this module:
+ *   - Lifecycle transitions when necessary (COMPRESSED → ACTIVE)
+ *   - Metadata updates (memoryLayer, updatedAt, promotion history)
+ *   - Event logging via lifecycleHistory entry
+ *
+ * All operations are immutable: the input item is never mutated.
+ */
+
+import {
+  WORKING_LAYERS,
+  MEMORY_LAYERS,
+  LAYER_CONFIG,
+  isMemoryLayer,
+} from "./context-memory-layers.js";
+import {
+  LIFECYCLE_STATES,
+  transition as lifecycleTransition,
+  canTransition as isValidTransition,
+} from "./context-lifecycle.js";
+
+/**
+ * @typedef {Object} PromotionEvent
+ * @property {"promote"} type
+ * @property {string} fromLayer
+ * @property {string} toLayer
+ * @property {boolean} lifecycleChanged
+ * @property {string} [fromLifecycle]
+ * @property {string} [toLifecycle]
+ * @property {number} timestamp
+ */
+
+/**
+ * @typedef {Object} PromotionResult
+ * @property {Object} item — the promoted item (immutable copy with updates)
+ * @property {PromotionEvent} event
+ */
+
+/**
+ * Promote a context item to a higher-priority memory layer.
+ *
+ * Handles necessary lifecycle transitions (e.g. COMPRESSED → ACTIVE)
+ * before the layer change, updates metadata, and logs the event.
+ *
+ * @param {Object} item - The item to promote (must have memoryLayer or inferable category)
+ * @param {string} targetLayer - Target memory layer (N0–N3)
+ * @returns {PromotionResult}
+ */
+export function promoteItem(item, targetLayer) {
+  if (!item || typeof item !== "object") {
+    throw new TypeError("item must be an object");
+  }
+  if (!isMemoryLayer(targetLayer)) {
+    throw new TypeError(`invalid target layer: ${targetLayer}`);
+  }
+  if (!WORKING_LAYERS.includes(targetLayer)) {
+    throw new TypeError(
+      `cannot promote to ${targetLayer}: use demoteItem for archive moves`,
+    );
+  }
+
+  const currentLayer = resolveCurrentLayer(item);
+  const currentPriority = LAYER_CONFIG[currentLayer].priority;
+  const targetPriority = LAYER_CONFIG[targetLayer].priority;
+
+  if (targetPriority >= currentPriority) {
+    throw new TypeError(
+      `not a promotion: ${currentLayer} (priority ${currentPriority}) → ${targetLayer} (priority ${targetPriority})`,
+    );
+  }
+
+  const now = Date.now();
+
+  // --- Lifecycle transition if necessary ---
+  let lifecycle = item.lifecycle || LIFECYCLE_STATES.CREATED;
+  let lifecycleChanged = false;
+  let fromLifecycle = lifecycle;
+
+  if (lifecycle === LIFECYCLE_STATES.COMPRESSED) {
+    if (isValidTransition(lifecycle, LIFECYCLE_STATES.ACTIVE)) {
+      const transitioned = lifecycleTransition(item, LIFECYCLE_STATES.ACTIVE, {
+        reason: "promotion-from-compressed",
+        timestamp: now,
+      });
+      lifecycle = transitioned.lifecycle;
+      lifecycleChanged = true;
+    }
+  }
+
+  let toLifecycle = lifecycle;
+
+  // --- Build new item (immutable) ---
+  const promotedItem = {
+    ...item,
+    memoryLayer: targetLayer,
+    lifecycle,
+    updatedAt: now,
+    metadata: {
+      ...(item.metadata || {}),
+      promotedFrom: currentLayer,
+      promotedAt: now,
+    },
+    lifecycleHistory: [
+      ...(Array.isArray(item.lifecycleHistory) ? item.lifecycleHistory : []),
+      {
+        type: "promote",
+        from: currentLayer,
+        to: targetLayer,
+        ...(lifecycleChanged
+          ? { lifecycle: { from: fromLifecycle, to: toLifecycle } }
+          : {}),
+        timestamp: now,
+      },
+    ],
+  };
+
+  const event = {
+    type: "promote",
+    fromLayer: currentLayer,
+    toLayer: targetLayer,
+    lifecycleChanged,
+    ...(lifecycleChanged ? { fromLifecycle, toLifecycle } : {}),
+    timestamp: now,
+  };
+
+  return { item: Object.freeze(promotedItem), event };
+}
+
+/**
+ * Resolve the current memory layer of an item.
+ * Falls back from item.memoryLayer → category-based default → N3.
+ *
+ * @param {Object} item
+ * @returns {string}
+ */
+function resolveCurrentLayer(item) {
+  if (isMemoryLayer(item.memoryLayer)) {
+    return item.memoryLayer;
+  }
+  const category = item.type || item.category;
+  if (category && typeof category === "string") {
+    return inferLayerFromCategory(category);
+  }
+  return "N3";
+}
+
+/**
+ * Infer a memory layer from a category string using the same
+ * rules as context-memory-layers.js CATEGORY_DEFAULT_LAYER.
+ *
+ * @param {string} category
+ * @returns {string}
+ */
+function inferLayerFromCategory(category) {
+  const defaults = {
+    REQUIREMENT: "N0",
+    DECISION: "N0",
+    FACT: "N1",
+    OBSERVATION: "N2",
+    EVIDENCE: "N2",
+    RESULT: "N2",
+    ERROR: "N2",
+    CLAIM: "N3",
+    ASSUMPTION: "N3",
+    ACTION: "N3",
+  };
+  return defaults[category] || "N3";
+}

package/src/context/context-query-contract.js

@@ -0,0 +1,101 @@
+import { LIFECYCLE_STATES } from "./context-lifecycle.js";
+import { CONTEXT_EVENT_TYPES } from "./context-event-ingress.js";
+
+export const CONTEXT_PURPOSE = Object.freeze({
+  PLANNING: "PLANNING",
+  IMPLEMENTATION: "IMPLEMENTATION",
+  INVESTIGATION: "INVESTIGATION",
+  DEBUGGING: "DEBUGGING",
+  VALIDATION: "VALIDATION",
+  REVIEW: "REVIEW",
+  RESUME: "RESUME",
+});
+
+const PURPOSE_LAYER_REQUIREMENT = Object.freeze({
+  [CONTEXT_PURPOSE.PLANNING]: ["R0", "R1", "R2"],
+  [CONTEXT_PURPOSE.IMPLEMENTATION]: ["R0", "R1"],
+  [CONTEXT_PURPOSE.INVESTIGATION]: ["H0", "H1"],
+  [CONTEXT_PURPOSE.DEBUGGING]: ["OBS", "EVID"],
+  [CONTEXT_PURPOSE.VALIDATION]: ["VER"],
+  [CONTEXT_PURPOSE.REVIEW]: ["ALL"],
+  [CONTEXT_PURPOSE.RESUME]: ["ALL"],
+});
+
+export function buildContextQuery({
+  taskId,
+  subtaskId = null,
+  requirementId = null,
+  hypothesisId = null,
+  experimentId = null,
+  executionId = null,
+  taskType = null,
+  phase = null,
+  activeFiles = [],
+  activeTools = [],
+  knownFailures = [],
+  unresolvedQuestions = [],
+  budget = null,
+  purpose = CONTEXT_PURPOSE.PLANNING,
+} = {}) {
+  if (!taskId) throw new TypeError("contextQuery requires taskId");
+
+  return {
+    taskId,
+    subtaskId,
+    requirementId,
+    hypothesisId,
+    experimentId,
+    executionId,
+    taskType,
+    phase,
+    activeFiles,
+    activeTools,
+    knownFailures,
+    unresolvedQuestions,
+    budget,
+    purpose,
+    _layerRequirement: PURPOSE_LAYER_REQUIREMENT[purpose] || PURPOSE_LAYER_REQUIREMENT[CONTEXT_PURPOSE.PLANNING],
+    _timestamp: Date.now(),
+  };
+}
+
+export function matchesQuery(item, query) {
+  if (query.requirementId && item.requirementId !== query.requirementId) return false;
+  if (query.hypothesisId && item.hypothesisId !== query.hypothesisId) return false;
+  if (query.experimentId && item.experimentId !== query.experimentId) return false;
+  if (query.executionId && item.executionId !== query.executionId) return false;
+  if (query.taskType && item.taskType && item.taskType !== query.taskType) return false;
+  if (query.phase && item.phase && item.phase !== query.phase) return false;
+  if (query.activeFiles && query.activeFiles.length > 0 && item.scope === "FILE") {
+    if (!query.activeFiles.some((f) => (item.content?.path || "").includes(f))) return false;
+  }
+  if (query.activeTools && query.activeTools.length > 0 && item.scope === "TOOL") {
+    if (!query.activeTools.some((t) => (item.content?.tool || "").includes(t))) return false;
+  }
+  return true;
+}
+
+export function scoreRelevance(item, query) {
+  let score = 0;
+  if (item.mandatoryIncluded === true) score += 10;
+  if (item.lifecycle === LIFECYCLE_STATES.ACTIVE) score += 5;
+  if (item.lifecycle === LIFECYCLE_STATES.CREATED) score += 3;
+  if (item.importance === "HIGH") score += 5;
+  if (item.importance === "MEDIUM") score += 3;
+  if (item.unresolvedCriticalUnknowns?.length > 0) score += 8;
+  if (query.requirementId && item.requirementId === query.requirementId) score += 10;
+  if (query.hypothesisId && item.hypothesisId === query.hypothesisId) score += 10;
+  if (query.experimentId && item.experimentId === query.experimentId) score += 10;
+  if (query.executionId && item.executionId === query.executionId) score += 10;
+  const recency = (query._timestamp || Date.now()) - item.timestamp;
+  if (recency < 60000) score += 5;
+  else if (recency < 300000) score += 3;
+  return score;
+}
+
+export function retrieveRelevantContext(items, query) {
+  const filtered = items.filter((item) => matchesQuery(item, query));
+  const scored = filtered.map((item) => ({ item, score: scoreRelevance(item, query) }));
+  scored.sort((a, b) => b.score - a.score);
+  return scored.map((s) => s.item);
+}

package/src/context/context-ranking.js

@@ -0,0 +1,164 @@
+/**
+ * Context Ranking — Relevance Scoring & Ranking.
+ *
+ * Change 70: Implements multi-signal ranking for context retrieval.
+ * Scores combine term matching, recency, importance, lifecycle state,
+ * and provenance quality.
+ *
+ * Ranking formula (weighted sum):
+ *   score = w1 * termMatch + w2 * recency + w3 * importance + w4 * lifecycleBoost
+ *
+ * Invariant: All scores normalized to [0, 1] range. Higher = more relevant.
+ */
+
+const WEIGHTS = Object.freeze({
+  termMatch: 0.40,
+  recency: 0.15,
+  importance: 0.25,
+  lifecycle: 0.10,
+  provenance: 0.10,
+});
+
+const LIFECYCLE_BOOST = Object.freeze({
+  ACTIVE: 1.0,
+  CREATED: 0.8,
+  COMPRESSED: 0.4,
+  STALE: 0.2,
+  INVALIDATED: 0.0,
+  ARCHIVED: 0.1,
+});
+
+const PROVENANCE_BOOST = Object.freeze({
+  user_decided: 1.0,
+  observed: 0.7,
+  inferred: 0.3,
+});
+
+/**
+ * Tokenizes text into a set of lowercase terms.
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+function tokenize(text = "") {
+  return new Set(
+    (text || "")
+      .toLowerCase()
+      .replace(/[^a-z0-9áéíóúñü\s]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 1)
+  );
+}
+
+/**
+ * Computes term overlap ratio between query and item text.
+ * @param {string} query
+ * @param {string} itemText
+ * @returns {number} 0..1
+ */
+function computeTermMatch(query, itemText) {
+  const queryTokens = tokenize(query);
+  const itemTokens = tokenize(itemText);
+  if (!queryTokens.size || !itemTokens.size) return 0;
+
+  let hits = 0;
+  for (const t of queryTokens) {
+    if (itemTokens.has(t)) hits++;
+  }
+  return hits / queryTokens.size;
+}
+
+/**
+ * Computes recency score based on item timestamp.
+ * More recent = higher score. Decays over 30 days.
+ * @param {number} [timestamp]
+ * @param {number} [now]
+ * @returns {number} 0..1
+ */
+function computeRecency(timestamp, now = Date.now()) {
+  if (!timestamp) return 0.5;
+  const ageMs = now - timestamp;
+  const ageDays = ageMs / (1000 * 60 * 60 * 24);
+  // Exponential decay: 1.0 at 0 days, ~0.1 at 30 days
+  return Math.exp(-ageDays / 30);
+}
+
+/**
+ * Computes importance score from item metadata.
+ * @param {number} [importance]
+ * @returns {number} 0..1
+ */
+function computeImportance(importance) {
+  if (typeof importance !== "number") return 0.5;
+  return Math.min(1, Math.max(0, importance / 10));
+}
+
+/**
+ * Computes lifecycle boost factor.
+ * @param {string} lifecycle
+ * @returns {number}
+ */
+function computeLifecycleBoost(lifecycle) {
+  return LIFECYCLE_BOOST[lifecycle] ?? 0.3;
+}
+
+/**
+ * Computes provenance quality factor.
+ * @param {string} provenance
+ * @returns {number}
+ */
+function computeProvenanceBoost(provenance) {
+  return PROVENANCE_BOOST[provenance] ?? 0.3;
+}
+
+/**
+ * Ranks context items by multi-signal relevance scoring.
+ *
+ * @param {Array} items - Context items to rank.
+ * @param {string} query - Search query for term matching.
+ * @param {Object} [options]
+ * @param {string[]} [options.requiredTerms] - Terms that must appear (binary filter).
+ * @param {Object} [options.weights] - Override default weights.
+ * @returns {Array} Items sorted by relevanceScore descending, with score attached.
+ */
+export function rankContextItems(items, query, options = {}) {
+  const { requiredTerms = [], weights = {} } = options;
+  const w = { ...WEIGHTS, ...weights };
+
+  // Validate weights sum ~1.0 (informational only)
+  const weightSum = Object.values(w).reduce((a, b) => a + b, 0);
+
+  return items
+    .map((item) => {
+      const text = item.content || item.label || item.text || item.summary || `${item.id}`;
+      const termScore = computeTermMatch(query, text);
+      const recencyScore = computeRecency(item.timestamp || item.updatedAt);
+      const importanceScore = computeImportance(item.importance);
+      const lifecycleScore = computeLifecycleBoost(item.lifecycle);
+      const provenanceScore = computeProvenanceBoost(item.provenance);
+
+      // Required terms binary filter (not a score component)
+      if (requiredTerms.length > 0) {
+        const itemTokens = tokenize(text);
+        const allRequiredPresent = requiredTerms.every((t) => itemTokens.has(t.toLowerCase()));
+        if (!allRequiredPresent) {
+          return { ...item, relevanceScore: 0, relevanceReason: "required_terms_missing" };
+        }
+      }
+
+      const compositeScore =
+        w.termMatch * termScore +
+        w.recency * recencyScore +
+        w.importance * importanceScore +
+        w.lifecycle * lifecycleScore +
+        w.provenance * provenanceScore;
+
+      return {
+        ...item,
+        relevanceScore: Math.round(compositeScore * 1000) / 1000,
+        relevanceReason: `term:${termScore.toFixed(2)} recency:${recencyScore.toFixed(2)} importance:${importanceScore.toFixed(2)}`,
+      };
+    })
+    .sort((a, b) => (b.relevanceScore ?? 0) - (a.relevanceScore ?? 0));
+}
+
+export { WEIGHTS, LIFECYCLE_BOOST, PROVENANCE_BOOST };