@tiinex/core 0.1.1

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

@@ -0,0 +1,249 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArtifactMarkdown } from '../../../../artifacts/artifact.parse.js';
+import { buildArtifactCreationContract } from '../../../../schemas/creation.contracts.js';
+import { renderArtifactCreationDraftMarkdown } from '../../../../schemas/creation.renderer.js';
+import { canonicalC14nV2SelfState } from '../../../../integrity/integrity.c14nV2.js';
+import { sha256Hex, utf8Bytes } from '../../../../export/package.bytes.js';
+import { resolveSchemaModule } from '../../../../schemas/resolver.js';
+import { loadNodePortableInput } from '../../input/node.input.js';
+import { runPortableOperation } from '../../operation.catalog.js';
+
+const STATE_RELATIVE_PATH = '.tiinex/continuation.json';
+
+export async function runCommonAuthorCli(parsed = {}, runtime = {}) {
+  const flags = parsed.flags || {};
+  const workspaceRoot = path.resolve(String(flags.workspace || parsed.positionals?.[0] || '.'));
+  const state = await readContinuationState(workspaceRoot);
+  const schemaId = String(flags.schema || '').trim();
+  const artifactRelativePath = normalizeWorkspaceRelativePath(flags.path || parsed.positionals?.[1] || '');
+  const bodyPath = String(flags.body || flags.content || '').trim();
+  if (!schemaId) throw new Error('portable.cli.author.schema.required');
+  if (!artifactRelativePath) throw new Error('portable.cli.author.path.required');
+  if (!bodyPath) throw new Error('portable.cli.author.body.required');
+  const artifactPath = safeWorkspaceTarget(workspaceRoot, artifactRelativePath);
+  const bodyMarkdown = (await readFile(path.resolve(bodyPath), 'utf8')).trim();
+  if (!bodyMarkdown) throw new Error('portable.cli.author.body.empty');
+
+  const parentRelativePath = resolveParentRelativePath(flags, state);
+  const parentPath = parentRelativePath ? safeWorkspaceTarget(workspaceRoot, parentRelativePath) : '';
+  const parentRecord = parentPath ? await parentRecordFromArtifact(parentPath, parentRelativePath, { workspaceRoot, childRelativePath: artifactRelativePath }) : {};
+  const transitionType = String(flags.transition || defaultTransition(schemaId, Boolean(parentPath))).trim();
+  const contract = buildArtifactCreationContract({ schemaId, transitionType });
+  const title = String(flags.title || firstHeading(bodyMarkdown) || state?.roleLabel || schemaId).trim();
+  const summary = String(flags.summary || title).trim();
+  const authors = String(flags.authors || state?.roleLabel || '').trim();
+  const why = Object.prototype.hasOwnProperty.call(flags, 'why') ? String(flags.why || '').trim() : '';
+  const status = String(flags.status || 'ready/local').trim();
+
+  const markdown = renderArtifactCreationDraftMarkdown(contract, {
+    currentSchemaId: schemaId,
+    parentRecord,
+    childPath: artifactRelativePath,
+    bodyMarkdown,
+    title,
+    summary,
+    authors,
+    why,
+    status,
+    createdAt: flags['created-at'] || new Date()
+  });
+  const selfIntegrity = canonicalC14nV2SelfState(markdown);
+  if (selfIntegrity.state !== 'verified') throw new Error(`portable.cli.author.integrity.${selfIntegrity.reason || selfIntegrity.state}`);
+
+  await mkdir(path.dirname(artifactPath), { recursive: true });
+  let wrote = false;
+  try {
+    await writeFile(artifactPath, markdown, { encoding: 'utf8', flag: flags.overwrite ? 'w' : 'wx' });
+    wrote = true;
+    const auditMaterial = await loadNodePortableInput(
+      [artifactPath, ...(parentPath ? [parentPath] : [])],
+      { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] }
+    );
+    const audit = await runPortableOperation('audit', auditMaterial, {});
+    const stageMaterial = await loadNodePortableInput(
+      normalizeRuntimePaths(runtime.defaultSchemaMaterialPaths),
+      { maxFiles: flags['max-files'], maxTextBytes: flags['max-text-bytes'] }
+    );
+    const stage = await runPortableOperation('stage-draft', {
+      ...stageMaterial,
+      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);
+    if (blocking) {
+      await rm(artifactPath, { force: true });
+      wrote = false;
+      return Object.freeze({
+        schema: 'tiinex.portable.common-author.result.v1',
+        operation: 'author',
+        status: 'blocked',
+        artifact: Object.freeze({ path: artifactRelativePath, schemaId, written: false }),
+        audit,
+        stage,
+        findingSummary: mergeFindingSummaries(audit?.findingSummary, stage?.findingSummary),
+        nextAction: 'Resolve the reported schema/continuity finding, then rerun the same author command. No invalid durable artifact was retained.',
+        boundary: 'Common-path authoring composes the shared renderer, c14n-v2 sealing, runtime audit, and staging qualification. It may write only the requested local Workspace artifact and runtime-only .tiinex continuation state; it performs no remote mutation.'
+      });
+    }
+    const updatedState = await updateContinuationState(workspaceRoot, state, {
+      lastAuthoredPath: artifactRelativePath,
+      lastAuthoredSchemaId: schemaId,
+      ...(schemaId === 'tiinex.handoff.v1' ? { returnHandoffPath: artifactRelativePath } : {})
+    });
+    return Object.freeze({
+      schema: 'tiinex.portable.common-author.result.v1',
+      operation: 'author',
+      status: 'qualified',
+      artifact: Object.freeze({ path: artifactRelativePath, absolutePath: artifactPath, schemaId, parentPath: parentRelativePath, 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'
+        ? `Run handoff ${workspaceRoot} to manufacture the canonical full-source return; the Handoff path and received parent carrier are already carried forward.`
+        : `Author the next result artifact with --parent ${artifactRelativePath}; Tooling will preserve and reseal exact local continuity.`,
+      continuationState: Object.freeze({ path: path.join(workspaceRoot, STATE_RELATIVE_PATH), returnHandoffPath: updatedState.returnHandoffPath || '' }),
+      boundary: 'Common-path authoring composes the shared renderer, c14n-v2 sealing, runtime audit, and staging qualification. It may write only the requested local Workspace artifact and runtime-only .tiinex continuation state; it performs no remote mutation.'
+    });
+  } catch (error) {
+    if (wrote && !flags['keep-invalid']) await rm(artifactPath, { force: true });
+    throw error;
+  }
+}
+
+async function parentRecordFromArtifact(parentPath, parentRelativePath, context = {}) {
+  const markdown = await readFile(parentPath, 'utf8');
+  const parsed = parseArtifactMarkdown(markdown);
+  const current = parsed.envelope?.current || {};
+  const schemaId = String(current.schema?.id || '').trim();
+  const schemaTarget = String(current.schema?.target || '').trim();
+  const self = canonicalC14nV2SelfState(markdown);
+  if (!schemaId) throw new Error('portable.cli.author.parent.schema-authority.required');
+  if (self.state !== 'verified') throw new Error(`portable.cli.author.parent.integrity.${self.reason || self.state}`);
+  const schemaReferenceAuthority = schemaTarget
+    ? exactDeclaredSchemaReferenceAuthority(schemaId, schemaTarget)
+    : await recoverQualifiedLocalSchemaReferenceAuthority(schemaId, context);
+  if (!schemaReferenceAuthority) throw new Error('portable.cli.author.parent.schema-authority.required');
+  return Object.freeze({
+    id: parentRelativePath,
+    path: parentRelativePath,
+    schemaId,
+    currentSchemaId: schemaId,
+    currentCreatedAt: String(current.createdAt || ''),
+    createdAt: String(current.createdAt || ''),
+    markdown,
+    recoveryMode: 'local-relative',
+    schemaReferenceAuthority
+  });
+}
+
+function exactDeclaredSchemaReferenceAuthority(schemaId, schemaTarget) {
+  return Object.freeze({
+    schemaId,
+    exactTargets: Object.freeze([schemaTarget]),
+    preferredTarget: schemaTarget,
+    resolutionState: 'qualified'
+  });
+}
+
+async function recoverQualifiedLocalSchemaReferenceAuthority(schemaId, context = {}) {
+  const workspaceRoot = path.resolve(String(context.workspaceRoot || '.'));
+  const childRelativePath = normalizeWorkspaceRelativePath(context.childRelativePath || '');
+  const resolution = resolveSchemaModule({ schemaId });
+  const module = resolution?.fallbackUsed ? null : resolution?.module || null;
+  const source = module?.schemaSource || null;
+  const qualification = typeof source?.qualify === 'function' ? source.qualify() : null;
+  const materialIdentity = qualification?.materialIdentity || {};
+  const bundledPath = normalizeWorkspaceRelativePath(source?.bundledPath || '');
+  const expectedSha256 = String(materialIdentity.sha256 || qualification?.checksum || '').trim().toLowerCase();
+  if (!module || String(module.id || '') !== schemaId) return null;
+  if (qualification?.state !== 'qualified' || materialIdentity?.state !== 'qualified' || String(materialIdentity.schemaId || '') !== schemaId) return null;
+  if (!bundledPath || !childRelativePath || !expectedSha256) return null;
+
+  let localMarkdown;
+  try { localMarkdown = await readFile(safeWorkspaceTarget(workspaceRoot, bundledPath), 'utf8'); }
+  catch { return null; }
+  if (sha256Hex(utf8Bytes(localMarkdown)).toLowerCase() !== expectedSha256) return null;
+
+  let localParsed;
+  try { localParsed = parseArtifactMarkdown(localMarkdown); }
+  catch { return null; }
+  if (String(localParsed.envelope?.current?.schema?.id || '').trim() !== schemaId) return null;
+
+  const childDir = path.posix.dirname(childRelativePath);
+  const preferredTarget = path.posix.relative(childDir === '.' ? '' : childDir, bundledPath);
+  if (!preferredTarget || path.posix.isAbsolute(preferredTarget)) return null;
+  return Object.freeze({
+    schemaId,
+    exactTargets: Object.freeze([preferredTarget]),
+    preferredTarget,
+    resolutionState: 'qualified',
+    targetAuthority: 'qualified-local-bundled-schema-material',
+    resolutionEvidence: Object.freeze({
+      state: 'qualified',
+      kind: 'workspace-bundled-schema-byte-match',
+      workspacePath: bundledPath,
+      sha256: expectedSha256
+    })
+  });
+}
+
+function resolveParentRelativePath(flags = {}, state = {}) {
+  if (flags['no-parent']) return '';
+  if (typeof flags.parent === 'string' && flags.parent.trim()) return normalizeWorkspaceRelativePath(flags.parent);
+  return normalizeWorkspaceRelativePath(state?.lastAuthoredPath || state?.selectedHandoffPath || '');
+}
+
+function defaultTransition(schemaId, hasParent) {
+  if (!hasParent) return 'create-artifact';
+  if (schemaId === 'tiinex.evidence.v1') return 'reference-record';
+  return 'continue-from-record';
+}
+
+function firstHeading(markdown = '') {
+  const match = String(markdown || '').match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : '';
+}
+
+function normalizeWorkspaceRelativePath(value = '') {
+  const raw = String(value || '').trim().replace(/\\/g, '/').replace(/^\.\//, '');
+  if (!raw || raw.startsWith('/') || /^[A-Za-z]:\//.test(raw)) return '';
+  const parts = raw.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) return '';
+  return parts.join('/');
+}
+
+function safeWorkspaceTarget(root, relative) {
+  const target = path.resolve(root, relative);
+  const rel = path.relative(root, target);
+  if (!relative || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) throw new Error(`portable.cli.author.path.unsafe:${relative}`);
+  return target;
+}
+
+async function readContinuationState(workspaceRoot) {
+  try { return JSON.parse(await readFile(path.join(workspaceRoot, STATE_RELATIVE_PATH), 'utf8')); }
+  catch { return {}; }
+}
+
+async function updateContinuationState(workspaceRoot, previous = {}, patch = {}) {
+  const statePath = path.join(workspaceRoot, STATE_RELATIVE_PATH);
+  const next = Object.freeze({ ...previous, ...patch, schema: 'tiinex.portable.ground-continuation-state.v1', version: 1 });
+  await mkdir(path.dirname(statePath), { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}
+
+function normalizeRuntimePaths(value) {
+  const values = Array.isArray(value) ? value : value ? [value] : [];
+  return values.map((item) => String(item || '').trim()).filter(Boolean);
+}
+
+function mergeFindingSummaries(...summaries) {
+  const counts = summaries.reduce((out, summary) => {
+    const value = summary?.counts || {};
+    out.error += Number(value.error || 0);
+    out.warning += Number(value.warning || 0);
+    out.info += Number(value.info || 0);
+    return out;
+  }, { error: 0, warning: 0, info: 0 });
+  counts.total = counts.error + counts.warning + counts.info;
+  return Object.freeze({ status: counts.error ? 'invalid' : counts.warning ? 'degraded' : 'clean', counts: Object.freeze(counts) });
+}

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

@@ -0,0 +1,330 @@
+const COMMON_DEFAULT_PROJECTION = 'common-default';
+
+export function projectCommonCliDefaultOutput(result = {}, parsed = {}) {
+  if (parsed?.flags?.full === true) return result;
+  if (parsed?.command === 'orient-handoff-package') return projectOrientDefault(result, parsed);
+  if (parsed?.command === 'project-grounding-readiness') return projectGroundDefault(result, parsed);
+  if (parsed?.command === 'manufacture-handoff-package' && parsed?.surfaceCommand === 'handoff') return projectHandoffDefault(result, parsed);
+  return result;
+}
+
+function projectOrientDefault(result = {}, parsed = {}) {
+  const projection = result?.entrypoint?.projection || {};
+  const routes = (result.routes || projection.routes || []).map(projectOrientRoute);
+  const workspaces = (result.workspaces || projection.workspaces || []).map((workspace) => Object.freeze({
+    id: String(workspace?.id || ''),
+    title: String(workspace?.title || ''),
+    qualification: String(workspace?.qualification || '')
+  }));
+  const actionableFindings = actionable(result);
+  const selected = routes.find((route) => route.pointerPath) || routes[0] || {};
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || 'orient-handoff-package',
+    resultSchema: result.resultSchema,
+    projection: COMMON_DEFAULT_PROJECTION,
+    status: result.status,
+    workspaces: Object.freeze(workspaces),
+    routes: Object.freeze(routes),
+    selection: result.selection || projection.selection || null,
+    authority: projection.authority ? Object.freeze({ ...projection.authority }) : null,
+    carrierLineage: compactCarrierLineage(result.carrierLineage),
+    nextAction: selected.pointerPath ? Object.freeze({
+      command: 'ground',
+      package: sourceArgument(parsed),
+      route: selected.pointerPath
+    }) : null,
+    findingSummary: result.findingSummary || null,
+    actionableFindings: Object.freeze(actionableFindings.slice(0, 20)),
+    actionableFindingsOmitted: Math.max(0, actionableFindings.length - 20),
+    detail: detailReceipt(parsed),
+    boundary: 'Common default orientation projection. It preserves route/workspace qualification, selection, non-authority, actionable findings, and the exact grounding route while moving package topology, endpoint-role, and closure receipts behind --full.'
+  });
+}
+
+function projectGroundDefault(result = {}, parsed = {}) {
+  const required = result?.coverage?.requiredContext || {};
+  const currentWork = result?.currentWork || {};
+  const continuity = result?.continuity || {};
+  const actionableFindings = actionable(result);
+  const continuing = typeof parsed?.flags?.continue === 'string' && parsed.flags.continue.length > 0;
+  const explicitRequiredBodies = typeof parsed?.flags?.['include-required-context'] === 'string' && parsed.flags['include-required-context'].length > 0;
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || 'project-grounding-readiness',
+    resultSchema: result.resultSchema,
+    projection: COMMON_DEFAULT_PROJECTION,
+    status: result.status,
+    readiness: compactReadiness(result.readiness),
+    authority: compactGroundAuthority(result.authority),
+    requiredContext: Object.freeze({
+      declared: Number(required.declared || 0),
+      matchedInWorkspaceSnapshots: Number(required.matchedInWorkspaceSnapshots || 0),
+      missingFromWorkspaceSnapshots: Number(required.missingFromWorkspaceSnapshots || 0),
+      items: Object.freeze((continuing && !explicitRequiredBodies ? [] : (required.items || [])).map(projectRequiredContextItem)),
+      itemsOmitted: Number(required.itemsOmitted || 0) + (continuing && !explicitRequiredBodies ? (required.items || []).length : 0),
+      bodiesProjected: Number(required.bodiesProjected || 0),
+      bodiesAvailable: Number(required.bodiesAvailable || 0)
+    }),
+    capsule: result.capsule ? Object.freeze({ ...result.capsule }) : null,
+    currentWork: Object.freeze({
+      state: String(currentWork.state || ''),
+      frontier: Object.freeze((currentWork.frontier || []).map(projectCurrentWorkItem)),
+      frontierOmitted: Number(currentWork.frontierOmitted || 0),
+      blockers: Object.freeze((currentWork.blockers || []).slice(0, 20).map((item) => Object.freeze({ ...item }))),
+      blockersOmitted: Number(currentWork.blockersOmitted || 0) + Math.max(0, (currentWork.blockers || []).length - 20)
+    }),
+    continuity: compactContinuity(continuity, { continuing }),
+    ...(result.continuationMaterialization ? { continuationMaterialization: Object.freeze({ ...result.continuationMaterialization }) } : {}),
+    findingSummary: result.findingSummary || null,
+    actionableFindings: Object.freeze(actionableFindings.slice(0, 20)),
+    actionableFindingsOmitted: Math.max(0, actionableFindings.length - 20),
+    detail: detailReceipt(parsed),
+    boundary: result.boundary || 'Decision-oriented common default grounding projection. Full qualified receipt remains available with --full.'
+  });
+}
+
+function projectHandoffDefault(result = {}, parsed = {}) {
+  const human = result.humanOutput || {};
+  const primary = result.primaryOutput || null;
+  const plan = result.planSummary || {};
+  const carrier = result.carrierProjection || {};
+  const route = (carrier.routes || [])[0] || {};
+  const actionableFindings = actionable(result);
+  return Object.freeze({
+    schema: result.schema,
+    operation: result.operation || 'manufacture-handoff-package',
+    resultSchema: result.resultSchema,
+    projection: COMMON_DEFAULT_PROJECTION,
+    status: result.status,
+    verification: result.verification ? Object.freeze({ ...result.verification }) : null,
+    closure: Object.freeze({
+      status: String(plan.status || ''),
+      requiredClosureReady: Boolean(plan.requiredClosureReady),
+      semanticHandoffStatus: String(plan.semanticHandoffStatus || ''),
+      requiredCount: Array.isArray(plan.required) ? plan.required.length : 0,
+      referenceCount: Array.isArray(plan.reference) ? plan.reference.length : 0,
+      workspaces: Object.freeze((plan.workspaces || []).map((workspace) => Object.freeze({
+        id: String(workspace.id || ''),
+        materialization: String(workspace.materialization || ''),
+        qualification: String(workspace.qualification || ''),
+        entryCount: Number(workspace.entryCount || 0),
+        completenessState: String(workspace.completenessState || '')
+      })))
+    }),
+    carrier: Object.freeze({
+      status: String(carrier.status || ''),
+      mode: String(carrier.mode || ''),
+      lineage: carrier.lineage ? compactCarrierLineage(carrier.lineage) : null,
+      route: Object.freeze({
+        id: String(route.id || ''),
+        state: String(route.state || ''),
+        workspaceId: String(route.workspaceId || ''),
+        workspaceRelativePath: String(route.workspaceRelativePath || ''),
+        from: String(route.from || ''),
+        to: String(route.to || ''),
+        projectedFilename: String(route.projectedFilename || '')
+      })
+    }),
+    transport: Object.freeze({
+      primary: primary ? Object.freeze({ ...primary }) : null,
+      routing: human.normalInlineRouting ? Object.freeze({ ...human.normalInlineRouting }) : null,
+      sharedRouting: human.sharedRouting ? Object.freeze({ ...human.sharedRouting, routes: Object.freeze((human.sharedRouting.routes || []).map((item) => Object.freeze({ ...item }))) }) : null,
+      presentation: compactHandoffPresentation(human.presentation),
+      normalEmission: compactHandoffNormalEmission(human.normalEmissionBoundary)
+    }),
+    roundtripSummary: result.roundtripSummary ? Object.freeze({ ...result.roundtripSummary }) : null,
+    toolingBootstrapInspection: result.toolingBootstrapInspection ? Object.freeze({
+      status: String(result.toolingBootstrapInspection.status || ''),
+      delivery: String(result.toolingBootstrapInspection.delivery || ''),
+      counts: Object.freeze({ ...(result.toolingBootstrapInspection.counts || {}) })
+    }) : null,
+    operationBoundary: result.operationBoundary ? Object.freeze({ ...result.operationBoundary }) : null,
+    findingSummary: result.findingSummary || null,
+    actionableFindings: Object.freeze(actionableFindings.slice(0, 20)),
+    actionableFindingsOmitted: Math.max(0, actionableFindings.length - 20),
+    detail: detailReceipt(parsed),
+    boundary: 'Common default Handoff manufacture projection. Normal operator completion is one canonical Handoff package plus the exact adjacent routing content; markdown-capable hosts must render that routing in a fenced code block. Canonical Workspace Evidence/Handoff artifacts remain inside the carrier and are not additional loose transport payloads. Full manufacturing evidence remains available behind --full.'
+  });
+}
+
+
+function compactHandoffPresentation(presentation = {}) {
+  if (!presentation || typeof presentation !== 'object') return null;
+  return Object.freeze({
+    copyableSurfaceRequired: Boolean(presentation.copyableSurfaceRequired),
+    exactContentRequired: Boolean(presentation.exactContentRequired),
+    fencedCodeBlockWhenSupported: String(presentation.fencedCodeBlockWhenSupported || ''),
+    markdownCapableHostRendering: String(presentation.markdownCapableHostRendering || ''),
+    wrapperAuthority: String(presentation.wrapperAuthority || '')
+  });
+}
+
+function compactHandoffNormalEmission(boundary = {}) {
+  if (!boundary || typeof boundary !== 'object') return null;
+  return Object.freeze({
+    allowed: Object.freeze([...(boundary.allowed || [])]),
+    canonicalFilePayloadCount: Number(boundary.canonicalFilePayloadCount || 0),
+    workspaceArtifactsAsLooseTransportFiles: Boolean(boundary.workspaceArtifactsAsLooseTransportFiles),
+    semanticWorkSummaryProse: Boolean(boundary.semanticWorkSummaryProse),
+    helperArtifacts: Boolean(boundary.helperArtifacts),
+    manuallyReconstructedRouting: Boolean(boundary.manuallyReconstructedRouting),
+    duplicateNormalFileChoices: Boolean(boundary.duplicateNormalFileChoices)
+  });
+}
+
+function projectOrientRoute(route = {}) {
+  return Object.freeze({
+    id: String(route.id || ''),
+    state: String(route.state || ''),
+    workspaceId: String(route.workspaceId || ''),
+    workspaceRelativeHandoffPath: String(route.workspaceRelativeHandoffPath || ''),
+    from: String(route.from || ''),
+    to: String(route.to || ''),
+    pointerPath: String(route.pointerPath || '')
+  });
+}
+
+function compactReadiness(readiness = {}) {
+  return Object.freeze({
+    state: String(readiness.state || ''),
+    reasons: Object.freeze((readiness.reasons || []).map((item) => Object.freeze({
+      code: String(item?.code || ''),
+      message: String(item?.message || '')
+    }))),
+    missingEvidence: Object.freeze([...(readiness.missingEvidence || [])]),
+    nextAction: readiness.nextAction ? Object.freeze({ ...readiness.nextAction }) : null
+  });
+}
+
+function compactGroundAuthority(authority = {}) {
+  const route = authority.route || {};
+  const handoff = authority.handoff || {};
+  const role = authority.role || {};
+  const holderBinding = authority.holderBinding || {};
+  const operationBoundary = authority.operationBoundary || {};
+  return Object.freeze({
+    state: String(authority.state || ''),
+    route: Object.freeze({
+      id: String(route.id || ''),
+      pointerPath: String(route.pointerPath || ''),
+      workspaceId: String(route.workspaceId || '')
+    }),
+    handoff: Object.freeze({
+      purpose: String(handoff.purpose || ''),
+      from: String(handoff.from || ''),
+      to: String(handoff.to || ''),
+      completionExpectation: handoff.completionExpectation || null
+    }),
+    role: Object.freeze({
+      state: String(role.state || ''),
+      label: String(role.label || ''),
+      kind: String(role.kind || '')
+    }),
+    holderBinding: Object.freeze({
+      state: String(holderBinding.state || ''),
+      holderId: String(holderBinding.holderId || ''),
+      roleLabel: String(holderBinding.roleLabel || ''),
+      recipientRoleLabel: String(holderBinding.recipientRoleLabel || ''),
+      recipientCompatibility: String(holderBinding.recipientCompatibility || ''),
+      source: String(holderBinding.source || ''),
+      explicit: Boolean(holderBinding.explicit),
+      inferredFromTransport: Boolean(holderBinding.inferredFromTransport)
+    }),
+    operationBoundary: Object.freeze({
+      sourceMutation: Boolean(operationBoundary.sourceMutation),
+      remoteWrite: Boolean(operationBoundary.remoteWrite),
+      semanticAuthority: String(operationBoundary.semanticAuthority || ''),
+      boundary: String(operationBoundary.boundary || '')
+    })
+  });
+}
+
+function projectRequiredContextItem(item = {}) {
+  const contentProjected = Boolean(item.contentProjected && typeof item.content === 'string');
+  return Object.freeze({
+    requirementId: String(item.requirementId || ''),
+    name: String(item.name || ''),
+    state: String(item.state || ''),
+    workspaceId: String(item.workspaceId || ''),
+    innerPath: String(item.innerPath || ''),
+    contentProjected,
+    ...(contentProjected ? { content: item.content } : {})
+  });
+}
+
+function projectCurrentWorkItem(item = {}) {
+  const contentProjected = Boolean(item.contentProjected && typeof item.content === 'string');
+  return Object.freeze({
+    id: String(item.id || ''),
+    path: String(item.path || ''),
+    title: String(item.title || ''),
+    declaredStatus: String(item.declaredStatus || ''),
+    ...(contentProjected ? { contentProjected: true, content: item.content } : { contentProjected: false })
+  });
+}
+
+function compactContinuity(continuity = {}, options = {}) {
+  const proof = continuity.proof || {};
+  const roots = proof.roots || [];
+  const continuing = Boolean(options.continuing);
+  return Object.freeze({
+    state: String(continuity.state || ''),
+    roots: Object.freeze((continuing ? [] : roots).map((root) => Object.freeze({
+      id: String(root.id || ''),
+      path: String(root.path || ''),
+      title: String(root.title || ''),
+      schemaId: String(root.schemaId || ''),
+      declaresParent: Boolean(root.declaresParent),
+      hasContinuityContext: Boolean(root.hasContinuityContext),
+      hasIntegrity: Boolean(root.hasIntegrity)
+    }))),
+    ...(continuing ? { rootsOmitted: roots.length } : {}),
+    blockingIssues: Object.freeze([...(continuity.blockingIssues || [])]),
+    blockingIssuesOmitted: Number(continuity.blockingIssuesOmitted || 0),
+    recovery: continuity.recovery ? Object.freeze({ ...continuity.recovery }) : null,
+    losses: continuity.losses ? Object.freeze({
+      state: String(continuity.losses.state || ''),
+      blocking: Boolean(continuity.losses.blocking),
+      items: Object.freeze([...(continuity.losses.items || [])]),
+      itemsOmitted: Number(continuity.losses.itemsOmitted || 0)
+    }) : null
+  });
+}
+
+function compactCarrierLineage(lineage = {}) {
+  if (!lineage || typeof lineage !== 'object') return null;
+  return Object.freeze({
+    mode: String(lineage.mode || ''),
+    dimension: String(lineage.dimension || ''),
+    parentDimension: String(lineage.parentDimension || ''),
+    checkpointKind: String(lineage.checkpointKind || ''),
+    authority: String(lineage.authority || '')
+  });
+}
+
+function actionable(result = {}) {
+  const explicit = Array.isArray(result.actionableFindings) ? result.actionableFindings : [];
+  if (explicit.length) return explicit.map((item) => Object.freeze({ ...item }));
+  return (result.findings || [])
+    .filter((item) => item?.severity === 'error' || item?.severity === 'warning')
+    .map((item) => Object.freeze({ ...item }));
+}
+
+function detailReceipt(parsed = {}) {
+  const flags = parsed.flags || {};
+  return Object.freeze({
+    fullReceipt: Object.freeze({
+      command: String(parsed.surfaceCommand || parsed.command || ''),
+      package: sourceArgument(parsed),
+      workspace: parsed?.surfaceCommand === 'handoff' ? sourceArgument(parsed) : '',
+      route: typeof flags.route === 'string' ? flags.route : '',
+      continue: typeof flags.continue === 'string' ? flags.continue : '',
+      flag: '--full'
+    })
+  });
+}
+
+function sourceArgument(parsed = {}) {
+  return String(parsed.positionals?.[0] || '');
+}

package/src/tooling/portable/adapters/cli/cli.editor-assistance.js

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+
+export async function prepareEditorAssistanceCliInput(material = {}, flags = {}) {
+  const focusPath = norm(flags.focus || flags.path || '');
+  if (!focusPath || !flags.overlay) return { input: { ...material, focusPath }, options: {} };
+  const overlayMarkdown = await readFile(String(flags.overlay), 'utf8');
+  const files = (material.files || []).map((file) => norm(file.path || '') === focusPath ? { ...file, content: overlayMarkdown } : file);
+  const input = { ...material, files, focusPath };
+  if (Array.isArray(material.records)) input.records = material.records.map((record) => norm(record.path || record.id || '') === focusPath ? { ...record, markdown: overlayMarkdown } : record);
+  return { input, options: {} };
+}
+
+function norm(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, ''); }