@aifabrix/builder 2.54.1 → 2.55.0

package/lib/role-assistant/test-cases.js

@@ -8,11 +8,14 @@ const path = require('path');
 const fs = require('../internal/fs-real-sync');
 const yaml = require('js-yaml');
 const { resolveExternalSystemPath } = require('../utils/app-path-resolve');
-const { VERDICT } = require('../lifecycle/product-model');
 const {
   buildHonestyObservation,
   evaluateHonestyExpectations
 } = require('./test-cases-honesty');
+const {
+  SUPPORTED_LIFECYCLE_STATES,
+  deriveLifecycleState
+} = require('./test-cases-lifecycle');
 function loadNodeFsSnapshot() {
   if (global.__AIFABRIX_NODE_FS_UNMOCKED__) {
     return global.__AIFABRIX_NODE_FS_UNMOCKED__;
@@ -22,32 +25,6 @@ function loadNodeFsSnapshot() {
     : require('node:fs');
 }
 const nodeFs = loadNodeFsSnapshot();
-const SUPPORTED_LIFECYCLE_STATES = new Set(['completed', 'question', 'approval-required', 'dependency', 'safe-stop', 'rejected', 'failed']);
-const LIFECYCLE_STATE_ALIASES = Object.freeze({
-  completed: ['completed', 'complete', 'done', 'success', 'verified'],
-  question: ['question', 'question_required', 'awaiting_question', 'pending_question'],
-  'approval-required': ['approval_required', 'awaiting_approval', 'pending_approval', 'requires_approval'],
-  dependency: ['dependency', 'dependency_wait', 'dependency_blocked', 'awaiting_dependency'],
-  'safe-stop': ['safe_stop', 'safe_stopped', 'policy_blocked', 'halted', 'paused'],
-  rejected: ['rejected', 'denied', 'declined', 'policy_rejected'],
-  failed: ['failed', 'error', 'errored', 'timeout', 'cancelled', 'canceled']
-});
-
-const WORK_STATUS_TO_LIFECYCLE = Object.freeze({
-  completed: 'completed', waiting: 'question', running: 'dependency', stopped: 'safe-stop'
-});
-const WAIT_REASON_TO_LIFECYCLE = Object.freeze({
-  ask: 'question', approval: 'approval-required', ownerroute: 'dependency',
-  realityconfirm: 'question', knowledgeconfirm: 'question'
-});
-const WORKER_TASK_STATUS_TO_LIFECYCLE = Object.freeze({
-  draft: 'dependency', pendingapproval: 'approval-required', approved: 'dependency',
-  running: 'dependency', completed: 'completed', failed: 'failed',
-  cancelled: 'rejected', canceled: 'rejected'
-});
-const WORKER_APPROVAL_STATE_TO_LIFECYCLE = Object.freeze({
-  pending: 'approval-required', approved: 'dependency', rejected: 'rejected'
-});
 function safeExistsSync(filePath) {
   // Prefer unmocked node:fs so Jest worker fs mocks cannot hide real temp files.
   return nodeFs.existsSync(filePath) || fs.existsSync(filePath);
@@ -105,6 +82,7 @@ function normalizeCaseFromFile(filePath, parsed) {
     answers: Array.isArray(parsed.answers) ? parsed.answers : [],
     approvals: Array.isArray(parsed.approvals) ? parsed.approvals : [],
     expected,
+    metadata: parsed.metadata && typeof parsed.metadata === 'object' ? parsed.metadata : {},
     preflight: parsed.preflight && typeof parsed.preflight === 'object' ? parsed.preflight : {},
     sourceFile: filePath
   };
@@ -202,150 +180,11 @@ function loadRoleAssistantTestCase(roleKey, selector, options = {}) {
     throw new Error(`Role assistant test case ${lookup} not found in ${testsDir}`);
   }
   const parsed = parseCaseYamlFile(filePath);
+  const { assertTestCaseDocument } = require('./test-case-validate');
+  assertTestCaseDocument(parsed, filePath);
   return normalizeCaseFromFile(filePath, parsed);
 }
 
-function normalizeLifecycleStateToken(value) {
-  if (typeof value !== 'string') {
-    return '';
-  }
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '_')
-    .replace(/^_+|_+$/g, '');
-}
-
-function lifecycleStateFromToken(token) {
-  if (!token) {
-    return null;
-  }
-  for (const [state, aliases] of Object.entries(LIFECYCLE_STATE_ALIASES)) {
-    for (const alias of aliases) {
-      if (token === alias || token.startsWith(`${alias}_`)) {
-        return state;
-      }
-    }
-  }
-  return null;
-}
-
-function lifecycleStateFromSignalValue(value) {
-  if (value === null || value === undefined) {
-    return null;
-  }
-  if (typeof value === 'string') {
-    return lifecycleStateFromToken(normalizeLifecycleStateToken(value));
-  }
-  if (Array.isArray(value)) {
-    for (const row of value) {
-      const state = lifecycleStateFromSignalValue(row);
-      if (state) {
-        return state;
-      }
-    }
-    return null;
-  }
-  if (typeof value === 'object') {
-    const fields = [
-      'lifecycleState',
-      'state',
-      'status',
-      'code',
-      'type',
-      'reason',
-      'kind',
-      'category',
-      'errorCode'
-    ];
-    for (const field of fields) {
-      const state = lifecycleStateFromSignalValue(value[field]);
-      if (state) {
-        return state;
-      }
-    }
-  }
-  return null;
-}
-
-function mapWorkStatusFromResult(result) {
-  const rawStatus = normalizeLifecycleStateToken(result?.status);
-  if (rawStatus && WORK_STATUS_TO_LIFECYCLE[rawStatus]) {
-    const waitReason = normalizeLifecycleStateToken(result?.wait?.waitReason || '');
-    if (rawStatus === 'waiting' && waitReason && WAIT_REASON_TO_LIFECYCLE[waitReason]) {
-      return WAIT_REASON_TO_LIFECYCLE[waitReason];
-    }
-    return WORK_STATUS_TO_LIFECYCLE[rawStatus];
-  }
-  return null;
-}
-
-function mapWorkerTaskStateFromResult(result) {
-  const statusCandidates = [result?.task?.status, result?.status, result?.workerTask?.status];
-  for (const row of statusCandidates) {
-    const token = normalizeLifecycleStateToken(row);
-    if (token && WORKER_TASK_STATUS_TO_LIFECYCLE[token]) {
-      return WORKER_TASK_STATUS_TO_LIFECYCLE[token];
-    }
-  }
-  const approvalCandidates = [result?.task?.approvalState, result?.approvalState, result?.workerTask?.approvalState];
-  for (const row of approvalCandidates) {
-    const token = normalizeLifecycleStateToken(row);
-    if (token && WORKER_APPROVAL_STATE_TO_LIFECYCLE[token]) {
-      return WORKER_APPROVAL_STATE_TO_LIFECYCLE[token];
-    }
-  }
-  return null;
-}
-
-function resolveLifecycleStateFromResult(result) {
-  const workState = mapWorkStatusFromResult(result);
-  if (workState) {
-    return workState;
-  }
-  const workerTaskState = mapWorkerTaskStateFromResult(result);
-  if (workerTaskState) {
-    return workerTaskState;
-  }
-  const topLevelCandidates = [
-    result?.lifecycleState, result?.state, result?.status, result?.lifecycle?.state,
-    result?.report?.lifecycleState, result?.report?.state, result?.report?.status,
-    result?.report?.lifecycle?.state, result?.report?.runtime?.state, result?.report?.work?.state
-  ];
-  for (const candidate of topLevelCandidates) {
-    const state = lifecycleStateFromSignalValue(candidate);
-    if (state) {
-      return state;
-    }
-  }
-  const steps = Array.isArray(result?.stepsRun) ? result.stepsRun : [];
-  for (const row of steps) {
-    const stepCandidates = [
-      row?.lifecycleState, row?.state, row?.status, row?.code, row?.errorCode, row?.reason,
-      row?.kind, row?.type, row?.error, row?.failure, row?.details, row?.result
-    ];
-    for (const candidate of stepCandidates) {
-      const state = lifecycleStateFromSignalValue(candidate);
-      if (state) {
-        return state;
-      }
-    }
-  }
-  return null;
-}
-
-function deriveLifecycleState(result, lifecycleVerdict) {
-  if (lifecycleVerdict === VERDICT.VERIFIED) {
-    return 'completed';
-  }
-  const structuredState = resolveLifecycleStateFromResult(result);
-  if (structuredState) {
-    return structuredState;
-  }
-  if (lifecycleVerdict === VERDICT.NOT_VERIFIED) return 'safe-stop';
-  return 'failed';
-}
-
 function addCapabilityToken(set, value) {
   if (typeof value === 'string' && value.trim()) set.add(value.trim());
 }
@@ -361,9 +200,34 @@ function collectCapabilitiesFromWorkSteps(out, steps) {
       addCapabilityToken(out, row.executionOutcome.capabilityKey);
       addCapabilityToken(out, row.executionOutcome.capability);
     }
+    const execution = row.capabilityExecution;
+    if (execution && typeof execution === 'object') {
+      addCapabilityToken(out, execution.capabilityKey);
+      addCapabilityToken(out, execution.capability);
+    }
   }
 }
 
+/**
+ * Identity-preflight CIP fallback uses operationId "operation" (or omits it).
+ * That is a Reality probe log, not an observed write capability.
+ * @param {object} row
+ * @returns {boolean}
+ */
+function cipArtifactIsUnspecifiedOperation(row) {
+  const fingerprint = typeof row.fingerprint === 'string' ? row.fingerprint : '';
+  const opMatch = fingerprint.match(/(?:^|[|,])operationId=([^|,]+)/);
+  if (opMatch) {
+    const operationId = opMatch[1].trim();
+    return !operationId || operationId === 'operation';
+  }
+  const artifactRef = typeof row.artifactRef === 'string' ? row.artifactRef : '';
+  if (/^cip-log:[^:]+:[^:]+:operation:/.test(artifactRef)) {
+    return true;
+  }
+  return /(?:^|[|,])capabilityKey=/.test(fingerprint);
+}
+
 /**
  * Work-result artifactIndex often carries CIP fingerprints like
  * `capabilityKey=customer.createBasic|operationId=createbasic` when steps[] is empty.
@@ -374,6 +238,7 @@ function collectCapabilitiesFromArtifactIndex(out, artifacts) {
   if (!Array.isArray(artifacts)) return;
   for (const row of artifacts) {
     if (!row || typeof row !== 'object') continue;
+    if (cipArtifactIsUnspecifiedOperation(row)) continue;
     addCapabilityToken(out, row.capabilityKey);
     addCapabilityToken(out, row.capability);
     const fingerprint = typeof row.fingerprint === 'string' ? row.fingerprint : '';
@@ -414,6 +279,7 @@ function collectObservedCapabilities(result) {
 module.exports = {
   SUPPORTED_LIFECYCLE_STATES,
   roleAssistantTestsDir,
+  listTestCaseFiles,
   loadRoleAssistantTestCase,
   deriveLifecycleState,
   collectObservedCapabilities,

package/lib/role-assistant/test-pack-map.js

@@ -0,0 +1,180 @@
+/**
+ * Map local Role Assistant YAML cases to a published test pack (and back).
+ *
+ * @fileoverview YAML specification only — currentStatus stays on dataplane
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const yaml = require('js-yaml');
+const fs = require('../internal/fs-real-sync');
+const { roleAssistantTestsDir } = require('./test-cases');
+const { discoverSuiteCaseFiles } = require('./test-suite');
+const { roleAssistantSystemKey } = require('../utils/role-assistant-paths');
+
+const PACK_API_VERSION = 'dataplane.aifabrix.ai/v1';
+const PACK_KIND = 'RoleAssistantTestPack';
+const STATUS_KEYS = new Set(['currentStatus', 'lastTestedAt', 'summary', 'sourceFile']);
+const YAML_SPEC_KEYS = [
+  'caseId',
+  'input',
+  'answers',
+  'approvals',
+  'expected',
+  'preflight',
+  'metadata'
+];
+const PACK_INPUT_ALIASES = ['executionPath', 'roleRef', 'businessRoleRef'];
+
+function isYamlName(name) {
+  return /\.(ya?ml)$/i.test(name);
+}
+
+function listRootYamlFiles(testsDir) {
+  if (!fs.existsSync(testsDir)) {
+    return [];
+  }
+  return fs.readdirSync(testsDir)
+    .filter((name) => isYamlName(name))
+    .map((name) => path.join(testsDir, name));
+}
+
+function copySpecFields(parsed, caseId) {
+  const out = { caseId };
+  for (const key of YAML_SPEC_KEYS) {
+    if (key === 'caseId' || parsed[key] === undefined) {
+      continue;
+    }
+    out[key] = parsed[key];
+  }
+  const input = out.input && typeof out.input === 'object' && !Array.isArray(out.input)
+    ? out.input
+    : {};
+  for (const key of PACK_INPUT_ALIASES) {
+    if (input[key] !== undefined) {
+      out[key] = input[key];
+    }
+  }
+  return out;
+}
+
+function specCaseFromFile(filePath) {
+  const parsed = yaml.load(fs.readFileSync(filePath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Test case must be an object: ${filePath}`);
+  }
+  const fileBase = path.basename(filePath, path.extname(filePath));
+  const caseId = String(parsed.caseId || fileBase).trim();
+  if (!caseId) {
+    throw new Error(`Test case is missing caseId: ${filePath}`);
+  }
+  return copySpecFields(parsed, caseId);
+}
+
+function collectSuiteMap(testsDir) {
+  const suites = new Map();
+  const add = (suiteId, filePath) => {
+    const id = String(suiteId || 'default').trim() || 'default';
+    if (!suites.has(id)) {
+      suites.set(id, []);
+    }
+    suites.get(id).push(specCaseFromFile(filePath));
+  };
+  for (const filePath of listRootYamlFiles(testsDir)) {
+    add('default', filePath);
+  }
+  for (const row of discoverSuiteCaseFiles(testsDir)) {
+    add(row.suite, row.absPath);
+  }
+  return suites;
+}
+
+function buildRoleAssistantTestPack(systemKey, suiteMap) {
+  const key = roleAssistantSystemKey(systemKey);
+  const suites = [];
+  for (const [suiteId, cases] of suiteMap.entries()) {
+    if (cases.length > 0) {
+      suites.push({ suiteId, cases });
+    }
+  }
+  return {
+    apiVersion: PACK_API_VERSION,
+    kind: PACK_KIND,
+    metadata: { key },
+    spec: { suites }
+  };
+}
+
+function mapLocalTestsToPack(systemKey, options = {}) {
+  const testsDir = roleAssistantTestsDir(systemKey, options);
+  if (!fs.existsSync(testsDir)) {
+    return { skipped: true, reason: 'No tests folder' };
+  }
+  const suiteMap = collectSuiteMap(testsDir);
+  const pack = buildRoleAssistantTestPack(systemKey, suiteMap);
+  if (!pack.spec.suites.length) {
+    return { skipped: true, reason: 'No test cases in tests folder' };
+  }
+  return { skipped: false, pack, testsDir };
+}
+
+function mergePackAliasesIntoInput(packCase, input) {
+  const next = { ...input };
+  for (const key of PACK_INPUT_ALIASES) {
+    if (packCase[key] !== undefined && next[key] === undefined) {
+      next[key] = packCase[key];
+    }
+  }
+  return next;
+}
+
+function yamlFromPackCase(packCase) {
+  const body = {};
+  for (const key of YAML_SPEC_KEYS) {
+    if (packCase[key] === undefined || STATUS_KEYS.has(key)) {
+      continue;
+    }
+    body[key] = packCase[key];
+  }
+  const input = body.input && typeof body.input === 'object' && !Array.isArray(body.input)
+    ? body.input
+    : {};
+  const merged = mergePackAliasesIntoInput(packCase, input);
+  if (Object.keys(merged).length > 0) {
+    body.input = merged;
+  }
+  return yaml.dump(body, { lineWidth: 120, noRefs: true, sortKeys: false });
+}
+
+function writePackToTestsDir(pack, testsDir) {
+  const suites = pack && pack.spec && Array.isArray(pack.spec.suites) ? pack.spec.suites : [];
+  fs.mkdirSync(testsDir, { recursive: true });
+  let written = 0;
+  for (const suite of suites) {
+    const suiteId = String((suite && suite.suiteId) || 'default').trim() || 'default';
+    const suiteDir = path.join(testsDir, suiteId);
+    fs.mkdirSync(suiteDir, { recursive: true });
+    const cases = Array.isArray(suite.cases) ? suite.cases : [];
+    for (const row of cases) {
+      const caseId = String((row && row.caseId) || '').trim();
+      if (!caseId) {
+        continue;
+      }
+      fs.writeFileSync(path.join(suiteDir, `${caseId}.yaml`), yamlFromPackCase(row), 'utf8');
+      written += 1;
+    }
+  }
+  return written;
+}
+
+module.exports = {
+  PACK_API_VERSION,
+  PACK_KIND,
+  YAML_SPEC_KEYS,
+  mapLocalTestsToPack,
+  writePackToTestsDir,
+  specCaseFromFile
+};

package/lib/role-assistant/test-pack-sync.js

@@ -0,0 +1,187 @@
+/**
+ * Role Assistant test-pack sidecar: upload PUT, download GET, case status PATCH.
+ *
+ * @fileoverview Shared CLI and builder-api adapters — no Task/PE or /runs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const os = require('os');
+const path = require('path');
+const logger = require('../utils/logger');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { isDigitalWorkerKind } = require('../utils/platform-shell-package');
+const { roleAssistantTestsDir } = require('./test-cases');
+const { mapLocalTestsToPack, writePackToTestsDir } = require('./test-pack-map');
+const {
+  upsertRoleAssistantTestPack,
+  getRoleAssistantTestPack,
+  patchRoleAssistantTestCaseStatus
+} = require('../api/role-assistant-test-pack.api');
+const fs = require('../internal/fs-real-sync');
+
+function skipResult(reason) {
+  return { skipped: true, reason };
+}
+
+function isRoleAssistantPayload(payload) {
+  return isDigitalWorkerKind(payload && payload.application);
+}
+
+async function runTestsSidecar(ctx, sidecar, quietSidecar) {
+  if (!isRoleAssistantPayload(ctx.payload)) {
+    sidecar.tests = skipResult('Not a Role Assistant package');
+    return;
+  }
+  if (ctx.options && ctx.options.dryRun === true) {
+    sidecar.tests = skipResult('Dry run');
+    return;
+  }
+  const mapped = mapLocalTestsToPack(ctx.systemKey, {
+    pathOptions: (ctx.options && ctx.options.pathOptions) || {},
+    testsDir: ctx.options && ctx.options.testsDir
+  });
+  if (mapped.skipped) {
+    sidecar.tests = skipResult(mapped.reason);
+    return;
+  }
+  try {
+    const uploaded = await upsertRoleAssistantTestPack(
+      ctx.dataplaneUrl,
+      ctx.authConfig,
+      ctx.systemKey,
+      mapped.pack
+    );
+    sidecar.tests = {
+      skipped: false,
+      packVersion: uploaded && uploaded.packVersion,
+      packKey: uploaded && uploaded.packKey
+    };
+  } catch (err) {
+    sidecar.tests = skipResult(err.message || String(err));
+    if (!quietSidecar) {
+      logger.log(formatWarningLine(`Role assistant tests upload skipped: ${err.message}`));
+    }
+  }
+}
+
+async function exportRoleAssistantTests(params) {
+  const { systemKey, dataplaneUrl, authConfig, options = {} } = params;
+  const row = await getRoleAssistantTestPack(dataplaneUrl, authConfig, systemKey, {
+    allowMissing: true
+  });
+  if (!row || !row.pack) {
+    return skipResult('No published test pack');
+  }
+  const testsDir = roleAssistantTestsDir(systemKey, {
+    pathOptions: options.pathOptions || {},
+    testsDir: options.testsDir
+  });
+  const written = writePackToTestsDir(row.pack, testsDir);
+  return { skipped: false, written, testsDir };
+}
+
+function publishedTestsOwnerToken() {
+  if (typeof process.getuid === 'function') {
+    return String(process.getuid());
+  }
+  return 'u';
+}
+
+function publishedTestsTempDir(systemKey) {
+  const key = String(systemKey || 'pack').replace(/[^a-zA-Z0-9._-]+/g, '_');
+  return path.join(os.tmpdir(), `aifabrix-ra-tests-${publishedTestsOwnerToken()}`, key);
+}
+
+async function materializePublishedTests(systemKey, dataplaneUrl, authConfig, destRoot) {
+  const row = await getRoleAssistantTestPack(dataplaneUrl, authConfig, systemKey, {
+    allowMissing: true
+  });
+  if (!row || !row.pack) {
+    throw new Error(
+      `No published tests for ${systemKey}. Upload the Role Assistant package first.`
+    );
+  }
+  if (fs.existsSync(destRoot)) {
+    fs.rmSync(destRoot, { recursive: true, force: true });
+  }
+  const written = writePackToTestsDir(row.pack, destRoot);
+  return { testsDir: destRoot, written };
+}
+
+function caseStatusFromEvaluation(evaluation) {
+  if (!evaluation) {
+    return 'skipped';
+  }
+  if (evaluation.passed === true) {
+    return 'passed';
+  }
+  if (evaluation.passed === false) {
+    return 'failed';
+  }
+  return 'skipped';
+}
+
+function caseSummaryFromEvaluation(evaluation) {
+  if (!evaluation) {
+    return undefined;
+  }
+  const summary = evaluation.summary || evaluation.reason || evaluation.error;
+  return typeof summary === 'string' && summary.trim() ? summary.trim() : undefined;
+}
+
+async function loadPublishedTestsIntoOptions(systemKey, opts, authContext) {
+  if (!opts || opts.fromDataplane !== true) {
+    return opts;
+  }
+  const dest = publishedTestsTempDir(systemKey);
+  await materializePublishedTests(
+    systemKey,
+    authContext.dataplaneUrl,
+    authContext.authConfig,
+    dest
+  );
+  return { ...opts, casesRoot: dest, testsDir: dest };
+}
+
+async function patchCaseStatusAfterRun(params) {
+  const { systemKey, caseId, evaluation, dataplaneUrl, authConfig } = params;
+  if (!dataplaneUrl || !authConfig || !caseId) {
+    return { skipped: true, reason: 'Missing dataplane context' };
+  }
+  const body = {
+    status: caseStatusFromEvaluation(evaluation),
+    testedAt: new Date().toISOString()
+  };
+  const summary = caseSummaryFromEvaluation(evaluation);
+  if (summary) {
+    body.summary = summary;
+  }
+  try {
+    await patchRoleAssistantTestCaseStatus(
+      dataplaneUrl,
+      authConfig,
+      systemKey,
+      caseId,
+      body
+    );
+    return { skipped: false, status: body.status };
+  } catch (err) {
+    logger.log(
+      formatWarningLine(`Could not update published case status for ${caseId}: ${err.message}`)
+    );
+    return { skipped: true, reason: err.message || String(err) };
+  }
+}
+
+module.exports = {
+  runTestsSidecar,
+  exportRoleAssistantTests,
+  publishedTestsTempDir,
+  materializePublishedTests,
+  loadPublishedTestsIntoOptions,
+  caseStatusFromEvaluation,
+  patchCaseStatusAfterRun
+};

package/lib/role-assistant/test-runner-debug.js

@@ -0,0 +1,54 @@
+/**
+ * Role assistant --debug Work Result fetch and log persistence.
+ *
+ * @fileoverview Technical work-result depth and logs under role-assistant/<role>/logs/
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { getWorkExecutionResult } = require('../api/work.api');
+const { sanitizeForLog } = require('../utils/test-log-writer');
+const {
+  getRoleAssistantPath,
+  roleAssistantSystemKey
+} = require('../utils/role-assistant-paths');
+
+function requestedWorkResultDepth(options) {
+  return options && options.debug === true ? 'technical' : 'business';
+}
+
+async function fetchWorkHubResult(dataplaneUrl, authConfig, processExecutionId, options = {}) {
+  try {
+    const workResult = await getWorkExecutionResult(dataplaneUrl, authConfig, processExecutionId, {
+      requestedDepth: requestedWorkResultDepth(options),
+      format: 'json'
+    });
+    return { workResult, workResultError: null };
+  } catch (error) {
+    return { workResult: null, workResultError: error.message || String(error) };
+  }
+}
+
+function persistRoleAssistantDebugLog(roleKey, payload, options = {}) {
+  if (!options || options.debug !== true) {
+    return null;
+  }
+  const systemKey = roleAssistantSystemKey(roleKey);
+  const logsDir = path.join(getRoleAssistantPath(systemKey), 'logs');
+  fs.mkdirSync(logsDir, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const filePath = path.join(logsDir, `work-result-technical-${timestamp}.json`);
+  const sanitized = sanitizeForLog(payload);
+  fs.writeFileSync(filePath, `${JSON.stringify(sanitized, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+module.exports = {
+  requestedWorkResultDepth,
+  fetchWorkHubResult,
+  persistRoleAssistantDebugLog
+};