ultra-builder-pro-cli 0.24.1 → 0.25.0

package/mcp-server/lib/context-envelope.cjs

@@ -8,7 +8,11 @@ const baselines = require('./baseline-workflow.cjs');
 const canonical = require('./canonical-json.cjs');
 const changes = require('./change-workflow.cjs');
 const decisions = require('./decision-records.cjs');
-const { writeManagedJson } = require('./managed-file-write.cjs');
+const {
+  restoreManagedFile,
+  snapshotManagedFile,
+  writeManagedJson,
+} = require('./managed-file-write.cjs');
 const ops = require('./state-ops.cjs');
 const { readStableProjectFile } = require('./safe-project-file.cjs');
 const checkpoints = require('./stage-checkpoints.cjs');
@@ -70,8 +74,33 @@ function selectedTask(db, taskId) {
 function resolvedScope(db, input = {}) {
   const requested = input.scope || {};
   const task = selectedTask(db, requested.task_id);
+  if (requested.task_id && !task) {
+    throw new ContextEnvelopeError(
+      'CONTEXT_SCOPE_NOT_FOUND',
+      `Context task scope does not exist: ${requested.task_id}`,
+      { scope_type: 'task', scope_id: requested.task_id },
+    );
+  }
   const changeId = requested.change_id || task?.change_id || null;
   const change = selectedChange(db, changeId);
+  if (requested.change_id && !change) {
+    throw new ContextEnvelopeError(
+      'CONTEXT_SCOPE_NOT_FOUND',
+      `Context Change scope does not exist: ${requested.change_id}`,
+      { scope_type: 'change', scope_id: requested.change_id },
+    );
+  }
+  if (task && requested.change_id && task.change_id !== requested.change_id) {
+    throw new ContextEnvelopeError(
+      'CONTEXT_SCOPE_MISMATCH',
+      `Context task ${task.id} belongs to Change ${task.change_id || '(none)'}, not ${requested.change_id}`,
+      {
+        task_id: task.id,
+        task_change_id: task.change_id || null,
+        requested_change_id: requested.change_id,
+      },
+    );
+  }
   const baseline = baselines.readBaseline(db);
   if (task) return { type: 'task', id: task.id, baseline, change, task };
   if (change) return { type: 'change', id: change.id, baseline, change, task: null };
@@ -254,6 +283,31 @@ function authorityPayload(db, input, options) {
       item.diagnostics.filter((diagnostic) => diagnostic.severity === 'hard_conflict')
     )),
   };
+  if (scope.task) {
+    diagnostics.warnings.push(...ops.taskContractBlockers(scope.task).map((code) => ({
+      code,
+      severity: 'warning',
+      message: 'Task semantics are incomplete; the active Skill and model own the decision to proceed.',
+    })));
+  }
+  if (scope.change) {
+    const advisory = [
+      [!String(scope.change.contract?.outcome || '').trim(), 'CHANGE_OUTCOME_UNRESOLVED'],
+      [!Array.isArray(scope.change.contract?.acceptance)
+        || scope.change.contract.acceptance.length === 0, 'CHANGE_ACCEPTANCE_UNRESOLVED'],
+      [!scope.change.contract?.recovery, 'CHANGE_RECOVERY_UNRESOLVED'],
+      [!String(scope.change.classification?.rationale || '').trim(), 'CHANGE_CLASSIFICATION_UNRESOLVED'],
+      [scope.change.research_disposition?.status === 'unresolved',
+        'CHANGE_RESEARCH_DISPOSITION_UNRESOLVED'],
+    ];
+    diagnostics.warnings.push(...advisory
+      .filter(([missing]) => missing)
+      .map(([, code]) => ({
+        code,
+        severity: 'warning',
+        message: 'Change semantics remain mutable; the active Skill and model own completion.',
+      })));
+  }
   for (const code of baselineHealth.blockers || []) {
     diagnostics.needs_attention.push({ code, severity: 'needs_attention' });
   }
@@ -435,58 +489,77 @@ function persistEnvelope(db, input = {}, options = {}) {
   const scope = resolvedScope(db, input);
   const id = `context-${full.digest.slice(0, 24)}`;
   const artifactPath = contextArtifactPath(scope, id);
-  const published = writeManagedJson(options.rootDir || process.cwd(), artifactPath, full);
-  ops.tx(db, () => {
-    db.prepare(
-      `INSERT INTO context_envelopes
-       (id, stage, scope_type, scope_id, digest, file_digest, payload_json, artifact_path)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
-    ).run(
-      id,
-      input.stage || 'project',
-      scope.type,
-      scope.id,
-      full.digest,
-      published.digest,
-      JSON.stringify(full.envelope),
-      artifactPath,
-    );
-    if (!artifactPath.startsWith('.ultra/.runtime/')) {
-      artifactRegistry.recordArtifactInTx(db, {
-        id: `artifact-${id}`,
-        owner_type: scope.change ? 'change' : (scope.baseline ? 'baseline' : 'project'),
-        owner_id: scope.change?.id || scope.baseline?.id || 'project',
-        kind: 'context_envelope',
-        path: artifactPath,
-        content_digest: published.digest,
-        source_refs: [
-          ...(scope.change
-            ? [{ type: 'change', id: scope.change.id, relation: 'compiled_from' }]
-            : []),
-          ...(scope.task
-            ? [{ type: 'task', id: scope.task.id, relation: 'compiled_from_task_contract' }]
-            : []),
-          ...(scope.baseline && !scope.change
-            ? [{ type: 'baseline', id: scope.baseline.id, relation: 'compiled_from' }]
-            : []),
-        ],
-        consumer_refs: [{
-          type: 'external',
-          id: 'ultra-context-consumer',
-          relation: 'consumed_by',
-        }],
-        provenance: {
-          writer: 'context-envelope',
-          envelope_digest: full.digest,
-          stage: input.stage || 'project',
-        },
-        metadata: {
-          envelope_id: id,
-          semantic_digest: full.digest,
+  const rootDir = options.rootDir || process.cwd();
+  const snapshot = snapshotManagedFile(rootDir, artifactPath);
+  const published = writeManagedJson(rootDir, artifactPath, full);
+  try {
+    ops.tx(db, () => {
+      db.prepare(
+        `INSERT INTO context_envelopes
+         (id, stage, scope_type, scope_id, digest, file_digest, payload_json, artifact_path)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      ).run(
+        id,
+        input.stage || 'project',
+        scope.type,
+        scope.id,
+        full.digest,
+        published.digest,
+        JSON.stringify(full.envelope),
+        artifactPath,
+      );
+      if (!artifactPath.startsWith('.ultra/.runtime/')) {
+        artifactRegistry.recordArtifactInTx(db, {
+          id: `artifact-${id}`,
+          owner_type: scope.change ? 'change' : (scope.baseline ? 'baseline' : 'project'),
+          owner_id: scope.change?.id || scope.baseline?.id || 'project',
+          kind: 'context_envelope',
+          path: artifactPath,
+          content_digest: published.digest,
+          source_refs: [
+            ...(scope.change
+              ? [{ type: 'change', id: scope.change.id, relation: 'compiled_from' }]
+              : []),
+            ...(scope.task
+              ? [{ type: 'task', id: scope.task.id, relation: 'compiled_from_task_contract' }]
+              : []),
+            ...(scope.baseline && !scope.change
+              ? [{ type: 'baseline', id: scope.baseline.id, relation: 'compiled_from' }]
+              : []),
+          ],
+          consumer_refs: [{
+            type: 'external',
+            id: 'ultra-context-consumer',
+            relation: 'consumed_by',
+          }],
+          provenance: {
+            writer: 'context-envelope',
+            envelope_digest: full.digest,
+            stage: input.stage || 'project',
+          },
+          metadata: {
+            envelope_id: id,
+            semantic_digest: full.digest,
+          },
+        }, { rootDir });
+      }
+    });
+  } catch (error) {
+    try {
+      restoreManagedFile(rootDir, snapshot);
+    } catch (rollbackError) {
+      throw new ContextEnvelopeError(
+        'STATE_CORRUPT',
+        'Context Envelope publication failed and its managed file could not be restored',
+        {
+          cause: error.code || error.message,
+          rollback: rollbackError.code || rollbackError.message,
+          path: artifactPath,
         },
-      }, { rootDir: options.rootDir || process.cwd() });
+      );
     }
-  });
+    throw error;
+  }
   return {
     id,
     digest: full.digest,

package/mcp-server/lib/decision-records.cjs

@@ -3,9 +3,18 @@
 const canonical = require('./canonical-json.cjs');
 const artifactRegistry = require('./artifact-registry.cjs');
 const ops = require('./state-ops.cjs');
-const { writeManagedJson } = require('./managed-file-write.cjs');
+const {
+  restoreManagedFile,
+  snapshotManagedFile,
+  writeManagedJson,
+} = require('./managed-file-write.cjs');
 const { readStableProjectFile } = require('./safe-project-file.cjs');
 
+const DECISION_FIELDS = new Set([
+  'id', 'scope', 'question', 'recommendation', 'selection', 'effects',
+  'non_goals', 'owner', 'source', 'provenance', 'applied_refs', 'supersedes_id',
+]);
+
 class DecisionRecordError extends Error {
   constructor(code, message, details) {
     super(message);
@@ -21,11 +30,55 @@ function requiredText(value, field) {
   return normalized;
 }
 
+function assertExactFields(value, allowed, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new DecisionRecordError('VALIDATION_ERROR', `${field} must be an object`);
+  }
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new DecisionRecordError(
+      'VALIDATION_ERROR', `${field}.${unknown[0]} is not allowed`,
+    );
+  }
+}
+
+function assertJsonValue(value, field, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return;
+    throw new DecisionRecordError('VALIDATION_ERROR', `${field} must contain valid JSON values`);
+  }
+  if (typeof value !== 'object') {
+    throw new DecisionRecordError('VALIDATION_ERROR', `${field} must contain valid JSON values`);
+  }
+  if (seen.has(value)) {
+    throw new DecisionRecordError('VALIDATION_ERROR', `${field} must not contain circular references`);
+  }
+  if (!Array.isArray(value)) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new DecisionRecordError(
+        'VALIDATION_ERROR', `${field} must contain only JSON objects`,
+      );
+    }
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonValue(item, `${field}[${index}]`, seen));
+  } else {
+    Object.entries(value).forEach(([key, item]) => (
+      assertJsonValue(item, `${field}.${key}`, seen)
+    ));
+  }
+  seen.delete(value);
+}
+
 function plainObject(value, field) {
   if (value === undefined) return {};
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new DecisionRecordError('VALIDATION_ERROR', `${field} must be an object`);
   }
+  assertJsonValue(value, field);
   return JSON.parse(JSON.stringify(value));
 }
 
@@ -38,6 +91,7 @@ function stringArray(value, field) {
 }
 
 function normalizeScope(scope = {}) {
+  assertExactFields(scope, new Set(['baseline_id', 'change_id']), 'scope');
   const baseline = typeof scope.baseline_id === 'string' ? scope.baseline_id.trim() : '';
   const change = typeof scope.change_id === 'string' ? scope.change_id.trim() : '';
   if (Boolean(baseline) === Boolean(change)) {
@@ -186,10 +240,19 @@ function normalizeAppliedRefs(value) {
     if (!item || typeof item !== 'object' || Array.isArray(item)) {
       throw new DecisionRecordError('VALIDATION_ERROR', `applied_refs[${index}] must be an object`);
     }
+    assertExactFields(
+      item,
+      new Set(['ref', 'field', 'digest']),
+      `applied_refs[${index}]`,
+    );
     return {
       ref: requiredText(item.ref, `applied_refs[${index}].ref`),
-      ...(item.field ? { field: requiredText(item.field, `applied_refs[${index}].field`) } : {}),
-      ...(item.digest ? { digest: requiredText(item.digest, `applied_refs[${index}].digest`) } : {}),
+      ...(item.field !== undefined
+        ? { field: requiredText(item.field, `applied_refs[${index}].field`) }
+        : {}),
+      ...(item.digest !== undefined
+        ? { digest: requiredText(item.digest, `applied_refs[${index}].digest`) }
+        : {}),
     };
   });
 }
@@ -201,7 +264,11 @@ function artifactPath(scope, id) {
 }
 
 function acceptDecision(db, input = {}, { rootDir = process.cwd() } = {}) {
+  assertExactFields(input, DECISION_FIELDS, 'decision');
   const scope = normalizeScope(input.scope);
+  const supersedesId = input.supersedes_id === undefined || input.supersedes_id === null
+    ? null
+    : requiredText(input.supersedes_id, 'supersedes_id');
   const value = {
     schema_version: '1.0',
     id: requiredText(input.id, 'id'),
@@ -216,9 +283,7 @@ function acceptDecision(db, input = {}, { rootDir = process.cwd() } = {}) {
     provenance: plainObject(input.provenance, 'provenance'),
     applied_refs: normalizeAppliedRefs(input.applied_refs),
     status: 'accepted',
-    supersedes_id: input.supersedes_id
-      ? requiredText(input.supersedes_id, 'supersedes_id')
-      : null,
+    supersedes_id: supersedesId,
   };
   const digest = canonical.digest(value);
   const document = { ...value, digest };
@@ -247,83 +312,104 @@ function acceptDecision(db, input = {}, { rootDir = process.cwd() } = {}) {
         'a decision can only supersede another decision in the same scope',
       );
     }
+    if (prior.status !== 'accepted') {
+      throw new DecisionRecordError(
+        'DECISION_NOT_SUPERSEDEABLE',
+        `decision ${value.supersedes_id} is ${prior.status}`,
+      );
+    }
   }
+  artifactRegistry.assertArtifactOwner(db, scope.type, scope.id);
+  const snapshot = snapshotManagedFile(rootDir, relative);
   const published = writeManagedJson(rootDir, relative, document);
-  return ops.tx(db, () => {
-    if (value.supersedes_id) {
+  try {
+    return ops.tx(db, () => {
+      if (value.supersedes_id) {
+        db.prepare(
+          `UPDATE decision_records SET status = 'superseded',
+           updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+           WHERE id = ? AND status = 'accepted'`,
+        ).run(value.supersedes_id);
+      }
       db.prepare(
-        `UPDATE decision_records SET status = 'superseded',
-         updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
-         WHERE id = ? AND status = 'accepted'`,
-      ).run(value.supersedes_id);
-    }
-    db.prepare(
-      `INSERT INTO decision_records
-       (id, scope_type, scope_id, question, recommendation, selection,
-        effects_json, non_goals_json, owner, source, provenance_json,
-        applied_refs_json, status, digest, artifact_path, supersedes_id)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'accepted', ?, ?, ?)`,
-    ).run(
-      value.id,
-      scope.type,
-      scope.id,
-      value.question,
-      value.recommendation,
-      value.selection,
-      JSON.stringify(value.effects),
-      JSON.stringify(value.non_goals),
-      value.owner,
-      value.source,
-      JSON.stringify(value.provenance),
-      JSON.stringify(value.applied_refs),
-      digest,
-      relative,
-      value.supersedes_id,
-    );
-    artifactRegistry.recordArtifactInTx(db, {
-      id: `artifact-decision-${value.id}`,
-      owner_type: scope.type,
-      owner_id: scope.id,
-      change_id: scope.type === 'change' ? scope.id : null,
-      kind: 'decision_record',
-      path: relative,
-      content_digest: published.digest,
-      source_refs: [{
-        type: scope.type,
-        id: scope.id,
-        relation: 'decided_for',
-      }],
-      consumer_refs: [{
-        type: 'external',
-        id: 'ultra-context-consumer',
-        relation: 'consumed_by',
-      }],
-      provenance: {
-        writer: 'decision-records',
-        decision_digest: digest,
-        owner: value.owner,
-        source: value.source,
-      },
-      metadata: {
-        decision_id: value.id,
-        status: value.status,
-        supersedes_id: value.supersedes_id,
-      },
-    }, { rootDir });
-    ops.appendEventInTx(db, {
-      type: 'decision_recorded',
-      change_id: scope.type === 'change' ? scope.id : null,
-      payload: {
-        decision_id: value.id,
-        scope_type: scope.type,
-        scope_id: scope.id,
+        `INSERT INTO decision_records
+         (id, scope_type, scope_id, question, recommendation, selection,
+          effects_json, non_goals_json, owner, source, provenance_json,
+          applied_refs_json, status, digest, artifact_path, supersedes_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'accepted', ?, ?, ?)`,
+      ).run(
+        value.id,
+        scope.type,
+        scope.id,
+        value.question,
+        value.recommendation,
+        value.selection,
+        JSON.stringify(value.effects),
+        JSON.stringify(value.non_goals),
+        value.owner,
+        value.source,
+        JSON.stringify(value.provenance),
+        JSON.stringify(value.applied_refs),
         digest,
-        artifact_path: relative,
-        supersedes_id: value.supersedes_id,
-      },
+        relative,
+        value.supersedes_id,
+      );
+      artifactRegistry.recordArtifactInTx(db, {
+        id: `artifact-decision-${value.id}`,
+        owner_type: scope.type,
+        owner_id: scope.id,
+        change_id: scope.type === 'change' ? scope.id : null,
+        kind: 'decision_record',
+        path: relative,
+        content_digest: published.digest,
+        source_refs: [{
+          type: scope.type,
+          id: scope.id,
+          relation: 'decided_for',
+        }],
+        consumer_refs: [{
+          type: 'external',
+          id: 'ultra-context-consumer',
+          relation: 'consumed_by',
+        }],
+        provenance: {
+          writer: 'decision-records',
+          decision_digest: digest,
+          owner: value.owner,
+          source: value.source,
+        },
+        metadata: {
+          decision_id: value.id,
+          status: value.status,
+          supersedes_id: value.supersedes_id,
+        },
+      }, { rootDir });
+      ops.appendEventInTx(db, {
+        type: 'decision_recorded',
+        change_id: scope.type === 'change' ? scope.id : null,
+        payload: {
+          decision_id: value.id,
+          scope_type: scope.type,
+          scope_id: scope.id,
+          digest,
+          artifact_path: relative,
+          supersedes_id: value.supersedes_id,
+        },
+      });
+      return readDecision(db, value.id);
     });
-    return readDecision(db, value.id);
-  });
+  } catch (error) {
+    try {
+      restoreManagedFile(rootDir, snapshot);
+    } catch (rollbackError) {
+      throw new DecisionRecordError(
+        'RECORD_FILE_ROLLBACK_REQUIRED',
+        `decision database mutation failed and managed file recovery also failed: ${relative}`,
+        { cause: error.message, rollback_error: rollbackError.message },
+      );
+    }
+    throw error;
+  }
 }
 
 module.exports = {