@tiinex/core 0.3.0 → 0.5.0

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

@@ -21,7 +21,7 @@ export async function projectManufacturingRequirements({ handoff, workspaceId, h
     if (!runtime) throw new Error(`portable.handoff-manufacture.route.workspace-unresolved:${routeWorkspaceId}`);
     const routeMarkdown = routeWorkspaceId === workspaceId && routePath === handoffPath
       ? handoff.markdown
-      : await readWorkspaceText(runtime.root, routePath, 'portable.handoff-manufacture.route.path');
+      : await readWorkspaceRuntimeText(runtime, routePath, 'portable.handoff-manufacture.route.path');
     const projected = routeWorkspaceId === workspaceId && routePath === handoffPath
       ? primary
       : projectHandoffMaterialRequirements({ id: routePath, path: routePath, semanticStatus: 'unknown', markdown: routeMarkdown });
@@ -75,7 +75,7 @@ export async function resolveWorkspaceRequirementMaterials(requirements, workspa
       const targetRuntime = workspaceRuntimeById.get(targetWorkspaceId);
       const entry = targetRuntime ? entryFromEnumeration(targetRuntime.enumeration, targetPath) : null;
       if (entry) {
-        out.push(materialCandidateFromWorkspaceEntry(requirement, targetWorkspaceId, targetPath, entry, targetRuntime.enumeration));
+        out.push(materialCandidateFromWorkspaceEntry(requirement, targetWorkspaceId, targetPath, entry, targetRuntime.enumeration, targetRuntime));
         continue;
       }
     }
@@ -85,20 +85,28 @@ export async function resolveWorkspaceRequirementMaterials(requirements, workspa
     if (workspaceQualified) {
       const targetRuntime = workspaceRuntimeById.get(workspaceQualified.workspaceId);
       const entry = targetRuntime ? entryFromEnumeration(targetRuntime.enumeration, workspaceQualified.path) : null;
-      if (entry) out.push(materialCandidateFromWorkspaceEntry(requirement, workspaceQualified.workspaceId, workspaceQualified.path, entry, targetRuntime.enumeration));
+      if (entry) out.push(materialCandidateFromWorkspaceEntry(requirement, workspaceQualified.workspaceId, workspaceQualified.path, entry, targetRuntime.enumeration, targetRuntime));
       continue;
     }
     if (isExternalReference(target) || target.startsWith('#')) continue;
     const routeWorkspaceId = String(requirement.routeWorkspaceId || [...workspaceRuntimeById.keys()][0] || '');
     const runtime = workspaceRuntimeById.get(routeWorkspaceId);
     if (!runtime) continue;
+    if (!runtime.root) {
+      const relative = resolveRelativeWorkspaceTarget(String(requirement.routePath || ''), target);
+      if (!relative) continue;
+      const entry = entryFromEnumeration(runtime.enumeration, relative);
+      if (!entry) continue;
+      out.push(materialCandidateFromWorkspaceEntry(requirement, routeWorkspaceId, relative, entry, runtime.enumeration, runtime));
+      continue;
+    }
     const handoffDir = path.dirname(path.resolve(runtime.root, String(requirement.routePath || '')));
     const absolute = path.resolve(handoffDir, decodeURIComponent(target.split('#')[0]));
     if (!inside(runtime.root, absolute)) continue;
     const relative = normalizeRelativePath(path.relative(runtime.root, absolute));
     const entry = entryFromEnumeration(runtime.enumeration, relative);
     if (!entry) continue;
-    out.push(materialCandidateFromWorkspaceEntry(requirement, routeWorkspaceId, relative, entry, runtime.enumeration));
+    out.push(materialCandidateFromWorkspaceEntry(requirement, routeWorkspaceId, relative, entry, runtime.enumeration, runtime));
   }
   return out;
 }
@@ -207,7 +215,7 @@ async function resolveDerivedDependencyMaterial(requirement, sourceMaterial, wor
   if (requirement.targetWorkspaceId && requirement.targetPath) {
     const runtime = workspaceRuntimeById.get(String(requirement.targetWorkspaceId));
     const entry = runtime ? entryFromEnumeration(runtime.enumeration, requirement.targetPath) : null;
-    if (entry) return materialCandidateFromWorkspaceEntry(requirement, requirement.targetWorkspaceId, requirement.targetPath, entry, runtime.enumeration);
+    if (entry) return materialCandidateFromWorkspaceEntry(requirement, requirement.targetWorkspaceId, requirement.targetPath, entry, runtime.enumeration, runtime);
   }
   const target = String(requirement.reference?.target || '');
   const sourcePath = String(sourceMaterial.provenance?.sourcePath || '').trim();
@@ -291,7 +299,19 @@ export function entryFromEnumeration(enumeration = {}, relative = '') {
   return matches.length === 1 ? matches[0] : null;
 }
 
-export function materialCandidateFromWorkspaceEntry(requirement, workspaceId, relative, entry, enumeration) {
+export function materialCandidateFromWorkspaceEntry(requirement, workspaceId, relative, entry, enumeration, runtime = {}) {
+  const packageParentProvider = String(runtime.provider || '').startsWith('qualified-package-parent-workspace');
+  const materializationSource = enumeration?.materialization?.source || {};
+  const provenance = packageParentProvider
+    ? Object.freeze({
+        workspaceId,
+        path: relative,
+        boundary: '.',
+        parentPackagePath: String(materializationSource.parentPackagePath || ''),
+        parentPackageSha256: String(materializationSource.parentPackageSha256 || ''),
+        parentWorkspaceArchivePath: String(materializationSource.parentWorkspaceArchivePath || '')
+      })
+    : Object.freeze({ workspaceId, path: relative, boundary: '.' });
   return Object.freeze({
     requirementId: requirement.id,
     referenceTarget: String(requirement.reference?.target || requirement.referenceTarget || ''),
@@ -300,10 +320,14 @@ export function materialCandidateFromWorkspaceEntry(requirement, workspaceId, re
     bytes: entry.bytes,
     sha256: entry.sha256,
     mediaType: entry.mediaType,
-    providerId: 'node-workspace-enumerator',
-    providerKind: 'qualified-local-workspace',
-    provenance: Object.freeze({ workspaceId, path: relative, boundary: '.' }),
-    authority: Object.freeze({ localIdentityQualified: true, completenessEvidenceFingerprint: enumeration.evidence.entriesFingerprint })
+    providerId: packageParentProvider ? 'package-parent-workspace-enumerator' : 'node-workspace-enumerator',
+    providerKind: packageParentProvider ? 'qualified-package-parent-workspace' : 'qualified-local-workspace',
+    provenance,
+    authority: Object.freeze({
+      localIdentityQualified: true,
+      packageParentWorkspaceQualified: packageParentProvider,
+      completenessEvidenceFingerprint: enumeration.evidence.entriesFingerprint
+    })
   });
 }
 
@@ -316,7 +340,7 @@ function materialCandidateFromWorkspaceBinding(requirement, binding, workspaceRu
   const runtime = workspaceRuntimeById.get(workspaceId);
   const entry = runtime ? entryFromEnumeration(runtime.enumeration, relative) : null;
   if (!entry) return null;
-  return materialCandidateFromWorkspaceEntry(requirement, workspaceId, relative, entry, runtime.enumeration);
+  return materialCandidateFromWorkspaceEntry(requirement, workspaceId, relative, entry, runtime.enumeration, runtime);
 }
 
 async function materialCandidateFromBinding(requirement, binding, workspaceRoot) {
@@ -343,6 +367,15 @@ async function readWorkspaceText(root, relative, code) {
   return readFile(absolute, 'utf8');
 }
 
+async function readWorkspaceRuntimeText(runtime, relative, code) {
+  if (runtime?.root) return readWorkspaceText(runtime.root, relative, code);
+  const entry = entryFromEnumeration(runtime?.enumeration, relative);
+  if (!entry) throw new Error(`${code}.unresolved`);
+  const markdown = decodeUtf8(entry.data);
+  if (!markdown) throw new Error(`${code}.non-text`);
+  return markdown;
+}
+
 
 export function normalizeRelativePath(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '').split('/').filter((part) => part && part !== '.').join('/'); }
 function inside(root, absolute) { const relative = path.relative(root, absolute); return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative)); }

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

@@ -1,4 +1,5 @@
 import { parseArtifactMarkdown } from '../../../../artifacts/artifact.parse.js';
+import { parseWorkspaceQualifiedReference } from '../../handoff/workspaceQualifiedReference.js';
 import { safeWorkspaceToken } from './handoff.manufacture.multiRoot.js';
 import {
   decodeUtf8,
@@ -136,7 +137,7 @@ export function expandBoundedParentBoundaryClosure(input = {}) {
           fields: Object.freeze({ RouteWorkspace: workspaceId, RoutePath: sourcePath, TargetWorkspace: workspaceId, TargetPath: parentPath, Reference: reference })
         });
         dependencies.push(requirement);
-        materials.push(materialCandidateFromWorkspaceEntry(requirement, workspaceId, parentPath, parentEntry, runtime.enumeration));
+        materials.push(materialCandidateFromWorkspaceEntry(requirement, workspaceId, parentPath, parentEntry, runtime.enumeration, runtime));
       }
     }
   }
@@ -145,3 +146,97 @@ export function expandBoundedParentBoundaryClosure(input = {}) {
     materials: Object.freeze(materials)
   });
 }
+
+export function expandRouteParentBoundaryClosure(input = {}) {
+  const requirements = input.requirements || {};
+  const dependencies = [...(requirements.dependencies || [])];
+  const materials = [...(input.materials || [])];
+  const materializationByWorkspaceId = new Map((input.workspaceMaterializations || []).map((item) => [String(item.id || item.workspaceId || ''), item]));
+  const seenRequirementIds = new Set(dependencies.map((item) => String(item.id || '')));
+  const seenRouteTargets = new Set(dependencies.map((item) => `${String(item.routeWorkspaceId || '')}\0${normalizeRelativePath(item.routePath || '')}\0${String(item.targetWorkspaceId || '')}\0${normalizeRelativePath(item.targetPath || '')}`));
+
+  for (const route of input.routeSpecs || []) {
+    const routeWorkspaceId = String(route.workspaceId || '').trim();
+    const routePath = normalizeRelativePath(route.path || route.workspaceRelativePath || '');
+    if (!routeWorkspaceId || !routePath) continue;
+    let currentWorkspaceId = routeWorkspaceId;
+    let currentPath = routePath;
+    const visited = new Set();
+    for (let depth = 0; depth < 256; depth += 1) {
+      const visitKey = `${currentWorkspaceId}\0${currentPath}`;
+      if (visited.has(visitKey)) break;
+      visited.add(visitKey);
+      const runtime = input.workspaceRuntimeById?.get(currentWorkspaceId);
+      const currentEntry = runtime ? entryFromEnumeration(runtime.enumeration, currentPath) : null;
+      if (!currentEntry) break;
+      const markdown = decodeUtf8(currentEntry.data);
+      if (!markdown) break;
+      let parent;
+      try { parent = parseArtifactMarkdown(markdown).envelope?.parent || {}; } catch { break; }
+      const reference = String(parent.trace || (parent.originEntries || []).find((item) => String(item?.label || '').trim() === 'relative')?.target || '').trim();
+      if (!reference) break;
+
+      let targetWorkspaceId = currentWorkspaceId;
+      let targetPath = '';
+      const qualified = parseWorkspaceQualifiedReference(reference);
+      if (qualified) {
+        targetWorkspaceId = qualified.workspaceId;
+        targetPath = normalizeRelativePath(qualified.path);
+      } else {
+        if (isExternalReference(reference) || reference.startsWith('#')) break;
+        targetPath = resolveRelativeWorkspaceTarget(currentPath, reference);
+      }
+      if (!targetWorkspaceId || !targetPath) break;
+
+      const targetRuntime = input.workspaceRuntimeById?.get(targetWorkspaceId);
+      const targetEntry = targetRuntime ? entryFromEnumeration(targetRuntime.enumeration, targetPath) : null;
+      const targetMaterialization = materializationByWorkspaceId.get(targetWorkspaceId);
+      const targetAlreadyCarried = workspaceMaterializationIncludesPath(targetMaterialization, targetPath);
+      const routeTargetKey = `${routeWorkspaceId}\0${routePath}\0${targetWorkspaceId}\0${targetPath}`;
+      if (!targetAlreadyCarried && !seenRouteTargets.has(routeTargetKey)) {
+        seenRouteTargets.add(routeTargetKey);
+        const id = `route-parent:${safeWorkspaceToken(routeWorkspaceId)}:${sha256Text(`${routePath}\0${currentWorkspaceId}\0${currentPath}\0${targetWorkspaceId}\0${targetPath}`).slice(0, 20)}`;
+        if (!seenRequirementIds.has(id)) {
+          seenRequirementIds.add(id);
+          const requirement = Object.freeze({
+            id,
+            name: `Route Parent boundary for ${currentWorkspaceId}:${currentPath}`,
+            classification: 'parent-boundary',
+            material: 'exact detached Parent continuity dependency',
+            purpose: 'preserve selected Handoff route continuity across a Workspace carriage boundary without requiring complete unrelated Workspace carriage',
+            availability: 'declared',
+            materialReference: reference,
+            reference: Object.freeze({ form: qualified ? 'parent-workspace-qualified-target' : 'parent-relative-target', raw: reference, label: '', target: reference, exactTargetDeclared: true }),
+            routeWorkspaceId,
+            routePath,
+            sourceWorkspaceId: currentWorkspaceId,
+            sourcePath: currentPath,
+            targetWorkspaceId,
+            targetPath,
+            sourceRequirementId: '',
+            fields: Object.freeze({ RouteWorkspace: routeWorkspaceId, RoutePath: routePath, SourceWorkspace: currentWorkspaceId, SourcePath: currentPath, TargetWorkspace: targetWorkspaceId, TargetPath: targetPath, Reference: reference })
+          });
+          dependencies.push(requirement);
+          if (targetEntry) materials.push(materialCandidateFromWorkspaceEntry(requirement, targetWorkspaceId, targetPath, targetEntry, targetRuntime.enumeration, targetRuntime));
+        }
+      }
+      if (!targetEntry) break;
+      currentWorkspaceId = targetWorkspaceId;
+      currentPath = targetPath;
+    }
+  }
+
+  return Object.freeze({
+    requirements: Object.freeze({ ...requirements, dependencies: Object.freeze(dependencies), counts: Object.freeze({ ...(requirements.counts || {}), dependencies: dependencies.length }) }),
+    materials: Object.freeze(materials)
+  });
+}
+
+function workspaceMaterializationIncludesPath(materialization = null, targetPath = '') {
+  if (!materialization) return false;
+  const state = String(materialization.state || materialization.materialization || '');
+  if (state === 'complete') return true;
+  if (state !== 'bounded') return false;
+  const normalized = normalizeRelativePath(targetPath);
+  return (materialization.includedEntries || materialization.entries || []).some((entry) => normalizeRelativePath(entry.path || '') === normalized);
+}

package/src/tooling/portable/adapters/node/sourceFrontierComparison.js

@@ -0,0 +1,194 @@
+import path from 'node:path';
+import { enumerateNodeWorkspace } from './handoff.manufacture.enumeration.js';
+import { loadNodePortableInput } from '../../input/node.input.js';
+import { inspectRecipientFacingV2Topology } from '../../handoff/recipientV2.inspect.js';
+import { handoffWorkspaceProviderForId, listHandoffWorkspaceEntries } from '../../handoff/workspaceByteProvider.js';
+import { safeWorkspaceToken } from './handoff.manufacture.multiRoot.js';
+import { portableFinding } from '../../findings.js';
+import {
+  PORTABLE_SOURCE_FRONTIER_SCHEMA_ID,
+  compareOrReconcilePortableSourceFrontiers,
+  createPortableSourceFrontier
+} from '../../comparison/sourceFrontierComparison.js';
+
+export const PORTABLE_NODE_SOURCE_FRONTIER_INPUT_SCHEMA_ID = 'tiinex.portable.node-source-frontier-input.v1';
+
+export async function prepareNodeSourceFrontierComparisonInput(input = {}, options = {}) {
+  if (input.base || input.incoming || input.current) {
+    if (!input.base || !input.incoming || !input.current) return { base: invalidFrontier('base', 'three-way-input-incomplete'), incoming: invalidFrontier('incoming', 'three-way-input-incomplete'), current: invalidFrontier('current', 'three-way-input-incomplete') };
+    const [base, incoming, current] = await Promise.all([
+      prepareNodeSourceFrontier(input.base, { ...options, side: 'base' }),
+      prepareNodeSourceFrontier(input.incoming, { ...options, side: 'incoming' }),
+      prepareNodeSourceFrontier(input.current, { ...options, side: 'current' })
+    ]);
+    return Object.freeze({ base, incoming, current });
+  }
+  const [left, right] = await Promise.all([
+    prepareNodeSourceFrontier(input.left, { ...options, side: 'left' }),
+    prepareNodeSourceFrontier(input.right, { ...options, side: 'right' })
+  ]);
+  return Object.freeze({ left, right });
+}
+
+export async function compareNodeSourceFrontiers(input = {}, options = {}) {
+  const normalized = await prepareNodeSourceFrontierComparisonInput(input, options);
+  return compareOrReconcilePortableSourceFrontiers(normalized);
+}
+
+export async function prepareNodeSourceFrontier(descriptor = {}, options = {}) {
+  if (descriptor?.schema === PORTABLE_SOURCE_FRONTIER_SCHEMA_ID) return createPortableSourceFrontier(descriptor);
+  const kind = String(descriptor?.kind || '').trim().toLowerCase();
+  if (!kind) return invalidFrontier(options.side || '', 'input-kind-required', portableFinding('error', 'portable.source-frontier.node.kind-required', 'Node source-frontier input requires an explicit kind; filesystem/package type is never guessed.', { side: options.side || '' }));
+  if (kind === 'local-workspace') return frontierFromLocalWorkspace(descriptor, options);
+  if (kind === 'local-frontier') return frontierFromLocalWorkspaceSet(descriptor, options);
+  if (kind === 'handoff-package') return frontierFromHandoffPackage(descriptor, options);
+  if (kind === 'qualified-workspace-provider') return frontierFromQualifiedProvider(descriptor, options);
+  if (kind === 'normalized-frontier') return createPortableSourceFrontier(descriptor.frontier || descriptor.value || {});
+  return invalidFrontier(options.side || '', 'input-kind-unsupported', portableFinding('error', 'portable.source-frontier.node.kind-unsupported', 'Node source-frontier input kind is unsupported.', { kind, side: options.side || '' }));
+}
+
+async function frontierFromLocalWorkspace(descriptor, options) {
+  const rootText = String(descriptor.root || descriptor.path || descriptor.workspaceRoot || '').trim();
+  if (!rootText) return invalidFrontier(options.side || '', 'local-workspace-root-required', portableFinding('error', 'portable.source-frontier.node.local-root-required', 'Local Workspace comparison input requires an explicit root path.', { side: options.side || '' }));
+  const root = path.resolve(rootText);
+  const workspaceId = safeWorkspaceToken(descriptor.workspaceId || descriptor.id || path.basename(root) || 'workspace');
+  try {
+    const enumeration = await enumerateNodeWorkspace(root, enumerationOptions(descriptor, options, workspaceId));
+    if (enumeration.status !== 'qualified-complete') return invalidFrontier(options.side || '', `local-enumeration-${enumeration.status}`, portableFinding('error', 'portable.source-frontier.node.local-enumeration-unqualified', 'Local Workspace source enumeration did not qualify as complete under the shared manufacture snapshot contract.', { workspaceId, status: enumeration.status }));
+    return createPortableSourceFrontier({
+      id: descriptor.label || `${options.side || 'input'}:${workspaceId}`,
+      source: { kind: 'local-workspace', ref: root, snapshotContract: 'shared-handoff-manufacture-node-enumeration-v1' },
+      workspaces: [workspaceFromEnumeration(workspaceId, enumeration, root)],
+      boundary: 'Local source is enumerated by the same deterministic Node Workspace enumerator used by Handoff manufacture; excluded directories and symlink policy therefore remain shared.'
+    });
+  } catch (error) {
+    return createPortableSourceFrontier({ id: descriptor.label || options.side || '', state: 'qualification-error', source: { kind: 'local-workspace', ref: root }, workspaces: [{ workspaceId, state: 'unavailable', reason: 'local-workspace-read-failed', source: { kind: 'local-workspace', ref: root } }], findings: [portableFinding('error', 'portable.source-frontier.node.local-read-failed', 'Local Workspace source could not be enumerated.', { workspaceId, ref: root, detail: String(error?.message || error || '') })] });
+  }
+}
+
+async function frontierFromLocalWorkspaceSet(descriptor, options) {
+  const specs = Array.isArray(descriptor.workspaces) ? descriptor.workspaces : [];
+  if (!specs.length) return invalidFrontier(options.side || '', 'local-frontier-workspaces-required', portableFinding('error', 'portable.source-frontier.node.local-frontier-empty', 'Local multi-Workspace frontier requires at least one explicit Workspace root binding.', { side: options.side || '' }));
+  const results = await Promise.all(specs.map(async (spec, index) => {
+    const rootText = String(spec.root || spec.path || spec.workspaceRoot || '').trim();
+    if (!rootText) return { workspaceId: String(spec.workspaceId || spec.id || `workspace-${index + 1}`), state: 'unavailable', reason: 'local-workspace-root-required', source: { kind: 'local-workspace' }, finding: portableFinding('error', 'portable.source-frontier.node.local-root-required', 'Local frontier Workspace binding requires an explicit root path.', { index }) };
+    const root = path.resolve(rootText);
+    const workspaceId = safeWorkspaceToken(spec.workspaceId || spec.id || '');
+    if (!spec.workspaceId && !spec.id) return { workspaceId: `unresolved-${index + 1}`, state: 'qualification-error', reason: 'workspace-id-required', source: { kind: 'local-workspace', ref: root }, finding: portableFinding('error', 'portable.source-frontier.node.local-frontier-id-required', 'Every local multi-Workspace root requires an explicit Workspace id.', { ref: root }) };
+    try {
+      const enumeration = await enumerateNodeWorkspace(root, enumerationOptions({ ...descriptor, ...spec }, options, workspaceId));
+      if (enumeration.status !== 'qualified-complete') return { workspaceId, state: 'qualification-error', reason: `enumeration-${enumeration.status}`, source: { kind: 'local-workspace', ref: root }, finding: portableFinding('error', 'portable.source-frontier.node.local-enumeration-unqualified', 'Local frontier Workspace did not qualify as a complete manufacture-equivalent snapshot.', { workspaceId, status: enumeration.status }) };
+      return workspaceFromEnumeration(workspaceId, enumeration, root);
+    } catch (error) {
+      return { workspaceId, state: 'unavailable', reason: 'local-workspace-read-failed', source: { kind: 'local-workspace', ref: root }, finding: portableFinding('error', 'portable.source-frontier.node.local-read-failed', 'Local frontier Workspace source could not be enumerated.', { workspaceId, ref: root, detail: String(error?.message || error || '') }) };
+    }
+  }));
+  const findings = results.map((item) => item.finding).filter(Boolean);
+  return createPortableSourceFrontier({
+    id: descriptor.label || options.side || 'local-frontier',
+    state: findings.some((item) => item.severity === 'error') ? 'qualification-error' : 'qualified',
+    source: { kind: 'local-frontier', workspaceCount: specs.length, snapshotContract: 'shared-handoff-manufacture-node-enumeration-v1' },
+    workspaces: results.map(({ finding, ...workspace }) => workspace),
+    findings,
+    boundary: 'Explicit local multi-Workspace roots, each enumerated by the shared Handoff-manufacture Workspace snapshot contract. Workspace ids are never inferred across the multi-root boundary.'
+  });
+}
+
+async function frontierFromHandoffPackage(descriptor, options) {
+  const packagePathText = String(descriptor.path || descriptor.packagePath || descriptor.root || '').trim();
+  if (!packagePathText) return invalidFrontier(options.side || '', 'handoff-package-path-required', portableFinding('error', 'portable.source-frontier.node.package-path-required', 'Handoff-package comparison input requires an explicit package path.', { side: options.side || '' }));
+  const packagePath = path.resolve(packagePathText);
+  let material;
+  try {
+    material = await loadNodePortableInput([packagePath], { maxFiles: descriptor.maxCarrierFiles || options.maxCarrierFiles || 10000, maxTextBytes: descriptor.maxTextBytes || options.maxTextBytes || 16 * 1024 * 1024 });
+  } catch (error) {
+    return invalidFrontier(options.side || '', 'handoff-package-read-failed', portableFinding('error', 'portable.source-frontier.node.package-read-failed', 'Handoff package could not be read by current trusted Core Tooling.', { ref: packagePath, detail: String(error?.message || error || '') }));
+  }
+  const loaderErrors = (material.findings || []).filter((item) => item.severity === 'error');
+  const inspection = inspectRecipientFacingV2Topology(material);
+  if (loaderErrors.length || inspection.status !== 'valid') {
+    return createPortableSourceFrontier({
+      id: descriptor.label || options.side || '', state: 'qualification-error', source: { kind: 'handoff-package', ref: packagePath, qualification: inspection.status || 'invalid' }, workspaces: [],
+      findings: [...loaderErrors, ...(inspection.findings || []).filter((item) => item.severity === 'error').map((item) => portableFinding('error', item.code || 'portable.source-frontier.package-unqualified', item.message || 'Handoff package qualification failed.', { ref: item.path || packagePath }))],
+      boundary: 'Received Handoff package failed current trusted Core package qualification; no Workspace source paths are projected for comparison.'
+    });
+  }
+
+  const availableIds = new Set([...(inspection.workspaces || []).map((item) => String(item.workspaceId || '')), ...(inspection.sealedWorkspaces || []).map((item) => String(item.workspaceId || ''))].filter(Boolean));
+  const selectors = normalizeSelectors(descriptor.workspaceIds || descriptor.select || descriptor.workspaces);
+  const ids = selectors.length ? selectors : [...availableIds].sort();
+  const openedById = new Map((descriptor.openedWorkspaces || []).map((item) => [String(item?.workspaceId || ''), item]).filter(([id]) => id));
+  const sealedById = new Map((inspection.sealedWorkspaces || []).map((item) => [String(item.workspaceId || ''), item]).filter(([id]) => id));
+  const workspaces = ids.map((workspaceId) => {
+    if (!availableIds.has(workspaceId)) return { workspaceId, state: 'unavailable', reason: 'workspace-not-carried', source: { kind: 'handoff-package', ref: packagePath } };
+    const sealedBinding = sealedById.get(workspaceId) || null;
+    const opened = openedById.get(workspaceId) || null;
+    if (sealedBinding && authorizedOpenMatchesSealedBinding(opened, sealedBinding, workspaceId)) {
+      const normalized = workspaceFromProvider(workspaceId, opened.provider, { kind: 'authorized-opened-workspace-provider', packageRef: packagePath });
+      if (normalized.state === 'qualified') return normalized;
+    }
+    if (sealedBinding) return { workspaceId, state: 'locked', qualification: 'locked-qualified-sealed-binding', reason: opened ? 'authorized-open-result-does-not-match-sealed-binding' : 'password-sealed-workspace-not-opened', source: { kind: 'handoff-package', ref: packagePath, binding: 'password-sealed-workspace-byte-tree' } };
+    return workspaceFromProvider(workspaceId, inspection.workspaceByteProvider, { kind: 'qualified-handoff-package-workspace', packageRef: packagePath });
+  });
+  return createPortableSourceFrontier({
+    id: descriptor.label || options.side || path.basename(packagePath),
+    source: { kind: 'handoff-package', ref: packagePath, qualification: 'qualified-current-tooling', format: String(inspection.format || '') },
+    workspaces,
+    boundary: 'Handoff inputs are inspected by the receiver current trusted Core Tooling. Clear qualified Workspace providers expose exact path/hash source; sealed bindings remain locked unless caller supplies an already-authorized qualified opened provider.'
+  });
+}
+
+function authorizedOpenMatchesSealedBinding(opened, sealedBinding, workspaceId) {
+  if (!opened || opened.state !== 'opened-qualified' || !opened.provider) return false;
+  if (String(opened.workspaceId || '') !== String(workspaceId || '')) return false;
+  if (String(opened.workspaceArtifactPath || '') !== String(sealedBinding.workspaceArtifactPath || '')) return false;
+  if (String(opened.workspaceArtifactSha256 || '').toLowerCase() !== String(sealedBinding.workspaceArtifactSha256 || '').toLowerCase()) return false;
+  return true;
+}
+
+function frontierFromQualifiedProvider(descriptor, options) {
+  const provider = descriptor.provider || descriptor.value || null;
+  const providerIds = Array.isArray(provider?.workspaces) ? provider.workspaces.map((item) => String(item?.id || '')).filter(Boolean) : [];
+  const selectors = normalizeSelectors(descriptor.workspaceIds || descriptor.select || descriptor.workspaces);
+  const ids = selectors.length ? selectors : providerIds.sort();
+  if (!provider || !ids.length) return invalidFrontier(options.side || '', 'provider-unavailable', portableFinding('error', 'portable.source-frontier.node.provider-unavailable', 'Qualified Workspace provider input must expose at least one explicit or discoverable Workspace id.', { side: options.side || '' }));
+  return createPortableSourceFrontier({ id: descriptor.label || options.side || 'qualified-provider', source: { kind: 'qualified-workspace-provider' }, workspaces: ids.map((id) => workspaceFromProvider(id, provider, { kind: 'qualified-workspace-provider' })) });
+}
+
+function workspaceFromEnumeration(workspaceId, enumeration, root) {
+  return {
+    workspaceId, state: 'qualified', qualification: 'qualified-complete-manufacture-enumeration', source: { kind: 'local-workspace', ref: root },
+    entries: (enumeration.materialization?.includedEntries || []).map((entry) => ({ path: entry.path, bytes: entry.bytes, sha256: entry.sha256 })),
+    evidence: { ...(enumeration.evidence || {}), sourceSelection: 'enumerateNodeWorkspace' }
+  };
+}
+
+function workspaceFromProvider(workspaceId, provider, source) {
+  const workspace = handoffWorkspaceProviderForId(provider, workspaceId);
+  if (!workspace || workspace.state !== 'qualified') return { workspaceId, state: workspace?.state === 'locked' ? 'locked' : 'qualification-error', qualification: String(workspace?.state || 'provider-unresolved'), reason: 'qualified-workspace-provider-unresolved', source };
+  const entries = listHandoffWorkspaceEntries(provider, workspaceId);
+  return {
+    workspaceId, state: 'qualified', qualification: 'qualified-exact-package-provider', source,
+    entries: entries.map((entry) => ({ path: entry.path || entry.innerPath, bytes: entry.bytes, sha256: entry.sha256 })),
+    evidence: { providerSchema: String(provider.schema || ''), providerState: String(provider.status || ''), workspaceMode: String(workspace.mode || ''), coverage: String(workspace.materialization?.materialization || workspace.binding?.coverage || '') }
+  };
+}
+
+function enumerationOptions(descriptor, options, workspaceId) {
+  return {
+    workspaceId,
+    workspaceTitle: String(descriptor.workspaceTitle || descriptor.title || workspaceId),
+    sourceMetadata: descriptor.sourceMetadata || {},
+    excludeDirectories: descriptor.excludeDirectories || options.excludeDirectories,
+    maxFiles: descriptor.maxFiles || options.maxFiles
+  };
+}
+
+function normalizeSelectors(value) {
+  const list = Array.isArray(value) ? value : value ? String(value).split(',') : [];
+  return [...new Set(list.map((item) => typeof item === 'string' ? item.trim() : String(item?.workspaceId || item?.id || '').trim()).filter(Boolean))].sort();
+}
+
+function invalidFrontier(id, reason, finding = null) {
+  return createPortableSourceFrontier({ id, state: 'qualification-error', source: { kind: 'unavailable', reason }, workspaces: [], findings: [finding || portableFinding('error', 'portable.source-frontier.node.input-invalid', 'Node source-frontier input is invalid.', { reason })] });
+}