@aifabrix/builder 2.54.1 → 2.55.0

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

@@ -0,0 +1,291 @@
+/**
+ * Map role-assistant test results to expected lifecycleState tokens.
+ * @fileoverview Prefer work.result completion over coarse work.status.
+ */
+
+'use strict';
+
+const { VERDICT } = require('../lifecycle/product-model');
+
+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'
+});
+const COMPLETION_STATE_TO_LIFECYCLE = Object.freeze({
+  safestopped: 'safe-stop',
+  safe_stopped: 'safe-stop',
+  cancelled: 'rejected',
+  canceled: 'rejected',
+  completed: 'completed',
+  waiting: 'question'
+});
+const STEP_SIGNAL_FIELDS = [
+  'lifecycleState',
+  'state',
+  'status',
+  'code',
+  'errorCode',
+  'reason',
+  'kind',
+  'type',
+  'error',
+  'failure',
+  'details',
+  'result'
+];
+const OBJECT_SIGNAL_FIELDS = [
+  'lifecycleState',
+  'state',
+  'status',
+  'code',
+  'type',
+  'reason',
+  'kind',
+  'category',
+  'errorCode'
+];
+const TOP_LEVEL_SIGNAL_PATHS = [
+  'lifecycleState',
+  'state',
+  'status',
+  'lifecycle.state',
+  'report.lifecycleState',
+  'report.state',
+  'report.status',
+  'report.lifecycle.state',
+  'report.runtime.state',
+  'report.work.state'
+];
+
+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)) {
+    return firstLifecycleFromValues(value);
+  }
+  if (typeof value === 'object') {
+    return firstLifecycleFromValues(OBJECT_SIGNAL_FIELDS.map((field) => value[field]));
+  }
+  return null;
+}
+
+function firstLifecycleFromValues(values) {
+  for (const candidate of values) {
+    const state = lifecycleStateFromSignalValue(candidate);
+    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 workResultCompletionObject(result) {
+  const workResult =
+    result?.workResult && typeof result.workResult === 'object' ? result.workResult : null;
+  const completion =
+    workResult?.completion && typeof workResult.completion === 'object'
+      ? workResult.completion
+      : null;
+  return { workResult, completion };
+}
+
+function mapWorkResultCompletionToLifecycle(result) {
+  const { workResult, completion } = workResultCompletionObject(result);
+  const state = normalizeLifecycleStateToken(completion?.state);
+  if (!workResult || !completion || !state) {
+    return null;
+  }
+  if (state === 'failed') {
+    return workResultSignalsRejected(workResult) ? 'rejected' : 'failed';
+  }
+  return COMPLETION_STATE_TO_LIFECYCLE[state] || lifecycleStateFromToken(state);
+}
+
+function completionReasonBag(processExecution) {
+  const pe = processExecution && typeof processExecution === 'object' ? processExecution : {};
+  if (pe.completionReason && typeof pe.completionReason === 'object') {
+    return pe.completionReason;
+  }
+  if (pe.completion_reason && typeof pe.completion_reason === 'object') {
+    return pe.completion_reason;
+  }
+  return {};
+}
+
+function workResultSignalsRejected(workResult) {
+  const reasonBag = completionReasonBag(workResult?.processExecution);
+  const kind = normalizeLifecycleStateToken(reasonBag.kind || reasonBag.Kind);
+  if (kind === 'rejected' || kind === 'denied' || kind === 'unauthorized') {
+    return true;
+  }
+  const text = [
+    reasonBag.summary,
+    workResult?.completion?.businessLanguage?.reason,
+    workResult?.completion?.businessLanguage?.summary,
+    workResult?.completion?.businessLanguage?.outcomeState,
+    workResult?.task?.resultSummary
+  ]
+    .filter((row) => typeof row === 'string' && row.trim())
+    .join(' ')
+    .toLowerCase();
+  return /\b(trust|authority|denied|rejected|unauthorized|not authorized)\b/.test(text);
+}
+
+function valueAtDottedPath(source, dottedPath) {
+  return dottedPath.split('.').reduce((cursor, key) => {
+    if (!cursor || typeof cursor !== 'object') {
+      return undefined;
+    }
+    return cursor[key];
+  }, source);
+}
+
+function lifecycleStateFromStepsRun(result) {
+  const steps = Array.isArray(result?.stepsRun) ? result.stepsRun : [];
+  for (const row of steps) {
+    const state = firstLifecycleFromValues(STEP_SIGNAL_FIELDS.map((field) => row?.[field]));
+    if (state) {
+      return state;
+    }
+  }
+  return null;
+}
+
+function resolveLifecycleStateFromResult(result) {
+  // Prefer governed work.result completion over coarse work.status "stopped"
+  // (which collapses failed + safeStopped + cancelled into safe-stop).
+  return (
+    mapWorkResultCompletionToLifecycle(result) ||
+    mapWorkStatusFromResult(result) ||
+    mapWorkerTaskStateFromResult(result) ||
+    firstLifecycleFromValues(TOP_LEVEL_SIGNAL_PATHS.map((path) => valueAtDottedPath(result, path))) ||
+    lifecycleStateFromStepsRun(result)
+  );
+}
+
+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';
+}
+
+module.exports = {
+  SUPPORTED_LIFECYCLE_STATES,
+  deriveLifecycleState
+};

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

@@ -0,0 +1,122 @@
+/**
+ * Graph hop assertions for expected.search (one-level related records).
+ *
+ * @fileoverview Evaluate graphDepth, relatedTypes, and related.minRows
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function relatedRows(payload, resourceType) {
+  const related = asObject(asObject(payload).related);
+  if (!Object.prototype.hasOwnProperty.call(related, resourceType)) {
+    return null;
+  }
+  const bundle = related[resourceType];
+  if (Array.isArray(bundle)) {
+    return bundle;
+  }
+  if (bundle && Array.isArray(bundle.data)) {
+    return bundle.data;
+  }
+  return [];
+}
+
+function relatedMeta(payload, resourceType) {
+  const bundle = asObject(asObject(payload).related)[resourceType];
+  return asObject(asObject(bundle).meta);
+}
+
+function evaluateGraphDepth(expectedSearch, meta) {
+  if (!Number.isFinite(Number(expectedSearch.graphDepth))) {
+    return null;
+  }
+  const expected = Number(expectedSearch.graphDepth);
+  const actual = Number(meta.graphDepth);
+  const passed = actual === expected;
+  return {
+    id: 'expected.search.graphDepth',
+    passed,
+    message: passed
+      ? `Search graphDepth matched ${expected}.`
+      : `Search graphDepth expected ${expected} but got ${Number.isFinite(actual) ? actual : 'none'}.`
+  };
+}
+
+function evaluateRelatedTypes(expectedTypes, meta) {
+  if (!Array.isArray(expectedTypes) || expectedTypes.length === 0) {
+    return [];
+  }
+  const observed = Array.isArray(meta.relatedTypes) ? meta.relatedTypes.map(String) : [];
+  return expectedTypes.map((item) => {
+    const key = String(item || '').trim();
+    const passed = Boolean(key && observed.includes(key));
+    return {
+      id: `expected.search.relatedTypes:${key}`,
+      passed,
+      message: passed
+        ? `Search relatedTypes included "${key}".`
+        : `Search relatedTypes did not include "${key}".`
+    };
+  });
+}
+
+function evaluateRelatedHop(resourceType, spec, payload) {
+  const assertions = [];
+  const rows = relatedRows(payload, resourceType);
+  if (Number.isFinite(Number(spec.minRows))) {
+    const minRows = Number(spec.minRows);
+    if (rows === null) {
+      assertions.push({
+        id: `expected.search.related.${resourceType}.minRows`,
+        passed: false,
+        message: `Related "${resourceType}" was omitted from the search graph.`
+      });
+    } else {
+      const passed = rows.length >= minRows;
+      assertions.push({
+        id: `expected.search.related.${resourceType}.minRows`,
+        passed,
+        message: passed
+          ? `Related "${resourceType}" returned at least ${minRows} row(s).`
+          : `Related "${resourceType}" returned ${rows.length} row(s); expected at least ${minRows}.`
+      });
+    }
+  }
+  if (spec.resultMode) {
+    const actual = String(relatedMeta(payload, resourceType).resultMode || '');
+    const passed = rows !== null && actual === String(spec.resultMode);
+    assertions.push({
+      id: `expected.search.related.${resourceType}.resultMode`,
+      passed,
+      message: passed
+        ? `Related "${resourceType}" resultMode matched "${spec.resultMode}".`
+        : `Related "${resourceType}" resultMode expected "${spec.resultMode}" but got "${actual || 'omitted'}".`
+    });
+  }
+  return assertions;
+}
+
+function evaluateSearchGraphExpectations(expectedSearch, payload, meta) {
+  const assertions = [];
+  const depth = evaluateGraphDepth(expectedSearch, meta);
+  if (depth) {
+    assertions.push(depth);
+  }
+  assertions.push(...evaluateRelatedTypes(expectedSearch.relatedTypes, meta));
+  const related = asObject(expectedSearch.related);
+  for (const resourceType of Object.keys(related)) {
+    const spec = asObject(related[resourceType]);
+    assertions.push(...evaluateRelatedHop(resourceType, spec, payload));
+  }
+  return assertions;
+}
+
+module.exports = {
+  evaluateSearchGraphExpectations
+};

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

@@ -9,6 +9,8 @@
 'use strict';
 
 const { operationKeys } = require('./test-runner-search');
+const { skillsEnvelope } = require('../search/search-skills');
+const { evaluateSearchGraphExpectations } = require('./test-cases-search-graph');
 
 function asObject(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -128,11 +130,19 @@ function evaluateSearchExpectations(expectedSearch, observation) {
     assertions.push(errorAssertion);
   }
   assertions.push(...evaluateSearchShape(expectedSearch, searchObs));
+  assertions.push(
+    ...evaluateSearchGraphExpectations(
+      expectedSearch,
+      searchObs.payload,
+      searchMeta(searchObs.payload)
+    )
+  );
   return assertions;
 }
 
 function skillsResourceEntry(skillsPayload, resourceType) {
-  const rts = asObject(asObject(skillsPayload).search).resourceTypes;
+  const root = skillsEnvelope(skillsPayload) || asObject(skillsPayload);
+  const rts = asObject(asObject(root).search).resourceTypes;
   return asObject(asObject(rts)[resourceType]);
 }
 
@@ -208,7 +218,15 @@ function evaluateSkillsExpectations(expectedSkills, observation) {
         : `work.skills did not publish resourceType "${resourceType}".`
     });
   }
-  if (expectedSkills.operationRequired === true) {
+  if (expectedSkills.operationRequired === false) {
+    assertions.push({
+      id: 'expected.skills.operationRequired',
+      passed: true,
+      skip: true,
+      kind: 'skip',
+      message: 'operationRequired is false — check skipped.'
+    });
+  } else if (expectedSkills.operationRequired === true) {
     const passed = spec.operationRequired === true;
     assertions.push({
       id: 'expected.skills.operationRequired',