@pi-unipi/background-tasks 2.6.1

package/src/fusion/config.ts

@@ -0,0 +1,449 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rm } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import type { Api, Model } from '@earendil-works/pi-ai';
+import { isJsonObject, parseJsonText, type JsonObject } from '../types.js';
+import { replaceFileDurable } from '../durable-fs.js';
+import { CLAUDE_CODE_200K_SUBSCRIPTION_CONTEXT_WINDOW } from '../anthropic-attribution.js';
+import {
+  FUSION_MODEL_CONFIG_SCHEMA_VERSION,
+  FusionError,
+  type FusionModelConfigRevision,
+  type FusionModelConfigV1,
+  type FusionModelSelection,
+  type FusionThinkingLevel,
+  type LoadedFusionModelConfig,
+  type ResolvedFusionModel,
+  type ResolvedFusionModels,
+} from './types.js';
+
+export const FUSION_MODEL_CONFIG_FILE = 'fusion-models.json';
+export const CURRENT_MODEL_SELECTION = '$current';
+
+export interface FusionModelRegistry {
+  getAll(): Model<Api>[];
+  getAvailable(): Model<Api>[];
+  find?(provider: string, modelId: string): Model<Api> | undefined;
+  isUsingOAuth?(model: Model<Api>): boolean;
+}
+
+export interface ResolveFusionModelsInput {
+  config: FusionModelConfigV1;
+  modelRegistry: FusionModelRegistry;
+  currentModel: Model<Api> | undefined;
+  thinkingLevel: FusionThinkingLevel;
+}
+
+export function defaultFusionModelConfig(): FusionModelConfigV1 {
+  return {
+    schema_version: FUSION_MODEL_CONFIG_SCHEMA_VERSION,
+    candidates: [CURRENT_MODEL_SELECTION, CURRENT_MODEL_SELECTION, CURRENT_MODEL_SELECTION],
+    evaluator: CURRENT_MODEL_SELECTION,
+    merger: CURRENT_MODEL_SELECTION,
+  };
+}
+
+export function fusionModelConfigPath(agentDir = getAgentDir()): string {
+  return join(agentDir, FUSION_MODEL_CONFIG_FILE);
+}
+
+function sha256Hex(bytes: Buffer): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+async function revisionForPath(path: string): Promise<FusionModelConfigRevision> {
+  try {
+    const bytes = await readFile(path);
+    return { path, exists: true, sha256: sha256Hex(bytes) };
+  } catch (error) {
+    if (errorHasCode(error, 'ENOENT')) return { path, exists: false, sha256: null };
+    throw error;
+  }
+}
+
+function errorHasCode(error: unknown, code: string): boolean {
+  return isJsonObject(error) && error['code'] === code;
+}
+
+function keysOf(value: object): string[] {
+  return Object.keys(value).sort();
+}
+
+function assertClosed(record: JsonObject, expected: readonly string[], label: string): void {
+  const expectedSet = new Set(expected);
+  for (const key of Object.keys(record)) {
+    if (!expectedSet.has(key)) throw configError(`${label} contains unknown key ${key}`);
+  }
+  for (const key of expected) {
+    if (!Object.prototype.hasOwnProperty.call(record, key)) {
+      throw configError(`${label} is missing key ${key}`);
+    }
+  }
+}
+
+function configError(message: string): FusionError {
+  return new FusionError(message, { code: 'config_invalid', childCreated: false });
+}
+
+function requireSelection(value: unknown, label: string): FusionModelSelection {
+  if (typeof value !== 'string') throw configError(`${label} must be a string`);
+  if (value === CURRENT_MODEL_SELECTION) return value;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) throw configError(`${label} must not be blank`);
+  if (trimmed !== value) throw configError(`${label} must not have surrounding whitespace`);
+  if (!trimmed.includes('/')) throw configError(`${label} must be a qualified provider/model key`);
+  return trimmed;
+}
+
+function requireCandidateSelections(
+  value: unknown,
+): [FusionModelSelection, FusionModelSelection, FusionModelSelection] {
+  if (!Array.isArray(value)) throw configError('candidates must be an array');
+  if (value.length !== 3) throw configError('candidates must contain exactly three entries');
+  const first = requireSelection(value[0], 'candidates[0]');
+  const second = requireSelection(value[1], 'candidates[1]');
+  const third = requireSelection(value[2], 'candidates[2]');
+  return [first, second, third];
+}
+
+export function parseFusionModelConfig(value: unknown): FusionModelConfigV1 {
+  if (!isJsonObject(value) || Array.isArray(value))
+    throw configError('fusion model config must be an object');
+  const record: JsonObject = value;
+  assertClosed(
+    record,
+    ['schema_version', 'candidates', 'evaluator', 'merger'],
+    'fusion model config',
+  );
+  if (record['schema_version'] !== FUSION_MODEL_CONFIG_SCHEMA_VERSION) {
+    throw configError('fusion model config schema_version mismatch');
+  }
+  return {
+    schema_version: FUSION_MODEL_CONFIG_SCHEMA_VERSION,
+    candidates: requireCandidateSelections(record['candidates']),
+    evaluator: requireSelection(record['evaluator'], 'evaluator'),
+    merger: requireSelection(record['merger'], 'merger'),
+  };
+}
+
+export async function loadFusionModelConfig(
+  path = fusionModelConfigPath(),
+): Promise<LoadedFusionModelConfig> {
+  const revision = await revisionForPath(path);
+  if (!revision.exists) return { config: defaultFusionModelConfig(), revision };
+  let parsed: unknown;
+  try {
+    parsed = parseJsonText(await readFile(path, 'utf8'));
+  } catch (error) {
+    throw configError(
+      `fusion model config is not valid JSON at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const config = parseFusionModelConfig(parsed);
+  return { config, revision };
+}
+
+function qualifiedModelKey(model: Pick<Model<Api>, 'provider' | 'id'>): string {
+  return `${model.provider}/${model.id}`;
+}
+
+function requireContextWindow(model: Model<Api>, label: string): number {
+  const value = model.contextWindow;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new FusionError(`${label} has no positive context window`, {
+      code: 'model_unavailable',
+      childCreated: false,
+    });
+  }
+  return Math.floor(value);
+}
+
+function transportContextWindow(model: Model<Api>, label: string): number {
+  const advertised = requireContextWindow(model, label);
+  return model.provider === 'anthropic'
+    ? Math.min(advertised, CLAUDE_CODE_200K_SUBSCRIPTION_CONTEXT_WINDOW)
+    : advertised;
+}
+
+function requireMaxOutputTokens(model: Model<Api>, label: string): number {
+  const value = model.maxTokens;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new FusionError(`${label} has no positive maximum output token capacity`, {
+      code: 'model_unavailable',
+      childCreated: false,
+    });
+  }
+  return Math.floor(value);
+}
+
+function modelIndex(models: readonly Model<Api>[]): Map<string, Model<Api>> {
+  const out = new Map<string, Model<Api>>();
+  for (const model of models) out.set(qualifiedModelKey(model), model);
+  return out;
+}
+
+const FRONTIER_MODEL_PATTERN =
+  /(?:^|[-_/])(?:gpt|codex|claude|opus|sonnet|o[134](?:-[a-z0-9.]+)*)(?:[-_/]|$)/iu;
+const TRUSTED_SUBSCRIPTION_ENDPOINTS = Object.freeze({
+  anthropic: 'https://api.anthropic.com',
+  'openai-codex': 'https://chatgpt.com/backend-api',
+} as const);
+const AUTH_HEADER_NAMES = new Set(['authorization', 'proxy-authorization', 'x-api-key', 'api-key']);
+
+function isKnownFrontierEndpoint(baseUrl: string | undefined): boolean {
+  if (baseUrl === undefined || baseUrl.trim().length === 0) return false;
+  try {
+    const hostname = new URL(baseUrl).hostname.toLowerCase().replace(/\.+$/u, '');
+    return (
+      hostname === 'api.openai.com' ||
+      hostname === 'api.anthropic.com' ||
+      hostname === 'openrouter.ai' ||
+      hostname === 'chatgpt.com' ||
+      hostname.endsWith('.openai.azure.com') ||
+      hostname.endsWith('.cognitiveservices.azure.com') ||
+      hostname.endsWith('.ai.azure.com')
+    );
+  } catch {
+    return false;
+  }
+}
+
+function assertTrustedSubscriptionEndpoint(
+  model: Model<Api>,
+  slotLabel: string,
+  provider: keyof typeof TRUSTED_SUBSCRIPTION_ENDPOINTS,
+): void {
+  const expectedText = TRUSTED_SUBSCRIPTION_ENDPOINTS[provider];
+  const effectiveText = model.baseUrl?.trim() || expectedText;
+  let effective: URL;
+  try {
+    effective = new URL(effectiveText);
+  } catch {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} has a malformed subscription endpoint`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  const expected = new URL(expectedText);
+  const effectivePath = effective.href.slice(effective.origin.length).replace(/\/+$/u, '');
+  const expectedPath = expected.href.slice(expected.origin.length).replace(/\/+$/u, '');
+  if (
+    effective.protocol !== 'https:' ||
+    effective.username !== '' ||
+    effective.password !== '' ||
+    effective.search !== '' ||
+    effective.hash !== '' ||
+    effective.origin !== expected.origin ||
+    effectivePath !== expectedPath
+  ) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} does not use the trusted Pi subscription endpoint ${expectedText}`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  const unsafeHeader = Object.keys(model.headers ?? {}).find((name) =>
+    AUTH_HEADER_NAMES.has(name.toLowerCase()),
+  );
+  if (unsafeHeader !== undefined) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} overrides subscription authentication header ${unsafeHeader}`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+}
+
+function assertSubscriptionRoute(
+  model: Model<Api>,
+  slotLabel: string,
+  registry: FusionModelRegistry,
+): void {
+  const provider = model.provider.toLowerCase();
+  const frontier =
+    provider === 'openai' ||
+    provider === 'openrouter' ||
+    provider === 'anthropic' ||
+    provider === 'openai-codex' ||
+    provider.includes('azure') ||
+    FRONTIER_MODEL_PATTERN.test(`${provider}/${model.id}`) ||
+    isKnownFrontierEndpoint(model.baseUrl);
+  if (!frontier) return;
+  if (provider !== 'anthropic' && provider !== 'openai-codex') {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} is a frontier-model API channel; Fusion requires the Pi Anthropic or Codex subscription route`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  assertTrustedSubscriptionEndpoint(model, slotLabel, provider);
+  if (registry.isUsingOAuth === undefined) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} cannot be admitted because ModelRegistry OAuth observation is unavailable`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+  if (!registry.isUsingOAuth(model)) {
+    throw new FusionError(
+      `${slotLabel} route ${model.provider}/${model.id} is not using subscription OAuth; metered API credentials are forbidden for Fusion`,
+      { code: 'model_unavailable', childCreated: false },
+    );
+  }
+}
+
+function resolveSelection(
+  selection: FusionModelSelection,
+  slotLabel: string,
+  availableByKey: Map<string, Model<Api>>,
+  currentModel: Model<Api> | undefined,
+  thinkingLevel: FusionThinkingLevel,
+  registry: FusionModelRegistry,
+): ResolvedFusionModel {
+  if (selection === CURRENT_MODEL_SELECTION) {
+    if (currentModel === undefined) {
+      throw new FusionError(`${slotLabel} uses $current but Pi has no current model`, {
+        code: 'model_unavailable',
+        childCreated: false,
+      });
+    }
+    const qualifiedId = qualifiedModelKey(currentModel);
+    const available = availableByKey.get(qualifiedId);
+    if (available === undefined) {
+      throw new FusionError(
+        `${slotLabel} current model is not available to child Pi: ${qualifiedId}`,
+        {
+          code: 'model_unavailable',
+          childCreated: false,
+        },
+      );
+    }
+    assertSubscriptionRoute(available, slotLabel, registry);
+    return {
+      selection,
+      source: 'current',
+      provider: available.provider,
+      model: available.id,
+      qualifiedId,
+      thinkingLevel,
+      contextWindow: transportContextWindow(available, slotLabel),
+      maxOutputTokens: requireMaxOutputTokens(available, slotLabel),
+    };
+  }
+  const model = availableByKey.get(selection);
+  if (model === undefined) {
+    throw new FusionError(`${slotLabel} configured model is unavailable: ${selection}`, {
+      code: 'model_unavailable',
+      childCreated: false,
+    });
+  }
+  assertSubscriptionRoute(model, slotLabel, registry);
+  return {
+    selection,
+    source: 'configured',
+    provider: model.provider,
+    model: model.id,
+    qualifiedId: selection,
+    thinkingLevel,
+    contextWindow: transportContextWindow(model, slotLabel),
+    maxOutputTokens: requireMaxOutputTokens(model, slotLabel),
+  };
+}
+
+export function resolveFusionModels(input: ResolveFusionModelsInput): ResolvedFusionModels {
+  const availableByKey = modelIndex(input.modelRegistry.getAvailable());
+  const [first, second, third] = input.config.candidates;
+  const resolve = (selection: FusionModelSelection, slot: string): ResolvedFusionModel =>
+    resolveSelection(
+      selection,
+      slot,
+      availableByKey,
+      input.currentModel,
+      input.thinkingLevel,
+      input.modelRegistry,
+    );
+  return {
+    candidates: [
+      resolve(first, 'candidate 1'),
+      resolve(second, 'candidate 2'),
+      resolve(third, 'candidate 3'),
+    ],
+    evaluator: resolve(input.config.evaluator, 'evaluator'),
+    merger: resolve(input.config.merger, 'merger'),
+  };
+}
+
+async function delay(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function withConfigLock<T>(path: string, fn: () => Promise<T>): Promise<T> {
+  const dir = dirname(path);
+  const lockPath = join(dir, `.${basename(path)}.lock`);
+  const started = Date.now();
+  let handle: Awaited<ReturnType<typeof open>> | undefined;
+  while (handle === undefined) {
+    try {
+      handle = await open(lockPath, 'wx', 0o600);
+    } catch (error) {
+      if (!errorHasCode(error, 'EEXIST')) throw error;
+      if (Date.now() - started > 10_000) {
+        throw new FusionError(`timed out waiting for fusion model config lock: ${path}`, {
+          code: 'config_conflict',
+          childCreated: false,
+        });
+      }
+      await delay(25);
+    }
+  }
+  try {
+    await handle.writeFile(`${String(process.pid)}\n`);
+    await handle.sync();
+    return await fn();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+function prettyConfig(config: FusionModelConfigV1): string {
+  const sorted = {
+    schema_version: config.schema_version,
+    candidates: [...config.candidates],
+    evaluator: config.evaluator,
+    merger: config.merger,
+  };
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+function revisionsMatch(
+  expected: FusionModelConfigRevision,
+  current: FusionModelConfigRevision,
+): boolean {
+  if (expected.path !== current.path) return false;
+  if (expected.exists !== current.exists) return false;
+  return expected.sha256 === current.sha256;
+}
+
+export async function saveFusionModelConfig(
+  path: string,
+  config: FusionModelConfigV1,
+  expectedRevision: FusionModelConfigRevision,
+): Promise<FusionModelConfigRevision> {
+  parseFusionModelConfig(config);
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  return withConfigLock(path, async () => {
+    const current = await revisionForPath(path);
+    if (!revisionsMatch(expectedRevision, current)) {
+      throw new FusionError(`fusion model config changed on disk: ${path}`, {
+        code: 'config_conflict',
+        childCreated: false,
+      });
+    }
+    await replaceFileDurable(path, prettyConfig(config));
+    return revisionForPath(path);
+  });
+}
+
+export function describeFusionModelConfig(config: FusionModelConfigV1): string {
+  return keysOf(config).join(', ');
+}

package/src/fusion/context.ts

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../attested-pi-run.js';
+import {
+  projectVisibleConversationV2,
+  type OmittedRunCounts,
+  type ProjectedConversationV2,
+  type ProjectionEntry,
+} from '../context-visible-conversation-v2.js';
+import {
+  snapshotParentConversation,
+  type ParentContextSource,
+  type ParentSnapshotOptions,
+  type ReadonlyParentSessionManager,
+} from '../context-parent-snapshot.js';
+import type { Message } from '@earendil-works/pi-ai';
+import { FUSION_REASON_TOOL_NAME } from './workflows.js';
+import {
+  FUSION_BRANCH_FILTER_ID,
+  FUSION_COMMAND_CONTEXT_POLICY_ID,
+  FUSION_CONTEXT_LEDGER_SCHEMA_VERSION,
+  FUSION_CONTEXT_TRANSFORM_ID,
+  FUSION_INPUT_SCHEMA_VERSION,
+  FUSION_TOOL_CONTEXT_POLICY_ID,
+  FusionError,
+  type FusionBranchFilterDescriptor,
+  type FusionCanonicalRequestV3,
+  type FusionSessionProjectionCanonicalInputV5,
+  type FusionWorkflowId,
+  type FusionContextOmissionLedgerV2,
+  type FusionContextPolicyDescriptor,
+  type FusionConversationProjectionV3,
+  type FusionProjectionEntry,
+  type FusionProjectionOmissionCounts,
+  type FusionRequestAuthority,
+  type FusionSource,
+} from './types.js';
+
+/**
+ * Re-exported from the workflow registry, which owns every workflow's tool name.
+ * Kept here so existing importers of this module keep working unchanged.
+ */
+export {
+  FUSION_BRAINSTORM_TOOL_NAME,
+  FUSION_REASON_TOOL_NAME,
+  FUSION_INVESTIGATE_TOOL_NAME,
+  FUSION_RESEARCH_TOOL_NAME,
+  FUSION_VALIDATE_TOOL_NAME,
+} from './workflows.js';
+
+/** Retained for source compatibility; Fusion's session access is the shared adapter. */
+export type FusionReadonlySessionManager = ReadonlyParentSessionManager;
+export type FusionContextSource = ParentContextSource;
+
+export interface BuildFusionCanonicalInputOptions {
+  source: FusionSource;
+  request: string;
+  toolCallId?: string;
+  toolName?: string;
+  workflow?: FusionWorkflowId;
+}
+
+export interface BuiltFusionCanonicalInput {
+  input: FusionSessionProjectionCanonicalInputV5;
+  serialized: string;
+  ledger: FusionContextOmissionLedgerV2;
+  transcriptLeafId: string | null;
+}
+
+export function normalizeFusionCommandRequest(args: string): string {
+  return args.trim();
+}
+
+function sha256Text(value: string): string {
+  return createHash('sha256').update(Buffer.from(value, 'utf8')).digest('hex');
+}
+
+function contextPolicyId(source: FusionSource): string {
+  return source === 'tool' ? FUSION_TOOL_CONTEXT_POLICY_ID : FUSION_COMMAND_CONTEXT_POLICY_ID;
+}
+
+function requestAuthority(source: FusionSource): FusionRequestAuthority {
+  return source === 'tool' ? 'explicit_text' : 'directive_over_projected_conversation';
+}
+
+function policyDescriptor(source: FusionSource): FusionContextPolicyDescriptor {
+  return {
+    id: contextPolicyId(source),
+    transform: FUSION_CONTEXT_TRANSFORM_ID,
+    version: 2,
+    receipt_format: 'omitted_activity.v2',
+    user_text: 'verbatim',
+    assistant_text: 'verbatim',
+    assistant_thinking: 'ledger_only',
+    tool_call_arguments: 'ledger_only',
+    tool_results: 'ledger_only',
+    tool_payload_preview_bytes: 0,
+    images: 'marker_or_ledger_only',
+    unknown_block_behavior: 'error',
+  };
+}
+
+function compactOmissionCounts(counts: OmittedRunCounts): FusionProjectionOmissionCounts {
+  return [
+    counts.assistant_thinking ?? 0,
+    counts.tool_calls ?? 0,
+    counts.tool_result_texts ?? 0,
+  ];
+}
+
+function expandOmissionCounts(counts: FusionProjectionOmissionCounts): OmittedRunCounts {
+  const out: OmittedRunCounts = {};
+  const [assistantThinking, toolCalls, toolResults] = counts;
+  if (assistantThinking > 0) out.assistant_thinking = assistantThinking;
+  if (toolCalls > 0) out.tool_calls = toolCalls;
+  if (toolResults > 0) out.tool_result_texts = toolResults;
+  return out;
+}
+
+export function compactFusionProjectionEntry(entry: ProjectionEntry): FusionProjectionEntry {
+  if (entry.kind === 'text') {
+    return [
+      't',
+      entry.role === 'user' ? 'u' : 'a',
+      entry.source_ordinal,
+      entry.block_ordinal,
+      entry.text,
+    ];
+  }
+  return ['o', [entry.at[0], entry.at[1]], entry.bytes, compactOmissionCounts(entry.counts)];
+}
+
+export function expandFusionProjectionEntry(entry: FusionProjectionEntry): ProjectionEntry {
+  if (entry[0] === 't') {
+    return {
+      kind: 'text',
+      source_ordinal: entry[2],
+      block_ordinal: entry[3],
+      role: entry[1] === 'u' ? 'user' : 'assistant',
+      text: entry[4],
+    };
+  }
+  return {
+    kind: 'omitted_activity',
+    at: [entry[1][0], entry[1][1]],
+    bytes: entry[2],
+    counts: expandOmissionCounts(entry[3]),
+  };
+}
+
+function compactFusionProjectionEntries(
+  entries: readonly ProjectionEntry[],
+): readonly FusionProjectionEntry[] {
+  return entries.map(compactFusionProjectionEntry);
+}
+
+function compactOmissionReceiptBytes(entries: readonly FusionProjectionEntry[]): number {
+  let total = 0;
+  for (const entry of entries) {
+    if (entry[0] === 'o') total += Buffer.byteLength(canonicalJson(entry), 'utf8');
+  }
+  return total;
+}
+
+/**
+ * Seal the shared transform output into Fusion's versioned envelopes.
+ *
+ * Fusion v4 compacts only the child-facing projection entries. Ledger rows are
+ * carried through unchanged, so the ledger root commits to exactly the same
+ * omitted payload records before and after tuple encoding. Golden tests pin the
+ * new canonical-input bytes and the unchanged ledger bytes.
+ */
+function sealFusionProjection(
+  projected: ProjectedConversationV2,
+  source: FusionSource,
+  branchFilter: FusionBranchFilterDescriptor,
+): { projection: FusionConversationProjectionV3; ledger: FusionContextOmissionLedgerV2 } {
+  const entries = compactFusionProjectionEntries(projected.entries);
+  return {
+    projection: {
+      policy: policyDescriptor(source),
+      branch_filter: branchFilter,
+      entries,
+      accounting: {
+        ...projected.accounting,
+        omission_receipt_utf8_bytes: compactOmissionReceiptBytes(entries),
+      },
+    },
+    ledger: {
+      schema_version: FUSION_CONTEXT_LEDGER_SCHEMA_VERSION,
+      policy_id: contextPolicyId(source),
+      transform: FUSION_CONTEXT_TRANSFORM_ID,
+      entries: projected.ledger.entries,
+      projection_map: projected.ledger.projection_map,
+      root_sha256: projected.ledger.root_sha256,
+    },
+  };
+}
+
+/** Preserved public entry point; delegates to the shared frozen transform. */
+export function projectFusionConversation(
+  messages: readonly Message[],
+  source: FusionSource,
+  branchFilter: FusionBranchFilterDescriptor,
+): { projection: FusionConversationProjectionV3; ledger: FusionContextOmissionLedgerV2 } {
+  return sealFusionProjection(projectVisibleConversationV2(messages), source, branchFilter);
+}
+
+export function buildFusionCanonicalInput(
+  ctx: FusionContextSource,
+  options: BuildFusionCanonicalInputOptions,
+): BuiltFusionCanonicalInput {
+  if (options.request.trim().length === 0) {
+    throw new FusionError('fusion request must not be blank', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const workflow = options.workflow ?? 'reason';
+  if (workflow !== 'reason') {
+    throw new FusionError('parent session projection is available only to the reason workflow', {
+      code: 'context_capture_failed',
+      childCreated: false,
+    });
+  }
+  const toolName = options.toolName ?? FUSION_REASON_TOOL_NAME;
+  const snapshotOptions: ParentSnapshotOptions = {
+    toolName,
+    excludeActiveToolCallLeaf: options.source === 'tool',
+  };
+  if (options.toolCallId !== undefined) snapshotOptions.toolCallId = options.toolCallId;
+  const snapshot = snapshotParentConversation(ctx, snapshotOptions);
+  const branchFilter: FusionBranchFilterDescriptor = {
+    id: FUSION_BRANCH_FILTER_ID,
+    tool_name: toolName,
+    tool_call_id: options.source === 'tool' ? (options.toolCallId ?? null) : null,
+    active_tool_call_leaf_excluded: snapshot.activeToolCallLeafExcluded,
+  };
+  const projected = projectFusionConversation(snapshot.messages, options.source, branchFilter);
+  const request: FusionCanonicalRequestV3 = {
+    source: options.source,
+    authority: requestAuthority(options.source),
+    text: options.request,
+    sha256: sha256Text(options.request),
+  };
+  const input: FusionSessionProjectionCanonicalInputV5 = {
+    schema_version: FUSION_INPUT_SCHEMA_VERSION,
+    workflow: 'reason',
+    cwd: ctx.cwd,
+    request,
+    system_prompt: ctx.getSystemPrompt(),
+    conversation_projection: projected.projection,
+    context: {
+      kind: 'session_projection',
+      policy_id: 'fusion-session-projection-v1',
+      system_prompt: ctx.getSystemPrompt(),
+      conversation_projection: projected.projection,
+    },
+  };
+  return {
+    input,
+    serialized: canonicalJson(input),
+    ledger: projected.ledger,
+    transcriptLeafId: snapshot.leafId,
+  };
+}