backend-skeleton 1.0.0 → 1.1.0

package/handles/_engine.mjs

@@ -31,7 +31,9 @@ const DIFFABLE_ACTIONS = new Set(['update', 'conflict', 'adopt-update']);
 // overwrite is only ever reversible if the content it destroys is already committed. Fails
 // closed (treats git errors, or a repo where the path can't be resolved, as "dirty") since the
 // whole point is to never make an irreversible action look safe by default.
-function isDirtyOrUntracked(repoRoot, absPath) {
+// D-write-safety-phase0 (item 2): exported so stack/apply.mjs can apply the identical
+// git-recoverability check before a --force overwrite -- previously private to this file.
+export function isDirtyOrUntracked(repoRoot, absPath) {
 	try {
 		const out = execFileSync('git', ['status', '--porcelain', '--', absPath], { cwd: repoRoot, encoding: 'utf8' });
 		return out.trim().length > 0;
@@ -58,16 +60,22 @@ function isDirtyOrUntracked(repoRoot, absPath) {
 //                  'update'/'conflict'/'adopt-update' action -- the only 3 where content actually
 //                  differs. Off by default since it shells out to git per diffable file.
 //   postResolverUnit: D-patch-transactions (Continued) -- an OPTIONAL single unit, { id,
-//                  templatePath, targetAbs, render() => string }, whose correct content can only
-//                  be computed AFTER resolverUnits above have been written (e.g. typescript-
-//                  express's resolvers_index.ts barrel -- its import list must reflect the
-//                  resolvers directory's REAL final on-disk listing, including this run's own
-//                  just-written resolver files, not just this run's own resolverUnits -- a 4th
-//                  infraUnits entry can't do this, since infra is processed BEFORE resolvers).
-//                  Reuses the exact same classify/conflict/force/manifest logic the infra loop
-//                  above already implements, applied to exactly one repo-owned (kind: 'infra')
-//                  unit. null (the default) is a true no-op.
-export function emitUnits({ repoRoot, featureId, provider, force = false, reason = '', infraUnits, resolverUnits, orphanScan, dryRun = false, computeDiff = false, postResolverUnit = null }) {
+//                  templatePath, targetAbs, render() => string, kind?, ownership?, owner? },
+//                  whose correct content can only be computed AFTER resolverUnits above have been
+//                  written (e.g. typescript-express's resolvers_index.ts barrel -- its import list
+//                  must reflect the resolvers directory's REAL final on-disk listing, including
+//                  this run's own just-written resolver files, not just this run's own
+//                  resolverUnits -- a 4th infraUnits entry can't do this, since infra is processed
+//                  BEFORE resolvers). Reuses the exact same classify/conflict/force/manifest logic
+//                  the infra loop above already implements. `kind`/`ownership`/`owner` default to
+//                  `'infra'`/`'repo'`/`'_repo'` (the barrel's own shape, unchanged);
+//                  D-write-safety-phase0 (item 1) is the first caller to override them, for a
+//                  feature-owned unit (java-spring/python-fastapi's migration.sql,
+//                  kind: 'migration', ownership: 'feature') whose content does NOT actually depend
+//                  on the resolver loop's post-write state -- it just reuses this slot rather than
+//                  adding a third one.
+//                  null (the default) is a true no-op.
+export function emitUnits({ repoRoot, featureId, provider, force = false, reason = '', infraUnits, resolverUnits, orphanScan, dryRun = false, computeDiff = false, postResolverUnits = [] }) {
 	const manifest = loadManifest(repoRoot);
 	const nowIso = new Date().toISOString();
 
@@ -125,6 +133,10 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 					};
 					manifestChanged = true;
 					writeUnit(u.targetAbs, u.rendered);
+					// D-write-safety-phase0 (item 3): persist per-unit, not once at the end of the whole
+					// loop -- a crash after this write but before a later unit's own write must not
+					// leave THIS file's real provenance unrecorded.
+					saveManifest(repoRoot, manifest);
 				}
 				written.push(u.relPath);
 				forced.push(u.relPath);
@@ -150,6 +162,8 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 					updated_at: nowIso,
 				};
 				manifestChanged = true;
+				// D-write-safety-phase0 (item 3): see the comment at this loop's first saveManifest() call.
+				saveManifest(repoRoot, manifest);
 			}
 			recordAction({ relPath: u.relPath, kind: 'infra', action: u.action, diskContent: u.diskContent, rendered: u.rendered });
 		}
@@ -197,6 +211,11 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 						updated_at: nowIso, last_force: { reason, at: nowIso, overwritten_hash: diskHash },
 					};
 					manifestChanged = true;
+					// D-write-safety-phase0 (item 3): persist per-unit -- the resolver loop is where this
+					// matters most (potentially many resolvers per feature, one saveManifest() call at
+					// the end previously meant a crash partway through left every already-written
+					// resolver this run unrecorded, not just the interrupted one).
+					saveManifest(repoRoot, manifest);
 				}
 				written.push(relPath);
 				forced.push(relPath);
@@ -228,23 +247,37 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 					updated_at: nowIso,
 				};
 				manifestChanged = true;
+				// D-write-safety-phase0 (item 3): see the comment at this loop's first saveManifest() call.
+				saveManifest(repoRoot, manifest);
 			}
 		}
 		recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.rendered });
 	}
 
-	// ---- post-resolver unit: an OPTIONAL single unit whose correct content can only be computed
-	// AFTER the resolver loop above has finished writing (e.g. typescript-express's
-	// resolvers_index.ts barrel -- its import list must reflect the resolvers directory's REAL
-	// on-disk listing, including THIS run's own just-written resolver files, not just this run's
-	// own resolverUnits). Reuses the EXACT SAME classify/conflict/force/manifest logic the infra
-	// loop above already implements, applied to exactly one unit. `render()` is called HERE, not
-	// earlier, precisely so it observes this run's own writes. null (the default) is a true no-op
-	// -- java-spring/python-fastapi never pass this, so this block never executes for them. See
-	// D-patch-transactions (Continued) in DECISIONS.md for why this couldn't just be a 4th
-	// infraUnits entry. ----
-	if (postResolverUnit) {
-		const u = postResolverUnit;
+	// ---- post-resolver units: an array of units whose correct content can only be computed AFTER
+	// the resolver loop above has finished writing (e.g. typescript-express's resolvers_index.ts
+	// barrel -- its import list must reflect the resolvers directory's REAL on-disk listing,
+	// including THIS run's own just-written resolver files, not just this run's own
+	// resolverUnits). Reuses the EXACT SAME classify/conflict/force/manifest logic the infra loop
+	// above already implements, applied to each unit independently. `render()` is called HERE, not
+	// earlier, precisely so it observes this run's own writes (still true for a unit whose content
+	// doesn't actually need that timing, like migration.sql -- it just reuses this array rather
+	// than adding a third mechanism). Empty array (the default) is a true no-op.
+	// D-typescript-express-registry-parity: was a single optional `postResolverUnit` object
+	// (D-write-safety-phase0's own kind/ownership/owner generalization) until typescript-express
+	// needed TWO units here at once (resolvers_index.ts, repo-owned, AND migration.sql,
+	// feature-owned, once this item gave it one) -- widened to an array, same per-unit logic,
+	// nothing else about the mechanism changed. See D-patch-transactions (Continued) in
+	// DECISIONS.md for why this couldn't just be infraUnits/resolverUnits entries. ----
+	for (const u of postResolverUnits) {
+		// D-write-safety-phase0 (item 1): generalized from a hardcoded infra/repo/_repo triple so a
+		// feature-owned single unit (java-spring/python-fastapi's migration.sql) can reuse this exact
+		// classify/conflict/force/manifest cycle too, not just typescript-express's repo-owned
+		// resolvers_index.ts barrel. Defaults preserve the original hardcoded values byte-for-byte, so
+		// the barrel caller (which never sets these) is unaffected.
+		const unitKind = u.kind ?? 'infra';
+		const unitOwnership = u.ownership ?? 'repo';
+		const unitOwner = u.owner ?? '_repo';
 		const rendered = u.render();
 		const relPath = path.relative(repoRoot, u.targetAbs);
 		const diskContent = readIfExists(u.targetAbs);
@@ -256,28 +289,30 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 		const action = classifyFile({ exists, diskHash, manifestEntryHash: entry?.generated_hash ?? null, freshRenderHash, matchesPristineRender });
 
 		if (action === 'conflict' && !force) {
-			conflicts.push({ path: relPath, kind: 'infra', reason: 'diverged from the last content backend-skeleton generated -- see notes for remediation' });
-			recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+			conflicts.push({ path: relPath, kind: unitKind, reason: 'diverged from the last content backend-skeleton generated -- see notes for remediation' });
+			recordAction({ relPath, kind: unitKind, action, diskContent, rendered });
 		} else if (action === 'conflict') {
 			if (isDirtyOrUntracked(repoRoot, u.targetAbs)) {
-				conflicts.push({ path: relPath, kind: 'infra', reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
-				recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+				conflicts.push({ path: relPath, kind: unitKind, reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+				recordAction({ relPath, kind: unitKind, action, diskContent, rendered });
 			} else {
 				if (!dryRun) {
 					manifest.files[relPath] = {
-						kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+						kind: unitKind, ownership: unitOwnership, owner: unitOwner, provider, template: u.id,
 						template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
 						updated_at: nowIso, last_force: { reason, at: nowIso },
 					};
 					manifestChanged = true;
 					writeUnit(u.targetAbs, rendered);
+					// D-write-safety-phase0 (item 3): see the infra loop's first saveManifest() call above.
+					saveManifest(repoRoot, manifest);
 				}
 				written.push(relPath);
 				forced.push(relPath);
-				recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+				recordAction({ relPath, kind: unitKind, action, diskContent, rendered });
 			}
 		} else if (action === 'unchanged') {
-			recordAction({ relPath, kind: 'infra', action });
+			recordAction({ relPath, kind: unitKind, action });
 		} else {
 			if (action !== 'adopt-unchanged') {
 				if (!dryRun) writeUnit(u.targetAbs, rendered);
@@ -285,13 +320,15 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 			}
 			if (!dryRun) {
 				manifest.files[relPath] = {
-					kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+					kind: unitKind, ownership: unitOwnership, owner: unitOwner, provider, template: u.id,
 					template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
 					updated_at: nowIso,
 				};
 				manifestChanged = true;
+				// D-write-safety-phase0 (item 3): see the infra loop's first saveManifest() call above.
+				saveManifest(repoRoot, manifest);
 			}
-			recordAction({ relPath, kind: 'infra', action, diskContent, rendered });
+			recordAction({ relPath, kind: unitKind, action, diskContent, rendered });
 		}
 	}
 
@@ -325,6 +362,12 @@ export function emitUnits({ repoRoot, featureId, provider, force = false, reason
 		}
 	}
 
+	// D-write-safety-phase0 (item 3): every mutation site above already calls saveManifest()
+	// itself, incrementally, right after its own write -- this is now a defensive backstop, not
+	// the primary persistence mechanism (a no-op resave of already-current content in the normal
+	// case), kept so a future mutation site added without its own incremental save still ends up
+	// correct at the end of a run that completes normally. It is NOT what makes this item's own
+	// crash-safety property hold -- that comes entirely from the per-unit calls above.
 	if (!dryRun && manifestChanged) saveManifest(repoRoot, manifest);
 
 	// D-resolver-policy-split: two units (Resolver + Policy) now share one resourceType, so

package/handles/capability-codec.mjs

@@ -0,0 +1,94 @@
+// ROADMAP.md Phase 6, item 1 (D-sbf2-capability-codec): the `sbf2_` token FORMAT and its
+// Ed25519 sign/verify mechanics -- deliberately INFRASTRUCTURE ONLY. Not wired into
+// `handles/codec.mjs`'s `HANDLE_DECODERS` dispatch table, not called from `HandleController`/
+// `ResourceResolver`, no CLI command issues or consumes one. ROADMAP's own Phase 6 text is explicit
+// about why: `sbf1_` conveys no authority by design (all authority comes from the target app's own
+// `@PreAuthorize`-derived check) -- a capability token is a genuinely DIFFERENT design, and this
+// project's own Phase 4 pilot (D-handles-pilot-cohort) never exercised a single real cross-tenant
+// or delegated-access use case (one resource, one org, straightforward CRUD). Building the actual
+// delegation MODEL -- what "scope" grants, how a capability token interacts with the real
+// authorization flow, key rotation/multiple-signers/revocation -- against zero real delegation
+// requirements is exactly what this project has refused to do everywhere else (D-security-8's own
+// "never guess, always explicit" boundary, D-write-safety-phase1's non-UUID refusal, this whole
+// project's Data-First Numerics discipline). This module exists so that work, once real
+// requirements exist, has real, tested crypto/envelope plumbing to start from rather than a blank
+// page -- not because the delegation model itself is considered designed.
+//
+// Reuses lib/attest.mjs's Ed25519 primitives directly (Node built-in `crypto`, zero new
+// dependencies) -- the same canonicalize/sign/verify this project's own gate attestations already
+// use, not a second, independently-written crypto path.
+import { signPayload, verifyPayload } from '../lib/attest.mjs';
+
+// D-security-10 precedent (handles/codec.mjs's own MAX_HANDLE_TOKEN_LENGTH): a defense-in-depth
+// cap before attempting to decode, not a functional requirement. Larger than sbf1's 2048 -- this
+// envelope carries a JSON payload plus a base64 Ed25519 signature (~88 bytes), not a bare
+// kind:type:uuid:pointer address.
+const MAX_CAPABILITY_TOKEN_LENGTH = 4096;
+const PREFIX = 'sbf2_';
+const BASE64URL_CHARSET_RE = /^[A-Za-z0-9_-]*$/;
+
+// Byte-for-byte the same base64url encode/decode handles/codec.mjs's own encodeHandle/
+// decodeSbf1Handle use (duplicated rather than imported -- these are ~3-line helpers with no
+// handle-specific meaning, and importing them would wire this file into handles/codec.mjs's own
+// module for no real reason beyond avoiding a duplicate).
+function base64url(buf) {
+	return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlDecode(str) {
+	if (!BASE64URL_CHARSET_RE.test(str)) throw new Error('not valid base64url after the sbf2_ prefix');
+	const pad = (4 - (str.length % 4)) % 4;
+	const padded = str.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(pad);
+	return Buffer.from(padded, 'base64');
+}
+
+// The payload shape ROADMAP.md Phase 6 itself names: issuer, audience, expiry, and a scope.
+// `scope`'s internal shape is deliberately UNINTERPRETED by this module -- it's carried through
+// verbatim, JSON-serializable, nothing more. This module has no opinion about what a "scope"
+// value means or how it should be checked against a real request; that's exactly the delegation-
+// model design this module deliberately does not make.
+export function encodeCapabilityToken({ iss, aud, exp, scope }, privateKeyPem) {
+	if (typeof iss !== 'string' || !iss) throw new Error('encodeCapabilityToken requires a non-empty "iss" (issuer)');
+	if (typeof aud !== 'string' || !aud) throw new Error('encodeCapabilityToken requires a non-empty "aud" (audience)');
+	if (typeof exp !== 'number' || !Number.isFinite(exp)) throw new Error('encodeCapabilityToken requires a numeric "exp" (Unix seconds)');
+	if (scope === undefined) throw new Error('encodeCapabilityToken requires a "scope" (any JSON-serializable value, uninterpreted by this codec)');
+
+	const payload = { iss, aud, exp, scope };
+	const sig = signPayload(payload, privateKeyPem);
+	const envelope = { payload, sig };
+	return `${PREFIX}${base64url(Buffer.from(JSON.stringify(envelope), 'utf8'))}`;
+}
+
+// Returns { ok: true, payload } or { ok: false, reason } -- never throws on a malformed/tampered/
+// expired token. Matches this project's own established convention for routine, expected
+// verification failures (contracts/openapi.mjs's loadOpenApiDocument/inlineSchema,
+// lib/schema-validate.mjs's validateAgainstSchema), not handles/codec.mjs's own throw-based
+// decodeHandle() -- an invalid capability token is an ordinary, expected outcome a caller needs
+// to branch on cleanly, not an exceptional program error.
+export function decodeCapabilityToken(token, publicKeyPem, { now = Math.floor(Date.now() / 1000) } = {}) {
+	if (typeof token !== 'string' || !token.startsWith(PREFIX)) return { ok: false, reason: 'missing sbf2_ prefix' };
+	if (token.length > MAX_CAPABILITY_TOKEN_LENGTH) return { ok: false, reason: `token exceeds the maximum length of ${MAX_CAPABILITY_TOKEN_LENGTH} characters` };
+
+	let envelope;
+	try {
+		const raw = base64urlDecode(token.slice(PREFIX.length)).toString('utf8');
+		envelope = JSON.parse(raw);
+	} catch (err) {
+		return { ok: false, reason: `malformed token: ${err.message}` };
+	}
+	if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope)) return { ok: false, reason: 'malformed token: not an object' };
+	const { payload, sig } = envelope;
+	if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return { ok: false, reason: 'malformed token: missing payload' };
+	if (typeof sig !== 'string' || !sig) return { ok: false, reason: 'malformed token: missing signature' };
+
+	if (!verifyPayload(payload, sig, publicKeyPem)) return { ok: false, reason: 'invalid signature' };
+
+	const { iss, aud, exp, scope } = payload;
+	if (typeof iss !== 'string' || !iss) return { ok: false, reason: 'malformed payload: missing iss' };
+	if (typeof aud !== 'string' || !aud) return { ok: false, reason: 'malformed payload: missing aud' };
+	if (typeof exp !== 'number' || !Number.isFinite(exp)) return { ok: false, reason: 'malformed payload: missing exp' };
+	if (scope === undefined) return { ok: false, reason: 'malformed payload: missing scope' };
+	if (exp <= now) return { ok: false, reason: 'expired' };
+
+	return { ok: true, payload: { iss, aud, exp, scope } };
+}

package/handles/codec.mjs

@@ -53,10 +53,20 @@ export function encodeHandle({ kind, type, uuid, pointer = null }) {
 	return `sbf1_${base64url(Buffer.from(raw, 'utf8'))}`;
 }
 
+// D-handle-identity-contract-freeze (Phase 3): scheme-dispatch table, not a hardcoded 'sbf1_'
+// check -- reserves the discriminant for a future `sbf2_` scheme (Phase 6, capability-scoped
+// handles) to register itself here additively, without ever changing how an existing 'sbf1_'
+// token decodes. encodeHandle() is untouched -- it still only ever emits 'sbf1_' tokens.
+const HANDLE_DECODERS = { sbf1: decodeSbf1Handle };
+
 export function decodeHandle(token) {
-	if (typeof token !== 'string' || !token.startsWith('sbf1_')) {
-		throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
-	}
+	const scheme = typeof token === 'string' && token.includes('_') ? token.slice(0, token.indexOf('_')) : token;
+	const decoder = typeof scheme === 'string' ? HANDLE_DECODERS[scheme] : undefined;
+	if (!decoder) throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
+	return decoder(token);
+}
+
+function decodeSbf1Handle(token) {
 	if (token.length > MAX_HANDLE_TOKEN_LENGTH) {
 		throw new Error(`handle token exceeds the maximum length of ${MAX_HANDLE_TOKEN_LENGTH} characters`);
 	}

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

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { emitUnits } from '../../_engine.mjs';
 import { loadPatchApprovals, approvedStrategyFor } from '../../../lib/patch-approvals.mjs';
 import { computeCodegenNeeds, renderPatchFieldBody } from './patch-strategy.mjs';
 import { sha256File } from '../../../lib/fsutil.mjs';
@@ -56,12 +56,54 @@ function lowerFirst(s) {
 // the primary `ObjectMapper` bean, which is what `@RequiredArgsConstructor` injection needs.
 // Defaults to the classic package when build.gradle/the plugin version can't be found -- covers
 // the far more common Spring Boot <=3.x case, and matches this project's own CI fixture corpus.
-export function detectJacksonPackage(repoRoot) {
+// D-write-safety-phase1 (item 1): a disk-verified grep for `spring-boot-starter-aop`, the ONE
+// dependency `HandleAspect.java` needs to actually intercept anything (Spring AOP is not enabled
+// by any other starter) -- `emit.mjs`'s own postEmitNotes has said so since O4, but only AFTER
+// writing code that silently can't work without it. Checks the same 3 build-file names
+// `scanners/adapters/java-spring.mjs`'s own `JAVA_BUILD_FILE_GLOBS` uses (not re-imported --
+// that constant is scanner-internal; duplicating 3 literal filenames here is simpler than adding
+// a cross-module export for them), since a Kotlin DSL or Maven repo is just as real a target as a
+// Groovy one. A simple substring check, not a real dependency-graph parse -- matches this
+// codebase's own "good-enough regex, not a real parser" convention throughout, and a
+// transitively-pulled-in `spring-boot-starter-aop` (via some other starter) is not a real shape
+// this project's own oracle or fixtures have ever exhibited.
+// D-handles-pilot-cohort follow-up: shared by detectJacksonPackage (Jackson 3 vs 2) and
+// springAopArtifactName (spring-boot-starter-aspectj vs -aop) -- both decisions hinge on the same
+// single signal, the Spring Boot Gradle plugin's own declared major version. Returns null (not a
+// guessed default) when build.gradle is absent or the plugin version can't be found -- callers
+// each decide their own "can't tell, assume the more common case" default, since that default
+// differs per caller (Jackson 2 vs the pre-4.x -aop artifact name).
+function detectSpringBootMajorVersion(repoRoot) {
 	const buildGradlePath = path.join(repoRoot, 'build.gradle');
-	if (!fs.existsSync(buildGradlePath)) return 'com.fasterxml.jackson.databind';
+	if (!fs.existsSync(buildGradlePath)) return null;
 	const text = fs.readFileSync(buildGradlePath, 'utf8');
 	const match = text.match(/id\s+['"]org\.springframework\.boot['"]\s+version\s+['"](\d+)\./);
-	const majorVersion = match ? Number(match[1]) : null;
+	return match ? Number(match[1]) : null;
+}
+
+// D-handles-pilot-cohort: found live, deploying against a real Spring Boot 4.1.0 target --
+// `spring-boot-starter-aop` does not exist as an artifact for Spring Boot 4.x (confirmed against
+// the real Maven Central BOM POM for spring-boot-dependencies:4.1.0, a 404 for the old artifact);
+// it was renamed to `spring-boot-starter-aspectj`. `hasSpringAopDependency()`'s old hardcoded
+// check would have "passed" a target repo that added the WRONG (nonexistent, for its own Boot
+// version) artifact name, only ever caught by a real compile failure.
+export function springAopArtifactName(repoRoot) {
+	const majorVersion = detectSpringBootMajorVersion(repoRoot);
+	return majorVersion !== null && majorVersion >= 4 ? 'spring-boot-starter-aspectj' : 'spring-boot-starter-aop';
+}
+
+export function hasSpringAopDependency(repoRoot) {
+	const artifactName = springAopArtifactName(repoRoot);
+	for (const name of ['build.gradle', 'build.gradle.kts', 'pom.xml']) {
+		const buildFilePath = path.join(repoRoot, name);
+		if (!fs.existsSync(buildFilePath)) continue;
+		if (fs.readFileSync(buildFilePath, 'utf8').includes(artifactName)) return true;
+	}
+	return false;
+}
+
+export function detectJacksonPackage(repoRoot) {
+	const majorVersion = detectSpringBootMajorVersion(repoRoot);
 	return majorVersion !== null && majorVersion >= 4 ? 'tools.jackson.databind' : 'com.fasterxml.jackson.databind';
 }
 
@@ -99,11 +141,6 @@ function currentlyApprovedFields(approvals, resourceType, patchable) {
 	return approved;
 }
 
-function writeUnit(target, content) {
-	fs.mkdirSync(path.dirname(target), { recursive: true });
-	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
@@ -136,6 +173,7 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 	// now needs jacksonPackage too, for the same reason patch codegen already did).
 	const patchApprovals = loadPatchApprovals(repoRoot, featureId);
 	const jacksonPackage = detectJacksonPackage(repoRoot);
+	const aopArtifactName = springAopArtifactName(repoRoot);
 
 	const infraUnits = INFRA_FILES.map((f) => ({
 		id: f.template,
@@ -145,7 +183,9 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 		// HandleController.java.tmpl -- applied to every infra file uniformly anyway, matching
 		// how BASE_PACKAGE/JACKSON_PACKAGE already do (render()'s replaceAll is a harmless no-op
 		// for a token absent from a given template, e.g. JACKSON_PACKAGE inside HandleCodec.java.tmpl).
-		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage, ENFORCE_REGISTRY: String(enforceRegistry) }),
+		// AOP_ARTIFACT_NAME (D-handles-pilot-cohort): same no-op-when-absent reasoning, only
+		// referenced by RecordHandleSnapshot.java.tmpl's own javadoc today.
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage, AOP_ARTIFACT_NAME: aopArtifactName, ENFORCE_REGISTRY: String(enforceRegistry) }),
 	}));
 
 	// O4 (D-handle-lifecycle): every resource in THIS feature shares the same contract file and
@@ -245,25 +285,25 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 		resourceTypeOf: (file, _content) => file.replace(/ResolverPolicy\.java$|Resolver\.java$/, ''),
 	} : null;
 
-	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff });
-
-	// The migration file is regenerated fresh every run, unconditionally, regardless of the
-	// resolver/infra conflict-block state above -- it has never been manifest-tracked (no
-	// conflict detection for it at all), matching the pre-G4 behavior exactly. D4: this is exactly
-	// the `outputs.spec` category P4's conformance harness already had to special-case (see
-	// handles/conformance.mjs) -- classifyFile() never runs against it, so its create/unchanged/
-	// update action is derived locally here, tagged `kind: 'spec'` in the actions report so it
-	// reads distinctly from the manifest-tracked infra/resolver kinds.
-	const migrationContent = render(MIGRATION_TEMPLATE, { FEATURE_ID: featureId });
+	// D-write-safety-phase0 (item 1): migration.sql used to be regenerated fresh every run,
+	// unconditionally, with no manifest tracking and no conflict detection at all -- a hand-edited
+	// migration (an added index, a NOT NULL, a tenant column) was silently overwritten on the next
+	// `handles emit`. It's feature-scoped (specs/<featureId>/handles/migration.sql), not a
+	// repo-wide singleton, but its content depends only on featureId (not on the resolver loop's
+	// post-write state) -- so it reuses emitUnits()'s postResolverUnits slot (previously
+	// typescript-express-only, for resolvers_index.ts; widened to an array in
+	// D-typescript-express-registry-parity once that provider needed two units here at once)
+	// rather than adding a third write path, with kind/ownership/owner overridden to reflect real
+	// feature ownership.
 	const migrationPath = path.join(repoRoot, 'specs', featureId, 'handles', 'migration.sql');
-	const migrationRelPath = path.relative(repoRoot, migrationPath);
-	const migrationDiskContent = fs.existsSync(migrationPath) ? fs.readFileSync(migrationPath, 'utf8') : null;
-	const migrationAction = migrationDiskContent === null ? 'create' : (migrationDiskContent === migrationContent ? 'unchanged' : 'update');
-	if (!dryRun) writeUnit(migrationPath, migrationContent);
-	result.written.push(migrationRelPath);
-	const migrationActionEntry = { path: migrationRelPath, kind: 'spec', action: migrationAction };
-	if (computeDiff && migrationAction === 'update') migrationActionEntry.diff = unifiedDiff(migrationRelPath, migrationDiskContent, migrationContent);
-	result.actions.push(migrationActionEntry);
+	const result = emitUnits({
+		repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits, orphanScan, dryRun, computeDiff,
+		postResolverUnits: [{
+			id: 'migration.sql.tmpl', templatePath: MIGRATION_TEMPLATE, targetAbs: migrationPath,
+			render: () => render(MIGRATION_TEMPLATE, { FEATURE_ID: featureId }),
+			kind: 'migration', ownership: 'feature', owner: featureId,
+		}],
+	});
 
 	const postEmitNotes = [
 		'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
@@ -271,20 +311,25 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 		// 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.',
+		`NOT done automatically: HandleAspect.java requires ${aopArtifactName} on your own build.gradle classpath (Spring AOP is not enabled by any other starter; the artifact is named spring-boot-starter-aop before Spring Boot 4, spring-boot-starter-aspectj from Spring Boot 4 on -- ${aopArtifactName} matches what this repo's own detected Spring Boot version needs). 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.
+	// D-write-safety-phase1 (item 2): now ALSO collected into registrationGaps (a real, structured
+	// array), not just prose -- the postEmitNote stays unconditional (still visible even when
+	// --force acknowledges it) so the CLI layer (bin/bskel.mjs) can decide whether an unacknowledged
+	// gap should block the command, without this function knowing anything about --force itself.
+	const registrationGaps = [];
 	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.`,
-			);
+			const note = `${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.`;
+			postEmitNotes.push(note);
+			registrationGaps.push({ resourceType: resource.type, file: relServiceFile, note });
 		}
 	}
 
-	return { ...result, postEmitNotes };
+	return { ...result, postEmitNotes, registrationGaps };
 }

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

@@ -62,9 +62,10 @@ export function emitObserveJavaSpring({ repoRoot, featureId, contract, basePacka
 	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
 
 	// The projected observed-schema.json classpath resource -- regenerated unconditionally every
-	// run, like handles' own migration.sql, and for the identical reason: nobody hand-finishes a
-	// generated data file the way they hand-finish a resolver stub, so O2-style conflict tracking
-	// buys nothing here. `kind: 'spec'` matches migration.sql's own action-reporting convention.
+	// run (unlike handles' own migration.sql, which moved to manifest tracking in
+	// D-write-safety-phase0 -- this file stays unconditional: nobody hand-finishes a generated
+	// data file the way they hand-finish a resolver stub, so O2-style conflict tracking buys
+	// nothing here). `kind: 'spec'` still means "always regenerated, not conflict-tracked".
 	const operations = {};
 	for (const [opId, opContract] of Object.entries(contract.operations)) {
 		operations[opId] = projectOperation(opContract);

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

@@ -77,9 +77,18 @@ function findRequestBodyTypeName(controllerFilePath, methodName) {
 // during this item's grounding). A DTO living somewhere else is a documented gap: patchable stays
 // empty for that resource, exactly like findServiceFile()'s own "resolver NOT generated" fallback
 // for a service that can't be found.
+// D-write-safety-phase1 (item 4b): a real, bounded fallback -- after the domain/<module>/
+// presentation/dto/ convention (Team-IZ-Backend's own shape) fails, also try the DTO directly
+// under <module>/ with no domain/presentation/dto middle segments, the natural flat-package
+// variant of the same convention (javaSrcRoot is already base-package-anchored -- see
+// detectBasePackage() -- so this is `<basePackage>/<module>/<Type>.java`, not a second guessed
+// base). Does not attempt any other shape: no second real oracle has ever validated one, and
+// guessing further risks W9-style overfitting to an imagined repo rather than a confirmed one.
 function findUpdateDtoFile(javaSrcRoot, module, dtoTypeName) {
-	const guessedPath = path.join(javaSrcRoot, 'domain', module, 'presentation', 'dto', `${dtoTypeName}.java`);
-	return fs.existsSync(guessedPath) ? guessedPath : null;
+	const conventional = path.join(javaSrcRoot, 'domain', module, 'presentation', 'dto', `${dtoTypeName}.java`);
+	if (fs.existsSync(conventional)) return conventional;
+	const flat = path.join(javaSrcRoot, module, `${dtoTypeName}.java`);
+	return fs.existsSync(flat) ? flat : null;
 }
 
 // The full patchable-field pipeline for one entity: find its update endpoint -> find the
@@ -194,10 +203,20 @@ function findRequiredAuthority(controllerFilePath, methodName) {
 // guaranteed for every entity): <Entity>Service under domain/<module>/application/. Only
 // trusted if the file actually exists -- see D-resolver-scope in DECISIONS.md for why a
 // resolver is only generated when this resolves to a real file, not a guessed import.
+// D-write-safety-phase1 (item 4b): falls back to <module>/<Entity>Service.java directly under
+// javaSrcRoot (no domain/application segments) when the conventional path doesn't exist -- the
+// flat-package variant of the same convention. Confirmed this does NOT close the real-world case
+// that motivated it (spring-projects/spring-petclinic): petclinic has no *Service.java at all
+// (controllers call a Spring Data repository directly), and its entities are Integer-keyed, not
+// UUID (see idFieldIsUuid's own gate in planHandles() below, which fires first regardless). This
+// is a real, independent improvement for a different, plausible shape -- a UUID-keyed entity with
+// a Service layer, just not nested under domain/ -- not a claim that it closes the petclinic gap.
 function findServiceFile(javaSrcRoot, module, entityClassName) {
 	const guessedType = `${entityClassName}Service`;
-	const guessedPath = path.join(javaSrcRoot, 'domain', module, 'application', `${guessedType}.java`);
-	return fs.existsSync(guessedPath) ? { serviceType: guessedType, file: guessedPath } : null;
+	const conventional = path.join(javaSrcRoot, 'domain', module, 'application', `${guessedType}.java`);
+	if (fs.existsSync(conventional)) return { serviceType: guessedType, file: conventional };
+	const flat = path.join(javaSrcRoot, module, `${guessedType}.java`);
+	return fs.existsSync(flat) ? { serviceType: guessedType, file: flat } : null;
 }
 
 // Counts top-level commas in a captured argument list, treating `<...>` (generics) as non-
@@ -246,10 +265,26 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 
 	for (const entity of targetModule.entities) {
 		if (resourceFilter && !resourceFilter.includes(entity.className)) continue;
+
+		// D-write-safety-phase1 (item 4a): a non-UUID primary key disqualifies resolver generation
+		// entirely, independent of whether a Service class can be found -- fetch(UUID resourceUid)
+		// and the sbf1_ handle token format both hard-assume a UUID identity. Checked BEFORE the
+		// service lookup so the note names the real, decisive reason instead of the generic "no
+		// XService found" note below, which would be true but misleading here (implies the fix is
+		// finding/writing a service, when no service could ever make this entity addressable).
+		// `=== false` (not just falsy) deliberately excludes `null` (idField itself was never
+		// found, e.g. inherited from an unindexed superclass) -- that stays the existing, separate
+		// "no XService found" path unchanged, since this scanner genuinely doesn't know the type
+		// there, not that it's confirmed non-UUID.
+		const pkIsNonUuid = entity.idFieldIsUuid === false;
+		if (pkIsNonUuid) {
+			notes.push(`${entity.className}: primary key is declared \`${entity.idFieldType}\`, not UUID -- the handles subsystem only generates UUID-addressable resolvers (fetch(UUID resourceUid); the sbf1_ handle token format encodes a UUID). Resolver NOT generated for this entity, and cannot be regardless of where its service file lives. See D-handle-uid-type-binding in DECISIONS.md.`);
+		}
+
 		const fetchOp = findFetchOperation(targetModule.controllers, entity.className);
 		const authorityResult = findRequiredAuthority(fetchOp?.controllerFile ?? null, fetchOp?.method ?? null);
 		const requiredAuthority = authorityResult.authority;
-		const service = findServiceFile(javaSrcRoot, targetModule.module, entity.className);
+		const service = pkIsNonUuid ? null : findServiceFile(javaSrcRoot, targetModule.module, entity.className);
 		const serviceParamCount = (service && fetchOp) ? countServiceMethodParams(service.file, fetchOp.method) : null;
 
 		// O5 (D-resolver-authorization-action-aware): the SAME extraction, run again against the
@@ -276,12 +311,16 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)/hasAuthority(...)) found for ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} -- requiredAuthorityForPatch() defaults to "TODO_ROLE", fix before relying on it`);
 		}
 		if (!service) {
-			notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);
+			// pkIsNonUuid already explained the real reason above -- this note would be true but
+			// redundant (and misleading: it implies finding a service would fix it).
+			if (!pkIsNonUuid) {
+				notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ or ${targetModule.module}/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);
+			}
 		} else if (fetchOp && serviceParamCount !== 1) {
 			const reason = serviceParamCount === null
 				? `could not find a ${fetchOp.method}(...) method on ${service.serviceType} to confirm its argument count`
 				: `${service.serviceType}.${fetchOp.method} takes ${serviceParamCount} argument(s), not the single resource UUID the generated resolver always passes`;
-			notes.push(`${entity.className}: ${reason} -- resolver NOT generated (would either fail to compile or silently call the wrong overload and drop a required scoping argument, e.g. an organization/cohort id). Wire it by hand.`);
+			notes.push(`${entity.className}: ${reason} -- resolver NOT generated (would either fail to compile or silently call the wrong overload and drop a required scoping argument, e.g. an organization/cohort id). Wire it by hand -- ResourceResolver#fetch/#patchField receive the request's Authentication (D-resolver-authentication-context) for exactly this case, e.g. deriving a tenant/org id the same way the resource's own controller already does.`);
 		}
 
 		// A3 (D-patch-strategy): only worth computing once fetch()/the resolver itself is actually
@@ -319,6 +358,11 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 			type: entity.className,
 			table: entity.table,
 			idField: entity.idField,
+			// D-write-safety-phase1 (item 4a): surfaced in --json output too, not just the note --
+			// null/null when the type genuinely couldn't be determined (not the same as confirmed
+			// non-UUID; see pkIsNonUuid's own `=== false` check above).
+			idFieldType: entity.idFieldType,
+			idFieldIsUuid: entity.idFieldIsUuid,
 			fetchOperation: fetchOp,
 			updateOperation: patchResult.updateOperation,
 			patchable: patchResult.patchable,