@haddowg/json-api-codegen 1.4.0 → 1.6.0

package/dist/cli.d.mts

@@ -1,4 +1,4 @@
-import { r as CodegenConfig } from "./index-Cnj374D6.mjs";
+import { r as CodegenConfig } from "./index-CU-kUx70.mjs";
 
 //#region src/cli.d.ts
 declare const USAGE = "Usage: json-api-codegen --input <url|file> --output <file> [--server <name>] [--schemas <url|file>] [--check]";

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as generate, r as schemasOutputPath, t as check } from "./src-BE7OMLWG.mjs";
+import { n as generate, r as schemasOutputPath, t as check } from "./src-C2INS1Wd.mjs";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts

package/dist/{index-Cnj374D6.d.mts → index-CU-kUx70.d.mts}

@@ -48,6 +48,7 @@ interface ParameterObject {
   'x-profile'?: string;
 }
 interface OperationObject {
+  operationId?: string;
   parameters?: readonly ParameterObject[];
   requestBody?: RequestBodyObject;
   responses?: Record<string, ResponseObject>;
@@ -76,12 +77,11 @@ interface OpenApiDocument {
 //#endregion
 //#region src/build-descriptor.d.ts
 declare class DescriptorBuilder {
-  private readonly doc;
   private readonly schemas;
   private readonly paths;
   /** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
   private typePaginators?;
-  constructor(doc: OpenApiDocument);
+  constructor(source: OpenApiDocument);
   /**
    * The collection-level paginator kind for a WIRE type (`tracks`), memoised. Resolves each
    * resource schema's wire type (its `type.const`) to the paginator of its collection GET — the
@@ -89,13 +89,6 @@ declare class DescriptorBuilder {
    */
   private typePaginator;
   build(): ApiDescriptor;
-  /**
-   * Warn about relations a create or update body accepts but the resource never renders. A
-   * write-only relation (generator contract 5) is left out of the response schema, and the
-   * descriptor has no way to mark a relation as writable but unreadable, so it is missing from
-   * the client entirely rather than typed onto reads that never carry it.
-   */
-  private warnWriteOnlyRelations;
   /**
    * The server-level Atomic Operations capability: the path whose `POST` requestBody
    * declares the atomic ext media type ({@link ATOMIC_EXT}). `null` when no such endpoint
@@ -111,7 +104,26 @@ declare class DescriptorBuilder {
   /** Follow a `$ref` to its identifier/resource schema and read `properties.type.const`. */
   private resolveConst;
   private attributes;
+  /**
+   * The relations of a type: every relation its resource renders, plus each write-only relation
+   * the create and update bodies accept. A write-only relation is one whose body property carries
+   * `writeOnly: true` (generator contract 8) or, in an older document, one the resource doesn't
+   * render. A pivot relation reads its response pivot off the rendered relationship and its
+   * request pivot off the write bodies.
+   */
   private relations;
+  /**
+   * The relationships the create and update bodies accept: each one's component `$ref` and
+   * whether the body marks it `writeOnly`.
+   */
+  private writeRelationships;
+  /**
+   * Each relation's related and relationship paths, keyed by relation name, from the
+   * operationIds the projector stamps (`fetchRelated.<type>.<relation>`, …). A relation's path
+   * segment is its URI field name, which may differ from its name, so the paths are never
+   * derived from the name when an operationId names them.
+   */
+  private relationEndpoints;
   /**
    * The per-relation mutation capability, derived from the HTTP methods the relationship
    * endpoint (`{collection}/{id}/relationships/{rel}`) advertises. For a to-many:
@@ -152,12 +164,19 @@ declare class DescriptorBuilder {
   /** Resolve a relationship component's `data` into a {@link RelationDescriptor}. */
   private relationFromComponent;
   /**
-   * Extract the pivot field-shape from a pivot `allOf` — the entry carrying
-   * `properties.meta.properties.pivot.properties` (a `belongsToMany` member's `meta.pivot`), as a
-   * field-name → wire-format-hint map (D33). Returns `undefined` when the allOf carries no pivot
-   * property block.
+   * The request pivot of a pivot relation: read off the component a write body (or a
+   * relationship mutation) refs, falling back to the rendered relationship's pivot minus its
+   * `readOnly` fields when no request shape is published (before generator contract 8).
+   */
+  private writePivot;
+  /**
+   * A {@link PivotDescriptor} from a member's `meta.pivot` schema: field hints, the required
+   * fields and the nullable ones. Generator contract 8 refs a `<Type><Rel>Pivot` (response) or
+   * `<Type><Rel>WritePivot` (request) component, each with its own `required`. An older document
+   * inlines one shared schema in the write context, so a read takes every field as rendered and a
+   * write drops the `readOnly` ones. `undefined` when the schema has no fields.
    */
-  private pivotFieldsFromAllOf;
+  private pivotDescriptor;
   /** Pull the related type from the `$ref` entry of an `allOf` (the pivot shape). */
   private constFromAllOf;
   /** Resolve every `$ref` entry in a list to its wire type. */
@@ -241,7 +260,7 @@ declare function buildAtomic(doc: OpenApiDocument): AtomicDescriptor | null;
 /** Below this the document predates the structures this codegen reads. */
 declare const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-declare const MAXIMUM_CONTRACT = 7;
+declare const MAXIMUM_CONTRACT = 9;
 /**
  * Check the document's `info.x-generator.contract` against the range this codegen reads. A
  * document older than the range throws; a newer one returns a warning, because its new
@@ -262,7 +281,6 @@ interface VerbCollision {
  */
 declare function detectVerbCollisions(descriptor: ApiDescriptor): VerbCollision[];
 declare class Emitter {
-  private readonly doc;
   private readonly descriptor;
   private readonly atomic;
   private readonly schemas;
@@ -287,7 +305,8 @@ declare class Emitter {
   private readonly actionAliasNames;
   /** Provenance of the source document, stamped into the generated header for drift tracking. */
   private readonly provenance;
-  constructor(doc: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
+  private readonly doc;
+  constructor(source: OpenApiDocument, descriptor: ApiDescriptor, atomic: AtomicDescriptor | null);
   /** Map each declared wire type back to the `Base` of its resource schema. */
   private indexBases;
   emit(): string;
@@ -546,4 +565,4 @@ declare function generate(config: CodegenConfig): Promise<string>;
 declare function check(config: CodegenConfig): Promise<CheckResult>;
 //#endregion
 export { InfoObject as A, MAXIMUM_CONTRACT as C, buildAtomic as D, DescriptorBuilder as E, PathItemObject as F, RequestBodyObject as I, ResponseObject as L, OpenApiDocument as M, OperationObject as N, buildDescriptor as O, ParameterObject as P, SchemaObject as R, emit as S, checkContract as T, emitErrorCodes as _, generate as a, VerbCollision as b, deriveProvenance as c, emitSchemas as d, SchemaBundle as f, ErrorCatalogue as g, DocumentedErrorCode as h, check as i, MediaTypeObject as j, HttpMethod as k, hashJson as l, readSchemas as m, CheckResult as n, schemasOutputPath as o, readDocument as p, CodegenConfig as r, Provenance as s, ArtifactDrift as t, provenanceLines as u, readErrorCatalogue as v, MINIMUM_CONTRACT as w, detectVerbCollisions as x, Emitter as y, SchemaOrBool as z };
-//# sourceMappingURL=index-Cnj374D6.d.mts.map
+//# sourceMappingURL=index-CU-kUx70.d.mts.map

package/dist/index-CU-kUx70.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CU-kUx70.d.mts","names":[],"sources":["../src/openapi.ts","../src/build-descriptor.ts","../src/contract.ts","../src/emit.ts","../src/error-codes.ts","../src/reader.ts","../src/emit-schemas.ts","../src/provenance.ts","../src/index.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-Cnj374D6.mjs";
+import { A as InfoObject, C as MAXIMUM_CONTRACT, D as buildAtomic, E as DescriptorBuilder, F as PathItemObject, I as RequestBodyObject, L as ResponseObject, M as OpenApiDocument, N as OperationObject, O as buildDescriptor, P as ParameterObject, R as SchemaObject, S as emit, T as checkContract, _ as emitErrorCodes, a as generate, b as VerbCollision, c as deriveProvenance, d as emitSchemas, f as SchemaBundle, g as ErrorCatalogue, h as DocumentedErrorCode, i as check, j as MediaTypeObject, k as HttpMethod, l as hashJson, m as readSchemas, n as CheckResult, o as schemasOutputPath, p as readDocument, r as CodegenConfig, s as Provenance, t as ArtifactDrift, u as provenanceLines, v as readErrorCatalogue, w as MINIMUM_CONTRACT, x as detectVerbCollisions, y as Emitter, z as SchemaOrBool } from "./index-CU-kUx70.mjs";
 export { ArtifactDrift, CheckResult, CodegenConfig, DescriptorBuilder, type DocumentedErrorCode, Emitter, type ErrorCatalogue, type HttpMethod, type InfoObject, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, type MediaTypeObject, type OpenApiDocument, type OperationObject, type ParameterObject, type PathItemObject, type Provenance, type RequestBodyObject, type ResponseObject, type SchemaBundle, type SchemaObject, type SchemaOrBool, type VerbCollision, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-BE7OMLWG.mjs";
+import { _ as checkContract, a as readSchemas, b as buildDescriptor, c as detectVerbCollisions, d as hashJson, f as provenanceLines, g as MINIMUM_CONTRACT, h as MAXIMUM_CONTRACT, i as readDocument, l as emit, m as readErrorCatalogue, n as generate, o as emitSchemas, p as emitErrorCodes, r as schemasOutputPath, s as Emitter, t as check, u as deriveProvenance, v as DescriptorBuilder, y as buildAtomic } from "./src-C2INS1Wd.mjs";
 export { DescriptorBuilder, Emitter, MAXIMUM_CONTRACT, MINIMUM_CONTRACT, buildAtomic, buildDescriptor, check, checkContract, deriveProvenance, detectVerbCollisions, emit, emitErrorCodes, emitSchemas, generate, hashJson, provenanceLines, readDocument, readErrorCatalogue, readSchemas, schemasOutputPath };

package/dist/{src-BE7OMLWG.mjs → src-C2INS1Wd.mjs}

@@ -3,6 +3,64 @@ import { dirname } from "node:path";
 import { ATOMIC_EXT, CANONICAL_PAGE_KEYS, HANDLE_RESERVED } from "@haddowg/json-api-client";
 import { createHash } from "node:crypto";
 import { parse } from "yaml";
+//#region src/unwrap-refs.ts
+/**
+* Keywords that annotate a schema without constraining it. A single-entry `allOf` wrapper is
+* read as its `$ref` only when the wrapper carries nothing else, plus any `x-` extension.
+*/
+const ANNOTATIONS = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"example",
+	"examples",
+	"default",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"$comment"
+]);
+const unwrapped = /* @__PURE__ */ new WeakMap();
+/**
+* The document with every `{ allOf: [{ $ref }], ...annotations }` node rewritten as
+* `{ $ref, ...annotations }`. From generator contract 9 the projector wraps a `$ref` that
+* carries an `example`, `examples` or `default` this way, because OAS 3.0 tooling ignores a
+* `$ref`'s siblings. Reading the wrapper as its `$ref` keeps every lookup that follows a `$ref`
+* working, and keeps the annotations for the TSDoc. The input is not modified.
+*/
+function unwrapRefs(doc) {
+	let out = unwrapped.get(doc);
+	if (out === void 0) {
+		out = unwrapNode(doc);
+		unwrapped.set(doc, out);
+		unwrapped.set(out, out);
+	}
+	return out;
+}
+function unwrapNode(node) {
+	if (Array.isArray(node)) return node.map(unwrapNode);
+	if (typeof node !== "object" || node === null) return node;
+	const out = {};
+	for (const [key, value] of Object.entries(node)) out[key] = unwrapNode(value);
+	const ref = wrappedRef(out);
+	if (ref === void 0) return out;
+	const { allOf: _allOf, ...annotations } = out;
+	return {
+		$ref: ref,
+		...annotations
+	};
+}
+/** The `$ref` a node wraps in a single-entry `allOf`, when that is all the node constrains. */
+function wrappedRef(node) {
+	const allOf = node["allOf"];
+	if (!Array.isArray(allOf) || allOf.length !== 1 || "$ref" in node) return;
+	const entry = allOf[0];
+	if (typeof entry !== "object" || entry === null) return;
+	const keys = Object.keys(entry);
+	const ref = entry["$ref"];
+	if (keys.length !== 1 || typeof ref !== "string") return;
+	return Object.keys(node).every((key) => key === "allOf" || ANNOTATIONS.has(key) || key.startsWith("x-")) ? ref : void 0;
+}
+//#endregion
 //#region src/build-descriptor.ts
 const REF_PREFIX$2 = "#/components/schemas/";
 const JSON_API_MEDIA_TYPE$1 = "application/vnd.api+json";
@@ -19,19 +77,26 @@ function refName$1(ref) {
 function isSchema$2(value) {
 	return typeof value === "object" && value !== null;
 }
+/** The operationId prefixes of a relation's related read and its relationship endpoint. */
+const RELATED_OPERATION = "fetchRelated";
+const RELATIONSHIP_OPERATIONS = [
+	"fetchRelationship",
+	"updateRelationship",
+	"addRelationship",
+	"removeRelationship"
+];
 /** The set of `type` keys a JSON type node declares, with `"null"` removed. */
 function typeKeys(type) {
 	if (type === void 0) return [];
 	return (Array.isArray(type) ? type : [type]).filter((t) => t !== "null");
 }
 var DescriptorBuilder = class {
-	doc;
 	schemas;
 	paths;
 	/** Lazily-built wire-type -> collection-level paginator kind (for per-relation divergence, D6a). */
 	typePaginators;
-	constructor(doc) {
-		this.doc = doc;
+	constructor(source) {
+		const doc = unwrapRefs(source);
 		this.schemas = doc.components?.schemas ?? {};
 		this.paths = doc.paths ?? {};
 	}
@@ -60,7 +125,7 @@ var DescriptorBuilder = class {
 			const actions = collection ? this.actions(collection) : {};
 			const descriptor = {
 				attributes: this.attributes(base),
-				relations: this.relations(schema, collection),
+				relations: this.relations(wireType, base, schema, collection),
 				paths: this.operationPaths(base),
 				paginator: this.paginator(base),
 				clientId: this.clientId(base)
@@ -75,27 +140,11 @@ var DescriptorBuilder = class {
 			if (filterable !== void 0) descriptor.filterable = filterable;
 			if (Object.keys(actions).length > 0) descriptor.actions = actions;
 			if (Object.keys(schema.properties ?? {}).every((prop) => prop === "type") && Object.keys(descriptor.paths).length === 0) continue;
-			this.warnWriteOnlyRelations(wireType, base, descriptor.relations);
 			out[wireType] = descriptor;
 		}
 		return sortRecord(out);
 	}
 	/**
-	* Warn about relations a create or update body accepts but the resource never renders. A
-	* write-only relation (generator contract 5) is left out of the response schema, and the
-	* descriptor has no way to mark a relation as writable but unreadable, so it is missing from
-	* the client entirely rather than typed onto reads that never carry it.
-	*/
-	warnWriteOnlyRelations(wireType, base, readable) {
-		const writeOnly = /* @__PURE__ */ new Set();
-		for (const request of [`${base}CreateRequest`, `${base}UpdateRequest`]) {
-			const data = this.schemas[request]?.properties?.["data"];
-			const relationships = isSchema$2(data) ? data.properties?.["relationships"] : void 0;
-			for (const name of Object.keys(isSchema$2(relationships) ? relationships.properties ?? {} : {})) if (!(name in readable)) writeOnly.add(name);
-		}
-		for (const name of writeOnly) console.warn(`json-api codegen: relationship "${name}" on "${wireType}" is accepted on writes but never rendered (a write-only relation); the client has no slot for a relation it can't read, so it is left out.`);
-	}
-	/**
 	* The server-level Atomic Operations capability: the path whose `POST` requestBody
 	* declares the atomic ext media type ({@link ATOMIC_EXT}). `null` when no such endpoint
 	* exists. Server-level, so it rides {@link buildAtomic}, not the per-type descriptor.
@@ -131,31 +180,106 @@ var DescriptorBuilder = class {
 		for (const [name, prop] of Object.entries(props)) if (isSchema$2(prop)) out[name] = formatHint(prop);
 		return sortRecord(out);
 	}
-	relations(resource, collection) {
-		const relProps = isSchema$2(resource.properties?.["relationships"]) ? resource.properties["relationships"].properties : void 0;
-		if (relProps === void 0) return {};
+	/**
+	* The relations of a type: every relation its resource renders, plus each write-only relation
+	* the create and update bodies accept. A write-only relation is one whose body property carries
+	* `writeOnly: true` (generator contract 8) or, in an older document, one the resource doesn't
+	* render. A pivot relation reads its response pivot off the rendered relationship and its
+	* request pivot off the write bodies.
+	*/
+	relations(wireType, base, resource, collection) {
+		const relProps = isSchema$2(resource.properties?.["relationships"]) ? resource.properties["relationships"].properties ?? {} : {};
+		const writes = this.writeRelationships(base);
+		const endpoints = this.relationEndpoints(wireType);
 		const out = {};
-		for (const [name, prop] of Object.entries(relProps)) {
-			if (!isSchema$2(prop) || typeof prop.$ref !== "string") continue;
-			const component = this.schemas[refName$1(prop.$ref) ?? ""];
-			const descriptor = component ? this.relationFromComponent(component) : void 0;
-			if (descriptor === void 0) {
+		const add = (name, component, writeOnly) => {
+			const parsed = component ? this.relationFromComponent(component) : void 0;
+			if (parsed === void 0) {
 				console.warn(`json-api codegen: relationship "${name}" has an unrecognized linkage shape; dropping it from the descriptor.`);
-				continue;
+				return;
+			}
+			const descriptor = { ...parsed };
+			if (writeOnly) {
+				delete descriptor.readPivot;
+				descriptor.writeOnly = true;
 			}
-			out[name] = collection === void 0 ? descriptor : this.withRelationExposure(descriptor, collection, name);
+			if (descriptor.pivot === true) {
+				const writePivot = this.writePivot(writes.get(name)?.ref ?? endpoints.get(name)?.requestRef, component);
+				if (writePivot !== void 0) descriptor.writePivot = writePivot;
+			}
+			out[name] = collection === void 0 ? descriptor : this.withRelationExposure(descriptor, collection, name, endpoints.get(name));
+		};
+		for (const [name, prop] of Object.entries(relProps)) {
+			if (!isSchema$2(prop) || typeof prop.$ref !== "string" || writes.get(name)?.writeOnly) continue;
+			add(name, this.schemas[refName$1(prop.$ref) ?? ""], false);
 		}
+		for (const [name, write] of writes) if (write.writeOnly || !(name in relProps)) add(name, this.schemas[refName$1(write.ref) ?? ""], true);
 		return sortRecord(out);
 	}
 	/**
+	* The relationships the create and update bodies accept: each one's component `$ref` and
+	* whether the body marks it `writeOnly`.
+	*/
+	writeRelationships(base) {
+		const out = /* @__PURE__ */ new Map();
+		for (const request of [`${base}CreateRequest`, `${base}UpdateRequest`]) {
+			const data = this.schemas[request]?.properties?.["data"];
+			const relationships = isSchema$2(data) ? data.properties?.["relationships"] : void 0;
+			const props = isSchema$2(relationships) ? relationships.properties ?? {} : {};
+			for (const [name, prop] of Object.entries(props)) {
+				if (!isSchema$2(prop) || typeof prop.$ref !== "string") continue;
+				const writeOnly = prop["writeOnly"] === true || out.get(name)?.writeOnly === true;
+				out.set(name, {
+					ref: out.get(name)?.ref ?? prop.$ref,
+					writeOnly
+				});
+			}
+		}
+		return out;
+	}
+	/**
+	* Each relation's related and relationship paths, keyed by relation name, from the
+	* operationIds the projector stamps (`fetchRelated.<type>.<relation>`, …). A relation's path
+	* segment is its URI field name, which may differ from its name, so the paths are never
+	* derived from the name when an operationId names them.
+	*/
+	relationEndpoints(wireType) {
+		const out = /* @__PURE__ */ new Map();
+		const entry = (rel) => {
+			let found = out.get(rel);
+			if (found === void 0) {
+				found = {};
+				out.set(rel, found);
+			}
+			return found;
+		};
+		for (const [path, item] of Object.entries(this.paths)) for (const [method, op] of Object.entries(item)) {
+			const id = op?.operationId;
+			if (typeof id !== "string") continue;
+			const dot = id.indexOf(".");
+			const prefix = id.slice(0, dot);
+			const rest = id.slice(dot + 1);
+			if (dot < 0 || !rest.startsWith(`${wireType}.`)) continue;
+			const rel = rest.slice(wireType.length + 1);
+			if (prefix === RELATED_OPERATION) entry(rel).related = path;
+			else if (RELATIONSHIP_OPERATIONS.includes(prefix)) {
+				const found = entry(rel);
+				found.relationship = path;
+				const ref = method === "get" ? void 0 : this.requestBodyRef(op);
+				if (ref !== void 0) found.requestRef = ref;
+			}
+		}
+		return out;
+	}
+	/**
 	* The per-relation mutation capability, derived from the HTTP methods the relationship
 	* endpoint (`{collection}/{id}/relationships/{rel}`) advertises. For a to-many:
 	* `add` <- POST, `remove` <- DELETE, `replace` <- PATCH. For a to-one: `set` <- PATCH.
 	* Only `true` verbs are emitted (a missing verb is simply absent). Returns `undefined`
 	* when the relation exposes no relationship endpoint at all.
 	*/
-	relationMutations(collection, rel, cardinality) {
-		const item = this.paths[`${collection}/{id}/relationships/${rel}`];
+	relationMutations(path, cardinality) {
+		const item = this.paths[path];
 		if (item === void 0) return;
 		const mutations = {};
 		if (cardinality === "many") {
@@ -175,19 +299,23 @@ var DescriptorBuilder = class {
 	* relationship endpoint exists, else `{}`) so the client gates a suppressed relation OFF rather
 	* than failing open (offering `.get()`/`.related()`/mutations that 404).
 	*/
-	withRelationExposure(descriptor, collection, name) {
+	withRelationExposure(descriptor, collection, name, endpoints) {
 		const out = { ...descriptor };
-		const relatedGet = this.operation(`${collection}/{id}/${name}`, "get");
+		const relatedPath = endpoints?.related ?? `${collection}/{id}/${name}`;
+		const relationshipPath = endpoints?.relationship ?? `${collection}/{id}/relationships/${name}`;
+		const segment = (endpoints?.related ?? endpoints?.relationship)?.split("/").pop();
+		if (segment !== void 0 && segment !== name) out.uriField = segment;
+		const relatedGet = this.operation(relatedPath, "get");
 		if (relatedGet === void 0) out.related = false;
-		const mutations = this.relationMutations(collection, name, descriptor.cardinality);
+		const mutations = this.relationMutations(relationshipPath, descriptor.cardinality);
 		if (mutations === void 0) {
 			out.relationship = false;
 			out.mutations = {};
 		} else out.mutations = mutations;
-		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(`${collection}/{id}/relationships/${name}`, "get"));
+		const countable = withCountParam(relatedGet) ?? withCountParam(this.operation(relationshipPath, "get"));
 		if (countable !== void 0) out.countable = countable;
 		if (descriptor.cardinality === "many") {
-			const relatedPaginator = this.paginatorOf(relatedGet) === "none" ? this.paginatorOf(this.operation(`${collection}/{id}/relationships/${name}`, "get")) : this.paginatorOf(relatedGet);
+			const relatedPaginator = this.paginatorOf(relatedGet) === "none" ? this.paginatorOf(this.operation(relationshipPath, "get")) : this.paginatorOf(relatedGet);
 			const relatedType = descriptor.types[0];
 			const typePaginator = relatedType !== void 0 ? this.typePaginator(relatedType) : "none";
 			if (relatedPaginator !== "none" && JSON.stringify(relatedPaginator) !== JSON.stringify(typePaginator)) out.paginator = relatedPaginator;
@@ -311,8 +439,8 @@ var DescriptorBuilder = class {
 					types: [type],
 					pivot: true
 				};
-				const pivotFields = this.pivotFieldsFromAllOf(items.allOf);
-				if (pivotFields !== void 0) relation.pivotFields = pivotFields;
+				const readPivot = this.pivotDescriptor(pivotNodeFromAllOf(items.allOf), "read");
+				if (readPivot !== void 0) relation.readPivot = readPivot;
 				return relation;
 			}
 			if (Array.isArray(items.anyOf)) return {
@@ -325,7 +453,7 @@ var DescriptorBuilder = class {
 		if (Array.isArray(data.anyOf)) {
 			const types = [];
 			let pivot = false;
-			let pivotFields;
+			let readPivot;
 			for (const entry of data.anyOf) if (typeof entry.$ref === "string") {
 				const type = this.resolveConst(entry.$ref);
 				if (type !== void 0) types.push(type);
@@ -334,7 +462,7 @@ var DescriptorBuilder = class {
 				if (type !== void 0) {
 					types.push(type);
 					pivot = true;
-					pivotFields = this.pivotFieldsFromAllOf(entry.allOf);
+					readPivot = this.pivotDescriptor(pivotNodeFromAllOf(entry.allOf), "read");
 				}
 			} else if (Array.isArray(entry.anyOf)) types.push(...this.constsFromRefs(entry.anyOf));
 			if (types.length === 0) return;
@@ -343,26 +471,44 @@ var DescriptorBuilder = class {
 				types,
 				pivot
 			};
-			if (pivotFields !== void 0) relation.pivotFields = pivotFields;
+			if (readPivot !== void 0) relation.readPivot = readPivot;
 			return relation;
 		}
 	}
 	/**
-	* Extract the pivot field-shape from a pivot `allOf` — the entry carrying
-	* `properties.meta.properties.pivot.properties` (a `belongsToMany` member's `meta.pivot`), as a
-	* field-name → wire-format-hint map (D33). Returns `undefined` when the allOf carries no pivot
-	* property block.
+	* The request pivot of a pivot relation: read off the component a write body (or a
+	* relationship mutation) refs, falling back to the rendered relationship's pivot minus its
+	* `readOnly` fields when no request shape is published (before generator contract 8).
+	*/
+	writePivot(ref, fallback) {
+		const component = ref === void 0 ? void 0 : this.schemas[refName$1(ref) ?? ""];
+		return this.pivotDescriptor(pivotNodeOf(component ?? fallback) ?? pivotNodeOf(fallback), "write");
+	}
+	/**
+	* A {@link PivotDescriptor} from a member's `meta.pivot` schema: field hints, the required
+	* fields and the nullable ones. Generator contract 8 refs a `<Type><Rel>Pivot` (response) or
+	* `<Type><Rel>WritePivot` (request) component, each with its own `required`. An older document
+	* inlines one shared schema in the write context, so a read takes every field as rendered and a
+	* write drops the `readOnly` ones. `undefined` when the schema has no fields.
 	*/
-	pivotFieldsFromAllOf(allOf) {
-		for (const entry of allOf) {
-			const meta = entry.properties?.["meta"];
-			const pivot = isSchema$2(meta) ? meta.properties?.["pivot"] : void 0;
-			const props = isSchema$2(pivot) ? pivot.properties : void 0;
-			if (props === void 0) continue;
-			const out = {};
-			for (const [name, schema] of Object.entries(props)) if (isSchema$2(schema)) out[name] = formatHint(schema);
-			return Object.keys(out).length > 0 ? sortRecord(out) : void 0;
+	pivotDescriptor(node, side) {
+		if (node === void 0) return;
+		const shared = typeof node.$ref !== "string";
+		const schema = shared ? node : this.schemas[refName$1(node.$ref) ?? ""];
+		const fields = {};
+		const nullable = [];
+		for (const [name, prop] of Object.entries(schema?.properties ?? {})) {
+			if (!isSchema$2(prop) || prop[side === "read" ? "writeOnly" : "readOnly"] === true) continue;
+			fields[name] = formatHint(prop);
+			if (isNullable(prop)) nullable.push(name);
 		}
+		const names = Object.keys(fields);
+		if (names.length === 0) return;
+		const required = shared && side === "read" ? names : names.filter((name) => schema?.required?.includes(name));
+		const out = { fields: sortRecord(fields) };
+		if (required.length < names.length) out.required = required.sort();
+		if (nullable.length > 0) out.nullable = nullable.sort();
+		return out;
 	}
 	/** Pull the related type from the `$ref` entry of an `allOf` (the pivot shape). */
 	constFromAllOf(allOf) {
@@ -544,6 +690,30 @@ var DescriptorBuilder = class {
 		return op?.responses?.["200"]?.content?.["application/vnd.api+json"]?.schema?.$ref;
 	}
 };
+/** The `meta.pivot` schema node of a pivot `allOf` entry list, if any. */
+function pivotNodeFromAllOf(allOf) {
+	for (const entry of allOf) {
+		const meta = entry.properties?.["meta"];
+		const pivot = isSchema$2(meta) ? meta.properties?.["pivot"] : void 0;
+		if (isSchema$2(pivot)) return pivot;
+	}
+}
+/**
+* The `meta.pivot` schema node of a relationship component or document: its to-many `items`
+* `allOf`, or a to-one `anyOf` entry's `allOf`.
+*/
+function pivotNodeOf(component) {
+	const data = component.properties?.["data"];
+	if (!isSchema$2(data)) return;
+	if (Array.isArray(data.items?.allOf)) return pivotNodeFromAllOf(data.items.allOf);
+	for (const entry of data.anyOf ?? []) if (Array.isArray(entry.allOf)) return pivotNodeFromAllOf(entry.allOf);
+}
+/** Whether a schema admits `null`: a `null` type, or a `null` branch in `anyOf`/`oneOf`. */
+function isNullable(schema) {
+	const type = schema.type;
+	if (type === "null" || Array.isArray(type) && type.includes("null")) return true;
+	return [...schema.anyOf ?? [], ...schema.oneOf ?? []].some((branch) => branch.type === "null");
+}
 /** A schema's wire format hint: explicit `format`, else the JSON type, else a ref-enum is `string`. */
 function formatHint(schema) {
 	if (typeof schema.format === "string") return schema.format;
@@ -735,7 +905,7 @@ function stampedMenu(schema, stamp, warn) {
 /** Below this the document predates the structures this codegen reads. */
 const MINIMUM_CONTRACT = 1;
 /** Above this the document carries structures this codegen does not read. */
-const MAXIMUM_CONTRACT = 7;
+const MAXIMUM_CONTRACT = 9;
 /**
 * Check the document's `info.x-generator.contract` against the range this codegen reads. A
 * document older than the range throws; a newer one returns a warning, because its new
@@ -745,8 +915,8 @@ const MAXIMUM_CONTRACT = 7;
 function checkContract(doc) {
 	const contract = doc.info?.["x-generator"]?.contract;
 	if (typeof contract !== "number") return;
-	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 7). Use an older codegen release, or regenerate the document from a newer server.`);
-	if (contract > 7) return `the document declares contract ${contract} and this codegen reads up to 7. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
+	if (contract < 1) throw new Error(`the document declares contract ${contract}, which predates what this codegen reads (it supports 1 to 9). Use an older codegen release, or regenerate the document from a newer server.`);
+	if (contract > 9) return `the document declares contract ${contract} and this codegen reads up to 9. It describes capabilities that were not generated; upgrade the codegen to pick them up.`;
 }
 //#endregion
 //#region src/error-codes.ts
@@ -1045,7 +1215,6 @@ function memberDoc(schema) {
 	return description ? `${description}\n\n${tags.join("\n")}` : tags.join("\n");
 }
 var Emitter = class {
-	doc;
 	descriptor;
 	atomic;
 	schemas;
@@ -1070,13 +1239,14 @@ var Emitter = class {
 	actionAliasNames = /* @__PURE__ */ new Map();
 	/** Provenance of the source document, stamped into the generated header for drift tracking. */
 	provenance;
-	constructor(doc, descriptor, atomic) {
-		this.doc = doc;
+	doc;
+	constructor(source, descriptor, atomic) {
 		this.descriptor = descriptor;
 		this.atomic = atomic;
-		this.schemas = doc.components?.schemas ?? {};
+		this.doc = unwrapRefs(source);
+		this.schemas = this.doc.components?.schemas ?? {};
 		this.baseByType = this.indexBases();
-		this.provenance = deriveProvenance(doc);
+		this.provenance = deriveProvenance(source);
 	}
 	/** Map each declared wire type back to the `Base` of its resource schema. */
 	indexBases() {
@@ -1662,4 +1832,4 @@ async function check(config) {
 //#endregion
 export { checkContract as _, readSchemas as a, buildDescriptor as b, detectVerbCollisions as c, hashJson as d, provenanceLines as f, MINIMUM_CONTRACT as g, MAXIMUM_CONTRACT as h, readDocument as i, emit as l, readErrorCatalogue as m, generate as n, emitSchemas as o, emitErrorCodes as p, schemasOutputPath as r, Emitter as s, check as t, deriveProvenance as u, DescriptorBuilder as v, buildAtomic as y };
 
-//# sourceMappingURL=src-BE7OMLWG.mjs.map
+//# sourceMappingURL=src-C2INS1Wd.mjs.map