backend-skeleton 1.0.0-beta.9 → 1.1.0

package/handles/_engine.mjs

@@ -5,11 +5,16 @@
 // D-handles-providers (G4) in DECISIONS.md. `handles/providers/java-spring/emit.mjs` is the
 // reference caller to compare against if this file's behavior is ever in question.
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { sha256File, sha256String } from '../lib/fsutil.mjs';
 import { loadManifest, saveManifest, classifyFile, extractResolverOwnerFeatureId, BSKEL_GENERATED_MARKER } from '../lib/handles-manifest.mjs';
+// D-patch-transactions: unifiedDiff() moved to lib/diff.mjs (stack/config-apply.mjs needs the
+// identical mechanism for its own collateral-diff safety gate) -- re-exported here so every
+// existing caller in this file keeps working unchanged.
+import { unifiedDiff } from '../lib/diff.mjs';
+
+export { unifiedDiff };
 
 function readIfExists(target) {
 	return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
@@ -20,40 +25,15 @@ function writeUnit(target, content) {
 	fs.writeFileSync(target, content);
 }
 
-// D4 (D-handles-dryrun): a real unified diff via `git diff --no-index`, not a hand-rolled diff
-// algorithm -- `git` is already a hard dependency (isDirtyOrUntracked below already shells out to
-// it on every emit), so this adds zero new dependencies. `cwd: tmpDir` + relative `a/<relPath>`/
-// `b/<relPath>` paths (rather than absolute temp paths) keep the diff header clean and
-// reproducible -- the random tmpdir name never leaks into the output. `git diff --no-index` exits
-// 1 when the two sides differ (the expected, common case here, not a failure) -- only a status
-// other than 0/1 is a genuine error worth throwing.
-export function unifiedDiff(relPath, before, after) {
-	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bskel-handles-diff-'));
-	try {
-		const beforeAbs = path.join(tmpDir, 'a', relPath);
-		const afterAbs = path.join(tmpDir, 'b', relPath);
-		fs.mkdirSync(path.dirname(beforeAbs), { recursive: true });
-		fs.mkdirSync(path.dirname(afterAbs), { recursive: true });
-		fs.writeFileSync(beforeAbs, before ?? '');
-		fs.writeFileSync(afterAbs, after ?? '');
-		try {
-			return execFileSync('git', ['diff', '--no-index', '--no-color', '--', `a/${relPath}`, `b/${relPath}`], { cwd: tmpDir, encoding: 'utf8' });
-		} catch (err) {
-			if (err.status === 1 && typeof err.stdout === 'string') return err.stdout;
-			throw err;
-		}
-	} finally {
-		fs.rmSync(tmpDir, { recursive: true, force: true });
-	}
-}
-
 const DIFFABLE_ACTIONS = new Set(['update', 'conflict', 'adopt-update']);
 
 // O2: refuses --force on a target that isn't safely recoverable from git history -- a --force
 // 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;
@@ -79,7 +59,23 @@ function isDirtyOrUntracked(repoRoot, absPath) {
 //   computeDiff:   D4 -- when true, attaches a real unified diff (git diff --no-index) to every
 //                  'update'/'conflict'/'adopt-update' action -- the only 3 where content actually
 //                  differs. Off by default since it shells out to git per diffable file.
-export function emitUnits({ repoRoot, featureId, provider, force = false, reason = '', infraUnits, resolverUnits, orphanScan, dryRun = false, computeDiff = false }) {
+//   postResolverUnit: D-patch-transactions (Continued) -- an OPTIONAL single unit, { id,
+//                  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();
 
@@ -137,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);
@@ -162,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 });
 		}
@@ -209,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);
@@ -240,11 +247,91 @@ 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 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);
+		const exists = diskContent !== null;
+		const diskHash = exists ? sha256String(diskContent) : null;
+		const freshRenderHash = sha256String(rendered);
+		const entry = manifest.files[relPath];
+		const matchesPristineRender = exists && diskContent === rendered;
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: entry?.generated_hash ?? null, freshRenderHash, matchesPristineRender });
+
+		if (action === 'conflict' && !force) {
+			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: 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: 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: unitKind, action, diskContent, rendered });
+			}
+		} else if (action === 'unchanged') {
+			recordAction({ relPath, kind: unitKind, action });
+		} else {
+			if (action !== 'adopt-unchanged') {
+				if (!dryRun) writeUnit(u.targetAbs, rendered);
+				written.push(relPath);
+			}
+			if (!dryRun) {
+				manifest.files[relPath] = {
+					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: unitKind, action, diskContent, rendered });
+		}
+	}
+
 	// ---- orphan detection: a resolver this feature's CURRENT plan no longer generates, left
 	// untouched and never deleted -- same conservative bias as D-migration-scope/D-config-patch.
 	// Suppressed entirely under --resource (orphanScan === null), since every resource outside the
@@ -275,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);