@styx-api/core 0.1.0

package/src/backend/schema/jsonschema.ts

@@ -0,0 +1,303 @@
+import type { Binding, BoundType, BoundVariant } from "../../bindings/index.js";
+import type { Expr, ScalarKind } from "../../ir/index.js";
+import type { CodegenContext } from "../../manifest/index.js";
+import type { Backend, EmittedApp } from "../backend.js";
+import { type OutputShape, collectOutputFields, streamFields } from "../collect-output-fields.js";
+import { findDoc } from "../find-doc.js";
+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";
+
+export interface JsonSchema {
+  type?: string | string[];
+  items?: JsonSchema;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  oneOf?: JsonSchema[];
+  enum?: (string | number)[];
+  const?: string | number;
+  [key: string]: unknown;
+}
+
+class SchemaBuilder {
+  constructor(private ctx: CodegenContext) {}
+
+  build(): JsonSchema {
+    const envelope: JsonSchema = {
+      $schema: "https://json-schema.org/draft/2020-12/schema",
+    };
+    if (this.ctx.app?.doc?.title) envelope.title = this.ctx.app.doc.title;
+    if (this.ctx.app?.doc?.description) envelope.description = this.ctx.app.doc.description;
+
+    const rootBinding = this.ctx.resolve(this.ctx.expr);
+    if (!rootBinding) return envelope;
+
+    const schema = { ...envelope, ...this.fromBinding(rootBinding) };
+
+    if (this.ctx.app?.id && schema.properties) {
+      const pkg = this.ctx.package?.name ?? "unknown";
+      schema.properties = {
+        "@type": { const: `${pkg}/${this.ctx.app.id}` },
+        ...schema.properties,
+      };
+      schema.required = ["@type", ...(schema.required ?? [])];
+    }
+
+    return schema;
+  }
+
+  private fromBinding(binding: Binding): JsonSchema {
+    const schema = this.fromType(binding.type, binding.node);
+    const meta = binding.node.meta;
+    if (meta?.doc?.title) schema.title = meta.doc.title;
+    if (meta?.doc?.description) schema.description = meta.doc.description;
+    if (meta?.defaultValue !== undefined) schema.default = meta.defaultValue;
+    return schema;
+  }
+
+  private fromType(type: BoundType, node?: Expr): JsonSchema {
+    switch (type.kind) {
+      case "scalar":
+        return this.scalarSchema(type.scalar, node);
+      case "bool":
+        return { type: "boolean" };
+      case "count":
+        return { type: "integer", minimum: 0 };
+      case "literal":
+        return { const: type.value };
+      case "optional":
+        return this.fromType(type.inner, node?.kind === "optional" ? node.attrs.node : undefined);
+      case "list": {
+        const repeat = node?.kind === "repeat" ? node : undefined;
+        const schema: JsonSchema = {
+          type: "array",
+          items: this.fromType(type.item, repeat?.attrs.node),
+        };
+        // Bounded/fixed-length vectors (e.g. a 3-element coordinate) carry length
+        // constraints so a form consumer can render the right number of slots.
+        if (repeat?.attrs.countMin !== undefined) schema.minItems = repeat.attrs.countMin;
+        if (repeat?.attrs.countMax !== undefined) schema.maxItems = repeat.attrs.countMax;
+        return schema;
+      }
+      case "struct":
+        return this.structSchema(type, node);
+      case "union":
+        return this.unionSchema(type);
+    }
+  }
+
+  private findTerminal(node: Expr): Expr {
+    switch (node.kind) {
+      case "optional":
+        return this.findTerminal(node.attrs.node);
+      case "repeat":
+        return this.findTerminal(node.attrs.node);
+      case "sequence": {
+        const nonLiteral = node.attrs.nodes.find((n) => n.kind !== "literal");
+        return nonLiteral ? this.findTerminal(nonLiteral) : node;
+      }
+      default:
+        return node;
+    }
+  }
+
+  private scalarSchema(scalar: ScalarKind, node?: Expr): JsonSchema {
+    const base: JsonSchema = {
+      int: { type: "integer" } as JsonSchema,
+      float: { type: "number" } as JsonSchema,
+      str: { type: "string" } as JsonSchema,
+      path: { type: "string", "x-styx-type": "path" } as JsonSchema,
+    }[scalar];
+
+    const terminal = node ? this.findTerminal(node) : undefined;
+    if (terminal && (terminal.kind === "int" || terminal.kind === "float")) {
+      if (terminal.attrs.minValue !== undefined) base.minimum = terminal.attrs.minValue;
+      if (terminal.attrs.maxValue !== undefined) base.maximum = terminal.attrs.maxValue;
+    }
+
+    return base;
+  }
+
+  private structSchema(type: Extract<BoundType, { kind: "struct" }>, node?: Expr): JsonSchema {
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+
+    // Use shared findStructNode for correct traversal through opt/rep/alt wrappers
+    const structNode = node ? findStructNode(node, this.ctx, type) : undefined;
+    if (structNode) {
+      for (const child of structNode.attrs.nodes) {
+        // Use shared resolveFieldBinding for correct collapsed-sequence handling
+        const match = resolveFieldBinding(child, this.ctx, type);
+        if (!match) continue;
+        const { binding, wrapperNode } = match;
+
+        const schema = this.fromType(binding.type, binding.node);
+        const fieldType = type.fields[binding.name]!;
+
+        // Use shared findDoc for correct doc propagation through collapsed sequences
+        const doc =
+          findDoc(wrapperNode, fieldType) ??
+          findDoc(binding.node, fieldType) ??
+          wrapperNode.meta?.doc?.description;
+        if (doc) schema.description = doc;
+
+        const title = wrapperNode.meta?.doc?.title ?? binding.node.meta?.doc?.title;
+        if (title) schema.title = title;
+
+        const defaultValue = wrapperNode.meta?.defaultValue ?? binding.node.meta?.defaultValue;
+        if (defaultValue !== undefined) schema.default = defaultValue;
+
+        properties[binding.name] = schema;
+        if (fieldType.kind !== "optional" && defaultValue === undefined) {
+          required.push(binding.name);
+        }
+      }
+    } else {
+      for (const [name, fieldType] of Object.entries(type.fields)) {
+        properties[name] = this.fromType(fieldType);
+        if (fieldType.kind !== "optional") {
+          required.push(name);
+        }
+      }
+    }
+
+    const schema: JsonSchema = { type: "object", properties };
+    if (required.length > 0) schema.required = required;
+    return schema;
+  }
+
+  private unionSchema(type: Extract<BoundType, { kind: "union" }>): JsonSchema {
+    const allLiterals = type.variants.every((v: BoundVariant) => v.type.kind === "literal");
+    if (allLiterals) {
+      return {
+        enum: type.variants.map((v: BoundVariant) =>
+          v.type.kind === "literal" ? v.type.value : "",
+        ),
+      };
+    }
+    return { oneOf: type.variants.map((v: BoundVariant) => this.fromType(v.type)) };
+  }
+}
+
+export function generateSchema(ctx: CodegenContext): JsonSchema {
+  return new SchemaBuilder(ctx).build();
+}
+
+/** Output names are language-neutral in the schema; key by the raw descriptor id. */
+const rawName = (name: string): string => name;
+
+/** The JSON Schema for one output field, given its solved shape. */
+function outputFieldSchema(shape: OutputShape): JsonSchema {
+  // A list output is always present (an empty array when nothing is produced),
+  // its elements never null: `OutputPathType[]` / `list[OutputPathType]`.
+  if (shape.kind === "list") {
+    return { type: "array", items: { type: "string", "x-styx-type": "path" } };
+  }
+  // A single output's key is always present on the Outputs object; when its gate
+  // is off the value is `null` (the backends type it `OutputPathType | None` /
+  // `OutputPathType | null`). So a gated single is a path OR null - not an
+  // absent key. We mark it `required` (see below) and carry the null branch.
+  if (shape.optional) return { type: ["string", "null"], "x-styx-type": "path" };
+  return { type: "string", "x-styx-type": "path" };
+}
+
+/**
+ * JSON Schema for a tool's **Outputs object**: the set of files it produces
+ * (resolved outputs + mutable inputs surfaced as outputs) plus its captured
+ * stdout/stderr streams. Built from the same `collectOutputFields` /
+ * `streamFields` source of truth the Python and TypeScript backends use to type
+ * the Outputs dataclass/interface, so the three describe the same shape.
+ *
+ * Field encoding (mirrors how the language backends type each field):
+ * - required single -> `{ type: "string", x-styx-type: "path" }`
+ * - optional single -> `{ type: ["string", "null"], x-styx-type: "path" }`
+ * - list output     -> `{ type: "array", items: { type: "string", x-styx-type: "path" } }`
+ * - stream field    -> `{ type: "array", items: { type: "string" } }` (lines of
+ *   text, NOT paths - the absent `x-styx-type` lets a consumer tell them apart)
+ *
+ * EVERY field is `required`: unlike the inputs schema (where an optional param
+ * key is genuinely omitted, so "not in `required`" is faithful), an Outputs
+ * field is always present - a gated single is `null`, a gated list is an empty
+ * array. So optionality is carried by the `null` type branch, and a strict
+ * validator accepts the actual emitted object (e.g. `{ "out_file": null }`).
+ */
+export function generateOutputsSchema(ctx: CodegenContext): JsonSchema {
+  const schema: JsonSchema = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+  };
+  if (ctx.app?.doc?.title) schema.title = ctx.app.doc.title;
+  if (ctx.app?.doc?.description) schema.description = ctx.app.doc.description;
+
+  const properties: Record<string, JsonSchema> = {};
+  const required: string[] = [];
+
+  for (const field of collectOutputFields(ctx, rawName)) {
+    const prop = outputFieldSchema(field.shape);
+    if (field.doc) prop.description = field.doc;
+    properties[field.name] = prop;
+    required.push(field.name);
+  }
+
+  for (const stream of streamFields(ctx, rawName)) {
+    const prop: JsonSchema = { type: "array", items: { type: "string" } };
+    if (stream.doc) prop.description = stream.doc;
+    properties[stream.name] = prop;
+    required.push(stream.name);
+  }
+
+  schema.properties = properties;
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+/**
+ * Filesystem-safe, unique-within-the-package stem for one tool's schema files.
+ *
+ * In catalog mode every tool in a package emits into the same `<pkg>/` directory,
+ * so fixed `schema.json` names would clobber each other (only the last tool would
+ * survive). We prefix each tool's files with a slug derived from its app id -
+ * `snakeCase` so symbol-heavy ids like `3dfim+` / `@2dwarper.Allin` become safe,
+ * lowercase, collision-resistant stems (`3dfim` / `2dwarper_allin`) - and dedup
+ * through the shared package `scope` so the rare slug collision still gets a `_2`.
+ *
+ * Returns undefined when there is no scope (standalone single-tool emission, where
+ * one unprefixed `schema.json` is unambiguous) or no app id (anonymous descriptor).
+ */
+function schemaStem(ctx: CodegenContext, scope?: Scope): string | undefined {
+  const id = ctx.app?.id;
+  if (!id || !scope) return undefined;
+  return scope.add(snakeCase(id) || "schema");
+}
+
+export class JsonSchemaBackend implements Backend {
+  readonly name = "json-schema";
+  readonly target = "json-schema";
+
+  /** One scope per package so per-tool schema file stems stay unique in the suite directory. */
+  newPackageScope(): Scope {
+    return new Scope();
+  }
+
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp {
+    const schema = generateSchema(ctx);
+    const outputsSchema = generateOutputsSchema(ctx);
+    // In a catalog build, prefix with a per-tool stem so co-located tools don't
+    // clobber one another; standalone single-tool builds keep the bare names.
+    const stem = schemaStem(ctx, scope);
+    const prefix = stem ? `${stem}.` : "";
+    return {
+      meta: ctx.app,
+      // Inputs and outputs are kept as two cleanly addressable artifacts
+      // (mirroring v1's `<tool>.input.json` / `<tool>.output.json` split): a
+      // consumer can fetch/compute either independently.
+      files: new Map([
+        [`${prefix}schema.json`, JSON.stringify(schema, null, 2)],
+        [`${prefix}outputs.schema.json`, JSON.stringify(outputsSchema, null, 2)],
+      ]),
+      errors: [],
+      warnings: [],
+    };
+  }
+}

package/src/backend/scope.ts

@@ -0,0 +1,50 @@
+/** Symbol collision avoidance for code generation. */
+export class Scope {
+  private readonly reserved: ReadonlySet<string>;
+  private readonly used: Set<string>;
+  private readonly parent?: Scope;
+
+  constructor(reserved: Iterable<string> = [], parent?: Scope) {
+    this.reserved = new Set(reserved);
+    this.used = new Set();
+    this.parent = parent;
+  }
+
+  /** Check if a symbol is already taken (in this scope or any parent). */
+  has(symbol: string): boolean {
+    return (
+      this.reserved.has(symbol) || this.used.has(symbol) || (this.parent?.has(symbol) ?? false)
+    );
+  }
+
+  /**
+   * Add a symbol, appending a numeric suffix to avoid collisions. Returns the
+   * safe name.
+   *
+   * When a `recase` transform is given, a disambiguated candidate is routed back
+   * through it so the suffix is absorbed into the identifier's casing - e.g.
+   * `pascalCase` folds `Config_2` into `Config2` - rather than leaving a
+   * mixed-case `Config_2`. Uniqueness is always checked on the final emitted
+   * form, so two hints that case-collide still get distinct names. Defaults to
+   * identity (the bare `<name>_<n>` suffix) for callers that don't case-normalize.
+   */
+  add(candidate: string, recase: (s: string) => string = (s) => s): string {
+    if (!this.has(candidate)) {
+      this.used.add(candidate);
+      return candidate;
+    }
+    let suffix = 2;
+    let safe = recase(`${candidate}_${suffix}`);
+    while (this.has(safe)) {
+      suffix++;
+      safe = recase(`${candidate}_${suffix}`);
+    }
+    this.used.add(safe);
+    return safe;
+  }
+
+  /** Create a child scope that inherits this scope's restrictions. */
+  child(reserved: Iterable<string> = []): Scope {
+    return new Scope(reserved, this);
+  }
+}

package/src/backend/sig-entries.ts

@@ -0,0 +1,97 @@
+import type { BoundType } from "../bindings/index.js";
+import type { FieldInfo } from "./collect-field-info.js";
+
+/**
+ * One entry of a kwarg-style signature, shared across language backends. Each
+ * entry describes a single user-facing parameter of the `_params()` factory
+ * and the kwarg wrapper:
+ * - `sigType`/`sigDefault` go directly into the function signature
+ * - `isOptional`/`hasExplicitDefault` drive the dict-build branches (required
+ *   and explicitly-defaulted fields are always set; optional-no-default fields
+ *   are conditionally set when not None/null)
+ * - `doc` is rendered into the per-param doc block (Args / @param)
+ *
+ * `name` is the scrubbed host identifier (used in the signature and function
+ * body); `wireKey` is the Boutiques field name (used as the dict key /
+ * TypedDict field key). They diverge when the wire key collides with a host
+ * reserved word, is not a valid identifier, or shadows a local in the emitting
+ * function (e.g. wire `float` -> host `float_`, wire `4d_input` -> host
+ * `v_4d_input`).
+ */
+export interface SigEntry {
+  /** Scrubbed host identifier - safe to use in signatures and as a local. */
+  name: string;
+  /** Boutiques field name - used as the dict key / TypedDict field key. */
+  wireKey: string;
+  sigType: string;
+  /** Rendered default expression in the host language, or undefined for required-no-default. */
+  sigDefault?: string;
+  /** True iff the BoundType is `optional` (i.e. dict-build conditionally includes). */
+  isOptional: boolean;
+  /** True iff the field carries an explicit defaultValue in its FieldInfo. */
+  hasExplicitDefault: boolean;
+  doc?: string;
+}
+
+/** Per-backend rendering hooks for `buildSigEntries`. */
+export interface SigOptions {
+  /** Render a non-optional BoundType as a language-native type expression. */
+  renderType: (t: BoundType) => string;
+  /** Suffix appended to `renderType(inner)` for optional fields (e.g. ` | None`, ` | null`). */
+  nullableSuffix: string;
+  /** Default expression for optional-no-default fields (e.g. `None`, `null`). */
+  nullableDefault: string;
+  /** Render a JS scalar default as a host-language literal (e.g. `True`/`true`). */
+  renderDefault: (v: string | number | boolean) => string;
+}
+
+/**
+ * Build per-field signature entries for the kwarg wrapper and params factory.
+ * Skips `@type` (the factory injects it as a constant). Required-no-default
+ * entries are placed before defaulted ones so the resulting signature is
+ * syntactically valid in both Python and TS.
+ *
+ * `registerLocal` is called once per field with the wire key; it must return
+ * a scrubbed, unique host identifier (typically by combining a language-aware
+ * scrub function with `Scope.add()`). The caller's scope should already have
+ * the function's other locals (`params`, `runner`, ...) reserved so this
+ * registration cannot collide with them.
+ */
+export function buildSigEntries(
+  rootType: Extract<BoundType, { kind: "struct" }>,
+  fieldInfo: Map<string, FieldInfo>,
+  registerLocal: (wireKey: string) => string,
+  opts: SigOptions,
+): SigEntry[] {
+  const entries: SigEntry[] = [];
+  for (const [fieldName, fieldType] of Object.entries(rootType.fields)) {
+    if (fieldType.kind === "literal") continue;
+
+    const fi = fieldInfo.get(fieldName);
+    const isOptional = fieldType.kind === "optional";
+    const inner = isOptional ? fieldType.inner : fieldType;
+    let sigType = opts.renderType(inner);
+    if (isOptional) sigType += opts.nullableSuffix;
+
+    let sigDefault: string | undefined;
+    const hasExplicitDefault = fi?.defaultValue !== undefined;
+    if (hasExplicitDefault) {
+      sigDefault = opts.renderDefault(fi!.defaultValue!);
+    } else if (isOptional) {
+      sigDefault = opts.nullableDefault;
+    }
+
+    entries.push({
+      name: registerLocal(fieldName),
+      wireKey: fieldName,
+      sigType,
+      sigDefault,
+      isOptional,
+      hasExplicitDefault,
+      doc: fi?.doc,
+    });
+  }
+  const required = entries.filter((e) => e.sigDefault === undefined);
+  const defaulted = entries.filter((e) => e.sigDefault !== undefined);
+  return [...required, ...defaulted];
+}

package/src/backend/snippet-core.ts

@@ -0,0 +1,185 @@
+import type { BoundType } from "../bindings/index.js";
+
+/**
+ * Per-language rendering hooks for the call-site snippet renderer. The recursive
+ * structure (struct -> object literal, union -> picked variant, list -> array)
+ * is language-agnostic; only leaf-literal syntax, object keys, and indentation
+ * differ, and those are supplied here.
+ */
+export interface SnippetDialect {
+  /** One indentation level (e.g. `"    "` for Python, `"  "` for TypeScript). */
+  indentUnit: string;
+  /** Render a string value as a host literal (quoted). */
+  string(value: string): string;
+  /** Render a boolean value as a host literal (`True`/`true`). */
+  boolean(value: boolean): string;
+  /** Render a number value as a host literal. */
+  number(value: number): string;
+  /** Host literal for a null/None value. */
+  null: string;
+  /** Render an object-literal key from a wire key, quoting when not a bare identifier. */
+  objKey(wireKey: string): string;
+}
+
+/** Options shared by both language renderers. */
+export interface SnippetOptions {
+  /**
+   * Module the package is imported from (e.g. `"niwrap"`). Defaults to the
+   * project name on the context. When unset and no project name is available,
+   * Python falls back to a bare `import <pkg>` and TypeScript omits the import.
+   */
+  packageRoot?: string;
+  /** Whether to prepend an import line. Defaults to `true`. */
+  includeImport?: boolean;
+}
+
+/** Is `value` a plain (non-array) object usable as a struct/union config? */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Strip transparent `optional` wrappers down to the underlying value type. */
+function unwrap(type: BoundType): BoundType {
+  return type.kind === "optional" ? unwrap(type.inner) : type;
+}
+
+/** Render a leaf primitive (string/number/bool/null) by its JS runtime type. */
+function renderPrimitive(value: unknown, d: SnippetDialect): string {
+  if (value === null || value === undefined) return d.null;
+  switch (typeof value) {
+    case "string":
+      return d.string(value);
+    case "boolean":
+      return d.boolean(value);
+    case "number":
+      return d.number(value);
+    default:
+      // Bigint / unexpected: fall back to a quoted string form.
+      return d.string(String(value));
+  }
+}
+
+/** The `@type` discriminator value carried by a struct type, if any. */
+function structAtType(type: Extract<BoundType, { kind: "struct" }>): string | undefined {
+  const field = type.fields["@type"];
+  return field && field.kind === "literal" ? String(field.value) : undefined;
+}
+
+/**
+ * Render a struct config as a host object literal (Python dict / TS object).
+ * Keys are the Boutiques wire names (the generated TypedDict / interface keys) -
+ * nested structs have no constructor function in the generated code, so callers
+ * build them as plain object literals.
+ *
+ * `@type` is emitted from the struct's literal discriminator field when present
+ * (union variants carry a required, load-bearing `@type`); for the root call the
+ * tag is injected via `injectAtType` (the root's `@type` is derived from
+ * `pkg/appId`, not stored as a field). Non-`@type` literal fields have no
+ * runtime representation and are skipped.
+ */
+export function renderStructLiteral(
+  value: unknown,
+  type: Extract<BoundType, { kind: "struct" }>,
+  indent: string,
+  d: SnippetDialect,
+  injectAtType?: string,
+): string {
+  const obj = isRecord(value) ? value : {};
+  const inner = indent + d.indentUnit;
+  const lines: string[] = [];
+
+  const atType = structAtType(type) ?? injectAtType;
+  if (atType !== undefined) {
+    lines.push(`${inner}${d.objKey("@type")}: ${d.string(atType)},`);
+  }
+
+  for (const [wireKey, fieldType] of Object.entries(type.fields)) {
+    if (wireKey === "@type") continue;
+    if (fieldType.kind === "literal") continue; // no runtime representation
+    if (!(wireKey in obj)) continue; // omitted optional / absent field
+    lines.push(`${inner}${d.objKey(wireKey)}: ${renderValue(obj[wireKey], fieldType, inner, d)},`);
+  }
+
+  if (lines.length === 0) return "{}";
+  return `{\n${lines.join("\n")}\n${indent}}`;
+}
+
+/**
+ * Render a union config. An object value with an `@type` is matched to the
+ * struct variant whose discriminator equals that tag and rendered as that
+ * variant's object literal; a primitive value (a bare literal/scalar variant,
+ * e.g. a mixed union's `"Linear"` const arm) is rendered directly.
+ */
+function renderUnion(
+  value: unknown,
+  type: Extract<BoundType, { kind: "union" }>,
+  indent: string,
+  d: SnippetDialect,
+): string {
+  if (isRecord(value)) {
+    const tag = value["@type"];
+    const match = type.variants.find(
+      (v) => v.type.kind === "struct" && structAtType(v.type) === String(tag),
+    );
+    if (match && match.type.kind === "struct") {
+      return renderStructLiteral(value, match.type, indent, d);
+    }
+    // Unknown/missing tag: fall back to the sole struct variant if there is one,
+    // otherwise emit an empty object. (Well-formed configs always match.)
+    const onlyStruct = type.variants.filter((v) => v.type.kind === "struct");
+    if (onlyStruct.length === 1 && onlyStruct[0]!.type.kind === "struct") {
+      return renderStructLiteral(value, onlyStruct[0]!.type, indent, d);
+    }
+    return "{}";
+  }
+  return renderPrimitive(value, d);
+}
+
+/**
+ * Render a list config. A list of structs/unions renders multi-line (one object
+ * literal per element); a list of primitives renders inline (`[1, 2, 3]`).
+ */
+function renderList(value: unknown, item: BoundType, indent: string, d: SnippetDialect): string {
+  if (!Array.isArray(value) || value.length === 0) return "[]";
+  const it = unwrap(item);
+  if (it.kind === "struct" || it.kind === "union") {
+    const inner = indent + d.indentUnit;
+    const elems = value.map((el) => `${inner}${renderValue(el, it, inner, d)},`);
+    return `[\n${elems.join("\n")}\n${indent}]`;
+  }
+  return `[${value.map((el) => renderValue(el, it, indent, d)).join(", ")}]`;
+}
+
+/**
+ * Render a config value to a host-language expression, guided by its BoundType.
+ *
+ * `indent` is the leading whitespace of the line the value starts on; multi-line
+ * forms (object/array literals) place their members one level deeper and close
+ * back at `indent`. The renderer follows the BoundType tree for shape and reads
+ * the parallel config object for values, so unknown / absent keys are simply
+ * omitted (a partial config produces a partial snippet).
+ */
+export function renderValue(
+  value: unknown,
+  type: BoundType,
+  indent: string,
+  d: SnippetDialect,
+): string {
+  // A present null/undefined renders as the host null literal regardless of the
+  // declared type. An explicitly-unset optional field (a form may emit `null`
+  // rather than omitting the key) must not be coerced into an empty `{}` / `[]`
+  // by the struct/list branches below - that would be a value the generated code
+  // rejects (a struct missing its required keys, a non-array for a list).
+  if (value === null || value === undefined) return d.null;
+  const t = unwrap(type);
+  switch (t.kind) {
+    case "struct":
+      return renderStructLiteral(value, t, indent, d);
+    case "union":
+      return renderUnion(value, t, indent, d);
+    case "list":
+      return renderList(value, t.item, indent, d);
+    default:
+      return renderPrimitive(value, d);
+  }
+}

package/src/backend/string-case.ts

@@ -0,0 +1,30 @@
+/** Split a string into lowercase word tokens for case conversion. */
+function tokenize(s: string): string[] {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // camelCase boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2") // consecutive uppercase -> keep runs
+    .replace(/[^a-zA-Z0-9]+/g, " ")
+    .trim()
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+export function snakeCase(s: string): string {
+  return tokenize(s).join("_");
+}
+
+export function screamingSnakeCase(s: string): string {
+  return tokenize(s).join("_").toUpperCase();
+}
+
+export function pascalCase(s: string): string {
+  return tokenize(s)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+export function camelCase(s: string): string {
+  const pascal = pascalCase(s);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}

package/src/backend/styxdefs-compat.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime version floors baked into generated dependency metadata.
+ *
+ * styx2-generated code calls `mutable_copy` / `mutableCopy` (introduced in the
+ * styxdefs 0.7.0 / styxdefs-js 0.2.0 release), so emitted packages genuinely
+ * require that runtime floor. This is the single source of truth: bump here and
+ * both the Python and TypeScript backends pick it up.
+ */
+export const STYXDEFS_COMPAT = {
+  /** PEP 508 specifier for the Python `styxdefs` package. */
+  python: ">=0.7.0,<0.8.0",
+  /** npm semver range for the `styxdefs` package. */
+  npm: "^0.2.0",
+} 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.
+ */
+export const PYTHON_RUNNER_DEPS = ["styxdocker", "styxsingularity", "styxgraph"] as const;