ultra-builder-pro-cli 0.23.0 → 0.24.0

package/mcp-server/lib/stage-checkpoints.cjs

@@ -0,0 +1,309 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+const ops = require('./state-ops.cjs');
+const canonical = require('./canonical-json.cjs');
+
+const STAGES = new Set(['init', 'research', 'change', 'plan', 'dev', 'test', 'review', 'deliver']);
+const SCOPE_KEYS = Object.freeze([
+  ['task_id', 'task'],
+  ['change_id', 'change'],
+  ['baseline_id', 'baseline'],
+  ['project_id', 'project'],
+]);
+
+class StageCheckpointError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'StageCheckpointError';
+    this.code = code;
+    if (details) this.details = details;
+  }
+}
+
+function parseJson(value, fallback) {
+  try { return value == null ? fallback : JSON.parse(value); }
+  catch { return fallback; }
+}
+
+function normalizeScope(scope = {}) {
+  const matches = SCOPE_KEYS.filter(([key]) => (
+    typeof scope[key] === 'string' && scope[key].trim()
+  ));
+  if (matches.length !== 1) {
+    throw new StageCheckpointError(
+      'VALIDATION_ERROR',
+      'checkpoint scope must contain exactly one of project_id, baseline_id, change_id, or task_id',
+    );
+  }
+  const [key, type] = matches[0];
+  return { type, id: scope[key].trim() };
+}
+
+function validateStage(stage) {
+  if (!STAGES.has(stage)) {
+    throw new StageCheckpointError('VALIDATION_ERROR', `unsupported checkpoint stage: ${stage}`);
+  }
+}
+
+function normalizeDiagnostics(value) {
+  if (!Array.isArray(value)) {
+    throw new StageCheckpointError('VALIDATION_ERROR', 'diagnostics must be an array');
+  }
+  return value.map((item, index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      throw new StageCheckpointError('VALIDATION_ERROR', `diagnostics[${index}] must be an object`);
+    }
+    const code = String(item.code || '').trim();
+    if (!code) {
+      throw new StageCheckpointError('VALIDATION_ERROR', `diagnostics[${index}].code is required`);
+    }
+    const severity = item.severity || 'needs_attention';
+    if (!['warning', 'needs_attention', 'hard_conflict'].includes(severity)) {
+      throw new StageCheckpointError(
+        'VALIDATION_ERROR',
+        `diagnostics[${index}].severity is invalid`,
+      );
+    }
+    return {
+      code,
+      severity,
+      ...(item.message ? { message: String(item.message) } : {}),
+      ...(item.details === undefined ? {} : { details: item.details }),
+    };
+  });
+}
+
+function checkpointDigest(value) {
+  return canonical.digest({
+    stage: value.stage,
+    scope_type: value.scope_type,
+    scope_id: value.scope_id,
+    revision: value.revision,
+    payload: value.payload,
+    evidence: value.evidence,
+    diagnostics: value.diagnostics,
+    context_envelope_id: value.context_envelope_id || null,
+    supersedes_id: value.supersedes_id || null,
+  });
+}
+
+function rowToCheckpoint(row) {
+  if (!row) return null;
+  const checkpoint = {
+    id: row.id,
+    stage: row.stage,
+    scope: { [`${row.scope_type}_id`]: row.scope_id },
+    scope_type: row.scope_type,
+    scope_id: row.scope_id,
+    revision: row.revision,
+    status: row.status,
+    payload: parseJson(row.payload_json, {}),
+    evidence: parseJson(row.evidence_json, []),
+    diagnostics: parseJson(row.diagnostics_json, []),
+    context_envelope_id: row.context_envelope_id,
+    digest: row.digest,
+    supersedes_id: row.supersedes_id,
+    idempotency_key: row.idempotency_key,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    accepted_at: row.accepted_at,
+  };
+  const actual = checkpointDigest(checkpoint);
+  if (actual !== checkpoint.digest) {
+    throw new StageCheckpointError(
+      'CHECKPOINT_DIGEST_MISMATCH',
+      `Stage Checkpoint database authority is corrupt: ${checkpoint.id}`,
+      { expected: checkpoint.digest, actual },
+    );
+  }
+  return checkpoint;
+}
+
+function readCheckpoint(db, id) {
+  return rowToCheckpoint(db.prepare('SELECT * FROM stage_checkpoints WHERE id = ?').get(id));
+}
+
+function listCheckpoints(db, { stage, scope, status, limit = 100 } = {}) {
+  const clauses = [];
+  const params = [];
+  if (stage) { validateStage(stage); clauses.push('stage = ?'); params.push(stage); }
+  if (scope) {
+    const normalized = normalizeScope(scope);
+    clauses.push('scope_type = ?', 'scope_id = ?');
+    params.push(normalized.type, normalized.id);
+  }
+  if (status) { clauses.push('status = ?'); params.push(status); }
+  const bounded = Math.min(Math.max(Number(limit) || 100, 1), 500);
+  return db.prepare(
+    `SELECT * FROM stage_checkpoints
+     ${clauses.length ? `WHERE ${clauses.join(' AND ')}` : ''}
+     ORDER BY stage, scope_type, scope_id, revision DESC
+     LIMIT ?`,
+  ).all(...params, bounded).map(rowToCheckpoint);
+}
+
+function existingByIdempotency(db, idempotencyKey) {
+  if (!idempotencyKey) return null;
+  return rowToCheckpoint(
+    db.prepare('SELECT * FROM stage_checkpoints WHERE idempotency_key = ?').get(idempotencyKey),
+  );
+}
+
+function saveDraft(db, input = {}) {
+  validateStage(input.stage);
+  const scope = normalizeScope(input.scope);
+  const idempotencyKey = String(input.idempotency_key || '').trim();
+  if (!idempotencyKey) {
+    throw new StageCheckpointError('VALIDATION_ERROR', 'idempotency_key is required');
+  }
+  const existingRetry = existingByIdempotency(db, idempotencyKey);
+  if (existingRetry) return existingRetry;
+  const payload = input.payload && typeof input.payload === 'object' && !Array.isArray(input.payload)
+    ? input.payload : {};
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+  const diagnostics = normalizeDiagnostics(input.diagnostics || []);
+  return ops.tx(db, () => {
+    const draft = db.prepare(
+      `SELECT * FROM stage_checkpoints
+       WHERE stage = ? AND scope_type = ? AND scope_id = ? AND status = 'draft'
+       ORDER BY revision DESC LIMIT 1`,
+    ).get(input.stage, scope.type, scope.id);
+    if (draft) {
+      const value = {
+        stage: input.stage,
+        scope_type: scope.type,
+        scope_id: scope.id,
+        revision: draft.revision,
+        payload,
+        evidence,
+        diagnostics,
+        context_envelope_id: input.context_envelope_id || null,
+        supersedes_id: draft.supersedes_id,
+      };
+      const digest = checkpointDigest(value);
+      db.prepare(
+        `UPDATE stage_checkpoints
+         SET payload_json = ?, evidence_json = ?, diagnostics_json = ?,
+             context_envelope_id = ?, digest = ?, idempotency_key = ?,
+             updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         WHERE id = ?`,
+      ).run(
+        JSON.stringify(payload),
+        JSON.stringify(evidence),
+        JSON.stringify(diagnostics),
+        input.context_envelope_id || null,
+        digest,
+        idempotencyKey,
+        draft.id,
+      );
+      return readCheckpoint(db, draft.id);
+    }
+    const accepted = db.prepare(
+      `SELECT id, revision FROM stage_checkpoints
+       WHERE stage = ? AND scope_type = ? AND scope_id = ? AND status = 'accepted'
+       ORDER BY revision DESC LIMIT 1`,
+    ).get(input.stage, scope.type, scope.id);
+    const revision = (accepted?.revision || 0) + 1;
+    const id = `checkpoint-${crypto.randomUUID()}`;
+    const value = {
+      stage: input.stage,
+      scope_type: scope.type,
+      scope_id: scope.id,
+      revision,
+      payload,
+      evidence,
+      diagnostics,
+      context_envelope_id: input.context_envelope_id || null,
+      supersedes_id: accepted?.id || null,
+    };
+    db.prepare(
+      `INSERT INTO stage_checkpoints
+       (id, stage, scope_type, scope_id, revision, payload_json, evidence_json,
+        diagnostics_json, context_envelope_id, digest, supersedes_id, idempotency_key)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id,
+      input.stage,
+      scope.type,
+      scope.id,
+      revision,
+      JSON.stringify(payload),
+      JSON.stringify(evidence),
+      JSON.stringify(diagnostics),
+      input.context_envelope_id || null,
+      checkpointDigest(value),
+      accepted?.id || null,
+      idempotencyKey,
+    );
+    return readCheckpoint(db, id);
+  });
+}
+
+function acceptDraft(db, input = {}) {
+  const idempotencyKey = String(input.idempotency_key || '').trim();
+  if (!idempotencyKey) {
+    throw new StageCheckpointError('VALIDATION_ERROR', 'idempotency_key is required');
+  }
+  return ops.tx(db, () => {
+    const row = db.prepare('SELECT * FROM stage_checkpoints WHERE id = ?').get(input.id);
+    if (!row) throw new StageCheckpointError('CHECKPOINT_NOT_FOUND', `checkpoint not found: ${input.id}`);
+    if (row.status === 'accepted') return rowToCheckpoint(row);
+    if (row.status !== 'draft') {
+      throw new StageCheckpointError(
+        'CHECKPOINT_NOT_MUTABLE',
+        `checkpoint ${input.id} is ${row.status}`,
+      );
+    }
+    if (row.supersedes_id) {
+      db.prepare(
+        `UPDATE stage_checkpoints SET status = 'superseded',
+         updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+         WHERE id = ? AND status = 'accepted'`,
+      ).run(row.supersedes_id);
+    }
+    db.prepare(
+      `UPDATE stage_checkpoints
+       SET status = 'accepted', accepted_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+           updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+       WHERE id = ?`,
+    ).run(row.id);
+    const accepted = readCheckpoint(db, row.id);
+    ops.appendEventInTx(db, {
+      type: 'ultra_checkpoint_accepted',
+      change_id: accepted.scope_type === 'change' ? accepted.scope_id : null,
+      task_id: accepted.scope_type === 'task' ? accepted.scope_id : null,
+      payload: {
+        checkpoint_id: accepted.id,
+        stage: accepted.stage,
+        revision: accepted.revision,
+        digest: accepted.digest,
+      },
+    });
+    return accepted;
+  });
+}
+
+function currentCheckpoint(db, stage, scope, { includeDraft = true } = {}) {
+  validateStage(stage);
+  const normalized = normalizeScope(scope);
+  const statuses = includeDraft ? "('draft','accepted')" : "('accepted')";
+  return rowToCheckpoint(db.prepare(
+    `SELECT * FROM stage_checkpoints
+     WHERE stage = ? AND scope_type = ? AND scope_id = ? AND status IN ${statuses}
+     ORDER BY CASE status WHEN 'draft' THEN 0 ELSE 1 END, revision DESC LIMIT 1`,
+  ).get(stage, normalized.type, normalized.id));
+}
+
+module.exports = {
+  StageCheckpointError,
+  STAGES,
+  normalizeScope,
+  readCheckpoint,
+  listCheckpoints,
+  saveDraft,
+  acceptDraft,
+  currentCheckpoint,
+  checkpointDigest,
+};

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 = '20.0';
+const EXPECTED_VERSION = '22.0';
 const KIMI_SCHEMA_VERSION = '9.1';
 const CONTEXT_SCHEMA_VERSION = '10.0';
 const BASELINE_SCHEMA_VERSION = '11.0';
@@ -22,6 +22,8 @@ const GIT_AUTHORITY_SCHEMA_VERSION = '17.0';
 const ADAPTIVE_SCHEMA_VERSION = '18.0';
 const DECISION_COMPLETION_SCHEMA_VERSION = '19.0';
 const ARTIFACT_REGISTRY_SCHEMA_VERSION = '20.0';
+const KERNEL_SCHEMA_VERSION = '21.0';
+const CHECKPOINT_NATIVE_SCHEMA_VERSION = '22.0';
 
 const MIGRATED_GAPS = Object.freeze([{
   id: 'legacy-rebaseline-required',
@@ -56,6 +58,10 @@ const REQUIRED_TABLES = Object.freeze([
   'workflow_steps',
   'decision_threads',
   'decision_items',
+  'stage_checkpoints',
+  'decision_records',
+  'context_envelopes',
+  'worker_packets',
 ]);
 
 class ActiveSessionLeaseConflictError extends Error {
@@ -173,6 +179,7 @@ function applyBaselineUpgrade(db, { legacyState = false } = {}) {
       classification_json TEXT NOT NULL DEFAULT '{}',
       provider_refs_json  TEXT NOT NULL DEFAULT '{}',
       research_run_id     TEXT,
+      research_checkpoint_id TEXT,
       approved_by         TEXT,
       approval_note       TEXT,
       started_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -226,6 +233,62 @@ function applyBaselineColumns(db) {
     db, 'baselines', columns, 'classification_json', "TEXT NOT NULL DEFAULT '{}'",
   ) || changed;
   changed = addColumnIfMissing(db, 'baselines', columns, 'research_run_id', 'TEXT') || changed;
+  changed = addColumnIfMissing(
+    db,
+    'baselines',
+    columns,
+    'research_checkpoint_id',
+    'TEXT',
+  ) || changed;
+  if (columns.has('research_checkpoint_id')
+      && tableNames(db).includes('stage_checkpoints')) {
+    const result = db.prepare(
+      `UPDATE baselines
+       SET research_checkpoint_id = research_run_id
+       WHERE research_checkpoint_id IS NULL
+         AND research_run_id IS NOT NULL
+         AND EXISTS (
+           SELECT 1 FROM stage_checkpoints
+           WHERE stage_checkpoints.id = baselines.research_run_id
+             AND stage_checkpoints.stage = 'research'
+         )`,
+    ).run();
+    changed = result.changes > 0 || changed;
+  }
+  return changed;
+}
+
+function applyKernelIntegrityColumns(db) {
+  const tables = new Set(tableNames(db));
+  let changed = false;
+  if (tables.has('context_envelopes')) {
+    const columns = columnNames(db, 'context_envelopes');
+    changed = addColumnIfMissing(
+      db,
+      'context_envelopes',
+      columns,
+      'file_digest',
+      'TEXT',
+    ) || changed;
+  }
+  if (tables.has('worker_packets')) {
+    const columns = columnNames(db, 'worker_packets');
+    for (const [name, definition] of [
+      ['file_digest', 'TEXT'],
+      ['status', "TEXT NOT NULL DEFAULT 'assigned' CHECK (status IN ('pending', 'assigned', 'abandoned'))"],
+      ['assigned_at', 'TEXT'],
+      ['abandoned_at', 'TEXT'],
+      ['abandon_reason', 'TEXT'],
+    ]) {
+      changed = addColumnIfMissing(
+        db,
+        'worker_packets',
+        columns,
+        name,
+        definition,
+      ) || changed;
+    }
+  }
   return changed;
 }
 
@@ -422,7 +485,8 @@ function migrateAdaptiveWorkflowRuns(db, fromVersion = latestSchemaVersion(db))
   ).get();
   if ([
     ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
-    ARTIFACT_REGISTRY_SCHEMA_VERSION,
+    ARTIFACT_REGISTRY_SCHEMA_VERSION, KERNEL_SCHEMA_VERSION,
+    CHECKPOINT_NATIVE_SCHEMA_VERSION,
   ].includes(fromVersion) || existing) {
     return false;
   }
@@ -538,11 +602,11 @@ function migrateAdaptiveWorkflowRuns(db, fromVersion = latestSchemaVersion(db))
   return true;
 }
 
-function tableSupportsKimi(db, table) {
+function tableSupportsRuntime(db, table, runtime) {
   const row = db.prepare(
     "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
   ).get(table);
-  return typeof row?.sql === 'string' && row.sql.includes("'kimi'");
+  return typeof row?.sql === 'string' && row.sql.includes(`'${runtime}'`);
 }
 
 function baselineSupportsUnbornGit(db) {
@@ -676,6 +740,7 @@ function upgradeBaselineWorktreeConstraint(db, fromVersion = latestSchemaVersion
           classification_json TEXT NOT NULL DEFAULT '{}',
           provider_refs_json  TEXT NOT NULL DEFAULT '{}',
           research_run_id     TEXT,
+          research_checkpoint_id TEXT,
           approved_by         TEXT,
           approval_note       TEXT,
           started_at          TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
@@ -687,7 +752,8 @@ function upgradeBaselineWorktreeConstraint(db, fromVersion = latestSchemaVersion
           repository_revision, repository_branch, worktree_state, worktree_digest,
           worktree_files_json, worktree_accepted, known_red_accepted, spec_refs_json,
           evidence_json, verification_json, unknowns_json, gaps_json, classification_json,
-          provider_refs_json, research_run_id, approved_by, approval_note, started_at,
+          provider_refs_json, research_run_id, research_checkpoint_id,
+          approved_by, approval_note, started_at,
           updated_at, converged_at
         )
         SELECT
@@ -695,7 +761,8 @@ function upgradeBaselineWorktreeConstraint(db, fromVersion = latestSchemaVersion
           repository_revision, repository_branch, worktree_state, worktree_digest,
           worktree_files_json, worktree_accepted, known_red_accepted, spec_refs_json,
           evidence_json, verification_json, unknowns_json, gaps_json, classification_json,
-          provider_refs_json, research_run_id, approved_by, approval_note, started_at,
+          provider_refs_json, research_run_id, research_checkpoint_id,
+          approved_by, approval_note, started_at,
           updated_at, converged_at
         FROM baselines;
         DROP TABLE baselines;
@@ -717,7 +784,11 @@ function upgradeBaselineWorktreeConstraint(db, fromVersion = latestSchemaVersion
 
 function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
   assertNoDuplicateActiveSessionLeases(db);
-  if (tableSupportsKimi(db, 'events') && tableSupportsKimi(db, 'sessions')) return false;
+  const missingKimi = !tableSupportsRuntime(db, 'events', 'kimi')
+    || !tableSupportsRuntime(db, 'sessions', 'kimi');
+  const missingGrok = !tableSupportsRuntime(db, 'events', 'grok')
+    || !tableSupportsRuntime(db, 'sessions', 'grok');
+  if (!missingKimi && !missingGrok) return false;
   const previousVersion = fromVersion || 'unknown';
   const foreignKeys = db.pragma('foreign_keys', { simple: true });
   db.pragma('foreign_keys = OFF');
@@ -732,7 +803,7 @@ function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
           task_id       TEXT,
           change_id     TEXT,
           session_id    TEXT,
-          runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex', 'kimi')),
+          runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex', 'kimi', 'grok')),
           payload_json  TEXT
         );
         INSERT INTO events_runtime_upgrade
@@ -749,7 +820,7 @@ function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
         CREATE TABLE sessions_runtime_upgrade (
           sid               TEXT PRIMARY KEY,
           task_id           TEXT NOT NULL REFERENCES tasks(id),
-          runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex', 'kimi')),
+          runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex', 'kimi', 'grok')),
           pid               INTEGER,
           worktree_path     TEXT NOT NULL,
           artifact_dir      TEXT NOT NULL,
@@ -771,15 +842,28 @@ function upgradeRuntimeConstraints(db, fromVersion = latestSchemaVersion(db)) {
         CREATE UNIQUE INDEX sessions_one_active_task
           ON sessions(task_id) WHERE status = 'running';
       `);
-      db.prepare(
-        `INSERT INTO migration_history
-          (from_version, to_version, direction, status, notes)
-         VALUES (?, ?, 'forward', 'success', ?)`,
-      ).run(
-        previousVersion,
-        KIMI_SCHEMA_VERSION,
-        'Add Kimi to durable event and session runtime constraints',
-      );
+      if (missingKimi) {
+        db.prepare(
+          `INSERT INTO migration_history
+            (from_version, to_version, direction, status, notes)
+           VALUES (?, ?, 'forward', 'success', ?)`,
+        ).run(
+          previousVersion,
+          KIMI_SCHEMA_VERSION,
+          'Add Kimi to durable event and session runtime constraints',
+        );
+      }
+      if (missingGrok) {
+        db.prepare(
+          `INSERT INTO migration_history
+            (from_version, to_version, direction, status, notes)
+           VALUES (?, ?, 'forward', 'success', ?)`,
+        ).run(
+          missingKimi ? KIMI_SCHEMA_VERSION : previousVersion,
+          KERNEL_SCHEMA_VERSION,
+          'Add Grok to durable event and session runtime constraints',
+        );
+      }
       const violations = db.pragma('foreign_key_check');
       if (violations.length > 0) {
         throw new Error(`runtime constraint migration produced ${violations.length} foreign key violation(s)`);
@@ -935,6 +1019,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
         WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
         DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
         DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+        KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
       ].includes(fromVersion)
         && !contextMigration,
     );
@@ -953,6 +1038,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     applyBaselineColumns(db);
     applyChangeColumns(db);
     applySemanticAuthorityColumns(db);
+    applyKernelIntegrityColumns(db);
     const artifactRegistryChanged = applyArtifactRegistryUpgrade(db);
     const baselineMigration = db.prepare(
       "SELECT 1 FROM migration_history WHERE to_version = '11.0' AND status = 'success' LIMIT 1",
@@ -962,6 +1048,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION,
       GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
       DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion)
       && !baselineMigration) {
       db.prepare(
@@ -993,7 +1080,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
         db.prepare(
           `UPDATE baselines SET mode = 'migrated', status = 'adopting',
            classification_json = ?, gaps_json = ?, approved_by = NULL, approval_note = ?,
-           converged_at = NULL, research_run_id = NULL, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+           converged_at = NULL, research_run_id = NULL, research_checkpoint_id = NULL,
+           updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
            WHERE id = ?`,
         ).run(
           JSON.stringify(classification), JSON.stringify(gaps),
@@ -1034,6 +1122,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
       DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
       DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion) && !workflowMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1051,7 +1140,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     if (fromVersion && ![
       AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION,
       GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
-      ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      ARTIFACT_REGISTRY_SCHEMA_VERSION, KERNEL_SCHEMA_VERSION,
+      CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion) && !authorityMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1069,7 +1159,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     if (fromVersion && ![
       SEMANTIC_SCHEMA_VERSION, DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION,
       ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
-      ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      ARTIFACT_REGISTRY_SCHEMA_VERSION, KERNEL_SCHEMA_VERSION,
+      CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion) && !semanticMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1087,6 +1178,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     if (fromVersion && ![
       DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
       DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion)
       && !dialogueMigration) {
       db.prepare(
@@ -1104,7 +1196,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     ).get();
     if (fromVersion && ![
       GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
-      ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      ARTIFACT_REGISTRY_SCHEMA_VERSION, KERNEL_SCHEMA_VERSION,
+      CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion)
       && !gitStateMigration) {
       db.prepare(
@@ -1123,7 +1216,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     ).get();
     if (fromVersion && ![
       ADAPTIVE_SCHEMA_VERSION, DECISION_COMPLETION_SCHEMA_VERSION,
-      ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      ARTIFACT_REGISTRY_SCHEMA_VERSION, KERNEL_SCHEMA_VERSION,
+      CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion) && !adaptiveMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1142,6 +1236,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
     ).get();
     if (fromVersion && ![
       DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+      KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
     ].includes(fromVersion) && !completionMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1159,6 +1254,8 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       "SELECT 1 FROM migration_history WHERE to_version = '20.0' AND status = 'success' LIMIT 1",
     ).get();
     if (fromVersion && fromVersion !== ARTIFACT_REGISTRY_SCHEMA_VERSION
+      && fromVersion !== KERNEL_SCHEMA_VERSION
+      && fromVersion !== CHECKPOINT_NATIVE_SCHEMA_VERSION
       && !artifactRegistryMigration) {
       db.prepare(
         `INSERT INTO migration_history
@@ -1172,6 +1269,39 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
           : 'Add the typed artifact registry, dependency graph, and orphan diagnostics',
       );
     }
+    const kernelMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '21.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion
+      && fromVersion !== KERNEL_SCHEMA_VERSION
+      && fromVersion !== CHECKPOINT_NATIVE_SCHEMA_VERSION
+      && !kernelMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        ARTIFACT_REGISTRY_SCHEMA_VERSION,
+        KERNEL_SCHEMA_VERSION,
+        'Add the seven-tool persistence kernel, reversible stage checkpoints, canonical context envelopes, normalized decisions, worker packets, and Grok runtime authority',
+      );
+    }
+    const checkpointNativeMigration = db.prepare(
+      "SELECT 1 FROM migration_history WHERE to_version = '22.0' AND status = 'success' LIMIT 1",
+    ).get();
+    if (fromVersion
+      && fromVersion !== CHECKPOINT_NATIVE_SCHEMA_VERSION
+      && !checkpointNativeMigration) {
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        KERNEL_SCHEMA_VERSION,
+        CHECKPOINT_NATIVE_SCHEMA_VERSION,
+        'Bind Baseline research to Stage Checkpoints and add byte digests for Context Envelopes and Worker Packets',
+      );
+    }
     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)');
     ensureActiveSessionLeaseIndex(db);
@@ -1179,7 +1309,7 @@ function applyCompatibleUpgrades(db, fromVersion = latestSchemaVersion(db), { le
       'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
     ).run(
       EXPECTED_VERSION,
-      'Typed artifact registry, normalized dependency edges, and orphan diagnostics',
+      'Checkpoint-native baseline authority plus byte-bound Context Envelopes and Worker Packets',
     );
   })();
 }
@@ -1212,6 +1342,7 @@ function initStateDb(dbPath) {
         WORKFLOW_SCHEMA_VERSION, AUTHORITY_SCHEMA_VERSION, SEMANTIC_SCHEMA_VERSION,
         DIALOGUE_SCHEMA_VERSION, GIT_AUTHORITY_SCHEMA_VERSION, ADAPTIVE_SCHEMA_VERSION,
         DECISION_COMPLETION_SCHEMA_VERSION, ARTIFACT_REGISTRY_SCHEMA_VERSION,
+        KERNEL_SCHEMA_VERSION, CHECKPOINT_NATIVE_SCHEMA_VERSION,
       ].includes(fromVersion);
     backupPath = migrationBackup(db, dbPath, fromVersion, existing);
     // This must precede every ALTER, table rebuild, or index creation. Runtime