@wildo-ai/saas-technical-doc 1.1.4 → 1.1.6

package/dist/esm/companion/openapi-generator.js

@@ -35,15 +35,20 @@
  *        cross this contract.
  *
  * @wildo-boundary
- *   Imports only the portable OpenAPI output contract, the local operation
- *   projection contract, the lightweight public runtime constants and
- *   specification-prose cleanup. No serializer, React or saas-models root
- *   barrel enters this semantic generator.
+ *   Imports the portable OpenAPI output contract, the local operation
+ *   projection contract, the lightweight public runtime constants (header
+ *   keys) and specification-prose cleanup. No serializer or React enters this
+ *   semantic generator. The saas-models ROOT barrel does, for the atoms not
+ *   carved into `public-runtime`: the error definitions, collection query
+ *   parameters, pagination request schema, the M2M webhook delivery contract
+ *   and the Idempotency-Key vocabulary. A module has ONE public door, so the
+ *   vocabulary is not re-exported from `public-runtime` as well.
  */
-import { WildoHeaderKeys } from '@wildo-ai/saas-models/public-runtime';
-import { COLLECTION_QUERY_PARAMETERS, ERROR_DEFINITIONS, ErrorHandling_Strategy, ErrorSeverity, ErrorType, M2M_WEBHOOK_DELIVERY_CONTRACT, Resources_PaginationRequestSchema, } from '@wildo-ai/saas-models';
+import { SUBMISSION_CHALLENGE_RESPONSE_MAX_LENGTH, SubmissionChallengeRefusalCode, SubmissionChallengeResponseKind, WildoHeaderKeys, } from '@wildo-ai/saas-models/public-runtime';
+import { COLLECTION_QUERY_PARAMETERS, ERROR_DEFINITIONS, IDEMPOTENCY_KEY_MAX_LENGTH, IdempotencyKeyRefusalCode, ErrorHandling_Strategy, ErrorSeverity, ErrorType, M2M_WEBHOOK_DELIVERY_CONTRACT, Resources_PaginationRequestSchema, } from '@wildo-ai/saas-models';
 import { OpenApiSection, } from '../openapi/openapi-generation-output.schemas.js';
 import { OpenApiGenerationInputSchema, OPENAPI_RESOURCE_IDENTITY_CONTRACT_VERSION, OperationProjectionAuthenticationMode, OperationProjectionVariantType, } from './operation-projection.schemas.js';
+import { attachDerivedExamples } from './openapi-example-derivation.js';
 import { stripImplementationNoise } from './spec-to-operation-doc.js';
 /**
  * Retains every projected URL-bearing operation.
@@ -599,25 +604,47 @@ function buildCollectionFilterQueryParameters(op) {
             parameter['explode'] = true;
         }
         parameter['schema'] = isPlainObject(propertySchema) ? propertySchema : {};
-        if (isPlainObject(propertySchema) && typeof propertySchema.description === 'string') {
-            parameter['description'] = propertySchema.description;
-        }
-        else if (isObjectValued) {
-            // No authored description on the range object — synthesise a truthful hint
-            // that names the deepObject bracket form for each sub-field it carries.
+        const fieldDescription = isPlainObject(propertySchema) && typeof propertySchema.description === 'string'
+            ? propertySchema.description
+            : undefined;
+        if (isObjectValued) {
+            // The wire form of a range filter is not guessable, so its deepObject bracket
+            // hint is stated whether or not the field also carries a meaning — the field's
+            // meaning (injected from its specification) says WHAT it filters, the hint says
+            // HOW to send it, and neither replaces the other.
             const subKeys = isPlainObject(propertySchema) && isPlainObject(propertySchema.properties)
                 ? Object.keys(propertySchema.properties)
                 : [];
             const bracketHint = subKeys.length > 0
                 ? subKeys.map((subKey) => `\`${name}[${subKey}]=…\``).join(' & ')
                 : `\`${name}[<field>]=…\``;
-            parameter['description'] =
-                `Object-valued filter — serialise each sub-field with deepObject bracket notation (${bracketHint}).`;
+            const wireHint = `Object-valued filter — serialise each sub-field with deepObject bracket notation (${bracketHint}).`;
+            parameter['description'] = fieldDescription === undefined ? wireHint : `${fieldDescription}\n\n${wireHint}`;
+        }
+        else if (fieldDescription !== undefined) {
+            parameter['description'] = fieldDescription;
         }
         parameters.push(attachParameterExamples(op, parameter));
     }
     return parameters;
 }
+/**
+ * The error-body identifiers one documented failure mode names, each written as the field a
+ * client reads it from. `error.type`, `error.customMessageReference` and `error.code` are three
+ * different fields; the prose used to call every one of them "error code", which sent a client to
+ * `error.code` for values that arrive in the other two.
+ */
+function errorScenarioIdentifiers(scenario) {
+    const identifiers = [];
+    if (scenario.errorType !== undefined)
+        identifiers.push(`\`error.type\`: \`${scenario.errorType}\``);
+    if (scenario.customMessageReference !== undefined) {
+        identifiers.push(`\`error.customMessageReference\`: \`${scenario.customMessageReference}\``);
+    }
+    if (scenario.errorCode !== undefined)
+        identifiers.push(`\`error.code\`: \`${scenario.errorCode}\``);
+    return identifiers;
+}
 /**
  * Framework-universal pagination defaults, mirrored from the backend
  * repository adapters (`_doList` in both the MongoDB and PostgreSQL resource
@@ -810,6 +837,24 @@ function buildOperationObject(op, operationId, errorResponseSchema) {
         if (isPlainObject(wildo))
             wildo['m2mNotifications'] = notifications.map((notification) => ({ ...notification }));
     }
+    /*
+     * The documented failure modes as DATA, beside the prose the error responses carry. A client, an
+     * SDK generator or the reference's errors table branches on these values; prose cannot be read
+     * that way, which is how a code used to exist only inside a sentence (#1620).
+     */
+    const errorScenarios = op.errorScenarios ?? [];
+    if (errorScenarios.length > 0) {
+        const wildo = operationObject['x-wildo'];
+        if (isPlainObject(wildo)) {
+            wildo['errorScenarios'] = errorScenarios.map((scenario) => ({
+                status: scenario.code,
+                when: scenario.when,
+                ...(scenario.errorType !== undefined && { errorType: scenario.errorType }),
+                ...(scenario.customMessageReference !== undefined && { customMessageReference: scenario.customMessageReference }),
+                ...(scenario.errorCode !== undefined && { errorCode: scenario.errorCode }),
+            }));
+        }
+    }
     const security = buildOperationSecurity(op);
     operationObject['security'] = security;
     if (op.access.authenticationMode !== OperationProjectionAuthenticationMode.PUBLIC && op.access.roleRequirements.length > 0) {
@@ -836,6 +881,35 @@ function buildOperationObject(op, operationId, errorResponseSchema) {
                 + 'Required for this sensitive operation and consumed when the request is authorized.',
         });
     }
+    if (op.idempotencyKey !== undefined) {
+        parameters.push({
+            name: op.idempotencyKey.headerName,
+            in: 'header',
+            required: op.idempotencyKey.required,
+            schema: { type: 'string', minLength: 1 },
+            examples: { 'One key per intended change': { value: '"8e03978e-40d5-43e8-bc93-6894a57f9324"' } },
+            description: 'Your identity for this one intended change: a quoted string (or a bare token) of 1 to '
+                + `${IDEMPOTENCY_KEY_MAX_LENGTH} printable ASCII characters (a UUID is typical). Send a new key for each new change and `
+                + 'the SAME key when you retry it, so a retry after a lost response receives the first outcome instead of running again.'
+                + (op.idempotencyKey.required ? ' Required: a request without it is refused.' : ' Optional: a request without it runs, but its retries are not deduplicated.'),
+        });
+    }
+    if (op.submissionChallenge !== undefined) {
+        parameters.push({
+            name: op.submissionChallenge.headerName,
+            in: 'header',
+            // Optional in the reference because it is conditional: asked only when the application declares a captcha provider,
+            // and only of a caller that is not signed in. The description states both conditions.
+            required: false,
+            schema: { type: 'string', minLength: 1, maxLength: SUBMISSION_CHALLENGE_RESPONSE_MAX_LENGTH },
+            description: 'Your answer to this application\'s submission challenge, as JSON. Asked only when the application protects its '
+                + 'public forms with a captcha provider, and only of a caller that is not signed in; a signed-in or machine caller '
+                + `omits it. Send either \`{"kind":"${SubmissionChallengeResponseKind.PROVIDER_TOKEN}","providerRef":"<captcha provider>",`
+                + `"token":"<vendor token>"}\` or a solved proof of work, \`{"kind":"${SubmissionChallengeResponseKind.PROOF_OF_WORK}",`
+                + `"challenge":{…},"number":<n>}\`, for a challenge fetched from `
+                + `GET ${op.submissionChallenge.proofOfWorkChallengePath}. Each proof of work is accepted once.`,
+        });
+    }
     if (op.acceptsIfMatch) {
         parameters.push({
             name: WildoHeaderKeys.IF_MATCH,
@@ -986,6 +1060,10 @@ const FRAMEWORK_OWNED_PROPERTY_DESCRIPTIONS = Object.freeze({
     createdAt: 'When the record was created, set by the application and never accepted from a client.',
     updatedAt: 'When the record last changed, set by the application on every write.',
     organizationId: 'The organization this record belongs to. It scopes every read and write: a caller only ever addresses records in an organization they are a member of.',
+    applicationId: 'The application this record belongs to, for a record scoped to the application rather than to one organization.',
+    // The USER scope foreign key `declarePolymorphicSchemas` injects on a user-scoped variant, as `organizationId` is for
+    // an organization-scoped one (#1625).
+    userId: 'The user this record belongs to, for a record scoped to one user rather than to an organization.',
     // retention-authority: N/A — an API consumer's ENGLISH description of what the two values mean,
     // rendered into the OpenAPI document. There is no emitter to consume here: the audience is a
     // person reading a schema, and the sentence has to say `active` and `retained` in words for the
@@ -995,6 +1073,29 @@ const FRAMEWORK_OWNED_PROPERTY_DESCRIPTIONS = Object.freeze({
     data: 'The page of records this response carries.',
     pagination: 'Where this page sits in the full result set — the page number, the page size, and the totals needed to ask for the next one.',
 });
+/**
+ * The four fields of the `pagination` block every collection response carries (#1625). One shape,
+ * built by `createPaginationResponseMetadataSchema` and owned by no resource, so it was 272
+ * undescribed properties in Wonder Todos' API document alone — the same four, once per list.
+ *
+ * Applied only INSIDE a property named `pagination`, where these names mean exactly this; a
+ * resource's own `page` or `total` field is never touched. `totalPages` is `0` for an empty result on
+ * every adapter, computed by one function since #1714.
+ */
+const PAGINATION_PROPERTY_DESCRIPTIONS = Object.freeze({
+    page: 'The page this response carries, counted from 1.',
+    limit: 'How many records a page holds: the `limit` the request asked for, or the default when it asked for none.',
+    total: 'How many records match the request, across every page.',
+    totalPages: 'How many pages of `limit` records the matching set spans: `0` when nothing matches. Ask for pages 1 to `totalPages`.',
+});
+/** An authored description always wins; these fill gaps. */
+function fillMissingDescriptions(properties, descriptions) {
+    for (const [name, description] of Object.entries(descriptions)) {
+        const property = properties[name];
+        if (isPlainObject(property) && property['description'] === undefined)
+            property['description'] = description;
+    }
+}
 /**
  * The structural signature of a MATERIALIZED resource document in a response
  * schema is the `_id` property. The serializer attaches `_version` /
@@ -1085,6 +1186,9 @@ function fillFrameworkOwnedPropertyDescriptions(node) {
             if (framework !== undefined && property['description'] === undefined) {
                 property['description'] = framework;
             }
+            if (name === 'pagination' && isPlainObject(property['properties'])) {
+                fillMissingDescriptions(property['properties'], PAGINATION_PROPERTY_DESCRIPTIONS);
+            }
             fillFrameworkOwnedPropertyDescriptions(property);
         }
     }
@@ -1176,9 +1280,8 @@ function buildResponsesObject(op, responseBodySchema, errorResponseSchema) {
         responses['204'] = { description: 'No Content' };
     }
     for (const error of op.errorScenarios ?? []) {
-        const description = error.errorCode !== undefined
-            ? `${error.when} (error code: \`${error.errorCode}\`)`
-            : error.when;
+        const identifiers = errorScenarioIdentifiers(error);
+        const description = identifiers.length > 0 ? `${error.when} (${identifiers.join(', ')})` : error.when;
         const errorJsonMedia = { schema: errorResponseSchema };
         const examples = responseExamplesByStatus.get(error.code);
         if (examples !== undefined) {
@@ -1197,19 +1300,30 @@ function buildResponsesObject(op, responseBodySchema, errorResponseSchema) {
             };
         }
     }
-    if (op.acceptsIfMatch) {
-        const mergeFrameworkError = (code, description) => {
-            const existing = responses[code];
-            if (isPlainObject(existing) && typeof existing['description'] === 'string') {
-                existing['description'] = `${existing['description']}\n\n${description}`;
-                existing['content'] = { 'application/json': { schema: errorResponseSchema } };
-                return;
-            }
-            responses[code] = {
-                description,
-                content: { 'application/json': { schema: errorResponseSchema } },
-            };
+    // A framework-owned outcome merged into an operation's response map, beside whatever its specification authored.
+    const mergeFrameworkError = (code, description) => {
+        const existing = responses[code];
+        if (isPlainObject(existing) && typeof existing['description'] === 'string') {
+            existing['description'] = `${existing['description']}\n\n${description}`;
+            existing['content'] = { 'application/json': { schema: errorResponseSchema } };
+            return;
+        }
+        responses[code] = {
+            description,
+            content: { 'application/json': { schema: errorResponseSchema } },
         };
+    };
+    if (op.idempotencyKey !== undefined) {
+        mergeFrameworkError('400', `The \`${op.idempotencyKey.headerName}\` header is malformed (\`error.code\` \`${IdempotencyKeyRefusalCode.MALFORMED}\`)`
+            + (op.idempotencyKey.required ? `, or missing (\`${IdempotencyKeyRefusalCode.REQUIRED}\`).` : '.'));
+    }
+    if (op.submissionChallenge !== undefined) {
+        mergeFrameworkError('400', `The application protects this operation with a submission challenge and a caller who is not signed in sent no \``
+            + `${op.submissionChallenge.headerName}\` header (\`error.code\` \`${SubmissionChallengeRefusalCode.REQUIRED}\`), or an answer `
+            + `it did not accept: a refused vendor token, or a proof of work that is wrong, expired or already used `
+            + `(\`${SubmissionChallengeRefusalCode.REFUSED}\`). Fetch a fresh proof-of-work challenge and send the request again.`);
+    }
+    if (op.acceptsIfMatch) {
         mergeFrameworkError('400', 'The optional `If-Match` header is present but does not contain a non-negative integer resource version.');
         mergeFrameworkError('409', 'The `If-Match` version no longer matches the current resource version, so the mutation was not applied.');
     }
@@ -1267,6 +1381,17 @@ const GENERATOR_OWNED_ERROR_RESPONSE_NAMES = Object.freeze({
     [OperationProjectionAuthenticationMode.PUBLIC]: 'Unauthorized',
 });
 const INTERNAL_ERROR_RESPONSE_NAME = 'InternalServerError';
+/** The status each shared `components.responses` entry answers with, read by the example pass. */
+function errorStatusByComponentResponseName() {
+    return new Map([
+        [INTERNAL_ERROR_RESPONSE_NAME, '500'],
+        ...[
+            OperationProjectionAuthenticationMode.ANONYMOUS_SESSION,
+            OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED,
+            OperationProjectionAuthenticationMode.AUTHENTICATED,
+        ].map((mode) => [unauthorizedResponseName(mode), '401']),
+    ]);
+}
 function unauthorizedResponseName(mode) {
     return GENERATOR_OWNED_ERROR_RESPONSE_NAMES[mode];
 }
@@ -1294,14 +1419,16 @@ function unauthorizedDescription(mode) {
  * entry of its own: a public operation never gets a synthesised 401.
  */
 function buildErrorResponseComponents(usedNames, errorResponseSchema) {
-    const content = { 'application/json': { schema: errorResponseSchema } };
-    const all = { [INTERNAL_ERROR_RESPONSE_NAME]: { description: internalServerErrorDescription(), content } };
+    // One content object PER entry: the example pass writes each one's own example into it, and a
+    // shared object would make the last write every entry's example.
+    const content = () => ({ 'application/json': { schema: errorResponseSchema } });
+    const all = { [INTERNAL_ERROR_RESPONSE_NAME]: { description: internalServerErrorDescription(), content: content() } };
     for (const mode of [
         OperationProjectionAuthenticationMode.ANONYMOUS_SESSION,
         OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED,
         OperationProjectionAuthenticationMode.AUTHENTICATED,
     ]) {
-        all[unauthorizedResponseName(mode)] = { description: unauthorizedDescription(mode), content };
+        all[unauthorizedResponseName(mode)] = { description: unauthorizedDescription(mode), content: content() };
     }
     return Object.fromEntries(Object.entries(all).filter(([name]) => usedNames.has(name)));
 }
@@ -1499,6 +1626,44 @@ function componentSchemaName(op, role) {
  * Returns a described COPY. The caller's schema belongs to the projection input and a pin asserts
  * the generator leaves its input untouched.
  */
+/**
+ * The error envelope's remaining fields, by their path under the envelope root (#1625). `type` and
+ * `severity` are described from `ERROR_DEFINITIONS` below; these are the rest of what
+ * `ErrorHandlerService.sendErrorResponse` writes, and each sentence states what that method puts
+ * there. `message` and `customMessage` both carry the error's message reference, not prose: the
+ * words are the client's to render in its reader's language.
+ */
+const ERROR_ENVELOPE_PROPERTY_DESCRIPTIONS = Object.freeze({
+    'error': 'What went wrong. The application\'s error responses carry this one object.',
+    'error.message': 'The message reference for this failure, the same value as `customMessageReference`. It is a key for a message catalog, not a sentence to show a reader.',
+    'error.customMessage': 'The message reference for this failure, the same value as `message` and `customMessageReference`.',
+    'error.customMessageReference': 'A stable key naming this failure more precisely than `type` (for example `controller_resource_not_found`). Use it to choose the message you show.',
+    'error.code': 'A stable, operation-specific refusal code such as `LAST_ORGANIZATION_OWNER`, present when the operation declares one. Branch on this for the refusals an operation documents.',
+    'error.operationPath': 'Which operation refused the request, as the application names it internally. Useful in a support request; do not branch on it.',
+    'error.correlationId': 'An identifier for this request. Quote it in a support request: it joins this response to the application\'s own logs and audit records.',
+    'error.details': 'Extra facts about the failure that are safe to return. Present only for some failures; the keys depend on the failure.',
+    'error.details.versionConflict': 'Present when an update was refused because the record changed since it was read. Re-read the record, reapply the change, and retry.',
+    'error.details.versionConflict.currentVersion': 'The version the record is at now.',
+    'error.details.versionConflict.expectedVersion': 'The version the request was based on.',
+    'error.details.versionConflict.conflictingFields': 'The field paths the request submitted whose value differs from the record as it is now.',
+    'error.details.versionConflict.currentValues': 'The record as it is now, in the shape a read returns.',
+    'error.details.versionConflict.submittedValues': 'The values the request submitted.',
+    'error.timestamp': 'When the failure happened (ISO 8601, UTC).',
+    'error.initiatorIds': 'Who the application understood the request to come from: the organization, user or application identifiers it resolved. Absent or `null` when it resolved none.',
+    'error.validationErrors': 'Present on a validation failure: each key is a field path and each value is either a message or a `{ code, params }` entry naming the problem, so a form can show it beside the field.',
+    'error.userGuidance': 'Present when the application can say how to resolve the failure: an explanation, a resolution and, where it applies, a next action.',
+    'error.userGuidance.guidanceKey': 'A stable key for this guidance, to look up localized wording. When absent, use `customMessageReference`.',
+    'error.userGuidance.explanation': 'What went wrong, in the application\'s own words.',
+    'error.userGuidance.resolution': 'What to do about it.',
+    'error.userGuidance.params': 'Values the localized guidance wording interpolates.',
+    'error.userGuidance.completedSteps': 'Steps that had already completed before the failure.',
+    'error.userGuidance.nextAction': 'The suggested next step.',
+    'error.userGuidance.nextAction.label': 'A short label for the next step.',
+    'error.userGuidance.nextAction.ref': 'The operation path or URL the next step goes to.',
+    'error.userGuidance.nextAction.type': 'Whether `ref` names an operation or a URL.',
+    'error.userGuidance.retryAfterSeconds': 'On a rate limit: how many seconds to wait before retrying.',
+    'error.userGuidance.missingConfiguration': 'On a configuration failure: the configuration the application is missing.',
+});
 function describeFrameworkErrorEnvelopeEnums(schema) {
     if (!isPlainObject(schema))
         return schema;
@@ -1537,6 +1702,27 @@ function describeFrameworkErrorEnvelopeEnums(schema) {
             visit(entry);
     };
     visit(described);
+    const describeProperties = (node, prefix) => {
+        if (!isPlainObject(node))
+            return;
+        for (const key of ['anyOf', 'oneOf', 'allOf']) {
+            const branches = node[key];
+            if (Array.isArray(branches))
+                for (const branch of branches)
+                    describeProperties(branch, prefix);
+        }
+        const properties = node['properties'];
+        if (!isPlainObject(properties))
+            return;
+        for (const [name, property] of Object.entries(properties)) {
+            const path = prefix === '' ? name : `${prefix}.${name}`;
+            const description = ERROR_ENVELOPE_PROPERTY_DESCRIPTIONS[path];
+            if (isPlainObject(property) && description !== undefined && property['description'] === undefined)
+                property['description'] = description;
+            describeProperties(property, path);
+        }
+    };
+    describeProperties(described, '');
     return described;
 }
 function createSchemaRegistry() {
@@ -1587,6 +1773,91 @@ function createSchemaRegistry() {
         },
     };
 }
+const COMPONENT_SCHEMA_REF_PREFIX = '#/components/schemas/';
+/**
+ * One object definition per resource: "the Tasks object" (#1621).
+ *
+ * Every operation hoists its own named body component, so a resource's representation used to be
+ * published once per operation that returns it. Measured on the Wonder Todos document of 2026-09-24:
+ * 135 response components and 80 list-row schemas were byte-identical to their resource's read
+ * representation, each carrying the same field documentation — 215 copies, and no single place a
+ * reader could learn what a task IS.
+ *
+ * This pass names each resource's canonical read representation after the resource (`Tasks`) and
+ * folds into it every response component OF THAT RESOURCE whose content is identical (ignoring the
+ * per-operation description), plus every list's `data[]` rows that are. A context or summary shape
+ * that differs keeps its own component: identity is decided by CONTENT, never assumed from the verb.
+ *
+ * Folding removes per-operation component names, which are public identities. That is safe because
+ * no authored guide links to a component schema (guides link resources and operation families), and
+ * the link index fails publication closed if one ever does.
+ *
+ * Mutates `paths`, `schemas` and `canonicalReadResponseRefByResource` (so the webhooks block, which
+ * sends the resource document itself, references the object). Returns the object name per resource.
+ */
+function consolidateResourceObjects(paths, schemas, canonicalReadResponseRefByResource, responseComponentOwner, purposeByResourceIdentifier) {
+    const contentOf = (schema) => {
+        if (!isPlainObject(schema))
+            return stableStringify(schema);
+        const { description: _description, $schema: _dialect, ...content } = schema;
+        return stableStringify(content);
+    };
+    const objectNameByResource = new Map();
+    const replacement = new Map();
+    const objectContentByName = new Map();
+    for (const [resourceIdentifier, readRef] of [...canonicalReadResponseRefByResource.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        const readSchema = schemas[readRef.slice(COMPONENT_SCHEMA_REF_PREFIX.length)];
+        if (!isPlainObject(readSchema))
+            continue;
+        let objectName = pascal(resourceIdentifier);
+        for (let suffix = 2; schemas[objectName] !== undefined; suffix += 1)
+            objectName = `${pascal(resourceIdentifier)}Object${suffix === 2 ? '' : suffix}`;
+        const purpose = purposeByResourceIdentifier.get(resourceIdentifier);
+        const { description: _description, ...content } = readSchema;
+        schemas[objectName] = {
+            ...content,
+            description: `The \`${resourceIdentifier}\` resource as the API returns it.${purpose === undefined ? '' : ` ${stripImplementationNoise(purpose)}`}`,
+        };
+        const objectContent = contentOf(readSchema);
+        objectNameByResource.set(resourceIdentifier, objectName);
+        objectContentByName.set(objectName, objectContent);
+        for (const [ref, owner] of responseComponentOwner) {
+            if (owner !== resourceIdentifier)
+                continue;
+            const name = ref.slice(COMPONENT_SCHEMA_REF_PREFIX.length);
+            const candidate = schemas[name];
+            if (!isPlainObject(candidate))
+                continue;
+            if (contentOf(candidate) === objectContent) {
+                replacement.set(ref, `${COMPONENT_SCHEMA_REF_PREFIX}${objectName}`);
+                continue;
+            }
+            const data = isPlainObject(candidate['properties']) ? candidate['properties']['data'] : undefined;
+            if (isPlainObject(data) && data['type'] === 'array' && contentOf(data['items']) === objectContent) {
+                data['items'] = { $ref: `${COMPONENT_SCHEMA_REF_PREFIX}${objectName}` };
+            }
+        }
+        canonicalReadResponseRefByResource.set(resourceIdentifier, `${COMPONENT_SCHEMA_REF_PREFIX}${objectName}`);
+    }
+    for (const ref of replacement.keys())
+        delete schemas[ref.slice(COMPONENT_SCHEMA_REF_PREFIX.length)];
+    const rewrite = (node) => {
+        if (Array.isArray(node)) {
+            for (const entry of node)
+                rewrite(entry);
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        const ref = node['$ref'];
+        if (typeof ref === 'string' && replacement.has(ref))
+            node['$ref'] = replacement.get(ref);
+        for (const entry of Object.values(node))
+            rewrite(entry);
+    };
+    rewrite(paths);
+    return objectNameByResource;
+}
 /**
  * Replace an operation object's inline request/response BODY schemas with
  * `$ref`s into `components/schemas` (via `registry`). Walks only the
@@ -1760,6 +2031,9 @@ function buildOpenApiDocument(section, operations, input) {
      * reference rather than a guess — and a resource with no read operation simply gets prose.
      */
     const canonicalReadResponseRefByResource = new Map();
+    // The resource each response component was hoisted for, so the resource-object pass below only
+    // ever folds a resource's OWN representations into its object.
+    const responseComponentOwner = new Map();
     const paths = {};
     const ownershipByPathAndVerb = new Map();
     const tagSet = new Set();
@@ -1772,6 +2046,9 @@ function buildOpenApiDocument(section, operations, input) {
     // ones get `2`, `3`, … — applied here rather than in the projector because
     // uniqueness is a per-document (per-section) property.
     const operationIdUseCount = new Map();
+    // Each published operation id's projection, so the example pass can compose an error body from
+    // that operation's own documented scenarios.
+    const projectionByOperationId = new Map();
     const schemaRegistry = createSchemaRegistry();
     // The schema comes from the same model the backend error handler serializes.
     // Register before per-operation hoisting so every non-success response shares
@@ -1801,6 +2078,7 @@ function buildOpenApiDocument(section, operations, input) {
         operationIdUseCount.set(baseOperationId, priorUses + 1);
         const operationId = priorUses === 0 ? baseOperationId : `${baseOperationId}${priorUses + 1}`;
         const operationObject = buildOperationObject(op, operationId, errorResponseSchema);
+        projectionByOperationId.set(operationId, op);
         for (const response of Object.values((operationObject['responses'] ?? {}))) {
             const ref = isPlainObject(response) ? response['$ref'] : undefined;
             if (typeof ref === 'string' && ref.startsWith('#/components/responses/')) {
@@ -1830,6 +2108,13 @@ function buildOpenApiDocument(section, operations, input) {
             operationObject['description'] = existing.length > 0 ? `${existing}\n\n${note}` : note;
         }
         hoistOperationSchemas(operationObject, op, schemaRegistry, purposeByResourceIdentifier.get(op.resourceIdentifier));
+        for (const response of Object.values((operationObject['responses'] ?? {}))) {
+            const media = isPlainObject(response) && isPlainObject(response['content']) ? response['content']['application/json'] : undefined;
+            const ref = isPlainObject(media) && isPlainObject(media['schema']) ? media['schema']['$ref'] : undefined;
+            if (typeof ref === 'string' && ref.startsWith(COMPONENT_SCHEMA_REF_PREFIX) && !responseComponentOwner.has(ref)) {
+                responseComponentOwner.set(ref, op.resourceIdentifier);
+            }
+        }
         if (op.baseOperationIdentifier === 'read' && splitOperationQualifiers(op).via.length === 0 && !canonicalReadResponseRefByResource.has(op.resourceIdentifier)) {
             const okSchema = (operationObject['responses']?.['200']?.content?.['application/json']?.schema);
             if (typeof okSchema?.$ref === 'string')
@@ -1853,8 +2138,9 @@ function buildOpenApiDocument(section, operations, input) {
         }
         resourceTagsByName.set(tag.name, tag);
     }
+    const objectSchemaNameByResource = consolidateResourceObjects(paths, schemaRegistry.schemas(), canonicalReadResponseRefByResource, responseComponentOwner, purposeByResourceIdentifier);
     const webhooks = buildWebhooksObject(sortedOps, canonicalReadResponseRefByResource);
-    return {
+    const document = {
         openapi: '3.1.0',
         info: {
             title: `${titleBase} ${sectionLabel}`,
@@ -1878,6 +2164,7 @@ function buildOpenApiDocument(section, operations, input) {
                 ...(descriptor?.lifecycleRole === undefined ? {} : { lifecycleRole: stripImplementationNoise(descriptor.lifecycleRole) }),
                 ...(descriptor?.relationships === undefined ? {} : { relationships: descriptor.relationships }),
                 ...(descriptor?.category === undefined ? {} : { category: descriptor.category }),
+                ...(objectSchemaNameByResource.has(tagName) ? { objectSchema: objectSchemaNameByResource.get(tagName) } : {}),
             };
             const tag = {
                 name: tagName,
@@ -1906,6 +2193,9 @@ function buildOpenApiDocument(section, operations, input) {
             securitySchemes: SECURITY_SCHEMES,
         },
     };
+    // Every JSON body with no authored example gets a derived one, marked as generated (#1619).
+    attachDerivedExamples(document, projectionByOperationId, errorStatusByComponentResponseName());
+    return document;
 }
 /**
  * Counts the unique `resourceIdentifier` values among a set of