@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/companion/spec-to-operation-doc.js

@@ -0,0 +1,326 @@
+/**
+ * @wildo-package @wildo-ai/saas-technical-doc/companion (spec → OpenAPI enrichment)
+ *
+ * Pure mappers from a resource SPECIFICATION's authored prose into OpenAPI:
+ *  - **Tier 1** `buildOperationDocFromSpec` — operation `purpose` / `outcome` /
+ *    `whenToUse` (with per-variant overrides) → operation `description` on an
+ *    `OperationProjection`. The `summary` (operation TITLE) is intentionally NOT
+ *    produced here: it is a short verb-first label the generator derives
+ *    (`buildDefaultSummary`), kept separate from the authored prose.
+ *  - **Tier 2** `injectFieldDocsIntoJsonSchema` — per-field `meaning` /
+ *    `whyItMatters` / `relationshipContext` / enum-value meanings → property
+ *    `description` + `x-enum-descriptions` on a request/response JSON-Schema
+ *    fragment.
+ *
+ * See `.claude/plans/technical-doc-openapi-spec-integration.md`. Without authored
+ * spec prose the description is empty and the operation falls back to the
+ * generator's humanized verb-first title alone (e.g. `"List users"`) with no
+ * field documentation — the "quality will be very poor" failure mode this
+ * integration removes.
+ *
+ * @wildo-boundary
+ *   Imports NOTHING — pure string composition. It deliberately declares its
+ *   own NARROW structural input types instead of importing
+ *   `ResourceOperationSpecification` / `ResourceOperationVariantSpecification`
+ *   from `@wildo-ai/saas-specifications`. Same K-3 boundary reasoning the rest
+ *   of `companion/` follows (see `operation-projection.schemas.ts`): pulling
+ *   the spec package would drag a heavy type graph into the decorator-free
+ *   technical-doc companion bundle. The types below MUST remain a structural
+ *   SUBSET of the authored spec types — only the prose fields this mapper
+ *   reads. If the spec layer renames a prose field, update these in lockstep.
+ */
+/** OperationProjection description cap: ≤2000 (Zod-enforced downstream). The
+ * summary (title) is derived by the generator, not built here. */
+const DESCRIPTION_MAX_LENGTH = 2000;
+/** Collapse all whitespace runs to single spaces and trim (single-line summary). */
+const toSingleLine = (value) => value.replace(/\s+/gu, ' ').trim();
+/** Clamp to `max` chars, appending an ellipsis when truncated. */
+const clampLength = (value, max) => value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;
+/**
+ * Strip implementation-only noise that authored spec prose carries for the
+ * FRAMEWORK-KNOWLEDGE audience but that means nothing to an API consumer
+ * reading the generated docs:
+ *  - Parentheticals naming a runtime variant — `(API_CALL in factory)`,
+ *    `(REPOSITORY_ONLY create in factory — …)`.
+ *  - Dangling `in factory` / `in the factory` phrases.
+ * Then normalise the leftover spacing/punctuation. Conservative by design — it
+ * only removes parentheticals that actually contain a variant marker, so
+ * ordinary parenthetical prose survives.
+ *
+ * This is the single canonical "spec prose → consumer prose" cleaner, applied
+ * to EVERY prose surface that reaches the OpenAPI output: the Tier-1 operation
+ * `description` (here), Tier-2 field descriptions + `x-enum-descriptions`
+ * (`composeFieldDescription` / `cleanEnumMeanings`), Tier-3 response/error/
+ * example/rate-limit prose (`asCleanProse`), and the resource `tags[].description`
+ * (applied by the generator — `openapi-generator.ts` imports this). Exported so
+ * those out-of-module surfaces clean prose identically rather than diverging.
+ */
+export const stripImplementationNoise = (value) => value
+    .replace(/\s*\([^()]*\b(?:API_CALL_WITH_CALLBACK|API_CALL|REPOSITORY_ONLY|INTERNAL_CALL|CRON_JOB|BATCH_JOB)\b[^()]*\)/gu, '')
+    .replace(/\s+in\s+(?:the\s+)?factory\b/giu, '')
+    .replace(/\(\s*\)/gu, '')
+    .replace(/\s+([.,;:])/gu, '$1')
+    .replace(/\s{2,}/gu, ' ')
+    .trim();
+/**
+ * Resolve the EFFECTIVE prose for an operation, applying variant overlay
+ * semantics: a present variant field REPLACES the base field; an absent
+ * variant field falls back to the base. `variantKey === undefined` resolves
+ * the reserved `'default'` variant.
+ *
+ * Returns `{}` when the spec is absent or carries no prose at all — callers
+ * leave `OperationProjection.summary` / `.description` unset so the
+ * generator's humanized fallback applies (graceful degradation for
+ * operations / resources with no authored spec).
+ */
+export const buildOperationDocFromSpec = (operationSpec, variantKey) => {
+    if (operationSpec === undefined) {
+        return {};
+    }
+    const variant = operationSpec.variants?.[variantKey ?? 'default'];
+    const effectivePurpose = variant?.purpose ?? operationSpec.purpose;
+    const effectiveOutcome = variant?.outcome ?? operationSpec.outcome;
+    const effectiveWhenToUse = variant?.whenToUse ?? operationSpec.whenToUse;
+    const doc = {};
+    // The OpenAPI `summary` (operation TITLE / nav label / breadcrumb) is
+    // intentionally NOT taken from `purpose`. `purpose` is impl-aware intent prose
+    // authored for the framework-knowledge layer — a full sentence, often with
+    // runtime detail like "(API_CALL in factory)" — which is far too long and too
+    // internal to be a title. The generator derives a short verb-first title
+    // (`buildDefaultSummary`); here we only build the DESCRIPTION from the authored
+    // prose. The description LEADS with `purpose` (the intent), then the observable
+    // `outcome`, then a "When to use" clause — each cleaned of implementation noise.
+    const descriptionParts = [];
+    if (effectivePurpose !== undefined) {
+        const purpose = stripImplementationNoise(toSingleLine(effectivePurpose));
+        if (purpose.length > 0)
+            descriptionParts.push(purpose);
+    }
+    if (effectiveOutcome !== undefined) {
+        const outcome = stripImplementationNoise(effectiveOutcome.trim());
+        if (outcome.length > 0)
+            descriptionParts.push(outcome);
+    }
+    if (effectiveWhenToUse !== undefined) {
+        const whenToUse = stripImplementationNoise(effectiveWhenToUse.trim());
+        if (whenToUse.length > 0)
+            descriptionParts.push(`**When to use:** ${whenToUse}`);
+    }
+    if (descriptionParts.length > 0) {
+        doc.description = clampLength(descriptionParts.join('\n\n'), DESCRIPTION_MAX_LENGTH);
+    }
+    return doc;
+};
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Clean an enum value→meaning record for consumer-facing output: strip
+ * implementation-only noise from each meaning (see `stripImplementationNoise`)
+ * and drop any entry that is non-string or empty after cleaning. Used for both
+ * the human-readable "Values:" legend and the machine `x-enum-descriptions`
+ * extension so the two never diverge.
+ */
+const cleanEnumMeanings = (enumValueMeanings) => {
+    const cleaned = {};
+    for (const [value, meaning] of Object.entries(enumValueMeanings)) {
+        if (typeof meaning !== 'string') {
+            continue;
+        }
+        const cleanedMeaning = stripImplementationNoise(meaning.trim());
+        if (cleanedMeaning.length > 0) {
+            cleaned[value] = cleanedMeaning;
+        }
+    }
+    return cleaned;
+};
+/**
+ * Compose a single property `description` from a field's authored docs:
+ * meaning + whyItMatters + relationshipContext as space-joined sentences,
+ * then an optional markdown "Values:" legend from enum meanings. Each authored
+ * sentence is run through `stripImplementationNoise` — the field-spec prose is
+ * authored for the framework-knowledge audience and may carry runtime markers
+ * (`(API_CALL in factory)`) that mean nothing to an API consumer. Returns
+ * `undefined` when the field carries no usable prose.
+ */
+const composeFieldDescription = (doc) => {
+    const sentences = [];
+    for (const candidate of [doc.meaning, doc.whyItMatters, doc.relationshipContext]) {
+        if (typeof candidate === 'string' && candidate.trim().length > 0) {
+            const cleaned = stripImplementationNoise(candidate.trim());
+            if (cleaned.length > 0) {
+                sentences.push(cleaned);
+            }
+        }
+    }
+    let description = sentences.join(' ');
+    if (doc.enumValueMeanings !== undefined) {
+        const legend = Object.entries(cleanEnumMeanings(doc.enumValueMeanings)).map(([value, meaning]) => `- \`${value}\`: ${meaning}`);
+        if (legend.length > 0) {
+            const block = `Values:\n${legend.join('\n')}`;
+            description = description.length > 0 ? `${description}\n\n${block}` : block;
+        }
+    }
+    return description.length > 0 ? description : undefined;
+};
+/**
+ * Enrich the TOP-LEVEL properties of an OpenAPI/JSON-Schema object fragment
+ * (a `requestBodySchema` / `responseBodySchema` produced by
+ * `convertZodSchemaToOpenApiSchema`) with authored field documentation.
+ * Mutates `fragment` in place.
+ *
+ * Rules:
+ *  - Property `description` is composed from the field's docs ONLY when the
+ *    property has no existing `description` — a Zod `.describe()` authored on
+ *    the DTO field wins (it is closer to the wire contract).
+ *  - `x-enum-descriptions` (value → meaning) is set whenever enum meanings
+ *    exist, independent of the description-clobber rule, for machine consumers.
+ *
+ * Only top-level properties are walked: the field-spec extractor produces
+ * specs for top-level schema fields only, so nested-object properties have no
+ * authored docs to apply. No-op for non-object fragments (`null`, scalars).
+ * Joins by EXACT property-name match — DTO property names that diverge from
+ * the resource's field names (renamed / computed / backend-stripped fields)
+ * are simply left undocumented rather than mis-documented.
+ */
+export const injectFieldDocsIntoJsonSchema = (fragment, fieldDocsByName) => {
+    if (!isPlainObject(fragment)) {
+        return;
+    }
+    const properties = fragment['properties'];
+    if (!isPlainObject(properties)) {
+        return;
+    }
+    for (const [propertyName, rawPropertySchema] of Object.entries(properties)) {
+        if (!isPlainObject(rawPropertySchema)) {
+            continue;
+        }
+        const doc = fieldDocsByName[propertyName];
+        if (doc === undefined) {
+            continue;
+        }
+        if (rawPropertySchema['description'] === undefined) {
+            const description = composeFieldDescription(doc);
+            if (description !== undefined) {
+                rawPropertySchema['description'] = description;
+            }
+        }
+        if (doc.enumValueMeanings !== undefined) {
+            const cleanedEnumMeanings = cleanEnumMeanings(doc.enumValueMeanings);
+            if (Object.keys(cleanedEnumMeanings).length > 0) {
+                rawPropertySchema['x-enum-descriptions'] = cleanedEnumMeanings;
+            }
+        }
+    }
+};
+const asNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+/**
+ * Like `asNonEmptyString`, but for PROSE fields surfaced verbatim to API
+ * consumers (response-status `meaning`, error-scenario `when`, example `title`,
+ * `rateLimitNote`): additionally strips implementation-only noise (see
+ * `stripImplementationNoise`) and returns `undefined` if the value is empty
+ * before OR after cleaning. Do NOT use for code-like fields (`code`,
+ * `errorCode`, `forStatus`) — those pass through untouched via `asNonEmptyString`.
+ */
+const asCleanProse = (value) => {
+    const raw = asNonEmptyString(value);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const cleaned = stripImplementationNoise(raw);
+    return cleaned.length > 0 ? cleaned : undefined;
+};
+/**
+ * Extract + normalize the Tier-3 HTTP-documentation fields from a raw authored
+ * operation spec into the projection shape. Variant examples are a complete
+ * overlay: when `variants.<key>.examples` is present it replaces the base
+ * operation examples, rather than merging a payload that may target a different
+ * response schema. Defensive: a malformed entry is dropped rather than
+ * poisoning the whole projection (the generator re-validates via Zod). Returns
+ * `{}` when the operation authored no HTTP docs.
+ *
+ * Prose fields (`meaning` / `when` / `title` / `rateLimitNote`) are cleaned of
+ * implementation-only noise via `asCleanProse`, consistent with the Tier-1
+ * `description` and Tier-2 field descriptions. `code` / `forStatus` /
+ * `errorCode` are `HttpResponseStatusCode` / error-code enum values whose
+ * runtime string value (`'200'`, …) is the OpenAPI `responses` key / a machine
+ * code, so they pass through untouched as strings.
+ */
+export const buildOperationHttpDocFromSpec = (operationSpec, variantKey) => {
+    if (!isPlainObject(operationSpec)) {
+        return {};
+    }
+    const doc = {};
+    const responseStatuses = operationSpec['responseStatuses'];
+    if (Array.isArray(responseStatuses)) {
+        const normalized = responseStatuses
+            .map((entry) => {
+            if (!isPlainObject(entry))
+                return undefined;
+            const code = asNonEmptyString(entry['code']);
+            const meaning = asCleanProse(entry['meaning']);
+            return code !== undefined && meaning !== undefined ? { code, meaning } : undefined;
+        })
+            .filter((entry) => entry !== undefined);
+        if (normalized.length > 0)
+            doc.responseStatuses = normalized;
+    }
+    const errorScenarios = operationSpec['errorScenarios'];
+    if (Array.isArray(errorScenarios)) {
+        const normalized = errorScenarios
+            .map((entry) => {
+            if (!isPlainObject(entry))
+                return undefined;
+            const code = asNonEmptyString(entry['code']);
+            const when = asCleanProse(entry['when']);
+            if (code === undefined || when === undefined)
+                return undefined;
+            const scenario = { code, when };
+            const errorCode = asNonEmptyString(entry['errorCode']);
+            if (errorCode !== undefined)
+                scenario.errorCode = errorCode;
+            return scenario;
+        })
+            .filter((entry) => entry !== undefined);
+        if (normalized.length > 0)
+            doc.errorScenarios = normalized;
+    }
+    if (typeof operationSpec['idempotent'] === 'boolean') {
+        doc.idempotent = operationSpec['idempotent'];
+    }
+    const rateLimitNote = asCleanProse(operationSpec['rateLimitNote']);
+    if (rateLimitNote !== undefined) {
+        doc.rateLimitNote = rateLimitNote;
+    }
+    const variants = operationSpec['variants'];
+    const variant = isPlainObject(variants) ? variants[variantKey ?? 'default'] : undefined;
+    // A present variant `examples` member deliberately suppresses the base even
+    // when it is malformed or empty: falling back would publish a payload under a
+    // schema the variant does not own. The normalizer below emits no example for
+    // that invalid/empty override, which is safer than a misleading one.
+    const examples = isPlainObject(variant) && Object.prototype.hasOwnProperty.call(variant, 'examples')
+        ? variant['examples']
+        : operationSpec['examples'];
+    if (Array.isArray(examples)) {
+        const normalized = examples
+            .map((entry) => {
+            if (!isPlainObject(entry))
+                return undefined;
+            const title = asCleanProse(entry['title']);
+            if (title === undefined)
+                return undefined;
+            const example = { title };
+            if (entry['request'] !== undefined)
+                example.request = entry['request'];
+            if (entry['response'] !== undefined)
+                example.response = entry['response'];
+            const forStatus = asNonEmptyString(entry['forStatus']);
+            if (forStatus !== undefined)
+                example.forStatus = forStatus;
+            return example;
+        })
+            .filter((entry) => entry !== undefined);
+        if (normalized.length > 0)
+            doc.examples = normalized;
+    }
+    return doc;
+};
+//# sourceMappingURL=spec-to-operation-doc.js.map

package/dist/esm/companion/spec-to-operation-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-to-operation-doc.js","sourceRoot":"","sources":["../../../../src/companion/spec-to-operation-doc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAiCH;kEACkE;AAClE,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,oFAAoF;AACpF,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAEnF,kEAAkE;AAClE,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,GAAW,EAAU,EAAE,CACzD,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,CAAC;AAExE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAa,EAAU,EAAE,CAChE,KAAK;KACF,OAAO,CACN,+GAA+G,EAC/G,EAAE,CACH;KACA,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC;KAC9C,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;KACxB,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC;KAC9B,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;KACxB,IAAI,EAAE,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,aAA6C,EAC7C,UAA8B,EAChB,EAAE;IAChB,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,EAAE,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC;IAClE,MAAM,gBAAgB,GAAG,OAAO,EAAE,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC;IACnE,MAAM,gBAAgB,GAAG,OAAO,EAAE,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC;IACnE,MAAM,kBAAkB,GAAG,OAAO,EAAE,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC;IAEzE,MAAM,GAAG,GAAiB,EAAE,CAAC;IAE7B,sEAAsE;IACtE,+EAA+E;IAC/E,2EAA2E;IAC3E,8EAA8E;IAC9E,yEAAyE;IACzE,gFAAgF;IAChF,gFAAgF;IAChF,iFAAiF;IACjF,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,wBAAwB,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,wBAAwB,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;QAClE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,wBAAwB,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,CAAC;QACtE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;YAAE,gBAAgB,CAAC,IAAI,CAAC,oBAAoB,SAAS,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAwBF,MAAM,aAAa,GAAG,CAAC,KAAc,EAAoC,EAAE,CACzE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEvE;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,CAAC,iBAAyC,EAA0B,EAAE;IAC9F,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACjE,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,SAAS;QACX,CAAC;QACD,MAAM,cAAc,GAAG,wBAAwB,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,OAAO,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,uBAAuB,GAAG,CAAC,GAAa,EAAsB,EAAE;IACpE,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACjF,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjE,MAAM,OAAO,GAAG,wBAAwB,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YAC3D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEtC,IAAI,GAAG,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CACzE,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,KAAK,OAAO,OAAO,EAAE,CACnD,CAAC;QACF,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,KAAK,GAAG,YAAY,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,WAAW,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,WAAW,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAC9E,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1D,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAC3C,QAAiB,EACjB,eAAyC,EACnC,EAAE;IACR,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO;IACT,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;IAC1C,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,KAAK,MAAM,CAAC,YAAY,EAAE,iBAAiB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3E,IAAI,CAAC,aAAa,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,SAAS;QACX,CAAC;QACD,IAAI,iBAAiB,CAAC,aAAa,CAAC,KAAK,SAAS,EAAE,CAAC;YACnD,MAAM,WAAW,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;YACjD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC9B,iBAAiB,CAAC,aAAa,CAAC,GAAG,WAAW,CAAC;YACjD,CAAC;QACH,CAAC;QACD,IAAI,GAAG,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YACrE,IAAI,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,iBAAiB,CAAC,qBAAqB,CAAC,GAAG,mBAAmB,CAAC;YACjE,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAmBF,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAsB,EAAE,CAC9D,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAElF;;;;;;;GAOG;AACH,MAAM,YAAY,GAAG,CAAC,KAAc,EAAsB,EAAE;IAC1D,MAAM,GAAG,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAC9C,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,aAAsB,EAAE,UAAmB,EAAoB,EAAE;IAC7G,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAqB,EAAE,CAAC;IAEjC,MAAM,gBAAgB,GAAG,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACpC,MAAM,UAAU,GAAG,gBAAgB;aAChC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC5C,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC/C,OAAO,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACrF,CAAC,CAAC;aACD,MAAM,CAAC,CAAC,KAAK,EAA8C,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;QACtF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,gBAAgB,GAAG,UAAU,CAAC;IAC/D,CAAC;IAED,MAAM,cAAc,GAAG,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,cAAc;aAC9B,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC5C,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YAC7C,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;YACzC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC/D,MAAM,QAAQ,GAAuD,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YACpF,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;YACvD,IAAI,SAAS,KAAK,SAAS;gBAAE,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC;YAC5D,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC;aACD,MAAM,CAAC,CAAC,KAAK,EAA+D,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC;QACvG,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,cAAc,GAAG,UAAU,CAAC;IAC7D,CAAC;IAED,IAAI,OAAO,aAAa,CAAC,YAAY,CAAC,KAAK,SAAS,EAAE,CAAC;QACrD,GAAG,CAAC,UAAU,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IACnE,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,GAAG,CAAC,aAAa,GAAG,aAAa,CAAC;IACpC,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACxF,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,QAAQ,GACZ,aAAa,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC;QACjF,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;QACrB,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,QAAQ;aACxB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACb,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC5C,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,MAAM,OAAO,GAAiF,EAAE,KAAK,EAAE,CAAC;YACxG,IAAI,KAAK,CAAC,SAAS,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;YACvE,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS;gBAAE,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;YAC1E,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;YACvD,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;YAC3D,OAAO,OAAO,CAAC;QACjB,CAAC,CAAC;aACD,MAAM,CACL,CAAC,KAAK,EAAyF,EAAE,CAC/F,KAAK,KAAK,SAAS,CACtB,CAAC;QACJ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC;IACvD,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC,CAAC","sourcesContent":["/**\n * @wildo-package @wildo-ai/saas-technical-doc/companion (spec → OpenAPI enrichment)\n *\n * Pure mappers from a resource SPECIFICATION's authored prose into OpenAPI:\n *  - **Tier 1** `buildOperationDocFromSpec` — operation `purpose` / `outcome` /\n *    `whenToUse` (with per-variant overrides) → operation `description` on an\n *    `OperationProjection`. The `summary` (operation TITLE) is intentionally NOT\n *    produced here: it is a short verb-first label the generator derives\n *    (`buildDefaultSummary`), kept separate from the authored prose.\n *  - **Tier 2** `injectFieldDocsIntoJsonSchema` — per-field `meaning` /\n *    `whyItMatters` / `relationshipContext` / enum-value meanings → property\n *    `description` + `x-enum-descriptions` on a request/response JSON-Schema\n *    fragment.\n *\n * See `.claude/plans/technical-doc-openapi-spec-integration.md`. Without authored\n * spec prose the description is empty and the operation falls back to the\n * generator's humanized verb-first title alone (e.g. `\"List users\"`) with no\n * field documentation — the \"quality will be very poor\" failure mode this\n * integration removes.\n *\n * @wildo-boundary\n *   Imports NOTHING — pure string composition. It deliberately declares its\n *   own NARROW structural input types instead of importing\n *   `ResourceOperationSpecification` / `ResourceOperationVariantSpecification`\n *   from `@wildo-ai/saas-specifications`. Same K-3 boundary reasoning the rest\n *   of `companion/` follows (see `operation-projection.schemas.ts`): pulling\n *   the spec package would drag a heavy type graph into the decorator-free\n *   technical-doc companion bundle. The types below MUST remain a structural\n *   SUBSET of the authored spec types — only the prose fields this mapper\n *   reads. If the spec layer renames a prose field, update these in lockstep.\n */\n\n/**\n * Narrow structural view of a per-variant operation spec — the prose fields\n * a variant may override. Subset of `ResourceOperationVariantSpecification`.\n */\nexport interface OperationSpecVariantProse {\n  purpose?: string;\n  outcome?: string;\n  whenToUse?: string;\n  /** Complete OpenAPI example replacement for this response-shape variant. */\n  examples?: Array<{ title: string; request?: unknown; response?: unknown; forStatus?: string }>;\n}\n\n/**\n * Narrow structural view of an operation spec — the base prose plus the\n * per-variant overrides map. Subset of `ResourceOperationSpecification`.\n * `variants` is keyed by the named variant key, with the reserved `'default'`\n * key for the no-`variantKey` (default-variant) path.\n */\nexport interface OperationSpecProse {\n  purpose?: string;\n  outcome?: string;\n  whenToUse?: string;\n  variants?: Record<string, OperationSpecVariantProse | undefined>;\n}\n\n/** The OpenAPI prose this mapper produces. Both fields optional. */\nexport interface OperationDoc {\n  summary?: string;\n  description?: string;\n}\n\n/** OperationProjection description cap: ≤2000 (Zod-enforced downstream). The\n * summary (title) is derived by the generator, not built here. */\nconst DESCRIPTION_MAX_LENGTH = 2000;\n\n/** Collapse all whitespace runs to single spaces and trim (single-line summary). */\nconst toSingleLine = (value: string): string => value.replace(/\\s+/gu, ' ').trim();\n\n/** Clamp to `max` chars, appending an ellipsis when truncated. */\nconst clampLength = (value: string, max: number): string =>\n  value.length <= max ? value : `${value.slice(0, max - 1).trimEnd()}…`;\n\n/**\n * Strip implementation-only noise that authored spec prose carries for the\n * FRAMEWORK-KNOWLEDGE audience but that means nothing to an API consumer\n * reading the generated docs:\n *  - Parentheticals naming a runtime variant — `(API_CALL in factory)`,\n *    `(REPOSITORY_ONLY create in factory — …)`.\n *  - Dangling `in factory` / `in the factory` phrases.\n * Then normalise the leftover spacing/punctuation. Conservative by design — it\n * only removes parentheticals that actually contain a variant marker, so\n * ordinary parenthetical prose survives.\n *\n * This is the single canonical \"spec prose → consumer prose\" cleaner, applied\n * to EVERY prose surface that reaches the OpenAPI output: the Tier-1 operation\n * `description` (here), Tier-2 field descriptions + `x-enum-descriptions`\n * (`composeFieldDescription` / `cleanEnumMeanings`), Tier-3 response/error/\n * example/rate-limit prose (`asCleanProse`), and the resource `tags[].description`\n * (applied by the generator — `openapi-generator.ts` imports this). Exported so\n * those out-of-module surfaces clean prose identically rather than diverging.\n */\nexport const stripImplementationNoise = (value: string): string =>\n  value\n    .replace(\n      /\\s*\\([^()]*\\b(?:API_CALL_WITH_CALLBACK|API_CALL|REPOSITORY_ONLY|INTERNAL_CALL|CRON_JOB|BATCH_JOB)\\b[^()]*\\)/gu,\n      '',\n    )\n    .replace(/\\s+in\\s+(?:the\\s+)?factory\\b/giu, '')\n    .replace(/\\(\\s*\\)/gu, '')\n    .replace(/\\s+([.,;:])/gu, '$1')\n    .replace(/\\s{2,}/gu, ' ')\n    .trim();\n\n/**\n * Resolve the EFFECTIVE prose for an operation, applying variant overlay\n * semantics: a present variant field REPLACES the base field; an absent\n * variant field falls back to the base. `variantKey === undefined` resolves\n * the reserved `'default'` variant.\n *\n * Returns `{}` when the spec is absent or carries no prose at all — callers\n * leave `OperationProjection.summary` / `.description` unset so the\n * generator's humanized fallback applies (graceful degradation for\n * operations / resources with no authored spec).\n */\nexport const buildOperationDocFromSpec = (\n  operationSpec: OperationSpecProse | undefined,\n  variantKey: string | undefined,\n): OperationDoc => {\n  if (operationSpec === undefined) {\n    return {};\n  }\n\n  const variant = operationSpec.variants?.[variantKey ?? 'default'];\n  const effectivePurpose = variant?.purpose ?? operationSpec.purpose;\n  const effectiveOutcome = variant?.outcome ?? operationSpec.outcome;\n  const effectiveWhenToUse = variant?.whenToUse ?? operationSpec.whenToUse;\n\n  const doc: OperationDoc = {};\n\n  // The OpenAPI `summary` (operation TITLE / nav label / breadcrumb) is\n  // intentionally NOT taken from `purpose`. `purpose` is impl-aware intent prose\n  // authored for the framework-knowledge layer — a full sentence, often with\n  // runtime detail like \"(API_CALL in factory)\" — which is far too long and too\n  // internal to be a title. The generator derives a short verb-first title\n  // (`buildDefaultSummary`); here we only build the DESCRIPTION from the authored\n  // prose. The description LEADS with `purpose` (the intent), then the observable\n  // `outcome`, then a \"When to use\" clause — each cleaned of implementation noise.\n  const descriptionParts: string[] = [];\n  if (effectivePurpose !== undefined) {\n    const purpose = stripImplementationNoise(toSingleLine(effectivePurpose));\n    if (purpose.length > 0) descriptionParts.push(purpose);\n  }\n  if (effectiveOutcome !== undefined) {\n    const outcome = stripImplementationNoise(effectiveOutcome.trim());\n    if (outcome.length > 0) descriptionParts.push(outcome);\n  }\n  if (effectiveWhenToUse !== undefined) {\n    const whenToUse = stripImplementationNoise(effectiveWhenToUse.trim());\n    if (whenToUse.length > 0) descriptionParts.push(`**When to use:** ${whenToUse}`);\n  }\n  if (descriptionParts.length > 0) {\n    doc.description = clampLength(descriptionParts.join('\\n\\n'), DESCRIPTION_MAX_LENGTH);\n  }\n\n  return doc;\n};\n\n// ---------------------------------------------------------------------------\n// Tier 2 — field / enum documentation\n// ---------------------------------------------------------------------------\n\n/**\n * Narrow structural view of one field's authored documentation. Built by the\n * companion projector from the extracted resource field specs and consumed by\n * `injectFieldDocsIntoJsonSchema`. Boundary-clean (no `@wildo-ai/saas-specifications`\n * import): the projector maps `ExtractedFieldSpec.params.{meaning,whyItMatters,\n * relationshipContext,values}` into this shape before calling the injector.\n */\nexport interface FieldDoc {\n  /** Business meaning of the field (becomes the lead of the property description). */\n  meaning?: string;\n  /** Why the field is included (appended to the description). */\n  whyItMatters?: string;\n  /** For foreign keys: the relationship this field expresses. */\n  relationshipContext?: string;\n  /** For enum fields: enum value string → authored meaning. */\n  enumValueMeanings?: Record<string, string>;\n}\n\nconst isPlainObject = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/**\n * Clean an enum value→meaning record for consumer-facing output: strip\n * implementation-only noise from each meaning (see `stripImplementationNoise`)\n * and drop any entry that is non-string or empty after cleaning. Used for both\n * the human-readable \"Values:\" legend and the machine `x-enum-descriptions`\n * extension so the two never diverge.\n */\nconst cleanEnumMeanings = (enumValueMeanings: Record<string, string>): Record<string, string> => {\n  const cleaned: Record<string, string> = {};\n  for (const [value, meaning] of Object.entries(enumValueMeanings)) {\n    if (typeof meaning !== 'string') {\n      continue;\n    }\n    const cleanedMeaning = stripImplementationNoise(meaning.trim());\n    if (cleanedMeaning.length > 0) {\n      cleaned[value] = cleanedMeaning;\n    }\n  }\n  return cleaned;\n};\n\n/**\n * Compose a single property `description` from a field's authored docs:\n * meaning + whyItMatters + relationshipContext as space-joined sentences,\n * then an optional markdown \"Values:\" legend from enum meanings. Each authored\n * sentence is run through `stripImplementationNoise` — the field-spec prose is\n * authored for the framework-knowledge audience and may carry runtime markers\n * (`(API_CALL in factory)`) that mean nothing to an API consumer. Returns\n * `undefined` when the field carries no usable prose.\n */\nconst composeFieldDescription = (doc: FieldDoc): string | undefined => {\n  const sentences: string[] = [];\n  for (const candidate of [doc.meaning, doc.whyItMatters, doc.relationshipContext]) {\n    if (typeof candidate === 'string' && candidate.trim().length > 0) {\n      const cleaned = stripImplementationNoise(candidate.trim());\n      if (cleaned.length > 0) {\n        sentences.push(cleaned);\n      }\n    }\n  }\n  let description = sentences.join(' ');\n\n  if (doc.enumValueMeanings !== undefined) {\n    const legend = Object.entries(cleanEnumMeanings(doc.enumValueMeanings)).map(\n      ([value, meaning]) => `- \\`${value}\\`: ${meaning}`,\n    );\n    if (legend.length > 0) {\n      const block = `Values:\\n${legend.join('\\n')}`;\n      description = description.length > 0 ? `${description}\\n\\n${block}` : block;\n    }\n  }\n\n  return description.length > 0 ? description : undefined;\n};\n\n/**\n * Enrich the TOP-LEVEL properties of an OpenAPI/JSON-Schema object fragment\n * (a `requestBodySchema` / `responseBodySchema` produced by\n * `convertZodSchemaToOpenApiSchema`) with authored field documentation.\n * Mutates `fragment` in place.\n *\n * Rules:\n *  - Property `description` is composed from the field's docs ONLY when the\n *    property has no existing `description` — a Zod `.describe()` authored on\n *    the DTO field wins (it is closer to the wire contract).\n *  - `x-enum-descriptions` (value → meaning) is set whenever enum meanings\n *    exist, independent of the description-clobber rule, for machine consumers.\n *\n * Only top-level properties are walked: the field-spec extractor produces\n * specs for top-level schema fields only, so nested-object properties have no\n * authored docs to apply. No-op for non-object fragments (`null`, scalars).\n * Joins by EXACT property-name match — DTO property names that diverge from\n * the resource's field names (renamed / computed / backend-stripped fields)\n * are simply left undocumented rather than mis-documented.\n */\nexport const injectFieldDocsIntoJsonSchema = (\n  fragment: unknown,\n  fieldDocsByName: Record<string, FieldDoc>,\n): void => {\n  if (!isPlainObject(fragment)) {\n    return;\n  }\n  const properties = fragment['properties'];\n  if (!isPlainObject(properties)) {\n    return;\n  }\n  for (const [propertyName, rawPropertySchema] of Object.entries(properties)) {\n    if (!isPlainObject(rawPropertySchema)) {\n      continue;\n    }\n    const doc = fieldDocsByName[propertyName];\n    if (doc === undefined) {\n      continue;\n    }\n    if (rawPropertySchema['description'] === undefined) {\n      const description = composeFieldDescription(doc);\n      if (description !== undefined) {\n        rawPropertySchema['description'] = description;\n      }\n    }\n    if (doc.enumValueMeanings !== undefined) {\n      const cleanedEnumMeanings = cleanEnumMeanings(doc.enumValueMeanings);\n      if (Object.keys(cleanedEnumMeanings).length > 0) {\n        rawPropertySchema['x-enum-descriptions'] = cleanedEnumMeanings;\n      }\n    }\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Tier 3 — operation HTTP documentation (response statuses / errors / examples)\n// ---------------------------------------------------------------------------\n\n/**\n * Projection-shaped HTTP documentation for one operation (Tier 3). Mirrors the\n * authored `ResourceOperationSpecification` HTTP fields, normalized to plain\n * JSON the OpenAPI generator emits as `responses` / `examples` / extensions.\n */\nexport interface OperationHttpDoc {\n  responseStatuses?: Array<{ code: string; meaning: string }>;\n  errorScenarios?: Array<{ code: string; when: string; errorCode?: string }>;\n  idempotent?: boolean;\n  rateLimitNote?: string;\n  examples?: Array<{ title: string; request?: unknown; response?: unknown; forStatus?: string }>;\n}\n\nconst asNonEmptyString = (value: unknown): string | undefined =>\n  typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;\n\n/**\n * Like `asNonEmptyString`, but for PROSE fields surfaced verbatim to API\n * consumers (response-status `meaning`, error-scenario `when`, example `title`,\n * `rateLimitNote`): additionally strips implementation-only noise (see\n * `stripImplementationNoise`) and returns `undefined` if the value is empty\n * before OR after cleaning. Do NOT use for code-like fields (`code`,\n * `errorCode`, `forStatus`) — those pass through untouched via `asNonEmptyString`.\n */\nconst asCleanProse = (value: unknown): string | undefined => {\n  const raw = asNonEmptyString(value);\n  if (raw === undefined) {\n    return undefined;\n  }\n  const cleaned = stripImplementationNoise(raw);\n  return cleaned.length > 0 ? cleaned : undefined;\n};\n\n/**\n * Extract + normalize the Tier-3 HTTP-documentation fields from a raw authored\n * operation spec into the projection shape. Variant examples are a complete\n * overlay: when `variants.<key>.examples` is present it replaces the base\n * operation examples, rather than merging a payload that may target a different\n * response schema. Defensive: a malformed entry is dropped rather than\n * poisoning the whole projection (the generator re-validates via Zod). Returns\n * `{}` when the operation authored no HTTP docs.\n *\n * Prose fields (`meaning` / `when` / `title` / `rateLimitNote`) are cleaned of\n * implementation-only noise via `asCleanProse`, consistent with the Tier-1\n * `description` and Tier-2 field descriptions. `code` / `forStatus` /\n * `errorCode` are `HttpResponseStatusCode` / error-code enum values whose\n * runtime string value (`'200'`, …) is the OpenAPI `responses` key / a machine\n * code, so they pass through untouched as strings.\n */\nexport const buildOperationHttpDocFromSpec = (operationSpec: unknown, variantKey?: string): OperationHttpDoc => {\n  if (!isPlainObject(operationSpec)) {\n    return {};\n  }\n  const doc: OperationHttpDoc = {};\n\n  const responseStatuses = operationSpec['responseStatuses'];\n  if (Array.isArray(responseStatuses)) {\n    const normalized = responseStatuses\n      .map((entry) => {\n        if (!isPlainObject(entry)) return undefined;\n        const code = asNonEmptyString(entry['code']);\n        const meaning = asCleanProse(entry['meaning']);\n        return code !== undefined && meaning !== undefined ? { code, meaning } : undefined;\n      })\n      .filter((entry): entry is { code: string; meaning: string } => entry !== undefined);\n    if (normalized.length > 0) doc.responseStatuses = normalized;\n  }\n\n  const errorScenarios = operationSpec['errorScenarios'];\n  if (Array.isArray(errorScenarios)) {\n    const normalized = errorScenarios\n      .map((entry) => {\n        if (!isPlainObject(entry)) return undefined;\n        const code = asNonEmptyString(entry['code']);\n        const when = asCleanProse(entry['when']);\n        if (code === undefined || when === undefined) return undefined;\n        const scenario: { code: string; when: string; errorCode?: string } = { code, when };\n        const errorCode = asNonEmptyString(entry['errorCode']);\n        if (errorCode !== undefined) scenario.errorCode = errorCode;\n        return scenario;\n      })\n      .filter((entry): entry is { code: string; when: string; errorCode?: string } => entry !== undefined);\n    if (normalized.length > 0) doc.errorScenarios = normalized;\n  }\n\n  if (typeof operationSpec['idempotent'] === 'boolean') {\n    doc.idempotent = operationSpec['idempotent'];\n  }\n\n  const rateLimitNote = asCleanProse(operationSpec['rateLimitNote']);\n  if (rateLimitNote !== undefined) {\n    doc.rateLimitNote = rateLimitNote;\n  }\n\n  const variants = operationSpec['variants'];\n  const variant = isPlainObject(variants) ? variants[variantKey ?? 'default'] : undefined;\n  // A present variant `examples` member deliberately suppresses the base even\n  // when it is malformed or empty: falling back would publish a payload under a\n  // schema the variant does not own. The normalizer below emits no example for\n  // that invalid/empty override, which is safer than a misleading one.\n  const examples =\n    isPlainObject(variant) && Object.prototype.hasOwnProperty.call(variant, 'examples')\n      ? variant['examples']\n      : operationSpec['examples'];\n  if (Array.isArray(examples)) {\n    const normalized = examples\n      .map((entry) => {\n        if (!isPlainObject(entry)) return undefined;\n        const title = asCleanProse(entry['title']);\n        if (title === undefined) return undefined;\n        const example: { title: string; request?: unknown; response?: unknown; forStatus?: string } = { title };\n        if (entry['request'] !== undefined) example.request = entry['request'];\n        if (entry['response'] !== undefined) example.response = entry['response'];\n        const forStatus = asNonEmptyString(entry['forStatus']);\n        if (forStatus !== undefined) example.forStatus = forStatus;\n        return example;\n      })\n      .filter(\n        (entry): entry is { title: string; request?: unknown; response?: unknown; forStatus?: string } =>\n          entry !== undefined,\n      );\n    if (normalized.length > 0) doc.examples = normalized;\n  }\n\n  return doc;\n};\n"]}

package/dist/esm/companion/technical-documentation-asset-path.d.ts

@@ -0,0 +1,16 @@
+import { TechnicalDocumentationAssetKind } from '@wildo-ai/saas-specifications/technical-documentation';
+/**
+ * Encodes the complete semantic asset ref as a portable, case-fold-safe filename stem.
+ *
+ * Byte digests never participate: an asset keeps this path when its bytes change.
+ * Every non-lowercase-alphanumeric member is represented by a distinct token, so
+ * two valid namespaced refs cannot collapse to the same stem on Windows or macOS.
+ */
+export declare function technicalDocumentationAssetFileStem(assetRefInput: string): string;
+/** Canonical managed path for every asset kind implemented by the current reusable pipeline. */
+export declare function technicalDocumentationCanonicalAssetRelativePath(input: {
+    readonly assetRef: string;
+    readonly kind: TechnicalDocumentationAssetKind;
+    readonly mediaType: string;
+}): string;
+//# sourceMappingURL=technical-documentation-asset-path.d.ts.map

package/dist/esm/companion/technical-documentation-asset-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-asset-path.d.ts","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-asset-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,+BAA+B,EAChC,MAAM,uDAAuD,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,gGAAgG;AAChG,wBAAgB,gDAAgD,CAAC,KAAK,EAAE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GAAG,MAAM,CAIT"}

package/dist/esm/companion/technical-documentation-asset-path.js

@@ -0,0 +1,19 @@
+import { technicalDocumentationCanonicalAssetRelativePathContract, technicalDocumentationAssetRefPortableStem, } from '@wildo-ai/saas-specifications/technical-documentation';
+/**
+ * Encodes the complete semantic asset ref as a portable, case-fold-safe filename stem.
+ *
+ * Byte digests never participate: an asset keeps this path when its bytes change.
+ * Every non-lowercase-alphanumeric member is represented by a distinct token, so
+ * two valid namespaced refs cannot collapse to the same stem on Windows or macOS.
+ */
+export function technicalDocumentationAssetFileStem(assetRefInput) {
+    return technicalDocumentationAssetRefPortableStem(assetRefInput);
+}
+/** Canonical managed path for every asset kind implemented by the current reusable pipeline. */
+export function technicalDocumentationCanonicalAssetRelativePath(input) {
+    const path = technicalDocumentationCanonicalAssetRelativePathContract(input);
+    if (path !== null)
+        return path;
+    throw new Error(`technical-documentation asset path policy does not support ${input.kind}/${input.mediaType}`);
+}
+//# sourceMappingURL=technical-documentation-asset-path.js.map

package/dist/esm/companion/technical-documentation-asset-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-asset-path.js","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-asset-path.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wDAAwD,EACxD,0CAA0C,GAE3C,MAAM,uDAAuD,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,mCAAmC,CAAC,aAAqB;IACvE,OAAO,0CAA0C,CAAC,aAAa,CAAC,CAAC;AACnE,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,gDAAgD,CAAC,KAIhE;IACC,MAAM,IAAI,GAAG,wDAAwD,CAAC,KAAK,CAAC,CAAC;IAC7E,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,IAAI,KAAK,CAAC,8DAA8D,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;AACjH,CAAC","sourcesContent":["import {\n  technicalDocumentationCanonicalAssetRelativePathContract,\n  technicalDocumentationAssetRefPortableStem,\n  TechnicalDocumentationAssetKind,\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\n/**\n * Encodes the complete semantic asset ref as a portable, case-fold-safe filename stem.\n *\n * Byte digests never participate: an asset keeps this path when its bytes change.\n * Every non-lowercase-alphanumeric member is represented by a distinct token, so\n * two valid namespaced refs cannot collapse to the same stem on Windows or macOS.\n */\nexport function technicalDocumentationAssetFileStem(assetRefInput: string): string {\n  return technicalDocumentationAssetRefPortableStem(assetRefInput);\n}\n\n/** Canonical managed path for every asset kind implemented by the current reusable pipeline. */\nexport function technicalDocumentationCanonicalAssetRelativePath(input: {\n  readonly assetRef: string;\n  readonly kind: TechnicalDocumentationAssetKind;\n  readonly mediaType: string;\n}): string {\n  const path = technicalDocumentationCanonicalAssetRelativePathContract(input);\n  if (path !== null) return path;\n  throw new Error(`technical-documentation asset path policy does not support ${input.kind}/${input.mediaType}`);\n}\n\n"]}

package/dist/esm/companion/technical-documentation-capture-execution-port.d.ts

@@ -0,0 +1,14 @@
+import type { TechnicalDocumentationCaptureExecutionRequestV1, TechnicalDocumentationCaptureReceiptV1 } from '@wildo-ai/saas-specifications/technical-documentation';
+/**
+ * Result returned before the application-owned publication transaction writes any byte. Keeping bytes in memory at this seam prevents the reusable capture
+ * implementation from choosing an application output root or bypassing complete-tree staging.
+ */
+export interface TechnicalDocumentationCaptureExecutionResult {
+    readonly receipt: TechnicalDocumentationCaptureReceiptV1;
+    readonly outputBytes: Uint8Array;
+}
+/** Production-neutral execution port implemented by the Node-only Playwright capture package. */
+export interface TechnicalDocumentationCaptureExecutionPort {
+    execute(request: TechnicalDocumentationCaptureExecutionRequestV1): Promise<TechnicalDocumentationCaptureExecutionResult>;
+}
+//# sourceMappingURL=technical-documentation-capture-execution-port.d.ts.map

package/dist/esm/companion/technical-documentation-capture-execution-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-capture-execution-port.d.ts","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-capture-execution-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+CAA+C,EAC/C,sCAAsC,EACvC,MAAM,uDAAuD,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,OAAO,EAAE,sCAAsC,CAAC;IACzD,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;CAClC;AAED,iGAAiG;AACjG,MAAM,WAAW,0CAA0C;IACzD,OAAO,CAAC,OAAO,EAAE,+CAA+C,GAAG,OAAO,CAAC,4CAA4C,CAAC,CAAC;CAC1H"}

package/dist/esm/companion/technical-documentation-capture-execution-port.js

@@ -0,0 +1 @@
+//# sourceMappingURL=technical-documentation-capture-execution-port.js.map

package/dist/esm/companion/technical-documentation-capture-execution-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-capture-execution-port.js","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-capture-execution-port.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  TechnicalDocumentationCaptureExecutionRequestV1,\n  TechnicalDocumentationCaptureReceiptV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\n/**\n * Result returned before the application-owned publication transaction writes any byte. Keeping bytes in memory at this seam prevents the reusable capture\n * implementation from choosing an application output root or bypassing complete-tree staging.\n */\nexport interface TechnicalDocumentationCaptureExecutionResult {\n  readonly receipt: TechnicalDocumentationCaptureReceiptV1;\n  readonly outputBytes: Uint8Array;\n}\n\n/** Production-neutral execution port implemented by the Node-only Playwright capture package. */\nexport interface TechnicalDocumentationCaptureExecutionPort {\n  execute(request: TechnicalDocumentationCaptureExecutionRequestV1): Promise<TechnicalDocumentationCaptureExecutionResult>;\n}\n"]}

package/dist/esm/companion/technical-documentation-diagram-materializer.d.ts

@@ -0,0 +1,25 @@
+import { type TechnicalDocumentationAssetRequestV1 } from '@wildo-ai/saas-specifications/technical-documentation';
+export interface TechnicalDocumentationDiagramNode {
+    readonly nodeRef: string;
+    readonly label: string;
+}
+export interface TechnicalDocumentationDiagramEdge {
+    readonly fromNodeRef: string;
+    readonly toNodeRef: string;
+    readonly label: string;
+}
+export interface TechnicalDocumentationDiagramDefinition {
+    readonly diagramRef: string;
+    readonly title: string;
+    readonly nodes: readonly TechnicalDocumentationDiagramNode[];
+    readonly edges: readonly TechnicalDocumentationDiagramEdge[];
+}
+export declare const TECHNICAL_DOCUMENTATION_APPLICATION_REQUEST_DIAGRAM_V1: TechnicalDocumentationDiagramDefinition;
+export declare function createTechnicalDocumentationApplicationRequestDiagramAssetRequest(): TechnicalDocumentationAssetRequestV1;
+/** A dependency-free deterministic SVG materializer; no layout engine or runtime font metrics participate in its bytes. */
+export declare function materializeTechnicalDocumentationDiagram(definition: TechnicalDocumentationDiagramDefinition): {
+    readonly bytes: Uint8Array;
+    readonly byteDigest: string;
+    readonly mediaType: 'image/svg+xml';
+};
+//# sourceMappingURL=technical-documentation-diagram-materializer.d.ts.map

package/dist/esm/companion/technical-documentation-diagram-materializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-diagram-materializer.d.ts","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-diagram-materializer.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,oCAAoC,EAC1C,MAAM,uDAAuD,CAAC;AAI/D,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uCAAuC;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,iCAAiC,EAAE,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,iCAAiC,EAAE,CAAC;CAC9D;AAED,eAAO,MAAM,sDAAsD,EAAE,uCAYnE,CAAC;AAEH,wBAAgB,iEAAiE,IAAI,oCAAoC,CAwBxH;AAMD,2HAA2H;AAC3H,wBAAgB,wCAAwC,CAAC,UAAU,EAAE,uCAAuC,GAAG;IAC7G,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACrC,CA+BA"}

package/dist/esm/companion/technical-documentation-diagram-materializer.js

@@ -0,0 +1,86 @@
+import { TechnicalDocumentationAssetAccessClass, TechnicalDocumentationAssetKind, TechnicalDocumentationAssetOrigin, TechnicalDocumentationAssetRequiredness, TechnicalDocumentationAssetRightsBasis, } from '@wildo-ai/saas-specifications/technical-documentation';
+import { technicalDocumentationSha256Bytes } from './rendering/technical-documentation-render-model.js';
+export const TECHNICAL_DOCUMENTATION_APPLICATION_REQUEST_DIAGRAM_V1 = Object.freeze({
+    diagramRef: 'technical-documentation:diagram/application-api-request',
+    title: 'From client to application API',
+    nodes: Object.freeze([
+        { nodeRef: 'technical-documentation:diagram-node/client', label: 'Client or service' },
+        { nodeRef: 'technical-documentation:diagram-node/application-api', label: 'Application API' },
+        { nodeRef: 'technical-documentation:diagram-node/resource', label: 'Documented resource' },
+    ]),
+    edges: Object.freeze([
+        { fromNodeRef: 'technical-documentation:diagram-node/client', toNodeRef: 'technical-documentation:diagram-node/application-api', label: 'Authenticated request' },
+        { fromNodeRef: 'technical-documentation:diagram-node/application-api', toNodeRef: 'technical-documentation:diagram-node/resource', label: 'Authorized operation' },
+    ]),
+});
+export function createTechnicalDocumentationApplicationRequestDiagramAssetRequest() {
+    return {
+        assetRef: 'technical-documentation:asset/application-api-request-diagram',
+        kind: TechnicalDocumentationAssetKind.DIAGRAM,
+        origin: TechnicalDocumentationAssetOrigin.DETERMINISTIC_RENDER,
+        accessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,
+        requiredness: TechnicalDocumentationAssetRequiredness.REQUIRED,
+        rights: {
+            basis: TechnicalDocumentationAssetRightsBasis.ENGINE_AUTHORED,
+            authorityRef: 'technical-documentation:rights/engine-authored-diagram',
+        },
+        sourceAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,
+        viewedTenantAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,
+        roleAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,
+        captureOrRenderProfileRef: 'technical-documentation:renderer/deterministic-svg-v1',
+        /*
+         * The definition this diagram depicts, NAMED. It was a sha256 of the definition until
+         * 2026-08-27 — computed here by calling the materializer, then compared by the pilot against
+         * the value the same materializer returned over the same frozen constant. A value compared
+         * with itself.
+         */
+        semanticInputRef: TECHNICAL_DOCUMENTATION_APPLICATION_REQUEST_DIAGRAM_V1.diagramRef,
+        altText: 'A client sends an authenticated request through the application API to a documented resource.',
+    };
+}
+function escapeXml(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+/** A dependency-free deterministic SVG materializer; no layout engine or runtime font metrics participate in its bytes. */
+export function materializeTechnicalDocumentationDiagram(definition) {
+    if (definition.nodes.length < 2)
+        throw new Error('technical-documentation diagram requires at least two nodes');
+    const nodes = [...definition.nodes].sort((left, right) => left.nodeRef.localeCompare(right.nodeRef));
+    const nodeRefs = nodes.map((node) => node.nodeRef);
+    if (new Set(nodeRefs).size !== nodeRefs.length)
+        throw new Error('technical-documentation diagram node refs must be unique');
+    const nodeRefSet = new Set(nodeRefs);
+    const edges = [...definition.edges].sort((left, right) => `${left.fromNodeRef}\0${left.toNodeRef}\0${left.label}`.localeCompare(`${right.fromNodeRef}\0${right.toNodeRef}\0${right.label}`));
+    for (const edge of edges) {
+        if (!nodeRefSet.has(edge.fromNodeRef) || !nodeRefSet.has(edge.toNodeRef))
+            throw new Error('technical-documentation diagram edge references an unknown node');
+    }
+    const width = 960;
+    const nodeWidth = 180;
+    const gap = (width - nodes.length * nodeWidth) / (nodes.length + 1);
+    const xByRef = new Map(nodes.map((node, index) => [node.nodeRef, Math.round(gap + index * (nodeWidth + gap))]));
+    const nodeSvg = nodes.map((node) => {
+        const x = xByRef.get(node.nodeRef);
+        return `<g><rect x="${x}" y="96" width="${nodeWidth}" height="72" rx="12" fill="#f7f8fb" stroke="#263247" stroke-width="2"/><text x="${x + nodeWidth / 2}" y="138" text-anchor="middle" font-family="system-ui,sans-serif" font-size="16" fill="#172033">${escapeXml(node.label)}</text></g>`;
+    }).join('');
+    const edgeSvg = edges.map((edge, index) => {
+        const fromX = xByRef.get(edge.fromNodeRef) + nodeWidth;
+        const toX = xByRef.get(edge.toNodeRef);
+        const y = 112 + index * 14;
+        return `<g><path d="M ${fromX} ${y} L ${toX} ${y}" stroke="#54657e" stroke-width="2" marker-end="url(#arrow)"/><text x="${Math.round((fromX + toX) / 2)}" y="${y - 6}" text-anchor="middle" font-family="system-ui,sans-serif" font-size="12" fill="#34445d">${escapeXml(edge.label)}</text></g>`;
+    }).join('');
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="240" viewBox="0 0 ${width} 240" role="img" aria-labelledby="title"><title id="title">${escapeXml(definition.title)}</title><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="#54657e"/></marker></defs><text x="480" y="42" text-anchor="middle" font-family="system-ui,sans-serif" font-size="22" font-weight="600" fill="#172033">${escapeXml(definition.title)}</text>${edgeSvg}${nodeSvg}</svg>\n`;
+    const bytes = Buffer.from(svg, 'utf8');
+    return Object.freeze({
+        bytes,
+        byteDigest: technicalDocumentationSha256Bytes(bytes),
+        mediaType: 'image/svg+xml',
+    });
+}
+/*
+ * `technicalDocumentationDiagramProducerImplementationDigest()` lived here until 2026-08-27. It
+ * hashed `escapeXml.toString()` and this materializer's own source text, and rode into every
+ * resolved asset as `producerImplementationDigest`. Nothing compared it; the producer is named by
+ * `producerRef` + `producerVersion`, which a reader can act on.
+ */
+//# sourceMappingURL=technical-documentation-diagram-materializer.js.map

package/dist/esm/companion/technical-documentation-diagram-materializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical-documentation-diagram-materializer.js","sourceRoot":"","sources":["../../../../src/companion/technical-documentation-diagram-materializer.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  TechnicalDocumentationAssetAccessClass,\n  TechnicalDocumentationAssetKind,\n  TechnicalDocumentationAssetOrigin,\n  TechnicalDocumentationAssetRequiredness,\n  TechnicalDocumentationAssetRightsBasis,\n  type TechnicalDocumentationAssetRequestV1,\n} from '@wildo-ai/saas-specifications/technical-documentation';\n\nimport { technicalDocumentationSha256Bytes } from './rendering/technical-documentation-render-model';\n\nexport interface TechnicalDocumentationDiagramNode {\n  readonly nodeRef: string;\n  readonly label: string;\n}\n\nexport interface TechnicalDocumentationDiagramEdge {\n  readonly fromNodeRef: string;\n  readonly toNodeRef: string;\n  readonly label: string;\n}\n\nexport interface TechnicalDocumentationDiagramDefinition {\n  readonly diagramRef: string;\n  readonly title: string;\n  readonly nodes: readonly TechnicalDocumentationDiagramNode[];\n  readonly edges: readonly TechnicalDocumentationDiagramEdge[];\n}\n\nexport const TECHNICAL_DOCUMENTATION_APPLICATION_REQUEST_DIAGRAM_V1: TechnicalDocumentationDiagramDefinition = Object.freeze({\n  diagramRef: 'technical-documentation:diagram/application-api-request',\n  title: 'From client to application API',\n  nodes: Object.freeze([\n    { nodeRef: 'technical-documentation:diagram-node/client', label: 'Client or service' },\n    { nodeRef: 'technical-documentation:diagram-node/application-api', label: 'Application API' },\n    { nodeRef: 'technical-documentation:diagram-node/resource', label: 'Documented resource' },\n  ]),\n  edges: Object.freeze([\n    { fromNodeRef: 'technical-documentation:diagram-node/client', toNodeRef: 'technical-documentation:diagram-node/application-api', label: 'Authenticated request' },\n    { fromNodeRef: 'technical-documentation:diagram-node/application-api', toNodeRef: 'technical-documentation:diagram-node/resource', label: 'Authorized operation' },\n  ]),\n});\n\nexport function createTechnicalDocumentationApplicationRequestDiagramAssetRequest(): TechnicalDocumentationAssetRequestV1 {\n  return {\n    assetRef: 'technical-documentation:asset/application-api-request-diagram',\n    kind: TechnicalDocumentationAssetKind.DIAGRAM,\n    origin: TechnicalDocumentationAssetOrigin.DETERMINISTIC_RENDER,\n    accessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,\n    requiredness: TechnicalDocumentationAssetRequiredness.REQUIRED,\n    rights: {\n      basis: TechnicalDocumentationAssetRightsBasis.ENGINE_AUTHORED,\n      authorityRef: 'technical-documentation:rights/engine-authored-diagram',\n    },\n    sourceAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,\n    viewedTenantAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,\n    roleAccessClass: TechnicalDocumentationAssetAccessClass.PUBLIC,\n    captureOrRenderProfileRef: 'technical-documentation:renderer/deterministic-svg-v1',\n    /*\n     * The definition this diagram depicts, NAMED. It was a sha256 of the definition until\n     * 2026-08-27 — computed here by calling the materializer, then compared by the pilot against\n     * the value the same materializer returned over the same frozen constant. A value compared\n     * with itself.\n     */\n    semanticInputRef: TECHNICAL_DOCUMENTATION_APPLICATION_REQUEST_DIAGRAM_V1.diagramRef,\n    altText: 'A client sends an authenticated request through the application API to a documented resource.',\n  };\n}\n\nfunction escapeXml(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('\"', '&quot;').replaceAll(\"'\", '&apos;');\n}\n\n/** A dependency-free deterministic SVG materializer; no layout engine or runtime font metrics participate in its bytes. */\nexport function materializeTechnicalDocumentationDiagram(definition: TechnicalDocumentationDiagramDefinition): {\n  readonly bytes: Uint8Array;\n  readonly byteDigest: string;\n  readonly mediaType: 'image/svg+xml';\n} {\n  if (definition.nodes.length < 2) throw new Error('technical-documentation diagram requires at least two nodes');\n  const nodes = [...definition.nodes].sort((left, right) => left.nodeRef.localeCompare(right.nodeRef));\n  const nodeRefs = nodes.map((node) => node.nodeRef);\n  if (new Set(nodeRefs).size !== nodeRefs.length) throw new Error('technical-documentation diagram node refs must be unique');\n  const nodeRefSet = new Set(nodeRefs);\n  const edges = [...definition.edges].sort((left, right) => `${left.fromNodeRef}\\0${left.toNodeRef}\\0${left.label}`.localeCompare(`${right.fromNodeRef}\\0${right.toNodeRef}\\0${right.label}`));\n  for (const edge of edges) {\n    if (!nodeRefSet.has(edge.fromNodeRef) || !nodeRefSet.has(edge.toNodeRef)) throw new Error('technical-documentation diagram edge references an unknown node');\n  }\n  const width = 960;\n  const nodeWidth = 180;\n  const gap = (width - nodes.length * nodeWidth) / (nodes.length + 1);\n  const xByRef = new Map(nodes.map((node, index) => [node.nodeRef, Math.round(gap + index * (nodeWidth + gap))]));\n  const nodeSvg = nodes.map((node) => {\n    const x = xByRef.get(node.nodeRef) as number;\n    return `<g><rect x=\"${x}\" y=\"96\" width=\"${nodeWidth}\" height=\"72\" rx=\"12\" fill=\"#f7f8fb\" stroke=\"#263247\" stroke-width=\"2\"/><text x=\"${x + nodeWidth / 2}\" y=\"138\" text-anchor=\"middle\" font-family=\"system-ui,sans-serif\" font-size=\"16\" fill=\"#172033\">${escapeXml(node.label)}</text></g>`;\n  }).join('');\n  const edgeSvg = edges.map((edge, index) => {\n    const fromX = (xByRef.get(edge.fromNodeRef) as number) + nodeWidth;\n    const toX = xByRef.get(edge.toNodeRef) as number;\n    const y = 112 + index * 14;\n    return `<g><path d=\"M ${fromX} ${y} L ${toX} ${y}\" stroke=\"#54657e\" stroke-width=\"2\" marker-end=\"url(#arrow)\"/><text x=\"${Math.round((fromX + toX) / 2)}\" y=\"${y - 6}\" text-anchor=\"middle\" font-family=\"system-ui,sans-serif\" font-size=\"12\" fill=\"#34445d\">${escapeXml(edge.label)}</text></g>`;\n  }).join('');\n  const svg = `<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"${width}\" height=\"240\" viewBox=\"0 0 ${width} 240\" role=\"img\" aria-labelledby=\"title\"><title id=\"title\">${escapeXml(definition.title)}</title><defs><marker id=\"arrow\" markerWidth=\"8\" markerHeight=\"8\" refX=\"7\" refY=\"4\" orient=\"auto\"><path d=\"M0,0 L8,4 L0,8 z\" fill=\"#54657e\"/></marker></defs><text x=\"480\" y=\"42\" text-anchor=\"middle\" font-family=\"system-ui,sans-serif\" font-size=\"22\" font-weight=\"600\" fill=\"#172033\">${escapeXml(definition.title)}</text>${edgeSvg}${nodeSvg}</svg>\\n`;\n  const bytes = Buffer.from(svg, 'utf8');\n  return Object.freeze({\n    bytes,\n    byteDigest: technicalDocumentationSha256Bytes(bytes),\n    mediaType: 'image/svg+xml' as const,\n  });\n}\n\n/*\n * `technicalDocumentationDiagramProducerImplementationDigest()` lived here until 2026-08-27. It\n * hashed `escapeXml.toString()` and this materializer's own source text, and rode into every\n * resolved asset as `producerImplementationDigest`. Nothing compared it; the producer is named by\n * `producerRef` + `producerVersion`, which a reader can act on.\n */\n"]}