backend-skeleton 1.0.0 → 1.1.1

package/handles/providers/typescript-express/templates/registry.ts.tmpl

@@ -1,20 +1,29 @@
 // Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
 //
 // In-process registry mapping a handle `type` string to its resolver instance -- deliberately NOT
-// a database table. This 1st-slice scope carries no recover()/snapshot lifecycle equivalent (no
-// sbf_handle/sbf_handle_snapshot table) -- mirrors java-spring/python-fastapi's own pre-O4/
-// pre-follow-up state, not a gap specific to this provider. See D-typescript-express-provider in
-// DECISIONS.md.
+// a database table (that's HandleRegistry in handleEntities.ts, an unrelated concept that only
+// shares the word "registry" -- see that file's own header). See D-typescript-express-provider /
+// D-typescript-express-registry-parity in DECISIONS.md.
 
 // Unlike the Python provider's ResourceResolver (which threads a per-request SQLAlchemy `session`
-// through every method, matching FastAPI's own dependency-injection convention), this interface
-// takes NO dataSource/session parameter at all -- TypeORM's `DataSource` is an app-wide singleton
-// instantiated once at startup (`export const AppDataSource = new DataSource(...)`), not a
-// per-request-injected object the way SQLAlchemy's `Session` is. Each generated resolver imports
-// its own DataSource reference directly (see resolver.ts.tmpl) -- a genuine simplification from
-// this ecosystem's own real pattern, not an arbitrary deviation from the Python provider's shape.
+// argument through every METHOD CALL, matching FastAPI's own dependency-injection convention),
+// none of fetch()/checkAccess()/patchField()/toPublic() below take a dataSource/session parameter
+// -- TypeORM's `DataSource` is an app-wide singleton instantiated once at startup (`export const
+// AppDataSource = new DataSource(...)`), not a per-request-injected object the way SQLAlchemy's
+// `Session` is. Each generated resolver still imports its own DataSource reference directly (see
+// resolver.ts.tmpl) and exposes it as the `dataSource` FIELD below (not a method parameter) --
+// D-typescript-express-registry-parity's own infrastructure (recordSnapshotWrapper.ts, router.ts's
+// recover()/enforcement logic) reads it from there rather than needing a separate reference of
+// its own. `featureUid`/`contractRef` are the other two live-derived values
+// D-resolver-policy-split exists for (see <Type>Policy.ts.tmpl). All three fields are read by
+// that infrastructure only, never by fetch()/checkAccess()/patchField()/toPublic().
+import type { DataSource } from 'typeorm';
+
 export interface ResourceResolver {
   type: string;
+  featureUid: string;
+  contractRef: string;
+  dataSource: DataSource;
   fetch(resourceUid: string): Promise<unknown>;
   checkAccess(obj: unknown): void;
   patchField(obj: unknown, pointer: string, value: unknown): void;

package/handles/providers/typescript-express/templates/resolver.ts.tmpl

@@ -24,9 +24,22 @@
 import { {{MODEL}} } from '{{MODEL_IMPORT_PATH}}';
 import { {{DATA_SOURCE_NAME}} } from '{{DATA_SOURCE_IMPORT_PATH}}';
 import { register, HandleAccessDeniedError, HandleNotImplementedError, type ResourceResolver } from '../registry';
+import { {{RESOURCE_TYPE}}Policy } from './{{RESOURCE_TYPE_CAMEL}}Policy';
 
 const {{RESOURCE_TYPE}}Resolver: ResourceResolver = {
+  ...{{RESOURCE_TYPE}}Policy,
+  // Redundant with the spread above (Policy already carries `type`) -- restated explicitly so
+  // this file's own orphan-scan (emit.mjs's resourceTypeOf(), a content-read, not a filename
+  // guess) can still find a real `type: 'X'` field without needing to open the sibling Policy
+  // file too. A literal, not derived from anything -- if this and the Policy value ever
+  // disagreed, the object-literal spread order means this line always wins at runtime, matching
+  // what the orphan scan would read.
   type: '{{RESOURCE_TYPE}}',
+  // D-typescript-express-registry-parity: exposed here, not in the policy file -- this is an
+  // OBJECT REFERENCE (the same app-wide DataSource singleton fetch() already imports below), not
+  // a plain regenerable string value the way contractRef/featureUid are. Read by recordSnapshotWrapper.ts
+  // and router.ts's recover()/enforcement logic so they never need their own separate DataSource.
+  dataSource: {{DATA_SOURCE_NAME}},
 
   async fetch(resourceUid: string): Promise<unknown> {
     return {{DATA_SOURCE_NAME}}.getRepository({{MODEL}}).findOne({ where: { {{ID_FIELD}}: resourceUid } });

package/handles/providers/typescript-express/templates/resolverPolicy.ts.tmpl

@@ -0,0 +1,20 @@
+// Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+//
+// D-typescript-express-registry-parity (mirrors java-spring's ResourceResolverPolicyStub.java.tmpl
+// / D-resolver-policy-split): machine-owned companion to {{RESOURCE_TYPE}}Resolver -- every value
+// here is derived directly from the current contract/scan and is safe to regenerate on every
+// `bskel handles emit` run, even when the sibling resolver file has diverged (e.g. a hand-finished
+// patchField()) and is refusing to regenerate. This is a SEPARATE file, not a section of
+// resolver.ts, so a hand-edit to checkAccess()/patchField() there never blocks a live-derived
+// value here (contractRef/featureUid) from updating -- both used to live in one file for this
+// provider's own 1st slice, and classifyFile()'s conflict detection is file-level.
+//
+// Nothing here is ever meant to be hand-edited -- to change one of these values, change the
+// SOURCE it was derived from (the feature contract, etc.) and re-run `bskel handles emit`. A
+// hand-edit here will be silently overwritten on the next run, by design (see the "provably
+// untouched -> safe to regenerate" path in lib/handles-manifest.mjs's classifyFile()).
+export const {{RESOURCE_TYPE}}Policy = {
+  type: '{{RESOURCE_TYPE}}',
+  contractRef: '{{CONTRACT_REF}}',
+  featureUid: '{{FEATURE_UID}}',
+} as const;

package/handles/providers/typescript-express/templates/router.ts.tmpl

@@ -9,8 +9,38 @@
 // against still pins this version) does NOT auto-catch a rejected Promise inside an async route
 // handler the way Express 5 does, and that can't be assumed of an arbitrary target app either way.
 import { Router, type Request, type Response } from 'express';
-import { decodeHandle, resolveJsonPointer } from './codec';
-import { resolverFor, HandleAccessDeniedError, HandleNotImplementedError } from './registry';
+import { decodeHandle, resolveJsonPointer, deriveHandleUid, type DecodedHandle } from './codec';
+import { resolverFor, HandleAccessDeniedError, HandleNotImplementedError, type ResourceResolver } from './registry';
+import { HandleRegistry, HandleSnapshot } from './handleEntities';
+
+// O3 (D-handle-registry-enforcement, part 2 of 2), D-typescript-express-registry-parity: opt-in,
+// defaults false -- baked in at `bskel handles emit --enforce-registry on` time, matching every
+// other per-target-repo codegen constant this project bakes in (e.g. featureUid/contractRef on
+// each resolver). `registerHandle()` is only ever called by generated code wrapped with
+// recordSnapshot(...) (an app that opted in) or a target app's own hand-written calls -- an app
+// that mints handles through neither path gets fully working fetch()/patch() with zero registry
+// involvement today; flipping this on unconditionally would 404 every one of their existing
+// handles. Stays a deliberate, informed choice a target app's own maintainer makes.
+const ENFORCE_REGISTRY = {{ENFORCE_REGISTRY}};
+
+export class HandleNotRegisteredError extends Error {}
+
+// D-handle-registry-enforcement's own bootstrapping-trap fix, ported here from day one (not
+// rediscovered): always derives and looks up the PARENT RESOURCE's own row (kind='r',
+// pointer=null), regardless of the requested handle's own kind/pointer -- `resourceType` is still
+// exactly cross-checked (the real D-security-9 protection: an attacker-controlled `type` can't
+// claim a different, more sensitive resource's registration by UUID coincidence), but kind/pointer
+// are not, since every real registration in this system is resource-level. Structurally correct,
+// not a workaround: revocation is inherently a resource-level concept, matching how fetch()'s own
+// kind=f path already fetches the WHOLE resource and narrows client-side with a pointer.
+async function requireRegisteredOrThrow(resolver: ResourceResolver, decoded: DecodedHandle): Promise<HandleRegistry> {
+  const resourceHandleUid = deriveHandleUid('r', decoded.type, decoded.uuid, null);
+  const registry = await resolver.dataSource.getRepository(HandleRegistry).findOne({ where: { handleUid: resourceHandleUid } });
+  if (registry == null || registry.resourceType !== decoded.type || registry.revokedAt != null) {
+    throw new HandleNotRegisteredError('no active registration for this handle');
+  }
+  return registry;
+}
 
 export const router = Router();
 
@@ -38,6 +68,9 @@ router.get('/handles/:handle', async (req: Request, res: Response) => {
   }
 
   try {
+    if (ENFORCE_REGISTRY) {
+      await requireRegisteredOrThrow(resolver, decoded);
+    }
     const obj = await resolver.fetch(decoded.uuid);
     if (obj == null) {
       res.status(404).json({ detail: 'resource not found' });
@@ -65,6 +98,10 @@ router.get('/handles/:handle', async (req: Request, res: Response) => {
       res.status(403).json({ detail: exc.message });
       return;
     }
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
     throw exc;
   }
 });
@@ -100,6 +137,9 @@ router.patch('/handles/:handle', async (req: Request, res: Response) => {
   }
 
   try {
+    if (ENFORCE_REGISTRY) {
+      await requireRegisteredOrThrow(resolver, decoded);
+    }
     const obj = await resolver.fetch(decoded.uuid);
     if (obj == null) {
       res.status(404).json({ detail: 'resource not found' });
@@ -117,6 +157,77 @@ router.patch('/handles/:handle', async (req: Request, res: Response) => {
       res.status(501).json({ detail: exc.message });
       return;
     }
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
+    throw exc;
+  }
+});
+
+// D-handle-lifecycle (O4), D-typescript-express-registry-parity: recover() structurally REQUIRES
+// a registry row to find a snapshot's own primary key -- there is no "unenforced" mode for it,
+// unlike fetch()/patch() above. Always calls the same shared cross-check those two now optionally
+// call, so the two paths can never silently drift apart. Unlike fetch()/patch(), this does NOT
+// call resolver.fetch() first -- recovering history of a since-deleted resource is legitimate, so
+// this never requires the live resource to still exist.
+router.get('/handles/:handle/recover', async (req: Request, res: Response) => {
+  if (typeof req.params.handle !== 'string') {
+    res.status(400).json({ detail: 'malformed handle path segment' });
+    return;
+  }
+  let decoded;
+  try {
+    decoded = decodeHandle(req.params.handle);
+  } catch (exc) {
+    res.status(400).json({ detail: (exc as Error).message });
+    return;
+  }
+
+  const resolver = resolverFor(decoded.type);
+  if (!resolver) {
+    res.status(404).json({ detail: `no resolver registered for handle type "${decoded.type}"` });
+    return;
+  }
+
+  let registry: HandleRegistry;
+  try {
+    registry = await requireRegisteredOrThrow(resolver, decoded);
+  } catch (exc) {
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
     throw exc;
   }
+
+  const atParam = typeof req.query.at === 'string' ? req.query.at : null;
+  const at = atParam != null ? new Date(atParam) : null;
+  if (at != null && Number.isNaN(at.getTime())) {
+    res.status(400).json({ detail: `"at" query parameter is not a valid date: "${atParam}"` });
+    return;
+  }
+
+  const qb = resolver.dataSource.getRepository(HandleSnapshot)
+    .createQueryBuilder('snapshot')
+    .where('snapshot.handle_uid = :handleUid', { handleUid: registry.handleUid })
+    .orderBy('snapshot.recorded_at', 'DESC');
+  if (at != null) qb.andWhere('snapshot.recorded_at <= :at', { at });
+  const snapshot = await qb.getOne();
+
+  if (snapshot == null) {
+    res.status(404).json({ detail: `no snapshot recorded for this handle${at != null ? ` at or before ${at.toISOString()}` : ''}` });
+    return;
+  }
+
+  res.status(200).json({
+    handle: req.params.handle,
+    recordedAt: snapshot.recordedAt,
+    operationId: snapshot.operationId,
+    // snapshot.payload is already a native object/array/scalar (a real jsonb column) -- no
+    // manual re-parse step exists here for the double-encoding bug Java once had to be possible
+    // in the first place.
+    payload: snapshot.payload,
+    schemaDrift: registry.contractRef !== snapshot.contractHash,
+  });
 });

package/handles/providers/typescript-express.mjs

@@ -9,10 +9,13 @@ export const provider = {
 	id: 'typescript-express',
 	title: 'TypeScript / Express / TypeORM',
 	requiresCapabilities: ['resource.fetch'],
-	// No migration.sql -- this 1st-slice provider generates no schema-owning artifact (no
-	// recover(), no sbf_handle table), matching java-spring/python-fastapi's own pre-O4/
-	// pre-follow-up state, not a gap specific to this provider.
-	outputs: { spec: [] },
+	// D-typescript-express-registry-parity: migration.sql is manifest-tracked now (like every
+	// other provider's, per D-write-safety-phase0), so this declaration is NOT for idempotence
+	// exclusion -- it's lib/verify.mjs's S6 safety net (a `handles ran` check that fires even with
+	// no manifest entry at all, e.g. a `gate force`d handles gate). See java-spring.mjs's own
+	// identical comment for the full reasoning; checkArtifacts() dedupes against the manifest-
+	// based check by path, so this never produces a duplicate once a real manifest entry exists.
+	outputs: { spec: ['handles/migration.sql'] },
 	plan,
 	emit(args) {
 		return emitTypeScriptExpress(args);

package/lib/cli.mjs

@@ -306,11 +306,15 @@ export const COMMANDS = {
 		},
 	},
 	'stack apply': {
-		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--json]',
+		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--json]',
 		options: {
 			choice: { type: 'string', default: null },
 			apply: { type: 'boolean', default: false },
 			port: { type: 'string', default: '8080', numeric: { min: 1, max: 65535 } },
+			// D-write-safety-phase0 (item 2): mirrors handles emit's own --force/--reason exactly --
+			// a file that diverged from what `stack apply` itself last wrote is refused without this.
+			force: { type: 'boolean', default: false },
+			reason: { type: 'string', default: '' },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -359,11 +363,16 @@ export const COMMANDS = {
 	// purpose IS the live query). Reuses `--resource type1,type2`'s exact multi-value convention
 	// from `handles plan`/`handles emit` rather than a new singular flag name.
 	'handles audit': {
-		usage: 'bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--json]',
+		usage: 'bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--module <name>] [--check-registry-coverage] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			'database-url-env': { type: 'string', default: null, required: true },
 			resource: { type: 'string', default: '' },
+			// D-write-safety-phase1 (item 3): both opt-in, only consulted when --check-registry-coverage
+			// is set -- the base command stays gate-independent and scan-report-independent otherwise
+			// (see this command's own doc comment in bin/bskel.mjs for why that matters).
+			module: { type: 'string', default: null },
+			'check-registry-coverage': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},

package/lib/exit-codes.mjs

@@ -22,6 +22,23 @@ export const EXIT_CODES = Object.freeze({
 	LOW_CONFIDENCE_SCAN: 16,
 	MISSING_CAPABILITY: 17,
 	REFRESH_FAILED: 18,
+	// D-write-safety-phase0 (item 2): `stack apply --apply` refusing to overwrite a file that
+	// diverged from what backend-skeleton itself last wrote (without --force --reason) --
+	// deliberately its own code, not a reuse of HANDLES_CONFLICT, since this is a different write
+	// surface (stack/apply.mjs, not handles/_engine.mjs) and D-stable-api-contract's exit-code
+	// promise is additive-safe for new codes.
+	STACK_CONFLICT: 19,
+	// D-write-safety-phase1 (item 1): `handles emit --enforce-registry on` refusing to proceed
+	// because the target java-spring repo's build file has no `spring-boot-starter-aop` --
+	// HandleAspect.java cannot intercept anything without it, so writing the resolvers would be
+	// silently unusable. Not a reuse of MISSING_CAPABILITY(17), which means "the ADAPTER doesn't
+	// declare this capability at all" -- this repo's adapter does, it's just one dependency short.
+	HANDLES_MISSING_DEPENDENCY: 20,
+	// D-write-safety-phase1 (item 2): `handles emit --enforce-registry on` refusing to proceed
+	// because a resource has no @RecordHandleSnapshot/@record_snapshot anywhere the static check
+	// can find -- distinct from HANDLES_CONFLICT(15), which is about a GENERATED file diverging;
+	// this is about a hand-written file bskel never touches lacking an annotation it can't add.
+	HANDLES_REGISTRATION_GAP: 21,
 });
 
 // `reason` values a `sbf.cli-diagnostic/1` envelope (lib/cli.mjs) can carry. Deliberately does
@@ -55,6 +72,10 @@ export const EXIT_REASONS = Object.freeze({
 	ADAPTER_UNAVAILABLE: EXIT_CODES.NOT_PASSED,
 	PROVIDER_UNAVAILABLE: EXIT_CODES.NOT_PASSED,
 	UNKNOWN_OPERATION: EXIT_CODES.NOT_PASSED,
+	// D-openapi-cyclic-refs: `contract tool-schema`'s own refusal when the operation's payload
+	// schema is genuinely recursive -- Anthropic's tool-use input_schema explicitly does not
+	// support recursive schemas (a real, documented API limitation, not a bskel-side gap).
+	RECURSIVE_SCHEMA_UNSUPPORTED: EXIT_CODES.NOT_PASSED,
 	SCAN_FAILED: EXIT_CODES.NOT_PASSED,
 	PLAN_FAILED: EXIT_CODES.NOT_PASSED,
 });

package/lib/verify.mjs

@@ -110,24 +110,33 @@ function handlesOutputsFor(root, featureId) {
 // has ever run at all, independent of its current pass/stale status -- a stale or forced handles
 // gate still implies every one of its expected outputs should exist. A provider with zero
 // spec-scoped outputs simply produces no artifact items here at all, which is correct: there is
-// nothing to check (no provider currently declares an empty outputs.spec -- java-spring and
-// python-fastapi both emit migration.sql, G4's D-handles-providers follow-up -- but the code
-// path stays general for whatever provider comes next).
+// nothing to check (no provider currently declares a non-empty outputs.spec any more --
+// D-write-safety-phase0 (item 1) moved java-spring/python-fastapi's migration.sql onto manifest
+// tracking, the same mechanism handlesManifestChecks() below already covers, so this loop is now
+// live only for the fallback case below or a future provider with a genuinely untracked output).
 export function checkArtifacts(root, featureId, gates = []) {
 	const checks = [];
 	const contractPath = specPath(root, featureId, 'contracts', `${featureId}.schema.json`);
 	checks.push({ artifact: 'contract', path: path.relative(root, contractPath), exists: fs.existsSync(contractPath) });
 
 	const handlesRan = gates.find((g) => g.gate === 'handles')?.ran ?? false;
+	const manifestChecks = handlesManifestChecks(root, featureId, handlesRan);
+	// D-write-safety-phase0 (item 1): a path already covered by the manifest-based check above must
+	// not also get the legacy existence-only check below -- migration.sql is now BOTH manifest-
+	// tracked (owner: featureId) AND still named in DEFAULT_HANDLES_OUTPUTS's fallback list, so
+	// without this guard a scan-report-missing/corrupt repo would report it twice.
+	const manifestCheckedPaths = new Set(manifestChecks.map((c) => c.path));
 	for (const relOutput of handlesOutputsFor(root, featureId)) {
 		const outputPath = specPath(root, featureId, ...relOutput.split('/'));
+		const outputRelPath = path.relative(root, outputPath);
+		if (manifestCheckedPaths.has(outputRelPath)) continue;
 		const outputExists = fs.existsSync(outputPath);
 		if (handlesRan || outputExists) {
 			const label = path.basename(relOutput, path.extname(relOutput));
-			checks.push({ artifact: `handles ${label}`, path: path.relative(root, outputPath), exists: outputExists });
+			checks.push({ artifact: `handles ${label}`, path: outputRelPath, exists: outputExists });
 		}
 	}
-	checks.push(...handlesManifestChecks(root, featureId, handlesRan));
+	checks.push(...manifestChecks);
 	return checks;
 }
 
@@ -138,6 +147,11 @@ export function checkArtifacts(root, featureId, gates = []) {
 // nothing regenerates it implicitly, and the feature doesn't compile without it. Same mechanism
 // and reasoning as the migration.sql check above (S6) -- existence only, at verify time, entirely
 // outside the gate token.
+// D-write-safety-phase0 (item 1): manifest 'kind' values -> the label bskel verify's report shows.
+// Anything not listed falls back to 'handles resolver' (the historical default before 'migration'
+// existed) -- see the artifact: line below.
+const HANDLES_ARTIFACT_LABELS = { infra: 'handles infra', migration: 'handles migration' };
+
 function handlesManifestChecks(root, featureId, handlesRan) {
 	let manifest;
 	try {
@@ -162,7 +176,10 @@ function handlesManifestChecks(root, featureId, handlesRan) {
 		.map(([relPath, e]) => {
 			const abs = resolveWithinRoot(root, relPath);
 			return {
-				artifact: e.kind === 'infra' ? 'handles infra' : 'handles resolver',
+				// D-write-safety-phase0 (item 1): was a binary ternary (infra vs. everything else
+				// called "resolver") -- widened once migration.sql started manifest-tracking as its
+				// own kind: 'migration', which is neither infra (repo-owned) nor a resolver.
+				artifact: HANDLES_ARTIFACT_LABELS[e.kind] ?? 'handles resolver',
 				path: relPath,
 				exists: abs !== null && fs.existsSync(abs),
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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",
@@ -38,6 +38,7 @@
     "test:java-compile": "node scripts/java-compile-smoke.mjs",
     "test:python-import": "node scripts/python-import-smoke.mjs",
     "test:db-introspect": "node scripts/db-introspect-smoke.mjs",
+    "test:registry-coverage": "node scripts/handles-registry-coverage-smoke.mjs",
     "test:ddl-apply": "node scripts/ddl-apply-smoke.mjs",
     "test:cross-feature-fk": "node scripts/cross-feature-fk-smoke.mjs",
     "test:java-integration": "node scripts/java-integration-smoke.mjs",
@@ -45,7 +46,9 @@
     "test:python-integration": "node scripts/python-integration-smoke.mjs",
     "test:typescript-compile": "node scripts/typescript-typecheck-smoke.mjs",
     "test:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs",
-    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
+    "test:shadow-validation": "node scripts/shadow-validation-smoke.mjs",
+    "test:oracle-corpus": "node scripts/shadow-validation-smoke.mjs --manifest test/fixtures/oracle-manifest.json",
+    "test:all-smoke": "npm test && npm run test:pack && npm run test:java-compile && npm run test:java-integration && npm run test:python-import && npm run test:python-integration && npm run test:db-introspect && npm run test:registry-coverage && npm run test:ddl-apply && npm run test:cross-feature-fk && npm run test:java-ast && npm run test:typescript-compile"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/scanners/adapters/_java-spring-analyzer.mjs

@@ -53,7 +53,15 @@ export function matchBalanced(text, openIndex, openChar, closeChar) {
 	return -1;
 }
 
-const CLASS_OR_RECORD_RE = /(?:public\s+)?(class|record)\s+(\w+)/;
+// D-entity-id-field-inheritance: `\b` before `(class|record)` -- found live, not anticipated,
+// while verifying a real cross-file inheritance walk against `@MappedSuperclass`-annotated Java
+// (spring-petclinic's own `BaseEntity`). Without it, `class`/`record` could match as a SUBSTRING of
+// a preceding identifier that happens to end the same way -- `@MappedSuperclass\npublic class
+// BaseEntity` matched "class" inside "Superclass" itself (no `\w`-to-non-`\w` transition exists
+// between "Super" and "class", so no real word boundary there either way), then captured the next
+// bare word ("public") as if it were the class name. `\s+` alone was never sufficient protection --
+// it only requires whitespace AFTER the match, never a real word start before it.
+const CLASS_OR_RECORD_RE = /(?:public\s+)?\b(class|record)\s+(\w+)/;
 
 // Adds `record` support and makes `public` optional (a package-private class is still a legal
 // Spring bean) in the one place both extractController() and extractEntity() already duplicate
@@ -141,7 +149,22 @@ const MAPPING_VERBS = ['Get', 'Post', 'Put', 'Patch', 'Delete'];
 const MAPPING_ANNOTATION_RE = new RegExp(`@(?:(${MAPPING_VERBS.join('|')})Mapping|RequestMapping)\\b`, 'g');
 const REQUEST_MAPPING_RE = /@RequestMapping\b/g;
 const CLASS_OR_RECORD_START_RE = /^(?:public\s+)?(?:class|record)\b/;
-const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*RequestMethod\.(\w+)\b/;
+// D-java-spring-static-import-method: `RequestMethod.` prefix made optional -- confirmed live,
+// dogfooding against a real, popular repo (gothinkster/spring-boot-realworld-example-app, 1,584
+// real GitHub stars): its UsersApi.java (register + login, 2 of the RealWorld spec's most
+// fundamental endpoints) uses `import static ... RequestMethod.POST;` then bare
+// `@RequestMapping(path = "/users", method = POST)` -- a real, common Java style (static-import a
+// single enum constant to cut the qualifier) the original prefix-required regex silently missed
+// (0/2 endpoints on this file; the OTHER 15/17 endpoints in this same corpus, using
+// @PostMapping/@GetMapping shorthand elsewhere, were unaffected and already correct). The verb
+// alternation is restricted to Spring's own real `RequestMethod` enum's 8 actual values (GET,
+// HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE) rather than a bare `\w+` -- narrower than
+// "any identifier", so an unrelated `method = someVariable` still correctly fails to match rather
+// than being misread as a verb. Verified live: the existing multi-verb array form (`method =
+// {RequestMethod.GET, RequestMethod.POST}`, still deliberately unresolved/skipped) does NOT
+// accidentally partial-match here -- the array's own `{` breaks the match before any verb name is
+// reached, same as before this change.
+const REQUEST_MAPPING_METHOD_RE = /\bmethod\s*=\s*(?:RequestMethod\.)?(GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|TRACE)\b/;
 
 // True when `class`/`record` is the next real declaration after `index`, ONE OR MORE further
 // annotations allowed in between (e.g. a real oracle shape: `@RequestMapping(...)

package/scanners/adapters/java-spring.mjs

@@ -45,10 +45,43 @@ function listJavaFiles(srcRoot) {
 	return out.split('\n').filter(Boolean).sort();
 }
 
-function moduleOf(filePath, srcRoot) {
+// D-module-attribution-base-package: found live via a real-world corpus check (spring-projects/
+// spring-petclinic, the canonical public Spring Boot reference app) -- `domain/<module>/...` is
+// Team-IZ-Backend's OWN package convention, not a general Spring Boot one; petclinic's real
+// packages (`org.springframework.samples.petclinic.owner`, `...vet`, `...system`) never contain a
+// `domain` segment at all, so every entity there collapsed into `_unknown`. Finds the app's real
+// base package via its `@SpringBootApplication` class -- the actual framework-defined component-
+// scan root, not a second guessed folder name -- and returns the first path segment immediately
+// below it as a fallback module name. A single targeted `rg` search (not a second full-file read
+// pass), matching this file's own `listJavaFiles()` pattern for rg-invocation-with-graceful-empty-
+// result.
+function findBasePackage(srcRoot) {
+	let out;
+	try {
+		out = execFileSync('rg', ['-l', '--fixed-strings', '@SpringBootApplication', '-g', '*.java', srcRoot], { encoding: 'utf8' });
+	} catch {
+		return null; // rg exits 1 on "no match" -- not an error, just no @SpringBootApplication class found
+	}
+	const file = out.split('\n').filter(Boolean).sort()[0];
+	if (!file) return null;
+	const text = fs.readFileSync(file, 'utf8');
+	const pkg = text.match(/(?:^|\n)\s*package\s+([\w.]+)\s*;/);
+	return pkg ? pkg[1].split('.') : null;
+}
+
+function moduleOf(filePath, srcRoot, basePackageParts) {
 	const parts = path.relative(srcRoot, filePath).split(path.sep);
 	const domainIdx = parts.indexOf('domain');
-	return domainIdx >= 0 && parts[domainIdx + 1] ? parts[domainIdx + 1] : null;
+	if (domainIdx >= 0 && parts[domainIdx + 1]) return parts[domainIdx + 1];
+	// Fallback: the first segment directly under the app's own base package (e.g. petclinic's
+	// `owner`/`vet`/`system`) -- only when that segment is itself a subpackage (a directory), never
+	// the base package's own top-level file (the `@SpringBootApplication` class itself, or any
+	// other file living directly in the base package with no feature module of its own).
+	if (basePackageParts && basePackageParts.length && parts.length > basePackageParts.length + 1) {
+		const matchesBasePackage = basePackageParts.every((seg, i) => parts[i] === seg);
+		if (matchesBasePackage) return parts[basePackageParts.length];
+	}
+	return null;
 }
 
 function extractQuotedOrValue(argsText) {
@@ -132,12 +165,46 @@ function extractController(text, filePath) {
 	return { className, basePath, operationIds, endpoints, file: filePath, line: classLine };
 }
 
-function extractEntity(text, filePath) {
+// D-entity-id-field-inheritance: found live against a real corpus check (spring-projects/
+// spring-petclinic) -- `Owner extends Person extends BaseEntity`, and `@Id` lives on `BaseEntity`
+// (a `@MappedSuperclass`), the standard, textbook JPA pattern for sharing an id/audit-field base
+// across entities. A single-file-only `@Id` search misses it entirely for every entity built this
+// way. `classIndex` (simple class name -> that file's own text, built once per scan in
+// scanJavaSpring()) lets this walk the real `extends` chain instead of guessing.
+function extendsClauseName(maskedText) {
+	const m = maskedText.match(/\bclass\s+\w+\s+extends\s+(\w+)/);
+	return m ? m[1] : null;
+}
+
+// Depth-capped as insurance against a pathological/malformed input, not because real compilable
+// Java can have circular inheritance (it can't) -- same "not expected to trigger, cheap insurance"
+// reasoning javascript-express.mjs's own mount-graph cycle guard (`seen`) already uses for an
+// analogous risk.
+// D-write-safety-phase1 (item 4a): now also captures the declared TYPE, not just the field name --
+// mirrors typescript-express.mjs's own already-established `idFieldIsUuid` precedent
+// (scanners/adapters/typescript-express.mjs:216), which java-spring never had. Returns
+// `{field, type} | null` (was a bare string | null) -- see extractEntity() below for how both
+// existing and new consumers keep working from this.
+function findIdField(text, classIndex, depth = 0) {
+	const direct = text.match(/@Id\b[\s\S]{0,200}?private\s+(\S+)\s+(\w+)\s*;/);
+	if (direct) return { field: direct[2], type: direct[1] };
+	if (depth >= 10) return null;
+	const superName = extendsClauseName(maskNonCode(text));
+	if (!superName || !classIndex.has(superName)) return null;
+	return findIdField(classIndex.get(superName), classIndex, depth + 1);
+}
+
+// Bare and fully-qualified both count -- a real repo can `import java.util.UUID;` or spell it out
+// inline (`private java.util.UUID id;`), and this is a text-based scan with no import resolution.
+function isUuidType(type) {
+	return type === 'UUID' || type === 'java.util.UUID';
+}
+
+function extractEntity(text, filePath, classIndex) {
 	if (!/@Entity\b/.test(text)) return null;
 	const masked = maskNonCode(text);
 	const classDecl = findClassOrRecordDeclaration(masked);
 	const tableMatch = text.match(/@Table\(\s*name\s*=\s*"([^"]+)"/);
-	const idFieldMatch = text.match(/@Id\b[\s\S]{0,200}?private\s+\S+\s+(\w+)\s*;/);
 	return {
 		className: classDecl ? classDecl.name : path.basename(filePath, '.java'),
 		table: tableMatch ? tableMatch[1] : null,
@@ -147,7 +214,20 @@ function extractEntity(text, filePath) {
 		// two adapters that DO guess (python-fastapi/typescript-express) -- cross-feature collision
 		// detection reads this field, not each adapter's own null-vs-guessed convention.
 		tableSource: tableMatch ? 'explicit' : null,
-		idField: idFieldMatch ? idFieldMatch[1] : null,
+		...(() => {
+			const id = findIdField(text, classIndex);
+			return {
+				idField: id?.field ?? null,
+				// D-write-safety-phase1 (item 4a): idFieldIsUuid mirrors typescript-express.mjs's own
+				// field name exactly, for the same reason it exists there -- the handles subsystem's
+				// entire identity model is UUID-addressable (fetch(UUID resourceUid), sbf1_ handle
+				// tokens encode a UUID), so a non-UUID PK means "no resolver, and say why" rather than
+				// silence. idFieldType is the extra, java-spring-specific detail (the actual declared
+				// type string) that lets the diagnostic name it, not just say "not UUID".
+				idFieldType: id?.type ?? null,
+				idFieldIsUuid: id ? isUuidType(id.type) : null,
+			};
+		})(),
 		file: filePath,
 		line: classDecl ? lineNumberAt(text, classDecl.index) : null,
 	};
@@ -239,6 +319,24 @@ export function scanJavaSpring(repoRoot) {
 	const srcRoot = detectJavaSpringRoot(repoRoot);
 	if (!srcRoot) return null;
 
+	const basePackage = findBasePackage(srcRoot);
+
+	// D-entity-id-field-inheritance: built once, not per-entity -- a single pass over the same
+	// files this function was already about to read anyway (no new file I/O), so
+	// extractEntity()'s idField search can walk a real `extends` chain across files.
+	const files = listJavaFiles(srcRoot);
+	const fileTexts = new Map();
+	const classIndex = new Map();
+	for (const file of files) {
+		const text = fs.readFileSync(file, 'utf8');
+		fileTexts.set(file, text);
+		const decl = findClassOrRecordDeclaration(maskNonCode(text));
+		// First file wins on a same-simple-name collision across packages -- `files` is already
+		// sorted (listJavaFiles()'s own O6 determinism guarantee), so this is deterministic, not
+		// silently random; a documented, bounded limitation, not a general symbol resolver.
+		if (decl && !classIndex.has(decl.name)) classIndex.set(decl.name, text);
+	}
+
 	const modules = new Map();
 	const moduleEntry = (name) => {
 		const key = name ?? '_unknown';
@@ -246,16 +344,16 @@ export function scanJavaSpring(repoRoot) {
 		return modules.get(key);
 	};
 
-	for (const file of listJavaFiles(srcRoot)) {
-		const text = fs.readFileSync(file, 'utf8');
-		const mod = moduleOf(file, srcRoot);
+	for (const file of files) {
+		const text = fileTexts.get(file);
+		const mod = moduleOf(file, srcRoot, basePackage);
 
 		if (/@RestController\b/.test(text)) {
 			const controller = extractController(text, file);
 			if (controller) moduleEntry(mod).controllers.push(controller);
 		}
 		if (/@Entity\b/.test(text)) {
-			const entity = extractEntity(text, file);
+			const entity = extractEntity(text, file, classIndex);
 			if (entity) moduleEntry(mod).entities.push(entity);
 		}
 		if (mod && file.includes(`${path.sep}domain${path.sep}`) && /public\s+enum\s+\w+/.test(text)) {
@@ -271,7 +369,7 @@ export function scanJavaSpring(repoRoot) {
 	// paths) -- this is what lib/gate-definitions.mjs's `scan` gate hashes to detect real content
 	// drift, and every other manifest-shaped gate input in this codebase (stack's `applied_file:`)
 	// is repo-relative too.
-	const filesRead = listJavaFiles(srcRoot).map((f) => path.relative(repoRoot, f));
+	const filesRead = files.map((f) => path.relative(repoRoot, f));
 	return { srcRoot, modules: [...modules.values()], pathPrefixSignals: detectGlobalPathPrefixSignals(repoRoot), filesRead };
 }