@tiinex/core 0.13.0 → 0.14.0

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

@@ -14,9 +14,10 @@ import { indexRecipientFiles, recipientWorkspaceDescriptor, virtualCacheMaterial
 import { inspectPortableToolingBootstrap } from './toolingBootstrap.js';
 import { projectRecipientV2EndpointRoles, projectRecipientV2ParticipantRoles, projectRecipientV2Routes } from './recipientV2.inspect.projection.js';
 import { RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID } from './recipientV2.packageV1.constants.js';
-import { parseHandoffPackageV1, validatePackageFields, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
+import { BOOTSTRAP_PACKAGE_ROLE, HANDOFF_PACKAGE_ROLE, parseHandoffPackageV1, validatePackageFields, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
 import { deriveVisibleFacts, validateRouteClosure } from './recipientV2.packageV1.inspect.helpers.js';
-import { workspaceCarrierProjection } from './recipientV2.packageV1.workspaceProjection.js';
+import { bootstrapCarrierProjection, workspaceCarrierProjection } from './recipientV2.packageV1.workspaceProjection.js';
+import { inspectRecipientV2WorkspaceSurface } from './recipientV2.inspect.workspaces.js';
 import { byteEqual, currentSchemaId, decodeUtf8, dedupeFindings, deepFreeze, oneFile } from './recipientV2.packageV1.shared.js';
 import { parseTransportEnvelopeV1, qualifyTransportEnvelopeV1Artifact, TRANSPORT_ENVELOPE_V1_ROLE, TRANSPORT_ENVELOPE_V1_SCHEMA_ID } from './transportEnvelopeV1.js';
 
@@ -85,7 +86,6 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
       if (String(payloadArtifact.facts?.workspaceId || '') && String(payloadArtifact.facts.workspaceId) !== String(binding.workspaceId || '')) findings.push(finding('error', 'portable.handoff-package-v1.workspace-sealed-payload-workspace-mismatch', 'Protected payload descriptor Workspace Id diverges from package binding.', { workspaceId: binding.workspaceId }));
       workspaceParts.push({ workspaceId: binding.workspaceId, bindingState: 'sealed', artifact: Object.freeze({ path: workspaceFile.path, sha256: sha256Hex(workspaceData), markdown: workspaceMarkdown }), facts: { workspaceId: binding.workspaceId, sourceWorkspaceTargetInnerPath: '', sourceWorkspaceTargetSha256: sha256Hex(workspaceData) }, archiveFile: null, archive: null, targetQualification: null, protectedPayloadArtifact: payloadArtifact, protectedPayloadFile: payloadFile, transportEnvelopeArtifact: envelopeArtifact });
       sealedWorkspaceBindings.push(Object.freeze({ workspaceId: binding.workspaceId, workspaceArtifactPath: binding.workspaceArtifactPath, workspaceArtifactSha256: sha256Hex(workspaceData), protectedPayloadDescriptorPath: binding.protectedPayloadDescriptorPath, protectedPayloadPath: payload.location, protectedPayloadSha256: payload.integrityValue, protectedPayloadBytes: protectedBytes.byteLength, transportEnvelopePath: binding.transportEnvelopePath, envelope }));
-      virtualWorkspaceTargets.push(workspaceFile);
       continue;
     }
 
@@ -107,16 +107,36 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
     const descriptorPart = recipientWorkspaceDescriptor({ workspaceId: binding.workspaceId, facts: { providerKind: 'package-local-stored-zip-v1' }, representation: { workspaceArtifactInnerPath: binding.workspaceArtifactInnerPath, coverage: 'complete' }, payload: { location: binding.snapshotPath }, entries: parsed.entries || [], targetMarkdown: workspaceMarkdown, targetPackagePath: binding.workspaceArtifactPath, targetFile: { bytes: workspaceData.byteLength, sha256: sha256Hex(workspaceData) }, archiveFile: { path: archiveFile.path, bytes: archiveData.byteLength, sha256: archiveSha } });
     workspaceDescriptors.push(descriptorPart);
     workspaceParts.push({ workspaceId: binding.workspaceId, bindingState: 'verified', artifact: Object.freeze({ path: workspaceFile.path, sha256: sha256Hex(workspaceData), markdown: workspaceMarkdown }), facts: { workspaceId: binding.workspaceId, sourceWorkspaceTargetInnerPath: binding.workspaceArtifactInnerPath, sourceWorkspaceTargetSha256: sha256Hex(workspaceData) }, archiveFile, archive: { archive: parsed, sha256: archiveSha }, targetQualification });
-    virtualWorkspaceTargets.push(workspaceFile);
   }
 
   const payloadArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.external.payload.v1' && item.status === 'qualified');
   const bootstrapArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'portable Tooling bootstrap runtime for recipient orientation and verification');
   const cacheArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-scoped Handoff dependency cache');
   const protectedWorkspacePayloadArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'password-sealed Workspace protected payload');
-  const forbiddenWorkspacePayloads = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-representation-payload');
-  if (forbiddenWorkspacePayloads.length) findings.push(finding('error', 'portable.handoff-package-v1.workspace-payload-redundant', 'Complete package-local Workspace bindings must not carry redundant Workspace External Payload companions.', { count: forbiddenWorkspacePayloads.length }));
-  if (generatedArtifacts.some((item) => item.schemaId === 'tiinex.workspace.representation.v1' || item.schemaId === 'tiinex.relation.v1')) findings.push(finding('error', 'portable.handoff-package-v1.workspace-representation-redundant', 'Complete package-local Workspace bindings must not carry redundant Workspace Representation/Relation companions.'));
+  const genericWorkspaceArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.workspace.v1' && item.facts?.role === 'workspace-node');
+  const genericRepresentationArtifacts = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.workspace.representation.v1');
+  const genericWorkspacePayloadArtifacts = payloadArtifacts.filter((item) => item.facts?.role === 'workspace-representation-payload');
+  if (generatedArtifacts.some((item) => item.schemaId === 'tiinex.relation.v1')) findings.push(finding('error', 'portable.handoff-package-v1.relation-unowned', 'Package-v1 material carriage is selected through Workspace Representation bindings; detached Relation companions are not package-owned carrier truth.'));
+  const genericMaterialSurface = inspectRecipientV2WorkspaceSurface({
+    generatedArtifacts: [...genericWorkspaceArtifacts, ...genericRepresentationArtifacts, ...genericWorkspacePayloadArtifacts],
+    rootArtifact: null, index, findings, transportManifest: { identityByPath: new Map() }
+  });
+  const materialBindings = packageContract?.materialRepresentations || [];
+  const materialPartsByRepresentation = new Map((genericMaterialSurface.workspaceParts || []).map((part) => [String(part.representationArtifact?.path || ''), part]));
+  const selectedMaterialRepresentationPaths = new Set();
+  for (const binding of materialBindings) {
+    const representationPath = String(binding.workspaceRepresentationPath || '');
+    if (selectedMaterialRepresentationPaths.has(representationPath)) findings.push(finding('error', 'portable.handoff-package-v1.material-representation-binding-duplicate', 'Each carried Workspace Representation may be selected at most once by Material Representation Bindings.', { path: representationPath }));
+    selectedMaterialRepresentationPaths.add(representationPath);
+    const part = materialPartsByRepresentation.get(representationPath) || null;
+    if (!part) { findings.push(finding('error', 'portable.handoff-package-v1.material-representation-unresolved', 'Material Representation binding must resolve to one qualified carried tiinex.workspace.representation.v1 closure.', { materialId: binding.materialId || '', path: representationPath })); continue; }
+    if (String(binding.carriageState || '') !== 'verified') findings.push(finding('error', 'portable.handoff-package-v1.material-representation-unverified', 'A package ready for source-material use requires Carriage State verified.', { materialId: binding.materialId || '', carriageState: binding.carriageState || '' }));
+    if (String(part.representation?.bindingState || '') !== 'verified' || !['complete', 'bounded'].includes(String(part.representation?.coverage || '')) || part.targetQualification?.state !== 'qualified') findings.push(finding('error', 'portable.handoff-package-v1.material-representation-provider-unqualified', 'Selected Workspace Representation must independently qualify as a clear provider-ready complete/bounded binding.', { materialId: binding.materialId || '', workspaceId: part.workspaceId || '', coverage: part.representation?.coverage || '', bindingState: part.representation?.bindingState || '' }));
+  }
+  for (const part of genericMaterialSurface.workspaceParts || []) if (!selectedMaterialRepresentationPaths.has(String(part.representationArtifact?.path || ''))) findings.push(finding('error', 'portable.handoff-package-v1.material-representation-unselected', 'Carried generic Workspace Representation closure must be selected by exactly one Material Representation Binding.', { path: part.representationArtifact?.path || '', workspaceId: part.workspaceId || '' }));
+  workspaceParts.push(...(genericMaterialSurface.workspaceParts || []));
+  workspaceDescriptors.push(...(genericMaterialSurface.workspaceDescriptors || []));
+  virtualWorkspaceTargets.push(...(genericMaterialSurface.virtualWorkspaceTargetFiles || []));
 
   let bootstrapInspection = null;
   if (packageContract?.bootstrapPath) {
@@ -149,7 +169,7 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
   const virtualCache = { files: Object.freeze(virtualCacheParts.flatMap((item) => item.files || [])), materialized: Object.freeze(virtualCacheParts.flatMap((item) => item.materialized || [])) };
 
   const descriptor = deepFreeze({ schema: 'tiinex.transport.handoff-material-closure-descriptor.v2', version: 2, workspaceMaterializations: Object.freeze(workspaceDescriptors.map((item) => item.workspace)), workspaceArchiveBindings: Object.freeze(workspaceDescriptors.map((item) => item.binding)), materialized: Object.freeze(virtualCache.materialized), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]), endpointRoles: Object.freeze([]), participantRoles: Object.freeze([]), dependencies: Object.freeze([]) }) });
-  const semanticBundle = { ...bundle, files: Object.freeze([...files, ...virtualCache.files]) };
+  const semanticBundle = { ...bundle, files: Object.freeze([...files, ...virtualWorkspaceTargets, ...virtualCache.files]) };
   const workspaceByteProvider = buildHandoffWorkspaceByteProvider(semanticBundle, descriptor);
   findings.push(...(workspaceByteProvider.findings || []));
 
@@ -157,9 +177,19 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
   const endpointRolePointers = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'endpoint-role' && item.status === 'qualified');
   const participantRolePointers = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'participant-role' && item.status === 'qualified');
   const lineage = packageContract ? Object.freeze({ dimension: packageContract.carrierDimension, parentDimension: packageContract.parentCarrierDimension, checkpointKind: packageContract.carrierCheckpoint, majorReason: packageContract.majorReason || '' }) : null;
-  const workspaceMode = String(packageContract?.packageRole || '') === WORKSPACE_PACKAGE_ROLE;
+  const packageRole = String(packageContract?.packageRole || '');
+  const workspaceMode = packageRole === WORKSPACE_PACKAGE_ROLE;
+  const bootstrapMode = packageRole === BOOTSTRAP_PACKAGE_ROLE;
+  const carriedWorkspaceIds = new Set([...workspaceParts.map((part) => String(part.workspaceId || '').toLowerCase()), ...sealedWorkspaceBindings.map((part) => String(part.workspaceId || '').toLowerCase())].filter(Boolean));
+  if (packageContract?.carrierCheckpoint === 'major') {
+    const missingMajorWorkspaceIds = (packageContract.requiredMajorWorkspaceIds || []).filter((workspaceId) => !carriedWorkspaceIds.has(String(workspaceId || '').toLowerCase()));
+    if (missingMajorWorkspaceIds.length) findings.push(finding('error', 'portable.handoff-package-v1.major-source-closure-incomplete', 'Major package-v1 carrier is missing one or more Workspace source-material bindings required by its explicit carrier profile.', { carrierProfileId: String(packageContract.carrierProfileId || ''), missingWorkspaceIds: missingMajorWorkspaceIds }));
+  }
   let carrierProjection;
-  if (workspaceMode) {
+  if (bootstrapMode) {
+    if (workspaceParts.length || sealedWorkspaceBindings.length || routePointers.length || endpointRolePointers.length || participantRolePointers.length || caches.length) findings.push(finding('error', 'portable.handoff-package-v1.bootstrap-carrier.semantic-surface-present', 'Bootstrap-only carrier must not expose Workspace/material provider, Handoff route, Role pointer, or Handoff cache semantics.', { workspaces: workspaceParts.length, sealedWorkspaces: sealedWorkspaceBindings.length, routes: routePointers.length, endpointRoles: endpointRolePointers.length, participantRoles: participantRolePointers.length, caches: caches.length }));
+    carrierProjection = bootstrapCarrierProjection(lineage, bootstrapInspection?.status === 'valid');
+  } else if (workspaceMode) {
     if (routePointers.length || endpointRolePointers.length || participantRolePointers.length || caches.length) findings.push(finding('error', 'portable.handoff-package-v1.workspace-carrier.handoff-surface-present', 'Pointerless Workspace carrier must not expose Handoff route, Role pointer, or Handoff cache carriers.', { routes: routePointers.length, endpointRoles: endpointRolePointers.length, participantRoles: participantRolePointers.length, caches: caches.length }));
     carrierProjection = workspaceCarrierProjection(workspaceParts, lineage);
   } else {
@@ -196,6 +226,7 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
     packageFile?.path,
     packageContract?.startPath,
     ...(bindings || []).flatMap((binding) => [binding.workspaceArtifactPath, binding.snapshotPath, binding.protectedPayloadDescriptorPath, binding.transportEnvelopePath]),
+    ...(genericMaterialSurface.workspaceParts || []).flatMap((part) => [part.artifact?.path, part.representationArtifact?.path, part.payloadArtifact?.path, part.archiveFile?.path]),
     ...protectedWorkspacePayloadArtifacts.flatMap((artifact) => [artifact.path, parseRecipientV2ExternalPayload(artifact.markdown).location]),
     ...generatedArtifacts.filter((item) => ['recovery-orientation', 'handoff-route', 'endpoint-role', 'participant-role'].includes(String(item.facts?.role || ''))).map((item) => item.path),
     ...bootstrapArtifacts.flatMap((artifact) => [artifact.path, parseRecipientV2ExternalPayload(artifact.markdown).location]),
@@ -212,12 +243,12 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
   return deepFreeze({
     schema: 'tiinex.portable.recipient-facing-handoff-package-v1.inspection.v1', detected: Boolean(packageFile), status, format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID,
     rootArtifact: packageFile ? Object.freeze({ path: packageFile.path, schemaId: RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, sha256: sha256Hex(packageFileBytes(packageFile)), carrierLineage: lineage }) : null,
-    readArtifact, workspaces: Object.freeze(workspaceParts.map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: 'complete', bindingState: item.bindingState || 'verified', workspaceArtifactPath: item.artifact.path, workspaceArchivePath: item.archiveFile?.path || '', sourceWorkspaceTargetInnerPath: item.facts.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.facts.sourceWorkspaceTargetSha256 }))), sealedWorkspaces: Object.freeze(sealedWorkspaceBindings),
+    readArtifact, workspaces: Object.freeze(workspaceParts.map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: String(item.representation?.coverage || item.facts?.coverage || 'complete'), bindingState: item.bindingState || String(item.representation?.bindingState || 'verified'), workspaceArtifactPath: item.artifact.path, workspaceArchivePath: item.archiveFile?.path || '', sourceWorkspaceTargetInnerPath: item.facts.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.facts.sourceWorkspaceTargetSha256 }))), sealedWorkspaces: Object.freeze(sealedWorkspaceBindings),
     routes: projectRecipientV2Routes(routePointers, endpointRolePointers, participantRolePointers), endpointRoles: projectRecipientV2EndpointRoles(endpointRolePointers), participantRoles: projectRecipientV2ParticipantRoles(participantRolePointers),
     caches: Object.freeze(caches.map((cache) => Object.freeze({ workspaceId: String(cache.facts?.workspaceId || ''), artifactPath: cache.artifact.path, archivePath: cache.file.path, materials: cache.facts.materials || [] }))),
     bootstrapInspection, transportManifest: null, artifactFacts: Object.freeze(generatedArtifacts.map((item) => Object.freeze({ path: item.path, facts: item.facts }))), descriptor, workspaceByteProvider, carrierProjection, coldConsumerProjection,
     packageContract, findings: Object.freeze(finalFindings), findingSummary: Object.freeze({ errors: finalFindings.filter((item) => item.severity === 'error').length, findings: finalFindings.length }),
-    boundary: 'Read-only qualification of tiinex.handoff.package.v1: visible package identity/discovery and complete package-local Workspace bindings are reverified from exact bytes; derived inventories have no authority.'
+    boundary: 'Read-only qualification of tiinex.handoff.package.v1: visible package identity/discovery, direct complete Workspace bindings, generic complete/bounded Workspace Representation bindings, and bootstrap/route projection rules are reverified from exact bytes; derived inventories have no authority.'
   });
 }
 
@@ -239,14 +270,22 @@ function qualifyParentBoundaryCacheRequirementIds(caches = [], workspaceByteProv
     const requirementId = String(item.requirementId || '');
     const routeWorkspaceId = String(item.routeWorkspaceId || '');
     const routePath = normalizeWorkspacePath(item.routePath || '');
-    const sourceWorkspaceId = String(item.sourceWorkspaceId || '');
-    const sourcePath = normalizeWorkspacePath(item.sourcePath || '');
+    const sourceWorkspaceId = String(item.sourceWorkspaceId || routeWorkspaceId || '');
+    const sourcePath = normalizeWorkspacePath(item.sourcePath || routePath || '');
     const targetWorkspaceId = String(item.targetWorkspaceId || '');
     const targetPath = normalizeWorkspacePath(item.targetPath || item.originalPath || '');
     const referenceTarget = String(item.referenceTarget || '').trim();
     const routeQualified = (carrierProjection.routes || []).some((route) => String(route.state || '') === 'qualified' && String(route.workspaceId || '') === routeWorkspaceId && normalizeWorkspacePath(route.workspaceRelativePath || '') === routePath);
+    const sourceRequirementId = String(item.sourceRequirementId || '');
+    const sourceWorkspace = (workspaceByteProvider.workspaces || []).find((workspace) => String(workspace.id || '') === sourceWorkspaceId) || null;
+    const boundedRecoveryQualified = Boolean(
+      sourceRequirementId.startsWith(`bounded-workspace:${sourceWorkspaceId}:`) &&
+      routeWorkspaceId === sourceWorkspaceId && routePath === sourcePath &&
+      String(sourceWorkspace?.materialization?.materialization || '') === 'bounded' &&
+      sourceWorkspace?.state === 'qualified'
+    );
     let reason = '';
-    if (!requirementId || !routeQualified || !sourceWorkspaceId || !sourcePath || !targetWorkspaceId || !targetPath || !referenceTarget || !candidate.entry) reason = 'parent-boundary-visible-facts-incomplete';
+    if (!requirementId || (!routeQualified && !boundedRecoveryQualified) || !sourceWorkspaceId || !sourcePath || !targetWorkspaceId || !targetPath || !referenceTarget || !candidate.entry) reason = 'parent-boundary-visible-facts-incomplete';
     if (!reason && targetIndex.get(candidate.targetKey)?.length !== 1) reason = 'parent-boundary-target-ambiguous';
     if (!reason) {
       const alreadyCarried = resolveHandoffWorkspaceEntry(workspaceByteProvider, targetWorkspaceId, targetPath);
@@ -276,7 +315,7 @@ function qualifyParentBoundaryCacheRequirementIds(caches = [], workspaceByteProv
       }
     }
     if (reason) findings.push(finding('error', 'portable.handoff-package-v1.cache-parent-boundary-unqualified', 'Workspace dependency cache Parent-boundary material is not independently justified by the selected route declared Parent chain.', { requirementId, reason }));
-    else allowed.add(requirementId);
+    else { allowed.add(requirementId); if (sourceRequirementId) allowed.add(sourceRequirementId); }
   }
   return allowed;
 }

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

@@ -1,4 +1,4 @@
-import { WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
+import { BOOTSTRAP_PACKAGE_ROLE, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
 import { deepFreeze } from './recipientV2.packageV1.shared.js';
 
 export function workspaceCarrierProjection(workspaceParts = [], lineage = null) {
@@ -20,3 +20,16 @@ export function workspaceCarrierProjection(workspaceParts = [], lineage = null)
     findings: Object.freeze([])
   });
 }
+
+export function bootstrapCarrierProjection(lineage = null, bootstrapQualified = false) {
+  return deepFreeze({
+    schema: 'tiinex.portable.handoff-carrier-projection.v1', version: 1,
+    status: bootstrapQualified ? 'ready' : 'blocked', mode: 'bootstrap', lineage,
+    workspaces: Object.freeze([]),
+    workspace: Object.freeze({ id: '', title: '', slug: '', qualification: 'unresolved' }),
+    selection: Object.freeze({ policy: 'none', qualifiedRouteCount: 0, implicitRouteId: '', packageRole: BOOTSTRAP_PACKAGE_ROLE }),
+    routes: Object.freeze([]),
+    authority: Object.freeze({ semanticAuthority: 'none', filenameAuthority: false, dimensionalParentAuthority: false, routeSelectionAuthority: 'none', holderAuthority: 'none', workAuthority: 'none' }),
+    findings: Object.freeze([])
+  });
+}

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

@@ -15,6 +15,7 @@ import { buildRecipientFacingV2PackageV1 } from './recipientV2.packageV1.js';
 import { buildEndpointRolePointerChain, buildParticipantRolePointerChain } from './recipientV2.endpointRolePointers.js';
 import {
   bindingForWorkspace,
+  boundedWorkspaceClaimsDetachedRecovery,
   deepFreeze,
   detachedMaterial,
   duplicates,
@@ -46,9 +47,6 @@ export function buildRecipientFacingV2Topology(input = {}) {
   if (input.legacyRecipientV2Compatibility === true) return sourceSurface;
   if (input.artifactFirstDualProjectionPhase1 === true) return buildRecipientFacingV2ArtifactFirstPhase1({ ...input, sourceSurface });
   if (input.artifactFirstCleanCarrierPhase2 === true) return buildRecipientFacingV2ArtifactFirstPhase2Clean({ ...input, sourceSurface });
-  const hasIndependentBoundedWorkspaceRepresentation = (input.descriptor?.workspaceArchiveBindings || input.bundle?.handoffClosure?.workspaceArchiveBindings || [])
-    .some((binding) => String(binding.coverage || '') === 'bounded' || String(binding.representation?.kind || '') === 'bounded-workspace-snapshot');
-  if (hasIndependentBoundedWorkspaceRepresentation) return buildRecipientFacingV2ArtifactFirstPhase2Clean({ ...input, sourceSurface });
   const explicitRouteSelector = String(input.routeSelector || input.routeId || '').trim();
   if (!explicitRouteSelector && (sourceSurface.topology?.routes || []).length > 1) return sourceSurface;
   return buildRecipientFacingV2PackageV1({ ...input, sourceSurface });
@@ -145,7 +143,8 @@ function buildRecipientFacingV2TopologyLegacy(input = {}) {
     const workspace = workspaceById.get(workspacePlan.workspaceId);
     if (!workspace) continue;
     const workspaceRoutes = routePlans.filter((plan) => plan.workspace.workspaceId === workspace.workspaceId);
-    const materials = detached.filter((item) => workspaceRoutes.some((plan) => routeClaimsDetachedMaterial(plan.route, item)));
+    const binding = bindingForWorkspace(descriptor, workspace.workspaceId);
+    const materials = detached.filter((item) => workspaceRoutes.some((plan) => routeClaimsDetachedMaterial(plan.route, item)) || boundedWorkspaceClaimsDetachedRecovery(binding, item));
     if (!materials.length) continue;
     const artifactPath = `001-${workspacePlan.ordinal}-1-cache.trace.md`;
     const archivePath = `001-${workspacePlan.ordinal}-1-cache.zip`;

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

@@ -1,6 +1,20 @@
 import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
 
 export function bindingForWorkspace(descriptor = {}, workspaceId = '') { return (descriptor.workspaceArchiveBindings || []).find((binding) => String(binding.workspaceId || '') === String(workspaceId || '')) || null; }
+export function boundedWorkspaceClaimsDetachedRecovery(binding = {}, material = {}) {
+  const workspaceId = String(binding.workspaceId || '').trim();
+  if (!workspaceId || String(binding.coverage || '') !== 'bounded') return false;
+  if (String(material.classification || '') !== 'parent-boundary') return false;
+  if (String(material.routeWorkspaceId || '') !== workspaceId) return false;
+  if (!String(material.sourceRequirementId || '').startsWith(`bounded-workspace:${workspaceId}:`)) return false;
+  const targetWorkspaceId = String(material.targetWorkspaceId || workspaceId);
+  if (targetWorkspaceId !== workspaceId) return false;
+  const included = new Set((binding.entryMap?.entries || []).map((entry) => normalizeWorkspacePath(entry.path || '')));
+  const sourcePath = normalizeWorkspacePath(material.sourcePath || material.routePath || '');
+  const targetPath = normalizeWorkspacePath(material.targetPath || material.originalPath || '');
+  return Boolean(sourcePath && targetPath && included.has(sourcePath) && !included.has(targetPath));
+}
+
 export function routeClaimsDetachedMaterial(route = {}, material = {}) {
   const scopedWorkspace = String(material.routeWorkspaceId || '').trim();
   const scopedPath = normalizeWorkspacePath(material.routePath || '');

package/src/tooling/portable/handoff/workspaceCarrier.manufacture.js

@@ -7,7 +7,7 @@ import { renderRecipientV2Pointer } from './recipientV2.artifacts.js';
 import { RECIPIENT_V2_READ_PATH, RECIPIENT_V2_FORMAT_ID } from './recipientV2.topology.js';
 import { recipientV2WorkspaceEntryCurrentRead } 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 { safeToken, finding } from './recipientV2.topology.materials.js';
 import { 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, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
@@ -19,6 +19,7 @@ export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
   const targetByWorkspace = indexWorkspaceTargetDeclarations(input.workspaceTargets || []);
   const workspaces = [...(input.workspaceMaterializations || [])].sort((a, b) => String(a.id || '').localeCompare(String(b.id || '')));
   const plans = [];
+  const forcedMaterialWorkspaceIds = new Set([...(input.materialRepresentationWorkspaceIds || []), ...(input.genericMaterialWorkspaceIds || [])].map((value) => String(value || '')));
   for (const [index, raw] of workspaces.entries()) {
     const id = String(raw.id || '').trim();
     const wrapper = Object.freeze({ ...raw, materialization: String(raw.state || ''), qualification: 'qualified', correlationStatus: 'qualified' });
@@ -28,13 +29,35 @@ export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
     const prefix = `001-${index + 3}`;
     const slug = safeToken(id);
     const archiveData = exportFileMapZipUint8Array((qualified.entries || []).map((entry) => ({ path: entry.path, data: entry.data })), 'portable.workspace-carrier.workspace-archive.path.invalid');
-    const workspacePath = `${prefix}-${slug}.workspace.md`;
-    const archivePath = `${prefix}-${slug}.workspace.zip`;
-    const workspaceFile = exactFile(workspacePath, qualified.target.data, 'recipient-v2-package-v1-exact-workspace-artifact', 'text/markdown');
-    const archiveFile = exactFile(archivePath, archiveData, 'recipient-v2-package-v1-complete-workspace-snapshot', 'application/zip');
-    plans.push(Object.freeze({ id, raw, qualified, workspaceFile, archiveFile, projection: Object.freeze({ workspaceId: id, workspacePath, archivePath, sourceWorkspaceTargetInnerPath: qualified.target.path, sourceWorkspaceTargetSha256: workspaceFile.sha256, archiveSha256: archiveFile.sha256, archiveBytes: archiveFile.bytes, coverage: 'complete' }) }));
+    const coverage = String(raw.state || '') === 'bounded' ? 'bounded' : 'complete';
+    const useMaterialRepresentation = coverage === 'bounded' || forcedMaterialWorkspaceIds.has(id);
+    if (useMaterialRepresentation) {
+      const sourceWorkspacePath = `source-${prefix}-${slug}.workspace.md`;
+      const sourceArchivePath = `source-${prefix}-${slug}.workspace.zip`;
+      const sourceWorkspaceFile = exactFile(sourceWorkspacePath, qualified.target.data, 'recipient-v2-workspace-carrier-material-source-target', 'text/markdown');
+      const sourceArchiveFile = exactFile(sourceArchivePath, archiveData, 'recipient-v2-workspace-carrier-material-source-archive', 'application/zip');
+      const evidence = coverage === 'bounded' ? (raw.scopeEvidence || {}) : (raw.completenessEvidence || {});
+      const binding = Object.freeze({
+        workspaceId: id, coverage,
+        representation: Object.freeze({ packagePath: sourceArchivePath, kind: coverage === 'bounded' ? 'bounded-workspace-snapshot' : 'complete-workspace-snapshot', codec: 'deterministic-stored-zip' }),
+        workspaceTarget: Object.freeze({ packagePath: sourceWorkspacePath, innerPath: qualified.target.path }),
+        provider: Object.freeze({ kind: 'package-local-stored-zip-v1' }),
+        scope: coverage === 'bounded' ? Object.freeze({ ...evidence }) : undefined,
+        completeness: coverage === 'complete' ? Object.freeze({ ...evidence }) : undefined,
+        entryMap: Object.freeze({ count: qualified.entries.length, entries: Object.freeze(qualified.entries.map((entry) => Object.freeze({ path: entry.path, bytes: entry.bytes, sha256: entry.sha256, referenceTarget: String(entry.referenceTarget || '') }))) })
+      });
+      plans.push(Object.freeze({ id, raw, qualified, coverage, useMaterialRepresentation, sourceWorkspaceFile, sourceArchiveFile, binding, projection: Object.freeze({ workspaceId: id, coverage }) }));
+    } else {
+      const workspacePath = `${prefix}-${slug}.workspace.md`;
+      const archivePath = `${prefix}-${slug}.workspace.zip`;
+      const workspaceFile = exactFile(workspacePath, qualified.target.data, 'recipient-v2-package-v1-exact-workspace-artifact', 'text/markdown');
+      const archiveFile = exactFile(archivePath, archiveData, 'recipient-v2-package-v1-complete-workspace-snapshot', 'application/zip');
+      plans.push(Object.freeze({ id, raw, qualified, coverage, useMaterialRepresentation, workspaceFile, archiveFile, projection: Object.freeze({ workspaceId: id, workspacePath, archivePath, sourceWorkspaceTargetInnerPath: qualified.target.path, sourceWorkspaceTargetSha256: workspaceFile.sha256, archiveSha256: archiveFile.sha256, archiveBytes: archiveFile.bytes, coverage: 'complete' }) }));
+    }
   }
   if (!plans.length || findings.some((item) => item.severity === 'error')) return blocked(findings);
+  const directPlans = plans.filter((plan) => !plan.useMaterialRepresentation);
+  const materialPlans = plans.filter((plan) => plan.useMaterialRepresentation).map((plan, materialIndex) => { const ordinal = workspaces.findIndex((item) => String(item.id || '') === plan.id) + 3; const prefix = `001-${ordinal}`; const slug = safeToken(plan.id); return Object.freeze({ binding: plan.binding, ordinal, workspaceId: plan.id, slug, prefix, workspacePath: `${prefix}-${slug}.workspace.md`, archivePath: `${prefix}-${slug}.workspace.zip`, payloadArtifactPath: `${prefix}-1-workspace-representation-payload.trace.md`, representationArtifactPath: `${prefix}-2-workspace-representation.trace.md`, sourceWorkspaceFile: plan.sourceWorkspaceFile, sourceArchiveFile: plan.sourceArchiveFile }); });
   const createdAt = String(input.createdAt || '1970-01-01 00:00:00');
   const bootstrapSource = (input.additionalTransportFiles || []).filter((file) => String(file.path || '').startsWith('tiinex.bootstrap/'));
   const packageFile = finalizeFile({
@@ -42,10 +65,16 @@ export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
     kind: 'tiinex-handoff-package-artifact',
     logicalKind: 'recipient-v2-package-v1-root',
     mediaType: 'text/markdown',
-    content: renderHandoffPackageV1({ createdAt, packageRole: WORKSPACE_PACKAGE_ROLE, workspaces: plans.map((plan) => plan.projection), carrierLineage: input.carrierLineage || {}, carrierProfile: input.carrierProfile || null, startPath: RECIPIENT_V2_READ_PATH, bootstrapPath: bootstrapSource.length ? '001-2-bootstrap.trace.md' : '' })
+    content: renderHandoffPackageV1({ createdAt, packageRole: WORKSPACE_PACKAGE_ROLE, workspaces: directPlans.map((plan) => plan.projection), materialRepresentations: materialPlans.map((plan) => Object.freeze({ materialId: `workspace-${plan.workspaceId}`, workspaceId: plan.workspaceId, representationArtifactPath: plan.representationArtifactPath, carriageState: 'verified' })), carrierLineage: input.carrierLineage || {}, carrierProfile: input.carrierProfile || null, startPath: RECIPIENT_V2_READ_PATH, bootstrapPath: bootstrapSource.length ? '001-2-bootstrap.trace.md' : '' })
   });
   const packageParent = recipientV2ParentAuthority(packageFile, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET, createdAt);
-  const files = [packageFile, ...plans.flatMap((plan) => [plan.workspaceFile, plan.archiveFile])];
+  const files = [packageFile, ...directPlans.flatMap((plan) => [plan.workspaceFile, plan.archiveFile])];
+  const topology = { workspaces: directPlans.map((plan) => plan.projection) };
+  if (materialPlans.length) {
+    const byPath = new Map();
+    for (const plan of materialPlans) { byPath.set(plan.sourceWorkspaceFile.path, [plan.sourceWorkspaceFile]); byPath.set(plan.sourceArchiveFile.path, [plan.sourceArchiveFile]); }
+    buildRecipientV2WorkspaceCarriers({ workspacePlans: materialPlans, byPath, findings, createdAt, rootParent: packageParent, files, topology });
+  }
   let bootstrap = null;
   if (bootstrapSource.length) {
     bootstrap = buildRecipientV2BootstrapCarrier(bootstrapSource, createdAt, findings, packageParent);
@@ -56,17 +85,17 @@ export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
     packageRole: WORKSPACE_PACKAGE_ROLE,
     packageRootPath: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH,
     entryArtifactPath: RECIPIENT_V2_READ_PATH,
-    artifactSurface: 'tiinex.handoff.package.v1-plus-exact-complete-workspace-snapshots',
+    artifactSurface: 'tiinex.handoff.package.v1-plus-qualified-source-material-bindings',
     routeAuthority: 'none', routeSelectionAuthority: 'none', siblingRouteInference: false,
     carrierLineage: input.carrierLineage || null, pathParentProjection: true, pathAuthority: false
   });
   const readFile = finalizeFile({
     path: RECIPIENT_V2_READ_PATH, kind: 'handoff-recovery-pointer', logicalKind: 'recipient-v2-package-v1-workspace-recovery-orientation', mediaType: 'text/markdown', transportFacts: readFacts,
-    content: renderRecipientV2Pointer({ createdAt, parent: packageParent, role: 'recovery-orientation', title: 'READ BEFORE PROCEEDING — Tiinex Workspace Carrier', summary: 'Qualified recovery/orientation Pointer for the pointerless package-v1 Workspace carrier.', prose: 'Read this Start artifact first and qualify the declared Tooling bootstrap. This carrier intentionally exposes no Handoff route or Continue-from Pointer; do not infer semantic Handoff state from Workspace carriage.', currentRead: [...recipientV2WorkspaceEntryCurrentRead(), { label: 'Package Artifact', value: `[Workspace Package](${RECIPIENT_V2_PACKAGE_V1_ROOT_PATH})` }, { label: 'Carrier Dimension', value: `\`${String(input.carrierLineage?.dimension || '001')}\`` }], destinations: [{ label: 'Workspace Package contract', target: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH }, ...(bootstrap ? [{ label: 'Portable Tooling bootstrap', target: bootstrap.projection.artifactPath }] : []), ...plans.map((plan) => ({ label: `Workspace ${plan.id}`, target: plan.projection.workspacePath }))], facts: readFacts })
+    content: renderRecipientV2Pointer({ createdAt, parent: packageParent, role: 'recovery-orientation', title: 'READ BEFORE PROCEEDING — Tiinex Workspace Carrier', summary: 'Qualified recovery/orientation Pointer for the pointerless package-v1 Workspace carrier.', prose: 'Read this Start artifact first and qualify the declared Tooling bootstrap. This carrier intentionally exposes no Handoff route or Continue-from Pointer; do not infer semantic Handoff state from Workspace carriage.', currentRead: [...recipientV2WorkspaceEntryCurrentRead(), { label: 'Package Artifact', value: `[Workspace Package](${RECIPIENT_V2_PACKAGE_V1_ROOT_PATH})` }, { label: 'Carrier Dimension', value: `\`${String(input.carrierLineage?.dimension || '001')}\`` }], destinations: [{ label: 'Workspace Package contract', target: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH }, ...(bootstrap ? [{ label: 'Portable Tooling bootstrap', target: bootstrap.projection.artifactPath }] : []), ...topology.workspaces.map((workspace) => ({ label: `Workspace ${workspace.workspaceId}`, target: workspace.workspacePath }))], facts: readFacts })
   });
   files.push(readFile);
   const sortedFiles = Object.freeze([...files].sort((a, b) => String(a.path || '').localeCompare(String(b.path || ''))));
-  const bundle = deepFreeze({ status: 'ready', files: sortedFiles, handoffClosure: null, transportFormat: RECIPIENT_V2_FORMAT_ID, boundary: 'Pointerless recipient-facing Workspace carrier. Exact carried Workspace source bytes retain authority; carrier placement creates no Handoff semantics.' });
+  const bundle = deepFreeze({ status: 'ready', files: sortedFiles, handoffClosure: null, transportFormat: RECIPIENT_V2_FORMAT_ID, boundary: 'Pointerless recipient-facing Workspace carrier. Exact qualified direct or generic complete/bounded Workspace source bytes retain authority; carrier placement creates no Handoff semantics.' });
   const inspection = inspectRecipientFacingV2Topology(bundle);
   const roundtrip = input.verifyRoundtrip === false ? null : roundTripRecipientFacingV2Topology(bundle, inspection);
   const toolingBootstrapInspection = inspection.bootstrapInspection || inspectPortableToolingBootstrap({ files: bootstrapSource });
@@ -75,7 +104,7 @@ export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
   const carrierProjection = inspection.carrierProjection || workspaceProjection(plans, input.carrierLineage || {});
   return deepFreeze({
     schema: 'tiinex.portable.handoff-manufacturing.v2', status: ready ? 'ready' : 'blocked', executable: ready, transportExecutable: ready,
-    verification: Object.freeze({ baselineManufacture: 'ready', manufacturePath: 'direct-qualified-workspace-to-pointerless-package-v1', packageInspection: inspection.status, closureInspection: 'not-applicable', carrierInspection: inspection.status, selectedHandoffConformance: 'not-applicable', pointerEntrypointInspection: 'not-applicable', coldConsumerEntrypointInspection: inspection.status, companionInspection: 'not-applicable', roundtrip: roundtrip?.status || 'not-requested', toolingBootstrap: toolingBootstrapInspection.status }),
+    verification: Object.freeze({ baselineManufacture: 'ready', manufacturePath: 'qualified-workspace-material-to-pointerless-package-v1', packageInspection: inspection.status, closureInspection: 'not-applicable', carrierInspection: inspection.status, selectedHandoffConformance: 'not-applicable', pointerEntrypointInspection: 'not-applicable', coldConsumerEntrypointInspection: inspection.status, companionInspection: 'not-applicable', roundtrip: roundtrip?.status || 'not-requested', toolingBootstrap: toolingBootstrapInspection.status }),
     plan: Object.freeze({ status: ready ? 'ready' : 'blocked', requiredClosureReady: true, semanticHandoffStatus: 'not-declared', workspaceMaterializations: Object.freeze(workspaces), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]) }) }),
     bundle, inspection, carrierProjection, roundtrip, toolingBootstrapInspection, toolingBootstrap: input.toolingBootstrap || null, carrierLineage: input.carrierLineage || carrierProjection.lineage || null, manufacturingEvidence: input.manufacturingEvidence || null,
     findings: Object.freeze(allFindings), findingSummary: summarizePortableFindings(allFindings), operationBoundary: Object.freeze({ sourceMutation: false, remoteWrite: false, handoffSemantics: false }),
@@ -89,5 +118,5 @@ function workspaceProjection(plans, lineage) {
 }
 function blocked(findings = []) {
   const all = findings.length ? findings : [finding('error', 'portable.workspace-carrier.manufacture.blocked', 'Pointerless Workspace carrier manufacture failed closed.')];
-  return deepFreeze({ schema: 'tiinex.portable.handoff-manufacturing.v2', status: 'blocked', executable: false, transportExecutable: false, verification: Object.freeze({ manufacturePath: 'direct-qualified-workspace-to-pointerless-package-v1' }), plan: Object.freeze({ status: 'blocked', workspaceMaterializations: Object.freeze([]), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]) }) }), bundle: null, inspection: null, carrierProjection: Object.freeze({ schema: 'tiinex.portable.handoff-carrier-projection.v1', status: 'blocked', mode: 'workspace', workspaces: Object.freeze([]), routes: Object.freeze([]), findings: Object.freeze(all) }), findings: Object.freeze(all), findingSummary: summarizePortableFindings(all), boundary: 'Failed closed before emitting pointerless Workspace carrier bytes.' });
+  return deepFreeze({ schema: 'tiinex.portable.handoff-manufacturing.v2', status: 'blocked', executable: false, transportExecutable: false, verification: Object.freeze({ manufacturePath: 'qualified-workspace-material-to-pointerless-package-v1' }), plan: Object.freeze({ status: 'blocked', workspaceMaterializations: Object.freeze([]), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]) }) }), bundle: null, inspection: null, carrierProjection: Object.freeze({ schema: 'tiinex.portable.handoff-carrier-projection.v1', status: 'blocked', mode: 'workspace', workspaces: Object.freeze([]), routes: Object.freeze([]), findings: Object.freeze(all) }), findings: Object.freeze(all), findingSummary: summarizePortableFindings(all), boundary: 'Failed closed before emitting pointerless Workspace carrier bytes.' });
 }