backend-skeleton 1.0.0-beta.7 → 1.0.0-beta.9

package/bin/bskel.mjs

@@ -31,6 +31,11 @@ import { validateEnvelope, operationPayloadSchema } from '../contracts/validate.
 import { evaluateResolution, loadResolution, saveResolution, requireWarningCode, warningKey, countByCode } from '../contracts/completeness.mjs';
 import { loadPatchApprovals, savePatchApprovals, approvalKey } from '../lib/patch-approvals.mjs';
 import { loadManifest, saveManifest } from '../lib/handles-manifest.mjs';
+import { createHttpServer } from '../lib/http-server.mjs';
+import {
+	resolveClassFile, listDownstreamDependents, DependencyOperationError,
+	declareDependency, removeDependency, buildDependencyListReport,
+} from '../lib/field-dependencies.mjs';
 import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting } from '../new/index.mjs';
 import {
 	requireSingleLineText, requireValidJavaPackageName, requireValidArtifactId,
@@ -77,6 +82,9 @@ function usage() {
   bskel contract validate --feature <id> --file <envelope.json>
   bskel contract tool-schema --feature <id> --operation <operationId>
   bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path"|--all) --reason "..." [--expires <Nd>]
+  bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."]
+  bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."
+  bskel dependency list --feature <id> [--json]
   bskel stack apply --choice <id> [--apply] [--port N] [--json]
   bskel catalog lint [<choice>] [--json]
   bskel handles plan --feature <id> [--module <name>] [--resource type1,type2] [--diff] [--ast]
@@ -95,6 +103,7 @@ function usage() {
   bskel gate show [<name>] [--feature <id>]
   bskel gate export --feature <id> [--out <path>] [--json]
   bskel doctor [--workflow ${DOCTOR_WORKFLOWS.join('|')}] [--json]
+  bskel serve [--port N] [--host <addr>] [--json]
 `);
 }
 
@@ -1055,6 +1064,7 @@ function cmdContractEmit(args) {
 			console.error(`\nnote: ${evaluation.staleWaivers.length} recorded waiver(s) no longer match any current warning (kept as-is, not auto-removed):`);
 			for (const w of evaluation.staleWaivers) console.error(`  ${w.code} (${w.subject ?? '*'})`);
 		}
+		for (const n of describeDownstreamImpact(root, flags.feature)) console.error(`\nnote: ${n}`);
 		if (evaluation.blocking) {
 			if (evaluation.status === 'blocked') {
 				console.error(`\nblocked: this contract has zero operations and cannot be waived -- fix --module/--terms, or run \`bskel gate force contract --feature ${flags.feature} --reason "..."\` if this module genuinely has no HTTP surface (yet).`);
@@ -1363,6 +1373,123 @@ function cmdContractWaive(args) {
 	process.exit(evaluation.blocking ? EXIT.AWAITING_DISPOSITION : EXIT.PASS);
 }
 
+// D-dependency-propagation-notice: called from cmdContractEmit/cmdHandlesEmit to warn a SOURCE
+// feature, at the moment its own generated artifacts are refreshed, that other features declared a
+// dependency on one of its fields. Only surfaces a note when the dependent's OWN `dependencies` gate
+// is actually stale AND that staleness is attributable to THIS featureId specifically (a
+// `source_field_file:<featureId>:` key in its changed_inputs) -- a dependent that's stale for some
+// OTHER, unrelated reason must not be misattributed to this feature's own change. When
+// changed_inputs can't explain the staleness (NO_RECORDED_INPUTS/RECORDED_INPUTS_MISMATCH), the note
+// is skipped rather than guessed -- this is a best-effort nudge, never the source of truth for
+// whether something is actually stale (bskel verify/status on the dependent feature itself remains
+// that source of truth).
+function describeDownstreamImpact(root, featureId) {
+	const byDependent = new Map();
+	for (const { dependentFeature, dep } of listDownstreamDependents(root, featureId)) {
+		if (!byDependent.has(dependentFeature)) byDependent.set(dependentFeature, []);
+		byDependent.get(dependentFeature).push(dep);
+	}
+	const notes = [];
+	const prefix = `source_field_file:${featureId}:`;
+	for (const [dependentFeature, deps] of byDependent) {
+		const gate = requireNamedGate(root, 'dependencies', dependentFeature);
+		if (gate.status !== 'stale') continue;
+		if (!(gate.changed_inputs ?? []).some((k) => k.startsWith(prefix))) continue;
+		const list = deps.map((d) => `${d.target.resourceType}.${d.target.fieldName} <- ${d.source.resourceType}.${d.source.fieldName}`).join('; ');
+		notes.push(
+			`downstream impact: feature "${dependentFeature}" depends on this feature's field(s) (${list}), and that dependency just went stale -- ` +
+			`review with \`bskel dependency list --feature ${dependentFeature} --json\`, then re-run \`bskel dependency declare ...\` once the change is accounted for.`,
+		);
+	}
+	return notes;
+}
+
+// D-http-serving-layer: cmdDependencyDeclare/Remove/List are now thin CLI wrappers over
+// lib/field-dependencies.mjs's declareDependency/removeDependency/buildDependencyListReport --
+// lib/http-server.mjs's POST/DELETE/GET handlers call the SAME functions, so the CLI and HTTP
+// surfaces can never diverge on what these operations actually do. A thrown DependencyOperationError
+// carries the exact (exitCode, reasonCode) this CLI path always used -- fail() is called with those
+// verbatim, so this refactor is behavior-preserving (verified: test/dependency-cli.test.mjs, written
+// before this refactor existed, passes unchanged).
+function cmdDependencyDeclare(args) {
+	const flags = parseCommand('dependency declare', args);
+	if (flags.help) { console.log(renderCommandHelp('dependency declare')); process.exit(0); }
+	setContext('dependency declare', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = declareDependency(root, {
+			feature: flags.feature, resource: flags.resource, field: flags.field,
+			sourceFeature: flags['source-feature'], sourceResource: flags['source-resource'], sourceField: flags['source-field'],
+			reason: flags.reason, memo: flags.memo,
+		});
+	} catch (err) {
+		if (err instanceof DependencyOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`declared: ${flags.resource}.${flags.field} <- ${flags['source-feature']}/${flags['source-resource']}.${flags['source-field']}`);
+		console.log(`gate: dependencies -> ${result.gate.status}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+function cmdDependencyRemove(args) {
+	const flags = parseCommand('dependency remove', args);
+	if (flags.help) { console.log(renderCommandHelp('dependency remove')); process.exit(0); }
+	setContext('dependency remove', flags);
+	const root = requireRepoRoot();
+	let result;
+	try {
+		result = removeDependency(root, {
+			feature: flags.feature, resource: flags.resource, field: flags.field,
+			sourceFeature: flags['source-feature'], sourceResource: flags['source-resource'], sourceField: flags['source-field'],
+			reason: flags.reason,
+		});
+	} catch (err) {
+		if (err instanceof DependencyOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`removed: ${flags.resource}.${flags.field} <- ${flags['source-feature']}/${flags['source-resource']}.${flags['source-field']}`);
+		console.log(`gate: dependencies -> ${result.gate.status}`);
+	}
+	process.exit(EXIT.PASS);
+}
+
+function cmdDependencyList(args) {
+	const flags = parseCommand('dependency list', args);
+	if (flags.help) { console.log(renderCommandHelp('dependency list')); process.exit(0); }
+	setContext('dependency list', flags);
+	const root = requireRepoRoot();
+	let report;
+	try {
+		report = buildDependencyListReport(root, flags.feature);
+	} catch (err) {
+		if (err instanceof DependencyOperationError) fail(err.exitCode, err.reasonCode, err.message);
+		throw err;
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify(report, null, 2));
+	} else {
+		console.log(`dependencies -- feature ${flags.feature} (gate: ${report.gate.status})`);
+		for (const r of report.dependencies) {
+			const tNote = r.target_resolved ? 'ok' : `UNRESOLVED:${r.target_unresolved_reason}`;
+			const sNote = r.source_resolved ? 'ok' : `UNRESOLVED:${r.source_unresolved_reason}`;
+			console.log(`  ${r.target.resourceType}.${r.target.fieldName} [${tNote}] <- ${r.source.feature}/${r.source.resourceType}.${r.source.fieldName} [${sNote}]`);
+		}
+		if (report.dependencies.length === 0) console.log('  (none declared)');
+	}
+	process.exit(0);
+}
+
 // D-contract-history: a derived VIEW over the contract file's own git history in whatever repo
 // bskel is invoked in -- reads, never writes. Deliberately does NOT try to correlate a commit to
 // a specific `.sbf/<feature>.history.jsonl` gate-pass event: that file is per-machine, gitignored,
@@ -1990,6 +2117,11 @@ function cmdHandlesEmit(args) {
 	// D4: dryRun never marks the gate passed -- nothing real happened this run.
 	const gateState = dryRun ? null : passNamedGate(root, 'handles', flags.feature, { resolverStubs });
 
+	// D-dependency-propagation-notice: appended here (not inside any provider's own emit.mjs) so it
+	// applies uniformly regardless of which provider ran -- inherits the same --json/text-mode
+	// visibility every provider-authored postEmitNote already has, no special-casing needed.
+	postEmitNotes.push(...describeDownstreamImpact(root, flags.feature));
+
 	if (flags.json) {
 		console.log(JSON.stringify({ written, resolverStubs, conflicts, orphans, forced, notes: allNotes, actions, blocked: false, gate: gateState?.gates.handles ?? null, check: dryRun, postEmitNotes }, null, 2));
 	} else if (!flags.quiet) {
@@ -2603,6 +2735,39 @@ function cmdDoctor(args) {
 	process.exit(allOk ? 0 : 1);
 }
 
+// D-http-serving-layer: starts a real, long-running HTTP server (lib/http-server.mjs) -- unlike
+// every other command in this file, success here does NOT process.exit(); the server's own open
+// socket keeps the event loop alive until Ctrl+C (SIGINT) or SIGTERM. Every route handler calls
+// straight into the same lib/ functions the CLI commands use -- no separate business logic lives in
+// the HTTP layer itself.
+async function cmdServe(args) {
+	const flags = parseCommand('serve', args);
+	if (flags.help) { console.log(renderCommandHelp('serve')); process.exit(0); }
+	setContext('serve', flags);
+	const root = requireRepoRoot();
+	const port = Number.parseInt(flags.port, 10);
+
+	let started;
+	try {
+		started = await createHttpServer(root, { host: flags.host, port });
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `could not start server: ${err.message}`);
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify({ listening: started.url, host: started.host, port: started.port, repo: root }));
+	} else if (!flags.quiet) {
+		console.log(`bskel serve -- listening on ${started.url}`);
+		console.log(`  UI:  ${started.url}/`);
+		console.log(`  API: ${started.url}/api/...`);
+		console.log('press Ctrl+C to stop');
+	}
+
+	const shutdown = () => started.server.close(() => process.exit(0));
+	process.on('SIGINT', shutdown);
+	process.on('SIGTERM', shutdown);
+}
+
 // P2 (D-greenfield-bootstrap): the one path into this tool that doesn't require an existing git
 // repo (contrast requireRepoRoot(), used by nearly everything else) -- `bskel new` is what CREATES
 // one. `--stack`'s two choices come from new/index.mjs's plain dispatch map, not a dynamic
@@ -2850,6 +3015,16 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'dependency': {
+			const sub = rest[0];
+			const subArgs = rest.slice(1);
+			if (sub === 'declare') return cmdDependencyDeclare(subArgs);
+			if (sub === 'remove') return cmdDependencyRemove(subArgs);
+			if (sub === 'list') return cmdDependencyList(subArgs);
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'stack': {
 			if (rest[0] === 'apply') return cmdStackApply(rest.slice(1));
 			usage();
@@ -2903,6 +3078,8 @@ async function dispatchCommand(cmd, rest) {
 		case 'doctor':
 			cmdDoctor(rest);
 			break;
+		case 'serve':
+			return cmdServe(rest);
 		case 'new':
 			return cmdNew(rest);
 		default:

package/contracts/completeness.mjs

@@ -18,6 +18,16 @@ export const COMPLETENESS = Object.freeze({ COMPLETE: 'complete', PARTIAL: 'part
 // CONTRACT_EMPTY both mean the endpoint loop in buildContract() never ran at all) -- so gating
 // waivers on `completeness === 'blocked'` in cmdContractWaive is sufficient to keep them
 // unwaivable; there is no case where either fires with operations > 0.
+//
+// `waivable` only has functional meaning for ERROR-severity codes -- `bin/bskel.mjs`'s
+// `cmdContractWaive` filters to `severity === 'error'` before anything else, and
+// `evaluateResolution()` below only ever considers ERROR-severity warnings when computing
+// `unwaived`/`blocking` in the first place, by design (a WARN never blocks completeness, waived
+// or not). Every WARN-severity code below is marked `waivable: true` anyway -- read that as "this
+// finding is conceptually the kind of thing a human might choose to acknowledge," not as "this can
+// currently be passed to `bskel contract waive`" -- it can't, and isn't meant to. This is
+// deliberate (`test/contract-completeness.test.mjs` asserts the exact shape below, repeatedly,
+// across every OpenAPI-passthrough item that's added a WARN code), not an unnoticed inconsistency.
 export const WARNING_CODES = Object.freeze({
 	CONTRACT_NO_MODULE: { severity: SEVERITY.ERROR, waivable: false },
 	CONTRACT_EMPTY: { severity: SEVERITY.ERROR, waivable: false },

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

@@ -104,6 +104,22 @@ function writeUnit(target, content) {
 	fs.writeFileSync(target, content);
 }
 
+// O3 follow-up (D-handle-registry-enforcement, "Continued"): a coarse, per-resource, emit-time,
+// source-only proxy for "has this resource's own create-flow ever been wired to register a
+// HandleRegistry row" -- see DECISIONS.md for why this stays static and never queries a live
+// target-app database (that's a separate, harder, still-open gap, not this). Requires the opening
+// "(" so a bare comment/javadoc mention of the annotation's name (RecordHandleSnapshot.java.tmpl's
+// own javadoc has one) doesn't count as "found". Deliberately biased toward a false-positive
+// WARNING (nagging a resource that's actually registered some other way, e.g. a hand-written
+// HandleService.register() call with no annotation) over a false-negative SILENCE (saying nothing
+// about a resource that really can never bootstrap its first PATCH) -- see DECISIONS.md.
+const RECORD_HANDLE_SNAPSHOT_RE = /@RecordHandleSnapshot\s*\(/;
+
+function hasRecordHandleSnapshot(serviceFilePath) {
+	if (!serviceFilePath || !fs.existsSync(serviceFilePath)) return false;
+	return RECORD_HANDLE_SNAPSHOT_RE.test(fs.readFileSync(serviceFilePath, 'utf8'));
+}
+
 // See DECISIONS.md D-handles-ownership for the full design; the conflict/manifest/force/orphan
 // logic itself now lives in handles/_engine.mjs (D-handles-providers, G4) -- this function's job
 // is purely to compute java-spring's own render/paths and hand them to emitUnits(). `force`/
@@ -249,15 +265,26 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 	if (computeDiff && migrationAction === 'update') migrationActionEntry.diff = unifiedDiff(migrationRelPath, migrationDiskContent, migrationContent);
 	result.actions.push(migrationActionEntry);
 
-	return {
-		...result,
-		postEmitNotes: [
-			'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
-			// O4 (D-handle-lifecycle): HandleAspect.java only actually intercepts anything once a
-			// human applies @RecordHandleSnapshot to a real service method AND the target repo has
-			// this dependency -- never auto-added to build.gradle, same "review and apply yourself"
-			// boundary as the migration note above.
-			'NOT done automatically: HandleAspect.java requires spring-boot-starter-aop on your own build.gradle classpath (Spring AOP is not enabled by any other starter). Add it yourself before applying @RecordHandleSnapshot to any service method.',
-		],
-	};
+	const postEmitNotes = [
+		'NOT done automatically: applying specs/<id>/handles/migration.sql to any database. Review it and apply yourself.',
+		// O4 (D-handle-lifecycle): HandleAspect.java only actually intercepts anything once a
+		// human applies @RecordHandleSnapshot to a real service method AND the target repo has
+		// this dependency -- never auto-added to build.gradle, same "review and apply yourself"
+		// boundary as the migration note above.
+		'NOT done automatically: HandleAspect.java requires spring-boot-starter-aop on your own build.gradle classpath (Spring AOP is not enabled by any other starter). Add it yourself before applying @RecordHandleSnapshot to any service method.',
+	];
+	// O3 follow-up (D-handle-registry-enforcement, "Continued"): per-resource, conditional on
+	// enforceRegistry actually being on -- see hasRecordHandleSnapshot() above.
+	if (enforceRegistry) {
+		for (const resource of plan.resources) {
+			if (!resource.willGenerateResolver) continue;
+			if (hasRecordHandleSnapshot(resource.service.file)) continue;
+			const relServiceFile = path.relative(repoRoot, resource.service.file);
+			postEmitNotes.push(
+				`${resource.type}: --enforce-registry is on, but no @RecordHandleSnapshot(...) was found anywhere in ${relServiceFile} -- this resource may never get its first HandleRegistry row, and every fetch()/patch() call against it will 404 until something registers it. Apply @RecordHandleSnapshot to ${resource.service.serviceType}'s own create-flow method (or call HandleService.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`,
+			);
+		}
+	}
+
+	return { ...result, postEmitNotes };
 }

package/handles/providers/python-fastapi/emit.mjs

@@ -40,6 +40,16 @@ function dottedModulePath(file, importRoot) {
 	return rel.split(path.sep).join('.');
 }
 
+// O3 follow-up (D-handle-registry-enforcement, "Continued"): same static, coarse, per-resource
+// presence check as java-spring's own -- see that file's identical comment for the false-
+// positive/false-negative bias reasoning (unchanged here).
+const RECORD_SNAPSHOT_RE = /@record_snapshot\s*\(/;
+
+function hasRecordSnapshot(routeFilePath) {
+	if (!routeFilePath || !fs.existsSync(routeFilePath)) return false;
+	return RECORD_SNAPSHOT_RE.test(fs.readFileSync(routeFilePath, 'utf8'));
+}
+
 // See DECISIONS.md D-handles-providers. G4 follow-up: migration.sql + a real recover() lifecycle
 // (tables.py/handle_service.py/record_snapshot.py) are now generated, mirroring java-spring's own
 // O4 work -- the EXCLUDED section's original "even Java hasn't got O4" reasoning is stale, see
@@ -197,5 +207,18 @@ export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter =
 	// and apply yourself" boundary as the migration note above.
 	postEmitNotes.push('NOT done automatically: applying @record_snapshot (handles/record_snapshot.py) to any of your own service functions. Codegen never touches existing business logic files.');
 
+	// O3 follow-up (D-handle-registry-enforcement, "Continued"): per-resource, conditional on
+	// enforceRegistry.
+	if (enforceRegistry) {
+		for (const resource of plan.resources) {
+			if (!resource.willGenerateResolver) continue;
+			if (hasRecordSnapshot(resource.fetchRoute.file)) continue;
+			const relRouteFile = path.relative(repoRoot, resource.fetchRoute.file);
+			postEmitNotes.push(
+				`${resource.type}: --enforce-registry is on, but no @record_snapshot(...) was found anywhere in ${relRouteFile} -- this resource may never get its first registry row, and every fetch/patch call against it will 404 until something registers it. Apply @record_snapshot to its own create-flow route function (or call handle_service.register() by hand at least once per resource), then re-emit. See D-handle-registry-enforcement in DECISIONS.md for the full bootstrapping explanation.`,
+			);
+		}
+	}
+
 	return { ...result, postEmitNotes };
 }

package/lib/cli.mjs

@@ -228,6 +228,40 @@ export const COMMANDS = {
 			operation: { type: 'string', default: null, required: true },
 		},
 	},
+	'dependency declare': {
+		usage: 'bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			'source-feature': { type: 'string', default: null, required: true },
+			'source-resource': { type: 'string', default: null, required: true },
+			'source-field': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			memo: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'dependency remove': {
+		usage: 'bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: null, required: true },
+			field: { type: 'string', default: null, required: true },
+			'source-feature': { type: 'string', default: null, required: true },
+			'source-resource': { type: 'string', default: null, required: true },
+			'source-field': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'dependency list': {
+		usage: 'bskel dependency list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'stack apply': {
 		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--json]',
 		options: {
@@ -409,6 +443,17 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	serve: {
+		usage: 'bskel serve [--port N] [--host <addr>] [--json]',
+		options: {
+			// min:0 (unlike stack apply --port's min:1) -- 0 is the standard "let the OS pick a free
+			// ephemeral port" sentinel, genuinely useful both for tests and for a user who doesn't care
+			// which port they get, not just a testing convenience.
+			port: { type: 'string', default: '4747', numeric: { min: 0, max: 65535 } },
+			host: { type: 'string', default: '127.0.0.1' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 };
 
 function describeParseArgsError(err, spec) {

package/lib/field-dependencies.mjs

@@ -0,0 +1,355 @@
+// D-field-dependency: declares that a field on one feature's resource is derived from a field on
+// some (possibly the same) feature's resource, tracked via the same disk-hash gate mechanism every
+// other gate in this project uses. See DECISIONS.md for the full design.
+//
+// Zero new source-scanning logic: a resource "field" resolves to a FILE the same way
+// lib/gate-definitions.mjs's `contract.recompute()` already resolves one -- via a feature's own
+// persisted brownfield-scan.json `related_modules[].{entities,dtos}[]`, both already `{className,
+// file}` on every adapter (D-gate-precision "Continued (part 3)", commit a8d647b). This module's
+// resolveClassFile() is the ONE function both `bskel dependency declare`'s validation and the
+// `dependencies` gate's recompute() call -- never two separately-maintained copies, so the token
+// that gets passed and the token later required can never diverge.
+import path from 'node:path';
+import { readJsonIfExists, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { listFeatures, loadFeatureFile } from './featurelifecycle.mjs';
+import { passNamedGate, requireNamedGate } from './gates.mjs';
+import { withLockSync } from './lock.mjs';
+import { requireValidFeatureId, slugWords } from './featureid.mjs';
+import { EXIT_CODES } from './exit-codes.mjs';
+
+const DEPENDENCIES_SCHEMA = 'sbf.field-dependency/1';
+
+// D-http-serving-layer: thrown by declareDependency/removeDependency/buildDependencyListReport
+// instead of calling bin/bskel.mjs's fail() (which calls process.exit() and can't be shared between
+// a CLI caller and an HTTP caller). Carries both an HTTP status AND the existing CLI exit-code/reason
+// vocabulary (lib/exit-codes.mjs) so a caller on either side derives its own response shape from the
+// SAME thrown error, rather than the CLI/HTTP paths each re-deciding "what does this failure mean"
+// independently and risking disagreement.
+export class DependencyOperationError extends Error {
+	constructor(message, { httpStatus = 400, exitCode = EXIT_CODES.BAD_ARGS, reasonCode = 'BAD_ARGS' } = {}) {
+		super(message);
+		this.name = 'DependencyOperationError';
+		this.httpStatus = httpStatus;
+		this.exitCode = exitCode;
+		this.reasonCode = reasonCode;
+	}
+}
+
+// D-http-serving-layer: requireValidFeatureId() throws a plain Error (it's a low-level primitive
+// shared by many OTHER commands too, so its own throw shape is deliberately left unchanged) -- an
+// uncaught plain Error reaching lib/http-server.mjs's handler would map to a misleading 500 instead
+// of the 400 a malformed feature id actually deserves. This rewraps it as a DependencyOperationError
+// right at the point of use, matching this module's own consistent error vocabulary end to end.
+function requireValidFeatureIdOr400(id) {
+	try {
+		requireValidFeatureId(id);
+	} catch (err) {
+		throw new DependencyOperationError(err.message, { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+}
+
+// A resolveClassFile() failure, translated into the (httpStatus, exitCode, reasonCode) triple --
+// 'no_scan_report' is a real prerequisite-not-established state (409/NOT_PASSED, matching the exact
+// ternary bin/bskel.mjs's cmdDependencyDeclare used before this was extracted); every other reason is
+// a genuine bad argument (400/BAD_ARGS).
+function resolutionFailureErrorOptions(resolution) {
+	return resolution.reason === 'no_scan_report'
+		? { httpStatus: 409, exitCode: EXIT_CODES.NOT_PASSED, reasonCode: 'MISSING_ARTIFACT' }
+		: { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' };
+}
+
+// D-field-dependency: shared error-message builder for resolveClassFile()'s own failure reasons --
+// used by both declare (target and source resolution) so the two error paths never phrase the same
+// underlying failure differently. Mirrors requireWarningCode's "known codes: ..." naming convention
+// for the one case (class_not_found) where naming the real alternatives is actionable. Moved here
+// (was bin/bskel.mjs) alongside declareDependency, its only caller.
+export function describeResolutionFailure(featureId, resourceType, resolution) {
+	switch (resolution.reason) {
+		case 'no_scan_report':
+			return `no brownfield-scan.json for feature "${featureId}" -- run \`bskel scan --feature ${featureId} --terms <a,b,c>\` first`;
+		case 'no_disposition':
+			return `feature "${featureId}" has no scan disposition yet -- run \`bskel scan disposition --feature ${featureId} --mode reuse|extend|replace|parallel --note "..."\` first`;
+		case 'module_not_found':
+			return `feature "${featureId}"'s disposed module no longer appears in its own scan report -- re-run \`bskel scan\`/\`bskel scan disposition\``;
+		case 'class_not_found':
+			return `no resource type "${resourceType}" found in feature "${featureId}"'s disposed module -- known classes: ${resolution.knownClasses?.join(', ') || '(none)'}`;
+		default:
+			return `could not resolve "${resourceType}" on feature "${featureId}"`;
+	}
+}
+
+export function dependenciesPath(root, featureId) {
+	return specPath(root, featureId, 'dependencies.json');
+}
+
+export function loadFieldDependencies(root, featureId) {
+	const path = dependenciesPath(root, featureId);
+	const parsed = readJsonIfExists(path);
+	if (parsed === null) return { schema: DEPENDENCIES_SCHEMA, feature_id: featureId, dependencies: [] };
+	const { ok, errors } = validateAgainstSchema('field-dependency.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${path}: does not match schemas/field-dependency.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveFieldDependencies(root, featureId, doc) {
+	const { ok, errors } = validateAgainstSchema('field-dependency.schema.json', doc);
+	if (!ok) {
+		throw new Error(`refusing to write invalid field dependencies for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	writeFileAtomic(dependenciesPath(root, featureId), `${JSON.stringify(doc, null, 2)}\n`);
+	return doc;
+}
+
+// The one, shared identity key -- edge-level, not target-level, since a target field CAN
+// legitimately have more than one source (e.g. a computed/concatenated field) -- unlike
+// patch-approvals' {resource,field} key, which is 1:1 by construction.
+export function dependencyKey(dep) {
+	return `${dep.target.resourceType}::${dep.target.fieldName}->${dep.source.feature}::${dep.source.resourceType}::${dep.source.fieldName}`;
+}
+
+// Resolves a {featureId, resourceType} pair to the real source file backing it, via that
+// feature's own disposed module's entities/dtos -- exactly the lookup contract.recompute() already
+// does for its own module_file: tokens, just reusable across features instead of within one.
+// Deliberately excludes controllers/enums: a controller isn't "a resource with fields" in the
+// relevant sense, and an enum's "fields" are its constants, a structurally different concept this
+// slice doesn't address.
+export function resolveClassFile(root, featureId, resourceType) {
+	const reportPath = specPath(root, featureId, 'brownfield-scan.json');
+	const report = readJsonIfExists(reportPath);
+	if (!report) return { file: null, reason: 'no_scan_report' };
+	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
+	if (!moduleName) return { file: null, reason: 'no_disposition' };
+	const mod = report.related_modules?.find((m) => m.module === moduleName);
+	if (!mod) return { file: null, reason: 'module_not_found' };
+	const candidates = [...(mod.entities ?? []), ...(mod.dtos ?? [])];
+	const match = candidates.find((item) => item.className === resourceType);
+	if (!match?.file) return { file: null, reason: 'class_not_found', knownClasses: candidates.map((c) => c.className) };
+	return { file: match.file, reason: null };
+}
+
+// D-dependency-propagation-notice: the reverse of resolveClassFile()'s own forward lookup -- "who
+// else declared a dependency ON this feature" instead of "what does this feature's dependency point
+// at". Used by `contract emit`/`handles emit` (bin/bskel.mjs's describeDownstreamImpact()) to warn
+// the SOURCE side that other features are relying on what it's about to re-derive. One level only --
+// no recursive graph walk, matching this whole feature's own explicit non-goal of full cycle
+// detection (see D-field-dependency). listFeatures() is lib/featurelifecycle.mjs's schema-validated,
+// archived-filtering version (not lib/workflow.mjs's bare directory scan) -- an archived feature's
+// stale dependency isn't worth nagging a human about.
+export function listDownstreamDependents(root, featureId) {
+	const dependents = [];
+	for (const record of listFeatures(root)) {
+		if (record.feature_id === featureId) continue;
+		const doc = loadFieldDependencies(root, record.feature_id);
+		for (const dep of doc.dependencies) {
+			if (dep.source.feature === featureId) dependents.push({ dependentFeature: record.feature_id, dep });
+		}
+	}
+	return dependents;
+}
+
+// D-http-serving-layer: the mutation core of `bskel dependency declare`, extracted so `bin/bskel.mjs`'s
+// cmdDependencyDeclare (CLI) and lib/http-server.mjs's POST handler call the IDENTICAL code -- never
+// two separately-maintained copies of "what does declaring a dependency actually do" that could
+// drift, the same principle resolveClassFile()'s own header comment already establishes for itself.
+// Throws DependencyOperationError on any failure; the CLI wrapper maps that back to fail(), the HTTP
+// handler maps it to a JSON error response -- both derive their own response shape from the SAME
+// thrown error rather than re-deciding independently.
+export function declareDependency(root, { feature, resource, field, sourceFeature, sourceResource, sourceField, reason, memo }) {
+	requireValidFeatureIdOr400(feature);
+	requireValidFeatureIdOr400(sourceFeature); // path-injection defense, same as every --feature flag (D-security-3)
+	if (!reason || !reason.trim()) {
+		throw new DependencyOperationError('bskel dependency declare requires --reason "..." -- every dependency must be auditable', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	if (feature === sourceFeature && resource === sourceResource && field === sourceField) {
+		throw new DependencyOperationError(`"${resource}.${field}" cannot depend on itself`, { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+
+	const target = resolveClassFile(root, feature, resource);
+	if (!target.file) {
+		throw new DependencyOperationError(describeResolutionFailure(feature, resource, target), resolutionFailureErrorOptions(target));
+	}
+	const source = resolveClassFile(root, sourceFeature, sourceResource);
+	if (!source.file) {
+		throw new DependencyOperationError(describeResolutionFailure(sourceFeature, sourceResource, source), resolutionFailureErrorOptions(source));
+	}
+
+	const dep = {
+		target: { resourceType: resource, fieldName: field },
+		source: { feature: sourceFeature, resourceType: sourceResource, fieldName: sourceField },
+		reason,
+		...(memo ? { memo } : {}),
+		at: new Date().toISOString(),
+	};
+
+	// S5 (D-persistence-integrity): same load-modify-save-under-one-lock shape cmdContractWaive
+	// already uses, for the identical reason -- closes the lost-update race between this function's
+	// own load and its save. Safe under concurrent HTTP requests too: withLockSync is fully
+	// synchronous (fs.mkdirSync + a blocking retry loop, no `await` anywhere inside), and Node's
+	// single-threaded event loop means a request handler runs to completion without ever yielding to
+	// a second concurrently-arriving request -- verified directly against lib/lock.mjs, not assumed.
+	const updated = withLockSync(root, 'state', () => {
+		const current = loadFieldDependencies(root, feature);
+		const key = dependencyKey(dep);
+		const next = {
+			schema: 'sbf.field-dependency/1',
+			feature_id: feature,
+			dependencies: [...current.dependencies.filter((d) => dependencyKey(d) !== key), dep],
+		};
+		saveFieldDependencies(root, feature, next);
+		return next;
+	});
+	const gateState = passNamedGate(root, 'dependencies', feature, { dependency_count: updated.dependencies.length });
+	return { dependency: dep, gate: gateState.gates.dependencies };
+}
+
+// D-http-serving-layer: the mutation core of `bskel dependency remove`, mirroring declareDependency's
+// own shared-primitive rationale above.
+export function removeDependency(root, { feature, resource, field, sourceFeature, sourceResource, sourceField, reason }) {
+	requireValidFeatureIdOr400(feature);
+	requireValidFeatureIdOr400(sourceFeature);
+	if (!reason || !reason.trim()) {
+		throw new DependencyOperationError('bskel dependency remove requires --reason "..." -- every removal must be auditable', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+
+	const targetKey = dependencyKey({
+		target: { resourceType: resource, fieldName: field },
+		source: { feature: sourceFeature, resourceType: sourceResource, fieldName: sourceField },
+	});
+
+	const updated = withLockSync(root, 'state', () => {
+		const current = loadFieldDependencies(root, feature);
+		const match = current.dependencies.find((d) => dependencyKey(d) === targetKey);
+		if (!match) {
+			const known = current.dependencies.map((d) => `${d.target.resourceType}.${d.target.fieldName} <- ${d.source.feature}/${d.source.resourceType}.${d.source.fieldName}`);
+			throw new DependencyOperationError(
+				`no declared dependency matches "${resource}.${field} <- ${sourceFeature}/${sourceResource}.${sourceField}" -- currently declared: ${known.join('; ') || '(none)'}`,
+				{ httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' },
+			);
+		}
+		const next = {
+			schema: 'sbf.field-dependency/1',
+			feature_id: feature,
+			dependencies: current.dependencies.filter((d) => dependencyKey(d) !== targetKey),
+		};
+		saveFieldDependencies(root, feature, next);
+		return next;
+	});
+	const gateState = passNamedGate(root, 'dependencies', feature, { dependency_count: updated.dependencies.length });
+	return { removed: true, gate: gateState.gates.dependencies };
+}
+
+// D-http-serving-layer: the read core of `bskel dependency list`, mirroring the two mutation
+// functions' own shared-primitive rationale. Read-only, gate-independent like cmdHandlesAudit --
+// always resolves current state (even past whatever token the gate itself last stored) so a diverged
+// dependency is visible here immediately, not only after the next explicit `gate require`.
+export function buildDependencyListReport(root, featureId) {
+	requireValidFeatureIdOr400(featureId);
+	const record = loadFeatureFile(root, featureId);
+	if (!record) {
+		throw new DependencyOperationError(
+			`no feature.json at specs/${featureId}/ -- run \`bskel feature init --slug ${slugWords(featureId).join('-')}\` first (or hand-write specs/${featureId}/feature.json with a minted feature_uid)`,
+			{ httpStatus: 404, exitCode: EXIT_CODES.NOT_PASSED, reasonCode: 'MISSING_ARTIFACT' },
+		);
+	}
+	const doc = loadFieldDependencies(root, featureId);
+
+	const rows = doc.dependencies.map((dep) => {
+		const t = resolveClassFile(root, featureId, dep.target.resourceType);
+		const s = resolveClassFile(root, dep.source.feature, dep.source.resourceType);
+		return {
+			...dep,
+			target_resolved: Boolean(t.file),
+			target_file: t.file ? path.relative(root, t.file) : null,
+			target_unresolved_reason: t.reason,
+			source_resolved: Boolean(s.file),
+			source_file: s.file ? path.relative(root, s.file) : null,
+			source_unresolved_reason: s.reason,
+		};
+	});
+	const gateResult = requireNamedGate(root, 'dependencies', featureId);
+
+	return {
+		schema: 'sbf.dependency-list/1',
+		feature_id: featureId,
+		dependencies: rows,
+		gate: { status: gateResult.status, code: gateResult.code, changed_inputs: gateResult.changed_inputs ?? null },
+	};
+}
+
+// D-http-serving-layer: these two prefixes MUST stay byte-identical to lib/gate-definitions.mjs's own
+// TARGET_FIELD_FILE_PREFIX/SOURCE_FIELD_FILE_PREFIX constants -- duplicated here (2 short string
+// literals) rather than exported+imported, the same tradeoff lib/workflow.mjs's own
+// awaitingDispositionCommand() already documents for itself ("duplicated here rather than
+// exported+imported... for two lines of text"). If gate-definitions.mjs's own tokens ever change,
+// this must change with them.
+const TARGET_FIELD_FILE_PREFIX = 'target_field_file:';
+const SOURCE_FIELD_FILE_PREFIX = 'source_field_file:';
+
+// D-http-serving-layer: the repo-wide aggregate lib/http-server.mjs's `GET /api/graph` serves --
+// every distinct {feature, resourceType} pair that participates in ANY declared dependency (a
+// resource is only "on the graph" because it has a real wire, not an independent "list every scanned
+// class" feature nothing else asks for), plus one wire per declared dependency with a HONEST 3-value
+// `resolution` ('synced'/'stale'/'unresolved') grounded in what's actually computable -- this does
+// NOT recreate the original Fieldwire UI mockup's 4-state vocabulary (its 'conflict' state meant a
+// type-mismatch/propagation decision this backend has no data for). Per-edge attribution reuses the
+// SAME changed_inputs-prefix-matching precision bin/bskel.mjs's describeDownstreamImpact() (Slice 2)
+// already established, so a feature stale for one dependency's reason never marks an unrelated
+// dependency 'stale' too.
+export function buildDependencyGraph(root) {
+	const nodes = new Map();
+	const wires = [];
+
+	const nodeFor = (featureId, resourceType) => {
+		const key = `${featureId}::${resourceType}`;
+		if (!nodes.has(key)) {
+			const r = resolveClassFile(root, featureId, resourceType);
+			nodes.set(key, { id: key, feature: featureId, resourceType, file: r.file ? path.relative(root, r.file) : null, resolved: Boolean(r.file) });
+		}
+		return key;
+	};
+
+	for (const record of listFeatures(root)) {
+		const doc = loadFieldDependencies(root, record.feature_id);
+		if (doc.dependencies.length === 0) continue;
+		const gate = requireNamedGate(root, 'dependencies', record.feature_id);
+		const changedInputs = new Set(gate.changed_inputs ?? []);
+
+		for (const dep of doc.dependencies) {
+			const targetNode = nodeFor(record.feature_id, dep.target.resourceType);
+			const sourceNode = nodeFor(dep.source.feature, dep.source.resourceType);
+			const t = resolveClassFile(root, record.feature_id, dep.target.resourceType);
+			const s = resolveClassFile(root, dep.source.feature, dep.source.resourceType);
+
+			let resolution = 'synced';
+			let unresolvedSide = null;
+			let unresolvedReason = null;
+			if (!t.file) { resolution = 'unresolved'; unresolvedSide = 'target'; unresolvedReason = t.reason; }
+			else if (!s.file) { resolution = 'unresolved'; unresolvedSide = 'source'; unresolvedReason = s.reason; }
+			else if (gate.status === 'stale') {
+				const targetKey = `${TARGET_FIELD_FILE_PREFIX}${dep.target.resourceType}`;
+				const sourceKey = `${SOURCE_FIELD_FILE_PREFIX}${dep.source.feature}:${dep.source.resourceType}`;
+				if (changedInputs.has(targetKey) || changedInputs.has(sourceKey)) resolution = 'stale';
+			}
+
+			wires.push({
+				id: `${targetNode}->${sourceNode}::${dep.target.fieldName}->${dep.source.fieldName}`,
+				feature: record.feature_id,
+				target: dep.target,
+				source: dep.source,
+				reason: dep.reason,
+				memo: dep.memo ?? null,
+				hasMemo: Boolean(dep.memo),
+				at: dep.at,
+				resolution,
+				unresolvedSide,
+				unresolvedReason,
+			});
+		}
+	}
+
+	return { nodes: [...nodes.values()], wires };
+}

package/lib/gate-definitions.mjs

@@ -22,6 +22,7 @@ import { sha256File, fileMode, readJsonIfExists, resolveWithinRoot } from './fsu
 import { specPath, sbfPath } from './paths.mjs';
 import { ADAPTERS, adapterById } from '../scanners/registry.mjs';
 import { loadManifest } from './handles-manifest.mjs';
+import { dependenciesPath, resolveClassFile } from './field-dependencies.mjs';
 
 // S2: prefix for stack's per-applied-file input keys -- lib/gates.mjs's diffInputs() compares
 // top-level keys only, so a manifest-shaped input (one hash per applied file) has to flatten
@@ -41,6 +42,12 @@ const SOURCE_FILE_PREFIX = 'source_file:';
 // to the DISPOSED module specifically (a narrower set than SOURCE_FILE_PREFIX's whole-adapter
 // read-set), so the `contract` gate stops being sensitive to every Java file in the repo.
 const MODULE_FILE_PREFIX = 'module_file:';
+// D-field-dependency: flattened per-declared-dependency file tokens, one key per DISTINCT
+// {feature, resourceType} the feature's own dependencies.json actually references (deduped --
+// two fields on the same class collapse to one key, since this gate has no field-level parser and
+// would otherwise just repeat the identical file hash N times with zero added diagnostic value).
+const TARGET_FIELD_FILE_PREFIX = 'target_field_file:';
+const SOURCE_FIELD_FILE_PREFIX = 'source_field_file:';
 
 // The preflight and stack gates are repo-scoped, not feature-scoped -- preflight runs before a
 // feature_id exists at all, and a stack choice is a project-wide decision, not per-feature.
@@ -210,6 +217,31 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-field-dependency: a resolved file gets its real content hash; an UNRESOLVABLE one gets a
+	// labeled sentinel string instead of a bare null -- unlike contract.recompute()'s own bare-null
+	// precedent (safe there only because the path itself is always deterministic via specPath()),
+	// here "no file resolves at all" (a renamed/deleted class) is a distinct failure mode from "a
+	// known file was deleted" (also a real, legitimate null from sha256File), and a human reading
+	// `changed_inputs` deserves to know which. Both are equally fail-closed: neither can coincide
+	// with a previously-stored good hash.
+	dependencies: {
+		name: 'dependencies',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => {
+			const depsPath = dependenciesPath(root, featureId);
+			const inputs = { dependencies_hash: sha256File(depsPath) };
+			const doc = readJsonIfExists(depsPath);
+			const fileTokenFor = (resolution) => (resolution.file ? sha256File(resolution.file) : `unresolved:${resolution.reason}`);
+			for (const dep of doc?.dependencies ?? []) {
+				const targetKey = `${TARGET_FIELD_FILE_PREFIX}${dep.target.resourceType}`;
+				if (!(targetKey in inputs)) inputs[targetKey] = fileTokenFor(resolveClassFile(root, featureId, dep.target.resourceType));
+				const sourceKey = `${SOURCE_FIELD_FILE_PREFIX}${dep.source.feature}:${dep.source.resourceType}`;
+				if (!(sourceKey in inputs)) inputs[sourceKey] = fileTokenFor(resolveClassFile(root, dep.source.feature, dep.source.resourceType));
+			}
+			return inputs;
+		},
+	},
 	// Staleness = the generated Java (or the contract it was generated from) has moved since
 	// emit -- NOT "does the migration still match the DB schema" (unknowable without a live DB
 	// connection this tool deliberately never opens on its own, see D-migration-scope). Note
@@ -283,7 +315,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 // test/gate-definitions.test.mjs asserts this stays exactly in sync with GATE_DEFINITIONS' own
 // key set, so a gate added to one and not the other fails loudly instead of silently vanishing
 // from `bskel verify` the way `stack` did before this module existed.
-export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'contract', 'handles', 'stack', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'contract', 'dependencies', 'handles', 'stack', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;

package/lib/http-server.mjs

@@ -0,0 +1,172 @@
+// D-http-serving-layer: a native node:http server (zero new dependencies -- this package ships no
+// web framework) exposing read/write JSON endpoints over the field-dependency data model, plus a
+// minimal bundled sanity-check UI page. Every route handler calls straight into the SAME lib/
+// functions bin/bskel.mjs's CLI commands call (declareDependency/removeDependency/
+// buildDependencyListReport/listFeatures/computeWorkflowState) -- there is no second copy of any
+// business logic here, only HTTP transport (routing, CORS, JSON (de)serialization). See
+// DECISIONS.md's D-http-serving-layer for the full design and the CORS-asymmetry security reasoning.
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { listFeatures } from './featurelifecycle.mjs';
+import { computeWorkflowState } from './workflow.mjs';
+import { isValidFeatureId } from './featureid.mjs';
+import {
+	buildDependencyListReport, buildDependencyGraph, declareDependency, removeDependency, DependencyOperationError,
+} from './field-dependencies.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const UI_HTML_PATH = path.join(__dirname, 'serve-ui.html');
+
+// GET/HEAD/their own OPTIONS preflight get the wildcard; POST/DELETE never do -- an unrestricted
+// Access-Control-Allow-Origin on a mutating route would let any website a user's browser has open
+// silently mutate their repo via a background fetch. The bundled UI page (served BY this same
+// server) is same-origin and completely unaffected -- CORS only ever applies cross-origin.
+const CORS_METHODS = new Set(['GET', 'HEAD']);
+
+function sendJson(res, status, body, { cors = false } = {}) {
+	const payload = JSON.stringify(body, null, 2);
+	const headers = { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(payload) };
+	if (cors) headers['Access-Control-Allow-Origin'] = '*';
+	res.writeHead(status, headers);
+	res.end(payload);
+}
+
+function sendError(res, err, { cors = false } = {}) {
+	if (err instanceof DependencyOperationError) {
+		sendJson(res, err.httpStatus, { error: err.message, reasonCode: err.reasonCode }, { cors });
+		return;
+	}
+	// D-http-serving-layer: everything user-input-shaped throws DependencyOperationError (see
+	// requireValidFeatureIdOr400 in lib/field-dependencies.mjs) -- reaching here means a genuine,
+	// unexpected failure (e.g. a filesystem error), so 500 is the honest answer, not a guess.
+	sendJson(res, 500, { error: err.message ?? 'internal error' }, { cors });
+}
+
+// Bounds the body a single request can force this process to buffer -- a local,
+// single-user dev server still shouldn't let an unbounded body exhaust memory.
+const MAX_BODY_BYTES = 1_000_000;
+
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on('data', (chunk) => {
+			size += chunk.length;
+			if (size > MAX_BODY_BYTES) {
+				reject(new DependencyOperationError(`request body exceeds ${MAX_BODY_BYTES} bytes`, { httpStatus: 413, reasonCode: 'BAD_ARGS' }));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on('end', () => {
+			if (chunks.length === 0) { resolve({}); return; }
+			let parsed;
+			try {
+				parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+			} catch {
+				reject(new DependencyOperationError('request body is not valid JSON', { httpStatus: 400, reasonCode: 'BAD_ARGS' }));
+				return;
+			}
+			if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+				reject(new DependencyOperationError('request body must be a JSON object', { httpStatus: 400, reasonCode: 'BAD_ARGS' }));
+				return;
+			}
+			resolve(parsed);
+		});
+		req.on('error', reject);
+	});
+}
+
+let uiHtmlCache = null;
+function serveUiPage(res) {
+	if (uiHtmlCache === null) uiHtmlCache = fs.readFileSync(UI_HTML_PATH, 'utf8');
+	res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Length': Buffer.byteLength(uiHtmlCache) });
+	res.end(uiHtmlCache);
+}
+
+const FEATURE_STATUS_RE = /^\/api\/features\/([^/]+)\/status$/;
+const FEATURE_DEPENDENCIES_RE = /^\/api\/features\/([^/]+)\/dependencies$/;
+
+async function handleRequest(root, req, res) {
+	let url;
+	try {
+		url = new URL(req.url, `http://${req.headers.host ?? 'localhost'}`);
+	} catch {
+		sendJson(res, 400, { error: 'invalid request URL' });
+		return;
+	}
+	const { pathname } = url;
+	const method = req.method ?? 'GET';
+	const cors = CORS_METHODS.has(method);
+
+	if (method === 'OPTIONS') {
+		const headers = { 'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS', 'Access-Control-Allow-Headers': 'Content-Type' };
+		// Only ever grant a preflight for GET-eligible routes -- a POST/DELETE preflight gets no
+		// Access-Control-Allow-Origin, so the browser refuses to send the real cross-origin write.
+		if (pathname === '/' || pathname.startsWith('/api/')) headers['Access-Control-Allow-Origin'] = '*';
+		res.writeHead(204, headers);
+		res.end();
+		return;
+	}
+
+	try {
+		if (method === 'GET' && pathname === '/') { serveUiPage(res); return; }
+		if (method === 'GET' && pathname === '/api/health') { sendJson(res, 200, { status: 'ok', repo: root }, { cors }); return; }
+		if (method === 'GET' && pathname === '/api/features') { sendJson(res, 200, { features: listFeatures(root) }, { cors }); return; }
+		if (method === 'GET' && pathname === '/api/graph') { sendJson(res, 200, buildDependencyGraph(root), { cors }); return; }
+
+		const statusMatch = pathname.match(FEATURE_STATUS_RE);
+		if (method === 'GET' && statusMatch) {
+			const featureId = decodeURIComponent(statusMatch[1]);
+			if (!isValidFeatureId(featureId)) { sendJson(res, 400, { error: `invalid feature id "${featureId}"` }, { cors }); return; }
+			sendJson(res, 200, computeWorkflowState(root, featureId), { cors });
+			return;
+		}
+
+		const depsMatch = pathname.match(FEATURE_DEPENDENCIES_RE);
+		if (depsMatch) {
+			const featureId = decodeURIComponent(depsMatch[1]);
+			if (!isValidFeatureId(featureId)) { sendJson(res, 400, { error: `invalid feature id "${featureId}"` }, { cors }); return; }
+
+			if (method === 'GET') { sendJson(res, 200, buildDependencyListReport(root, featureId), { cors }); return; }
+			if (method === 'POST') {
+				const body = await readJsonBody(req);
+				const result = declareDependency(root, { feature: featureId, ...body });
+				sendJson(res, 201, result); // no CORS -- mutating route, same-origin only
+				return;
+			}
+			if (method === 'DELETE') {
+				const body = await readJsonBody(req);
+				const result = removeDependency(root, { feature: featureId, ...body });
+				sendJson(res, 200, result); // no CORS -- mutating route
+				return;
+			}
+		}
+
+		sendJson(res, 404, { error: `not found: ${method} ${pathname}` }, { cors });
+	} catch (err) {
+		sendError(res, err, { cors });
+	}
+}
+
+// Default host 127.0.0.1 (loopback only) -- explicit --host opt-in required to expose beyond it,
+// matching this project's established "safe default, explicit override" convention (e.g.
+// --enforce-registry). Returns once the server has actually bound (server.address() is real), not
+// merely once listen() was called -- callers (bin/bskel.mjs's cmdServe, tests) need the REAL bound
+// port when 0 was requested.
+export function createHttpServer(root, { host = '127.0.0.1', port = 4747 } = {}) {
+	const server = http.createServer((req, res) => {
+		handleRequest(root, req, res).catch((err) => sendError(res, err));
+	});
+	return new Promise((resolve, reject) => {
+		server.once('error', reject);
+		server.listen(port, host, () => {
+			server.removeListener('error', reject);
+			const addr = server.address();
+			resolve({ server, host: addr.address, port: addr.port, url: `http://${addr.address}:${addr.port}` });
+		});
+	});
+}

package/lib/serve-ui.html

@@ -0,0 +1,117 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>bskel serve</title>
+<style>
+	:root { color-scheme: light dark; }
+	body { font-family: ui-monospace, Menlo, Consolas, monospace; max-width: 960px; margin: 2rem auto; padding: 0 1rem; line-height: 1.4; }
+	h1 { font-size: 1.1rem; }
+	h2 { font-size: 1rem; margin-top: 2rem; }
+	table { border-collapse: collapse; width: 100%; margin-top: 0.5rem; }
+	th, td { text-align: left; padding: 0.3rem 0.6rem; border-bottom: 1px solid #8884; font-size: 0.85rem; }
+	.resolution-synced { color: #2a2; }
+	.resolution-stale { color: #c90; }
+	.resolution-unresolved { color: #d33; }
+	form { margin-top: 0.5rem; display: grid; grid-template-columns: repeat(3, 1fr); gap: 0.4rem; max-width: 720px; }
+	form label { display: flex; flex-direction: column; font-size: 0.75rem; gap: 0.15rem; }
+	form input { font: inherit; padding: 0.25rem; }
+	form button { grid-column: 1 / -1; padding: 0.4rem; font: inherit; cursor: pointer; }
+	#formStatus { font-size: 0.85rem; margin-top: 0.4rem; }
+	.muted { opacity: 0.6; }
+</style>
+</head>
+<body>
+<h1>bskel serve -- functionality check</h1>
+<p class="muted">Not a redesign of the original Fieldwire mockup -- this exists to prove the API actually works, nothing more.</p>
+
+<h2>Nodes</h2>
+<table id="nodesTable"><thead><tr><th>feature</th><th>resourceType</th><th>file</th><th>resolved</th></tr></thead><tbody></tbody></table>
+
+<h2>Wires</h2>
+<table id="wiresTable"><thead><tr><th>target</th><th>source</th><th>resolution</th><th>memo</th></tr></thead><tbody></tbody></table>
+
+<h2>Declare a new dependency</h2>
+<form id="declareForm">
+	<label>feature <input name="feature" required></label>
+	<label>resource <input name="resource" required></label>
+	<label>field <input name="field" required></label>
+	<label>source feature <input name="sourceFeature" required></label>
+	<label>source resource <input name="sourceResource" required></label>
+	<label>source field <input name="sourceField" required></label>
+	<label style="grid-column: 1 / -1">reason <input name="reason" required></label>
+	<button type="submit">Declare</button>
+</form>
+<div id="formStatus"></div>
+
+<script>
+// D-http-serving-layer: `reason`/`memo` (and every other string field) are free text a human types
+// via `bskel dependency declare --reason/--memo` or this page's own POST form -- never assumed safe
+// to inject as markup. Every cell here is built via textContent, never innerHTML/insertAdjacentHTML,
+// so a value like `<script>...` or `<img onerror=...>` renders as inert text, not executes.
+function td(text) {
+	const cell = document.createElement('td');
+	cell.textContent = text;
+	return cell;
+}
+
+async function loadGraph() {
+	const res = await fetch('/api/graph');
+	const graph = await res.json();
+
+	const nodesBody = document.querySelector('#nodesTable tbody');
+	nodesBody.replaceChildren();
+	for (const n of graph.nodes) {
+		const tr = document.createElement('tr');
+		tr.append(td(n.feature), td(n.resourceType), td(n.file ?? '(unresolved)'), td(String(n.resolved)));
+		nodesBody.appendChild(tr);
+	}
+
+	const wiresBody = document.querySelector('#wiresTable tbody');
+	wiresBody.replaceChildren();
+	for (const w of graph.wires) {
+		const tr = document.createElement('tr');
+		const target = `${w.feature}/${w.target.resourceType}.${w.target.fieldName}`;
+		const source = `${w.source.feature}/${w.source.resourceType}.${w.source.fieldName}`;
+		const resolutionCell = td(`${w.resolution}${w.unresolvedReason ? ` (${w.unresolvedReason})` : ''}`);
+		resolutionCell.className = `resolution-${w.resolution}`;
+		tr.append(td(target), td(source), resolutionCell, td(w.hasMemo ? w.memo : ''));
+		wiresBody.appendChild(tr);
+	}
+}
+
+document.getElementById('declareForm').addEventListener('submit', async (ev) => {
+	ev.preventDefault();
+	const form = new FormData(ev.target);
+	const feature = form.get('feature');
+	const statusEl = document.getElementById('formStatus');
+	statusEl.textContent = 'declaring...';
+	try {
+		const res = await fetch(`/api/features/${encodeURIComponent(feature)}/dependencies`, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				resource: form.get('resource'), field: form.get('field'),
+				sourceFeature: form.get('sourceFeature'), sourceResource: form.get('sourceResource'), sourceField: form.get('sourceField'),
+				reason: form.get('reason'),
+			}),
+		});
+		const body = await res.json();
+		if (!res.ok) throw new Error(body.error ?? `HTTP ${res.status}`);
+		statusEl.textContent = `declared, gate: ${body.gate.status}`;
+		ev.target.reset();
+		await loadGraph();
+	} catch (err) {
+		statusEl.textContent = `error: ${err.message}`;
+	}
+});
+
+loadGraph().catch((err) => {
+	const p = document.createElement('p');
+	p.style.color = '#d33';
+	p.textContent = `failed to load /api/graph: ${err.message}`;
+	document.body.appendChild(p);
+});
+</script>
+</body>
+</html>

package/lib/workflow.mjs

@@ -32,8 +32,16 @@ const ESTABLISH_COMMAND = {
 	preflight: () => 'bskel preflight',
 	scan: (id) => `bskel scan --feature ${id} --terms <a,b,c>`,
 	contract: (id) => `bskel contract emit --feature ${id}`,
+	// D-field-dependency: this and `conformance` immediately below were BOTH missing before this
+	// item -- found live while adding this one, same crash class, fixed together. Neither had ever
+	// been exercised through `next` on a stale REQUIRED_WHEN_PRESENT gate (no test covered it) --
+	// without an entry here, `computeWorkflowState()` calls `ESTABLISH_COMMAND[gateName](featureId)`
+	// directly on the first real stale occurrence and throws a raw TypeError instead of a clean
+	// stale report.
+	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
 	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
 	stack: () => 'bskel stack apply --choice <id> --apply',
+	conformance: (id) => `bskel observe emit --feature ${id}   # then: run the target app, then bskel observe import --feature ${id} --receipts <path>`,
 };
 
 // awaiting_disposition needs a genuinely different remediation per gate, not a re-run --
@@ -54,7 +62,7 @@ function awaitingDispositionCommand(gateName, featureId) {
 // opposed to being a pure read (bskel verify, bskel status, bskel next itself). Matched by the
 // command's own leading "bskel <verb...>" prefix so this can't silently drift from the actual
 // command names above.
-const MUTATING_PREFIXES = ['bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive', 'bskel gate force', 'bskel handles emit', 'bskel handles plan', 'bskel stack apply'];
+const MUTATING_PREFIXES = ['bskel preflight', 'bskel scan', 'bskel feature init', 'bskel contract emit', 'bskel contract waive', 'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit', 'bskel handles plan', 'bskel stack apply'];
 
 function action(command, reason) {
 	return { command, reason, mutating: MUTATING_PREFIXES.some((p) => command.startsWith(p)) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",

package/schemas/field-dependency.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:field-dependency:1",
+  "title": "backend-skeleton field-dependency declarations",
+  "description": "Validates specs/<feature_id>/dependencies.json, written by `bskel dependency declare`/`bskel dependency remove` -- see D-field-dependency in DECISIONS.md. Each entry declares that ONE field on this feature's own resource is derived from a field on some (possibly the same) feature's resource. Deliberately no synthetic id: an entry is addressed by its own natural compound key (target.resourceType/fieldName + source.feature/resourceType/fieldName), matching contract-resolution.schema.json's {code,subject} and patch-approvals.schema.json's {resource,field} precedent. This is a data-model-only slice -- nothing yet reads this file to generate code; the `dependencies` gate (lib/gate-definitions.mjs) only tracks whether it and what it points at have moved.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "dependencies"],
+  "properties": {
+    "schema": { "const": "sbf.field-dependency/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "dependencies": {
+      "description": "One entry per declared edge. `target` is always a resource on THIS file's own feature_id (never repeated per-entry); `source` names its own feature explicitly since it may differ (cross-feature) or be the same (same-feature dependencies are supported by construction, not a special case).",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["target", "source", "reason", "at"],
+        "properties": {
+          "target": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["resourceType", "fieldName"],
+            "properties": {
+              "resourceType": { "type": "string", "minLength": 1 },
+              "fieldName": { "type": "string", "minLength": 1 }
+            }
+          },
+          "source": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["feature", "resourceType", "fieldName"],
+            "properties": {
+              "feature": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+              "resourceType": { "type": "string", "minLength": 1 },
+              "fieldName": { "type": "string", "minLength": 1 }
+            }
+          },
+          "reason": { "type": "string" },
+          "memo": {
+            "description": "Optional free-text intent, e.g. captured from a future UI's own resolve-decision flow. Inert documentation only in this slice -- nothing reads it yet.",
+            "type": "string"
+          },
+          "at": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}