backend-skeleton 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -119,13 +119,22 @@ inverse of `contract emit --openapi-file`. Useful for a Swagger UI page scoped t
 instead of the whole repo, a client generator that can't follow `$ref` (an exported document has
 none), or a mock server for one feature's operations.
 
-It is a **deliberately lossy, narrow projection, and it says so**: the contract carries no query or
-header parameters, no security requirements, no summaries or tags, and no per-status responses, so
-none of those appear — every omission is disclosed both in prose (`info.description`) and
-machine-readably (`info.x-bskel-omitted`). Nothing is invented to fill a gap: `security` is omitted
-rather than emitted as `[]` (an empty array would positively claim no authentication is required),
-and an operation whose body shape the contract doesn't know gets a JSON media-type entry with no
-schema rather than a fabricated one.
+It is a **deliberately lossy, narrow projection, and it says so** — every omission is disclosed
+both in prose (`info.description`) and machine-readably (`info.x-bskel-omitted`). Nothing is
+invented to fill a gap: an operation whose body shape the contract doesn't know gets a JSON
+media-type entry with no schema rather than a fabricated one, and an operation with no per-status
+source data still collapses its 2xx/4xx/5xx bodies into two unions rather than guessing a status
+code.
+
+Query/header/cookie parameters, `security` (plus the referenced security schemes), `summary`,
+`tags`, per-status responses, and non-JSON request media types (e.g. `multipart/form-data`) **are**
+emitted — but only when a real `--openapi-file` source document said something for that exact
+operation, copied byte-for-byte, never reconstructed. `security: []` is emitted when the source
+document itself said `[]` (a genuine claim that no authentication is required); it is never
+invented as a default. Where no source document was given, or it said nothing for an operation
+(or a particular field of one), the key is simply omitted, meaning "unspecified." Operation-level
+`description` remains excluded — measured too expensive to copy by default (real average 2,442.7
+bytes/operation).
 
 Export refuses a zero-operation contract, refuses when the scan found a global path prefix the
 contract's paths don't reflect (`--allow-unprefixed` overrides), and stamps every document with an
@@ -281,4 +290,7 @@ are not part of the published package — clone this repository directly if you
 
 ## License
 
-MIT — see `LICENSE`.
+Dual-licensed: [AGPL-3.0-or-later](./LICENSE) for open-source use, or a
+commercial license for closed-source/proprietary use without AGPL's
+copyleft obligations. See [`COMMERCIAL-LICENSE.md`](./COMMERCIAL-LICENSE.md)
+for why, and how to obtain one.

package/bin/bskel.mjs

@@ -25,7 +25,7 @@ import { introspectSchema, describeConnectionError } from '../scanners/db/intros
 import { renderScanMarkdown, renderPlanConstraints, renderScanExplain } from '../scanners/render.mjs';
 import { ADAPTERS, LOAD_ERRORS, adapterById } from '../scanners/registry.mjs';
 import { COMMAND_CAPABILITIES, CAPABILITY_SATISFIERS, explainMissingCapability } from '../scanners/capabilities.mjs';
-import { buildContract, selectModule } from '../contracts/emit.mjs';
+import { buildContract, selectModule, CONTRACT_SCHEMA_VERSION } from '../contracts/emit.mjs';
 import { validateEnvelope, operationPayloadSchema } from '../contracts/validate.mjs';
 import { evaluateResolution, loadResolution, saveResolution, requireWarningCode, warningKey, countByCode } from '../contracts/completeness.mjs';
 import { loadPatchApprovals, savePatchApprovals, approvalKey } from '../lib/patch-approvals.mjs';
@@ -836,6 +836,15 @@ function cmdContractEmit(args) {
 	const flags = parseCommand('contract emit', args);
 	if (flags.help) { console.log(renderCommandHelp('contract emit')); process.exit(0); }
 	setContext('contract emit', flags);
+
+	// Real dogfooding finding (Phase 3, Team-IZ/Backend, 2026-08-24): --path-prefix only has any
+	// effect inside buildReconciliation(), which only runs when --openapi-file is also given (see
+	// below) -- passing --path-prefix alone was a silent no-op with zero feedback. Checked before
+	// any repo/gate work so the failure is immediate and doesn't depend on feature/gate state.
+	if (flags['path-prefix'] && !flags['openapi-file']) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--path-prefix only applies when reconciling against a real OpenAPI document -- pass --openapi-file <path> together with it, or drop --path-prefix (the value has no effect on its own).`);
+	}
+
 	const root = requireRepoRoot();
 	requirePreflightPassed(root);
 	requireValidFeatureId(flags.feature);
@@ -962,6 +971,13 @@ function cmdContractEmit(args) {
 					console.log(`openapi: ${s.schema_resolved} request body schema(s) projected, ${s.schema_unresolved} unresolved`);
 					console.log(`openapi: ${s.response_schema_resolved} response + ${s.error_schema_resolved} error schema(s) projected, ${s.response_schema_unresolved + s.error_schema_unresolved} unresolved`);
 				}
+				// A7: dialect-independent (security/summary/tags) always ran; parameters only when
+				// schema projection was enabled -- printed unconditionally either way, same "just print
+				// the numbers, they may be zero" style as the two lines above.
+				const p = reconciliation.stats;
+				console.log(`openapi: ${p.parameters_copied} operation(s) with parameters copied (${p.parameters_unresolved} partial/unresolved), ${p.security_copied + p.security_public} with security copied, ${p.summary_copied} summaries + ${p.tags_copied} tag sets copied`);
+				// A8: same "just print the numbers" style.
+				console.log(`openapi: ${p.per_status_copied} operation(s) with per-status responses copied, ${p.request_media_types_copied} with non-JSON request media type(s) copied`);
 			}
 		}
 		for (const w of contract.warnings) console.error(`warning[${w.severity}] ${w.code}${w.subject ? ` (${w.subject})` : ''}: ${w.message}`);
@@ -1005,6 +1021,14 @@ function loadContract(root, featureId) {
 		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no contract at ${contractPath} -- run \`bskel contract emit --feature ${featureId}\` first`);
 	}
 	const parsed = JSON.parse(fs.readFileSync(contractPath, 'utf8'));
+	// A7: a targeted pre-check for the single most common way an old contract fails the schema
+	// below -- an `sbf_contract` bump has a real read-time consequence for the first time (S5's
+	// schema validation postdates A2/A3, which had none), so a contract emitted by an older bskel
+	// gets a friendly re-emit instruction instead of a raw ajv dump. Any OTHER schema violation
+	// (hand-edited, corrupted, etc.) still falls through to the generic message below unchanged.
+	if (typeof parsed?.sbf_contract === 'string' && parsed.sbf_contract !== CONTRACT_SCHEMA_VERSION) {
+		fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', `${contractPath}: this contract was emitted by an older bskel (sbf_contract "${parsed.sbf_contract}", expected "${CONTRACT_SCHEMA_VERSION}") -- re-run \`bskel contract emit --feature ${featureId}\` to re-emit it in the current format.`);
+	}
 	// S5 (D-persistence-integrity): validated against schemas/feature-contract.schema.json (the
 	// meta-schema for THIS file's own shape -- not the same as contracts/validate.mjs, which
 	// validates a runtime agent envelope's PAYLOAD against one operation inside an already-valid
@@ -1116,6 +1140,13 @@ function cmdContractExport(args) {
 	if (built.literalStatusStandIn) {
 		console.error('note: --status-codes literal writes `200` for every documented success body. The source contract records no status codes whatsoever, so `200` is a bskel-chosen stand-in, NOT a claim that any of these operations actually returns 200 -- `--status-codes range` (the default) emits the spec-legal `2XX` range key and invents nothing.');
 	}
+	// A7: ONE stderr note, not per-operation -- mixed passthrough coverage can only arise in an
+	// explicitly waived `partial` contract (a `complete` one has 100% coverage by construction, see
+	// D-openapi-passthrough); disclosure, not a new refusal. The exact per-operation map is always in
+	// info.x-bskel-generated.passthrough regardless of whether this note fires.
+	if (built.mixedPassthrough) {
+		console.error(`note: ${built.passthroughWithoutCount} of ${Object.keys(contract.operations).length} operation(s) in this export carry no source-document passthrough (parameters/security/summary/tags) -- see info.x-bskel-generated.passthrough for exactly which ones.`);
+	}
 
 	const rendered = `${JSON.stringify(built.document, null, 2)}\n`;
 	if (flags.out) {

package/contracts/completeness.mjs

@@ -64,6 +64,41 @@ export const WARNING_CODES = Object.freeze({
 	// 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 },
+	// A7: at least one non-path parameter on a matched/adopted operation could not be copied into
+	// sourceParameters -- an unsupported shape ($ref/content/unknown key/cap exceeded), or a schema
+	// inlineSchema() itself could not resolve. WARN, not ERROR: verb/path/body are still correctly
+	// contracted, this is a missed enhancement -- same reasoning as CONTRACT_OPENAPI_SCHEMA_UNRESOLVED.
+	CONTRACT_OPENAPI_PARAMETERS_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	// A7: the operation declared `security` in the source document, but at least one named scheme
+	// could not be resolved against components.securitySchemes (or the requirement itself was
+	// malformed/oversized) -- the WHOLE security value is dropped for that operation rather than a
+	// partial/dangling one, and this warns about it. Deliberately a SEPARATE code from
+	// CONTRACT_OPENAPI_PARAMETERS_UNRESOLVED (same operation, same subject, unrelated failure) --
+	// same "a waiver for one must never silently cover the other" reasoning D-openapi-response-schema
+	// already established for the response/error split. WARN: omitting security is still honest
+	// ("unspecified"), just less specific than the source document actually was.
+	CONTRACT_OPENAPI_SECURITY_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
+	// Real dogfooding finding (Phase 3, Team-IZ/Backend, 2026-08-24): A1 §7's `path_prefix_signals`
+	// were only ever consulted at `contract export` time (A6's own refusal, contracts/export.mjs's
+	// unreflectedPathPrefixes()) -- a module with an unaddressed global prefix signal could still
+	// classify as `complete` at `contract emit` time, which is exactly backwards: the paths ARE
+	// wrong, `contract export` just happens to independently catch it before publishing. ERROR (not
+	// WARN) for the same reason CONTRACT_OPENAPI_DRIFT is ERROR: a wrong path is a correctness
+	// defect, not a missed enhancement. Waivable so a false-positive signal (see --allow-unprefixed's
+	// own escape hatch) doesn't permanently block a module it genuinely doesn't apply to.
+	CONTRACT_UNREFLECTED_PATH_PREFIX: { severity: SEVERITY.ERROR, waivable: true },
+	// A8: the operation's request body declared a non-JSON media type (e.g. multipart/form-data)
+	// whose schema could not be fully projected -- the media type name is still recorded, its
+	// shape is not. Deliberately a SEPARATE code from CONTRACT_OPENAPI_SCHEMA_UNRESOLVED (the
+	// application/json-body code) -- the two can co-occur on one operation, and a shared code
+	// would let a waiver for one silently cover the other, same reasoning D-openapi-response-schema
+	// established for its own response/error split. WARN: verb/path/the JSON body (if any) stay
+	// correctly contracted, this is a missed enhancement. No equivalent code exists for per-status
+	// responses -- that failure mode is not independent of A3's own response/error unresolved
+	// codes (both walk the same responses map through the same inlineSchema() at the same cap), so
+	// it reuses CONTRACT_OPENAPI_RESPONSE_SCHEMA_UNRESOLVED/CONTRACT_OPENAPI_ERROR_SCHEMA_UNRESOLVED
+	// unchanged -- see D-openapi-per-status.
+	CONTRACT_OPENAPI_REQUEST_MEDIA_TYPE_UNRESOLVED: { severity: SEVERITY.WARN, waivable: true },
 });
 
 export const WARNING_CODE_NAMES = Object.freeze(Object.keys(WARNING_CODES));

package/contracts/emit.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { makeWarning, classifyContract } from './completeness.mjs';
 import { findMethodParams } from '../scanners/adapters/_java-spring-analyzer.mjs';
+import { pathPrefixCandidates, unreflectedPathPrefixes } from './export.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
@@ -14,6 +15,14 @@ import { findMethodParams } from '../scanners/adapters/_java-spring-analyzer.mjs
 // 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}$';
 
+// A7/A8: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
+// const -- bin/bskel.mjs's loadContract() imports this too, so the friendly "re-emit with the
+// current bskel" message and the value actually written here cannot drift apart. Bumped "5" -> "6"
+// for this item (sourceResponses/sourceRequestBody) -- cheap this time: the friendly re-emit
+// pre-check in loadContract() needed zero code change, it already compares against this imported
+// constant -- see D-openapi-per-status.
+export const CONTRACT_SCHEMA_VERSION = '6';
+
 function pathParamsSchema(routePath) {
 	const params = [...routePath.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
 	const properties = {};
@@ -101,6 +110,18 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 				let responseSchemaUnresolvedReason = null;
 				let errorSchema = null;
 				let errorSchemaUnresolvedReason = null;
+				// A7: same matched/adopted-only discipline as A2/A3's fields above -- stays null for
+				// every other kind.
+				let sourceParameters = null;
+				let parametersUnresolved = null;
+				let sourceSecurity = null;
+				let securityUnresolvedReason = null;
+				let sourceSummary = null;
+				let sourceTags = null;
+				// A8: same discipline, for the two new passthrough fields.
+				let sourceResponses = null;
+				let sourceRequestBody = null;
+				let requestMediaTypesUnresolvedReason = null;
 
 				if (res) {
 					switch (res.kind) {
@@ -118,6 +139,15 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							responseSchemaUnresolvedReason = res.responseSchemaUnresolvedReason ?? null;
 							errorSchema = res.errorSchema ?? null;
 							errorSchemaUnresolvedReason = res.errorSchemaUnresolvedReason ?? null;
+							sourceParameters = res.sourceParameters ?? null;
+							parametersUnresolved = res.parametersUnresolved ?? null;
+							sourceSecurity = res.sourceSecurity ?? null;
+							securityUnresolvedReason = res.securityUnresolvedReason ?? null;
+							sourceSummary = res.sourceSummary ?? null;
+							sourceTags = res.sourceTags ?? null;
+							sourceResponses = res.sourceResponses ?? null;
+							sourceRequestBody = res.sourceRequestBody ?? null;
+							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? null;
 							break;
 						case 'adopted':
 							// No @Operation(operationId=...) in source at all -- the id itself comes from
@@ -135,6 +165,15 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 							responseSchemaUnresolvedReason = res.responseSchemaUnresolvedReason ?? null;
 							errorSchema = res.errorSchema ?? null;
 							errorSchemaUnresolvedReason = res.errorSchemaUnresolvedReason ?? null;
+							sourceParameters = res.sourceParameters ?? null;
+							parametersUnresolved = res.parametersUnresolved ?? null;
+							sourceSecurity = res.sourceSecurity ?? null;
+							securityUnresolvedReason = res.securityUnresolvedReason ?? null;
+							sourceSummary = res.sourceSummary ?? null;
+							sourceTags = res.sourceTags ?? null;
+							sourceResponses = res.sourceResponses ?? null;
+							sourceRequestBody = res.sourceRequestBody ?? null;
+							requestMediaTypesUnresolvedReason = res.requestMediaTypesUnresolvedReason ?? 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`,
@@ -241,18 +280,64 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 						detail: { reason: errorSchemaUnresolvedReason, verb, path: route, operationId },
 					}));
 				}
+				// A7: at least one non-path parameter on this matched/adopted operation could not be
+				// copied verbatim -- an unsupported parameter shape ($ref/content/unknown key/cap
+				// exceeded) or a schema inlineSchema() itself could not resolve. One warning per
+				// operation (not per parameter), same "subject is the operationId" shape as the schema-
+				// unresolved codes above -- the message enumerates every individual failure.
+				if (parametersUnresolved) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_PARAMETERS_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) has ${parametersUnresolved.length} parameter(s) that could not be copied from the source document: ${parametersUnresolved.map((p) => `${p.in ?? '?'} "${p.name ?? '?'}" (${p.reason})`).join(', ')}`,
+						detail: { verb, path: route, operationId, unresolved: parametersUnresolved },
+					}));
+				}
+				// A7: the operation declared `security` in the source document, but at least one named
+				// scheme could not be resolved against components.securitySchemes (or the requirement
+				// itself was malformed/oversized) -- the WHOLE security value is dropped for this
+				// operation, never a dangling reference (see contracts/openapi.mjs's applySecurity).
+				if (securityUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_SECURITY_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) declares a security requirement that could not be copied (${securityUnresolvedReason}) -- security stays unrepresented for this operation, same as before --openapi-file`,
+						detail: { reason: securityUnresolvedReason, verb, path: route, operationId },
+					}));
+				}
+				// A8: the operation's request body declared a non-application/json media type (e.g.
+				// multipart/form-data) whose schema could not be fully projected -- the media type
+				// itself is still recorded in sourceRequestBody (see contracts/openapi.mjs's
+				// applyRequestMediaTypes), only its shape is missing. A SEPARATE code from
+				// CONTRACT_OPENAPI_SCHEMA_UNRESOLVED (the application/json body's own code): the two
+				// CAN co-occur on one operation (an endpoint legally accepting both application/json
+				// and multipart/form-data), and warningKey is {code, subject=operationId} -- sharing a
+				// code would let a waiver for one silently cover the other, the same reasoning
+				// D-openapi-response-schema's response/error split already established and A7 reused
+				// for parameters/security.
+				if (requestMediaTypesUnresolvedReason) {
+					warnings.push(makeWarning('CONTRACT_OPENAPI_REQUEST_MEDIA_TYPE_UNRESOLVED', {
+						subject: operationId,
+						message: `operationId "${operationId}" (${verb} ${route}) declares a non-JSON request media type that could not be fully copied (${requestMediaTypesUnresolvedReason}) -- the media type name is still recorded where possible, its shape is not`,
+						detail: { reason: requestMediaTypesUnresolvedReason, 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.
+					// A2/A3/A7: omitted entirely (not null/false) when there's nothing to project/copy --
+					// keeps `openapi:null` (and any operation that isn't matched/adopted) byte-identical
+					// to pre-A2/A3/A7 output, the same guarantee A1 established for its own fields.
 					...(requestBodySchema ? { requestBodySchema, requestBodyRequired } : {}),
 					...(responseSchema ? { responseSchema } : {}),
 					...(errorSchema ? { errorSchema } : {}),
+					...(sourceParameters ? { sourceParameters } : {}),
+					...(sourceSecurity ? { sourceSecurity } : {}),
+					...(sourceSummary ? { sourceSummary } : {}),
+					...(sourceTags ? { sourceTags } : {}),
+					...(sourceResponses ? { sourceResponses } : {}),
+					...(sourceRequestBody ? { sourceRequestBody } : {}),
 				};
 			}
 		}
@@ -267,19 +352,44 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 		}));
 	}
 
+	// Real dogfooding finding (Phase 3, Team-IZ/Backend, 2026-08-24): reuses A6's own
+	// pathPrefixCandidates()/unreflectedPathPrefixes() (contracts/export.mjs) rather than
+	// re-deriving prefix detection here -- this is the SAME check `contract export` already runs,
+	// just moved earlier so `completeness` itself reflects it instead of only being caught later at
+	// export time. Runs against the final `operations` (post-reconciliation, if any) rather than
+	// gating on `!openapi`, because a partially-reconciled contract (matched paths corrected, a
+	// drift/missing one left at its uncorrected scan path) is exactly the mixed case
+	// unreflectedPathPrefixes() itself warns is no safer than a wholly-unprefixed contract.
+	for (const prefix of unreflectedPathPrefixes({ operations }, pathPrefixCandidates(scanReport.path_prefix_signals))) {
+		warnings.push(makeWarning('CONTRACT_UNREFLECTED_PATH_PREFIX', {
+			subject: prefix,
+			message: `the scan found a global path-prefix signal (${prefix}) that this contract's operation paths do not reflect -- \`contract export\` already refuses to publish this by default (see D-openapi-export); this warning surfaces the same issue at \`contract emit\` time instead of only at export time. Re-run with --openapi-file to correct the paths, or waive if this signal genuinely does not apply to this module.`,
+			detail: { prefix },
+		}));
+	}
+
 	const completeness = {
 		status: classifyContract({ operations, warnings }),
 		operation_count: Object.keys(operations).length,
 		endpoint_count: endpointCount,
 	};
 
+	// A7: only schemes actually referenced by at least one operation's COPIED sourceSecurity
+	// requirement anywhere in this contract -- omitted entirely (not {}) when openapi is null or no
+	// operation ended up with a resolvable security requirement, same byte-identity discipline as
+	// every other openapi-derived field.
+	const sourceSecuritySchemes = openapi && openapi.sourceSecuritySchemes && openapi.sourceSecuritySchemes.size > 0
+		? Object.fromEntries(openapi.sourceSecuritySchemes)
+		: null;
+
 	return {
-		sbf_contract: '4',
+		sbf_contract: CONTRACT_SCHEMA_VERSION,
 		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' },
+		...(sourceSecuritySchemes ? { sourceSecuritySchemes } : {}),
 		operations,
 		warnings,
 		completeness,