@tiinex/core 0.1.1

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

@@ -0,0 +1,316 @@
+import { resolveLineage } from '../../../lineage/lineage.resolve.js';
+import { normalizePortableInput } from '../input/portable.input.js';
+import { projectPortableOperatingOverview } from '../overview/operatingOverview.js';
+import { summarizePortableFindings } from '../findings.js';
+import { directedLineageCone, isRoutedHandoffBundle, materializeQualifiedWorkspaceSnapshot, normalizeSelectors, projectBlockers, projectRelevantTopology, projectRequiredContext, relevantLineageIssues, resolveRequiredContextRecords, resolveSelectedRouteRecords } from './grounding.readiness.support.js';
+import { groundPortableColdConsumer } from '../handoff/coldStartQualification.grounding.js';
+import { createColdStartMaterialContext, projectGroundedContinuation } from '../handoff/coldStartQualification.materials.js';
+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';
+
+export const PORTABLE_GROUNDING_READINESS_SCHEMA_ID = 'tiinex.portable.grounding-readiness.v1';
+
+const MAX_ITEMS = 12;
+
+export function projectPortableGroundingReadiness(input = {}, options = {}) {
+  const bundle = input.bundle || input.package || input;
+  const handoffMode = isRoutedHandoffBundle(bundle);
+  if (!handoffMode) {
+    const material = normalizePortableInput(input.materials || input);
+    return composeGroundingReadiness({
+      mode: 'loaded-material',
+      authority: null,
+      continuation: null,
+      contextAudit: null,
+      material,
+      requiredContext: [],
+      findings: [...(material.findings || [])]
+    });
+  }
+
+  const route = String(input.route || input.routeId || input.routePath || '').trim();
+  const materialContext = createColdStartMaterialContext();
+  const grounding = groundPortableColdConsumer({
+    ...input,
+    bundle,
+    package: bundle,
+    ingressKind: 'routed-handoff-package',
+    route,
+    toolingAvailable: true
+  }, { ...options, coldStartMaterialContext: materialContext });
+  const continuation = projectGroundedContinuation({
+    bundle,
+    route,
+    grounding,
+    qualification: { status: 'not-assessed-by-ground' },
+    packageSourcePath: String(input.packageSourcePath || '')
+  }, materialContext);
+  const contextAudit = auditHandoffPackageContextCarriage({ bundle });
+  const snapshot = materializeQualifiedWorkspaceSnapshot(bundle, contextAudit, {
+    includeLegacyTopics: Boolean(input.includeLegacyTopics || options.includeLegacyTopics)
+  });
+  const recoveryMaterial = acceptedRecoveryMaterial(input.recoveryAcceptance || input.recovery || input.recoveredMaterial || {});
+  const material = normalizePortableInput({
+    files: [...snapshot.files, ...recoveryMaterial.files],
+    findings: [...snapshot.findings, ...recoveryMaterial.findings]
+  });
+  return composeGroundingReadiness({
+    mode: 'routed-handoff-package',
+    authority: grounding,
+    continuation,
+    contextAudit,
+    material,
+    requiredContext: continuation.requiredContext || [],
+    requiredContextSelectors: normalizeSelectors(input.includeRequiredContext || options.includeRequiredContext),
+    includeCurrentWork: Boolean(input.includeCurrentWork || options.includeCurrentWork),
+    findings: [
+      ...(grounding.findings || []),
+      ...(contextAudit.findings || []),
+      ...(snapshot.findings || []),
+      ...(material.findings || [])
+    ]
+  });
+}
+
+export function composeGroundingReadiness({ mode = 'loaded-material', authority = null, continuation = null, contextAudit = null, material = {}, requiredContext = [], requiredContextSelectors = [], includeCurrentWork = false, findings = [] } = {}) {
+  const records = Array.isArray(material.records) ? material.records : [];
+  const lineage = resolveLineage(records, { depth: 'portable-grounding-readiness' });
+  const requiredRecordResolution = resolveRequiredContextRecords(requiredContext, records);
+  const requiredContextProjection = projectRequiredContext(requiredContext, requiredContextSelectors);
+  const handoffMode = mode === 'routed-handoff-package';
+  const routeRecordIds = resolveSelectedRouteRecords(authority, records);
+  const relevantIds = handoffMode
+    ? directedLineageCone(lineage, routeRecordIds)
+    : new Set((lineage.nodes || []).map((node) => node.id));
+  const relevantRecords = records.filter((record) => relevantIds.has(record.id));
+  const overview = projectPortableOperatingOverview({ records: relevantRecords });
+  const topology = projectRelevantTopology(lineage, relevantIds, overview.frontierCandidates || [], routeRecordIds);
+  const lineageIssues = relevantLineageIssues(lineage, relevantIds);
+  const routeBlockingLineageIssues = relevantLineageIssues(lineage, routeRecordIds);
+  const continuity = projectColdStartContinuity({ mode, lineage, routeRecordIds, authority, material });
+  const combinedFindings = dedupeFindings([
+    ...findings,
+    ...filterFindingsForIds(lineage.findings || [], relevantIds),
+    ...(overview.findings || [])
+  ]);
+
+  const missingEvidence = [];
+  const reasons = [];
+  const known = [];
+  const inferred = [];
+  const unresolved = [];
+  const humanOnly = [];
+  let holderBindingActReady = !handoffMode;
+
+  if (handoffMode) {
+    const route = authority?.selectedRoute || null;
+    const roleState = String(authority?.role?.state || 'unresolved');
+    const holderState = String(authority?.holderBinding?.state || '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'));
+    else if (roleState === 'blocked') missing(missingEvidence, unresolved, 'recipient-role-blocked', 'The Handoff recipient Role boundary is blocked or contradictory.');
+    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;
+      missing(missingEvidence, unresolved, 'session-holder-role-binding-blocked', 'The explicit consuming-session holder Role contradicts the selected Handoff recipient Role.');
+    } else {
+      holderBindingActReady = false;
+      unresolved.push(evidence('session-holder-role-binding', 'unresolved', `recipient Role ${authority?.role?.endpoint?.label || authority?.handoff?.to || 'recipient'} is qualified separately from the consuming session`));
+      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.'));
+    }
+
+    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)`));
+    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 {
+    unresolved.push(evidence('bounded-handoff-authority', 'not-supplied', 'loaded material only'));
+    reasons.push(reason('discussion-only-without-handoff', 'Loaded material can support bounded discussion, but no Handoff authority/Required Context closure was supplied for act-ready grounding.'));
+  }
+
+  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' : 'all loaded records'));
+  inferred.push(evidence('lineage-leaf-role', 'bounded-inference', 'derived only from declared Parent edges in the shared resolver'));
+
+  if (handoffMode) {
+    if (routeBlockingLineageIssues.length) {
+      missing(missingEvidence, unresolved, 'selected-route-lineage-unresolved', `${routeBlockingLineageIssues.length} Parent-lineage ambiguity/missing/integrity issue(s) affect the selected Handoff route itself.`);
+    } 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.');
+    }
+    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) {
+    missing(missingEvidence, unresolved, 'loaded-lineage-unresolved', `${lineageIssues.length} loaded Parent-lineage ambiguity/missing/integrity issue(s) remain.`);
+  } else if (topology.leaves.length) {
+    known.push(evidence('loaded-parent-lineage-leaves', 'resolved', `${topology.leaves.length} loaded leaf/leaves`));
+  } else {
+    missing(missingEvidence, unresolved, 'loaded-lineage-leaf-missing', 'No resolved Parent-lineage leaf is available in the loaded material.');
+  }
+
+  if (handoffMode) {
+    if (continuity.state === 'qualified') known.push(evidence('cold-start-root-continuity', 'qualified', `${continuity.proof.qualifiedRoots.length} qualified semantic root(s); ${continuity.proof.ancestorRecordsChecked} ancestor record(s) checked without projecting ancestor bodies.`));
+    else missing(missingEvidence, unresolved, 'cold-start-root-continuity-unproven', `Cold-start continuity to a qualified semantic root is unproven; ${continuity.blockingIssues.length} blocking Parent/root issue(s) remain.`);
+  }
+
+  if (topology.currentTasks.length) known.push(evidence('declared-current-work', 'qualified-candidates', `${topology.currentTasks.length} Task candidate(s) on the selected route lineage`));
+  else unresolved.push(evidence('declared-current-work', 'unresolved', 'no exact-qualified nonterminal Task candidate on the selected route lineage'));
+
+  if (topology.currentFrontier.length) known.push(evidence('declared-current-frontier', 'resolved', `${topology.currentFrontier.length} nearest current Task anchor(s) to the selected route leaf`));
+  else reasons.push(reason('current-frontier-not-resolved', 'Authority grounding is not act-ready until declared current-work evidence is resolved on the selected Handoff route lineage.'));
+
+  const frontierTaskIds = new Set((topology.currentFrontier || []).map((item) => String(item.id || '')));
+  const blockers = projectBlockers(overview.blockerSignals || [], frontierTaskIds);
+  const currentWorkProjection = projectCurrentWork(topology, records, includeCurrentWork);
+  const capsule = projectGroundingCapsule({ authority, continuation, contextAudit, requiredContext, records, topology, blockers });
+  if (continuity.losses?.items?.length) unresolved.push(evidence('non-critical-material-loss', 'degraded-nonblocking', `${continuity.losses.items.length} unavailable non-lineage asset/reference item(s) remain visible without blocking unrelated work.`));
+  const externalHumanGates = Array.isArray(authority?.humanOnlyGates) ? authority.humanOnlyGates : [];
+  for (const gate of externalHumanGates) humanOnly.push(evidence('human-only-gate', 'declared', String(gate?.label || gate || 'human gate')));
+
+  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.'));
+
+  return Object.freeze({
+    schema: PORTABLE_GROUNDING_READINESS_SCHEMA_ID,
+    status: state === 'insufficient-grounding' ? 'blocked' : 'ready',
+    readiness: Object.freeze({
+      state,
+      reasons: Object.freeze(reasons.slice(0, MAX_ITEMS)),
+      missingEvidence: Object.freeze(missingEvidence.slice(0, MAX_ITEMS)),
+      nextAction: nextActionFor(state, topology, continuity, authority)
+    }),
+    authority: projectGroundingAuthority(authority, mode),
+    coverage: Object.freeze({
+      mode,
+      loadedRecords: records.length,
+      relevantRecords: relevantIds.size,
+      requiredContext: Object.freeze({
+        declared: requiredContext.length,
+        matchedInWorkspaceSnapshots: requiredRecordResolution.matched,
+        missingFromWorkspaceSnapshots: requiredRecordResolution.missing.length,
+        items: requiredContextProjection.items,
+        itemsOmitted: requiredContextProjection.itemsOmitted,
+        bodiesProjected: requiredContextProjection.bodiesProjected,
+        bodiesAvailable: requiredContextProjection.bodiesAvailable,
+        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 })
+    }),
+    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'),
+      basis: 'declared-parent-only',
+      filenameDimensionsUsed: false,
+      carrierDimensionsUsed: false,
+      roots: Object.freeze(topology.roots.slice(0, MAX_ITEMS)),
+      rootsOmitted: Math.max(0, topology.roots.length - MAX_ITEMS),
+      leaves: Object.freeze(topology.leaves.slice(0, MAX_ITEMS)),
+      leavesOmitted: Math.max(0, topology.leaves.length - MAX_ITEMS),
+      selectedRouteLeaves: Object.freeze(topology.routeLeaves.slice(0, MAX_ITEMS)),
+      selectedRouteLeavesOmitted: Math.max(0, topology.routeLeaves.length - MAX_ITEMS),
+      blockingIssues: Object.freeze(routeBlockingLineageIssues.slice(0, MAX_ITEMS)),
+      blockingIssuesOmitted: Math.max(0, routeBlockingLineageIssues.length - MAX_ITEMS),
+      diagnosticIssues: Object.freeze(lineageIssues.slice(0, MAX_ITEMS)),
+      diagnosticIssuesOmitted: Math.max(0, lineageIssues.length - MAX_ITEMS),
+      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,
+    capsule,
+    currentWork: Object.freeze({
+      state: topology.currentFrontier.length ? 'current-frontier-resolved' : topology.currentTasks.length ? 'current-candidates-without-frontier' : 'unresolved',
+      frontier: currentWorkProjection.frontier,
+      frontierOmitted: Math.max(0, topology.currentFrontier.length - MAX_ITEMS),
+      candidates: Object.freeze(topology.currentTasks.slice(0, MAX_ITEMS)),
+      candidatesOmitted: Math.max(0, topology.currentTasks.length - MAX_ITEMS),
+      blockers: Object.freeze(blockers.slice(0, MAX_ITEMS)),
+      blockersOmitted: Math.max(0, blockers.length - MAX_ITEMS),
+      bodiesProjected: currentWorkProjection.bodiesProjected,
+      bodiesAvailable: currentWorkProjection.bodiesAvailable,
+      bodyProjectionRequested: Boolean(includeCurrentWork),
+      lifecycleIsLineagePosition: false,
+      lineageLeafMeansWorkflowFrontier: false
+    }),
+    evidence: Object.freeze({
+      known: Object.freeze(known.slice(0, MAX_ITEMS)),
+      inferred: Object.freeze(inferred.slice(0, MAX_ITEMS)),
+      unresolved: Object.freeze(unresolved.slice(0, MAX_ITEMS)),
+      humanOnly: Object.freeze(humanOnly.slice(0, MAX_ITEMS))
+    }),
+    findingSummary: summarizePortableFindings(combinedFindings),
+    actionableFindings: Object.freeze(combinedFindings.filter((item) => item.severity === 'error' || item.severity === 'warning').slice(0, MAX_ITEMS)),
+    actionableFindingsOmitted: Math.max(0, combinedFindings.filter((item) => item.severity === 'error' || item.severity === 'warning').length - MAX_ITEMS),
+    deeper: Object.freeze({
+      requiredContextBodies: handoffMode ? 'Re-run the same ground command with --include-required-context <requirement-id,name|all> only when exact qualified body text is needed.' : 'not-applicable',
+      currentWorkBody: handoffMode ? 'Re-run the same ground command with --include-current-work when the exact current Task body is needed; --continue <workspace-dir> includes it automatically.' : 'not-applicable',
+      lineage: 'Use resolve-lineage/search-lineage only when the bounded selected-route leaf/current-work pointers above are insufficient.',
+      coldStartQualification: handoffMode ? 'Use qualify-cold-start only when cold-start process qualification/evidence is itself required; ground does not claim pre-takeover host observations.' : 'not-applicable'
+    }),
+    boundary: 'Decision-oriented grounding projection only. Handoff/Role/Task/Parent artifacts retain authority; this projection composes their loaded evidence and fails visible rather than inventing missing currentness or lineage.'
+  });
+}
+
+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) => {
+    const record = recordById.get(String(item.id || ''));
+    const available = Boolean(record && typeof record.markdown === 'string' && record.markdown.length > 0);
+    return Object.freeze({
+      ...item,
+      contentProjected: Boolean(includeCurrentWork && available),
+      ...(includeCurrentWork && available ? { content: record.markdown } : {})
+    });
+  });
+  const bodiesAvailable = (topology.currentFrontier || []).filter((item) => {
+    const record = recordById.get(String(item.id || ''));
+    return Boolean(record && typeof record.markdown === 'string' && record.markdown.length > 0);
+  }).length;
+  return Object.freeze({
+    frontier: Object.freeze(frontier),
+    bodiesProjected: frontier.filter((item) => item.contentProjected).length,
+    bodiesAvailable
+  });
+}
+
+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-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') 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',
+    target: continuity.recovery?.target || '',
+    basis: 'cold-start continuity to a qualified semantic root is required before substantive work',
+    recovery: continuity.recovery || null
+  });
+  return Object.freeze({ kind: 'resolve-missing-grounding-evidence', target: '', basis: 'one or more blocking authority/context/lineage conditions remain' });
+}
+
+function nodeSummary(node = {}) { return Object.freeze({ id: node.id || '', path: node.path || '', title: node.title || '', schemaId: node.schemaId || '', trace: node.trace || '' }); }
+function evidence(code, state, detail) { return Object.freeze({ code, state, detail: compactText(detail, 280) }); }
+function reason(code, message) { return Object.freeze({ code, message }); }
+function missing(list, unresolved, code, message) { const item = reason(code, message); list.push(item); unresolved.push(evidence(code, 'unresolved', message)); }
+function finding(severity, code, message, params = {}) { return Object.freeze({ severity, code, message, source: PORTABLE_GROUNDING_READINESS_SCHEMA_ID, params }); }
+function compactText(value = '', limit = 240) { const text = String(value || '').replace(/\s+/g, ' ').trim(); return text.length > limit ? `${text.slice(0, Math.max(0, limit - 1))}…` : text; }
+function filterFindingsForIds(items = [], ids = new Set()) { return items.filter((item) => !item?.nodeId || ids.has(item.nodeId)); }
+function dedupeFindings(items = []) { return dedupeBy(items, (item) => `${item.severity || ''}:${item.code || ''}:${item.nodeId || ''}:${item.target || ''}:${item.message || ''}`); }
+function dedupeBy(items = [], keyFn) { const map = new Map(); for (const item of items) { const key = keyFn(item); if (!map.has(key)) map.set(key, item); } return Object.freeze([...map.values()]); }

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

@@ -0,0 +1,245 @@
+import { packageFileBytes } from '../../../export/package.bytes.js';
+import { inspectStoredWorkspaceArchive } from '../handoff/workspaceByteProvider.js';
+import { RECIPIENT_V2_READ_PATH } from '../handoff/recipientV2.topology.js';
+import { decodeUtf8, findFile } from '../handoff/coldStartQualification.shared.js';
+
+const CURRENT_TASK_SCHEMA = 'tiinex.task.v1';
+const MAX_ITEMS = 12;
+const BLOCKING_LINEAGE_CODES = new Set([
+  'lineage.target.ambiguous',
+  'lineage.parent.integrityMismatch',
+  'lineage.parent.selfReference',
+  'lineage.parent.exactTargetNotLoaded',
+  'lineage.target.outOfBoundary',
+  'lineage.parent.boundaryBlocked'
+]);
+
+export function isRoutedHandoffBundle(bundle = {}) {
+  return Array.isArray(bundle?.files) && bundle.files.some((file) => String(file.path || '') === RECIPIENT_V2_READ_PATH);
+}
+
+export function materializeQualifiedWorkspaceSnapshot(bundle, contextAudit, options = {}) {
+  const files = [];
+  const findings = [];
+  for (const workspace of contextAudit?.workspaceMaterializations || []) {
+    const workspaceId = String(workspace.workspaceId || '').trim();
+    const archivePath = String(workspace.archivePackagePath || '').trim();
+    const archiveFile = findFile(bundle, archivePath);
+    if (!workspaceId || !archivePath || !archiveFile) {
+      findings.push(finding('error', 'portable.grounding.workspace-snapshot.unavailable', 'A qualified Workspace snapshot archive could not be resolved from the carrier.', { workspaceId, archivePath }));
+      continue;
+    }
+    const archive = inspectStoredWorkspaceArchive(packageFileBytes(archiveFile), { ownedBytes: true });
+    if (archive.state !== 'qualified') {
+      findings.push(finding('error', 'portable.grounding.workspace-snapshot.invalid', 'A carried Workspace snapshot archive is not qualified readable material.', { workspaceId, archivePath }));
+      continue;
+    }
+    for (const entry of archive.entries || []) {
+      const innerPath = String(entry.path || '').replace(/\\/g, '/');
+      if (!isGroundingArtifactPath(innerPath)) continue;
+      if (!options.includeLegacyTopics && /(?:^|\/)\.topics\/development(?:\/|$)/.test(innerPath)) continue;
+      const content = decodeUtf8(entry.data || new Uint8Array());
+      if (!content) continue;
+      files.push(Object.freeze({
+        path: `${workspaceId}/${innerPath}`,
+        content,
+        size: Number(entry.size || (entry.data?.byteLength || 0)),
+        sourceMode: 'portable-handoff-workspace-snapshot'
+      }));
+    }
+  }
+  return Object.freeze({ files: Object.freeze(files), findings: Object.freeze(findings) });
+}
+
+export function projectRequiredContext(requiredContext = [], selectors = []) {
+  const requested = normalizeSelectors(selectors);
+  const selected = (entry) => requested.includes('all') || requested.some((selector) => requiredContextMatches(entry, selector));
+  const availableBodies = requiredContext.filter((entry) => typeof entry?.content === 'string' && entry.content.length > 0).length;
+  const items = requiredContext.slice(0, MAX_ITEMS).map((entry) => {
+    const contentProjected = selected(entry) && typeof entry?.content === 'string';
+    return Object.freeze({
+      requirementId: entry.requirementId || '',
+      name: entry.name || '',
+      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 || '',
+      contentProjected,
+      ...(contentProjected ? { content: entry.content } : {})
+    });
+  });
+  const unmatched = requested.filter((selector) => selector !== 'all' && !requiredContext.some((entry) => requiredContextMatches(entry, selector)));
+  return Object.freeze({
+    items: Object.freeze(items),
+    itemsOmitted: Math.max(0, requiredContext.length - items.length),
+    bodiesProjected: items.filter((item) => item.contentProjected).length,
+    bodiesAvailable: availableBodies,
+    requestedSelectors: Object.freeze(requested),
+    unmatchedSelectors: Object.freeze(unmatched)
+  });
+}
+
+export function normalizeSelectors(value) {
+  if (!value) return Object.freeze([]);
+  if (Array.isArray(value)) return Object.freeze(value.map((item) => String(item || '').trim().toLowerCase()).filter(Boolean));
+  if (value === true) return Object.freeze(['all']);
+  return Object.freeze(String(value).split(',').map((item) => item.trim().toLowerCase()).filter(Boolean));
+}
+
+export function resolveRequiredContextRecords(requiredContext = [], records = []) {
+  const byPath = new Map(records.map((record) => [String(record.path || ''), record]));
+  const ids = new Set();
+  const missing = [];
+  let matched = 0;
+  for (const entry of requiredContext || []) {
+    if (entry.state !== 'qualified') continue;
+    const workspaceId = String(entry.workspaceId || '').trim();
+    const innerPath = String(entry.innerPath || entry.workspaceRelativePath || '').replace(/^\/+/, '').replace(/\\/g, '/');
+    if (!workspaceId || !innerPath) continue;
+    const expectedPath = `${workspaceId}/${innerPath}`;
+    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.`);
+  }
+  return Object.freeze({ ids, matched, missing: Object.freeze(missing) });
+}
+
+function isExactHydratedWorkspaceContext(entry = {}) {
+  if (String(entry.providerMode || '') !== 'archive') 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);
+  const expectedSha = String(entry.sha256 || '').trim().toLowerCase();
+  const actualSha = String(entry.actualSha256 || '').trim().toLowerCase();
+  return expectedBytes > 0 && expectedBytes === actualBytes && /^[0-9a-f]{64}$/.test(expectedSha) && expectedSha === actualSha;
+}
+
+export function resolveSelectedRouteRecords(authority = {}, records = []) {
+  const route = authority?.selectedRoute || {};
+  const workspaceId = String(route.workspaceId || '').trim();
+  const innerPath = String(route.workspaceRelativeHandoffPath || '').replace(/^\/+/, '').replace(/\\/g, '/');
+  if (!workspaceId || !innerPath) return new Set();
+  const expectedPath = `${workspaceId}/${innerPath}`;
+  return new Set(records.filter((record) => record.path === expectedPath).map((record) => record.id));
+}
+
+export function directedLineageCone(lineage = {}, startIds = new Set()) {
+  const all = new Set((lineage.nodes || []).map((node) => node.id));
+  if (!startIds.size) return new Set();
+  const parents = new Map();
+  const children = new Map();
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !edge.from || !edge.to || edge.status === 'missing' || edge.status === 'mismatch') continue;
+    add(parents, edge.to, edge.from);
+    add(children, edge.from, edge.to);
+  }
+  const starts = [...startIds].filter((id) => all.has(id));
+  const out = new Set(starts);
+  const walk = (adjacent) => {
+    const queue = [...starts];
+    const seen = new Set(starts);
+    while (queue.length) {
+      const id = queue.shift();
+      for (const next of adjacent.get(id) || []) {
+        if (seen.has(next)) continue;
+        seen.add(next);
+        out.add(next);
+        queue.push(next);
+      }
+    }
+  };
+  walk(parents);
+  walk(children);
+  return out;
+}
+
+export function projectRelevantTopology(lineage = {}, relevantIds = new Set(), frontierCandidates = [], routeRecordIds = new Set()) {
+  const nodeById = new Map((lineage.nodes || []).map((node) => [node.id, node]));
+  const parentIncoming = new Map();
+  const parentOutgoing = new Map();
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !edge.to) continue;
+    if (edge.from) add(parentOutgoing, edge.from, edge);
+    add(parentIncoming, edge.to, edge);
+  }
+  const roots = [];
+  const leaves = [];
+  for (const id of relevantIds) {
+    const node = nodeById.get(id);
+    if (!node) continue;
+    const incomingResolved = (parentIncoming.get(id) || []).some((edge) => edge.from && edge.status !== 'missing' && edge.status !== 'mismatch');
+    const outgoingResolved = (parentOutgoing.get(id) || []).some((edge) => edge.to && edge.status !== 'missing' && edge.status !== 'mismatch');
+    const summary = nodeSummary(node);
+    if (!incomingResolved) roots.push(summary);
+    if (!outgoingResolved) leaves.push(summary);
+  }
+  const currentTasks = (frontierCandidates || [])
+    .filter((item) => relevantIds.has(item.id) && item.schemaId === CURRENT_TASK_SCHEMA)
+    .map((item) => Object.freeze({ id: item.id, path: item.path, title: item.title, declaredStatus: item.declaredStatus, objective: compactText(item.objective, 240) }));
+  const currentTaskIds = new Set(currentTasks.map((item) => item.id));
+  const routeLeaves = leaves.filter((item) => routeRecordIds.has(item.id));
+  const distance = ancestorDistanceFromRoute(lineage, routeRecordIds, relevantIds);
+  const rankedCurrent = currentTasks.filter((item) => distance.has(item.id)).sort((a, b) => distance.get(a.id) - distance.get(b.id));
+  const nearestDistance = rankedCurrent.length ? distance.get(rankedCurrent[0].id) : Number.POSITIVE_INFINITY;
+  const currentFrontier = rankedCurrent.filter((item) => distance.get(item.id) === nearestDistance);
+  const relevantPaths = Object.freeze([...relevantIds].map((id) => String(nodeById.get(id)?.path || '')).filter(Boolean));
+  return Object.freeze({ roots, leaves, routeLeaves, currentTasks, currentTaskIds, currentFrontier, relevantPaths });
+}
+
+export function relevantLineageIssues(lineage = {}, relevantIds = new Set()) {
+  const issues = [];
+  for (const findingEntry of lineage.findings || []) {
+    if (!BLOCKING_LINEAGE_CODES.has(String(findingEntry.code || ''))) continue;
+    if (findingEntry.nodeId && !relevantIds.has(findingEntry.nodeId)) continue;
+    issues.push(Object.freeze({ code: findingEntry.code, severity: findingEntry.severity, nodeId: findingEntry.nodeId || '', target: findingEntry.target || '', message: findingEntry.message || '' }));
+  }
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !relevantIds.has(edge.to)) continue;
+    if (!['probable', 'missing', 'mismatch'].includes(String(edge.status || ''))) continue;
+    issues.push(Object.freeze({ code: `lineage.parent.${edge.status}`, severity: edge.status === 'mismatch' ? 'error' : 'warning', nodeId: edge.to, target: edge.target || '', message: `Relevant Parent edge remains ${edge.status}.` }));
+  }
+  return dedupeBy(issues, (item) => `${item.code}:${item.nodeId}:${item.target}`);
+}
+
+export function projectBlockers(blockers = [], currentTaskIds = new Set()) {
+  return blockers.filter((item) => currentTaskIds.has(item.id)).map((item) => Object.freeze({ kind: item.kind, id: item.id, path: item.path, title: item.title, text: compactText(item.text, 240), basis: item.basis }));
+}
+
+function ancestorDistanceFromRoute(lineage = {}, routeRecordIds = new Set(), relevantIds = new Set()) {
+  const parents = new Map();
+  for (const edge of lineage.edges || []) {
+    if (edge.kind !== 'parent' || !edge.from || !edge.to || edge.status === 'missing' || edge.status === 'mismatch') continue;
+    if (!relevantIds.has(edge.from) || !relevantIds.has(edge.to)) continue;
+    add(parents, edge.to, edge.from);
+  }
+  const distance = new Map();
+  const queue = [];
+  for (const id of routeRecordIds) { distance.set(id, 0); queue.push(id); }
+  while (queue.length) {
+    const id = queue.shift();
+    const nextDistance = distance.get(id) + 1;
+    for (const parentId of parents.get(id) || []) {
+      if (distance.has(parentId) && distance.get(parentId) <= nextDistance) continue;
+      distance.set(parentId, nextDistance);
+      queue.push(parentId);
+    }
+  }
+  return distance;
+}
+
+function isGroundingArtifactPath(value = '') {
+  const path = String(value || '').toLowerCase();
+  return path.endsWith('.trace.md') || path.endsWith('.workspace.md');
+}
+function requiredContextMatches(entry = {}, selector = '') {
+  const wanted = String(selector || '').trim().toLowerCase();
+  return [entry.requirementId, entry.name, entry.referenceTarget, entry.innerPath].some((value) => String(value || '').toLowerCase() === wanted);
+}
+function nodeSummary(node = {}) { return Object.freeze({ id: node.id || '', path: node.path || '', title: node.title || '', schemaId: node.schemaId || '', trace: node.trace || '' }); }
+function finding(severity, code, message, params = {}) { return Object.freeze({ severity, code, message, source: 'tiinex.portable.grounding-readiness.v1', params }); }
+function add(map, key, value) { if (!map.has(key)) map.set(key, []); map.get(key).push(value); }
+function compactText(value = '', limit = 240) { const text = String(value || '').replace(/\s+/g, ' ').trim(); return text.length > limit ? `${text.slice(0, Math.max(0, limit - 1))}…` : text; }
+function dedupeBy(items = [], keyFn) { const map = new Map(); for (const item of items) { const key = keyFn(item); if (!map.has(key)) map.set(key, item); } return Object.freeze([...map.values()]); }

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

@@ -0,0 +1,71 @@
+import { parseWorkspaceEntrypoints } from '../handoff/workspaceSourceIdentity.js';
+const MAX_WORKSPACES = 8;
+const MAX_SOURCES = 8;
+
+export function projectGroundingSourceEvidence({ records = [], contextAudit = null, continuation = null, sourceProfiles = [] } = {}) {
+  const byPath = new Map((records || []).map((record) => [String(record.path || ''), record]));
+  const profiles = profileIndex(sourceProfiles);
+  const workspaces = (contextAudit?.workspaceMaterializations || []).slice(0, MAX_WORKSPACES).map((workspace) => {
+    const workspaceId = String(workspace.workspaceId || '');
+    const innerPath = normalizePath(workspace.sourceWorkspaceTargetInnerPath || '');
+    const exactPath = workspaceId && innerPath ? `${workspaceId}/${innerPath}` : '';
+    const record = exactPath ? byPath.get(exactPath) : null;
+    const declared = record ? parseWorkspaceEntrypoints(record.markdown || '') : [];
+    const explicitProfile = profiles.get(workspaceId) || [];
+    const sources = declared.length ? declared : explicitProfile;
+    const unique = sources.length === 1 ? sources[0] : null;
+    const qualifiedArtifact = Boolean(
+      String(workspace.qualification || '') === 'qualified'
+      && innerPath
+      && record
+      && record.hasContinuityContext
+      && record.hasIntegrity
+    );
+    if (!qualifiedArtifact && !explicitProfile.length) return Object.freeze({ workspace: workspaceId, state: 'unresolved' });
+    return Object.freeze({
+      workspace: workspaceId,
+      state: qualifiedArtifact ? 'qualified' : 'explicit-profile',
+      carrier: String(workspace.reason || 'qualified-workspace-snapshot'),
+      sourceArtifactPath: exactPath,
+      sourceArtifactSha256: String(workspace.sourceWorkspaceTargetSha256 || ''),
+      repository: String(unique?.repository || ''),
+      ref: String(unique?.ref || ''),
+      rootPath: String(unique?.rootPath || ''),
+      remoteState: String(unique?.remoteState || 'not-checked'),
+      sources: Object.freeze(sources.slice(0, MAX_SOURCES))
+    });
+  });
+  return Object.freeze({
+    carrier: Object.freeze({
+      state: String(contextAudit?.coverage?.state || contextAudit?.status || 'unresolved'),
+      workspaceCount: Number(contextAudit?.workspaceMaterializations?.length || 0),
+      packageSourcePath: String(continuation?.packageSourcePath || '')
+    }),
+    workspaces: Object.freeze(workspaces),
+    boundary: 'Exact selected Workspace source artifact/profile only.'
+  });
+}
+
+function profileIndex(value = []) {
+  const map = new Map();
+  if (!value) return map;
+  if (!Array.isArray(value) && typeof value === 'object') {
+    for (const [workspaceId, profile] of Object.entries(value)) map.set(String(workspaceId), Object.freeze(normalizeProfileList(profile)));
+    return map;
+  }
+  for (const item of value || []) {
+    const workspaceId = String(item?.workspaceId || item?.workspace || '');
+    if (!workspaceId) continue;
+    const list = map.get(workspaceId) || [];
+    list.push(normalizeProfile(item));
+    map.set(workspaceId, Object.freeze(list));
+  }
+  return map;
+}
+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, '\\$&'); }