@wildo-ai/saas-technical-doc 1.1.1 → 1.1.3

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

@@ -41,6 +41,7 @@
  *   barrel enters this semantic generator.
  */
 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 { OpenApiSection, } from '../openapi/openapi-generation-output.schemas.js';
 import { OpenApiGenerationInputSchema, OPENAPI_RESOURCE_IDENTITY_CONTRACT_VERSION, OperationProjectionAuthenticationMode, OperationProjectionVariantType, } from './operation-projection.schemas.js';
 import { stripImplementationNoise } from './spec-to-operation-doc.js';
@@ -344,6 +345,58 @@ function extractPathParameters(path) {
     const matches = path.matchAll(/\{([^}]+)\}/gu);
     return Array.from(matches, (match) => match[1]);
 }
+/**
+ * What a path placeholder identifies, read off the path rather than guessed from its name.
+ *
+ * Measured on Wonder CRM: 0 of 911 path parameters carried a description while query parameters
+ * were 85% covered and headers 100% — so a reader looking at `/organizations/{organizationId}/deal/
+ * {dealId}` was told what every filter meant and nothing about the two values they must supply.
+ *
+ * The segment BEFORE a placeholder names the collection it addresses, which is the fact that makes
+ * this derivable rather than invented. The last placeholder addresses the operation's own resource;
+ * the earlier ones are the scope it lives in, and saying so is what tells a caller which id goes
+ * where. The collection name is quoted verbatim, never humanized: it is the identifier the API
+ * itself uses, so a reader can match it against the path, the tag and the payload.
+ */
+function describePathParameter(path, parameterName, resourceIdentifier) {
+    const segments = path.split('/').filter((segment) => segment.length > 0);
+    const placeholderIndex = segments.indexOf(`{${parameterName}}`);
+    const owningCollection = placeholderIndex > 0 ? segments[placeholderIndex - 1] : undefined;
+    if (owningCollection === undefined || owningCollection.startsWith('{')) {
+        return `Identifier supplied in the request path as \`${parameterName}\`.`;
+    }
+    return owningCollection === resourceIdentifier
+        ? `Identifier of the \`${owningCollection}\` this operation addresses.`
+        : `Identifier of the \`${owningCollection}\` the addressed record belongs to.`;
+}
+/**
+ * Splits an operation's qualifier tail into the two kinds that look alike and mean opposite things.
+ *
+ * `Via<Parent>` qualifiers are ROUTING: the same operation reached through a different parent, so
+ * `GET /organizations/{organizationId}/organization-members/{id}` and
+ * `GET /users/{userId}/organization-members/{id}` are one operation at two addresses. Every other
+ * qualifier — `summary`, `context`, `BULK` — is a genuinely different operation with a different
+ * response.
+ *
+ * Conflating them is what makes the reference look four times its real size. Measured on Wonder
+ * CRM: 546 operations at 439 paths, of which 486 are another path's operation repeated —
+ * `organizationMembers` publishes its whole surface three times.
+ */
+function splitOperationQualifiers(op) {
+    const tail = op.operationKey.startsWith(op.baseOperationIdentifier)
+        ? op.operationKey.slice(op.baseOperationIdentifier.length)
+        : '';
+    const segments = tail.split('_').filter(Boolean);
+    return {
+        via: segments.filter((segment) => segment.startsWith('Via')),
+        shape: segments.filter((segment) => !segment.startsWith('Via')),
+    };
+}
+/** The identity an alias shares with the one canonical route of the same operation. */
+function canonicalRouteKey(op) {
+    const { shape } = splitOperationQualifiers(op);
+    return [op.resourceIdentifier, op.baseOperationIdentifier, shape.join('_'), op.httpVerb].join('\u0000');
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -403,7 +456,7 @@ function buildQueryParametersFromRequestSchema(op) {
     // operation. The flat trio names are excluded too so a DTO can never collide with
     // them. Ops WITHOUT the pagination contract keep every DTO property untouched.
     const paginationAxisProperties = op.pagination !== undefined
-        ? new Set(['pagination', 'sorting', 'filters', 'page', 'limit', 'sort'])
+        ? new Set(['pagination', 'sorting', 'filters', COLLECTION_QUERY_PARAMETERS.page, COLLECTION_QUERY_PARAMETERS.limit, COLLECTION_QUERY_PARAMETERS.sort])
         : new Set();
     return Object.entries(properties)
         .filter(([name]) => !paginationAxisProperties.has(name))
@@ -522,7 +575,7 @@ function buildCollectionFilterQueryParameters(op) {
     // nested fallback name, so it is surfaced under the wire name, not verbatim.
     if ('searchRequest' in filterProperties) {
         parameters.push(attachParameterExamples(op, {
-            name: 'q',
+            name: COLLECTION_QUERY_PARAMETERS.search,
             in: 'query',
             required: false,
             schema: { type: 'string' },
@@ -574,8 +627,9 @@ function buildCollectionFilterQueryParameters(op) {
  * must not import `@wildo-ai/saas-backend-lib`); keep in sync with the
  * repository defaults.
  */
-const PAGINATION_DEFAULT_PAGE = 1;
-const PAGINATION_DEFAULT_LIMIT = 20;
+// Defaults are read off the shared pagination request schema, never restated.
+const PAGINATION_DEFAULT_PAGE = Resources_PaginationRequestSchema.shape.page.parse(undefined);
+const PAGINATION_DEFAULT_LIMIT = Resources_PaginationRequestSchema.shape.limit.parse(undefined);
 /**
  * Emits the flat `page` / `limit` / `sort` query parameters for a paginated
  * collection operation (`op.pagination` present — LIST / SEARCH-like; see the
@@ -613,21 +667,21 @@ function buildPaginationQueryParameters(op) {
             + '(e.g. `createdAt:desc`). Defaults to `createdAt:desc` (newest first).';
     return [
         {
-            name: 'page',
+            name: COLLECTION_QUERY_PARAMETERS.page,
             in: 'query',
             required: false,
             schema: { type: 'integer', minimum: 1, default: PAGINATION_DEFAULT_PAGE },
             description: '1-based page number of the collection slice.',
         },
         {
-            name: 'limit',
+            name: COLLECTION_QUERY_PARAMETERS.limit,
             in: 'query',
             required: false,
             schema: { type: 'integer', minimum: 1, maximum: pagination.maxLimit, default: PAGINATION_DEFAULT_LIMIT },
             description: `Maximum number of items per page (up to ${pagination.maxLimit}).`,
         },
         {
-            name: 'sort',
+            name: COLLECTION_QUERY_PARAMETERS.sort,
             in: 'query',
             required: false,
             schema: { type: 'string' },
@@ -736,6 +790,26 @@ function buildOperationObject(op, operationId, errorResponseSchema) {
     // Auth (Tier-1 framework knowledge). The source projector resolves access
     // semantics once; this generator only transports that fact into standard
     // OpenAPI `security` and the companion `x-wildo` extension.
+    /*
+     * Say that this call notifies, where the reader is standing.
+     *
+     * A developer looking at `changeStatus` needs to know it does more than change a record: every
+     * endpoint configured on that channel receives a delivery. The mechanics — retries, signature,
+     * how to verify — are the webhook contract's and are described once at the document's `webhooks`
+     * block, not restated on each of the operations that fire one.
+     */
+    const notifications = op.m2mNotifications ?? [];
+    if (notifications.length > 0) {
+        const channels = [...new Set(notifications.map((notification) => notification.channel))].sort();
+        const note = `A successful call also delivers an outbound webhook on ${channels.length === 1 ? 'the ' : ''}`
+            + `${channels.map((channel) => `\`${channel}\``).join(' and ')} channel${channels.length === 1 ? '' : 's'}`
+            + ', to every endpoint an organization has configured and enabled there. See this document\'s `webhooks` for the delivery contract.';
+        const existing = typeof operationObject['description'] === 'string' ? operationObject['description'] : '';
+        operationObject['description'] = existing.length > 0 ? `${existing}\n\n${note}` : note;
+        const wildo = operationObject['x-wildo'];
+        if (isPlainObject(wildo))
+            wildo['m2mNotifications'] = notifications.map((notification) => ({ ...notification }));
+    }
     const security = buildOperationSecurity(op);
     operationObject['security'] = security;
     if (op.access.authenticationMode !== OperationProjectionAuthenticationMode.PUBLIC && op.access.roleRequirements.length > 0) {
@@ -749,6 +823,7 @@ function buildOperationObject(op, operationId, errorResponseSchema) {
             in: 'path',
             required: true,
             schema: { type: 'string' },
+            description: describePathParameter(op.path, paramName, op.resourceIdentifier),
         })));
     }
     if (op.stepUpAuthentication !== undefined) {
@@ -888,6 +963,34 @@ const ENGINE_METADATA_PROPERTY_SCHEMAS = {
             + 'conflict-free merges of concurrent edits. Opaque to clients — safe to ignore.',
     },
 };
+/**
+ * Descriptions for the properties EVERY resource carries and NO resource authors.
+ *
+ * `_version` and `_field_meta` above are injected by the generator, so they were described where
+ * they are created. These are different: they are real fields on the document, present on every
+ * resource, and therefore owned by no single resource specification — which is exactly why they
+ * were the most undescribed properties in the whole reference. Measured on Wonder CRM:
+ *
+ *   data 123 · pagination 123 · retentionStatus 104 · impersonalizedAt 104 · _id 90 ·
+ *   createdAt 65 · updatedAt 64 · organizationId 48
+ *
+ * — 721 of the 1,091 undescribed top-level properties, from eight names that mean the same thing
+ * everywhere. Asking every resource to describe them would be hundreds of copies of one sentence.
+ *
+ * An AUTHORED description always wins: this fills a gap, it never overrides a specification. That
+ * matters for names an application could legitimately reuse — a resource of its own with a field
+ * called `data` describes it, and this map stays out of the way.
+ */
+const FRAMEWORK_OWNED_PROPERTY_DESCRIPTIONS = Object.freeze({
+    _id: 'The record’s identifier. Stable for the life of the record and the value every path parameter and reference uses.',
+    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.',
+    retentionStatus: 'Whether the record is still `active` or has been `retained` — kept for a legal or accounting obligation after the person it concerned was erased. A retained record has had its personal detail removed.',
+    impersonalizedAt: 'When personal detail was stripped from this record, if it ever was. Absent on a record that has not been through erasure.',
+    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 structural signature of a MATERIALIZED resource document in a response
  * schema is the `_id` property. The serializer attaches `_version` /
@@ -953,11 +1056,47 @@ function injectEngineMetadataIntoEntitySchemas(schema) {
  * (`stableStringify`) still collapses them onto one component. Non-object
  * schemas (`null` / scalar) pass through unchanged.
  */
+/**
+ * Fills a description on the properties every resource carries and none authors.
+ *
+ * Recursive, because these appear at every depth: `data` and `pagination` wrap the envelope,
+ * `_id` and `createdAt` sit on the document inside it, and a `context`-mode response nests another
+ * collection again. Never overrides an authored description — a specification that describes its
+ * own field wins, which is what keeps this safe for a name an application might reuse.
+ */
+function fillFrameworkOwnedPropertyDescriptions(node) {
+    if (Array.isArray(node)) {
+        for (const entry of node)
+            fillFrameworkOwnedPropertyDescriptions(entry);
+        return;
+    }
+    if (!isPlainObject(node))
+        return;
+    const properties = node['properties'];
+    if (isPlainObject(properties)) {
+        for (const [name, property] of Object.entries(properties)) {
+            if (!isPlainObject(property))
+                continue;
+            const framework = FRAMEWORK_OWNED_PROPERTY_DESCRIPTIONS[name];
+            if (framework !== undefined && property['description'] === undefined) {
+                property['description'] = framework;
+            }
+            fillFrameworkOwnedPropertyDescriptions(property);
+        }
+    }
+    for (const key of ['items', 'allOf', 'oneOf', 'anyOf', 'additionalProperties']) {
+        if (key in node)
+            fillFrameworkOwnedPropertyDescriptions(node[key]);
+    }
+}
 function augmentResponseSchemaWithEngineMetadata(responseBodySchema) {
     if (!isPlainObject(responseBodySchema)) {
         return responseBodySchema;
     }
     const clone = structuredClone(responseBodySchema);
+    // Safe to mutate: `clone` is this function's own deep copy, and the caller's schema is the
+    // operation projection's — a generator that edited it would be editing the data it was handed.
+    fillFrameworkOwnedPropertyDescriptions(clone);
     const properties = clone['properties'];
     const dataSchema = isPlainObject(properties) ? properties['data'] : undefined;
     if (isPlainObject(dataSchema) && (dataSchema['type'] === 'array' || 'items' in dataSchema)) {
@@ -1091,27 +1230,151 @@ function buildResponsesObject(op, responseBodySchema, errorResponseSchema) {
     // 401 contract. A resource-owned 401 is more specific (for example a
     // step-up flow) and deliberately takes precedence.
     if (op.access.authenticationMode !== OperationProjectionAuthenticationMode.PUBLIC && responses['401'] === undefined) {
-        const description = (() => {
-            switch (op.access.authenticationMode) {
-                case OperationProjectionAuthenticationMode.ANONYMOUS_SESSION:
-                    return 'The anonymous-session token is missing, malformed, expired, or invalid.';
-                case OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED:
-                    return 'No valid anonymous-session token, bearer token, or API key was supplied.';
-                case OperationProjectionAuthenticationMode.AUTHENTICATED:
-                    return 'No valid bearer token or API key was supplied.';
-                default: {
-                    const exhaustiveAuthenticationMode = op.access.authenticationMode;
-                    throw new Error(`OpenAPI generator: unsupported authentication mode ${String(exhaustiveAuthenticationMode)}`);
-                }
-            }
-        })();
-        responses['401'] = {
-            description,
-            content: { 'application/json': { schema: errorResponseSchema } },
-        };
+        // Referenced, not inlined: the wording is the generator's and identical for every operation
+        // with the same access mode, so `unauthorizedDescription` states it once and the component
+        // carries it. Repeating the content block on 546 operations said nothing a reader could use.
+        responses['401'] = { $ref: `#/components/responses/${unauthorizedResponseName(op.access.authenticationMode)}` };
+    }
+    /*
+     * Every operation can fail inside the application, and not one said so. Added last and only when
+     * absent, so an authored 500 — which can say something specific about THIS operation — wins.
+     */
+    if (responses['500'] === undefined) {
+        responses['500'] = { $ref: `#/components/responses/${INTERNAL_ERROR_RESPONSE_NAME}` };
     }
     return responses;
 }
+/**
+ * The error responses the GENERATOR owns, named once in `components.responses`.
+ *
+ * Only the ones whose wording is the generator's own are shared. An authored response carries a
+ * description written for that one operation — "No release record exists for the supplied id in the
+ * caller's scope" — and that sentence is the most useful prose in the document; folding it into a
+ * shared component would replace it with something generic, so authored responses stay inline.
+ *
+ * The 401 wording is derived from the operation's ACCESS MODE, which is why there are three: the
+ * credential a caller is missing differs, and saying "no valid bearer token" to an anonymous-session
+ * endpoint would be wrong.
+ */
+const GENERATOR_OWNED_ERROR_RESPONSE_NAMES = Object.freeze({
+    [OperationProjectionAuthenticationMode.ANONYMOUS_SESSION]: 'UnauthorizedAnonymousSession',
+    [OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED]: 'UnauthorizedAnonymousOrAuthenticated',
+    [OperationProjectionAuthenticationMode.AUTHENTICATED]: 'Unauthorized',
+    [OperationProjectionAuthenticationMode.PUBLIC]: 'Unauthorized',
+});
+const INTERNAL_ERROR_RESPONSE_NAME = 'InternalServerError';
+function unauthorizedResponseName(mode) {
+    return GENERATOR_OWNED_ERROR_RESPONSE_NAMES[mode];
+}
+/** The one place each 401 wording is written; the components below are built from it. */
+function unauthorizedDescription(mode) {
+    switch (mode) {
+        case OperationProjectionAuthenticationMode.ANONYMOUS_SESSION:
+            return 'The anonymous-session token is missing, malformed, expired, or invalid.';
+        case OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED:
+            return 'No valid anonymous-session token, bearer token, or API key was supplied.';
+        case OperationProjectionAuthenticationMode.AUTHENTICATED:
+        case OperationProjectionAuthenticationMode.PUBLIC:
+            return 'No valid bearer token or API key was supplied.';
+        default: {
+            const exhaustiveAuthenticationMode = mode;
+            throw new Error(`OpenAPI generator: unsupported authentication mode ${String(exhaustiveAuthenticationMode)}`);
+        }
+    }
+}
+/**
+ * The `components.responses` block, built from the same wording the operations reference.
+ *
+ * Emitted only for the names an operation actually used, so a document never carries a component
+ * nothing points at — the reason `PUBLIC` shares the authenticated name rather than earning an
+ * 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 } };
+    for (const mode of [
+        OperationProjectionAuthenticationMode.ANONYMOUS_SESSION,
+        OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED,
+        OperationProjectionAuthenticationMode.AUTHENTICATED,
+    ]) {
+        all[unauthorizedResponseName(mode)] = { description: unauthorizedDescription(mode), content };
+    }
+    return Object.fromEntries(Object.entries(all).filter(([name]) => usedNames.has(name)));
+}
+/**
+ * Every operation can fail with the framework's error envelope, and until now not one of the 546
+ * published operations said so — measured on Wonder CRM, `500` appeared zero times.
+ *
+ * Synthesised rather than authored, for the same reason the 401 is: it is true of every operation
+ * by construction, so making each specification restate it would be 546 copies of one fact with 546
+ * chances to drift. An authored 500 takes precedence, exactly as an authored 401 does.
+ */
+function internalServerErrorDescription() {
+    return 'The request failed inside the application. The body is the standard error envelope and carries a `correlationId` to quote when reporting it; the request was not necessarily rejected, so do not assume it had no effect until you have checked.';
+}
+/**
+ * The document's `webhooks` block — what a RECEIVER is sent, described where OpenAPI 3.1 puts it.
+ *
+ * Until now the reference described only what a client CALLS. An integrator writing the other half
+ * — the endpoint this application posts to — had no machine-readable contract at all, and every
+ * operation that fires a delivery said nothing about it.
+ *
+ * Two facts make these entries honest rather than plausible:
+ *
+ *   · THE BODY IS THE RESOURCE DOCUMENT ITSELF, not an envelope around it. The delivery worker
+ *     posts the stored payload verbatim, and a backend test exists specifically to fail if anyone
+ *     wraps it — because the body's bytes must hash to the signature's `bodyHash` claim. So the
+ *     schema referenced here is the resource's own read response, and when that component cannot
+ *     be resolved the entry carries prose instead of a shape it cannot prove.
+ *   · THE DELIVERY CONTRACT IS ONE OBJECT. Retries, timeout, signature algorithm and claim names
+ *     come from `M2M_WEBHOOK_DELIVERY_CONTRACT`, the same source the delivery worker derives its
+ *     tunables from, so the published contract cannot drift from what is actually sent.
+ */
+function buildWebhooksObject(operations, canonicalReadResponseRefByResource) {
+    const webhooks = {};
+    for (const op of operations) {
+        for (const notification of op.m2mNotifications ?? []) {
+            const key = `${op.resourceIdentifier}.${op.baseOperationIdentifier}`;
+            if (webhooks[key] !== undefined)
+                continue;
+            const bodyRef = canonicalReadResponseRefByResource.get(op.resourceIdentifier);
+            const contract = M2M_WEBHOOK_DELIVERY_CONTRACT;
+            webhooks[key] = {
+                post: {
+                    summary: `${op.resourceIdentifier} ${op.baseOperationIdentifier}`,
+                    description: [
+                        `Sent to every endpoint configured and enabled on the \`${notification.channel}\` channel when \`${op.resourceIdentifier}.${op.baseOperationIdentifier}\` succeeds.`,
+                        '',
+                        `The body is the record itself, exactly as the API returns it — there is no envelope around it, and the bytes you receive are the bytes the signature was computed over.`,
+                        '',
+                        `Verify before trusting it: the \`${contract.signatureHeader}\` header carries a ${contract.signatureAlgorithm} JWT whose \`${contract.signatureClaims.bodyHash}\` claim is the ${contract.bodyHashAlgorithm} digest of the raw body. Its \`${contract.signatureClaims.deliveryId}\` claim is the delivery id and is identical across every retry, so use it to deduplicate.`,
+                        '',
+                        `Answer 2xx to acknowledge. Anything else is retried up to ${contract.maxAttempts} attempts with a fixed backoff, and each attempt is abandoned after ${Math.round(contract.requestTimeoutMs / 1000)} seconds.`,
+                    ].join('\n'),
+                    'x-wildo': {
+                        resourceIdentifier: op.resourceIdentifier,
+                        operationIdentifier: op.baseOperationIdentifier,
+                        eventChannel: notification.channel,
+                        notificationIdentifier: notification.identifier,
+                    },
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': bodyRef === undefined
+                                // No read response to point at — say what the body is rather than assert a shape.
+                                ? { schema: { type: 'object', description: `The \`${op.resourceIdentifier}\` record as the API returns it.` } }
+                                : { schema: { $ref: bodyRef } },
+                        },
+                    },
+                    responses: {
+                        '2XX': { description: 'The delivery was accepted. Any 2xx ends the delivery; the body is ignored.' },
+                    },
+                },
+            };
+        }
+    }
+    return webhooks;
+}
 /**
  * Builds the OpenAPI request-body `examples` map from authored examples that
  * carry a `request` payload. Returns undefined when there are none.
@@ -1173,6 +1436,23 @@ function stableStringify(value) {
     }
     return JSON.stringify(value) ?? 'null';
 }
+/**
+ * Which half of an operation a generated component schema models.
+ *
+ * A closed two-member vocabulary, named rather than inlined because the two members are not
+ * symmetric and the difference is worth stating once: a REQUEST schema is what a caller must
+ * SEND and is therefore the contract they are held to, while a RESPONSE schema is what the
+ * application PROMISES to return. Both the schema NAME and its description are derived from
+ * this value, so the member is the single input that decides how an integrator reads the card.
+ *
+ * The member VALUES are the PascalCase suffixes appended to a schema name (`TodosCreateRequest`),
+ * so they are wire-visible in the published OpenAPI document and not free to rename.
+ */
+export var OpenApiComponentSchemaRole;
+(function (OpenApiComponentSchemaRole) {
+    OpenApiComponentSchemaRole["REQUEST"] = "Request";
+    OpenApiComponentSchemaRole["RESPONSE"] = "Response";
+})(OpenApiComponentSchemaRole || (OpenApiComponentSchemaRole = {}));
 /**
  * Component name for an operation's request/response body. Mirrors the
  * verb-first operationId namer (shares `pascal`): `<Resource><BaseVerb><Quals><Role>`,
@@ -1193,15 +1473,84 @@ function componentSchemaName(op, role) {
         .join('');
     return `${pascal(op.resourceIdentifier)}${pascal(op.baseOperationIdentifier)}${schemaQualifiers}${role}`;
 }
+/**
+ * Describe the two closed vocabularies inside the framework's own error envelope, from the
+ * definitions the runtime already carries.
+ *
+ * `error.type` is the field an integrator branches on, and it arrived as twenty bare tokens with no
+ * explanation — the ONLY enum in the document that no authoring could reach, because the sweep that
+ * describes enum values reads a field specification and this schema belongs to no resource. The
+ * words are not written here: `ERROR_DEFINITIONS` is a `Record<ErrorType, …>` the error builder
+ * itself consults, so the sentence, the HTTP status and whether the framework's own strategy is to
+ * retry all come from the same source that decides them at runtime.
+ *
+ * Matching is by EXACT VALUE SET, and that is only sound because it is scoped to this one
+ * generator-owned schema. Across the document at large it would not be: `['active', 'expired',
+ * 'inactive']` occurs on an OAuth client and on an API key with different meanings, so propagating
+ * one description to the other by value set would put "Client may mint tokens" on an API key.
+ *
+ * `severity` gets one sentence rather than six invented ones: it drives the framework's own logging
+ * and alerting, and a client has nothing to do with it.
+ *
+ * Returns a described COPY. The caller's schema belongs to the projection input and a pin asserts
+ * the generator leaves its input untouched.
+ */
+function describeFrameworkErrorEnvelopeEnums(schema) {
+    if (!isPlainObject(schema))
+        return schema;
+    const errorTypeValues = new Set(Object.values(ErrorType));
+    const severityValues = new Set(Object.values(ErrorSeverity));
+    const errorTypeMeanings = {};
+    for (const value of Object.values(ErrorType)) {
+        const definition = ERROR_DEFINITIONS[value];
+        const retries = definition.errorHandlingStrategy === ErrorHandling_Strategy.RETRY;
+        errorTypeMeanings[value] = `${definition.description} (HTTP ${String(definition.statusCode)})`
+            + `${retries ? ' — retrying is expected to help.' : '.'}`;
+    }
+    const described = structuredClone(schema);
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const entry of node)
+                visit(entry);
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        const values = node['enum'];
+        if (Array.isArray(values) && node['description'] === undefined) {
+            const present = new Set(values.map((value) => String(value)));
+            if (present.size === errorTypeValues.size && [...present].every((value) => errorTypeValues.has(value))) {
+                node['description'] = `Which kind of failure this was. Branch on this rather than on wording.\n\nValues:\n`
+                    + Object.entries(errorTypeMeanings).map(([value, meaning]) => `- \`${value}\`: ${meaning}`).join('\n');
+                node['x-enum-descriptions'] = errorTypeMeanings;
+            }
+            else if (present.size === severityValues.size && [...present].every((value) => severityValues.has(value))) {
+                node['description'] = 'How seriously the application itself treats this failure — it drives logging and alerting '
+                    + 'on the server. A client has nothing to decide from it; branch on `type` and `code`.';
+            }
+        }
+        for (const entry of Object.values(node))
+            visit(entry);
+    };
+    visit(described);
+    return described;
+}
 function createSchemaRegistry() {
     const nameBySemanticIdentityAndContent = new Map();
     const contentByName = new Map();
     const schemas = {};
     return {
-        ref(schema, desiredName) {
+        ref(schema, desiredName, description) {
             if (!isHoistableSchema(schema)) {
                 return schema;
             }
+            /*
+             * Canonicalised BEFORE the description is attached, deliberately. Deduplication is by
+             * name-and-content, so folding the description into the identity would split one component
+             * into several whenever two operations produced the same shape — the opposite of what a
+             * description is for. A component name maps to exactly one desired name, hence to one
+             * operation's resource, so the description attached here describes the schema that is stored.
+             */
             const canonical = stableStringify(schema);
             const semanticIdentityAndContent = `${desiredName}\u0000${canonical}`;
             const existingName = nameBySemanticIdentityAndContent.get(semanticIdentityAndContent);
@@ -1216,7 +1565,17 @@ function createSchemaRegistry() {
             }
             nameBySemanticIdentityAndContent.set(semanticIdentityAndContent, name);
             contentByName.set(name, canonical);
-            schemas[name] = schema;
+            /*
+             * COPIED, never mutated. The caller's schema object belongs to the operation projection, and
+             * a pin asserts the generator leaves its input untouched — writing the description onto it
+             * would have made this generator edit the data it was handed, which is the one thing that
+             * test exists to prevent. A shallow copy suffices: only a top-level key is added, and an
+             * authored description already on the schema outranks the derived one.
+             */
+            const stored = description !== undefined && isPlainObject(schema) && schema['description'] === undefined
+                ? { ...schema, description }
+                : schema;
+            schemas[name] = stored;
             return { $ref: `#/components/schemas/${name}` };
         },
         schemas() {
@@ -1232,12 +1591,29 @@ function createSchemaRegistry() {
  * inline. All success statuses share one response schema object, so they
  * resolve to the same `$ref`. Mutates `operationObject` in place.
  */
-function hoistOperationSchemas(operationObject, op, registry) {
+/**
+ * What a component schema IS, taken from the operation that hoisted it.
+ *
+ * Measured on Wonder CRM: 0 of 474 component schemas carried a description, so the schema list read
+ * as 474 names — `DealReadResponse`, `DealReadContextResponse`, `DealReadSummaryResponse` — with
+ * nothing to tell them apart or say what a deal is.
+ *
+ * Derived from the OPERATION rather than from the schema's name. 473 of the 474 names do start with
+ * their resource's tag, so a prefix match would have worked and would have been a guess: the
+ * hoisting operation is the authoritative link, and it costs nothing to use it. The resource's own
+ * purpose is appended when its specification authored one, because a reader who reached a schema
+ * card may never have seen the tag.
+ */
+function describeComponentSchema(op, role, resourcePurpose) {
+    const what = `${role === OpenApiComponentSchemaRole.REQUEST ? 'Request body' : 'Response body'} for \`${op.resourceIdentifier}.${op.baseOperationIdentifier}\`.`;
+    return resourcePurpose === undefined ? what : `${what} ${resourcePurpose}`;
+}
+function hoistOperationSchemas(operationObject, op, registry, resourcePurpose) {
     const requestBody = operationObject['requestBody'];
     if (isPlainObject(requestBody) && isPlainObject(requestBody['content'])) {
         const media = requestBody['content']['application/json'];
         if (isPlainObject(media) && isHoistableSchema(media['schema'])) {
-            media['schema'] = registry.ref(media['schema'], componentSchemaName(op, 'Request'));
+            media['schema'] = registry.ref(media['schema'], componentSchemaName(op, OpenApiComponentSchemaRole.REQUEST), describeComponentSchema(op, OpenApiComponentSchemaRole.REQUEST, resourcePurpose));
         }
     }
     const responses = operationObject['responses'];
@@ -1248,7 +1624,7 @@ function hoistOperationSchemas(operationObject, op, registry) {
             }
             const media = entry['content']['application/json'];
             if (isPlainObject(media) && isHoistableSchema(media['schema'])) {
-                media['schema'] = registry.ref(media['schema'], componentSchemaName(op, 'Response'));
+                media['schema'] = registry.ref(media['schema'], componentSchemaName(op, OpenApiComponentSchemaRole.RESPONSE), describeComponentSchema(op, OpenApiComponentSchemaRole.RESPONSE, resourcePurpose));
             }
         }
     }
@@ -1342,6 +1718,44 @@ function buildOpenApiDocument(section, operations, input) {
     const sectionLabel = section === OpenApiSection.API_REFERENCE
         ? 'API reference'
         : 'Application administration API reference';
+    /*
+     * Resource purposes, indexed before the operation loop so a hoisted schema can carry what its
+     * resource IS. The tag descriptions below read the same map; building it once keeps the schema
+     * card and the tag card quoting one string rather than two copies that can drift.
+     */
+    const purposeByResourceIdentifier = new Map();
+    for (const tag of input.resourceTags ?? []) {
+        if (tag.description !== undefined && !purposeByResourceIdentifier.has(tag.name)) {
+            purposeByResourceIdentifier.set(tag.name, tag.description);
+        }
+    }
+    /*
+     * The canonical route of every operation that has one, indexed before any operation object is
+     * built. A route with no `Via` qualifier is the operation's own address; the `Via` ones are the
+     * same operation reached through a parent.
+     *
+     * Indexed rather than inferred per operation, because "shortest path wins" would be a guess and
+     * this is a fact the operation key already carries. An operation reachable ONLY through a parent
+     * has no canonical entry, and is deliberately left unmarked: calling it an alias of nothing would
+     * tell a reader to go somewhere that does not exist.
+     */
+    const canonicalPathByRoute = new Map();
+    for (const op of sortedOps) {
+        if (splitOperationQualifiers(op).via.length > 0)
+            continue;
+        const key = canonicalRouteKey(op);
+        if (!canonicalPathByRoute.has(key))
+            canonicalPathByRoute.set(key, op.path);
+    }
+    /** Exactly the shared error responses some operation referenced, so none is emitted unused. */
+    const usedErrorResponseNames = new Set();
+    /**
+     * Each resource's canonical read-response component, for the `webhooks` block to point at.
+     *
+     * The read operation's response IS the record a delivery carries, so this is a resolved
+     * reference rather than a guess — and a resource with no read operation simply gets prose.
+     */
+    const canonicalReadResponseRefByResource = new Map();
     const paths = {};
     const ownershipByPathAndVerb = new Map();
     const tagSet = new Set();
@@ -1358,7 +1772,15 @@ function buildOpenApiDocument(section, operations, input) {
     // The schema comes from the same model the backend error handler serializes.
     // Register before per-operation hoisting so every non-success response shares
     // the stable, named component instead of producing resource-local copies.
-    const errorResponseSchema = schemaRegistry.ref(input.errorResponseSchema, 'ErrorResponse');
+    const errorResponseSchema = schemaRegistry.ref(describeFrameworkErrorEnvelopeEnums(input.errorResponseSchema), 'ErrorResponse', 
+    // The one schema the GENERATOR owns rather than projects, so it was the one schema with no
+    // description while all 473 others had one: the sweep that described component schemas words
+    // them from the operation and the resource, and this belongs to neither.
+    'The body returned whenever a request does not succeed. `error.type` says which kind of failure it '
+        + 'was and `error.code`, when present, is the stable identifier to branch on in code — branch on '
+        + 'those rather than on wording. `error.customMessage` is the text meant for a person, and '
+        + '`error.customMessageReference` is its translation key; `error.message` is the technical '
+        + 'explanation. `error.context` is present only on validation, conflict and rate-limit failures.');
     for (const op of sortedOps) {
         if (paths[op.path] === undefined) {
             paths[op.path] = {};
@@ -1375,7 +1797,40 @@ function buildOpenApiDocument(section, operations, input) {
         operationIdUseCount.set(baseOperationId, priorUses + 1);
         const operationId = priorUses === 0 ? baseOperationId : `${baseOperationId}${priorUses + 1}`;
         const operationObject = buildOperationObject(op, operationId, errorResponseSchema);
-        hoistOperationSchemas(operationObject, op, schemaRegistry);
+        for (const response of Object.values((operationObject['responses'] ?? {}))) {
+            const ref = isPlainObject(response) ? response['$ref'] : undefined;
+            if (typeof ref === 'string' && ref.startsWith('#/components/responses/')) {
+                usedErrorResponseNames.add(ref.slice('#/components/responses/'.length));
+            }
+        }
+        /*
+         * Mark an alias route AS one, and point at the operation's own address.
+         *
+         * OpenAPI has no concept of "the same operation at another path", so a reader meeting
+         * `organizationMembers` for the first time sees its whole surface three times with no way to
+         * tell that two of them are conveniences. The description says so in words a reader acts on,
+         * and `x-wildo.aliasOfPath` gives a renderer something to group or fold on.
+         *
+         * NOT `deprecated`: an alias is a supported route and a client calling it is doing nothing
+         * wrong. Saying "prefer" would be an instruction nobody asked this generator to give.
+         */
+        const canonicalPath = splitOperationQualifiers(op).via.length === 0
+            ? undefined
+            : canonicalPathByRoute.get(canonicalRouteKey(op));
+        if (canonicalPath !== undefined && canonicalPath !== op.path) {
+            const wildo = operationObject['x-wildo'];
+            if (isPlainObject(wildo))
+                wildo['aliasOfPath'] = canonicalPath;
+            const existing = typeof operationObject['description'] === 'string' ? operationObject['description'] : '';
+            const note = `The same operation is published at \`${op.httpVerb.toUpperCase()} ${canonicalPath}\`. This route reaches it through its parent, which is a convenience rather than a different operation — either address does the same thing.`;
+            operationObject['description'] = existing.length > 0 ? `${existing}\n\n${note}` : note;
+        }
+        hoistOperationSchemas(operationObject, op, schemaRegistry, purposeByResourceIdentifier.get(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')
+                canonicalReadResponseRefByResource.set(op.resourceIdentifier, okSchema.$ref);
+        }
         paths[op.path][op.httpVerb] = operationObject;
         ownershipByPathAndVerb.set(collisionKey, `${op.resourceIdentifier}.${op.operationKey}`);
         tagSet.add(op.resourceIdentifier);
@@ -1394,6 +1849,7 @@ function buildOpenApiDocument(section, operations, input) {
         }
         resourceTagsByName.set(tag.name, tag);
     }
+    const webhooks = buildWebhooksObject(sortedOps, canonicalReadResponseRefByResource);
     return {
         openapi: '3.1.0',
         info: {
@@ -1427,6 +1883,9 @@ function buildOpenApiDocument(section, operations, input) {
             return description !== undefined && description.length > 0 ? { ...tag, description } : tag;
         }),
         paths,
+        // `webhooks` (OpenAPI 3.1) = what this application SENDS. The reference described only what a
+        // client calls; an integrator writing the receiving endpoint had no machine-readable contract.
+        ...(Object.keys(webhooks).length > 0 ? { webhooks } : {}),
         // `components.schemas` = hoisted, content-deduped request/response body
         // models (named `<Resource><Verb><Quals>Request|Response`); `securitySchemes`
         // = framework-universal auth, referenced by each op's `security`.
@@ -1434,6 +1893,12 @@ function buildOpenApiDocument(section, operations, input) {
             ...(Object.keys(schemaRegistry.schemas()).length > 0
                 ? { schemas: schemaRegistry.schemas() }
                 : {}),
+            // `responses` = the error responses the GENERATOR words (the access-mode 401s and the
+            // universal 500). An authored response stays inline on its operation, because its
+            // description is written for that one operation and is the document's most useful prose.
+            ...(usedErrorResponseNames.size > 0
+                ? { responses: buildErrorResponseComponents(usedErrorResponseNames, errorResponseSchema) }
+                : {}),
             securitySchemes: SECURITY_SCHEMES,
         },
     };