@tiinex/core 0.17.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -78,6 +78,8 @@
     "./tooling/portable/engine.facade.js": "./src/tooling/portable/engine.facade.js",
     "./tooling/portable/grounding/grounding.capsule.js": "./src/tooling/portable/grounding/grounding.capsule.js",
     "./tooling/portable/grounding/grounding.participantAuthority.js": "./src/tooling/portable/grounding/grounding.participantAuthority.js",
+    "./tooling/portable/grounding/grounding.processApplicability.js": "./src/tooling/portable/grounding/grounding.processApplicability.js",
+    "./tooling/portable/grounding/grounding.implementationSourceAuthority.js": "./src/tooling/portable/grounding/grounding.implementationSourceAuthority.js",
     "./tooling/portable/grounding/grounding.readiness.js": "./src/tooling/portable/grounding/grounding.readiness.js",
     "./tooling/portable/grounding/grounding.workProvenance.js": "./src/tooling/portable/grounding/grounding.workProvenance.js",
     "./tooling/portable/handoff/carrierLineage.js": "./src/tooling/portable/handoff/carrierLineage.js",
@@ -169,12 +171,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "2986187f3e95582d13c784060272e111931c6a1b",
+  "gitHead": "fe01706aecacbf28c66e2ac052e4f639170dfe73",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "2986187f3e95582d13c784060272e111931c6a1b",
-    "sourceTree": "0c65ff04241c756ae67978d777d1bee8ac1befc9",
+    "sourceCommit": "fe01706aecacbf28c66e2ac052e4f639170dfe73",
+    "sourceTree": "b4e5dbb825a1504fef53f1e5281d4bd6fd3c87ff",
     "repository": "Tiinex/core",
-    "previousVersion": "0.16.0"
+    "previousVersion": "0.18.0"
   }
 }

package/src/tooling/portable/adapters/cli/cli.command-input.js

@@ -117,7 +117,7 @@ export async function commandInput(parsed, runtime = {}) {
         packageSourcePath: packagePath,
         includeLegacyTopics: Boolean(flags['include-legacy-topics']),
         includeRequiredContext: flags['include-required-context'] || '',
-        holderBinding: { roleLabel: flags['holder-role'] || '', holderId: flags['holder-id'] || '' },
+        holderBinding: { roleLabel: flags['holder-role'] || '', holderId: flags['holder-id'] || '', sourceLocator: holderBindingCliSource(flags) },
         host,
         recoveryAcceptance
       },
@@ -471,4 +471,11 @@ function mergeLoadedMaterial(primary = {}, secondary = {}) {
 }
 
 function normalizeRuntimePaths(value) { const paths = Array.isArray(value) ? value : value ? [value] : []; return paths.map((entry) => String(entry || '').trim()).filter(Boolean); }
+function holderBindingCliSource(flags = {}) {
+  const fields = [];
+  if (Object.prototype.hasOwnProperty.call(flags, 'holder-role')) fields.push('--holder-role');
+  if (Object.prototype.hasOwnProperty.call(flags, 'holder-id')) fields.push('--holder-id');
+  return fields.length ? `cli:${fields.join(',')}` : '';
+}
+
 function splitFlag(value) { return !value || value === true ? [] : String(value).split(',').map((item) => item.trim()).filter(Boolean); }

package/src/tooling/portable/adapters/cli/cli.common-author.js

@@ -31,8 +31,8 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
 
   const parentReference = resolveParentReference(flags, state);
   const parentSource = String(flags['parent-source'] || flags['parent-file'] || '').trim();
-  if (isWorkspaceQualifiedReference(parentReference) && !parentSource) throw new Error('portable.cli.author.parent-source.required');
-  if (parentSource && !parentReference) throw new Error('portable.cli.author.parent.required');
+  if (isWorkspaceQualifiedReference(parentReference) && !parentSource) throw new Error(`portable.cli.author.parent-source.required: --parent ${parentReference} names an explicit cross-Workspace Parent. Supply --parent-source <local-file> containing the exact qualified Parent bytes; Tooling will not discover or fetch that Parent automatically.`);
+  if (parentSource && !parentReference) throw new Error('portable.cli.author.parent.required: --parent-source supplies Parent bytes but no semantic Parent reference. Supply --parent <workspace::path|relative-path> explicitly; Tooling will not infer Parent identity from the source file.');
   if (isWorkspaceQualifiedReference(parentReference) && !requestedArtifactRelativePath && !targetDirectory) throw new Error('portable.cli.author.cross-workspace-parent.target-required');
   const parentPath = parentReference ? (parentSource ? path.resolve(parentSource) : safeWorkspaceTarget(workspaceRoot, parentReference)) : '';
   const artifactRelativePath = requestedArtifactRelativePath || await allocateArtifactRelativePath({ workspaceRoot, targetDirectory, parentRelativePath: parentReference, schemaId, title });
@@ -80,6 +80,7 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
     }, {});
     const blocking = Number(audit?.findingSummary?.counts?.error || 0) + Number(stage?.findingSummary?.counts?.error || 0);
     if (blocking) {
+      const actionableFindings = projectAuthorActionableFindings(audit, stage);
       await rm(artifactPath, { force: true });
       wrote = false;
       return Object.freeze({
@@ -90,7 +91,8 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
         audit,
         stage,
         findingSummary: mergeFindingSummaries(audit?.findingSummary, stage?.findingSummary),
-        nextAction: 'Resolve the reported schema/continuity finding, then rerun the same author command. No invalid durable artifact was retained.',
+        actionableFindings,
+        nextAction: actionableFindings[0]?.nextAction || 'Resolve the reported schema/continuity finding, then rerun the same author command. No invalid durable artifact was retained.',
         boundary: 'Common-path authoring composes the shared renderer, c14n-v2 sealing, runtime audit, and staging qualification. It may write only the requested local Workspace artifact and runtime-only .tiinex continuation state; it performs no remote mutation.'
       });
     }
@@ -125,12 +127,12 @@ async function parentRecordFromArtifact(parentPath, parentRelativePath, context
   const schemaId = String(current.schema?.id || '').trim();
   const schemaTarget = String(current.schema?.target || '').trim();
   const self = canonicalC14nV2SelfState(markdown);
-  if (!schemaId) throw new Error('portable.cli.author.parent.schema-authority.required');
+  if (!schemaId) throw new Error('portable.cli.author.parent.schema-authority.required: the supplied Parent does not declare a Current Schema. Supply exact qualified Parent bytes with an explicit Current Schema reference; Tooling will not infer Parent schema authority from path or filename.');
   if (self.state !== 'verified') throw new Error(`portable.cli.author.parent.integrity.${self.reason || self.state}`);
   const schemaReferenceAuthority = schemaTarget
     ? exactDeclaredSchemaReferenceAuthority(schemaId, schemaTarget)
     : await recoverQualifiedRuntimeSchemaReferenceAuthority(schemaId, context.runtime || {});
-  if (!schemaReferenceAuthority) throw new Error('portable.cli.author.parent.schema-authority.required');
+  if (!schemaReferenceAuthority) throw new Error(`portable.cli.author.parent.schema-authority.required: Parent schema ${schemaId} lacks an exact qualified schema-reference authority. Supply Parent bytes with an exact Current Schema target or qualified runtime canonical schema material; Tooling will not invent the schema target.`);
   return Object.freeze({
     id: parentRelativePath,
     path: parentRelativePath,
@@ -144,6 +146,28 @@ async function parentRecordFromArtifact(parentPath, parentRelativePath, context
   });
 }
 
+function projectAuthorActionableFindings(audit = {}, stage = {}) {
+  const findings = [
+    ...(audit.findings || audit.actionableFindings || []),
+    ...(stage.findings || stage.actionableFindings || [])
+  ].filter((item) => item && (item.severity === 'error' || item.severity === 'warning'));
+  const seen = new Set();
+  const out = [];
+  for (const item of findings) {
+    const code = String(item.code || '');
+    const key = `${code}\u0000${String(item.message || '')}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(Object.freeze({
+      code,
+      message: String(item.message || ''),
+      ...(item.contractGuidance ? { contractGuidance: Object.freeze({ ...item.contractGuidance }) } : {}),
+      nextAction: String(item.contractGuidance?.nextAction || 'Resolve this exact finding using its cited authority/evidence, then rerun the same author command. No invalid durable artifact was retained.')
+    }));
+  }
+  return Object.freeze(out.slice(0, 20));
+}
+
 export function parentRecoveryMode(reference = '') {
   const classification = classifyParentRecoveryReference(reference);
   if (classification.kind === 'workspace-qualified') return 'workspace-qualified';

package/src/tooling/portable/adapters/cli/cli.common-output.js

@@ -103,6 +103,7 @@ function projectGroundDefault(result = {}, parsed = {}) {
     status: result.status,
     readiness: compactReadiness(result.readiness),
     authority: compactGroundAuthority(result.authority),
+    orchestrationReadiness: compactOrchestrationReadiness(result.orchestrationReadiness),
     requiredContext: Object.freeze({
       declared: Number(required.declared || 0),
       matchedInWorkspaceSnapshots: Number(required.matchedInWorkspaceSnapshots || 0),
@@ -162,6 +163,7 @@ function projectHandoffDefault(result = {}, parsed = {}) {
       status: String(carrier.status || ''),
       mode: String(carrier.mode || ''),
       lineage: carrier.lineage ? compactCarrierLineage(carrier.lineage) : null,
+      allocation: result.carrierAllocation ? Object.freeze({ ...result.carrierAllocation }) : null,
       route: Object.freeze({
         id: String(route.id || ''),
         state: String(route.state || ''),
@@ -254,13 +256,18 @@ function compactGroundAuthority(authority = {}) {
     route: Object.freeze({
       id: String(route.id || ''),
       pointerPath: String(route.pointerPath || ''),
-      workspaceId: String(route.workspaceId || '')
+      workspaceId: String(route.workspaceId || ''),
+      workspaceRelativePath: String(route.workspaceRelativePath || ''),
+      sha256: String(route.sha256 || ''),
+      provenance: route.provenance ? Object.freeze({ ...route.provenance }) : null
     }),
     handoff: Object.freeze({
       purpose: String(handoff.purpose || ''),
       from: String(handoff.from || ''),
       to: String(handoff.to || ''),
-      completionExpectation: handoff.completionExpectation || null
+      completionExpectation: handoff.completionExpectation || null,
+      transfers: Object.freeze((handoff.transfers || []).map((item) => Object.freeze({ ...item }))),
+      provenance: handoff.provenance ? Object.freeze({ ...handoff.provenance }) : null
     }),
     role: Object.freeze({
       state: String(role.state || ''),
@@ -269,13 +276,20 @@ function compactGroundAuthority(authority = {}) {
     }),
     holderBinding: Object.freeze({
       state: String(holderBinding.state || ''),
+      bindingPresent: Boolean(holderBinding.bindingPresent),
+      declarationPresent: Boolean(holderBinding.declarationPresent),
       holderId: String(holderBinding.holderId || ''),
       roleLabel: String(holderBinding.roleLabel || ''),
       recipientRoleLabel: String(holderBinding.recipientRoleLabel || ''),
       recipientCompatibility: String(holderBinding.recipientCompatibility || ''),
       source: String(holderBinding.source || ''),
+      sourceDetail: holderBinding.sourceDetail ? Object.freeze({ ...holderBinding.sourceDetail }) : null,
+      authorization: holderBinding.authorization ? Object.freeze({ ...holderBinding.authorization, provenance: holderBinding.authorization.provenance ? Object.freeze({ ...holderBinding.authorization.provenance }) : null }) : null,
+      durableIdentity: holderBinding.durableIdentity ? Object.freeze({ ...holderBinding.durableIdentity }) : Object.freeze({ state: 'not-established' }),
+      semanticAuthorityState: String(holderBinding.semanticAuthorityState || 'not-established'),
       explicit: Boolean(holderBinding.explicit),
-      inferredFromTransport: Boolean(holderBinding.inferredFromTransport)
+      inferredFromTransport: Boolean(holderBinding.inferredFromTransport),
+      provenance: holderBinding.provenance ? Object.freeze({ ...holderBinding.provenance }) : null
     }),
     operationBoundary: Object.freeze({
       sourceMutation: Boolean(operationBoundary.sourceMutation),
@@ -286,14 +300,35 @@ function compactGroundAuthority(authority = {}) {
   });
 }
 
+function compactOrchestrationReadiness(value = {}) {
+  if (!value || typeof value !== 'object') return null;
+  const wider = value.widerOrchestration || {};
+  return Object.freeze({
+    state: String(value.state || ''),
+    boundedActionReadiness: String(value.boundedActionReadiness || ''),
+    widerOrchestration: Object.freeze({
+      state: String(wider.state || ''),
+      blockers: Object.freeze((wider.blockers || []).slice(0, 8).map((item) => Object.freeze({ ...item })))
+    }),
+    participantMap: String(value.participantMap || ''),
+    sourceScope: String(value.sourceScope || ''),
+    processApplicability: value.processApplicability ? Object.freeze({ ...value.processApplicability, unresolved: Object.freeze([...(value.processApplicability.unresolved || [])].map((item) => Object.freeze({ ...item }))) }) : null,
+    boundary: String(value.boundary || '')
+  });
+}
+
 function projectRequiredContextItem(item = {}) {
   const contentProjected = Boolean(item.contentProjected && typeof item.content === 'string');
   return Object.freeze({
     requirementId: String(item.requirementId || ''),
     name: String(item.name || ''),
+    material: String(item.material || ''),
+    purpose: String(item.purpose || ''),
+    declaredAvailability: String(item.declaredAvailability || ''),
     state: String(item.state || ''),
     workspaceId: String(item.workspaceId || ''),
     innerPath: String(item.innerPath || ''),
+    provenance: item.provenance ? Object.freeze({ ...item.provenance }) : null,
     contentProjected,
     ...(contentProjected ? { content: item.content } : {})
   });

package/src/tooling/portable/adapters/cli/cli.handoff-manufacture.js

@@ -10,7 +10,7 @@ import { projectRecipientV2HumanOutput } from '../../handoff/recipientV2.humanOu
 import { inspectRecipientFacingV2Topology } from '../../handoff/recipientV2.inspect.js';
 import { carrierLineageFromCliParent, initialHandoffCarrierLineage, parentHandoffCarrierLineageFromBundle, parentHandoffCarrierProfileFromBundle } from '../../handoff/carrierLineage.js';
 import { loadNodePortableInput } from '../../input/node.input.js';
-import { reserveHandoffSiblingIndex } from './cli.handoff-sibling-allocation.js';
+import { resolveHandoffSiblingAllocation } from './cli.handoff-sibling-allocation.js';
 import { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
 
 export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime = {}) {
@@ -26,7 +26,6 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
   const handoffPath = flags.handoff || parsed.positionals?.[1] || continuationState.returnHandoffPath || '';
   if (!flags['workspace-id'] && continuationState.workspaceId) flags['workspace-id'] = continuationState.workspaceId;
   if (!flags['workspace-target'] && continuationState.workspaceTarget) flags['workspace-target'] = continuationState.workspaceTarget;
-  if (!flags['package-sibling-index'] && continuationState.returnPackageSiblingIndex) flags['package-sibling-index'] = continuationState.returnPackageSiblingIndex;
   if (!flags['package-parent'] && continuationState.packageParentPath) flags['package-parent'] = continuationState.packageParentPath;
   if (!flags.route && handoffPath) flags.route = handoffPath;
   if (!flags.output && !flags['output-dir'] && parsed.surfaceCommand === 'handoff' && continuationState.returnOutputDir) flags['output-dir'] = continuationState.returnOutputDir;
@@ -55,6 +54,7 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
   let packageParentSha256 = '';
   let carrierLineage = initialHandoffCarrierLineage();
   let inheritedCarrierProfile = normalizeHandoffCarrierProfile(null);
+  let carrierAllocation = Object.freeze({ state: 'root', allocationMode: 'initial-root', siblingIndex: null, provenance: Object.freeze({ basis: 'initial-carrier-root' }) });
   if (parentPackagePath) {
     const resolvedParent = path.resolve(parentPackagePath);
     const parentBytes = new Uint8Array(await readFile(resolvedParent));
@@ -86,21 +86,35 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
       major: Boolean(flags['package-major']),
       majorReason: flags['major-reason'] || ''
     });
-    const siblingAllocation = await reserveHandoffSiblingIndex({
-      parentPackagePath: resolvedParent,
-      parentPackageSha256: provisionalLineage.parentPackageSha256,
-      parentDimension: provisionalLineage.parentDimension,
-      enabled: !flags['package-major'] && Boolean(flags.output || flags['output-dir']),
-      siblingIndex: flags['package-sibling-index']
-    });
-    carrierLineage = flags['package-major'] ? provisionalLineage : carrierLineageFromCliParent({
-      bundle: parentBundle,
-      parentPath: resolvedParent,
-      parentBytes,
-      routeDimensions,
-      qualifiedParentLineage: parentLineage,
-      siblingIndex: siblingAllocation.siblingIndex
-    });
+    if (flags['package-major']) {
+      carrierLineage = provisionalLineage;
+      carrierAllocation = Object.freeze({
+        state: 'qualified', allocationMode: 'explicit-major', siblingIndex: null,
+        provenance: Object.freeze({ basis: 'explicit-major-request', parentPackagePath: resolvedParent, parentPackageSha256: provisionalLineage.parentPackageSha256, parentDimension: provisionalLineage.parentDimension }),
+        boundary: 'Carrier Major creation remains explicit and separate from non-Major pointer-order allocation.'
+      });
+    } else {
+      const parentInspection = inspectRecipientFacingV2Topology(parentBundle);
+      const siblingAllocation = await resolveHandoffSiblingAllocation({
+        parentInspection,
+        parentPackagePath: resolvedParent,
+        parentPackageSha256: provisionalLineage.parentPackageSha256,
+        parentDimension: provisionalLineage.parentDimension,
+        selectedRoutePointer: continuationState.selectedRoutePointer || flags['package-parent-route-pointer'] || '',
+        selectedRouteId: continuationState.selectedRouteId || flags['package-parent-route-id'] || '',
+        explicitSiblingIndex: flags['package-sibling-index'],
+        enabled: Boolean(flags.output || flags['output-dir'])
+      });
+      carrierAllocation = siblingAllocation;
+      carrierLineage = carrierLineageFromCliParent({
+        bundle: parentBundle,
+        parentPath: resolvedParent,
+        parentBytes,
+        routeDimensions,
+        qualifiedParentLineage: parentLineage,
+        siblingIndex: siblingAllocation.siblingIndex
+      });
+    }
     packageParentSha256 = String(carrierLineage.parentPackageSha256 || '');
   } else if (flags['package-major']) {
     throw new Error('portable.cli.handoff-carrier.package-major.parent-required');
@@ -129,6 +143,7 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
     verifyRoundtrip,
     recipientRouteSelector: flags.route || '',
     carrierLineage,
+    carrierAllocation,
     carrierProfile,
     packageParentBundle,
     packageParentPath: parentPackagePath ? path.resolve(parentPackagePath) : '',
@@ -329,6 +344,7 @@ export function summarizeHandoffManufactureCliOutput(result = {}, writeReceipt =
     }) : null,
     toolingBootstrap: result.toolingBootstrap || null,
     carrierLineage: result.carrierLineage || projection.lineage || null,
+    carrierAllocation: result.carrierAllocation || result.manufacturingEvidence?.carrierAllocation || null,
     majorReadiness: result.majorReadiness || null,
     operationBoundary: result.operationBoundary ? Object.freeze({ ...result.operationBoundary }) : null,
     manufacturingEvidence: result.manufacturingEvidence || null,

package/src/tooling/portable/adapters/cli/cli.handoff-sibling-allocation.js

@@ -2,6 +2,125 @@ import { mkdir, open, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 const MAX_SIBLING_INDEX = 9999;
+const POINTER_PATH_RE = /^(\d{3}(?:-\d+)*)-handoff-pointer\.trace\.md$/;
+
+export function deriveHandoffSiblingAllocation({ parentInspection = null, selectedRoutePointer = '', selectedRouteId = '', explicitSiblingIndex = null, parentPackagePath = '', parentPackageSha256 = '', parentDimension = '' } = {}) {
+  const explicit = normalizeSiblingIndex(explicitSiblingIndex);
+  const inspection = parentInspection && typeof parentInspection === 'object' ? parentInspection : null;
+  if (!inspection || inspection.detected === false) return freeze({
+    state: 'unavailable',
+    siblingIndex: explicit || null,
+    allocationMode: explicit ? 'explicit-override-only' : 'unavailable',
+    reasonCode: 'qualified-parent-route-topology-unavailable',
+    provenance: provenanceBase({ parentPackagePath, parentPackageSha256, parentDimension, explicitSiblingIndex: explicit }),
+    boundary: allocationBoundary()
+  });
+  if (String(inspection.status || '') !== 'valid') return freeze({
+    state: 'blocked',
+    siblingIndex: null,
+    allocationMode: 'blocked',
+    reasonCode: 'qualified-parent-route-topology-invalid',
+    provenance: provenanceBase({ parentPackagePath, parentPackageSha256, parentDimension, explicitSiblingIndex: explicit }),
+    boundary: allocationBoundary()
+  });
+
+  const routes = [...(inspection.routes || [])].map((route) => ({
+    pointerPath: String(route.pointerPath || '').trim(),
+    routeId: String(route.routeId || '').trim(),
+    workspaceId: String(route.workspaceId || '').trim(),
+    workspaceRelativeHandoffPath: String(route.workspaceRelativeHandoffPath || '').trim()
+  }));
+  if (!routes.length) return blocked('qualified-parent-route-topology-empty');
+
+  const qualified = [];
+  const seenDimensions = new Set();
+  for (const route of routes) {
+    const match = route.pointerPath.match(POINTER_PATH_RE);
+    if (!match) return blocked('qualified-parent-route-pointer-order-unresolved');
+    const dimension = match[1];
+    if (seenDimensions.has(dimension)) return blocked('qualified-parent-route-pointer-order-ambiguous');
+    seenDimensions.add(dimension);
+    qualified.push({ ...route, pointerDimension: dimension, pointerSegments: dimension.split('-').map((value) => Number.parseInt(value, 10)) });
+  }
+  qualified.sort(comparePointerOrder);
+
+  const pointerSelector = String(selectedRoutePointer || '').trim();
+  const routeIdSelector = String(selectedRouteId || '').trim();
+  let selected = null;
+  if (pointerSelector) {
+    const matches = qualified.filter((route) => route.pointerPath === pointerSelector);
+    if (matches.length !== 1) return blocked(matches.length ? 'selected-parent-route-pointer-ambiguous' : 'selected-parent-route-pointer-unqualified');
+    selected = matches[0];
+  }
+  if (routeIdSelector) {
+    const matches = qualified.filter((route) => route.routeId === routeIdSelector);
+    if (matches.length !== 1) return blocked(matches.length ? 'selected-parent-route-id-ambiguous' : 'selected-parent-route-id-unqualified');
+    if (selected && selected.pointerPath !== matches[0].pointerPath) return blocked('selected-parent-route-selector-conflict');
+    selected = matches[0];
+  }
+  if (!selected) {
+    if (qualified.length !== 1) return blocked('selected-parent-route-required-for-parallel-topology');
+    selected = qualified[0];
+  }
+
+  const siblingIndex = qualified.findIndex((route) => route.pointerPath === selected.pointerPath) + 1;
+  if (!Number.isInteger(siblingIndex) || siblingIndex < 1 || siblingIndex > MAX_SIBLING_INDEX) return blocked('derived-sibling-index-out-of-range');
+  if (explicit && explicit !== siblingIndex) return blocked('explicit-sibling-index-conflicts-with-qualified-topology', { expectedSiblingIndex: siblingIndex });
+
+  return freeze({
+    state: 'qualified',
+    siblingIndex,
+    childDimension: parentDimension ? `${String(parentDimension).trim()}-${siblingIndex}` : '',
+    allocationMode: 'qualified-parent-route-pointer-ordinal',
+    explicitOverride: explicit ? 'matched-derived-value' : 'not-supplied',
+    reasonCode: '',
+    provenance: {
+      ...provenanceBase({ parentPackagePath, parentPackageSha256, parentDimension, explicitSiblingIndex: explicit }),
+      basis: 'qualified-parent-route-pointer-ordinal',
+      selectedRoutePointer: selected.pointerPath,
+      selectedRouteId: selected.routeId,
+      selectedWorkspaceId: selected.workspaceId,
+      selectedWorkspaceRelativeHandoffPath: selected.workspaceRelativeHandoffPath,
+      routeOrdinal: siblingIndex,
+      qualifiedRouteCount: qualified.length,
+      pointerOrder: qualified.map((route, index) => Object.freeze({ ordinal: index + 1, pointerPath: route.pointerPath, routeId: route.routeId }))
+    },
+    boundary: allocationBoundary()
+  });
+
+  function blocked(reasonCode, extra = {}) {
+    return freeze({
+      state: 'blocked', siblingIndex: null, allocationMode: 'blocked', reasonCode, ...extra,
+      provenance: provenanceBase({ parentPackagePath, parentPackageSha256, parentDimension, explicitSiblingIndex: explicit }),
+      boundary: allocationBoundary()
+    });
+  }
+}
+
+export async function resolveHandoffSiblingAllocation(input = {}) {
+  const derived = deriveHandoffSiblingAllocation(input);
+  if (derived.state === 'qualified') return derived;
+  if (derived.state === 'blocked') throw new Error(`portable.cli.handoff-carrier.sibling-allocation.${derived.reasonCode}`);
+  const explicit = normalizeSiblingIndex(input.explicitSiblingIndex ?? input.siblingIndex);
+  if (!explicit) throw new Error('portable.cli.handoff-carrier.sibling-allocation.explicit-index-required-when-topology-unavailable');
+  const legacy = await reserveHandoffSiblingIndex({
+    parentPackagePath: input.parentPackagePath,
+    parentPackageSha256: input.parentPackageSha256,
+    parentDimension: input.parentDimension,
+    enabled: input.enabled !== false,
+    siblingIndex: explicit
+  });
+  return freeze({
+    ...legacy,
+    allocationMode: 'explicit-advanced-override',
+    explicitOverride: 'required-because-qualified-topology-unavailable',
+    provenance: {
+      ...provenanceBase({ ...input, explicitSiblingIndex: explicit }),
+      basis: 'explicit-advanced-override-without-qualified-route-topology'
+    },
+    boundary: allocationBoundary()
+  });
+}
 
 export async function reserveHandoffSiblingIndex({ parentPackagePath = '', parentPackageSha256 = '', parentDimension = '', enabled = true, siblingIndex = null } = {}) {
   const requestedSiblingIndex = normalizeSiblingIndex(siblingIndex);
@@ -35,21 +154,39 @@ export async function reserveHandoffSiblingIndex({ parentPackagePath = '', paren
   }
 }
 
+function comparePointerOrder(left, right) {
+  const a = left.pointerSegments || [], b = right.pointerSegments || [];
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] === undefined) return -1;
+    if (b[index] === undefined) return 1;
+    if (a[index] !== b[index]) return a[index] - b[index];
+  }
+  return left.pointerPath.localeCompare(right.pointerPath);
+}
+
+function provenanceBase({ parentPackagePath = '', parentPackageSha256 = '', parentDimension = '', explicitSiblingIndex = null } = {}) {
+  return {
+    parentPackagePath: String(parentPackagePath || ''),
+    parentPackageSha256: String(parentPackageSha256 || '').trim().toLowerCase(),
+    parentDimension: String(parentDimension || '').trim(),
+    explicitSiblingIndex: explicitSiblingIndex ? normalizeSiblingIndex(explicitSiblingIndex) : null
+  };
+}
+function allocationBoundary() { return 'Transport-only carrier allocation. A non-Major sibling ordinal may come only from exact qualified package-local Handoff Pointer order for the selected parent route, or from an explicit advanced override when such topology is unavailable. Allocation never creates semantic Parent, Workspace, Role, acceptance, completion, participant, process, or source authority; different carrier prefixes are not coordinated.'; }
 function normalizeSiblingIndex(value) {
   if (value === null || value === undefined || value === '') return 0;
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_SIBLING_INDEX) throw new Error('portable.cli.handoff-carrier.sibling-allocation.index-invalid');
   return parsed;
 }
-
 async function readAllocation(allocationPath) {
   try { return JSON.parse(await readFile(allocationPath, 'utf8')); }
   catch { throw new Error('portable.cli.handoff-carrier.sibling-allocation.existing-reservation-invalid'); }
 }
-
 function sameAllocation(left = {}, right = {}) {
   return String(left.parentPackageSha256 || '') === String(right.parentPackageSha256 || '')
     && String(left.parentDimension || '') === String(right.parentDimension || '')
     && Number(left.siblingIndex || 0) === Number(right.siblingIndex || 0)
     && String(left.childDimension || '') === String(right.childDimension || '');
 }
+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/adapters/cli/cli.help.js

@@ -83,7 +83,7 @@ function commonCommandHelp(command, surfaceCommand) {
     '',
     `${command} handoff <workspace-dir>`,
     '',
-    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent as carrier-lineage evidence, canonical projected filename, and return output directory. When the outgoing Handoff declares `Signal Kind: return`, delegation manufacture is transport-not-ready unless the delegator supplies `--return-package-sibling-index <1..9999>` for the expected non-Major return, or explicitly declares `--return-package-major`; the qualified reservation is carried in the route pointer and later continuation state. A non-major continuation that writes a carrier must supply an explicitly coordinated `--package-sibling-index <1..9999>`; Tooling will not silently discover the next sibling because isolated runtimes cannot prove a globally unique reservation. Distinct explicit sibling indexes preserve same-Major parallelism, while byte-identical duplicate transport at one exact output path is idempotent and divergent bytes fail closed. It does not implicitly carry sibling Workspaces from the received package; advanced manufacture must select exact reusable parent snapshots with `--package-parent-workspaces <id,...|all>`. Recovery/integration manufacture can bind the reconciled byte proof with `--require-reconciliation-proof --reconciliation-proof <full-reconcile-receipt.json>`; missing, non-ready, edited, or source-stale proof blocks package output. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
+    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent as carrier-lineage evidence, canonical projected filename, and return output directory. Ordinary non-Major continuation derives its sibling ordinal from the exact qualified selected Handoff Pointer order in the received parent carrier, so common-path `handoff` does not require `--package-sibling-index` or `--return-package-sibling-index`. A single selected Pointer derives `-1`; parallel qualified Pointers derive dense local ordinals in Pointer order, and each returned branch continues from its own carrier. `--package-sibling-index` remains an advanced compatibility override only when qualified route topology is unavailable, and must match when topology already proves the value; conflicting or ambiguous topology fails closed. `--return-package-major` remains the explicit Major-return declaration. Different carrier prefixes are never globally coordinated. Byte-identical duplicate transport at one exact output path is idempotent and divergent bytes fail closed. It does not implicitly carry sibling Workspaces from the received package; advanced manufacture must select exact reusable parent snapshots with `--package-parent-workspaces <id,...|all>`. Recovery/integration manufacture can bind the reconciled byte proof with `--require-reconciliation-proof --reconciliation-proof <full-reconcile-receipt.json>`; missing, non-ready, edited, or source-stale proof blocks package output. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
     '',
     `Advanced/internal catalog: ${command} operations`
   ];

package/src/tooling/portable/adapters/cli/cli.run.js

@@ -134,6 +134,9 @@ function cliColdStartQualificationSummary(result = {}, flags = {}) {
     return Object.freeze({
       requirementId: item.requirementId,
       name: item.name,
+      material: item.material,
+      purpose: item.purpose,
+      declaredAvailability: item.declaredAvailability,
       state: item.state,
       referenceTarget: item.referenceTarget,
       kind: item.kind,
@@ -147,6 +150,7 @@ function cliColdStartQualificationSummary(result = {}, flags = {}) {
       actualBytes: item.actualBytes,
       actualSha256: item.actualSha256,
       contentState: item.contentState,
+      provenance: item.provenance,
       contentProjected,
       ...(contentProjected ? { content: item.content } : {})
     });

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

@@ -6,7 +6,7 @@ import { qualifyToolingRuntimeSourceAlignment } from './handoff.manufacture.runt
 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 { preparePackageParentWorkspaceReuse, projectRequiredContextWorkspaceSelectionPreflight } from './handoff.manufacture.packageParent.js';
 import { qualifyPortableSourceReconciliationProofForManufacture } from '../../comparison/sourceFrontierReconciliationProof.js';
 import { qualifyPortableManufactureSchemaReferenceCandidate } from '../../handoff/schemaReferencePreflight.js';
 import { qualifyDelegationReturnReservation } from '../../handoff/delegationReturnReservation.js';
@@ -46,14 +46,6 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     (value) => Object.freeze({ value, error: null }),
     (error) => Object.freeze({ value: null, error })
   );
-  const enumerationPromise = enumerateNodeWorkspace(workspaceRoot, {
-    workspaceId,
-    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 || []);
   const seenWorkspaceIds = new Set([workspaceId]);
   const additionalWorkspaceInputs = additionalWorkspaceDescriptors.map((descriptor) => {
@@ -77,6 +69,23 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     workspaceIds: input.packageParentWorkspaceIds || input.reusePackageParentWorkspaceIds || [],
     workspaceAliases: input.packageParentWorkspaceAliases || input.workspaceAliases || {}
   });
+  const handoffMarkdown = await handoffMarkdownPromise;
+  const requiredContextWorkspaceSelectionPreflight = projectRequiredContextWorkspaceSelectionPreflight({
+    handoffMarkdown,
+    currentWorkspaceIds: [...seenWorkspaceIds],
+    packageParentReuse
+  });
+  if (requiredContextWorkspaceSelectionPreflight.state === 'action-required') {
+    throw new Error(`portable.handoff-manufacture.required-context.workspace-selection.required: ${requiredContextWorkspaceSelectionPreflight.nextAction} Missing Workspace ids: ${requiredContextWorkspaceSelectionPreflight.missingWorkspaceIds.join(',')}. Tooling will not auto-select package-parent Workspace source from carrier lineage.`);
+  }
+  const enumerationPromise = enumerateNodeWorkspace(workspaceRoot, {
+    workspaceId,
+    workspaceTitle: requestedWorkspaceTitle,
+    sourceMetadata: input.workspaceSource || input.sourceMetadata || {},
+    excludeDirectories: input.excludeDirectories || options.excludeDirectories,
+    excludeRelativePaths: input.excludeRelativePaths || options.excludeRelativePaths,
+    maxFiles: input.maxFiles || options.maxFiles
+  });
   const additionalEnumerationsPromise = Promise.all(additionalWorkspaceInputs.map(async ({ descriptor, id, root, requestedTitle }) => {
     const enumerated = await enumerateNodeWorkspace(root, {
       workspaceId: id,
@@ -90,8 +99,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     return Object.freeze({ descriptor, id, root, requestedTitle, enumerated });
   }));
 
-  const [handoffMarkdown, enumeration, additionalEnumerations] = await Promise.all([
-    handoffMarkdownPromise,
+  const [enumeration, additionalEnumerations] = await Promise.all([
     enumerationPromise,
     additionalEnumerationsPromise
   ]);
@@ -132,7 +140,8 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
   }
   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 })
+    && (returnCarrierReservationPreflight.carrierKind === 'major' || Number.isInteger(returnCarrierReservationPreflight.siblingIndex))
+    ? Object.freeze({ carrierKind: returnCarrierReservationPreflight.carrierKind, ...(Number.isInteger(returnCarrierReservationPreflight.siblingIndex) ? { 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({
@@ -197,6 +206,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     transportRoutes,
     workspaceTargets,
     carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null),
+    carrierAllocation: input.carrierAllocation ? Object.freeze({ ...input.carrierAllocation }) : null,
     carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null),
     toolingBootstrap: toolingBootstrap.summary,
     reconciliationProofQualification,
@@ -210,6 +220,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
       reconciliationProof: reconciliationProofQualification,
       schemaReferencePreflight,
       returnCarrierReservationPreflight,
+      carrierAllocation: input.carrierAllocation ? Object.freeze({ ...input.carrierAllocation }) : null,
       packageParentWorkspaceReuse: Object.freeze({
         state: String(packageParentReuse.state || ''),
         providerState: String(packageParentReuse.providerState || ''),
@@ -217,10 +228,12 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
         selectionMode: String(packageParentReuse.selectionMode || ''),
         requestedWorkspaceIds: Object.freeze([...(packageParentReuse.requestedWorkspaceIds || [])].map(String)),
         providerWorkspaceIds: Object.freeze([...(packageParentReuse.providerWorkspaceIds || [])].map(String)),
+        providerWorkspaceTargets: Object.freeze([...(packageParentReuse.providerWorkspaceTargets || [])].map((item) => Object.freeze({ ...item }))),
         inheritedWorkspaceIds: Object.freeze((packageParentReuse.inherited || []).map((item) => String(item.id || ''))),
         workspaceAliases: Object.freeze([...(packageParentReuse.workspaceAliases || [])].map((item) => Object.freeze({ ...item }))),
         boundary: String(packageParentReuse.boundary || '')
       }),
+      requiredContextWorkspaceSelectionPreflight,
       carrierProjection: Object.freeze({ requestedRoutes: transportRoutes.length || 1, carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null), carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null), boundary: 'Routes are qualified later against packaged workspace bytes; adapter text is not authority.' })
     }),
     verifyRoundtrip: input.verifyRoundtrip !== false