@tiinex/core 0.13.0 → 0.14.0

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

@@ -7,9 +7,9 @@ import { RECIPIENT_V2_EXTERNAL_PAYLOAD_SCHEMA_TARGET, renderRecipientV2ExternalP
 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 { buildRecipientV2BootstrapCarrier, buildRecipientV2WorkspaceCarriers, 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 { bindingForWorkspace, boundedWorkspaceClaimsDetachedRecovery, 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';
@@ -39,20 +39,33 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
   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 every complete Workspace source explicitly
-  // selected for carriage. Route closure remains selected and minimal, but an
-  // explicitly carried Workspace is not pruned merely because it is outside the
-  // selected Handoff's pre-Handoff closure. Qualified package-parent Workspaces
-  // used only as read-only requirement providers remain detached closure material.
-  const workspaceIds = [...sourceWorkspaceById.keys()].filter(Boolean).sort();
+  const descriptorBindingById = new Map((descriptor.workspaceArchiveBindings || []).map((binding) => [String(binding.workspaceId || ''), binding]));
+  const forcedMaterialWorkspaceIds = new Set([...(input.materialRepresentationWorkspaceIds || []), ...(input.genericMaterialWorkspaceIds || [])].map((value) => String(value || '')));
+  for (const binding of descriptor.workspaceArchiveBindings || []) if (String(binding.coverage || '') === 'bounded' || String(binding.representation?.kind || '') === 'bounded-workspace-snapshot') forcedMaterialWorkspaceIds.add(String(binding.workspaceId || ''));
+  const workspaceIds = [...new Set([...sourceWorkspaceById.keys(), ...descriptorBindingById.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 topology = { root: null, read: null, workspaces: [], materialRepresentations: [], caches: [], endpointRoles: [], participantRoles: [], routes: [], bootstrap: null };
   const workspaceById = new Map();
+  const directWorkspaceProjections = [];
+  const materialPlans = [];
 
   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 descriptorBinding = descriptorBindingById.get(plan.workspaceId);
+    const useMaterialRepresentation = forcedMaterialWorkspaceIds.has(plan.workspaceId);
+    if (useMaterialRepresentation) {
+      if (!descriptorBinding) { findings.push(finding('error', 'portable.handoff-package-v1.material.workspace-binding-missing', 'Generic Material Representation selection requires one qualified source Workspace representation binding.', { workspaceId: plan.workspaceId })); continue; }
+      materialPlans.push(Object.freeze({
+        ...plan, binding: descriptorBinding,
+        workspacePath: `${plan.prefix}-${plan.slug}.workspace.md`,
+        archivePath: `${plan.prefix}-${plan.slug}.workspace.zip`,
+        payloadArtifactPath: `${plan.prefix}-1-workspace-representation-payload.trace.md`,
+        representationArtifactPath: `${plan.prefix}-2-workspace-representation.trace.md`
+      }));
+      continue;
+    }
+    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; bounded material must use Material Representation Bindings.', { 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);
@@ -69,43 +82,37 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
     files.push(workspaceFile);
     const parent = recipientV2ParentAuthority(workspaceFile, 'tiinex.workspace.v1', workspaceSchemaTarget(targetQualification), createdAt);
     const sealedPrepared = sealedByWorkspaceId.get(plan.workspaceId) || null;
+    let projection;
     if (sealedPrepared) {
-      const protectedPayloadPath = `${plan.prefix}-${plan.slug}.protected.bin`;
-      const protectedPayloadDescriptorPath = `${plan.prefix}-${plan.slug}.protected-payload.trace.md`;
-      const transportEnvelopePath = `${plan.prefix}-${plan.slug}.transport-envelope.trace.md`;
-      const projection = Object.freeze({
-        workspaceId: plan.workspaceId, ordinal: plan.ordinal, workspacePath, workspaceSha256: workspaceFile.sha256,
-        snapshotKind: 'password-sealed-workspace-byte-tree', bindingState: 'sealed', protectedPayloadPath, protectedPayloadDescriptorPath, transportEnvelopePath,
-        protectedPayloadBytes: sealedPrepared.protectedPayload.byteLength, sourceWorkspaceTargetSha256: workspaceFile.sha256, sourceWorkspaceTargetBytes: workspaceFile.bytes, coverage: 'complete'
-      });
-      topology.workspaces.push(projection);
-      workspaceById.set(plan.workspaceId, { ...projection, file: workspaceFile, parent, sealed: true });
+      projection = Object.freeze({ workspaceId: plan.workspaceId, ordinal: plan.ordinal, workspacePath, workspaceSha256: workspaceFile.sha256, snapshotKind: 'password-sealed-workspace-byte-tree', bindingState: 'sealed', protectedPayloadPath: `${plan.prefix}-${plan.slug}.protected.bin`, protectedPayloadDescriptorPath: `${plan.prefix}-${plan.slug}.protected-payload.trace.md`, transportEnvelopePath: `${plan.prefix}-${plan.slug}.transport-envelope.trace.md`, protectedPayloadBytes: sealedPrepared.protectedPayload.byteLength, sourceWorkspaceTargetSha256: workspaceFile.sha256, sourceWorkspaceTargetBytes: workspaceFile.bytes, coverage: 'complete' });
     } else {
       const archivePath = `${plan.prefix}-${plan.slug}.workspace.zip`;
       const archiveFile = exactFile(archivePath, archiveData, 'recipient-v2-package-v1-complete-workspace-snapshot', 'application/zip');
       files.push(archiveFile);
-      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 });
+      projection = Object.freeze({ workspaceId: plan.workspaceId, ordinal: plan.ordinal, workspacePath, workspaceSha256: workspaceFile.sha256, archivePath, archiveSha256: archiveFile.sha256, archiveBytes: archiveFile.bytes, sourceWorkspaceTargetInnerPath: innerPath, sourceWorkspaceTargetSha256: workspaceFile.sha256, sourceWorkspaceTargetBytes: workspaceFile.bytes, coverage: 'complete' });
     }
+    topology.workspaces.push(projection); directWorkspaceProjections.push(projection);
+    workspaceById.set(plan.workspaceId, { ...projection, file: workspaceFile, parent, sealed: Boolean(sealedPrepared) });
   }
 
   if (findings.some((item) => item.severity === 'error')) return blocked('workspace-binding-blocked', findings);
-
+  const materialBindingsForContract = materialPlans.map((plan) => Object.freeze({ materialId: `workspace-${plan.workspaceId}`, workspaceId: plan.workspaceId, representationArtifactPath: plan.representationArtifactPath, carriageState: 'verified' }));
   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' : '' })
+    content: renderHandoffPackageV1({ createdAt, packageRole: input.packageRole || undefined, workspaces: directWorkspaceProjections, materialRepresentations: materialBindingsForContract, 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);
+  if (materialPlans.length) {
+    const materialWorkspaceById = buildRecipientV2WorkspaceCarriers({ workspacePlans: materialPlans, byPath: uniqueFileIndex(input.bundle?.files || [], findings), findings, createdAt, rootParent: packageParent, files, topology });
+    for (const [workspaceId, workspace] of materialWorkspaceById) workspaceById.set(workspaceId, workspace);
+    topology.materialRepresentations.push(...materialBindingsForContract);
+  }
+
 
   for (const workspace of topology.workspaces.filter((item) => item.bindingState === 'sealed')) {
     const prepared = sealedByWorkspaceId.get(workspace.workspaceId);
@@ -124,28 +131,33 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
 
   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 cachePlanByWorkspace = new Map();
+  for (const plan of workspacePlans) {
+    const workspace = workspaceById.get(plan.workspaceId);
+    if (!workspace) continue;
+    const binding = bindingForWorkspace(descriptor, workspace.workspaceId);
+    const materials = detached.filter((item) => (workspace.workspaceId === String(route.workspaceId || '') && routeClaimsDetachedMaterial(route, item)) || boundedWorkspaceClaimsDetachedRecovery(binding, item));
+    if (!materials.length) continue;
     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 cacheEntries = materials.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, sourceWorkspaceId: item.sourceWorkspaceId, sourcePath: item.sourcePath, targetWorkspaceId: item.targetWorkspaceId, targetPath: item.targetPath, originalPath: item.originalPath, archiveEntry: cacheEntries[index].path, bytes: item.bytes, sha256: item.sha256 }))
+      workspaceId: workspace.workspaceId, archivePath, archiveBytes: cacheFile.bytes, archiveSha256: cacheFile.sha256,
+      materials: materials.map((item, index) => ({ requirementId: item.requirementId, classification: item.classification, referenceTarget: item.referenceTarget, routeWorkspaceId: item.routeWorkspaceId, routePath: item.routePath, sourceRequirementId: item.sourceRequirementId, sourceWorkspaceId: item.sourceWorkspaceId, sourcePath: item.sourcePath, targetWorkspaceId: item.targetWorkspaceId, targetPath: item.targetPath, 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, materials: cacheFacts.materials }) });
+    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: workspace.parent, title: `Workspace Dependency Cache — ${workspace.workspaceId}`, summary: 'Exact route-bounded or bounded-Workspace recovery dependency bytes outside the carried Workspace representation.', label: `${workspace.workspaceId} Handoff dependency cache`, kind: 'zip export', role: 'workspace-scoped Handoff dependency cache', location: archivePath, bytes: cacheFile.bytes, sha256: cacheFile.sha256, materials: cacheFacts.materials }) });
     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) };
+    const cache = { workspaceId: workspace.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 }));
+    cachePlanByWorkspace.set(workspace.workspaceId, cache);
   }
+  const owningWorkspace = workspaceById.get(String(route.workspaceId || ''));
+  const cache = owningWorkspace ? (cachePlanByWorkspace.get(owningWorkspace.workspaceId) || null) : null;
 
   if (!owningWorkspace) findings.push(finding('error', 'portable.handoff-package-v1.route.workspace-unresolved', 'Selected Handoff route owning Workspace is not carried.'));
-  else if (owningWorkspace.sealed) findings.push(finding('error', 'portable.handoff-package-v1.route.workspace-sealed-forbidden', 'Selected authoritative Handoff route Workspace must remain a clear verified snapshot in Secure Transport V1.', { workspaceId: owningWorkspace.workspaceId }));
+  else if (owningWorkspace.sealed) findings.push(finding('error', 'portable.handoff-package-v1.route.workspace-sealed-forbidden', 'Selected authoritative Handoff route must remain inside clear qualified carried material in Secure Transport V1.', { workspaceId: owningWorkspace.workspaceId }));
   else {
     const plan = workspacePlans.find((item) => item.workspaceId === owningWorkspace.workspaceId);
     const binding = bindingForWorkspace(descriptor, owningWorkspace.workspaceId);
@@ -163,12 +175,12 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
       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 }) });
+    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 qualified carried Workspace representation.', prose: 'Follow only this Pointer carrier-ancestor closure for pre-Handoff package grounding, then resolve the authoritative Handoff path against the exact qualified carried Workspace representation.', 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 representation 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 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-qualified-carried-material', routeAuthority: 'qualified-handoff-route-pointer-plus-exact-qualified-carried-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 });
 
@@ -177,7 +189,7 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
   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.' });
+  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 direct complete Workspace bindings and/or generic complete/bounded Workspace Representation bindings; bootstrap/cache ownership is explicit and transport projection creates no semantic authority.' });
 }
 
 

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

@@ -9,23 +9,26 @@ import { normalizeHandoffCarrierProfile, normalizeWorkspaceIds } from './carrier
 
 export const HANDOFF_PACKAGE_ROLE = 'recipient-facing-handoff-carrier';
 export const WORKSPACE_PACKAGE_ROLE = 'recipient-facing-workspace-carrier';
+export const BOOTSTRAP_PACKAGE_ROLE = 'recipient-facing-bootstrap-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' });
+const PACKAGE_ROLES = Object.freeze([HANDOFF_PACKAGE_ROLE, WORKSPACE_PACKAGE_ROLE, BOOTSTRAP_PACKAGE_ROLE]);
+
+function roleProfileForRole(role = HANDOFF_PACKAGE_ROLE) {
+  return role === HANDOFF_PACKAGE_ROLE
+    ? Object.freeze({ routePlacementRule: 'authoritative-workspace-descended', continueFromRule: 'exact-package-local-handoff-pointer', preHandoffClosureRule: 'selected-pointer-carrier-ancestors', routeTransportRule: 'selected-handoff-route-instruction', recipientProjectionRule: 'qualified-handoff-to-endpoint-only' })
+    : Object.freeze({ routePlacementRule: 'none', continueFromRule: 'none', preHandoffClosureRule: 'none', routeTransportRule: 'none', recipientProjectionRule: 'none' });
 }
 
 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) => renderWorkspaceBinding(workspace)).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 packageRole = PACKAGE_ROLES.includes(String(input.packageRole || '')) ? String(input.packageRole) : HANDOFF_PACKAGE_ROLE;
+  const roleProfile = roleProfileForRole(packageRole);
+  const workspaceBlocks = (input.workspaces || []).map((workspace) => renderWorkspaceBinding(workspace)).join('\n');
+  const materialBlocks = (input.materialRepresentations || []).map((material) => renderMaterialRepresentationBinding(material)).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 carrier identity, Start/bootstrap exposure, qualified source-material bindings, route discovery when declared, and transport projection boundaries.\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## Material Representation Bindings\n\n${materialBlocks || '- none'}\n\n## Route Discovery\n\n- Route Placement Rule: ${roleProfile.routePlacementRule}\n- Continue-From Rule: ${roleProfile.continueFromRule}\n- Pre-Handoff Closure Rule: ${roleProfile.preHandoffClosureRule}\n\n## Transport Projection\n\n- Generic Transport Rule: start-artifact-instruction\n- Route Transport Rule: ${roleProfile.routeTransportRule}\n- Recipient Projection Rule: ${roleProfile.recipientProjectionRule}\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, byte integrity, Role presence, Workspace identity, or transport destination creates Handoff, recipient, holder, participation, acceptance, provenance, Parent, project membership, or work authority\n- Must Not Be Used To Claim: carrier convenience metadata overrides authoritative contained artifacts, exact qualified source bytes, or the selected Handoff To endpoint when recipient projection is permitted\n- Generic Payload Boundary: bootstrap/cache payloads retain explicit External Payload ownership when required; direct complete Workspace snapshot binding is package-local only\n- Generic Representation Boundary: independently selectable complete/bounded Workspace representation semantics remain owned by qualified tiinex.workspace.representation.v1 bindings\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`;
@@ -33,15 +36,14 @@ export function renderHandoffPackageV1(input = {}) {
 
 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);
+  const workspaces = parseWorkspaceBindings(sectionText(body, 'Workspace Snapshot Bindings'));
+  const materialRepresentations = parseMaterialRepresentationBindings(sectionText(body, 'Material Representation Bindings'));
   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'),
+    workspaces: Object.freeze(workspaces), materialRepresentations: Object.freeze(materialRepresentations),
+    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'),
+    genericTransportRule: field(sectionText(body, 'Transport Projection'), 'Generic Transport Rule'), routeTransportRule: field(sectionText(body, 'Transport Projection'), 'Route Transport Rule'), recipientProjectionRule: field(sectionText(body, 'Transport Projection'), 'Recipient Projection 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')
   });
@@ -49,36 +51,35 @@ export function parseHandoffPackageV1(markdown = '') {
 
 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 roleKnown = PACKAGE_ROLES.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: PACKAGE_ROLES.join('|'), observed: packageRole }));
+  const roleProfile = roleProfileForRole(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']
+    ['carrierKind', 'self-contained'], ['bootstrapRule', 'start-then-qualified-bootstrap'], ['routePlacementRule', roleProfile.routePlacementRule], ['continueFromRule', roleProfile.continueFromRule], ['preHandoffClosureRule', roleProfile.preHandoffClosureRule], ['genericTransportRule', 'start-artifact-instruction'], ['routeTransportRule', roleProfile.routeTransportRule], ['recipientProjectionRule', roleProfile.recipientProjectionRule], ['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.'));
   for (const binding of value?.workspaces || []) validateWorkspaceBinding(binding, findings);
+  for (const binding of value?.materialRepresentations || []) validateMaterialRepresentationBinding(binding, findings);
+  const directCount = Array.isArray(value?.workspaces) ? value.workspaces.length : 0;
+  const materialCount = Array.isArray(value?.materialRepresentations) ? value.materialRepresentations.length : 0;
+  if (packageRole === BOOTSTRAP_PACKAGE_ROLE && (directCount || materialCount)) findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-carrier.material-forbidden', 'Bootstrap-only carrier must declare no Workspace Snapshot Bindings and no Material Representation Bindings.', { directCount, materialCount }));
+  if ([WORKSPACE_PACKAGE_ROLE, HANDOFF_PACKAGE_ROLE].includes(packageRole) && !(directCount + materialCount)) findings.push(finding('error', 'portable.handoff-package-v1.source-material-bindings-missing', 'Workspace/Handoff carrier requires at least one qualified source-material binding across Workspace Snapshot Bindings and Material Representation Bindings.'));
   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 }));
-  }
+  if (value?.carrierCheckpoint === 'major' && (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.'));
 }
 
 function parseWorkspaceBindings(text = '') {
   const out = [];
   const re = /^-\s+([^\n]+)\n((?:\s{2}-\s+[^\n]+\n?)*)/gm;
   for (const match of String(text || '').matchAll(re)) {
+    if (String(match[1] || '').trim().toLowerCase() === 'none') continue;
     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 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);
@@ -100,6 +101,24 @@ function parseWorkspaceBindings(text = '') {
   return out.map((item) => Object.freeze({ ...item, byteSize: item.byteSize ?? null }));
 }
 
+function parseMaterialRepresentationBindings(text = '') {
+  const out = [];
+  const re = /^-\s+([^\n]+)\n((?:\s{2}-\s+[^\n]+\n?)*)/gm;
+  for (const match of String(text || '').matchAll(re)) {
+    if (String(match[1] || '').trim().toLowerCase() === 'none') continue;
+    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 === 'Material Id') current.materialId = value;
+      else if (key === 'Workspace Representation') current.workspaceRepresentationPath = markdownTarget(value);
+      else if (key === 'Carriage State') current.carriageState = value;
+      else if (key === 'Notes') current.notes = value;
+    }
+    out.push(current);
+  }
+  return out.map((item) => Object.freeze({ ...item }));
+}
 
 function renderWorkspaceBinding(workspace = {}) {
   const sealed = String(workspace.snapshotKind || '') === 'password-sealed-workspace-byte-tree' || String(workspace.bindingState || '') === 'sealed';
@@ -107,6 +126,12 @@ function renderWorkspaceBinding(workspace = {}) {
   return `- ${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: $/, '');
 }
 
+function renderMaterialRepresentationBinding(material = {}) {
+  const id = String(material.materialId || material.workspaceId || 'material');
+  const path = String(material.workspaceRepresentationPath || material.representationArtifactPath || '');
+  return `- ${id}\n  - Material Id: ${id}\n  - Workspace Representation: [${id} Workspace Representation](${path})\n  - Carriage State: ${String(material.carriageState || 'verified')}${material.notes ? `\n  - Notes: ${String(material.notes)}` : ''}`;
+}
+
 function validateWorkspaceBinding(binding = {}, findings = []) {
   const workspaceId = String(binding.workspaceId || '');
   if (!workspaceId || !binding.workspaceArtifactPath || String(binding.coverage || '') !== 'complete') findings.push(finding('error', 'portable.handoff-package-v1.workspace-binding-common-invalid', 'Workspace binding requires Workspace Id, Workspace Artifact, and complete coverage.', { workspaceId }));
@@ -124,7 +149,8 @@ function validateWorkspaceBinding(binding = {}, findings = []) {
   findings.push(finding('error', 'portable.handoff-package-v1.workspace-binding-kind-invalid', 'Workspace binding Snapshot Kind is unsupported.', { workspaceId, snapshotKind: kind }));
 }
 
-function normalizeProfileId(value = '') {
-  const text = String(value || '').trim();
-  return text.toLowerCase() === 'none' ? '' : text;
+function validateMaterialRepresentationBinding(binding = {}, findings = []) {
+  if (!String(binding.materialId || '').trim() || !String(binding.workspaceRepresentationPath || '').trim() || !['verified', 'unresolved'].includes(String(binding.carriageState || ''))) findings.push(finding('error', 'portable.handoff-package-v1.material-representation-binding-invalid', 'Material Representation binding requires Material Id, Workspace Representation link, and closed-domain Carriage State.', { materialId: String(binding.materialId || ''), carriageState: String(binding.carriageState || '') }));
 }
+
+function normalizeProfileId(value = '') { const text = String(value || '').trim(); return text.toLowerCase() === 'none' ? '' : text; }

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

@@ -1,8 +1,9 @@
 import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
-import { parseRecipientV2ExternalPayload, parseRecipientV2Pointer } from './recipientV2.artifacts.js';
+import { parseRecipientV2ExternalPayload, parseRecipientV2Pointer, parseRecipientV2WorkspaceRepresentation } 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 { recipientEntriesFingerprint } from './recipientV2.topology.helpers.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';
@@ -62,16 +63,15 @@ export function deriveVisibleFacts({ file = null, markdown = '', schemaId = '',
     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 === 'recovery-orientation') { const routed = String(packageContract?.packageRole || '') === 'recipient-facing-handoff-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: routed ? 'qualified-handoff-route-pointer-plus-exact-handoff-bytes' : 'none', routeSelectionAuthority: routed ? RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY : 'none', siblingRouteInference: routed ? RECIPIENT_V2_SIBLING_ROUTE_INFERENCE : false }; }
     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 direct = directWorkspaceClosure(index, packageContract, workspaceId);
+      const generic = direct ? null : genericWorkspaceClosure(index, packageContract, { workspaceId });
+      const closure = direct || generic;
+      const handoffEntry = (closure?.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([]) };
+      return { ...base, workspaceId, workspaceArtifactPath: closure?.workspaceFile?.path || '', workspaceArtifactSha256: closure?.workspaceFile ? sha256Hex(packageFileBytes(closure.workspaceFile)) : '', archivePath: closure?.archiveFile?.path || '', archiveSha256: closure?.archiveFile ? sha256Hex(packageFileBytes(closure.archiveFile)) : '', sourceWorkspaceTargetInnerPath: closure?.workspaceArtifactInnerPath || '', sourceWorkspaceTargetSha256: closure?.sourceWorkspaceTargetSha256 || '', 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 || '';
@@ -90,17 +90,70 @@ export function deriveVisibleFacts({ file = null, markdown = '', schemaId = '',
     const workspaceId = (packageContract?.workspaces || []).find((item) => item.transportEnvelopePath === file?.path)?.workspaceId || '';
     return { factsFormat: 'portable-recipient-v2', factsVersion: 1, role: TRANSPORT_ENVELOPE_V1_ROLE, workspaceId: String(workspaceId || ''), workspaceArtifactPath: visible.workspaceArtifactPath, protectedPayloadDescriptorPath: visible.protectedPayloadDescriptorPath, workspaceBindingValue: visible.workspaceBindingValue, profileId: visible.profile?.profileId || '', profileVersion: Number(visible.profile?.profileVersion || 0) };
   }
+  if (schemaId === 'tiinex.workspace.v1') {
+    const generic = genericWorkspaceClosure(index, packageContract, { workspaceArtifactPath: file?.path });
+    if (!generic) return null;
+    const entries = generic.parsed?.entries || [];
+    const totalBytes = entries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0);
+    return { factsFormat: 'portable-recipient-v2', factsVersion: 1, role: 'workspace-node', workspaceId: generic.workspaceId, archivePath: generic.archiveFile?.path || '', archiveBytes: generic.archiveFile ? packageFileBytes(generic.archiveFile).byteLength : 0, archiveSha256: generic.archiveFile ? sha256Hex(packageFileBytes(generic.archiveFile)) : '', representationArtifactPath: generic.representationFile?.path || '', payloadArtifactPath: generic.payloadFile?.path || '', sourceWorkspaceTargetInnerPath: generic.workspaceArtifactInnerPath || '', sourceWorkspaceTargetBytes: Number(generic.sourceWorkspaceTargetBytes || 0), sourceWorkspaceTargetSha256: generic.sourceWorkspaceTargetSha256 || '', entryCount: entries.length, totalBytes, entriesFingerprint: recipientEntriesFingerprint(entries), coverage: generic.representation?.coverage || '', coverageState: generic.representation?.bindingState === 'verified' ? 'qualified' : 'unresolved', completenessState: generic.representation?.coverage === 'complete' && generic.representation?.bindingState === 'verified' ? 'qualified' : '', archiveCodec: 'deterministic-stored-zip', providerKind: 'package-local-stored-zip-v1' };
+  }
+  if (schemaId === 'tiinex.workspace.representation.v1') {
+    const generic = genericWorkspaceClosure(index, packageContract, { representationArtifactPath: file?.path });
+    if (!generic) return null;
+    const entries = generic.parsed?.entries || [];
+    return { factsFormat: 'portable-recipient-v2', factsVersion: 1, role: 'workspace-representation', workspaceId: generic.workspaceId, workspaceArtifactPath: generic.workspaceFile?.path || '', payloadArtifactPath: generic.payloadFile?.path || '', sourceWorkspaceTargetInnerPath: generic.workspaceArtifactInnerPath || '', archivePath: generic.archiveFile?.path || '', archiveSha256: generic.archiveFile ? sha256Hex(packageFileBytes(generic.archiveFile)) : '', entryCount: entries.length, entriesFingerprint: recipientEntriesFingerprint(entries), coverage: generic.representation?.coverage || '', coverageState: generic.representation?.bindingState === 'verified' ? 'qualified' : 'unresolved', completenessState: generic.representation?.coverage === 'complete' && generic.representation?.bindingState === 'verified' ? 'qualified' : '' };
+  }
   if (schemaId === 'tiinex.external.payload.v1') {
     const visible = parseRecipientV2ExternalPayload(markdown);
-    const role = String(visible.payloadRole || '');
+    const rawRole = String(visible.payloadRole || '');
+    const role = /workspace archive representation payload$/i.test(rawRole) ? 'workspace-representation-payload' : rawRole;
     const parent = parentTraceFromMarkdown(markdown);
-    const workspaceId = String(visible.workspaceId || '') || (packageContract?.workspaces || []).find((item) => item.workspaceArtifactPath === parent)?.workspaceId || '';
+    const genericParent = genericWorkspaceClosure(index, packageContract, { workspaceArtifactPath: parent });
+    const workspaceId = String(visible.workspaceId || '') || (packageContract?.workspaces || []).find((item) => item.workspaceArtifactPath === parent)?.workspaceId || genericParent?.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 directWorkspaceClosure(index, packageContract, workspaceId) {
+  const binding = (packageContract?.workspaces || []).find((item) => String(item.workspaceId || '') === String(workspaceId || '')) || null;
+  if (!binding || String(binding.snapshotKind || '') !== 'exact-workspace-byte-tree-archive') return null;
+  const archiveFile = oneFile(index, binding.snapshotPath);
+  const workspaceFile = oneFile(index, binding.workspaceArtifactPath);
+  const parsed = archiveFile ? inspectStoredWorkspaceArchive(packageFileBytes(archiveFile), { ownedBytes: true }) : null;
+  return archiveFile && workspaceFile && parsed ? { workspaceId: String(binding.workspaceId || ''), workspaceFile, archiveFile, parsed, workspaceArtifactInnerPath: String(binding.workspaceArtifactInnerPath || ''), sourceWorkspaceTargetSha256: sha256Hex(packageFileBytes(workspaceFile)) } : null;
+}
+
+function genericWorkspaceClosure(index, packageContract, selector = {}) {
+  for (const binding of packageContract?.materialRepresentations || []) {
+    const representationFile = oneFile(index, binding.workspaceRepresentationPath);
+    if (!representationFile) continue;
+    const representation = parseRecipientV2WorkspaceRepresentation(decodeUtf8(packageFileBytes(representationFile)));
+    if (selector.representationArtifactPath && String(representationFile.path || '') !== String(selector.representationArtifactPath)) continue;
+    const workspaceFile = oneFile(index, representation.workspaceArtifactPath);
+    const payloadFile = oneFile(index, representation.payloadArtifactPath);
+    if (!workspaceFile || !payloadFile) continue;
+    if (selector.workspaceArtifactPath && String(workspaceFile.path || '') !== String(selector.workspaceArtifactPath)) continue;
+    const workspaceMarkdown = decodeUtf8(packageFileBytes(workspaceFile));
+    const workspaceId = workspaceIdFromCarrierWorkspaceMarkdown(workspaceMarkdown);
+    if (selector.workspaceId && workspaceId !== String(selector.workspaceId || '')) continue;
+    const payload = parseRecipientV2ExternalPayload(decodeUtf8(packageFileBytes(payloadFile)));
+    const archiveFile = oneFile(index, payload.location);
+    const parsed = archiveFile ? inspectStoredWorkspaceArchive(packageFileBytes(archiveFile), { ownedBytes: true }) : null;
+    if (!archiveFile || !parsed) continue;
+    const target = (parsed.entries || []).find((entry) => String(entry.path || '') === String(representation.workspaceArtifactInnerPath || '')) || null;
+    return { binding, workspaceId, representationFile, representation, workspaceFile, payloadFile, payload, archiveFile, parsed, workspaceArtifactInnerPath: String(representation.workspaceArtifactInnerPath || ''), sourceWorkspaceTargetBytes: Number(target?.bytes || 0), sourceWorkspaceTargetSha256: String(target?.sha256 || '') };
+  }
+  return null;
+}
+
+function workspaceIdFromCarrierWorkspaceMarkdown(markdown = '') {
+  const summary = String(markdown).match(/^\s*-\s+Summary:\s+Package-local Workspace node for\s+(.+?);/mi)?.[1]?.trim();
+  if (summary) return summary;
+  return String(markdown).match(/^#\s+(.+?)\s+—\s+Handoff Workspace\s*$/m)?.[1]?.trim() || '';
+}
+
 function workspaceIdForRoute(index = new Map(), routeId = '') {
   const targetRouteId = String(routeId || '');
   if (!targetRouteId) return '';