backend-skeleton 1.0.0-beta.1

package/contracts/completeness.mjs

@@ -0,0 +1,176 @@
+// A5: distinguishes "a contract file was written" from "this contract is complete enough to
+// trust". `buildContract()` (contracts/emit.mjs) always succeeds and always returns SOME
+// object, even when it found zero usable operations -- Team-IZ-Backend's `codeanalysis` module
+// (1 entity, 0 controllers) produces operations:0, warnings:0 with the pre-A5 code, and the
+// `contract` gate passed silently (see D-contract-completeness in DECISIONS.md for the full
+// before/after). This module is the single place that turns a contract's warnings into a
+// completeness verdict and evaluates that verdict against recorded waivers -- contracts/emit.mjs
+// stays a pure "what did the scan find" function and never looks at waivers itself, and
+// bin/bskel.mjs never re-derives severity/blocking logic inline.
+import { readJsonIfExists, writeFileAtomic } from '../lib/fsutil.mjs';
+import { specPath } from '../lib/paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+
+export const SEVERITY = Object.freeze({ ERROR: 'error', WARN: 'warn' });
+export const COMPLETENESS = Object.freeze({ COMPLETE: 'complete', PARTIAL: 'partial', BLOCKED: 'blocked' });
+
+// `waivable: false` codes only ever co-occur with zero operations (CONTRACT_NO_MODULE and
+// CONTRACT_EMPTY both mean the endpoint loop in buildContract() never ran at all) -- so gating
+// waivers on `completeness === 'blocked'` in cmdContractWaive is sufficient to keep them
+// unwaivable; there is no case where either fires with operations > 0.
+export const WARNING_CODES = Object.freeze({
+	CONTRACT_NO_MODULE: { severity: SEVERITY.ERROR, waivable: false },
+	CONTRACT_EMPTY: { severity: SEVERITY.ERROR, waivable: false },
+	CONTRACT_UNMATCHED_ENDPOINT: { severity: SEVERITY.ERROR, waivable: true },
+	CONTRACT_DUPLICATE_OPERATION_ID: { severity: SEVERITY.ERROR, waivable: true },
+	CONTRACT_BODY_UNKNOWN: { severity: SEVERITY.WARN, waivable: true },
+	// A1: an operationId correlated by the scan (or by OpenAPI reconciliation) that disagrees
+	// with the OpenAPI document on verb or path in a way the inferred/given path prefix can't
+	// explain -- a real conflict, not just a missing prefix. Never silently resolved in favor of
+	// either source; the scan's own value is kept (fail-closed) and this blocks until a human
+	// looks. See contracts/openapi.mjs.
+	CONTRACT_OPENAPI_DRIFT: { severity: SEVERITY.ERROR, waivable: true },
+	// A1: the scan found a real operationId that simply isn't in the OpenAPI document at all --
+	// distinct from DRIFT (found but disagrees) because a waiver keyed on one must never silently
+	// cover the other if the underlying cause changes later (see D-contract-completeness's
+	// wildcard-waiver reasoning, reapplied here). Left uncorrected (still the unprefixed scan
+	// path) specifically so this can't be mistaken for a successful reconciliation.
+	CONTRACT_OPENAPI_MISSING_OPERATION: { severity: SEVERITY.ERROR, waivable: true },
+	// A1: an unmatched (no operationId) endpoint's verb+normalized-path resolved to more than one
+	// OpenAPI operation candidate -- never guessed, see contracts/openapi.mjs's reconcileModule.
+	CONTRACT_OPENAPI_AMBIGUOUS: { severity: SEVERITY.ERROR, waivable: true },
+	// A1: an operationId was adopted from the OpenAPI document itself (the scan found no
+	// @Operation(operationId=...) at all) rather than confirmed against source -- low-risk (same
+	// class as CONTRACT_BODY_UNKNOWN): the id is real and addressable, but isn't pinned in Java
+	// source, so renaming the handler method silently changes what clients see.
+	CONTRACT_OPENAPI_DERIVED_OPERATION_ID: { severity: SEVERITY.WARN, waivable: true },
+	// A2: a `matched`/`adopted` operation (path/verb already reconciled) whose OpenAPI requestBody
+	// declares an application/json schema, but that schema could not be projected into a
+	// self-contained JSON Schema -- an unsupported keyword, an over-long or uncompilable `pattern`,
+	// a $ref cycle, or a depth/node-count cap. Deliberately WARN, not ERROR: the contract is still
+	// CORRECT (the pre-A2 `body:true -> {type:'object'}` fallback still applies), just less
+	// specific -- a missed enhancement, not a defect. Making this ERROR would make `partial`/
+	// `blocked` depend on how exotic a downstream DTO's validation annotations happen to be, across
+	// every real module -- same class as CONTRACT_BODY_UNKNOWN. See contracts/openapi.mjs's
+	// inlineSchema() and D-openapi-request-schema in DECISIONS.md.
+	CONTRACT_OPENAPI_SCHEMA_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	// A3: same shape as CONTRACT_OPENAPI_SCHEMA_UNRESOLVED above, one for the response (2xx) side
+	// and one for the error (4xx/5xx) side -- deliberately TWO codes, not one shared with each
+	// other or with the request-side code above. An operation's request/response/error projection
+	// can each fail independently for unrelated reasons; if they shared a code, a waiver for one
+	// failure (keyed on {code, subject=operationId}) would silently also cover the other, and a
+	// future severity change to one direction would force splitting a shipped code. Same WARN
+	// reasoning: the pre-A3 unconstrained response/error check still applies, so this is a missed
+	// enhancement, not a defect. See D-openapi-response-schema in DECISIONS.md.
+	CONTRACT_OPENAPI_RESPONSE_SCHEMA_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	CONTRACT_OPENAPI_ERROR_SCHEMA_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+});
+
+export const WARNING_CODE_NAMES = Object.freeze(Object.keys(WARNING_CODES));
+
+export function getWarningCode(code) {
+	return Object.hasOwn(WARNING_CODES, code) ? WARNING_CODES[code] : null;
+}
+
+// The typo-defense point for `bskel contract waive --code <CODE>` -- same pattern as
+// lib/gate-definitions.mjs's requireGateDefinition.
+export function requireWarningCode(code) {
+	const spec = getWarningCode(code);
+	if (!spec) {
+		throw new Error(`unknown contract warning code "${code}" -- known codes: ${WARNING_CODE_NAMES.join(', ')}`);
+	}
+	return spec;
+}
+
+// severity is stamped onto the warning at creation time (so a plain JSON reader never needs this
+// module to know what a contract means), but blocking decisions always re-derive severity from
+// WARNING_CODES, not from the stamped value -- see evaluateResolution.
+export function makeWarning(code, { subject = null, message, detail = {} }) {
+	const spec = requireWarningCode(code);
+	return { code, severity: spec.severity, subject, message, detail };
+}
+
+// The waiver key. Deliberately code+subject only, NEVER message -- message text gets rephrased
+// over time, and a waiver keyed on it would silently stop matching. subject is derived from the
+// stable verb+path or operationId, not from anything a human might reword.
+export function warningKey(warning) {
+	return `${warning.code}::${warning.subject ?? '*'}`;
+}
+
+export function countByCode(warnings) {
+	const counts = {};
+	for (const w of warnings) counts[w.code] = (counts[w.code] ?? 0) + 1;
+	return counts;
+}
+
+// Completeness from the contract's own content alone -- knows nothing about waivers (see
+// evaluateResolution for the waiver-aware verdict). Zero operations always means `blocked`
+// regardless of what warnings say (a blocked contract usually has zero warnings too, since the
+// endpoint loop that would generate them never ran -- but this stays correct either way).
+export function classifyContract({ operations, warnings }) {
+	if (Object.keys(operations).length === 0) return COMPLETENESS.BLOCKED;
+	if (warnings.some((w) => w.severity === SEVERITY.ERROR)) return COMPLETENESS.PARTIAL;
+	return COMPLETENESS.COMPLETE;
+}
+
+const RESOLUTION_SCHEMA = 'sbf.contract-resolution/1';
+
+export function resolutionPath(root, featureId) {
+	return specPath(root, featureId, 'contracts', `${featureId}.resolution.json`);
+}
+
+export function loadResolution(root, featureId) {
+	const path = resolutionPath(root, featureId);
+	const parsed = readJsonIfExists(path);
+	if (parsed === null) {
+		return { schema: RESOLUTION_SCHEMA, feature_id: featureId, waivers: [] };
+	}
+	// S5 (D-persistence-integrity): lib-style read function -- throws a plain Error (same
+	// convention as lib/state.mjs's loadState), which bin/bskel.mjs's main() catch-all already
+	// treats as a documented case ("a malformed-state read", exit 14/BAD_ARGS).
+	const { ok, errors } = validateAgainstSchema('contract-resolution.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${path}: does not match schemas/contract-resolution.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+// S5 (D-persistence-integrity): the write-side sibling of loadResolution() above -- validated
+// before it touches disk, same "fail loud here, not later" reasoning as every other write site
+// this item touched. Deliberately does NOT lock by itself: the load-modify-save race this file
+// has (`bskel contract waive` reads the current resolution, appends new waiver entries, then
+// writes -- no synchronization) can only be closed by locking the WHOLE cycle, not just the final
+// write -- see bin/bskel.mjs's cmdContractWaive, which wraps loadResolution()...saveResolution()
+// in withLockSync(), the same shape lib/state.mjs's setGate() already uses for its own
+// load-modify-save.
+export function saveResolution(root, featureId, resolution) {
+	const { ok, errors } = validateAgainstSchema('contract-resolution.schema.json', resolution);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid contract resolution for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(resolutionPath(root, featureId), `${JSON.stringify(resolution, null, 2)}\n`);
+	return resolution;
+}
+
+// The waiver-aware verdict `bskel contract emit`/`bskel contract waive` act on. `blocked` is
+// never waivable, full stop -- a contract with zero operations has nothing waiving could fix.
+// For `partial`, only ERROR-severity warnings can block (a WARN like CONTRACT_BODY_UNKNOWN never
+// blocks, waived or not). Deliberately no wildcard match: a waiver only cancels the EXACT
+// code+subject pair recorded for it, so a new unmatched endpoint added later is never silently
+// covered by an old "--all" waive -- see the "waiver invalidation" test in test/contract-cli.test.mjs.
+export function evaluateResolution(contract, resolution) {
+	const status = classifyContract(contract);
+	const waivers = resolution.waivers ?? [];
+	const waivedKeys = new Set(waivers.map(warningKey));
+
+	const errorWarnings = contract.warnings.filter((w) => w.severity === SEVERITY.ERROR);
+	const unwaived = errorWarnings.filter((w) => !waivedKeys.has(warningKey(w)));
+	const waived = errorWarnings.filter((w) => waivedKeys.has(warningKey(w)));
+
+	const currentErrorKeys = new Set(errorWarnings.map(warningKey));
+	const staleWaivers = waivers.filter((w) => !currentErrorKeys.has(warningKey(w)));
+
+	const blocking = status === COMPLETENESS.BLOCKED || unwaived.length > 0;
+
+	return { status, blocking, unwaived, waived, staleWaivers };
+}

package/contracts/emit.mjs

@@ -0,0 +1,287 @@
+import fs from 'node:fs';
+import { makeWarning, classifyContract } from './completeness.mjs';
+import { findMethodParams } from '../scanners/adapters/_java-spring-analyzer.mjs';
+
+// D-security-2: a plain UUID `pattern`, not `format: 'uuid'`. ajv-formats' uuid format accepts
+// an optional `urn:uuid:` prefix (per its RFC 4122 reading), but Spring's `UUID` path-variable
+// converter expects the bare form -- a contract using `format: 'uuid'` could certify a
+// `urn:uuid:...` request as valid when the real endpoint would reject it. Found by the Codex
+// security review, verified against the installed ajv-formats@3.0.1.
+//
+// A2: exported so contracts/openapi.mjs's inlineSchema() can apply the identical fix one layer
+// down -- springdoc renders a Java `UUID` request-body field as `{type:'string', format:'uuid'}`,
+// the exact shape this const was created to avoid, just inside a projected body schema instead of
+// a path param. Direction stays one-way (openapi.mjs imports from emit.mjs, never the reverse).
+export const BARE_UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
+
+function pathParamsSchema(routePath) {
+	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+	const properties = {};
+	for (const p of params) {
+		// Naming convention seen throughout Team-IZ-Backend (`UUID organizationId`, etc.) --
+		// a heuristic, not a guarantee; wrong for a path param that happens to end in "Id" but
+		// isn't a UUID, which just means an over-strict uuid-shaped check on that one field.
+		properties[p] = /id$/i.test(p) ? { type: 'string', pattern: BARE_UUID_PATTERN } : { type: 'string' };
+	}
+	return { type: 'object', additionalProperties: false, properties, required: params };
+}
+
+// Re-reads the controller source (already located by the scan) to check whether this specific
+// method's parameter list has @RequestBody -- verb alone is not reliable in this codebase
+// (e.g. `deleteOrganization` is DELETE but still takes a @RequestBody confirm-name payload).
+// A2 Phase 1 (D-java-analyzer): confirmed live that the old non-greedy `([\s\S]*?)\)\s*\{` regex
+// (the exact pattern the catalog's own A2 Why names alongside extractController()) failed to
+// match at all against a return type with a space inside a generic (`ResponseEntity<Map<String,
+// Object>>`) -- findMethodParams() shares the same balanced-delimiter analyzer that fixes the
+// scanner's identical GenericWithSpaceController case.
+function detectRequestBody(filePath, methodName) {
+	if (!filePath || !fs.existsSync(filePath)) return null;
+	const text = fs.readFileSync(filePath, 'utf8');
+	const params = findMethodParams(text, methodName);
+	if (params === null) return null;
+	return /@RequestBody/.test(params);
+}
+
+// A1: shared with contracts/openapi.mjs so "which module" and "which endpoint is which" are
+// defined in exactly one place -- openapi.mjs imports these (never the reverse), so a
+// reconciliation is guaranteed to line up with the same module/endpoint buildContract() sees,
+// as long as both are called with the same (scanReport, moduleName) inputs.
+export function selectModule(scanReport, moduleName) {
+	return moduleName
+		? scanReport.related_modules.find((m) => m.module === moduleName)
+		: scanReport.related_modules[0];
+}
+
+// A string, not object identity, so it survives serialization into the openapi snapshot and
+// doesn't depend on both callers sharing the exact same parsed scanReport object.
+export function endpointKey(controllerIndex, endpointIndex) {
+	return `${controllerIndex}:${endpointIndex}`;
+}
+
+// A5: warnings are structured ({code, severity, subject, message, detail}), not bare strings --
+// see contracts/completeness.mjs. The three original warning conditions (no-module/unmatched/
+// duplicate) and their exact message text are unchanged; two are new (CONTRACT_EMPTY,
+// CONTRACT_BODY_UNKNOWN). This function still never looks at waivers -- it reports what the scan
+// found, nothing more; bin/bskel.mjs's cmdContractEmit is what weighs warnings against
+// contracts/completeness.mjs's evaluateResolution() to decide whether to block.
+//
+// A1: `openapi` (default null) is an already-computed contracts/openapi.mjs Reconciliation --
+// this function never opens the OpenAPI file itself (same "stays pure" discipline as never
+// looking at waivers). `openapi === null` is a hard guarantee of byte-identical output to
+// pre-A1 behavior -- see test/contract.test.mjs's "openapi param omitted" test.
+export function buildContract({ featureId, featureUid, scanReport, module: moduleName, openapi = null }) {
+	const targetModule = selectModule(scanReport, moduleName);
+
+	const operations = {};
+	const warnings = [];
+	let endpointCount = 0;
+
+	if (!targetModule) {
+		warnings.push(makeWarning('CONTRACT_NO_MODULE', {
+			message: 'no related module in the scan report -- emitting an empty operation set. Pass --module, or re-run `bskel scan` with terms that actually match the intended feature.',
+		}));
+	} else {
+		for (const [ci, controller] of targetModule.controllers.entries()) {
+			for (const [ei, ep] of controller.endpoints.entries()) {
+				endpointCount++;
+				const res = openapi ? openapi.byEndpoint.get(endpointKey(ci, ei)) ?? null : null;
+
+				let operationId = ep.operationId;
+				let verb = ep.verb;
+				let route = ep.path;
+				let provenance = 'scan';
+				let openapiAttempted = false;
+				let openapiReason = null;
+				// A2/A3: only ever set for matched/adopted (contracts/openapi.mjs's applyRequestBodySchema/
+				// applyResponseSchemas run for those two kinds only) -- stays null for every other kind.
+				let requestBodySchema = null;
+				let requestBodyRequired = false;
+				let schemaUnresolvedReason = null;
+				let responseSchema = null;
+				let responseSchemaUnresolvedReason = null;
+				let errorSchema = null;
+				let errorSchemaUnresolvedReason = null;
+
+				if (res) {
+					switch (res.kind) {
+						case 'matched':
+							// operationId came from source (scan), verb/path are OpenAPI-confirmed --
+							// this is A1's main fix: the endpoint was already addressable, but its path
+							// was wrong (missing e.g. a global /api/v0 prefix the scanner can't see).
+							verb = res.verb;
+							route = res.path;
+							provenance = 'scan+openapi';
+							requestBodySchema = res.requestBodySchema ?? null;
+							requestBodyRequired = res.requestBodyRequired ?? false;
+							schemaUnresolvedReason = res.schemaUnresolvedReason ?? null;
+							responseSchema = res.responseSchema ?? null;
+							responseSchemaUnresolvedReason = res.responseSchemaUnresolvedReason ?? null;
+							errorSchema = res.errorSchema ?? null;
+							errorSchemaUnresolvedReason = res.errorSchemaUnresolvedReason ?? null;
+							break;
+						case 'adopted':
+							// No @Operation(operationId=...) in source at all -- the id itself comes from
+							// the document, not from anything pinned in Java. Real and addressable, but
+							// flagged (WARN, not ERROR) since renaming the handler method would silently
+							// change it.
+							operationId = res.operationId;
+							verb = res.verb;
+							route = res.path;
+							provenance = 'openapi';
+							requestBodySchema = res.requestBodySchema ?? null;
+							requestBodyRequired = res.requestBodyRequired ?? false;
+							schemaUnresolvedReason = res.schemaUnresolvedReason ?? null;
+							responseSchema = res.responseSchema ?? null;
+							responseSchemaUnresolvedReason = res.responseSchemaUnresolvedReason ?? null;
+							errorSchema = res.errorSchema ?? null;
+							errorSchemaUnresolvedReason = res.errorSchemaUnresolvedReason ?? null;
+							warnings.push(makeWarning('CONTRACT_OPENAPI_DERIVED_OPERATION_ID', {
+								subject: operationId,
+								message: `operationId "${operationId}" for ${res.verb} ${res.path} was not found in the source (no @Operation(operationId=...)) -- adopted directly from the OpenAPI document instead`,
+								detail: { verb: res.verb, path: res.path, scan_verb: ep.verb, scan_path: ep.path },
+							}));
+							break;
+						case 'drift':
+							// operationId matches on both sides, but verb/path disagree in a way the
+							// path prefix can't explain -- possibly the scanner's "nearest preceding
+							// @Operation(" heuristic mis-attributed this id to the wrong method. Fail
+							// closed: keep the scan's own value, don't silently adopt the document's.
+							warnings.push(makeWarning('CONTRACT_OPENAPI_DRIFT', {
+								subject: ep.operationId,
+								message: `operationId "${ep.operationId}" disagrees with the OpenAPI document on ${res.reason} -- scan has ${ep.verb} ${ep.path}, OpenAPI has ${res.openapi.verb} ${res.openapi.path}. Not auto-resolved.`,
+								detail: { reason: res.reason, scan: { verb: ep.verb, path: ep.path }, openapi: res.openapi },
+							}));
+							break;
+						case 'missing':
+							// The scan's operationId isn't in the document anywhere -- left uncorrected
+							// (still the unprefixed scan path) specifically so this can't be mistaken
+							// for a successful reconciliation.
+							warnings.push(makeWarning('CONTRACT_OPENAPI_MISSING_OPERATION', {
+								subject: ep.operationId,
+								message: `operationId "${ep.operationId}" (${ep.verb} ${ep.path}) was not found anywhere in the OpenAPI document -- path left uncorrected`,
+								detail: { verb: ep.verb, path: ep.path },
+							}));
+							break;
+						case 'ambiguous':
+							warnings.push(makeWarning('CONTRACT_OPENAPI_AMBIGUOUS', {
+								subject: `${ep.verb} ${ep.path}`,
+								message: `${ep.verb} ${ep.path} matched more than one OpenAPI operation candidate -- not guessed`,
+								detail: { verb: ep.verb, path: ep.path, candidates: res.candidates },
+							}));
+							continue; // still has no operationId -- can't be addressed either way
+						case 'unresolved':
+							// No candidate, or the path prefix couldn't be determined -- falls through
+							// to the ordinary CONTRACT_UNMATCHED_ENDPOINT path below, with detail
+							// recording that OpenAPI reconciliation was attempted and why it didn't help.
+							openapiAttempted = true;
+							openapiReason = res.reason;
+							break;
+						default:
+							break;
+					}
+				}
+
+				if (!operationId) {
+					warnings.push(makeWarning('CONTRACT_UNMATCHED_ENDPOINT', {
+						subject: `${ep.verb} ${ep.path}`,
+						message: `${ep.verb} ${ep.path} (method ${ep.method}) has no correlated operationId in the scan -- skipped, it cannot be addressed by operation_id in the envelope`,
+						detail: {
+							verb: ep.verb, path: ep.path, method: ep.method,
+							...(openapiAttempted ? { openapi_attempted: true, openapi_reason: openapiReason } : {}),
+						},
+					}));
+					continue;
+				}
+				if (operations[operationId]) {
+					warnings.push(makeWarning('CONTRACT_DUPLICATE_OPERATION_ID', {
+						subject: operationId,
+						message: `duplicate operationId "${operationId}" seen more than once -- keeping the first occurrence`,
+						detail: { verb, path: route, method: ep.method },
+					}));
+					continue;
+				}
+				const hasBody = detectRequestBody(controller.file, ep.method);
+				if (hasBody === null) {
+					// Low-risk metadata gap, not a routing/addressing problem -- warn, not error (see
+					// WARNING_CODES in completeness.mjs). operationPayloadSchema() already treats
+					// body:'unknown' as optional, so this just makes that leniency visible instead of silent.
+					warnings.push(makeWarning('CONTRACT_BODY_UNKNOWN', {
+						subject: `${verb} ${route}`,
+						message: `${verb} ${route} (operationId "${operationId}") -- could not determine whether this method takes a @RequestBody (controller source not found or method signature not matched); payload body is treated as optional`,
+						detail: { verb, path: route, method: ep.method, operationId },
+					}));
+				}
+				// A2: the schema was found and couldn't be projected -- distinct from "no schema to
+				// project at all" (requestBodySchema stays null with no warning in that case, see
+				// contracts/openapi.mjs's applyRequestBodySchema). Falls back to the pre-A2 bare-object
+				// check (operationPayloadSchema treats a missing requestBodySchema as before); never
+				// blocks completeness (WARN, see contracts/completeness.mjs).
+				if (schemaUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_SCHEMA_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) matched an OpenAPI operation with a JSON request body, but its schema could not be projected (${schemaUnresolvedReason}) -- the body is still validated, just as a bare object instead of its real shape`,
+						detail: { reason: schemaUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				// A3: same "found but couldn't project" distinction as the request-body warning above,
+				// applied separately to response (2xx) and error (4xx/5xx) -- two DIFFERENT codes (see
+				// D-openapi-response-schema), so a projection failure on one direction never shares a
+				// waiver key with an unrelated failure on another direction for the same operation.
+				if (responseSchemaUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_RESPONSE_SCHEMA_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) documents a 2xx JSON response, but its schema could not be projected (${responseSchemaUnresolvedReason}) -- the response stays unconstrained, same as before --openapi-file`,
+						detail: { reason: responseSchemaUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				if (errorSchemaUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_ERROR_SCHEMA_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) documents a 4xx/5xx JSON response, but its schema could not be projected (${errorSchemaUnresolvedReason}) -- the error payload stays unconstrained, same as before --openapi-file`,
+						detail: { reason: errorSchemaUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				operations[operationId] = {
+					verb,
+					path: route,
+					pathParams: pathParamsSchema(route),
+					body: hasBody === null ? 'unknown' : hasBody,
+					provenance,
+					// A2/A3: omitted entirely (not null/false) when there's nothing to project -- keeps
+					// `openapi:null` (and any operation that isn't matched/adopted) byte-identical to
+					// pre-A2/A3 output, the same guarantee A1 established for its own fields.
+					...(requestBodySchema ? { requestBodySchema, requestBodyRequired } : {}),
+					...(responseSchema ? { responseSchema } : {}),
+					...(errorSchema ? { errorSchema } : {}),
+				};
+			}
+		}
+	}
+
+	// Fires regardless of WHY operations ended up empty (no module matched, or a module matched
+	// but had zero controllers/endpoints, or every endpoint was unmatched/duplicate) -- the other
+	// warnings explain the cause, this one states the consequence: nothing here can be trusted.
+	if (Object.keys(operations).length === 0) {
+		warnings.push(makeWarning('CONTRACT_EMPTY', {
+			message: 'this contract has zero operations -- it cannot be used by `contract validate`/`tool-schema`, or routed to by `handles emit`. Fix --module/--terms, or if this module genuinely has no HTTP surface (yet), there is nothing to contract.',
+		}));
+	}
+
+	const completeness = {
+		status: classifyContract({ operations, warnings }),
+		operation_count: Object.keys(operations).length,
+		endpoint_count: endpointCount,
+	};
+
+	return {
+		sbf_contract: '4',
+		feature_id: featureId,
+		feature_uid: featureUid,
+		source: targetModule
+			? { adapter: scanReport.adapter, module: targetModule.module, provenance: openapi ? 'scan+openapi' : 'scan' }
+			: { adapter: scanReport.adapter ?? null, module: null, provenance: 'none' },
+		operations,
+		warnings,
+		completeness,
+	};
+}