backend-skeleton 1.0.0-beta.1

package/handles/providers/java-spring/templates/HandleController.java.tmpl

@@ -0,0 +1,177 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{JACKSON_PACKAGE}}.ObjectMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * D-handles (DECISIONS.md): exposed in production. Per-resolver {@code requiredAuthority()} is
+ * the entire defense for this generic-object-accessor security surface -- a resolver that
+ * forgets to check something it should is a real vulnerability, not a theoretical one. Review
+ * new resolvers accordingly.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel handles emit}). Registered resolvers come from
+ * {@code Map<String, ResourceResolver>} auto-collected by Spring from all {@code @Component}
+ * beans implementing {@link ResourceResolver} -- keyed by BEAN NAME, not {@link
+ * ResourceResolver#type()}, so {@link #resolverFor} looks up by iterating and matching {@code
+ * type()} explicitly rather than assuming bean name == type.
+ */
+@RestController
+@RequestMapping("/handles")
+@RequiredArgsConstructor
+public class HandleController {
+
+	private final Map<String, ResourceResolver> resolversByBeanName;
+	private final HandleRegistryRepository handleRegistryRepository;
+	private final HandleSnapshotRepository handleSnapshotRepository;
+	private final ObjectMapper objectMapper;
+
+	@GetMapping("/{handle}")
+	public ResponseEntity<Object> fetch(@PathVariable String handle) {
+		HandleCodec.Decoded decoded = decodeOrThrow(handle);
+		ResourceResolver resolver = resolverFor(decoded.type());
+		requireAuthority(resolver.requiredAuthority());
+
+		Object resource = resolver.fetch(decoded.uuid());
+		if (decoded.pointer() == null) {
+			return ResponseEntity.ok(resource);
+		}
+		// O4 (D-handle-lifecycle): kind=f -- serialize the whole resource through the SAME
+		// ObjectMapper the rest of the app uses, then walk the RFC 6901 pointer via Jackson's own
+		// JsonNode#at (no hand-rolled walker needed here, unlike the JS reference implementation's
+		// resolveJsonPointer, which had no such built-in to reach for). A pointer that resolves to
+		// a genuinely missing node returns 404, not null/absent -- resolveJsonPointer's own JS
+		// behavior ("current == null -> return undefined") is preserved as "the field truly isn't
+		// there", not silently coerced to some other shape.
+		JsonNode root = objectMapper.valueToTree(resource);
+		JsonNode target = root.at(decoded.pointer());
+		if (target.isMissingNode()) {
+			throw new ResponseStatusException(HttpStatus.NOT_FOUND, "pointer \"" + decoded.pointer() + "\" does not resolve on " + decoded.type());
+		}
+		return ResponseEntity.ok(target);
+	}
+
+	@PatchMapping("/{handle}")
+	public ResponseEntity<Void> patch(@PathVariable String handle, @RequestBody Object value) {
+		HandleCodec.Decoded decoded = decodeOrThrow(handle);
+		// D-security-10: checks kind explicitly rather than inferring "field handle" from
+		// pointer-presence alone -- HandleCodec.decode() doesn't itself enforce that only kind=f
+		// carries a pointer (that's enforced on the encode side, see HandleCodec#encode), so a
+		// hand-crafted token of a reserved/future kind (e.g. kind=o) with a pointer appended must
+		// still be rejected here rather than treated as a field handle. Found by the Codex
+		// security review.
+		if (!decoded.kind().equals("f") || decoded.pointer() == null) {
+			throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "cannot PATCH a resource-level handle (kind=r) -- only field handles (kind=f) support PATCH");
+		}
+		ResourceResolver resolver = resolverFor(decoded.type());
+		requireAuthority(resolver.requiredAuthority());
+
+		resolver.patchField(decoded.uuid(), decoded.pointer(), value);
+		return ResponseEntity.noContent().build();
+	}
+
+	@GetMapping("/{handle}/recover")
+	public ResponseEntity<?> recover(@PathVariable String handle, @RequestParam(required = false) Instant at) {
+		HandleCodec.Decoded decoded = decodeOrThrow(handle);
+		ResourceResolver resolver = resolverFor(decoded.type());
+		requireAuthority(resolver.requiredAuthority());
+
+		UUID handleUid = HandleCodec.deriveHandleUid(decoded.kind(), decoded.type(), decoded.uuid(), decoded.pointer());
+
+		// D-security-9: handleUid alone does not prove WHAT is being recovered -- kind=r's
+		// derivation returns the resource UUID verbatim (no type binding baked into the hash), so
+		// an attacker who controls `type` in the handle token (as long as it names a real,
+		// registered resolver whose requiredAuthority() they can pass) can request the snapshot
+		// history of a DIFFERENT, more sensitive resource type that happens to share the same
+		// UUID. Found by the Codex security review. Fix: cross-check the decoded type/kind/pointer
+		// against the registry row this handleUid was actually registered under, and 404 on ANY
+		// disagreement -- without saying which field mismatched, so the error can't be used to
+		// probe which part was wrong. A revoked handle is rejected the same way; it must not be
+		// recoverable at all.
+		HandleRegistry registry = handleRegistryRepository.findById(handleUid)
+				.filter(r -> r.getResourceType().equals(decoded.type()))
+				.filter(r -> r.getKind().equals(decoded.kind()))
+				.filter(r -> Objects.equals(r.getPointer(), decoded.pointer()))
+				.filter(r -> !r.isRevoked())
+				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no snapshot recorded for this handle"));
+
+		List<HandleSnapshot> snapshots = handleSnapshotRepository.findByHandleUidOrderByRecordedAtDesc(handleUid);
+		Optional<HandleSnapshot> match = at == null
+				? snapshots.stream().findFirst()
+				: snapshots.stream().filter(s -> !s.getRecordedAt().isAfter(at)).findFirst();
+
+		if (match.isEmpty()) {
+			throw new ResponseStatusException(HttpStatus.NOT_FOUND, "no snapshot recorded for this handle" + (at != null ? " at or before " + at : ""));
+		}
+		HandleSnapshot snapshot = match.get();
+		// Reuses the registry row already fetched (and validated) above instead of querying again.
+		boolean drift = !registry.getContractRef().equals(snapshot.getContractHash());
+
+		// O4 (D-handle-lifecycle): snapshot.getPayload() is the raw JSON TEXT HandleService
+		// recorded (a Java String) -- embedding it into this response Map as-is would make
+		// Jackson serialize it as an ESCAPED JSON STRING VALUE, double-encoding a caller's real
+		// payload into something like "payload":"{\"name\":...}" instead of a normal nested
+		// object. Confirmed live (not assumed) by inspecting a real recover() response before
+		// this fix -- readTree parses it back into a JsonNode so it serializes as genuine nested
+		// JSON. A parse failure here means the stored payload isn't valid JSON at all, which only
+		// this app's own recordSnapshot() ever writes -- an internal invariant violation, not a
+		// caller-facing input error.
+		JsonNode payload;
+		try {
+			payload = objectMapper.readTree(snapshot.getPayload());
+		} catch (Exception e) {
+			throw new IllegalStateException("stored handle snapshot payload is not valid JSON", e);
+		}
+
+		return ResponseEntity.ok(Map.of(
+				"handle", handle,
+				"recorded_at", snapshot.getRecordedAt(),
+				"operation_id", snapshot.getOperationId(),
+				"payload", payload,
+				"schema_drift", drift
+		));
+	}
+
+	private HandleCodec.Decoded decodeOrThrow(String handle) {
+		try {
+			return HandleCodec.decode(handle);
+		} catch (IllegalArgumentException e) {
+			throw new ResponseStatusException(HttpStatus.BAD_REQUEST, e.getMessage());
+		}
+	}
+
+	private ResourceResolver resolverFor(String type) {
+		return resolversByBeanName.values().stream()
+				.filter(r -> r.type().equals(type))
+				.findFirst()
+				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no resolver registered for handle type \"" + type + "\""));
+	}
+
+	private void requireAuthority(String requiredRole) {
+		boolean granted = SecurityContextHolder.getContext().getAuthentication().getAuthorities().stream()
+				.map(GrantedAuthority::getAuthority)
+				.anyMatch(authority -> authority.equals("ROLE_" + requiredRole));
+		if (!granted) {
+			throw new ResponseStatusException(HttpStatus.FORBIDDEN, "requires role " + requiredRole);
+		}
+	}
+}

package/handles/providers/java-spring/templates/HandleRegistry.java.tmpl

@@ -0,0 +1,107 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import org.hibernate.annotations.CreationTimestamp;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * Registry row for one addressable handle -- maps a derived {@code handle_uid} (see
+ * {@link HandleCodec#deriveHandleUid}) back to the resource/field it addresses, so a handle can
+ * be looked up in the reverse direction without re-deriving it from a token.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel handles emit}). The corresponding migration
+ * (see the emitted {@code migration.sql}) is NOT applied automatically -- this repo has no
+ * Flyway/Liquibase, so apply it yourself against Supabase, and add a JPA {@code @Table}
+ * mapping only once that migration has actually run.
+ */
+@Getter
+@Entity
+@Table(name = "sbf_handle")
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class HandleRegistry {
+
+	@Id
+	@Column(name = "handle_uid", updatable = false, nullable = false)
+	private UUID handleUid;
+
+	/** {@code r} (resource), {@code f} (field), or {@code o} (operation instance -- reserved, unused). */
+	@Column(name = "kind", nullable = false, length = 1)
+	private String kind;
+
+	@Column(name = "resource_type", nullable = false, length = 100)
+	private String resourceType;
+
+	@Column(name = "resource_uid", nullable = false)
+	private UUID resourceUid;
+
+	/** RFC 6901 JSON Pointer, null for {@code kind = r}. */
+	@Column(name = "pointer")
+	private String pointer;
+
+	@Column(name = "feature_uid", nullable = false)
+	private UUID featureUid;
+
+	@Column(name = "operation_id", length = 100)
+	private String operationId;
+
+	@Column(name = "contract_ref", nullable = false)
+	private String contractRef;
+
+	@CreationTimestamp
+	@Column(name = "created_at", nullable = false, updatable = false)
+	private Instant createdAt;
+
+	@Column(name = "revoked_at")
+	private Instant revokedAt;
+
+	@Column(name = "revoked_reason")
+	private String revokedReason;
+
+	public static HandleRegistry create(
+			UUID handleUid, String kind, String resourceType, UUID resourceUid,
+			String pointer, UUID featureUid, String operationId, String contractRef
+	) {
+		HandleRegistry registry = new HandleRegistry();
+		registry.handleUid = handleUid;
+		registry.kind = kind;
+		registry.resourceType = resourceType;
+		registry.resourceUid = resourceUid;
+		registry.pointer = pointer;
+		registry.featureUid = featureUid;
+		registry.operationId = operationId;
+		registry.contractRef = contractRef;
+		return registry;
+	}
+
+	public boolean isRevoked() {
+		return revokedAt != null;
+	}
+
+	/**
+	 * O4 (D-handle-lifecycle): {@code handle_uid} is DERIVED from {@code kind}/{@code
+	 * resourceType}/{@code resourceUid}/{@code pointer} (see {@link HandleCodec#deriveHandleUid})
+	 * -- those four fields can never legitimately differ for an existing row with this same id,
+	 * so {@link HandleService#register} only ever needs to refresh the three fields that CAN
+	 * change across separate registrations of the same resource/pointer: which feature most
+	 * recently touched it, which operation, and its current contract hash. Deliberately does NOT
+	 * touch {@code revokedAt} -- re-registering a revoked handle must never silently un-revoke it.
+	 */
+	void refresh(UUID featureUid, String operationId, String contractRef) {
+		this.featureUid = featureUid;
+		this.operationId = operationId;
+		this.contractRef = contractRef;
+	}
+
+	void revoke(String reason) {
+		this.revokedAt = Instant.now();
+		this.revokedReason = reason;
+	}
+}

package/handles/providers/java-spring/templates/HandleRegistryRepository.java.tmpl

@@ -0,0 +1,8 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.UUID;
+
+public interface HandleRegistryRepository extends JpaRepository<HandleRegistry, UUID> {
+}

package/handles/providers/java-spring/templates/HandleService.java.tmpl

@@ -0,0 +1,95 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import {{JACKSON_PACKAGE}}.ObjectMapper;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * O4 (D-handle-lifecycle): the explicit API that makes {@code HandleController.recover()}
+ * actually reachable -- before this existed, nothing anywhere ever called {@link
+ * HandleRegistry#create}/{@link HandleSnapshot#create}, so a registry lookup could never find a
+ * row. Deliberately NEVER auto-invoked by anything generated elsewhere and never wired into any
+ * EXISTING business logic class -- call it explicitly from your own service code at the point a
+ * resource is actually created/updated, or apply {@code @RecordHandleSnapshot} to an existing
+ * service method to have {@link HandleAspect} call it for you (see that annotation's own javadoc
+ * for the opt-in, explicit-parameter-index design and why nothing here ever guesses).
+ *
+ * <p>Generated by backend-skeleton ({@code bskel handles emit}).
+ */
+@Service
+@RequiredArgsConstructor
+public class HandleService {
+
+	private final HandleRegistryRepository handleRegistryRepository;
+	private final HandleSnapshotRepository handleSnapshotRepository;
+	private final ObjectMapper objectMapper;
+
+	/**
+	 * Derives {@code handle_uid} ({@link HandleCodec#deriveHandleUid}) and UPSERTS the registry
+	 * row -- the schema's own {@code unique (resource_type, resource_uid, pointer)} constraint
+	 * (see the emitted {@code migration.sql}) means the SAME {@code (kind, type, resourceUid,
+	 * pointer)} triple always derives the SAME {@code handle_uid}, so re-registering it is
+	 * expected, not an error: an existing row has its {@code featureUid}/{@code operationId}/
+	 * {@code contractRef} refreshed (see {@link HandleRegistry#refresh}) rather than failing a
+	 * unique-constraint check. Returns the encoded handle token ({@link HandleCodec#encode},
+	 * already implemented -- "minting" a token was never the missing piece, persisting the row
+	 * backing it was).
+	 */
+	@Transactional
+	public String register(String kind, String type, UUID resourceUid, String pointer, UUID featureUid, String operationId, String contractRef) {
+		String token = HandleCodec.encode(kind, type, resourceUid, pointer);
+		UUID handleUid = HandleCodec.deriveHandleUid(kind, type, resourceUid, pointer);
+		HandleRegistry existing = handleRegistryRepository.findById(handleUid).orElse(null);
+		if (existing == null) {
+			handleRegistryRepository.save(HandleRegistry.create(handleUid, kind, type, resourceUid, pointer, featureUid, operationId, contractRef));
+		} else {
+			existing.refresh(featureUid, operationId, contractRef);
+		}
+		return token;
+	}
+
+	/**
+	 * Records one envelope for an already-registered handle. {@code payload} is serialized
+	 * through the same {@link ObjectMapper} the rest of the app uses -- callers pass a real
+	 * object (a DTO, a request body, an error shape), never a pre-serialized string, so this is
+	 * the one place that decides how it becomes the JSON text {@code sbf_handle_snapshot.payload}
+	 * stores.
+	 */
+	@Transactional
+	public void recordSnapshot(UUID handleUid, String envelopeDir, String operationId, String contractHash, Object payload) {
+		// A generic `catch (Exception e)` (not the Jackson-2-specific checked
+		// JsonProcessingException, nor assuming Jackson 3's unchecked JacksonException) compiles
+		// correctly against EITHER Jackson major version {{JACKSON_PACKAGE}} might have resolved
+		// to at `bskel handles emit` time -- this template must compile whichever one a real
+		// target repo is actually on, and the two versions disagree on whether this throws a
+		// checked or unchecked exception.
+		String json;
+		try {
+			json = objectMapper.writeValueAsString(payload);
+		} catch (Exception e) {
+			throw new IllegalStateException("could not serialize handle snapshot payload", e);
+		}
+		handleSnapshotRepository.save(HandleSnapshot.create(handleUid, envelopeDir, operationId, contractHash, json));
+	}
+
+	@Transactional
+	public void revoke(UUID handleUid, String reason) {
+		handleRegistryRepository.findById(handleUid).ifPresent(registry -> registry.revoke(reason));
+	}
+
+	/**
+	 * O4 (D-handle-lifecycle): retention is EXPOSED, not auto-scheduled -- nothing generated here
+	 * wires a {@code @Scheduled} job to call this automatically. Deciding how long snapshots
+	 * should live, and whether a background job is even appropriate for this application, is left
+	 * to a human -- the same boundary {@code D-migration-scope} already draws around never
+	 * applying the emitted {@code migration.sql} on its own.
+	 */
+	@Transactional
+	public long pruneSnapshotsOlderThan(Instant cutoff) {
+		return handleSnapshotRepository.deleteByRecordedAtBefore(cutoff);
+	}
+}

package/handles/providers/java-spring/templates/HandleSnapshot.java.tmpl

@@ -0,0 +1,75 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import org.hibernate.annotations.CreationTimestamp;
+import org.hibernate.annotations.JdbcTypeCode;
+import org.hibernate.type.SqlTypes;
+
+import java.time.Instant;
+import java.util.UUID;
+
+/**
+ * One recorded envelope for a handle -- what {@code bskel handles emit}'s {@code recover} verb
+ * reads from. Rows are written explicitly via {@link HandleService#recordSnapshot}, either called
+ * directly or automatically by {@link HandleAspect} for methods annotated
+ * {@code @RecordHandleSnapshot} (O4, D-handle-lifecycle) -- nothing here writes on its own.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel handles emit}). Migration NOT applied
+ * automatically -- see the note on {@link HandleRegistry}.
+ */
+@Getter
+@Entity
+@Table(name = "sbf_handle_snapshot")
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class HandleSnapshot {
+
+	@Id
+	@GeneratedValue(strategy = GenerationType.IDENTITY)
+	@Column(name = "snapshot_id", updatable = false, nullable = false)
+	private Long snapshotId;
+
+	@Column(name = "handle_uid", nullable = false)
+	private UUID handleUid;
+
+	@Column(name = "envelope_dir", nullable = false, length = 20)
+	private String envelopeDir;
+
+	@Column(name = "operation_id", nullable = false, length = 100)
+	private String operationId;
+
+	/**
+	 * Hash of the feature contract this snapshot was recorded against. {@code recover} compares
+	 * this to the CURRENT contract's hash -- a mismatch means the contract has since changed
+	 * shape, and {@code recover} must say so explicitly (a {@code schema_drift} marker) rather
+	 * than silently returning a payload the current contract no longer describes.
+	 */
+	@Column(name = "contract_hash", nullable = false, length = 64)
+	private String contractHash;
+
+	/** JSON payload, stored as text (same convention as {@code ReportSnapshot.summaryPayload}) -- Hibernate handles JSON<->text at the JDBC layer via {@code SqlTypes.JSON}. */
+	@JdbcTypeCode(SqlTypes.JSON)
+	@Column(name = "payload", nullable = false)
+	private String payload;
+
+	@CreationTimestamp
+	@Column(name = "recorded_at", nullable = false, updatable = false)
+	private Instant recordedAt;
+
+	public static HandleSnapshot create(UUID handleUid, String envelopeDir, String operationId, String contractHash, String payload) {
+		HandleSnapshot snapshot = new HandleSnapshot();
+		snapshot.handleUid = handleUid;
+		snapshot.envelopeDir = envelopeDir;
+		snapshot.operationId = operationId;
+		snapshot.contractHash = contractHash;
+		snapshot.payload = payload;
+		return snapshot;
+	}
+}

package/handles/providers/java-spring/templates/HandleSnapshotRepository.java.tmpl

@@ -0,0 +1,20 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.UUID;
+
+public interface HandleSnapshotRepository extends JpaRepository<HandleSnapshot, Long> {
+
+	/** Most recent snapshot first -- `recover(handle)` without a timestamp wants index 0 of this. */
+	List<HandleSnapshot> findByHandleUidOrderByRecordedAtDesc(UUID handleUid);
+
+	/**
+	 * O4 (D-handle-lifecycle): backs {@link HandleService#pruneSnapshotsOlderThan} -- retention is
+	 * exposed as a callable method, but nothing generated here schedules it automatically (see
+	 * HandleService's own javadoc for why).
+	 */
+	long deleteByRecordedAtBefore(Instant cutoff);
+}

package/handles/providers/java-spring/templates/RecordHandleSnapshot.java.tmpl

@@ -0,0 +1,50 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * O4 (D-handle-lifecycle): apply this to an EXISTING service method (never generated onto one --
+ * a human decides which methods are worth handle-tracking) to have {@link HandleAspect}
+ * automatically {@link HandleService#register register} the resource-level handle and {@link
+ * HandleService#recordSnapshot record} the request/response/error envelope around every call.
+ *
+ * <p>{@code resourceUidParam} is an explicit parameter INDEX, not inferred from the method
+ * signature -- the same "never guess, always explicit" boundary {@code D-resolver-scope}/
+ * {@code D-security-8} already draw for this codebase's generated code: a wrong guess here would
+ * silently attribute a snapshot to the wrong resource, which recording nothing at all would never
+ * do.
+ *
+ * <p>{@code redact} is an explicit array of JSON Pointers into the recorded envelope to blank
+ * before storage -- deliberately NOT a guessed heuristic (e.g. "any field named like a secret").
+ * An empty array (the default) means nothing is redacted; if the annotated method's payload
+ * carries anything sensitive, the human applying this annotation must name it.
+ *
+ * <p>Example:
+ * <pre>{@code
+ * @RecordHandleSnapshot(resourceType = "Organization", operationId = "updateOrganization", resourceUidParam = 0, redact = {"/internalNote"})
+ * public OrganizationResponse updateOrganization(UUID organizationId, UpdateOrganizationRequest request, UUID requesterId) { ... }
+ * }</pre>
+ *
+ * <p>Generated by backend-skeleton ({@code bskel handles emit}). Requires {@code
+ * spring-boot-starter-aop} on the target repo's own classpath -- NOT added automatically (see
+ * {@code handles emit}'s own post-emit notes), matching this project's established boundary of
+ * never auto-editing a target's build file.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface RecordHandleSnapshot {
+
+	/** Must match a registered {@link ResourceResolver#type()}. */
+	String resourceType();
+
+	String operationId();
+
+	/** Zero-based index into the annotated method's own parameter list -- the resource's UUID. */
+	int resourceUidParam();
+
+	/** JSON Pointers (RFC 6901) into the recorded envelope to blank before storage. Empty by default -- nothing redacted unless explicitly named. */
+	String[] redact() default {};
+}

package/handles/providers/java-spring/templates/ResourceResolver.java.tmpl

@@ -0,0 +1,50 @@
+package {{BASE_PACKAGE}}.global.handle;
+
+import java.util.UUID;
+
+/**
+ * One implementation per resource type, registered as a {@code @Component} so Spring collects
+ * them into a {@code Map<String, ResourceResolver>} (bean name -&gt; resolver) that
+ * {@link HandleController} dispatches through by decoded handle {@code type} -- no reflection,
+ * an unknown type is just a missing map key.
+ *
+ * <p>{@code fetch}/{@code patchField} return/accept plain {@code Object} (typically the
+ * resource's existing response DTO) rather than a fixed type, since resolvers are registered
+ * generically -- {@link HandleController#fetch} serializes whatever {@code fetch} returns
+ * through Jackson and walks a JSON Pointer with {@code JsonNode#at} for field-level (kind=f)
+ * addressing.
+ */
+public interface ResourceResolver {
+
+	/** Must match the {@code type} segment used when this resource's handles were minted (e.g. "Organization"). */
+	String type();
+
+	/** Fetches the whole resource, serialized the same shape its normal API response uses. */
+	Object fetch(UUID resourceUid);
+
+	/**
+	 * Applies a single field-level patch. Implementations route through the resource's EXISTING
+	 * update path (its real service method + DTO) rather than raw persistence access, so
+	 * existing validation/business rules keep applying -- see the generated resolver stub for
+	 * this feature's target module for the specific pattern to follow (some DTOs use {@code
+	 * PatchField<T>} for null-has-meaning fields, most just treat null-vs-absent as "unchanged",
+	 * and some require re-submitting the whole object; check the target DTO before assuming).
+	 */
+	void patchField(UUID resourceUid, String pointer, Object value);
+
+	/** Spring Security role name (no "ROLE_" prefix) required to fetch/patch this resource type via a handle. */
+	String requiredAuthority();
+
+	/**
+	 * O4 (D-handle-lifecycle): the content hash of the feature contract this resolver was
+	 * generated from -- baked in at {@code bskel handles emit} time (regenerated every run, so a
+	 * contract change is picked up automatically), never read from disk at runtime (a deployed
+	 * app has no access to {@code specs/} at all). {@link HandleService#register} stores this as
+	 * a registry row's {@code contract_ref}; {@code recover}'s {@code schema_drift} check compares
+	 * a snapshot's own recorded hash against the CURRENT value of this method, not a stale one.
+	 */
+	String contractRef();
+
+	/** O4 (D-handle-lifecycle): the feature_uid this resolver was generated for, baked in the same way as {@link #contractRef()}. */
+	UUID featureUid();
+}

package/handles/providers/java-spring/templates/ResourceResolverStub.java.tmpl

@@ -0,0 +1,77 @@
+package {{BASE_PACKAGE}}.domain.{{MODULE}}.infrastructure;
+
+import {{BASE_PACKAGE}}.global.handle.ResourceResolver;
+import {{SERVICE_IMPORT}};
+{{PATCH_IMPORTS}}import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import java.util.UUID;
+
+/**
+ * Generated by backend-skeleton ({@code bskel handles emit}) for feature {{FEATURE_ID}}.
+ *
+ * <p>{@code fetch} is wired to the real, existing read path ({@link {{SERVICE_TYPE}}#{{FETCH_METHOD}}})
+ * -- safe to trust as-is, it's a read-only call into code that already exists and is tested.
+ *
+ * <p>{@code patchField} is generated PER FIELD, not as one blanket stub (see DECISIONS.md
+ * D-patch-strategy, and D-resolver-scope for why a wrong guess here is worse than an honest
+ * stub). Each field of the update DTO is classified into one of four partial-update conventions
+ * found in this codebase's real DTOs:
+ * <ol>
+ *   <li>{@code patch-wrapper} -- the field uses {@code PatchField<T>} because null itself is
+ *       meaningful (distinguishes "don't touch" from "set to null").</li>
+ *   <li>{@code null-means-unchanged} -- a plain nullable field where null/absent both mean
+ *       "leave unchanged".</li>
+ *   <li>{@code fetch-merge-submit} -- the field is required ({@code @NotNull} or a primitive)
+ *       even in this otherwise-partial DTO, so patching it safely means fetching the current
+ *       resource first and resubmitting the full request with only this field changed.</li>
+ *   <li>{@code unsupported} -- a collection, nested {@code @Valid} object, or array field, not
+ *       safely expressible as a single scalar patch.</li>
+ * </ol>
+ * Only {@code patch-wrapper}/{@code null-means-unchanged} fields are ever auto-generated, and
+ * only once explicitly approved via {@code bskel handles patch approve} -- every other case
+ * below explains, per field, exactly why it isn't (or isn't yet).
+ */
+@Component
+@RequiredArgsConstructor
+public class {{RESOURCE_TYPE}}Resolver implements ResourceResolver {
+
+	// O4 (D-handle-lifecycle): baked in at `bskel handles emit` time -- CONTRACT_REF is the
+	// content hash of specs/{{FEATURE_ID}}/contracts/{{FEATURE_ID}}.schema.json as of this run,
+	// regenerated fresh every time (never read from disk at runtime, a deployed app has no
+	// access to specs/ at all).
+	private static final String CONTRACT_REF = "{{CONTRACT_REF}}";
+	private static final UUID FEATURE_UID = UUID.fromString("{{FEATURE_UID}}");
+
+	private final {{SERVICE_TYPE}} {{SERVICE_FIELD}};
+{{PATCH_FIELDS}}
+	@Override
+	public String type() {
+		return "{{RESOURCE_TYPE}}";
+	}
+
+	@Override
+	public Object fetch(UUID resourceUid) {
+		return {{SERVICE_FIELD}}.{{FETCH_METHOD}}(resourceUid);
+	}
+
+	@Override
+	public void patchField(UUID resourceUid, String pointer, Object value) {
+{{PATCH_FIELD_BODY}}
+	}
+
+	@Override
+	public String requiredAuthority() {
+		return "{{REQUIRED_AUTHORITY}}";
+	}
+
+	@Override
+	public String contractRef() {
+		return CONTRACT_REF;
+	}
+
+	@Override
+	public UUID featureUid() {
+		return FEATURE_UID;
+	}
+}