@descryy/runtime-openapi-observation 0.0.0

package/dist/declared-roles.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Which DTO schemas a resolved `API_ENDPOINT` actually declares, by role —
+ * the two-hop join `adapter-openapi` (descry-adapters) writes but nothing
+ * here had read yet: `API_ROUTE --SERVES_API--> API_ENDPOINT`,
+ * `API_ROUTE --USES_TYPE(roles)--> DTO`. An endpoint resolves; its declared
+ * shape is one edge traversal further, through the route that serves it —
+ * `API_ENDPOINT` itself carries no `attrs.fields`, only `attrs.method`/
+ * `attrs.pathTemplate` (`adapter.ts`, read directly rather than assumed).
+ *
+ * **Multiple serving routes are folded, not refused.** Unlike
+ * `resolveEndpointNode`'s own "similar endpoint" ambiguity (which route
+ * served THIS request), several real routes legitimately serving one shared
+ * `API_ENDPOINT` (a repo-scoped route in each of several repositories,
+ * DEC-115) all declare the *same contract* by construction — the endpoint is
+ * the join point precisely because it is workspace-scoped and they are not.
+ * So every DTO any serving route declares, under whichever roles it declares
+ * them, is unioned rather than picked between.
+ */
+import type { IRNode } from "@descryy/ir";
+import { type SqlDriver } from "@descryy/core";
+export type SchemaRole = "request" | "response" | "errorResponse";
+export type DeclaredSchemaRoles = {
+    readonly [K in SchemaRole]: readonly IRNode[];
+};
+/** `{request: [], response: [], errorResponse: []}` for an endpoint no route serves (should not happen for a `resolved` endpoint, but reported rather than assumed) or one whose serving route(s) declared no `USES_TYPE` edge at all — a real, disclosed "this operation names no schema", not an error. */
+export declare function declaredSchemaRoles(driver: SqlDriver, endpointNodeId: string): DeclaredSchemaRoles;
+//# sourceMappingURL=declared-roles.d.ts.map

package/dist/declared-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-roles.d.ts","sourceRoot":"","sources":["../src/declared-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAE5E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,CAAC;AAElE,MAAM,MAAM,mBAAmB,GAAG;IAAE,QAAQ,EAAE,CAAC,IAAI,UAAU,GAAG,SAAS,MAAM,EAAE;CAAE,CAAC;AAOpF,6SAA6S;AAC7S,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,mBAAmB,CAqBlG"}

package/dist/declared-roles.js

@@ -0,0 +1,48 @@
+/**
+ * Which DTO schemas a resolved `API_ENDPOINT` actually declares, by role —
+ * the two-hop join `adapter-openapi` (descry-adapters) writes but nothing
+ * here had read yet: `API_ROUTE --SERVES_API--> API_ENDPOINT`,
+ * `API_ROUTE --USES_TYPE(roles)--> DTO`. An endpoint resolves; its declared
+ * shape is one edge traversal further, through the route that serves it —
+ * `API_ENDPOINT` itself carries no `attrs.fields`, only `attrs.method`/
+ * `attrs.pathTemplate` (`adapter.ts`, read directly rather than assumed).
+ *
+ * **Multiple serving routes are folded, not refused.** Unlike
+ * `resolveEndpointNode`'s own "similar endpoint" ambiguity (which route
+ * served THIS request), several real routes legitimately serving one shared
+ * `API_ENDPOINT` (a repo-scoped route in each of several repositories,
+ * DEC-115) all declare the *same contract* by construction — the endpoint is
+ * the join point precisely because it is workspace-scoped and they are not.
+ * So every DTO any serving route declares, under whichever roles it declares
+ * them, is unioned rather than picked between.
+ */
+import { getNode, incoming, outgoing } from "@descryy/core";
+function rolesOf(attrs) {
+    const roles = attrs?.roles;
+    return Array.isArray(roles) ? roles.filter((r) => typeof r === "string") : [];
+}
+/** `{request: [], response: [], errorResponse: []}` for an endpoint no route serves (should not happen for a `resolved` endpoint, but reported rather than assumed) or one whose serving route(s) declared no `USES_TYPE` edge at all — a real, disclosed "this operation names no schema", not an error. */
+export function declaredSchemaRoles(driver, endpointNodeId) {
+    const result = { request: [], response: [], errorResponse: [] };
+    const seen = new Set();
+    const servingRoutes = incoming(driver, endpointNodeId, { types: ["SERVES_API"] });
+    for (const routeEdge of servingRoutes) {
+        const usesType = outgoing(driver, routeEdge.from, { types: ["USES_TYPE"] });
+        for (const edge of usesType) {
+            const dto = getNode(driver, edge.to);
+            if (dto === undefined)
+                continue; // a dangling edge target: a disclosed gap, not a schema to invent
+            for (const role of rolesOf(edge.attrs)) {
+                if (role !== "request" && role !== "response" && role !== "errorResponse")
+                    continue;
+                const key = `${role}:${dto.id}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                result[role].push(dto);
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=declared-roles.js.map

package/dist/declared-roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-roles.js","sourceRoot":"","sources":["../src/declared-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAkB,MAAM,eAAe,CAAC;AAM5E,SAAS,OAAO,CAAC,KAAoD;IACnE,MAAM,KAAK,GAAG,KAAK,EAAE,KAAK,CAAC;IAC3B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED,6SAA6S;AAC7S,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,cAAsB;IAC3E,MAAM,MAAM,GAAoC,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IACjG,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,KAAK,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAClF,KAAK,MAAM,SAAS,IAAI,aAAa,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC5E,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YACrC,IAAI,GAAG,KAAK,SAAS;gBAAE,SAAS,CAAC,kEAAkE;YACnG,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACvC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,eAAe;oBAAE,SAAS;gBACpF,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;gBAChC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACd,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/endpoint-comparison.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resolving an observed request's method+path against the graph's declared
+ * `API_ENDPOINT` shapes — checklist §15's "documented endpoint" /
+ * "undocumented endpoint" / "wrong method" boxes, and §18's "table/column
+ * mapping" analogue for the OpenAPI half: does the contract know about this
+ * call at all, and if not, is that because the path was never declared, or
+ * because it was declared under a different verb.
+ *
+ * Both underlying queries (`resolveEndpointNode`, `resolveEndpointNodesByPath`)
+ * are `@descryy/runtime-graph-correlator`'s, reused rather than duplicated —
+ * `resolveEndpointNodesByPath` exists in that package specifically because
+ * this comparison needed it (a method-agnostic path query resolveEndpointNode
+ * deliberately doesn't answer on its own).
+ */
+import type { IRNode } from "@descryy/ir";
+import type { SqlDriver } from "@descryy/core";
+export type EndpointComparison = 
+/** Exact method+path resolved to exactly one declared operation. */
+{
+    readonly outcome: "documented";
+    readonly endpoint: IRNode;
+}
+/**
+ * Neither the exact method+path, nor the path under any other method,
+ * resolves to anything — the operation was never declared, under any verb.
+ */
+ | {
+    readonly outcome: "undocumented";
+    readonly reason: string;
+}
+/**
+ * The path IS declared — just not for the method that was actually used.
+ * A different fact from `undocumented`: this is what a contract-reading
+ * person would call a client bug, not a documentation gap.
+ */
+ | {
+    readonly outcome: "wrong-method";
+    readonly observedMethod: string;
+    readonly declaredUnderMethods: readonly string[];
+    readonly reason: string;
+}
+/** Passed straight through from the underlying resolver — same "similar endpoint" shape, one layer up. */
+ | {
+    readonly outcome: "ambiguous";
+    readonly candidates: readonly IRNode[];
+    readonly reason: string;
+};
+export interface ObservedRequest {
+    readonly method: string;
+    readonly path: string;
+}
+export declare function compareObservedEndpoint(driver: SqlDriver, observed: ObservedRequest): EndpointComparison;
+//# sourceMappingURL=endpoint-comparison.d.ts.map

package/dist/endpoint-comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-comparison.d.ts","sourceRoot":"","sources":["../src/endpoint-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAG/C,MAAM,MAAM,kBAAkB;AAC5B,oEAAoE;AAClE;IAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAC/D;;;GAGG;GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC/D;;;;GAIG;GACD;IACE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AACH,0GAA0G;GACxG;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,GAAG,kBAAkB,CA2BxG"}

package/dist/endpoint-comparison.js

@@ -0,0 +1,40 @@
+/**
+ * Resolving an observed request's method+path against the graph's declared
+ * `API_ENDPOINT` shapes — checklist §15's "documented endpoint" /
+ * "undocumented endpoint" / "wrong method" boxes, and §18's "table/column
+ * mapping" analogue for the OpenAPI half: does the contract know about this
+ * call at all, and if not, is that because the path was never declared, or
+ * because it was declared under a different verb.
+ *
+ * Both underlying queries (`resolveEndpointNode`, `resolveEndpointNodesByPath`)
+ * are `@descryy/runtime-graph-correlator`'s, reused rather than duplicated —
+ * `resolveEndpointNodesByPath` exists in that package specifically because
+ * this comparison needed it (a method-agnostic path query resolveEndpointNode
+ * deliberately doesn't answer on its own).
+ */
+import { resolveEndpointNode, resolveEndpointNodesByPath } from "@descryy/runtime-graph-correlator";
+export function compareObservedEndpoint(driver, observed) {
+    const exact = resolveEndpointNode(driver, observed.method, observed.path);
+    if (exact.outcome === "resolved") {
+        return { outcome: "documented", endpoint: exact.node };
+    }
+    if (exact.outcome === "ambiguous") {
+        return { outcome: "ambiguous", candidates: exact.candidates, reason: exact.reason };
+    }
+    // exact.outcome === "not-found" -- the exact method+path is not declared.
+    // Whether the *path* is declared under some other method is a separate
+    // question resolveEndpointNode's own method filter cannot answer.
+    const byPath = resolveEndpointNodesByPath(driver, observed.path);
+    if (byPath.nodes.length === 0) {
+        return { outcome: "undocumented", reason: exact.reason };
+    }
+    const declaredUnderMethods = [...new Set(byPath.nodes.map((n) => n.name.slice(0, n.name.indexOf(" "))))].sort();
+    return {
+        outcome: "wrong-method",
+        observedMethod: observed.method.toUpperCase(),
+        declaredUnderMethods,
+        reason: `${observed.path} is declared under ${declaredUnderMethods.join(", ")}, not ` +
+            `${observed.method.toUpperCase()} — the path is documented, the verb used was not.`,
+    };
+}
+//# sourceMappingURL=endpoint-comparison.js.map

package/dist/endpoint-comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-comparison.js","sourceRoot":"","sources":["../src/endpoint-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AA6BpG,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,QAAyB;IAClF,MAAM,KAAK,GAAG,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE1E,IAAI,KAAK,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IACtF,CAAC;IAED,0EAA0E;IAC1E,uEAAuE;IACvE,kEAAkE;IAClE,MAAM,MAAM,GAAG,0BAA0B,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACjE,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC3D,CAAC;IAED,MAAM,oBAAoB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAChH,OAAO;QACL,OAAO,EAAE,cAAc;QACvB,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE;QAC7C,oBAAoB;QACpB,MAAM,EACJ,GAAG,QAAQ,CAAC,IAAI,sBAAsB,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ;YAC7E,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,mDAAmD;KACtF,CAAC;AACJ,CAAC"}

package/dist/exchange-comparison.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Ties `compareObservedEndpoint`, `classifyStatus`, `declaredSchemaRoles` and
+ * `compareBodyAgainstSchema` together into the one comparison checklist
+ * §15's own boxes actually describe: is the call documented, did its
+ * outcome's class match a schema role the contract declares for it, and —
+ * when a body was observed — does that body's own fields match that role's
+ * declared shape.
+ *
+ * **What "surprising" claims, precisely, and what it does not.** The
+ * contract (`adapter-openapi`) carries `responseSchemas`/`errorSchemas` by
+ * *role*, never a specific status code (§14/§18's own DECISIONS entry names
+ * this limit). So this can say "the operation's contract declares zero
+ * schemas for outcomes shaped like this one" — a real, checkable fact — and
+ * cannot say "this contract expected 200, not 201." Reported as
+ * `statusSurprising: boolean | null`, never as a confident status-code
+ * mismatch it has no basis for.
+ *
+ * **Request and response are compared against different roles, on purpose.**
+ * A request body is always checked against the `request` role, regardless of
+ * outcome; a response body is checked against whichever role the *observed*
+ * status bucket expects (`response` for success, `errorResponse` for a client
+ * or server error) — the same operation's success and error bodies are
+ * different contracts, and comparing an error body against the success DTO
+ * would report every field of a real, correct error response as missing.
+ */
+import type { SqlDriver } from "@descryy/core";
+import { type EndpointComparison, type ObservedRequest } from "./endpoint-comparison.ts";
+import { type DeclaredSchemaRoles } from "./declared-roles.ts";
+import { type StatusBucket } from "./status-bucket.ts";
+import { type SchemaComparison } from "./schema-comparison.ts";
+export interface ObservedExchange extends ObservedRequest {
+    readonly status: number;
+    /** The same raw `string | null` `browser-network-collector` already captures. Omitted (`undefined`) means "not observed", same as `null`. */
+    readonly requestBody?: string | null;
+    readonly responseBody?: string | null;
+}
+export interface ExchangeComparison {
+    readonly endpoint: EndpointComparison;
+    readonly statusBucket: StatusBucket;
+    /** `null` only when `endpoint.outcome !== "documented"` -- nothing to compare a status against without a resolved contract. */
+    readonly declaredRoles: DeclaredSchemaRoles | null;
+    /**
+     * `true`: the observed outcome's bucket has an expected role
+     * (`success`->`response`, `client-error`/`server-error`->`errorResponse`)
+     * and the endpoint's contract declares zero schemas under it.
+     * `false`: a schema is declared, or the endpoint isn't resolved cleanly
+     * enough to ask. `null`: the bucket (`informational`/`redirect`) has no
+     * role in this adapter's vocabulary to compare against at all.
+     */
+    readonly statusSurprising: boolean | null;
+    /** `null` only when `endpoint.outcome !== "documented"`. Always compared against the `request` role, independent of the observed status. */
+    readonly requestSchema: SchemaComparison | null;
+    /** `null` when the endpoint isn't resolved, or the status bucket has no expected role (`informational`/`redirect`) to compare against. */
+    readonly responseSchema: SchemaComparison | null;
+}
+export declare function compareObservedExchange(driver: SqlDriver, observed: ObservedExchange): ExchangeComparison;
+//# sourceMappingURL=exchange-comparison.d.ts.map

package/dist/exchange-comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-comparison.d.ts","sourceRoot":"","sources":["../src/exchange-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAA2B,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAClH,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAyC,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAA4B,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6IAA6I;IAC7I,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,+HAA+H;IAC/H,QAAQ,CAAC,aAAa,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,4IAA4I;IAC5I,QAAQ,CAAC,aAAa,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChD,0IAA0I;IAC1I,QAAQ,CAAC,cAAc,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAClD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAwBzG"}

package/dist/exchange-comparison.js

@@ -0,0 +1,50 @@
+/**
+ * Ties `compareObservedEndpoint`, `classifyStatus`, `declaredSchemaRoles` and
+ * `compareBodyAgainstSchema` together into the one comparison checklist
+ * §15's own boxes actually describe: is the call documented, did its
+ * outcome's class match a schema role the contract declares for it, and —
+ * when a body was observed — does that body's own fields match that role's
+ * declared shape.
+ *
+ * **What "surprising" claims, precisely, and what it does not.** The
+ * contract (`adapter-openapi`) carries `responseSchemas`/`errorSchemas` by
+ * *role*, never a specific status code (§14/§18's own DECISIONS entry names
+ * this limit). So this can say "the operation's contract declares zero
+ * schemas for outcomes shaped like this one" — a real, checkable fact — and
+ * cannot say "this contract expected 200, not 201." Reported as
+ * `statusSurprising: boolean | null`, never as a confident status-code
+ * mismatch it has no basis for.
+ *
+ * **Request and response are compared against different roles, on purpose.**
+ * A request body is always checked against the `request` role, regardless of
+ * outcome; a response body is checked against whichever role the *observed*
+ * status bucket expects (`response` for success, `errorResponse` for a client
+ * or server error) — the same operation's success and error bodies are
+ * different contracts, and comparing an error body against the success DTO
+ * would report every field of a real, correct error response as missing.
+ */
+import { compareObservedEndpoint } from "./endpoint-comparison.js";
+import { declaredSchemaRoles } from "./declared-roles.js";
+import { classifyStatus, expectedRoleForBucket } from "./status-bucket.js";
+import { compareBodyAgainstSchema } from "./schema-comparison.js";
+export function compareObservedExchange(driver, observed) {
+    const endpoint = compareObservedEndpoint(driver, observed);
+    const statusBucket = classifyStatus(observed.status);
+    if (endpoint.outcome !== "documented") {
+        return {
+            endpoint,
+            statusBucket,
+            declaredRoles: null,
+            statusSurprising: null,
+            requestSchema: null,
+            responseSchema: null,
+        };
+    }
+    const declaredRoles = declaredSchemaRoles(driver, endpoint.endpoint.id);
+    const expectedRole = expectedRoleForBucket(statusBucket);
+    const statusSurprising = expectedRole === null ? null : declaredRoles[expectedRole].length === 0;
+    const requestSchema = compareBodyAgainstSchema(declaredRoles.request, observed.requestBody);
+    const responseSchema = expectedRole === null ? null : compareBodyAgainstSchema(declaredRoles[expectedRole], observed.responseBody);
+    return { endpoint, statusBucket, declaredRoles, statusSurprising, requestSchema, responseSchema };
+}
+//# sourceMappingURL=exchange-comparison.js.map

package/dist/exchange-comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exchange-comparison.js","sourceRoot":"","sources":["../src/exchange-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,uBAAuB,EAAiD,MAAM,0BAA0B,CAAC;AAClH,OAAO,EAAE,mBAAmB,EAA4B,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAqB,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EAAE,wBAAwB,EAAyB,MAAM,wBAAwB,CAAC;AA6BzF,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,QAA0B;IACnF,MAAM,QAAQ,GAAG,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3D,MAAM,YAAY,GAAG,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAErD,IAAI,QAAQ,CAAC,OAAO,KAAK,YAAY,EAAE,CAAC;QACtC,OAAO;YACL,QAAQ;YACR,YAAY;YACZ,aAAa,EAAE,IAAI;YACnB,gBAAgB,EAAE,IAAI;YACtB,aAAa,EAAE,IAAI;YACnB,cAAc,EAAE,IAAI;SACrB,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxE,MAAM,YAAY,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACzD,MAAM,gBAAgB,GAAG,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IAEjG,MAAM,aAAa,GAAG,wBAAwB,CAAC,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC5F,MAAM,cAAc,GAClB,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,wBAAwB,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;IAE9G,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC;AACpG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { EndpointComparison, ObservedRequest } from "./endpoint-comparison.ts";
+export { compareObservedEndpoint } from "./endpoint-comparison.ts";
+export type { SchemaRole, DeclaredSchemaRoles } from "./declared-roles.ts";
+export { declaredSchemaRoles } from "./declared-roles.ts";
+export { STATUS_BUCKETS, type StatusBucket, classifyStatus, expectedRoleForBucket } from "./status-bucket.ts";
+export type { FieldDetail, FieldMismatch, SchemaComparison } from "./schema-comparison.ts";
+export { compareBodyAgainstSchema } from "./schema-comparison.ts";
+export type { ObservedExchange, ExchangeComparison } from "./exchange-comparison.ts";
+export { compareObservedExchange } from "./exchange-comparison.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE9G,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAElE,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { compareObservedEndpoint } from "./endpoint-comparison.js";
+export { declaredSchemaRoles } from "./declared-roles.js";
+export { STATUS_BUCKETS, classifyStatus, expectedRoleForBucket } from "./status-bucket.js";
+export { compareBodyAgainstSchema } from "./schema-comparison.js";
+export { compareObservedExchange } from "./exchange-comparison.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAGnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAqB,cAAc,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAG9G,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAGlE,OAAO,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/schema-comparison.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The row §15 left open: an observed request/response BODY compared against a
+ * declared DTO's fields, not merely *which* DTOs a role names
+ * (`declaredSchemaRoles`, which stops at "here are the schemas"). Reads
+ * `DTO.attrs.fieldDetail` — `{name, nullable, required, type?}[]`, written by
+ * `adapter-openapi`'s own `document.ts` directly from the contract, never
+ * derived here.
+ *
+ * **Comparable to the resolved graph, not to a stream.** This takes a raw
+ * body already in hand (the same `string | null` `browser-network-collector`
+ * already captures) — parsing and shape-checking are this file's job, sourcing
+ * the bytes is not, matching every other comparator in this package.
+ *
+ * **Extra fields are never reported.** This adapter does not capture
+ * `additionalProperties`, so "the body has a field the contract doesn't
+ * mention" is not a claim the contract supports either way — reporting it
+ * would be inventing a stricter contract than the one that was published.
+ *
+ * **A role naming more than one DTO refuses, rather than picks one.**
+ * `declaredSchemaRoles` unions across every serving route by design (DEC-115,
+ * multiple repo-scoped routes serving one workspace endpoint) — ordinarily
+ * they agree, but when they name two different schemas for the same role,
+ * comparing the body against whichever came first would silently prefer one
+ * repository's contract over another's.
+ */
+import type { IRNode } from "@descryy/ir";
+export interface FieldDetail {
+    readonly name: string;
+    readonly nullable: boolean;
+    readonly required: boolean;
+    readonly type?: string;
+}
+export type FieldMismatch = {
+    readonly kind: "missing-required";
+    readonly field: string;
+} | {
+    readonly kind: "type-mismatch";
+    readonly field: string;
+    readonly declaredType: string;
+    readonly observedType: string;
+} | {
+    readonly kind: "null-not-nullable";
+    readonly field: string;
+};
+export type SchemaComparison = 
+/** No DTO is declared for this role at all — nothing to compare against. */
+{
+    readonly outcome: "no-schema-declared";
+}
+/** More than one serving route declares a different DTO for the same role. */
+ | {
+    readonly outcome: "ambiguous-schema";
+    readonly candidates: readonly IRNode[];
+    readonly reason: string;
+}
+/** A DTO is declared, but no body was observed to compare it against (e.g. a GET, or a 204). */
+ | {
+    readonly outcome: "no-body-observed";
+    readonly schema: IRNode;
+}
+/** A body was observed but is not valid JSON — a DTO's fields cannot be read off it. */
+ | {
+    readonly outcome: "unparsable-body";
+    readonly schema: IRNode;
+    readonly reason: string;
+}
+/** Valid JSON, but not an object — a DTO's fields have nothing to land on. */
+ | {
+    readonly outcome: "not-an-object";
+    readonly schema: IRNode;
+    readonly observedType: string;
+} | {
+    readonly outcome: "match";
+    readonly schema: IRNode;
+} | {
+    readonly outcome: "mismatch";
+    readonly schema: IRNode;
+    readonly mismatches: readonly FieldMismatch[];
+};
+export declare function compareBodyAgainstSchema(schemas: readonly IRNode[], rawBody: string | null | undefined): SchemaComparison;
+//# sourceMappingURL=schema-comparison.d.ts.map

package/dist/schema-comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-comparison.d.ts","sourceRoot":"","sources":["../src/schema-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxH;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,gBAAgB;AAC1B,4EAA4E;AAC1E;IAAE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE;AAC5C,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC3G,gGAAgG;GAC9F;IAAE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AACnE,wFAAwF;GACtF;IAAE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE;AAC3F,8EAA8E;GAC5E;IAAE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,CAAC;AAwC7G,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,gBAAgB,CA+DzH"}

package/dist/schema-comparison.js

@@ -0,0 +1,121 @@
+/**
+ * The row §15 left open: an observed request/response BODY compared against a
+ * declared DTO's fields, not merely *which* DTOs a role names
+ * (`declaredSchemaRoles`, which stops at "here are the schemas"). Reads
+ * `DTO.attrs.fieldDetail` — `{name, nullable, required, type?}[]`, written by
+ * `adapter-openapi`'s own `document.ts` directly from the contract, never
+ * derived here.
+ *
+ * **Comparable to the resolved graph, not to a stream.** This takes a raw
+ * body already in hand (the same `string | null` `browser-network-collector`
+ * already captures) — parsing and shape-checking are this file's job, sourcing
+ * the bytes is not, matching every other comparator in this package.
+ *
+ * **Extra fields are never reported.** This adapter does not capture
+ * `additionalProperties`, so "the body has a field the contract doesn't
+ * mention" is not a claim the contract supports either way — reporting it
+ * would be inventing a stricter contract than the one that was published.
+ *
+ * **A role naming more than one DTO refuses, rather than picks one.**
+ * `declaredSchemaRoles` unions across every serving route by design (DEC-115,
+ * multiple repo-scoped routes serving one workspace endpoint) — ordinarily
+ * they agree, but when they name two different schemas for the same role,
+ * comparing the body against whichever came first would silently prefer one
+ * repository's contract over another's.
+ */
+function isFieldDetail(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === "string" &&
+        typeof v.nullable === "boolean" &&
+        typeof v.required === "boolean" &&
+        (v.type === undefined || typeof v.type === "string"));
+}
+/** Malformed entries are dropped, not thrown on — the same defensive reading `rolesOf` (declared-roles.ts) does for edge attrs. */
+function fieldDetailOf(schema) {
+    const raw = schema.attrs?.fieldDetail;
+    return Array.isArray(raw) ? raw.filter(isFieldDetail) : [];
+}
+function observedTypeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * JSON's own type system has no `integer` — `5` and `5.5` are both
+ * `"number"`. An `integer`-declared field is checked against
+ * `Number.isInteger`, which is the only place declared and observed types
+ * are not a plain `typeof` match.
+ */
+const TYPE_CHECKS = {
+    string: (v) => typeof v === "string",
+    number: (v) => typeof v === "number",
+    integer: (v) => typeof v === "number" && Number.isInteger(v),
+    boolean: (v) => typeof v === "boolean",
+    array: (v) => Array.isArray(v),
+    object: (v) => typeof v === "object" && v !== null && !Array.isArray(v),
+};
+export function compareBodyAgainstSchema(schemas, rawBody) {
+    if (schemas.length === 0)
+        return { outcome: "no-schema-declared" };
+    if (schemas.length > 1) {
+        return {
+            outcome: "ambiguous-schema",
+            candidates: schemas,
+            reason: `${schemas.length} serving routes declare different schemas for this role ` +
+                `(${schemas.map((s) => s.name).join(", ")}) — picking one to compare the body against would be a guess.`,
+        };
+    }
+    const schema = schemas[0]; // length checked above: not 0, not >1.
+    if (rawBody === null || rawBody === undefined) {
+        return { outcome: "no-body-observed", schema };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawBody);
+    }
+    catch {
+        return {
+            outcome: "unparsable-body",
+            schema,
+            reason: "the observed body is not valid JSON, so field-level comparison against a JSON schema is not possible",
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { outcome: "not-an-object", schema, observedType: observedTypeOf(parsed) };
+    }
+    const body = parsed;
+    const mismatches = [];
+    for (const field of fieldDetailOf(schema)) {
+        if (!Object.prototype.hasOwnProperty.call(body, field.name)) {
+            if (field.required)
+                mismatches.push({ kind: "missing-required", field: field.name });
+            continue;
+        }
+        const value = body[field.name];
+        if (value === null) {
+            if (!field.nullable)
+                mismatches.push({ kind: "null-not-nullable", field: field.name });
+            continue;
+        }
+        if (field.type === undefined)
+            continue;
+        const check = TYPE_CHECKS[field.type];
+        // An unrecognised declared type (the document names something outside
+        // this map) is not checked, rather than silently treated as a match —
+        // there is nothing here yet to compare it against.
+        if (check !== undefined && !check(value)) {
+            mismatches.push({
+                kind: "type-mismatch",
+                field: field.name,
+                declaredType: field.type,
+                observedType: observedTypeOf(value),
+            });
+        }
+    }
+    return mismatches.length === 0 ? { outcome: "match", schema } : { outcome: "mismatch", schema, mismatches };
+}
+//# sourceMappingURL=schema-comparison.js.map

package/dist/schema-comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-comparison.js","sourceRoot":"","sources":["../src/schema-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA8BH,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS;QAC/B,OAAO,CAAC,CAAC,QAAQ,KAAK,SAAS;QAC/B,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CACrD,CAAC;AACJ,CAAC;AAED,mIAAmI;AACnI,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IACzC,OAAO,OAAO,KAAK,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,WAAW,GAA0D;IACzE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ;IACpC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ;IACpC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;IAC5D,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,SAAS;IACtC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,UAAU,wBAAwB,CAAC,OAA0B,EAAE,OAAkC;IACrG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,CAAC;IACnE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,OAAO,EAAE,kBAAkB;YAC3B,UAAU,EAAE,OAAO;YACnB,MAAM,EACJ,GAAG,OAAO,CAAC,MAAM,0DAA0D;gBAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,+DAA+D;SAC3G,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC,uCAAuC;IACnE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9C,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IACjD,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,OAAO,EAAE,iBAAiB;YAC1B,MAAM;YACN,MAAM,EAAE,sGAAsG;SAC/G,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;IACpF,CAAC;IAED,MAAM,IAAI,GAAG,MAAiC,CAAC;IAC/C,MAAM,UAAU,GAAoB,EAAE,CAAC;IAEvC,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,IAAI,KAAK,CAAC,QAAQ;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACrF,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,CAAC,QAAQ;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACvF,SAAS;QACX,CAAC;QAED,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;YAAE,SAAS;QACvC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtC,sEAAsE;QACtE,sEAAsE;QACtE,mDAAmD;QACnD,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACzC,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,eAAe;gBACrB,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,YAAY,EAAE,KAAK,CAAC,IAAI;gBACxB,YAAY,EAAE,cAAc,CAAC,KAAK,CAAC;aACpC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAC9G,CAAC"}

package/dist/status-bucket.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A real HTTP status classified into the class an OpenAPI document actually
+ * has a role vocabulary for. `adapter-openapi`'s `Operation` (descry-adapters)
+ * carries `responseSchemas` (2xx) and `errorSchemas` (non-2xx) — two roles,
+ * not eleven status codes — so this reader stops at the same resolution the
+ * contract itself does, rather than inventing a numeric comparison the
+ * document was never asked to support.
+ */
+export declare const STATUS_BUCKETS: readonly ["informational", "success", "redirect", "client-error", "server-error"];
+export type StatusBucket = (typeof STATUS_BUCKETS)[number];
+export declare function classifyStatus(status: number): StatusBucket;
+/**
+ * The DTO role (`adapter.ts`'s own `roles` vocabulary: `"request"` /
+ * `"response"` / `"errorResponse"`) a bucket corresponds to — `null` for
+ * informational/redirect, which `adapter-openapi` never assigns a role to at
+ * all. Refused rather than guessed: reporting "no declared schema" for a
+ * bucket the contract was never asked about would read as a finding where
+ * there is only an unmodelled case.
+ */
+export declare function expectedRoleForBucket(bucket: StatusBucket): "response" | "errorResponse" | null;
+//# sourceMappingURL=status-bucket.d.ts.map

package/dist/status-bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-bucket.d.ts","sourceRoot":"","sources":["../src/status-bucket.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,cAAc,mFAAoF,CAAC;AAChH,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAM3D;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,eAAe,GAAG,IAAI,CAI/F"}

package/dist/status-bucket.js

@@ -0,0 +1,36 @@
+/**
+ * A real HTTP status classified into the class an OpenAPI document actually
+ * has a role vocabulary for. `adapter-openapi`'s `Operation` (descry-adapters)
+ * carries `responseSchemas` (2xx) and `errorSchemas` (non-2xx) — two roles,
+ * not eleven status codes — so this reader stops at the same resolution the
+ * contract itself does, rather than inventing a numeric comparison the
+ * document was never asked to support.
+ */
+export const STATUS_BUCKETS = ["informational", "success", "redirect", "client-error", "server-error"];
+export function classifyStatus(status) {
+    if (status >= 100 && status < 200)
+        return "informational";
+    if (status >= 200 && status < 300)
+        return "success";
+    if (status >= 300 && status < 400)
+        return "redirect";
+    if (status >= 400 && status < 500)
+        return "client-error";
+    return "server-error";
+}
+/**
+ * The DTO role (`adapter.ts`'s own `roles` vocabulary: `"request"` /
+ * `"response"` / `"errorResponse"`) a bucket corresponds to — `null` for
+ * informational/redirect, which `adapter-openapi` never assigns a role to at
+ * all. Refused rather than guessed: reporting "no declared schema" for a
+ * bucket the contract was never asked about would read as a finding where
+ * there is only an unmodelled case.
+ */
+export function expectedRoleForBucket(bucket) {
+    if (bucket === "success")
+        return "response";
+    if (bucket === "client-error" || bucket === "server-error")
+        return "errorResponse";
+    return null;
+}
+//# sourceMappingURL=status-bucket.js.map

package/dist/status-bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-bucket.js","sourceRoot":"","sources":["../src/status-bucket.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,eAAe,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,CAAU,CAAC;AAGhH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,eAAe,CAAC;IAC1D,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,UAAU,CAAC;IACrD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,cAAc,CAAC;IACzD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAoB;IACxD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC5C,IAAI,MAAM,KAAK,cAAc,IAAI,MAAM,KAAK,cAAc;QAAE,OAAO,eAAe,CAAC;IACnF,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@descryy/runtime-openapi-observation",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "OpenAPI runtime contract comparison (plan §15/§18): a real observed HTTP exchange, compared against the graph's already-declared API_ENDPOINT/DTO shapes -- documented/undocumented/wrong-method resolution and status-bucket-vs-declared-role comparison.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/ir": "^0.1.0",
+    "@descryy/core": "^0.1.0",
+    "@descryy/runtime-graph-correlator": "*"
+  },
+  "devDependencies": {
+    "@descry/adapter-openapi": "file:../../../descry-adapters/packages/adapter-openapi",
+    "@descryy/runtime-controller": "*"
+  }
+}