FR-024 §7 entity read-view — the codegen READ half: route reads to the replica view + carry derived fields in the read type (cross-port)

[dmealing]

Summary

#213 fixed the schema/write half of FR-024 §7 (entity read-views): meta migrate now excludes derived (origin.*) fields from the write table and emits the replica view, and the write-side codegen (Drizzle table + Insert/Update Zod schemas) excludes them too (verified end-to-end by a real-PG round-trip). But the read half of the §7 contract is still unimplemented — spec §7 says derived fields are "excluded from INSERT/UPDATE, write codecs, and create/update inputs; reads route to the view", and only the first clause shipped.

The gaps (read side)

For a write-through entity (isWriteThrough — a writable table source + a non-primary read-only view source + derived fields):

1. Reads route to the TABLE, not the replica view. codegen-ts/src/templates/queries-file.ts special-cases only isProjection (→ renderProjectionQueriesFile); a write-through entity (isProjection is false) falls to the vanilla path, whose findById/list select from the entity's own collection = the write table. So a derived column (e.g. customerName) is never returned — the view exists but nothing reads it.
2. The entity's read TYPE excludes the derived field. Because meta migrate does not implement FR-024 §7 on the schema path: derived entity fields leak into the table DDL and the read-view is never emitted #213 excludes derived fields from the Drizzle table + Insert/Update schemas, the generated <Entity> type (inferred from the table select) no longer carries the derived field — but a read through the view returns it. The read type and the wire shape disagree.
3. Cross-port ORM/DTO generators need the same treatment. meta migrate does not implement FR-024 §7 on the schema path: derived entity fields leak into the table DDL and the read-view is never emitted #213's exclusions are TS-only (ADR-0015 schema is TS-owned, but the Drizzle/Zod exclusions are TS-codegen). The other four ports (Java SpringDtoGenerator/repo, Kotlin Exposed, C# EntityGenerator/EF, Python) map fields to columns/DTO members with no derived-field exclusion, and none route reads to the replica view. This is a coordinated 5-port change.

Proposed shape

• Introduce a shared MetaField.isDerived() per port (TS already has it, metadata/src/core/field/meta-field.ts) as the SSOT for "read-only, view-side only".
• Write-through entity codegen (all ports): exclude derived fields from the write table / ORM entity / write DTOs (as TS now does); route the generated read path (findById/list/repo reads) to the replica view; make the entity's read type/DTO carry the derived fields (read shape = the view's columns).
• Keep the write path (create/update) targeting the table with the derived fields absent — the same write-through dispatch projections/entities already model.

Not in scope

• The migrate schema half (done, meta migrate does not implement FR-024 §7 on the schema path: derived entity fields leak into the table DDL and the read-view is never emitted #213).
• A flattened field.object on a write-through entity is not yet handled in the entity-host view SELECT (scalars + derived joins are) — track as a sub-item or a separate note.

Refs

• meta migrate does not implement FR-024 §7 on the schema path: derived entity fields leak into the table DDL and the read-view is never emitted #213 (schema/write half, landed), FR-024 §7 (docs/superpowers/specs/2026-06-12-fr-024-entity-surfaces-projections-design.md), ADR-0028 (derived ⇒ read-only), ADR-0015 (schema TS-owned; runtime/codegen per-port).

[dmealing]

Shipped in the coordinated 0.17.0 (npm / PyPI / NuGet) · 7.9.0 (Maven Central) release — live on all four registries (PR #215, tag v0.17.0). Cross-port, conformance-gated. See CHANGELOG [0.17.0].