no-mistakes(document): docs: sync origin.passthrough type-preservation docs

Author: dmealing

docs/1.0-readiness.md

@@ -44,8 +44,9 @@ Status legend: ✅ done · 🔶 in progress · ⬜ not started · ❓ **[RATIFY]
 - ✅ **B2. `0.x → 1.0` migration guide written** —
   [`docs/features/migrations/0.x-to-1.0.md`](features/migrations/0.x-to-1.0.md):
   version re-baseline + verify strict-default, jsonb parsed-value, timestamp
-  instant-default, `@dbColumnType` slim, `index.*`/`@unique` removal, deprecated-export
-  removal. FR-024 deferred → no declared-API vocab to migrate.
+  instant-default, `@dbColumnType` slim, `index.*`/`@unique` removal, passthrough
+  type-preservation (`@convert`), deprecated-export removal. FR-024 deferred → no
+  declared-API vocab to migrate.
 
 ## C. Metamodel freeze (the durable spine)
 
@@ -57,12 +58,16 @@ Status legend: ✅ done · 🔶 in progress · ⬜ not started · ❓ **[RATIFY]
   timestamps + `@localTime`, the `@dbColumnType` slim, reverse-nav finders — and
   ADR-0037 now gives a durable framework for any future addition. Only A2 (FR-024)
   remains open. Audit the registry for anything still experimental.
-- 🔶 **C3. The last breaking metamodel/wire move landed in `0.15.1`/`7.7.1`** — the
-  `index.*` type + `identity.secondary` key-purity (ADR-0040; `@unique` removed →
-  `ERR_UNKNOWN_ATTR`). It followed `0.15.0`/`7.7.0` (the metamodel-1.0 vocabulary
-  program + the ADR-0039 own-accessor fix) and `0.14.0`/`7.6.0` (verify strict-default,
-  jsonb parsed-value). `index.*` **reset the quiet-period clock** — the first
-  no-breaking coordinated release must come *after* `0.15.1`/`7.7.1` (see G3).
+- 🔶 **C3. The last breaking metamodel/wire move landed in the `0.15.x` line** —
+  `origin.passthrough` is now type-preserving (#185; a divergent `field.<subType>` or
+  array-ness fails load with `ERR_PASSTHROUGH_TYPE_MISMATCH`, generalizing/retiring the
+  FR-015 `ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH`; opt out with the acknowledgement-only
+  `@convert` on `origin.passthrough`). It followed `0.15.1`/`7.7.1` — the `index.*` type +
+  `identity.secondary` key-purity (ADR-0040; `@unique` removed → `ERR_UNKNOWN_ATTR`) — which
+  followed `0.15.0`/`7.7.0` (the metamodel-1.0 vocabulary program + the ADR-0039 own-accessor
+  fix) and `0.14.0`/`7.6.0` (verify strict-default, jsonb parsed-value). The passthrough move
+  **reset the quiet-period clock** — the first no-breaking coordinated release must come
+  *after* it (see G3).
 - ✅ **C4. `metamodelVersion` marker SHIPPED** (PR #145, all 5 ports, `"0.9"`). A single **rolled-up**
   spec-version string the loader/**registry** exposes and every port emits, asserted by
   the conformance matrix — the artifact that lets packages version independently while
@@ -138,14 +143,15 @@ Status legend: ✅ done · 🔶 in progress · ⬜ not started · ❓ **[RATIFY]
   `→8.0.0`, freeze the spec version at `Metamodel 1.0` (C4). Both forward; no
   backwards move on any registry.
 - ⬜ **G2. Remove the deprecated export** if A3=remove (one-time).
-- ⬜ **G3. A quiet period** — at least one coordinated release after `0.15.1`/`7.7.1`
-  (the last breaking move, C3) with **no metamodel-breaking changes**, to prove the
-  rate has actually dropped. Requires A2/FR-024 to land additively or defer.
+- ⬜ **G3. A quiet period** — at least one coordinated release after the last breaking
+  move (C3, the `0.15.x` passthrough type-preservation move) with **no
+  metamodel-breaking changes**, to prove the rate has actually dropped. Requires
+  A2/FR-024 to land additively or defer.
 - ⬜ **G4. Cut Metamodel 1.0** through the `releasing` skill (RC → smoke → confirm →
   promote), with the migration guide (B2) + compat policy (B1) published alongside.
 
 ---
 
-_Last updated 2026-07-02 (post `0.15.1`/`7.7.1` + `0.15.2`; A1 ratified — decouple).
+_Last updated 2026-07-08 (post `0.15.1`/`7.7.1` + `0.15.2`; the `0.15.x` passthrough type-preservation move (#185) reset the quiet-period clock — C3/G3; A1 ratified — decouple).
 Owner: maintainer. Update the status marks as items land; ratify the remaining §A
 decisions (A2–A4) to unblock the rest._

docs/features/migrations/0.x-to-1.0.md

@@ -77,7 +77,27 @@ the new **`index.lookup`** type.
 - **Full mechanical rewrite + the no-DDL-churn guarantee:**
   [identity.secondary → index.lookup](identity-secondary-to-index-lookup.md).
 
-## 6. Deprecated `codegen-ts/generators` export removed (at the 1.0 cut)
+## 6. `origin.passthrough` is type-preserving (shipped 0.15.x)
+
+A field carrying `origin.passthrough @from: "Entity.field"` forwards the source value
+unchanged, so its declared `field.<subType>` and array-ness must be **identical** to the
+resolved source field. A divergence now fails load with `ERR_PASSTHROUGH_TYPE_MISMATCH`
+(e.g. a `field.uuid` source surfaced by a projection as `field.string` — the exact
+mismodeling that leaves a view `String`-typed over a `uuid` column and forces hand-written
+`String↔UUID` coercion). The check compares **subType and array-ness only — nullability is
+deliberately not judged** (a view over an outer join legitimately widens `NOT NULL` →
+nullable). This generalizes and retires the narrow, stored-proc-parameter-ref-only
+`ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH` (FR-015) into one host-agnostic invariant
+covering projections, entities, values, and parameter refs alike.
+
+- **If load newly fails:** the error names both the declared type and the source type.
+  Declare the source's type (usually the fix — the projection was wrong), or set
+  `@convert: true` on the `origin.passthrough` if the divergence is intentional.
+- **`@convert` is an acknowledgement only — it does NOT generate a cast**; the value flows
+  through unchanged and the consumer owns any coercion. Real type-converting projections
+  remain `origin.expression`'s job (#159, post-1.0).
+
+## 7. Deprecated `codegen-ts/generators` export removed (at the 1.0 cut)
 
 Importing the built-in generators from `@metaobjectsdev/codegen-ts/generators`
 (`entityFile` / `queriesFile` / `routesFile` / `barrel`) is **removed** at 1.0.

docs/features/templates-and-payloads.md

@@ -446,6 +446,9 @@ The following conformance fixtures gate this feature's behavior across ports:
 - [`fixtures/conformance/origin-collection-simple/`](../../fixtures/conformance/origin-collection-simple/) — `origin.collection` for repeated-row payloads
 - [`fixtures/conformance/error-origin-bad-via-path/`](../../fixtures/conformance/error-origin-bad-via-path/) — unresolvable `@via` rejected
 - [`fixtures/conformance/error-origin-bad-aggregate-fn/`](../../fixtures/conformance/error-origin-bad-aggregate-fn/) — unknown `@agg` rejected
+- [`fixtures/conformance/error-origin-passthrough-type-mismatch/`](../../fixtures/conformance/error-origin-passthrough-type-mismatch/) — a `passthrough` field whose `field.<subType>` differs from its `@from` source fails with `ERR_PASSTHROUGH_TYPE_MISMATCH`
+- [`fixtures/conformance/error-origin-passthrough-array-mismatch/`](../../fixtures/conformance/error-origin-passthrough-array-mismatch/) — a `passthrough` field whose array-ness differs from its `@from` source fails with `ERR_PASSTHROUGH_TYPE_MISMATCH`
+- [`fixtures/conformance/origin-passthrough-convert-optout/`](../../fixtures/conformance/origin-passthrough-convert-optout/) — `@convert: true` acknowledges a deliberate type divergence (no cast generated)
 
 **Render engine output (`fixtures/render-conformance/`)** — byte-identical Mustache output across ports
 

spec/cross-language-porting-guide.md

@@ -74,7 +74,14 @@ warning lists, through these ordered stages. Mirror the order; the mechanism is
       `@db.indexed` → **warning** (drift detection).
    4. **Origin paths** — `passthrough`/`aggregate` `@from`/`@of` must resolve to
       `Entity.field`; `@via` must hop correctly through relationships
-      (`ERR_INVALID_ORIGIN`).
+      (`ERR_INVALID_ORIGIN`). A `passthrough` field must also be **type-preserving**:
+      its declared `field.<subType>` and array-ness must match the resolved source field
+      (nullability is not judged — an outer-join view legitimately widens `NOT NULL` →
+      nullable). A divergence fails with `ERR_PASSTHROUGH_TYPE_MISMATCH` unless the
+      `origin.passthrough` carries `@convert: true` (an acknowledgement only — it does
+      not generate a cast). This host-agnostic check covers projections, entities,
+      values, and stored-proc parameter refs (it generalizes/retires the FR-015
+      `ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH`).
    5. **Attribute schema** — declared attrs must match their declared value type and
       allowed-values; required attrs must be present (effective: own + inherited). Undeclared
       attrs are **not** rejected (open policy). Errors `ERR_MISSING_REQUIRED_ATTR`,