@tiinex/core 0.18.0 → 0.20.0

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

@@ -11,6 +11,8 @@ import { runPortableOperation } from '../../operation.catalog.js';
 import { markPortableBootstrapCanonicalSource } from '../../providers/schema.bootstrap.provenance.js';
 import { allocateContinuationPath, allocateDirectoryArtifactPath } from '../../../../transitions/record.transitions.js';
 import { classifyParentRecoveryReference } from '../../../../lineage/parentRecoveryReference.js';
+import { creationSchemaReferenceValidationContext } from '../../draft/draft.validation-context.js';
+import { isQualifiedIdentifierOnlyHistoricalSchemaReferenceAuthority, qualifiedIdentifierOnlyHistoricalSchemaReferenceAuthority } from '../../../../schemas/schema.reference.js';
 
 const STATE_RELATIVE_PATH = '.tiinex/continuation.json';
 
@@ -66,16 +68,21 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
     await writeFile(artifactPath, markdown, { encoding: 'utf8', flag: flags.overwrite ? 'w' : 'wx' });
     wrote = true;
     const auditMaterial = await loadNodePortableInput(
-      [artifactPath, ...(parentPath ? [parentPath] : [])],
+      [artifactPath],
       { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] }
     );
-    const audit = await runPortableOperation('audit', auditMaterial, {});
+    const candidateAudit = await runPortableOperation('audit', auditMaterial, {});
+    const parentAudit = parentPath
+      ? await runHistoricalParentAudit(parentPath, parentRecord, contract, flags)
+      : null;
+    const audit = mergeAuthorAuditResults(candidateAudit, parentAudit);
     const stageMaterial = await loadNodePortableInput(
       normalizeRuntimePaths(runtime.defaultSchemaMaterialPaths),
       { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] }
     );
     const stage = await runPortableOperation('stage-draft', {
       ...stageMaterial,
+      schemaReferenceAuthorities: creationSchemaReferenceValidationContext(contract, parentRecord),
       draft: { path: artifactRelativePath, markdown, schemaId, sourceMode: 'local-common-author', source: null }
     }, {});
     const blocking = Number(audit?.findingSummary?.counts?.error || 0) + Number(stage?.findingSummary?.counts?.error || 0);
@@ -87,7 +94,7 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
         schema: 'tiinex.portable.common-author.result.v1',
         operation: 'author',
         status: 'blocked',
-        artifact: Object.freeze({ path: artifactRelativePath, schemaId, written: false }),
+        artifact: Object.freeze({ path: artifactRelativePath, schemaId, written: false, parentPath: parentReference, parentSource: parentSource || '', parentSchemaReferenceAuthority: projectHistoricalParentReferenceAuthority(parentRecord) }),
         audit,
         stage,
         findingSummary: mergeFindingSummaries(audit?.findingSummary, stage?.findingSummary),
@@ -105,7 +112,7 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
       schema: 'tiinex.portable.common-author.result.v1',
       operation: 'author',
       status: 'qualified',
-      artifact: Object.freeze({ path: artifactRelativePath, absolutePath: artifactPath, schemaId, parentPath: parentReference, parentSource: parentSource || '', selfIntegrity: selfIntegrity.state, written: true }),
+      artifact: Object.freeze({ path: artifactRelativePath, absolutePath: artifactPath, schemaId, parentPath: parentReference, parentSource: parentSource || '', parentSchemaReferenceAuthority: projectHistoricalParentReferenceAuthority(parentRecord), selfIntegrity: selfIntegrity.state, written: true }),
       qualification: Object.freeze({ audit: audit.status, stage: stage.status, exportReady: Boolean(stage?.stagedArtifact?.qualification?.exportReady) }),
       findingSummary: mergeFindingSummaries(audit?.findingSummary, stage?.findingSummary),
       nextAction: schemaId === 'tiinex.handoff.v1'
@@ -120,6 +127,88 @@ export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
   }
 }
 
+async function runHistoricalParentAudit(parentPath, parentRecord = {}, contract = {}, flags = {}) {
+  const material = await loadNodePortableInput(
+    [parentPath],
+    { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] }
+  );
+  const exactCurrentMatch = sameExactSchemaReferenceAuthority(
+    parentRecord.schemaReferenceAuthority || null,
+    contract?.schemaReferences?.current || null,
+    parentRecord.schemaId || parentRecord.currentSchemaId || ''
+  );
+  return runPortableOperation('audit', material, {
+    schemaReferenceContext: 'historical',
+    schemaReferenceAuthorities: Object.freeze({ current: parentRecord.schemaReferenceAuthority || null }),
+    ...(exactCurrentMatch ? {} : {
+      schemaValidationAuthority: historicalParentSchemaValidationAuthority(parentRecord)
+    })
+  });
+}
+
+export function sameExactSchemaReferenceAuthority(parentAuthority = null, currentAuthority = null, schemaId = '') {
+  if (!parentAuthority || !currentAuthority) return false;
+  const expectedSchemaId = String(schemaId || '').trim();
+  const parentSchemaId = String(parentAuthority.schemaId || '').trim();
+  const currentSchemaId = String(currentAuthority.schemaId || '').trim();
+  if (!expectedSchemaId || parentSchemaId !== expectedSchemaId || currentSchemaId !== expectedSchemaId) return false;
+  if (String(parentAuthority.resolutionState || parentAuthority.state || '') !== 'qualified') return false;
+  if (String(currentAuthority.resolutionState || currentAuthority.state || '') !== 'qualified') return false;
+  const parentTargets = exactSchemaReferenceTargets(parentAuthority);
+  const currentTargets = new Set(exactSchemaReferenceTargets(currentAuthority));
+  return parentTargets.length > 0 && parentTargets.some((target) => currentTargets.has(target));
+}
+
+function exactSchemaReferenceTargets(authority = {}) {
+  return [...new Set([
+    ...(Array.isArray(authority.exactTargets) ? authority.exactTargets : []),
+    authority.preferredTarget || authority.target || ''
+  ].map((item) => String(item || '').trim()).filter(Boolean))];
+}
+
+function historicalParentSchemaValidationAuthority(parentRecord = {}) {
+  const schemaId = String(parentRecord.schemaId || parentRecord.currentSchemaId || '').trim();
+  const target = String(parentRecord.schemaReferenceAuthority?.preferredTarget || parentRecord.schemaReferenceAuthority?.target || '').trim();
+  const identifierOnly = isQualifiedIdentifierOnlyHistoricalSchemaReferenceAuthority(parentRecord.schemaReferenceAuthority || {});
+  return Object.freeze({
+    schema: 'tiinex.portable.historical-parent-schema-validation-authority.v1',
+    state: 'unavailable',
+    reason: identifierOnly ? 'historical-parent-schema-revision-unresolved-identifier-only' : 'historical-parent-schema-revision-not-qualified-as-current-candidate-authority',
+    schemaId,
+    currentReference: Object.freeze({
+      state: identifierOnly ? 'historical-identifier-only-preserved' : target ? 'historical-exact-reference-preserved' : 'unavailable',
+      basis: identifierOnly ? 'historical-parent-declared-schema-identifier-only' : 'historical-parent-declared-schema-reference',
+      raw: '',
+      target,
+      exactRevisionState: identifierOnly ? 'unresolved' : target ? 'declared-exact-reference' : 'unavailable'
+    }),
+    lineage: Object.freeze([]),
+    findings: Object.freeze([
+      identifierOnly
+        ? `Historical Parent ${parentRecord.path || parentRecord.id || '(parent)'} preserves only the declared ${schemaId || 'Current Schema'} identifier; exact historical schema revision remains unresolved and current candidate schema validation is withheld for the Parent.`
+        : `Historical Parent ${parentRecord.path || parentRecord.id || '(parent)'} is preserved under its exact declared ${schemaId || 'Current Schema'} reference${target ? ` ${target}` : ''}; current candidate schema validation is withheld because exact same-revision current authority is not qualified.`
+    ]),
+    compiledContract: null,
+    boundary: 'Historical Parent validation still runs Root readability, exact declared schema-identifier/reference-shape checks, recovery and integrity. Identifier-only authority never becomes exact historical schema-revision authority; current schema-specific machine/companion validation is applied only when the Parent and current creation contract share exact qualified schema-revision authority.'
+  });
+}
+
+function mergeAuthorAuditResults(candidateAudit = {}, parentAudit = null) {
+  if (!parentAudit) return candidateAudit;
+  const audits = Object.freeze([...(candidateAudit.audits || []), ...(parentAudit.audits || [])]);
+  const findings = Object.freeze([...(candidateAudit.findings || []), ...(parentAudit.findings || [])]);
+  return Object.freeze({
+    ...candidateAudit,
+    audits,
+    findings,
+    findingSummary: mergeFindingSummaries(candidateAudit.findingSummary, parentAudit.findingSummary),
+    boundary: Object.freeze({
+      ...(candidateAudit.boundary || {}),
+      historicalParentAudit: 'separate exact-byte historical audit; current schema-specific validation only when exact same-revision authority is qualified'
+    })
+  });
+}
+
 async function parentRecordFromArtifact(parentPath, parentRelativePath, context = {}) {
   const markdown = await readFile(parentPath, 'utf8');
   const parsed = parseArtifactMarkdown(markdown);
@@ -131,8 +220,11 @@ async function parentRecordFromArtifact(parentPath, parentRelativePath, context
   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: 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.`);
+    : qualifiedIdentifierOnlyHistoricalSchemaReferenceAuthority(schemaId, {
+      basis: 'exact-historical-parent-current-schema-identifier',
+      parentPath: String(parentRelativePath || ''),
+      parentSha256: sha256Hex(utf8Bytes(markdown))
+    });
   return Object.freeze({
     id: parentRelativePath,
     path: parentRelativePath,
@@ -146,6 +238,25 @@ async function parentRecordFromArtifact(parentPath, parentRelativePath, context
   });
 }
 
+function projectHistoricalParentReferenceAuthority(parentRecord = {}) {
+  const authority = parentRecord?.schemaReferenceAuthority || null;
+  if (!authority || !String(parentRecord?.schemaId || parentRecord?.currentSchemaId || '').trim()) return null;
+  const schemaId = String(parentRecord.schemaId || parentRecord.currentSchemaId || '').trim();
+  const target = String(authority.preferredTarget || authority.target || '').trim();
+  const identifierOnly = isQualifiedIdentifierOnlyHistoricalSchemaReferenceAuthority(authority);
+  return Object.freeze({
+    state: String(authority.resolutionState || authority.state || 'unavailable'),
+    kind: identifierOnly ? 'identifier-only' : target ? 'exact-target' : 'unresolved',
+    schemaId,
+    target,
+    exactRevisionState: identifierOnly ? 'unresolved' : target ? 'declared-exact-reference' : 'unresolved',
+    provenance: Object.freeze({ ...(authority.resolutionEvidence || authority.evidence || {}) }),
+    boundary: identifierOnly
+      ? 'Exact historical Parent artifact identity/integrity and declared schema identifier are qualified; no exact historical schema representation target is claimed or inferred.'
+      : 'Historical Parent schema-reference authority is projected only at the exact strength carried by the supplied Parent bytes.'
+  });
+}
+
 function projectAuthorActionableFindings(audit = {}, stage = {}) {
   const findings = [
     ...(audit.findings || audit.actionableFindings || []),

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

@@ -104,6 +104,7 @@ function projectGroundDefault(result = {}, parsed = {}) {
     readiness: compactReadiness(result.readiness),
     authority: compactGroundAuthority(result.authority),
     orchestrationReadiness: compactOrchestrationReadiness(result.orchestrationReadiness),
+    delegationReadiness: compactDelegationReadiness(result.delegationReadiness),
     requiredContext: Object.freeze({
       declared: Number(required.declared || 0),
       matchedInWorkspaceSnapshots: Number(required.matchedInWorkspaceSnapshots || 0),
@@ -163,6 +164,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 || ''),
@@ -275,11 +277,17 @@ 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),
       provenance: holderBinding.provenance ? Object.freeze({ ...holderBinding.provenance }) : null
@@ -293,6 +301,24 @@ function compactGroundAuthority(authority = {}) {
   });
 }
 
+
+function compactDelegationReadiness(value = {}) {
+  if (!value || typeof value !== 'object') return null;
+  return Object.freeze({
+    state: String(value.state || ''),
+    delegateCapabilityAuthority: value.delegateCapabilityAuthority ? Object.freeze({ ...value.delegateCapabilityAuthority }) : null,
+    processApplicability: value.processApplicability ? Object.freeze({ ...value.processApplicability }) : null,
+    targetAuthority: value.targetAuthority ? Object.freeze({ ...value.targetAuthority }) : null,
+    sourceAuthority: value.sourceAuthority ? Object.freeze({ ...value.sourceAuthority }) : null,
+    returnReconciliationExpectation: value.returnReconciliationExpectation ? Object.freeze({ ...value.returnReconciliationExpectation }) : null,
+    blockers: Object.freeze((value.blockers || []).slice(0, 8).map((item) => Object.freeze({ ...item }))),
+    plainChatFallbackPermitted: Boolean(value.plainChatFallbackPermitted),
+    repositoryScanningFallbackPermitted: Boolean(value.repositoryScanningFallbackPermitted),
+    nextOperations: Object.freeze((value.nextOperations || []).slice(0, 4).map((item) => Object.freeze({ ...item }))),
+    boundary: String(value.boundary || '')
+  });
+}
+
 function compactOrchestrationReadiness(value = {}) {
   if (!value || typeof value !== 'object') return null;
   const wider = value.widerOrchestration || {};

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/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, projectRequiredContextWorkspaceSelectionPreflight } from './handoff.manufacture.packageParent.js';
+import { preparePackageParentExactMaterialProvider, preparePackageParentWorkspaceReuse, projectPackageParentMaterialClosurePreflight, projectRequiredContextWorkspaceSelectionPreflight, resolvePackageParentRequirementMaterials } from './handoff.manufacture.packageParent.js';
 import { qualifyPortableSourceReconciliationProofForManufacture } from '../../comparison/sourceFrontierReconciliationProof.js';
 import { qualifyPortableManufactureSchemaReferenceCandidate } from '../../handoff/schemaReferencePreflight.js';
 import { qualifyDelegationReturnReservation } from '../../handoff/delegationReturnReservation.js';
@@ -69,6 +69,12 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
     workspaceIds: input.packageParentWorkspaceIds || input.reusePackageParentWorkspaceIds || [],
     workspaceAliases: input.packageParentWorkspaceAliases || input.workspaceAliases || {}
   });
+  const packageParentExactMaterialProvider = preparePackageParentExactMaterialProvider({
+    bundle: input.packageParentBundle || null,
+    currentWorkspaceIds: [...seenWorkspaceIds],
+    parentPackagePath: input.packageParentPath || '',
+    parentPackageSha256: input.packageParentSha256 || ''
+  });
   const handoffMarkdown = await handoffMarkdownPromise;
   const requiredContextWorkspaceSelectionPreflight = projectRequiredContextWorkspaceSelectionPreflight({
     handoffMarkdown,
@@ -140,7 +146,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({
@@ -168,16 +175,18 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
 
   const routeSpecs = transportRoutes.length ? transportRoutes : Object.freeze([{ workspaceId, path: handoffPath }]);
   let requirements = await projectManufacturingRequirements({ handoff, workspaceId, handoffPath, routeSpecs, workspaceRuntimeById });
+  const packageParentMaterialClosurePreflight = projectPackageParentMaterialClosurePreflight(requirements, packageParentExactMaterialProvider);
   let materials = await resolveWorkspaceRequirementMaterials(requirements, workspaceRuntimeById, input.materialBindings || {});
+  materials = appendMissingRequirementMaterials(materials, resolvePackageParentRequirementMaterials(requirements, packageParentExactMaterialProvider));
   const dependencyClosure = await expandPointerDependencyClosure({ requirements, materials, workspaceRuntimeById, bindings: input.materialBindings || {} });
   requirements = dependencyClosure.requirements;
-  materials = dependencyClosure.materials;
+  materials = appendMissingRequirementMaterials(dependencyClosure.materials, resolvePackageParentRequirementMaterials(requirements, packageParentExactMaterialProvider));
   const routeParentBoundaryClosure = expandRouteParentBoundaryClosure({ requirements, materials, workspaceMaterializations, workspaceRuntimeById, routeSpecs });
   requirements = routeParentBoundaryClosure.requirements;
-  materials = routeParentBoundaryClosure.materials;
+  materials = appendMissingRequirementMaterials(routeParentBoundaryClosure.materials, resolvePackageParentRequirementMaterials(requirements, packageParentExactMaterialProvider));
   const parentBoundaryClosure = expandBoundedParentBoundaryClosure({ requirements, materials, workspaceMaterializations, workspaceRuntimeById });
   requirements = parentBoundaryClosure.requirements;
-  materials = parentBoundaryClosure.materials;
+  materials = appendMissingRequirementMaterials(parentBoundaryClosure.materials, resolvePackageParentRequirementMaterials(requirements, packageParentExactMaterialProvider));
   const toolingBootstrapResult = await toolingBootstrapPromise;
   if (toolingBootstrapResult.error) throw toolingBootstrapResult.error;
   const toolingBootstrap = toolingBootstrapResult.value;
@@ -205,6 +214,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,
@@ -218,6 +228,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 || ''),
@@ -230,6 +241,7 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
         workspaceAliases: Object.freeze([...(packageParentReuse.workspaceAliases || [])].map((item) => Object.freeze({ ...item }))),
         boundary: String(packageParentReuse.boundary || '')
       }),
+      packageParentMaterialClosurePreflight,
       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.' })
     }),
@@ -238,6 +250,19 @@ export async function prepareNodeHandoffManufacturingInput(input = {}, options =
 }
 
 
+function appendMissingRequirementMaterials(existing = [], additional = []) {
+  const out = [...(existing || [])];
+  const alreadyBound = new Set(out.map((item) => String(item.requirementId || '')).filter(Boolean));
+  for (const item of additional || []) {
+    const id = String(item.requirementId || '');
+    if (id && alreadyBound.has(id)) continue;
+    out.push(item);
+    if (id) alreadyBound.add(id);
+  }
+  return Object.freeze(out);
+}
+
+
 function mergeWorkspaceTargetBindings(explicit = [], inherited = []) {
   const out = [];
   const seen = new Set();