feat(#208): TS loader validation for @sql/@Unmanaged (6 fail-closed rules)

Task 3 — validate-source-escapes.ts (sibling of validate-source-roles.ts),
wired into the load pipeline. The six rules from design §5:
- R1 @SQL AND @Unmanaged on one 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 (reads the RAW
     attr, not the sqlBody accessor which already narrows empty→undefined)
- 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_ORIGIN_UNDER_UNMANAGED
The R4-error / R6-warn asymmetry is deliberate (§5.6): @SQL is a second body
(two sources of truth); @Unmanaged acts on nothing, so a documented-but-
unacted-on lineage is benign. ADR-0039 own/resolving discipline applied.

Three ERR codes + one WARN code added to errors.ts + the TS-owned
fixtures/conformance/ERROR-CODES.json manifest (the other ports do not gate on
it — Python conformance green with the change). TS-only per the plan; the 4-port
validation mirror lands in Tasks 7–9.

Gated by validate-source-escapes.test.ts (one case per rule); full metadata
suite 2195/2195 + typecheck clean; the Task-1 positive source-sql-escape fixture
still passes (its shapes are legal). Deep review folded into the post-Task-6
TS-reference checkpoint.

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

Author: dmealing

fixtures/conformance/ERROR-CODES.json

@@ -69,6 +69,9 @@
     "ERR_INVALID_METAMODEL_CONSTRAINT": "FR-033: a provider set's merged metamodel constraint graph contains a contradiction surfaced by validateConstraints — one of: (1) a parents/children rule references an unregistered type.subType (dangling); (2) a required child (min>=1) whose type.subType is not admitted under that parent (unsatisfiable); (3) bad cardinality (min>max, max:0 with min>=1, or min<0); (4) closed-set clash — a child declares a parent whose OWN children is a closed set (no * wildcard) that does not admit it; (5) a required-child cycle that cannot bottom out; (6) the same attr name contributed twice (across providers or the extends chain) with a conflicting valueType/required/default. The detail names which check and the offending type(s).",
     "ERR_INVALID_INDEX": "An index.lookup's @fields is empty (at least one field is required) or names a field that does not exist on the owning entity's effective (resolved, via extends) field set.",
     "ERR_COMPUTED_TYPE_MISMATCH": "#195: an origin.computed @expr tree's inferred root type does not equal the carrying field's declared field.<subType>. A computed column's type is DERIVED from its expression, never asserted (no @convert escape), so a mismatch is a hard load error (sibling of ERR_PASSTHROUGH_TYPE_MISMATCH).",
-    "ERR_UNKNOWN_EXPR_NODE": "#195: an origin.computed @expr tree contains a node whose kind/op/fn is not in the closed expression grammar (field/value refs, comparisons sharing the filter op vocabulary, isNull/isNotNull, and/or/not, coalesce). Fail-closed per ADR-0023; the detail names the offending token."
+    "ERR_UNKNOWN_EXPR_NODE": "#195: an origin.computed @expr tree contains a node whose kind/op/fn is not in the closed expression grammar (field/value refs, comparisons sharing the filter op vocabulary, isNull/isNotNull, and/or/not, coalesce). Fail-closed per ADR-0023; the detail names the offending token.",
+    "ERR_SQL_BODY_WITH_UNMANAGED": "#208: a source.rdb declares both @sql (author-supplied body) and @unmanaged (DDL owned elsewhere). The two markers are the mutually exclusive non-default states of one DDL-ownership axis — contradictory on a single source.",
+    "ERR_SQL_BODY_ON_WRITABLE_KIND": "#208: a source.rdb declares @sql with a writable @kind (\"table\", the default). A hand-written CREATE TABLE would bypass the column-diff machinery; tables are fully modeled or @unmanaged, never opaque-bodied.",
+    "ERR_ORIGIN_UNDER_SQL_BODY": "#208: a host object whose read source carries @sql also declares an origin.*-bearing (derived) field, or (on object.projection) an @filter (#207) — two sources of truth for the same body (the synthesized derivation/outer-WHERE vs. the author's verbatim SQL). Fail-closed."
   }
 }

server/typescript/packages/metadata/src/errors.ts

@@ -178,6 +178,19 @@ export const ERROR_CODES = [
   // #195 — origin.computed @expr contains a node whose kind/op/fn is not in the
   // closed expression grammar (ADR-0023 fail-closed). Detail names the bad token.
   "ERR_UNKNOWN_EXPR_NODE",
+  // #208 — a source.rdb declares BOTH @sql (author-supplied body) and
+  // @unmanaged (DDL owned elsewhere). The two markers are the mutually
+  // exclusive non-default states of one "who owns this DDL" axis.
+  "ERR_SQL_BODY_WITH_UNMANAGED",
+  // #208 — a source.rdb declares @sql with a writable @kind ("table", the
+  // default). A hand-written CREATE TABLE would bypass the column-diff
+  // machinery; tables are fully modeled or @unmanaged, never opaque-bodied.
+  "ERR_SQL_BODY_ON_WRITABLE_KIND",
+  // #208 — a host object whose read source carries @sql also declares an
+  // origin.*-bearing (derived) field, or (on object.projection) an @filter —
+  // two sources of truth for the same body (the synthesized derivation/WHERE
+  // vs. the author's verbatim SQL). Fail-closed.
+  "ERR_ORIGIN_UNDER_SQL_BODY",
   "ERR_UNKNOWN",
 ] as const;
 
@@ -197,6 +210,13 @@ export const WARNING_CODES = [
   // implication does not apply to value-objects; the attr is retained for
   // language-specific record/struct treatment (e.g. Kotlin `val` vs `var`).
   "WARN_READONLY_VALUE_OBJECT",
+  // #208 — a host object whose source carries @unmanaged also declares an
+  // origin.*-bearing (derived) field. Deliberate asymmetry with
+  // ERR_ORIGIN_UNDER_SQL_BODY: @unmanaged acts on nothing (the tool never
+  // touches the object's DDL), so a documented-but-unacted-on lineage is
+  // benign — a WARN preserves the matview symmetry and lets an author
+  // document lineage for future in-process evaluation (#211).
+  "WARN_ORIGIN_UNDER_UNMANAGED",
 ] as const;
 export type WarningCode = (typeof WARNING_CODES)[number];
 

server/typescript/packages/metadata/src/loader/meta-data-loader.ts

@@ -21,6 +21,7 @@ import { parseJson } from "../parser-json.js";
 import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
+import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
 import { validateSourcePhysicalNames } from "../persistence/source/validate-source-physical-names.js";
 import { validateSourceParameterRef } from "../persistence/source/validate-source-parameter-ref.js";
 import { validateFieldReadOnly } from "../core/field/validate-field-readonly.js";
@@ -635,6 +636,13 @@ export class MetaDataLoader {
       // ERR_SOURCE_MULTIPLE_PRIMARY).
       errors.push(...validateSourceRoles(root));
 
+      // #208 — DDL-ownership escape valves: source.rdb @sql / @unmanaged
+      // fail-closed rules (ERR_SQL_BODY_WITH_UNMANAGED / ERR_SQL_BODY_ON_WRITABLE_KIND /
+      // ERR_BAD_ATTR_VALUE / ERR_ORIGIN_UNDER_SQL_BODY / WARN_ORIGIN_UNDER_UNMANAGED).
+      const sourceEscapeResult = validateSourceEscapes(root);
+      errors.push(...sourceEscapeResult.errors);
+      envelopeWarnings.push(...sourceEscapeResult.warnings);
+
       // FR-016 / ADR-0018 — per-kind physical-name alias validation on
       // source.rdb (kind-matching alias, no multiples, legacy @table warning).
       const physicalNameResult = validateSourcePhysicalNames(root);

server/typescript/packages/metadata/src/persistence/source/validate-source-escapes.ts

@@ -0,0 +1,158 @@
+// Validation pass: DDL-ownership escape valves (#208) — @sql / @unmanaged on
+// source.rdb. Sibling of validate-source-roles.ts / validate-source-physical-names.ts.
+//
+// #208 gives source.rdb two mutually exclusive, non-default DDL-ownership
+// markers: @sql (a hand-written body the tool registers/fingerprints/drift-
+// checks but never authors) and @unmanaged (this object's DDL is owned
+// elsewhere — the tool never touches it). This pass enforces the six
+// fail-closed rules from the design doc (§5):
+//
+//   R1  @sql AND @unmanaged on the SAME source          → ERR_SQL_BODY_WITH_UNMANAGED
+//   R2  @sql on a writable @kind ("table", the default)  → ERR_SQL_BODY_ON_WRITABLE_KIND
+//   R3  @sql present but empty / whitespace-only         → 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_ORIGIN_UNDER_UNMANAGED
+//
+// R1–R3 are per-source (declaration-layer). R4–R6 are per-host-object: a host
+// with ANY own source.rdb carrying @sql/@unmanaged is judged against its own
+// fields (and, for R5, its own @filter). The asymmetry between R4 (hard error)
+// and R6 (warn) is deliberate (design doc §5.6): @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.
+
+import type { MetaData } from "../../shared/meta-data.js";
+import { ParseError } from "../../errors.js";
+import type { LoaderWarning } from "../../source.js";
+import { TYPE_OBJECT, TYPE_SOURCE, TYPE_FIELD } from "../../shared/base-types.js";
+import { OBJECT_SUBTYPE_PROJECTION, OBJECT_PROJECTION_ATTR_FILTER } from "../../core/object/object-constants.js";
+import { MetaSource } from "./meta-source.js";
+import { MetaField } from "../../core/field/meta-field.js";
+import { SOURCE_ATTR_SQL, SOURCE_SUBTYPE_RDB } from "./source-constants.js";
+
+export interface SourceEscapeValidationResult {
+  errors: ParseError[];
+  warnings: LoaderWarning[];
+}
+
+export function validateSourceEscapes(root: MetaData): SourceEscapeValidationResult {
+  const errors: ParseError[] = [];
+  const warnings: LoaderWarning[] = [];
+
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // ADR-0039: own — declaration-layer source iteration (mirrors validateSourceRoles /
+    // validateSourceParameterRef): R1–R3 judge markers DECLARED on this object's own sources.
+    const sources = obj
+      .ownChildren()
+      .filter(
+        (c): c is MetaSource =>
+          c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_RDB && c instanceof MetaSource,
+      );
+
+    let hasSqlHost = false;
+    let hasUnmanagedHost = false;
+
+    for (const source of sources) {
+      // ADR-0039: resolving — @sql/@unmanaged are inheritable (follow the
+      // @role/effectiveKind precedent — sources are inheritable, NOT the
+      // @dbColumnType own-only exception).
+      const sqlSet = source.sqlBody !== undefined;
+      const unmanagedSet = source.isUnmanaged;
+
+      // R1 — contradictory DDL owners on the same source.
+      if (sqlSet && unmanagedSet) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" declares both @sql and @unmanaged — these are the ` +
+              `mutually exclusive non-default states of one DDL-ownership axis (an author-supplied body ` +
+              `contradicts "someone else owns this DDL")`,
+            { code: "ERR_SQL_BODY_WITH_UNMANAGED", source: source.source },
+          ),
+        );
+      }
+
+      // R2 — @sql on a writable kind would bypass the column-diff machinery;
+      // tables are fully modeled or @unmanaged, never opaque-bodied.
+      if (sqlSet && source.isWritable()) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" declares @sql with a writable @kind ("${source.effectiveKind}") — ` +
+              `@sql is legal only on a read-only kind (view/materializedView/storedProc/tableFunction); ` +
+              `a writable table is either fully modeled or marked @unmanaged, never opaque-bodied`,
+            { code: "ERR_SQL_BODY_ON_WRITABLE_KIND", source: source.source },
+          ),
+        );
+      }
+
+      // R3 — @sql present but empty/whitespace. MUST read the raw attr, not
+      // the sqlBody accessor: sqlBody already narrows an empty string to
+      // undefined, which would make a present-but-empty @sql indistinguishable
+      // from an absent one.
+      const rawSql = source.attr(SOURCE_ATTR_SQL);
+      if (rawSql !== undefined && (typeof rawSql !== "string" || rawSql.trim() === "")) {
+        errors.push(
+          new ParseError(
+            `source.rdb on object "${obj.name}" sets @sql to an empty/whitespace-only value; ` +
+              `@sql requires a non-empty SQL body`,
+            { code: "ERR_BAD_ATTR_VALUE", source: source.source },
+          ),
+        );
+      }
+
+      if (sqlSet) hasSqlHost = true;
+      if (unmanagedSet) hasUnmanagedHost = true;
+    }
+
+    if (!hasSqlHost && !hasUnmanagedHost) continue;
+
+    // R4 / R6 — origin.*-bearing (derived) own fields under an @sql / @unmanaged
+    // host. ADR-0039: own — origin.* never inherits (ADR-0029), so isDerived()
+    // is own-only by policy (mirrors validateDerivedFieldProvidability).
+    // @sql (hard error) takes priority over @unmanaged (warn) when a host
+    // happens to declare both markers across different sources.
+    for (const field of obj.ownChildren().filter((c): c is MetaField => c.type === TYPE_FIELD && c instanceof MetaField)) {
+      if (!field.isDerived()) continue;
+      if (hasSqlHost) {
+        errors.push(
+          new ParseError(
+            `field "${obj.name}.${field.name}" carries an origin.* (derived) child, but "${obj.name}" has a ` +
+              `read source carrying @sql — the synthesized derivation and the author's verbatim SQL are two ` +
+              `sources of truth for the same body`,
+            { code: "ERR_ORIGIN_UNDER_SQL_BODY", source: field.source },
+          ),
+        );
+      } else {
+        warnings.push({
+          code: "WARN_ORIGIN_UNDER_UNMANAGED",
+          message:
+            `field "${obj.name}.${field.name}" carries an origin.* (derived) child, but "${obj.name}" has a ` +
+            `source marked @unmanaged — the tool never touches this object's DDL, so the derivation is ` +
+            `documented lineage only (not acted on); this is informational, not an error`,
+          source: field.source,
+        });
+      }
+    }
+
+    // R5 — a projection's row-scope @filter (#207) lowers to the outer WHERE
+    // of a TOOL-SYNTHESIZED body; with @sql the author owns the body (and its
+    // WHERE), so wrapping it is deferred cleverness (design doc D5) — reject.
+    if (hasSqlHost && obj.subType === OBJECT_SUBTYPE_PROJECTION) {
+      // ADR-0039: own — the @filter is declared locally on this projection
+      // (mirrors validateProjectionFilter).
+      const filter = obj.ownAttr(OBJECT_PROJECTION_ATTR_FILTER);
+      if (filter !== undefined) {
+        errors.push(
+          new ParseError(
+            `projection "${obj.name}" declares both @filter and an @sql read source — a view-level @filter ` +
+              `lowers to the outer WHERE of a synthesized body; with @sql the author owns the body (and its ` +
+              `WHERE), so the two cannot be combined`,
+            { code: "ERR_ORIGIN_UNDER_SQL_BODY", source: obj.source },
+          ),
+        );
+      }
+    }
+  }
+
+  return { errors, warnings };
+}

server/typescript/packages/metadata/test/validate-source-escapes.test.ts

@@ -0,0 +1,129 @@
+// #208 — DDL-ownership escape valves loader validation (§5 R1–R6).
+// One test per rule: R1–R5 are hard errors, R6 is a WARN (not an error).
+
+import { describe, expect, test } from "bun:test";
+import { MetaDataLoader } from "../src/loader/meta-data-loader.js";
+import { InMemoryStringSource } from "../src/loader/meta-data-source.js";
+
+async function loadDoc(doc: unknown) {
+  return new MetaDataLoader().load([new InMemoryStringSource(JSON.stringify(doc))]);
+}
+const codesOf = (errors: readonly Error[]) => errors.map((e) => (e as { code?: string }).code);
+
+describe("#208 source escape validation (@sql / @unmanaged)", () => {
+  test("R1: @sql AND @unmanaged on one source → ERR_SQL_BODY_WITH_UNMANAGED", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.projection": { name: "H", children: [
+          { "source.rdb": { "@kind": "view", "@view": "v", "@sql": "SELECT 1", "@unmanaged": true } },
+          { "field.long": { name: "id" } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_SQL_BODY_WITH_UNMANAGED");
+  });
+
+  test("R2: @sql on @kind:table (writable, default) → ERR_SQL_BODY_ON_WRITABLE_KIND", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.entity": { name: "H", children: [
+          { "source.rdb": { "@table": "t", "@sql": "SELECT 1" } },
+          { "field.long": { name: "id" } },
+          { "identity.primary": { name: "id", "@fields": ["id"] } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_SQL_BODY_ON_WRITABLE_KIND");
+  });
+
+  test("R3: @sql present but empty string → ERR_BAD_ATTR_VALUE", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.projection": { name: "H", children: [
+          { "source.rdb": { "@kind": "view", "@view": "v", "@sql": "" } },
+          { "field.long": { name: "id" } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_BAD_ATTR_VALUE");
+  });
+
+  test("R3b: @sql present but whitespace-only → ERR_BAD_ATTR_VALUE", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.projection": { name: "H", children: [
+          { "source.rdb": { "@kind": "view", "@view": "v", "@sql": "   " } },
+          { "field.long": { name: "id" } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_BAD_ATTR_VALUE");
+  });
+
+  test("R4: origin.* under an @sql host → ERR_ORIGIN_UNDER_SQL_BODY", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.entity": { name: "Base", children: [
+          { "field.long": { name: "id" } },
+          { "field.string": { name: "title" } },
+          { "identity.primary": { name: "id", "@fields": "id" } },
+        ] } },
+        { "object.projection": { name: "H", children: [
+          { "source.rdb": { "@kind": "view", "@view": "v_h", "@sql": "SELECT id, title FROM base" } },
+          { "field.long": { name: "id", extends: "acme::Base.id" } },
+          { "field.string": { name: "displayTitle", children: [
+            { "origin.passthrough": { "@from": "acme::Base.title" } },
+          ] } },
+          { "identity.primary": { name: "id", extends: "acme::Base.id" } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_ORIGIN_UNDER_SQL_BODY");
+  });
+
+  test("R5: @filter (#207) + @sql on a projection → ERR_ORIGIN_UNDER_SQL_BODY", async () => {
+    const { errors } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.entity": { name: "Order", children: [
+          { "source.rdb": { "@table": "orders" } },
+          { "field.uuid": { name: "id" } },
+          { "field.string": { name: "status" } },
+          { "identity.primary": { name: "id", "@fields": ["id"] } },
+        ] } },
+        { "object.projection": { name: "ActiveOrders", "@filter": { status: { ne: "archived" } }, children: [
+          { "source.rdb": {
+              "@kind": "view",
+              "@view": "v_active_orders",
+              "@sql": "SELECT * FROM orders WHERE status <> 'archived'",
+          } },
+          { "field.uuid": { name: "id", extends: "acme::Order.id" } },
+          { "field.string": { name: "status", extends: "acme::Order.status" } },
+          { "identity.primary": { name: "id", extends: "acme::Order.id" } },
+        ] } },
+      ] },
+    });
+    expect(codesOf(errors)).toContain("ERR_ORIGIN_UNDER_SQL_BODY");
+  });
+
+  test("R6: origin.* under an @unmanaged host → WARN, not error", async () => {
+    const { errors, warnings } = await loadDoc({
+      "metadata.root": { package: "acme", children: [
+        { "object.entity": { name: "Base", children: [
+          { "field.long": { name: "id" } },
+          { "field.string": { name: "title" } },
+          { "identity.primary": { name: "id", "@fields": "id" } },
+        ] } },
+        { "object.projection": { name: "H", children: [
+          { "source.rdb": { "@kind": "view", "@view": "v_h", "@unmanaged": true } },
+          { "field.long": { name: "id", extends: "acme::Base.id" } },
+          { "field.string": { name: "displayTitle", children: [
+            { "origin.passthrough": { "@from": "acme::Base.title" } },
+          ] } },
+          { "identity.primary": { name: "id", extends: "acme::Base.id" } },
+        ] } },
+      ] },
+    });
+    expect(errors).toEqual([]);
+    expect(warnings.map((w) => w.code)).toContain("WARN_ORIGIN_UNDER_UNMANAGED");
+  });
+});