@tiinex/core 0.14.0 → 0.16.0

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

@@ -9,6 +9,7 @@ import { enumerateNodeWorkspace, PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID }
 import { preparePackageParentWorkspaceReuse } from './handoff.manufacture.packageParent.js';
 import { qualifyPortableSourceReconciliationProofForManufacture } from '../../comparison/sourceFrontierReconciliationProof.js';
 import { qualifyPortableManufactureSchemaReferenceCandidate } from '../../handoff/schemaReferencePreflight.js';
+import { qualifyDelegationReturnReservation } from '../../handoff/delegationReturnReservation.js';
 import {
   assertInside,
   expandPointerDependencyClosure,
@@ -102,6 +103,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
   });
 
   const schemaReferencePreflight = qualifyPortableManufactureSchemaReferenceCandidate(handoff);
+  const returnCarrierReservationPreflight = qualifyDelegationReturnReservation({ markdown: handoffMarkdown, returnPackageSiblingIndex: input.returnPackageSiblingIndex, returnPackageMajor: input.returnPackageMajor === true });
 
   if (enumeration.status !== 'qualified-complete') throw new Error(`portable.handoff-manufacture.workspace-enumeration.${enumeration.status}`);
   const workspaceTitle = requestedWorkspaceTitle || inferWorkspaceTitle(enumeration) || workspaceId;
@@ -128,7 +130,11 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     if (!id || workspaceRuntimeById.has(id)) continue;
     workspaceRuntimeById.set(id, Object.freeze({ id, root: '', enumeration: provided.enumeration, provider: 'qualified-package-parent-workspace-material-provider' }));
   }
-  const transportRoutes = Object.freeze([...(input.transportRoutes || input.handoffRoutes || [])].map((route) => normalizeTransportRoute(route, workspaceId)).filter(Boolean));
+  const suppliedTransportRoutes = [...(input.transportRoutes || input.handoffRoutes || [])].map((route) => normalizeTransportRoute(route, workspaceId)).filter(Boolean);
+  const reservationProjection = returnCarrierReservationPreflight.state === 'qualified' && returnCarrierReservationPreflight.returnExpected
+    ? Object.freeze({ carrierKind: returnCarrierReservationPreflight.carrierKind, siblingIndex: returnCarrierReservationPreflight.siblingIndex })
+    : null;
+  const transportRoutes = Object.freeze((suppliedTransportRoutes.length ? suppliedTransportRoutes : [Object.freeze({ workspaceId, path: handoffPath })]).map((route) => Object.freeze({ ...route, ...(route.path === handoffPath && String(route.workspaceId || '') === workspaceId && reservationProjection ? { returnCarrierReservation: reservationProjection } : {}) })));
   const workspaceTargets = mergeWorkspaceTargetBindings(normalizeWorkspaceTargetBindings({
     primaryWorkspaceId: workspaceId,
     primaryTargetPath: input.workspaceTargetPath || input.workspaceArtifactPath || '',
@@ -195,6 +201,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     toolingBootstrap: toolingBootstrap.summary,
     reconciliationProofQualification,
     schemaReferencePreflight,
+    returnCarrierReservationPreflight,
     manufacturingEvidence: Object.freeze({
       enumeration: enumeration.evidence,
       workspaceEnumerations: Object.freeze(workspaceEnumerations),
@@ -202,6 +209,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
       runtimeSourceAlignment,
       reconciliationProof: reconciliationProofQualification,
       schemaReferencePreflight,
+      returnCarrierReservationPreflight,
       packageParentWorkspaceReuse: Object.freeze({
         state: String(packageParentReuse.state || ''),
         providerState: String(packageParentReuse.providerState || ''),

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

@@ -58,7 +58,7 @@ export function inspectHandoffCarrierProjection(bundle = {}, options = {}) {
   if (projection && projection.schema !== HANDOFF_CARRIER_PROJECTION_SCHEMA_ID) findings.push(finding('error', 'portable.handoff-carrier.schema.invalid', 'Handoff carrier projection schema/version is unsupported.'));
   if (projection && projection.boundary !== BOUNDARY) findings.push(finding('error', 'portable.handoff-carrier.boundary.invalid', 'Handoff carrier projection lost its disposable non-authoritative boundary.'));
   if (projection) {
-    const expected = buildHandoffCarrierProjection({ bundle, workspaceByteProvider: options.workspaceByteProvider || null, carrierLineage: projection.lineage || null, routes: (projection.routes || []).map((route) => ({ workspaceId: route.workspaceId, path: route.workspaceRelativePath, purpose: route.purpose, participantRoles: route.participantRoleSpecs || [] })) });
+    const expected = buildHandoffCarrierProjection({ bundle, workspaceByteProvider: options.workspaceByteProvider || null, carrierLineage: projection.lineage || null, routes: (projection.routes || []).map((route) => ({ workspaceId: route.workspaceId, path: route.workspaceRelativePath, purpose: route.purpose, participantRoles: route.participantRoleSpecs || [], returnCarrierReservation: route.returnCarrierReservation || null })) });
     for (const field of ['status', 'mode', 'lineage', 'workspaces', 'workspace', 'selection', 'routes', 'authority']) {
       if (stableJson(expected[field]) !== stableJson(projection[field])) findings.push(finding('error', `portable.handoff-carrier.${field}.mismatch`, `Handoff carrier ${field} diverges from current package/workspace truth.`));
     }
@@ -162,7 +162,7 @@ function normalizeRouteSpecs(value, descriptor, defaultWorkspace = null) {
     const path = normalizeWorkspacePath(spec.path || spec.workspaceRelativePath || '');
     const workspaceId = String(spec.workspaceId || spec.workspace || defaultWorkspaceId || '');
     const key = `${workspaceId}\u0000${path}`;
-    if (path && !map.has(key)) map.set(key, Object.freeze({ workspaceId, path, purpose: String(spec.purpose || ''), participantRoles: Object.freeze([...(spec.participantRoles || spec.roles || [])].map((entry) => typeof entry === 'string' ? entry : Object.freeze({ ...(entry || {}) }))) }));
+    if (path && !map.has(key)) map.set(key, Object.freeze({ workspaceId, path, purpose: String(spec.purpose || ''), participantRoles: Object.freeze([...(spec.participantRoles || spec.roles || [])].map((entry) => typeof entry === 'string' ? entry : Object.freeze({ ...(entry || {}) }))), returnCarrierReservation: spec.returnCarrierReservation ? Object.freeze({ ...(spec.returnCarrierReservation || {}) }) : null }));
   }
   return [...map.values()].sort((a, b) => a.workspaceId.localeCompare(b.workspaceId) || a.path.localeCompare(b.path));
 }

package/src/tooling/portable/handoff/carrierProjection.routeQualification.js

@@ -53,6 +53,7 @@ export function qualifyRoute(bundle, descriptor, byteProvider, workspace, spec =
     materialRequirements,
     participantRoles,
     participantRoleSpecs,
+    returnCarrierReservation: spec.returnCarrierReservation ? deepFreeze({ ...(spec.returnCarrierReservation || {}) }) : null,
     requiredClosure,
     reasons: Object.freeze(reasons),
     authority: Object.freeze({ artifactPartiesAuthoritative: true, dimensionSemanticAuthority: false, filenameSemanticAuthority: false })

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

@@ -0,0 +1,101 @@
+export const PORTABLE_DELEGATION_RETURN_RESERVATION_SCHEMA_ID = 'tiinex.portable.delegation-return-reservation-preflight.v1';
+
+export function qualifyDelegationReturnReservation(input = {}) {
+  const markdown = String(input.markdown || input.handoffMarkdown || '');
+  const completion = sectionText(markdown, 'Completion Expectation');
+  const signalKind = field(completion, 'Signal Kind').toLowerCase();
+  const returnExpected = signalKind === 'return';
+  const declaredMajor = input.returnPackageMajor === true;
+  const rawIndex = firstDefined(input.returnPackageSiblingIndex, reservedSiblingIndexFromHandoff(markdown));
+  const findings = [];
+
+  if (!returnExpected) return freeze({
+    schema: PORTABLE_DELEGATION_RETURN_RESERVATION_SCHEMA_ID,
+    state: 'not-required',
+    returnExpected: false,
+    carrierKind: 'not-applicable',
+    siblingIndex: null,
+    findings,
+    boundary: boundary()
+  });
+
+  if (declaredMajor) {
+    if (rawIndex !== undefined && rawIndex !== null && String(rawIndex).trim() !== '') findings.push(finding('error', 'portable.delegation-return-reservation.major-index-conflict', 'A Major return declaration must not also carry a non-Major package sibling index.'));
+    return freeze({
+      schema: PORTABLE_DELEGATION_RETURN_RESERVATION_SCHEMA_ID,
+      state: findings.length ? 'blocked' : 'qualified',
+      returnExpected: true,
+      carrierKind: 'major',
+      siblingIndex: null,
+      findings,
+      boundary: boundary()
+    });
+  }
+
+  const siblingIndex = parseSiblingIndex(rawIndex);
+  if (siblingIndex === null) findings.push(finding('error', 'portable.delegation-return-reservation.sibling-index.required', 'A return Handoff is transport-not-ready until the delegator supplies one explicit non-Major return package sibling index in the supported range 1..9999.'));
+  return freeze({
+    schema: PORTABLE_DELEGATION_RETURN_RESERVATION_SCHEMA_ID,
+    state: findings.length ? 'blocked' : 'qualified',
+    returnExpected: true,
+    carrierKind: 'non-major',
+    siblingIndex,
+    findings,
+    boundary: boundary()
+  });
+}
+
+export function parseDelegationReturnReservationPointer(pointer = {}) {
+  const siblingIndex = parseSiblingIndex(pointer.returnPackageSiblingIndex);
+  const carrierKind = String(pointer.returnPackageCarrierKind || '').trim().toLowerCase();
+  if (carrierKind === 'major') return freeze({ state: 'qualified', returnExpected: true, carrierKind: 'major', siblingIndex: null });
+  if (carrierKind === 'non-major' && siblingIndex !== null) return freeze({ state: 'qualified', returnExpected: true, carrierKind: 'non-major', siblingIndex });
+  return freeze({ state: 'unresolved', returnExpected: false, carrierKind: '', siblingIndex: null });
+}
+
+
+function reservedSiblingIndexFromHandoff(markdown = '') {
+  const transfers = sectionText(markdown, 'Transfers');
+  if (!transfers) return null;
+  const lines = transfers.replace(/\r\n?/g, '\n').split('\n');
+  const start = lines.findIndex((line) => /^\s*-\s+reserved-return-package-sibling-index\s*$/i.test(line));
+  if (start < 0) return null;
+  const block = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^-\s+[^\s].*$/.test(lines[index])) break;
+    block.push(lines[index]);
+  }
+  const description = field(block.join('\n'), 'Description');
+  const match = description.match(/(?:package\s+sibling\s+index|sibling\s+index|index)\s+`?(\d{1,4})`?/i);
+  return match ? match[1] : null;
+}
+function firstDefined(...values) {
+  for (const value of values) if (value !== undefined && value !== null && String(value).trim() !== '') return value;
+  return null;
+}
+
+function parseSiblingIndex(value) {
+  if (value === undefined || value === null || String(value).trim() === '') return null;
+  if (!/^\d+$/.test(String(value).trim())) return null;
+  const parsed = Number.parseInt(String(value).trim(), 10);
+  return Number.isInteger(parsed) && parsed >= 1 && parsed <= 9999 ? parsed : null;
+}
+function sectionText(markdown = '', heading = '') {
+  const lines = String(markdown || '').replace(/\r\n?/g, '\n').split('\n');
+  const start = lines.findIndex((line) => new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'i').test(line));
+  if (start < 0) return '';
+  const out = [];
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index])) break;
+    out.push(lines[index]);
+  }
+  return out.join('\n');
+}
+function field(section = '', name = '') {
+  const match = String(section || '').match(new RegExp(`^\\s*-\\s+${escapeRegExp(name)}\\s*:\\s*(.+?)\\s*$`, 'mi'));
+  return String(match?.[1] || '').trim();
+}
+function boundary() { return 'Transport preflight only. It validates an explicit delegator-coordinated return reservation and never allocates, discovers, increments, guesses, recycles, or promotes a sibling index into semantic Parent, Workspace, Role, acceptance, or completion authority.'; }
+function finding(severity, code, message) { return Object.freeze({ severity, code, message }); }
+function escapeRegExp(value = '') { return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map(freeze)); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }

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

@@ -21,9 +21,12 @@ export function manufactureRecipientRelativeHandoffPackage(input = {}, options =
   const reconciliationBlocked = String(reconciliationProofQualification?.state || '') === 'blocked';
   const schemaReferencePreflight = input.schemaReferencePreflight || input.manufacturingEvidence?.schemaReferencePreflight || null;
   const schemaReferenceBlocked = String(schemaReferencePreflight?.state || '') === 'blocked';
+  const returnCarrierReservationPreflight = input.returnCarrierReservationPreflight || input.manufacturingEvidence?.returnCarrierReservationPreflight || null;
+  const returnCarrierReservationBlocked = String(returnCarrierReservationPreflight?.state || '') === 'blocked';
   const findings = Object.freeze([
     ...majorFindings,
     ...(schemaReferencePreflight?.findings || []),
+    ...(returnCarrierReservationPreflight?.findings || []),
     ...(reconciliationProofQualification?.findings || []),
     ...(baseline.findings || []),
     ...(upgraded.findings || []),
@@ -36,7 +39,7 @@ export function manufactureRecipientRelativeHandoffPackage(input = {}, options =
     ...(upgraded.roundtrip?.findings || []),
     ...(toolingBootstrapInspection?.findings || [])
   ]);
-  const status = baseline.status !== 'blocked' && upgraded.status !== 'blocked' && toolingBootstrapInspection?.status === 'valid' && majorReadiness.state !== 'blocked' && !schemaReferenceBlocked && !reconciliationBlocked ? upgraded.status : 'blocked';
+  const status = baseline.status !== 'blocked' && upgraded.status !== 'blocked' && toolingBootstrapInspection?.status === 'valid' && majorReadiness.state !== 'blocked' && !schemaReferenceBlocked && !returnCarrierReservationBlocked && !reconciliationBlocked ? upgraded.status : 'blocked';
   return Object.freeze({
     schema: 'tiinex.portable.handoff-manufacturing.v2',
     status,
@@ -55,6 +58,7 @@ export function manufactureRecipientRelativeHandoffPackage(input = {}, options =
       roundtrip: upgraded.roundtrip ? String(upgraded.roundtrip.status || 'unknown') : 'not-requested',
       toolingBootstrap: String(toolingBootstrapInspection?.status || 'unavailable'),
       schemaReferencePreflight: String(schemaReferencePreflight?.state || 'not-run'),
+      returnCarrierReservationPreflight: String(returnCarrierReservationPreflight?.state || 'not-run'),
       reconciliationProof: String(reconciliationProofQualification?.state || 'not-required')
     }),
     plan: baseline.plan,
@@ -74,6 +78,7 @@ export function manufactureRecipientRelativeHandoffPackage(input = {}, options =
     toolingBootstrap: input.toolingBootstrap || null,
     manufacturingEvidence: input.manufacturingEvidence || null,
     schemaReferencePreflight,
+    returnCarrierReservationPreflight,
     reconciliationProofQualification,
     toolingBootstrapInspection,
     carrierLineage: upgraded.carrierProjection?.lineage || baseline.carrierProjection?.lineage || input.carrierLineage || null,
@@ -86,6 +91,7 @@ export function manufactureRecipientRelativeHandoffPackage(input = {}, options =
       remoteMutation: false,
       physicalRoundtripVerification: upgraded.roundtrip ? String(upgraded.roundtrip.status || 'unknown') : 'not-requested',
       schemaReferencePreflight: String(schemaReferencePreflight?.state || 'not-run'),
+      returnCarrierReservationPreflight: String(returnCarrierReservationPreflight?.state || 'not-run'),
       reconciliationProof: String(reconciliationProofQualification?.state || 'not-required'),
       hostBehaviorAuthority: 'none'
     }),

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

@@ -115,7 +115,7 @@ export function upgradeRecipientRelativeHandoffTransportPackageV2(baseline = {},
   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 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, returnCarrierReservation: route.returnCarrierReservation || null })) });
   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 || {} });

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

@@ -24,6 +24,17 @@ export function correlatePointerFacts(markdown, facts, findings, path) {
   if (facts.role !== 'handoff-route' || !facts.archivePath) return;
   const targets = [...sectionText(markdown, 'Destinations').matchAll(/\[[^\]]*\]\(([^)]+)\)/g)].map((match) => match[1]);
   if (targets.length !== 1 || targets[0] !== String(facts.archivePath)) findings.push(finding('error', 'portable.handoff-v2-surface.pointer.visible-destination-mismatch', 'Route Pointer visible Destination diverges from its sealed machine facts.', { path }));
+  if (facts.returnCarrierReservation) {
+    const current = sectionText(markdown, 'Current Read');
+    const visibleKind = unquoteCode(fieldValue(current, 'Return Package Carrier Kind'));
+    const expectedKind = String(facts.returnCarrierReservation.carrierKind || '');
+    if (visibleKind !== expectedKind) findings.push(finding('error', 'portable.handoff-v2-surface.pointer.visible-return-carrier-kind-mismatch', 'Route Pointer visible return-carrier kind diverges from its sealed machine facts.', { path }));
+    if (expectedKind === 'non-major') {
+      const visibleSiblingIndex = Number(unquoteCode(fieldValue(current, 'Return Package Sibling Index')) || 0);
+      const expectedSiblingIndex = Number(facts.returnCarrierReservation.siblingIndex || 0);
+      if (visibleSiblingIndex !== expectedSiblingIndex) findings.push(finding('error', 'portable.handoff-v2-surface.pointer.visible-return-sibling-index-mismatch', 'Route Pointer visible return package sibling index diverges from its sealed machine facts.', { path }));
+    }
+  }
 }
 export function markdownTarget(value = '') { return String(value || '').match(/\[[^\]]*\]\(([^)]+)\)/)?.[1] || String(value || '').trim(); }
 export function inspectExternalPayloadShape(markdown, findings, path) {

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

@@ -1,13 +1,17 @@
 import { parentTrace } from './recipientV2.lineage.js';
 
-export function projectRecipientV2Routes(routePointers = [], endpointPointers = [], participantPointers = []) {
-  return Object.freeze(routePointers.map((item) => Object.freeze({
+export function projectRecipientV2Routes(routePointers = [], endpointPointers = [], participantPointers = [], qualifiedRoutes = []) {
+  return Object.freeze(routePointers.map((item) => {
+    const qualified = (qualifiedRoutes || []).find((route) => String(route.workspaceId || '') === String(item.facts?.workspaceId || '') && String(route.workspaceRelativePath || '') === String(item.facts?.workspaceRelativeHandoffPath || '')) || null;
+    return Object.freeze({
     pointerPath: item.path,
     workspaceId: String(item.facts?.workspaceId || ''),
     workspaceRelativeHandoffPath: String(item.facts?.workspaceRelativeHandoffPath || ''),
+    returnCarrierReservation: item.facts?.returnCarrierReservation || qualified?.returnCarrierReservation || null,
     endpointRolePointers: Object.freeze(rolePointerAncestors(item, endpointPointers, participantPointers).filter((path) => endpointPointers.some((pointer) => pointer.path === path))),
     participantRolePointers: Object.freeze(rolePointerAncestors(item, endpointPointers, participantPointers).filter((path) => participantPointers.some((pointer) => pointer.path === path)))
-  })));
+  });
+  }));
 }
 
 export function projectRecipientV2EndpointRoles(pointers = []) {

package/src/tooling/portable/handoff/recipientV2.packageV1.build.js

@@ -173,11 +173,12 @@ function buildRecipientFacingV2PackageV1Prepared(input = {}, sealedByWorkspaceId
       workspaceId: owningWorkspace.workspaceId, workspaceArtifactPath: owningWorkspace.workspacePath, workspaceArtifactSha256: owningWorkspace.workspaceSha256,
       archivePath: owningWorkspace.archivePath, archiveSha256: owningWorkspace.archiveSha256, sourceWorkspaceTargetInnerPath: owningWorkspace.sourceWorkspaceTargetInnerPath,
       sourceWorkspaceTargetSha256: owningWorkspace.sourceWorkspaceTargetSha256, workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), handoffBytes: Number(routeEntry?.bytes || 0), handoffSha256: String(route.sha256 || ''), routeId: String(route.id || ''), parties: route.parties || {}, cacheArtifactPath: cache?.artifactPath || '',
+      returnCarrierReservation: route.returnCarrierReservation || null,
       requiredContextBindings: Object.freeze((route.requiredClosure?.requirements || []).filter((entry) => entry.state === 'qualified' && entry.resolution?.kind === 'workspace-archive-entry').map((entry) => Object.freeze({ requirementId: String(entry.requirementId || ''), name: String(entry.name || ''), referenceTarget: String(entry.referenceTarget || ''), workspaceId: String(entry.resolution?.workspaceId || ''), workspaceRelativePath: String(entry.resolution?.workspaceRelativePath || entry.resolution?.innerPath || ''), bytes: Number(entry.resolution?.bytes || 0), sha256: String(entry.resolution?.sha256 || '') })))
     };
-    const pointer = finalizeFile({ path: pointerPath, kind: 'handoff-route-pointer', logicalKind: 'recipient-v2-package-v1-handoff-route-pointer', mediaType: 'text/markdown', transportFacts: recipientV2TransportFacts('handoff-route', pointerFacts), content: renderRecipientV2Pointer({ createdAt, parent: lineageParent, role: 'handoff-route', title: `Handoff Route Pointer — ${String(route.parties?.to || owningWorkspace.workspaceId || 'recipient')}`, summary: 'Qualified package-local Pointer to one authoritative Handoff inside one qualified carried Workspace representation.', prose: 'Follow only this Pointer carrier-ancestor closure for pre-Handoff package grounding, then resolve the authoritative Handoff path against the exact qualified carried Workspace representation.', currentRead: [{ label: 'Workspace Id', value: `\`${owningWorkspace.workspaceId}\`` }, { label: 'Workspace', value: `[${owningWorkspace.workspaceId}](${owningWorkspace.workspacePath})` }, { label: 'Route Id', value: `\`${String(route.id || '')}\`` }, ...(pointerFacts.cacheArtifactPath ? [{ label: 'Workspace Dependency Cache', value: `[cache](${pointerFacts.cacheArtifactPath})` }] : []), { label: 'Handoff Workspace Path', value: `\`${String(route.workspaceRelativePath || '')}\`` }], destinations: [{ label: 'Workspace representation containing the qualified Handoff route', display: `${owningWorkspace.archivePath} :: ${String(route.workspaceRelativePath || '')}`, target: owningWorkspace.archivePath }], facts: pointerFacts }) });
+    const pointer = finalizeFile({ path: pointerPath, kind: 'handoff-route-pointer', logicalKind: 'recipient-v2-package-v1-handoff-route-pointer', mediaType: 'text/markdown', transportFacts: recipientV2TransportFacts('handoff-route', pointerFacts), content: renderRecipientV2Pointer({ createdAt, parent: lineageParent, role: 'handoff-route', title: `Handoff Route Pointer — ${String(route.parties?.to || owningWorkspace.workspaceId || 'recipient')}`, summary: 'Qualified package-local Pointer to one authoritative Handoff inside one qualified carried Workspace representation.', prose: 'Follow only this Pointer carrier-ancestor closure for pre-Handoff package grounding, then resolve the authoritative Handoff path against the exact qualified carried Workspace representation.', currentRead: [{ label: 'Workspace Id', value: `\`${owningWorkspace.workspaceId}\`` }, { label: 'Workspace', value: `[${owningWorkspace.workspaceId}](${owningWorkspace.workspacePath})` }, { label: 'Route Id', value: `\`${String(route.id || '')}\`` }, ...(pointerFacts.cacheArtifactPath ? [{ label: 'Workspace Dependency Cache', value: `[cache](${pointerFacts.cacheArtifactPath})` }] : []), { label: 'Handoff Workspace Path', value: `\`${String(route.workspaceRelativePath || '')}\`` }, ...(route.returnCarrierReservation ? [{ label: 'Return Package Carrier Kind', value: `\`${String(route.returnCarrierReservation.carrierKind || '')}\`` }, ...(route.returnCarrierReservation.carrierKind === 'non-major' ? [{ label: 'Return Package Sibling Index', value: `\`${String(route.returnCarrierReservation.siblingIndex || '')}\`` }] : [])] : [])], destinations: [{ label: 'Workspace representation containing the qualified Handoff route', display: `${owningWorkspace.archivePath} :: ${String(route.workspaceRelativePath || '')}`, target: owningWorkspace.archivePath }], facts: pointerFacts }) });
     files.push(pointer);
-    topology.routes.push(Object.freeze({ pointerPath, workspaceId: owningWorkspace.workspaceId, workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), routeId: String(route.id || ''), sha256: String(route.sha256 || '') }));
+    topology.routes.push(Object.freeze({ pointerPath, workspaceId: owningWorkspace.workspaceId, workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''), routeId: String(route.id || ''), sha256: String(route.sha256 || ''), returnCarrierReservation: route.returnCarrierReservation || null }));
   }
 
   const readFacts = { format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, packageRootPath: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, entryArtifactPath: RECIPIENT_V2_READ_PATH, artifactSurface: 'tiinex.handoff.package.v1-plus-qualified-carried-material', routeAuthority: 'qualified-handoff-route-pointer-plus-exact-qualified-carried-handoff-bytes', routeSelectionAuthority: RECIPIENT_V2_ROUTE_SELECTION_AUTHORITY, siblingRouteInference: RECIPIENT_V2_SIBLING_ROUTE_INFERENCE, carrierLineage: carrier.lineage || null, pathParentProjection: true, pathAuthority: false };

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

@@ -71,7 +71,13 @@ export function deriveVisibleFacts({ file = null, markdown = '', schemaId = '',
       const closure = direct || generic;
       const handoffEntry = (closure?.parsed?.entries || []).find((entry) => entry.path === visible.handoffWorkspacePath) || null;
       const current = sectionText(markdown, 'Current Read');
-      return { ...base, workspaceId, workspaceArtifactPath: closure?.workspaceFile?.path || '', workspaceArtifactSha256: closure?.workspaceFile ? sha256Hex(packageFileBytes(closure.workspaceFile)) : '', archivePath: closure?.archiveFile?.path || '', archiveSha256: closure?.archiveFile ? sha256Hex(packageFileBytes(closure.archiveFile)) : '', sourceWorkspaceTargetInnerPath: closure?.workspaceArtifactInnerPath || '', sourceWorkspaceTargetSha256: closure?.sourceWorkspaceTargetSha256 || '', workspaceRelativeHandoffPath: visible.handoffWorkspacePath, handoffBytes: Number(handoffEntry?.bytes || 0), handoffSha256: String(handoffEntry?.sha256 || ''), routeId: visible.routeId || unquote(field(current, 'Route Id')), cacheArtifactPath: markdownTarget(field(current, 'Workspace Dependency Cache')), requiredContextBindings: Object.freeze([]) };
+      const returnCarrierReservation = visible.returnPackageCarrierKind
+        ? Object.freeze({
+            carrierKind: String(visible.returnPackageCarrierKind || ''),
+            ...(String(visible.returnPackageCarrierKind || '') === 'non-major' ? { siblingIndex: Number(visible.returnPackageSiblingIndex || 0) } : {})
+          })
+        : null;
+      return { ...base, workspaceId, workspaceArtifactPath: closure?.workspaceFile?.path || '', workspaceArtifactSha256: closure?.workspaceFile ? sha256Hex(packageFileBytes(closure.workspaceFile)) : '', archivePath: closure?.archiveFile?.path || '', archiveSha256: closure?.archiveFile ? sha256Hex(packageFileBytes(closure.archiveFile)) : '', sourceWorkspaceTargetInnerPath: closure?.workspaceArtifactInnerPath || '', sourceWorkspaceTargetSha256: closure?.sourceWorkspaceTargetSha256 || '', workspaceRelativeHandoffPath: visible.handoffWorkspacePath, handoffBytes: Number(handoffEntry?.bytes || 0), handoffSha256: String(handoffEntry?.sha256 || ''), routeId: visible.routeId || unquote(field(current, 'Route Id')), cacheArtifactPath: markdownTarget(field(current, 'Workspace Dependency Cache')), returnCarrierReservation, requiredContextBindings: Object.freeze([]) };
     }
     if (role === 'endpoint-role' || role === 'participant-role') {
       const targetPayload = visible.targetPayload || '';

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

@@ -16,6 +16,7 @@ import { projectRecipientV2EndpointRoles, projectRecipientV2ParticipantRoles, pr
 import { RECIPIENT_V2_PACKAGE_V1_FORMAT_ID, RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID } from './recipientV2.packageV1.constants.js';
 import { BOOTSTRAP_PACKAGE_ROLE, HANDOFF_PACKAGE_ROLE, parseHandoffPackageV1, validatePackageFields, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
 import { deriveVisibleFacts, validateRouteClosure } from './recipientV2.packageV1.inspect.helpers.js';
+import { qualifyDelegationReturnReservation } from './delegationReturnReservation.js';
 import { bootstrapCarrierProjection, workspaceCarrierProjection } from './recipientV2.packageV1.workspaceProjection.js';
 import { inspectRecipientV2WorkspaceSurface } from './recipientV2.inspect.workspaces.js';
 import { byteEqual, currentSchemaId, decodeUtf8, dedupeFindings, deepFreeze, oneFile } from './recipientV2.packageV1.shared.js';
@@ -195,7 +196,19 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
   } else {
     inspectEndpointRolePointers(endpointRolePointers, workspaceParts, caches, findings);
     inspectParticipantRolePointers(participantRolePointers, workspaceParts, caches, findings);
-    const routeSpecs = routePointers.map((pointer) => ({ workspaceId: String(pointer.facts?.workspaceId || ''), path: String(pointer.facts?.workspaceRelativeHandoffPath || ''), purpose: '' }));
+    const routeSpecs = routePointers.map((pointer) => {
+      const workspaceId = String(pointer.facts?.workspaceId || '');
+      const path = String(pointer.facts?.workspaceRelativeHandoffPath || '');
+      let returnCarrierReservation = pointer.facts?.returnCarrierReservation || null;
+      if (!returnCarrierReservation && workspaceId && path) {
+        const entry = resolveHandoffWorkspaceEntry(workspaceByteProvider, workspaceId, path);
+        if (entry.state === 'qualified') {
+          const preflight = qualifyDelegationReturnReservation({ markdown: decodeUtf8(entry.data) });
+          if (preflight.state === 'qualified' && preflight.returnExpected) returnCarrierReservation = Object.freeze({ carrierKind: preflight.carrierKind, siblingIndex: preflight.siblingIndex });
+        }
+      }
+      return { workspaceId, path, purpose: '', returnCarrierReservation };
+    });
     carrierProjection = buildHandoffCarrierProjection({ bundle: semanticBundle, descriptor, workspaceByteProvider, carrierLineage: lineage, routes: routeSpecs });
     if (carrierProjection.status !== 'ready') findings.push(finding('error', 'portable.handoff-package-v1.routes-unqualified', 'Selected Handoff Pointer does not independently resolve to qualified authoritative Handoff bytes.', { causes: carrierProjection.findings || [] }));
     inspectRoutePointers(routePointers, carrierProjection, workspaceParts, endpointRolePointers, participantRolePointers, index, findings);
@@ -244,7 +257,7 @@ export function inspectRecipientFacingV2PackageV1(bundle = {}, options = {}) {
     schema: 'tiinex.portable.recipient-facing-handoff-package-v1.inspection.v1', detected: Boolean(packageFile), status, format: RECIPIENT_V2_PACKAGE_V1_FORMAT_ID,
     rootArtifact: packageFile ? Object.freeze({ path: packageFile.path, schemaId: RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, sha256: sha256Hex(packageFileBytes(packageFile)), carrierLineage: lineage }) : null,
     readArtifact, workspaces: Object.freeze(workspaceParts.map((item) => Object.freeze({ workspaceId: item.workspaceId, coverage: String(item.representation?.coverage || item.facts?.coverage || 'complete'), bindingState: item.bindingState || String(item.representation?.bindingState || 'verified'), workspaceArtifactPath: item.artifact.path, workspaceArchivePath: item.archiveFile?.path || '', sourceWorkspaceTargetInnerPath: item.facts.sourceWorkspaceTargetInnerPath, sourceWorkspaceTargetSha256: item.facts.sourceWorkspaceTargetSha256 }))), sealedWorkspaces: Object.freeze(sealedWorkspaceBindings),
-    routes: projectRecipientV2Routes(routePointers, endpointRolePointers, participantRolePointers), endpointRoles: projectRecipientV2EndpointRoles(endpointRolePointers), participantRoles: projectRecipientV2ParticipantRoles(participantRolePointers),
+    routes: projectRecipientV2Routes(routePointers, endpointRolePointers, participantRolePointers, carrierProjection?.routes || []), endpointRoles: projectRecipientV2EndpointRoles(endpointRolePointers), participantRoles: projectRecipientV2ParticipantRoles(participantRolePointers),
     caches: Object.freeze(caches.map((cache) => Object.freeze({ workspaceId: String(cache.facts?.workspaceId || ''), artifactPath: cache.artifact.path, archivePath: cache.file.path, materials: cache.facts.materials || [] }))),
     bootstrapInspection, transportManifest: null, artifactFacts: Object.freeze(generatedArtifacts.map((item) => Object.freeze({ path: item.path, facts: item.facts }))), descriptor, workspaceByteProvider, carrierProjection, coldConsumerProjection,
     packageContract, findings: Object.freeze(finalFindings), findingSummary: Object.freeze({ errors: finalFindings.filter((item) => item.severity === 'error').length, findings: finalFindings.length }),

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

@@ -6,6 +6,8 @@ export function parseRecipientV2Pointer(markdown = '') {
     workspaceId: unquoteCode(fieldValue(current, 'Workspace Id')),
     workspacePayload: markdownTarget(fieldValue(current, 'Workspace Payload')),
     handoffWorkspacePath: unquoteCode(fieldValue(current, 'Handoff Workspace Path')),
+    returnPackageCarrierKind: unquoteCode(fieldValue(current, 'Return Package Carrier Kind')),
+    returnPackageSiblingIndex: unquoteCode(fieldValue(current, 'Return Package Sibling Index')),
     routeId: unquoteCode(fieldValue(current, 'Route Id')),
     routeSelection: fieldValue(current, 'Route Selection'),
     selectedRouteId: unquoteCode(fieldValue(current, 'Selected Route Id')),

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

@@ -0,0 +1,145 @@
+import { comparePortableSourceFrontiers, createPortableSourceFrontier } from '../comparison/sourceFrontierComparison.js';
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { handoffWorkspaceProviderForId, listHandoffWorkspaceEntries } from './workspaceByteProvider.js';
+
+export const PORTABLE_RECOVERY_ACCEPTANCE_AUDIT_SCHEMA_ID = 'tiinex.portable.recovery-acceptance-audit.v1';
+
+export function auditPortableRecoveryAcceptance(input = {}) {
+  const basisInspection = inspectRecipientFacingV2Topology(input.basis?.bundle || input.basis || {});
+  const candidateInspection = inspectRecipientFacingV2Topology(input.candidate?.bundle || input.candidate || {});
+  const findings = [];
+  if (String(basisInspection.status || '') !== 'valid') findings.push(finding('error', 'portable.recovery-acceptance.basis-unqualified', 'Recovery acceptance audit requires one independently qualified accepted-basis Handoff package.'));
+  if (String(candidateInspection.status || '') !== 'valid') findings.push(finding('error', 'portable.recovery-acceptance.candidate-unqualified', 'Recovery acceptance audit requires one independently qualified candidate Handoff package.'));
+  if (findings.some((item) => item.severity === 'error')) return auditResult('blocked', [], findings, basisInspection, candidateInspection, input);
+
+  const candidateIds = [...new Set((candidateInspection.workspaces || []).map((item) => normalizeId(item.workspaceId)).filter(Boolean))].sort();
+  const requestedIds = [...new Set([...(input.workspaceIds || input.selectedWorkspaceIds || [])].map(normalizeId).filter(Boolean))].sort();
+  const ids = requestedIds.length ? requestedIds : candidateIds;
+  const expectedRemovals = normalizeExpectedRemovals(input.expectedRemovals || {});
+  const workspaces = ids.map((workspaceId) => auditWorkspace({ workspaceId, basisInspection, candidateInspection, expectedRemovals, findings }));
+  for (const workspaceId of requestedIds) if (!candidateIds.includes(workspaceId)) findings.push(finding('error', 'portable.recovery-acceptance.workspace-unresolved', 'Explicitly requested candidate Workspace is not present in the qualified candidate carrier.', { workspaceId }));
+  const status = findings.some((item) => item.severity === 'error') || workspaces.some((item) => item.state !== 'ready') ? 'blocked' : 'ready';
+  return auditResult(status, workspaces, findings, basisInspection, candidateInspection, input);
+}
+
+function auditWorkspace({ workspaceId, basisInspection, candidateInspection, expectedRemovals, findings }) {
+  const basisProvider = handoffWorkspaceProviderForId(basisInspection.workspaceByteProvider, workspaceId);
+  const candidateProvider = handoffWorkspaceProviderForId(candidateInspection.workspaceByteProvider, workspaceId);
+  const candidateTopology = (candidateInspection.workspaces || []).find((item) => normalizeId(item.workspaceId) === workspaceId) || null;
+  const basisTopology = (basisInspection.workspaces || []).find((item) => normalizeId(item.workspaceId) === workspaceId) || null;
+  const reasons = [];
+  if (basisProvider.state !== 'qualified') {
+    reasons.push('basis-workspace-unqualified');
+    findings.push(finding('error', 'portable.recovery-acceptance.basis-workspace-unqualified', 'Accepted-basis Workspace bytes are unavailable or unqualified.', { workspaceId, state: String(basisProvider.state || '') }));
+  }
+  if (candidateProvider.state !== 'qualified') {
+    reasons.push('candidate-workspace-unqualified');
+    findings.push(finding('error', 'portable.recovery-acceptance.candidate-workspace-unqualified', 'Candidate Workspace bytes are unavailable or unqualified.', { workspaceId, state: String(candidateProvider.state || '') }));
+  }
+  const coverage = String(candidateTopology?.coverage || '');
+  if (coverage !== 'complete') {
+    reasons.push('candidate-workspace-not-complete');
+    findings.push(finding('error', 'portable.recovery-acceptance.candidate-workspace-not-complete', 'Master Recovery acceptance requires a complete candidate Workspace representation; bounded coverage cannot prove restart suitability.', { workspaceId, coverage }));
+  }
+  if (reasons.length) return freeze({ workspaceId, state: 'blocked', coverage, reasons: freeze(reasons), comparisonState: 'unavailable', counts: emptyCounts(), unexplainedRemovals: freeze([]), expectedRemovals: freeze([...expectedRemovals.get(workspaceId) || []]), materialization: materializationReceipt(candidateProvider, candidateTopology) });
+
+  const basis = frontierForProvider(workspaceId, basisProvider, 'accepted-basis');
+  const candidate = frontierForProvider(workspaceId, candidateProvider, 'candidate-recovery');
+  const comparison = comparePortableSourceFrontiers({ left: basis, right: candidate });
+  const workspace = (comparison.workspaces || []).find((item) => normalizeId(item.workspaceId) === workspaceId) || null;
+  if (comparison.status !== 'ready' || !workspace || !workspace.delta) {
+    reasons.push('workspace-comparison-unqualified');
+    findings.push(finding('error', 'portable.recovery-acceptance.workspace-comparison-unqualified', 'Accepted-basis to candidate Workspace comparison did not qualify.', { workspaceId, state: String(workspace?.state || comparison.state || '') }));
+    return freeze({ workspaceId, state: 'blocked', coverage, reasons: freeze(reasons), comparisonState: String(workspace?.state || comparison.state || ''), counts: emptyCounts(), unexplainedRemovals: freeze([]), expectedRemovals: freeze([...expectedRemovals.get(workspaceId) || []]), materialization: materializationReceipt(candidateProvider, candidateTopology) });
+  }
+
+  const removals = (workspace.delta.removed || []).map((entry) => String(entry.path || '')).filter(Boolean);
+  const expected = expectedRemovals.get(workspaceId) || new Set();
+  const unexplained = removals.filter((path) => !expected.has(path));
+  const staleExpected = [...expected].filter((path) => !removals.includes(path));
+  if (unexplained.length) {
+    reasons.push('unexplained-removals');
+    findings.push(finding('error', 'portable.recovery-acceptance.unexplained-removals', 'Candidate Recovery removes accepted-basis source paths without an explicit expected-removal disposition.', { workspaceId, count: unexplained.length, paths: unexplained }));
+  }
+  if (staleExpected.length) findings.push(finding('warning', 'portable.recovery-acceptance.expected-removal-stale', 'One or more declared expected removals are not removals in the candidate carrier.', { workspaceId, count: staleExpected.length, paths: staleExpected }));
+  return freeze({
+    workspaceId,
+    state: reasons.length ? 'blocked' : 'ready',
+    coverage,
+    reasons: freeze(reasons),
+    basisCoverage: String(basisTopology?.coverage || ''),
+    comparisonState: String(workspace.state || ''),
+    counts: freeze({
+      additions: Number(workspace.delta.counts?.added || 0),
+      removals: Number(workspace.delta.counts?.removed || 0),
+      byteChanged: Number(workspace.delta.counts?.byteChanged || 0),
+      unexplainedRemovals: unexplained.length,
+      totalChanges: Number(workspace.delta.counts?.total || 0)
+    }),
+    unexplainedRemovals: freeze(unexplained),
+    expectedRemovals: freeze([...expected]),
+    staleExpectedRemovals: freeze(staleExpected),
+    materialization: materializationReceipt(candidateProvider, candidateTopology)
+  });
+}
+
+function auditResult(status, workspaces, findings, basisInspection, candidateInspection, input) {
+  const unexplainedRemovalCount = workspaces.reduce((sum, item) => sum + Number(item.counts?.unexplainedRemovals || 0), 0);
+  const completeWorkspaceCount = workspaces.filter((item) => item.coverage === 'complete').length;
+  const allReady = workspaces.length > 0 && workspaces.every((item) => item.state === 'ready');
+  return freeze({
+    schema: PORTABLE_RECOVERY_ACCEPTANCE_AUDIT_SCHEMA_ID,
+    status,
+    state: status === 'ready' && allReady ? 'acceptance-audit-ready' : 'acceptance-audit-blocked',
+    basisQualification: String(basisInspection.status || 'invalid'),
+    candidateQualification: String(candidateInspection.status || 'invalid'),
+    selectionMode: (input.workspaceIds || input.selectedWorkspaceIds || []).length ? 'explicit-workspace-set' : 'all-candidate-workspaces',
+    workspaces: freeze(workspaces),
+    counts: freeze({ workspaces: workspaces.length, readyWorkspaces: workspaces.filter((item) => item.state === 'ready').length, completeWorkspaces: completeWorkspaceCount, unexplainedRemovals: unexplainedRemovalCount }),
+    suitability: freeze({
+      state: status === 'ready' && allReady && unexplainedRemovalCount === 0 ? 'restart-source-ready' : 'blocked',
+      candidateCarrierQualified: String(candidateInspection.status || '') === 'valid',
+      exactWorkspaceMaterializationQualified: workspaces.length > 0 && workspaces.every((item) => item.materialization?.state === 'qualified'),
+      allSelectedWorkspacesComplete: workspaces.length > 0 && completeWorkspaceCount === workspaces.length,
+      unexplainedRemovalCount,
+      gitCommitStateProven: false,
+      semanticAcceptanceGranted: false
+    }),
+    findings: freeze(findings),
+    boundary: 'Coarse Recovery acceptance audit over already-qualified carrier bytes. It decodes the exact candidate Workspace representations, compares them to one explicit accepted basis, and fails on unexplained source removals or incomplete coverage. It does not inspect a live checkout, prove Git cleanliness/committability, decide semantic correctness, authorize deletion, or grant Master Recovery acceptance; target landing still requires the separate exact source preflight.'
+  });
+}
+
+function frontierForProvider(workspaceId, provider, label) {
+  const entries = listHandoffWorkspaceEntries({ workspaces: [provider] }, workspaceId);
+  return createPortableSourceFrontier({ id: `${label}:${workspaceId}`, source: { kind: label, workspaceId }, workspaces: [{ workspaceId, entries: entries.map(entryIdentity) }] });
+}
+function materializationReceipt(provider, topology) {
+  return freeze({ state: provider?.state === 'qualified' ? 'qualified' : 'unqualified', mode: String(provider?.mode || ''), coverage: String(topology?.coverage || ''), entryCount: Array.isArray(provider?.entries) ? provider.entries.length : 0, archivePackagePath: String(provider?.archive?.packagePath || '') });
+}
+function normalizeExpectedRemovals(value) {
+  const source = value?.expectedRemovals && typeof value.expectedRemovals === 'object' ? value.expectedRemovals : value;
+  const out = new Map();
+  if (Array.isArray(source)) {
+    for (const item of source) {
+      const workspaceId = normalizeId(item?.workspaceId || item?.workspace || '');
+      const path = normalizePath(item?.path || '');
+      if (!workspaceId || !path) continue;
+      if (!out.has(workspaceId)) out.set(workspaceId, new Set());
+      out.get(workspaceId).add(path);
+    }
+    return out;
+  }
+  for (const [key, paths] of Object.entries(source || {})) {
+    const workspaceId = normalizeId(key);
+    if (!workspaceId) continue;
+    out.set(workspaceId, new Set((Array.isArray(paths) ? paths : [paths]).map(normalizePath).filter(Boolean)));
+  }
+  return out;
+}
+function normalizeId(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''); }
+function normalizePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').trim(); }
+function entryIdentity(entry = {}) { return freeze({ path: String(entry.path || entry.innerPath || ''), bytes: Number(entry.bytes ?? entry.size ?? 0), sha256: String(entry.sha256 || '').toLowerCase() }); }
+function emptyCounts() { return freeze({ additions: 0, removals: 0, byteChanged: 0, unexplainedRemovals: 0, totalChanges: 0 }); }
+function finding(severity, code, message, context = {}) { return freeze({ severity, code, message, context: freeze({ ...context }) }); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map((item) => freeze(item))); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }