@tiinex/core 0.1.1

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

@@ -0,0 +1,194 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectRecipientV2Artifact, parseRecipientV2Pointer, parseRecipientV2Relation } from './recipientV2.artifacts.js';
+import { inspectRecipientV2TransportManifest, RECIPIENT_V2_TRANSPORT_MANIFEST_PATH } from './recipientV2.transportManifest.js';
+import { qualifyPhase1WorkspaceCarriers, PHASE1_COMPLETE_WORKSPACE_ROLE, PHASE1_BOUNDED_WORKSPACE_ROLE } from './recipientV2.artifactFirst.workspaces.js';
+import { deriveRecipientV2ArtifactFirstPhase1Facts, parsePhase1Payload, qualifyPhase1BootstrapPayload, qualifyPhase1CachePayload } from './recipientV2.artifactFirst.materials.js';
+import { phase1CacheParentCandidates } from './recipientV2.artifactFirst.closure.js';
+import { qualifyPhase1RouteBindings, validatePhase1IngressBindings } from './recipientV2.artifactFirst.routes.js';
+import { RECIPIENT_V2_READ_PATH, RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_SCHEMA_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_FORMAT_ID, RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_SCHEMA_ID, PHASE2_CLEAN_PROFILE, PHASE2_COMPATIBILITY_TRANSPORT, PHASE1_BOOTSTRAP_ROLE, PHASE1_CACHE_ROLE, artifactFirstCarrierFilename, safeToken, currentSchemaId, decodeUtf8, stableJson, deepFreeze, finding } from './recipientV2.artifactFirst.shared.js';
+
+export function inspectRecipientV2ArtifactFirstPhase1Specimen(bundle = {}) {
+  const files = Array.isArray(bundle) ? bundle : (bundle.files || []);
+  const findings = [];
+  const semanticFiles = files.filter((file) => String(file.path || '') !== RECIPIENT_V2_TRANSPORT_MANIFEST_PATH);
+  const markdownFiles = semanticFiles.filter((file) => /\.md$/i.test(String(file.path || '')));
+  const workspaceWrappers = markdownFiles.filter((file) => currentSchemaId(decodeUtf8(packageFileBytes(file))) === 'tiinex.workspace.v1');
+  if (workspaceWrappers.length) findings.push(finding('error', 'portable.handoff-v2-phase1.workspace-wrapper.present', 'Phase 1 artifact-first specimen must not generate an outer Workspace wrapper.', { count: workspaceWrappers.length }));
+
+  const factsByPath = deriveRecipientV2ArtifactFirstPhase1Facts(semanticFiles);
+  const qualified = markdownFiles.map((file) => inspectRecipientV2Artifact(file, { facts: factsByPath.get(String(file.path || '')) || null }));
+  for (const item of qualified) findings.push(...(item.findings || []));
+
+  const pointers = qualified.filter((item) => item.schemaId === 'tiinex.pointer.v1').map((item) => ({ ...item, parsed: parseRecipientV2Pointer(item.markdown) }));
+  const payloads = qualified.filter((item) => item.schemaId === 'tiinex.external.payload.v1').map((item) => ({ ...item, parsed: parsePhase1Payload(item.markdown) }));
+  const relations = qualified.filter((item) => item.schemaId === 'tiinex.relation.v1').map((item) => ({ ...item, parsed: parseRecipientV2Relation(item.markdown) }));
+  const ingress = pointers.filter((item) => item.path === RECIPIENT_V2_READ_PATH && item.parsed.role === 'recovery-orientation');
+  const routes = pointers.filter((item) => item.parsed.role === 'handoff-route');
+  const endpointPointers = pointers.filter((item) => item.parsed.role === 'endpoint-role');
+  const participantPointers = pointers.filter((item) => item.parsed.role === 'participant-role');
+  const workspacePayloads = payloads.filter((item) => [PHASE1_COMPLETE_WORKSPACE_ROLE, PHASE1_BOUNDED_WORKSPACE_ROLE].includes(item.parsed.payloadRole));
+  const bootstrapPayloads = payloads.filter((item) => item.parsed.payloadRole === PHASE1_BOOTSTRAP_ROLE);
+  const cachePayloads = payloads.filter((item) => item.parsed.payloadRole === PHASE1_CACHE_ROLE);
+  const unknownPayloads = payloads.filter((item) => ![PHASE1_COMPLETE_WORKSPACE_ROLE, PHASE1_BOUNDED_WORKSPACE_ROLE, PHASE1_BOOTSTRAP_ROLE, PHASE1_CACHE_ROLE].includes(item.parsed.payloadRole));
+  if (ingress.length !== 1) findings.push(finding('error', 'portable.handoff-v2-phase1.ingress.count', 'Phase 1 specimen requires exactly one ingress Pointer.', { count: ingress.length }));
+  if (!routes.length) findings.push(finding('error', 'portable.handoff-v2-phase1.route.count', 'Artifact-first specimen requires at least one visible Handoff route Pointer.', { count: routes.length }));
+  if (!workspacePayloads.length) findings.push(finding('error', 'portable.handoff-v2-phase1.payload.workspace-count', 'Artifact-first full-source carriage requires at least one Workspace External Payload artifact.', { count: workspacePayloads.length }));
+  if (bootstrapPayloads.length > 1) findings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.count', 'A carried portable Tooling bootstrap must have exactly one owning External Payload artifact.', { count: bootstrapPayloads.length }));
+  if (cachePayloads.length > 1) findings.push(finding('error', 'portable.handoff-v2-phase1.cache.count', 'A selected Workspace may expose at most one selected-route dependency cache External Payload.', { count: cachePayloads.length }));
+  if (unknownPayloads.length) findings.push(finding('error', 'portable.handoff-v2-phase1.payload.unclassified', 'Phase 1 specimen contains an External Payload artifact outside the bounded Workspace/bootstrap/cache ownership subset.', { count: unknownPayloads.length }));
+  if (!relations.length) findings.push(finding('error', 'portable.handoff-v2-phase1.relation.count', 'Artifact-first full-source carriage requires a typed material-representation Relation for every carried Workspace.', { count: relations.length }));
+  if (markdownFiles.some((file) => factsByPath.get(String(file.path || ''))?.role === 'package-root')) findings.push(finding('error', 'portable.handoff-v2-phase1.package-root.present', 'Phase 1 specimen must not use a package-root Pointer as receiver semantic authority.'));
+
+  const bootstrapPayload = bootstrapPayloads[0] || null;
+  const ingressPointer = ingress[0];
+  const selectedRouteIdFromIngress = String(ingressPointer?.parsed?.selectedRouteId || '');
+  const bootstrapQualification = bootstrapPayload ? qualifyPhase1BootstrapPayload(bootstrapPayload, semanticFiles, findings) : null;
+  const cacheQualifications = cachePayloads.map((item) => qualifyPhase1CachePayload(item, semanticFiles, findings));
+  const recoveryParentCandidates = phase1CacheParentCandidates(cacheQualifications);
+  const workspaceQualificationList = qualifyPhase1WorkspaceCarriers({ workspacePayloads, relations, semanticFiles, recoveryParentCandidates, findings });
+  const workspaceQualifications = new Map(workspaceQualificationList.map((item) => [String(item.workspaceId || ''), item]));
+  const endpointRoleQualifications = [];
+  const participantRoleQualifications = [];
+  const rolePointers = [...endpointPointers, ...participantPointers];
+  const boundRolePaths = new Set();
+  const routeQualifications = [];
+
+  qualifyPhase1RouteBindings({
+    routes, workspaceQualifications, findings, recoveryParentCandidates, selectedRouteIdFromIngress, cacheQualifications, rolePointers, endpointPointers, participantPointers, cachePayloads, endpointRoleQualifications, participantRoleQualifications, boundRolePaths, routeQualifications
+  });
+
+  validatePhase1IngressBindings({ workspaceQualificationList, ingressPointer, routes, bootstrapPayload, cachePayloads, rolePointers, boundRolePaths, findings });
+
+  if (ingressPointer) {
+    const candidateCount = Number(ingressPointer.parsed.candidateRouteCount || 0);
+    const selectedRouteId = String(ingressPointer.parsed.selectedRouteId || '');
+    const mode = String(ingressPointer.parsed.routeSelection || '');
+    if (candidateCount < 1) findings.push(finding('error', 'portable.handoff-v2-phase1.route-selection.candidate-count-missing', 'Ingress Pointer must preserve the qualified candidate-route count used for artifact-first selection.'));
+    if (candidateCount !== routes.length) findings.push(finding('error', 'portable.handoff-v2-phase1.route-selection.candidate-count-mismatch', 'Ingress candidate-route count must equal the complete visible shared route set.', { candidateCount, visibleRouteCount: routes.length }));
+    if (candidateCount > 1 && mode !== 'explicit-qualified-route-selector') findings.push(finding('error', 'portable.handoff-v2-phase1.route-selection.explicit-required', 'More than one qualified source Handoff route requires one explicit default recipient route selector.'));
+    if (candidateCount === 1 && mode !== 'implicit-single-qualified-route' && mode !== 'explicit-qualified-route-selector') findings.push(finding('error', 'portable.handoff-v2-phase1.route-selection.mode-invalid', 'Single-route artifact-first selection mode is unsupported.', { mode }));
+    const selectedMatches = routeQualifications.filter((item) => item.routeId === selectedRouteId);
+    if (!selectedRouteId || selectedMatches.length !== 1) findings.push(finding('error', 'portable.handoff-v2-phase1.route-selection.binding-mismatch', 'Ingress route selection must bind exactly one member of the complete visible shared route set.', { selectedRouteId, matches: selectedMatches.length }));
+  }
+
+  const selectedRouteQualification = routeQualifications.find((item) => item.routeId === selectedRouteIdFromIngress) || routeQualifications[0] || null;
+  const payload = selectedRouteQualification?.payload || null;
+  const relation = selectedRouteQualification?.relation || null;
+  const route = selectedRouteQualification?.route || null;
+  const routeEntry = selectedRouteQualification?.routeEntry || null;
+  const routeConformance = selectedRouteQualification?.routeConformance || null;
+  const requiredClosure = selectedRouteQualification?.requiredClosure || Object.freeze({ state: 'blocked', requiredCount: 0, qualifiedCount: 0, requirements: Object.freeze([]) });
+  const workspaceTargetQualification = selectedRouteQualification?.workspaceTargetQualification || null;
+  const semanticStatus = findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified';
+  const cleanCarrierPhase2 = Boolean(
+    ingressPointer
+    && ingressPointer.parsed.carrierProfile === PHASE2_CLEAN_PROFILE
+    && ingressPointer.parsed.compatibilityTransport === PHASE2_COMPATIBILITY_TRANSPORT
+  );
+  if (ingressPointer && (Boolean(ingressPointer.parsed.carrierProfile) !== Boolean(ingressPointer.parsed.compatibilityTransport))) findings.push(finding('error', 'portable.handoff-v2-phase2.clean-profile.incomplete', 'Clean-carrier profile and compatibility-transport declaration must appear together on the visible ingress Pointer.'));
+  if (ingressPointer?.parsed?.carrierProfile && ingressPointer.parsed.carrierProfile !== PHASE2_CLEAN_PROFILE) findings.push(finding('error', 'portable.handoff-v2-phase2.clean-profile.unsupported', 'Artifact-first ingress declares an unsupported clean-carrier profile.', { profile: ingressPointer.parsed.carrierProfile }));
+  if (ingressPointer?.parsed?.compatibilityTransport && ingressPointer.parsed.compatibilityTransport !== PHASE2_COMPATIBILITY_TRANSPORT) findings.push(finding('error', 'portable.handoff-v2-phase2.compatibility-transport.unsupported', 'Artifact-first ingress declares an unsupported compatibility-transport mode.', { mode: ingressPointer.parsed.compatibilityTransport }));
+  const transport = inspectRecipientV2TransportManifest(files);
+  const compatibilityFindings = [...(transport.findings || [])];
+  let compatibilityStatus = transport.state;
+  if (cleanCarrierPhase2) {
+    if (transport.state !== 'absent') compatibilityFindings.push(finding('error', 'portable.handoff-v2-phase2.compatibility.present', 'Clean-carrier Phase 2 profile must omit stored compatibility JSON; visible semantic artifacts and exact payload bytes are the complete receiver truth surface.'));
+    compatibilityStatus = compatibilityFindings.some((item) => item.severity === 'error') ? 'invalid' : 'omitted-qualified';
+  } else if (transport.state === 'valid') {
+    if (String(transport.manifest?.format || '') !== RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID) compatibilityFindings.push(finding('error', 'portable.handoff-v2-phase1.compatibility.format-mismatch', 'Compatibility JSON format does not identify the Phase 1 artifact-first specimen.'));
+    const declaredFacts = transport.factsByPath || new Map();
+    for (const [path, facts] of factsByPath) if (stableJson(declaredFacts.get(path) || null) !== stableJson(facts)) compatibilityFindings.push(finding('error', 'portable.handoff-v2-phase1.compatibility.not-derived', 'Compatibility JSON facts diverge from facts re-derived from visible semantic artifacts.', { path }));
+    compatibilityStatus = compatibilityFindings.some((item) => item.severity === 'error') ? 'invalid' : 'valid';
+  }
+  const finalSemanticStatus = findings.some((item) => item.severity === 'error') ? 'blocked' : semanticStatus;
+  const status = finalSemanticStatus === 'qualified' && (cleanCarrierPhase2 ? compatibilityStatus === 'omitted-qualified' : compatibilityStatus === 'valid') ? 'ready' : 'blocked';
+  const workspaceId = String(selectedRouteQualification?.workspaceId || payload?.parsed?.workspaceId || relation?.parsed?.targetWorkspaceId || route?.parsed?.workspaceId || '');
+  const lineage = ingressPointer ? Object.freeze({
+    mode: ingressPointer.parsed.carrierDimension?.includes('-') ? 'continue' : 'root',
+    dimension: String(ingressPointer.parsed.carrierDimension || ''),
+    parentDimension: String(ingressPointer.parsed.parentCarrierDimension || ''),
+    checkpointKind: String(ingressPointer.parsed.carrierCheckpoint || '')
+  }) : Object.freeze({ mode: '', dimension: '', parentDimension: '', checkpointKind: '' });
+  const carrierRoutes = routeQualifications.map((item) => item.route && item.routeEntry ? Object.freeze({
+    id: item.routeId,
+    workspaceId: item.workspaceId,
+    state: item.reasons.length ? 'blocked' : 'qualified',
+    workspaceRelativePath: String(item.route.parsed.handoffWorkspacePath || ''),
+    packagePath: String(item.payload?.parsed?.location || ''),
+    providerMode: 'archive',
+    archivePackagePath: String(item.payload?.parsed?.location || ''),
+    sha256: String(item.routeEntry.sha256 || ''),
+    dimension: String(lineage.dimension || ''),
+    parties: item.routeParties,
+    purpose: '',
+    projectedFilename: artifactFirstCarrierFilename(item.workspaceId, lineage.dimension, item.routeParties.from, item.routeParties.to),
+    conformance: item.routeConformance,
+    requiredClosure: item.requiredClosure,
+    endpointRolePointers: Object.freeze(item.endpointRoles.filter((role) => role.state === 'qualified').map((role) => role.pointerPath)),
+    participantRolePointers: Object.freeze(item.participantRoles.filter((role) => role.state === 'qualified').map((role) => role.pointerPath)),
+    reasons: item.reasons,
+    authority: Object.freeze({ artifactPartiesAuthoritative: true, dimensionSemanticAuthority: false, filenameSemanticAuthority: false })
+  }) : null).filter(Boolean);
+  const selectedRouteId = String(selectedRouteIdFromIngress || selectedRouteQualification?.routeId || '');
+  const selectedCarrierRoute = carrierRoutes.find((item) => item.id === selectedRouteId) || null;
+  const selectedWorkspaceQualification = workspaceQualifications.get(workspaceId) || null;
+  const sourceCandidateRouteCount = Number(ingressPointer?.parsed?.candidateRouteCount || 0);
+  const sourceSelectionMode = String(ingressPointer?.parsed?.routeSelection || '');
+  const selectionPolicy = sourceCandidateRouteCount > 1 || sourceSelectionMode === 'explicit-qualified-route-selector'
+    ? 'explicit-qualified-route-bound'
+    : 'implicit-single-qualified-route';
+  const qualifiedRouteCount = carrierRoutes.filter((item) => item.state === 'qualified').length;
+  const allVisibleRoutesQualified = carrierRoutes.length === routeQualifications.length && qualifiedRouteCount === carrierRoutes.length;
+  const carrierProjection = deepFreeze({
+    schema: 'tiinex.portable.handoff-carrier-projection.v1',
+    version: 1,
+    status: finalSemanticStatus === 'qualified' && allVisibleRoutesQualified && selectedCarrierRoute?.state === 'qualified' ? 'ready' : 'blocked',
+    mode: routeQualifications.length > 1 ? 'shared' : 'single',
+    lineage,
+    workspaces: Object.freeze(workspaceQualificationList.map((item) => Object.freeze({ id: item.workspaceId, title: item.workspaceId, slug: safeToken(item.workspaceId), qualification: item.workspaceTargetQualification?.state === 'qualified' ? 'qualified' : 'blocked' }))),
+    workspace: workspaceId ? Object.freeze({ id: workspaceId, title: workspaceId, slug: safeToken(workspaceId), qualification: selectedWorkspaceQualification?.workspaceTargetQualification?.state === 'qualified' ? 'qualified' : 'blocked' }) : Object.freeze({ id: '', title: '', slug: '', qualification: 'unresolved' }),
+    selection: Object.freeze({ policy: selectionPolicy, qualifiedRouteCount, sourceCandidateRouteCount, selectedRouteId }),
+    routes: Object.freeze(carrierRoutes),
+    authority: Object.freeze({ semanticAuthority: 'none', filenameAuthority: false, dimensionalParentAuthority: false, routeSelectionAuthority: 'qualified-visible-route-pointer-plus-exact-handoff-bytes' }),
+    findings: Object.freeze([])
+  });
+  const coldConsumerProjection = deepFreeze({
+    schema: 'tiinex.portable.handoff-cold-consumer-projection.v1',
+    version: 1,
+    status: carrierProjection.status,
+    workspaces: carrierProjection.workspaces,
+    routes: Object.freeze(carrierProjection.routes.map((item) => Object.freeze({ id: item.id, state: item.state, workspaceId: item.workspaceId, workspaceRelativeHandoffPath: item.workspaceRelativePath, packagePath: item.packagePath, sha256: item.sha256, from: item.parties?.from || '', to: item.parties?.to || '', endpointRolePointers: Object.freeze(item.endpointRolePointers || []), participantRolePointers: Object.freeze(item.participantRolePointers || []) }))),
+    selection: Object.freeze({ policy: carrierProjection.selection.policy, qualifiedRouteCount: carrierProjection.selection.qualifiedRouteCount, implicitRouteId: carrierProjection.routes.length === 1 && carrierProjection.routes[0].state === 'qualified' ? carrierProjection.routes[0].id : '' }),
+    authority: Object.freeze({ semanticAuthority: 'none', packageTruthRequired: true, routeBindingAuthority: 'visible-route-pointer-plus-exact-payload-and-handoff-bytes' })
+  });
+  const format = cleanCarrierPhase2 ? RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_FORMAT_ID : RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID;
+  return deepFreeze({
+    schema: cleanCarrierPhase2 ? RECIPIENT_V2_ARTIFACT_FIRST_PHASE2_CLEAN_SCHEMA_ID : RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_SCHEMA_ID,
+    format,
+    cleanCarrierPhase2,
+    status,
+    semanticStatus: finalSemanticStatus,
+    compatibilityStatus,
+    workspaceId,
+    coverage: payload?.parsed?.payloadRole === PHASE1_BOUNDED_WORKSPACE_ROLE ? 'bounded' : 'complete',
+    handoffWorkspacePath: String(route?.parsed?.handoffWorkspacePath || ''),
+    workspaceTargetQualification,
+    routeEntry: routeEntry ? Object.freeze({ path: routeEntry.path, bytes: routeEntry.bytes, sha256: routeEntry.sha256 }) : null,
+    routeConformance,
+    requiredClosure,
+    bootstrapQualification,
+    workspaces: Object.freeze(workspaceQualificationList.map((item) => Object.freeze({ workspaceId: item.workspaceId, payloadArtifactPath: item.payload.path, representationArtifactPath: item.relation.path, archivePath: item.payload.parsed.location, coverage: item.payload.parsed.payloadRole === PHASE1_BOUNDED_WORKSPACE_ROLE ? 'bounded' : 'complete', workspaceTargetQualification: item.workspaceTargetQualification }))),
+    caches: Object.freeze(cacheQualifications.map((item) => Object.freeze({ workspaceId: item.workspaceId, artifactPath: item.artifactPath, archivePath: item.payloadPath, materials: item.materials }))),
+    endpointRoles: Object.freeze(endpointRoleQualifications.filter((item) => item.state === 'qualified').map((item) => Object.freeze({ pointerPath: item.pointerPath, workspaceId: item.workspaceId, routeId: item.routeId, requirementId: item.requirementId, endpointParty: item.endpointParty, roleLabelHint: item.roleLabelHint, referenceTarget: item.referenceTarget, targetCarrierKind: item.targetCarrierKind, targetWorkspaceId: item.targetWorkspaceId, archivePath: item.archivePath, targetInnerPath: item.targetInnerPath, targetArchiveEntry: item.targetArchiveEntry, targetBytes: item.targetBytes, targetSha256: item.targetSha256 }))),
+    participantRoles: Object.freeze(participantRoleQualifications.filter((item) => item.state === 'qualified').map((item) => Object.freeze({ pointerPath: item.pointerPath, workspaceId: item.workspaceId, routeId: item.routeId, requirementId: item.requirementId, roleLabelHint: item.roleLabelHint, referenceTarget: item.referenceTarget, targetCarrierKind: item.targetCarrierKind, targetWorkspaceId: item.targetWorkspaceId, archivePath: item.archivePath, targetInnerPath: item.targetInnerPath, targetArchiveEntry: item.targetArchiveEntry, targetBytes: item.targetBytes, targetSha256: item.targetSha256 }))),
+    routeSelection: ingressPointer ? Object.freeze({ mode: String(ingressPointer.parsed.routeSelection || ''), selectedRouteId: String(ingressPointer.parsed.selectedRouteId || ''), candidateCount: Number(ingressPointer.parsed.candidateRouteCount || 0) }) : null,
+    carrierProjection,
+    coldConsumerProjection,
+    transportManifest: transport.state === 'absent' ? null : Object.freeze({ state: transport.state, path: RECIPIENT_V2_TRANSPORT_MANIFEST_PATH, sha256: transport.file ? sha256Hex(packageFileBytes(transport.file)) : '' }),
+    semanticFactsByPath: factsByPath,
+    findings: Object.freeze([...findings, ...compatibilityFindings]),
+    boundary: cleanCarrierPhase2
+      ? 'Artifact-first Phase 2 clean-carrier qualification reconstructs receiver truth only from visible semantic artifacts plus exact payload bytes and requires stored compatibility JSON to be absent.'
+      : 'Artifact-first Phase 1 qualification keeps semantic receiver artifacts independently qualifiable from compatibility JSON. Phase 1 still requires the derived JSON projection for interoperability, but it is not receiver semantic authority.'
+  });
+}

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

@@ -0,0 +1,207 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { parseRecipientV2Pointer, parseRecipientV2Relation } from './recipientV2.artifacts.js';
+import { recipientV2TransportFacts } from './recipientV2.transportManifest.js';
+import { PHASE1_COMPLETE_WORKSPACE_ROLE, PHASE1_BOUNDED_WORKSPACE_ROLE } from './recipientV2.artifactFirst.workspaces.js';
+import { PHASE1_BOOTSTRAP_ROLE, PHASE1_CACHE_ROLE, currentSchemaId, decodeUtf8, oneFile, sectionText, fieldValue, markdownTarget, normalizeRoutePath, deepFreeze, finding } from './recipientV2.artifactFirst.shared.js';
+
+export function deriveRecipientV2ArtifactFirstPhase1Facts(files = []) {
+  const facts = new Map();
+  const payloadByPath = new Map();
+  const archiveByLocation = new Map();
+  const archiveIdentity = (location = '') => {
+    const key = String(location || '');
+    if (!key) return null;
+    if (archiveByLocation.has(key)) return archiveByLocation.get(key);
+    const file = oneFile(files, key);
+    if (!file) { archiveByLocation.set(key, null); return null; }
+    const bytes = packageFileBytes(file);
+    const identity = Object.freeze({ file, bytes, sha256: sha256Hex(bytes), archive: inspectStoredWorkspaceArchive(bytes, { ownedBytes: true }) });
+    archiveByLocation.set(key, identity);
+    return identity;
+  };
+  for (const file of files) {
+    const path = String(file.path || '');
+    if (!/\.md$/i.test(path)) continue;
+    const markdown = decodeUtf8(packageFileBytes(file));
+    if (currentSchemaId(markdown) === 'tiinex.external.payload.v1') payloadByPath.set(path, parsePhase1Payload(markdown));
+  }
+  for (const file of files) {
+    const path = String(file.path || '');
+    if (!/\.md$/i.test(path)) continue;
+    const markdown = decodeUtf8(packageFileBytes(file));
+    const schemaId = currentSchemaId(markdown);
+    if (schemaId === 'tiinex.pointer.v1') {
+      const parsed = parseRecipientV2Pointer(markdown);
+      if (parsed.role === 'participant-role' || parsed.role === 'endpoint-role') {
+        const roleKind = parsed.role === 'endpoint-role' ? 'endpoint-role' : 'participant-role';
+        const targetPayload = payloadByPath.get(String(parsed.targetPayload || '')) || null;
+        const targetArchiveIdentity = targetPayload ? archiveIdentity(targetPayload.location) : null;
+        const archive = targetArchiveIdentity?.archive || null;
+        const targetPath = parsed.targetCarrierKind === 'workspace-cache-entry' ? parsed.targetArchiveEntry : parsed.targetInnerPath;
+        const targetMatches = archive?.state === 'qualified' ? archive.entries.filter((entry) => String(entry.path || '') === String(targetPath || '')) : [];
+        const target = targetMatches.length === 1 ? targetMatches[0] : null;
+        const targetBytes = target ? packageFileBytes({ data: target.data }) : new Uint8Array();
+        facts.set(path, recipientV2TransportFacts(roleKind, {
+          workspaceId: parsed.workspaceId || '',
+          routeId: parsed.routeId || '',
+          ...(roleKind === 'endpoint-role' ? { endpointRequirementId: parsed.endpointRequirementId || '', endpointParty: parsed.endpointParty || '' } : { participantRequirementId: parsed.participantRequirementId || '' }),
+          roleLabelHint: parsed.roleLabelHint || '',
+          referenceTarget: parsed.roleReference || '',
+          targetCarrierKind: parsed.targetCarrierKind || '',
+          targetWorkspaceId: parsed.targetWorkspaceId || '',
+          archivePath: targetPayload?.location || '',
+          archiveSha256: targetArchiveIdentity?.sha256 || '',
+          targetInnerPath: parsed.targetInnerPath || '',
+          targetArchiveEntry: parsed.targetArchiveEntry || '',
+          targetBytes: targetBytes.byteLength,
+          targetSha256: targetBytes.byteLength ? sha256Hex(targetBytes) : ''
+        }));
+      } else facts.set(path, recipientV2TransportFacts(parsed.role || 'navigation', {
+          workspaceId: parsed.workspaceId || '',
+          payloadArtifactPath: parsed.workspacePayload || '',
+          workspaceRelativeHandoffPath: parsed.handoffWorkspacePath || '',
+          routeId: parsed.routeId || '',
+          routeSelection: parsed.role === 'recovery-orientation' ? Object.freeze({ mode: parsed.routeSelection || '', selectedRouteId: parsed.selectedRouteId || '', candidateCount: Number(parsed.candidateRouteCount || 0) }) : undefined,
+          carrierLineage: parsed.role === 'recovery-orientation' ? Object.freeze({ dimension: parsed.carrierDimension || '', parentDimension: parsed.parentCarrierDimension || '', checkpointKind: parsed.carrierCheckpoint || '' }) : undefined
+        }));
+    } else if (schemaId === 'tiinex.external.payload.v1') {
+      const parsed = parsePhase1Payload(markdown);
+      if ([PHASE1_COMPLETE_WORKSPACE_ROLE, PHASE1_BOUNDED_WORKSPACE_ROLE].includes(parsed.payloadRole)) facts.set(path, recipientV2TransportFacts('workspace-representation-payload', { workspaceId: parsed.workspaceId, coverage: parsed.payloadRole === PHASE1_BOUNDED_WORKSPACE_ROLE ? 'bounded' : 'complete', archivePath: parsed.location || '', archiveBytes: Number(parsed.bytes || 0), archiveSha256: parsed.integrityValue || '' }));
+      else if (parsed.payloadRole === PHASE1_BOOTSTRAP_ROLE) facts.set(path, recipientV2TransportFacts('tooling-bootstrap', { archivePath: parsed.location || '', archiveBytes: Number(parsed.bytes || 0), archiveSha256: parsed.integrityValue || '', payloadRole: parsed.payloadRole }));
+      else if (parsed.payloadRole === PHASE1_CACHE_ROLE) {
+        const archive = archiveIdentity(parsed.location)?.archive || null;
+        const materials = parsed.materials.map((material) => {
+          const matches = archive?.state === 'qualified' ? archive.entries.filter((entry) => String(entry.path || '') === String(material.archiveEntry || '')) : [];
+          const entry = matches.length === 1 ? matches[0] : null;
+          const bytes = entry ? packageFileBytes({ data: entry.data }) : new Uint8Array();
+          return Object.freeze({ requirementId: material.requirementId, classification: material.classification, referenceTarget: material.referenceTarget, routeWorkspaceId: parsed.workspaceId, routePath: '', sourceRequirementId: material.requirementId, originalPath: '', archiveEntry: material.archiveEntry, bytes: bytes.byteLength, sha256: bytes.byteLength ? sha256Hex(bytes) : '' });
+        });
+        facts.set(path, recipientV2TransportFacts('workspace-dependency-cache', { workspaceId: parsed.workspaceId, archivePath: parsed.location || '', archiveBytes: Number(parsed.bytes || 0), archiveSha256: parsed.integrityValue || '', materials: Object.freeze(materials) }));
+      }
+    } else if (schemaId === 'tiinex.relation.v1') {
+      const parsed = parseRecipientV2Relation(markdown);
+      facts.set(path, recipientV2TransportFacts('workspace-representation', {
+        workspaceId: parsed.targetWorkspaceId || '', coverage: parsed.scope === 'bounded recipient-relative workspace materialization' ? 'bounded' : 'complete', workspaceArtifactInnerPath: parsed.targetWorkspaceInnerPath || '', payloadArtifactPath: parsed.source || '', relationType: parsed.relationType || '', relationDirection: parsed.direction || '', relationScope: parsed.scope || ''
+      }));
+    }
+  }
+  return facts;
+}
+
+export function parsePhase1Payload(markdown = '') {
+  const identity = sectionText(markdown, 'Payload Identity');
+  const location = sectionText(markdown, 'Payload Location');
+  const integrity = sectionText(markdown, 'Integrity Reference');
+  return Object.freeze({
+    workspaceId: fieldValue(identity, 'Workspace Id'),
+    payloadRole: fieldValue(identity, 'Payload Role'),
+    bytes: Number(fieldValue(identity, 'Byte Size') || 0),
+    location: markdownTarget(fieldValue(location, 'Location')),
+    integrityStatus: fieldValue(integrity, 'Integrity Status'),
+    integrityMethod: fieldValue(integrity, 'Integrity Method'),
+    integrityValue: fieldValue(integrity, 'Integrity Value'),
+    integrityTarget: fieldValue(integrity, 'Integrity Target'),
+    materials: parsePhase1MaterialBindings(markdown)
+  });
+}
+
+function parsePhase1MaterialBindings(markdown = '') {
+  const section = sectionText(markdown, 'Payload Material Bindings');
+  if (!section) return Object.freeze([]);
+  const out = [];
+  let current = null;
+  for (const line of section.split(/\r?\n/)) {
+    const requirement = line.match(/^\s*-\s+Requirement Id:\s*(.*?)\s*$/i);
+    if (requirement) {
+      if (current) out.push(Object.freeze(current));
+      current = { requirementId: String(requirement[1] || '').trim(), classification: '', referenceTarget: '', archiveEntry: '' };
+      continue;
+    }
+    if (!current) continue;
+    const classification = line.match(/^\s+-\s+Classification:\s*(.*?)\s*$/i);
+    const reference = line.match(/^\s+-\s+Material Reference:\s*(.*?)\s*$/i);
+    const archiveEntry = line.match(/^\s+-\s+Archive Entry:\s*(.*?)\s*$/i);
+    if (classification) current.classification = String(classification[1] || '').trim();
+    else if (reference) current.referenceTarget = String(reference[1] || '').trim();
+    else if (archiveEntry) current.archiveEntry = String(archiveEntry[1] || '').trim();
+  }
+  if (current) out.push(Object.freeze(current));
+  return Object.freeze(out);
+}
+
+export function selectPhase1SourceRoute(carrierProjection = {}, selector = '', findings = []) {
+  const candidates = [...(carrierProjection.routes || [])].filter((route) => String(route.state || '') === 'qualified');
+  const requested = String(selector || '').trim();
+  if (!requested) {
+    if (candidates.length === 1) return deepFreeze({ state: 'qualified', mode: 'implicit-single-qualified-route', selector: '', candidateCount: 1, route: candidates[0] });
+    findings.push(finding('error', candidates.length > 1 ? 'portable.handoff-v2-phase1.route-selection.required' : 'portable.handoff-v2-phase1.route-selection.unresolved', candidates.length > 1 ? 'Phase 1 artifact-first manufacture requires an explicit route selector when more than one qualified Handoff candidate exists.' : 'Phase 1 artifact-first manufacture requires exactly one qualified Handoff route candidate.', { candidateCount: candidates.length }));
+    return deepFreeze({ state: 'blocked', mode: candidates.length > 1 ? 'selection-required' : 'unresolved', selector: '', candidateCount: candidates.length, route: null });
+  }
+  const normalized = normalizeRoutePath(requested);
+  const matches = candidates.filter((route) => String(route.id || '') === requested || normalizeRoutePath(route.workspaceRelativePath || '') === normalized || `${String(route.workspaceId || '')}:${normalizeRoutePath(route.workspaceRelativePath || '')}` === requested);
+  if (matches.length !== 1) {
+    findings.push(finding('error', matches.length > 1 ? 'portable.handoff-v2-phase1.route-selection.ambiguous' : 'portable.handoff-v2-phase1.route-selection.unresolved', 'Explicit Phase 1 route selector must bind exactly one qualified Handoff route candidate.', { selector: requested, matches: matches.length, candidateCount: candidates.length }));
+    return deepFreeze({ state: 'blocked', mode: matches.length > 1 ? 'ambiguous' : 'unresolved', selector: requested, candidateCount: candidates.length, route: null });
+  }
+  return deepFreeze({ state: 'qualified', mode: 'explicit-qualified-route-selector', selector: requested, candidateCount: candidates.length, route: matches[0] });
+}
+
+export function qualifyPhase1BootstrapPayload(bootstrapPayload = null, semanticFiles = [], findings = []) {
+  if (!bootstrapPayload) return null;
+  const localFindings = [];
+  if (String(bootstrapPayload.parsed?.payloadRole || '') !== PHASE1_BOOTSTRAP_ROLE) localFindings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.role-mismatch', 'Portable Tooling bootstrap External Payload must declare the accepted bootstrap payload role.'));
+  const location = String(bootstrapPayload.parsed?.location || '');
+  const matches = semanticFiles.filter((file) => String(file.path || '') === location);
+  if (!location || matches.length !== 1) localFindings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.location-unresolved', 'Portable Tooling bootstrap External Payload Location must resolve exactly one carried payload file.', { path: location, count: matches.length }));
+  let bytes = new Uint8Array();
+  if (matches.length === 1) {
+    bytes = packageFileBytes(matches[0]);
+    const digest = sha256Hex(bytes);
+    if (Number(bootstrapPayload.parsed?.bytes || 0) !== bytes.byteLength || String(bootstrapPayload.parsed?.integrityStatus || '') !== 'verified' || String(bootstrapPayload.parsed?.integrityMethod || '') !== 'sha256' || String(bootstrapPayload.parsed?.integrityValue || '') !== digest) localFindings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.identity-mismatch', 'Portable Tooling bootstrap visible byte identity diverges from the exact carried payload bytes.', { path: location }));
+    const archive = inspectStoredWorkspaceArchive(bytes, { ownedBytes: true });
+    if (archive.state !== 'qualified') localFindings.push(finding('error', 'portable.handoff-v2-phase1.bootstrap.archive-invalid', 'Portable Tooling bootstrap payload is not a qualified deterministic stored-ZIP representation.', { path: location, findings: archive.findings || [] }));
+  }
+  findings.push(...localFindings);
+  return deepFreeze({ state: localFindings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified', artifactPath: String(bootstrapPayload.path || ''), payloadPath: location, payloadRole: String(bootstrapPayload.parsed?.payloadRole || ''), bytes: bytes.byteLength, sha256: bytes.byteLength ? sha256Hex(bytes) : '', findings: Object.freeze(localFindings), boundary: 'Visible External Payload ownership of exact portable Tooling bootstrap bytes. Ingress navigation and package placement create no Parent or package authority.' });
+}
+
+export function qualifyPhase1CachePayload(cachePayload = null, semanticFiles = [], findings = []) {
+  if (!cachePayload) return null;
+  const localFindings = [];
+  const location = String(cachePayload.parsed?.location || '');
+  const matches = semanticFiles.filter((file) => String(file.path || '') === location);
+  if (!location || matches.length !== 1) localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.location-unresolved', 'Selected-route cache External Payload Location must resolve exactly one carried payload file.', { path: location, count: matches.length }));
+  let bytes = new Uint8Array();
+  let archive = null;
+  const materialQualifications = [];
+  if (matches.length === 1) {
+    bytes = packageFileBytes(matches[0]);
+    const digest = sha256Hex(bytes);
+    if (Number(cachePayload.parsed?.bytes || 0) !== bytes.byteLength || String(cachePayload.parsed?.integrityStatus || '') !== 'verified' || String(cachePayload.parsed?.integrityMethod || '') !== 'sha256' || String(cachePayload.parsed?.integrityValue || '') !== digest) localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.identity-mismatch', 'Selected-route cache visible byte identity diverges from exact carried cache bytes.', { path: location }));
+    archive = inspectStoredWorkspaceArchive(bytes, { ownedBytes: true });
+    if (archive.state !== 'qualified') localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.archive-invalid', 'Selected-route cache payload is not a qualified deterministic stored-ZIP representation.', { path: location, findings: archive.findings || [] }));
+  }
+  const seenRequirements = new Set();
+  const seenReferences = new Set();
+  const seenEntries = new Set();
+  for (const material of cachePayload.parsed?.materials || []) {
+    const requirementId = String(material.requirementId || '');
+    const referenceTarget = String(material.referenceTarget || '');
+    const archiveEntry = String(material.archiveEntry || '');
+    if (!requirementId || !referenceTarget || !archiveEntry) {
+      localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.material-binding-incomplete', 'Every selected-route cache material binding must visibly declare requirement id, material reference, and archive entry.'));
+      continue;
+    }
+    if (seenRequirements.has(requirementId) || seenReferences.has(referenceTarget) || seenEntries.has(archiveEntry)) localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.material-binding-ambiguous', 'Selected-route cache material bindings must be one-to-one by requirement id, material reference, and archive entry.', { requirementId, referenceTarget, archiveEntry }));
+    seenRequirements.add(requirementId); seenReferences.add(referenceTarget); seenEntries.add(archiveEntry);
+    const entryMatches = archive?.state === 'qualified' ? archive.entries.filter((entry) => String(entry.path || '') === archiveEntry) : [];
+    if (archive?.state === 'qualified' && entryMatches.length !== 1) localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.material-entry-unresolved', 'Selected-route cache material binding must resolve exactly one exact cache entry.', { requirementId, referenceTarget, archiveEntry, count: entryMatches.length }));
+    const entry = entryMatches.length === 1 ? entryMatches[0] : null;
+    const entryBytes = entry ? packageFileBytes({ data: entry.data }) : new Uint8Array();
+    materialQualifications.push(deepFreeze({ requirementId, classification: String(material.classification || ''), referenceTarget, archiveEntry, bytes: entryBytes.byteLength, sha256: entryBytes.byteLength ? sha256Hex(entryBytes) : '' }));
+  }
+  if (!(cachePayload.parsed?.materials || []).length) localFindings.push(finding('error', 'portable.handoff-v2-phase1.cache.material-bindings-missing', 'Selected-route cache External Payload must visibly bind every owned detached material to one archive entry.'));
+  findings.push(...localFindings);
+  return deepFreeze({ state: localFindings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified', workspaceId: String(cachePayload.parsed?.workspaceId || ''), artifactPath: String(cachePayload.path || ''), payloadPath: location, payloadRole: String(cachePayload.parsed?.payloadRole || ''), bytes: bytes.byteLength, sha256: bytes.byteLength ? sha256Hex(bytes) : '', archive, materials: Object.freeze(materialQualifications), findings: Object.freeze(localFindings), boundary: 'Visible cache External Payload ownership plus exact cache ZIP bytes and visible material-to-entry bindings. Cache location and compatibility JSON do not create material authority.' });
+}

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

@@ -0,0 +1,69 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectRecipientV2ArtifactFirstPhase1Specimen } from './recipientV2.artifactFirst.inspect.js';
+import { RECIPIENT_V2_READ_PATH, RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID, PHASE2_CLEAN_PROFILE, decodeUtf8, deepFreeze } from './recipientV2.artifactFirst.shared.js';
+
+export function isRecipientV2ArtifactFirstPhase1Surface(files = []) {
+  return files.some((file) => {
+    if (String(file.path || '') !== RECIPIENT_V2_READ_PATH) return false;
+    const markdown = decodeUtf8(packageFileBytes(file));
+    return markdown.includes('Artifact-First Phase 1 Specimen') || markdown.includes(`Carrier Profile: ${PHASE2_CLEAN_PROFILE}`);
+  });
+}
+
+export function inspectRecipientFacingV2ArtifactFirstPhase1(bundle = {}) {
+  const inspection = inspectRecipientV2ArtifactFirstPhase1Specimen(bundle);
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const facts = inspection.semanticFactsByPath || new Map();
+  const ingressFile = files.find((file) => String(file.path || '') === RECIPIENT_V2_READ_PATH) || null;
+  const payloadEntries = [...facts.entries()].filter(([, item]) => item?.role === 'workspace-representation-payload');
+  const relationEntries = [...facts.entries()].filter(([, item]) => item?.role === 'workspace-representation');
+  const relationByWorkspace = new Map(relationEntries.map((entry) => [String(entry[1]?.workspaceId || ''), entry]));
+  const routeEntries = [...facts.entries()].filter(([, item]) => item?.role === 'handoff-route');
+  const bootstrapEntry = [...facts.entries()].find(([, item]) => item?.role === 'tooling-bootstrap') || null;
+  const cacheEntries = [...facts.entries()].filter(([, item]) => item?.role === 'workspace-dependency-cache');
+  return deepFreeze({
+    schema: 'tiinex.portable.recipient-facing-handoff-v2.inspection.v1',
+    detected: true,
+    status: inspection.status === 'ready' ? 'valid' : 'invalid',
+    format: inspection.format || RECIPIENT_V2_ARTIFACT_FIRST_PHASE1_FORMAT_ID,
+    rootArtifact: null,
+    readArtifact: ingressFile ? Object.freeze({ path: RECIPIENT_V2_READ_PATH, schemaId: 'tiinex.pointer.v1', sha256: sha256Hex(packageFileBytes(ingressFile)), facts: facts.get(RECIPIENT_V2_READ_PATH) || null }) : null,
+    workspaces: Object.freeze(payloadEntries.map(([payloadPath, item]) => {
+      const relationEntry = relationByWorkspace.get(String(item?.workspaceId || '')) || null;
+      return Object.freeze({
+        workspaceId: String(item?.workspaceId || ''),
+        workspaceArtifactPath: '',
+        workspaceRepresentationArtifactPath: String(relationEntry?.[0] || ''),
+        workspacePayloadArtifactPath: payloadPath,
+        workspaceArchivePath: String(item?.archivePath || ''),
+        sourceWorkspaceTargetInnerPath: String(relationEntry?.[1]?.workspaceArtifactInnerPath || ''),
+        sourceWorkspaceTargetSha256: ''
+      });
+    })),
+    routes: Object.freeze(routeEntries.map(([pointerPath, item]) => {
+      const routeId = String(item?.routeId || `handoff-route:${String(item?.workspaceId || '')}:${String(item?.workspaceRelativeHandoffPath || '')}`);
+      return Object.freeze({
+        pointerPath,
+        routeId,
+        workspaceId: String(item?.workspaceId || ''),
+        workspaceRelativeHandoffPath: String(item?.workspaceRelativeHandoffPath || ''),
+        endpointRolePointers: Object.freeze((inspection.endpointRoles || []).filter((role) => String(role.routeId || '') === routeId).map((role) => role.pointerPath)),
+        participantRolePointers: Object.freeze((inspection.participantRoles || []).filter((role) => String(role.routeId || '') === routeId).map((role) => role.pointerPath))
+      });
+    })),
+    endpointRoles: Object.freeze(inspection.endpointRoles || []),
+    participantRoles: Object.freeze(inspection.participantRoles || []),
+    caches: Object.freeze(inspection.caches || cacheEntries.map(([artifactPath, item]) => Object.freeze({ workspaceId: String(item?.workspaceId || ''), artifactPath, archivePath: String(item?.archivePath || ''), materials: Object.freeze(item?.materials || []) }))),
+    bootstrapInspection: bootstrapEntry ? Object.freeze({ status: inspection.bootstrapQualification?.state === 'qualified' ? 'valid' : 'invalid', path: bootstrapEntry[0], state: inspection.bootstrapQualification?.state || 'blocked', archivePath: String(bootstrapEntry[1]?.archivePath || ''), bytes: Number(bootstrapEntry[1]?.archiveBytes || 0), sha256: String(bootstrapEntry[1]?.archiveSha256 || ''), findings: Object.freeze([...(inspection.bootstrapQualification?.findings || [])]) }) : null,
+    transportManifest: inspection.transportManifest,
+    artifactFacts: Object.freeze([...facts.entries()].map(([path, item]) => Object.freeze({ path, facts: item }))),
+    descriptor: null,
+    workspaceByteProvider: null,
+    carrierProjection: inspection.carrierProjection,
+    coldConsumerProjection: inspection.coldConsumerProjection,
+    findings: inspection.findings,
+    findingSummary: Object.freeze({ errors: inspection.findings.filter((item) => item.severity === 'error').length, findings: inspection.findings.length }),
+    boundary: inspection.boundary,
+    phase1: inspection
+  });
+}