@tiinex/core 0.1.1

package/src/tooling/portable/handoff/recipientV2.packageV1.contract.js

@@ -0,0 +1,101 @@
+import { sealC14nV2Self } from '../../../integrity/integrity.c14nV2.js';
+import { C14N_V2_VALIDATOR_TARGET } from '../../../integrity/integrity.methodReference.js';
+import { finding } from './recipientV2.topology.materials.js';
+import { RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET } from './recipientV2.packageV1.constants.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { RECIPIENT_V2_ROOT_SCHEMA_TARGET } from './recipientV2.artifacts.js';
+import { field, markdownTarget, normalizeCreatedAt, sectionText, unquote, validCarrierDimension } from './recipientV2.packageV1.shared.js';
+import { normalizeHandoffCarrierProfile, normalizeWorkspaceIds } from './carrierProfile.js';
+
+export const HANDOFF_PACKAGE_ROLE = 'recipient-facing-handoff-carrier';
+export const WORKSPACE_PACKAGE_ROLE = 'recipient-facing-workspace-carrier';
+export const WORKSPACE_CARRIER_CANONICAL_BLOCKER = 'portable.handoff-package-v1.workspace-carrier.canonical-follow-through-required';
+
+function routeProfileForRole(role = HANDOFF_PACKAGE_ROLE) {
+  return role === WORKSPACE_PACKAGE_ROLE
+    ? Object.freeze({ routePlacementRule: 'none', continueFromRule: 'none', preHandoffClosureRule: 'none' })
+    : Object.freeze({ routePlacementRule: 'authoritative-workspace-descended', continueFromRule: 'exact-package-local-handoff-pointer', preHandoffClosureRule: 'selected-pointer-carrier-ancestors' });
+}
+
+export function renderHandoffPackageV1(input = {}) {
+  const createdAt = normalizeCreatedAt(input.createdAt || '');
+  const lineage = input.carrierLineage || {};
+  const carrierProfile = normalizeHandoffCarrierProfile(input.carrierProfile || null);
+  const packageRole = [HANDOFF_PACKAGE_ROLE, WORKSPACE_PACKAGE_ROLE].includes(String(input.packageRole || '')) ? String(input.packageRole) : HANDOFF_PACKAGE_ROLE;
+  const routeProfile = routeProfileForRole(packageRole);
+  const workspaces = input.workspaces || [];
+  const workspaceBlocks = workspaces.map((workspace) => `- ${workspace.workspaceId}\n  - Workspace Id: ${workspace.workspaceId}\n  - Workspace Artifact: [${workspace.workspaceId} Workspace](${workspace.workspacePath})\n  - Snapshot Path: [${workspace.workspaceId} Snapshot](${workspace.archivePath})\n  - Workspace Artifact Inner Path: \`${workspace.sourceWorkspaceTargetInnerPath}\`\n  - Snapshot Kind: exact-workspace-byte-tree-archive\n  - Coverage: complete\n  - Binding State: verified\n  - Integrity Method: sha256\n  - Integrity Value: ${workspace.archiveSha256}\n  - Byte Size: ${workspace.archiveBytes || ''}`.replace(/\n  - Byte Size: $/, '')).join('\n');
+  const unsigned = `# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](${RECIPIENT_V2_ROOT_SCHEMA_TARGET})\n- Current\n  - Current Schema: [tiinex.handoff.package.v1](${RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET})\n  - Created At: ${createdAt}\n  - Summary: Recipient-facing self-contained Handoff carrier identity, discovery, exact complete Workspace snapshot bindings, and fail-closed qualification boundary.\n\n---\n\n# Handoff Package\n\n## Package Identity\n\n- Package Role: ${packageRole}\n- Carrier Kind: self-contained\n\n## Bootstrap Exposure\n\n- Start Artifact: [Start](${input.startPath || RECIPIENT_V2_READ_PATH})\n${input.bootstrapPath ? `- Tooling Bootstrap Descriptor: [Bootstrap](${input.bootstrapPath})\n` : '- Tooling Bootstrap Descriptor: [Bootstrap](001-2-bootstrap.trace.md)\n'}- Bootstrap Rule: start-then-qualified-bootstrap\n\n## Workspace Snapshot Bindings\n\n${workspaceBlocks || '- none'}\n\n## Route Discovery\n\n- Route Placement Rule: ${routeProfile.routePlacementRule}\n- Continue-From Rule: ${routeProfile.continueFromRule}\n- Pre-Handoff Closure Rule: ${routeProfile.preHandoffClosureRule}\n\n## Carrier Continuity\n\n- Carrier Dimension: ${String(lineage.dimension || '001')}\n${lineage.parentDimension ? `- Parent Carrier Dimension: ${String(lineage.parentDimension)}\n` : ''}- Carrier Checkpoint: ${String(lineage.checkpointKind || 'progression')}\n${lineage.majorReason ? `- Major Reason: ${String(lineage.majorReason)}\n` : ''}- Carrier Profile Id: ${carrierProfile.id || 'none'}\n- Required Major Workspace Ids: ${carrierProfile.requiredMajorWorkspaceIds.length ? carrierProfile.requiredMajorWorkspaceIds.join(', ') : 'none'}\n\n## Qualification Boundary\n\n- Receiver Qualification: reverify-carried-authority-and-bytes\n- Failure Policy: fail-closed\n- Derived Inventory Authority: none\n\n## Interpretation Limits\n\n- Does Not Mean: package placement, discovery ancestry, or byte integrity creates Handoff, Workspace, Role, participation, acceptance, provenance, or Parent authority\n- Must Not Be Used To Claim: carrier convenience metadata overrides the authoritative contained artifacts or exact qualified source bytes\n- Generic Payload Boundary: bootstrap/cache payloads retain explicit External Payload ownership when required; complete Workspace snapshot binding is package-local only\n- Generic Representation Boundary: bounded, partial, independently selectable, multi-representation, or external-lifecycle Workspace representations require the generic Workspace Representation contract\n- Carrier Profile Boundary: required Workspace identifiers come only from the explicit carrier profile; literal project Workspace names have no generic semantic meaning\n\n---\n\n# Continuity Integrity\n\n- [sha256-base64url-c14n-v2](${C14N_V2_VALIDATOR_TARGET})\n  - Towards: self\n  - Value: pending\n`;
+  const sealed = sealC14nV2Self(unsigned);
+  if (sealed.state !== 'sealed') throw new Error(`portable.handoff-package-v1.integrity.seal-failed:${sealed.reason || sealed.state}`);
+  return `${sealed.markdown}\n`;
+}
+
+export function parseHandoffPackageV1(markdown = '') {
+  const body = String(markdown || '');
+  const workspaceHeading = '## Workspace Snapshot Bindings';
+  const workspaceStart = body.indexOf(workspaceHeading);
+  const workspaceEnd = workspaceStart >= 0 ? body.indexOf('## Route Discovery', workspaceStart + workspaceHeading.length) : -1;
+  const workspacesSection = workspaceStart >= 0 ? body.slice(workspaceStart + workspaceHeading.length, workspaceEnd >= 0 ? workspaceEnd : undefined).trim() : '';
+  const workspaces = parseWorkspaceBindings(workspacesSection);
+  return Object.freeze({
+    packageRole: field(sectionText(body, 'Package Identity'), 'Package Role'), carrierKind: field(sectionText(body, 'Package Identity'), 'Carrier Kind'),
+    startPath: markdownTarget(field(sectionText(body, 'Bootstrap Exposure'), 'Start Artifact')), bootstrapPath: markdownTarget(field(sectionText(body, 'Bootstrap Exposure'), 'Tooling Bootstrap Descriptor')), bootstrapRule: field(sectionText(body, 'Bootstrap Exposure'), 'Bootstrap Rule'),
+    workspaces: Object.freeze(workspaces), routePlacementRule: field(sectionText(body, 'Route Discovery'), 'Route Placement Rule'), continueFromRule: field(sectionText(body, 'Route Discovery'), 'Continue-From Rule'), preHandoffClosureRule: field(sectionText(body, 'Route Discovery'), 'Pre-Handoff Closure Rule'),
+    carrierDimension: field(sectionText(body, 'Carrier Continuity'), 'Carrier Dimension'), parentCarrierDimension: field(sectionText(body, 'Carrier Continuity'), 'Parent Carrier Dimension'), carrierCheckpoint: field(sectionText(body, 'Carrier Continuity'), 'Carrier Checkpoint'), majorReason: field(sectionText(body, 'Carrier Continuity'), 'Major Reason'), carrierProfileId: normalizeProfileId(field(sectionText(body, 'Carrier Continuity'), 'Carrier Profile Id')), requiredMajorWorkspaceIds: normalizeWorkspaceIds(field(sectionText(body, 'Carrier Continuity'), 'Required Major Workspace Ids')),
+    receiverQualification: field(sectionText(body, 'Qualification Boundary'), 'Receiver Qualification'), failurePolicy: field(sectionText(body, 'Qualification Boundary'), 'Failure Policy'), derivedInventoryAuthority: field(sectionText(body, 'Qualification Boundary'), 'Derived Inventory Authority')
+  });
+}
+
+export function validatePackageFields(value, findings) {
+  const packageRole = String(value?.packageRole || '');
+  const roleKnown = [HANDOFF_PACKAGE_ROLE, WORKSPACE_PACKAGE_ROLE].includes(packageRole);
+  if (!roleKnown) findings.push(finding('error', 'portable.handoff-package-v1.field.packageRole.invalid', 'Handoff package v1 Package Role is missing or invalid.', { field: 'packageRole', expected: `${HANDOFF_PACKAGE_ROLE}|${WORKSPACE_PACKAGE_ROLE}`, observed: packageRole }));
+  const routeProfile = routeProfileForRole(roleKnown ? packageRole : HANDOFF_PACKAGE_ROLE);
+  const exact = [
+    ['carrierKind', 'self-contained'], ['bootstrapRule', 'start-then-qualified-bootstrap'], ['routePlacementRule', routeProfile.routePlacementRule], ['continueFromRule', routeProfile.continueFromRule], ['preHandoffClosureRule', routeProfile.preHandoffClosureRule], ['receiverQualification', 'reverify-carried-authority-and-bytes'], ['failurePolicy', 'fail-closed'], ['derivedInventoryAuthority', 'none']
+  ];
+  for (const [key, expected] of exact) if (String(value?.[key] || '') !== expected) findings.push(finding('error', `portable.handoff-package-v1.field.${key}.invalid`, 'Handoff package v1 required closed-domain field is missing or invalid.', { field: key, expected, observed: String(value?.[key] || '') }));
+  if (!value?.startPath || !value?.bootstrapPath) findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-exposure-invalid', 'Start Artifact and Tooling Bootstrap Descriptor must be package-local links.'));
+  if (!Array.isArray(value?.workspaces) || !value.workspaces.length) findings.push(finding('error', 'portable.handoff-package-v1.workspace-bindings-missing', 'Handoff package v1 requires at least one complete Workspace snapshot binding.'));
+  if (!validCarrierDimension(value?.carrierDimension)) findings.push(finding('error', 'portable.handoff-package-v1.carrier-dimension-invalid', 'Carrier Dimension must be a canonical numeric hyphen path.', { value: value?.carrierDimension || '' }));
+  if (value?.parentCarrierDimension && !validCarrierDimension(value.parentCarrierDimension)) findings.push(finding('error', 'portable.handoff-package-v1.parent-carrier-dimension-invalid', 'Parent Carrier Dimension must be a canonical numeric hyphen path.', { value: value.parentCarrierDimension || '' }));
+  if (!['progression', 'major'].includes(String(value?.carrierCheckpoint || ''))) findings.push(finding('error', 'portable.handoff-package-v1.carrier-checkpoint-invalid', 'Carrier Checkpoint must be progression or major.'));
+  if (value?.carrierCheckpoint === 'major' && !String(value.majorReason || '').trim()) findings.push(finding('error', 'portable.handoff-package-v1.major-reason-missing', 'Major carrier requires one meaningful Major Reason.'));
+  if (value?.carrierCheckpoint === 'major') {
+    if ((value.requiredMajorWorkspaceIds || []).length && !String(value.carrierProfileId || '').trim()) findings.push(finding('error', 'portable.handoff-package-v1.major-carrier-profile-missing', 'Named Major Workspace requirements require one explicit carrier profile id.'));
+    const carried = new Set((value?.workspaces || []).map((item) => String(item.workspaceId || '').trim().toLowerCase()).filter(Boolean));
+    const missing = normalizeWorkspaceIds(value.requiredMajorWorkspaceIds || []).filter((workspaceId) => !carried.has(workspaceId));
+    if (missing.length) findings.push(finding('error', 'portable.handoff-package-v1.major-source-closure-incomplete', 'Major package-v1 carrier is missing one or more Workspace snapshot bindings required by its explicit carrier profile.', { carrierProfileId: String(value.carrierProfileId || ''), missingWorkspaceIds: missing }));
+  }
+}
+
+function parseWorkspaceBindings(text = '') {
+  const out = [];
+  const re = /^-\s+([^\n]+)\n((?:\s{2}-\s+[^\n]+\n?)*)/gm;
+  for (const match of String(text || '').matchAll(re)) {
+    const current = { label: String(match[1] || '').trim() };
+    for (const line of String(match[2] || '').split('\n')) {
+      const fieldMatch = line.match(/^\s{2}-\s+([^:]+):\s*(.*)$/);
+      if (!fieldMatch) continue;
+      const key = fieldMatch[1].trim(); const value = fieldMatch[2].trim();
+      if (key === 'Workspace Id') current.workspaceId = value;
+      else if (key === 'Workspace Artifact') current.workspaceArtifactPath = markdownTarget(value);
+      else if (key === 'Snapshot Path') current.snapshotPath = markdownTarget(value);
+      else if (key === 'Workspace Artifact Inner Path') current.workspaceArtifactInnerPath = unquote(value);
+      else if (key === 'Snapshot Kind') current.snapshotKind = value;
+      else if (key === 'Coverage') current.coverage = value;
+      else if (key === 'Binding State') current.bindingState = value;
+      else if (key === 'Integrity Method') current.integrityMethod = value;
+      else if (key === 'Integrity Value') current.integrityValue = value;
+      else if (key === 'Byte Size') current.byteSize = /^\d+$/.test(value) ? Number(value) : null;
+    }
+    out.push(current);
+  }
+  return out.map((item) => Object.freeze({ ...item, byteSize: item.byteSize ?? null }));
+}
+
+function normalizeProfileId(value = '') {
+  const text = String(value || '').trim();
+  return text.toLowerCase() === 'none' ? '' : text;
+}

package/src/tooling/portable/handoff/recipientV2.packageV1.inspect.helpers.js

@@ -0,0 +1,126 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { parseRecipientV2ExternalPayload, parseRecipientV2Pointer } from './recipientV2.artifacts.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, RECIPIENT_V2_SIBLING_ROUTE_INFERENCE } from './recipientV2.entryContract.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { parentTrace } from './recipientV2.lineage.js';
+import { finding } from './recipientV2.topology.materials.js';
+import { RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH } from './recipientV2.packageV1.constants.js';
+import { currentSchemaId, decodeUtf8, field, markdownTarget, numericDimension, oneFile, sectionText, unquote } from './recipientV2.packageV1.shared.js';
+
+export function validateRouteClosure(routePointers, endpointPointers, participantPointers, caches, workspaces, findings) {
+  const roles = new Map([...(endpointPointers || []), ...(participantPointers || [])].map((item) => [item.path, item]));
+  const cacheByPath = new Map((caches || []).map((item) => [item.artifact.path, item]));
+  const workspaceByPath = new Map((workspaces || []).map((item) => [item.artifact.path, item]));
+  for (const pointer of routePointers || []) {
+    const expectedWorkspace = workspaces.find((item) => item.workspaceId === String(pointer.facts?.workspaceId || ''));
+    if (!expectedWorkspace) continue;
+    let cursor = pointer;
+    const seen = new Set([pointer.path]);
+    const ancestorRoles = [];
+    let terminal = '';
+    while (cursor) {
+      const trace = parentTrace(cursor);
+      if (!trace || seen.has(trace)) break;
+      seen.add(trace);
+      if (roles.has(trace)) { cursor = roles.get(trace); ancestorRoles.push(trace); continue; }
+      if (cacheByPath.has(trace) || workspaceByPath.has(trace)) { terminal = trace; break; }
+      findings.push(finding('error', 'portable.handoff-package-v1.route-ancestor-unknown', 'Selected Handoff Pointer ancestor closure contains an unjustified package artifact role.', { pointer: pointer.path, ancestor: trace })); break;
+    }
+    const expectedTerminal = String(pointer.facts?.cacheArtifactPath || expectedWorkspace.artifact.path);
+    if (terminal !== expectedTerminal) findings.push(finding('error', 'portable.handoff-package-v1.route-ancestor-terminal-invalid', 'Selected Handoff Pointer ancestor closure must terminate at its bounded cache when present, otherwise its owning Workspace artifact.', { pointer: pointer.path, expectedTerminal, observedTerminal: terminal }));
+    for (const role of [...(endpointPointers || []), ...(participantPointers || [])].filter((item) => String(item.facts?.routeId || '') === String(pointer.facts?.routeId || ''))) if (!ancestorRoles.includes(role.path)) findings.push(finding('error', 'portable.handoff-package-v1.route-role-off-closure', 'Route-required Role Pointer must be on the selected Handoff Pointer ancestor closure.', { pointer: pointer.path, rolePointer: role.path }));
+    const wsDim = numericDimension(expectedWorkspace.artifact.path);
+    const pointerDim = numericDimension(pointer.path);
+    if (!wsDim || !pointerDim || !pointerDim.startsWith(`${wsDim}-`)) findings.push(finding('error', 'portable.handoff-package-v1.route-placement-invalid', 'Handoff Pointer numeric path must descend from the Workspace containing its authoritative Handoff target.', { pointer: pointer.path, workspace: expectedWorkspace.artifact.path }));
+    validateNumericParentChain(pointer, roles, cacheByPath, expectedWorkspace, findings);
+  }
+}
+
+function validateNumericParentChain(pointer, roles, cacheByPath, workspace, findings) {
+  let child = pointer;
+  const lookup = new Map([...roles, ...cacheByPath].map(([key, value]) => [key, value.artifact || value]));
+  lookup.set(workspace.artifact.path, workspace.artifact);
+  const seen = new Set();
+  while (child && !seen.has(child.path)) {
+    seen.add(child.path);
+    const trace = parentTrace(child);
+    if (!trace) break;
+    const childDim = numericDimension(child.path);
+    const parentDim = numericDimension(trace);
+    const expected = childDim.split('-').slice(0, -1).join('-');
+    if (!childDim || !parentDim || parentDim !== expected) findings.push(finding('error', 'portable.handoff-package-v1.numeric-lineage-invalid', 'Carrier-local route ancestor numeric dimensions must mirror declared Parent continuity without alphabetic lineage components.', { path: child.path, parent: trace, childDimension: childDim, parentDimension: parentDim, expectedParentDimension: expected }));
+    if (trace === workspace.artifact.path) break;
+    child = lookup.get(trace) || null;
+  }
+}
+
+export function deriveVisibleFacts({ markdown = '', schemaId = '', packageContract = null, index = new Map() } = {}) {
+  if (schemaId === 'tiinex.pointer.v1') {
+    const visible = parseRecipientV2Pointer(markdown);
+    const role = String(visible.role || '');
+    if (!role) return null;
+    const base = { factsFormat: 'portable-recipient-v2', factsVersion: 1, role };
+    if (role === 'recovery-orientation') { const workspaceMode = String(packageContract?.packageRole || '') === 'recipient-facing-workspace-carrier'; return { ...base, format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, packageRole: String(packageContract?.packageRole || ''), packageRootPath: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, entryArtifactPath: RECIPIENT_V2_READ_PATH, routeAuthority: workspaceMode ? 'none' : 'qualified-handoff-route-pointer-plus-exact-handoff-bytes', routeSelectionAuthority: workspaceMode ? 'none' : RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, siblingRouteInference: workspaceMode ? false : RECIPIENT_V2_SIBLING_ROUTE_INFERENCE }; }
+    if (role === 'handoff-route') {
+      const workspaceId = String(visible.workspaceId || '');
+      const binding = (packageContract?.workspaces || []).find((item) => item.workspaceId === workspaceId) || null;
+      const archiveFile = binding ? oneFile(index, binding.snapshotPath) : null;
+      const workspaceFile = binding ? oneFile(index, binding.workspaceArtifactPath) : null;
+      const parsed = archiveFile ? inspectStoredWorkspaceArchive(packageFileBytes(archiveFile), { ownedBytes: true }) : null;
+      const handoffEntry = (parsed?.entries || []).find((entry) => entry.path === visible.handoffWorkspacePath) || null;
+      const current = sectionText(markdown, 'Current Read');
+      return { ...base, workspaceId, workspaceArtifactPath: binding?.workspaceArtifactPath || '', workspaceArtifactSha256: workspaceFile ? sha256Hex(packageFileBytes(workspaceFile)) : '', archivePath: binding?.snapshotPath || '', archiveSha256: archiveFile ? sha256Hex(packageFileBytes(archiveFile)) : '', sourceWorkspaceTargetInnerPath: binding?.workspaceArtifactInnerPath || '', sourceWorkspaceTargetSha256: workspaceFile ? sha256Hex(packageFileBytes(workspaceFile)) : '', workspaceRelativeHandoffPath: visible.handoffWorkspacePath, handoffBytes: Number(handoffEntry?.bytes || 0), handoffSha256: String(handoffEntry?.sha256 || ''), routeId: visible.routeId || unquote(field(current, 'Route Id')), cacheArtifactPath: markdownTarget(field(current, 'Workspace Dependency Cache')), requiredContextBindings: Object.freeze([]) };
+    }
+    if (role === 'endpoint-role' || role === 'participant-role') {
+      const targetPayload = visible.targetPayload || '';
+      const payload = oneFile(index, targetPayload);
+      let entry = null;
+      if (payload) {
+        const parsed = inspectStoredWorkspaceArchive(packageFileBytes(payload), { ownedBytes: true });
+        entry = (parsed.entries || []).find((item) => item.path === (visible.targetInnerPath || visible.targetArchiveEntry)) || null;
+      }
+      return { ...base, workspaceId: workspaceIdForRoute(index, visible.routeId || ''), routeId: visible.routeId || '', endpointRequirementId: visible.endpointRequirementId || '', participantRequirementId: visible.participantRequirementId || '', endpointParty: visible.endpointParty || '', roleLabelHint: visible.roleLabelHint || '', referenceTarget: visible.roleReference || '', targetCarrierKind: visible.targetCarrierKind || '', targetWorkspaceId: visible.targetWorkspaceId || '', archivePath: targetPayload, archiveSha256: payload ? sha256Hex(packageFileBytes(payload)) : '', targetInnerPath: visible.targetInnerPath || '', targetArchiveEntry: visible.targetArchiveEntry || '', targetBytes: Number(entry?.bytes || 0), targetSha256: String(entry?.sha256 || '') };
+    }
+    return base;
+  }
+  if (schemaId === 'tiinex.external.payload.v1') {
+    const visible = parseRecipientV2ExternalPayload(markdown);
+    const role = String(visible.payloadRole || '');
+    const parent = parentTraceFromMarkdown(markdown);
+    const workspaceId = String(visible.workspaceId || '') || (packageContract?.workspaces || []).find((item) => item.workspaceArtifactPath === parent)?.workspaceId || '';
+    const materials = parsePayloadMaterials(sectionText(markdown, 'Payload Material Bindings'));
+    return { factsFormat: 'portable-recipient-v2', factsVersion: 1, role, workspaceId, archivePath: visible.location, archiveBytes: visible.bytes, archiveSha256: visible.integrityValue, materials };
+  }
+  return null;
+}
+
+function workspaceIdForRoute(index = new Map(), routeId = '') {
+  const targetRouteId = String(routeId || '');
+  if (!targetRouteId) return '';
+  const matches = [];
+  for (const files of index.values()) for (const candidate of files || []) {
+    if (!/\.md$/i.test(String(candidate.path || ''))) continue;
+    const candidateMarkdown = decodeUtf8(packageFileBytes(candidate));
+    if (currentSchemaId(candidateMarkdown) !== 'tiinex.pointer.v1') continue;
+    const visible = parseRecipientV2Pointer(candidateMarkdown);
+    if (visible.role === 'handoff-route' && String(visible.routeId || '') === targetRouteId) matches.push(String(visible.workspaceId || ''));
+  }
+  const unique = [...new Set(matches.filter(Boolean))];
+  return unique.length === 1 ? unique[0] : '';
+}
+
+function parsePayloadMaterials(section = '') {
+  const lines = String(section || '').split('\n');
+  const out = []; let current = null;
+  for (const line of lines) {
+    const first = line.match(/^- Requirement Id:\s*(.+)$/);
+    if (first) { if (current) out.push(current); current = { requirementId: first[1].trim() }; continue; }
+    const match = line.match(/^\s{2}-\s+([^:]+):\s*(.*)$/); if (!current || !match) continue;
+    const key = match[1].trim(), value = match[2].trim();
+    if (key === 'Classification') current.classification = value; else if (key === 'Material Reference') current.referenceTarget = value; else if (key === 'Archive Entry') current.archiveEntry = value; else if (key === 'Route Workspace Id') current.routeWorkspaceId = value; else if (key === 'Route Path') current.routePath = value; else if (key === 'Source Requirement Id') current.sourceRequirementId = value; else if (key === 'Original Path') current.originalPath = value; else if (key === 'Byte Size') current.bytes = Number(value || 0); else if (key === 'SHA256') current.sha256 = value;
+  }
+  if (current) out.push(current);
+  return out;
+}
+function parentTraceFromMarkdown(markdown = '') { return String(markdown).match(/^\s*-\s+Trace:\s*\[[^\]]*\]\(([^)]+)\)\s*$/mi)?.[1] || ''; }

package/src/tooling/portable/handoff/recipientV2.packageV1.inspect.js

@@ -0,0 +1,185 @@
+import { packageFileByteView, packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { canonicalC14nV2SelfState } from '../../../integrity/integrity.c14nV2.js';
+import { buildHandoffCarrierProjection } from './carrierProjection.js';
+import { buildHandoffWorkspaceByteProvider, inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+import { inspectRecipientV2Artifact, parseRecipientV2ExternalPayload, parseRecipientV2Facts } from './recipientV2.artifacts.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { recipientColdProjection } from './recipientV2.coldProjection.js';
+import { buildPackageLocalParentResolver, inspectEndpointRolePointers, inspectParticipantRolePointers, inspectRoutePointers, parentTrace } from './recipientV2.lineage.js';
+import { finding } from './recipientV2.topology.materials.js';
+import { indexRecipientFiles, recipientWorkspaceDescriptor, virtualCacheMaterial } from './recipientV2.inspect.helpers.js';
+import { inspectPortableToolingBootstrap } from './toolingBootstrap.js';
+import { projectRecipientV2EndpointRoles, projectRecipientV2ParticipantRoles, projectRecipientV2Routes } from './recipientV2.inspect.projection.js';
+import { RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID } from './recipientV2.packageV1.constants.js';
+import { parseHandoffPackageV1, validatePackageFields, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
+import { deriveVisibleFacts, validateRouteClosure } from './recipientV2.packageV1.inspect.helpers.js';
+import { workspaceCarrierProjection } from './recipientV2.packageV1.workspaceProjection.js';
+import { byteEqual, currentSchemaId, decodeUtf8, dedupeFindings, deepFreeze, oneFile } from './recipientV2.packageV1.shared.js';
+
+export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const findings = [];
+  const index = indexRecipientFiles(files, findings);
+  for (const file of files) if (String(file.path || '').includes('/')) findings.push(finding('error', 'portable.handoff-package-v1.path-nonflat', 'Package v1 carrier root must be flat.', { path: file.path || '' }));
+  const packageCandidates = files.filter((file) => currentSchemaId(decodeUtf8(packageFileBytes(file))) === RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID);
+  if (packageCandidates.length !== 1) findings.push(finding('error', 'portable.handoff-package-v1.package-artifact-count', 'Carrier must contain exactly one tiinex.handoff.package.v1 artifact.', { count: packageCandidates.length }));
+  const packageFile = packageCandidates[0] || null;
+  const packageMarkdown = packageFile ? decodeUtf8(packageFileBytes(packageFile)) : '';
+  const packageContract = packageFile ? parseHandoffPackageV1(packageMarkdown) : null;
+  if (packageFile) {
+    if (!/^\d{3}-tiinex-handoff-package\.trace\.md$/.test(String(packageFile.path || ''))) findings.push(finding('error', 'portable.handoff-package-v1.filename-invalid', 'Handoff package artifact filename must expose exactly one numeric package-root dimension.', { path: packageFile.path || '' }));
+    const self = canonicalC14nV2SelfState(packageMarkdown);
+    if (self.state !== 'verified') findings.push(finding('error', 'portable.handoff-package-v1.integrity-self-invalid', 'Handoff package artifact self-integrity must independently verify.', { reason: self.reason || self.state }));
+    validatePackageFields(packageContract, findings);
+  }
+
+  const generatedArtifacts = [];
+  const resolveParent = buildPackageLocalParentResolver(index);
+  for (const file of files) {
+    if (!/\.md$/i.test(String(file.path || '')) || file === packageFile) continue;
+    const markdown = decodeUtf8(packageFileBytes(file));
+    const schemaId = currentSchemaId(markdown);
+    const facts = file.transportFacts || parseRecipientV2Facts(markdown) || deriveVisibleFacts({ file, markdown, schemaId, packageContract, index });
+    if (schemaId === 'tiinex.workspace.v1' && !facts) continue;
+    if (schemaId === 'tiinex.party.role.v1') { findings.push(finding('error', 'portable.handoff-package-v1.detached-role-copy', 'Package root must not carry detached Role artifacts; route grounding uses Role Pointers to exact Workspace/cache bytes.', { path: file.path || '' })); continue; }
+    if (!facts) { findings.push(finding('error', 'portable.handoff-package-v1.unknown-artifact-role', 'Package root contains Markdown whose semantic carrier role is not justified by package v1.', { path: file.path || '', schemaId })); continue; }
+    const artifact = inspectRecipientV2Artifact(file, { facts, resolveParent });
+    generatedArtifacts.push(artifact);
+    findings.push(...artifact.findings);
+  }
+  const readArtifact = generatedArtifacts.find((item) => item.path === packageContract?.startPath && item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'recovery-orientation') || null;
+  if (!readArtifact) findings.push(finding('error', 'portable.handoff-package-v1.start-unresolved', 'Start Artifact must resolve to one qualified recovery/orientation Pointer.'));
+  else if (packageFile && parentTrace(readArtifact) !== packageFile.path) findings.push(finding('error', 'portable.handoff-package-v1.start-parent-mismatch', 'Start Artifact must descend directly from the package artifact.', { observedParent: parentTrace(readArtifact), expectedParent: packageFile.path }));
+
+  const bindings = packageContract?.workspaces || [];
+  const workspaceParts = [];
+  const workspaceDescriptors = [];
+  const virtualWorkspaceTargets = [];
+  for (const binding of bindings) {
+    const workspaceFile = oneFile(index, binding.workspaceArtifactPath);
+    const archiveFile = oneFile(index, binding.snapshotPath);
+    if (!workspaceFile || !archiveFile) { findings.push(finding('error', 'portable.handoff-package-v1.workspace-binding-unresolved', 'Workspace binding paths must resolve exactly once inside the package.', { workspaceId: binding.workspaceId })); continue; }
+    const workspaceMarkdown = decodeUtf8(packageFileBytes(workspaceFile));
+    if (currentSchemaId(workspaceMarkdown) !== 'tiinex.workspace.v1') findings.push(finding('error', 'portable.handoff-package-v1.workspace-schema-invalid', 'Workspace Artifact must declare tiinex.workspace.v1.', { workspaceId: binding.workspaceId, path: workspaceFile.path || '' }));
+    if (String(binding.snapshotKind || '') !== 'exact-workspace-byte-tree-archive' || String(binding.coverage || '') !== 'complete' || String(binding.bindingState || '') !== 'verified' || String(binding.integrityMethod || '') !== 'sha256') findings.push(finding('error', 'portable.handoff-package-v1.workspace-binding-contract-invalid', 'Qualified package v1 Workspace binding requires exact complete verified sha256 semantics.', { workspaceId: binding.workspaceId }));
+    const archiveData = packageFileByteView(archiveFile);
+    const archiveSha = sha256Hex(archiveData);
+    if (archiveSha !== binding.integrityValue) findings.push(finding('error', 'portable.handoff-package-v1.workspace-snapshot-digest-mismatch', 'Workspace Snapshot Integrity Value diverges from exact carried bytes.', { workspaceId: binding.workspaceId }));
+    if (binding.byteSize !== null && Number(binding.byteSize) !== archiveData.byteLength) findings.push(finding('error', 'portable.handoff-package-v1.workspace-snapshot-size-mismatch', 'Workspace Snapshot Byte Size diverges from exact carried bytes.', { workspaceId: binding.workspaceId }));
+    const parsed = inspectStoredWorkspaceArchive(archiveData, { ownedBytes: true });
+    if (parsed.state !== 'qualified') { findings.push(finding('error', 'portable.handoff-package-v1.workspace-snapshot-invalid', 'Workspace Snapshot failed safe normalized archive qualification.', { workspaceId: binding.workspaceId })); continue; }
+    const inner = (parsed.entries || []).filter((entry) => entry.path === binding.workspaceArtifactInnerPath);
+    if (inner.length !== 1) { findings.push(finding('error', 'portable.handoff-package-v1.workspace-inner-unresolved', 'Workspace Artifact Inner Path must resolve exactly once.', { workspaceId: binding.workspaceId, count: inner.length })); continue; }
+    const workspaceData = packageFileByteView(workspaceFile);
+    const innerData = packageFileByteView({ data: inner[0].data });
+    if (!byteEqual(workspaceData, innerData)) findings.push(finding('error', 'portable.handoff-package-v1.workspace-inner-byte-mismatch', 'Carried Workspace Artifact bytes must exactly equal the selected snapshot inner entry.', { workspaceId: binding.workspaceId }));
+    const targetQualification = qualifyHandoffWorkspaceTarget({ targetPath: binding.workspaceArtifactInnerPath, targetData: workspaceData, entries: parsed.entries || [] });
+    if (targetQualification.state !== 'qualified') findings.push(finding('error', 'portable.handoff-package-v1.workspace-target-unqualified', 'Exact bound Workspace Artifact does not qualify.', { workspaceId: binding.workspaceId, reasons: targetQualification.reasons || [] }));
+    const descriptorPart = recipientWorkspaceDescriptor({ workspaceId: binding.workspaceId, facts: { providerKind: 'package-local-stored-zip-v1' }, representation: { workspaceArtifactInnerPath: binding.workspaceArtifactInnerPath, coverage: 'complete' }, payload: { location: binding.snapshotPath }, entries: parsed.entries || [], targetMarkdown: workspaceMarkdown, targetPackagePath: binding.workspaceArtifactPath, targetFile: { bytes: workspaceData.byteLength, sha256: sha256Hex(workspaceData) }, archiveFile: { path: archiveFile.path, bytes: archiveData.byteLength, sha256: archiveSha } });
+    workspaceDescriptors.push(descriptorPart);
+    workspaceParts.push({ workspaceId: binding.workspaceId, artifact: Object.freeze({ path: workspaceFile.path, sha256: sha256Hex(workspaceData), markdown: workspaceMarkdown }), facts: { workspaceId: binding.workspaceId, sourceWorkspaceTargetInnerPath: binding.workspaceArtifactInnerPath, sourceWorkspaceTargetSha256: sha256Hex(workspaceData) }, archiveFile, archive: { archive: parsed, sha256: archiveSha }, targetQualification });
+    virtualWorkspaceTargets.push(workspaceFile);
+  }
+
+  const payloadArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.external.payload.v1' && item.status === 'qualified');
+  const bootstrapArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'portable Tooling bootstrap runtime for recipient orientation and verification');
+  const cacheArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-scoped Handoff dependency cache');
+  const forbiddenWorkspacePayloads = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-representation-payload');
+  if (forbiddenWorkspacePayloads.length) findings.push(finding('error', 'portable.handoff-package-v1.workspace-payload-redundant', 'Complete package-local Workspace bindings must not carry redundant Workspace External Payload companions.', { count: forbiddenWorkspacePayloads.length }));
+  if (generatedArtifacts.some((item) => item.schemaId === 'tiinex.workspace.representation.v1' || item.schemaId === 'tiinex.relation.v1')) findings.push(finding('error', 'portable.handoff-package-v1.workspace-representation-redundant', 'Complete package-local Workspace bindings must not carry redundant Workspace Representation/Relation companions.'));
+
+  let bootstrapInspection = null;
+  if (packageContract?.bootstrapPath) {
+    const bootstrapArtifact = bootstrapArtifacts.find((item) => item.path === packageContract.bootstrapPath) || null;
+    if (!bootstrapArtifact) findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-unresolved', 'Tooling Bootstrap Descriptor must resolve to one qualified bootstrap External Payload artifact.'));
+    else {
+      const payload = parseRecipientV2ExternalPayload(bootstrapArtifact.markdown);
+      const zip = oneFile(index, payload.location);
+      if (!zip || payload.integrityMethod !== 'sha256' || payload.integrityValue !== (zip ? sha256Hex(packageFileBytes(zip)) : '')) findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-payload-invalid', 'Tooling bootstrap descriptor/payload byte identity failed qualification.'));
+      else {
+        const parsed = inspectStoredWorkspaceArchive(packageFileBytes(zip), { ownedBytes: true });
+        if (parsed.state === 'qualified') {
+          bootstrapInspection = inspectPortableToolingBootstrap({ files: (parsed.entries || []).map((entry) => Object.freeze({ path: `tiinex.bootstrap/${entry.path}`, data: entry.data })) });
+          if (bootstrapInspection.status !== 'valid') findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-runtime-unqualified', 'Tooling bootstrap payload failed embedded runtime qualification.'));
+        }
+      }
+    }
+  }
+
+  const caches = [];
+  for (const artifact of cacheArtifacts) {
+    const payload = parseRecipientV2ExternalPayload(artifact.markdown);
+    const file = oneFile(index, payload.location);
+    if (!file) { findings.push(finding('error', 'portable.handoff-package-v1.cache-payload-missing', 'Cache descriptor payload location is unresolved.', { path: artifact.path })); continue; }
+    const parsed = inspectStoredWorkspaceArchive(packageFileBytes(file), { ownedBytes: true });
+    if (parsed.state !== 'qualified') findings.push(finding('error', 'portable.handoff-package-v1.cache-payload-invalid', 'Cache payload is not a qualified safe stored ZIP.', { path: file.path }));
+    caches.push({ artifact, file, facts: artifact.facts || {}, archive: { archive: parsed, sha256: sha256Hex(packageFileBytes(file)) } });
+  }
+  const virtualCacheParts = caches.map((cache) => virtualCacheMaterial(cache, findings));
+  const virtualCache = { files: Object.freeze(virtualCacheParts.flatMap((item) => item.files || [])), materialized: Object.freeze(virtualCacheParts.flatMap((item) => item.materialized || [])) };
+
+  const descriptor = deepFreeze({ schema: 'tiinex.transport.handoff-material-closure-descriptor.v2', version: 2, workspaceMaterializations: Object.freeze(workspaceDescriptors.map((item) => item.workspace)), workspaceArchiveBindings: Object.freeze(workspaceDescriptors.map((item) => item.binding)), materialized: Object.freeze(virtualCache.materialized), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]), endpointRoles: Object.freeze([]), participantRoles: Object.freeze([]), dependencies: Object.freeze([]) }) });
+  const semanticBundle = { ...bundle, files: Object.freeze([...files, ...virtualCache.files]) };
+  const workspaceByteProvider = buildHandoffWorkspaceByteProvider(semanticBundle, descriptor);
+  findings.push(...(workspaceByteProvider.findings || []));
+
+  const routePointers = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'handoff-route' && item.status === 'qualified');
+  const endpointRolePointers = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'endpoint-role' && item.status === 'qualified');
+  const participantRolePointers = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'participant-role' && item.status === 'qualified');
+  const lineage = packageContract ? Object.freeze({ dimension: packageContract.carrierDimension, parentDimension: packageContract.parentCarrierDimension, checkpointKind: packageContract.carrierCheckpoint, majorReason: packageContract.majorReason || '' }) : null;
+  const workspaceMode = String(packageContract?.packageRole || '') === WORKSPACE_PACKAGE_ROLE;
+  let carrierProjection;
+  if (workspaceMode) {
+    if (routePointers.length || endpointRolePointers.length || participantRolePointers.length || caches.length) findings.push(finding('error', 'portable.handoff-package-v1.workspace-carrier.handoff-surface-present', 'Pointerless Workspace carrier must not expose Handoff route, Role pointer, or Handoff cache carriers.', { routes: routePointers.length, endpointRoles: endpointRolePointers.length, participantRoles: participantRolePointers.length, caches: caches.length }));
+    carrierProjection = workspaceCarrierProjection(workspaceParts, lineage);
+  } else {
+    inspectEndpointRolePointers(endpointRolePointers, workspaceParts, caches, findings);
+    inspectParticipantRolePointers(participantRolePointers, workspaceParts, caches, findings);
+    const routeSpecs = routePointers.map((pointer) => ({ workspaceId: String(pointer.facts?.workspaceId || ''), path: String(pointer.facts?.workspaceRelativeHandoffPath || ''), purpose: '' }));
+    carrierProjection = buildHandoffCarrierProjection({ bundle: semanticBundle, descriptor, workspaceByteProvider, carrierLineage: lineage, routes: routeSpecs });
+    if (carrierProjection.status !== 'ready') findings.push(finding('error', 'portable.handoff-package-v1.routes-unqualified', 'Selected Handoff Pointer does not independently resolve to qualified authoritative Handoff bytes.', { causes: carrierProjection.findings || [] }));
+    inspectRoutePointers(routePointers, carrierProjection, workspaceParts, endpointRolePointers, participantRolePointers, index, findings);
+    validateRouteClosure(routePointers, endpointRolePointers, participantRolePointers, caches, workspaceParts, findings);
+    if (routePointers.length !== 1) findings.push(finding('error', 'portable.handoff-package-v1.route-count-invalid', 'Qualified Handoff-carrier package-v1 delivery requires exactly one selected Handoff Pointer.', { count: routePointers.length }));
+    for (const route of carrierProjection.routes || []) {
+      if (route.requiredClosure?.state !== 'qualified') findings.push(finding('error', 'portable.handoff-package-v1.required-closure-unqualified', 'Authoritative Handoff Required Context is not fully carried by exact Workspace snapshots or bounded cache.', { routeId: route.id || '' }));
+      for (const requirement of route.requiredClosure?.requirements || []) if (requirement.state === 'qualified' && !['workspace-archive-entry', 'materialized-required-material'].includes(String(requirement.resolution?.kind || ''))) findings.push(finding('error', 'portable.handoff-package-v1.external-closure-asset', 'Selected route closure requires a carrier kind not owned by complete Workspace snapshots or bounded cache.', { routeId: route.id || '', requirementId: requirement.requirementId || '', kind: requirement.resolution?.kind || '' }));
+    }
+    const allowedCacheRequirementIds = new Set();
+    for (const route of carrierProjection.routes || []) for (const requirement of route.requiredClosure?.requirements || []) if (requirement.requirementId) allowedCacheRequirementIds.add(String(requirement.requirementId));
+    for (const pointer of endpointRolePointers) if (pointer.facts?.endpointRequirementId) allowedCacheRequirementIds.add(String(pointer.facts.endpointRequirementId));
+    for (const pointer of participantRolePointers) if (pointer.facts?.participantRequirementId) allowedCacheRequirementIds.add(String(pointer.facts.participantRequirementId));
+    for (const cache of caches) for (const material of cache.facts?.materials || []) {
+      const requirementId = String(material.sourceRequirementId || material.requirementId || '');
+      if (!requirementId || !allowedCacheRequirementIds.has(requirementId)) findings.push(finding('error', 'portable.handoff-package-v1.cache-over-expansion', 'Workspace dependency cache contains material not required by the selected Handoff route closure.', { cache: cache.artifact.path, requirementId }));
+    }
+  }
+
+  const knownPaths = new Set([
+    packageFile?.path,
+    packageContract?.startPath,
+    ...(bindings || []).flatMap((binding) => [binding.workspaceArtifactPath, binding.snapshotPath]),
+    ...generatedArtifacts.filter((item) => ['recovery-orientation', 'handoff-route', 'endpoint-role', 'participant-role'].includes(String(item.facts?.role || ''))).map((item) => item.path),
+    ...bootstrapArtifacts.flatMap((artifact) => [artifact.path, parseRecipientV2ExternalPayload(artifact.markdown).location]),
+    ...caches.flatMap((cache) => [cache.artifact.path, cache.file.path])
+  ].filter(Boolean));
+  for (const file of files) {
+    const filePath = String(file.path || '');
+    if (/\.json$/i.test(filePath)) findings.push(finding('error', 'portable.handoff-package-v1.parallel-truth-json', 'Package-v1 carrier must not contain receipt.json, manifest.json, or equivalent root-level JSON parallel semantic truth.', { path: filePath }));
+    if (!knownPaths.has(filePath)) findings.push(finding('error', 'portable.handoff-package-v1.unknown-package-artifact', 'Package root contains an artifact whose carrier semantic role is not justified by package-v1 bindings or selected route closure.', { path: filePath }));
+  }
+  const finalFindings = dedupeFindings(findings);
+  const status = finalFindings.some((item) => item.severity === 'error') ? 'invalid' : 'valid';
+  const coldConsumerProjection = recipientColdProjection(carrierProjection, RECIPIENT_V2_READ_PATH);
+  return deepFreeze({
+    schema: 'tiinex.portable.recipient-facing-handoff-package-v1.inspection.v1', detected: Boolean(packageFile), status, format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID,
+    rootArtifact: packageFile ? Object.freeze({ path: packageFile.path, schemaId: RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, sha256: sha256Hex(packageFileBytes(packageFile)), carrierLineage: lineage }) : null,
+    readArtifact, workspaces: Object.freeze(workspaceParts.map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: 'complete', workspaceArtifactPath: item.artifact.path, workspaceArchivePath: item.archiveFile.path, sourceWorkspaceTargetInnerPath: item.facts.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.facts.sourceWorkspaceTargetSha256 }))),
+    routes: projectRecipientV2Routes(routePointers, endpointRolePointers, participantRolePointers), endpointRoles: projectRecipientV2EndpointRoles(endpointRolePointers), participantRoles: projectRecipientV2ParticipantRoles(participantRolePointers),
+    caches: Object.freeze(caches.map((cache) => Object.freeze({ workspaceId: String(cache.facts?.workspaceId || ''), artifactPath: cache.artifact.path, archivePath: cache.file.path, materials: cache.facts.materials || [] }))),
+    bootstrapInspection, transportManifest: null, artifactFacts: Object.freeze(generatedArtifacts.map((item) => Object.freeze({ path: item.path, facts: item.facts }))), descriptor, workspaceByteProvider, carrierProjection, coldConsumerProjection,
+    packageContract, findings: Object.freeze(finalFindings), findingSummary: Object.freeze({ errors: finalFindings.filter((item) => item.severity === 'error').length, findings: finalFindings.length }),
+    boundary: 'Read-only qualification of tiinex.handoff.package.v1: visible package identity/discovery and complete package-local Workspace bindings are reverified from exact bytes; derived inventories have no authority.'
+  });
+}

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

@@ -0,0 +1,12 @@
+import { packageFileBytes } from '../../../export/package.bytes.js';
+import { RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID } from './recipientV2.packageV1.constants.js';
+import { currentSchemaId, decodeUtf8 } from './recipientV2.packageV1.shared.js';
+
+export { RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET } from './recipientV2.packageV1.constants.js';
+export { buildRecipientFacingV2PackageV1 } from './recipientV2.packageV1.build.js';
+export { inspectRecipientFacingV2PackageV1 } from './recipientV2.packageV1.inspect.js';
+export { parseHandoffPackageV1, renderHandoffPackageV1 } from './recipientV2.packageV1.contract.js';
+
+export function isRecipientV2PackageV1Surface(files = []) {
+  return files.some((file) => /\.md$/i.test(String(file.path || '')) && currentSchemaId(decodeUtf8(packageFileBytes(file))) === RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID);
+}

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

@@ -0,0 +1,24 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileByteView } from '../../../export/package.bytes.js';
+import { finding } from './recipientV2.topology.materials.js';
+
+export function exactFile(path, data, logicalKind, mediaType) {
+  return finalizeFile({ path, requestedPath: path, kind: logicalKind, logicalKind, mediaType, data: packageFileByteView({ data }) });
+}
+export function workspaceSchemaTarget(qualification = {}) {
+  return String(qualification?.schemaTarget || '') || 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/coordination/workspace/tiinex.workspace.v1.schema.md';
+}
+export function oneFile(index, path) { const list = index.get(String(path || '')) || []; return list.length === 1 ? list[0] : null; }
+export function validCarrierDimension(value = '') { return /^\d{3}(?:-(?:[1-9]\d*))*$/.test(String(value || '')); }
+export function numericDimension(path = '') { return String(path || '').match(/^(\d{3}(?:-[1-9]\d*)*)-/)?.[1] || ''; }
+export function currentSchemaId(markdown = '') { return String(markdown || '').match(/^\s*-\s+Current Schema:\s*(?:\[)?(tiinex\.[A-Za-z0-9._-]+)(?:\])?/mi)?.[1] || ''; }
+export function sectionText(markdown = '', title = '') { const source = String(markdown || ''); const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); const match = source.match(new RegExp(`^##\\s+${escaped}\\s*$([\\s\\S]*?)(?=^##\\s+|^#\\s+Continuity Integrity\\s*$|\\Z)`, 'mi')); return match ? match[1] : ''; }
+export function field(section = '', label = '') { const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); return String(section || '').match(new RegExp(`^\\s*-\\s+${escaped}:\\s*(.*?)\\s*$`, 'mi'))?.[1]?.trim() || ''; }
+export function markdownTarget(value = '') { const match = String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/); return match ? match[1].trim() : ''; }
+export function unquote(value = '') { const text = String(value || '').trim(); return text.startsWith('`') && text.endsWith('`') ? text.slice(1, -1) : text; }
+export function byteEqual(a, b) { if (a.byteLength !== b.byteLength) return false; for (let i = 0; i < a.byteLength; i += 1) if (a[i] !== b[i]) return false; return true; }
+export function normalizeCreatedAt(value = '') { const text = String(value || '').trim(); if (!text) return '1970-01-01 00:00:00'; return text.replace('T', ' ').replace(/\.\d{3}Z$/, '').replace(/Z$/, '').slice(0, 19); }
+export function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+export function dedupeFindings(items = []) { const map = new Map(); for (const item of items) { const key = `${item.severity || ''}:${item.code || ''}:${item.workspaceId || ''}:${item.path || ''}:${item.pointer || ''}:${item.rolePointer || ''}`; if (!map.has(key)) map.set(key, item); } return [...map.values()]; }
+export function blocked(reason, findings = []) { return Object.freeze({ status: 'blocked', files: Object.freeze([]), topology: Object.freeze({}), inspection: null, findings: Object.freeze([...(findings || []), finding('error', `portable.handoff-package-v1.${reason}`, 'Recipient-facing package-v1 construction failed closed.')]), boundary: 'Package-v1 construction failed closed before exposing a recipient carrier.' }); }
+export function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

package/src/tooling/portable/handoff/recipientV2.packageV1.workspaceProjection.js

@@ -0,0 +1,22 @@
+import { WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
+import { deepFreeze } from './recipientV2.packageV1.shared.js';
+
+export function workspaceCarrierProjection(workspaceParts = [], lineage = null) {
+  const workspaces = workspaceParts.map((item) => Object.freeze({
+    id: String(item.workspaceId || ''),
+    title: String(item.workspaceId || ''),
+    slug: String(item.workspaceId || '').replace(/[^a-zA-Z0-9._-]+/g, '-').toLowerCase(),
+    qualification: item.targetQualification?.state === 'qualified' ? 'qualified' : 'unresolved'
+  }));
+  const ready = workspaces.length > 0 && workspaces.every((item) => item.qualification === 'qualified');
+  return deepFreeze({
+    schema: 'tiinex.portable.handoff-carrier-projection.v1', version: 1,
+    status: ready ? 'ready' : 'blocked', mode: 'workspace', lineage,
+    workspaces: Object.freeze(workspaces),
+    workspace: workspaces[0] || Object.freeze({ id: '', title: '', slug: '', qualification: 'unresolved' }),
+    selection: Object.freeze({ policy: 'none', qualifiedRouteCount: 0, implicitRouteId: '', packageRole: WORKSPACE_PACKAGE_ROLE }),
+    routes: Object.freeze([]),
+    authority: Object.freeze({ semanticAuthority: 'none', filenameAuthority: false, dimensionalParentAuthority: false, routeSelectionAuthority: 'none' }),
+    findings: Object.freeze([])
+  });
+}

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

@@ -0,0 +1,40 @@
+export function parseRecipientV2Pointer(markdown = '') {
+  const current = sectionText(markdown, 'Current Read');
+  const destinations = sectionText(markdown, 'Destinations');
+  return Object.freeze({
+    role: fieldValue(current, 'Carrier Role'),
+    workspaceId: unquoteCode(fieldValue(current, 'Workspace Id')),
+    workspacePayload: markdownTarget(fieldValue(current, 'Workspace Payload')),
+    handoffWorkspacePath: unquoteCode(fieldValue(current, 'Handoff Workspace Path')),
+    routeId: unquoteCode(fieldValue(current, 'Route Id')),
+    routeSelection: fieldValue(current, 'Route Selection'),
+    selectedRouteId: unquoteCode(fieldValue(current, 'Selected Route Id')),
+    candidateRouteCount: Number(unquoteCode(fieldValue(current, 'Candidate Route Count')) || 0),
+    carrierDimension: unquoteCode(fieldValue(current, 'Carrier Dimension')),
+    parentCarrierDimension: unquoteCode(fieldValue(current, 'Parent Carrier Dimension')),
+    carrierCheckpoint: fieldValue(current, 'Carrier Checkpoint'),
+    carrierProfile: fieldValue(current, 'Carrier Profile'),
+    compatibilityTransport: fieldValue(current, 'Compatibility Transport'),
+    endpointRequirementId: unquoteCode(fieldValue(current, 'Endpoint Requirement Id')),
+    endpointParty: fieldValue(current, 'Endpoint Party'),
+    participantRequirementId: unquoteCode(fieldValue(current, 'Participant Requirement Id')),
+    roleLabelHint: fieldValue(current, 'Role Label Hint'),
+    roleReference: unquoteCode(fieldValue(current, 'Role Reference')),
+    targetCarrierKind: unquoteCode(fieldValue(current, 'Target Carrier Kind')),
+    targetPayload: markdownTarget(fieldValue(current, 'Target Payload')),
+    targetWorkspaceId: unquoteCode(fieldValue(current, 'Target Workspace Id')),
+    targetInnerPath: unquoteCode(fieldValue(current, 'Target Inner Path')),
+    targetArchiveEntry: unquoteCode(fieldValue(current, 'Target Archive Entry')),
+    destinations: Object.freeze([...String(destinations || '').matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) => String(match[1] || '')))
+  });
+}
+
+function sectionText(markdown = '', heading = '') {
+  const escaped = escapeRe(heading);
+  const match = String(markdown || '').match(new RegExp(`(?:^|\\n)## ${escaped}\\s*\\n([\\s\\S]*?)(?=\\n## |\\n---\\n|$)`));
+  return String(match?.[1] || '').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 unquoteCode(value = '') { const text = String(value || '').trim(); return text.startsWith('`') && text.endsWith('`') ? text.slice(1, -1) : text; }
+function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
+function escapeRe(value = '') { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

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

@@ -0,0 +1,16 @@
+export function selectRecipientRoutes(routes = [], selector = '', findings = []) {
+  const qualified = [...routes].filter((route) => String(route.state || '') === 'qualified');
+  const requested = String(selector || '').trim();
+  if (!requested) return Object.freeze({ selector: '', routes: Object.freeze(qualified) });
+  const normalized = normalizeRoutePath(requested);
+  const matches = qualified.filter((route) => String(route.id || '') === requested || normalizeRoutePath(route.workspaceRelativePath || '') === normalized || `${String(route.workspaceId || '')}:${normalizeRoutePath(route.workspaceRelativePath || '')}` === requested);
+  if (matches.length !== 1) {
+    findings.push(Object.freeze({ severity: 'error', code: matches.length > 1 ? 'portable.handoff-v2-surface.route-selector.ambiguous' : 'portable.handoff-v2-surface.route-selector.unresolved', message: 'Recipient-v2 selected transport route must resolve to exactly one qualified Handoff route before the visible surface is generated.', selector: requested, matches: matches.length }));
+    return Object.freeze({ selector: requested, routes: Object.freeze([]) });
+  }
+  return Object.freeze({ selector: requested, routes: Object.freeze(matches) });
+}
+
+function normalizeRoutePath(value = '') {
+  return String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}

package/src/tooling/portable/handoff/recipientV2.topology.helpers.js

@@ -0,0 +1,20 @@
+import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export function recipientPackageRootPath(workspaces = []) {
+  if (workspaces.length === 1) return `001-${safeToken(workspaces[0].workspaceId || 'tiinex')}-handoff-package.trace.md`;
+  return '001-tiinex-handoff-package.trace.md';
+}
+
+export function recipientEntriesFingerprint(entries = []) {
+  const identities = entries.map((entry) => ({ path: String(entry.path || ''), bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || '') })).sort((a, b) => a.path.localeCompare(b.path));
+  return sha256Hex(utf8Bytes(JSON.stringify(sortJson(identities))));
+}
+
+function safeToken(value = '') {
+  return String(value || '').trim().toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'workspace';
+}
+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])]));
+}