chati-dev 4.4.1 → 4.5.2

package/src/installer/validator.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { hashFile } from './file-hasher.js';
 import { loadManifest } from './manifest.js';
 import { ADAPTABLE_FILES } from '../config/framework-adapter.js';
@@ -187,28 +187,23 @@ export async function validateInstallation(targetDir) {
     try {
       const configContent = readFileSync(configYamlPath, 'utf-8');
       const enabledProviders = [];
-      let primaryProvider = null;
       let currentProvider = null;
 
       for (const line of configContent.split('\n')) {
         const provLine = line.match(/^\s{4}(\w+):$/);
-        if (provLine && ['claude', 'gemini', 'codex'].includes(provLine[1])) {
+        if (provLine && ['claude', 'gemini', 'codex', 'grok'].includes(provLine[1])) {
           currentProvider = provLine[1];
         }
         if (currentProvider && line.includes('enabled: true')) {
           enabledProviders.push(currentProvider);
         }
-        if (currentProvider && line.includes('primary: true')) {
-          primaryProvider = currentProvider;
-        }
       }
 
-      // Validate overlay completeness for each secondary provider
-      if (enabledProviders.length > 1 && primaryProvider) {
-        const secondaryProviders = enabledProviders.filter(p => p !== primaryProvider);
+      // Validate overlay completeness for every enabled provider.
+      if (enabledProviders.length > 0) {
         const overlayDetails = [];
 
-        for (const provider of secondaryProviders) {
+        for (const provider of enabledProviders) {
           let present = 0;
           let missing = 0;
           const missingFiles = [];

package/src/installer-v2/catalog-client.js

@@ -0,0 +1,165 @@
+import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { isIP } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { canonicalSerialize, ContractError } from '@chati/core';
+import { validateCapabilitySnapshot } from '@chati/provider-registry';
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export const DEFAULT_CATALOG_URL = 'https://raw.githubusercontent.com/Chati-dev/Chati.dev/main/packages/chati-dev/src/installer-v2/model-catalog-envelope.json';
+export const CATALOG_CACHE_PATH = '.chati/v2/cache/model-catalog.json';
+export const BUNDLED_CATALOG_PATH = join(moduleDir, 'model-catalog.json');
+export const BUNDLED_CATALOG_SIGNATURE_PATH = join(moduleDir, 'model-catalog.sig');
+const PUBLIC_KEY_PATH = join(moduleDir, '..', 'installer', 'signing-public-key.pem');
+
+function catalogError(code, message, details = {}) {
+  return new ContractError(code, message, details);
+}
+
+function parseSignedPayload(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw catalogError('INVALID_SIGNED_CATALOG', 'signed catalog payload must be an object');
+  }
+  if (!value.catalog || typeof value.signature !== 'string' || !value.signature.trim()) {
+    throw catalogError('INVALID_SIGNED_CATALOG', 'signed catalog payload requires catalog and signature');
+  }
+  return { catalog: value.catalog, signature: value.signature.trim() };
+}
+
+function readPublicKey(publicKeyPem) {
+  const source = publicKeyPem ?? readFileSync(PUBLIC_KEY_PATH, 'utf8');
+  return createPublicKey(source);
+}
+
+export function assertCatalogUrl(value) {
+  let url;
+  try { url = new URL(value); } catch { throw catalogError('CATALOG_URL_INVALID', 'catalog URL must be an absolute HTTPS URL'); }
+  if (url.protocol !== 'https:' || url.username || url.password) throw catalogError('CATALOG_URL_INVALID', 'catalog URL must use HTTPS without embedded credentials');
+  const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const ipKind = isIP(hostname);
+  const blockedIpv4 = ipKind === 4 && (/^10\./.test(hostname)
+    || /^127\./.test(hostname)
+    || /^169\.254\./.test(hostname)
+    || /^192\.168\./.test(hostname)
+    || /^172\.(1[6-9]|2\d|3[01])\./.test(hostname)
+    || /^0\./.test(hostname));
+  const blockedIpv6 = ipKind === 6 && (hostname === '::1' || hostname === '::' || /^(fc|fd|fe8|fe9|fea|feb)/.test(hostname));
+  if (hostname === 'localhost' || hostname.endsWith('.localhost') || blockedIpv4 || blockedIpv6) {
+    throw catalogError('CATALOG_URL_FORBIDDEN', 'catalog URL may not target a loopback, link-local, or private host');
+  }
+  return url.toString();
+}
+
+export function verifySignedCapabilityCatalog(payload, { clock = () => new Date(), publicKeyPem } = {}) {
+  const { catalog, signature } = parseSignedPayload(payload);
+  const verified = cryptoVerify(
+    null,
+    Buffer.from(canonicalSerialize(catalog)),
+    readPublicKey(publicKeyPem),
+    Buffer.from(signature, 'base64'),
+  );
+  if (!verified) throw catalogError('CATALOG_SIGNATURE_INVALID', 'model catalog signature is invalid');
+  return validateCapabilitySnapshot(catalog, { clock });
+}
+
+function readSignedCatalogFile(path) {
+  return parseSignedPayload(JSON.parse(readFileSync(path, 'utf8')));
+}
+
+function writeCache(projectDir, payload) {
+  const path = join(projectDir, CATALOG_CACHE_PATH);
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp-${process.pid}`;
+  writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+  renameSync(temporary, path);
+  return CATALOG_CACHE_PATH;
+}
+
+function readBundledPayload() {
+  return {
+    catalog: JSON.parse(readFileSync(BUNDLED_CATALOG_PATH, 'utf8')),
+    signature: readFileSync(BUNDLED_CATALOG_SIGNATURE_PATH, 'utf8').trim(),
+  };
+}
+
+function catalogPublishedAt(catalog) {
+  const parsed = catalog.published_at ? Date.parse(catalog.published_at) : 0;
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+const SOURCE_PRIORITY = Object.freeze({ remote: 3, cache: 2, bundled: 1 });
+
+/**
+ * Resolves every available signed CHATI model catalog and selects the newest
+ * published snapshot. Remote wins ties, then cache, then the bundled release.
+ * Vendor APIs and local binary inference stay outside this trust boundary.
+ */
+export async function resolveCapabilityCatalog({
+  projectDir,
+  catalogUrl = process.env.CHATI_MODEL_CATALOG_URL || DEFAULT_CATALOG_URL,
+  fetchImpl = globalThis.fetch,
+  clock = () => new Date(),
+  publicKeyPem,
+  timeoutMs = 5000,
+} = {}) {
+  const failures = [];
+  const candidates = [];
+
+  if (catalogUrl && typeof fetchImpl === 'function') {
+    try {
+      const safeCatalogUrl = assertCatalogUrl(catalogUrl);
+      const response = await fetchImpl(safeCatalogUrl, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (!response.ok) throw catalogError('CATALOG_HTTP_ERROR', `catalog endpoint returned HTTP ${response.status}`);
+      const payload = parseSignedPayload(await response.json());
+      const catalog = verifySignedCapabilityCatalog(payload, { clock, publicKeyPem });
+      candidates.push({ source: 'remote', source_url: safeCatalogUrl, payload, catalog });
+    } catch (error) {
+      failures.push({ source: 'remote', code: error.code || error.name || 'CATALOG_FETCH_FAILED' });
+    }
+  }
+
+  if (projectDir) {
+    const cachePath = join(projectDir, CATALOG_CACHE_PATH);
+    if (existsSync(cachePath)) {
+      try {
+        const payload = readSignedCatalogFile(cachePath);
+        const catalog = verifySignedCapabilityCatalog(payload, { clock, publicKeyPem });
+        candidates.push({ source: 'cache', cache_path: CATALOG_CACHE_PATH, payload, catalog });
+      } catch (error) {
+        failures.push({ source: 'cache', code: error.code || error.name || 'CATALOG_CACHE_INVALID' });
+      }
+    }
+  }
+
+  try {
+    const payload = readBundledPayload();
+    const catalog = verifySignedCapabilityCatalog(payload, { clock, publicKeyPem });
+    candidates.push({ source: 'bundled', cache_path: null, payload, catalog });
+  } catch (error) {
+    failures.push({ source: 'bundled', code: error.code || error.name || 'CATALOG_BUNDLE_INVALID' });
+  }
+
+  if (candidates.length === 0) {
+    throw catalogError('CATALOG_UNAVAILABLE', 'no fresh, signed CHATI model catalog is available', { failures });
+  }
+
+  candidates.sort((left, right) =>
+    catalogPublishedAt(right.catalog) - catalogPublishedAt(left.catalog)
+    || SOURCE_PRIORITY[right.source] - SOURCE_PRIORITY[left.source]
+  );
+  const selected = candidates[0];
+  const cache_path = selected.source === 'remote' && projectDir
+    ? writeCache(projectDir, selected.payload)
+    : (selected.cache_path ?? null);
+  return Object.freeze({
+    source: selected.source,
+    ...(selected.source_url ? { source_url: selected.source_url } : {}),
+    cache_path,
+    catalog: selected.catalog,
+  });
+}

package/src/installer-v2/index.js

@@ -0,0 +1,304 @@
+/**
+ * Installer v2 is deliberately a planner, not an installer.
+ *
+ * It creates one provider-neutral installation artifact, inspects a target for
+ * legacy v1 markers, and returns a migration/rollback plan. Artifact writes
+ * are explicit through installV2 or authorized migrateV2. It never invokes a
+ * provider CLI or reads credentials.
+ */
+import { existsSync, mkdirSync, writeFileSync, renameSync, readFileSync, copyFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { canonicalize, canonicalSerialize, sha256, ContractError } from '@chati/core';
+import { validateInstallation } from '@chati/provider-registry';
+
+export const INSTALLATION_SCHEMA_VERSION = 2;
+export const INSTALLATION_ARTIFACT_PATH = '.chati/v2/installation.json';
+
+const V1_MARKERS = Object.freeze([
+  { provider_id: 'anthropic', harness_id: 'claude', path: '.claude/settings.json' },
+  { provider_id: 'anthropic', harness_id: 'claude', path: 'CLAUDE.local.md' },
+  { provider_id: 'openai', harness_id: 'codex', path: '.codex/config.toml' },
+  { provider_id: 'xai', harness_id: 'grok', path: '.grok/config.json' },
+  { provider_id: null, harness_id: null, path: '.chati/session.yaml' },
+]);
+
+const PROVIDER_SPECIFIC_ROOT_FILES = new Set([
+  'claude.md', 'claude.local.md', 'codex.md', 'codex.local.md', 'grok.md', 'grok.local.md',
+  '.claude.lock', '.codex.lock', '.grok.lock',
+]);
+
+function assertObject(value, code, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new ContractError(code, `${label} must be an object`);
+}
+
+function assertString(value, code, label) {
+  if (typeof value !== 'string' || value.trim() === '') throw new ContractError(code, `${label} must be a non-empty string`);
+}
+
+function readClock(clock) {
+  if (typeof clock !== 'function') throw new ContractError('MISSING_CLOCK', 'a deterministic clock function is required');
+  const result = clock();
+  const date = result instanceof Date ? result : new Date(result);
+  if (Number.isNaN(date.getTime())) throw new ContractError('INVALID_CLOCK', 'clock must return a valid timestamp');
+  return date.toISOString();
+}
+
+function ensureRelativePath(path) {
+  assertString(path, 'INVALID_MANAGED_PATH', 'managed path');
+  const normalized = path.replaceAll('\\', '/');
+  const root = normalized.split('/')[0];
+  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+    throw new ContractError('INVALID_MANAGED_PATH', 'managed path must remain inside the project');
+  }
+  if (['.claude', '.codex', '.grok'].includes(root)) {
+    throw new ContractError('PROVIDER_SPECIFIC_MANAGED_PATH', 'installer v2 may not manage provider-specific configuration paths');
+  }
+  if (PROVIDER_SPECIFIC_ROOT_FILES.has(root.toLowerCase())) {
+    throw new ContractError('PROVIDER_SPECIFIC_MANAGED_PATH', 'installer v2 may not manage provider-specific root markers or locks');
+  }
+  return normalized;
+}
+
+function normalizeBrainReadCapability(capability) {
+  if (capability === undefined || capability === null || capability === false) return { status: 'not-configured' };
+  assertObject(capability, 'INVALID_BRAIN_CAPABILITY', 'brain_read_capability');
+  if (capability.status === 'not-configured') return { status: 'not-configured' };
+  if (capability.mode !== 'read-only') throw new ContractError('BRAIN_WRITE_FORBIDDEN', 'installer v2 permits only a read-only Brain capability');
+  assertString(capability.policy_ref, 'INVALID_BRAIN_CAPABILITY', 'brain_read_capability.policy_ref');
+  return { status: 'configured', mode: 'read-only', policy_ref: capability.policy_ref };
+}
+
+function artifactCore(input, createdAt) {
+  assertObject(input, 'INVALID_INSTALLATION', 'installation input');
+  assertObject(input.installation, 'INVALID_INSTALLATION', 'installation');
+  assertObject(input.capability_snapshot, 'INVALID_CATALOG', 'capability_snapshot');
+  assertString(input.project_id, 'INVALID_INSTALLATION', 'project_id');
+  const installation = validateInstallation(input.installation, input.capability_snapshot, { clock: () => createdAt });
+  const brain_read_capability = normalizeBrainReadCapability(input.brain_read_capability);
+  const managed_paths = (input.managed_paths ?? [INSTALLATION_ARTIFACT_PATH]).map(ensureRelativePath);
+  if (!managed_paths.includes(INSTALLATION_ARTIFACT_PATH)) managed_paths.unshift(INSTALLATION_ARTIFACT_PATH);
+  if (new Set(managed_paths).size !== managed_paths.length) throw new ContractError('DUPLICATE_MANAGED_PATH', 'managed_paths must be unique');
+  const selectedModelKeys = new Set(installation.enabled_providers.flatMap((binding) =>
+    binding.allowed_models.map((model_id) => `${binding.provider_id}:${model_id}`),
+  ));
+  const capability_snapshot = {
+    // This is a projection, not a catalog copy. Keep only attributes needed by
+    // the installation contract and only models explicitly selected by a binding.
+    snapshot_id: input.capability_snapshot.snapshot_id,
+    expires_at: input.capability_snapshot.expires_at,
+    models: input.capability_snapshot.models
+      .filter((model) => selectedModelKeys.has(`${model.provider_id}:${model.model_id}`))
+      .map(({ provider_id, model_id, actions, adjudication_priority, highest_reasoning_configuration, routing_priority, tier, natural_role }) => ({
+        provider_id,
+        model_id,
+        actions,
+        ...(adjudication_priority !== undefined ? { adjudication_priority } : {}),
+        ...(highest_reasoning_configuration !== undefined ? { highest_reasoning_configuration } : {}),
+        ...(routing_priority !== undefined ? { routing_priority } : {}),
+        ...(tier !== undefined ? { tier } : {}),
+        ...(natural_role !== undefined ? { natural_role } : {}),
+      })),
+  };
+  return {
+    schema_version: INSTALLATION_SCHEMA_VERSION,
+    artifact_type: 'chati-installation',
+    project_id: input.project_id,
+    created_at: createdAt,
+    installation,
+    // An artifact exposes no capability information for providers not selected
+    // during installation. The full catalog remains an input, never an output.
+    capability_snapshot,
+    brain_read_capability,
+    managed_paths,
+  };
+}
+
+/** Creates a deterministic provider-neutral artifact. It never installs it. */
+export function createInstallationArtifact(input, { clock = () => new Date(), artifactId } = {}) {
+  const core = artifactCore(input, readClock(clock));
+  const digest = sha256(core);
+  const installation_artifact_id = artifactId ?? `install-v2-${digest.slice(0, 16)}`;
+  assertString(installation_artifact_id, 'INVALID_INSTALLATION', 'installation_artifact_id');
+  return Object.freeze(canonicalize({ ...core, installation_artifact_id, digest }));
+}
+
+/** Validates an artifact without inspecting provider-specific configuration files. */
+export function doctorV2(artifact, { clock = () => new Date() } = {}) {
+  const checks = [];
+  try {
+    assertObject(artifact, 'INVALID_ARTIFACT', 'artifact');
+    if (artifact.schema_version !== INSTALLATION_SCHEMA_VERSION || artifact.artifact_type !== 'chati-installation') {
+      throw new ContractError('UNSUPPORTED_INSTALLATION_ARTIFACT', 'expected a chati installation artifact v2');
+    }
+    const { digest, installation_artifact_id, ...core } = artifact;
+    assertString(installation_artifact_id, 'INVALID_ARTIFACT', 'installation_artifact_id');
+    if (sha256(core) !== digest) throw new ContractError('INSTALLATION_ARTIFACT_DRIFT', 'installation artifact digest does not match its content');
+    validateInstallation(artifact.installation, artifact.capability_snapshot, { clock: () => readClock(clock) });
+    normalizeBrainReadCapability(artifact.brain_read_capability);
+    if (!Array.isArray(artifact.managed_paths) || !artifact.managed_paths.every((path) => ensureRelativePath(path))) {
+      throw new ContractError('INVALID_MANAGED_PATH', 'managed_paths must be valid project-relative paths');
+    }
+    checks.push({ name: 'artifact', status: 'pass', message: 'artifact schema and digest are valid' });
+    checks.push({ name: 'selected-bindings', status: 'pass', message: 'only explicitly selected provider/harness bindings are present' });
+    checks.push({ name: 'brain-capability', status: 'pass', message: 'Brain capability is absent or read-only' });
+  } catch (error) {
+    checks.push({ name: 'artifact', status: 'fail', code: error.code ?? 'INVALID_ARTIFACT', message: error.message });
+  }
+  return Object.freeze({ schema_version: 1, doctor: 'chati-installation-v2', passed: checks.every((check) => check.status === 'pass'), checks });
+}
+
+/** Read-only detector for known v1 footprints. Marker presence never enables a provider. */
+export function detectV1Installation(projectDir, { exists = existsSync } = {}) {
+  assertString(projectDir, 'INVALID_PROJECT_DIR', 'projectDir');
+  if (typeof exists !== 'function') throw new ContractError('INVALID_DETECTOR', 'exists must be a function');
+  const markers = V1_MARKERS.filter((marker) => exists(join(projectDir, marker.path))).map((marker) => ({ ...marker }));
+  const bindings = markers
+    .filter((marker) => marker.provider_id)
+    .map(({ provider_id, harness_id }) => ({ provider_id, harness_id }))
+    .filter((binding, index, all) => all.findIndex((entry) => entry.provider_id === binding.provider_id && entry.harness_id === binding.harness_id) === index);
+  return Object.freeze({ detector_version: 1, detected: markers.length > 0, markers, detected_bindings: bindings });
+}
+
+/** Builds a backup plan only. The caller must separately authorize and execute any write. */
+export function createBackupPlan(projectDir, detector, artifact) {
+  assertString(projectDir, 'INVALID_PROJECT_DIR', 'projectDir');
+  assertObject(detector, 'INVALID_DETECTOR', 'detector');
+  assertObject(artifact, 'INVALID_ARTIFACT', 'artifact');
+  const backup_id = `backup-v2-${artifact.digest.slice(0, 16)}`;
+  const entries = detector.markers.map((marker) => ({ source_path: marker.path, backup_path: `.chati/v2/backups/${backup_id}/${marker.path}` }));
+  return Object.freeze(canonicalize({ schema_version: 1, backup_id, project_dir: resolve(projectDir), entries, write_required: false }));
+}
+
+/** Produces the inverse of a future authorized migration, without performing either operation. */
+export function createRollbackPlan(artifact, backupPlan) {
+  assertObject(artifact, 'INVALID_ARTIFACT', 'artifact');
+  assertObject(backupPlan, 'INVALID_BACKUP_PLAN', 'backupPlan');
+  return Object.freeze(canonicalize({
+    schema_version: 1,
+    rollback_id: `rollback-v2-${artifact.digest.slice(0, 16)}`,
+    installation_artifact_id: artifact.installation_artifact_id,
+    backup_id: backupPlan.backup_id,
+    restore_entries: backupPlan.entries,
+    remove_created_paths: artifact.managed_paths,
+    requires_explicit_authorization: true,
+    write_required: false,
+  }));
+}
+
+/**
+ * Read-only migration preview. It does not write a v2 artifact or back up v1.
+ * Re-running with the same inputs returns the same plans and does not duplicate
+ * provider bindings or managed paths.
+ */
+export function dryRunV2(input, { projectDir, clock = () => new Date(), exists = existsSync } = {}) {
+  assertString(projectDir, 'INVALID_PROJECT_DIR', 'projectDir');
+  const artifact = createInstallationArtifact(input, { clock });
+  const doctor = doctorV2(artifact, { clock });
+  const detector = detectV1Installation(projectDir, { exists });
+  const backup_plan = createBackupPlan(projectDir, detector, artifact);
+  const rollback_plan = createRollbackPlan(artifact, backup_plan);
+  const configured = new Set(artifact.installation.enabled_providers.map(({ provider_id, harness_id }) => `${provider_id}:${harness_id}`));
+  const incompatibilities = detector.detected_bindings
+    .filter(({ provider_id, harness_id }) => !configured.has(`${provider_id}:${harness_id}`))
+    .map(({ provider_id, harness_id }) => ({ code: 'V1_BINDING_NOT_SELECTED', provider_id, harness_id, message: 'legacy marker is not a selected v2 binding' }));
+  const pathOutsideProject = artifact.managed_paths.some((managedPath) => relative(resolve(projectDir), resolve(projectDir, managedPath)).split(sep).includes('..'));
+  if (pathOutsideProject) throw new ContractError('INVALID_MANAGED_PATH', 'managed path resolves outside project');
+  return Object.freeze(canonicalize({ schema_version: 1, mode: 'dry-run', writes_performed: false, artifact, doctor, detector, backup_plan, rollback_plan, incompatibilities }));
+}
+
+/** Explicit v2 installation. It writes only the provider-neutral artifact path. */
+export function installV2(input, { projectDir, clock = () => new Date(), exists = existsSync } = {}) {
+  const report = dryRunV2(input, { projectDir, clock, exists });
+  const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
+  const directory = join(projectDir, '.chati', 'v2');
+  mkdirSync(directory, { recursive: true });
+  const serialized = `${canonicalSerialize(report.artifact)}\n`;
+  if (existsSync(artifactPath)) {
+    const existing = readFileSync(artifactPath, 'utf8');
+    if (existing === serialized) return Object.freeze(canonicalize({ ...report, mode: 'installed', writes_performed: false, artifact_path: INSTALLATION_ARTIFACT_PATH }));
+    throw new ContractError('INSTALLATION_ARTIFACT_EXISTS', 'existing v2 artifact differs; use an explicit migration or rollback flow');
+  }
+  const temporary = `${artifactPath}.tmp-${process.pid}`;
+  writeFileSync(temporary, serialized, { encoding: 'utf8', flag: 'wx' });
+  renameSync(temporary, artifactPath);
+  return Object.freeze(canonicalize({ ...report, mode: 'installed', writes_performed: true, artifact_path: INSTALLATION_ARTIFACT_PATH }));
+}
+
+/**
+ * Explicitly replaces an existing v2 artifact after preserving its exact
+ * bytes in the project-local backup store. Provider-specific files are never
+ * read or rewritten by this operation.
+ */
+export function reconfigureV2(input, { projectDir, clock = () => new Date(), exists = existsSync } = {}) {
+  const report = dryRunV2(input, { projectDir, clock, exists });
+  const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
+  if (!existsSync(artifactPath)) return installV2(input, { projectDir, clock, exists });
+  const existing = readFileSync(artifactPath, 'utf8');
+  let existingArtifact;
+  try { existingArtifact = JSON.parse(existing); } catch (error) {
+    throw new ContractError('EXISTING_INSTALLATION_CORRUPT', `existing v2 artifact is not valid JSON: ${error.message}`);
+  }
+  if (existingArtifact?.schema_version !== INSTALLATION_SCHEMA_VERSION || existingArtifact?.artifact_type !== 'chati-installation') {
+    throw new ContractError('EXISTING_INSTALLATION_CORRUPT', 'existing v2 artifact has an unsupported schema');
+  }
+  const backupId = `reconfigure-${sha256({ previous: existingArtifact.digest, next: report.artifact.digest }).slice(0, 20)}`;
+  const backupPath = join(projectDir, '.chati', 'v2', 'backups', backupId, 'installation.json');
+  mkdirSync(dirname(backupPath), { recursive: true });
+  if (existsSync(backupPath) && readFileSync(backupPath, 'utf8') !== existing) {
+    throw new ContractError('RECONFIGURE_BACKUP_CONFLICT', 'reconfiguration backup path contains different material');
+  }
+  if (!existsSync(backupPath)) writeFileSync(backupPath, existing, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  const serialized = `${canonicalSerialize(report.artifact)}\n`;
+  const temporary = `${artifactPath}.tmp-${process.pid}`;
+  writeFileSync(temporary, serialized, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  renameSync(temporary, artifactPath);
+  return Object.freeze(canonicalize({
+    ...report,
+    mode: 'reconfigured',
+    writes_performed: true,
+    artifact_path: INSTALLATION_ARTIFACT_PATH,
+    backup_path: relative(projectDir, backupPath).replaceAll('\\', '/'),
+    provider_specific_files_rewritten: false,
+  }));
+}
+
+/**
+ * Performs the narrow, explicit v4 to v2 activation. It backs up detected
+ * legacy markers, writes the provider-neutral artifact, and never rewrites a
+ * provider-specific configuration file.
+ */
+export function migrateV2(input, { projectDir, authorize = false, clock = () => new Date(), exists = existsSync } = {}) {
+  const preview = dryRunV2(input, { projectDir, clock, exists });
+  if (authorize !== true) {
+    return Object.freeze(canonicalize({ ...preview, mode: 'migration-preview', writes_performed: false, requires_explicit_authorization: true }));
+  }
+
+  const artifactPath = join(projectDir, INSTALLATION_ARTIFACT_PATH);
+  if (existsSync(artifactPath)) {
+    const expected = `${canonicalSerialize(preview.artifact)}\n`;
+    if (readFileSync(artifactPath, 'utf8') !== expected) {
+      throw new ContractError('INSTALLATION_ARTIFACT_EXISTS', 'existing v2 artifact differs; use an explicit rollback flow');
+    }
+  }
+
+  const backed_up = [];
+  for (const entry of preview.backup_plan.entries) {
+    const source = join(projectDir, entry.source_path);
+    const destination = join(projectDir, entry.backup_path);
+    if (!existsSync(source) || existsSync(destination)) continue;
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(source, destination, 0);
+    backed_up.push(entry);
+  }
+  const installed = installV2(input, { projectDir, clock, exists });
+  return Object.freeze(canonicalize({
+    ...preview,
+    mode: 'migrated',
+    writes_performed: installed.writes_performed || backed_up.length > 0,
+    backed_up,
+    artifact_path: installed.artifact_path,
+    provider_specific_files_rewritten: false,
+  }));
+}
+
+export { canonicalSerialize };