@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/companion/rendering/technical-documentation-managed-tree-validator.js

@@ -0,0 +1,204 @@
+import { TechnicalDocumentationOutputKind, TechnicalDocumentationRendererKind, TechnicalDocumentationRenderOutputManifestV1Schema, } from '@wildo-ai/saas-specifications/technical-documentation';
+import { technicalDocumentationSha256Bytes, } from './technical-documentation-render-model.js';
+import { ApplicationConsumerDocumentationRoute, applicationConsumerDocumentationRoutePath, } from '../../openapi/api-reference-targets.js';
+/**
+ * Ceilings applied when an application declares none.
+ *
+ * The point is that ABSENCE is bounded, not that these numbers are precisely right. An
+ * application which never thought about output size still gets a documentation tree that
+ * cannot silently grow until a build host runs out of memory; one that genuinely outgrows
+ * a ceiling raises it explicitly, and that edit is visible in review.
+ *
+ * Generous on purpose. A default tight enough to be "safe" for a small application would
+ * fire on ordinary growth, and a limit that routinely fires is a limit people learn to
+ * raise without reading — which is worse than no limit at all.
+ */
+export const TECHNICAL_DOCUMENTATION_DEFAULT_OUTPUT_BUDGETS = Object.freeze({
+    maximumPageCount: 2_000,
+    maximumTotalBytes: 512 * 1024 * 1024,
+    maximumSearchIndexBytes: 64 * 1024 * 1024,
+});
+/**
+ * Sentinels every application inherits, which an application can EXTEND but never remove.
+ *
+ * ## Why this set is so small
+ *
+ * A sentinel is matched with `String.includes` against every public file, so a generic
+ * marker — `secret`, `token`, `password`, `Bearer` — would fire on the very guides that
+ * teach authentication, error handling and webhook signature verification. Those documents
+ * legitimately contain those words. A canary that cries on correct content gets removed,
+ * and then it protects nothing.
+ *
+ * So the mandatory set is restricted to byte sequences that **cannot legitimately appear in
+ * published product documentation** under any authoring style. A PEM private-key header
+ * qualifies: documentation teaches readers to *use* a public key, never to read a private
+ * one, so its presence in a public tree is a leak by construction rather than by judgement.
+ *
+ * Application-specific canaries — a restricted-content marker, a fixture value that must
+ * stay internal — belong in the application's own declared list, which is UNIONED with this
+ * one. The union direction is the safety property: an application must be able to add
+ * canaries and must not be able to switch these off.
+ */
+export const TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS = Object.freeze([
+    '-----BEGIN OPENSSH PRIVATE KEY-----',
+    '-----BEGIN PGP PRIVATE KEY BLOCK-----',
+    '-----BEGIN PRIVATE KEY-----',
+    '-----BEGIN RSA PRIVATE KEY-----',
+]);
+/**
+ * Resolves the effective budgets from an application's partial declaration.
+ *
+ * Per-field rather than all-or-nothing: an application that only needs a larger page
+ * count should not have to restate — and thereby freeze a copy of — every other ceiling.
+ */
+export function resolveTechnicalDocumentationOutputBudgets(declared) {
+    return Object.freeze({ ...TECHNICAL_DOCUMENTATION_DEFAULT_OUTPUT_BUDGETS, ...(declared ?? {}) });
+}
+/**
+ * Unions the mandatory sentinels with an application's declared ones.
+ *
+ * A union, never a replacement — see
+ * {@link TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS}. Deduplicated and sorted so
+ * the resolved set is a stable value: it is compared and reported, and an order that
+ * varied with authoring order would make two identical policies look different.
+ */
+export function resolveTechnicalDocumentationForbiddenPublicSentinels(declared) {
+    const sentinels = new Set(TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS);
+    for (const sentinel of declared ?? []) {
+        const trimmed = sentinel.trim();
+        // An empty sentinel is skipped by the validator anyway; dropping it here keeps the
+        // resolved set honest about how many canaries are actually armed.
+        if (trimmed.length > 0)
+            sentinels.add(trimmed);
+    }
+    return Object.freeze([...sentinels].sort());
+}
+const GENERATED_MARKDOWN_LINK_PATTERN = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^)]*)?\)/g;
+/**
+ * Routes published by the API-reference pipeline rather than the guide renderer.
+ *
+ * API-reference links enter a guide only through the semantic OpenAPI link index,
+ * which proves the requested resource, operation, request, response or schema is
+ * present before the renderer receives its public URL. The managed-tree validator
+ * must therefore recognize the independently published route root while continuing
+ * to require every ordinary guide and static-asset target to exist in this exact
+ * render manifest.
+ */
+const INDEPENDENT_API_REFERENCE_ROUTES = new Set([
+    applicationConsumerDocumentationRoutePath(ApplicationConsumerDocumentationRoute.API_REFERENCE),
+    applicationConsumerDocumentationRoutePath(ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE),
+]);
+function validateGeneratedMarkdownLinkClosure(input) {
+    for (const match of input.text.matchAll(GENERATED_MARKDOWN_LINK_PATTERN)) {
+        const destination = match[1];
+        if (destination === undefined || destination.startsWith('#') || /^(?:https?:|mailto:)/i.test(destination))
+            continue;
+        const pathOnly = destination.split(/[?#]/, 1)[0];
+        if (pathOnly === undefined || pathOnly.length === 0)
+            continue;
+        if (pathOnly.startsWith('/')) {
+            const rootRelativePath = pathOnly.slice(1);
+            const docusaurusStaticPath = `docusaurus/static/${rootRelativePath}`;
+            if (input.docusaurusRoutes.has(pathOnly)
+                || (input.sourcePath.startsWith('docusaurus/docs/') ? input.declaredByPath.has(docusaurusStaticPath) : input.declaredByPath.has(rootRelativePath)))
+                continue;
+            throw new Error(`technical-documentation generated link target is absent: ${input.sourcePath} -> ${destination}`);
+        }
+        const resolvedPath = posixPath.normalize(posixPath.join(posixPath.dirname(input.sourcePath), pathOnly));
+        if (resolvedPath.startsWith('../') || posixPath.isAbsolute(resolvedPath) || !input.declaredByPath.has(resolvedPath)) {
+            throw new Error(`technical-documentation generated link target is absent: ${input.sourcePath} -> ${destination}`);
+        }
+    }
+}
+export function validateTechnicalDocumentationManagedTree(input) {
+    const manifest = TechnicalDocumentationRenderOutputManifestV1Schema.parse(input.manifest);
+    /*
+     * Binding is an identity comparison between two independently produced manifests, which is a
+     * check with two real sides. The `renderOutputDigest` recomputation that used to follow was not:
+     * it hashed this manifest and compared the result against the copy stored inside it.
+     */
+    const boundBundle = manifest.authorizedBundleIdentity;
+    if (boundBundle.ref !== input.authorizedBundle.bundleRef || boundBundle.version !== input.authorizedBundle.bundleVersion) {
+        throw new Error('technical-documentation render manifest does not bind the authorized bundle');
+    }
+    const boundAssets = manifest.resolvedAssetBundleIdentity;
+    if (boundAssets.ref !== input.resolvedAssetBundle.assetBundleRef || boundAssets.version !== input.resolvedAssetBundle.assetBundleVersion) {
+        throw new Error('technical-documentation render manifest does not bind the resolved asset bundle');
+    }
+    const declaredByPath = new Map(manifest.outputs.map((output) => [output.normalizedRelativePath, output]));
+    const docusaurusRoutes = new Set(manifest.outputs.flatMap((output) => {
+        const path = output.normalizedRelativePath;
+        return path.startsWith('docusaurus/docs/') && path.endsWith('.mdx')
+            ? [`/${path.slice('docusaurus/docs/'.length, -'.mdx'.length)}`]
+            : [];
+    }));
+    for (const apiReferenceRoute of INDEPENDENT_API_REFERENCE_ROUTES)
+        docusaurusRoutes.add(apiReferenceRoute);
+    const filesByPath = new Map();
+    for (const file of input.files) {
+        if (filesByPath.has(file.normalizedRelativePath))
+            throw new Error(`technical-documentation managed tree duplicates path: ${file.normalizedRelativePath}`);
+        filesByPath.set(file.normalizedRelativePath, file);
+    }
+    if (filesByPath.size !== declaredByPath.size)
+        throw new Error('technical-documentation managed tree inventory does not match its manifest');
+    const authorizedUnitRefs = new Set(input.authorizedBundle.units.map((unit) => unit.unitRef));
+    let totalBytes = 0;
+    let pageCount = 0;
+    let searchIndexBytes = 0;
+    for (const [path, output] of declaredByPath) {
+        const file = filesByPath.get(path);
+        if (file === undefined)
+            throw new Error(`technical-documentation managed output is missing: ${path}`);
+        if (file.outputRef !== output.outputRef || file.rendererRef !== output.rendererRef || file.outputKind !== output.outputKind
+            || file.mediaType !== output.mediaType || [...file.sourceUnitRefs].sort().join('\0') !== output.sourceUnitRefs.join('\0')) {
+            throw new Error(`technical-documentation managed output metadata mismatch: ${path}`);
+        }
+        if (file.bytes.byteLength !== output.byteLength || technicalDocumentationSha256Bytes(file.bytes) !== output.byteDigest) {
+            throw new Error(`technical-documentation managed output byte identity mismatch: ${path}`);
+        }
+        for (const sourceUnitRef of output.sourceUnitRefs) {
+            if (!authorizedUnitRefs.has(sourceUnitRef))
+                throw new Error(`technical-documentation output cites an unauthorized unit: ${sourceUnitRef}`);
+        }
+        const text = Buffer.from(file.bytes).toString('utf8');
+        for (const sentinel of input.forbiddenPublicSentinels) {
+            if (sentinel.length > 0 && text.includes(sentinel))
+                throw new Error(`technical-documentation managed public tree contains forbidden sentinel in ${path}`);
+        }
+        if (output.outputKind === TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT) {
+            validateGeneratedMarkdownLinkClosure({ sourcePath: path, text, declaredByPath, docusaurusRoutes });
+        }
+        totalBytes += file.bytes.byteLength;
+        if (output.outputKind === TechnicalDocumentationOutputKind.HTML_PAGE || output.outputKind === TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT)
+            pageCount += 1;
+        if (path === 'indexes/search.json')
+            searchIndexBytes = file.bytes.byteLength;
+    }
+    /**
+     * Captures are source material, not unconditional public output. An API-only
+     * publication deliberately has no page renderer that can reference a
+     * screenshot, so it must not publish unused product imagery. Once the
+     * Docusaurus content renderer participates, every resolved asset remains a
+     * required managed output as before.
+     */
+    if (manifest.rendererExecutions.some((execution) => execution.rendererKind === TechnicalDocumentationRendererKind.DOCUSAURUS)) {
+        const resolvedAssetPaths = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => asset.normalizedRelativePath === null ? [] : [asset.normalizedRelativePath]);
+        for (const path of resolvedAssetPaths) {
+            const output = declaredByPath.get(path);
+            if (output?.outputKind !== TechnicalDocumentationOutputKind.ASSET) {
+                throw new Error(`technical-documentation resolved asset is absent from the managed output tree: ${path}`);
+            }
+        }
+    }
+    const report = { pageCount, totalBytes, searchIndexBytes };
+    if (pageCount > input.budgets.maximumPageCount)
+        throw new Error(`technical-documentation page budget exceeded: ${pageCount}`);
+    if (totalBytes > input.budgets.maximumTotalBytes)
+        throw new Error(`technical-documentation total-byte budget exceeded: ${totalBytes}`);
+    if (searchIndexBytes > input.budgets.maximumSearchIndexBytes)
+        throw new Error(`technical-documentation search-index budget exceeded: ${searchIndexBytes}`);
+    return Object.freeze(report);
+}
+import { posix as posixPath } from 'node:path';
+//# sourceMappingURL=technical-documentation-managed-tree-validator.js.map

package/dist/esm/companion/rendering/technical-documentation-managed-tree-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-managed-tree-validator.js","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-managed-tree-validator.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  TechnicalDocumentationOutputKind,\n  TechnicalDocumentationRendererKind,\n  TechnicalDocumentationRenderOutputManifestV1Schema,\n  type TechnicalDocumentationAuthorizedBundleManifestV1,\n  type TechnicalDocumentationRenderOutputManifestV1,\n  type TechnicalDocumentationResolvedAssetBundleManifestV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\nimport {\n  technicalDocumentationSha256Bytes,\n  type TechnicalDocumentationRenderedFile,\n} from './technical-documentation-render-model';\nimport {\n  ApplicationConsumerDocumentationRoute,\n  applicationConsumerDocumentationRoutePath,\n} from '../../openapi/api-reference-targets';\n\nexport interface TechnicalDocumentationOutputBudgets {\n  readonly maximumPageCount: number;\n  readonly maximumTotalBytes: number;\n  readonly maximumSearchIndexBytes: number;\n}\n\n/**\n * Ceilings applied when an application declares none.\n *\n * The point is that ABSENCE is bounded, not that these numbers are precisely right. An\n * application which never thought about output size still gets a documentation tree that\n * cannot silently grow until a build host runs out of memory; one that genuinely outgrows\n * a ceiling raises it explicitly, and that edit is visible in review.\n *\n * Generous on purpose. A default tight enough to be \"safe\" for a small application would\n * fire on ordinary growth, and a limit that routinely fires is a limit people learn to\n * raise without reading — which is worse than no limit at all.\n */\nexport const TECHNICAL_DOCUMENTATION_DEFAULT_OUTPUT_BUDGETS: TechnicalDocumentationOutputBudgets = Object.freeze({\n  maximumPageCount: 2_000,\n  maximumTotalBytes: 512 * 1024 * 1024,\n  maximumSearchIndexBytes: 64 * 1024 * 1024,\n});\n\n/**\n * Sentinels every application inherits, which an application can EXTEND but never remove.\n *\n * ## Why this set is so small\n *\n * A sentinel is matched with `String.includes` against every public file, so a generic\n * marker — `secret`, `token`, `password`, `Bearer` — would fire on the very guides that\n * teach authentication, error handling and webhook signature verification. Those documents\n * legitimately contain those words. A canary that cries on correct content gets removed,\n * and then it protects nothing.\n *\n * So the mandatory set is restricted to byte sequences that **cannot legitimately appear in\n * published product documentation** under any authoring style. A PEM private-key header\n * qualifies: documentation teaches readers to *use* a public key, never to read a private\n * one, so its presence in a public tree is a leak by construction rather than by judgement.\n *\n * Application-specific canaries — a restricted-content marker, a fixture value that must\n * stay internal — belong in the application's own declared list, which is UNIONED with this\n * one. The union direction is the safety property: an application must be able to add\n * canaries and must not be able to switch these off.\n */\nexport const TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS: readonly string[] = Object.freeze([\n  '-----BEGIN OPENSSH PRIVATE KEY-----',\n  '-----BEGIN PGP PRIVATE KEY BLOCK-----',\n  '-----BEGIN PRIVATE KEY-----',\n  '-----BEGIN RSA PRIVATE KEY-----',\n]);\n\n/**\n * Resolves the effective budgets from an application's partial declaration.\n *\n * Per-field rather than all-or-nothing: an application that only needs a larger page\n * count should not have to restate — and thereby freeze a copy of — every other ceiling.\n */\nexport function resolveTechnicalDocumentationOutputBudgets(\n  declared?: Partial<TechnicalDocumentationOutputBudgets>,\n): TechnicalDocumentationOutputBudgets {\n  return Object.freeze({ ...TECHNICAL_DOCUMENTATION_DEFAULT_OUTPUT_BUDGETS, ...(declared ?? {}) });\n}\n\n/**\n * Unions the mandatory sentinels with an application's declared ones.\n *\n * A union, never a replacement — see\n * {@link TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS}. Deduplicated and sorted so\n * the resolved set is a stable value: it is compared and reported, and an order that\n * varied with authoring order would make two identical policies look different.\n */\nexport function resolveTechnicalDocumentationForbiddenPublicSentinels(\n  declared?: readonly string[],\n): readonly string[] {\n  const sentinels = new Set<string>(TECHNICAL_DOCUMENTATION_MANDATORY_PUBLIC_SENTINELS);\n  for (const sentinel of declared ?? []) {\n    const trimmed = sentinel.trim();\n    // An empty sentinel is skipped by the validator anyway; dropping it here keeps the\n    // resolved set honest about how many canaries are actually armed.\n    if (trimmed.length > 0) sentinels.add(trimmed);\n  }\n  return Object.freeze([...sentinels].sort());\n}\n\nexport interface TechnicalDocumentationManagedTreeValidationReport {\n  readonly pageCount: number;\n  readonly totalBytes: number;\n  readonly searchIndexBytes: number;\n}\n\nconst GENERATED_MARKDOWN_LINK_PATTERN = /!?\\[[^\\]]*\\]\\(([^)\\s]+)(?:\\s+[\"'][^)]*)?\\)/g;\n\n/**\n * Routes published by the API-reference pipeline rather than the guide renderer.\n *\n * API-reference links enter a guide only through the semantic OpenAPI link index,\n * which proves the requested resource, operation, request, response or schema is\n * present before the renderer receives its public URL. The managed-tree validator\n * must therefore recognize the independently published route root while continuing\n * to require every ordinary guide and static-asset target to exist in this exact\n * render manifest.\n */\nconst INDEPENDENT_API_REFERENCE_ROUTES: ReadonlySet<string> = new Set([\n  applicationConsumerDocumentationRoutePath(ApplicationConsumerDocumentationRoute.API_REFERENCE),\n  applicationConsumerDocumentationRoutePath(ApplicationConsumerDocumentationRoute.APPLICATION_ADMINISTRATION_API_REFERENCE),\n]);\n\nfunction validateGeneratedMarkdownLinkClosure(input: {\n  readonly sourcePath: string;\n  readonly text: string;\n  readonly declaredByPath: ReadonlyMap<string, TechnicalDocumentationRenderOutputManifestV1['outputs'][number]>;\n  readonly docusaurusRoutes: ReadonlySet<string>;\n}): void {\n  for (const match of input.text.matchAll(GENERATED_MARKDOWN_LINK_PATTERN)) {\n    const destination = match[1];\n    if (destination === undefined || destination.startsWith('#') || /^(?:https?:|mailto:)/i.test(destination)) continue;\n    const pathOnly = destination.split(/[?#]/, 1)[0];\n    if (pathOnly === undefined || pathOnly.length === 0) continue;\n    if (pathOnly.startsWith('/')) {\n      const rootRelativePath = pathOnly.slice(1);\n      const docusaurusStaticPath = `docusaurus/static/${rootRelativePath}`;\n      if (input.docusaurusRoutes.has(pathOnly)\n        || (input.sourcePath.startsWith('docusaurus/docs/') ? input.declaredByPath.has(docusaurusStaticPath) : input.declaredByPath.has(rootRelativePath))) continue;\n      throw new Error(`technical-documentation generated link target is absent: ${input.sourcePath} -> ${destination}`);\n    }\n    const resolvedPath = posixPath.normalize(posixPath.join(posixPath.dirname(input.sourcePath), pathOnly));\n    if (resolvedPath.startsWith('../') || posixPath.isAbsolute(resolvedPath) || !input.declaredByPath.has(resolvedPath)) {\n      throw new Error(`technical-documentation generated link target is absent: ${input.sourcePath} -> ${destination}`);\n    }\n  }\n}\n\nexport function validateTechnicalDocumentationManagedTree(input: {\n  readonly manifest: unknown;\n  readonly files: readonly TechnicalDocumentationRenderedFile[];\n  readonly authorizedBundle: TechnicalDocumentationAuthorizedBundleManifestV1;\n  readonly resolvedAssetBundle: TechnicalDocumentationResolvedAssetBundleManifestV1;\n  readonly forbiddenPublicSentinels: readonly string[];\n  readonly budgets: TechnicalDocumentationOutputBudgets;\n}): TechnicalDocumentationManagedTreeValidationReport {\n  const manifest: TechnicalDocumentationRenderOutputManifestV1 = TechnicalDocumentationRenderOutputManifestV1Schema.parse(input.manifest);\n  /*\n   * Binding is an identity comparison between two independently produced manifests, which is a\n   * check with two real sides. The `renderOutputDigest` recomputation that used to follow was not:\n   * it hashed this manifest and compared the result against the copy stored inside it.\n   */\n  const boundBundle = manifest.authorizedBundleIdentity;\n  if (boundBundle.ref !== input.authorizedBundle.bundleRef || boundBundle.version !== input.authorizedBundle.bundleVersion) {\n    throw new Error('technical-documentation render manifest does not bind the authorized bundle');\n  }\n  const boundAssets = manifest.resolvedAssetBundleIdentity;\n  if (boundAssets.ref !== input.resolvedAssetBundle.assetBundleRef || boundAssets.version !== input.resolvedAssetBundle.assetBundleVersion) {\n    throw new Error('technical-documentation render manifest does not bind the resolved asset bundle');\n  }\n\n  const declaredByPath = new Map(manifest.outputs.map((output) => [output.normalizedRelativePath, output]));\n  const docusaurusRoutes = new Set(manifest.outputs.flatMap((output) => {\n    const path = output.normalizedRelativePath as string;\n    return path.startsWith('docusaurus/docs/') && path.endsWith('.mdx')\n      ? [`/${path.slice('docusaurus/docs/'.length, -'.mdx'.length)}`]\n      : [];\n  }));\n  for (const apiReferenceRoute of INDEPENDENT_API_REFERENCE_ROUTES) docusaurusRoutes.add(apiReferenceRoute);\n  const filesByPath = new Map<string, TechnicalDocumentationRenderedFile>();\n  for (const file of input.files) {\n    if (filesByPath.has(file.normalizedRelativePath)) throw new Error(`technical-documentation managed tree duplicates path: ${file.normalizedRelativePath}`);\n    filesByPath.set(file.normalizedRelativePath, file);\n  }\n  if (filesByPath.size !== declaredByPath.size) throw new Error('technical-documentation managed tree inventory does not match its manifest');\n\n  const authorizedUnitRefs = new Set(input.authorizedBundle.units.map((unit) => unit.unitRef));\n  let totalBytes = 0;\n  let pageCount = 0;\n  let searchIndexBytes = 0;\n  for (const [path, output] of declaredByPath) {\n    const file = filesByPath.get(path);\n    if (file === undefined) throw new Error(`technical-documentation managed output is missing: ${path}`);\n    if (file.outputRef !== output.outputRef || file.rendererRef !== output.rendererRef || file.outputKind !== output.outputKind\n      || file.mediaType !== output.mediaType || [...file.sourceUnitRefs].sort().join('\\0') !== output.sourceUnitRefs.join('\\0')) {\n      throw new Error(`technical-documentation managed output metadata mismatch: ${path}`);\n    }\n    if (file.bytes.byteLength !== output.byteLength || technicalDocumentationSha256Bytes(file.bytes) !== output.byteDigest) {\n      throw new Error(`technical-documentation managed output byte identity mismatch: ${path}`);\n    }\n    for (const sourceUnitRef of output.sourceUnitRefs) {\n      if (!authorizedUnitRefs.has(sourceUnitRef)) throw new Error(`technical-documentation output cites an unauthorized unit: ${sourceUnitRef}`);\n    }\n    const text = Buffer.from(file.bytes).toString('utf8');\n    for (const sentinel of input.forbiddenPublicSentinels) {\n      if (sentinel.length > 0 && text.includes(sentinel)) throw new Error(`technical-documentation managed public tree contains forbidden sentinel in ${path}`);\n    }\n    if (output.outputKind === TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT) {\n      validateGeneratedMarkdownLinkClosure({ sourcePath: path, text, declaredByPath, docusaurusRoutes });\n    }\n    totalBytes += file.bytes.byteLength;\n    if (output.outputKind === TechnicalDocumentationOutputKind.HTML_PAGE || output.outputKind === TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT) pageCount += 1;\n    if (path === 'indexes/search.json') searchIndexBytes = file.bytes.byteLength;\n  }\n\n  /**\n   * Captures are source material, not unconditional public output. An API-only\n   * publication deliberately has no page renderer that can reference a\n   * screenshot, so it must not publish unused product imagery. Once the\n   * Docusaurus content renderer participates, every resolved asset remains a\n   * required managed output as before.\n   */\n  if (manifest.rendererExecutions.some((execution) => execution.rendererKind === TechnicalDocumentationRendererKind.DOCUSAURUS)) {\n    const resolvedAssetPaths = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => asset.normalizedRelativePath === null ? [] : [asset.normalizedRelativePath]);\n    for (const path of resolvedAssetPaths) {\n      const output = declaredByPath.get(path);\n      if (output?.outputKind !== TechnicalDocumentationOutputKind.ASSET) {\n        throw new Error(`technical-documentation resolved asset is absent from the managed output tree: ${path}`);\n      }\n    }\n  }\n  const report = { pageCount, totalBytes, searchIndexBytes };\n  if (pageCount > input.budgets.maximumPageCount) throw new Error(`technical-documentation page budget exceeded: ${pageCount}`);\n  if (totalBytes > input.budgets.maximumTotalBytes) throw new Error(`technical-documentation total-byte budget exceeded: ${totalBytes}`);\n  if (searchIndexBytes > input.budgets.maximumSearchIndexBytes) throw new Error(`technical-documentation search-index budget exceeded: ${searchIndexBytes}`);\n  return Object.freeze(report);\n}\nimport { posix as posixPath } from 'node:path';\n"]}

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.d.ts

@@ -0,0 +1,9 @@
+import { type TechnicalDocumentationApiReferenceTargetV1, type TechnicalDocumentationResolvedAssetBundleManifestV1 } from '@wildo-ai/saas-specifications/technical-documentation';
+import { type TechnicalDocumentationRenderModel, type TechnicalDocumentationRendererResult } from './technical-documentation-render-model';
+export declare function renderTechnicalDocumentationMarkdown(input: {
+    readonly model: TechnicalDocumentationRenderModel;
+    readonly resolvedAssetBundle: TechnicalDocumentationResolvedAssetBundleManifestV1;
+    readonly assetBytesByPath: ReadonlyMap<string, Uint8Array>;
+    readonly resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string;
+}): TechnicalDocumentationRendererResult;
+//# sourceMappingURL=technical-documentation-markdown-renderer.d.ts.map

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-markdown-renderer.d.ts","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-markdown-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,0CAA0C,EAC/C,KAAK,mDAAmD,EAEzD,MAAM,uDAAuD,CAAC;AAE/D,OAAO,EAEL,KAAK,iCAAiC,EACtC,KAAK,oCAAoC,EAC1C,MAAM,wCAAwC,CAAC;AA2DhD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE;IAC1D,QAAQ,CAAC,KAAK,EAAE,iCAAiC,CAAC;IAClD,QAAQ,CAAC,mBAAmB,EAAE,mDAAmD,CAAC;IAClF,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3D,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC,MAAM,EAAE,0CAA0C,KAAK,MAAM,CAAC;CACrG,GAAG,oCAAoC,CAkDvC"}

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.js

@@ -0,0 +1,106 @@
+import { TechnicalDocumentationAssetResolutionStatus, TechnicalDocumentationLinkKind, TechnicalDocumentationOutputKind, TechnicalDocumentationRendererKind, } from '@wildo-ai/saas-specifications/technical-documentation';
+import { createTechnicalDocumentationRendererExecution, } from './technical-documentation-render-model.js';
+import { technicalDocumentationAssetFileStem, } from '../technical-documentation-asset-path.js';
+/**
+ * Statuses whose asset carries real bytes at a real path, and therefore renders.
+ *
+ * `PLACEHOLDER` belongs here with `RESOLVED`: the framework materializes a stand-in image,
+ * so the page shows a picture rather than a hole. That is the whole distinction from
+ * `MISSING` — both mean "the real capture has not run", but only one of them SHIPS
+ * something. Rendering is a question about bytes; whether provisional imagery may be
+ * published at all is an environment policy decided at publication, not here.
+ */
+const RENDERABLE_ASSET_STATUSES = new Set([
+    TechnicalDocumentationAssetResolutionStatus.PLACEHOLDER,
+    TechnicalDocumentationAssetResolutionStatus.RESOLVED,
+]);
+const MARKDOWN_RENDERER_REF = 'technical-documentation:renderer/markdown';
+function relativeMarkdownPath(sourcePath, targetPath) {
+    const relativePath = path.relative(path.dirname(sourcePath), targetPath);
+    return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}
+function renderLink(link, model, sourcePath, resolveApiReferenceTarget) {
+    if (link.kind === TechnicalDocumentationLinkKind.UNIT) {
+        const targetPath = model.unitPathByRef.get(link.targetUnitRef);
+        if (targetPath === undefined)
+            throw new Error(`technical-documentation link target is not in the authorized render model: ${link.targetUnitRef}`);
+        return `- [${link.label}](${relativeMarkdownPath(sourcePath, `markdown/${targetPath}.md`)})`;
+    }
+    if (link.kind === TechnicalDocumentationLinkKind.EXTERNAL)
+        return `- [${link.label}](${link.externalUrl})`;
+    if (link.kind === TechnicalDocumentationLinkKind.API_REFERENCE) {
+        if (resolveApiReferenceTarget === undefined)
+            throw new Error(`technical-documentation API-reference link was not resolved before Markdown rendering: ${link.linkRef}`);
+        return `- [${link.label}](${resolveApiReferenceTarget(link.apiReferenceTarget)})`;
+    }
+    return `- ${link.label}`;
+}
+function renderUnit(unit, model, assetPathByRef, resolveApiReferenceTarget) {
+    const unitPath = model.unitPathByRef.get(unit.unitRef);
+    if (unitPath === undefined)
+        throw new Error(`technical-documentation render model has no path for ${unit.unitRef}`);
+    const sourcePath = `markdown/${unitPath}.md`;
+    const sections = unit.sections.map((section) => `## ${section.heading}\n\n${section.bodyMarkdown}`).join('\n\n');
+    const links = unit.links.length === 0 ? '' : `\n\n## Related\n\n${unit.links.map((link) => renderLink(link, model, sourcePath, resolveApiReferenceTarget)).join('\n')}`;
+    const figures = unit.assetRequests.flatMap((request) => {
+        const assetPath = assetPathByRef.get(request.assetRef);
+        return assetPath === undefined ? [] : [`![${request.altText}](${relativeMarkdownPath(sourcePath, assetPath)})`];
+    });
+    const assetSection = figures.length === 0 ? '' : `\n\n## Product view\n\n${figures.join('\n\n')}`;
+    return `# ${unit.title}\n\n${unit.summary}\n\n${sections}${assetSection}${links}\n`;
+}
+export function renderTechnicalDocumentationMarkdown(input) {
+    const assetPathByRef = new Map(input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => RENDERABLE_ASSET_STATUSES.has(asset.status) ? [[asset.assetRef, asset.normalizedRelativePath]] : []));
+    const sourceUnitRefsByAssetRef = new Map();
+    for (const unit of input.model.units) {
+        for (const request of unit.assetRequests) {
+            const owners = sourceUnitRefsByAssetRef.get(request.assetRef) ?? [];
+            owners.push(unit.unitRef);
+            sourceUnitRefsByAssetRef.set(request.assetRef, owners);
+        }
+    }
+    const assetFiles = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => {
+        if (!RENDERABLE_ASSET_STATUSES.has(asset.status))
+            return [];
+        const path = asset.normalizedRelativePath;
+        const bytes = input.assetBytesByPath.get(path);
+        if (bytes === undefined)
+            throw new Error(`technical-documentation Markdown asset bytes are absent: ${path}`);
+        const sourceUnitRefs = [...(sourceUnitRefsByAssetRef.get(asset.assetRef) ?? [])].sort();
+        if (sourceUnitRefs.length === 0)
+            throw new Error(`technical-documentation resolved asset has no authorized unit owner: ${asset.assetRef}`);
+        return [{
+                outputRef: `technical-documentation:output/markdown-asset/${technicalDocumentationAssetFileStem(asset.assetRef)}`,
+                rendererRef: MARKDOWN_RENDERER_REF,
+                outputKind: TechnicalDocumentationOutputKind.ASSET,
+                sourceUnitRefs,
+                normalizedRelativePath: path,
+                mediaType: asset.mediaType,
+                bytes,
+            }];
+    });
+    return {
+        execution: createTechnicalDocumentationRendererExecution({
+            rendererKind: TechnicalDocumentationRendererKind.MARKDOWN,
+            rendererRef: MARKDOWN_RENDERER_REF,
+            rendererVersion: 1,
+            configurationRef: 'technical-documentation:renderer-configuration/markdown-v1',
+        }),
+        files: [...input.model.units.map((unit) => {
+                const path = input.model.unitPathByRef.get(unit.unitRef);
+                return {
+                    // Keep the complete route identity: final path segments are not a
+                    // globally unique page identity once consumer documentation has domains.
+                    outputRef: `technical-documentation:output/markdown/${path.split('/').join(':')}`,
+                    rendererRef: MARKDOWN_RENDERER_REF,
+                    outputKind: TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT,
+                    sourceUnitRefs: [unit.unitRef],
+                    normalizedRelativePath: `markdown/${path}.md`,
+                    mediaType: 'text/markdown',
+                    bytes: Buffer.from(renderUnit(unit, input.model, assetPathByRef, input.resolveApiReferenceTarget), 'utf8'),
+                };
+            }), ...assetFiles],
+    };
+}
+import { posix as path } from 'node:path';
+//# sourceMappingURL=technical-documentation-markdown-renderer.js.map

package/dist/esm/companion/rendering/technical-documentation-markdown-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-markdown-renderer.js","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-markdown-renderer.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  TechnicalDocumentationAssetResolutionStatus,\n  TechnicalDocumentationLinkKind,\n  TechnicalDocumentationOutputKind,\n  TechnicalDocumentationRendererKind,\n  type TechnicalDocumentationLinkV1,\n  type TechnicalDocumentationApiReferenceTargetV1,\n  type TechnicalDocumentationResolvedAssetBundleManifestV1,\n  type TechnicalDocumentationUnitV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\nimport {\n  createTechnicalDocumentationRendererExecution,\n  type TechnicalDocumentationRenderModel,\n  type TechnicalDocumentationRendererResult,\n} from './technical-documentation-render-model';\nimport {\n  technicalDocumentationAssetFileStem,\n} from '../technical-documentation-asset-path';\n\n/**\n * Statuses whose asset carries real bytes at a real path, and therefore renders.\n *\n * `PLACEHOLDER` belongs here with `RESOLVED`: the framework materializes a stand-in image,\n * so the page shows a picture rather than a hole. That is the whole distinction from\n * `MISSING` — both mean \"the real capture has not run\", but only one of them SHIPS\n * something. Rendering is a question about bytes; whether provisional imagery may be\n * published at all is an environment policy decided at publication, not here.\n */\nconst RENDERABLE_ASSET_STATUSES: ReadonlySet<TechnicalDocumentationAssetResolutionStatus> = new Set([\n  TechnicalDocumentationAssetResolutionStatus.PLACEHOLDER,\n  TechnicalDocumentationAssetResolutionStatus.RESOLVED,\n]);\n\nconst MARKDOWN_RENDERER_REF = 'technical-documentation:renderer/markdown';\n\nfunction relativeMarkdownPath(sourcePath: string, targetPath: string): string {\n  const relativePath = path.relative(path.dirname(sourcePath), targetPath);\n  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;\n}\n\nfunction renderLink(link: TechnicalDocumentationLinkV1, model: TechnicalDocumentationRenderModel, sourcePath: string, resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string): string {\n  if (link.kind === TechnicalDocumentationLinkKind.UNIT) {\n    const targetPath = model.unitPathByRef.get(link.targetUnitRef as string);\n    if (targetPath === undefined) throw new Error(`technical-documentation link target is not in the authorized render model: ${link.targetUnitRef}`);\n    return `- [${link.label}](${relativeMarkdownPath(sourcePath, `markdown/${targetPath}.md`)})`;\n  }\n  if (link.kind === TechnicalDocumentationLinkKind.EXTERNAL) return `- [${link.label}](${link.externalUrl})`;\n  if (link.kind === TechnicalDocumentationLinkKind.API_REFERENCE) {\n    if (resolveApiReferenceTarget === undefined) throw new Error(`technical-documentation API-reference link was not resolved before Markdown rendering: ${link.linkRef}`);\n    return `- [${link.label}](${resolveApiReferenceTarget(link.apiReferenceTarget as TechnicalDocumentationApiReferenceTargetV1)})`;\n  }\n  return `- ${link.label}`;\n}\n\nfunction renderUnit(\n  unit: TechnicalDocumentationUnitV1,\n  model: TechnicalDocumentationRenderModel,\n  assetPathByRef: ReadonlyMap<string, string>,\n  resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string,\n): string {\n  const unitPath = model.unitPathByRef.get(unit.unitRef);\n  if (unitPath === undefined) throw new Error(`technical-documentation render model has no path for ${unit.unitRef}`);\n  const sourcePath = `markdown/${unitPath}.md`;\n  const sections = unit.sections.map((section) => `## ${section.heading}\\n\\n${section.bodyMarkdown}`).join('\\n\\n');\n  const links = unit.links.length === 0 ? '' : `\\n\\n## Related\\n\\n${unit.links.map((link) => renderLink(link, model, sourcePath, resolveApiReferenceTarget)).join('\\n')}`;\n  const figures = unit.assetRequests.flatMap((request) => {\n    const assetPath = assetPathByRef.get(request.assetRef);\n    return assetPath === undefined ? [] : [`![${request.altText}](${relativeMarkdownPath(sourcePath, assetPath)})`];\n  });\n  const assetSection = figures.length === 0 ? '' : `\\n\\n## Product view\\n\\n${figures.join('\\n\\n')}`;\n  return `# ${unit.title}\\n\\n${unit.summary}\\n\\n${sections}${assetSection}${links}\\n`;\n}\n\nexport function renderTechnicalDocumentationMarkdown(input: {\n  readonly model: TechnicalDocumentationRenderModel;\n  readonly resolvedAssetBundle: TechnicalDocumentationResolvedAssetBundleManifestV1;\n  readonly assetBytesByPath: ReadonlyMap<string, Uint8Array>;\n  readonly resolveApiReferenceTarget?: (target: TechnicalDocumentationApiReferenceTargetV1) => string;\n}): TechnicalDocumentationRendererResult {\n  const assetPathByRef = new Map(input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) =>\n    RENDERABLE_ASSET_STATUSES.has(asset.status) ? [[asset.assetRef, asset.normalizedRelativePath as string]] : []));\n  const sourceUnitRefsByAssetRef = new Map<string, string[]>();\n  for (const unit of input.model.units) {\n    for (const request of unit.assetRequests) {\n      const owners = sourceUnitRefsByAssetRef.get(request.assetRef) ?? [];\n      owners.push(unit.unitRef);\n      sourceUnitRefsByAssetRef.set(request.assetRef, owners);\n    }\n  }\n  const assetFiles = input.resolvedAssetBundle.resolvedAssetSet.assets.flatMap((asset) => {\n    if (!RENDERABLE_ASSET_STATUSES.has(asset.status)) return [];\n    const path = asset.normalizedRelativePath as string;\n    const bytes = input.assetBytesByPath.get(path);\n    if (bytes === undefined) throw new Error(`technical-documentation Markdown asset bytes are absent: ${path}`);\n    const sourceUnitRefs = [...(sourceUnitRefsByAssetRef.get(asset.assetRef) ?? [])].sort();\n    if (sourceUnitRefs.length === 0) throw new Error(`technical-documentation resolved asset has no authorized unit owner: ${asset.assetRef}`);\n    return [{\n      outputRef: `technical-documentation:output/markdown-asset/${technicalDocumentationAssetFileStem(asset.assetRef)}`,\n      rendererRef: MARKDOWN_RENDERER_REF,\n      outputKind: TechnicalDocumentationOutputKind.ASSET,\n      sourceUnitRefs,\n      normalizedRelativePath: path,\n      mediaType: asset.mediaType,\n      bytes,\n    }];\n  });\n  return {\n    execution: createTechnicalDocumentationRendererExecution({\n      rendererKind: TechnicalDocumentationRendererKind.MARKDOWN,\n      rendererRef: MARKDOWN_RENDERER_REF,\n      rendererVersion: 1,\n      configurationRef: 'technical-documentation:renderer-configuration/markdown-v1',\n    }),\n    files: [...input.model.units.map((unit) => {\n      const path = input.model.unitPathByRef.get(unit.unitRef) as string;\n      return {\n        // Keep the complete route identity: final path segments are not a\n        // globally unique page identity once consumer documentation has domains.\n        outputRef: `technical-documentation:output/markdown/${path.split('/').join(':')}`,\n        rendererRef: MARKDOWN_RENDERER_REF,\n        outputKind: TechnicalDocumentationOutputKind.MARKDOWN_DOCUMENT,\n        sourceUnitRefs: [unit.unitRef],\n        normalizedRelativePath: `markdown/${path}.md`,\n        mediaType: 'text/markdown',\n        bytes: Buffer.from(renderUnit(unit, input.model, assetPathByRef, input.resolveApiReferenceTarget), 'utf8'),\n      };\n    }), ...assetFiles],\n  };\n}\nimport { posix as path } from 'node:path';\n"]}

package/dist/esm/companion/rendering/technical-documentation-mdx-escaping.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Escapes MDX-significant syntax in prose that was authored as, or derived into, MARKDOWN.
+ *
+ * ## The defect this exists to prevent
+ *
+ * Docusaurus compiles `.mdx`, not `.md`. In MDX, `{` opens a JavaScript expression and `<`
+ * opens a JSX element. Both are ordinary literal characters in Markdown, so any producer
+ * that emits correct Markdown can emit invalid MDX without doing anything wrong.
+ *
+ * Documentation is full of exactly these characters, because route templates are:
+ *
+ * ```text
+ * **PUT /api/v1/organizations/{organizationId}/todos/{todoId}/assign**
+ * ```
+ *
+ * That line renders as a client-side crash — `ReferenceError: organizationId is not defined`
+ * — thrown from inside `<MDXContent>`, with the page replaced by "This page crashed." It is
+ * not a build failure: the MDX compiles, because `{organizationId}` is a syntactically valid
+ * expression. It fails at RENDER, in the reader's browser, which is the worst place to find it.
+ *
+ * ## Why escaping happens here rather than at the producer
+ *
+ * The producers are content authors and the derivation service, and neither of them should
+ * need to know which renderer their prose eventually reaches. The Markdown renderer next door
+ * emits `.md` and must NOT escape — a `\{` there is a literal backslash on the page. So the
+ * obligation belongs to the renderer that chose MDX, and to no one else.
+ *
+ * ## Why it is fence-aware
+ *
+ * MDX does not parse expressions inside code spans or fenced blocks, so escaping there would
+ * be visible corruption — a curl example would render a stray backslash. Code is also where
+ * these characters are MOST common, which is why a naive global replace looks like it works
+ * (the crash stops) while quietly damaging every example on the page.
+ */
+/**
+ * Returns `markdown` with MDX-significant characters escaped everywhere MDX would
+ * interpret them, and untouched inside fenced blocks and inline code spans.
+ *
+ * Markdown structure is preserved exactly: headings, emphasis, lists, links and tables
+ * use none of the characters this touches.
+ */
+export declare function escapeMarkdownForMdx(markdown: string): string;
+//# sourceMappingURL=technical-documentation-mdx-escaping.d.ts.map

package/dist/esm/companion/rendering/technical-documentation-mdx-escaping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-mdx-escaping.d.ts","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-mdx-escaping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAyCH;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAY7D"}

package/dist/esm/companion/rendering/technical-documentation-mdx-escaping.js

@@ -0,0 +1,88 @@
+/**
+ * Escapes MDX-significant syntax in prose that was authored as, or derived into, MARKDOWN.
+ *
+ * ## The defect this exists to prevent
+ *
+ * Docusaurus compiles `.mdx`, not `.md`. In MDX, `{` opens a JavaScript expression and `<`
+ * opens a JSX element. Both are ordinary literal characters in Markdown, so any producer
+ * that emits correct Markdown can emit invalid MDX without doing anything wrong.
+ *
+ * Documentation is full of exactly these characters, because route templates are:
+ *
+ * ```text
+ * **PUT /api/v1/organizations/{organizationId}/todos/{todoId}/assign**
+ * ```
+ *
+ * That line renders as a client-side crash — `ReferenceError: organizationId is not defined`
+ * — thrown from inside `<MDXContent>`, with the page replaced by "This page crashed." It is
+ * not a build failure: the MDX compiles, because `{organizationId}` is a syntactically valid
+ * expression. It fails at RENDER, in the reader's browser, which is the worst place to find it.
+ *
+ * ## Why escaping happens here rather than at the producer
+ *
+ * The producers are content authors and the derivation service, and neither of them should
+ * need to know which renderer their prose eventually reaches. The Markdown renderer next door
+ * emits `.md` and must NOT escape — a `\{` there is a literal backslash on the page. So the
+ * obligation belongs to the renderer that chose MDX, and to no one else.
+ *
+ * ## Why it is fence-aware
+ *
+ * MDX does not parse expressions inside code spans or fenced blocks, so escaping there would
+ * be visible corruption — a curl example would render a stray backslash. Code is also where
+ * these characters are MOST common, which is why a naive global replace looks like it works
+ * (the crash stops) while quietly damaging every example on the page.
+ */
+/** Opens or closes a fenced code block: ``` or ~~~, optionally indented, with any info string. */
+const FENCE_LINE = /^\s{0,3}(`{3,}|~{3,})/;
+/** One inline code span: a backtick run, the shortest content, then a matching run. */
+const INLINE_CODE_SPAN = /(`+)([\s\S]*?)\1/g;
+/**
+ * A `<` that MDX would read as the start of a JSX element — followed by a name or a
+ * closing slash. A `<` used as "less than" (`a < b`, `<= 3`) is left alone, because
+ * escaping it would put a visible entity into ordinary prose.
+ */
+const JSX_LIKE_OPEN = /<(?=[A-Za-z/])/g;
+/**
+ * A `{` that is not already escaped.
+ *
+ * The lookbehind is what makes this function idempotent, and idempotence is not a
+ * theoretical nicety here: an author may reasonably write `\{` themselves, and a second
+ * escaping pass would turn it into `\\{` — which renders a VISIBLE backslash and leaves
+ * the expression evaluating anyway, i.e. strictly worse than doing nothing.
+ */
+const UNESCAPED_BRACE = /(?<!\\)\{/g;
+function escapeOutsideCode(text) {
+    return text.replace(UNESCAPED_BRACE, '\\{').replace(JSX_LIKE_OPEN, '&lt;');
+}
+function escapeLineOutsideInlineCode(line) {
+    let result = '';
+    let lastIndex = 0;
+    INLINE_CODE_SPAN.lastIndex = 0;
+    for (let match = INLINE_CODE_SPAN.exec(line); match !== null; match = INLINE_CODE_SPAN.exec(line)) {
+        result += escapeOutsideCode(line.slice(lastIndex, match.index));
+        result += match[0];
+        lastIndex = match.index + match[0].length;
+    }
+    return result + escapeOutsideCode(line.slice(lastIndex));
+}
+/**
+ * Returns `markdown` with MDX-significant characters escaped everywhere MDX would
+ * interpret them, and untouched inside fenced blocks and inline code spans.
+ *
+ * Markdown structure is preserved exactly: headings, emphasis, lists, links and tables
+ * use none of the characters this touches.
+ */
+export function escapeMarkdownForMdx(markdown) {
+    let insideFence = false;
+    return markdown
+        .split('\n')
+        .map((line) => {
+        if (FENCE_LINE.test(line)) {
+            insideFence = !insideFence;
+            return line;
+        }
+        return insideFence ? line : escapeLineOutsideInlineCode(line);
+    })
+        .join('\n');
+}
+//# sourceMappingURL=technical-documentation-mdx-escaping.js.map

package/dist/esm/companion/rendering/technical-documentation-mdx-escaping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-mdx-escaping.js","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-mdx-escaping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,kGAAkG;AAClG,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAE3C,uFAAuF;AACvF,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,YAAY,CAAC;AAErC,SAAS,iBAAiB,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,2BAA2B,CAAC,IAAY;IAC/C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,gBAAgB,CAAC,SAAS,GAAG,CAAC,CAAC;IAC/B,KAAK,IAAI,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,KAAK,IAAI,EAAE,KAAK,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClG,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAChE,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;QACnB,SAAS,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAC5C,CAAC;IACD,OAAO,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,OAAO,QAAQ;SACZ,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,WAAW,GAAG,CAAC,WAAW,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,CAAC,CAAC;IAChE,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC","sourcesContent":["/**\n * Escapes MDX-significant syntax in prose that was authored as, or derived into, MARKDOWN.\n *\n * ## The defect this exists to prevent\n *\n * Docusaurus compiles `.mdx`, not `.md`. In MDX, `{` opens a JavaScript expression and `<`\n * opens a JSX element. Both are ordinary literal characters in Markdown, so any producer\n * that emits correct Markdown can emit invalid MDX without doing anything wrong.\n *\n * Documentation is full of exactly these characters, because route templates are:\n *\n * ```text\n * **PUT /api/v1/organizations/{organizationId}/todos/{todoId}/assign**\n * ```\n *\n * That line renders as a client-side crash — `ReferenceError: organizationId is not defined`\n * — thrown from inside `<MDXContent>`, with the page replaced by \"This page crashed.\" It is\n * not a build failure: the MDX compiles, because `{organizationId}` is a syntactically valid\n * expression. It fails at RENDER, in the reader's browser, which is the worst place to find it.\n *\n * ## Why escaping happens here rather than at the producer\n *\n * The producers are content authors and the derivation service, and neither of them should\n * need to know which renderer their prose eventually reaches. The Markdown renderer next door\n * emits `.md` and must NOT escape — a `\\{` there is a literal backslash on the page. So the\n * obligation belongs to the renderer that chose MDX, and to no one else.\n *\n * ## Why it is fence-aware\n *\n * MDX does not parse expressions inside code spans or fenced blocks, so escaping there would\n * be visible corruption — a curl example would render a stray backslash. Code is also where\n * these characters are MOST common, which is why a naive global replace looks like it works\n * (the crash stops) while quietly damaging every example on the page.\n */\n\n/** Opens or closes a fenced code block: ``` or ~~~, optionally indented, with any info string. */\nconst FENCE_LINE = /^\\s{0,3}(`{3,}|~{3,})/;\n\n/** One inline code span: a backtick run, the shortest content, then a matching run. */\nconst INLINE_CODE_SPAN = /(`+)([\\s\\S]*?)\\1/g;\n\n/**\n * A `<` that MDX would read as the start of a JSX element — followed by a name or a\n * closing slash. A `<` used as \"less than\" (`a < b`, `<= 3`) is left alone, because\n * escaping it would put a visible entity into ordinary prose.\n */\nconst JSX_LIKE_OPEN = /<(?=[A-Za-z/])/g;\n\n/**\n * A `{` that is not already escaped.\n *\n * The lookbehind is what makes this function idempotent, and idempotence is not a\n * theoretical nicety here: an author may reasonably write `\\{` themselves, and a second\n * escaping pass would turn it into `\\\\{` — which renders a VISIBLE backslash and leaves\n * the expression evaluating anyway, i.e. strictly worse than doing nothing.\n */\nconst UNESCAPED_BRACE = /(?<!\\\\)\\{/g;\n\nfunction escapeOutsideCode(text: string): string {\n  return text.replace(UNESCAPED_BRACE, '\\\\{').replace(JSX_LIKE_OPEN, '&lt;');\n}\n\nfunction escapeLineOutsideInlineCode(line: string): string {\n  let result = '';\n  let lastIndex = 0;\n  INLINE_CODE_SPAN.lastIndex = 0;\n  for (let match = INLINE_CODE_SPAN.exec(line); match !== null; match = INLINE_CODE_SPAN.exec(line)) {\n    result += escapeOutsideCode(line.slice(lastIndex, match.index));\n    result += match[0];\n    lastIndex = match.index + match[0].length;\n  }\n  return result + escapeOutsideCode(line.slice(lastIndex));\n}\n\n/**\n * Returns `markdown` with MDX-significant characters escaped everywhere MDX would\n * interpret them, and untouched inside fenced blocks and inline code spans.\n *\n * Markdown structure is preserved exactly: headings, emphasis, lists, links and tables\n * use none of the characters this touches.\n */\nexport function escapeMarkdownForMdx(markdown: string): string {\n  let insideFence = false;\n  return markdown\n    .split('\\n')\n    .map((line) => {\n      if (FENCE_LINE.test(line)) {\n        insideFence = !insideFence;\n        return line;\n      }\n      return insideFence ? line : escapeLineOutsideInlineCode(line);\n    })\n    .join('\\n');\n}\n"]}

package/dist/esm/companion/rendering/technical-documentation-openapi-renderer.d.ts

@@ -0,0 +1,7 @@
+import { type OpenApiGenerationOutput } from '../../openapi/openapi-generation-output.schemas';
+import { type TechnicalDocumentationRendererResult } from './technical-documentation-render-model';
+export declare function renderVerifiedTechnicalDocumentationOpenApi(input: {
+    readonly documents: OpenApiGenerationOutput;
+    readonly sourceUnitRefs: readonly string[];
+}): TechnicalDocumentationRendererResult;
+//# sourceMappingURL=technical-documentation-openapi-renderer.d.ts.map

package/dist/esm/companion/rendering/technical-documentation-openapi-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-openapi-renderer.d.ts","sourceRoot":"","sources":["../../../../../src/companion/rendering/technical-documentation-openapi-renderer.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAEL,KAAK,oCAAoC,EAC1C,MAAM,wCAAwC,CAAC;AAIhD,wBAAgB,2CAA2C,CAAC,KAAK,EAAE;IACjE,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,GAAG,oCAAoC,CA2CvC"}

package/dist/esm/companion/rendering/technical-documentation-openapi-renderer.js

@@ -0,0 +1,51 @@
+import { TechnicalDocumentationOutputKind, TechnicalDocumentationRendererKind } from '@wildo-ai/saas-specifications/technical-documentation';
+import { stringify as stringifyYaml } from 'yaml';
+import { OPENAPI_OUTPUT_FILENAMES, } from '../../openapi/openapi-generation-output.schemas.js';
+import { createTechnicalDocumentationRendererExecution, } from './technical-documentation-render-model.js';
+const OPENAPI_RENDERER_REF = 'technical-documentation:renderer/openapi';
+export function renderVerifiedTechnicalDocumentationOpenApi(input) {
+    if (input.sourceUnitRefs.length === 0)
+        throw new Error('technical-documentation OpenAPI rendering requires authorized source units');
+    return {
+        execution: createTechnicalDocumentationRendererExecution({
+            rendererKind: TechnicalDocumentationRendererKind.OPENAPI,
+            rendererRef: OPENAPI_RENDERER_REF,
+            rendererVersion: 1,
+            configurationRef: 'technical-documentation:renderer-configuration/openapi-3-1-0',
+        }),
+        files: input.documents.sections.flatMap((section) => {
+            const sectionPath = section.section.toLowerCase().replaceAll('_', '-');
+            const sourceUnitRefs = [...input.sourceUnitRefs].sort();
+            const filenames = OPENAPI_OUTPUT_FILENAMES[section.section];
+            const yaml = stringifyYaml(section.document, { lineWidth: 0, sortMapEntries: false });
+            const json = `${JSON.stringify(section.document, null, 2)}\n`;
+            /**
+             * YAML and JSON are two deterministic serializations of one generator
+             * document. YAML is the reviewable/downloadable contract; JSON is the
+             * browser renderer input. Neither file contains renderer-authored API
+             * meaning.
+             */
+            return [
+                {
+                    outputRef: `technical-documentation:output/openapi/${sectionPath}/yaml`,
+                    rendererRef: OPENAPI_RENDERER_REF,
+                    outputKind: TechnicalDocumentationOutputKind.OPENAPI_DOCUMENT,
+                    sourceUnitRefs,
+                    normalizedRelativePath: `openapi/${filenames.yaml}`,
+                    mediaType: 'application/yaml',
+                    bytes: Buffer.from(yaml, 'utf8'),
+                },
+                {
+                    outputRef: `technical-documentation:output/openapi/${sectionPath}/json`,
+                    rendererRef: OPENAPI_RENDERER_REF,
+                    outputKind: TechnicalDocumentationOutputKind.OPENAPI_DOCUMENT,
+                    sourceUnitRefs,
+                    normalizedRelativePath: `openapi/${filenames.json}`,
+                    mediaType: 'application/json',
+                    bytes: Buffer.from(json, 'utf8'),
+                },
+            ];
+        }),
+    };
+}
+//# sourceMappingURL=technical-documentation-openapi-renderer.js.map