ai-delivery-workflow 0.2.2

package/lib/evolution.mjs

@@ -0,0 +1,971 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const SCHEMA_VERSION = 1;
+const RISK_ORDER = Object.freeze({ low: 0, medium: 1, high: 2 });
+const STATES = new Set(["observed", "proposed", "trial", "active", "rejected", "disabled", "rolled-back", "superseded", "expired"]);
+const SOURCE_KINDS = new Set(["user", "objective", "ai-observation"]);
+const METRIC_RESULTS = new Set(["improved", "neutral", "worsened", "failure"]);
+const SAFE_POINTS = new Set(["task", "version", "review"]);
+const HOOK_EVENTS = new Set([
+  ...["task", "node", "gate", "artifact", "version", "release"]
+    .flatMap((scope) => ["before", "after", "failed"].map((phase) => `${scope}.${phase}`)),
+  "feedback-recorded",
+  "evaluation-due",
+  "extension-state-changed",
+]);
+const HIGH_CAPABILITIES = new Set([
+  "block", "script", "git", "deployment", "security", "permission", "environment", "external-system",
+]);
+const MEDIUM_CAPABILITIES = new Set([
+  "routing", "template", "work-package", "artifact-generation", "validation",
+]);
+const LOW_CAPABILITIES = new Set(["advisory", "checklist", "display", "declarative-check"]);
+const SECRET_KEY = /^(authorization|cookie|set-cookie|password|passwd|secret|access[_-]?token|refresh[_-]?token|api[_-]?key|private[_-]?key)$/i;
+const BANNED_IMPORT = /(?:node:)?(?:child_process|worker_threads|cluster|net|http|https|http2|dgram|tls|vm)\b|\brequire\s*\(/;
+const MAX_TEXT = 8_192;
+const MAX_EVENT = 64 * 1024;
+const ACTIVE_TASK = path.join(".workflow", "delivery", "runtime", "active-task.json");
+
+function now() {
+  return new Date().toISOString();
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function checksum(value) {
+  const copy = structuredClone(value);
+  delete copy.checksum;
+  return sha256(canonical(copy));
+}
+
+function redact(value, key = "") {
+  if (SECRET_KEY.test(key)) return "[REDACTED]";
+  if (typeof value === "string") {
+    return value
+      .replace(/Bearer\s+[^\s]+/gi, "Bearer [REDACTED]")
+      .replace(/\b(?:sk|ghp|glpat)-[A-Za-z0-9_-]{8,}\b/g, "[REDACTED_TOKEN]")
+      .replace(/\b(authorization|password|passwd|secret|access[_-]?token|refresh[_-]?token|api[_-]?key|private[_-]?key)\s*[:=]\s*[^\s,;]+/gi, "$1=[REDACTED]")
+      .slice(0, MAX_TEXT);
+  }
+  if (Array.isArray(value)) return value.slice(0, 100).map((item) => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).slice(0, 200).map(([name, item]) => [name, redact(item, name)]));
+  }
+  return value;
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temporary, content, "utf8");
+  fs.renameSync(temporary, file);
+}
+
+function isInside(candidate, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function safeId(value, label) {
+  const text = String(value || "").trim();
+  if (!text || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(text)) {
+    throw new Error(`${label} must use letters, numbers, dot, underscore, or hyphen.`);
+  }
+  return text;
+}
+
+function requireText(value, label) {
+  const text = String(value || "").trim();
+  if (!text) throw new Error(`${label} is required.`);
+  return text;
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const options = new Map();
+  const flags = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) {
+      positional.push(value);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) flags.add(value);
+    else {
+      options.set(value, next);
+      index += 1;
+    }
+  }
+  return { positional, options, flags };
+}
+
+function loadStructured(file, yaml) {
+  if (!fs.existsSync(file)) throw new Error(`Input does not exist: ${file}`);
+  const text = fs.readFileSync(file, "utf8");
+  return path.extname(file).toLowerCase() === ".json" ? JSON.parse(text) : yaml.parse(text);
+}
+
+function relativeProjectPath(projectRoot, absolute) {
+  if (!isInside(absolute, projectRoot)) throw new Error(`Path escapes project: ${absolute}`);
+  return path.relative(projectRoot, absolute).replaceAll("\\", "/");
+}
+
+function evolutionPaths(projectRoot) {
+  const workflow = path.join(projectRoot, ".workflow");
+  return {
+    workflow,
+    root: path.join(workflow, "evolution"),
+    index: path.join(workflow, "evolution", "index.yaml"),
+    extensions: path.join(workflow, "extensions"),
+    runtime: path.join(workflow, "delivery", "runtime", "evolution"),
+  };
+}
+
+function emptyIndex() {
+  return {
+    schema_version: SCHEMA_VERSION,
+    revision: 0,
+    feedback: [],
+    proposals: [],
+    extensions: [],
+    decisions: [],
+    updated_at: null,
+  };
+}
+
+function readIndex(paths, yaml) {
+  if (!fs.existsSync(paths.index)) return emptyIndex();
+  const index = yaml.parse(fs.readFileSync(paths.index, "utf8"));
+  if (!index || index.schema_version !== SCHEMA_VERSION) throw new Error("Evolution index schema_version must be 1.");
+  for (const key of ["feedback", "proposals", "extensions", "decisions"]) {
+    if (!Array.isArray(index[key])) throw new Error(`Evolution index ${key} must be an array.`);
+  }
+  return index;
+}
+
+function writeIndex(paths, index, yaml) {
+  index.revision += 1;
+  index.updated_at = now();
+  atomicWrite(paths.index, yaml.stringify(index, { lineWidth: 0 }));
+}
+
+function writeRecord(projectRoot, paths, directory, id, record, yaml) {
+  const file = path.join(paths.root, directory, `${id}.yaml`);
+  atomicWrite(file, yaml.stringify(record, { lineWidth: 0 }));
+  return relativeProjectPath(projectRoot, file);
+}
+
+function nextId(prefix, entries, field) {
+  const maximum = entries.reduce((current, entry) => {
+    const match = String(entry?.[field] || "").match(new RegExp(`^${prefix}-(\\d+)$`));
+    return Math.max(current, match ? Number(match[1]) : 0);
+  }, 0);
+  return `${prefix}-${String(maximum + 1).padStart(4, "0")}`;
+}
+
+function decision(projectRoot, paths, index, yaml, kind, subject, from, to, evidence = {}) {
+  if (!STATES.has(to) && to !== "approved") throw new Error(`Unsupported decision state: ${to}`);
+  const record = {
+    decision_id: nextId("DEC", index.decisions, "decision_id"),
+    kind,
+    subject,
+    from: from || null,
+    to,
+    evidence: redact(evidence),
+    decided_at: now(),
+  };
+  record.checksum = checksum(record);
+  record.path = writeRecord(projectRoot, paths, "decisions", record.decision_id, record, yaml);
+  index.decisions.push(record);
+  if (kind.startsWith("extension-") || kind === "trial-evaluated") {
+    appendRuntimeEvent(paths, {
+      schema_version: 1,
+      event_id: `EVT-${record.decision_id}`,
+      idempotency_key: `decision:${record.decision_id}`,
+      event_type: "extension-state-changed",
+      occurred_at: record.decided_at,
+      scope: { subject },
+      payload: { from: record.from, to: record.to, decision_id: record.decision_id },
+    });
+  }
+  return record;
+}
+
+function appendRuntimeEvent(paths, event) {
+  const file = path.join(paths.runtime, "events", "events.jsonl");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let line = JSON.stringify(redact(event));
+  if (Buffer.byteLength(line, "utf8") > MAX_EVENT) {
+    line = JSON.stringify({ schema_version: 1, event_id: event.event_id, event_type: event.event_type, truncated: true });
+  }
+  fs.appendFileSync(file, `${line}\n`, "utf8");
+  if (!new Set(["evaluation-due", "extension-state-changed"]).has(event.event_type)) {
+    const pendingFile = path.join(paths.runtime, "pending", `${sha256(event.idempotency_key || event.event_id).slice(0, 20)}.json`);
+    if (!fs.existsSync(pendingFile)) atomicWrite(pendingFile, `${JSON.stringify(redact(event), null, 2)}\n`);
+  }
+}
+
+function clearPending(paths) {
+  const pending = path.join(paths.runtime, "pending");
+  fs.rmSync(pending, { recursive: true, force: true });
+  fs.mkdirSync(pending, { recursive: true });
+}
+
+function readProcessed(paths) {
+  const file = path.join(paths.runtime, "processed.json");
+  if (!fs.existsSync(file)) return { schema_version: 1, keys: {} };
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function rememberProcessed(paths, key, result) {
+  const processed = readProcessed(paths);
+  processed.keys[key] = { at: now(), result };
+  const keys = Object.keys(processed.keys);
+  for (const stale of keys.slice(0, Math.max(0, keys.length - 10_000))) delete processed.keys[stale];
+  atomicWrite(path.join(paths.runtime, "processed.json"), `${JSON.stringify(processed, null, 2)}\n`);
+}
+
+function classifyRisk(manifest, requested = "low") {
+  if (!(requested in RISK_ORDER)) throw new Error(`Unsupported requested risk: ${requested}`);
+  const capabilities = new Set(Array.isArray(manifest.capabilities) ? manifest.capabilities : []);
+  const hooks = Array.isArray(manifest.hooks) ? manifest.hooks : [];
+  if (hooks.some((hook) => hook?.decision === "block" || hook?.entrypoint)) capabilities.add("block");
+  let derived = "low";
+  if ([...capabilities].some((item) =>
+    HIGH_CAPABILITIES.has(item) || (!MEDIUM_CAPABILITIES.has(item) && !LOW_CAPABILITIES.has(item)))) derived = "high";
+  else if ([...capabilities].some((item) => MEDIUM_CAPABILITIES.has(item))) derived = "medium";
+  return RISK_ORDER[requested] > RISK_ORDER[derived] ? requested : derived;
+}
+
+function validateManifest(manifest, sourceRoot) {
+  if (!manifest || manifest.schema_version !== 1) throw new Error("Extension manifest schema_version must be 1.");
+  safeId(manifest.extension_id, "extension_id");
+  safeId(manifest.version, "version");
+  if (!Array.isArray(manifest.capabilities) || !manifest.capabilities.length) {
+    throw new Error("Extension manifest capabilities must be a non-empty array.");
+  }
+  if (!Array.isArray(manifest.hooks) || !manifest.hooks.length) {
+    throw new Error("Extension manifest hooks must be a non-empty array.");
+  }
+  for (const hook of manifest.hooks) {
+    if (!HOOK_EVENTS.has(hook?.event)) throw new Error(`Unsupported Hook event: ${hook?.event}`);
+    if (!new Set(["pass", "warn", "block"]).has(hook?.decision || "pass")) {
+      throw new Error(`Unsupported Hook decision: ${hook?.decision}`);
+    }
+    if (hook?.decision === "block" && !hook.event.endsWith(".before")) {
+      throw new Error(`Blocking Hooks are only valid for before events: ${hook.event}`);
+    }
+    if (hook.entrypoint) {
+      const entrypoint = path.resolve(sourceRoot, hook.entrypoint);
+      if (!isInside(entrypoint, sourceRoot) || !entrypoint.endsWith(".mjs") || !fs.existsSync(entrypoint)) {
+        throw new Error(`Hook entrypoint must be an existing project-local .mjs file: ${hook.entrypoint}`);
+      }
+      const source = fs.readFileSync(entrypoint, "utf8");
+      if (BANNED_IMPORT.test(source)) throw new Error(`Hook entrypoint imports a prohibited runtime: ${hook.entrypoint}`);
+    }
+  }
+  for (const file of filesUnder(sourceRoot).filter((item) => item.endsWith(".mjs"))) {
+    if (BANNED_IMPORT.test(fs.readFileSync(file, "utf8"))) {
+      throw new Error(`Extension module imports a prohibited runtime: ${path.relative(sourceRoot, file)}`);
+    }
+  }
+}
+
+function filesUnder(root) {
+  const files = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`Extension sources may not contain symbolic links: ${absolute}`);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) files.push(absolute);
+    }
+  };
+  visit(root);
+  return files.sort();
+}
+
+function directoryChecksum(root) {
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(path.relative(root, file).replaceAll("\\", "/"));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function findExtension(index, id, version) {
+  const extension = index.extensions.find((item) => item.extension_id === id && item.version === version);
+  if (!extension) throw new Error(`Extension is not registered: ${id}@${version}`);
+  return extension;
+}
+
+function eligibleFeedback(feedback, allFeedback) {
+  if (feedback.source_kind === "ai-observation") return false;
+  if (feedback.source_kind === "user" && feedback.explicit_user) return true;
+  if (feedback.source_kind === "objective" && feedback.strong_signal) return true;
+  const related = allFeedback.filter((item) => item.signal_key === feedback.signal_key);
+  const events = new Set(related.map((item) => item.source_event_id));
+  const tasks = new Set(related.map((item) => item.task_id).filter(Boolean));
+  return events.size >= 3 || tasks.size >= 2;
+}
+
+function requireSafePoint(projectRoot, options) {
+  const safePoint = options.get("--safe-point");
+  if (!SAFE_POINTS.has(safePoint)) {
+    throw new Error(`--safe-point must be one of: ${[...SAFE_POINTS].join(", ")}.`);
+  }
+  if (fs.existsSync(path.join(projectRoot, ACTIVE_TASK))) {
+    throw new Error("Evolution state cannot change while an active task marker exists.");
+  }
+  return safePoint;
+}
+
+function normalizeHookOutcome(output) {
+  if (!output || typeof output !== "object" || Array.isArray(output)) {
+    throw new Error("Hook output must be a JSON object.");
+  }
+  if (!new Set(["pass", "warn", "block"]).has(output.decision)) {
+    throw new Error("Hook output decision is invalid.");
+  }
+  if (output.messages !== undefined && !Array.isArray(output.messages)) {
+    throw new Error("Hook output messages must be an array.");
+  }
+  if (output.evidence_refs !== undefined && !Array.isArray(output.evidence_refs)) {
+    throw new Error("Hook output evidence_refs must be an array.");
+  }
+  return redact({
+    decision: output.decision,
+    messages: (output.messages || []).slice(0, 50).map((item) => String(item)),
+    evidence_refs: (output.evidence_refs || []).slice(0, 100).map((item) => String(item)),
+  });
+}
+
+function requireChecksum(extension, supplied) {
+  if (!supplied || supplied !== extension.checksum) {
+    throw new Error(`Checksum mismatch for ${extension.extension_id}@${extension.version}.`);
+  }
+}
+
+function hasValidApproval(index, extension) {
+  if (!extension.approval || extension.approval.checksum !== extension.checksum) return false;
+  const confirmation = index.feedback.find((item) =>
+    item.feedback_id === extension.approval.confirmation_feedback_id);
+  return Boolean(confirmation
+    && confirmation.source_kind === "user"
+    && confirmation.explicit_user
+    && confirmation.category === "extension-approval"
+    && confirmation.confirmation_subject === `${extension.extension_id}@${extension.version}`
+    && confirmation.confirmation_checksum === extension.checksum
+    && confirmation.source_event_id === extension.approval.source_event_id);
+}
+
+function handleFeedback(projectRoot, paths, index, options, flags, yaml) {
+  const idempotencyKey = safeId(options.get("--idempotency-key") || options.get("--source-event-id"), "idempotency_key");
+  const existing = index.feedback.find((item) => item.idempotency_key === idempotencyKey);
+  if (existing) return { feedback_id: existing.feedback_id, path: existing.path, deduplicated: true };
+  const sourceKind = options.get("--source-kind") || "user";
+  if (!SOURCE_KINDS.has(sourceKind)) throw new Error(`Unsupported source kind: ${sourceKind}`);
+  const record = redact({
+    feedback_id: nextId("FDB", index.feedback, "feedback_id"),
+    status: "observed",
+    category: requireText(options.get("--category"), "category"),
+    summary: requireText(options.get("--summary"), "summary"),
+    impact: requireText(options.get("--impact"), "impact"),
+    source_kind: sourceKind,
+    source_event_id: safeId(options.get("--source-event-id"), "source_event_id"),
+    signal_key: safeId(options.get("--signal-key"), "signal_key"),
+    task_id: options.get("--task-id") || null,
+    node_id: options.get("--node-id") || null,
+    iteration_id: options.get("--iteration-id") || null,
+    artifact_id: options.get("--artifact-id") || null,
+    excerpt: options.get("--excerpt") || null,
+    idempotency_key: idempotencyKey,
+    explicit_user: flags.has("--explicit-user"),
+    strong_signal: flags.has("--strong-signal"),
+    confirmation_subject: options.get("--confirmation-subject") || null,
+    confirmation_checksum: options.get("--confirmation-checksum") || null,
+    recorded_at: now(),
+  });
+  if (record.confirmation_checksum && !/^[a-f0-9]{64}$/i.test(record.confirmation_checksum)) {
+    throw new Error("confirmation_checksum must be a SHA-256 value.");
+  }
+  record.checksum = checksum(record);
+  record.path = writeRecord(projectRoot, paths, "feedback", record.feedback_id, record, yaml);
+  index.feedback.push(record);
+  decision(projectRoot, paths, index, yaml, "feedback-recorded", record.feedback_id, null, "observed", {
+    source_event_id: record.source_event_id,
+  });
+  writeIndex(paths, index, yaml);
+  appendRuntimeEvent(paths, {
+    schema_version: 1,
+    event_id: `EVT-${record.feedback_id}`,
+    idempotency_key: `feedback:${record.idempotency_key}`,
+    event_type: "feedback-recorded",
+    occurred_at: record.recorded_at,
+    scope: { feedback_id: record.feedback_id },
+    payload: { category: record.category, signal_key: record.signal_key },
+  });
+  return { feedback_id: record.feedback_id, path: record.path, deduplicated: false, checksum: record.checksum };
+}
+
+function handlePropose(projectRoot, paths, index, options, yaml) {
+  const specFile = path.resolve(options.get("--spec") || "");
+  if (!isInside(specFile, projectRoot)) throw new Error("Proposal spec must be inside the project.");
+  const spec = redact(loadStructured(specFile, yaml));
+  for (const field of ["title", "extension_id", "hypothesis", "baseline"]) requireText(spec[field], field);
+  safeId(spec.extension_id, "extension_id");
+  if (!Array.isArray(spec.feedback_ids) || !spec.feedback_ids.length) throw new Error("feedback_ids must be a non-empty array.");
+  if (!Array.isArray(spec.metrics) || !spec.metrics.length) throw new Error("metrics must be a non-empty array.");
+  if (!Array.isArray(spec.scope) || !spec.scope.length) throw new Error("scope must be a non-empty array.");
+  if (!Array.isArray(spec.rollback_conditions) || !spec.rollback_conditions.length) {
+    throw new Error("rollback_conditions must be a non-empty array.");
+  }
+  const feedback = spec.feedback_ids.map((id) => {
+    const record = index.feedback.find((item) => item.feedback_id === id);
+    if (!record) throw new Error(`Unknown feedback: ${id}`);
+    return record;
+  });
+  if (!feedback.some((item) => eligibleFeedback(item, index.feedback))) {
+    throw new Error("Proposal evidence has not reached the repeated-signal or strong-signal threshold.");
+  }
+  const record = {
+    proposal_id: nextId("PRP", index.proposals, "proposal_id"),
+    status: "proposed",
+    title: spec.title,
+    feedback_ids: [...new Set(spec.feedback_ids)],
+    extension_id: spec.extension_id,
+    requested_risk: spec.requested_risk || "low",
+    hypothesis: spec.hypothesis,
+    baseline: spec.baseline,
+    metrics: spec.metrics,
+    scope: spec.scope,
+    rollback_conditions: spec.rollback_conditions,
+    proposed_at: now(),
+  };
+  if (!(record.requested_risk in RISK_ORDER)) throw new Error(`Unsupported requested risk: ${record.requested_risk}`);
+  record.checksum = checksum(record);
+  record.path = writeRecord(projectRoot, paths, "proposals", record.proposal_id, record, yaml);
+  index.proposals.push(record);
+  decision(projectRoot, paths, index, yaml, "proposal-created", record.proposal_id, "observed", "proposed", {
+    feedback_ids: record.feedback_ids,
+  });
+  writeIndex(paths, index, yaml);
+  return { proposal_id: record.proposal_id, path: record.path, checksum: record.checksum, status: record.status };
+}
+
+function handleRegister(projectRoot, paths, index, options, yaml) {
+  const proposalId = safeId(options.get("--proposal-id"), "proposal_id");
+  const proposal = index.proposals.find((item) => item.proposal_id === proposalId);
+  if (!proposal) throw new Error(`Unknown proposal: ${proposalId}`);
+  if (proposal.status !== "proposed") throw new Error(`Proposal ${proposalId} is ${proposal.status}.`);
+  const source = path.resolve(options.get("--source") || "");
+  if (!isInside(source, projectRoot) || !fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
+    throw new Error("Extension source must be an existing directory inside the project.");
+  }
+  const manifestFile = ["manifest.yaml", "manifest.yml", "manifest.json"]
+    .map((name) => path.join(source, name)).find((file) => fs.existsSync(file));
+  if (!manifestFile) throw new Error("Extension source is missing manifest.yaml, manifest.yml, or manifest.json.");
+  const manifest = loadStructured(manifestFile, yaml);
+  validateManifest(manifest, source);
+  if (manifest.extension_id !== proposal.extension_id) throw new Error("Extension manifest does not match proposal extension_id.");
+  if (index.extensions.some((item) => item.extension_id === manifest.extension_id && item.version === manifest.version)) {
+    throw new Error(`Extension version is already registered: ${manifest.extension_id}@${manifest.version}`);
+  }
+  const effectiveRisk = classifyRisk(manifest, proposal.requested_risk);
+  const destination = path.join(paths.extensions, manifest.extension_id, "versions", manifest.version);
+  if (fs.existsSync(destination)) throw new Error(`Extension destination already exists: ${destination}`);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.cpSync(source, destination, { recursive: true, errorOnExist: true });
+  const digest = directoryChecksum(destination);
+  const record = {
+    extension_id: manifest.extension_id,
+    version: manifest.version,
+    proposal_id: proposalId,
+    state: "proposed",
+    requested_risk: proposal.requested_risk,
+    effective_risk: effectiveRisk,
+    manifest_path: relativeProjectPath(projectRoot, path.join(destination, path.basename(manifestFile))),
+    root_path: relativeProjectPath(projectRoot, destination),
+    checksum: digest,
+    approval: null,
+    blocking_hook_events: manifest.hooks.filter((hook) => hook.decision === "block").map((hook) => hook.event),
+    registered_at: now(),
+    updated_at: now(),
+  };
+  index.extensions.push(record);
+  decision(projectRoot, paths, index, yaml, "extension-registered", `${record.extension_id}@${record.version}`, "proposed", "proposed", {
+    effective_risk: effectiveRisk,
+    checksum: digest,
+  });
+  writeIndex(paths, index, yaml);
+  return { extension_id: record.extension_id, version: record.version, state: record.state, effective_risk: effectiveRisk, checksum: digest };
+}
+
+function handleApprove(projectRoot, paths, index, options, yaml) {
+  const extension = findExtension(index, safeId(options.get("--extension-id"), "extension_id"), safeId(options.get("--version"), "version"));
+  requireChecksum(extension, options.get("--checksum"));
+  if (!new Set(["proposed", "trial"]).has(extension.state)) {
+    throw new Error(`Extension cannot be approved from state ${extension.state}.`);
+  }
+  const confirmationId = safeId(options.get("--confirmation-feedback-id"), "confirmation_feedback_id");
+  const confirmation = index.feedback.find((item) => item.feedback_id === confirmationId);
+  const expectedSubject = `${extension.extension_id}@${extension.version}`;
+  if (!confirmation || confirmation.source_kind !== "user" || !confirmation.explicit_user
+    || confirmation.category !== "extension-approval"
+    || confirmation.confirmation_subject !== expectedSubject
+    || confirmation.confirmation_checksum !== extension.checksum) {
+    throw new Error("Approval requires explicit-user feedback bound to this extension version and checksum.");
+  }
+  extension.approval = {
+    checksum: extension.checksum,
+    source_event_id: confirmation.source_event_id,
+    confirmation_feedback_id: confirmationId,
+    approved_at: now(),
+  };
+  extension.updated_at = now();
+  const proposal = index.proposals.find((item) => item.proposal_id === extension.proposal_id);
+  if (proposal) proposal.approved_at = extension.approval.approved_at;
+  decision(projectRoot, paths, index, yaml, "extension-approved", `${extension.extension_id}@${extension.version}`, extension.state, "approved", extension.approval);
+  writeIndex(paths, index, yaml);
+  return { extension_id: extension.extension_id, version: extension.version, approval: extension.approval };
+}
+
+function experimentFile(paths, extension) {
+  return path.join(paths.root, "experiments", `${extension.extension_id}-${extension.version}.yaml`);
+}
+
+function readExperiment(paths, extension, yaml) {
+  const file = experimentFile(paths, extension);
+  if (!fs.existsSync(file)) {
+    return {
+      experiment_id: `EXP-${extension.extension_id}-${extension.version}`,
+      extension_id: extension.extension_id,
+      version: extension.version,
+      state: "trial",
+      target_executions: 3,
+      target_iterations: 1,
+      observations: [],
+      started_at: now(),
+    };
+  }
+  return yaml.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeExperiment(paths, experiment, yaml) {
+  experiment.checksum = checksum(experiment);
+  atomicWrite(experimentFile(paths, experiment), yaml.stringify(experiment, { lineWidth: 0 }));
+}
+
+function handleEnable(projectRoot, paths, index, options, yaml) {
+  const extension = findExtension(index, safeId(options.get("--extension-id"), "extension_id"), safeId(options.get("--version"), "version"));
+  requireChecksum(extension, options.get("--checksum"));
+  const safePoint = requireSafePoint(projectRoot, options);
+  const targetState = options.get("--state") || "trial";
+  if (!new Set(["trial", "active"]).has(targetState)) throw new Error("Enable state must be trial or active.");
+  if (targetState === "trial" && extension.state !== "proposed") {
+    throw new Error(`Extension can enter trial only from proposed, not ${extension.state}.`);
+  }
+  if (targetState === "active") {
+    if (extension.state !== "trial") throw new Error(`Extension can become active only from trial, not ${extension.state}.`);
+    const experiment = readExperiment(paths, extension, yaml);
+    if (experiment.state !== "awaiting-approval") {
+      throw new Error("Extension can become active only after its trial window passes.");
+    }
+  }
+  if (extension.effective_risk !== "low" && !hasValidApproval(index, extension)) {
+    throw new Error(`Extension ${extension.extension_id}@${extension.version} requires checksum-bound human approval.`);
+  }
+  if (targetState === "active" && !hasValidApproval(index, extension)) {
+    throw new Error("Direct activation requires checksum-bound human approval.");
+  }
+  const { manifest } = loadExtensionManifest(projectRoot, extension, yaml);
+  const capabilityKeys = new Set(Array.isArray(manifest.capability_keys) ? manifest.capability_keys : []);
+  const declaredConflicts = new Set(Array.isArray(manifest.conflicts_with) ? manifest.conflicts_with : []);
+  for (const other of index.extensions.filter((item) => item !== extension && (item.state === "trial" || item.state === "active"))) {
+    const { manifest: otherManifest } = loadExtensionManifest(projectRoot, other, yaml);
+    const otherKeys = new Set(Array.isArray(otherManifest.capability_keys) ? otherManifest.capability_keys : []);
+    const otherConflicts = new Set(Array.isArray(otherManifest.conflicts_with) ? otherManifest.conflicts_with : []);
+    const conflicts = declaredConflicts.has(other.extension_id)
+      || otherConflicts.has(extension.extension_id)
+      || [...capabilityKeys].some((key) => otherKeys.has(key));
+    if (!conflicts) continue;
+    const priority = extension.approval ? 2 : 1;
+    const otherPriority = other.approval ? 2 : 1;
+    if (priority === otherPriority && priority === 2) {
+      throw new Error(`Approved extensions conflict at equal precedence: ${extension.extension_id} and ${other.extension_id}.`);
+    }
+    const disabled = priority > otherPriority ? other : extension;
+    const winner = disabled === extension ? other : extension;
+    disabled.state = "disabled";
+    disabled.reason = `conflicts with higher-precedence extension ${winner.extension_id}@${winner.version}`;
+    disabled.updated_at = now();
+    decision(projectRoot, paths, index, yaml, "extension-conflict", `${disabled.extension_id}@${disabled.version}`, "proposed", "disabled", {
+      winner: `${winner.extension_id}@${winner.version}`,
+    });
+    if (disabled === extension) {
+      writeIndex(paths, index, yaml);
+      return { extension_id: extension.extension_id, version: extension.version, state: "disabled", conflict_with: winner.extension_id };
+    }
+  }
+  const previous = extension.state;
+  extension.state = targetState;
+  extension.updated_at = now();
+  extension.effective_from = { safe_point: safePoint, boundary: "next-task-or-version", decided_at: extension.updated_at };
+  if (targetState === "trial") writeExperiment(paths, readExperiment(paths, extension, yaml), yaml);
+  decision(projectRoot, paths, index, yaml, "extension-enabled", `${extension.extension_id}@${extension.version}`, previous, targetState, {
+    checksum: extension.checksum,
+    automatic: extension.effective_risk === "low" && !extension.approval,
+    effective_from: extension.effective_from,
+  });
+  writeIndex(paths, index, yaml);
+  return { extension_id: extension.extension_id, version: extension.version, state: extension.state, effective_risk: extension.effective_risk };
+}
+
+function handleEvaluate(projectRoot, paths, index, options, yaml) {
+  const safePoint = requireSafePoint(projectRoot, options);
+  clearPending(paths);
+  if (!options.has("--extension-id")) {
+    const eligible = index.feedback.filter((item) => eligibleFeedback(item, index.feedback));
+    appendRuntimeEvent(paths, {
+      schema_version: 1,
+      event_id: `EVT-EVALUATION-${Date.now()}`,
+      idempotency_key: `evaluation:${index.revision}:${safePoint}`,
+      event_type: "evaluation-due",
+      occurred_at: now(),
+      scope: { safe_point: safePoint },
+      payload: { eligible_feedback_ids: eligible.map((item) => item.feedback_id) },
+    });
+    return { safe_point: safePoint, eligible_feedback: eligible.map((item) => ({ feedback_id: item.feedback_id, signal_key: item.signal_key })) };
+  }
+  const extension = findExtension(index, safeId(options.get("--extension-id"), "extension_id"), safeId(options.get("--version"), "version"));
+  if (extension.state !== "trial") throw new Error(`Extension is not in trial: ${extension.extension_id}@${extension.version}`);
+  const installedRoot = path.join(projectRoot, extension.root_path);
+  if (!fs.existsSync(installedRoot) || directoryChecksum(installedRoot) !== extension.checksum) {
+    const previous = extension.state;
+    extension.state = "disabled";
+    extension.reason = "extension checksum verification failed";
+    extension.updated_at = now();
+    decision(projectRoot, paths, index, yaml, "extension-quarantined", `${extension.extension_id}@${extension.version}`, previous, "disabled", {
+      reason: extension.reason,
+    });
+    writeIndex(paths, index, yaml);
+    return { extension_id: extension.extension_id, version: extension.version, state: extension.state, quarantined: true };
+  }
+  const metricResult = options.get("--metric-result");
+  if (!METRIC_RESULTS.has(metricResult)) throw new Error(`Unsupported metric result: ${metricResult}`);
+  const eventId = safeId(options.get("--event-id"), "event_id");
+  const experiment = readExperiment(paths, extension, yaml);
+  if (!experiment.observations.some((item) => item.event_id === eventId)) {
+    experiment.observations.push({
+      event_id: eventId,
+      safe_point: safePoint,
+      iteration_id: options.get("--iteration-id") || null,
+      result: metricResult,
+      observed_at: now(),
+    });
+  }
+  const previous = extension.state;
+  if (experiment.observations.some((item) => item.result === "worsened" || item.result === "failure")) {
+    experiment.state = "rolled-back";
+    extension.state = "rolled-back";
+  } else {
+    const iterations = new Set(experiment.observations.map((item) => item.iteration_id).filter(Boolean));
+    const windowComplete = experiment.observations.length >= experiment.target_executions
+      || (safePoint === "version" && iterations.size >= experiment.target_iterations);
+    if (windowComplete) {
+      experiment.state = extension.effective_risk === "low" ? "active" : "awaiting-approval";
+      if (extension.effective_risk === "low") extension.state = "active";
+    }
+  }
+  extension.updated_at = now();
+  experiment.completed_at = experiment.state === "trial" ? null : now();
+  writeExperiment(paths, experiment, yaml);
+  if (extension.state !== previous) {
+    decision(projectRoot, paths, index, yaml, "trial-evaluated", `${extension.extension_id}@${extension.version}`, previous, extension.state, {
+      observations: experiment.observations.length,
+      experiment_state: experiment.state,
+    });
+  }
+  writeIndex(paths, index, yaml);
+  return { extension_id: extension.extension_id, version: extension.version, state: extension.state, experiment_state: experiment.state };
+}
+
+function handleTerminal(projectRoot, paths, index, options, yaml, command) {
+  const extension = findExtension(index, safeId(options.get("--extension-id"), "extension_id"), safeId(options.get("--version"), "version"));
+  requireChecksum(extension, options.get("--checksum"));
+  const previous = extension.state;
+  let target = command === "rollback" ? "rolled-back" : options.get("--disposition") || "disabled";
+  if (!new Set(["disabled", "expired", "superseded", "rolled-back"]).has(target)) throw new Error(`Unsupported terminal state: ${target}`);
+  if (command === "rollback" && !new Set(["trial", "active"]).has(previous)) {
+    throw new Error(`Extension cannot roll back from state ${previous}.`);
+  }
+  if (command === "disable" && target === "rolled-back") {
+    throw new Error("Use rollback to enter rolled-back state.");
+  }
+  if (target === "disabled" && !new Set(["proposed", "trial", "active"]).has(previous)) {
+    throw new Error(`Extension cannot be disabled from state ${previous}.`);
+  }
+  if (target === "superseded") {
+    const replacement = requireText(options.get("--superseded-by"), "superseded_by");
+    const match = replacement.match(/^([^@]+)@(.+)$/);
+    if (!match || match[1] !== extension.extension_id) {
+      throw new Error("superseded_by must reference another registered version of the same extension.");
+    }
+    const successor = findExtension(index, safeId(match[1], "superseded_extension_id"), safeId(match[2], "superseded_version"));
+    if (successor === extension || successor.superseded_by === `${extension.extension_id}@${extension.version}`) {
+      throw new Error("superseded_by would create an invalid replacement chain.");
+    }
+  }
+  extension.state = target;
+  extension.superseded_by = options.get("--superseded-by") || null;
+  extension.reason = requireText(options.get("--reason"), "reason");
+  extension.updated_at = now();
+  decision(projectRoot, paths, index, yaml, `extension-${command}`, `${extension.extension_id}@${extension.version}`, previous, target, {
+    reason: extension.reason,
+    superseded_by: extension.superseded_by,
+  });
+  writeIndex(paths, index, yaml);
+  return { extension_id: extension.extension_id, version: extension.version, state: target };
+}
+
+function handleReject(projectRoot, paths, index, options, yaml) {
+  const proposalId = safeId(options.get("--proposal-id"), "proposal_id");
+  const proposal = index.proposals.find((item) => item.proposal_id === proposalId);
+  if (!proposal) throw new Error(`Unknown proposal: ${proposalId}`);
+  if (proposal.status !== "proposed") throw new Error(`Proposal cannot be rejected from status ${proposal.status}.`);
+  if (index.extensions.some((item) => item.proposal_id === proposalId)) {
+    throw new Error("A proposal with a registered extension version cannot be rejected.");
+  }
+  const previous = proposal.status;
+  proposal.status = "rejected";
+  proposal.rejected_at = now();
+  proposal.reason = requireText(options.get("--reason"), "reason");
+  decision(projectRoot, paths, index, yaml, "proposal-rejected", proposalId, previous, "rejected", { reason: proposal.reason });
+  writeIndex(paths, index, yaml);
+  return { proposal_id: proposalId, status: proposal.status };
+}
+
+function loadExtensionManifest(projectRoot, extension, yaml) {
+  const file = path.join(projectRoot, extension.manifest_path);
+  const manifest = loadStructured(file, yaml);
+  const root = path.join(projectRoot, extension.root_path);
+  validateManifest(manifest, root);
+  return { manifest, root };
+}
+
+function executeScript(root, hook, event) {
+  const entrypoint = path.resolve(root, hook.entrypoint);
+  const result = spawnSync(process.execPath, [entrypoint], {
+    cwd: root,
+    input: JSON.stringify(event),
+    encoding: "utf8",
+    timeout: Math.min(Number(hook.timeout_seconds || 5), 10) * 1_000,
+    windowsHide: true,
+    env: {
+      PATH: process.env.PATH || "",
+      SystemRoot: process.env.SystemRoot || "",
+      TEMP: process.env.TEMP || "",
+      TMP: process.env.TMP || "",
+      AI_DELIVERY_HOOK_EVENT: event.event_type,
+    },
+  });
+  if (result.error || result.status !== 0) throw new Error(result.error?.message || result.stderr || `Hook exited ${result.status}`);
+  const output = JSON.parse(result.stdout || "{}");
+  return normalizeHookOutcome(output);
+}
+
+function dispatchHookEvent(projectRoot, paths, index, rawEvent, yaml) {
+  const event = redact(rawEvent);
+  if (event.schema_version !== 1) throw new Error("Hook event schema_version must be 1.");
+  safeId(event.event_id, "event_id");
+  safeId(event.idempotency_key, "idempotency_key");
+  if (!HOOK_EVENTS.has(event.event_type)) throw new Error(`Unsupported Hook event: ${event.event_type}`);
+  const processed = readProcessed(paths);
+  if (processed.keys[event.idempotency_key]) return { ...processed.keys[event.idempotency_key].result, deduplicated: true };
+  appendRuntimeEvent(paths, event);
+  const outcomes = [];
+  let indexChanged = false;
+  for (const extension of index.extensions.filter((item) => item.state === "active" || item.state === "trial")) {
+    const approved = hasValidApproval(index, extension);
+    const failClosed = approved
+      && Array.isArray(extension.blocking_hook_events)
+      && extension.blocking_hook_events.includes(event.event_type);
+    try {
+      if (extension.effective_risk !== "low" && !approved) {
+        throw new Error("extension approval receipt is missing or invalid");
+      }
+      if (directoryChecksum(path.join(projectRoot, extension.root_path)) !== extension.checksum) {
+        throw new Error("extension checksum mismatch");
+      }
+      const { manifest, root } = loadExtensionManifest(projectRoot, extension, yaml);
+      const matchingHooks = manifest.hooks.filter((item) => item.event === event.event_type);
+      for (const hook of matchingHooks) {
+        let outcome = hook.entrypoint
+          ? executeScript(root, hook, event)
+          : normalizeHookOutcome({
+            decision: hook.decision || "pass",
+            messages: hook.message ? [hook.message] : [],
+            evidence_refs: hook.evidence_refs || [],
+          });
+        if (outcome.decision === "block" && (extension.state === "trial" && extension.effective_risk === "low" || !approved)) {
+          outcome = { ...outcome, decision: "warn", messages: [...outcome.messages, "未获人工批准的扩展不能阻断流程。"] };
+        }
+        if (outcome.decision === "block" && !event.event_type.endsWith(".before")) {
+          outcome = { ...outcome, decision: "warn", messages: [...outcome.messages, "仅 before Hook 可以阻断流程。"] };
+        }
+        outcomes.push(redact({ extension_id: extension.extension_id, version: extension.version, ...outcome }));
+      }
+    } catch (error) {
+      const previous = extension.state;
+      extension.state = previous === "trial" ? "rolled-back" : "disabled";
+      extension.reason = `Hook failure: ${redact(error.message)}`;
+      extension.updated_at = now();
+      decision(projectRoot, paths, index, yaml, "extension-hook-failed", `${extension.extension_id}@${extension.version}`, previous, extension.state, {
+        event_id: event.event_id,
+        event_type: event.event_type,
+        reason: extension.reason,
+      });
+      indexChanged = true;
+      outcomes.push(redact({
+        extension_id: extension.extension_id,
+        version: extension.version,
+        decision: failClosed ? "block" : "warn",
+        messages: [`Hook 执行失败：${error.message}`],
+        evidence_refs: [],
+      }));
+    }
+  }
+  const result = {
+    schema_version: 1,
+    event_id: event.event_id,
+    decision: outcomes.some((item) => item.decision === "block") ? "block"
+      : outcomes.some((item) => item.decision === "warn") ? "warn" : "pass",
+    messages: redact(outcomes.flatMap((item) => item.messages)),
+    evidence_refs: redact([...new Set(outcomes.flatMap((item) => item.evidence_refs))]),
+    outcomes,
+    deduplicated: false,
+  };
+  if (outcomes.length) {
+    const record = {
+      schema_version: 1,
+      event_id: event.event_id,
+      event_type: event.event_type,
+      decision: result.decision,
+      outcomes,
+      recorded_at: now(),
+    };
+    record.checksum = checksum(record);
+    writeRecord(projectRoot, paths, path.join("experiments", "hook-results"), event.event_id, redact(record), yaml);
+  }
+  if (indexChanged) writeIndex(paths, index, yaml);
+  rememberProcessed(paths, event.idempotency_key, result);
+  return result;
+}
+
+function handleHook(projectRoot, paths, index, options, yaml) {
+  const input = options.get("--input");
+  const event = input === "-"
+    ? JSON.parse(fs.readFileSync(0, "utf8"))
+    : loadStructured(path.resolve(input || ""), yaml);
+  return dispatchHookEvent(projectRoot, paths, index, event, yaml);
+}
+
+function handleVerify(projectRoot, paths, index, yaml) {
+  const issues = [];
+  let indexChanged = false;
+  for (const extension of index.extensions) {
+    try {
+      const root = path.join(projectRoot, extension.root_path);
+      if (!fs.existsSync(root)) throw new Error("extension directory is missing");
+      if (directoryChecksum(root) !== extension.checksum) throw new Error("checksum mismatch");
+      loadExtensionManifest(projectRoot, extension, yaml);
+      if (extension.approval && !hasValidApproval(index, extension)) throw new Error("approval receipt or checksum mismatch");
+    } catch (error) {
+      issues.push({ extension_id: extension.extension_id, version: extension.version, severity: "warning", message: error.message });
+      if (extension.state === "trial" || extension.state === "active") {
+        const previous = extension.state;
+        extension.state = "disabled";
+        extension.reason = `verification failed: ${redact(error.message)}`;
+        extension.updated_at = now();
+        decision(projectRoot, paths, index, yaml, "extension-quarantined", `${extension.extension_id}@${extension.version}`, previous, "disabled", {
+          reason: extension.reason,
+        });
+        indexChanged = true;
+      }
+    }
+  }
+  if (indexChanged) writeIndex(paths, index, yaml);
+  return { ok: issues.length === 0, schema_version: index.schema_version, revision: index.revision, issues };
+}
+
+function handleExport(projectRoot, paths, index, options, yaml) {
+  const extension = findExtension(index, safeId(options.get("--extension-id"), "extension_id"), safeId(options.get("--version"), "version"));
+  const bundle = {
+    schema_version: 1,
+    bundle_id: `PROMOTION-${extension.extension_id}-${extension.version}`,
+    extension_id: extension.extension_id,
+    version: extension.version,
+    effective_risk: extension.effective_risk,
+    checksum: extension.checksum,
+    state: extension.state,
+    proposal_id: extension.proposal_id,
+    exported_at: now(),
+    contains_executable_code: extension.effective_risk === "high",
+    transfer_status: "local-only",
+  };
+  const file = path.join(paths.root, "promotion", `${bundle.bundle_id}.yaml`);
+  atomicWrite(file, yaml.stringify(bundle, { lineWidth: 0 }));
+  return { bundle_id: bundle.bundle_id, path: relativeProjectPath(projectRoot, file), checksum: checksum(bundle) };
+}
+
+export function executeEvolutionCommand(argv, dependencies) {
+  const yaml = dependencies?.yaml;
+  if (!yaml?.parse || !yaml?.stringify) throw new Error("Evolution CLI requires YAML parse and stringify functions.");
+  const { positional, options, flags } = parseArgs(argv);
+  const projectRoot = path.resolve(options.get("--project") || process.cwd());
+  const paths = evolutionPaths(projectRoot);
+  const index = readIndex(paths, yaml);
+  const [command, subcommand] = positional;
+  if (command === "feedback" && subcommand === "record") return handleFeedback(projectRoot, paths, index, options, flags, yaml);
+  if (command === "propose") return handlePropose(projectRoot, paths, index, options, yaml);
+  if (command === "register") return handleRegister(projectRoot, paths, index, options, yaml);
+  if (command === "approve") return handleApprove(projectRoot, paths, index, options, yaml);
+  if (command === "reject") return handleReject(projectRoot, paths, index, options, yaml);
+  if (command === "enable") return handleEnable(projectRoot, paths, index, options, yaml);
+  if (command === "disable" || command === "rollback") return handleTerminal(projectRoot, paths, index, options, yaml, command);
+  if (command === "evaluate") return handleEvaluate(projectRoot, paths, index, options, yaml);
+  if (command === "hook" && subcommand === "dispatch") return handleHook(projectRoot, paths, index, options, yaml);
+  if (command === "verify") return handleVerify(projectRoot, paths, index, yaml);
+  if (command === "export") return handleExport(projectRoot, paths, index, options, yaml);
+  if (command === "inspect") return index;
+  throw new Error(`Unknown evolution command: ${positional.join(" ") || "(missing)"}`);
+}
+
+export function dispatchEvolutionHookEvent(projectRoot, event, dependencies) {
+  const yaml = dependencies?.yaml;
+  if (!yaml?.parse || !yaml?.stringify) throw new Error("Evolution Hook dispatch requires YAML parse and stringify functions.");
+  const resolvedRoot = path.resolve(projectRoot || process.cwd());
+  const paths = evolutionPaths(resolvedRoot);
+  const index = readIndex(paths, yaml);
+  return dispatchHookEvent(resolvedRoot, paths, index, event, yaml);
+}
+
+export const EVOLUTION_HOOK_PROTOCOL_VERSION = SCHEMA_VERSION;
+export const EVOLUTION_HOOK_EVENTS = [...HOOK_EVENTS];