fix(loader): a projection may borrow any UNIQUE key, not only the primary (#310)

A projection borrows its key rather than declaring one — `identity.primary:
{ extends: "Account.pk" }`. The loader required a dotted extends target to have
the same type AND subtype, so the borrowed identity had to be the entity's
`identity.primary`. A read model keyed on a BUSINESS key — a unique code or slug
modelled as `identity.secondary`, with the surrogate auto-increment primary
deliberately never surfaced — could not be declared at all. It failed with
ERR_EXTENDS_TARGET_MISMATCH plus a second, misleading ERR_MISSING_REQUIRED_ATTR
for `@fields`, because the inherit never happened.

THE CODE WAS STRICTER THAN THE CONTRACT IT SHIPS. The byte-gated registry
manifest for `object.projection` says, in both `description` and `rules`:
"Identity is optional and, when present, MUST extend an entity identity."
Not "an entity's PRIMARY identity" — and an `identity.secondary` is an entity
identity. `spec/metamodel/object.json` and ADR-0028 carry the same unqualified
sentence. So this is a correction, and `expected-registry.json` is unchanged.

THE RULE IS UNIQUENESS, NOT NOMINATION. ADR-0040 moved uniqueness into the TYPE,
so primary and secondary are both unique keys, differing only in which one the
entity nominated as its main handle; borrowing a key borrows uniqueness, not that
nomination. `identity.reference` stays excluded on both sides — a foreign key is
not unique, so it can never back a key — and that bound is pinned, not assumed.

The subtype half of the gate was never written for identities. Its only
conformance byte is `error-extends-entity-field-type-mismatch`, a `field.uuid`
extending a `field.string`. For a FIELD, subtype IS the datatype and inheriting
across it is incoherent; for an identity, subtype is a ROLE. A field-shape rule
had been generalized onto a role axis without a fixture ever exercising it.

Nothing downstream needed changing, which was checked rather than assumed:
FR-024's key-correspondence pass never read the subtype, and the view builder
already anchors the FROM relation on the extended identity's OWNER, so the
emitted SQL selects the projected columns and omits the surrogate.

TWO DOORS, ONE PREDICATE. TypeScript and C# each check this twice — eagerly
during parse and again after all files load — and each held its own copy of the
boolean. My first cut fixed only the deferred door and every probe passed,
because the loader defers. They now share one function; reverting only the eager
door turns the new test red.

Gated by `projection-identity-borrows-secondary`, green in all four loader ports
(TS 566 · Java 566 · C# 901 · Python 401), plus per-port negatives for the FK
case and the untouched field case. The authoring skill showed only the trivial
`extends: "Entity.id"` form, which is what led an adopter to conclude composite
and natural-key projection identity were unsupported; it now shows both.

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

Author: dmealing

CHANGELOG.md

@@ -352,6 +352,50 @@ command whose whole job is the drift verdict. Pinned by a regression test on the
 which needs no Postgres container and covers the silent half: before the fix its failure
 output *is* the bug, verbatim.
 
+### Fixed — a projection could not borrow an entity's alternate key ([#310](https://github.com/metaobjectsdev/metaobjects/issues/310), all four loaders)
+
+A `object.projection` borrows its key rather than declaring one:
+`identity.primary: { extends: "Account.pk" }`. But the loader required a dotted `extends`
+target to have the same type **and subtype**, so the borrowed identity had to be the
+entity's `identity.primary`. A read model keyed on a **business key** — a unique code or
+slug the entity models as `identity.secondary`, with the surrogate auto-increment
+`identity.primary` deliberately never surfaced — failed to load with
+`ERR_EXTENDS_TARGET_MISMATCH`, plus a second, misleading `ERR_MISSING_REQUIRED_ATTR:
+@fields` (the inherit never happened, so the identity looked malformed too).
+
+**This was the code being stricter than the contract it ships.** The byte-gated registry
+manifest for `object.projection` says, in both its `description` and its `rules`:
+
+> Identity is optional and, when present, MUST extend **an entity identity**.
+
+Not "an entity's PRIMARY identity" — and an `identity.secondary` is an entity identity.
+`spec/metamodel/object.json` and ADR-0028 carry the same unqualified sentence. So this is a
+correction, not a capability grant, and `expected-registry.json` is unchanged.
+
+**The rule is uniqueness, not nomination.** ADR-0040 moved uniqueness into the TYPE, so
+`identity.primary` and `identity.secondary` are both unique keys — they differ only in
+which one the entity nominated as its main handle, and borrowing a key borrows uniqueness,
+not that nomination. `identity.reference` stays excluded on both sides: a foreign key is
+not unique, so it can never back a key. That bound is pinned per port, not assumed.
+
+The subtype half of the gate was never written for identities in the first place. Its only
+conformance byte is `error-extends-entity-field-type-mismatch` — a `field.uuid` extending a
+`field.string`. For a FIELD, subtype IS the datatype and inheriting across it is incoherent;
+for an identity, subtype is a ROLE. A field-shape rule had been generalized onto a role axis
+without a fixture ever exercising it.
+
+Nothing downstream needed changing: FR-024's key-correspondence pass never read the subtype,
+and the view builder already anchors the FROM relation on the *extended identity's owner* —
+so the emitted SQL selects the projected columns and omits the surrogate, as intended.
+
+**Two doors, one predicate.** TypeScript and C# each check this twice — an eager check
+during parse and a deferred one after all files load — and each held its own copy of the
+boolean. They now share one function, because a one-sided fix passes whichever path a given
+loader configuration happens to take; the eager door is pinned separately, and reverting
+only it turns the new test red.
+
+New shared fixture `projection-identity-borrows-secondary`, green in all four ports.
+
 ### Fixed — Java and Kotlin get the safety floor they never implemented (Maven)
 
 `docs/features/codegen-concepts.md` §7 has always stated a **product-wide** backstop —

agent-context/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/agent-context-conformance/java-kotlin-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/agent-context-conformance/java-react/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/agent-context-conformance/python/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/agent-context-conformance/ts-react-tanstack/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/agent-context-conformance/ts-requirements/expected/.claude/skills/metaobjects-authoring/SKILL.md

@@ -789,6 +789,31 @@ declared field set IS the exposure (fail-closed). Give it a read-only `source.rd
 projection detection + view DDL off that read-only source, so without it `meta gen`
 emits nothing for the projection.
 
+**The borrowed key may be ANY unique key — including a composite, and including the
+entity's `identity.secondary`.** The single-field `extends: "Author.id"` above is the
+common case, not the limit. Both of these are legal:
+
+```yaml
+# Composite primary → composite primary. @fields is COMPUTED from the local
+# pass-through fields, so it is optional here (declare it and it must agree).
+- identity.primary: { name: pk, extends: "Order.pk" }      # Order.pk = [tenant, ref]
+
+# A read model keyed on the entity's BUSINESS key, never surfacing its surrogate id.
+# Account has both: identity.primary pk (auto-increment id) AND identity.secondary
+# byCode (tenant + code). The view exposes tenant + code and borrows byCode.
+- identity.primary: { name: pk, extends: "Account.byCode" }
+```
+
+The rule is **uniqueness, not nomination**: ADR-0040 put uniqueness in the type, so
+`identity.primary` and `identity.secondary` are both unique keys and either can back a
+projection's key. `identity.reference` cannot — a foreign key is not unique, so
+`identity.primary extends: "Account.ownerRef"` is `ERR_EXTENDS_TARGET_MISMATCH`.
+
+Key correspondence still holds in every case: every field named by the borrowed identity's
+`@fields` needs a local field `extends`-ing that entity field, or the load fails with
+`ERR_IDENTITY_KEY_MISMATCH` — the identity cannot claim a pass-through the fields do not
+make.
+
 **A CONCRETE projection declares its OWN source — never inherits one.** A
 projection may `extends` another projection to reuse shape, but the child must
 declare its own `source.rdb`; inheriting the parent's is

fixtures/conformance/projection-identity-borrows-secondary/README.md

@@ -0,0 +1,37 @@
+# projection-identity-borrows-secondary (#310)
+
+A projection's `identity.primary` extends the entity's **`identity.secondary`**.
+
+`Account` has a surrogate auto-increment `identity.primary` AND a unique business key
+(`byCode`, over `tenant` + `code`). The read model keys off the business key and
+**deliberately never surfaces the surrogate `id` at all** — the shape an adopter needs for a
+read-only API view addressed by a code or slug rather than an internal database id.
+
+## Why this must load
+
+The loader required a dotted `extends` target to have the same type *and subtype*, so this
+failed with `ERR_EXTENDS_TARGET_MISMATCH` — while the shipped, byte-gated registry text for
+`object.projection` says, in both its `description` and its `rules`:
+
+> Identity is optional and, when present, MUST extend **an entity identity**.
+
+Not "an entity's PRIMARY identity". An `identity.secondary` is an entity identity, so the
+loader was stricter than the contract it ships in every port.
+
+**ADR-0040 is what makes the rule statable.** It moved uniqueness into the TYPE:
+`identity.primary` and `identity.secondary` are both unique keys (`@unique` was *removed*
+from secondary precisely because the subtype already says so), while `identity.reference` is
+a foreign key and carries no uniqueness. So a key may borrow any UNIQUE key — borrowing a
+key borrows uniqueness, not the entity's choice of which one is its main handle.
+
+The bound matters as much as the grant: `identity.primary` extending an `identity.reference`
+is still refused, because an FK cannot back a key. That negative is pinned per-port rather
+than here, since this corpus's `expected-errors.json` shape covers one load at a time.
+
+## Provenance of the rule this relaxes
+
+The subtype half of the gate was never written for identities. Its only conformance byte is
+`error-extends-entity-field-type-mismatch` — a `field.uuid` extending a `field.string`. For a
+FIELD, subtype IS the datatype and inheriting across it is incoherent; for an identity,
+subtype is a ROLE. A field-shape rule was generalized onto a role axis without a fixture ever
+exercising it.

fixtures/conformance/projection-identity-borrows-secondary/input/meta.demo.json

@@ -0,0 +1,32 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Account",
+          "children": [
+            { "source.rdb": { "@table": "accounts" } },
+            { "field.long": { "name": "id" } },
+            { "field.string": { "name": "tenant" } },
+            { "field.string": { "name": "code" } },
+            { "field.string": { "name": "internalNotes" } },
+            { "identity.primary": { "name": "pk", "@fields": ["id"], "@generation": "increment" } },
+            { "identity.secondary": { "name": "byCode", "@fields": ["tenant", "code"] } }
+          ]
+        }
+      },
+      {
+        "object.projection": {
+          "name": "AccountsByCode",
+          "children": [
+            { "source.rdb": { "@kind": "view", "@table": "v_accounts_by_code" } },
+            { "field.string": { "name": "tenant", "extends": "demo::Account.tenant" } },
+            { "field.string": { "name": "code", "extends": "demo::Account.code" } },
+            { "identity.primary": { "name": "pk", "extends": "demo::Account.byCode" } }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/projection-identity-borrows-secondary/providers.json

@@ -0,0 +1 @@
+["metaobjects-core-types", "metaobjects-db"]