@styx-api/core 0.4.0 → 0.5.1

package/src/backend/pydra/emit.ts

@@ -0,0 +1,318 @@
+import type { CodegenContext } from "../../manifest/index.js";
+import { CodeBuilder } from "../code-builder.js";
+import type { OutputField } from "../collect-output-fields.js";
+import { emitDocstring } from "../python/emit.js";
+import { pyStr, renderPyLiteral } from "../python/typemap.js";
+import type { TypedParam, TypedParamItem, TypedSpec } from "../typed-spec.js";
+
+/** Generated symbol names for one tool's pydra task module. */
+export interface PydraNames {
+  /** Styx Python module file stem to import the wrapper from (e.g. `_bet`). */
+  styxStem: string;
+  /** Task module file stem (e.g. `bet`). */
+  ifaceStem: string;
+  /** Task class name (e.g. `Bet`). */
+  cls: string;
+}
+
+/** Which optional imports the emitted module needs. */
+interface Imports {
+  typing: boolean;
+  attrs: boolean;
+  file: boolean;
+  directory: boolean;
+}
+
+/** A scalar enum's Python type: int when every choice is numeric, else str. */
+function enumScalar(choices: readonly (string | number)[] | undefined): string {
+  return (choices ?? []).every((c) => typeof c === "number") ? "int" : "str";
+}
+
+/** True when a parameter is a file path (a path scalar or a list of paths). */
+function isPathParam(p: TypedParam): boolean {
+  return p.kind === "path" || (p.kind === "list" && p.itemType?.kind === "path");
+}
+
+function itemTypeStr(item: TypedParamItem | undefined, imp: Imports): string {
+  if (!item) {
+    imp.typing = true;
+    return "ty.Any";
+  }
+  switch (item.kind) {
+    case "path":
+      imp.file = true;
+      return "File";
+    case "int":
+    case "count":
+      return "int";
+    case "float":
+      return "float";
+    case "str":
+      return "str";
+    case "bool":
+      return "bool";
+    case "enum":
+      return enumScalar(item.choices);
+    default:
+      imp.typing = true;
+      return "ty.Any";
+  }
+}
+
+/** Base (non-optional) Python type expression for a parameter. */
+function baseType(p: TypedParam, imp: Imports): string {
+  switch (p.kind) {
+    case "path":
+      imp.file = true;
+      return "File";
+    case "int":
+    case "count":
+      return "int";
+    case "float":
+      return "float";
+    case "str":
+      return "str";
+    case "bool":
+      return "bool";
+    case "enum":
+      return enumScalar(p.choices);
+    case "list":
+      return `list[${itemTypeStr(p.itemType, imp)}]`;
+    case "struct":
+    case "union":
+      imp.typing = true;
+      return "ty.Any";
+  }
+}
+
+/** Full input type, wrapping in `ty.Optional[...]` for an omittable-no-default field. */
+function inputType(p: TypedParam, imp: Imports): string {
+  const base = baseType(p, imp);
+  if (p.optional && !p.hasDefault) {
+    imp.typing = true;
+    return `ty.Optional[${base}]`;
+  }
+  return base;
+}
+
+/** An attrs validator enforcing numeric range / list-length bounds, or undefined. */
+function validatorExpr(p: TypedParam, imp: Imports): string | undefined {
+  const checks: string[] = [];
+  if (p.range) {
+    if (p.range.min !== undefined)
+      checks.push(`attrs.validators.ge(${renderPyLiteral(p.range.min)})`);
+    if (p.range.max !== undefined)
+      checks.push(`attrs.validators.le(${renderPyLiteral(p.range.max)})`);
+  }
+  if (p.listBounds) {
+    if (p.listBounds.min !== undefined)
+      checks.push(`attrs.validators.min_len(${p.listBounds.min})`);
+    if (p.listBounds.max !== undefined)
+      checks.push(`attrs.validators.max_len(${p.listBounds.max})`);
+  }
+  if (checks.length === 0) return undefined;
+  imp.attrs = true;
+  const inner = checks.length === 1 ? checks[0]! : `attrs.validators.and_(${checks.join(", ")})`;
+  // Skip validation for unset (attrs.NOTHING) / None values. A bare attrs
+  // validator runs against the NOTHING sentinel of an unset mandatory field and
+  // would crash construction; `_styx_optional` guards both NOTHING and None
+  // (attrs.validators.optional only guards None).
+  return `_styx_optional(${inner})`;
+}
+
+/** Help text: doc + degrade / media-type notes. */
+function helpText(p: TypedParam): string | undefined {
+  const parts: string[] = [];
+  if (p.doc) parts.push(p.doc);
+  if (p.kind === "struct" || p.kind === "union") parts.push("(nested configuration; pass a dict)");
+  if (p.mediaTypes && p.mediaTypes.length > 0) {
+    parts.push(`(media types: ${p.mediaTypes.join(", ")})`);
+  }
+  return parts.length > 0 ? parts.join(" ") : undefined;
+}
+
+/** Render a `python.arg(...)` field for one parameter. */
+function renderInputArg(p: TypedParam, imp: Imports): string {
+  const args: string[] = [`type=${inputType(p, imp)}`];
+  if (p.mandatory) {
+    // no default -> mandatory
+  } else if (p.optional && !p.hasDefault) {
+    args.push("default=None");
+  } else {
+    args.push(`default=${renderPyLiteral(p.default!)}`);
+  }
+  if (p.kind === "enum") {
+    args.push(`allowed_values=[${(p.choices ?? []).map((c) => renderPyLiteral(c)).join(", ")}]`);
+  }
+  const v = validatorExpr(p, imp);
+  if (v) args.push(`validator=${v}`);
+  const h = helpText(p);
+  if (h) args.push(`help=${pyStr(h)}`);
+  return `python.arg(${args.join(", ")})`;
+}
+
+/** Python type for an output field. `isRoot` is the synthetic output directory. */
+function outputType(f: OutputField, isRoot: boolean, imp: Imports): string {
+  if (f.shape.kind === "list") {
+    imp.file = true;
+    return "list[File]";
+  }
+  if (isRoot) {
+    imp.directory = true;
+    return "Directory";
+  }
+  imp.file = true;
+  if (f.shape.optional) {
+    imp.typing = true;
+    return "ty.Optional[File]";
+  }
+  return "File";
+}
+
+function renderOutputArg(f: OutputField, isRoot: boolean, imp: Imports): string {
+  const args: string[] = [`type=${outputType(f, isRoot, imp)}`];
+  if (f.doc) args.push(`help=${pyStr(f.doc)}`);
+  return `python.out(${args.join(", ")})`;
+}
+
+/**
+ * Emit the pydra task module for one tool: a `@python.define` task whose typed
+ * inputs/outputs carry rich constraints and whose body delegates execution to the
+ * co-emitted styx Python wrapper (Option B). Targets the post-rewrite
+ * `pydra.compose` API (pydra >= 1.0a, Python >= 3.11).
+ */
+export function emitPydraTask(ctx: CodegenContext, spec: TypedSpec, names: PydraNames): string {
+  const imp: Imports = { typing: false, attrs: false, file: false, directory: false };
+
+  // Render fields first so we know which imports are needed.
+  const inputEntries = spec.params.map((p) => ({
+    key: p.hostName,
+    expr: renderInputArg(p, imp),
+  }));
+  const outputEntries = spec.outputs.map((f, i) => ({
+    key: f.id,
+    expr: renderOutputArg(f, i === 0, imp),
+  }));
+  for (const s of spec.streams) {
+    // list[str] uses builtin generics - no extra import needed.
+    outputEntries.push({
+      key: s.id,
+      expr: `python.out(type=list[str]${s.doc ? `, help=${pyStr(s.doc)}` : ""})`,
+    });
+  }
+
+  // Path-typed inputs arrive from pydra as fileformats objects; the styx wrapper
+  // expects str/pathlib.Path, so convert them at the call boundary.
+  const needsPath = spec.params.some(isPathParam);
+
+  const cb = new CodeBuilder("    ");
+  cb.comment("This file was auto generated by Styx.", "# ");
+  cb.comment("Do not edit this file directly.", "# ");
+  cb.comment("Targets the pydra.compose API (pydra >= 1.0a, Python >= 3.11).", "# ");
+  cb.blank();
+
+  if (needsPath) cb.line("import os");
+  if (imp.typing) cb.line("import typing as ty");
+  if (imp.attrs) cb.line("import attrs.validators");
+  cb.line("from pydra.compose import python");
+  const ff: string[] = [];
+  if (imp.directory) ff.push("Directory");
+  if (imp.file) ff.push("File");
+  if (ff.length > 0) cb.line(`from fileformats.generic import ${ff.join(", ")}`);
+  cb.blank();
+  cb.line(`from .${names.styxStem} import ${spec.delegation.wrapperFn}`);
+  cb.blank();
+  cb.blank();
+
+  if (imp.attrs) {
+    cb.line("def _styx_optional(validator):");
+    cb.indent(() => {
+      cb.line('"""Apply an attrs validator only to a set (non-NOTHING), non-None value."""');
+      cb.line("def _check(instance, attribute, value):");
+      cb.indent(() => {
+        cb.line("if value is attrs.NOTHING or value is None:");
+        cb.indent(() => cb.line("return"));
+        cb.line("validator(instance, attribute, value)");
+      });
+      cb.line("return _check");
+    });
+    cb.blank();
+    cb.blank();
+  }
+
+  if (needsPath) {
+    cb.line("def _styx_path(value):");
+    cb.indent(() => {
+      cb.line('"""Convert fileformats / Path inputs into a styxdefs-accepted path."""');
+      cb.line("if value is None:");
+      cb.indent(() => cb.line("return None"));
+      cb.line("if isinstance(value, (list, tuple)):");
+      cb.indent(() => cb.line("return [os.fspath(v) for v in value]"));
+      cb.line("return os.fspath(value)");
+    });
+    cb.blank();
+    cb.blank();
+  }
+
+  // Decorator
+  cb.line("@python.define(");
+  cb.indent(() => {
+    if (inputEntries.length === 0) {
+      cb.line("inputs={},");
+    } else {
+      cb.line("inputs={");
+      cb.indent(() => {
+        for (const e of inputEntries) cb.line(`${pyStr(e.key)}: ${e.expr},`);
+      });
+      cb.line("},");
+    }
+    cb.line("outputs={");
+    cb.indent(() => {
+      for (const e of outputEntries) cb.line(`${pyStr(e.key)}: ${e.expr},`);
+    });
+    cb.line("},");
+  });
+  cb.line(")");
+
+  // Function
+  const paramList = spec.params.map((p) => p.hostName);
+  cb.line(`def ${names.cls}(${paramList.join(", ")}):`);
+  cb.indent(() => {
+    const docText = [ctx.app?.doc?.title, ctx.app?.doc?.description].filter(Boolean).join("\n\n");
+    emitDocstring(cb, docText || undefined);
+
+    if (!spec.rootIsStruct) {
+      cb.line("raise NotImplementedError(");
+      cb.indent(() =>
+        cb.line(pyStr("styx pydra backend: tools with a non-struct root are not supported.")),
+      );
+      cb.line(")");
+      return;
+    }
+
+    if (spec.params.length === 0) {
+      cb.line(`result = ${spec.delegation.wrapperFn}()`);
+    } else {
+      cb.line(`result = ${spec.delegation.wrapperFn}(`);
+      cb.indent(() => {
+        for (const p of spec.params) {
+          const expr = isPathParam(p) ? `_styx_path(${p.hostName})` : p.hostName;
+          cb.line(`${p.hostName}=${expr},`);
+        }
+      });
+      cb.line(")");
+    }
+
+    const returns = [
+      ...spec.outputs.map((f) => `result.${f.id}`),
+      ...spec.streams.map((s) => `result.${s.id}`),
+    ];
+    if (returns.length === 1) {
+      cb.line(`return ${returns[0]}`);
+    } else {
+      cb.line(`return ${returns.join(", ")}`);
+    }
+  });
+
+  return cb.toString();
+}

package/src/backend/pydra/index.ts

@@ -0,0 +1,3 @@
+export type { PydraNames } from "./emit.js";
+export { emitPydraTask } from "./emit.js";
+export { generatePydra, PydraBackend, pydraNames } from "./pydra.js";

package/src/backend/pydra/pydra.ts

@@ -0,0 +1,67 @@
+import type { CodegenContext } from "../../manifest/index.js";
+import type { Backend, EmittedApp, EmitWarning } from "../backend.js";
+import type { Scope } from "../scope.js";
+import { appModuleName, generatePython } from "../python/index.js";
+import { pascalCase } from "../string-case.js";
+import { buildTypedSpec } from "../typed-spec.js";
+import { emitPydraTask, type PydraNames } from "./emit.js";
+
+/** Derive the per-tool pydra module/class names. */
+export function pydraNames(ctx: CodegenContext): PydraNames {
+  const mod = appModuleName(ctx.app);
+  const rawId = ctx.app?.id ?? "tool";
+  // Mirror the Python backend's digit-leading-id prescrub so the task class name
+  // is a valid Python identifier (e.g. `3dPFM` -> `V3DPfm`).
+  const safeId = /^[0-9]/.test(rawId) ? "v_" + rawId : rawId;
+  return {
+    styxStem: `_${mod}`,
+    ifaceStem: mod,
+    cls: pascalCase(safeId),
+  };
+}
+
+/** Generate the pydra task module source for one tool. */
+export function generatePydra(ctx: CodegenContext): string {
+  return emitPydraTask(ctx, buildTypedSpec(ctx), pydraNames(ctx));
+}
+
+/**
+ * Emits pydra tasks (`@python.define`, the post-rewrite pydra.compose API) whose
+ * typed inputs/outputs carry rich constraints (numeric ranges and list bounds via
+ * attrs validators, enum choices, file types, defaults) and which delegate
+ * execution to the styx Python wrapper (Option B): no command-line arg-building
+ * or output-path resolution is re-implemented here.
+ *
+ * Per tool, two co-located files are emitted so the output is a self-contained,
+ * importable Python package: `_<tool>.py` (the styx Python module) and
+ * `<tool>.py` (the task, importing the wrapper via a relative import).
+ */
+export class PydraBackend implements Backend {
+  readonly name = "pydra";
+  readonly target = "pydra";
+
+  // `scope` is intentionally unused: each tool is emitted as its own module, so
+  // per-tool fresh scoping keeps the styx module's kwarg names and the typed
+  // spec's host names identical by construction (see NipypeBackend).
+  emitApp(ctx: CodegenContext, _scope?: Scope): EmittedApp {
+    const names = pydraNames(ctx);
+    const spec = buildTypedSpec(ctx);
+    const warnings: EmitWarning[] = [];
+    if (!spec.rootIsStruct) {
+      warnings.push({
+        message: `pydra: '${ctx.app?.id ?? "?"}' has a non-struct root; emitted task has no typed inputs and raises on run.`,
+      });
+    }
+    const styxCode = generatePython(ctx);
+    const taskCode = emitPydraTask(ctx, spec, names);
+    return {
+      meta: ctx.app,
+      files: new Map([
+        [`${names.styxStem}.py`, styxCode],
+        [`${names.ifaceStem}.py`, taskCode],
+      ]),
+      errors: [],
+      warnings,
+    };
+  }
+}

package/src/backend/python/index.ts

@@ -1,9 +1,14 @@
-export type { PublicNames } from "./python.js";
+export type { PublicNames, PyEmitModel } from "./python.js";
 export {
   appModuleName,
+  buildEmitModel,
   computePublicNames,
   generatePackageInit,
   generatePython,
   PythonBackend,
 } from "./python.js";
+// Output-field id sanitizer, reused by the nipype/pydra delegation spec so the
+// generated specs reference the exact dataclass attribute names the Python
+// Outputs object exposes.
+export { pyId } from "./outputs-emit.js";
 export { renderPythonCall } from "./snippet.js";

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

@@ -394,7 +394,7 @@ export function emitBuildOutputs(
 }
 
 /** Sanitize an output name to a valid Python identifier. */
-function pyId(name: string): string {
+export function pyId(name: string): string {
   let s = name.replace(/[^a-zA-Z0-9_]/g, "_");
   if (/^\d/.test(s)) s = "_" + s;
   if (s === "") s = "_";

package/src/backend/python/packaging.ts

@@ -72,17 +72,23 @@ function licenseField(proj: ProjectMeta): string {
 }
 
 /**
- * Per-suite `pyproject.toml`. The flat layout (`python/<pkg>/bet.py`) makes the
- * directory itself the importable package, so setuptools' `package-dir` maps the
- * import name (`<pkg>`) onto the distribution's root directory. The styxdefs
+ * Per-suite `pyproject.toml`. The suite source stays in a flat directory
+ * (`python/<pkg>/bet.py`), but setuptools' `package-dir` maps that directory onto
+ * the dotted import package `<project>.<pkg>`, so every suite nests under the
+ * metapackage's `<project>/` namespace. That restores `from <project> import
+ * <pkg>` while keeping each suite a separately-installable distribution (and
+ * leaves no top-level `<pkg>` polluting the global namespace). With no project
+ * name the import name is the bare `<pkg>` (top-level fallback). The styxdefs
  * floor is the only runtime dependency.
  *
- * Precondition: `pkg.name` must be a valid Python identifier - the flat layout's
- * relative imports (`from .bet import *`) already require this, and the CLI uses
- * it verbatim as the directory name, so this stays consistent with that.
+ * Precondition: `importName` is a valid (possibly dotted) Python package path -
+ * the caller scrubs the project + package names into identifiers accordingly.
  */
-export function generateSubPyproject(proj: ProjectMeta, pkg: PackageMeta): string {
-  const importName = pkgDir(pkg);
+export function generateSubPyproject(
+  proj: ProjectMeta,
+  pkg: PackageMeta,
+  importName: string,
+): string {
   const cb = new CodeBuilder("  ");
   cb.line("[project]");
   cb.line(`name = "${tomlStr(pyDistName(proj, pkg))}"`);
@@ -112,11 +118,42 @@ export function generateSubPyproject(proj: ProjectMeta, pkg: PackageMeta): strin
 }
 
 /**
- * Root `pyproject.toml`: a metapackage depending on each per-suite distribution
- * plus the container/graph runner packages. `packages = []` keeps setuptools
- * from sweeping the sibling suite directories into this distribution.
+ * The metapackage's `__init__.py`. A thin re-export of styxkit so the runner
+ * configuration helpers (`use_docker`, `use_local`, `set_global_runner`, ...)
+ * are reachable as `<project>.<name>` - the v1 ergonomic that the v2 split into
+ * per-suite distributions otherwise dropped. The logic lives in styxkit (pulled
+ * in via `styxkit[all]`), so this stays a wildcard re-export and never re-emits
+ * the runner-config code itself.
  */
-export function generateRootPyproject(proj: ProjectMeta, distNames: string[]): string {
+export function generateRootInitPy(): string {
+  return (
+    "# This file was auto generated by Styx.\n" +
+    "# Do not edit this file directly.\n" +
+    "\n" +
+    "# Re-export styxkit's runner-configuration helpers (use_docker, use_local,\n" +
+    "# use_auto, set_global_runner, get_global_runner, ...) so they are available\n" +
+    "# directly on this package, e.g. `import niwrap; niwrap.use_docker()`.\n" +
+    "from styxkit import *  # noqa: F401,F403\n"
+  );
+}
+
+/**
+ * Root `pyproject.toml`: a metapackage depending on `styxkit[all]` (the runner
+ * stack it re-exports) plus each per-suite distribution. `packages` lists only
+ * the metapackage's own module so setuptools ships the styxkit re-export without
+ * sweeping the sibling suite directories into this distribution. The module is
+ * the `<project>/` namespace package the suites nest into, so installing the
+ * metapackage makes `<project>.use_docker()` reachable alongside the suites'
+ * `from <project> import <pkg>`. `moduleDir` is the on-disk source directory; it
+ * differs from the import `moduleName` only when a suite is named after the
+ * project, in which case a `package-dir` remap keeps the import name intact.
+ */
+export function generateRootPyproject(
+  proj: ProjectMeta,
+  distNames: string[],
+  moduleName: string,
+  moduleDir: string,
+): string {
   const cb = new CodeBuilder("  ");
   cb.line("[project]");
   cb.line(`name = "${tomlStr(proj.name ?? "project")}"`);
@@ -132,7 +169,13 @@ export function generateRootPyproject(proj: ProjectMeta, distNames: string[]): s
   cb.line("]");
   cb.blank();
   cb.line("[tool.setuptools]");
-  cb.line("packages = []");
+  cb.line(`packages = ["${moduleName}"]`);
+  if (moduleDir !== moduleName) {
+    cb.line(`package-dir = { "${moduleName}" = "${moduleDir}" }`);
+  }
+  cb.blank();
+  cb.line("[tool.setuptools.package-data]");
+  cb.line(`"${moduleName}" = ["py.typed"]`);
   cb.blank();
   cb.line(BUILD_SYSTEM);
   return cb.toString() + "\n";

package/src/backend/python/python.ts

@@ -1,11 +1,19 @@
 import type { BoundType } from "../../bindings/index.js";
 import type { AppMeta } from "../../ir/index.js";
 import type { CodegenContext, PackageMeta, ProjectMeta } from "../../manifest/index.js";
-import type { AppEntrypoint, Backend, EmitResult, EmittedApp, EmittedPackage } from "../backend.js";
+import type {
+  AppEntrypoint,
+  Backend,
+  EmitResult,
+  EmittedApp,
+  EmittedPackage,
+  EmitWarning,
+} from "../backend.js";
 import type { SigEntry } from "../sig-entries.js";
 import type { NamedType } from "./types.js";
 import {
   generateRequirementsTxt,
+  generateRootInitPy,
   generateRootPyproject,
   generateRootReadme,
   generateSubPyproject,
@@ -537,6 +545,15 @@ export class PythonBackend implements Backend {
     const files = new Map<string, string>();
     const distNames: string[] = [];
     const pkgDirs: string[] = [];
+    const warnings: EmitWarning[] = [];
+
+    // The metapackage's importable module doubles as the namespace every suite
+    // nests under (`<project>.<suite>`), so `from <project> import <suite>` and
+    // `<project>.use_docker()` both resolve from one shared `<project>/` package.
+    // Scrub the project name to a valid, non-keyword identifier; with no project
+    // name there is no namespace and suites stay top-level (matching the bare
+    // distribution-name fallback in `pyDistName`).
+    const nsName = proj.name && proj.name.trim() ? pyScrubIdent(proj.name, PY_RESERVED) : undefined;
 
     for (const p of packages) {
       const pkg = p.meta ?? {};
@@ -545,14 +562,34 @@ export class PythonBackend implements Backend {
       const dir = pkg.name ?? "package";
       pkgDirs.push(dir);
       distNames.push(pyDistName(proj, pkg));
-      files.set(`${dir}/pyproject.toml`, generateSubPyproject(proj, pkg));
+      // Import package: `<project>.<suite>` so it shares the metapackage's
+      // namespace; setuptools maps the flat suite dir onto this dotted path.
+      const importPkg = nsName ? `${nsName}.${dir}` : dir;
+      files.set(`${dir}/pyproject.toml`, generateSubPyproject(proj, pkg, importPkg));
       files.set(`${dir}/README.md`, generateSubReadme(proj, pkg));
     }
 
-    files.set("pyproject.toml", generateRootPyproject(proj, distNames));
+    // The metapackage ships `<project>/__init__.py` (a thin styxkit re-export so
+    // `<project>.use_docker()` works, PEP 561 typed) into the same `<project>/`
+    // package the suites nest under. Its on-disk source dir must dodge a suite
+    // named after the project (both would write `<project>/`); the import name
+    // stays `<project>` via a `package-dir` remap so the namespace is preserved.
+    const metaImport = nsName ?? "project";
+    let metaDir = metaImport;
+    if (pkgDirs.includes(metaDir)) {
+      const collided = metaDir;
+      while (pkgDirs.includes(metaDir)) metaDir += "_";
+      warnings.push({
+        message: `metapackage directory "${collided}" collides with a suite directory; emitting its sources in "${metaDir}" instead (import name stays "${metaImport}")`,
+      });
+    }
+    files.set(`${metaDir}/__init__.py`, generateRootInitPy());
+    files.set(`${metaDir}/py.typed`, "");
+
+    files.set("pyproject.toml", generateRootPyproject(proj, distNames, metaImport, metaDir));
     files.set("README.md", generateRootReadme(proj, distNames));
     files.set("requirements.txt", generateRequirementsTxt(pkgDirs));
 
-    return { files, errors: [], warnings: [] };
+    return { files, errors: [], warnings };
   }
 }

package/src/backend/schema/jsonschema.ts

@@ -8,6 +8,7 @@ import { findStructNode } from "../find-struct-node.js";
 import { resolveFieldBinding } from "../resolve-field-binding.js";
 import { Scope } from "../scope.js";
 import { snakeCase } from "../string-case.js";
+import { findAlternativeNode, findRepeatNode } from "../validate-walk.js";
 
 export interface JsonSchema {
   type?: string | string[];
@@ -69,7 +70,11 @@ class SchemaBuilder {
       case "optional":
         return this.fromType(type.inner, node?.kind === "optional" ? node.attrs.node : undefined);
       case "list": {
-        const repeat = node?.kind === "repeat" ? node : undefined;
+        // Descend through any optional/flag-sequence wrappers to the repeat node
+        // (matching the TS/Python backends). A naive `node.kind === "repeat"`
+        // check only matches a bare top-level list and silently drops the bounds
+        // (and item-level scalar ranges) for the common optional/flagged shape.
+        const repeat = findRepeatNode(node);
         const schema: JsonSchema = {
           type: "array",
           items: this.fromType(type.item, repeat?.attrs.node),
@@ -83,7 +88,7 @@ class SchemaBuilder {
       case "struct":
         return this.structSchema(type, node);
       case "union":
-        return this.unionSchema(type);
+        return this.unionSchema(type, node);
     }
   }
 
@@ -167,7 +172,7 @@ class SchemaBuilder {
     return schema;
   }
 
-  private unionSchema(type: Extract<BoundType, { kind: "union" }>): JsonSchema {
+  private unionSchema(type: Extract<BoundType, { kind: "union" }>, node?: Expr): JsonSchema {
     const allLiterals = type.variants.every((v: BoundVariant) => v.type.kind === "literal");
     if (allLiterals) {
       return {
@@ -176,7 +181,32 @@ class SchemaBuilder {
         ),
       };
     }
-    return { oneOf: type.variants.map((v: BoundVariant) => this.fromType(v.type)) };
+    // Thread each arm's IR node so struct-variant fields keep their constraints
+    // (numeric ranges, list bounds). `variants` stays parallel to the IR `alts`
+    // (the solver builds them together), so `alts[i]` is variant `i`'s node.
+    const altNode = findAlternativeNode(node);
+    return {
+      oneOf: type.variants.map((v: BoundVariant, i: number) => {
+        const schema = this.fromType(v.type, altNode?.attrs.alts[i]);
+        // The solver prepends a synthetic `@type` literal to each non-literal
+        // variant, but `structSchema`'s node-driven branch builds properties from
+        // the IR struct's children, which don't include `@type`. Re-add it (first,
+        // required) so each arm still carries its discriminant tag.
+        if (
+          v.type.kind === "struct" &&
+          "@type" in v.type.fields &&
+          schema.properties &&
+          !("@type" in schema.properties)
+        ) {
+          schema.properties = {
+            "@type": this.fromType(v.type.fields["@type"]!),
+            ...schema.properties,
+          };
+          schema.required = ["@type", ...(schema.required ?? [])];
+        }
+        return schema;
+      }),
+    };
   }
 }
 

package/src/backend/styxdefs-compat.ts

@@ -14,8 +14,10 @@ export const STYXDEFS_COMPAT = {
 } as const;
 
 /**
- * Extra Python runtime packages the root distribution pulls in (container +
- * graph runners). Left unpinned - styxdefs's floor constrains them transitively
- * via their own inter-package pins.
+ * Extra Python runtime packages the root metapackage pulls in. `styxkit[all]`
+ * provides the cross-backend runner-selection helpers (`use_docker`, `use_auto`,
+ * ...) that the metapackage's `__init__` re-exports, and transitively installs
+ * every container/graph runner backend. Left unpinned - styxkit's own styxdefs
+ * floor constrains the stack.
  */
-export const PYTHON_RUNNER_DEPS = ["styxdocker", "styxsingularity", "styxgraph"] as const;
+export const PYTHON_RUNNER_DEPS = ["styxkit[all]"] as const;