Skip to content

Add the ray-traced scene profile: types, validator, receipt, fixtures - #160

Merged
flyingrobots merged 2 commits into
mainfrom
feat/ray-traced-scene-profile
Nov 14, 2026
Merged

flyingrobots merged 2 commits into
mainfrom
feat/ray-traced-scene-profile

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Closes #153

What this adds

The first Geordi slice of the accepted design docs/design/2026-11-fixed-point-and-ray-traced-scene-profiles.md (Part C). It is Rust only and contains no renderer.

  • geordi-ir: GeordiFixedQ32_32 for geordi-fixed-q32.32/1. It deserializes only from a JSON integer token in -(2^53 - 1)..=2^53 - 1. There are DTOs for geordi-ray-traced-scene/1 (meshes by hash and layout, instances with column-major affine transforms, the pinhole camera with tanHalfFovY, diffuse materials, the directional light and the uniform sky, film, and render settings). parse_geordi_ray_traced_scene, validate_geordi_ray_traced_scene and validate_geordi_ray_traced_scene_mesh_assets report stable GEORDI_E_RT_* diagnostics with JSON paths. The module also has the canonical scene JSON and sceneHash, the raw-RGBA8 imageHash, and the geordi-ray-traced-render-receipt/1 type with a builder, parser, validator, canonical JSON and receipt hash.
  • geordi-renderer: GeordiRayTracedRuntimeProfile with assert_ray_traced_runtime_profile, which works like assert_native_runtime_profile. RenderedImage::from_rgba8 is a public checked constructor that rejects a byte length other than width * height * 4 and overflow of that product. RenderedImage::image_hash returns the image hash. Existing behaviour is unchanged.
  • Fixtures in fixtures/ray-traced-scene/: one valid triangle-only scene (two instances of a binary little-endian PLY unit quad) and 60 failure fixtures, one rule each. Each failure's stage, code and path are recorded in failures/expected-diagnostics.json, and a test checks them exactly.
  • Docs: a living reference at docs/ray-traced-scene-profile.md, a new section in docs/ERROR_CODES.md, and updates to the docs and design indexes, STATUS.md, the README.md status and nonclaims, and CHANGELOG.md.

Not claimed: Geordi does not claim geordi/ray-traced-3d/1. None of the design's proof gates has run.

Interpretations to review

Most of the design is implemented as written. These points needed a choice. Each one is also stated in the reference page.

  1. Sampler and tone curve identities (needs a maintainer decision). The design says to reject an unknown sampler or tone curve identity (B8). But Bunny has published none yet (bunny#221 and bunny#222 are open), and the design's own example uses placeholders. If Geordi recognized only published identities, no scene could validate, and the "one valid fixture" in Part C could not exist. So Geordi's validator checks only the form name/N. Recognizing an identity is left to assert_ray_traced_runtime_profile, which is how B5 assigns it ("A runtime profile declares the integrator, sampler and tone curve identities it implements"). The reference fixture uses fixture-placeholder-sampler/1 and fixture-placeholder-tone-curve/1, which no runtime implements. When Bunny publishes its identities, they can become a recognized list in Geordi.
  2. -0 is rejected, not normalized. serde_json reads -0 as a float, so it cannot be told apart from -0.0 or -0e0, which the profile rejects. The design (A2) says -0 is normalized to 0; canonical writers never emit it.
  3. Every number token must be an integer. The safe-range rule is applied to plain integers too (counts, film, seed, samples). Each of those then has its own tighter range check.
  4. Paths for type errors. A wrong JSON type (for example a string in a Q32.32 field) and unknown or missing fields report path $, with the line and column in the message, because serde_json gives no JSON path and adding serde_path_to_error would be a new dependency. Fractions, exponents, -0 and out-of-range integers carry exact JSON paths.
  5. Requirements. A scene must require geordi/ray-traced-3d/1 and each feature its content uses. Declaring an unused feature is accepted.
  6. Duplicate ids are checked within each collection (meshes, materials, instances, lights), not across them. Ids must be non-empty.
  7. Declared bounds must have min <= max on every axis. This is a small rule the design implies but does not state.
  8. Mesh checks Geordi cannot see. The validator checks the path, the file's presence inside the fixture root and its hash. Decoding the binary PLY, and checking counts, bounds and triangle indices, stays with the runtime (B2: "The runtime recomputes both"), because Geordi has no binary PLY decoder and no Bunny dependency.
  9. The scene hash input. sceneHash is the hash of the existing Rust canonical JSON form (geordi_sha256_from_canonical_json_value: sorted keys, two-space indent, final newline). The committed reference scene is stored in that form.
  10. Runtime negotiation reuses GeordiRuntimeUnsupportedProfileError (no code, as the native path), and also checks mesh layout identities.

Verification

All Rust gates ran in the geordi dev container (rust 1.96.0) at the head commit: cargo fmt --check, cargo clippy --locked --workspace --all-targets -- -D warnings, and cargo test --locked --workspace.

The tests use these oracles:

  • the committed scene bytes, checked against Python's json.dumps(sort_keys=True, indent=2);
  • SHA-256 test vectors from Python hashlib and shasum;
  • a hand-written golden receipt;
  • boundary values on both sides of every numeric range;
  • a shear test that fails if the linear part is read row-major;
  • an exactness test that a nearest-even rounding check would fail.

Deliberate mutations, each restored afterwards:

  • range check <= changed to <: 2 tests fail;
  • trace-domain < changed to <=: 4 tests fail;
  • camera-domain >= changed to >: 2 tests fail.

The TypeScript and docs gates run in CI only. A local Python copy of the documentation hygiene rules passes.

Implement the first Geordi slice of the accepted fixed-point and
ray-traced scene profile design, in Rust only and without a renderer.

geordi-ir gains the geordi-fixed-q32.32/1 number type, which
deserializes only from JSON integers in -(2^53 - 1)..=2^53 - 1, and the
geordi-ray-traced-scene/1 DTOs, parser and validator with stable
GEORDI_E_RT_* diagnostics. The validator checks every version 1 rule
in the design, including the exact i128 trace-domain check on
transformed mesh bounds. It also verifies mesh asset hashes, computes
canonical scene and receipt hashes and the raw RGBA8 image hash, and
defines the geordi-ray-traced-render-receipt/1 type with a builder,
parser and validator.

geordi-renderer gains a ray-tracing runtime profile with a negotiation
check, and a checked public RenderedImage::from_rgba8 constructor.

Fixtures: one valid triangle-only scene with a binary PLY mesh and 60
failure fixtures, each with its expected code and path recorded.

The profile is not claimed: no proof gate has run.

Refs #153
@chatgpt-codex-connector

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-14T01:48:35.732441Z
We couldn’t complete this review. Comment @codex review to try again.
e3bf6b0 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 2 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 7b8d2703-1e9e-4efd-8d22-70e0a59a6c81
Commits

Reviewing files that changed from the base of the PR and between 9c9e583 and 5cc7656.

Files selected for processing: 77

  • CHANGELOG.md
  • README.md
  • crates/geordi-ir/src/lib.rs
  • crates/geordi-ir/src/ray_traced_scene.rs
  • crates/geordi-ir/src/ray_traced_scene/tests.rs
  • crates/geordi-renderer/src/lib.rs
  • crates/geordi-renderer/src/ray_traced_tests.rs
  • docs/ERROR_CODES.md
  • docs/README.md
  • docs/STATUS.md
  • docs/design/2026-11-fixed-point-and-ray-traced-scene-profiles.md
  • docs/design/README.md
  • docs/ray-traced-scene-profile.md
  • fixtures/ray-traced-scene/README.md
  • fixtures/ray-traced-scene/failures/albedo-above-one.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/camera-forward-zero.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/camera-kind-orthographic.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/camera-outside-trace-domain.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/camera-up-parallel.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/camera-up-zero.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/directional-without-toward-light.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/expected-diagnostics.json
  • fixtures/ray-traced-scene/failures/film-too-wide.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/film-zero-height.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/instance-material-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/instance-mesh-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/instance-outside-trace-domain.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/integrator-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/json-invalid.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/light-kind-point.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/material-id-duplicate.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/material-kind-specular.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/max-bounces-two.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-bounds-inverted.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-count-negative.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-file-missing.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-hash-malformed.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-hash-mismatch.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-layout-ascii.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/mesh-path-escapes.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/missing-field.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-beyond-i64.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-exponent.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-fraction.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-negative-zero.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-null.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-out-of-range.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/number-string.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/numeric-profile-binary64.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/output-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/primitive-count-exceeded.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/radiance-above-cap.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/radiance-negative.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/reconstruction-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/requirement-duplicate.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/requirement-profile-missing.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/requirement-unknown.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/requirement-used-feature-missing.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/sampler-malformed.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/samples-above-limit.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/samples-not-power-of-two.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/scene-id-empty.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/scene-version-unsupported.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/seed-out-of-range.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/sky-missing.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/sky-toward-light-null.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/sky-with-toward-light.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/tan-half-fov-y-above-four.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/tan-half-fov-y-zero.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/tone-curve-malformed.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/toward-light-not-normalized.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/toward-light-zero.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/two-directional-lights.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/two-skies.rt-scene.geordi.json
  • fixtures/ray-traced-scene/failures/unknown-field.rt-scene.geordi.json
  • fixtures/ray-traced-scene/meshes/unit-quad.ply
  • fixtures/ray-traced-scene/reference.rt-scene.geordi.json
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Identities are recognized at runtime negotiation, not by the artifact validator, and -0 is rejected rather than normalized. Both were choices made while implementing #153; the accepted design now says so.
@flyingrobots
flyingrobots merged commit fe8b95b into main Nov 14, 2026
2 checks passed
@flyingrobots
flyingrobots deleted the feat/ray-traced-scene-profile branch November 14, 2026 01:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Implement the ray-traced 3D scene profile and its validator

1 participant