backend-skeleton 1.0.0-beta.9 → 1.1.0

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

@@ -0,0 +1,123 @@
+// Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
+//
+// D-typescript-express-registry-parity: the opt-in AUTOMATIC half of the handle lifecycle --
+// apply `recordSnapshot(...)` to wrap an EXISTING service function (never generated onto one --
+// a human decides which functions are worth handle-tracking) to have it automatically register
+// the resource-level handle and record the request/response/error envelope around every call.
+//
+// Java splits this into a marker annotation (@RecordHandleSnapshot) + a Spring AOP interceptor
+// (HandleAspect) because Java has no other way to intercept a method call. Python collapses both
+// into one decorator, because Python decorators natively ARE that ecosystem's interception
+// mechanism. TypeScript has NEITHER available here: TS decorators are an experimental,
+// `experimentalDecorators`-gated feature that targets class methods, not the standalone async
+// functions this provider's own resolvers/routes are written as -- and this provider's own
+// codec.ts already establishes "zero non-erasable TypeScript syntax (no decorators...)" as a
+// real, load-bearing constraint. The equivalent here is a HIGHER-ORDER FUNCTION: one mechanism,
+// same "no marker/interceptor split" property Python's decorator has, without decorator syntax.
+//
+// Only an async wrapper exists (no sync variant) -- unlike Python, where a decorator can wrap
+// either a sync or async function and must detect which at decoration time, every Express
+// handler and TypeORM repository call in this ecosystem is already async by convention, so
+// there's no second code path to maintain.
+//
+// `resourceUidArg` is an argument INDEX (not a parameter NAME) -- TypeScript/JavaScript has no
+// runtime reflection equivalent to Python's `inspect.signature(fn).bind(...)`, so this cannot
+// resolve a named parameter the way the Python port does; pass the zero-based position of the
+// resource-uid argument in the wrapped function's own parameter list. `redact` is an explicit
+// array of JSON Pointers, never a guessed heuristic. A failure recording a snapshot is ALWAYS
+// logged and swallowed, never allowed to fail the real business call it wraps -- snapshot
+// recording is best-effort observability, not a new way for an unrelated call to start failing.
+//
+// Requires nothing extra installed (unlike Java's spring-boot-starter-aop) -- a plain function
+// needs no framework support -- but still requires a human to apply it to their own code;
+// codegen never touches an existing business logic file.
+//
+// Example:
+//   export const updateOrganization = recordSnapshot(
+//     { resourceType: 'Organization', operationId: 'updateOrganization', resourceUidArg: 0, redact: ['/internalNote'] },
+//     async (organizationId: string, req: UpdateOrganizationRequest): Promise<OrganizationResponse> => { ... },
+//   );
+import type { DataSource } from 'typeorm';
+import { registerHandle, recordSnapshot as persistSnapshot } from './handleService';
+import { deriveHandleUid } from './codec';
+import { resolverFor } from './registry';
+
+export interface RecordSnapshotOptions {
+  resourceType: string;
+  operationId: string;
+  resourceUidArg: number;
+  redact?: string[];
+}
+
+function redactInPlace(obj: unknown, pointer: string): void {
+  if (!pointer.startsWith('/')) return;
+  const parts = pointer.slice(1).split('/').map((p) => p.replace(/~1/g, '/').replace(/~0/g, '~'));
+  let current: unknown = obj;
+  for (const part of parts.slice(0, -1)) {
+    if (current == null) return;
+    current = Array.isArray(current) ? current[Number(part)] : (current as Record<string, unknown>)[part];
+  }
+  const leaf = parts[parts.length - 1];
+  if (Array.isArray(current)) {
+    const idx = Number(leaf);
+    if (!Number.isNaN(idx) && idx < current.length) current[idx] = '***REDACTED***';
+  } else if (current != null && typeof current === 'object') {
+    if (leaf in (current as Record<string, unknown>)) (current as Record<string, unknown>)[leaf] = '***REDACTED***';
+  }
+}
+
+function safely(action: () => Promise<void>, handleUid: string, envelopeDir: string): void {
+  action().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.warn(`recordSnapshot: could not record ${envelopeDir} snapshot for handle ${handleUid} -- the wrapped call proceeds unaffected`, err);
+  });
+}
+
+export function recordSnapshot<Args extends unknown[], R>(
+  options: RecordSnapshotOptions,
+  dataSource: DataSource,
+  fn: (...args: Args) => Promise<R>,
+): (...args: Args) => Promise<R> {
+  const { resourceType, operationId, resourceUidArg, redact = [] } = options;
+  return async (...args: Args): Promise<R> => {
+    const resolver = resolverFor(resourceType);
+    if (resolver == null) {
+      // eslint-disable-next-line no-console
+      console.warn(`recordSnapshot: no resolver registered for resourceType "${resourceType}" -- skipping snapshot recording, the wrapped call proceeds unaffected`);
+      return fn(...args);
+    }
+    const resourceUid = args[resourceUidArg];
+    if (typeof resourceUid !== 'string') {
+      // eslint-disable-next-line no-console
+      console.warn(`recordSnapshot: resourceUidArg ${resourceUidArg} on a call to a wrapped "${resourceType}" function did not resolve to a string argument -- skipping snapshot recording, the wrapped call proceeds unaffected`);
+      return fn(...args);
+    }
+    const handleUid = deriveHandleUid('r', resourceType, resourceUid, null);
+
+    const record = (envelopeDir: string, payload: unknown) => {
+      if (payload != null && typeof payload === 'object') {
+        for (const pointer of redact) redactInPlace(payload, pointer);
+      }
+      safely(async () => {
+        await registerHandle(dataSource, { kind: 'r', type: resourceType, resourceUid, pointer: null, featureUid: resolver.featureUid, operationId, contractRef: resolver.contractRef });
+        await persistSnapshot(dataSource, handleUid, envelopeDir, operationId, resolver.contractRef, payload);
+      }, handleUid, envelopeDir);
+    };
+
+    // The remaining arguments once resourceUidArg is excluded -- the sole survivor UNWRAPPED (the
+    // common case: one DTO), matching Java's/Python's own request-payload projection exactly, so
+    // a `redact` pointer written against the DTO's own fields resolves correctly.
+    const rest = args.filter((_, i) => i !== resourceUidArg);
+    record('request', rest.length === 1 ? rest[0] : rest);
+
+    let result: R;
+    try {
+      result = await fn(...args);
+    } catch (err) {
+      record('error', { message: err instanceof Error ? err.message : String(err) });
+      throw err;
+    }
+    record('response', result);
+    return result;
+  };
+}

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

@@ -1,20 +1,29 @@
 // Generated by backend-skeleton. Do not hand-edit -- change the source template and regenerate.
 //
 // In-process registry mapping a handle `type` string to its resolver instance -- deliberately NOT
-// a database table. This 1st-slice scope carries no recover()/snapshot lifecycle equivalent (no
-// sbf_handle/sbf_handle_snapshot table) -- mirrors java-spring/python-fastapi's own pre-O4/
-// pre-follow-up state, not a gap specific to this provider. See D-typescript-express-provider in
-// DECISIONS.md.
+// a database table (that's HandleRegistry in handleEntities.ts, an unrelated concept that only
+// shares the word "registry" -- see that file's own header). See D-typescript-express-provider /
+// D-typescript-express-registry-parity in DECISIONS.md.
 
 // Unlike the Python provider's ResourceResolver (which threads a per-request SQLAlchemy `session`
-// through every method, matching FastAPI's own dependency-injection convention), this interface
-// takes NO dataSource/session parameter at all -- TypeORM's `DataSource` is an app-wide singleton
-// instantiated once at startup (`export const AppDataSource = new DataSource(...)`), not a
-// per-request-injected object the way SQLAlchemy's `Session` is. Each generated resolver imports
-// its own DataSource reference directly (see resolver.ts.tmpl) -- a genuine simplification from
-// this ecosystem's own real pattern, not an arbitrary deviation from the Python provider's shape.
+// argument through every METHOD CALL, matching FastAPI's own dependency-injection convention),
+// none of fetch()/checkAccess()/patchField()/toPublic() below take a dataSource/session parameter
+// -- TypeORM's `DataSource` is an app-wide singleton instantiated once at startup (`export const
+// AppDataSource = new DataSource(...)`), not a per-request-injected object the way SQLAlchemy's
+// `Session` is. Each generated resolver still imports its own DataSource reference directly (see
+// resolver.ts.tmpl) and exposes it as the `dataSource` FIELD below (not a method parameter) --
+// D-typescript-express-registry-parity's own infrastructure (recordSnapshotWrapper.ts, router.ts's
+// recover()/enforcement logic) reads it from there rather than needing a separate reference of
+// its own. `featureUid`/`contractRef` are the other two live-derived values
+// D-resolver-policy-split exists for (see <Type>Policy.ts.tmpl). All three fields are read by
+// that infrastructure only, never by fetch()/checkAccess()/patchField()/toPublic().
+import type { DataSource } from 'typeorm';
+
 export interface ResourceResolver {
   type: string;
+  featureUid: string;
+  contractRef: string;
+  dataSource: DataSource;
   fetch(resourceUid: string): Promise<unknown>;
   checkAccess(obj: unknown): void;
   patchField(obj: unknown, pointer: string, value: unknown): void;

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

@@ -24,9 +24,22 @@
 import { {{MODEL}} } from '{{MODEL_IMPORT_PATH}}';
 import { {{DATA_SOURCE_NAME}} } from '{{DATA_SOURCE_IMPORT_PATH}}';
 import { register, HandleAccessDeniedError, HandleNotImplementedError, type ResourceResolver } from '../registry';
+import { {{RESOURCE_TYPE}}Policy } from './{{RESOURCE_TYPE_CAMEL}}Policy';
 
 const {{RESOURCE_TYPE}}Resolver: ResourceResolver = {
+  ...{{RESOURCE_TYPE}}Policy,
+  // Redundant with the spread above (Policy already carries `type`) -- restated explicitly so
+  // this file's own orphan-scan (emit.mjs's resourceTypeOf(), a content-read, not a filename
+  // guess) can still find a real `type: 'X'` field without needing to open the sibling Policy
+  // file too. A literal, not derived from anything -- if this and the Policy value ever
+  // disagreed, the object-literal spread order means this line always wins at runtime, matching
+  // what the orphan scan would read.
   type: '{{RESOURCE_TYPE}}',
+  // D-typescript-express-registry-parity: exposed here, not in the policy file -- this is an
+  // OBJECT REFERENCE (the same app-wide DataSource singleton fetch() already imports below), not
+  // a plain regenerable string value the way contractRef/featureUid are. Read by recordSnapshotWrapper.ts
+  // and router.ts's recover()/enforcement logic so they never need their own separate DataSource.
+  dataSource: {{DATA_SOURCE_NAME}},
 
   async fetch(resourceUid: string): Promise<unknown> {
     return {{DATA_SOURCE_NAME}}.getRepository({{MODEL}}).findOne({ where: { {{ID_FIELD}}: resourceUid } });

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

@@ -0,0 +1,20 @@
+// Generated by backend-skeleton (bskel handles emit) for feature {{FEATURE_ID}}.
+//
+// D-typescript-express-registry-parity (mirrors java-spring's ResourceResolverPolicyStub.java.tmpl
+// / D-resolver-policy-split): machine-owned companion to {{RESOURCE_TYPE}}Resolver -- every value
+// here is derived directly from the current contract/scan and is safe to regenerate on every
+// `bskel handles emit` run, even when the sibling resolver file has diverged (e.g. a hand-finished
+// patchField()) and is refusing to regenerate. This is a SEPARATE file, not a section of
+// resolver.ts, so a hand-edit to checkAccess()/patchField() there never blocks a live-derived
+// value here (contractRef/featureUid) from updating -- both used to live in one file for this
+// provider's own 1st slice, and classifyFile()'s conflict detection is file-level.
+//
+// Nothing here is ever meant to be hand-edited -- to change one of these values, change the
+// SOURCE it was derived from (the feature contract, etc.) and re-run `bskel handles emit`. A
+// hand-edit here will be silently overwritten on the next run, by design (see the "provably
+// untouched -> safe to regenerate" path in lib/handles-manifest.mjs's classifyFile()).
+export const {{RESOURCE_TYPE}}Policy = {
+  type: '{{RESOURCE_TYPE}}',
+  contractRef: '{{CONTRACT_REF}}',
+  featureUid: '{{FEATURE_UID}}',
+} as const;

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

@@ -9,8 +9,38 @@
 // against still pins this version) does NOT auto-catch a rejected Promise inside an async route
 // handler the way Express 5 does, and that can't be assumed of an arbitrary target app either way.
 import { Router, type Request, type Response } from 'express';
-import { decodeHandle, resolveJsonPointer } from './codec';
-import { resolverFor, HandleAccessDeniedError, HandleNotImplementedError } from './registry';
+import { decodeHandle, resolveJsonPointer, deriveHandleUid, type DecodedHandle } from './codec';
+import { resolverFor, HandleAccessDeniedError, HandleNotImplementedError, type ResourceResolver } from './registry';
+import { HandleRegistry, HandleSnapshot } from './handleEntities';
+
+// O3 (D-handle-registry-enforcement, part 2 of 2), D-typescript-express-registry-parity: opt-in,
+// defaults false -- baked in at `bskel handles emit --enforce-registry on` time, matching every
+// other per-target-repo codegen constant this project bakes in (e.g. featureUid/contractRef on
+// each resolver). `registerHandle()` is only ever called by generated code wrapped with
+// recordSnapshot(...) (an app that opted in) or a target app's own hand-written calls -- an app
+// that mints handles through neither path gets fully working fetch()/patch() with zero registry
+// involvement today; flipping this on unconditionally would 404 every one of their existing
+// handles. Stays a deliberate, informed choice a target app's own maintainer makes.
+const ENFORCE_REGISTRY = {{ENFORCE_REGISTRY}};
+
+export class HandleNotRegisteredError extends Error {}
+
+// D-handle-registry-enforcement's own bootstrapping-trap fix, ported here from day one (not
+// rediscovered): always derives and looks up the PARENT RESOURCE's own row (kind='r',
+// pointer=null), regardless of the requested handle's own kind/pointer -- `resourceType` is still
+// exactly cross-checked (the real D-security-9 protection: an attacker-controlled `type` can't
+// claim a different, more sensitive resource's registration by UUID coincidence), but kind/pointer
+// are not, since every real registration in this system is resource-level. Structurally correct,
+// not a workaround: revocation is inherently a resource-level concept, matching how fetch()'s own
+// kind=f path already fetches the WHOLE resource and narrows client-side with a pointer.
+async function requireRegisteredOrThrow(resolver: ResourceResolver, decoded: DecodedHandle): Promise<HandleRegistry> {
+  const resourceHandleUid = deriveHandleUid('r', decoded.type, decoded.uuid, null);
+  const registry = await resolver.dataSource.getRepository(HandleRegistry).findOne({ where: { handleUid: resourceHandleUid } });
+  if (registry == null || registry.resourceType !== decoded.type || registry.revokedAt != null) {
+    throw new HandleNotRegisteredError('no active registration for this handle');
+  }
+  return registry;
+}
 
 export const router = Router();
 
@@ -38,6 +68,9 @@ router.get('/handles/:handle', async (req: Request, res: Response) => {
   }
 
   try {
+    if (ENFORCE_REGISTRY) {
+      await requireRegisteredOrThrow(resolver, decoded);
+    }
     const obj = await resolver.fetch(decoded.uuid);
     if (obj == null) {
       res.status(404).json({ detail: 'resource not found' });
@@ -65,6 +98,10 @@ router.get('/handles/:handle', async (req: Request, res: Response) => {
       res.status(403).json({ detail: exc.message });
       return;
     }
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
     throw exc;
   }
 });
@@ -100,6 +137,9 @@ router.patch('/handles/:handle', async (req: Request, res: Response) => {
   }
 
   try {
+    if (ENFORCE_REGISTRY) {
+      await requireRegisteredOrThrow(resolver, decoded);
+    }
     const obj = await resolver.fetch(decoded.uuid);
     if (obj == null) {
       res.status(404).json({ detail: 'resource not found' });
@@ -117,6 +157,77 @@ router.patch('/handles/:handle', async (req: Request, res: Response) => {
       res.status(501).json({ detail: exc.message });
       return;
     }
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
+    throw exc;
+  }
+});
+
+// D-handle-lifecycle (O4), D-typescript-express-registry-parity: recover() structurally REQUIRES
+// a registry row to find a snapshot's own primary key -- there is no "unenforced" mode for it,
+// unlike fetch()/patch() above. Always calls the same shared cross-check those two now optionally
+// call, so the two paths can never silently drift apart. Unlike fetch()/patch(), this does NOT
+// call resolver.fetch() first -- recovering history of a since-deleted resource is legitimate, so
+// this never requires the live resource to still exist.
+router.get('/handles/:handle/recover', async (req: Request, res: Response) => {
+  if (typeof req.params.handle !== 'string') {
+    res.status(400).json({ detail: 'malformed handle path segment' });
+    return;
+  }
+  let decoded;
+  try {
+    decoded = decodeHandle(req.params.handle);
+  } catch (exc) {
+    res.status(400).json({ detail: (exc as Error).message });
+    return;
+  }
+
+  const resolver = resolverFor(decoded.type);
+  if (!resolver) {
+    res.status(404).json({ detail: `no resolver registered for handle type "${decoded.type}"` });
+    return;
+  }
+
+  let registry: HandleRegistry;
+  try {
+    registry = await requireRegisteredOrThrow(resolver, decoded);
+  } catch (exc) {
+    if (exc instanceof HandleNotRegisteredError) {
+      res.status(404).json({ detail: exc.message });
+      return;
+    }
     throw exc;
   }
+
+  const atParam = typeof req.query.at === 'string' ? req.query.at : null;
+  const at = atParam != null ? new Date(atParam) : null;
+  if (at != null && Number.isNaN(at.getTime())) {
+    res.status(400).json({ detail: `"at" query parameter is not a valid date: "${atParam}"` });
+    return;
+  }
+
+  const qb = resolver.dataSource.getRepository(HandleSnapshot)
+    .createQueryBuilder('snapshot')
+    .where('snapshot.handle_uid = :handleUid', { handleUid: registry.handleUid })
+    .orderBy('snapshot.recorded_at', 'DESC');
+  if (at != null) qb.andWhere('snapshot.recorded_at <= :at', { at });
+  const snapshot = await qb.getOne();
+
+  if (snapshot == null) {
+    res.status(404).json({ detail: `no snapshot recorded for this handle${at != null ? ` at or before ${at.toISOString()}` : ''}` });
+    return;
+  }
+
+  res.status(200).json({
+    handle: req.params.handle,
+    recordedAt: snapshot.recordedAt,
+    operationId: snapshot.operationId,
+    // snapshot.payload is already a native object/array/scalar (a real jsonb column) -- no
+    // manual re-parse step exists here for the double-encoding bug Java once had to be possible
+    // in the first place.
+    payload: snapshot.payload,
+    schemaDrift: registry.contractRef !== snapshot.contractHash,
+  });
 });

package/handles/providers/typescript-express.mjs

@@ -9,10 +9,13 @@ export const provider = {
 	id: 'typescript-express',
 	title: 'TypeScript / Express / TypeORM',
 	requiresCapabilities: ['resource.fetch'],
-	// No migration.sql -- this 1st-slice provider generates no schema-owning artifact (no
-	// recover(), no sbf_handle table), matching java-spring/python-fastapi's own pre-O4/
-	// pre-follow-up state, not a gap specific to this provider.
-	outputs: { spec: [] },
+	// D-typescript-express-registry-parity: migration.sql is manifest-tracked now (like every
+	// other provider's, per D-write-safety-phase0), so this declaration is NOT for idempotence
+	// exclusion -- it's lib/verify.mjs's S6 safety net (a `handles ran` check that fires even with
+	// no manifest entry at all, e.g. a `gate force`d handles gate). See java-spring.mjs's own
+	// identical comment for the full reasoning; checkArtifacts() dedupes against the manifest-
+	// based check by path, so this never produces a duplicate once a real manifest entry exists.
+	outputs: { spec: ['handles/migration.sql'] },
 	plan,
 	emit(args) {
 		return emitTypeScriptExpress(args);

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

package/lib/cli.mjs

@@ -85,10 +85,29 @@ export const COMMANDS = {
 	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
 	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
 	'gate export': {
-		usage: 'bskel gate export --feature <id> [--out <path>] [--json]',
+		usage: 'bskel gate export --feature <id> [--out <path>] [--sign --key <privateKeyPath>] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			out: { type: 'string', default: null },
+			sign: { type: 'boolean', default: false },
+			key: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-gate-attestation-signing.
+	'attest keygen': {
+		usage: 'bskel attest keygen --out <dir> [--force] [--json]',
+		options: {
+			out: { type: 'string', default: null, required: true },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'attest verify': {
+		usage: 'bskel attest verify --file <path> --pubkey <path> [--json]',
+		options: {
+			file: { type: 'string', default: null, required: true },
+			pubkey: { type: 'string', default: null, required: true },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -129,6 +148,30 @@ export const COMMANDS = {
 		},
 		allowPositionals: true,
 	},
+	'scan cross-feature-check': {
+		usage: 'bskel scan cross-feature-check --feature <id> [--db [--database-url-env <NAME>] [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-cross-feature-fk-inference: byte-identical shape to `scan`'s own --db/--database-url-env/
+			// --schema (resolved via the SAME resolveDbSchemaOrExit() helper) -- omitting them entirely
+			// is the exact prior behavior, unchanged.
+			db: { type: 'boolean', default: false },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'scan cross-feature-waive': {
+		usage: 'bskel scan cross-feature-waive --feature <id> --signal resource_type|table|operation_id|db_foreign_key --identifier <name> --other-feature <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			signal: { type: 'string', default: null, required: true },
+			identifier: { type: 'string', default: null, required: true },
+			'other-feature': { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'feature init': {
 		usage: 'bskel feature init --slug <name>',
 		options: { slug: { type: 'string', default: null, required: true } },
@@ -263,11 +306,15 @@ export const COMMANDS = {
 		},
 	},
 	'stack apply': {
-		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--json]',
+		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--json]',
 		options: {
 			choice: { type: 'string', default: null },
 			apply: { type: 'boolean', default: false },
 			port: { type: 'string', default: '8080', numeric: { min: 1, max: 65535 } },
+			// D-write-safety-phase0 (item 2): mirrors handles emit's own --force/--reason exactly --
+			// a file that diverged from what `stack apply` itself last wrote is refused without this.
+			force: { type: 'boolean', default: false },
+			reason: { type: 'string', default: '' },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -316,11 +363,16 @@ export const COMMANDS = {
 	// purpose IS the live query). Reuses `--resource type1,type2`'s exact multi-value convention
 	// from `handles plan`/`handles emit` rather than a new singular flag name.
 	'handles audit': {
-		usage: 'bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--json]',
+		usage: 'bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--module <name>] [--check-registry-coverage] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			'database-url-env': { type: 'string', default: null, required: true },
 			resource: { type: 'string', default: '' },
+			// D-write-safety-phase1 (item 3): both opt-in, only consulted when --check-registry-coverage
+			// is set -- the base command stays gate-independent and scan-report-independent otherwise
+			// (see this command's own doc comment in bin/bskel.mjs for why that matters).
+			module: { type: 'string', default: null },
+			'check-registry-coverage': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -343,10 +395,11 @@ export const COMMANDS = {
 		},
 	},
 	'observe import': {
-		usage: 'bskel observe import --feature <id> --receipts <path> [--json]',
+		usage: 'bskel observe import --feature <id> --receipts <path> [--fail-on-violation] [--json]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			receipts: { type: 'string', default: null, required: true },
+			'fail-on-violation': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -410,6 +463,70 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-patch-transactions: content-addressed patch transactions, Slice 1 (config_check ->
+	// config_apply). `propose`/`approve` only touch specs/, so no --force escape exists on either --
+	// re-propose is the only remediation for a stale target. `rollback` alone gets --force (reverting
+	// to a known-good, git-recoverable prior state is materially lower-risk than forcing a forward
+	// edit whose collateral effects were never re-verified).
+	'patch propose': {
+		usage: 'bskel patch propose --feature <id> [--kind config-apply --choice <stackChoiceId> --target <config_check target path> | --kind ddl-apply --database-url-env <NAME> --sql-file <path> [--schema public]] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			// D-ddl-apply: default 'config-apply' -- omitting --kind entirely is byte-identical to
+			// this project's prior behavior. choice/target/database-url-env/sql-file are validated
+			// by hand inside cmdPatchPropose (kind-conditional requirements aren't expressible via
+			// this table's own unconditional `required: true`), matching this file's existing
+			// convention for kind-conditional flags (e.g. --reason on approve/rollback).
+			kind: { type: 'string', default: 'config-apply' },
+			choice: { type: 'string', default: null },
+			target: { type: 'string', default: null },
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sql-file': { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch approve': {
+		usage: 'bskel patch approve --feature <id> --transaction <id> --reason "..." [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch apply': {
+		usage: 'bskel patch apply --feature <id> --transaction <id> [--confirm <id-or-dropped-table-name>] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			// D-ddl-apply: required for any kind other than config-apply -- what value it must
+			// exactly equal is kind- AND transaction-specific (getPatchKind(kind).requiredConfirmValue(txn)):
+			// the transaction id for a non-drop ddl-apply transaction, or the sorted, comma-joined
+			// dropped-table name(s) for one that drops a table. Checked by hand inside cmdPatchApply
+			// once the transaction's own kind/shape is known, not declaratively here. Ignored for
+			// config-apply.
+			confirm: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch rollback': {
+		usage: 'bskel patch rollback --feature <id> --transaction <id> --reason "..." [--force] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			transaction: { type: 'string', default: null, required: true },
+			reason: { type: 'string', default: '' },
+			force: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'patch list': {
+		usage: 'bskel patch list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	verify: {
 		usage: 'bskel verify --feature <id> [--build [--allow-skip-build]] [--json]',
 		options: {
@@ -444,13 +561,27 @@ export const COMMANDS = {
 		},
 	},
 	serve: {
-		usage: 'bskel serve [--port N] [--host <addr>] [--json]',
+		usage: 'bskel serve [--port N] [--host <addr>] [--database-url-env <NAME> [--schema public] [--sign-key <path>] [--require-sign-key]] [--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' },
+			// D-ddl-apply: every new DB-schema/patch-transaction route is gated behind this one flag
+			// being present -- a plain `bskel serve` (no --database-url-env) stays byte-identical to
+			// today, those paths simply don't exist (404, not 403), mirroring --host's own "safe
+			// default, explicit override" convention. --sign-key is optional even when the DB surface
+			// is enabled (see D-ddl-apply's "detect and warn, never hard-require" signing posture).
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			'sign-key': { type: 'string', default: null },
+			// D-ddl-apply: opt-in-to-MORE-strictness -- refuses to even start the DDL surface without
+			// --sign-key also given, closing this feature's own named "mandatory signing... cheap,
+			// well-justified near-term addition" EXIT item. A no-op when --database-url-env wasn't
+			// given at all (nothing to enforce on a surface that isn't running), same as --schema/
+			// --sign-key themselves already being inert outside that case.
+			'require-sign-key': { type: 'boolean', default: false },
 			json: { type: 'boolean', default: false },
 		},
 	},