docs(adr): correct the false 3D claim; record 3D as a goal, not a carried feature #30

New issue

Closed

opened 2026-07-02 14:03:39 +00:00 by toph · 1 comment

toph commented

2026-07-02 14:03:39 +00:00

Owner

The action-model design doc claims the runtime state carries "per-face exact isometry into 3D" and that non-flat fold angles are "already carried" by it (2026-06-29-action-model-folding-design.md:67,83,117-118,265). That's false: Isometry.t is a planar 2×2 + translation (isometry.ml:4-11), Geom.point is 2D, and the vertex-dedup invariant in fold_emit.ml:9-14 self-documents that it breaks for non-flat folds. 3D isn't carried — reaching it is a type-level rework (3D isometries, 3D geometry, per-(face,vertex) coords).

To be clear about intent: 3D is the goal, and an explicitly wanted one — it's just not expressible yet. The problem with the doc isn't the ambition, it's asserting the ambition is already implemented. "Already carried" invites building on a guarantee that doesn't exist.

So:

Correct the design doc — replace every "already carries" / "isometry into 3D" with the honest version: flat folds only today (2D isometries), 3D is an intended follow-slice requiring the type-level rework above.
Write the ADR recording the current state as a limitation, not a preference: the evaluator is flat-only — the all-layers simple fold model, the weakest in the Demaine–O'Rourke taxonomy [demaine2007, §14.1.2] — with 3D as the committed target. Flat-only is where we are, not where we're aiming.

The staging is fine. Only the "3D is already here" claim needs to go.

The action-model design doc claims the runtime state carries "per-face exact isometry into 3D" and that non-flat fold angles are "already carried" by it (`2026-06-29-action-model-folding-design.md:67,83,117-118,265`). That's false: `Isometry.t` is a planar 2×2 + translation (`isometry.ml:4-11`), `Geom.point` is 2D, and the vertex-dedup invariant in `fold_emit.ml:9-14` self-documents that it breaks for non-flat folds. 3D isn't carried — reaching it is a type-level rework (3D isometries, 3D geometry, per-(face,vertex) coords). To be clear about intent: 3D **is** the goal, and an explicitly wanted one — it's just not expressible yet. The problem with the doc isn't the ambition, it's asserting the ambition is already implemented. "Already carried" invites building on a guarantee that doesn't exist. So: - Correct the design doc — replace every "already carries" / "isometry into 3D" with the honest version: flat folds only today (2D isometries), 3D is an intended follow-slice requiring the type-level rework above. - Write the ADR recording the current state as a *limitation, not a preference*: the evaluator is flat-only — the all-layers simple fold model, the weakest in the Demaine–O'Rourke taxonomy [demaine2007, §14.1.2] — with 3D as the committed target. Flat-only is where we are, not where we're aiming. The staging is fine. Only the "3D is already here" claim needs to go.

toph changed title from ~~docs(adr): record flat-only as an explicit decision~~ to docs(adr): correct the false 3D claim; record 3D as a goal, not a carried feature

2026-07-03 19:47:17 +00:00

toph commented

2026-07-03 19:55:58 +00:00

Author

Owner

Done in 629c14d (on main). ADR 0015 records flat-only as the current scope with 3D as the intended goal; the action-model design doc's "already carries 3D" claims are corrected to 2D-today / 3D-is-the-goal.

Numbered 0015, not 0014 — 0014 is reserved by the unmerged crease-entity branch.

Done in 629c14d (on `main`). ADR 0015 records flat-only as the current scope with 3D as the intended goal; the action-model design doc's "already carries 3D" claims are corrected to 2D-today / 3D-is-the-goal. Numbered 0015, not 0014 — 0014 is reserved by the unmerged crease-entity branch.

toph closed this issue

2026-07-03 19:55:58 +00:00

toph referenced this issue from a commit

2026-07-03 19:55:58 +00:00

docs(adr): record flat-only scope; 3D is a goal, not a carried feature (#30)

toph referenced this issue

2026-07-03 20:08:52 +00:00

WIP: feat(vscode): live preview — per-step diagrams synced to cursor (#42) #53

toph referenced this issue

2026-07-04 18:46:01 +00:00

feat(vscode): live preview — per-step diagrams synced to cursor (#42) #60

toph referenced this issue