@tiinex/core 0.1.1

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

@@ -0,0 +1,80 @@
+export function portableCliHelpText(commandPrefix = '', surfaceCommand = '') {
+  const command = String(commandPrefix || '').trim()
+    || (String(process.argv[1] || '').replace(/\\/g, '/').includes('/bin/') ? 'node bin/tiinex-portable.mjs' : 'node tools/tiinex-portable.mjs');
+  const common = String(surfaceCommand || '').trim().toLowerCase();
+  const specific = commonCommandHelp(command, common);
+  if (specific) return specific.join('\n');
+  return [
+    'Tiinex portable tooling',
+    '',
+    'Common path (same command for humans and LLMs):',
+    `${command} ground <handoff-package.zip> --route <Continue-from> [--holder-role <recipient-role>]`,
+    `${command} ground <handoff-package.zip> --route <Continue-from> --holder-role <recipient-role> --continue <workspace-dir>`,
+    `${command} author <workspace-dir> --schema <schema-id> --path <workspace-relative-artifact> --body <body.md> [--parent <workspace-relative-parent>] [--title <title>] [--summary <summary>] [--why <why>]`,
+    `${command} handoff <workspace-dir>`,
+    '',
+    `Handoff aliases: ${command} orient <carrier.zip>; ${command} validate <carrier.zip>`,
+    `Advanced/internal catalog: ${command} operations`,
+    '',
+    'Common boundaries:',
+    '- `orient`, `ground`, and public `handoff` use compact decision-first default projections; add `--full` on the same command for the complete qualified receipt.',
+    '- `ground` is read-only; append `--continue <workspace-dir>` only after `grounded-to-act` to materialize the selected carried Workspace and runtime-only `.tiinex/continuation.json`.',
+    '- `author` uses continuation state to infer ordinary Parent continuity, seal c14n-v2 integrity, audit, and stage; invalid artifacts are not retained.',
+    '- `handoff` uses continuation state plus the latest qualified authored Handoff to manufacture the canonical return carrier and excludes runtime-only `.tiinex` state. Normal operator completion is one Handoff package plus the exact routing text; markdown-capable hosts render that routing in a fenced code block, and do not emit loose Evidence/Handoff markdown as extra transport payloads.',
+    '- Remote reads/writes remain explicit host concerns. Tooling operation safety does not create or revoke semantic Task/Handoff authority.',
+    '',
+    'Use `<common-command> --help` for focused common-path usage. Use `operations` deliberately for the advanced/internal operation catalog.'
+  ].join('\n');
+}
+
+function commonCommandHelp(command, surfaceCommand) {
+  if (surfaceCommand === 'ground') return [
+    'Tiinex portable tooling — ground',
+    '',
+    `${command} ground <handoff-package.zip> --route <Continue-from> [--holder-role <recipient-role>]`,
+    `${command} ground <handoff-package.zip> --route <Continue-from> --holder-role <recipient-role> --continue <workspace-dir>`,
+    '',
+    'Reads and qualifies the exact selected Handoff route. The default projection keeps readiness, recipient authority boundary, explicit consuming-session holder binding, Required Context closure, continuity/blockers, current Task identity, and exact next action compact; add `--full` for the full qualified receipt.',
+    'Add `--include-required-context <requirement-id,name|all>` and/or `--include-current-work` only when exact body text is needed. `ground --continue` includes the bounded current Task body needed to proceed, retains Required Context counts and continuity/recovery state, and does not repeat qualified Required Context item paths or root-detail receipts unless explicitly requested (or `--full` is used).',
+    'For a Role recipient, `--holder-role <recipient-role>` is an explicit consuming-session Role-capacity binding; it is never inferred from route selection, provider identity, or assistant/user position. Without it, the holder remains unresolved and grounding stays discussion-only. After `grounded-to-act`, `--continue` materializes the selected carried Workspace into an empty local directory and writes runtime-only `.tiinex/continuation.json`. The grounding operation itself is non-mutating; downstream work authority comes from qualified Handoff/Task/Role artifacts, not from that operation-safety fact.',
+    '',
+    `Advanced/internal catalog: ${command} operations`
+  ];
+  if (surfaceCommand === 'author') return [
+    'Tiinex portable tooling — author',
+    '',
+    `${command} author <workspace-dir> --schema <schema-id> --path <workspace-relative-artifact> --body <body.md> [--parent <workspace-relative-parent>] [--title <title>] [--summary <summary>] [--why <why>]`,
+    '',
+    'Uses qualified continuation state to infer the ordinary Parent when `--parent` is omitted, seals c14n-v2 self-integrity, audits, stages, and updates continuation state only after qualification. Invalid output is not retained.',
+    '',
+    `Advanced/internal catalog: ${command} operations`
+  ];
+  if (surfaceCommand === 'handoff') return [
+    'Tiinex portable tooling — handoff',
+    '',
+    `${command} handoff <workspace-dir>`,
+    '',
+    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent, unchanged sibling Workspace providers, canonical projected filename, and return output directory. 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`
+  ];
+  if (surfaceCommand === 'orient') return [
+    'Tiinex portable tooling — orient',
+    '',
+    `${command} orient <handoff-package.zip>`,
+    '',
+    'Read-only recipient orientation for a supplied Handoff carrier. The default projection identifies qualified Workspaces/routes, selection, non-authority, and the exact grounding route; add `--full` for endpoint, closure, and package-detail receipts.',
+    '',
+    `Advanced/internal catalog: ${command} operations`
+  ];
+  if (surfaceCommand === 'validate') return [
+    'Tiinex portable tooling — validate',
+    '',
+    `${command} validate <handoff-package.zip>`,
+    '',
+    'Audits carried Handoff-package context and qualification evidence without mutating source material.',
+    '',
+    `Advanced/internal catalog: ${command} operations`
+  ];
+  return null;
+}

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

@@ -0,0 +1,13 @@
+export async function land(flags, material, readOptionalJson, splitFlag) {
+  const repositoriesValue = await readOptionalJson(flags.repositories || flags.repos);
+  const selectionsValue = await readOptionalJson(flags.selections);
+  return {
+    input: {
+      ...material,
+      repositories: repositoriesValue.repositories || (Array.isArray(repositoriesValue) ? repositoriesValue : []),
+      selections: selectionsValue.selections || selectionsValue || repositoriesValue.selections || {},
+      workspaceIds: splitFlag(flags.workspaces || flags['workspace-ids'])
+    },
+    options: {}
+  };
+}

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

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { writePortableLocalDraftFile } from '../../output/node.draft.js';
+import { writePortableArtifactResultPackage } from '../../output/artifact.result.package.js';
+import { writePortableArtifactSet, writePortableArtifactSetBundle } from '../../output/node.artifact-set.js';
+
+export async function materializeCliLocalDraftResult(result = {}, input = {}, flags = {}) {
+  if (!flags.output) throw new Error('portable.cli.artifact-output.required');
+  const writeReceipt = await writePortableLocalDraftFile(result, flags.output, { overwrite: flags.overwrite === true });
+  const qualifiedPath = flags['qualified-package'] || flags['result-package'] || '';
+  const primaryOutput = Object.freeze({ role: 'artifact', mediaType: 'text/markdown', path: writeReceipt.outputPath, sha256: writeReceipt.sha256, bytes: writeReceipt.bytes, status: writeReceipt.status });
+  if (!qualifiedPath) return Object.freeze({ ...result, writeReceipt, delivery: Object.freeze({ profile: 'artifact-first', primary: primaryOutput, secondary: null }) });
+
+  const transferVerificationDocument = await readRequiredJsonDocument(flags['transfer-verification'], 'portable.cli.transfer-verification.required');
+  const bootstrapVerificationDocument = await readRequiredJsonDocument(flags['bootstrap-verification'], 'portable.cli.bootstrap-verification.required');
+  const resultPackageReceipt = await writePortableArtifactResultPackage(result, qualifiedPath, {
+    writeReceipt,
+    creationInput: input,
+    transferManifest: await readRequiredJson(flags['transfer-manifest'], 'portable.cli.transfer-manifest.required'),
+    bootstrapManifest: await readRequiredJson(flags['bootstrap-manifest'], 'portable.cli.bootstrap-manifest.required'),
+    transferVerification: transferVerificationDocument.value,
+    transferVerificationBytes: transferVerificationDocument.bytes,
+    bootstrapVerification: bootstrapVerificationDocument.value,
+    bootstrapVerificationBytes: bootstrapVerificationDocument.bytes,
+    taskRequest: await readRequiredText(flags['task-request'], 'portable.cli.task-request.required'),
+    createdAt: flags['created-at'] || '',
+    overwrite: flags.overwrite === true
+  });
+  return Object.freeze({ ...result, writeReceipt, resultPackageReceipt, delivery: Object.freeze({ profile: 'artifact-first-with-qualified-evidence', primary: primaryOutput, secondary: Object.freeze({ role: 'qualified-evidence', mediaType: 'application/zip', path: resultPackageReceipt.outputPath, sha256: resultPackageReceipt.sha256, bytes: resultPackageReceipt.bytes, status: resultPackageReceipt.status }) }) });
+}
+
+async function readRequiredJson(file = '', code = 'portable.cli.json-file.required') {
+  if (!String(file || '').trim()) throw new Error(code);
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+async function readRequiredJsonDocument(file = '', code = 'portable.cli.json-file.required') {
+  if (!String(file || '').trim()) throw new Error(code);
+  const bytes = await readFile(file);
+  return Object.freeze({ value: JSON.parse(bytes.toString('utf8')), bytes });
+}
+
+async function readRequiredText(file = '', code = 'portable.cli.text-file.required') {
+  if (!String(file || '').trim()) throw new Error(code);
+  return readFile(file, 'utf8');
+}
+
+export async function materializeCliArtifactSetResult(result = {}, flags = {}, options = {}) {
+  if (options.bundlePrimary === true) {
+    if (!flags.bundle) throw new Error('portable.cli.live-export.bundle.required');
+    const bundleReceipt = await writePortableArtifactSetBundle(result, flags.bundle, { overwrite: flags.overwrite === true });
+    return Object.freeze({
+      ...result,
+      bundleReceipt,
+      delivery: Object.freeze({
+        profile: 'bundle-only',
+        primary: Object.freeze({ role: 'artifact-bundle', mediaType: 'application/zip', path: bundleReceipt.outputPath, sha256: bundleReceipt.sha256, bytes: bundleReceipt.bytes, status: bundleReceipt.status }),
+        secondary: null
+      })
+    });
+  }
+  if (!flags['output-dir']) throw new Error('portable.cli.artifact-set.output-dir.required');
+  const writeReceipt = await writePortableArtifactSet(result, flags['output-dir'], { bundlePath: flags.bundle || '', overwrite: flags.overwrite === true });
+  return Object.freeze({
+    ...result,
+    writeReceipt,
+    delivery: Object.freeze({
+      profile: 'artifact-first-set',
+      primary: Object.freeze(writeReceipt.artifacts.map((entry) => Object.freeze({ role: 'artifact', mediaType: 'text/markdown', path: entry.outputPath, sha256: entry.sha256, bytes: entry.bytes, status: 'written-local-clean' }))),
+      secondary: writeReceipt.bundleReceipt ? Object.freeze({ role: 'artifact-bundle', mediaType: 'application/zip', path: writeReceipt.bundleReceipt.outputPath, sha256: writeReceipt.bundleReceipt.sha256, bytes: writeReceipt.bundleReceipt.bytes, status: writeReceipt.bundleReceipt.status }) : null
+    })
+  });
+}

package/src/tooling/portable/adapters/cli/cli.material-policy.js

@@ -0,0 +1,6 @@
+export const OPERATIONS_WITHOUT_EXPLICIT_MATERIAL = new Set([
+  'prepare-task','prepare-materialization','create-local-artifact-set','create-local-draft','plan-host-action','accept-host-receipt',
+  'describe-checkpoint-gate','qualify-checkpoint','describe-schema-chain','schema-guide','plan-artifact','list-material-providers',
+  'resolve-schema-material','resolve-schema-chain-material','materialize-durable-findings','build-runtime-package','roundtrip-runtime-package',
+  'describe-cold-start-ingress','project-cold-start-host','qualify-cold-start','ground-cold-consumer'
+]);

package/src/tooling/portable/adapters/cli/cli.operator-bridge.js

@@ -0,0 +1,18 @@
+export async function prepareOperatorBridgeCliInput(command = '', material = {}, flags = {}, readOptionalJson = async () => ({})) {
+  if (command === 'project-workspace-package-sources') {
+    const repositories = await readOptionalJson(flags.repositories);
+    return { input: { ...material, repositories: repositories.repositories || repositories }, options: {} };
+  }
+  if (command === 'project-handoff-authoring-plan') return { input: { ...material, parentPath: flags.parent || flags['parent-path'] || '', title: flags.title || '' }, options: {} };
+  if (command === 'project-handoff-endpoints') return { input: { ...material, workspaceId: flags['workspace-id'] || flags.workspace || 'workspace' }, options: {} };
+  if (command === 'project-operator-context') {
+    const repositories = await readOptionalJson(flags.repositories);
+    const workspaceRoots = await readOptionalJson(flags['workspace-roots'] || flags.roots);
+    return { input: { ...material, repositories: repositories.repositories || repositories, workspaceRoots: workspaceRoots.workspaces || workspaceRoots.roots || workspaceRoots }, options: {} };
+  }
+  if (command === 'project-staged-validation') {
+    const staged = await readOptionalJson(flags.staged || flags.paths);
+    return { input: { ...material, stagedPaths: staged.stagedPaths || staged.paths || (Array.isArray(staged) ? staged : []) }, options: {} };
+  }
+  return null;
+}

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

@@ -0,0 +1,14 @@
+export async function reductionPreflightCliInput({ material, flags, options, readOptionalJson, splitFlag }) {
+  const value = await readOptionalJson(flags['reduction-inputs'] || flags.inputs || flags['eligibility-inputs']);
+  const candidateSet = value.candidateSet || value.candidates || splitFlag(flags.candidate || flags.candidates);
+  return {
+    input: {
+      ...material,
+      ...value,
+      candidateSet,
+      reductionArtifactPath: flags.reduction || flags['reduction-artifact'] || value.reductionArtifactPath || value.reduction || '',
+      immutableSources: value.immutableSources || await readOptionalJson(flags['immutable-sources'])
+    },
+    options
+  };
+}

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

@@ -0,0 +1,434 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { listPortableOperations, runPortableOperation } from '../../operation.catalog.js';
+import { writePortableRuntimePackageZip } from '../../output/node.zip.js';
+import { materializeCliArtifactSetResult, materializeCliLocalDraftResult } from './cli.local-output.js';
+import { portableCliHelpText } from './cli.help.js';
+import { materializeHandoffManufactureCliOutput } from './cli.handoff-manufacture.js';
+import { commandInput } from './cli.command-input.js';
+import { continueGroundWithHostResult } from './cli.ground-recovery.js';
+import { groundContinuationOperationInput, materializeGroundWorkspaceCliOutput } from './cli.ground-materialize.js';
+import { runCommonAuthorCli } from './cli.common-author.js';
+import { projectCommonCliDefaultOutput } from './cli.common-output.js';
+
+export async function runPortableCli(argv = process.argv.slice(2), io = console, runtime = {}) {
+  const parsed = parseArgs(argv);
+  if (!parsed.command || parsed.command === 'help' || parsed.flags.help) {
+    io.log(portableCliHelpText(runtime.commandPrefix, parsed.flags.help ? parsed.surfaceCommand : ''));
+    return 0;
+  }
+  if (parsed.command === 'operations') {
+    writeJson(io, listPortableOperations(), parsed.flags.compact !== true);
+    return 0;
+  }
+  try {
+    if (parsed.command === 'author') {
+      const result = await runCommonAuthorCli(parsed, runtime);
+      writeJson(io, result, parsed.flags.compact !== true);
+      return result?.findingSummary?.counts?.error ? 2 : 0;
+    }
+    const timingEnabled = Boolean(parsed.flags['phase-timing']);
+    const totalStartedAt = timingEnabled ? monotonicNowMs() : 0;
+
+    const inputStartedAt = timingEnabled ? monotonicNowMs() : 0;
+    const { input, options } = await commandInput(parsed, runtime);
+    const operationInput = parsed.command === 'project-grounding-readiness'
+      ? groundContinuationOperationInput(input, parsed.flags)
+      : input;
+    const inputPreparationMs = timingEnabled ? elapsedMs(inputStartedAt) : 0;
+
+    const operationStartedAt = timingEnabled ? monotonicNowMs() : 0;
+    let result = await runPortableOperation(parsed.command, operationInput, options);
+    let commonPathOutput = null;
+    if (parsed.command === 'project-grounding-readiness' && parsed.flags['host-result']) {
+      const continued = await continueGroundWithHostResult(result, operationInput, options, parsed.flags);
+      result = continued.result;
+      commonPathOutput = continued.output;
+    }
+    const operationExecutionMs = timingEnabled ? elapsedMs(operationStartedAt) : 0;
+
+    const materializationStartedAt = timingEnabled ? monotonicNowMs() : 0;
+    let output = commonPathOutput || result;
+    if (parsed.command === 'manufacture-handoff-package') {
+      output = await materializeHandoffManufactureCliOutput(result, parsed.flags);
+    } else if (parsed.command === 'project-grounding-readiness' && (parsed.flags.continue || parsed.flags['materialize-workspace'] || parsed.flags['workspace-output'])) {
+      output = await materializeGroundWorkspaceCliOutput(output, operationInput, parsed.flags);
+    } else if (parsed.command === 'build-runtime-package' && parsed.flags.output) {
+      const receipt = await writePortableRuntimePackageZip(result.bundle, parsed.flags.output);
+      output = Object.freeze({ ...result, bundle: undefined, writeReceipt: receipt });
+    } else if (parsed.command === 'create-local-draft' && (parsed.flags.output || parsed.flags['qualified-package'] || parsed.flags['result-package'])) {
+      output = await materializeCliLocalDraftResult(result, input, parsed.flags);
+    } else if ((parsed.command === 'create-local-artifact-set' || parsed.command === 'export-live-lineage') && (parsed.flags['output-dir'] || parsed.flags.bundle)) {
+      output = await materializeCliArtifactSetResult(result, parsed.flags, { bundlePrimary: parsed.command === 'export-live-lineage' });
+    } else if (parsed.command === 'process-live-turn' && parsed.flags.output && result.status !== 'blocked') {
+      const outputPath = path.resolve(String(parsed.flags.output));
+      const stateBytes = `${JSON.stringify(result.state, null, 2)}\n`;
+      await mkdir(path.dirname(outputPath), { recursive: true });
+      await writeFile(outputPath, stateBytes, 'utf8');
+      output = Object.freeze({ ...result, liveStateOutput: Object.freeze({ path: outputPath, bytes: Buffer.byteLength(stateBytes), artifacts: result.state?.artifacts?.length || 0 }) });
+    }
+    const outputMaterializationMs = timingEnabled ? elapsedMs(materializationStartedAt) : 0;
+    if (timingEnabled) output = withCliPhaseTiming(output, {
+      command: parsed.command,
+      inputPreparationMs,
+      operationExecutionMs,
+      outputMaterializationMs,
+      measuredElapsedBeforeFinalSerializationMs: elapsedMs(totalStartedAt)
+    });
+    if (parsed.flags.summary) output = withCliSummaryProjection(output, parsed.command, parsed.flags);
+    output = projectCommonCliDefaultOutput(output, parsed);
+    writeJson(io, output, parsed.flags.compact !== true);
+    return result?.findingSummary?.counts?.error ? 2 : 0;
+  } catch (error) {
+    io.error(JSON.stringify({
+      schema: 'tiinex.portable.cli.error.v1',
+      error: String(error?.message || error),
+      command: parsed.command
+    }, null, 2));
+    return 1;
+  }
+}
+
+export function withCliSummaryProjection(result = {}, command = '', flags = {}) {
+  const operation = String(command || result.operation || '');
+  if (!['inspect', 'audit', 'search-lineage', 'resolve-lineage', 'qualify-cold-start'].includes(operation)) return result;
+  if (operation === 'qualify-cold-start') return cliColdStartQualificationSummary(result, flags);
+  const findings = Array.isArray(result.findings) ? result.findings : [];
+  const actionableFindings = findings.filter((finding) => finding?.severity === 'error' || finding?.severity === 'warning');
+  const counts = cliSummaryCounts(result, operation, findings);
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || operation,
+    projection: 'bounded-summary',
+    status: result.status || (result.findingSummary?.counts?.error ? 'blocked' : 'ready'),
+    boundary: result.boundary,
+    counts,
+    ...(operation === 'search-lineage' ? {
+      query: result.query,
+      scope: result.scope,
+      page: result.page,
+      facets: result.facets
+    } : {}),
+    ...(operation === 'resolve-lineage' ? {
+      traversal: cliLineageTraversalSummary(result.traversal),
+      lineage: cliLineageGraphSummary(result.lineage)
+    } : {}),
+    findingSummary: result.findingSummary,
+    actionableFindings: Object.freeze(actionableFindings.slice(0, 20)),
+    actionableFindingsOmitted: Math.max(0, actionableFindings.length - 20),
+    ...(result.cliPhaseTiming ? { cliPhaseTiming: result.cliPhaseTiming } : {})
+  });
+}
+
+
+function cliColdStartQualificationSummary(result = {}, flags = {}) {
+  const findings = Array.isArray(result.findings) ? result.findings : [];
+  const actionableFindings = findings.filter((finding) => finding?.severity === 'error' || finding?.severity === 'warning');
+  const requiredContext = Array.isArray(result.continuation?.requiredContext) ? result.continuation.requiredContext : [];
+  const requestedRequiredContextSelectors = coldStartRequiredContextSelectors(flags['include-required-context']);
+  const selectedRequiredContext = requiredContext.filter((item) => coldStartRequiredContextSelected(item, requestedRequiredContextSelectors));
+  const selectedSet = new Set(selectedRequiredContext);
+  const orderedRequiredContext = [...selectedRequiredContext, ...requiredContext.filter((item) => !selectedSet.has(item))];
+  const requiredContextSummary = orderedRequiredContext.slice(0, 20).map((item) => {
+    const contentProjected = selectedSet.has(item) && typeof item?.content === 'string';
+    return Object.freeze({
+      requirementId: item.requirementId,
+      name: item.name,
+      state: item.state,
+      referenceTarget: item.referenceTarget,
+      kind: item.kind,
+      workspaceId: item.workspaceId,
+      archivePackagePath: item.archivePackagePath,
+      innerPath: item.innerPath,
+      packagePath: item.packagePath,
+      providerMode: item.providerMode,
+      bytes: item.bytes,
+      sha256: item.sha256,
+      actualBytes: item.actualBytes,
+      actualSha256: item.actualSha256,
+      contentState: item.contentState,
+      contentProjected,
+      ...(contentProjected ? { content: item.content } : {})
+    });
+  });
+  const projectedRequiredContextBodies = requiredContextSummary.filter((item) => item.contentProjected).length;
+  const availableRequiredContextBodies = requiredContext.filter((item) => typeof item?.content === 'string' && item.content.length > 0).length;
+  const unmatchedRequiredContextSelectors = requestedRequiredContextSelectors.filter((selector) => selector !== 'all' && !requiredContext.some((item) => coldStartRequiredContextMatches(item, selector)));
+  const qualification = result.qualification || {};
+  const grounding = result.grounding || {};
+  const continuation = result.continuation || {};
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || 'qualify-cold-start',
+    resultSchema: result.resultSchema,
+    projection: 'bounded-summary',
+    status: result.status,
+    ingressKind: result.ingressKind,
+    qualification: Object.freeze({
+      state: qualification.state,
+      preferredPathPassed: qualification.preferredPathPassed,
+      recoveryState: qualification.recoveryState,
+      recoveryIsPreferredPathEvidence: qualification.recoveryIsPreferredPathEvidence,
+      toolingAvailability: qualification.toolingAvailability,
+      firstSemanticOperation: qualification.firstSemanticOperation,
+      expectedFirstSemanticOperation: qualification.expectedFirstSemanticOperation,
+      orientationOperation: qualification.orientationOperation,
+      groundingState: qualification.groundingState,
+      hostEvidence: qualification.hostEvidence,
+      fallback: qualification.fallback
+    }),
+    metrics: result.metrics,
+    grounding: Object.freeze({
+      status: grounding.status,
+      ingressKind: grounding.ingressKind,
+      selectedRoute: cliColdStartRouteSummary(grounding.selectedRoute),
+      handoff: cliColdStartHandoffSummary(grounding.handoff),
+      role: cliColdStartRoleSummary(grounding.role),
+      participation: cliColdStartParticipationSummary(grounding.participation),
+      interaction: cliColdStartInteractionSummary(grounding.interaction),
+      capabilities: cliColdStartCapabilitiesSummary(grounding.capabilities),
+      degradedCapture: grounding.degradedCapture,
+      mutationBoundary: grounding.mutationBoundary,
+      next: grounding.next,
+      findingSummary: grounding.findingSummary
+    }),
+    continuation: Object.freeze({
+      state: continuation.state,
+      substantiveWorkMayBegin: continuation.substantiveWorkMayBegin,
+      qualificationState: continuation.qualificationState,
+      selectedRoute: continuation.selectedRoute,
+      transfer: Object.freeze([...(continuation.transfer || [])].slice(0, 20)),
+      transferOmitted: Math.max(0, (continuation.transfer || []).length - 20),
+      requiredContext: Object.freeze(requiredContextSummary),
+      requiredContextOmitted: Math.max(0, requiredContext.length - requiredContextSummary.length),
+      requiredContextContentBodiesProjected: projectedRequiredContextBodies,
+      requiredContextContentBodiesOmitted: Math.max(0, availableRequiredContextBodies - projectedRequiredContextBodies),
+      requestedRequiredContextSelectors: Object.freeze(requestedRequiredContextSelectors),
+      unmatchedRequiredContextSelectors: Object.freeze(unmatchedRequiredContextSelectors),
+      completionExpectation: continuation.completionExpectation,
+      returnPackage: continuation.returnPackage,
+      next: continuation.next,
+      boundary: continuation.boundary
+    }),
+    oneShot: result.oneShot,
+    findingSummary: result.findingSummary,
+    actionableFindings: Object.freeze(actionableFindings.slice(0, 20)),
+    actionableFindingsOmitted: Math.max(0, actionableFindings.length - 20),
+    projectionBoundary: Object.freeze({
+      requiredContextBodiesProjected: projectedRequiredContextBodies > 0,
+      fullProjectionAvailable: true,
+      interpretation: 'This receipt preserves cold-start qualification state, route/task transfer, required-context identity metadata, completion expectation, and actionable findings while omitting body-scale grounding/context material. Request the full qualification projection or explicitly read the qualified required-context material before relying on omitted body text for substantive reasoning.'
+    }),
+    ...(result.cliPhaseTiming ? { cliPhaseTiming: result.cliPhaseTiming } : {})
+  });
+}
+
+
+function coldStartRequiredContextSelectors(value) {
+  if (!value) return Object.freeze([]);
+  if (value === true) return Object.freeze(['all']);
+  return Object.freeze(String(value).split(',').map((item) => item.trim()).filter(Boolean).map((item) => item.toLowerCase()));
+}
+
+function coldStartRequiredContextSelected(item = {}, selectors = []) {
+  if (!selectors.length) return false;
+  if (selectors.includes('all')) return true;
+  return selectors.some((selector) => coldStartRequiredContextMatches(item, selector));
+}
+
+function coldStartRequiredContextMatches(item = {}, selector = '') {
+  const normalized = String(selector || '').trim().toLowerCase();
+  if (!normalized) return false;
+  return [item.requirementId, item.name, item.referenceTarget].some((value) => String(value || '').trim().toLowerCase() === normalized);
+}
+
+function cliColdStartRouteSummary(route = {}) {
+  if (!route || typeof route !== 'object') return route;
+  const required = route.requiredClosure || {};
+  return Object.freeze({
+    id: route.id,
+    state: route.state,
+    workspaceId: route.workspaceId,
+    workspaceRelativeHandoffPath: route.workspaceRelativeHandoffPath,
+    packagePath: route.packagePath,
+    from: route.from,
+    to: route.to,
+    pointerPath: route.pointerPath,
+    requiredClosure: Object.freeze({
+      state: required.state,
+      requiredCount: required.requiredCount,
+      qualifiedCount: required.qualifiedCount,
+      requirementsProjected: false
+    })
+  });
+}
+
+function cliColdStartHandoffSummary(handoff = {}) {
+  if (!handoff || typeof handoff !== 'object') return handoff;
+  return Object.freeze({
+    schemaId: handoff.schemaId,
+    purpose: handoff.purpose,
+    from: handoff.from,
+    fromKind: handoff.fromKind,
+    to: handoff.to,
+    toKind: handoff.toKind,
+    transferCount: (handoff.transfers || []).length,
+    transfersProjected: false,
+    completionExpectation: handoff.completionExpectation,
+    routeId: handoff.routeId,
+    workspaceId: handoff.workspaceId,
+    workspaceRelativePath: handoff.workspaceRelativePath,
+    packagePath: handoff.packagePath
+  });
+}
+
+function cliColdStartRoleSummary(role = {}) {
+  if (!role || typeof role !== 'object') return role;
+  return Object.freeze({
+    state: role.state,
+    endpoint: role.endpoint,
+    material: role.material,
+    transition: role.transition,
+    predecessor: role.predecessor,
+    compatibility: role.compatibility,
+    exactBoundaryProjected: false,
+    authorityBoundaryProjected: false,
+    interpretationLimitsProjected: false
+  });
+}
+
+function cliColdStartParticipationSummary(participation = {}) {
+  if (!participation || typeof participation !== 'object') return participation;
+  return Object.freeze({
+    participantState: participation.participantState,
+    currentContribution: participation.currentContribution,
+    handoffCapacities: participation.handoffCapacities,
+    transportIdentityAssumption: participation.transportIdentityAssumption,
+    cardinality: participation.cardinality
+  });
+}
+
+function cliColdStartInteractionSummary(interaction = {}) {
+  if (!interaction || typeof interaction !== 'object') return interaction;
+  return Object.freeze({
+    handoffPurpose: interaction.handoffPurpose,
+    currentPurpose: interaction.currentPurpose,
+    purposeState: interaction.purposeState,
+    mode: interaction.mode,
+    modeState: interaction.modeState,
+    executionExpected: interaction.executionExpected,
+    nonExecutionMode: interaction.nonExecutionMode,
+    continuingDialoguePermitted: interaction.continuingDialoguePermitted,
+    oneShotAssumed: interaction.oneShotAssumed
+  });
+}
+
+function cliColdStartCapabilitiesSummary(capabilities = {}) {
+  if (!capabilities || typeof capabilities !== 'object') return capabilities;
+  const discovery = capabilities.discovery || {};
+  const profile = discovery.profile || {};
+  const instance = profile.capabilityInstance || capabilities.instance || {};
+  const advertised = profile.capabilities || {};
+  return Object.freeze({
+    discovery: Object.freeze({
+      schema: discovery.schema,
+      status: discovery.status,
+      tools: Array.isArray(profile.tools) ? profile.tools.length : 0,
+      provider: instance.provider,
+      host: instance.host,
+      session: instance.session,
+      materialAccess: advertised.materialAccess,
+      execution: advertised.execution,
+      mutation: advertised.mutation,
+      interaction: advertised.interaction
+    }),
+    providerNameGrantsCapability: capabilities.providerNameGrantsCapability,
+    advertisementIsExerciseEvidence: capabilities.advertisementIsExerciseEvidence
+  });
+}
+
+function cliSummaryCounts(result = {}, operation = '', findings = []) {
+  if (operation === 'inspect') return Object.freeze({
+    files: Array.isArray(result.files) ? result.files.length : 0,
+    records: Array.isArray(result.records) ? result.records.length : 0,
+    assets: Array.isArray(result.assets) ? result.assets.length : 0,
+    workspaceEntries: Array.isArray(result.workspaceEntries) ? result.workspaceEntries.length : 0,
+    findings: findings.length
+  });
+  if (operation === 'audit') return Object.freeze({
+    audits: Array.isArray(result.audits) ? result.audits.length : 0,
+    findings: findings.length
+  });
+  if (operation === 'search-lineage') return Object.freeze({
+    returnedMatches: Array.isArray(result.matches) ? result.matches.length : Number(result.page?.returned || 0),
+    totalMatches: Number(result.page?.total || 0),
+    eligibleRecords: Number(result.scope?.eligibleRecords || 0),
+    findings: findings.length
+  });
+  return Object.freeze({
+    loadedNodes: Number(result.traversal?.stats?.loadedNodes || result.lineage?.stats?.loadedNodes || result.lineage?.stats?.nodes || 0),
+    visitedNodes: Number(result.traversal?.stats?.visitedNodes || result.lineage?.stats?.visitedNodes || 0),
+    traversedEdges: Number(result.traversal?.stats?.traversedEdges || result.lineage?.stats?.traversedEdges || 0),
+    missingEdges: Number(result.traversal?.stats?.missingEdges || result.lineage?.stats?.missingEdges || 0),
+    findings: findings.length
+  });
+}
+
+function cliLineageTraversalSummary(traversal = {}) {
+  return Object.freeze({
+    boundary: traversal.boundary,
+    direction: traversal.direction,
+    maxDepth: traversal.maxDepth,
+    startIds: Object.freeze([...(traversal.startIds || [])]),
+    stats: traversal.stats
+  });
+}
+
+function cliLineageGraphSummary(lineage = {}) {
+  return Object.freeze({
+    stats: lineage.stats,
+    options: lineage.options
+  });
+}
+
+function monotonicNowMs() {
+  return Number(process.hrtime.bigint()) / 1_000_000;
+}
+
+function elapsedMs(startedAt = 0) {
+  return Math.max(0, Math.round((monotonicNowMs() - Number(startedAt || 0)) * 1000) / 1000);
+}
+
+function withCliPhaseTiming(result = {}, timing = {}) {
+  return Object.freeze({
+    ...result,
+    cliPhaseTiming: Object.freeze({
+      schema: 'tiinex.portable.cli.phase-timing.v1',
+      command: String(timing.command || ''),
+      measuredElapsedBeforeFinalSerializationMs: Number(timing.measuredElapsedBeforeFinalSerializationMs || 0),
+      phases: Object.freeze({
+        inputPreparationMs: Number(timing.inputPreparationMs || 0),
+        operationExecutionMs: Number(timing.operationExecutionMs || 0),
+        outputMaterializationMs: Number(timing.outputMaterializationMs || 0)
+      }),
+      measurementBoundary: 'immediately-before-final-json-serialization',
+      unmeasured: Object.freeze({
+        finalJsonSerialization: true,
+        finalEmission: true
+      }),
+      boundary: 'Monotonic in-process CLI phase timing through result/output materialization only. The receipt is frozen immediately before final JSON serialization, so final JSON serialization and emission are explicitly unmeasured. It also excludes host review/queue latency, client streaming latency, model compute outside this process, and any work performed before this CLI process starts or after it exits.'
+    })
+  });
+}
+
+
+function parseArgs(argv=[]) {
+  const args=[...argv],first=args.shift()||'';
+  if(first==='--help'||first==='-h') return {command:'help',flags:{help:true},positionals:[]};
+  const command=({orient:'orient-handoff-package',ground:'project-grounding-readiness',receive:'qualify-cold-start',validate:'audit-handoff-package-context',handoff:'manufacture-handoff-package',author:'author'})[first]||first;
+  const flags={},positionals=[];
+  while(args.length){const token=args.shift();if(!token.startsWith('--')){positionals.push(token);continue;}const key=token.slice(2);flags[key]=!args.length||args[0].startsWith('--')?true:args.shift();}
+  return {command,flags,positionals,surfaceCommand:first};
+}
+
+function writeJson(io, value, pretty = true) { io.log(JSON.stringify(value, null, pretty ? 2 : 0)); }