backend-skeleton 1.0.0-beta.1

package/contracts/validate.mjs

@@ -0,0 +1,147 @@
+// D-ajv-runtime (see DECISIONS.md): unlike archify, ajv here is a real runtime dependency of
+// `bskel` itself, not a devDependency used only to pre-compile a fixed set of schemas at build
+// time. Archify's 5 diagram schemas are fixed at package-build time, so standalone-compiling
+// them once makes sense; a per-feature contract's operation schemas don't exist until `bskel
+// contract emit` runs for THAT feature, so there is nothing to standalone-compile in advance.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+// P1 (D-npm-packaging): `import.meta.dirname` (Node >=20.11) was this codebase's only call site
+// requiring a Node floor above what package.json declares (>=18) -- every other file already
+// uses this portable pattern. Fixing the one outlier, not raising the floor, since nothing else
+// in the runtime code needs anything newer than plain ES2022/Node 18.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) {
+		_ajv = new Ajv2020({ allErrors: true, strict: false });
+		try {
+			addFormats(_ajv);
+		} catch {
+			// ajv-formats not installed -- format keywords (uuid, date-time) become no-ops rather
+			// than a hard failure; validate() below still catches everything else.
+		}
+	}
+	return _ajv;
+}
+
+function loadEnvelopeSchema() {
+	const schemaPath = path.join(__dirname, '..', 'schemas', 'agent-envelope.schema.json');
+	return JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+}
+
+export function validateEnvelopeStructure(envelope) {
+	const schema = loadEnvelopeSchema();
+	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	const ok = validateFn(envelope);
+	return { ok, errors: ok ? [] : (validateFn.errors ?? []) };
+}
+
+// A2: `requestBodySchema` (projected from a real OpenAPI document, contracts/openapi.mjs's
+// inlineSchema()) replaces the bare {type:'object'} placeholder when present -- every branch is
+// byte-identical to pre-A2 output when it's absent (the common case: openapi=null, or an
+// operation that isn't matched/adopted). Requiredness of the `body` KEY in the envelope is
+// decided by the SAME `body===true` condition as before, not by the document's
+// `requestBody.required` -- the scan remains the oracle for whether an operation takes a body at
+// all (A1's provenance split); `requestBodySchema` only ever tightens what's INSIDE that body.
+// `additionalProperties:false` is deliberately never added to `bodySchema` itself -- see
+// D-openapi-request-schema: Team-IZ-Backend has no Jackson customization, so the real endpoints
+// accept and ignore unknown body fields (Spring Boot's default), and a contract that rejects what
+// the real API accepts is a false negative, not a safety improvement.
+//
+// A3: `direction` selects which of the operation's three projected schemas this payload is
+// checked against. `request` behavior is completely unchanged (byte-identical, that branch always
+// returns a schema). `response`/`error` return `null` -- unconstrained, exactly as before A3 --
+// when the operation has no projected responseSchema/errorSchema; when it does, the payload must
+// be `{body: <the actual response/error body>}`, NOT the bare body. The wrapper (rather than
+// payload being the response body directly) keeps a future status-code field additive
+// (`payload.status`) instead of requiring a breaking `sbf` bump, and keeps this function's return
+// shape uniform across all three directions ("a named-parts object, additionalProperties:false")
+// -- see D-openapi-response-schema. An unrecognized `direction` also returns null (unconstrained),
+// matching the envelope schema's own enum being the actual gate on valid direction values.
+export function operationPayloadSchema(opContract, direction = 'request') {
+	if (direction === 'request') {
+		const properties = { pathParams: opContract.pathParams };
+		const required = ['pathParams'];
+		const bodySchema = opContract.requestBodySchema ?? { type: 'object' };
+		if (opContract.body === true) {
+			properties.body = bodySchema;
+			required.push('body');
+		} else if (opContract.body === 'unknown') {
+			properties.body = bodySchema;
+		}
+		// body === false: deliberately absent from `properties` -- with additionalProperties:false
+		// below, a payload that includes a body for a known-bodyless operation is rejected outright.
+		return { type: 'object', additionalProperties: false, properties, required };
+	}
+	if (direction === 'response' || direction === 'error') {
+		const schema = direction === 'response' ? opContract.responseSchema : opContract.errorSchema;
+		if (!schema) return null;
+		return { type: 'object', additionalProperties: false, properties: { body: schema }, required: ['body'] };
+	}
+	return null;
+}
+
+// Validates a full envelope against a specific feature's contract: feature_id/feature_uid must
+// match the contract exactly (not just be well-formed), operation_id must be one the contract
+// actually knows about, and payload must satisfy that operation's specific pathParams/body
+// shape -- this is what makes "wrong feature" and "wrong operation" and "right operation but
+// missing a required path param" all fail differently and traceably, not just "invalid JSON".
+export function validateAgainstContract(envelope, contract) {
+	const errors = [];
+	if (envelope.feature_id !== contract.feature_id) {
+		errors.push(`feature_id mismatch: envelope has "${envelope.feature_id}", contract is for "${contract.feature_id}"`);
+	}
+	if (envelope.feature_uid !== contract.feature_uid) {
+		errors.push(`feature_uid mismatch: envelope has "${envelope.feature_uid}", contract is for "${contract.feature_uid}" (a stale payload from a renamed/recreated feature would land here)`);
+	}
+	// D-security-1: Object.hasOwn, not a plain `[key]` lookup -- `contract.operations` is a
+	// plain object, so `operation_id: "constructor"` (or "toString", "__proto__", etc.) would
+	// otherwise resolve an inherited Object.prototype property and pass as if it were a real,
+	// defined operation. Found by the Codex security review, verified against this exact code.
+	const opContract = Object.hasOwn(contract.operations, envelope.operation_id)
+		? contract.operations[envelope.operation_id]
+		: undefined;
+	if (!opContract) {
+		errors.push(`operation_id "${envelope.operation_id}" is not defined in this feature's contract (known operations: ${Object.keys(contract.operations).join(', ') || '(none)'})`);
+		return { ok: false, errors };
+	}
+	// A3: direction-agnostic -- operationPayloadSchema() returns null for response/error when
+	// nothing was projected (unconstrained, exactly as every direction behaved before A2/A3), and a
+	// real schema otherwise. request behavior is unchanged (that branch always returns a schema).
+	const payloadSchema = operationPayloadSchema(opContract, envelope.direction);
+	if (payloadSchema) {
+		// A2: before A2, payloadSchema was always 100% synthesized by this codebase, so
+		// ajv().compile() never threw. Now it can embed a projected schema, and the contract file
+		// itself is hand-editable on disk (the `contract` gate would go stale, but this function
+		// doesn't consult gates) -- a malformed schema must fail cleanly, not crash.
+		let validateFn;
+		try {
+			validateFn = ajv().compile(payloadSchema);
+		} catch (err) {
+			errors.push(`this operation's contract payload schema could not be compiled: ${err.message} -- the contract file may have been hand-edited (re-run \`bskel contract emit\`)`);
+			return { ok: false, errors };
+		}
+		const ok = validateFn(envelope.payload);
+		if (!ok) {
+			for (const e of validateFn.errors ?? []) {
+				errors.push(`payload${e.instancePath} ${e.message}`);
+			}
+		}
+	}
+	// No payloadSchema (unknown direction, or a known direction with nothing projected for this
+	// operation): not constrained beyond the envelope's own structure -- see D-contract-scope.
+	return { ok: errors.length === 0, errors };
+}
+
+export function validateEnvelope(envelope, contract) {
+	const structural = validateEnvelopeStructure(envelope);
+	if (!structural.ok) {
+		return { ok: false, errors: structural.errors.map((e) => `${e.instancePath || '(root)'} ${e.message}`) };
+	}
+	return validateAgainstContract(envelope, contract);
+}

package/handles/_engine.mjs

@@ -0,0 +1,281 @@
+// G4: shared, safety-critical emit machinery -- extracted from what was originally handles/
+// emit.mjs (Java-only, pre-G4) so any codegen provider's own emit() can reuse the exact same
+// conflict/manifest/force/orphan logic instead of duplicating it. This is pure code motion --
+// the ownership/conflict semantics themselves are unchanged from O2's D-handles-ownership. See
+// 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';
+
+function readIfExists(target) {
+	return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	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) {
+	try {
+		const out = execFileSync('git', ['status', '--porcelain', '--', absPath], { cwd: repoRoot, encoding: 'utf8' });
+		return out.trim().length > 0;
+	} catch {
+		return true;
+	}
+}
+
+// The provider-neutral core of `bskel handles emit`. Each provider computes its own render/paths,
+// then calls this once to do the actual conflict-safe write. See DECISIONS.md D-handles-ownership
+// for the full design this preserves unchanged.
+//
+//   infraUnits:    [{ id, templatePath, targetAbs, rendered }]  -- repo-owned, all-or-nothing
+//   resolverUnits: [{ id, resourceType, module, templatePath, targetAbs, rendered,
+//                      pristineRenderFor(ownerId) => string }]  -- feature-owned, independent
+//   orphanScan:    { dir, module, matchesFile(filename) => bool,
+//                     resourceTypeOf(filename, content) => string|null } | null
+//                  -- null disables orphan detection entirely (mirrors --resource narrowing)
+//   provider:      string, written into every manifest entry this call creates/updates
+//   dryRun:        D4 (D-handles-dryrun) -- when true, every actual write (writeUnit/saveManifest)
+//                  is skipped, but the exact same classification runs and `written`/`forced`
+//                  still record what WOULD have been written. Nothing on disk changes.
+//   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 }) {
+	const manifest = loadManifest(repoRoot);
+	const nowIso = new Date().toISOString();
+
+	const written = [];
+	const conflicts = [];
+	const orphans = [];
+	const notes = [];
+	const resolverStubs = [];
+	const forced = [];
+	const actions = [];
+	let manifestChanged = false;
+
+	function recordAction({ relPath, kind, action, resourceType, diskContent, rendered }) {
+		const entry = { path: relPath, kind, action };
+		if (resourceType) entry.resourceType = resourceType;
+		if (computeDiff && DIFFABLE_ACTIONS.has(action)) entry.diff = unifiedDiff(relPath, diskContent, rendered);
+		actions.push(entry);
+	}
+
+	// ---- infra: repo-owned, all-or-nothing (a half-upgraded infra set is worse than either
+	// extreme, so one conflict blocks the whole set unless --force). ----
+	const infraPlans = infraUnits.map((u) => {
+		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(u.rendered);
+		const entry = manifest.files[relPath];
+		// Infra is feature-independent, so a pristine render IS the fresh render (no owner-recovery
+		// step needed, unlike a resolver's baked-in FEATURE_ID).
+		const matchesPristineRender = exists && diskContent === u.rendered;
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: entry?.generated_hash ?? null, freshRenderHash, matchesPristineRender });
+		return { ...u, relPath, diskContent, freshRenderHash, action };
+	});
+
+	const infraHasConflict = infraPlans.some((u) => u.action === 'conflict');
+	if (infraHasConflict && !force) {
+		for (const u of infraPlans) {
+			conflicts.push({ path: u.relPath, kind: 'infra', reason: 'diverged from the last content backend-skeleton generated -- see notes for remediation' });
+			recordAction({ relPath: u.relPath, kind: 'infra', action: u.action, diskContent: u.diskContent, rendered: u.rendered });
+		}
+	} else {
+		for (const u of infraPlans) {
+			if (u.action === 'conflict') {
+				if (isDirtyOrUntracked(repoRoot, u.targetAbs)) {
+					conflicts.push({ path: u.relPath, kind: 'infra', reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+					recordAction({ relPath: u.relPath, kind: 'infra', action: u.action, diskContent: u.diskContent, rendered: u.rendered });
+					continue;
+				}
+				if (!dryRun) {
+					manifest.files[u.relPath] = {
+						kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+						template_hash: sha256File(u.templatePath), generated_hash: u.freshRenderHash,
+						updated_at: nowIso, last_force: { reason, at: nowIso },
+					};
+					manifestChanged = true;
+					writeUnit(u.targetAbs, u.rendered);
+				}
+				written.push(u.relPath);
+				forced.push(u.relPath);
+				recordAction({ relPath: u.relPath, kind: 'infra', action: u.action, diskContent: u.diskContent, rendered: u.rendered });
+				continue;
+			}
+			if (u.action === 'unchanged') {
+				recordAction({ relPath: u.relPath, kind: 'infra', action: u.action });
+				continue;
+			}
+			// 'adopt-unchanged' means disk content already IS the correct bytes (a pristine,
+			// no-manifest-entry file) -- record the manifest entry so future runs see it as
+			// 'unchanged', but don't rewrite bytes that are already correct, and don't claim we
+			// "wrote" a file whose content didn't actually change.
+			if (u.action !== 'adopt-unchanged') {
+				if (!dryRun) writeUnit(u.targetAbs, u.rendered);
+				written.push(u.relPath);
+			}
+			if (!dryRun) {
+				manifest.files[u.relPath] = {
+					kind: 'infra', ownership: 'repo', owner: '_repo', provider, template: u.id,
+					template_hash: sha256File(u.templatePath), generated_hash: u.freshRenderHash,
+					updated_at: nowIso,
+				};
+				manifestChanged = true;
+			}
+			recordAction({ relPath: u.relPath, kind: 'infra', action: u.action, diskContent: u.diskContent, rendered: u.rendered });
+		}
+	}
+
+	// ---- resolvers: feature-owned, independent per file. "Regenerate when provably untouched"
+	// rather than "create once" -- a live-derived value (e.g. a required-authority string) is
+	// re-derived every run, and "once" would strand a stale value in a security-relevant file. ----
+	const generatedTypesThisRun = new Set();
+
+	for (const u of resolverUnits) {
+		resolverStubs.push(u.resourceType);
+
+		const relPath = path.relative(repoRoot, u.targetAbs);
+		generatedTypesThisRun.add(u.resourceType);
+
+		const diskContent = readIfExists(u.targetAbs);
+		const exists = diskContent !== null;
+		const diskHash = exists ? sha256String(diskContent) : null;
+		const freshRenderHash = sha256String(u.rendered);
+		const entry = manifest.files[relPath];
+
+		let matchesPristineRender = false;
+		let recoveredOwner = null;
+		if (exists) {
+			recoveredOwner = extractResolverOwnerFeatureId(diskContent);
+			if (recoveredOwner) {
+				matchesPristineRender = u.pristineRenderFor(recoveredOwner) === diskContent;
+			}
+		}
+		const action = classifyFile({ exists, diskHash, manifestEntryHash: entry?.generated_hash ?? null, freshRenderHash, matchesPristineRender });
+
+		if (action === 'conflict') {
+			if (force) {
+				if (isDirtyOrUntracked(repoRoot, u.targetAbs)) {
+					conflicts.push({ path: relPath, kind: 'resolver', resourceType: u.resourceType, reason: 'refusing --force: this file has uncommitted/untracked changes -- commit or stash it first so the overwrite is recoverable' });
+					recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.rendered });
+					continue;
+				}
+				if (!dryRun) {
+					writeUnit(u.targetAbs, u.rendered);
+					manifest.files[relPath] = {
+						kind: 'resolver', ownership: 'feature', owner: featureId, resource_type: u.resourceType, module: u.module, provider,
+						template: u.id, template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
+						updated_at: nowIso, last_force: { reason, at: nowIso, overwritten_hash: diskHash },
+					};
+					manifestChanged = true;
+				}
+				written.push(relPath);
+				forced.push(relPath);
+				recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.rendered });
+				continue;
+			}
+			conflicts.push({
+				path: relPath, kind: 'resolver', resourceType: u.resourceType,
+				reason: 'diverged from the last content backend-skeleton generated -- if you have not edited this file, this may be expected after a template upgrade or a security-relevant source change. If you HAVE edited it (e.g. finished a stubbed-out method), leave it -- nothing else in this run depends on it.',
+			});
+			recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.rendered });
+			continue;
+		}
+
+		const priorOwner = entry?.owner ?? recoveredOwner;
+		if (priorOwner && priorOwner !== featureId) {
+			notes.push(`ownership transfer: ${relPath} was generated by feature "${priorOwner}", now generated by "${featureId}"`);
+		}
+
+		if (action !== 'unchanged') {
+			if (action !== 'adopt-unchanged') {
+				if (!dryRun) writeUnit(u.targetAbs, u.rendered);
+				written.push(relPath);
+			}
+			if (!dryRun) {
+				manifest.files[relPath] = {
+					kind: 'resolver', ownership: 'feature', owner: featureId, resource_type: u.resourceType, module: u.module, provider,
+					template: u.id, template_hash: sha256File(u.templatePath), generated_hash: freshRenderHash,
+					updated_at: nowIso,
+				};
+				manifestChanged = true;
+			}
+		}
+		recordAction({ relPath, kind: 'resolver', action, resourceType: u.resourceType, diskContent, rendered: u.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
+	// filter would otherwise look orphaned. ----
+	if (orphanScan) {
+		const seenOrphanPaths = new Set();
+		for (const [relPath, entry] of Object.entries(manifest.files)) {
+			// `entry.provider` is absent on a manifest written before G4 -- treat that as
+			// "java-spring" so orphan detection for existing target repos keeps working exactly as
+			// before this item, rather than silently going blind on their first post-G4 run.
+			const entryProvider = entry.provider ?? 'java-spring';
+			if (entry.kind !== 'resolver' || entry.module !== orphanScan.module || entryProvider !== provider || generatedTypesThisRun.has(entry.resource_type)) continue;
+			orphans.push({ path: relPath, resourceType: entry.resource_type, reason: 'manifest tracks this resolver but the current plan no longer generates it -- left on disk untouched' });
+			seenOrphanPaths.add(relPath);
+		}
+		if (fs.existsSync(orphanScan.dir)) {
+			for (const file of fs.readdirSync(orphanScan.dir)) {
+				if (!orphanScan.matchesFile(file)) continue;
+				const absPath = path.join(orphanScan.dir, file);
+				const relPath = path.relative(repoRoot, absPath);
+				if (seenOrphanPaths.has(relPath)) continue;
+				const content = readIfExists(absPath);
+				if (!content || !content.includes(BSKEL_GENERATED_MARKER)) continue;
+				const resourceType = orphanScan.resourceTypeOf(file, content);
+				if (!resourceType || generatedTypesThisRun.has(resourceType)) continue;
+				orphans.push({ path: relPath, resourceType, reason: 'file carries the backend-skeleton marker but the current plan no longer generates it -- left on disk untouched' });
+			}
+		}
+	}
+
+	if (!dryRun && manifestChanged) saveManifest(repoRoot, manifest);
+
+	return { written, resolverStubs, conflicts, orphans, notes, forced, blocked: conflicts.length > 0, actions };
+}

package/handles/codec.mjs

@@ -0,0 +1,119 @@
+// D5/D6 (DECISIONS.md): the "handle" is a composite address -- kind:type:uuid[:pointer],
+// base64url-encoded with an `sbf1_` prefix -- extending Relay's `base64(Type:id)` global-ID
+// pattern with an RFC 6901 JSON Pointer for field-level addressing. This is the JS reference
+// implementation; handles/providers/java-spring/templates/HandleCodec.java.tmpl and
+// handles/providers/python-fastapi/templates/codec.py.tmpl must stay byte-identical in behavior --
+// executed, both directions, cross-checked against test/handles-java-codec.test.mjs and
+// test/handles-python-codec.test.mjs respectively (test/handles-codec.test.mjs only self-tests
+// this file's own JS-side behavior, it does not cross-check either other language).
+import { createHash } from 'node:crypto';
+
+// Fixed namespace UUID for this skill's field-handle derivation (arbitrary but permanent --
+// changing it would silently re-derive every existing field_uid to a different value).
+export const NS_SBF_FIELD = 'a3f1c2e0-8b4d-4f1a-9c3e-1d2b3a4c5d6e';
+
+const UUID_RE = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const HANDLE_RE = new RegExp(`^([rfo]):([^:]+):(${UUID_RE})(?::(.*))?$`, 'i');
+const BASE64URL_CHARSET_RE = /^[A-Za-z0-9_-]*$/;
+
+// D-security-10: no upper bound on token length before attempting to decode -- a defense-in-
+// depth cap, not a functional requirement (real handles are well under this). Found by the
+// Codex security review as part of the "other requested checks" pass.
+const MAX_HANDLE_TOKEN_LENGTH = 2048;
+
+function base64url(buf) {
+	return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// D-security-10: Node's `Buffer.from(str, 'base64')` silently IGNORES characters outside the
+// base64 alphabet instead of rejecting them, while Java's `Base64.getUrlDecoder().decode()`
+// throws on the same input -- the two implementations' "byte-identical behavior" claim (D5/D6)
+// didn't actually hold for malformed input. Found by the Codex security review. The explicit
+// charset check below makes the JS side reject exactly what the Java side rejects, before either
+// one gets a chance to decode it differently.
+function base64urlDecode(str) {
+	if (!BASE64URL_CHARSET_RE.test(str)) {
+		throw new Error('not valid base64url after the sbf1_ prefix');
+	}
+	const pad = (4 - (str.length % 4)) % 4;
+	const padded = str.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat(pad);
+	return Buffer.from(padded, 'base64');
+}
+
+export function encodeHandle({ kind, type, uuid, pointer = null }) {
+	if (!['r', 'f', 'o'].includes(kind)) throw new Error(`invalid handle kind "${kind}" (expected r, f, or o)`);
+	if (!type || !uuid) throw new Error('encodeHandle requires both type and uuid');
+	if (kind === 'f' && !pointer) throw new Error('field handles (kind=f) require a JSON Pointer');
+	// D-security-10: the symmetric case was previously unchecked -- a non-field handle silently
+	// carrying a pointer would encode fine and only cause confusion downstream (e.g. patch()
+	// deciding "field handle" purely from pointer-presence, not kind). Found by the Codex
+	// security review.
+	if (kind !== 'f' && pointer) throw new Error(`handle kind "${kind}" must not carry a JSON Pointer (only kind=f field handles do)`);
+	const raw = `${kind}:${type}:${uuid}${pointer ? `:${pointer}` : ''}`;
+	return `sbf1_${base64url(Buffer.from(raw, 'utf8'))}`;
+}
+
+export function decodeHandle(token) {
+	if (typeof token !== 'string' || !token.startsWith('sbf1_')) {
+		throw new Error('not an sbf1 handle (missing "sbf1_" prefix)');
+	}
+	if (token.length > MAX_HANDLE_TOKEN_LENGTH) {
+		throw new Error(`handle token exceeds the maximum length of ${MAX_HANDLE_TOKEN_LENGTH} characters`);
+	}
+	const raw = base64urlDecode(token.slice('sbf1_'.length)).toString('utf8');
+	const match = raw.match(HANDLE_RE);
+	if (!match) throw new Error(`malformed handle payload after decoding: "${raw}"`);
+	const [, kind, type, uuid, pointer] = match;
+	return { kind: kind.toLowerCase(), type, uuid: uuid.toLowerCase(), pointer: pointer ?? null };
+}
+
+function uuidToBytes(uuid) {
+	return Buffer.from(uuid.replace(/-/g, ''), 'hex');
+}
+
+function bytesToUuid(bytes) {
+	const hex = bytes.toString('hex');
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// RFC 4122 UUIDv5 (name-based, SHA-1). Implemented directly rather than pulling in the `uuid`
+// package -- this is the only place a v5 is needed and the algorithm is ~10 lines. Verified
+// against the standard test vector in test/handles-codec.test.mjs (NAMESPACE_DNS + "example.com").
+export function uuidv5(namespaceUuid, name) {
+	const hash = createHash('sha1')
+		.update(Buffer.concat([uuidToBytes(namespaceUuid), Buffer.from(name, 'utf8')]))
+		.digest();
+	const bytes = Buffer.from(hash.subarray(0, 16));
+	bytes[6] = (bytes[6] & 0x0f) | 0x50; // version 5
+	bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+	return bytesToUuid(bytes);
+}
+
+// The plain-UUID identity of a handle (for use as a DB primary key / foreign key), derivable
+// offline without a DB round-trip: kind=r handles ARE the resource's own uuid (no derivation
+// needed -- a resource handle and the entity's own PK are the same identity); kind=f handles
+// derive a UUIDv5 from type+uuid+pointer, so the same field always gets the same handle_uid
+// without ever needing to look it up first.
+export function deriveHandleUid({ kind, type, uuid, pointer }) {
+	if (kind === 'r') return uuid;
+	if (kind === 'f') {
+		if (!pointer) throw new Error('field handles require a pointer to derive handle_uid');
+		return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:${pointer}`);
+	}
+	if (kind === 'o') return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:o`);
+	throw new Error(`invalid handle kind "${kind}"`);
+}
+
+// RFC 6901 JSON Pointer resolution -- used by the `fetch` verb to extract a field's value from
+// a resource's serialized shape once the resolver has fetched the whole resource.
+export function resolveJsonPointer(obj, pointer) {
+	if (pointer == null || pointer === '') return obj;
+	if (!pointer.startsWith('/')) throw new Error(`invalid JSON Pointer "${pointer}" -- must start with "/"`);
+	const parts = pointer.split('/').slice(1).map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+	let current = obj;
+	for (const part of parts) {
+		if (current == null) return undefined;
+		current = Array.isArray(current) ? current[Number(part)] : current[part];
+	}
+	return current;
+}

package/handles/conformance.mjs

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+
+const CONFORMANCE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_ROOT = path.join(CONFORMANCE_ROOT, '..', 'schemas');
+
+let _ajv = null;
+function ajv() {
+	if (!_ajv) _ajv = new Ajv2020({ allErrors: true, strict: false });
+	return _ajv;
+}
+
+function loadHandlesPlanSchema() {
+	return JSON.parse(fs.readFileSync(path.join(SCHEMAS_ROOT, 'handles-plan.schema.json'), 'utf8'));
+}
+
+// P4 (D-extension-conformance): schemas/handles-plan.schema.json existed since G4 (multi-provider
+// handles codegen) but had no real consumer anywhere in the codebase -- bin/bskel.mjs renders a
+// provider's plan() output directly, never validating it against this schema. This is that
+// schema's first real use: proof a third-party provider's plan() actually produces the shape
+// schemas/handles-plan.schema.json (and this project's own CLI renderer) expect, plus an emit()
+// idempotence check equivalent to stack/apply.mjs's applyPlan() re-apply guarantee -- a second
+// emit() against files the first emit() already wrote must report nothing new to write.
+//
+// Found live while grounding this against the real java-spring provider: `provider.outputs.spec`
+// (e.g. `handles/migration.sql`, under `specs/<featureId>/`) is BY DESIGN regenerated
+// unconditionally on every emit() call, unlike the manifest-tracked generated-code files --
+// handles/providers/java-spring/emit.mjs's own comment documents this as pre-existing, intentional
+// behavior, not a bug this item should flag. `provider.outputs.spec` is exactly the schema field
+// (schemas/handles-provider.schema.json, required) that already distinguishes these two
+// categories, so the idempotence check excludes those declared paths instead of hardcoding
+// per-provider knowledge into this harness.
+export function checkProviderConformance(provider, { repoRoot, scanReport, module = null, resourceFilter = null, featureId = 'zz-conformance-check' } = {}) {
+	const errors = [];
+	let plan;
+	try {
+		plan = provider.plan({ repoRoot, scanReport, module, resourceFilter });
+	} catch (err) {
+		errors.push(`plan() threw: ${err.message}`);
+		return { provider: provider.id, ok: false, errors };
+	}
+
+	const schema = loadHandlesPlanSchema();
+	const validateFn = ajv().getSchema(schema.$id) ?? ajv().compile(schema);
+	if (!validateFn(plan)) {
+		const details = (validateFn.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
+		errors.push(`plan() output does not match schemas/handles-plan.schema.json: ${details}`);
+	}
+
+	let first;
+	try {
+		first = provider.emit({ repoRoot, featureId, plan, resourceFilter, force: false, reason: '' });
+	} catch (err) {
+		errors.push(`emit() threw: ${err.message}`);
+		return { provider: provider.id, ok: false, errors };
+	}
+
+	let second;
+	try {
+		second = provider.emit({ repoRoot, featureId, plan, resourceFilter, force: false, reason: '' });
+	} catch (err) {
+		errors.push(`emit() threw on its second, idempotent call: ${err.message}`);
+		return { provider: provider.id, ok: false, errors };
+	}
+	const specOwnedPaths = new Set((provider.outputs?.spec ?? []).map((relPath) => path.join('specs', featureId, relPath)));
+	const unexpectedWrites = (second.written ?? []).filter((w) => !specOwnedPaths.has(w));
+	if (!Array.isArray(second.written) || unexpectedWrites.length !== 0) {
+		errors.push(`emit() is not idempotent -- a second call against files the first call already wrote reported written: ${JSON.stringify(second.written)} (expected only provider.outputs.spec entries, if any: ${JSON.stringify([...specOwnedPaths])})`);
+	}
+
+	return { provider: provider.id, ok: errors.length === 0, errors, firstEmitWritten: first.written };
+}