@tiinex/core 0.1.1

package/src/tooling/portable/adapters/cli/cli.ground-materialize.js

@@ -0,0 +1,96 @@
+import { mkdir, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { inspectRecipientFacingV2Topology } from '../../handoff/recipientV2.inspect.js';
+import { handoffWorkspaceProviderForId } from '../../handoff/workspaceByteProvider.js';
+
+export function groundContinuationOperationInput(input = {}, flags = {}) {
+  return Object.freeze({
+    ...input,
+    includeRequiredContext: flags['include-required-context'] || (flags.continue && flags.full ? 'all' : input.includeRequiredContext || ''),
+    includeCurrentWork: Boolean(flags['include-current-work'] || flags.continue || input.includeCurrentWork)
+  });
+}
+
+export async function materializeGroundWorkspaceCliOutput(result = {}, input = {}, flags = {}) {
+  const outputValue = stringFlag(flags.continue) || stringFlag(flags['materialize-workspace']) || stringFlag(flags['workspace-output']);
+  if (!outputValue) {
+    if (flags.continue === true) throw new Error('portable.cli.ground.continue-output.required');
+    if (flags['materialize-workspace'] === true) throw new Error('portable.cli.ground.workspace-output.required');
+    return result;
+  }
+  if (String(result?.readiness?.state || '') !== 'grounded-to-act') throw new Error('portable.cli.ground.workspace-materialization.requires-grounded-to-act');
+  const inspection = inspectRecipientFacingV2Topology(input.bundle || input.package || input);
+  if (String(inspection.status || '') !== 'valid') throw new Error('portable.cli.ground.workspace-materialization.package-unqualified');
+  const workspaceId = String(flags.workspace || result?.authority?.route?.workspaceId || '').trim();
+  if (!workspaceId) throw new Error('portable.cli.ground.workspace-id.required');
+  const workspace = handoffWorkspaceProviderForId(inspection.workspaceByteProvider, workspaceId);
+  if (String(workspace.state || '') !== 'qualified') throw new Error(`portable.cli.ground.workspace-unqualified:${workspaceId}`);
+
+  const outputDir = path.resolve(outputValue);
+  await ensureEmptyOutputDirectory(outputDir);
+  let totalBytes = 0;
+  for (const entry of workspace.entries || []) {
+    const target = safeTarget(outputDir, String(entry.path || ''));
+    await mkdir(path.dirname(target), { recursive: true });
+    const data = byteView(entry.data);
+    await writeFile(target, data);
+    totalBytes += data.byteLength;
+  }
+  const selectedLeafPath = String(result?.lineage?.selectedRouteLeaves?.[0]?.path || '');
+  const selectedHandoffPath = selectedLeafPath.startsWith(`${workspaceId}/`) ? selectedLeafPath.slice(workspaceId.length + 1) : '';
+  const workspaceInspection = (inspection.workspaces || []).find((item) => String(item.workspaceId || '') === workspaceId) || {};
+  const continuationState = Object.freeze({
+    schema: 'tiinex.portable.ground-continuation-state.v1',
+    version: 1,
+    packageParentPath: path.resolve(String(input.packageSourcePath || '')),
+    selectedRoutePointer: String(result?.authority?.route?.pointerPath || input.route || ''),
+    selectedRouteId: String(result?.authority?.route?.id || ''),
+    selectedHandoffPath,
+    workspaceId,
+    workspaceTarget: String(workspaceInspection.sourceWorkspaceTargetInnerPath || ''),
+    roleLabel: String(result?.authority?.role?.label || ''),
+    returnOutputDir: path.dirname(path.resolve(String(input.packageSourcePath || outputDir))),
+    boundary: 'Runtime-only continuation state carried forward from one qualified ground --continue receipt. It is excluded from canonical Workspace manufacture and is not semantic authority.'
+  });
+  const continuationStatePath = path.join(outputDir, '.tiinex', 'continuation.json');
+  await mkdir(path.dirname(continuationStatePath), { recursive: true });
+  await writeFile(continuationStatePath, `${JSON.stringify(continuationState, null, 2)}\n`, 'utf8');
+  const materialization = Object.freeze({
+    schema: 'tiinex.portable.ground-workspace-materialization.v1',
+    state: 'materialized',
+    workspaceId,
+    outputDir,
+    fileCount: (workspace.entries || []).length,
+    totalBytes,
+    archivePackagePath: String(workspace.archive?.packagePath || workspace.archive?.location || ''),
+    coverage: String(workspace.materialization?.materialization || workspace.materialization?.coverage || 'complete'),
+    entriesFingerprint: String(workspace.materialization?.completenessEvidence?.entriesFingerprint || workspace.binding?.completeness?.entriesFingerprint || ''),
+    continuationStatePath,
+    sourceMutation: false,
+    remoteWrite: false,
+    boundary: 'Local exact-byte materialization of one already-qualified carried Workspace plus runtime-only .tiinex continuation state. The runtime state is excluded from canonical Workspace manufacture; no package content is executed, semantic authority is not inferred from filenames or output placement, and the input carrier remains untouched.'
+  });
+  return Object.freeze({ ...result, continuationMaterialization: materialization });
+}
+
+async function ensureEmptyOutputDirectory(outputDir) {
+  await mkdir(outputDir, { recursive: true });
+  const existing = await readdir(outputDir);
+  if (existing.length) throw new Error(`portable.cli.ground.workspace-output.not-empty:${outputDir}`);
+}
+
+function safeTarget(root, relative) {
+  const target = path.resolve(root, relative);
+  const rel = path.relative(root, target);
+  if (!relative || rel === '' || rel.startsWith(`..${path.sep}`) || rel === '..' || path.isAbsolute(rel)) throw new Error(`portable.cli.ground.workspace-path.unsafe:${relative}`);
+  return target;
+}
+
+function byteView(value) {
+  if (value instanceof Uint8Array) return value;
+  if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new Error('portable.cli.ground.workspace-entry.bytes-unavailable');
+}
+
+function stringFlag(value) { return typeof value === 'string' && value.trim() ? value.trim() : ''; }

package/src/tooling/portable/adapters/cli/cli.ground-recovery.js

@@ -0,0 +1,99 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+import { planPortableHostAction, acceptPortableHostActionReceipt, PORTABLE_HOST_ACTION_RECEIPT_SCHEMA_ID } from '../../host/tool.bindings.js';
+import { runPortableOperation } from '../../operation.catalog.js';
+
+export async function continueGroundWithHostResult(result = {}, input = {}, options = {}, flags = {}) {
+  const resultTarget = flags['host-result'];
+  if (!resultTarget) return { result, output: result };
+  const recovery = result?.continuity?.recovery;
+  if (recovery?.state !== 'host-action-available' || !recovery.hostAction) throw new Error('portable.cli.ground.host-result-without-host-action');
+  const { acceptance } = await acceptGroundHostResult(result, input, flags);
+  await persistRecoveryState(flags.state || flags['recovery-state'], acceptance);
+  const resumed = await runPortableOperation('project-grounding-readiness', { ...input, recoveryAcceptance: acceptance }, options);
+  const continuation = Object.freeze({
+    schema: 'tiinex.portable.ground-host-recovery-continuation.v1',
+    state: resumed.status === 'blocked' ? 'recovery-continues' : 'grounding-resumed',
+    hostResultAccepted: true,
+    cumulativeRepositoryFiles: Number(acceptance.cumulativeRecovery?.repositoryFiles || 0),
+    statePath: String(flags.state || flags['recovery-state'] || ''),
+    stateOwnedByTooling: Boolean(flags.state || flags['recovery-state']),
+    nextHostAction: resumed?.continuity?.recovery?.state === 'host-action-available' ? resumed.continuity.recovery.hostAction : null,
+    boundary: 'The caller returns only exact host-result content. Tooling owns plan identity, receipt normalization, cumulative prior acceptance, and resume composition; accepted material remains subject to grounding lineage qualification.'
+  });
+  return { result: resumed, output: Object.freeze({ ...resumed, hostRecoveryContinuation: continuation }) };
+}
+
+
+export async function acceptGroundHostResult(result = {}, input = {}, flags = {}) {
+  const resultTarget = flags['host-result'];
+  const recovery = result?.continuity?.recovery;
+  if (!resultTarget) throw new Error('portable.cli.ground.host-result.required');
+  if (recovery?.state !== 'host-action-available' || !recovery.hostAction) throw new Error('portable.cli.ground.host-result-without-host-action');
+  const content = await readHostResultContent(resultTarget);
+  const action = recovery.hostAction;
+  const plan = planPortableHostAction({ ...input.host, host: input.host, action: action.action, request: action.request });
+  if (plan.status !== 'ready') throw new Error('portable.cli.ground.host-action-plan-blocked');
+  const step = plan.steps.find((entry) => entry.capability === 'repositoryRead');
+  if (!step) throw new Error('portable.cli.ground.repository-read-step.required');
+  const request = action.request || {};
+  const receipt = Object.freeze({
+    schema: PORTABLE_HOST_ACTION_RECEIPT_SCHEMA_ID,
+    actionId: plan.actionId,
+    action: plan.action,
+    steps: Object.freeze([Object.freeze({
+      stepId: step.stepId,
+      toolId: step.tool?.id || action.selectedTool?.id || '',
+      status: 'completed',
+      normalized: Object.freeze({ files: Object.freeze([Object.freeze({
+        path: String(request.path || ''),
+        content,
+        source: Object.freeze({
+          repository: String(request.repository || ''),
+          ref: String(request.ref || ''),
+          commit: String(request.ref || ''),
+          path: String(request.path || ''),
+          authority: 'remote-repository-unverified'
+        })
+      })]) })
+    })])
+  });
+  const acceptance = acceptPortableHostActionReceipt({ plan, receipt, priorAcceptance: input.recoveryAcceptance || {} });
+  if (acceptance.status !== 'accepted') throw new Error('portable.cli.ground.host-result-rejected');
+  return Object.freeze({ plan, acceptance });
+}
+
+
+async function readGroundRecoveryState(file = '') {
+  if (!file) return {};
+  try { return JSON.parse(await readFile(file, 'utf8')); }
+  catch (error) { if (error?.code === 'ENOENT') return {}; throw error; }
+}
+
+export function hostToolProfile(host = {}, hostTool = '') {
+  const name = String(hostTool || '').trim();
+  if (!name) return host;
+  const tools = Array.isArray(host?.tools) ? host.tools : [];
+  if (tools.some((tool) => String(tool?.id || tool?.name || tool) === name)) return host;
+  return Object.freeze({ ...host, tools: Object.freeze([...tools, Object.freeze({ id: name, name })]) });
+}
+
+
+export async function groundInput(flags = {}, baseHost = {}) {
+  const host = hostToolProfile(baseHost, flags['host-tool']);
+  const state = flags.recovery ? JSON.parse(await readFile(flags.recovery, 'utf8')) : await readGroundRecoveryState(flags.state || flags['recovery-state']);
+  return Object.freeze({ host, recoveryAcceptance: state.result || state });
+}
+
+async function readHostResultContent(target) {
+  if (target === true || target === '-') return readFile(0, 'utf8');
+  return readFile(String(target), 'utf8');
+}
+
+async function persistRecoveryState(target, acceptance) {
+  if (!target || target === true || target === '-') return;
+  const outputPath = path.resolve(String(target));
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(acceptance, null, 2)}\n`, 'utf8');
+}

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

@@ -0,0 +1,345 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareNodeHandoffManufacturingInput } from '../node/handoff.manufacture.js';
+import { prepareNodeWorkspaceCarrierManufacturingInput } from '../node/workspaceCarrier.manufacture.js';
+import { projectHandoffHumanOutput } from '../../handoff/carrierProjection.js';
+import { writePortableRuntimePackageZip } from '../../output/node.zip.js';
+import { writeRecipientFacingV2PackageZip } from '../../output/recipientV2.zip.js';
+import { projectRecipientV2HumanOutput } from '../../handoff/recipientV2.humanOutput.js';
+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 { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
+
+export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime = {}) {
+  const flags = parsed.flags || {};
+  const workspaceRoot = flags.workspace || parsed.positionals?.[0] || '.';
+  const carrierMode = String(flags['carrier-mode'] || 'handoff').trim().toLowerCase();
+  if (!['handoff', 'workspace'].includes(carrierMode)) throw new Error(`portable.cli.handoff-carrier.carrier-mode.invalid:${carrierMode}`);
+  if (carrierMode === 'workspace') return prepareWorkspaceCarrierCliCommand(flags, workspaceRoot, runtime);
+  const continuationState = parsed.surfaceCommand === 'handoff'
+    ? await readGroundContinuationState(workspaceRoot)
+    : {};
+  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-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;
+  const materialBindings = await readOptionalJson(flags['material-bindings'] || flags.materials);
+  const operatorCarrierProfile = await readOptionalJson(flags['carrier-profile']);
+  const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
+  const workspaceDescriptorValue = await readOptionalJson(flags['workspace-roots'] || flags['workspace-descriptors']);
+  const workspaceTargetValue = await readOptionalJson(flags['workspace-targets']);
+  const workspaceScopeValue = await readOptionalJson(flags['workspace-scopes']);
+  const routeDescriptorValue = await readOptionalJson(flags['workspace-routes'] || flags['handoff-route-descriptors']);
+  const additionalWorkspaces = [
+    ...splitFlag(flags['additional-workspaces']),
+    ...descriptorArray(workspaceDescriptorValue, 'workspaces')
+  ];
+  const handoffRoutes = [
+    ...splitFlag(flags['handoff-routes'] || flags.routes),
+    ...descriptorArray(routeDescriptorValue, 'routes')
+  ];
+  const verifyRoundtrip = !flags['no-roundtrip'];
+  const parentPackagePath = String(flags['package-parent'] || '').trim();
+  let packageParentBundle = null;
+  let packageParentSha256 = '';
+  let carrierLineage = initialHandoffCarrierLineage();
+  let inheritedCarrierProfile = normalizeHandoffCarrierProfile(null);
+  if (parentPackagePath) {
+    const resolvedParent = path.resolve(parentPackagePath);
+    const parentBytes = new Uint8Array(await readFile(resolvedParent));
+    const parentBundle = await loadNodePortableInput([resolvedParent], { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] });
+    packageParentBundle = parentBundle;
+    inheritedCarrierProfile = parentHandoffCarrierProfileFromBundle(parentBundle);
+    let parentLineage = null;
+    let routeDimensions = [];
+    try {
+      // Modern recipient-v2 continuation needs only the qualified package-root lineage
+      // plus exact parent package identity. Avoid broad topology requalification here;
+      // manufacture performs its own full qualification on the newly produced carrier.
+      parentLineage = parentHandoffCarrierLineageFromBundle(parentBundle);
+    } catch {
+      // Explicit compatibility fallback for older carriers that lack a directly
+      // qualified package-root lineage. Preserve the prior strict inspection path.
+      const parentInspection = inspectRecipientFacingV2Topology(parentBundle);
+      parentLineage = parentInspection.carrierProjection?.lineage || null;
+      routeDimensions = (parentInspection.carrierProjection?.routes || []).map((route) => route.dimension);
+      if (parentInspection.status !== 'valid' && !parentLineage?.dimension) throw new Error('portable.cli.handoff-carrier.package-parent.invalid');
+    }
+    // Package-parent lineage is a human progress projection, not Workspace provider authority.
+    const provisionalLineage = carrierLineageFromCliParent({
+      bundle: parentBundle,
+      parentPath: resolvedParent,
+      parentBytes,
+      routeDimensions,
+      qualifiedParentLineage: parentLineage,
+      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'])
+    });
+    carrierLineage = flags['package-major'] ? provisionalLineage : 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');
+  }
+  const carrierProfile = selectCarrierProfile({
+    operator: operatorCarrierProfile,
+    inherited: inheritedCarrierProfile,
+    runtime: runtime.defaultCarrierProfile || null
+  });
+  const input = await prepareNodeHandoffManufacturingInput({
+    workspaceRoot,
+    handoffPath,
+    handoffRoutes,
+    additionalWorkspaces,
+    workspaceId: flags['workspace-id'] || '',
+    workspaceTitle: flags['workspace-title'] || flags.title || '',
+    workspaceTargetPath: flags['workspace-target'] || flags['workspace-artifact'] || '',
+    workspaceTargets: workspaceTargetValue,
+    workspaceScopes: descriptorArray(workspaceScopeValue, 'scopes').length ? descriptorArray(workspaceScopeValue, 'scopes') : workspaceScopeValue,
+    toolingBootstrap: flags['tooling-bootstrap'] || 'embedded',
+    expectedToolingBootstrap,
+    materialBindings,
+    referenceTargets: splitFlag(flags['reference-targets']),
+    maxFiles: flags['max-files'],
+    bootstrapMaxFiles: flags['bootstrap-max-files'],
+    verifyRoundtrip,
+    recipientRouteSelector: flags.route || '',
+    carrierLineage,
+    carrierProfile,
+    packageParentBundle,
+    packageParentPath: parentPackagePath ? path.resolve(parentPackagePath) : '',
+    packageParentSha256
+  }, runtime);
+  return {
+    input,
+    options: {
+      verifyRoundtrip,
+      legacyRecipientV2Compatibility: Boolean(flags['legacy-recipient-v2-compatibility']),
+      packageInput: { builtAt: flags['built-at'] || undefined }
+    }
+  };
+}
+
+export async function materializeHandoffManufactureCliOutput(result = {}, flags = {}) {
+  const workspaceMode = String(result.carrierProjection?.mode || '') === 'workspace';
+  let humanOutput = workspaceMode ? projectWorkspaceCarrierHumanOutput(result) : projectHandoffHumanOutput({
+    projection: result.carrierProjection || {},
+    route: flags.route || '',
+    collisionInstance: flags['collision-instance'] || 1
+  });
+  if (!workspaceMode && result.bundle?.transportFormat) humanOutput = projectRecipientV2HumanOutput(humanOutput, result.inspection || {});
+  const wantsWrite = Boolean(flags.output || flags['output-dir']);
+  const blocked = result.status === 'blocked' || result.transportExecutable === false || Number(result.findingSummary?.counts?.error || 0) > 0;
+  if (!wantsWrite || blocked) return summarizeHandoffManufactureCliOutput(result, {}, humanOutput, null);
+  const shared = result.carrierProjection?.mode === 'shared';
+  if ((shared || flags['output-dir'] || flags['transport-text']) && humanOutput.status !== 'ready') throw new Error(humanOutput.status === 'selection-required' ? 'portable.cli.handoff-carrier.route-selection.required' : 'portable.cli.handoff-carrier.output.blocked');
+  const target = resolveHandoffOutputPath(flags, humanOutput.primary.filename);
+  const writeBundle = result.bundle;
+  const writeReceipt = writeBundle?.transportFormat
+    ? await writeRecipientFacingV2PackageZip(writeBundle, target, writeBundle === result.bundle ? { inspection: result.inspection } : {})
+    : await writePortableRuntimePackageZip(writeBundle, target);
+  if (workspaceMode && flags['transport-text']) throw new Error('portable.cli.workspace-carrier.transport-text.unavailable');
+  const transportTextReceipt = flags['transport-text'] ? await writeTransportTextSidecar(humanOutput, target, flags['transport-text']) : null;
+  return summarizeHandoffManufactureCliOutput(result, writeReceipt, humanOutput, transportTextReceipt);
+}
+
+async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.', runtime = {}) {
+  if (flags.handoff || flags.route || flags.routes || flags['handoff-routes'] || flags['workspace-routes']) throw new Error('portable.cli.workspace-carrier.handoff-route.forbidden');
+  const operatorCarrierProfile = await readOptionalJson(flags['carrier-profile']);
+  const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
+  const workspaceDescriptorValue = await readOptionalJson(flags['workspace-roots'] || flags['workspace-descriptors']);
+  const workspaceTargetValue = await readOptionalJson(flags['workspace-targets']);
+  const additionalWorkspaces = [...splitFlag(flags['additional-workspaces']), ...descriptorArray(workspaceDescriptorValue, 'workspaces')];
+  const verifyRoundtrip = !flags['no-roundtrip'];
+  const carrierProfile = selectCarrierProfile({ operator: operatorCarrierProfile, runtime: runtime.defaultCarrierProfile || null });
+  const input = await prepareNodeWorkspaceCarrierManufacturingInput({
+    workspaceRoot,
+    additionalWorkspaces,
+    workspaceId: flags['workspace-id'] || '',
+    workspaceTitle: flags['workspace-title'] || flags.title || '',
+    workspaceTargetPath: flags['workspace-target'] || flags['workspace-artifact'] || '',
+    workspaceTargets: workspaceTargetValue,
+    toolingBootstrap: flags['tooling-bootstrap'] || 'embedded',
+    expectedToolingBootstrap,
+    maxFiles: flags['max-files'],
+    bootstrapMaxFiles: flags['bootstrap-max-files'],
+    verifyRoundtrip,
+    createdAt: flags['built-at'] || undefined,
+    carrierLineage: Object.freeze({ ...initialHandoffCarrierLineage(), checkpointKind: 'progression', majorReason: '' }),
+    carrierProfile
+  }, runtime);
+  return { input, options: { verifyRoundtrip, packageInput: { builtAt: flags['built-at'] || undefined } } };
+}
+
+function projectWorkspaceCarrierHumanOutput(result = {}) {
+  const projection = result.carrierProjection || {};
+  const ready = result.status === 'ready' && projection.status === 'ready' && projection.mode === 'workspace' && (projection.routes || []).length === 0;
+  const dimension = String(projection.lineage?.dimension || '001');
+  const filename = `tiinex-workspace-${dimension}.handoff-package.zip`;
+  return Object.freeze({
+    schema: 'tiinex.portable.handoff-human-output.v1',
+    status: ready ? 'ready' : 'blocked',
+    primary: ready ? Object.freeze({ kind: 'workspace-package', filename, dimension, parentDimension: String(projection.lineage?.parentDimension || ''), checkpointKind: String(projection.lineage?.checkpointKind || ''), routeId: '', workspaceId: '', workspaceRelativeHandoffPath: '', collisionInstance: 1, singleHumanTransportChoice: true }) : null,
+    normalInlineRouting: null, sharedRouting: null,
+    presentation: Object.freeze({ kind: 'pointerless-workspace-carrier', label: 'Workspace carrier', authority: 'none' }),
+    normalEmissionBoundary: Object.freeze({ allowed: Object.freeze(['package-file']), forbidden: Object.freeze(['handoff-routing-text', 'continue-from-pointer']) }),
+    fallbackTransportText: null, selectedRoute: null, findings: Object.freeze([]),
+    boundary: 'Pointerless Workspace-carrier output projection only. No Handoff routing text exists because the package role declares no Handoff route.'
+  });
+}
+
+export function summarizeHandoffManufactureCliOutput(result = {}, writeReceipt = {}, humanOutput = null, transportTextReceipt = null) {
+  const summarizeRequirement = (item = {}) => Object.freeze({
+    requirementId: String(item.requirementId || ''),
+    classification: String(item.classification || ''),
+    disposition: String(item.disposition || ''),
+    referenceTarget: String(item.referenceTarget || ''),
+    selectedPath: String(item.selectedMaterial?.path || ''),
+    selectedSha256: String(item.selectedMaterial?.sha256 || ''),
+    providerId: String(item.selectedMaterial?.provider?.id || '')
+  });
+  const summarizeWorkspace = (item = {}) => Object.freeze({
+    id: String(item.id || ''),
+    materialization: String(item.materialization || ''),
+    qualification: String(item.qualification || ''),
+    entryCount: Array.isArray(item.includedEntries) ? item.includedEntries.length : 0,
+    completenessState: String(item.completenessEvidence?.state || ''),
+    completenessProof: String(item.completenessEvidence?.proof || ''),
+    scopeState: String(item.scopeEvidence?.state || ''),
+    scopeProof: String(item.scopeEvidence?.proof || '')
+  });
+  const bootstrapInspection = result.toolingBootstrapInspection || {};
+  const projection = result.carrierProjection || {};
+  const routeSummary = Object.freeze((projection.routes || []).map((route) => Object.freeze({
+    id: String(route.id || ''),
+    state: String(route.state || ''),
+    workspaceId: String(route.workspaceId || ''),
+    workspaceRelativePath: String(route.workspaceRelativePath || ''),
+    dimension: String(route.dimension || ''),
+    from: String(route.parties?.from || ''),
+    to: String(route.parties?.to || ''),
+    projectedFilename: String(route.projectedFilename || '')
+  })));
+  return Object.freeze({
+    schema: result.schema || 'tiinex.portable.operation.result.v1',
+    operation: String(result.operation || 'manufacture-handoff-package'),
+    resultSchema: String(result.resultSchema || ''),
+    status: String(result.status || 'unknown'),
+    executable: Boolean(result.executable),
+    transportExecutable: Boolean(result.transportExecutable),
+    verification: Object.freeze({ ...(result.verification || {}) }),
+    planSummary: Object.freeze({
+      status: String(result.plan?.status || 'unknown'),
+      requiredClosureReady: Boolean(result.plan?.requiredClosureReady),
+      semanticHandoffStatus: String(result.plan?.semanticHandoffStatus || 'unknown'),
+      required: Object.freeze((result.plan?.requirements?.required || []).map(summarizeRequirement)),
+      reference: Object.freeze((result.plan?.requirements?.reference || []).map(summarizeRequirement)),
+      workspaces: Object.freeze((result.plan?.workspaceMaterializations || []).map(summarizeWorkspace))
+    }),
+    carrierProjection: Object.freeze({
+      status: String(projection.status || 'unknown'),
+      mode: String(projection.mode || ''),
+      lineage: projection.lineage ? Object.freeze({ ...projection.lineage }) : null,
+      workspaces: Object.freeze((projection.workspaces || []).map((workspace) => Object.freeze({ ...workspace }))),
+      workspace: Object.freeze({ ...(projection.workspace || {}) }),
+      selection: Object.freeze({ ...(projection.selection || {}) }),
+      routes: routeSummary
+    }),
+    humanOutput: humanOutput ? Object.freeze({
+      status: humanOutput.status,
+      primary: humanOutput.primary,
+      normalInlineRouting: humanOutput.normalInlineRouting ? Object.freeze({ ...humanOutput.normalInlineRouting }) : null,
+      sharedRouting: humanOutput.sharedRouting ? Object.freeze({ ...humanOutput.sharedRouting, routes: Object.freeze([...(humanOutput.sharedRouting.routes || [])].map((item) => Object.freeze({ ...item }))) }) : null,
+      presentation: humanOutput.presentation ? Object.freeze({ ...humanOutput.presentation }) : null,
+      normalEmissionBoundary: humanOutput.normalEmissionBoundary ? Object.freeze({ ...humanOutput.normalEmissionBoundary, allowed: Object.freeze([...(humanOutput.normalEmissionBoundary.allowed || [])]) }) : null,
+      fallbackTransportText: humanOutput.fallbackTransportText ? Object.freeze({ ...humanOutput.fallbackTransportText, content: undefined }) : null
+    }) : null,
+    toolingBootstrap: result.toolingBootstrap || null,
+    carrierLineage: result.carrierLineage || projection.lineage || null,
+    majorReadiness: result.majorReadiness || null,
+    operationBoundary: result.operationBoundary ? Object.freeze({ ...result.operationBoundary }) : null,
+    manufacturingEvidence: result.manufacturingEvidence || null,
+    toolingBootstrapInspection: Object.freeze({
+      schema: String(bootstrapInspection.schema || ''),
+      status: String(bootstrapInspection.status || 'unknown'),
+      delivery: String(bootstrapInspection.delivery || 'unknown'),
+      counts: Object.freeze({ ...(bootstrapInspection.counts || {}) }),
+      qualification: Object.freeze({ ...(bootstrapInspection.qualification || {}) })
+    }),
+    roundtripSummary: result.roundtrip ? Object.freeze({
+      schema: String(result.roundtrip.schema || ''),
+      status: String(result.roundtrip.status || 'unknown'),
+      verification: Object.freeze({ ...(result.roundtrip.verification || {}) }),
+      runtimeStatus: String(result.roundtrip.runtime?.status || '')
+    }) : null,
+    findings: Object.freeze((result.findings || []).map((finding) => Object.freeze({
+      severity: String(finding.severity || ''),
+      code: String(finding.code || ''),
+      message: String(finding.message || '')
+    }))),
+    findingSummary: result.findingSummary || null,
+    boundary: String(result.boundary || ''),
+    writeReceipt: writeReceipt?.status ? writeReceipt : null,
+    primaryOutput: writeReceipt?.status ? Object.freeze({ ...writeReceipt, projectedFilename: String(humanOutput?.primary?.filename || ''), selectedRoute: String(humanOutput?.primary?.workspaceRelativeHandoffPath || '') }) : null,
+    transportTextSidecar: transportTextReceipt
+  });
+}
+
+
+function resolveHandoffOutputPath(flags = {}, projectedFilename = '') {
+  const filename = String(projectedFilename || '').trim();
+  if (!filename) throw new Error('portable.cli.handoff-carrier.output-filename.unresolved');
+  if (flags.output) {
+    const requested = path.resolve(String(flags.output));
+    if (path.basename(requested) !== filename) throw new Error('portable.cli.handoff-carrier.output-filename.mismatch');
+    return requested;
+  }
+  if (!flags['output-dir']) throw new Error('portable.cli.handoff-carrier.output-dir.required');
+  return path.resolve(String(flags['output-dir']), filename);
+}
+async function writeTransportTextSidecar(humanOutput, packageTarget, flagValue) {
+  const target = flagValue === true
+    ? defaultSidecarPath(packageTarget)
+    : path.resolve(String(flagValue));
+  await mkdir(path.dirname(target), { recursive: true });
+  const content = String(humanOutput.fallbackTransportText?.content || '');
+  await writeFile(target, content, 'utf8');
+  return Object.freeze({ schema: 'tiinex.portable.handoff-transport-text-write.v1', status: 'written', path: target, bytes: Buffer.byteLength(content, 'utf8'), authority: 'none', normalEmission: false });
+}
+function defaultSidecarPath(packageTarget) {
+  const suffix = '.handoff-package.zip';
+  return packageTarget.toLowerCase().endsWith(suffix) ? `${packageTarget.slice(0, -suffix.length)}.transport.txt` : `${packageTarget}.transport.txt`;
+}
+async function readOptionalJson(file = '') { if (!file) return {}; return JSON.parse(await readFile(file, 'utf8')); }
+function descriptorArray(value, key) { if (Array.isArray(value)) return value; if (Array.isArray(value?.[key])) return value[key]; return []; }
+function splitFlag(value) { if (!value || value === true) return []; return String(value).split(',').map((item) => item.trim()).filter(Boolean); }
+
+
+function selectCarrierProfile({ operator = null, inherited = null, runtime = null } = {}) {
+  for (const [value, source] of [[operator, 'operator'], [inherited, 'inherited-package'], [runtime, 'runtime-profile']]) {
+    const profile = normalizeHandoffCarrierProfile(value, { source });
+    if (profile.state === 'qualified') return profile;
+  }
+  return normalizeHandoffCarrierProfile(null);
+}
+
+async function readGroundContinuationState(workspaceRoot = '.') {
+  try { return JSON.parse(await readFile(path.join(path.resolve(String(workspaceRoot || '.')), '.tiinex', 'continuation.json'), 'utf8')); }
+  catch { return {}; }
+}

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

@@ -0,0 +1,31 @@
+import { mkdir, open } from 'node:fs/promises';
+import path from 'node:path';
+
+const MAX_SIBLING_INDEX = 9999;
+
+export async function reserveHandoffSiblingIndex({ parentPackagePath = '', parentPackageSha256 = '', parentDimension = '', enabled = true } = {}) {
+  if (!enabled) return Object.freeze({ state: 'not-reserved', siblingIndex: 1, allocationPath: '' });
+  const parentPath = path.resolve(String(parentPackagePath || ''));
+  const digest = String(parentPackageSha256 || '').trim().toLowerCase();
+  const dimension = String(parentDimension || '').trim();
+  if (!parentPath || !/^[0-9a-f]{64}$/.test(digest) || !/^\d{3}(?:-\d+)*$/.test(dimension)) throw new Error('portable.cli.handoff-carrier.sibling-allocation.parent-unqualified');
+  const allocationDir = path.join(path.dirname(parentPath), '.tiinex-handoff-sibling-allocations');
+  await mkdir(allocationDir, { recursive: true });
+  const key = `${digest.slice(0, 24)}-${dimension.replace(/[^0-9-]/g, '')}`;
+  for (let siblingIndex = 1; siblingIndex <= MAX_SIBLING_INDEX; siblingIndex += 1) {
+    const allocationPath = path.join(allocationDir, `${key}-${siblingIndex}.allocation`);
+    try {
+      const handle = await open(allocationPath, 'wx');
+      try {
+        await handle.writeFile(`${JSON.stringify({ parentPackageSha256: digest, parentDimension: dimension, siblingIndex, childDimension: `${dimension}-${siblingIndex}` })}\n`, 'utf8');
+      } finally {
+        await handle.close();
+      }
+      return Object.freeze({ state: 'reserved', siblingIndex, allocationPath });
+    } catch (error) {
+      if (error?.code === 'EEXIST') continue;
+      throw error;
+    }
+  }
+  throw new Error('portable.cli.handoff-carrier.sibling-allocation.exhausted');
+}