fix(codegen-ts): join an unenforced required reference LEFT OUTER in projection views

#209 made a belongs-to hop INNER when its FK field is @required, since
every base row then has a match. That holds only when a constraint
enforces the reference. Under @Enforce: false the column can name a row
that does not exist, and INNER silently drops the base row from the view.
Found reviewing an adopter's view migration: an account ref_id that holds
a user id or a group id joined INNER to the user table.

The hop is INNER only when the reference is also enforced; otherwise
LEFT OUTER. The nested-chain demotion is unchanged. MetaReferenceIdentity's
doc comment, which said projection join inference ignores @Enforce, is
corrected.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M1mRRB1K2WdYy82kntMQdx

Author: dmealing

CHANGELOG.md

@@ -10,6 +10,16 @@ here.**
 
 ## [Unreleased]
 
+### Fixed
+
+- **A projection view keeps rows whose unenforced reference has no target.** A belongs-to hop
+  whose FK field is `@required` was joined `INNER`, on the reasoning that every row has a
+  match. That holds only for an enforced reference: under `@enforce: false` there is no FK
+  constraint, and a row can name a target that does not exist, so `INNER` dropped it from the
+  view. Such a hop is now `LEFT OUTER`. **Upgrading:** the next `meta migrate` rewrites any
+  view that joins through an unenforced required reference; review it — the view returns the
+  rows it had been dropping.
+
 ## [1.0.11] — 2026-10-01
 
 _npm `1.0.11` (all 14 `@metaobjectsdev/*` packages in lockstep), PyPI `1.0.11`, NuGet `1.0.11` and

server/typescript/packages/codegen-ts/src/projection/extract-view-spec.ts

@@ -911,9 +911,14 @@ function buildJoinTree(
         // for (and keeps `verify --db` fingerprints aligned). A nullable belongs-to
         // FK, or ANY has-many hop (FK on the child — a base row may have zero
         // children), stays LEFT OUTER so no base row is dropped.
+        // And only for an ENFORCED reference: `@enforce: false` declares a logical reference
+        // with no FK constraint, so a NOT NULL column can still name a row that does not
+        // exist, and INNER would silently drop that base row (an adopter's account `ref_id`
+        // holds a user id OR a group id). Unenforced stays LEFT OUTER.
         const fkFieldObj = (fkHolder as MetaObject).findField(fkField);
         const selfInner =
-          referenceHolder === "source" && fkFieldObj !== undefined && isRequired(fkFieldObj);
+          referenceHolder === "source" && fkFieldObj !== undefined && isRequired(fkFieldObj) &&
+          ref.referenceIdentity.enforce;
         // Nested-chain safety: joins render flat + left-associative, so an INNER hop
         // BELOW any LEFT ancestor drops the base row (its ON references a column the
         // LEFT ancestor NULLed). An INNER only survives when the ENTIRE ancestor chain

server/typescript/packages/codegen-ts/test/projection/join-type-derivation.test.ts

@@ -21,7 +21,7 @@ async function load(children: unknown[]) {
 // Order --belongs-to--> Customer (FK `customerId` on Order). A projection passes
 // through Customer.name via the single-hop `customer` relationship, forcing a join
 // from orders to customers.
-const belongsToModel = (customerIdRequired: boolean) => [
+const belongsToModel = (customerIdRequired: boolean, enforce = true) => [
   { "object.entity": { name: "Customer", children: [
     { "source.rdb": { "@table": "customers" } },
     { "field.long": { name: "id" } },
@@ -33,7 +33,7 @@ const belongsToModel = (customerIdRequired: boolean) => [
     { "field.long": { name: "id" } },
     { "field.long": { name: "customerId", ...(customerIdRequired ? { "@required": true } : {}) } },
     { "identity.primary": { name: "pk", "@fields": "id" } },
-    { "identity.reference": { name: "ref_customer", "@fields": "customerId", "@references": "Customer" } },
+    { "identity.reference": { name: "ref_customer", "@fields": "customerId", "@references": "Customer", ...(enforce ? {} : { "@enforce": false }) } },
     { "relationship.association": { name: "customer", "@objectRef": "Customer", "@cardinality": "one" } },
   ] } },
   { "object.projection": { name: "OrderView", children: [
@@ -52,6 +52,17 @@ describe("#209 — belongs-to join type derived from FK optionality", () => {
     expect(v!.sql).not.toContain("LEFT OUTER JOIN customers");
   });
 
+  // INNER is lossless only when every base row HAS a match — which only a database-enforced
+  // reference guarantees. `@enforce: false` declares a logical reference with no FK
+  // constraint, so a row may name a target that does not exist (an adopter's account
+  // `ref_id` holds a user id OR a group id). INNER dropped those rows from the view.
+  test("required but UNENFORCED FK → LEFT OUTER JOIN (no constraint guarantees the match)", async () => {
+    const root = await load(belongsToModel(true, false));
+    const [v] = buildProjectionViews(root, { dialect: "postgres", columnNamingStrategy: "snake_case" });
+    expect(v!.sql).toContain("LEFT OUTER JOIN customers");
+    expect(v!.sql).not.toContain("INNER JOIN customers");
+  });
+
   test("nullable FK → LEFT OUTER JOIN (preserved)", async () => {
     const root = await load(belongsToModel(false));
     const [v] = buildProjectionViews(root, { dialect: "postgres", columnNamingStrategy: "snake_case" });

server/typescript/packages/metadata/src/core/identity/meta-identity.ts

@@ -94,8 +94,9 @@ export class MetaReferenceIdentity extends MetaIdentity {
    * Whether the reference is physically enforced by the backend.
    * Default true (hard FK constraint emitted). Explicit `@enforce: false`
    * marks the reference as logical-only — drizzle-schema skips `.references()`
-   * and migrate-ts's expected schema omits the FK descriptor. relations()
-   * block and projection JOIN inference are unaffected.
+   * and migrate-ts's expected schema omits the FK descriptor. The relations()
+   * block is unaffected; projection JOIN inference keeps an unenforced required
+   * belongs-to hop LEFT OUTER, since no constraint guarantees the target row.
    */
   get enforce(): boolean {
     // ADR-0039: resolving — @enforce may be inherited via extends.