@tiinex/core 0.17.0 → 0.19.0

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

@@ -9,6 +9,7 @@ import { auditHandoffPackageContextCarriage } from '../handoff/contextAudit.js';
 import { acceptedRecoveryMaterial, projectColdStartContinuity } from './grounding.continuity.js';
 import { projectGroundingAuthority } from './grounding.readiness.authority.js';
 import { projectGroundingCapsule } from './grounding.capsule.js';
+import { projectGroundingOrchestrationReadiness } from './grounding.orchestrationReadiness.js';
 
 export const PORTABLE_GROUNDING_READINESS_SCHEMA_ID = 'tiinex.portable.grounding-readiness.v1';
 
@@ -112,6 +113,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
     const route = authority?.selectedRoute || null;
     const roleState = String(authority?.role?.state || 'unresolved');
     const holderState = String(authority?.holderBinding?.state || 'unresolved');
+    const holderAuthorizationState = String(authority?.holderBinding?.authorization?.state || (holderState === 'not-applicable' ? 'not-applicable' : 'unresolved'));
     if (!route || String(authority?.status || '') === 'blocked') missing(missingEvidence, unresolved, 'authority-route-unqualified', 'The selected Handoff route is not qualified for this grounding result.');
     else known.push(evidence('qualified-handoff-route', 'qualified', route.id || route.pointerPath || 'selected-route'));
     if (roleState === 'qualified' || roleState === 'not-applicable') known.push(evidence('recipient-role-boundary', roleState, authority?.role?.endpoint?.label || 'recipient'));
@@ -119,7 +121,6 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
     else missing(missingEvidence, unresolved, 'recipient-role-unresolved', 'The Handoff recipient Role boundary is not qualified for act-ready grounding.');
 
     if (holderState === 'qualified' || holderState === 'not-applicable') {
-      holderBindingActReady = true;
       known.push(evidence('session-holder-role-binding', holderState, authority?.holderBinding?.roleLabel || authority?.role?.endpoint?.label || 'recipient'));
     } else if (holderState === 'blocked') {
       holderBindingActReady = false;
@@ -130,13 +131,28 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
       reasons.push(reason('session-holder-role-binding-unresolved', 'The selected recipient Role does not assign itself to this consuming session. Supply an explicit matching session holder Role binding before act-ready continuation.'));
     }
 
+    if (holderState === 'not-applicable') {
+      holderBindingActReady = true;
+      known.push(evidence('session-holder-role-binding-authorization', 'not-applicable', 'selected Handoff recipient is not a Role endpoint'));
+    } else if (holderState === 'qualified') {
+      if (holderAuthorizationState === 'qualified') {
+        holderBindingActReady = true;
+        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.'));
+      }
+    }
+
     const required = Array.isArray(requiredContext) ? requiredContext : [];
     const unresolvedRequired = required.filter((entry) => entry.state !== 'qualified');
     if (unresolvedRequired.length) missing(missingEvidence, unresolved, 'required-context-unqualified', `${unresolvedRequired.length} declared Required Context item(s) are not exact-qualified.`);
     else known.push(evidence('required-context-closure', 'qualified', `${required.length} item(s)`));
     if (String(continuation?.state || '') !== 'ready') missing(missingEvidence, unresolved, 'continuation-not-ready', 'The grounded continuation is not ready for substantive work.');
-    if (String(contextAudit?.status || '') !== 'ready' || String(contextAudit?.coverage?.state || '') !== 'qualified') missing(missingEvidence, unresolved, 'workspace-snapshot-coverage-unqualified', 'Complete carried Workspace snapshot coverage is not qualified.');
-    else known.push(evidence('workspace-snapshot-coverage', 'qualified', `${contextAudit.workspaceMaterializations?.length || 0} workspace(s)`));
+    const workspaceCoverage = projectWorkspaceActionCoverage(contextAudit);
+    if (!workspaceCoverage.qualified) missing(missingEvidence, unresolved, 'workspace-snapshot-coverage-unqualified', workspaceCoverage.message);
+    else known.push(evidence('workspace-snapshot-coverage', 'qualified', `${workspaceCoverage.count} workspace representation(s): ${workspaceCoverage.completeCount} complete, ${workspaceCoverage.boundedCount} bounded`));
     for (const item of requiredRecordResolution.missing) missing(missingEvidence, unresolved, 'required-context-not-in-snapshot', item);
     if (!routeRecordIds.size) missing(missingEvidence, unresolved, 'selected-route-not-in-snapshot', 'The qualified selected Handoff route was not found at its exact carried Workspace path.');
   } else {
@@ -147,7 +163,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
   if (!records.length) missing(missingEvidence, unresolved, 'no-artifact-records', 'No readable Tiinex artifact records were loaded for grounding.');
   else known.push(evidence('loaded-artifact-records', 'known', `${records.length} record(s)`));
 
-  inferred.push(evidence('relevant-lineage-scope', 'bounded-inference', handoffMode ? 'directed declared-Parent cone around the exact selected Handoff route within complete carried Workspace snapshots plus independently qualified exact detached Parent-boundary cache records' : 'all loaded records'));
+  inferred.push(evidence('relevant-lineage-scope', 'bounded-inference', handoffMode ? 'directed declared-Parent cone around the exact selected Handoff route within qualified carried Workspace representations (complete or bounded as declared) plus independently qualified exact detached Parent-boundary cache records' : 'all loaded records'));
   inferred.push(evidence('lineage-leaf-role', 'bounded-inference', 'derived only from declared Parent edges in the shared resolver'));
 
   if (handoffMode) {
@@ -156,7 +172,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
     } else if (topology.routeLeaves.length) {
       known.push(evidence('selected-route-parent-lineage-leaf', 'resolved', `${topology.routeLeaves.length} selected-route leaf/leaves`));
     } else {
-      missing(missingEvidence, unresolved, 'selected-route-lineage-leaf-missing', 'The selected Handoff route is not a resolved Parent-lineage leaf in the complete carried Workspace snapshots.');
+      missing(missingEvidence, unresolved, 'selected-route-lineage-leaf-missing', 'The selected Handoff route is not a resolved Parent-lineage leaf in the qualified carried Workspace material.');
     }
     if (lineageIssues.length > routeBlockingLineageIssues.length) unresolved.push(evidence('upstream-lineage-diagnostics', continuity.state === 'qualified' ? 'degraded-nonblocking' : 'blocking-for-cold-start-continuity', `${lineageIssues.length - routeBlockingLineageIssues.length} upstream Parent-lineage issue(s) remain outside the selected-route edge boundary.`));
   } else if (lineageIssues.length) {
@@ -189,7 +205,8 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
   let state = 'grounded-to-act';
   if (missingEvidence.length) state = 'insufficient-grounding';
   else if (!handoffMode || !holderBindingActReady || !topology.currentFrontier.length || humanOnly.length) state = 'grounded-to-discuss';
-  if (state === 'grounded-to-act') reasons.push(reason('bounded-act-ready', 'Selected Handoff authority, explicit consuming-session holder Role binding, Required Context, carried Workspace coverage, cold-start continuity to a qualified semantic root, the selected-route Parent-lineage leaf, and declared current-work frontier evidence are all resolved enough for the next bounded action.'));
+  if (state === 'grounded-to-act') reasons.push(reason('bounded-act-ready', 'Selected Handoff authority, explicit consuming-session holder Role binding, exact qualified holder-assignment authorization where the recipient is a Role, exact Required Context, qualified carried Workspace coverage (complete or bounded as declared), cold-start continuity to a qualified semantic root, the selected-route Parent-lineage leaf, and declared current-work frontier evidence are all resolved enough for the next bounded action.'));
+  const orchestrationReadiness = projectGroundingOrchestrationReadiness({ readinessState: state, participantContext: capsule.participantContext, processApplicability: capsule.processApplicability, sourceEvidence: capsule.sourceEvidence, topology });
 
   return Object.freeze({
     schema: PORTABLE_GROUNDING_READINESS_SCHEMA_ID,
@@ -216,11 +233,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
         requestedSelectors: requiredContextProjection.requestedSelectors,
         unmatchedSelectors: requiredContextProjection.unmatchedSelectors
       }),
-      workspaceSnapshots: contextAudit ? Object.freeze({
-        state: String(contextAudit.coverage?.state || contextAudit.status || 'unresolved'),
-        qualified: String(contextAudit.status || '') === 'ready',
-        count: contextAudit.workspaceMaterializations?.length || 0
-      }) : Object.freeze({ state: 'not-supplied', qualified: false, count: 0 })
+      workspaceSnapshots: contextAudit ? projectWorkspaceActionCoverage(contextAudit) : Object.freeze({ state: 'not-supplied', qualified: false, count: 0, completeCount: 0, boundedCount: 0, unqualified: Object.freeze([]), message: 'No carried Workspace context audit was supplied.' })
     }),
     lineage: Object.freeze({
       state: handoffMode ? (routeBlockingLineageIssues.length ? 'unresolved' : topology.routeLeaves.length ? (lineageIssues.length ? 'resolved-with-upstream-degradation' : 'resolved') : 'missing-leaf') : (lineageIssues.length ? 'unresolved' : topology.leaves.length ? 'resolved' : 'missing-leaf'),
@@ -240,6 +253,7 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
       boundary: 'Leaf/root roles are derived only from loaded declared Parent edges produced by the shared lineage resolver. Filename numbering, carrier dimensions, directory depth, branch names, and Task lifecycle labels are never substituted for Parent topology.'
     }),
     continuity,
+    orchestrationReadiness,
     capsule,
     currentWork: Object.freeze({
       state: topology.currentFrontier.length ? 'current-frontier-resolved' : topology.currentTasks.length ? 'current-candidates-without-frontier' : 'unresolved',
@@ -274,6 +288,47 @@ export function composeGroundingReadiness({ mode = 'loaded-material', authority
   });
 }
 
+function projectWorkspaceActionCoverage(contextAudit = {}) {
+  const workspaces = Array.isArray(contextAudit?.workspaceMaterializations) ? contextAudit.workspaceMaterializations : [];
+  const summaries = workspaces.map((workspace) => {
+    const coverage = workspaceCoverageState(workspace);
+    const qualification = String(workspace?.qualification || '').trim().toLowerCase();
+    const qualified = ['complete', 'bounded'].includes(coverage) && qualification === 'qualified';
+    return Object.freeze({ workspaceId: String(workspace?.workspaceId || ''), coverage, qualification: qualification || 'unresolved', qualified });
+  });
+  const aggregateReady = String(contextAudit?.status || '') === 'ready' && String(contextAudit?.coverage?.state || '') === 'qualified';
+  const qualified = aggregateReady && summaries.length > 0 && summaries.every((item) => item.qualified);
+  const completeCount = summaries.filter((item) => item.coverage === 'complete').length;
+  const boundedCount = summaries.filter((item) => item.coverage === 'bounded').length;
+  const unqualified = summaries.filter((item) => !item.qualified);
+  const message = qualified
+    ? `Qualified carried Workspace coverage is established for ${summaries.length} representation(s): ${completeCount} complete, ${boundedCount} bounded.`
+    : !aggregateReady
+      ? 'Carried Workspace context audit is not qualified for bounded action readiness.'
+      : !summaries.length
+        ? 'No qualified carried Workspace representation is available for the selected Handoff route.'
+        : `Carried Workspace representation qualification is incomplete for ${unqualified.length} workspace(s); bounded carriage is actionable only when each carried representation is independently qualified as complete or bounded.`;
+  return Object.freeze({
+    state: qualified ? 'qualified' : 'unqualified',
+    qualified,
+    count: summaries.length,
+    completeCount,
+    boundedCount,
+    unqualified: Object.freeze(unqualified),
+    message,
+    boundary: 'Complete and bounded carriage remain distinct. Bounded coverage can satisfy current-route action readiness only when the carried representation itself is qualified; it never implies whole-Workspace or whole-program authority.'
+  });
+}
+
+function workspaceCoverageState(workspace = {}) {
+  const explicit = String(workspace?.coverage || workspace?.materialization || '').trim().toLowerCase();
+  if (explicit === 'complete' || explicit === 'bounded') return explicit;
+  const reason = String(workspace?.reason || '').trim().toLowerCase();
+  if (reason.includes('bounded') || reason.includes('partial')) return 'bounded';
+  if (reason.includes('complete')) return 'complete';
+  return 'unresolved';
+}
+
 function projectCurrentWork(topology = {}, records = [], includeCurrentWork = false) {
   const recordById = new Map((records || []).map((record) => [String(record.id || ''), record]));
   const frontier = (topology.currentFrontier || []).slice(0, MAX_ITEMS).map((item) => {
@@ -297,8 +352,13 @@ function projectCurrentWork(topology = {}, records = [], includeCurrentWork = fa
 }
 
 function nextActionFor(state, topology, continuity = {}, authority = null) {
-  if (state === 'grounded-to-act') return Object.freeze({ kind: 'continue-bounded-handoff-work', target: topology.currentFrontier[0]?.path || '', basis: 'qualified authority + explicit session holder Role binding + required context + cold-start root continuity + selected-route Parent leaf + declared current-work frontier' });
+  if (state === 'grounded-to-act') return Object.freeze({ kind: 'continue-bounded-handoff-work', target: topology.currentFrontier[0]?.path || '', basis: 'qualified authority + explicit session holder Role binding + exact qualified holder-assignment authorization when Role-recipient + required context + cold-start root continuity + selected-route Parent leaf + declared current-work frontier' });
   if (state === 'grounded-to-discuss' && String(authority?.holderBinding?.state || 'unresolved') === 'unresolved') return Object.freeze({ kind: 'declare-explicit-session-holder-role-binding', target: authority?.role?.endpoint?.label || authority?.handoff?.to || '', basis: 'recipient Role qualification is separate from consuming-session holder binding; no transport/provider/assistant-user identity inference is permitted' });
+  if (state === 'grounded-to-discuss' && String(authority?.holderBinding?.state || '') === 'qualified' && String(authority?.holderBinding?.authorization?.state || 'unresolved') !== 'qualified') return Object.freeze({
+    kind: 'resolve-session-holder-binding-authorization',
+    target: authority?.holderBinding?.authorization?.provenance?.roleArtifactPath || authority?.role?.endpoint?.label || authority?.handoff?.to || '',
+    basis: 'a matching explicit session Role assertion is not semantic authorization; exact qualified recipient Role Holder Relationship authority must establish the assignment mode'
+  });
   if (state === 'grounded-to-discuss') return Object.freeze({ kind: topology.currentFrontier.length ? 'obtain-bounded-action-authority-or-human-gate' : 'resolve-current-work-frontier', target: topology.currentTasks[0]?.path || '', basis: 'discussion-ready but act-readiness condition is unresolved' });
   if (continuity?.state === 'unproven') return Object.freeze({
     kind: continuity.recovery?.state === 'host-action-available' ? 'recover-required-parent-with-host-action' : 'request-exact-required-parent-material',

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

@@ -122,12 +122,16 @@ export function projectRequiredContext(requiredContext = [], selectors = []) {
     return Object.freeze({
       requirementId: entry.requirementId || '',
       name: entry.name || '',
+      material: entry.material || '',
+      purpose: entry.purpose || '',
+      declaredAvailability: entry.declaredAvailability || '',
       state: entry.state || '',
       workspaceId: entry.workspaceId || '',
       innerPath: entry.innerPath || entry.workspaceRelativePath || '',
       referenceTarget: entry.referenceTarget || '',
       bytes: Number(entry.bytes || entry.actualBytes || 0),
       sha256: entry.sha256 || entry.actualSha256 || '',
+      provenance: entry.provenance ? Object.freeze({ ...entry.provenance }) : null,
       contentProjected,
       ...(contentProjected ? { content: entry.content } : {})
     });
@@ -164,7 +168,7 @@ export function resolveRequiredContextRecords(requiredContext = [], records = []
     const record = byPath.get(expectedPath);
     if (record) { ids.add(record.id); matched += 1; continue; }
     if (isExactHydratedWorkspaceContext(entry)) { matched += 1; continue; }
-    missing.push(`${entry.requirementId || entry.name || expectedPath}: exact qualified context was not found at ${expectedPath} inside the complete carried Workspace snapshots.`);
+    missing.push(`${entry.requirementId || entry.name || expectedPath}: exact qualified context was not found at ${expectedPath} inside the qualified carried Workspace material.`);
   }
   return Object.freeze({ ids, matched, missing: Object.freeze(missing) });
 }

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

@@ -1,12 +1,17 @@
 import { parseWorkspaceEntrypoints } from '../handoff/workspaceSourceIdentity.js';
 const MAX_WORKSPACES = 8;
 const MAX_SOURCES = 8;
+const MAX_MATERIALS = 12;
+const MAX_BLOCKERS = 8;
 
-export function projectGroundingSourceEvidence({ records = [], contextAudit = null, continuation = null, sourceProfiles = [] } = {}) {
+export function projectGroundingSourceEvidence({ records = [], contextAudit = null, continuation = null, requiredContext = [], sourceProfiles = [] } = {}) {
   const byPath = new Map((records || []).map((record) => [String(record.path || ''), record]));
   const profiles = profileIndex(sourceProfiles);
+  const coverageByWorkspace = new Map();
   const workspaces = (contextAudit?.workspaceMaterializations || []).slice(0, MAX_WORKSPACES).map((workspace) => {
     const workspaceId = String(workspace.workspaceId || '');
+    const coverage = normalizeCoverage(workspace);
+    if (workspaceId) coverageByWorkspace.set(workspaceId, coverage);
     const innerPath = normalizePath(workspace.sourceWorkspaceTargetInnerPath || '');
     const exactPath = workspaceId && innerPath ? `${workspaceId}/${innerPath}` : '';
     const record = exactPath ? byPath.get(exactPath) : null;
@@ -21,10 +26,21 @@ export function projectGroundingSourceEvidence({ records = [], contextAudit = nu
       && record.hasContinuityContext
       && record.hasIntegrity
     );
-    if (!qualifiedArtifact && !explicitProfile.length) return Object.freeze({ workspace: workspaceId, state: 'unresolved' });
+    if (!qualifiedArtifact && !explicitProfile.length) return Object.freeze({
+      workspace: workspaceId,
+      state: 'unresolved',
+      coverage,
+      carrier: String(workspace.reason || ''),
+      provenance: Object.freeze({
+        basis: 'carried-workspace-materialization-without-qualified-source-declaration',
+        sourceArtifactPath: exactPath,
+        boundary: 'Workspace carriage alone does not establish repository/source identity.'
+      })
+    });
     return Object.freeze({
       workspace: workspaceId,
       state: qualifiedArtifact ? 'qualified' : 'explicit-profile',
+      coverage,
       carrier: String(workspace.reason || 'qualified-workspace-snapshot'),
       sourceArtifactPath: exactPath,
       sourceArtifactSha256: String(workspace.sourceWorkspaceTargetSha256 || ''),
@@ -32,20 +48,150 @@ export function projectGroundingSourceEvidence({ records = [], contextAudit = nu
       ref: String(unique?.ref || ''),
       rootPath: String(unique?.rootPath || ''),
       remoteState: String(unique?.remoteState || 'not-checked'),
-      sources: Object.freeze(sources.slice(0, MAX_SOURCES))
+      sources: Object.freeze(sources.slice(0, MAX_SOURCES)),
+      provenance: Object.freeze({
+        basis: qualifiedArtifact ? 'exact-qualified-workspace-source-artifact' : 'explicit-source-profile',
+        sourceArtifactPath: exactPath,
+        sourceArtifactSha256: String(workspace.sourceWorkspaceTargetSha256 || ''),
+        coverageBasis: String(workspace.reason || ''),
+        boundary: qualifiedArtifact
+          ? 'Source identity is projected only from the exact qualified Workspace artifact carried for this Workspace.'
+          : 'Source identity is projected only from an explicitly supplied source profile; no repository discovery is implied.'
+      })
     });
   });
+
+  const requirements = (requiredContext || []).slice(0, MAX_MATERIALS).map((entry) => projectRequirement(entry, coverageByWorkspace));
+  const unavailable = requirements.filter((entry) => entry.availability === 'unavailable');
+  const blockers = unavailable.slice(0, MAX_BLOCKERS).map((entry) => Object.freeze({
+    code: 'authoritative-material-unavailable',
+    requirementId: entry.requirementId,
+    name: entry.name,
+    requiredMaterial: Object.freeze({
+      material: entry.material,
+      referenceTarget: entry.referenceTarget,
+      workspace: entry.workspace,
+      path: entry.path
+    }),
+    owner: Object.freeze({
+      kind: 'selected-handoff-required-context',
+      requirementId: entry.requirementId,
+      name: entry.name,
+      purpose: entry.purpose
+    }),
+    basis: Object.freeze({
+      state: entry.state,
+      availability: entry.availability,
+      materialClass: entry.materialClass,
+      workspaceCoverage: entry.workspaceCoverage,
+      providerMode: entry.providerMode,
+      kind: entry.kind,
+      provenance: entry.provenance
+    }),
+    blockingReason: 'The exact declared Required Context material is not qualified in current carried/explicit material, so Tooling cannot claim that authority is available.',
+    workspace: entry.workspace,
+    path: entry.path,
+    referenceTarget: entry.referenceTarget,
+    request: exactMaterialRequest(entry)
+  }));
+  const boundedOrCache = requirements.filter((entry) => entry.availability === 'qualified' && ['bounded-workspace', 'cache'].includes(entry.materialClass));
+  const contextMaterials = [
+    ...(contextAudit?.materialCarriers || []).map((item) => projectAuditMaterial(item, 'requirement-material')),
+    ...(contextAudit?.explicitDetachedMaterial || []).map((item) => projectAuditMaterial(item, 'bounded-or-cache-material')),
+    ...(contextAudit?.lineageMaterializations || []).map((item) => projectAuditMaterial(item, 'lineage-cache-material'))
+  ].slice(0, MAX_MATERIALS);
+
   return Object.freeze({
     carrier: Object.freeze({
       state: String(contextAudit?.coverage?.state || contextAudit?.status || 'unresolved'),
       workspaceCount: Number(contextAudit?.workspaceMaterializations?.length || 0),
-      packageSourcePath: String(continuation?.packageSourcePath || '')
+      packageSourcePath: String(continuation?.packageSourcePath || ''),
+      completeWorkspaceCount: workspaces.filter((item) => item.coverage === 'complete').length,
+      boundedWorkspaceCount: workspaces.filter((item) => item.coverage === 'bounded').length
     }),
     workspaces: Object.freeze(workspaces),
-    boundary: 'Exact selected Workspace source artifact/profile only.'
+    requirements: Object.freeze(requirements),
+    boundedOrCache: Object.freeze(boundedOrCache),
+    carriedMaterial: Object.freeze(contextMaterials),
+    blockers: Object.freeze(blockers),
+    boundary: 'Exact selected Workspace/source declarations and exact qualified Required Context material only. Complete Workspace carriage, bounded Workspace/cache material, explicit requirements, and unavailable authoritative material remain distinct. Missing material never authorizes repository, connector, or network discovery.'
+  });
+}
+
+function projectRequirement(entry = {}, coverageByWorkspace = new Map()) {
+  const state = String(entry.state || 'unresolved');
+  const providerMode = String(entry.providerMode || '');
+  const workspace = String(entry.workspaceId || '');
+  const workspaceCoverage = coverageByWorkspace.get(workspace) || 'unresolved';
+  let materialClass = 'explicit-requirement';
+  if (state === 'qualified') {
+    if (providerMode === 'cache' || String(entry.kind || '') === 'workspace-cache-entry') materialClass = 'cache';
+    else if (providerMode === 'archive' && workspaceCoverage === 'bounded') materialClass = 'bounded-workspace';
+    else if (providerMode === 'archive' && workspaceCoverage === 'complete') materialClass = 'complete-workspace';
+    else if (providerMode === 'archive') materialClass = 'workspace-material';
+    else materialClass = 'qualified-material';
+  }
+  return Object.freeze({
+    requirementId: String(entry.requirementId || ''),
+    name: String(entry.name || ''),
+    material: String(entry.material || ''),
+    purpose: String(entry.purpose || ''),
+    declaredAvailability: String(entry.declaredAvailability || ''),
+    state,
+    availability: state === 'qualified' ? 'qualified' : 'unavailable',
+    materialClass,
+    workspace,
+    workspaceCoverage,
+    path: String(entry.innerPath || entry.workspaceRelativePath || ''),
+    packagePath: String(entry.packagePath || entry.archivePackagePath || ''),
+    providerMode,
+    kind: String(entry.kind || ''),
+    referenceTarget: String(entry.referenceTarget || ''),
+    bytes: Number(entry.bytes || 0),
+    sha256: String(entry.sha256 || ''),
+    provenance: Object.freeze({
+      basis: String(entry.provenance?.basis || 'selected-handoff-required-context-and-route-closure'),
+      declarationSource: entry.provenance?.declarationSource ? Object.freeze({ ...(entry.provenance.declarationSource || {}) }) : null,
+      resolutionKind: String(entry.provenance?.resolutionKind || entry.kind || ''),
+      providerMode: String(entry.provenance?.providerMode || providerMode),
+      boundary: String(entry.provenance?.boundary || 'Requirement identity comes from the selected Handoff declaration; qualification/material class comes from exact route closure and carried source state.')
+    })
+  });
+}
+
+function projectAuditMaterial(item = {}, classification = '') {
+  return Object.freeze({
+    classification,
+    requirementId: String(item.requirementId || item.requirement?.id || ''),
+    name: String(item.requirement?.name || ''),
+    workspace: String(item.workspaceId || item.targetWorkspaceId || item.selectedProvider?.workspaceId || ''),
+    path: String(item.workspaceRelativePath || item.targetPath || item.originalPath || item.selectedProvider?.workspaceRelativePath || ''),
+    packagePath: String(item.path || item.archivePackagePath || ''),
+    bytes: Number(item.bytes || item.actualBytes || 0),
+    sha256: String(item.sha256 || item.actualSha256 || ''),
+    authority: Object.freeze({ ...(item.authority || {}) }),
+    provenance: Object.freeze({
+      basis: classification,
+      carrierPath: String(item.path || item.archivePackagePath || ''),
+      boundary: 'Diagnostic carriage evidence only; presence does not create semantic authority beyond the requirement/material it exactly resolves.'
+    })
   });
 }
 
+function exactMaterialRequest(entry = {}) {
+  const target = entry.referenceTarget || [entry.workspace, entry.path].filter(Boolean).join('::') || entry.name || entry.requirementId || 'the declared Required Context material';
+  return `Provide exact qualified material for ${target}, or an explicitly qualified bounded Workspace/cache carrier that resolves this declared requirement. Do not substitute GitHub, a connector, a repository checkout, or network discovery without separate authority.`;
+}
+
+function normalizeCoverage(workspace = {}) {
+  const explicit = String(workspace.coverage || '').trim().toLowerCase();
+  if (explicit === 'complete' || explicit === 'bounded') return explicit;
+  const reason = String(workspace.reason || '').toLowerCase();
+  if (reason.includes('bounded') || reason.includes('partial')) return 'bounded';
+  if (reason.includes('complete')) return 'complete';
+  return 'unresolved';
+}
+
 function profileIndex(value = []) {
   const map = new Map();
   if (!value) return map;
@@ -64,8 +210,4 @@ function profileIndex(value = []) {
 }
 function normalizeProfileList(value) { return (Array.isArray(value) ? value : [value]).filter(Boolean).map(normalizeProfile); }
 function normalizeProfile(value = {}) { return Object.freeze({ label: String(value.label || ''), sourceKind: String(value.sourceKind || value.kind || ''), repository: String(value.repository || ''), ref: String(value.ref || ''), rootPath: String(value.rootPath || ''), remoteState: String(value.remoteState || 'not-checked'), basis: 'explicit-source-profile' }); }
-function section(markdown = '', heading = '') { const escaped = escape(heading); return String(markdown || '').match(new RegExp(`(?:^|\\n)##\\s+${escaped}\\s*\\r?\\n([\\s\\S]*?)(?=\\n##\\s+|\\n#\\s+Continuity Integrity|$)`, 'i'))?.[1]?.trim() || ''; }
-function field(markdown = '', label = '') { const escaped = escape(label); return strip(String(markdown || '').match(new RegExp(`^\\s*-\\s+${escaped}:\\s*(.+)$`, 'mi'))?.[1] || ''); }
 function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, ''); }
-function strip(value = '') { return String(value || '').replace(/^\[([^\]]+)\]\([^)]+\)$/, '$1').replace(/[`*_]/g, '').trim(); }
-function escape(value = '') { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

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

@@ -76,7 +76,18 @@ function qualifyRequiredRequirement(bundle, descriptor, byteProvider, workspace,
   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);
-  return deepFreeze({requirementId:String(requirement.id||''),name:String(requirement.name||''),referenceTarget:target,state:!reasons.length&&resolution?.state==='qualified'?'qualified':'blocked',resolution:resolution?.state==='qualified'?resolution:null,reasons:Object.freeze([...new Set(reasons)])});
+  return deepFreeze({
+    requirementId:String(requirement.id||''),
+    name:String(requirement.name||''),
+    material:String(requirement.material||''),
+    purpose:String(requirement.purpose||''),
+    declaredAvailability:String(requirement.availability||''),
+    referenceTarget:target,
+    declarationSource:requirement.source||null,
+    state:!reasons.length&&resolution?.state==='qualified'?'qualified':'blocked',
+    resolution:resolution?.state==='qualified'?resolution:null,
+    reasons:Object.freeze([...new Set(reasons)])
+  });
 }
 
 function resolveWorkspaceRequiredMaterial(byteProvider, workspace, resolvedPath) {

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

@@ -31,6 +31,7 @@ import {
   normalizeStringList,
   normalizeToken
 } from './coldStartQualification.shared.js';
+import { projectHolderBindingAuthorization } from '../grounding/grounding.holderBindingAuthorization.js';
 
 export function groundPortableColdConsumer(input = {}, options = {}) {
   const ingressKind = normalizeIngressKind(input.ingressKind || input.kind || (input.toolingAvailable === false ? COLD_START_INGRESS_KINDS.DEGRADED_CAPTURE : COLD_START_INGRESS_KINDS.HANDOFF));
@@ -59,7 +60,7 @@ export function groundPortableColdConsumer(input = {}, options = {}) {
 
   const bundle = input.bundle || input.package || input;
   const role = groundRecipientRole(input, handoff, bundle, orientation, selectedRoute, findings, materialContext);
-  const holderBinding = groundHolderBinding(input, handoff, findings);
+  const holderBinding = groundHolderBinding(input, handoff, role, findings);
   const participation = groundParticipation(input, handoff, bundle, orientation, selectedRoute, findings, materialContext);
   const interaction = groundInteraction(input, handoff);
 
@@ -68,7 +69,12 @@ export function groundPortableColdConsumer(input = {}, options = {}) {
   }
 
   const blocked = findings.some((finding) => finding.severity === 'error');
-  const degraded = degradedCapture.active || role.state === 'degraded' || holderBinding.state === 'unresolved' || interaction.modeState === 'unresolved' || participation.participantState === 'unresolved';
+  const degraded = degradedCapture.active
+    || role.state === 'degraded'
+    || holderBinding.state === 'unresolved'
+    || holderBinding.authorization?.state === 'unresolved'
+    || interaction.modeState === 'unresolved'
+    || participation.participantState === 'unresolved';
   return deepFreeze({
     schema: PORTABLE_COLD_CONSUMER_GROUNDING_SCHEMA_ID,
     version: 1,
@@ -178,13 +184,14 @@ function groundRecipientRole(input, handoff, bundle, orientation, selectedRoute,
     compatibility,
     exactBoundaryLoaded: selected ? selected.boundary : null,
     authorityBoundaryLoaded: selected ? selected.authorityBoundary : null,
+    holderRelationshipLoaded: selected ? selected.holderRelationship : null,
     interpretationLimitsLoaded: selected ? selected.interpretationLimits : null,
     boundary: 'A Handoff `To Kind: role` endpoint remains bounded even when current Role material is missing. Matching Role material qualifies the loaded boundary but does not prove a human holder, consent, or authority beyond the Role artifact itself.'
   });
 }
 
 
-function groundHolderBinding(input, handoff, findings) {
+function groundHolderBinding(input, handoff, role, findings) {
   const raw = input.holderBinding || input.sessionHolderBinding || input.sessionRoleBinding || {};
   const explicit = typeof raw === 'string' ? { roleLabel: raw } : (raw && typeof raw === 'object' ? raw : {});
   const roleLabel = String(explicit.roleLabel || explicit.role || input.holderRole || input.sessionRole || '').trim();
@@ -193,6 +200,9 @@ function groundHolderBinding(input, handoff, findings) {
   const recipientRoleKind = normalizeToken(handoff.toKind || (recipientRoleLabel ? 'role' : ''));
   const roleRecipient = recipientRoleKind === 'role';
   const explicitlySupplied = Boolean(roleLabel || holderId);
+  const sourceDetail = holderBindingSourceDetail(input, explicit, explicitlySupplied);
+  const authorization = projectHolderBindingAuthorization(role);
+  const durableIdentity = holderDurableIdentityProjection(holderId);
 
   if (!roleRecipient) return deepFreeze({
     state: 'not-applicable',
@@ -201,6 +211,9 @@ function groundHolderBinding(input, handoff, findings) {
     recipientRoleLabel,
     recipientCompatibility: 'not-applicable',
     source: explicitlySupplied ? 'explicit-input' : 'none',
+    sourceDetail,
+    authorization,
+    durableIdentity,
     explicit: explicitlySupplied,
     inferredFromTransport: false,
     boundary: 'The selected Handoff recipient is not a Role endpoint, so no consuming-session Role holder binding is required or inferred.'
@@ -215,6 +228,9 @@ function groundHolderBinding(input, handoff, findings) {
       recipientRoleLabel,
       recipientCompatibility: 'unresolved',
       source: explicitlySupplied ? 'explicit-input' : 'none',
+      sourceDetail,
+      authorization,
+      durableIdentity,
       explicit: explicitlySupplied,
       inferredFromTransport: false,
       boundary: 'Recipient Role and consuming-session holder are separate. No holder Role is inferred from route selection, transport identity, provider identity, assistant/user position, or participant declarations.'
@@ -230,6 +246,9 @@ function groundHolderBinding(input, handoff, findings) {
       recipientRoleLabel,
       recipientCompatibility: 'mismatch',
       source: 'explicit-input',
+      sourceDetail,
+      authorization,
+      durableIdentity,
       explicit: true,
       inferredFromTransport: false,
       boundary: 'An explicit holder Role mismatch is contradictory and blocks act-ready grounding. Tooling does not relabel the session to make the route fit.'
@@ -243,12 +262,52 @@ function groundHolderBinding(input, handoff, findings) {
     recipientRoleLabel,
     recipientCompatibility: 'matched',
     source: 'explicit-input',
+    sourceDetail,
+    authorization,
+    durableIdentity,
     explicit: true,
     inferredFromTransport: false,
     boundary: 'Explicit consuming-session Role-capacity binding only. This binds the current Tooling invocation/session to the selected recipient Role capacity; it does not prove a human identity, consent, or authority beyond the qualified Handoff/Role/Task boundaries.'
   });
 }
 
+function holderDurableIdentityProjection(holderId = '') {
+  return deepFreeze({
+    state: 'not-established',
+    declaredHolderId: String(holderId || ''),
+    boundary: 'A bounded session Role assertion and its assignment authorization do not establish durable Party/person/model holder identity. Exact holder/Party authority would be required separately.'
+  });
+}
+
+function holderBindingSourceDetail(input = {}, explicit = {}, explicitlySupplied = false) {
+  if (!explicitlySupplied) return deepFreeze({
+    kind: 'none',
+    locator: '',
+    authorityClass: 'none',
+    semanticAuthorityState: 'not-established',
+    qualifiedMaterialSource: false,
+    boundary: 'No consuming-session holder declaration was supplied.'
+  });
+  const declaredLocator = String(explicit.sourceLocator || explicit.source || '').trim();
+  let locator = declaredLocator;
+  if (!locator) {
+    if (input.holderBinding) locator = 'input.holderBinding';
+    else if (input.sessionHolderBinding) locator = 'input.sessionHolderBinding';
+    else if (input.sessionRoleBinding) locator = 'input.sessionRoleBinding';
+    else if (input.holderRole || input.holderId) locator = 'input.holderRole/input.holderId';
+    else if (input.sessionRole) locator = 'input.sessionRole';
+    else locator = 'explicit-session-input';
+  }
+  return deepFreeze({
+    kind: 'operator-session-input',
+    locator,
+    authorityClass: 'session-binding-input-only',
+    semanticAuthorityState: 'not-established',
+    qualifiedMaterialSource: false,
+    boundary: 'This source proves only the explicit consuming-session Role-capacity declaration supplied to Tooling. It is not semantic holder-assignment authority carried by qualified material.'
+  });
+}
+
 function groundParticipation(input, handoff, bundle, orientation, selectedRoute, findings, materialContext) {
   const explicitParticipants = normalizeParticipants(input.participants || input.interaction?.participants || []);
   const packageRoleGrounding = resolvePackageParticipantRoles(bundle, orientation, selectedRoute, findings);

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

@@ -160,6 +160,7 @@ export function parseRoleMaterial(entry) {
     const roleSection = sectionText(parsed.body?.text || '', 'Role Identity');
     const boundarySection = sectionText(parsed.body?.text || '', 'Role Boundary');
     const authoritySection = sectionText(parsed.body?.text || '', 'Authority And Responsibility Boundary');
+    const holderSection = sectionText(parsed.body?.text || '', 'Holder Relationship');
     const limitsSection = sectionText(parsed.body?.text || '', 'Interpretation Limits');
     const label = sectionField(roleSection, 'Role Label');
     return deepFreeze({
@@ -172,6 +173,13 @@ export function parseRoleMaterial(entry) {
       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') }),
+      holderRelationship: Object.freeze({
+        holderState: sectionField(holderSection, 'Holder State'),
+        currentHolder: sectionField(holderSection, 'Current Holder'),
+        possibleHolder: sectionField(holderSection, 'Possible Holder'),
+        unknownHolder: sectionField(holderSection, 'Unknown Holder'),
+        relationArtifact: sectionReferenceTarget(holderSection, 'Relation Artifact')
+      }),
       interpretationLimits: Object.freeze({ doesNotProve: sectionField(limitsSection, 'Does Not Prove'), mustNotBeTreatedAs: sectionField(limitsSection, 'Must Not Be Treated As') }),
       parentTrace: String(parsed.envelope?.parent?.trace || ''),
       parentSchemaId: String(parsed.envelope?.parent?.schema?.id || '')
@@ -232,6 +240,9 @@ function hydrateRequiredContextEntry(bundle = {}, entry = {}, context = null) {
   const base = {
     requirementId: String(entry.requirementId || ''),
     name: String(entry.name || ''),
+    material: String(entry.material || ''),
+    purpose: String(entry.purpose || ''),
+    declaredAvailability: String(entry.declaredAvailability || ''),
     state: String(entry.state || resolution.state || 'unresolved'),
     referenceTarget: String(entry.referenceTarget || ''),
     kind: String(resolution.kind || ''),
@@ -241,7 +252,14 @@ function hydrateRequiredContextEntry(bundle = {}, entry = {}, context = null) {
     packagePath: String(resolution.packagePath || ''),
     providerMode: String(resolution.providerMode || ''),
     bytes: Number(resolution.bytes || 0),
-    sha256: String(resolution.sha256 || '')
+    sha256: String(resolution.sha256 || ''),
+    provenance: Object.freeze({
+      basis: 'selected-handoff-required-context-declaration',
+      declarationSource: entry.declarationSource ? Object.freeze({ ...(entry.declarationSource || {}) }) : null,
+      resolutionKind: String(resolution.kind || ''),
+      providerMode: String(resolution.providerMode || ''),
+      boundary: 'Material/Purpose/Availability are copied from the exact selected Handoff Required Context declaration; qualification and bytes come from exact route closure resolution.'
+    })
   };
   if (base.state !== 'qualified') return Object.freeze({ ...base, contentState: 'unavailable', content: '' });
   const hydrated = resolveQualifiedMaterialBytes(bundle, resolution, context);

package/src/tooling/portable/handoff/contextAudit.js

@@ -184,7 +184,7 @@ function auditRecipientV2(bundle = {}) {
         sha256: String(material.sha256 || '')
       })))
     : [];
-  return deepFreeze({ schema: PORTABLE_HANDOFF_CONTEXT_AUDIT_SCHEMA_ID, status: inspection.status === 'valid' && !unexplained ? 'ready' : 'blocked', coverage: Object.freeze({ nonControlCarrierCount: files.length, classifiedCarrierCount: classified, unexplainedCarrierCount: unexplained, state: unexplained ? 'incomplete' : 'qualified' }), workspaceMaterializations: Object.freeze((inspection.workspaces || []).map((item) => Object.freeze({ workspaceId: item.workspaceId, reason: 'complete-workspace-archive-representation', qualification: 'qualified', carrierMode: 'archive', workspaceTargetPackagePath: item.workspaceArtifactPath, archivePackagePath: item.workspaceArchivePath, sourceWorkspaceTargetInnerPath: item.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.sourceWorkspaceTargetSha256 }))), lineageMaterializations: Object.freeze(lineageMaterializations), materialCarriers: Object.freeze([]), generatedEntrypoints: Object.freeze([String(inspection.rootArtifact?.path || ''), RECIPIENT_V2_READ_PATH, ...(inspection.endpointRoles || []).map((item) => item.pointerPath), ...(inspection.participantRoles || []).map((item) => item.pointerPath), ...(inspection.routes || []).map((item) => item.pointerPath)].filter(Boolean)), namedPackageRequirements: Object.freeze([]), explicitDetachedMaterial: Object.freeze(cacheMaterials), unexplainedCarriers: Object.freeze([]), duplicateByteSummary: Object.freeze({ materialCarriersAlsoPresentInWorkspace: 0, totalMaterialCarriers: cacheMaterials.length, interpretation: 'Exact Workspace-scoped recipient cache material is permitted only when not satisfied by a qualified Workspace archive.' }), routeGrounding: Object.freeze((inspection.carrierProjection?.routes || []).map((route) => Object.freeze({ routeId: route.id, workspaceId: route.workspaceId, handoffPackagePath: route.packagePath, required: route.requiredClosure?.requirements || [] }))), inspections: Object.freeze({ recipientV2: inspection.status, parentBoundaryGrounding: parentBoundaryGroundingEligible ? 'qualified-package-v1' : 'not-projected' }), findings: Object.freeze(dedupeFindings(findings)), boundary: 'Recipient-facing v2 carriage audit over qualified visible Tiinex artifacts and exact payload bytes. Complete Workspace snapshots and independently qualified package-v1 detached Parent-boundary lineage are projected separately; detached lineage never implies whole-Workspace carriage or membership.' });
+  return deepFreeze({ schema: PORTABLE_HANDOFF_CONTEXT_AUDIT_SCHEMA_ID, status: inspection.status === 'valid' && !unexplained ? 'ready' : 'blocked', coverage: Object.freeze({ nonControlCarrierCount: files.length, classifiedCarrierCount: classified, unexplainedCarrierCount: unexplained, state: unexplained ? 'incomplete' : 'qualified' }), workspaceMaterializations: Object.freeze((inspection.workspaces || []).map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: String(item.coverage || 'unresolved'), reason: String(item.coverage || '') === 'complete' ? 'complete-workspace-archive-representation' : String(item.coverage || '') === 'bounded' ? 'bounded-workspace-archive-representation' : 'workspace-archive-representation', qualification: 'qualified', carrierMode: 'archive', workspaceTargetPackagePath: item.workspaceArtifactPath, archivePackagePath: item.workspaceArchivePath, sourceWorkspaceTargetInnerPath: item.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.sourceWorkspaceTargetSha256 }))), lineageMaterializations: Object.freeze(lineageMaterializations), materialCarriers: Object.freeze([]), generatedEntrypoints: Object.freeze([String(inspection.rootArtifact?.path || ''), RECIPIENT_V2_READ_PATH, ...(inspection.endpointRoles || []).map((item) => item.pointerPath), ...(inspection.participantRoles || []).map((item) => item.pointerPath), ...(inspection.routes || []).map((item) => item.pointerPath)].filter(Boolean)), namedPackageRequirements: Object.freeze([]), explicitDetachedMaterial: Object.freeze(cacheMaterials), unexplainedCarriers: Object.freeze([]), duplicateByteSummary: Object.freeze({ materialCarriersAlsoPresentInWorkspace: 0, totalMaterialCarriers: cacheMaterials.length, interpretation: 'Exact Workspace-scoped recipient cache material is permitted only when not satisfied by a qualified Workspace archive.' }), routeGrounding: Object.freeze((inspection.carrierProjection?.routes || []).map((route) => Object.freeze({ routeId: route.id, workspaceId: route.workspaceId, handoffPackagePath: route.packagePath, required: route.requiredClosure?.requirements || [] }))), inspections: Object.freeze({ recipientV2: inspection.status, parentBoundaryGrounding: parentBoundaryGroundingEligible ? 'qualified-package-v1' : 'not-projected' }), findings: Object.freeze(dedupeFindings(findings)), boundary: 'Recipient-facing v2 carriage audit over qualified visible Tiinex artifacts and exact payload bytes. Complete Workspace snapshots and independently qualified package-v1 detached Parent-boundary lineage are projected separately; detached lineage never implies whole-Workspace carriage or membership.' });
 }
 
 function indexWorkspaceEntries(workspaces = []) {