@styx-api/core 0.7.0 → 0.8.0

package/src/backend/python/python.ts

@@ -378,6 +378,19 @@ export function buildEmitModel(
 }
 
 export function generatePython(ctx: CodegenContext, packageScope?: Scope): string {
+  return generatePythonModule(ctx, packageScope).code;
+}
+
+/**
+ * Emit the module and, alongside it, the dispatch entrypoint carrying the
+ * *scope-registered* execute-function name. Computing the entrypoint here (not
+ * via the scope-blind `appEntrypoint`) keeps the suite dispatcher in sync with
+ * the actual emitted symbol when a shared package scope suffix-bumps a collision.
+ */
+function generatePythonModule(
+  ctx: CodegenContext,
+  packageScope?: Scope,
+): { code: string; entrypoint: AppEntrypoint | undefined } {
   const cb = new CodeBuilder("    ");
   // A package-shared scope keeps top-level names unique across every tool in the
   // suite's `from .x import *` re-exports; without one a per-tool scope suffices.
@@ -403,9 +416,7 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
   // Every tool emits an Outputs object: at minimum the synthetic `root` output
   // directory (output_file(".")), plus any declared file/mutable outputs and
   // stdout/stderr stream fields. OutputPathType is therefore always imported.
-  const emitOutputs = true;
-
-  emitImports(cb, true);
+  emitImports(cb);
   cb.blank();
 
   emitMetadata(ctx, names.metadata, cb);
@@ -413,12 +424,10 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
 
   emitTypeDeclarations(typeDecls, namedTypes, ctx, cb, names.params, rootTypeTag);
 
-  if (emitOutputs) {
-    emitOutputsClass(ctx, names.outputs, cb);
-    cb.blank();
-  }
+  emitOutputsClass(ctx, names.outputs, cb);
+  cb.blank();
 
-  if (emitOutputs && needsStripExtensionsHelper(ctx)) {
+  if (needsStripExtensionsHelper(ctx)) {
     emitStripExtensionsHelper(cb);
     cb.blank();
   }
@@ -457,10 +466,8 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
   emitBuildCargs(ctx, rootType, paramsType, names.cargs, cb);
   cb.blank();
 
-  if (emitOutputs) {
-    emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
-    cb.blank();
-  }
+  emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
+  cb.blank();
 
   // Dict-style execute function. For struct roots it's the internal
   // `<tool>_execute`; for other roots it doubles as the user-facing wrapper.
@@ -471,8 +478,8 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
     executeName,
     names.metadata,
     names.cargs,
-    emitOutputs ? names.outputsFn : undefined,
-    emitOutputs ? names.outputs : undefined,
+    names.outputsFn,
+    names.outputs,
     names.validate,
     streamFieldIds(ctx),
     cb,
@@ -487,7 +494,7 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
       names.wrapper,
       names.paramsFn,
       names.execute,
-      emitOutputs ? names.outputs : undefined,
+      names.outputs,
       cb,
     );
     cb.blank();
@@ -497,10 +504,10 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
   // module's stdlib/styxdefs imports.
   const publicSymbols = [
     names.params,
-    ...(emitOutputs ? [names.outputs] : []),
+    names.outputs,
     names.metadata,
     names.cargs,
-    ...(emitOutputs ? [names.outputsFn] : []),
+    names.outputsFn,
     ...(rootIsStruct ? [names.paramsFn, names.execute] : []),
     ...nestedFactories.map((nf) => nf.funcName),
     names.validate,
@@ -512,7 +519,14 @@ export function generatePython(ctx: CodegenContext, packageScope?: Scope): strin
   });
   cb.line("]");
 
-  return cb.toString();
+  // `executeName` is the scope-registered symbol actually emitted above, so the
+  // dispatcher references the real name even after a collision suffix-bump.
+  const appId = ctx.app?.id;
+  const pkg = ctx.package?.name;
+  const entrypoint: AppEntrypoint | undefined =
+    appId && pkg ? { type: `${pkg}/${appId}`, executeFn: executeName } : undefined;
+
+  return { code: cb.toString(), entrypoint };
 }
 
 /**
@@ -529,6 +543,10 @@ export function appModuleName(meta: AppMeta | undefined): string {
  * The dispatch entrypoint for one app: its root `@type` (`<package>/<app>`) and
  * the dict-style execute function name. Returns undefined when the id or package
  * is unknown (no stable `@type`), so the app is left out of the suite dispatcher.
+ *
+ * Note: this recomputes the execute name without a package scope, so it reflects
+ * the un-bumped name. The emitter (`emitApp`) instead takes the entrypoint from
+ * the scope-aware emit pass; use that path when a shared package scope is in play.
  */
 export function appEntrypoint(ctx: CodegenContext): AppEntrypoint | undefined {
   const appId = ctx.app?.id;
@@ -599,10 +617,14 @@ function emitPackageDispatch(cb: CodeBuilder, dispatch: AppEntrypoint[]): void {
       }
     });
     cb.line("}");
-    cb.line('_fn = _dispatch.get(params["@type"])');
+    // `.get` (not `params["@type"]`) so a missing discriminant surfaces the
+    // clean ValueError below instead of a bare KeyError. The `is not None` guard
+    // also narrows `_type` away from None for the typed `_dispatch.get`.
+    cb.line('_type = params.get("@type")');
+    cb.line("_fn = _dispatch.get(_type) if _type is not None else None");
     cb.line("if _fn is None:");
     cb.indent(() => {
-      cb.line(`raise ValueError(f"No tool registered for @type {params['@type']!r}")`);
+      cb.line(`raise ValueError(f"No tool registered for @type {_type!r}")`);
     });
     cb.line("return _fn(params, runner)");
   });
@@ -613,11 +635,13 @@ export class PythonBackend implements Backend {
   readonly target = "python";
 
   emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp {
-    const code = generatePython(ctx, scope);
+    // Take the entrypoint from the same pass that emitted the module, so its
+    // execute-function name reflects any shared-scope suffix-bump.
+    const { code, entrypoint } = generatePythonModule(ctx, scope);
     const fileName = `${appModuleName(ctx.app)}.py`;
     return {
       meta: ctx.app,
-      entrypoint: appEntrypoint(ctx),
+      entrypoint,
       files: new Map([[fileName, code]]),
       errors: [],
       warnings: [],

package/src/backend/python/validate-emit.ts

@@ -146,7 +146,10 @@ function emitValue(
       const itemNode = findRepeatNode(node)?.attrs.node;
       const elem = e.scope.add("e");
       e.cb.line(`for ${elem} in ${valueExpr}:`);
-      e.cb.indent(() => emitValue(e, type.item, itemNode, wireKey, elem, expected));
+      // Report the element type (e.g. `int`), not the list type (`list[int]`).
+      e.cb.indent(() =>
+        emitValue(e, type.item, itemNode, wireKey, elem, expectedType(e, type.item)),
+      );
       return;
     }
     case "struct": {

package/src/backend/resolve-output-tokens.ts

@@ -1,80 +1,4 @@
-import type {
-  BindingRegistry,
-  GateAtom,
-  OutputScope,
-  ResolvedOutput,
-  ResolvedToken,
-} from "../bindings/index.js";
 import { outputGate } from "../bindings/index.js";
 
 // Re-export the core helper so backends have a single entry point.
 export { outputGate };
-
-/**
- * Compact 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 `output.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;
-}
-
-/**
- * One output ready for codegen. `gate` is the wrapper sequence (outermost
- * first); the backend renders each atom as the appropriate scope-introducing
- * statement, then emits the path expression inside the innermost layer.
- */
-export interface OutputEmitPlan {
-  name: string;
-  gate: GateAtom[];
-  tokens: ResolvedToken[];
-  resolved: ResolvedOutput;
-}
-
-export function planOutput(
-  scopeGate: GateAtom[],
-  output: ResolvedOutput,
-  bindings: BindingRegistry,
-): OutputEmitPlan {
-  return {
-    name: output.name,
-    gate: outputGate(scopeGate, output, bindings),
-    tokens: compactTokens(output.tokens),
-    resolved: output,
-  };
-}
-
-/**
- * Does the output have any conditional wrapper? Equivalent to "is at least one
- * atom a `present` or `variant`?". `iter` alone means the output emits a list
- * and is not conditionally absent.
- */
-export function isGated(plan: OutputEmitPlan): boolean {
-  return plan.gate.some((a) => a.kind === "present" || a.kind === "variant");
-}
-
-/** Does the output iterate (emit zero-or-more values)? */
-export function isIterated(plan: OutputEmitPlan): boolean {
-  return plan.gate.some((a) => a.kind === "iter");
-}
-
-/**
- * Convenience for backends emitting all outputs of a scope at once. The caller
- * provides the scope's gate (typically `bindings.get(scope.scope)?.gate ?? []`).
- */
-export function planScope(
-  scope: OutputScope,
-  scopeGate: GateAtom[],
-  bindings: BindingRegistry,
-): OutputEmitPlan[] {
-  return scope.outputs.map((output) => planOutput(scopeGate, output, bindings));
-}

package/src/backend/typescript/arg-builder.ts

@@ -1,5 +1,5 @@
 import type { Binding, BindingId, BoundType, BoundVariant } from "../../bindings/index.js";
-import { collectFieldInfo } from "../collect-field-info.js";
+import { collectDefaults, rootFieldDefault } from "../field-defaults.js";
 import type { Expr } from "../../ir/index.js";
 import type { CodegenContext } from "../../manifest/index.js";
 import { CodeBuilder } from "../code-builder.js";
@@ -92,14 +92,6 @@ function accessOf(binding: Binding, arg: ArgContext): string {
  * carrying a Boutiques default. Restricted to single-segment (root) field access
  * so a nested field can never accidentally pick up a same-named root default.
  */
-function rootFieldDefault(
-  binding: Binding,
-  defaults: ReadonlyMap<string, string>,
-): string | undefined {
-  const a = binding.access;
-  if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-  return undefined;
-}
 
 /**
  * Render a binding's access for an UNCONDITIONAL value read (terminal, repeat
@@ -113,20 +105,6 @@ function readAccess(binding: Binding, arg: ArgContext): string {
   return def !== undefined ? `(${accessOf(binding, arg)} ?? ${def})` : accessOf(binding, arg);
 }
 
-/** Build the field-name -> rendered-default map for a struct root (else empty).
- * Includes only non-optional defaulted fields (optional fields are
- * presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults(ctx: CodegenContext, rootType?: BoundType): Map<string, string> {
-  const out = new Map<string, string>();
-  if (rootType?.kind !== "struct") return out;
-  for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-    if (fi.defaultValue === undefined) continue;
-    if (rootType.fields[name]?.kind === "optional") continue;
-    out.set(name, renderTsLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 // -- Recursive descent --
 
 let loopVarCounter = 0;
@@ -142,7 +120,7 @@ export function buildArgs(rootExpr: Expr, ctx: CodegenContext, rootType?: BoundT
   const initialCtx: ArgContext = {
     joinDepth: 0,
     loopVars: new Map(),
-    defaults: collectDefaults(ctx, rootType),
+    defaults: collectDefaults(ctx, renderTsLiteral, rootType),
   };
   return walk(rootExpr, ctx, initialCtx);
 }

package/src/backend/typescript/emit.ts

@@ -10,7 +10,10 @@ import { collectFieldInfo, resolveTypeName } from "./types.js";
 
 export function emitJsDoc(cb: CodeBuilder, description?: string): void {
   if (!description) return;
-  const lines = description.split("\n");
+  // Escape `*/` so a description containing it can't terminate the block comment
+  // early (`*\/` is not a comment terminator; the backslash is inert in comments).
+  const safe = description.replace(/\*\//g, "*\\/");
+  const lines = safe.split("\n");
   if (lines.length === 1) {
     cb.line(`/** ${lines[0]} */`);
   } else {
@@ -22,9 +25,9 @@ export function emitJsDoc(cb: CodeBuilder, description?: string): void {
   }
 }
 
-export function emitImports(cb: CodeBuilder, emitOutputs: boolean): void {
-  const inputs = ["Runner", "Execution", "Metadata", "InputPathType"];
-  if (emitOutputs) inputs.push("OutputPathType");
+export function emitImports(cb: CodeBuilder): void {
+  // Every tool emits an Outputs object, so OutputPathType is always needed.
+  const inputs = ["Runner", "Execution", "Metadata", "InputPathType", "OutputPathType"];
   cb.line(`import type { ${inputs.join(", ")} } from "styxdefs";`);
   cb.line('import { getGlobalRunner, StyxValidationError } from "styxdefs";');
 }

package/src/backend/typescript/outputs-emit.ts

@@ -1,12 +1,6 @@
-import type {
-  Binding,
-  BindingId,
-  BoundType,
-  GateAtom,
-  ResolvedToken,
-} from "../../bindings/index.js";
+import type { BindingId, BoundType, GateAtom, ResolvedToken } from "../../bindings/index.js";
 import { outputGate } from "../../bindings/index.js";
-import { collectFieldInfo } from "../collect-field-info.js";
+import { collectDefaults, rootFieldDefault } from "../field-defaults.js";
 import type { CodegenContext } from "../../manifest/index.js";
 import { CodeBuilder } from "../code-builder.js";
 import {
@@ -18,6 +12,7 @@ import {
   rootOutput,
   streamFields,
 } from "../collect-output-fields.js";
+import { unionIsMixed, variantAtomUnion } from "../union-variants.js";
 import { emitJsDoc, renderAccess, tsPropAccess } from "./emit.js";
 import { renderTsLiteral } from "./typemap.js";
 
@@ -97,32 +92,6 @@ interface OutputEmitCtx {
   defaults: ReadonlyMap<string, string>;
 }
 
-/** The rendered default for a binding iff it is a root-level defaulted field. */
-function rootFieldDefault(
-  binding: Binding | undefined,
-  defaults: ReadonlyMap<string, string>,
-): string | undefined {
-  if (!binding) return undefined;
-  const a = binding.access;
-  if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-  return undefined;
-}
-
-/** Build the field-name -> rendered-default map for the struct root (else empty).
- * Includes only non-optional defaulted fields (optional fields are
- * presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults(ctx: CodegenContext): Map<string, string> {
-  const out = new Map<string, string>();
-  const rootType = ctx.resolve(ctx.expr)?.type;
-  if (rootType?.kind !== "struct") return out;
-  for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-    if (fi.defaultValue === undefined) continue;
-    if (rootType.fields[name]?.kind === "optional") continue;
-    out.set(name, renderTsLiteral(fi.defaultValue));
-  }
-  return out;
-}
-
 /**
  * Render one output's wrapper stack and emit the assignment inside the
  * innermost wrapper. Nesting is done via recursive callbacks so the
@@ -201,10 +170,17 @@ function renderWrapperOpen(atom: GateAtom, ec: OutputEmitCtx): WrapperRender {
   }
   if (atom.kind === "variant") {
     const access = bindingAccess(atom.binding, ec);
-    return {
-      open: `if (${access}["@type"] === ${JSON.stringify(atom.variant)}) {`,
-      close: `}`,
-    };
+    const check = `${access}["@type"] === ${JSON.stringify(atom.variant)}`;
+    // A mixed union (`0 | Struct`) only carries `@type` on its struct arms; guard
+    // on the object shape first so TS narrows off the bare-literal arm before the
+    // subscript (which would otherwise be a "property does not exist" error).
+    // Mirrors the cargs builder and validator. Pure-struct unions need no guard.
+    const union = variantAtomUnion(atom, ec.ctx.bindings);
+    const cond =
+      union && unionIsMixed(union)
+        ? `typeof ${access} === "object" && ${access} !== null && ${check}`
+        : check;
+    return { open: `if (${cond}) {`, close: `}` };
   }
   // present
   const binding = ec.ctx.bindings.get(atom.binding);
@@ -321,7 +297,7 @@ export function emitBuildOutputs(
       ctx,
       iter: new Map(),
       fieldShapes: new Map(fields.map((f) => [f.id, f.shape])),
-      defaults: collectDefaults(ctx),
+      defaults: collectDefaults(ctx, renderTsLiteral),
     };
 
     // Initialize the outputs object with defaults so wrapper code can assign or

package/src/backend/typescript/typemap.ts

@@ -1,5 +1,13 @@
 import type { BoundType } from "../../bindings/index.js";
 
+// A valid TS identifier can be an unquoted object key; anything else (e.g. a
+// wire key like `4d_input`) must be quoted. Kept local to avoid a cycle with
+// emit.ts (which imports this module).
+const TS_IDENT_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function objKey(key: string): string {
+  return TS_IDENT_RE.test(key) ? key : JSON.stringify(key);
+}
+
 export function mapType(type: BoundType, resolve: (type: BoundType) => string | undefined): string {
   switch (type.kind) {
     case "scalar":
@@ -27,7 +35,7 @@ export function mapType(type: BoundType, resolve: (type: BoundType) => string |
       if (name) return name;
       const fields = Object.entries(type.fields)
         .filter(([, v]) => v.kind !== "literal")
-        .map(([k, v]) => `${k}: ${mapType(v, resolve)}`)
+        .map(([k, v]) => `${objKey(k)}: ${mapType(v, resolve)}`)
         .join("; ");
       return `{ ${fields} }`;
     }

package/src/backend/typescript/typescript.ts

@@ -256,6 +256,19 @@ export function buildEmitModel(
 }
 
 export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): string {
+  return generateTypeScriptModule(ctx, packageScope).code;
+}
+
+/**
+ * Emit the module and, alongside it, the dispatch entrypoint carrying the
+ * *scope-registered* execute-function name. Computing the entrypoint here (not
+ * via the scope-blind `appEntrypoint`) keeps the suite dispatcher in sync with
+ * the actual emitted symbol when a shared package scope suffix-bumps a collision.
+ */
+function generateTypeScriptModule(
+  ctx: CodegenContext,
+  packageScope?: Scope,
+): { code: string; entrypoint: AppEntrypoint | undefined } {
   const cb = new CodeBuilder("  ");
   // A package-shared scope keeps top-level names unique across every tool in the
   // suite barrel; without one (standalone emit) a per-tool scope is enough.
@@ -282,9 +295,7 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
   // Every tool emits an Outputs object: at minimum the synthetic `root` output
   // directory (outputFile(".")), plus any declared file/mutable outputs and
   // stdout/stderr stream fields. OutputPathType is therefore always imported.
-  const emitOutputs = true;
-
-  emitImports(cb, true);
+  emitImports(cb);
   cb.blank();
 
   emitMetadata(ctx, names.metadata, cb);
@@ -292,12 +303,10 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
 
   emitTypeDeclarations(typeDecls, namedTypes, ctx, names.params, appId, pkg, cb);
 
-  if (emitOutputs) {
-    emitOutputsInterface(ctx, names.outputs, cb);
-    cb.blank();
-  }
+  emitOutputsInterface(ctx, names.outputs, cb);
+  cb.blank();
 
-  if (emitOutputs && needsStripExtensionsHelper(ctx)) {
+  if (needsStripExtensionsHelper(ctx)) {
     emitStripExtensionsHelper(cb);
     cb.blank();
   }
@@ -327,10 +336,8 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
   emitBuildCargs(ctx, rootType, paramsType, names.cargs, cb);
   cb.blank();
 
-  if (emitOutputs) {
-    emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
-    cb.blank();
-  }
+  emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
+  cb.blank();
 
   // Dict-style execute function. For struct roots it's the internal
   // `<tool>Execute`; for other roots it doubles as the user-facing wrapper.
@@ -341,8 +348,8 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
     executeName,
     names.metadata,
     names.cargs,
-    emitOutputs ? names.outputsFn : undefined,
-    emitOutputs ? names.outputs : undefined,
+    names.outputsFn,
+    names.outputs,
     names.validate,
     streamFieldIds(ctx),
     cb,
@@ -357,13 +364,24 @@ export function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): s
       names.wrapper,
       names.paramsFn,
       names.execute,
-      emitOutputs ? names.outputs : undefined,
+      names.outputs,
       cb,
     );
     cb.blank();
   }
 
-  return cb.toString();
+  // `executeName` is the scope-registered symbol actually emitted above, so the
+  // dispatcher references the real name even after a collision suffix-bump. Guard
+  // on `ctx.package?.name` (not the destructured `pkg`, which falls back to
+  // "unknown") so a package-less app yields no entrypoint, as before.
+  const entryAppId = ctx.app?.id;
+  const entryPkg = ctx.package?.name;
+  const entrypoint: AppEntrypoint | undefined =
+    entryAppId && entryPkg
+      ? { type: `${entryPkg}/${entryAppId}`, executeFn: executeName }
+      : undefined;
+
+  return { code: cb.toString(), entrypoint };
 }
 
 /**
@@ -381,6 +399,9 @@ export function appModuleName(meta: AppMeta | undefined): string {
  * the dict-style execute function name. Returns undefined when the id or package
  * is unknown (no stable `@type`), so the app is left out of the suite dispatcher.
  */
+// Note: this recomputes the execute name without a package scope, so it reflects
+// the un-bumped name. The emitter (`emitApp`) instead takes the entrypoint from
+// the scope-aware emit pass; use that path when a shared package scope is in play.
 export function appEntrypoint(ctx: CodegenContext): AppEntrypoint | undefined {
   const appId = ctx.app?.id;
   const pkg = ctx.package?.name;
@@ -469,11 +490,13 @@ export class TypeScriptBackend implements Backend {
   readonly target = "typescript";
 
   emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp {
-    const code = generateTypeScript(ctx, scope);
+    // Take the entrypoint from the same pass that emitted the module, so its
+    // execute-function name reflects any shared-scope suffix-bump.
+    const { code, entrypoint } = generateTypeScriptModule(ctx, scope);
     const fileName = `${appModuleName(ctx.app)}.ts`;
     return {
       meta: ctx.app,
-      entrypoint: appEntrypoint(ctx),
+      entrypoint,
       files: new Map([[fileName, code]]),
       errors: [],
       warnings: [],

package/src/backend/typescript/validate-emit.ts

@@ -136,7 +136,10 @@ function emitValue(
       const itemNode = findRepeatNode(node)?.attrs.node;
       const elem = e.scope.add("el");
       e.cb.line(`for (const ${elem} of ${access}) {`);
-      e.cb.indent(() => emitValue(e, type.item, itemNode, wireKey, elem, expected));
+      // Report the element type (e.g. `int`), not the list type (`int[]`).
+      e.cb.indent(() =>
+        emitValue(e, type.item, itemNode, wireKey, elem, expectedType(e, type.item)),
+      );
       e.cb.line("}");
       return;
     }

package/src/backend/union-variants.ts

@@ -1,4 +1,44 @@
-import type { BoundType, BoundVariant } from "../bindings/index.js";
+import type { BindingRegistry, BoundType, BoundVariant, GateAtom } from "../bindings/index.js";
+
+/**
+ * Whether a union is "mixed": it has at least one non-struct (bare-literal) arm
+ * alongside its struct variants (e.g. ants `n4_correction = Literal[0] | N4On`).
+ *
+ * The `@type` discriminator only exists on the struct arms, so indexing
+ * `value["@type"]` on the union value is unsound (a type error, and a runtime
+ * KeyError if the literal arm is ever hit) until the value is narrowed to a
+ * struct at runtime. Backends that dispatch on `@type` must first emit a shape
+ * guard (Python `isinstance(value, dict)`, TS `typeof value === "object"`) when
+ * this is true; a pure-struct union (every arm a struct) needs no guard.
+ */
+export function unionIsMixed(unionType: Extract<BoundType, { kind: "union" }>): boolean {
+  return unionType.variants.some((v) => v.type.kind !== "struct");
+}
+
+/**
+ * The union type bound by a `variant` gate atom, if the atom's binding resolves
+ * to a union - used by the outputs emitters to decide whether the variant gate
+ * needs a mixed-union shape guard before its `@type` check. Returns `undefined`
+ * for a well-formed non-union (defensive; a variant atom should always name a
+ * union binding).
+ */
+export function variantAtomUnion(
+  atom: Extract<GateAtom, { kind: "variant" }>,
+  bindings: BindingRegistry,
+): Extract<BoundType, { kind: "union" }> | undefined {
+  return resolveUnion(bindings.get(atom.binding)?.type);
+}
+
+function resolveUnion(
+  type: BoundType | undefined,
+): Extract<BoundType, { kind: "union" }> | undefined {
+  if (!type) return undefined;
+  // An `optional<union>` binding can carry a variant gate (the optional wrapper
+  // and the union collapse onto one access path); unwrap to reach the union.
+  if (type.kind === "optional") return resolveUnion(type.inner);
+  if (type.kind === "union") return type;
+  return undefined;
+}
 
 /** A union's struct variant paired with its index into the union's `variants`
  * array (which stays parallel to the IR `alts` and the per-arm results a caller