# ADR-015 — Derive the template datum from geometry, never from the reported parametric window

- **Status:** Accepted
- **Date:** 2026-09-05
- **Amends:** PRD 7.14 (recorded there as a hazard), PRD 11.14 (the measurement)
- **Deciders:** orchestrator
- **Raised by:** reviewer R-C1, finding N6 — which judged that updating PRD 7.14 alone
  *might* suffice. The decision to record an ADR was not the reviewer's.
- **Evidence:** live measurement on Fusion 2704.1.53 (PRD 11.14)

## Context

A miter template is a paper wrap. It is useless unless the fabricator can align it to a
known line on the tube — the **datum** (PRD 4, FR-3.1). The datum is an angular origin on
a cylindrical or conical face, so the obvious implementation is to take the face's
parametric window and measure from its start: `θ = v − vmin`.

**That obvious implementation is wrong, and it fails silently.** Measured across nine
cylindrical faces at `r = 14.3 mm` on Fusion 2704.1.53 (PRD 11.14):

| Source | Reported `v` window |
|---|---|
| `parametricRange()` on an **untrimmed** cylindrical face | `[0, 2π]` |
| `parametricRange()` on a **trimmed** cylindrical face | `[−π, +π]` |
| `textureCoordinates` on **the same untrimmed face** | `[−π, +π]` |

One face, two APIs, two windows. The window is a per-face, per-API report, not a property
of the surface.

The underlying parameterization is **stable**: `v = 0` landed on `+X` on all nine faces
measured, worst deviation `0.000e+00`. Only the reported *window* moves. So a datum taken
as `v − vmin` shifts by `π` — half a wrap, **44.925 mm of arc at `r = 14.3 mm`** — between
a trimmed and an untrimmed face of the same tube.

This is the failure mode PRD 7 exists to catalogue: the template still prints, still looks
correct, still wraps. It is simply clocked half a turn around the tube, and the error is
only discovered after the metal is cut.

The hazard is not hypothetical bookkeeping. Trimming is not something the add-in controls
— it is a consequence of how the *user* modeled the intersection, and PRD 2 fixes that the
add-in reads geometry and never creates it. So both cases will occur in normal use, on the
same tube, in the same document.

## Decision

**The datum is derived from an explicit geometric direction and asserted against PRD 4.
No datum, anywhere in the codebase, is derived from `vmin` or `vmax`.**

Concretely, for a face with axis `a` and a chosen reference direction `d` in the plane
perpendicular to `a`:

1. Take `d` from geometry that exists independently of the parameterization — the
   intersection direction, an explicit user selection (FR-3.1 "clock to"), or a documented
   world-axis fallback.
2. Compute the angle of a point as `atan2(P·(a × d), P·d)`, a value that does not depend on
   what window any API reports.
3. **Assert the handedness convention of PRD 4 in code**, not in a comment. PRD 7.1 records
   that a mirrored template looks perfect and fits nothing.

`parametricRange()` remains fine for what it actually is: a *width*, used to place samples
inside the face. Its **endpoints** are never a datum.

## Consequences

- Every datum implementation carries a geometric reference direction. There is no code path
  that reads `vmin` to establish an origin, and its absence is checkable by grep in review.
- The datum survives the user trimming, re-cutting or rebuilding a face, because it never
  depended on how the kernel reported that face's window.
- `tests/` must include a face in **both** trimmed and untrimmed form and assert the datum
  agrees between them. That test is the one that would catch a regression here, and it
  cannot be written without a fixture pair — PRD 13.2's programmatic corpus.
- A cost: the reference direction must be chosen and justified per surface type, which is
  more work than reading `vmin`. That is the point.

## Alternatives rejected

- **Normalize the window first** (shift whatever is reported to a canonical `[0, 2π]`).
  Rejected: it assumes the two APIs disagree only by a phase offset, which is exactly the
  unverified assumption that produced the hazard. It also leaves the datum defined in terms
  of a reported quantity, so the next API that reports a third window reintroduces the bug.
- **Always read the window from one chosen API** (`parametricRange()` only). Rejected: the
  measurement shows that *the same API* reports different windows for trimmed and untrimmed
  faces of the same tube, so fixing the API does not fix the datum.
- **Document the hazard and rely on care.** Rejected. This defect class already survived one
  review cycle in this repo as PRD 6.0's cone row, and it survived precisely because it was
  prose that no test reads. A constraint that only lives in prose is not enforced.