@tiinex/core 0.19.0 → 0.20.0

package/src/tooling/portable/grounding/grounding.holderBindingAuthorization.js

@@ -1,81 +1,80 @@
-import { deepFreeze, normalizeComparable, normalizeToken } from '../handoff/coldStartQualification.shared.js';
+import { deepFreeze, normalizeToken } from '../handoff/coldStartQualification.shared.js';
+import {
+  HOLDER_ASSIGNMENT_MODE,
+  isCanonicalHolderAssignmentMode,
+  projectHolderAssignmentModeAuthority
+} from './grounding.holderAssignmentModes.js';
 
-export const EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE = 'assignable per explicit session or Handoff';
-export const CURRENT_ROLE_EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE = 'assignable per explicit session, role invocation, or Handoff; no permanent holder asserted';
-export const ANCHOR_EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE = 'assignable per explicit session or Handoff; no permanent holder asserted';
-
-const AUTHORIZED_EXPLICIT_SESSION_OR_HANDOFF_STATES = new Set([
-  normalizeComparable(EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE),
-  normalizeComparable(CURRENT_ROLE_EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE),
-  normalizeComparable(ANCHOR_EXPLICIT_SESSION_OR_HANDOFF_HOLDER_STATE)
-]);
-
-export function projectHolderBindingAuthorization(role = {}) {
+export function projectHolderBindingAuthorization(role = {}, options = {}) {
   const endpointKind = normalizeToken(role?.endpoint?.kind || '');
+  const requestedMode = String(options.assertionMode || options.assignmentMode || HOLDER_ASSIGNMENT_MODE.EXPLICIT_SESSION).trim();
   if (endpointKind !== 'role') return deepFreeze({
     state: 'not-applicable',
     assignmentMode: '',
+    authorizedModes: deepFreeze([]),
     holderState: '',
     source: 'none',
     reasonCode: 'recipient-not-role',
+    modeAuthority: projectHolderAssignmentModeAuthority(role),
     provenance: {
-      basis: 'recipient-not-role',
-      roleArtifactPath: '',
-      roleArtifactSha256: '',
-      section: 'Holder Relationship',
-      field: 'Holder State',
-      boundary: 'Holder-assignment authorization is only applicable when the selected Handoff recipient is a Role endpoint.'
+      basis: 'recipient-not-role', roleArtifactPath: '', roleArtifactSha256: '', section: 'Holder Relationship', field: 'Assignment Modes', exactValue: '', assertionMode: '', boundary: 'Holder-assignment authorization is only applicable when the selected Handoff recipient is a Role endpoint.'
     },
     boundary: 'No Role assignment authorization is required for a non-Role recipient.'
   });
 
-  const material = role?.material?.artifact || null;
-  const relationship = role?.holderRelationshipLoaded || {};
-  const holderState = String(relationship.holderState || '').trim();
-  const qualifiedMaterial = String(role?.state || '') === 'qualified'
-    && String(role?.material?.state || '') === 'qualified'
-    && Boolean(material?.path)
-    && Boolean(material?.sha256);
-  const provenance = {
-    basis: qualifiedMaterial ? 'exact-qualified-role-holder-relationship' : 'exact-qualified-role-holder-relationship-not-established',
-    roleArtifactPath: String(material?.path || ''),
-    roleArtifactSha256: String(material?.sha256 || ''),
-    roleSchemaId: String(material?.schemaId || ''),
-    roleLabel: String(material?.roleLabel || role?.endpoint?.label || ''),
-    section: 'Holder Relationship',
-    field: 'Holder State',
-    exactValue: holderState,
-    boundary: 'Only exact qualified recipient Role material may authorize the bounded session assignment mode. Handoff endpoints, transport identity, explicit session input, filenames, and package placement do not provide this authority.'
-  };
+  const modeAuthority = projectHolderAssignmentModeAuthority(role);
+  const holderState = String(modeAuthority.holderState || role?.holderRelationshipLoaded?.holderState || '').trim();
+  const provenance = deepFreeze({
+    ...(modeAuthority.provenance || {}),
+    assertionMode: requestedMode,
+    boundary: 'The bounded binding result compares one explicit assertion mechanism to exact qualified canonical assignment-mode authority. Holder State prose remains diagnostic-only.'
+  });
 
-  if (!qualifiedMaterial) return deepFreeze({
+  if (modeAuthority.state !== 'qualified') return deepFreeze({
     state: 'unresolved',
-    assignmentMode: '',
+    assignmentMode: requestedMode,
+    authorizedModes: deepFreeze([]),
     holderState,
-    source: 'none',
-    reasonCode: 'qualified-role-holder-authority-not-established',
+    source: modeAuthority.source || 'none',
+    reasonCode: modeAuthority.reasonCode || 'holder-assignment-mode-authority-unresolved',
+    modeAuthority,
     provenance,
-    boundary: 'A matching session Role assertion remains unauthorized until exact qualified Role material establishes the assignment mode.'
+    boundary: 'A matching Role assertion remains unauthorized until exact qualified canonical assignment-mode authority is established.'
   });
 
-  const assignmentAuthorized = AUTHORIZED_EXPLICIT_SESSION_OR_HANDOFF_STATES.has(normalizeComparable(holderState));
-  if (!assignmentAuthorized) return deepFreeze({
+  if (!isCanonicalHolderAssignmentMode(requestedMode)) return deepFreeze({
     state: 'unresolved',
-    assignmentMode: '',
+    assignmentMode: requestedMode,
+    authorizedModes: deepFreeze([...(modeAuthority.modes || [])]),
+    holderState,
+    source: modeAuthority.source,
+    reasonCode: 'holder-binding-assertion-mode-unqualified',
+    modeAuthority,
+    provenance,
+    boundary: 'The asserted binding mechanism is not a canonical mode established by semantic authority. Core does not reinterpret arbitrary assertion labels.'
+  });
+
+  if (!(modeAuthority.modes || []).includes(requestedMode)) return deepFreeze({
+    state: 'unresolved',
+    assignmentMode: requestedMode,
+    authorizedModes: deepFreeze([...(modeAuthority.modes || [])]),
     holderState,
-    source: 'qualified-recipient-role-material',
-    reasonCode: holderState ? 'holder-assignment-mode-not-authorized' : 'holder-assignment-mode-unresolved',
+    source: modeAuthority.source,
+    reasonCode: 'holder-assignment-mode-not-authorized',
+    modeAuthority,
     provenance,
-    boundary: 'The exact qualified Role does not establish authorization for explicit-session/Handoff assignment. Core preserves this as unresolved and does not reinterpret other Holder State wording.'
+    boundary: 'The exact qualified canonical mode set does not authorize the asserted bounded binding mechanism. No widening between session, user-session, invocation, Handoff, or participation modes is permitted.'
   });
 
   return deepFreeze({
     state: 'qualified',
-    assignmentMode: 'explicit-session-or-handoff',
+    assignmentMode: requestedMode,
+    authorizedModes: deepFreeze([...(modeAuthority.modes || [])]),
     holderState,
-    source: 'qualified-recipient-role-material',
+    source: modeAuthority.source,
     reasonCode: 'holder-assignment-mode-authorized',
+    modeAuthority,
     provenance,
-    boundary: 'Exact qualified Role Holder Relationship authorizes this assignment mode for the bounded current session only; it does not establish durable holder identity or broader participant/process/source authority.'
+    boundary: 'Exact qualified canonical assignment-mode authority authorizes only this bounded assertion mechanism; it does not establish durable holder identity or broader participant/process/delegation/source/acceptance authority.'
   });
 }

package/src/tooling/portable/grounding/grounding.readiness.js

@@ -41,6 +41,7 @@ export function projectPortableGroundingReadiness(input = {}, options = {}) {
     route,
     toolingAvailable: true
   }, { ...options, coldStartMaterialContext: materialContext });
+  const authority = withExplicitGroundingAuthorityInputs(grounding, input);
   const continuation = projectGroundedContinuation({
     bundle,
     route,
@@ -62,7 +63,7 @@ export function projectPortableGroundingReadiness(input = {}, options = {}) {
   });
   return composeGroundingReadiness({
     mode: 'routed-handoff-package',
-    authority: grounding,
+    authority,
     continuation,
     contextAudit,
     material,
@@ -140,8 +141,8 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
         known.push(evidence('session-holder-role-binding-authorization', 'qualified', authority?.holderBinding?.authorization?.provenance?.roleArtifactPath || authority?.role?.endpoint?.label || 'recipient Role material'));
       } else {
         holderBindingActReady = false;
-        unresolved.push(evidence('session-holder-role-binding-authorization', holderAuthorizationState || 'unresolved', authority?.holderBinding?.authorization?.holderState || 'exact qualified Role Holder Relationship does not establish the explicit-session/Handoff assignment mode'));
-        reasons.push(reason('session-holder-role-binding-authorization-unresolved', 'The explicit consuming-session Role assertion matches the selected recipient Role, but exact qualified Role holder-assignment authority does not establish that assignment mode. Matching session input alone cannot make the route act-ready.'));
+        unresolved.push(evidence('session-holder-role-binding-authorization', holderAuthorizationState || 'unresolved', authority?.holderBinding?.authorization?.reasonCode || 'exact qualified canonical assignment-mode authority does not authorize the asserted binding mechanism'));
+        reasons.push(reason('session-holder-role-binding-authorization-unresolved', 'The explicit consuming-session Role assertion matches the selected recipient Role, but exact qualified canonical assignment-mode authority does not authorize the asserted mechanism. Matching session input alone cannot make the route act-ready.'));
       }
     }
 
@@ -254,6 +255,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
     }),
     continuity,
     orchestrationReadiness,
+    delegationReadiness: capsule.delegationReadiness,
     capsule,
     currentWork: Object.freeze({
       state: topology.currentFrontier.length ? 'current-frontier-resolved' : topology.currentTasks.length ? 'current-candidates-without-frontier' : 'unresolved',
@@ -288,6 +290,20 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
   });
 }
 
+
+function withExplicitGroundingAuthorityInputs(grounding = {}, input = {}) {
+  const context = input.delegationContext && typeof input.delegationContext === 'object' ? input.delegationContext : {};
+  const selected = {
+    delegateCapabilityAuthority: input.delegateCapabilityAuthority || context.delegateCapabilityAuthority || null,
+    processApplicability: input.processApplicability || context.processApplicability || null,
+    delegationTargetAuthority: input.delegationTargetAuthority || context.delegationTargetAuthority || context.targetAuthority || null,
+    implementationSourceAuthority: input.implementationSourceAuthority || context.implementationSourceAuthority || context.sourceAuthority || null,
+    delegationReturnReconciliationExpectation: input.delegationReturnReconciliationExpectation || context.delegationReturnReconciliationExpectation || context.returnReconciliationExpectation || null
+  };
+  const additions = Object.fromEntries(Object.entries(selected).filter(([, value]) => value && typeof value === 'object'));
+  return Object.freeze({ ...(grounding || {}), ...additions, ...(Object.keys(context).length ? { delegationContext: Object.freeze({ ...context }) } : {}) });
+}
+
 function projectWorkspaceActionCoverage(contextAudit = {}) {
   const workspaces = Array.isArray(contextAudit?.workspaceMaterializations) ? contextAudit.workspaceMaterializations : [];
   const summaries = workspaces.map((workspace) => {

package/src/tooling/portable/grounding/grounding.readiness.support.js

@@ -174,7 +174,7 @@ export function resolveRequiredContextRecords(requiredContext = [], records = []
 }
 
 function isExactHydratedWorkspaceContext(entry = {}) {
-  if (String(entry.providerMode || '') !== 'archive') return false;
+  if (!['archive', 'cache'].includes(String(entry.providerMode || ''))) return false;
   if (!['hydrated-text', 'qualified-locator-only'].includes(String(entry.contentState || ''))) return false;
   const expectedBytes = Number(entry.bytes || 0);
   const actualBytes = Number(entry.actualBytes || 0);

package/src/tooling/portable/handoff/carrierProjection.routeQualification.js

@@ -71,8 +71,22 @@ function qualifyRequiredRequirement(bundle, descriptor, byteProvider, workspace,
   let resolution=null;
   if (!target||target.startsWith('#')) { resolution=resolveDescriptorMaterial(bundle,descriptor,byteProvider,target,requirementId,workspace.id,routePath); if(!resolution) reasons.push('exact-required-material-reference-or-binding-unresolved'); }
   const qualified=parseWorkspaceQualifiedReference(target);
-  if (!resolution&&!reasons.length&&qualified) resolution=resolveWorkspaceRequiredMaterial(byteProvider,{id:qualified.workspaceId},qualified.path);
-  if (!resolution&&!reasons.length&&!qualified&&!isExternalReference(target)) { const resolvedPath=resolveWorkspaceReference(routePath,target); if(!resolvedPath) reasons.push('workspace-reference-outside-or-invalid'); else resolution=resolveWorkspaceRequiredMaterial(byteProvider,workspace,resolvedPath); }
+  if (!resolution&&!reasons.length&&qualified) {
+    const workspaceResolution=resolveWorkspaceRequiredMaterial(byteProvider,{id:qualified.workspaceId},qualified.path);
+    resolution=workspaceResolution.state==='qualified'
+      ? workspaceResolution
+      : (resolveDescriptorMaterial(bundle,descriptor,byteProvider,target,requirementId,workspace.id,routePath)||workspaceResolution);
+  }
+  if (!resolution&&!reasons.length&&!qualified&&!isExternalReference(target)) {
+    const resolvedPath=resolveWorkspaceReference(routePath,target);
+    if(!resolvedPath) reasons.push('workspace-reference-outside-or-invalid');
+    else {
+      const workspaceResolution=resolveWorkspaceRequiredMaterial(byteProvider,workspace,resolvedPath);
+      resolution=workspaceResolution.state==='qualified'
+        ? workspaceResolution
+        : (resolveDescriptorMaterial(bundle,descriptor,byteProvider,target,requirementId,workspace.id,routePath)||workspaceResolution);
+    }
+  }
   if (!resolution&&!reasons.length) resolution=resolveDescriptorMaterial(bundle,descriptor,byteProvider,target,requirementId,workspace.id,routePath);
   if (!resolution&&!reasons.length) reasons.push('required-material-not-carried');
   if (resolution?.state!=='qualified'&&resolution?.reason) reasons.push(resolution.reason);
@@ -190,8 +204,10 @@ function resolveRouteParent(bundle, descriptor, byteProvider, workspace, routePa
     if (!markdown) continue;
     const self = validatedC14nV2PrimarySelfDigest(markdown);
     if (self.state !== 'verified' || self.value !== digest) continue;
-    const key = `${candidate.workspaceId || ''}\u0000${candidate.workspaceRelativePath || ''}\u0000${candidate.packagePath || ''}`;
-    digestMatches.set(key, Object.freeze({ state: 'qualified', markdown, basis: 'parent-target-digest-candidate', workspaceRelativePath: normalizeWorkspacePath(candidate.workspaceRelativePath || ''), packagePath: String(candidate.packagePath || ''), sha256: sha256Hex(data) }));
+    const candidatePath = normalizeWorkspacePath(candidate.workspaceRelativePath || '');
+    const candidateSha256 = sha256Hex(data);
+    const key = `${candidate.workspaceId || ''}\u0000${candidatePath}\u0000${candidateSha256}`;
+    if (!digestMatches.has(key)) digestMatches.set(key, Object.freeze({ state: 'qualified', markdown, basis: 'parent-target-digest-candidate', workspaceRelativePath: candidatePath, packagePath: String(candidate.packagePath || ''), sha256: candidateSha256 }));
   }
   if (digestMatches.size === 1) return [...digestMatches.values()][0];
   if (digestMatches.size > 1) return Object.freeze({ state: 'ambiguous', reason: 'multiple-parent-target-digest-candidates' });

package/src/tooling/portable/handoff/coldStartQualification.grounding.js

@@ -19,6 +19,7 @@ import {
   resolveGroundingRouteMarkdown,
   recipientFactsIndexForColdStart,
   resolveReferencedRoleMaterial,
+  resolveReferencedEndpointRoleMaterial,
   selectGroundingRoute
 } from './coldStartQualification.materials.js';
 import {
@@ -60,6 +61,7 @@ export function groundPortableColdConsumer(input = {}, options = {}) {
 
   const bundle = input.bundle || input.package || input;
   const role = groundRecipientRole(input, handoff, bundle, orientation, selectedRoute, findings, materialContext);
+  const senderRole = groundSenderRole(handoff, bundle, orientation, selectedRoute, materialContext);
   const holderBinding = groundHolderBinding(input, handoff, role, findings);
   const participation = groundParticipation(input, handoff, bundle, orientation, selectedRoute, findings, materialContext);
   const interaction = groundInteraction(input, handoff);
@@ -84,6 +86,7 @@ export function groundPortableColdConsumer(input = {}, options = {}) {
     selectedRoute,
     handoff,
     role,
+    senderRole,
     holderBinding,
     participation,
     interaction,
@@ -120,6 +123,50 @@ export function groundPortableColdConsumer(input = {}, options = {}) {
   });
 }
 
+function groundSenderRole(handoff, bundle, orientation, selectedRoute, materialContext) {
+  const fromKind = normalizeToken(handoff.fromKind);
+  if (fromKind && fromKind !== 'role') return deepFreeze({
+    state: 'not-applicable',
+    endpoint: Object.freeze({ label: handoff.from || '', kind: handoff.fromKind || '', bounded: Boolean(handoff.from) }),
+    material: Object.freeze({ state: 'not-required', artifact: null }),
+    exactBoundaryLoaded: null,
+    authorityBoundaryLoaded: null,
+    boundary: 'Sender endpoint is not declared as Role; no sender Role authority is invented.'
+  });
+  if (!handoff.fromReference) return deepFreeze({
+    state: 'unresolved',
+    endpoint: Object.freeze({ label: handoff.from || '', kind: handoff.fromKind || (handoff.from ? 'role' : ''), bounded: Boolean(handoff.from) }),
+    material: Object.freeze({ state: 'missing-exact-reference', artifact: null }),
+    exactBoundaryLoaded: null,
+    authorityBoundaryLoaded: null,
+    boundary: 'Delegation projection requires an exact Handoff From Reference; Role inventory and endpoint labels are not substituted.'
+  });
+  const localFindings = [];
+  const material = resolveReferencedEndpointRoleMaterial(bundle, handoff, orientation, selectedRoute, localFindings, materialContext, 'from');
+  const parsed = material ? parseRoleMaterial(material) : null;
+  const target = normalizeComparable(handoff.from || '');
+  if (!parsed || (target && normalizeComparable(parsed.label) !== target)) return deepFreeze({
+    state: 'unresolved',
+    endpoint: Object.freeze({ label: handoff.from || '', kind: handoff.fromKind || (handoff.from ? 'role' : ''), bounded: Boolean(handoff.from) }),
+    material: Object.freeze({ state: localFindings.length ? 'unresolved-exact-reference' : 'missing', artifact: null }),
+    exactBoundaryLoaded: null,
+    authorityBoundaryLoaded: null,
+    boundary: 'Exact sender Role material did not qualify; sender authority is not inferred from carried Role inventory.'
+  });
+  return deepFreeze({
+    state: 'qualified',
+    endpoint: Object.freeze({ label: handoff.from || parsed.label || '', kind: handoff.fromKind || 'role', bounded: Boolean(handoff.from) }),
+    material: Object.freeze({
+      state: 'qualified',
+      artifact: Object.freeze({ path: parsed.path, sha256: parsed.sha256, schemaId: parsed.schemaId, title: parsed.title, roleLabel: parsed.label, roleKind: parsed.roleKind, reference: handoff.fromReference || '' })
+    }),
+    exactBoundaryLoaded: parsed.boundary,
+    authorityBoundaryLoaded: parsed.authorityBoundary,
+    interpretationLimitsLoaded: parsed.interpretationLimits,
+    boundary: 'Exact Handoff From Reference Role material only. Sender Role authority remains separate from Handoff transfer and is never inferred from endpoint naming or cache inventory.'
+  });
+}
+
 function groundRecipientRole(input, handoff, bundle, orientation, selectedRoute, findings, materialContext) {
   const toKind = normalizeToken(handoff.toKind);
   if (toKind && toKind !== 'role') return deepFreeze({
@@ -201,12 +248,14 @@ function groundHolderBinding(input, handoff, role, findings) {
   const roleRecipient = recipientRoleKind === 'role';
   const explicitlySupplied = Boolean(roleLabel || holderId);
   const sourceDetail = holderBindingSourceDetail(input, explicit, explicitlySupplied);
-  const authorization = projectHolderBindingAuthorization(role);
+  const assertionMode = String(explicit.assignmentMode || explicit.bindingMode || explicit.mechanism || input.holderAssignmentMode || input.sessionAssignmentMode || 'explicit-session').trim();
+  const authorization = projectHolderBindingAuthorization(role, { assertionMode });
   const durableIdentity = holderDurableIdentityProjection(holderId);
 
   if (!roleRecipient) return deepFreeze({
     state: 'not-applicable',
     holderId,
+    assertionMode,
     roleLabel,
     recipientRoleLabel,
     recipientCompatibility: 'not-applicable',
@@ -224,6 +273,7 @@ function groundHolderBinding(input, handoff, role, findings) {
     return deepFreeze({
       state: 'unresolved',
       holderId,
+      assertionMode,
       roleLabel: '',
       recipientRoleLabel,
       recipientCompatibility: 'unresolved',
@@ -242,6 +292,7 @@ function groundHolderBinding(input, handoff, role, findings) {
     return deepFreeze({
       state: 'blocked',
       holderId,
+      assertionMode,
       roleLabel,
       recipientRoleLabel,
       recipientCompatibility: 'mismatch',
@@ -258,6 +309,7 @@ function groundHolderBinding(input, handoff, role, findings) {
   return deepFreeze({
     state: 'qualified',
     holderId,
+    assertionMode,
     roleLabel,
     recipientRoleLabel,
     recipientCompatibility: 'matched',
@@ -310,7 +362,7 @@ function holderBindingSourceDetail(input = {}, explicit = {}, explicitlySupplied
 
 function groundParticipation(input, handoff, bundle, orientation, selectedRoute, findings, materialContext) {
   const explicitParticipants = normalizeParticipants(input.participants || input.interaction?.participants || []);
-  const packageRoleGrounding = resolvePackageParticipantRoles(bundle, orientation, selectedRoute, findings);
+  const packageRoleGrounding = resolvePackageParticipantRoles(bundle, orientation, selectedRoute, findings, materialContext);
   const participants = dedupeGroundedParticipants(explicitParticipants);
   const contributions = normalizeContributions(input.contributions || input.interaction?.contributions || []);
   const currentContributionId = String(input.currentContributionId || input.interaction?.currentContributionId || '').trim();
@@ -345,7 +397,7 @@ function resolvePackageParticipantRoles(bundle = {}, orientation = null, selecte
     const pointerPath = String(pointerPaths[index] || '');
     const pointerFile = findFile(bundle, pointerPath);
     if (!pointerFile) { findings.push(portableFinding('error', 'portable.cold-start.participant-role.pointer.missing', 'Selected Handoff route declares Role grounding Pointer ancestry that is not carried.', { pointerPath })); continue; }
-    const compatibilityFacts = recipientV2FactsIndex(bundle).map.get(pointerPath) || null;
+    const compatibilityFacts = recipientFactsIndexForColdStart(bundle, materialContext).map.get(pointerPath) || null;
     const projectedFacts = (orientation?.participantRoles || []).find((item) => String(item.pointerPath || '') === pointerPath) || null;
     const facts = compatibilityFacts?.role === 'participant-role'
       ? compatibilityFacts

package/src/tooling/portable/handoff/coldStartQualification.materials.js

@@ -3,6 +3,7 @@ import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
 import { portableFinding } from '../findings.js';
 import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
 import { recipientV2FactsIndex } from './recipientV2.transportManifest.js';
+import { deriveRecipientV2ArtifactFirstPhase1Facts } from './recipientV2.artifactFirst.materials.js';
 import { parseNamedDeclarationSection } from '../schema/named.declarations.js';
 import { resolveColdStartRolePointerMaterial } from './coldStartRolePointers.js';
 import {
@@ -58,7 +59,12 @@ export function collectPackageRoleMaterials(bundle = {}) {
 }
 
 export function resolveReferencedRoleMaterial(bundle = {}, handoff = {}, orientation = null, selectedRoute = null, findings = [], context = null) {
-  const reference = String(handoff.toReference || '').trim();
+  return resolveReferencedEndpointRoleMaterial(bundle, handoff, orientation, selectedRoute, findings, context, 'to');
+}
+
+export function resolveReferencedEndpointRoleMaterial(bundle = {}, handoff = {}, orientation = null, selectedRoute = null, findings = [], context = null, endpointParty = 'to') {
+  const party = String(endpointParty || 'to').trim().toLowerCase() === 'from' ? 'from' : 'to';
+  const reference = String(party === 'from' ? handoff.fromReference : handoff.toReference || '').trim();
   if (!reference) return null;
   if (!isExternalReference(reference)) {
     const workspaceZip = findFile(bundle, String(handoff.packagePath || ''));
@@ -71,7 +77,7 @@ export function resolveReferencedRoleMaterial(bundle = {}, handoff = {}, orienta
           const markdown = decodeUtf8(matches[0].data || new Uint8Array());
           if (markdown) return Object.freeze({ path: `${workspaceZip.path}::${resolvedPath}`, markdown, explicit: false, exactReference: reference });
         }
-        if (matches.length > 1) findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff To Reference resolves to multiple entries in the selected Workspace archive.', { reference, resolvedPath }));
+        if (matches.length > 1) findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff endpoint Reference resolves to multiple entries in the selected Workspace archive.', { reference, resolvedPath }));
       }
     }
   }
@@ -85,14 +91,14 @@ export function resolveReferencedRoleMaterial(bundle = {}, handoff = {}, orienta
       : projectedFacts
         ? { role: 'endpoint-role', ...projectedFacts }
         : {};
-    if (facts.role !== 'endpoint-role' || String(facts.endpointParty || '').toLowerCase() !== 'to') continue;
+    if (facts.role !== 'endpoint-role' || String(facts.endpointParty || '').toLowerCase() !== party) continue;
     if (facts.referenceTarget && String(facts.referenceTarget) !== reference) continue;
     const material = resolveColdStartRolePointerMaterial(bundle, facts, findings, String(pointerPath || ''), 'endpoint-role');
     if (material) endpointPointerMatches.push(Object.freeze({ ...material, exactReference: reference }));
   }
   if (endpointPointerMatches.length === 1) return endpointPointerMatches[0];
   if (endpointPointerMatches.length > 1) {
-    findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff To Reference resolves through multiple qualified endpoint Role Pointers.', { reference, count: endpointPointerMatches.length }));
+    findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff endpoint Reference resolves through multiple qualified endpoint Role Pointers.', { reference, count: endpointPointerMatches.length }));
     return null;
   }
   const cacheMatches = [];
@@ -114,7 +120,7 @@ export function resolveReferencedRoleMaterial(bundle = {}, handoff = {}, orienta
     }
   }
   if (cacheMatches.length === 1) return cacheMatches[0];
-  if (cacheMatches.length > 1) findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff To Reference resolves to multiple cached exact byte carriers.', { reference, count: cacheMatches.length }));
+  if (cacheMatches.length > 1) findings.push(portableFinding('error', 'portable.cold-start.role.reference-material.ambiguous', 'Handoff endpoint Reference resolves to multiple cached exact byte carriers.', { reference, count: cacheMatches.length }));
   return null;
 }
 
@@ -172,9 +178,16 @@ export function parseRoleMaterial(entry) {
       label,
       roleKind: sectionField(roleSection, 'Role Kind'),
       boundary: Object.freeze({ inScope: sectionField(boundarySection, 'In Scope'), outOfScope: sectionField(boundarySection, 'Out Of Scope'), context: sectionField(boundarySection, 'Context') }),
-      authorityBoundary: Object.freeze({ mayDo: sectionField(authoritySection, 'May Do'), doesNotAuthorize: sectionField(authoritySection, 'Does Not Authorize'), reviewBoundary: sectionField(authoritySection, 'Review Boundary') }),
+      authorityBoundary: Object.freeze({
+        mayDo: sectionField(authoritySection, 'May Do'),
+        doesNotAuthorize: sectionField(authoritySection, 'Does Not Authorize'),
+        requiredInstrument: sectionField(authoritySection, 'Required Instrument'),
+        delegation: sectionField(authoritySection, 'Delegation'),
+        reviewBoundary: sectionField(authoritySection, 'Review Boundary')
+      }),
       holderRelationship: Object.freeze({
         holderState: sectionField(holderSection, 'Holder State'),
+        assignmentModes: sectionField(holderSection, 'Assignment Modes'),
         currentHolder: sectionField(holderSection, 'Current Holder'),
         possibleHolder: sectionField(holderSection, 'Possible Holder'),
         unknownHolder: sectionField(holderSection, 'Unknown Holder'),
@@ -262,7 +275,7 @@ function hydrateRequiredContextEntry(bundle = {}, entry = {}, context = null) {
     })
   };
   if (base.state !== 'qualified') return Object.freeze({ ...base, contentState: 'unavailable', content: '' });
-  const hydrated = resolveQualifiedMaterialBytes(bundle, resolution, context);
+  const hydrated = resolveQualifiedMaterialBytes(bundle, resolution, context, base);
   if (!hydrated.bytes) return Object.freeze({ ...base, state: 'unresolved', contentState: 'unavailable', content: '' });
   const actualSha256 = sha256Hex(hydrated.bytes);
   const identityQualified = (!base.bytes || hydrated.bytes.byteLength === base.bytes) && (!base.sha256 || actualSha256 === base.sha256);
@@ -270,14 +283,21 @@ function hydrateRequiredContextEntry(bundle = {}, entry = {}, context = null) {
   return Object.freeze({
     ...base,
     state: identityQualified ? 'qualified' : 'identity-mismatch',
+    workspaceId: String(hydrated.workspaceId || base.workspaceId || ''),
+    archivePackagePath: String(hydrated.archivePackagePath || base.archivePackagePath || ''),
+    innerPath: String(hydrated.innerPath || base.innerPath || ''),
+    packagePath: String(hydrated.packagePath || base.packagePath || ''),
+    providerMode: String(hydrated.providerMode || base.providerMode || ''),
+    kind: String(hydrated.kind || base.kind || ''),
     actualBytes: hydrated.bytes.byteLength,
     actualSha256,
+    provenance: Object.freeze({ ...(base.provenance || {}), providerMode: String(hydrated.providerMode || base.providerMode || ''), resolutionKind: String(hydrated.kind || base.kind || '') }),
     contentState: text ? 'hydrated-text' : identityQualified ? 'qualified-locator-only' : 'unavailable',
     content: text
   });
 }
 
-function resolveQualifiedMaterialBytes(bundle = {}, resolution = {}, context = null) {
+function resolveQualifiedMaterialBytes(bundle = {}, resolution = {}, context = null, requirement = {}) {
   const kind = String(resolution.kind || '');
   if (kind === 'workspace-archive-entry' || kind === 'workspace-cache-entry') {
     const archivePath = String(resolution.archivePackagePath || resolution.packagePath || '');
@@ -293,17 +313,64 @@ function resolveQualifiedMaterialBytes(bundle = {}, resolution = {}, context = n
   }
   const packagePath = String(resolution.packagePath || '');
   const file = packagePath ? findFile(bundle, packagePath) : null;
-  return Object.freeze({ bytes: file ? packageFileBytes(file) : null });
+  if (file) return Object.freeze({ bytes: packageFileBytes(file), packagePath });
+  if (kind === 'materialized-required-material') {
+    const requirementId = String(requirement.requirementId || '');
+    const referenceTarget = String(requirement.referenceTarget || '');
+    const matches = [];
+    const factsIndex = recipientFactsIndexForColdStart(bundle, context).map;
+    const visibleFactsIndex = deriveRecipientV2ArtifactFirstPhase1Facts(bundle.files || []);
+    for (const candidateFile of bundle.files || []) {
+      const candidatePath = String(candidateFile.path || '');
+      const facts = factsIndex.get(candidatePath) || visibleFactsIndex.get(candidatePath) || null;
+      if (facts?.role !== 'workspace-dependency-cache' && !/dependency cache/i.test(String(facts?.role || ''))) continue;
+      for (const material of facts.materials || []) {
+        if (requirementId && String(material.requirementId || '') !== requirementId) continue;
+        if (referenceTarget && String(material.referenceTarget || '') !== referenceTarget) continue;
+        const archivePath = String(facts.archivePath || '');
+        const archiveFile = findFile(bundle, archivePath);
+        if (!archiveFile) continue;
+        const archive = inspectWorkspaceArchiveForColdStart(archiveFile, context);
+        if (archive.state !== 'qualified') continue;
+        const entries = (archive.entries || []).filter((entry) => String(entry.path || '') === String(material.archiveEntry || ''));
+        if (entries.length !== 1) continue;
+        const entry = entries[0];
+        const data = packageFileBytes({ data: entry.data });
+        const actualSha = sha256Hex(data);
+        if (Number(material.bytes || 0) && Number(material.bytes || 0) !== data.byteLength) continue;
+        if (String(material.sha256 || '') && String(material.sha256 || '') !== actualSha) continue;
+        if (Number(resolution.bytes || 0) && Number(resolution.bytes || 0) !== data.byteLength) continue;
+        if (String(resolution.sha256 || '') && String(resolution.sha256 || '') !== actualSha) continue;
+        matches.push(Object.freeze({
+          bytes: data, providerMode: 'cache', kind: 'workspace-cache-entry',
+          workspaceId: String(material.targetWorkspaceId || material.sourceWorkspaceId || facts.workspaceId || ''),
+          innerPath: String(material.targetPath || material.originalPath || ''),
+          archivePackagePath: archivePath, packagePath: archivePath
+        }));
+      }
+    }
+    if (matches.length === 1) return matches[0];
+  }
+  return Object.freeze({ bytes: null });
 }
 
 export function parseHandoffGrounding(markdown, route) {
   const parties = sectionText(markdown, 'Handoff Parties');
   const transferSection = parseNamedDeclarationSection(markdown, '## Transfers');
+  const retainedSection = parseNamedDeclarationSection(markdown, '## Retained Responsibilities');
   const completion = sectionText(markdown, 'Completion Expectation');
   const transfers = Object.freeze((transferSection.entries || []).filter((entry) => String(entry.name || '').trim().toLowerCase() !== 'none').map((entry) => Object.freeze({
     id: String(entry.name || ''),
     transferKind: String(entry.fields?.['Transfer Kind'] || ''),
     description: String(entry.fields?.Description || ''),
+    controllingArtifact: String(entry.fields?.['Controlling Artifact'] || ''),
+    controllingArtifactTarget: markdownReferenceTarget(entry.fields?.['Controlling Artifact'] || ''),
+    boundary: String(entry.fields?.Boundary || '')
+  })));
+  const retainedResponsibilities = Object.freeze((retainedSection.entries || []).filter((entry) => String(entry.name || '').trim().toLowerCase() !== 'none').map((entry) => Object.freeze({
+    id: String(entry.name || ''),
+    retainedBy: String(entry.fields?.['Retained By'] || ''),
+    responsibility: String(entry.fields?.Responsibility || ''),
     boundary: String(entry.fields?.Boundary || '')
   })));
   return deepFreeze({
@@ -316,6 +383,7 @@ export function parseHandoffGrounding(markdown, route) {
     fromReference: sectionReferenceTarget(parties, 'From Reference'),
     toReference: sectionReferenceTarget(parties, 'To Reference'),
     transfers,
+    retainedResponsibilities,
     completionExpectation: Object.freeze({
       signalKind: sectionField(completion, 'Signal Kind'),
       signalMeaning: sectionField(completion, 'Signal Meaning'),
@@ -330,8 +398,14 @@ export function parseHandoffGrounding(markdown, route) {
   });
 }
 
+function markdownReferenceTarget(value = '') {
+  const text = String(value || '').trim();
+  const match = text.match(/\[[^\]]*\]\(([^)]+)\)/);
+  return match ? String(match[1] || '').trim() : '';
+}
+
 export function emptyHandoffGrounding() {
-  return deepFreeze({ schemaId: '', purpose: '', from: '', fromKind: '', fromReference: '', to: '', toKind: '', toReference: '', transfers: Object.freeze([]), completionExpectation: Object.freeze({ signalKind: '', signalMeaning: '', returnTo: '' }), routeId: '', workspaceId: '', workspaceRelativePath: '', packagePath: '', sha256: '', boundary: 'No Handoff material supplied.' });
+  return deepFreeze({ schemaId: '', purpose: '', from: '', fromKind: '', fromReference: '', to: '', toKind: '', toReference: '', transfers: Object.freeze([]), retainedResponsibilities: Object.freeze([]), completionExpectation: Object.freeze({ signalKind: '', signalMeaning: '', returnTo: '' }), routeId: '', workspaceId: '', workspaceRelativePath: '', packagePath: '', sha256: '', boundary: 'No Handoff material supplied.' });
 }
 
 export function resolveGroundingRouteMarkdown(bundle = {}, selectedRoute = {}, findings = [], context = null) {

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

@@ -136,7 +136,7 @@ export function buildParticipantRolePointerChain(input = {}) {
         prose: 'This Pointer is recipient discovery/grounding only. It does not declare semantic participation, change Handoff From/To, prove a human holder, or create Role authority; participation meaning remains owned by authoritative Handoff/Relation/context authority.',
         currentRead: [
           { label: 'Route Id', value: `\`${String(input.route?.id || '')}\`` },
-          { label: 'Grounding Requirement Id', value: `\`${String(requirement.id || '')}\`` },
+          { label: 'Participant Requirement Id', value: `\`${String(requirement.id || '')}\`` },
           ...(roleFacts.roleLabelHint ? [{ label: 'Role Label Hint', value: roleFacts.roleLabelHint }] : []),
           { label: 'Role Reference', value: roleFacts.referenceTarget ? `\`${roleFacts.referenceTarget}\`` : 'exact carried target' },
           { label: 'Target Carrier Kind', value: target.carrierKind },

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

@@ -38,14 +38,17 @@ export function projectRecipientV2EndpointRoles(pointers = []) {
 export function projectRecipientV2ParticipantRoles(pointers = []) {
   return Object.freeze(pointers.map((item) => Object.freeze({
     pointerPath: item.path,
-    routeId: String(item.facts?.routeId || qualified?.id || ''),
-    workspaceId: String(item.facts?.workspaceId || ''),
     routeId: String(item.facts?.routeId || ''),
+    workspaceId: String(item.facts?.workspaceId || ''),
+    requirementId: String(item.facts?.participantRequirementId || ''),
     roleLabelHint: String(item.facts?.roleLabelHint || ''),
     referenceTarget: String(item.facts?.referenceTarget || ''),
     targetCarrierKind: String(item.facts?.targetCarrierKind || ''),
     targetWorkspaceId: String(item.facts?.targetWorkspaceId || ''),
+    archivePath: String(item.facts?.archivePath || ''),
     targetInnerPath: String(item.facts?.targetInnerPath || item.facts?.targetArchiveEntry || ''),
+    targetArchiveEntry: String(item.facts?.targetArchiveEntry || ''),
+    targetBytes: Number(item.facts?.targetBytes || 0),
     targetSha256: String(item.facts?.targetSha256 || '')
   })));
 }

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

@@ -9,7 +9,7 @@ import { RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, RECIPIENT_V2_SIBLING_ROUTE_INFE
 import { recipientV2TransportFacts } from './recipientV2.transportManifest.js';
 import { buildRecipientV2BootstrapCarrier, buildRecipientV2WorkspaceCarriers, recipientV2ParentAuthority } from './recipientV2.topology.workspaces.js';
 import { buildEndpointRolePointerChain, buildParticipantRolePointerChain } from './recipientV2.endpointRolePointers.js';
-import { bindingForWorkspace, boundedWorkspaceClaimsDetachedRecovery, detachedMaterial, duplicates, finding, roleMaterialTarget, routeClaimsDetachedMaterial, safeToken, uniqueFileIndex } from './recipientV2.topology.materials.js';
+import { bindingForWorkspace, boundedWorkspaceClaimsDetachedRecovery, coalesceDetachedCacheMaterials, 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';
@@ -136,7 +136,7 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
     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));
+    const materials = coalesceDetachedCacheMaterials(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`;