Upload folder using huggingface_hub (part 3)

api/spec/packages/legacy/src/rest.tsp

@@ -0,0 +1,43 @@
+import "@typespec/rest";
+
+namespace TypeSpec.Rest.Resource {
+  /**
+   * Resource update operation model.
+   * @template Resource The resource model to update with replace.
+   */
+  @friendlyName("{name}ReplaceUpdate", Resource)
+  model ResourceReplaceModel<Resource extends {}>
+    is UpdateableProperties<DefaultKeyVisibility<Resource, Lifecycle.Read>>;
+}
+
+namespace OpenMeter.Rest {
+  /**
+   * Resource create operation model.
+   * @template Resource The resource model to create.
+   */
+  @friendlyName("{name}Create", Resource)
+  @withVisibilityFilter(#{ all: #[Lifecycle.Create] })
+  model ResourceCreateModel<Resource extends {}> {
+    ...Resource;
+  }
+
+  /**
+   * Resource update operation model.
+   * @template Resource The resource model to partially update.
+   */
+  @friendlyName("{name}Update", Resource)
+  @withVisibilityFilter(#{ all: #[Lifecycle.Update] })
+  model ResourceUpdateModel<Resource extends {}> {
+    ...Resource;
+  }
+
+  /**
+   * Resource replace operation model.
+   * @template Resource The resource model to update with replace.
+   */
+  @friendlyName("{name}Replace", Resource)
+  @withVisibilityFilter(#{ any: #[Lifecycle.Create, Lifecycle.Update] })
+  model ResourceReplaceModel<Resource extends {}> {
+    ...Resource;
+  }
+}

api/spec/packages/legacy/src/subjects.tsp

@@ -0,0 +1,156 @@
+import "@typespec/http";
+import "@typespec/rest";
+import "@typespec/openapi3";
+
+using TypeSpec.Http;
+using TypeSpec.OpenAPI;
+
+namespace OpenMeter;
+
+@route("/api/v1/subjects")
+@tag("Subjects")
+@friendlyName("Subjects")
+interface SubjectsEndpoints {
+  /**
+   * List subjects.
+   *
+   * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+   */
+  #deprecated "Subjects as entities are being depracated, use customers instead"
+  #suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+  @get
+  @operationId("listSubjects")
+  @summary("List subjects")
+  list(): Subject[] | CommonErrors;
+
+  /**
+   * Get subject by ID or key.
+   *
+   * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+   */
+  #deprecated "Subjects as entities are being depracated, use customers instead"
+  #suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+  @get
+  @operationId("getSubject")
+  @summary("Get subject")
+  get(@path subjectIdOrKey: string): Subject | NotFoundError | CommonErrors;
+
+  /**
+   * Upserts a subject. Creates or updates subject.
+   *
+   * If the subject doesn't exist, it will be created.
+   * If the subject exists, it will be partially updated with the provided fields.
+   *
+   * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+   */
+  #deprecated "Subjects as entities are being depracated, use customers instead"
+  #suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+  @post
+  @operationId("upsertSubject")
+  @summary("Upsert subject")
+  upsert(@body subject: SubjectUpsert[]): Subject[] | CommonErrors;
+
+  /**
+   * Delete subject by ID or key.
+   *
+   * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+   */
+  #deprecated "Subjects as entities are being depracated, use customers instead"
+  #suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+  @delete
+  @operationId("deleteSubject")
+  @summary("Delete subject")
+  delete(@path subjectIdOrKey: string): void | CommonErrors;
+}
+
+/**
+ * A subject is a unique identifier for a usage attribution by its key.
+ * Subjects only exist in the concept of metering.
+ * Subjects are optional to create and work as an enrichment for the subject key like displayName, metadata, etc.
+ * Subjects are useful when you are reporting usage events with your own database ID but want to enrich the subject with a human-readable name or metadata.
+ * For most use cases, a subject is equivalent to a customer.
+ *
+ * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+ */
+#deprecated "Use customers instead"
+#suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+@friendlyName("Subject")
+@example(#{
+  createdAt: DateTime.fromISO("2025-01-01T01:01:01.001Z"),
+  updatedAt: DateTime.fromISO("2025-02-01T01:01:01.001Z"),
+  deletedAt: DateTime.fromISO("2025-03-01T01:01:01.001Z"),
+  id: "01G65Z755AFWAKHE12NY0CQ9FH",
+  key: "customer-id",
+  displayName: "Customer Name",
+  metadata: #{ hubspotId: "123456" },
+  stripeCustomerId: "cus_JMOlctsKV8",
+})
+model Subject {
+  ...ResourceTimestamps;
+
+  // Validator doesn't obey required for readOnly properties
+  // See: https://github.com/stoplightio/spectral/issues/1274
+
+  /**
+   * A unique identifier for the subject.
+   */
+  @visibility(Lifecycle.Read)
+  @example("01G65Z755AFWAKHE12NY0CQ9FH")
+  id: ULID;
+
+  /**
+   * A unique, human-readable identifier for the subject.
+   * This is typically a database ID or a customer key.
+   */
+  @example("customer-db-id-123")
+  key: string;
+
+  /**
+   * A human-readable display name for the subject.
+   */
+  @example("Customer Name")
+  displayName?: string | null;
+
+  /**
+   * Metadata for the subject.
+   */
+  @example(#{ hubspotId: "123456" })
+  metadata?: Record<unknown> | null;
+
+  /**
+   * The start of the current period for the subject.
+   */
+  #deprecated "Use Stripe App instead"
+  @example(DateTime.fromISO("2023-01-01T00:00:00Z"))
+  currentPeriodStart?: DateTime;
+
+  /**
+   * The end of the current period for the subject.
+   */
+  #deprecated "Use Stripe App instead"
+  @example(DateTime.fromISO("2023-02-01T00:00:00Z"))
+  currentPeriodEnd?: DateTime;
+
+  /**
+   * The Stripe customer ID for the subject.
+   */
+  #deprecated "Use customer app instead"
+  @example("cus_JMOlctsKV8")
+  stripeCustomerId?: string | null;
+}
+
+/**
+ * A subject is a unique identifier for a user or entity.
+ *
+ * ⚠️ __Deprecated__: Subjects as managable entities are being depracated, use customers with subject key usage attribution instead.
+ */
+#deprecated "Use customers instead"
+#suppress "deprecated" "Subjects APIs will be removed on December 1st, 2025"
+@friendlyName("SubjectUpsert")
+@example(#{
+  key: "customer-id",
+  displayName: "Customer Name",
+  metadata: #{ hubspotId: "123456" },
+  stripeCustomerId: "cus_JMOlctsKV8",
+})
+model SubjectUpsert is TypeSpec.Rest.Resource.ResourceCreateModel<Subject>;

api/spec/packages/legacy/src/types.tsp

@@ -0,0 +1,447 @@
+import "@typespec/openapi3";
+
+using TypeSpec.OpenAPI;
+
+/**
+ * ULID (Universally Unique Lexicographically Sortable Identifier).
+ */
+// See: https://github.com/ulid/spec/issues/94
+@pattern("^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$")
+@example("01G65Z755AFWAKHE12NY0CQ9FH")
+@extension("x-inline", true)
+scalar ULID extends string;
+
+/**
+ * A key is a unique string that is used to identify a resource.
+ */
+@pattern(
+  "^[a-z0-9]+(?:_[a-z0-9]+)*$",
+  "Must start with a lowercase letter or a number. Can contain lowercase letters, numbers, and underscores."
+)
+@minLength(1)
+@maxLength(64)
+@extension("x-inline", true)
+scalar Key extends string;
+
+/**
+ * ExternalKey is a looser version of key.
+ */
+@maxLength(256)
+@minLength(1)
+@extension("x-inline", true)
+scalar ExternalKey extends string;
+
+/**
+ * ULID (Universally Unique Lexicographically Sortable Identifier).
+ * A key is a unique string that is used to identify a resource.
+ *
+ * TODO: this is a temporary solution to support both ULID and Key in the same spec for codegen.
+ */
+@pattern("^[a-z0-9]+(?:_[a-z0-9]+)*$|^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$")
+@minLength(1)
+@maxLength(64)
+@extension("x-inline", true)
+scalar ULIDOrKey extends string;
+
+/**
+ * ULID (Universally Unique Lexicographically Sortable Identifier) or external unique key.
+ */
+@extension("x-go-type", "string")
+@friendlyName("ULIDOrExternalKey")
+union ULIDOrExternalKey {
+  id: ULID,
+  key: ExternalKey,
+}
+
+// NOTE (andras): key format enforcement isn't supported by TypeSpec (patternProperties). See: https://github.com/microsoft/typespec/discussions/1626
+// TODO: decide if we want to use the generated Metadata type instead and update code to use it
+/**
+ * Set of key-value pairs.
+ * Metadata can be used to store additional information about a resource.
+ */
+@extension("x-go-type", "map[string]string")
+@example(#{ externalId: "019142cc-a016-796a-8113-1a942fecd26d" })
+@friendlyName("Metadata")
+model Metadata {
+  ...Record<string>;
+}
+
+/**
+ * [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
+ */
+@encode(DateTimeKnownEncoding.rfc3339)
+@example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+@extension("x-inline", true)
+scalar DateTime extends utcDateTime;
+
+/**
+ * Represents a resource with a key.
+ */
+@friendlyName("KeyedResource")
+model Keyed {
+  /**
+   * A locally unique identifier for the resource.
+   */
+  key: Key;
+}
+
+/**
+ * Represents a resource with a unique key.
+ */
+@friendlyName("UniqueResource")
+model UniqueResource {
+  ...Resource;
+
+  /**
+   * A semi-unique identifier for the resource.
+   */
+  @visibility(Lifecycle.Read, Lifecycle.Create)
+  @summary("Key")
+  key: Key;
+}
+
+/**
+ * IDResource is a resouce with an ID.
+ */
+// NOTE: this can be used to have a type, that we can later replace with the expanded type if needed without
+// breaking api compatibility
+@friendlyName("IDResource")
+model IDResource {
+  /**
+   * A unique identifier for the resource.
+   */
+  @visibility(Lifecycle.Read)
+  @example("01G65Z755AFWAKHE12NY0CQ9FH")
+  @summary("ID")
+  id: ULID;
+}
+
+/**
+ * Represents common fields of resources.
+ */
+@friendlyName("Resource")
+model Resource {
+  /**
+   * A unique identifier for the resource.
+   */
+  @visibility(Lifecycle.Read)
+  @example("01G65Z755AFWAKHE12NY0CQ9FH")
+  @summary("ID")
+  id: ULID;
+
+  /**
+   * Human-readable name for the resource. Between 1 and 256 characters.
+   */
+  @summary("Display name")
+  @minLength(1)
+  @maxLength(256)
+  name: string;
+
+  /**
+   * Optional description of the resource. Maximum 1024 characters.
+   */
+  @maxLength(1024)
+  @summary("Description")
+  description?: string;
+
+  /**
+   * Additional metadata for the resource.
+   */
+  @summary("Metadata")
+  metadata?: Metadata | null;
+
+  ...ResourceTimestamps;
+}
+
+/**
+ * Represents resources that can be cadenced, have scheduled activity changes.
+ */
+@friendlyName("CadencedResource")
+model CadencedResource {
+  /**
+   * The cadence start of the resource.
+   */
+  activeFrom: DateTime;
+
+  /**
+   * The cadence end of the resource.
+   */
+  activeTo?: DateTime;
+}
+
+/**
+ * Collects the timestamps used by all resources.
+ */
+@friendlyName("Timestamps")
+model ResourceTimestamps {
+  /**
+   * Timestamp of when the resource was created.
+   */
+  @summary("Creation Time")
+  @visibility(Lifecycle.Read)
+  @example(DateTime.fromISO("2024-01-01T01:01:01.001Z"))
+  createdAt: DateTime;
+
+  /**
+   * Timestamp of when the resource was last updated.
+   */
+  @summary("Last Update Time")
+  @visibility(Lifecycle.Read)
+  @example(DateTime.fromISO("2024-01-01T01:01:01.001Z"))
+  updatedAt: DateTime;
+
+  /**
+   * Timestamp of when the resource was permanently deleted.
+   */
+  @summary("Deletion Time")
+  @visibility(Lifecycle.Read)
+  @example(DateTime.fromISO("2024-01-01T01:01:01.001Z"))
+  deletedAt?: DateTime;
+}
+
+/**
+ * Represents common fields of resources that can be archived.
+ */
+@friendlyName("Archiveable")
+model Archiveable {
+  /**
+   * Timestamp of when the resource was archived.
+   */
+  @summary("Archival Time")
+  @visibility(Lifecycle.Read)
+  archivedAt?: DateTime;
+}
+
+// This is a reasonably good RE2-safe ISO8601 duration pattern that allows fractional components (though overly permissive)
+// It matches patterns such as
+// - P1Y
+// - P1.5Y
+// - P1Y2M1D
+// - P1Y2MT <= invalid: must have time component defined after T
+// - P1Y2MT1H2S
+// - P1Y2.3MT1.4H2S <= invalid: spec only allows for a single fractional component
+//
+// A stricter alternative that doesn't allow fractional components is: ^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$
+// ^before using the stricter pattern make sure to double escape the backslashes
+@pattern("^P(?:\\d+(?:\\.\\d+)?Y)?(?:\\d+(?:\\.\\d+)?M)?(?:\\d+(?:\\.\\d+)?W)?(?:\\d+(?:\\.\\d+)?D)?(?:T(?:\\d+(?:\\.\\d+)?H)?(?:\\d+(?:\\.\\d+)?M)?(?:\\d+(?:\\.\\d+)?S)?)?$")
+@extension("x-inline", true)
+scalar ISO8601Duration extends string;
+
+/**
+ * Period duration for the recurrence
+ */
+@friendlyName("RecurringPeriodInterval")
+union RecurringPeriodInterval {
+  ISO8601Duration,
+  RecurringPeriodIntervalEnum,
+}
+
+/**
+ * The unit of time for the interval.
+ * One of: `day`, `week`, `month`, or `year`.
+ */
+@friendlyName("RecurringPeriodIntervalEnum")
+enum RecurringPeriodIntervalEnum {
+  #suppress "@openmeter/api-spec-legacy/casing" "Use existing values"
+  Day: "DAY",
+  #suppress "@openmeter/api-spec-legacy/casing" "Use existing values"
+  Week: "WEEK",
+  #suppress "@openmeter/api-spec-legacy/casing" "Use existing values"
+  Month: "MONTH",
+  #suppress "@openmeter/api-spec-legacy/casing" "Use existing values"
+  Year: "YEAR",
+}
+
+/**
+ * Recurring period with an interval and an anchor.
+ */
+#deprecated "Use RecurringPeriodV2 instead"
+@example(#{
+  interval: RecurringPeriodIntervalEnum.Day,
+  intervalISO: duration.fromISO("P1D"),
+  anchor: DateTime.fromISO("2023-01-01T01:01:01.001Z"),
+})
+@friendlyName("RecurringPeriod")
+model RecurringPeriod {
+  ...RecurringPeriodV2;
+
+  /**
+   * The unit of time for the interval in ISO8601 format.
+   */
+  @encode(DurationKnownEncoding.ISO8601)
+  intervalISO: duration;
+}
+
+/**
+ * Recurring period with an interval and an anchor.
+ */
+@friendlyName("RecurringPeriodV2")
+model RecurringPeriodV2 {
+  /**
+   * The unit of time for the interval. Heuristically maps ISO duraitons to enum values or returns the ISO duration.
+   */
+  @summary("Interval")
+  interval: RecurringPeriodInterval;
+
+  /**
+   * A date-time anchor to base the recurring period on.
+   */
+  @summary("Anchor time")
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  anchor: DateTime;
+}
+
+/**
+ * Recurring period with an interval and an anchor.
+ */
+@example(#{
+  interval: RecurringPeriodIntervalEnum.Day,
+  anchor: DateTime.fromISO("2023-01-01T01:01:01.001Z"),
+})
+@friendlyName("RecurringPeriodCreateInput")
+model RecurringPeriodCreateInput {
+  /**
+   * The unit of time for the interval.
+   */
+  @summary("Interval")
+  interval: RecurringPeriodInterval;
+
+  /**
+   * A date-time anchor to base the recurring period on.
+   */
+  @summary("Anchor time")
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  anchor?: DateTime;
+}
+
+/**
+ * A period with a start and end time.
+ */
+@friendlyName("Period")
+model Period {
+  /**
+   * Period start time.
+   */
+  @example(DateTime.fromISO("2023-01-01T01:01:01.001Z"))
+  from: DateTime;
+
+  /**
+   * Period end time.
+   */
+  @example(DateTime.fromISO("2023-02-01T01:01:01.001Z"))
+  to: DateTime;
+}
+
+/**
+ * Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
+ * Custom three-letter currency codes are also supported for convenience.
+ */
+@pattern("^[A-Z]{3}$")
+// TODO: add helpers for currency database
+@friendlyName("CurrencyCode")
+@minLength(3)
+@maxLength(3)
+@example("USD")
+scalar CurrencyCode extends string;
+
+/**
+ * [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 country code.
+ * Custom two-letter country codes are also supported for convenience.
+ */
+@pattern("^[A-Z]{2}$")
+@friendlyName("CountryCode")
+@minLength(2)
+@maxLength(2)
+@example("US")
+scalar CountryCode extends string;
+
+/**
+ * Address
+ */
+@friendlyName("Address")
+model Address {
+  /**
+   * Country code in [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 format.
+   */
+  country?: CountryCode;
+
+  /**
+   * Postal code.
+   */
+  postalCode?: string;
+
+  /**
+   * State or province.
+   */
+  state?: string;
+
+  /**
+   * City.
+   */
+  city?: string;
+
+  /**
+   * First line of the address.
+   */
+  line1?: string;
+
+  /**
+   * Second line of the address.
+   */
+  line2?: string;
+
+  /**
+   * Phone number.
+   */
+  phoneNumber?: string;
+}
+
+/**
+ * Meta object to generate create/update request from type by omitting readonly properties.
+ */
+@friendlyName("{name}Request", T)
+model Request<T, Keys extends string> {
+  ...OmitProperties<T, Keys>;
+}
+
+/**
+ * Set of key-value pairs managed by the system. Cannot be modified by user.
+ */
+@example(#{ externalId: "019142cc-a016-796a-8113-1a942fecd26d" })
+@friendlyName("Annotations")
+model Annotations {
+  ...Record<unknown>;
+}
+
+/**
+ * Numeric represents an arbitrary precision number.
+ */
+@pattern("^\\-?[0-9]+(\\.[0-9]+)?$")
+@friendlyName("Numeric")
+scalar Numeric extends string;
+alias Money = Numeric;
+
+/**
+ * Numeric representation of a percentage
+ *
+ * 50% is represented as 50
+ */
+@example(50)
+@friendlyName("Percentage")
+@extension("x-go-type", "models.Percentage")
+@extension("x-go-package", "github.com/openmeterio/openmeter/pkg/models")
+scalar Percentage extends float64;
+
+/**
+ * Unit describes how the quantity of the product should be interpreted.
+ */
+@friendlyName("Unit")
+scalar Unit extends string;
+
+/**
+ * TaxIdentificationCode is a normalized tax code shown on the original identity document.
+ */
+@minLength(1)
+@maxLength(32)
+@friendlyName("BillingTaxIdentificationCode")
+scalar TaxIdentificationCode extends string;

api/spec/packages/legacy/tspconfig.client.yaml

@@ -0,0 +1,21 @@
+emit:
+  - '@typespec/http-client-python'
+parameters:
+  base-dir:
+    default: '{cwd}'
+  client-dir:
+    default: '{cwd}/../../../client'
+output-dir: '{base-dir}'
+options:
+  '@typespec/http-client-python':
+    emitter-output-dir: '{client-dir}/python'
+    package-name: openmeter
+    generation-subdir: _generated
+    namespace: openmeter
+    package-version: '0.0.0'
+    generate-packaging-files: false
+    license:
+      name: Apache 2.0
+linter:
+  extends:
+    - '@openmeter/api-spec-legacy/all'

api/spec/packages/legacy/tspconfig.yaml

@@ -0,0 +1,14 @@
+emit:
+  - '@typespec/openapi3'
+parameters:
+  base-dir:
+    default: '{cwd}'
+  client-dir:
+    default: '{cwd}/../client'
+output-dir: '{base-dir}'
+options:
+  '@typespec/openapi3':
+    emitter-output-dir: '{output-dir}/output'
+linter:
+  extends:
+    - '@openmeter/api-spec-legacy/all'

api/spec/packages/typespec-go/.gitignore

@@ -0,0 +1,2 @@
+dist/
+tsconfig.tsbuildinfo

api/spec/packages/typespec-go/README.md

@@ -0,0 +1,76 @@
+# @openmeter/typespec-go
+
+A TypeSpec **emitter** that generates the OpenMeter **Go** SDK from the AIP
+TypeSpec specs, mirroring [`@openmeter/typespec-typescript`](../typespec-typescript)
+but targeting Go.
+
+## Output
+
+The emitter writes to `api/v3/client` at the **repo root** (not a sibling of
+this package): a single flat `package openmeter` that is its own nested Go
+module, `github.com/openmeterio/openmeter/api/v3/client`. The output directory
+is set in [`packages/aip/tspconfig.yaml`](../aip/tspconfig.yaml) via
+`emitter-output-dir: '{output-dir}/../../../v3/client'`.
+
+The generated files are fully regenerable — **never hand-edit them**. Change
+the emitter (for spec-derived files) or `src/runtime-templates.ts` (for the
+static runtime files), then regenerate. The output cleaner wipes previously
+generated files before emission but preserves `*_test.go` and `testdata/`:
+hand-written wire tests live in `api/v3/client` and survive regeneration.
+
+## How it works
+
+`src/emitter.tsx` discovers and groups HTTP operations, validates codec/name
+exhaustiveness, computes payload-context reachability (read vs input model
+projections), and renders models, services, the root client, and the package
+`README.md` from one operation IR — so documented call paths and routes always
+match the emitted SDK. Unions retain their raw JSON for forward-compatible
+round-tripping. The wire format is snake_case and the Go surface is PascalCase
+fields with `json:"snake_case"` tags, so — unlike the TS emitter — there is
+**no casing translation layer**. See [PLAN.md](./PLAN.md) for the design
+history and the full architecture.
+
+## Options
+
+Declared in `src/lib.ts`, configured in `packages/aip/tspconfig.yaml`:
+
+| Option                | Required | Purpose                                                                                |
+| --------------------- | -------- | -------------------------------------------------------------------------------------- |
+| `module-path`         | yes      | Go module path of the generated SDK (`github.com/openmeterio/openmeter/api/v3/client`) |
+| `package-name`        | yes      | Go package name (`openmeter`)                                                          |
+| `sdk-version`         | no       | Fallback version used when Go build info is unavailable; defaults to `0.0.0-dev`       |
+| `include-services`    | no       | Service namespaces to emit (`['OpenMeter']`); all services when omitted                |
+| `strip-name-prefixes` | no       | PascalCase type-name prefixes stripped when unambiguous                                |
+| `include-resources`   | no       | Operation groups to emit; every discovered group when omitted                          |
+| `readme-note`         | no       | Markdown callout inserted after the generated README intro                             |
+| `go-version`          | no       | Stamped into the go.mod `go` directive; defaults to `1.23`, the generated code's floor |
+
+## Commands
+
+| Task                | Command                                                                                                  |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| Build the emitter   | `pnpm build` (`alloy build`)                                                                             |
+| Watch               | `pnpm watch`                                                                                             |
+| Typecheck           | `pnpm typecheck`                                                                                         |
+| Emitter tests       | `pnpm test` (vitest over `test/`)                                                                        |
+| Emitter checks      | `pnpm check` (typecheck + tests)                                                                         |
+| Regenerate the SDK  | `pnpm --filter @openmeter/api-spec-aip run generate` (or `make gen-api`, repo root)                      |
+| Generated SDK check | `make test-go-sdk` (repo root), or in `api/v3/client`: `go build ./... && go vet ./... && go test ./...` |
+
+## Wiring
+
+Registered in [`packages/aip/tspconfig.yaml`](../aip/tspconfig.yaml) under
+`emit:` and declared as a `workspace:*` devDependency of
+`@openmeter/api-spec-aip` so `tsp` resolves it. One `pnpm generate` produces
+the OpenAPI document and every SDK.
+
+## Releases
+
+Releases are `api/v3/client/vX.Y.Z` git tags, gated by
+`.github/workflows/release-go-sdk.yaml`. `Version` resolves at runtime via
+`debug.ReadBuildInfo()` to the module version consumers pulled in through their
+own `go.mod`, so no stamping commit is needed before tagging: push the paired
+root and nested-module tags and the gate runs `make test-go-sdk` against them.
+`sdk-version` in `packages/aip/tspconfig.yaml` only sets the fallback baked
+into `option.go` for builds without resolvable module build info (the module
+itself, replace directives, vendored trees).

api/spec/packages/typespec-go/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@openmeter/typespec-go",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "alloy build",
+    "watch": "alloy build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm run build && vitest --run",
+    "check": "pnpm run typecheck && pnpm run test"
+  },
+  "dependencies": {
+    "@alloy-js/core": "0.23.1",
+    "@alloy-js/go": "0.3.0",
+    "@typespec/compiler": "1.11.0",
+    "@typespec/emitter-framework": "0.17.0",
+    "@typespec/http": "1.11.0",
+    "@typespec/openapi": "1.11.0"
+  },
+  "devDependencies": {
+    "@alloy-js/cli": "0.23.0",
+    "@types/node": "25.9.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
+  }
+}

api/spec/packages/typespec-go/src/components/GoClient.tsx

@@ -0,0 +1,145 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import type { Refkey } from '@alloy-js/core'
+import { strings, url } from '../stdlib.js'
+
+export interface GoClientResource {
+  name: string
+  root: string
+  nestPath: string[]
+  serviceRefkey: Refkey
+}
+
+export interface GoClientProps {
+  clientRefkey: Refkey
+  resources: GoClientResource[]
+}
+
+export function GoClient({ clientRefkey, resources }: GoClientProps) {
+  const roots = resources.filter((resource) => resource.nestPath.length === 0)
+  const wiring = [...resources]
+    .sort((left, right) => left.nestPath.length - right.nestPath.length)
+    .map((resource) => {
+      const target = ['c', resource.root, ...resource.nestPath].join('.')
+      return `${target} = &${resource.name}Service{client: c}`
+    })
+    .join('\n')
+
+  const receiver = () => (
+    <go.FunctionReceiver
+      name="c"
+      type={
+        <go.Pointer>
+          <go.Reference refkey={clientRefkey} />
+        </go.Pointer>
+      }
+    />
+  )
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      <go.StructTypeDeclaration name="Client" refkey={clientRefkey}>
+        <ay.List hardline>
+          <go.StructMember
+            name="baseURL"
+            type={<go.Pointer>{url.URL}</go.Pointer>}
+          />
+          <go.StructMember
+            name="httpClient"
+            type={<go.Pointer>{go.std.net.http.Client}</go.Pointer>}
+          />
+          <go.StructMember name="token" type="string" />
+          <go.StructMember name="userAgent" type="string" />
+          <ay.List hardline>
+            {roots.map((resource) => (
+              <go.StructMember
+                name={resource.root}
+                type={
+                  <go.Pointer>
+                    <go.Reference refkey={resource.serviceRefkey} />
+                  </go.Pointer>
+                }
+              />
+            ))}
+          </ay.List>
+        </ay.List>
+      </go.StructTypeDeclaration>
+      <go.FunctionDeclaration
+        name="New"
+        parameters={[
+          { name: 'baseURL', type: 'string' },
+          { name: 'opts', type: 'Option', variadic: true },
+        ]}
+        returns={['*Client', 'error']}
+      >
+        {ay.code`
+          if baseURL == "" {
+            return nil, ${go.std.fmt.Errorf}("openmeter: baseURL is required")
+          }
+
+          u, err := ${url.Parse}(baseURL)
+          if err != nil {
+            return nil, ${go.std.fmt.Errorf}("openmeter: invalid baseURL %q: %w", baseURL, err)
+          }
+
+          if u.Scheme == "" || u.Host == "" {
+            return nil, ${go.std.fmt.Errorf}("openmeter: baseURL %q must be absolute (scheme and host)", baseURL)
+          }
+
+          c := &Client{
+            baseURL: u,
+            userAgent: defaultUserAgent,
+          }
+
+          for _, opt := range opts {
+            opt(c)
+          }
+
+          if c.httpClient == nil {
+            c.httpClient = defaultHTTPClient()
+          }
+
+          ${wiring}
+
+          return c, nil
+        `}
+      </go.FunctionDeclaration>
+      <ay.List joiner={'\n'}>
+        {`// resolve joins the client base URL with an API path, preserving any base path
+// prefix and base query present on the base URL. apiPath is parsed so percent
+// escapes already present in a segment, such as an ID escaped by
+// replacePathParam, are carried through on RawPath instead of being
+// re-escaped.`}
+        <go.FunctionDeclaration
+          name="resolve"
+          receiver={receiver()}
+          parameters={[{ name: 'apiPath', type: 'string' }]}
+          returns={<go.Pointer>{url.URL}</go.Pointer>}
+        >
+          {ay.code`
+          base := *c.baseURL
+
+          if !${strings.HasSuffix}(base.Path, "/") {
+            base.Path += "/"
+          }
+
+          trimmed := ${strings.TrimPrefix}(apiPath, "/")
+          ref, err := ${url.Parse}(trimmed)
+          if err != nil {
+            ref = &${url.URL}{Path: trimmed}
+          }
+
+          resolved := base.ResolveReference(ref)
+          resolved.RawQuery = base.RawQuery
+          return resolved
+        `}
+        </go.FunctionDeclaration>
+      </ay.List>
+      {ay.code`
+        func replacePathParam(path, name, value string) string {
+          return ${strings.ReplaceAll}(path, "{" + name + "}", ${url.PathEscape}(value))
+        }
+      `}
+    </ay.List>
+  )
+}

api/spec/packages/typespec-go/src/components/GoEnum.tsx

@@ -0,0 +1,69 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import { type Refkey } from '@alloy-js/core'
+import { type Union, type UnionVariant } from '@typespec/compiler'
+import { goExportedName } from '../go-types.js'
+
+export interface GoEnumProps {
+  union: Union
+  name: string
+  refkey: Refkey
+  doc?: string
+}
+
+export function GoEnum({ union, name, refkey, doc }: GoEnumProps) {
+  const members = [...union.variants.values()].map((variant) => ({
+    name: variantName(variant),
+    value: variantValue(variant),
+  }))
+
+  return (
+    <>
+      <go.TypeDeclaration name={name} refkey={refkey} doc={doc}>
+        string
+      </go.TypeDeclaration>
+      {'\n\n'}
+      <go.VariableDeclarationGroup const>
+        {members.map((member) => (
+          <go.VariableDeclaration
+            name={`${name}${goExportedName(member.name)}`}
+            type={refkey}
+          >
+            {JSON.stringify(member.value)}
+          </go.VariableDeclaration>
+        ))}
+      </go.VariableDeclarationGroup>
+      {'\n\n'}
+      <go.FunctionDeclaration
+        name="Valid"
+        receiver={<go.FunctionReceiver name="value" type={name} />}
+        returns="bool"
+      >
+        {ay.code`
+          switch value {
+          case ${members
+            .map((member) => `${name}${goExportedName(member.name)}`)
+            .join(', ')}:
+            return true
+          default:
+            return false
+          }
+        `}
+      </go.FunctionDeclaration>
+    </>
+  )
+}
+
+function variantName(variant: UnionVariant): string {
+  return typeof variant.name === 'symbol' ? variantValue(variant) : variant.name
+}
+
+function variantValue(variant: UnionVariant): string {
+  if (variant.type.kind !== 'String') {
+    throw new Error(
+      `Go string enum variant ${String(variant.name)} is not a string literal`,
+    )
+  }
+
+  return variant.type.value
+}

api/spec/packages/typespec-go/src/components/GoModels.tsx

@@ -0,0 +1,206 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import { type Program, type Type, type Union } from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import {
+  goFields,
+  goProjectionsOf,
+  goType,
+  nullableUnionElement,
+  optionalTypeName,
+  typeName,
+  type GoDeclarationPlan,
+} from '../go-types.js'
+import { GoEnum } from './GoEnum.js'
+import { GoStruct } from './GoStruct.js'
+import { GoTypeSpecEnum } from './GoTypeSpecEnum.js'
+import { GoUnion } from './GoUnion.js'
+import { isRuntimeBackedTypeName } from '../runtime-symbols.js'
+
+export interface GoModelsProps {
+  program: Program
+  types: Set<Type>
+}
+
+export function GoModels({ program, types }: GoModelsProps) {
+  const typekit = $(program)
+  const projections = goProjectionsOf(program)
+  const emittedNames = new Map<string, Type>()
+  const declarations = [...types]
+    .filter(
+      (type) =>
+        type.kind !== 'Model' ||
+        (!typekit.array.is(type) && !typekit.record.is(type)),
+    )
+    .flatMap((type) => {
+      const name = optionalTypeName(program, type)
+      return name ? [{ name, type }] : []
+    })
+    .filter(({ name, type }) => !isRuntimeBackedTypeName(name, type.kind))
+    .filter(({ name, type }) => {
+      const existing = emittedNames.get(name)
+      if (!existing) {
+        emittedNames.set(name, type)
+      }
+      return !existing
+    })
+    // Code-point comparison, not localeCompare: the output is a committed
+    // artifact, and locale-dependent ordering would produce spurious diffs
+    // across machines.
+    .sort((left, right) =>
+      left.name < right.name ? -1 : left.name > right.name ? 1 : 0,
+    )
+
+  // Without a configured projection registry (unit tests), every model emits
+  // its read projection under the natural name.
+  const plannedDeclarations = (
+    type: Type,
+    name: string,
+  ): GoDeclarationPlan[] =>
+    projections
+      ? (projections.declarations.get(type) ?? [])
+      : [{ name, mode: 'read' }]
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      {declarations.map(({ name, type }) => {
+        switch (type.kind) {
+          case 'Model': {
+            const doc = typekit.type.getDoc(type)
+            return (
+              <ay.List joiner={'\n\n'}>
+                {plannedDeclarations(type, name).map((declaration) => (
+                  <GoStruct
+                    name={declaration.name}
+                    fields={goFields(program, type, {
+                      mode: declaration.mode === 'input' ? 'input' : undefined,
+                    })}
+                    doc={doc}
+                  />
+                ))}
+              </ay.List>
+            )
+          }
+          case 'Union':
+            return (
+              <ay.List joiner={'\n\n'}>
+                {plannedDeclarations(type, name).map((declaration) =>
+                  renderUnion(program, type, declaration),
+                )}
+              </ay.List>
+            )
+          case 'Enum':
+            return (
+              <GoTypeSpecEnum
+                enumType={type}
+                name={name}
+                doc={typekit.type.getDoc(type)}
+              />
+            )
+          // Scalars never carry generated behavior and no emitted field
+          // references a scalar alias (fields use the underlying Go type),
+          // so declaring them would only add dead exported names.
+          case 'Scalar':
+          default:
+            return undefined
+        }
+      })}
+    </ay.List>
+  )
+}
+
+export function renderUnion(
+  program: Program,
+  union: Union,
+  declaration: GoDeclarationPlan,
+) {
+  const name = declaration.name
+  const mode = declaration.mode === 'input' ? ('input' as const) : undefined
+  const doc = $(program).type.getDoc(union)
+
+  if (nullableUnionElement(union)) {
+    return (
+      <go.TypeDeclaration name={name} alias doc={doc}>
+        {goType(program, union, { mode }).type}
+      </go.TypeDeclaration>
+    )
+  }
+
+  const variants = [...union.variants.values()]
+  if (
+    variants.length > 0 &&
+    variants.every((variant) => variant.type.kind === 'String')
+  ) {
+    return <GoEnum union={union} name={name} refkey={ay.refkey()} doc={doc} />
+  }
+
+  if (
+    variants.length > 0 &&
+    variants.every((variant) => isStringLike(program, variant.type))
+  ) {
+    return (
+      <go.TypeDeclaration name={name} doc={doc}>
+        string
+      </go.TypeDeclaration>
+    )
+  }
+
+  if (
+    variants.length > 0 &&
+    variants.every((variant) => variant.type.kind === 'Model')
+  ) {
+    return (
+      <GoUnion
+        program={program}
+        union={union}
+        name={name}
+        mode={mode}
+        doc={doc}
+      />
+    )
+  }
+
+  const concrete = variants.filter(
+    (variant) => variant.type.kind !== 'Intrinsic',
+  )
+  if (concrete.length === 1) {
+    return (
+      <go.TypeDeclaration name={name} alias doc={doc}>
+        {goType(program, concrete[0]!.type, { mode }).type}
+      </go.TypeDeclaration>
+    )
+  }
+
+  if (concrete.length > 1) {
+    return (
+      <GoUnion
+        program={program}
+        union={union}
+        name={name}
+        mode={mode}
+        doc={doc}
+      />
+    )
+  }
+
+  throw new Error(
+    `typespec-go: union ${typeName(program, union)} has no concrete variants representable in Go; give it at least one non-intrinsic variant or replace the union with the intended model before emitting it`,
+  )
+}
+
+export function isStringLike(program: Program, type: Type): boolean {
+  switch (type.kind) {
+    case 'String':
+      return true
+    case 'Scalar':
+      return goType(program, type).type === 'string'
+    case 'Enum':
+      return [...type.members.values()].every(
+        (member) => typeof (member.value ?? member.name) === 'string',
+      )
+    case 'EnumMember':
+      return typeof (type.value ?? type.name) === 'string'
+    default:
+      return false
+  }
+}

api/spec/packages/typespec-go/src/components/GoResource.tsx

@@ -0,0 +1,1000 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import type { Refkey } from '@alloy-js/core'
+import {
+  resolveEncodedName,
+  walkPropertiesInherited,
+  type ModelProperty,
+  type Operation,
+  type Program,
+  type Type,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { isHeader, isStatusCode } from '@typespec/http'
+import {
+  goExportedName,
+  goType,
+  queryFilterKind,
+  queryScalarKind,
+  typeName,
+} from '../go-types.js'
+import {
+  describeOperations,
+  operationBaseName,
+  type GoOperation,
+  type GoParameter,
+} from '../operations.js'
+import { context, iter, strconv, strings, url } from '../stdlib.js'
+import { GoStruct } from './GoStruct.js'
+
+export interface GoResourceProps {
+  program: Program
+  resource: string
+  serviceName: string
+  nestPath: string[]
+  operations: Operation[]
+  bodyOverrides: Map<string, Type>
+  serviceRefkey: Refkey
+  children: Array<{ name: string; serviceRefkey: Refkey }>
+}
+
+export function GoResource({
+  program,
+  resource,
+  serviceName,
+  nestPath,
+  operations,
+  bodyOverrides,
+  serviceRefkey,
+  children,
+}: GoResourceProps) {
+  const described = describeOperations(
+    program,
+    resource,
+    operations,
+    bodyOverrides,
+    nestPath,
+  )
+  const paramsNames = resolveListParamsNames(program, described)
+  const params = listParameterDeclarations(program, described, paramsNames)
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      <go.StructTypeDeclaration
+        name={`${goExportedName(serviceName)}Service`}
+        refkey={serviceRefkey}
+      >
+        <ay.List hardline>
+          <go.StructMember name="client" type="*Client" />
+          <ay.List hardline>
+            {children.map((child) => (
+              <go.StructMember
+                name={goExportedName(child.name)}
+                type={
+                  <go.Pointer>
+                    <go.Reference refkey={child.serviceRefkey} />
+                  </go.Pointer>
+                }
+              />
+            ))}
+          </ay.List>
+        </ay.List>
+      </go.StructTypeDeclaration>
+      {params}
+      <ay.List>
+        {described.flatMap((operation) => [
+          <OperationMethod
+            program={program}
+            operation={operation}
+            serviceRefkey={serviceRefkey}
+            paramsNames={paramsNames}
+          />,
+          '\n\n',
+          operation.pagination &&
+          isPlainPageEnvelope(program, operation.response) ? (
+            <>
+              <ListAllMethod
+                program={program}
+                operation={operation}
+                serviceRefkey={serviceRefkey}
+                paramsNames={paramsNames}
+              />
+              {'\n\n'}
+            </>
+          ) : undefined,
+          isTextResponse(operation) ? (
+            <>
+              <StreamMethod
+                program={program}
+                operation={operation}
+                serviceRefkey={serviceRefkey}
+                paramsNames={paramsNames}
+              />
+              {'\n\n'}
+            </>
+          ) : undefined,
+        ])}
+      </ay.List>
+    </ay.List>
+  )
+}
+
+function OperationMethod({
+  program,
+  operation,
+  serviceRefkey,
+  paramsNames,
+}: {
+  program: Program
+  operation: GoOperation
+  serviceRefkey: Refkey
+  paramsNames: Map<GoOperation, string>
+}) {
+  // goType resolves the read-side reference name, honoring structural-dedupe
+  // aliases; typeName alone would reference a collapsed declaration.
+  const responseName = operation.response
+    ? readReferenceName(program, operation.response)
+    : undefined
+  const textResponse = isTextResponse(operation)
+  const parameters = methodParameters(program, operation, paramsNames)
+  const path = pathCode(operation)
+  const requestBody = operation.body
+    ? operation.bodyOptional
+      ? 'optionalBody(request)'
+      : 'request'
+    : 'nil'
+  const query = operation.queryParams.length > 0 ? 'params.values()' : 'nil'
+  const requestContentType = operation.body
+    ? JSON.stringify(operation.requestContentType ?? 'application/json')
+    : '""'
+  const accept = JSON.stringify(
+    operation.responseContentType ??
+      (operation.response ? 'application/json' : ''),
+  )
+  const returns = textResponse
+    ? ['[]byte', 'error']
+    : responseName
+      ? [`*${responseName}`, 'error']
+      : 'error'
+
+  return (
+    <go.FunctionDeclaration
+      name={goExportedName(operation.methodName)}
+      receiver={serviceReceiver(serviceRefkey)}
+      parameters={parameters}
+      returns={returns}
+      doc={$(program).type.getDoc(operation.operation)}
+    >
+      {textResponse
+        ? ay.code`
+            ${path}
+
+            req, err := s.client.newRequestWithContentType(ctx, ${httpMethod(operation.verb)}, path, ${query}, ${requestBody}, ${requestContentType}, ${accept})
+            if err != nil {
+              return nil, err
+            }
+
+            return s.client.doRaw(req)
+          `
+        : responseName
+          ? ay.code`
+            ${path}
+
+            req, err := s.client.newRequestWithContentType(ctx, ${httpMethod(operation.verb)}, path, ${query}, ${requestBody}, ${requestContentType}, ${accept})
+            if err != nil {
+              return nil, err
+            }
+
+            var out ${responseName}
+            if err := s.client.doJSON(req, &out); err != nil {
+              return nil, err
+            }
+
+            return &out, nil
+          `
+          : ay.code`
+              ${path}
+
+              req, err := s.client.newRequestWithContentType(ctx, ${httpMethod(operation.verb)}, path, ${query}, ${requestBody}, ${requestContentType}, ${accept})
+              if err != nil {
+                return err
+              }
+
+              _, err = s.client.doRaw(req)
+              return err
+            `}
+    </go.FunctionDeclaration>
+  )
+}
+
+function ListAllMethod({
+  program,
+  operation,
+  serviceRefkey,
+  paramsNames,
+}: {
+  program: Program
+  operation: GoOperation
+  serviceRefkey: Refkey
+  paramsNames: Map<GoOperation, string>
+}) {
+  if (operation.pagination === 'cursor') {
+    return (
+      <CursorListAllMethod
+        program={program}
+        operation={operation}
+        serviceRefkey={serviceRefkey}
+        paramsNames={paramsNames}
+      />
+    )
+  }
+
+  const element = pageElement(program, operation.response!)
+  const listArguments = [
+    ...operation.pathParams.map((parameter) => localName(parameter.name)),
+    ...(operation.body ? ['request'] : []),
+    'pageParams',
+  ].join(', ')
+
+  return (
+    <go.FunctionDeclaration
+      name={`${goExportedName(operation.methodName)}All`}
+      receiver={serviceReceiver(serviceRefkey)}
+      parameters={methodParameters(program, operation, paramsNames)}
+      returns={<Seq2Type element={element} />}
+      doc={allIteratorDoc(operation, element)}
+    >
+      {ay.code`
+        return paginate(params.Page, func(page, size int) ([]${element}, int, error) {
+          pageParams := params
+          pageParams.Page = &PageParams{Size: Int(size), Number: Int(page)}
+
+          resp, err := s.${goExportedName(operation.methodName)}(ctx, ${listArguments})
+          if err != nil {
+            return nil, 0, err
+          }
+
+          return resp.Data, resp.Meta.Page.Total, nil
+        })
+      `}
+    </go.FunctionDeclaration>
+  )
+}
+
+function CursorListAllMethod({
+  program,
+  operation,
+  serviceRefkey,
+  paramsNames,
+}: {
+  program: Program
+  operation: GoOperation
+  serviceRefkey: Refkey
+  paramsNames: Map<GoOperation, string>
+}) {
+  const element = pageElement(program, operation.response!)
+  const listArguments = [
+    ...operation.pathParams.map((parameter) => localName(parameter.name)),
+    ...(operation.body ? ['request'] : []),
+    'pageParams',
+  ].join(', ')
+
+  return (
+    <go.FunctionDeclaration
+      name={`${goExportedName(operation.methodName)}All`}
+      receiver={serviceReceiver(serviceRefkey)}
+      parameters={methodParameters(program, operation, paramsNames)}
+      returns={<Seq2Type element={element} />}
+      doc={allIteratorDoc(operation, element)}
+    >
+      {ay.code`
+        return paginateCursor(params.Page, func(after, before *string, size int) ([]${element}, *string, *string, error) {
+          pageParams := params
+          pageParams.Page = &CursorPageParams{Size: Int(size), After: after, Before: before}
+
+          resp, err := s.${goExportedName(operation.methodName)}(ctx, ${listArguments})
+          if err != nil {
+            return nil, nil, nil, err
+          }
+
+          return resp.Data, String(resp.Meta.Page.Next.GetOrEmpty()), String(resp.Meta.Page.Previous.GetOrEmpty()), nil
+        })
+      `}
+    </go.FunctionDeclaration>
+  )
+}
+
+function StreamMethod({
+  program,
+  operation,
+  serviceRefkey,
+  paramsNames,
+}: {
+  program: Program
+  operation: GoOperation
+  serviceRefkey: Refkey
+  paramsNames: Map<GoOperation, string>
+}) {
+  const requestBody = operation.body
+    ? operation.bodyOptional
+      ? 'optionalBody(request)'
+      : 'request'
+    : 'nil'
+
+  return (
+    <go.FunctionDeclaration
+      name={`${goExportedName(operation.methodName)}Stream`}
+      receiver={serviceReceiver(serviceRefkey)}
+      parameters={methodParameters(program, operation, paramsNames)}
+      returns={[go.std.io.ReadCloser, 'error']}
+    >
+      {ay.code`
+        ${pathCode(operation)}
+
+        req, err := s.client.newRequestWithContentType(ctx, ${httpMethod(operation.verb)}, path, ${operation.queryParams.length > 0 ? 'params.values()' : 'nil'}, ${requestBody}, ${JSON.stringify(operation.requestContentType ?? 'application/json')}, ${JSON.stringify(operation.responseContentType ?? 'text/csv')})
+        if err != nil {
+          return nil, err
+        }
+
+        resp, err := s.client.doStream(req)
+        if err != nil {
+          return nil, err
+        }
+
+        return resp.Body, nil
+      `}
+    </go.FunctionDeclaration>
+  )
+}
+
+function listParameterDeclarations(
+  program: Program,
+  operations: GoOperation[],
+  paramsNames: Map<GoOperation, string>,
+) {
+  const emitted = new Set<string>()
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      {operations.flatMap((operation) => {
+        if (operation.queryParams.length === 0) {
+          return []
+        }
+
+        // resolveListParamsNames guarantees operations sharing a params name
+        // also share a query shape, so deduping by name emits one identical
+        // struct for all of them.
+        const paramsName = paramsNames.get(operation)!
+        if (emitted.has(paramsName)) {
+          return []
+        }
+        emitted.add(paramsName)
+
+        const deepObjects = operation.queryParams.filter(
+          (parameter) => parameter.queryCodec?.kind === 'deepObject',
+        )
+        const deepObjectNames = new Map(
+          deepObjects.map((parameter) => [
+            parameter.name,
+            deepObjectName(paramsName, parameter),
+          ]),
+        )
+        const paramsRefkey = ay.refkey()
+
+        return [
+          <ay.List joiner={'\n\n'}>
+            {deepObjects.map((parameter) => {
+              const codec = parameter.queryCodec!
+              if (codec.kind !== 'deepObject') {
+                return undefined
+              }
+              return (
+                <GoStruct
+                  name={deepObjectNames.get(parameter.name)!}
+                  fields={[...codec.model.properties.values()].map((property) =>
+                    queryFilterField(program, property),
+                  )}
+                  tags={false}
+                />
+              )
+            })}
+            <go.StructTypeDeclaration name={paramsName} refkey={paramsRefkey}>
+              <ay.List hardline>
+                {operation.queryParams.map((parameter) =>
+                  queryParamField(program, parameter, deepObjectNames),
+                )}
+              </ay.List>
+            </go.StructTypeDeclaration>
+            <go.FunctionDeclaration
+              name="values"
+              receiver={<go.FunctionReceiver name="p" type={paramsRefkey} />}
+              returns={url.Values}
+            >
+              {queryValuesBody(program, operation.queryParams)}
+            </go.FunctionDeclaration>
+          </ay.List>,
+        ]
+      })}
+    </ay.List>
+  )
+}
+
+function queryParamField(
+  program: Program,
+  parameter: GoParameter,
+  deepObjectNames: Map<string, string>,
+) {
+  switch (parameter.queryCodec?.kind) {
+    case 'page':
+      return <go.StructMember name="Page" type="*PageParams" />
+    case 'cursorPage':
+      return <go.StructMember name="Page" type="*CursorPageParams" />
+    case 'sort':
+      return (
+        <go.StructMember name={goExportedName(parameter.name)} type="*Sort" />
+      )
+    case 'deepObject':
+      return (
+        <go.StructMember
+          name={goExportedName(parameter.name)}
+          type={`*${deepObjectNames.get(parameter.name)!}`}
+        />
+      )
+    default:
+      const mapped = goType(program, parameter.type)
+      return (
+        <go.StructMember
+          name={goExportedName(parameter.name)}
+          type={
+            parameter.property.optional && !mapped.nilable ? (
+              <go.Pointer>{mapped.type}</go.Pointer>
+            ) : (
+              mapped.type
+            )
+          }
+        />
+      )
+  }
+}
+
+function queryValuesBody(program: Program, parameters: GoParameter[]) {
+  const statements: ay.Children[] = [ay.code`q := ${url.Values}{}`]
+
+  for (const parameter of parameters) {
+    switch (parameter.queryCodec?.kind) {
+      case 'page':
+        statements.push(ay.code`addPageParams(q, p.Page)`)
+        break
+      case 'cursorPage':
+        statements.push(ay.code`addCursorPageParams(q, p.Page)`)
+        break
+      case 'sort':
+        statements.push(
+          ay.code`addSort(q, ${JSON.stringify(parameter.name)}, p.${goExportedName(parameter.name)})`,
+        )
+        break
+      case 'deepObject':
+        statements.push(deepObjectValues(program, parameter))
+        break
+      case 'array': {
+        const field = `p.${goExportedName(parameter.name)}`
+        const wireName = JSON.stringify(parameter.name)
+        if (parameter.type.kind !== 'Model') {
+          throw new Error(
+            `array query parameter ${parameter.name} is not a model`,
+          )
+        }
+        const element = parameter.type.indexer?.value
+        if (!element) {
+          throw new Error(
+            `array query parameter ${parameter.name} has no element type`,
+          )
+        }
+        const value = queryScalarValue(program, element, 'value')
+        if (parameter.queryCodec.explode) {
+          statements.push(ay.code`for _, value := range ${field} {
+            q.Add(${wireName}, ${value})
+          }`)
+        } else {
+          const values = `${localName(parameter.name)}Values`
+          statements.push(ay.code`if len(${field}) > 0 {
+            ${values} := make([]string, 0, len(${field}))
+            for _, value := range ${field} {
+              ${values} = append(${values}, ${value})
+            }
+            q.Set(${wireName}, ${strings.Join}(${values}, ","))
+          }`)
+        }
+        break
+      }
+      case 'scalar':
+      default: {
+        const field = `p.${goExportedName(parameter.name)}`
+        const wireName = JSON.stringify(parameter.name)
+        if (parameter.property.optional) {
+          const value = queryScalarValue(program, parameter.type, `*${field}`)
+          statements.push(ay.code`if ${field} != nil {
+            q.Set(${wireName}, ${value})
+          }`)
+        } else {
+          const value = queryScalarValue(program, parameter.type, field)
+          statements.push(ay.code`q.Set(${wireName}, ${value})`)
+        }
+        break
+      }
+    }
+  }
+
+  statements.push(ay.code`return q`)
+  return <ay.List joiner={'\n\n'}>{statements}</ay.List>
+}
+
+export function deepObjectName(
+  paramsName: string,
+  parameter: GoParameter,
+): string {
+  if (parameter.name === 'filter') {
+    return `${paramsName.replace(/ListParams$/, '').replace(/Params$/, '')}Filter`
+  }
+
+  return `${paramsName.replace(/Params$/, '')}${goExportedName(parameter.name)}`
+}
+
+function queryFilterField(program: Program, property: ModelProperty) {
+  const kind = queryFilterKind(program, property.type)
+  let type: ay.Children
+
+  switch (kind) {
+    case 'string':
+      type = <go.Pointer>StringFilter</go.Pointer>
+      break
+    case 'stringExact':
+      type = <go.Pointer>StringExactFilter</go.Pointer>
+      break
+    case 'dateTime':
+      type = <go.Pointer>DateTimeFilter</go.Pointer>
+      break
+    case 'numeric':
+      type = <go.Pointer>NumericFilter</go.Pointer>
+      break
+    case 'boolean':
+      type = <go.Pointer>BooleanFilter</go.Pointer>
+      break
+    case 'labels':
+      type = 'map[string]*StringFilter'
+      break
+    case 'scalar': {
+      const mapped = goType(program, property.type)
+      type = mapped.nilable ? (
+        mapped.type
+      ) : (
+        <go.Pointer>{mapped.type}</go.Pointer>
+      )
+      break
+    }
+  }
+
+  return {
+    name: goExportedName(property.name),
+    wireName: resolveEncodedName(program, property, 'application/json'),
+    type,
+    optional: false,
+    nilable: false,
+    doc: $(program).type.getDoc(property),
+  }
+}
+
+function deepObjectValues(
+  program: Program,
+  parameter: GoParameter,
+): ay.Children {
+  const codec = parameter.queryCodec
+  if (codec?.kind !== 'deepObject') {
+    throw new Error(`${parameter.name} is not a deep-object query parameter`)
+  }
+
+  const root = `p.${goExportedName(parameter.name)}`
+  const fields = [...codec.model.properties.values()].map((property) => {
+    const field = `${root}.${goExportedName(property.name)}`
+    const wireName = resolveEncodedName(program, property, 'application/json')
+    const prefix = JSON.stringify(`${parameter.name}[${wireName}]`)
+
+    switch (queryFilterKind(program, property.type)) {
+      case 'string':
+        return ay.code`addStringFilter(q, ${prefix}, ${field})`
+      case 'stringExact':
+        return ay.code`addStringExactFilter(q, ${prefix}, ${field})`
+      case 'dateTime':
+        return ay.code`addDateTimeFilter(q, ${prefix}, ${field})`
+      case 'numeric':
+        return ay.code`addNumericFilter(q, ${prefix}, ${field})`
+      case 'boolean':
+        return ay.code`addBooleanFilter(q, ${prefix}, ${field})`
+      case 'labels':
+        return ay.code`for key, filter := range ${field} {
+          addStringFilter(q, ${JSON.stringify(`${parameter.name}[${wireName}][`)}+key+"]", filter)
+        }`
+      case 'scalar': {
+        const value = queryScalarValue(program, property.type, `*${field}`)
+        return ay.code`if ${field} != nil {
+          q.Set(${prefix}, ${value})
+        }`
+      }
+    }
+  })
+
+  return ay.code`if ${root} != nil {
+    ${(<ay.List joiner={'\n'}>{fields}</ay.List>)}
+  }`
+}
+
+export function queryScalarValue(
+  program: Program,
+  type: Type,
+  expression: string,
+): ay.Children {
+  const mapped = goType(program, type).type
+  const convert = (target: string) =>
+    mapped === target ? expression : `${target}(${expression})`
+
+  switch (queryScalarKind(program, type)) {
+    case 'string':
+      return convert('string')
+    case 'boolean':
+      return ay.code`${strconv.FormatBool}(${convert('bool')})`
+    case 'integer':
+      return isUnsignedType(type)
+        ? ay.code`${strconv.FormatUint}(${convert('uint64')}, 10)`
+        : ay.code`${strconv.FormatInt}(${convert('int64')}, 10)`
+    case 'float':
+      return ay.code`${strconv.FormatFloat}(${convert('float64')}, 'g', -1, 64)`
+    case 'dateTime':
+      // A dereference like *p.From must be parenthesized before .Format so the
+      // selector does not bind tighter than the dereference.
+      return ay.code`${expression.startsWith('*') ? `(${expression})` : expression}.Format(${go.std.time.RFC3339Nano})`
+  }
+}
+
+function isUnsignedType(type: Type): boolean {
+  if (type.kind !== 'Scalar') {
+    return false
+  }
+  for (
+    let current: typeof type | undefined = type;
+    current;
+    current = current.baseScalar
+  ) {
+    if (/^uint/.test(current.name)) {
+      return true
+    }
+  }
+  return false
+}
+
+function methodParameters(
+  program: Program,
+  operation: GoOperation,
+  paramsNames: Map<GoOperation, string>,
+): { name: string; type: ay.Children }[] {
+  const parameters: { name: string; type: ay.Children }[] = [
+    { name: 'ctx', type: context.Context },
+    ...operation.pathParams.map((parameter) => ({
+      name: localName(parameter.name),
+      type: 'string',
+    })),
+  ]
+  if (operation.body) {
+    const mapped = goType(program, operation.body, { mode: 'input' })
+    parameters.push({
+      name: 'request',
+      type:
+        operation.bodyOptional && !mapped.nilable ? (
+          <go.Pointer>{mapped.type}</go.Pointer>
+        ) : (
+          mapped.type
+        ),
+    })
+  }
+  if (operation.queryParams.length > 0) {
+    const paramsName = paramsNames.get(operation)
+    if (!paramsName) {
+      throw new Error(
+        `typespec-go: no params struct name resolved for ${operation.operation.name}`,
+      )
+    }
+    parameters.push({
+      name: 'params',
+      type: paramsName,
+    })
+  }
+
+  return parameters
+}
+
+function pathCode(operation: GoOperation): ay.Children {
+  const errPrefix =
+    operation.response || isTextResponse(operation) ? 'nil, ' : ''
+  const guards: ay.Children[] = operation.pathParams.map(
+    (parameter) =>
+      ay.code`if ${localName(parameter.name)} == "" {
+          return ${errPrefix}${go.std.fmt.Errorf}("openmeter: %s must not be empty: %w", ${JSON.stringify(localName(parameter.name))}, ErrEmptyID)
+        }`,
+  )
+  const substitutions: ay.Children[] = operation.pathParams.map(
+    (parameter) =>
+      ay.code`path = replacePathParam(path, ${JSON.stringify(parameter.name)}, ${localName(parameter.name)})`,
+  )
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      {[
+        ...guards,
+        ay.code`path := ${JSON.stringify(operation.path)}`,
+        ...substitutions,
+      ]}
+    </ay.List>
+  )
+}
+
+function serviceReceiver(serviceRefkey: Refkey) {
+  return (
+    <go.FunctionReceiver
+      name="s"
+      type={
+        <go.Pointer>
+          <go.Reference refkey={serviceRefkey} />
+        </go.Pointer>
+      }
+    />
+  )
+}
+
+function Seq2Type({ element }: { element: string }) {
+  return (
+    <>
+      {iter.Seq2}[{element}, error]
+    </>
+  )
+}
+
+function httpMethod(verb: string): ay.Children {
+  switch (verb.toUpperCase()) {
+    case 'GET':
+      return go.std.net.http.MethodGet
+    case 'POST':
+      return go.std.net.http.MethodPost
+    case 'PUT':
+      return go.std.net.http.MethodPut
+    case 'PATCH':
+      return go.std.net.http.MethodPatch
+    case 'DELETE':
+      return go.std.net.http.MethodDelete
+    default:
+      return JSON.stringify(verb.toUpperCase())
+  }
+}
+
+function isTextResponse(operation: GoOperation): boolean {
+  return operation.responseContentType?.startsWith('text/') ?? false
+}
+
+/**
+ * Resolves the params struct name for every operation that has query
+ * parameters.
+ *
+ * Params structs are preferably named after the page element
+ * (CustomerListParams). Distinct operations can legitimately page over the
+ * same element with different query shapes (list_prices supports sort,
+ * list_overrides does not); naming both after the element would merge two
+ * different shapes into whichever struct happens to be discovered first.
+ * Every operation in such a conflicted group therefore gets its
+ * operation-derived name instead, keeping the outcome independent of
+ * operation iteration order.
+ */
+export function resolveListParamsNames(
+  program: Program,
+  operations: GoOperation[],
+): Map<GoOperation, string> {
+  const groups = new Map<string, GoOperation[]>()
+  for (const operation of operations) {
+    if (operation.queryParams.length === 0) {
+      continue
+    }
+    const name = listParamsName(program, operation)
+    const group = groups.get(name)
+    if (group) {
+      group.push(operation)
+    } else {
+      groups.set(name, [operation])
+    }
+  }
+
+  const resolved = new Map<GoOperation, string>()
+  const shapes = new Map<string, string>()
+  for (const [name, group] of groups) {
+    const signatures = new Set(
+      group.map((operation) => querySignature(program, operation.queryParams)),
+    )
+    for (const operation of group) {
+      const finalName =
+        signatures.size > 1 ? operationParamsName(program, operation) : name
+      const signature = querySignature(program, operation.queryParams)
+      const existing = shapes.get(finalName)
+      if (existing !== undefined && existing !== signature) {
+        throw new Error(
+          `typespec-go: params struct ${finalName} would be emitted with two different query shapes; add a distinct @friendlyName or @operationId to one of the operations`,
+        )
+      }
+      shapes.set(finalName, signature)
+      resolved.set(operation, finalName)
+    }
+  }
+
+  return resolved
+}
+
+/**
+ * Canonical signature of an operation's query parameter list mirroring
+ * exactly what the generated params struct and its values() body depend on:
+ * parameter order, wire names, codec kinds, optionality, and rendered Go
+ * field types. Two operations may share a params struct only when their
+ * signatures are equal.
+ */
+function querySignature(program: Program, parameters: GoParameter[]): string {
+  return parameters
+    .map((parameter) => {
+      const codec = parameter.queryCodec
+      switch (codec?.kind) {
+        case 'page':
+          return 'page'
+        case 'cursorPage':
+          return 'cursorPage'
+        case 'sort':
+          return `sort:${parameter.name}`
+        case 'deepObject':
+          return `deepObject:${parameter.name}:{${[
+            ...codec.model.properties.values(),
+          ]
+            .map(
+              (property) =>
+                `${property.name}:${resolveEncodedName(program, property, 'application/json')}:${filterFieldSignature(program, property.type)}`,
+            )
+            .join(',')}}`
+        case 'array': {
+          if (
+            parameter.type.kind !== 'Model' ||
+            !parameter.type.indexer?.value
+          ) {
+            throw new Error(
+              `array query parameter ${parameter.name} has no element type`,
+            )
+          }
+          return `array:${parameter.name}:${codec.explode}:${scalarSignature(program, parameter.type.indexer.value)}`
+        }
+        default:
+          return `scalar:${parameter.name}:${parameter.property.optional}:${scalarSignature(program, parameter.type)}`
+      }
+    })
+    .join(';')
+}
+
+function filterFieldSignature(program: Program, type: Type): string {
+  const kind = queryFilterKind(program, type)
+  return kind === 'scalar' ? `scalar:${scalarSignature(program, type)}` : kind
+}
+
+function scalarSignature(program: Program, type: Type): string {
+  const mapped = goType(program, type).type
+  return typeof mapped === 'string' ? mapped : queryScalarKind(program, type)
+}
+
+function operationParamsName(program: Program, operation: GoOperation): string {
+  return `${goExportedName(operationBaseName(program, operation.operation))}Params`
+}
+
+function listParamsName(program: Program, operation: GoOperation): string {
+  if (operation.pagination && operation.response) {
+    try {
+      return `${pageElement(program, operation.response)}ListParams`
+    } catch {
+      // A cursor-bearing operation can return a non-standard envelope. Keep a
+      // collision-free operation name rather than guessing an element type.
+    }
+  }
+
+  return operationParamsName(program, operation)
+}
+
+/**
+ * All-iterators surface only the page elements, so they are emitted only for
+ * the canonical {data, meta} page envelope. Any extra response field (for
+ * example GovernanceQueryResponse.errors, which reports partial failures)
+ * would be silently dropped from the iteration; such operations only get the
+ * plain method that returns the full envelope.
+ */
+export function isPlainPageEnvelope(
+  program: Program,
+  response: Type | undefined,
+): boolean {
+  if (response?.kind !== 'Model') {
+    return false
+  }
+
+  const properties = [...walkPropertiesInherited(response)].filter(
+    (property) =>
+      !isStatusCode(program, property) && !isHeader(program, property),
+  )
+
+  return (
+    properties.length === 2 &&
+    properties.some(
+      (property) =>
+        property.name === 'data' &&
+        property.type.kind === 'Model' &&
+        $(program).array.is(property.type),
+    ) &&
+    properties.some((property) => property.name === 'meta')
+  )
+}
+
+function allIteratorDoc(operation: GoOperation, element: string): string {
+  const listName = goExportedName(operation.methodName)
+  return `${listName}All returns an iterator over all ${element} results, fetching pages of ${listName} transparently. Iteration stops at the first error, which is yielded as the second value.`
+}
+
+function pageElement(program: Program, response: Type): string {
+  if (response.kind !== 'Model') {
+    throw new Error('paginated response must be a model')
+  }
+  const data = response.properties.get('data')
+  if (!data || data.type.kind !== 'Model' || !$(program).array.is(data.type)) {
+    throw new Error(
+      `${typeName(program, response)} must contain an array data property`,
+    )
+  }
+  const element = data.type.indexer?.value
+  if (!element) {
+    throw new Error(`${typeName(program, response)} data array has no element`)
+  }
+
+  return readReferenceName(program, element)
+}
+
+function readReferenceName(program: Program, type: Type): string {
+  const mapped = goType(program, type).type
+  return typeof mapped === 'string' ? mapped : typeName(program, type)
+}
+
+// Locals every generated method body may declare (including the receiver and
+// the paginate callback arguments that capture path parameters); a path
+// parameter with one of these names would shadow them and emit non-compiling
+// or subtly wrong Go.
+const reservedMethodLocals = new Set([
+  'after',
+  'before',
+  'ctx',
+  'err',
+  'out',
+  'page',
+  'pageParams',
+  'params',
+  'path',
+  'q',
+  'req',
+  'request',
+  'resp',
+  's',
+  'size',
+])
+
+export function localName(name: string): string {
+  const exported = goExportedName(name)
+  const acronym = exported.match(/^([A-Z]{2,})([A-Z][a-z].*)$/)
+  const local = /^[A-Z0-9]+$/.test(exported)
+    ? exported.toLowerCase()
+    : acronym?.[1] && acronym[2]
+      ? acronym[1].toLowerCase() + acronym[2]
+      : exported.charAt(0).toLowerCase() + exported.slice(1)
+
+  return reservedMethodLocals.has(local) ? `${local}Param` : local
+}

api/spec/packages/typespec-go/src/components/GoStruct.tsx

@@ -0,0 +1,41 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import type { Refkey } from '@alloy-js/core'
+import type { GoField } from '../go-types.js'
+
+export interface GoStructProps {
+  name: string
+  fields: GoField[]
+  refkey?: Refkey
+  doc?: string
+  tags?: boolean
+}
+
+export function GoStruct({
+  name,
+  fields,
+  refkey,
+  doc,
+  tags = true,
+}: GoStructProps) {
+  return (
+    <go.StructTypeDeclaration name={name} refkey={refkey} doc={doc}>
+      <ay.List hardline>
+        {fields.map((field) => (
+          <go.StructMember
+            name={field.name}
+            type={field.type}
+            doc={field.doc}
+            tag={
+              tags
+                ? {
+                    json: `${field.wireName}${field.optional ? ',omitempty' : ''}`,
+                  }
+                : undefined
+            }
+          />
+        ))}
+      </ay.List>
+    </go.StructTypeDeclaration>
+  )
+}

api/spec/packages/typespec-go/src/components/GoTypeSpecEnum.tsx

@@ -0,0 +1,55 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import type { Enum } from '@typespec/compiler'
+import { goExportedName } from '../go-types.js'
+
+export function GoTypeSpecEnum({
+  enumType,
+  name,
+  doc,
+}: {
+  enumType: Enum
+  name: string
+  doc?: string
+}) {
+  const members = [...enumType.members.values()].map((member) => ({
+    name: `${name}${goExportedName(member.name)}`,
+    value: member.value ?? member.name,
+  }))
+  const underlying = members.some((member) => typeof member.value === 'number')
+    ? 'int'
+    : 'string'
+
+  return (
+    <>
+      <go.TypeDeclaration name={name} doc={doc}>
+        {underlying}
+      </go.TypeDeclaration>
+      {'\n\n'}
+      <go.VariableDeclarationGroup const>
+        <ay.List hardline>
+          {members.map((member) => (
+            <go.VariableDeclaration name={member.name} type={name}>
+              {JSON.stringify(member.value)}
+            </go.VariableDeclaration>
+          ))}
+        </ay.List>
+      </go.VariableDeclarationGroup>
+      {'\n\n'}
+      <go.FunctionDeclaration
+        name="Valid"
+        receiver={<go.FunctionReceiver name="value" type={name} />}
+        returns="bool"
+      >
+        {ay.code`
+          switch value {
+          case ${members.map((member) => member.name).join(', ')}:
+            return true
+          default:
+            return false
+          }
+        `}
+      </go.FunctionDeclaration>
+    </>
+  )
+}

api/spec/packages/typespec-go/src/components/GoUnion.tsx

@@ -0,0 +1,389 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import type {
+  Model,
+  ModelProperty,
+  Program,
+  Type,
+  Union,
+  UnionVariant,
+} from '@typespec/compiler'
+import { resolveEncodedName } from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { goExportedName, goType } from '../go-types.js'
+import { json } from '../stdlib.js'
+
+export interface GoUnionProps {
+  program: Program
+  union: Union
+  name: string
+  mode?: 'input' | 'output'
+  doc?: string
+}
+
+/**
+ * Emits a JSON-preserving tagged union with named, typed accessors for every
+ * model variant. The raw payload is retained so unknown discriminator values
+ * remain forward compatible and round-trip unchanged.
+ */
+export function GoUnion({ program, union, name, mode, doc }: GoUnionProps) {
+  const modelVariants = [...union.variants.values()].flatMap((variant) =>
+    variant.type.kind === 'Model' ? [variant.type] : [],
+  )
+  const discriminator = discriminatorProperty(program, union, modelVariants)
+  if (!discriminator && modelVariants.length > 1) {
+    throw new Error(
+      `typespec-go: union ${name} has multiple object variants but no discriminator; add @discriminated so Go accessors can select variants safely`,
+    )
+  }
+  // The discriminated path assumes every selectable variant is a model: the
+  // From* constructors envelope the payload under the discriminator property
+  // and the As* accessors match on it. A scalar or enum variant has neither,
+  // so it would emit constructors/accessors that cannot round-trip.
+  if (discriminator) {
+    const nonModelVariants = [...union.variants.values()].filter(
+      (variant) =>
+        variant.type.kind !== 'Model' && variant.type.kind !== 'Intrinsic',
+    )
+    if (nonModelVariants.length > 0) {
+      throw new Error(
+        `typespec-go: discriminated union ${name} mixes model and non-model variants (${nonModelVariants
+          .map((variant) => variant.type.kind)
+          .join(', ')}); only model variants can carry the discriminator`,
+      )
+    }
+  }
+  const variants = [...union.variants.values()].flatMap((variant) => {
+    if (variant.type.kind === 'Intrinsic') {
+      return []
+    }
+
+    const mapped = goType(program, variant.type, { mode }).type
+    return [
+      {
+        variant,
+        type: variant.type,
+        name:
+          variant.type.kind === 'Model' && typeof mapped === 'string'
+            ? mapped
+            : variantAccessorName(program, name, variant),
+        goType: mapped,
+        discriminatorValue:
+          variant.type.kind === 'Model'
+            ? discriminatorLiteral(variant.type, discriminator)
+            : undefined,
+      },
+    ]
+  })
+  const discriminatorField = discriminator
+    ? goExportedName(discriminator.wireName.replace(/^\$/, ''))
+    : 'Type'
+
+  const contractDoc = [
+    ...(doc ? [doc, ''] : []),
+    `${name} is a JSON-preserving tagged union: its zero value marshals as JSON null, and values must be built with the ${name}From* constructors.`,
+    ...(discriminator
+      ? [
+          `The exported ${discriminatorField} field is decode-side metadata; MarshalJSON round-trips the original payload and ignores writes to it.`,
+        ]
+      : []),
+  ].join('\n')
+
+  return (
+    <ay.List joiner={'\n\n'}>
+      <go.StructTypeDeclaration name={name} doc={contractDoc}>
+        <ay.List hardline>
+          {discriminator ? (
+            <go.StructMember
+              name={discriminatorField}
+              type="string"
+              tag={{ json: discriminator.wireName }}
+            />
+          ) : undefined}
+          <go.StructMember name="raw" type={json.RawMessage} />
+        </ay.List>
+      </go.StructTypeDeclaration>
+      <go.FunctionDeclaration
+        name="UnmarshalJSON"
+        receiver={
+          <go.FunctionReceiver
+            name="u"
+            type={<go.Pointer>{name}</go.Pointer>}
+          />
+        }
+        parameters={[{ name: 'data', type: '[]byte' }]}
+        returns="error"
+      >
+        {discriminator
+          ? ay.code`
+              u.raw = append([]byte(nil), data...)
+              if string(data) == "null" {
+                u.${discriminatorField} = ""
+                return nil
+              }
+
+              var envelope struct {
+                Value string ${`\`json:${JSON.stringify(discriminator.wireName)}\``}
+              }
+              if err := ${json.Unmarshal}(data, &envelope); err != nil {
+                return err
+              }
+              u.${discriminatorField} = envelope.Value
+              return nil
+            `
+          : ay.code`
+              u.raw = append([]byte(nil), data...)
+              return nil
+            `}
+      </go.FunctionDeclaration>
+      <go.FunctionDeclaration
+        name="MarshalJSON"
+        receiver={<go.FunctionReceiver name="u" type={name} />}
+        returns={['[]byte', 'error']}
+      >
+        {ay.code`
+          if len(u.raw) == 0 {
+            return []byte("null"), nil
+          }
+          return append([]byte(nil), u.raw...), nil
+        `}
+      </go.FunctionDeclaration>
+      <ay.List>
+        {variants.flatMap((item) => [
+          <go.FunctionDeclaration
+            name={`As${item.name}`}
+            receiver={<go.FunctionReceiver name="u" type={name} />}
+            returns={[<go.Pointer>{item.goType}</go.Pointer>, 'error']}
+          >
+            {accessorBody({
+              unionName: name,
+              variantName: item.name,
+              variantType: item.type,
+              goType: item.goType,
+              discriminator,
+              discriminatorField,
+              discriminatorValue: item.discriminatorValue,
+            })}
+          </go.FunctionDeclaration>,
+          '\n\n',
+          <go.FunctionDeclaration
+            name={`${name}From${item.name}`}
+            parameters={[{ name: 'value', type: item.goType }]}
+            returns={[name, 'error']}
+          >
+            {discriminator && item.discriminatorValue !== undefined
+              ? ay.code`
+                  value.${discriminatorField} = ${JSON.stringify(item.discriminatorValue)}
+                  raw, err := ${json.Marshal}(value)
+                  if err != nil {
+                    return ${name}{}, err
+                  }
+                  var result ${name}
+                  if err := result.UnmarshalJSON(raw); err != nil {
+                    return ${name}{}, err
+                  }
+                  return result, nil
+                `
+              : ay.code`
+                  raw, err := ${json.Marshal}(value)
+                  if err != nil {
+                    return ${name}{}, err
+                  }
+                  var result ${name}
+                  if err := result.UnmarshalJSON(raw); err != nil {
+                    return ${name}{}, err
+                  }
+                  return result, nil
+                `}
+          </go.FunctionDeclaration>,
+          '\n\n',
+        ])}
+      </ay.List>
+    </ay.List>
+  )
+}
+
+function accessorBody({
+  unionName,
+  variantName,
+  variantType,
+  goType: goTypeName,
+  discriminator,
+  discriminatorField,
+  discriminatorValue,
+}: {
+  unionName: string
+  variantName: string
+  variantType: Type
+  goType: ay.Children
+  discriminator: { name: string; wireName: string } | undefined
+  discriminatorField: string
+  discriminatorValue: string | undefined
+}): ay.Children {
+  const discriminatorGuard =
+    discriminator && discriminatorValue !== undefined
+      ? ay.code`
+          if u.${discriminatorField} != ${JSON.stringify(discriminatorValue)} {
+            return nil, ${go.std.fmt.Errorf}("${unionName}: expected ${discriminator.wireName} %q, got %q", ${JSON.stringify(discriminatorValue)}, u.${discriminatorField})
+          }
+        `
+      : undefined
+  const scalarGuard = variantValidation(unionName, variantName, variantType)
+
+  if (discriminatorGuard && scalarGuard) {
+    return ay.code`
+      ${discriminatorGuard}
+      var value ${goTypeName}
+      if err := ${json.Unmarshal}(u.raw, &value); err != nil {
+        return nil, err
+      }
+      ${scalarGuard}
+      return &value, nil
+    `
+  }
+
+  if (discriminatorGuard) {
+    return ay.code`
+      ${discriminatorGuard}
+      var value ${goTypeName}
+      if err := ${json.Unmarshal}(u.raw, &value); err != nil {
+        return nil, err
+      }
+      return &value, nil
+    `
+  }
+
+  if (scalarGuard) {
+    return ay.code`
+      var value ${goTypeName}
+      if err := ${json.Unmarshal}(u.raw, &value); err != nil {
+        return nil, err
+      }
+      ${scalarGuard}
+      return &value, nil
+    `
+  }
+
+  return ay.code`
+    var value ${goTypeName}
+    if err := ${json.Unmarshal}(u.raw, &value); err != nil {
+      return nil, err
+    }
+    return &value, nil
+  `
+}
+
+export function variantAccessorName(
+  program: Program,
+  unionName: string,
+  variant: UnionVariant,
+): string {
+  const variantName =
+    typeof variant.name === 'symbol'
+      ? `Variant${goExportedName(String(variant.name.description ?? ''))}`
+      : goExportedName(variant.name)
+  return variantName || `${unionName}Variant`
+}
+
+export function discriminatorProperty(
+  program: Program,
+  union: Union,
+  variants: Model[],
+): { name: string; wireName: string } | undefined {
+  if (variants.length === 0) {
+    return undefined
+  }
+
+  const discriminated = $(program).union.getDiscriminatedUnion(union)
+  if (discriminated) {
+    if (discriminated.options.envelope !== 'none') {
+      throw new Error(
+        `typespec-go: union ${union.name ?? '<anonymous union>'} uses unsupported discriminated union envelope ${discriminated.options.envelope}`,
+      )
+    }
+    const name = discriminated.options.discriminatorPropertyName
+    const property = variants[0]?.properties.get(name)
+    return {
+      name,
+      wireName: property
+        ? resolveEncodedName(
+            program,
+            property as ModelProperty & { name: string },
+            'application/json',
+          )
+        : name,
+    }
+  }
+
+  for (const candidate of ['type', '$type']) {
+    if (
+      variants.length > 0 &&
+      variants.every((model) => model.properties.has(candidate))
+    ) {
+      const property = variants[0]!.properties.get(candidate)!
+      return {
+        name: candidate,
+        wireName: resolveEncodedName(program, property, 'application/json'),
+      }
+    }
+  }
+
+  return undefined
+}
+
+export function discriminatorLiteral(
+  model: Model,
+  discriminator: { name: string; wireName: string } | undefined,
+): string | undefined {
+  if (!discriminator) {
+    return undefined
+  }
+
+  const property = model.properties.get(discriminator.name)
+  if (!property) {
+    return undefined
+  }
+
+  switch (property.type.kind) {
+    case 'String':
+      return property.type.value
+    case 'EnumMember':
+      return String(property.type.value ?? property.type.name)
+    default:
+      return undefined
+  }
+}
+
+function variantValidation(
+  unionName: string,
+  variantName: string,
+  type: Type,
+): ay.Children {
+  switch (type.kind) {
+    case 'Enum':
+      return ay.code`
+        if !value.Valid() {
+          return nil, ${go.std.fmt.Errorf}("${unionName}: value %q is not ${variantName}", value)
+        }
+      `
+    case 'EnumMember':
+      return ay.code`
+        if value != ${JSON.stringify(type.value ?? type.name)} {
+          return nil, ${go.std.fmt.Errorf}("${unionName}: value %q is not ${variantName}", value)
+        }
+      `
+    case 'String':
+    case 'Number':
+    case 'Boolean':
+      if ('value' in type && type.value !== undefined) {
+        return ay.code`
+          if value != ${JSON.stringify(type.value)} {
+            return nil, ${go.std.fmt.Errorf}("${unionName}: value %q is not ${variantName}", value)
+          }
+        `
+      }
+      return undefined
+    default:
+      return undefined
+  }
+}

api/spec/packages/typespec-go/src/emitter.tsx

@@ -0,0 +1,602 @@
+import * as go from '@alloy-js/go'
+import * as ay from '@alloy-js/core'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { type EmitContext, emitFile, resolvePath } from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { Output, writeOutput } from '@typespec/emitter-framework'
+import { GoClient } from './components/GoClient.js'
+import { GoModels } from './components/GoModels.js'
+import { GoResource } from './components/GoResource.js'
+import {
+  configureGoProjections,
+  configureGoTypeNames,
+  optionalTypeName,
+  queryScalarKind,
+  resolveGoTypeNames,
+  setSyntheticTypeNames,
+  type GoDeclarationPlan,
+} from './go-types.js'
+import { groupOperations, operationNestPath } from './grouping.js'
+import type { GoEmitterOptions } from './lib.js'
+import {
+  computeDivergentTypes,
+  computeReachability,
+  computeStructuralAliases,
+  planDeclarations,
+  promoteAnonymousModels,
+} from './projections.js'
+import {
+  collectHttpOperations,
+  describeOperations,
+  jsonBodyOverrides,
+} from './operations.js'
+import { readmeFile } from './readme.js'
+import { RUNTIME_TEMPLATES } from './runtime-templates.js'
+import {
+  conflictsWithReservedGoSymbol,
+  isRuntimeBackedTypeName,
+} from './runtime-symbols.js'
+
+const execFileAsync = promisify(execFile)
+const generatedHeader =
+  '// Code generated by @openmeter/typespec-go. DO NOT EDIT.'
+
+/**
+ * Emits the OpenMeter Go SDK from the AIP TypeSpec program.
+ *
+ * The static runtime is emitted from TypeScript templates
+ * (RUNTIME_TEMPLATES). Models, the root client, and every resource service are
+ * generated from the walked program through one metadata-driven path. The
+ * optional include-resources setting only narrows that generic path; by default
+ * every discovered operation group is emitted.
+ */
+export async function $onEmit(context: EmitContext<GoEmitterOptions>) {
+  const { program, emitterOutputDir } = context
+  const pkg = context.options['package-name']
+  const modulePath = context.options['module-path']
+  const sdkVersion = context.options['sdk-version'] ?? '0.0.0-dev'
+  const goVersion = context.options['go-version'] ?? '1.23'
+  if (!modulePath) {
+    throw new Error(
+      "typespec-go: the module-path option is required; set it to the SDK's published Go module path (e.g. github.com/openmeterio/openmeter/api/v3/client) in tspconfig.yaml",
+    )
+  }
+  if (!pkg) {
+    throw new Error(
+      'typespec-go: the package-name option is required; set it to the generated Go package name (e.g. openmeter) in tspconfig.yaml',
+    )
+  }
+  configureGoTypeNames(program, context.options['strip-name-prefixes'] ?? [])
+
+  await cleanOutputDirectory(program.host, emitterOutputDir)
+
+  const operations = collectHttpOperations(
+    program,
+    context.options['include-services'],
+  )
+  const groups = groupOperations(operations)
+  const includeResources = new Set(
+    context.options['include-resources'] ?? groups.keys(),
+  )
+  for (const resource of includeResources) {
+    if (!groups.has(resource)) {
+      throw new Error(
+        `unknown include-resources entry ${resource}; available resources: ${[...groups.keys()].join(', ')}`,
+      )
+    }
+  }
+  const includedGroups = [...groups].filter(([resource]) =>
+    includeResources.has(resource),
+  )
+  const bodyOverrides = jsonBodyOverrides(program)
+  const reachability = computeReachability(
+    program,
+    includedGroups,
+    bodyOverrides,
+  )
+  const modelTypes = new Set(
+    [...reachability.byResource.values()].flatMap((types) => [...types]),
+  )
+  resolveGoTypeNames(program, modelTypes)
+  setSyntheticTypeNames(program, promoteAnonymousModels(program, modelTypes))
+  const typeOwners = new Map<import('@typespec/compiler').Type, Set<string>>()
+  for (const [resource, types] of reachability.byResource) {
+    for (const type of types) {
+      const owners = typeOwners.get(type)
+      if (owners) {
+        owners.add(resource)
+      } else {
+        typeOwners.set(type, new Set([resource]))
+      }
+    }
+  }
+  const divergentTypes = computeDivergentTypes(
+    program,
+    reachability.readReachable,
+    reachability.inputReachable,
+  )
+  const declarationPlan = planDeclarations(
+    program,
+    modelTypes,
+    reachability.readReachable,
+    reachability.inputReachable,
+    divergentTypes,
+  )
+  const structuralAliases = computeStructuralAliases(
+    program,
+    declarationPlan,
+    reachability.readReachable,
+    divergentTypes,
+  )
+  configureGoProjections(program, {
+    readReachable: reachability.readReachable,
+    inputReachable: reachability.inputReachable,
+    divergent: divergentTypes,
+    aliases: structuralAliases,
+    declarations: declarationPlan,
+  })
+  validateUniqueTypeNames(program, modelTypes)
+  const modelGroups = groupTypesByOwner(
+    program,
+    modelTypes,
+    typeOwners,
+    declarationPlan,
+  )
+
+  // Runtime helpers stay verbatim. All spec-derived models, services, and
+  // client wiring are emitted below.
+  for (const [path, content] of Object.entries(RUNTIME_TEMPLATES)) {
+    await emitFile(program, {
+      path: resolvePath(emitterOutputDir, path),
+      content: prepareRuntimeTemplate(
+        path,
+        content,
+        pkg,
+        modulePath,
+        sdkVersion,
+        goVersion,
+      ),
+    })
+  }
+
+  const clientRefkey = ay.refkey()
+  const resources = includedGroups.flatMap(([root, resourceOperations]) => {
+    const operationsByPath = new Map<string, typeof resourceOperations>()
+    operationsByPath.set('', [])
+    for (const operation of resourceOperations) {
+      const nestPath = operationNestPath(operation, root)
+      for (let depth = 1; depth <= nestPath.length; depth++) {
+        const ancestorKey = nestPath.slice(0, depth).join('\0')
+        if (!operationsByPath.has(ancestorKey)) {
+          operationsByPath.set(ancestorKey, [])
+        }
+      }
+      const key = nestPath.join('\0')
+      operationsByPath.get(key)!.push(operation)
+    }
+
+    return [...operationsByPath].map(([key, nodeOperations]) => {
+      const nestPath = key ? key.split('\0') : []
+      return {
+        name: [root, ...nestPath].join(''),
+        root,
+        nestPath,
+        operations: nodeOperations,
+        serviceRefkey: ay.refkey(),
+      }
+    })
+  })
+
+  const childrenOf = (resource: (typeof resources)[number]) =>
+    resources
+      .filter(
+        (candidate) =>
+          candidate.root === resource.root &&
+          candidate.nestPath.length === resource.nestPath.length + 1 &&
+          resource.nestPath.every(
+            (segment, index) => candidate.nestPath[index] === segment,
+          ),
+      )
+      .map((candidate) => ({
+        name: candidate.nestPath.at(-1)!,
+        serviceRefkey: candidate.serviceRefkey,
+      }))
+
+  validateOperationIR(program, resources, bodyOverrides)
+
+  await emitFile(program, {
+    path: resolvePath(emitterOutputDir, 'README.md'),
+    content: readmeFile(
+      program,
+      modulePath,
+      pkg,
+      resources,
+      bodyOverrides,
+      context.options['readme-note'],
+    ),
+  })
+
+  // The header prop renders before the package clause: the Go generated-code
+  // convention (go/ast.IsGenerated, golangci-lint, linguist) only recognizes
+  // the DO NOT EDIT marker when it precedes `package`.
+  const fileHeader = `${generatedHeader}\n\n`
+  await writeOutput(
+    program,
+    <Output program={program} useTabs printWidth={1000}>
+      <go.ModuleDirectory name={modulePath}>
+        <go.SourceDirectory path="." name={pkg}>
+          <go.SourceFile path="doc.go" header={packageDocHeader(pkg)} />
+          {[...modelGroups].map(([namespace, types]) => (
+            <go.SourceFile
+              path={`models_${goFileSegment(namespace)}.go`}
+              header={fileHeader}
+            >
+              <GoModels program={program} types={types} />
+            </go.SourceFile>
+          ))}
+          {resources.map((resource) => (
+            <go.SourceFile path={serviceFileName(resource)} header={fileHeader}>
+              <GoResource
+                program={program}
+                resource={resource.root}
+                serviceName={resource.name}
+                nestPath={resource.nestPath}
+                operations={resource.operations}
+                bodyOverrides={bodyOverrides}
+                serviceRefkey={resource.serviceRefkey}
+                children={childrenOf(resource)}
+              />
+            </go.SourceFile>
+          ))}
+          <go.SourceFile path="client.go" header={fileHeader}>
+            <GoClient clientRefkey={clientRefkey} resources={resources} />
+          </go.SourceFile>
+        </go.SourceDirectory>
+      </go.ModuleDirectory>
+    </Output>,
+    emitterOutputDir,
+  )
+
+  const generatedFiles = [
+    resolvePath(emitterOutputDir, 'doc.go'),
+    resolvePath(emitterOutputDir, 'client.go'),
+    ...[...modelGroups.keys()].map((namespace) =>
+      resolvePath(emitterOutputDir, `models_${goFileSegment(namespace)}.go`),
+    ),
+    ...resources.map((resource) =>
+      resolvePath(emitterOutputDir, serviceFileName(resource)),
+    ),
+  ]
+  // alloy's Go printer does not column-align struct tags the way gofmt does, so
+  // a gofmt pass makes the generated files gofmt-clean. This couples generation
+  // to a Go toolchain on PATH; surface a clear error if it is missing rather
+  // than a raw spawn ENOENT.
+  try {
+    await execFileAsync('gofmt', ['-w', ...generatedFiles])
+  } catch (err) {
+    throw new Error(
+      `typespec-go: gofmt is required to format the generated Go SDK but could not run ` +
+        `(${(err as Error).message}). Install the Go toolchain or put gofmt on PATH.`,
+    )
+  }
+}
+
+// Removes previously generated output before emission so file renames (for
+// example llmcost.go -> llm_cost.go or newly nested service files) cannot
+// leave duplicate declarations behind. Hand-written Go wire tests (*_test.go
+// and their testdata/ fixtures) live alongside the generated files to assert
+// wire behavior against the emitted SDK; they are not emitter-owned, so they
+// must survive regeneration instead of being silently wiped.
+export async function cleanOutputDirectory(
+  host: Pick<import('@typespec/compiler').CompilerHost, 'readDir' | 'rm'>,
+  outputDir: string,
+): Promise<void> {
+  let entries: string[]
+  try {
+    entries = await host.readDir(outputDir)
+  } catch (error) {
+    if (
+      typeof error === 'object' &&
+      error !== null &&
+      'code' in error &&
+      error.code === 'ENOENT'
+    ) {
+      return
+    }
+    throw error
+  }
+
+  for (const entry of entries) {
+    if (entry.endsWith('_test.go') || entry === 'testdata') {
+      continue
+    }
+    await host.rm(resolvePath(outputDir, entry), { recursive: true })
+  }
+}
+
+export function prepareRuntimeTemplate(
+  path: string,
+  content: string,
+  pkg: string,
+  modulePath: string,
+  sdkVersion: string,
+  goVersion: string,
+): string {
+  if (path === 'go.mod') {
+    return content
+      .replaceAll('{{MODULE_PATH}}', modulePath)
+      .replaceAll('{{GO_VERSION}}', goVersion)
+  }
+  if (!path.endsWith('.go')) {
+    return content
+  }
+
+  return `${generatedHeader}\n\n${content
+    .replace(/^package openmeter/m, `package ${pkg}`)
+    .replaceAll('{{MODULE_PATH}}', modulePath)
+    .replaceAll('{{SDK_VERSION}}', sdkVersion)}`
+}
+
+/** The doc.go prelude: the generated-code marker, a blank separator line so
+ * the marker does not become package documentation, then the package godoc
+ * attached to the package clause the source file renders right after it. */
+export function packageDocHeader(pkg: string): string {
+  return (
+    [
+      generatedHeader,
+      '',
+      `// Package ${pkg} provides a Go client SDK for the OpenMeter API — usage`,
+      '// metering and billing for AI and DevTool companies. It is generated from the',
+      '// OpenMeter TypeSpec definitions and exposes every operation as a method on a',
+      '// typed service hanging off [Client] (for example Client.Meters), with typed',
+      '// request and response models.',
+      '//',
+      '// Construct a [Client] with [New], passing the API base URL and a bearer',
+      '// token via [WithToken]:',
+      '//',
+      `//	om, err := ${pkg}.New(`,
+      '//		"https://openmeter.cloud/api/v3",',
+      `//		${pkg}.WithToken(os.Getenv("OPENMETER_API_KEY")),`,
+      '//	)',
+      '//',
+      '// Any non-2xx response is returned as an [APIError] carrying the HTTP status',
+      '// code and the RFC 7807 problem fields; unwrap it with [errors.As] or',
+      '// [AsAPIError]. Client-side validation failures such as an empty resource ID',
+      '// are reported before any request is sent and match [ErrEmptyID] via',
+      '// [errors.Is].',
+      '//',
+      '// Paginated list operations additionally provide ...All variants returning',
+      '// [iter.Seq2] sequences that fetch pages lazily and yield each item together',
+      '// with an error.',
+    ].join('\n') + '\n'
+  )
+}
+
+function serviceFileName(resource: {
+  root: string
+  nestPath: string[]
+}): string {
+  return `${[resource.root, ...resource.nestPath]
+    .map(goFileSegment)
+    .join('_')}.go`
+}
+
+function groupTypesByOwner(
+  program: import('@typespec/compiler').Program,
+  types: Set<import('@typespec/compiler').Type>,
+  owners: Map<import('@typespec/compiler').Type, Set<string>>,
+  declarationPlan: Map<import('@typespec/compiler').Type, GoDeclarationPlan[]>,
+): Map<string, Set<import('@typespec/compiler').Type>> {
+  // Only types that actually render a declaration claim a models file: scalar
+  // aliases are pruned and structural-dedupe drops collapsed projections, so
+  // grouping them would leave empty generated files behind.
+  const emitting = new Set(
+    [...types].filter((type) => {
+      switch (type.kind) {
+        case 'Enum':
+          return optionalTypeName(program, type) !== undefined
+        case 'Model':
+        case 'Union':
+          return (declarationPlan.get(type)?.length ?? 0) > 0
+        default:
+          return false
+      }
+    }),
+  )
+
+  const ownersByName = new Map<string, Set<string>>()
+  for (const type of emitting) {
+    const name = optionalTypeName(program, type)
+    if (!name) {
+      continue
+    }
+    const namedOwners = ownersByName.get(name) ?? new Set<string>()
+    for (const owner of owners.get(type) ?? []) {
+      namedOwners.add(owner)
+    }
+    ownersByName.set(name, namedOwners)
+  }
+
+  const groups = new Map<string, Set<import('@typespec/compiler').Type>>()
+  for (const type of emitting) {
+    const name = optionalTypeName(program, type)
+    const typeOwner = name ? ownersByName.get(name) : owners.get(type)
+    const key = typeOwner?.size === 1 ? [...typeOwner][0]! : 'shared'
+    const group = groups.get(key)
+    if (group) {
+      group.add(type)
+    } else {
+      groups.set(key, new Set([type]))
+    }
+  }
+
+  // Code-point comparison, not localeCompare: the output is a committed
+  // artifact, and locale-dependent ordering would produce spurious diffs
+  // across machines.
+  return new Map(
+    [...groups].sort(([left], [right]) =>
+      left < right ? -1 : left > right ? 1 : 0,
+    ),
+  )
+}
+
+function goFileSegment(segment: string): string {
+  return segment
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+}
+
+export function validateUniqueTypeNames(
+  program: import('@typespec/compiler').Program,
+  types: Set<import('@typespec/compiler').Type>,
+): void {
+  const typekit = $(program)
+  const names = new Map<string, import('@typespec/compiler').Type>()
+  for (const type of types) {
+    if (
+      type.kind !== 'Model' &&
+      type.kind !== 'Union' &&
+      type.kind !== 'Enum' &&
+      type.kind !== 'Scalar'
+    ) {
+      continue
+    }
+    if (
+      type.kind === 'Model' &&
+      (typekit.array.is(type) || typekit.record.is(type))
+    ) {
+      continue
+    }
+    const name = optionalTypeName(program, type)
+    if (!name) {
+      continue
+    }
+    if (isRuntimeBackedTypeName(name, type.kind)) {
+      continue
+    }
+    if (conflictsWithReservedGoSymbol(name, type.kind)) {
+      throw new Error(
+        `typespec-go: Go type ${name} conflicts with reserved SDK runtime symbol ${name}; add a distinct @friendlyName or rename the TypeSpec construct`,
+      )
+    }
+    const existing = names.get(name)
+    if (existing && existing !== type) {
+      if (
+        existing.kind === 'Model' &&
+        type.kind === 'Model' &&
+        modelSignature(program, existing) === modelSignature(program, type)
+      ) {
+        continue
+      }
+      try {
+        if (
+          queryScalarKind(program, existing) === queryScalarKind(program, type)
+        ) {
+          continue
+        }
+      } catch {
+        // Non-scalar collisions are always ambiguous.
+      }
+      throw new Error(
+        `typespec-go: Go type name collision for ${name} (${existing.kind} and ${type.kind}); add a distinct @friendlyName instead of silently choosing one`,
+      )
+    }
+    names.set(name, type)
+  }
+}
+
+function validateOperationIR(
+  program: import('@typespec/compiler').Program,
+  resources: Array<{
+    root: string
+    nestPath: string[]
+    operations: import('@typespec/compiler').Operation[]
+  }>,
+  bodyOverrides: Map<string, import('@typespec/compiler').Type>,
+): void {
+  for (const resource of resources) {
+    const methods = new Set<string>()
+    for (const operation of describeOperations(
+      program,
+      resource.root,
+      resource.operations,
+      bodyOverrides,
+      resource.nestPath,
+    )) {
+      if (methods.has(operation.methodName)) {
+        throw new Error(
+          `typespec-go: duplicate method ${[resource.root, ...resource.nestPath, operation.methodName].join('.')}; add a distinct @friendlyName`,
+        )
+      }
+      methods.add(operation.methodName)
+
+      for (const parameter of operation.queryParams) {
+        if (!parameter.queryCodec) {
+          throw new Error(
+            `typespec-go: query parameter ${parameter.name} on ${operation.operation.name} has no serializer`,
+          )
+        }
+      }
+      if (operation.body && !operation.requestContentType) {
+        throw new Error(
+          `typespec-go: request body on ${operation.operation.name} has no content type`,
+        )
+      }
+    }
+  }
+}
+
+function modelSignature(
+  program: import('@typespec/compiler').Program,
+  model: import('@typespec/compiler').Model,
+): string {
+  const typeSignature = (
+    type: import('@typespec/compiler').Type,
+    seen = new Set<import('@typespec/compiler').Type>(),
+  ): string => {
+    if (seen.has(type)) {
+      return optionalTypeName(program, type) ?? type.kind
+    }
+    seen.add(type)
+
+    if (type.kind === 'Model') {
+      const typekit = $(program)
+      if (typekit.array.is(type)) {
+        return `[]${type.indexer ? typeSignature(type.indexer.value, seen) : '?'}`
+      }
+      if (typekit.record.is(type)) {
+        return `map:${type.indexer ? typeSignature(type.indexer.value, seen) : '?'}`
+      }
+      const name = optionalTypeName(program, type)
+      if (name) {
+        return `model:${name}`
+      }
+      return `model:{${[...type.properties.values()]
+        .map(
+          (property) =>
+            `${property.name}:${property.optional}:${property.defaultValue !== undefined}:${typeSignature(property.type, seen)}`,
+        )
+        .join(',')}}`
+    }
+    if (type.kind === 'Union') {
+      return `union:${[...type.variants.values()]
+        .map((variant) => typeSignature(variant.type, seen))
+        .join('|')}`
+    }
+    return `${type.kind}:${optionalTypeName(program, type) ?? ('value' in type ? String(type.value) : '')}`
+  }
+
+  return JSON.stringify({
+    base: model.baseModel
+      ? optionalTypeName(program, model.baseModel)
+      : undefined,
+    properties: [...model.properties.values()].map((property) => ({
+      name: property.name,
+      optional: property.optional,
+      defaulted: property.defaultValue !== undefined,
+      type: typeSignature(property.type),
+    })),
+  })
+}

api/spec/packages/typespec-go/src/go-types.tsx

@@ -0,0 +1,731 @@
+import * as ay from '@alloy-js/core'
+import * as go from '@alloy-js/go'
+import {
+  getFriendlyName,
+  resolveEncodedName,
+  walkPropertiesInherited,
+  type Model,
+  type ModelProperty,
+  type Program,
+  type Scalar,
+  type Type,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { isHeader, isStatusCode, isVisible, Visibility } from '@typespec/http'
+
+const stripNamePrefixes = new WeakMap<Program, readonly string[]>()
+const resolvedTypeNames = new WeakMap<Program, Map<string, string>>()
+const syntheticTypeNames = new WeakMap<Program, Map<Type, string>>()
+const projectionsByProgram = new WeakMap<Program, GoProjections>()
+
+export function inputVariantName(name: string): string {
+  return `${name}Input`
+}
+
+/** Which payload projection of a model a declaration or reference lives in:
+ * read models come from response bodies, input models from request bodies. */
+export type GoPayloadMode = 'read' | 'input'
+
+export interface GoDeclarationPlan {
+  name: string
+  mode: GoPayloadMode
+}
+
+/**
+ * Payload-context visibility state for one emitted program.
+ *
+ * Response-reachable models are rendered in a read context, so their
+ * Create-/Update-only properties (which the server never returns) are dropped.
+ * Request-reachable models are rendered in an input context that keeps every
+ * spec-projected property. A model needed by both contexts with different
+ * shapes is emitted twice (Name plus NameInput); `declarations` records
+ * exactly which projections each type emits, and `aliases` redirects
+ * declarations that would duplicate a structurally identical canonical type.
+ */
+export interface GoProjections {
+  readReachable: Set<Type>
+  inputReachable: Set<Type>
+  divergent: Set<Type>
+  aliases: Map<string, string>
+  declarations: Map<Type, GoDeclarationPlan[]>
+}
+
+export function configureGoProjections(
+  program: Program,
+  projections: GoProjections,
+): void {
+  projectionsByProgram.set(program, projections)
+}
+
+export function goProjectionsOf(program: Program): GoProjections | undefined {
+  return projectionsByProgram.get(program)
+}
+
+export function setSyntheticTypeNames(
+  program: Program,
+  names: Map<Type, string>,
+): void {
+  syntheticTypeNames.set(program, names)
+}
+
+/**
+ * The Go type name a field or accessor must reference for `type` in the given
+ * payload context: the input twin when the type emits one, then any
+ * structural-dedupe alias pointing at the canonical declaration.
+ */
+export function goReferenceTypeName(
+  program: Program,
+  type: Type,
+  name: string,
+  mode?: 'input' | 'output',
+): string {
+  const projections = goProjectionsOf(program)
+  if (!projections) {
+    return name
+  }
+
+  let final =
+    mode === 'input' && projections.divergent.has(type)
+      ? inputVariantName(name)
+      : name
+  while (projections.aliases.has(final)) {
+    final = projections.aliases.get(final)!
+  }
+  return final
+}
+
+export interface GoField {
+  name: string
+  wireName: string
+  type: ay.Children
+  /** Plain-text rendering of `type` when expressible without alloy context;
+   * consumed by the structural-dedupe signature. */
+  typeText?: string
+  optional: boolean
+  nilable: boolean
+  doc?: string
+}
+
+export type GoQueryScalarKind =
+  | 'string'
+  | 'boolean'
+  | 'integer'
+  | 'float'
+  | 'dateTime'
+
+export type GoQueryFilterKind =
+  | 'string'
+  | 'stringExact'
+  | 'dateTime'
+  | 'numeric'
+  | 'boolean'
+  | 'labels'
+  | 'scalar'
+
+export interface GoTypeOptions {
+  mode?: 'input' | 'output'
+}
+
+export interface GoTypeResult {
+  type: ay.Children
+  /** Plain-text rendering of `type`; undefined only for inline struct
+   * literals, which cannot participate in structural dedupe. */
+  text?: string
+  nilable: boolean
+  jsonNullable?: boolean
+}
+
+export function configureGoTypeNames(
+  program: Program,
+  prefixes: readonly string[],
+): void {
+  stripNamePrefixes.set(program, prefixes)
+  resolvedTypeNames.delete(program)
+}
+
+export function resolveGoTypeNames(program: Program, types: Iterable<Type>) {
+  const baseNames = [...types]
+    .map((type) => baseGoTypeName(program, type))
+    .filter((name): name is string => name !== undefined)
+
+  resolvedTypeNames.set(
+    program,
+    resolveStrippedNames(baseNames, stripNamePrefixes.get(program) ?? []),
+  )
+}
+
+export function goFields(
+  program: Program,
+  model: Model,
+  options: {
+    omit?: Set<string>
+    mode?: 'input' | 'output'
+  } = {},
+): GoField[] {
+  const fields: GoField[] = []
+  const projections = goProjectionsOf(program)
+  // Payload-context visibility: a response-reachable model is rendered in a
+  // read context, so Create-/Update-only properties (never returned by the
+  // server) are dropped from it. Request payloads render in input mode and
+  // keep every property the spec projected into them; without a configured
+  // projection registry (unit tests) nothing is filtered.
+  const filterRead =
+    options.mode !== 'input' &&
+    projections !== undefined &&
+    projections.readReachable.has(model)
+
+  for (const property of walkPropertiesInherited(model)) {
+    if (
+      isStatusCode(program, property) ||
+      isHeader(program, property) ||
+      options.omit?.has(property.name)
+    ) {
+      continue
+    }
+    if (filterRead && !isVisible(program, property, Visibility.Read)) {
+      continue
+    }
+
+    const mapped = goType(program, property.type, options)
+    const optional =
+      property.optional ||
+      (options.mode === 'input' && property.defaultValue !== undefined)
+    const pointerOptional =
+      optional &&
+      !mapped.jsonNullable &&
+      (!mapped.nilable || options.mode === 'input')
+    fields.push({
+      name: goExportedName(property.name),
+      wireName: resolveEncodedName(
+        program,
+        property as ModelProperty & { name: string },
+        'application/json',
+      ),
+      type: pointerOptional ? (
+        <go.Pointer>{mapped.type}</go.Pointer>
+      ) : (
+        mapped.type
+      ),
+      typeText:
+        mapped.text === undefined
+          ? undefined
+          : `${pointerOptional ? '*' : ''}${mapped.text}`,
+      optional,
+      nilable: mapped.nilable,
+      doc: $(program).type.getDoc(property),
+    })
+  }
+
+  return fields
+}
+
+export function goType(
+  program: Program,
+  type: Type,
+  options: GoTypeOptions = {},
+): GoTypeResult {
+  switch (type.kind) {
+    case 'Boolean':
+      return { type: 'bool', text: 'bool', nilable: false }
+    case 'Number': {
+      const text = Number.isInteger(type.value) ? 'int' : 'float64'
+      return { type: text, text, nilable: false }
+    }
+    case 'String':
+      return { type: 'string', text: 'string', nilable: false }
+    case 'Scalar':
+      return scalarType(type)
+    case 'Union': {
+      const nullable = nullableUnionElement(type)
+      if (nullable) {
+        const element = goType(program, nullable, options)
+        return {
+          type: ay.code`Nullable[${element.type}]`,
+          text:
+            element.text === undefined
+              ? undefined
+              : `Nullable[${element.text}]`,
+          nilable: false,
+          jsonNullable: true,
+        }
+      }
+
+      const oneOrMany = oneOrManyElement(program, type)
+      if (oneOrMany) {
+        const element = goType(program, oneOrMany, options)
+        return {
+          type: ay.code`OneOrMany[${element.type}]`,
+          text:
+            element.text === undefined
+              ? undefined
+              : `OneOrMany[${element.text}]`,
+          nilable: false,
+        }
+      }
+
+      const name = optionalTypeName(program, type)
+      if (!name) {
+        const variants = [...type.variants.values()]
+          .map((variant) => variant.type)
+          .filter((variant) => variant.kind !== 'Intrinsic')
+        if (variants.length === 1) {
+          return goType(program, variants[0]!, options)
+        }
+        if (
+          variants.length > 1 &&
+          variants.every((variant) => variant.kind === 'String')
+        ) {
+          return { type: 'string', text: 'string', nilable: false }
+        }
+        throw new Error(
+          `anonymous union of [${[...type.variants.values()]
+            .map((variant) => variant.type.kind)
+            .join(
+              ', ',
+            )}] is not representable in Go; name the union or reduce it to string literals or a single concrete variant`,
+        )
+      }
+      const runtime = runtimeFilterTypeName(name)
+      if (runtime !== name) {
+        return { type: runtime, text: runtime, nilable: false }
+      }
+      const reference = goReferenceTypeName(program, type, name, options.mode)
+      return { type: reference, text: reference, nilable: false }
+    }
+    case 'Enum': {
+      const name = typeName(program, type)
+      return { type: name, text: name, nilable: false }
+    }
+    case 'EnumMember': {
+      const name = typeName(program, type.enum)
+      return { type: name, text: name, nilable: false }
+    }
+    case 'Model': {
+      const typekit = $(program)
+      if (typekit.array.is(type)) {
+        const element = type.indexer?.value
+        if (!element) {
+          throw new Error('array model is missing its element type')
+        }
+        const mapped = goType(program, element, options)
+        return {
+          type: ay.code`[]${mapped.type}`,
+          text: mapped.text === undefined ? undefined : `[]${mapped.text}`,
+          nilable: true,
+        }
+      }
+      if (typekit.record.is(type)) {
+        const value = type.indexer?.value
+        if (!value) {
+          throw new Error('record model is missing its value type')
+        }
+        const mapped = goType(program, value, options)
+        return {
+          type: ay.code`map[string]${mapped.type}`,
+          text:
+            mapped.text === undefined ? undefined : `map[string]${mapped.text}`,
+          nilable: true,
+        }
+      }
+
+      const name = optionalTypeName(program, type)
+      if (name) {
+        const reference = goReferenceTypeName(program, type, name, options.mode)
+        return { type: reference, text: reference, nilable: false }
+      }
+
+      return {
+        type: (
+          <go.StructDeclaration>
+            <ay.List hardline>
+              {goFields(program, type, options).map((field) => (
+                <go.StructMember
+                  name={field.name}
+                  type={field.type}
+                  doc={field.doc}
+                  tag={{
+                    json: `${field.wireName}${field.optional ? ',omitempty' : ''}`,
+                  }}
+                />
+              ))}
+            </ay.List>
+          </go.StructDeclaration>
+        ),
+        nilable: false,
+      }
+    }
+    case 'Intrinsic':
+      if (type.name === 'unknown') {
+        return { type: 'any', text: 'any', nilable: false }
+      }
+      throw new Error(
+        `intrinsic type ${type.name} is not representable in Go; only an explicit unknown maps to any`,
+      )
+    default:
+      throw new Error(`unsupported TypeSpec type kind ${type.kind}`)
+  }
+}
+
+// Named *FieldFilter unions are runtime-backed (see runtime-symbols.ts):
+// GoModels never declares them, so every reference must resolve to one of the
+// static filter types shipped in the runtime templates.
+const runtimeFilterTypesByUnionName = new Map<string, string>([
+  ['StringFieldFilter', 'StringFilter'],
+  ['StringFieldFilterExact', 'StringExactFilter'],
+  ['ULIDFieldFilter', 'StringExactFilter'],
+  ['DateTimeFieldFilter', 'DateTimeFilter'],
+  ['NumericFieldFilter', 'NumericFilter'],
+  ['BooleanFieldFilter', 'BooleanFilter'],
+])
+
+export function runtimeFilterTypeName(name: string): string {
+  const runtime = runtimeFilterTypesByUnionName.get(name)
+  if (runtime) {
+    return runtime
+  }
+
+  // Same suffix classification runtime-symbols.ts uses to skip declaring
+  // these unions; an unmapped one would reference an undeclared Go type.
+  if (name.endsWith('FieldFilter') || name.endsWith('FieldFilterExact')) {
+    throw new Error(
+      `field filter union ${name} has no runtime filter type; map it in runtimeFilterTypesByUnionName and back it with a static runtime filter`,
+    )
+  }
+
+  return name
+}
+
+export function nullableUnionElement(type: Type): Type | undefined {
+  if (type.kind !== 'Union') {
+    return undefined
+  }
+
+  const variants = [...type.variants.values()].map((variant) => variant.type)
+  const hasNull = variants.some(
+    (variant) => variant.kind === 'Intrinsic' && variant.name === 'null',
+  )
+  if (!hasNull) {
+    return undefined
+  }
+
+  const concrete = variants.filter(
+    (variant) => !(variant.kind === 'Intrinsic' && variant.name === 'null'),
+  )
+  return concrete.length === 1 ? concrete[0] : undefined
+}
+
+export function typeName(program: Program, type: Type): string {
+  const name = optionalTypeName(program, type)
+  if (!name) {
+    throw new Error(
+      `anonymous ${type.kind} cannot be emitted as a named Go type`,
+    )
+  }
+
+  return name
+}
+
+export function optionalTypeName(
+  program: Program,
+  type: Type,
+): string | undefined {
+  const synthetic = syntheticTypeNames.get(program)?.get(type)
+  if (synthetic) {
+    return synthetic
+  }
+
+  const name = baseGoTypeName(program, type)
+  if (!name) {
+    return undefined
+  }
+
+  const mapped =
+    resolvedTypeNames.get(program)?.get(name) ??
+    stripOnePrefix(name, stripNamePrefixes.get(program) ?? [])
+
+  switch (mapped) {
+    case 'PagePaginatedMeta':
+      return 'PaginatedMeta'
+    default:
+      return mapped
+  }
+}
+
+function baseGoTypeName(program: Program, type: Type): string | undefined {
+  const friendlyName = getFriendlyName(program, type)
+  const declaredName =
+    'name' in type && typeof type.name === 'string' ? type.name : undefined
+  const name = friendlyName ?? declaredName
+  return name ? goExportedName(name) : undefined
+}
+
+function stripOnePrefix(name: string, prefixes: readonly string[]): string {
+  for (const prefix of prefixes) {
+    if (
+      prefix &&
+      name.length > prefix.length &&
+      name.startsWith(prefix) &&
+      /[A-Z]/.test(name[prefix.length]!)
+    ) {
+      return name.slice(prefix.length)
+    }
+  }
+  return name
+}
+
+function resolveStrippedNames(
+  names: Iterable<string>,
+  prefixes: readonly string[],
+): Map<string, string> {
+  const all = [...names]
+  const resolved = new Map<string, string>()
+
+  if (prefixes.length === 0) {
+    for (const name of all) {
+      resolved.set(name, name)
+    }
+    return resolved
+  }
+
+  const originals = new Set(all)
+  const candidate = new Map<string, string>()
+  for (const name of all) {
+    candidate.set(name, stripOnePrefix(name, prefixes))
+  }
+
+  const candidateCounts = new Map<string, number>()
+  for (const target of candidate.values()) {
+    candidateCounts.set(target, (candidateCounts.get(target) ?? 0) + 1)
+  }
+
+  for (const name of all) {
+    const target = candidate.get(name)!
+    const collides =
+      target !== name &&
+      (originals.has(target) || (candidateCounts.get(target) ?? 0) > 1)
+    resolved.set(name, collides ? name : target)
+  }
+
+  return resolved
+}
+
+export function goExportedName(name: string): string {
+  const initialisms = new Map([
+    ['api', 'API'],
+    ['csv', 'CSV'],
+    ['http', 'HTTP'],
+    ['id', 'ID'],
+    ['json', 'JSON'],
+    ['llm', 'LLM'],
+    ['sql', 'SQL'],
+    ['ulid', 'ULID'],
+    ['url', 'URL'],
+    ['uuid', 'UUID'],
+  ])
+
+  return name
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[\s\-_./]+/)
+    .filter(Boolean)
+    .map((part) => {
+      const initialism = initialisms.get(part.toLowerCase())
+      return (
+        initialism ?? part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
+      )
+    })
+    .join('')
+}
+
+export function queryScalarKind(
+  program: Program,
+  type: Type,
+): GoQueryScalarKind {
+  switch (type.kind) {
+    case 'String':
+      return 'string'
+    case 'Boolean':
+      return 'boolean'
+    case 'Number':
+      return Number.isInteger(type.value) ? 'integer' : 'float'
+    case 'Enum': {
+      const numeric = [...type.members.values()].some(
+        (member) => typeof member.value === 'number',
+      )
+      return numeric ? 'integer' : 'string'
+    }
+    case 'EnumMember':
+      return queryScalarKind(program, type.enum)
+    case 'Union': {
+      const concrete = [...type.variants.values()]
+        .map((variant) => variant.type)
+        .filter((variant) => variant.kind !== 'Intrinsic')
+      if (concrete.length === 0) {
+        throw new Error('query union has no concrete variants')
+      }
+      const kinds = new Set(
+        concrete.map((variant) => queryScalarKind(program, variant)),
+      )
+      if (kinds.size !== 1) {
+        throw new Error(
+          `query union ${optionalTypeName(program, type) ?? '<anonymous>'} mixes incompatible scalar kinds`,
+        )
+      }
+      return [...kinds][0]!
+    }
+    case 'Scalar':
+      return scalarQueryKind(type)
+    default:
+      throw new Error(
+        `unsupported ${type.kind} query scalar ${optionalTypeName(program, type) ?? '<anonymous>'}`,
+      )
+  }
+}
+
+export function queryFilterKind(
+  program: Program,
+  type: Type,
+): GoQueryFilterKind {
+  switch (optionalTypeName(program, type)) {
+    case 'StringFieldFilter':
+      return 'string'
+    case 'StringFieldFilterExact':
+    case 'ULIDFieldFilter':
+      return 'stringExact'
+    case 'DateTimeFieldFilter':
+      return 'dateTime'
+    case 'NumericFieldFilter':
+      return 'numeric'
+    case 'BooleanFieldFilter':
+      return 'boolean'
+    case 'LabelsFieldFilter':
+      return 'labels'
+    default:
+      queryScalarKind(program, type)
+      return 'scalar'
+  }
+}
+
+function scalarType(scalar: Scalar): GoTypeResult {
+  for (
+    let current: Scalar | undefined = scalar;
+    current;
+    current = current.baseScalar
+  ) {
+    switch (current.name) {
+      case 'DateTime':
+      case 'utcDateTime':
+      case 'offsetDateTime':
+        return { type: go.std.time.Time, text: 'time.Time', nilable: false }
+      case 'Numeric':
+        return { type: 'Numeric', text: 'Numeric', nilable: false }
+      case 'boolean':
+        return { type: 'bool', text: 'bool', nilable: false }
+      case 'integer':
+      case 'safeint':
+        // `integer` is arbitrary-precision and `safeint` spans 53 bits on the
+        // wire, so neither fits a narrower sized Go integer by declaration.
+        return { type: 'int64', text: 'int64', nilable: false }
+      case 'int8':
+        return { type: 'int8', text: 'int8', nilable: false }
+      case 'int16':
+        return { type: 'int16', text: 'int16', nilable: false }
+      case 'int32':
+        return { type: 'int32', text: 'int32', nilable: false }
+      case 'int64':
+        return { type: 'int64', text: 'int64', nilable: false }
+      case 'uint8':
+        return { type: 'uint8', text: 'uint8', nilable: false }
+      case 'uint16':
+        return { type: 'uint16', text: 'uint16', nilable: false }
+      case 'uint32':
+        return { type: 'uint32', text: 'uint32', nilable: false }
+      case 'uint64':
+        return { type: 'uint64', text: 'uint64', nilable: false }
+      case 'float':
+      case 'float64':
+        return { type: 'float64', text: 'float64', nilable: false }
+      case 'float32':
+        return { type: 'float32', text: 'float32', nilable: false }
+      case 'decimal':
+      case 'decimal128':
+        return { type: 'Numeric', text: 'Numeric', nilable: false }
+      case 'string':
+        return { type: 'string', text: 'string', nilable: false }
+      default:
+        break
+    }
+  }
+
+  return { type: 'string', text: 'string', nilable: false }
+}
+
+function scalarQueryKind(scalar: Scalar): GoQueryScalarKind {
+  for (
+    let current: Scalar | undefined = scalar;
+    current;
+    current = current.baseScalar
+  ) {
+    switch (current.name) {
+      case 'DateTime':
+      case 'utcDateTime':
+      case 'offsetDateTime':
+        return 'dateTime'
+      case 'boolean':
+        return 'boolean'
+      case 'integer':
+      case 'int8':
+      case 'int16':
+      case 'int32':
+      case 'int64':
+      case 'safeint':
+      case 'uint8':
+      case 'uint16':
+      case 'uint32':
+      case 'uint64':
+        return 'integer'
+      case 'float':
+      case 'float32':
+      case 'float64':
+      case 'decimal':
+      case 'decimal128':
+        return 'float'
+      case 'string':
+      case 'Numeric':
+        return 'string'
+      default:
+        break
+    }
+  }
+
+  return 'string'
+}
+
+export function oneOrManyElement(
+  program: Program,
+  type: Type,
+): Type | undefined {
+  if (type.kind !== 'Union') {
+    return undefined
+  }
+
+  const variants = [...type.variants.values()]
+    .map((variant) => variant.type)
+    .filter((variant) => variant.kind !== 'Intrinsic')
+  if (variants.length !== 2) {
+    return undefined
+  }
+
+  const typekit = $(program)
+  const array = variants.find(
+    (variant): variant is Model =>
+      variant.kind === 'Model' && typekit.array.is(variant),
+  )
+  const single = variants.find((variant) => variant !== array)
+  const element = array?.indexer?.value
+  if (!array || !single || !element) {
+    return undefined
+  }
+
+  return element === single ? single : undefined
+}

api/spec/packages/typespec-go/src/grouping.ts

@@ -0,0 +1,167 @@
+import {
+  getFriendlyName,
+  type Operation,
+  type Program,
+} from '@typespec/compiler'
+import { getOperationId } from '@typespec/openapi'
+
+const NOISE_TOKENS = new Set(['metering'])
+const ACRONYMS = new Map([
+  ['csv', 'CSV'],
+  ['json', 'JSON'],
+])
+const SPLIT_BY_INTERFACE = new Set(['ProductCatalog'])
+
+function lowerFirst(name: string): string {
+  const match = name.match(/^([A-Z]{2,})([A-Z][a-z].*)$/)
+  if (match?.[1] && match[2]) {
+    return match[1].toLowerCase() + match[2]
+  }
+
+  return name.charAt(0).toLowerCase() + name.slice(1)
+}
+
+export function resourceWords(resource: string): string[] {
+  return resource
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .split(/[\s\-_]+/)
+    .filter(Boolean)
+    .map((word) => word.toLowerCase())
+}
+
+function resourceTokens(
+  resource: string,
+  nestPath: string[] = [],
+): Set<string> {
+  const tokens = new Set(NOISE_TOKENS)
+  for (const word of [
+    ...resourceWords(resource),
+    ...nestPath.flatMap(resourceWords),
+  ]) {
+    tokens.add(word)
+    tokens.add(word.endsWith('s') ? word.slice(0, -1) : `${word}s`)
+  }
+
+  return tokens
+}
+
+export function methodNameOf(
+  program: Program,
+  operation: Operation,
+  resource: string,
+  nestPath: string[] = [],
+): string {
+  const operationID =
+    getFriendlyName(program, operation) ??
+    getOperationId(program, operation) ??
+    operation.name
+  const strip = resourceTokens(resource, nestPath)
+  const kept = resourceWords(operationID).filter((part) => !strip.has(part))
+  const parts = kept.length > 0 ? kept : resourceWords(operationID)
+
+  return exportedMethodName(parts)
+}
+
+export function methodNameFromOperationName(operationName: string): string {
+  return exportedMethodName(resourceWords(operationName))
+}
+
+function exportedMethodName(parts: string[]): string {
+  return parts
+    .map(
+      (part) =>
+        ACRONYMS.get(part) ?? part.charAt(0).toUpperCase() + part.slice(1),
+    )
+    .join('')
+}
+
+export function sourceOf(operation: Operation): {
+  chain: string[]
+  interface?: string
+} {
+  const source =
+    operation.interface?.sourceInterfaces?.[0] ??
+    operation.sourceOperation?.interface
+  const chain: string[] = []
+
+  for (
+    let namespace = source?.namespace;
+    namespace?.name;
+    namespace = namespace.namespace
+  ) {
+    chain.unshift(namespace.name)
+  }
+
+  return { chain, interface: source?.name }
+}
+
+export function operationNestPath(
+  operation: Operation,
+  resource: string,
+): string[] {
+  const { chain } = sourceOf(operation)
+  if (SPLIT_BY_INTERFACE.has(chain[0] ?? '') || chain[0] !== resource) {
+    return []
+  }
+
+  return chain.slice(1)
+}
+
+function interfaceResource(interfaceName: string): string {
+  return pluralize(interfaceName.replace(/Operations$/, ''))
+}
+
+export function groupOperations(
+  operations: Operation[],
+): Map<string, Operation[]> {
+  const groups = new Map<string, Operation[]>()
+
+  for (const operation of operations) {
+    const { chain, interface: sourceInterface } = sourceOf(operation)
+    const top = chain[0]
+    if (!top) {
+      const qualifiedName = operation.interface
+        ? `${operation.interface.name}.${operation.name}`
+        : operation.name
+      throw new Error(
+        `typespec-go: cannot place operation ${qualifiedName} in a resource group: its source declaration is not inside a named namespace. Declare it in an interface that extends a resource namespace interface (for example \`interface Endpoints extends Customers.Operations\`) or reference a namespaced operation with \`is\`, so the emitter knows which Go sub-client owns it.`,
+      )
+    }
+
+    const resource =
+      SPLIT_BY_INTERFACE.has(top) && sourceInterface
+        ? interfaceResource(sourceInterface)
+        : top
+    const existing = groups.get(resource)
+    if (existing) {
+      existing.push(operation)
+    } else {
+      groups.set(resource, [operation])
+    }
+  }
+
+  return groups
+}
+
+export function pluralize(word: string): string {
+  if (word.endsWith('s')) {
+    return word
+  }
+  if (/(x|z|ch|sh)$/i.test(word)) {
+    return `${word}es`
+  }
+  if (/[^aeiou]y$/i.test(word)) {
+    return `${word.slice(0, -1)}ies`
+  }
+
+  return `${word}s`
+}
+
+export function namespaceNames(resource: string): {
+  class: string
+  getter: string
+} {
+  const className = resource.charAt(0).toUpperCase() + resource.slice(1)
+  return { class: className, getter: lowerFirst(className) }
+}

api/spec/packages/typespec-go/src/index.ts

@@ -0,0 +1,2 @@
+export { $onEmit } from './emitter.jsx'
+export { $lib } from './lib.js'

api/spec/packages/typespec-go/src/lib.ts

@@ -0,0 +1,102 @@
+import { createTypeSpecLibrary, JSONSchemaType } from '@typespec/compiler'
+
+export interface GoEmitterOptions {
+  /** Go module path of the generated SDK, e.g. github.com/openmeterio/openmeter/sdk/go/openmeter. */
+  'module-path': string
+  /** Go package name for the flat single-package SDK, e.g. "openmeter". */
+  'package-name': string
+  /** Markdown inserted after the README intro, e.g. a GitHub alert callout. */
+  'readme-note'?: string
+  /**
+   * Fallback SDK version used when Go build info is unavailable (the module
+   * itself, replace directives, vendored trees without version data). Module
+   * consumers instead get their resolved module version from
+   * debug.ReadBuildInfo() at runtime, so tagged releases need no stamping
+   * commit. Defaults to the 0.0.0-dev placeholder.
+   */
+  'sdk-version'?: string
+  /**
+   * Service namespace names whose operations are emitted as sub-clients. When
+   * omitted, all services are included. Mirrors the TypeScript emitter's knob.
+   */
+  'include-services'?: string[]
+  /** PascalCase type-name prefixes to strip when doing so is unambiguous. */
+  'strip-name-prefixes'?: string[]
+  /**
+   * Operation-group names to generate. When omitted, every discovered group is
+   * emitted.
+   */
+  'include-resources'?: string[]
+  /**
+   * Minimum Go version stamped into the generated go.mod's `go` directive.
+   * Defaults to 1.23, the generated code's actual floor (the iter package).
+   * Raise it when repo-preserved *_test.go files need newer stdlib APIs; doing
+   * so raises the consumer floor for every SDK user, not just this repo.
+   */
+  'go-version'?: string
+}
+
+const EmitterOptionsSchema: JSONSchemaType<GoEmitterOptions> = {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    'module-path': {
+      type: 'string',
+      description: 'Go module path of the generated SDK.',
+    },
+    'package-name': {
+      type: 'string',
+      description: 'Go package name for the flat single-package SDK.',
+    },
+    'readme-note': {
+      type: 'string',
+      nullable: true,
+      description:
+        'Markdown inserted after the README intro, e.g. a GitHub alert callout.',
+    },
+    'sdk-version': {
+      type: 'string',
+      nullable: true,
+      description:
+        'Fallback SDK version used when Go build info is unavailable (module consumers instead get their resolved module version at runtime). Defaults to 0.0.0-dev.',
+    },
+    'include-services': {
+      type: 'array',
+      items: { type: 'string' },
+      nullable: true,
+      description:
+        'Service namespace names whose operations are emitted as sub-clients. When omitted, all services are included.',
+    },
+    'strip-name-prefixes': {
+      type: 'array',
+      items: { type: 'string' },
+      nullable: true,
+      description:
+        'PascalCase type-name prefixes to strip when doing so is unambiguous.',
+    },
+    'include-resources': {
+      type: 'array',
+      items: { type: 'string' },
+      nullable: true,
+      description:
+        'Operation-group names to generate. Defaults to every discovered group.',
+    },
+    'go-version': {
+      type: 'string',
+      nullable: true,
+      description:
+        "Minimum Go version stamped into the generated go.mod's go directive. Defaults to 1.23, the generated code's actual floor (the iter package). Raise it when repo-preserved *_test.go files need newer stdlib APIs, noting it raises the consumer floor.",
+    },
+  },
+  required: ['module-path', 'package-name'],
+}
+
+export const $lib = createTypeSpecLibrary({
+  name: 'typespec-go',
+  emitter: {
+    options: EmitterOptionsSchema,
+  },
+  diagnostics: {},
+})
+
+export const { reportDiagnostic, createDiagnostic } = $lib

api/spec/packages/typespec-go/src/operations.ts

@@ -0,0 +1,470 @@
+import {
+  getFriendlyName,
+  type Model,
+  type ModelProperty,
+  type Operation,
+  type Program,
+  type Type,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import {
+  getAllHttpServices,
+  type HttpOperationParameter,
+  type HttpOperationQueryParameter,
+  type HttpStatusCodesEntry,
+} from '@typespec/http'
+import '@typespec/http/experimental/typekit'
+import { getOperationId } from '@typespec/openapi'
+import { optionalTypeName } from './go-types.js'
+import { methodNameFromOperationName, methodNameOf } from './grouping.js'
+
+export type GoQueryCodec =
+  | { kind: 'page' }
+  | { kind: 'cursorPage' }
+  | { kind: 'sort' }
+  | { kind: 'deepObject'; model: Model }
+  | { kind: 'array'; explode: boolean }
+  | { kind: 'scalar' }
+
+export interface GoOperation {
+  operation: Operation
+  methodName: string
+  verb: string
+  path: string
+  pathParams: GoParameter[]
+  queryParams: GoParameter[]
+  body?: Type
+  bodyOptional: boolean
+  requestContentType?: string
+  response?: Type
+  responseContentType?: string
+  pagination?: 'page' | 'cursor'
+}
+
+export interface GoParameter {
+  name: string
+  property: ModelProperty
+  type: Type
+  queryCodec?: GoQueryCodec
+}
+
+export function collectHttpOperations(
+  program: Program,
+  includeServices?: string[],
+): Operation[] {
+  const [services] = getAllHttpServices(program)
+  const included =
+    includeServices && includeServices.length > 0
+      ? services.filter((service) =>
+          includeServices.includes(service.namespace.name),
+        )
+      : services
+  const seen = new Set<string>()
+  const operations: Operation[] = []
+
+  for (const service of included) {
+    for (const httpOperation of service.operations) {
+      const operation = httpOperation.operation
+      const identity = operationRepresentationKey(program, operation)
+      if (seen.has(identity)) {
+        continue
+      }
+      seen.add(identity)
+      operations.push(operation)
+    }
+  }
+
+  return operations
+}
+
+export function describeOperations(
+  program: Program,
+  resource: string,
+  operations: Operation[],
+  bodyOverrides: Map<string, Type> = new Map(),
+  nestPath: string[] = [],
+): GoOperation[] {
+  const typekit = $(program)
+
+  const described = operations.map((operation) => {
+    const httpOperation = typekit.httpOperation.get(operation)
+    assertSupportedParameters(
+      operation,
+      httpOperation.parameters.parameters,
+      httpOperation.parameters.body?.contentTypeProperty,
+    )
+    if (
+      httpOperation.parameters.body &&
+      httpOperation.parameters.body.bodyKind !== 'single'
+    ) {
+      throw new Error(
+        `typespec-go: unsupported ${httpOperation.parameters.body.bodyKind} request body on ${operation.name}; add an explicit Go body codec before emitting it`,
+      )
+    }
+    const pathParams = httpOperation.parameters.parameters
+      .filter((parameter) => parameter.type === 'path')
+      .map((parameter) => ({
+        name: parameter.name,
+        property: parameter.param,
+        type: parameter.param.type,
+      }))
+    const queryParams = httpOperation.parameters.parameters
+      .filter((parameter) => parameter.type === 'query')
+      .map((parameter) => ({
+        name: parameter.name,
+        property: parameter.param,
+        type: parameter.param.type,
+        queryCodec: classifyQueryParameter(program, operation, parameter),
+      }))
+    const response = successBody(program, operation, httpOperation.responses)
+    const overrideKey = qualifiedOperationKey(operation)
+    const body =
+      bodyOverrides.get(overrideKey) ?? httpOperation.parameters.body?.type
+    const requestContentType = bodyOverrides.has(overrideKey)
+      ? 'application/json'
+      : preferredContentType(httpOperation.parameters.body?.contentTypes)
+
+    return {
+      operation,
+      methodName: methodNameOf(program, operation, resource, nestPath),
+      verb: httpOperation.verb,
+      path: httpOperation.path,
+      pathParams,
+      queryParams,
+      body,
+      bodyOptional:
+        body !== undefined &&
+        !bodyOverrides.has(overrideKey) &&
+        (httpOperation.parameters.body?.property?.optional ?? false),
+      requestContentType,
+      response:
+        response &&
+        (optionalTypeName(program, response.type)
+          ? response.type
+          : response.envelope),
+      responseContentType: response?.contentType,
+      pagination: paginationKind(queryParams),
+    }
+  })
+
+  return disambiguateMethodNames(described)
+}
+
+export function classifyQueryParameter(
+  program: Program,
+  operation: Operation,
+  parameter: HttpOperationQueryParameter,
+): GoQueryCodec {
+  const typekit = $(program)
+  const type = parameter.param.type
+  if (parameter.name === 'sort') {
+    return { kind: 'sort' }
+  }
+
+  if (type.kind === 'Model') {
+    if (typekit.array.is(type)) {
+      return { kind: 'array', explode: parameter.explode }
+    }
+
+    if (parameter.style === 'deepObject') {
+      // Only a parameter literally named `page` may become a pagination
+      // codec, and its property set must match one pagination shape exactly;
+      // otherwise a coincidentally shaped filter model would be silently
+      // reclassified and lose its remaining properties.
+      if (parameter.name !== 'page') {
+        return { kind: 'deepObject', model: type }
+      }
+
+      const properties = new Set(type.properties.keys())
+      const within = (allowed: readonly string[]) =>
+        [...properties].every((key) => allowed.includes(key))
+      if (
+        (properties.has('after') || properties.has('before')) &&
+        within(['size', 'after', 'before'])
+      ) {
+        return { kind: 'cursorPage' }
+      }
+      if (properties.has('number') && within(['size', 'number'])) {
+        return { kind: 'page' }
+      }
+
+      throw new Error(
+        `typespec-go: query parameter page on ${operation.name} has properties {${[...properties].join(', ')}} matching neither page pagination {size, number} nor cursor pagination {size, after, before}; rename the parameter or align it with a pagination shape before emitting it`,
+      )
+    }
+  }
+
+  return { kind: 'scalar' }
+}
+
+/**
+ * Request body overrides for @sharedRoute siblings.
+ *
+ * TypeSpec exposes the CSV meter query as a response-only sibling of the JSON
+ * query. Both operations share an operation id, so the JSON sibling's request
+ * body is also the request body for the CSV method.
+ *
+ * Shared-route variants that already declare their own body keep that body and
+ * content type. That lets the Go SDK expose explicit media-type-specific
+ * overloads such as CloudEvents single-event, CloudEvents batch, and generic
+ * application/json ingest.
+ *
+ * Siblings are associated by their shared route (declaring container + verb +
+ * path) rather than by operation id or name, so two unrelated operations that
+ * happen to share a name in different namespaces can never donate a body to
+ * each other. The returned map is keyed by qualifiedOperationKey.
+ */
+export function jsonBodyOverrides(program: Program): Map<string, Type> {
+  const typekit = $(program)
+  const [services] = getAllHttpServices(program)
+  const bodylessRoutes = new Map<string, string>()
+  const jsonBodyByRoute = new Map<string, Type>()
+
+  for (const service of services) {
+    for (const httpOperation of service.operations) {
+      const operation = httpOperation.operation
+      const routeKey = [
+        containerPath(operation).join('.'),
+        httpOperation.verb,
+        httpOperation.path,
+      ].join('|')
+      const body = typekit.httpOperation.get(operation).parameters.body
+
+      if (!body?.type) {
+        bodylessRoutes.set(qualifiedOperationKey(operation), routeKey)
+      } else if (body.contentTypes.includes('application/json')) {
+        jsonBodyByRoute.set(routeKey, body.type)
+      }
+    }
+  }
+
+  const overrides = new Map<string, Type>()
+  for (const [operationKey, routeKey] of bodylessRoutes) {
+    const json = jsonBodyByRoute.get(routeKey)
+    if (json) {
+      overrides.set(operationKey, json)
+    }
+  }
+
+  return overrides
+}
+
+function qualifiedOperationKey(operation: Operation): string {
+  return [...containerPath(operation), operation.name].join('.')
+}
+
+function containerPath(operation: Operation): string[] {
+  const path: string[] = []
+  for (
+    let namespace = operation.interface?.namespace ?? operation.namespace;
+    namespace?.name;
+    namespace = namespace.namespace
+  ) {
+    path.unshift(namespace.name)
+  }
+  if (operation.interface) {
+    path.push(operation.interface.name)
+  }
+
+  return path
+}
+
+export function operationBaseName(
+  program: Program,
+  operation: Operation,
+): string {
+  const identity =
+    getFriendlyName(program, operation) ??
+    getOperationId(program, operation) ??
+    operation.name
+
+  return identity
+    .split(/[-_/\s]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+function operationRepresentationKey(
+  program: Program,
+  operation: Operation,
+): string {
+  const httpOperation = $(program).httpOperation.get(operation)
+  const body = httpOperation.parameters.body
+  const response = successBody(program, operation, httpOperation.responses)
+
+  return [
+    operationBaseName(program, operation),
+    httpOperation.verb,
+    httpOperation.path,
+    body?.contentTypes.join(',') ?? '',
+    typeKey(program, body?.type),
+    response?.contentType ?? '',
+    typeKey(program, response?.type),
+  ].join('|')
+}
+
+function typeKey(
+  program: Program,
+  type: Type | undefined,
+  seen = new Set<Type>(),
+): string {
+  if (!type) {
+    return ''
+  }
+
+  const named = optionalTypeName(program, type)
+  if (named) {
+    return `${type.kind}:${named}`
+  }
+
+  if (seen.has(type)) {
+    return type.kind
+  }
+  seen.add(type)
+
+  switch (type.kind) {
+    case 'Model': {
+      const typekit = $(program)
+      if (typekit.array.is(type)) {
+        return `array:${typeKey(program, type.indexer?.value, seen)}`
+      }
+      if (typekit.record.is(type)) {
+        return `record:${typeKey(program, type.indexer?.value, seen)}`
+      }
+      return `model:{${[...type.properties.values()]
+        .map(
+          (property) =>
+            `${property.name}:${typeKey(program, property.type, seen)}`,
+        )
+        .join(',')}}`
+    }
+    case 'Union':
+      return `union:${[...type.variants.values()]
+        .map((variant) => typeKey(program, variant.type, seen))
+        .join('|')}`
+    case 'Tuple':
+      return `tuple:${type.values
+        .map((value) => typeKey(program, value, seen))
+        .join('|')}`
+    default:
+      return `${type.kind}:${'value' in type ? String(type.value) : ''}`
+  }
+}
+
+function disambiguateMethodNames(operations: GoOperation[]): GoOperation[] {
+  const byMethodName = new Map<string, GoOperation[]>()
+  for (const operation of operations) {
+    const group = byMethodName.get(operation.methodName)
+    if (group) {
+      group.push(operation)
+    } else {
+      byMethodName.set(operation.methodName, [operation])
+    }
+  }
+
+  for (const group of byMethodName.values()) {
+    if (group.length < 2) {
+      continue
+    }
+
+    for (const operation of group) {
+      operation.methodName = methodNameFromOperationName(
+        operation.operation.name,
+      )
+    }
+  }
+
+  return operations
+}
+
+function assertSupportedParameters(
+  operation: Operation,
+  parameters: HttpOperationParameter[],
+  contentTypeProperty: ModelProperty | undefined,
+): void {
+  for (const parameter of parameters) {
+    if (parameter.type === 'path' || parameter.type === 'query') {
+      continue
+    }
+    if (
+      parameter.type === 'header' &&
+      contentTypeProperty &&
+      parameter.param === contentTypeProperty
+    ) {
+      continue
+    }
+
+    throw new Error(
+      `typespec-go: unsupported ${parameter.type} parameter ${parameter.name} on ${operation.name}; add an explicit Go ${parameter.type} codec before emitting it`,
+    )
+  }
+}
+
+function is2xx(status: HttpStatusCodesEntry): boolean {
+  return (
+    status === '*' ||
+    (typeof status === 'number' && status >= 200 && status < 300) ||
+    (typeof status === 'object' && status.start >= 200 && status.start < 300)
+  )
+}
+
+function successBody(
+  program: Program,
+  operation: Operation,
+  responses: ReturnType<
+    ReturnType<typeof $>['httpOperation']['get']
+  >['responses'],
+): { type: Type; envelope: Type; contentType?: string } | undefined {
+  let found: { type: Type; envelope: Type; contentType?: string } | undefined
+  let foundKey: string | undefined
+
+  for (const response of responses) {
+    if (!is2xx(response.statusCodes)) {
+      continue
+    }
+    for (const content of response.responses) {
+      if (!content.body?.type) {
+        continue
+      }
+      if (found === undefined) {
+        found = {
+          type: content.body.type,
+          envelope: response.type,
+          contentType: content.body.contentTypes[0],
+        }
+        foundKey = typeKey(program, content.body.type)
+      } else if (foundKey !== typeKey(program, content.body.type)) {
+        const describe = (type: Type) =>
+          optionalTypeName(program, type) ?? type.kind
+        throw new Error(
+          `typespec-go: operation ${operation.name} declares multiple 2xx response bodies with different types (${describe(found.type)} vs ${describe(content.body.type)}); split the variants into @sharedRoute siblings or align the response models before emitting it`,
+        )
+      }
+    }
+  }
+
+  return found
+}
+
+function preferredContentType(
+  contentTypes: readonly string[] | undefined,
+): string | undefined {
+  return (
+    contentTypes?.find((contentType) => contentType === 'application/json') ??
+    contentTypes?.[0]
+  )
+}
+
+function paginationKind(queryParams: GoParameter[]): GoOperation['pagination'] {
+  for (const parameter of queryParams) {
+    if (parameter.queryCodec?.kind === 'page') {
+      return 'page'
+    }
+    if (parameter.queryCodec?.kind === 'cursorPage') {
+      return 'cursor'
+    }
+  }
+
+  return undefined
+}

api/spec/packages/typespec-go/src/projections.ts

@@ -0,0 +1,1039 @@
+import {
+  resolveEncodedName,
+  walkPropertiesInherited,
+  type Model,
+  type Operation,
+  type Program,
+  type Type,
+  type Union,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { isHeader, isStatusCode, isVisible, Visibility } from '@typespec/http'
+import {
+  goExportedName,
+  goType,
+  inputVariantName,
+  nullableUnionElement,
+  oneOrManyElement,
+  optionalTypeName,
+  runtimeFilterTypeName,
+  type GoDeclarationPlan,
+  type GoPayloadMode,
+} from './go-types.js'
+import { isStringLike } from './components/GoModels.js'
+import {
+  discriminatorLiteral,
+  discriminatorProperty,
+  variantAccessorName,
+} from './components/GoUnion.js'
+import { isRuntimeBackedTypeName } from './runtime-symbols.js'
+import { describeOperations } from './operations.js'
+
+export interface GoReachability {
+  /** Types reachable from response bodies, path params, and query params. */
+  readReachable: Set<Type>
+  /** Types reachable from request bodies. */
+  inputReachable: Set<Type>
+  /** Every type each resource touches, for output file grouping. */
+  byResource: Map<string, Set<Type>>
+}
+
+/**
+ * Walks every operation's payloads into read-side and input-side type sets.
+ *
+ * The read walk skips properties not visible in Lifecycle.Read: the server
+ * never returns them, so their types must not be dragged into read models.
+ * The input walk keeps every property because request trees are already
+ * visibility-projected by the spec (Create/Update request templates).
+ */
+export function computeReachability(
+  program: Program,
+  groups: Iterable<readonly [string, Operation[]]>,
+  bodyOverrides: Map<string, Type>,
+): GoReachability {
+  const readReachable = new Set<Type>()
+  const inputReachable = new Set<Type>()
+  const byResource = new Map<string, Set<Type>>()
+
+  const makeWalker = (
+    resourceTypes: Set<Type>,
+    target: Set<Type>,
+    filterRead: boolean,
+  ) => {
+    // Each direction keeps its own visited set: a type reachable from both a
+    // request body and a response must land in both classification sets, not
+    // just whichever walk happened to run first.
+    const visited = new Set<Type>()
+    const visit = (type: Type | undefined): void => {
+      if (!type || visited.has(type)) {
+        return
+      }
+      visited.add(type)
+      resourceTypes.add(type)
+      target.add(type)
+
+      switch (type.kind) {
+        case 'Model':
+          if (type.baseModel) {
+            visit(type.baseModel)
+          }
+          if (type.indexer) {
+            visit(type.indexer.value)
+          }
+          for (const property of type.properties.values()) {
+            if (filterRead && !isVisible(program, property, Visibility.Read)) {
+              continue
+            }
+            visit(property.type)
+          }
+          break
+        case 'Union':
+          // Runtime-backed filter unions render as static runtime types
+          // (StringFilter, DateTimeFilter, ...); walking their variants would
+          // promote their anonymous object variants into dead declarations.
+          if (type.name && isRuntimeBackedTypeName(type.name, type.kind)) {
+            break
+          }
+          for (const variant of type.variants.values()) {
+            visit(variant.type)
+          }
+          break
+        case 'Tuple':
+          for (const value of type.values) {
+            visit(value)
+          }
+          break
+        case 'EnumMember':
+          visit(type.enum)
+          break
+        default:
+          break
+      }
+    }
+    return visit
+  }
+
+  for (const [resource, operations] of groups) {
+    const resourceTypes = new Set<Type>()
+    byResource.set(resource, resourceTypes)
+    const visitRead = makeWalker(resourceTypes, readReachable, true)
+    const visitInput = makeWalker(resourceTypes, inputReachable, false)
+
+    for (const operation of describeOperations(
+      program,
+      resource,
+      operations,
+      bodyOverrides,
+    )) {
+      for (const parameter of operation.pathParams) {
+        visitRead(parameter.type)
+      }
+      for (const parameter of operation.queryParams) {
+        if (parameter.name === 'filter' && parameter.type.kind === 'Model') {
+          // Deep-object filter models are rendered as query params structs by
+          // GoResource, not as JSON models; only their field types are models.
+          for (const property of parameter.type.properties.values()) {
+            visitRead(property.type)
+          }
+        } else {
+          visitRead(parameter.type)
+        }
+      }
+      visitRead(operation.response)
+      visitInput(operation.body)
+    }
+  }
+
+  return { readReachable, inputReachable, byResource }
+}
+
+/**
+ * Types whose input projection renders differently from their read projection,
+ * limited to types reachable from both directions (only those emit twice).
+ *
+ * Divergence causes: a defaulted property (optional in input), an optional
+ * collection (pointered in input so an explicitly empty collection survives
+ * omitempty), a property not visible in Lifecycle.Read (dropped from the read
+ * projection), or a reference to another divergent both-reachable type.
+ */
+export function computeDivergentTypes(
+  program: Program,
+  readReachable: Set<Type>,
+  inputReachable: Set<Type>,
+): Set<Type> {
+  const typekit = $(program)
+  const divergent = new Set<Type>()
+  const memo = new Map<Type, boolean>()
+  const visiting = new Set<Type>()
+  const both = (type: Type): boolean =>
+    readReachable.has(type) && inputReachable.has(type)
+
+  const isCollection = (type: Type): boolean =>
+    type.kind === 'Model' && (typekit.array.is(type) || typekit.record.is(type))
+
+  // Whether a field or variant referencing this type renders a different Go
+  // type name in input context than in read context.
+  const referenceDiverges = (type: Type): boolean => {
+    switch (type.kind) {
+      case 'Model':
+        if (typekit.array.is(type) || typekit.record.is(type)) {
+          return type.indexer ? referenceDiverges(type.indexer.value) : false
+        }
+        return both(type) && diverges(type)
+      case 'Union':
+        if (optionalTypeName(program, type)) {
+          return both(type) && diverges(type)
+        }
+        return [...type.variants.values()].some((variant) =>
+          referenceDiverges(variant.type),
+        )
+      case 'Tuple':
+        return type.values.some(referenceDiverges)
+      default:
+        return false
+    }
+  }
+
+  const diverges = (type: Model | Union): boolean => {
+    const cached = memo.get(type)
+    if (cached !== undefined) {
+      return cached
+    }
+    if (visiting.has(type)) {
+      return false
+    }
+    visiting.add(type)
+
+    let result = false
+    if (type.kind === 'Model') {
+      for (const property of walkPropertiesInherited(type)) {
+        if (isHeader(program, property) || isStatusCode(program, property)) {
+          continue
+        }
+        if (
+          !isVisible(program, property, Visibility.Read) ||
+          // A default only changes the input rendering when the property is
+          // required: fieldShape keeps an already-optional property optional
+          // in both modes, so the projections stay byte-identical.
+          (property.defaultValue !== undefined && !property.optional) ||
+          (property.optional && isCollection(property.type)) ||
+          referenceDiverges(property.type)
+        ) {
+          result = true
+          break
+        }
+      }
+      if (!result && type.indexer) {
+        result = referenceDiverges(type.indexer.value)
+      }
+    } else {
+      result = [...type.variants.values()].some((variant) =>
+        referenceDiverges(variant.type),
+      )
+    }
+
+    visiting.delete(type)
+    memo.set(type, result)
+    if (result) {
+      divergent.add(type)
+    }
+    return result
+  }
+
+  for (const type of readReachable) {
+    if (
+      (type.kind === 'Model' || type.kind === 'Union') &&
+      inputReachable.has(type)
+    ) {
+      diverges(type)
+    }
+  }
+
+  // Only both-reachable types emit two projections; drop incidental members.
+  for (const type of [...divergent]) {
+    if (!both(type)) {
+      divergent.delete(type)
+    }
+  }
+
+  return divergent
+}
+
+/**
+ * Assigns deterministic Go type names to anonymous models reachable from the
+ * public surface, derived from the enclosing type plus the field (for example
+ * SubscriptionCreate.customer becomes SubscriptionCreateCustomer). Without
+ * promotion a required anonymous struct field cannot be populated in a
+ * composite literal without redeclaring the whole anonymous type.
+ */
+export function promoteAnonymousModels(
+  program: Program,
+  types: Set<Type>,
+): Map<Type, string> {
+  const typekit = $(program)
+  const promoted = new Map<Type, string>()
+  const taken = new Map<string, Type>()
+  for (const type of types) {
+    const name = optionalTypeName(program, type)
+    if (name) {
+      taken.set(name, type)
+    }
+  }
+
+  const isAnonymousStruct = (type: Type): type is Model =>
+    type.kind === 'Model' &&
+    !typekit.array.is(type) &&
+    !typekit.record.is(type) &&
+    optionalTypeName(program, type) === undefined &&
+    promoted.get(type) === undefined
+
+  const claim = (type: Model, name: string): void => {
+    const existing = taken.get(name)
+    if (existing && existing !== type) {
+      throw new Error(
+        `typespec-go: promoted anonymous model name ${name} collides with an existing ${existing.kind}; add a @friendlyName to disambiguate`,
+      )
+    }
+    promoted.set(type, name)
+    taken.set(name, type)
+    visitModel(type, name)
+  }
+
+  const visitFieldType = (type: Type, parentName: string, field: string) => {
+    switch (type.kind) {
+      case 'Model':
+        if (typekit.array.is(type) || typekit.record.is(type)) {
+          if (type.indexer) {
+            visitFieldType(type.indexer.value, parentName, field)
+          }
+          return
+        }
+        if (isAnonymousStruct(type)) {
+          claim(type, `${parentName}${goExportedName(field)}`)
+        }
+        return
+      case 'Union':
+        for (const variant of type.variants.values()) {
+          visitFieldType(variant.type, parentName, field)
+        }
+        return
+      case 'Tuple':
+        for (const value of type.values) {
+          visitFieldType(value, parentName, field)
+        }
+        return
+      default:
+        return
+    }
+  }
+
+  const visitModel = (model: Model, name: string): void => {
+    for (const property of walkPropertiesInherited(model)) {
+      if (isHeader(program, property) || isStatusCode(program, property)) {
+        continue
+      }
+      visitFieldType(property.type, name, property.name)
+    }
+    if (model.indexer) {
+      visitFieldType(model.indexer.value, name, 'Item')
+    }
+  }
+
+  const named = [...types]
+    .flatMap((type) => {
+      if (type.kind !== 'Model' && type.kind !== 'Union') {
+        return []
+      }
+      if (
+        type.kind === 'Model' &&
+        (typekit.array.is(type) || typekit.record.is(type))
+      ) {
+        return []
+      }
+      const name = optionalTypeName(program, type)
+      return name ? [{ name, type }] : []
+    })
+    .sort((left, right) =>
+      left.name < right.name ? -1 : left.name > right.name ? 1 : 0,
+    )
+
+  for (const { name, type } of named) {
+    if (type.kind === 'Model') {
+      visitModel(type, name)
+    } else {
+      for (const variant of type.variants.values()) {
+        const field =
+          typeof variant.name === 'symbol'
+            ? String(variant.name.description ?? 'Variant')
+            : variant.name
+        visitFieldType(variant.type, name, field)
+      }
+    }
+  }
+
+  return promoted
+}
+
+/**
+ * Which projections each reachable type emits, and under what names.
+ *
+ * A type reachable only from requests emits only its input projection under
+ * the natural name; only from responses, only the read projection. A type
+ * reachable from both emits one declaration when the projections agree, and a
+ * read declaration plus a NameInput declaration when they diverge.
+ */
+export function planDeclarations(
+  program: Program,
+  types: Set<Type>,
+  readReachable: Set<Type>,
+  inputReachable: Set<Type>,
+  divergent: Set<Type>,
+): Map<Type, GoDeclarationPlan[]> {
+  const typekit = $(program)
+  const plan = new Map<Type, GoDeclarationPlan[]>()
+
+  for (const type of types) {
+    if (type.kind !== 'Model' && type.kind !== 'Union') {
+      continue
+    }
+    if (
+      type.kind === 'Model' &&
+      (typekit.array.is(type) || typekit.record.is(type))
+    ) {
+      continue
+    }
+    const name = optionalTypeName(program, type)
+    if (!name || isRuntimeBackedTypeName(name, type.kind)) {
+      continue
+    }
+
+    const needsRead = readReachable.has(type)
+    const needsInput = inputReachable.has(type)
+    if (needsInput && !needsRead) {
+      plan.set(type, [{ name, mode: 'input' }])
+    } else if (needsRead && needsInput && divergent.has(type)) {
+      plan.set(type, [
+        { name, mode: 'read' },
+        { name: inputVariantName(name), mode: 'input' },
+      ])
+    } else {
+      plan.set(type, [{ name, mode: 'read' }])
+    }
+  }
+
+  return plan
+}
+
+const PROJECTION_PREFIXES = ['Create', 'Update', 'Upsert'] as const
+
+interface PlannedDeclaration {
+  type: Type
+  declaration: GoDeclarationPlan
+}
+
+/**
+ * Collapses visibility-projection twins onto their canonical types.
+ *
+ * The spec's Create/Update request templates copy every nested model (and
+ * union) into a prefixed twin even when visibility filtering removes nothing,
+ * leaving byte-identical duplicates such as UpdateAddress next to Address.
+ * A declaration whose name is Create/Update/Upsert + the name of another
+ * emitted declaration (matched by emitted Go name, or by the source's declared
+ * TypeSpec name when the canonical emits under a @friendlyName), and whose
+ * rendered shape is identical, is dropped with every reference redirected to
+ * the canonical name — so read-modify-write flows need no type mapping.
+ *
+ * Matching is a recursive structural comparison rather than flat text
+ * equality: when two field references differ only because the candidate side
+ * points at another prefixed twin of the target side's type (UpdateRateCard-
+ * TaxConfig.code is UpdateResourceReference where RateCardTaxConfig.code is
+ * TaxCodeReference), that reference pair is matched recursively and committed
+ * as an additional alias when the enclosing declarations match. The outer
+ * loop runs to a fixpoint because twins reference other twins.
+ *
+ * Returns aliases keyed by the dropped declaration name; the corresponding
+ * plan entries are removed in place.
+ */
+export function computeStructuralAliases(
+  program: Program,
+  plan: Map<Type, GoDeclarationPlan[]>,
+  readReachable: Set<Type>,
+  divergent: Set<Type>,
+): Map<string, string> {
+  const typekit = $(program)
+  const aliases = new Map<string, string>()
+
+  const declarationsByName = new Map<string, PlannedDeclaration>()
+  for (const [type, declarations] of plan) {
+    for (const declaration of declarations) {
+      declarationsByName.set(declaration.name, { type, declaration })
+    }
+  }
+
+  // FilterVisibility twins are named from the source's declared TypeSpec name,
+  // while the canonical type may emit under a @friendlyName (CreateCurrencyCode
+  // vs BillingCurrencyCode); index declared names so those still resolve. An
+  // ambiguous declared name (every ResourceReference<T> instantiation declares
+  // "ResourceReference") yields no top-level target, but such twins still
+  // collapse as reference pairs inside an enclosing declaration match, where
+  // the target instantiation is known from context.
+  const byDeclaredName = new Map<string, PlannedDeclaration | 'ambiguous'>()
+  for (const [type, declarations] of plan) {
+    const declared =
+      'name' in type && typeof type.name === 'string' ? type.name : undefined
+    if (!declared) {
+      continue
+    }
+    const natural = declarations.find(
+      (declaration) => declaration.name === optionalTypeName(program, type),
+    )
+    if (!natural) {
+      continue
+    }
+    byDeclaredName.set(
+      declared,
+      byDeclaredName.has(declared)
+        ? 'ambiguous'
+        : { type, declaration: natural },
+    )
+  }
+
+  const resolveThrough = (
+    name: string,
+    pending: Map<string, string>,
+  ): string => {
+    let final = name
+    for (
+      let next = aliases.get(final) ?? pending.get(final);
+      next !== undefined;
+      next = aliases.get(final) ?? pending.get(final)
+    ) {
+      final = next
+    }
+    return final
+  }
+
+  const referenceName = (
+    type: Type,
+    mode: GoPayloadMode,
+    pending: Map<string, string>,
+  ): string | undefined => {
+    const name = optionalTypeName(program, type)
+    if (!name) {
+      return undefined
+    }
+    const runtime = type.kind === 'Union' ? runtimeFilterTypeName(name) : name
+    if (runtime !== name) {
+      return runtime
+    }
+    const base =
+      mode === 'input' && divergent.has(type) ? inputVariantName(name) : name
+    return resolveThrough(base, pending)
+  }
+
+  const projectionPrefixRest = (name: string): string | undefined => {
+    for (const prefix of PROJECTION_PREFIXES) {
+      if (
+        name.startsWith(prefix) &&
+        name.length > prefix.length &&
+        /[A-Z]/.test(name[prefix.length]!)
+      ) {
+        return name.slice(prefix.length)
+      }
+    }
+    return undefined
+  }
+
+  const scalarText = (type: Type): string | undefined => {
+    try {
+      return goType(program, type).text
+    } catch {
+      return undefined
+    }
+  }
+
+  // Whether referencing `left` in `leftMode` renders the same Go type
+  // expression as referencing `right` in `rightMode`, growing `pending` with
+  // the reference-pair aliases the match depends on.
+  const typesMatch = (
+    left: Type,
+    leftMode: GoPayloadMode,
+    right: Type,
+    rightMode: GoPayloadMode,
+    pending: Map<string, string>,
+    inProgress: Set<string>,
+  ): boolean => {
+    if (left.kind === 'Model' || right.kind === 'Model') {
+      if (left.kind !== 'Model' || right.kind !== 'Model') {
+        return false
+      }
+      const leftArray = typekit.array.is(left)
+      const rightArray = typekit.array.is(right)
+      const leftRecord = typekit.record.is(left)
+      const rightRecord = typekit.record.is(right)
+      if (leftArray !== rightArray || leftRecord !== rightRecord) {
+        return false
+      }
+      if (leftArray || leftRecord) {
+        return (
+          left.indexer !== undefined &&
+          right.indexer !== undefined &&
+          typesMatch(
+            left.indexer.value,
+            leftMode,
+            right.indexer.value,
+            rightMode,
+            pending,
+            inProgress,
+          )
+        )
+      }
+      return namedReferencesMatch(
+        left,
+        leftMode,
+        right,
+        rightMode,
+        pending,
+        inProgress,
+      )
+    }
+
+    if (left.kind === 'Union' || right.kind === 'Union') {
+      if (left.kind !== 'Union' || right.kind !== 'Union') {
+        return false
+      }
+      const leftNullable = nullableUnionElement(left)
+      const rightNullable = nullableUnionElement(right)
+      if ((leftNullable === undefined) !== (rightNullable === undefined)) {
+        return false
+      }
+      if (leftNullable && rightNullable) {
+        return typesMatch(
+          leftNullable,
+          leftMode,
+          rightNullable,
+          rightMode,
+          pending,
+          inProgress,
+        )
+      }
+      const leftOneOrMany = oneOrManyElement(program, left)
+      const rightOneOrMany = oneOrManyElement(program, right)
+      if ((leftOneOrMany === undefined) !== (rightOneOrMany === undefined)) {
+        return false
+      }
+      if (leftOneOrMany && rightOneOrMany) {
+        return typesMatch(
+          leftOneOrMany,
+          leftMode,
+          rightOneOrMany,
+          rightMode,
+          pending,
+          inProgress,
+        )
+      }
+      const leftNamed = optionalTypeName(program, left) !== undefined
+      const rightNamed = optionalTypeName(program, right) !== undefined
+      if (leftNamed && rightNamed) {
+        return namedReferencesMatch(
+          left,
+          leftMode,
+          right,
+          rightMode,
+          pending,
+          inProgress,
+        )
+      }
+      if (leftNamed || rightNamed) {
+        return false
+      }
+      // Anonymous unions render through goType's fallbacks; both sides must
+      // reduce to the same plain text (single concrete variant or string set).
+      const leftText = scalarText(left)
+      return leftText !== undefined && leftText === scalarText(right)
+    }
+
+    const leftText = scalarText(left)
+    return leftText !== undefined && leftText === scalarText(right)
+  }
+
+  const namedReferencesMatch = (
+    left: Type,
+    leftMode: GoPayloadMode,
+    right: Type,
+    rightMode: GoPayloadMode,
+    pending: Map<string, string>,
+    inProgress: Set<string>,
+  ): boolean => {
+    const leftName = referenceName(left, leftMode, pending)
+    const rightName = referenceName(right, rightMode, pending)
+    if (leftName === undefined || rightName === undefined) {
+      return false
+    }
+    if (leftName === rightName) {
+      return true
+    }
+
+    // Prefix tolerance: the candidate side may reference its own prefixed
+    // twin of the type the target side references.
+    const rest = projectionPrefixRest(leftName)
+    if (rest === undefined) {
+      return false
+    }
+    const rightDeclared =
+      'name' in right && typeof right.name === 'string' ? right.name : undefined
+    if (rest !== rightName && rest !== rightDeclared) {
+      return false
+    }
+    const leftDeclaration = plan
+      .get(left)
+      ?.find((declaration) => declaration.name === leftName)
+    const rightDeclaration = plan
+      .get(right)
+      ?.find((declaration) => declaration.name === rightName)
+    if (!leftDeclaration || !rightDeclaration) {
+      return false
+    }
+    const key = `${leftName}->${rightName}`
+    if (inProgress.has(key)) {
+      return true
+    }
+    inProgress.add(key)
+    const matched = declarationsMatch(
+      left,
+      leftDeclaration.mode,
+      right,
+      rightDeclaration.mode,
+      pending,
+      inProgress,
+    )
+    inProgress.delete(key)
+    if (matched) {
+      pending.set(leftName, rightName)
+    }
+    return matched
+  }
+
+  const filteredProperties = (type: Model, mode: GoPayloadMode) =>
+    [...walkPropertiesInherited(type)].filter(
+      (property) =>
+        !isHeader(program, property) &&
+        !isStatusCode(program, property) &&
+        (mode === 'input' ||
+          !readReachable.has(type) ||
+          isVisible(program, property, Visibility.Read)),
+    )
+
+  const fieldShape = (
+    type: Model,
+    property: typeof type.properties extends Map<string, infer P> ? P : never,
+    mode: GoPayloadMode,
+  ) => {
+    const options = { mode: mode === 'input' ? ('input' as const) : undefined }
+    const mapped = goType(program, property.type, options)
+    const optional =
+      property.optional ||
+      (mode === 'input' && property.defaultValue !== undefined)
+    const pointerOptional =
+      optional && !mapped.jsonNullable && (!mapped.nilable || mode === 'input')
+    return {
+      name: goExportedName(property.name),
+      wireName: resolveEncodedName(program, property, 'application/json'),
+      optional,
+      pointerOptional,
+    }
+  }
+
+  // Whether the two planned declarations render identical Go code up to the
+  // declared type name, mirroring the GoModels render strategies.
+  const declarationsMatch = (
+    left: Type,
+    leftMode: GoPayloadMode,
+    right: Type,
+    rightMode: GoPayloadMode,
+    pending: Map<string, string>,
+    inProgress: Set<string>,
+  ): boolean => {
+    if (left.kind === 'Model' && right.kind === 'Model') {
+      const leftProperties = filteredProperties(left, leftMode)
+      const rightProperties = filteredProperties(right, rightMode)
+      if (leftProperties.length !== rightProperties.length) {
+        return false
+      }
+      for (let index = 0; index < leftProperties.length; index++) {
+        const leftProperty = leftProperties[index]!
+        const rightProperty = rightProperties[index]!
+        let leftShape
+        let rightShape
+        try {
+          leftShape = fieldShape(left, leftProperty, leftMode)
+          rightShape = fieldShape(right, rightProperty, rightMode)
+        } catch {
+          return false
+        }
+        if (
+          leftShape.name !== rightShape.name ||
+          leftShape.wireName !== rightShape.wireName ||
+          leftShape.optional !== rightShape.optional ||
+          leftShape.pointerOptional !== rightShape.pointerOptional ||
+          !typesMatch(
+            leftProperty.type,
+            leftMode,
+            rightProperty.type,
+            rightMode,
+            pending,
+            inProgress,
+          )
+        ) {
+          return false
+        }
+      }
+      return true
+    }
+
+    if (left.kind === 'Union' && right.kind === 'Union') {
+      return unionDeclarationsMatch(
+        left,
+        leftMode,
+        right,
+        rightMode,
+        pending,
+        inProgress,
+      )
+    }
+
+    return false
+  }
+
+  const unionRenderStrategy = (
+    union: Union,
+  ): 'nullable' | 'strenum' | 'stringlike' | 'tagged' | 'alias' | 'invalid' => {
+    if (nullableUnionElement(union)) {
+      return 'nullable'
+    }
+    const variants = [...union.variants.values()]
+    if (
+      variants.length > 0 &&
+      variants.every((variant) => variant.type.kind === 'String')
+    ) {
+      return 'strenum'
+    }
+    if (
+      variants.length > 0 &&
+      variants.every((variant) => isStringLike(program, variant.type))
+    ) {
+      return 'stringlike'
+    }
+    if (
+      variants.length > 0 &&
+      variants.every((variant) => variant.type.kind === 'Model')
+    ) {
+      return 'tagged'
+    }
+    const concrete = variants.filter(
+      (variant) => variant.type.kind !== 'Intrinsic',
+    )
+    if (concrete.length === 1) {
+      return 'alias'
+    }
+    return concrete.length > 1 ? 'tagged' : 'invalid'
+  }
+
+  const unionDeclarationsMatch = (
+    left: Union,
+    leftMode: GoPayloadMode,
+    right: Union,
+    rightMode: GoPayloadMode,
+    pending: Map<string, string>,
+    inProgress: Set<string>,
+  ): boolean => {
+    const strategy = unionRenderStrategy(left)
+    if (strategy !== unionRenderStrategy(right) || strategy === 'invalid') {
+      return false
+    }
+
+    const leftVariants = [...left.variants.values()]
+    const rightVariants = [...right.variants.values()]
+
+    switch (strategy) {
+      case 'nullable':
+        return typesMatch(
+          nullableUnionElement(left)!,
+          leftMode,
+          nullableUnionElement(right)!,
+          rightMode,
+          pending,
+          inProgress,
+        )
+      case 'strenum': {
+        if (leftVariants.length !== rightVariants.length) {
+          return false
+        }
+        return leftVariants.every((variant, index) => {
+          const other = rightVariants[index]!
+          return (
+            variant.type.kind === 'String' &&
+            other.type.kind === 'String' &&
+            goExportedName(String(variant.name)) ===
+              goExportedName(String(other.name)) &&
+            variant.type.value === other.type.value
+          )
+        })
+      }
+      case 'stringlike':
+        return true
+      case 'alias': {
+        const leftConcrete = leftVariants.filter(
+          (variant) => variant.type.kind !== 'Intrinsic',
+        )[0]!
+        const rightConcrete = rightVariants.filter(
+          (variant) => variant.type.kind !== 'Intrinsic',
+        )[0]!
+        return typesMatch(
+          leftConcrete.type,
+          leftMode,
+          rightConcrete.type,
+          rightMode,
+          pending,
+          inProgress,
+        )
+      }
+      case 'tagged': {
+        const leftConcrete = leftVariants.filter(
+          (variant) => variant.type.kind !== 'Intrinsic',
+        )
+        const rightConcrete = rightVariants.filter(
+          (variant) => variant.type.kind !== 'Intrinsic',
+        )
+        if (leftConcrete.length !== rightConcrete.length) {
+          return false
+        }
+        const leftDiscriminator = discriminatorProperty(
+          program,
+          left,
+          leftConcrete.flatMap((variant) =>
+            variant.type.kind === 'Model' ? [variant.type] : [],
+          ),
+        )
+        const rightDiscriminator = discriminatorProperty(
+          program,
+          right,
+          rightConcrete.flatMap((variant) =>
+            variant.type.kind === 'Model' ? [variant.type] : [],
+          ),
+        )
+        if (leftDiscriminator?.wireName !== rightDiscriminator?.wireName) {
+          return false
+        }
+        return leftConcrete.every((variant, index) => {
+          const other = rightConcrete[index]!
+          if (variant.type.kind !== other.type.kind) {
+            return false
+          }
+          if (variant.type.kind === 'Model' && other.type.kind === 'Model') {
+            if (
+              discriminatorLiteral(variant.type, leftDiscriminator) !==
+              discriminatorLiteral(other.type, rightDiscriminator)
+            ) {
+              return false
+            }
+          } else if (
+            variantAccessorName(program, '', variant) !==
+            variantAccessorName(program, '', other)
+          ) {
+            return false
+          }
+          return typesMatch(
+            variant.type,
+            leftMode,
+            other.type,
+            rightMode,
+            pending,
+            inProgress,
+          )
+        })
+      }
+    }
+  }
+
+  const sortedEntries = (): PlannedDeclaration[] =>
+    [...plan]
+      .flatMap(([type, declarations]) =>
+        declarations.map((declaration) => ({ type, declaration })),
+      )
+      .sort((leftEntry, rightEntry) =>
+        leftEntry.declaration.name < rightEntry.declaration.name
+          ? -1
+          : leftEntry.declaration.name > rightEntry.declaration.name
+            ? 1
+            : 0,
+      )
+
+  for (let changed = true; changed; ) {
+    changed = false
+    for (const { type, declaration } of sortedEntries()) {
+      if (aliases.has(declaration.name)) {
+        continue
+      }
+      const rest = projectionPrefixRest(declaration.name)
+      if (rest === undefined) {
+        continue
+      }
+      const declaredMatch = byDeclaredName.get(rest)
+      const target =
+        declarationsByName.get(resolveThrough(rest, new Map())) ??
+        (declaredMatch === 'ambiguous' ? undefined : declaredMatch)
+      if (!target || target.type === type) {
+        continue
+      }
+      const targetName = resolveThrough(target.declaration.name, new Map())
+      if (aliases.has(target.declaration.name)) {
+        // The canonical itself collapsed; follow it to its final home.
+        const followed = declarationsByName.get(targetName)
+        if (!followed || followed.type === type) {
+          continue
+        }
+      }
+
+      const pending = new Map<string, string>()
+      if (
+        declarationsMatch(
+          type,
+          declaration.mode,
+          target.type,
+          target.declaration.mode,
+          pending,
+          new Set([`${declaration.name}->${targetName}`]),
+        )
+      ) {
+        aliases.set(declaration.name, targetName)
+        for (const [from, to] of pending) {
+          if (!aliases.has(from)) {
+            aliases.set(from, to)
+          }
+        }
+        changed = true
+      }
+    }
+  }
+
+  // Flatten chains and drop the collapsed declarations from the plan.
+  for (const [name] of aliases) {
+    aliases.set(name, resolveThrough(name, new Map()))
+  }
+  for (const [type, declarations] of plan) {
+    const kept = declarations.filter(
+      (declaration) => !aliases.has(declaration.name),
+    )
+    if (kept.length === declarations.length) {
+      continue
+    }
+    if (kept.length === 0) {
+      plan.delete(type)
+    } else {
+      plan.set(type, kept)
+    }
+  }
+
+  return aliases
+}

api/spec/packages/typespec-go/src/readme.ts

@@ -0,0 +1,371 @@
+import type { Operation, Program, Type } from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { goExportedName } from './go-types.js'
+import { namespaceNames } from './grouping.js'
+import { describeOperations, type GoOperation } from './operations.js'
+
+export interface ReadmeService {
+  root: string
+  nestPath: string[]
+  operations: Operation[]
+}
+
+interface ResourceSection {
+  root: string
+  operations: Array<{ service: ReadmeService; operation: GoOperation }>
+}
+
+const HEADINGS = {
+  toc: 'Table of Contents',
+  install: 'Installation',
+  init: 'Initialization',
+  usage: 'Usage',
+  resources: 'Available Resources and Operations',
+  errors: 'Error Handling',
+  pagination: 'Pagination and Streaming',
+} as const
+
+/** GitHub's heading-to-anchor slug: lowercase, strip punctuation, spaces to
+ * hyphens. The table of contents is built with this same function so its links
+ * always resolve to the headings it points at. */
+function slug(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+}
+
+function tocEntry(heading: string, depth: number): string {
+  const indent = '  '.repeat(depth)
+  return `${indent}- [${heading}](#${slug(heading)})`
+}
+
+function header(note?: string): string {
+  const lines = [
+    '# OpenMeter Go SDK',
+    '',
+    'Go client for the OpenMeter API — usage metering and billing for',
+    'AI and DevTool companies. This package is generated from the OpenMeter',
+    'TypeSpec definitions and ships typed request and response models.',
+  ]
+  if (note) {
+    lines.push('', note.trim())
+  }
+  return lines.join('\n')
+}
+
+function tableOfContents(resources: ResourceSection[]): string {
+  const lines = [`## ${HEADINGS.toc}`, '']
+  lines.push(tocEntry(HEADINGS.install, 0))
+  lines.push(tocEntry(HEADINGS.init, 0))
+  lines.push(tocEntry(HEADINGS.usage, 0))
+  lines.push(tocEntry(HEADINGS.resources, 0))
+  for (const resource of resources) {
+    lines.push(tocEntry(namespaceNames(resource.root).class, 1))
+  }
+  lines.push(tocEntry(HEADINGS.errors, 0))
+  lines.push(tocEntry(HEADINGS.pagination, 0))
+  return lines.join('\n')
+}
+
+function installation(modulePath: string): string {
+  return [
+    `## ${HEADINGS.install}`,
+    '',
+    '```bash',
+    `go get ${modulePath}`,
+    '```',
+  ].join('\n')
+}
+
+function initialization(modulePath: string, packageName: string): string {
+  return [
+    `## ${HEADINGS.init}`,
+    '',
+    'Create a client with a base URL and an API key. The API key is sent as a',
+    '`Bearer` token on every request.',
+    '',
+    '```go',
+    'package main',
+    '',
+    'import (',
+    '\t"log"',
+    '\t"os"',
+    '',
+    `\t"${modulePath}"`,
+    ')',
+    '',
+    'func main() {',
+    `\tom, err := ${packageName}.New(`,
+    '\t\t"https://openmeter.cloud/api/v3",',
+    `\t\t${packageName}.WithToken(os.Getenv("OPENMETER_API_KEY")),`,
+    '\t)',
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '',
+    '\t_ = om',
+    '}',
+    '```',
+    '',
+    'For region-specific deployments, pass the concrete API base URL for that',
+    'region to `New`.',
+  ].join('\n')
+}
+
+function usage(modulePath: string, packageName: string): string {
+  return [
+    `## ${HEADINGS.usage}`,
+    '',
+    'Every operation is reachable through a namespaced service on the client and',
+    'returns a typed response plus an `error`.',
+    '',
+    '```go',
+    'package main',
+    '',
+    'import (',
+    '\t"context"',
+    '\t"log"',
+    '\t"os"',
+    '',
+    `\t"${modulePath}"`,
+    ')',
+    '',
+    'func main() {',
+    `\tom, err := ${packageName}.New(`,
+    '\t\t"https://openmeter.cloud/api/v3",',
+    `\t\t${packageName}.WithToken(os.Getenv("OPENMETER_API_KEY")),`,
+    '\t)',
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '',
+    '\tctx := context.Background()',
+    `\tmeter, err := om.Meters.Create(ctx, ${packageName}.CreateMeterRequest{`,
+    '\t\tName:          "Tokens",',
+    '\t\tKey:           "tokens",',
+    `\t\tAggregation:   ${packageName}.MeterAggregationSum,`,
+    '\t\tEventType:     "request",',
+    `\t\tValueProperty: ${packageName}.String("$.tokens"),`,
+    '\t})',
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '',
+    `\tmeters, err := om.Meters.List(ctx, ${packageName}.MeterListParams{})`,
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '',
+    '\t_, _ = meter, meters',
+    '}',
+    '```',
+    '',
+    'Operation arguments follow the generated method signature: path parameters',
+    'come first, then a typed request body when present, then typed query params',
+    'when present.',
+  ].join('\n')
+}
+
+function callPath(service: ReadmeService, methodName: string): string {
+  return ['om', service.root, ...service.nestPath, methodName].join('.')
+}
+
+// Mirrors GoResource's isTextResponse: text responses grow a Stream method
+// variant alongside the byte-returning method.
+function isTextResponse(operation: GoOperation): boolean {
+  return operation.responseContentType?.startsWith('text/') ?? false
+}
+
+function summaryCell(program: Program, op: GoOperation): string {
+  const summary = $(program).type.getDoc(op.operation)
+  if (!summary) {
+    return ''
+  }
+
+  return summary
+    .trim()
+    .replace(/\s+/g, ' ')
+    .replace(/\\/g, '\\\\')
+    .replace(/\|/g, '\\|')
+}
+
+function operationsTable(
+  program: Program,
+  operations: ResourceSection['operations'],
+): string {
+  const header = ['| Method | HTTP | Description |', '| --- | --- | --- |']
+  const rows = operations.flatMap(({ service, operation }) => {
+    const call = `\`${callPath(service, operation.methodName)}\``
+    const http = `\`${operation.verb.toUpperCase()} ${operation.path}\``
+    const row = `| ${call} | ${http} | ${summaryCell(program, operation)} |`
+    if (!isTextResponse(operation)) {
+      return [row]
+    }
+    const streamName = `${goExportedName(operation.methodName)}Stream`
+    const streamCall = `\`${callPath(service, streamName)}\``
+    return [
+      row,
+      `| ${streamCall} | ${http} | Streaming variant of \`${operation.methodName}\` returning an \`io.ReadCloser\`. |`,
+    ]
+  })
+  return [...header, ...rows].join('\n')
+}
+
+function resourcesSection(
+  program: Program,
+  resources: ResourceSection[],
+): string {
+  const blocks = [
+    `## ${HEADINGS.resources}`,
+    '',
+    'Operations are grouped by resource and exposed as services on the client.',
+    'The full call path, HTTP route, and a short description are listed below.',
+  ]
+
+  for (const resource of resources) {
+    blocks.push(
+      '',
+      `### ${namespaceNames(resource.root).class}`,
+      '',
+      operationsTable(program, resource.operations),
+    )
+  }
+
+  return blocks.join('\n')
+}
+
+function errorHandling(modulePath: string, packageName: string): string {
+  return [
+    `## ${HEADINGS.errors}`,
+    '',
+    'A non-2xx response returns an `*APIError` carrying the problem-details',
+    'fields (`StatusCode`, `Status`, `Type`, `Title`, `Detail`, `Instance`) from',
+    'the response where available. Client-side validation errors such as an empty',
+    'path ID are returned before any HTTP request is made.',
+    '',
+    '```go',
+    'package main',
+    '',
+    'import (',
+    '\t"context"',
+    '\t"errors"',
+    '\t"log"',
+    '',
+    `\t"${modulePath}"`,
+    ')',
+    '',
+    'func main() {',
+    `\tom, err := ${packageName}.New("https://openmeter.cloud/api/v3", ${packageName}.WithToken("om_..."))`,
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '',
+    '\t_, err = om.Meters.Get(context.Background(), "unknown")',
+    '\tif err != nil {',
+    `\t\tvar apiErr *${packageName}.APIError`,
+    '\t\tif errors.As(err, &apiErr) {',
+    '\t\t\tlog.Printf("%d %s %s", apiErr.StatusCode, apiErr.Title, apiErr.Type)',
+    '\t\t\treturn',
+    '\t\t}',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '}',
+    '```',
+  ].join('\n')
+}
+
+function paginationAndStreaming(packageName: string): string {
+  return [
+    `## ${HEADINGS.pagination}`,
+    '',
+    'Paginated list operations also emit `ListAll` helpers that return',
+    '`iter.Seq2[T, error]`. Text responses such as meter CSV export emit a byte',
+    'returning method and a `Stream` variant for callers that want an',
+    '`io.ReadCloser`.',
+    '',
+    'Cursor-paginated responses report their position as `Next` and `Previous`',
+    'on `CursorMetaPage`. Both are opaque cursor tokens: pass them back verbatim',
+    'as the `page[after]` / `page[before]` query parameters',
+    '(`CursorPageParams.After` / `CursorPageParams.Before`); do not parse or',
+    'construct them.',
+    '',
+    'Iterating with `Before` set walks pages backward while the items within',
+    'each page stay in forward order, so the resulting stream is not globally',
+    'sorted.',
+    '',
+    '```go',
+    `for meter, err := range om.Meters.ListAll(ctx, ${packageName}.MeterListParams{}) {`,
+    '\tif err != nil {',
+    '\t\tlog.Fatal(err)',
+    '\t}',
+    '\tlog.Println(meter.Key)',
+    '}',
+    '',
+    `stream, err := om.Meters.QueryCSVStream(ctx, "meter-id", ${packageName}.MeterQueryRequest{})`,
+    'if err != nil {',
+    '\tlog.Fatal(err)',
+    '}',
+    'defer stream.Close()',
+    '```',
+  ].join('\n')
+}
+
+function resourceSections(
+  program: Program,
+  services: ReadmeService[],
+  bodyOverrides: Map<string, Type>,
+): ResourceSection[] {
+  const byRoot = new Map<string, ResourceSection>()
+  for (const service of services) {
+    const section = byRoot.get(service.root) ?? {
+      root: service.root,
+      operations: [],
+    }
+    if (!byRoot.has(service.root)) {
+      byRoot.set(service.root, section)
+    }
+
+    for (const operation of describeOperations(
+      program,
+      service.root,
+      service.operations,
+      bodyOverrides,
+      service.nestPath,
+    )) {
+      section.operations.push({ service, operation })
+    }
+  }
+
+  return [...byRoot.values()].filter(
+    (resource) => resource.operations.length > 0,
+  )
+}
+
+/** The package README, built from the same grouped operations the Go SDK files
+ * are generated from, so the documented call paths and routes always match the
+ * emitted client. */
+export function readmeFile(
+  program: Program,
+  modulePath: string,
+  packageName: string,
+  services: ReadmeService[],
+  bodyOverrides: Map<string, Type>,
+  note?: string,
+): string {
+  const resources = resourceSections(program, services, bodyOverrides)
+
+  return (
+    [
+      header(note),
+      tableOfContents(resources),
+      installation(modulePath),
+      initialization(modulePath, packageName),
+      usage(modulePath, packageName),
+      resourcesSection(program, resources),
+      errorHandling(modulePath, packageName),
+      paginationAndStreaming(packageName),
+    ].join('\n\n') + '\n'
+  )
+}

api/spec/packages/typespec-go/src/runtime-symbols.ts

@@ -0,0 +1,81 @@
+import type { Type } from '@typespec/compiler'
+
+// Exported names owned by the static runtime templates and fixed client
+// scaffolding. TypeSpec-generated declarations share Go's package-level
+// namespace with these symbols, so any accidental overlap must stop emission
+// before the generated SDK reaches go build.
+export const RESERVED_GO_SYMBOL_NAMES = new Set([
+  'APIError',
+  'AsAPIError',
+  'Bool',
+  'BooleanFilter',
+  'Client',
+  'CursorPageParams',
+  'DateTimeFilter',
+  'DecodeAPIError',
+  'ErrEmptyID',
+  'Int',
+  'Many',
+  'New',
+  'Null',
+  'Nullable',
+  'NullableValue',
+  'Numeric',
+  'NumericFilter',
+  'One',
+  'OneOrMany',
+  'Option',
+  'PageMeta',
+  'PageParams',
+  'PaginatedMeta',
+  'Ptr',
+  'Sort',
+  'SortOrder',
+  'SortOrderAsc',
+  'SortOrderDesc',
+  'String',
+  'StringExactFilter',
+  'StringFilter',
+  'Time',
+  'Version',
+  'WithHTTPClient',
+  'WithToken',
+  'WithUserAgent',
+])
+
+// TypeSpec constructs that intentionally map to runtime-owned SDK shapes rather
+// than generated model declarations.
+const RUNTIME_BACKED_TYPE_NAMES = new Set([
+  'Numeric',
+  'PageMeta',
+  'PageParams',
+  'PaginatedMeta',
+  'SortQuery',
+  'StringFilter',
+  'StringFieldFilter',
+  'StringFieldFilterExact',
+])
+
+export function isRuntimeBackedTypeName(
+  name: string,
+  kind: Type['kind'],
+): boolean {
+  if (name === 'String') {
+    return kind === 'Scalar'
+  }
+
+  return (
+    RUNTIME_BACKED_TYPE_NAMES.has(name) ||
+    name.endsWith('FieldFilter') ||
+    name.endsWith('FieldFilterExact')
+  )
+}
+
+export function conflictsWithReservedGoSymbol(
+  name: string,
+  kind: Type['kind'],
+): boolean {
+  return (
+    RESERVED_GO_SYMBOL_NAMES.has(name) && !isRuntimeBackedTypeName(name, kind)
+  )
+}

api/spec/packages/typespec-go/src/runtime-templates.ts

@@ -0,0 +1,868 @@
+// Static Go SDK runtime files emitted into the generated SDK.
+//
+// Keep these as emitter-owned TypeScript templates rather than files in a
+// runtime/ Go package. That avoids making the emitter source tree look like a
+// standalone Go module while still keeping the generated runtime reviewable.
+
+export const RUNTIME_TEMPLATES: Record<string, string> = {
+  'errors.go': `package openmeter
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+)
+
+// ErrEmptyID is returned by operations that target a single resource when the
+// resource ID is empty. It is caught before any request is made so an omitted
+// ID surfaces as a clear client-side error rather than an ambiguous server
+// response. Match it with errors.Is.
+var ErrEmptyID = errors.New("openmeter: resource ID must not be empty")
+
+// APIError is returned for any non-2xx API response. It mirrors the API's
+// RFC 7807-style problem body. When the body cannot be parsed as such, Title is
+// left empty and RawBody carries the undecoded payload.
+type APIError struct {
+	// StatusCode is the HTTP status code of the response.
+	StatusCode int \`json:"-"\`
+
+	// Status is the status code echoed in the problem body (usually equal to
+	// StatusCode).
+	Status int \`json:"status"\`
+	// Title is a short, stable, human-readable summary of the problem.
+	Title string \`json:"title"\`
+	// Type is an optional machine-readable error type.
+	Type string \`json:"type,omitempty"\`
+	// Detail is a human-readable explanation specific to this occurrence.
+	Detail string \`json:"detail"\`
+	// Instance carries the correlation ID, formatted as kong:trace:<id>.
+	Instance string \`json:"instance"\`
+
+	// RawBody is the undecoded response body, always populated.
+	RawBody []byte \`json:"-"\`
+}
+
+func newAPIError(statusCode int, body []byte) *APIError {
+	e := &APIError{StatusCode: statusCode, RawBody: body}
+	// Best-effort decode; a non-conforming body still yields a useful error via
+	// StatusCode and RawBody.
+	_ = json.Unmarshal(body, e)
+	return e
+}
+
+// AsAPIError returns the APIError inside err, when err came from an API response.
+func AsAPIError(err error) (*APIError, bool) {
+	var apiErr *APIError
+	if errors.As(err, &apiErr) {
+		return apiErr, true
+	}
+	return nil, false
+}
+
+// Decode decodes the original error response body into out.
+func (e *APIError) Decode(out any) error {
+	return json.Unmarshal(e.RawBody, out)
+}
+
+// DecodeAPIError decodes an API error body into T. The returned boolean is false
+// when err is not an APIError.
+func DecodeAPIError[T any](err error) (T, bool, error) {
+	var zero T
+	apiErr, ok := AsAPIError(err)
+	if !ok {
+		return zero, false, nil
+	}
+
+	var out T
+	if err := apiErr.Decode(&out); err != nil {
+		return zero, true, err
+	}
+	return out, true, nil
+}
+
+func (e *APIError) Error() string {
+	switch {
+	case e.Title != "" && e.Detail != "":
+		return fmt.Sprintf("openmeter: %d %s: %s", e.StatusCode, e.Title, e.Detail)
+	case e.Title != "":
+		return fmt.Sprintf("openmeter: %d %s", e.StatusCode, e.Title)
+	default:
+		// No RFC 7807 fields parsed (e.g. a proxy returned an HTML error page).
+		// Inline the raw body for diagnostics but bound it so a large payload
+		// can't blow up log lines; RawBody still holds the full response.
+		const maxInline = 512
+		body := e.RawBody
+		suffix := ""
+		if len(body) > maxInline {
+			body = body[:maxInline]
+			suffix = "… (truncated)"
+		}
+		return fmt.Sprintf("openmeter: unexpected status %d: %s%s", e.StatusCode, string(body), suffix)
+	}
+}
+`,
+  'filters.go': `package openmeter
+
+import "time"
+
+// StringFilter expresses the comparison operators accepted for string fields.
+type StringFilter struct {
+	Eq        *string
+	Neq       *string
+	Gt        *string
+	Gte       *string
+	Lt        *string
+	Lte       *string
+	Contains  *string
+	Oeq       []string
+	Ocontains []string
+	Exists    *bool
+}
+
+// StringExactFilter expresses exact comparisons for strings and ULIDs.
+type StringExactFilter struct {
+	Eq  *string
+	Neq *string
+	Oeq []string
+}
+
+// DateTimeFilter expresses comparisons against RFC 3339 timestamps.
+type DateTimeFilter struct {
+	Eq  *time.Time
+	Gt  *time.Time
+	Gte *time.Time
+	Lt  *time.Time
+	Lte *time.Time
+}
+
+// NumericFilter expresses numeric comparison operators.
+type NumericFilter struct {
+	Eq  *float64
+	Neq *float64
+	Gt  *float64
+	Gte *float64
+	Lt  *float64
+	Lte *float64
+	Oeq []float64
+}
+
+// BooleanFilter expresses equality for a boolean field.
+type BooleanFilter struct {
+	Eq *bool
+}
+`,
+  // {{MODULE_PATH}} is interpolated from the required module-path option.
+  // {{GO_VERSION}} comes from the go-version option, defaulting to 1.23 (the
+  // generated code's actual floor, needed by the iter package); a repo can
+  // raise it to a higher consumer floor, e.g. when preserved *_test.go files
+  // need newer stdlib APIs. The single-entry require stays unparenthesized so
+  // 'go mod tidy -diff' is a no-op on the emitted file.
+  'go.mod': `module {{MODULE_PATH}}
+
+go {{GO_VERSION}}
+
+require github.com/oapi-codegen/nullable v1.2.0
+`,
+  'go.sum': `github.com/oapi-codegen/nullable v1.2.0 h1:VflFkDW980KhBPiFF7nWSyjg+r4Obqj8lXipV0UkP5w=
+github.com/oapi-codegen/nullable v1.2.0/go.mod h1:KUZ3vUzkmEKY90ksAmit2+5juDIhIZhfDl+0PwOQlFY=
+`,
+  'nullable.go': `package openmeter
+
+import "github.com/oapi-codegen/nullable"
+
+// Nullable represents a JSON field with three states: unspecified, explicit
+// null, or a concrete value. Optional nullable fields use this as a value with
+// omitempty; do not wrap it in a pointer.
+type Nullable[T any] = nullable.Nullable[T]
+
+// Null constructs an explicit JSON null.
+func Null[T any]() Nullable[T] {
+	return nullable.NewNullNullable[T]()
+}
+
+// NullableValue constructs a non-null value.
+func NullableValue[T any](value T) Nullable[T] {
+	return nullable.NewNullableWithValue(value)
+}
+`,
+  'one_or_many.go': `package openmeter
+
+import (
+	"bytes"
+	"encoding/json"
+)
+
+// OneOrMany represents a JSON value that accepts either one T or an array of T.
+// The zero value holds neither variant and marshals as JSON null.
+type OneOrMany[T any] struct {
+	one  *T
+	many []T
+}
+
+// One wraps a single value.
+func One[T any](value T) OneOrMany[T] {
+	return OneOrMany[T]{one: &value}
+}
+
+// Many wraps an array. A non-nil empty slice is encoded as [].
+func Many[T any](values []T) OneOrMany[T] {
+	return OneOrMany[T]{many: values}
+}
+
+// AsOne returns the single value. The boolean is false when the array variant
+// is set or the value is empty.
+func (value OneOrMany[T]) AsOne() (*T, bool) {
+	if value.many != nil || value.one == nil {
+		return nil, false
+	}
+	return value.one, true
+}
+
+// AsMany returns the array. The boolean is false when the single-value variant
+// is set or the value is empty.
+func (value OneOrMany[T]) AsMany() ([]T, bool) {
+	if value.many == nil {
+		return nil, false
+	}
+	return value.many, true
+}
+
+func (value OneOrMany[T]) MarshalJSON() ([]byte, error) {
+	if value.many != nil {
+		return json.Marshal(value.many)
+	}
+	if value.one != nil {
+		return json.Marshal(value.one)
+	}
+	return []byte("null"), nil
+}
+
+func (value *OneOrMany[T]) UnmarshalJSON(data []byte) error {
+	*value = OneOrMany[T]{}
+	data = bytes.TrimSpace(data)
+	if bytes.Equal(data, []byte("null")) {
+		return nil
+	}
+	if len(data) > 0 && data[0] == '[' {
+		return json.Unmarshal(data, &value.many)
+	}
+	var one T
+	if err := json.Unmarshal(data, &one); err != nil {
+		return err
+	}
+	value.one = &one
+	return nil
+}
+`,
+  'option.go': `package openmeter
+
+import (
+	"net/http"
+	"runtime/debug"
+)
+
+// Version is the SDK version reported in the default User-Agent. When the SDK
+// is consumed as a module dependency it is resolved from the consumer's build
+// info (the module version selected by their go.mod), so tagged releases need
+// no stamping commit. Builds where that is unavailable — the module itself,
+// replace directives, vendored trees without version data — fall back to the
+// sdk-version emitter option ("{{SDK_VERSION}}").
+var Version = resolveVersion()
+
+func resolveVersion() string {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		for _, dep := range info.Deps {
+			if dep.Path != "{{MODULE_PATH}}" || dep.Replace != nil {
+				continue
+			}
+			if dep.Version != "" && dep.Version != "(devel)" {
+				return dep.Version
+			}
+		}
+	}
+	return "{{SDK_VERSION}}"
+}
+
+var defaultUserAgent = "openmeter-go-sdk/" + Version
+
+// Option configures a Client during New.
+type Option func(*Client)
+
+// WithToken sets the bearer token sent in the Authorization header of every
+// request. The header is applied during request construction, so it is honored
+// regardless of any client injected via WithHTTPClient.
+func WithToken(token string) Option {
+	return func(c *Client) {
+		c.token = token
+	}
+}
+
+// WithHTTPClient replaces the default *http.Client. The provided client owns all
+// transport behavior: retries, timeouts, proxies, TLS, and tracing. Pass nil to
+// keep the default.
+func WithHTTPClient(hc *http.Client) Option {
+	return func(c *Client) {
+		if hc != nil {
+			c.httpClient = hc
+		}
+	}
+}
+
+// WithUserAgent overrides the User-Agent header sent with each request.
+func WithUserAgent(ua string) Option {
+	return func(c *Client) {
+		if ua != "" {
+			c.userAgent = ua
+		}
+	}
+}
+`,
+  'pagination.go': `package openmeter
+
+import (
+	"fmt"
+	"iter"
+	"net/url"
+	"strconv"
+)
+
+const defaultListPageSize = 100
+const maxPages = 10_000
+
+// PageParams selects a numbered page.
+type PageParams struct {
+	Size   *int
+	Number *int
+}
+
+// CursorPageParams selects a cursor page.
+type CursorPageParams struct {
+	Size   *int
+	After  *string
+	Before *string
+}
+
+type PageMeta struct {
+	Number int \`json:"number"\`
+	Size   int \`json:"size"\`
+	Total  int \`json:"total"\`
+}
+
+type PaginatedMeta struct {
+	Page PageMeta \`json:"page"\`
+}
+
+func addPageParams(q url.Values, page *PageParams) {
+	if page == nil {
+		return
+	}
+	if page.Size != nil {
+		setDeepObjectString(q, "page", "size", strconv.Itoa(*page.Size))
+	}
+	if page.Number != nil {
+		setDeepObjectString(q, "page", "number", strconv.Itoa(*page.Number))
+	}
+}
+
+func addCursorPageParams(q url.Values, page *CursorPageParams) {
+	if page == nil {
+		return
+	}
+	if page.Size != nil {
+		setDeepObjectString(q, "page", "size", strconv.Itoa(*page.Size))
+	}
+	if page.After != nil {
+		setDeepObjectString(q, "page", "after", *page.After)
+	}
+	if page.Before != nil {
+		setDeepObjectString(q, "page", "before", *page.Before)
+	}
+}
+
+func paginate[T any](start *PageParams, fetch func(page, size int) ([]T, int, error)) iter.Seq2[T, error] {
+	return func(yield func(T, error) bool) {
+		page, size := 1, defaultListPageSize
+		if start != nil {
+			if start.Number != nil {
+				page = *start.Number
+			}
+			if start.Size != nil {
+				size = *start.Size
+			}
+		}
+		seen := 0
+		for fetched := 0; fetched < maxPages; fetched++ {
+			data, total, err := fetch(page, size)
+			if err != nil {
+				var zero T
+				yield(zero, err)
+				return
+			}
+			for _, item := range data {
+				if !yield(item, nil) {
+					return
+				}
+			}
+			seen += len(data)
+			if len(data) == 0 || (total > 0 && seen >= total) {
+				return
+			}
+			page++
+		}
+		var zero T
+		yield(zero, fmt.Errorf("openmeter: pagination did not terminate within %d pages", maxPages))
+	}
+}
+
+func paginateCursor[T any](start *CursorPageParams, fetch func(after, before *string, size int) ([]T, *string, *string, error)) iter.Seq2[T, error] {
+	return func(yield func(T, error) bool) {
+		size := defaultListPageSize
+		var after, before *string
+		if start != nil {
+			after = start.After
+			before = start.Before
+			if after != nil && before != nil {
+				var zero T
+				yield(zero, fmt.Errorf("openmeter: cursor pagination cannot use both after and before"))
+				return
+			}
+			if start.Size != nil {
+				size = *start.Size
+			}
+		}
+		reverse := before != nil
+		for fetched := 0; fetched < maxPages; fetched++ {
+			data, next, previous, err := fetch(after, before, size)
+			if err != nil {
+				var zero T
+				yield(zero, err)
+				return
+			}
+			for _, item := range data {
+				if !yield(item, nil) {
+					return
+				}
+			}
+			if reverse {
+				if previous == nil || *previous == "" || len(data) == 0 {
+					return
+				}
+				before = previous
+			} else {
+				if next == nil || *next == "" || len(data) == 0 {
+					return
+				}
+				after = next
+			}
+		}
+		var zero T
+		yield(zero, fmt.Errorf("openmeter: cursor pagination did not terminate within %d pages", maxPages))
+	}
+}
+`,
+  'ptr.go': `package openmeter
+
+import "time"
+
+// Pointer helpers for populating optional request fields inline. They mirror the
+// convention used by other Go cloud SDKs (e.g. aws.String), keeping call sites
+// free of one-off address-of locals.
+
+// Ptr returns a pointer to v. It is the generic form covering any type; the
+// typed String/Int/Bool/Time below remain because they let the compiler infer
+// the element type at call sites where a bare literal would not (e.g.
+// String("x") vs Ptr("x"), which are equivalent, but Int(1) avoids Ptr[int](1)).
+func Ptr[T any](v T) *T { return &v }
+
+// String returns a pointer to s.
+func String(s string) *string { return &s }
+
+// Int returns a pointer to i.
+func Int(i int) *int { return &i }
+
+// Bool returns a pointer to b.
+func Bool(b bool) *bool { return &b }
+
+// Time returns a pointer to t.
+func Time(t time.Time) *time.Time { return &t }
+`,
+  'query.go': `package openmeter
+
+import (
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// SortOrder is the direction of a sort expression.
+type SortOrder string
+
+const (
+	SortOrderAsc  SortOrder = "asc"
+	SortOrderDesc SortOrder = "desc"
+)
+
+// Sort selects a wire field and optional direction.
+type Sort struct {
+	By    string
+	Order SortOrder
+}
+
+func setDeepObjectString(q url.Values, prefix, key, value string) {
+	q.Set(prefix+"["+key+"]", value)
+}
+
+func addSort(q url.Values, name string, sort *Sort) {
+	if sort == nil || sort.By == "" {
+		return
+	}
+	value := sort.By
+	if sort.Order != "" {
+		value += " " + string(sort.Order)
+	}
+	q.Set(name, value)
+}
+
+func addStringFilter(q url.Values, prefix string, f *StringFilter) {
+	if f == nil {
+		return
+	}
+	if f.Eq != nil {
+		setDeepObjectString(q, prefix, "eq", *f.Eq)
+	}
+	if f.Neq != nil {
+		setDeepObjectString(q, prefix, "neq", *f.Neq)
+	}
+	if f.Contains != nil {
+		setDeepObjectString(q, prefix, "contains", *f.Contains)
+	}
+	if f.Gt != nil {
+		setDeepObjectString(q, prefix, "gt", *f.Gt)
+	}
+	if f.Gte != nil {
+		setDeepObjectString(q, prefix, "gte", *f.Gte)
+	}
+	if f.Lt != nil {
+		setDeepObjectString(q, prefix, "lt", *f.Lt)
+	}
+	if f.Lte != nil {
+		setDeepObjectString(q, prefix, "lte", *f.Lte)
+	}
+	if len(f.Oeq) > 0 {
+		setDeepObjectString(q, prefix, "oeq", strings.Join(f.Oeq, ","))
+	}
+	if len(f.Ocontains) > 0 {
+		setDeepObjectString(q, prefix, "ocontains", strings.Join(f.Ocontains, ","))
+	}
+	if f.Exists != nil {
+		setDeepObjectString(q, prefix, "exists", strconv.FormatBool(*f.Exists))
+	}
+}
+
+func addStringExactFilter(q url.Values, prefix string, f *StringExactFilter) {
+	if f == nil {
+		return
+	}
+	if f.Eq != nil {
+		setDeepObjectString(q, prefix, "eq", *f.Eq)
+	}
+	if f.Neq != nil {
+		setDeepObjectString(q, prefix, "neq", *f.Neq)
+	}
+	if len(f.Oeq) > 0 {
+		setDeepObjectString(q, prefix, "oeq", strings.Join(f.Oeq, ","))
+	}
+}
+
+func addDateTimeFilter(q url.Values, prefix string, f *DateTimeFilter) {
+	if f == nil {
+		return
+	}
+	values := []struct {
+		name  string
+		value *time.Time
+	}{
+		{"eq", f.Eq},
+		{"gt", f.Gt},
+		{"gte", f.Gte},
+		{"lt", f.Lt},
+		{"lte", f.Lte},
+	}
+	for _, value := range values {
+		if value.value != nil {
+			setDeepObjectString(q, prefix, value.name, value.value.Format(time.RFC3339Nano))
+		}
+	}
+}
+
+func addNumericFilter(q url.Values, prefix string, f *NumericFilter) {
+	if f == nil {
+		return
+	}
+	format := func(value float64) string {
+		return strconv.FormatFloat(value, 'g', -1, 64)
+	}
+	values := []struct {
+		name  string
+		value *float64
+	}{
+		{"eq", f.Eq},
+		{"neq", f.Neq},
+		{"gt", f.Gt},
+		{"gte", f.Gte},
+		{"lt", f.Lt},
+		{"lte", f.Lte},
+	}
+	for _, value := range values {
+		if value.value != nil {
+			setDeepObjectString(q, prefix, value.name, format(*value.value))
+		}
+	}
+	if len(f.Oeq) > 0 {
+		values := make([]string, 0, len(f.Oeq))
+		for _, value := range f.Oeq {
+			values = append(values, format(value))
+		}
+		setDeepObjectString(q, prefix, "oeq", strings.Join(values, ","))
+	}
+}
+
+func addBooleanFilter(q url.Values, prefix string, f *BooleanFilter) {
+	if f != nil && f.Eq != nil {
+		setDeepObjectString(q, prefix, "eq", strconv.FormatBool(*f.Eq))
+	}
+}
+`,
+  'request_content_type.go': `package openmeter
+
+import (
+	"context"
+	"net/http"
+	"net/url"
+)
+
+func (c *Client) newRequestWithContentType(
+	ctx context.Context,
+	method string,
+	apiPath string,
+	query url.Values,
+	body any,
+	contentType string,
+	accept string,
+) (*http.Request, error) {
+	req, err := c.newRequest(ctx, method, apiPath, query, body, accept)
+	if err != nil {
+		return nil, err
+	}
+	if body != nil && contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	return req, nil
+}
+
+func optionalBody[T any](body *T) any {
+	if body == nil {
+		return nil
+	}
+	return body
+}
+`,
+  'transport.go': `package openmeter
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+const (
+	contentTypeJSON = "application/json"
+
+	// defaultRequestTimeout bounds a buffered request when the caller's context
+	// carries no deadline, so a call can't hang forever by default. It is applied
+	// via context, not http.Client.Timeout, so it never interferes with streaming
+	// body reads. Callers wanting a different bound pass their own context
+	// deadline; requests made through Stream method variants are never bounded by
+	// this and rely solely on the caller's context.
+	defaultRequestTimeout = 30 * time.Second
+
+	// maxBufferedResponse caps how much of a response the buffered read paths
+	// (JSON decoding, byte-returning text methods) hold in memory, guarding
+	// against unbounded growth from an unexpectedly large payload. Exports that
+	// may exceed this should use the operation's Stream method variant.
+	maxBufferedResponse = 10 << 20 // 10 MiB
+	// maxErrorBody caps how much of a non-2xx body is read to build an APIError.
+	maxErrorBody = 1 << 20 // 1 MiB
+)
+
+// defaultHTTPClient builds the SDK's default transport.
+//
+// It deliberately sets no http.Client.Timeout: that field also bounds reading the
+// response body and would abort a streamed export mid-read. Per-call deadlines
+// come from the request context instead (see defaultRequestTimeout).
+func defaultHTTPClient() *http.Client {
+	return &http.Client{}
+}
+
+// newRequest builds an *http.Request against the client base URL. body, when
+// non-nil, is JSON-encoded and Content-Type is set accordingly. accept sets the
+// Accept header (JSON or CSV) to drive server-side content negotiation.
+func (c *Client) newRequest(ctx context.Context, method, apiPath string, query url.Values, body any, accept string) (*http.Request, error) {
+	u := c.resolve(apiPath)
+	if len(query) > 0 {
+		merged := u.Query()
+		for key, values := range query {
+			merged.Del(key)
+			for _, value := range values {
+				merged.Add(key, value)
+			}
+		}
+		u.RawQuery = merged.Encode()
+	}
+
+	var bodyReader io.Reader
+	if body != nil {
+		buf, err := json.Marshal(body)
+		if err != nil {
+			return nil, fmt.Errorf("openmeter: encoding request body: %w", err)
+		}
+
+		bodyReader = bytes.NewReader(buf)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, u.String(), bodyReader)
+	if err != nil {
+		return nil, fmt.Errorf("openmeter: building request: %w", err)
+	}
+
+	if body != nil {
+		req.Header.Set("Content-Type", contentTypeJSON)
+	}
+
+	if accept != "" {
+		req.Header.Set("Accept", accept)
+	}
+
+	if c.userAgent != "" {
+		req.Header.Set("User-Agent", c.userAgent)
+	}
+
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
+
+	return req, nil
+}
+
+// doJSON executes req and decodes a 2xx JSON body into out (out may be nil to
+// discard the body). Non-2xx responses are converted to *APIError.
+func (c *Client) doJSON(req *http.Request, out any) error {
+	body, err := c.doRaw(req)
+	if err != nil {
+		return err
+	}
+
+	if out == nil || len(body) == 0 {
+		return nil
+	}
+
+	if err := json.Unmarshal(body, out); err != nil {
+		return fmt.Errorf("openmeter: decoding response body: %w", err)
+	}
+
+	return nil
+}
+
+// withDefaultDeadline bounds a buffered request to defaultRequestTimeout when
+// the caller's context carries no deadline, so a call can't hang forever by
+// default. When the caller already set a deadline, the request is returned
+// unchanged. The returned cancel func must always be called; it is a no-op in
+// the pass-through case. Streaming requests intentionally skip this so a long
+// body read is bounded only by the caller's own context.
+func withDefaultDeadline(req *http.Request) (*http.Request, context.CancelFunc) {
+	if _, ok := req.Context().Deadline(); ok {
+		return req, func() {}
+	}
+
+	ctx, cancel := context.WithTimeout(req.Context(), defaultRequestTimeout)
+	return req.WithContext(ctx), cancel
+}
+
+// doRaw executes req, returns the 2xx body (capped at maxBufferedResponse), and
+// converts any non-2xx response into an *APIError. Use doStream for responses
+// that may exceed the buffered limit (e.g. large CSV exports).
+func (c *Client) doRaw(req *http.Request) ([]byte, error) {
+	req, cancel := withDefaultDeadline(req)
+	defer cancel()
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("openmeter: request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := readAllCapped(resp.Body, maxErrorBody)
+		return nil, newAPIError(resp.StatusCode, body)
+	}
+
+	body, err := readAllCapped(resp.Body, maxBufferedResponse)
+	if err != nil {
+		return nil, err
+	}
+
+	return body, nil
+}
+
+// doStream executes req and returns the live response for streaming. The caller
+// owns resp.Body and must close it. Non-2xx responses are converted to
+// *APIError (with the body closed) exactly as the buffered paths do, so a
+// successful return always carries a readable body.
+func (c *Client) doStream(req *http.Request) (*http.Response, error) {
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("openmeter: request failed: %w", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		defer resp.Body.Close()
+
+		body, _ := readAllCapped(resp.Body, maxErrorBody)
+
+		return nil, newAPIError(resp.StatusCode, body)
+	}
+
+	return resp, nil
+}
+
+// readAllCapped reads up to max bytes from r and returns an error if the source
+// carries more, bounding how much a buffered response can hold in memory. On
+// error it still returns whatever bytes were read (capped at max) so callers can
+// preserve partial diagnostic content, e.g. an oversized or truncated error body.
+func readAllCapped(r io.Reader, max int64) ([]byte, error) {
+	body, err := io.ReadAll(io.LimitReader(r, max+1))
+	if err != nil {
+		return body, fmt.Errorf("openmeter: reading response body: %w", err)
+	}
+
+	if int64(len(body)) > max {
+		return body[:max], fmt.Errorf("openmeter: response body exceeds %d-byte limit; use a streaming method for large payloads", max)
+	}
+
+	return body, nil
+}
+`,
+  'types.go': `package openmeter
+
+// Numeric represents an arbitrary-precision number. The API encodes it as a
+// decimal string (e.g. "12.3456") to avoid float precision loss, so the SDK
+// surfaces it as a string. Parse with a decimal library when arithmetic is needed.
+type Numeric = string
+`,
+}

api/spec/packages/typespec-go/src/stdlib.ts

@@ -0,0 +1,89 @@
+import * as go from '@alloy-js/go'
+
+export const context = go.createModule(
+  'context',
+  {
+    kind: 'package',
+    members: {
+      Context: { kind: 'interface', members: {} },
+    },
+  } as const,
+  true,
+)
+
+export const url = go.createModule(
+  'url',
+  {
+    kind: 'package',
+    path: 'net/url',
+    members: {
+      URL: { kind: 'struct', members: {} },
+      Values: {
+        kind: 'type',
+        members: {
+          Add: { kind: 'method' },
+          Set: { kind: 'method' },
+        },
+      },
+      Parse: { kind: 'function' },
+      PathEscape: { kind: 'function' },
+      PathUnescape: { kind: 'function' },
+    },
+  } as const,
+  true,
+)
+
+export const iter = go.createModule(
+  'iter',
+  {
+    kind: 'package',
+    path: 'iter',
+    members: {
+      Seq2: { kind: 'type', members: {} },
+    },
+  } as const,
+  true,
+)
+
+export const strings = go.createModule(
+  'strings',
+  {
+    kind: 'package',
+    path: 'strings',
+    members: {
+      HasSuffix: { kind: 'function' },
+      Join: { kind: 'function' },
+      ReplaceAll: { kind: 'function' },
+      TrimPrefix: { kind: 'function' },
+    },
+  } as const,
+  true,
+)
+
+export const json = go.createModule(
+  'json',
+  {
+    kind: 'package',
+    path: 'encoding/json',
+    members: {
+      Marshal: { kind: 'function' },
+      RawMessage: { kind: 'type', members: {} },
+      Unmarshal: { kind: 'function' },
+    },
+  } as const,
+  true,
+)
+
+export const strconv = go.createModule(
+  'strconv',
+  {
+    kind: 'package',
+    members: {
+      FormatBool: { kind: 'function' },
+      FormatFloat: { kind: 'function' },
+      FormatInt: { kind: 'function' },
+      FormatUint: { kind: 'function' },
+    },
+  } as const,
+  true,
+)

api/spec/packages/typespec-go/test/assembly.test.ts

@@ -0,0 +1,385 @@
+import { createTestHost, createTestRunner } from '@typespec/compiler/testing'
+import { HttpTestLibrary } from '@typespec/http/testing'
+import { OpenAPITestLibrary } from '@typespec/openapi/testing'
+import { describe, expect, it } from 'vitest'
+import type { Program } from '@typespec/compiler'
+import {
+  cleanOutputDirectory,
+  packageDocHeader,
+  prepareRuntimeTemplate,
+} from '../dist/emitter.js'
+import { goExportedName } from '../dist/go-types.js'
+import {
+  collectHttpOperations,
+  describeOperations,
+} from '../dist/operations.js'
+import { readmeFile } from '../dist/readme.js'
+import { RESERVED_GO_SYMBOL_NAMES } from '../dist/runtime-symbols.js'
+import { RUNTIME_TEMPLATES } from '../dist/runtime-templates.js'
+
+const GENERATED_HEADER =
+  '// Code generated by @openmeter/typespec-go. DO NOT EDIT.'
+
+/** Package-level exported identifiers declared by a runtime Go template:
+ * top-level func/type/const/var declarations plus members of top-level
+ * const/var blocks. Methods are skipped; they do not occupy the package
+ * namespace. */
+function templateExportedSymbols(content: string): string[] {
+  const names: string[] = []
+  let inBlock = false
+  for (const line of content.split('\n')) {
+    if (inBlock) {
+      if (line === ')') {
+        inBlock = false
+        continue
+      }
+      const member = line.match(/^\t([A-Za-z_][A-Za-z0-9_]*)/)
+      if (member) {
+        names.push(member[1]!)
+      }
+      continue
+    }
+    if (/^(const|var) \($/.test(line)) {
+      inBlock = true
+      continue
+    }
+    if (line.startsWith('func (')) {
+      continue
+    }
+    const decl = line.match(/^(?:func|type|const|var) ([A-Za-z_][A-Za-z0-9_]*)/)
+    if (decl) {
+      names.push(decl[1]!)
+    }
+  }
+  return names.filter((name) => /^[A-Z]/.test(name))
+}
+
+async function compileFixture(code: string): Promise<Program> {
+  const host = await createTestHost({
+    libraries: [HttpTestLibrary, OpenAPITestLibrary],
+  })
+  const runner = await createTestRunner(host)
+  await runner.compile(`
+    import "@typespec/http";
+    import "@typespec/openapi";
+    using TypeSpec.Http;
+    using TypeSpec.OpenAPI;
+    ${code}
+  `)
+  return runner.program
+}
+
+describe('runtime template assembly', () => {
+  it('keeps RESERVED_GO_SYMBOL_NAMES in sync with runtime template exports', () => {
+    const exported = new Map<string, string>()
+    for (const [path, content] of Object.entries(RUNTIME_TEMPLATES)) {
+      if (!path.endsWith('.go')) {
+        continue
+      }
+      for (const name of templateExportedSymbols(content)) {
+        exported.set(name, path)
+      }
+    }
+
+    // Guard the extractor itself: a regex regression that finds nothing (or
+    // misses const-block members) must fail here, not silently pass.
+    expect(exported.get('APIError')).toBe('errors.go')
+    expect(exported.get('SortOrderAsc')).toBe('query.go')
+
+    const missing = [...exported].filter(
+      ([name]) => !RESERVED_GO_SYMBOL_NAMES.has(name),
+    )
+    expect(
+      missing,
+      `runtime template exports missing from RESERVED_GO_SYMBOL_NAMES in runtime-symbols.ts: ${missing
+        .map(([name, path]) => `${name} (${path})`)
+        .join(', ')}`,
+    ).toEqual([])
+  })
+
+  it('interpolates go.mod from the module-path option with a tidy-canonical require block', () => {
+    const gomod = prepareRuntimeTemplate(
+      'go.mod',
+      RUNTIME_TEMPLATES['go.mod']!,
+      'openmeter',
+      'github.com/openmeterio/openmeter/api/v3/client',
+      '0.0.0-dev',
+      '1.23',
+    )
+
+    expect(gomod).toContain(
+      'module github.com/openmeterio/openmeter/api/v3/client\n',
+    )
+    expect(gomod).toContain('\ngo 1.23\n')
+    expect(gomod).toContain(
+      '\nrequire github.com/oapi-codegen/nullable v1.2.0\n',
+    )
+    expect(gomod).not.toContain('{{MODULE_PATH}}')
+    expect(gomod).not.toContain('require (')
+  })
+
+  it('stamps the go-version option into the go.mod go directive, overriding the 1.23 default', () => {
+    const gomod = prepareRuntimeTemplate(
+      'go.mod',
+      RUNTIME_TEMPLATES['go.mod']!,
+      'openmeter',
+      'github.com/openmeterio/openmeter/api/v3/client',
+      '0.0.0-dev',
+      '1.24',
+    )
+
+    expect(gomod).toContain('\ngo 1.24\n')
+    expect(gomod).not.toContain('go 1.23')
+    expect(gomod).not.toContain('{{GO_VERSION}}')
+  })
+
+  it('interpolates the module path into resolveVersion and the sdk-version fallback into its return', () => {
+    const option = prepareRuntimeTemplate(
+      'option.go',
+      RUNTIME_TEMPLATES['option.go']!,
+      'openmeter',
+      'github.com/openmeterio/openmeter/api/v3/client',
+      '1.2.3',
+      '1.23',
+    )
+
+    expect(option).toContain('var Version = resolveVersion()')
+    expect(option).toContain('func resolveVersion() string')
+    expect(option).toContain(
+      'dep.Path != "github.com/openmeterio/openmeter/api/v3/client"',
+    )
+    expect(option).toContain('return "1.2.3"')
+    expect(option).not.toContain('{{MODULE_PATH}}')
+    expect(option).not.toContain('{{SDK_VERSION}}')
+  })
+
+  it('falls back to the 0.0.0-dev default sdk-version when the option is omitted', () => {
+    const option = prepareRuntimeTemplate(
+      'option.go',
+      RUNTIME_TEMPLATES['option.go']!,
+      'openmeter',
+      'github.com/openmeterio/openmeter/api/v3/client',
+      '0.0.0-dev',
+      '1.23',
+    )
+
+    expect(option).toContain('return "0.0.0-dev"')
+  })
+
+  it('emits every runtime Go file with the generated header before the package clause', () => {
+    for (const [path, content] of Object.entries(RUNTIME_TEMPLATES)) {
+      if (!path.endsWith('.go')) {
+        continue
+      }
+      const prepared = prepareRuntimeTemplate(
+        path,
+        content,
+        'sdk',
+        'example.com/sdk',
+        '0.0.0-dev',
+        '1.23',
+      )
+      const lines = prepared.split('\n')
+      expect(lines[0], path).toBe(GENERATED_HEADER)
+      expect(lines[1], path).toBe('')
+      expect(prepared, path).toContain('\npackage sdk\n')
+      expect(prepared, path).not.toContain('{{SDK_VERSION}}')
+      expect(prepared, path).not.toContain('{{MODULE_PATH}}')
+    }
+  })
+
+  it('passes non-Go templates through untouched', () => {
+    expect(
+      prepareRuntimeTemplate(
+        'go.sum',
+        RUNTIME_TEMPLATES['go.sum']!,
+        'openmeter',
+        'example.com/sdk',
+        '0.0.0-dev',
+        '1.23',
+      ),
+    ).toBe(RUNTIME_TEMPLATES['go.sum'])
+  })
+
+  it('exposes read accessors and null zero-value docs on OneOrMany', () => {
+    const oneOrMany = RUNTIME_TEMPLATES['one_or_many.go']!
+    expect(oneOrMany).toContain('func (value OneOrMany[T]) AsOne() (*T, bool)')
+    expect(oneOrMany).toContain(
+      'func (value OneOrMany[T]) AsMany() ([]T, bool)',
+    )
+    expect(oneOrMany).toContain('marshals as JSON null')
+  })
+
+  it('keeps spec-derived method names out of the static transport template', () => {
+    const transport = RUNTIME_TEMPLATES['transport.go']!
+    expect(transport).not.toContain('QueryCSVStream')
+    expect(transport).not.toContain('contentTypeCSV')
+  })
+})
+
+describe('doc.go package documentation', () => {
+  it('renders the generated marker detached from the package godoc', () => {
+    const header = packageDocHeader('openmeter')
+    const lines = header.split('\n')
+
+    expect(lines[0]).toBe(GENERATED_HEADER)
+    // The blank separator keeps the marker out of the package documentation.
+    expect(lines[1]).toBe('')
+    expect(lines[2]).toMatch(/^\/\/ Package openmeter provides/)
+    // Every remaining line is comment content, and the trailing newline keeps
+    // the godoc attached to the package clause the source file renders next.
+    expect(header.endsWith('\n')).toBe(true)
+    for (const line of lines.slice(2, -1)) {
+      expect(line).toMatch(/^\/\//)
+    }
+    expect(header).not.toContain('\npackage ')
+
+    for (const topic of ['WithToken', 'APIError', 'errors.As', 'iter.Seq2']) {
+      expect(header).toContain(topic)
+    }
+  })
+})
+
+describe('output cleaning', () => {
+  it('preserves hand-written Go tests and testdata across regeneration', async () => {
+    const removed: string[] = []
+    await cleanOutputDirectory(
+      {
+        readDir: async () => [
+          'client.go',
+          'go.mod',
+          'README.md',
+          'wire_test.go',
+          'testdata',
+        ],
+        rm: async (path: string) => {
+          removed.push(path)
+        },
+      },
+      '/out',
+    )
+
+    expect(removed.sort()).toEqual([
+      '/out/README.md',
+      '/out/client.go',
+      '/out/go.mod',
+    ])
+  })
+
+  it('treats a missing output directory as already clean', async () => {
+    await cleanOutputDirectory(
+      {
+        readDir: async () => {
+          const error = new Error('missing') as NodeJS.ErrnoException
+          error.code = 'ENOENT'
+          throw error
+        },
+        rm: async () => {
+          throw new Error('rm must not run when the directory is missing')
+        },
+      },
+      '/out',
+    )
+  })
+
+  it('surfaces non-ENOENT filesystem errors', async () => {
+    await expect(
+      cleanOutputDirectory(
+        {
+          readDir: async () => {
+            const error = new Error(
+              'permission denied',
+            ) as NodeJS.ErrnoException
+            error.code = 'EACCES'
+            throw error
+          },
+          rm: async () => {},
+        },
+        '/out',
+      ),
+    ).rejects.toThrow('permission denied')
+  })
+})
+
+describe('generated README', () => {
+  async function compileReadme(): Promise<{
+    readme: string
+    methodNames: string[]
+    csvMethodName: string
+  }> {
+    const program = await compileFixture(`
+      @service namespace Test;
+
+      model Item {
+        id: string;
+      }
+
+      @route("/items")
+      interface Operations {
+        @get op list(): Item[];
+
+        @route("/export")
+        @get op exportCsv(): {
+          @header contentType: "text/csv";
+          @body _: string;
+        };
+      }
+    `)
+
+    const operations = collectHttpOperations(program)
+    const described = describeOperations(program, 'Test', operations)
+    const csv = described.find(
+      (operation) => operation.responseContentType === 'text/csv',
+    )!
+    const readme = readmeFile(
+      program,
+      'github.com/openmeterio/openmeter/api/v3/client',
+      'openmeter',
+      [{ root: 'Test', nestPath: [], operations }],
+      new Map(),
+    )
+    return {
+      readme,
+      methodNames: described.map((operation) => operation.methodName),
+      csvMethodName: csv.methodName,
+    }
+  }
+
+  it('shows compiling examples with an om variable and openmeter qualifiers', async () => {
+    const { readme } = await compileReadme()
+
+    expect(readme).toContain('om, err := openmeter.New(')
+    expect(readme).toContain(
+      'om.Meters.Create(ctx, openmeter.CreateMeterRequest{',
+    )
+    expect(readme).toContain('openmeter.MeterListParams{}')
+    // The local variable must not shadow the package qualifier.
+    expect(readme).not.toContain('client, err :=')
+    expect(readme).not.toContain('client.Meters')
+    // Examples target the unified request type names without the Input suffix.
+    expect(readme).not.toContain('CreateMeterRequestInput')
+    expect(readme).not.toContain('MeterQueryRequestInput')
+  })
+
+  it('lists the Stream variant of text-response operations', async () => {
+    const { readme, methodNames, csvMethodName } = await compileReadme()
+
+    for (const methodName of methodNames) {
+      expect(readme).toContain(`\`om.Test.${methodName}\``)
+    }
+    expect(readme).toContain(
+      `\`om.Test.${goExportedName(csvMethodName)}Stream\``,
+    )
+  })
+
+  it('documents opaque cursor tokens and backward-iteration ordering', async () => {
+    const { readme } = await compileReadme()
+
+    expect(readme).toContain('opaque cursor tokens')
+    expect(readme).toContain('`page[after]` / `page[before]`')
+    expect(readme.replace(/\s+/g, ' ')).toContain('not globally sorted')
+    expect(readme).toContain(
+      'om.Meters.QueryCSVStream(ctx, "meter-id", openmeter.MeterQueryRequest{})',
+    )
+  })
+})

api/spec/packages/typespec-go/test/go-types.test.ts

@@ -0,0 +1,100 @@
+import { createTestHost, createTestRunner } from '@typespec/compiler/testing'
+import { describe, expect, it } from 'vitest'
+import { goType } from '../dist/go-types.js'
+import type { Program } from '@typespec/compiler'
+
+async function compileTypes(code: string): Promise<Program> {
+  const host = await createTestHost()
+  const runner = await createTestRunner(host)
+  await runner.compile(code)
+  return runner.program
+}
+
+describe('Go type mapping', () => {
+  it('maps unbounded integer scalars to int64 and keeps sized scalars exact', async () => {
+    const program = await compileTypes(`
+      model Sample {
+        version: integer;
+        quantity: safeint;
+        priority: int16;
+        octet: int8;
+      }
+    `)
+
+    const sample = program.getGlobalNamespaceType().models.get('Sample')!
+    const fieldType = (name: string) =>
+      goType(program, sample.properties.get(name)!.type).type
+
+    expect(fieldType('version')).toBe('int64')
+    expect(fieldType('quantity')).toBe('int64')
+    expect(fieldType('priority')).toBe('int16')
+    expect(fieldType('octet')).toBe('int8')
+  })
+
+  it('maps every known field filter union to its runtime filter type', async () => {
+    const program = await compileTypes(`
+      union StringFieldFilter { equals: string }
+      union StringFieldFilterExact { equals: string }
+      union ULIDFieldFilter { equals: string }
+      union DateTimeFieldFilter { equals: utcDateTime }
+      union NumericFieldFilter { equals: float64 }
+      union BooleanFieldFilter { equals: boolean }
+    `)
+
+    const unions = program.getGlobalNamespaceType().unions
+    const unionType = (name: string) => goType(program, unions.get(name)!).type
+
+    expect(unionType('StringFieldFilter')).toBe('StringFilter')
+    expect(unionType('StringFieldFilterExact')).toBe('StringExactFilter')
+    expect(unionType('ULIDFieldFilter')).toBe('StringExactFilter')
+    expect(unionType('DateTimeFieldFilter')).toBe('DateTimeFilter')
+    expect(unionType('NumericFieldFilter')).toBe('NumericFilter')
+    expect(unionType('BooleanFieldFilter')).toBe('BooleanFilter')
+  })
+
+  it('rejects field filter unions without a runtime filter mapping', async () => {
+    const program = await compileTypes(`
+      union DurationFieldFilter { equals: string }
+    `)
+
+    const union = program
+      .getGlobalNamespaceType()
+      .unions.get('DurationFieldFilter')!
+    expect(() => goType(program, union)).toThrow(
+      'field filter union DurationFieldFilter has no runtime filter type',
+    )
+  })
+
+  it('rejects anonymous unions that mix non-string variants', async () => {
+    const program = await compileTypes(`
+      model Sample {
+        value: int32 | boolean;
+      }
+    `)
+
+    const value = program
+      .getGlobalNamespaceType()
+      .models.get('Sample')!
+      .properties.get('value')!
+    expect(() => goType(program, value.type)).toThrow(
+      'anonymous union of [Scalar, Scalar] is not representable in Go',
+    )
+  })
+
+  it('maps explicit unknown to any but rejects other intrinsics', async () => {
+    const program = await compileTypes(`
+      model Sample {
+        config?: unknown;
+        forbidden?: null;
+      }
+    `)
+
+    const sample = program.getGlobalNamespaceType().models.get('Sample')!
+    expect(goType(program, sample.properties.get('config')!.type).type).toBe(
+      'any',
+    )
+    expect(() =>
+      goType(program, sample.properties.get('forbidden')!.type),
+    ).toThrow('intrinsic type null is not representable in Go')
+  })
+})

api/spec/packages/typespec-go/test/operations.test.ts

@@ -0,0 +1,586 @@
+import type { Model, Program } from '@typespec/compiler'
+import { createTestHost, createTestRunner } from '@typespec/compiler/testing'
+import { HttpTestLibrary } from '@typespec/http/testing'
+import { OpenAPITestLibrary } from '@typespec/openapi/testing'
+import { describe, expect, it } from 'vitest'
+import {
+  collectHttpOperations,
+  describeOperations,
+  jsonBodyOverrides,
+  type GoOperation,
+} from '../dist/operations.js'
+import { groupOperations, operationNestPath } from '../dist/grouping.js'
+import { computeDivergentTypes } from '../dist/projections.js'
+import { validateUniqueTypeNames } from '../dist/emitter.js'
+import { isRuntimeBackedTypeName } from '../dist/runtime-symbols.js'
+import {
+  configureGoTypeNames,
+  optionalTypeName,
+  resolveGoTypeNames,
+} from '../dist/go-types.js'
+
+async function compileProgram(code: string): Promise<Program> {
+  const host = await createTestHost({
+    libraries: [HttpTestLibrary, OpenAPITestLibrary],
+  })
+  const runner = await createTestRunner(host)
+  await runner.compile(`
+    import "@typespec/http";
+    import "@typespec/openapi";
+    using TypeSpec.Http;
+    using TypeSpec.OpenAPI;
+    ${code}
+  `)
+
+  return runner.program
+}
+
+async function compileOperations(code: string): Promise<GoOperation[]> {
+  const program = await compileProgram(code)
+  const operations = collectHttpOperations(program)
+  return describeOperations(program, 'Test', operations)
+}
+
+describe('operation HTTP IR', () => {
+  it('classifies every supported query encoding from HTTP metadata', async () => {
+    const operations = await compileOperations(`
+      @service namespace Test;
+
+      namespace Common {
+        model SortQuery {
+          by: string;
+          order?: "asc" | "desc";
+        }
+      }
+
+      model ItemFilter {
+        key?: string;
+      }
+
+      @route("/items")
+      interface Operations {
+        @get
+        op list(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+          @query sort?: Common.SortQuery,
+          @query(#{ style: "deepObject", explode: true }) filter?: ItemFilter,
+          @query(#{ explode: true }) expand?: string[],
+          @query timestamp?: utcDateTime,
+        ): string[];
+
+        @get
+        @route("/cursor")
+        op cursor(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            after?: string;
+            before?: string;
+          },
+        ): string[];
+      }
+    `)
+
+    const list = operations.find(
+      (operation) => operation.operation.name === 'list',
+    )!
+    expect(
+      Object.fromEntries(
+        list.queryParams.map((parameter) => [
+          parameter.name,
+          parameter.queryCodec,
+        ]),
+      ),
+    ).toMatchObject({
+      page: { kind: 'page' },
+      sort: { kind: 'sort' },
+      filter: { kind: 'deepObject' },
+      expand: { kind: 'array', explode: true },
+      timestamp: { kind: 'scalar' },
+    })
+    expect(list.pagination).toBe('page')
+
+    const cursor = operations.find(
+      (operation) => operation.operation.name === 'cursor',
+    )!
+    expect(cursor.queryParams[0]?.queryCodec).toEqual({
+      kind: 'cursorPage',
+    })
+    expect(cursor.pagination).toBe('cursor')
+  })
+
+  it('retains optional body and media-type metadata', async () => {
+    const operations = await compileOperations(`
+      @service namespace Test;
+
+      model Request {
+        value: string;
+      }
+
+      model Response {
+        value: string;
+      }
+
+      @route("/items")
+      interface Operations {
+        @post
+        op create(@body body?: Request): Response;
+      }
+    `)
+
+    expect(operations).toHaveLength(1)
+    expect(operations[0]).toMatchObject({
+      bodyOptional: true,
+      requestContentType: 'application/json',
+      responseContentType: 'application/json',
+    })
+  })
+
+  it('retains shared-route media-type variants as distinct methods', async () => {
+    const operations = await compileOperations(`
+      @service namespace Test;
+
+      model Event {
+        id: string;
+      }
+
+      model Response {
+        accepted: boolean;
+      }
+
+      @route("/events")
+      interface Operations {
+        @post
+        @operationId("ingest-metering-events")
+        @sharedRoute
+        ingestEvent(
+          @header contentType: "application/cloudevents+json",
+          @body body: Event,
+        ): Response;
+
+        @post
+        @operationId("ingest-metering-events")
+        @sharedRoute
+        ingestEvents(
+          @header contentType: "application/cloudevents-batch+json",
+          @body body: Event[],
+        ): Response;
+
+        @post
+        @operationId("ingest-metering-events")
+        @sharedRoute
+        ingestEventsJson(
+          @header contentType: "application/json",
+          @body body: Event | Event[],
+        ): Response;
+      }
+    `)
+
+    expect(operations.map((operation) => operation.methodName)).toEqual([
+      'IngestEvent',
+      'IngestEvents',
+      'IngestEventsJSON',
+    ])
+    expect(operations.map((operation) => operation.requestContentType)).toEqual(
+      [
+        'application/cloudevents+json',
+        'application/cloudevents-batch+json',
+        'application/json',
+      ],
+    )
+    expect(operations.map((operation) => operation.body?.kind)).toEqual([
+      'Model',
+      'Model',
+      'Union',
+    ])
+  })
+
+  it('rejects operations that cannot be traced to a resource namespace', async () => {
+    const program = await compileProgram(`
+      @service namespace Test;
+
+      @route("/items")
+      interface Operations {
+        @get op list(): string[];
+      }
+    `)
+
+    const operations = collectHttpOperations(program)
+    expect(() => groupOperations(operations)).toThrow(
+      'cannot place operation Operations.list',
+    )
+  })
+
+  it('groups operations by the namespace of their source interface', async () => {
+    const program = await compileProgram(`
+      namespace Widgets {
+        interface Operations {
+          @get op list(): string[];
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/widgets")
+        interface Endpoints extends Widgets.Operations {}
+      }
+    `)
+
+    const operations = collectHttpOperations(program)
+    expect([...groupOperations(operations).keys()]).toEqual(['Widgets'])
+  })
+
+  it('keeps same-named operations in different containers from sharing bodies', async () => {
+    const program = await compileProgram(`
+      @service namespace Test;
+
+      model Payload {
+        value: string;
+      }
+
+      @route("/widgets")
+      interface Widgets {
+        @get op list(): string[];
+      }
+
+      @route("/gadgets")
+      interface Gadgets {
+        @post op list(@body body: Payload): string[];
+      }
+    `)
+
+    const overrides = jsonBodyOverrides(program)
+    expect(overrides.size).toBe(0)
+
+    const operations = describeOperations(
+      program,
+      'Test',
+      collectHttpOperations(program),
+      overrides,
+    )
+    const widgetsList = operations.find(
+      (operation) => operation.path === '/widgets',
+    )!
+    expect(widgetsList.body).toBeUndefined()
+    const gadgetsList = operations.find(
+      (operation) => operation.path === '/gadgets',
+    )!
+    expect((gadgetsList.body as Model | undefined)?.name).toBe('Payload')
+  })
+
+  it('attaches the shared-route JSON body to bodyless siblings by qualified key', async () => {
+    const program = await compileProgram(`
+      @service namespace Test;
+
+      model QueryRequest {
+        value: string;
+      }
+
+      model QueryResult {
+        value: string;
+      }
+
+      @route("/query")
+      interface Operations {
+        @post
+        @operationId("query-thing")
+        @sharedRoute
+        query(@body request: QueryRequest): {
+          @header contentType: "application/json";
+          @body _: QueryResult;
+        };
+
+        @friendlyName("queryThingCsv")
+        @post
+        @operationId("query-thing")
+        @sharedRoute
+        queryCsv(): {
+          @header contentType: "text/csv";
+          @body _: string;
+        };
+      }
+    `)
+
+    const overrides = jsonBodyOverrides(program)
+    expect([...overrides.keys()]).toEqual(['Test.Operations.queryCsv'])
+
+    const operations = describeOperations(
+      program,
+      'Test',
+      collectHttpOperations(program),
+      overrides,
+    )
+    const csv = operations.find(
+      (operation) => operation.operation.name === 'queryCsv',
+    )!
+    expect(csv.requestContentType).toBe('application/json')
+    expect((csv.body as Model | undefined)?.name).toBe('QueryRequest')
+  })
+
+  it('rejects multiple 2xx response bodies with different types', async () => {
+    await expect(
+      compileOperations(`
+        @service namespace Test;
+
+        model Created {
+          id: string;
+        }
+
+        model Accepted {
+          token: string;
+        }
+
+        @route("/items")
+        interface Operations {
+          @post op create(): {
+            @statusCode _: 201;
+            @body body: Created;
+          } | {
+            @statusCode _: 202;
+            @body body: Accepted;
+          };
+        }
+      `),
+    ).rejects.toThrow('multiple 2xx response bodies with different types')
+  })
+
+  it('accepts multiple 2xx responses sharing one body type', async () => {
+    const operations = await compileOperations(`
+      @service namespace Test;
+
+      model Created {
+        id: string;
+      }
+
+      @route("/items")
+      interface Operations {
+        @post op create(): {
+          @statusCode _: 200;
+          @body body: Created;
+        } | {
+          @statusCode _: 201;
+          @body body: Created;
+        };
+      }
+    `)
+
+    expect(operations[0]?.response?.kind).toBe('Model')
+  })
+
+  it('rejects page parameters that match no pagination shape', async () => {
+    await expect(
+      compileOperations(`
+        @service namespace Test;
+
+        @route("/items")
+        interface Operations {
+          @get op list(
+            @query(#{ style: "deepObject", explode: true })
+            page?: {
+              size?: integer;
+              after?: string;
+              tenant?: string;
+            },
+          ): string[];
+        }
+      `),
+    ).rejects.toThrow('query parameter page on list')
+
+    await expect(
+      compileOperations(`
+        @service namespace Test;
+
+        @route("/items")
+        interface Operations {
+          @get op list(
+            @query(#{ style: "deepObject", explode: true })
+            page?: {
+              size?: integer;
+            },
+          ): string[];
+        }
+      `),
+    ).rejects.toThrow('query parameter page on list')
+  })
+
+  it('keeps pagination-shaped models under other names as deep objects', async () => {
+    const operations = await compileOperations(`
+      @service namespace Test;
+
+      @route("/items")
+      interface Operations {
+        @get op list(
+          @query(#{ style: "deepObject", explode: true })
+          filter?: {
+            size?: integer;
+            after?: string;
+          },
+        ): string[];
+      }
+    `)
+
+    expect(operations[0]?.queryParams[0]?.queryCodec).toMatchObject({
+      kind: 'deepObject',
+    })
+    expect(operations[0]?.pagination).toBeUndefined()
+  })
+
+  it('rejects caller-controlled headers until a header codec exists', async () => {
+    await expect(
+      compileOperations(`
+        @service namespace Test;
+
+        @route("/items")
+        interface Operations {
+          @get
+          op get(@header requestId?: string): string;
+        }
+      `),
+    ).rejects.toThrow(
+      'typespec-go: unsupported header parameter request-id on get',
+    )
+  })
+
+  it('derives nested service paths from the source namespace', async () => {
+    const host = await createTestHost({ libraries: [HttpTestLibrary] })
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      import "@typespec/http";
+      using TypeSpec.Http;
+
+      namespace Customers.Credits.Grants {
+        interface Operations {
+          @get op list(): string[];
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/grants")
+        interface Endpoints extends Customers.Credits.Grants.Operations {}
+      }
+    `)
+
+    const [operation] = collectHttpOperations(runner.program)
+    expect(operationNestPath(operation!, 'Customers')).toEqual([
+      'Credits',
+      'Grants',
+    ])
+  })
+
+  it('marks defaulted both-reachable models and their parents as divergent', async () => {
+    const host = await createTestHost()
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      model Child {
+        mode: string = "default";
+      }
+      model Parent {
+        child: Child;
+      }
+    `)
+
+    const global = runner.program.getGlobalNamespaceType()
+    const child = global.models.get('Child')!
+    const parent = global.models.get('Parent')!
+    const both = new Set([parent, child])
+    const divergent = computeDivergentTypes(runner.program, both, both)
+
+    expect(divergent.has(child)).toBe(true)
+    expect(divergent.has(parent)).toBe(true)
+  })
+
+  it('marks optional collection both-reachable models as divergent', async () => {
+    const host = await createTestHost()
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      model Request {
+        labels?: Record<string>;
+        features?: string[];
+      }
+    `)
+
+    const global = runner.program.getGlobalNamespaceType()
+    const request = global.models.get('Request')!
+    const both = new Set([request])
+    const divergent = computeDivergentTypes(runner.program, both, both)
+
+    expect(divergent.has(request)).toBe(true)
+  })
+
+  it('keeps request-only models out of the divergent set', async () => {
+    const host = await createTestHost()
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      model Request {
+        labels?: Record<string>;
+      }
+    `)
+
+    const global = runner.program.getGlobalNamespaceType()
+    const request = global.models.get('Request')!
+    const divergent = computeDivergentTypes(
+      runner.program,
+      new Set(),
+      new Set([request]),
+    )
+
+    expect(divergent.size).toBe(0)
+  })
+
+  it('rejects generated type names that collide with reserved runtime symbols', async () => {
+    const host = await createTestHost()
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      model APIError {
+        title: string;
+      }
+    `)
+
+    const apiError = runner.program
+      .getGlobalNamespaceType()
+      .models.get('APIError')!
+
+    expect(() =>
+      validateUniqueTypeNames(runner.program, new Set([apiError])),
+    ).toThrow('reserved SDK runtime symbol APIError')
+  })
+
+  it('treats SortQuery as a runtime-backed query helper instead of a generated model', () => {
+    expect(isRuntimeBackedTypeName('SortQuery', 'Model')).toBe(true)
+  })
+
+  it('strips configured Go type-name prefixes only when unambiguous', async () => {
+    const host = await createTestHost()
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      model BillingWidget {
+        value: string;
+      }
+
+      model MeteringPlan {
+        value: string;
+      }
+
+      model Plan {
+        value: string;
+      }
+    `)
+
+    const global = runner.program.getGlobalNamespaceType()
+    const billingWidget = global.models.get('BillingWidget')!
+    const meteringPlan = global.models.get('MeteringPlan')!
+    const plan = global.models.get('Plan')!
+
+    configureGoTypeNames(runner.program, ['Billing', 'Metering'])
+    resolveGoTypeNames(runner.program, [billingWidget, meteringPlan, plan])
+
+    expect(optionalTypeName(runner.program, billingWidget)).toBe('Widget')
+    expect(optionalTypeName(runner.program, meteringPlan)).toBe('MeteringPlan')
+    expect(optionalTypeName(runner.program, plan)).toBe('Plan')
+  })
+})

api/spec/packages/typespec-go/test/projections.test.ts

@@ -0,0 +1,504 @@
+import type { Model, Program, Type, Union } from '@typespec/compiler'
+import { createTestHost, createTestRunner } from '@typespec/compiler/testing'
+import { HttpTestLibrary } from '@typespec/http/testing'
+import { OpenAPITestLibrary } from '@typespec/openapi/testing'
+import { describe, expect, it } from 'vitest'
+import {
+  configureGoProjections,
+  configureGoTypeNames,
+  goFields,
+  goType,
+  optionalTypeName,
+  resolveGoTypeNames,
+  setSyntheticTypeNames,
+  type GoProjections,
+} from '../dist/go-types.js'
+import { collectHttpOperations, jsonBodyOverrides } from '../dist/operations.js'
+import { groupOperations } from '../dist/grouping.js'
+import {
+  computeDivergentTypes,
+  computeReachability,
+  computeStructuralAliases,
+  planDeclarations,
+  promoteAnonymousModels,
+} from '../dist/projections.js'
+import { renderUnion } from '../dist/components/GoModels.js'
+
+interface PlannedProgram {
+  program: Program
+  projections: GoProjections
+  modelTypes: Set<Type>
+  namedType: (name: string) => Type
+}
+
+/** Mirrors the emitter's planning phase: reachability, name resolution,
+ * anonymous-model promotion, divergence, declaration planning, and structural
+ * dedupe, then configures the live registry the render components consult. */
+async function planFixture(code: string): Promise<PlannedProgram> {
+  const host = await createTestHost({
+    libraries: [HttpTestLibrary, OpenAPITestLibrary],
+  })
+  const runner = await createTestRunner(host)
+  await runner.compile(`
+    import "@typespec/http";
+    import "@typespec/openapi";
+    using TypeSpec.Http;
+    using TypeSpec.OpenAPI;
+    ${code}
+  `)
+  const program = runner.program
+  configureGoTypeNames(program, [])
+  const operations = collectHttpOperations(program)
+  const groups = groupOperations(operations)
+  const bodyOverrides = jsonBodyOverrides(program)
+  const reachability = computeReachability(program, groups, bodyOverrides)
+  const modelTypes = new Set(
+    [...reachability.byResource.values()].flatMap((types) => [...types]),
+  )
+  resolveGoTypeNames(program, modelTypes)
+  setSyntheticTypeNames(program, promoteAnonymousModels(program, modelTypes))
+  const divergent = computeDivergentTypes(
+    program,
+    reachability.readReachable,
+    reachability.inputReachable,
+  )
+  const declarations = planDeclarations(
+    program,
+    modelTypes,
+    reachability.readReachable,
+    reachability.inputReachable,
+    divergent,
+  )
+  const aliases = computeStructuralAliases(
+    program,
+    declarations,
+    reachability.readReachable,
+    divergent,
+  )
+  const projections: GoProjections = {
+    readReachable: reachability.readReachable,
+    inputReachable: reachability.inputReachable,
+    divergent,
+    aliases,
+    declarations,
+  }
+  configureGoProjections(program, projections)
+
+  const namedType = (name: string): Type => {
+    const match = [...modelTypes].find(
+      (type) => optionalTypeName(program, type) === name,
+    )
+    if (!match) {
+      throw new Error(`fixture type ${name} not reachable`)
+    }
+    return match
+  }
+
+  return { program, projections, modelTypes, namedType }
+}
+
+const declarationNames = (projections: GoProjections): string[] =>
+  [...projections.declarations.values()]
+    .flatMap((declarations) => declarations.map(({ name }) => name))
+    .sort()
+
+describe('payload-context visibility', () => {
+  it('drops create/update-only properties from response-reachable models', async () => {
+    const { program, projections, namedType } = await planFixture(`
+      model App {
+        name: string;
+
+        @visibility(Lifecycle.Read)
+        masked_api_key: string;
+
+        @visibility(Lifecycle.Create, Lifecycle.Update)
+        @secret
+        secret_api_key?: string;
+      }
+
+      namespace Apps {
+        interface Operations {
+          @get op get(): App;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/apps")
+        interface Endpoints extends Apps.Operations {}
+      }
+    `)
+
+    const app = namedType('App') as Model
+    expect(projections.declarations.get(app)).toEqual([
+      { name: 'App', mode: 'read' },
+    ])
+    const fieldNames = goFields(program, app).map((field) => field.name)
+    expect(fieldNames).toEqual(['Name', 'MaskedAPIKey'])
+    // The input rendering of the same model keeps the spec-projected fields.
+    const inputNames = goFields(program, app, { mode: 'input' }).map(
+      (field) => field.name,
+    )
+    expect(inputNames).toContain('SecretAPIKey')
+  })
+})
+
+describe('request-type unification', () => {
+  it('emits request-only models once, as the input projection under the natural name', async () => {
+    const { program, projections, namedType } = await planFixture(`
+      model CreateMeterRequest {
+        name: string;
+        labels?: Record<string>;
+      }
+
+      model Meter {
+        id: string;
+        name: string;
+      }
+
+      namespace Meters {
+        interface Operations {
+          @post op create(@body body: CreateMeterRequest): Meter;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/meters")
+        interface Endpoints extends Meters.Operations {}
+      }
+    `)
+
+    const request = namedType('CreateMeterRequest') as Model
+    expect(projections.declarations.get(request)).toEqual([
+      { name: 'CreateMeterRequest', mode: 'input' },
+    ])
+    expect(declarationNames(projections)).not.toContain(
+      'CreateMeterRequestInput',
+    )
+    // The single emission uses input semantics: the optional collection is
+    // pointered so an explicitly empty map survives omitempty.
+    const labels = goFields(program, request, { mode: 'input' }).find(
+      (field) => field.name === 'Labels',
+    )
+    expect(labels?.typeText).toBe('*map[string]string')
+  })
+
+  it('keeps distinct read and input declarations for dual-reachable divergent models', async () => {
+    const { program, projections, namedType } = await planFixture(`
+      model Event {
+        id: string;
+        specversion: string = "1.0";
+      }
+
+      model IngestedEvent {
+        event: Event;
+      }
+
+      namespace Events {
+        interface Operations {
+          @post op ingest(@body body: Event): void;
+          @get op get(): IngestedEvent;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/events")
+        interface Endpoints extends Events.Operations {}
+      }
+    `)
+
+    const event = namedType('Event')
+    expect(projections.divergent.has(event)).toBe(true)
+    expect(projections.declarations.get(event)).toEqual([
+      { name: 'Event', mode: 'read' },
+      { name: 'EventInput', mode: 'input' },
+    ])
+    // Request-side references resolve to the input twin, read side to Event.
+    expect(goType(program, event, { mode: 'input' }).type).toBe('EventInput')
+    expect(goType(program, event).type).toBe('Event')
+  })
+
+  it('does not diverge dual-reachable models whose only default sits on an optional property', async () => {
+    // fieldShape keeps an already-optional property optional in both modes,
+    // so an optional-with-default property renders byte-identically and must
+    // not spawn a spurious *Input twin.
+    const { program, projections, namedType } = await planFixture(`
+      model Profile {
+        id: string;
+        interval?: string = "PT1H";
+      }
+
+      namespace Profiles {
+        interface Operations {
+          @post op create(@body body: Profile): Profile;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/profiles")
+        interface Endpoints extends Profiles.Operations {}
+      }
+    `)
+
+    const profile = namedType('Profile')
+    expect(projections.divergent.has(profile)).toBe(false)
+    expect(declarationNames(projections)).not.toContain('ProfileInput')
+    expect(goType(program, profile, { mode: 'input' }).type).toBe('Profile')
+  })
+})
+
+describe('structural dedupe of visibility projections', () => {
+  it('collapses identical projection twins onto the canonical types', async () => {
+    const { program, projections, namedType } = await planFixture(`
+      model Address {
+        // Visible in both lifecycles: the Update copy filters nothing away and
+        // stays byte-identical to the canonical model.
+        @visibility(Lifecycle.Read, Lifecycle.Update)
+        country?: string;
+      }
+
+      model Doc {
+        address: Address;
+      }
+
+      model UpdateDoc
+        is FilterVisibility<Doc, #{ all: #[Lifecycle.Update] }, "Update{name}">;
+
+      namespace Docs {
+        interface Operations {
+          @get op get(): Doc;
+          @patch(#{ implicitOptionality: false }) op update(@body body: UpdateDoc): Doc;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/docs")
+        interface Endpoints extends Docs.Operations {}
+      }
+    `)
+
+    // The Update copies are byte-identical to the canonical read models, so
+    // both the root and the nested reference pair collapse.
+    expect(projections.aliases.get('UpdateDoc')).toBe('Doc')
+    expect(projections.aliases.get('UpdateAddress')).toBe('Address')
+    const names = declarationNames(projections)
+    expect(names).not.toContain('UpdateDoc')
+    expect(names).not.toContain('UpdateAddress')
+
+    const updateDoc = namedType('UpdateDoc')
+    expect(goType(program, updateDoc, { mode: 'input' }).type).toBe('Doc')
+  })
+
+  it('keeps projection twins whose filtered shape genuinely differs', async () => {
+    const { projections } = await planFixture(`
+      model Doc {
+        name: string;
+
+        @visibility(Lifecycle.Read)
+        etag: string;
+      }
+
+      model UpdateDoc
+        is FilterVisibility<Doc, #{ all: #[Lifecycle.Update] }, "Update{name}">;
+
+      namespace Docs {
+        interface Operations {
+          @get op get(): Doc;
+          @patch(#{ implicitOptionality: false }) op update(@body body: UpdateDoc): Doc;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/docs")
+        interface Endpoints extends Docs.Operations {}
+      }
+    `)
+
+    expect(projections.aliases.size).toBe(0)
+    expect(declarationNames(projections)).toContain('UpdateDoc')
+  })
+})
+
+describe('anonymous model promotion', () => {
+  it('promotes anonymous inline models to enclosing-type-plus-field names', async () => {
+    const { program, namedType, projections } = await planFixture(`
+      model SubscriptionCreate {
+        customer: {
+          id?: string;
+          key?: string;
+        };
+      }
+
+      namespace Subscriptions {
+        interface Operations {
+          @post op create(@body body: SubscriptionCreate): void;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/subscriptions")
+        interface Endpoints extends Subscriptions.Operations {}
+      }
+    `)
+
+    expect(declarationNames(projections)).toContain(
+      'SubscriptionCreateCustomer',
+    )
+    const create = namedType('SubscriptionCreate') as Model
+    const customer = goFields(program, create, { mode: 'input' }).find(
+      (field) => field.name === 'Customer',
+    )
+    expect(customer?.typeText).toBe('SubscriptionCreateCustomer')
+  })
+
+  it('fails loudly when a promoted name collides with an existing type', async () => {
+    const host = await createTestHost({
+      libraries: [HttpTestLibrary, OpenAPITestLibrary],
+    })
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      import "@typespec/http";
+      import "@typespec/openapi";
+      using TypeSpec.Http;
+      using TypeSpec.OpenAPI;
+
+      model WidgetOwner {
+        name: string;
+      }
+
+      model Widget {
+        owner: {
+          id: string;
+        };
+        fallback: WidgetOwner;
+      }
+
+      namespace Widgets {
+        interface Operations {
+          @get op get(): Widget;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/widgets")
+        interface Endpoints extends Widgets.Operations {}
+      }
+    `)
+    const program = runner.program
+    configureGoTypeNames(program, [])
+    const operations = collectHttpOperations(program)
+    const reachability = computeReachability(
+      program,
+      groupOperations(operations),
+      jsonBodyOverrides(program),
+    )
+    const modelTypes = new Set(
+      [...reachability.byResource.values()].flatMap((types) => [...types]),
+    )
+    resolveGoTypeNames(program, modelTypes)
+
+    expect(() => promoteAnonymousModels(program, modelTypes)).toThrow(
+      'promoted anonymous model name WidgetOwner collides',
+    )
+  })
+})
+
+describe('scalar alias pruning', () => {
+  it('plans no declarations for spec scalars and keeps fields on Go primitives', async () => {
+    const { program, projections, namedType } = await planFixture(`
+      scalar ResourceKey extends string;
+
+      model Meter {
+        key: ResourceKey;
+      }
+
+      namespace Meters {
+        interface Operations {
+          @get op get(): Meter;
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/meters")
+        interface Endpoints extends Meters.Operations {}
+      }
+    `)
+
+    expect(declarationNames(projections)).toEqual(['Meter'])
+    const meter = namedType('Meter') as Model
+    const key = goFields(program, meter).find((field) => field.name === 'Key')
+    expect(key?.typeText).toBe('string')
+  })
+})
+
+describe('union rendering guards', () => {
+  it('throws for named unions with no concrete variants instead of emitting any', async () => {
+    const host = await createTestHost({
+      libraries: [HttpTestLibrary, OpenAPITestLibrary],
+    })
+    const runner = await createTestRunner(host)
+    await runner.compile(`
+      union Broken {
+        nothing: null,
+      }
+    `)
+    const program = runner.program
+    configureGoTypeNames(program, [])
+    const union = program.getGlobalNamespaceType().unions.get('Broken')!
+    resolveGoTypeNames(program, [union])
+
+    expect(() =>
+      renderUnion(program, union as Union, { name: 'Broken', mode: 'read' }),
+    ).toThrow('union Broken has no concrete variants representable in Go')
+  })
+})
+
+describe('filter reachability', () => {
+  it('does not promote object variants of runtime-backed filter unions', async () => {
+    // Runtime-backed filter unions render as static runtime types
+    // (StringFilter, ...); their anonymous object variants must not leak into
+    // the reachable set and get emitted as dead *Object declarations.
+    const { projections } = await planFixture(`
+      union StringFieldFilter {
+        equals: string,
+        object: {
+          eq?: string,
+        },
+      }
+
+      model ItemFilter {
+        name?: StringFieldFilter;
+      }
+
+      model Item {
+        id: string;
+      }
+
+      namespace Items {
+        interface Operations {
+          @get op list(
+            @query(#{ style: "deepObject", explode: true }) filter?: ItemFilter,
+          ): Item[];
+        }
+      }
+
+      @service
+      namespace Test {
+        @route("/items")
+        interface Endpoints extends Items.Operations {}
+      }
+    `)
+
+    const names = declarationNames(projections)
+    expect(names).toContain('Item')
+    expect(names.some((name) => name.endsWith('FieldFilterObject'))).toBe(false)
+  })
+})

api/spec/packages/typespec-go/test/resource-render.test.ts

@@ -0,0 +1,324 @@
+import { createTestHost, createTestRunner } from '@typespec/compiler/testing'
+import { HttpTestLibrary } from '@typespec/http/testing'
+import { OpenAPITestLibrary } from '@typespec/openapi/testing'
+import { describe, expect, it } from 'vitest'
+import type { Program } from '@typespec/compiler'
+import {
+  collectHttpOperations,
+  describeOperations,
+  type GoOperation,
+} from '../dist/operations.js'
+import {
+  deepObjectName,
+  isPlainPageEnvelope,
+  localName,
+  queryScalarValue,
+  resolveListParamsNames,
+} from '../dist/components/GoResource.js'
+
+async function compileResource(
+  code: string,
+): Promise<{ program: Program; operations: GoOperation[] }> {
+  const host = await createTestHost({
+    libraries: [HttpTestLibrary, OpenAPITestLibrary],
+  })
+  const runner = await createTestRunner(host)
+  await runner.compile(`
+    import "@typespec/http";
+    import "@typespec/openapi";
+    using TypeSpec.Http;
+    using TypeSpec.OpenAPI;
+    ${code}
+  `)
+
+  const operations = collectHttpOperations(runner.program)
+  return {
+    program: runner.program,
+    operations: describeOperations(runner.program, 'Test', operations),
+  }
+}
+
+function operationNamed(operations: GoOperation[], name: string): GoOperation {
+  const operation = operations.find(
+    (candidate) => candidate.operation.name === name,
+  )
+  if (!operation) {
+    throw new Error(`missing operation ${name} in fixture`)
+  }
+  return operation
+}
+
+const pageFixturePreamble = `
+  @service namespace Test;
+
+  namespace Common {
+    model SortQuery {
+      by: string;
+      order?: "asc" | "desc";
+    }
+  }
+
+  model Item {
+    id: string;
+  }
+
+  model ItemPageMeta {
+    total: int32;
+  }
+
+  model ItemPage {
+    data: Item[];
+    meta: ItemPageMeta;
+  }
+`
+
+describe('list params struct naming', () => {
+  it('splits shared-element params structs when query shapes differ', async () => {
+    const { program, operations } = await compileResource(`
+      ${pageFixturePreamble}
+
+      @route("/items")
+      interface Operations {
+        @get
+        @operationId("list-items")
+        op listItems(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+          @query sort?: Common.SortQuery,
+        ): ItemPage;
+
+        @get
+        @route("/archived")
+        @operationId("list-archived-items")
+        op listArchived(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): ItemPage;
+      }
+    `)
+
+    const names = resolveListParamsNames(program, operations)
+    expect(names.get(operationNamed(operations, 'listItems'))).toBe(
+      'ListItemsParams',
+    )
+    expect(names.get(operationNamed(operations, 'listArchived'))).toBe(
+      'ListArchivedItemsParams',
+    )
+
+    // The outcome must not depend on which operation is discovered first.
+    const reversed = resolveListParamsNames(program, [...operations].reverse())
+    expect(reversed.get(operationNamed(operations, 'listItems'))).toBe(
+      'ListItemsParams',
+    )
+    expect(reversed.get(operationNamed(operations, 'listArchived'))).toBe(
+      'ListArchivedItemsParams',
+    )
+  })
+
+  it('shares one element-named params struct when query shapes match', async () => {
+    const { program, operations } = await compileResource(`
+      ${pageFixturePreamble}
+
+      @route("/items")
+      interface Operations {
+        @get
+        @operationId("list-items")
+        op listItems(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): ItemPage;
+
+        @get
+        @route("/archived")
+        @operationId("list-archived-items")
+        op listArchived(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): ItemPage;
+      }
+    `)
+
+    const names = resolveListParamsNames(program, operations)
+    expect(names.get(operationNamed(operations, 'listItems'))).toBe(
+      'ItemListParams',
+    )
+    expect(names.get(operationNamed(operations, 'listArchived'))).toBe(
+      'ItemListParams',
+    )
+  })
+})
+
+describe('All iterator emission rule', () => {
+  it('accepts only the plain {data, meta} page envelope', async () => {
+    const { program, operations } = await compileResource(`
+      ${pageFixturePreamble}
+
+      model QueryPage {
+        data: Item[];
+        meta: ItemPageMeta;
+        errors: string[];
+      }
+
+      model StatusItemPage {
+        @statusCode _: 200;
+        data: Item[];
+        meta: ItemPageMeta;
+      }
+
+      @route("/items")
+      interface Operations {
+        @get
+        @operationId("list-plain")
+        op listPlain(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): ItemPage;
+
+        @get
+        @route("/query")
+        @operationId("list-partial")
+        op listPartial(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): QueryPage;
+
+        @get
+        @route("/status")
+        @operationId("list-status")
+        op listStatus(
+          @query(#{ style: "deepObject", explode: true })
+          page?: {
+            size?: integer;
+            number?: integer;
+          },
+        ): StatusItemPage;
+      }
+    `)
+
+    const plain = operationNamed(operations, 'listPlain')
+    expect(plain.pagination).toBe('page')
+    expect(isPlainPageEnvelope(program, plain.response)).toBe(true)
+
+    // A paginated response carrying extra fields (partial-failure errors) must
+    // not get an All iterator that would silently drop them.
+    const partial = operationNamed(operations, 'listPartial')
+    expect(partial.pagination).toBe('page')
+    expect(isPlainPageEnvelope(program, partial.response)).toBe(false)
+
+    // HTTP metadata properties (status code, headers) do not count as payload.
+    const status = operationNamed(operations, 'listStatus')
+    expect(isPlainPageEnvelope(program, status.response)).toBe(true)
+
+    expect(isPlainPageEnvelope(program, undefined)).toBe(false)
+  })
+})
+
+describe('path parameter local names', () => {
+  it('lowercases whole-acronym parameters', () => {
+    expect(localName('id')).toBe('id')
+    expect(localName('ulid')).toBe('ulid')
+  })
+
+  it('keeps mixed-word casing intact', () => {
+    expect(localName('customerId')).toBe('customerID')
+    expect(localName('priceId')).toBe('priceID')
+    expect(localName('llmModel')).toBe('llmModel')
+  })
+
+  it('renames parameters colliding with generated method locals', () => {
+    expect(localName('request')).toBe('requestParam')
+    expect(localName('path')).toBe('pathParam')
+    expect(localName('params')).toBe('paramsParam')
+    expect(localName('page')).toBe('pageParam')
+    expect(localName('s')).toBe('sParam')
+  })
+})
+
+describe('query rendering helpers', () => {
+  it('strips the Params suffix from deep-object type names', async () => {
+    const { operations } = await compileResource(`
+      @service namespace Test;
+
+      model ItemFilter {
+        key?: string;
+      }
+
+      @route("/items")
+      interface Operations {
+        @get
+        op list(
+          @query(#{ style: "deepObject", explode: true }) filter?: ItemFilter,
+          @query(#{ style: "deepObject", explode: true }) options?: ItemFilter,
+        ): string[];
+      }
+    `)
+
+    const list = operationNamed(operations, 'list')
+    const filter = list.queryParams.find(
+      (parameter) => parameter.name === 'filter',
+    )!
+    const options = list.queryParams.find(
+      (parameter) => parameter.name === 'options',
+    )!
+
+    expect(deepObjectName('ItemListParams', filter)).toBe('ItemFilter')
+    expect(deepObjectName('GetCustomerCreditBalanceParams', filter)).toBe(
+      'GetCustomerCreditBalanceFilter',
+    )
+    expect(deepObjectName('ItemListParams', options)).toBe('ItemListOptions')
+  })
+
+  it('omits no-op query scalar conversions', async () => {
+    const { program, operations } = await compileResource(`
+      @service namespace Test;
+
+      enum Color {
+        red,
+        green,
+      }
+
+      @route("/items")
+      interface Operations {
+        @get
+        op list(
+          @query code?: string,
+          @query color?: Color,
+        ): string[];
+      }
+    `)
+
+    const list = operationNamed(operations, 'list')
+    const code = list.queryParams.find(
+      (parameter) => parameter.name === 'code',
+    )!
+    const color = list.queryParams.find(
+      (parameter) => parameter.name === 'color',
+    )!
+
+    // A Go string needs no conversion (and never doubled parentheses).
+    expect(queryScalarValue(program, code.type, '*p.Code')).toBe('*p.Code')
+    expect(queryScalarValue(program, code.type, 'value')).toBe('value')
+    // Named string-like types still convert, with single parentheses.
+    expect(queryScalarValue(program, color.type, '*p.Color')).toBe(
+      'string(*p.Color)',
+    )
+  })
+})

api/spec/packages/typespec-go/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "jsx": "preserve",
+    "jsxImportSource": "@alloy-js/core",
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "libReplacement": false,
+    "noImplicitReturns": true,
+    "incremental": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "useDefineForClassFields": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src"],
+  "exclude": ["./node_modules", "./dist"]
+}

api/spec/packages/typespec-typescript/.gitignore

@@ -0,0 +1,2 @@
+dist/
+tsconfig.tsbuildinfo

api/spec/packages/typespec-typescript/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@openmeter/typespec-typescript",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "alloy build",
+    "watch": "alloy build --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "alloy build && vitest --run",
+    "check": "pnpm run typecheck && pnpm run test"
+  },
+  "dependencies": {
+    "@alloy-js/core": "0.23.1",
+    "@alloy-js/typescript": "0.23.0",
+    "@typespec/compiler": "1.11.0",
+    "@typespec/emitter-framework": "0.17.0",
+    "@typespec/http": "1.11.0",
+    "@typespec/http-client": "0.15.1",
+    "@typespec/openapi": "1.11.0",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@alloy-js/cli": "0.23.0",
+    "@types/node": "25.9.2",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "zod": ">=4"
+  }
+}

api/spec/packages/typespec-typescript/src/ZodOperations.tsx

@@ -0,0 +1,313 @@
+import { type Children, For, refkey } from '@alloy-js/core'
+import {
+  ObjectExpression,
+  ObjectProperty,
+  VarDeclaration,
+} from '@alloy-js/typescript'
+import {
+  getFriendlyName,
+  type ModelProperty,
+  type Operation,
+  type Program,
+  type Type,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { getAllHttpServices } from '@typespec/http'
+import { getExtensions, getOperationId } from '@typespec/openapi'
+import { ZodSchema } from './components/ZodSchema.jsx'
+import { isSuccessStatus } from './http-status.js'
+import { queryCodecForParameter, type QueryCodec } from './query-codecs.js'
+import {
+  callPart,
+  CoerceContext,
+  toCamelCase,
+  useWireMode,
+  zodMemberExpr,
+} from './utils.jsx'
+
+/**
+ * Per-operation request and response Zod schemas.
+ *
+ * The component-level walk emits one schema per data type. This walk adds the
+ * HTTP layer on top: for every operation it emits the assembled query- and
+ * path-parameter objects (with URL-appropriate coercion), the request body, and
+ * the success response body. Bodies reference the shared component schemas via
+ * refkey so the reuse the component emitter buys is preserved; only the param
+ * objects, which have no standalone component, are built inline.
+ */
+
+/** Refkey families so per-operation schemas can be cross-referenced if needed. */
+const pathParamsSym = Symbol.for('typespec-typescript.op.pathParams')
+const queryParamsSym = Symbol.for('typespec-typescript.op.queryParams')
+const bodySym = Symbol.for('typespec-typescript.op.body')
+const responseSym = Symbol.for('typespec-typescript.op.response')
+
+export interface OperationSchema {
+  /**
+   * Declared name before prefix stripping (e.g. `CreateCustomerBody`). Joined
+   * into the emitter's name pool so strips never collide with these.
+   */
+  baseName: string
+  /** Render the declaration under its final (post-strip) name. */
+  render: (name: string) => Children
+}
+
+// Customer-visibility markers from the spec's shared/consts.tsp: x-private is
+// "private and should not be exposed to customers", x-internal is "internal and
+// should not be used by customers". Both are emitted but quarantined under the
+// `client.internal.*` sub-client so the audience split stays visible at every
+// call site — the SDK is also how internal consumers call the API, so dropping
+// x-private operations would just push those callers back to hand-rolled HTTP.
+// x-unstable operations stay in the public surface: most of the young v3 API
+// carries that marker, and it flags maturity, not audience.
+function hasExtension(
+  program: Program,
+  op: Operation,
+  key: `x-${string}`,
+): boolean {
+  // The walked operation is an `extends`/`op is` instance; the @extension
+  // decorators may live on it or on the source operation it was cloned from,
+  // so the whole source chain is consulted.
+  for (
+    let current: Operation | undefined = op;
+    current;
+    current = current.sourceOperation
+  ) {
+    if (getExtensions(program, current).get(key) === true) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Whether an operation belongs to the `client.internal.*` surface. Internal
+ * operations are emitted like any other (funcs, envelope types, zod schemas),
+ * but their grouped-client methods live under `client.internal.*` instead of
+ * the public sub-clients (see emitter.tsx). x-private implies the internal
+ * surface too: it marks a stricter audience than x-internal, so it must never
+ * surface publicly, but internal consumers still call it through the SDK.
+ */
+export function isInternalOperation(program: Program, op: Operation): boolean {
+  return (
+    hasExtension(program, op, 'x-internal') ||
+    hasExtension(program, op, 'x-private')
+  )
+}
+
+/**
+ * Collect every HTTP operation in the program, de-duplicated by the underlying
+ * TypeSpec `Operation` (the same operation surfaces under multiple service
+ * namespaces — OpenMeter and MeteringAndBilling — and must not be emitted
+ * twice). Operations marked x-internal or x-private are collected like any
+ * other and later routed to the `client.internal.*` surface.
+ */
+export function collectHttpOperations(
+  program: Program,
+  includeServices?: string[],
+): Operation[] {
+  const [services] = getAllHttpServices(program)
+  const included =
+    includeServices && includeServices.length > 0
+      ? services.filter((s) => includeServices.includes(s.namespace.name))
+      : services
+  // The same logical endpoint is declared under multiple service namespaces
+  // (OpenMeter and MeteringAndBilling) as distinct `extends` instances, and
+  // `@sharedRoute` content-type variants share one id too. De-dupe by the
+  // stable operation id and keep the first occurrence so each endpoint emits a
+  // single set of schemas.
+  const seen = new Set<string>()
+  const result: Operation[] = []
+  for (const service of included) {
+    for (const httpOp of service.operations) {
+      const id = operationBaseName(program, httpOp.operation)
+      if (seen.has(id)) {
+        continue
+      }
+      seen.add(id)
+      result.push(httpOp.operation)
+    }
+  }
+  return result
+}
+
+/**
+ * `create-customer` / `Foo_bar` -> `CreateCustomer` / `FooBar`.
+ *
+ * An operation-level `@friendlyName` takes precedence over the operation id:
+ * `@sharedRoute` content-type variants share one operation id (one OpenAPI
+ * operation), and a friendly name is how the spec marks a variant that must
+ * surface as its own SDK operation (e.g. `queryMeterCsv`) instead of being
+ * collapsed into its JSON sibling.
+ */
+export function operationBaseName(program: Program, op: Operation): string {
+  const id =
+    getFriendlyName(program, op) || getOperationId(program, op) || op.name
+  return id
+    .split(/[-_/\s]+/)
+    .filter(Boolean)
+    .map((part: string) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+interface ParamLeaf {
+  name: string
+  prop: ModelProperty
+  codec?: QueryCodec
+}
+
+function paramObject(
+  params: ParamLeaf[],
+  camelizeInCamelPass: boolean,
+): Children {
+  // `p.name` is the HTTP-binding wire name. Camelize it only for the public
+  // (camel) pass; the wire pass (emitted under WireModeContext, see
+  // emitter.tsx's `…Wire` re-render) must keep the raw wire name so a
+  // `*QueryParamsWire` schema actually matches the querystring sent on the
+  // wire — otherwise it silently describes the wrong (camelCase) shape.
+  const wire = useWireMode()
+  const camelize = camelizeInCamelPass && !wire
+  return (
+    <CoerceContext.Provider value={true}>
+      {zodMemberExpr(
+        callPart(
+          'object',
+          <ObjectExpression>
+            <For each={params} comma hardline enderPunctuation>
+              {(p) => (
+                <ObjectProperty name={camelize ? toCamelCase(p.name) : p.name}>
+                  {wire && p.codec ? (
+                    <CoerceContext.Provider value={false}>
+                      <ZodSchema
+                        type={p.prop}
+                        valueType={p.codec.wireType}
+                        nested
+                      />
+                    </CoerceContext.Provider>
+                  ) : (
+                    <ZodSchema type={p.prop} nested />
+                  )}
+                </ObjectProperty>
+              )}
+            </For>
+          </ObjectExpression>,
+        ),
+      )}
+    </CoerceContext.Provider>
+  )
+}
+
+/**
+ * Build the request/response schema declarations for a single operation.
+ * Returns the renderable declarations along with the names they declare so the
+ * caller can run them through prefix-stripping/name-policy resolution.
+ */
+export function operationSchemas(
+  program: Program,
+  op: Operation,
+  bodyOverrides: Map<string, Type>,
+): OperationSchema[] {
+  const tk = $(program)
+  const httpOp = tk.httpOperation.get(op)
+  const base = operationBaseName(program, op)
+  const out: OperationSchema[] = []
+
+  const pathParams: ParamLeaf[] = []
+  const queryParams: ParamLeaf[] = []
+  for (const param of httpOp.parameters.parameters) {
+    if (param.type === 'path') {
+      pathParams.push({ name: param.name, prop: param.param })
+    } else if (param.type === 'query') {
+      queryParams.push({
+        name: param.name,
+        prop: param.param,
+        codec: queryCodecForParameter(program, param.name),
+      })
+    }
+    // headers are transport metadata; intentionally skipped.
+  }
+
+  if (pathParams.length > 0) {
+    out.push({
+      baseName: `${base}PathParams`,
+      render: (name) => (
+        <VarDeclaration export name={name} refkey={refkey(op, pathParamsSym)}>
+          {paramObject(pathParams, false)}
+        </VarDeclaration>
+      ),
+    })
+  }
+
+  if (queryParams.length > 0) {
+    out.push({
+      baseName: `${base}QueryParams`,
+      render: (name) => (
+        <VarDeclaration export name={name} refkey={refkey(op, queryParamsSym)}>
+          {paramObject(queryParams, true)}
+        </VarDeclaration>
+      ),
+    })
+  }
+
+  // The body the func actually sends: a shared-route JSON override (e.g. the
+  // single-or-batch ingest union, or a response-only variant like queryMeterCsv
+  // whose declared op omits the body) when present, else the op's own body. The
+  // boundary mapper walks this schema, so it must match the wire shape.
+  const bodyType = bodyOverrides.get(base) ?? httpOp.parameters.body?.type
+  if (bodyType) {
+    out.push({
+      baseName: `${base}Body`,
+      render: (name) => (
+        <VarDeclaration export name={name} refkey={refkey(op, bodySym)}>
+          {bodySchemaRef(program, bodyType)}
+        </VarDeclaration>
+      ),
+    })
+  }
+
+  const responseType = successBodyType(program, httpOp)
+  if (responseType) {
+    out.push({
+      baseName: `${base}Response`,
+      render: (name) => (
+        <VarDeclaration export name={name} refkey={refkey(op, responseSym)}>
+          {bodySchemaRef(program, responseType)}
+        </VarDeclaration>
+      ),
+    })
+  }
+
+  return out
+}
+
+/**
+ * Reference the component schema for a body type, or inline it when it is an
+ * anonymous/non-declaration type with no standalone component.
+ */
+function bodySchemaRef(_program: Program, type: Type): Children {
+  // `nested` ZodSchema emits a reference (refkey member expression) for
+  // declaration types and inlines anonymous ones, matching the component walk.
+  return <ZodSchema type={type} nested />
+}
+
+/**
+ * The body type of the first 2xx response that carries one. Error responses are
+ * available as their own component schemas (e.g. `badRequest`); the per-op
+ * `Response` schema models the success payload a caller validates.
+ */
+function successBodyType(
+  program: Program,
+  httpOp: ReturnType<ReturnType<typeof $>['httpOperation']['get']>,
+): Type | undefined {
+  for (const response of httpOp.responses) {
+    if (!isSuccessStatus(response.statusCodes)) {
+      continue
+    }
+    for (const content of response.responses) {
+      if (content.body) {
+        return content.body.type
+      }
+    }
+  }
+  return undefined
+}

api/spec/packages/typespec-typescript/src/casing-gate.ts

@@ -0,0 +1,250 @@
+import {
+  type Model,
+  type Operation,
+  type Program,
+  resolveEncodedName,
+  type Type,
+  type Union,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import '@typespec/http/experimental/typekit'
+import { isCasingDerivable, toCamelCase } from './casing.js'
+import { isSuccessStatus } from './http-status.js'
+import { bodyProperties, emitsAsIntersection } from './utils.jsx'
+
+/**
+ * The JSON wire name of a body property: its `@encodedName("application/json", …)`
+ * when present, otherwise its declared name. This is the same source the OpenAPI
+ * emitter uses, so the gate measures the public→snake transform against the real
+ * wire contract rather than against the (camelized) emitted key.
+ */
+function wireName(program: Program, prop: Type & { name: string }): string {
+  return resolveEncodedName(program, prop, 'application/json')
+}
+
+/**
+ * Fails the build when an emitted wire key is not recoverable from its public
+ * (camelized) form by the deterministic casing rule. The boundary mapper derives
+ * every wire key it does not carry an explicit name for via `toSnakeCase`, so a
+ * non-derivable name would silently ship a wrong key; this gate turns that into a
+ * codegen error. Covers body property names, query parameter names, and the
+ * discriminator/envelope keys of discriminated unions — every key the mapper or
+ * the URL serializer rewrites.
+ */
+export function assertCasingDerivable(
+  program: Program,
+  models: Model[],
+  operations: Operation[],
+): void {
+  const tk = $(program)
+  const violations: string[] = []
+  const check = (where: string, name: string): void => {
+    if (!isCasingDerivable(name)) {
+      violations.push(`${where}: '${name}' is not snake↔camel derivable`)
+    }
+  }
+
+  // Two distinct wire names in the same object can camelize to the same public
+  // key (e.g. `foo_bar` and `fooBar`); each individually round-trips fine, so
+  // `check` above never catches it, but the emitted model/query type would
+  // silently duplicate or shadow one side. Fail the build instead.
+  const collisions: string[] = []
+  const checkNoCollisions = (where: string, wireNames: string[]): void => {
+    const byCamel = new Map<string, Set<string>>()
+    for (const name of wireNames) {
+      const camel = toCamelCase(name)
+      const group = byCamel.get(camel) ?? new Set<string>()
+      group.add(name)
+      byCamel.set(camel, group)
+    }
+    for (const [camel, names] of byCamel) {
+      if (names.size > 1) {
+        collisions.push(
+          `${where}: ${[...names].join(', ')} all camelize to '${camel}'`,
+        )
+      }
+    }
+  }
+
+  for (const model of models) {
+    const wireNames: string[] = []
+    for (const prop of bodyProperties(program, model)) {
+      const name = wireName(program, prop as Type & { name: string })
+      check(`${model.name}.${prop.name}`, name)
+      wireNames.push(name)
+    }
+    checkNoCollisions(model.name || '<anonymous model>', wireNames)
+  }
+
+  for (const op of operations) {
+    const httpOp = tk.httpOperation.get(op)
+    const queryNames: string[] = []
+    for (const param of httpOp.parameters.parameters) {
+      if (param.type === 'query') {
+        check(`${op.name} query`, param.name)
+        queryNames.push(param.name)
+      }
+    }
+    checkNoCollisions(`${op.name} query`, queryNames)
+  }
+
+  if (collisions.length > 0) {
+    throw new Error(
+      `camelCase SDK: ${collisions.length} wire key group(s) collapse onto the ` +
+        `same camelCase name. Rename one side or add an explicit override.\n  ${collisions.join('\n  ')}`,
+    )
+  }
+
+  // Unions the boundary mapper actually walks: those reachable from a request body
+  // or a success response. Error-envelope unions (e.g. `InvalidParameter` via
+  // `badRequest`) are excluded — they are consumed by `to-error.ts`, never mapped.
+  const { unions: mappedUnions, models: mappedModels } = mappedReachableTypes(
+    program,
+    operations,
+  )
+
+  // Models the mapper would walk that emit as `z.intersection(...)` (a record
+  // spread combined with named fields): the walker's object/record branches
+  // dispatch on `def.type`, and zod has no `"intersection"` case in that
+  // dispatch, so such a schema would silently pass through untransformed —
+  // the record side keeps its wire casing, the named-field side keeps its
+  // wire casing too, and nothing gets camelized. Every intersection model
+  // today (`baseError`/`badRequest`) is error-envelope-only and bypasses the
+  // mapper entirely, so this fails the build the moment that stops being
+  // true rather than letting a future model silently ship the wrong casing.
+  const intersectionModels: string[] = []
+  for (const model of mappedModels) {
+    if (emitsAsIntersection(program, model)) {
+      intersectionModels.push(model.name || '<anonymous model>')
+    }
+  }
+  if (intersectionModels.length > 0) {
+    throw new Error(
+      `camelCase SDK: ${intersectionModels.length} model(s) reachable from a ` +
+        `request body or success response emit as z.intersection(...), which the ` +
+        `wire mapper cannot walk (no case for it). Restructure the model to avoid ` +
+        `combining a record indexer with named properties, or extend the mapper's ` +
+        `walk() with an intersection branch.\n  ${intersectionModels.join('\n  ')}`,
+    )
+  }
+
+  const ambiguousUnions: string[] = []
+  // Iterates `mappedUnions` (every union reachable from an operation's request/
+  // response body, named or inline) rather than only namespace-owned unions, so
+  // an inline union in a model field still reaches the ambiguous-union and
+  // discriminator/envelope casing checks below.
+  for (const union of mappedUnions) {
+    const discriminated = tk.union.getDiscriminatedUnion(union)
+    if (!discriminated) {
+      // A non-discriminated union of two or more object variants has no key the
+      // mapper can use to pick a variant; it would have to guess from the data's
+      // key set at runtime. The mapper deliberately does not — so fail the build,
+      // forcing the union to be `@discriminated` (scalar-vs-object unions are fine,
+      // the mapper distinguishes those by JS type).
+      if (objectVariantCount(program, union) >= 2) {
+        ambiguousUnions.push(union.name ?? '<anonymous union>')
+      }
+      continue
+    }
+    check(
+      `${union.name ?? 'union'} discriminator`,
+      discriminated.options.discriminatorPropertyName,
+    )
+    if (discriminated.options.envelope === 'object') {
+      check(
+        `${union.name ?? 'union'} envelope`,
+        discriminated.options.envelopePropertyName,
+      )
+    }
+  }
+
+  if (ambiguousUnions.length > 0) {
+    throw new Error(
+      `camelCase SDK: ${ambiguousUnions.length} non-discriminated union(s) with ` +
+        `multiple object variants cannot be mapped (the wire mapper cannot pick a ` +
+        `variant). Add @discriminated.\n  ${ambiguousUnions.join('\n  ')}`,
+    )
+  }
+
+  if (violations.length > 0) {
+    throw new Error(
+      `camelCase SDK: ${violations.length} wire key(s) are not casing-derivable. ` +
+        `Add an @encodedName or an explicit override.\n  ${violations.join('\n  ')}`,
+    )
+  }
+}
+
+/** The number of a union's variants whose value is an object/model type. */
+function objectVariantCount(program: Program, union: Union): number {
+  const tk = $(program)
+  let count = 0
+  for (const variant of union.variants.values()) {
+    const type = variant.type
+    if (type.kind === 'Model' && !tk.array.is(type) && !tk.record.is(type)) {
+      count++
+    }
+  }
+  return count
+}
+
+/**
+ * The unions and models the boundary mapper walks: those in the transitive closure
+ * of every operation's request body and success-response body. Error responses are
+ * excluded (their bodies are read by the error path, not mapped).
+ */
+function mappedReachableTypes(
+  program: Program,
+  operations: Operation[],
+): { unions: Set<Union>; models: Set<Model> } {
+  const tk = $(program)
+  const unions = new Set<Union>()
+  const models = new Set<Model>()
+  const seen = new Set<Type>()
+  const visit = (type: Type | undefined): void => {
+    if (!type || seen.has(type)) {
+      return
+    }
+    seen.add(type)
+    switch (type.kind) {
+      case 'Union':
+        unions.add(type)
+        for (const variant of type.variants.values()) {
+          visit(variant.type)
+        }
+        break
+      case 'Model':
+        models.add(type)
+        if (type.indexer) {
+          visit(type.indexer.value)
+        }
+        if (type.baseModel) {
+          visit(type.baseModel)
+        }
+        for (const prop of type.properties.values()) {
+          visit(prop.type)
+        }
+        break
+      case 'Tuple':
+        for (const value of type.values) {
+          visit(value)
+        }
+        break
+      default:
+        break
+    }
+  }
+
+  for (const op of operations) {
+    const httpOp = tk.httpOperation.get(op)
+    visit(httpOp.parameters.body?.type)
+    for (const response of httpOp.responses) {
+      if (!isSuccessStatus(response.statusCodes)) {
+        continue
+      }
+      for (const content of response.responses) {
+        visit(content.body?.type)
+      }
+    }
+  }
+  return { unions, models }
+}

api/spec/packages/typespec-typescript/src/casing.ts

@@ -0,0 +1,18 @@
+export function toCamelCase(name: string): string {
+  return name.replace(/_([a-z0-9])/g, (_m, c: string) => c.toUpperCase())
+}
+
+export function toSnakeCase(name: string): string {
+  return name.replace(/([A-Z])/g, (_m, c: string) => `_${c.toLowerCase()}`)
+}
+
+/**
+ * True when a name survives the camel→snake→camel round-trip, i.e. its wire form
+ * is recoverable from its public (camelized) form by {@link toSnakeCase} alone.
+ * The boundary mapper relies on this for every key it does not carry an explicit
+ * wire name for; the codegen gate asserts it over every emitted wire key so a
+ * non-derivable name fails the build instead of silently shipping a wrong key.
+ */
+export function isCasingDerivable(wireName: string): boolean {
+  return toSnakeCase(toCamelCase(wireName)) === wireName
+}

api/spec/packages/typespec-typescript/src/components/ZodCustomTypeComponent.tsx

@@ -0,0 +1,90 @@
+import type { Children, ComponentDefinition } from '@alloy-js/core'
+import type { ModelProperty, Type } from '@typespec/compiler'
+import { useTsp } from '@typespec/emitter-framework'
+import {
+  getEmitOptionsForType,
+  getEmitOptionsForTypeKind,
+  useZodOptions,
+} from '../context/zod-options.js'
+import { zodBaseSchemaParts } from '../zodBaseSchema.jsx'
+import { zodConstraintsParts } from '../zodConstraintsParts.jsx'
+import { zodDescriptionParts } from '../zodDescriptionParts.jsx'
+import { zodMemberParts } from '../zodMemberParts.jsx'
+
+export interface ZodCustomTypeComponentCommonProps<T extends Type> {
+  type: T
+  children: Children
+}
+
+export interface ZodCustomTypeComponentDeclarationProps<
+  T extends Type,
+  // biome-ignore lint/suspicious/noExplicitAny: matches @alloy-js/core ComponentDefinition surface
+  U extends ComponentDefinition<any>,
+> extends ZodCustomTypeComponentCommonProps<T> {
+  declare: true
+  declarationProps: U extends ComponentDefinition<infer P> ? P : never
+  Declaration: U
+}
+
+export interface ZodCustomTypeComponentReferenceProps<
+  T extends Type,
+> extends ZodCustomTypeComponentCommonProps<T> {
+  reference: true
+  member?: ModelProperty
+}
+
+export type ZodCustomTypeComponentProps<
+  T extends Type,
+  // biome-ignore lint/suspicious/noExplicitAny: matches @alloy-js/core ComponentDefinition surface
+  U extends ComponentDefinition<any>,
+> =
+  | ZodCustomTypeComponentDeclarationProps<T, U>
+  | ZodCustomTypeComponentReferenceProps<T>
+
+export function ZodCustomTypeComponent<
+  T extends Type,
+  // biome-ignore lint/suspicious/noExplicitAny: matches @alloy-js/core ComponentDefinition surface
+  U extends ComponentDefinition<any>,
+>(props: ZodCustomTypeComponentProps<T, U>) {
+  const options = useZodOptions()
+  const { $ } = useTsp()
+  const descriptor =
+    getEmitOptionsForType($.program, props.type, options.customEmit) ??
+    getEmitOptionsForTypeKind($.program, props.type.kind, options.customEmit)
+
+  if (!descriptor) {
+    return <>{props.children}</>
+  }
+
+  if ('declare' in props && props.declare && descriptor.declare) {
+    const CustomComponent = descriptor.declare
+    return (
+      <CustomComponent
+        type={props.type}
+        default={props.children}
+        baseSchemaParts={() => zodBaseSchemaParts(props.type)}
+        constraintParts={() => zodConstraintsParts(props.type)}
+        descriptionParts={() => zodDescriptionParts(props.type)}
+        declarationProps={props.declarationProps}
+        Declaration={props.Declaration}
+      />
+    )
+  }
+
+  if ('reference' in props && props.reference && descriptor.reference) {
+    const CustomComponent = descriptor.reference
+    return (
+      <CustomComponent
+        type={props.type}
+        member={props.member}
+        default={props.children}
+        baseSchemaParts={() => zodBaseSchemaParts(props.member ?? props.type)}
+        constraintParts={() => zodConstraintsParts(props.type, props.member)}
+        descriptionParts={() => zodDescriptionParts(props.type, props.member)}
+        memberParts={() => zodMemberParts(props.member)}
+      />
+    )
+  }
+
+  return <>{props.children}</>
+}

api/spec/packages/typespec-typescript/src/components/ZodOptions.tsx

@@ -0,0 +1,24 @@
+import type { Children } from '@alloy-js/core'
+import {
+  type ZodCustomEmitOptions,
+  ZodOptionsContext,
+} from '../context/zod-options.js'
+
+export interface ZodOptionsProps {
+  /**
+   * Provide custom component for rendering a specific TypeSpec type.
+   */
+  customEmit: ZodCustomEmitOptions
+  children: Children
+}
+
+/**
+ * Set ZodOptions for the children of this component.
+ */
+export function ZodOptions(props: ZodOptionsProps) {
+  return (
+    <ZodOptionsContext.Provider value={{ customEmit: props.customEmit }}>
+      {props.children}
+    </ZodOptionsContext.Provider>
+  )
+}

api/spec/packages/typespec-typescript/src/components/ZodSchema.tsx

@@ -0,0 +1,62 @@
+import { type Children, refkey } from '@alloy-js/core'
+import { MemberExpression } from '@alloy-js/typescript'
+import type { Type } from '@typespec/compiler'
+import { useTsp } from '@typespec/emitter-framework'
+import { activeRefkeySym, shouldReference, useWireMode } from '../utils.jsx'
+import { zodBaseSchemaParts } from '../zodBaseSchema.jsx'
+import { zodConstraintsParts } from '../zodConstraintsParts.jsx'
+import { zodDescriptionParts } from '../zodDescriptionParts.jsx'
+import { zodMemberParts } from '../zodMemberParts.jsx'
+import { ZodCustomTypeComponent } from './ZodCustomTypeComponent.jsx'
+
+export interface ZodSchemaProps {
+  readonly type: Type
+  /** Overrides the property's value type while preserving its member metadata. */
+  readonly valueType?: Type
+  readonly nested?: boolean
+}
+
+/**
+ * Component that translates a TypeSpec type into the Zod type.
+ */
+export function ZodSchema(props: ZodSchemaProps): Children {
+  const { $ } = useTsp()
+  const rkSym = activeRefkeySym(useWireMode())
+
+  if (!props.nested) {
+    return (
+      <MemberExpression>
+        {zodBaseSchemaParts(props.type)}
+        {zodConstraintsParts(props.type)}
+        {zodDescriptionParts(props.type)}
+      </MemberExpression>
+    )
+  }
+
+  const { member, type } = $.modelProperty.is(props.type)
+    ? { member: props.type, type: props.type.type }
+    : { type: props.type, member: undefined }
+  const valueType = props.valueType ?? type
+
+  if (shouldReference($.program, valueType)) {
+    return (
+      <ZodCustomTypeComponent type={valueType} member={member} reference>
+        <MemberExpression>
+          <MemberExpression.Part refkey={refkey(valueType, rkSym)} />
+          {zodMemberParts(member)}
+        </MemberExpression>
+      </ZodCustomTypeComponent>
+    )
+  }
+
+  return (
+    <ZodCustomTypeComponent type={valueType} member={member} reference>
+      <MemberExpression>
+        {zodBaseSchemaParts(valueType)}
+        {zodConstraintsParts(valueType, member)}
+        {zodMemberParts(member)}
+        {zodDescriptionParts(valueType, member)}
+      </MemberExpression>
+    </ZodCustomTypeComponent>
+  )
+}

api/spec/packages/typespec-typescript/src/components/ZodSchemaDeclaration.tsx

@@ -0,0 +1,64 @@
+import * as ay from '@alloy-js/core'
+import * as ts from '@alloy-js/typescript'
+import { getFriendlyName } from '@typespec/compiler'
+import { useTsp } from '@typespec/emitter-framework'
+import {
+  activeRefkeySym,
+  DeclaringTypeContext,
+  useWireMode,
+} from '../utils.jsx'
+import { ZodCustomTypeComponent } from './ZodCustomTypeComponent.jsx'
+import { ZodSchema, type ZodSchemaProps } from './ZodSchema.jsx'
+
+interface ZodSchemaDeclarationProps
+  extends
+    Omit<ts.VarDeclarationProps, 'type' | 'name' | 'value' | 'kind'>,
+    ZodSchemaProps {
+  readonly name?: string
+}
+
+/**
+ * Declare a Zod schema.
+ */
+export function ZodSchemaDeclaration(props: ZodSchemaDeclarationProps) {
+  const { $ } = useTsp()
+  const internalRk = ay.refkey(props.type, activeRefkeySym(useWireMode()))
+  const [zodSchemaProps, varDeclProps] = ay.splitProps(props, [
+    'type',
+    'nested',
+  ]) as [ZodSchemaDeclarationProps, ts.VarDeclarationProps]
+
+  const refkeys = [props.refkey ?? []].flat()
+  refkeys.push(internalRk)
+  // Prefer `@friendlyName` over the raw template name so instantiations like
+  // `CreateRequest<Plan>` become `createPlanRequest` instead of
+  // `createRequest_2`. Mirrors the TS SDK emitter and the OpenAPI emitter,
+  // which already honor the friendly name. References resolve via refkey, so
+  // overriding the declaration name keeps call sites consistent.
+  const friendlyName = getFriendlyName($.program, props.type)
+  const newProps = ay.mergeProps(varDeclProps, {
+    refkey: refkeys,
+    name:
+      props.name ||
+      friendlyName ||
+      ('name' in props.type &&
+        typeof props.type.name === 'string' &&
+        props.type.name) ||
+      props.type.kind,
+  })
+
+  return (
+    <DeclaringTypeContext.Provider value={props.type}>
+      <ZodCustomTypeComponent
+        declare
+        type={props.type}
+        Declaration={ts.VarDeclaration}
+        declarationProps={newProps}
+      >
+        <ts.VarDeclaration {...newProps}>
+          <ZodSchema {...zodSchemaProps} />
+        </ts.VarDeclaration>
+      </ZodCustomTypeComponent>
+    </DeclaringTypeContext.Provider>
+  )
+}

api/spec/packages/typespec-typescript/src/components/index.ts

@@ -0,0 +1,4 @@
+export type { ZodCustomTypeComponentProps } from './ZodCustomTypeComponent.jsx'
+export * from './ZodOptions.jsx'
+export * from './ZodSchema.jsx'
+export * from './ZodSchemaDeclaration.jsx'

api/spec/packages/typespec-typescript/src/context/zod-options.ts

@@ -0,0 +1,163 @@
+import {
+  type Children,
+  type ComponentContext,
+  type ComponentDefinition,
+  createContext,
+  useContext,
+} from '@alloy-js/core'
+import type {
+  ObjectPropertyProps,
+  VarDeclarationProps,
+} from '@alloy-js/typescript'
+import type {
+  Enum,
+  EnumMember,
+  Model,
+  ModelProperty,
+  Program,
+  Scalar,
+  Type,
+  Union,
+  UnionVariant,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { isBuiltIn } from '../utils.jsx'
+
+const getEmitOptionsForTypeSym: unique symbol = Symbol.for(
+  'typespec-typescript:getEmitOptionsForType',
+)
+
+const getEmitOptionsForTypeKindSym: unique symbol = Symbol.for(
+  'typespec-typescript:getEmitOptionsForTypeKind',
+)
+
+export type ZodCustomEmitOptions = ZodCustomEmitOptionsClass
+export const ZodCustomEmitOptions = (() => new ZodCustomEmitOptionsClass()) as {
+  new (): ZodCustomEmitOptionsClass
+  (): ZodCustomEmitOptionsClass
+}
+
+export class ZodCustomEmitOptionsClass {
+  #typeEmitOptions: Map<Type, ZodCustomEmitOptionsBase<any>> = new Map()
+  #typeKindEmitOptions: Map<Type['kind'], ZodCustomEmitOptionsBase<any>> =
+    new Map()
+
+  forType<const T extends Type>(type: T, options: ZodCustomEmitOptionsBase<T>) {
+    this.#typeEmitOptions.set(type, options)
+
+    return this
+  }
+
+  forTypeKind<const TKind extends Type['kind']>(
+    typeKind: TKind,
+    options: ZodCustomEmitOptionsBase<Extract<Type, { kind: TKind }>>,
+  ) {
+    this.#typeKindEmitOptions.set(typeKind, options)
+
+    return this
+  }
+
+  /**
+   * @internal
+   */
+  [getEmitOptionsForTypeSym](program: Program, type: Type) {
+    const direct = this.#typeEmitOptions.get(type)
+    if (direct || !$(program).scalar.is(type) || isBuiltIn(program, type)) {
+      return direct
+    }
+
+    let currentScalar: Scalar | undefined = type
+    while (
+      currentScalar &&
+      !isBuiltIn(program, currentScalar) &&
+      !this.#typeEmitOptions.has(currentScalar)
+    ) {
+      currentScalar = currentScalar?.baseScalar
+    }
+
+    if (!currentScalar) {
+      return undefined
+    }
+
+    return this.#typeEmitOptions.get(currentScalar)
+  }
+
+  /**
+   * @internal
+   */
+  [getEmitOptionsForTypeKindSym](_program: Program, typeKind: Type['kind']) {
+    return this.#typeKindEmitOptions.get(typeKind)
+  }
+}
+
+export interface ZodCustomEmitPropsBase<TCustomType extends Type> {
+  type: TCustomType
+  default: Children
+  baseSchemaParts: () => Children
+  constraintParts: () => Children
+  descriptionParts: () => Children
+}
+
+export type CustomTypeToProps<TCustomType extends Type> =
+  TCustomType extends ModelProperty
+    ? ObjectPropertyProps
+    : TCustomType extends EnumMember
+      ? Record<string, never>
+      : TCustomType extends UnionVariant
+        ? Record<string, never>
+        : TCustomType extends Model | Scalar | Union | Enum
+          ? VarDeclarationProps
+          : VarDeclarationProps | ObjectPropertyProps
+
+export interface ZodCustomEmitReferenceProps<
+  TCustomType extends Type,
+> extends ZodCustomEmitPropsBase<TCustomType> {
+  member?: ModelProperty
+  memberParts: () => Children
+}
+
+export interface ZodCustomEmitDeclareProps<
+  TCustomType extends Type,
+> extends ZodCustomEmitPropsBase<TCustomType> {
+  Declaration: ComponentDefinition<CustomTypeToProps<TCustomType>>
+  declarationProps: CustomTypeToProps<TCustomType>
+}
+
+export type ZodCustomDeclarationComponent<TCustomType extends Type> =
+  ComponentDefinition<ZodCustomEmitDeclareProps<TCustomType>>
+
+export type ZodCustomReferenceComponent<TCustomType extends Type> =
+  ComponentDefinition<ZodCustomEmitReferenceProps<TCustomType>>
+
+export interface ZodCustomEmitOptionsBase<TCustomType extends Type> {
+  declare?: ZodCustomDeclarationComponent<TCustomType>
+  reference?: ZodCustomReferenceComponent<TCustomType>
+  noDeclaration?: boolean
+}
+
+export interface ZodOptionsContext {
+  customEmit?: ZodCustomEmitOptions
+}
+
+export const ZodOptionsContext: ComponentContext<ZodOptionsContext> =
+  createContext({})
+
+export function useZodOptions(): ZodOptionsContext {
+  return useContext(ZodOptionsContext)!
+}
+
+export function getEmitOptionsForType(
+  program: Program,
+  type: Type,
+  options?: ZodCustomEmitOptions,
+) {
+  return options?.[getEmitOptionsForTypeSym](program, type)
+}
+
+export function getEmitOptionsForTypeKind(
+  program: Program,
+  typeKind: Type['kind'],
+  options?: ZodCustomEmitOptions,
+) {
+  return options?.[getEmitOptionsForTypeKindSym](program, typeKind)
+}

api/spec/packages/typespec-typescript/src/emitter.tsx

@@ -0,0 +1,523 @@
+import * as ay from '@alloy-js/core'
+import * as ts from '@alloy-js/typescript'
+import {
+  type EmitContext,
+  getFriendlyName,
+  ListenerFlow,
+  type Model,
+  navigateProgram,
+  type Operation,
+  type Program,
+  type Type,
+  type Union,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+// Registers the experimental HTTP typekit ($.httpOperation, $.modelProperty
+// HTTP helpers) used by the operation walk and metadata stripping.
+import '@typespec/http/experimental/typekit'
+import { Output, writeOutput } from '@typespec/emitter-framework'
+import { ZodSchemaDeclaration } from './components/ZodSchemaDeclaration.jsx'
+import { zod } from './external-packages/zod.js'
+import type { ZodEmitterOptions } from './lib.js'
+import {
+  collectHttpOperations,
+  isInternalOperation,
+  operationSchemas,
+} from './ZodOperations.jsx'
+import { resolveStrippedNames } from './strip-prefixes.js'
+import { newTopologicalTypeCollector, WireModeContext } from './utils.jsx'
+import { RUNTIME_TEMPLATES } from './runtime-templates.js'
+import { assertCasingDerivable } from './casing-gate.js'
+import { WIRE_RUNTIME } from './wire-runtime.js'
+import { interfacesFile } from './interface-types.js'
+import { inputVariantName } from './input-variants.js'
+import {
+  computeResponseReachableModels,
+  setResponseReachableModels,
+} from './visibility.js'
+import { findPaginationTemplates, paginationInfo } from './pagination.js'
+import {
+  groupOperations,
+  jsonBodyOverrides,
+  sdkOperation,
+  type SdkOperation,
+} from './sdk-operations.js'
+import { requestTypesFor } from './request-types.js'
+import { readmeFile, type ReadmeResource } from './readme.js'
+import {
+  facadeFile,
+  funcsFile,
+  funcsIndexFile,
+  indexFile,
+  internalFile,
+  namespaceFile,
+  operationsAssertFile,
+  operationsFile,
+  sdkRootFile,
+} from './sdk-files.js'
+
+/**
+ * The base name a type is declared under before prefix stripping: its
+ * `@friendlyName` if present, otherwise its own name.
+ */
+function baseName(program: Program, type: Type): string | undefined {
+  const friendly = getFriendlyName(program, type)
+  if (friendly) return friendly
+  return 'name' in type && typeof type.name === 'string' ? type.name : undefined
+}
+
+export async function $onEmit(context: EmitContext<ZodEmitterOptions>) {
+  const types = getAllDataTypes(context.program)
+  const tsNamePolicy = ts.createTSNamePolicy()
+  const stripPrefixes = context.options['strip-name-prefixes'] ?? []
+
+  const operations = collectHttpOperations(
+    context.program,
+    context.options['include-services'],
+  )
+
+  // Gate visibility filtering on response reachability before any model is
+  // walked: a create-/update-only property is dropped from a model's read shape
+  // only when that model appears in a response body. Set once, consulted by
+  // every property walker (interfaces, zod schemas, input-variant detection).
+  setResponseReachableModels(
+    context.program,
+    computeResponseReachableModels(context.program, operations),
+  )
+
+  const bodyOverrides = jsonBodyOverrides(context.program)
+  const opSchemas = operations.flatMap((op) =>
+    operationSchemas(context.program, op, bodyOverrides),
+  )
+
+  // Pre-pass: collision-guarded resolved names so a strip is only applied when
+  // it does not clash with another schema (mirrors the TS SDK emitter). The
+  // per-operation schema names join the pool so strips never collide with them
+  // either.
+  const baseNames = [
+    ...types
+      .map((type) => baseName(context.program, type))
+      .filter((n): n is string => n !== undefined),
+    ...opSchemas.map((s) => s.baseName),
+  ]
+  const resolved = resolveStrippedNames(baseNames, stripPrefixes)
+
+  const resolveName = (type: Type): string | undefined => {
+    const base = baseName(context.program, type)
+    return base ? (resolved.get(base) ?? base) : undefined
+  }
+  const models = types.filter((t): t is Model => t.kind === 'Model')
+  // A union can be declared in TypeSpec — and still picked up as a zod schema,
+  // since `getAllDataTypes` walks the whole namespace tree — without anything
+  // in the SDK surface ever referencing it (`PriceUsageBased` is reserved for
+  // future use; `ULIDOrResourceKey`/`ULIDOrExternalResourceKey` are unused
+  // today). Such a union has no meaningful shape for an SDK user to import
+  // (often literally `string | string`), so it is excluded from the `types.ts`
+  // alias pass even though its zod schema is still emitted.
+  const reachableUnions = computeReachableUnions(context.program, operations)
+  const unions = types.filter(
+    (t): t is Union => t.kind === 'Union' && reachableUnions.has(t),
+  )
+
+  // Fail the build if any wire key is not recoverable from its camelCase public
+  // form by the deterministic casing rule, before emitting anything that relies
+  // on it.
+  assertCasingDerivable(context.program, models, operations)
+
+  const interfaceName = (name: string) =>
+    tsNamePolicy.getName(name, 'interface')
+  const interfaces = interfacesFile(
+    context.program,
+    models,
+    unions,
+    resolveName,
+    (name) => tsNamePolicy.getName(name, 'variable'),
+    interfaceName,
+  )
+
+  // A type resolves to its documented interface only when its resolved name
+  // matches an emitted interface (string-based, so template instantiations whose
+  // Type identity differs from the collected model still resolve).
+  const emittedInterfaceNames = new Set(
+    [...models, ...unions]
+      .map((m) => resolveName(m))
+      .filter((n): n is string => Boolean(n))
+      .map(interfaceName),
+  )
+  const resolveInterface = (type: Type | undefined): string | undefined => {
+    if (!type) {
+      return undefined
+    }
+    const resolved = resolveName(type)
+    if (!resolved) {
+      return undefined
+    }
+    const name = interfaceName(resolved)
+    return emittedInterfaceNames.has(name) ? name : undefined
+  }
+
+  // String-keyed set of interface names whose input shape diverges, so a request
+  // body resolves to its `…Input` variant even when the HTTP body Type identity
+  // differs from the collected model (same bridging as `resolveInterface`).
+  const divergentInterfaceNames = new Set(
+    [...interfaces.divergentModels, ...interfaces.divergentUnions]
+      .map((m) => resolveName(m))
+      .filter((n): n is string => Boolean(n))
+      .map(interfaceName),
+  )
+  const resolveRequestBody = (type: Type | undefined): string | undefined => {
+    const name = resolveInterface(type)
+    if (!name) {
+      return undefined
+    }
+    return divergentInterfaceNames.has(name) ? inputVariantName(name) : name
+  }
+
+  const groups = groupOperations(context.program, operations)
+  const resources = [...groups.keys()]
+  const sdkFiles: Array<{ path: string; content: string }> = []
+  const readmeResources: ReadmeResource[] = []
+  // Groups' x-internal operations, destined for the `client.internal.*`
+  // surface. They share their group's funcs and operations modules with the
+  // public ops; only the facade classes are split. A group whose operations
+  // are all internal (e.g. currencies) gets no public facade at all.
+  const internalResources: ReadmeResource[] = []
+  const publicResources: string[] = []
+  const paginationTemplates = findPaginationTemplates(context.program)
+  // Names the operations modules export (`<Base>Request`/`<Base>Response`/
+  // `<Base>Query`), mirroring requestDecl/queryType/responseDecl in
+  // request-types.ts. indexFile must not re-export a same-named domain model:
+  // the explicit re-export would shadow the operation alias at the package
+  // root, and the two are not interchangeable (the alias wraps path params and
+  // AcceptDateStrings widening).
+  const operationTypeNames = new Set<string>()
+  for (const [resource, ops] of groups) {
+    const sdkOps = ops.map((op) =>
+      sdkOperation(
+        context.program,
+        op,
+        resource,
+        resolveInterface,
+        resolveRequestBody,
+        bodyOverrides,
+      ),
+    )
+    ops.forEach((op, i) => {
+      sdkOps[i]!.pagination = paginationInfo(
+        context.program,
+        op,
+        paginationTemplates,
+        resolveInterface,
+      )
+    })
+    for (const op of sdkOps) {
+      operationTypeNames.add(`${op.base}Request`)
+      operationTypeNames.add(`${op.base}Response`)
+      if (op.queryParams.length > 0) {
+        operationTypeNames.add(`${op.base}Query`)
+      }
+    }
+    const publicOps: SdkOperation[] = []
+    const internalOps: SdkOperation[] = []
+    ops.forEach((op, i) => {
+      const target = isInternalOperation(context.program, op)
+        ? internalOps
+        : publicOps
+      target.push(sdkOps[i]!)
+    })
+    const file = namespaceFile(resource)
+    const requestTypes = requestTypesFor(
+      context.program,
+      ops,
+      sdkOps,
+      interfaces.refNameInput,
+      bodyOverrides,
+    )
+    sdkFiles.push({
+      path: `src/models/operations/${file}.ts`,
+      content: operationsFile(resource, requestTypes),
+    })
+    const operationsAsserts = operationsAssertFile(resource, requestTypes)
+    if (operationsAsserts) {
+      sdkFiles.push({
+        path: `src/models/operations/${file}.assert.ts`,
+        content: operationsAsserts,
+      })
+    }
+    sdkFiles.push({
+      path: `src/funcs/${file}.ts`,
+      content: funcsFile(resource, sdkOps),
+    })
+    if (publicOps.length > 0) {
+      publicResources.push(resource)
+      readmeResources.push({ resource, ops: publicOps })
+      sdkFiles.push({
+        path: `src/sdk/${file}.ts`,
+        content: facadeFile(resource, publicOps),
+      })
+    }
+    if (internalOps.length > 0) {
+      internalResources.push({ resource, ops: internalOps })
+    }
+  }
+  if (internalResources.length > 0) {
+    sdkFiles.push({
+      path: 'src/sdk/internal.ts',
+      content: internalFile(internalResources),
+    })
+  }
+  sdkFiles.push({ path: 'src/lib/wire.ts', content: WIRE_RUNTIME })
+  sdkFiles.push({ path: 'src/models/types.ts', content: interfaces.types })
+  sdkFiles.push({
+    path: 'src/models/types.assert.ts',
+    content: interfaces.asserts,
+  })
+  sdkFiles.push({
+    path: 'src/funcs/index.ts',
+    content: funcsIndexFile(resources),
+  })
+  sdkFiles.push({
+    path: 'src/sdk/sdk.ts',
+    content: sdkRootFile(publicResources, internalResources.length > 0),
+  })
+  sdkFiles.push({
+    path: 'src/index.ts',
+    content: indexFile(
+      publicResources,
+      resources,
+      interfaces.typeNames,
+      operationTypeNames,
+    ),
+  })
+  sdkFiles.push({
+    path: 'README.md',
+    content: readmeFile(
+      readmeResources,
+      context.options['package-name'],
+      context.options['readme-note'],
+      internalResources,
+    ),
+  })
+
+  // Stamped on every emitted file (repo convention for generated code): the
+  // four regenerated tests/ files and README.md are indistinguishable from
+  // hand-written files without it, inviting edits the next generate reverts.
+  const generatedComment =
+    'Code generated by @openmeter/typespec-typescript. DO NOT EDIT.'
+
+  // writeOutput is async; without the await, $onEmit resolves before the
+  // files land on the host — the tsp CLI masks this (the process outlives the
+  // pending writes), but in-memory compilation (the emitter test harness)
+  // observes a partially written output directory.
+  await writeOutput(
+    context.program,
+    <Output
+      program={context.program}
+      namePolicy={tsNamePolicy}
+      externals={[zod]}
+    >
+      <ts.SourceFile
+        path="src/models/schemas.ts"
+        headerComment={generatedComment}
+      >
+        <ay.For
+          each={types}
+          ender={';'}
+          joiner={
+            <>
+              ;<hbr />
+              <hbr />
+            </>
+          }
+        >
+          {(type) => {
+            const base = baseName(context.program, type)
+            const name = base ? resolved.get(base) : undefined
+            return <ZodSchemaDeclaration type={type} name={name} export />
+          }}
+        </ay.For>
+        ;<hbr />
+        <hbr />
+        <ay.For
+          each={opSchemas}
+          ender={';'}
+          joiner={
+            <>
+              ;<hbr />
+              <hbr />
+            </>
+          }
+        >
+          {(schema) =>
+            schema.render(resolved.get(schema.baseName) ?? schema.baseName)
+          }
+        </ay.For>
+        ;<hbr />
+        <hbr />
+        {/* The snake_case wire pass: the same models and per-op body/response
+            schemas re-emitted strict for the optional `validate` option. Because
+            both come from one walk over the same types, they are structurally
+            identical except for casing and strictness. */}
+        <WireModeContext.Provider value={true}>
+          <ay.For
+            each={types}
+            ender={';'}
+            joiner={
+              <>
+                ;<hbr />
+                <hbr />
+              </>
+            }
+          >
+            {(type) => {
+              const base = baseName(context.program, type)
+              const name = base ? resolved.get(base) : undefined
+              return (
+                <ZodSchemaDeclaration
+                  type={type}
+                  name={name ? `${name}Wire` : undefined}
+                  export
+                />
+              )
+            }}
+          </ay.For>
+          ;<hbr />
+          <hbr />
+          <ay.For
+            each={opSchemas}
+            ender={';'}
+            joiner={
+              <>
+                ;<hbr />
+                <hbr />
+              </>
+            }
+          >
+            {(schema) =>
+              schema.render(
+                `${resolved.get(schema.baseName) ?? schema.baseName}Wire`,
+              )
+            }
+          </ay.For>
+        </WireModeContext.Provider>
+      </ts.SourceFile>
+      {Object.entries(RUNTIME_TEMPLATES).map(([path, content]) => (
+        <ts.SourceFile path={path} headerComment={generatedComment}>
+          {content}
+        </ts.SourceFile>
+      ))}
+      {sdkFiles.map(({ path, content }) =>
+        path.endsWith('.md') ? (
+          <ts.SourceFile path={path}>
+            {`<!-- ${generatedComment} -->\n\n${content}`}
+          </ts.SourceFile>
+        ) : (
+          <ts.SourceFile path={path} headerComment={generatedComment}>
+            {content}
+          </ts.SourceFile>
+        ),
+      )}
+    </Output>,
+    context.emitterOutputDir,
+  )
+}
+
+/**
+ * Collects all the models defined in the spec and returns them in
+ * topologically sorted order. Types are ordered such that dependencies appear
+ * before the types that depend on them.
+ */
+function getAllDataTypes(program: Program) {
+  const collector = newTopologicalTypeCollector(program)
+  const globalNs = program.getGlobalNamespaceType()
+
+  navigateProgram(
+    program,
+    {
+      namespace(n) {
+        if (n !== globalNs && !$(program).type.isUserDefined(n)) {
+          return ListenerFlow.NoRecursion
+        }
+        return undefined
+      },
+      model: collector.collectType,
+      enum: collector.collectType,
+      union: collector.collectType,
+      scalar: collector.collectType,
+    },
+    { includeTemplateDeclaration: false },
+  )
+
+  return collector.types
+}
+
+/**
+ * Named unions transitively reachable from any operation's request body, query
+ * parameters, or response body (success or error) — descending through model
+ * properties, indexers, base/derived models, and nested union variants, the
+ * same shape the interface/schema walkers traverse. Used to gate which unions
+ * earn a `types.ts` alias: a declared-but-unreferenced union is still
+ * collected as a zod schema (see `getAllDataTypes`), but has nothing to alias
+ * to that an SDK caller could actually encounter.
+ */
+function computeReachableUnions(
+  program: Program,
+  operations: Operation[],
+): Set<Union> {
+  const reachable = new Set<Union>()
+  const visited = new Set<Type>()
+
+  const visit = (type: Type | undefined): void => {
+    if (!type || visited.has(type)) {
+      return
+    }
+    visited.add(type)
+    switch (type.kind) {
+      case 'Model':
+        if (type.indexer) {
+          visit(type.indexer.value)
+        }
+        if (type.baseModel) {
+          visit(type.baseModel)
+        }
+        for (const derived of type.derivedModels) {
+          visit(derived)
+        }
+        for (const prop of type.properties.values()) {
+          visit(prop.type)
+        }
+        break
+      case 'Union':
+        reachable.add(type)
+        for (const variant of type.variants.values()) {
+          visit(variant.type)
+        }
+        break
+      case 'Tuple':
+        for (const value of type.values) {
+          visit(value)
+        }
+        break
+      default:
+        break
+    }
+  }
+
+  const tk = $(program)
+  for (const op of operations) {
+    const httpOp = tk.httpOperation.get(op)
+    visit(httpOp.parameters.body?.type)
+    for (const param of httpOp.parameters.parameters) {
+      if (param.type === 'query') {
+        visit(param.param.type)
+      }
+    }
+    for (const response of httpOp.responses) {
+      for (const content of response.responses) {
+        visit(content.body?.type)
+      }
+    }
+  }
+
+  return reachable
+}

api/spec/packages/typespec-typescript/src/external-packages/zod.ts

@@ -0,0 +1,12 @@
+import { createPackage } from '@alloy-js/typescript'
+import packageJson from 'zod/package.json' with { type: 'json' }
+
+export const zod = createPackage({
+  name: 'zod',
+  version: packageJson.version,
+  descriptor: {
+    '.': {
+      named: ['z'],
+    },
+  },
+})

api/spec/packages/typespec-typescript/src/http-status.ts

@@ -0,0 +1,24 @@
+import type { HttpStatusCodesEntry } from '@typespec/http'
+
+/**
+ * Whether a response's status code(s) mark it as a success response — the ONE
+ * definition every walk must share (operation schemas, request/response types,
+ * visibility, casing gate). A divergent local copy is how an operation's
+ * compile-time types and its runtime mapping drift apart: a body one walk sees
+ * and another skips ships with unverified casing or a mismatched schema.
+ *
+ * Semantics: a single status is success in 200–299; a `{start, end}` range is
+ * success when it overlaps 200–299; the `"*"` default-response wildcard IS
+ * success — its body is mapped at runtime when no numbered success response
+ * exists, so every compile-time walk (including the casing gate) must examine
+ * it too.
+ */
+export function isSuccessStatus(statusCodes: HttpStatusCodesEntry): boolean {
+  if (statusCodes === '*') {
+    return true
+  }
+  if (typeof statusCodes === 'number') {
+    return statusCodes >= 200 && statusCodes < 300
+  }
+  return statusCodes.start < 300 && statusCodes.end >= 200
+}

api/spec/packages/typespec-typescript/src/index.ts

@@ -0,0 +1,6 @@
+export * from './components/index.js'
+export * from './context/zod-options.js'
+export { $onEmit } from './emitter.jsx'
+export * from './external-packages/zod.js'
+export { $lib } from './lib.js'
+export * from './utils.js'

api/spec/packages/typespec-typescript/src/input-variants.ts

@@ -0,0 +1,118 @@
+import {
+  type Model,
+  type Program,
+  type Type,
+  type Union,
+} from '@typespec/compiler'
+import { bodyProperties } from './utils.jsx'
+
+/**
+ * The input shape of a model differs from its output shape only when a defaulted
+ * property — anywhere in its reachable subtree — flips from required (output) to
+ * optional (input). This computes the set of models for which an `…Input`
+ * variant interface must be emitted.
+ *
+ * A model diverges-on-input iff it has a defaulted property, or any property
+ * type (descending through arrays, records, unions, tuples, and `baseModel`,
+ * matching the schema walker) transitively reaches a model that diverges.
+ */
+export function computeDivergentModels(
+  program: Program,
+  models: Model[],
+): Set<Model> {
+  const diverges = new Set<Model>()
+  const memo = new Map<Model, boolean>()
+  const stack = new Set<Model>()
+
+  const reaches = (type: Type): boolean => {
+    switch (type.kind) {
+      case 'Model':
+        return modelDiverges(type)
+      case 'ModelProperty':
+        return reaches(type.type)
+      case 'Union':
+        for (const variant of type.variants.values()) {
+          if (reaches(variant.type)) {
+            return true
+          }
+        }
+        return false
+      case 'Tuple':
+        return type.values.some(reaches)
+      default:
+        return false
+    }
+  }
+
+  const modelDiverges = (model: Model): boolean => {
+    const cached = memo.get(model)
+    if (cached !== undefined) {
+      return cached
+    }
+    // A cycle that reaches back to an in-progress model contributes nothing on
+    // its own; the originating frame still sees its other branches.
+    if (stack.has(model)) {
+      return false
+    }
+    stack.add(model)
+
+    let result = false
+    if (model.indexer && reaches(model.indexer.value)) {
+      result = true
+    }
+    if (!result && model.baseModel && modelDiverges(model.baseModel)) {
+      result = true
+    }
+    if (!result) {
+      for (const prop of bodyProperties(program, model)) {
+        if (prop.defaultValue !== undefined || reaches(prop.type)) {
+          result = true
+          break
+        }
+      }
+    }
+
+    stack.delete(model)
+    memo.set(model, result)
+    if (result) {
+      diverges.add(model)
+    }
+    return result
+  }
+
+  for (const model of models) {
+    modelDiverges(model)
+  }
+  return diverges
+}
+
+/** The interface name of a model's input variant. */
+export function inputVariantName(outputName: string): string {
+  return `${outputName}Input`
+}
+
+/**
+ * Named unions that need an `…Input` alias: at least one variant is a model
+ * whose own input shape diverges (see {@link computeDivergentModels}). Unions
+ * carry no properties of their own, so — unlike a model — a union never
+ * diverges on its own account; it only needs an `…Input` variant when
+ * substituting one of its variants for that variant's `…Input` interface
+ * actually changes the union's shape. Only the immediate variants are
+ * checked (matching the requirement that drives it: picking the right
+ * variant interface per branch, not a transitive default-value walk).
+ */
+export function computeDivergentUnions(
+  unions: Union[],
+  divergentModels: Set<Model>,
+): Set<Union> {
+  const diverges = new Set<Union>()
+  for (const union of unions) {
+    for (const variant of union.variants.values()) {
+      if (variant.type.kind === 'Model' && divergentModels.has(variant.type)) {
+        diverges.add(union)
+        break
+      }
+    }
+  }
+  return diverges
+}

api/spec/packages/typespec-typescript/src/interface-types.ts

@@ -0,0 +1,280 @@
+import {
+  type Model,
+  type Program,
+  type Type,
+  type Union,
+} from '@typespec/compiler'
+import { $ } from '@typespec/compiler/typekit'
+import { bodyProperties, jsdoc, publicPropertyName } from './utils.jsx'
+import {
+  type IoMode,
+  type RefName,
+  isOptional,
+  tsTypeOf,
+  unionVariantsType,
+} from './ts-types.js'
+import {
+  computeDivergentModels,
+  computeDivergentUnions,
+  inputVariantName,
+} from './input-variants.js'
+
+type ResolveName = (type: Type) => string | undefined
+type SchemaName = (resolvedName: string) => string
+
+/**
+ * A mutual-assignability check between an emitted type and its wire schema. The
+ * emitted type is walked from TypeSpec independently of zod, so this is the only
+ * place the two artifacts meet: any divergence becomes a build error.
+ */
+function conformanceGuard(name: string, schemaRef: string): string {
+  return (
+    `type _Assert${name} = [${name}] extends [${schemaRef}]\n` +
+    `  ? [${schemaRef}] extends [${name}]\n` +
+    `    ? true\n` +
+    `    : { __error: '${name} is missing fields present in the wire schema' }\n` +
+    `  : { __error: '${name} has fields not present in the wire schema' }\n` +
+    `const _assert${name}: _Assert${name} = true`
+  )
+}
+
+/**
+ * A one-directional check for input variants: the emitted type must be a valid
+ * input the schema accepts (`[X] extends [z.input]`), but not vice versa. zod's
+ * `z.input` of a coerced leaf (e.g. `z.coerce.bigint()`) is the loose `unknown`;
+ * the emitted type deliberately keeps the strict leaf (`bigint`), so the reverse
+ * direction is intentionally dropped instead of widening the public type.
+ */
+function inputConformanceGuard(name: string, schemaRef: string): string {
+  return (
+    `type _Assert${name} = [${name}] extends [${schemaRef}]\n` +
+    `  ? true\n` +
+    `  : { __error: '${name} is not assignable to the wire input schema' }\n` +
+    `const _assert${name}: _Assert${name} = true`
+  )
+}
+
+function interfaceBody(
+  program: Program,
+  model: Model,
+  refName: RefName,
+  io: IoMode,
+): string {
+  const tk = $(program)
+  const lines: string[] = []
+  for (const prop of bodyProperties(program, model)) {
+    const doc = jsdoc(tk.type.getDoc(prop), '  ')
+    if (doc) {
+      lines.push(doc)
+    }
+    const opt = isOptional(prop, io) ? '?' : ''
+    lines.push(
+      `  ${publicPropertyName(program, prop)}${opt}: ${tsTypeOf(program, prop.type, refName, io)}`,
+    )
+  }
+  // An indexer (`...Record<...>`) makes the model open; mirror it with an index
+  // signature so the interface stays assignable to the open wire shape while
+  // keeping its documented known fields.
+  if (model.indexer?.key.name === 'string') {
+    lines.push(
+      `  [key: string]: ${tsTypeOf(program, model.indexer.value, refName, io)}`,
+    )
+  }
+  return lines.join('\n')
+}
+
+export interface InterfacesResult {
+  types: string
+  asserts: string
+  /** Names of every interface/type exported from `types.ts`, including `…Input` variants. */
+  typeNames: string[]
+  /** Models whose input shape diverges from their output interface. */
+  divergentModels: Set<Model>
+  /** Named unions whose input shape diverges from their output alias. */
+  divergentUnions: Set<Union>
+  /**
+   * Input-mode ref resolver: the `…Input` variant for a divergent model or
+   * union, else the type's plain alias. Used to build request/query types.
+   */
+  refNameInput: RefName
+}
+
+export function interfacesFile(
+  program: Program,
+  models: Model[],
+  unions: Union[],
+  resolveName: ResolveName,
+  schemaName: SchemaName,
+  interfaceName: (resolvedName: string) => string,
+): InterfacesResult {
+  const tk = $(program)
+  const emitted = new Set<Type>([...models, ...unions])
+  const refName = (type: Type): string | undefined => {
+    if (!emitted.has(type)) {
+      return undefined
+    }
+    const resolved = resolveName(type)
+    return resolved ? interfaceName(resolved) : undefined
+  }
+
+  const divergent = computeDivergentModels(program, models)
+  const divergentUnions = computeDivergentUnions(unions, divergent)
+  // An input-mode ref points at a child's `…Input` variant when that child also
+  // diverges, so relaxed optionality propagates through the subtree.
+  const refNameInput: RefName = (type) => {
+    const name = refName(type)
+    if (!name) {
+      return undefined
+    }
+    if (type.kind === 'Model' && divergent.has(type)) {
+      return inputVariantName(name)
+    }
+    if (type.kind === 'Union' && divergentUnions.has(type)) {
+      return inputVariantName(name)
+    }
+    return name
+  }
+
+  const blocks: string[] = []
+  const inputBlocks: string[] = []
+  const asserts: string[] = []
+  for (const model of models) {
+    const resolved = resolveName(model)
+    if (!resolved) {
+      continue
+    }
+    const name = interfaceName(resolved)
+    const schemaRef = `z.output<typeof schemas.${schemaName(resolved)}>`
+    const doc = jsdoc(tk.type.getDoc(model), '')
+
+    // When the model `extends` an emitted base, the interface extends it too so
+    // inherited fields (and their docs) propagate; only own properties go in the
+    // body.
+    const baseName = model.baseModel ? refName(model.baseModel) : undefined
+    const extendsClause = baseName ? ` extends ${baseName}` : ''
+
+    const hasWireProps = bodyProperties(program, model).length > 0
+
+    // Models with no wire-mapped properties and no base (records, unions, marker
+    // types) have no structural interface — alias straight to the mapped type so
+    // it is correct (e.g. `Labels` -> `Record<string, string>`) rather than an
+    // empty, permissive `interface {}`.
+    if (!hasWireProps && !baseName) {
+      const parts: string[] = []
+      if (doc) {
+        parts.push(doc)
+      }
+      // Exclude the model from its own ref resolution so the alias expresses its
+      // structure (`Record<string, string>`) instead of aliasing to itself.
+      const structural: RefName = (type) =>
+        type === model ? undefined : refName(type)
+      parts.push(
+        `export type ${name} = ${tsTypeOf(program, model, structural)}`,
+      )
+      blocks.push(parts.join('\n'))
+      // The alias is an independently-walked type, not the inferred shape, so it
+      // is guarded too — unlike a `z.output` alias, it can diverge.
+      asserts.push(conformanceGuard(name, schemaRef))
+      continue
+    }
+
+    const body = interfaceBody(program, model, refName, 'output')
+    const parts: string[] = []
+    if (doc) {
+      parts.push(doc)
+    }
+    parts.push(`export interface ${name}${extendsClause} {\n${body}\n}`)
+    blocks.push(parts.join('\n'))
+    asserts.push(conformanceGuard(name, schemaRef))
+
+    // The input variant relaxes defaulted fields to optional (transitively); it
+    // is emitted only where the input shape actually diverges from the output.
+    if (divergent.has(model)) {
+      const inputNameStr = inputVariantName(name)
+      const inputExtends =
+        model.baseModel && divergent.has(model.baseModel)
+          ? ` extends ${inputVariantName(refName(model.baseModel)!)}`
+          : extendsClause
+      const inputBody = interfaceBody(program, model, refNameInput, 'input')
+      const inputParts: string[] = []
+      if (doc) {
+        inputParts.push(doc)
+      }
+      inputParts.push(
+        `export interface ${inputNameStr}${inputExtends} {\n${inputBody}\n}`,
+      )
+      inputBlocks.push(inputParts.join('\n'))
+      asserts.push(
+        inputConformanceGuard(
+          inputNameStr,
+          `z.input<typeof schemas.${schemaName(resolved)}>`,
+        ),
+      )
+    }
+  }
+
+  for (const union of unions) {
+    const resolved = resolveName(union)
+    if (!resolved) {
+      continue
+    }
+    const name = interfaceName(resolved)
+    const schemaRef = `z.output<typeof schemas.${schemaName(resolved)}>`
+    const doc = jsdoc(tk.type.getDoc(union), '')
+
+    // Exclude the union from its own ref resolution so the alias expands its
+    // variants (`PriceFree | PriceFlat | …`) instead of aliasing to itself.
+    const structural: RefName = (type) =>
+      type === union ? undefined : refName(type)
+    const parts: string[] = []
+    if (doc) {
+      parts.push(doc)
+    }
+    parts.push(
+      `export type ${name} = ${unionVariantsType(program, union, structural, 'output')}`,
+    )
+    blocks.push(parts.join('\n'))
+    asserts.push(conformanceGuard(name, schemaRef))
+
+    // Mirrors the model input variant above: emitted only when substituting a
+    // variant's own `…Input` interface actually changes the union's shape.
+    if (divergentUnions.has(union)) {
+      const inputNameStr = inputVariantName(name)
+      const structuralInput: RefName = (type) =>
+        type === union ? undefined : refNameInput(type)
+      const inputParts: string[] = []
+      if (doc) {
+        inputParts.push(doc)
+      }
+      inputParts.push(
+        `export type ${inputNameStr} = ${unionVariantsType(program, union, structuralInput, 'input')}`,
+      )
+      inputBlocks.push(inputParts.join('\n'))
+      asserts.push(
+        inputConformanceGuard(
+          inputNameStr,
+          `z.input<typeof schemas.${schemaName(resolved)}>`,
+        ),
+      )
+    }
+  }
+
+  const allBlocks = [...blocks, ...inputBlocks]
+  const typeNames = allBlocks
+    .map((b) => b.match(/export (?:interface|type) (\w+)/)?.[1])
+    .filter((n): n is string => Boolean(n))
+  const types = `${allBlocks.join('\n\n')}\n`
+  const assertImports =
+    `import { z } from 'zod'\n` +
+    `import * as schemas from './schemas.js'\n` +
+    `import type { ${typeNames.join(', ')} } from './types.js'\n`
+  const assertsFile = `${assertImports}\n${asserts.join('\n\n')}\n`
+  return {
+    types,
+    asserts: assertsFile,
+    typeNames,
+    divergentModels: divergent,
+    divergentUnions,
+    refNameInput,
+  }
+}

api/spec/packages/typespec-typescript/src/lib.ts

@@ -0,0 +1,72 @@
+import {
+  createTypeSpecLibrary,
+  JSONSchemaType,
+  paramMessage,
+} from '@typespec/compiler'
+
+export interface ZodEmitterOptions {
+  'package-name': string
+  'readme-note'?: string
+  'strip-name-prefixes'?: string[]
+  'include-services'?: string[]
+}
+
+const EmitterOptionsSchema: JSONSchemaType<ZodEmitterOptions> = {
+  type: 'object',
+  additionalProperties: true,
+  properties: {
+    'package-name': {
+      type: 'string',
+      description:
+        'The npm package name the generated README installs and imports.',
+    },
+    'readme-note': {
+      type: 'string',
+      nullable: true,
+      description:
+        'Markdown inserted after the README intro, e.g. a GitHub alert callout.',
+    },
+    'strip-name-prefixes': {
+      type: 'array',
+      items: { type: 'string' },
+      nullable: true,
+      description: 'Prefixes to strip from generated Zod schema',
+    },
+    'include-services': {
+      type: 'array',
+      items: { type: 'string' },
+      nullable: true,
+      description:
+        'Service namespace names whose operations get per-operation schemas. When omitted, all services are included.',
+    },
+  },
+  required: ['package-name'],
+}
+
+export const $lib = createTypeSpecLibrary({
+  name: 'typespec-typescript',
+  emitter: {
+    options: EmitterOptionsSchema,
+  },
+  // Every silent-degradation path in the emitter must report one of these.
+  // Nothing in the current spec triggers them — they exist so future spec
+  // shapes the emitter cannot faithfully map surface in the generate output
+  // instead of quietly eroding the SDK (a z.any() schema, or an endpoint
+  // missing from the published client).
+  diagnostics: {
+    'unsupported-type': {
+      severity: 'warning',
+      messages: {
+        default: paramMessage`${'kind'} has no schema mapping and degrades to any/unknown in the generated SDK`,
+      },
+    },
+    'ungrouped-operation': {
+      severity: 'warning',
+      messages: {
+        default: paramMessage`operation '${'operation'}' has no resolvable source interface (not authored via the extends/op-is pattern) and was omitted from the generated SDK`,
+      },
+    },
+  },
+})
+
+export const { reportDiagnostic, createDiagnostic } = $lib