@wildo-ai/saas-technical-doc 1.1.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"operation-projection.schemas.d.ts","sourceRoot":"","sources":["../../../../src/companion/operation-projection.schemas.ts"],"names":[],"mappings":"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"}

package/dist/esm/companion/operation-projection.schemas.js

@@ -0,0 +1,610 @@
+/**
+ * @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 { TechnicalDocumentationSupportedApiVersionSchema } from '@wildo-ai/saas-specifications/technical-documentation';
+import { z } from 'zod';
+import { OpenApiSection } from '../openapi/openapi-generation-output.schemas.js';
+/**
+ * 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 var OperationProjectionVariantType;
+(function (OperationProjectionVariantType) {
+    OperationProjectionVariantType["API_CALL"] = "api_call";
+    OperationProjectionVariantType["API_CALL_WITH_CALLBACK"] = "api_call_with_callback";
+})(OperationProjectionVariantType || (OperationProjectionVariantType = {}));
+/**
+ * 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 var OperationProjectionPrimaryScope;
+(function (OperationProjectionPrimaryScope) {
+    OperationProjectionPrimaryScope["USER_SELF"] = "user_self";
+    OperationProjectionPrimaryScope["ORGANIZATIONS"] = "organizations";
+    OperationProjectionPrimaryScope["APPLICATION"] = "applications";
+    OperationProjectionPrimaryScope["ANONYMOUS"] = "anonymous";
+})(OperationProjectionPrimaryScope || (OperationProjectionPrimaryScope = {}));
+/**
+ * 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 var OperationProjectionHttpVerb;
+(function (OperationProjectionHttpVerb) {
+    OperationProjectionHttpVerb["GET"] = "get";
+    OperationProjectionHttpVerb["POST"] = "post";
+    OperationProjectionHttpVerb["PUT"] = "put";
+    OperationProjectionHttpVerb["DELETE"] = "delete";
+    OperationProjectionHttpVerb["PATCH"] = "patch";
+})(OperationProjectionHttpVerb || (OperationProjectionHttpVerb = {}));
+/**
+ * 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 var OperationProjectionAuthenticationMode;
+(function (OperationProjectionAuthenticationMode) {
+    OperationProjectionAuthenticationMode["PUBLIC"] = "public";
+    OperationProjectionAuthenticationMode["ANONYMOUS_SESSION"] = "anonymous_session";
+    OperationProjectionAuthenticationMode["AUTHENTICATED"] = "authenticated";
+    OperationProjectionAuthenticationMode["ANONYMOUS_OR_AUTHENTICATED"] = "anonymous_or_authenticated";
+})(OperationProjectionAuthenticationMode || (OperationProjectionAuthenticationMode = {}));
+/**
+ * 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 const OperationRoleRequirementSchema = z.strictObject({
+    role: z.string().min(1),
+    label: z.string().min(1).max(200),
+    businessRole: z.string().min(1).max(4000).nullable(),
+    authorityBoundary: z.string().min(1).max(4000).nullable(),
+});
+/**
+ * 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 const OperationAccessDocumentationSchema = z.strictObject({
+    authenticationMode: z.enum(OperationProjectionAuthenticationMode),
+    authenticationSummary: z.string().min(1).max(500),
+    roleRequirements: z.array(OperationRoleRequirementSchema),
+});
+/** Versioned identity carried from the resolved HTTP operation into OpenAPI. */
+export const OPENAPI_OPERATION_IDENTITY_CONTRACT_VERSION = 1;
+/** Versioned identity carried by each generated OpenAPI resource tag. */
+export 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 const OpenApiOperationIdentitySchema = z.strictObject({
+    contractVersion: z.literal(OPENAPI_OPERATION_IDENTITY_CONTRACT_VERSION),
+    resourceRef: z.string().min(1),
+    operationFamilyRef: z.string().min(1),
+    operationVariantRef: z.string().min(1),
+    variantType: z.enum(OperationProjectionVariantType),
+    httpVerb: z.enum(OperationProjectionHttpVerb),
+    path: z.string().min(1),
+});
+/**
+ * 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 function createOpenApiOperationIdentity(input) {
+    const encode = (value) => encodeURIComponent(value);
+    const resourceRef = `technical-documentation:resource/${encode(input.resourceIdentifier)}`;
+    const operationFamilyRef = `${resourceRef}/operation-family/${encode(input.baseOperationIdentifier)}`;
+    const variantSegment = input.variantKey === null ? 'default' : encode(input.variantKey);
+    return {
+        contractVersion: OPENAPI_OPERATION_IDENTITY_CONTRACT_VERSION,
+        resourceRef,
+        operationFamilyRef,
+        operationVariantRef: `${operationFamilyRef}/variant/${variantSegment}/${input.variantType}/${input.httpVerb}/${encode(input.path)}`,
+        variantType: input.variantType,
+        httpVerb: input.httpVerb,
+        path: input.path,
+    };
+}
+/**
+ * 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 const OperationProjectionSchema = z.strictObject({
+    resourceIdentifier: z.string().min(1),
+    operationKey: z.string().min(1),
+    /**
+     * 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.string().min(1),
+    /** Exact runtime variant discriminator. `null` is the canonical default variant. */
+    variantKey: z.string().min(1).nullable(),
+    variantType: z.enum(OperationProjectionVariantType),
+    httpVerb: z.enum(OperationProjectionHttpVerb),
+    path: z.string().min(1),
+    primaryScope: z.enum(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.enum(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: OpenApiOperationIdentitySchema,
+    // Resolved role list (enum → string). MAY be empty: an operation with no
+    // declared roles is a real, intentional runtime state — an open / no-specific-
+    // role-gate endpoint (e.g. the core `users` LIST: "app users can list users").
+    // Each entry must be a non-empty string, but the array itself can be `[]`. The
+    // source classifier treats an empty role set as normal API, not application
+    // administration. NOT `.min(1)` — not every engine endpoint is role-gated.
+    roles: z.array(z.string().min(1)),
+    /**
+     * 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: OperationAccessDocumentationSchema,
+    isApiKeyAccessDisabled: z.boolean(),
+    stepUpAuthentication: z.strictObject({
+        headerName: z.string().min(1),
+        tokenEndpointPath: z.string().min(1),
+    }).optional(),
+    acceptsIfMatch: z.boolean(),
+    summary: z.string().min(1).max(200).optional(),
+    description: z.string().min(1).max(2000).optional(),
+    /**
+     * 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.unknown().nullable(),
+    /**
+     * 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.unknown().nullable(),
+    /**
+     * 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.strictObject({
+        maxLimit: z.number().int().min(1),
+        sortableFields: z.array(z.string().min(1)),
+    }).optional(),
+    /**
+     * 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.string().min(1).optional(),
+    /**
+     * 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.array(z.strictObject({
+        code: z.string().min(1),
+        meaning: z.string().min(1),
+    })).optional(),
+    errorScenarios: z.array(z.strictObject({
+        code: z.string().min(1),
+        when: z.string().min(1),
+        errorCode: z.string().min(1).optional(),
+    })).optional(),
+    idempotent: z.boolean().optional(),
+    rateLimitNote: z.string().min(1).optional(),
+    examples: z.array(z.strictObject({
+        title: z.string().min(1),
+        request: z.unknown().optional(),
+        response: z.unknown().optional(),
+        forStatus: z.string().min(1).optional(),
+    })).optional(),
+}).superRefine((projection, ctx) => {
+    if (projection.identity.variantType !== projection.variantType
+        || projection.identity.httpVerb !== projection.httpVerb
+        || projection.identity.path !== projection.path) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['identity'],
+            message: 'OperationProjection identity must exactly mirror the resolved variant type, HTTP verb and path.',
+        });
+    }
+    if (projection.variantType === OperationProjectionVariantType.API_CALL_WITH_CALLBACK) {
+        if (projection.callbackPath === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['callbackPath'],
+                message: `OperationProjection for '${projection.resourceIdentifier}.${projection.operationKey}' ` +
+                    `has variantType=${OperationProjectionVariantType.API_CALL_WITH_CALLBACK} but no callbackPath. ` +
+                    `The introspection projector MUST populate callbackPath for callback variants — without it the generator ` +
+                    `cannot emit an OpenAPI \`callbacks:\` block, which would silently produce a misleading doc that ` +
+                    `looks like a regular synchronous endpoint.`,
+            });
+        }
+    }
+    else if (projection.callbackPath !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['callbackPath'],
+            message: `OperationProjection for '${projection.resourceIdentifier}.${projection.operationKey}' ` +
+                `has callbackPath but variantType=${projection.variantType} (expected ${OperationProjectionVariantType.API_CALL_WITH_CALLBACK}). ` +
+                `Reject at parse time so the projector bug surfaces immediately rather than producing a doc with phantom callback metadata.`,
+        });
+    }
+});
+/**
+ * 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 var ResourceRelationshipDocumentationCardinality;
+(function (ResourceRelationshipDocumentationCardinality) {
+    ResourceRelationshipDocumentationCardinality["ONE"] = "one";
+    ResourceRelationshipDocumentationCardinality["ZERO_OR_ONE"] = "zero_or_one";
+    ResourceRelationshipDocumentationCardinality["ONE_OR_MANY"] = "one_or_many";
+    ResourceRelationshipDocumentationCardinality["MANY"] = "many";
+})(ResourceRelationshipDocumentationCardinality || (ResourceRelationshipDocumentationCardinality = {}));
+/** The three developer-authored relationship meanings projected into OpenAPI. */
+export var ResourceRelationshipDocumentationNature;
+(function (ResourceRelationshipDocumentationNature) {
+    ResourceRelationshipDocumentationNature["COMPOSITION"] = "composition";
+    ResourceRelationshipDocumentationNature["REFERENCE"] = "reference";
+    ResourceRelationshipDocumentationNature["ASSOCIATION"] = "association";
+})(ResourceRelationshipDocumentationNature || (ResourceRelationshipDocumentationNature = {}));
+/** The compiled lifecycle dependency of a relationship, not a presentation hint. */
+export var ResourceRelationshipDocumentationLifecycleModel;
+(function (ResourceRelationshipDocumentationLifecycleModel) {
+    ResourceRelationshipDocumentationLifecycleModel["DEPENDENT"] = "dependent";
+    ResourceRelationshipDocumentationLifecycleModel["INDEPENDENT"] = "independent";
+    ResourceRelationshipDocumentationLifecycleModel["LINK_ONLY"] = "link_only";
+})(ResourceRelationshipDocumentationLifecycleModel || (ResourceRelationshipDocumentationLifecycleModel = {}));
+/** Execution timing for an explicitly configured parent-delete lifecycle. */
+export var ResourceRelationshipDocumentationDeleteMode;
+(function (ResourceRelationshipDocumentationDeleteMode) {
+    ResourceRelationshipDocumentationDeleteMode["IMMEDIATE"] = "immediate";
+    ResourceRelationshipDocumentationDeleteMode["LAZY"] = "lazy";
+})(ResourceRelationshipDocumentationDeleteMode || (ResourceRelationshipDocumentationDeleteMode = {}));
+/** Effect of an explicitly configured parent-delete lifecycle. */
+export var ResourceRelationshipDocumentationDeleteStrategy;
+(function (ResourceRelationshipDocumentationDeleteStrategy) {
+    ResourceRelationshipDocumentationDeleteStrategy["DELETE"] = "delete";
+    ResourceRelationshipDocumentationDeleteStrategy["IMPERSONALIZE_AND_RETAIN"] = "impersonalize_and_retain";
+})(ResourceRelationshipDocumentationDeleteStrategy || (ResourceRelationshipDocumentationDeleteStrategy = {}));
+/**
+ * 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 const ResourceRelationshipDocumentationSchema = z.strictObject({
+    relatedResourceName: z.string().min(1),
+    /** Resolved FK identity when the relationship is represented by a field. */
+    foreignKeyField: z.string().min(1).optional(),
+    resourceCardinality: z.enum(ResourceRelationshipDocumentationCardinality),
+    relatedResourceCardinality: z.enum(ResourceRelationshipDocumentationCardinality),
+    nature: z.enum(ResourceRelationshipDocumentationNature),
+    lifecycleModel: z.enum(ResourceRelationshipDocumentationLifecycleModel),
+    onParentDelete: z.strictObject({
+        enabled: z.boolean(),
+        mode: z.enum(ResourceRelationshipDocumentationDeleteMode),
+        strategy: z.enum(ResourceRelationshipDocumentationDeleteStrategy),
+        maxDepth: z.number().int().min(0),
+    }).optional(),
+});
+/**
+ * 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 const ApiReferenceResourceCategorySchema = z.strictObject({
+    /** Stable, readable public identity used in API-reference fragments. */
+    id: z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/).max(100),
+    /** Consumer-facing category label displayed by the renderer. */
+    label: z.string().min(1).max(200),
+    /** Optional category orientation supplied by the application, never React. */
+    description: z.string().min(1).max(2000).optional(),
+});
+/**
+ * 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 const ResourceTagSchema = z.strictObject({
+    /** Must equal the `resourceIdentifier` the generator derives the tag from. */
+    name: z.string().min(1),
+    /** Business-purpose prose for the resource group. */
+    description: z.string().min(1).max(2000).optional(),
+    /** Specification-owned explanation of how this resource changes over time. */
+    lifecycleRole: z.string().min(1).max(4000).optional(),
+    /** Compiled relationship facts relevant to this resource. */
+    relationships: z.array(ResourceRelationshipDocumentationSchema).optional(),
+    /** Explicit application-owned API-reference navigation grouping. */
+    category: ApiReferenceResourceCategorySchema.optional(),
+});
+/**
+ * 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 const OpenApiServerSchema = z.strictObject({
+    /**
+     * 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.string().min(1),
+    /** Optional human label shown in the docs server picker (e.g. "Production"). */
+    description: z.string().min(1).max(200).optional(),
+});
+/**
+ * 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 const OpenApiGenerationInputSchema = z.strictObject({
+    /**
+     * 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.string().min(1),
+    /**
+     * 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.string().min(1),
+    /**
+     * 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.string().min(1).max(200).optional(),
+    /** Exact supported public API contract release surfaced in `openapi.info.version`. */
+    supportedApiVersion: TechnicalDocumentationSupportedApiVersionSchema,
+    /**
+     * 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.array(OperationProjectionSchema),
+    /**
+     * 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.unknown(),
+    /**
+     * 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.array(ResourceTagSchema).optional(),
+    /**
+     * 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.array(OpenApiServerSchema).optional(),
+    /**
+     * 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.string().min(1).max(8000).optional(),
+});
+//# sourceMappingURL=operation-projection.schemas.js.map