Attach outputs to nodes; rework solver union/variant model

Move tool output specs from AppMeta to the NodeMeta of the node that owns
them. The host node is the implicit trigger; gating is read off its tree
position by gateContext (host -> root). Replaces an earlier, never-shipped
AppMeta-flat design whose pass-coupling and dual name-index made
simplify/flatten/canonicalize all name-aware.

IR + passes
  - NodeMeta.outputs?: Output[]; Output gains optional? (frontend-declared,
    ORed with structural gating). AppMeta.outputs and Output.triggers gone.
  - simplify.mergeMeta concatenates outputs (and carries defaultValue);
    PassContext / collectReferencedNames / name-preservation.test.ts gone.
    flatten/canonicalize/remove-empty back to plain apply(expr).

Solver
  - ResolvedOutput.branchCondition is GateAtom[][]: { present, binding } or
    { variant, binding, variant }. Backends read the predicate kind off
    bindings.get(binding).type.kind.
  - SolveOptions.appMeta removed; solve(expr) finds outputs in the IR.
  - resolve is the single node -> binding map (no side-channel). Variant
    gates recovered via alts.indexOf(prev) -> union.variants[i].name.
  - Union/variant rework: tagVariant -> pure taggedVariantType; fixes the
    field name for collapsed single-field arms (seq(lit("convert"), path{src})
    now boxes as { src: scalar }, not { convert: scalar }). nodeToVariant
    side-channel and allLiterals special-case dropped. Multi-field arm
    bindings are retyped explicitly so they agree with the union.

Boutiques frontend
  - attachOutputs runs inside parseDescriptor so subcommand descriptors
    carry their own outputs. pickOutputHost = LCA of referenced input
    nodes (real LCA, not the earlier "single -> node, else root"
    heuristic); literal-only or unresolved refs -> root. Refs to optional
    inputs get fallback: "". output-files[].optional -> Output.optional.

Backend
  - backend/resolve-output-tokens.ts: planOutput / outputGuard /
    GuardClause / OutputEmitPlan. Storage-model-agnostic; no codegen
    changes yet (Phase 3.5 will wire it in).

479 tests pass.

Author: nx10

packages/core/src/backend/index.ts

@@ -8,6 +8,18 @@ export { collectNamedTypes, resolveTypeName } from "./collect-named-types.js";
 export { findDoc } from "./find-doc.js";
 export { findStructNode } from "./find-struct-node.js";
 export { resolveFieldBinding } from "./resolve-field-binding.js";
+export type {
+  GuardClause,
+  OutputCardinality,
+  OutputEmitPlan,
+  OutputGuard,
+} from "./resolve-output-tokens.js";
+export {
+  compactTokens,
+  outputCardinality,
+  outputGuard,
+  planOutput,
+} from "./resolve-output-tokens.js";
 export { Scope } from "./scope.js";
 export type { JsonSchema } from "./schema/index.js";
 export { generateSchema, JsonSchemaBackend } from "./schema/index.js";

packages/core/src/backend/resolve-output-tokens.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+import type { ResolvedOutput, ResolvedToken } from "../bindings/index.js";
+import {
+  compactTokens,
+  outputCardinality,
+  outputGuard,
+  planOutput,
+} from "./resolve-output-tokens.js";
+
+function output(overrides: Partial<ResolvedOutput> = {}): ResolvedOutput {
+  return {
+    name: "out",
+    tokens: [],
+    branchCondition: [[]],
+    listScope: [],
+    optional: false,
+    ...overrides,
+  };
+}
+
+describe("outputCardinality", () => {
+  it("returns 'always' when not optional and no listScope", () => {
+    expect(outputCardinality(output())).toBe("always");
+  });
+
+  it("returns 'optional' when optional and no listScope", () => {
+    expect(outputCardinality(output({ optional: true }))).toBe("optional");
+  });
+
+  it("returns 'list' when listScope present and not optional", () => {
+    expect(outputCardinality(output({ listScope: ["b1"] }))).toBe("list");
+  });
+
+  it("returns 'list-optional' when both listScope and optional", () => {
+    expect(outputCardinality(output({ listScope: ["b1"], optional: true }))).toBe(
+      "list-optional",
+    );
+  });
+});
+
+describe("outputGuard", () => {
+  it("returns 'always' for empty branchCondition", () => {
+    expect(outputGuard(output({ branchCondition: [] }))).toEqual({ kind: "always" });
+  });
+
+  it("returns 'always' for single empty path", () => {
+    expect(outputGuard(output({ branchCondition: [[]] }))).toEqual({ kind: "always" });
+  });
+
+  it("returns 'any-of' for non-empty branchCondition", () => {
+    const guard = outputGuard(
+      output({
+        branchCondition: [
+          [{ kind: "present", binding: "b1" }],
+          [
+            { kind: "present", binding: "b2" },
+            { kind: "variant", binding: "u1", variant: "add" },
+          ],
+        ],
+      }),
+    );
+    expect(guard).toEqual({
+      kind: "any-of",
+      clauses: [
+        { atoms: [{ kind: "present", binding: "b1" }] },
+        {
+          atoms: [
+            { kind: "present", binding: "b2" },
+            { kind: "variant", binding: "u1", variant: "add" },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("does NOT collapse a single non-empty path", () => {
+    const guard = outputGuard(output({ branchCondition: [[{ kind: "present", binding: "b1" }]] }));
+    expect(guard).toEqual({
+      kind: "any-of",
+      clauses: [{ atoms: [{ kind: "present", binding: "b1" }] }],
+    });
+  });
+});
+
+describe("compactTokens", () => {
+  it("merges consecutive literal tokens", () => {
+    const tokens: ResolvedToken[] = [
+      { kind: "literal", value: "a" },
+      { kind: "literal", value: "b" },
+      { kind: "literal", value: "c" },
+    ];
+    expect(compactTokens(tokens)).toEqual([{ kind: "literal", value: "abc" }]);
+  });
+
+  it("preserves refs and merges literals around them", () => {
+    const tokens: ResolvedToken[] = [
+      { kind: "literal", value: "pre-" },
+      { kind: "literal", value: "fix" },
+      { kind: "ref", binding: "b1" },
+      { kind: "literal", value: ".out" },
+    ];
+    expect(compactTokens(tokens)).toEqual([
+      { kind: "literal", value: "pre-fix" },
+      { kind: "ref", binding: "b1" },
+      { kind: "literal", value: ".out" },
+    ]);
+  });
+
+  it("returns empty array for empty input", () => {
+    expect(compactTokens([])).toEqual([]);
+  });
+});
+
+describe("planOutput", () => {
+  it("packages cardinality, guard, listScope, and compacted tokens", () => {
+    const resolved = output({
+      name: "log",
+      tokens: [
+        { kind: "literal", value: "log-" },
+        { kind: "literal", value: "file" },
+        { kind: "ref", binding: "b1" },
+      ],
+      branchCondition: [[{ kind: "present", binding: "b2" }]],
+      listScope: ["b3"],
+      optional: true,
+    });
+    const plan = planOutput(resolved);
+    expect(plan.name).toBe("log");
+    expect(plan.cardinality).toBe("list-optional");
+    expect(plan.guard).toEqual({
+      kind: "any-of",
+      clauses: [{ atoms: [{ kind: "present", binding: "b2" }] }],
+    });
+    expect(plan.listScope).toEqual(["b3"]);
+    expect(plan.tokens).toEqual([
+      { kind: "literal", value: "log-file" },
+      { kind: "ref", binding: "b1" },
+    ]);
+    expect(plan.resolved).toBe(resolved);
+  });
+
+  it("preserves ref token's stripExtensions and fallback through compacting", () => {
+    const resolved = output({
+      tokens: [
+        { kind: "ref", binding: "b1", stripExtensions: [".nii"], fallback: "x" },
+      ],
+    });
+    const plan = planOutput(resolved);
+    expect(plan.tokens[0]).toEqual({
+      kind: "ref",
+      binding: "b1",
+      stripExtensions: [".nii"],
+      fallback: "x",
+    });
+  });
+});

packages/core/src/backend/resolve-output-tokens.ts

@@ -0,0 +1,105 @@
+import type { BindingId, GateAtom, ResolvedOutput, ResolvedToken } from "../bindings/index.js";
+
+/**
+ * Cardinality of a resolved output: how many path values it produces and
+ * whether the user must handle a null/missing case.
+ *
+ * - `always`: exactly one path, never null. Type as `path`.
+ * - `optional`: zero or one path. Type as `path | null`.
+ * - `list`: zero or more paths (per listScope iteration). Type as `path[]`.
+ * - `list-optional`: zero or more paths but the whole output may be skipped.
+ *   Type as `path[] | null`.
+ */
+export type OutputCardinality = "always" | "optional" | "list" | "list-optional";
+
+/** Compute cardinality from `listScope` and `optional` on a ResolvedOutput. */
+export function outputCardinality(resolved: ResolvedOutput): OutputCardinality {
+  const isList = resolved.listScope.length > 0;
+  if (isList && resolved.optional) return "list-optional";
+  if (isList) return "list";
+  if (resolved.optional) return "optional";
+  return "always";
+}
+
+/**
+ * Guard expression controlling whether the output emits.
+ *
+ * `always` means the output emits unconditionally (no gating ancestors).
+ * `any-of` is a disjunction of conjunctions: emit if any clause's atoms all
+ * hold. Each `GateAtom` is either `present` (the bound parameter is non-null /
+ * `true` / `> 0`, per its binding's type) or `variant` (a union selected a
+ * particular arm).
+ */
+export type OutputGuard =
+  | { kind: "always" }
+  | { kind: "any-of"; clauses: GuardClause[] };
+
+export interface GuardClause {
+  /** All of these conditions must hold for this clause to fire. */
+  atoms: GateAtom[];
+}
+
+/**
+ * Reduce `branchCondition` to a guard expression. An empty branchCondition or
+ * a single empty path collapses to `always`; otherwise we keep the disjunction
+ * of conjunctions.
+ */
+export function outputGuard(resolved: ResolvedOutput): OutputGuard {
+  const bc = resolved.branchCondition;
+  if (bc.length === 0) return { kind: "always" };
+  if (bc.length === 1 && bc[0]!.length === 0) return { kind: "always" };
+  return {
+    kind: "any-of",
+    clauses: bc.map((atoms) => ({ atoms })),
+  };
+}
+
+/**
+ * Merge consecutive literal tokens. Backends that emit string concatenation
+ * benefit from a shorter token stream; backends that template each token
+ * individually can ignore this and use `resolved.tokens` directly.
+ */
+export function compactTokens(tokens: ResolvedToken[]): ResolvedToken[] {
+  const out: ResolvedToken[] = [];
+  for (const tok of tokens) {
+    const last = out[out.length - 1];
+    if (tok.kind === "literal" && last && last.kind === "literal") {
+      out[out.length - 1] = { kind: "literal", value: last.value + tok.value };
+    } else {
+      out.push(tok);
+    }
+  }
+  return out;
+}
+
+/**
+ * Single point of entry: convert a ResolvedOutput to a plan whose fields map
+ * directly to the codegen patterns described in `memory/design_outputs.md`.
+ *
+ * Backends typically need:
+ * - `cardinality` to decide the field type (`path | null` vs `path[]`, etc.).
+ * - `guard` to render the if-condition gating the output assignment.
+ * - `listScope` to render the for-loop when iterating per repeat-binding.
+ * - `tokens` to render the path expression. Refs with a `fallback` should be
+ *   emitted as `ref ?? fallback` (or the language equivalent) so unreachable
+ *   refs naturally resolve to their fallback at runtime.
+ */
+export interface OutputEmitPlan {
+  name: string;
+  cardinality: OutputCardinality;
+  guard: OutputGuard;
+  listScope: BindingId[];
+  tokens: ResolvedToken[];
+  resolved: ResolvedOutput;
+}
+
+export function planOutput(resolved: ResolvedOutput): OutputEmitPlan {
+  return {
+    name: resolved.name,
+    cardinality: outputCardinality(resolved),
+    guard: outputGuard(resolved),
+    listScope: resolved.listScope,
+    tokens: compactTokens(resolved.tokens),
+    resolved,
+  };
+}

packages/core/src/bindings/binding.ts

@@ -1,4 +1,5 @@
 import type { Expr } from "../ir/index.js";
+import type { ResolvedOutput } from "./resolved-output.js";
 import type { BoundType } from "./types.js";
 
 export type BindingId = string;
@@ -12,9 +13,24 @@ export interface Binding {
 
 export type BindingRegistry = Map<BindingId, Binding>;
 
+export type OutputDiagnosticLevel = "error" | "warning";
+
+export interface OutputDiagnostic {
+  output: string;
+  message: string;
+  level: OutputDiagnosticLevel;
+}
+
+export interface OutputValidationResult {
+  errors: OutputDiagnostic[];
+  warnings: OutputDiagnostic[];
+}
+
 export interface SolveResult {
   bindings: BindingRegistry;
   resolve: (node: Expr) => Binding | undefined;
+  outputs: ResolvedOutput[];
+  outputDiagnostics: OutputValidationResult;
 }
 
 export function createRegistry(): BindingRegistry {

packages/core/src/bindings/index.ts

@@ -1,4 +1,13 @@
-export type { Binding, BindingId, BindingRegistry, SolveResult } from "./binding.js";
+export type {
+  Binding,
+  BindingId,
+  BindingRegistry,
+  OutputDiagnostic,
+  OutputDiagnosticLevel,
+  OutputValidationResult,
+  SolveResult,
+} from "./binding.js";
 export { createRegistry } from "./binding.js";
+export type { GateAtom, ResolvedOutput, ResolvedToken } from "./resolved-output.js";
 export type { BoundType, BoundVariant } from "./types.js";
 export { formatSolveResult } from "./format.js";

packages/core/src/bindings/resolved-output.ts

@@ -0,0 +1,49 @@
+import type { Documentation, MediaTypeIdentifier } from "../ir/types.js";
+import type { BindingId } from "./binding.js";
+
+/**
+ * Resolved token in an output path template. Refs point at solved bindings;
+ * literals are emitted verbatim.
+ */
+export type ResolvedToken =
+  | { kind: "literal"; value: string }
+  | {
+      kind: "ref";
+      binding: BindingId;
+      stripExtensions?: string[];
+      fallback?: string;
+    };
+
+/**
+ * One condition that must hold for an output to fire.
+ *
+ * - `present`: the bound parameter is "active" - non-null for an `optional`,
+ *   `true` for a `bool`, `> 0` for a `count`. The backend reads the predicate
+ *   off `bindings.get(binding).type.kind`.
+ * - `variant`: the union bound by `binding` selected the variant named
+ *   `variant` (the output is hosted inside that alternative arm).
+ */
+export type GateAtom =
+  | { kind: "present"; binding: BindingId }
+  | { kind: "variant"; binding: BindingId; variant: string };
+
+/**
+ * Output specification translated against the binding registry.
+ *
+ * - `branchCondition`: disjunction (outer) of conjunctions (inner) of
+ *   `GateAtom`s. An output attached to a single host node has exactly one
+ *   disjunct - the host's branch path; the disjunctive shape is kept so
+ *   several hosts producing the same output can be merged later.
+ * - `listScope`: repeat-ancestor (`list`) bindings of the host. The output
+ *   emits once per iteration of the innermost listed binding.
+ * - `optional`: true when the branch path is non-empty (the host is gated).
+ */
+export interface ResolvedOutput {
+  name: string;
+  doc?: Documentation;
+  tokens: ResolvedToken[];
+  branchCondition: GateAtom[][];
+  listScope: BindingId[];
+  optional: boolean;
+  mediaTypes?: MediaTypeIdentifier[];
+}