backend-skeleton 1.0.0-beta.8 → 1.0.0

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

package/schemas/gate-attestation.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:gate-attestation:1",
+  "title": "backend-skeleton signed gate attestation (bskel gate export --sign / bskel attest verify)",
+  "description": "D-gate-attestation-signing: the combined envelope `bskel gate export --sign` writes -- a gate-export report (schemas/gate-export.schema.json's own shape) plus a detached Ed25519 signature over that report's canonical (deep-key-sorted, whitespace-free) JSON serialization. Signature validity is the ONLY thing `bskel attest verify`'s exit code reflects -- whether the gates inside `report` themselves passed is a separate, printed-but-not-exit-code-driving question (a legitimately-signed, all-failing report must not look like a tool error).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "report", "signature"],
+  "properties": {
+    "schema": { "const": "sbf.gate-attestation/1" },
+    "report": { "type": "object" },
+    "signature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": { "const": "ed25519" },
+        "value": { "type": "string", "description": "base64-encoded raw Ed25519 signature bytes over canonicalize(report)." }
+      }
+    }
+  }
+}

package/schemas/gate-export.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:gate-export:1",
+  "title": "backend-skeleton gate export report (bskel gate export)",
+  "description": "D-gate-attestation-signing: this schema was written FROM cmdGateExport's real, already-shipped report shape (bin/bskel.mjs) -- it did not exist before this item and the report itself is unchanged by adding it. `current` mirrors schemas/state.schema.json's own per-gate record shape exactly (the same raw, stored record getGate() returns -- status is constrained to the 3 values ever WRITTEN to disk, never the read-time-derived not_run/stale/pass (forced)). `additionalProperties` is intentionally open on `gates` itself (keyed by gate name) so this schema never needs editing when a new gate is added -- GATE_NAMES in lib/gate-definitions.mjs is the one place that list lives.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "generated_at", "git", "gates"],
+  "properties": {
+    "schema": { "const": "sbf.gate-export/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "git": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["branch", "head_sha", "dirty"],
+      "properties": {
+        "branch": { "type": ["string", "null"], "description": "lib/repo.mjs's currentBranch() -- null on failure, or the literal string \"HEAD\" for a detached HEAD (not a real branch name)." },
+        "head_sha": { "type": "string" },
+        "dirty": { "type": ["boolean", "null"], "description": "lib/repo.mjs's isDirty() -- null on failure. true covers BOTH modified tracked files and untracked files (git status --porcelain, no -uno)." }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["scope", "current", "history"],
+        "properties": {
+          "scope": { "type": "string", "description": "the resolved scope id this gate was read from -- REPO_GATE_ID (\"_repo\") for a repo-scoped gate, or the feature_id itself." },
+          "current": {
+            "anyOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["status", "token", "at"],
+                "properties": {
+                  "status": { "enum": ["pass", "awaiting_disposition", "revoked"] },
+                  "token": { "type": "string" },
+                  "at": { "type": "string" },
+                  "forced": { "type": "boolean" },
+                  "reason": { "type": "string" },
+                  "evidence": { "type": "object" },
+                  "inputs": { "type": "object" }
+                }
+              }
+            ]
+          },
+          "history": {
+            "type": "array",
+            "items": { "type": "object" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/patch-transaction.schema.json

@@ -0,0 +1,182 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:patch-transaction:1",
+  "title": "backend-skeleton content-addressed patch transaction (specs/<feature_id>/patch-transactions/<transaction_id>.json)",
+  "description": "D-patch-transactions: generalizes A3/D-patch-strategy's per-{resource,field} patch-approvals.json shape into a kind-agnostic propose/approve/apply/rollback transaction. One file per transaction (not one growing array) -- each record carries a lifecycle with real state transitions and references a content-addressed rollback blob under this same feature's patch-transactions/blobs/ directory. D-ddl-apply added a second kind ('ddl-apply') -- kind-specific source/target/postcondition/apply shapes are enforced by the allOf/if-then branches below, keyed on `kind`. The config-apply branch is byte-identical to this schema's pre-D-ddl-apply shape (existing config-apply records validate unchanged).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "transaction_id", "feature_id", "kind", "source", "target", "preimage", "proposed_value", "postcondition", "status", "created_at"],
+  "properties": {
+    "schema": { "const": "sbf.patch-transaction/1" },
+    "transaction_id": { "type": "string", "pattern": "^pt-[0-9a-f-]{36}$" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "kind": { "enum": ["config-apply", "ddl-apply"] },
+    "source": {
+      "type": "object",
+      "description": "Kind-specific opaque context needed to re-plan this transaction fresh at approve/apply time. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "target": {
+      "type": "object",
+      "description": "Kind-specific description of what this transaction acts on. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "preimage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["region_hash", "file_hash"],
+      "properties": {
+        "region_hash": { "type": "string" },
+        "file_hash": { "type": "string" }
+      }
+    },
+    "current_value": { "type": "string" },
+    "proposed_value": { "type": "string" },
+    "postcondition": {
+      "type": "object",
+      "description": "Kind-specific re-check applied before the record is allowed to transition to 'applied'. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "status": { "enum": ["proposed", "approved", "applied", "rolled_back"] },
+    "created_at": { "type": "string", "format": "date-time" },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "at"],
+      "properties": {
+        "reason": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "apply": {
+      "type": "object",
+      "description": "Kind-specific record of what actually happened at apply time. Shape enforced per-kind by the allOf/if-then branches below."
+    },
+    "rollback": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "at"],
+      "properties": {
+        "reason": { "type": "string" },
+        "at": { "type": "string", "format": "date-time" },
+        "forced": { "type": "boolean" }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "config-apply" } } },
+      "then": {
+        "properties": {
+          "source": {
+            "additionalProperties": false,
+            "required": ["choice"],
+            "properties": {
+              "choice": { "type": "string" }
+            }
+          },
+          "target": {
+            "additionalProperties": false,
+            "required": ["file", "key_path"],
+            "properties": {
+              "file": { "type": "string" },
+              "key_path": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+            }
+          },
+          "postcondition": {
+            "additionalProperties": false,
+            "required": ["kind", "pattern"],
+            "properties": {
+              "kind": { "const": "regex-match" },
+              "pattern": { "type": "string" }
+            }
+          },
+          "apply": {
+            "additionalProperties": false,
+            "required": ["at", "postimage_file_hash"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "postimage_file_hash": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "ddl-apply" } } },
+      "then": {
+        "properties": {
+          "source": {
+            "additionalProperties": false,
+            "required": ["database_url_env", "schema"],
+            "properties": {
+              "database_url_env": { "type": "string" },
+              "schema": { "type": "string" }
+            }
+          },
+          "target": {
+            "additionalProperties": false,
+            "required": ["database_url_env", "schema", "sql_text"],
+            "properties": {
+              "database_url_env": { "type": "string" },
+              "schema": { "type": "string" },
+              "sql_text": { "type": "string" }
+            }
+          },
+          "postcondition": {
+            "additionalProperties": false,
+            "required": ["kind", "schema", "expected_tables"],
+            "properties": {
+              "kind": { "const": "db-schema-diff" },
+              "schema": { "type": "string" },
+              "expected_tables": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              },
+              "expected_indexes": {
+                "description": "D-ddl-apply (INDEX/SCHEMA postcondition precision): optional, not required -- absent on any ddl-apply record persisted before this field existed, and empty for a statement batch with no CREATE/DROP INDEX in it.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              },
+              "expected_schemas": {
+                "description": "D-ddl-apply (INDEX/SCHEMA postcondition precision): optional, not required -- same reasoning as expected_indexes, for CREATE/DROP SCHEMA.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "expect"],
+                  "properties": {
+                    "name": { "type": "string" },
+                    "expect": { "enum": ["present", "absent"] }
+                  }
+                }
+              }
+            }
+          },
+          "apply": {
+            "additionalProperties": false,
+            "required": ["at", "postimage_schema_hash", "executed_statements"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "postimage_schema_hash": { "type": "string" },
+              "executed_statements": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/scan-report.schema.json

@@ -67,21 +67,23 @@
         "migrations": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["tool", "files", "tables"],
+          "required": ["tool", "files", "tables", "generated_at"],
           "properties": {
             "tool": { "enum": ["flyway", "liquibase", "none"] },
             "files": { "type": "array", "items": { "type": "string" } },
-            "tables": { "type": "array" }
+            "tables": { "type": "array" },
+            "generated_at": { "description": "D-cross-feature-fk-inference (staleness/freshness token): when this Plane A migration-file scan ran.", "type": "string", "format": "date-time" }
           }
         },
         "live": {
           "type": ["object", "null"],
           "additionalProperties": false,
-          "required": ["schema", "tables", "schema_hash"],
+          "required": ["schema", "tables", "schema_hash", "generated_at"],
           "properties": {
             "schema": { "type": "string" },
             "tables": { "type": "array" },
-            "schema_hash": { "type": "string" }
+            "schema_hash": { "type": "string" },
+            "generated_at": { "description": "D-cross-feature-fk-inference (staleness/freshness token): when this Plane C live introspection ran.", "type": "string", "format": "date-time" }
           }
         }
       }

package/schemas/stack-choice.schema.json

@@ -50,11 +50,22 @@
           "type": "array",
           "items": {
             "type": "object",
+            "additionalProperties": false,
             "required": ["target", "externalized_pattern", "note"],
             "properties": {
               "target": { "type": "string" },
               "externalized_pattern": { "type": "string" },
-              "note": { "type": "string" }
+              "note": { "type": "string" },
+              "apply": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["key_path", "value_template"],
+                "description": "D-patch-transactions: optional, additive -- a catalog entry without this still behaves exactly as before (config_check reports needs-manual-patch only, `bskel patch propose` refuses naming this note). key_path addresses a plain scalar value via YAML.Document#getIn(); value_template's one literal token, {{CURRENT}}, is replaced with the value's current string content -- deliberately NOT lib/template.mjs's own {{PORT}} renderer, a different, unrelated templating purpose.",
+                "properties": {
+                  "key_path": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+                  "value_template": { "type": "string" }
+                }
+              }
             }
           }
         }

package/stack/apply.mjs

@@ -27,7 +27,10 @@ export function listCatalogChoices() {
 // paths (must stay under STACK_ROOT) and generated-file target paths (must stay under the
 // caller's repoRoot). A catalog entry is data (currently only ships with this skill, but the
 // mechanism doesn't assume that), so every path it names is treated as untrusted input.
-function assertContained(root, target, label) {
+// D-patch-transactions: exported once stack/config-apply.mjs (a second real consumer, checking
+// the SAME catalog-declared config_check.target path) needed the identical containment check --
+// previously only used inside this file.
+export function assertContained(root, target, label) {
 	const resolvedRoot = path.resolve(root);
 	const resolvedTarget = path.resolve(target);
 	const rel = path.relative(resolvedRoot, resolvedTarget);

package/stack/catalog/ngrok.yml

@@ -39,8 +39,14 @@ static:
       note: >
         allowed-origins must be environment-variable-driven for the tunnel URL to actually take
         effect (e.g. `allowed-origins: ${AUTH_LOGIN_ALLOWED_ORIGINS:default-value}`). If this
-        check reports needs-manual-patch, add that yourself -- backend-skeleton deliberately
-        does not auto-edit application config files (see D-config-patch in DECISIONS.md).
+        check reports needs-manual-patch, run `bskel patch propose --feature <id> --choice ngrok
+        --target src/main/resources/application.yaml` for a machine-applicable fix (see
+        D-patch-transactions in DECISIONS.md), or add it yourself -- backend-skeleton never
+        auto-edits an application config file without an explicit propose/approve/apply sequence
+        (see D-config-patch in DECISIONS.md).
+      apply:
+        key_path: [auth, login, allowed-origins]
+        value_template: "${AUTH_LOGIN_ALLOWED_ORIGINS:{{CURRENT}}}"
 
 runtime:
   script: scripts/dev-tunnel.sh

package/stack/config-apply.mjs

@@ -0,0 +1,168 @@
+// D-patch-transactions: the "config-apply" kind planner for lib/patch-transactions.mjs -- turns a
+// catalog `config_check` entry's new, additive `apply` block into a real, comment-preserving edit
+// via the `yaml` package's Document API (already a repo dependency, used elsewhere in this file's
+// own sibling apply.mjs for read-only parsing). `propose`/`approve`/`apply` in bin/bskel.mjs all
+// call planConfigApply() FRESH every time -- never trusting a stored render -- which is what makes
+// "re-verify preimage at every step" real rather than assumed.
+//
+// Two things were verified live against yaml@2.9.0 before this module was written, not assumed:
+// (1) doc.getIn(keyPath, true) and a mapping pair's key/value nodes carry real byte-offset
+// `.range` tuples today -- the "preimage hash of the specific target region" primitive this
+// feature needs. (2) the Document API does NOT byte-for-byte round-trip untouched lines elsewhere
+// in the same file (comment spacing collapses, flow-collection spacing normalizes, trailing
+// whitespace strips) -- a postcondition-only check would silently ship cosmetic reformatting of a
+// hand-tuned config file, exactly the failure mode D-config-patch's own WHY was written to avoid.
+// The collateral-diff check below is the direct fix for that, not an afterthought.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseDocument, isScalar } from 'yaml';
+import { sha256File, sha256String } from '../lib/fsutil.mjs';
+import { unifiedDiff } from '../lib/diff.mjs';
+import { assertContained } from './apply.mjs';
+import { readBlob } from '../lib/patch-transactions.mjs';
+
+class ConfigApplyPlanError extends Error {}
+
+function findConfigCheck(entry, targetPath) {
+	return (entry.static?.config_check ?? []).find((c) => c.target === targetPath);
+}
+
+// 0-indexed line number of a byte offset -- local, tiny, and 0-indexed (matching this module's own
+// line-array comparisons below) rather than reusing scanners/text-util.mjs's 1-indexed
+// lineNumberAt(), which would introduce a new stack/ -> scanners/ import direction for four lines
+// of logic.
+function lineIndexAt(text, offset) {
+	let line = 0;
+	for (let i = 0; i < offset; i++) if (text[i] === '\n') line++;
+	return line;
+}
+
+// Refuses (throws ConfigApplyPlanError) unless EVERY line that differs between `before` and
+// `after` falls within [targetStartLine, targetEndLine] (inclusive, 0-indexed) -- the direct
+// mitigation for yaml's own confirmed collateral-reformatting behavior on UNTOUCHED lines
+// elsewhere in the same document. A total line-count mismatch is refused outright (Slice 1 only
+// ever targets a single-line scalar; a line appearing/disappearing anywhere is unexpected either
+// way and safer to refuse than to reason about).
+function assertNoCollateralChanges(relPath, before, after, targetStartLine, targetEndLine) {
+	const beforeLines = before.split('\n');
+	const afterLines = after.split('\n');
+	if (beforeLines.length !== afterLines.length) {
+		throw new ConfigApplyPlanError(
+			`the proposed edit to "${relPath}" changes the file's total line count (${beforeLines.length} -> ${afterLines.length}), which this tool refuses to apply automatically -- review the diff and patch it by hand:\n${unifiedDiff(relPath, before, after)}`,
+		);
+	}
+	const collateral = [];
+	for (let i = 0; i < beforeLines.length; i++) {
+		if (i >= targetStartLine && i <= targetEndLine) continue;
+		if (beforeLines[i] !== afterLines[i]) collateral.push(i + 1);
+	}
+	if (collateral.length > 0) {
+		throw new ConfigApplyPlanError(
+			`the proposed edit to "${relPath}" would also change line(s) ${collateral.join(', ')} outside the target key -- refusing to risk silently reformatting unrelated content. Review the diff and patch it by hand:\n${unifiedDiff(relPath, before, after)}`,
+		);
+	}
+}
+
+// `catalogEntry` is an already-schema-validated stack/apply.mjs `loadCatalogEntry()` result;
+// `targetPath` is the catalog-declared `config_check.target` (repo-relative) to act on. Returns a
+// plan object shaped for lib/patch-transactions.mjs's propose/approve/apply, or throws
+// ConfigApplyPlanError with a message safe to print directly to a human.
+export function planConfigApply(repoRoot, catalogEntry, targetPath) {
+	const check = findConfigCheck(catalogEntry, targetPath);
+	if (!check) {
+		throw new ConfigApplyPlanError(`no config_check entry for target "${targetPath}" in catalog choice "${catalogEntry.id}"`);
+	}
+	if (!check.apply) {
+		throw new ConfigApplyPlanError(`no machine-applicable fix declared for "${targetPath}" in catalog choice "${catalogEntry.id}" -- see its note: "${check.note}"`);
+	}
+
+	const targetAbs = path.join(repoRoot, targetPath);
+	assertContained(repoRoot, targetAbs, 'catalog config_check target path');
+	if (!fs.existsSync(targetAbs)) {
+		throw new ConfigApplyPlanError(`"${targetPath}" does not exist -- nothing to patch`);
+	}
+	const text = fs.readFileSync(targetAbs, 'utf8');
+
+	const doc = parseDocument(text);
+	const { key_path: keyPath, value_template: valueTemplate } = check.apply;
+	const node = doc.getIn(keyPath, true);
+	if (node === undefined) {
+		throw new ConfigApplyPlanError(`"${targetPath}" has no value at ${JSON.stringify(keyPath)} -- the catalog entry's "apply.key_path" doesn't match this file's real structure`);
+	}
+	if (!isScalar(node)) {
+		throw new ConfigApplyPlanError(`"${targetPath}"'s value at ${JSON.stringify(keyPath)} is not a plain scalar (it's a mapping or list) -- config_apply only ever targets a single scalar value`);
+	}
+
+	// The parent mapping's own pair for this key, so the region span can include the key AND its
+	// trailing comment (pair.value.range[2]), not just the bare value -- a reformatted comment on
+	// the TARGET's own line is expected (part of the edit), only OTHER lines' comments/spacing
+	// changing is collateral damage.
+	const parentPath = keyPath.slice(0, -1);
+	const parentNode = parentPath.length === 0 ? doc.contents : doc.getIn(parentPath, true);
+	const lastKey = keyPath[keyPath.length - 1];
+	const pair = parentNode.items.find((p) => String(p.key.value) === lastKey);
+	if (!pair) {
+		throw new ConfigApplyPlanError(`internal error: resolved a value at ${JSON.stringify(keyPath)} but could not locate its own key/value pair -- refusing`);
+	}
+
+	const currentValue = String(node.value);
+	const proposedValue = valueTemplate.replaceAll('{{CURRENT}}', currentValue);
+
+	const regionStart = pair.key.range[0];
+	const regionEnd = pair.value.range[2];
+	const regionText = text.slice(regionStart, regionEnd);
+	const regionHash = sha256String(regionText);
+
+	doc.setIn(keyPath, proposedValue);
+	const renderedContent = String(doc);
+
+	const targetStartLine = lineIndexAt(text, regionStart);
+	// regionEnd (pair.value.range[2]) includes the target line's OWN trailing newline when the
+	// value has a line comment or is the last token before one -- verified live against yaml@2.9.0.
+	// Using regionEnd directly would make lineIndexAt count that newline as already passed, shifting
+	// targetEndLine one line too far and silently exempting the FOLLOWING line from the collateral
+	// check (confirmed live: without this -1, a flow-list reformatted on the very next line was
+	// wrongly treated as "inside the target region" and the collateral check never fired).
+	// Math.max guards the degenerate regionStart===regionEnd case (an empty span) from going negative.
+	const targetEndLine = lineIndexAt(text, Math.max(regionStart, regionEnd - 1));
+	assertNoCollateralChanges(targetPath, text, renderedContent, targetStartLine, targetEndLine);
+
+	if (!new RegExp(check.externalized_pattern).test(renderedContent)) {
+		throw new ConfigApplyPlanError(`the proposed edit to "${targetPath}" does not satisfy this catalog entry's own "externalized_pattern" -- the "apply" block is likely misconfigured, refusing rather than applying an edit that wouldn't even fix the check it's for`);
+	}
+
+	return {
+		target: { file: targetPath, key_path: keyPath },
+		preimage: { region_hash: regionHash, file_hash: sha256String(text) },
+		current_value: currentValue,
+		proposed_value: proposedValue,
+		postcondition: { kind: 'regex-match', pattern: check.externalized_pattern },
+		originalContent: text,
+		renderedContent,
+	};
+}
+
+// D-ddl-apply: the "config-apply" kind's apply/rollback executors, injected into
+// lib/patch-transactions.mjs's applyTransaction()/rollbackTransaction() via lib/patch-kinds.mjs.
+// Bodies are moved verbatim from what used to live directly inside applyTransaction()/
+// rollbackTransaction() -- a pure refactor, not a behavior change (both event this project's own
+// existing patch-transactions.test.mjs / patch-config-apply-cli.test.mjs suites re-verify pass
+// unchanged).
+export async function executeConfigApply(root, featureId, txn, freshKindPlan) {
+	const targetAbs = path.join(root, txn.target.file);
+	fs.writeFileSync(targetAbs, freshKindPlan.renderedContent);
+	return { postimage_file_hash: sha256String(freshKindPlan.renderedContent) };
+}
+
+export async function executeConfigRollback(root, featureId, txn, { force = false } = {}) {
+	const targetAbs = path.join(root, txn.target.file);
+	const currentHash = sha256File(targetAbs);
+	if (currentHash !== txn.apply.postimage_file_hash && !force) {
+		throw new Error(
+			`"${txn.target.file}" has changed since transaction "${txn.transaction_id}" applied -- rolling back would silently clobber that change; pass --force --reason if intentional`,
+		);
+	}
+	const original = readBlob(root, featureId, txn.preimage.file_hash);
+	fs.writeFileSync(targetAbs, original);
+	return {};
+}