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

package/src/state/replay-engine.js

@@ -0,0 +1,5 @@
+export function replayEvents(events, initialState) {
+  return events.reduce((state, event) => {
+    return { ...state, ...event };
+  }, initialState);
+}

package/src/state/requirement-ownership.js

@@ -0,0 +1,20 @@
+// Requirement ownership: verify who can validate a requirement
+export function verifyRequirementOwnership(task, owner) {
+  if (!task || !owner) return { owned: false, reason: "missing-input" };
+  const taskOwner = task.owner || task.assignedTo || null;
+  if (taskOwner === owner) return { owned: true, owner: taskOwner };
+  if (task.verifiers && Array.isArray(task.verifiers) && task.verifiers.includes(owner)) {
+    return { owned: true, owner: taskOwner };
+  }
+  return { owned: false, reason: "not-owner", owner: taskOwner };
+}
+
+// Assert that a task can be verified given its state and ownership
+export function assertCanVerify(task, verifier) {
+  if (!task) return { canVerify: false, reason: "missing-task" };
+  if (task.status === "VERIFIED") return { canVerify: false, reason: "already-verified" };
+  if (task.status === "BLOCKED") return { canVerify: false, reason: "blocked" };
+  const ownership = verifyRequirementOwnership(task, verifier);
+  if (!ownership.owned) return { canVerify: false, reason: "no-ownership", ...ownership };
+  return { canVerify: true, verifier };
+}

package/src/state/requirement-state.js

@@ -0,0 +1,152 @@
+/**
+ * Requirement State Machine
+ *
+ * Formalizes the lifecycle states of a requirement and the legal transitions
+ * between them. Used by completion-gate to determine whether a requirement can
+ * be considered complete.
+ *
+ * States:
+ *  - PENDING      : requirement identified but not started
+ *  - IN_PROGRESS  : work is being done; some evidence may exist
+ *  - VERIFIED     : sufficient verified evidence exists; gates can pass
+ *  - INVALIDATED  : existing evidence was invalidated (stale, contradicted, etc.)
+ *  - BLOCKED      : cannot proceed (dependency, missing info, external blocker)
+ *  - NEEDS_REPLAN : current approach cannot satisfy the requirement
+ *
+ * Transition table is the source of truth. Any transition not listed is
+ * considered illegal and will return { allowed: false } from canTransition().
+ */
+
+export const REQUIREMENT_STATES = Object.freeze({
+  PENDING: "PENDING",
+  IN_PROGRESS: "IN_PROGRESS",
+  VERIFIED: "VERIFIED",
+  INVALIDATED: "INVALIDATED",
+  BLOCKED: "BLOCKED",
+  NEEDS_REPLAN: "NEEDS_REPLAN",
+});
+
+export const TERMINAL_STATES = new Set([
+  REQUIREMENT_STATES.VERIFIED,
+]);
+
+/**
+ * Allowed transitions: from -> Set(to).
+ * VERIFIED is intentionally reachable from a small set of states to avoid
+ * silently promoting blocked/needs-replan requirements.
+ */
+export const TRANSITIONS = Object.freeze({
+  [REQUIREMENT_STATES.PENDING]: new Set([
+    REQUIREMENT_STATES.IN_PROGRESS,
+    REQUIREMENT_STATES.BLOCKED,
+  ]),
+  [REQUIREMENT_STATES.IN_PROGRESS]: new Set([
+    REQUIREMENT_STATES.VERIFIED,
+    REQUIREMENT_STATES.INVALIDATED,
+    REQUIREMENT_STATES.BLOCKED,
+    REQUIREMENT_STATES.NEEDS_REPLAN,
+    REQUIREMENT_STATES.PENDING,
+  ]),
+  [REQUIREMENT_STATES.VERIFIED]: new Set([
+    // Once verified, it can be invalidated if evidence is later contradicted.
+    REQUIREMENT_STATES.INVALIDATED,
+  ]),
+  [REQUIREMENT_STATES.INVALIDATED]: new Set([
+    REQUIREMENT_STATES.IN_PROGRESS,
+    REQUIREMENT_STATES.NEEDS_REPLAN,
+    REQUIREMENT_STATES.PENDING,
+  ]),
+  [REQUIREMENT_STATES.BLOCKED]: new Set([
+    REQUIREMENT_STATES.IN_PROGRESS,
+    REQUIREMENT_STATES.PENDING,
+    REQUIREMENT_STATES.NEEDS_REPLAN,
+  ]),
+  [REQUIREMENT_STATES.NEEDS_REPLAN]: new Set([
+    REQUIREMENT_STATES.PENDING,
+    REQUIREMENT_STATES.IN_PROGRESS,
+  ]),
+});
+
+/**
+ * Returns whether `to` is a legal next state from `from`.
+ */
+export function canTransition(from, to) {
+  if (!Object.values(REQUIREMENT_STATES).includes(to)) {
+    return { allowed: false, reason: `unknown target state: ${to}` };
+  }
+  const allowed = TRANSITIONS[from];
+  if (!allowed) {
+    return { allowed: false, reason: `unknown source state: ${from}` };
+  }
+  if (!allowed.has(to)) {
+    return {
+      allowed: false,
+      reason: `illegal transition ${from} -> ${to}`,
+    };
+  }
+  return { allowed: true };
+}
+
+/**
+ * Executes a transition. Returns a new state object (immutable update) or
+ * an { error } object if the transition is illegal.
+ */
+export function transition(requirement, to) {
+  if (!requirement || typeof requirement !== "object") {
+    return { error: "requirement must be an object" };
+  }
+  const from = requirement.status || REQUIREMENT_STATES.PENDING;
+  const check = canTransition(from, to);
+  if (!check.allowed) {
+    return { error: check.reason, from, to };
+  }
+  return {
+    ...requirement,
+    status: to,
+    lastTransitionAt: new Date().toISOString(),
+    lastTransitionFrom: from,
+  };
+}
+
+/**
+ * Pure decision: is this requirement eligible for completion?
+ * Only VERIFIED requirements are complete.
+ */
+export function isRequirementComplete(requirement) {
+  return Boolean(
+    requirement &&
+    typeof requirement === "object" &&
+    requirement.status === REQUIREMENT_STATES.VERIFIED
+  );
+}
+
+/**
+ * Aggregates a list of requirements into an overall verdict.
+ * Returns { allComplete, blocked, incomplete, summary }.
+ */
+export function summarizeRequirements(requirements = []) {
+  const incomplete = [];
+  const blocked = [];
+  for (const req of requirements) {
+    if (!isRequirementComplete(req)) {
+      incomplete.push(req);
+      if (
+        req.status === REQUIREMENT_STATES.BLOCKED ||
+        req.status === REQUIREMENT_STATES.NEEDS_REPLAN
+      ) {
+        blocked.push(req);
+      }
+    }
+  }
+  return {
+    allComplete: incomplete.length === 0,
+    incomplete,
+    blocked,
+    summary: {
+      total: requirements.length,
+      complete: requirements.length - incomplete.length,
+      incomplete: incomplete.length,
+      blocked: blocked.length,
+    },
+  };
+}

package/src/state/run-event-identity.js

@@ -0,0 +1,172 @@
+/**
+ * Run Event Identity — scoped, stable event IDs.
+ *
+ * Events use composite IDs: <runId>:<type>:<sequence>
+ *
+ * Format:
+ *   run-003:act:001
+ *   run-003:obs:004
+ *   run-003:dec:002
+ *   run-003:ev:003
+ *
+ * Benefits:
+ *   - Unique within task (different runs have different prefixes)
+ *   - Readable and debuggable
+ *   - Legacy IDs still supported for backward compatibility
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {"act" | "obs" | "dec" | "ev"} EventType
+ */
+
+/**
+ * Generate a scoped event ID.
+ *
+ * @param {string} runId - Run ID (e.g., "run-003")
+ * @param {EventType} type - Event type
+ * @param {number} sequence - Sequence number
+ * @returns {string} Scoped event ID (e.g., "run-003:act:001")
+ */
+export function generateEventId(runId, type, sequence) {
+  const seq = String(sequence).padStart(3, "0");
+  return `${runId}:${type}:${seq}`;
+}
+
+/**
+ * Parse a scoped event ID into components.
+ *
+ * @param {string} eventId - Scoped event ID
+ * @returns {{ runId: string, type: EventType, sequence: number } | null}
+ */
+export function parseEventId(eventId) {
+  if (!eventId || typeof eventId !== "string") return null;
+
+  const parts = eventId.split(":");
+  if (parts.length !== 3) return null;
+
+  const [runId, type, seqStr] = parts;
+  const sequence = parseInt(seqStr, 10);
+
+  if (isNaN(sequence)) return null;
+  if (!["act", "obs", "dec", "ev"].includes(type)) return null;
+
+  return { runId, type: /** @type {EventType} */ (type), sequence };
+}
+
+/**
+ * Check if an ID is a scoped event ID (vs legacy).
+ *
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isScopedEventId(id) {
+  return parseEventId(id) !== null;
+}
+
+/**
+ * Get the next sequence number for an event type in a run.
+ *
+ * @param {Object} run - Run object
+ * @param {EventType} type - Event type
+ * @returns {number} Next sequence number
+ */
+export function getNextSequence(run, type) {
+  const fieldMap = {
+    act: "actions",
+    obs: "observations",
+    dec: "decisions",
+    ev: "evidence",
+  };
+
+  const field = fieldMap[type];
+  if (!field || !run[field]) return 1;
+
+  // Count existing scoped IDs for this type
+  let maxSeq = 0;
+  for (const event of run[field]) {
+    if (event.id && isScopedEventId(event.id)) {
+      const parsed = parseEventId(event.id);
+      if (parsed && parsed.type === type && parsed.sequence > maxSeq) {
+        maxSeq = parsed.sequence;
+      }
+    }
+  }
+
+  return maxSeq + 1;
+}
+
+/**
+ * Create a scoped event within a run.
+ *
+ * @param {Object} run - Run object
+ * @param {EventType} type - Event type
+ * @param {Object} data - Event data
+ * @returns {Object} Created event with scoped ID
+ */
+export function createScopedEvent(run, type, data) {
+  const sequence = getNextSequence(run, type);
+  const id = generateEventId(run.id, type, sequence);
+
+  return {
+    id,
+    ...data,
+    timestamp: Date.now(),
+  };
+}
+
+/**
+ * Migrate legacy event IDs to scoped format.
+ *
+ * @param {Object} run - Run object
+ * @returns {Object} Run with migrated IDs
+ */
+export function migrateRunEventIds(run) {
+  if (!run) return run;
+
+  const fieldMap = {
+    actions: "act",
+    observations: "obs",
+    decisions: "dec",
+    evidence: "ev",
+  };
+
+  for (const [field, type] of Object.entries(fieldMap)) {
+    if (!run[field]) continue;
+
+    for (let i = 0; i < run[field].length; i++) {
+      const event = run[field][i];
+      // Only migrate legacy IDs (not already scoped)
+      if (event.id && !isScopedEventId(event.id)) {
+        const sequence = i + 1;
+        event.id = generateEventId(run.id, type, sequence);
+      }
+    }
+  }
+
+  return run;
+}
+
+/**
+ * Get event type from scoped ID.
+ *
+ * @param {string} eventId
+ * @returns {EventType | null}
+ */
+export function getEventType(eventId) {
+  const parsed = parseEventId(eventId);
+  return parsed ? parsed.type : null;
+}
+
+/**
+ * Get run ID from scoped event ID.
+ *
+ * @param {string} eventId
+ * @returns {string | null}
+ */
+export function getRunIdFromEvent(eventId) {
+  const parsed = parseEventId(eventId);
+  return parsed ? parsed.runId : null;
+}

package/src/state/state-engine.js

@@ -0,0 +1,19 @@
+/**
+ * Formal Execution State — WAM 1.2
+ *
+ * Implementa el lifecycle formal de la tarea.
+ */
+export const STATE = {
+  INITIALIZING: "INITIALIZING",
+  INVESTIGATING: "INVESTIGATING",
+  EXECUTING: "EXECUTING",
+  VERIFYING: "VERIFYING",
+  COMPLETED: "COMPLETED",
+  BLOCKED: "BLOCKED",
+  WAITING_AUTHORIZATION: "WAITING_AUTHORIZATION",
+  FAILED: "FAILED",
+};
+
+export function getPhaseLabel(phase) {
+  return phase || STATE.INITIALIZING;
+}

package/src/state/state-machine.js

@@ -0,0 +1,119 @@
+/**
+ * State Machine — centralized transitions for hypothesis / experiment /
+ * evidence events during the execution loop.
+ *
+ * Pure functions: given an assessment (and optional supporting context),
+ * return the next status and any side-effect descriptors. No I/O.
+ *
+ * Decouples decision logic from execution-engine.js so status transitions
+ * become testable in isolation and reusable across noteSuccess / noteFailure /
+ * handleContradiction callers.
+ */
+
+import { AssessmentResult } from "../policy/assessment-engine.js";
+import { HYPOTHESIS_STATUS, EXPERIMENT_STATUS } from "../cognition/cognition-store.js";
+
+export { HYPOTHESIS_STATUS, EXPERIMENT_STATUS };
+
+/**
+ * Contradiction severity classification. Higher severity → faster replan.
+ */
+export const SEVERITY = Object.freeze({
+  HIGH: "high",
+  LOW: "low",
+  NONE: null,
+});
+
+/**
+ * Derive the next hypothesis status from an assessment verdict.
+ * Returns { status, severity } so callers can branch on both.
+ *
+ * Rules (M2 execution-loop contract):
+ *   - SUPPORTED     → SUPPORTED, no severity
+ *   - CONTRADICTED  → REJECTED (high) when contradicted > supported; else TESTING (low)
+ *   - INCONCLUSIVE  → TESTING, no severity
+ *
+ * @param {object} assessment - { result, summary: { contradicted, supported } }
+ * @returns {{status: string, severity: string|null}}
+ */
+export function deriveHypothesisStatus(assessment) {
+  if (!assessment || typeof assessment !== "object") {
+    return { status: HYPOTHESIS_STATUS.TESTING, severity: SEVERITY.NONE };
+  }
+  if (assessment.result === AssessmentResult.SUPPORTED) {
+    return { status: HYPOTHESIS_STATUS.SUPPORTED, severity: SEVERITY.NONE };
+  }
+  if (assessment.result === AssessmentResult.CONTRADICTED) {
+    const { summary = {} } = assessment;
+    const contradicted = summary.contradicted || 0;
+    const supported = summary.supported || 0;
+    if (contradicted > supported && contradicted > 0) {
+      return { status: HYPOTHESIS_STATUS.REJECTED, severity: SEVERITY.HIGH };
+    }
+    return { status: HYPOTHESIS_STATUS.TESTING, severity: SEVERITY.LOW };
+  }
+  return { status: HYPOTHESIS_STATUS.TESTING, severity: SEVERITY.NONE };
+}
+
+/**
+ * Decide whether the current outcome should trigger a replan.
+ * A replan is warranted when:
+ *   - assessment is CONTRADICTED AND
+ *   - hypothesis has moved to REJECTED (high severity contradiction), OR
+ *   - hypothesis remains TESTING but contradicted (caller may want to re-explore)
+ *
+ * @param {object} args
+ * @param {object} args.assessment
+ * @param {string} args.hypothesisStatus
+ * @returns {boolean}
+ */
+export function shouldReplan({ assessment, hypothesisStatus }) {
+  if (!assessment || assessment.result !== AssessmentResult.CONTRADICTED) return false;
+  if (hypothesisStatus === HYPOTHESIS_STATUS.REJECTED) return true;
+  return false;
+}
+
+/**
+ * Decide whether the contradiction should be noted as a learning event
+ * (without forcing a full replan).
+ *
+ * @param {object} args
+ * @param {object} args.assessment
+ * @param {string} args.hypothesisStatus
+ * @returns {boolean}
+ */
+export function shouldNoteContradiction({ assessment, hypothesisStatus }) {
+  if (!assessment || assessment.result !== AssessmentResult.CONTRADICTED) return false;
+  // When REJECTED, the caller may already replan; still useful to note it.
+  return hypothesisStatus !== HYPOTHESIS_STATUS.SUPPORTED;
+}
+
+/**
+ * Pick the experiment terminal status for an outcome.
+ *
+ * @param {string} outcome - "success" | "failure"
+ * @returns {string}
+ */
+export function deriveExperimentStatus(outcome) {
+  return outcome === "failure"
+    ? EXPERIMENT_STATUS.FAILED
+    : EXPERIMENT_STATUS.COMPLETED;
+}
+
+/**
+ * Contradiction-handling transition: given a contradicted experiment,
+ * compute the next hypothesis status + replan trigger descriptor.
+ *
+ * @param {object} args
+ * @param {string} args.outcome - "success" | "failure" | "contradicted"
+ * @param {object} args.assessment
+ * @returns {{status: string, replan: boolean, severity: string|null}}
+ */
+export function transitionAfterOutcome({ outcome, assessment }) {
+  const derived = deriveHypothesisStatus(assessment);
+  const replan = shouldReplan({
+    assessment,
+    hypothesisStatus: derived.status,
+  });
+  return { ...derived, replan };
+}