fix(codegen-csharp,gates): an unconfigured FK is NoAction, not EF's cascade (#294, #337)

Review findings on the two preceding commits.

The serious one: establishing a relationship without an explicit DeleteBehavior
does NOT reproduce "no action". EF applies its own convention, and for a
REQUIRED foreign key that convention is Cascade — so an FK with no resolved
action (no correlated relationship, or an explicit @onDelete: "no-action") would
have made the generated context cascade-delete rows the database refuses to
orphan. Before the feature EF had no relationship at all and did nothing;
establishing one and leaving it unconfigured was a behaviour change in the
destructive direction, which is the opposite of the point. Verified against a
real EF model — it reported Cascade where the DDL says nothing — and the
integration test now pins NoAction. The unit test that asserted "no clause" was
pinning the defect and has been rewritten to say why the clause is required.

The M:N junction sides deliberately keep EF's existing convention unless the
metadata declares an action: they have been configured that way since FR-018,
and pinning them to NoAction would stop EF clearing junction rows on a tracked
delete — a behaviour change for every M:N adopter, unrelated to this issue.

Also from review:
- the junction skip is per FK COLUMN, not per entity, so a junction carrying a
  third reference of its own still gets it configured;
- that map is keyed by node identity rather than bare name, so two same-named
  entities in different packages cannot cross-suppress (ADR-0041/0042);
- the gate scans .txt as well as .md — docs/llms/ ships llms.txt and
  llms-full.txt, the files #343 landed in, which the gate built for that
  incident could not see. It immediately found a real one: the headline
  "defining metadata" example declared createdAt as a field.string carrying
  @autoset, which is registered on field.timestamp;
- the gate checks YAML, not just JSON. ADR-0006 makes YAML the authoring
  front-end and the authoring skill teaches in it, so a sigil-free YAML block
  with a retired attribute is the #337 shape exactly. Blocks are re-emitted as
  YAML so the desugar still sees bare keys; a self-test case fails if the path
  is ever skipped again;
- ERR_BAD_ATTR_FILTER was in both classification sets, making the outcome depend
  on check order.

Simplifications: the raw @onDelete/@onUpdate accessors move onto
MetaRelationship (closing a divergence from the TS SSOT, which reads them off
the node), M:N navigations are derived once instead of twice per entity, and
three sites use the memoized MetaObject.FindField.

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

Author: dmealing

CHANGELOG.md

@@ -121,13 +121,30 @@ The precedence is a **port of `migrate-ts`'s `referential-actions.ts`**, the cro
 tier for tier: reference-level `@onDelete` → a correlated sibling relationship → the
 parent-side reverse relationship, package-aware (ADR-0042), with `@through` excluded, the
 more-than-one-reference-to-the-same-target ambiguity guard, and the inferred-`set-null`-on-
-NOT-NULL satisfiability guard. Three behaviours are decided rather than inherited: a TPH
-base and subtype declaring the **same** FK configure it **once**, on the base that owns the
-shared column (a duplicate is the ambiguity the adopter was working around); an M:N
-junction's FK sides ride on the `UsingEntity` call that creates them, so the per-reference
-pass skips junction entities rather than configuring one FK twice; and a resolved
-`set-null` over a `@required` FK **warns and emits no clause**, because EF fails MODEL
-VALIDATION there and would take down the entire `DbContext` rather than one relationship.
+NOT-NULL satisfiability guard. Four behaviours are decided rather than inherited:
+
+- **An FK with no resolved action is `DeleteBehavior.NoAction`, stated explicitly.** This is
+  the one that is easy to get backwards, and a pre-merge review caught it: `no-action` IS
+  the database default and the DDL writes no `ON DELETE` clause for it, so emitting nothing
+  looks right — but EF does not read an absent `OnDelete` as "no action". It applies its own
+  convention, and for a **required** FK that convention is **`Cascade`**. Leaving the call
+  off would have made the generated context delete rows the database would have refused to
+  orphan: a destructive disagreement with the schema, introduced by the change meant to end
+  the disagreement. Confirmed against a real EF model, which reported `Cascade` where the
+  DDL says nothing.
+- **A TPH base and subtype declaring the same FK configure it once**, on the base that owns
+  the shared column — a duplicate is the ambiguity the adopter was working around.
+- **An M:N junction's two join columns ride on the `UsingEntity` call** that creates them,
+  so the per-reference pass skips *those columns* rather than the whole entity (a junction
+  carrying a third reference of its own still gets it configured). Those two keep EF's
+  existing convention unless the metadata declares an action: they have been configured that
+  way since FR-018, and pinning them to `NoAction` now would stop EF clearing junction rows
+  on a tracked delete — a behaviour change for every M:N adopter, and nothing to do with
+  this issue. The 1:N path defaults precisely because those relationships are **new** here.
+- **A resolved `set-null` over a `@required` FK warns and falls back to `NoAction`**, because
+  EF fails MODEL VALIDATION there and would take down the entire `DbContext` rather than one
+  relationship.
+
 `@onUpdate` is deliberately not surfaced — `DeleteBehavior` covers deletes only, so it
 remains a DDL-level fact.
 
@@ -294,8 +311,16 @@ worked example, the exact spelling that release turned into a load error; **#343
 `@verifiedBy` and the pre-`0.24.0` `@status` enum a full release after both went. Each was
 fixed by hand, in a different file — which is why the family recurred instead of converging.
 
-`scripts/check-doc-examples.ts` now loads every fenced JSON example under `docs/` and the
-`agent-context` skills against the **strict** registry, in the `gates` lane.
+`scripts/check-doc-examples.ts` now loads every fenced JSON **and YAML** example under
+`docs/` and the `agent-context` skills against the **strict** registry, in the `gates` lane.
+YAML is not optional coverage: ADR-0006 makes it the universal authoring front-end and the
+authoring skill teaches in it, so a sigil-free YAML block carrying a retired attribute is
+the #337 shape exactly. `.txt` is scanned alongside `.md` because `docs/llms/` ships
+`llms.txt` / `llms-full.txt` — the very files #343 landed in, which an `.md`-only sweep
+would have left invisible to the gate built for them. It found one on its first full run:
+`llms-full.txt`'s headline "defining metadata" example declared `createdAt` as a
+`field.string` carrying `@autoSet`, an attribute registered on `field.timestamp` — a broken
+model in the file whose entire audience is agents copying it.
 
 **The hard part was never extraction, it was telling a real drift from an illustration**,
 because most doc blocks are deliberately partial. The rule is the KIND of error, not a

docs/llms/llms-full.txt

@@ -229,7 +229,7 @@ metadata.root:
         children:
           - field.long:    { name: id }
           - field.string:  { name: email }
-          - field.string:  { name: createdAt, autoSet: onCreate }
+          - field.timestamp: { name: createdAt, autoSet: onCreate }
           - identity.primary: { fields: [id] }
 ```
 

scripts/check-doc-examples.ts

@@ -46,6 +46,7 @@ import { isAbsolute, join, relative } from "node:path";
 // node_modules and is not reachable from `scripts/`. The source import also means the
 // gate reads the loader as it is NOW, with no build step between edit and gate.
 import { MetaDataLoader } from "../server/typescript/packages/metadata/src/index.js";
+import type { MetaDataFormat } from "../server/typescript/packages/metadata/src/loader/meta-data-source.js";
 
 const REPO_ROOT = new URL("..", import.meta.url).pathname.replace(/\/$/, "");
 
@@ -116,7 +117,6 @@ const FAIL_CODES = new Set([
   "ERR_RELATIVE_REF_IN_CANONICAL",
   "ERR_TOO_MANY_OCCURRENCES",
   "ERR_UNKNOWN_EXPR_NODE",
-  "ERR_BAD_ATTR_FILTER",
   "ERR_YAML_COERCION",
   "ERR_MISSING_SUBTYPE",
 ]);
@@ -195,12 +195,24 @@ interface Block {
   readonly body: string;
 }
 
-function markdownFiles(dir: string, out: string[] = []): string[] {
+/** A block rendered back into something the loader will accept, in its own format. */
+interface LoadableModel {
+  readonly content: string;
+  readonly format: MetaDataFormat;
+}
+
+/**
+ * Documents that carry shipped examples. `.txt` is included deliberately: `docs/llms/`
+ * ships `llms.txt` / `llms-full.txt`, and #343 — one of the three incidents this gate
+ * exists for — landed in exactly those files. Scanning only `.md` would have left the
+ * gate blind to the surface that motivated it.
+ */
+function documentFiles(dir: string, out: string[] = []): string[] {
   for (const entry of readdirSync(dir)) {
     if (entry === "node_modules" || entry.startsWith(".")) continue;
     const full = join(dir, entry);
-    if (statSync(full).isDirectory()) markdownFiles(full, out);
-    else if (entry.endsWith(".md")) out.push(full);
+    if (statSync(full).isDirectory()) documentFiles(full, out);
+    else if (entry.endsWith(".md") || entry.endsWith(".txt")) out.push(full);
   }
   return out;
 }
@@ -292,20 +304,30 @@ const HOST_DEPENDENT_TYPES = new Set(["origin"]);
  * synthetic root so the loader sees a well-formed document. That wrapping is what makes
  * fragment-ness mechanical: nothing about the block has to be annotated.
  */
-function asLoadableModel(block: Block): string | undefined {
-  const text = block.lang === "yaml" || block.lang === "yml" ? undefined : stripJsonComments(block.body);
-  if (text === undefined) return undefined; // YAML handled separately (see gate docs)
+function asLoadableModel(block: Block): LoadableModel | undefined {
+  const isYaml = block.lang === "yaml" || block.lang === "yml";
+  // YAML authoring is sigil-free (ADR-0006) and the loader desugars it, so a YAML block
+  // is parsed, wrapped like any other fragment, and handed BACK to the loader as YAML —
+  // re-emitting keeps the bare attribute keys the desugar expects, where canonical JSON
+  // would demand `@` sigils this gate must not invent. ADR-0006 makes YAML the universal
+  // authoring front-end, so a YAML example teaching a retired attribute is exactly the
+  // #337 shape and must not sail through unchecked.
+  const format: MetaDataFormat = isYaml ? "yaml" : "json";
+  const emit = (value: unknown): LoadableModel => ({
+    content: isYaml ? Bun.YAML.stringify(value) : JSON.stringify(value),
+    format,
+  });
 
   let parsed: unknown;
   try {
-    parsed = JSON.parse(text);
+    parsed = isYaml ? Bun.YAML.parse(block.body) : JSON.parse(stripJsonComments(block.body));
   } catch {
     return undefined; // an elision or a prose snippet — makes no metadata claim
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
 
   const keys = Object.keys(parsed as Record<string, unknown>);
-  if (keys.includes("metadata.root")) return JSON.stringify(parsed);
+  if (keys.includes("metadata.root")) return emit(parsed);
   if (keys.length !== 1 || !NODE_KEY.test(keys[0]!)) return undefined;
 
   const key = keys[0]!;
@@ -327,7 +349,7 @@ function asLoadableModel(block: Block): string | undefined {
       .map((n) => ({ "field.string": { name: n } }));
     node = { "object.entity": { name: "DocExample", children: [...fields, parsed] } };
   }
-  return JSON.stringify({ "metadata.root": { package: "docexample", children: [node] } });
+  return emit({ "metadata.root": { package: "docexample", children: [node] } });
 }
 
 interface Finding {
@@ -346,7 +368,7 @@ async function main(): Promise<void> {
   for (const root of roots) {
     const dir = isAbsolute(root) ? root : join(REPO_ROOT, root);
     try { statSync(dir); } catch { continue; }
-    for (const file of markdownFiles(dir)) {
+    for (const file of documentFiles(dir)) {
       const path = relative(REPO_ROOT, file);
       if (SKIP_PREFIXES.some((p) => path.startsWith(p))) continue;
       blocks.push(...fencedBlocks(file));
@@ -364,15 +386,15 @@ async function main(): Promise<void> {
 
     let errors: readonly Error[];
     try {
-      ({ errors } = await MetaDataLoader.fromString(model, "json", { strict: true }));
+      ({ errors } = await MetaDataLoader.fromString(model.content, model.format, { strict: true }));
     } catch (e) {
       errors = [e as Error];
     }
 
     for (const error of errors) {
       const code = (error as { code?: string }).code ?? "ERR_UNCODED";
-      const finding: Finding = { block, code, message: error.message };
       if (FRAGMENT_CODES.has(code)) continue;
+      const finding: Finding = { block, code, message: error.message };
       if (FAIL_CODES.has(code)) { findings.push(finding); continue; }
       if (!unclassified.has(code)) unclassified.set(code, finding);
     }

scripts/test-doc-examples.ts

@@ -63,6 +63,22 @@ const CASES: readonly Case[] = [
       "```",
     ].join("\n"),
   },
+  {
+    // ADR-0006 makes YAML the universal authoring front-end, and the authoring skill
+    // teaches in it — so a YAML example carrying retired vocabulary is the #337 shape
+    // exactly. This case fails if the YAML path is ever skipped again.
+    name: "retired attribute in a sigil-free YAML block",
+    shouldFail: true,
+    because: "ERR_UNKNOWN_ATTR",
+    markdown: [
+      "```yaml",
+      "requirement.functional:",
+      "  name: recallMeasurement",
+      "  level: 4",
+      "  verifiedBy: [MeasurementTest]",
+      "```",
+    ].join("\n"),
+  },
   {
     // The everyday case: a fragment that omits everything around it must stay silent,
     // or the gate is noise and gets disabled.

server/csharp/MetaObjects.Codegen.Tests/Issue294ReferentialActionTests.cs

@@ -115,12 +115,40 @@ public void Tier3_the_parent_side_composition_supplies_its_subtype_default()
     }
 
     [Fact]
-    public void No_action_emits_no_clause_because_it_is_the_database_default()
+    public void No_action_is_stated_explicitly_rather_than_left_to_EF_s_convention()
     {
+        // Tempting to emit nothing here — `no-action` IS the database default, and the
+        // TS-owned DDL writes no ON DELETE clause for it. But EF does not treat an absent
+        // OnDelete as "no action": it applies its own convention, which for a REQUIRED
+        // foreign key is Cascade. Omitting the call would therefore make the generated
+        // context delete rows the database would refuse to orphan.
         var (source, _) = Generate(TwoEntityModel(referenceAttrs: """, "@onDelete": "no-action" """));
-        var line = WeekFkLine(source);
-        Assert.Contains("HasForeignKey(nameof(Week.ProgramId));", line);
-        Assert.DoesNotContain(".OnDelete(", line);
+        Assert.Contains(".OnDelete(DeleteBehavior.NoAction)", WeekFkLine(source));
+    }
+
+    [Fact]
+    public void An_uncorrelated_reference_is_NoAction_too()
+    {
+        // No @onDelete, and no relationship on either side to correlate with: the resolved
+        // action is "none", which must still be stated for the reason above.
+        var (source, _) = Generate("""
+        { "metadata.root": { "package": "acme", "children": [
+          { "object.entity": { "name": "Program", "children": [
+            { "source.rdb": { "@table": "programs" } },
+            { "field.long": { "name": "id" } },
+            { "identity.primary": { "@fields": "id" } }
+          ]}},
+          { "object.entity": { "name": "Week", "children": [
+            { "source.rdb": { "@table": "weeks" } },
+            { "field.long": { "name": "id" } },
+            { "field.long": { "name": "programId" } },
+            { "identity.primary": { "@fields": "id" } },
+            { "identity.reference": { "name": "refProgram", "@fields": "programId",
+              "@references": "Program" } }
+          ]}}
+        ]}}
+        """);
+        Assert.Contains(".OnDelete(DeleteBehavior.NoAction)", WeekFkLine(source));
     }
 
     [Fact]
@@ -132,7 +160,10 @@ public void Set_null_over_a_required_fk_warns_instead_of_breaking_model_validati
             referenceAttrs: """, "@onDelete": "set-null" """,
             programIdAttrs: ""","@required": true"""));
 
-        Assert.DoesNotContain(".OnDelete(", WeekFkLine(source));
+        // NoAction rather than nothing: an omitted call would leave EF's convention in
+        // charge, and for this REQUIRED foreign key that convention is Cascade — turning
+        // an unsatisfiable set-null into destructive cascade deletes.
+        Assert.Contains(".OnDelete(DeleteBehavior.NoAction)", WeekFkLine(source));
         Assert.Contains(warnings, w => w.Contains("SET NULL") && w.Contains("programId"));
     }