@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/companion/operation-projection.schemas.d.ts

@@ -0,0 +1,797 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc/companion (input projection)
+ *
+ * Input shape consumed by the companion-side OpenAPI generator
+ * (saas-technical-doc.md Step 3).
+ *
+ * Why a dedicated projection (and NOT importing `ResourcesRegistry` from
+ * `@wildo-ai/saas-models`):
+ *
+ *  - The full `ResourceConfiguration` carries ~40 internal-only fields
+ *    (factory metadata, repository wiring, validation hooks, frontend
+ *    presets, lifecycle bindings, …). The OpenAPI generator does NOT need
+ *    any of them — it needs ONLY operation-level HTTP shape data
+ *    (method + path + request/response Zod schemas + role binding +
+ *    primary scope + authentication-mode flags). Coupling the
+ *    generator to the full type would (a) drag the entire schema graph
+ *    + decorator framework into the companion bundle, defeating the
+ *    point of `@wildo-ai/saas-models/public-runtime`; (b) couple test
+ *    fixtures to dozens of irrelevant fields, making generator unit
+ *    tests brittle to unrelated framework changes; (c) make the
+ *    introspection-subprocess hop's wire format depend on the entire
+ *    framework's type stability.
+ *
+ *  - The introspection subprocess (wonder-todos backend) ALREADY has
+ *    the resolved `ResourceConfiguration` graph — it's the natural
+ *    place to flatten it into this minimal projection. The companion
+ *    process then transforms the projection into YAML without ever
+ *    needing the framework's resource-config types.
+ *
+ *  - This file re-declares the small subset of enums/literals the
+ *    projection carries (`ResourceOperationVariantTypeProjection`,
+ *    `ResourcePrimaryScopeProjection`) rather than importing them from
+ *    `@wildo-ai/saas-models` so that `engine/saas-technical-doc/companion`
+ *    does NOT pull the heavy package's root barrel (which boots
+ *    `initZodDecorators()` — see `saas-models-public-runtime.md` K-3 for
+ *    the rationale). The projection's enum members MUST stay in
+ *    one-to-one alignment with `ResourceOperationVariantType` and
+ *    `ResourcePrimaryScope`; if the source enums grow a new member,
+ *    update this file in the same commit and rerun the boundary tests.
+ *
+ * @wildo-boundary
+ *   This file imports only Zod and the portable technical-documentation
+ *   contract subpath — no React, no `@wildo-ai/saas-models` root, no
+ *   decorators. The supported API version deliberately reuses the publication
+ *   contract's named runtime schema rather than creating a parallel vocabulary.
+ */
+import { z } from 'zod';
+import { OpenApiSection } from '../openapi/openapi-generation-output.schemas';
+/**
+ * Mirror of `@wildo-ai/saas-models` `ResourceOperationVariantType` —
+ * narrowed to the two variants the OpenAPI generator emits per K-5
+ * (`API_CALL` is the default URL-bearing operation; `API_CALL_WITH_CALLBACK`
+ * additionally carries an asynchronous callback URL). Other variants
+ * (`CRON_JOB`, `BATCH_JOB`, `INTERNAL_CALL`, `REPOSITORY_ONLY`) are
+ * intentionally NOT included — they have no HTTP surface to document.
+ *
+ * The introspection emitter MUST drop non-API operations BEFORE
+ * projecting; the generator additionally re-asserts the variant via
+ * Zod parse so a future bug at the projector layer cannot inject
+ * non-API ops into an API doc.
+ */
+export declare enum OperationProjectionVariantType {
+    API_CALL = "api_call",
+    API_CALL_WITH_CALLBACK = "api_call_with_callback"
+}
+/**
+ * Mirror of `@wildo-ai/saas-models` `ResourcePrimaryScope` — kept
+ * complete (4 members) because scope remains part of the documented operation
+ * contract even though consumer sectioning is now an explicit separate fact.
+ *
+ * If `ResourcePrimaryScope` grows a new member upstream, update this
+ * enum in the same commit AND extend the audience splitter to either
+ * route the new scope into one of the existing buckets or fail-closed
+ * with a clear "unsupported scope" error — never silently drop the op.
+ */
+export declare enum OperationProjectionPrimaryScope {
+    USER_SELF = "user_self",
+    ORGANIZATIONS = "organizations",
+    APPLICATION = "applications",
+    ANONYMOUS = "anonymous"
+}
+/**
+ * Allowed HTTP methods carried on a projected operation. Mirrors the
+ * `HttpMethod` enum in `@wildo-ai/saas-models` but kept local for the
+ * same boundary reason as the variant + scope enums above.
+ *
+ * Lowercase string values match the OpenAPI 3.1 path-item keys
+ * (`get`, `post`, `put`, `delete`, `patch`) — keeping the projection
+ * value verbatim consumable by the YAML emitter avoids one hop of
+ * case-translation in the hot path.
+ */
+export declare enum OperationProjectionHttpVerb {
+    GET = "get",
+    POST = "post",
+    PUT = "put",
+    DELETE = "delete",
+    PATCH = "patch"
+}
+/**
+ * Authentication posture resolved from the same role binding the backend
+ * enforces. This is intentionally a documentation fact rather than a browser
+ * inference: `APP_PUBLIC` and `APP_ANONYMOUS` are access-mode sentinels, while
+ * every other role is an authorization requirement.
+ */
+export declare enum OperationProjectionAuthenticationMode {
+    PUBLIC = "public",
+    ANONYMOUS_SESSION = "anonymous_session",
+    AUTHENTICATED = "authenticated",
+    ANONYMOUS_OR_AUTHENTICATED = "anonymous_or_authenticated"
+}
+/**
+ * One role requirement as it should be understood by an integrator. `role`
+ * remains the exact runtime token; `label` is resolved once at generation time
+ * and the explanatory fields come from the application role specification —
+ * never from a browser-side naming heuristic.
+ */
+export declare const OperationRoleRequirementSchema: z.ZodObject<{
+    role: z.ZodString;
+    label: z.ZodString;
+    businessRole: z.ZodNullable<z.ZodString>;
+    authorityBoundary: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type OperationRoleRequirement = z.infer<typeof OperationRoleRequirementSchema>;
+/**
+ * Consumer-facing access contract emitted into the operation's `x-wildo`
+ * metadata. Its prose is assembled in the introspection subprocess from the
+ * authoritative role specifications; the OpenAPI generator and browser only
+ * transport and render it.
+ */
+export declare const OperationAccessDocumentationSchema: z.ZodObject<{
+    authenticationMode: z.ZodEnum<typeof OperationProjectionAuthenticationMode>;
+    authenticationSummary: z.ZodString;
+    roleRequirements: z.ZodArray<z.ZodObject<{
+        role: z.ZodString;
+        label: z.ZodString;
+        businessRole: z.ZodNullable<z.ZodString>;
+        authorityBoundary: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type OperationAccessDocumentation = z.infer<typeof OperationAccessDocumentationSchema>;
+/** Versioned identity carried from the resolved HTTP operation into OpenAPI. */
+export declare const OPENAPI_OPERATION_IDENTITY_CONTRACT_VERSION = 1;
+/** Versioned identity carried by each generated OpenAPI resource tag. */
+export declare const OPENAPI_RESOURCE_IDENTITY_CONTRACT_VERSION = 1;
+/**
+ * The non-editorial identity of one externally exposed HTTP operation.
+ *
+ * This deliberately excludes `operationKey`: that key exists to create a
+ * readable OpenAPI `operationId` and can contain a defensive positional
+ * fallback for unusual multi-path configurations. Conservation, generated
+ * routes and framework metadata must instead join this stable source tuple.
+ */
+export declare const OpenApiOperationIdentitySchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    resourceRef: z.ZodString;
+    operationFamilyRef: z.ZodString;
+    operationVariantRef: z.ZodString;
+    variantType: z.ZodEnum<typeof OperationProjectionVariantType>;
+    httpVerb: z.ZodEnum<typeof OperationProjectionHttpVerb>;
+    path: z.ZodString;
+}, z.core.$strict>;
+export type OpenApiOperationIdentity = z.infer<typeof OpenApiOperationIdentitySchema>;
+/**
+ * Derives stable semantic refs for the resolved operation tuple. This is the
+ * sole constructor so the subprocess projector, generator and future browser
+ * reader cannot gradually invent incompatible identities.
+ */
+export declare function createOpenApiOperationIdentity(input: {
+    readonly resourceIdentifier: string;
+    readonly baseOperationIdentifier: string;
+    readonly variantKey: string | null;
+    readonly variantType: OperationProjectionVariantType;
+    readonly httpVerb: OperationProjectionHttpVerb;
+    readonly path: string;
+}): OpenApiOperationIdentity;
+/**
+ * Single projected operation — the atomic unit consumed by the URL-bearing
+ * operation guard and the explicit consumer-section grouping.
+ *
+ * Field decisions:
+ *
+ *  - `resourceIdentifier` is a free string (NOT typed against
+ *    `CoreResourceType`) because applications can declare custom
+ *    resource types beyond the core enum. The generator uses this
+ *    string as the OpenAPI tag name, so we want the wire format to
+ *    survive any application-extended vocabulary without a schema
+ *    bump.
+ *
+ *  - `operationKey` is the framework's canonical operation identifier
+ *    (e.g. `'CREATE'`, `'LIST'`, `'READ'`, custom-named ops); used
+ *    verbatim as the OpenAPI `operationId` after a small
+ *    PascalCase prefix (`<Resource><OperationKey>`). Stable across
+ *    runs so client-codegen consumers can rely on it.
+ *
+ *  - `httpVerb` and `path` carry the wire-level routing details. The
+ *    `path` MUST be the OpenAPI-style template path (e.g.
+ *    `/api/v1/{organizationId}/users/{userId}`), NOT an Express
+ *    `:userId` form — the projector at the introspection side is
+ *    responsible for the Express → OpenAPI brace conversion so the
+ *    generator can pass the value through unchanged.
+ *
+ *  - `roles` is the resolved string list (after enum → string
+ *    flattening) so the splitter can audience-classify without
+ *    re-importing the role enums. Empty array is rejected via Zod's
+ *    `.min(1)` because every operation in the framework MUST declare
+ *    at least one role binding (the framework's resource-config
+ *    schema enforces this on the source side; the Zod check here is
+ *    defense-in-depth).
+ *
+ *  - `requestBodySchema` / `responseBodySchema` carry pre-converted
+ *    JSON Schema fragments (from `z.toJSONSchema()` at the projector
+ *    side). The generator does NOT see the source Zod schemas — the
+ *    projector does the conversion so the generator stays
+ *    decorator-framework-free (importing a Zod schema graph would
+ *    pull `initZodDecorators()` for any `@wildo-ai/saas-models`-typed
+ *    schema).
+ *
+ *  - `summary` and `description` are optional human-readable strings;
+ *    when omitted, the YAML emitter falls back to the canonical
+ *    `<HTTP_VERB> <Resource>.<OperationKey>` derivation so the docs
+ *    site never renders a literal "undefined" title.
+ *
+ *  - `isApiKeyAccessDisabled` is an authentication-mode fact. The
+ *    introspection projector forwards it verbatim; the generator keeps the
+ *    operation and omits only its API-key security alternative.
+ *
+ *  - `stepUpAuthentication` is present only when the resolved operation
+ *    requires a fresh, single-use re-authentication proof. Both values are
+ *    projected from the framework's named route/header constants so OpenAPI
+ *    never invents or duplicates the protocol vocabulary.
+ *
+ *  - `acceptsIfMatch` is the resolved optimistic-locking capability of this
+ *    exact HTTP operation. It is true only for the controller's supported
+ *    single-resource UPDATE-like lane, including custom operations borrowing
+ *    UPDATE semantics; the generator uses it to expose the optional header and
+ *    its framework-owned 400/409 outcomes without resource-level duplication.
+ *
+ *  - `callbackPath` is OPTIONAL and MUST be present iff
+ *    `variantType === API_CALL_WITH_CALLBACK`. The generator emits an
+ *    OpenAPI 3.1 `callbacks:` block when set. The schema's
+ *    `superRefine` enforces this invariant at parse time so the
+ *    generator's hot path can assume the field is correctly populated.
+ */
+export declare const OperationProjectionSchema: z.ZodObject<{
+    resourceIdentifier: z.ZodString;
+    operationKey: z.ZodString;
+    /**
+     * The RAW operation identifier (e.g. `CREATE`, `LIST`, `EXPORT_AUDIT_LOGS`,
+     * `ROTATE_TOKEN`) WITHOUT the variant / bulk / multi-path qualifiers that
+     * `operationKey` appends. `buildOperationId` needs this to compose a
+     * verb-first developer-facing operationId (`createOrganization`): the verb
+     * is derived from the base identifier and the resource noun from
+     * `resourceIdentifier`, while the qualifiers are `operationKey` with this
+     * prefix removed. Carried separately because a base identifier can itself
+     * contain `_` (e.g. `EXPORT_AUDIT_LOGS`), so the qualifier boundary cannot be
+     * recovered from `operationKey` alone.
+     */
+    baseOperationIdentifier: z.ZodString;
+    /** Exact runtime variant discriminator. `null` is the canonical default variant. */
+    variantKey: z.ZodNullable<z.ZodString>;
+    variantType: z.ZodEnum<typeof OperationProjectionVariantType>;
+    httpVerb: z.ZodEnum<typeof OperationProjectionHttpVerb>;
+    path: z.ZodString;
+    primaryScope: z.ZodEnum<typeof OperationProjectionPrimaryScope>;
+    /**
+     * Consumer-facing documentation section resolved at the source-authority
+     * boundary. The OpenAPI generator groups by this explicit fact; it must not
+     * reinterpret internal scopes or role strings into product navigation.
+     */
+    consumerApiSection: z.ZodEnum<typeof OpenApiSection>;
+    /**
+     * Stable source identity used for conservation and the strict `x-wildo`
+     * extension. It is not a human-facing operationId and never depends on
+     * iteration order or display prose.
+     */
+    identity: z.ZodObject<{
+        contractVersion: z.ZodLiteral<1>;
+        resourceRef: z.ZodString;
+        operationFamilyRef: z.ZodString;
+        operationVariantRef: z.ZodString;
+        variantType: z.ZodEnum<typeof OperationProjectionVariantType>;
+        httpVerb: z.ZodEnum<typeof OperationProjectionHttpVerb>;
+        path: z.ZodString;
+    }, z.core.$strict>;
+    roles: z.ZodArray<z.ZodString>;
+    /**
+     * Source-resolved consumer access explanation. This must remain aligned with
+     * `roles`: the projector is the only place allowed to interpret access-mode
+     * sentinels and attach the app's role-specification prose.
+     */
+    access: z.ZodObject<{
+        authenticationMode: z.ZodEnum<typeof OperationProjectionAuthenticationMode>;
+        authenticationSummary: z.ZodString;
+        roleRequirements: z.ZodArray<z.ZodObject<{
+            role: z.ZodString;
+            label: z.ZodString;
+            businessRole: z.ZodNullable<z.ZodString>;
+            authorityBoundary: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    isApiKeyAccessDisabled: z.ZodBoolean;
+    stepUpAuthentication: z.ZodOptional<z.ZodObject<{
+        headerName: z.ZodString;
+        tokenEndpointPath: z.ZodString;
+    }, z.core.$strict>>;
+    acceptsIfMatch: z.ZodBoolean;
+    summary: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * JSON-Schema fragment representing the request body (or query for
+     * GET / DELETE if the projector chose to flatten query parameters
+     * into a single schema). The exact shape is whatever
+     * `z.toJSONSchema()` emits. For POST / PUT / PATCH style verbs the
+     * generator passes it through unchanged into the OpenAPI
+     * `requestBody.content.application/json.schema` slot. For GET /
+     * DELETE the generator expects an object-shaped schema and explodes
+     * the top-level properties into `parameters[]` entries with
+     * `in: 'query'`. `null` means "no request input".
+     */
+    requestBodySchema: z.ZodNullable<z.ZodUnknown>;
+    /**
+     * JSON-Schema fragment representing the 2xx response body. `null`
+     * means "no body" → emitted as a 204-style `responses` entry with
+     * description only. `unknown` to stay format-agnostic; the
+     * projector is responsible for emitting valid JSON Schema.
+     */
+    responseBodySchema: z.ZodNullable<z.ZodUnknown>;
+    /**
+     * Paginated-collection query contract — present iff the operation is a
+     * framework paginated collection operation (a `LIST` / `SEARCH` core
+     * operation, or a custom operation borrowing one via
+     * `resourceOperationLike`). Those operations universally accept the flat
+     * `page` / `limit` / `sort` query parameters and return the
+     * `{ data, pagination }` envelope (the backend controller forces
+     * `paginated: true` for every HTTP LIST/SEARCH dispatch), but NONE of that
+     * appears in the operation's request DTO — without this block the generator
+     * would document a paginated endpoint with no way to page it.
+     *
+     * The PROJECTOR resolves the per-operation values (it sees the resolved
+     * runtime operation); the GENERATOR owns the universal parameter shapes and
+     * the framework-constant defaults (`page` defaults to 1, `limit` to 20 —
+     * mirrors of the repository `_doList` defaults). Split chosen so this wire
+     * schema stays framework-decoupled: the projection carries FACTS, not
+     * OpenAPI fragments.
+     *
+     *  - `maxLimit` — largest accepted `limit` value. Resolved from the
+     *    operation's `maxPaginatedResultPerPageLimit ?? 50` (the same fallback
+     *    the frontend HTTP client clamps with; only SEARCH-like operations can
+     *    author a different cap today).
+     *  - `sortableFields` — the operation's declared `sortFields` allow-list.
+     *    Non-empty: only these fields may be named in `sort` (unrecognised
+     *    fields are silently ignored by the backend validator) and the default
+     *    ordering is the first entry, descending. Empty: the backend applies
+     *    any requested field verbatim and defaults to `createdAt:desc`.
+     */
+    pagination: z.ZodOptional<z.ZodObject<{
+        maxLimit: z.ZodNumber;
+        sortableFields: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    /**
+     * Path of the asynchronous callback (`API_CALL_WITH_CALLBACK` only).
+     * The generator turns this into an OpenAPI `callbacks:` block
+     * referencing the same `responseBodySchema`.
+     */
+    callbackPath: z.ZodOptional<z.ZodString>;
+    /**
+     * Tier-3 authored HTTP documentation, projected from the resource
+     * specification's operation overlay. All optional; when present the
+     * generator emits real `responses` (success + error), request/response
+     * `examples`, an `x-idempotent` extension, and a rate-limit note instead of
+     * the default single `200`/`204`. `code` / `forStatus` are OpenAPI status
+     * keys (`'200'`, `'404'`, …).
+     */
+    responseStatuses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        meaning: z.ZodString;
+    }, z.core.$strict>>>;
+    errorScenarios: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        when: z.ZodString;
+        errorCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    idempotent: z.ZodOptional<z.ZodBoolean>;
+    rateLimitNote: z.ZodOptional<z.ZodString>;
+    examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        request: z.ZodOptional<z.ZodUnknown>;
+        response: z.ZodOptional<z.ZodUnknown>;
+        forStatus: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type OperationProjection = z.infer<typeof OperationProjectionSchema>;
+/**
+ * Closed projection vocabulary mirroring the relationship cardinalities in
+ * `@wildo-ai/saas-models`. It deliberately lives in the narrow IPC/OpenAPI
+ * contract so the generator and browser never need to import the full resource
+ * registry just to render a resource's public relationship semantics.
+ */
+export declare enum ResourceRelationshipDocumentationCardinality {
+    ONE = "one",
+    ZERO_OR_ONE = "zero_or_one",
+    ONE_OR_MANY = "one_or_many",
+    MANY = "many"
+}
+/** The three developer-authored relationship meanings projected into OpenAPI. */
+export declare enum ResourceRelationshipDocumentationNature {
+    COMPOSITION = "composition",
+    REFERENCE = "reference",
+    ASSOCIATION = "association"
+}
+/** The compiled lifecycle dependency of a relationship, not a presentation hint. */
+export declare enum ResourceRelationshipDocumentationLifecycleModel {
+    DEPENDENT = "dependent",
+    INDEPENDENT = "independent",
+    LINK_ONLY = "link_only"
+}
+/** Execution timing for an explicitly configured parent-delete lifecycle. */
+export declare enum ResourceRelationshipDocumentationDeleteMode {
+    IMMEDIATE = "immediate",
+    LAZY = "lazy"
+}
+/** Effect of an explicitly configured parent-delete lifecycle. */
+export declare enum ResourceRelationshipDocumentationDeleteStrategy {
+    DELETE = "delete",
+    IMPERSONALIZE_AND_RETAIN = "impersonalize_and_retain"
+}
+/**
+ * One relationship fact from the perspective of a resource OpenAPI tag.
+ *
+ * `relatedResourceName` and the two cardinalities are deliberately symmetric:
+ * resource configurations include both ordinary parent → child relationships
+ * and FK-reference declarations, so this public contract must not guess an
+ * ownership direction from declaration order. `lifecycleModel` and the
+ * optional `onParentDelete` policy carry the framework's already-resolved
+ * lifecycle truth without exposing registry implementation details.
+ */
+export declare const ResourceRelationshipDocumentationSchema: z.ZodObject<{
+    relatedResourceName: z.ZodString;
+    /** Resolved FK identity when the relationship is represented by a field. */
+    foreignKeyField: z.ZodOptional<z.ZodString>;
+    resourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+    relatedResourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+    nature: z.ZodEnum<typeof ResourceRelationshipDocumentationNature>;
+    lifecycleModel: z.ZodEnum<typeof ResourceRelationshipDocumentationLifecycleModel>;
+    onParentDelete: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        mode: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteMode>;
+        strategy: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteStrategy>;
+        maxDepth: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceRelationshipDocumentation = z.infer<typeof ResourceRelationshipDocumentationSchema>;
+/**
+ * A source-declared grouping for resources in one consumer API reference.
+ *
+ * API resource categories are navigation meaning, not a renderer inference.
+ * An application declares the category once in `wildo.tech-doc.config.ts`; the
+ * companion attaches it to the corresponding resource tag and the generator
+ * transports the fact through strict OpenAPI metadata.  The identifier is
+ * deliberately application-defined: different products can have genuinely
+ * different business domains while still using the same renderer.
+ */
+export declare const ApiReferenceResourceCategorySchema: z.ZodObject<{
+    /** Stable, readable public identity used in API-reference fragments. */
+    id: z.ZodString;
+    /** Consumer-facing category label displayed by the renderer. */
+    label: z.ZodString;
+    /** Optional category orientation supplied by the application, never React. */
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ApiReferenceResourceCategory = z.infer<typeof ApiReferenceResourceCategorySchema>;
+/**
+ * Optional per-resource OpenAPI tag descriptor (specification + registry enrichment).
+ *
+ * The generator groups operations under a tag named after the resource
+ * identifier. Each emitted OpenAPI tag has a strict `x-wildo` resource identity;
+ * this descriptor enriches it with its specification-owned purpose/lifecycle
+ * prose and the compiled relationship facts from the resolved resource graph.
+ */
+export declare const ResourceTagSchema: z.ZodObject<{
+    /** Must equal the `resourceIdentifier` the generator derives the tag from. */
+    name: z.ZodString;
+    /** Business-purpose prose for the resource group. */
+    description: z.ZodOptional<z.ZodString>;
+    /** Specification-owned explanation of how this resource changes over time. */
+    lifecycleRole: z.ZodOptional<z.ZodString>;
+    /** Compiled relationship facts relevant to this resource. */
+    relationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        relatedResourceName: z.ZodString;
+        /** Resolved FK identity when the relationship is represented by a field. */
+        foreignKeyField: z.ZodOptional<z.ZodString>;
+        resourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+        relatedResourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+        nature: z.ZodEnum<typeof ResourceRelationshipDocumentationNature>;
+        lifecycleModel: z.ZodEnum<typeof ResourceRelationshipDocumentationLifecycleModel>;
+        onParentDelete: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodBoolean;
+            mode: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteMode>;
+            strategy: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteStrategy>;
+            maxDepth: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    /** Explicit application-owned API-reference navigation grouping. */
+    category: z.ZodOptional<z.ZodObject<{
+        /** Stable, readable public identity used in API-reference fragments. */
+        id: z.ZodString;
+        /** Consumer-facing category label displayed by the renderer. */
+        label: z.ZodString;
+        /** Optional category orientation supplied by the application, never React. */
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceTag = z.infer<typeof ResourceTagSchema>;
+/**
+ * One OpenAPI `servers[]` entry — a base URL the API is reachable at, plus an
+ * optional human label. **App-enriched**: deployment URLs are an
+ * application/environment concern (the framework cannot know an app's prod
+ * domain), so they are authored on `WildoTechnicalDocConfig.apiServers` and
+ * threaded into `OpenApiGenerationInput.servers`. The shared shape lives here
+ * (the boundary-clean, zod-only module the generator consumes); the config
+ * schema imports it so the two never drift.
+ */
+export declare const OpenApiServerSchema: z.ZodObject<{
+    /**
+     * Base URL — the bare ORIGIN the API is served from, e.g.
+     * `http://localhost:4241` or `https://api.example.com`. Do NOT append the
+     * `/api/v1` mount: the generated operation `paths` are already mount-prefixed
+     * (`/api/v1/...`), and the effective request URL is `server.url` + path — so
+     * including the mount here would DOUBLE it (`…/api/v1/api/v1/...`).
+     */
+    url: z.ZodString;
+    /** Optional human label shown in the docs server picker (e.g. "Production"). */
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OpenApiServer = z.infer<typeof OpenApiServerSchema>;
+/**
+ * Top-level wire format consumed by the OpenAPI generator. Wrapped
+ * in an object so the projector can attach metadata (app slug, build
+ * timestamp, framework version) without a schema-shape break later.
+ */
+export declare const OpenApiGenerationInputSchema: z.ZodObject<{
+    /**
+     * App slug from `WildoSaasConfig.slug`. Surfaces in the generated
+     * `openapi.info.title` so a
+     * multi-app generation run can be disambiguated. Free-string
+     * (no validation against `WildoSaasConfigSchema.slug` regex) because
+     * the generator should not gate on the same constraint twice; the
+     * `defineSaasConfig` parser already enforced the shape at author time.
+     */
+    appSlug: z.ZodString;
+    /**
+     * App display name from `WildoSaasConfig.displayName` — used as the
+     * default base title in the generated `openapi.info.title`. The
+     * companion route concatenates it with the section name
+     * (`"Wonder Todos API reference"`).
+     */
+    appDisplayName: z.ZodString;
+    /**
+     * Optional public marketing title from `WildoSaasConfig.technicalDoc.publicMarketingTitle`.
+     * When present, replaces `appDisplayName` in the generated title so
+     * the OpenAPI docs match the docs site landing page.
+     */
+    publicMarketingTitle: z.ZodOptional<z.ZodString>;
+    /** Exact supported public API contract release surfaced in `openapi.info.version`. */
+    supportedApiVersion: z.ZodString;
+    /**
+     * Flat list of all URL-bearing operation projections. The projector includes
+     * every exposed operation and resolves its consumer section explicitly; the
+     * generator validates, groups and renders without eligibility inference.
+     */
+    operations: z.ZodArray<z.ZodObject<{
+        resourceIdentifier: z.ZodString;
+        operationKey: z.ZodString;
+        /**
+         * The RAW operation identifier (e.g. `CREATE`, `LIST`, `EXPORT_AUDIT_LOGS`,
+         * `ROTATE_TOKEN`) WITHOUT the variant / bulk / multi-path qualifiers that
+         * `operationKey` appends. `buildOperationId` needs this to compose a
+         * verb-first developer-facing operationId (`createOrganization`): the verb
+         * is derived from the base identifier and the resource noun from
+         * `resourceIdentifier`, while the qualifiers are `operationKey` with this
+         * prefix removed. Carried separately because a base identifier can itself
+         * contain `_` (e.g. `EXPORT_AUDIT_LOGS`), so the qualifier boundary cannot be
+         * recovered from `operationKey` alone.
+         */
+        baseOperationIdentifier: z.ZodString;
+        /** Exact runtime variant discriminator. `null` is the canonical default variant. */
+        variantKey: z.ZodNullable<z.ZodString>;
+        variantType: z.ZodEnum<typeof OperationProjectionVariantType>;
+        httpVerb: z.ZodEnum<typeof OperationProjectionHttpVerb>;
+        path: z.ZodString;
+        primaryScope: z.ZodEnum<typeof OperationProjectionPrimaryScope>;
+        /**
+         * Consumer-facing documentation section resolved at the source-authority
+         * boundary. The OpenAPI generator groups by this explicit fact; it must not
+         * reinterpret internal scopes or role strings into product navigation.
+         */
+        consumerApiSection: z.ZodEnum<typeof OpenApiSection>;
+        /**
+         * Stable source identity used for conservation and the strict `x-wildo`
+         * extension. It is not a human-facing operationId and never depends on
+         * iteration order or display prose.
+         */
+        identity: z.ZodObject<{
+            contractVersion: z.ZodLiteral<1>;
+            resourceRef: z.ZodString;
+            operationFamilyRef: z.ZodString;
+            operationVariantRef: z.ZodString;
+            variantType: z.ZodEnum<typeof OperationProjectionVariantType>;
+            httpVerb: z.ZodEnum<typeof OperationProjectionHttpVerb>;
+            path: z.ZodString;
+        }, z.core.$strict>;
+        roles: z.ZodArray<z.ZodString>;
+        /**
+         * Source-resolved consumer access explanation. This must remain aligned with
+         * `roles`: the projector is the only place allowed to interpret access-mode
+         * sentinels and attach the app's role-specification prose.
+         */
+        access: z.ZodObject<{
+            authenticationMode: z.ZodEnum<typeof OperationProjectionAuthenticationMode>;
+            authenticationSummary: z.ZodString;
+            roleRequirements: z.ZodArray<z.ZodObject<{
+                role: z.ZodString;
+                label: z.ZodString;
+                businessRole: z.ZodNullable<z.ZodString>;
+                authorityBoundary: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        isApiKeyAccessDisabled: z.ZodBoolean;
+        stepUpAuthentication: z.ZodOptional<z.ZodObject<{
+            headerName: z.ZodString;
+            tokenEndpointPath: z.ZodString;
+        }, z.core.$strict>>;
+        acceptsIfMatch: z.ZodBoolean;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        /**
+         * JSON-Schema fragment representing the request body (or query for
+         * GET / DELETE if the projector chose to flatten query parameters
+         * into a single schema). The exact shape is whatever
+         * `z.toJSONSchema()` emits. For POST / PUT / PATCH style verbs the
+         * generator passes it through unchanged into the OpenAPI
+         * `requestBody.content.application/json.schema` slot. For GET /
+         * DELETE the generator expects an object-shaped schema and explodes
+         * the top-level properties into `parameters[]` entries with
+         * `in: 'query'`. `null` means "no request input".
+         */
+        requestBodySchema: z.ZodNullable<z.ZodUnknown>;
+        /**
+         * JSON-Schema fragment representing the 2xx response body. `null`
+         * means "no body" → emitted as a 204-style `responses` entry with
+         * description only. `unknown` to stay format-agnostic; the
+         * projector is responsible for emitting valid JSON Schema.
+         */
+        responseBodySchema: z.ZodNullable<z.ZodUnknown>;
+        /**
+         * Paginated-collection query contract — present iff the operation is a
+         * framework paginated collection operation (a `LIST` / `SEARCH` core
+         * operation, or a custom operation borrowing one via
+         * `resourceOperationLike`). Those operations universally accept the flat
+         * `page` / `limit` / `sort` query parameters and return the
+         * `{ data, pagination }` envelope (the backend controller forces
+         * `paginated: true` for every HTTP LIST/SEARCH dispatch), but NONE of that
+         * appears in the operation's request DTO — without this block the generator
+         * would document a paginated endpoint with no way to page it.
+         *
+         * The PROJECTOR resolves the per-operation values (it sees the resolved
+         * runtime operation); the GENERATOR owns the universal parameter shapes and
+         * the framework-constant defaults (`page` defaults to 1, `limit` to 20 —
+         * mirrors of the repository `_doList` defaults). Split chosen so this wire
+         * schema stays framework-decoupled: the projection carries FACTS, not
+         * OpenAPI fragments.
+         *
+         *  - `maxLimit` — largest accepted `limit` value. Resolved from the
+         *    operation's `maxPaginatedResultPerPageLimit ?? 50` (the same fallback
+         *    the frontend HTTP client clamps with; only SEARCH-like operations can
+         *    author a different cap today).
+         *  - `sortableFields` — the operation's declared `sortFields` allow-list.
+         *    Non-empty: only these fields may be named in `sort` (unrecognised
+         *    fields are silently ignored by the backend validator) and the default
+         *    ordering is the first entry, descending. Empty: the backend applies
+         *    any requested field verbatim and defaults to `createdAt:desc`.
+         */
+        pagination: z.ZodOptional<z.ZodObject<{
+            maxLimit: z.ZodNumber;
+            sortableFields: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        /**
+         * Path of the asynchronous callback (`API_CALL_WITH_CALLBACK` only).
+         * The generator turns this into an OpenAPI `callbacks:` block
+         * referencing the same `responseBodySchema`.
+         */
+        callbackPath: z.ZodOptional<z.ZodString>;
+        /**
+         * Tier-3 authored HTTP documentation, projected from the resource
+         * specification's operation overlay. All optional; when present the
+         * generator emits real `responses` (success + error), request/response
+         * `examples`, an `x-idempotent` extension, and a rate-limit note instead of
+         * the default single `200`/`204`. `code` / `forStatus` are OpenAPI status
+         * keys (`'200'`, `'404'`, …).
+         */
+        responseStatuses: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            meaning: z.ZodString;
+        }, z.core.$strict>>>;
+        errorScenarios: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            when: z.ZodString;
+            errorCode: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        idempotent: z.ZodOptional<z.ZodBoolean>;
+        rateLimitNote: z.ZodOptional<z.ZodString>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            request: z.ZodOptional<z.ZodUnknown>;
+            response: z.ZodOptional<z.ZodUnknown>;
+            forStatus: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    /**
+     * JSON Schema for the canonical framework HTTP error envelope. The
+     * subprocess converts the same `ErrorResponseSchema` the backend serializes;
+     * the generator registers it once as `components.schemas.ErrorResponse` and
+     * references it from every documented non-success response. Keeping this
+     * here makes the OpenAPI document an exact projection of the runtime wire
+     * contract rather than a renderer-owned approximation.
+     */
+    errorResponseSchema: z.ZodUnknown;
+    /**
+     * Optional resource → tag-description descriptors. The generator emits each
+     * one as an OpenAPI top-level `tags[].description` for the tags it derives
+     * from a section's operations; resources without a descriptor still get a
+     * bare `{ name }` tag. Order-independent (the generator looks up by `name`).
+     */
+    resourceTags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Must equal the `resourceIdentifier` the generator derives the tag from. */
+        name: z.ZodString;
+        /** Business-purpose prose for the resource group. */
+        description: z.ZodOptional<z.ZodString>;
+        /** Specification-owned explanation of how this resource changes over time. */
+        lifecycleRole: z.ZodOptional<z.ZodString>;
+        /** Compiled relationship facts relevant to this resource. */
+        relationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            relatedResourceName: z.ZodString;
+            /** Resolved FK identity when the relationship is represented by a field. */
+            foreignKeyField: z.ZodOptional<z.ZodString>;
+            resourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+            relatedResourceCardinality: z.ZodEnum<typeof ResourceRelationshipDocumentationCardinality>;
+            nature: z.ZodEnum<typeof ResourceRelationshipDocumentationNature>;
+            lifecycleModel: z.ZodEnum<typeof ResourceRelationshipDocumentationLifecycleModel>;
+            onParentDelete: z.ZodOptional<z.ZodObject<{
+                enabled: z.ZodBoolean;
+                mode: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteMode>;
+                strategy: z.ZodEnum<typeof ResourceRelationshipDocumentationDeleteStrategy>;
+                maxDepth: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        /** Explicit application-owned API-reference navigation grouping. */
+        category: z.ZodOptional<z.ZodObject<{
+            /** Stable, readable public identity used in API-reference fragments. */
+            id: z.ZodString;
+            /** Consumer-facing category label displayed by the renderer. */
+            label: z.ZodString;
+            /** Optional category orientation supplied by the application, never React. */
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    /**
+     * Optional OpenAPI `servers[]` — the base URLs the API is reachable at.
+     * App-enriched via `WildoTechnicalDocConfig.apiServers` (deployment URLs are
+     * application/environment knowledge, not framework knowledge). When omitted
+     * the generator emits no `servers` block (back-compatible with the
+     * pre-servers output). Each entry is `{ url, description? }`.
+     */
+    servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /**
+         * Base URL — the bare ORIGIN the API is served from, e.g.
+         * `http://localhost:4241` or `https://api.example.com`. Do NOT append the
+         * `/api/v1` mount: the generated operation `paths` are already mount-prefixed
+         * (`/api/v1/...`), and the effective request URL is `server.url` + path — so
+         * including the mount here would DOUBLE it (`…/api/v1/api/v1/...`).
+         */
+        url: z.ZodString;
+        /** Optional human label shown in the docs server picker (e.g. "Production"). */
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    /**
+     * Optional app-authored markdown intro for the API reference landing page,
+     * from `WildoTechnicalDocConfig.apiOverview`. The generator PREPENDS it to the
+     * framework-universal "## API conventions" block (auth / pagination /
+     * idempotency / errors — which it always emits) to form `info.description`.
+     * App enrichment: the conventions are framework knowledge; the overview is the
+     * app's own framing.
+     */
+    apiOverview: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type OpenApiGenerationInput = z.infer<typeof OpenApiGenerationInputSchema>;
+//# sourceMappingURL=operation-projection.schemas.d.ts.map