backend-skeleton 1.0.0-beta.9 → 1.1.0

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/handleEntities.ts.tmpl

@@ -0,0 +1,89 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// G5 follow-up (D-typescript-express-registry-parity): mirrors java-spring's HandleRegistry.java.tmpl/
+// HandleSnapshot.java.tmpl and python-fastapi's tables.py.tmpl -- same table names, columns, and
+// unique(resource_type, resource_uid, pointer) constraint, so all three providers' generated
+// schemas agree byte-for-byte at the DDL level (see the emitted migration.sql). NOT the same
+// concept as this package's own registry.ts -- that file is an in-process type->resolver
+// dispatch map; HandleRegistry here is a real database table. The names collide only because
+// Java's own naming does; treat them as unrelated.
+//
+// `payload` is a native `jsonb` column -- TypeORM (de)serializes at the DB boundary automatically,
+// the same no-manual-round-trip safety python-fastapi's own tables.py already has (Java's original
+// `payload` column was a manually (de)serialized String, the exact bug class this structurally
+// cannot reproduce).
+//
+// Requires `experimentalDecorators`/`emitDecoratorMetadata` in the target app's own tsconfig --
+// already required by this provider's own real oracle (any TypeORM app already needs both for its
+// OWN `@Entity()` classes; this is not a new requirement this file introduces). Unlike codec.ts
+// (deliberately decorator-free so it can run standalone via `node --experimental-strip-types`),
+// this file is inherently coupled to a real TypeORM build the way every entity in this ecosystem
+// already is.
+import { Entity, PrimaryColumn, Column, CreateDateColumn, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity({ name: 'sbf_handle' })
+export class HandleRegistry {
+  @PrimaryColumn('uuid')
+  handleUid!: string;
+
+  // 'r' (resource), 'f' (field), or 'o' (operation instance -- reserved, unused).
+  @Column('text')
+  kind!: string;
+
+  @Column('text')
+  resourceType!: string;
+
+  @Column('uuid')
+  resourceUid!: string;
+
+  // RFC 6901 JSON Pointer, null for kind='r'.
+  @Column('text', { nullable: true })
+  pointer!: string | null;
+
+  @Column('uuid')
+  featureUid!: string;
+
+  @Column('text', { nullable: true })
+  operationId!: string | null;
+
+  @Column('text')
+  contractRef!: string;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  createdAt!: Date;
+
+  @Column('timestamptz', { nullable: true })
+  revokedAt!: Date | null;
+
+  @Column('text', { nullable: true })
+  revokedReason!: string | null;
+}
+
+@Entity({ name: 'sbf_handle_snapshot' })
+export class HandleSnapshot {
+  @PrimaryGeneratedColumn({ type: 'bigint' })
+  snapshotId!: string;
+
+  @Column('uuid')
+  handleUid!: string;
+
+  // 'request', 'response', or 'error' -- what kind of payload this envelope holds.
+  @Column('text')
+  envelopeDir!: string;
+
+  @Column('text')
+  operationId!: string;
+
+  // Hash of the feature contract this snapshot was recorded against. `recover` compares this to
+  // the CURRENT contract's hash -- a mismatch means the contract has since changed shape, and
+  // `recover` must say so explicitly (a schemaDrift marker) rather than silently returning a
+  // payload the current contract no longer describes.
+  @Column('text')
+  contractHash!: string;
+
+  @Column('jsonb')
+  payload!: unknown;
+
+  @CreateDateColumn({ type: 'timestamptz' })
+  recordedAt!: Date;
+}

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

@@ -0,0 +1,81 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// G5 follow-up (D-typescript-express-registry-parity): mirrors Java's HandleService.java.tmpl /
+// python-fastapi's handle_service.py.tmpl -- the explicit API that makes a real GET
+// /handles/:handle/recover reachable. Deliberately never auto-invoked by anything generated
+// elsewhere and never wired into any EXISTING business logic file -- call these functions
+// explicitly from your own service code at the point a resource is actually created/updated, or
+// wrap an existing service function with `recordSnapshot(...)` (see recordSnapshotWrapper.ts) to
+// have it called for you.
+//
+// Named `registerHandle`/`revokeHandle` (not `register`/`revoke`) -- `registry.ts`'s own
+// `register()` is a completely unrelated function (in-process resolver-type dispatch, not a
+// database write); the names collide only because both files use the word "register" for
+// different things. Plain exported functions taking `dataSource` explicitly, not a class with
+// injected dependencies -- matches this provider's own established convention (every resolver
+// already imports its own app-wide DataSource singleton directly; there is no DI container here
+// the way Spring's @Service beans have, or even FastAPI's own Depends()).
+import type { DataSource } from 'typeorm';
+import { HandleRegistry, HandleSnapshot } from './handleEntities';
+import { deriveHandleUid, encodeHandle } from './codec';
+
+export interface RegisterHandleArgs {
+  kind: string;
+  type: string;
+  resourceUid: string;
+  pointer: string | null;
+  featureUid: string;
+  operationId: string | null;
+  contractRef: string;
+}
+
+// Derives handleUid and UPSERTS the registry row -- the schema's own
+// unique(resource_type, resource_uid, pointer) constraint means the SAME (kind, type,
+// resource_uid, pointer) tuple always derives the SAME handleUid, so re-registering it is
+// expected, not an error: an existing row has its featureUid/operationId/contractRef refreshed,
+// but revokedAt/revokedReason are NEVER touched here -- re-registering a revoked handle must
+// never silently un-revoke it. Returns the encoded handle token.
+export async function registerHandle(dataSource: DataSource, args: RegisterHandleArgs): Promise<string> {
+  const { kind, type, resourceUid, pointer, featureUid, operationId, contractRef } = args;
+  const token = encodeHandle(kind, type, resourceUid, pointer);
+  const handleUid = deriveHandleUid(kind, type, resourceUid, pointer);
+  const repo = dataSource.getRepository(HandleRegistry);
+  const existing = await repo.findOne({ where: { handleUid } });
+  if (existing == null) {
+    await repo.save(repo.create({ handleUid, kind, resourceType: type, resourceUid, pointer, featureUid, operationId, contractRef, revokedAt: null, revokedReason: null }));
+  } else {
+    existing.featureUid = featureUid;
+    existing.operationId = operationId;
+    existing.contractRef = contractRef;
+    await repo.save(existing);
+  }
+  return token;
+}
+
+// Records one envelope for an already-registered handle. `payload` is a plain
+// object/array/scalar (already JSON-shaped), stored directly into the native jsonb column -- no
+// manual JSON.stringify/JSON.parse round-trip exists here for `recover` to get wrong later.
+export async function recordSnapshot(dataSource: DataSource, handleUid: string, envelopeDir: string, operationId: string, contractHash: string, payload: unknown): Promise<void> {
+  const repo = dataSource.getRepository(HandleSnapshot);
+  await repo.save(repo.create({ handleUid, envelopeDir, operationId, contractHash, payload }));
+}
+
+export async function revokeHandle(dataSource: DataSource, handleUid: string, reason: string): Promise<void> {
+  const repo = dataSource.getRepository(HandleRegistry);
+  const existing = await repo.findOne({ where: { handleUid } });
+  if (existing != null) {
+    existing.revokedAt = new Date();
+    existing.revokedReason = reason;
+    await repo.save(existing);
+  }
+}
+
+// Retention is EXPOSED, not auto-scheduled -- nothing generated here calls this automatically.
+// Deciding how long snapshots should live, and whether a background job is even appropriate for
+// this application, is left to a human -- the same boundary this provider's own migration.sql
+// already draws around never applying itself.
+export async function pruneSnapshotsOlderThan(dataSource: DataSource, cutoff: Date): Promise<number> {
+  const repo = dataSource.getRepository(HandleSnapshot);
+  const result = await repo.createQueryBuilder().delete().where('recorded_at < :cutoff', { cutoff }).execute();
+  return result.affected ?? 0;
+}

package/handles/providers/typescript-express/templates/migration.sql.tmpl

@@ -0,0 +1,36 @@
+-- Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+-- NOT applied automatically -- review it and apply yourself (e.g. via `psql` or your own
+-- TypeORM migration, wrapped in a `queryRunner.query(...)` migration file if you use one). See
+-- D-config-patch / D-migration-scope in DECISIONS.md for why backend-skeleton never applies
+-- schema changes on its own. Same table names/columns as the java-spring/python-fastapi
+-- providers' own migration.sql.tmpl, so all three providers' generated schemas agree at the DDL
+-- level.
+
+create table if not exists sbf_handle (
+	handle_uid uuid primary key,
+	kind text not null check (kind in ('r', 'f', 'o')),
+	resource_type text not null,
+	resource_uid uuid not null,
+	pointer text,
+	feature_uid uuid not null,
+	operation_id text,
+	contract_ref text not null,
+	created_at timestamptz not null default now(),
+	revoked_at timestamptz,
+	revoked_reason text,
+	unique (resource_type, resource_uid, pointer)
+);
+
+create index if not exists ix_sbf_handle_resource on sbf_handle (resource_type, resource_uid);
+
+create table if not exists sbf_handle_snapshot (
+	snapshot_id bigserial primary key,
+	handle_uid uuid not null references sbf_handle (handle_uid),
+	envelope_dir text not null check (envelope_dir in ('request', 'response', 'error')),
+	operation_id text not null,
+	contract_hash text not null,
+	payload jsonb not null,
+	recorded_at timestamptz not null default now()
+);
+
+create index if not exists ix_sbf_handle_snapshot_handle_uid on sbf_handle_snapshot (handle_uid, recorded_at desc);

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);
+}