feat(#208): Java @sql/@Unmanaged accessors + loader validation

dmealing · claude · dmealing · commit bbf51f2862c6 · 2026-07-17T21:29:30.000-04:00
Task 7 — the Java port of the DDL-ownership escape-valve validation, mirroring the TS reference (validate-source-escapes.ts). - MetaSource.java: resolving getSqlBody() (String, empty→null) + isUnmanaged() (boolean) accessors (ADR-0039 resolving, matching getEffectiveKind()/getRole(); read RdbSource.ATTR_SQL/ATTR_UNMANAGED registered in Task 1). - ValidationPhase.java: validateSourceEscapes implementing the six fail-closed rules R1–R6, wired right after validateOnePrimarySource (the source-roles pass). Same codes as TS: ERR_SQL_BODY_WITH_UNMANAGED, ERR_SQL_BODY_ON_WRITABLE_KIND, ERR_BAD_ATTR_VALUE (R3), ERR_ORIGIN_UNDER_SQL_BODY (R4+R5), WARN_ORIGIN_UNDER_UNMANAGED (R6, envelope warning). R4 (error) beats R6 (warn); R3 reads the raw attr. Fail-fast throw wrapped by pass() — the Java loader idiom. - ErrorCode.java + ErrorMessageConstants.java: the three new codes + the WARN code. - Issue208SourceEscapeValidationTest.java: 8 TDD tests (5 errors + R6 warn + a positive @SQL view projection), confirmed red before implementing. Kotlin rides Java's JVM registry (no separate change). Registration was Task 1; migrate/verify lowering is TS-only (ADR-0015). Scoped test 8/8; full `mvn -pl metadata test` 1183/1183. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NGQ7oSuNcjhsMHWwZzhBwr
diff --git a/server/java/metadata/src/main/java/com/metaobjects/ErrorCode.java b/server/java/metadata/src/main/java/com/metaobjects/ErrorCode.java
@@ -382,6 +382,32 @@ public enum ErrorCode {
      */
     ERR_COMPUTED_TYPE_MISMATCH,
 
+    /**
+     * #208 (DDL-ownership escape valves, design doc §5 R1): a {@code source.rdb}
+     * declares both {@code @sql} and {@code @unmanaged} — the two mutually
+     * exclusive non-default states of one DDL-ownership axis (an author-supplied
+     * body contradicts "someone else owns this DDL").
+     */
+    ERR_SQL_BODY_WITH_UNMANAGED,
+
+    /**
+     * #208 (design doc §5 R2): a {@code source.rdb} declares {@code @sql} with a
+     * writable {@code @kind} ("table", the default) — {@code @sql} is legal only
+     * on a read-only kind (view/materializedView/storedProc/tableFunction); a
+     * writable table is either fully modeled or marked {@code @unmanaged}, never
+     * opaque-bodied.
+     */
+    ERR_SQL_BODY_ON_WRITABLE_KIND,
+
+    /**
+     * #208 (design doc §5 R4/R5): a field carrying an {@code origin.*} (derived)
+     * child — or, for an {@code object.projection}, a row-scope {@code @filter}
+     * (#207) — lives under a host object that declares an {@code @sql} read
+     * source. The synthesized derivation/filter and the author's verbatim SQL
+     * body are two sources of truth for the same data.
+     */
+    ERR_ORIGIN_UNDER_SQL_BODY,
+
     /** An internal loader error with no stable error code. */
     ERR_UNKNOWN,
 }
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java b/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java
@@ -179,6 +179,9 @@ public static void run(MetaRoot root, MetaDataLoader loader) {
         // FR-015 — source.rdb @parameterRef typed-input rules.
         pass(collected, () -> validateSourceParameterRef(root));
         pass(collected, () -> validateOnePrimarySource(root));
+        // #208 — DDL-ownership escape valves (@sql/@unmanaged on source.rdb).
+        // Sibling of the source-role pass above; must run after it.
+        pass(collected, () -> validateSourceEscapes(root, loader));
         pass(collected, () -> validateRelationshipReferentialActions(root));
         pass(collected, () -> validateRelationshipsM2M(root));
         // ADR-0042 — the cross-package ambiguity pass (ERR_AMBIGUOUS_REF) is RETIRED. A bare
@@ -1063,6 +1066,142 @@ private static void validateObjectPrimarySource(MetaObject obj) {
         }
     }
 
+    // =========================================================================
+    // #208 — DDL-ownership escape valves (@sql / @unmanaged on source.rdb).
+    //
+    // source.rdb has two mutually exclusive, non-default DDL-ownership markers:
+    // @sql (a hand-written body the tool registers/fingerprints/drift-checks but
+    // never authors or parses) and @unmanaged (this object's DDL is owned
+    // elsewhere — the tool never touches it). Six fail-closed rules (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 own 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 own field under an @unmanaged host → WARN_ORIGIN_UNDER_UNMANAGED
+    //
+    // R1–R3 are per-source (declaration-layer, own-only). 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). @sql (R4, hard error) takes priority
+    // over @unmanaged (R6, warn) when a host declares both markers across different
+    // sources. Mirrors TS validate-source-escapes.ts.
+    // =========================================================================
+
+    static void validateSourceEscapes(MetaRoot root, MetaDataLoader loader) {
+        for (MetaData rootChild : root.getChildren(MetaData.class, false)) {
+            if (!(rootChild instanceof MetaObject)) continue;
+            validateObjectSourceEscapes((MetaObject) rootChild, loader);
+        }
+    }
+
+    private static void validateObjectSourceEscapes(MetaObject obj, MetaDataLoader loader) {
+        // ADR-0039: own — declaration-layer source iteration (mirrors
+        // validateObjectSourcePhysicalNames / validateObjectPrimarySource): R1–R3
+        // judge markers DECLARED on this object's own sources.
+        List<RdbSource> sources = obj.getChildren(RdbSource.class, false);
+
+        boolean hasSqlHost = false;
+        boolean hasUnmanagedHost = false;
+
+        for (RdbSource source : sources) {
+            // ADR-0039: resolving — @sql/@unmanaged are inheritable (follow the
+            // @role/effectiveKind precedent — sources are inheritable, NOT the
+            // @dbColumnType own-only exception).
+            boolean sqlSet = source.getSqlBody() != null;
+            boolean unmanagedSet = source.isUnmanaged();
+
+            // R1 — contradictory DDL owners on the same source.
+            if (sqlSet && unmanagedSet) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_SQL_BODY_WITH_UNMANAGED
+                        + ": source.rdb on object \"" + obj.getName()
+                        + "\" 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\")",
+                    ErrorCode.ERR_SQL_BODY_WITH_UNMANAGED, source.getSource());
+            }
+
+            // 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()) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_SQL_BODY_ON_WRITABLE_KIND
+                        + ": source.rdb on object \"" + obj.getName()
+                        + "\" declares @sql with a writable @kind (\"" + source.getEffectiveKind()
+                        + "\") — @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",
+                    ErrorCode.ERR_SQL_BODY_ON_WRITABLE_KIND, source.getSource());
+            }
+
+            // R3 — @sql present but empty/whitespace. MUST read the raw attr, not
+            // getSqlBody(): getSqlBody() already narrows an empty string to null,
+            // which would make a present-but-empty @sql indistinguishable from an
+            // absent one.
+            if (source.hasMetaAttr(RdbSource.ATTR_SQL)) {
+                String rawSql = source.getMetaAttr(RdbSource.ATTR_SQL).getValueAsString();
+                if (rawSql == null || rawSql.trim().isEmpty()) {
+                    throw new MetaDataException(
+                        ErrorMessageConstants.ERR_BAD_ATTR_VALUE
+                            + ": source.rdb on object \"" + obj.getName()
+                            + "\" sets @sql to an empty/whitespace-only value; @sql requires a "
+                            + "non-empty SQL body",
+                        ErrorCode.ERR_BAD_ATTR_VALUE, source.getSource());
+                }
+            }
+
+            if (sqlSet) hasSqlHost = true;
+            if (unmanagedSet) hasUnmanagedHost = true;
+        }
+
+        if (!hasSqlHost && !hasUnmanagedHost) return;
+
+        // 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 (MetaField<?> field : obj.getChildren(MetaField.class, false)) {
+            if (!field.isDerived()) continue;
+            if (hasSqlHost) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_ORIGIN_UNDER_SQL_BODY
+                        + ": field \"" + obj.getName() + "." + field.getName()
+                        + "\" carries an origin.* (derived) child, but \"" + obj.getName()
+                        + "\" has a read source carrying @sql — the synthesized derivation and "
+                        + "the author's verbatim SQL are two sources of truth for the same body",
+                    ErrorCode.ERR_ORIGIN_UNDER_SQL_BODY, field.getSource());
+            } else if (loader != null) {
+                loader.addEnvelopeWarning(new LoaderWarning(
+                    ErrorMessageConstants.WARN_ORIGIN_UNDER_UNMANAGED,
+                    "field \"" + obj.getName() + "." + field.getName()
+                        + "\" carries an origin.* (derived) child, but \"" + obj.getName()
+                        + "\" 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",
+                    field.getSource()));
+            }
+        }
+
+        // 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 && MetaObject.SUBTYPE_PROJECTION.equals(obj.getSubType())) {
+            // ADR-0039: own — the @filter is declared locally on this projection
+            // (mirrors validateProjectionFilter).
+            if (obj.hasMetaAttr(MetaObject.ATTR_FILTER, false)) {
+                throw new MetaDataException(
+                    ErrorMessageConstants.ERR_ORIGIN_UNDER_SQL_BODY
+                        + ": projection \"" + obj.getName()
+                        + "\" 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",
+                    ErrorCode.ERR_ORIGIN_UNDER_SQL_BODY, obj.getSource());
+            }
+        }
+    }
+
     // =========================================================================
     // Relationship @onDelete / @onUpdate enum validation
     //
diff --git a/server/java/metadata/src/main/java/com/metaobjects/source/MetaSource.java b/server/java/metadata/src/main/java/com/metaobjects/source/MetaSource.java
@@ -231,6 +231,37 @@ public String getSchema() {
             : null;
     }
 
+    /**
+     * FR-024/#208 — the hand-written SQL body for this source's DB object, when
+     * declared via {@code @sql}, narrowed to a non-empty string (empty string →
+     * {@code null}, treated as absent; a whitespace-only value is still "set" —
+     * loader validation independently rejects it via {@code ERR_BAD_ATTR_VALUE}).
+     * The tool registers + fingerprints + drift-checks this body but never
+     * authors or parses it. {@code @sql} is registered on the concrete
+     * {@code source.rdb} subtype ({@link RdbSource#ATTR_SQL}).
+     */
+    public String getSqlBody() {
+        // ADR-0039: resolving — an inherited source's @sql lives on the super node
+        // (matches getEffectiveKind()/getRole()/getTableName() above).
+        if (!hasMetaAttr(RdbSource.ATTR_SQL)) return null;
+        String v = getMetaAttr(RdbSource.ATTR_SQL).getValueAsString();
+        return (v != null && !v.isEmpty()) ? v : null;
+    }
+
+    /**
+     * FR-024/#208 — {@code true} when this source's DB object is managed
+     * elsewhere (Flyway / a hand-migration owns its DDL); {@code meta migrate}
+     * does not create/drop/drift-check it. {@code @unmanaged} is registered on
+     * the concrete {@code source.rdb} subtype ({@link RdbSource#ATTR_UNMANAGED}).
+     */
+    public boolean isUnmanaged() {
+        // ADR-0039: resolving — an inherited source's @unmanaged lives on the
+        // super node (matches getEffectiveKind()/getRole()/getTableName() above).
+        if (!hasMetaAttr(RdbSource.ATTR_UNMANAGED)) return false;
+        Object v = getMetaAttr(RdbSource.ATTR_UNMANAGED).getValue();
+        return Boolean.TRUE.equals(v);
+    }
+
     /**
      * FR-016 / ADR-0018: resolved physical SQL name for this source, following
      * the four-step rule:
diff --git a/server/java/metadata/src/main/java/com/metaobjects/util/ErrorMessageConstants.java b/server/java/metadata/src/main/java/com/metaobjects/util/ErrorMessageConstants.java
@@ -223,6 +223,38 @@ private ErrorMessageConstants() {
      */
     public static final String ERR_INVALID_INDEX = "ERR_INVALID_INDEX";
 
+    /**
+     * #208 (DDL-ownership escape valves, design doc §5 R1): a {@code source.rdb}
+     * declares both {@code @sql} and {@code @unmanaged} on the same source.
+     * Cross-language contract: {@code ERR_SQL_BODY_WITH_UNMANAGED}.
+     */
+    public static final String ERR_SQL_BODY_WITH_UNMANAGED = "ERR_SQL_BODY_WITH_UNMANAGED";
+
+    /**
+     * #208 (design doc §5 R2): a {@code source.rdb} declares {@code @sql} with a
+     * writable {@code @kind} ("table", the default) — {@code @sql} is legal only
+     * on a read-only kind.
+     * Cross-language contract: {@code ERR_SQL_BODY_ON_WRITABLE_KIND}.
+     */
+    public static final String ERR_SQL_BODY_ON_WRITABLE_KIND = "ERR_SQL_BODY_ON_WRITABLE_KIND";
+
+    /**
+     * #208 (design doc §5 R4/R5): an {@code origin.*}-bearing (derived) own field,
+     * or an {@code object.projection}'s row-scope {@code @filter} (#207), lives
+     * under a host object that declares an {@code @sql} read source.
+     * Cross-language contract: {@code ERR_ORIGIN_UNDER_SQL_BODY}.
+     */
+    public static final String ERR_ORIGIN_UNDER_SQL_BODY = "ERR_ORIGIN_UNDER_SQL_BODY";
+
+    /**
+     * #208 (design doc §5 R6) warning: an {@code origin.*}-bearing (derived) own
+     * field lives under a host object that declares an {@code @unmanaged} source.
+     * {@code @unmanaged} acts on nothing, so documented-but-unacted-on lineage is
+     * benign — informational only, never an error.
+     * Cross-language contract: {@code WARN_ORIGIN_UNDER_UNMANAGED}.
+     */
+    public static final String WARN_ORIGIN_UNDER_UNMANAGED = "WARN_ORIGIN_UNDER_UNMANAGED";
+
     // === ERROR MESSAGE FORMATS ===
 
     /** Format template for not found errors */
diff --git a/server/java/metadata/src/test/java/com/metaobjects/source/Issue208SourceEscapeValidationTest.java b/server/java/metadata/src/test/java/com/metaobjects/source/Issue208SourceEscapeValidationTest.java
