scene-capability-engine 3.6.64 → 3.6.67

package/lib/semantic/kernel-loader.js

@@ -0,0 +1,881 @@
+const { getSceStateStore } = require('../state/sce-state-store');
+const { publishSemanticLibraryDelta } = require('./shared-publication');
+const {
+  resolveTargetLibrary,
+  buildCapabilityId
+} = require('./capability-contract');
+const { buildSemanticArchiveDecision } = require('./archive-routing');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeNonNegativeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeStringArray(value, fallback = []) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  return value
+    .map((item) => normalizeString(item))
+    .filter(Boolean);
+}
+
+function unique(values = []) {
+  return Array.from(new Set(normalizeStringArray(values, [])));
+}
+
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function tokenize(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return (normalized.match(/[a-z0-9\u4e00-\u9fff]+/g) || [])
+    .filter((item) => item.length > 1);
+}
+
+function isPromotedSemanticStatus(status) {
+  const normalized = normalizeString(status).toLowerCase();
+  return normalized === 'promoted'
+    || normalized === 'promoted-local'
+    || normalized === 'published-shared'
+    || normalized === 'publish_pending';
+}
+
+function computeActivation(prompt, lesson = {}) {
+  const promptTokens = [...new Set(tokenize(prompt))];
+  const lessonBasis = [
+    lesson.title,
+    lesson.summary,
+    lesson.heuristic,
+    lesson.lesson_type,
+    lesson.source_runtime,
+    lesson.fingerprint,
+    JSON.stringify(lesson.evidence || {}),
+    JSON.stringify(lesson.metadata || {})
+  ].join(' ');
+  const lessonTokens = [...new Set(tokenize(lessonBasis))];
+  const matchedTerms = promptTokens.filter((token) => lessonTokens.includes(token));
+  return {
+    lesson_id: lesson.lesson_id,
+    score: matchedTerms.length,
+    matched_terms: matchedTerms
+  };
+}
+
+function getStateStore(projectPath, dependencies = {}) {
+  return dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule,
+    noCache: dependencies.noCache === true
+  });
+}
+
+function readLessonPublishMetadata(lesson = {}) {
+  if (lesson.metadata && typeof lesson.metadata === 'object'
+      && lesson.metadata.publish
+      && typeof lesson.metadata.publish === 'object') {
+    return lesson.metadata.publish;
+  }
+  return {};
+}
+
+function extractObservationIds(lesson = {}, evaluationRun = {}, existingLedger = {}) {
+  const evidence = lesson.evidence && typeof lesson.evidence === 'object' ? lesson.evidence : {};
+  const lineage = existingLedger.lineage && typeof existingLedger.lineage === 'object'
+    ? existingLedger.lineage
+    : {};
+  return unique([
+    ...(Array.isArray(lineage.observation_ids) ? lineage.observation_ids : []),
+    ...normalizeStringArray(evidence.observation_ids, []),
+    normalizeString(evidence.observation_id),
+    ...normalizeStringArray(evaluationRun.observation_ids, [])
+  ]);
+}
+
+function mapLessonStatusToCapabilityStatus(status) {
+  const normalized = normalizeString(status).toLowerCase();
+  if (normalized === 'deprecated') {
+    return 'deprecated';
+  }
+  if (normalized === 'publish_blocked') {
+    return 'quarantined';
+  }
+  if (normalized === 'candidate') {
+    return 'candidate';
+  }
+  return 'active';
+}
+
+function normalizeQualitySignal(value) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (['positive', 'negative', 'mixed', 'unknown'].includes(normalized)) {
+    return normalized;
+  }
+  return 'mixed';
+}
+
+function readLessonMetadata(lesson = {}) {
+  return lesson.metadata && typeof lesson.metadata === 'object'
+    ? lesson.metadata
+    : {};
+}
+
+function readLessonChannelId(lesson = {}) {
+  const metadata = readLessonMetadata(lesson);
+  return normalizeString(metadata.channel_id || metadata.channelId) || null;
+}
+
+function readLessonSessionId(lesson = {}) {
+  const metadata = readLessonMetadata(lesson);
+  return normalizeString(metadata.session_id || metadata.sessionId) || null;
+}
+
+function calculateGovernancePenaltyScore(metrics = {}) {
+  const rewriteCount = normalizeNonNegativeInteger(metrics.governance_rewrite_count, 0);
+  const clarifyCount = normalizeNonNegativeInteger(metrics.governance_clarify_count, 0);
+  const narrowCount = normalizeNonNegativeInteger(metrics.governance_narrow_count, 0);
+  const refuseCount = normalizeNonNegativeInteger(metrics.governance_refuse_count, 0);
+  const planningBlocked = normalizeNonNegativeInteger(metrics.governance_planning_blocked_count, 0);
+  const executionBlocked = normalizeNonNegativeInteger(metrics.governance_execution_blocked_count, 0);
+  const governedRate = Number(metrics.governance_governed_rate_percent);
+
+  let penalty = 0;
+  penalty += rewriteCount * 3;
+  penalty += clarifyCount * 2;
+  penalty += narrowCount * 1;
+  penalty += refuseCount * 8;
+  penalty += planningBlocked * 4;
+  penalty += executionBlocked * 8;
+  if (Number.isFinite(governedRate)) {
+    penalty += governedRate / 20;
+  }
+  return Number(clamp(penalty, 0, 40).toFixed(2));
+}
+
+async function summarizeGovernancePressure(scope = {}, store, limit = 200) {
+  if (!store) {
+    return {
+      governance_scope: {
+        project_id: null,
+        channel_id: null,
+        scene_id: null,
+        spec_id: null,
+        limit
+      },
+      governance_total_assessments: 0,
+      governance_governed_count: 0,
+      governance_clarify_count: 0,
+      governance_rewrite_count: 0,
+      governance_narrow_count: 0,
+      governance_refuse_count: 0,
+      governance_planning_blocked_count: 0,
+      governance_execution_blocked_count: 0,
+      governance_governed_rate_percent: 0,
+      governance_penalty_score: 0
+    };
+  }
+
+  const projectId = normalizeString(scope.project_id || scope.projectId) || null;
+  const channelId = normalizeString(scope.channel_id || scope.channelId) || null;
+  const sceneId = normalizeString(scope.scene_id || scope.sceneId) || null;
+  const specId = normalizeString(scope.spec_id || scope.specId) || null;
+  const assessments = await store.listSupremeIntentAssessments({
+    project_id: projectId,
+    channel_id: channelId,
+    scene_id: sceneId,
+    spec_id: specId,
+    limit
+  });
+  const items = Array.isArray(assessments) ? assessments : [];
+  const summarizeAction = (action) => items.filter((item) => normalizeString(item.action) === action).length;
+  const governedCount = items.filter((item) => normalizeString(item.action) !== 'allow').length;
+  const planningBlockedCount = items.filter((item) => item.planning_allowed !== true).length;
+  const executionBlockedCount = items.filter((item) => item.execution_allowed !== true).length;
+  const metrics = {
+    governance_scope: {
+      project_id: projectId,
+      channel_id: channelId,
+      scene_id: sceneId,
+      spec_id: specId,
+      limit
+    },
+    governance_total_assessments: items.length,
+    governance_governed_count: governedCount,
+    governance_clarify_count: summarizeAction('clarify'),
+    governance_rewrite_count: summarizeAction('rewrite'),
+    governance_narrow_count: summarizeAction('narrow'),
+    governance_refuse_count: summarizeAction('refuse'),
+    governance_planning_blocked_count: planningBlockedCount,
+    governance_execution_blocked_count: executionBlockedCount,
+    governance_governed_rate_percent: items.length > 0
+      ? Number(((governedCount / items.length) * 100).toFixed(2))
+      : 0
+  };
+  return {
+    ...metrics,
+    governance_penalty_score: calculateGovernancePenaltyScore(metrics)
+  };
+}
+
+function calculateRankScore(options = {}) {
+  const confidence = Number(options.confidence);
+  const evaluationScore = Number(options.evaluation_score ?? options.evaluationScore);
+  const activationSuccessCount = normalizeNonNegativeInteger(options.activation_success_count ?? options.activationSuccessCount, 0);
+  const activationMixedCount = normalizeNonNegativeInteger(options.activation_mixed_count ?? options.activationMixedCount, 0);
+  const activationNegativeCount = normalizeNonNegativeInteger(options.activation_negative_count ?? options.activationNegativeCount, 0);
+  const quarantineCount = normalizeNonNegativeInteger(options.quarantine_count ?? options.quarantineCount, 0);
+  const governancePenaltyScore = Number.isFinite(Number(
+    options.governance_penalty_score ?? options.governancePenaltyScore
+  ))
+    ? Number(options.governance_penalty_score ?? options.governancePenaltyScore)
+    : calculateGovernancePenaltyScore(options);
+
+  let score = 40;
+  if (Number.isFinite(confidence)) {
+    score += confidence * 20;
+  }
+  if (Number.isFinite(evaluationScore)) {
+    score += evaluationScore / 10;
+  }
+  score += activationSuccessCount * 12;
+  score += activationMixedCount * 3;
+  score -= activationNegativeCount * 15;
+  score -= quarantineCount * 20;
+  score -= governancePenaltyScore;
+  return Number(clamp(score, 0, 100).toFixed(2));
+}
+
+function shouldQuarantineCapability(metrics = {}) {
+  const negativeCount = normalizeNonNegativeInteger(metrics.activation_negative_count, 0);
+  const successCount = normalizeNonNegativeInteger(metrics.activation_success_count, 0);
+  return negativeCount >= 2 && negativeCount > successCount;
+}
+
+async function syncSemanticCapabilityLedger(lesson = {}, options = {}, dependencies = {}) {
+  const lessonId = normalizeString(lesson.lesson_id || options.lesson_id || options.lessonId);
+  if (!lessonId) {
+    return null;
+  }
+
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+  const evaluationRun = options.evaluationRun && typeof options.evaluationRun === 'object'
+    ? options.evaluationRun
+    : null;
+  const capabilityId = normalizeString(options.capability_id || options.capabilityId) || buildCapabilityId(lesson);
+  const existingLedger = await store.getSemanticCapabilityLedger(capabilityId);
+  const publish = readLessonPublishMetadata(lesson);
+  const nowIso = normalizeString(options.updated_at || options.updatedAt) || new Date().toISOString();
+  const archive = buildSemanticArchiveDecision(lesson);
+  const targetLibrary = normalizeString(options.target_library || options.targetLibrary)
+    || normalizeString(archive.target_library)
+    || resolveTargetLibrary(lesson);
+  const capabilityStatus = normalizeString(options.capability_status || options.capabilityStatus)
+    || mapLessonStatusToCapabilityStatus(lesson.status);
+  const publishState = normalizeString(options.publish_state || options.publishState || publish.publish_state)
+    || normalizeString(existingLedger && existingLedger.publish_state)
+    || 'pending';
+  const governanceMetrics = await summarizeGovernancePressure({
+    project_id: normalizeString(lesson.project_id) || normalizeString(existingLedger && existingLedger.project_id),
+    channel_id: normalizeString(options.channel_id || options.channelId)
+      || readLessonChannelId(lesson)
+      || normalizeString(existingLedger && existingLedger.channel_id),
+    scene_id: normalizeString(lesson.scene_id) || normalizeString(existingLedger && existingLedger.scene_id),
+    spec_id: normalizeString(lesson.spec_id) || normalizeString(existingLedger && existingLedger.spec_id)
+  }, store);
+
+  const metrics = {
+    ...(existingLedger && existingLedger.metrics && typeof existingLedger.metrics === 'object'
+      ? existingLedger.metrics
+      : {}),
+    confidence: Number.isFinite(Number(lesson.confidence)) ? Number(lesson.confidence) : null,
+    evaluation_score: evaluationRun && Number.isFinite(Number(evaluationRun.score))
+      ? Number(evaluationRun.score)
+      : Number(existingLedger && existingLedger.metrics && existingLedger.metrics.evaluation_score),
+    promotion_release_gate: normalizeString(options.release_gate || options.releaseGate)
+      || normalizeString(evaluationRun && evaluationRun.release_gate)
+      || normalizeString(existingLedger && existingLedger.metrics && existingLedger.metrics.promotion_release_gate)
+      || null,
+    activation_count: normalizeNonNegativeInteger(
+      options.activation_count ?? options.activationCount ?? (existingLedger && existingLedger.activation_count),
+      0
+    ),
+    activation_success_count: normalizeNonNegativeInteger(
+      options.activation_success_count ?? options.activationSuccessCount ?? (existingLedger && existingLedger.activation_success_count),
+      0
+    ),
+    activation_mixed_count: normalizeNonNegativeInteger(
+      options.activation_mixed_count ?? options.activationMixedCount ?? (existingLedger && existingLedger.activation_mixed_count),
+      0
+    ),
+    activation_negative_count: normalizeNonNegativeInteger(
+      options.activation_negative_count ?? options.activationNegativeCount ?? (existingLedger && existingLedger.activation_negative_count),
+      0
+    ),
+    quarantine_count: normalizeNonNegativeInteger(
+      options.quarantine_count ?? options.quarantineCount ?? (existingLedger && existingLedger.quarantine_count),
+      0
+    ),
+    last_activated_at: normalizeString(options.last_activated_at || options.lastActivatedAt)
+      || normalizeString(existingLedger && existingLedger.last_activated_at)
+      || null,
+    last_quality_signal: normalizeString(options.last_quality_signal || options.lastQualitySignal)
+      || normalizeString(existingLedger && existingLedger.last_quality_signal)
+      || null,
+    last_runtime: normalizeString(options.last_runtime || options.lastRuntime)
+      || normalizeString(existingLedger && existingLedger.last_runtime)
+      || null,
+    archive_class: normalizeString(archive.archive_class)
+      || normalizeString(existingLedger && existingLedger.metrics && existingLedger.metrics.archive_class)
+      || null,
+    archive_reuse_scope: normalizeString(archive.reuse_scope)
+      || normalizeString(existingLedger && existingLedger.metrics && existingLedger.metrics.archive_reuse_scope)
+      || null,
+    archive_reason_code: normalizeString(archive.reason_code)
+      || normalizeString(existingLedger && existingLedger.metrics && existingLedger.metrics.archive_reason_code)
+      || null,
+    ...governanceMetrics
+  };
+
+  const publication = {
+    ...(existingLedger && existingLedger.publication && typeof existingLedger.publication === 'object'
+      ? existingLedger.publication
+      : {}),
+    ...(publish && typeof publish === 'object' ? publish : {}),
+    consent_model: normalizeString(publish.consent_model)
+      || normalizeString(existingLedger && existingLedger.publication && existingLedger.publication.consent_model)
+      || 'adopt-implied',
+    publish_required: publish.publish_required === true
+      || Boolean(existingLedger && existingLedger.publication && existingLedger.publication.publish_required),
+    publish_state: publishState,
+    queued_at: normalizeString(publish.queued_at)
+      || normalizeString(existingLedger && existingLedger.publication && existingLedger.publication.queued_at)
+      || null,
+    target_library: targetLibrary,
+    archive,
+    publish_target_libraries: unique([
+      ...(Array.isArray(publish.publish_target_libraries) ? publish.publish_target_libraries : []),
+      ...(Array.isArray(existingLedger && existingLedger.publication && existingLedger.publication.publish_target_libraries)
+        ? existingLedger.publication.publish_target_libraries
+        : []),
+      targetLibrary
+    ])
+  };
+
+  const lineage = {
+    ...(existingLedger && existingLedger.lineage && typeof existingLedger.lineage === 'object'
+      ? existingLedger.lineage
+      : {}),
+    lesson_id: lessonId,
+    fingerprint: normalizeString(lesson.fingerprint)
+      || normalizeString(existingLedger && existingLedger.lineage && existingLedger.lineage.fingerprint)
+      || null,
+    observation_ids: extractObservationIds(lesson, evaluationRun || {}, existingLedger || {}),
+    evaluation_run_id: normalizeString(options.evaluation_run_id || options.evaluationRunId)
+      || normalizeString(evaluationRun && evaluationRun.evaluation_run_id)
+      || normalizeString(existingLedger && existingLedger.evaluation_run_id)
+      || null,
+    source_runtime: normalizeString(lesson.source_runtime)
+      || normalizeString(existingLedger && existingLedger.lineage && existingLedger.lineage.source_runtime)
+      || null,
+    target_library: targetLibrary,
+    archive
+  };
+
+  const rankScore = calculateRankScore({
+    confidence: metrics.confidence,
+    evaluation_score: metrics.evaluation_score,
+    activation_success_count: metrics.activation_success_count,
+    activation_mixed_count: metrics.activation_mixed_count,
+    activation_negative_count: metrics.activation_negative_count,
+    quarantine_count: metrics.quarantine_count,
+    governance_penalty_score: metrics.governance_penalty_score
+  });
+
+  return store.upsertSemanticCapabilityLedger({
+    capability_id: capabilityId,
+    lesson_id: lessonId,
+    evaluation_run_id: lineage.evaluation_run_id,
+    project_id: normalizeString(lesson.project_id) || normalizeString(existingLedger && existingLedger.project_id) || null,
+    channel_id: normalizeString(options.channel_id || options.channelId)
+      || readLessonChannelId(lesson)
+      || normalizeString(existingLedger && existingLedger.channel_id)
+      || null,
+    session_id: normalizeString(options.session_id || options.sessionId)
+      || readLessonSessionId(lesson)
+      || normalizeString(existingLedger && existingLedger.session_id)
+      || null,
+    scene_id: normalizeString(lesson.scene_id) || normalizeString(existingLedger && existingLedger.scene_id) || null,
+    spec_id: normalizeString(lesson.spec_id) || normalizeString(existingLedger && existingLedger.spec_id) || null,
+    target_library: targetLibrary,
+    capability_status: capabilityStatus,
+    publish_state: publishState,
+    activation_count: metrics.activation_count,
+    activation_success_count: metrics.activation_success_count,
+    activation_mixed_count: metrics.activation_mixed_count,
+    activation_negative_count: metrics.activation_negative_count,
+    quarantine_count: metrics.quarantine_count,
+    last_activated_at: metrics.last_activated_at,
+    last_quality_signal: metrics.last_quality_signal,
+    last_runtime: metrics.last_runtime,
+    rank_score: rankScore,
+    lineage,
+    publication,
+    metrics,
+    created_at: normalizeString(existingLedger && existingLedger.created_at) || nowIso,
+    updated_at: nowIso
+  });
+}
+
+async function applySemanticCapabilityQuarantine(lesson = {}, options = {}, dependencies = {}) {
+  const lessonId = normalizeString(lesson.lesson_id || options.lesson_id || options.lessonId);
+  if (!lessonId) {
+    return null;
+  }
+
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+  const existingLesson = lesson.lesson_id ? lesson : await store.getSemanticLessonCandidate(lessonId);
+  if (!existingLesson) {
+    return null;
+  }
+
+  const nowIso = normalizeString(options.updated_at || options.updatedAt) || new Date().toISOString();
+  const reason = normalizeString(options.reason) || 'native-quality-regression';
+  const actor = normalizeString(options.actor) || 'sce-native';
+  const existingPublish = readLessonPublishMetadata(existingLesson);
+
+  return store.upsertSemanticLessonCandidate({
+    ...existingLesson,
+    status: normalizeString(existingLesson.status) === 'deprecated' ? 'deprecated' : 'publish_blocked',
+    metadata: {
+      ...(existingLesson.metadata || {}),
+      publish: {
+        ...existingPublish,
+        consent_model: normalizeString(existingPublish.consent_model) || 'adopt-implied',
+        publish_required: existingPublish.publish_required === true,
+        publish_state: 'blocked',
+        blocked_at: nowIso,
+        blocked_reason: reason
+      },
+      quarantine: {
+        quarantined_at: nowIso,
+        quarantined_by: actor,
+        reason
+      }
+    },
+    updated_at: nowIso
+  });
+}
+
+async function listPromotedSemanticBehaviors(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+  const projectId = normalizeString(options.project_id || options.projectId);
+  const channelId = normalizeString(options.channel_id || options.channelId);
+  const sceneId = normalizeString(options.scene_id || options.sceneId);
+  const specId = normalizeString(options.spec_id || options.specId);
+  const limit = normalizeInteger(options.limit, 20);
+
+  let items = await store.listSemanticLessonCandidates({
+    project_id: projectId,
+    limit: limit > 0 ? Math.max(limit * 4, 20) : 20
+  });
+  items = Array.isArray(items) ? items : [];
+  items = items.filter((item) => {
+    if (!isPromotedSemanticStatus(item.status)) {
+      return false;
+    }
+    if (sceneId && normalizeString(item.scene_id) !== sceneId) {
+      return false;
+    }
+    if (specId && normalizeString(item.spec_id) !== specId) {
+      return false;
+    }
+    if (channelId && readLessonChannelId(item) !== channelId) {
+      return false;
+    }
+    return true;
+  });
+  if (limit > 0) {
+    items = items.slice(0, limit);
+  }
+  return items;
+}
+
+async function activatePromotedSemanticBehaviors(prompt, options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+  const behaviors = await listPromotedSemanticBehaviors(options, {
+    ...dependencies,
+    projectPath,
+    stateStore: store
+  });
+  const ranked = await Promise.all(behaviors.map(async (item) => {
+    const capabilityId = buildCapabilityId(item);
+    const ledger = await store.getSemanticCapabilityLedger(capabilityId);
+    return {
+      lesson: item,
+      capability_id: capabilityId,
+      ledger,
+      activation: computeActivation(prompt, item)
+    };
+  }));
+
+  return ranked
+    .map((item) => ({
+      ...item,
+      activation: {
+        ...item.activation,
+        weighted_score: Number((
+          Number(item.activation.score || 0)
+          + ((Number(item.ledger && item.ledger.rank_score) || 0) / 25)
+        ).toFixed(2))
+      }
+    }))
+    .filter((item) => item.activation.score > 0)
+    .sort((left, right) => {
+      if (right.activation.weighted_score !== left.activation.weighted_score) {
+        return right.activation.weighted_score - left.activation.weighted_score;
+      }
+      if (right.activation.score !== left.activation.score) {
+        return right.activation.score - left.activation.score;
+      }
+      const leftRank = Number(left.ledger && left.ledger.rank_score) || 0;
+      const rightRank = Number(right.ledger && right.ledger.rank_score) || 0;
+      if (rightRank !== leftRank) {
+        return rightRank - leftRank;
+      }
+      return `${left.lesson.lesson_id}`.localeCompare(`${right.lesson.lesson_id}`);
+    })
+    .map((item) => ({
+      ...item.lesson,
+      capability_id: item.capability_id,
+      rank_score: Number(item.ledger && item.ledger.rank_score) || 0,
+      activation: item.activation
+    }));
+}
+
+async function promoteSemanticLessonCandidate(options = {}, dependencies = {}) {
+  const lessonId = normalizeString(options.lesson_id || options.lessonId);
+  const evaluationRunId = normalizeString(options.evaluation_run_id || options.evaluationRunId);
+  if (!lessonId) {
+    throw new Error('lesson_id is required');
+  }
+  if (!evaluationRunId) {
+    throw new Error('evaluation_run_id is required');
+  }
+
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+
+  const lesson = await store.getSemanticLessonCandidate(lessonId);
+  if (!lesson) {
+    throw new Error(`Semantic lesson candidate not found: ${lessonId}`);
+  }
+  const evaluationRun = await store.getSemanticEvaluationRun(evaluationRunId);
+  if (!evaluationRun) {
+    throw new Error(`Semantic evaluation run not found: ${evaluationRunId}`);
+  }
+  if (normalizeString(evaluationRun.verdict) !== 'passed') {
+    throw new Error(`Evaluation run ${evaluationRunId} did not pass`);
+  }
+  if (evaluationRun.regression_detected === true) {
+    throw new Error(`Evaluation run ${evaluationRunId} is marked as regression`);
+  }
+  if (evaluationRun.governance && evaluationRun.governance.promotion_gate_passed === false) {
+    throw new Error(`Evaluation run ${evaluationRunId} did not pass promotion gate`);
+  }
+
+  const nowIso = new Date().toISOString();
+  const actor = normalizeString(options.actor) || null;
+  const releaseGate = normalizeString(options.release_gate || options.releaseGate)
+    || normalizeString(evaluationRun.release_gate)
+    || null;
+  const archive = buildSemanticArchiveDecision(lesson);
+
+  const promotedLesson = await store.upsertSemanticLessonCandidate({
+    ...lesson,
+    status: 'publish_pending',
+    evidence: {
+      ...(lesson.evidence || {}),
+      promotion: {
+        evaluation_run_id: evaluationRun.evaluation_run_id,
+        score: evaluationRun.score,
+        threshold: evaluationRun.threshold,
+        expected_terms: evaluationRun.evidence
+          && evaluationRun.evidence.replay_dataset
+          && Array.isArray(evaluationRun.evidence.replay_dataset.expected_terms)
+          ? evaluationRun.evidence.replay_dataset.expected_terms
+          : [],
+        matched_terms: evaluationRun.evidence && Array.isArray(evaluationRun.evidence.matched_terms)
+          ? evaluationRun.evidence.matched_terms
+          : []
+      }
+    },
+    metadata: {
+      ...(lesson.metadata || {}),
+      promotion: {
+        promoted_at: nowIso,
+        promoted_by: actor,
+        release_gate: releaseGate
+      },
+      archive,
+      publish: {
+        consent_model: 'adopt-implied',
+        publish_required: true,
+        publish_state: 'pending',
+        publish_target_libraries: [archive.target_library],
+        queued_at: nowIso
+      }
+    },
+    updated_at: nowIso
+  });
+
+  await syncSemanticCapabilityLedger(promotedLesson, {
+    evaluationRun,
+    release_gate: releaseGate,
+    capability_status: 'active',
+    publish_state: 'pending',
+    updated_at: nowIso
+  }, {
+    ...dependencies,
+    projectPath,
+    stateStore: store
+  });
+
+  if (dependencies.autoPublish !== false) {
+    const publication = await publishSemanticLibraryDelta({
+      project_id: promotedLesson.project_id,
+      spec_id: promotedLesson.spec_id,
+      lesson_id: promotedLesson.lesson_id,
+      capability_id: buildCapabilityId(promotedLesson),
+      limit: 1
+    }, {
+      ...dependencies,
+      projectPath,
+      fileSystem: dependencies.fileSystem,
+      stateStore: store,
+      syncSemanticCapabilityLedger
+    });
+    if (!publication || !publication.totals) {
+      throw new Error(`Automatic semantic publication failed for lesson ${promotedLesson.lesson_id}`);
+    }
+    if (publication.totals.published < 1 && publication.totals.blocked < 1) {
+      throw new Error(`Automatic semantic publication failed for lesson ${promotedLesson.lesson_id}`);
+    }
+    const latestLesson = await store.getSemanticLessonCandidate(promotedLesson.lesson_id);
+    return {
+      ...latestLesson,
+      auto_publication: publication
+    };
+  }
+
+  return promotedLesson;
+}
+
+async function rollbackPromotedSemanticLesson(options = {}, dependencies = {}) {
+  const lessonId = normalizeString(options.lesson_id || options.lessonId);
+  if (!lessonId) {
+    throw new Error('lesson_id is required');
+  }
+
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+
+  const lesson = await store.getSemanticLessonCandidate(lessonId);
+  if (!lesson) {
+    throw new Error(`Semantic lesson candidate not found: ${lessonId}`);
+  }
+
+  const nowIso = new Date().toISOString();
+  const actor = normalizeString(options.actor) || null;
+  const reason = normalizeString(options.reason) || 'manual-rollback';
+  const publish = readLessonPublishMetadata(lesson);
+  const rolledBackLesson = await store.upsertSemanticLessonCandidate({
+    ...lesson,
+    status: 'deprecated',
+    metadata: {
+      ...(lesson.metadata || {}),
+      publish: {
+        ...publish,
+        consent_model: normalizeString(publish.consent_model) || 'adopt-implied',
+        publish_required: publish.publish_required === true,
+        publish_state: 'blocked',
+        blocked_at: nowIso,
+        blocked_reason: reason
+      },
+      rollback: {
+        rolled_back_at: nowIso,
+        rolled_back_by: actor,
+        reason
+      }
+    },
+    updated_at: nowIso
+  });
+
+  await syncSemanticCapabilityLedger(rolledBackLesson, {
+    capability_status: 'deprecated',
+    publish_state: 'blocked',
+    updated_at: nowIso
+  }, {
+    ...dependencies,
+    projectPath,
+    stateStore: store
+  });
+
+  return rolledBackLesson;
+}
+
+async function recordSemanticCapabilityActivation(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = getStateStore(projectPath, dependencies);
+  let lesson = options.lesson && typeof options.lesson === 'object'
+    ? options.lesson
+    : null;
+
+  if (!lesson) {
+    const lessonId = normalizeString(options.lesson_id || options.lessonId);
+    if (lessonId) {
+      lesson = await store.getSemanticLessonCandidate(lessonId);
+    }
+  }
+
+  const capabilityId = normalizeString(options.capability_id || options.capabilityId)
+    || (lesson ? buildCapabilityId(lesson) : '');
+  if (!capabilityId) {
+    throw new Error('capability_id or lesson_id is required');
+  }
+
+  let ledger = await store.getSemanticCapabilityLedger(capabilityId);
+  if (!ledger && lesson) {
+    ledger = await syncSemanticCapabilityLedger(lesson, {}, {
+      ...dependencies,
+      projectPath,
+      stateStore: store
+    });
+  }
+  if (!ledger) {
+    return null;
+  }
+
+  if (!lesson && ledger.lesson_id) {
+    lesson = await store.getSemanticLessonCandidate(ledger.lesson_id);
+  }
+
+  const qualitySignal = normalizeQualitySignal(options.quality_signal || options.qualitySignal);
+  const nowIso = normalizeString(options.activated_at || options.activatedAt) || new Date().toISOString();
+  const activationCount = normalizeNonNegativeInteger(ledger.activation_count, 0) + 1;
+  const activationSuccessCount = normalizeNonNegativeInteger(ledger.activation_success_count, 0) + (qualitySignal === 'positive' ? 1 : 0);
+  const activationMixedCount = normalizeNonNegativeInteger(ledger.activation_mixed_count, 0) + (qualitySignal === 'mixed' || qualitySignal === 'unknown' ? 1 : 0);
+  const activationNegativeCount = normalizeNonNegativeInteger(ledger.activation_negative_count, 0) + (qualitySignal === 'negative' ? 1 : 0);
+  const baseQuarantineCount = normalizeNonNegativeInteger(ledger.quarantine_count, 0);
+  const nextMetrics = {
+    ...(ledger.metrics || {}),
+    confidence: lesson && Number.isFinite(Number(lesson.confidence)) ? Number(lesson.confidence) : ledger.metrics && ledger.metrics.confidence,
+    evaluation_score: ledger.metrics && Number.isFinite(Number(ledger.metrics.evaluation_score))
+      ? Number(ledger.metrics.evaluation_score)
+      : null,
+    promotion_release_gate: normalizeString(ledger.metrics && ledger.metrics.promotion_release_gate) || null,
+    activation_count: activationCount,
+    activation_success_count: activationSuccessCount,
+    activation_mixed_count: activationMixedCount,
+    activation_negative_count: activationNegativeCount,
+    quarantine_count: baseQuarantineCount,
+    last_activated_at: nowIso,
+    last_quality_signal: qualitySignal,
+    last_runtime: normalizeString(options.source_runtime || options.sourceRuntime) || 'sce-native'
+  };
+
+  const willQuarantine = shouldQuarantineCapability(nextMetrics);
+  if (willQuarantine && normalizeString(ledger.capability_status) !== 'quarantined') {
+    nextMetrics.quarantine_count = baseQuarantineCount + 1;
+  }
+
+  const updatedLedger = await syncSemanticCapabilityLedger(lesson || {
+    lesson_id: ledger.lesson_id,
+    project_id: ledger.project_id,
+    scene_id: ledger.scene_id,
+    spec_id: ledger.spec_id,
+    source_runtime: ledger.lineage && ledger.lineage.source_runtime
+  }, {
+    capability_id: capabilityId,
+    evaluation_run_id: ledger.evaluation_run_id,
+    channel_id: normalizeString(options.channel_id || options.channelId) || ledger.channel_id,
+    session_id: normalizeString(options.session_id || options.sessionId) || ledger.session_id,
+    capability_status: willQuarantine ? 'quarantined' : normalizeString(ledger.capability_status) || 'active',
+    publish_state: willQuarantine ? 'blocked' : normalizeString(ledger.publish_state) || 'pending',
+    activation_count: nextMetrics.activation_count,
+    activation_success_count: nextMetrics.activation_success_count,
+    activation_mixed_count: nextMetrics.activation_mixed_count,
+    activation_negative_count: nextMetrics.activation_negative_count,
+    quarantine_count: nextMetrics.quarantine_count,
+    last_activated_at: nowIso,
+    last_quality_signal: qualitySignal,
+    last_runtime: nextMetrics.last_runtime,
+    updated_at: nowIso
+  }, {
+    ...dependencies,
+    projectPath,
+    stateStore: store
+  });
+
+  let updatedLesson = lesson;
+  if (willQuarantine && lesson) {
+    updatedLesson = await applySemanticCapabilityQuarantine(lesson, {
+      actor: normalizeString(options.actor) || 'sce-native',
+      reason: normalizeString(options.reason) || 'native-quality-regression',
+      updated_at: nowIso
+    }, {
+      ...dependencies,
+      projectPath,
+      stateStore: store
+    });
+  }
+
+  return {
+    ledger: updatedLedger,
+    lesson: updatedLesson,
+    quarantined: willQuarantine
+  };
+}
+
+module.exports = {
+  isPromotedSemanticStatus,
+  resolveTargetLibrary,
+  buildCapabilityId,
+  calculateRankScore,
+  calculateGovernancePenaltyScore,
+  shouldQuarantineCapability,
+  summarizeGovernancePressure,
+  syncSemanticCapabilityLedger,
+  applySemanticCapabilityQuarantine,
+  listPromotedSemanticBehaviors,
+  activatePromotedSemanticBehaviors,
+  promoteSemanticLessonCandidate,
+  rollbackPromotedSemanticLesson,
+  recordSemanticCapabilityActivation
+};