docs(#208): ADR-0043 + migration/verify docs for @sql/@Unmanaged

Task 11 — the durable docs for the DDL-ownership escape valves.

- spec/decisions/ADR-0043-ddl-ownership-escape-valves.md (new, Nygard): the one-axis /
  two-attr model, the ADR-0037 attribute rationale, the suppression rule, the six
  loader-validation rules, the cross-port (register+validate) vs TS-only (lowering)
  split, the adopt-view ceremony, and the documented adopter caveats + deferred
  follow-ups (@dependsOn for @SQL, matview managed path, opaque-body column verify).
- agent-context/skills/metaobjects-verify/references/migration.md: replaced the "no
  attribute injects hand-written SQL (by design)" statement with a "DDL-ownership
  escape valves" section documenting @SQL (tool-managed opaque body + adopt-view) and
  @Unmanaged (external, managed elsewhere).
- docs/features/migrations-and-drift.md: an @sql/@Unmanaged note beside the adopt-view
  step — an irreducible view is now managed-but-opaque instead of accidentally-unmanaged.
- CHANGELOG.md [Unreleased]: the #208 entry.
- spec/roadmap.md: marked #208 SHIPPED (unreleased) + filed the three deferred follow-ups.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGQ7oSuNcjhsMHWwZzhBwr

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,15 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### #208 — DDL-ownership escape valves (`@sql` body + `@unmanaged` marker)
+
+Two mutually-exclusive `source.rdb` attributes express *who owns a DB object's DDL* — the escape from "a projection's view is always synthesized from its `origin.*` children" (ADR-0043):
+
+- **`@sql`** — a hand-written view body the tool **registers, fingerprints, and drift-checks but never authors or parses**. The value is the body inside `CREATE <kind> <name> AS …`. It lets a genuinely-irreducible view (recursive CTE, window function, set operation) carry an `extends`-bound identity/fields for row identity and shape *without* the tool mis-synthesizing a wrong base-table passthrough `SELECT` — the **suppression rule** classifies DDL-ownership *before* the derivation decision, closing a silent-wrong-synthesis hole. The `@sql` view rides the existing emit/fingerprint pipeline; a pre-existing unstamped view at its name is `replace-view`-blocked pending the one-time **`meta migrate --allow adopt-view`** adoption ceremony. `@sql` on a writable kind, combined with `@unmanaged`, empty, or combined with `origin.*`/`@filter` is a load error. v1 migrate lowering is `@kind: view` only (matview/proc → an actionable hard error).
+- **`@unmanaged: true`** — this DB object (a view **or a table**) is managed elsewhere (Flyway / a hand-migration owns its DDL). `meta migrate` never creates, drops, or drift-checks it (excluded from both the expected and the introspected-actual sides across the online, offline, D1, and `verify` paths); `meta verify --db` reports it as *external (declared)*. An inbound FK from a managed table still resolves the external table's physical name.
+
+**Registration + the six fail-closed loader-validation rules (R1–R6) ship in all five ports** (TS / C# / Java / Kotlin / Python), resolving `MetaSource` accessors following the `@role`/`effectiveKind` precedent (ADR-0039), conformance-gated by shared `fixtures/conformance/` error-fixtures — every port emits the same code per rule (`ERR_SQL_BODY_WITH_UNMANAGED` / `ERR_SQL_BODY_ON_WRITABLE_KIND` / `ERR_BAD_ATTR_VALUE` / `ERR_ORIGIN_UNDER_SQL_BODY` / `WARN_ORIGIN_UNDER_UNMANAGED`). All migrate/verify **lowering is TS-only** (ADR-0015). An `xhigh` review before merge caught a real offline-`migrate` DROP-for-external-table bug (the offline `planOffline` path did not thread the unmanaged-name set), fixed + regression-tested. Deferred follow-ups: `@dependsOn` for `@sql` views, the matview managed path, and opaque-body column-name verification. Designed in `docs/superpowers/specs/2026-07-17-issue-208-ddl-ownership-escape-valves-design.md`.
+
 ### #214 — entity read-view codegen READ half (all five ports)
 
 Completes the read side of the FR-024 §7 entity read-view (#213 shipped the write/schema half — the write table excludes derived `origin.*` fields and the replica view is emitted + migrate-converged). A **write-through entity** (a writable `table` source + a read-only replica `view` source + derived fields) now generates a hybrid read/write surface in TypeScript:

agent-context/skills/metaobjects-verify/references/migration.md

@@ -129,8 +129,10 @@ A non-unique recency index is `index.lookup`:
 
 The `@where` / `@using` / `@expr` / `@orders` attributes are **index** physical
 escapes on `identity.secondary` / `index.lookup` — they are NOT a raw-SQL escape
-hatch for views. There is no attribute that injects hand-written SQL into a
-projection view body (by design — see below).
+hatch for views. For a genuinely-irreducible view body, use the `source.rdb`
+**`@sql`** escape (a tool-managed, opaque hand-written body — see the
+"DDL-ownership escape valves" section below); for a DB object owned entirely by
+Flyway / a hand-migration, use **`@unmanaged`**.
 
 ## Projection views (generated view DDL)
 
@@ -151,10 +153,55 @@ canonical view-SQL emitter shared with drift detection.
   `metaobjects-audit` skill, not here.
 
 **Do not hand-author view SQL for a shape origins can express** — model it as a
-projection so the view DDL is generated and drift-checked. The only case for
-hand-written view DDL is a genuinely irreducible view (recursive CTE, window
-function, set operation) that origins can't express; carry that in a hand-edited
-migration file.
+projection so the view DDL is generated and drift-checked. For a genuinely
+irreducible view (recursive CTE, window function, set operation) that origins
+can't express, use the `@sql` escape below rather than a hand-edited migration
+file — that keeps the view tool-managed (emitted, fingerprinted, drift-checked)
+instead of accidentally unmanaged.
+
+## DDL-ownership escape valves (`@sql` / `@unmanaged`) — #208
+
+Two mutually-exclusive `source.rdb` attributes express *who owns a DB object's
+DDL* (ADR-0043). They are the escape from "a projection's view is always
+synthesized from its `origin.*` children."
+
+**`@sql`** — a hand-written view body the tool **registers, fingerprints, and
+drift-checks but never authors or parses**. The value is the body *inside*
+`CREATE VIEW <name> AS …` (not the `CREATE` wrapper, not the name). Legal only on
+a read-only kind; v1 migrate lowers it on `@kind: view` only (matview/proc → a
+hard error, deferred). Authored sigil-free in YAML as a block scalar:
+
+```yaml
+object.projection:
+  name: OrgTree
+  children:
+    - source.rdb: { kind: view, view: v_org_tree, sql: |
+        WITH RECURSIVE t AS (
+          SELECT id, parent_id FROM org WHERE parent_id IS NULL
+          UNION ALL SELECT o.id, o.parent_id FROM org o JOIN t ON o.parent_id = t.id)
+        SELECT * FROM t }
+    - field.long: { name: id, extends: Org.id }
+    - identity.primary: { extends: Org.pk }
+```
+
+The `extends`-bound identity/fields declare the read model's shape and row
+identity *without* triggering wrong synthesis (the suppression rule). The view is
+emitted verbatim with a fingerprint COMMENT stamp; a second `meta migrate` is a
+no-op. **Adopting a pre-existing hand-written view** at that name: the first diff
+reports `replace-view` **blocked** (an unstamped view is indistinguishable from
+someone else's SQL) — run **`meta migrate --allow adopt-view`** once to stamp it,
+then it converges. `@sql` **forbids** `origin.*` children and a `@filter` on the
+same host (two sources of truth → load error).
+
+**`@unmanaged: true`** — this DB object (a view **or a table**) is managed
+elsewhere (Flyway / a hand-migration owns its DDL). `meta migrate` never creates,
+drops, or drift-checks it; `meta verify --db` reports it as *external (declared)*.
+Legal on any `@kind`, including `table` (the Flyway-owned-entity case). An FK from
+a managed table into an `@unmanaged` table resolves its physical name, but the
+external object must exist before that FK is applied (a documented ordering caveat,
+not enforced).
+
+`@sql` and `@unmanaged` are **mutually exclusive** on one source.
 
 ## Adopting an existing database (non-destructive)
 

docs/features/migrations-and-drift.md

@@ -183,6 +183,21 @@ closes the loop on the doctrine in
 sitting where a projection expects one is now **visible to `meta verify --db`** as drift,
 instead of being silently invisible to it.
 
+**Genuinely-irreducible views and externally-owned objects (`@sql` / `@unmanaged`, #208).**
+Some read models cannot be expressed as `origin.*` (a recursive CTE, a window function, a
+set operation). Rather than hand-write such a view *outside* the tool — where it degrades
+to accidentally-unmanaged — carry its body in a `source.rdb` **`@sql`** attribute. The tool
+registers, fingerprints, and drift-checks that verbatim body (never parsing it) exactly like
+a synthesized view: it emits `CREATE VIEW … AS <your body>` with a fingerprint stamp, a
+second migrate is a no-op, and a pre-existing hand-written view at that name is adopted via
+the same `--allow adopt-view` step above. An `@sql` view may carry an `extends`-bound
+`identity.primary` / fields (for row identity and read-model shape) without the tool
+mis-synthesizing a body. For a DB object whose DDL is owned entirely elsewhere (Flyway, a
+hand-migration) — a view **or a table** — mark its source **`@unmanaged: true`**: `meta
+migrate` never creates, drops, or drift-checks it, and `meta verify --db` reports it as
+*external (declared)*. The two are mutually exclusive. See
+[ADR-0043](../../spec/decisions/ADR-0043-ddl-ownership-escape-valves.md).
+
 ## Verified by
 
 The following conformance fixtures gate this feature's behavior across ports:

spec/decisions/ADR-0043-ddl-ownership-escape-valves.md

@@ -0,0 +1,70 @@
+# ADR-0043: DDL-ownership escape valves (`@sql` body + `@unmanaged` marker)
+
+## Status
+
+**Accepted** (2026-07-17). Implements FR #208 (chartered as the #195 follow-up (a)). Applies the ADR-0037 vocabulary-expansion framework; composes with the projection/view model (ADR-0028), the source-v2 paradigm (ADR-0007), and the TS-owns-schema split (ADR-0015).
+
+## Context
+
+A projection's view body is **synthesized** from its `origin.*` children through the one canonical view-SQL emitter (`build-projection-views.ts`). This is the right default — a projection's `CREATE VIEW` is derived from the model, so a hand-written view is drift. But two cases have no home:
+
+1. **A genuinely-irreducible view.** Some read models cannot be expressed as `origin.*` (recursive CTEs, window functions, lateral joins, vendor-specific SQL). Today the author's only recourse is to hand-write the view *outside* the tool — where it degrades to **accidentally unmanaged**: `meta migrate` neither owns nor emits it, and `meta verify --db` cannot drift-check it.
+
+2. **The silent-wrong-synthesis hole.** The moment such a hand-bodied view declares its lineage — an `extends`-bound `identity.primary` for row identity, or `extends`-bound fields for shape — `viewIsDerived()` flips **true** and the tool **synthesizes a wrong body** (a trivial base-table passthrough `SELECT`) in place of the author's intended SQL. That silent-wrong-synthesis is worse than an abort.
+
+Separately, an author may want a DB object (a view **or a table**) whose DDL is owned entirely **elsewhere** — a Flyway migration, a hand-run script — so `meta migrate` must never create, drop, or drift-check it.
+
+These are the two non-default states of **one axis: who owns a DB object's DDL** — `derived` (default; the tool synthesizes) · `supplied` (the author writes the body, the tool manages its lifecycle) · `external` (someone else owns the DDL).
+
+## Decision
+
+### 1. Two attributes on `source.rdb`, one axis
+
+- **`@sql`** (string) — a hand-written body the tool **registers, fingerprints, and drift-checks but never authors or parses**. The body goes *inside* `CREATE <kind> <physicalName> AS …` — never the `CREATE` wrapper, never the object name.
+- **`@unmanaged`** (boolean) — this object's DDL is owned elsewhere; the tool never touches it.
+
+They are **mutually exclusive** on a single source ("emit + fingerprint this" contradicts "never touch this"). Both are attributes on `source.rdb` (ADR-0007 — physical concerns live on the source child), so granularity is **per-source**: a write-through entity can keep its table managed while marking only its read-view source `@unmanaged`.
+
+### 2. ADR-0037 rationale — why attributes, not a subtype or a `@kind`
+
+- `@sql`: **physical-only** (Step 1, decisive) — the body changes no native type and no logical meaning; the projection's declared fields still type the read model and the wire contract is untouched. It is a pure physical-DDL payload, the same category as the existing `@where`/`@expr` raw-SQL escapes. Not a subtype (still an RDB view, no distinct native type/behavior/child vocabulary); not a `@kind` (a hand-bodied view is still `@kind: view` — DDL-provenance is a *second* axis, and folding it into `@kind` makes `@kind` the ADR-0037-forbidden catch-all). Name `@sql` (not `@sqlView`, which is view-specific and self-contradictory on a matview; not `@ddl`, which implies the full `CREATE` wrapper; not `@body`) generalizes by pattern — a future non-RDB paradigm subtype registers its own body attr.
+- `@unmanaged`: tool-lifecycle **configuration** → attribute (Step 2c). A boolean exception-flag (the common case is absent). Rejected `@managed: false` (2c forbids a default-true opt-out) and an enum (`@lifecycle`), since the "supplied" state is already carried by `@sql`'s presence.
+
+### 3. The suppression rule (the load-bearing, non-deferrable piece)
+
+An `@sql`- or `@unmanaged`-marked read source **suppresses derivation-classification entirely**: DDL-ownership is classified **before** `viewIsDerived`. This is what lets an escape-valve host legally carry `extends`-bound fields and a borrowed `identity.primary { extends: "Base.id" }` as pure shape / row-identity declarations *without* the tool mis-synthesizing a body. ADR-0028's "self-declared under external assembly" already licenses these declarations — no ADR-0028 change needed.
+
+### 4. Cross-port scope split
+
+- **All five ports** (TS / C# / Java / Kotlin / Python): register the two attrs on `source.rdb`; resolving `MetaSource` accessors (`sqlBody`/`isUnmanaged` etc., following the `@role`/`effectiveKind` *resolving* precedent — **not** the `@dbColumnType` own-only exception, ADR-0039); and the six fail-closed loader-validation rules (§5), conformance-gated by shared `fixtures/conformance/` error-fixtures.
+- **TS-only** (ADR-0015 — schema is TS-owned): all migrate/verify *lowering* — the `@sql` verbatim-emit + fingerprint + adopt-view ceremony, and the `@unmanaged` skip + act-side silencing.
+
+### 5. Loader validation — six fail-closed rules (cross-port)
+
+| # | Rule | Code |
+|---|------|------|
+| R1 | `@sql` **and** `@unmanaged` on the same source | `ERR_SQL_BODY_WITH_UNMANAGED` |
+| R2 | `@sql` on a writable `@kind` (`table`) | `ERR_SQL_BODY_ON_WRITABLE_KIND` |
+| R3 | `@sql` present but empty/whitespace | `ERR_BAD_ATTR_VALUE` |
+| R4 | `origin.*`-bearing field under an `@sql` host | `ERR_ORIGIN_UNDER_SQL_BODY` |
+| R5 | `object.projection` `@filter` (#207) + `@sql` host | `ERR_ORIGIN_UNDER_SQL_BODY` |
+| R6 | `origin.*`-bearing field under an `@unmanaged` host | **WARN** `WARN_ORIGIN_UNDER_UNMANAGED` |
+
+The R4-error / R6-warn asymmetry is deliberate: `@sql` is a second body (two sources of truth for the *same* data); `@unmanaged` acts on nothing, so a documented-but-unacted-on lineage is benign. `@sql` (R4) takes priority over `@unmanaged` (R6) when a host declares both markers across different sources.
+
+### 6. Migrate lowering (TS-only)
+
+- **`@sql`** rides the *existing* pipeline: push a verbatim `ExpectedView` (`name`=physicalName, `sql`=the verbatim body, `dependsOn`=the `extends`-bound anchor tables, `columns` **omitted**). `buildExpectedSchema` fingerprints `v.sql`; emit stamps the COMMENT marker; an absent `columns` makes the diff fail safe to a gated drop+create instead of a wrong `CREATE OR REPLACE`. A pre-existing **unstamped** view at the name is `replace-view` **blocked pending `migrate --allow adopt-view`** — the one-time adoption ceremony. `@sql` on a non-`view` kind (matview/proc/tableFunction) is an actionable hard error (D4 — not yet migrate-managed).
+- **`@unmanaged`** is excluded from both sides: skipped from `expected` (views in `build-projection-views`; tables in `buildExpectedSchema` Pass 1, **but kept in `entityToTable`** so an inbound FK resolves the external table's physical name), and excluded from the introspected `actual` via a `collectUnmanagedNames` set threaded from every diff entry point (online, offline `planOffline`, D1, and `verify`'s `computeDrift`). Net: a declared-external object produces **silence**, not a policy-gated drop. `verify --db` annotates it "external (declared)".
+
+## Consequences
+
+- A genuinely-irreducible view is now **managed-but-opaque**: `meta migrate` owns its lifecycle (emit / fingerprint-drift / gated drop) without ever parsing its body, and the one-time `--allow adopt-view` ceremony adopts a pre-existing hand-written view.
+- The "generalizes to any object" half falls out for free: `@unmanaged` on a `@kind: table` is the Flyway-owned-entity case.
+- **Documented adopter caveats (not errors):**
+  - An FK *from a managed table into an `@unmanaged` table* has no migration-**ordering** guarantee versus the external tool — the external object must exist before the managed FK is applied.
+  - An `@unmanaged` view is **not** drop/recreated around a managed dependency's column-altering `ALTER` — the tool has no body for an external view and cannot recreate it; Postgres blocking the `ALTER` is the adopter's signal to coordinate.
+- **Deferred follow-ups (filed on the roadmap):**
+  - **`@dependsOn` for `@sql` views** — a `@sql` view's `dependsOn` is derived from `extends`-bound anchors only, so a table the opaque body JOINs but does not surface as a bound column is not tracked for auto-recreate around a column `ALTER` (§11 YAGNI — defer the explicit `@dependsOn` attr until an adopter hits it).
+  - **The matview managed path** — `@sql` on `@kind: materializedView` needs `pg_matviews` introspection + COMMENT-on-matview plumbing + a REFRESH story.
+  - **Opaque-body column-name verification** — PG exposes an `@sql` view's output columns via `information_schema.columns`, so `verify` could eventually column-name-check an opaque body against the declared field set.