backend-skeleton 1.0.0-beta.6 → 1.0.0-beta.8

package/handles/providers/java-spring/emit.mjs

@@ -104,6 +104,22 @@ function writeUnit(target, content) {
 	fs.writeFileSync(target, content);
 }
 
+// O3 follow-up (D-handle-registry-enforcement, "Continued"): a coarse, per-resource, emit-time,
+// source-only proxy for "has this resource's own create-flow ever been wired to register a
+// HandleRegistry row" -- see DECISIONS.md for why this stays static and never queries a live
+// target-app database (that's a separate, harder, still-open gap, not this). Requires the opening
+// "(" so a bare comment/javadoc mention of the annotation's name (RecordHandleSnapshot.java.tmpl's
+// own javadoc has one) doesn't count as "found". Deliberately biased toward a false-positive
+// WARNING (nagging a resource that's actually registered some other way, e.g. a hand-written
+// HandleService.register() call with no annotation) over a false-negative SILENCE (saying nothing
+// about a resource that really can never bootstrap its first PATCH) -- see DECISIONS.md.
+const RECORD_HANDLE_SNAPSHOT_RE = /@RecordHandleSnapshot\s*\(/;
+
+function hasRecordHandleSnapshot(serviceFilePath) {
+	if (!serviceFilePath || !fs.existsSync(serviceFilePath)) return false;
+	return RECORD_HANDLE_SNAPSHOT_RE.test(fs.readFileSync(serviceFilePath, 'utf8'));
+}
+
 // See DECISIONS.md D-handles-ownership for the full design; the conflict/manifest/force/orphan
 // logic itself now lives in handles/_engine.mjs (D-handles-providers, G4) -- this function's job
 // is purely to compute java-spring's own render/paths and hand them to emitUnits(). `force`/
@@ -249,15 +265,26 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 	if (computeDiff && migrationAction === 'update') migrationActionEntry.diff = unifiedDiff(migrationRelPath, migrationDiskContent, migrationContent);
 	result.actions.push(migrationActionEntry);
 
-	return {
-		...result,
-		postEmitNotes: [
-			'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
-			// O4 (D-handle-lifecycle): HandleAspect.java only actually intercepts anything once a
-			// human applies @RecordHandleSnapshot to a real service method AND the target repo has
-			// this dependency -- never auto-added to build.gradle, same "review and apply yourself"
-			// boundary as the migration note above.
-			'NOT done automatically: HandleAspect.java requires spring-boot-starter-aop on your own build.gradle classpath (Spring AOP is not enabled by any other starter). Add it yourself before applying @RecordHandleSnapshot to any service method.',
-		],
-	};
+	const postEmitNotes = [
+		'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
+		// O4 (D-handle-lifecycle): HandleAspect.java only actually intercepts anything once a
+		// human applies @RecordHandleSnapshot to a real service method AND the target repo has
+		// this dependency -- never auto-added to build.gradle, same "review and apply yourself"
+		// boundary as the migration note above.
+		'NOT done automatically: HandleAspect.java requires spring-boot-starter-aop on your own build.gradle classpath (Spring AOP is not enabled by any other starter). Add it yourself before applying @RecordHandleSnapshot to any service method.',
+	];
+	// O3 follow-up (D-handle-registry-enforcement, "Continued"): per-resource, conditional on
+	// enforceRegistry actually being on -- see hasRecordHandleSnapshot() above.
+	if (enforceRegistry) {
+		for (const resource of plan.resources) {
+			if (!resource.willGenerateResolver) continue;
+			if (hasRecordHandleSnapshot(resource.service.file)) continue;
+			const relServiceFile = path.relative(repoRoot, resource.service.file);
+			postEmitNotes.push(
+				`${resource.type}: --enforce-registry is on, but no @RecordHandleSnapshot(...) was found anywhere in ${relServiceFile} -- this resource may never get its first HandleRegistry row, and every fetch()/patch() call against it will 404 until something registers it. Apply @RecordHandleSnapshot to ${resource.service.serviceType}'s own create-flow method (or call HandleService.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`,
+			);
+		}
+	}
+
+	return { ...result, postEmitNotes };
 }

package/handles/providers/python-fastapi/emit.mjs

@@ -40,6 +40,16 @@ function dottedModulePath(file, importRoot) {
 	return rel.split(path.sep).join('.');
 }
 
+// O3 follow-up (D-handle-registry-enforcement, "Continued"): same static, coarse, per-resource
+// presence check as java-spring's own -- see that file's identical comment for the false-
+// positive/false-negative bias reasoning (unchanged here).
+const RECORD_SNAPSHOT_RE = /@record_snapshot\s*\(/;
+
+function hasRecordSnapshot(routeFilePath) {
+	if (!routeFilePath || !fs.existsSync(routeFilePath)) return false;
+	return RECORD_SNAPSHOT_RE.test(fs.readFileSync(routeFilePath, 'utf8'));
+}
+
 // See DECISIONS.md D-handles-providers. G4 follow-up: migration.sql + a real recover() lifecycle
 // (tables.py/handle_service.py/record_snapshot.py) are now generated, mirroring java-spring's own
 // O4 work -- the EXCLUDED section's original "even Java hasn't got O4" reasoning is stale, see
@@ -197,5 +207,18 @@ export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter =
 	// and apply yourself" boundary as the migration note above.
 	postEmitNotes.push('NOT done automatically: applying @record_snapshot (handles/record_snapshot.py) to any of your own service functions. Codegen never touches existing business logic files.');
 
+	// O3 follow-up (D-handle-registry-enforcement, "Continued"): per-resource, conditional on
+	// enforceRegistry.
+	if (enforceRegistry) {
+		for (const resource of plan.resources) {
+			if (!resource.willGenerateResolver) continue;
+			if (hasRecordSnapshot(resource.fetchRoute.file)) continue;
+			const relRouteFile = path.relative(repoRoot, resource.fetchRoute.file);
+			postEmitNotes.push(
+				`${resource.type}: --enforce-registry is on, but no @record_snapshot(...) was found anywhere in ${relRouteFile} -- this resource may never get its first registry row, and every fetch/patch call against it will 404 until something registers it. Apply @record_snapshot to its own create-flow route function (or call handle_service.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`,
+			);
+		}
+	}
+
 	return { ...result, postEmitNotes };
 }

package/lib/gate-definitions.mjs

@@ -196,9 +196,10 @@ export const GATE_DEFINITIONS = Object.freeze({
 			};
 			const moduleName = report?.disposition?.module ?? report?.related_modules?.[0]?.module;
 			const mod = report?.related_modules?.find((m) => m.module === moduleName);
-			// DTOs deliberately excluded -- scanJavaSpring() stores them as bare class-name
-			// strings today, no `.file` field (Part 1's own named, out-of-scope gap).
-			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? [])]) {
+			// DTOs now included -- every adapter pushes {className, file} objects for dtos, the
+			// same shape controllers/entities/enums already use. See D-gate-precision "Continued
+			// (part 3)" in DECISIONS.md.
+			for (const item of [...(mod?.controllers ?? []), ...(mod?.entities ?? []), ...(mod?.enums ?? []), ...(mod?.dtos ?? [])]) {
 				if (!item.file) continue;
 				// related_modules[].{controllers,entities,enums}[].file are stored ABSOLUTE
 				// (unlike Part 1's own repo-relative files_read) -- confirmed live against a real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",

package/scanners/adapters/java-spring.mjs

@@ -257,7 +257,7 @@ export function scanJavaSpring(repoRoot) {
 			if (en) moduleEntry(mod).enums.push(en);
 		}
 		if (mod && file.includes(`${path.sep}presentation${path.sep}dto${path.sep}`)) {
-			moduleEntry(mod).dtos.push(path.basename(file, '.java'));
+			moduleEntry(mod).dtos.push({ className: path.basename(file, '.java'), file });
 		}
 	}
 

package/scanners/adapters/python-fastapi.mjs

@@ -160,6 +160,42 @@ function extractTableEntities(text, file) {
 	return entities;
 }
 
+// D-gate-precision (Continued, part 3): the DTO/request-response-shape counterpart to
+// extractTableEntities() -- a SQLModel-family class WITHOUT `table=True` (`ItemBase(SQLModel)`,
+// `ItemPublic(ItemBase)`, `ItemCreate(ItemBase)`), the real convention confirmed against this
+// project's own committed fixture and the real oracle it mirrors (fastapi/full-stack-fastapi-
+// template). Deliberately a separate function, not merged into extractTableEntities() -- zero
+// regression risk to existing entity extraction. One narrow, named exclusion beyond "not
+// table=True": `class Settings(BaseSettings):` (pydantic-settings' own well-known config-class
+// base) is not API request/response surface -- excluding it is a concrete, common false-positive
+// fix, not a hypothetical one. No broader positive allowlist (e.g. requiring `SQLModel`/`BaseModel`
+// literally in the base list) is layered on top: the real oracle's own `ItemPublic(ItemBase)` shape
+// (a DTO extending ANOTHER DTO, not SQLModel/BaseModel directly) would fail such an allowlist,
+// trading a bounded, low-cost false positive for a worse false negative (a missed real DTO change)
+// -- the same "prefer false positive over false negative" call this exact drift-detection mechanism
+// already makes for controllers/entities/enums.
+function extractDtoClasses(text, file) {
+	const dtos = [];
+	for (const m of text.matchAll(CLASS_RE)) {
+		if (/table\s*=\s*True/.test(m[2])) continue; // has its own entity extractor above
+		if (/\bBaseSettings\b/.test(m[2])) continue; // pydantic-settings config, not API surface
+		dtos.push({ className: m[1], file, line: lineNumberAt(text, m.index) });
+	}
+	return dtos;
+}
+
+// Bounded, non-exhaustive allowlist of DTO class-name suffixes -- validated against this project's
+// own committed fixture (ItemBase/ItemCreate/ItemPublic/ItemsPublic, all correctly stripping to
+// "item"/"items", the real "items" module). A DTO whose class name uses a different convention
+// (Schema, Payload, Out) lands in the `_dtos` bucket below instead -- named, accepted, untracked,
+// same shape as an unmatched entity's `_models` fallback. Purely additive to extend: a future
+// suffix added here can only ever gain coverage, never lose it.
+const KNOWN_DTO_SUFFIXES = ['Base', 'Create', 'Update', 'Public', 'Read', 'Response', 'Request', 'In', 'Out'];
+function stripKnownDtoSuffix(className) {
+	const suffix = KNOWN_DTO_SUFFIXES.find((s) => className.length > s.length && className.endsWith(s));
+	return suffix ? className.slice(0, -suffix.length) : className;
+}
+
 // A1 §7 equivalent for FastAPI: `include_router(router, prefix=X)` applies a prefix the
 // per-router-file scan above cannot see (each file is read independently, with no idea another
 // file mounts it under a further prefix). Two-step resolution when X is a variable/attribute
@@ -224,6 +260,7 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 	};
 
 	const allEntities = [];
+	const allDtos = [];
 	for (const file of files) {
 		const text = fs.readFileSync(file, 'utf8');
 
@@ -240,6 +277,7 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 		}
 
 		allEntities.push(...extractTableEntities(text, file));
+		allDtos.push(...extractDtoClasses(text, file));
 	}
 
 	// Entity -> module assignment: this repo's real layout has no domain/<module>/ folder (all
@@ -255,6 +293,18 @@ export function scanPythonFastApi(repoRoot, projectRoot) {
 		moduleEntry(targetModule ?? '_models').entities.push(entity);
 	}
 
+	// DTO -> module assignment: same narrow name-match as entities, suffix-stripped first via the
+	// bounded allowlist above (ItemPublic -> "item" -> matches "items"). Unmatched (unlisted suffix,
+	// or no correlation at all) lands in a separate `_dtos` bucket -- not merged into entities' own
+	// `_models` -- and is therefore NOT tracked by any feature's contract gate; a real, named,
+	// accepted limitation (see D-gate-precision "Continued (part 3)" in DECISIONS.md).
+	for (const dto of allDtos) {
+		const lower = stripKnownDtoSuffix(dto.className).toLowerCase();
+		const candidates = new Set([lower, `${lower}s`]);
+		const targetModule = [...modules.keys()].find((name) => candidates.has(name));
+		moduleEntry(targetModule ?? '_dtos').dtos.push(dto);
+	}
+
 	return {
 		modules: [...modules.values()],
 		pathPrefixSignals: extractIncludeRouterPrefixSignals(repoRoot, files),

package/scanners/adapters/typescript-express.mjs

@@ -32,6 +32,15 @@ const VERB_CALL_RE = new RegExp(`\\brouter\\.(${VERBS.join('|')})\\s*\\(`, 'gi')
 const ROUTER_USE_RE = /\brouter\.use\s*\(/g;
 const ENTITY_CLASS_RE = /@Entity\s*\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)\s*\n?\s*export\s+class\s+(\w+)/g;
 
+// D-gate-precision (Continued, part 3): a pure PATH-CONVENTION heuristic, mirroring java-spring's
+// own identical solution to the identical problem (`.../presentation/dto/`) rather than inventing
+// syntactic DTO detection this ecosystem doesn't have a reliable single marker for -- plain
+// `interface`, `type` aliases, class-validator classes, Zod schemas, and undecorated classes are
+// all real conventions, and this adapter's own `api.request-shape: false` capability already names
+// why no such regex is attempted here. One entry per FILE under a `dto/` directory, not per
+// exported symbol -- same file-level granularity java's own DTO tracking already settled for.
+const DTO_DIR_SEGMENT = `${path.sep}dto${path.sep}`;
+
 // Two independent signals required, mirroring java-spring's "build file AND src layout" /
 // python-fastapi's "dependency declared AND source-confirmed" combined bar: (a) package.json
 // declares express, (b) at least one .ts file actually imports Router from 'express' and calls
@@ -220,6 +229,7 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 	};
 
 	const allEntities = [];
+	const allDtos = [];
 	for (const file of files) {
 		const text = fileTexts.get(file);
 		// G6: `\bRouter\s*\(` -- see detectTypeScriptExpressRoot above. Same widening for the same
@@ -235,6 +245,9 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 				moduleEntry(moduleName).controllers.push({ className, basePath: prefix, operationIds: [], endpoints, file });
 			}
 		}
+		if (file.includes(DTO_DIR_SEGMENT)) {
+			allDtos.push({ className: path.basename(file, '.ts'), file }); // no `line` -- path-based, no content parsed
+		}
 		allEntities.push(...extractTableEntities(text, file));
 	}
 
@@ -248,6 +261,19 @@ export function scanTypeScriptExpress(repoRoot, projectRoot) {
 		moduleEntry(targetModule ?? '_models').entities.push(entity);
 	}
 
+	// DTO -> module assignment: same narrow name-match as entities, with a trailing literal
+	// `Dto`/`DTO` stripped first -- the one near-definitional, cross-project-safe TS DTO marker (a
+	// DTO's own name almost universally contains it). An action-prefixed name (`CreateUserDto.ts`,
+	// a common real-world shape) still will NOT exact-match after stripping ("createuser" !=
+	// "user"/"users") and lands in `_dtos` -- honestly uncovered rather than guessed at (see
+	// D-gate-precision "Continued (part 3)" in DECISIONS.md).
+	for (const dto of allDtos) {
+		const lower = dto.className.replace(/Dto$/i, '').toLowerCase();
+		const candidates = new Set([lower, `${lower}s`]);
+		const targetModule = [...modules.keys()].find((name) => candidates.has(name));
+		moduleEntry(targetModule ?? '_dtos').dtos.push(dto);
+	}
+
 	return {
 		modules: [...modules.values()],
 		pathPrefixSignals: [],

package/scanners/render.mjs

@@ -70,7 +70,7 @@ export function renderScanMarkdown(report) {
 				lines.push(`- Enum \`${en.name}\`: ${en.constants.join(', ')}`);
 			}
 			if (mod.dtos.length > 0) {
-				lines.push(`- DTOs: ${mod.dtos.join(', ')}`);
+				lines.push(`- DTOs: ${mod.dtos.map((d) => d.className).join(', ')}`);
 			}
 			lines.push('');
 		}

package/schemas/scan-report.schema.json

@@ -25,7 +25,7 @@
           "controllers": { "type": "array" },
           "entities": { "type": "array" },
           "enums": { "type": "array" },
-          "dtos": { "type": "array", "items": { "type": "string" } },
+          "dtos": { "type": "array" },
           "evidence": {
             "description": "D-scanner-evidence: every {signal, term, value, weight, file, line} match that contributed to `score` -- capped per signal type AT COLLECTION TIME (not filtered afterward), so this array's size stays bounded regardless of repo size. See `capped_signals` for which signal types actually hit that cap.",
             "type": "array",