scene-capability-engine 3.6.32 → 3.6.36

package/lib/app/registry-config.js

@@ -0,0 +1,73 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_APP_REGISTRY_CONFIG_PATH = path.join('.sce', 'config', 'app-registries.json');
+
+const DEFAULT_APP_REGISTRY_CONFIG = Object.freeze({
+  version: '1.0',
+  bundle_registry: {
+    repo_url: 'https://github.com/heguangyong/magicball-app-bundle-registry.git',
+    branch: 'main',
+    index_url: 'https://raw.githubusercontent.com/heguangyong/magicball-app-bundle-registry/main/bundles/index.json'
+  },
+  service_catalog: {
+    repo_url: 'https://github.com/heguangyong/magicball-app-service-catalog.git',
+    branch: 'main',
+    index_url: 'https://raw.githubusercontent.com/heguangyong/magicball-app-service-catalog/main/catalog/index.json'
+  }
+});
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function mergeSection(base = {}, patch = {}) {
+  return {
+    ...base,
+    ...Object.fromEntries(
+      Object.entries(patch || {}).filter(([, value]) => value !== undefined)
+    )
+  };
+}
+
+async function loadAppRegistryConfig(projectPath = process.cwd(), fileSystem = fs) {
+  const configPath = path.join(projectPath, DEFAULT_APP_REGISTRY_CONFIG_PATH);
+  let filePayload = {};
+  if (await fileSystem.pathExists(configPath)) {
+    filePayload = await fileSystem.readJson(configPath);
+  }
+  return {
+    config_path: DEFAULT_APP_REGISTRY_CONFIG_PATH,
+    config: {
+      version: normalizeString(filePayload.version) || DEFAULT_APP_REGISTRY_CONFIG.version,
+      bundle_registry: mergeSection(DEFAULT_APP_REGISTRY_CONFIG.bundle_registry, filePayload.bundle_registry),
+      service_catalog: mergeSection(DEFAULT_APP_REGISTRY_CONFIG.service_catalog, filePayload.service_catalog)
+    }
+  };
+}
+
+async function saveAppRegistryConfig(patch = {}, projectPath = process.cwd(), fileSystem = fs) {
+  const loaded = await loadAppRegistryConfig(projectPath, fileSystem);
+  const nextConfig = {
+    version: DEFAULT_APP_REGISTRY_CONFIG.version,
+    bundle_registry: mergeSection(loaded.config.bundle_registry, patch.bundle_registry),
+    service_catalog: mergeSection(loaded.config.service_catalog, patch.service_catalog)
+  };
+  const configPath = path.join(projectPath, DEFAULT_APP_REGISTRY_CONFIG_PATH);
+  await fileSystem.ensureDir(path.dirname(configPath));
+  await fileSystem.writeJson(configPath, nextConfig, { spaces: 2 });
+  return {
+    config_path: DEFAULT_APP_REGISTRY_CONFIG_PATH,
+    config: nextConfig
+  };
+}
+
+module.exports = {
+  DEFAULT_APP_REGISTRY_CONFIG_PATH,
+  DEFAULT_APP_REGISTRY_CONFIG,
+  loadAppRegistryConfig,
+  saveAppRegistryConfig
+};

package/lib/app/registry-sync-service.js

@@ -0,0 +1,228 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { loadAppRegistryConfig } = require('./registry-config');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+async function readJsonResource(resourceRef, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const fetchImpl = dependencies.fetchImpl || global.fetch;
+  const normalized = normalizeString(resourceRef);
+  if (!normalized) {
+    throw new Error('resource reference is required');
+  }
+  if (/^https?:\/\//i.test(normalized)) {
+    if (typeof fetchImpl !== 'function') {
+      throw new Error(`fetch unavailable for remote resource: ${normalized}`);
+    }
+    const response = await fetchImpl(normalized);
+    if (!response || response.ok !== true) {
+      const status = response && typeof response.status !== 'undefined' ? response.status : 'unknown';
+      throw new Error(`failed to fetch ${normalized} (status=${status})`);
+    }
+    return response.json();
+  }
+  const resolvedPath = path.isAbsolute(normalized)
+    ? normalized
+    : path.join(dependencies.projectPath || process.cwd(), normalized);
+  return fileSystem.readJson(resolvedPath);
+}
+
+function resolveChildResource(parentRef, childRef) {
+  const normalizedParent = normalizeString(parentRef);
+  const normalizedChild = normalizeString(childRef);
+  if (!normalizedChild) {
+    return normalizedParent;
+  }
+  if (/^https?:\/\//i.test(normalizedChild) || path.isAbsolute(normalizedChild)) {
+    return normalizedChild;
+  }
+  if (/^https?:\/\//i.test(normalizedParent)) {
+    return new URL(normalizedChild, normalizedParent).toString();
+  }
+  return path.join(path.dirname(normalizedParent), normalizedChild);
+}
+
+function graphToRegisterPayload(graph = {}) {
+  const bundle = graph.bundle || {};
+  const runtimeRelease = graph.runtime_release || {};
+  const ontologyBundle = graph.ontology_bundle || {};
+  const engineeringProject = graph.engineering_project || {};
+  return {
+    app_id: bundle.app_id,
+    app_key: bundle.app_key,
+    app_name: bundle.app_name,
+    app_slug: bundle.app_slug || undefined,
+    workspace_id: bundle.workspace_id || undefined,
+    runtime_release_id: bundle.runtime_release_id || undefined,
+    ontology_bundle_id: bundle.ontology_bundle_id || undefined,
+    engineering_project_id: bundle.engineering_project_id || undefined,
+    default_scene_id: bundle.default_scene_id || undefined,
+    environment: bundle.environment || undefined,
+    status: bundle.status || undefined,
+    source_origin: bundle.source_origin || undefined,
+    tags: Array.isArray(bundle.tags) ? bundle.tags : [],
+    metadata: bundle.metadata && typeof bundle.metadata === 'object' ? { ...bundle.metadata } : {},
+    runtime: runtimeRelease && runtimeRelease.release_id ? {
+      release_id: runtimeRelease.release_id,
+      runtime_version: runtimeRelease.runtime_version,
+      release_channel: runtimeRelease.release_channel,
+      release_status: runtimeRelease.release_status,
+      entrypoint: runtimeRelease.entrypoint,
+      runtime_status: runtimeRelease.runtime_status,
+      release_notes_file: runtimeRelease.release_notes_file,
+      release_evidence_file: runtimeRelease.release_evidence_file,
+      published_at: runtimeRelease.published_at,
+      source_updated_at: runtimeRelease.source_updated_at,
+      metadata: runtimeRelease.metadata || {}
+    } : undefined,
+    ontology: ontologyBundle && ontologyBundle.ontology_bundle_id ? {
+      ontology_bundle_id: ontologyBundle.ontology_bundle_id,
+      ontology_version: ontologyBundle.ontology_version,
+      template_version: ontologyBundle.template_version,
+      capability_catalog_version: ontologyBundle.capability_catalog_version,
+      triad_revision: ontologyBundle.triad_revision,
+      triad_status: ontologyBundle.triad_status,
+      publish_readiness: ontologyBundle.publish_readiness,
+      template_source: ontologyBundle.template_source,
+      capability_set: Array.isArray(ontologyBundle.capability_set) ? ontologyBundle.capability_set : [],
+      summary: ontologyBundle.summary || {},
+      metadata: ontologyBundle.metadata || {}
+    } : undefined,
+    engineering: engineeringProject && engineeringProject.engineering_project_id ? {
+      engineering_project_id: engineeringProject.engineering_project_id,
+      project_key: engineeringProject.project_key,
+      project_name: engineeringProject.project_name,
+      repo_url: engineeringProject.repo_url,
+      repo_provider: engineeringProject.repo_provider,
+      default_branch: engineeringProject.default_branch,
+      current_branch: engineeringProject.current_branch,
+      commit_sha: engineeringProject.commit_sha,
+      workspace_path: engineeringProject.workspace_path,
+      code_version: engineeringProject.code_version,
+      synced_runtime_release_id: engineeringProject.synced_runtime_release_id,
+      dirty_state: engineeringProject.dirty_state === true,
+      auth_policy: engineeringProject.auth_policy || {},
+      metadata: engineeringProject.metadata || {}
+    } : undefined,
+    scene_bindings: Array.isArray(graph.scene_bindings)
+      ? graph.scene_bindings.map((item) => ({
+        scene_id: item.scene_id,
+        binding_role: item.binding_role,
+        source: item.source,
+        metadata: item.metadata || {}
+      }))
+      : []
+  };
+}
+
+async function syncBundleRegistry(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateStore = dependencies.stateStore;
+  const loadedConfig = await loadAppRegistryConfig(projectPath, fileSystem);
+  const indexRef = normalizeString(options.indexUrl) || normalizeString(loadedConfig.config.bundle_registry.index_url);
+  const indexPayload = await readJsonResource(indexRef, dependencies);
+  const bundleItems = Array.isArray(indexPayload && indexPayload.bundles) ? indexPayload.bundles : [];
+  const synced = [];
+  for (const item of bundleItems) {
+    const resourceRef = normalizeString(item && item.url) || resolveChildResource(indexRef, item && item.file);
+    const bundlePayload = await readJsonResource(resourceRef, dependencies);
+    const graph = await stateStore.registerAppBundle(bundlePayload);
+    synced.push({
+      app_id: graph && graph.bundle ? graph.bundle.app_id : null,
+      app_key: graph && graph.bundle ? graph.bundle.app_key : null,
+      source: resourceRef
+    });
+  }
+  return {
+    mode: 'app-registry-sync-bundles',
+    index_url: indexRef,
+    source_generated_at: indexPayload && indexPayload.generated_at ? indexPayload.generated_at : null,
+    synced_count: synced.length,
+    items: synced
+  };
+}
+
+async function syncServiceCatalog(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateStore = dependencies.stateStore;
+  const loadedConfig = await loadAppRegistryConfig(projectPath, fileSystem);
+  const indexRef = normalizeString(options.indexUrl) || normalizeString(loadedConfig.config.service_catalog.index_url);
+  const indexPayload = await readJsonResource(indexRef, dependencies);
+  const appItems = Array.isArray(indexPayload && indexPayload.apps) ? indexPayload.apps : [];
+  const synced = [];
+  for (const item of appItems) {
+    const resourceRef = normalizeString(item && item.url) || resolveChildResource(indexRef, item && item.file);
+    const appPayload = await readJsonResource(resourceRef, dependencies);
+    const appId = normalizeString(appPayload && appPayload.app_id);
+    const appKey = normalizeString(appPayload && appPayload.app_key);
+    const appName = normalizeString(appPayload && appPayload.app_name);
+    let graph = await stateStore.getAppBundleGraph(appId || appKey);
+    if (!graph) {
+      graph = await stateStore.registerAppBundle({
+        app_id: appId,
+        app_key: appKey,
+        app_name: appName || appKey || appId,
+        status: 'active',
+        environment: normalizeString(appPayload && appPayload.environment) || null,
+        source_origin: 'app-service-catalog-sync'
+      });
+    }
+    const nextPayload = graphToRegisterPayload(graph);
+    const releases = Array.isArray(appPayload && appPayload.releases) ? appPayload.releases : [];
+    const defaultReleaseId = normalizeString(appPayload && appPayload.default_release_id) || (releases[0] && normalizeString(releases[0].release_id)) || null;
+    const activeRelease = releases.find((entry) => normalizeString(entry && entry.release_id) === defaultReleaseId) || releases[0] || null;
+    nextPayload.metadata = nextPayload.metadata || {};
+    nextPayload.metadata.service_catalog = {
+      synced_at: new Date().toISOString(),
+      source: resourceRef,
+      app_name: appName || null,
+      default_release_id: defaultReleaseId,
+      releases
+    };
+    if (activeRelease) {
+      nextPayload.runtime_release_id = normalizeString(activeRelease.release_id);
+      nextPayload.runtime = {
+        release_id: normalizeString(activeRelease.release_id),
+        runtime_version: normalizeString(activeRelease.runtime_version),
+        release_channel: normalizeString(activeRelease.release_channel) || null,
+        release_status: normalizeString(activeRelease.release_status) || 'published',
+        entrypoint: normalizeString(activeRelease.entrypoint) || null,
+        runtime_status: normalizeString(activeRelease.runtime_status) || null,
+        release_notes_file: normalizeString(activeRelease.release_notes_file) || null,
+        release_evidence_file: normalizeString(activeRelease.release_evidence_file) || null,
+        published_at: normalizeString(activeRelease.published_at) || null,
+        metadata: activeRelease.metadata && typeof activeRelease.metadata === 'object' ? activeRelease.metadata : {}
+      };
+    }
+    const updated = await stateStore.registerAppBundle(nextPayload);
+    synced.push({
+      app_id: updated && updated.bundle ? updated.bundle.app_id : appId,
+      app_key: updated && updated.bundle ? updated.bundle.app_key : appKey,
+      source: resourceRef,
+      release_count: releases.length,
+      default_release_id: defaultReleaseId || null
+    });
+  }
+  return {
+    mode: 'app-registry-sync-service-catalog',
+    index_url: indexRef,
+    source_generated_at: indexPayload && indexPayload.generated_at ? indexPayload.generated_at : null,
+    synced_count: synced.length,
+    items: synced
+  };
+}
+
+module.exports = {
+  readJsonResource,
+  resolveChildResource,
+  syncBundleRegistry,
+  syncServiceCatalog
+};

package/lib/auto/archive-schema-service.js

@@ -0,0 +1,276 @@
+const path = require('path');
+
+function normalizeSchemaScope(scopeCandidate) {
+  const allowed = new Set([
+    'close-loop-session',
+    'batch-session',
+    'controller-session',
+    'governance-session'
+  ]);
+  const raw = `${scopeCandidate || 'all'}`.trim().toLowerCase();
+  const tokens = raw.split(',').map((item) => item.trim()).filter(Boolean);
+  if (tokens.length === 0 || tokens.includes('all')) {
+    return [...allowed];
+  }
+  const normalized = [];
+  for (const token of tokens) {
+    if (!allowed.has(token)) {
+      throw new Error('--only must be one of: all, close-loop-session, batch-session, controller-session, governance-session');
+    }
+    if (!normalized.includes(token)) {
+      normalized.push(token);
+    }
+  }
+  return normalized;
+}
+
+function normalizeTargetSchemaVersion(targetVersionCandidate) {
+  const normalized = `${targetVersionCandidate || ''}`.trim();
+  if (!normalized) {
+    throw new Error('--target-version is required.');
+  }
+  if (normalized.length > 32) {
+    throw new Error('--target-version must be 32 characters or fewer.');
+  }
+  return normalized;
+}
+
+function getAutoArchiveSchemaTargets(projectPath, scope, dependencies = {}) {
+  const {
+    getCloseLoopSessionDir,
+    getCloseLoopBatchSummaryDir,
+    getCloseLoopControllerSessionDir,
+    getGovernanceCloseLoopSessionDir
+  } = dependencies;
+  const allTargets = [
+    { id: 'close-loop-session', directory: getCloseLoopSessionDir(projectPath) },
+    { id: 'batch-session', directory: getCloseLoopBatchSummaryDir(projectPath) },
+    { id: 'controller-session', directory: getCloseLoopControllerSessionDir(projectPath) },
+    { id: 'governance-session', directory: getGovernanceCloseLoopSessionDir(projectPath) }
+  ];
+  const scopeSet = new Set(scope);
+  return allTargets.filter((item) => scopeSet.has(item.id));
+}
+
+function classifyArchiveSchemaCompatibility(schemaVersion, supportedVersions) {
+  const normalized = typeof schemaVersion === 'string' ? schemaVersion.trim() : '';
+  if (!normalized) {
+    return 'missing_schema_version';
+  }
+  if (supportedVersions.has(normalized)) {
+    return 'compatible';
+  }
+  return 'incompatible';
+}
+
+async function checkAutoArchiveSchema(projectPath, options = {}, dependencies = {}) {
+  const {
+    fs,
+    calculatePercent,
+    getCloseLoopSessionDir,
+    getCloseLoopBatchSummaryDir,
+    getCloseLoopControllerSessionDir,
+    getGovernanceCloseLoopSessionDir,
+    supportedVersions,
+    now = () => new Date()
+  } = dependencies;
+  const scope = normalizeSchemaScope(options.only);
+  const targets = getAutoArchiveSchemaTargets(projectPath, scope, {
+    getCloseLoopSessionDir,
+    getCloseLoopBatchSummaryDir,
+    getCloseLoopControllerSessionDir,
+    getGovernanceCloseLoopSessionDir
+  });
+  const archives = [];
+
+  for (const target of targets) {
+    const archiveSummary = {
+      id: target.id,
+      directory: target.directory,
+      total_files: 0,
+      compatible_files: 0,
+      missing_schema_version_files: 0,
+      incompatible_files: 0,
+      parse_error_files: 0,
+      issues: []
+    };
+    if (!(await fs.pathExists(target.directory))) {
+      archives.push(archiveSummary);
+      continue;
+    }
+    const files = (await fs.readdir(target.directory))
+      .filter((item) => item.toLowerCase().endsWith('.json'))
+      .sort((left, right) => left.localeCompare(right));
+    archiveSummary.total_files = files.length;
+
+    for (const file of files) {
+      const filePath = path.join(target.directory, file);
+      let payload = null;
+      try {
+        payload = await fs.readJson(filePath);
+      } catch (error) {
+        archiveSummary.parse_error_files += 1;
+        archiveSummary.issues.push({ file: filePath, compatibility: 'parse_error', error: error.message });
+        continue;
+      }
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        archiveSummary.parse_error_files += 1;
+        archiveSummary.issues.push({ file: filePath, compatibility: 'parse_error', error: 'invalid JSON root type' });
+        continue;
+      }
+      const schemaVersion = typeof payload.schema_version === 'string' ? payload.schema_version.trim() : '';
+      const compatibility = classifyArchiveSchemaCompatibility(schemaVersion, supportedVersions);
+      if (compatibility === 'compatible') {
+        archiveSummary.compatible_files += 1;
+      } else if (compatibility === 'missing_schema_version') {
+        archiveSummary.missing_schema_version_files += 1;
+        archiveSummary.issues.push({ file: filePath, compatibility, schema_version: null });
+      } else {
+        archiveSummary.incompatible_files += 1;
+        archiveSummary.issues.push({ file: filePath, compatibility, schema_version: schemaVersion });
+      }
+    }
+    archives.push(archiveSummary);
+  }
+
+  const totals = archives.reduce((acc, item) => ({
+    total_files: acc.total_files + item.total_files,
+    compatible_files: acc.compatible_files + item.compatible_files,
+    missing_schema_version_files: acc.missing_schema_version_files + item.missing_schema_version_files,
+    incompatible_files: acc.incompatible_files + item.incompatible_files,
+    parse_error_files: acc.parse_error_files + item.parse_error_files
+  }), {
+    total_files: 0,
+    compatible_files: 0,
+    missing_schema_version_files: 0,
+    incompatible_files: 0,
+    parse_error_files: 0
+  });
+
+  const nowValue = now();
+  return {
+    mode: 'auto-schema-check',
+    generated_at: nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString(),
+    supported_versions: [...supportedVersions],
+    scope,
+    summary: {
+      ...totals,
+      compatibility_rate_percent: calculatePercent(totals.compatible_files, totals.total_files)
+    },
+    archives
+  };
+}
+
+async function migrateAutoArchiveSchema(projectPath, options = {}, dependencies = {}) {
+  const {
+    fs,
+    getCloseLoopSessionDir,
+    getCloseLoopBatchSummaryDir,
+    getCloseLoopControllerSessionDir,
+    getGovernanceCloseLoopSessionDir,
+    defaultVersion,
+    now = () => new Date()
+  } = dependencies;
+  const scope = normalizeSchemaScope(options.only);
+  const targetVersion = normalizeTargetSchemaVersion(options.targetVersion || defaultVersion);
+  const dryRun = !options.apply;
+  const targets = getAutoArchiveSchemaTargets(projectPath, scope, {
+    getCloseLoopSessionDir,
+    getCloseLoopBatchSummaryDir,
+    getCloseLoopControllerSessionDir,
+    getGovernanceCloseLoopSessionDir
+  });
+  const archives = [];
+
+  for (const target of targets) {
+    const archiveSummary = {
+      id: target.id,
+      directory: target.directory,
+      total_files: 0,
+      candidate_files: 0,
+      updated_files: 0,
+      skipped_compatible_files: 0,
+      parse_error_files: 0,
+      updates: [],
+      errors: []
+    };
+    if (!(await fs.pathExists(target.directory))) {
+      archives.push(archiveSummary);
+      continue;
+    }
+
+    const files = (await fs.readdir(target.directory))
+      .filter((item) => item.toLowerCase().endsWith('.json'))
+      .sort((left, right) => left.localeCompare(right));
+    archiveSummary.total_files = files.length;
+
+    for (const file of files) {
+      const filePath = path.join(target.directory, file);
+      let payload = null;
+      try {
+        payload = await fs.readJson(filePath);
+      } catch (error) {
+        archiveSummary.parse_error_files += 1;
+        archiveSummary.errors.push({ file: filePath, error: error.message });
+        continue;
+      }
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        archiveSummary.parse_error_files += 1;
+        archiveSummary.errors.push({ file: filePath, error: 'invalid JSON root type' });
+        continue;
+      }
+
+      const previousVersion = typeof payload.schema_version === 'string' ? payload.schema_version.trim() : '';
+      if (previousVersion === targetVersion) {
+        archiveSummary.skipped_compatible_files += 1;
+        continue;
+      }
+
+      archiveSummary.candidate_files += 1;
+      if (dryRun) {
+        archiveSummary.updates.push({ file: filePath, from: previousVersion || null, to: targetVersion });
+        continue;
+      }
+
+      payload.schema_version = targetVersion;
+      await fs.writeJson(filePath, payload, { spaces: 2 });
+      archiveSummary.updated_files += 1;
+      archiveSummary.updates.push({ file: filePath, from: previousVersion || null, to: targetVersion });
+    }
+    archives.push(archiveSummary);
+  }
+
+  const totals = archives.reduce((acc, item) => ({
+    total_files: acc.total_files + item.total_files,
+    candidate_files: acc.candidate_files + item.candidate_files,
+    updated_files: acc.updated_files + item.updated_files,
+    skipped_compatible_files: acc.skipped_compatible_files + item.skipped_compatible_files,
+    parse_error_files: acc.parse_error_files + item.parse_error_files
+  }), {
+    total_files: 0,
+    candidate_files: 0,
+    updated_files: 0,
+    skipped_compatible_files: 0,
+    parse_error_files: 0
+  });
+
+  const nowValue = now();
+  return {
+    mode: 'auto-schema-migrate',
+    generated_at: nowValue instanceof Date ? nowValue.toISOString() : new Date(nowValue).toISOString(),
+    dry_run: dryRun,
+    target_version: targetVersion,
+    scope,
+    summary: totals,
+    archives
+  };
+}
+
+module.exports = {
+  normalizeSchemaScope,
+  normalizeTargetSchemaVersion,
+  getAutoArchiveSchemaTargets,
+  classifyArchiveSchemaCompatibility,
+  checkAutoArchiveSchema,
+  migrateAutoArchiveSchema
+};

package/lib/auto/archive-summary.js

@@ -0,0 +1,60 @@
+function normalizeStatusToken(statusCandidate) {
+  return String(statusCandidate || '').trim().toLowerCase();
+}
+
+function isCompletedStatus(statusCandidate) {
+  return normalizeStatusToken(statusCandidate) === 'completed';
+}
+
+function isFailedStatus(statusCandidate) {
+  return ['failed', 'partial-failed', 'error', 'invalid'].includes(normalizeStatusToken(statusCandidate));
+}
+
+function normalizeStatsWindowDays(daysCandidate) {
+  if (daysCandidate === undefined || daysCandidate === null) {
+    return null;
+  }
+  const parsed = Number(daysCandidate);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 36500) {
+    throw new Error('--days must be an integer between 0 and 36500.');
+  }
+  return parsed;
+}
+
+function filterEntriesByStatus(entries, statusFilter = []) {
+  if (!Array.isArray(statusFilter) || statusFilter.length === 0) {
+    return Array.isArray(entries) ? entries : [];
+  }
+  const statusSet = new Set(statusFilter.map((item) => normalizeStatusToken(item)).filter(Boolean));
+  return (Array.isArray(entries) ? entries : []).filter((entry) => statusSet.has(normalizeStatusToken(entry && entry.status)));
+}
+
+function filterGovernanceEntriesByResumeMode(entries, resumeOnly = false) {
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  if (!resumeOnly) {
+    return safeEntries;
+  }
+  return safeEntries.filter((entry) => (
+    typeof (entry && entry.resumed_from_governance_session_id) === 'string' &&
+    String(entry.resumed_from_governance_session_id).trim().length > 0
+  ));
+}
+
+function calculatePercent(numerator, denominator) {
+  const safeNumerator = Number(numerator) || 0;
+  const safeDenominator = Number(denominator) || 0;
+  if (safeDenominator <= 0) {
+    return 0;
+  }
+  return Number(((safeNumerator / safeDenominator) * 100).toFixed(2));
+}
+
+module.exports = {
+  normalizeStatusToken,
+  isCompletedStatus,
+  isFailedStatus,
+  normalizeStatsWindowDays,
+  filterEntriesByStatus,
+  filterGovernanceEntriesByResumeMode,
+  calculatePercent
+};