@tiinex/core 0.1.1

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

@@ -0,0 +1,84 @@
+import { summarizePortableFindings } from '../findings.js';
+import { inspectPortableToolingBootstrap } from './toolingBootstrap.js';
+import { upgradeRecipientRelativeHandoffTransportPackageV2 } from './materialClosure.archiveV2.js';
+import { buildRecipientRelativeHandoffV2DirectBaseline } from './materialClosure.archiveV2.direct.js';
+import { qualifyMajorCarrierReadiness } from './carrierLineage.js';
+import { manufactureRecipientRelativeWorkspacePackage } from './workspaceCarrier.manufacture.js';
+
+export function manufactureRecipientRelativeHandoffPackage(input = {}, options = {}) {
+  if (String(input.carrierMode || '') === 'workspace') return manufactureRecipientRelativeWorkspacePackage(input, options);
+  const baseline = buildRecipientRelativeHandoffV2DirectBaseline(input, options);
+  const upgraded = upgradeRecipientRelativeHandoffTransportPackageV2(baseline, input, options);
+  const toolingBootstrapInspection = upgraded.inspection?.bootstrapInspection || inspectPortableToolingBootstrap(baseline.bundle || upgraded.bundle || {});
+  const majorReadiness = qualifyMajorCarrierReadiness({
+    ...input,
+    carrierProfile: input.carrierProfile || null
+  }, input.carrierLineage || upgraded.carrierProjection?.lineage || baseline.carrierProjection?.lineage || {});
+  const majorFindings = majorReadiness.state === 'blocked' ? [Object.freeze({ severity: 'error', code: 'portable.handoff-carrier-lineage.major.not-self-contained', message: 'Major Handoff carrier requires complete replacement-capable carried Workspace snapshots.' })] : [];
+  const findings = Object.freeze([
+    ...majorFindings,
+    ...(baseline.findings || []),
+    ...(upgraded.findings || []),
+    ...(upgraded.inspection?.findings || []),
+    ...(upgraded.closureInspection?.findings || []),
+    ...(upgraded.carrierInspection?.findings || []),
+    ...(upgraded.pointerEntrypointInspection?.findings || []),
+    ...(upgraded.coldConsumerEntrypointInspection?.findings || []),
+    ...(upgraded.companionInspection?.findings || []),
+    ...(upgraded.roundtrip?.findings || []),
+    ...(toolingBootstrapInspection?.findings || [])
+  ]);
+  const status = baseline.status !== 'blocked' && upgraded.status !== 'blocked' && toolingBootstrapInspection?.status === 'valid' && majorReadiness.state !== 'blocked' ? upgraded.status : 'blocked';
+  return Object.freeze({
+    schema: 'tiinex.portable.handoff-manufacturing.v2',
+    status,
+    executable: Boolean(baseline.executable) && status !== 'blocked',
+    transportExecutable: status !== 'blocked',
+    verification: Object.freeze({
+      baselineManufacture: String(baseline.status || 'unavailable'),
+      manufacturePath: 'direct-qualified-workspace-to-archive',
+      packageInspection: String(upgraded.inspection?.status || 'unavailable'),
+      closureInspection: String(upgraded.closureInspection?.status || 'unavailable'),
+      carrierInspection: String(upgraded.carrierInspection?.status || 'unavailable'),
+      selectedHandoffConformance: (upgraded.carrierProjection?.routes || []).length > 0 && (upgraded.carrierProjection?.routes || []).every((route) => route.conformance?.status === 'qualified') ? 'qualified' : 'blocked',
+      pointerEntrypointInspection: String(upgraded.pointerEntrypointInspection?.status || 'unavailable'),
+      coldConsumerEntrypointInspection: String(upgraded.coldConsumerEntrypointInspection?.status || 'unavailable'),
+      companionInspection: String(upgraded.companionInspection?.status || 'unavailable'),
+      roundtrip: upgraded.roundtrip ? String(upgraded.roundtrip.status || 'unknown') : 'not-requested',
+      toolingBootstrap: String(toolingBootstrapInspection?.status || 'unavailable')
+    }),
+    plan: baseline.plan,
+    bundle: upgraded.bundle || baseline.bundle,
+    descriptor: upgraded.descriptor || baseline.descriptor,
+    transportCompanion: upgraded.transportCompanion || baseline.transportCompanion,
+    inspection: upgraded.inspection || baseline.inspection,
+    closureInspection: upgraded.closureInspection || baseline.closureInspection,
+    carrierProjection: upgraded.carrierProjection || baseline.carrierProjection,
+    carrierInspection: upgraded.carrierInspection || baseline.carrierInspection,
+    pointerEntrypointProjection: upgraded.pointerEntrypointProjection || baseline.pointerEntrypointProjection,
+    pointerEntrypointInspection: upgraded.pointerEntrypointInspection || baseline.pointerEntrypointInspection,
+    coldConsumerProjection: upgraded.coldConsumerProjection || baseline.coldConsumerProjection,
+    coldConsumerEntrypointInspection: upgraded.coldConsumerEntrypointInspection || baseline.coldConsumerEntrypointInspection,
+    companionInspection: upgraded.companionInspection || baseline.companionInspection,
+    roundtrip: upgraded.roundtrip || null,
+    toolingBootstrap: input.toolingBootstrap || null,
+    manufacturingEvidence: input.manufacturingEvidence || null,
+    toolingBootstrapInspection,
+    carrierLineage: upgraded.carrierProjection?.lineage || baseline.carrierProjection?.lineage || input.carrierLineage || null,
+    majorReadiness,
+    operationBoundary: Object.freeze({
+      operationClass: 'local-handoff-package-manufacture',
+      inputScope: 'caller-provided-local-workspace-material-and-optional-parent-package',
+      localPackageConstruction: true,
+      sourceMutation: false,
+      remoteMutation: false,
+      physicalRoundtripVerification: upgraded.roundtrip ? String(upgraded.roundtrip.status || 'unknown') : 'not-requested',
+      hostBehaviorAuthority: 'none'
+    }),
+    migration: upgraded.migration || null,
+    baseline: Object.freeze({ schema: baseline.schema, status: baseline.status, packageRepresentationSha256: String(baseline.bundle?.packageRepresentationSha256 || ''), representation: 'semantic-control-plus-detached-material-without-exploded-workspace-carrier' }),
+    findings,
+    findingSummary: summarizePortableFindings(findings),
+    boundary: 'Canonical archive-backed Handoff manufacturing facade. It fails closed unless each carrier workspace is bound to one exact carried tiinex.workspace.v1 artifact and one independently verified complete workspace archive.'
+  });
+}

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

@@ -0,0 +1,72 @@
+import { packageFileBytes, sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+import {
+  HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID,
+  HANDOFF_WORKSPACE_ARCHIVE_CODEC,
+  HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND,
+  HANDOFF_WORKSPACE_INNER_PATH_NORMALIZATION,
+  normalizeHandoffWorkspaceInnerPath
+} from './workspaceByteProvider.js';
+
+export function buildWorkspaceArchiveBinding({ workspace = {}, qualified = {}, archiveFile = {}, targetFile = {}, coverage = '' } = {}) {
+  const materialization = coverage === 'bounded' || String(workspace.materialization || '') === 'bounded' ? 'bounded' : 'complete';
+  const evidence = materialization === 'bounded' ? (workspace.scopeEvidence || {}) : (workspace.completenessEvidence || {});
+  const entries = (qualified.entries || []).map((entry) => Object.freeze({ path: entry.path, bytes: entry.bytes, sha256: entry.sha256, referenceTarget: entry.referenceTarget }));
+  const entriesFingerprint = sha256Hex(utf8Bytes(stableJson(entries)));
+  const totalBytes = entries.reduce((sum, entry) => sum + Number(entry.bytes || 0), 0);
+  return deepFreeze({
+    schema: HANDOFF_WORKSPACE_ARCHIVE_BINDING_SCHEMA_ID,
+    version: 1,
+    workspaceId: String(workspace.id || ''),
+    transportCorrelationKey: String(workspace.transportCorrelationKey || ''),
+    workspaceTarget: Object.freeze({
+      packagePath: String(targetFile.path || ''),
+      innerPath: String(qualified.target?.path || ''),
+      bytes: Number(targetFile.bytes || 0),
+      sha256: String(targetFile.sha256 || ''),
+      schema: 'tiinex.workspace.v1',
+      selfIntegrity: Object.freeze({ state: String(qualified.target?.selfIntegrity?.state || ''), value: String(qualified.target?.selfIntegrity?.value || '') }),
+      locatorAuthority: false
+    }),
+    coverage: materialization,
+    representation: Object.freeze({
+      kind: materialization === 'bounded' ? 'bounded-workspace-snapshot' : 'complete-workspace-snapshot',
+      packagePath: String(archiveFile.path || ''),
+      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: materialization === 'complete' ? Object.freeze({ state: 'qualified', basis: 'exact-qualified-workspace-completeness-evidence-plus-complete-archive-entry-set', entryCount: entries.length, totalBytes, entriesFingerprint }) : Object.freeze({}),
+    scope: materialization === 'bounded' ? Object.freeze({ ...evidence, state: 'qualified', entryCount: entries.length, totalBytes, entriesFingerprint }) : Object.freeze({}),
+    selection: Object.freeze({ rule: materialization === 'bounded' ? 'explicit-binding-per-bounded-scope' : 'exactly-one-binding-per-workspace', representationArtifactAuthority: 'explicit-recipient-workspace-representation-link' }),
+    provider: Object.freeze({ kind: HANDOFF_WORKSPACE_ARCHIVE_PROVIDER_KIND, state: 'ready', addressing: 'qualified-workspace-id-plus-normalized-inner-path', fallback: 'none', materialization }),
+    authority: Object.freeze({ workspaceIdentity: 'exact-workspace-target-byte-identity', archiveIdentity: 'exact-archive-byte-digest', pathAuthority: false, adjacencyAuthority: false, orderingAuthority: false, priorProvenanceAuthority: false })
+  });
+}
+
+export function detachedParentCandidates(materialized = [], byPath = new Map()) {
+  const out = [];
+  const seen = new Set();
+  for (const material of materialized || []) {
+    const packagePath = String(material.packagePath || '');
+    const workspacePath = normalizedOrEmpty(material.provenance?.path || material.originalPath || material.path || '');
+    if (!packagePath || !workspacePath) continue;
+    const files = byPath.get(packagePath) || [];
+    if (files.length !== 1) continue;
+    const data = packageFileBytes(files[0]);
+    const sha256 = sha256Hex(data);
+    const key = `${workspacePath}\u0000${sha256}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(Object.freeze({ path: workspacePath, data, bytes: data.byteLength, sha256 }));
+  }
+  return Object.freeze(out);
+}
+
+function normalizedOrEmpty(value = '') { const normalized = normalizeHandoffWorkspaceInnerPath(value); return normalized.state === 'qualified' ? normalized.path : ''; }
+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 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.direct.js

@@ -0,0 +1,160 @@
+import { buildExportPackageBundle } 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 { planRecipientRelativeHandoffMaterialClosure, workspaceMaterializationCorrelationKey } from './materialClosure.plan.js';
+import { buildHandoffClosureDescriptor, HANDOFF_CLOSURE_DESCRIPTOR_PATH } from './materialClosure.descriptor.js';
+import { qualifyHandoffMaterialClosurePlanReadiness } from './materialClosure.readiness.js';
+import { qualifyHandoffMaterialClosurePlanInputBinding } from './materialClosure.inputBinding.js';
+import { qualifyHandoffMaterializedOutput } from './materialClosure.materialized.js';
+import { HANDOFF_CARRIER_PROJECTION_PATH } from './carrierProjection.js';
+import { HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH } from './coldConsumerEntrypoint.js';
+import { HANDOFF_POINTER_ENTRYPOINT_PREFIX } from './pointerEntrypoint.js';
+import { HANDOFF_TRANSPORT_COMPANION_PATH } from './transportCompanion.js';
+
+export const PORTABLE_HANDOFF_V2_DIRECT_BASELINE_SCHEMA_ID = 'tiinex.portable.handoff-v2-direct-baseline.v1';
+
+export function buildRecipientRelativeHandoffV2DirectBaseline(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 file = finalizeFile({
+      path: materialPackagePath(entry),
+      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 directWorkspaceSources = [];
+  const packagedWorkspaces = [];
+  const planByCorrelation = indexPlanWorkspaces(plan.workspaceMaterializations || []);
+  const rawCorrelationCounts = countRawCorrelations(input.workspaceMaterializations || []);
+  let workspaceCorrelationBlocked = false;
+  for (const rawWorkspace of input.workspaceMaterializations || []) {
+    const transportCorrelationKey = workspaceMaterializationCorrelationKey(rawWorkspace);
+    const matches = planByCorrelation.get(transportCorrelationKey) || [];
+    const rawCount = rawCorrelationCounts.get(transportCorrelationKey) || 0;
+    const qualifiedWorkspace = matches.length === 1 && rawCount === 1 ? matches[0] : null;
+    const correlationStatus = qualifiedWorkspace ? 'qualified' : (matches.length > 1 || rawCount > 1 ? 'ambiguous' : 'unresolved');
+    if (!qualifiedWorkspace) workspaceCorrelationBlocked = true;
+    const workspaceId = String(qualifiedWorkspace?.id || rawWorkspace.id || rawWorkspace.workspaceId || 'workspace');
+    packagedWorkspaces.push(Object.freeze({
+      id: workspaceId,
+      transportCorrelationKey,
+      correlationStatus,
+      entries: Object.freeze((qualifiedWorkspace?.includedEntries || []).map((entry) => Object.freeze({ ...entry })))
+    }));
+    directWorkspaceSources.push(Object.freeze({ workspaceId, transportCorrelationKey, correlationStatus, workspace: rawWorkspace }));
+  }
+  if ((plan.workspaceMaterializations || []).length !== packagedWorkspaces.length) workspaceCorrelationBlocked = true;
+
+  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 semanticReady = planReadiness.state === 'qualified' && planReadiness.expectedRequiredClosureReady && planInputBinding.state === 'qualified' && materializedOutputQualification.state === 'qualified' && baseBundle.status !== 'blocked' && !workspaceCorrelationBlocked && !bootstrapCarrierBlocked && !additionalTransportBlocked;
+  const status = semanticReady ? (baseBundle.status === 'degraded' ? 'degraded' : 'ready') : 'blocked';
+
+  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].map(finalizeFile);
+  const materialRepresentationSha256 = packageMaterialRepresentationSha256(baseGoverned);
+  const priorBuildReceipt = parseJsonFile((baseBundle.files || []).find((file) => String(file.path || '') === buildReceiptPath)) || {};
+  const buildReceipt = Object.freeze({ ...priorBuildReceipt, operation: 'archive-backed-handoff-carrier-v2-direct-baseline', materialRepresentationSha256, counts: Object.freeze({ ...(priorBuildReceipt.counts || {}), materialFiles: baseGoverned.filter((file) => file.path && !String(file.path).startsWith('tiinex.package/')).length }), handoffCarrierVersion: 2 });
+  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 bundle = deepFreeze({ ...baseBundle, status, files, fileMap, packageRepresentationSha256: fileMap.representationSha256, handoffClosure: descriptor, boundary: `${baseBundle.boundary || ''} Direct v2 semantic baseline retains planning/closure truth without exploded complete-workspace outer carriage.` });
+
+  return deepFreeze({
+    schema: PORTABLE_HANDOFF_V2_DIRECT_BASELINE_SCHEMA_ID,
+    status,
+    executable: semanticReady,
+    transportExecutable: false,
+    plan,
+    planReadiness,
+    planInputBinding,
+    materializedOutputQualification,
+    bundle,
+    descriptor,
+    directWorkspaceSources: Object.freeze(directWorkspaceSources),
+    findings: Object.freeze([...(plan.findings || [])]),
+    boundary: 'Internal canonical archive-backed manufacture baseline. It reuses shared planning/material-closure owners while deliberately omitting exploded complete-Workspace carrier bytes before archive-backed representation is built.'
+  });
+}
+
+function indexPlanWorkspaces(items = []) {
+  const map = new Map();
+  for (const workspace of items) {
+    const key = String(workspace.transportCorrelationKey || '');
+    const list = map.get(key) || [];
+    list.push(workspace);
+    map.set(key, list);
+  }
+  return map;
+}
+function countRawCorrelations(items = []) {
+  const map = new Map();
+  for (const workspace of items) {
+    const key = workspaceMaterializationCorrelationKey(workspace);
+    map.set(key, (map.get(key) || 0) + 1);
+  }
+  return map;
+}
+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 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 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.archiveV2.indexes.js

@@ -0,0 +1,36 @@
+export function indexDirectWorkspaceSources(items = []) {
+  const map = new Map();
+  for (const item of items) {
+    const key = String(item?.transportCorrelationKey || '');
+    if (!key || String(item?.correlationStatus || '') !== 'qualified' || !item?.workspace) continue;
+    const list = map.get(key) || [];
+    list.push(item);
+    map.set(key, list);
+  }
+  return map;
+}
+
+export function resolveDirectWorkspaceSource(index, correlationKey = '') {
+  const items = index.get(String(correlationKey || '')) || [];
+  return items.length === 1 ? items[0] : null;
+}
+
+export function indexUniqueArchiveBaselineFiles(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, filesAtPath] of map) {
+    if (filesAtPath.length > 1) findings.push(Object.freeze({
+      severity: 'error',
+      code: 'portable.handoff-v2.outer-file-map.duplicate-path',
+      message: 'Baseline package contains duplicate outer paths; v2 refuses ambiguous byte selection.',
+      path,
+      count: filesAtPath.length
+    }));
+  }
+  return map;
+}

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

@@ -0,0 +1,247 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { packageFileBytes } from '../../../export/package.bytes.js';
+import { exportFileMapZipUint8Array } from '../../../export/package.zip.js';
+import { buildHandoffCarrierProjection, HANDOFF_CARRIER_PROJECTION_PATH, inspectHandoffCarrierProjection } from './carrierProjection.js';
+import { HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH } from './coldConsumerEntrypoint.js';
+import { HANDOFF_CLOSURE_DESCRIPTOR_PATH, HANDOFF_CLOSURE_DESCRIPTOR_V2_SCHEMA_ID } from './materialClosure.descriptor.js';
+import { HANDOFF_POINTER_ENTRYPOINT_PREFIX } from './pointerEntrypoint.js';
+import { buildHandoffTransportCompanionProjection, HANDOFF_TRANSPORT_COMPANION_PATH, inspectHandoffTransportCompanion } from './transportCompanion.js';
+import { normalizeHandoffWorkspaceInnerPath } from './workspaceByteProvider.js';
+import { indexWorkspaceTargetDeclarations, mapArchiveRequirements, qualifyDirectWorkspaceForArchive, qualifyWorkspaceForArchive } from './materialClosure.archiveV2.workspace.js';
+import { buildRecipientFacingV2Topology, RECIPIENT_V2_FORMAT_ID } from './recipientV2.topology.js';
+import { inspectRecipientFacingV2Topology, roundTripRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { indexDirectWorkspaceSources, indexUniqueArchiveBaselineFiles, resolveDirectWorkspaceSource } from './materialClosure.archiveV2.indexes.js';
+import { buildDirectArchiveProjectionProvider } from './materialClosure.archiveV2.projectionProvider.js';
+import { buildWorkspaceArchiveBinding, detachedParentCandidates } from './materialClosure.archiveV2.binding.js';
+
+export const PORTABLE_HANDOFF_TRANSPORT_PACKAGE_V2_SCHEMA_ID = 'tiinex.portable.handoff-transport-package.v2';
+
+export function upgradeRecipientRelativeHandoffTransportPackageV2(baseline = {}, input = {}, options = {}) {
+  const findings = [];
+  const baselineBundle = baseline.bundle || {};
+  const baselineDescriptor = baseline.descriptor || baselineBundle.handoffClosure || {};
+  if (!baselineBundle.files?.length || !baselineDescriptor.workspaceMaterializations?.length) {
+    return blockedUpgrade(baseline, [finding('error', 'portable.handoff-v2.baseline.unavailable', 'Archive-backed v2 manufacture requires a qualified recipient-relative semantic/control baseline.')]);
+  }
+
+  const byPath = indexUniqueArchiveBaselineFiles(baselineBundle.files || [], findings);
+  const archiveBindings = [];
+  const workspaceMaterializations = [];
+  const workspaceFiles = [];
+  const removedWorkspacePaths = new Set();
+  const workspaceEntryByQualifiedPath = new Map();
+  const workspaceTargetDeclarations = indexWorkspaceTargetDeclarations(input.workspaceTargets || input.workspaceTargetBindings || []);
+  const directSourcesByCorrelation = indexDirectWorkspaceSources(baseline.directWorkspaceSources || []);
+  let avoidedExplodedWorkspaceFiles = 0;
+  const records = [];
+  const parentCandidates = detachedParentCandidates(baselineDescriptor.materialized || [], byPath);
+
+  for (const workspace of baselineDescriptor.workspaceMaterializations || []) {
+    const directSource = resolveDirectWorkspaceSource(directSourcesByCorrelation, workspace.transportCorrelationKey);
+    const qualified = directSource
+      ? qualifyDirectWorkspaceForArchive(workspace, directSource.workspace, workspaceTargetDeclarations.get(String(workspace.id || '')) || [], parentCandidates)
+      : qualifyWorkspaceForArchive(workspace, byPath, workspaceTargetDeclarations.get(String(workspace.id || '')) || [], parentCandidates);
+    findings.push(...qualified.findings);
+    if (qualified.status !== 'qualified') continue;
+    const workspaceId = String(workspace.id || '');
+    const archivePath = `handoff.workspaces/${safeToken(workspaceId)}/workspace.snapshot.zip`;
+    const targetPath = `handoff.workspaces/${safeToken(workspaceId)}/workspace.artifact.md`;
+    const archiveBytes = exportFileMapZipUint8Array(qualified.entries.map((entry) => ({ path: entry.path, data: entry.data })), 'portable.handoff-v2.workspace-archive.path.invalid');
+    const coverage = String(workspace.materialization || '') === 'bounded' ? 'bounded' : 'complete';
+    const coverageEvidence = coverage === 'bounded' ? (workspace.scopeEvidence || {}) : (workspace.completenessEvidence || {});
+    const archiveFile = finalizeFile({ path: archivePath, kind: 'handoff-workspace-archive', logicalKind: coverage === 'bounded' ? 'recipient-relative-bounded-workspace-archive' : 'recipient-relative-complete-workspace-archive', mediaType: 'application/zip', data: archiveBytes, boundary: coverage === 'bounded' ? 'Exact bounded Workspace Representation entry set; omitted source paths remain outside representation and detached recovery remains separate.' : 'Exact complete Workspace snapshot representation; Workspace identity comes only from the exact qualified target plus binding, never archive name/placement.' });
+    const targetFile = finalizeFile({ path: targetPath, kind: 'handoff-workspace-target', logicalKind: 'recipient-relative-workspace-identity-target', mediaType: 'text/markdown', data: qualified.target.data, boundary: 'Exact tiinex.workspace.v1 target binding carrier id to Workspace identity; package name/placement have no authority.' });
+    workspaceFiles.push(targetFile, archiveFile);
+    for (const entry of qualified.entries) {
+      if (entry.packagePath && byPath.has(entry.packagePath)) removedWorkspacePaths.add(entry.packagePath);
+      else avoidedExplodedWorkspaceFiles += 1;
+      workspaceEntryByQualifiedPath.set(`${workspaceId}\u0000${entry.path}`, entry);
+    }
+    const binding = buildWorkspaceArchiveBinding({ workspace, qualified, archiveFile, targetFile, coverage });
+    const entries = binding.entryMap.entries;
+    archiveBindings.push(binding);
+    workspaceMaterializations.push(deepFreeze({ ...workspace, includedEntries: Object.freeze(entries) }));
+    records.push(Object.freeze({ workspace, binding, qualified, archiveFile }));
+  }
+
+  if (workspaceMaterializations.length !== (baselineDescriptor.workspaceMaterializations || []).length) {
+    return blockedUpgrade(baseline, findings.length ? findings : [finding('error', 'portable.handoff-v2.workspace.unqualified', 'One or more workspace snapshots could not qualify for archive-backed carriage.')]);
+  }
+
+  const removedMaterialPaths = new Set();
+  const materialized = (baselineDescriptor.materialized || []).map((material) => {
+    const workspaceId = String(material.provenance?.workspaceId || '');
+    const relative = normalizedOrEmpty(material.provenance?.path || material.originalPath || '');
+    const entry = workspaceId && relative ? workspaceEntryByQualifiedPath.get(`${workspaceId}\u0000${relative}`) : null;
+    if (entry && Number(material.bytes || 0) === entry.bytes && String(material.sha256 || '') === entry.sha256) {
+      if (material.packagePath) removedMaterialPaths.add(String(material.packagePath));
+      return deepFreeze({ ...material, packagePath: '', carrierKind: 'workspace-archive-entry', workspaceId, workspaceRelativePath: relative, authority: Object.freeze({ ...(material.authority || {}), carrierDedupBasis: 'exact-qualified-workspace-archive-entry-byte-identity' }) });
+    }
+    return material;
+  });
+
+  const bindingByWorkspace = new Map(archiveBindings.map((binding) => [binding.workspaceId, binding]));
+  const requirements = mapArchiveRequirements(baselineDescriptor.requirements || {}, materialized, bindingByWorkspace);
+  const descriptor = deepFreeze({
+    ...baselineDescriptor,
+    schema: HANDOFF_CLOSURE_DESCRIPTOR_V2_SCHEMA_ID,
+    version: 2,
+    boundary: 'Disposable recipient-relative transport metadata with exact archive-backed Workspace binding. Safe to delete with the package; not a Tiinex artifact, semantic Parent, workspace owner, package identity, Handoff acceptance/completion state, or semantic provider authority.',
+    requirements,
+    materialized: Object.freeze(materialized),
+    workspaceMaterializations: Object.freeze(workspaceMaterializations),
+    workspaceArchiveBindings: Object.freeze(archiveBindings),
+    providerProvenance: Object.freeze(materialized.map((entry) => Object.freeze({ requirementId: entry.requirementId, provider: entry.provider || {}, provenance: entry.provenance || {}, carrierKind: String(entry.carrierKind || 'detached-material') }))),
+    roundtripVerification: Object.freeze({
+      state: 'build-verified',
+      verifier: 'durable-outer-file-map-plus-qualified-workspace-archive-provider-rehydration-required',
+      descriptorPath: HANDOFF_CLOSURE_DESCRIPTOR_PATH,
+      expectedMaterial: Object.freeze([
+        ...materialized.filter((entry) => entry.carrierKind !== 'workspace-archive-entry').map((entry) => Object.freeze({ packagePath: entry.packagePath, bytes: entry.bytes, sha256: entry.sha256 })),
+        ...archiveBindings.flatMap((binding) => [
+          Object.freeze({ packagePath: binding.workspaceTarget.packagePath, bytes: binding.workspaceTarget.bytes, sha256: binding.workspaceTarget.sha256 }),
+          Object.freeze({ packagePath: binding.representation.packagePath, bytes: binding.representation.bytes, sha256: binding.representation.digest.value })
+        ])
+      ]),
+      note: 'Outer file-map integrity governs package files. Workspace entry identity/coverage is independently re-established from the exact archive digest, entry map, per-entry byte identity, and exact carried Workspace target; descriptor presence alone proves neither delivery nor Handoff acceptance.'
+    })
+  });
+
+  const generatedPaths = new Set([HANDOFF_CLOSURE_DESCRIPTOR_PATH, HANDOFF_CARRIER_PROJECTION_PATH, HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH, HANDOFF_TRANSPORT_COMPANION_PATH, 'tiinex.package/file-map.json', 'tiinex.package/build-receipt.json']);
+  const retained = (baselineBundle.files || []).filter((file) => {
+    const path = String(file.path || '');
+    return !generatedPaths.has(path) && !path.startsWith(HANDOFF_POINTER_ENTRYPOINT_PREFIX) && !removedWorkspacePaths.has(path) && !removedMaterialPaths.has(path);
+  });
+  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 projectionBundle = { ...baselineBundle, files: [...retained, ...workspaceFiles, descriptorFile], handoffClosure: descriptor };
+  const provider = buildDirectArchiveProjectionProvider(records);
+  const carrierProjection = buildHandoffCarrierProjection({ bundle: projectionBundle, descriptor, workspaceByteProvider: provider, carrierLineage: input.carrierLineage || baseline.carrierProjection?.lineage || null, routes: input.transportRoutes || input.handoffRoutes || (baseline.carrierProjection?.routes || []).map((route) => ({ workspaceId: route.workspaceId, path: route.workspaceRelativePath, purpose: route.purpose })) });
+  const createdAt=baselineBundle.manifest?.createdAt||baselineBundle.builtAt||'';
+  const transportStatus = baseline.status === 'blocked' || carrierProjection.status !== 'ready' ? 'blocked' : baseline.status;
+  const transportCompanion = buildHandoffTransportCompanionProjection({ bundle: projectionBundle, 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 companionInspectionRaw = inspectHandoffTransportCompanion({ ...projectionBundle, status: transportStatus, handoffClosure: descriptor, files: Object.freeze([...projectionBundle.files, companionFile]) });
+
+  // Recipient-v2 is the canonical carrier. Do not serialize and fully re-inspect the hidden
+  // legacy export-package control graph before building the recipient surface: that duplicated
+  // whole-archive hashing and let an implementation-only representation gate the real carrier.
+  // The direct closure/carrier builders qualify exact source bytes first; the visible recipient
+  // surface is then independently inspected, and optional roundtrip verifies its serialized bytes.
+  const recipientSurface = buildRecipientFacingV2Topology({
+    bundle: projectionBundle,
+    descriptor,
+    carrierProjection,
+    carrierProfile: input.carrierProfile || null,
+    routeSelector: input.recipientRouteSelector || '',
+    createdAt,
+    artifactFirstDualProjectionPhase1: options.artifactFirstDualProjectionPhase1 === true || input.artifactFirstDualProjectionPhase1 === true,
+    artifactFirstCleanCarrierPhase2: options.artifactFirstCleanCarrierPhase2 === true || input.artifactFirstCleanCarrierPhase2 === true,
+    legacyRecipientV2Compatibility: options.legacyRecipientV2Compatibility === true || input.legacyRecipientV2Compatibility === true
+  });
+  findings.push(...(recipientSurface.findings || []));
+  const bundle = deepFreeze({ ...baselineBundle, status: transportStatus, files: recipientSurface.files, fileMap: null, packageRepresentationSha256: '', handoffClosure: null, transportFormat: RECIPIENT_V2_FORMAT_ID, boundary: `${baselineBundle.boundary || ''} Recipient-facing v2 exposes a flat qualified-artifact/payload root; legacy control JSON is not serialized.` });
+  const fullRecipientVerificationRequested = options.verifyRoundtrip !== false && input.verifyRoundtrip !== false;
+  const constructionInspection = constructionRecipientV2Inspection(recipientSurface, carrierProjection, descriptor);
+  const normalReadyPath = carrierProjection.status === 'ready' && constructionInspection.status === 'valid';
+  // On the normal ready path, full verification needs one independent inspection of the
+  // physically serialized carrier, not two equivalent logical inspections of the same
+  // constructed bytes. Blocked/diagnostic manufacture keeps the prior logical inspection
+  // before roundtrip so fail-closed findings and suppressed route projections remain unchanged.
+  const sourceInspection = fullRecipientVerificationRequested && !normalReadyPath
+    ? inspectRecipientFacingV2Topology(bundle)
+    : constructionInspection;
+  const runtime = fullRecipientVerificationRequested ? roundTripRecipientFacingV2Topology(bundle, sourceInspection) : null;
+  const inspection = fullRecipientVerificationRequested && normalReadyPath
+    ? (runtime?.inspection || constructionInspection)
+    : sourceInspection;
+  const carrierReady = carrierProjection.status === 'ready';
+  const flatReady = recipientSurface.status === 'ready' && inspection.status === 'valid' && (!runtime || runtime.status === 'passed');
+  const verificationReady = carrierReady && flatReady && companionInspectionRaw.status === 'valid';
+  const closureInspection = deepFreeze({ schema: 'tiinex.portable.handoff-v2.recipient-closure.inspection.v1', status: inspection.status, workspaceByteProvider: inspection.workspaceByteProvider, findings: inspection.findings });
+  const carrierInspection = deepFreeze({ schema: 'tiinex.portable.handoff-v2.recipient-carrier.inspection.v1', status: inspection.status, projection: inspection.carrierProjection, findings: inspection.findings });
+  const pointerEntrypointInspection = deepFreeze({ schema: 'tiinex.portable.handoff-v2.recipient-pointer.inspection.v1', status: inspection.status, entries: inspection.routes, findings: inspection.findings });
+  const coldConsumerEntrypointInspection = deepFreeze({ schema: 'tiinex.portable.handoff-v2.recipient-orientation.inspection.v1', status: inspection.status, projection: inspection.coldConsumerProjection, findings: inspection.findings });
+  const companionInspection = deepFreeze({ schema: 'tiinex.portable.handoff-v2.internal-companion.inspection.v1', status: companionInspectionRaw.status, projection: transportCompanion, serialized: false, findings: companionInspectionRaw.findings || [] });
+  if (!verificationReady) findings.push(finding('error', 'portable.handoff-v2.verification.blocked', 'Canonical recipient-v2 package failed one or more direct carrier, recipient-facing topology/provider/route, companion, or roundtrip verification gates.', { carrierProjection: carrierProjection.status, recipientSurface: recipientSurface.status, recipientInspection: inspection.status, companionInspection: companionInspectionRaw.status, roundtrip: runtime?.status || 'not-requested' }));
+
+  const __out = deepFreeze({
+    schema: PORTABLE_HANDOFF_TRANSPORT_PACKAGE_V2_SCHEMA_ID,
+    status: verificationReady ? transportStatus : 'blocked',
+    bundle,
+    descriptor: inspection.descriptor || descriptor,
+    carrierProjection: inspection.carrierProjection,
+    pointerEntrypointProjection: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-pointer-projection.v1', entries: inspection.routes || Object.freeze([]) }),
+    coldConsumerProjection: inspection.coldConsumerProjection,
+    transportCompanion,
+    recipientSurface,
+    inspection,
+    closureInspection,
+    carrierInspection,
+    pointerEntrypointInspection,
+    coldConsumerEntrypointInspection,
+    companionInspection,
+    roundtrip: runtime,
+    findings: Object.freeze(dedupeFindings(findings)),
+    migration: Object.freeze({ mode: 'canonical-archive-backed-recipient', recipientTopology: RECIPIENT_V2_FORMAT_ID, manufacturePath: directSourcesByCorrelation.size ? 'direct-qualified-workspace-to-archive' : 'archive-baseline-upgrade', removedExplodedWorkspaceFiles: removedWorkspacePaths.size, avoidedExplodedWorkspaceFiles, deduplicatedDetachedMaterialFiles: removedMaterialPaths.size, exposedWorkspaceTargets: archiveBindings.length, workspaceArchives: archiveBindings.length }),
+    boundary: 'Canonical recipient transport representation only. No semantic Workspace identity is minted and this result carries no remote mutation authority.'
+  });
+  return __out;
+}
+
+
+function constructionRecipientV2Inspection(recipientSurface = {}, carrierProjection = {}, descriptor = {}) {
+  const topology = recipientSurface.topology || {};
+  const findings = Object.freeze([...(recipientSurface.findings || [])]);
+  const status = recipientSurface.status === 'ready' && !findings.some((item) => item.severity === 'error') ? 'valid' : 'invalid';
+  return deepFreeze({
+    schema: 'tiinex.portable.recipient-facing-handoff-v2.construction-inspection.v1',
+    detected: true,
+    status,
+    format: RECIPIENT_V2_FORMAT_ID,
+    verificationMode: 'construction-qualified; physical re-ingest required for independent recipient verification',
+    rootArtifact: topology.root ? Object.freeze({ path: String(topology.root.path || ''), sha256: String(topology.root.sha256 || '') }) : null,
+    readArtifact: topology.read ? Object.freeze({ path: String(topology.read.path || ''), status: 'qualified' }) : null,
+    workspaces: Object.freeze((topology.workspaces || []).map((item) => Object.freeze({
+      workspaceId: String(item.workspaceId || ''),
+      workspaceArtifactPath: String(item.workspacePath || ''),
+      workspaceArchivePath: String(item.archivePath || ''),
+      sourceWorkspaceTargetInnerPath: String(item.sourceWorkspaceTargetInnerPath || ''),
+      sourceWorkspaceTargetSha256: String(item.sourceWorkspaceTargetSha256 || '')
+    }))),
+    routes: Object.freeze((topology.routes || []).map((item) => Object.freeze({
+      pointerPath: String(item.pointerPath || ''),
+      workspaceId: String(item.workspaceId || ''),
+      workspaceRelativeHandoffPath: String(item.workspaceRelativeHandoffPath || ''),
+      endpointRolePointers: Object.freeze((topology.endpointRoles || [])
+        .filter((role) => String(role.routeId || '') === String(item.routeId || ''))
+        .map((role) => String(role.pointerPath || ''))
+        .filter(Boolean)),
+      participantRolePointers: Object.freeze((topology.participantRoles || [])
+        .filter((role) => String(role.routeId || '') === String(item.routeId || ''))
+        .map((role) => String(role.pointerPath || ''))
+        .filter(Boolean))
+    }))),
+    endpointRoles: Object.freeze((topology.endpointRoles || []).map((item) => Object.freeze({ ...item }))),
+    participantRoles: Object.freeze((topology.participantRoles || []).map((item) => Object.freeze({ ...item }))),
+    caches: Object.freeze((topology.caches || []).map((item) => Object.freeze({ ...item }))),
+    descriptor,
+    carrierProjection,
+    coldConsumerProjection: null,
+    bootstrapInspection: null,
+    findings,
+    findingSummary: Object.freeze({ errors: findings.filter((item) => item.severity === 'error').length, findings: findings.length }),
+    boundary: 'Producer-side construction qualification only. Independent recipient qualification is intentionally deferred to physical package re-ingest when full roundtrip is not requested.'
+  });
+}
+
+function normalizedOrEmpty(value = '') { const normalized = normalizeHandoffWorkspaceInnerPath(value); return normalized.state === 'qualified' ? normalized.path : ''; }
+function blockedUpgrade(baseline = {}, findings = []) { return deepFreeze({ schema: PORTABLE_HANDOFF_TRANSPORT_PACKAGE_V2_SCHEMA_ID, status: 'blocked', bundle: baseline.bundle || null, descriptor: baseline.descriptor || null, carrierProjection: baseline.carrierProjection || null, findings: Object.freeze(dedupeFindings(findings)), migration: Object.freeze({ mode: 'canonical-archive-backed-recipient', state: 'blocked-before-representation-switch' }), boundary: 'Canonical archive-backed recipient manufacture failed closed before changing the baseline carrier representation.' }); }
+function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+function parseJsonFile(file = null) { try { return file ? JSON.parse(decodeUtf8(packageFileBytes(file))) : null; } catch { return null; } }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function safeToken(value = '') { return String(value || '').trim().replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 100) || 'workspace'; }
+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 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.path || ''}:${item.packagePath || ''}`; 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); }