@tiinex/core 0.1.1

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

@@ -0,0 +1,218 @@
+import { packageFileByteView, packageFileBytes, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+import { validatedC14nV2PrimarySelfDigest } from '../../../integrity/integrity.c14nV2.js';
+import { inspectStoredWorkspaceArchive, HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID, HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID, HANDOFF_WORKSPACE_ARCHIVE_CODEC, HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND, HANDOFF_WORKSPACE_INNER_PATH_NORMALIZATION } from './workspaceByteProvider.js';
+import { boundedRecipientToken } from './recipientV2.inspect.pathToken.js';
+
+export function indexRecipientFiles(files = [], findings = []) {
+  const map = new Map();
+  for (const file of files) {
+    const path = String(file.path || '');
+    const list = map.get(path) || [];
+    list.push(file);
+    map.set(path, list);
+  }
+  for (const [path, list] of map) if (list.length !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.path-duplicate', 'Recipient-facing v2 root contains a duplicate path.', { path, count: list.length }));
+  return map;
+}
+
+export function oneRecipientFile(index, path = '') {
+  const list = index.get(String(path || '')) || [];
+  return list.length === 1 ? list[0] : null;
+}
+
+export function inspectRecipientZipPayload(file, facts = {}, findings = [], role = 'payload', verifiedIdentity = null) {
+  if (!file) return null;
+  const data = packageFileByteView(file);
+  const expectedPath = String(facts.archivePath || '');
+  if (expectedPath && expectedPath !== String(file.path || '')) findings.push(finding('error', `portable.handoff-v2-surface.${role}.path-mismatch`, 'Payload artifact local archive path does not resolve to the inspected payload.', { expectedPath, actualPath: file.path || '' }));
+  if (Number(facts.archiveBytes || 0) !== data.byteLength) findings.push(finding('error', `portable.handoff-v2-surface.${role}.bytes-mismatch`, 'Payload byte length differs from its qualified visible declaration.', { path: file.path || '' }));
+  const archiveSha256 = reusableVerifiedIdentity(verifiedIdentity, data) || sha256Hex(data);
+  if (String(facts.archiveSha256 || '') !== archiveSha256) findings.push(finding('error', `portable.handoff-v2-surface.${role}.sha256-mismatch`, 'Payload digest differs from its qualified visible declaration.', { path: file.path || '' }));
+  const archive = inspectStoredWorkspaceArchive(data, { ownedBytes: true });
+  if (archive.state !== 'qualified') for (const item of archive.findings || []) findings.push(finding('error', `portable.handoff-v2-surface.${role}.archive-invalid`, item.message || 'Stored ZIP payload is invalid.', { path: file.path || '', cause: item.code || '' }));
+  return Object.freeze({ data, sha256: archiveSha256, bytes: data.byteLength, archive });
+}
+
+
+
+function reusableVerifiedIdentity(identity, data) {
+  if (!identity || Number(identity.bytes) !== data.byteLength) return '';
+  const digest = String(identity.sha256 || '').toLowerCase();
+  return /^[a-f0-9]{64}$/.test(digest) ? digest : '';
+}
+
+export function buildQualifiedRecipientV2WorkspaceByteProvider(workspaceParts = []) {
+  const providerFindings = [];
+  const idCounts = new Map();
+  for (const part of workspaceParts) idCounts.set(String(part?.workspaceId || ''), (idCounts.get(String(part?.workspaceId || '')) || 0) + 1);
+  const workspaces = workspaceParts.map((part) => {
+    const descriptorPart = part?.descriptorPart || {};
+    const workspace = descriptorPart.workspace || {};
+    const binding = descriptorPart.binding || {};
+    const archive = part?.archive || {};
+    const representation = part?.representation || {};
+    const payload = part?.payload || {};
+    const parsedEntries = archive.archive?.entries || [];
+    const workspaceId = String(workspace.id || part?.workspaceId || '');
+    const reasons = [];
+    const reject = (code, detail = '') => reasons.push(Object.freeze({ code, detail }));
+    if (!workspaceId || idCounts.get(workspaceId) !== 1) reject('workspace-identity-ambiguous', `count=${idCounts.get(workspaceId) || 0}`);
+    if (part?.artifact?.schemaId !== 'tiinex.workspace.v1' || part?.artifact?.status !== 'qualified') reject('workspace-artifact-unqualified');
+    if (part?.representationArtifact?.schemaId !== 'tiinex.workspace.representation.v1' || part?.representationArtifact?.status !== 'qualified') reject('workspace-representation-unqualified');
+    if (part?.payloadArtifact?.schemaId !== 'tiinex.external.payload.v1' || part?.payloadArtifact?.status !== 'qualified') reject('workspace-representation-payload-unqualified');
+    if (representation.workspaceArtifactPath !== part?.artifact?.path) reject('workspace-representation-workspace-endpoint-mismatch');
+    if (representation.payloadArtifactPath !== part?.payloadArtifact?.path) reject('workspace-representation-payload-endpoint-mismatch');
+    const coverage = representation.coverage === 'bounded' ? 'bounded' : representation.coverage === 'complete' ? 'complete' : '';
+    const expectedRepresentationKind = coverage === 'bounded' ? 'exact-bounded-workspace-byte-tree-archive' : 'exact-workspace-byte-tree-archive';
+    const expectedActivationRule = coverage === 'bounded' ? 'verified-bounded-only' : 'verified-complete-only';
+    const expectedSelectionRule = coverage === 'bounded' ? 'explicit-binding-per-bounded-scope' : 'exactly-one-binding-per-workspace';
+    if (!coverage || representation.representationKind !== expectedRepresentationKind || representation.bindingState !== 'verified') reject(coverage === 'bounded' ? 'workspace-representation-not-verified-bounded' : 'workspace-representation-not-verified-complete');
+    if (coverage === 'bounded' && (representation.scopeBasis !== 'exact-representation-entry-set' || representation.includedEntryAuthority !== 'qualified-decoded-entry-set' || representation.omittedEntryMeaning !== 'outside-representation-not-absent-from-workspace' || representation.sourceMembershipClaim !== 'represented-entries-are-workspace-relative-source-bytes' || representation.recoveryClosureBoundary !== 'separate-qualified-closure')) reject('workspace-representation-bounded-scope-invalid');
+    if (representation.workspaceTreeRoot !== '.' || representation.archiveEntryRoot !== '.' || representation.pathMapping !== 'identity-relative-paths' || representation.collisionPolicy !== 'reject-ambiguous-or-unsafe-paths' || representation.decoderRequirement !== 'deterministic stored ZIP with safe-entry validation') reject('workspace-representation-correlation-invalid');
+    if (representation.activationRule !== expectedActivationRule || representation.payloadIntegrityRequirement !== 'verified-exact-payload-bytes' || representation.coverageRequirement !== coverage || representation.stalenessRule !== 'requalify-on-binding-relevant-change' || representation.selectionRule !== expectedSelectionRule || representation.multiWorkspaceIsolation !== 'independent-binding-closure') reject('workspace-representation-provider-contract-invalid');
+    if (representation.pathMapping === 'manifest' && !representation.mappingManifest) reject('workspace-representation-mapping-manifest-missing');
+    if (payload.mediaType !== 'application/zip' || payload.format !== 'deterministic stored ZIP' || payload.integrityStatus !== 'verified' || payload.integrityMethod !== 'sha256' || payload.integrityTarget !== 'exact payload bytes as carried at the declared local Location') reject('workspace-representation-payload-contract-invalid');
+    if (payload.location !== String(part?.archiveFile?.path || '')) reject('workspace-representation-payload-location-mismatch');
+    if (Number(payload.bytes || 0) !== Number(archive.bytes || 0) || String(payload.integrityValue || '') !== String(archive.sha256 || '')) reject('workspace-representation-payload-integrity-mismatch');
+    if (archive.archive?.state !== 'qualified') reject('workspace-representation-payload-decoder-unqualified');
+    if (String(representation.workspaceArtifactInnerPath || '') !== String(part?.sourceTargetEntry?.path || '')) reject('workspace-representation-inner-workspace-mismatch');
+    if (part?.targetQualification?.state !== 'qualified') reject('workspace-representation-inner-workspace-unqualified');
+    const exactEntriesFingerprint = recipientEntriesFingerprint(parsedEntries);
+    const facts = part?.facts || {};
+    const representationFacts = part?.representationArtifact?.facts || {};
+    const payloadFacts = part?.payloadArtifact?.facts || {};
+    if (String(facts.sourceWorkspaceTargetInnerPath || '') !== String(representation.workspaceArtifactInnerPath || '') || String(facts.sourceWorkspaceTargetSha256 || '') !== String(part?.targetFile?.sha256 || '') || Number(facts.sourceWorkspaceTargetBytes || 0) !== Number(part?.targetFile?.bytes || 0) || Number(facts.entryCount || 0) !== parsedEntries.length || String(facts.entriesFingerprint || '') !== exactEntriesFingerprint || String(facts.coverage || 'complete') !== coverage || String(facts.coverageState || facts.completenessState || '') !== 'qualified') reject('workspace-transport-witness-stale');
+    if (String(representationFacts.workspaceId || '') !== workspaceId || String(representationFacts.workspaceArtifactPath || '') !== String(part?.artifact?.path || '') || String(representationFacts.payloadArtifactPath || '') !== String(part?.payloadArtifact?.path || '') || String(representationFacts.sourceWorkspaceTargetInnerPath || '') !== String(representation.workspaceArtifactInnerPath || '') || String(representationFacts.archivePath || '') !== String(payload.location || '') || String(representationFacts.archiveSha256 || '') !== String(archive.sha256 || '') || Number(representationFacts.entryCount || 0) !== parsedEntries.length || String(representationFacts.entriesFingerprint || '') !== exactEntriesFingerprint || String(representationFacts.coverage || 'complete') !== coverage || String(representationFacts.coverageState || representationFacts.completenessState || '') !== 'qualified') reject('workspace-representation-transport-witness-stale');
+    if (String(payloadFacts.workspaceId || '') !== workspaceId || String(payloadFacts.archivePath || '') !== String(payload.location || '') || String(payloadFacts.archiveSha256 || '') !== String(archive.sha256 || '')) reject('workspace-representation-payload-transport-witness-stale');
+    const declaredByPath = new Map((binding.entryMap?.entries || []).map((entry) => [String(entry.path || ''), entry]));
+    const archivePath = String(binding.representation?.packagePath || part?.archiveFile?.path || '');
+    const entries = parsedEntries.map((entry) => {
+      const declared = declaredByPath.get(String(entry.path || '')) || {};
+      return deepFreeze({ path: String(entry.path || ''), innerPath: String(entry.path || ''), archivePackagePath: archivePath, packagePath: archivePath, bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || ''), referenceTarget: String(declared.referenceTarget || ''), data: entry.data });
+    });
+    const state = reasons.length ? 'blocked' : 'qualified';
+    for (const reason of reasons) providerFindings.push(finding('error', `portable.handoff-v2-surface.workspace-provider.${reason.code}`, 'Canonical Workspace Representation provider activation failed closed.', { workspaceId, detail: reason.detail || '' }));
+    return deepFreeze({
+      state,
+      id: workspaceId,
+      title: String(workspace.title || workspace.id || part?.workspaceId || ''),
+      mode: 'archive',
+      materialization: workspace,
+      entries: Object.freeze(entries),
+      workspaceTarget: deepFreeze({ ...(binding.workspaceTarget || {}), data: packageFileByteView(part?.targetFile || {}) }),
+      archive: deepFreeze({ ...(binding.representation || {}), data: archive.data || new Uint8Array() }),
+      binding,
+      reasons: Object.freeze(reasons),
+      authority: Object.freeze({ locatorAuthority: false, filenameAuthority: false, packagePlacementAuthority: false, bindingAuthority: 'schema-valid-tiinex.workspace.representation.v1-visible-binding-plus-schema-valid-external-payload-plus-exact-qualified-archive-bytes', hiddenTransportBindingAuthority: false })
+    });
+  });
+  return deepFreeze({
+    schema: HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID,
+    status: workspaces.length > 0 && workspaces.every((workspace) => workspace.state === 'qualified') ? 'ready' : 'blocked',
+    workspaces: Object.freeze(workspaces),
+    findings: Object.freeze(providerFindings),
+    boundary: 'Recipient-v2 archive provider activation is authorized only by one schema-valid verified complete-or-bounded tiinex.workspace.representation.v1 artifact, its explicitly referenced schema-valid External Payload, and exact qualified payload bytes. Bounded scope never implies whole-Workspace completeness; hidden transport binding metadata has no semantic provider authority.'
+  });
+}
+
+export function recipientEntryIdentities(entries = []) {
+  return entries.map((entry) => ({ path: String(entry.path || ''), bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || '') })).sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function recipientEntriesFingerprint(entries = []) {
+  return sha256Hex(utf8Bytes(stableJson(recipientEntryIdentities(entries))));
+}
+
+export function recipientWorkspaceDescriptor(input = {}) {
+  const facts = input.facts || {};
+  const representation = input.representation || {};
+  const payload = input.payload || {};
+  const entries = recipientEntryIdentities(input.entries || []).map((entry) => Object.freeze({ ...entry, referenceTarget: '' }));
+  const workspaceId = String(input.workspaceId || facts.workspaceId || '');
+  const targetPath = String(input.targetPackagePath || '');
+  const targetInnerPath = String(representation.workspaceArtifactInnerPath || '');
+  const archivePath = String(payload.location || input.archiveFile?.path || '');
+  const targetFile = input.targetFile || {};
+  const selfIntegrity = validatedC14nV2PrimarySelfDigest(input.targetMarkdown || '');
+  const archiveFile = input.archiveFile || {};
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+  const coverage = representation.coverage === 'bounded' ? 'bounded' : 'complete';
+  const coverageEvidence = Object.freeze({ state: 'qualified', basis: coverage === 'bounded' ? 'canonical-verified-bounded-workspace-representation-plus-exact-external-payload-and-qualified-bounded-entry-set' : 'canonical-verified-complete-workspace-representation-plus-exact-external-payload-and-qualified-complete-entry-set', entryCount: entries.length, totalBytes, ...(coverage === 'bounded' ? { scopeBasis: representation.scopeBasis, includedEntryAuthority: representation.includedEntryAuthority, omittedEntryMeaning: representation.omittedEntryMeaning, sourceMembershipClaim: representation.sourceMembershipClaim, recoveryClosureBoundary: representation.recoveryClosureBoundary } : {}) });
+  const transportCorrelationKey = recipientLocalWorkspaceCorrelationKey({ workspaceId, representation, payload, targetFile, entries });
+  const workspace = Object.freeze({
+    id: workspaceId,
+    title: workspaceId,
+    materialization: coverage,
+    qualification: 'qualified',
+    correlationStatus: 'qualified',
+    transportCorrelationKey,
+    completenessEvidence: coverage === 'complete' ? coverageEvidence : Object.freeze({}),
+    scopeEvidence: coverage === 'bounded' ? coverageEvidence : Object.freeze({}),
+    includedEntries: Object.freeze(entries)
+  });
+  const binding = Object.freeze({
+    schema: HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID,
+    version: 1,
+    workspaceId,
+    transportCorrelationKey,
+    workspaceTarget: Object.freeze({ packagePath: targetPath, innerPath: targetInnerPath, bytes: Number(targetFile.bytes || 0), sha256: String(targetFile.sha256 || ''), schema: 'tiinex.workspace.v1', selfIntegrity: Object.freeze({ state: String(selfIntegrity.state || ''), value: String(selfIntegrity.value || '') }), locatorAuthority: false }),
+    coverage,
+    representation: Object.freeze({ kind: coverage === 'bounded' ? 'bounded-workspace-snapshot' : 'complete-workspace-snapshot', packagePath: archivePath, mediaType: 'application/zip', codec: HANDOFF_WORKSPACE_ARCHIVE_CODEC, bytes: Number(archiveFile.bytes || 0), digest: Object.freeze({ method: 'sha256', value: String(archiveFile.sha256 || ''), target: 'archive-bytes-as-carried' }), deterministic: true, locatorAuthority: false }),
+    entryMap: Object.freeze({ normalization: HANDOFF_WORKSPACE_INNER_PATH_NORMALIZATION, count: entries.length, entries: Object.freeze(entries) }),
+    completeness: coverage === 'complete' ? Object.freeze({ ...coverageEvidence, entriesFingerprint: '' }) : Object.freeze({}),
+    scope: coverage === 'bounded' ? Object.freeze({ ...coverageEvidence, entriesFingerprint: '' }) : Object.freeze({}),
+    selection: Object.freeze({ rule: coverage === 'bounded' ? 'explicit-binding-per-bounded-scope' : 'exactly-one-binding-per-workspace', representationArtifactAuthority: 'explicit-recipient-workspace-representation-link' }),
+    provider: Object.freeze({ kind: String(facts.providerKind || HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND), state: 'ready', addressing: 'qualified-workspace-id-plus-normalized-inner-path', fallback: 'none', materialization: coverage }),
+    authority: Object.freeze({ workspaceIdentity: 'explicit-canonical-workspace-representation-workspace-endpoint-plus-exact-workspace-target-byte-identity', archiveIdentity: 'explicit-external-payload-endpoint-plus-exact-archive-byte-digest', canonicalRepresentationSchema: 'tiinex.workspace.representation.v1', hiddenTransportBindingAuthority: false, pathAuthority: false, adjacencyAuthority: false, orderingAuthority: false })
+  });
+  return Object.freeze({ workspace, binding });
+}
+
+
+function recipientLocalWorkspaceCorrelationKey(input = {}) {
+  const identity = {
+    format: 'recipient-v2-canonical-workspace-representation-binding',
+    workspaceId: String(input.workspaceId || ''),
+    workspaceArtifactPath: String(input.representation?.workspaceArtifactPath || ''),
+    payloadArtifactPath: String(input.representation?.payloadArtifactPath || ''),
+    sourceWorkspaceTargetInnerPath: String(input.representation?.workspaceArtifactInnerPath || ''),
+    sourceWorkspaceTargetSha256: String(input.targetFile?.sha256 || ''),
+    sourceWorkspaceTargetBytes: Number(input.targetFile?.bytes || 0),
+    archivePath: String(input.payload?.location || ''),
+    archiveSha256: String(input.payload?.integrityValue || ''),
+    entriesFingerprint: recipientEntriesFingerprint(input.entries || []),
+    coverage: String(input.representation?.coverage || 'complete')
+  };
+  return `recipient-v2:${sha256Hex(utf8Bytes(stableJson(identity)))}`;
+}
+
+export function virtualCacheMaterial(cache = {}, findings = []) {
+  const archive = cache.archive?.archive;
+  const byPath = new Map((archive?.entries || []).map((entry) => [String(entry.path || ''), entry]));
+  const files = [];
+  const materialized = [];
+  for (const item of cache.facts?.materials || []) {
+    const entry = byPath.get(String(item.archiveEntry || ''));
+    if (!entry) {
+      findings.push(finding('error', 'portable.handoff-v2-surface.cache.entry-missing', 'Context cache declaration does not resolve to exactly one archive entry.', { requirementId: item.requirementId || '', archiveEntry: item.archiveEntry || '' }));
+      continue;
+    }
+    if (Number(item.bytes || 0) !== Number(entry.bytes || 0) || String(item.sha256 || '') !== String(entry.sha256 || '')) findings.push(finding('error', 'portable.handoff-v2-surface.cache.entry-identity-mismatch', 'Context cache entry bytes differ from its visible declaration.', { requirementId: item.requirementId || '', archiveEntry: item.archiveEntry || '' }));
+    const packagePath = `recipient.v2.cache/${boundedRecipientToken(cache.facts?.workspaceId || 'workspace')}/${boundedRecipientToken(item.requirementId || item.archiveEntry)}.bin`;
+    files.push(Object.freeze({ path: packagePath, data: entry.data, size: entry.bytes, kind: 'recipient-v2-virtual-cache-material' }));
+    materialized.push(Object.freeze({ requirementId: String(item.requirementId || ''), classification: String(item.classification || ''), referenceTarget: String(item.referenceTarget || ''), originalPath: String(item.originalPath || ''), packagePath, carrierKind: 'detached-material', bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || ''), authority: Object.freeze({ carrierDedupBasis: 'visible-cache-artifact-plus-exact-archive-entry-byte-identity' }) }));
+  }
+  return Object.freeze({ files: Object.freeze(files), materialized: Object.freeze(materialized) });
+}
+
+
+export function isForbiddenLegacyV2Path(path = '') {
+  const value = String(path || '');
+  return value.startsWith('context/') || value.startsWith('handoff.workspaces/') || value.startsWith('tiinex.bootstrap/') || value.startsWith('tiinex.package/') || /^handoff-entrypoint-.*\.trace\.md$/i.test(value);
+}
+
+export function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+export function stableJson(value) { return JSON.stringify(sortJson(value)); }
+export function dedupeFindings(items = []) { const map = new Map(); for (const item of items) { const key = `${item.severity || ''}:${item.code || ''}:${item.path || item.workspaceId || item.requirementId || ''}:${item.message || ''}`; if (!map.has(key)) map.set(key, item); } return [...map.values()]; }
+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); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }

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

@@ -0,0 +1,194 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { exportFileMapZipUint8Array } from '../../../export/package.zip.js';
+import { inspectStoredWorkspaceArchive } from './workspaceByteProvider.js';
+import { buildHandoffCarrierProjection } from './carrierProjection.js';
+import { handoffWorkspaceProviderForId } from './workspaceByteProvider.js';
+import { inspectRecipientV2Artifact } from './recipientV2.artifacts.js';
+import { RECIPIENT_V2_FORMAT_ID, RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+import { recipientColdProjection } from './recipientV2.coldProjection.js';
+import { RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, RECIPIENT_V2_SIBLING_ROUTE_INFERENCE } from './recipientV2.entryContract.js';
+import { buildQualifiedRecipientV2WorkspaceByteProvider, dedupeFindings, deepFreeze, finding, indexRecipientFiles, isForbiddenLegacyV2Path } from './recipientV2.inspect.helpers.js';
+import { buildPackageLocalParentResolver, inspectRoutePointers, parentTrace } from './recipientV2.lineage.js';
+import { inspectRecipientV2TransportManifest, recipientV2FactsForFile, RECIPIENT_V2_TRANSPORT_MANIFEST_PATH } from './recipientV2.transportManifest.js';
+import { inspectRecipientFacingV2ArtifactFirstPhase1, isRecipientV2ArtifactFirstPhase1Surface } from './recipientV2.artifactFirstPhase1.js';
+import { inspectRecipientFacingV2PackageV1, isRecipientV2PackageV1Surface } from './recipientV2.packageV1.js';
+import { projectRecipientV2EndpointRoles, projectRecipientV2ParticipantRoles, projectRecipientV2Routes } from './recipientV2.inspect.projection.js';
+import { inspectRecipientV2WorkspaceSurface } from './recipientV2.inspect.workspaces.js';
+
+export const RECIPIENT_V2_TOPOLOGY_INSPECTION_SCHEMA_ID = 'tiinex.portable.recipient-facing-handoff-v2.inspection.v1';
+
+export function roundTripRecipientFacingV2Topology(bundle = {}, sourceInspection = null) {
+  sourceInspection = sourceInspection || inspectRecipientFacingV2Topology(bundle);
+  if (sourceInspection.status !== 'valid') return deepFreeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.roundtrip.v1', status: 'failed', comparison: 'not-run', inspection: sourceInspection, findings: sourceInspection.findings });
+  let zipBytes;
+  try { zipBytes = exportFileMapZipUint8Array((bundle.files || []).map((file) => ({ path: String(file.path || ''), data: packageFileBytes(file) })), 'portable.handoff-v2-surface.roundtrip.path.invalid'); }
+  catch (error) { return deepFreeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.roundtrip.v1', status: 'failed', comparison: 'not-run', inspection: sourceInspection, findings: Object.freeze([finding('error', 'portable.handoff-v2-surface.roundtrip.serialize-failed', 'Recipient-facing v2 serialization failed.', { detail: String(error?.message || error || '') })]) }); }
+  const parsed = inspectStoredWorkspaceArchive(zipBytes, { ownedBytes: true });
+  if (parsed.state !== 'qualified') return deepFreeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.roundtrip.v1', status: 'failed', comparison: 'mismatch', inspection: sourceInspection, findings: Object.freeze((parsed.findings || []).map((item) => finding('error', 'portable.handoff-v2-surface.roundtrip.zip-invalid', item.message || 'Serialized recipient-facing v2 ZIP is invalid.', { cause: item.code || '' }))) });
+  const files = (parsed.entries || []).map((entry) => Object.freeze({ path: entry.path, data: entry.data, bytes: entry.bytes, sha256: entry.sha256 }));
+  const verifiedPhysicalIdentityByPath = new Map((parsed.entries || []).map((entry) => [String(entry.path || ''), Object.freeze({ data: entry.data, bytes: entry.bytes, sha256: entry.sha256 })]));
+  const reinspection = inspectRecipientFacingV2Topology({ ...bundle, files: Object.freeze(files) }, { verifiedPhysicalIdentityByPath });
+  const sourceManifestSha256 = String(sourceInspection.transportManifest?.sha256 || '');
+  const receivedManifestSha256 = String(reinspection.transportManifest?.sha256 || '');
+  const manifestComparisonAvailable = sourceInspection.transportManifest?.state === 'valid' && reinspection.transportManifest?.state === 'valid' && sourceManifestSha256 && receivedManifestSha256;
+  const comparison = manifestComparisonAvailable
+    ? (sourceManifestSha256 === receivedManifestSha256 ? 'match' : 'mismatch')
+    : compareRecipientFileBytes(bundle.files || [], files);
+  const status = comparison === 'match' && reinspection.status === 'valid' ? 'passed' : 'failed';
+  return deepFreeze({ schema: 'tiinex.portable.recipient-facing-handoff-v2.roundtrip.v1', status, comparison, bytes: zipBytes.byteLength, inspection: reinspection, findings: reinspection.findings });
+}
+
+export function inspectRecipientFacingV2Topology(bundle = {}, options = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  if (isRecipientV2PackageV1Surface(files)) return inspectRecipientFacingV2PackageV1(bundle, options);
+  if (isRecipientV2ArtifactFirstPhase1Surface(files)) return inspectRecipientFacingV2ArtifactFirstPhase1(bundle, options);
+  const findings = [];
+  const index = indexRecipientFiles(files, findings);
+  const forbidden = files.filter((file) => isForbiddenLegacyV2Path(file.path));
+  for (const file of forbidden) findings.push(finding('error', 'portable.handoff-v2-surface.legacy-envelope-exposed', 'Recipient-facing v2 package exposes a rejected legacy control/envelope path.', { path: file.path || '' }));
+  for (const file of files) if (String(file.path || '').includes('/')) findings.push(finding('error', 'portable.handoff-v2-surface.path-nonflat', 'Recipient-facing v2 package root must be flat.', { path: file.path || '' }));
+
+  const transportManifest = inspectRecipientV2TransportManifest(files, { verifiedPhysicalIdentityByPath: options.verifiedPhysicalIdentityByPath });
+  if (transportManifest.state === 'invalid') findings.push(...transportManifest.findings);
+  if (transportManifest.state === 'valid' && String(transportManifest.manifest?.format || '') !== RECIPIENT_V2_FORMAT_ID) findings.push(finding('error', 'portable.handoff-v2-transport.manifest.format-mismatch', 'Recipient-v2 transport manifest declares an unsupported carrier format.', { observed: String(transportManifest.manifest?.format || ''), expected: RECIPIENT_V2_FORMAT_ID }));
+  const generatedFiles = [];
+  const generatedFacts = new Map();
+  const untypedMarkdown = [];
+  for (const file of files) {
+    if (!/\.md$/i.test(String(file.path || ''))) continue;
+    const facts = recipientV2FactsForFile(file, transportManifest.state === 'absent' ? null : transportManifest);
+    if (facts) { generatedFiles.push(file); generatedFacts.set(String(file.path || ''), facts); }
+    else untypedMarkdown.push(file);
+  }
+  const resolveParent = buildPackageLocalParentResolver(index);
+  const generatedArtifacts = generatedFiles.map((file) => inspectRecipientV2Artifact(file, { facts: generatedFacts.get(String(file.path || '')) || null, resolveParent }));
+  for (const artifact of generatedArtifacts) findings.push(...artifact.findings);
+  for (const file of untypedMarkdown) findings.push(finding('error', 'portable.handoff-v2-surface.markdown-unqualified', 'Recipient-facing v2 root contains Markdown that is not one generated qualified package-local Tiinex artifact.', { path: file.path || '' }));
+
+  const packageRoots = generatedArtifacts.filter((item) => item.schemaId === 'tiinex.pointer.v1' && item.facts?.role === 'package-root');
+  const rootArtifact = packageRoots.length === 1 ? packageRoots[0] : null;
+  if (packageRoots.length !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.package-root.unresolvable', 'Recipient-facing v2 package must expose exactly one package-local Tiinex root artifact.', { count: packageRoots.length }));
+  else {
+    if (rootArtifact.conformance?.parentContinuity?.parentDeclared) findings.push(finding('error', 'portable.handoff-v2-surface.package-root.parent-invalid', 'Package-local root artifact must not declare a Parent.', { path: rootArtifact.path }));
+    if (String(rootArtifact.facts?.entryArtifactPath || '') !== RECIPIENT_V2_READ_PATH) findings.push(finding('error', 'portable.handoff-v2-surface.package-root.entry-mismatch', 'Package-local root must explicitly declare the fixed recipient entry artifact.', { path: rootArtifact.path, expectedEntry: RECIPIENT_V2_READ_PATH, observedEntry: String(rootArtifact.facts?.entryArtifactPath || '') }));
+  }
+
+  const readArtifact = generatedArtifacts.find((item) => item.path === RECIPIENT_V2_READ_PATH) || null;
+  if (!readArtifact) findings.push(finding('error', 'portable.handoff-v2-surface.read-missing', 'Recipient-facing v2 package is missing its qualified READ-BEFORE Pointer.'));
+  else {
+    if (readArtifact.schemaId !== 'tiinex.pointer.v1' || readArtifact.facts?.role !== 'recovery-orientation' || readArtifact.facts?.format !== RECIPIENT_V2_FORMAT_ID) findings.push(finding('error', 'portable.handoff-v2-surface.read-role-invalid', 'READ-BEFORE artifact does not identify the supported flat recipient-facing v2 surface.', { path: readArtifact.path || '' }));
+    if (String(readArtifact.facts?.entryArtifactPath || '') !== RECIPIENT_V2_READ_PATH) findings.push(finding('error', 'portable.handoff-v2-surface.read.entry-mismatch', 'READ-BEFORE artifact must explicitly identify itself as the fixed recipient entry artifact.', { path: readArtifact.path || '', expectedEntry: RECIPIENT_V2_READ_PATH, observedEntry: String(readArtifact.facts?.entryArtifactPath || '') }));
+    if (String(readArtifact.facts?.routeSelectionAuthority || '') !== RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY) findings.push(finding('error', 'portable.handoff-v2-surface.read.route-selection-authority-missing', 'READ-BEFORE artifact must declare that recipient routing is selected by one exact package-local Handoff Route Pointer supplied by the outer invocation.', { path: readArtifact.path || '' }));
+    if (readArtifact.facts?.siblingRouteInference !== RECIPIENT_V2_SIBLING_ROUTE_INFERENCE) findings.push(finding('error', 'portable.handoff-v2-surface.read.sibling-route-inference-enabled', 'READ-BEFORE artifact must fail closed rather than infer among sibling Handoff routes.', { path: readArtifact.path || '' }));
+    if (rootArtifact && parentTrace(readArtifact) !== rootArtifact.path) findings.push(finding('error', 'portable.handoff-v2-surface.read.parent-mismatch', 'READ-BEFORE artifact must be a direct child of the package-local root.', { path: readArtifact.path, expectedParent: rootArtifact.path, observedParent: parentTrace(readArtifact) }));
+  }
+  const detected = Boolean(rootArtifact || readArtifact?.facts?.format === RECIPIENT_V2_FORMAT_ID || transportManifest.state !== 'absent' || forbidden.length);
+
+  const workspaceSurface = inspectRecipientV2WorkspaceSurface({ generatedArtifacts, rootArtifact, index, findings, transportManifest });
+  const {
+    routePointers,
+    endpointRolePointers,
+    participantRolePointers,
+    bootstrap,
+    workspaceParts,
+    workspaceDescriptors,
+    virtualWorkspaceTargetFiles,
+    archiveClaims,
+    caches,
+    virtualCache
+  } = workspaceSurface;
+
+  for (const file of files) {
+    const path = String(file.path || '');
+    if (/\.zip$/i.test(path) && (archiveClaims.get(path) || []).length !== 1) findings.push(finding('error', 'portable.handoff-v2-surface.payload-unowned', 'Every visible ZIP companion must be owned by exactly one qualified package-local Markdown lineage node.', { path, claims: (archiveClaims.get(path) || []).length }));
+    if (!/\.(?:md|zip)$/i.test(path) && path !== RECIPIENT_V2_TRANSPORT_MANIFEST_PATH) findings.push(finding('error', 'portable.handoff-v2-surface.root-file-kind-invalid', 'Recipient-facing v2 root may expose only qualified Tiinex Markdown artifacts, explicitly referenced ZIP companions, and the single transport-owned manifest.', { path }));
+  }
+
+  const routeWorkspaceMaterialized = routePointers.flatMap((pointer) => {
+    const facts = pointer.facts || {};
+    return (Array.isArray(facts.requiredContextBindings) ? facts.requiredContextBindings : []).map((binding) => Object.freeze({
+      requirementId: String(binding.requirementId || ''),
+      classification: 'required',
+      referenceTarget: String(binding.referenceTarget || ''),
+      routeWorkspaceId: String(facts.workspaceId || ''),
+      routePath: String(facts.workspaceRelativeHandoffPath || ''),
+      carrierKind: 'workspace-archive-entry',
+      workspaceId: String(binding.workspaceId || ''),
+      workspaceRelativePath: String(binding.workspaceRelativePath || ''),
+      bytes: Number(binding.bytes || 0),
+      sha256: String(binding.sha256 || '')
+    }));
+  });
+  const descriptor = deepFreeze({
+    schema: 'tiinex.transport.handoff-material-closure-descriptor.v2', version: 2,
+    workspaceMaterializations: Object.freeze(workspaceDescriptors.map((item) => item.workspace)),
+    workspaceArchiveBindings: Object.freeze(workspaceDescriptors.map((item) => item.binding)),
+    materialized: Object.freeze([...virtualCache.materialized, ...routeWorkspaceMaterialized]),
+    requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]), endpointRoles: Object.freeze([]), participantRoles: Object.freeze([]), dependencies: Object.freeze([]) })
+  });
+  const semanticBundle = { ...bundle, files: Object.freeze([...files, ...virtualWorkspaceTargetFiles, ...virtualCache.files]) };
+  const workspaceByteProvider = buildQualifiedRecipientV2WorkspaceByteProvider(workspaceParts);
+  findings.push(...workspaceByteProvider.findings);
+  for (const workspace of workspaceParts) {
+    const providerWorkspace = handoffWorkspaceProviderForId(workspaceByteProvider, workspace.workspaceId);
+    if (providerWorkspace.state !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-surface.workspace-provider.unqualified', 'Visible package-local Workspace node plus exact archive/source Workspace bytes did not requalify as one complete Workspace provider.', { workspaceId: workspace.workspaceId, reasons: providerWorkspace.reasons || [] }));
+  }
+
+  const routeSpecs = routePointers.map((pointer) => ({ workspaceId: String(pointer.facts?.workspaceId || ''), path: String(pointer.facts?.workspaceRelativeHandoffPath || ''), purpose: '' }));
+  const carrierLineage = rootArtifact?.facts?.carrierLineage || legacyCarrierLineageFromRoutePointers(routePointers);
+  const carrierProjection = buildHandoffCarrierProjection({ bundle: semanticBundle, descriptor, workspaceByteProvider, carrierLineage, routes: routeSpecs });
+  if (carrierProjection.status !== 'ready') findings.push(finding('error', 'portable.handoff-v2-surface.routes.unqualified', 'Recipient-facing route Pointers do not independently resolve to qualified carried Handoff bytes.', { causes: carrierProjection.findings || [] }));
+  inspectRoutePointers(routePointers, carrierProjection, workspaceParts, endpointRolePointers, participantRolePointers, index, findings);
+  for (const route of carrierProjection.routes || []) if (route.requiredClosure?.state !== 'qualified') findings.push(finding('error', 'portable.handoff-v2-surface.required-closure.unqualified', 'Selected Handoff Required Context does not resolve entirely to exact Workspace/archive or qualified cache bytes.', { routeId: route.id || '', requirements: route.requiredClosure?.requirements || [] }));
+  if (!routePointers.length) findings.push(finding('error', 'portable.handoff-v2-surface.routes.missing', 'Recipient-facing v2 package requires at least one qualified Handoff route Pointer.'));
+  if (!workspaceParts.length) findings.push(finding('error', 'portable.handoff-v2-surface.workspaces.missing', 'Recipient-facing v2 package requires at least one qualified package-local Workspace node/archive pair.'));
+
+  const coldConsumerProjection = recipientColdProjection(carrierProjection, RECIPIENT_V2_READ_PATH);
+  const finalFindings = dedupeFindings(findings);
+  const status = finalFindings.some((item) => item.severity === 'error') ? 'invalid' : 'valid';
+  return deepFreeze({
+    schema: RECIPIENT_V2_TOPOLOGY_INSPECTION_SCHEMA_ID,
+    detected,
+    status,
+    format: detected ? RECIPIENT_V2_FORMAT_ID : '',
+    rootArtifact: rootArtifact ? Object.freeze({ path: rootArtifact.path, schemaId: rootArtifact.schemaId, sha256: rootArtifact.sha256, carrierLineage: carrierProjection.lineage || null }) : null,
+    readArtifact,
+    workspaces: Object.freeze(workspaceParts.map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: item.representation.coverage === 'bounded' ? 'bounded' : 'complete', workspaceArtifactPath: item.artifact.path, workspaceRepresentationArtifactPath: item.representationArtifact.path, workspacePayloadArtifactPath: item.payloadArtifact.path, workspaceArchivePath: item.archiveFile.path, sourceWorkspaceTargetInnerPath: item.representation.workspaceArtifactInnerPath, sourceWorkspaceTargetSha256: item.targetFile.sha256 }))),
+    routes: projectRecipientV2Routes(routePointers, endpointRolePointers, participantRolePointers),
+    endpointRoles: projectRecipientV2EndpointRoles(endpointRolePointers),
+    participantRoles: projectRecipientV2ParticipantRoles(participantRolePointers),
+    caches: Object.freeze(caches.map((cache) => Object.freeze({ workspaceId: String(cache.facts?.workspaceId || ''), artifactPath: cache.artifact.path, archivePath: cache.file.path, materials: cache.facts.materials || [] }))),
+    bootstrapInspection: bootstrap?.inspection || null,
+    transportManifest: transportManifest.state === 'absent' ? null : Object.freeze({ state: transportManifest.state, path: RECIPIENT_V2_TRANSPORT_MANIFEST_PATH, sha256: transportManifest.file ? sha256Hex(packageFileBytes(transportManifest.file)) : '', format: String(transportManifest.manifest?.format || '') }),
+    artifactFacts: Object.freeze(generatedArtifacts.map((item) => Object.freeze({ path: item.path, facts: item.facts }))),
+    descriptor,
+    workspaceByteProvider,
+    carrierProjection,
+    coldConsumerProjection,
+    findings: Object.freeze(finalFindings),
+    findingSummary: Object.freeze({ errors: finalFindings.filter((item) => item.severity === 'error').length, findings: finalFindings.length }),
+    boundary: 'Read-only qualification of the flat recipient-facing v2 carrier. The package-local numeric tree must mirror explicit Parent continuity; exact durable Workspace and Handoff source bytes remain independently qualified inside their owned archive representations.'
+  });
+}
+
+
+
+function compareRecipientFileBytes(sourceFiles = [], receivedFiles = []) {
+  const identityMap = (files) => new Map(files.map((file) => {
+    const data = packageFileBytes(file);
+    return [String(file.path || ''), `${data.byteLength}:${sha256Hex(data)}`];
+  }));
+  const source = identityMap(sourceFiles);
+  const received = identityMap(receivedFiles);
+  return source.size === received.size && [...source].every(([path, identity]) => received.get(path) === identity) ? 'match' : 'mismatch';
+}
+
+function legacyCarrierLineageFromRoutePointers(routePointers = []) {
+  const dimensions = [...new Set(routePointers.map((pointer) => {
+    const name = String(pointer.facts?.workspaceRelativeHandoffPath || '').replace(/\\/g, '/').split('/').pop() || '';
+    return String(name.match(/^(\d{3}(?:-\d+)*)-/)?.[1] || '');
+  }).filter(Boolean))];
+  if (dimensions.length !== 1) return null;
+  const dimension = dimensions[0];
+  return Object.freeze({ mode: dimension.includes('-') ? 'continue' : 'root', dimension, checkpointKind: dimension.includes('-') ? 'progression' : 'major' });
+}

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

@@ -0,0 +1,9 @@
+import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export function boundedRecipientToken(value = '') {
+  const raw = String(value || '');
+  const token = raw.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!token) return 'material';
+  if (token.length <= 100) return token;
+  return `${token.slice(0, 87)}-${sha256Hex(utf8Bytes(raw)).slice(0, 12)}`;
+}

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

@@ -0,0 +1,58 @@
+import { parentTrace } from './recipientV2.lineage.js';
+
+export function projectRecipientV2Routes(routePointers = [], endpointPointers = [], participantPointers = []) {
+  return Object.freeze(routePointers.map((item) => Object.freeze({
+    pointerPath: item.path,
+    workspaceId: String(item.facts?.workspaceId || ''),
+    workspaceRelativeHandoffPath: String(item.facts?.workspaceRelativeHandoffPath || ''),
+    endpointRolePointers: Object.freeze(rolePointerAncestors(item, endpointPointers, participantPointers).filter((path) => endpointPointers.some((pointer) => pointer.path === path))),
+    participantRolePointers: Object.freeze(rolePointerAncestors(item, endpointPointers, participantPointers).filter((path) => participantPointers.some((pointer) => pointer.path === path)))
+  })));
+}
+
+export function projectRecipientV2EndpointRoles(pointers = []) {
+  return Object.freeze(pointers.map((item) => Object.freeze({
+    pointerPath: item.path,
+    workspaceId: String(item.facts?.workspaceId || ''),
+    routeId: String(item.facts?.routeId || ''),
+    requirementId: String(item.facts?.endpointRequirementId || ''),
+    endpointParty: String(item.facts?.endpointParty || ''),
+    roleLabelHint: String(item.facts?.roleLabelHint || ''),
+    referenceTarget: String(item.facts?.referenceTarget || ''),
+    targetCarrierKind: String(item.facts?.targetCarrierKind || ''),
+    targetWorkspaceId: String(item.facts?.targetWorkspaceId || ''),
+    archivePath: String(item.facts?.archivePath || ''),
+    targetInnerPath: String(item.facts?.targetInnerPath || item.facts?.targetArchiveEntry || ''),
+    targetArchiveEntry: String(item.facts?.targetArchiveEntry || ''),
+    targetBytes: Number(item.facts?.targetBytes || 0),
+    targetSha256: String(item.facts?.targetSha256 || '')
+  })));
+}
+
+export function projectRecipientV2ParticipantRoles(pointers = []) {
+  return Object.freeze(pointers.map((item) => Object.freeze({
+    pointerPath: item.path,
+    workspaceId: String(item.facts?.workspaceId || ''),
+    routeId: String(item.facts?.routeId || ''),
+    roleLabelHint: String(item.facts?.roleLabelHint || ''),
+    referenceTarget: String(item.facts?.referenceTarget || ''),
+    targetCarrierKind: String(item.facts?.targetCarrierKind || ''),
+    targetWorkspaceId: String(item.facts?.targetWorkspaceId || ''),
+    targetInnerPath: String(item.facts?.targetInnerPath || item.facts?.targetArchiveEntry || ''),
+    targetSha256: String(item.facts?.targetSha256 || '')
+  })));
+}
+
+function rolePointerAncestors(routePointer, endpointPointers = [], participantPointers = []) {
+  const byPath = new Map([...endpointPointers, ...participantPointers].map((item) => [String(item.path || ''), item]));
+  const out = [];
+  const seen = new Set();
+  let parent = parentTrace(routePointer);
+  while (byPath.has(parent) && !seen.has(parent)) {
+    seen.add(parent);
+    const pointer = byPath.get(parent);
+    out.unshift(pointer.path);
+    parent = parentTrace(pointer);
+  }
+  return out;
+}