@tiinex/core 0.12.0 → 0.14.0

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

@@ -2,17 +2,25 @@ import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { sha256Hex } from '../../../../export/package.bytes.js';
 import { safeWorkspaceToken, serializableMetadata } from './handoff.manufacture.multiRoot.js';
+import {
+  DEFAULT_PORTABLE_SOURCE_EXCLUDED_DIRECTORIES,
+  DEFAULT_PORTABLE_SOURCE_EXCLUDED_RELATIVE_PATHS,
+  portableSourceEligibilityPolicy,
+  qualifyPortableSourcePath
+} from '../../source/sourceEligibility.js';
 
 export const PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID = 'tiinex.portable.node-workspace-enumeration.v1';
-export const DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES = Object.freeze(['.git', '.tiinex', 'node_modules', '.site-publish', '.release', '.outgoing-handoff-packages']);
-export const DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_RELATIVE_PATHS = Object.freeze(['.vscode/link']);
+export const DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES = DEFAULT_PORTABLE_SOURCE_EXCLUDED_DIRECTORIES;
+export const DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_RELATIVE_PATHS = DEFAULT_PORTABLE_SOURCE_EXCLUDED_RELATIVE_PATHS;
 const DEFAULT_MAX_FILES = 10000;
 
 export async function enumerateNodeWorkspace(rootInput = '.', options = {}) {
   const root = path.resolve(String(rootInput || '.'));
   const maxFiles = positiveInteger(options.maxFiles, DEFAULT_MAX_FILES);
-  const excluded = new Set([...(options.excludeDirectories || DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES)].map(String));
-  const excludedPaths = new Set(options.excludeRelativePaths || DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_RELATIVE_PATHS);
+  const sourceEligibility = portableSourceEligibilityPolicy({
+    excludeDirectories: options.excludeDirectories == null ? DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_DIRECTORIES : options.excludeDirectories,
+    excludeRelativePaths: options.excludeRelativePaths == null ? DEFAULT_HANDOFF_MANUFACTURE_EXCLUDED_RELATIVE_PATHS : options.excludeRelativePaths
+  });
   const queue = [root];
   const absoluteFiles = [];
   const skippedSymlinks = [];
@@ -21,10 +29,15 @@ export async function enumerateNodeWorkspace(rootInput = '.', options = {}) {
     const entries = await readdir(current, { withFileTypes: true });
     entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
-      if (entry.isDirectory() && excluded.has(entry.name)) continue;
       const absolute = path.join(current, entry.name);
-      if (excludedPaths.has(normalizeRelativePath(path.relative(root, absolute)))) continue;
-      if (entry.isSymbolicLink()) { skippedSymlinks.push(normalizeRelativePath(path.relative(root, absolute))); continue; }
+      const relative = normalizeRelativePath(path.relative(root, absolute));
+      const eligibility = qualifyPortableSourcePath(relative, {
+        excludeDirectories: sourceEligibility.excludedDirectories,
+        excludeRelativePaths: sourceEligibility.excludedRelativePaths,
+        entryKind: entry.isDirectory() ? 'directory' : 'file'
+      });
+      if (!eligibility.eligible) continue;
+      if (entry.isSymbolicLink()) { skippedSymlinks.push(relative); continue; }
       if (entry.isDirectory()) queue.push(absolute);
       else if (entry.isFile()) absoluteFiles.push(absolute);
       if (absoluteFiles.length > maxFiles) {
@@ -62,7 +75,13 @@ export async function enumerateNodeWorkspace(rootInput = '.', options = {}) {
     workspaceId,
     entryCount: includedEntries.length,
     totalBytes,
-    exclusions: Object.freeze({ directories: Object.freeze([...excluded].sort()), relativePaths: Object.freeze([...excludedPaths].sort()), symbolicLinks: 'excluded-and-reported' }),
+    exclusions: Object.freeze({
+      directories: sourceEligibility.excludedDirectories,
+      relativePaths: sourceEligibility.excludedRelativePaths,
+      fileSuffixes: sourceEligibility.excludedFileSuffixes,
+      symbolicLinks: 'excluded-and-reported',
+      sourceEligibilitySchema: sourceEligibility.schema
+    }),
     skippedSymlinks: Object.freeze(skippedSymlinks.sort()),
     entriesFingerprint: sha256Text(stableJson(includedEntries))
   });

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

@@ -7,6 +7,8 @@ import { normalizeHandoffCarrierLineage } from '../../handoff/carrierLineage.js'
 import { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
 import { enumerateNodeWorkspace, PORTABLE_NODE_WORKSPACE_ENUMERATION_SCHEMA_ID } from './handoff.manufacture.enumeration.js';
 import { preparePackageParentWorkspaceReuse } from './handoff.manufacture.packageParent.js';
+import { qualifyPortableSourceReconciliationProofForManufacture } from '../../comparison/sourceFrontierReconciliationProof.js';
+import { qualifyPortableManufactureSchemaReferenceCandidate } from '../../handoff/schemaReferencePreflight.js';
 import {
   assertInside,
   expandPointerDependencyClosure,
@@ -48,6 +50,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     workspaceTitle: requestedWorkspaceTitle,
     sourceMetadata: input.workspaceSource || input.sourceMetadata || {},
     excludeDirectories: input.excludeDirectories || options.excludeDirectories,
+    excludeRelativePaths: input.excludeRelativePaths || options.excludeRelativePaths,
     maxFiles: input.maxFiles || options.maxFiles
   });
   const additionalWorkspaceDescriptors = normalizeAdditionalWorkspaceDescriptors(input.additionalWorkspaces || input.workspaceRoots || input.workspaceDescriptors || []);
@@ -79,6 +82,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
       workspaceTitle: requestedTitle,
       sourceMetadata: descriptor.source || descriptor.sourceMetadata || {},
       excludeDirectories: descriptor.excludeDirectories || input.excludeDirectories || options.excludeDirectories,
+      excludeRelativePaths: descriptor.excludeRelativePaths || input.excludeRelativePaths || options.excludeRelativePaths,
       maxFiles: descriptor.maxFiles || input.maxFiles || options.maxFiles
     });
     if (enumerated.status !== 'qualified-complete') throw new Error(`portable.handoff-manufacture.workspace-enumeration.${id}.${enumerated.status}`);
@@ -97,6 +101,8 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     markdown: handoffMarkdown
   });
 
+  const schemaReferencePreflight = qualifyPortableManufactureSchemaReferenceCandidate(handoff);
+
   if (enumeration.status !== 'qualified-complete') throw new Error(`portable.handoff-manufacture.workspace-enumeration.${enumeration.status}`);
   const workspaceTitle = requestedWorkspaceTitle || inferWorkspaceTitle(enumeration) || workspaceId;
   const primaryMaterialization = Object.freeze({ ...enumeration.materialization, title: workspaceTitle });
@@ -138,6 +144,13 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     if (targets.length !== 1) throw new Error(`portable.handoff-manufacture.workspace-scope.target-${targets.length ? 'ambiguous' : 'required'}:${materialization.id}`);
     workspaceMaterializations[index] = projectBoundedWorkspaceMaterialization(materialization, scope, targets[0].path);
   }
+  const hasReconciliationProof = Boolean(input.reconciliationProof && typeof input.reconciliationProof === 'object' && Object.keys(input.reconciliationProof).length);
+  const reconciliationProofQualification = qualifyPortableSourceReconciliationProofForManufacture({
+    proof: input.reconciliationProof || null,
+    requireProof: input.requireReconciliationProof === true,
+    workspaceMaterializations,
+    requiredWorkspaceIds: hasReconciliationProof || input.requireReconciliationProof === true ? [workspaceId] : []
+  });
 
   const routeSpecs = transportRoutes.length ? transportRoutes : Object.freeze([{ workspaceId, path: handoffPath }]);
   let requirements = await projectManufacturingRequirements({ handoff, workspaceId, handoffPath, routeSpecs, workspaceRuntimeById });
@@ -180,11 +193,15 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null),
     carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null),
     toolingBootstrap: toolingBootstrap.summary,
+    reconciliationProofQualification,
+    schemaReferencePreflight,
     manufacturingEvidence: Object.freeze({
       enumeration: enumeration.evidence,
       workspaceEnumerations: Object.freeze(workspaceEnumerations),
       toolingBootstrap: toolingBootstrap.summary,
       runtimeSourceAlignment,
+      reconciliationProof: reconciliationProofQualification,
+      schemaReferencePreflight,
       packageParentWorkspaceReuse: Object.freeze({
         state: String(packageParentReuse.state || ''),
         providerState: String(packageParentReuse.providerState || ''),

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

@@ -59,7 +59,7 @@ async function frontierFromLocalWorkspace(descriptor, options) {
       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.'
+      boundary: 'Local source is enumerated by the same deterministic Node Workspace enumerator used by Handoff manufacture; durable-source eligibility, generated-cache exclusions, configured path exclusions, 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 || '') })] });
@@ -180,6 +180,7 @@ function enumerationOptions(descriptor, options, workspaceId) {
     workspaceTitle: String(descriptor.workspaceTitle || descriptor.title || workspaceId),
     sourceMetadata: descriptor.sourceMetadata || {},
     excludeDirectories: descriptor.excludeDirectories || options.excludeDirectories,
+    excludeRelativePaths: descriptor.excludeRelativePaths || options.excludeRelativePaths,
     maxFiles: descriptor.maxFiles || options.maxFiles
   };
 }

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

@@ -0,0 +1,23 @@
+import { prepareNodeSourceFrontier } from './sourceFrontierComparison.js';
+import { provePortableSourceReconciliation } from '../../comparison/sourceFrontierReconciliationProof.js';
+
+export async function prepareNodeSourceReconciliationProofInput(input = {}, options = {}) {
+  const [base, incoming, current, reconciled] = await Promise.all([
+    prepareNodeSourceFrontier(input.base, { ...options, side: 'base' }),
+    prepareNodeSourceFrontier(input.incoming, { ...options, side: 'incoming' }),
+    prepareNodeSourceFrontier(input.current, { ...options, side: 'current' }),
+    prepareNodeSourceFrontier(input.reconciled, { ...options, side: 'reconciled' })
+  ]);
+  return Object.freeze({
+    base,
+    incoming,
+    current,
+    reconciled,
+    dispositions: input.dispositions || []
+  });
+}
+
+export async function proveNodeSourceReconciliation(input = {}, options = {}) {
+  const normalized = await prepareNodeSourceReconciliationProofInput(input, options);
+  return provePortableSourceReconciliation(normalized);
+}

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

@@ -3,7 +3,7 @@ import { enumerateNodeWorkspace } from './handoff.manufacture.enumeration.js';
 import { buildToolingBootstrapTransportFiles } from './handoff.manufacture.bootstrap.js';
 import { qualifyToolingRuntimeSourceAlignment } from './handoff.manufacture.runtimeSource.js';
 import { inferWorkspaceTitle, normalizeAdditionalWorkspaceDescriptors, safeWorkspaceToken } from './handoff.manufacture.multiRoot.js';
-import { normalizeWorkspaceTargetBindings } from './handoff.manufacture.scope.js';
+import { normalizeWorkspaceScopes, normalizeWorkspaceTargetBindings, projectBoundedWorkspaceMaterialization } from './handoff.manufacture.scope.js';
 import { normalizeHandoffCarrierLineage } from '../../handoff/carrierLineage.js';
 import { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
 
@@ -29,6 +29,7 @@ export async function prepareNodeWorkspaceCarrierManufacturingInput(input = {},
       workspaceTitle: descriptor.title,
       sourceMetadata: descriptor.source || descriptor.sourceMetadata || {},
       excludeDirectories: descriptor.excludeDirectories || input.excludeDirectories || options.excludeDirectories,
+      excludeRelativePaths: descriptor.excludeRelativePaths || input.excludeRelativePaths || options.excludeRelativePaths,
       maxFiles: descriptor.maxFiles || input.maxFiles || options.maxFiles
     });
     if (enumeration.status !== 'qualified-complete') throw new Error(`portable.workspace-carrier.workspace-enumeration.${descriptor.id}.${enumeration.status}`);
@@ -42,6 +43,15 @@ export async function prepareNodeWorkspaceCarrierManufacturingInput(input = {},
     explicitBindings: input.workspaceTargets || input.workspaceTargetBindings || [],
     additionalWorkspaceDescriptors
   });
+  const workspaceScopes = normalizeWorkspaceScopes(input.workspaceScopes || input.workspaceScopeBindings || []);
+  const materializations = enumerations.map((item) => {
+    const materialization = item.materialization;
+    const scope = workspaceScopes.get(String(materialization.id || '')) || null;
+    if (!scope || scope.coverage !== 'bounded') return materialization;
+    const targets = workspaceTargets.filter((target) => String(target.workspaceId || '') === String(materialization.id || ''));
+    if (targets.length !== 1) throw new Error(`portable.workspace-carrier.workspace-scope.target-${targets.length ? 'ambiguous' : 'required'}:${materialization.id}`);
+    return projectBoundedWorkspaceMaterialization(materialization, scope, targets[0].path);
+  });
   const toolingBootstrap = await buildToolingBootstrapTransportFiles({
     delivery: input.toolingBootstrap || input.bootstrapDelivery || 'embedded',
     runtimeRoot: input.runtimeRoot || options.runtimeRoot,
@@ -50,13 +60,14 @@ export async function prepareNodeWorkspaceCarrierManufacturingInput(input = {},
   });
   const runtimeSourceAlignment = await qualifyToolingRuntimeSourceAlignment({
     runtimeIdentity: toolingBootstrap.runtimeIdentity,
-    localWorkspaces: enumerations.map((item) => Object.freeze({ id: item.materialization.id, root: item.root, materialization: item.materialization })),
+    localWorkspaces: enumerations.map((item, index) => Object.freeze({ id: materializations[index].id, root: item.root, materialization: item.materialization })),
     maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
   });
   return Object.freeze({
     carrierMode: 'workspace',
     createdAt: String(input.createdAt || ''),
-    workspaceMaterializations: Object.freeze(enumerations.map((item) => item.materialization)),
+    workspaceMaterializations: Object.freeze(materializations),
+    materialRepresentationWorkspaceIds: Object.freeze([...(input.materialRepresentationWorkspaceIds || input.genericMaterialWorkspaceIds || [])].map(String)),
     workspaceTargets,
     additionalTransportFiles: toolingBootstrap.files,
     carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null),

package/src/tooling/portable/audit/audit.capability.js

@@ -16,7 +16,8 @@ export function auditPortableRecord(record = {}, options = {}) {
       record,
       markdown: record.markdown,
       validationContractOverride: runtimeProjection?.state === 'qualified' ? runtimeProjection.compiledContract : null,
-      schemaValidationAuthority: requireExactSchemaAuthority ? runtimeAuthority : null
+      schemaValidationAuthority: requireExactSchemaAuthority ? runtimeAuthority : null,
+      schemaReferenceContext: options.schemaReferenceContext || 'historical'
     });
   } catch (error) {
     const finding = portableFinding('error', 'portable.audit.exception', error?.message || 'Audit failed.', {

package/src/tooling/portable/bootstrap/tiinex.llm.bootstrap.md

@@ -18,9 +18,9 @@ The same workflow must survive different host arrangements:
 
 When this bootstrap or the portable repository is available as a project source, normalize only the explicitly uploaded Markdown, archive, and project-source material, then start with `discover-tooling` or `prepare-task`.
 
-### Qualified routed Handoff package
+### Qualified Tiinex package
 
-When a received carrier exposes the qualified recipient-facing Tiinex Handoff package surface, start at `001-1-READ-BEFORE-PROCEEDING.trace.md`. Before Tiinex Tooling is available, the host may perform only the bounded bootstrap exception: read the declared bootstrap node, extract `001-2-bootstrap.zip` into a writable runtime location, and make its Tooling entrypoint callable. Prefer a location that survives turns in the current runtime, but never treat that location as project or artifact authority. Do not manually unpack Workspace/cache payloads or perform broad ZIP/filesystem/repository archaeology. The Tooling entrypoint is exactly `runtime/tools/tiinex-portable.mjs` relative to the chosen extraction root; do not search/list the extracted runtime to discover it. Give the untouched original Handoff-package carrier to that entrypoint and use `orient-handoff-package` as the first semantic operation. Keep the outer Continue-from path opaque to native access. After orientation, use `ground <same-package.zip> --route <same-Continue-from>` as the one shared human/LLM decision-grounding path. Its bounded default receipt composes the selected Handoff authority, exact qualified Required Context identities, the selected-route declared-Parent leaf, a compact declared-Parent continuity-to-qualified-root proof, declared current-work frontier, blockers, and explicit unresolved evidence. Continue substantive bounded work only when `readiness.state` is `grounded-to-act`; `grounded-to-discuss` and `insufficient-grounding` must not be upgraded by generic inference. An apparent loaded root that still declares an unavailable Parent is not cold-start closure: follow `readiness.nextAction.recovery` exactly. If a bound exact repository-read host capability is available, use the projected `plan-host-action` request, normalize the host result through `accept-host-receipt`, then resume the same `ground` command with `--recovery <accepted-host-receipt.json>`; otherwise request exactly the named material from the Transport Operator. When an accepted pinned repository Parent declares a deterministic relative Parent, Tooling may derive only that exact sibling path from the accepted repository/commit/base-path context. For repeated recovery, call `accept-host-receipt --prior <previous-accepted.json>` so the newest accepted result explicitly carries all prior accepted recovery material; pass only that newest cumulative result back to the same `ground --recovery` seam. Never broaden search or treat fetched material as verified before lineage identity/integrity qualification. Re-run the same `ground` command with `--include-required-context <requirement-id,name|all>` only when exact qualified Required Context body text is needed. No external qualification schema, Tooling source inspection, `--help`/operation discovery, context-audit detour, or separate `ground-cold-consumer` call is required before this decision grounding. Native host tools remain valid execution mechanics after Tiinex takeover on already-resolved ordinary source, and explicit degraded fallback only when qualification explains why it was required.
+When a received carrier exposes the qualified recipient-facing Tiinex package surface, start at its declared Start artifact (normally `001-1-READ-BEFORE-PROCEEDING.trace.md`). Before Tiinex Tooling is available, the host may perform only the bounded bootstrap exception: read the declared bootstrap node, extract `001-2-bootstrap.zip` into a writable runtime location, and make its Tooling entrypoint callable. Prefer a location that survives turns in the current runtime, but never treat that location as project or artifact authority. Do not manually unpack Workspace/cache payloads or perform broad ZIP/filesystem/repository archaeology. The Tooling entrypoint is exactly `runtime/tools/tiinex-portable.mjs` relative to the chosen extraction root; do not search/list the extracted runtime to discover it. Give the untouched original package carrier to that entrypoint and use `orient-handoff-package` as the first semantic operation. Package role is qualified from the carried package contract rather than inferred from filenames, Workspace/Role presence, or transport labels. A bootstrap-only or pointerless Workspace carrier has no Handoff route and must not be upgraded into recipient, holder, participation, delegation, current-work, or grounded-to-act authority; use the qualified route-less orientation/material projection only. For a routed Handoff carrier, keep the outer Continue-from path opaque to native access and, after orientation, use `ground <same-package.zip> --route <same-Continue-from>` as the one shared human/LLM decision-grounding path. Its bounded default receipt composes the selected Handoff authority, exact qualified Required Context identities, the selected-route declared-Parent leaf, a compact declared-Parent continuity-to-qualified-root proof, declared current-work frontier, blockers, and explicit unresolved evidence. Continue substantive bounded work only when `readiness.state` is `grounded-to-act`; `grounded-to-discuss` and `insufficient-grounding` must not be upgraded by generic inference. An apparent loaded root that still declares an unavailable Parent is not cold-start closure: follow `readiness.nextAction.recovery` exactly. If a bound exact repository-read host capability is available, use the projected `plan-host-action` request, normalize the host result through `accept-host-receipt`, then resume the same `ground` command with `--recovery <accepted-host-receipt.json>`; otherwise request exactly the named material from the Transport Operator. When an accepted pinned repository Parent declares a deterministic relative Parent, Tooling may derive only that exact sibling path from the accepted repository/commit/base-path context. For repeated recovery, call `accept-host-receipt --prior <previous-accepted.json>` so the newest accepted result explicitly carries all prior accepted recovery material; pass only that newest cumulative result back to the same `ground --recovery` seam. Never broaden search or treat fetched material as verified before lineage identity/integrity qualification. Re-run the same `ground` command with `--include-required-context <requirement-id,name|all>` only when exact qualified Required Context body text is needed. No external qualification schema, Tooling source inspection, `--help`/operation discovery, context-audit detour, or separate `ground-cold-consumer` call is required before this decision grounding. Native host tools remain valid execution mechanics after Tiinex takeover on already-resolved ordinary source, and explicit degraded fallback only when qualification explains why it was required.
 
 ### Bootstrap travels inside an archive
 

package/src/tooling/portable/comparison/sourceFrontierComparison.js

@@ -1,5 +1,6 @@
 import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
 import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { portableSourceEligibilityPolicy, qualifyPortableSourcePath } from '../source/sourceEligibility.js';
 
 export const PORTABLE_SOURCE_FRONTIER_SCHEMA_ID = 'tiinex.portable.source-frontier.v1';
 export const PORTABLE_SOURCE_FRONTIER_COMPARISON_SCHEMA_ID = 'tiinex.portable.source-frontier-comparison.v1';
@@ -45,16 +46,34 @@ export function createPortableSourceFrontier(input = {}) {
     workspaces: Object.freeze(workspaces),
     findings: normalizedFindings,
     findingSummary: summarizePortableFindings(normalizedFindings),
-    boundary: String(input.boundary || 'Exact source-byte frontier only. Workspace/path equality does not establish semantic equivalence, authority, acceptance, or merge disposition.')
+    boundary: String(input.boundary || 'Eligible durable source-byte frontier only. Source-ineligible transport/runtime/cache bytes are outside frontier identity; Workspace/path equality does not establish semantic equivalence, authority, acceptance, deletion, or merge disposition.')
   });
 }
 
 export function createPortableWorkspaceSnapshot(entries = [], evidence = {}) {
   const findings = [];
-  const normalized = normalizeEntries(entries, findings);
+  const selection = normalizeEntries(entries, findings);
   if (findings.length) return deepFreeze({ state: 'qualification-error', entries: Object.freeze([]), findings: Object.freeze(findings) });
+  const normalized = selection.entries;
   const totalBytes = normalized.reduce((sum, entry) => sum + entry.bytes, 0);
   const fingerprint = snapshotFingerprint(normalized);
+  const inheritedEvidence = serializableObject(evidence);
+  const priorEligibility = inheritedEvidence?.sourceEligibility && typeof inheritedEvidence.sourceEligibility === 'object'
+    ? inheritedEvidence.sourceEligibility
+    : null;
+  const upstreamSelection = priorEligibility?.upstreamSelection || (priorEligibility && Number(priorEligibility.excludedEntryCount || 0) > 0 ? portableSourceSelectionReceipt(priorEligibility) : null);
+  const sourceEligibility = Object.freeze({
+    schema: selection.policy.schema,
+    inputEntryCount: selection.inputEntryCount,
+    eligibleEntryCount: normalized.length,
+    excludedEntryCount: selection.excludedEntryCount,
+    excludedByReason: Object.freeze({ ...selection.excludedByReason }),
+    excludedDirectories: selection.policy.excludedDirectories,
+    excludedRelativePaths: selection.policy.excludedRelativePaths,
+    excludedFileSuffixes: selection.policy.excludedFileSuffixes,
+    ...(upstreamSelection ? { upstreamSelection: Object.freeze(upstreamSelection) } : {}),
+    boundary: selection.policy.boundary
+  });
   return deepFreeze({
     state: QUALIFIED,
     entryCount: normalized.length,
@@ -62,7 +81,7 @@ export function createPortableWorkspaceSnapshot(entries = [], evidence = {}) {
     fingerprint,
     fingerprintMethod: 'sha256-path-bytes-sha256-v1',
     entries: Object.freeze(normalized),
-    evidence: Object.freeze(serializableObject(evidence)),
+    evidence: Object.freeze({ ...inheritedEvidence, sourceEligibility }),
     findings: Object.freeze([])
   });
 }
@@ -181,13 +200,28 @@ function normalizeWorkspace(raw, workspaceId, findings) {
 function normalizeEntries(entries, findings) {
   const out = [];
   const seen = new Set();
+  const policy = portableSourceEligibilityPolicy();
+  const excludedByReason = {};
+  let inputEntryCount = 0;
+  let excludedEntryCount = 0;
   for (const raw of entries || []) {
+    inputEntryCount += 1;
     const rawPath = String(raw?.path || raw?.innerPath || '').trim();
     const path = normalizePath(rawPath);
     if (unsafeRawPath(rawPath) || !path || unsafePath(path)) {
       findings.push(portableFinding('error', 'portable.source-frontier.entry.path-invalid', 'Comparable source entry has an unsafe or empty Workspace-relative path.', { path: rawPath }));
       continue;
     }
+    const eligibility = qualifyPortableSourcePath(path, {
+      excludeDirectories: policy.excludedDirectories,
+      excludeRelativePaths: policy.excludedRelativePaths,
+      entryKind: 'file'
+    });
+    if (!eligibility.eligible) {
+      excludedEntryCount += 1;
+      excludedByReason[eligibility.reason] = Number(excludedByReason[eligibility.reason] || 0) + 1;
+      continue;
+    }
     if (seen.has(path)) {
       findings.push(portableFinding('error', 'portable.source-frontier.entry.path-duplicate', 'Comparable source snapshot contains a duplicate normalized path.', { path }));
       continue;
@@ -202,7 +236,23 @@ function normalizeEntries(entries, findings) {
     out.push(Object.freeze({ path, bytes, sha256 }));
   }
   out.sort((a, b) => a.path.localeCompare(b.path));
-  return out;
+  return Object.freeze({
+    entries: Object.freeze(out),
+    policy,
+    inputEntryCount,
+    excludedEntryCount,
+    excludedByReason: Object.freeze(Object.fromEntries(Object.entries(excludedByReason).sort(([a], [b]) => a.localeCompare(b))))
+  });
+}
+
+function portableSourceSelectionReceipt(value = {}) {
+  return {
+    schema: String(value.schema || ''),
+    inputEntryCount: Number(value.inputEntryCount || 0),
+    eligibleEntryCount: Number(value.eligibleEntryCount || 0),
+    excludedEntryCount: Number(value.excludedEntryCount || 0),
+    excludedByReason: Object.freeze({ ...serializableObject(value.excludedByReason || {}) })
+  };
 }
 
 function compareWorkspaceUnion(left, right) {