backend-skeleton 1.4.0 → 1.6.0

package/handles/providers/java-spring/ast-helper/src/main/java/com/backendskeleton/asthelper/Main.java

@@ -1,21 +1,35 @@
 package com.backendskeleton.asthelper;
 
+import com.github.javaparser.JavaParser;
 import com.github.javaparser.ParserConfiguration;
+import com.github.javaparser.ParseResult;
+import com.github.javaparser.Problem;
+import com.github.javaparser.Range;
 import com.github.javaparser.StaticJavaParser;
 import com.github.javaparser.ast.CompilationUnit;
 import com.github.javaparser.ast.ImportDeclaration;
+import com.github.javaparser.ast.body.FieldDeclaration;
+import com.github.javaparser.ast.body.MethodDeclaration;
 import com.github.javaparser.ast.body.Parameter;
 import com.github.javaparser.ast.body.RecordDeclaration;
+import com.github.javaparser.ast.body.TypeDeclaration;
+import com.github.javaparser.ast.body.VariableDeclarator;
 import com.github.javaparser.ast.expr.AnnotationExpr;
+import com.github.javaparser.ast.stmt.BlockStmt;
 import com.github.javaparser.ast.type.Type;
 import com.github.javaparser.symbolsolver.JavaSymbolSolver;
 import com.github.javaparser.symbolsolver.resolution.typesolvers.CombinedTypeSolver;
 import com.github.javaparser.symbolsolver.resolution.typesolvers.JavaParserTypeSolver;
 import com.github.javaparser.symbolsolver.resolution.typesolvers.ReflectionTypeSolver;
 
+import java.io.BufferedReader;
+import java.io.ByteArrayOutputStream;
 import java.io.File;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Path;
+import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -50,6 +64,19 @@ public final class Main {
 	}
 
 	public static void main(String[] args) throws Exception {
+		// D-java-source-splice: two new modes, dispatched on a literal args[0] match -- "locate" and
+		// "parse" can never collide with a real DTO file path (relative or absolute paths always
+		// contain a path separator or a file extension), so the pre-existing 2-positional-arg
+		// classify invocation below is completely unaffected and untouched.
+		if (args.length >= 1 && "locate".equals(args[0])) {
+			runLocate(args);
+			return;
+		}
+		if (args.length >= 2 && "parse".equals(args[0]) && "-".equals(args[1])) {
+			runParse();
+			return;
+		}
+
 		if (args.length < 2) {
 			System.err.println("usage: Main <dto-file-path> <src-root>");
 			System.exit(2);
@@ -175,4 +202,384 @@ public final class Main {
 		sb.append('"');
 		return sb.toString();
 	}
+
+	// ---------------------------------------------------------------------------------------
+	// D-java-source-splice: "locate" mode -- the authoritative node locator for the new
+	// java-source-splice patch kind. Resolves a method/field member inside a SINGLE top-level
+	// type by its erased parameter-type signature (a real javac uniqueness rule, not a
+	// heuristic -- two methods in one type can never share both a name and the same erased
+	// parameter types). Reports every top-level type in the file so the Node-side caller can
+	// refuse when the file declares more than one (V1 scope restriction, enforced on the Node
+	// side, not here). Every field on a locate result is line/column, 1-based, INCLUSIVE on
+	// both ends (JavaParser's own Range convention) -- the Node side converts to a byte offset
+	// itself and self-validates by slicing the real file text and asserting it equals
+	// regionText/signatureText exactly, so an offset-conversion bug here fails closed rather
+	// than silently corrupting a splice.
+	// ---------------------------------------------------------------------------------------
+
+	private static void runLocate(String[] args) throws Exception {
+		if (args.length < 4) {
+			System.err.println("usage: Main locate <java-file> <src-root> <locators-file>");
+			System.exit(2);
+		}
+		String javaFile = args[1];
+		String srcRoot = args[2];
+		String locatorsFile = args[3];
+
+		List<Locator> locators = readLocators(locatorsFile);
+
+		CombinedTypeSolver typeSolver = new CombinedTypeSolver();
+		typeSolver.add(new ReflectionTypeSolver());
+		typeSolver.add(new JavaParserTypeSolver(new File(srcRoot)));
+		StaticJavaParser.getParserConfiguration().setLanguageLevel(ParserConfiguration.LanguageLevel.JAVA_17);
+		StaticJavaParser.getParserConfiguration().setSymbolResolver(new JavaSymbolSolver(typeSolver));
+
+		// Read the RAW file text separately from parsing it -- confirmed live, not assumed: JavaParser
+		// Node#toString() invokes its own PrettyPrinter (default 4-space reformatting) rather than
+		// returning literal source bytes. A first draft used body.toString() for regionText/
+		// signatureText and it silently NORMALIZED the real file's tab indentation to spaces --
+		// caught immediately by the Node-side self-validating offset check (D5, mechanism 2) refusing
+		// with a "does not match" error, exactly the failure mode that check exists to catch. Every
+		// regionText/signatureText below is now a real substring of `rawText`, sliced by Range, never
+		// a re-printed node.
+		String rawText = Files.readString(Path.of(javaFile), StandardCharsets.UTF_8);
+
+		CompilationUnit cu = StaticJavaParser.parse(Path.of(javaFile));
+
+		List<String> topLevelTypeNames = new ArrayList<>();
+		for (TypeDeclaration<?> t : cu.getTypes()) {
+			topLevelTypeNames.add(fqnOf(t));
+		}
+
+		StringBuilder json = new StringBuilder();
+		json.append("{\"topLevelTypes\":[");
+		for (int i = 0; i < topLevelTypeNames.size(); i++) {
+			if (i > 0) json.append(',');
+			json.append(jsonString(topLevelTypeNames.get(i)));
+		}
+		json.append("],\"results\":[");
+		for (int i = 0; i < locators.size(); i++) {
+			if (i > 0) json.append(',');
+			appendLocateResult(json, cu, locators.get(i), rawText);
+		}
+		json.append("]}");
+		System.out.println(json);
+	}
+
+	/**
+	 * 1-based line, 1-based column (JavaParser's own Range convention, both ends INCLUSIVE) -> a
+	 * real substring of `text`. The Node-side `lineColToOffset()` is the same algorithm,
+	 * independently implemented -- this is the Java-side half of D5's mechanism 2 (the
+	 * self-validating offset conversion), not a shared implementation, so a bug in one cannot
+	 * silently agree with a matching bug in the other.
+	 */
+	private static String sliceByRange(String text, int beginLine, int beginColumn, int endLine, int endColumn) {
+		int start = lineColToIndex(text, beginLine, beginColumn);
+		int endInclusive = lineColToIndex(text, endLine, endColumn);
+		return text.substring(start, endInclusive + 1);
+	}
+
+	private static int lineColToIndex(String text, int line, int column) {
+		int idx = 0;
+		int currentLine = 1;
+		while (currentLine < line) {
+			int nl = text.indexOf('\n', idx);
+			if (nl < 0) throw new IllegalStateException("line " + line + " exceeds the file's actual line count");
+			idx = nl + 1;
+			currentLine++;
+		}
+		return idx + (column - 1);
+	}
+
+	private static String fqnOf(TypeDeclaration<?> t) {
+		return t.getFullyQualifiedName().orElse(t.getNameAsString());
+	}
+
+	/** One locator request read from the locators file -- see readLocators() for the on-disk shape. */
+	private static final class Locator {
+		String typeFqn;
+		String memberKind; // "method" | "field"
+		String memberName;
+		List<String> paramTypes; // method only; empty for field
+	}
+
+	/**
+	 * Plain, delimiter-free line format (deliberately not JSON -- this helper has no JSON parser
+	 * dependency, and this format needs none, since every field is a single line with no
+	 * embedded newlines possible in a Java identifier/FQN):
+	 * <pre>
+	 * &lt;locator count N&gt;
+	 * &lt;type_fqn&gt;
+	 * &lt;member_kind&gt;
+	 * &lt;member_name&gt;
+	 * &lt;param count&gt;
+	 * &lt;param type 1&gt;
+	 * ...
+	 * &lt;param type param-count&gt;
+	 * (repeated N times)
+	 * </pre>
+	 */
+	private static List<Locator> readLocators(String locatorsFile) throws Exception {
+		List<String> lines = Files.readAllLines(Path.of(locatorsFile), StandardCharsets.UTF_8);
+		List<Locator> out = new ArrayList<>();
+		int i = 0;
+		int count = Integer.parseInt(lines.get(i++).trim());
+		for (int n = 0; n < count; n++) {
+			Locator loc = new Locator();
+			loc.typeFqn = lines.get(i++);
+			loc.memberKind = lines.get(i++);
+			loc.memberName = lines.get(i++);
+			int paramCount = Integer.parseInt(lines.get(i++).trim());
+			loc.paramTypes = new ArrayList<>();
+			for (int p = 0; p < paramCount; p++) loc.paramTypes.add(lines.get(i++));
+			out.add(loc);
+		}
+		return out;
+	}
+
+	/** Strips generic type arguments for an erasure-level comparison, e.g. "java.util.List<java.lang.String>" -> "java.util.List". Handles one level of nesting, sufficient for this kind's V1 scope (no nested-generic locator inputs are attempted). */
+	private static String eraseGenerics(String describedType) {
+		int lt = describedType.indexOf('<');
+		return lt < 0 ? describedType : describedType.substring(0, lt);
+	}
+
+	private static void appendLocateResult(StringBuilder json, CompilationUnit cu, Locator loc, String rawText) {
+		TypeDeclaration<?> target = null;
+		for (TypeDeclaration<?> t : cu.getTypes()) {
+			if (fqnOf(t).equals(loc.typeFqn)) {
+				target = t;
+				break;
+			}
+		}
+		if (target == null) {
+			appendUnresolved(json, "no top-level type named \"" + loc.typeFqn + "\" in this file");
+			return;
+		}
+
+		if ("field".equals(loc.memberKind)) {
+			appendFieldLocateResult(json, target, loc, rawText);
+			return;
+		}
+		appendMethodLocateResult(json, target, loc, rawText);
+	}
+
+	private static void appendMethodLocateResult(StringBuilder json, TypeDeclaration<?> target, Locator loc, String rawText) {
+		List<MethodDeclaration> candidates = new ArrayList<>();
+		for (Object member : target.getMembers()) {
+			if (member instanceof MethodDeclaration m && m.getNameAsString().equals(loc.memberName)) {
+				candidates.add(m);
+			}
+		}
+		if (candidates.isEmpty()) {
+			appendUnresolved(json, "no method named \"" + loc.memberName + "\" in \"" + loc.typeFqn + "\"");
+			return;
+		}
+
+		MethodDeclaration matched = null;
+		List<String> matchedErased = null;
+		List<String> matchedUnresolved = null;
+		int matchCount = 0;
+		for (MethodDeclaration m : candidates) {
+			List<Parameter> params = m.getParameters();
+			if (params.size() != loc.paramTypes.size()) continue;
+			List<String> erased = new ArrayList<>();
+			List<String> unresolved = new ArrayList<>();
+			boolean allResolved = true;
+			for (Parameter p : params) {
+				try {
+					erased.add(eraseGenerics(p.getType().resolve().describe()));
+				} catch (Exception e) {
+					erased.add(null);
+					unresolved.add(p.getNameAsString());
+					allResolved = false;
+				}
+			}
+			if (!allResolved) continue; // an unresolved param can never be asserted to MATCH a request
+			boolean paramsEqual = true;
+			for (int k = 0; k < erased.size(); k++) {
+				if (!erased.get(k).equals(loc.paramTypes.get(k))) {
+					paramsEqual = false;
+					break;
+				}
+			}
+			if (paramsEqual) {
+				matched = m;
+				matchedErased = erased;
+				matchedUnresolved = unresolved;
+				matchCount++;
+			}
+		}
+
+		if (matchCount == 0) {
+			// Report the nearest miss for diagnostics: if there's exactly one same-name candidate,
+			// show what its real (possibly unresolved) erased param types actually are.
+			if (candidates.size() == 1) {
+				MethodDeclaration only = candidates.get(0);
+				List<String> unresolved = new ArrayList<>();
+				List<String> erasedOrRaw = new ArrayList<>();
+				for (Parameter p : only.getParameters()) {
+					try {
+						erasedOrRaw.add(eraseGenerics(p.getType().resolve().describe()));
+					} catch (Exception e) {
+						erasedOrRaw.add(p.getType().asString());
+						unresolved.add(p.getNameAsString());
+					}
+				}
+				appendUnresolved(json, "\"" + loc.memberName + "\" was found but its parameter types do not match the given locator", erasedOrRaw, unresolved);
+			} else {
+				appendUnresolved(json, "\"" + loc.memberName + "\" has " + candidates.size() + " overload(s) but none match the given locator's parameter types");
+			}
+			return;
+		}
+		if (matchCount > 1) {
+			appendUnresolved(json, "\"" + loc.memberName + "\" locator matched " + matchCount + " overloads -- this should be impossible under javac's own erased-signature uniqueness rule; refusing rather than guessing");
+			return;
+		}
+
+		Optional<BlockStmt> bodyOpt = matched.getBody();
+		if (bodyOpt.isEmpty()) {
+			appendUnresolved(json, "\"" + loc.memberName + "\" has no body (abstract/interface method) -- nothing to splice");
+			return;
+		}
+		BlockStmt body = bodyOpt.get();
+		Range bodyRange = body.getRange().orElseThrow();
+		Range sigRange = signatureRange(matched.getRange().orElseThrow(), bodyRange);
+		String regionText = sliceByRange(rawText, bodyRange.begin.line, bodyRange.begin.column, bodyRange.end.line, bodyRange.end.column);
+		String signatureText = sliceByRange(rawText, sigRange.begin.line, sigRange.begin.column, sigRange.end.line, sigRange.end.column);
+
+		json.append("{\"resolved\":true")
+				.append(",\"beginLine\":").append(bodyRange.begin.line)
+				.append(",\"beginColumn\":").append(bodyRange.begin.column)
+				.append(",\"endLine\":").append(bodyRange.end.line)
+				.append(",\"endColumn\":").append(bodyRange.end.column)
+				.append(",\"regionText\":").append(jsonString(regionText))
+				.append(",\"signatureBeginLine\":").append(sigRange.begin.line)
+				.append(",\"signatureBeginColumn\":").append(sigRange.begin.column)
+				.append(",\"signatureEndLine\":").append(sigRange.end.line)
+				.append(",\"signatureEndColumn\":").append(sigRange.end.column)
+				.append(",\"signatureText\":").append(jsonString(signatureText))
+				.append(",\"erasedParamTypes\":[");
+		for (int k = 0; k < matchedErased.size(); k++) {
+			if (k > 0) json.append(',');
+			json.append(jsonString(matchedErased.get(k)));
+		}
+		json.append("],\"unresolvedParamTypes\":[");
+		for (int k = 0; k < matchedUnresolved.size(); k++) {
+			if (k > 0) json.append(',');
+			json.append(jsonString(matchedUnresolved.get(k)));
+		}
+		json.append("]}");
+	}
+
+	private static void appendFieldLocateResult(StringBuilder json, TypeDeclaration<?> target, Locator loc, String rawText) {
+		FieldDeclaration matched = null;
+		VariableDeclarator matchedVar = null;
+		int candidateFieldGroups = 0;
+		for (Object member : target.getMembers()) {
+			if (!(member instanceof FieldDeclaration f)) continue;
+			for (VariableDeclarator v : f.getVariables()) {
+				if (v.getNameAsString().equals(loc.memberName)) {
+					matched = f;
+					matchedVar = v;
+					candidateFieldGroups = f.getVariables().size();
+				}
+			}
+		}
+		if (matched == null) {
+			appendUnresolved(json, "no field named \"" + loc.memberName + "\" in \"" + loc.typeFqn + "\"");
+			return;
+		}
+		if (candidateFieldGroups != 1) {
+			appendUnresolved(json, "field \"" + loc.memberName + "\" is declared in a multi-variable declaration (e.g. \"int a, b;\") -- not supported, split it into its own declaration first");
+			return;
+		}
+		if (matchedVar.getInitializer().isEmpty()) {
+			appendUnresolved(json, "field \"" + loc.memberName + "\" has no initializer to replace");
+			return;
+		}
+
+		Range initRange = matchedVar.getInitializer().get().getRange().orElseThrow();
+		Range sigRange = signatureRange(matched.getRange().orElseThrow(), initRange);
+		String regionText = sliceByRange(rawText, initRange.begin.line, initRange.begin.column, initRange.end.line, initRange.end.column);
+		String signatureText = sliceByRange(rawText, sigRange.begin.line, sigRange.begin.column, sigRange.end.line, sigRange.end.column);
+
+		json.append("{\"resolved\":true")
+				.append(",\"beginLine\":").append(initRange.begin.line)
+				.append(",\"beginColumn\":").append(initRange.begin.column)
+				.append(",\"endLine\":").append(initRange.end.line)
+				.append(",\"endColumn\":").append(initRange.end.column)
+				.append(",\"regionText\":").append(jsonString(regionText))
+				.append(",\"signatureBeginLine\":").append(sigRange.begin.line)
+				.append(",\"signatureBeginColumn\":").append(sigRange.begin.column)
+				.append(",\"signatureEndLine\":").append(sigRange.end.line)
+				.append(",\"signatureEndColumn\":").append(sigRange.end.column)
+				.append(",\"signatureText\":").append(jsonString(signatureText))
+				.append(",\"erasedParamTypes\":[],\"unresolvedParamTypes\":[]}");
+	}
+
+	/**
+	 * [declBegin, memberEnd) where memberEnd is the position just before the body/initializer
+	 * starts -- i.e. everything from the first annotation/modifier through (and including) the
+	 * bytes right up to the opening brace or "=". Position has no left(int) (only right(int)),
+	 * so this shifts back one column directly; the degenerate column<=1 case (the body/
+	 * initializer starting at column 1 of a line, which real Java source essentially never does)
+	 * clamps to column 1 rather than going invalid -- harmless, since the Node-side
+	 * self-validation assertion (slice === signatureText) is the actual safety net either way.
+	 */
+	private static Range signatureRange(Range declRange, Range memberInnerRange) {
+		com.github.javaparser.Position b = memberInnerRange.begin;
+		com.github.javaparser.Position sigEnd = b.withColumn(Math.max(1, b.column - 1));
+		return new Range(declRange.begin, sigEnd);
+	}
+
+	private static void appendUnresolved(StringBuilder json, String error) {
+		appendUnresolved(json, error, List.of(), List.of());
+	}
+
+	private static void appendUnresolved(StringBuilder json, String error, List<String> erasedOrRaw, List<String> unresolved) {
+		json.append("{\"resolved\":false,\"error\":").append(jsonString(error))
+				.append(",\"erasedParamTypes\":[");
+		for (int k = 0; k < erasedOrRaw.size(); k++) {
+			if (k > 0) json.append(',');
+			json.append(jsonString(erasedOrRaw.get(k)));
+		}
+		json.append("],\"unresolvedParamTypes\":[");
+		for (int k = 0; k < unresolved.size(); k++) {
+			if (k > 0) json.append(',');
+			json.append(jsonString(unresolved.get(k)));
+		}
+		json.append("]}");
+	}
+
+	// ---------------------------------------------------------------------------------------
+	// D-java-source-splice: "parse -" mode -- a plain syntax gate for a candidate rendered file,
+	// read from stdin (build.gradle's `run { standardInput = System.in }` already wires this),
+	// used at propose time on RENDERED content that has not been written to disk yet. Fresh,
+	// solver-free JavaParser instance -- a syntax check needs no classpath/src-root at all.
+	// ---------------------------------------------------------------------------------------
+
+	private static void runParse() throws Exception {
+		ByteArrayOutputStream buf = new ByteArrayOutputStream();
+		try (BufferedReader reader = new BufferedReader(new InputStreamReader(System.in, StandardCharsets.UTF_8))) {
+			int c;
+			while ((c = reader.read()) != -1) buf.write(c);
+		}
+		String source = buf.toString(StandardCharsets.UTF_8);
+
+		JavaParser parser = new JavaParser(new ParserConfiguration().setLanguageLevel(ParserConfiguration.LanguageLevel.JAVA_17));
+		ParseResult<CompilationUnit> result = parser.parse(source);
+
+		if (result.isSuccessful()) {
+			System.out.println("{\"ok\":true}");
+			return;
+		}
+		StringBuilder json = new StringBuilder("{\"ok\":false,\"problems\":[");
+		List<Problem> problems = result.getProblems();
+		for (int i = 0; i < problems.size(); i++) {
+			if (i > 0) json.append(',');
+			json.append(jsonString(problems.get(i).getVerboseMessage()));
+		}
+		json.append("]}");
+		System.out.println(json);
+	}
 }

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

@@ -7,6 +7,7 @@ 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';
+import { policyRequiresResolution } from './plan.mjs';
 
 const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
@@ -17,6 +18,10 @@ const RESOLVER_TEMPLATE = path.join(TEMPLATES_DIR, 'ResourceResolverStub.java.tm
 // this separate, always-safe-to-regenerate companion file rather than the same file as the
 // hand-editable patchField() body -- see the template's own javadoc and DECISIONS.md.
 const RESOLVER_POLICY_TEMPLATE = path.join(TEMPLATES_DIR, 'ResourceResolverPolicyStub.java.tmpl');
+// D-resolver-policy-contract (PC4): only ever emitted for a resource whose authorizationMode is
+// 'delegated' -- a generated interface bskel deliberately never implements (see the template's
+// own javadoc for the startup-failure mechanism this relies on).
+const AUTHZ_POLICY_TEMPLATE = path.join(TEMPLATES_DIR, 'AuthorizationPolicyStub.java.tmpl');
 
 const INFRA_FILES = [
 	{ template: 'HandleCodec.java.tmpl', target: 'global/handle/HandleCodec.java' },
@@ -128,6 +133,56 @@ function buildPatchFields() {
 	return '\tprivate final Validator validator;\n\tprivate final ObjectMapper objectMapper;\n';
 }
 
+// D-resolver-policy-contract (PC4): the three ResourceResolverStub.java.tmpl token builders below
+// all render '' for a materialized resource -- byte-identical output to before this item existed.
+// Only a 'delegated' resource (see plan.mjs's authorizationMode) gets non-empty values.
+function buildPolicyImport(basePackage, module, resourceType) {
+	return `import ${basePackage}.domain.${module}.infrastructure.${resourceType}AuthorizationPolicy;\n`;
+}
+
+function buildPolicyField(resourceType) {
+	return `\tprivate final ${resourceType}AuthorizationPolicy authorizationPolicy;\n`;
+}
+
+function buildPolicyOverrides(resourceType) {
+	return [
+		'',
+		'\t@Override',
+		'\tpublic String authorizationMode() {',
+		`\t\treturn ${resourceType}ResolverPolicy.authorizationMode();`,
+		'\t}',
+		'',
+		'\t@Override',
+		'\tpublic boolean authorize(Authentication authentication, String action, UUID resourceUid, String pointer) {',
+		'\t\treturn authorizationPolicy.authorize(authentication, action, resourceUid, pointer);',
+		'\t}',
+		'',
+	].join('\n');
+}
+
+function escapeJavadoc(s) {
+	return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// The AuthorizationPolicyStub.java.tmpl's own javadoc body -- one block per policies[] record that
+// actually NEEDS resolution (policyRequiresResolution() -- excludes the benign 'endpoint-absent'/
+// 'endpoint-method-absent' case, e.g. a read-only resource's nonexistent PATCH endpoint, so the
+// generated javadoc names only the real reason this file exists, never a distracting non-issue).
+// Only ever called for a resource that already has at least one such record (see the 'delegated'
+// gate below) -- the '' fallback exists for defensive completeness, not an expected path.
+function buildPolicyEvidenceJavadoc(policies) {
+	const lines = [];
+	for (const p of policies) {
+		if (!policyRequiresResolution(p)) continue;
+		const loc = p.evidence.file ? `${p.evidence.file}${p.evidence.line ? `:${p.evidence.line}` : ''}` : '(no source location)';
+		lines.push(` * <p><b>${escapeJavadoc(p.action)}</b>: {@code ${escapeJavadoc(p.evidence.kind)}} at ${escapeJavadoc(loc)}`);
+		if (p.evidence.symbol) lines.push(` * ({@code ${escapeJavadoc(p.evidence.symbol)}})`);
+		if (p.evidence.text) lines.push(` * <br>source: {@code ${escapeJavadoc(p.evidence.text)}}`);
+		if (p.reason) lines.push(` * <br>${escapeJavadoc(p.reason)}`);
+	}
+	return lines.length > 0 ? `${lines.join('\n')}\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
@@ -217,6 +272,11 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 			const { needsValidation, needsPatchFieldImport } = computeCodegenNeeds(patchable, approvedFields);
 			const serviceField = lowerFirst(resource.service.serviceType);
 			const sharedVars = { BASE_PACKAGE: basePackage, MODULE: plan.module, RESOURCE_TYPE: resource.type, FEATURE_ID: featureId };
+			// D-resolver-policy-contract (PC4): true only when plan.mjs's own refusal ladder
+			// (derivePolicy(), see plan.mjs) couldn't safely auto-derive a role-only check for
+			// fetch AND/OR patch -- one resource = one resolver bean = one mode, so either action
+			// being unresolved delegates the whole resolver (fail-closed by construction).
+			const delegated = resource.authorizationMode === 'delegated';
 			// D-resolver-policy-split: the resolver's own vars no longer include the four
 			// live-derived/security-relevant tokens -- those move to policyVars below, into a
 			// separate generated file, specifically so a hand-edited patchField() (which stales
@@ -238,6 +298,11 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 					approvedFields,
 					blockedReason: resource.updateServiceBlockedReason,
 				}),
+				// D-resolver-policy-contract (PC4): all three render '' for a materialized
+				// resource -- byte-identical output to before this item existed.
+				POLICY_IMPORT: delegated ? buildPolicyImport(basePackage, plan.module, resource.type) : '',
+				POLICY_FIELD: delegated ? buildPolicyField(resource.type) : '',
+				POLICY_OVERRIDES: delegated ? buildPolicyOverrides(resource.type) : '',
 			};
 			const policyVars = {
 				...sharedVars,
@@ -247,8 +312,11 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 				REQUIRED_AUTHORITY_PATCH: resource.requiredAuthorityForPatch,
 				CONTRACT_REF: contractRef,
 				FEATURE_UID: featureUid,
+				// D-resolver-policy-contract (PC2): always regenerated, regardless of mode -- see
+				// ResourceResolverPolicyStub.java.tmpl's own comment for why this is safe.
+				AUTHORIZATION_MODE: resource.authorizationMode ?? 'role',
 			};
-			return [
+			const units = [
 				{
 					id: 'ResourceResolverStub.java.tmpl',
 					resourceType: resource.type,
@@ -274,15 +342,32 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 					}),
 				},
 			];
+			if (delegated) {
+				const authzVars = { ...sharedVars, POLICY_EVIDENCE_JAVADOC: buildPolicyEvidenceJavadoc(resource.policies ?? []) };
+				units.push({
+					id: 'AuthorizationPolicyStub.java.tmpl',
+					resourceType: resource.type,
+					module: plan.module,
+					templatePath: AUTHZ_POLICY_TEMPLATE,
+					targetAbs: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure', `${resource.type}AuthorizationPolicy.java`),
+					rendered: render(AUTHZ_POLICY_TEMPLATE, authzVars),
+					pristineRenderFor: (ownerId) => render(AUTHZ_POLICY_TEMPLATE, { ...authzVars, FEATURE_ID: ownerId }),
+				});
+			}
+			return units;
 		});
 
 	const orphanScan = (!resourceFilter && plan.module) ? {
 		dir: path.join(javaSrcRoot, 'domain', plan.module, 'infrastructure'),
 		module: plan.module,
-		// D-resolver-policy-split: recognize both generated suffixes -- longest-first so
-		// 'FooResolverPolicy.java' isn't misclassified as a plain '...Policy' resource type.
-		matchesFile: (file) => file.endsWith('ResolverPolicy.java') || file.endsWith('Resolver.java'),
-		resourceTypeOf: (file, _content) => file.replace(/ResolverPolicy\.java$|Resolver\.java$/, ''),
+		// D-resolver-policy-split / D-resolver-policy-contract (PC11): recognize all three
+		// generated suffixes -- longest-first so 'FooAuthorizationPolicy.java'/'FooResolverPolicy.java'
+		// are never misclassified as a plain '...Policy'/'...Resolver' resource type. A resource
+		// that transitions unresolved -> materialized leaves its AuthorizationPolicy.java as a
+		// reported orphan (never auto-deleted, same never-delete bias D-migration-scope/
+		// D-config-patch already take for generated files bskel stops needing).
+		matchesFile: (file) => file.endsWith('AuthorizationPolicy.java') || file.endsWith('ResolverPolicy.java') || file.endsWith('Resolver.java'),
+		resourceTypeOf: (file, _content) => file.replace(/AuthorizationPolicy\.java$|ResolverPolicy\.java$|Resolver\.java$/, ''),
 	} : null;
 
 	// D-write-safety-phase0 (item 1): migration.sql used to be regenerated fresh every run,
@@ -331,5 +416,40 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 		}
 	}
 
-	return { ...result, postEmitNotes, registrationGaps };
+	// D-resolver-policy-contract (PC9): unconditional -- unlike registrationGaps above, this is NOT
+	// gated on enforceRegistry (an orthogonal axis: registry enforcement is about revocation/
+	// lifecycle and produces 404s; this is about authorization and produces a 403 or, for an
+	// unresolved resource, a boot failure). Ships default-on: bin/bskel.mjs blocks the gate on this
+	// unless --force --reason acknowledges it (same acknowledgement mechanism as registrationGaps).
+	const unresolvedPolicies = [];
+	for (const resource of plan.resources) {
+		if (!resource.willGenerateResolver) continue;
+		for (const p of resource.policies ?? []) {
+			// D-resolver-policy-contract (PC2 follow-up): excludes 'endpoint-absent'/
+			// 'endpoint-method-absent' -- see plan.mjs's policyRequiresResolution() for why (a
+			// read-only resource with no PATCH endpoint at all is a normal, common shape with
+			// nothing to protect, not the gap this item exists to close).
+			if (!policyRequiresResolution(p)) continue;
+			unresolvedPolicies.push({
+				resourceType: resource.type,
+				action: p.action,
+				kind: p.evidence.kind,
+				file: p.evidence.file,
+				line: p.evidence.line,
+				note: p.reason,
+			});
+		}
+	}
+	if (unresolvedPolicies.length > 0) {
+		const byResource = new Map();
+		for (const u of unresolvedPolicies) {
+			if (!byResource.has(u.resourceType)) byResource.set(u.resourceType, []);
+			byResource.get(u.resourceType).push(u.action);
+		}
+		for (const [resourceType, actions] of byResource) {
+			postEmitNotes.push(`${resourceType}: authorization could not be safely auto-derived for ${actions.join('/')} -- ${resourceType}AuthorizationPolicy.java was generated but is NOT implemented by anything. Your application will not start until a @Component implementing it exists. See that file's own javadoc for the exact evidence and reason.`);
+		}
+	}
+
+	return { ...result, postEmitNotes, registrationGaps, unresolvedPolicies };
 }