scene-capability-engine 3.6.65 → 3.6.67

package/lib/semantic/archive-report.js

@@ -0,0 +1,283 @@
+const { getSceStateStore } = require('../state/sce-state-store');
+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 isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readLessonPublishState(lesson = {}) {
+  const metadata = isObject(lesson.metadata) ? lesson.metadata : {};
+  const publish = isObject(metadata.publish) ? metadata.publish : {};
+  return normalizeString(publish.publish_state) || normalizeString(lesson.status) || 'none';
+}
+
+function readArchiveDecision(lesson = {}, ledger = {}) {
+  const lessonMetadata = isObject(lesson.metadata) ? lesson.metadata : {};
+  const lessonArchive = isObject(lessonMetadata.archive) ? lessonMetadata.archive : null;
+  if (lessonArchive && normalizeString(lessonArchive.target_library)) {
+    return lessonArchive;
+  }
+  const ledgerLineage = isObject(ledger.lineage) ? ledger.lineage : {};
+  const lineageArchive = isObject(ledgerLineage.archive) ? ledgerLineage.archive : null;
+  if (lineageArchive && normalizeString(lineageArchive.target_library)) {
+    return lineageArchive;
+  }
+  const ledgerPublication = isObject(ledger.publication) ? ledger.publication : {};
+  const publicationArchive = isObject(ledgerPublication.archive) ? ledgerPublication.archive : null;
+  if (publicationArchive && normalizeString(publicationArchive.target_library)) {
+    return publicationArchive;
+  }
+  return buildSemanticArchiveDecision({
+    project_id: lesson.project_id || ledger.project_id,
+    scene_id: lesson.scene_id || ledger.scene_id,
+    spec_id: lesson.spec_id || ledger.spec_id,
+    lesson_type: lesson.lesson_type || null,
+    metadata: {
+      channel_id: normalizeString(lessonMetadata.channel_id || ledger.channel_id) || null,
+      session_id: normalizeString(lessonMetadata.session_id || ledger.session_id) || null
+    }
+  });
+}
+
+function createBucket(targetLibrary, archiveDecision = {}) {
+  return {
+    target_library: targetLibrary,
+    archive_class: normalizeString(archiveDecision.archive_class) || null,
+    repository_name: normalizeString(archiveDecision.repository_name) || targetLibrary || null,
+    reuse_scope: normalizeString(archiveDecision.reuse_scope) || null,
+    lesson_count: 0,
+    ledger_count: 0,
+    candidate_count: 0,
+    publish_pending_count: 0,
+    published_shared_count: 0,
+    publish_blocked_count: 0,
+    deprecated_count: 0,
+    active_capability_count: 0,
+    quarantined_capability_count: 0,
+    deprecated_capability_count: 0
+  };
+}
+
+function incrementCounter(map, key) {
+  const normalizedKey = normalizeString(key) || 'unknown';
+  map[normalizedKey] = (map[normalizedKey] || 0) + 1;
+}
+
+function sortCounters(map = {}, keyName = 'key') {
+  return Object.entries(map)
+    .map(([key, count]) => ({ [keyName]: key, count }))
+    .sort((left, right) => {
+      if (right.count !== left.count) {
+        return right.count - left.count;
+      }
+      return `${left[keyName]}`.localeCompare(`${right[keyName]}`);
+    });
+}
+
+function buildSemanticArchiveSummary(input = {}) {
+  const lessons = Array.isArray(input.lessons) ? input.lessons : [];
+  const capabilityLedgers = Array.isArray(input.capabilityLedgers) ? input.capabilityLedgers : [];
+  const recentLimit = normalizeInteger(input.recent_limit || input.recentLimit, 10);
+  const ledgersByLessonId = {};
+  for (const ledger of capabilityLedgers) {
+    const lessonId = normalizeString(ledger.lesson_id);
+    if (lessonId && !ledgersByLessonId[lessonId]) {
+      ledgersByLessonId[lessonId] = ledger;
+    }
+  }
+
+  const byLibrary = {};
+  const byArchiveClass = {};
+  const byReuseScope = {};
+  let missingArchiveCount = 0;
+  const recentItems = [];
+  const seenLessonIds = new Set();
+
+  for (const lesson of lessons) {
+    const lessonId = normalizeString(lesson.lesson_id);
+    const ledger = ledgersByLessonId[lessonId] || {};
+    const archive = readArchiveDecision(lesson, ledger);
+    const targetLibrary = normalizeString(archive.target_library);
+    if (!targetLibrary) {
+      missingArchiveCount += 1;
+      continue;
+    }
+    if (!byLibrary[targetLibrary]) {
+      byLibrary[targetLibrary] = createBucket(targetLibrary, archive);
+    }
+    const bucket = byLibrary[targetLibrary];
+    bucket.lesson_count += 1;
+    const lessonStatus = normalizeString(lesson.status);
+    const publishState = readLessonPublishState(lesson);
+    if (lessonStatus === 'candidate') {
+      bucket.candidate_count += 1;
+    }
+    if (publishState === 'pending' || lessonStatus === 'publish_pending') {
+      bucket.publish_pending_count += 1;
+    }
+    if (publishState === 'published-shared' || lessonStatus === 'published-shared') {
+      bucket.published_shared_count += 1;
+    }
+    if (publishState === 'blocked' || lessonStatus === 'publish_blocked') {
+      bucket.publish_blocked_count += 1;
+    }
+    if (lessonStatus === 'deprecated') {
+      bucket.deprecated_count += 1;
+    }
+    incrementCounter(byArchiveClass, archive.archive_class);
+    incrementCounter(byReuseScope, archive.reuse_scope);
+    recentItems.push({
+      lesson_id: lessonId || null,
+      capability_id: normalizeString(ledger.capability_id) || null,
+      project_id: normalizeString(lesson.project_id) || normalizeString(ledger.project_id) || null,
+      channel_id: normalizeString((lesson.metadata && lesson.metadata.channel_id) || ledger.channel_id) || null,
+      session_id: normalizeString((lesson.metadata && lesson.metadata.session_id) || ledger.session_id) || null,
+      scene_id: normalizeString(lesson.scene_id) || normalizeString(ledger.scene_id) || null,
+      spec_id: normalizeString(lesson.spec_id) || normalizeString(ledger.spec_id) || null,
+      target_library: targetLibrary,
+      archive_class: normalizeString(archive.archive_class) || null,
+      reuse_scope: normalizeString(archive.reuse_scope) || null,
+      reason_code: normalizeString(archive.reason_code) || null,
+      lesson_status: lessonStatus || null,
+      publish_state: publishState || null,
+      updated_at: normalizeString(lesson.updated_at) || normalizeString(ledger.updated_at) || null
+    });
+    if (lessonId) {
+      seenLessonIds.add(lessonId);
+    }
+  }
+
+  for (const ledger of capabilityLedgers) {
+    const archive = readArchiveDecision({}, ledger);
+    const targetLibrary = normalizeString(ledger.target_library) || normalizeString(archive.target_library);
+    if (!targetLibrary) {
+      missingArchiveCount += 1;
+      continue;
+    }
+    if (!byLibrary[targetLibrary]) {
+      byLibrary[targetLibrary] = createBucket(targetLibrary, archive);
+    }
+    const bucket = byLibrary[targetLibrary];
+    bucket.ledger_count += 1;
+    const capabilityStatus = normalizeString(ledger.capability_status);
+    if (capabilityStatus === 'active') {
+      bucket.active_capability_count += 1;
+    }
+    if (capabilityStatus === 'quarantined') {
+      bucket.quarantined_capability_count += 1;
+    }
+    if (capabilityStatus === 'deprecated') {
+      bucket.deprecated_capability_count += 1;
+    }
+
+    const lessonId = normalizeString(ledger.lesson_id);
+    if (lessonId && !seenLessonIds.has(lessonId)) {
+      recentItems.push({
+        lesson_id: lessonId,
+        capability_id: normalizeString(ledger.capability_id) || null,
+        project_id: normalizeString(ledger.project_id) || null,
+        channel_id: normalizeString(ledger.channel_id) || null,
+        session_id: normalizeString(ledger.session_id) || null,
+        scene_id: normalizeString(ledger.scene_id) || null,
+        spec_id: normalizeString(ledger.spec_id) || null,
+        target_library: targetLibrary,
+        archive_class: normalizeString(archive.archive_class) || null,
+        reuse_scope: normalizeString(archive.reuse_scope) || null,
+        reason_code: normalizeString(archive.reason_code) || null,
+        lesson_status: null,
+        publish_state: normalizeString(ledger.publish_state) || null,
+        updated_at: normalizeString(ledger.updated_at) || null
+      });
+    }
+  }
+
+  return {
+    totals: {
+      lesson_total: lessons.length,
+      ledger_total: capabilityLedgers.length,
+      missing_archive_count: missingArchiveCount,
+      library_count: Object.keys(byLibrary).length
+    },
+    by_library: Object.values(byLibrary).sort((left, right) => `${left.target_library}`.localeCompare(`${right.target_library}`)),
+    by_archive_class: sortCounters(byArchiveClass, 'archive_class'),
+    by_reuse_scope: sortCounters(byReuseScope, 'reuse_scope'),
+    recent_items: recentItems
+      .sort((left, right) => `${right.updated_at || ''}`.localeCompare(`${left.updated_at || ''}`))
+      .slice(0, recentLimit)
+  };
+}
+
+async function buildSemanticArchiveReport(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule,
+    noCache: dependencies.noCache === true
+  });
+  const projectId = normalizeString(options.project_id || options.projectId);
+  const specId = normalizeString(options.spec_id || options.specId);
+  const sessionId = normalizeString(options.session_id || options.sessionId);
+  const limit = normalizeInteger(options.limit, 200);
+  const recentLimit = normalizeInteger(options.recent_limit || options.recentLimit, 10);
+
+  let lessons = await store.listSemanticLessonCandidates({
+    project_id: projectId,
+    limit
+  });
+  lessons = Array.isArray(lessons) ? lessons : [];
+  if (specId) {
+    lessons = lessons.filter((item) => normalizeString(item.spec_id) === specId);
+  }
+  if (sessionId) {
+    lessons = lessons.filter((item) => normalizeString(item.metadata && item.metadata.session_id) === sessionId);
+  }
+
+  let capabilityLedgers = await store.listSemanticCapabilityLedgers({
+    project_id: projectId,
+    spec_id: specId,
+    limit
+  });
+  capabilityLedgers = Array.isArray(capabilityLedgers) ? capabilityLedgers : [];
+  if (sessionId) {
+    capabilityLedgers = capabilityLedgers.filter((item) => normalizeString(item.session_id) === sessionId);
+  }
+
+  return {
+    mode: 'semantic-archive-report',
+    success: true,
+    generated_at: new Date().toISOString(),
+    filters: {
+      project_id: projectId || null,
+      spec_id: specId || null,
+      session_id: sessionId || null,
+      limit,
+      recent_limit: recentLimit
+    },
+    ...buildSemanticArchiveSummary({
+      lessons,
+      capabilityLedgers,
+      recent_limit: recentLimit
+    })
+  };
+}
+
+module.exports = {
+  buildSemanticArchiveSummary,
+  buildSemanticArchiveReport
+};

package/lib/semantic/archive-routing.js

@@ -0,0 +1,67 @@
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeMetadata(payload = {}) {
+  return payload && typeof payload === 'object' ? payload : {};
+}
+
+function buildSemanticArchiveDecision(lesson = {}) {
+  const metadata = normalizeMetadata(lesson.metadata);
+  const lessonType = normalizeString(lesson.lesson_type);
+  const sceneId = normalizeString(lesson.scene_id) || null;
+  const specId = normalizeString(lesson.spec_id) || null;
+  const projectId = normalizeString(lesson.project_id) || null;
+  const channelId = normalizeString(metadata.channel_id || metadata.channelId) || null;
+  const sessionId = normalizeString(metadata.session_id || metadata.sessionId) || null;
+
+  if (lessonType === 'failure-pattern') {
+    return {
+      target_library: 'experience-library',
+      archive_class: 'experience',
+      repository_name: 'experience-library',
+      reuse_scope: 'cross-project',
+      reason_code: 'failure-pattern-routes-to-experience-library',
+      project_id: projectId,
+      channel_id: channelId,
+      session_id: sessionId,
+      scene_id: sceneId,
+      spec_id: specId
+    };
+  }
+
+  if (sceneId === 'scene.sce-semantic-kernel') {
+    return {
+      target_library: 'ontology-capability-library',
+      archive_class: 'ontology-capability',
+      repository_name: 'ontology-capability-library',
+      reuse_scope: 'cross-project',
+      reason_code: 'semantic-kernel-scene-routes-to-ontology-capability-library',
+      project_id: projectId,
+      channel_id: channelId,
+      session_id: sessionId,
+      scene_id: sceneId,
+      spec_id: specId
+    };
+  }
+
+  return {
+    target_library: 'application-library',
+    archive_class: 'application',
+    repository_name: 'application-library',
+    reuse_scope: 'project-or-spec',
+    reason_code: 'project-scoped-pattern-routes-to-application-library',
+    project_id: projectId,
+    channel_id: channelId,
+    session_id: sessionId,
+    scene_id: sceneId,
+    spec_id: specId
+  };
+}
+
+module.exports = {
+  buildSemanticArchiveDecision
+};

package/lib/semantic/backflow-report.js

@@ -0,0 +1,245 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { getSceStateStore } = require('../state/sce-state-store');
+
+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 readLessonPublish(lesson = {}) {
+  if (lesson.metadata && typeof lesson.metadata === 'object'
+      && lesson.metadata.publish
+      && typeof lesson.metadata.publish === 'object') {
+    return lesson.metadata.publish;
+  }
+  return {};
+}
+
+async function readJsonIfExists(filePath, fileSystem = fs) {
+  if (!await fileSystem.pathExists(filePath)) {
+    return null;
+  }
+  try {
+    return await fileSystem.readJson(filePath);
+  } catch (_error) {
+    return null;
+  }
+}
+
+function incrementCounter(map, key) {
+  const normalizedKey = normalizeString(key) || 'unknown';
+  map[normalizedKey] = (map[normalizedKey] || 0) + 1;
+}
+
+function sortCounters(map = {}, keyName = 'reason') {
+  return Object.entries(map)
+    .map(([key, count]) => ({ [keyName]: key, count }))
+    .sort((left, right) => {
+      if (right.count !== left.count) {
+        return right.count - left.count;
+      }
+      return `${left[keyName]}`.localeCompare(`${right[keyName]}`);
+    });
+}
+
+function listUniqueSpecIds(lessons = [], explicitSpecId = '') {
+  const requested = normalizeString(explicitSpecId);
+  if (requested) {
+    return [requested];
+  }
+  return [...new Set(lessons.map((item) => normalizeString(item.spec_id)).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}
+
+function collectBlockedSpecIds(localBlockedLessons = [], mergeReceipts = [], releaseReceipts = []) {
+  const specIds = new Set();
+  for (const lesson of localBlockedLessons) {
+    const specId = normalizeString(lesson && lesson.spec_id);
+    if (specId) {
+      specIds.add(specId);
+    }
+  }
+  for (const receipt of [...mergeReceipts, ...releaseReceipts]) {
+    const specId = normalizeString(receipt && receipt.spec_id);
+    const blockedCount = normalizeInteger(receipt && receipt.totals && receipt.totals.blocked, 0);
+    if (specId && blockedCount > 0) {
+      specIds.add(specId);
+    }
+  }
+  return [...specIds].sort((left, right) => left.localeCompare(right));
+}
+
+function buildLocalBlockedItems(lessons = [], ledgersByCapabilityId = {}, limit = 10) {
+  const ledgersByLessonId = {};
+  for (const ledger of Object.values(ledgersByCapabilityId || {})) {
+    const lessonId = normalizeString(ledger && ledger.lesson_id);
+    if (lessonId && !ledgersByLessonId[lessonId]) {
+      ledgersByLessonId[lessonId] = ledger;
+    }
+  }
+  return lessons
+    .map((lesson) => {
+      const publish = readLessonPublish(lesson);
+      const linkedLedger = ledgersByLessonId[normalizeString(lesson.lesson_id)] || null;
+      const capabilityId = normalizeString(linkedLedger && linkedLedger.capability_id);
+      const ledger = linkedLedger;
+      return {
+        lesson_id: lesson.lesson_id,
+        capability_id: capabilityId || null,
+        project_id: lesson.project_id || null,
+        channel_id: normalizeString(lesson.metadata && lesson.metadata.channel_id) || null,
+        session_id: normalizeString(lesson.metadata && lesson.metadata.session_id) || null,
+        scene_id: lesson.scene_id || null,
+        spec_id: lesson.spec_id || null,
+        blocked_reason: normalizeString(publish.blocked_reason) || 'unknown',
+        blocked_at: normalizeString(publish.blocked_at) || null,
+        governance_penalty_score: Number(ledger && ledger.metrics && ledger.metrics.governance_penalty_score) || 0,
+        governance_refuse_count: Number(ledger && ledger.metrics && ledger.metrics.governance_refuse_count) || 0,
+        governance_execution_blocked_count: Number(ledger && ledger.metrics && ledger.metrics.governance_execution_blocked_count) || 0
+      };
+    })
+    .sort((left, right) => `${right.blocked_at || ''}`.localeCompare(`${left.blocked_at || ''}`))
+    .slice(0, limit);
+}
+
+async function buildSemanticBackflowReport(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule,
+    noCache: dependencies.noCache === true
+  });
+
+  const projectId = normalizeString(options.project_id || options.projectId);
+  const specId = normalizeString(options.spec_id || options.specId);
+  const limit = normalizeInteger(options.limit, 200);
+  const recentLimit = normalizeInteger(options.recent_limit || options.recentLimit, 10);
+
+  let lessons = await store.listSemanticLessonCandidates({
+    project_id: projectId,
+    limit
+  });
+  lessons = Array.isArray(lessons) ? lessons : [];
+  if (specId) {
+    lessons = lessons.filter((item) => normalizeString(item.spec_id) === specId);
+  }
+
+  let ledgers = await store.listSemanticCapabilityLedgers({
+    project_id: projectId,
+    spec_id: specId,
+    limit
+  });
+  ledgers = Array.isArray(ledgers) ? ledgers : [];
+  const ledgersByCapabilityId = {};
+  for (const ledger of ledgers) {
+    const capabilityId = normalizeString(ledger.capability_id);
+    if (capabilityId) {
+      ledgersByCapabilityId[capabilityId] = ledger;
+    }
+  }
+
+  const localBlockedLessons = lessons.filter((item) => {
+    const publish = readLessonPublish(item);
+    return normalizeString(item.status) === 'publish_blocked'
+      || normalizeString(publish.publish_state) === 'blocked';
+  });
+  const localBlockedByReason = {};
+  for (const lesson of localBlockedLessons) {
+    incrementCounter(localBlockedByReason, readLessonPublish(lesson).blocked_reason || 'unknown');
+  }
+
+  const targetSpecIds = listUniqueSpecIds(lessons, specId);
+  const mergeBlockedByReason = {};
+  const releaseBlockedByReason = {};
+  const mergeReceipts = [];
+  const releaseReceipts = [];
+
+  for (const currentSpecId of targetSpecIds) {
+    const mergeReceiptPath = path.join(projectPath, '.sce', 'specs', currentSpecId, 'registry', 'semantic-shared', 'latest.receipt.json');
+    const releaseReceiptPath = path.join(projectPath, '.sce', 'specs', currentSpecId, 'registry', 'semantic-shared', 'published', 'latest.receipt.json');
+    const mergeReceipt = await readJsonIfExists(mergeReceiptPath, fileSystem);
+    const releaseReceipt = await readJsonIfExists(releaseReceiptPath, fileSystem);
+
+    if (mergeReceipt) {
+      mergeReceipts.push({
+        spec_id: currentSpecId,
+        success: mergeReceipt.success === true,
+        generated_at: normalizeString(mergeReceipt.generated_at) || null,
+        totals: mergeReceipt.totals || {},
+        blocked: Array.isArray(mergeReceipt.blocked) ? mergeReceipt.blocked : []
+      });
+      for (const item of Array.isArray(mergeReceipt.blocked) ? mergeReceipt.blocked : []) {
+        incrementCounter(mergeBlockedByReason, item.reason || 'unknown');
+      }
+    }
+
+    if (releaseReceipt) {
+      releaseReceipts.push({
+        spec_id: currentSpecId,
+        success: releaseReceipt.success === true,
+        generated_at: normalizeString(releaseReceipt.generated_at) || null,
+        totals: releaseReceipt.totals || {},
+        blocked: Array.isArray(releaseReceipt.blocked) ? releaseReceipt.blocked : []
+      });
+      for (const item of Array.isArray(releaseReceipt.blocked) ? releaseReceipt.blocked : []) {
+        incrementCounter(releaseBlockedByReason, item.reason || 'unknown');
+      }
+    }
+  }
+
+  const blockedSpecIds = collectBlockedSpecIds(localBlockedLessons, mergeReceipts, releaseReceipts);
+
+  return {
+    mode: 'semantic-backflow-report',
+    success: true,
+    generated_at: new Date().toISOString(),
+    filters: {
+      project_id: projectId || null,
+      spec_id: specId || null,
+      limit,
+      recent_limit: recentLimit
+    },
+    totals: {
+      lesson_total: lessons.length,
+      local_publish_blocked: localBlockedLessons.length,
+      central_merge_blocked: mergeReceipts.reduce((sum, item) => sum + normalizeInteger(item.totals && item.totals.blocked, 0), 0),
+      central_release_blocked: releaseReceipts.reduce((sum, item) => sum + normalizeInteger(item.totals && item.totals.blocked, 0), 0),
+      blocked_spec_count: blockedSpecIds.length,
+      merge_receipt_count: mergeReceipts.length,
+      release_receipt_count: releaseReceipts.length
+    },
+    blocked_spec_ids: blockedSpecIds,
+    local: {
+      blocked_by_reason: sortCounters(localBlockedByReason, 'reason'),
+      recent_blocked_items: buildLocalBlockedItems(localBlockedLessons, ledgersByCapabilityId, recentLimit)
+    },
+    central_merge: {
+      blocked_by_reason: sortCounters(mergeBlockedByReason, 'reason'),
+      receipts: mergeReceipts
+        .sort((left, right) => `${right.generated_at || ''}`.localeCompare(`${left.generated_at || ''}`))
+        .slice(0, recentLimit)
+    },
+    central_release: {
+      blocked_by_reason: sortCounters(releaseBlockedByReason, 'reason'),
+      receipts: releaseReceipts
+        .sort((left, right) => `${right.generated_at || ''}`.localeCompare(`${left.generated_at || ''}`))
+        .slice(0, recentLimit)
+    }
+  };
+}
+
+module.exports = {
+  buildSemanticBackflowReport
+};

package/lib/semantic/capability-contract.js

@@ -0,0 +1,30 @@
+const { buildSemanticArchiveDecision } = require('./archive-routing');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function resolveTargetLibrary(lesson = {}) {
+  return normalizeString(buildSemanticArchiveDecision(lesson).target_library) || 'application-library';
+}
+
+function buildCapabilityId(lesson = {}) {
+  const base = normalizeString(lesson.fingerprint || lesson.lesson_id || 'capability');
+  const metadata = lesson.metadata && typeof lesson.metadata === 'object'
+    ? lesson.metadata
+    : {};
+  const channelId = normalizeString(metadata.channel_id || metadata.channelId);
+  const normalizedBase = base.replace(/[^a-zA-Z0-9._-]+/g, '-').toLowerCase();
+  const normalizedChannel = channelId.replace(/[^a-zA-Z0-9._-]+/g, '-').toLowerCase();
+  return normalizedChannel
+    ? `cap.${normalizedBase}.ch.${normalizedChannel}`
+    : `cap.${normalizedBase}`;
+}
+
+module.exports = {
+  resolveTargetLibrary,
+  buildCapabilityId
+};