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

package/lib/codegen/generator.js

@@ -0,0 +1,813 @@
+/**
+ * The generic smithy→SDK service generator (dev-time only).
+ *
+ * One driver compiles a Smithy JSON model into an Effect SDK service module.
+ * Everything provider-specific arrives through {@link SdkSpec}: import
+ * header, trait vocabulary (which trait ids mean payload/file/nullable/…),
+ * the `T.*` pipe expressions to emit for each binding, how operations are
+ * declared (protocol/retry/error names), and naming policies. The driver
+ * owns the pipeline: operation discovery, reachability, topological order,
+ * schema/interface emission, error classes, pagination validation, and
+ * operation consts.
+ *
+ * A provider's `scripts/generate.ts` reduces to: load models (its own
+ * pipeline — docs-derived specs, patches, …), define its {@link SdkSpec},
+ * call {@link generateService} per model, write files.
+ */
+import { camel as _camel, local, lowerFirst, oneLine, q, tsKey, upperFirst, } from "./naming.js";
+import { orderIndex, reachableFrom, shapeDeps, topoOrder, } from "./graph.js";
+import { enumDecl, errorClass, errorUnionAlias, interfaceDecl, interfaceField, operationConst, PURE, suspendConst, } from "./emit.js";
+import { JSON_PRELUDE, makeSchemaRef, makeTsRef, TS_JSON_PRELUDE, } from "./prelude.js";
+import { collectOperations, collectOpErrorIds, ensureNamedIo, modelNamespace, } from "./operations.js";
+import { memberBases, smithyWireName } from "./members.js";
+import { validatePaginated } from "./pagination.js";
+import { booleanStringEnums, STRING_ENCODED_TRAIT, } from "./boolean-string-enums.js";
+const PAGINATED_TRAIT = "smithy.api#paginated";
+/**
+ * Error categories, derived from the STANDARD Smithy error traits.
+ *
+ * `smithy.api#httpError` and `smithy.api#retryable` are how every Smithy
+ * model — AWS's included — says what kind of failure an error is. The
+ * categories the runtime acts on (`core/category.ts`, and `isTransientError`
+ * in `core/retry.ts`) are a reading of those two traits, so the reading
+ * belongs here, once, for every provider.
+ *
+ * A model that wants its errors classified states the status the API
+ * actually returns:
+ *
+ *   "traits": { "smithy.api#error": "client", "smithy.api#httpError": 404 }
+ *
+ * and the error class is emitted with `.pipe(C.withNotFoundError)`. A model
+ * with no `httpError` gets no categories — the same as today.
+ */
+export const errorCategories = (traits, 
+/** Categories a provider knows that the traits don't say (AWS's spec file). */
+extra = []) => {
+    const categories = [];
+    const add = (name) => {
+        if (!categories.includes(name))
+            categories.push(name);
+    };
+    const status = traits?.["smithy.api#httpError"];
+    if (typeof status === "number") {
+        if (status === 401 || status === 403)
+            add("AuthError");
+        else if (status === 402)
+            add("QuotaError");
+        else if (status === 400 ||
+            status === 404 ||
+            status === 405 ||
+            status === 406 ||
+            status === 410 ||
+            status === 413 ||
+            status === 415 ||
+            status === 422) {
+            add("BadRequestError");
+        }
+        else if (status === 408 || status === 504)
+            add("TimeoutError");
+        else if (status === 409)
+            add("ConflictError");
+        else if (status === 429)
+            add("ThrottlingError");
+        else if (status >= 500 && status < 600)
+            add("ServerError");
+    }
+    const retryable = traits?.["smithy.api#retryable"];
+    if (retryable !== undefined) {
+        add("RetryableError");
+        if (retryable?.throttling)
+            add("ThrottlingError");
+    }
+    for (const name of extra)
+        add(name);
+    return categories;
+};
+/** `["NotFoundError"]` → `C.withNotFoundError`. */
+const categoryPipes = (traits) => errorCategories(traits).map((name) => `C.with${name}`);
+/** Compile one Smithy model into a service module. */
+export const generateService = (model, spec) => {
+    // `"true" | "false"` request members become real booleans that travel as
+    // their string spelling (see boolean-string-enums.ts).
+    booleanStringEnums(model);
+    const shapes = model.shapes;
+    const pure = spec.pure ?? PURE;
+    const prelude = spec.prelude ?? JSON_PRELUDE;
+    const tsPrelude = spec.tsPrelude ?? TS_JSON_PRELUDE;
+    const memberName = spec.memberName ?? ((n) => n);
+    const opExportName = spec.opExportName ?? lowerFirst;
+    // 1. Operations — synthesize named Request/Response for Unit I/O so every
+    //    operation has an input shape that can carry operation-level traits.
+    const operations = collectOperations(shapes);
+    const httpFor = {}; // input shape id → http trait
+    const ns = modelNamespace(operations, shapes, spec.namespaceFallback ?? "smithy.unknown");
+    const selected = [];
+    for (const op of operations) {
+        selected.push(op);
+        const { input, output } = ensureNamedIo(shapes, op, ns);
+        op.def.__input = input;
+        op.def.__output = output;
+        const http = op.def.traits?.["smithy.api#http"];
+        if (http)
+            httpFor[input] = http;
+    }
+    if (selected.length === 0)
+        return { code: "", operations: 0 };
+    // 2. Reachability + dependencies-first order (cycles suspend at refs).
+    const roots = [
+        ...selected.flatMap((op) => [op.def.__input, op.def.__output]),
+        ...(spec.extraRoots?.(selected, shapes) ?? []),
+    ];
+    const reachable = reachableFrom(shapes, roots, shapeDeps);
+    const order = topoOrder(shapes, reachable, shapeDeps);
+    const indexOf = orderIndex(order);
+    /**
+     * 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();
+    const canon = (target) => canonicalId.get(target) ?? target;
+    const rawRef = makeSchemaRef(prelude, indexOf);
+    const rawTsRef = makeTsRef(tsPrelude);
+    const ref = (target, selfIdx) => rawRef(canon(target), selfIdx);
+    const tsRef = (target) => rawTsRef(canon(target));
+    // Direction classification for enum openness. Enum ALIASES are emitted
+    // CLOSED (exhaustively matchable on reads); request-reachable shapes
+    // re-open enum references inline (`X | (string & {})`) so consumers can
+    // send tomorrow's values without an SDK update.
+    const requestReachable = reachableFrom(shapes, selected.map((op) => op.def.__input), shapeDeps);
+    // Discriminant enums: single-value enums required by a union-arm
+    // structure (e.g. the worker binding `type: "ai"` literals). These stay
+    // CLOSED even on the request side — consumers and the union's TS
+    // narrowing rely on the exact literal (v0 parity).
+    const discriminantEnums = new Set();
+    for (const d of Object.values(shapes)) {
+        if (d?.type !== "union")
+            continue;
+        for (const um of Object.values(d.members ?? {})) {
+            const arm = shapes[um.target];
+            if (arm?.type !== "structure")
+                continue;
+            for (const am of Object.values(arm.members ?? {})) {
+                const t = shapes[am.target];
+                if ((t?.type === "enum" || t?.type === "intEnum") &&
+                    Object.keys(t.members ?? {}).length === 1 &&
+                    am.traits?.["smithy.api#required"] !== undefined) {
+                    discriminantEnums.add(am.target);
+                }
+            }
+        }
+    }
+    /**
+     * TS reference with direction-aware enum openness. Any reference inside a
+     * request-reachable shape re-opens the enum inline — including shapes
+     * shared with responses (a value you can SEND must accept undocumented
+     * members, and response runtime is open regardless). References inside
+     * pure response/error shapes stay the plain closed alias, and so do
+     * union-arm discriminant literals.
+     */
+    const tsRefAt = (rawTarget, ownerId) => {
+        const target = canon(rawTarget);
+        const base = tsRef(target);
+        if (!requestReachable.has(ownerId))
+            return base;
+        if (discriminantEnums.has(target))
+            return base;
+        const d = shapes[target];
+        if (d?.type === "enum")
+            return `${base} | (string & {})`;
+        if (d?.type === "intEnum")
+            return `${base} | (number & {})`;
+        return base;
+    };
+    const wireKind = spec.wireKind ??
+        ((b) => b === "label"
+            ? "label"
+            : b === "query"
+                ? "query"
+                : b === "header"
+                    ? "header"
+                    : "other");
+    // The generic binding cascade; provider bindings slot in after headers.
+    const extraBindingOf = (traits) => {
+        for (const b of spec.extraBindings ?? []) {
+            if (b.trait in traits)
+                return b.binding;
+        }
+        return undefined;
+    };
+    const bindingOf = (traits) => "smithy.api#httpLabel" in traits
+        ? "label"
+        : "smithy.api#httpQuery" in traits
+            ? "query"
+            : "smithy.api#httpHeader" in traits
+                ? "header"
+                : (extraBindingOf(traits) ??
+                    ("smithy.api#httpPayload" in traits ? "rawBody" : "body"));
+    // Shapes reachable from any response/error root — used to scope the
+    // blanket-nullable-optionals rule to reads (the wire returns explicit
+    // nulls; requests only accept null where a nullable trait says so).
+    const responseReachable = spec.optionalsNullable === true
+        ? reachableFrom(shapes, [
+            ...selected.map((op) => op.def.__output),
+            ...collectOpErrorIds(selected, shapes),
+        ], shapeDeps)
+        : undefined;
+    const memberInfos = (d, ownerId) => memberBases(d, memberName).map((base) => {
+        const traits = base.traits;
+        const binding = bindingOf(traits);
+        return {
+            ...base,
+            binding,
+            wire: smithyWireName(traits, base.name, wireKind(binding)),
+            nullable: (spec.nullableTrait ? spec.nullableTrait in traits : false) ||
+                // Blanket-nullable optionals (v0 surface): every optional BODY
+                // member of a response-reachable shape accepts/announces null
+                // in addition to being omittable.
+                (responseReachable !== undefined &&
+                    ownerId !== undefined &&
+                    responseReachable.has(ownerId) &&
+                    !base.required &&
+                    binding === "body"),
+        };
+    });
+    /** The single value a one-value enum shape fixes, if `target` is one. */
+    const soleEnumValue = (target) => {
+        const d = shapes[target];
+        if (d?.type !== "enum")
+            return undefined;
+        const values = Object.values(d.members ?? {}).map((m) => 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) => {
+        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();
+            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 };
+        }
+        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.
+    const genericPipes = (info) => {
+        switch (info.binding) {
+            case "label":
+                return [
+                    info.wire === info.tsName ? "T.Label()" : `T.Label(${q(info.wire)})`,
+                ];
+            case "query":
+                return [
+                    info.wire === info.tsName ? "T.Query()" : `T.Query(${q(info.wire)})`,
+                ];
+            case "header":
+                return [
+                    info.wire === info.tsName
+                        ? "T.Header()"
+                        : `T.Header(${q(info.wire)})`,
+                ];
+            case "rawBody":
+                return ["T.HttpBody()"];
+            case "body":
+                return info.wire !== info.tsName ? [`T.Body(${q(info.wire)})`] : [];
+            default:
+                return [];
+        }
+    };
+    const memberPipes = spec.memberPipes ??
+        ((info) => [
+            ...genericPipes(info),
+            // The binding table's pipe (envelope payloads, file uploads, …).
+            ...(spec.extraBindings ?? [])
+                .filter((b) => b.binding === info.binding && b.trait in info.traits)
+                .map((b) => b.pipe),
+            // Trait-table pipes: trait value JSON-inlined as the argument.
+            ...Object.entries(spec.memberTraitPipes ?? {})
+                .filter(([trait]) => info.traits[trait] !== undefined)
+                .map(([trait, builder]) => `${builder}(${JSON.stringify(info.traits[trait])})`),
+            ...(STRING_ENCODED_TRAIT in info.traits ? ["T.StringEncoded()"] : []),
+            ...(spec.memberExtraPipes?.(info) ?? []),
+        ]);
+    const memberTsTypeOf = (info, tsRefFn) => spec.memberTsType?.(info, tsRefFn) ??
+        (spec.extraBindings ?? []).find((b) => b.binding === info.binding && b.tsType !== undefined)?.tsType;
+    const emitMember = (info, selfIdx) => {
+        let expr = ref(info.target, selfIdx);
+        if (info.nullable)
+            expr = `S.NullOr(${expr})`;
+        const pipes = memberPipes(info);
+        if (pipes.length)
+            expr = `${expr}.pipe(${pipes.join(", ")})`;
+        if (!info.required)
+            expr = `S.optional(${expr})`;
+        return `  ${q(info.tsName)}: ${expr},`;
+    };
+    const opIoShapes = new Set();
+    for (const op of selected) {
+        opIoShapes.add(op.def.__input);
+        opIoShapes.add(op.def.__output);
+    }
+    // 3. Validate pagination traits: a paginated op must actually carry its
+    //    token on the input and its items member on the output, else it
+    //    degrades to a plain operation.
+    const paginatedOutputs = new Set();
+    const paginatedItemsRoot = new Map();
+    /** Op id → its full (possibly dotted) items path, `""` when it has none. */
+    const paginatedItemsPath = new Map();
+    /** Output shape id → the pagination profile that decodes it. */
+    const outputProfile = new Map();
+    /** Op id → its pagination profile (drives protocol/strategy emission). */
+    const opProfile = new Map();
+    const usedProfiles = new Set();
+    const profileNames = Object.keys(spec.paginationProfiles ?? {});
+    if (profileNames.length > 0) {
+        for (const op of selected) {
+            const pg = op.def.traits?.[PAGINATED_TRAIT];
+            if (!pg)
+                continue;
+            // Which profile decodes this op's pages: the selector's answer, or
+            // the sole declared profile.
+            const profileName = spec.paginationProfileFor?.(pg, op) ??
+                (profileNames.length === 1 ? profileNames[0] : undefined);
+            const profile = profileName
+                ? spec.paginationProfiles[profileName]
+                : undefined;
+            if (!profile)
+                continue;
+            const inNames = new Set(memberInfos(shapes[op.def.__input] ?? {}).map((m) => m.tsName));
+            const outNames = new Set(memberInfos(shapes[op.def.__output] ?? {}).map((m) => m.tsName));
+            const { ok, itemsRoot } = validatePaginated({
+                trait: pg,
+                inputNames: inNames,
+                outputNames: outNames,
+                itemsFallback: profile.itemsFallback,
+                syntheticOutputs: new Set(profile.syntheticOutputs ?? []),
+            });
+            if (ok) {
+                op.def.__pagination = pg;
+                paginatedOutputs.add(op.def.__output);
+                paginatedItemsRoot.set(op.def.__output, itemsRoot);
+                paginatedItemsPath.set(op.id, String(pg.items ?? profile.itemsFallback ?? ""));
+                outputProfile.set(op.def.__output, profile);
+                opProfile.set(op.id, profile);
+                usedProfiles.add(profile);
+            }
+        }
+    }
+    // 4. Error classes from the operations' errors lists.
+    const out = [];
+    // 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();
+    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;
+    const errorIds = collectOpErrorIds(selected, shapes);
+    const errorIdSet = new Set(errorIds);
+    const errorNames = new Set(errorIds.map(local));
+    const shapeDocs = spec.shapeDocs ?? true;
+    for (const id of errorIds) {
+        const d = shapes[id];
+        const name = local(id);
+        const doc = oneLine(d.traits?.["smithy.api#documentation"]);
+        if (doc && shapeDocs)
+            out.push(`/** ${doc} */`);
+        const overridden = spec.errors?.override?.({ id, def: d, name });
+        if (overridden) {
+            out.push(...overridden);
+            continue;
+        }
+        const errorField = spec.errors?.field ??
+            ((mn, target) => `  ${tsKey(mn)}: ${prelude[local(target)] ?? "S.Unknown"},`);
+        const fields = d.members && Object.keys(d.members).length
+            ? Object.entries(d.members).map(([mn, m]) => errorField(mn, m.target))
+            : (spec.errors?.defaultFields?.(prelude) ?? [
+                errorField("code", "smithy.api#Integer"),
+                errorField("message", "smithy.api#String"),
+            ]);
+        const matchers = spec.errorMatchersTrait
+            ? d.traits?.[spec.errorMatchersTrait]
+            : undefined;
+        const categories = categoryPipes(d.traits);
+        if (categories.length)
+            usesCategories = true;
+        out.push(errorClass({
+            name,
+            fields,
+            pipes: categories.length
+                ? `.pipe(${categories.join(", ")})`
+                : undefined,
+            wrap: spec.errors?.wrap?.(d.traits ?? {}) ??
+                (matchers
+                    ? (cls) => `T.applyErrorMatchers(\n${cls},\n${JSON.stringify(matchers)},\n)`
+                    : undefined),
+        }));
+    }
+    // 5. Every reachable shape in dependency order: explicit TS type next to
+    //    a schema const cast to `S.Schema<T>` (the compile-perf pattern).
+    order.forEach((id, i) => {
+        if (errorIdSet.has(id))
+            return; // emitted as an error class above
+        const d = shapes[id];
+        const name = local(id);
+        const doc = oneLine(d.traits?.["smithy.api#documentation"]);
+        if (doc && shapeDocs)
+            out.push(`/** ${doc} */`);
+        const override = spec.shapeOverride?.({
+            id,
+            def: d,
+            name,
+            selfIdx: i,
+            ref,
+            tsRef,
+            members: memberInfos,
+        });
+        if (override) {
+            out.push(...override);
+            return;
+        }
+        if (d.type === "structure") {
+            // Bare-payload response: single trait-marked member — the response IS
+            // that member's value; emit its type + a root marker for the protocol.
+            const memberEntriesAll = Object.entries(d.members ?? {});
+            const soleMemberRoot = !paginatedOutputs.has(id) && memberEntriesAll.length === 1
+                ? (spec.extraBindings ?? []).find((b) => b.rootPipe !== undefined &&
+                    b.trait in (memberEntriesAll[0][1].traits ?? {}))
+                : undefined;
+            if (soleMemberRoot) {
+                const [, m] = memberEntriesAll[0];
+                // Alias responses are op roots too — they must carry the service
+                // key dictionary so opaque content (union cases, freeform maps)
+                // nested in the payload decodes with the same wire mapping as
+                // struct-form roots.
+                const rootPipes = [
+                    soleMemberRoot.rootPipe,
+                    ...(spec.rootKeyDictionary && opIoShapes.has(id)
+                        ? [`T.KeyDictionary(KEY_DICTIONARY)`]
+                        : []),
+                ];
+                out.push(`export type ${name} = ${tsRef(m.target)};`);
+                out.push(suspendConst({
+                    name,
+                    pure,
+                    multiline: true,
+                    annotateIdentifier: true,
+                    expr: `${ref(m.target, i)}.pipe(${rootPipes.join(", ")})`,
+                }));
+                return;
+            }
+            // Paginated outputs always deliver their items member — required.
+            const itemsRoot = paginatedItemsRoot.get(id);
+            const infos = memberInfos(d, id).map((info) => info.tsName === itemsRoot ? { ...info, required: true } : info);
+            const fields = infos.flatMap((info) => interfaceField({
+                name: info.tsName,
+                optional: !info.required,
+                doc: info.doc,
+                type: memberTsTypeOf(info, tsRef) ??
+                    `${tsRefAt(info.target, id)}${info.nullable ? " | null" : ""}`,
+            }));
+            const members = infos.map((info) => emitMember(info, i));
+            const inject = outputProfile.get(id)?.injectOutputMember;
+            if (inject && !infos.some((m) => m.tsName === inject.tsName)) {
+                fields.push(...inject.interfaceLines);
+                members.push(inject.structLine);
+            }
+            const struct = members.length
+                ? `S.Struct({\n${members.join("\n")}\n})`
+                : `S.Struct({})`;
+            const structCtx = {
+                id,
+                isOpIo: opIoShapes.has(id),
+                httpTrait: httpFor[id],
+            };
+            const pipes = spec.structPipes?.(structCtx) ?? [
+                ...(structCtx.httpTrait
+                    ? [`T.Http(${JSON.stringify(structCtx.httpTrait)})`]
+                    : []),
+                ...(spec.rootKeyDictionary && structCtx.isOpIo
+                    ? [`T.KeyDictionary(KEY_DICTIONARY)`]
+                    : []),
+            ];
+            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(`export type ${name} = Array<${tsRefAt(d.member.target, id)}${nullable ? " | null" : ""}>;`);
+            out.push(`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)}${nullable ? " | null" : ""} | undefined };`);
+            out.push(`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
+            // (`type X = X | A | B` ≡ `A | B`) and is an illegal circular type
+            // alias. Specs produce them: atlas's OnlineArchiveSchedule is a
+            // discriminated oneOf whose DEFAULT arm is `allOf: [$ref <the union
+            // itself>]`, so the arm resolves back to its own parent.
+            const caseTargets = Object.values(d.members ?? {})
+                .map((m) => m.target)
+                .filter((t) => t !== id);
+            const caseKeys = caseTargets.map((t) => {
+                const cd = shapes[t];
+                return cd?.type === "structure"
+                    ? memberInfos(cd).map((mi) => mi.tsName)
+                    : [];
+            });
+            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)}${disc ? `, ${JSON.stringify(disc)}` : ""}));\n`);
+            }
+            else {
+                throw new Error(`no union emission configured for shape ${id} — set unionStyle or union`);
+            }
+        }
+        else if (d.type === "enum") {
+            const values = Object.values(d.members ?? {})
+                .map((m) => m.traits?.["smithy.api#enumValue"])
+                .filter((v) => typeof v === "string");
+            out.push(...enumDecl({ name, values, pure }));
+        }
+        else if (d.type === "intEnum") {
+            // CLOSED numeric literal union alias (`type Y = 1 | 30`); INPUT
+            // references re-open it inline (`Y | (number & {})`). Schema stays
+            // S.Number (protocols never validate enum membership).
+            const values = Object.values(d.members ?? {})
+                .map((m) => m.traits?.["smithy.api#enumValue"])
+                .filter((v) => typeof v === "number");
+            const union = values.length ? values.join(" | ") : "number";
+            out.push(`export type ${name} = ${union};`, `export const ${name} = S.Number;\n`);
+        }
+    });
+    // 6. Operations — declarative emission from the names in operationDecl,
+    //    unless the provider overrides the whole shape.
+    /**
+     * The element type `.items()` yields, resolved from the pagination
+     * trait's items PATH against the response shape.
+     *
+     * `makePaginated` can't infer this — the path is a runtime string — and
+     * the structural `API.PaginatedItem` fallback only recognizes bare arrays
+     * and `{ result: […] }` envelopes, so every other envelope degrades to
+     * `unknown` (distilled #302). Resolving it here and passing it as an
+     * explicit type argument is what makes `.items()` typed.
+     *
+     * Returns undefined when the path doesn't lead to a list, which leaves
+     * the annotation on the structural fallback rather than asserting a type
+     * the shape doesn't support.
+     */
+    const paginatedItemTsType = (outputId, itemsPath) => {
+        // No items path: `.items()` is a page passthrough at runtime, so an
+        // item IS a whole response.
+        if (!itemsPath)
+            return tsRef(outputId);
+        let id = 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 = shapes[id];
+            if (def?.type === "list") {
+                id = def.member.target;
+                def = shapes[id];
+                fannedOut = true;
+            }
+            if (def?.type !== "structure")
+                return undefined;
+            const info = memberInfos(def).find((m) => m.tsName === segment);
+            if (!info)
+                return undefined;
+            id = info.target;
+        }
+        const last = shapes[id];
+        if (last?.type === "list")
+            return tsRef(last.member.target);
+        return fannedOut ? tsRef(id) : undefined;
+    };
+    const emitOperation = spec.operation ??
+        ((ctx) => {
+            const decl = spec.operationDecl;
+            if (!decl) {
+                throw new Error("SdkSpec needs either operationDecl or operation");
+            }
+            const errList = [...ctx.errorNames, ...decl.commonErrorClasses];
+            const paginated = ctx.pagination !== undefined;
+            const itemTsType = paginated
+                ? paginatedItemTsType(ctx.op.def.__output, paginatedItemsPath.get(ctx.op.id) ?? "")
+                : undefined;
+            const typeAnnotation = `API.${paginated ? "PaginatedOperationMethod" : "OperationMethod"}<\n` +
+                `  ${ctx.inputName},\n` +
+                `  ${ctx.outputTsType},\n` +
+                `  ${ctx.opName}Error,\n` +
+                `  ${decl.contextType}` +
+                (itemTsType ? `,\n  ${itemTsType}\n` : `\n`) +
+                `>`;
+            const config = `{\n` +
+                `  input: ${ctx.inputName},\n` +
+                `  output: ${ctx.outputSchema},\n` +
+                `  errors: [${errList.join(", ")}],\n` +
+                `  protocol: ${(paginated && opProfile.get(ctx.op.id)?.protocol) || decl.protocol},\n` +
+                `  retry: ${decl.retry},\n` +
+                (decl.extraConfig?.(ctx) ?? []).map((l) => `  ${l},\n`).join("") +
+                (paginated
+                    ? `  pagination: ${JSON.stringify(ctx.pagination)} as const,\n`
+                    : "") +
+                `}`;
+            return [
+                errorUnionAlias(ctx.opName, ctx.errorNames, decl.commonErrorType),
+                ...(ctx.doc ? [`/** ${ctx.doc} */`] : []),
+                operationConst({
+                    exportName: ctx.exportName,
+                    typeAnnotation,
+                    factory: paginated ? "API.makePaginated" : "API.make",
+                    pure,
+                    extraArg: paginated ? opProfile.get(ctx.op.id)?.strategy : undefined,
+                    config,
+                    // `makePaginated` infers the items element from the structural
+                    // fallback; an explicit item type needs the same `as any as`
+                    // idiom the schema consts use.
+                    castToAnnotation: itemTsType !== undefined,
+                }),
+            ].join("\n");
+        });
+    for (const op of selected) {
+        const opName = local(op.id);
+        const errNames = (op.def.errors ?? [])
+            .map((e) => local(e.target))
+            .filter((n) => errorNames.has(n));
+        out.push(emitOperation({
+            op,
+            opName,
+            exportName: opExportName(opName),
+            inputName: local(op.def.__input),
+            outputName: local(op.def.__output),
+            outputTsType: tsRef(op.def.__output),
+            outputSchema: ref(op.def.__output, indexOf.size),
+            errorNames: errNames,
+            doc: oneLine(op.def.traits?.["smithy.api#documentation"]),
+            pagination: op.def.__pagination,
+        }));
+    }
+    // 7. Alias re-exports, then provider trailing sections.
+    const emittedOps = new Set(selected.map((op) => opExportName(local(op.id))));
+    for (const { alias, target } of spec.opAliases ?? []) {
+        if (!emittedOps.has(target) || emittedOps.has(alias))
+            continue;
+        emittedOps.add(alias);
+        const A = upperFirst(alias);
+        const T2 = upperFirst(target);
+        out.push(`// Alias of ${target} (same route, alternate export name upstream).\n` +
+            `export const ${alias} = ${target};\n` +
+            `export type ${A}Request = ${T2}Request;\n` +
+            `export type ${A}Response = ${T2}Response;\n` +
+            `export type ${A}Error = ${T2}Error;\n`);
+    }
+    if (spec.footer) {
+        out.push(...spec.footer({ emittedOps }));
+    }
+    // Default header: banner + imports derived from operationDecl names and
+    // the conventional SDK module layout, op error/context type re-exports,
+    // and the KEY_DICTIONARY const when configured.
+    const defaultHeader = (ctx) => {
+        const decl = spec.operationDecl;
+        if (!decl) {
+            throw new Error("the default header needs operationDecl — or pass header");
+        }
+        const retryNs = decl.retry.split(".")[0];
+        // Imports the used pagination profiles pull in: their protocol consts
+        // (from the protocol module) and strategy/injected-member names (from
+        // the pagination module).
+        const profileProtocols = [
+            ...new Set([...usedProfiles]
+                .map((p) => p.protocol)
+                .filter((p) => p !== undefined && p !== decl.protocol)),
+        ];
+        const pagImports = [
+            ...new Set([...usedProfiles].flatMap((p) => [
+                ...(p.strategy ? [p.strategy] : []),
+                ...(p.injectOutputMember?.imports ?? []),
+            ])),
+        ];
+        return (`// AUTO-GENERATED by scripts/generate.ts${spec.sourceNote ? ` from ${spec.sourceNote}` : ""}. Do not edit.\n` +
+            `import * as S from "@distilled.cloud/core/schema";\n` +
+            `import * as API from "@distilled.cloud/core/api";\n` +
+            (usesCategories
+                ? `import * as C from "@distilled.cloud/core/category";\n`
+                : "") +
+            `import * as T from "../traits.ts";\n` +
+            `import {\n` +
+            `  ${decl.protocol},\n` +
+            profileProtocols.map((p) => `  ${p},\n`).join("") +
+            `  type ${decl.commonErrorType},\n` +
+            `  type ${decl.contextType},\n` +
+            `} from "../protocol.ts";\n` +
+            (ctx.hasPaginated && pagImports.length
+                ? `import { ${pagImports.join(", ")} } from "../pagination.ts";\n`
+                : "") +
+            `import { ${[...decl.commonErrorClasses].sort().join(", ")} } from "../errors.ts";\n` +
+            `import * as ${retryNs} from "../retry.ts";\n\n` +
+            // Re-exported so inferred provider types downstream can always name them.
+            `export type { ${decl.commonErrorType}, ${decl.contextType} };\n\n` +
+            (spec.rootKeyDictionary
+                ? `/** ${spec.rootKeyDictionary.doc} */\n` +
+                    `const KEY_DICTIONARY: Record<string, string | ReadonlyArray<string>> = ${JSON.stringify(spec.rootKeyDictionary.dict)};\n\n`
+                : ""));
+    };
+    const header = (spec.header ?? defaultHeader)({
+        hasPaginated: paginatedOutputs.size > 0,
+        model,
+    });
+    const code = header + out.join("\n") + "\n";
+    return {
+        code: spec.postProcess?.(code) ?? code,
+        operations: selected.length,
+    };
+};
+// Re-exported so provider specs can be written against the same helpers the
+// driver uses, without importing every codegen module individually.
+export { errorUnionAlias, operationConst, upperFirst, tsKey, q, local };
+//# sourceMappingURL=generator.js.map