@tiinex/core 0.1.1

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

@@ -0,0 +1,116 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+
+export const PORTABLE_HANDOFF_MATERIAL_CANDIDATE_SCHEMA_ID = 'tiinex.portable.handoff-material-candidate.v1';
+
+export function collectHandoffMaterialCandidates(input = {}) {
+  const out = [];
+  for (const material of input.materials || []) out.push(normalizeCandidate(material, { providerId: material.providerId || 'supplied-material', providerKind: material.providerKind || 'supplied-material' }));
+  for (const response of input.providerResults || []) {
+    const providerId = String(response.providerId || response.provider?.id || 'provider-result');
+    const providerKind = String(response.providerKind || response.provider?.kind || 'provider');
+    for (const candidate of response.candidates || response.materials || []) out.push(normalizeCandidate({ ...candidate, requirementId: candidate.requirementId || response.requirementId, referenceTarget: candidate.referenceTarget || response.referenceTarget }, { providerId, providerKind, responseStatus: response.status || '' }));
+  }
+  for (const prior of input.priorPackages || []) {
+    for (const candidate of prior.materials || []) out.push(normalizeCandidate({ ...candidate, priorPackageId: prior.id || prior.packageId || '', requirementId: candidate.requirementId }, { providerId: String(prior.providerId || `prior-package:${prior.id || prior.packageId || 'unknown'}`), providerKind: 'prior-package' }));
+  }
+  return Object.freeze(out.filter((item) => item.bytes > 0 || item.referenceTarget || item.requirementId));
+}
+
+export function resolveRequirementMaterial(requirement = {}, candidates = [], recipient = {}, policy = {}) {
+  const target = String(requirement.reference?.target || '');
+  const capability = recipientCanResolveReference(recipient, target);
+  const exactRequirementCandidates = candidates.filter((candidate) => candidate.requirementId && candidate.requirementId === requirement.id);
+  const relevant = exactRequirementCandidates.length ? exactRequirementCandidates : candidates.filter((candidate) => candidateMatchesRequirement(candidate, requirement));
+  const withBytes = relevant.filter((candidate) => candidate.bytes > 0 && candidate.sha256);
+  const conflicts = withBytes.filter((candidate) => candidate.expectedSha256 && candidate.expectedSha256 !== candidate.sha256);
+  if (conflicts.length) return resolution('integrity-conflict', requirement, relevant, null, capability, 'Resolved bytes contradict declared expected integrity authority.');
+  const digests = [...new Set(withBytes.map((candidate) => candidate.sha256))];
+  if (digests.length > 1) return resolution('ambiguous', requirement, relevant, null, capability, 'Multiple provider/material candidates carry distinct exact bytes and no selection authority is supplied.');
+  const exactBound = withBytes.filter((candidate) => candidateBoundToRequirement(candidate, requirement));
+  if (withBytes.length && !exactBound.length && target) return resolution('unresolved', requirement, relevant, null, capability, 'Resolved bytes cannot be bound back to the requested exact material reference.');
+  const distinctExactCandidates = distinctCandidateAuthorities(exactBound);
+  if (distinctExactCandidates.length > 1) return resolution('ambiguous', requirement, relevant, null, capability, 'Multiple distinct provider/material candidates are bound to the same exact requested representation, but no provider-selection authority exists. Byte equality does not authorize choosing provider provenance by array order.');
+  if (capability && policy.preferReferenceWhenResolvable !== false && target) return resolution('reference-sufficient', requirement, relevant, null, capability, 'Recipient capability can resolve the exact declared material reference without embedding bytes.');
+  if (exactBound.length) {
+    const selected = exactBound[0];
+    return resolution('materialized', requirement, relevant, selected, capability, 'Exact bytes are available and bound to the requested representation.');
+  }
+  if (capability && target) return resolution('reference-sufficient', requirement, relevant, null, capability, 'Recipient capability can resolve the exact declared material reference.');
+  return resolution('unresolved', requirement, relevant, null, capability, target ? 'Exact required material is not currently resolvable or materialized.' : 'No exact Material Reference or explicitly bound local material is available.');
+}
+
+export function recipientCanResolveReference(recipient = {}, target = '') {
+  if (!target) return false;
+  const exactTargets = new Set([
+    ...(recipient.referenceTargets || []),
+    ...(recipient.capabilities?.referenceTargets || []),
+    ...(recipient.resolvableReferences || [])
+  ].map(String));
+  return exactTargets.has(String(target));
+}
+
+function normalizeCandidate(value = {}, provider = {}) {
+  const data = packageFileBytes(value);
+  const suppliedSha = String(value.sha256 || value.integrity?.sha256 || '').toLowerCase();
+  const computedSha = data.byteLength ? sha256Hex(data) : '';
+  return deepFreeze({
+    schema: PORTABLE_HANDOFF_MATERIAL_CANDIDATE_SCHEMA_ID,
+    id: String(value.id || value.representationId || ''),
+    requirementId: String(value.requirementId || ''),
+    referenceTarget: String(value.referenceTarget || value.reference || value.source?.reference || value.source?.permalink || ''),
+    path: String(value.path || ''),
+    packagePath: String(value.packagePath || ''),
+    workspaceId: String(value.workspaceId || ''),
+    bytes: data.byteLength,
+    sha256: computedSha || suppliedSha,
+    expectedSha256: String(value.expectedSha256 || value.authority?.sha256 || '').toLowerCase(),
+    data,
+    mediaType: String(value.mediaType || value.type || 'application/octet-stream'),
+    provider: Object.freeze({ id: String(provider.providerId || ''), kind: String(provider.providerKind || ''), responseStatus: String(provider.responseStatus || ''), priorPackageId: String(value.priorPackageId || '') }),
+    provenance: Object.freeze(serializable(value.provenance || value.source || {})),
+    authority: Object.freeze(serializable(value.authority || {}))
+  });
+}
+
+
+function distinctCandidateAuthorities(candidates = []) {
+  const byIdentity = new Map();
+  for (const candidate of candidates) {
+    const identity = candidateAuthorityIdentity(candidate);
+    if (!byIdentity.has(identity)) byIdentity.set(identity, candidate);
+  }
+  return [...byIdentity.values()];
+}
+
+function candidateAuthorityIdentity(candidate = {}) {
+  return JSON.stringify(sortJson({
+    id: String(candidate.id || ''),
+    path: String(candidate.path || ''),
+    referenceTarget: String(candidate.referenceTarget || ''),
+    provider: candidate.provider || {},
+    provenance: candidate.provenance || {},
+    authority: candidate.authority || {}
+  }));
+}
+
+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])]));
+}
+
+function candidateMatchesRequirement(candidate, requirement) {
+  if (candidate.requirementId && candidate.requirementId === requirement.id) return true;
+  const target = String(requirement.reference?.target || '');
+  return Boolean(target && candidate.referenceTarget === target);
+}
+function candidateBoundToRequirement(candidate, requirement) {
+  const target = String(requirement.reference?.target || '');
+  if (!target) return Boolean(candidate.requirementId === requirement.id && candidate.authority?.localIdentityQualified === true);
+  return candidate.referenceTarget === target;
+}
+function resolution(disposition, requirement, candidates, selected, capability, reason) {
+  return deepFreeze({ disposition, requirementId: requirement.id, requirementName: String(requirement.name || ''), classification: requirement.classification, referenceTarget: String(requirement.reference?.target || ''), routeWorkspaceId: String(requirement.routeWorkspaceId || ''), routePath: String(requirement.routePath || ''), sourceRequirementId: String(requirement.sourceRequirementId || ''), recipientReferenceCapability: Boolean(capability), selectedMaterial: selected, candidates: Object.freeze(candidates), reason });
+}
+function serializable(value = {}) { const out = {}; for (const [key, item] of Object.entries(value || {})) if (typeof item !== 'function' && typeof item !== 'undefined') out[key] = item; return out; }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

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

@@ -0,0 +1,181 @@
+import { buildExportPackageBundle, inspectExportPackageBundle } from '../../../export/package.builder.js';
+import { buildExportPackageFileMap, finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileBytes, sha256Hex, stableFingerprintBytes, utf8Bytes } from '../../../export/package.bytes.js';
+import { packageMaterialRepresentationSha256 } from '../../../export/package.controlIntegrity.js';
+import { roundTripPortableRuntimePackage } from '../package/runtime.package.js';
+import { planRecipientRelativeHandoffMaterialClosure, qualifyWorkspaceMaterializationCorrelationEntry, workspaceMaterializationCorrelationKey } from './materialClosure.plan.js';
+import { buildHandoffClosureDescriptor, HANDOFF_CLOSURE_DESCRIPTOR_PATH, inspectHandoffClosureDescriptor } from './materialClosure.descriptor.js';
+import { qualifyHandoffMaterialClosurePlanReadiness } from './materialClosure.readiness.js';
+import { qualifyHandoffMaterialClosurePlanInputBinding } from './materialClosure.inputBinding.js';
+import { qualifyHandoffMaterializedOutput } from './materialClosure.materialized.js';
+import { buildHandoffTransportCompanionProjection, HANDOFF_TRANSPORT_COMPANION_PATH, inspectHandoffTransportCompanion } from './transportCompanion.js';
+import { buildHandoffCarrierProjection, HANDOFF_CARRIER_PROJECTION_PATH, inspectHandoffCarrierProjection } from './carrierProjection.js';
+import { buildHandoffColdConsumerProjection, renderHandoffColdConsumerEntrypoint, HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH, inspectHandoffColdConsumerEntrypoint } from './coldConsumerEntrypoint.js';
+import { buildHandoffPointerEntrypoints, inspectHandoffPointerEntrypoints, HANDOFF_POINTER_ENTRYPOINT_PREFIX } from './pointerEntrypoint.js';
+
+export const PORTABLE_HANDOFF_TRANSPORT_PACKAGE_SCHEMA_ID = 'tiinex.portable.handoff-transport-package.v1';
+
+export function buildRecipientRelativeHandoffTransportPackage(input = {}, options = {}) {
+  const plan = input.plan || planRecipientRelativeHandoffMaterialClosure(input, options);
+  const planReadiness = qualifyHandoffMaterialClosurePlanReadiness(plan);
+  const planInputBinding = qualifyHandoffMaterialClosurePlanInputBinding(plan, input, { externallySupplied: Boolean(input.plan) });
+  const materializedOutputQualification = qualifyHandoffMaterializedOutput(plan);
+  const baseBundle = input.baseBundle || buildExportPackageBundle(input.workspace || {}, { ...(input.packageInput || {}), ...(options.packageInput || {}) });
+  const extraFiles = [];
+  const packagedMaterial = [];
+  for (const entry of materializedOutputQualification.state === 'qualified' ? materializedOutputQualification.expected : []) {
+    const packagePath = materialPackagePath(entry);
+    const file = finalizeFile({ path: packagePath, kind: 'handoff-material', logicalKind: 'recipient-relative-material', entryId: entry.requirementId, mediaType: entry.mediaType || 'application/octet-stream', data: entry.data, boundary: 'Recipient-relative exact byte carrier. Canonical artifact/source/workspace authority remains external and is preserved in the closure descriptor.' });
+    extraFiles.push(file);
+    packagedMaterial.push(Object.freeze({ ...entry, packagePath: file.path, bytes: file.bytes, sha256: file.sha256 }));
+  }
+  const packagedWorkspaces = [];
+  const qualifiedWorkspaceByCorrelation = indexWorkspaceMaterializationTruth(plan.workspaceMaterializations || []);
+  const rawWorkspaceCorrelationCounts = countWorkspaceCorrelationKeys(input.workspaceMaterializations || []);
+  let workspaceCorrelationBlocked = false;
+  for (const workspace of input.workspaceMaterializations || []) {
+    const transportCorrelationKey = workspaceMaterializationCorrelationKey(workspace);
+    const correlation = resolveWorkspaceMaterializationTruth(qualifiedWorkspaceByCorrelation, transportCorrelationKey, rawWorkspaceCorrelationCounts.get(transportCorrelationKey) || 0);
+    const qualifiedWorkspace = correlation.workspace;
+    const correlationStatus = correlation.status;
+    if (correlationStatus !== 'qualified') workspaceCorrelationBlocked = true;
+    const workspaceId = String(qualifiedWorkspace?.id || workspace.id || workspace.workspaceId || 'workspace');
+    const packagedEntries = [];
+    for (const entry of workspace.entries || []) {
+      if (!hasBytes(entry)) continue;
+      const file = finalizeFile({ path: workspacePackagePath(workspace, entry, workspaceId), kind: 'handoff-workspace-material', logicalKind: 'recipient-relative-workspace-byte-carrier', entryId: `workspace:${workspaceId}:${entry.path || ''}`, mediaType: entry.mediaType || entry.type || 'application/octet-stream', data: packageFileBytes(entry), boundary: workspaceCarrierBoundary(qualifiedWorkspace) });
+      extraFiles.push(file);
+      packagedEntries.push(Object.freeze({ path: String(entry.path || ''), packagePath: file.path, bytes: file.bytes, sha256: file.sha256, referenceTarget: String(entry.referenceTarget || '') }));
+    }
+    packagedWorkspaces.push(Object.freeze({ id: workspaceId, transportCorrelationKey, correlationStatus, entries: Object.freeze(packagedEntries) }));
+  }
+  let bootstrapPath = '';
+  let bootstrapCarrierBlocked = false;
+  if (plan.bootstrap?.status === 'present') {
+    const bootstrapPresented = input.bootstrap?.present === true || input.bootstrap?.include === true;
+    const bootstrapData = packageFileBytes(input.bootstrap || {});
+    if (!bootstrapPresented || bootstrapData.byteLength === 0) {
+      bootstrapCarrierBlocked = true;
+    } else {
+      bootstrapPath = safePath(input.bootstrap?.path || 'tiinex.package/bootstrap.md');
+      extraFiles.push(finalizeFile({ path: bootstrapPath, kind: 'handoff-bootstrap', logicalKind: 'transport-orientation', mediaType: String(input.bootstrap?.mediaType || input.bootstrap?.type || 'text/markdown'), data: bootstrapData, boundary: 'Optional transport orientation only; not a Tiinex artifact or workspace lineage member.' }));
+    }
+  }
+  let additionalTransportBlocked = false;
+  const additionalTransportPaths = new Set();
+  for (const entry of input.additionalTransportFiles || []) {
+    const filePath = safePath(entry.path || '');
+    const data = packageFileBytes(entry);
+    if (!filePath || data.byteLength === 0 || additionalTransportPaths.has(filePath) || reservedGeneratedPath(filePath)) {
+      additionalTransportBlocked = true;
+      continue;
+    }
+    additionalTransportPaths.add(filePath);
+    extraFiles.push(finalizeFile({
+      path: filePath,
+      kind: String(entry.kind || 'handoff-transport-material'),
+      logicalKind: String(entry.logicalKind || 'recipient-relative-transport-material'),
+      entryId: String(entry.entryId || ''),
+      mediaType: String(entry.mediaType || entry.type || 'application/octet-stream'),
+      data,
+      boundary: String(entry.boundary || 'Additional recipient-relative transport byte; package placement does not create semantic authority.'),
+      sourceBoundary: String(entry.sourceBoundary || '')
+    }));
+  }
+  const localRunId = String(input.localRunId || `handoff-closure:${stableFingerprintBytes(utf8Bytes(JSON.stringify({ handoff: plan.handoff, required: plan.requirements?.required?.map((x) => [x.requirementId, x.disposition]), reference: plan.requirements?.reference?.map((x) => [x.requirementId, x.disposition]) })))}`);
+  const descriptor = buildHandoffClosureDescriptor(plan, { materialized: packagedMaterial, workspaces: packagedWorkspaces, bootstrapPath, localRunId, planInputBinding, materializedOutputQualification });
+  const descriptorFile = finalizeFile({ path: HANDOFF_CLOSURE_DESCRIPTOR_PATH, kind: 'handoff-closure-descriptor', logicalKind: 'disposable-transport-control', mediaType: 'application/json', content: `${stablePrettyJson(descriptor)}\n`, boundary: descriptor.boundary });
+  const packageClosureStatus = planReadiness.state === 'qualified' && planReadiness.expectedRequiredClosureReady && planInputBinding.state === 'qualified' && materializedOutputQualification.state === 'qualified' && baseBundle.status !== 'blocked' && !workspaceCorrelationBlocked && !bootstrapCarrierBlocked && !additionalTransportBlocked ? (baseBundle.status === 'degraded' ? 'degraded' : 'ready') : 'blocked';
+  const projectionBundle = { ...baseBundle, files: [...(baseBundle.files || []), ...extraFiles, descriptorFile], handoffClosure: descriptor };
+  const carrierProjection = buildHandoffCarrierProjection({ bundle: projectionBundle, descriptor, carrierLineage: input.carrierLineage || null, routes: input.transportRoutes || input.handoffRoutes || [] });
+  const carrierFile = finalizeFile({ path: HANDOFF_CARRIER_PROJECTION_PATH, kind: 'handoff-carrier-projection', logicalKind: 'disposable-human-transport-projection', mediaType: 'application/json', content: `${stablePrettyJson(carrierProjection)}\n`, boundary: carrierProjection.boundary });
+  const pointerEntrypointProjection = buildHandoffPointerEntrypoints({ carrierProjection, createdAt: baseBundle.manifest?.createdAt || baseBundle.builtAt || '' });
+  const pointerEntrypointFiles = pointerEntrypointProjection.entries.map((entry) => finalizeFile({ path: entry.path, kind: 'handoff-route-pointer', logicalKind: 'disposable-package-orientation-projection', mediaType: 'text/markdown', content: entry.markdown, boundary: entry.boundary }));
+  const coldConsumerProjection = buildHandoffColdConsumerProjection({ carrierProjection });
+  const coldConsumerEntrypointFile = finalizeFile({ path: HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH, kind: 'handoff-cold-consumer-entrypoint', logicalKind: 'disposable-package-orientation-projection', mediaType: 'text/markdown', content: renderHandoffColdConsumerEntrypoint({ projection: coldConsumerProjection }), boundary: coldConsumerProjection.boundary });
+  const selectedHandoffConformanceReady = (carrierProjection.routes || []).length > 0 && (carrierProjection.routes || []).every((route) => route.conformance?.status === 'qualified');
+  const transportStatus = !selectedHandoffConformanceReady || (carrierProjection.mode === 'shared' && carrierProjection.status !== 'ready') ? 'blocked' : packageClosureStatus;
+  const transportCompanion = buildHandoffTransportCompanionProjection({ bundle: baseBundle, descriptor, packageStatus: transportStatus, participation: input.transportParticipation || input.participation || {} });
+  const companionFile = finalizeFile({ path: HANDOFF_TRANSPORT_COMPANION_PATH, kind: 'handoff-transport-companion', logicalKind: 'disposable-transport-projection', mediaType: 'application/json', content: `${stablePrettyJson(transportCompanion)}\n`, boundary: transportCompanion.boundary });
+  const oldFileMapPath = 'tiinex.package/file-map.json';
+  const buildReceiptPath = 'tiinex.package/build-receipt.json';
+  const baseGoverned = [...(baseBundle.files || []).filter((file) => ![oldFileMapPath, buildReceiptPath].includes(String(file.path || ''))), ...extraFiles, descriptorFile, carrierFile, ...pointerEntrypointFiles, coldConsumerEntrypointFile, companionFile].map(finalizeFile);
+  const materialRepresentationSha256 = packageMaterialRepresentationSha256(baseGoverned);
+  const priorBuildReceipt = parseJsonFile((baseBundle.files || []).find((file) => String(file.path || '') === buildReceiptPath)) || {};
+  const buildReceipt = Object.freeze({ ...priorBuildReceipt, materialRepresentationSha256, counts: Object.freeze({ ...(priorBuildReceipt.counts || {}), materialFiles: baseGoverned.filter((file) => file.path && !String(file.path).startsWith('tiinex.package/')).length }) });
+  const buildReceiptFile = finalizeFile({ path: buildReceiptPath, kind: 'package-build-receipt', mediaType: 'application/json', content: `${stablePrettyJson(buildReceipt)}\n` });
+  const governed = [...baseGoverned, buildReceiptFile].map(finalizeFile);
+  const fileMap = buildExportPackageFileMap(governed, { packageId: baseBundle.packageId || '' });
+  const fileMapFile = finalizeFile({ path: oldFileMapPath, kind: 'package-file-map', mediaType: 'application/json', content: `${stablePrettyJson(fileMap)}\n` });
+  const files = Object.freeze([...governed, fileMapFile]);
+  const status = transportStatus;
+  const bundle = deepFreeze({ ...baseBundle, schema: baseBundle.schema, status, files, fileMap, packageRepresentationSha256: fileMap.representationSha256, handoffClosure: descriptor, boundary: `${baseBundle.boundary} Recipient-relative Handoff closure descriptor/material are disposable transport controls and do not alter semantic Handoff or workspace truth.` });
+  const inspection = inspectExportPackageBundle(bundle);
+  const closureInspection = inspectHandoffClosureDescriptor(bundle);
+  const carrierInspection = inspectHandoffCarrierProjection(bundle);
+  const pointerEntrypointInspection = inspectHandoffPointerEntrypoints(bundle);
+  const coldConsumerEntrypointInspection = inspectHandoffColdConsumerEntrypoint(bundle);
+  const companionInspection = inspectHandoffTransportCompanion(bundle);
+  return deepFreeze({ schema: PORTABLE_HANDOFF_TRANSPORT_PACKAGE_SCHEMA_ID, status: inspection.status === 'valid' && closureInspection.status === 'valid' && carrierInspection.status === 'valid' && pointerEntrypointInspection.status === 'valid' && coldConsumerEntrypointInspection.status === 'valid' && companionInspection.status === 'valid' ? status : 'blocked', plan, planReadiness, planInputBinding, materializedOutputQualification, bundle, inspection, closureInspection, descriptor, carrierProjection, carrierInspection, pointerEntrypointProjection, pointerEntrypointInspection, coldConsumerProjection, coldConsumerEntrypointInspection, transportCompanion, companionInspection });
+}
+
+export function roundTripRecipientRelativeHandoffTransportPackage(input = {}, options = {}) {
+  const built = input.bundle ? input : buildRecipientRelativeHandoffTransportPackage(input, options);
+  const bundle = built.bundle || input.bundle;
+  const runtime = roundTripPortableRuntimePackage({ bundle });
+  const closureInspection = inspectHandoffClosureDescriptor(bundle);
+  const carrierInspection = inspectHandoffCarrierProjection(bundle);
+  const pointerEntrypointInspection = inspectHandoffPointerEntrypoints(bundle);
+  const coldConsumerEntrypointInspection = inspectHandoffColdConsumerEntrypoint(bundle);
+  const companionInspection = inspectHandoffTransportCompanion(bundle);
+  const status = runtime.status.startsWith('passed') && closureInspection.status === 'valid' && carrierInspection.status === 'valid' && pointerEntrypointInspection.status === 'valid' && coldConsumerEntrypointInspection.status === 'valid' && companionInspection.status === 'valid' ? 'passed' : 'failed';
+  return deepFreeze({ schema: 'tiinex.portable.handoff-transport-package.roundtrip.v1', status, built, runtime, closureInspection, carrierInspection, pointerEntrypointInspection, coldConsumerEntrypointInspection, companionInspection, verification: Object.freeze({ descriptorPath: HANDOFF_CLOSURE_DESCRIPTOR_PATH, descriptorVerified: closureInspection.status === 'valid', carrierProjectionPath: HANDOFF_CARRIER_PROJECTION_PATH, carrierProjectionVerified: carrierInspection.status === 'valid', pointerEntrypointsVerified: pointerEntrypointInspection.status === 'valid', coldConsumerEntrypointPath: HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH, coldConsumerEntrypointVerified: coldConsumerEntrypointInspection.status === 'valid', companionPath: HANDOFF_TRANSPORT_COMPANION_PATH, companionVerified: companionInspection.status === 'valid', packageRoundtrip: runtime.status, requiredClosureReady: Boolean(built.plan?.requiredClosureReady) }) });
+}
+
+
+function indexWorkspaceMaterializationTruth(items = []) {
+  const index = new Map();
+  for (const workspace of items) {
+    const qualification = qualifyWorkspaceMaterializationCorrelationEntry(workspace);
+    if (qualification.state !== 'qualified') continue;
+    const key = qualification.key;
+    const current = index.get(key);
+    if (!current) index.set(key, Object.freeze({ status: 'qualified', workspace }));
+    else index.set(key, Object.freeze({ status: 'ambiguous', workspace: null }));
+  }
+  return index;
+}
+
+function countWorkspaceCorrelationKeys(items = []) {
+  const counts = new Map();
+  for (const workspace of items) {
+    const key = workspaceMaterializationCorrelationKey(workspace);
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return counts;
+}
+
+function resolveWorkspaceMaterializationTruth(index, key = '', rawCount = 0) {
+  if (!key || rawCount !== 1) return Object.freeze({ status: rawCount > 1 ? 'ambiguous' : 'unresolved', workspace: null });
+  const entry = index.get(String(key || ''));
+  if (!entry) return Object.freeze({ status: 'unresolved', workspace: null });
+  return entry;
+}
+
+
+function workspaceCarrierBoundary(workspace = null) {
+  if (workspace?.qualification === 'qualified' && workspace?.materialization === 'complete') return 'Package-local complete-evidence-backed workspace byte carrier; directory shape is not completeness proof.';
+  if (workspace?.qualification && workspace.qualification !== 'qualified') return `Package-local partial workspace byte carrier; planner-qualified workspace truth is ${workspace.materialization || 'partial'}/${workspace.qualification}. Raw caller completeness claims are not package authority.`;
+  return 'Package-local partial workspace byte carrier; directory shape is not completeness proof.';
+}
+
+function reservedGeneratedPath(value = '') { const path = String(value || ''); return path.startsWith(HANDOFF_POINTER_ENTRYPOINT_PREFIX) || ['tiinex.package/file-map.json', 'tiinex.package/build-receipt.json', HANDOFF_CLOSURE_DESCRIPTOR_PATH, HANDOFF_CARRIER_PROJECTION_PATH, HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH, HANDOFF_TRANSPORT_COMPANION_PATH].includes(path); }
+function materialPackagePath(entry = {}) { return safePath(entry.requestedPackagePath || `handoff.material/${safeToken(entry.requirementId || 'material')}/material.bin`); }
+function workspacePackagePath(workspace = {}, entry = {}, qualifiedWorkspaceId = '') { return safePath(entry.packagePath || `handoff.workspaces/${safeToken(qualifiedWorkspaceId || workspace.id || workspace.workspaceId || 'workspace')}/${safePath(entry.path || 'material.bin')}`); }
+function safePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').split('/').filter((part) => part && part !== '.' && part !== '..').map((part) => part.replace(/[\u0000-\u001f<>:"|?*]/g, '_')).join('/') || 'material.bin'; }
+function safeToken(value = '') { const raw = String(value || ''); const token = raw.trim().replace(/[^a-zA-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)}`; }
+function hasBytes(value = {}) { return packageFileBytes(value).byteLength > 0; }
+function parseJsonFile(file = {}) { try { return JSON.parse(new TextDecoder().decode(packageFileBytes(file))); } catch { return null; } }
+function stablePrettyJson(value) { return JSON.stringify(sortJson(value), null, 2); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return undefined; return Object.fromEntries(Object.keys(value).sort().flatMap((key) => { const sorted = sortJson(value[key]); return typeof sorted === 'undefined' ? [] : [[key, sorted]]; })); }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

package/src/tooling/portable/handoff/materialClosure.plan.js

@@ -0,0 +1,204 @@
+import { projectHandoffMaterialRequirements } from './materialClosure.requirements.js';
+import { collectHandoffMaterialCandidates, resolveRequirementMaterial } from './materialClosure.materials.js';
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { buildHandoffMaterialClosurePlanInputBinding } from './materialClosure.inputBinding.js';
+
+export const PORTABLE_HANDOFF_MATERIAL_CLOSURE_PLAN_SCHEMA_ID = 'tiinex.portable.handoff-material-closure-plan.v1';
+
+export function planRecipientRelativeHandoffMaterialClosure(input = {}, options = {}) {
+  const findings = [];
+  const requirements = input.requirements || projectHandoffMaterialRequirements(input.handoff || {});
+  const candidates = collectHandoffMaterialCandidates(input);
+  const policy = Object.freeze({
+    preferReferenceWhenResolvable: input.preferReferenceWhenResolvable !== false,
+    includeReferenceMaterial: input.includeReferenceMaterial === true,
+    bootstrap: input.bootstrap?.present === true || input.bootstrap?.include === true ? 'present' : 'absent'
+  });
+  const required = requirements.required.map((requirement) => resolveRequirementMaterial(requirement, candidates, input.recipient || {}, policy));
+  const reference = requirements.reference.map((requirement) => referenceDisposition(requirement, candidates, input.recipient || {}, policy));
+  const endpointRoles = (requirements.endpointRoles || []).map((requirement) => resolveRequirementMaterial(requirement, candidates, input.recipient || {}, { ...policy, preferReferenceWhenResolvable: false }));
+  const participantRoles = (requirements.participantRoles || []).map((requirement) => resolveRequirementMaterial(requirement, candidates, input.recipient || {}, { ...policy, preferReferenceWhenResolvable: false }));
+  const dependencies = (requirements.dependencies || []).map((requirement) => resolveRequirementMaterial(requirement, candidates, input.recipient || {}, { ...policy, preferReferenceWhenResolvable: false }));
+  const workspaces = qualifyWorkspaceMaterializations(input.workspaceMaterializations || [], findings);
+  const inputBinding = buildHandoffMaterialClosurePlanInputBinding(requirements, input.recipient || {}, { required, reference, endpointRoles, participantRoles, dependencies }, { policy, bootstrap: input.bootstrap || {} });
+  const requiredBlocked = required.some((item) => ['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition));
+  const endpointRoleBlocked = endpointRoles.some((item) => ['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition));
+  const participantRoleBlocked = participantRoles.some((item) => ['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition));
+  const dependencyBlocked = dependencies.some((item) => ['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition));
+  const workspaceBlocked = workspaces.some((item) => String(item.qualification || '').startsWith('invalid-'));
+  const ready = !requiredBlocked && !endpointRoleBlocked && !participantRoleBlocked && !dependencyBlocked && !workspaceBlocked;
+  for (const item of required) if (['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition)) findings.push(finding('error', `portable.handoff-material.required.${item.disposition}`, item.reason, { requirementId: item.requirementId, referenceTarget: item.referenceTarget }));
+  for (const item of endpointRoles) if (['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition)) findings.push(finding('error', `portable.handoff-material.endpoint-role.${item.disposition}`, item.reason, { requirementId: item.requirementId, referenceTarget: item.referenceTarget }));
+  for (const item of participantRoles) if (['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition)) findings.push(finding('error', `portable.handoff-material.participant-role.${item.disposition}`, item.reason, { requirementId: item.requirementId, referenceTarget: item.referenceTarget }));
+  for (const item of dependencies) if (['unresolved', 'ambiguous', 'integrity-conflict'].includes(item.disposition)) findings.push(finding('error', `portable.handoff-material.dependency.${item.disposition}`, item.reason, { requirementId: item.requirementId, referenceTarget: item.referenceTarget }));
+  for (const item of reference) if (item.disposition === 'ambiguous' || item.disposition === 'integrity-conflict') findings.push(finding('warning', `portable.handoff-material.reference.${item.disposition}`, item.reason, { requirementId: item.requirementId, referenceTarget: item.referenceTarget }));
+  const materialized = [...required, ...reference, ...endpointRoles, ...participantRoles, ...dependencies].filter((item) => item.disposition === 'materialized' && item.selectedMaterial).map((item) => materializedPlanEntry(item));
+  return deepFreeze({
+    schema: PORTABLE_HANDOFF_MATERIAL_CLOSURE_PLAN_SCHEMA_ID,
+    status: ready ? 'ready' : 'blocked',
+    requiredClosureReady: ready,
+    semanticHandoffStatus: String(requirements.handoff?.semanticStatus || 'unknown'),
+    boundary: 'Recipient-relative disposable transport plan. It does not change Handoff validity/state, artifact identity, workspace ownership, provider semantics, or acceptance/completion.',
+    handoff: requirements.handoff,
+    inputBinding,
+    policy,
+    requirements: Object.freeze({ required: Object.freeze(required), reference: Object.freeze(reference), endpointRoles: Object.freeze(endpointRoles), participantRoles: Object.freeze(participantRoles), dependencies: Object.freeze(dependencies) }),
+    materialized: Object.freeze(materialized),
+    workspaceMaterializations: Object.freeze(workspaces),
+    bootstrap: Object.freeze({ status: policy.bootstrap, boundary: 'Optional transport orientation only; not Handoff semantics, workspace authority, or artifact identity.' }),
+    findings: Object.freeze([...(requirements.findings || []), ...findings])
+  });
+}
+
+function referenceDisposition(requirement, candidates, recipient, policy) {
+  if (!policy.includeReferenceMaterial) {
+    const resolved = resolveRequirementMaterial(requirement, candidates, recipient, policy);
+    if (resolved.disposition === 'reference-sufficient') return resolved;
+    return Object.freeze({ ...resolved, disposition: 'omitted-by-plan', selectedMaterial: null, reason: 'Reference-only material was intentionally omitted by this recipient-relative plan.' });
+  }
+  return resolveRequirementMaterial(requirement, candidates, recipient, policy);
+}
+
+function materializedPlanEntry(item) {
+  const material = item.selectedMaterial || {};
+  return Object.freeze({
+    requirementId: item.requirementId,
+    classification: item.classification,
+    referenceTarget: item.referenceTarget,
+    routeWorkspaceId: item.routeWorkspaceId,
+    routePath: item.routePath,
+    sourceRequirementId: item.sourceRequirementId,
+    path: material.path,
+    requestedPackagePath: material.packagePath,
+    bytes: material.bytes,
+    sha256: material.sha256,
+    mediaType: material.mediaType,
+    provider: material.provider,
+    provenance: material.provenance,
+    authority: material.authority,
+    data: material.data
+  });
+}
+
+function qualifyWorkspaceMaterializations(items, findings) {
+  return Object.freeze((items || []).map((item, index) => {
+    const qualified = qualifyWorkspaceMaterialization(item, index, findings);
+    const transportCorrelationEvidence = workspaceMaterializationCorrelationEvidence(item, qualified);
+    return deepFreeze({ ...qualified, transportCorrelationEvidence, transportCorrelationKey: workspaceMaterializationCorrelationKeyFromEvidence(transportCorrelationEvidence) });
+  }));
+}
+
+function qualifyWorkspaceMaterialization(item = {}, index = 0, findings = null) {
+  const requested = String(item.state || item.materialization || 'partial');
+  const completeEvidence = item.completenessEvidence?.state === 'qualified' || item.completeEvidence?.state === 'qualified';
+  const boundedEvidence = item.scopeEvidence?.state === 'qualified';
+  let qualification = 'qualified';
+  let materialization = 'partial';
+  if (requested === 'complete') {
+    qualification = completeEvidence ? 'qualified' : 'invalid-completeness-claim';
+    materialization = completeEvidence ? 'complete' : 'partial';
+  } else if (requested === 'bounded') {
+    qualification = boundedEvidence ? 'qualified' : 'invalid-bounded-scope-claim';
+    materialization = boundedEvidence ? 'bounded' : 'partial';
+  }
+  if (qualification === 'invalid-completeness-claim' && findings) findings.push(finding('error', 'portable.handoff-material.workspace.complete-unproven', 'Workspace materialization claimed complete without qualified completeness evidence for the declared workspace boundary.', { workspaceId: item.id || item.workspaceId || `workspace-${index}` }));
+  if (qualification === 'invalid-bounded-scope-claim' && findings) findings.push(finding('error', 'portable.handoff-material.workspace.bounded-unproven', 'Workspace materialization claimed bounded without qualified exact representation-entry-set scope evidence.', { workspaceId: item.id || item.workspaceId || `workspace-${index}` }));
+  return deepFreeze({
+    id: String(item.id || item.workspaceId || `workspace-${index}`),
+    title: String(item.title || item.name || item.workspaceTitle || item.id || item.workspaceId || `workspace-${index}`),
+    source: Object.freeze({ ...(item.source || {}) }),
+    materialization,
+    qualification,
+    completenessEvidence: Object.freeze({ ...(item.completenessEvidence || item.completeEvidence || {}) }),
+    scopeEvidence: Object.freeze({ ...(item.scopeEvidence || {}) }),
+    includedEntries: Object.freeze((item.includedEntries || item.entries || []).map(normalizeIncludedEntry))
+  });
+}
+
+export function workspaceMaterializationCorrelationEvidence(item = {}, prequalified = null) {
+  const qualified = prequalified || qualifyWorkspaceMaterialization(item);
+  return deepFreeze(sortJson({
+    schema: 'tiinex.portable.handoff-workspace-transport-correlation-evidence.v1',
+    declared: {
+      id: String(item.id || ''),
+      workspaceId: String(item.workspaceId || ''),
+      requestedMaterialization: String(item.state || item.materialization || 'partial')
+    },
+    source: serializable(item.source || {}),
+    completenessEvidence: serializable(item.completenessEvidence || item.completeEvidence || {}),
+    scopeEvidence: serializable(item.scopeEvidence || {}),
+    carrierEntries: (item.entries || []).map((entry) => carrierCorrelationEntry(entry)),
+    qualifiedTruth: {
+      materialization: String(qualified.materialization || 'partial'),
+      qualification: String(qualified.qualification || ''),
+      completenessEvidence: serializable(qualified.completenessEvidence || {}),
+      scopeEvidence: serializable(qualified.scopeEvidence || {}),
+      includedEntries: (qualified.includedEntries || []).map(normalizeIncludedEntry)
+    }
+  }));
+}
+
+export function workspaceMaterializationCorrelationKey(item = {}) {
+  return workspaceMaterializationCorrelationKeyFromEvidence(workspaceMaterializationCorrelationEvidence(item));
+}
+
+export function workspaceMaterializationCorrelationKeyFromEvidence(evidence = {}) {
+  return JSON.stringify(sortJson(serializable(evidence)));
+}
+
+export function qualifyWorkspaceMaterializationCorrelationEntry(item = {}) {
+  const evidence = item?.transportCorrelationEvidence
+    ? deepFreeze(sortJson(serializable(item.transportCorrelationEvidence)))
+    : workspaceMaterializationCorrelationEvidence(item);
+  const key = String(item?.transportCorrelationKey || '');
+  const expectedKey = workspaceMaterializationCorrelationKeyFromEvidence(evidence);
+  const findings = [];
+  if (!key) findings.push('transport-correlation-key-missing');
+  else if (key !== expectedKey) findings.push('transport-correlation-key-stale');
+  const qualifiedTruth = evidence.qualifiedTruth || {};
+  if (stableJson(item.source || {}) !== stableJson(evidence.source || {})) findings.push('transport-correlation-source-mismatch');
+  if (String(item.materialization || '') !== String(qualifiedTruth.materialization || '')) findings.push('transport-correlation-materialization-mismatch');
+  if (String(item.qualification || '') !== String(qualifiedTruth.qualification || '')) findings.push('transport-correlation-qualification-mismatch');
+  if (stableJson(item.completenessEvidence || {}) !== stableJson(qualifiedTruth.completenessEvidence || {})) findings.push('transport-correlation-completeness-evidence-mismatch');
+  if (stableJson(item.scopeEvidence || {}) !== stableJson(qualifiedTruth.scopeEvidence || {})) findings.push('transport-correlation-scope-evidence-mismatch');
+  if (stableJson(item.includedEntries || []) !== stableJson(qualifiedTruth.includedEntries || [])) findings.push('transport-correlation-included-entries-mismatch');
+  return Object.freeze({ state: findings.length ? 'invalid' : 'qualified', key, expectedKey, evidence, findings: Object.freeze(findings) });
+}
+
+function carrierCorrelationEntry(entry = {}) {
+  const data = packageFileBytes(entry);
+  return Object.freeze({
+    path: String(entry.path || ''),
+    requestedPackagePath: String(entry.packagePath || ''),
+    referenceTarget: String(entry.referenceTarget || ''),
+    mediaType: String(entry.mediaType || entry.type || ''),
+    bytes: data.byteLength,
+    sha256: sha256Hex(data)
+  });
+}
+
+function normalizeIncludedEntry(entry = {}) {
+  return Object.freeze({ path: String(entry.path || ''), sha256: String(entry.sha256 || ''), bytes: Number(entry.bytes || 0), referenceTarget: String(entry.referenceTarget || '') });
+}
+
+function stableJson(value) { return JSON.stringify(sortJson(serializable(value))); }
+
+
+function serializable(value = {}) {
+  if (Array.isArray(value)) return value.map(serializable);
+  if (!value || typeof value !== 'object') return value;
+  if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return undefined;
+  return Object.fromEntries(Object.entries(value).flatMap(([key, item]) => {
+    if (typeof item === 'function' || typeof item === 'undefined') return [];
+    const normalized = serializable(item);
+    return typeof normalized === 'undefined' ? [] : [[key, normalized]];
+  }));
+}
+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])]));
+}
+
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

package/src/tooling/portable/handoff/materialClosure.readiness.js

@@ -0,0 +1,36 @@
+export function qualifyHandoffMaterialClosurePlanReadiness(plan = {}) {
+  const blockingRequirements = [
+    ...(plan.requirements?.required || []),
+    ...(plan.requirements?.endpointRoles || []),
+    ...(plan.requirements?.participantRoles || []),
+    ...(plan.requirements?.dependencies || [])
+  ];
+  const requiredBlockers = Object.freeze(blockingRequirements
+    .filter((entry) => ['unresolved', 'ambiguous', 'integrity-conflict'].includes(String(entry?.disposition || '')))
+    .map((entry) => Object.freeze({ requirementId: String(entry?.requirementId || ''), disposition: String(entry?.disposition || '') })));
+  const workspaceBlockers = Object.freeze((plan.workspaceMaterializations || [])
+    .filter((entry) => String(entry?.qualification || '') !== 'qualified')
+    .map((entry) => Object.freeze({ id: String(entry?.id || ''), materialization: String(entry?.materialization || 'partial'), qualification: String(entry?.qualification || 'unresolved') })));
+  const expectedRequiredClosureReady = requiredBlockers.length === 0 && workspaceBlockers.length === 0;
+  const expectedStatus = expectedRequiredClosureReady ? 'ready' : 'blocked';
+  const declaredRequiredClosureReady = Boolean(plan.requiredClosureReady);
+  const declaredStatus = String(plan.status || 'blocked');
+  const findings = [];
+  if (declaredRequiredClosureReady !== expectedRequiredClosureReady) findings.push('required-closure-ready-contradictory');
+  if (declaredStatus !== expectedStatus) findings.push('plan-status-contradictory');
+  return deepFreeze({
+    state: findings.length ? 'invalid' : 'qualified',
+    declaredStatus,
+    declaredRequiredClosureReady,
+    expectedStatus,
+    expectedRequiredClosureReady,
+    blockers: Object.freeze({ required: requiredBlockers, workspaces: workspaceBlockers }),
+    findings: Object.freeze(findings)
+  });
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}