@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/content.exports.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@wildo-ai/saas-technical-doc/content` — reusable application-consumer documentation content and portable identity contracts.
+ *
+ * This entry point is deliberately neutral: it contains no filesystem access, application discovery, runtime evidence, publication policy, React or
+ * browser runtime. Application companions may combine this engine-owned content with accepted application semantics and authorized operational evidence.
+ */
+export * from './content/application-consumer-documentation-content-manifest.schemas';
+export * from './content/application-consumer-documentation-content.techdoc';
+//# sourceMappingURL=content.exports.d.ts.map

package/dist/esm/content.exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.exports.d.ts","sourceRoot":"","sources":["../../../src/content.exports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,uEAAuE,CAAC;AACtF,cAAc,8DAA8D,CAAC"}

package/dist/esm/content.exports.js

@@ -0,0 +1,9 @@
+/**
+ * `@wildo-ai/saas-technical-doc/content` — reusable application-consumer documentation content and portable identity contracts.
+ *
+ * This entry point is deliberately neutral: it contains no filesystem access, application discovery, runtime evidence, publication policy, React or
+ * browser runtime. Application companions may combine this engine-owned content with accepted application semantics and authorized operational evidence.
+ */
+export * from './content/application-consumer-documentation-content-manifest.schemas.js';
+export * from './content/application-consumer-documentation-content.techdoc.js';
+//# sourceMappingURL=content.exports.js.map

package/dist/esm/content.exports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.exports.js","sourceRoot":"","sources":["../../../src/content.exports.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,uEAAuE,CAAC;AACtF,cAAc,8DAA8D,CAAC","sourcesContent":["/**\n * `@wildo-ai/saas-technical-doc/content` — reusable application-consumer documentation content and portable identity contracts.\n *\n * This entry point is deliberately neutral: it contains no filesystem access, application discovery, runtime evidence, publication policy, React or\n * browser runtime. Application companions may combine this engine-owned content with accepted application semantics and authorized operational evidence.\n */\n\nexport * from './content/application-consumer-documentation-content-manifest.schemas';\nexport * from './content/application-consumer-documentation-content.techdoc';\n"]}

package/dist/esm/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc
+ *
+ * SaaS technical documentation engine — portable OpenAPI contracts and the
+ * strict per-service documentation configuration authoring surface. Framework
+ * consumer prose is exposed separately through `./content`; companion-side
+ * projection and rendering live under `./companion`.
+ *
+ * @wildo-boundary
+ *   - This barrel re-exports the shared (Node + companion + Docusaurus
+ *     build) surface: OpenAPI generation output types and the per-service
+ *     config schema + define helper.
+ *   - The browser-only React + fetch runtime lives in `./runtime/` and is
+ *     re-exported via the package's `./runtime` subpath export — NOT here.
+ *   - The Node-only OpenAPI generator code lives in `./companion/` and is
+ *     re-exported via the package's `./companion` subpath export — NOT here.
+ *   - This separation keeps the docs Docusaurus bundle from accidentally
+ *     pulling Node-only code, and keeps the companion subprocess from
+ *     accidentally pulling React.
+ *   - `defineTechnicalDocConfig` parses the Node-authored service config and
+ *     belongs in companion/build code. Browser code consumes already-resolved
+ *     runtime artifacts through `./runtime`; it must not author configuration.
+ */
+export * from './openapi/index';
+export * from './config/index';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,26 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc
+ *
+ * SaaS technical documentation engine — portable OpenAPI contracts and the
+ * strict per-service documentation configuration authoring surface. Framework
+ * consumer prose is exposed separately through `./content`; companion-side
+ * projection and rendering live under `./companion`.
+ *
+ * @wildo-boundary
+ *   - This barrel re-exports the shared (Node + companion + Docusaurus
+ *     build) surface: OpenAPI generation output types and the per-service
+ *     config schema + define helper.
+ *   - The browser-only React + fetch runtime lives in `./runtime/` and is
+ *     re-exported via the package's `./runtime` subpath export — NOT here.
+ *   - The Node-only OpenAPI generator code lives in `./companion/` and is
+ *     re-exported via the package's `./companion` subpath export — NOT here.
+ *   - This separation keeps the docs Docusaurus bundle from accidentally
+ *     pulling Node-only code, and keeps the companion subprocess from
+ *     accidentally pulling React.
+ *   - `defineTechnicalDocConfig` parses the Node-authored service config and
+ *     belongs in companion/build code. Browser code consumes already-resolved
+ *     runtime artifacts through `./runtime`; it must not author configuration.
+ */
+export * from './openapi/index.js';
+export * from './config/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC","sourcesContent":["/**\n * @wildo-package @wildo-ai/saas-technical-doc\n *\n * SaaS technical documentation engine — portable OpenAPI contracts and the\n * strict per-service documentation configuration authoring surface. Framework\n * consumer prose is exposed separately through `./content`; companion-side\n * projection and rendering live under `./companion`.\n *\n * @wildo-boundary\n *   - This barrel re-exports the shared (Node + companion + Docusaurus\n *     build) surface: OpenAPI generation output types and the per-service\n *     config schema + define helper.\n *   - The browser-only React + fetch runtime lives in `./runtime/` and is\n *     re-exported via the package's `./runtime` subpath export — NOT here.\n *   - The Node-only OpenAPI generator code lives in `./companion/` and is\n *     re-exported via the package's `./companion` subpath export — NOT here.\n *   - This separation keeps the docs Docusaurus bundle from accidentally\n *     pulling Node-only code, and keeps the companion subprocess from\n *     accidentally pulling React.\n *   - `defineTechnicalDocConfig` parses the Node-authored service config and\n *     belongs in companion/build code. Browser code consumes already-resolved\n *     runtime artifacts through `./runtime`; it must not author configuration.\n */\n\nexport * from './openapi/index';\nexport * from './config/index';\n"]}

package/dist/esm/openapi/api-reference-link-index.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Semantic links into the generated API reference.
+ *
+ * This module projects a canonical OpenAPI document into a small index of
+ * public paths. It does not describe or navigate API contracts itself: every
+ * entry is derived from standard OpenAPI fields plus the strict `x-wildo`
+ * source identities already present in the document. Guide generation can use
+ * the index to link to exact API targets without hard-coding Docusaurus URLs
+ * or duplicating operations, request DTOs, responses, or schemas.
+ */
+import { OpenApiSection, type OpenApiSectionOutput } from './openapi-generation-output.schemas';
+import { type TechnicalDocumentationApiReferenceTargetV1 } from '@wildo-ai/saas-specifications/technical-documentation';
+/** The semantic source identity a guide may resolve to a consumer API URL. */
+export declare enum ApiReferenceLinkIdentityKind {
+    /** A generated section exists and its root page is a valid public destination. */
+    ROOT = "ROOT",
+    CATEGORY = "CATEGORY",
+    RESOURCE = "RESOURCE",
+    OPERATION_FAMILY = "OPERATION_FAMILY",
+    OPERATION_VARIANT = "OPERATION_VARIANT",
+    REQUEST = "REQUEST",
+    RESPONSE = "RESPONSE",
+    COMPONENT_SCHEMA = "COMPONENT_SCHEMA"
+}
+export type ApiReferenceLinkIdentity = {
+    readonly kind: ApiReferenceLinkIdentityKind.ROOT;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.CATEGORY;
+    readonly categoryId: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.RESOURCE;
+    readonly resourceRef: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY;
+    readonly operationFamilyRef: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT;
+    readonly operationVariantRef: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.REQUEST;
+    readonly operationVariantRef: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.RESPONSE;
+    readonly operationVariantRef: string;
+    readonly status: string;
+} | {
+    readonly kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA;
+    readonly schemaName: string;
+};
+/** One resolved public URL. `section` keeps an identity unambiguous across both API references. */
+export interface ApiReferenceLinkIndexEntry {
+    readonly section: OpenApiSection;
+    readonly identity: ApiReferenceLinkIdentity;
+    readonly href: string;
+}
+/** JSON-safe result of projecting the selected OpenAPI documents. */
+export interface ApiReferenceLinkIndex {
+    readonly schemaVersion: 1;
+    readonly entries: readonly ApiReferenceLinkIndexEntry[];
+}
+/**
+ * Result of asking whether one semantic guide target exists in the exact
+ * generated OpenAPI index. This is deliberately not a boolean: the named
+ * vocabulary keeps availability decisions readable at guide-composition call
+ * sites and leaves room for future source-owned states without overloading
+ * `false`.
+ */
+export declare enum TechnicalDocumentationApiReferenceTargetAvailability {
+    AVAILABLE = "AVAILABLE",
+    UNAVAILABLE = "UNAVAILABLE"
+}
+/**
+ * Creates links from the exact generated OpenAPI documents.
+ *
+ * This is intentionally a fail-closed projection. An HTTP operation without
+ * the established source identity, a tag/operation resource mismatch, or a
+ * duplicate semantic target means guide links could become ambiguous, so the
+ * index is not emitted at all.
+ */
+export declare function createApiReferenceLinkIndex(sections: readonly OpenApiSectionOutput[]): ApiReferenceLinkIndex;
+/** Resolves one semantic API target and fails loudly when a guide asks for unavailable documentation. */
+export declare function resolveApiReferenceLink(index: ApiReferenceLinkIndex, section: OpenApiSection, identity: ApiReferenceLinkIdentity): string;
+/**
+ * Answers whether a typed target exists in the generated OpenAPI index without
+ * manufacturing a URL or turning normal optional-content selection into an
+ * exception path. Included guide links must still use the strict resolver.
+ */
+export declare function getTechnicalDocumentationApiReferenceTargetAvailability(index: ApiReferenceLinkIndex, target: TechnicalDocumentationApiReferenceTargetV1): TechnicalDocumentationApiReferenceTargetAvailability;
+/**
+ * Resolves a portable guide target through the generated OpenAPI index.
+ *
+ * The technical-documentation contract owns the semantic target because guide
+ * content cannot depend on the renderer package. This adapter is the only
+ * place that translates that portable target into the OpenAPI identities used
+ * to produce public consumer URLs.
+ */
+export declare function resolveTechnicalDocumentationApiReferenceLink(index: ApiReferenceLinkIndex, target: TechnicalDocumentationApiReferenceTargetV1): string;
+//# sourceMappingURL=api-reference-link-index.d.ts.map

package/dist/esm/openapi/api-reference-link-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-reference-link-index.d.ts","sourceRoot":"","sources":["../../../../src/openapi/api-reference-link-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChG,OAAO,EAGL,KAAK,0CAA0C,EAChD,MAAM,uDAAuD,CAAC;AAQ/D,8EAA8E;AAC9E,oBAAY,4BAA4B;IACtC,kFAAkF;IAClF,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,gBAAgB,qBAAqB;IACrC,iBAAiB,sBAAsB;IACvC,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,gBAAgB,qBAAqB;CACtC;AAED,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,IAAI,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtF;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,gBAAgB,CAAC;IAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,GACrG;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,iBAAiB,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GACvG;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,OAAO,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,QAAQ,CAAC;IAAC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvH;IAAE,QAAQ,CAAC,IAAI,EAAE,4BAA4B,CAAC,gBAAgB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG,mGAAmG;AACnG,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACzD;AAED;;;;;;GAMG;AACH,oBAAY,oDAAoD;IAC9D,SAAS,cAAc;IACvB,WAAW,gBAAgB;CAC5B;AAoED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GAAG,qBAAqB,CAyH5G;AAED,yGAAyG;AACzG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,wBAAwB,GAAG,MAAM,CAKzI;AAwCD;;;;GAIG;AACH,wBAAgB,uDAAuD,CACrE,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,0CAA0C,GACjD,oDAAoD,CAMtD;AAED;;;;;;;GAOG;AACH,wBAAgB,6CAA6C,CAC3D,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,0CAA0C,GACjD,MAAM,CAGR"}

package/dist/esm/openapi/api-reference-link-index.js

@@ -0,0 +1,301 @@
+/**
+ * Semantic links into the generated API reference.
+ *
+ * This module projects a canonical OpenAPI document into a small index of
+ * public paths. It does not describe or navigate API contracts itself: every
+ * entry is derived from standard OpenAPI fields plus the strict `x-wildo`
+ * source identities already present in the document. Guide generation can use
+ * the index to link to exact API targets without hard-coding Docusaurus URLs
+ * or duplicating operations, request DTOs, responses, or schemas.
+ */
+import { OpenApiSection } from './openapi-generation-output.schemas.js';
+import { TechnicalDocumentationApiReferenceSection, TechnicalDocumentationApiReferenceTargetKind, } from '@wildo-ai/saas-specifications/technical-documentation';
+import { ApiReferenceTargetKind, ApplicationConsumerDocumentationRoute, applicationConsumerDocumentationTargetPath, } from './api-reference-targets.js';
+/** The semantic source identity a guide may resolve to a consumer API URL. */
+export var ApiReferenceLinkIdentityKind;
+(function (ApiReferenceLinkIdentityKind) {
+    /** A generated section exists and its root page is a valid public destination. */
+    ApiReferenceLinkIdentityKind["ROOT"] = "ROOT";
+    ApiReferenceLinkIdentityKind["CATEGORY"] = "CATEGORY";
+    ApiReferenceLinkIdentityKind["RESOURCE"] = "RESOURCE";
+    ApiReferenceLinkIdentityKind["OPERATION_FAMILY"] = "OPERATION_FAMILY";
+    ApiReferenceLinkIdentityKind["OPERATION_VARIANT"] = "OPERATION_VARIANT";
+    ApiReferenceLinkIdentityKind["REQUEST"] = "REQUEST";
+    ApiReferenceLinkIdentityKind["RESPONSE"] = "RESPONSE";
+    ApiReferenceLinkIdentityKind["COMPONENT_SCHEMA"] = "COMPONENT_SCHEMA";
+})(ApiReferenceLinkIdentityKind || (ApiReferenceLinkIdentityKind = {}));
+/**
+ * Result of asking whether one semantic guide target exists in the exact
+ * generated OpenAPI index. This is deliberately not a boolean: the named
+ * vocabulary keeps availability decisions readable at guide-composition call
+ * sites and leaves room for future source-owned states without overloading
+ * `false`.
+ */
+export var TechnicalDocumentationApiReferenceTargetAvailability;
+(function (TechnicalDocumentationApiReferenceTargetAvailability) {
+    TechnicalDocumentationApiReferenceTargetAvailability["AVAILABLE"] = "AVAILABLE";
+    TechnicalDocumentationApiReferenceTargetAvailability["UNAVAILABLE"] = "UNAVAILABLE";
+})(TechnicalDocumentationApiReferenceTargetAvailability || (TechnicalDocumentationApiReferenceTargetAvailability = {}));
+const OPENAPI_HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function routeForSection(section) {
+    switch (section) {
+        case OpenApiSection.API_REFERENCE:
+            return ApplicationConsumerDocumentationRoute.API_REFERENCE;
+        case OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE:
+            return ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE;
+        default: {
+            const exhaustiveSection = section;
+            throw new Error(`Unsupported API-reference section: ${String(exhaustiveSection)}`);
+        }
+    }
+}
+function resourceName(resourceRef) {
+    const name = resourceRef.match(/^technical-documentation:resource\/([^/]+)$/)?.[1];
+    if (name === undefined)
+        throw new Error(`API-reference resource identity is not a canonical resource ref: '${resourceRef}'`);
+    return name;
+}
+function familyName(operationFamilyRef) {
+    const name = operationFamilyRef.match(/^technical-documentation:resource\/[^/]+\/operation-family\/([^/]+)$/)?.[1];
+    if (name === undefined)
+        throw new Error(`API-reference family identity is not canonical: '${operationFamilyRef}'`);
+    return name;
+}
+function targetHref(section, target) {
+    return applicationConsumerDocumentationTargetPath(routeForSection(section), target);
+}
+/** The root is an index entry too: a guide may cite it only when that section was generated. */
+function sectionRootHref(section) {
+    return applicationConsumerDocumentationTargetPath(routeForSection(section));
+}
+function identityKey(section, identity) {
+    switch (identity.kind) {
+        case ApiReferenceLinkIdentityKind.ROOT:
+            return `${section}\0${identity.kind}`;
+        case ApiReferenceLinkIdentityKind.CATEGORY:
+            return `${section}\0${identity.kind}\0${identity.categoryId}`;
+        case ApiReferenceLinkIdentityKind.RESOURCE:
+            return `${section}\0${identity.kind}\0${identity.resourceRef}`;
+        case ApiReferenceLinkIdentityKind.OPERATION_FAMILY:
+            return `${section}\0${identity.kind}\0${identity.operationFamilyRef}`;
+        case ApiReferenceLinkIdentityKind.OPERATION_VARIANT:
+        case ApiReferenceLinkIdentityKind.REQUEST:
+            return `${section}\0${identity.kind}\0${identity.operationVariantRef}`;
+        case ApiReferenceLinkIdentityKind.RESPONSE:
+            return `${section}\0${identity.kind}\0${identity.operationVariantRef}\0${identity.status}`;
+        case ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA:
+            return `${section}\0${identity.kind}\0${identity.schemaName}`;
+        default: {
+            const exhaustiveIdentity = identity;
+            throw new Error(`Unsupported API-reference link identity: ${JSON.stringify(exhaustiveIdentity)}`);
+        }
+    }
+}
+/**
+ * Creates links from the exact generated OpenAPI documents.
+ *
+ * This is intentionally a fail-closed projection. An HTTP operation without
+ * the established source identity, a tag/operation resource mismatch, or a
+ * duplicate semantic target means guide links could become ambiguous, so the
+ * index is not emitted at all.
+ */
+export function createApiReferenceLinkIndex(sections) {
+    const entries = [];
+    const seen = new Set();
+    const sectionSet = new Set();
+    const identityByHref = new Map();
+    const add = (section, identity, href) => {
+        const key = identityKey(section, identity);
+        if (seen.has(key))
+            throw new Error(`API-reference link identity is duplicated: ${key}`);
+        const priorIdentity = identityByHref.get(href);
+        if (priorIdentity !== undefined && priorIdentity !== key) {
+            throw new Error(`API-reference public link '${href}' is ambiguous between ${priorIdentity} and ${key}`);
+        }
+        seen.add(key);
+        identityByHref.set(href, key);
+        entries.push({ section, identity, href });
+    };
+    for (const sectionOutput of sections) {
+        if (sectionSet.has(sectionOutput.section))
+            throw new Error(`API-reference section is duplicated: ${sectionOutput.section}`);
+        sectionSet.add(sectionOutput.section);
+        const document = sectionOutput.document;
+        if (!isRecord(document) || !isRecord(document.paths))
+            throw new Error(`API-reference ${sectionOutput.section} document has no OpenAPI paths object`);
+        add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.ROOT }, sectionRootHref(sectionOutput.section));
+        const tags = new Map();
+        const usedResourceRefs = new Set();
+        const categoryMetadataById = new Map();
+        if (!Array.isArray(document.tags))
+            throw new Error(`API-reference ${sectionOutput.section} document has no resource tags`);
+        for (const tag of document.tags) {
+            if (!isRecord(tag) || typeof tag.name !== 'string' || !isRecord(tag['x-wildo']) || typeof tag['x-wildo'].resourceRef !== 'string') {
+                throw new Error(`API-reference ${sectionOutput.section} document has a malformed resource tag`);
+            }
+            if (tags.has(tag.name))
+                throw new Error(`API-reference ${sectionOutput.section} resource tag is duplicated: '${tag.name}'`);
+            const category = tag['x-wildo'].category;
+            if (category !== undefined && (!isRecord(category) || typeof category.id !== 'string' || typeof category.label !== 'string'
+                || (category.description !== undefined && typeof category.description !== 'string'))) {
+                throw new Error(`API-reference resource tag '${tag.name}' has malformed category metadata`);
+            }
+            const categoryId = isRecord(category) && typeof category.id === 'string' ? category.id : null;
+            const categoryLabel = isRecord(category) && typeof category.label === 'string' ? category.label : null;
+            const categoryDescription = isRecord(category) && typeof category.description === 'string' ? category.description : null;
+            const tagResourceRef = tag['x-wildo'].resourceRef;
+            if (resourceName(tagResourceRef) !== tag.name)
+                throw new Error(`API-reference resource tag '${tag.name}' disagrees with its resource identity`);
+            tags.set(tag.name, { resourceRef: tagResourceRef });
+            add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.RESOURCE, resourceRef: tagResourceRef }, targetHref(sectionOutput.section, {
+                kind: ApiReferenceTargetKind.RESOURCE,
+                resourceName: tag.name,
+            }));
+            if (categoryId !== null) {
+                if (categoryLabel === null)
+                    throw new Error(`API-reference resource tag '${tag.name}' has malformed category metadata`);
+                const priorMetadata = categoryMetadataById.get(categoryId);
+                if (priorMetadata !== undefined && (priorMetadata.label !== categoryLabel || priorMetadata.description !== categoryDescription)) {
+                    throw new Error(`API-reference category '${categoryId}' has inconsistent source metadata`);
+                }
+                categoryMetadataById.set(categoryId, { label: categoryLabel, description: categoryDescription });
+                const categoryIdentity = { kind: ApiReferenceLinkIdentityKind.CATEGORY, categoryId };
+                const key = identityKey(sectionOutput.section, categoryIdentity);
+                if (!seen.has(key))
+                    add(sectionOutput.section, categoryIdentity, targetHref(sectionOutput.section, {
+                        kind: ApiReferenceTargetKind.CATEGORY,
+                        categoryName: categoryId,
+                    }));
+            }
+        }
+        for (const [path, pathItem] of Object.entries(document.paths)) {
+            if (!isRecord(pathItem))
+                continue;
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (!OPENAPI_HTTP_METHODS.has(method))
+                    continue;
+                if (!isRecord(operation) || !isRecord(operation['x-wildo']) || typeof operation.operationId !== 'string') {
+                    throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has malformed identity metadata`);
+                }
+                const metadata = operation['x-wildo'];
+                if (typeof metadata.resourceRef !== 'string' || typeof metadata.operationFamilyRef !== 'string' || typeof metadata.operationVariantRef !== 'string') {
+                    throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has incomplete identity metadata`);
+                }
+                if (metadata.path !== path || metadata.httpVerb !== method)
+                    throw new Error(`API-reference ${method.toUpperCase()} ${path} operation identity disagrees with its OpenAPI location`);
+                const tag = tags.get(resourceName(metadata.resourceRef));
+                if (tag === undefined || tag.resourceRef !== metadata.resourceRef)
+                    throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has no matching resource tag`);
+                usedResourceRefs.add(metadata.resourceRef);
+                const operationTarget = { kind: ApiReferenceTargetKind.OPERATION, operationId: operation.operationId };
+                const familyIdentity = { kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY, operationFamilyRef: metadata.operationFamilyRef };
+                if (!seen.has(identityKey(sectionOutput.section, familyIdentity))) {
+                    add(sectionOutput.section, familyIdentity, targetHref(sectionOutput.section, {
+                        kind: ApiReferenceTargetKind.OPERATION_FAMILY,
+                        resourceName: resourceName(metadata.resourceRef),
+                        operationName: familyName(metadata.operationFamilyRef),
+                    }));
+                }
+                add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT, operationVariantRef: metadata.operationVariantRef }, targetHref(sectionOutput.section, operationTarget));
+                if (isRecord(operation.requestBody)) {
+                    add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.REQUEST, operationVariantRef: metadata.operationVariantRef }, targetHref(sectionOutput.section, {
+                        kind: ApiReferenceTargetKind.REQUEST,
+                        operationId: operation.operationId,
+                    }));
+                }
+                if (isRecord(operation.responses)) {
+                    for (const status of Object.keys(operation.responses)) {
+                        add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.RESPONSE, operationVariantRef: metadata.operationVariantRef, status }, targetHref(sectionOutput.section, {
+                            kind: ApiReferenceTargetKind.RESPONSE,
+                            operationId: operation.operationId,
+                            status,
+                        }));
+                    }
+                }
+            }
+        }
+        for (const [tagName, tag] of tags) {
+            if (!usedResourceRefs.has(tag.resourceRef)) {
+                throw new Error(`API-reference resource tag '${tagName}' has no rendered HTTP operation`);
+            }
+        }
+        const componentSchemas = isRecord(document.components) && isRecord(document.components.schemas) ? document.components.schemas : {};
+        for (const schemaName of Object.keys(componentSchemas)) {
+            add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA, schemaName }, targetHref(sectionOutput.section, {
+                kind: ApiReferenceTargetKind.COMPONENT_SCHEMA,
+                schemaName,
+            }));
+        }
+    }
+    return { schemaVersion: 1, entries: entries.sort((left, right) => identityKey(left.section, left.identity).localeCompare(identityKey(right.section, right.identity))) };
+}
+/** Resolves one semantic API target and fails loudly when a guide asks for unavailable documentation. */
+export function resolveApiReferenceLink(index, section, identity) {
+    const expectedKey = identityKey(section, identity);
+    const entry = index.entries.find((candidate) => identityKey(candidate.section, candidate.identity) === expectedKey);
+    if (entry === undefined)
+        throw new Error(`API-reference link target is unavailable: ${expectedKey}`);
+    return entry.href;
+}
+function technicalDocumentationTargetIdentity(target) {
+    const section = target.section === TechnicalDocumentationApiReferenceSection.API_REFERENCE
+        ? OpenApiSection.API_REFERENCE
+        : OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE;
+    switch (target.kind) {
+        case TechnicalDocumentationApiReferenceTargetKind.ROOT:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.ROOT } };
+        case TechnicalDocumentationApiReferenceTargetKind.CATEGORY:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.CATEGORY, categoryId: target.categoryId } };
+        case TechnicalDocumentationApiReferenceTargetKind.RESOURCE:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.RESOURCE, resourceRef: target.resourceRef } };
+        case TechnicalDocumentationApiReferenceTargetKind.OPERATION_FAMILY:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY, operationFamilyRef: target.operationFamilyRef } };
+        case TechnicalDocumentationApiReferenceTargetKind.OPERATION_VARIANT:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT, operationVariantRef: target.operationVariantRef } };
+        case TechnicalDocumentationApiReferenceTargetKind.REQUEST:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.REQUEST, operationVariantRef: target.operationVariantRef } };
+        case TechnicalDocumentationApiReferenceTargetKind.RESPONSE:
+            return {
+                section,
+                identity: {
+                    kind: ApiReferenceLinkIdentityKind.RESPONSE,
+                    operationVariantRef: target.operationVariantRef,
+                    status: target.status,
+                },
+            };
+        case TechnicalDocumentationApiReferenceTargetKind.COMPONENT_SCHEMA:
+            return { section, identity: { kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA, schemaName: target.schemaName } };
+        default: {
+            const exhaustiveTarget = target;
+            throw new Error(`Unsupported technical-documentation API-reference target: ${JSON.stringify(exhaustiveTarget)}`);
+        }
+    }
+}
+/**
+ * Answers whether a typed target exists in the generated OpenAPI index without
+ * manufacturing a URL or turning normal optional-content selection into an
+ * exception path. Included guide links must still use the strict resolver.
+ */
+export function getTechnicalDocumentationApiReferenceTargetAvailability(index, target) {
+    const { section, identity } = technicalDocumentationTargetIdentity(target);
+    const expectedKey = identityKey(section, identity);
+    return index.entries.some((candidate) => identityKey(candidate.section, candidate.identity) === expectedKey)
+        ? TechnicalDocumentationApiReferenceTargetAvailability.AVAILABLE
+        : TechnicalDocumentationApiReferenceTargetAvailability.UNAVAILABLE;
+}
+/**
+ * Resolves a portable guide target through the generated OpenAPI index.
+ *
+ * The technical-documentation contract owns the semantic target because guide
+ * content cannot depend on the renderer package. This adapter is the only
+ * place that translates that portable target into the OpenAPI identities used
+ * to produce public consumer URLs.
+ */
+export function resolveTechnicalDocumentationApiReferenceLink(index, target) {
+    const { section, identity } = technicalDocumentationTargetIdentity(target);
+    return resolveApiReferenceLink(index, section, identity);
+}
+//# sourceMappingURL=api-reference-link-index.js.map

package/dist/esm/openapi/api-reference-link-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-reference-link-index.js","sourceRoot":"","sources":["../../../../src/openapi/api-reference-link-index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Semantic links into the generated API reference.\n *\n * This module projects a canonical OpenAPI document into a small index of\n * public paths. It does not describe or navigate API contracts itself: every\n * entry is derived from standard OpenAPI fields plus the strict `x-wildo`\n * source identities already present in the document. Guide generation can use\n * the index to link to exact API targets without hard-coding Docusaurus URLs\n * or duplicating operations, request DTOs, responses, or schemas.\n */\n\nimport { OpenApiSection, type OpenApiSectionOutput } from './openapi-generation-output.schemas';\nimport {\n  TechnicalDocumentationApiReferenceSection,\n  TechnicalDocumentationApiReferenceTargetKind,\n  type TechnicalDocumentationApiReferenceTargetV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\nimport {\n  ApiReferenceTargetKind,\n  ApplicationConsumerDocumentationRoute,\n  applicationConsumerDocumentationTargetPath,\n  type ApiReferencePublicTarget,\n} from './api-reference-targets';\n\n/** The semantic source identity a guide may resolve to a consumer API URL. */\nexport enum ApiReferenceLinkIdentityKind {\n  /** A generated section exists and its root page is a valid public destination. */\n  ROOT = 'ROOT',\n  CATEGORY = 'CATEGORY',\n  RESOURCE = 'RESOURCE',\n  OPERATION_FAMILY = 'OPERATION_FAMILY',\n  OPERATION_VARIANT = 'OPERATION_VARIANT',\n  REQUEST = 'REQUEST',\n  RESPONSE = 'RESPONSE',\n  COMPONENT_SCHEMA = 'COMPONENT_SCHEMA',\n}\n\nexport type ApiReferenceLinkIdentity =\n  | { readonly kind: ApiReferenceLinkIdentityKind.ROOT }\n  | { readonly kind: ApiReferenceLinkIdentityKind.CATEGORY; readonly categoryId: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.RESOURCE; readonly resourceRef: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY; readonly operationFamilyRef: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT; readonly operationVariantRef: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.REQUEST; readonly operationVariantRef: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.RESPONSE; readonly operationVariantRef: string; readonly status: string }\n  | { readonly kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA; readonly schemaName: string };\n\n/** One resolved public URL. `section` keeps an identity unambiguous across both API references. */\nexport interface ApiReferenceLinkIndexEntry {\n  readonly section: OpenApiSection;\n  readonly identity: ApiReferenceLinkIdentity;\n  readonly href: string;\n}\n\n/** JSON-safe result of projecting the selected OpenAPI documents. */\nexport interface ApiReferenceLinkIndex {\n  readonly schemaVersion: 1;\n  readonly entries: readonly ApiReferenceLinkIndexEntry[];\n}\n\n/**\n * Result of asking whether one semantic guide target exists in the exact\n * generated OpenAPI index. This is deliberately not a boolean: the named\n * vocabulary keeps availability decisions readable at guide-composition call\n * sites and leaves room for future source-owned states without overloading\n * `false`.\n */\nexport enum TechnicalDocumentationApiReferenceTargetAvailability {\n  AVAILABLE = 'AVAILABLE',\n  UNAVAILABLE = 'UNAVAILABLE',\n}\n\ntype UnknownRecord = Record<string, unknown>;\n\nconst OPENAPI_HTTP_METHODS: ReadonlySet<string> = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace']);\n\nfunction isRecord(value: unknown): value is UnknownRecord {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction routeForSection(section: OpenApiSection): ApplicationConsumerDocumentationRoute {\n  switch (section) {\n    case OpenApiSection.API_REFERENCE:\n      return ApplicationConsumerDocumentationRoute.API_REFERENCE;\n    case OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE:\n      return ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE;\n    default: {\n      const exhaustiveSection: never = section;\n      throw new Error(`Unsupported API-reference section: ${String(exhaustiveSection)}`);\n    }\n  }\n}\n\nfunction resourceName(resourceRef: string): string {\n  const name = resourceRef.match(/^technical-documentation:resource\\/([^/]+)$/)?.[1];\n  if (name === undefined) throw new Error(`API-reference resource identity is not a canonical resource ref: '${resourceRef}'`);\n  return name;\n}\n\nfunction familyName(operationFamilyRef: string): string {\n  const name = operationFamilyRef.match(/^technical-documentation:resource\\/[^/]+\\/operation-family\\/([^/]+)$/)?.[1];\n  if (name === undefined) throw new Error(`API-reference family identity is not canonical: '${operationFamilyRef}'`);\n  return name;\n}\n\nfunction targetHref(section: OpenApiSection, target: ApiReferencePublicTarget): string {\n  return applicationConsumerDocumentationTargetPath(routeForSection(section), target);\n}\n\n/** The root is an index entry too: a guide may cite it only when that section was generated. */\nfunction sectionRootHref(section: OpenApiSection): string {\n  return applicationConsumerDocumentationTargetPath(routeForSection(section));\n}\n\nfunction identityKey(section: OpenApiSection, identity: ApiReferenceLinkIdentity): string {\n  switch (identity.kind) {\n    case ApiReferenceLinkIdentityKind.ROOT:\n      return `${section}\\0${identity.kind}`;\n    case ApiReferenceLinkIdentityKind.CATEGORY:\n      return `${section}\\0${identity.kind}\\0${identity.categoryId}`;\n    case ApiReferenceLinkIdentityKind.RESOURCE:\n      return `${section}\\0${identity.kind}\\0${identity.resourceRef}`;\n    case ApiReferenceLinkIdentityKind.OPERATION_FAMILY:\n      return `${section}\\0${identity.kind}\\0${identity.operationFamilyRef}`;\n    case ApiReferenceLinkIdentityKind.OPERATION_VARIANT:\n    case ApiReferenceLinkIdentityKind.REQUEST:\n      return `${section}\\0${identity.kind}\\0${identity.operationVariantRef}`;\n    case ApiReferenceLinkIdentityKind.RESPONSE:\n      return `${section}\\0${identity.kind}\\0${identity.operationVariantRef}\\0${identity.status}`;\n    case ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA:\n      return `${section}\\0${identity.kind}\\0${identity.schemaName}`;\n    default: {\n      const exhaustiveIdentity: never = identity;\n      throw new Error(`Unsupported API-reference link identity: ${JSON.stringify(exhaustiveIdentity)}`);\n    }\n  }\n}\n\n/**\n * Creates links from the exact generated OpenAPI documents.\n *\n * This is intentionally a fail-closed projection. An HTTP operation without\n * the established source identity, a tag/operation resource mismatch, or a\n * duplicate semantic target means guide links could become ambiguous, so the\n * index is not emitted at all.\n */\nexport function createApiReferenceLinkIndex(sections: readonly OpenApiSectionOutput[]): ApiReferenceLinkIndex {\n  const entries: ApiReferenceLinkIndexEntry[] = [];\n  const seen = new Set<string>();\n  const sectionSet = new Set<OpenApiSection>();\n  const identityByHref = new Map<string, string>();\n  const add = (section: OpenApiSection, identity: ApiReferenceLinkIdentity, href: string): void => {\n    const key = identityKey(section, identity);\n    if (seen.has(key)) throw new Error(`API-reference link identity is duplicated: ${key}`);\n    const priorIdentity = identityByHref.get(href);\n    if (priorIdentity !== undefined && priorIdentity !== key) {\n      throw new Error(`API-reference public link '${href}' is ambiguous between ${priorIdentity} and ${key}`);\n    }\n    seen.add(key);\n    identityByHref.set(href, key);\n    entries.push({ section, identity, href });\n  };\n\n  for (const sectionOutput of sections) {\n    if (sectionSet.has(sectionOutput.section)) throw new Error(`API-reference section is duplicated: ${sectionOutput.section}`);\n    sectionSet.add(sectionOutput.section);\n    const document = sectionOutput.document;\n    if (!isRecord(document) || !isRecord(document.paths)) throw new Error(`API-reference ${sectionOutput.section} document has no OpenAPI paths object`);\n    add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.ROOT }, sectionRootHref(sectionOutput.section));\n    const tags = new Map<string, { resourceRef: string }>();\n    const usedResourceRefs = new Set<string>();\n    const categoryMetadataById = new Map<string, { label: string; description: string | null }>();\n    if (!Array.isArray(document.tags)) throw new Error(`API-reference ${sectionOutput.section} document has no resource tags`);\n    for (const tag of document.tags) {\n      if (!isRecord(tag) || typeof tag.name !== 'string' || !isRecord(tag['x-wildo']) || typeof tag['x-wildo'].resourceRef !== 'string') {\n        throw new Error(`API-reference ${sectionOutput.section} document has a malformed resource tag`);\n      }\n      if (tags.has(tag.name)) throw new Error(`API-reference ${sectionOutput.section} resource tag is duplicated: '${tag.name}'`);\n      const category = tag['x-wildo'].category;\n      if (category !== undefined && (!isRecord(category) || typeof category.id !== 'string' || typeof category.label !== 'string'\n        || (category.description !== undefined && typeof category.description !== 'string'))) {\n        throw new Error(`API-reference resource tag '${tag.name}' has malformed category metadata`);\n      }\n      const categoryId = isRecord(category) && typeof category.id === 'string' ? category.id : null;\n      const categoryLabel = isRecord(category) && typeof category.label === 'string' ? category.label : null;\n      const categoryDescription = isRecord(category) && typeof category.description === 'string' ? category.description : null;\n      const tagResourceRef = tag['x-wildo'].resourceRef;\n      if (resourceName(tagResourceRef) !== tag.name) throw new Error(`API-reference resource tag '${tag.name}' disagrees with its resource identity`);\n      tags.set(tag.name, { resourceRef: tagResourceRef });\n      add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.RESOURCE, resourceRef: tagResourceRef }, targetHref(sectionOutput.section, {\n        kind: ApiReferenceTargetKind.RESOURCE,\n        resourceName: tag.name,\n      }));\n      if (categoryId !== null) {\n        if (categoryLabel === null) throw new Error(`API-reference resource tag '${tag.name}' has malformed category metadata`);\n        const priorMetadata = categoryMetadataById.get(categoryId);\n        if (priorMetadata !== undefined && (priorMetadata.label !== categoryLabel || priorMetadata.description !== categoryDescription)) {\n          throw new Error(`API-reference category '${categoryId}' has inconsistent source metadata`);\n        }\n        categoryMetadataById.set(categoryId, { label: categoryLabel, description: categoryDescription });\n        const categoryIdentity = { kind: ApiReferenceLinkIdentityKind.CATEGORY, categoryId } as const;\n        const key = identityKey(sectionOutput.section, categoryIdentity);\n        if (!seen.has(key)) add(sectionOutput.section, categoryIdentity, targetHref(sectionOutput.section, {\n          kind: ApiReferenceTargetKind.CATEGORY,\n          categoryName: categoryId,\n        }));\n      }\n    }\n\n    for (const [path, pathItem] of Object.entries(document.paths)) {\n      if (!isRecord(pathItem)) continue;\n      for (const [method, operation] of Object.entries(pathItem)) {\n        if (!OPENAPI_HTTP_METHODS.has(method)) continue;\n        if (!isRecord(operation) || !isRecord(operation['x-wildo']) || typeof operation.operationId !== 'string') {\n          throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has malformed identity metadata`);\n        }\n        const metadata = operation['x-wildo'];\n        if (typeof metadata.resourceRef !== 'string' || typeof metadata.operationFamilyRef !== 'string' || typeof metadata.operationVariantRef !== 'string') {\n          throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has incomplete identity metadata`);\n        }\n        if (metadata.path !== path || metadata.httpVerb !== method) throw new Error(`API-reference ${method.toUpperCase()} ${path} operation identity disagrees with its OpenAPI location`);\n        const tag = tags.get(resourceName(metadata.resourceRef));\n        if (tag === undefined || tag.resourceRef !== metadata.resourceRef) throw new Error(`API-reference ${method.toUpperCase()} ${path} operation has no matching resource tag`);\n        usedResourceRefs.add(metadata.resourceRef);\n        const operationTarget = { kind: ApiReferenceTargetKind.OPERATION, operationId: operation.operationId } as const;\n        const familyIdentity = { kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY, operationFamilyRef: metadata.operationFamilyRef } as const;\n        if (!seen.has(identityKey(sectionOutput.section, familyIdentity))) {\n          add(sectionOutput.section, familyIdentity, targetHref(sectionOutput.section, {\n            kind: ApiReferenceTargetKind.OPERATION_FAMILY,\n            resourceName: resourceName(metadata.resourceRef),\n            operationName: familyName(metadata.operationFamilyRef),\n          }));\n        }\n        add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT, operationVariantRef: metadata.operationVariantRef }, targetHref(sectionOutput.section, operationTarget));\n        if (isRecord(operation.requestBody)) {\n          add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.REQUEST, operationVariantRef: metadata.operationVariantRef }, targetHref(sectionOutput.section, {\n            kind: ApiReferenceTargetKind.REQUEST,\n            operationId: operation.operationId,\n          }));\n        }\n        if (isRecord(operation.responses)) {\n          for (const status of Object.keys(operation.responses)) {\n            add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.RESPONSE, operationVariantRef: metadata.operationVariantRef, status }, targetHref(sectionOutput.section, {\n              kind: ApiReferenceTargetKind.RESPONSE,\n              operationId: operation.operationId,\n              status,\n            }));\n          }\n        }\n      }\n    }\n\n    for (const [tagName, tag] of tags) {\n      if (!usedResourceRefs.has(tag.resourceRef)) {\n        throw new Error(`API-reference resource tag '${tagName}' has no rendered HTTP operation`);\n      }\n    }\n\n    const componentSchemas = isRecord(document.components) && isRecord(document.components.schemas) ? document.components.schemas : {};\n    for (const schemaName of Object.keys(componentSchemas)) {\n      add(sectionOutput.section, { kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA, schemaName }, targetHref(sectionOutput.section, {\n        kind: ApiReferenceTargetKind.COMPONENT_SCHEMA,\n        schemaName,\n      }));\n    }\n  }\n  return { schemaVersion: 1, entries: entries.sort((left, right) => identityKey(left.section, left.identity).localeCompare(identityKey(right.section, right.identity))) };\n}\n\n/** Resolves one semantic API target and fails loudly when a guide asks for unavailable documentation. */\nexport function resolveApiReferenceLink(index: ApiReferenceLinkIndex, section: OpenApiSection, identity: ApiReferenceLinkIdentity): string {\n  const expectedKey = identityKey(section, identity);\n  const entry = index.entries.find((candidate) => identityKey(candidate.section, candidate.identity) === expectedKey);\n  if (entry === undefined) throw new Error(`API-reference link target is unavailable: ${expectedKey}`);\n  return entry.href;\n}\n\nfunction technicalDocumentationTargetIdentity(target: TechnicalDocumentationApiReferenceTargetV1): {\n  readonly section: OpenApiSection;\n  readonly identity: ApiReferenceLinkIdentity;\n} {\n  const section = target.section === TechnicalDocumentationApiReferenceSection.API_REFERENCE\n    ? OpenApiSection.API_REFERENCE\n    : OpenApiSection.APPLICATION_ADMINISTRATION_API_REFERENCE;\n  switch (target.kind) {\n    case TechnicalDocumentationApiReferenceTargetKind.ROOT:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.ROOT } };\n    case TechnicalDocumentationApiReferenceTargetKind.CATEGORY:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.CATEGORY, categoryId: target.categoryId } };\n    case TechnicalDocumentationApiReferenceTargetKind.RESOURCE:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.RESOURCE, resourceRef: target.resourceRef } };\n    case TechnicalDocumentationApiReferenceTargetKind.OPERATION_FAMILY:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.OPERATION_FAMILY, operationFamilyRef: target.operationFamilyRef } };\n    case TechnicalDocumentationApiReferenceTargetKind.OPERATION_VARIANT:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.OPERATION_VARIANT, operationVariantRef: target.operationVariantRef } };\n    case TechnicalDocumentationApiReferenceTargetKind.REQUEST:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.REQUEST, operationVariantRef: target.operationVariantRef } };\n    case TechnicalDocumentationApiReferenceTargetKind.RESPONSE:\n      return {\n        section,\n        identity: {\n          kind: ApiReferenceLinkIdentityKind.RESPONSE,\n          operationVariantRef: target.operationVariantRef,\n          status: target.status,\n        },\n      };\n    case TechnicalDocumentationApiReferenceTargetKind.COMPONENT_SCHEMA:\n      return { section, identity: { kind: ApiReferenceLinkIdentityKind.COMPONENT_SCHEMA, schemaName: target.schemaName } };\n    default: {\n      const exhaustiveTarget: never = target;\n      throw new Error(`Unsupported technical-documentation API-reference target: ${JSON.stringify(exhaustiveTarget)}`);\n    }\n  }\n}\n\n/**\n * Answers whether a typed target exists in the generated OpenAPI index without\n * manufacturing a URL or turning normal optional-content selection into an\n * exception path. Included guide links must still use the strict resolver.\n */\nexport function getTechnicalDocumentationApiReferenceTargetAvailability(\n  index: ApiReferenceLinkIndex,\n  target: TechnicalDocumentationApiReferenceTargetV1,\n): TechnicalDocumentationApiReferenceTargetAvailability {\n  const { section, identity } = technicalDocumentationTargetIdentity(target);\n  const expectedKey = identityKey(section, identity);\n  return index.entries.some((candidate) => identityKey(candidate.section, candidate.identity) === expectedKey)\n    ? TechnicalDocumentationApiReferenceTargetAvailability.AVAILABLE\n    : TechnicalDocumentationApiReferenceTargetAvailability.UNAVAILABLE;\n}\n\n/**\n * Resolves a portable guide target through the generated OpenAPI index.\n *\n * The technical-documentation contract owns the semantic target because guide\n * content cannot depend on the renderer package. This adapter is the only\n * place that translates that portable target into the OpenAPI identities used\n * to produce public consumer URLs.\n */\nexport function resolveTechnicalDocumentationApiReferenceLink(\n  index: ApiReferenceLinkIndex,\n  target: TechnicalDocumentationApiReferenceTargetV1,\n): string {\n  const { section, identity } = technicalDocumentationTargetIdentity(target);\n  return resolveApiReferenceLink(index, section, identity);\n}\n"]}