backend-skeleton 1.0.0-beta.9 → 1.0.0

package/handles/providers/typescript-express/observe.mjs

@@ -0,0 +1,101 @@
+// D-runtime-conformance-receipts: the emit-side half of opt-in runtime contract-conformance
+// checking for typescript-express. Mirrors handles/providers/python-fastapi/observe.mjs's own
+// shape -- observe and handles are orthogonal capabilities that happen to share the same repo-wide
+// "generated infra" pattern, not the same feature. See DECISIONS.md for the full WHY, including the
+// TS-specific response-body-capture note (res.json patch + res.on('finish', ...), never a wrapped
+// return value the way java's @Around/python's `await fn(...)` are) the generated
+// observeContract.ts itself implements.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { sha256File } from '../../../lib/fsutil.mjs';
+import { specPath } from '../../../lib/paths.mjs';
+import { projectOperation } from '../../observe-schema-projection.mjs';
+
+const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
+
+// Repo-wide, shared across every feature that ever runs `bskel observe emit` -- observedSchema.ts
+// discovers every schemas/*.observed-schema.json file at MODULE LOAD time rather than being
+// regenerated per feature, so these three files are true infra (create-once-per-repo, all-or-nothing
+// conflict unit), same treatment INFRA_FILES gives handles' own handlesDir infra files (codec.ts/
+// registry.ts/router.ts). Three files, not python's four -- TS/Node has no __init__.py-equivalent
+// package marker a plain relative-import directory needs to be importable, so there is no
+// __init__.ts-shaped file to carry over. None of the three need any {{VAR}} substitution -- observe
+// stays decoupled from handles/, cross-imports between them are relative `from './contractCheck'`.
+const INFRA_FILES = [
+	{ template: 'contractCheck.ts.tmpl', target: 'contractCheck.ts' },
+	{ template: 'observedSchema.ts.tmpl', target: 'observedSchema.ts' },
+	{ template: 'observeContract.ts.tmpl', target: 'observeContract.ts' },
+];
+
+function render(templatePath, vars) {
+	let content = fs.readFileSync(templatePath, 'utf8');
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, content);
+}
+
+// See DECISIONS.md D-runtime-conformance-receipts. `contract` is the already-loaded, already
+// schema-validated feature contract (bin/bskel.mjs's loadContract) -- this function does not read
+// specs/ itself. `plan` is the already-computed typescript-express resource plan (bin/bskel.mjs
+// calls planTypeScriptExpress() before this, the same --module dependency python-fastapi's own
+// observe emit already established) -- only `plan.srcRoot` is used here, `plan.resources`/
+// `plan.notes` are computed and simply unused, same tolerance emitUnits() already extends to
+// java's/python's own `resolverUnits: []`. There is no per-resource generated file here (a human
+// inserts observeContract('...') directly into an existing route's own middleware array), so
+// emitUnits()'s resolver/orphan machinery has nothing to do.
+export function emitObserveTypeScriptExpress({ repoRoot, featureId, contract, plan, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const observeDir = path.join(plan.srcRoot, 'observe');
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(observeDir, f.target),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), {}),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
+
+	// The projected observed-schema.json resource -- regenerated unconditionally every run, like
+	// handles' own migration.sql (and both other providers' own observe schema resource), for the
+	// identical reason: nobody hand-finishes a generated data file, so O2-style conflict tracking
+	// buys nothing here. `kind: 'spec'` matches migration.sql's own action-reporting convention --
+	// NOT the `kind: 'infra'` A13 gave resolvers_index.ts, which was a genuinely hand-editable
+	// barrel; this is a generated data file, same class as migration.sql, not that one.
+	const operations = {};
+	for (const [opId, opContract] of Object.entries(contract.operations)) {
+		operations[opId] = projectOperation(opContract);
+	}
+	const contractRef = sha256File(specPath(repoRoot, featureId, 'contracts', `${featureId}.schema.json`));
+	const schemaContent = `${JSON.stringify({ sbf_observed_schema: '1', feature_id: featureId, feature_uid: contract.feature_uid, contract_ref: contractRef, operations }, null, '\t')}\n`;
+	const schemaPath = path.join(observeDir, 'schemas', `${featureId}.observed-schema.json`);
+	const schemaRelPath = path.relative(repoRoot, schemaPath);
+	const schemaDiskContent = fs.existsSync(schemaPath) ? fs.readFileSync(schemaPath, 'utf8') : null;
+	const schemaAction = schemaDiskContent === null ? 'create' : (schemaDiskContent === schemaContent ? 'unchanged' : 'update');
+	if (!dryRun) writeUnit(schemaPath, schemaContent);
+	result.written.push(schemaRelPath);
+	const schemaActionEntry = { path: schemaRelPath, kind: 'spec', action: schemaAction };
+	if (computeDiff && schemaAction === 'update') schemaActionEntry.diff = unifiedDiff(schemaRelPath, schemaDiskContent, schemaContent);
+	result.actions.push(schemaActionEntry);
+
+	return {
+		...result,
+		postEmitNotes: [
+			'NOT done automatically: route observeContract\'s own receipt sink (defaults to one JSON line per receipt via process.stdout.write) to wherever you want receipt lines collected -- bskel never edits your logging/process-supervisor config. Override it at app startup ("import { setReceiptSink } from \'./observe/observeContract\';") to point it at your own log pipeline, then point `bskel observe import --receipts <path>` at whatever that ends up as.',
+			'If your build compiles TypeScript to a separate output directory (`tsc --outDir dist`), make sure observe/schemas/*.json is copied alongside the compiled observedSchema.js -- tsc only compiles .ts files, it does not copy plain data files into the output tree, and observedSchema.ts discovers its schemas relative to its OWN compiled location at runtime (__dirname). A target app that only ever runs from src/ (ts-node, tsx) needs no extra step here.',
+			`Contract-conformance checking only covers path params always, plus a bounded slice of request/response/error body shape -- and only when this contract was emitted with --openapi-file. See the emitted ${path.relative(repoRoot, schemaPath)}'s own "unsupported" markers for exactly what is skipped for this feature.`,
+			'NOT done automatically: insert observeContract(\'<operationId>\') into whichever existing route\'s own middleware array/argument list you want observed (e.g. `router.get(path, [checkJwt, observeContract(\'op-id\')], handler)`) -- nothing is inserted for you (D-resolver-scope: never guess which route implements which operation).',
+			'error_class is never populated in this provider\'s receipts (always omitted) -- Express middleware runs BEFORE the route handler and is structurally unable to observe a thrown error the way java\'s @Around/python\'s except block can (by the time a handler throws or calls next(err), this middleware\'s own call frame has already returned). See DECISIONS.md D-runtime-conformance-receipts.',
+			'Response-body checking only covers a handler that calls res.json(...) or res.send(<object>) (Express\'s own res.send delegates to res.json for a plain-object body) -- a handler that calls res.send(<string>)/res.end(...) directly, or whose response is produced by Express\'s own default/generic error handler, has its response check silently skipped, never guessed.',
+			'OpenAPI reconciliation for this adapter matches scanned Express route strings EXACTLY against the OpenAPI document\'s own path keys (contracts/openapi.mjs has no ":id" <-> "{id}" translation) -- a real, standards-compliant OpenAPI document (which must use "{id}") will not match a scanned ":id"/":id([0-9]+)" route unless the document\'s own path key happens to already read that way. Unlike python-fastapi, this is not "for free."',
+		],
+	};
+}

package/handles/providers/typescript-express/templates/contractCheck.ts.tmpl

@@ -0,0 +1,136 @@
+// Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+// template and regenerate.
+//
+// D-runtime-conformance-receipts: pure, dependency-free -- the only place a real observed value is
+// ever looked at. `Violation.message` MUST NEVER interpolate the observed value itself, only the
+// JSON Pointer and constraint kind ("required"/"type"/"pattern"/"unsupported") -- a real payload
+// value must never leave this process, structurally, not by convention (see DECISIONS.md
+// D-runtime-conformance-receipts, Decision A).
+//
+// Every check here matches exactly what handles/observe-schema-projection.mjs's own projection
+// produces (shared with java-spring/python-fastapi, nothing TS-specific about the shape) --
+// required-field presence, scalar (string/number/integer/boolean) type, and a pre-compiled regex
+// pattern (compiled once by observedSchema.ts, not here). Nothing deeper: a property this checker
+// cannot evaluate is marked `unsupported` at its own pointer by the projection already, never
+// guessed at here.
+
+export interface ObservedProperty {
+	type: string | null;
+	pattern: RegExp | null;
+}
+
+export interface ObservedObject {
+	required: string[];
+	properties: Record<string, ObservedProperty>;
+	unsupported: string[];
+}
+
+export interface Violation {
+	pointer: string;
+	keyword: 'required' | 'type' | 'pattern' | 'status' | 'unsupported';
+	message: string;
+}
+
+function matchesType(type: string, value: unknown): boolean {
+	switch (type) {
+		case 'string':
+			return typeof value === 'string';
+		case 'boolean':
+			return typeof value === 'boolean';
+		case 'integer':
+			return typeof value === 'number' && Number.isInteger(value);
+		case 'number':
+			return typeof value === 'number';
+		default:
+			return true; // an unrecognized type name is not this checker's job to enforce
+	}
+}
+
+function checkScalar(prop: ObservedProperty, value: unknown, pointer: string): Violation[] {
+	const violations: Violation[] = [];
+	if (prop.type !== null && !matchesType(prop.type, value)) {
+		violations.push({ pointer, keyword: 'type', message: `expected type "${prop.type}"` });
+		return violations;
+	}
+	if (prop.pattern !== null && typeof value === 'string' && !prop.pattern.test(value)) {
+		violations.push({ pointer, keyword: 'pattern', message: 'does not match the required pattern' });
+	}
+	return violations;
+}
+
+/**
+ * Checks `actual` (a request/response/error JSON body) against `schema`, an already-compiled
+ * entry from observedSchema.get(...)'s own request/response/error field. `basePointer` is
+ * prefixed onto every violation's own pointer ("" for the root, "/body" for a wrapped body).
+ */
+export function checkObject(schema: ObservedObject | null, actual: unknown, basePointer = ''): Violation[] {
+	const violations: Violation[] = [];
+	if (schema === null) return violations;
+	for (const pointer of schema.unsupported) {
+		violations.push({ pointer: `${basePointer}${pointer}`, keyword: 'unsupported', message: 'schema at this pointer is deeper than this checker supports for now -- not validated' });
+	}
+	if (actual === null || actual === undefined) {
+		if (schema.required.length > 0 || Object.keys(schema.properties).length > 0) {
+			violations.push({ pointer: basePointer, keyword: 'type', message: 'expected an object, got none' });
+		}
+		return violations;
+	}
+	if (typeof actual !== 'object' || Array.isArray(actual)) {
+		violations.push({ pointer: basePointer, keyword: 'type', message: 'expected an object' });
+		return violations;
+	}
+	const record = actual as Record<string, unknown>;
+	for (const field of schema.required) {
+		if (!(field in record)) {
+			violations.push({ pointer: `${basePointer}/${field}`, keyword: 'required', message: 'missing required field' });
+		}
+	}
+	for (const [field, prop] of Object.entries(schema.properties)) {
+		if (!(field in record)) continue; // required-ness already checked above; an absent optional field is not a violation
+		violations.push(...checkScalar(prop, record[field], `${basePointer}/${field}`));
+	}
+	return violations;
+}
+
+/**
+ * `actual` is Express's own `req.params`-shaped name->value map. Values are coerced to string
+ * before a pattern check (Express's own router always produces string param values for a named
+ * segment; a defensive String() coercion here matches java's/python's own equivalent).
+ */
+export function checkPathParams(schema: ObservedObject | null, actual: Record<string, unknown>): Violation[] {
+	const violations: Violation[] = [];
+	if (schema === null) return violations;
+	for (const pointer of schema.unsupported) {
+		violations.push({ pointer: `/pathParams${pointer}`, keyword: 'unsupported', message: 'schema at this pointer is deeper than this checker supports for now -- not validated' });
+	}
+	for (const field of schema.required) {
+		const value = actual[field];
+		if (value === undefined || value === null) {
+			violations.push({ pointer: `/pathParams/${field}`, keyword: 'required', message: 'missing required path parameter' });
+			continue;
+		}
+		const prop = schema.properties[field];
+		if (prop?.pattern != null && !prop.pattern.test(String(value))) {
+			violations.push({ pointer: `/pathParams/${field}`, keyword: 'pattern', message: 'does not match the required pattern' });
+		}
+	}
+	return violations;
+}
+
+/**
+ * A8: `statusKey` is a literal source-document status key ("200", a range like "4XX", or
+ * "default") -- contracts/emit.mjs's own `sourceResponses` vocabulary
+ * (schemas/feature-contract.schema.json's `^(?:[1-5](?:[0-9]{2}|XX)|default)$` pattern). Matching
+ * a REAL observed status against this key is a bounded, mechanical string comparison, not
+ * JSON-Schema interpretation.
+ */
+export function statusMatches(statusKey: string, actualStatus: number): boolean {
+	if (statusKey === 'default') return true;
+	const actual = String(actualStatus);
+	if (statusKey.length !== 3 || actual.length !== 3) return false;
+	for (let i = 0; i < 3; i++) {
+		const k = statusKey[i];
+		if (k !== 'X' && k !== actual[i]) return false;
+	}
+	return true;
+}

package/handles/providers/typescript-express/templates/observeContract.ts.tmpl

@@ -0,0 +1,146 @@
+// Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+// template and regenerate.
+//
+// D-runtime-conformance-receipts: the opt-in AUTOMATIC half of runtime contract-conformance
+// checking -- exists only for a route a human has chosen to insert observeContract('...') into.
+// Never activates on anything else, and a failure here is ALWAYS logged and swallowed, never
+// allowed to affect the real request/response (best-effort observability, same posture java's
+// ContractObservationAspect / python's observe_contract already establish).
+//
+// Combines java's separate @ObserveContract annotation + ContractObservationAspect interceptor,
+// and mirrors python's single-decorator choice: Express middleware IS this ecosystem's own
+// interception mechanism, so there is no separate "declare a marker" vs. "implement the
+// interceptor" split worth preserving here either.
+//
+// STRUCTURAL DIFFERENCE FROM JAVA/PYTHON, not a deferred gap: Express middleware runs BEFORE the
+// route handler and never receives its return value -- there is no `joinPoint.proceed()`/
+// `await fn(...)` to intercept. Response-body capture instead patches `res.json` on the per-request
+// `res` instance (confirmed against the real express@4.18.2 source: `res.send(<plainObject>)`
+// itself delegates to `this.json(...)`, so this single patch point covers both call styles) and
+// reads the FINAL, real `res.statusCode` inside `res.on('finish', ...)` -- which fires exactly
+// once regardless of whether the handler succeeded, threw, or Express's own default/custom error
+// handling ultimately produced the response. A handler that calls `res.send(<string>)`/
+// `res.end(...)` directly, or whose response is produced by Express's own generic error handler,
+// never touches the patched `res.json` -- the response check is silently SKIPPED for that request,
+// never guessed (same "unsupported, not guessed" discipline as everywhere else in this feature).
+//
+// error_class is NEVER populated (always omitted) -- by the time a handler throws or calls
+// next(err), this middleware's own call frame has already returned; there is no catch-block
+// equivalent available the way java's @Around/python's except block have. See DECISIONS.md
+// D-runtime-conformance-receipts.
+//
+// Path-parameter checking needs no config (Express's own req.params is already keyed by the real
+// route's own :name segments). Request-body checking is AUTOMATIC whenever op.body !== 'false'
+// (req.body is Express's own unambiguous body once body-parsing middleware has run -- no
+// python-style explicit body_param argument needed here).
+//
+// Example:
+//   router.get('/users/:id', [checkJwt, observeContract('users-show')], showUser);
+
+import type { RequestHandler, Request, Response } from 'express';
+import * as contractCheck from './contractCheck';
+import * as observedSchema from './observedSchema';
+import type { ObservedOperation } from './observedSchema';
+import type { Violation } from './contractCheck';
+
+/**
+ * Where a receipt JSON line is delivered -- defaults to stdout (one line per receipt), matching
+ * java's/python's own "a dedicated, independently-routable channel a human points `bskel observe
+ * import` at" property without inventing a logging framework dependency. Override at app startup
+ * (`import { setReceiptSink } from './observe/observeContract'; setReceiptSink((line) => ...);`)
+ * to route it wherever you want -- bskel never chooses your delivery path (D-config-patch's own
+ * boundary).
+ */
+let receiptSink: (line: string) => void = (line) => {
+	process.stdout.write(`${line}\n`);
+};
+
+export function setReceiptSink(sink: (line: string) => void): void {
+	receiptSink = sink;
+}
+
+function checkRequest(op: ObservedOperation, req: Request): Violation[] {
+	const violations = contractCheck.checkPathParams(op.pathParams, req.params as Record<string, unknown>);
+	if (op.body !== 'false' && req.body !== undefined) {
+		violations.push(...contractCheck.checkObject(op.request, req.body, '/body'));
+	}
+	return violations;
+}
+
+function checkResponse(op: ObservedOperation, body: unknown): Violation[] {
+	return contractCheck.checkObject(op.response, body, '/body');
+}
+
+function emitReceipt(op: ObservedOperation, operationId: string, requestViolations: Violation[], responseViolations: Violation[], status: number): void {
+	try {
+		const allViolations = [...requestViolations, ...responseViolations];
+		if (op.statuses) {
+			const matched = op.statuses.some((key) => contractCheck.statusMatches(key, status));
+			if (!matched) {
+				allViolations.push({ pointer: '/status', keyword: 'status', message: `observed status ${status} is not among the documented status keys` });
+			}
+		}
+		const receipt: Record<string, unknown> = {
+			feature_id: op.featureId,
+			feature_uid: op.featureUid,
+			operation_id: operationId,
+			contract_ref: op.contractRef,
+			verb: op.verb,
+			status,
+			recorded_at: new Date().toISOString(),
+			violations: allViolations,
+		};
+		receiptSink(JSON.stringify(receipt));
+	} catch (err) {
+		console.warn(`observeContract: could not emit a receipt for "${operationId}"`, err);
+	}
+}
+
+export function observeContract(operationId: string): RequestHandler {
+	return (req: Request, res: Response, next) => {
+		let op: ObservedOperation | undefined;
+		try {
+			op = observedSchema.get(operationId);
+		} catch {
+			op = undefined;
+		}
+		if (!op) {
+			console.warn(`observeContract: no observed schema loaded for operationId "${operationId}" -- skipping, the request proceeds unaffected`);
+			next();
+			return;
+		}
+		const activeOp = op;
+
+		let requestViolations: Violation[] = [];
+		try {
+			requestViolations = checkRequest(activeOp, req);
+		} catch (err) {
+			console.warn(`observeContract: could not complete the request check for "${operationId}" -- the request proceeds unaffected`, err);
+			requestViolations = [];
+		}
+
+		try {
+			let capturedBody: unknown;
+			let bodyCaptured = false;
+			const originalJson = res.json.bind(res);
+			res.json = ((body?: any): Response => {
+				capturedBody = body;
+				bodyCaptured = true;
+				return originalJson(body);
+			}) as typeof res.json;
+
+			res.on('finish', () => {
+				try {
+					const responseViolations = bodyCaptured ? checkResponse(activeOp, capturedBody) : [];
+					emitReceipt(activeOp, operationId, requestViolations, responseViolations, res.statusCode);
+				} catch (err) {
+					console.warn(`observeContract: could not emit a receipt for "${operationId}" -- the response was already sent unaffected`, err);
+				}
+			});
+		} catch (err) {
+			console.warn(`observeContract: could not attach response observation for "${operationId}" -- the request proceeds unaffected`, err);
+		}
+
+		next();
+	};
+}

package/handles/providers/typescript-express/templates/observedSchema.ts.tmpl

@@ -0,0 +1,116 @@
+// Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+// template and regenerate.
+//
+// D-runtime-conformance-receipts: loads every `<feature-id>.observed-schema.json` file under this
+// package's own `schemas/` directory (one per feature `bskel observe emit --module ...` has been
+// run against) at MODULE LOAD time and merges them into one flat map keyed by operationId -- a
+// deployed app has no access to specs/ at runtime, same reasoning java's ResourceResolver /
+// python's observed_schema.py already state, just a plain data file here instead of a baked string
+// constant. Node's own CommonJS module cache gives this the same "loaded once, shared everywhere"
+// property java's @Component / python's module-level `_OPERATIONS` get.
+//
+// `schemas/` is a plain directory discovered via `fs.readdirSync`, not a bundler-aware asset
+// pipeline -- this ecosystem's own target apps only ever run compiled output sitting next to this
+// same compiled file (a plain `tsc` deployment), so `__dirname` (CommonJS -- this generated tree's
+// own tsconfig.json pins `module: "commonjs"`) is a real, valid runtime anchor; `import.meta.url`
+// is deliberately NOT used here -- it is not legal syntax under CommonJS module output and would
+// fail `tsc` outright.
+//
+// Every `pattern` keyword is compiled exactly ONCE here, not per-request -- an invalid regex
+// string at this point marks that one field unsupported rather than throwing at module load.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ObservedObject, ObservedProperty } from './contractCheck';
+
+export interface ObservedOperation {
+	featureId: string | null;
+	featureUid: string | null;
+	contractRef: string | null;
+	verb: string | null;
+	path: string | null;
+	pathParams: ObservedObject;
+	body: string;
+	request: ObservedObject | null;
+	response: ObservedObject;
+	error: ObservedObject;
+	statuses: string[] | null;
+}
+
+const SCHEMAS_DIR = path.join(__dirname, 'schemas');
+
+function compileProperty(prop: any): ObservedProperty | null {
+	const patternText = prop?.pattern;
+	if (patternText === undefined) return { type: prop?.type ?? null, pattern: null };
+	try {
+		return { type: prop?.type ?? null, pattern: new RegExp(patternText) };
+	} catch {
+		return null; // caller treats this as unsupported
+	}
+}
+
+function compileObject(node: any): ObservedObject {
+	if (!node) return { required: [], properties: {}, unsupported: [] };
+	const unsupported: string[] = [...(node.unsupported ?? [])];
+	const properties: Record<string, ObservedProperty> = {};
+	for (const [name, prop] of Object.entries<any>(node.properties ?? {})) {
+		const compiled = compileProperty(prop);
+		if (compiled === null) {
+			unsupported.push(`/${name}`);
+			continue;
+		}
+		properties[name] = compiled;
+	}
+	return { required: [...(node.required ?? [])], properties, unsupported };
+}
+
+function loadOne(filePath: string): Record<string, ObservedOperation> {
+	let raw: any;
+	try {
+		raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+	} catch (err) {
+		console.warn(`observedSchema: could not read/parse ${filePath} -- skipping this feature's observed schema`, err);
+		return {};
+	}
+	const featureId = raw.feature_id ?? null;
+	const featureUid = raw.feature_uid ?? null;
+	const contractRef = raw.contract_ref ?? null;
+	const operations: Record<string, ObservedOperation> = {};
+	for (const [operationId, op] of Object.entries<any>(raw.operations ?? {})) {
+		const body = op.body ?? 'unknown';
+		operations[operationId] = {
+			featureId, featureUid, contractRef,
+			verb: op.verb ?? null,
+			path: op.path ?? null,
+			pathParams: compileObject(op.pathParams),
+			body,
+			request: body === 'false' ? null : compileObject(op.request),
+			response: compileObject(op.response),
+			error: compileObject(op.error),
+			statuses: op.statuses ?? null,
+		};
+	}
+	return operations;
+}
+
+function loadAll(): Map<string, ObservedOperation> {
+	const merged = new Map<string, ObservedOperation>();
+	if (!fs.existsSync(SCHEMAS_DIR)) return merged;
+	const files = fs.readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.observed-schema.json')).sort();
+	for (const file of files) {
+		for (const [operationId, op] of Object.entries(loadOne(path.join(SCHEMAS_DIR, file)))) {
+			if (merged.has(operationId)) {
+				console.warn(`observedSchema: operationId "${operationId}" is declared by more than one *.observed-schema.json on disk -- the last one loaded wins`);
+			}
+			merged.set(operationId, op);
+		}
+	}
+	return merged;
+}
+
+const OPERATIONS = loadAll();
+
+/** undefined when no loaded *.observed-schema.json declares this operationId. */
+export function get(operationId: string): ObservedOperation | undefined {
+	return OPERATIONS.get(operationId);
+}

package/lib/attest.mjs

@@ -0,0 +1,40 @@
+// D-gate-attestation-signing: cryptographic primitives for signed gate attestations -- Node's
+// built-in `crypto` module only (Ed25519, available since Node 12, well within this project's
+// >=18 floor), zero new dependencies. Deliberately minimal: this module knows how to canonicalize,
+// sign, and verify a JSON payload -- it has no opinion about WHERE a key lives (bin/bskel.mjs's
+// `--key`/`--pubkey` flags are the only interface, per the user's own explicit choice to reject a
+// new home-directory key-storage convention for this slice -- see DECISIONS.md).
+import { generateKeyPairSync, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { sortKeysDeep } from './gates.mjs';
+
+export function generateKeypair() {
+	const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+	return {
+		publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }),
+		privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }),
+	};
+}
+
+// Deep-sorted, whitespace-free JSON -- the ONLY thing that's ever actually signed/verified.
+// Reusing lib/gates.mjs's own sortKeysDeep() (already proven correct via every gate's `inputs`
+// field) rather than a second, possibly-subtly-different implementation.
+export function canonicalize(value) {
+	return JSON.stringify(sortKeysDeep(value));
+}
+
+export function signPayload(payload, privateKeyPem) {
+	const canonical = canonicalize(payload);
+	return cryptoSign(null, Buffer.from(canonical), privateKeyPem).toString('base64');
+}
+
+// Returns a plain boolean, never throws on a malformed signature/key -- a corrupt or wrong-format
+// signature is exactly as "not valid" as a mismatched one, not a distinct error class a caller
+// needs to handle differently.
+export function verifyPayload(payload, signatureB64, publicKeyPem) {
+	const canonical = canonicalize(payload);
+	try {
+		return cryptoVerify(null, Buffer.from(canonical), publicKeyPem, Buffer.from(signatureB64, 'base64'));
+	} catch {
+		return false;
+	}
+}