@tiinex/core 0.1.1

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

@@ -0,0 +1,44 @@
+import { HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID } from './workspaceByteProvider.js';
+
+export function buildDirectArchiveProjectionProvider(records = []) {
+  const workspaces = records.map(({ workspace = {}, binding = {}, qualified = {}, archiveFile = null } = {}) => {
+    const archivePath = String(binding.representation?.packagePath || archiveFile?.path || '');
+    const entries = (qualified.entries || []).map((entry) => deepFreeze({
+      path: String(entry.path || ''),
+      innerPath: String(entry.path || ''),
+      archivePackagePath: archivePath,
+      packagePath: archivePath,
+      bytes: Number(entry.bytes || 0),
+      sha256: String(entry.sha256 || ''),
+      referenceTarget: String(entry.referenceTarget || ''),
+      data: entry.data
+    }));
+    return deepFreeze({
+      state: 'qualified',
+      id: String(workspace.id || ''),
+      title: String(workspace.title || workspace.id || ''),
+      mode: 'archive',
+      materialization: workspace,
+      entries: Object.freeze(entries),
+      workspaceTarget: deepFreeze({ ...(binding.workspaceTarget || {}), data: qualified.target?.data || new Uint8Array() }),
+      archive: deepFreeze({ ...(binding.representation || {}), data: archiveFile?.data || new Uint8Array() }),
+      binding,
+      reasons: Object.freeze([]),
+      authority: Object.freeze({ locatorAuthority: false, filenameAuthority: false, packagePlacementAuthority: false, bindingAuthority: 'manufacture-local-exact-qualified-workspace-source-plus-new-archive-byte-identity' })
+    });
+  });
+  return deepFreeze({
+    schema: HANDOFF_WORKSPACE_BYTE_PROVIDER_SCHEMA_ID,
+    status: workspaces.length && workspaces.every((workspace) => workspace.state === 'qualified') ? 'ready' : 'blocked',
+    workspaces: Object.freeze(workspaces),
+    findings: Object.freeze([]),
+    boundary: 'Manufacture-local projection provider only. It reuses already exact-qualified source bytes solely to construct the disposable carrier projection; serialized-byte closure verification independently reconstructs the authoritative archive provider.'
+  });
+}
+
+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.archiveV2.workspace.js

@@ -0,0 +1,226 @@
+import { packageFileByteView, packageFileBytes, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+import { normalizeHandoffWorkspaceInnerPath } from './workspaceByteProvider.js';
+import { qualifyHandoffWorkspaceTarget } from './workspaceTargetConformance.js';
+
+export function qualifyWorkspaceForArchive(workspace = {}, byPath = new Map(), targetDeclarations = [], parentCandidates = []) {
+  const findings = [];
+  const workspaceId = String(workspace.id || '');
+  if (!workspaceId) findings.push(finding('error', 'portable.handoff-v2.workspace.id.unresolved', 'Archive-backed workspace binding requires an exact carrier workspace id.'));
+  const coverage = workspaceCoverage(workspace);
+  const evidence = workspaceEvidence(workspace, coverage);
+  if (!coverage || String(workspace.qualification || '') !== 'qualified' || String(workspace.correlationStatus || '') !== 'qualified' || String(evidence.state || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-v2.workspace.coverage.unqualified', 'Archive-backed workspace representation requires explicit qualified complete or bounded entry-set evidence.', { workspaceId, coverage }));
+  if (targetDeclarations.length !== 1) {
+    findings.push(finding('error', targetDeclarations.length > 1 ? 'portable.handoff-v2.workspace-target.ambiguous' : 'portable.handoff-v2.workspace-target.missing', targetDeclarations.length > 1 ? 'More than one explicit Workspace target was declared for the carrier workspace id; v2 refuses ambiguous semantic binding.' : 'No explicit exact Workspace artifact target was declared for the carrier workspace id; v2 refuses filename/content scanning or transport-only semantic Workspace identity.', { workspaceId, targetCount: targetDeclarations.length }));
+    return blocked(workspaceId, findings);
+  }
+  const targetNormalized = normalizeHandoffWorkspaceInnerPath(targetDeclarations[0].path || '');
+  if (targetNormalized.state !== 'qualified') {
+    findings.push(finding('error', `portable.handoff-v2.${targetNormalized.reason || 'workspace-target-path-unsafe'}`, 'Explicit Workspace target locator is not a safe normalized workspace-relative path.', { workspaceId, path: targetDeclarations[0].path || '' }));
+    return blocked(workspaceId, findings);
+  }
+  if (!/\.workspace\.md$/i.test(targetNormalized.path)) {
+    findings.push(finding('error', 'portable.handoff-v2.workspace-target.path-contract-mismatch', 'Explicit Workspace target must identify a .workspace.md artifact under the tiinex.workspace.v1 artifact contract; schema-material filenames do not qualify as Workspace instances.', { workspaceId, path: targetNormalized.path }));
+    return blocked(workspaceId, findings);
+  }
+
+  const entries = qualifyWorkspaceEntries(workspace, byPath, workspaceId, findings);
+  const evidenceFingerprint = sha256Hex(utf8Bytes(stableJson(entries.map(projectEntryIdentity))));
+  if (String(evidence.entriesFingerprint || '') !== evidenceFingerprint || Number(evidence.entryCount || -1) !== entries.length || Number(evidence.totalBytes || -1) !== entries.reduce((sum, entry) => sum + entry.bytes, 0)) findings.push(finding('error', `portable.handoff-v2.workspace.${coverage}-evidence.stale`, 'Workspace coverage evidence does not exactly cover the archive entry set.', { workspaceId, coverage }));
+
+  const targetEntry = entries.find((entry) => entry.path === targetNormalized.path) || null;
+  if (!targetEntry) findings.push(finding('error', 'portable.handoff-v2.workspace-target.unresolvable', 'Explicit Workspace target is not present exactly once in the qualified Workspace Representation entry set.', { workspaceId, path: targetNormalized.path }));
+  const targetQualification = targetEntry ? qualifyHandoffWorkspaceTarget({ targetPath: targetNormalized.path, targetData: targetEntry.data, entries, parentCandidates }) : null;
+  if (targetQualification?.state !== 'qualified') {
+    for (const reason of targetQualification?.reasons || ['workspace-target-artifact-conformance-unqualified']) findings.push(workspaceTargetFinding(reason, workspaceId, targetNormalized.path));
+  }
+  const target = targetEntry && targetQualification?.state === 'qualified'
+    ? Object.freeze({ ...targetEntry, selfIntegrity: targetQualification.selfIntegrity, conformance: targetQualification.conformance })
+    : null;
+  return deepFreeze({ status: findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified', workspaceId, entries: Object.freeze(entries), target, findings: Object.freeze(findings) });
+}
+
+
+export function qualifyDirectWorkspaceForArchive(workspace = {}, rawWorkspace = null, targetDeclarations = [], parentCandidates = []) {
+  const findings = [];
+  const workspaceId = String(workspace.id || '');
+  if (!workspaceId) findings.push(finding('error', 'portable.handoff-v2.workspace.id.unresolved', 'Archive-backed workspace binding requires an exact carrier workspace id.'));
+  if (!rawWorkspace || typeof rawWorkspace !== 'object') {
+    findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.unavailable', 'Direct archive-backed manufacture requires the exact already-qualified workspace materialization bytes correlated to this closure workspace.', { workspaceId }));
+    return blocked(workspaceId, findings);
+  }
+  const coverage = workspaceCoverage(workspace);
+  const evidence = workspaceEvidence(workspace, coverage);
+  if (!coverage || String(workspace.qualification || '') !== 'qualified' || String(workspace.correlationStatus || '') !== 'qualified' || String(evidence.state || '') !== 'qualified') {
+    findings.push(finding('error', 'portable.handoff-v2.workspace.coverage.unqualified', 'Archive-backed workspace representation requires explicit qualified complete or bounded entry-set evidence.', { workspaceId, coverage }));
+  }
+  if (targetDeclarations.length !== 1) {
+    findings.push(finding('error', targetDeclarations.length > 1 ? 'portable.handoff-v2.workspace-target.ambiguous' : 'portable.handoff-v2.workspace-target.missing', targetDeclarations.length > 1 ? 'More than one explicit Workspace target was declared for the carrier workspace id; v2 refuses ambiguous semantic binding.' : 'No explicit exact Workspace artifact target was declared for the carrier workspace id; v2 refuses filename/content scanning or transport-only semantic Workspace identity.', { workspaceId, targetCount: targetDeclarations.length }));
+    return blocked(workspaceId, findings);
+  }
+  const targetNormalized = normalizeHandoffWorkspaceInnerPath(targetDeclarations[0].path || '');
+  if (targetNormalized.state !== 'qualified') {
+    findings.push(finding('error', `portable.handoff-v2.${targetNormalized.reason || 'workspace-target-path-unsafe'}`, 'Explicit Workspace target locator is not a safe normalized workspace-relative path.', { workspaceId, path: targetDeclarations[0].path || '' }));
+    return blocked(workspaceId, findings);
+  }
+  if (!/\.workspace\.md$/i.test(targetNormalized.path)) {
+    findings.push(finding('error', 'portable.handoff-v2.workspace-target.path-contract-mismatch', 'Explicit Workspace target must identify a .workspace.md artifact under the tiinex.workspace.v1 artifact contract; schema-material filenames do not qualify as Workspace instances.', { workspaceId, path: targetNormalized.path }));
+    return blocked(workspaceId, findings);
+  }
+
+  const rawEvidence = workspaceEvidence(rawWorkspace, coverage);
+  const declaredEvidence = evidence;
+  const evidenceMatches = workspaceCoverage(rawWorkspace) === coverage
+    && String(rawEvidence.state || '') === 'qualified'
+    && String(rawEvidence.entriesFingerprint || '') === String(declaredEvidence.entriesFingerprint || '')
+    && Number(rawEvidence.entryCount ?? -1) === Number(declaredEvidence.entryCount ?? -2)
+    && Number(rawEvidence.totalBytes ?? -1) === Number(declaredEvidence.totalBytes ?? -2);
+  if (!evidenceMatches) findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.coverage-evidence-mismatch', 'Direct Workspace source does not carry the same qualified complete-or-bounded evidence as the correlated closure Workspace.', { workspaceId, coverage }));
+
+  const declaredByPath = new Map();
+  for (const declared of workspace.includedEntries || []) {
+    const normalized = normalizeHandoffWorkspaceInnerPath(declared.path || '');
+    if (normalized.state !== 'qualified') {
+      findings.push(finding('error', `portable.handoff-v2.${normalized.reason || 'workspace-inner-path-unsafe'}`, 'Qualified Workspace Representation declaration contains an unsafe path.', { workspaceId, path: declared.path || '' }));
+      continue;
+    }
+    if (declaredByPath.has(normalized.path)) {
+      findings.push(finding('error', 'portable.handoff-v2.workspace-inner-path-duplicate', 'Qualified Workspace Representation declaration contains duplicate normalized inner paths.', { workspaceId, path: normalized.path }));
+      continue;
+    }
+    declaredByPath.set(normalized.path, Object.freeze({ ...declared, path: normalized.path }));
+  }
+
+  const rawByPath = new Map();
+  for (const raw of rawWorkspace.entries || []) {
+    const normalized = normalizeHandoffWorkspaceInnerPath(raw.path || '');
+    if (normalized.state !== 'qualified') {
+      findings.push(finding('error', `portable.handoff-v2.${normalized.reason || 'workspace-inner-path-unsafe'}`, 'Direct workspace source contains an unsafe path that cannot enter an archive-backed provider.', { workspaceId, path: raw.path || '' }));
+      continue;
+    }
+    if (rawByPath.has(normalized.path)) {
+      findings.push(finding('error', 'portable.handoff-v2.workspace-inner-path-duplicate', 'Direct workspace source contains duplicate normalized inner paths.', { workspaceId, path: normalized.path }));
+      continue;
+    }
+    const data = packageFileByteView(raw);
+    const bytes = data.byteLength;
+    const declaredBytes = Number(raw.bytes ?? -1);
+    const sha256 = String(raw.sha256 || '');
+    if (declaredBytes !== bytes || !/^[0-9a-f]{64}$/i.test(sha256)) {
+      findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.identity-unqualified', 'Direct Workspace source entry lacks the exact prequalified byte identity produced by Workspace enumeration.', { workspaceId, path: normalized.path }));
+    }
+    rawByPath.set(normalized.path, Object.freeze({ path: normalized.path, data, bytes, sha256, referenceTarget: String(raw.referenceTarget || '') }));
+  }
+
+  const entries = [];
+  for (const [declaredPath, declared] of declaredByPath) {
+    const raw = rawByPath.get(declaredPath);
+    if (!raw) {
+      findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.entry-missing', 'Qualified Workspace Representation declaration is missing from the direct source byte set.', { workspaceId, path: declaredPath }));
+      continue;
+    }
+    if (Number(declared.bytes || 0) !== raw.bytes || String(declared.sha256 || '') !== raw.sha256) {
+      findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.identity-mismatch', 'Direct workspace source prequalified byte identity diverges from the qualified complete-workspace declaration.', { workspaceId, path: declaredPath }));
+    }
+    entries.push(Object.freeze({ path: declaredPath, packagePath: '', bytes: raw.bytes, sha256: raw.sha256, referenceTarget: String(declared.referenceTarget || ''), data: raw.data }));
+  }
+  for (const rawPath of rawByPath.keys()) {
+    if (!declaredByPath.has(rawPath)) findings.push(finding('error', 'portable.handoff-v2.workspace-direct-source.entry-extra', 'Direct workspace source contains bytes outside the qualified complete-workspace declaration.', { workspaceId, path: rawPath }));
+  }
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+
+  const evidenceFingerprint = sha256Hex(utf8Bytes(stableJson(entries.map(projectEntryIdentity))));
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+  if (String(declaredEvidence.entriesFingerprint || '') !== evidenceFingerprint || Number(declaredEvidence.entryCount ?? -1) !== entries.length || Number(declaredEvidence.totalBytes ?? -1) !== totalBytes) {
+    findings.push(finding('error', `portable.handoff-v2.workspace.${coverage}-evidence.stale`, 'Workspace coverage evidence does not exactly cover the direct archive entry identity set.', { workspaceId, coverage }));
+  }
+
+  const targetEntry = entries.find((entry) => entry.path === targetNormalized.path) || null;
+  if (!targetEntry) findings.push(finding('error', 'portable.handoff-v2.workspace-target.unresolvable', 'Explicit Workspace target is not present exactly once in the qualified Workspace Representation entry set.', { workspaceId, path: targetNormalized.path }));
+  const targetQualification = targetEntry ? qualifyHandoffWorkspaceTarget({ targetPath: targetNormalized.path, targetData: targetEntry.data, entries, parentCandidates }) : null;
+  if (targetQualification?.state !== 'qualified') {
+    for (const reason of targetQualification?.reasons || ['workspace-target-artifact-conformance-unqualified']) findings.push(workspaceTargetFinding(reason, workspaceId, targetNormalized.path));
+  }
+  const target = targetEntry && targetQualification?.state === 'qualified'
+    ? Object.freeze({ ...targetEntry, selfIntegrity: targetQualification.selfIntegrity, conformance: targetQualification.conformance })
+    : null;
+  return deepFreeze({ status: findings.some((item) => item.severity === 'error') ? 'blocked' : 'qualified', workspaceId, entries: Object.freeze(entries), target, findings: Object.freeze(findings) });
+}
+
+function workspaceCoverage(workspace = {}) {
+  const value = String(workspace.materialization || workspace.state || '');
+  return value === 'complete' || value === 'bounded' ? value : '';
+}
+function workspaceEvidence(workspace = {}, coverage = workspaceCoverage(workspace)) {
+  return coverage === 'bounded' ? (workspace.scopeEvidence || {}) : coverage === 'complete' ? (workspace.completenessEvidence || {}) : {};
+}
+
+function safeToken(value = '') { return String(value || '').trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || 'workspace'; }
+
+export function indexWorkspaceTargetDeclarations(value = []) {
+  const map = new Map();
+  const items = Array.isArray(value) ? value : (value && typeof value === 'object' ? Object.entries(value).map(([workspaceId, path]) => ({ workspaceId, path: typeof path === 'string' ? path : path?.path })) : []);
+  for (const item of items) {
+    const workspaceId = String(item?.workspaceId || item?.workspace || item?.id || '').trim();
+    const path = String(item?.path || item?.workspaceTargetPath || item?.workspaceArtifactPath || '').trim();
+    if (!workspaceId || !path) continue;
+    const list = map.get(workspaceId) || [];
+    list.push(Object.freeze({ workspaceId, path }));
+    map.set(workspaceId, list);
+  }
+  return map;
+}
+
+export function mapArchiveRequirements(requirements = {}, materialized = [], bindingByWorkspace = new Map()) {
+  const carrierByRequirement = new Map(materialized.map((entry) => [String(entry.requirementId || ''), entry]));
+  const mapOne = (item) => {
+    const carrier = carrierByRequirement.get(String(item.requirementId || ''));
+    if (!carrier || carrier.carrierKind !== 'workspace-archive-entry') return item;
+    const binding = bindingByWorkspace.get(carrier.workspaceId);
+    return deepFreeze({ ...item, materializedPackagePath: String(binding?.representation?.packagePath || ''), materializedCarrier: Object.freeze({ kind: 'workspace-archive-entry', workspaceId: carrier.workspaceId, workspaceRelativePath: carrier.workspaceRelativePath, archivePackagePath: String(binding?.representation?.packagePath || '') }) });
+  };
+  return Object.freeze({
+    required: Object.freeze((requirements.required || []).map(mapOne)),
+    reference: Object.freeze((requirements.reference || []).map(mapOne)),
+    endpointRoles: Object.freeze((requirements.endpointRoles || []).map(mapOne)),
+    participantRoles: Object.freeze((requirements.participantRoles || []).map(mapOne)),
+    dependencies: Object.freeze((requirements.dependencies || []).map(mapOne))
+  });
+}
+
+function qualifyWorkspaceEntries(workspace, byPath, workspaceId, findings) {
+  const entries = [];
+  const seen = new Set();
+  for (const declared of workspace.includedEntries || []) {
+    const normalized = normalizeHandoffWorkspaceInnerPath(declared.path || '');
+    if (normalized.state !== 'qualified') { findings.push(finding('error', `portable.handoff-v2.${normalized.reason || 'workspace-inner-path-unsafe'}`, 'Workspace contains an unsafe path that cannot enter an archive-backed provider.', { workspaceId, path: declared.path || '' })); continue; }
+    if (seen.has(normalized.path)) { findings.push(finding('error', 'portable.handoff-v2.workspace-inner-path-duplicate', 'Workspace contains duplicate normalized inner paths.', { workspaceId, path: normalized.path })); continue; }
+    seen.add(normalized.path);
+    const packagePath = String(declared.packagePath || '');
+    const matches = byPath.get(packagePath) || [];
+    const file = matches.length === 1 ? matches[0] : null;
+    if (!file) { findings.push(finding('error', 'portable.handoff-v2.workspace-entry.unresolvable', 'Qualified v1 workspace entry is not uniquely resolvable to exact package bytes.', { workspaceId, path: normalized.path, packagePath })); continue; }
+    const data = packageFileBytes(file);
+    const sha256 = sha256Hex(data);
+    if (Number(declared.bytes || 0) !== data.byteLength || String(declared.sha256 || '') !== sha256) findings.push(finding('error', 'portable.handoff-v2.workspace-entry.identity-mismatch', 'Workspace entry byte identity diverges from the v1 closure declaration.', { workspaceId, path: normalized.path }));
+    entries.push(Object.freeze({ path: normalized.path, packagePath, bytes: data.byteLength, sha256, referenceTarget: String(declared.referenceTarget || ''), data }));
+  }
+  return entries.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function projectEntryIdentity(entry) { return { path: entry.path, bytes: entry.bytes, sha256: entry.sha256, referenceTarget: entry.referenceTarget }; }
+function workspaceTargetFinding(reason, workspaceId, path) {
+  const code = `portable.handoff-v2.${String(reason || 'workspace-target-artifact-conformance-unqualified')}`;
+  const messages = {
+    'workspace-target-schema-unqualified': 'Explicit Workspace target does not qualify as tiinex.workspace.v1 under exact registered schema authority.',
+    'workspace-target-self-integrity-unverified': 'Explicit Workspace target does not have verified primary c14n-v2 self integrity.',
+    'workspace-target-self-integrity-mismatch': 'Explicit Workspace target primary c14n-v2 self integrity does not match its exact bytes.',
+    'workspace-target-parent-continuity-unqualified': 'Explicit Workspace target declares Parent but its Parent-target continuity cannot be independently verified.',
+    'workspace-target-artifact-conformance-unqualified': 'Explicit Workspace target fails Root/registered-schema/integrity artifact conformance.'
+  };
+  return finding('error', code, messages[reason] || messages['workspace-target-artifact-conformance-unqualified'], { workspaceId, path });
+}
+function blocked(workspaceId, findings) { return deepFreeze({ status: 'blocked', workspaceId, entries: Object.freeze([]), target: null, findings: Object.freeze(findings) }); }
+function stableJson(value) { return JSON.stringify(sortJson(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])])); }
+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.descriptor.js

@@ -0,0 +1,169 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { qualifyHandoffMaterialClosurePlanReadiness } from './materialClosure.readiness.js';
+import { buildHandoffWorkspaceByteProvider, resolveHandoffWorkspaceEntry } from './workspaceByteProvider.js';
+
+export const HANDOFF_CLOSURE_DESCRIPTOR_SCHEMA_ID = 'tiinex.transport.handoff-material-closure-descriptor.v1';
+export const HANDOFF_CLOSURE_DESCRIPTOR_V2_SCHEMA_ID = 'tiinex.transport.handoff-material-closure-descriptor.v2';
+export const HANDOFF_CLOSURE_DESCRIPTOR_PATH = 'tiinex.package/handoff-closure.json';
+
+export function buildHandoffClosureDescriptor(plan = {}, packageMaterial = {}) {
+  const materialized = (packageMaterial.materialized || []).map((entry) => descriptorMaterial(entry));
+  const packagedWorkspaceByCorrelation = indexPackagedWorkspaces(packageMaterial.workspaces || []);
+  const workspaces = (plan.workspaceMaterializations || []).map((workspace) => {
+    const packagedResolution = resolvePackagedWorkspace(packagedWorkspaceByCorrelation, workspace.transportCorrelationKey);
+    const packaged = packagedResolution.workspace || {};
+    const correlationStatus = packagedResolution.status === 'qualified' ? String(packaged.correlationStatus || 'unresolved') : packagedResolution.status;
+    const entries = correlationStatus === 'qualified' && (packaged.entries || []).length ? packaged.entries : workspace.includedEntries;
+    return Object.freeze({
+      id: workspace.id,
+      title: String(workspace.title || workspace.id || ''),
+      source: workspace.source,
+      materialization: workspace.materialization,
+      qualification: workspace.qualification,
+      completenessEvidence: workspace.completenessEvidence,
+      scopeEvidence: workspace.scopeEvidence || Object.freeze({}),
+      transportCorrelationKey: String(workspace.transportCorrelationKey || ''),
+      correlationStatus,
+      includedEntries: entries
+    });
+  });
+  return deepFreeze({
+    schema: HANDOFF_CLOSURE_DESCRIPTOR_SCHEMA_ID,
+    version: 1,
+    boundary: 'Disposable recipient-relative transport metadata. Safe to delete with the package; not a Tiinex artifact, semantic Parent, workspace owner, package identity, Handoff acceptance/completion state, or provider authority.',
+    handoff: Object.freeze({ id: String(plan.handoff?.id || ''), path: String(plan.handoff?.path || ''), reference: String(plan.handoff?.reference || ''), semanticStatus: String(plan.semanticHandoffStatus || 'unknown') }),
+    plan: Object.freeze({ status: String(plan.status || 'blocked'), requiredClosureReady: Boolean(plan.requiredClosureReady), localRunId: String(packageMaterial.localRunId || ''), inputBindingState: String(packageMaterial.planInputBinding?.state || 'unresolved'), inputBindingMode: String(packageMaterial.planInputBinding?.mode || 'unknown'), inputBindingFindings: Object.freeze([...(packageMaterial.planInputBinding?.findings || [])]), materializedOutputState: String(packageMaterial.materializedOutputQualification?.state || 'unresolved'), materializedOutputFindings: Object.freeze([...(packageMaterial.materializedOutputQualification?.findings || [])]) }),
+    requirements: Object.freeze({
+      required: Object.freeze((plan.requirements?.required || []).map(descriptorRequirement)),
+      reference: Object.freeze((plan.requirements?.reference || []).map(descriptorRequirement)),
+      endpointRoles: Object.freeze((plan.requirements?.endpointRoles || []).map(descriptorRequirement)),
+      participantRoles: Object.freeze((plan.requirements?.participantRoles || []).map(descriptorRequirement)),
+      dependencies: Object.freeze((plan.requirements?.dependencies || []).map(descriptorRequirement))
+    }),
+    materialized: Object.freeze(materialized),
+    workspaceMaterializations: Object.freeze(workspaces),
+    bootstrap: Object.freeze({ status: String(plan.bootstrap?.status || 'absent'), packagePath: String(packageMaterial.bootstrapPath || ''), boundary: String(plan.bootstrap?.boundary || '') }),
+    providerProvenance: Object.freeze(materialized.map((entry) => Object.freeze({ requirementId: entry.requirementId, provider: entry.provider, provenance: entry.provenance }))),
+    roundtripVerification: Object.freeze({
+      state: 'build-verified',
+      verifier: 'durable-file-map-plus-independent-archive-rehydration-required',
+      descriptorPath: HANDOFF_CLOSURE_DESCRIPTOR_PATH,
+      expectedMaterial: Object.freeze([
+        ...materialized.map((entry) => Object.freeze({ packagePath: entry.packagePath, bytes: entry.bytes, sha256: entry.sha256 })),
+        ...workspaces.flatMap((workspace) => (workspace.includedEntries || []).filter((entry) => entry.packagePath).map((entry) => Object.freeze({ packagePath: entry.packagePath, bytes: entry.bytes, sha256: entry.sha256 })))
+      ]),
+      note: 'Build evidence proves descriptor/material byte identities before archive serialization. Independent archive extraction/rehydration must verify the same governed bytes; descriptor presence does not prove delivery or Handoff acceptance.'
+    })
+  });
+}
+
+export function inspectHandoffClosureDescriptor(bundle = {}, options = {}) {
+  const findings = [];
+  const descriptorFile = (bundle.files || []).find((file) => String(file.path || '') === HANDOFF_CLOSURE_DESCRIPTOR_PATH);
+  const descriptor = descriptorFile ? parseJsonFile(descriptorFile) : null;
+  if (!descriptor) findings.push(finding('error', 'portable.handoff-closure.descriptor.missing', 'Handoff transport package is missing a readable package-local closure descriptor.'));
+  const supportedSchema = descriptor && [HANDOFF_CLOSURE_DESCRIPTOR_SCHEMA_ID, HANDOFF_CLOSURE_DESCRIPTOR_V2_SCHEMA_ID].includes(String(descriptor.schema || ''));
+  if (descriptor && !supportedSchema) findings.push(finding('error', 'portable.handoff-closure.descriptor.schema.invalid', 'Handoff closure descriptor schema/version is unsupported.'));
+  const isV2 = String(descriptor?.schema || '') === HANDOFF_CLOSURE_DESCRIPTOR_V2_SCHEMA_ID;
+  const byPath = new Map((bundle.files || []).map((file) => [String(file.path || ''), file]));
+  const suppliedProvider = options.workspaceByteProvider || (options.schema === 'tiinex.portable.handoff-workspace-byte-provider.v1' ? options : null);
+  const byteProvider = descriptor ? (suppliedProvider || buildHandoffWorkspaceByteProvider(bundle, descriptor)) : null;
+  if (isV2 && byteProvider?.status !== 'ready') findings.push(...(byteProvider?.findings || []));
+
+  for (const entry of descriptor?.materialized || []) {
+    if (String(entry.carrierKind || '') === 'workspace-archive-entry') {
+      const resolved = resolveHandoffWorkspaceEntry(byteProvider || {}, entry.workspaceId, entry.workspaceRelativePath);
+      if (resolved.state !== 'qualified') { findings.push(finding('error', 'portable.handoff-closure.material.workspace-provider-unqualified', 'Descriptor materialized entry cannot be resolved through its qualified workspace archive provider.', { requirementId: entry.requirementId || '', workspaceId: entry.workspaceId || '', workspaceRelativePath: entry.workspaceRelativePath || '', reason: resolved.reason || resolved.state })); continue; }
+      const data = packageFileBytes({ data: resolved.data });
+      if (Number(entry.bytes || 0) !== data.byteLength) findings.push(finding('error', 'portable.handoff-closure.material.bytes-mismatch', 'Descriptor materialized entry byte length differs from workspace-provider bytes.', { requirementId: entry.requirementId || '', workspaceId: entry.workspaceId || '', workspaceRelativePath: entry.workspaceRelativePath || '' }));
+      if (String(entry.sha256 || '') !== sha256Hex(data)) findings.push(finding('error', 'portable.handoff-closure.material.sha256-mismatch', 'Descriptor materialized entry digest differs from workspace-provider bytes.', { requirementId: entry.requirementId || '', workspaceId: entry.workspaceId || '', workspaceRelativePath: entry.workspaceRelativePath || '' }));
+      continue;
+    }
+    const file = byPath.get(String(entry.packagePath || ''));
+    if (!file) { findings.push(finding('error', 'portable.handoff-closure.material.missing', 'Descriptor materialized entry is missing from package bytes.', { requirementId: entry.requirementId || '', packagePath: entry.packagePath || '' })); continue; }
+    const data = packageFileBytes(file);
+    if (Number(entry.bytes || 0) !== data.byteLength) findings.push(finding('error', 'portable.handoff-closure.material.bytes-mismatch', 'Descriptor materialized entry byte length differs from package bytes.', { packagePath: entry.packagePath || '' }));
+    if (String(entry.sha256 || '') !== sha256Hex(data)) findings.push(finding('error', 'portable.handoff-closure.material.sha256-mismatch', 'Descriptor materialized entry digest differs from package bytes.', { packagePath: entry.packagePath || '' }));
+  }
+  for (const workspace of descriptor?.workspaceMaterializations || []) {
+    if (String(workspace.correlationStatus || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-closure.workspace-correlation.unqualified', 'Descriptor workspace materialization is not uniquely correlated to one packaged workspace byte carrier.', { workspaceId: workspace.id || '', correlationStatus: workspace.correlationStatus || 'unresolved' }));
+    if (isV2) continue;
+    for (const entry of workspace.includedEntries || []) {
+      if (!entry.packagePath) continue;
+      const file = byPath.get(String(entry.packagePath || ''));
+      if (!file) { findings.push(finding('error', 'portable.handoff-closure.workspace-material.missing', 'Descriptor workspace material entry is missing from package bytes.', { workspaceId: workspace.id || '', packagePath: entry.packagePath || '' })); continue; }
+      const data = packageFileBytes(file);
+      if (Number(entry.bytes || 0) !== data.byteLength) findings.push(finding('error', 'portable.handoff-closure.workspace-material.bytes-mismatch', 'Descriptor workspace material entry byte length differs from package bytes.', { workspaceId: workspace.id || '', packagePath: entry.packagePath || '' }));
+      if (String(entry.sha256 || '') !== sha256Hex(data)) findings.push(finding('error', 'portable.handoff-closure.workspace-material.sha256-mismatch', 'Descriptor workspace material entry digest differs from package bytes.', { workspaceId: workspace.id || '', packagePath: entry.packagePath || '' }));
+    }
+  }
+  if (descriptor?.bootstrap?.status === 'present' && !byPath.has(String(descriptor.bootstrap.packagePath || ''))) findings.push(finding('error', 'portable.handoff-closure.bootstrap.missing', 'Descriptor declares bootstrap present but the package-local bootstrap file is missing.', { packagePath: descriptor.bootstrap.packagePath || '' }));
+  const readinessQualification = descriptor ? qualifyHandoffMaterialClosurePlanReadiness({
+    status: descriptor.plan?.status,
+    requiredClosureReady: descriptor.plan?.requiredClosureReady,
+    requirements: descriptor.requirements,
+    workspaceMaterializations: descriptor.workspaceMaterializations
+  }) : null;
+  if (readinessQualification?.findings.includes('required-closure-ready-contradictory')) findings.push(finding('error', 'portable.handoff-closure.readiness.inconsistent', 'Descriptor required closure readiness conflicts with blocking required-material or workspace-materialization truth.'));
+  if (readinessQualification?.findings.includes('plan-status-contradictory')) findings.push(finding('error', 'portable.handoff-closure.plan-status.inconsistent', 'Descriptor plan status conflicts with blocking required-material or workspace-materialization truth.'));
+  if (descriptor && String(descriptor.plan?.inputBindingState || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-closure.plan-input-binding.unqualified', 'Descriptor plan is not qualified against the current parallel Handoff/recipient planning inputs.', { mode: descriptor.plan?.inputBindingMode || 'unknown', inputBindingFindings: descriptor.plan?.inputBindingFindings || [] }));
+  if (descriptor && String(descriptor.plan?.materializedOutputState || '') !== 'qualified') findings.push(finding('error', 'portable.handoff-closure.materialized-output.unqualified', 'Descriptor plan materialized output is not qualified against its own selected material-resolution truth.', { materializedOutputFindings: descriptor.plan?.materializedOutputFindings || [] }));
+  inspectRequirementMaterialCorrespondence(descriptor, findings);
+  return deepFreeze({ schema: 'tiinex.transport.handoff-material-closure-descriptor.inspection.v1', status: findings.some((item) => item.severity === 'error') ? 'invalid' : 'valid', descriptor, findings: Object.freeze(dedupeFindings(findings)), ...(isV2 ? { workspaceByteProvider: byteProvider } : {}) });
+}
+
+
+function indexPackagedWorkspaces(items = []) {
+  const index = new Map();
+  for (const workspace of items) {
+    const key = String(workspace?.transportCorrelationKey || '');
+    if (!key) continue;
+    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 resolvePackagedWorkspace(index, key = '') {
+  if (!key) return Object.freeze({ status: 'unresolved', workspace: null });
+  return index.get(String(key || '')) || Object.freeze({ status: 'unresolved', workspace: null });
+}
+
+
+function descriptorRequirement(item = {}) {
+  return Object.freeze({ requirementId: String(item.requirementId || ''), name: String(item.requirementName || item.name || ''), classification: String(item.classification || ''), disposition: String(item.disposition || ''), referenceTarget: String(item.referenceTarget || ''), reason: String(item.reason || ''), recipientReferenceCapability: Boolean(item.recipientReferenceCapability), routeWorkspaceId: String(item.routeWorkspaceId || ''), routePath: String(item.routePath || ''), sourceRequirementId: String(item.sourceRequirementId || ''), materializedPackagePath: String(item.packagePath || item.selectedMaterial?.packagePath || ''), selectedMaterial: descriptorSelectedMaterial(item.selectedMaterial) });
+}
+function descriptorSelectedMaterial(material = null) {
+  if (!material) return null;
+  return Object.freeze({ path: String(material.path || ''), requestedPackagePath: String(material.packagePath || ''), bytes: Number(material.bytes || 0), sha256: String(material.sha256 || ''), mediaType: String(material.mediaType || ''), provider: material.provider || {}, provenance: material.provenance || {}, authority: material.authority || {} });
+}
+function inspectRequirementMaterialCorrespondence(descriptor, findings) {
+  if (!descriptor) return;
+  const requirements = [...(descriptor.requirements?.required || []), ...(descriptor.requirements?.reference || []), ...(descriptor.requirements?.endpointRoles || []), ...(descriptor.requirements?.participantRoles || []), ...(descriptor.requirements?.dependencies || [])];
+  const materialized = descriptor.materialized || [];
+  const byRequirement = new Map();
+  for (const carrier of materialized) {
+    const id = String(carrier.requirementId || '');
+    const list = byRequirement.get(id) || []; list.push(carrier); byRequirement.set(id, list);
+  }
+  const expectedIds = new Set();
+  for (const requirement of requirements) {
+    if (String(requirement.disposition || '') !== 'materialized') continue;
+    const id = String(requirement.requirementId || ''); expectedIds.add(id);
+    const carriers = byRequirement.get(id) || [];
+    if (carriers.length === 0) { findings.push(finding('error', 'portable.handoff-closure.materialized-output.required-carrier-missing', 'A materialized requirement has no exact packaged carrier.', { requirementId: id })); continue; }
+    if (carriers.length !== 1) { findings.push(finding('error', 'portable.handoff-closure.materialized-output.required-carrier-ambiguous', 'A materialized requirement has multiple packaged carriers without output-selection authority.', { requirementId: id, count: carriers.length })); continue; }
+    const selected = requirement.selectedMaterial || {}; const carrier = carriers[0];
+    if (!selected.sha256 || Number(selected.bytes || 0) <= 0) findings.push(finding('error', 'portable.handoff-closure.materialized-output.selected-material-unqualified', 'Materialized requirement lacks exact selected-material byte identity.', { requirementId: id }));
+    if (String(carrier.sha256 || '') !== String(selected.sha256 || '') || Number(carrier.bytes || 0) !== Number(selected.bytes || 0) || String(carrier.classification || '') !== String(requirement.classification || '') || String(carrier.referenceTarget || '') !== String(requirement.referenceTarget || '')) findings.push(finding('error', 'portable.handoff-closure.materialized-output.carrier-mismatch', 'Packaged material carrier diverges from the requirement selected-material truth.', { requirementId: id }));
+  }
+  for (const carrier of materialized) if (!expectedIds.has(String(carrier.requirementId || ''))) findings.push(finding('error', 'portable.handoff-closure.materialized-output.unbound-carrier', 'Packaged material carrier is not bound to a requirement whose disposition is materialized.', { requirementId: carrier.requirementId || '', packagePath: carrier.packagePath || '' }));
+}
+
+function descriptorMaterial(entry = {}) {
+  return Object.freeze({ requirementId: String(entry.requirementId || ''), classification: String(entry.classification || ''), referenceTarget: String(entry.referenceTarget || ''), routeWorkspaceId: String(entry.routeWorkspaceId || ''), routePath: String(entry.routePath || ''), sourceRequirementId: String(entry.sourceRequirementId || ''), packagePath: String(entry.packagePath || ''), originalPath: String(entry.path || ''), bytes: Number(entry.bytes || 0), sha256: String(entry.sha256 || ''), mediaType: String(entry.mediaType || ''), provider: entry.provider || {}, provenance: entry.provenance || {}, authority: entry.authority || {}, ...(entry.carrierKind ? { carrierKind: String(entry.carrierKind), workspaceId: String(entry.workspaceId || ''), workspaceRelativePath: String(entry.workspaceRelativePath || '') } : {}) });
+}
+function parseJsonFile(file = {}) { try { return JSON.parse(new TextDecoder().decode(packageFileBytes(file))); } catch { return null; } }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function dedupeFindings(items = []) { const map = new Map(); for (const item of items) { const key = `${item.severity || ''}:${item.code || ''}:${item.workspaceId || ''}:${item.requirementId || ''}:${item.packagePath || ''}:${item.workspaceRelativePath || ''}`; if (!map.has(key)) map.set(key, item); } return [...map.values()]; }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }