@distilled.cloud/core 1.0.0-rc.1 → 1.0.0-rc.10

package/src/codegen/cli.ts

@@ -1,12 +1,11 @@
 /**
  * The generic generator CLI harness (dev-time only).
  *
- * Owns the smithy-model pipeline every SDK package shares: scan the model
- * directory (plus optional hand-authored manual specs), apply the RFC-6902
- * patch chain (`patches/<resource>/*.json`, `*.manual.json` last; stale
- * targets warn, malformed patches fail the run), compile each model through
- * {@link generateService} with the provider's {@link SdkSpec}, write the
- * service modules and the namespaced barrel.
+ * Owns the smithy→SDK pipeline every SDK package shares: scan the model
+ * directory (plus optional hand-authored manual specs), compile each model
+ * through {@link generateService} with the provider's {@link SdkSpec}, write
+ * the service modules and the namespaced barrel. RFC-6902 patches apply in
+ * convert so `.generated-specs` is already the patched model.
  *
  * A provider's `scripts/generate.ts` is: trait consts + an SdkSpec + a
  * `runGeneratorCli` call.
@@ -17,11 +16,6 @@ import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import { Flag } from "effect/unstable/cli";
 import { Command } from "effect/unstable/cli";
-import {
-  applyOperation,
-  isStaleTargetError,
-  type PatchFile,
-} from "../json-patch.ts";
 import { barrel } from "./emit.ts";
 import { formatGenerated } from "./format.ts";
 import { generateService, type SdkSpec } from "./generator.ts";
@@ -37,15 +31,63 @@ export interface GeneratorCliOptions {
   readonly outDir?: string;
   /** Model files to skip (e.g. a shared protocols model). */
   readonly excludeModel?: (file: string) => boolean;
+  /**
+   * Where the models are, when they aren't a flat directory of `<resource>.json`.
+   * AWS vendors Amazon's own repo, whose models sit at
+   * `models/<service>/service/<version>/<service>-<version>.json`.
+   *
+   * Returns the model files to compile; manual specs are merged in after,
+   * as usual.
+   */
+  readonly discoverModels?: (ctx: {
+    readonly smithyDir: string;
+  }) => Effect.Effect<
+    ReadonlyArray<{ readonly file: string; readonly dir: string }>,
+    never,
+    FileSystem.FileSystem | Path.Path
+  >;
+  /**
+   * Side effects to run before generating — e.g. AWS copies `partitions.json`
+   * out of the smithy submodule, runtime data its endpoint resolver reads.
+   */
+  readonly prepare?: (ctx: {
+    readonly root: string;
+    readonly outDir: string;
+  }) => Effect.Effect<void, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * The output module's name, when it isn't the model's filename. AWS names
+   * modules after the service's `aws.api#service` sdkId (`amazon-s3.json` →
+   * `s3.ts`), so the public surface reads `AWS.S3.getObject`.
+   */
+  readonly resourceName?: (ctx: {
+    readonly model: any;
+    readonly file: string;
+  }) => string;
+  /** Barrel export name for a resource. Default: the resource name itself. */
+  readonly barrelExportName?: (resource: string) => string;
+  /**
+   * The closing pass over the output directory. Defaults to formatting;
+   * AWS lint-fixes first (see `codegen/format.ts`).
+   */
+  readonly finalize?: (dir: string) => Effect.Effect<void>;
+  /**
+   * Keep generating after a model fails, instead of stopping at the first.
+   * AWS compiles 430 services in one run, and one broken model shouldn't
+   * hide the state of the other 429. The run still FAILS at the end — the
+   * failures are reported together rather than swallowed.
+   */
+  readonly continueOnModelError?: boolean;
   /** Directory of hand-authored models merged after the generated ones. */
   readonly manualSpecsDir?: string;
-  /** RFC-6902 patch chain root. Default `patches`; `false` disables. */
-  readonly patchesDir?: string | false;
   /**
-   * Model transform applied AFTER the patch chain, before generation —
-   * for whole-model rewrites that must see post-patch shape names (e.g.
-   * cloudflare's scope-twin structural dedup). May mutate the model;
-   * a returned log line is printed.
+   * RFC-6902 patches apply in convert, never here. Only `false` is accepted
+   * so a string is a type error rather than a silently ignored setting.
+   */
+  readonly patchesDir?: false;
+  /**
+   * Model transform applied before generation (e.g. AWS dropping
+   * unreachable foreign-namespace shapes from a vendored model). Does not
+   * write back to `.generated-specs` — convert owns the committed model.
    */
   readonly transformModel?: (model: any, resource: string) => string | void;
   /** The provider spec — built per model (metadata may vary per model). */
@@ -57,15 +99,15 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
   const command = Command.make(
     "generate",
     {
-      smithy: Flag.string("smithy").pipe(
+      smithy: Flag.String("smithy").pipe(
         Flag.withDefault(options.smithyDir ?? ".generated-specs"),
         Flag.withDescription("Directory of Smithy JSON models"),
       ),
-      out: Flag.string("out").pipe(
+      out: Flag.String("out").pipe(
         Flag.withDefault(options.outDir ?? "src/services"),
         Flag.withDescription("Output directory for generated service modules"),
       ),
-      resource: Flag.string("resource").pipe(
+      resource: Flag.String("resource").pipe(
         Flag.withDefault(""),
         Flag.withDescription("Only generate this resource (e.g. ai)"),
       ),
@@ -82,14 +124,19 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         yield* Console.log(`   Smithy: ${smithyDir}`);
         yield* Console.log(`   Output: ${outDir}`);
 
+        yield* options.prepare?.({ root, outDir }) ?? Effect.void;
+
         // Generated models plus optional manual-specs (hand-authored models
         // for APIs the provider's spec source doesn't cover). A manual model
         // must not shadow a generated one.
-        const generated = (yield* fs.readDirectory(smithyDir))
-          .filter(
-            (f) => f.endsWith(".json") && !(options.excludeModel?.(f) ?? false),
-          )
-          .map((f) => ({ file: f, dir: smithyDir }));
+        const generated = options.discoverModels
+          ? yield* options.discoverModels({ smithyDir })
+          : (yield* fs.readDirectory(smithyDir))
+              .filter(
+                (f) =>
+                  f.endsWith(".json") && !(options.excludeModel?.(f) ?? false),
+              )
+              .map((f) => ({ file: f, dir: smithyDir }));
         const manualDir = options.manualSpecsDir
           ? path.resolve(root, options.manualSpecsDir)
           : undefined;
@@ -115,84 +162,41 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         yield* fs.makeDirectory(outDir, { recursive: true });
 
         const written: string[] = [];
+        const failedModels: string[] = [];
         let totalOps = 0;
-        let totalPatches = 0;
-        let staleOps = 0;
-        const badPatches: string[] = [];
-
-        // Orphan check: a patch directory matching no smithy model would be
-        // silently dropped — flag it instead.
-        const patchRoot =
-          options.patchesDir === false
-            ? undefined
-            : path.join(root, options.patchesDir ?? "patches");
-        if (patchRoot && (yield* fs.exists(patchRoot))) {
-          const resources = new Set(
-            entries.map((e) => e.file.replace(/\.json$/, "")),
-          );
-          for (const dir of yield* fs.readDirectory(patchRoot)) {
-            if (!resources.has(dir)) {
-              yield* Console.warn(
-                `⚠️  patches/${dir}/ matches no smithy model — orphaned?`,
-              );
-            }
-          }
-        }
 
         for (const { file, dir } of entries) {
-          const resource = file.replace(/\.json$/, "");
-          if (config.resource && resource !== config.resource) continue;
-
           const model = JSON.parse(
             yield* fs.readFileString(path.join(dir, file)),
           );
-
-          // Apply the RFC-6902 patch chain before generating. Hand-written
-          // *.manual.json patches apply after the generated ones — they
-          // usually target post-rename shape names.
-          const patchDir = patchRoot && path.join(patchRoot, resource);
-          if (patchDir && (yield* fs.exists(patchDir))) {
-            const patchFiles = (yield* fs.readDirectory(patchDir))
-              .filter((f) => f.endsWith(".json"))
-              .sort(
-                (a, b) =>
-                  Number(a.endsWith(".manual.json")) -
-                    Number(b.endsWith(".manual.json")) || a.localeCompare(b),
-              );
-            for (const pf of patchFiles) {
-              const parsed = JSON.parse(
-                yield* fs.readFileString(path.join(patchDir, pf)),
-              ) as PatchFile;
-              for (const patchOp of parsed.patches ?? []) {
-                try {
-                  applyOperation(model, patchOp);
-                } catch (e) {
-                  const msg = e instanceof Error ? e.message : String(e);
-                  if (isStaleTargetError(msg)) {
-                    staleOps++;
-                    yield* Console.warn(
-                      `   ⚠️  stale: ${resource}/${pf} [${patchOp.op} ${patchOp.path}]`,
-                    );
-                  } else {
-                    badPatches.push(
-                      `${resource}/${pf} [${patchOp.op} ${patchOp.path}]: ${msg}`,
-                    );
-                  }
-                }
-              }
-              totalPatches++;
-            }
-          }
+          // The module's name — the model's filename unless the provider
+          // derives it from the model itself (AWS: the service's sdkId).
+          const resource =
+            options.resourceName?.({ model, file }) ??
+            file.replace(/\.json$/, "");
+          if (config.resource && resource !== config.resource) continue;
 
           if (options.transformModel) {
             const note = options.transformModel(model, resource);
             if (note) yield* Console.log(`   ${note}`);
           }
 
-          const { code, operations } = generateService(
-            model,
-            options.spec(model),
-          );
+          // `generateService` and the provider spec are synchronous and
+          // throw; with continueOnModelError the throw is recorded and the
+          // run moves on, so one broken model doesn't hide the state of
+          // every model after it. The run still fails at the end.
+          let generated;
+          try {
+            generated = generateService(model, options.spec(model));
+          } catch (e) {
+            if (!options.continueOnModelError) throw e;
+            failedModels.push(
+              `${resource}: ${e instanceof Error ? e.message : String(e)}`,
+            );
+            yield* Console.error(`❌ ${resource}`);
+            continue;
+          }
+          const { code, operations } = generated;
           if (operations === 0) continue;
 
           yield* fs.writeFileString(path.join(outDir, `${resource}.ts`), code);
@@ -200,17 +204,6 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
           totalOps += operations;
         }
 
-        if (badPatches.length) {
-          for (const b of badPatches) {
-            yield* Console.error(`❌ bad patch: ${b}`);
-          }
-          return yield* Effect.die(
-            new Error(
-              `${badPatches.length} malformed patch operation(s) — fix or remove them`,
-            ),
-          );
-        }
-
         // Barrel — namespace per resource to avoid op-name collisions.
         //
         // A FULL run is authoritative: the barrel is exactly what was
@@ -224,11 +217,22 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
         // resource without removing anything.
         const barrelPath = path.join(outDir, "index.ts");
         const filtered = config.resource !== "";
-        let resources = written;
+        // Sorted, not in generation order: a provider that discovers models
+        // in some other order (AWS walks Amazon's directory tree) would
+        // otherwise reshuffle the barrel on every run.
+        let resources = [...written].sort((a, b) =>
+          `${a}.json`.localeCompare(`${b}.json`),
+        );
         if (filtered && (yield* fs.exists(barrelPath))) {
+          // Recover the RESOURCE from each export line's path, not its name:
+          // the two differ when barrelExportName renames (AWS exports
+          // `S3` from `./s3.ts`).
           const existing = (yield* fs.readFileString(barrelPath))
             .split("\n")
-            .map((line) => /^export \* as (\S+) from/.exec(line)?.[1])
+            .map(
+              (line) =>
+                /^export \* as \S+ from "\.\/(.+)\.ts";/.exec(line)?.[1],
+            )
             .filter((name): name is string => name !== undefined);
           // Ordered exactly as a full run orders it: by MODEL FILENAME, so
           // the `.json` takes part in the collation (`ai_gateway.json` sorts
@@ -243,19 +247,32 @@ export const runGeneratorCli = (options: GeneratorCliOptions): void => {
           barrelPath,
           barrel(
             `// AUTO-GENERATED by scripts/generate.ts. Do not edit.\n`,
-            resources.map((r) => ({ name: r, path: `./${r}.ts` })),
+            resources.map((r) => ({
+              name: options.barrelExportName?.(r) ?? r,
+              path: `./${r}.ts`,
+            })),
           ),
         );
 
-        yield* formatGenerated(outDir);
+        yield* (options.finalize ?? formatGenerated)(outDir);
 
         yield* Console.log(
-          `\n✅ Generated ${totalOps} operations across ${written.length} resource modules` +
-            (totalPatches
-              ? ` (${totalPatches} patch files applied${staleOps ? `, ${staleOps} stale op(s) skipped` : ""}).`
-              : "."),
+          `\n✅ Generated ${totalOps} operations across ${written.length} resource modules.`,
         );
         yield* Console.log(`   ${path.join(outDir, "index.ts")}`);
+
+        // Models that failed under continueOnModelError. Reported together,
+        // at the end, and the run FAILS — a generate that couldn't produce
+        // a module must not exit 0 with the failure buried in the log.
+        if (failedModels.length) {
+          yield* Console.error(
+            `\n❌ ${failedModels.length} model(s) failed to generate:`,
+          );
+          for (const f of failedModels) yield* Console.error(`   ${f}`);
+          return yield* Effect.die(
+            new Error(`${failedModels.length} model(s) failed to generate`),
+          );
+        }
       }),
   ).pipe(Command.withDescription(options.description));
 

package/src/codegen/emit.ts

@@ -9,7 +9,7 @@
  *     .annotate({ identifier: "X" })
  *     as any as S.Schema<X>;                      // no inference needed
  *
- * plus closed-alias string-union enums, `S.TaggedErrorClass` error classes, and
+ * plus closed-alias string-union enums, `S.TaggedError` error classes, and
  * `API.make(() => ({ … }))` operation consts. The helpers here own those
  * shared skeletons; providers own the content strings (member pipes, trait
  * calls, config fields). Emitted output is normalized by oxfmt afterwards,
@@ -18,11 +18,7 @@
  */
 import { q } from "./naming.ts";
 
-/**
- * The PURE annotation emitted before generated schema consts. A single
- * `/*@__PURE__*​/` — Rolldown 1.1+ warns on the `/*#__PURE__*​/` form
- * (distilled #374).
- */
+/** PURE annotates calls, never property reads. Both @ and # forms are supported. */
 export const PURE = "/*@__PURE__*/ ";
 
 /** `export interface X { … }` (or the empty-body form). */
@@ -101,7 +97,7 @@ export const enumDecl = (o: EnumDeclOptions): string[] => {
   const union = o.values.length ? o.values.map(q).join(" | ") : "string";
   return [
     `export type ${o.name} = ${union};`,
-    `export const ${o.name} = ${o.pure ?? ""}${o.schemaExpr ?? "S.String"};\n`,
+    `export const ${o.name} = ${o.schemaExpr ? `${o.pure ?? ""}${o.schemaExpr}` : "S.String"};\n`,
   ];
 };
 
@@ -120,7 +116,7 @@ export interface ErrorClassOptions {
 }
 
 /**
- * `export class X extends /*@__PURE__*​/ S.TaggedErrorClass<X>()("X", { … }) {}`
+ * `export class X extends /*@__PURE__*​/ S.TaggedError<X>()("X", { … }) {}`
  *
  * The PURE markers are what make an unused error class droppable. A class
  * whose heritage clause is an unannotated call can never be tree-shaken —
@@ -130,12 +126,12 @@ export interface ErrorClassOptions {
  *
  * `wrap` needs its own marker as well as the inner one: a pure call's
  * ARGUMENTS are still evaluated, so annotating only
- * `T.applyErrorMatchers(S.TaggedErrorClass…(…), […])` leaves the inner call
+ * `T.applyErrorMatchers(S.TaggedError…(…), […])` leaves the inner call
  * holding the class alive. Verified against esbuild in both directions.
  */
 export const errorClass = (o: ErrorClassOptions): string => {
   const annotations = o.annotations ? `,\n${o.annotations}` : "";
-  const cls = `${PURE}S.TaggedErrorClass<${o.name}>()(${q(o.tag ?? o.name)}, {\n${o.fields.join("\n")}\n}${annotations})${o.pipes ?? ""}`;
+  const cls = `${PURE}S.TaggedError<${o.name}>()(${q(o.tag ?? o.name)}, {\n${o.fields.join("\n")}\n}${annotations})${o.pipes ?? ""}`;
   const body = o.wrap ? `${PURE}${o.wrap(cls)}` : cls;
   return `export class ${o.name} extends ${body} {}\n`;
 };

package/src/codegen/generator.ts

@@ -55,6 +55,10 @@ import {
 } from "./operations.ts";
 import { memberBases, smithyWireName } from "./members.ts";
 import { validatePaginated } from "./pagination.ts";
+import {
+  booleanStringEnums,
+  STRING_ENCODED_TRAIT,
+} from "./boolean-string-enums.ts";
 
 const PAGINATED_TRAIT = "smithy.api#paginated";
 
@@ -447,6 +451,9 @@ export const generateService = (
   model: any,
   spec: SdkSpec,
 ): GeneratedService => {
+  // `"true" | "false"` request members become real booleans that travel as
+  // their string spelling (see boolean-string-enums.ts).
+  booleanStringEnums(model);
   const shapes: ShapeMap = model.shapes;
   const pure = spec.pure ?? PURE;
   const prelude = spec.prelude ?? JSON_PRELUDE;
@@ -487,8 +494,27 @@ export const generateService = (
   const order = topoOrder(shapes, reachable, shapeDeps);
   const indexOf = orderIndex(order);
 
-  const ref = makeSchemaRef(prelude, indexOf);
-  const tsRef = makeTsRef(tsPrelude);
+  /**
+   * Shape id → the id whose emitted body it shares.
+   *
+   * Structural aliasing (see the struct emission below) has to cascade: a
+   * parent only matches another parent if their MEMBERS render identically,
+   * and a member renders as its target's name. So every reference resolves
+   * through this map first — once `…ItemGroupRuleGroup` is aliased onto a
+   * canonical shape, the parents referencing it start rendering the same
+   * text and collapse in turn.
+   *
+   * Filled in topological order, so a canonical target is always a shape
+   * that was already emitted — a back-reference, never a forward one.
+   */
+  const canonicalId = new Map<string, string>();
+  const canon = (target: string): string => canonicalId.get(target) ?? target;
+
+  const rawRef = makeSchemaRef(prelude, indexOf);
+  const rawTsRef = makeTsRef(tsPrelude);
+  const ref = (target: string, selfIdx: number) =>
+    rawRef(canon(target), selfIdx);
+  const tsRef = (target: string) => rawTsRef(canon(target));
 
   // Direction classification for enum openness. Enum ALIASES are emitted
   // CLOSED (exhaustively matchable on reads); request-reachable shapes
@@ -529,7 +555,8 @@ export const generateService = (
    * pure response/error shapes stay the plain closed alias, and so do
    * union-arm discriminant literals.
    */
-  const tsRefAt = (target: string, ownerId: string): string => {
+  const tsRefAt = (rawTarget: string, ownerId: string): string => {
+    const target = canon(rawTarget);
     const base = tsRef(target);
     if (!requestReachable.has(ownerId)) return base;
     if (discriminantEnums.has(target)) return base;
@@ -605,6 +632,50 @@ export const generateService = (
       };
     });
 
+  /** The single value a one-value enum shape fixes, if `target` is one. */
+  const soleEnumValue = (target: string): string | undefined => {
+    const d = shapes[target];
+    if (d?.type !== "enum") return undefined;
+    const values = Object.values(d.members ?? {}).map(
+      (m: any) => m.traits?.["smithy.api#enumValue"],
+    );
+    return values.length === 1 && typeof values[0] === "string"
+      ? values[0]
+      : undefined;
+  };
+
+  /**
+   * The member every case of a union pins to a different literal — the tag
+   * the API itself discriminates by (`type: "zone"`, `id: "browser_check"`).
+   * Undefined unless every case is a structure carrying that member and no
+   * two cases claim the same value.
+   */
+  const unionDiscriminator = (
+    caseTargets: readonly string[],
+  ): { key: string; values: string[] } | undefined => {
+    if (caseTargets.length < 2) return undefined;
+    const perCase = caseTargets.map((t) => {
+      const cd = shapes[t];
+      if (cd?.type !== "structure") return undefined;
+      const tags = new Map<string, string>();
+      for (const mi of memberInfos(cd)) {
+        const value = soleEnumValue(mi.target);
+        if (value !== undefined) tags.set(mi.tsName, value);
+      }
+      return tags;
+    });
+    if (perCase.some((tags) => tags === undefined || tags.size === 0)) {
+      return undefined;
+    }
+    for (const key of perCase[0]!.keys()) {
+      const values = perCase.map((tags) => tags!.get(key));
+      if (values.some((v) => v === undefined)) continue;
+      if (new Set(values).size !== values.length) continue;
+      return { key, values: values as string[] };
+    }
+    return undefined;
+  };
+
   // Generic pipes for the smithy bindings (the SDK's traits module exports
   // core's Label/Query/Header/HttpBody/Body builders under these names);
   // provider bindings and member traits append theirs via memberExtraPipes.
@@ -648,6 +719,7 @@ export const generateService = (
           ([trait, builder]) =>
             `${builder}(${JSON.stringify(info.traits[trait])})`,
         ),
+      ...(STRING_ENCODED_TRAIT in info.traits ? ["T.StringEncoded()"] : []),
       ...(spec.memberExtraPipes?.(info) ?? []),
     ]);
 
@@ -731,6 +803,13 @@ export const generateService = (
 
   // 4. Error classes from the operations' errors lists.
   const out: string[] = [];
+  // Emitted struct body → the name that owns it, for structural aliasing.
+  // Keyed on the emitted TEXT, so two shapes collapse only when what they
+  // would emit is byte-identical — including member names, targets, docs and
+  // pipes. References are already resolved to names at this point, so a
+  // difference anywhere in the tree shows up as different text.
+  const structBodies = new Map<string, { id: string; name: string }>();
+  let aliased = 0;
   // Set when any error carries CATEGORY_TRAIT, so the header only imports
   // the category module when something actually uses it.
   let usesCategories = false;
@@ -866,7 +945,6 @@ export const generateService = (
         fields.push(...inject.interfaceLines);
         members.push(inject.structLine);
       }
-      out.push(interfaceDecl(name, fields));
       const struct = members.length
         ? `S.Struct({\n${members.join("\n")}\n})`
         : `S.Struct({})`;
@@ -884,26 +962,65 @@ export const generateService = (
           : []),
       ];
       const tail = pipes.map((p) => `.pipe(${p})`).join("");
+
+      // Shapes whose emitted body is byte-identical are one shape wearing
+      // many names. The docs pipelines generate a fresh copy of every nested
+      // shape per operation, so cloudflare's zero_trust carries 374 copies of
+      // `{ group?: unknown }` — one per operation x application type x
+      // include/exclude/require — and 72% of its 16,800 structures are
+      // redundant that way.
+      //
+      // Emit the body once and alias the rest to it. The public name is kept,
+      // so nothing about the surface changes; only the duplicate bodies go.
+      // Operation I/O is excluded: those carry the operation's Http trait and
+      // must never be merged onto one another.
+      const bodyKey = `${JSON.stringify(fields)}|${struct}${tail}`;
+      const canonical = structCtx.isOpIo
+        ? undefined
+        : structBodies.get(bodyKey);
+      if (canonical !== undefined) {
+        out.push(`export type ${name} = ${canonical.name};`);
+        out.push(`export const ${name} = ${canonical.name};\n`);
+        // Later shapes referencing this one now render the canonical name,
+        // which is what lets their bodies collapse too.
+        canonicalId.set(id, canonical.id);
+        aliased++;
+      } else {
+        if (!structCtx.isOpIo) {
+          structBodies.set(bodyKey, { id, name });
+        }
+        out.push(interfaceDecl(name, fields));
+        out.push(
+          suspendConst({
+            name,
+            pure,
+            multiline: true,
+            annotateIdentifier: true,
+            expr: `${struct}${tail}`,
+          }),
+        );
+      }
+    } else if (d.type === "list") {
+      const nullable =
+        spec.nullableTrait !== undefined &&
+        spec.nullableTrait in (d.member.traits ?? {});
+      const item = ref(d.member.target, i);
       out.push(
-        suspendConst({
-          name,
-          pure,
-          multiline: true,
-          annotateIdentifier: true,
-          expr: `${struct}${tail}`,
-        }),
+        `export type ${name} = Array<${tsRefAt(d.member.target, id)}${nullable ? " | null" : ""}>;`,
       );
-    } else if (d.type === "list") {
-      out.push(`export type ${name} = Array<${tsRefAt(d.member.target, id)}>;`);
       out.push(
-        `export const ${name} = ${pure}S.Array(${ref(d.member.target, i)}) as any as S.Schema<${name}>;\n`,
+        `export const ${name} = ${pure}S.Array(${nullable ? `S.NullOr(${item})` : item}) as any as S.Schema<${name}>;\n`,
       );
     } else if (d.type === "map") {
+      const nullable =
+        spec.nullableTrait !== undefined &&
+        spec.nullableTrait in (d.value.traits ?? {});
+      const value = ref(d.value.target, i);
       out.push(
-        `export type ${name} = { [key: string]: ${tsRefAt(d.value.target, id)} | undefined };`,
+        `export type ${name} = { [key: string]: ${tsRefAt(d.value.target, id)}${nullable ? " | null" : ""} | undefined };`,
       );
       out.push(
-        `export const ${name} = ${pure}S.Record(S.String, ${ref(d.value.target, i)}) as any as S.Schema<${name}>;\n`,
+        `export const ${name} = ${pure}S.Record(S.String, ${nullable ? `S.NullOr(${value})` : value}) as any as S.Schema<${name}>;\n`,
       );
     } else if (d.type === "union") {
       // A union arm targeting the union itself carries no information
@@ -923,9 +1040,10 @@ export const generateService = (
       if (spec.union) {
         out.push(...spec.union({ name, caseTargets, caseKeys, tsRef }));
       } else if (spec.unionStyle === "opaque-cases") {
+        const disc = unionDiscriminator(caseTargets);
         out.push(
           `export type ${name} = ${caseTargets.map((t) => tsRefAt(t, id)).join(" | ") || "unknown"};`,
-          `export const ${name} = ${pure}S.Unknown.pipe(T.UnionCases(${JSON.stringify(caseKeys)}));\n`,
+          `export const ${name} = ${pure}S.Unknown.pipe(T.UnionCases(${JSON.stringify(caseKeys)}${disc ? `, ${JSON.stringify(disc)}` : ""}));\n`,
         );
       } else {
         throw new Error(
@@ -947,7 +1065,7 @@ export const generateService = (
       const union = values.length ? values.join(" | ") : "number";
       out.push(
         `export type ${name} = ${union};`,
-        `export const ${name} = ${pure}S.Number;\n`,
+        `export const ${name} = S.Number;\n`,
       );
     }
   });
@@ -975,14 +1093,26 @@ export const generateService = (
     // No items path: `.items()` is a page passthrough at runtime, so an
     // item IS a whole response.
     if (!itemsPath) return tsRef(outputId);
-    let def = shapes[outputId];
+    let id: string = outputId;
+    // Whether the path crossed a list on the way down (`"edges.node"` on a
+    // Relay connection). When it did, the path itself is what fans out, so
+    // the value it lands on IS one item — it needn't be a list again.
+    let fannedOut = false;
     for (const segment of itemsPath.split(".")) {
+      let def: any = shapes[id];
+      if (def?.type === "list") {
+        id = def.member.target as string;
+        def = shapes[id];
+        fannedOut = true;
+      }
       if (def?.type !== "structure") return undefined;
       const info = memberInfos(def).find((m) => m.tsName === segment);
       if (!info) return undefined;
-      def = shapes[info.target];
+      id = info.target;
     }
-    return def?.type === "list" ? tsRef(def.member.target) : undefined;
+    const last: any = shapes[id];
+    if (last?.type === "list") return tsRef(last.member.target);
+    return fannedOut ? tsRef(id) : undefined;
   };
 
   const emitOperation =