@tiinex/core 0.11.0 → 0.13.0

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

@@ -2,10 +2,13 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { inferWorkspaceTitle, normalizeAdditionalWorkspaceDescriptors, normalizeTransportRoute, safeWorkspaceToken } from './handoff.manufacture.multiRoot.js';
 import { buildToolingBootstrapTransportFiles, PORTABLE_TOOLING_BOOTSTRAP_MANIFEST_SCHEMA_ID } from './handoff.manufacture.bootstrap.js';
+import { qualifyToolingRuntimeSourceAlignment } from './handoff.manufacture.runtimeSource.js';
 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,
@@ -47,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 || []);
@@ -78,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}`);
@@ -96,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 });
@@ -137,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 });
@@ -153,6 +167,14 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
   const toolingBootstrapResult = await toolingBootstrapPromise;
   if (toolingBootstrapResult.error) throw toolingBootstrapResult.error;
   const toolingBootstrap = toolingBootstrapResult.value;
+  const runtimeSourceAlignment = await qualifyToolingRuntimeSourceAlignment({
+    runtimeIdentity: toolingBootstrap.runtimeIdentity,
+    localWorkspaces: [
+      Object.freeze({ id: workspaceId, root: workspaceRoot, materialization: primaryMaterialization }),
+      ...additionalEnumerations.map(({ id, root, enumerated }) => Object.freeze({ id, root, materialization: enumerated.materialization }))
+    ],
+    maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
+  });
   const orientationBootstrap = input.transportBootstrapContent
     ? Object.freeze({ present: true, path: String(input.transportBootstrapPath || 'tiinex.package/bootstrap.md'), content: String(input.transportBootstrapContent), mediaType: 'text/markdown' })
     : Object.freeze({ present: false });
@@ -171,10 +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/handoff.manufacture.runtimeSource.js

@@ -0,0 +1,82 @@
+import { buildToolingBootstrapRuntimeIdentity } from './handoff.manufacture.bootstrap.js';
+
+export const PORTABLE_TOOLING_RUNTIME_SOURCE_ALIGNMENT_SCHEMA_ID = 'tiinex.portable.tooling-runtime-source-alignment.v1';
+const CORE_PACKAGE_NAME = '@tiinex/core';
+
+export async function qualifyToolingRuntimeSourceAlignment(input = {}) {
+  const runtimeIdentity = normalizeIdentity(input.runtimeIdentity);
+  if (!runtimeIdentity.sourceRepresentationSha256) throw new Error('portable.tooling-bootstrap.runtime-source.runtime-identity-required');
+  const candidates = [];
+  for (const item of input.localWorkspaces || input.workspaces || []) {
+    const root = String(item?.root || '').trim();
+    if (!root) continue;
+    const materialization = item?.materialization || item?.enumeration?.materialization || null;
+    const packageIdentity = packageIdentityFromMaterialization(materialization);
+    if (packageIdentity.name !== CORE_PACKAGE_NAME) continue;
+    candidates.push(Object.freeze({
+      workspaceId: String(item?.id || materialization?.id || '').trim(),
+      root,
+      packageIdentity
+    }));
+  }
+  if (!candidates.length) return Object.freeze({
+    schema: PORTABLE_TOOLING_RUNTIME_SOURCE_ALIGNMENT_SCHEMA_ID,
+    state: 'not-observed',
+    coreWorkspaceCount: 0,
+    runtime: runtimeIdentity,
+    source: null,
+    boundary: 'No local Workspace with package identity @tiinex/core was selected, so exact runtime/source equality cannot be asserted from carried source.'
+  });
+  if (candidates.length !== 1) throw new Error(`portable.tooling-bootstrap.runtime-source.core-workspace-ambiguous:${candidates.map((item) => item.workspaceId || 'unlabeled').join(',')}`);
+
+  const candidate = candidates[0];
+  const sourceIdentity = normalizeIdentity(await buildToolingBootstrapRuntimeIdentity({
+    runtimeRoot: candidate.root,
+    maxFiles: input.maxFiles
+  }));
+  const evidence = Object.freeze({
+    schema: PORTABLE_TOOLING_RUNTIME_SOURCE_ALIGNMENT_SCHEMA_ID,
+    state: sourceIdentity.sourceRepresentationSha256 === runtimeIdentity.sourceRepresentationSha256 ? 'qualified-exact-match' : 'mismatch',
+    coreWorkspaceCount: 1,
+    workspaceId: candidate.workspaceId,
+    runtime: runtimeIdentity,
+    source: sourceIdentity,
+    boundary: 'Exact Tooling runtime source/data equality is required when a local @tiinex/core Workspace is carried. Release-normalized package.json metadata may differ, but matching package names or versions alone are insufficient.'
+  });
+  if (evidence.state !== 'qualified-exact-match') {
+    throw new Error([
+      'portable.tooling-bootstrap.runtime-source.mismatch',
+      `workspace=${candidate.workspaceId || 'unlabeled'}`,
+      `runtimeVersion=${runtimeIdentity.packageVersion || 'unknown'}`,
+      `sourceVersion=${sourceIdentity.packageVersion || candidate.packageIdentity.version || 'unknown'}`,
+      `runtimeSource=${runtimeIdentity.sourceRepresentationSha256}`,
+      `sourceSource=${sourceIdentity.sourceRepresentationSha256}`
+    ].join(':'));
+  }
+  return evidence;
+}
+
+function packageIdentityFromMaterialization(materialization) {
+  const entry = (materialization?.entries || []).find((item) => String(item?.path || '') === 'package.json');
+  if (!entry?.data) return Object.freeze({ name: '', version: '' });
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(entry.data));
+    return Object.freeze({ name: String(parsed?.name || '').trim(), version: String(parsed?.version || '').trim() });
+  } catch {
+    return Object.freeze({ name: '', version: '' });
+  }
+}
+
+function normalizeIdentity(value = {}) {
+  return Object.freeze({
+    schema: String(value?.schema || 'tiinex.portable.tooling-runtime-identity.v1'),
+    packageName: String(value?.packageName || ''),
+    packageVersion: String(value?.packageVersion || ''),
+    representationSha256: String(value?.representationSha256 || ''),
+    sourceRepresentationSha256: String(value?.sourceRepresentationSha256 || ''),
+    runtimeFiles: Number(value?.runtimeFiles || 0),
+    runtimeBytes: Number(value?.runtimeBytes || 0),
+    entrypointSha256: String(value?.entrypointSha256 || ''),
+    enumerationPolicySha256: String(value?.enumerationPolicySha256 || '')
+  });
+}

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 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 { normalizeHandoffCarrierLineage } from '../../handoff/carrierLineage.js';
@@ -28,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}`);
@@ -47,6 +49,11 @@ export async function prepareNodeWorkspaceCarrierManufacturingInput(input = {},
     expected: input.expectedToolingBootstrap || null,
     maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
   });
+  const runtimeSourceAlignment = await qualifyToolingRuntimeSourceAlignment({
+    runtimeIdentity: toolingBootstrap.runtimeIdentity,
+    localWorkspaces: enumerations.map((item) => Object.freeze({ id: item.materialization.id, root: item.root, materialization: item.materialization })),
+    maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
+  });
   return Object.freeze({
     carrierMode: 'workspace',
     createdAt: String(input.createdAt || ''),
@@ -56,7 +63,7 @@ export async function prepareNodeWorkspaceCarrierManufacturingInput(input = {},
     carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null),
     carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null),
     toolingBootstrap: toolingBootstrap.summary,
-    manufacturingEvidence: Object.freeze({ workspaceEnumerations: Object.freeze(enumerations.map((item) => Object.freeze({ id: item.materialization.id, root: item.root, evidence: item.evidence }))), toolingBootstrap: toolingBootstrap.summary }),
+    manufacturingEvidence: Object.freeze({ workspaceEnumerations: Object.freeze(enumerations.map((item) => Object.freeze({ id: item.materialization.id, root: item.root, evidence: item.evidence }))), toolingBootstrap: toolingBootstrap.summary, runtimeSourceAlignment }),
     verifyRoundtrip: input.verifyRoundtrip !== false
   });
 }

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/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) {