ultra-builder-pro-cli 0.24.2 → 0.25.1

package/mcp-server/lib/baseline-workflow.cjs

@@ -19,6 +19,22 @@ const GAP_CATEGORIES = new Set([
   'technical_debt', 'unknown', 'future_change',
 ]);
 const GAP_STATUSES = new Set(['open', 'accepted', 'resolved', 'deferred']);
+const BASELINE_START_FIELDS = new Set([
+  'id', 'project_name', 'project_type', 'stack', 'mode', 'repository_revision',
+  'replace_migrated', 'replace_ready', 'replacement_authorization', 'scope',
+  'provider_refs', 'classification',
+]);
+const BASELINE_REFRESH_FIELDS = new Set([
+  'id', 'project_name', 'project_type', 'stack', 'classification',
+]);
+const BASELINE_RECORD_FIELDS = new Set([
+  'id', 'repository_revision', 'scope', 'spec_refs', 'evidence', 'verification',
+  'unknowns', 'gaps', 'classification', 'provider_refs',
+]);
+const BASELINE_CONVERGE_FIELDS = new Set([
+  'id', 'expected_revision', 'approved_by', 'approval_note',
+  'accept_dirty_worktree', 'accept_known_red',
+]);
 
 class BaselineWorkflowError extends Error {
   constructor(code, message, details) {
@@ -199,6 +215,46 @@ function nonEmpty(value, field) {
   return text;
 }
 
+function optionalText(value, field, { nullable = false, emptyAsNull = false } = {}) {
+  if (value === undefined) return undefined;
+  if (value === null && nullable) return null;
+  if (typeof value !== 'string') {
+    throw new BaselineWorkflowError(
+      'VALIDATION_ERROR',
+      `${field} must be a string${nullable ? ' or null' : ''}`,
+    );
+  }
+  const text = value.trim();
+  return emptyAsNull && !text ? null : text;
+}
+
+function optionalBoolean(input, field) {
+  if (Object.hasOwn(input, field) && typeof input[field] !== 'boolean') {
+    throw new BaselineWorkflowError('VALIDATION_ERROR', `${field} must be a boolean`);
+  }
+}
+
+function optionalBaselineId(value) {
+  if (value === undefined) return undefined;
+  const id = nonEmpty(value, 'id');
+  if (!BASELINE_ID.test(id)) {
+    throw new BaselineWorkflowError('VALIDATION_ERROR', 'baseline id is invalid');
+  }
+  return id;
+}
+
+function assertExactFields(value, allowed, field) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new BaselineWorkflowError('VALIDATION_ERROR', `${field} must be an object`);
+  }
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    throw new BaselineWorkflowError(
+      'VALIDATION_ERROR', `${field}.${unknown[0]} is not allowed`,
+    );
+  }
+}
+
 function normalizeReplacementAuthorization(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new BaselineWorkflowError(
@@ -206,6 +262,13 @@ function normalizeReplacementAuthorization(value) {
       'replacing a ready baseline requires approved_by and reason',
     );
   }
+  const unknown = Object.keys(value).filter((key) => !['approved_by', 'reason'].includes(key));
+  if (unknown.length > 0) {
+    throw new BaselineWorkflowError(
+      'VALIDATION_ERROR',
+      `replacement_authorization.${unknown[0]} is not allowed`,
+    );
+  }
   let approvedBy;
   let reason;
   try {
@@ -245,13 +308,14 @@ function normalizeScope(value, rootDir) {
     throw new BaselineWorkflowError('VALIDATION_ERROR', 'scope must be a non-empty array');
   }
   return [...new Set(scope.map((item, index) => {
+    const relative = nonEmpty(item, `scope[${index}]`);
     const resolved = safeRelativePath(rootDir, item, `scope[${index}]`);
     if (!fs.existsSync(resolved)) {
       throw new BaselineWorkflowError(
-        'BASELINE_SCOPE_MISSING', `baseline scope does not exist: ${String(item).trim()}`,
+        'BASELINE_SCOPE_MISSING', `baseline scope does not exist: ${relative}`,
       );
     }
-    return String(item).trim();
+    return relative;
   }))];
 }
 
@@ -291,6 +355,11 @@ function normalizeSpecRefs(value, rootDir) {
     if (!item || typeof item !== 'object' || Array.isArray(item) || !SPEC_KINDS.has(item.kind)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid spec_refs[${index}]`);
     }
+    assertExactFields(
+      item,
+      new Set(['kind', 'path', 'digest']),
+      `spec_refs[${index}]`,
+    );
     const specPath = nonEmpty(item.path, `spec_refs[${index}].path`);
     const file = safeRelativePath(rootDir, specPath, `spec_refs[${index}].path`);
     if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
@@ -306,6 +375,11 @@ function normalizeEvidence(value, rootDir) {
     if (!item || typeof item !== 'object' || Array.isArray(item) || !EVIDENCE_KINDS.has(item.kind)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid evidence[${index}]`);
     }
+    assertExactFields(
+      item,
+      new Set(['kind', 'ref', 'summary', 'digest']),
+      `evidence[${index}]`,
+    );
     const normalized = {
       kind: item.kind,
       ref: nonEmpty(item.ref, `evidence[${index}].ref`),
@@ -330,6 +404,11 @@ function normalizeVerification(value) {
     if (!item || typeof item !== 'object' || Array.isArray(item) || !VERIFICATION_STATUSES.has(item.status)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid verification[${index}]`);
     }
+    assertExactFields(
+      item,
+      new Set(['name', 'command', 'status', 'evidence', 'rationale']),
+      `verification[${index}]`,
+    );
     const normalized = {
       name: nonEmpty(item.name, `verification[${index}].name`),
       command: nonEmpty(item.command, `verification[${index}].command`),
@@ -347,6 +426,16 @@ function normalizeUnknowns(value) {
     if (!item || typeof item !== 'object' || Array.isArray(item)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid unknowns[${index}]`);
     }
+    assertExactFields(
+      item,
+      new Set(['summary', 'blocking', 'owner']),
+      `unknowns[${index}]`,
+    );
+    if (item.blocking !== undefined && typeof item.blocking !== 'boolean') {
+      throw new BaselineWorkflowError(
+        'VALIDATION_ERROR', `unknowns[${index}].blocking must be a boolean`,
+      );
+    }
     const normalized = {
       summary: nonEmpty(item.summary, `unknowns[${index}].summary`),
       blocking: item.blocking === true,
@@ -363,6 +452,14 @@ function normalizeGaps(value) {
     if (!item || typeof item !== 'object' || Array.isArray(item)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid gaps[${index}]`);
     }
+    assertExactFields(
+      item,
+      new Set([
+        'id', 'category', 'status', 'blocking', 'summary',
+        'evidence_refs', 'owner', 'resolution',
+      ]),
+      `gaps[${index}]`,
+    );
     const id = nonEmpty(item.id, `gaps[${index}].id`);
     if (!BASELINE_ID.test(id) || ids.has(id)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid or duplicate gap id: ${id}`);
@@ -371,7 +468,12 @@ function normalizeGaps(value) {
     if (!GAP_CATEGORIES.has(item.category)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid gap category: ${item.category}`);
     }
-    const status = item.status || 'open';
+    if (item.blocking !== undefined && typeof item.blocking !== 'boolean') {
+      throw new BaselineWorkflowError(
+        'VALIDATION_ERROR', `gaps[${index}].blocking must be a boolean`,
+      );
+    }
+    const status = item.status === undefined ? 'open' : item.status;
     if (!GAP_STATUSES.has(status)) {
       throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid gap status: ${status}`);
     }
@@ -418,9 +520,20 @@ function summarizeGaps(gaps = []) {
 }
 
 function startBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = true } = {}) {
-  const id = input.id || 'project-baseline';
-  if (!BASELINE_ID.test(id)) throw new BaselineWorkflowError('VALIDATION_ERROR', 'baseline id is invalid');
+  assertExactFields(input, BASELINE_START_FIELDS, 'baseline.start');
+  const id = optionalBaselineId(input.id) || 'project-baseline';
   const projectName = nonEmpty(input.project_name, 'project_name');
+  const projectType = optionalText(
+    input.project_type, 'project_type', { nullable: true, emptyAsNull: true },
+  ) ?? null;
+  const stack = optionalText(input.stack, 'stack', { nullable: true, emptyAsNull: true }) ?? null;
+  const repositoryRevision = optionalText(
+    input.repository_revision,
+    'repository_revision',
+    { nullable: true, emptyAsNull: true },
+  ) ?? null;
+  optionalBoolean(input, 'replace_migrated');
+  optionalBoolean(input, 'replace_ready');
   if (!MODES.has(input.mode)) throw new BaselineWorkflowError('VALIDATION_ERROR', `invalid baseline mode: ${input.mode}`);
   if (readBaseline(db, id)) throw new BaselineWorkflowError('DUPLICATE_BASELINE_ID', `baseline ${id} exists`);
   const current = readBaseline(db);
@@ -464,7 +577,7 @@ function startBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = tr
   const providers = providerRefs.normalizeProviderRefs(input.provider_refs, BaselineWorkflowError);
   const classification = normalizeClassification(input.classification);
   const snapshot = gitWorktreeSnapshot(rootDir, scope);
-  if (snapshot.head && input.repository_revision && input.repository_revision !== snapshot.head) {
+  if (snapshot.head && repositoryRevision && repositoryRevision !== snapshot.head) {
     throw new BaselineWorkflowError(
       'BASELINE_REVISION_MISMATCH', 'repository_revision does not match current Git HEAD',
     );
@@ -483,8 +596,8 @@ function startBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = tr
         worktree_files_json, classification_json, provider_refs_json, started_at, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, '.', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
-      id, projectName, input.project_type || null, input.stack || null, input.mode, status,
-      JSON.stringify(scope), snapshot.head || input.repository_revision || null, snapshot.branch,
+      id, projectName, projectType, stack, input.mode, status,
+      JSON.stringify(scope), snapshot.head || repositoryRevision, snapshot.branch,
       snapshot.state, snapshot.digest, JSON.stringify(snapshot.files), JSON.stringify(classification),
       JSON.stringify(providers), ts, ts,
     );
@@ -509,7 +622,9 @@ function startBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = tr
 function refreshInProgressBaseline(db, input = {}, {
   rootDir = process.cwd(), emitEvent = true,
 } = {}) {
-  const current = readBaseline(db, input.id);
+  assertExactFields(input, BASELINE_REFRESH_FIELDS, 'baseline.refresh');
+  const id = optionalBaselineId(input.id);
+  const current = readBaseline(db, id);
   if (!current) {
     throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id || '(current)'} not found`);
   }
@@ -517,8 +632,12 @@ function refreshInProgressBaseline(db, input = {}, {
   const projectName = input.project_name === undefined
     ? current.project_name
     : nonEmpty(input.project_name, 'project_name');
-  const projectType = input.project_type === undefined ? current.project_type : input.project_type;
-  const stack = input.stack === undefined ? current.stack : input.stack;
+  const projectType = input.project_type === undefined
+    ? current.project_type
+    : optionalText(input.project_type, 'project_type', { nullable: true, emptyAsNull: true });
+  const stack = input.stack === undefined
+    ? current.stack
+    : optionalText(input.stack, 'stack', { nullable: true, emptyAsNull: true });
   const classification = input.classification === undefined
     ? current.classification
     : normalizeClassification(input.classification);
@@ -533,7 +652,7 @@ function refreshInProgressBaseline(db, input = {}, {
        worktree_digest = ?, worktree_files_json = ?, classification_json = ?,
        updated_at = ? WHERE id = ?`,
     ).run(
-      projectName, projectType || null, stack || null,
+      projectName, projectType, stack,
       repositoryRevision, snapshot.branch, snapshot.state, snapshot.digest,
       JSON.stringify(snapshot.files), JSON.stringify(classification), ts, current.id,
     );
@@ -543,8 +662,8 @@ function refreshInProgressBaseline(db, input = {}, {
         payload: {
           baseline_id: current.id,
           project_name: projectName,
-          project_type: projectType || null,
-          stack: stack || null,
+          project_type: projectType,
+          stack,
           repository_revision: repositoryRevision,
           repository_branch: snapshot.branch,
           worktree_state: snapshot.state,
@@ -556,7 +675,14 @@ function refreshInProgressBaseline(db, input = {}, {
 }
 
 function recordBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = true } = {}) {
-  const current = readBaseline(db, input.id);
+  assertExactFields(input, BASELINE_RECORD_FIELDS, 'baseline.record');
+  const id = optionalBaselineId(input.id);
+  const suppliedRevision = optionalText(
+    input.repository_revision,
+    'repository_revision',
+    { nullable: true, emptyAsNull: true },
+  );
+  const current = readBaseline(db, id);
   if (!current) throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id} not found`);
   if (['ready', 'superseded'].includes(current.status)) {
     throw new BaselineWorkflowError('BASELINE_NOT_MUTABLE', `baseline ${current.id} is ${current.status}`);
@@ -581,14 +707,14 @@ function recordBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = t
       'Git is initialized but has no commit; create an owner-authorized local checkpoint commit before recording the baseline',
     );
   }
-  if (snapshot.head && input.repository_revision && input.repository_revision !== snapshot.head) {
+  if (snapshot.head && suppliedRevision && suppliedRevision !== snapshot.head) {
     throw new BaselineWorkflowError(
       'BASELINE_REVISION_MISMATCH', 'repository_revision does not match current Git HEAD',
     );
   }
-  const revision = snapshot.head || (input.repository_revision === undefined
+  const revision = snapshot.head || (suppliedRevision === undefined
     ? (current.repository_revision || workspaceRevision({ scope, specs, evidence }, rootDir))
-    : nonEmpty(input.repository_revision, 'repository_revision'));
+    : (suppliedRevision || workspaceRevision({ scope, specs, evidence }, rootDir)));
   const status = current.mode === 'brownfield' ? 'adopting' : 'draft';
   const ts = nowIso();
   return ops.tx(db, () => {
@@ -823,12 +949,22 @@ function convergenceWarnings(db, baseline) {
 }
 
 function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent = true } = {}) {
-  const current = readBaseline(db, input.id);
+  assertExactFields(input, BASELINE_CONVERGE_FIELDS, 'baseline.converge');
+  const normalizedInput = {
+    ...input,
+    id: optionalBaselineId(input.id),
+    expected_revision: optionalText(input.expected_revision, 'expected_revision'),
+    approved_by: optionalText(input.approved_by, 'approved_by'),
+    approval_note: optionalText(input.approval_note, 'approval_note'),
+  };
+  optionalBoolean(input, 'accept_dirty_worktree');
+  optionalBoolean(input, 'accept_known_red');
+  const current = readBaseline(db, normalizedInput.id);
   if (!current) throw new BaselineWorkflowError('BASELINE_NOT_FOUND', `baseline ${input.id} not found`);
   if (!['draft', 'adopting', 'blocked'].includes(current.status)) {
     throw new BaselineWorkflowError('BASELINE_NOT_CONVERGEABLE', `baseline ${current.id} is ${current.status}`);
   }
-  const blockers = convergenceBlockers(db, current, input, rootDir);
+  const blockers = convergenceBlockers(db, current, normalizedInput, rootDir);
   const warnings = convergenceWarnings(db, current);
   const ts = nowIso();
   if (blockers.length > 0) {
@@ -857,9 +993,10 @@ function convergeBaseline(db, input = {}, { rootDir = process.cwd(), emitEvent =
        research_run_id = NULL,
        converged_at = ?, updated_at = ? WHERE id = ?`,
     ).run(
-      String(input.approved_by).trim(), String(input.approval_note).trim(),
-      input.accept_dirty_worktree === true ? 1 : 0,
-      input.accept_known_red === true ? 1 : 0, research?.id || null, ts, ts, current.id,
+      normalizedInput.approved_by, normalizedInput.approval_note,
+      normalizedInput.accept_dirty_worktree === true ? 1 : 0,
+      normalizedInput.accept_known_red === true ? 1 : 0,
+      research?.id || null, ts, ts, current.id,
     );
     if (emitEvent) {
       ops.appendEventInTx(db, {

package/mcp-server/lib/change-workflow.cjs

@@ -1,28 +1,32 @@
 'use strict';
 
 const baselines = require('./baseline-workflow.cjs');
-const compatibility = require('./legacy-change-workflow.cjs');
+const kernel = require('./kernel-change-workflow.cjs');
 
 function createChange(db, input, options = {}) {
-  return compatibility.createKernelChange(db, input, options);
+  return kernel.createChange(db, input, options);
 }
 
 function updateChange(db, id, patch = {}, options = {}) {
-  return compatibility.updateKernelChange(db, id, patch, options);
+  return kernel.updateChange(db, id, patch, options);
+}
+
+function supersedeChange(db, input = {}, options = {}) {
+  return kernel.supersedeChange(db, input, options);
 }
 
 function assertTaskCreationAllowed(db, input = {}, {
   rootDir = process.cwd(),
 } = {}) {
-  const change = input.change_id ? compatibility.readChange(db, input.change_id) : null;
+  const change = input.change_id ? kernel.readChange(db, input.change_id) : null;
   if (input.change_id && !change) {
-    throw new compatibility.ChangeWorkflowError(
+    throw new kernel.ChangeWorkflowError(
       'CHANGE_NOT_FOUND',
       `change ${input.change_id} not found`,
     );
   }
   if (change && !['active', 'blocked'].includes(change.status)) {
-    throw new compatibility.ChangeWorkflowError(
+    throw new kernel.ChangeWorkflowError(
       'CHANGE_NOT_MUTABLE',
       `change ${change.id} is ${change.status}`,
     );
@@ -40,21 +44,22 @@ function assertTaskCreationAllowed(db, input = {}, {
 }
 
 function archiveChange(db, input, options = {}) {
-  return compatibility.archiveKernelChange(db, input, options);
+  return kernel.archiveChange(db, input, options);
 }
 
 module.exports = {
-  ChangeWorkflowError: compatibility.ChangeWorkflowError,
+  ChangeWorkflowError: kernel.ChangeWorkflowError,
   createChange,
-  readChange: compatibility.readChange,
-  listChanges: compatibility.listChanges,
+  readChange: kernel.readChange,
+  listChanges: kernel.listChanges,
   updateChange,
-  recordDelta: compatibility.recordDelta,
-  recordDocumentationReconciliation: compatibility.recordDocumentationReconciliation,
+  supersedeChange,
+  recordDelta: kernel.recordDelta,
+  recordDocumentationReconciliation: kernel.recordDocumentationReconciliation,
   archiveChange,
-  normalizeDocsImpact: compatibility.normalizeDocsImpact,
-  normalizeProviderRefs: compatibility.normalizeProviderRefs,
-  normalizeBaselineBypass: compatibility.normalizeBaselineBypass,
+  normalizeDocsImpact: kernel.normalizeDocsImpact,
+  normalizeProviderRefs: kernel.normalizeProviderRefs,
+  normalizeBaselineBypass: kernel.normalizeBaselineBypass,
   assertTaskCreationAllowed,
-  recoverInterruptedArchives: compatibility.recoverInterruptedArchives,
+  recoverInterruptedArchives: kernel.recoverInterruptedArchives,
 };

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,