@tiinex/core 0.1.1

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

@@ -0,0 +1,177 @@
+import { packageFileByteView, sha256Hex } from '../../../export/package.bytes.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+import { inspectPortableToolingBootstrap } from './toolingBootstrap.js';
+import { parseRecipientV2ExternalPayload, parseRecipientV2WorkspaceRepresentation } from './recipientV2.artifacts.js';
+import {
+  finding,
+  inspectRecipientZipPayload,
+  oneRecipientFile,
+  recipientEntriesFingerprint,
+  recipientWorkspaceDescriptor,
+  virtualCacheMaterial
+} from './recipientV2.inspect.helpers.js';
+import {
+  inspectEndpointRolePointers,
+  inspectPackageLocalLineage,
+  inspectParticipantRolePointers,
+  parentTrace
+} from './recipientV2.lineage.js';
+
+export function inspectRecipientV2WorkspaceSurface({ generatedArtifacts = [], rootArtifact = null, index = new Map(), findings = [], transportManifest = null } = {}) {
+  const payloadArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.external.payload.v1' && item.status === 'qualified');
+  const workspaceArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.workspace.v1' && item.facts?.role === 'workspace-node' && item.status === 'qualified');
+  const workspaceRepresentationArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.workspace.representation.v1' && item.status === 'qualified');
+  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 workspacePayloadArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-representation-payload');
+  const bootstrapPayloadArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'portable Tooling bootstrap runtime for recipient orientation and verification');
+  const cachePayloadArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-scoped Handoff dependency cache');
+  if (bootstrapPayloadArtifacts.length > 1) findings.push(finding('error', 'portable.handoff-v2-surface.bootstrap.ambiguous', 'Recipient-facing v2 package exposes more than one bootstrap payload artifact.'));
+
+  inspectPackageLocalLineage({ generatedArtifacts, rootArtifact, findings });
+
+  const workspaceParts = [];
+  const workspaceDescriptors = [];
+  const virtualWorkspaceTargetFiles = [];
+  const archiveClaims = new Map();
+  const representationClaims = new Map();
+  const workspacePayloadClaims = new Map();
+  const caches = cachePayloadArtifacts.map((artifact) => inspectCache(artifact, index, archiveClaims, findings, transportManifest)).filter(Boolean);
+  const recoveryEntriesByWorkspace = indexCacheRecoveryEntries(caches);
+  for (const artifact of workspaceArtifacts) {
+    const facts = artifact.facts || {};
+    const workspaceId = String(facts.workspaceId || '');
+    if (rootArtifact && parentTrace(artifact) !== rootArtifact.path) findings.push(finding('error', 'portable.handoff-v2-surface.workspace.parent-mismatch', 'Package-local Workspace node must be a direct child of the package-local root.', { workspaceId, path: artifact.path, expectedParent: rootArtifact.path, observedParent: parentTrace(artifact) }));
+    const representationCandidates = workspaceRepresentationArtifacts.filter((candidate) => parseRecipientV2WorkspaceRepresentation(candidate.markdown).workspaceArtifactPath === artifact.path);
+    if (representationCandidates.length !== 1) {
+      findings.push(finding('error', representationCandidates.length ? 'portable.handoff-v2-surface.workspace-representation.ambiguous' : 'portable.handoff-v2-surface.workspace-representation.missing', 'Each carried Workspace must resolve exactly one schema-valid canonical Workspace Representation binding.', { workspaceId, workspaceArtifactPath: artifact.path, count: representationCandidates.length }));
+      continue;
+    }
+    const representationArtifact = representationCandidates[0];
+    addRecipientClaim(representationClaims, representationArtifact.path, artifact.path);
+    const representation = parseRecipientV2WorkspaceRepresentation(representationArtifact.markdown);
+    if (parentTrace(representationArtifact) !== artifact.path) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.parent-mismatch', 'Workspace Representation must be a package-local child of the Workspace it binds.', { workspaceId, path: representationArtifact.path, expectedParent: artifact.path, observedParent: parentTrace(representationArtifact) }));
+    if (String(representationArtifact.facts?.workspaceId || '') !== workspaceId || String(representationArtifact.facts?.workspaceArtifactPath || '') !== artifact.path || String(representationArtifact.facts?.payloadArtifactPath || '') !== representation.payloadArtifactPath) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.stale-transport-witness', 'Workspace Representation transport witness diverges from the visible canonical binding and must be treated as stale.', { workspaceId, path: representationArtifact.path }));
+
+    const payloadArtifactMatches = workspacePayloadArtifacts.filter((candidate) => candidate.path === representation.payloadArtifactPath);
+    if (payloadArtifactMatches.length !== 1) {
+      findings.push(finding('error', payloadArtifactMatches.length ? 'portable.handoff-v2-surface.workspace-representation-payload.ambiguous' : 'portable.handoff-v2-surface.workspace-representation-payload.missing', 'Workspace Representation must resolve exactly one schema-valid External Payload endpoint.', { workspaceId, representationArtifactPath: representationArtifact.path, payloadArtifactPath: representation.payloadArtifactPath, count: payloadArtifactMatches.length }));
+      continue;
+    }
+    const payloadArtifact = payloadArtifactMatches[0];
+    addRecipientClaim(workspacePayloadClaims, payloadArtifact.path, representationArtifact.path);
+    if (parentTrace(payloadArtifact) !== artifact.path) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation-payload.parent-mismatch', 'Workspace representation External Payload must be a package-local child of the bound Workspace.', { workspaceId, path: payloadArtifact.path, expectedParent: artifact.path, observedParent: parentTrace(payloadArtifact) }));
+    const payload = parseRecipientV2ExternalPayload(payloadArtifact.markdown);
+    if (payload.mediaType !== 'application/zip' || payload.format !== 'deterministic stored ZIP' || payload.integrityStatus !== 'verified' || payload.integrityMethod !== 'sha256' || payload.integrityTarget !== 'exact payload bytes as carried at the declared local Location') findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation-payload.contract-invalid', 'Workspace representation payload does not satisfy the exact archive/integrity contract required for provider activation.', { workspaceId, path: payloadArtifact.path }));
+    const archiveFile = oneRecipientFile(index, payload.location);
+    if (!archiveFile) { findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation-payload.location-unresolved', 'Workspace Representation payload Location does not resolve to exactly one package-local payload file.', { workspaceId, path: payload.location || '' })); continue; }
+    addRecipientClaim(archiveClaims, archiveFile.path, payloadArtifact.path);
+    const archive = inspectRecipientZipPayload(archiveFile, { archivePath: payload.location, archiveBytes: payload.bytes, archiveSha256: payload.integrityValue }, findings, 'workspace-representation-payload', transportManifest.identityByPath?.get?.(archiveFile.path));
+    if (!archive || archive.archive.state !== 'qualified') continue;
+    const entries = archive.archive.entries || [];
+    const totalBytes = entries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0);
+    const entriesFingerprint = recipientEntriesFingerprint(entries);
+    const coverage = representation.coverage === 'bounded' ? 'bounded' : 'complete';
+    if (Number(facts.entryCount || 0) !== entries.length || Number(facts.totalBytes || 0) !== totalBytes || String(facts.entriesFingerprint || '') !== entriesFingerprint || String(facts.coverage || 'complete') !== coverage || String(facts.coverageState || facts.completenessState || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-surface.workspace.transport-witness-stale', 'Workspace transport witness diverges from the canonical representation payload or exact archive entry set.', { workspaceId }));
+    if (String(representationArtifact.facts?.archivePath || '') !== payload.location || String(representationArtifact.facts?.archiveSha256 || '') !== archive.sha256 || Number(representationArtifact.facts?.entryCount || 0) !== entries.length || String(representationArtifact.facts?.entriesFingerprint || '') !== entriesFingerprint || String(representationArtifact.facts?.coverage || 'complete') !== coverage || String(representationArtifact.facts?.coverageState || representationArtifact.facts?.completenessState || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.stale-archive-witness', 'Workspace Representation transport witness diverges from the exact qualified payload and entry set.', { workspaceId, path: representationArtifact.path }));
+    if (String(payloadArtifact.facts?.workspaceId || '') !== workspaceId || String(payloadArtifact.facts?.archivePath || '') !== payload.location || String(payloadArtifact.facts?.archiveSha256 || '') !== archive.sha256) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation-payload.stale-transport-witness', 'Workspace representation payload transport witness diverges from the visible payload contract or exact payload bytes.', { workspaceId, path: payloadArtifact.path }));
+
+    const targetInnerPath = String(representation.workspaceArtifactInnerPath || '');
+    const targetMatches = entries.filter((entry) => String(entry.path || '') === targetInnerPath);
+    if (targetMatches.length !== 1) { findings.push(finding('error', 'portable.handoff-v2-surface.workspace-source-target.unresolvable', 'Canonical Workspace Representation must resolve exactly one durable source Workspace artifact inside its payload.', { workspaceId, targetInnerPath, count: targetMatches.length })); continue; }
+    const targetEntry = targetMatches[0];
+    const targetData = packageFileByteView({ data: targetEntry.data });
+    const targetSha256 = sha256Hex(targetData);
+    if (String(facts.sourceWorkspaceTargetInnerPath || '') !== targetInnerPath || Number(facts.sourceWorkspaceTargetBytes || 0) !== targetData.byteLength || String(facts.sourceWorkspaceTargetSha256 || '') !== targetSha256) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-source-target.stale-transport-witness', 'Workspace transport witness diverges from the canonical representation-selected durable Workspace artifact.', { workspaceId, targetInnerPath }));
+    if (String(representationArtifact.facts?.sourceWorkspaceTargetInnerPath || '') !== targetInnerPath) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.target-stale', 'Workspace Representation transport witness selects a different durable Workspace target than its visible canonical correlation.', { workspaceId, targetInnerPath }));
+    const targetQualification = qualifyHandoffWorkspaceTarget({ targetPath: targetInnerPath, targetData, entries, parentCandidates: recoveryEntriesByWorkspace.get(workspaceId) || [] });
+    if (targetQualification.state !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-surface.workspace-source-target.unqualified', 'Exact durable source Workspace artifact inside the archive does not independently qualify.', { workspaceId, targetInnerPath, reasons: targetQualification.reasons || [] }));
+
+    const targetVirtualPath = `recipient.v2.workspace-target/${safeToken(workspaceId)}.workspace.md`;
+    const targetVirtualFile = Object.freeze({ path: targetVirtualPath, data: targetData, bytes: targetData.byteLength, sha256: targetSha256, kind: 'recipient-v2-virtual-source-workspace-target' });
+    virtualWorkspaceTargetFiles.push(targetVirtualFile);
+    const descriptorPart = recipientWorkspaceDescriptor({ workspaceId, facts, representation, payload, entries, targetMarkdown: decodeUtf8(targetData), targetPackagePath: targetVirtualPath, targetFile: { bytes: targetData.byteLength, sha256: targetSha256 }, archiveFile: { path: archiveFile.path, bytes: archive.bytes, sha256: archive.sha256 } });
+    workspaceDescriptors.push(descriptorPart);
+    workspaceParts.push({ workspaceId, artifact, facts, representationArtifact, representation, payloadArtifact, payload, targetFile: targetVirtualFile, sourceTargetEntry: targetEntry, targetQualification, archiveFile, archive, descriptorPart });
+  }
+  for (const artifact of workspaceRepresentationArtifacts) if ((representationClaims.get(artifact.path) || []).length !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation.unowned', 'Every canonical Workspace Representation must bind exactly one carried Workspace.', { path: artifact.path, claims: (representationClaims.get(artifact.path) || []).length }));
+  for (const artifact of workspacePayloadArtifacts) if ((workspacePayloadClaims.get(artifact.path) || []).length !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.workspace-representation-payload.unowned', 'Every Workspace representation External Payload must be selected by exactly one canonical Workspace Representation.', { path: artifact.path, claims: (workspacePayloadClaims.get(artifact.path) || []).length }));
+
+  const bootstrap = inspectBootstrap(bootstrapPayloadArtifacts[0], index, archiveClaims, findings, transportManifest);
+  const cacheWorkspaceIds = new Set();
+  for (const cache of caches) {
+    const workspaceId = String(cache.facts?.workspaceId || '');
+    if (!workspaceId) findings.push(finding('error', 'portable.handoff-v2-surface.cache.workspace-id-missing', 'Workspace-scoped dependency cache must declare its owning Workspace id.', { path: cache.artifact.path || '' }));
+    else if (cacheWorkspaceIds.has(workspaceId)) findings.push(finding('error', 'portable.handoff-v2-surface.cache.workspace-ambiguous', 'A Workspace may expose at most one package-local dependency cache.', { workspaceId }));
+    else cacheWorkspaceIds.add(workspaceId);
+    const workspace = workspaceParts.find((item) => item.workspaceId === workspaceId);
+    if (!workspace) findings.push(finding('error', 'portable.handoff-v2-surface.cache.workspace-unresolved', 'Workspace-scoped dependency cache does not resolve to a carried qualified Workspace.', { workspaceId, path: cache.artifact.path || '' }));
+    else if (parentTrace(cache.artifact) !== workspace.artifact.path) findings.push(finding('error', 'portable.handoff-v2-surface.cache.parent-mismatch', 'Workspace-scoped dependency cache Parent must be its owning package-local Workspace node.', { workspaceId, path: cache.artifact.path || '', expectedParent: workspace.artifact.path, observedParent: parentTrace(cache.artifact) }));
+  }
+  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 || [])) };
+  inspectEndpointRolePointers(endpointRolePointers, workspaceParts, caches, findings);
+  inspectParticipantRolePointers(participantRolePointers, workspaceParts, caches, findings);
+
+  return Object.freeze({
+    routePointers: Object.freeze(routePointers),
+    endpointRolePointers: Object.freeze(endpointRolePointers),
+    participantRolePointers: Object.freeze(participantRolePointers),
+    bootstrap: bootstrap || null,
+    workspaceParts: Object.freeze(workspaceParts),
+    workspaceDescriptors: Object.freeze(workspaceDescriptors),
+    virtualWorkspaceTargetFiles: Object.freeze(virtualWorkspaceTargetFiles),
+    archiveClaims,
+    caches: Object.freeze(caches),
+    virtualCache: Object.freeze(virtualCache)
+  });
+}
+
+function indexCacheRecoveryEntries(caches = []) {
+  const map = new Map();
+  for (const cache of caches || []) {
+    const workspaceId = String(cache?.facts?.workspaceId || '');
+    if (!workspaceId || cache?.archive?.archive?.state !== 'qualified') continue;
+    const byArchivePath = new Map((cache.archive.archive.entries || []).map((entry) => [String(entry.path || ''), entry]));
+    const entries = map.get(workspaceId) || [];
+    for (const material of cache.facts?.materials || []) {
+      const originalPath = String(material.originalPath || '').replace(/\\/g, '/').replace(/^\/+/, '');
+      const entry = byArchivePath.get(String(material.archiveEntry || ''));
+      if (!originalPath || !entry) continue;
+      entries.push(Object.freeze({ path: originalPath, data: entry.data, bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || '') }));
+    }
+    map.set(workspaceId, entries);
+  }
+  return map;
+}
+function inspectBootstrap(artifact, index, claims, findings, transportManifest = null) {
+  if (!artifact) return null;
+  const facts = artifact.facts || {};
+  const file = oneRecipientFile(index, facts.archivePath);
+  if (!file) { findings.push(finding('error', 'portable.handoff-v2-surface.bootstrap.payload-missing', 'Bootstrap External Payload artifact does not resolve to its local ZIP companion.')); return null; }
+  addRecipientClaim(claims, file.path, artifact.path);
+  const archive = inspectRecipientZipPayload(file, facts, findings, 'bootstrap', transportManifest?.identityByPath?.get?.(file.path));
+  if (!archive || archive.archive.state !== 'qualified') return { artifact, file, facts, archive, inspection: null };
+  const entries = archive.archive.entries || [];
+  const totalBytes = entries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0);
+  if (Number(facts.entryCount || 0) !== entries.length || Number(facts.totalBytes || 0) !== totalBytes || String(facts.entriesFingerprint || '') !== recipientEntriesFingerprint(entries)) findings.push(finding('error', 'portable.handoff-v2-surface.bootstrap.identity-set-mismatch', 'Bootstrap archive entry identity set differs from its visible declaration.'));
+  const reconstructed = { files: entries.map((entry) => Object.freeze({ path: `tiinex.bootstrap/${entry.path}`, data: entry.data })) };
+  const inspection = inspectPortableToolingBootstrap(reconstructed);
+  if (inspection.status !== 'valid') findings.push(finding('error', 'portable.handoff-v2-surface.bootstrap.unqualified', 'Reconstructed bootstrap payload does not qualify against its embedded manifest.', { causes: inspection.findings || [] }));
+  return { artifact, file, facts, archive, inspection };
+}
+
+function inspectCache(artifact, index, claims, findings, transportManifest = null) {
+  if (!artifact) return null;
+  const facts = artifact.facts || {};
+  const file = oneRecipientFile(index, facts.archivePath);
+  if (!file) { findings.push(finding('error', 'portable.handoff-v2-surface.cache.payload-missing', 'Context cache External Payload artifact does not resolve to its local ZIP companion.')); return null; }
+  addRecipientClaim(claims, file.path, artifact.path);
+  const archive = inspectRecipientZipPayload(file, facts, findings, 'cache', transportManifest?.identityByPath?.get?.(file.path));
+  return { artifact, file, facts, archive };
+}
+
+export function addRecipientClaim(map, path, owner) { const key = String(path || ''); const list = map.get(key) || []; list.push(String(owner || '')); map.set(key, list); }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function safeToken(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || 'workspace'; }

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

@@ -0,0 +1,142 @@
+import { packageFileByteView, sha256Hex } from '../../../export/package.bytes.js';
+import { finding, oneRecipientFile } from './recipientV2.inspect.helpers.js';
+
+export function buildPackageLocalParentResolver(index) {
+  return ({ parent = {} } = {}) => {
+    const targets = new Set();
+    if (parent.trace) targets.add(String(parent.trace));
+    for (const entry of parent.originEntries || []) if (String(entry?.label || '') === 'relative' && entry?.target) targets.add(String(entry.target));
+    const resolved = [...targets].map((path) => oneRecipientFile(index, path)).filter(Boolean);
+    const unique = new Map(resolved.map((file) => [String(file.path || ''), file]));
+    if (unique.size !== 1) return Object.freeze({ state: unique.size > 1 ? 'ambiguous' : 'unavailable', reason: unique.size > 1 ? 'multiple-package-local-parent-candidates' : 'package-local-parent-not-carried' });
+    const file = [...unique.values()][0];
+    const markdown = decodeUtf8(packageFileByteView(file));
+    return markdown ? Object.freeze({ state: 'qualified', markdown, basis: 'package-local-parent-trace', packagePath: String(file.path || ''), sha256: sha256Hex(packageFileByteView(file)) }) : Object.freeze({ state: 'unavailable', reason: 'package-local-parent-not-markdown' });
+  };
+}
+
+export function inspectPackageLocalLineage({ generatedArtifacts = [], rootArtifact = null, findings = [] } = {}) {
+  if (!rootArtifact) return;
+  const byPath = new Map(generatedArtifacts.map((item) => [item.path, item]));
+  for (const artifact of generatedArtifacts) {
+    const path = String(artifact.path || '');
+    const trace = parentTrace(artifact);
+    const childDimension = numericDimension(path);
+    if (artifact === rootArtifact) {
+      if (childDimension !== '001') findings.push(finding('error', 'portable.handoff-v2-surface.lineage.root-dimension-invalid', 'Package root must occupy numeric dimension 001.', { path, dimension: childDimension }));
+      continue;
+    }
+    if (!trace) { findings.push(finding('error', 'portable.handoff-v2-surface.lineage.parent-missing', 'Every generated package-local artifact except the root must declare one Parent.', { path })); continue; }
+    const parent = byPath.get(trace);
+    if (!parent) { findings.push(finding('error', 'portable.handoff-v2-surface.lineage.parent-unresolved', 'Generated package-local Parent trace does not resolve to another carried generated artifact.', { path, parent: trace })); continue; }
+    const parentDimension = numericDimension(trace);
+    const expectedParentDimension = parentNumericDimension(childDimension);
+    if (!childDimension || !parentDimension || parentDimension !== expectedParentDimension) findings.push(finding('error', 'portable.handoff-v2-surface.lineage.path-parent-mismatch', 'Numeric pathing must mirror the explicitly declared package-local Parent relation.', { path, childDimension, parent: trace, parentDimension, expectedParentDimension }));
+
+    const seen = new Set([path]);
+    let cursor = artifact;
+    let reachedRoot = false;
+    while (cursor && cursor !== rootArtifact) {
+      const parentPath = parentTrace(cursor);
+      if (!parentPath || seen.has(parentPath)) break;
+      seen.add(parentPath);
+      cursor = byPath.get(parentPath) || null;
+      if (cursor === rootArtifact) reachedRoot = true;
+    }
+    if (!reachedRoot) findings.push(finding('error', 'portable.handoff-v2-surface.lineage.root-unreachable', 'Following declared Parent from a generated artifact must terminate at the single package-local root.', { path, root: rootArtifact.path }));
+  }
+}
+
+export function inspectParticipantRolePointers(pointers, workspaces, caches, findings) {
+  inspectRolePointers('participant-role', pointers, workspaces, caches, findings);
+}
+
+export function inspectEndpointRolePointers(pointers, workspaces, caches, findings) {
+  inspectRolePointers('endpoint-role', pointers, workspaces, caches, findings);
+}
+
+function inspectRolePointers(roleKind, pointers, workspaces, caches, findings) {
+  const codeKind = roleKind === 'endpoint-role' ? 'endpoint-role' : 'participant-role';
+  const labelKind = roleKind === 'endpoint-role' ? 'Endpoint Role' : 'Participant Role';
+  for (const pointer of pointers || []) {
+    const facts = pointer.facts || {};
+    const carrierKind = String(facts.targetCarrierKind || '');
+    let entry = null;
+    let archivePath = '';
+    if (carrierKind === 'workspace-archive-entry') {
+      const workspace = workspaces.find((item) => item.workspaceId === String(facts.targetWorkspaceId || ''));
+      archivePath = String(workspace?.archiveFile?.path || '');
+      entry = (workspace?.archive?.archive?.entries || []).find((item) => String(item.path || '') === String(facts.targetInnerPath || '')) || null;
+    } else if (carrierKind === 'workspace-cache-entry') {
+      const cache = caches.find((item) => item.artifact.path === String(facts.archivePath || '') || item.file.path === String(facts.archivePath || '') || String(item.facts?.workspaceId || '') === String(facts.workspaceId || ''));
+      archivePath = String(cache?.file?.path || '');
+      entry = (cache?.archive?.archive?.entries || []).find((item) => String(item.path || '') === String(facts.targetArchiveEntry || '')) || null;
+    } else {
+      findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.carrier-kind-invalid`, `${labelKind} Pointer declares an unsupported exact carrier kind.`, { path: pointer.path || '', carrierKind }));
+      continue;
+    }
+    if (!entry) {
+      findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.target-unresolved`, `${labelKind} Pointer target does not resolve to one exact carried archive entry.`, { path: pointer.path || '', carrierKind }));
+      continue;
+    }
+    const data = packageFileByteView({ data: entry.data });
+    const digest = sha256Hex(data);
+    if (String(facts.archivePath || '') !== archivePath) findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.archive-path-mismatch`, `${labelKind} Pointer archive path diverges from the independently resolved carrier.`, { path: pointer.path || '', expected: archivePath, observed: String(facts.archivePath || '') }));
+    if (Number(facts.targetBytes || 0) !== data.byteLength || String(facts.targetSha256 || '') !== digest) findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.target-identity-mismatch`, `${labelKind} Pointer byte identity diverges from the exact carried Role target.`, { path: pointer.path || '' }));
+    const markdown = decodeUtf8(data);
+    if (!/^\s*-\s+Current Schema:\s*(?:\[)?tiinex\.party\.role\.v1(?:\])?/mi.test(markdown)) findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.target-schema-invalid`, `${labelKind} Pointer target is not a readable tiinex.party.role.v1 artifact.`, { path: pointer.path || '' }));
+    const label = String(markdown.match(/^\s*-\s+Role Label:\s*(.+?)\s*$/mi)?.[1] || '').trim();
+    if (!label) findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.target-label-missing`, `${labelKind} Pointer target lacks a readable Role Label.`, { path: pointer.path || '' }));
+    if (facts.roleLabelHint && label && String(facts.roleLabelHint) !== label) findings.push(finding('error', `portable.handoff-v2-surface.${codeKind}.label-hint-mismatch`, `${labelKind} label hint contradicts the exact carried Role artifact.`, { path: pointer.path || '', expected: label, observed: String(facts.roleLabelHint || '') }));
+    if (roleKind === 'endpoint-role' && !['from', 'to'].includes(String(facts.endpointParty || '').toLowerCase())) findings.push(finding('error', 'portable.handoff-v2-surface.endpoint-role.party-invalid', 'Endpoint Role Pointer must visibly bind exactly one Handoff endpoint party.', { path: pointer.path || '', endpointParty: String(facts.endpointParty || '') }));
+  }
+}
+
+export function inspectRoutePointers(pointers, carrier, workspaces, endpointPointers, participantPointers, index, findings) {
+  const byKey = new Map((carrier.routes || []).map((route) => [`${route.workspaceId}\u0000${route.workspaceRelativePath}`, route]));
+  const roleByPath = new Map([...(endpointPointers || []), ...(participantPointers || [])].map((pointer) => [String(pointer.path || ''), pointer]));
+  for (const pointer of pointers) {
+    const facts = pointer.facts || {};
+    const key = `${String(facts.workspaceId || '')}\u0000${String(facts.workspaceRelativeHandoffPath || '')}`;
+    const route = byKey.get(key);
+    const workspace = workspaces.find((item) => item.workspaceId === String(facts.workspaceId || ''));
+    if (!route || route.state !== 'qualified' || !workspace) { findings.push(finding('error', 'portable.handoff-v2-surface.route-pointer.unqualified', 'Handoff route Pointer does not resolve to one independently qualified Handoff route.', { path: pointer.path || '' })); continue; }
+    const checks = [
+      [facts.workspaceArtifactPath, workspace.artifact.path, 'workspace-artifact-path'],
+      [facts.workspaceArtifactSha256, workspace.artifact.sha256, 'workspace-artifact-sha256'],
+      [facts.archivePath, workspace.archiveFile.path, 'archive-path'],
+      [facts.archiveSha256, String(workspace.archive?.sha256 || ''), 'archive-sha256'],
+      [facts.sourceWorkspaceTargetInnerPath, workspace.facts.sourceWorkspaceTargetInnerPath, 'source-workspace-target-inner-path'],
+      [facts.sourceWorkspaceTargetSha256, workspace.facts.sourceWorkspaceTargetSha256, 'source-workspace-target-sha256'],
+      [facts.handoffSha256, route.sha256, 'handoff-sha256']
+    ];
+    for (const [actual, expected, name] of checks) if (String(actual || '') !== String(expected || '')) findings.push(finding('error', `portable.handoff-v2-surface.route-pointer.${name}-mismatch`, 'Handoff route Pointer diverges from independently qualified Workspace/archive/Handoff truth.', { path: pointer.path || '' }));
+    const expectedBaseParent = facts.cacheArtifactPath ? String(facts.cacheArtifactPath) : workspace.artifact.path;
+    if (facts.cacheArtifactPath && !oneRecipientFile(index, facts.cacheArtifactPath)) findings.push(finding('error', 'portable.handoff-v2-surface.route-pointer.cache-missing', 'Handoff route Pointer declares a package-local Workspace dependency cache ancestor that is not carried.', { path: pointer.path || '', cacheArtifactPath: facts.cacheArtifactPath }));
+    let cursorParent = parentTrace(pointer);
+    const roleAncestors = [];
+    const seen = new Set();
+    while (roleByPath.has(cursorParent) && !seen.has(cursorParent)) {
+      seen.add(cursorParent);
+      const rolePointer = roleByPath.get(cursorParent);
+      roleAncestors.push(rolePointer);
+      if (String(rolePointer.facts?.routeId || '') !== String(route.id || '') || String(rolePointer.facts?.workspaceId || '') !== String(workspace.workspaceId || '')) findings.push(finding('error', 'portable.handoff-v2-surface.route-pointer.role-route-mismatch', 'Role Pointer ancestor is bound to a different Handoff route/Workspace.', { path: pointer.path || '', rolePointer: rolePointer.path || '' }));
+      cursorParent = parentTrace(rolePointer);
+    }
+    if (cursorParent !== expectedBaseParent) findings.push(finding('error', 'portable.handoff-v2-surface.route-pointer.parent-mismatch', 'Handoff route Pointer ancestry must pass only through route-bound endpoint/participant Role Pointers and terminate at its Workspace dependency cache when present, otherwise its package-local Workspace node.', { path: pointer.path || '', expectedParent: expectedBaseParent, observedTerminalParent: cursorParent }));
+    if (Number(facts.handoffBytes || 0) && Number(facts.handoffBytes || 0) !== Number(resolveRouteBytes(workspace, facts.workspaceRelativeHandoffPath))) findings.push(finding('error', 'portable.handoff-v2-surface.route-pointer.handoff-bytes-mismatch', 'Handoff route Pointer byte count differs from exact archive entry bytes.', { path: pointer.path || '' }));
+  }
+}
+
+function resolveRouteBytes(workspace, path) {
+  const entry = (workspace.archive?.archive?.entries || []).find((item) => String(item.path || '') === String(path || ''));
+  return Number(entry?.bytes || 0);
+}
+
+export function parentTrace(artifact = {}) {
+  return String(artifact?.conformance?.parentContinuity?.trace || '');
+}
+
+function numericDimension(path = '') { return String(path || '').match(/^(\d+(?:-\d+)*)-/)?.[1] || ''; }
+function parentNumericDimension(dimension = '') { const parts = String(dimension || '').split('-').filter(Boolean); return parts.length > 1 ? parts.slice(0, -1).join('-') : ''; }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }

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

@@ -0,0 +1,147 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileByteView } from '../../../export/package.bytes.js';
+import { exportFileMapZipUint8Array } from '../../../export/package.zip.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { renderRecipientV2ExternalPayload, renderRecipientV2Pointer } from './recipientV2.artifacts.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, RECIPIENT_V2_SIBLING_ROUTE_INFERENCE, recipientV2EntryCurrentRead } from './recipientV2.entryContract.js';
+import { recipientV2TransportFacts } from './recipientV2.transportManifest.js';
+import { buildRecipientV2BootstrapCarrier, recipientV2ParentAuthority } from './recipientV2.topology.workspaces.js';
+import { buildEndpointRolePointerChain, buildParticipantRolePointerChain } from './recipientV2.endpointRolePointers.js';
+import { bindingForWorkspace, detachedMaterial, duplicates, finding, roleMaterialTarget, routeClaimsDetachedMaterial, safeToken, uniqueFileIndex } from './recipientV2.topology.materials.js';
+import { 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';
+import { renderHandoffPackageV1 } from './recipientV2.packageV1.contract.js';
+import { inspectRecipientFacingV2PackageV1 } from './recipientV2.packageV1.inspect.js';
+import { blocked, deepFreeze, exactFile, workspaceSchemaTarget } from './recipientV2.packageV1.shared.js';
+
+export function buildRecipientFacingV2PackageV1(input = {}) {
+  const sourceSurface = input.sourceSurface || null;
+  const descriptor = input.descriptor || input.bundle?.handoffClosure || {};
+  const carrier = input.carrierProjection || {};
+  const createdAt = input.createdAt || input.bundle?.manifest?.createdAt || input.bundle?.builtAt || '';
+  const findings = [];
+  if (!sourceSurface || sourceSurface.status !== 'ready') return blocked('source-surface-unready', sourceSurface?.findings || []);
+  const routes = (carrier.routes || []).filter((route) => route.state === 'qualified');
+  const selector = String(input.routeSelector || input.routeId || '').trim();
+  const selected = selector ? routes.filter((route) => route.id === selector || route.workspaceRelativePath === selector || `${String(route.workspaceId || '')}:${String(route.workspaceRelativePath || '')}` === selector || `handoff-route:${String(route.workspaceId || '')}:${String(route.workspaceRelativePath || '')}` === selector) : routes;
+  if (selected.length !== 1) return blocked('route-selection-unresolved', [finding('error', 'portable.handoff-package-v1.route-selection-unresolved', 'Package v1 manufacture requires exactly one qualified selected Handoff route.', { count: selected.length })]);
+  const route = selected[0];
+  const sourceWorkspaceById = new Map((sourceSurface.topology?.workspaces || []).map((item) => [String(item.workspaceId || ''), item]));
+  const sourceByPath = new Map((sourceSurface.files || []).map((file) => [String(file.path || ''), file]));
+  // The package-v1 carrier preserves the complete inherited Workspace source chain.
+  // Route closure remains selected and minimal, but complete package-local Workspace
+  // bindings are not pruned merely because one carried Workspace is not on the
+  // selected Handoff's pre-Handoff closure.
+  const workspaceIds = [...sourceWorkspaceById.keys()].filter(Boolean).sort();
+  const workspacePlans = workspaceIds.map((workspaceId, index) => Object.freeze({ workspaceId, ordinal: index + 3, prefix: `001-${index + 3}`, slug: safeToken(workspaceId) }));
+  const files = [];
+  const topology = { root: null, read: null, workspaces: [], caches: [], endpointRoles: [], participantRoles: [], routes: [], bootstrap: null };
+  const workspaceById = new Map();
+
+  for (const plan of workspacePlans) {
+    const source = sourceWorkspaceById.get(plan.workspaceId);
+    if (!source || String(source.coverage || '') !== 'complete') { findings.push(finding('error', 'portable.handoff-package-v1.workspace.complete-required', 'Package-local direct Workspace binding requires one complete source snapshot.', { workspaceId: plan.workspaceId })); continue; }
+    const sourceArchive = sourceByPath.get(String(source.archivePath || ''));
+    if (!sourceArchive) { findings.push(finding('error', 'portable.handoff-package-v1.workspace.archive-missing', 'Selected complete Workspace archive is unavailable.', { workspaceId: plan.workspaceId })); continue; }
+    const archiveData = packageFileByteView(sourceArchive);
+    const parsed = inspectStoredWorkspaceArchive(archiveData, { ownedBytes: true });
+    if (parsed.state !== 'qualified') { findings.push(finding('error', 'portable.handoff-package-v1.workspace.archive-invalid', 'Selected complete Workspace snapshot bytes do not qualify.', { workspaceId: plan.workspaceId })); continue; }
+    const innerPath = String(source.sourceWorkspaceTargetInnerPath || '');
+    const matches = (parsed.entries || []).filter((entry) => entry.path === innerPath);
+    if (matches.length !== 1) { findings.push(finding('error', 'portable.handoff-package-v1.workspace.target-unresolved', 'Workspace artifact inner path must resolve exactly once inside the complete snapshot.', { workspaceId: plan.workspaceId, innerPath, count: matches.length })); continue; }
+    const targetData = packageFileByteView({ data: matches[0].data });
+    const targetQualification = qualifyHandoffWorkspaceTarget({ targetPath: innerPath, targetData, entries: parsed.entries || [] });
+    if (targetQualification.state !== 'qualified') { findings.push(finding('error', 'portable.handoff-package-v1.workspace.target-unqualified', 'Exact Workspace artifact bytes inside the snapshot do not qualify.', { workspaceId: plan.workspaceId, reasons: targetQualification.reasons || [] })); continue; }
+    const workspacePath = `${plan.prefix}-${plan.slug}.workspace.md`;
+    const archivePath = `${plan.prefix}-${plan.slug}.workspace.zip`;
+    const workspaceFile = exactFile(workspacePath, targetData, 'recipient-v2-package-v1-exact-workspace-artifact', 'text/markdown');
+    const archiveFile = exactFile(archivePath, archiveData, 'recipient-v2-package-v1-complete-workspace-snapshot', 'application/zip');
+    files.push(workspaceFile, archiveFile);
+    const parent = recipientV2ParentAuthority(workspaceFile, 'tiinex.workspace.v1', workspaceSchemaTarget(targetQualification), createdAt);
+    const projection = Object.freeze({
+      workspaceId: plan.workspaceId, ordinal: plan.ordinal, workspacePath, workspaceSha256: workspaceFile.sha256,
+      archivePath, archiveSha256: archiveFile.sha256, sourceWorkspaceTargetInnerPath: innerPath,
+      sourceWorkspaceTargetSha256: workspaceFile.sha256, sourceWorkspaceTargetBytes: workspaceFile.bytes, coverage: 'complete'
+    });
+    topology.workspaces.push(projection);
+    workspaceById.set(plan.workspaceId, { ...projection, file: workspaceFile, parent });
+  }
+
+  if (findings.some((item) => item.severity === 'error')) return blocked('workspace-binding-blocked', findings);
+
+  const packageFile = finalizeFile({
+    path: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH,
+    kind: 'tiinex-handoff-package-artifact',
+    logicalKind: 'recipient-v2-package-v1-root',
+    mediaType: 'text/markdown',
+    content: renderHandoffPackageV1({ createdAt, workspaces: topology.workspaces, carrierLineage: carrier.lineage || {}, carrierProfile: input.carrierProfile || null, startPath: RECIPIENT_V2_READ_PATH, bootstrapPath: hasBootstrap(input.bundle) ? '001-2-bootstrap.trace.md' : '' })
+  });
+  files.push(packageFile);
+  topology.root = Object.freeze({ path: packageFile.path, sha256: packageFile.sha256 });
+  const packageParent = recipientV2ParentAuthority(packageFile, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET, createdAt);
+
+  const bootstrapSource = (input.bundle?.files || []).filter((file) => String(file.path || '').startsWith('tiinex.bootstrap/'));
+  if (bootstrapSource.length) {
+    const bootstrap = buildRecipientV2BootstrapCarrier(bootstrapSource, createdAt, findings, packageParent);
+    if (bootstrap) { files.push(bootstrap.artifact, bootstrap.payload); topology.bootstrap = bootstrap.projection; }
+  }
+
+  const byPath = uniqueFileIndex(input.bundle?.files || [], findings);
+  const detached = detachedMaterial(descriptor, byPath, findings);
+  const selectedDetached = detached.filter((item) => routeClaimsDetachedMaterial(route, item));
+  const owningWorkspace = workspaceById.get(String(route.workspaceId || ''));
+  let cache = null;
+  if (selectedDetached.length && owningWorkspace) {
+    const plan = workspacePlans.find((item) => item.workspaceId === owningWorkspace.workspaceId);
+    const artifactPath = `${plan.prefix}-1-cache.trace.md`;
+    const archivePath = `${plan.prefix}-1-cache.zip`;
+    const cacheEntries = selectedDetached.map((item, index) => ({ path: `material/${index + 1}-${safeToken(item.requirementId || item.referenceTarget || 'material')}.bin`, data: item.data }));
+    const cacheBytes = exportFileMapZipUint8Array(cacheEntries, 'portable.handoff-package-v1.cache.path.invalid');
+    const cacheFile = finalizeFile({ path: archivePath, kind: 'handoff-material-cache', logicalKind: 'recipient-v2-package-v1-workspace-dependency-cache', mediaType: 'application/zip', data: cacheBytes });
+    const cacheFacts = {
+      workspaceId: owningWorkspace.workspaceId, archivePath, archiveBytes: cacheFile.bytes, archiveSha256: cacheFile.sha256,
+      materials: selectedDetached.map((item, index) => ({ requirementId: item.requirementId, classification: item.classification, referenceTarget: item.referenceTarget, routeWorkspaceId: item.routeWorkspaceId, routePath: item.routePath, sourceRequirementId: item.sourceRequirementId, originalPath: item.originalPath, archiveEntry: cacheEntries[index].path, bytes: item.bytes, sha256: item.sha256 }))
+    };
+    const cacheArtifact = finalizeFile({ path: artifactPath, kind: 'tiinex-external-payload-artifact', logicalKind: 'recipient-v2-package-v1-workspace-dependency-cache-reference', mediaType: 'text/markdown', transportFacts: recipientV2TransportFacts('workspace-scoped Handoff dependency cache', cacheFacts), content: renderRecipientV2ExternalPayload({ createdAt, parent: owningWorkspace.parent, title: `Workspace Dependency Cache — ${owningWorkspace.workspaceId}`, summary: 'Exact route-bounded dependency bytes not satisfied by a complete carried Workspace snapshot.', label: `${owningWorkspace.workspaceId} Handoff dependency cache`, kind: 'zip export', role: 'workspace-scoped Handoff dependency cache', location: archivePath, bytes: cacheFile.bytes, sha256: cacheFile.sha256, facts: cacheFacts }) });
+    files.push(cacheArtifact, cacheFile);
+    cache = { workspaceId: owningWorkspace.workspaceId, artifactPath, archivePath, materials: cacheFacts.materials, parent: recipientV2ParentAuthority(cacheArtifact, 'tiinex.external.payload.v1', RECIPIENT_V2_EXTERNAL_PAYLOAD_SCHEMA_TARGET, createdAt) };
+    topology.caches.push(Object.freeze({ workspaceId: cache.workspaceId, artifactPath, archivePath, materials: cache.materials }));
+  }
+
+  if (!owningWorkspace) findings.push(finding('error', 'portable.handoff-package-v1.route.workspace-unresolved', 'Selected Handoff route owning Workspace is not carried.'));
+  else {
+    const plan = workspacePlans.find((item) => item.workspaceId === owningWorkspace.workspaceId);
+    const binding = bindingForWorkspace(descriptor, owningWorkspace.workspaceId);
+    let lineageParent = cache?.parent || owningWorkspace.parent;
+    let nextDimension = cache ? `${plan.prefix}-1-1` : `${plan.prefix}-1`;
+    const endpointChain = buildEndpointRolePointerChain({ requirements: route.materialRequirements?.endpointRoles || [], descriptor, workspaceById, cache, workspace: owningWorkspace, route, createdAt, lineageParent, nextDimension, resolveRoleMaterialTarget: roleMaterialTarget, parentAuthority: recipientV2ParentAuthority });
+    files.push(...endpointChain.files); topology.endpointRoles.push(...endpointChain.roles); findings.push(...endpointChain.findings); lineageParent = endpointChain.lineageParent; nextDimension = endpointChain.nextDimension;
+    const participantChain = buildParticipantRolePointerChain({ requirements: route.materialRequirements?.participantRoles || [], descriptor, workspaceById, cache, workspace: owningWorkspace, route, createdAt, lineageParent, nextDimension, resolveRoleMaterialTarget: roleMaterialTarget, parentAuthority: recipientV2ParentAuthority });
+    files.push(...participantChain.files); topology.participantRoles.push(...participantChain.roles); findings.push(...participantChain.findings); lineageParent = participantChain.lineageParent; nextDimension = participantChain.nextDimension;
+    const pointerPath = `${nextDimension}-handoff-pointer.trace.md`;
+    const routeEntry = (binding?.entryMap?.entries || []).find((entry) => String(entry.path || '') === String(route.workspaceRelativePath || ''));
+    const pointerFacts = {
+      workspaceId: owningWorkspace.workspaceId, workspaceArtifactPath: owningWorkspace.workspacePath, workspaceArtifactSha256: owningWorkspace.workspaceSha256,
+      archivePath: owningWorkspace.archivePath, archiveSha256: owningWorkspace.archiveSha256, sourceWorkspaceTargetInnerPath: owningWorkspace.sourceWorkspaceTargetInnerPath,
+      sourceWorkspaceTargetSha256: owningWorkspace.sourceWorkspaceTargetSha256, workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), handoffBytes: Number(routeEntry?.bytes || 0), handoffSha256: String(route.sha256 || ''), routeId: String(route.id || ''), parties: route.parties || {}, cacheArtifactPath: cache?.artifactPath || '',
+      requiredContextBindings: Object.freeze((route.requiredClosure?.requirements || []).filter((entry) => entry.state === 'qualified' && entry.resolution?.kind === 'workspace-archive-entry').map((entry) => Object.freeze({ requirementId: String(entry.requirementId || ''), name: String(entry.name || ''), referenceTarget: String(entry.referenceTarget || ''), workspaceId: String(entry.resolution?.workspaceId || ''), workspaceRelativePath: String(entry.resolution?.workspaceRelativePath || entry.resolution?.innerPath || ''), bytes: Number(entry.resolution?.bytes || 0), sha256: String(entry.resolution?.sha256 || '') })))
+    };
+    const pointer = finalizeFile({ path: pointerPath, kind: 'handoff-route-pointer', logicalKind: 'recipient-v2-package-v1-handoff-route-pointer', mediaType: 'text/markdown', transportFacts: recipientV2TransportFacts('handoff-route', pointerFacts), content: renderRecipientV2Pointer({ createdAt, parent: lineageParent, role: 'handoff-route', title: `Handoff Route Pointer — ${String(route.parties?.to || owningWorkspace.workspaceId || 'recipient')}`, summary: 'Qualified package-local Pointer to one authoritative Handoff inside one complete Workspace snapshot.', prose: 'Follow only this Pointer carrier-ancestor closure for pre-Handoff package grounding, then resolve the authoritative Handoff path against the exact bound Workspace snapshot.', currentRead: [{ label: 'Workspace Id', value: `\`${owningWorkspace.workspaceId}\`` }, { label: 'Workspace', value: `[${owningWorkspace.workspaceId}](${owningWorkspace.workspacePath})` }, { label: 'Route Id', value: `\`${String(route.id || '')}\`` }, ...(pointerFacts.cacheArtifactPath ? [{ label: 'Workspace Dependency Cache', value: `[cache](${pointerFacts.cacheArtifactPath})` }] : []), { label: 'Handoff Workspace Path', value: `\`${String(route.workspaceRelativePath || '')}\`` }], destinations: [{ label: 'Workspace snapshot containing the qualified Handoff route', display: `${owningWorkspace.archivePath} :: ${String(route.workspaceRelativePath || '')}`, target: owningWorkspace.archivePath }], facts: pointerFacts }) });
+    files.push(pointer);
+    topology.routes.push(Object.freeze({ pointerPath, workspaceId: owningWorkspace.workspaceId, workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), routeId: String(route.id || ''), sha256: String(route.sha256 || '') }));
+  }
+
+  const readFacts = { format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, packageRootPath: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, entryArtifactPath: RECIPIENT_V2_READ_PATH, artifactSurface: 'tiinex.handoff.package.v1-plus-exact-complete-workspace-snapshots', routeAuthority: 'qualified-handoff-route-pointer-plus-exact-handoff-bytes', routeSelectionAuthority: RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, siblingRouteInference: RECIPIENT_V2_SIBLING_ROUTE_INFERENCE, carrierLineage: carrier.lineage || null, pathParentProjection: true, pathAuthority: false };
+  const readFile = finalizeFile({ path: RECIPIENT_V2_READ_PATH, kind: 'handoff-recovery-pointer', logicalKind: 'recipient-v2-package-v1-recovery-orientation', mediaType: 'text/markdown', transportFacts: recipientV2TransportFacts('recovery-orientation', readFacts), content: renderRecipientV2Pointer({ createdAt, parent: packageParent, role: 'recovery-orientation', title: 'READ BEFORE PROCEEDING — Tiinex Handoff Carrier', summary: 'Qualified recovery/orientation Pointer for the package-v1 recipient carrier.', prose: 'Read this Start artifact first, qualify the declared Tooling bootstrap, then continue from the exact supplied Handoff Pointer path. Do not infer sibling routes or derive semantic authority from package placement.', currentRead: [...recipientV2EntryCurrentRead(), { label: 'Package Artifact', value: `[Handoff Package](${RECIPIENT_V2_PACKAGE_V1_ROOT_PATH})` }, { label: 'Carrier Dimension', value: `\`${String(carrier.lineage?.dimension || '001')}\`` }, ...(carrier.lineage?.parentDimension ? [{ label: 'Parent Carrier Dimension', value: `\`${String(carrier.lineage.parentDimension)}\`` }] : []), { label: 'Carrier Checkpoint', value: String(carrier.lineage?.checkpointKind || 'progression') }], destinations: [{ label: 'Handoff Package contract', target: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH }, ...(topology.bootstrap ? [{ label: 'Portable Tooling bootstrap', target: topology.bootstrap.artifactPath }] : []), ...topology.workspaces.map((workspace) => ({ label: `Workspace ${workspace.workspaceId}`, target: workspace.workspacePath })), ...topology.routes.map((item) => ({ label: `Selected Handoff route ${item.routeId || item.workspaceRelativeHandoffPath}`, target: item.pointerPath }))], facts: readFacts }) });
+  files.push(readFile); topology.read = Object.freeze({ path: readFile.path, sha256: readFile.sha256 });
+
+  for (const duplicate of duplicates(files.map((file) => file.path))) findings.push(finding('error', 'portable.handoff-package-v1.path-duplicate', 'Package v1 generated duplicate package-local paths.', { path: duplicate }));
+  for (const file of files) if (String(file.path || '').includes('/')) findings.push(finding('error', 'portable.handoff-package-v1.path-nonflat', 'Package v1 root surface must remain flat.', { path: file.path || '' }));
+  const sortedFiles = [...files].sort((a, b) => String(a.path || '').localeCompare(String(b.path || '')));
+  const bundle = { ...(input.bundle || {}), files: Object.freeze(sortedFiles), handoffClosure: null, transportFormat: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID };
+  const inspection = inspectRecipientFacingV2PackageV1(bundle);
+  return Object.freeze({ status: inspection.status === 'valid' && !findings.some((item) => item.severity === 'error') ? 'ready' : 'blocked', files: Object.freeze(sortedFiles), topology: deepFreeze(topology), inspection, findings: Object.freeze([...findings, ...(inspection.findings || [])]), boundary: 'Recipient-facing tiinex.handoff.package.v1 carrier with exact complete Workspace artifacts/snapshots, bootstrap/cache External Payload ownership retained, and no redundant Workspace External Payload or Workspace Representation companions.' });
+}
+
+function hasBootstrap(bundle = {}) { return (bundle.files || []).some((file) => String(file.path || '').startsWith('tiinex.bootstrap/')); }

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

@@ -0,0 +1,4 @@
+export const RECIPIENT_V2_PACKAGE_V1_FORMAT_ID = 'tiinex-recipient-facing-handoff-package-v1';
+export const RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID = 'tiinex.handoff.package.v1';
+export const RECIPIENT_V2_PACKAGE_V1_ROOT_PATH = '001-tiinex-handoff-package.trace.md';
+export const RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET = 'https://github.com/Tiinex/docs/blob/3988951208eb9a8926e84ab42625d4b42fa00c2d/.topics/.schemas/coordination/handoff/package/tiinex.handoff.package.v1.schema.md';