@@ -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 —
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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.
@@ -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" } }
+          ]
+        }
+      }
+    ]
+  }
+}
@@ -0,0 +1 @@
+["metaobjects-core-types", "metaobjects-db"]
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+["metaobjects-core-types", "metaobjects-db"]`