@tiinex/core 0.1.1

package/src/tooling/portable/handoff/recipientV2.artifactFirst.roles.js

@@ -0,0 +1,166 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { renderRecipientV2Pointer } from './recipientV2.artifacts.js';
+
+export function buildPhase1RolePointers(input = {}) {
+  const kind = input.kind === 'endpoint' ? 'endpoint' : 'participant';
+  const expectedRole = `${kind}-role`;
+  const artifacts = [];
+  const projections = [];
+  const findings = [];
+  const workspaceById = new Map((input.workspaceCarriers || []).map((item) => [String(item.workspaceId || ''), item]));
+  for (const [index, sourcePointerPath] of [...(input.sourcePointerPaths || [])].entries()) {
+    const facts = input.sourceFactsByPath?.get(String(sourcePointerPath || '')) || null;
+    if (!facts || String(facts.role || '') !== expectedRole) {
+      findings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.source-unresolved`, `Selected-route ${kind} Role Pointer transport facts are unavailable in the qualified source carrier.`, { path: String(sourcePointerPath || '') }));
+      continue;
+    }
+    const targetCarrierKind = String(facts.targetCarrierKind || '');
+    const targetWorkspaceId = String(facts.targetWorkspaceId || '');
+    const workspaceCarrier = targetCarrierKind === 'workspace-archive-entry' ? workspaceById.get(targetWorkspaceId) || null : null;
+    const targetPayload = workspaceCarrier ? workspaceCarrier.payloadArtifactPath : targetCarrierKind === 'workspace-cache-entry' ? String(input.cacheArtifact?.path || '') : '';
+    if (!targetPayload) {
+      findings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.target-unresolved`, `Selected-route ${kind} Role target must resolve to an explicit carried Workspace or cache External Payload artifact.`, { path: String(sourcePointerPath || ''), targetCarrierKind, targetWorkspaceId }));
+      continue;
+    }
+    if (targetCarrierKind === 'workspace-cache-entry' && !(input.selectedCacheMaterials || []).some((item) => String(item.archiveEntry || '') === String(facts.targetArchiveEntry || ''))) {
+      findings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.cache-material-unresolved`, `${kind} Role cache target is not owned by the selected-route cache External Payload.`, { path: String(sourcePointerPath || ''), targetArchiveEntry: String(facts.targetArchiveEntry || '') }));
+      continue;
+    }
+    const roleLabel = String(facts.roleLabelHint || `${kind}-role`);
+    const pathPrefix = String(input.pathPrefix || '001-6').replace(/-+$/g, '') || '001-6';
+    const pointerPath = `${pathPrefix}-${kind === 'endpoint' ? 'e' : 'p'}-${index + 1}-${safeToken(roleLabel)}-role-pointer.trace.md`;
+    const requirementId = String(kind === 'endpoint' ? facts.endpointRequirementId : facts.participantRequirementId || '');
+    const currentRead = [
+      { label: 'Workspace Id', value: `\`${String(input.routeWorkspaceId || '')}\`` },
+      { label: 'Route Id', value: `\`${String(input.selectedRouteId || '')}\`` },
+      ...(kind === 'endpoint' ? [
+        { label: 'Endpoint Requirement Id', value: `\`${requirementId}\`` },
+        { label: 'Endpoint Party', value: String(facts.endpointParty || '') }
+      ] : [{ label: 'Participant Requirement Id', value: `\`${requirementId}\`` }]),
+      ...(facts.roleLabelHint ? [{ label: 'Role Label Hint', value: String(facts.roleLabelHint) }] : []),
+      { label: 'Role Reference', value: `\`${String(facts.referenceTarget || '')}\`` },
+      { label: 'Target Carrier Kind', value: targetCarrierKind },
+      { label: 'Target Payload', value: `[payload](${targetPayload})` },
+      ...(targetCarrierKind === 'workspace-archive-entry' ? [
+        { label: 'Target Workspace Id', value: `\`${targetWorkspaceId}\`` },
+        { label: 'Target Inner Path', value: `\`${String(facts.targetInnerPath || '')}\`` }
+      ] : []),
+      ...(targetCarrierKind === 'workspace-cache-entry' ? [{ label: 'Target Archive Entry', value: `\`${String(facts.targetArchiveEntry || '')}\`` }] : [])
+    ];
+    const pointer = finalizeFile({
+      path: pointerPath,
+      kind: `${kind}-role-pointer`,
+      logicalKind: `recipient-v2-phase1-${kind}-role-pointer`,
+      mediaType: 'text/markdown',
+      content: renderRecipientV2Pointer({
+        artifactFirst: true,
+        createdAt: input.createdAt,
+        role: expectedRole,
+        title: `${kind === 'endpoint' ? 'Endpoint' : 'Participant'} Role Pointer — ${roleLabel}`,
+        summary: `Artifact-first Pointer to one exact ${kind} Role artifact carried by an explicit Workspace or cache External Payload.`,
+        prose: kind === 'endpoint'
+          ? 'This Pointer grounds one exact Handoff From/To Role endpoint. It does not prove a human holder, consent, Handoff acceptance, or Role authority beyond the referenced Role artifact.'
+          : 'This Pointer contributes one additional participant Role to interaction grounding. It does not change Handoff From/To, prove a human holder, or create Role authority.',
+        currentRead,
+        destinations: [{ label: `Exact ${kind} Role payload owner`, target: targetPayload }]
+      })
+    });
+    artifacts.push(pointer);
+    projections.push(Object.freeze({
+      pointerPath,
+      workspaceId: String(input.routeWorkspaceId || ''),
+      routeId: String(input.selectedRouteId || ''),
+      requirementId,
+      ...(kind === 'endpoint' ? { endpointParty: String(facts.endpointParty || '') } : {}),
+      roleLabelHint: String(facts.roleLabelHint || ''),
+      referenceTarget: String(facts.referenceTarget || ''),
+      targetCarrierKind,
+      targetWorkspaceId,
+      targetInnerPath: String(facts.targetInnerPath || facts.targetArchiveEntry || ''),
+      targetSha256: String(facts.targetSha256 || '')
+    }));
+  }
+  return Object.freeze({ artifacts: Object.freeze(artifacts), projections: Object.freeze(projections), findings: Object.freeze(findings) });
+}
+
+export function qualifyPhase1RolePointer(pointer = null, context = {}, findings = []) {
+  const kind = context.kind === 'endpoint' ? 'endpoint' : 'participant';
+  const parsed = pointer?.parsed || {};
+  const localFindings = [];
+  const targetCarrierKind = String(parsed.targetCarrierKind || '');
+  if (String(parsed.workspaceId || '') !== String(context.routeWorkspaceId || '') || String(parsed.routeId || '') !== String(context.routeId || '')) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.route-binding-mismatch`, `${kind} Role Pointer must visibly bind the selected route Workspace and route id.`, { path: String(pointer?.path || '') }));
+  if (!['workspace-archive-entry', 'workspace-cache-entry'].includes(targetCarrierKind)) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.target-carrier-invalid`, `${kind} Role Pointer target carrier must be an explicit Workspace or selected-route cache payload.`, { path: String(pointer?.path || ''), targetCarrierKind }));
+  const targetPayload = String(parsed.targetPayload || '');
+  let targetArchive = null;
+  let archivePath = '';
+  let targetPath = '';
+  let targetWorkspaceId = String(parsed.targetWorkspaceId || '');
+  if (targetCarrierKind === 'workspace-archive-entry') {
+    const workspace = context.workspaceQualifications?.get(targetWorkspaceId) || null;
+    if (!workspace) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.workspace-unresolved`, `${kind} Role Pointer target Workspace is not carried as a qualified artifact-first Workspace payload.`, { targetWorkspaceId }));
+    else {
+      if (targetPayload !== String(workspace.payload?.path || '')) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.workspace-payload-mismatch`, `${kind} Role Pointer must target the explicit External Payload for its target Workspace.`, { targetWorkspaceId }));
+      targetArchive = workspace.archive;
+      archivePath = String(workspace.payload?.parsed?.location || '');
+      targetPath = String(parsed.targetInnerPath || '');
+    }
+  } else if (targetCarrierKind === 'workspace-cache-entry') {
+    const cacheIndex = (context.cachePayloads || []).findIndex((item) => String(item.path || '') === targetPayload);
+    if (cacheIndex < 0) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.cache-payload-unresolved`, `${kind} Role Pointer must target the explicit selected-route cache External Payload.`, { targetPayload }));
+    else {
+      const cacheQualification = context.cacheQualifications?.[cacheIndex] || null;
+      targetPath = String(parsed.targetArchiveEntry || '');
+      const material = (cacheQualification?.materials || []).find((item) => String(item.archiveEntry || '') === targetPath) || null;
+      if (!material) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.cache-entry-unowned`, `${kind} Role cache target must be one exact material explicitly owned by the selected-route cache External Payload.`, { targetPath }));
+      targetArchive = cacheQualification?.archive || null;
+      archivePath = String(cacheQualification?.payloadPath || '');
+    }
+  }
+  const matches = targetArchive?.state === 'qualified' ? targetArchive.entries.filter((entry) => String(entry.path || '') === targetPath) : [];
+  if (!targetPath || matches.length !== 1) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.target-unresolved`, `${kind} Role Pointer must resolve exactly one exact Role artifact inside its explicit payload owner.`, { targetPayload, targetPath, count: matches.length }));
+  let targetBytes = 0;
+  let targetSha256 = '';
+  if (matches.length === 1) {
+    const data = packageFileBytes({ data: matches[0].data });
+    targetBytes = data.byteLength;
+    targetSha256 = sha256Hex(data);
+    const markdown = decodeUtf8(data);
+    if (currentSchemaId(markdown) !== 'tiinex.party.role.v1') localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.schema-invalid`, `${kind} Role Pointer target must be one exact tiinex.party.role.v1 artifact.`, { targetPath }));
+    const roleLabel = fieldValue(sectionText(markdown, 'Role Identity'), 'Role Label');
+    if (!roleLabel) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.label-unresolved`, `${kind} Role target must visibly declare Role Label.`, { targetPath }));
+    if (parsed.roleLabelHint && roleLabel && normalizeToken(parsed.roleLabelHint) !== normalizeToken(roleLabel)) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.label-mismatch`, `${kind} Role Pointer label hint conflicts with the exact carried Role artifact.`, { hint: parsed.roleLabelHint, roleLabel }));
+  }
+  const requirementId = kind === 'endpoint' ? String(parsed.endpointRequirementId || '') : String(parsed.participantRequirementId || '');
+  if (!requirementId || !parsed.roleReference) localFindings.push(finding('error', `portable.handoff-v2-phase1.${kind}-role.binding-incomplete`, `${kind} Role Pointer must visibly preserve its requirement id and Role reference.`));
+  if (kind === 'endpoint' && !['from', 'to'].includes(String(parsed.endpointParty || '').toLowerCase())) localFindings.push(finding('error', 'portable.handoff-v2-phase1.endpoint-role.party-invalid', 'Endpoint Role Pointer must visibly declare endpoint party from or to.'));
+  findings.push(...localFindings);
+  return Object.freeze({
+    state: localFindings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified',
+    pointerPath: String(pointer?.path || ''),
+    workspaceId: String(parsed.workspaceId || ''),
+    routeId: String(parsed.routeId || ''),
+    requirementId,
+    ...(kind === 'endpoint' ? { endpointParty: String(parsed.endpointParty || '') } : {}),
+    roleLabelHint: String(parsed.roleLabelHint || ''),
+    referenceTarget: String(parsed.roleReference || ''),
+    targetCarrierKind,
+    targetWorkspaceId,
+    archivePath,
+    targetInnerPath: targetPath,
+    targetArchiveEntry: targetCarrierKind === 'workspace-cache-entry' ? targetPath : '',
+    targetBytes,
+    targetSha256,
+    findings: Object.freeze(localFindings)
+  });
+}
+
+function currentSchemaId(markdown = '') { return String(String(markdown || '').match(/Current Schema:\s*(?:\[)?(tiinex\.[a-z0-9._-]+)(?:\])?/i)?.[1] || '').toLowerCase(); }
+function sectionText(markdown = '', heading = '') { const re = new RegExp(`^##\\s+${escapeRe(heading)}\\s*$`, 'mi'); const match = re.exec(String(markdown || '')); if (!match) return ''; const rest = String(markdown || '').slice(match.index + match[0].length); const next = /^##\s+/m.exec(rest); return (next ? rest.slice(0, next.index) : rest).trim(); }
+function fieldValue(section = '', name = '') { const m = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRe(name)}:\\s*(.+?)\\s*$`, 'mi')); return String(m?.[1] || '').trim(); }
+function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
+function escapeRe(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function normalizeToken(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, ''); }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function safeToken(value = '') { return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'role'; }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }

package/src/tooling/portable/handoff/recipientV2.artifactFirst.routes.js

@@ -0,0 +1,113 @@
+import { qualifySelectedHandoffArtifact } from './routeArtifactConformance.js';
+import { qualifyPhase1RolePointer } from './recipientV2.artifactFirst.roles.js';
+import { qualifyPhase1RequiredContextClosure, resolveArchiveParent, parseHandoffParties } from './recipientV2.artifactFirst.closure.js';
+import { decodeUtf8, finding } from './recipientV2.artifactFirst.shared.js';
+
+export function qualifyPhase1RouteBindings({ routes = [], workspaceQualifications = new Map(), findings = [], recoveryParentCandidates = [], selectedRouteIdFromIngress = '', cacheQualifications = [], rolePointers = [], endpointPointers = [], participantPointers = [], cachePayloads = [], endpointRoleQualifications = [], participantRoleQualifications = [], boundRolePaths = new Set(), routeQualifications = [] } = {}) {
+  for (const route of routes) {
+    const routeWorkspaceId = String(route.parsed.workspaceId || '');
+    const workspaceQualification = workspaceQualifications.get(routeWorkspaceId) || null;
+    if (!workspaceQualification && routeWorkspaceId) findings.push(finding('error', 'portable.handoff-v2-phase1.workspace.route-unresolved', 'Every visible route Workspace must resolve one qualified artifact-first Workspace payload/relation pair.', { workspaceId: routeWorkspaceId, pointerPath: route.path }));
+    const payload = workspaceQualification?.payload || null;
+    const relation = workspaceQualification?.relation || null;
+    const archive = workspaceQualification?.archive || null;
+    const archiveFile = workspaceQualification?.archiveFile || null;
+    const workspaceTargetQualification = workspaceQualification?.workspaceTargetQualification || null;
+    let routeEntry = null;
+    let routeConformance = null;
+    let routeParties = Object.freeze({ from: '', to: '' });
+    let requiredClosure = Object.freeze({ state: 'blocked', requiredCount: 0, qualifiedCount: 0, requirements: Object.freeze([]), boundary: 'Artifact-first Required Context qualification has not run.' });
+    const semanticRouteId = String(route.parsed.routeId || `handoff-route:${routeWorkspaceId}:${String(route.parsed.handoffWorkspacePath || '')}`);
+    const routeEndpointRoles = [];
+    const routeParticipantRoles = [];
+
+    if (route && payload) {
+      if (route.parsed.workspaceId !== payload.parsed.workspaceId || route.parsed.workspacePayload !== payload.path) findings.push(finding('error', 'portable.handoff-v2-phase1.route.workspace-mismatch', 'Route Pointer must visibly bind the same Workspace identity and External Payload artifact.', { routeId: semanticRouteId }));
+      if (!route.parsed.handoffWorkspacePath) findings.push(finding('error', 'portable.handoff-v2-phase1.route.path-missing', 'Route Pointer must visibly declare the Handoff Workspace Path.', { routeId: semanticRouteId }));
+      if (!route.parsed.routeId || route.parsed.routeId !== semanticRouteId) findings.push(finding('error', 'portable.handoff-v2-phase1.route.id-missing', 'Route Pointer must visibly bind one exact route identity.', { routeId: semanticRouteId }));
+    }
+    if (archive?.state === 'qualified' && route) {
+      const routeEntries = archive.entries.filter((entry) => String(entry.path || '') === String(route.parsed.handoffWorkspacePath || ''));
+      if (routeEntries.length !== 1) findings.push(finding('error', 'portable.handoff-v2-phase1.route.unresolved', 'Route Pointer Handoff Workspace Path must resolve exactly one exact artifact inside its Workspace payload.', { routeId: semanticRouteId, path: route.parsed.handoffWorkspacePath || '', count: routeEntries.length }));
+      else {
+        routeEntry = routeEntries[0];
+        const routeMarkdown = decodeUtf8(routeEntry.data);
+        routeConformance = qualifySelectedHandoffArtifact({ markdown: routeMarkdown, resolveParent: ({ parent, targetEntry }) => resolveArchiveParent(route.parsed.handoffWorkspacePath, archive.entries, parent, targetEntry, recoveryParentCandidates) });
+        if (routeConformance.status !== 'qualified') findings.push(...(routeConformance.findings || []).map((item) => finding(item.severity || 'error', item.code || 'portable.handoff-v2-phase1.route.unqualified', item.message || 'Exact Handoff route did not qualify.', { routeId: semanticRouteId })));
+        routeParties = parseHandoffParties(routeMarkdown);
+        if (!routeParties.from || !routeParties.to) findings.push(finding('error', 'portable.handoff-v2-phase1.route.parties-unresolved', 'Exact Handoff bytes must provide From and To parties; route Pointer does not duplicate them.', { routeId: semanticRouteId }));
+        requiredClosure = qualifyPhase1RequiredContextClosure({
+          markdown: routeMarkdown,
+          routePath: route.parsed.handoffWorkspacePath,
+          workspaceId: payload?.parsed?.workspaceId || routeWorkspaceId,
+          archivePath: payload?.parsed?.location || '',
+          entries: archive.entries,
+          workspaceArchives: [...workspaceQualifications.values()].filter((item) => item?.archive?.state === 'qualified').map((item) => Object.freeze({ workspaceId: String(item.workspaceId || item.payload?.parsed?.workspaceId || ''), archivePath: String(item.payload?.parsed?.location || ''), entries: Object.freeze([...(item.archive?.entries || [])]) })),
+          caches: semanticRouteId === selectedRouteIdFromIngress ? cacheQualifications : []
+        });
+        findings.push(...(requiredClosure.findings || []).map((item) => Object.freeze({ ...item, routeId: semanticRouteId })));
+      }
+    }
+
+    if (route && payload && archive?.state === 'qualified') {
+      const expectedRolePaths = route.parsed.destinations.filter((target) => String(target || '') !== String(payload.path || ''));
+      for (const expectedPath of expectedRolePaths) {
+        const matches = rolePointers.filter((item) => String(item.path || '') === String(expectedPath || ''));
+        if (matches.length !== 1) {
+          findings.push(finding('error', 'portable.handoff-v2-phase1.role.pointer-missing', 'Route Pointer must resolve every declared Role Pointer exactly once.', { routeId: semanticRouteId, path: String(expectedPath || ''), count: matches.length }));
+          if (!endpointPointers.length && !participantPointers.length) findings.push(finding('error', 'portable.handoff-v2-phase1.participant-role.pointer-missing', 'Route Pointer has an unresolved Role destination and no surviving explicit Role Pointer can classify it.', { routeId: semanticRouteId, path: String(expectedPath || ''), count: matches.length }));
+          continue;
+        }
+        const pointer = matches[0];
+        boundRolePaths.add(String(pointer.path || ''));
+        const kind = pointer.parsed.role === 'endpoint-role' ? 'endpoint' : 'participant';
+        const result = qualifyPhase1RolePointer(pointer, { kind, routeWorkspaceId, routeId: semanticRouteId, workspaceQualifications, cachePayloads, cacheQualifications }, findings);
+        if (kind === 'endpoint') { routeEndpointRoles.push(result); endpointRoleQualifications.push(result); }
+        else { routeParticipantRoles.push(result); participantRoleQualifications.push(result); }
+      }
+    } else if (route?.parsed?.destinations?.some((target) => rolePointers.some((pointer) => String(pointer.path || '') === String(target || '')))) {
+      findings.push(finding('error', 'portable.handoff-v2-phase1.role.route-unresolved', 'Role Pointers cannot qualify until their route and Workspace payload qualify.', { routeId: semanticRouteId }));
+    }
+
+    const routeReasons = [];
+    if (routeConformance?.status !== 'qualified') routeReasons.push('handoff-conformance-unqualified');
+    if (requiredClosure.state !== 'qualified') routeReasons.push('required-context-closure-unqualified');
+    if (routeEndpointRoles.some((item) => item.state !== 'qualified')) routeReasons.push('endpoint-role-grounding-unqualified');
+    if (routeParticipantRoles.some((item) => item.state !== 'qualified')) routeReasons.push('participant-role-grounding-unqualified');
+    routeQualifications.push(Object.freeze({
+      route,
+      routeId: semanticRouteId,
+      workspaceId: routeWorkspaceId,
+      workspaceQualification,
+      payload,
+      relation,
+      archive,
+      archiveFile,
+      workspaceTargetQualification,
+      routeEntry,
+      routeConformance,
+      routeParties,
+      requiredClosure,
+      endpointRoles: Object.freeze(routeEndpointRoles),
+      participantRoles: Object.freeze(routeParticipantRoles),
+      reasons: Object.freeze(routeReasons)
+    }));
+  }
+
+}
+
+export function validatePhase1IngressBindings({ workspaceQualificationList = [], ingressPointer = null, routes = [], bootstrapPayload = null, cachePayloads = [], rolePointers = [], boundRolePaths = new Set(), findings = [] } = {}) {
+  for (const item of workspaceQualificationList) {
+    if (ingressPointer && !ingressPointer.parsed.destinations.includes(item.payload.path)) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.payload-missing', 'Ingress Pointer must navigate to every carried Workspace External Payload artifact.', { workspaceId: item.workspaceId, path: item.payload.path }));
+    if (ingressPointer && !ingressPointer.parsed.destinations.includes(item.relation.path)) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.relation-missing', 'Ingress Pointer must navigate to every carried Workspace material-representation Relation.', { workspaceId: item.workspaceId, path: item.relation.path }));
+  }
+  for (const route of routes) if (ingressPointer && !ingressPointer.parsed.destinations.includes(route.path)) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.route-missing', 'Ingress Pointer must navigate to every Handoff route Pointer.', { path: route.path }));
+  if (ingressPointer && bootstrapPayload && !ingressPointer.parsed.destinations.includes(bootstrapPayload.path)) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.bootstrap-missing', 'Ingress Pointer must navigate to the visible portable Tooling bootstrap External Payload artifact when one is carried.'));
+  if (ingressPointer && !bootstrapPayload && ingressPointer.parsed.destinations.some((target) => /bootstrap/i.test(String(target || '')))) findings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.artifact-unresolved', 'Ingress Pointer declares a portable Tooling bootstrap destination but no owning External Payload artifact is present.'));
+  for (const cachePayload of cachePayloads) if (ingressPointer && !ingressPointer.parsed.destinations.includes(cachePayload.path)) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.cache-missing', 'Ingress Pointer must navigate to every selected-route cache External Payload artifact.', { path: cachePayload.path }));
+  for (const pointer of rolePointers) {
+    if (!boundRolePaths.has(String(pointer.path || ''))) findings.push(finding('error', 'portable.handoff-v2-phase1.role.unbound', 'Role Pointer must be explicitly bound by one visible route Pointer.', { path: String(pointer.path || '') }));
+    if (ingressPointer && !ingressPointer.parsed.destinations.includes(pointer.path)) findings.push(finding('error', pointer.parsed.role === 'endpoint-role' ? 'portable.handoff-v2-phase1.ingress.endpoint-role-missing' : 'portable.handoff-v2-phase1.ingress.participant-role-missing', 'Ingress Pointer must navigate to every visible Role Pointer.', { path: pointer.path }));
+  }
+
+}

package/src/tooling/portable/handoff/recipientV2.artifactFirst.shared.js

@@ -0,0 +1,87 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileByteView, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export const RECIPIENT_V2_READ_PATH = '001-1-READ-BEFORE-PROCEEDING.trace.md';
+const RECIPIENT_V2_BASE_FORMAT_ID = 'tiinex-recipient-facing-handoff-v2-flat';
+export const RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID = `${RECIPIENT_V2_BASE_FORMAT_ID}-artifact-first-phase1`;
+export const RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_SCHEMA_ID = 'tiinex.portable.handoff-recipient-v2-artifact-first-phase1.v1';
+export const RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_FORMAT_ID = `${RECIPIENT_V2_BASE_FORMAT_ID}-artifact-first-clean-phase2`;
+export const RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_SCHEMA_ID = 'tiinex.portable.handoff-recipient-v2-artifact-first-clean-phase2.v1';
+export const PHASE2_CLEAN_PROFILE = 'artifact-first-clean-carrier-phase2';
+export const PHASE2_COMPATIBILITY_TRANSPORT = 'omitted-derived-non-authoritative';
+export const PHASE1_BOOTSTRAP_ROLE = 'portable Tooling bootstrap runtime for recipient orientation and verification';
+export const PHASE1_CACHE_ROLE = 'workspace-scoped Handoff dependency cache';
+
+export function normalizeRoutePath(value = '') { return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, ''); }
+
+export function normalizePhase1Token(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, ''); }
+
+export function cacheMaterialBelongsToRoute(material = {}, workspaceId = '', routePath = '') {
+  return String(material.routeWorkspaceId || '') === String(workspaceId || '') && normalizeRoutePath(material.routePath || '') === normalizeRoutePath(routePath || '');
+}
+
+export function selectOne(items = [], selector = '', label = 'item', findings = [], selectorFn = (item) => String(item.workspaceId || '')) { const candidates = selector ? items.filter((item) => selectorFn(item) === String(selector)) : items; if (candidates.length !== 1) { findings.push(finding('error', `portable.handoff-v2-phase1.${label}.selection`, `Phase 1 specimen requires exactly one selected ${label}.`, { selector: String(selector || ''), count: candidates.length })); return null; } return candidates[0]; }
+
+export function oneFile(files = [], path = '') { const matches = files.filter((file) => String(file.path || '') === String(path || '')); return matches.length === 1 ? matches[0] : null; }
+
+export function repathFinalizedFile(file = {}, path = '', overrides = {}) { return finalizeFile({ ...overrides, path, requestedPath: path, data: packageFileByteView(file) }); }
+
+export function currentSchemaId(markdown = '') { return String(String(markdown || '').match(/Current Schema:\s*(?:\[)?(tiinex\.[a-z0-9._-]+)(?:\])?/i)?.[1] || '').toLowerCase(); }
+
+export function sectionText(markdown = '', heading = '') { const re = new RegExp(`^##\\s+${escapeRe(heading)}\\s*$`, 'mi'); const match = re.exec(String(markdown || '')); if (!match) return ''; const rest = String(markdown || '').slice(match.index + match[0].length); const next = /^##\s+/m.exec(rest); return (next ? rest.slice(0, next.index) : rest).trim(); }
+
+export function fieldValue(section = '', name = '') { const m = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRe(name)}:\\s*(.+?)\\s*$`, 'mi')); return String(m?.[1] || '').trim(); }
+
+export function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
+
+export function escapeRe(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+
+export function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+
+export function phase1RouteToken(route = {}) {
+  const workspaceId = String(route.workspaceId || 'workspace');
+  const routePath = String(route.workspaceRelativePath || 'route');
+  const routeId = String(route.id || '');
+  const human = safeToken(`${workspaceId}-${routePath}`).slice(0, 42) || 'route';
+  return `${human}-${sha256Hex(utf8Bytes(`${workspaceId}\0${routePath}\0${routeId}`)).slice(0, 12)}`;
+}
+
+export function phase1RoutePointerPath(route = {}, index = 0, count = 1, selectedRouteId = '') {
+  if (String(route.id || '') === String(selectedRouteId || '') || count <= 1) return '001-4-handoff-pointer.trace.md';
+  return `001-4-${index + 1}-${phase1RouteToken(route)}-handoff-pointer.trace.md`;
+}
+
+export function phase1RolePathPrefix(route = {}, index = 0, count = 1, selectedRouteId = '') {
+  if (String(route.id || '') === String(selectedRouteId || '') || count <= 1) return '001-6';
+  return `001-6-${index + 1}-${phase1RouteToken(route)}`;
+}
+
+export function artifactFirstCarrierFilename(workspaceId = '', dimension = '', from = '', to = '') {
+  const workspace = safeToken(workspaceId);
+  const dimensionToken = String(dimension || '').trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const fromToken = String(from || '').trim().toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const toToken = String(to || '').trim().toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return workspace && dimensionToken && fromToken && toToken ? `${workspace}-${dimensionToken}-${fromToken}-to-${toToken}.handoff-package.zip` : '';
+}
+
+export function safeToken(value = '') { return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace'; }
+
+export function stableJson(value) { return JSON.stringify(sortJson(value)); }
+
+export function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }
+
+export function blocked(reason, findings = []) { return deepFreeze({ schema: RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_SCHEMA_ID, status: 'blocked', files: Object.freeze([]), topology: deepFreeze({ root: null, read: null, workspaces: [], caches: [], participantRoles: [], routes: [], bootstrap: null }), findings: Object.freeze([finding('error', `portable.handoff-v2-phase1.${reason}`, 'Artifact-first Phase 1 specimen could not be built.'), ...findings]) }); }
+
+export function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+
+export function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Map) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }
+
+export function sortedQualifiedCarrierRoutes(routes = [], selectedRouteId = '') {
+  return [...routes].filter((item) => String(item.state || '') === 'qualified').sort((a, b) => {
+    const aid = String(a.id || '');
+    const bid = String(b.id || '');
+    if (aid === selectedRouteId && bid !== selectedRouteId) return -1;
+    if (bid === selectedRouteId && aid !== selectedRouteId) return 1;
+    return `${String(a.workspaceId || '')}:${normalizeRoutePath(a.workspaceRelativePath || '')}`.localeCompare(`${String(b.workspaceId || '')}:${normalizeRoutePath(b.workspaceRelativePath || '')}`);
+  });
+}

package/src/tooling/portable/handoff/recipientV2.artifactFirst.workspaces.js

@@ -0,0 +1,160 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileByteView, packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+import { renderRecipientV2ExternalPayload, renderRecipientV2Relation } from './recipientV2.artifacts.js';
+
+export const PHASE1_COMPLETE_WORKSPACE_ROLE = 'complete Workspace archive representation payload';
+export const PHASE1_BOUNDED_WORKSPACE_ROLE = 'bounded Workspace archive representation payload';
+
+export function buildPhase1WorkspaceCarriers(input = {}) {
+  const sourceInspection = input.sourceInspection || {};
+  const sourceBundle = input.sourceBundle || {};
+  const selectedWorkspaceId = String(input.selectedWorkspaceId || '');
+  const findings = [];
+  const ordered = [...(sourceInspection.workspaces || [])].sort((a, b) => {
+    const aid = String(a.workspaceId || '');
+    const bid = String(b.workspaceId || '');
+    if (aid === selectedWorkspaceId && bid !== selectedWorkspaceId) return -1;
+    if (bid === selectedWorkspaceId && aid !== selectedWorkspaceId) return 1;
+    return aid.localeCompare(bid);
+  });
+  const carriers = [];
+  const seen = new Set();
+  for (const [index, workspace] of ordered.entries()) {
+    const workspaceId = String(workspace.workspaceId || '');
+    if (!workspaceId || seen.has(workspaceId)) {
+      findings.push(finding('error', 'portable.handoff-v2-phase1.workspace.identity-ambiguous', 'Artifact-first full-source carriage requires one unique visible Workspace identity per carried Workspace.', { workspaceId }));
+      continue;
+    }
+    seen.add(workspaceId);
+    const sourceArchive = oneFile(sourceBundle.files || [], workspace.workspaceArchivePath);
+    if (!sourceArchive) {
+      findings.push(finding('error', 'portable.handoff-v2-phase1.archive.unresolved', 'Carried Workspace archive is unavailable in the qualified source carrier.', { workspaceId, path: workspace.workspaceArchivePath }));
+      continue;
+    }
+    const selected = workspaceId === selectedWorkspaceId;
+    const token = safeToken(workspaceId);
+    const ordinal = index + 1;
+    const archivePath = selected ? '001-2-workspace.zip' : `001-2-${ordinal}-${token}-workspace.zip`;
+    const payloadArtifactPath = selected ? '001-2-workspace-payload.trace.md' : `001-2-${ordinal}-${token}-workspace-payload.trace.md`;
+    const relationArtifactPath = selected ? '001-3-workspace-representation-relation.trace.md' : `001-3-${ordinal}-${token}-workspace-representation-relation.trace.md`;
+    const coverage = workspace.coverage === 'bounded' ? 'bounded' : 'complete';
+    const payloadRole = coverage === 'bounded' ? PHASE1_BOUNDED_WORKSPACE_ROLE : PHASE1_COMPLETE_WORKSPACE_ROLE;
+    const scope = coverage === 'bounded' ? 'bounded recipient-relative workspace materialization' : 'complete recipient-relative workspace materialization';
+    const archiveFile = finalizeFile({
+      path: archivePath,
+      requestedPath: archivePath,
+      kind: 'handoff-workspace-archive',
+      logicalKind: coverage === 'bounded' ? 'recipient-v2-phase1-bounded-workspace-archive' : 'recipient-v2-phase1-complete-workspace-archive',
+      mediaType: 'application/zip',
+      data: packageFileByteView(sourceArchive),
+      boundary: 'Exact Workspace archive bytes owned by the visible External Payload artifact; package placement is not semantic provider authority.'
+    });
+    const payloadArtifact = finalizeFile({
+      path: payloadArtifactPath,
+      kind: 'tiinex-external-payload-artifact',
+      logicalKind: 'recipient-v2-phase1-workspace-payload',
+      mediaType: 'text/markdown',
+      content: renderRecipientV2ExternalPayload({
+        artifactFirst: true,
+        createdAt: input.createdAt,
+        workspaceId,
+        title: `Workspace Payload — ${workspaceId}`,
+        summary: `Artifact-first Phase 1 exact ${coverage} Workspace archive payload.`,
+        label: `${workspaceId} ${coverage} Workspace archive`,
+        kind: 'zip export',
+        role: payloadRole,
+        location: archivePath,
+        bytes: archiveFile.bytes,
+        sha256: archiveFile.sha256
+      })
+    });
+    const relationArtifact = finalizeFile({
+      path: relationArtifactPath,
+      kind: 'tiinex-relation-artifact',
+      logicalKind: 'recipient-v2-phase1-workspace-representation-relation',
+      mediaType: 'text/markdown',
+      content: renderRecipientV2Relation({
+        artifactFirst: true,
+        createdAt: input.createdAt,
+        title: `Workspace Material Representation — ${workspaceId}`,
+        summary: 'Typed non-Parent material-representation relation from the External Payload artifact to the represented Workspace artifact.',
+        relationType: 'material representation',
+        direction: 'payload artifact -> represented artifact',
+        scope,
+        sourceLabel: `${workspaceId} Workspace payload artifact`,
+        source: payloadArtifactPath,
+        targetLabel: `${workspaceId} represented Workspace artifact`,
+        target: String(workspace.sourceWorkspaceTargetInnerPath || ''),
+        targetWorkspaceId: workspaceId,
+        targetWorkspaceInnerPath: String(workspace.sourceWorkspaceTargetInnerPath || '')
+      })
+    });
+    carriers.push(Object.freeze({ workspace, workspaceId, selected, coverage, archivePath, payloadArtifactPath, relationArtifactPath, archiveFile, payloadArtifact, relationArtifact }));
+  }
+  if (!carriers.some((item) => item.selected)) findings.push(finding('error', 'portable.handoff-v2-phase1.workspace.selection', 'Selected route Workspace is not present in the carried full-source Workspace set.', { workspaceId: selectedWorkspaceId }));
+  return Object.freeze({ state: findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified', carriers: Object.freeze(carriers), findings: Object.freeze(findings) });
+}
+
+export function qualifyPhase1WorkspaceCarriers(input = {}) {
+  const payloads = input.workspacePayloads || [];
+  const relations = input.relations || [];
+  const semanticFiles = input.semanticFiles || [];
+  const recoveryParentCandidates = input.recoveryParentCandidates || [];
+  const findings = input.findings || [];
+  const records = [];
+  const payloadByWorkspace = uniqueByWorkspace(payloads, (item) => item.parsed?.workspaceId, 'payload', findings);
+  const relationByWorkspace = uniqueByWorkspace(relations, (item) => item.parsed?.targetWorkspaceId, 'relation', findings);
+  const ids = new Set([...payloadByWorkspace.keys(), ...relationByWorkspace.keys()]);
+  for (const workspaceId of [...ids].sort()) {
+    const payload = payloadByWorkspace.get(workspaceId) || null;
+    const relation = relationByWorkspace.get(workspaceId) || null;
+    if (!payload || !relation) {
+      findings.push(finding('error', 'portable.handoff-v2-phase1.workspace.surface-incomplete', 'Every carried artifact-first Workspace requires one External Payload and one material-representation Relation.', { workspaceId, payload: Boolean(payload), relation: Boolean(relation) }));
+      continue;
+    }
+    const expectedScope = payload.parsed.payloadRole === PHASE1_BOUNDED_WORKSPACE_ROLE ? 'bounded recipient-relative workspace materialization' : 'complete recipient-relative workspace materialization';
+    if (relation.parsed.relationType !== 'material representation' || relation.parsed.direction !== 'payload artifact -> represented artifact' || relation.parsed.scope !== expectedScope) findings.push(finding('error', 'portable.handoff-v2-phase1.relation.semantic-contract-mismatch', 'Workspace representation Relation does not match the accepted artifact-first material-representation predicate/direction/scope.', { workspaceId }));
+    if (relation.parsed.source !== payload.path) findings.push(finding('error', 'portable.handoff-v2-phase1.relation.payload-mismatch', 'Material-representation Relation Source must be the explicit Workspace External Payload artifact.', { workspaceId }));
+    if (!relation.parsed.targetWorkspaceId || relation.parsed.targetWorkspaceId !== workspaceId) findings.push(finding('error', 'portable.handoff-v2-phase1.relation.workspace-id-mismatch', 'Relation and External Payload must visibly agree on represented Workspace identity.', { workspaceId }));
+    if (!relation.parsed.targetWorkspaceInnerPath || relation.parsed.target !== relation.parsed.targetWorkspaceInnerPath) findings.push(finding('error', 'portable.handoff-v2-phase1.relation.workspace-inner-path-missing', 'Material-representation Relation must visibly identify the represented Workspace inner path.', { workspaceId }));
+    const archiveFiles = semanticFiles.filter((file) => String(file.path || '') === String(payload.parsed.location || ''));
+    if (archiveFiles.length !== 1) {
+      findings.push(finding('error', 'portable.handoff-v2-phase1.payload.location-unresolved', 'Workspace External Payload Location must resolve exactly one exact payload file.', { workspaceId, path: payload.parsed.location || '', count: archiveFiles.length }));
+      continue;
+    }
+    const archiveFile = archiveFiles[0];
+    const bytes = packageFileBytes(archiveFile);
+    if (payload.parsed.bytes !== bytes.byteLength || payload.parsed.integrityMethod !== 'sha256' || payload.parsed.integrityValue !== sha256Hex(bytes)) findings.push(finding('error', 'portable.handoff-v2-phase1.payload.identity-mismatch', 'Visible Workspace External Payload byte identity diverges from exact payload bytes.', { workspaceId }));
+    const archive = inspectStoredWorkspaceArchive(bytes, { ownedBytes: true });
+    findings.push(...(archive.findings || []));
+    let workspaceTargetQualification = null;
+    if (archive.state === 'qualified') {
+      const targetEntries = archive.entries.filter((entry) => String(entry.path || '') === String(relation.parsed.targetWorkspaceInnerPath || ''));
+      if (targetEntries.length !== 1) findings.push(finding('error', 'portable.handoff-v2-phase1.workspace-target.unresolved', 'Relation target Workspace inner path must resolve exactly one Workspace artifact inside the payload.', { workspaceId, path: relation.parsed.targetWorkspaceInnerPath || '', count: targetEntries.length }));
+      else {
+        workspaceTargetQualification = qualifyHandoffWorkspaceTarget({ targetPath: targetEntries[0].path, targetData: targetEntries[0].data, entries: archive.entries, parentCandidates: recoveryParentCandidates });
+        if (workspaceTargetQualification.state !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-phase1.workspace-target.unqualified', 'Relation-selected Workspace artifact inside the payload did not independently qualify.', { workspaceId, reasons: workspaceTargetQualification.reasons || [] }));
+      }
+    }
+    records.push(Object.freeze({ workspaceId, payload, relation, archiveFile, archive, workspaceTargetQualification }));
+  }
+  return Object.freeze(records);
+}
+
+function uniqueByWorkspace(items, idFn, label, findings) {
+  const map = new Map();
+  for (const item of items) {
+    const workspaceId = String(idFn(item) || '');
+    if (!workspaceId || map.has(workspaceId)) {
+      findings.push(finding('error', `portable.handoff-v2-phase1.${label}.workspace-ambiguous`, `Artifact-first Workspace ${label} must visibly bind one unique Workspace id.`, { workspaceId }));
+      continue;
+    }
+    map.set(workspaceId, item);
+  }
+  return map;
+}
+function oneFile(files = [], path = '') { const matches = files.filter((file) => String(file.path || '') === String(path || '')); return matches.length === 1 ? matches[0] : null; }
+function safeToken(value = '') { return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace'; }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }

package/src/tooling/portable/handoff/recipientV2.artifactFirstPhase1.js

@@ -0,0 +1,44 @@
+import { buildRecipientV2ArtifactFirstPhase1Specimen } from './recipientV2.artifactFirst.build.js';
+import { selectPhase1SourceRoute } from './recipientV2.artifactFirst.materials.js';
+import { blocked, deepFreeze } from './recipientV2.artifactFirst.shared.js';
+
+export { RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_SCHEMA_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_FORMAT_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_SCHEMA_ID } from './recipientV2.artifactFirst.shared.js';
+export { buildRecipientV2ArtifactFirstPhase1Specimen } from './recipientV2.artifactFirst.build.js';
+export { inspectRecipientV2ArtifactFirstPhase1Specimen } from './recipientV2.artifactFirst.inspect.js';
+export { isRecipientV2ArtifactFirstPhase1Surface, inspectRecipientFacingV2ArtifactFirstPhase1 } from './recipientV2.artifactFirst.projection.js';
+export { deriveRecipientV2ArtifactFirstPhase1Facts } from './recipientV2.artifactFirst.materials.js';
+export { qualifyRecipientV2ArtifactFirstPhase1RequiredContextClosure } from './recipientV2.artifactFirst.closure.js';
+
+export function buildRecipientFacingV2ArtifactFirstPhase1(input = {}) {
+  return buildRecipientFacingV2ArtifactFirst(input, false);
+}
+
+export function buildRecipientFacingV2ArtifactFirstPhase2Clean(input = {}) {
+  return buildRecipientFacingV2ArtifactFirst(input, true);
+}
+
+function buildRecipientFacingV2ArtifactFirst(input = {}, cleanCarrierPhase2 = false) {
+  const sourceSurface = input.sourceSurface || null;
+  const selectionFindings = [];
+  const routeSelection = selectPhase1SourceRoute(input.carrierProjection || sourceSurface?.carrierProjection || {}, input.routeSelector || input.routeId || '', selectionFindings);
+  if (routeSelection.state !== 'qualified') return blocked('route-selection-blocked', selectionFindings);
+  if (!sourceSurface || sourceSurface.status !== 'ready') return blocked('source-surface-unready', sourceSurface?.findings || []);
+  const specimen = buildRecipientV2ArtifactFirstPhase1Specimen({
+    bundle: { files: sourceSurface.files || [] },
+    createdAt: input.createdAt,
+    workspaceId: routeSelection.route.workspaceId || input.workspaceId || '',
+    routePath: routeSelection.route.workspaceRelativePath || '',
+    routeSelection,
+    bootstrap: sourceSurface.topology?.bootstrap || null,
+    cleanCarrierPhase2
+  });
+  if (specimen.status !== 'ready') return specimen;
+  return deepFreeze({
+    status: 'ready',
+    files: specimen.files,
+    topology: specimen.topology,
+    inspection: specimen.inspection,
+    findings: specimen.inspection.findings,
+    boundary: specimen.boundary
+  });
+}