backend-skeleton 1.0.0-beta.9 → 1.1.0

package/lib/serve-ui.html

@@ -44,6 +44,34 @@
 </form>
 <div id="formStatus"></div>
 
+<h2>Live DB schema</h2>
+<div id="dbSchemaPanel">
+	<p class="muted" id="dbSchemaNote">loading...</p>
+	<table id="dbSchemaTable" hidden><thead><tr><th>table</th><th>columns</th><th>primary key</th><th>foreign keys</th><th>indexes</th></tr></thead><tbody></tbody></table>
+</div>
+
+<h2>DDL patch transactions</h2>
+<div id="ddlPanel">
+	<form id="ddlFeatureForm" style="grid-template-columns: 1fr auto;">
+		<label>feature <input name="feature" id="ddlFeatureInput" required></label>
+		<button type="submit">Load transactions</button>
+	</form>
+	<table id="ddlTable"><thead><tr><th>transaction</th><th>kind</th><th>status</th><th>sql</th><th>created</th><th>action</th></tr></thead><tbody></tbody></table>
+	<div id="ddlActionStatus"></div>
+
+	<h3 style="font-size: 0.9rem; margin-top: 1.2rem;">Propose a DDL change</h3>
+	<form id="ddlProposeForm">
+		<label>feature <input name="feature" id="ddlProposeFeature" required></label>
+		<label>database_url_env <input name="databaseUrlEnv" placeholder="e.g. BSKEL_DDL_DATABASE_URL" required></label>
+		<label>schema <input name="schema" value="public" required></label>
+		<label style="grid-column: 1 / -1">sql_text
+			<textarea name="sqlText" rows="4" required style="font: inherit; padding: 0.4rem;" placeholder="CREATE TABLE widgets (id uuid PRIMARY KEY);"></textarea>
+		</label>
+		<button type="submit">Propose</button>
+	</form>
+	<div id="ddlProposeStatus"></div>
+</div>
+
 <script>
 // D-http-serving-layer: `reason`/`memo` (and every other string field) are free text a human types
 // via `bskel dependency declare --reason/--memo` or this page's own POST form -- never assumed safe
@@ -106,6 +134,189 @@ document.getElementById('declareForm').addEventListener('submit', async (ev) =>
 	}
 });
 
+// D-ddl-apply: mirrors td()'s own comment above -- every value rendered here (table/column names,
+// raw sql_text, error messages) is free text this tool never assumes is safe to inject as markup.
+// All via td()/textContent, never innerHTML.
+function tdList(items) {
+	return td(items.length ? items.join(', ') : '(none)');
+}
+
+// D-ddl-apply (DROP-TABLE-specific confirmation): mirrors scanners/db/ddl-apply.mjs's own
+// requiredConfirmValue() exactly -- the transaction id for a non-drop transaction, or the sorted,
+// comma-joined dropped-table name(s) for one that drops a table. Computed here purely so the
+// placeholder can SHOW the human what to type; the server independently re-derives and enforces
+// the same value, this is not the source of truth.
+function requiredConfirmValue(t) {
+	const droppedTables = (t.postcondition?.expected_tables ?? [])
+		.filter((x) => x.expect === 'absent')
+		.map((x) => x.name)
+		.sort();
+	return droppedTables.length > 0 ? droppedTables.join(',') : t.transaction_id;
+}
+
+async function loadDbSchema() {
+	const note = document.getElementById('dbSchemaNote');
+	const table = document.getElementById('dbSchemaTable');
+	try {
+		const res = await fetch('/api/db/schema');
+		if (res.status === 404) {
+			note.hidden = false;
+			note.textContent = 'DDL features are disabled -- start `bskel serve --database-url-env NAME` to enable them.';
+			table.hidden = true;
+			return;
+		}
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		note.hidden = true;
+		table.hidden = false;
+		const tbody = table.querySelector('tbody');
+		tbody.replaceChildren();
+		for (const t of body.tables) {
+			const tr = document.createElement('tr');
+			tr.append(
+				td(t.name),
+				td(t.columns.map((c) => `${c.name} ${c.type}${c.nullable ? '' : ' NOT NULL'}`).join(', ') || '(none)'),
+				tdList(t.primary_key),
+				td(t.foreign_keys.map((f) => `${f.column} -> ${f.references_table}.${f.references_column}`).join(', ') || '(none)'),
+				tdList(t.indexes),
+			);
+			tbody.appendChild(tr);
+		}
+		if (body.tables.length === 0) {
+			const tr = document.createElement('tr');
+			tr.appendChild(td('(no tables)'));
+			tbody.appendChild(tr);
+		}
+	} catch (err) {
+		note.hidden = false;
+		note.textContent = `failed to load /api/db/schema: ${err.message}`;
+		table.hidden = true;
+	}
+}
+
+async function loadDdlTransactions(feature) {
+	const tbody = document.querySelector('#ddlTable tbody');
+	tbody.replaceChildren();
+	if (!feature) return;
+	const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions`);
+	const body = await res.json();
+	if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+	for (const t of body.transactions) {
+		const tr = document.createElement('tr');
+		const sqlOrTarget = t.kind === 'ddl-apply' ? t.target.sql_text : `${t.target.file} @ ${(t.target.key_path || []).join('.')}`;
+		tr.append(td(t.transaction_id), td(t.kind), td(t.status), td(sqlOrTarget), td(t.created_at));
+
+		const actionCell = document.createElement('td');
+		if (t.status === 'proposed') {
+			const form = document.createElement('form');
+			form.style.gridTemplateColumns = 'none';
+			form.style.display = 'flex';
+			form.style.gap = '0.3rem';
+			const reasonInput = document.createElement('input');
+			reasonInput.placeholder = 'reason';
+			reasonInput.required = true;
+			const btn = document.createElement('button');
+			btn.type = 'submit';
+			btn.textContent = 'Approve';
+			form.append(reasonInput, btn);
+			form.addEventListener('submit', async (ev) => {
+				ev.preventDefault();
+				await runDdlAction(feature, t.transaction_id, 'approve', { reason: reasonInput.value });
+			});
+			actionCell.appendChild(form);
+		} else if (t.status === 'approved') {
+			const form = document.createElement('form');
+			form.style.gridTemplateColumns = 'none';
+			form.style.display = 'flex';
+			form.style.gap = '0.3rem';
+			const confirmInput = document.createElement('input');
+			// Deliberately starts EMPTY, never pre-filled -- a pre-filled confirm field would let a
+			// click submit this whole flow (applying a live DDL change) without the human actually
+			// re-reading/re-typing anything, defeating the entire point of this friction. The
+			// placeholder names the REQUIRED value -- the dropped table name(s), not the opaque
+			// transaction id, when this transaction drops a table (see requiredConfirmValue() above).
+			confirmInput.placeholder = `type "${requiredConfirmValue(t)}" to confirm`;
+			confirmInput.required = true;
+			const btn = document.createElement('button');
+			btn.type = 'submit';
+			btn.textContent = 'Apply';
+			form.append(confirmInput, btn);
+			form.addEventListener('submit', async (ev) => {
+				ev.preventDefault();
+				await runDdlAction(feature, t.transaction_id, 'apply', { confirm: confirmInput.value });
+			});
+			actionCell.appendChild(form);
+		} else {
+			actionCell.textContent = '(none)';
+		}
+		tr.appendChild(actionCell);
+		tbody.appendChild(tr);
+	}
+	if (body.transactions.length === 0) {
+		const tr = document.createElement('tr');
+		tr.appendChild(td('(none proposed)'));
+		tbody.appendChild(tr);
+	}
+}
+
+async function runDdlAction(feature, transactionId, action, body) {
+	const statusEl = document.getElementById('ddlActionStatus');
+	statusEl.textContent = `${action}ing...`;
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions/${encodeURIComponent(transactionId)}/${action}`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(body),
+		});
+		const responseBody = await res.json();
+		if (!res.ok) throw new Error(responseBody.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `${action} succeeded: ${transactionId} -> ${responseBody.status}`;
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+}
+
+document.getElementById('ddlFeatureForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const feature = document.getElementById('ddlFeatureInput').value;
+	try {
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		document.getElementById('ddlActionStatus').textContent = `error: ${err.message}`;
+	}
+});
+
+document.getElementById('ddlProposeForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const form = new FormData(ev.target);
+	const feature = form.get('feature');
+	const statusEl = document.getElementById('ddlProposeStatus');
+	statusEl.textContent = 'proposing...';
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/patch-transactions/propose`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				kind: 'ddl-apply',
+				databaseUrlEnv: form.get('databaseUrlEnv'),
+				schema: form.get('schema'),
+				sqlText: form.get('sqlText'),
+			}),
+		});
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `proposed: ${body.transaction_id}`;
+		ev.target.reset();
+		document.getElementById('ddlFeatureInput').value = feature;
+		await loadDdlTransactions(feature);
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+});
+
+loadDbSchema();
+
 loadGraph().catch((err) => {
 	const p = document.createElement('p');
 	p.style.color = '#d33';

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/lib/workflow.mjs

@@ -31,6 +31,11 @@ export function listFeatures(root) {
 const ESTABLISH_COMMAND = {
 	preflight: () => 'bskel preflight',
 	scan: (id) => `bskel scan --feature ${id} --terms <a,b,c>`,
+	// D-cross-feature-collision: added in the SAME commit as the gate itself this time -- the
+	// ESTABLISH_COMMAND/MUTATING_PREFIXES gap was found live twice already this session for other
+	// gates (dependencies/conformance below), so this one is wired up immediately rather than
+	// discovered later.
+	cross_feature: (id) => `bskel scan cross-feature-check --feature ${id}`,
 	contract: (id) => `bskel contract emit --feature ${id}`,
 	// D-field-dependency: this and `conformance` immediately below were BOTH missing before this
 	// item -- found live while adding this one, same crash class, fixed together. Neither had ever
@@ -41,6 +46,10 @@ const ESTABLISH_COMMAND = {
 	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
 	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
 	stack: () => 'bskel stack apply --choice <id> --apply',
+	// D-patch-transactions: added in the SAME commit as the gate itself -- per the
+	// `D-cross-feature-collision` entry's own explicit warning above (this exact ESTABLISH_COMMAND
+	// gap), already found live twice for other gates before it could recur a third time here.
+	patch_transactions: (id) => `bskel patch propose --feature ${id} --choice <id> --target <config_check target path>   # then: bskel patch approve ... then bskel patch apply ...`,
 	conformance: (id) => `bskel observe emit --feature ${id}   # then: run the target app, then bskel observe import --feature ${id} --receipts <path>`,
 };
 
@@ -55,17 +64,36 @@ function awaitingDispositionCommand(gateName, featureId) {
 	if (gateName === 'contract') {
 		return `bskel contract waive --feature ${featureId} --code <CODE> (--subject "..."|--all) --reason "..."   # or: bskel gate force contract --feature ${featureId} --reason "..." if intentional`;
 	}
+	if (gateName === 'cross_feature') {
+		return `bskel scan cross-feature-waive --feature ${featureId} --signal resource_type|table|operation_id --identifier <name> --other-feature <id> --reason "..."   # or: bskel gate force cross_feature --feature ${featureId} --reason "..." if intentional`;
+	}
 	return `bskel gate force ${gateName} --feature ${featureId} --reason "..."`;
 }
 
 // Whether a recommended command WRITES anything (gate state, generated files, applied files) as
 // opposed to being a pure read (bskel verify, bskel status, bskel next itself). Matched by the
 // command's own leading "bskel <verb...>" prefix so this can't silently drift from the actual
-// command names above.
-const MUTATING_PREFIXES = ['bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive', 'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit', 'bskel handles plan', 'bskel stack apply'];
+// command names above. `bskel observe emit`/`bskel observe import` were BOTH missing until found
+// live while fixing the identical ESTABLISH_COMMAND gap above (same bug class: neither had ever
+// been exercised through `next` recommending the real `conformance`-gate command, so a real
+// `mutating: false` misclassification on a command that actually writes files + passes a gate went
+// unnoticed) -- see D-field-dependency's COST section in DECISIONS.md.
+const MUTATING_PREFIXES = [
+	'bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive',
+	'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit',
+	'bskel handles plan', 'bskel stack apply', 'bskel observe emit', 'bskel observe import',
+	'bskel patch propose', 'bskel patch approve', 'bskel patch apply', 'bskel patch rollback',
+];
+
+// Exported (not just inlined into action()) so lib/workflow.mjs's own test suite can assert the
+// classification directly, without needing a full end-to-end fixture that drives a feature all the
+// way to a stale `conformance` gate just to observe one boolean.
+export function isMutatingCommand(command) {
+	return MUTATING_PREFIXES.some((p) => command.startsWith(p));
+}
 
 function action(command, reason) {
-	return { command, reason, mutating: MUTATING_PREFIXES.some((p) => command.startsWith(p)) };
+	return { command, reason, mutating: isMutatingCommand(command) };
 }
 
 // featureId === null means "repo scope only" -- feature-scoped gates (scan/contract/handles)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.9",
+  "version": "1.1.0",
   "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,11 +38,17 @@
     "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",
     "test:java-ast": "node scripts/java-ast-smoke.mjs",
     "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:spring-initializr-canary": "node scripts/spring-initializr-canary.mjs",
+    "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

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,16 +165,69 @@ 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,
-		idField: idFieldMatch ? idFieldMatch[1] : null,
+		// D-cross-feature-collision: this adapter never GUESSES a table name -- `table: null` above
+		// already means "no explicit @Table(name=...)", so tableSource is 'explicit' whenever
+		// `table` is non-null and null otherwise. Added only for a consistent field shape with the
+		// 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,
+		...(() => {
+			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,
 	};
@@ -233,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';
@@ -240,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)) {
@@ -265,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 };
 }