@wildo-ai/saas-technical-doc 1.1.1

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

@@ -0,0 +1,1562 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc/companion (generator)
+ *
+ * Pure-function OpenAPI 3.1 generator (saas-technical-doc.md Step 3).
+ *
+ * Pipeline:
+ *
+ *   `OpenApiGenerationInput`
+ *     ──filterApiCallOperations──►   (assert URL-bearing variants)
+ *     ──groupOperationsByConsumerApiSection──► (use source-resolved section)
+ *     ──buildOpenApiDocument──►          (per-section OpenAPI 3.1 doc as a JS object)
+ *     ──assembleOpenApiGenerationOutput──►(top-level `OpenApiGenerationOutput`)
+ *
+ * Key design points:
+ *
+ *   K-1: This module is `OpenApiGenerationInput` → `OpenApiGenerationOutput`
+ *        and contains no I/O, no global state, and no DI. It is consumed by
+ *        the companion controller (which owns the introspection hop +
+ *        filesystem write — see Step 4) and by unit tests in isolation.
+ *
+ *   K-2: Sections that contain ZERO operations after filtering are
+ *        OMITTED from the output's `sections[]` array (per the
+ *        `OpenApiGenerationOutputSchema` JSDoc). The companion UI
+ *        surfaces this as an absent section — the empty section is
+ *        intentional, not a generator bug.
+ *
+ *   K-3: The generator uses Zod-parsed input (validated up-front via
+ *        `OpenApiGenerationInputSchema`) so every downstream helper can
+ *        assume well-formed projections. Callers MUST call
+ *        `generateOpenApiDocuments(input)` (which parses) and NOT the
+ *        sub-helpers directly with unparsed data.
+ *
+ *   K-4: The semantic output carries one document object. YAML/JSON
+ *        serialization is renderer-owned so divergent format payloads cannot
+ *        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.
+ */
+import { WildoHeaderKeys } from '@wildo-ai/saas-models/public-runtime';
+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';
+/**
+ * Retains every projected URL-bearing operation.
+ *
+ *   - Variant outside `API_CALL` / `API_CALL_WITH_CALLBACK` (K-5):
+ *     defense-in-depth re-check on top of the projector's filter.
+ *     If a non-API variant ever leaks through, drop it silently here
+ *     rather than throwing — the projector is the single source of
+ *     truth for "should this op even be in the projection at all," but
+ *     we don't want a future projector regression to corrupt the
+ *     generated doc with non-HTTP operations.
+ *
+ * `isApiKeyAccessDisabled` controls the operation's accepted authentication
+ * schemes. It does not make an HTTP operation disappear from its API contract.
+ *
+ * Returns a NEW array — does not mutate the input.
+ */
+export function filterApiCallOperations(operations) {
+    return operations.filter((op) => {
+        if (op.variantType !== OperationProjectionVariantType.API_CALL &&
+            op.variantType !== OperationProjectionVariantType.API_CALL_WITH_CALLBACK) {
+            return false;
+        }
+        return true;
+    });
+}
+/**
+ * Groups operations by the explicit consumer-facing section resolved by the
+ * source projector. This layer deliberately does not reinterpret role strings
+ * or internal resource scopes: doing so would create a second authority for
+ * which product reference owns an operation.
+ *
+ * Returns a frozen `Record` keyed by `OpenApiSection`. Sections with
+ * zero operations are returned as empty arrays (NOT omitted) so the
+ * caller's filtering logic in `assembleOpenApiGenerationOutput` is the
+ * single place that decides "drop empty sections from the output."
+ */
+export function groupOperationsByConsumerApiSection(operations) {
+    const apiReferenceOperations = [];
+    const applicationAdministrationOperations = [];
+    for (const op of operations) {
+        switch (op.consumerApiSection) {
+            case OpenApiSection.API_REFERENCE:
+                apiReferenceOperations.push(op);
+                break;
+            case OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE:
+                applicationAdministrationOperations.push(op);
+                break;
+            default: {
+                const exhaustiveSection = op.consumerApiSection;
+                throw new Error(`OpenAPI generator: unsupported consumer API section ${String(exhaustiveSection)}`);
+            }
+        }
+    }
+    return Object.freeze({
+        [OpenApiSection.API_REFERENCE]: Object.freeze(apiReferenceOperations),
+        [OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE]: Object.freeze(applicationAdministrationOperations),
+    });
+}
+/**
+ * Stable, deterministic ordering for operations within an OpenAPI
+ * doc. Sorted by `(resourceIdentifier, path, httpVerb)` so the
+ * generated YAML diffs cleanly across runs even if the projector
+ * yields operations in a different order (e.g. iteration order
+ * depending on the resource registry walk).
+ */
+function sortOperationsForDeterministicOutput(operations) {
+    return [...operations].sort((a, b) => {
+        if (a.resourceIdentifier !== b.resourceIdentifier) {
+            return a.resourceIdentifier.localeCompare(b.resourceIdentifier);
+        }
+        if (a.path !== b.path) {
+            return a.path.localeCompare(b.path);
+        }
+        return a.httpVerb.localeCompare(b.httpVerb);
+    });
+}
+/**
+ * Maps an `OperationProjection` to its developer-facing OpenAPI `operationId`.
+ *
+ * VERB-FIRST camelCase — the convention the best public API references and the
+ * OpenAPI/SDK-generator ecosystem converge on (`createUser`, `listOrganizations`,
+ * `rotateApiKey`; see Speakeasy + Redocly operationId guidance). The
+ * `operationId` becomes the generated client method name; combined with the
+ * resource TAG, tag-grouping generators yield `sdk.organizations.create()` and
+ * flat generators yield `createOrganization()`.
+ *
+ * Composition: `<verb><ResourceNoun><Qualifiers>`, lower-camelCased.
+ *
+ *   - **verb** — the standard CRUD identifiers (the LOWERCASE
+ *     `CoreResourceOperation` values the projector actually emits) map to
+ *     idiomatic verbs (`create→create`, `read→get`, `list→list`,
+ *     `update→update`, `delete→delete`, `search→search` — see {@link CRUD_VERBS});
+ *     any other identifier becomes its own verb phrase via `pascal`, whether a
+ *     custom op (`exportAuditLogs`→`exportAuditLogs`, `EXPORT_AUDIT_LOGS`→
+ *     `exportAuditLogs`) or a framework collection op the map omits
+ *     (`count`→`count`, `create_many`→`createMany`).
+ *   - **ResourceNoun** — `resourceIdentifier` PascalCased with camelCase word
+ *     boundaries PRESERVED (`organizationApiKeys`→`OrganizationApiKeys`); the
+ *     prior implementation lowercased segment interiors and produced
+ *     `Organizationapikeys`.
+ *   - **Redundancy** — a custom verb phrase that already contains the resource
+ *     noun drops the repeat (`exportAuditLogs`, not `exportAuditLogsAuditLogs`).
+ *   - **Qualifiers** — the `operationKey` segments AFTER the base identifier:
+ *     the semantic `Via<Relationship>` disambiguator for relationship-nested
+ *     paths, the `summary`/`context` data-mode, and `BULK`. Each is PascalCased
+ *     and appended in order.
+ *
+ * Unique within the document and stable across runs (the multi-path
+ * disambiguator is the relationship name, not a positional index).
+ */
+/**
+ * Split a string on separators AND camelCase boundaries (lowercase/digit →
+ * uppercase) so multi-word camelCase identifiers keep their word boundaries.
+ */
+function splitWords(input) {
+    return input.split(/[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])/u).filter((segment) => segment.length > 0);
+}
+/**
+ * Industry-standard initialisms whose casing carries meaning in public API
+ * vocabulary. This is presentation-only: stable resource and operation
+ * identities remain unchanged in tags, operation ids and `x-wildo` metadata.
+ */
+const API_REFERENCE_DISPLAY_INITIALISM_BY_TOKEN = Object.freeze({
+    a2a: 'A2A',
+    api: 'API',
+    dlq: 'DLQ',
+    idp: 'IdP',
+    ip: 'IP',
+    jwt: 'JWT',
+    m2m: 'M2M',
+    mcp: 'MCP',
+    oauth: 'OAuth',
+    oidc: 'OIDC',
+    pdf: 'PDF',
+    saml: 'SAML',
+    scim: 'SCIM',
+    siem: 'SIEM',
+    sso: 'SSO',
+    url: 'URL',
+});
+function apiReferenceDisplayWord(word, capitalizeOrdinaryWord) {
+    const initialism = API_REFERENCE_DISPLAY_INITIALISM_BY_TOKEN[word.toLowerCase()];
+    if (initialism !== undefined)
+        return initialism;
+    const lowercaseWord = word.toLowerCase();
+    return capitalizeOrdinaryWord
+        ? `${lowercaseWord.charAt(0).toUpperCase()}${lowercaseWord.slice(1)}`
+        : lowercaseWord;
+}
+/**
+ * PascalCase a string. Lowercases the interior ONLY for all-uppercase words
+ * (SCREAMING_SNAKE op identifiers like `EXPORT`, `EXCHANGE` → `Export`,
+ * `Exchange`); camelCase words (`Api`, `organization`) keep their interior so
+ * word boundaries survive (`organizationApiKeys` → `OrganizationApiKeys`).
+ * Shared by `buildOperationId` and the `components/schemas` namer
+ * (`componentSchemaName`) so operation ids and model names stay consistent.
+ */
+function pascal(input) {
+    return splitWords(input)
+        .map((word) => {
+        const rest = /^[A-Z0-9]+$/u.test(word) ? word.slice(1).toLowerCase() : word.slice(1);
+        return word.charAt(0).toUpperCase() + rest;
+    })
+        .join('');
+}
+/**
+ * Idiomatic verb-first `operationId` verbs for the standard CRUD identifiers.
+ *
+ * Keyed on the LOWERCASE `@wildo-ai/saas-models` `CoreResourceOperation` VALUES
+ * (`'read'`, `'create'`, `'list'`, …) — NOT the SCREAMING_SNAKE enum MEMBER names.
+ * The projector sets `baseOperationIdentifier` to
+ * `String(operation.operationIdentifier)`, which for a core operation IS the
+ * lowercase enum value, so the lookup key MUST be lowercase.
+ *
+ * (History: this map was originally keyed on `'READ'` / `'CREATE'` / … — the
+ * enum member names — so no lookup ever matched at runtime and every base fell
+ * through to the custom-verb `pascal` path. It went unnoticed because
+ * `pascal(value)` lower-cased equals the intended verb for `create` / `list` /
+ * `update` / `delete` / `search` — the whole map was a no-op EXCEPT `read`,
+ * which produced `readX` instead of the intended `getX`.)
+ *
+ * Mirrored as string literals for the same boundary reason as the other
+ * framework constants in this file — the generator must NOT import
+ * `@wildo-ai/saas-models` (see the module `@wildo-boundary` note). Keep in sync
+ * with `CoreResourceOperation`.
+ *
+ * `read → get` is the sole non-identity mapping; the other five are listed for
+ * self-documentation and drift-resistance (they equal `pascal(value)`). Every
+ * OTHER identifier — custom ops AND the framework's own `count` / `create_many` /
+ * `update_many` / `delete_many` — becomes its own verb phrase via `pascal`
+ * (`create_many → createMany…`, `export_audit_logs → exportAuditLogs…`).
+ */
+const CRUD_VERBS = {
+    create: 'create',
+    read: 'get',
+    list: 'list',
+    update: 'update',
+    delete: 'delete',
+    search: 'search',
+};
+/**
+ * Human, sentence-case verb labels for the default operation TITLE (`summary`).
+ *
+ * Keyed on the same lowercase `CoreResourceOperation` values as {@link CRUD_VERBS}
+ * (see that constant for the boundary + casing rationale). NB the TITLE verb for
+ * a read is the plain `'Read'` (e.g. "Read application auth policy"), distinct
+ * from the `operationId` verb `get` — the two surfaces intentionally diverge.
+ * Identifiers absent here fall through to a humanised phrase of the identifier
+ * itself in `buildDefaultSummary`.
+ */
+const VERB_LABEL = {
+    create: 'Create',
+    read: 'Read',
+    list: 'List',
+    update: 'Update',
+    delete: 'Delete',
+    search: 'Search',
+};
+function buildOperationId(op) {
+    const base = op.baseOperationIdentifier;
+    const isCustom = CRUD_VERBS[base] === undefined;
+    const verbPascal = isCustom ? pascal(base) : pascal(CRUD_VERBS[base]);
+    const resourcePascal = pascal(op.resourceIdentifier);
+    // A custom verb phrase that already names the resource (e.g. EXPORT_AUDIT_LOGS
+    // on `auditLogs`) drops the repeated noun.
+    const corePascal = isCustom && verbPascal.includes(resourcePascal)
+        ? verbPascal
+        : `${verbPascal}${resourcePascal}`;
+    // Qualifiers = `operationKey` with the leading base identifier removed (the
+    // base can itself contain `_`, so we strip by length, not by splitting).
+    const qualifierTail = op.operationKey.startsWith(base)
+        ? op.operationKey.slice(base.length)
+        : '';
+    const qualifiersPascal = qualifierTail.split('_').filter(Boolean).map(pascal).join('');
+    const combined = `${corePascal}${qualifiersPascal}`;
+    return combined.charAt(0).toLowerCase() + combined.slice(1);
+}
+/**
+ * Default summary fallback. Used when the projector did not provide
+ * an explicit `summary` so the docs site never renders a blank title.
+ */
+/**
+ * The operation TITLE (OpenAPI `summary` — page title, nav label, breadcrumb).
+ *
+ * A SHORT, human, derived action label — NOT the authored `purpose` prose
+ * (that is impl-aware intent text and now lives in the `description`; see
+ * `buildOperationDocFromSpec`). Mirrors the verb-first `operationId` but rendered
+ * as a readable sentence-case phrase:
+ *
+ *   read + applicationAuthPolicy                 → "Read application auth policy"
+ *   list + organizationApiKeys (summary variant) → "List organization api keys (summary)"
+ *   create + appAnnouncements via posted-by-users → "Create app announcements via posted by users"
+ *   export_audit_logs + auditLogs                → "Export audit logs"
+ *
+ * The qualifier suffixes (`Via<…>`, `summary`/`context` data-mode, `BULK`) are
+ * humanised so the multiple endpoints of one resource read distinctly in the
+ * sidebar instead of colliding on the same title.
+ */
+function buildDefaultSummary(op) {
+    const words = (input) => input.split(/[^a-zA-Z0-9]+|(?<=[a-z0-9])(?=[A-Z])/u).filter((segment) => segment.length > 0);
+    const sentence = (input) => words(input).map((word) => apiReferenceDisplayWord(word, false)).join(' ');
+    const base = op.baseOperationIdentifier;
+    const verbPhrase = VERB_LABEL[base] ?? sentence(base);
+    const resourcePhrase = sentence(op.resourceIdentifier);
+    const actionWords = words(verbPhrase).map((word) => word.toLowerCase());
+    const resourceWords = words(resourcePhrase).map((word) => word.toLowerCase());
+    const actionAlreadyNamesResource = resourceWords.length > 0
+        && actionWords.length >= resourceWords.length
+        && resourceWords.every((word, index) => actionWords.at(index - resourceWords.length) === word);
+    let title = actionAlreadyNamesResource
+        ? `${verbPhrase.charAt(0).toUpperCase()}${verbPhrase.slice(1)}`
+        : `${verbPhrase.charAt(0).toUpperCase()}${verbPhrase.slice(1)} ${resourcePhrase}`.trim();
+    const qualifierTail = op.operationKey.startsWith(base) ? op.operationKey.slice(base.length) : '';
+    for (const qualifier of qualifierTail.split('_').filter(Boolean)) {
+        if (qualifier.startsWith('Via')) {
+            title += ` via ${sentence(qualifier.slice(3))}`;
+        }
+        else if (qualifier === 'BULK') {
+            title += ' (bulk)';
+        }
+        else if (qualifier.toLowerCase() === 'summary' || qualifier.toLowerCase() === 'context') {
+            title += ` (${qualifier.toLowerCase()})`;
+        }
+        else {
+            title += ` ${sentence(qualifier)}`;
+        }
+    }
+    return title;
+}
+/**
+ * Extracts `{paramName}` placeholders from an OpenAPI-style template
+ * path. Used to derive `parameters[]: in: path` entries automatically
+ * — the projector does not need to redeclare them.
+ *
+ * Returns an empty array for paths with no placeholders.
+ */
+function extractPathParameters(path) {
+    const matches = path.matchAll(/\{([^}]+)\}/gu);
+    return Array.from(matches, (match) => match[1]);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isQueryParameterVerb(httpVerb) {
+    return (httpVerb === 'get'
+        || httpVerb === 'delete');
+}
+/**
+ * Converts a top-level object JSON Schema fragment into OpenAPI query
+ * parameters for query-style verbs (GET / DELETE). Request examples are carried
+ * onto the individual OpenAPI Parameter Objects: these methods have no JSON
+ * body, so dropping an authored example here would make a valid source example
+ * invisible to both an OpenAPI viewer and the Wildo renderer.
+ *
+ * Why fail-loud on non-object schemas:
+ *
+ * The projection explicitly allows `requestBodySchema` to represent
+ * query input for GET / DELETE operations. If a projector bug emits a
+ * scalar / array / malformed schema here, silently reusing it as an
+ * OpenAPI `requestBody` would recreate the exact mis-documentation bug
+ * this helper exists to close. Throwing keeps the spec honest and pins
+ * the regression to the generator boundary.
+ */
+function buildQueryParametersFromRequestSchema(op) {
+    const schema = op.requestBodySchema;
+    if (schema === null) {
+        return [];
+    }
+    if (!isPlainObject(schema) || schema.type !== 'object') {
+        throw new Error(`OpenAPI generator: ${op.httpVerb.toUpperCase()} ${op.path} for `
+            + `${op.resourceIdentifier}.${op.operationKey} carries a non-object request schema. `
+            + `GET/DELETE request schemas must be object-shaped so the generator can emit query parameters.`);
+    }
+    const properties = schema.properties;
+    if (properties === undefined) {
+        return [];
+    }
+    if (!isPlainObject(properties)) {
+        throw new Error(`OpenAPI generator: ${op.httpVerb.toUpperCase()} ${op.path} for `
+            + `${op.resourceIdentifier}.${op.operationKey} has an object request schema with malformed `
+            + '`properties`. Expected a plain object so query parameters can be emitted deterministically.');
+    }
+    const requiredFields = Array.isArray(schema.required)
+        ? new Set(schema.required.filter((value) => typeof value === 'string'))
+        : new Set();
+    // Collection-axis dedupe: on a paginated collection operation (`op.pagination`
+    // present) the framework-generated SEARCH request DTO carries NESTED
+    // `pagination` / `sorting` / `filters` object properties. The canonical wire
+    // shape is FLAT (what the frontend HTTP client sends, what the backend
+    // controller reads first — the nested forms are fallbacks): the `page` /
+    // `limit` / `sort` trio, a free-text `q`, and one parameter per filter field
+    // (scalars flat, date ranges as `deepObject`). Exploding the `filters` object
+    // verbatim would emit a nested object with no `style: deepObject` metadata, so
+    // SDK generators would serialise it wrong. Drop the nested axes here — the flat
+    // trio is emitted by `buildPaginationQueryParameters`, and the flat `q` +
+    // per-field filters by `buildCollectionFilterQueryParameters`, both on the same
+    // 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();
+    return Object.entries(properties)
+        .filter(([name]) => !paginationAxisProperties.has(name))
+        .map(([name, propertySchema]) => {
+        const parameter = {
+            name,
+            in: 'query',
+            required: requiredFields.has(name),
+            schema: isPlainObject(propertySchema) ? propertySchema : {},
+        };
+        if (isPlainObject(propertySchema) && typeof propertySchema.description === 'string') {
+            parameter['description'] = propertySchema.description;
+        }
+        const examples = buildParameterExamples(op, name);
+        if (examples !== undefined) {
+            parameter['examples'] = examples;
+        }
+        return parameter;
+    });
+}
+/**
+ * Projects source-authored request values onto one OpenAPI parameter. Path and
+ * query parameters share the same Parameter Object example contract; retaining
+ * the source title lets a consumer correlate a concrete id/filter with the
+ * business case it was authored for. Response-only examples never participate.
+ */
+function buildParameterExamples(op, parameterName) {
+    const examples = {};
+    for (const example of op.examples ?? []) {
+        if (!isPlainObject(example.request) || !Object.prototype.hasOwnProperty.call(example.request, parameterName)) {
+            continue;
+        }
+        examples[example.title] = { value: example.request[parameterName] };
+    }
+    return Object.keys(examples).length > 0 ? examples : undefined;
+}
+/**
+ * Adds matching source-authored values to a generated Parameter Object. This
+ * is shared by path parameters, direct DTO-property query parameters and the
+ * framework-generated flat collection axes (`q`, filters, pagination).
+ */
+function attachParameterExamples(op, parameter) {
+    const name = parameter['name'];
+    if (typeof name !== 'string') {
+        return parameter;
+    }
+    const examples = buildParameterExamples(op, name);
+    return examples === undefined ? parameter : { ...parameter, examples };
+}
+/**
+ * Flattens a paginated collection operation's nested `filters` request-DTO object
+ * into the FLAT, wire-truthful query parameters the framework actually accepts —
+ * the filtering counterpart of the `page` / `limit` / `sort` pagination-trio
+ * reshape (`buildPaginationQueryParameters`).
+ *
+ * The framework's SEARCH request DTO (`createResourceSearchQueryRequestSchema`)
+ * always carries a top-level `filters` OBJECT: the free-text `searchRequest`, the
+ * `createdAt` / `updatedAt` date-range filters, plus one property per authored
+ * filter field. That nested object is NOT the wire shape — the frontend HTTP
+ * client sends each filter FLAT (`?status=…`) and free-text as `?q=…`, and the
+ * backend controller (`extractCollectionFilters` + `normalizeCollectionQueryRequestData`)
+ * reads the flat forms first. This helper re-surfaces the FLAT-serialisable
+ * `filters` properties as their own query parameters:
+ *
+ *  - `searchRequest` → the canonical flat `q` string (what the frontend sends and
+ *    the backend reads before `searchQuery` before the nested `filters.searchRequest`).
+ *  - any SCALAR property (string / number / boolean / enum) → a plain flat query
+ *    parameter (`?status=active`), carrying the property's schema (and description).
+ *  - an OBJECT-valued property (a date range `{ startDate?, endDate? }`) →
+ *    `style: deepObject, explode: true`, so SDK generators serialise it as
+ *    `field[startDate]=…&field[endDate]=…` (bracket notation). The backend runs
+ *    Express 5's default `simple` query parser (which leaves bracketed keys flat),
+ *    so the controller reconstructs the nested object from those keys —
+ *    `reconstructBracketedRangeFilters` in the collection-query controller,
+ *    declaration-gated to actual range fields. Emitting the `deepObject` metadata
+ *    is the second half of the fix the pagination reshape called out: a nested
+ *    object in a GET query string needs `style: deepObject`, which the naive DTO
+ *    explosion never emitted. (A global `extended` query parser was deliberately
+ *    NOT used — it changes `req.query` shape for every controller and breaks the
+ *    flat-scalar `req.query.X as string` assumption across auth / SCIM / chart.)
+ *  - a filter field whose name is ALSO a path parameter of this endpoint → SKIPPED
+ *    (URL-supplied; see the per-operation note below).
+ *
+ * Gated on `op.pagination !== undefined` (collection ops only — the same signal
+ * the collection-axis dedupe uses), a query verb, and a `filters` object property,
+ * so a non-collection GET carrying an unrelated `filters` property keeps its naive
+ * explosion untouched. All filter parameters are OPTIONAL. Returns `[]` when the
+ * op is not a paginated collection op or declares no `filters` object.
+ */
+function buildCollectionFilterQueryParameters(op) {
+    if (op.pagination === undefined || !isQueryParameterVerb(op.httpVerb)) {
+        return [];
+    }
+    const schema = op.requestBodySchema;
+    if (!isPlainObject(schema) || !isPlainObject(schema.properties)) {
+        return [];
+    }
+    const filtersSchema = schema.properties['filters'];
+    if (!isPlainObject(filtersSchema) || !isPlainObject(filtersSchema.properties)) {
+        return [];
+    }
+    const filterProperties = filtersSchema.properties;
+    // A filter field that is ALSO a path parameter of THIS endpoint (a parent-scope
+    // FK reached via a nested path, e.g. `todoId` on `/…/todos/{todoId}/tasks`) is
+    // already supplied by the URL. Emitting it AGAIN as a query parameter is
+    // redundant, produces two same-named parameters SDK generators mishandle, and —
+    // because the backend merges `{ ...req.params, ...req.query }` — would let the
+    // query value silently override the path scope (a tenant-scope footgun). Skip
+    // it: the path parameter is authoritative. The skip is PER-OPERATION (keyed on
+    // this path's params), so the same filter field is still emitted on a sibling
+    // path that does NOT bind the FK, where filtering by it is meaningful.
+    const pathParameterNames = new Set(extractPathParameters(op.path));
+    const parameters = [];
+    // Free-text search → the canonical flat `q` (the frontend sends `?q=`, and the
+    // backend reads `q` first). The `filters.searchRequest` DTO property is the
+    // nested fallback name, so it is surfaced under the wire name, not verbatim.
+    if ('searchRequest' in filterProperties) {
+        parameters.push(attachParameterExamples(op, {
+            name: 'q',
+            in: 'query',
+            required: false,
+            schema: { type: 'string' },
+            description: 'Free-text search query, matched against the operation\'s configured searchable '
+                + 'fields. Sent flat as `?q=…` (the wire form the backend reads first).',
+        }));
+    }
+    for (const [name, propertySchema] of Object.entries(filterProperties)) {
+        if (name === 'searchRequest' || pathParameterNames.has(name)) {
+            continue; // `searchRequest` surfaced as `q` above; path-param FKs are URL-supplied
+        }
+        const isObjectValued = isPlainObject(propertySchema)
+            && (propertySchema.type === 'object' || 'properties' in propertySchema);
+        const parameter = { name, in: 'query', required: false };
+        // Object-valued filters (date ranges) are irreducibly nested; emit deepObject
+        // so SDKs serialise `name[<field>]=…`. The backend's collection-query controller
+        // reconstructs the nested object from those bracketed keys (the global query
+        // parser stays `simple`); see `reconstructBracketedRangeFilters`.
+        if (isObjectValued) {
+            parameter['style'] = 'deepObject';
+            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 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}).`;
+        }
+        parameters.push(attachParameterExamples(op, parameter));
+    }
+    return parameters;
+}
+/**
+ * Framework-universal pagination defaults, mirrored from the backend
+ * repository adapters (`_doList` in both the MongoDB and PostgreSQL resource
+ * repositories, `@wildo-ai/saas-backend-lib`): an omitted `page` reads as
+ * page 1, an omitted `limit` reads as 20 items per page. Duplicated as
+ * literals for the same boundary reason as the enums above (the generator
+ * 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;
+/**
+ * Emits the flat `page` / `limit` / `sort` query parameters for a paginated
+ * collection operation (`op.pagination` present — LIST / SEARCH-like; see the
+ * projection schema JSDoc). These parameters are FRAMEWORK knowledge: the
+ * backend accepts them on every HTTP LIST/SEARCH dispatch but no request DTO
+ * declares them, so without this emission the spec documents paginated
+ * endpoints with no way to page them (and the `info.description` conventions
+ * block would promise parameters the operations never declare).
+ *
+ * Shapes follow the runtime contract exactly:
+ *
+ *  - `page` — 1-based positive integer, server default 1.
+ *  - `limit` — positive integer, server default 20, capped at the
+ *    per-operation `maxLimit` the projector resolved.
+ *  - `sort` — comma-separated `field:asc` / `field:desc` pairs, highest
+ *    priority first. With a non-empty `sortableFields` allow-list the backend
+ *    silently ignores unrecognised fields and defaults to the first allowed
+ *    field descending; with no allow-list any field applies and the default
+ *    is `createdAt:desc`. The description states whichever branch is true
+ *    for this operation, so the docs never promise sorting the backend
+ *    would drop.
+ */
+function buildPaginationQueryParameters(op) {
+    const pagination = op.pagination;
+    if (pagination === undefined) {
+        return [];
+    }
+    const sortableFields = pagination.sortableFields;
+    const sortDescription = sortableFields.length > 0
+        ? 'Sort order: comma-separated `field:asc` / `field:desc` pairs, highest priority first '
+            + `(e.g. \`${sortableFields[0]}:desc\`). Sortable fields: `
+            + `${sortableFields.map((field) => `\`${field}\``).join(', ')}. `
+            + `Unrecognised fields are ignored. Defaults to \`${sortableFields[0]}:desc\`.`
+        : 'Sort order: comma-separated `field:asc` / `field:desc` pairs, highest priority first '
+            + '(e.g. `createdAt:desc`). Defaults to `createdAt:desc` (newest first).';
+    return [
+        {
+            name: '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',
+            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',
+            in: 'query',
+            required: false,
+            schema: { type: 'string' },
+            description: sortDescription,
+        },
+    ].map((parameter) => attachParameterExamples(op, parameter));
+}
+/**
+ * HTTP header carrying a complete API key. Read from the lightweight public
+ * runtime entrypoint so the generator shares the backend's canonical header
+ * vocabulary without importing the saas-models root barrel.
+ */
+const API_KEY_AUTHORIZATION_HEADER_NAME = WildoHeaderKeys.AUTHORIZATION;
+/** HTTP header carrying an anonymous-session token. */
+const ANONYMOUS_SESSION_HEADER_NAME = WildoHeaderKeys.ANONYMOUS_SESSION_TOKEN;
+/**
+ * Framework-universal OpenAPI `components.securitySchemes`. Every Wildo API
+ * authenticates the same ways, so the generator emits these UNCONDITIONALLY —
+ * framework knowledge, not app config. Per-operation `security` references them
+ * by name (see `buildOperationSecurity`).
+ *
+ *  - `bearerAuth` — JWT access token in `Authorization: Bearer <jwt>`.
+ *  - `apiKeyAuth` — org-/app-scoped API key (`sk_org_…` / `sk_app_…`) in `Authorization` without a bearer scheme.
+ *  - `anonymousSessionAuth` — anonymous-session token in `x-anonymous-session-token`
+ *    (the pre-authentication surface; `APP_ANONYMOUS` operations).
+ */
+const SECURITY_SCHEMES = {
+    bearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+        description: 'JWT access token issued by the authentication service. Send as `Authorization: Bearer <token>`.',
+    },
+    apiKeyAuth: {
+        type: 'apiKey',
+        in: 'header',
+        name: API_KEY_AUTHORIZATION_HEADER_NAME,
+        description: 'Organization- or application-scoped API key (`sk_org_…` / `sk_app_…`), sent as the complete value of the `Authorization` header without a `Bearer` scheme.',
+    },
+    anonymousSessionAuth: {
+        type: 'apiKey',
+        in: 'header',
+        name: ANONYMOUS_SESSION_HEADER_NAME,
+        description: 'Anonymous-session token for pre-authentication (anonymous user) access, sent in the `x-anonymous-session-token` header.',
+    },
+};
+/**
+ * Per-operation OpenAPI `security`, derived ENTIRELY from the source-resolved
+ * access document (NOT `primaryScope`, which is the scope/audience axis).
+ *
+ *  - `roles` contains `APP_PUBLIC` → `[]` — explicitly PUBLIC (OpenAPI reads an
+ *    empty `security` array as "no authentication required"). Public access
+ *    wins over any other listed role, so the docs/"Try it" don't demand a token
+ *    for sign-up, public reads, etc.
+ *  - otherwise the requirements are OR-ed (any one satisfies the request):
+ *      • `anonymousSessionAuth` when `roles` contains `APP_ANONYMOUS`.
+ *      • `bearerAuth` (+ `apiKeyAuth`, unless `isApiKeyAccessDisabled`) when the
+ *        op has ANY non-`APP_ANONYMOUS` role, OR no role at all (an open endpoint
+ *        for any authenticated user — "app users can list users").
+ *
+ * So `[APP_ANONYMOUS]` → anonymous-session only; `[APP_ANONYMOUS, APP_USER]` →
+ * anonymous-session OR bearer/api-key; `[APP_USER]` / `[]` / `[ORG_OWNER]` →
+ * bearer/api-key. `isApiKeyAccessDisabled` removes only the API-key alternative;
+ * the HTTP operation remains documented.
+ */
+function buildOperationSecurity(op) {
+    if (op.access.authenticationMode === OperationProjectionAuthenticationMode.PUBLIC)
+        return [];
+    const requirements = [];
+    if (op.access.authenticationMode === OperationProjectionAuthenticationMode.ANONYMOUS_SESSION
+        || op.access.authenticationMode === OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED) {
+        requirements.push({ anonymousSessionAuth: [] });
+    }
+    if (op.access.authenticationMode === OperationProjectionAuthenticationMode.AUTHENTICATED
+        || op.access.authenticationMode === OperationProjectionAuthenticationMode.ANONYMOUS_OR_AUTHENTICATED) {
+        requirements.push({ bearerAuth: [] });
+        if (!op.isApiKeyAccessDisabled) {
+            requirements.push({ apiKeyAuth: [] });
+        }
+    }
+    return requirements;
+}
+/**
+ * Builds the OpenAPI 3.1 `paths.<path>.<method>` entry for a single
+ * operation. Returns a plain JS object suitable for direct YAML
+ * serialisation — no YAML primitives leak past the YAML emitter call.
+ */
+function buildOperationObject(op, operationId, errorResponseSchema) {
+    const operationObject = {
+        operationId,
+        summary: op.summary ?? buildDefaultSummary(op),
+        tags: [op.resourceIdentifier],
+        // Strict framework metadata for consumers that need to join a rendered
+        // operation back to its resolved source identity. Standard OpenAPI fields
+        // stay standard; this carries only Wildo-specific semantics.
+        'x-wildo': {
+            ...op.identity,
+            section: op.consumerApiSection,
+            roles: [...op.roles],
+            access: op.access,
+        },
+    };
+    if (op.description !== undefined) {
+        operationObject['description'] = op.description;
+    }
+    // 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.
+    const security = buildOperationSecurity(op);
+    operationObject['security'] = security;
+    if (op.access.authenticationMode !== OperationProjectionAuthenticationMode.PUBLIC && op.access.roleRequirements.length > 0) {
+        operationObject['x-required-roles'] = op.access.roleRequirements.map((requirement) => requirement.role);
+    }
+    const parameters = [];
+    const pathParams = extractPathParameters(op.path);
+    if (pathParams.length > 0) {
+        parameters.push(...pathParams.map((paramName) => attachParameterExamples(op, {
+            name: paramName,
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+        })));
+    }
+    if (op.stepUpAuthentication !== undefined) {
+        parameters.push({
+            name: op.stepUpAuthentication.headerName,
+            in: 'header',
+            required: true,
+            schema: { type: 'string' },
+            description: `Single-use re-authentication token obtained from POST ${op.stepUpAuthentication.tokenEndpointPath}. `
+                + 'Required for this sensitive operation and consumed when the request is authorized.',
+        });
+    }
+    if (op.acceptsIfMatch) {
+        parameters.push({
+            name: WildoHeaderKeys.IF_MATCH,
+            in: 'header',
+            required: false,
+            schema: {
+                type: 'string',
+                pattern: '^(?:[0-9]+|"[0-9]+"|W/"[0-9]+")$',
+            },
+            examples: {
+                'Current resource version': { value: '7' },
+            },
+            description: 'Optional optimistic-locking version from `_version` in the latest resource response. '
+                + 'Send it as a bare integer (`7`), quoted entity tag (`"7"`) or weak entity tag (`W/"7"`). '
+                + 'When supplied, the mutation is applied only if that version is still current.',
+        });
+    }
+    if (isQueryParameterVerb(op.httpVerb)) {
+        parameters.push(...buildQueryParametersFromRequestSchema(op));
+        // Paginated collection ops carry a nested `filters` bag in their request DTO;
+        // it was dropped from the naive explosion above and is re-surfaced here as the
+        // flat `q` + one parameter per filter field (scalars flat, date ranges as
+        // deepObject — the backend controller reconstructs the nested range object).
+        parameters.push(...buildCollectionFilterQueryParameters(op));
+    }
+    else if (op.requestBodySchema !== null) {
+        const requestJsonMedia = { schema: op.requestBodySchema };
+        const requestExamples = buildRequestExamples(op);
+        if (requestExamples !== undefined) {
+            requestJsonMedia['examples'] = requestExamples;
+        }
+        operationObject['requestBody'] = {
+            required: true,
+            content: {
+                'application/json': requestJsonMedia,
+            },
+        };
+    }
+    // Paginated collection ops (LIST / SEARCH-like) accept the framework's flat
+    // `page` / `limit` / `sort` query parameters regardless of what their request
+    // DTO declares. Appended LAST so operation-specific parameters (`q`, filter
+    // fields) read first and the boilerplate trio sits together at the end.
+    parameters.push(...buildPaginationQueryParameters(op));
+    if (parameters.length > 0) {
+        operationObject['parameters'] = parameters;
+    }
+    // Inject engine metadata (`_version` / `_field_meta`) that the response
+    // serializer reattaches onto every materialized resource document but which no
+    // resource schema declares. Computed once and shared by the `responses` object
+    // and the async callback payload (both describe the same operation result) so
+    // structurally identical schemas still content-dedup into one component when
+    // hoisted.
+    const augmentedResponseBodySchema = augmentResponseSchemaWithEngineMetadata(op.responseBodySchema);
+    operationObject['responses'] = buildResponsesObject(op, augmentedResponseBodySchema, errorResponseSchema);
+    if (op.variantType === OperationProjectionVariantType.API_CALL_WITH_CALLBACK) {
+        // The Zod superRefine on OperationProjectionSchema guarantees
+        // callbackPath is defined here — but the runtime check below is
+        // defense-in-depth in case a future caller bypasses Zod parsing
+        // and feeds the helper a raw projection (which the public API
+        // forbids but the helper itself remains pure-function).
+        if (op.callbackPath !== undefined) {
+            operationObject['callbacks'] = {
+                completion: {
+                    [`{$request.body#/callbackUrl}${op.callbackPath}`]: {
+                        post: {
+                            requestBody: {
+                                required: true,
+                                content: {
+                                    'application/json': {
+                                        schema: augmentedResponseBodySchema ?? {},
+                                    },
+                                },
+                            },
+                            responses: {
+                                '204': { description: 'Callback acknowledged' },
+                            },
+                        },
+                    },
+                },
+            };
+        }
+    }
+    if (op.idempotent !== undefined) {
+        operationObject['x-idempotent'] = op.idempotent;
+    }
+    if (op.rateLimitNote !== undefined) {
+        const rateLimitLine = `**Rate limiting:** ${op.rateLimitNote}`;
+        operationObject['description'] = typeof operationObject['description'] === 'string'
+            ? `${operationObject['description']}\n\n${rateLimitLine}`
+            : rateLimitLine;
+    }
+    return operationObject;
+}
+/**
+ * Client-facing engine-metadata properties that the response serializer
+ * REATTACHES onto every materialized resource document AFTER the response DTO
+ * parse strips them (`operation-response-serializer.backend.utils` +
+ * `services-registry-handler.transformOutput`, both in `@wildo-ai/saas-backend-lib`).
+ * They are engine metadata, NOT declared fields of any resource schema — so
+ * `operation.responseDto` (and thus the projected `responseBodySchema`) omits
+ * them and the generated OpenAPI would under-document the real wire response.
+ * We emit them as OPTIONAL, non-required properties so the spec matches what
+ * clients actually receive; well-behaved clients already ignore unknown
+ * `_`-prefixed fields, this just makes the contract explicit.
+ *
+ *  - `_version` — optimistic-locking counter (a non-negative integer; the
+ *    stored `_version_db_doc` surfaced to clients, starts at 1 and increments on
+ *    every write, but can read as `0`). The frontend echoes it back as the
+ *    `If-Match` request header on inline updates to detect concurrent edits.
+ *  - `_field_meta` — per-field CRDT causality map used for conflict-free merges
+ *    of concurrent edits. Opaque to API clients; safe to ignore.
+ *
+ * Cloned per-injection (spread) so no two schemas share a mutable node.
+ */
+const ENGINE_METADATA_PROPERTY_SCHEMAS = {
+    _version: {
+        type: 'integer',
+        description: 'Engine metadata (not a resource field): optimistic-locking version counter. '
+            + 'Echo it back as the `If-Match` request header on updates to guard against concurrent edits.',
+    },
+    _field_meta: {
+        type: 'object',
+        additionalProperties: true,
+        description: 'Engine metadata (not a resource field): per-field CRDT causality map used for '
+            + 'conflict-free merges of concurrent edits. Opaque to clients — safe to ignore.',
+    },
+};
+/**
+ * The structural signature of a MATERIALIZED resource document in a response
+ * schema is the `_id` property. The serializer attaches `_version` /
+ * `_field_meta` to exactly those objects (repository documents carry the stored
+ * `_version_db_doc`, surfaced as `_version`); envelopes (`{ count }`, delete /
+ * purge acks), computed-state projections (feature entitlements, lifecycle
+ * state), and `context`-mode wrappers have no `_id` and carry no engine
+ * metadata. Gating on `_id` keeps the spec truthful in BOTH directions — no
+ * under-documentation of real documents, no over-documentation of envelopes.
+ * Mutates `objectSchema.properties` in place (the caller owns a fresh clone).
+ */
+function injectEngineMetadataIntoResourceDocumentSchema(objectSchema) {
+    const properties = objectSchema['properties'];
+    if (!isPlainObject(properties) || !('_id' in properties)) {
+        return;
+    }
+    for (const [name, schema] of Object.entries(ENGINE_METADATA_PROPERTY_SCHEMAS)) {
+        // Never clobber an authored field of the same name (defensive — no resource
+        // declares `_version` / `_field_meta`, but the guard keeps injection
+        // idempotent). NOT added to `required`: engine metadata is optional.
+        if (!(name in properties)) {
+            properties[name] = { ...schema };
+        }
+    }
+}
+/**
+ * Walk the composite wrappers (`oneOf` / `anyOf` / `allOf`) a polymorphic /
+ * discriminated-union response produces (`z.toJSONSchema` emits `oneOf` for a
+ * `ZodDiscriminatedUnion`) down to the concrete object branches, injecting
+ * engine metadata into each branch that is a resource document. A non-composite
+ * object is injected directly.
+ */
+function injectEngineMetadataIntoEntitySchemas(schema) {
+    if (!isPlainObject(schema)) {
+        return;
+    }
+    let isComposite = false;
+    for (const compositeKey of ['oneOf', 'anyOf', 'allOf']) {
+        const branches = schema[compositeKey];
+        if (Array.isArray(branches)) {
+            isComposite = true;
+            for (const branch of branches) {
+                injectEngineMetadataIntoEntitySchemas(branch);
+            }
+        }
+    }
+    if (!isComposite) {
+        injectEngineMetadataIntoResourceDocumentSchema(schema);
+    }
+}
+/**
+ * Return a CLONE of an operation's response body schema with the engine-metadata
+ * properties injected at the SAME structural positions the response serializer
+ * attaches them (`operation-response-serializer.backend.utils`):
+ *
+ *   1. paginated `{ data: [ … ], pagination }` → each `data[]` item
+ *   2. flat array `[ … ]`                       → each item
+ *   3. single object                            → the object itself
+ *
+ * (each unwrapped through `oneOf`/`anyOf`/`allOf` for polymorphic resources).
+ * The original schema is NEVER mutated — the callback path and any structurally
+ * identical schema on another operation must stay pristine so content-dedup
+ * (`stableStringify`) still collapses them onto one component. Non-object
+ * schemas (`null` / scalar) pass through unchanged.
+ */
+function augmentResponseSchemaWithEngineMetadata(responseBodySchema) {
+    if (!isPlainObject(responseBodySchema)) {
+        return responseBodySchema;
+    }
+    const clone = structuredClone(responseBodySchema);
+    const properties = clone['properties'];
+    const dataSchema = isPlainObject(properties) ? properties['data'] : undefined;
+    if (isPlainObject(dataSchema) && (dataSchema['type'] === 'array' || 'items' in dataSchema)) {
+        // Paginated `{ data: [ … ] }` wrapper — mirror the serializer's `body.data[i]`
+        // attach position. (A `context`-mode wrapper's `data[]` item is itself a
+        // `{ data: [ … ] }` sub-collection with no `_id`, so it is correctly skipped.)
+        injectEngineMetadataIntoEntitySchemas(dataSchema['items']);
+    }
+    else if (clone['type'] === 'array' || 'items' in clone) {
+        injectEngineMetadataIntoEntitySchemas(clone['items']);
+    }
+    else {
+        injectEngineMetadataIntoEntitySchemas(clone);
+    }
+    return clone;
+}
+/**
+ * Builds the OpenAPI `responses` object for an operation: authored success
+ * statuses + error scenarios (Tier 3), plus the framework-wide authentication
+ * failure derived from the source-resolved access mode. It falls back to the
+ * default single `200`/`204` when no success status is authored. Response
+ * `examples` are attached to the status they declare via `forStatus`. Multiple
+ * error scenarios on the same code merge their `when` prose into one entry's
+ * description.
+ *
+ * `responseBodySchema` is the operation's response body schema ALREADY augmented
+ * with engine metadata (see `augmentResponseSchemaWithEngineMetadata`); the
+ * caller computes it once so the `responses` object and the async callback
+ * payload share the same node.
+ */
+function buildResponsesObject(op, responseBodySchema, errorResponseSchema) {
+    const responseExamplesByStatus = new Map();
+    for (const example of op.examples ?? []) {
+        if (example.response === undefined || example.forStatus === undefined) {
+            continue;
+        }
+        const bucket = responseExamplesByStatus.get(example.forStatus) ?? {};
+        bucket[example.title] = { value: example.response };
+        responseExamplesByStatus.set(example.forStatus, bucket);
+    }
+    const buildSuccessContent = (code) => {
+        if (responseBodySchema === null || code === '204') {
+            return undefined;
+        }
+        const jsonMedia = { schema: responseBodySchema };
+        const examples = responseExamplesByStatus.get(code);
+        if (examples !== undefined) {
+            jsonMedia['examples'] = examples;
+        }
+        return { 'application/json': jsonMedia };
+    };
+    const responses = {};
+    const successStatuses = op.responseStatuses ?? [];
+    if (successStatuses.length > 0) {
+        for (const status of successStatuses) {
+            const entry = { description: status.meaning };
+            const content = buildSuccessContent(status.code);
+            if (content !== undefined) {
+                entry['content'] = content;
+            }
+            responses[status.code] = entry;
+        }
+    }
+    else if (responseBodySchema !== null) {
+        const entry = { description: 'Success' };
+        const content = buildSuccessContent('200');
+        if (content !== undefined) {
+            entry['content'] = content;
+        }
+        responses['200'] = entry;
+    }
+    else {
+        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 errorJsonMedia = { schema: errorResponseSchema };
+        const examples = responseExamplesByStatus.get(error.code);
+        if (examples !== undefined) {
+            errorJsonMedia['examples'] = examples;
+        }
+        const errorContent = { 'application/json': errorJsonMedia };
+        const existing = responses[error.code];
+        if (isPlainObject(existing) && typeof existing['description'] === 'string') {
+            existing['description'] = `${existing['description']}\n\n${description}`;
+            existing['content'] = errorContent;
+        }
+        else {
+            responses[error.code] = {
+                description,
+                content: errorContent,
+            };
+        }
+    }
+    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 } },
+            };
+        };
+        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.');
+    }
+    // Every framework RATE_LIMIT error with a retry delay is serialized by
+    // `ErrorHandlerBackendService` with an HTTP `Retry-After` header. A source-
+    // authored 429 is therefore sufficient to project this protocol contract;
+    // individual resource specifications must not duplicate framework header
+    // vocabulary. The current runtime emits integer delay-seconds, not an HTTP
+    // date, so the Header Object deliberately exposes that narrower shape.
+    const rateLimitResponse = responses['429'];
+    if (isPlainObject(rateLimitResponse)) {
+        rateLimitResponse['headers'] = {
+            'Retry-After': {
+                description: 'Delay in seconds before the client should retry the request.',
+                schema: { type: 'integer', minimum: 0 },
+            },
+        };
+    }
+    // Authentication happens before the resource operation. The projection's
+    // access mode is the sole truth for which credentials may satisfy it, so the
+    // renderer and each resource specification do not need to re-state the same
+    // 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 } },
+        };
+    }
+    return responses;
+}
+/**
+ * Builds the OpenAPI request-body `examples` map from authored examples that
+ * carry a `request` payload. Returns undefined when there are none.
+ */
+function buildRequestExamples(op) {
+    const examples = {};
+    const pathParameterNames = new Set(extractPathParameters(op.path));
+    for (const example of op.examples ?? []) {
+        if (example.request === undefined) {
+            continue;
+        }
+        // Source examples use one object so the same authored scenario can feed path
+        // parameters and the JSON body. OpenAPI represents those as separate locations:
+        // keep path values on Parameter Objects (via `buildParameterExamples`) and remove
+        // them from the body example. Otherwise a primary-scope id such as
+        // `organizationId` appears twice even when the request DTO correctly owns only
+        // `justification` and `requestedDurationMinutes`.
+        const value = isPlainObject(example.request)
+            ? Object.fromEntries(Object.entries(example.request).filter(([name]) => !pathParameterNames.has(name)))
+            : example.request;
+        examples[example.title] = { value };
+    }
+    return Object.keys(examples).length > 0 ? examples : undefined;
+}
+/**
+ * Is this JSON-Schema fragment worth hoisting into `components/schemas`? Only
+ * structured bodies (objects / arrays / composed schemas) earn a named
+ * component + `$ref`; bare scalars (`{ type: 'string' }`) and empty `{}` stay
+ * inline (a `$ref` to a one-line scalar would be pure overhead). Already-`$ref`
+ * fragments are left alone.
+ */
+function isHoistableSchema(value) {
+    if (!isPlainObject(value) || '$ref' in value) {
+        return false;
+    }
+    return (value['type'] === 'object'
+        || value['type'] === 'array'
+        || 'properties' in value
+        || 'items' in value
+        || 'allOf' in value
+        || 'anyOf' in value
+        || 'oneOf' in value);
+}
+/**
+ * Deterministic, key-sorted stringification used to detect structurally
+ * IDENTICAL schemas regardless of key order, so the same shape authored on
+ * different operations (or the same operation reached at multiple paths — the
+ * `Via<…>` variants) collapses onto ONE component.
+ */
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(',')}]`;
+    }
+    if (isPlainObject(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * Component name for an operation's request/response body. Mirrors the
+ * verb-first operationId namer (shares `pascal`): `<Resource><BaseVerb><Quals><Role>`,
+ * e.g. `TodosListResponse`, `TodosCreateRequest`, `TodosListSummaryResponse`,
+ * `TodosChangeStatusBulkRequest`. Schema-affecting qualifiers (`summary` /
+ * `context` data-mode, `BULK`) ARE included; the multi-path `Via<…>`
+ * disambiguator is STRIPPED because it never changes the body shape — so the
+ * many URL variants of one operation share a single model.
+ */
+function componentSchemaName(op, role) {
+    const qualifierTail = op.operationKey.startsWith(op.baseOperationIdentifier)
+        ? op.operationKey.slice(op.baseOperationIdentifier.length)
+        : '';
+    const schemaQualifiers = qualifierTail
+        .split('_')
+        .filter((q) => q.length > 0 && !q.startsWith('Via'))
+        .map(pascal)
+        .join('');
+    return `${pascal(op.resourceIdentifier)}${pascal(op.baseOperationIdentifier)}${schemaQualifiers}${role}`;
+}
+function createSchemaRegistry() {
+    const nameBySemanticIdentityAndContent = new Map();
+    const contentByName = new Map();
+    const schemas = {};
+    return {
+        ref(schema, desiredName) {
+            if (!isHoistableSchema(schema)) {
+                return schema;
+            }
+            const canonical = stableStringify(schema);
+            const semanticIdentityAndContent = `${desiredName}\u0000${canonical}`;
+            const existingName = nameBySemanticIdentityAndContent.get(semanticIdentityAndContent);
+            if (existingName !== undefined) {
+                return { $ref: `#/components/schemas/${existingName}` };
+            }
+            let name = desiredName;
+            let suffix = 2;
+            while (contentByName.has(name) && contentByName.get(name) !== canonical) {
+                name = `${desiredName}${suffix}`;
+                suffix += 1;
+            }
+            nameBySemanticIdentityAndContent.set(semanticIdentityAndContent, name);
+            contentByName.set(name, canonical);
+            schemas[name] = schema;
+            return { $ref: `#/components/schemas/${name}` };
+        },
+        schemas() {
+            return schemas;
+        },
+    };
+}
+/**
+ * Replace an operation object's inline request/response BODY schemas with
+ * `$ref`s into `components/schemas` (via `registry`). Walks only the
+ * `application/json` body slots — `requestBody` and each `responses[*]` with
+ * content; query `parameters` (GET/DELETE) and the rare `callbacks` block stay
+ * 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) {
+    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'));
+        }
+    }
+    const responses = operationObject['responses'];
+    if (isPlainObject(responses)) {
+        for (const entry of Object.values(responses)) {
+            if (!isPlainObject(entry) || !isPlainObject(entry['content'])) {
+                continue;
+            }
+            const media = entry['content']['application/json'];
+            if (isPlainObject(media) && isHoistableSchema(media['schema'])) {
+                media['schema'] = registry.ref(media['schema'], componentSchemaName(op, 'Response'));
+            }
+        }
+    }
+}
+/**
+ * Framework-universal API conventions, emitted as the trailing section of every
+ * `info.description`. These describe behaviour that is TRUE OF EVERY Wildo API
+ * (engine-generic application behavior, not Wildo author guidance or app
+ * configuration), so the reusable generator authors them once here. Grounded
+ * in the actual generated spec: the three security schemes (see
+ * `SECURITY_SCHEMES`), the `{ data, pagination }` list envelope, the
+ * `x-idempotent` extension, and standard HTTP error codes. Rate-limit response
+ * headers are deliberately NOT claimed — they are not emitted in the spec.
+ */
+const API_CONVENTIONS_MARKDOWN = [
+    '## API conventions',
+    '',
+    '### Authentication',
+    '',
+    'Each operation lists the credentials it accepts under **Security**:',
+    '',
+    '- **Bearer token** — a JWT access token sent as `Authorization: Bearer <token>`.',
+    '- **API key** — an organization- or application-scoped key (`sk_org_…` / `sk_app_…`) sent as the complete value of the `Authorization` header without a `Bearer` scheme.',
+    '- **Anonymous session** — an anonymous-session token sent in `x-anonymous-session-token`, for pre-authentication operations.',
+    '',
+    'Operations with no security requirement are public.',
+    '',
+    '### Base URL',
+    '',
+    'Pick a base URL from the **Servers** dropdown and prepend it to each operation path (paths already include the `/api/v1` mount).',
+    '',
+    '### Pagination',
+    '',
+    'List and search operations return `{ "data": [ … ], "pagination": { "page", "limit", "total", "totalPages" } }`. Use the `page` and `limit` query parameters to page through results, and `sort` (comma-separated `field:asc` / `field:desc` pairs, highest priority first) to order them. Each operation documents its per-page maximum and sortable fields on the parameters themselves.',
+    '',
+    '### Filtering',
+    '',
+    'Search operations accept a free-text `q` query parameter and one query parameter per configured filter field (for example `?status=active`). Range filters (dates) are object-valued: pass them with `deepObject` bracket notation — `createdAt[startDate]=<ISO>&createdAt[endDate]=<ISO>`. Each operation documents its available filter fields on the parameters themselves.',
+    '',
+    '### Idempotency',
+    '',
+    'Operations flagged **idempotent** (the `x-idempotent` extension) are safe to retry — repeating the request has the same effect as making it once.',
+    '',
+    '### Errors',
+    '',
+    'Errors use standard HTTP status codes. Each operation documents the specific failures it can return (for example `400`, `403`, `404`, `409`) and the condition that triggers each.',
+].join('\n');
+/**
+ * Compose the OpenAPI `info.description` (the API reference landing page): the
+ * app's authored `apiOverview` (when present) followed by the framework-universal
+ * `API_CONVENTIONS_MARKDOWN`. The conventions are ALWAYS emitted, so the landing
+ * page is never blank — the overview is pure enrichment on top.
+ */
+function buildInfoDescription(input) {
+    const overview = input.apiOverview?.trim();
+    return overview && overview.length > 0
+        ? `${overview}\n\n${API_CONVENTIONS_MARKDOWN}`
+        : API_CONVENTIONS_MARKDOWN;
+}
+/**
+ * Produces the display label for an OpenAPI resource tag without changing the
+ * stable tag identity used by generated clients and operation metadata.
+ *
+ * The identity remains the resource identifier (`organizationApiKeys`), while
+ * the native Docusaurus reference can present a human-scannable resource
+ * heading (`Organization Api Keys`). Applications can later supply richer
+ * product terminology without making that editorial concern part of the wire
+ * contract.
+ */
+function buildResourceTagDisplayName(resourceIdentifier) {
+    return splitWords(resourceIdentifier)
+        .map((word) => apiReferenceDisplayWord(word, true))
+        .join(' ');
+}
+/**
+ * Builds the full OpenAPI 3.1 document object for a single section.
+ * Returns a plain JS object — the YAML emitter is a separate concern.
+ *
+ * `paths` are nested by template path; multiple HTTP verbs on the
+ * same path are merged into a single path-item object as the OpenAPI
+ * spec requires. Body schemas are hoisted into `components/schemas`
+ * (content-deduped, `$ref`-linked) by a per-section `SchemaRegistry`.
+ */
+function buildOpenApiDocument(section, operations, input) {
+    const sortedOps = sortOperationsForDeterministicOutput(operations);
+    const titleBase = input.publicMarketingTitle ?? input.appDisplayName;
+    // `organization` / `application` are internal scope partitions. The API
+    // reference must name the consumer job instead: organization-scoped tenant
+    // operations are the normal API, whereas application-scoped operations are
+    // the privileged administration surface.
+    const sectionLabel = section === OpenApiSection.API_REFERENCE
+        ? 'API reference'
+        : 'Application administration API reference';
+    const paths = {};
+    const ownershipByPathAndVerb = new Map();
+    const tagSet = new Set();
+    // operationId must be unique within the document. The verb-first builder is
+    // unique by construction for almost every operation, but a few resources with
+    // deeply self-nested URL families (e.g. `applications` via app-metadata /
+    // app-versions) reduce to the same semantic `Via<…>` and would otherwise
+    // collide. Disambiguate genuine collisions with a stable numeric suffix: the
+    // first occurrence (in deterministic sort order) keeps the clean name, later
+    // ones get `2`, `3`, … — applied here rather than in the projector because
+    // uniqueness is a per-document (per-section) property.
+    const operationIdUseCount = 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
+    // the stable, named component instead of producing resource-local copies.
+    const errorResponseSchema = schemaRegistry.ref(input.errorResponseSchema, 'ErrorResponse');
+    for (const op of sortedOps) {
+        if (paths[op.path] === undefined) {
+            paths[op.path] = {};
+        }
+        const collisionKey = `${op.path}::${op.httpVerb}`;
+        const existingOwner = ownershipByPathAndVerb.get(collisionKey);
+        if (existingOwner !== undefined) {
+            throw new Error(`OpenAPI generator: duplicate ${op.httpVerb.toUpperCase()} ${op.path} in `
+                + `${section}. Existing operation ${existingOwner} collides with `
+                + `${op.resourceIdentifier}.${op.operationKey}. Each OpenAPI path+verb pair must be unique.`);
+        }
+        const baseOperationId = buildOperationId(op);
+        const priorUses = operationIdUseCount.get(baseOperationId) ?? 0;
+        operationIdUseCount.set(baseOperationId, priorUses + 1);
+        const operationId = priorUses === 0 ? baseOperationId : `${baseOperationId}${priorUses + 1}`;
+        const operationObject = buildOperationObject(op, operationId, errorResponseSchema);
+        hoistOperationSchemas(operationObject, op, schemaRegistry);
+        paths[op.path][op.httpVerb] = operationObject;
+        ownershipByPathAndVerb.set(collisionKey, `${op.resourceIdentifier}.${op.operationKey}`);
+        tagSet.add(op.resourceIdentifier);
+    }
+    // Tier-2: per-resource tag descriptions (resource business purpose). The
+    // tag set is derived from the section's operations above; descriptions are
+    // looked up by tag name from the input's resourceTags (order-independent).
+    // Cleaned of implementation-only noise here (this is the surface the projector
+    // does NOT route through `buildOperationDocFromSpec`), so the resource group
+    // blurbs read identically to the per-operation prose. Tags whose description
+    // cleans to empty are dropped (treated as having no description).
+    const resourceTagsByName = new Map();
+    for (const tag of input.resourceTags ?? []) {
+        if (resourceTagsByName.has(tag.name)) {
+            throw new Error(`OpenAPI generator: duplicate resource tag descriptor for '${tag.name}'.`);
+        }
+        resourceTagsByName.set(tag.name, tag);
+    }
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: `${titleBase} ${sectionLabel}`,
+            description: buildInfoDescription(input),
+            version: input.supportedApiVersion,
+        },
+        // `servers` only when the app enriched `apiServers` (deployment URLs are
+        // app/environment knowledge — see WildoTechnicalDocConfig.apiServers).
+        // Omitted → back-compatible with the pre-servers output.
+        ...(input.servers && input.servers.length > 0 ? { servers: input.servers } : {}),
+        tags: Array.from(tagSet)
+            .sort((a, b) => a.localeCompare(b))
+            .map((tagName) => {
+            const descriptor = resourceTagsByName.get(tagName);
+            const description = descriptor?.description === undefined
+                ? undefined
+                : stripImplementationNoise(descriptor.description);
+            const resourceMetadata = {
+                contractVersion: OPENAPI_RESOURCE_IDENTITY_CONTRACT_VERSION,
+                resourceRef: `technical-documentation:resource/${tagName}`,
+                ...(descriptor?.lifecycleRole === undefined ? {} : { lifecycleRole: stripImplementationNoise(descriptor.lifecycleRole) }),
+                ...(descriptor?.relationships === undefined ? {} : { relationships: descriptor.relationships }),
+                ...(descriptor?.category === undefined ? {} : { category: descriptor.category }),
+            };
+            const tag = {
+                name: tagName,
+                'x-displayName': buildResourceTagDisplayName(tagName),
+                'x-wildo': resourceMetadata,
+            };
+            return description !== undefined && description.length > 0 ? { ...tag, description } : tag;
+        }),
+        paths,
+        // `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`.
+        components: {
+            ...(Object.keys(schemaRegistry.schemas()).length > 0
+                ? { schemas: schemaRegistry.schemas() }
+                : {}),
+            securitySchemes: SECURITY_SCHEMES,
+        },
+    };
+}
+/**
+ * Counts the unique `resourceIdentifier` values among a set of
+ * operations. Used to populate `OpenApiSectionOutput.resourceCount`.
+ */
+function countDistinctResources(operations) {
+    const resources = new Set();
+    for (const op of operations) {
+        resources.add(op.resourceIdentifier);
+    }
+    return resources.size;
+}
+/**
+ * Builds a single section's output entry. Returns `null` when the
+ * section is empty so the caller can omit it from `sections[]` per
+ * K-2.
+ */
+function buildSectionOutput(section, operations, input) {
+    if (operations.length === 0) {
+        return null;
+    }
+    const document = buildOpenApiDocument(section, operations, input);
+    return {
+        section,
+        operationCount: operations.length,
+        resourceCount: countDistinctResources(operations),
+        document,
+    };
+}
+/**
+ * Refuses a generator change that drops, duplicates or rewrites a resolved HTTP
+ * operation between the source projection and the final OpenAPI documents.
+ *
+ * This is intentionally performed against the emitted `x-wildo` identity,
+ * rather than operationId or path iteration order. Those are presentation and
+ * OpenAPI container details respectively; the source tuple is the contract.
+ */
+function assertGeneratedOperationConservation(operations, sections) {
+    const identityKey = (identity) => JSON.stringify([
+        identity['contractVersion'],
+        identity['resourceRef'],
+        identity['operationFamilyRef'],
+        identity['operationVariantRef'],
+        identity['variantType'],
+        identity['httpVerb'],
+        identity['path'],
+        identity['section'],
+    ]);
+    const expected = new Set();
+    for (const operation of operations) {
+        const key = identityKey({ ...operation.identity, section: operation.consumerApiSection });
+        if (expected.has(key))
+            throw new Error(`OpenAPI generator: duplicate source operation identity ${key}`);
+        expected.add(key);
+    }
+    const actual = new Set();
+    for (const section of sections) {
+        const paths = section.document['paths'];
+        if (!isPlainObject(paths))
+            throw new Error(`OpenAPI generator: ${section.section} document has no paths object`);
+        for (const pathItem of Object.values(paths)) {
+            if (!isPlainObject(pathItem))
+                continue;
+            for (const operationObject of Object.values(pathItem)) {
+                if (!isPlainObject(operationObject))
+                    continue;
+                const metadata = operationObject['x-wildo'];
+                if (metadata === undefined)
+                    continue;
+                if (!isPlainObject(metadata))
+                    throw new Error('OpenAPI generator: x-wildo operation metadata must be an object');
+                const key = identityKey(metadata);
+                if (actual.has(key))
+                    throw new Error(`OpenAPI generator: duplicate emitted operation identity ${key}`);
+                actual.add(key);
+            }
+        }
+    }
+    if (actual.size !== expected.size || [...expected].some((key) => !actual.has(key))) {
+        throw new Error('OpenAPI generator: resolved HTTP operation conservation failed between source projection and OpenAPI output');
+    }
+}
+/**
+ * Public entry point — single function the companion controller
+ * calls.
+ *
+ * Steps:
+ *   1. Parse the input (defense-in-depth — the controller validates
+ *      against `OpenApiGenerationInputSchema` already, but we re-parse
+ *      here so direct callers can't bypass validation).
+ *   2. Assert URL-bearing variants without treating authentication-mode flags
+ *      as eligibility filters.
+ *   3. Group by the explicit source-resolved consumer section.
+ *   4. Build one semantic OpenAPI document per non-empty section.
+ *   5. Drop empty sections (K-2).
+ *
+ * @param rawInput The unparsed input — typically the deserialised
+ *   wire payload from the introspection subprocess hop.
+ * @returns The `OpenApiGenerationOutput` ready to be returned by the
+ *   companion controller.
+ */
+export function generateOpenApiDocuments(rawInput) {
+    const input = OpenApiGenerationInputSchema.parse(rawInput);
+    const apiOps = filterApiCallOperations(input.operations);
+    const split = groupOperationsByConsumerApiSection(apiOps);
+    const sectionOrder = [
+        OpenApiSection.API_REFERENCE,
+        OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE,
+    ];
+    const sections = [];
+    for (const section of sectionOrder) {
+        const sectionOutput = buildSectionOutput(section, split[section], input);
+        if (sectionOutput !== null) {
+            sections.push(sectionOutput);
+        }
+    }
+    assertGeneratedOperationConservation(apiOps, sections);
+    return {
+        generatedAt: new Date().toISOString(),
+        sections,
+    };
+}
+//# sourceMappingURL=openapi-generator.js.map