backend-skeleton 1.0.0-beta.1

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

@@ -0,0 +1,232 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { loadPatchApprovals, approvedStrategyFor } from '../../../lib/patch-approvals.mjs';
+import { computeCodegenNeeds, renderPatchFieldBody } from './patch-strategy.mjs';
+import { sha256File } from '../../../lib/fsutil.mjs';
+import { specPath } from '../../../lib/paths.mjs';
+import { loadFeatureFile } from '../../../lib/featurelifecycle.mjs';
+
+const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
+const MIGRATION_TEMPLATE = path.join(TEMPLATES_DIR, 'migration.sql.tmpl');
+const RESOLVER_TEMPLATE = path.join(TEMPLATES_DIR, 'ResourceResolverStub.java.tmpl');
+
+const INFRA_FILES = [
+	{ template: 'HandleCodec.java.tmpl', target: 'global/handle/HandleCodec.java' },
+	{ template: 'HandleRegistry.java.tmpl', target: 'global/handle/HandleRegistry.java' },
+	{ template: 'HandleSnapshot.java.tmpl', target: 'global/handle/HandleSnapshot.java' },
+	{ template: 'HandleRegistryRepository.java.tmpl', target: 'global/handle/HandleRegistryRepository.java' },
+	{ template: 'HandleSnapshotRepository.java.tmpl', target: 'global/handle/HandleSnapshotRepository.java' },
+	{ template: 'ResourceResolver.java.tmpl', target: 'global/handle/ResourceResolver.java' },
+	{ template: 'HandleController.java.tmpl', target: 'global/handle/HandleController.java' },
+	// O4 (D-handle-lifecycle):
+	{ template: 'HandleService.java.tmpl', target: 'global/handle/HandleService.java' },
+	{ template: 'RecordHandleSnapshot.java.tmpl', target: 'global/handle/RecordHandleSnapshot.java' },
+	{ template: 'HandleAspect.java.tmpl', target: 'global/handle/HandleAspect.java' },
+];
+
+function render(templatePath, vars) {
+	let content = fs.readFileSync(templatePath, 'utf8');
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+function lowerFirst(s) {
+	return s.charAt(0).toLowerCase() + s.slice(1);
+}
+
+// A3 (D-patch-strategy): Spring Boot 4+ ships Jackson 3 as its primary JSON engine (package
+// `tools.jackson.databind`, NOT `com.fasterxml.jackson.databind`) -- confirmed by reading the
+// real oracle repo's own build.gradle (`id 'org.springframework.boot' version '4.1.0'`) AND its
+// own source (`SecurityConfig.java` imports `tools.jackson.databind.ObjectMapper`). A single
+// OTHER file in that same repo (`AiClient.java`) imports the classic `com.fasterxml.jackson`
+// package for a third-party AI SDK's own bundled Jackson 2 instance -- NOT what Spring actually
+// autoconfigures as the injectable `ObjectMapper` BEAN, so grepping "does any file mention this
+// import" would have been ambiguous/wrong here. The Spring Boot plugin's own major version is the
+// reliable signal: it determines which Jackson generation Spring's autoconfiguration wires up as
+// 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) {
+	const buildGradlePath = path.join(repoRoot, 'build.gradle');
+	if (!fs.existsSync(buildGradlePath)) return 'com.fasterxml.jackson.databind';
+	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 majorVersion !== null && majorVersion >= 4 ? 'tools.jackson.databind' : 'com.fasterxml.jackson.databind';
+}
+
+// The import block patchField() codegen needs, computed fresh every run
+// from the CURRENT classification + approvals (never cached against a prior emit) -- empty string
+// when nothing is approved yet, so a resource with no approved fields renders byte-identical to
+// one with no update endpoint at all.
+function buildPatchImports({ basePackage, module, dtoTypeName, needsPatchFieldImport, jacksonPackage }) {
+	const lines = [
+		`import ${basePackage}.domain.${module}.presentation.dto.${dtoTypeName};`,
+		'import jakarta.validation.ConstraintViolation;',
+		'import jakarta.validation.ConstraintViolationException;',
+		'import jakarta.validation.Validator;',
+		`import ${jacksonPackage}.ObjectMapper;`,
+		'import java.util.Set;',
+	];
+	if (needsPatchFieldImport) lines.push(`import ${basePackage}.global.json.PatchField;`);
+	return lines.map((l) => `${l}\n`).join('');
+}
+
+function buildPatchFields() {
+	return '\tprivate final Validator validator;\n\tprivate final ObjectMapper objectMapper;\n';
+}
+
+// The set of {resource, field} approvals whose recorded strategy still matches what the
+// classifier computes RIGHT NOW -- a stale approval (the DTO changed since approval) is excluded
+// here, not just skipped at codegen time, so callers never even have to reason about staleness
+// themselves. Fail-closed: a mismatch silently falls back to the "classified but not approved"
+// explanatory stub, exactly like never having been approved at all.
+function currentlyApprovedFields(approvals, resourceType, patchable) {
+	const approved = new Set();
+	for (const field of patchable) {
+		if (approvedStrategyFor(approvals, resourceType, field.field) === field.bucket) approved.add(field.field);
+	}
+	return approved;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, content);
+}
+
+// See DECISIONS.md D-handles-ownership for the full design; the conflict/manifest/force/orphan
+// logic itself now lives in handles/_engine.mjs (D-handles-providers, G4) -- this function's job
+// is purely to compute java-spring's own render/paths and hand them to emitUnits(). `force`/
+// `reason` overwrite any conflicted unit found within this call's own scope (already narrowed by
+// featureId/module/resourceFilter) -- never a blanket, unscoped force. `resourceFilter` (the same
+// array plan() was called with, or null) turns off orphan detection when non-null, since a scoped
+// run would otherwise report every OTHER resource's resolver as orphaned.
+export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const javaSrcRoot = path.join(repoRoot, 'src', 'main', 'java', ...basePackage.split('.'));
+
+	// A3 (D-patch-strategy): loaded/detected once per emit call -- approvals are feature-scoped
+	// (not per-resource) and the Jackson package is repo-wide, so one computation each covers
+	// every resource/infra file this call touches (O4/D-handle-lifecycle: HandleService.java.tmpl
+	// now needs jacksonPackage too, for the same reason patch codegen already did).
+	const patchApprovals = loadPatchApprovals(repoRoot, featureId);
+	const jacksonPackage = detectJacksonPackage(repoRoot);
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(javaSrcRoot, f.target),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage }),
+	}));
+
+	// O4 (D-handle-lifecycle): every resource in THIS feature shares the same contract file and
+	// feature_uid, so the common case only computes this once. requireNamedGate(root, 'contract',
+	// ...) already ran before emitJavaSpring() is ever reached (cmdHandlesEmit's own
+	// precondition), so this feature's own contract file is guaranteed to exist here.
+	//
+	// Deliberately NOT reused verbatim inside pristineRenderFor() below for a DIFFERENT owner --
+	// O2's cross-feature adoption check re-renders using the ORIGINAL owner's feature_id
+	// specifically to compare against what THAT feature would have generated; baking in the
+	// CURRENT run's own contract_ref/feature_uid there would compare disk content against the
+	// wrong feature's values and manufacture a false conflict for an untouched file. Falls back to
+	// null/placeholder if the other feature's own contract/feature file no longer exists (e.g. it
+	// was deleted) -- an edge case, not the common path, but must not throw.
+	const contractRefFor = (id) => sha256File(specPath(repoRoot, id, 'contracts', `${id}.schema.json`));
+	const featureUidFor = (id) => loadFeatureFile(repoRoot, id)?.feature_uid ?? '00000000-0000-0000-0000-000000000000';
+	const contractRef = contractRefFor(featureId);
+	const featureUid = featureUidFor(featureId);
+
+	const resolverUnits = plan.resources
+		.filter((r) => r.willGenerateResolver) // see plan.mjs: no broken imports generated on purpose
+		.map((resource) => {
+			const patchable = resource.patchable ?? [];
+			// A blocked update service (see plan.mjs's updateServiceBlockedReason) means NO field of
+			// this resource can be auto-generated regardless of approvals -- ignore any recorded
+			// approvals for its codegen-needs computation, but the classification itself still renders
+			// (see renderPatchFieldBody's blockedReason handling).
+			const approvedFields = resource.updateServiceBlockedReason ? new Set() : currentlyApprovedFields(patchApprovals, resource.type, patchable);
+			const { needsValidation, needsPatchFieldImport } = computeCodegenNeeds(patchable, approvedFields);
+			const serviceField = lowerFirst(resource.service.serviceType);
+			const vars = {
+				BASE_PACKAGE: basePackage,
+				MODULE: plan.module,
+				RESOURCE_TYPE: resource.type,
+				SERVICE_IMPORT: `${basePackage}.domain.${plan.module}.application.${resource.service.serviceType}`,
+				SERVICE_TYPE: resource.service.serviceType,
+				SERVICE_FIELD: serviceField,
+				FETCH_METHOD: resource.fetchOperation.method,
+				REQUIRED_AUTHORITY: resource.requiredAuthority,
+				FEATURE_ID: featureId,
+				CONTRACT_REF: contractRef,
+				FEATURE_UID: featureUid,
+				PATCH_IMPORTS: needsValidation ? buildPatchImports({ basePackage, module: plan.module, dtoTypeName: resource.dtoTypeName, needsPatchFieldImport, jacksonPackage }) : '',
+				PATCH_FIELDS: needsValidation ? buildPatchFields() : '',
+				PATCH_FIELD_BODY: renderPatchFieldBody({
+					resourceType: resource.type,
+					dtoTypeName: resource.dtoTypeName,
+					patchable,
+					updateOperation: resource.updateOperation,
+					serviceField,
+					approvedFields,
+					blockedReason: resource.updateServiceBlockedReason,
+				}),
+			};
+			return {
+				id: 'ResourceResolverStub.java.tmpl',
+				resourceType: resource.type,
+				module: plan.module,
+				templatePath: RESOLVER_TEMPLATE,
+				targetAbs: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure', `${resource.type}Resolver.java`),
+				rendered: render(RESOLVER_TEMPLATE, vars),
+				pristineRenderFor: (ownerId) => render(RESOLVER_TEMPLATE, {
+				...vars,
+				FEATURE_ID: ownerId,
+				CONTRACT_REF: ownerId === featureId ? contractRef : contractRefFor(ownerId),
+				FEATURE_UID: ownerId === featureId ? featureUid : featureUidFor(ownerId),
+			}),
+			};
+		});
+
+	const orphanScan = (!resourceFilter && plan.module) ? {
+		dir: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure'),
+		module: plan.module,
+		matchesFile: (file) => file.endsWith('Resolver.java'),
+		resourceTypeOf: (file, _content) => file.replace(/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 });
+	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);
+
+	return {
+		...result,
+		postEmitNotes: [
+			'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
+			// O4 (D-handle-lifecycle): HandleAspect.java only actually intercepts anything once a
+			// human applies @RecordHandleSnapshot to a real service method AND the target repo has
+			// this dependency -- never auto-added to build.gradle, same "review and apply yourself"
+			// boundary as the migration note above.
+			'NOT done automatically: HandleAspect.java requires spring-boot-starter-aop on your own build.gradle classpath (Spring AOP is not enabled by any other starter). Add it yourself before applying @RecordHandleSnapshot to any service method.',
+		],
+	};
+}

package/handles/providers/java-spring/patch-strategy.mjs

@@ -0,0 +1,229 @@
+// A3 (D-patch-strategy): classifies each field of an update-request DTO record into one of the
+// four partial-update conventions D-resolver-scope already found in the real oracle repo, from
+// static analysis alone -- no guessing beyond what the DTO's own type/annotations declare.
+//
+// Reuses _java-spring-analyzer.mjs's maskNonCode()/matchBalanced()/skipAnnotationsAndWhitespace()
+// (A2 Phase 1's proven infra) rather than duplicating regex-based Java parsing -- classification
+// operates entirely on MASKED text; no original-text value (e.g. a @Schema description string) is
+// ever needed to decide a field's bucket, only its type/annotation structure, which masking
+// preserves 1:1 outside comments/string interiors.
+import { maskNonCode, matchBalanced, findClassOrRecordDeclaration, skipAnnotationsAndWhitespace } from '../../../scanners/adapters/_java-spring-analyzer.mjs';
+
+export const PATCH_STRATEGY = Object.freeze({
+	PATCH_WRAPPER: 'patch-wrapper',
+	NULL_MEANS_UNCHANGED: 'null-means-unchanged',
+	FETCH_MERGE_SUBMIT: 'fetch-merge-submit',
+	UNSUPPORTED: 'unsupported',
+});
+
+// Only the two buckets where reconstructing "everything else stays absent" carries no risk of
+// silently carrying a stale sibling field -- see D-patch-strategy in DECISIONS.md for why
+// fetch-merge-submit is deliberately excluded even though it's classified just as precisely.
+export const CODEGEN_ELIGIBLE = Object.freeze([PATCH_STRATEGY.PATCH_WRAPPER, PATCH_STRATEGY.NULL_MEANS_UNCHANGED]);
+
+// Primitive Java types can never be null -- a field declared as one of these cannot represent
+// "omitted", so it can only ever mean "must always be resubmitted" (fetch-merge-submit), the same
+// bucket a boxed-but-@NotNull type gets. No real DTO in the oracle repo's grounding used a
+// primitive for a genuinely-optional field (Bean Validation on a partial-update DTO always uses
+// the boxed type precisely so absence is representable) -- this matches that convention exactly
+// rather than special-casing it.
+const PRIMITIVE_TYPES = new Set(['int', 'long', 'short', 'byte', 'char', 'boolean', 'float', 'double']);
+
+// Splits a record's parameter-list text (already masked) into its top-level components, treating
+// BOTH `<...>` (generics) and `(...)` (annotation argument lists, e.g. `@Schema(description = "",
+// nullable = true)`) as non-splitting depth. Deliberately NOT a reuse of plan.mjs's
+// countTopLevelCommas() (D-security-8, only tracks `<`/`>`, locked/untouched by this item) --
+// record components routinely carry parenthesized annotation args before the type, which that
+// narrower helper was never built to handle, so this is a fresh, purpose-built splitter rather
+// than stretching security-critical code to a new job.
+export function splitTopLevelParams(maskedParamsText) {
+	const params = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < maskedParamsText.length; i++) {
+		const ch = maskedParamsText[i];
+		if (ch === '<' || ch === '(') depth++;
+		else if (ch === '>' || ch === ')') depth = Math.max(0, depth - 1);
+		else if (ch === ',' && depth === 0) {
+			params.push(maskedParamsText.slice(start, i));
+			start = i + 1;
+		}
+	}
+	const last = maskedParamsText.slice(start);
+	if (last.trim() !== '') params.push(last);
+	return params.map((p) => p.trim()).filter(Boolean);
+}
+
+// From one masked parameter segment (e.g. `PatchField<Long> monthlyTokenLimit` or `@NotNull
+// OrganizationStatus status`), extracts { fieldName, baseType, generic, isArray } -- generic is
+// the raw text inside `<...>` when present (e.g. "Long"), null otherwise. Returns null if the
+// segment isn't shaped like `[annotations] Type[<...>][[]] name` at all (defensive -- should
+// never happen against a real record component, but a malformed/unrecognized shape must fail
+// closed to `unsupported`, never be silently misclassified).
+export function extractTypeAndName(maskedSegment) {
+	const afterAnnotations = skipAnnotationsAndWhitespace(maskedSegment, 0);
+	const rest = maskedSegment.slice(afterAnnotations);
+	const idMatch = rest.match(/^[\w.]+/);
+	if (!idMatch) return null;
+	let i = idMatch[0].length;
+	let generic = null;
+	if (rest[i] === '<') {
+		const close = matchBalanced(rest, i, '<', '>');
+		if (close === -1) return null;
+		generic = rest.slice(i + 1, close).trim();
+		i = close + 1;
+	}
+	let isArray = false;
+	while (rest.slice(i, i + 2) === '[]') {
+		isArray = true;
+		i += 2;
+	}
+	const nameMatch = rest.slice(i).trim().match(/^(\w+)/);
+	if (!nameMatch) return null;
+	return { fieldName: nameMatch[1], baseType: idMatch[0], generic, isArray };
+}
+
+// The classification rule itself -- see D-patch-strategy in DECISIONS.md for the real DTOs each
+// branch was confirmed against (UpdateOperationSettingRequest.monthlyTokenLimit for patch-wrapper,
+// UpdateOrganizationRequest.status for fetch-merge-submit, UpdateClassroomManagersRequest.
+// managerIds for unsupported, and the majority-case plain-nullable fields for null-means-unchanged).
+function classifyParam(maskedSegment) {
+	const hasNotNull = /@NotNull\b/.test(maskedSegment);
+	const hasValid = /@Valid\b/.test(maskedSegment);
+	const parsed = extractTypeAndName(maskedSegment);
+	if (!parsed) return null;
+	const { fieldName, baseType, generic, isArray } = parsed;
+
+	let bucket;
+	let convertType = baseType;
+	if (baseType === 'PatchField') {
+		// PatchField<T> already IS the "presence-optional, null-has-meaning" convention -- takes
+		// priority over any co-occurring @NotNull, which would be a contradictory/unused combination
+		// never seen in the oracle repo's grounding.
+		bucket = PATCH_STRATEGY.PATCH_WRAPPER;
+		convertType = generic ?? 'Object';
+	} else if (isArray || hasValid || ['List', 'Set', 'Map'].includes(baseType)) {
+		bucket = PATCH_STRATEGY.UNSUPPORTED;
+	} else if (hasNotNull || PRIMITIVE_TYPES.has(baseType)) {
+		bucket = PATCH_STRATEGY.FETCH_MERGE_SUBMIT;
+	} else {
+		bucket = PATCH_STRATEGY.NULL_MEANS_UNCHANGED;
+	}
+
+	return { field: fieldName, javaType: baseType, generic, bucket, convertType };
+}
+
+// The blanket stub -- byte-identical to the pre-A3 template text, used whenever a resource has no
+// classified patchable fields at all (no update endpoint found, no DTO resolved, or a non-record
+// DTO). Keeping this exact wording means a resource that never gets an update endpoint stays
+// completely unaffected by this item, not just functionally but textually.
+function blanketStub(resourceType) {
+	return [
+		'\t\t// TODO: route through the real update method, matching whichever partial-update',
+		"\t\t// convention the target field's DTO actually uses. Do not write directly to the",
+		'\t\t// repository/entity -- that bypasses this codebase\'s existing validation and business',
+		'\t\t// rules, which is the entire reason handles route through the service layer instead of raw SQL.',
+		'\t\tthrow new UnsupportedOperationException(',
+		`\t\t\t\t"patchField not yet implemented for ${resourceType}" + pointer + " -- see this class's javadoc");`,
+	].join('\n');
+}
+
+// One `case "/field" -> throw ...` explaining EXACTLY why this specific field isn't generated --
+// D-patch-strategy's whole point is replacing "read three paragraphs and guess" with a precise
+// per-field reason, so even the non-codegen branches stay field-specific, never lumped into one
+// generic message.
+function caseThrow(field, resourceType, reasonText) {
+	return `\t\t\tcase "/${field.field}" -> throw new UnsupportedOperationException(\n\t\t\t\t\t"patchField not auto-generated for ${resourceType}/${field.field} -- ${reasonText}");`;
+}
+
+function caseCodegen(field, { resourceType, dtoTypeName, updateOperation, serviceField, patchable }) {
+	const args = patchable.map((f) => {
+		if (f.field !== field.field) return 'null';
+		return f.bucket === PATCH_STRATEGY.PATCH_WRAPPER ? 'PatchField.of(convertedValue)' : 'convertedValue';
+	}).join(', ');
+	return [
+		`\t\t\tcase "/${field.field}" -> {`,
+		`\t\t\t\t${field.convertType} convertedValue = objectMapper.convertValue(value, ${field.convertType}.class);`,
+		`\t\t\t\t${dtoTypeName} patch = new ${dtoTypeName}(${args});`,
+		// O4 (D-handle-lifecycle): validateProperty, NOT validate(patch) -- a plain validate()
+		// checks every OTHER field on the reconstructed DTO too, so any @NotNull/primitive
+		// sibling (correctly classified as fetch-merge-submit, left null here on purpose) would
+		// ALWAYS fail validation for this field's own genuinely valid patch. Confirmed live: a
+		// real jakarta.validation.Validator run against this exact reconstruction threw on
+		// "ownerName" even when only "label" was being patched; validateProperty(patch, "${field.field}")
+		// scopes validation to just the field actually being changed, matching what a real
+		// single-field patch is supposed to validate.
+		`\t\t\t\tSet<ConstraintViolation<${dtoTypeName}>> violations = validator.validateProperty(patch, "${field.field}");`,
+		'\t\t\t\tif (!violations.isEmpty()) {',
+		'\t\t\t\t\tthrow new ConstraintViolationException(violations);',
+		'\t\t\t\t}',
+		`\t\t\t\t${serviceField}.${updateOperation.method}(resourceUid, patch);`,
+		'\t\t\t}',
+	].join('\n');
+}
+
+// Whether this resource's generated resolver needs the validation/conversion machinery at all
+// (Validator + ObjectMapper fields, their imports, Set/ConstraintViolation/
+// ConstraintViolationException imports, the DTO type's own import) and separately whether it
+// needs PatchField's import specifically -- both are ONLY true when at least one field actually
+// gets real codegen (an approved, currently-matching, codegen-eligible field), never merely
+// because a field is classified. A resource with fields classified but none approved yet renders
+// zero extra imports/fields, keeping it identical to a resource with no update endpoint at all
+// until a human actually approves something.
+export function computeCodegenNeeds(patchable, approvedFields) {
+	const codegenFields = patchable.filter((f) => CODEGEN_ELIGIBLE.includes(f.bucket) && approvedFields.has(f.field));
+	return {
+		needsValidation: codegenFields.length > 0,
+		needsPatchFieldImport: codegenFields.some((f) => f.bucket === PATCH_STRATEGY.PATCH_WRAPPER),
+	};
+}
+
+// Renders the FULL body of patchField() (everything between its `{`/`}`) -- one `case` per
+// classified field (real codegen for an approved eligible field, an explanatory throw for
+// everything else), or the untouched blanket stub when there's nothing classified at all.
+// `approvedFields` is a Set of field names whose CURRENT classification the caller has already
+// confirmed matches an existing approval (see lib/patch-approvals.mjs's approvedStrategyFor) --
+// this function trusts that check rather than re-deriving it, keeping the "is this approval still
+// valid" decision in exactly one place.
+export function renderPatchFieldBody({ resourceType, dtoTypeName, patchable, updateOperation, serviceField, approvedFields, blockedReason = null }) {
+	if (patchable.length === 0) return blanketStub(resourceType);
+	const cases = patchable.map((field) => {
+		// The classification is real and still worth showing per-field, but if the update SERVICE
+		// method itself isn't safely callable with the (id, dto) shape every codegen path assumes,
+		// no field of this resource can be generated regardless of its own bucket -- one shared
+		// reason, not a per-bucket one, since the blocker isn't about any single field.
+		if (blockedReason) return caseThrow(field, resourceType, blockedReason);
+		if (!CODEGEN_ELIGIBLE.includes(field.bucket)) {
+			const reasonText = field.bucket === PATCH_STRATEGY.FETCH_MERGE_SUBMIT
+				? 'classified as fetch-merge-submit -- this field is required (or the DTO is otherwise not partial), so patching it safely means fetching the current resource and resubmitting the full request with only this field changed. Not auto-generated (see D-patch-strategy in DECISIONS.md) -- route through the real update path by hand.'
+				: 'classified as unsupported (a collection, nested @Valid object, or array field) -- not safely expressible as a single scalar patch. Route through the real update path by hand.';
+			return caseThrow(field, resourceType, reasonText);
+		}
+		if (!approvedFields.has(field.field)) {
+			return caseThrow(field, resourceType, `classified as ${field.bucket} but not yet approved -- run \`bskel handles patch approve --feature <id> --resource ${resourceType} --field ${field.field} --strategy ${field.bucket} --reason "..."\` to enable codegen for this field.`);
+		}
+		return caseCodegen(field, { resourceType, dtoTypeName, updateOperation, serviceField, patchable });
+	}).join('\n');
+	return `\t\tswitch (pointer) {\n${cases}\n\t\t\tdefault -> throw new UnsupportedOperationException(\n\t\t\t\t\t"patchField not implemented for ${resourceType}" + pointer + " -- see this class's javadoc");\n\t\t}`;
+}
+
+// Entry point: classifies every component of a DTO record found in `dtoSourceText`. Returns
+// `{ resourceType, fields }`, or null if no top-level `record` declaration is found (this item
+// only supports record-shaped update DTOs -- the only shape found across all 17 real update DTOs
+// in the oracle repo; a class-shaped update DTO is a documented gap, not silently guessed at).
+export function classifyDtoFields(dtoSourceText) {
+	const masked = maskNonCode(dtoSourceText);
+	const decl = findClassOrRecordDeclaration(masked);
+	if (!decl || decl.keyword !== 'record') return null;
+
+	const nameEnd = masked.indexOf(decl.name, decl.index) + decl.name.length;
+	let i = nameEnd;
+	while (/\s/.test(masked[i])) i++;
+	if (masked[i] !== '(') return null;
+	const close = matchBalanced(masked, i, '(', ')');
+	if (close === -1) return null;
+
+	const maskedParamsText = masked.slice(i + 1, close);
+	const fields = splitTopLevelParams(maskedParamsText).map(classifyParam).filter(Boolean);
+	return { resourceType: decl.name, fields };
+}