@tiinex/core 0.1.1

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

@@ -0,0 +1,81 @@
+import {
+  COLD_START_INGRESS_KINDS,
+  normalizeIngressKind
+} from './coldStartQualification.contract.js';
+import { groundPortableColdConsumer } from './coldStartQualification.grounding.js';
+import { createColdStartMaterialContext, projectGroundedContinuation } from './coldStartQualification.materials.js';
+import { qualifyPortableColdStartTrace } from './coldStartQualification.observation.js';
+import { deepFreeze, normalizeToken } from './coldStartQualification.shared.js';
+
+export function qualifyPortableColdStartRun(input = {}, options = {}) {
+  const ingressKind = normalizeIngressKind(input.ingressKind || input.kind || COLD_START_INGRESS_KINDS.HANDOFF);
+  const bundle = input.bundle || input.package || input;
+  const route = String(input.route || input.routeId || input.routePath || '').trim();
+  const coldStartMaterialContext = createColdStartMaterialContext();
+  const hostEvidence = normalizeOneShotHostEvidence(input.hostEvidence || input.preTakeover || input.preTiinex || input.hostPreTakeover || 'unverified', input.hostEvidenceSource || input.evidenceSource || '');
+  const grounding = groundPortableColdConsumer({
+    ...input,
+    bundle,
+    package: bundle,
+    ingressKind,
+    route,
+    toolingAvailable: input.toolingAvailable === false ? false : true
+  }, { ...options, coldStartMaterialContext });
+  const events = [];
+  if (hostEvidence.mode === 'minimal-bootstrap-only') events.push({ mechanism: 'native-host', action: 'read declared Start/bootstrap nodes and materialize verified portable Tooling bootstrap', semanticClass: 'minimal-bootstrap', status: 'completed', read: true, arbitrary: false, candidateArtifacts: 0 });
+  else if (hostEvidence.mode === 'native-archaeology') events.push({ mechanism: 'native-host', action: 'native package/archive/filesystem inspection before Tiinex takeover', semanticClass: 'semantic-archaeology', status: 'completed', read: true, arbitrary: true, candidateArtifacts: Math.max(1, Number(input.candidateArtifacts || 1) || 1) });
+  else if (hostEvidence.mode === 'none') { /* Tooling was already callable; no native bootstrap action is declared. */ }
+  events.push({ mechanism: 'tiinex', operation: 'orient-handoff-package', status: String(grounding.orientation?.status || 'blocked') });
+  events.push({ mechanism: 'tiinex', operation: 'ground-cold-consumer', status: String(grounding.status || 'blocked') });
+  const traceInput = {
+    ingressKind,
+    toolingAvailable: input.toolingAvailable === false ? false : true,
+    events,
+    grounding,
+    outcome: grounding.status === 'blocked' ? { state: 'failed' } : hostEvidence.mode === 'unverified' ? { state: 'unknown' } : { state: 'recovered' },
+    hostEvidence: { state: hostEvidence.mode === 'unverified' ? 'unverified' : 'provided', source: hostEvidence.source, mode: hostEvidence.mode },
+    requireHostEvidence: true
+  };
+  const qualification = qualifyPortableColdStartTrace(traceInput, options);
+  const continuation = projectGroundedContinuation({ bundle, route, grounding, qualification, packageSourcePath: input.packageSourcePath || '' }, coldStartMaterialContext);
+  return deepFreeze({
+    ...qualification,
+    grounding,
+    continuation,
+    oneShot: Object.freeze({
+      state: grounding.status === 'blocked' ? 'blocked' : 'completed',
+      routeSelector: route,
+      hostEvidence: Object.freeze(hostEvidence),
+      toolingEvidence: 'generated-by-qualify-cold-start-run',
+      evidenceAttribution: Object.freeze({
+        tooling: Object.freeze({ source: 'portable-tooling', independentlyObserved: true, covers: Object.freeze(['orientation', 'route-resolution', 'recipient-grounding']) }),
+        preTakeoverHost: Object.freeze({ source: hostEvidence.source, mode: hostEvidence.mode, independentlyObservedByTooling: false })
+      }),
+      boundary: 'Tooling can generate and qualify its own orientation/grounding receipts. Pre-takeover native-host behavior is not directly observable by portable Tooling unless supplied by a host observer; caller-declared host evidence remains explicitly attributed rather than promoted to independent proof.'
+    })
+  });
+}
+
+export function isOneShotColdStartQualificationInput(input = {}) {
+  const bundle = input?.bundle || input?.package || null;
+  if (!bundle || !Array.isArray(bundle.files)) return false;
+  const explicitEvents = input?.events || input?.observations || input?.trace;
+  return !(Array.isArray(explicitEvents) && explicitEvents.length);
+}
+
+export function normalizeOneShotHostEvidence(value, source = '') {
+  const raw = typeof value === 'object' && value ? value : { mode: value };
+  const token = normalizeToken(raw.mode || raw.state || raw.kind || value || 'unverified');
+  const mode = ['minimal-bootstrap-only', 'minimal-bootstrap', 'bootstrap-only'].includes(token)
+    ? 'minimal-bootstrap-only'
+    : ['none', 'tooling-preinstalled', 'already-available'].includes(token)
+      ? 'none'
+      : ['native-archaeology', 'archaeology', 'fallback'].includes(token)
+        ? 'native-archaeology'
+        : 'unverified';
+  return Object.freeze({
+    mode,
+    source: String(raw.source || source || (mode === 'unverified' ? 'unverified' : 'caller-declared')).trim(),
+    independentlyObservedByTooling: false
+  });
+}

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

@@ -0,0 +1,57 @@
+export const NON_EXECUTION_MODES = new Set(['review', 'explanation', 'design-discussion', 'orientation', 'collaborative-dialogue']);
+export const READY_OPERATION_STATES = new Set(['ready', 'qualified', 'valid', 'accepted', 'passed', 'completed', 'degraded']);
+export function normalizeAttribution(value) {
+  const normalized = normalizeToken(value);
+  if (['verified', 'declared', 'unverified', 'unknown'].includes(normalized)) return normalized;
+  return normalized ? 'unverified' : 'unknown';
+}
+export function normalizeInteractionMode(value) {
+  const normalized = normalizeToken(value).replace(/_/g, '-');
+  if (!normalized) return '';
+  const aliases = { design: 'design-discussion', discussion: 'collaborative-dialogue', explain: 'explanation', review: 'review', execute: 'execution' };
+  return aliases[normalized] || normalized;
+}
+export function sectionText(markdown = '', heading = '') {
+  const escaped = escapeRegExp(heading);
+  const match = new RegExp(`^##\\s+${escaped}\\s*$`, 'mi').exec(String(markdown || ''));
+  if (!match) return '';
+  const rest = String(markdown).slice(match.index + match[0].length);
+  const next = /^##\s+/m.exec(rest);
+  return (next ? rest.slice(0, next.index) : rest).trim();
+}
+export function sectionField(section = '', name = '') {
+  const escaped = escapeRegExp(name);
+  const match = String(section || '').match(new RegExp(`^\\s*-\\s+${escaped}:\\s*(.+?)\\s*$`, 'mi'));
+  return stripMarkdown(String(match?.[1] || '').trim());
+}
+export function sectionReferenceTarget(section = '', name = '') {
+  const escaped = escapeRegExp(name);
+  const match = String(section || '').match(new RegExp(`^\\s*-\\s+${escaped}:\\s*(.+?)\\s*$`, 'mi'));
+  const raw = String(match?.[1] || '').trim();
+  const link = raw.match(/^\[[^\]]+\]\(([^)\s]+)\)$/);
+  return String(link?.[1] || raw).trim();
+}
+export function stripMarkdown(value = '') {
+  const text = String(value || '').trim();
+  const link = text.match(/^\[([^\]]+)\]\([^)]+\)$/);
+  if (link) return link[1].trim();
+  return text.replace(/^`(.+)`$/, '$1').replace(/^\*\*(.+)\*\*$/, '$1').trim();
+}
+export function normalizeSemanticClass(value) {
+  const normalized = normalizeToken(value).replace(/_/g, '-');
+  if (['bootstrap', 'host-bootstrap', 'minimal-ingress', 'minimal-bootstrap'].includes(normalized)) return 'minimal-bootstrap';
+  if (['substantive', 'reasoning', 'work', 'substantive-work'].includes(normalized)) return 'substantive-work';
+  if (['fallback', 'degraded-fallback'].includes(normalized)) return 'fallback';
+  if (['native-read', 'artifact-read', 'filesystem-read', 'archive-read'].includes(normalized)) return 'native-read';
+  return normalized || 'native-action';
+}
+export function normalizeComparable(value) { return stripMarkdown(value).toLowerCase().replace(/\s+/g, ' ').trim(); }
+export function normalizeToken(value) { return String(value || '').trim().toLowerCase(); }
+export function normalizePath(value) { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, ''); }
+export function normalizeStringList(value) { const list = Array.isArray(value) ? value : value ? [value] : []; return [...new Set(list.map((item) => String(item || '').trim()).filter(Boolean))]; }
+export function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+export function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+export function finiteOrNull(value) { const number = Number(value); return Number.isFinite(number) ? number : null; }
+export function parseTime(value) { const ms = Date.parse(String(value || '')); return Number.isFinite(ms) ? ms : null; }
+export function escapeRegExp(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+export function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

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

@@ -0,0 +1,39 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { portableFinding } from '../findings.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+
+export function resolveColdStartRolePointerMaterial(bundle, facts, findings, pointerPath, roleKind = 'participant-role') {
+  const codeKind = roleKind === 'endpoint-role' ? 'endpoint-role' : 'participant-role';
+  const labelKind = roleKind === 'endpoint-role' ? 'Endpoint Role' : 'Participant Role';
+  const archivePath = String(facts.archivePath || '').trim();
+  const archiveFile = findFile(bundle, archivePath);
+  if (!archiveFile) {
+    findings.push(portableFinding('error', `portable.cold-start.${codeKind}.archive.missing`, `${labelKind} Pointer target archive is not carried.`, { pointerPath, archivePath }));
+    return null;
+  }
+  const archive = inspectStoredWorkspaceArchive(packageFileBytes(archiveFile), { ownedBytes: true });
+  if (archive.state !== 'qualified') {
+    findings.push(portableFinding('error', `portable.cold-start.${codeKind}.archive.invalid`, `${labelKind} Pointer target archive is not qualified.`, { pointerPath, archivePath }));
+    return null;
+  }
+  const targetPath = String(facts.targetCarrierKind || '') === 'workspace-cache-entry'
+    ? String(facts.targetArchiveEntry || '')
+    : String(facts.targetInnerPath || '');
+  const matches = (archive.entries || []).filter((entry) => normalizePath(entry.path || '') === normalizePath(targetPath));
+  if (matches.length !== 1) {
+    findings.push(portableFinding('error', matches.length > 1 ? `portable.cold-start.${codeKind}.target.ambiguous` : `portable.cold-start.${codeKind}.target.missing`, `${labelKind} Pointer does not resolve to exactly one target entry.`, { pointerPath, archivePath, targetPath, matches: matches.length }));
+    return null;
+  }
+  const data = packageFileBytes({ data: matches[0].data });
+  if ((facts.targetBytes && Number(facts.targetBytes) !== data.byteLength)
+    || (facts.targetSha256 && String(facts.targetSha256) !== sha256Hex(data))) {
+    findings.push(portableFinding('error', `portable.cold-start.${codeKind}.target.identity-mismatch`, `${labelKind} Pointer target bytes diverge from the declared exact identity.`, { pointerPath, archivePath, targetPath }));
+    return null;
+  }
+  const markdown = decodeUtf8(data);
+  return markdown ? Object.freeze({ path: `${archivePath}::${targetPath}`, markdown }) : null;
+}
+
+function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+function normalizePath(value) { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, ''); }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }

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

@@ -0,0 +1,247 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectHandoffClosureDescriptor } from './materialClosure.descriptor.js';
+import { inspectHandoffCarrierProjection } from './carrierProjection.js';
+import { inspectHandoffPointerEntrypoints, isHandoffPointerEntrypointPath } from './pointerEntrypoint.js';
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { RECIPIENT_V2_TRANSPORT_MANIFEST_PATH } from './recipientV2.transportManifest.js';
+
+export const PORTABLE_HANDOFF_CONTEXT_AUDIT_SCHEMA_ID = 'tiinex.portable.handoff-context-carriage-audit.v1';
+
+export function auditHandoffPackageContextCarriage(input = {}) {
+  const bundle = input.bundle || input;
+  if ((bundle.files || []).some((file) => String(file.path || '') === RECIPIENT_V2_READ_PATH)) return auditRecipientV2(bundle);
+  const findings = [];
+  const closureInspection = inspectHandoffClosureDescriptor(bundle);
+  const carrierInspection = inspectHandoffCarrierProjection(bundle);
+  const pointerInspection = inspectHandoffPointerEntrypoints(bundle);
+  findings.push(...(closureInspection.findings || []), ...(carrierInspection.findings || []), ...(pointerInspection.findings || []));
+  const descriptor = closureInspection.descriptor || {};
+  const carrier = carrierInspection.projection || {};
+  const fileMap = parseJsonFile(findFile(bundle, 'tiinex.package/file-map.json')) || bundle.fileMap || {};
+  const fileMapByPath = new Map((fileMap.entries || []).map((entry) => [String(entry.path || ''), entry]));
+  const byPath = new Map((bundle.files || []).map((file) => [String(file.path || ''), file]));
+  const workspaceEntries = indexWorkspaceEntries(descriptor.workspaceMaterializations || []);
+  const workspaceOuterCarriers = indexWorkspaceOuterCarriers(descriptor.workspaceArchiveBindings || []);
+  const workspaceByteIndex = indexWorkspaceBytes(descriptor.workspaceMaterializations || []);
+  const materialByPath = indexMaterialized(descriptor.materialized || []);
+  const requirementById = new Map([...(descriptor.requirements?.required || []), ...(descriptor.requirements?.reference || [])].map((item) => [String(item.requirementId || ''), item]));
+  const routeGroundingByPath = indexRouteGrounding(carrier.routes || []);
+
+  const bindingByWorkspace = new Map((descriptor.workspaceArchiveBindings || []).map((binding) => [String(binding.workspaceId || ''), binding]));
+  const workspaceGroups = (descriptor.workspaceMaterializations || []).map((workspace) => workspaceGroup(workspace, routeGroundingByPath, bindingByWorkspace.get(String(workspace.id || ''))));
+  const materialCarriers = [];
+  const explicitDetached = [];
+  const generatedEntrypoints = [];
+  const packageRequirements = [];
+  const unexplained = [];
+  let nonControlCarrierCount = 0;
+  let classifiedCarrierCount = 0;
+
+  for (const file of bundle.files || []) {
+    const path = String(file.path || '');
+    if (!path || isControlOrBootstrap(path)) continue;
+    nonControlCarrierCount += 1;
+    const mapEntry = fileMapByPath.get(path) || {};
+    const workspaceMatches = workspaceEntries.get(path) || [];
+    const workspaceOuterMatches = workspaceOuterCarriers.get(path) || [];
+    const materialMatches = materialByPath.get(path) || [];
+    if (workspaceMatches.length === 1 || workspaceOuterMatches.length === 1) {
+      classifiedCarrierCount += 1;
+      continue;
+    }
+    if (workspaceMatches.length > 1 || workspaceOuterMatches.length > 1) {
+      unexplained.push(summaryFile(file, mapEntry, 'ambiguous-workspace-carrier'));
+      findings.push(finding('error', 'portable.handoff-context.workspace-carrier.ambiguous', 'One package carrier is claimed by multiple workspace materializations.', { path, count: Math.max(workspaceMatches.length, workspaceOuterMatches.length) }));
+      continue;
+    }
+    if (path.startsWith('handoff.material/')) {
+      if (materialMatches.length !== 1) {
+        unexplained.push(summaryFile(file, mapEntry, materialMatches.length ? 'ambiguous-requirement-material' : 'unbound-requirement-material'));
+        findings.push(finding('error', materialMatches.length ? 'portable.handoff-context.material.ambiguous' : 'portable.handoff-context.material.unbound', 'handoff.material carrier is not uniquely bound to one materialized Handoff requirement.', { path, count: materialMatches.length }));
+        continue;
+      }
+      const material = materialMatches[0];
+      const requirement = requirementById.get(String(material.requirementId || '')) || {};
+      const bytes = packageFileBytes(file);
+      const actualSha256 = bytes.byteLength ? sha256Hex(bytes) : String(mapEntry.sha256 || '');
+      const duplicateWorkspaceBytes = workspaceByteIndex.get(`${Number(material.bytes || 0)}:${String(material.sha256 || '')}`) || [];
+      materialCarriers.push(Object.freeze({
+        path,
+        reason: material.classification === 'reference' ? 'resolved-reference-context' : 'resolved-required-context',
+        requirement: Object.freeze({ id: String(material.requirementId || ''), name: String(requirement.name || ''), classification: String(material.classification || ''), referenceTarget: String(material.referenceTarget || '') }),
+        selectedProvider: Object.freeze({ ...(material.provider || {}) }),
+        provenance: Object.freeze({ ...(material.provenance || {}) }),
+        authority: Object.freeze({ ...(material.authority || {}) }),
+        bytes: Number(material.bytes || 0),
+        sha256: String(material.sha256 || ''),
+        actualBytes: bytes.byteLength || Number(mapEntry.bytes || 0),
+        actualSha256,
+        identicalWorkspaceBytes: Object.freeze(duplicateWorkspaceBytes.map((entry) => Object.freeze({ workspaceId: entry.workspaceId, workspaceRelativePath: entry.path, packagePath: entry.packagePath })))
+      }));
+      classifiedCarrierCount += 1;
+      continue;
+    }
+    if (isHandoffPointerEntrypointPath(path)) {
+      generatedEntrypoints.push(Object.freeze({ ...summaryFile(file, mapEntry, 'generated-pointer-entrypoint'), authority: 'none' }));
+      classifiedCarrierCount += 1;
+      continue;
+    }
+    if (isNamedBasePackageRequirement(mapEntry)) {
+      packageRequirements.push(Object.freeze({ ...summaryFile(file, mapEntry, namedBasePackageReason(mapEntry)), boundary: String(mapEntry.boundary || '') }));
+      classifiedCarrierCount += 1;
+      continue;
+    }
+    if (isExplicitDetachedTransport(mapEntry)) {
+      explicitDetached.push(Object.freeze({ ...summaryFile(file, mapEntry, 'explicitly-supplied-detached-material'), semanticLooking: /\.trace\.md$/i.test(path) }));
+      classifiedCarrierCount += 1;
+      if (/\.trace\.md$/i.test(path)) findings.push(finding('warning', 'portable.handoff-context.detached.semantic-artifact', 'Detached transport material looks like a Tiinex trace artifact but is not route/requirement grounding. Its carriage is explicit, not semantically justified by the Handoff.', { path }));
+      continue;
+    }
+    unexplained.push(summaryFile(file, mapEntry, 'unexplained'));
+    findings.push(finding('error', 'portable.handoff-context.carrier.unexplained', 'Non-control/non-bootstrap package carrier has no explicit qualified carriage reason.', { path, kind: String(mapEntry.kind || file.kind || '') }));
+  }
+
+  for (const material of descriptor.materialized || []) {
+    if (String(material.carrierKind || '') !== 'workspace-archive-entry') continue;
+    const requirement = requirementById.get(String(material.requirementId || '')) || {};
+    const duplicateWorkspaceBytes = workspaceByteIndex.get(`${Number(material.bytes || 0)}:${String(material.sha256 || '')}`) || [];
+    materialCarriers.push(Object.freeze({
+      path: '',
+      reason: material.classification === 'reference' ? 'resolved-reference-context-via-workspace-archive' : 'resolved-required-context-via-workspace-archive',
+      requirement: Object.freeze({ id: String(material.requirementId || ''), name: String(requirement.name || ''), classification: String(material.classification || ''), referenceTarget: String(material.referenceTarget || '') }),
+      selectedProvider: Object.freeze({ ...(material.provider || {}) }),
+      provenance: Object.freeze({ ...(material.provenance || {}) }),
+      authority: Object.freeze({ ...(material.authority || {}) }),
+      carrierKind: 'workspace-archive-entry',
+      workspaceId: String(material.workspaceId || ''),
+      workspaceRelativePath: String(material.workspaceRelativePath || ''),
+      bytes: Number(material.bytes || 0),
+      sha256: String(material.sha256 || ''),
+      actualBytes: Number(material.bytes || 0),
+      actualSha256: String(material.sha256 || ''),
+      identicalWorkspaceBytes: Object.freeze(duplicateWorkspaceBytes.map((entry) => Object.freeze({ workspaceId: entry.workspaceId, workspaceRelativePath: entry.path, packagePath: entry.packagePath })))
+    }));
+  }
+
+  const coverageQualified = classifiedCarrierCount === nonControlCarrierCount && unexplained.length === 0;
+  if (!coverageQualified) findings.push(finding('error', 'portable.handoff-context.coverage.incomplete', 'Context-carriage audit did not classify every non-control/non-bootstrap package carrier.', { nonControlCarrierCount, classifiedCarrierCount, unexplained: unexplained.length }));
+
+  const duplicateMaterialCount = materialCarriers.filter((item) => item.identicalWorkspaceBytes.length > 0).length;
+  return deepFreeze({
+    schema: PORTABLE_HANDOFF_CONTEXT_AUDIT_SCHEMA_ID,
+    status: findings.some((item) => item.severity === 'error') ? 'blocked' : 'ready',
+    coverage: Object.freeze({ nonControlCarrierCount, classifiedCarrierCount, unexplainedCarrierCount: unexplained.length, state: coverageQualified ? 'qualified' : 'incomplete' }),
+    workspaceMaterializations: Object.freeze(workspaceGroups),
+    materialCarriers: Object.freeze(materialCarriers),
+    generatedEntrypoints: Object.freeze(generatedEntrypoints),
+    namedPackageRequirements: Object.freeze(packageRequirements),
+    explicitDetachedMaterial: Object.freeze(explicitDetached),
+    unexplainedCarriers: Object.freeze(unexplained),
+    duplicateByteSummary: Object.freeze({ materialCarriersAlsoPresentInWorkspace: duplicateMaterialCount, totalMaterialCarriers: materialCarriers.length, interpretation: 'Duplicate bytes are visible evidence only. The audit does not infer that duplication is semantically required.' }),
+    routeGrounding: Object.freeze((carrier.routes || []).map((route) => Object.freeze({ routeId: String(route.id || ''), workspaceId: String(route.workspaceId || ''), handoffPackagePath: String(route.packagePath || ''), required: Object.freeze((route.requiredClosure?.requirements || []).map((item) => Object.freeze({ requirementId: String(item.requirementId || ''), name: String(item.name || ''), referenceTarget: String(item.referenceTarget || ''), state: String(item.state || ''), resolution: item.resolution || null }))) }))),
+    inspections: Object.freeze({ closure: closureInspection.status, carrier: carrierInspection.status, pointers: pointerInspection.status }),
+    findings: Object.freeze(dedupeFindings(findings)),
+    boundary: 'Recipient-relative carriage/provenance audit only. Complete workspace membership is classified as snapshot carriage, not automatically as Handoff Required Context; semantic relevance inside complete workspaces is not inferred.'
+  });
+}
+
+
+function auditRecipientV2(bundle = {}) {
+  const inspection = inspectRecipientFacingV2Topology(bundle);
+  const files = bundle.files || [];
+  const workspacePayloadPaths = new Set((inspection.workspaces || []).flatMap((item) => [item.workspaceArtifactPath, item.workspaceRepresentationArtifactPath, item.workspacePayloadArtifactPath, item.workspaceArchivePath]));
+  const routePointerPaths = new Set((inspection.routes || []).map((item) => item.pointerPath));
+  const endpointRolePointerPaths = new Set((inspection.endpointRoles || []).map((item) => item.pointerPath));
+  const participantRolePointerPaths = new Set((inspection.participantRoles || []).map((item) => item.pointerPath));
+  const cachePaths = new Set((inspection.caches || []).flatMap((cache) => [cache.artifactPath, cache.archivePath]));
+  const rootPath = String(inspection.rootArtifact?.path || '');
+  const classified = files.filter((file) => {
+    const path = String(file.path || '');
+    return path === rootPath || path === RECIPIENT_V2_READ_PATH || path === RECIPIENT_V2_TRANSPORT_MANIFEST_PATH || workspacePayloadPaths.has(path) || routePointerPaths.has(path) || endpointRolePointerPaths.has(path) || participantRolePointerPaths.has(path) || cachePaths.has(path) || /bootstrap\.(?:trace\.md|zip)$/i.test(path);
+  }).length;
+  const unexplained = Math.max(0, files.length - classified);
+  const findings = [...(inspection.findings || [])];
+  if (unexplained) findings.push(finding('error', 'portable.handoff-context.v2.coverage.incomplete', 'Recipient-facing v2 context audit could not classify every visible root carrier.', { total: files.length, classified, unexplained }));
+  const cacheMaterials = (inspection.caches || []).flatMap((cache) => cache.materials || []);
+  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 }))), 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 }), findings: Object.freeze(dedupeFindings(findings)), boundary: 'Recipient-facing v2 carriage audit over qualified visible Tiinex artifacts, exact payload bytes, and one transport-owned manifest control surface.' });
+}
+
+function indexWorkspaceEntries(workspaces = []) {
+  const map = new Map();
+  for (const workspace of workspaces) for (const entry of workspace.includedEntries || []) {
+    const path = String(entry.packagePath || '');
+    if (!path) continue;
+    const list = map.get(path) || [];
+    list.push(Object.freeze({ workspaceId: String(workspace.id || ''), materialization: String(workspace.materialization || ''), ...entry }));
+    map.set(path, list);
+  }
+  return map;
+}
+function indexWorkspaceOuterCarriers(bindings = []) {
+  const map = new Map();
+  const add = (path, value) => { if (!path) return; const list = map.get(path) || []; list.push(value); map.set(path, list); };
+  for (const binding of bindings) {
+    add(String(binding.workspaceTarget?.packagePath || ''), Object.freeze({ workspaceId: String(binding.workspaceId || ''), role: 'workspace-target' }));
+    add(String(binding.representation?.packagePath || ''), Object.freeze({ workspaceId: String(binding.workspaceId || ''), role: 'workspace-archive' }));
+  }
+  return map;
+}
+function indexWorkspaceBytes(workspaces = []) {
+  const map = new Map();
+  for (const workspace of workspaces) for (const entry of workspace.includedEntries || []) {
+    const key = `${Number(entry.bytes || 0)}:${String(entry.sha256 || '')}`;
+    const list = map.get(key) || [];
+    list.push(Object.freeze({ workspaceId: String(workspace.id || ''), path: String(entry.path || ''), packagePath: String(entry.packagePath || '') }));
+    map.set(key, list);
+  }
+  return map;
+}
+function indexMaterialized(items = []) {
+  const map = new Map();
+  for (const item of items) {
+    const path = String(item.packagePath || '');
+    if (!path) continue;
+    const list = map.get(path) || [];
+    list.push(item);
+    map.set(path, list);
+  }
+  return map;
+}
+function indexRouteGrounding(routes = []) {
+  const map = new Map();
+  const add = (path, role) => { if (!path) return; const list = map.get(path) || []; list.push(role); map.set(path, list); };
+  for (const route of routes) {
+    add(String(route.packagePath || ''), Object.freeze({ routeId: String(route.id || ''), role: 'controlling-handoff' }));
+    for (const requirement of route.requiredClosure?.requirements || []) add(String(requirement.resolution?.packagePath || ''), Object.freeze({ routeId: String(route.id || ''), role: 'required-context', requirementId: String(requirement.requirementId || ''), name: String(requirement.name || '') }));
+  }
+  return map;
+}
+function workspaceGroup(workspace = {}, routeGroundingByPath, archiveBinding = null) {
+  const entries = workspace.includedEntries || [];
+  const grounding = [];
+  for (const entry of entries) for (const role of routeGroundingByPath.get(String(entry.packagePath || '')) || []) grounding.push(Object.freeze({ workspaceRelativePath: String(entry.path || ''), packagePath: String(entry.packagePath || ''), ...role }));
+  return Object.freeze({
+    workspaceId: String(workspace.id || ''),
+    title: String(workspace.title || workspace.id || ''),
+    reason: workspace.materialization === 'complete' ? 'complete-workspace-materialization' : 'partial-workspace-materialization',
+    qualification: String(workspace.qualification || ''),
+    correlationStatus: String(workspace.correlationStatus || ''),
+    entryCount: entries.length,
+    totalBytes: entries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0),
+    completenessEvidence: Object.freeze({ ...(workspace.completenessEvidence || {}) }),
+    routeGrounding: Object.freeze(grounding),
+    ...(archiveBinding ? { carrierMode: 'archive', workspaceTargetPackagePath: String(archiveBinding.workspaceTarget?.packagePath || ''), archivePackagePath: String(archiveBinding.representation?.packagePath || '') } : { carrierMode: 'exploded' }),
+    interpretation: 'Workspace snapshot carriage is distinct from route Required Context; only routeGrounding entries are known to participate in explicit route grounding.'
+  });
+}
+function isControlOrBootstrap(path) { return path.startsWith('tiinex.package/') || path.startsWith('tiinex.bootstrap/'); }
+function isNamedBasePackageRequirement(entry = {}) { return ['workspace-context', 'artifact-markdown', 'asset', 'workspace-source-material', 'workspace-member-material'].includes(String(entry.kind || '')) || String(entry.path || '').startsWith('context/'); }
+function namedBasePackageReason(entry = {}) { const kind = String(entry.kind || ''); if (kind === 'workspace-context' || String(entry.path || '').startsWith('context/')) return 'base-package-workspace-context'; return `base-package-${kind || 'material'}`; }
+function isExplicitDetachedTransport(entry = {}) { return String(entry.kind || '').includes('transport-material') || String(entry.logicalKind || '') === 'recipient-relative-transport-material'; }
+function summaryFile(file = {}, mapEntry = {}, reason = '') { const data = packageFileBytes(file); return Object.freeze({ path: String(file.path || ''), reason, kind: String(mapEntry.kind || file.kind || ''), logicalKind: String(mapEntry.logicalKind || file.logicalKind || ''), bytes: data.byteLength || Number(mapEntry.bytes || file.size || 0), sha256: data.byteLength ? sha256Hex(data) : String(mapEntry.sha256 || '') }); }
+function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+function parseJsonFile(file = null) { try { return file ? JSON.parse(new TextDecoder().decode(packageFileBytes(file))) : null; } catch { return null; } }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function dedupeFindings(items = []) { const map = new Map(); for (const item of items) { const key = `${item.severity || ''}:${item.code || ''}:${item.path || item.packagePath || item.requirementId || ''}:${item.message || ''}`; if (!map.has(key)) map.set(key, item); } return [...map.values()]; }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }