ultra-builder-pro-cli 0.5.3 → 0.7.0

package/mcp-server/lib/runtime-state.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+
+const ops = require('./state-ops.cjs');
+const defaultProjector = require('./projector.cjs');
+
+class RuntimeStateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'RuntimeStateError';
+    this.code = code;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function parseJson(value) {
+  if (value == null) return null;
+  try { return JSON.parse(value); }
+  catch (error) {
+    throw new RuntimeStateError('STATE_CORRUPT', `invalid runtime JSON: ${error.message}`);
+  }
+}
+
+function rowToIncident(row) {
+  if (!row) return null;
+  return {
+    ...row,
+    retryable: Boolean(row.retryable),
+    evidence: parseJson(row.evidence_json),
+  };
+}
+
+function recordIncident(db, input) {
+  if (!input || !input.code || !input.message) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'incident code and message required');
+  }
+  return ops.tx(db, () => {
+    const existing = db.prepare(
+      `SELECT * FROM incidents
+       WHERE status = 'open' AND code = ?
+         AND change_id IS ? AND task_id IS ? AND session_id IS ?
+         AND source_kind IS ? AND source_id IS ?
+       ORDER BY first_seen_at ASC LIMIT 1`,
+    ).get(
+      input.code, input.change_id ?? null, input.task_id ?? null, input.session_id ?? null,
+      input.source_kind ?? null, input.source_id ?? null,
+    );
+    const ts = nowIso();
+    if (existing) {
+      db.prepare(
+        `UPDATE incidents SET message = ?, severity = ?, retryable = ?, evidence_json = ?,
+         occurrence_count = occurrence_count + 1, last_seen_at = ? WHERE id = ?`,
+      ).run(
+        input.message, input.severity || 'error', input.retryable ? 1 : 0,
+        input.evidence === undefined ? existing.evidence_json : JSON.stringify(input.evidence),
+        ts, existing.id,
+      );
+      return rowToIncident(db.prepare('SELECT * FROM incidents WHERE id = ?').get(existing.id));
+    }
+    const id = `inc-${randomUUID().slice(0, 12)}`;
+    db.prepare(
+      `INSERT INTO incidents
+       (id, code, severity, retryable, message, change_id, task_id, session_id,
+        source_kind, source_id, evidence_json, first_seen_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id, input.code, input.severity || 'error', input.retryable ? 1 : 0, input.message,
+      input.change_id ?? null, input.task_id ?? null, input.session_id ?? null,
+      input.source_kind ?? null, input.source_id ?? null,
+      input.evidence === undefined ? null : JSON.stringify(input.evidence), ts, ts,
+    );
+    return rowToIncident(db.prepare('SELECT * FROM incidents WHERE id = ?').get(id));
+  });
+}
+
+function resolveIncident(db, id, resolution) {
+  const result = db.prepare(
+    `UPDATE incidents SET status = 'resolved', resolved_at = ?, resolution = ?
+     WHERE id = ? AND status = 'open'`,
+  ).run(nowIso(), resolution || 'resolved', id);
+  return { resolved: result.changes > 0 };
+}
+
+const LIST_INCIDENTS_SQL = "SELECT * FROM incidents WHERE (@status IS NULL OR status = @status) AND (@change_id IS NULL OR change_id = @change_id) AND (@task_id IS NULL OR task_id = @task_id) ORDER BY last_seen_at DESC LIMIT @maxn";
+
+function listIncidents(db, { status = null, change_id = null, task_id = null, limit = 100 } = {}) {
+  return db.prepare(LIST_INCIDENTS_SQL).all({
+    status, change_id, task_id, maxn: Math.min(Math.max(limit, 1), 500),
+  }).map(rowToIncident);
+}
+
+function enqueueProjection(db, { tool_name, event_cursor, max_attempts = 3 } = {}) {
+  if (!tool_name) throw new RuntimeStateError('VALIDATION_ERROR', 'projection tool_name required');
+  const cursor = Number.isInteger(event_cursor)
+    ? event_cursor
+    : Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM events').get().id);
+  const result = db.prepare(
+    `INSERT INTO projection_jobs (tool_name, event_cursor, max_attempts)
+     VALUES (?, ?, ?)`,
+  ).run(tool_name, cursor, max_attempts);
+  return readProjectionJob(db, Number(result.lastInsertRowid));
+}
+
+function readProjectionJob(db, id) {
+  return db.prepare('SELECT * FROM projection_jobs WHERE id = ?').get(id) || null;
+}
+
+const LIST_PROJECTION_JOBS_SQL = "SELECT * FROM projection_jobs WHERE (@status IS NULL OR status = @status) ORDER BY id ASC LIMIT @maxn";
+
+function listProjectionJobs(db, { status = null, limit = 100 } = {}) {
+  return db.prepare(LIST_PROJECTION_JOBS_SQL).all({
+    status, maxn: Math.min(Math.max(limit, 1), 500),
+  });
+}
+
+function processProjectionJobs(db, {
+  rootDir = '.', project = defaultProjector.projectAll, limit = 10,
+} = {}) {
+  const pending = listProjectionJobs(db, { status: 'pending', limit });
+  const jobs = [];
+  for (const row of pending) {
+    const claimed = db.prepare(
+      "UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ? AND status = 'pending'",
+    ).run(nowIso(), row.id);
+    if (claimed.changes === 0) continue;
+    const active = readProjectionJob(db, row.id);
+    try {
+      const projection = project(db, { rootDir });
+      const ts = nowIso();
+      db.prepare(
+        `UPDATE projection_jobs SET status = 'completed', attempts = attempts + 1,
+         last_error = NULL, updated_at = ?, completed_at = ? WHERE id = ?`,
+      ).run(ts, ts, row.id);
+      const related = db.prepare(
+        "SELECT id FROM incidents WHERE status = 'open' AND source_kind = 'projection_job' AND source_id = ?",
+      ).all(String(row.id));
+      for (const incident of related) resolveIncident(db, incident.id, 'projection completed on retry');
+      jobs.push({ id: row.id, status: 'completed', projection });
+    } catch (error) {
+      const attempts = active.attempts + 1;
+      const status = attempts >= active.max_attempts ? 'failed' : 'pending';
+      db.prepare(
+        `UPDATE projection_jobs SET status = ?, attempts = ?, last_error = ?, updated_at = ?
+         WHERE id = ?`,
+      ).run(status, attempts, error.message, nowIso(), row.id);
+      const incident = recordIncident(db, {
+        code: 'PROJECTION_FAILED', severity: 'error', retryable: true,
+        message: error.message, source_kind: 'projection_job', source_id: String(row.id),
+        evidence: { tool_name: row.tool_name, event_cursor: row.event_cursor, attempts },
+      });
+      jobs.push({ id: row.id, status: status === 'pending' ? 'retrying' : 'failed', error: error.message, incident_id: incident.id });
+    }
+  }
+  return { processed: jobs.length, jobs };
+}
+
+function requeueInterruptedProjections(db, { staleBefore } = {}) {
+  const cutoff = staleBefore || new Date(Date.now() - 5 * 60 * 1000).toISOString();
+  if (typeof cutoff !== 'string' || Number.isNaN(Date.parse(cutoff))) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'staleBefore must be an ISO date-time');
+  }
+  const result = db.prepare(
+    `UPDATE projection_jobs
+     SET status = 'pending', last_error = 'interrupted projection requeued by doctor',
+         updated_at = ?, completed_at = NULL
+     WHERE status = 'running' AND updated_at < ?`,
+  ).run(nowIso(), cutoff);
+  return { requeued: result.changes, stale_before: cutoff };
+}
+
+function requeueFailedProjections(db) {
+  const result = db.prepare(
+    "UPDATE projection_jobs SET status = 'pending', attempts = 0, updated_at = ? WHERE status = 'failed'",
+  ).run(nowIso());
+  return { requeued: result.changes };
+}
+
+function ensureProjectionJob(db, { tool_name = 'runtime.reconcile' } = {}) {
+  const eventCursor = Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM events').get().id);
+  const projectedCursor = Number(db.prepare(
+    "SELECT COALESCE(MAX(event_cursor), 0) AS id FROM projection_jobs WHERE status IN ('pending', 'running', 'completed')",
+  ).get().id);
+  if (eventCursor <= projectedCursor) return { enqueued: false, event_cursor: eventCursor };
+  return { enqueued: true, job: enqueueProjection(db, { tool_name, event_cursor: eventCursor }) };
+}
+
+function readConsumerCursor(db, name) {
+  const row = db.prepare('SELECT cursor FROM event_consumers WHERE name = ?').get(name);
+  return row ? Number(row.cursor) : 0;
+}
+
+function writeConsumerCursor(db, name, cursor) {
+  if (!name || !Number.isInteger(cursor) || cursor < 0) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'consumer name and non-negative cursor required');
+  }
+  db.prepare(
+    `INSERT INTO event_consumers (name, cursor, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(name) DO UPDATE SET
+       cursor = MAX(event_consumers.cursor, excluded.cursor), updated_at = excluded.updated_at`,
+  ).run(name, cursor, nowIso());
+  return { name, cursor: readConsumerCursor(db, name) };
+}
+
+module.exports = {
+  RuntimeStateError,
+  recordIncident,
+  resolveIncident,
+  listIncidents,
+  enqueueProjection,
+  readProjectionJob,
+  listProjectionJobs,
+  processProjectionJobs,
+  requeueInterruptedProjections,
+  requeueFailedProjections,
+  ensureProjectionJob,
+  readConsumerCursor,
+  writeConsumerCursor,
+};

package/mcp-server/lib/runtime-state.test.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const runtime = require('./runtime-state.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-runtime-state-'));
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  return { rootDir, db };
+}
+
+function cleanup({ rootDir, db }) {
+  closeStateDb(db);
+  fs.rmSync(rootDir, { recursive: true, force: true });
+}
+
+test('projection jobs complete and retain their event cursor', () => {
+  const fx = fixture();
+  try {
+    const job = runtime.enqueueProjection(fx.db, { tool_name: 'task.create', event_cursor: 7 });
+    const result = runtime.processProjectionJobs(fx.db, {
+      rootDir: fx.rootDir,
+      project: () => ({ tasks_json: { count: 0 }, contexts: [] }),
+    });
+    assert.equal(result.processed, 1);
+    assert.equal(result.jobs[0].status, 'completed');
+    const stored = runtime.readProjectionJob(fx.db, job.id);
+    assert.equal(stored.status, 'completed');
+    assert.equal(stored.event_cursor, 7);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('projection failures are explicit, retryable incidents rather than swallowed warnings', () => {
+  const fx = fixture();
+  try {
+    runtime.enqueueProjection(fx.db, { tool_name: 'task.update', event_cursor: 4, max_attempts: 1 });
+    // Test Double rationale: deterministic projector failure is required; filesystem permission failures vary by host.
+    const result = runtime.processProjectionJobs(fx.db, {
+      rootDir: fx.rootDir,
+      project: () => { throw new Error('projection disk unavailable'); },
+    });
+    assert.equal(result.jobs[0].status, 'failed');
+    assert.match(result.jobs[0].error, /projection disk unavailable/);
+    const incidents = runtime.listIncidents(fx.db, { status: 'open' });
+    assert.equal(incidents.length, 1);
+    assert.equal(incidents[0].code, 'PROJECTION_FAILED');
+    assert.equal(incidents[0].retryable, true);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('event consumer cursors are durable and monotonic', () => {
+  const fx = fixture();
+  try {
+    assert.equal(runtime.readConsumerCursor(fx.db, 'spec-staleness'), 0);
+    runtime.writeConsumerCursor(fx.db, 'spec-staleness', 12);
+    runtime.writeConsumerCursor(fx.db, 'spec-staleness', 9);
+    assert.equal(runtime.readConsumerCursor(fx.db, 'spec-staleness'), 12);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('interrupted running projections are requeued only after the stale cutoff', () => {
+  const fx = fixture();
+  try {
+    const stale = runtime.enqueueProjection(fx.db, { tool_name: 'task.update', event_cursor: 3 });
+    const fresh = runtime.enqueueProjection(fx.db, { tool_name: 'task.create', event_cursor: 4 });
+    fx.db.prepare("UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ?")
+      .run('2000-01-01T00:00:00.000Z', stale.id);
+    fx.db.prepare("UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ?")
+      .run('2999-01-01T00:00:00.000Z', fresh.id);
+
+    const result = runtime.requeueInterruptedProjections(fx.db, {
+      staleBefore: '2026-01-01T00:00:00.000Z',
+    });
+    assert.equal(result.requeued, 1);
+    assert.equal(runtime.readProjectionJob(fx.db, stale.id).status, 'pending');
+    assert.equal(runtime.readProjectionJob(fx.db, fresh.id).status, 'running');
+  } finally {
+    cleanup(fx);
+  }
+});

package/mcp-server/lib/state-db.cjs

@@ -9,7 +9,7 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '8A.2';
+const EXPECTED_VERSION = '9.0';
 
 const REQUIRED_TABLES = Object.freeze([
   'tasks',
@@ -20,6 +20,13 @@ const REQUIRED_TABLES = Object.freeze([
   'telemetry',
   'specs_refs',
   'circuit_breaker',
+  'changes',
+  'artifacts',
+  'context_snapshots',
+  'trace_links',
+  'incidents',
+  'projection_jobs',
+  'event_consumers',
 ]);
 
 function readSchemaSql() {
@@ -64,18 +71,33 @@ function columnNames(db, table) {
   return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
 }
 
-function applyCompatibleUpgrades(db) {
+function applyCompatibleColumns(db) {
+  const tables = new Set(tableNames(db));
+  if (!tables.has('tasks')) return;
   const taskColumns = columnNames(db, 'tasks');
   if (!taskColumns.has('estimated_days')) {
-    db.transaction(() => {
-      db.exec('ALTER TABLE tasks ADD COLUMN estimated_days REAL CHECK (estimated_days IS NULL OR estimated_days > 0)');
-      db.prepare(
-        'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
-      ).run(EXPECTED_VERSION, 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');
-    })();
+    db.exec('ALTER TABLE tasks ADD COLUMN estimated_days REAL CHECK (estimated_days IS NULL OR estimated_days > 0)');
+  }
+  if (!taskColumns.has('change_id')) {
+    db.exec('ALTER TABLE tasks ADD COLUMN change_id TEXT REFERENCES changes(id) ON DELETE SET NULL');
+  }
+  if (tables.has('events')) {
+    const eventColumns = columnNames(db, 'events');
+    if (!eventColumns.has('change_id')) db.exec('ALTER TABLE events ADD COLUMN change_id TEXT');
   }
 }
 
+function applyCompatibleUpgrades(db) {
+  db.transaction(() => {
+    applyCompatibleColumns(db);
+    db.exec('CREATE INDEX IF NOT EXISTS tasks_change ON tasks(change_id) WHERE change_id IS NOT NULL');
+    db.exec('CREATE INDEX IF NOT EXISTS events_change ON events(change_id, id)');
+    db.prepare(
+      'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
+    ).run(EXPECTED_VERSION, 'Continuous change units and recoverable runtime state');
+  })();
+}
+
 function ensureSchemaVersion(db) {
   // schema_version is an audit trail — multiple rows across phase upgrades.
   // Guard by checking whether the expected version row exists rather than
@@ -94,6 +116,7 @@ function ensureSchemaVersion(db) {
 function initStateDb(dbPath) {
   const db = openStateDb(dbPath);
   const existing = new Set(tableNames(db));
+  applyCompatibleColumns(db);
   const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
   if (missing.length > 0) {
     applySchema(db);

package/mcp-server/lib/state-ops.cjs

@@ -13,6 +13,7 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 
 const { openStateDb } = require('./state-db.cjs');
+const { isSupportedRuntime } = require('../../adapters/_shared/runtime-assets.cjs');
 
 const STATUS_TRANSITIONS = Object.freeze({
   pending:     new Set(['in_progress', 'blocked', 'expanded']),
@@ -26,6 +27,7 @@ const TASK_FIELDS = Object.freeze([
   'id', 'title', 'type', 'priority', 'complexity', 'estimated_days', 'status',
   'deps', 'files_modified', 'session_id', 'stale', 'complexity_hint',
   'tag', 'trace_to', 'context_file', 'completion_commit', 'parent_id',
+  'change_id',
   'created_at', 'updated_at',
 ]);
 
@@ -33,6 +35,7 @@ const PATCHABLE_FIELDS = Object.freeze([
   'priority', 'complexity', 'estimated_days', 'deps', 'files_modified',
   'session_id', 'stale', 'complexity_hint', 'tag', 'trace_to',
   'context_file', 'completion_commit',
+  'change_id',
 ]);
 
 const SESSION_PATCHABLE = Object.freeze([
@@ -152,10 +155,14 @@ function createTask(db, input) {
     context_file: input.context_file ?? null,
     completion_commit: null,
     parent_id: input.parent_id ?? null,
+    change_id: input.change_id ?? null,
     created_at: ts,
     updated_at: ts,
   };
   return tx(db, () => {
+    if (row.change_id && !db.prepare('SELECT id FROM changes WHERE id = ?').get(row.change_id)) {
+      throw new StateOpsError('CHANGE_NOT_FOUND', `change ${row.change_id} does not exist`);
+    }
     try {
       db.prepare(
         `INSERT INTO tasks (${TASK_FIELDS.join(', ')})
@@ -170,6 +177,7 @@ function createTask(db, input) {
     appendEventInTx(db, {
       type: 'task_created',
       task_id: row.id,
+      change_id: row.change_id,
       payload: { priority: row.priority, type: row.type },
     });
     return readTask(db, row.id);
@@ -192,6 +200,10 @@ function patchTask(db, id, patch = {}) {
         throw new StateOpsError('VALIDATION_ERROR', `field ${key} is not patchable`);
       }
       let value = patch[key];
+      if (key === 'change_id' && value !== null
+        && !db.prepare('SELECT id FROM changes WHERE id = ?').get(value)) {
+        throw new StateOpsError('CHANGE_NOT_FOUND', `change ${value} does not exist`);
+      }
       if (key === 'deps' || key === 'files_modified') {
         if (value !== null && !Array.isArray(value)) {
           throw new StateOpsError('VALIDATION_ERROR', `${key} must be an array`);
@@ -223,6 +235,7 @@ function patchTask(db, id, patch = {}) {
       appendEventInTx(db, {
         type: statusEventType(nextStatus),
         task_id: id,
+        change_id: patch.change_id !== undefined ? patch.change_id : current.change_id,
         payload: { from: current.status, to: nextStatus },
       });
     }
@@ -263,12 +276,16 @@ function appendEventInTx(db, event) {
   if (!event || !event.type) {
     throw new StateOpsError('VALIDATION_ERROR', 'event.type is required');
   }
+  if (event.runtime != null && !isSupportedRuntime(event.runtime)) {
+    throw new StateOpsError('VALIDATION_ERROR', `unsupported runtime: ${event.runtime}`);
+  }
   const result = db.prepare(
-    `INSERT INTO events (type, task_id, session_id, runtime, payload_json)
-     VALUES (?, ?, ?, ?, ?)`,
+    `INSERT INTO events (type, task_id, change_id, session_id, runtime, payload_json)
+     VALUES (?, ?, ?, ?, ?, ?)`,
   ).run(
     event.type,
     event.task_id ?? null,
+    event.change_id ?? null,
     event.session_id ?? null,
     event.runtime ?? null,
     event.payload === undefined ? null : JSON.stringify(event.payload),
@@ -283,7 +300,7 @@ function appendEvent(db, event) {
 
 // Single static SQL using json_each for the optional types IN-list and
 // NULL-pass-through for task_id/session_id. Frozen literal — no concat, no interpolation.
-const SUBSCRIBE_EVENTS_SQL = "SELECT id, ts, type, task_id, session_id, runtime, payload_json FROM events WHERE id > @since_id AND (@types_json IS NULL OR EXISTS (SELECT 1 FROM json_each(@types_json) WHERE value = events.type)) AND (@task_id IS NULL OR task_id = @task_id) AND (@session_id IS NULL OR session_id = @session_id) ORDER BY id ASC LIMIT @maxn";
+const SUBSCRIBE_EVENTS_SQL = "SELECT id, ts, type, task_id, change_id, session_id, runtime, payload_json FROM events WHERE id > @since_id AND (@types_json IS NULL OR EXISTS (SELECT 1 FROM json_each(@types_json) WHERE value = events.type)) AND (@task_id IS NULL OR task_id = @task_id) AND (@session_id IS NULL OR session_id = @session_id) ORDER BY id ASC LIMIT @maxn";
 
 function subscribeEventsSince(db, { since_id = 0, types, task_id, session_id, limit = 100 } = {}) {
   const events = db.prepare(SUBSCRIBE_EVENTS_SQL).all({
@@ -311,6 +328,9 @@ function createSession(db, { sid, task_id, runtime, pid = null, worktree_path, a
   if (!sid || !task_id || !runtime || !worktree_path || !artifact_dir) {
     throw new StateOpsError('VALIDATION_ERROR', 'sid, task_id, runtime, worktree_path, artifact_dir required');
   }
+  if (!isSupportedRuntime(runtime)) {
+    throw new StateOpsError('VALIDATION_ERROR', `unsupported runtime: ${runtime}`);
+  }
   const lease = new Date(Date.now() + lease_seconds * 1000).toISOString();
   return tx(db, () => {
     if (!readTask(db, task_id)) {
@@ -697,6 +717,7 @@ module.exports = {
   deleteTask,
   // events
   appendEvent,
+  appendEventInTx,
   subscribeEventsSince,
   // sessions
   createSession,

package/mcp-server/lib/telemetry.cjs

@@ -12,6 +12,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const { computeCost } = require('./pricing.cjs');
+const { isSupportedRuntime } = require('../../adapters/_shared/runtime-assets.cjs');
 
 function todayStamp() {
   return new Date().toISOString().slice(0, 10);
@@ -33,6 +34,9 @@ function appendTelemetry(db, {
   payload = null,
   rootDir = '.',
 } = {}) {
+  if (runtime != null && !isSupportedRuntime(runtime)) {
+    throw new Error(`unsupported runtime: ${runtime}`);
+  }
   if (!event_type) throw new Error('appendTelemetry: event_type required');
 
   // Auto-derive cost when tokens + runtime known and caller didn't supply one.