@bpmsoftwaresolutions/ai-engine-client 1.1.87 → 1.1.88

package/src/domains/workflow-composition.js

@@ -1,11 +1,3420 @@
+import { cleanText, isPlainObject } from '../utils/communication.js';
+
+function cleanList(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => cleanText(item)).filter(Boolean);
+}
+
+function looksLikeUuid(value) {
+  const text = cleanText(value);
+  return Boolean(text && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(text));
+}
+
+function countRoadmapProjectionLines(markdown) {
+  const lines = [];
+  let inSummary = false;
+  for (const line of String(markdown || '').split(/\r?\n/)) {
+    if (line.startsWith('## Roadmap Summary')) {
+      inSummary = true;
+      continue;
+    }
+    if (inSummary && line.startsWith('## ')) {
+      break;
+    }
+    if (inSummary && line.startsWith('- ')) {
+      lines.push(line);
+    }
+  }
+  const wanted = [
+    'Total Items',
+    'Total Tasks',
+    'Total Subtasks',
+    'Total Acceptance Checks',
+    'Open Acceptance Checks',
+    'Completion Percentage',
+  ];
+  return lines.filter((line) => wanted.some((label) => line.startsWith(`- ${label}:`)));
+}
+
 export function createWorkflowCompositionDomain(client) {
   return {
-    registerModernizationAsset: (request) => client.registerModernizationAsset(request),
-    classifyModernizationAsset: (request) => client.classifyModernizationAsset(request),
-    discoverSalvageCandidates: (request) => client.discoverSalvageCandidates(request),
-    createModernizationWorkPacket: (request) => client.createModernizationWorkPacket(request),
-    requestModernizationWrapperExecution: (request) => client.requestModernizationWrapperExecution(request),
-    getModernizationWrapperEvidence: (request) => client.getModernizationWrapperEvidence(request),
-    decideModernizationGate: (request) => client.decideModernizationGate(request),
+    registerModernizationAsset: (request) => registerModernizationAsset(client, request),
+    classifyModernizationAsset: (request) => classifyModernizationAsset(client, request),
+    discoverSalvageCandidates: (request) => discoverSalvageCandidates(client, request),
+    createModernizationWorkPacket: (request) => createModernizationWorkPacket(client, request),
+    requestModernizationWrapperExecution: (request) => requestModernizationWrapperExecution(client, request),
+    getModernizationWrapperEvidence: (request) => getModernizationWrapperEvidence(client, request),
+    decideModernizationGate: (request) => decideModernizationGate(client, request),
+  };
+}
+
+export async function registerModernizationAsset(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  asset = {},
+  modernizationAsset = {},
+  assetName,
+  asset_name,
+  assetType,
+  asset_type,
+  sourceRef,
+  source_ref,
+  originSystem,
+  origin_system,
+  businessContext,
+  business_context,
+  suspectedValue,
+  suspected_value,
+  knownRisks = [],
+  known_risks = [],
+  evidenceRefs = [],
+  evidence_refs = [],
+  handoffNotes,
+  handoff_notes,
+  assignedClassifier,
+  assigned_classifier,
+  classificationRequired,
+  classification_required,
+  submittedBy,
+  submitted_by,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedAsset = isPlainObject(modernizationAsset)
+    ? modernizationAsset
+    : (isPlainObject(asset) ? asset : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedAsset.related_project_id)
+    || cleanText(normalizedAsset.relatedProjectId);
+  const normalizedAssetName = cleanText(asset_name) || cleanText(assetName) || cleanText(normalizedAsset.asset_name) || cleanText(normalizedAsset.assetName);
+  const normalizedAssetType = cleanText(asset_type) || cleanText(assetType) || cleanText(normalizedAsset.asset_type) || cleanText(normalizedAsset.assetType) || 'unknown';
+  const normalizedSourceRef = cleanText(source_ref) || cleanText(sourceRef) || cleanText(normalizedAsset.source_ref) || cleanText(normalizedAsset.sourceRef) || normalizedAssetName;
+  if (!normalizedAssetName && !normalizedSourceRef) {
+    throw new Error('asset_name or source_ref is required.');
+  }
+  const normalizedOriginSystem = cleanText(origin_system) || cleanText(originSystem) || cleanText(normalizedAsset.origin_system) || cleanText(normalizedAsset.originSystem);
+  const normalizedBusinessContext = cleanText(business_context) || cleanText(businessContext) || cleanText(normalizedAsset.business_context) || cleanText(normalizedAsset.businessContext);
+  const normalizedSuspectedValue = cleanText(suspected_value) || cleanText(suspectedValue) || cleanText(normalizedAsset.suspected_value) || cleanText(normalizedAsset.suspectedValue);
+  const normalizedKnownRisks = Array.isArray(known_risks)
+    ? known_risks
+    : (Array.isArray(knownRisks) ? knownRisks : normalizedAsset.known_risks || normalizedAsset.knownRisks || []);
+  const normalizedEvidenceRefs = Array.isArray(evidence_refs)
+    ? evidence_refs
+    : (Array.isArray(evidenceRefs) ? evidenceRefs : normalizedAsset.evidence_refs || normalizedAsset.evidenceRefs || []);
+  const normalizedHandoffNotes = cleanText(handoff_notes) || cleanText(handoffNotes) || cleanText(normalizedAsset.handoff_notes) || cleanText(normalizedAsset.handoffNotes);
+  const normalizedAssignedClassifier = cleanText(assigned_classifier)
+    || cleanText(assignedClassifier)
+    || cleanText(normalizedAsset.assigned_classifier)
+    || cleanText(normalizedAsset.assignedClassifier);
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedClassificationRequired = classification_required ?? classificationRequired ?? true;
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  } else {
+    throw new Error('projectIdentifier is required.');
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let assetIntakeRecord = null;
+  const assetIntakeSurface = typeof client.createModernizationAssetIntakeRecord === 'function'
+    ? client.createModernizationAssetIntakeRecord.bind(client)
+    : null;
+  if (!assetIntakeSurface) {
+    missingSurfaces.push('createModernizationAssetIntakeRecord');
+  } else {
+    assetIntakeRecord = await assetIntakeSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetName: normalizedAssetName,
+      assetType: normalizedAssetType,
+      sourceRef: normalizedSourceRef,
+      originSystem: normalizedOriginSystem,
+      businessContext: normalizedBusinessContext,
+      suspectedValue: normalizedSuspectedValue,
+      knownRisks: normalizedKnownRisks,
+      relatedProjectId: resolvedProjectId,
+      evidenceRefs: normalizedEvidenceRefs,
+      handoffNotes: normalizedHandoffNotes,
+      submittedBy: normalizedSubmittedBy,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'registerModernizationAsset',
+      },
+    });
+  }
+
+  let intakeObservation = null;
+  const observationSurface = typeof client.submitModernizationAssetObservation === 'function'
+    ? client.submitModernizationAssetObservation.bind(client)
+    : null;
+  if (!observationSurface) {
+    missingSurfaces.push('submitModernizationAssetObservation');
+  } else {
+    intakeObservation = await observationSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetName: normalizedAssetName,
+      assetType: normalizedAssetType,
+      sourceRef: normalizedSourceRef,
+      submittedBy: normalizedSubmittedBy,
+      observationKind: 'asset_intake',
+      observationState: 'registered',
+      observationSummary: normalizedBusinessContext || normalizedHandoffNotes || normalizedAssetName || normalizedSourceRef,
+      evidenceRefs: normalizedEvidenceRefs,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'registerModernizationAsset',
+      },
+    });
+  }
+
+  let transferResult = null;
+  let watchResult = null;
+  const classifierTransferNeeded = Boolean(normalizedClassificationRequired && normalizedAssignedClassifier);
+  if (classifierTransferNeeded) {
+    const transferSurface = typeof client.transferWorkPacket === 'function'
+      ? client.transferWorkPacket.bind(client)
+      : null;
+    if (!transferSurface) {
+      missingSurfaces.push('transferWorkPacket');
+    } else {
+      transferResult = await transferSurface({
+        workflowRunId: resolvedWorkflowRunId,
+        transferKind: 'upstream_remediation',
+        objective: `Classify modernization asset ${normalizedAssetName || normalizedSourceRef}`,
+        requestedOutcome: 'Review and classify the modernization asset intake.',
+        target: {
+          intent: 'upstream_remediation',
+          recipient_mode: 'agent_session',
+          preferred_agent_session_id: normalizedAssignedClassifier,
+          preferred_role_key: normalizedAssignedClassifier,
+        },
+        artifacts: normalizedSourceRef ? [normalizedSourceRef] : [],
+        issues: normalizedKnownRisks,
+        expected_evidence: normalizedEvidenceRefs,
+        preferred_modes: ['bundle', 'artifact_refs', 'inline_payload'],
+        capabilities: {},
+        sender_agent_session_id: normalizedSubmittedBy,
+        sender_actor_session_id: null,
+        message_kind: 'handoff',
+        subject: normalizedAssetName || normalizedSourceRef || 'Modernization asset intake',
+        body_markdown: normalizedHandoffNotes || normalizedBusinessContext || normalizedSuspectedValue,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'registerModernizationAsset',
+          asset_name: normalizedAssetName,
+          asset_type: normalizedAssetType,
+          source_ref: normalizedSourceRef,
+          origin_system: normalizedOriginSystem,
+        },
+      });
+    }
+  }
+
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+  const transferPacketId = cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+  const transferChannelId = cleanText(transferPayload.communication_transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.communication_transfer_channel?.channel_id)
+    || cleanText(transferPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.transfer_channel_id)
+    || cleanText(transferPayload.channel_id)
+    || null;
+
+  if (classifierTransferNeeded && transferChannelId && transferPacketId) {
+    const watchSurface = typeof client.startMessageWatch === 'function'
+      ? client.startMessageWatch.bind(client)
+      : null;
+    if (!watchSurface) {
+      missingSurfaces.push('startMessageWatch');
+    } else {
+      watchResult = await watchSurface({
+        transferChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedAssignedClassifier,
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          source_ref: normalizedSourceRef,
+          asset_type: normalizedAssetType,
+          classification_required: Boolean(normalizedClassificationRequired),
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedHandoffNotes || normalizedBusinessContext || normalizedSuspectedValue,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'registerModernizationAsset',
+        },
+      });
+    }
+  }
+
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+  const assetId = cleanText(assetIntakeRecord?.asset_id)
+    || cleanText(assetIntakeRecord?.assetId)
+    || cleanText(assetIntakeRecord?.intake_record_id)
+    || cleanText(assetIntakeRecord?.intakeRecordId)
+    || cleanText(assetIntakeRecord?.modernization_asset_id)
+    || cleanText(assetIntakeRecord?.modernizationAssetId)
+    || null;
+  const intakeRecordId = cleanText(assetIntakeRecord?.intake_record_id)
+    || cleanText(assetIntakeRecord?.intakeRecordId)
+    || cleanText(assetIntakeRecord?.asset_id)
+    || cleanText(assetIntakeRecord?.assetId)
+    || null;
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    asset_id: assetId,
+    intake_record_id: intakeRecordId,
+    asset_type: normalizedAssetType,
+    source_ref: normalizedSourceRef,
+    submitted_by: normalizedSubmittedBy,
+    classification_required: Boolean(normalizedClassificationRequired),
+    assigned_classifier: normalizedAssignedClassifier || null,
+    transfer_packet_id: transferPacketId,
+    watch_id: watchId,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      asset_intake_record: assetIntakeRecord,
+      intake_observation: intakeObservation,
+      transfer: transferPayload,
+      message_watch: watchPayload,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    transfer: transferPayload,
+    asset_intake_record: assetIntakeRecord,
+    intake_observation: intakeObservation,
+    message_watch: watchPayload,
+  };
+}
+
+export async function classifyModernizationAsset(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  asset = {},
+  modernizationAsset = {},
+  classification = {},
+  modernizationClassification = {},
+  assetId,
+  asset_id,
+  intakeRecordId,
+  intake_record_id,
+  assetType,
+  asset_type,
+  sourceRef,
+  source_ref,
+  classificationCategory,
+  classification_category,
+  domainArea,
+  domain_area,
+  reusePotential,
+  reuse_potential,
+  modernizationNeed,
+  modernization_need,
+  knownRisks = [],
+  known_risks = [],
+  evidenceRefs = [],
+  evidence_refs = [],
+  recommendedNextStep,
+  recommended_next_step,
+  classificationConfidence,
+  classification_confidence,
+  reviewRequired,
+  review_required,
+  assignedReviewer,
+  assigned_reviewer,
+  handoffNotes,
+  handoff_notes,
+  submittedBy,
+  submitted_by,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedAsset = isPlainObject(modernizationAsset)
+    ? modernizationAsset
+    : (isPlainObject(asset) ? asset : {});
+  const normalizedClassification = isPlainObject(modernizationClassification)
+    ? modernizationClassification
+    : (isPlainObject(classification) ? classification : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedAsset.related_project_id)
+    || cleanText(normalizedAsset.relatedProjectId)
+    || cleanText(normalizedClassification.related_project_id)
+    || cleanText(normalizedClassification.relatedProjectId);
+  const normalizedAssetId = cleanText(asset_id)
+    || cleanText(assetId)
+    || cleanText(intake_record_id)
+    || cleanText(intakeRecordId)
+    || cleanText(normalizedAsset.asset_id)
+    || cleanText(normalizedAsset.assetId)
+    || cleanText(normalizedAsset.intake_record_id)
+    || cleanText(normalizedAsset.intakeRecordId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedAsset.source_ref)
+    || cleanText(normalizedAsset.sourceRef)
+    || normalizedAssetId;
+  if (!normalizedAssetId && !normalizedSourceRef) {
+    throw new Error('asset_id, intake_record_id, or source_ref is required.');
+  }
+  const normalizedAssetType = cleanText(asset_type)
+    || cleanText(assetType)
+    || cleanText(normalizedAsset.asset_type)
+    || cleanText(normalizedAsset.assetType)
+    || 'unknown';
+  const normalizedClassificationCategory = cleanText(classification_category)
+    || cleanText(classificationCategory)
+    || cleanText(normalizedClassification.classification_category)
+    || cleanText(normalizedClassification.classificationCategory)
+    || 'uncategorized';
+  const normalizedDomainArea = cleanText(domain_area)
+    || cleanText(domainArea)
+    || cleanText(normalizedClassification.domain_area)
+    || cleanText(normalizedClassification.domainArea);
+  const normalizedReusePotential = cleanText(reuse_potential)
+    || cleanText(reusePotential)
+    || cleanText(normalizedClassification.reuse_potential)
+    || cleanText(normalizedClassification.reusePotential);
+  const normalizedModernizationNeed = cleanText(modernization_need)
+    || cleanText(modernizationNeed)
+    || cleanText(normalizedClassification.modernization_need)
+    || cleanText(normalizedClassification.modernizationNeed);
+  const normalizedRecommendedNextStep = cleanText(recommended_next_step)
+    || cleanText(recommendedNextStep)
+    || cleanText(normalizedClassification.recommended_next_step)
+    || cleanText(normalizedClassification.recommendedNextStep);
+  const normalizedClassificationConfidence = cleanText(classification_confidence)
+    || cleanText(classificationConfidence)
+    || cleanText(normalizedClassification.classification_confidence)
+    || cleanText(normalizedClassification.classificationConfidence);
+  const normalizedKnownRisks = Array.isArray(known_risks)
+    ? known_risks
+    : (Array.isArray(knownRisks) ? knownRisks : normalizedAsset.known_risks || normalizedAsset.knownRisks || []);
+  const normalizedEvidenceRefs = Array.isArray(evidence_refs)
+    ? evidence_refs
+    : (Array.isArray(evidenceRefs) ? evidenceRefs : normalizedAsset.evidence_refs || normalizedAsset.evidenceRefs || []);
+  const normalizedHandoffNotes = cleanText(handoff_notes)
+    || cleanText(handoffNotes)
+    || cleanText(normalizedClassification.handoff_notes)
+    || cleanText(normalizedClassification.handoffNotes)
+    || cleanText(normalizedAsset.handoff_notes)
+    || cleanText(normalizedAsset.handoffNotes);
+  const normalizedAssignedReviewer = cleanText(assigned_reviewer)
+    || cleanText(assignedReviewer)
+    || cleanText(normalizedClassification.assigned_reviewer)
+    || cleanText(normalizedClassification.assignedReviewer);
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedReviewRequired = review_required ?? reviewRequired ?? true;
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let registeredAssetRecord = null;
+  const intakeLookupSurface = typeof client.getModernizationAssetIntakeRecord === 'function'
+    ? client.getModernizationAssetIntakeRecord.bind(client)
+    : null;
+  if (!intakeLookupSurface) {
+    missingSurfaces.push('getModernizationAssetIntakeRecord');
+  } else {
+    registeredAssetRecord = await intakeLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'classifyModernizationAsset',
+      },
+    });
+  }
+
+  let classificationRecord = null;
+  const classificationSurface = typeof client.createModernizationAssetClassificationRecord === 'function'
+    ? client.createModernizationAssetClassificationRecord.bind(client)
+    : null;
+  if (!classificationSurface) {
+    missingSurfaces.push('createModernizationAssetClassificationRecord');
+  } else {
+    classificationRecord = await classificationSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      assetType: normalizedAssetType,
+      sourceRef: normalizedSourceRef,
+      classificationCategory: normalizedClassificationCategory,
+      domainArea: normalizedDomainArea,
+      reusePotential: normalizedReusePotential,
+      modernizationNeed: normalizedModernizationNeed,
+      knownRisks: normalizedKnownRisks,
+      recommendedNextStep: normalizedRecommendedNextStep,
+      classificationConfidence: normalizedClassificationConfidence,
+      evidenceRefs: normalizedEvidenceRefs,
+      reviewRequired: Boolean(normalizedReviewRequired),
+      assignedReviewer: normalizedAssignedReviewer,
+      submittedBy: normalizedSubmittedBy,
+      handoffNotes: normalizedHandoffNotes,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'classifyModernizationAsset',
+      },
+    });
+  }
+
+  let classificationObservation = null;
+  const observationSurface = typeof client.submitModernizationAssetClassificationObservation === 'function'
+    ? client.submitModernizationAssetClassificationObservation.bind(client)
+    : null;
+  if (!observationSurface) {
+    missingSurfaces.push('submitModernizationAssetClassificationObservation');
+  } else {
+    classificationObservation = await observationSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      assetType: normalizedAssetType,
+      sourceRef: normalizedSourceRef,
+      classificationCategory: normalizedClassificationCategory,
+      classificationConfidence: normalizedClassificationConfidence,
+      evidenceRefs: normalizedEvidenceRefs,
+      submittedBy: normalizedSubmittedBy,
+      observationKind: 'asset_classification',
+      observationState: 'prepared',
+      observationSummary: normalizedClassificationCategory || normalizedDomainArea || normalizedAssetType || normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'classifyModernizationAsset',
+      },
+    });
+  }
+
+  let transferResult = null;
+  let watchResult = null;
+  let heartbeatResult = null;
+  const reviewTransferNeeded = Boolean(normalizedReviewRequired && normalizedAssignedReviewer);
+  if (reviewTransferNeeded) {
+    const transferSurface = typeof client.transferWorkPacket === 'function'
+      ? client.transferWorkPacket.bind(client)
+      : null;
+    if (!transferSurface) {
+      missingSurfaces.push('transferWorkPacket');
+    } else {
+      transferResult = await transferSurface({
+        workflowRunId: resolvedWorkflowRunId,
+        transferKind: 'upstream_remediation',
+        objective: `Review modernization asset classification ${normalizedSourceRef || normalizedAssetId}`,
+        requestedOutcome: 'Review and enrich the modernization asset classification.',
+        target: {
+          intent: 'upstream_remediation',
+          recipient_mode: 'agent_session',
+          preferred_agent_session_id: normalizedAssignedReviewer,
+          preferred_role_key: normalizedAssignedReviewer,
+        },
+        artifacts: normalizedSourceRef ? [normalizedSourceRef] : [],
+        issues: normalizedKnownRisks,
+        expected_evidence: normalizedEvidenceRefs,
+        preferred_modes: ['bundle', 'artifact_refs', 'inline_payload'],
+        capabilities: {},
+        sender_agent_session_id: normalizedSubmittedBy,
+        sender_actor_session_id: null,
+        message_kind: 'handoff',
+        subject: normalizedClassificationCategory || normalizedSourceRef || 'Modernization asset classification',
+        body_markdown: normalizedHandoffNotes || normalizedRecommendedNextStep || normalizedClassificationCategory,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'classifyModernizationAsset',
+          asset_id: normalizedAssetId,
+          intake_record_id: cleanText(intake_record_id) || cleanText(intakeRecordId),
+          asset_type: normalizedAssetType,
+          classification_category: normalizedClassificationCategory,
+          domain_area: normalizedDomainArea,
+        },
+      });
+    }
+  }
+
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+  const transferPacketId = cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+  const transferChannelId = cleanText(transferPayload.communication_transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.communication_transfer_channel?.channel_id)
+    || cleanText(transferPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.transfer_channel_id)
+    || cleanText(transferPayload.channel_id)
+    || null;
+
+  if (reviewTransferNeeded && transferChannelId && transferPacketId) {
+    const watchSurface = typeof client.startMessageWatch === 'function'
+      ? client.startMessageWatch.bind(client)
+      : null;
+    if (!watchSurface) {
+      missingSurfaces.push('startMessageWatch');
+    } else {
+      watchResult = await watchSurface({
+        transferChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedAssignedReviewer,
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          asset_id: normalizedAssetId,
+          classification_category: normalizedClassificationCategory,
+          review_required: Boolean(normalizedReviewRequired),
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedHandoffNotes || normalizedRecommendedNextStep || normalizedClassificationCategory,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'classifyModernizationAsset',
+        },
+      });
+    }
+  }
+
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+
+  if ((classificationRecord || classificationObservation || transferResult) && typeof client.postCollaborationHeartbeat === 'function') {
+    try {
+      heartbeatResult = await client.postCollaborationHeartbeat({
+        transferChannelId: transferChannelId || undefined,
+        workTransferPacketId: transferPacketId || undefined,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedReviewRequired && normalizedAssignedReviewer ? 'classifier' : 'warehouse',
+        currentPhase: reviewTransferNeeded ? 'review_pending' : 'classification_prepared',
+        currentTaskSummary: normalizedClassificationCategory || normalizedSourceRef || 'Modernization asset classification',
+      });
+    } catch (error) {
+      void error;
+    }
+  }
+
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+  const classificationId = cleanText(classificationRecord?.classification_id)
+    || cleanText(classificationRecord?.classificationId)
+    || cleanText(classificationRecord?.intake_classification_id)
+    || cleanText(classificationRecord?.intakeClassificationId)
+    || null;
+  const assetRecordId = cleanText(registeredAssetRecord?.asset_id)
+    || cleanText(registeredAssetRecord?.assetId)
+    || cleanText(registeredAssetRecord?.intake_record_id)
+    || cleanText(registeredAssetRecord?.intakeRecordId)
+    || cleanText(normalizedAssetId)
+    || null;
+  const intakeRecordResolvedId = cleanText(registeredAssetRecord?.intake_record_id)
+    || cleanText(registeredAssetRecord?.intakeRecordId)
+    || cleanText(registeredAssetRecord?.asset_id)
+    || cleanText(registeredAssetRecord?.assetId)
+    || cleanText(intake_record_id)
+    || cleanText(intakeRecordId)
+    || null;
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    asset_id: assetRecordId,
+    intake_record_id: intakeRecordResolvedId,
+    classification_id: classificationId,
+    asset_type: normalizedAssetType,
+    classification_category: normalizedClassificationCategory,
+    reuse_potential: normalizedReusePotential || null,
+    risk_level: normalizedClassification.risk_level || normalizedClassification.riskLevel || normalizedKnownRisks[0] || null,
+    classification_confidence: normalizedClassificationConfidence || null,
+    assigned_reviewer: normalizedAssignedReviewer || null,
+    source_ref: normalizedSourceRef,
+    submitted_by: normalizedSubmittedBy,
+    review_required: Boolean(normalizedReviewRequired),
+    transfer_packet_id: transferPacketId,
+    watch_id: watchId,
+    heartbeat_status: cleanText(heartbeatPayload.activity_state)
+      || cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+      || cleanText(heartbeatPayload.status)
+      || cleanText(heartbeatPayload.heartbeat_status)
+      || null,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      registered_asset_record: registeredAssetRecord,
+      classification_record: classificationRecord,
+      classification_observation: classificationObservation,
+      review_transfer: transferPayload,
+      message_watch: watchPayload,
+      heartbeat: heartbeatPayload,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    registered_asset_record: registeredAssetRecord,
+    classification_record: classificationRecord,
+    classification_observation: classificationObservation,
+    transfer: transferPayload,
+    message_watch: watchPayload,
+    heartbeat: heartbeatPayload,
+  };
+}
+
+export async function discoverSalvageCandidates(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  asset = {},
+  modernizationAsset = {},
+  classification = {},
+  modernizationClassification = {},
+  assetId,
+  asset_id,
+  intakeRecordId,
+  intake_record_id,
+  classificationId,
+  classification_id,
+  sourceRef,
+  source_ref,
+  assetType,
+  asset_type,
+  classificationCategory,
+  classification_category,
+  domainArea,
+  domain_area,
+  reusePotential,
+  reuse_potential,
+  modernizationNeed,
+  modernization_need,
+  riskLevel,
+  risk_level,
+  knownRisks = [],
+  known_risks = [],
+  evidenceRefs = [],
+  evidence_refs = [],
+  recommendedNextStep,
+  recommended_next_step,
+  reviewRequired,
+  review_required,
+  assignedReviewer,
+  assigned_reviewer,
+  candidateSearchIntent,
+  candidate_search_intent,
+  candidateSearchQuery,
+  candidate_search_query,
+  relatedSymbols = [],
+  related_symbols = [],
+  relatedQualifiedNames = [],
+  related_qualified_names = [],
+  relatedFilePaths = [],
+  related_file_paths = [],
+  maxCandidates = 10,
+  submittedBy,
+  submitted_by,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedAsset = isPlainObject(modernizationAsset)
+    ? modernizationAsset
+    : (isPlainObject(asset) ? asset : {});
+  const normalizedClassification = isPlainObject(modernizationClassification)
+    ? modernizationClassification
+    : (isPlainObject(classification) ? classification : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedAsset.related_project_id)
+    || cleanText(normalizedAsset.relatedProjectId)
+    || cleanText(normalizedClassification.related_project_id)
+    || cleanText(normalizedClassification.relatedProjectId);
+  const normalizedAssetId = cleanText(asset_id)
+    || cleanText(assetId)
+    || cleanText(intake_record_id)
+    || cleanText(intakeRecordId)
+    || cleanText(normalizedAsset.asset_id)
+    || cleanText(normalizedAsset.assetId)
+    || cleanText(normalizedAsset.intake_record_id)
+    || cleanText(normalizedAsset.intakeRecordId);
+  const normalizedClassificationId = cleanText(classification_id)
+    || cleanText(classificationId)
+    || cleanText(normalizedClassification.classification_id)
+    || cleanText(normalizedClassification.classificationId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedAsset.source_ref)
+    || cleanText(normalizedAsset.sourceRef)
+    || normalizedAssetId;
+  if (!normalizedAssetId && !normalizedSourceRef && !normalizedClassificationId) {
+    throw new Error('asset_id, intake_record_id, classification_id, or source_ref is required.');
+  }
+  const normalizedAssetType = cleanText(asset_type)
+    || cleanText(assetType)
+    || cleanText(normalizedAsset.asset_type)
+    || cleanText(normalizedAsset.assetType)
+    || 'unknown';
+  const normalizedClassificationCategory = cleanText(classification_category)
+    || cleanText(classificationCategory)
+    || cleanText(normalizedClassification.classification_category)
+    || cleanText(normalizedClassification.classificationCategory)
+    || 'uncategorized';
+  const normalizedDomainArea = cleanText(domain_area)
+    || cleanText(domainArea)
+    || cleanText(normalizedClassification.domain_area)
+    || cleanText(normalizedClassification.domainArea);
+  const normalizedReusePotential = cleanText(reuse_potential)
+    || cleanText(reusePotential)
+    || cleanText(normalizedClassification.reuse_potential)
+    || cleanText(normalizedClassification.reusePotential);
+  const normalizedModernizationNeed = cleanText(modernization_need)
+    || cleanText(modernizationNeed)
+    || cleanText(normalizedClassification.modernization_need)
+    || cleanText(normalizedClassification.modernizationNeed);
+  const normalizedRiskLevel = cleanText(risk_level)
+    || cleanText(riskLevel)
+    || cleanText(normalizedClassification.risk_level)
+    || cleanText(normalizedClassification.riskLevel)
+    || null;
+  const normalizedRecommendedNextStep = cleanText(recommended_next_step)
+    || cleanText(recommendedNextStep)
+    || cleanText(normalizedClassification.recommended_next_step)
+    || cleanText(normalizedClassification.recommendedNextStep);
+  const normalizedKnownRisks = Array.isArray(known_risks)
+    ? known_risks
+    : (Array.isArray(knownRisks) ? knownRisks : normalizedAsset.known_risks || normalizedAsset.knownRisks || []);
+  const normalizedEvidenceRefs = Array.isArray(evidence_refs)
+    ? evidence_refs
+    : (Array.isArray(evidenceRefs) ? evidenceRefs : normalizedAsset.evidence_refs || normalizedAsset.evidenceRefs || []);
+  const normalizedAssignedReviewer = cleanText(assigned_reviewer)
+    || cleanText(assignedReviewer)
+    || cleanText(normalizedClassification.assigned_reviewer)
+    || cleanText(normalizedClassification.assignedReviewer);
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedReviewRequired = review_required ?? reviewRequired ?? true;
+  const normalizedCandidateSearchIntent = cleanText(candidate_search_intent)
+    || cleanText(candidateSearchIntent)
+    || normalizedClassificationCategory
+    || normalizedDomainArea
+    || normalizedSourceRef
+    || normalizedAssetType;
+  const normalizedCandidateSearchQuery = cleanText(candidate_search_query)
+    || cleanText(candidateSearchQuery)
+    || [
+        normalizedClassificationCategory,
+        normalizedDomainArea,
+        normalizedModernizationNeed,
+        normalizedSourceRef,
+        normalizedAssetType,
+      ].filter(Boolean).join(' ');
+  const normalizedRelatedSymbols = cleanList(related_symbols.length > 0 ? related_symbols : relatedSymbols);
+  const normalizedRelatedQualifiedNames = cleanList(related_qualified_names.length > 0 ? related_qualified_names : relatedQualifiedNames);
+  const normalizedRelatedFilePaths = cleanList(related_file_paths.length > 0 ? related_file_paths : relatedFilePaths);
+  const normalizedMaxCandidates = Number.isFinite(Number(maxCandidates)) && Number(maxCandidates) > 0
+    ? Number(maxCandidates)
+    : 10;
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let assetIntakeRecord = null;
+  const intakeLookupSurface = typeof client.getModernizationAssetIntakeRecord === 'function'
+    ? client.getModernizationAssetIntakeRecord.bind(client)
+    : null;
+  if (!intakeLookupSurface) {
+    missingSurfaces.push('getModernizationAssetIntakeRecord');
+  } else {
+    assetIntakeRecord = await intakeLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'discoverSalvageCandidates',
+      },
+    });
+  }
+
+  let classificationRecord = null;
+  const classificationLookupSurface = typeof client.getModernizationAssetClassificationRecord === 'function'
+    ? client.getModernizationAssetClassificationRecord.bind(client)
+    : null;
+  if (!classificationLookupSurface) {
+    missingSurfaces.push('getModernizationAssetClassificationRecord');
+  } else {
+    classificationRecord = await classificationLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      classificationId: normalizedClassificationId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'discoverSalvageCandidates',
+      },
+    });
+  }
+
+  let codeIntentResult = null;
+  if (typeof client.searchCodeByIntent === 'function') {
+    codeIntentResult = await client.searchCodeByIntent({
+      intentText: normalizedCandidateSearchIntent,
+      repoKey: normalizedProjectReference || undefined,
+      refName: normalizedSourceRef || undefined,
+      maxCandidates: normalizedMaxCandidates,
+    });
+  } else {
+    missingSurfaces.push('searchCodeByIntent');
+  }
+
+  if (typeof client.getCodeContextForIntent === 'function') {
+    await client.getCodeContextForIntent({
+      intentText: normalizedCandidateSearchIntent,
+      candidatePolicy: 'top_ranked',
+    }).catch(() => null);
+  } else {
+    missingSurfaces.push('getCodeContextForIntent');
+  }
+
+  let symbolSearchResult = null;
+  if (typeof client.searchSymbols === 'function') {
+    symbolSearchResult = await client.searchSymbols({
+      query: normalizedCandidateSearchQuery,
+      projectScope: resolvedProjectId || undefined,
+      maxResults: normalizedMaxCandidates,
+    }).catch(() => null);
+  } else {
+    missingSurfaces.push('searchSymbols');
+  }
+
+  const relatedCodeResults = [];
+  if (typeof client.getRelatedCode === 'function') {
+    for (const qualifiedName of normalizedRelatedQualifiedNames) {
+      relatedCodeResults.push(await client.getRelatedCode({
+        qualifiedName,
+        relationshipType: 'salvage_candidate',
+        depth: 2,
+        includeCode: false,
+        requestedBy: normalizedSubmittedBy,
+      }).catch(() => null));
+    }
+    for (const symbolKey of normalizedRelatedSymbols) {
+      relatedCodeResults.push(await client.getRelatedCode({
+        symbolKey,
+        relationshipType: 'salvage_candidate',
+        depth: 2,
+        includeCode: false,
+        requestedBy: normalizedSubmittedBy,
+      }).catch(() => null));
+    }
+  } else if (normalizedRelatedSymbols.length > 0 || normalizedRelatedQualifiedNames.length > 0) {
+    missingSurfaces.push('getRelatedCode');
+  }
+
+  const toArray = (value) => {
+    if (Array.isArray(value)) return value;
+    if (isPlainObject(value)) {
+      const candidates = value.candidates || value.results || value.items || value.symbols || value.related_code || value.relatedCode;
+      if (Array.isArray(candidates)) return candidates;
+    }
+    return [];
+  };
+
+  const mapCandidate = (entry, candidateType, fallbackRankReason) => {
+    if (!isPlainObject(entry)) return null;
+    const sourceRefValue = cleanText(entry.source_ref)
+      || cleanText(entry.sourceRef)
+      || cleanText(entry.qualified_name)
+      || cleanText(entry.qualifiedName)
+      || cleanText(entry.file_path)
+      || cleanText(entry.filePath)
+      || cleanText(entry.symbol_key)
+      || cleanText(entry.symbolKey)
+      || cleanText(entry.symbol_id)
+      || cleanText(entry.symbolId)
+      || null;
+    const candidate = {
+      candidate_type: cleanText(entry.candidate_type) || cleanText(entry.candidateType) || candidateType,
+      source_ref: sourceRefValue,
+      file_path: cleanText(entry.file_path) || cleanText(entry.filePath) || null,
+      qualified_name: cleanText(entry.qualified_name) || cleanText(entry.qualifiedName) || null,
+      responsibility_area: cleanText(entry.responsibility_area) || cleanText(entry.responsibilityArea) || normalizedDomainArea || normalizedClassificationCategory || null,
+      reuse_potential: cleanText(entry.reuse_potential) || cleanText(entry.reusePotential) || normalizedReusePotential || null,
+      modernization_need: cleanText(entry.modernization_need) || cleanText(entry.modernizationNeed) || normalizedModernizationNeed || null,
+      risk_level: cleanText(entry.risk_level) || cleanText(entry.riskLevel) || normalizedRiskLevel || null,
+      rank_reason: cleanText(entry.rank_reason) || cleanText(entry.rankReason) || fallbackRankReason,
+      evidence_refs: Array.isArray(entry.evidence_refs) ? entry.evidence_refs : (Array.isArray(entry.evidenceRefs) ? entry.evidenceRefs : [...normalizedEvidenceRefs]),
+      recommended_next_step: cleanText(entry.recommended_next_step) || cleanText(entry.recommendedNextStep) || normalizedRecommendedNextStep || null,
+    };
+    return candidate.source_ref || candidate.file_path || candidate.qualified_name ? candidate : null;
+  };
+
+  const candidateMap = new Map();
+  const addCandidates = (entries, candidateType, fallbackRankReason) => {
+    for (const entry of entries) {
+      const candidate = mapCandidate(entry, candidateType, fallbackRankReason);
+      if (!candidate) continue;
+      const key = candidate.source_ref || candidate.file_path || candidate.qualified_name;
+      if (!candidateMap.has(key)) {
+        candidateMap.set(key, candidate);
+      }
+    }
+  };
+
+  addCandidates(toArray(codeIntentResult), 'intent_search_match', 'ranked by intent search');
+  addCandidates(toArray(symbolSearchResult), 'symbol_search_match', 'ranked by inventory symbol search');
+  for (const relatedCodeResult of relatedCodeResults) {
+    addCandidates(toArray(relatedCodeResult), 'related_code_match', 'related code lookup');
+  }
+
+  const candidates = [...candidateMap.values()].slice(0, normalizedMaxCandidates);
+  const candidateCount = candidates.length;
+
+  let discoveryObservation = null;
+  const discoveryObservationSurface = typeof client.submitModernizationSalvageDiscoveryObservation === 'function'
+    ? client.submitModernizationSalvageDiscoveryObservation.bind(client)
+    : null;
+  if (!discoveryObservationSurface) {
+    missingSurfaces.push('submitModernizationSalvageDiscoveryObservation');
+  } else {
+    discoveryObservation = await discoveryObservationSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      classificationId: normalizedClassificationId,
+      candidateCount,
+      candidates,
+      evidenceRefs: normalizedEvidenceRefs,
+      observationKind: 'salvage_candidate_discovery',
+      observationState: 'prepared',
+      observationSummary: normalizedCandidateSearchIntent || normalizedClassificationCategory || normalizedSourceRef || 'salvage candidate discovery',
+      metadata: {
+        ...normalizedMetadata,
+        source: 'discoverSalvageCandidates',
+      },
+    });
+  }
+
+  let transferResult = null;
+  let watchResult = null;
+  let heartbeatResult = null;
+  const reviewTransferNeeded = Boolean(normalizedReviewRequired && normalizedAssignedReviewer);
+  if (reviewTransferNeeded) {
+    const transferSurface = typeof client.transferWorkPacket === 'function'
+      ? client.transferWorkPacket.bind(client)
+      : null;
+    if (!transferSurface) {
+      missingSurfaces.push('transferWorkPacket');
+    } else {
+      transferResult = await transferSurface({
+        workflowRunId: resolvedWorkflowRunId,
+        transferKind: 'upstream_remediation',
+        objective: `Review salvage candidates for ${normalizedSourceRef || normalizedAssetId}`,
+        requestedOutcome: 'Review and rank salvage candidates from governed inventory.',
+        target: {
+          intent: 'upstream_remediation',
+          recipient_mode: 'agent_session',
+          preferred_agent_session_id: normalizedAssignedReviewer,
+          preferred_role_key: normalizedAssignedReviewer,
+        },
+        artifacts: normalizedSourceRef ? [normalizedSourceRef] : [],
+        issues: normalizedKnownRisks,
+        expected_evidence: normalizedEvidenceRefs,
+        preferred_modes: ['bundle', 'artifact_refs', 'inline_payload'],
+        capabilities: {},
+        sender_agent_session_id: normalizedSubmittedBy,
+        sender_actor_session_id: null,
+        message_kind: 'handoff',
+        subject: normalizedCandidateSearchIntent || normalizedSourceRef || 'Salvage candidate discovery',
+        body_markdown: normalizedRecommendedNextStep || normalizedClassificationCategory || normalizedSourceRef,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'discoverSalvageCandidates',
+          asset_id: normalizedAssetId,
+          classification_id: normalizedClassificationId,
+          classification_category: normalizedClassificationCategory,
+          domain_area: normalizedDomainArea,
+        },
+      });
+    }
+  }
+
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+  const transferPacketId = cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+  const transferChannelId = cleanText(transferPayload.communication_transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.communication_transfer_channel?.channel_id)
+    || cleanText(transferPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(transferPayload.transfer_channel_id)
+    || cleanText(transferPayload.channel_id)
+    || null;
+
+  if (reviewTransferNeeded && transferChannelId && transferPacketId) {
+    const watchSurface = typeof client.startMessageWatch === 'function'
+      ? client.startMessageWatch.bind(client)
+      : null;
+    if (!watchSurface) {
+      missingSurfaces.push('startMessageWatch');
+    } else {
+      watchResult = await watchSurface({
+        transferChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedAssignedReviewer,
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          asset_id: normalizedAssetId,
+          classification_id: normalizedClassificationId,
+          candidate_count: candidateCount,
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedRecommendedNextStep || normalizedClassificationCategory || normalizedSourceRef,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'discoverSalvageCandidates',
+        },
+      });
+    }
+  }
+
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+
+  if ((discoveryObservation || transferResult) && typeof client.postCollaborationHeartbeat === 'function') {
+    try {
+      heartbeatResult = await client.postCollaborationHeartbeat({
+        transferChannelId: transferChannelId || undefined,
+        workTransferPacketId: transferPacketId || undefined,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: reviewTransferNeeded ? 'salvage_reviewer' : 'salvage_discovery',
+        currentPhase: reviewTransferNeeded ? 'review_pending' : 'discovery_complete',
+        currentTaskSummary: normalizedCandidateSearchIntent || normalizedSourceRef || 'Salvage candidate discovery',
+      });
+    } catch (error) {
+      void error;
+    }
+  }
+
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+  const heartbeatStatus = cleanText(heartbeatPayload.activity_state)
+    || cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeatPayload.status)
+    || cleanText(heartbeatPayload.heartbeat_status)
+    || null;
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    asset_id: cleanText(assetIntakeRecord?.asset_id)
+      || cleanText(assetIntakeRecord?.assetId)
+      || normalizedAssetId
+      || null,
+    intake_record_id: cleanText(assetIntakeRecord?.intake_record_id)
+      || cleanText(assetIntakeRecord?.intakeRecordId)
+      || cleanText(intake_record_id)
+      || cleanText(intakeRecordId)
+      || null,
+    classification_id: cleanText(classificationRecord?.classification_id)
+      || cleanText(classificationRecord?.classificationId)
+      || normalizedClassificationId
+      || null,
+    candidate_count: candidateCount,
+    candidates,
+    review_required: Boolean(normalizedReviewRequired),
+    assigned_reviewer: normalizedAssignedReviewer || null,
+    transfer_packet_id: transferPacketId,
+    watch_id: watchId,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      asset_intake_record: assetIntakeRecord,
+      classification_record: classificationRecord,
+      code_intent_search: codeIntentResult,
+      symbol_search: symbolSearchResult,
+      related_code: relatedCodeResults,
+      discovery_observation: discoveryObservation,
+      transfer: transferPayload,
+      message_watch: watchPayload,
+      heartbeat: heartbeatPayload,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    asset_intake_record: assetIntakeRecord,
+    classification_record: classificationRecord,
+    code_intent_search: codeIntentResult,
+    symbol_search: symbolSearchResult,
+    related_code: relatedCodeResults,
+    discovery_observation: discoveryObservation,
+    transfer: transferPayload,
+    message_watch: watchPayload,
+    heartbeat: heartbeatPayload,
+  };
+}
+
+export async function createModernizationWorkPacket(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  asset = {},
+  modernizationAsset = {},
+  classification = {},
+  modernizationClassification = {},
+  assetId,
+  asset_id,
+  intakeRecordId,
+  intake_record_id,
+  classificationId,
+  classification_id,
+  selectedCandidates = [],
+  selected_candidates = [],
+  candidateIds = [],
+  candidate_ids = [],
+  candidateObjects = [],
+  candidate_objects = [],
+  sourceRef,
+  source_ref,
+  packetTitle,
+  packet_title,
+  problemStatement,
+  problem_statement,
+  recommendedModernization,
+  recommended_modernization,
+  affectedFilesOrSymbols = [],
+  affected_files_or_symbols = [],
+  acceptanceCriteria = [],
+  acceptance_criteria = [],
+  riskLevel,
+  risk_level,
+  evidenceRefs = [],
+  evidence_refs = [],
+  wrapperExecutionRequired,
+  wrapper_execution_required,
+  handoffNotes,
+  handoff_notes,
+  targetAgent,
+  target_agent,
+  assignedOwner,
+  assigned_owner,
+  collaborationRequired,
+  collaboration_required,
+  channelId,
+  channel_id,
+  transferChannelId,
+  transfer_channel_id,
+  submittedBy,
+  submitted_by,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  includeTransferChannelProjection = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedAsset = isPlainObject(modernizationAsset)
+    ? modernizationAsset
+    : (isPlainObject(asset) ? asset : {});
+  const normalizedClassification = isPlainObject(modernizationClassification)
+    ? modernizationClassification
+    : (isPlainObject(classification) ? classification : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedAsset.related_project_id)
+    || cleanText(normalizedAsset.relatedProjectId)
+    || cleanText(normalizedClassification.related_project_id)
+    || cleanText(normalizedClassification.relatedProjectId);
+  const normalizedAssetId = cleanText(asset_id)
+    || cleanText(assetId)
+    || cleanText(intake_record_id)
+    || cleanText(intakeRecordId)
+    || cleanText(normalizedAsset.asset_id)
+    || cleanText(normalizedAsset.assetId)
+    || cleanText(normalizedAsset.intake_record_id)
+    || cleanText(normalizedAsset.intakeRecordId);
+  const normalizedClassificationId = cleanText(classification_id)
+    || cleanText(classificationId)
+    || cleanText(normalizedClassification.classification_id)
+    || cleanText(normalizedClassification.classificationId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedAsset.source_ref)
+    || cleanText(normalizedAsset.sourceRef)
+    || normalizedAssetId;
+  const normalizedPacketTitle = cleanText(packet_title) || cleanText(packetTitle);
+  const normalizedProblemStatement = cleanText(problem_statement)
+    || cleanText(problemStatement)
+    || normalizedPacketTitle
+    || normalizedSourceRef
+    || 'Modernization work packet';
+  const normalizedRecommendedModernization = cleanText(recommended_modernization)
+    || cleanText(recommendedModernization)
+    || cleanText(normalizedClassification.recommended_modernization)
+    || cleanText(normalizedClassification.recommendedModernization);
+  const normalizedRiskLevel = cleanText(risk_level)
+    || cleanText(riskLevel)
+    || cleanText(normalizedClassification.risk_level)
+    || cleanText(normalizedClassification.riskLevel)
+    || null;
+  const normalizedHandoffNotes = cleanText(handoff_notes) || cleanText(handoffNotes);
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedTargetAgent = cleanText(target_agent) || cleanText(targetAgent) || cleanText(assigned_owner) || cleanText(assignedOwner) || null;
+  const normalizedWrapperExecutionRequired = wrapper_execution_required ?? wrapperExecutionRequired ?? true;
+  const normalizedCollaborationRequired = collaboration_required ?? collaborationRequired ?? Boolean(normalizedTargetAgent);
+  const normalizedAffectedFilesOrSymbols = cleanList(affected_files_or_symbols.length > 0 ? affected_files_or_symbols : affectedFilesOrSymbols);
+  const normalizedAcceptanceCriteria = cleanList(acceptance_criteria.length > 0 ? acceptance_criteria : acceptanceCriteria);
+  const normalizedEvidenceRefs = cleanList(evidence_refs.length > 0 ? evidence_refs : evidenceRefs);
+
+  const candidateEntries = [
+    ...(Array.isArray(selected_candidates) && selected_candidates.length > 0 ? selected_candidates : selectedCandidates),
+    ...(Array.isArray(candidate_objects) && candidate_objects.length > 0 ? candidate_objects : candidateObjects),
+  ];
+  const normalizedCandidateIds = [];
+  const normalizedCandidateRecords = [];
+  for (const entry of candidateEntries) {
+    if (typeof entry === 'string') {
+      const candidateId = cleanText(entry);
+      if (candidateId) normalizedCandidateIds.push(candidateId);
+      continue;
+    }
+    if (!isPlainObject(entry)) continue;
+    const candidateId = cleanText(entry.candidate_id)
+      || cleanText(entry.candidateId)
+      || cleanText(entry.salvage_candidate_id)
+      || cleanText(entry.salvageCandidateId)
+      || cleanText(entry.work_packet_candidate_id)
+      || cleanText(entry.workPacketCandidateId)
+      || cleanText(entry.source_ref)
+      || cleanText(entry.sourceRef)
+      || cleanText(entry.qualified_name)
+      || cleanText(entry.qualifiedName);
+    if (candidateId) normalizedCandidateIds.push(candidateId);
+    normalizedCandidateRecords.push(entry);
+  }
+  for (const candidateId of Array.isArray(candidate_ids) && candidate_ids.length > 0 ? candidate_ids : candidateIds) {
+    const normalizedCandidateId = cleanText(candidateId);
+    if (normalizedCandidateId) normalizedCandidateIds.push(normalizedCandidateId);
+  }
+  const uniqueCandidateIds = [...new Set(normalizedCandidateIds)].filter(Boolean);
+  if (uniqueCandidateIds.length === 0) {
+    throw new Error('candidate_ids or selected_candidates is required.');
+  }
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let assetIntakeRecord = null;
+  const intakeLookupSurface = typeof client.getModernizationAssetIntakeRecord === 'function'
+    ? client.getModernizationAssetIntakeRecord.bind(client)
+    : null;
+  if (!intakeLookupSurface) {
+    missingSurfaces.push('getModernizationAssetIntakeRecord');
+  } else {
+    assetIntakeRecord = await intakeLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      intakeRecordId: cleanText(intake_record_id) || cleanText(intakeRecordId),
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'createModernizationWorkPacket',
+      },
+    });
+  }
+
+  let classificationRecord = null;
+  const classificationLookupSurface = typeof client.getModernizationAssetClassificationRecord === 'function'
+    ? client.getModernizationAssetClassificationRecord.bind(client)
+    : null;
+  if (!classificationLookupSurface) {
+    missingSurfaces.push('getModernizationAssetClassificationRecord');
+  } else {
+    classificationRecord = await classificationLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      classificationId: normalizedClassificationId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'createModernizationWorkPacket',
+      },
+    });
+  }
+
+  let candidateRecords = [];
+  const candidateLookupSurface = typeof client.getModernizationSalvageCandidateRecord === 'function'
+    ? client.getModernizationSalvageCandidateRecord.bind(client)
+    : typeof client.getModernizationWorkPacketCandidateRecord === 'function'
+      ? client.getModernizationWorkPacketCandidateRecord.bind(client)
+      : null;
+  if (!candidateLookupSurface) {
+    missingSurfaces.push('getModernizationSalvageCandidateRecord');
+    missingSurfaces.push('getModernizationWorkPacketCandidateRecord');
+  } else {
+    candidateRecords = await Promise.all(uniqueCandidateIds.map(async (candidateId) => {
+      try {
+        return await candidateLookupSurface({
+          projectId: resolvedProjectId,
+          workflowId: resolvedWorkflowId,
+          workflowRunId: resolvedWorkflowRunId,
+          candidateId,
+          sourceRef: normalizedSourceRef,
+          metadata: {
+            ...normalizedMetadata,
+            source: 'createModernizationWorkPacket',
+          },
+        });
+      } catch (error) {
+        void error;
+        return null;
+      }
+    }));
+  }
+
+  let packetRecord = null;
+  const packetCreationSurface = typeof client.createModernizationWorkPacketRecord === 'function'
+    ? client.createModernizationWorkPacketRecord.bind(client)
+    : null;
+  if (!packetCreationSurface) {
+    missingSurfaces.push('createModernizationWorkPacketRecord');
+  } else {
+    packetRecord = await packetCreationSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      assetId: normalizedAssetId,
+      classificationId: normalizedClassificationId,
+      candidateIds: uniqueCandidateIds,
+      packetTitle: normalizedPacketTitle || normalizedProblemStatement,
+      sourceRef: normalizedSourceRef,
+      problemStatement: normalizedProblemStatement,
+      recommendedModernization: normalizedRecommendedModernization,
+      affectedFilesOrSymbols: normalizedAffectedFilesOrSymbols,
+      acceptanceCriteria: normalizedAcceptanceCriteria,
+      riskLevel: normalizedRiskLevel,
+      evidenceRefs: normalizedEvidenceRefs,
+      wrapperExecutionRequired: Boolean(normalizedWrapperExecutionRequired),
+      handoffNotes: normalizedHandoffNotes,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'createModernizationWorkPacket',
+      },
+    });
+  }
+
+  const transferSurface = typeof client.transferWorkPacket === 'function'
+    ? client.transferWorkPacket.bind(client)
+    : null;
+  if (!transferSurface) missingSurfaces.push('transferWorkPacket');
+  const transferResult = transferSurface
+    ? await transferSurface({
+        workflowRunId: resolvedWorkflowRunId,
+        transferKind: 'upstream_remediation',
+        objective: normalizedProblemStatement || normalizedRecommendedModernization || 'Modernization work packet',
+        requestedOutcome: normalizedRecommendedModernization || normalizedProblemStatement || 'Prepare modernization handoff.',
+        target: normalizedTargetAgent
+          ? {
+              intent: 'upstream_remediation',
+              recipient_mode: 'agent_session',
+              preferred_agent_session_id: normalizedTargetAgent,
+              preferred_role_key: normalizedTargetAgent,
+            }
+          : {
+              intent: 'upstream_remediation',
+              recipient_mode: 'role',
+              preferred_role_key: 'modernization_execution',
+            },
+        artifacts: normalizedAffectedFilesOrSymbols,
+        issues: [],
+        expectedEvidence: normalizedAcceptanceCriteria,
+        preferredModes: ['bundle', 'artifact_refs', 'inline_payload'],
+        capabilities: {
+          wrapper_execution_required: Boolean(normalizedWrapperExecutionRequired),
+          selected_candidate_count: uniqueCandidateIds.length,
+        },
+        senderAgentSessionId: normalizedSubmittedBy,
+        senderActorSessionId: null,
+        messageKind: 'handoff',
+        subject: normalizedPacketTitle || normalizedProblemStatement || 'Modernization work packet',
+        bodyMarkdown: normalizedHandoffNotes || normalizedRecommendedModernization || normalizedProblemStatement,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+          asset_id: normalizedAssetId,
+          classification_id: normalizedClassificationId,
+          source_ref: normalizedSourceRef,
+          candidate_ids: uniqueCandidateIds,
+          selected_candidates: normalizedCandidateRecords,
+          wrapper_execution_required: Boolean(normalizedWrapperExecutionRequired),
+        },
+      })
+    : null;
+
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+  let transferPacketId = cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+
+  const transferChannelInputId = cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId);
+  const transferChannelSurface = transferChannelInputId
+    ? (typeof client.resumeTransferChannel === 'function'
+      ? client.resumeTransferChannel.bind(client)
+      : null)
+    : (transferPacketId && typeof client.openTransferChannel === 'function'
+      ? client.openTransferChannel.bind(client)
+      : null);
+  if (!transferChannelSurface && (transferChannelInputId || transferPacketId)) {
+    missingSurfaces.push(transferChannelInputId ? 'resumeTransferChannel' : 'openTransferChannel');
+  }
+  const channelResult = transferChannelSurface && transferPacketId
+    ? await transferChannelSurface({
+        transferChannelId: transferChannelInputId || undefined,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        channelKind: 'bidirectional',
+        upstreamAgentSessionId: normalizedSubmittedBy,
+        downstreamAgentSessionId: normalizedTargetAgent || undefined,
+        evidenceRequiredForClosure: true,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+        },
+      })
+    : null;
+  const channelPayload = isPlainObject(channelResult) ? channelResult : {};
+  const resolvedChannelId = cleanText(channelPayload.transfer_channel_id)
+    || cleanText(channelPayload.channel_id)
+    || cleanText(channelPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(channelPayload.communication_transfer_channel?.transfer_channel_id)
+    || transferChannelInputId
+    || null;
+
+  const ownershipSurface = normalizedTargetAgent && resolvedChannelId && typeof client.assignCollaborationOwnership === 'function'
+    ? client.assignCollaborationOwnership.bind(client)
+    : null;
+  if (normalizedTargetAgent && !ownershipSurface) missingSurfaces.push('assignCollaborationOwnership');
+  const ownershipResult = ownershipSurface
+    ? await ownershipSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: 'modernization_owner',
+        ownerAgentSessionId: normalizedTargetAgent,
+        ownerActorSessionId: null,
+        ownerLabel: normalizedTargetAgent,
+        assignmentState: 'assigned',
+        assignmentReason: normalizedProblemStatement || normalizedRecommendedModernization,
+        currentPhase: 'modernization_work_packet',
+        assignedByAgentSessionId: normalizedSubmittedBy,
+        assignedByActorSessionId: null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+        },
+      })
+    : null;
+  const ownershipPayload = isPlainObject(ownershipResult) ? ownershipResult : {};
+
+  const proposalSurface = resolvedChannelId && typeof client.postCollaborationProposal === 'function'
+    ? client.postCollaborationProposal.bind(client)
+    : null;
+  if (resolvedChannelId && !proposalSurface) missingSurfaces.push('postCollaborationProposal');
+  const proposalResult = proposalSurface
+    ? await proposalSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        proposalKind: 'modernization_work_packet',
+        proposalState: 'proposed',
+        participantRole: normalizedTargetAgent ? 'modernization_owner' : 'modernization_planner',
+        proposalSummary: normalizedProblemStatement || normalizedRecommendedModernization || 'Modernization work packet',
+        currentPhase: 'modernization_work_packet',
+        expectedNextUpdate: normalizedAcceptanceCriteria.join('; ') || normalizedRecommendedModernization || normalizedProblemStatement,
+        requiredEvidence: normalizedAcceptanceCriteria,
+        responseSchema: {
+          source_ref: normalizedSourceRef,
+          risk_level: normalizedRiskLevel,
+          candidate_ids: uniqueCandidateIds,
+          wrapper_execution_required: Boolean(normalizedWrapperExecutionRequired),
+        },
+        blockerSummary: normalizedProblemStatement || normalizedRecommendedModernization,
+        revisionNumber: 1,
+        proposerAgentSessionId: normalizedSubmittedBy,
+        proposerActorSessionId: null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+        },
+      })
+    : null;
+  const proposalPayload = isPlainObject(proposalResult) ? proposalResult : {};
+
+  const watchSurface = resolvedChannelId && typeof client.startMessageWatch === 'function'
+    ? client.startMessageWatch.bind(client)
+    : null;
+  if (resolvedChannelId && !watchSurface) missingSurfaces.push('startMessageWatch');
+  const watchResult = watchSurface
+    ? await watchSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedTargetAgent || 'modernization_owner',
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          source_ref: normalizedSourceRef,
+          candidate_ids: uniqueCandidateIds,
+          expected_acknowledgement: 'modernization work packet received',
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedHandoffNotes || normalizedRecommendedModernization || normalizedProblemStatement,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+        },
+      })
+    : null;
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+
+  const heartbeatSurface = resolvedChannelId && typeof client.postCollaborationHeartbeat === 'function'
+    ? client.postCollaborationHeartbeat.bind(client)
+    : null;
+  if (resolvedChannelId && !heartbeatSurface) missingSurfaces.push('postCollaborationHeartbeat');
+  const heartbeatResult = heartbeatSurface
+    ? await heartbeatSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedTargetAgent ? 'modernization_owner' : 'modernization_planner',
+        currentPhase: 'modernization_work_packet',
+        currentTaskSummary: normalizedProblemStatement || normalizedRecommendedModernization || 'Modernization work packet',
+        metadata: {
+          ...normalizedMetadata,
+          source: 'createModernizationWorkPacket',
+        },
+      }).catch(() => null)
+    : null;
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+
+  const transferChannelProjectionSurface = includeTransferChannelProjection && resolvedChannelId
+    ? (typeof client.getTransferChannelProjection === 'function'
+      ? client.getTransferChannelProjection.bind(client)
+      : typeof client.getLogaTransferChannelThreadProjection === 'function'
+        ? client.getLogaTransferChannelThreadProjection.bind(client)
+        : null)
+    : null;
+  if (includeTransferChannelProjection && resolvedChannelId && !transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
+  const transferChannelProjection = transferChannelProjectionSurface && resolvedChannelId
+    ? await transferChannelProjectionSurface(resolvedChannelId).catch(() => null)
+    : null;
+
+  const modernizationPacketId = cleanText(packetRecord?.modernization_packet_id)
+    || cleanText(packetRecord?.modernizationPacketId)
+    || cleanText(packetRecord?.work_packet_id)
+    || cleanText(packetRecord?.workPacketId)
+    || null;
+  const candidateCount = uniqueCandidateIds.length;
+  const proposalId = cleanText(proposalPayload.collaboration_proposal_id)
+    || cleanText(proposalPayload.proposal_id)
+    || cleanText(proposalPayload.collaboration_proposal?.collaboration_proposal_id)
+    || cleanText(proposalPayload.collaboration_proposal?.proposal_id)
+    || null;
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+  const expectedAcknowledgement = cleanText(watchPayload.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_acknowledgement)
+    || (normalizedTargetAgent ? 'acknowledgement' : null);
+  const assignedOwnerResolved = cleanText(ownershipPayload.owner_agent_session_id)
+    || cleanText(ownershipPayload.ownerAgentSessionId)
+    || normalizedTargetAgent
+    || null;
+  const heartbeatStatus = cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeatPayload.activity_state)
+    || cleanText(heartbeatPayload.status)
+    || cleanText(heartbeatPayload.collaboration_heartbeat?.status)
+    || null;
+  const transferPacketResolvedId = transferPacketId
+    || cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    asset_id: cleanText(assetIntakeRecord?.asset_id)
+      || cleanText(assetIntakeRecord?.assetId)
+      || normalizedAssetId
+      || null,
+    intake_record_id: cleanText(assetIntakeRecord?.intake_record_id)
+      || cleanText(assetIntakeRecord?.intakeRecordId)
+      || cleanText(intake_record_id)
+      || cleanText(intakeRecordId)
+      || null,
+    classification_id: cleanText(classificationRecord?.classification_id)
+      || cleanText(classificationRecord?.classificationId)
+      || normalizedClassificationId
+      || null,
+    candidate_ids: uniqueCandidateIds,
+    candidate_count: candidateCount,
+    modernization_packet_id: modernizationPacketId,
+    transfer_packet_id: transferPacketResolvedId,
+    channel_id: resolvedChannelId,
+    proposal_id: proposalId,
+    assigned_owner: assignedOwnerResolved,
+    watch_id: watchId,
+    expected_acknowledgement: expectedAcknowledgement,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      asset_intake_record: assetIntakeRecord,
+      classification_record: classificationRecord,
+      candidate_records: candidateRecords,
+      modernization_packet_record: packetRecord,
+      transfer: transferPayload,
+      channel: channelPayload,
+      ownership_assignment: ownershipPayload,
+      proposal: proposalPayload,
+      message_watch: watchPayload,
+      heartbeat: heartbeatPayload,
+      transfer_channel_projection: transferChannelProjection,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    asset_intake_record: assetIntakeRecord,
+    classification_record: classificationRecord,
+    candidate_records: candidateRecords,
+    modernization_packet_record: packetRecord,
+    transfer: transferPayload,
+    channel: channelPayload,
+    ownership_assignment: ownershipPayload,
+    proposal: proposalPayload,
+    message_watch: watchPayload,
+    heartbeat: heartbeatPayload,
+    selected_candidates: normalizedCandidateRecords,
+  };
+}
+
+export async function requestModernizationWrapperExecution(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  modernizationPacket = {},
+  modernization_packet = {},
+  modernizationPacketId,
+  modernization_packet_id,
+  packetId,
+  packet_id,
+  sourceRef,
+  source_ref,
+  wrapperName,
+  wrapper_name,
+  wrapperContractRef,
+  wrapper_contract_ref,
+  executionScope = [],
+  execution_scope = [],
+  allowedBlastRadius = [],
+  allowed_blast_radius = [],
+  requiredEvidence = [],
+  required_evidence = [],
+  acceptanceCriteria = [],
+  acceptance_criteria = [],
+  riskLevel,
+  risk_level,
+  targetAgent,
+  target_agent,
+  handoffNotes,
+  handoff_notes,
+  collaborationRequired,
+  collaboration_required,
+  channelId,
+  channel_id,
+  transferChannelId,
+  transfer_channel_id,
+  assignedOwner,
+  assigned_owner,
+  wrapperExecutionRequired,
+  wrapper_execution_required,
+  submittedBy,
+  submitted_by,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  includeTransferChannelProjection = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedPacket = isPlainObject(modernization_packet)
+    ? modernization_packet
+    : (isPlainObject(modernizationPacket) ? modernizationPacket : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedPacket.project_id)
+    || cleanText(normalizedPacket.projectId)
+    || cleanText(normalizedPacket.related_project_id)
+    || cleanText(normalizedPacket.relatedProjectId);
+  const normalizedPacketId = cleanText(modernization_packet_id)
+    || cleanText(modernizationPacketId)
+    || cleanText(packet_id)
+    || cleanText(packetId)
+    || cleanText(normalizedPacket.modernization_packet_id)
+    || cleanText(normalizedPacket.modernizationPacketId)
+    || cleanText(normalizedPacket.packet_id)
+    || cleanText(normalizedPacket.packetId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedPacket.source_ref)
+    || cleanText(normalizedPacket.sourceRef)
+    || normalizedPacketId;
+  const normalizedWrapperName = cleanText(wrapper_name) || cleanText(wrapperName);
+  const normalizedWrapperContractRef = cleanText(wrapper_contract_ref) || cleanText(wrapperContractRef);
+  const normalizedExecutionScope = cleanList(execution_scope.length > 0 ? execution_scope : executionScope);
+  const normalizedAllowedBlastRadius = cleanList(allowed_blast_radius.length > 0 ? allowed_blast_radius : allowedBlastRadius);
+  const normalizedRequiredEvidence = cleanList(required_evidence.length > 0 ? required_evidence : requiredEvidence);
+  const normalizedAcceptanceCriteria = cleanList(acceptance_criteria.length > 0 ? acceptance_criteria : acceptanceCriteria);
+  const normalizedRiskLevel = cleanText(risk_level)
+    || cleanText(riskLevel)
+    || cleanText(normalizedPacket.risk_level)
+    || cleanText(normalizedPacket.riskLevel)
+    || null;
+  const normalizedHandoffNotes = cleanText(handoff_notes) || cleanText(handoffNotes);
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedTargetAgent = cleanText(target_agent) || cleanText(targetAgent) || cleanText(assigned_owner) || cleanText(assignedOwner) || null;
+  const normalizedWrapperExecutionRequired = wrapper_execution_required ?? wrapperExecutionRequired ?? true;
+  const normalizedCollaborationRequired = collaboration_required ?? collaborationRequired ?? Boolean(normalizedTargetAgent || channelId || channel_id || transferChannelId || transfer_channel_id);
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let packetRecord = null;
+  const packetLookupSurface = typeof client.getModernizationWorkPacketRecord === 'function'
+    ? client.getModernizationWorkPacketRecord.bind(client)
+    : typeof client.getModernizationPacketRecord === 'function'
+      ? client.getModernizationPacketRecord.bind(client)
+      : null;
+  if (!packetLookupSurface) {
+    missingSurfaces.push('getModernizationWorkPacketRecord');
+    missingSurfaces.push('getModernizationPacketRecord');
+  } else {
+    packetRecord = await packetLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: normalizedPacketId,
+      packetId: normalizedPacketId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'requestModernizationWrapperExecution',
+      },
+    }).catch(() => null);
+  }
+
+  const packetRecordPayload = isPlainObject(packetRecord) ? packetRecord : {};
+  const resolvedModernizationPacketId = cleanText(packetRecordPayload.modernization_packet_id)
+    || cleanText(packetRecordPayload.modernizationPacketId)
+    || cleanText(packetRecordPayload.work_packet_id)
+    || cleanText(packetRecordPayload.workPacketId)
+    || normalizedPacketId
+    || null;
+
+  let wrapperRequestRecord = null;
+  const wrapperRequestSurface = typeof client.createModernizationWrapperExecutionRequestRecord === 'function'
+    ? client.createModernizationWrapperExecutionRequestRecord.bind(client)
+    : typeof client.submitModernizationWrapperExecutionRequest === 'function'
+      ? client.submitModernizationWrapperExecutionRequest.bind(client)
+      : null;
+  if (!wrapperRequestSurface) {
+    missingSurfaces.push('createModernizationWrapperExecutionRequestRecord');
+    missingSurfaces.push('submitModernizationWrapperExecutionRequest');
+  } else {
+    wrapperRequestRecord = await wrapperRequestSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: resolvedModernizationPacketId,
+      wrapperName: normalizedWrapperName,
+      wrapperContractRef: normalizedWrapperContractRef,
+      sourceRef: normalizedSourceRef,
+      executionScope: normalizedExecutionScope,
+      allowedBlastRadius: normalizedAllowedBlastRadius,
+      requiredEvidence: normalizedRequiredEvidence,
+      acceptanceCriteria: normalizedAcceptanceCriteria,
+      riskLevel: normalizedRiskLevel,
+      targetAgent: normalizedTargetAgent,
+      handoffNotes: normalizedHandoffNotes,
+      wrapperExecutionRequired: Boolean(normalizedWrapperExecutionRequired),
+      metadata: {
+        ...normalizedMetadata,
+        source: 'requestModernizationWrapperExecution',
+      },
+    }).catch(() => null);
+  }
+
+  let transferResult = null;
+  const transferSurface = typeof client.transferWorkPacket === 'function'
+    ? client.transferWorkPacket.bind(client)
+    : null;
+  if (!transferSurface) missingSurfaces.push('transferWorkPacket');
+  if (transferSurface && (!wrapperRequestRecord || !wrapperRequestRecord.wrapper_execution_request_id) && (normalizedWrapperExecutionRequired || normalizedTargetAgent || normalizedCollaborationRequired)) {
+    transferResult = await transferSurface({
+      workflowRunId: resolvedWorkflowRunId,
+      transferKind: 'upstream_remediation',
+      objective: normalizedWrapperName || normalizedWrapperContractRef || 'Wrapper execution request',
+      requestedOutcome: normalizedHandoffNotes || normalizedWrapperContractRef || 'Prepare wrapper execution request.',
+      target: normalizedTargetAgent
+        ? {
+            intent: 'upstream_remediation',
+            recipient_mode: 'agent_session',
+            preferred_agent_session_id: normalizedTargetAgent,
+            preferred_role_key: normalizedTargetAgent,
+          }
+        : {
+            intent: 'upstream_remediation',
+            recipient_mode: 'role',
+            preferred_role_key: 'wrapper_execution',
+          },
+      artifacts: normalizedExecutionScope,
+      issues: normalizedAllowedBlastRadius,
+      expectedEvidence: normalizedRequiredEvidence,
+      preferredModes: ['bundle', 'artifact_refs', 'inline_payload'],
+      capabilities: {
+        wrapper_execution_required: Boolean(normalizedWrapperExecutionRequired),
+        allowed_blast_radius: normalizedAllowedBlastRadius,
+      },
+      senderAgentSessionId: normalizedSubmittedBy,
+      senderActorSessionId: null,
+      messageKind: 'handoff',
+      subject: normalizedWrapperName || normalizedWrapperContractRef || 'Wrapper execution request',
+      bodyMarkdown: normalizedHandoffNotes || normalizedWrapperContractRef || normalizedWrapperName,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'requestModernizationWrapperExecution',
+        modernization_packet_id: resolvedModernizationPacketId,
+        wrapper_execution_required: Boolean(normalizedWrapperExecutionRequired),
+      },
+    });
+  }
+  const transferPayload = isPlainObject(transferResult) ? transferResult : {};
+
+  const transferPacketId = cleanText(wrapperRequestRecord?.transfer_packet_id)
+    || cleanText(wrapperRequestRecord?.work_transfer_packet_id)
+    || cleanText(wrapperRequestRecord?.workTransferPacketId)
+    || cleanText(transferPayload.work_transfer_packet?.work_transfer_packet_id)
+    || cleanText(transferPayload.work_transfer_packet_id)
+    || cleanText(transferPayload.transfer_packet_id)
+    || cleanText(transferPayload.packet_id)
+    || null;
+
+  const transferChannelInputId = cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId);
+  const channelSurface = transferChannelInputId
+    ? (typeof client.resumeTransferChannel === 'function'
+      ? client.resumeTransferChannel.bind(client)
+      : null)
+    : (transferPacketId && typeof client.openTransferChannel === 'function'
+      ? client.openTransferChannel.bind(client)
+      : null);
+  if (!channelSurface && (transferChannelInputId || transferPacketId)) {
+    missingSurfaces.push(transferChannelInputId ? 'resumeTransferChannel' : 'openTransferChannel');
+  }
+  const channelResult = channelSurface && transferPacketId
+    ? await channelSurface({
+        transferChannelId: transferChannelInputId || undefined,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        channelKind: 'bidirectional',
+        upstreamAgentSessionId: normalizedSubmittedBy,
+        downstreamAgentSessionId: normalizedTargetAgent || undefined,
+        evidenceRequiredForClosure: true,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'requestModernizationWrapperExecution',
+        },
+      })
+    : null;
+  const channelPayload = isPlainObject(channelResult) ? channelResult : {};
+  const resolvedChannelId = cleanText(channelPayload.transfer_channel_id)
+    || cleanText(channelPayload.channel_id)
+    || cleanText(channelPayload.transfer_channel?.transfer_channel_id)
+    || cleanText(channelPayload.communication_transfer_channel?.transfer_channel_id)
+    || transferChannelInputId
+    || null;
+
+  const ownershipSurface = normalizedTargetAgent && resolvedChannelId && typeof client.assignCollaborationOwnership === 'function'
+    ? client.assignCollaborationOwnership.bind(client)
+    : null;
+  if (normalizedTargetAgent && !ownershipSurface) missingSurfaces.push('assignCollaborationOwnership');
+  const ownershipResult = ownershipSurface
+    ? await ownershipSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: 'wrapper_executor',
+        ownerAgentSessionId: normalizedTargetAgent,
+        ownerActorSessionId: null,
+        ownerLabel: normalizedTargetAgent,
+        assignmentState: 'assigned',
+        assignmentReason: normalizedWrapperName || normalizedWrapperContractRef || normalizedHandoffNotes,
+        currentPhase: 'wrapper_execution_request',
+        assignedByAgentSessionId: normalizedSubmittedBy,
+        assignedByActorSessionId: null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'requestModernizationWrapperExecution',
+        },
+      })
+    : null;
+  const ownershipPayload = isPlainObject(ownershipResult) ? ownershipResult : {};
+
+  const watchSurface = resolvedChannelId && typeof client.startMessageWatch === 'function'
+    ? client.startMessageWatch.bind(client)
+    : null;
+  if (resolvedChannelId && !watchSurface) missingSurfaces.push('startMessageWatch');
+  const watchResult = watchSurface
+    ? await watchSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedTargetAgent || 'wrapper_executor',
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          modernization_packet_id: resolvedModernizationPacketId,
+          expected_acknowledgement: 'wrapper execution request received',
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedHandoffNotes || normalizedWrapperContractRef || normalizedWrapperName,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'requestModernizationWrapperExecution',
+        },
+      })
+    : null;
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+
+  const heartbeatSurface = resolvedChannelId && typeof client.postCollaborationHeartbeat === 'function'
+    ? client.postCollaborationHeartbeat.bind(client)
+    : null;
+  if (resolvedChannelId && !heartbeatSurface) missingSurfaces.push('postCollaborationHeartbeat');
+  const heartbeatResult = heartbeatSurface
+    ? await heartbeatSurface({
+        transferChannelId: resolvedChannelId,
+        workTransferPacketId: transferPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        participantRole: normalizedTargetAgent ? 'wrapper_executor' : 'wrapper_planner',
+        currentPhase: 'wrapper_execution_request',
+        currentTaskSummary: normalizedWrapperName || normalizedWrapperContractRef || 'Wrapper execution request',
+        metadata: {
+          ...normalizedMetadata,
+          source: 'requestModernizationWrapperExecution',
+        },
+      }).catch(() => null)
+    : null;
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+
+  const transferChannelProjectionSurface = includeTransferChannelProjection && resolvedChannelId
+    ? (typeof client.getTransferChannelProjection === 'function'
+      ? client.getTransferChannelProjection.bind(client)
+      : typeof client.getLogaTransferChannelThreadProjection === 'function'
+        ? client.getLogaTransferChannelThreadProjection.bind(client)
+        : null)
+    : null;
+  if (includeTransferChannelProjection && resolvedChannelId && !transferChannelProjectionSurface) missingSurfaces.push('getTransferChannelProjection');
+  const transferChannelProjection = transferChannelProjectionSurface && resolvedChannelId
+    ? await transferChannelProjectionSurface(resolvedChannelId).catch(() => null)
+    : null;
+
+  const wrapperExecutionRequestId = cleanText(wrapperRequestRecord?.wrapper_execution_request_id)
+    || cleanText(wrapperRequestRecord?.wrapperExecutionRequestId)
+    || cleanText(wrapperRequestRecord?.execution_request_id)
+    || cleanText(wrapperRequestRecord?.executionRequestId)
+    || null;
+  const expectedAcknowledgement = cleanText(watchPayload.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_message_kind)
+    || cleanText(watchPayload.message_watch?.expected_acknowledgement)
+    || (normalizedTargetAgent ? 'acknowledgement' : null);
+  const ownershipAssignmentId = cleanText(ownershipPayload.collaboration_ownership_assignment_id)
+    || cleanText(ownershipPayload.ownership_assignment_id)
+    || cleanText(ownershipPayload.collaboration_ownership_assignment?.collaboration_ownership_assignment_id)
+    || cleanText(ownershipPayload.collaboration_ownership_assignment?.ownership_assignment_id)
+    || null;
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+  const heartbeatStatus = cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeatPayload.activity_state)
+    || cleanText(heartbeatPayload.status)
+    || cleanText(heartbeatPayload.collaboration_heartbeat?.status)
+    || null;
+  const wrapperExecutionRequiredResolved = Boolean(normalizedWrapperExecutionRequired);
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    modernization_packet_id: resolvedModernizationPacketId,
+    wrapper_execution_request_id: wrapperExecutionRequestId || null,
+    transfer_packet_id: transferPacketId,
+    target_agent: normalizedTargetAgent || null,
+    channel_id: resolvedChannelId,
+    ownership_assignment_id: ownershipAssignmentId,
+    watch_id: watchId,
+    expected_acknowledgement: expectedAcknowledgement,
+    wrapper_execution_required: wrapperExecutionRequiredResolved,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      modernization_packet_record: packetRecordPayload,
+      wrapper_execution_request_record: wrapperRequestRecord,
+      transfer: transferPayload,
+      channel: channelPayload,
+      ownership_assignment: ownershipPayload,
+      message_watch: watchPayload,
+      heartbeat: heartbeatPayload,
+      transfer_channel_projection: transferChannelProjection,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    modernization_packet_record: packetRecordPayload,
+    wrapper_execution_request_record: wrapperRequestRecord,
+    transfer: transferPayload,
+    channel: channelPayload,
+    ownership_assignment: ownershipPayload,
+    message_watch: watchPayload,
+    heartbeat: heartbeatPayload,
+  };
+}
+
+export async function getModernizationWrapperEvidence(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  modernizationPacket = {},
+  modernization_packet = {},
+  modernizationPacketId,
+  modernization_packet_id,
+  packetId,
+  packet_id,
+  wrapperExecutionRequest = {},
+  wrapper_execution_request = {},
+  wrapperExecutionRequestId,
+  wrapper_execution_request_id,
+  wrapperExecutionId,
+  wrapper_execution_id,
+  sourceRef,
+  source_ref,
+  includeOperations = true,
+  include_operations = true,
+  includeFileManifest = true,
+  include_file_manifest = true,
+  includeVerificationSummary = true,
+  include_verification_summary = true,
+  includeProjection = true,
+  include_projection = true,
+  includePortfolioBundle = true,
+  includeProjectRoadmap = true,
+  includeProjectActiveItem = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedPacket = isPlainObject(modernization_packet)
+    ? modernization_packet
+    : (isPlainObject(modernizationPacket) ? modernizationPacket : {});
+  const normalizedWrapperExecutionRequest = isPlainObject(wrapper_execution_request)
+    ? wrapper_execution_request
+    : (isPlainObject(wrapperExecutionRequest) ? wrapperExecutionRequest : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedPacket.project_id)
+    || cleanText(normalizedPacket.projectId)
+    || cleanText(normalizedPacket.related_project_id)
+    || cleanText(normalizedPacket.relatedProjectId)
+    || cleanText(normalizedWrapperExecutionRequest.project_id)
+    || cleanText(normalizedWrapperExecutionRequest.projectId)
+    || cleanText(normalizedWrapperExecutionRequest.related_project_id)
+    || cleanText(normalizedWrapperExecutionRequest.relatedProjectId);
+  const normalizedModernizationPacketId = cleanText(modernization_packet_id)
+    || cleanText(modernizationPacketId)
+    || cleanText(packet_id)
+    || cleanText(packetId)
+    || cleanText(normalizedPacket.modernization_packet_id)
+    || cleanText(normalizedPacket.modernizationPacketId)
+    || cleanText(normalizedPacket.packet_id)
+    || cleanText(normalizedPacket.packetId)
+    || cleanText(normalizedWrapperExecutionRequest.modernization_packet_id)
+    || cleanText(normalizedWrapperExecutionRequest.modernizationPacketId)
+    || cleanText(normalizedWrapperExecutionRequest.packet_id)
+    || cleanText(normalizedWrapperExecutionRequest.packetId);
+  const normalizedWrapperExecutionRequestId = cleanText(wrapper_execution_request_id)
+    || cleanText(wrapperExecutionRequestId)
+    || cleanText(normalizedWrapperExecutionRequest.wrapper_execution_request_id)
+    || cleanText(normalizedWrapperExecutionRequest.wrapperExecutionRequestId)
+    || cleanText(normalizedWrapperExecutionRequest.execution_request_id)
+    || cleanText(normalizedWrapperExecutionRequest.executionRequestId);
+  const normalizedWrapperExecutionId = cleanText(wrapper_execution_id)
+    || cleanText(wrapperExecutionId)
+    || cleanText(normalizedWrapperExecutionRequest.wrapper_execution_id)
+    || cleanText(normalizedWrapperExecutionRequest.wrapperExecutionId)
+    || cleanText(normalizedWrapperExecutionRequest.execution_id)
+    || cleanText(normalizedWrapperExecutionRequest.executionId)
+    || cleanText(normalizedWrapperExecutionRequest.wrapper_execution_record_id)
+    || cleanText(normalizedWrapperExecutionRequest.wrapperExecutionRecordId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedPacket.source_ref)
+    || cleanText(normalizedPacket.sourceRef)
+    || cleanText(normalizedWrapperExecutionRequest.source_ref)
+    || cleanText(normalizedWrapperExecutionRequest.sourceRef)
+    || normalizedModernizationPacketId
+    || normalizedWrapperExecutionRequestId
+    || normalizedWrapperExecutionId;
+  const normalizedIncludeOperations = include_operations ?? includeOperations ?? true;
+  const normalizedIncludeFileManifest = include_file_manifest ?? includeFileManifest ?? true;
+  const normalizedIncludeVerificationSummary = include_verification_summary ?? includeVerificationSummary ?? true;
+  const normalizedIncludeProjection = include_projection ?? includeProjection ?? true;
+
+  const pickSurface = (candidateNames) => {
+    for (const candidateName of candidateNames) {
+      if (typeof client[candidateName] === 'function') {
+        return client[candidateName].bind(client);
+      }
+    }
+    for (const candidateName of candidateNames) {
+      missingSurfaces.push(candidateName);
+    }
+    return null;
+  };
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const portfolioBundle = includePortfolioBundle && typeof client.getPortfolioBundle === 'function'
+    ? await client.getPortfolioBundle().catch(() => null)
+    : null;
+  const projectRoadmapSummary = resolvedProjectId && includeProjectRoadmap && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && includeProjectActiveItem && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+
+  let modernizationPacketRecord = null;
+  const packetLookupSurface = pickSurface(['getModernizationWorkPacketRecord', 'getModernizationPacketRecord']);
+  if (packetLookupSurface) {
+    modernizationPacketRecord = await packetLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: normalizedModernizationPacketId,
+      packetId: normalizedModernizationPacketId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'getModernizationWrapperEvidence',
+      },
+    }).catch(() => null);
+  }
+
+  const packetRecordPayload = isPlainObject(modernizationPacketRecord) ? modernizationPacketRecord : {};
+  const resolvedModernizationPacketId = cleanText(packetRecordPayload.modernization_packet_id)
+    || cleanText(packetRecordPayload.modernizationPacketId)
+    || cleanText(packetRecordPayload.work_packet_id)
+    || cleanText(packetRecordPayload.workPacketId)
+    || normalizedModernizationPacketId
+    || null;
+  let wrapperExecutionRequestRecord = null;
+  const wrapperRequestLookupSurface = pickSurface([
+    'getModernizationWrapperExecutionRequestRecord',
+    'getWrapperExecutionRequestRecord',
+    'getModernizationWrapperExecutionRequest',
+    'getWrapperExecutionRequest',
+  ]);
+  if (wrapperRequestLookupSurface) {
+    wrapperExecutionRequestRecord = await wrapperRequestLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: resolvedModernizationPacketId,
+      wrapperExecutionRequestId: normalizedWrapperExecutionRequestId,
+      wrapperExecutionId: normalizedWrapperExecutionId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'getModernizationWrapperEvidence',
+      },
+    }).catch(() => null);
+  }
+
+  const requestRecordPayload = isPlainObject(wrapperExecutionRequestRecord) ? wrapperExecutionRequestRecord : {};
+  const resolvedWrapperExecutionRequestId = cleanText(requestRecordPayload.wrapper_execution_request_id)
+    || cleanText(requestRecordPayload.wrapperExecutionRequestId)
+    || cleanText(requestRecordPayload.execution_request_id)
+    || cleanText(requestRecordPayload.executionRequestId)
+    || normalizedWrapperExecutionRequestId
+    || null;
+
+  let wrapperExecutionEvidenceBundle = null;
+  const wrapperEvidenceLookupSurface = pickSurface([
+    'getWrapperExecutionEvidenceBundle',
+    'getLatestWrapperExecutionEvidenceBundle',
+    'getModernizationWrapperEvidenceBundle',
+    'getModernizationWrapperExecutionEvidenceBundle',
+  ]);
+  if (wrapperEvidenceLookupSurface) {
+    wrapperExecutionEvidenceBundle = await wrapperEvidenceLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: resolvedModernizationPacketId,
+      wrapperExecutionRequestId: resolvedWrapperExecutionRequestId,
+      wrapperExecutionId: normalizedWrapperExecutionId,
+      includeOperations: Boolean(normalizedIncludeOperations),
+      includeFileManifest: Boolean(normalizedIncludeFileManifest),
+      includeVerificationSummary: Boolean(normalizedIncludeVerificationSummary),
+      includeProjection: Boolean(normalizedIncludeProjection),
+      metadata: {
+        ...normalizedMetadata,
+        source: 'getModernizationWrapperEvidence',
+      },
+    }).catch(() => null);
+  }
+
+  const bundlePayload = isPlainObject(wrapperExecutionEvidenceBundle) ? wrapperExecutionEvidenceBundle : {};
+  let wrapperExecutionRecord = isPlainObject(bundlePayload.wrapper_execution_record)
+    ? bundlePayload.wrapper_execution_record
+    : isPlainObject(bundlePayload.wrapperExecutionRecord)
+      ? bundlePayload.wrapperExecutionRecord
+      : null;
+  let wrapperOperationRecords = Array.isArray(bundlePayload.wrapper_operation_records)
+    ? bundlePayload.wrapper_operation_records.filter((record) => isPlainObject(record))
+    : Array.isArray(bundlePayload.wrapperOperationRecords)
+      ? bundlePayload.wrapperOperationRecords.filter((record) => isPlainObject(record))
+      : [];
+  let wrapperFileManifest = isPlainObject(bundlePayload.wrapper_file_manifest)
+    ? bundlePayload.wrapper_file_manifest
+    : isPlainObject(bundlePayload.wrapperFileManifest)
+      ? bundlePayload.wrapperFileManifest
+      : null;
+  let wrapperVerificationSummary = isPlainObject(bundlePayload.wrapper_verification_summary)
+    ? bundlePayload.wrapper_verification_summary
+    : isPlainObject(bundlePayload.wrapperVerificationSummary)
+      ? bundlePayload.wrapperVerificationSummary
+      : null;
+
+  if (!wrapperExecutionEvidenceBundle) {
+    if (!wrapperExecutionRecord) {
+      const wrapperRecordSurface = pickSurface([
+        'getWrapperExecutionRecord',
+        'getModernizationWrapperExecutionRecord',
+      ]);
+      if (wrapperRecordSurface) {
+        const wrapperRecordResult = await wrapperRecordSurface({
+          projectId: resolvedProjectId,
+          workflowId: resolvedWorkflowId,
+          workflowRunId: resolvedWorkflowRunId,
+          modernizationPacketId: resolvedModernizationPacketId,
+          wrapperExecutionRequestId: resolvedWrapperExecutionRequestId,
+          wrapperExecutionId: normalizedWrapperExecutionId,
+          sourceRef: normalizedSourceRef,
+          metadata: {
+            ...normalizedMetadata,
+            source: 'getModernizationWrapperEvidence',
+          },
+        }).catch(() => null);
+        if (isPlainObject(wrapperRecordResult)) {
+          wrapperExecutionRecord = wrapperRecordResult;
+        }
+      }
+    }
+
+    if (normalizedIncludeOperations && wrapperOperationRecords.length === 0) {
+      const wrapperOperationSurface = pickSurface([
+        'getWrapperExecutionOperationLog',
+        'getModernizationWrapperExecutionOperationLog',
+        'listWrapperExecutionOperations',
+      ]);
+      if (wrapperOperationSurface) {
+        const wrapperOperationResult = await wrapperOperationSurface({
+          projectId: resolvedProjectId,
+          workflowId: resolvedWorkflowId,
+          workflowRunId: resolvedWorkflowRunId,
+          modernizationPacketId: resolvedModernizationPacketId,
+          wrapperExecutionRequestId: resolvedWrapperExecutionRequestId,
+          wrapperExecutionId: normalizedWrapperExecutionId,
+          includeProjection: Boolean(normalizedIncludeProjection),
+          metadata: {
+            ...normalizedMetadata,
+            source: 'getModernizationWrapperEvidence',
+          },
+        }).catch(() => null);
+        if (Array.isArray(wrapperOperationResult)) {
+          wrapperOperationRecords = wrapperOperationResult.filter((record) => isPlainObject(record));
+        } else if (isPlainObject(wrapperOperationResult)) {
+          const maybeRecords = Array.isArray(wrapperOperationResult.wrapper_operation_records)
+            ? wrapperOperationResult.wrapper_operation_records
+            : Array.isArray(wrapperOperationResult.operation_records)
+              ? wrapperOperationResult.operation_records
+              : [];
+          wrapperOperationRecords = maybeRecords.filter((record) => isPlainObject(record));
+        }
+      }
+    }
+
+    if (normalizedIncludeFileManifest && !wrapperFileManifest) {
+      const wrapperFileManifestSurface = pickSurface([
+        'getWrapperExecutionFileManifest',
+        'getModernizationWrapperExecutionFileManifest',
+      ]);
+      if (wrapperFileManifestSurface) {
+        const wrapperFileManifestResult = await wrapperFileManifestSurface({
+          projectId: resolvedProjectId,
+          workflowId: resolvedWorkflowId,
+          workflowRunId: resolvedWorkflowRunId,
+          modernizationPacketId: resolvedModernizationPacketId,
+          wrapperExecutionRequestId: resolvedWrapperExecutionRequestId,
+          wrapperExecutionId: normalizedWrapperExecutionId,
+          metadata: {
+            ...normalizedMetadata,
+            source: 'getModernizationWrapperEvidence',
+          },
+        }).catch(() => null);
+        if (isPlainObject(wrapperFileManifestResult)) {
+          wrapperFileManifest = wrapperFileManifestResult;
+        }
+      }
+    }
+
+    if (normalizedIncludeVerificationSummary && !wrapperVerificationSummary) {
+      const wrapperVerificationSurface = pickSurface([
+        'getWrapperExecutionVerificationSummary',
+        'getModernizationWrapperExecutionVerificationSummary',
+      ]);
+      if (wrapperVerificationSurface) {
+        const wrapperVerificationResult = await wrapperVerificationSurface({
+          projectId: resolvedProjectId,
+          workflowId: resolvedWorkflowId,
+          workflowRunId: resolvedWorkflowRunId,
+          modernizationPacketId: resolvedModernizationPacketId,
+          wrapperExecutionRequestId: resolvedWrapperExecutionRequestId,
+          wrapperExecutionId: normalizedWrapperExecutionId,
+          metadata: {
+            ...normalizedMetadata,
+            source: 'getModernizationWrapperEvidence',
+          },
+        }).catch(() => null);
+        if (isPlainObject(wrapperVerificationResult)) {
+          wrapperVerificationSummary = wrapperVerificationResult;
+        }
+      }
+    }
+  }
+
+  const wrapperExecutionIdResolved = cleanText(wrapperExecutionRecord?.execution_id)
+    || cleanText(wrapperExecutionRecord?.executionId)
+    || cleanText(bundlePayload.wrapper_execution_persistence?.wrapper_execution_record_id)
+    || cleanText(bundlePayload.wrapper_execution_persistence?.wrapperExecutionRecordId)
+    || normalizedWrapperExecutionId
+    || null;
+  const executionStatus = cleanText(wrapperExecutionRecord?.status)
+    || cleanText(bundlePayload.wrapper_execution_record?.status)
+    || cleanText(bundlePayload.wrapperExecutionRecord?.status)
+    || null;
+  const verificationStatus = cleanText(wrapperVerificationSummary?.verification_status)
+    || cleanText(wrapperVerificationSummary?.verificationStatus)
+    || cleanText(bundlePayload.wrapper_verification_summary?.verification_status)
+    || cleanText(bundlePayload.wrapperVerificationSummary?.verificationStatus)
+    || null;
+
+  const filesCreated = Array.isArray(wrapperFileManifest?.files_created)
+    ? wrapperFileManifest.files_created
+    : Array.isArray(wrapperFileManifest?.filesCreated)
+      ? wrapperFileManifest.filesCreated
+      : [];
+  const filesModified = Array.isArray(wrapperFileManifest?.files_modified)
+    ? wrapperFileManifest.files_modified
+    : Array.isArray(wrapperFileManifest?.filesModified)
+      ? wrapperFileManifest.filesModified
+      : [];
+  const filesCreatedOrModified = cleanList([...filesCreated, ...filesModified]);
+
+  const collectedEvidenceRefs = [];
+  const collectEvidenceRefs = (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== null && item !== undefined && item !== '') {
+          collectedEvidenceRefs.push(item);
+        }
+      }
+      return;
+    }
+    if (value !== null && value !== undefined && value !== '') {
+      collectedEvidenceRefs.push(value);
+    }
+  };
+  collectEvidenceRefs(bundlePayload.evidence_refs);
+  collectEvidenceRefs(bundlePayload.evidenceRefs);
+  collectEvidenceRefs(wrapperExecutionRecord?.evidence_refs);
+  collectEvidenceRefs(wrapperExecutionRecord?.evidenceRefs);
+  collectEvidenceRefs(wrapperVerificationSummary?.evidence_refs);
+  collectEvidenceRefs(wrapperVerificationSummary?.evidenceRefs);
+  collectEvidenceRefs(requestRecordPayload.evidence_refs);
+  collectEvidenceRefs(requestRecordPayload.evidenceRefs);
+  collectEvidenceRefs(packetRecordPayload.evidence_refs);
+  collectEvidenceRefs(packetRecordPayload.evidenceRefs);
+  if (Array.isArray(wrapperOperationRecords)) {
+    for (const record of wrapperOperationRecords) {
+      collectEvidenceRefs(record?.evidence_ref);
+      collectEvidenceRefs(record?.evidenceRefs);
+      collectEvidenceRefs(record?.evidence_refs);
+    }
+  }
+  const uniqueEvidenceRefs = [];
+  const seenEvidenceRefKeys = new Set();
+  for (const evidenceRef of collectedEvidenceRefs) {
+    const key = typeof evidenceRef === 'string'
+      ? evidenceRef.trim()
+      : JSON.stringify(evidenceRef);
+    if (!key || seenEvidenceRefKeys.has(key)) continue;
+    seenEvidenceRefKeys.add(key);
+    uniqueEvidenceRefs.push(evidenceRef);
+  }
+
+  const transferPacketId = cleanText(wrapperExecutionRequestRecord?.transfer_packet_id)
+    || cleanText(wrapperExecutionRequestRecord?.work_transfer_packet_id)
+    || cleanText(wrapperExecutionRequestRecord?.workTransferPacketId)
+    || cleanText(bundlePayload.transfer_packet_id)
+    || cleanText(bundlePayload.transferPacketId)
+    || null;
+  const transferChannelId = cleanText(wrapperExecutionRequestRecord?.transfer_channel_id)
+    || cleanText(wrapperExecutionRequestRecord?.channel_id)
+    || cleanText(wrapperExecutionRequestRecord?.channelId)
+    || cleanText(bundlePayload.transfer_channel_id)
+    || cleanText(bundlePayload.transferChannelId)
+    || null;
+
+  let transferPacketProjection = null;
+  if (normalizedIncludeProjection && transferPacketId) {
+    if (typeof client.getTransferPacketProjection === 'function') {
+      transferPacketProjection = await client.getTransferPacketProjection(transferPacketId).catch(() => null);
+    } else {
+      missingSurfaces.push('getTransferPacketProjection');
+    }
+  }
+  let transferChannelProjection = null;
+  if (normalizedIncludeProjection && transferChannelId) {
+    const transferChannelProjectionSurface = typeof client.getTransferChannelProjection === 'function'
+      ? client.getTransferChannelProjection.bind(client)
+      : typeof client.getLogaTransferChannelThreadProjection === 'function'
+        ? client.getLogaTransferChannelThreadProjection.bind(client)
+        : null;
+    if (!transferChannelProjectionSurface) {
+      missingSurfaces.push('getTransferChannelProjection');
+    } else {
+      transferChannelProjection = await transferChannelProjectionSurface(transferChannelId).catch(() => null);
+    }
+  }
+
+  const operationCount = wrapperOperationRecords.length;
+  const gateReady = Boolean(
+    wrapperExecutionRecord
+    && executionStatus === 'completed'
+    && verificationStatus === 'pass'
+    && operationCount > 0
+    && filesCreatedOrModified.length > 0
+  );
+
+  return {
+    status: missingSurfaces.length > 0 ? 'partial' : 'ready',
+    project_id: resolvedProjectId || null,
+    modernization_packet_id: resolvedModernizationPacketId,
+    wrapper_execution_request_id: resolvedWrapperExecutionRequestId || null,
+    wrapper_execution_id: wrapperExecutionIdResolved,
+    execution_status: executionStatus,
+    operation_count: operationCount,
+    files_created_or_modified: filesCreatedOrModified,
+    verification_status: verificationStatus,
+    gate_ready: gateReady,
+    evidence_refs: uniqueEvidenceRefs,
+    operator_projection_metadata: {
+      portfolio_bundle: portfolioBundle,
+      project_roadmap_summary: projectRoadmapSummary,
+      project_roadmap_active_item: projectActiveItem,
+      modernization_packet_record: modernizationPacketRecord,
+      wrapper_execution_request_record: wrapperExecutionRequestRecord,
+      wrapper_execution_record: wrapperExecutionRecord,
+      wrapper_execution_evidence_bundle: wrapperExecutionEvidenceBundle,
+      wrapper_operation_records: wrapperOperationRecords,
+      wrapper_file_manifest: wrapperFileManifest,
+      wrapper_verification_summary: wrapperVerificationSummary,
+      transfer_packet_projection: transferPacketProjection,
+      transfer_channel_projection: transferChannelProjection,
+    },
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    modernization_packet_record: modernizationPacketRecord,
+    wrapper_execution_request_record: wrapperExecutionRequestRecord,
+    wrapper_execution_record: wrapperExecutionRecord,
+    wrapper_execution_evidence_bundle: wrapperExecutionEvidenceBundle,
+    wrapper_operation_records: wrapperOperationRecords,
+    wrapper_file_manifest: wrapperFileManifest,
+    wrapper_verification_summary: wrapperVerificationSummary,
+    transfer_packet_projection: transferPacketProjection,
+    transfer_channel_projection: transferChannelProjection,
+  };
+}
+
+export async function decideModernizationGate(client, {
+  projectIdentifier,
+  projectId,
+  relatedProjectId,
+  related_project_id,
+  startWorkBody = {},
+  startWorkRequest = {},
+  resumeProjectWorkOptions = {},
+  modernizationPacket = {},
+  modernization_packet = {},
+  modernizationPacketId,
+  modernization_packet_id,
+  packetId,
+  packet_id,
+  wrapperExecutionRequestId,
+  wrapper_execution_request_id,
+  wrapperExecutionId,
+  wrapper_execution_id,
+  sourceRef,
+  source_ref,
+  requiredEvidence = [],
+  required_evidence = [],
+  acceptanceCriteria = [],
+  acceptance_criteria = [],
+  decisionMode,
+  decision_mode,
+  decisionBand,
+  decision_band,
+  reviewer,
+  reviewer_id,
+  assignedReviewer,
+  assigned_reviewer,
+  reviewRequired,
+  review_required,
+  riskLevel,
+  risk_level,
+  rationale,
+  rationaleText,
+  decisionRationale,
+  decision_rationale,
+  recordDecision,
+  record_decision,
+  reviewChannelId,
+  review_channel_id,
+  channelId,
+  channel_id,
+  transferChannelId,
+  transfer_channel_id,
+  implementationItemId,
+  implementation_item_id,
+  submittedBy,
+  submitted_by,
+  includeProjection = true,
+  include_projection = true,
+  metadata = {},
+} = {}) {
+  const missingSurfaces = [];
+  const normalizedMetadata = isPlainObject(metadata) ? metadata : {};
+  const normalizedPacket = isPlainObject(modernization_packet)
+    ? modernization_packet
+    : (isPlainObject(modernizationPacket) ? modernizationPacket : {});
+  const normalizedProjectReference = cleanText(projectIdentifier)
+    || cleanText(projectId)
+    || cleanText(relatedProjectId)
+    || cleanText(related_project_id)
+    || cleanText(normalizedPacket.project_id)
+    || cleanText(normalizedPacket.projectId)
+    || cleanText(normalizedPacket.related_project_id)
+    || cleanText(normalizedPacket.relatedProjectId);
+  const normalizedModernizationPacketId = cleanText(modernization_packet_id)
+    || cleanText(modernizationPacketId)
+    || cleanText(packet_id)
+    || cleanText(packetId)
+    || cleanText(normalizedPacket.modernization_packet_id)
+    || cleanText(normalizedPacket.modernizationPacketId)
+    || cleanText(normalizedPacket.packet_id)
+    || cleanText(normalizedPacket.packetId);
+  const normalizedWrapperExecutionRequestId = cleanText(wrapper_execution_request_id)
+    || cleanText(wrapperExecutionRequestId);
+  const normalizedWrapperExecutionId = cleanText(wrapper_execution_id)
+    || cleanText(wrapperExecutionId);
+  const normalizedSourceRef = cleanText(source_ref)
+    || cleanText(sourceRef)
+    || cleanText(normalizedPacket.source_ref)
+    || cleanText(normalizedPacket.sourceRef)
+    || normalizedModernizationPacketId
+    || normalizedWrapperExecutionRequestId
+    || normalizedWrapperExecutionId;
+  const normalizedRequiredEvidence = cleanList(required_evidence.length > 0 ? required_evidence : requiredEvidence);
+  const normalizedAcceptanceCriteria = cleanList(acceptance_criteria.length > 0 ? acceptance_criteria : acceptanceCriteria);
+  const normalizedDecisionMode = cleanText(decision_mode) || cleanText(decisionMode) || 'recommend_only';
+  const normalizedDecisionBand = cleanText(decision_band) || cleanText(decisionBand) || null;
+  const normalizedReviewer = cleanText(reviewer_id)
+    || cleanText(reviewer)
+    || cleanText(assigned_reviewer)
+    || cleanText(assignedReviewer)
+    || null;
+  const normalizedReviewRequired = review_required ?? reviewRequired ?? Boolean(normalizedReviewer);
+  const normalizedRiskLevel = cleanText(risk_level) || cleanText(riskLevel) || cleanText(normalizedPacket.risk_level) || cleanText(normalizedPacket.riskLevel) || null;
+  const normalizedRationale = cleanText(decision_rationale)
+    || cleanText(decisionRationale)
+    || cleanText(rationaleText)
+    || cleanText(rationale)
+    || null;
+  const normalizedRecordDecision = record_decision ?? recordDecision ?? normalizedDecisionMode === 'record_decision';
+  const normalizedSubmittedBy = cleanText(submitted_by)
+    || cleanText(submittedBy)
+    || client.agentSessionId
+    || client.actorId
+    || null;
+  const normalizedReviewChannelId = cleanText(review_channel_id)
+    || cleanText(reviewChannelId)
+    || cleanText(channel_id)
+    || cleanText(channelId)
+    || cleanText(transfer_channel_id)
+    || cleanText(transferChannelId)
+    || null;
+
+  const pickSurface = (candidateNames) => {
+    for (const candidateName of candidateNames) {
+      if (typeof client[candidateName] === 'function') {
+        return client[candidateName].bind(client);
+      }
+    }
+    for (const candidateName of candidateNames) {
+      missingSurfaces.push(candidateName);
+    }
+    return null;
+  };
+
+  let continuation = null;
+  let startWorkResult = null;
+  if (normalizedProjectReference) {
+    if (typeof client.resumeProjectWork === 'function') {
+      continuation = await client.resumeProjectWork({
+        projectIdentifier: normalizedProjectReference,
+        projectId: normalizedProjectReference,
+        requireClaim: false,
+        ...resumeProjectWorkOptions,
+      });
+    } else {
+      missingSurfaces.push('resumeProjectWork');
+    }
+  } else if (Object.keys(isPlainObject(startWorkRequest) ? startWorkRequest : {}).length > 0 || Object.keys(isPlainObject(startWorkBody) ? startWorkBody : {}).length > 0) {
+    if (typeof client.startWork === 'function') {
+      startWorkResult = await client.startWork({
+        ...(isPlainObject(startWorkBody) ? startWorkBody : {}),
+        ...(isPlainObject(startWorkRequest) ? startWorkRequest : {}),
+      });
+    } else {
+      missingSurfaces.push('startWork');
+    }
+  }
+
+  const projectPayload = isPlainObject(continuation?.project)
+    ? continuation.project
+    : isPlainObject(startWorkResult?.project)
+      ? startWorkResult.project
+      : isPlainObject(continuation?.summary)
+        ? continuation.summary
+        : {};
+  const resolvedProjectId = cleanText(projectPayload.project_id)
+    || cleanText(projectPayload.projectId)
+    || normalizedProjectReference;
+  const resolvedWorkflowId = cleanText(projectPayload.workflow_id)
+    || cleanText(projectPayload.workflowId)
+    || cleanText(continuation?.workflow_id)
+    || cleanText(startWorkResult?.workflow_id);
+  const resolvedWorkflowRunId = cleanText(projectPayload.workflow_run_id)
+    || cleanText(projectPayload.workflowRunId)
+    || cleanText(continuation?.workflow_run_id)
+    || cleanText(startWorkResult?.workflow_run_id)
+    || cleanText(startWorkResult?.workflowRunId);
+
+  const wrapperEvidence = await client.getModernizationWrapperEvidence({
+    projectIdentifier: resolvedProjectId || normalizedProjectReference,
+    modernizationPacketId: normalizedModernizationPacketId,
+    wrapperExecutionRequestId: normalizedWrapperExecutionRequestId,
+    wrapperExecutionId: normalizedWrapperExecutionId,
+    sourceRef: normalizedSourceRef,
+    includeOperations: true,
+    includeFileManifest: true,
+    includeVerificationSummary: true,
+    includeProjection: Boolean(include_projection ?? includeProjection ?? true),
+    metadata: {
+      ...normalizedMetadata,
+      source: 'decideModernizationGate',
+    },
+  }).catch(() => null);
+  const wrapperEvidencePayload = isPlainObject(wrapperEvidence) ? wrapperEvidence : {};
+
+  let modernizationPacketRecord = isPlainObject(wrapperEvidencePayload.modernization_packet_record)
+    ? wrapperEvidencePayload.modernization_packet_record
+    : null;
+  const packetLookupSurface = typeof client.getModernizationWorkPacketRecord === 'function'
+    ? client.getModernizationWorkPacketRecord.bind(client)
+    : typeof client.getModernizationPacketRecord === 'function'
+      ? client.getModernizationPacketRecord.bind(client)
+      : null;
+  if (!modernizationPacketRecord && packetLookupSurface) {
+    modernizationPacketRecord = await packetLookupSurface({
+      projectId: resolvedProjectId,
+      workflowId: resolvedWorkflowId,
+      workflowRunId: resolvedWorkflowRunId,
+      modernizationPacketId: normalizedModernizationPacketId,
+      packetId: normalizedModernizationPacketId,
+      sourceRef: normalizedSourceRef,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'decideModernizationGate',
+      },
+    }).catch(() => null);
+  }
+  if (!packetLookupSurface) {
+    missingSurfaces.push('getModernizationWorkPacketRecord');
+    missingSurfaces.push('getModernizationPacketRecord');
+  }
+
+  const packetRecordPayload = isPlainObject(modernizationPacketRecord) ? modernizationPacketRecord : {};
+  const resolvedModernizationPacketId = cleanText(packetRecordPayload.modernization_packet_id)
+    || cleanText(packetRecordPayload.modernizationPacketId)
+    || cleanText(packetRecordPayload.work_packet_id)
+    || cleanText(packetRecordPayload.workPacketId)
+    || normalizedModernizationPacketId
+    || null;
+  const resolvedImplementationItemId = cleanText(packetRecordPayload.implementation_item_id)
+    || cleanText(packetRecordPayload.implementationItemId)
+    || cleanText(packetRecordPayload.roadmap_item_id)
+    || cleanText(packetRecordPayload.roadmapItemId)
+    || cleanText(implementation_item_id)
+    || cleanText(implementationItemId)
+    || null;
+
+  const acceptanceCriteriaResolved = normalizedAcceptanceCriteria.length > 0
+    ? normalizedAcceptanceCriteria
+    : cleanList(packetRecordPayload.acceptance_criteria || packetRecordPayload.acceptanceCriteria || []);
+  const evidenceRefs = cleanList([
+    ...(Array.isArray(wrapperEvidencePayload.evidence_refs) ? wrapperEvidencePayload.evidence_refs : []),
+    ...(Array.isArray(wrapperEvidencePayload.evidenceRefs) ? wrapperEvidencePayload.evidenceRefs : []),
+  ]);
+  const requiredEvidenceMissing = normalizedRequiredEvidence.filter((evidenceRef) => !evidenceRefs.includes(evidenceRef));
+  const evidenceStatus = wrapperEvidencePayload.wrapper_execution_record
+    ? (wrapperEvidencePayload.gate_ready === true ? 'complete' : 'incomplete')
+    : 'absent';
+  const verificationStatus = cleanText(wrapperEvidencePayload.verification_status)
+    || cleanText(wrapperEvidencePayload.wrapper_verification_summary?.verification_status)
+    || cleanText(wrapperEvidencePayload.wrapper_verification_summary?.verificationStatus)
+    || null;
+  const evidenceComplete = evidenceStatus === 'complete' && verificationStatus === 'pass' && requiredEvidenceMissing.length === 0;
+  const reviewChannelPresent = Boolean(normalizedReviewChannelId);
+  const reviewRequiredResolved = Boolean(normalizedReviewRequired || evidenceStatus !== 'complete' || verificationStatus !== 'pass' || requiredEvidenceMissing.length > 0 || acceptanceCriteriaResolved.length === 0);
+  const recommendedDecision = evidenceComplete ? 'pass' : (reviewRequiredResolved ? 'pending' : 'block');
+  const gateDecisionRequested = normalizedRecordDecision && evidenceComplete;
+
+  let gateDecisionResult = null;
+  const gateDecisionSurface = typeof client.createImplementationPacketGateDecision === 'function'
+    ? client.createImplementationPacketGateDecision.bind(client)
+    : null;
+  if (normalizedRecordDecision && !gateDecisionSurface) {
+    missingSurfaces.push('createImplementationPacketGateDecision');
+  }
+  if (normalizedRecordDecision && gateDecisionSurface) {
+    gateDecisionResult = await gateDecisionSurface(resolvedModernizationPacketId, {
+      gate_type: cleanText(normalizedDecisionBand) || 'modernization_gate',
+      decision: evidenceComplete ? 'pass' : 'block',
+      rationale: normalizedRationale
+        || (evidenceComplete
+          ? 'Wrapper evidence satisfies the modernization gate.'
+          : 'Wrapper evidence is incomplete or unavailable; the gate cannot be marked as pass.'),
+      evidence_refs: evidenceRefs,
+      remediation_actions: evidenceComplete ? [] : ['Review wrapper evidence and missing modernization surfaces.'],
+      decided_by: normalizedReviewer || normalizedSubmittedBy || client.agentSessionId || client.actorId || null,
+    }).catch(() => null);
+  }
+
+  let gateDecisionId = cleanText(gateDecisionResult?.implementation_gate_decision_id)
+    || cleanText(gateDecisionResult?.gate_decision_id)
+    || null;
+
+  let evidenceLinkResult = null;
+  if (gateDecisionId && typeof client.addImplementationItemEvidence === 'function' && resolvedImplementationItemId) {
+    evidenceLinkResult = await client.addImplementationItemEvidence(
+      resolvedImplementationItemId,
+      {
+        evidence_type: 'modernization_gate_decision',
+        evidence_ref: gateDecisionId,
+        title: `Modernization gate decision for ${resolvedModernizationPacketId}`,
+        recorded_by: normalizedReviewer || normalizedSubmittedBy || client.agentSessionId || client.actorId || null,
+        metadata: {
+          ...normalizedMetadata,
+          source: 'decideModernizationGate',
+          modernization_packet_id: resolvedModernizationPacketId,
+          wrapper_execution_id: cleanText(wrapperEvidencePayload.wrapper_execution_id) || cleanText(wrapperEvidencePayload.wrapper_execution_record?.execution_id) || null,
+          decision: gateDecisionResult?.decision || (evidenceComplete ? 'pass' : 'block'),
+        },
+      },
+    ).catch(() => null);
+  } else if (gateDecisionId && !resolvedImplementationItemId) {
+    missingSurfaces.push('addImplementationItemEvidence');
+  }
+
+  let watchResult = null;
+  if (reviewRequiredResolved && reviewChannelPresent) {
+    const watchSurface = typeof client.startMessageWatch === 'function'
+      ? client.startMessageWatch.bind(client)
+      : null;
+    if (!watchSurface) {
+      missingSurfaces.push('startMessageWatch');
+    } else {
+      watchResult = await watchSurface({
+        transferChannelId: normalizedReviewChannelId,
+        workTransferPacketId: cleanText(wrapperEvidencePayload.transfer_packet_id) || cleanText(wrapperEvidencePayload.modernization_packet_id) || resolvedModernizationPacketId,
+        workflowRunId: resolvedWorkflowRunId,
+        watchingAgentRole: normalizedSubmittedBy,
+        expectedFromRole: normalizedReviewer || 'reviewer',
+        expectedMessageKind: 'response',
+        watchType: 'expected_peer_message',
+        watchingAgentSessionId: normalizedSubmittedBy,
+        expectedPayload: {
+          modernization_packet_id: resolvedModernizationPacketId,
+          expected_decision: recommendedDecision,
+        },
+        currentStatus: 'watching',
+        operatorNudge: normalizedRationale || 'Review modernization gate recommendation.',
+        metadata: {
+          ...normalizedMetadata,
+          source: 'decideModernizationGate',
+        },
+      }).catch(() => null);
+    }
+  }
+
+  const watchPayload = isPlainObject(watchResult) ? watchResult : {};
+  const watchId = cleanText(watchPayload.message_watch_id)
+    || cleanText(watchPayload.watch_id)
+    || cleanText(watchPayload.message_watch?.message_watch_id)
+    || cleanText(watchPayload.message_watch?.watch_id)
+    || null;
+
+  let heartbeatResult = null;
+  if (reviewChannelPresent && typeof client.postCollaborationHeartbeat === 'function') {
+    heartbeatResult = await client.postCollaborationHeartbeat({
+      transferChannelId: normalizedReviewChannelId,
+      workTransferPacketId: cleanText(wrapperEvidencePayload.transfer_packet_id) || resolvedModernizationPacketId,
+      workflowRunId: resolvedWorkflowRunId,
+      participantRole: normalizedReviewer ? 'reviewer' : 'gate_reviewer',
+      currentPhase: 'modernization_gate_review',
+      currentTaskSummary: normalizedRationale || `Review modernization gate for ${resolvedModernizationPacketId}`,
+      metadata: {
+        ...normalizedMetadata,
+        source: 'decideModernizationGate',
+      },
+    }).catch(() => null);
+  } else if (reviewChannelPresent) {
+    missingSurfaces.push('postCollaborationHeartbeat');
+  }
+  const heartbeatPayload = isPlainObject(heartbeatResult) ? heartbeatResult : {};
+  const heartbeatStatus = cleanText(heartbeatPayload.collaboration_heartbeat?.activity_state)
+    || cleanText(heartbeatPayload.activity_state)
+    || cleanText(heartbeatPayload.status)
+    || null;
+
+  const projectRoadmapSummary = resolvedProjectId && typeof client.getProjectRoadmapSummary === 'function'
+    ? await client.getProjectRoadmapSummary(resolvedProjectId).catch(() => null)
+    : null;
+  const projectActiveItem = resolvedProjectId && typeof client.getProjectRoadmapActiveItem === 'function'
+    ? await client.getProjectRoadmapActiveItem(resolvedProjectId).catch(() => null)
+    : null;
+  let projectProjection = null;
+  if (include_projection ?? includeProjection ?? true) {
+    const projectProjectionSurface = typeof client.getLogaProjectPortfolioProjection === 'function'
+      ? client.getLogaProjectPortfolioProjection.bind(client)
+      : null;
+    if (projectProjectionSurface) {
+      projectProjection = await projectProjectionSurface().catch(() => null);
+    } else {
+      missingSurfaces.push('getLogaProjectPortfolioProjection');
+    }
+  }
+
+  const operatorProjectionMetadata = {
+    modernization_packet_record: modernizationPacketRecord,
+    wrapper_evidence: wrapperEvidencePayload,
+    gate_decision: gateDecisionResult,
+    gate_decision_evidence_link: evidenceLinkResult,
+    project_roadmap_summary: projectRoadmapSummary,
+    project_roadmap_active_item: projectActiveItem,
+    project_projection: projectProjection,
+    review_watch: watchPayload,
+    review_heartbeat: heartbeatPayload,
+    acceptance_criteria: acceptanceCriteriaResolved,
+  };
+
+  const status = evidenceComplete
+    ? (gateDecisionRequested ? 'ready' : (missingSurfaces.length > 0 ? 'partial' : 'ready'))
+    : (reviewRequiredResolved ? 'review_required' : 'blocked');
+
+  return {
+    status,
+    project_id: resolvedProjectId || null,
+    modernization_packet_id: resolvedModernizationPacketId,
+    wrapper_execution_id: cleanText(wrapperEvidencePayload.wrapper_execution_id) || cleanText(wrapperEvidencePayload.wrapper_execution_record?.execution_id) || normalizedWrapperExecutionId || null,
+    evidence_status: evidenceStatus,
+    verification_status: verificationStatus,
+    recommended_decision: recommendedDecision,
+    gate_decision_id: gateDecisionId || null,
+    review_required: reviewRequiredResolved,
+    watch_id: watchId || null,
+    heartbeat_status: heartbeatStatus,
+    operator_projection_metadata: operatorProjectionMetadata,
+    missing_surfaces: [...new Set(missingSurfaces)],
+    project: projectPayload,
+    modernization_packet_record: modernizationPacketRecord,
+    wrapper_evidence: wrapperEvidencePayload,
+    gate_decision: gateDecisionResult,
+    gate_decision_evidence_link: evidenceLinkResult,
+    review_watch: watchPayload,
+    review_heartbeat: heartbeatPayload,
   };
 }