feat(core): publish the reproducibility envelope; document coupling at scale#1085
Merged
Conversation
…t scale Three fixes, all traceable to one external integrator forming false beliefs from the available documentation. FieldHandle.guarantees. The determinism classification, the controlled and uncontrolled inputs, the requirements for repeatability and the cross-plane tolerance existed only in an unexported experimental module. A consumer building replay and shared-state features concluded the runtime was byte-identical across Node, native and browser, and designed on it. That was a reasonable inference — the real answer was not reachable from the public API. It is conditionally-deterministic; host-geometry and body-ordering are NOT controlled; cross-plane agreement is a 1e-6 tolerance, never bit-equality. Publishing one fact twice creates a drift problem, so guarantees.test.ts asserts the published envelope matches the world adapter's contract declaration field by field. coupling-discipline.md. The rung discipline — couple at the lowest rung that achieves the effect — was arrived at independently by two consumer projects that each hit the same wall and each had to derive it from scratch. It covers rung selection, sampling cadence, the measured cost, and the section that was missing entirely: when NOT to use the field. High-frequency domain telemetry belongs in plain arrays and instanced geometry, not in bodies. That is a category boundary, not a performance tip. README signposting. @fundamental-engine/three was already fully documented in the packages table at line 486 of a 649-line README, with the exact API named. Two independent readers still recommended hand-building the headless-to-THREE.Points bridge it ships. The entry was correct; its placement was not, so a pointer now sits in the capabilities section where someone choosing an architecture will actually look. typecheck clean; check:api 20 protected entries; check:docs and check:links green; core suite 1115/1115.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Adding a required member to FieldHandle broke every class implementing it. FieldLayer (three) and FieldField (vanilla) both wrap a core handle and hand-forward its surface, so each needs a delegating getter — the wrappers change how a field is hosted or drawn, not what the engine guarantees about reproducing a run. This was my verification failure, not a surprise. After adding the interface member I ran pnpm typecheck from inside packages/core, which runs only that package's script, and reported the result as though it were the recursive gate. The root typecheck and pnpm -r build were never run. Vercel ran them and found it immediately. vanilla already ships delegation-drift.test.ts for precisely this class of bug — a handle member that exists on a real headless handle but was never forwarded on the wrapper. The guard was right; I did not run it. Recursive build clean, pnpm typecheck clean from the root, all nine packages' tests pass, check:api 20 protected entries, check:docs green.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
An external integrator evaluated Fundamental without installing it — every belief formed by reading. Three of those beliefs were false, and two were the documentation's fault rather than the reader's.
1 ·
FieldHandle.guarantees— the envelope is now queryableThe determinism classification, controlled/uncontrolled inputs, repeatability requirements and cross-plane tolerance existed only inside an unexported experimental module. To learn that
host-geometryandbody-orderingare uncontrolled, you had to read source the project tells you not to depend on.So the integrator concluded the runtime was byte-identical across Node, native and browser and designed replay and shared-state features on it. Reasonable inference; unavailable information.
Additive —
check:apinever fails on an addition. Documented in the HANDLE table.The drift guard
Publishing one fact twice creates a new problem.
guarantees.test.tsasserts the published envelope matches the world adapter's contract declaration field by field, so the two cannot diverge silently.2 ·
coupling-discipline.mdThe rung discipline — couple at the lowest rung that achieves the effect — was arrived at independently by two consumer projects, each hitting the same wall and deriving it from scratch. That is a strong signal it belonged in canon.
Includes the section that was missing entirely: when not to use the field. High-frequency domain telemetry belongs in plain arrays and instanced geometry, not in bodies — a category boundary, not a performance tip.
3 · README signposting
I initially claimed
@fundamental-engine/threewas invisible in the README. That was wrong — I truncated a grep and concluded from an incomplete view. It is fully documented at line 486 with the exact API.The weaker claim survives: two competent readers still missed it, at line 486 of a 649-line file. So this is a pointer in the capabilities section, not a rewrite.
Gates
typecheck ·
check:api(20 protected) ·check:docs·check:links· core suite 1115/1115