Official Codebase of 3DCodeVerse
Python
skills: four bundles — bbox contract, cadquery forms, scene lighting, opengl pipeline
gaoypeng7391ac7a05c4
diff --git a/harness/codeverse/skills/_claims/cv3d-bbox-contract.toml b/harness/codeverse/skills/_claims/cv3d-bbox-contract.tomlnew file mode 100644index 00000000..5bcd0d38--- /dev/null+++ b/harness/codeverse/skills/_claims/cv3d-bbox-contract.toml@@ -0,0 +1,21 @@+# Numbers this bundle quotes, pinned to the constants the contract gate actually reads.+# Move BBOX_TOLERANCE_M / REL_TOL / ERROR_FACTOR and the test that ships this skill fails.++[[claim]]+key = "bbox_tolerance_m"+text = "1 cm"+python = "codeverse.conventions:BBOX_TOLERANCE_M"+scale = 100+format = "{:.0f} cm"++[[claim]]+key = "bbox_rel_tol"+text = "0.10"+python = "codeverse.spatial.contract:REL_TOL"+format = "{:.2f}"++[[claim]]+key = "bbox_error_factor"+text = "3x"+python = "codeverse.spatial.contract:ERROR_FACTOR"+format = "{:.0f}x"diff --git a/harness/codeverse/skills/_claims/cv3d-opengl-pipeline.toml b/harness/codeverse/skills/_claims/cv3d-opengl-pipeline.tomlnew file mode 100644index 00000000..2cb98076--- /dev/null+++ b/harness/codeverse/skills/_claims/cv3d-opengl-pipeline.toml@@ -0,0 +1,19 @@+# gl_frames thresholds, pinned to the module the gate reads them from.++[[claim]]+key = "gl_static_diff"+text = "0.002"+python = "codeverse.spatial.frame_stats:STATIC_DIFF"+format = "{:.3f}"++[[claim]]+key = "gl_flicker_diff"+text = "0.35"+python = "codeverse.spatial.frame_stats:FLICKER_DIFF"+format = "{:.2f}"++[[claim]]+key = "gl_low_detail_edge"+text = "0.002"+python = "codeverse.spatial.frame_stats:LOW_DETAIL_EDGE"+format = "{:.3f}"diff --git a/harness/codeverse/skills/_claims/cv3d-scene-lighting.toml b/harness/codeverse/skills/_claims/cv3d-scene-lighting.tomlnew file mode 100644index 00000000..e38bbec5--- /dev/null+++ b/harness/codeverse/skills/_claims/cv3d-scene-lighting.toml@@ -0,0 +1,36 @@+# The four thresholds this bundle quotes are the ones scene_frames actually applies.+# Move one and the test that ships this skill fails, which is the point.++[[claim]]+key = "scene_dark_mean_lum"+text = "0.12"+python = "codeverse.spatial.frame_metrics:DARK_MEAN_LUM"+format = "{:.2f}"++[[claim]]+key = "scene_dark_frac"+text = "35 %"+python = "codeverse.spatial.frame_metrics:DARK_FRAC"+scale = 100+format = "{:.0f} %"++[[claim]]+key = "scene_blown_frac"+text = "20 %"+python = "codeverse.spatial.frame_metrics:BLOWN_FRAC"+scale = 100+format = "{:.0f} %"++[[claim]]+key = "scene_flat_modal_frac"+text = "85 %"+python = "codeverse.spatial.frame_metrics:FLAT_MODAL_FRAC"+scale = 100+format = "{:.0f} %"++[[claim]]+key = "scene_flat_modal_error"+text = "92 %"+python = "codeverse.spatial.frame_metrics:FLAT_MODAL_ERROR"+scale = 100+format = "{:.0f} %"diff --git a/harness/codeverse/skills/cv3d-bbox-contract/SKILL.md b/harness/codeverse/skills/cv3d-bbox-contract/SKILL.mdnew file mode 100644index 00000000..439e3ab7--- /dev/null+++ b/harness/codeverse/skills/cv3d-bbox-contract/SKILL.md@@ -0,0 +1,84 @@+---+name: cv3d-bbox-contract+description: Hit the plan's dimensions on the first build. Use whenever this session owns a part's or the object's size or placement — baseline, part, detail, refine, rebuild, zone — and on every repair round where the contract gate fired. Covers the tolerance the gate really uses (relative, not a flat millimetre figure), how instanced parts are measured, ground contact and footprint, part-name matching, and how to prove the numbers with measure / check_contract instead of by eye.+license: Apache-2.0+metadata:+ evidence: measured+ verified: 2026-08-25+ corpus: bench/out, 142 graded records with gate artefacts, recomputed 2026-08-25+---++# The plan's numbers are the contract++Read this before you type a dimension. Every number in `plan.json` is a promise the+`contract` gate measures against the exported GLB, in the plan's own authoring frame —+which is why every fix hint it writes is already labelled with that frame and is safe to+paste straight into your code.++## What the gate actually allows++Per axis, `tol = max(1 cm, 0.10 x the planned extent on that axis)`+(`codeverse/spatial/contract.py`, `codeverse/conventions.py`). A deviation past `tol` is a+WARN; past **3x** `tol` it is an ERROR.++| planned extent | tolerance on that axis | in relative terms |+|---|---|---|+| 3 cm | 1 cm | 33 % |+| 10 cm | 1 cm | 10 % |+| 50 cm | 5 cm | 10 % |+| 2 m | 20 cm | 10 % |++The absolute floor rules small parts and the relative term rules large ones. So a 4 cm+bracket may wander a full centimetre, and a 2 m beam that comes out 25 cm short is an+ERROR, not a rounding difference.++## What actually goes wrong (recomputed from `bench/out` 2026-08-25, 142 graded records with gate artefacts)++* part bbox deviates — **75 runs (52.8 %)**; overall bbox — 44 (31.0 %); per-instance —+ 29 (20.4 %); footprint off the up axis — 21 (14.8 %).+* Of 978 bbox findings, **673 name only the size**, 133 only the centre, 172 both. This is+ overwhelmingly a *size* defect, not a placement defect.+* Out-of-tolerance axes run **713 undersized to 394 oversized**. The usual story is a part+ built as its core shape while the plan's extent included the trim, flange or overhang.+* Median worst deviation is **1.47x tolerance**, p90 2.86x. Most failures are one axis+ missing by a hair — arithmetic you could have checked before building, not a redesign.++## Rules++1. **Type every plan number once.** Each dimension becomes one named constant at the top of+ the file; everything else is derived from those constants. A number typed twice is a+ number that will disagree with itself.+2. **Derive a spanning dimension from its neighbours' bounds, never re-type it.** A shelf+ that spans two uprights is `inner_span = pitch - upright_thickness + 2 * weld`, computed+ from the constants the uprights already used. Re-typing "0.58" is how the 1.47x median+ miss is made.+3. **Budget for what the modifiers do to the bounding box.** The gate measures the built+ AABB, after everything. A bevel, chamfer or fillet *shrinks* the silhouette; a solidify,+ skin or subdivision surface pulls a cage *inward*; an outline offset grows it. If the+ plan says 88 mm and your bevel eats 9 mm, you shipped 79 mm and the gate says so.+4. **Instanced parts are measured on extents only.** For a part with `instances > 1` the+ gate reads the plan box two ways — as the size of ONE copy, and as the union of all+ copies — and keeps whichever fits better, so building either reading is accepted. It+ does **not** check the centre of an instanced part (it cannot know which copy is which).+ A wrong *count* is a separate WARN: name the copies `Name_0 .. Name_N-1`.+5. **Sit on the ground and centre the footprint.** Lowest point at zero: a gap beyond 1 cm+ is a WARN and beyond 3 cm an ERROR, with the exact translation in the hint. The+ footprint centre must be within `max(1 cm, 10 % of the larger horizontal extent)` of the+ up axis — that one is always a WARN and always fixable by one translate.+6. **Names are the join key.** Parts match by their snake-cased name; the exact name is+ claimed first and `Name_0..Name_N` afterwards. A plan part with no matching node is an+ ERROR ("missing from the GLB"); an extra node the plan never mentioned is only INFO. So+ a spare helper node is cheap and a misspelt part name is expensive.++## Prove it, do not eyeball it++`build` -> `measure` -> `check_contract`. `measure` gives you per-part size in cm and the+ground gap; `check_contract` gives you, per failing part, the built size against the planned+size, the per-axis delta, the planned centre and the frame those numbers are written in.+Fix the largest ratio first — the message states it ("worst 3.4x tolerance"), so you always+know which finding is the ERROR.++`isolate <PartName>` renders one part alone with its measurement row when a delta does not+make sense.++Worked example of turning a real fix hint into an edit: `references/reading-a-fix-hint.md`.diff --git a/harness/codeverse/skills/cv3d-bbox-contract/references/reading-a-fix-hint.md b/harness/codeverse/skills/cv3d-bbox-contract/references/reading-a-fix-hint.mdnew file mode 100644index 00000000..35f74e52--- /dev/null+++ b/harness/codeverse/skills/cv3d-bbox-contract/references/reading-a-fix-hint.md@@ -0,0 +1,74 @@+# Reading a contract fix hint and turning it into one edit++Every example below is a real `fix_hint` string from `bench/out` (mined 2026-08-25). The+gate writes the numbers in the language's authoring frame, so they can be used directly.++## 1. One axis short — the common case++```+part 'FacetedRoofCap' bbox deviates from the plan (worst 2.2x tolerance)+part 'FacetedRoofCap': size 262.0x79.2x55.1 vs planned 262.0x88.0x54.0 cm+ (D x-0.0cm, y-8.8cm, z+1.1cm); planned centre (0.000, -0.060, 2.880) m+```++Read it as: two axes are fine, the depth is 8.8 cm short on a planned 88 cm — a clean 10 %,+which is exactly the relative tolerance, so it tipped over at 2.2x. The cap was almost+certainly built from a profile whose depth constant was the *inner* span while the plan+meant the outer one, or a bevel ate the overhang. The edit is one constant, not a rebuild.++Anti-pattern: scaling the whole object by 88/79.2 to "fix the number". That trades one+finding for a wrong overall bbox and a broken contact graph.++## 2. Centre only — the part is the right size, in the wrong place++```+part 'FrontApron': centre off by (x+0.0cm, y-3.0cm, z-0.0cm);+ planned centre (0.000, -0.200, 0.402) m+```++No size clause at all, so the geometry is correct and only the placement is wrong. Move the+part by the negation of the delta. Do not touch its dimensions.++## 3. Both — a part that grew from one end++```+part 'LeftBraceLower': size 18.1x2.3x15.7 vs planned 22.0x3.0x20.0 cm+ (D x-3.9cm, y-0.7cm, z-4.3cm); centre off by (x+2.2cm, y+0.4cm, z-0.6cm)+```++A size delta with roughly half of it echoed in the centre means the part was built from a+fixed origin and stopped short: one end stayed put, the other never reached. Fix the length+constant and the centre follows; correcting the centre alone leaves the size wrong.++## 4. Instances++```+'FrontLeg' (each instance): size 6.5x7.0x30.1 vs planned 3.5x7.0x28.0 cm+ (D x+3.0cm, y-0.0cm, z+2.1cm)+```++`(each instance)` means the gate compared the plan box with the size of ONE copy — here a+3.5 cm leg came out 6.5 cm, most likely a radius used where a diameter was planned. The+other wording, `(all instances)`, means it compared the plan box with the union of every+copy. The gate picks whichever reading is closer to the plan, so you never have to guess+which one the planner meant: build one copy at the planned size and the per-instance+reading passes; build a set whose union matches and the union reading passes.++## 5. Footprint and ground++```+translate everything by (-0.019, +0.006, +0.000) m to centre the footprint+object floats 130.0 mm above the ground+```++Both hints hand you the vector. Apply it to the top-level container, once, at the end of+construction — not per part, or the parts drift relative to each other and the contact+graph changes.++## Order of work on a repair round++1. `check_contract`, and sort the findings by the "worst Nx tolerance" number in the message.+2. Fix ERRORs (ratio above 3x) first; they are the only ones that fail the gate.+3. Change constants, never the built geometry, wherever a constant exists.+4. `build` -> `check_contract` again. A fix that moves a second part into failure means the+ two shared a derived number and one of them was re-typed.diff --git a/harness/codeverse/skills/cv3d-cadquery-forms/SKILL.md b/harness/codeverse/skills/cv3d-cadquery-forms/SKILL.mdnew file mode 100644index 00000000..071ab85d--- /dev/null+++ b/harness/codeverse/skills/cv3d-cadquery-forms/SKILL.md@@ -0,0 +1,92 @@+---+name: cv3d-cadquery-forms+description: Build the planned forms in CadQuery and get past the OCC kernel on the first try. Use for any session writing src/model.py in CadQuery — baseline, part, detail, refine, rebuild or repair. Gives the form-to-technique decision table, the fillet / revolve / boolean rules that decide whether the script builds at all, and the four traps our own lint and runtime wrapper are written to catch.+license: Apache-2.0+compatibility: CadQuery 2.8 on OCP; one module src/model.py exporting a module-level `result`.+metadata:+ evidence: inherited-unverified+ evidence_note: 'Every kernel rule below was probed against the CadQuery 2.8.0 installed in this repo on 2026-08-25 and cross-checked with the cadquery lint, the run_cq wrapper and the language contract. What is NOT available is score evidence. This harness has ZERO graded cadquery bench runs, so nothing here is ranked by measured defect frequency the way the blender and urdf bundles are. Routed off by default until cadquery has 20 graded runs.'+ verified: 2026-08-25+---++# CadQuery: forms, and the kernel rules that gate them++**Evidence warning, read it once:** we have no graded CadQuery runs. The API rules below are+verified against the installed kernel; the *priority order* is inferred, not measured.++## Form to technique++Plans and judge feedback name language-neutral forms. Build each one as its own kind of+solid — a revolved profile faked from stacked boxes reads as a blocky toy.++| form | build it as |+|---|---|+| slab / block / panel | `.box(x, y, z)`, `centered=(True, True, False)` to stand on zero |+| shaft / disc / cylinder | `.circle(r).extrude(h)`; `.cylinder(h, r)` takes height FIRST |+| revolved profile — vase, finial, baluster, dome, barrel | closed half-profile on `"XZ"` (`.polyline`/`.spline` + `.close()`) then `.revolve(360, (0,0,0), (0,1,0))`; keep the profile at radius >= 0 |+| ring / band / torus | `.moveTo(R, 0).circle(r).revolve(angle, ...)` — see the revolve trap below |+| extruded outline with softened edges | outline `.polyline().close().extrude(t)`, then `.edges("|Z").fillet(r)` |+| tube swept along a path | `.circle(r).sweep(path)`; the profile plane must be perpendicular to the path start |+| tapered solid — horn, spout, mast | `.circle(r1).workplane(offset=h).circle(r2).loft()`, or `.extrude(h, taper=deg)` |+| lofted transition between sections | `.loft()` between profiles with matching vertex counts (circle to circle, rect to rect) |+| shell with wall thickness | `.faces(">Z").shell(-t)` from ONE open face; never on a lofted round body — subtract a shrunken inner loft instead |+| carved cavity / slot / bore | `.cut(cutter)`, `.hole(d)`, `.cutBlind(-depth)` |+| faceted solid — die, gem | `.polygon(n, d).extrude(h)`, facets via `taper=` or a loft between polygons |+| radial array of N | `.polarArray(radius, start, angle, count)` before the feature; loops of `.union` only up to ~12 items |+| mirror pair | `.mirror("XZ")` on the piece, then place both in the Assembly |++## Kernel rules — probed against CadQuery 2.8.0 in this repo, 2026-08-25++1. **`.center()` before a revolve is fatal; use `.moveTo()`.** `Workplane("XZ").center(R, 0)+ .circle(r).revolve(360, ...)` raises `StdFail_NotDone: BRep_API: command not done`. The+ identical chain with `.moveTo(R, 0)` builds a valid torus. `.center()` moves the+ workplane origin, so the profile ends up sitting on the axis. Passing an explicit axis+ does not rescue it — both forms fail.+2. **Fillet failure is not monotone in the radius, so stay well under the budget.** On a+ 3 mm slab a top-rim fillet succeeded at 2.9 mm and failed at 3.0 mm; on a 3 mm shelled+ wall it succeeded at 1.4 mm, failed at 1.5 mm, succeeded again at 2.0 mm and failed at+ 3.0 mm. "Try a slightly bigger radius" is therefore not a strategy. Keep radii below+ **0.45 x the thinnest adjacent wall** — the budget the language contract states and the+ exact hint the runtime appends to every OCC refusal — fillet before booleans that would+ split the edge, biggest radii first, and wrap purely cosmetic fillets in `try/except`.+ (The common claim that the limit is half the shortest adjacent *edge* is false here: a+ 10 mm radius on a 10 mm vertical edge builds fine.)+3. **A union that does not overlap fails silently.** Two spheres placed exactly tangent+ union into **2 solids** and still report `isValid() == True`; the same pair with 0.5 mm+ of overlap gives 1 solid. `.isValid()` will not catch this and neither will a render.+ Assert `len(wp.solids().vals()) == 1` after every union and every cut — a through cut+ that splits a part also leaves 2 valid solids.+4. **`.cut()` is for removing material only.** Do not union across plan boundaries; each+ plan part stays its own solid in the Assembly. Overshoot cutters by >= 0.1 mm.+5. **Touching parts weld by overlapping >= 2 mm.** That figure is the CadQuery authoring+ contract's own, and it is the overlap the worked examples in the cookbook use; the+ connectivity gate's contact and penetration thresholds are stated once, in+ `cv3d-part-contact`, and are not repeated here.+6. **Keep solids closed.** Export runs through STL as well as GLB; `.shell()` keeps a solid+ watertight, hand-assembled faces do not.+7. Feature sizes >= 0.5 mm (OCC's tolerance eats smaller), <= 40 parts, build under 120 s.++## The four traps our own tooling is written to catch++* **No module-level `result`** — ERROR from `lint:cadquery`. It must not live under+ `if __name__ == "__main__":`, and `sys.exit()` before it is set is its own error.+* **`result` that is not a `cq.Assembly`** — the whole model exports as ONE node called+ `Object`, so the contract gate reports *every* plan part missing. Use+ `result.add(solid, name="PascalName", color=cq.Color(r, g, b))` per plan part; an `.add()`+ without `name=` gets a uuid node name and has the same effect.+* **A trailing selector** — a chain ending `.faces(">Z")` leaves Face objects on the stack.+ The wrapper recovers the parent solid and warns; end the chain on the solid.+* **Radians into a degrees argument** — `.rotate(p0, p1, angle)`, `cq.Location(v, axis, deg)`,+ `.revolve(deg)` and `twistExtrude(h, deg)` all take degrees. A `math.pi` expression in that+ slot is a lint ERROR. Also `cq.Solid.makeSphere(r)` without angle arguments builds a+ hemisphere (measured: z extent half of x and y); use `cq.Workplane("XY").sphere(r)`.++## Before you finish++Print the facts the harness will measure while you build — extents, `zmin`,+`len(solids().vals())`, `Volume()`, `isValid()` per part — then `build` -> `render_sheet` ->+`check_connectivity` -> `check_contract`. Code to copy: cookbook `cadquery` sections+*Extrude, revolve, loft, sweep*, *Shell, fillet, chamfer — robustly*, *Booleans*,+*Measure while you build*, *Pitfalls*.++More probe results and the failing/passing chains: `references/kernel-probes.md`.diff --git a/harness/codeverse/skills/cv3d-cadquery-forms/references/kernel-probes.md b/harness/codeverse/skills/cv3d-cadquery-forms/references/kernel-probes.mdnew file mode 100644index 00000000..a8df5e3f--- /dev/null+++ b/harness/codeverse/skills/cv3d-cadquery-forms/references/kernel-probes.md@@ -0,0 +1,72 @@+# CadQuery kernel probes — run against the CadQuery 2.8.0 in this repo, 2026-08-25++Each result below is a run, not a recollection. Reproduce any of them in a scratch script.++## Revolve: `.moveTo` vs `.center`++| chain (R = 50 mm, r = 8 mm, plane `"XZ"`) | result |+|---|---|+| `.moveTo(R, 0).circle(r).revolve(360, (0,0,0), (0,1,0))` | valid torus, 1 solid, bbox 116 x 116 x 16 mm |+| `.moveTo(R, 0).circle(r).revolve(360)` (default axis) | same valid torus |+| `.center(R, 0).circle(r).revolve(360, (0,0,0), (0,1,0))` | `StdFail_NotDone: BRep_API: command not done` |+| `.center(R, 0).circle(r).revolve(360)` | `StdFail_NotDone: BRep_API: command not done` |++An explicit axis does not save `.center()`: the workplane origin moved with it, so the+profile is sitting on the axis of revolution either way.++## Fillet: where OCC actually refuses++100 x 60 x 10 mm box, fillet on the four vertical edges (each 10 mm long):++| radius | 2 mm | 4 mm | 4.5 mm | 5 mm | 6 mm | 10 mm |+|---|---|---|---|---|---|---|+| result | ok | ok | ok | ok | ok | ok |++A radius equal to the whole edge length builds. So the widely repeated "radius must be+under half the shortest adjacent edge" is not the rule here.++100 x 60 x **3 mm** slab, fillet on the top rim (the adjacent wall is 3 mm):++| radius | 2.0 | 2.4 | 2.6 | 2.8 | 2.9 | 3.0 |+|---|---|---|---|---|---|---|+| x thickness | 0.67 | 0.80 | 0.87 | 0.93 | 0.97 | 1.00 |+| result | ok | ok | ok | ok | ok | **StdFail_NotDone** |++Cylinder shelled to a 3 mm wall, then a rim fillet:++| radius | 0.5 | 1.0 | 1.4 | 1.5 | 2.0 | 3.0 |+|---|---|---|---|---|---|---|+| x wall | 0.17 | 0.33 | 0.47 | 0.50 | 0.67 | 1.00 |+| result | ok | ok | ok | **fail** | ok | **fail** |++The failures are **not monotone** — 1.5 mm fails while 2.0 mm succeeds. That is the whole+argument for a conservative fixed budget (0.45 x the thinnest adjacent wall, which is the+number the contract states and the number the runtime prints when OCC refuses) plus+`try/except` around fillets that are only cosmetic. Incrementally nudging the radius after a+failure can appear to work and then break on a neighbouring part.++## Booleans: the silent failures++| operation | solids | `isValid()` |+|---|---|---|+| union of two spheres placed exactly tangent | **2** | True |+| union of the same spheres with 0.5 mm overlap | 1 | True |+| box cut through by a full-width cutter | **2** | True |++`isValid()` is not a connectivity check. The only reliable assertion is+`len(wp.solids().vals()) == 1` on anything that is supposed to be one part.++An exactly-coplanar cutter (top face flush with the block's face) succeeded in this probe+and produced the same face count as an overshooting cutter — but the cookbook records the+failing case, so keep the >= 0.1 mm overshoot as a habit rather than relying on luck.++## Sphere helper++`cq.Solid.makeSphere(0.02)` -> bbox 40 x 40 x **20** mm: a hemisphere.+`cq.Workplane("XY").sphere(0.02)` -> bbox 40 x 40 x 40 mm. The lint warns on the first form.++## Trailing selector++`cq.Workplane("XY").box(...).faces(">Z")` leaves `Face` objects on the stack. The harness+wrapper falls back to `findSolid()` and records a warning; a chain that ends on a selector+with no recoverable parent is a hard export error.diff --git a/harness/codeverse/skills/cv3d-opengl-pipeline/SKILL.md b/harness/codeverse/skills/cv3d-opengl-pipeline/SKILL.mdnew file mode 100644index 00000000..0c4a14dc--- /dev/null+++ b/harness/codeverse/skills/cv3d-opengl-pipeline/SKILL.md@@ -0,0 +1,108 @@+---+name: cv3d-opengl-pipeline+description: Write a raw OpenGL / moderngl program that renders what the brief asked for. Use for any opengl_python session - baseline, refine, repair or rebuild - and whenever the gl_frames gate reported flicker, no motion or a near-flat image. Covers the setup / render contract, the sampled-time trap that breaks every feedback simulation, VAO and uniform mechanics, ping-pong FBOs, and the three richness rules the judge scores this language worst on.+license: Apache-2.0+compatibility: OpenGL 3.3 core through moderngl, headless EGL; one module src/program.py, GLSL 330 core inline or in src/*.glsl.+metadata:+ evidence: measured+ evidence_note: 'Thin but real, and labelled so in the body. 5 graded opengl_python runs across graphics_v1_flash and graphics_v2_flash, 10 judged rounds, recomputed 2026-08-25. The API facts come from the runtime wrapper and the lint, not from the corpus.'+ verified: 2026-08-25+---++# The moderngl pipeline, and the two things that actually sink these runs++## The contract in four lines++`setup(ctx, width, height) -> state` is called **once**. `render(ctx, state, t, frame, fbo)`+is called once per sampled time; `fbo` arrives already bound, cleared to black with depth 1,+and with the viewport set. If you render into your own framebuffers you must call+`fbo.use()` and reset `ctx.viewport` before the **final** pass — the harness reads that+framebuffer and nothing else. Never create a context and never touch `ctx.screen`.++## Trap 1: `render()` is sampled, not ticked++The judged times are **t = 0, 1, 2.5, 4 and 6 s** — five calls, with unequal gaps, and with+about a dozen more interleaved when the preview GIF is on (so `frame` indexes the merged+sorted schedule, not the judged frames). There is no `dt` and there is no 60 Hz loop.++A simulation that advances one step per `render()` call therefore gets **five steps in+total**. This is not hypothetical: two of our 5 graded opengl_python runs were ping-pong+feedback effects, and they scored **0.19 and 0.48** (`graphics_v2_flash`, mined+2026-08-25) - the lowest and third-lowest of the five. The judge wrote *"the interior of+the seeds dies out"*, *"only expanding rings rather than labyrinthine patterns"*, *"ink is+only injected at t=0s"* and *"the ink dissipates far too quickly"*. Those are all the same+defect: five iterations of a solver that needed hundreds.++The fix is to make the frame a pure function of `t`, and get the iterations inside+`render()`:++* pick a fixed simulation step, e.g. `DT = 1/120`, and run `n = round(t / DT)` steps;+* keep the state and the time it represents in `state`; each call advances from+ `state["t_sim"]` to `t`, and **resets to the seed whenever `t < state["t_sim"]`** so an+ out-of-order or repeated sample still gives the same image;+* cap the work per call (a few thousand steps) so the build does not time out;+* inject sources as a function of `t`, not once at `frame == 0`.++## Trap 2: motion has to be continuous *and* visible++`gl_frames` measures the mean absolute difference between consecutive frames. Below+**0.002** it calls the program static; above **0.35** it calls it flicker. Only one of our+five opengl_python runs ever tripped this gate, but it tripped it in three separate rounds+(max deltas 0.373, 0.392, 0.416, `ogl_hard_voxel_city`, final score 0.342), and the judge+read the same frames as *"the camera motion is discontinuous or clips into a building,+resulting in a hard cut"*. Since the samples are 1 to 2 s apart, a camera or a phase that+is fine at 60 fps can still jump between samples. Drive every animated quantity+from a smooth function of `t`, and check the amplitude *between the sampled times*, not per+frame: `fract()`/`mod()` wraps and per-call randomness are the usual culprits.++## API mechanics that cost a build++* **Attribute names must match the shader's `in` names**, and the format string must match+ the byte layout: `[(vbo, "3f 3f", "in_pos", "in_normal"), (ibo, "3f 3f 1f/i", ...)]`. A+ wrong float count does not raise — it silently shuffles your data into garbage.+* **numpy is row-major, GLSL is column-major**: `prog["u_mvp"].write(M.T.astype("f4").tobytes())`.+ Never `.value = m.tolist()`.+* **`KeyError: 'u_x'`** means the compiler removed an unused uniform. Delete the assignment+ or guard with `if "u_x" in prog`.+* **Your own FBOs need their own depth attachment and their own `.clear()`** — `ctx.clear()`+ clears whatever is bound. Disable `DEPTH_TEST` for full-screen passes.+* **Ping-pong needs two textures**; never sample the one you are writing. Give a simulation+ state texture `NEAREST` filtering and clamped wrap — `LINEAR` diffuses the state a little+ every step and `repeat` wraps the domain — and store it as `f4`, not `f2` (half float+ clips near 65504 and quantises visibly in a feedback loop).+* Textures need `.use(location=k)` **every frame** as well as `prog["u_tex"].value = k`.+* `#version 330 core` on the first line of every shader string, `out vec4 fragColor;`, no+ `gl_FragColor`, no `attribute`/`varying`. Wide lines and `GL_QUADS` do not exist in core.+* Seed with `np.random.default_rng(SEED)` in `setup`; no wall clock, no extra python module+ (the harness ignores anything but `src/program.py`, and the lint warns).++## Make the image worth judging++Over 5 runs and 10 judged rounds (`graphics_v1_flash` + `graphics_v2_flash`, recomputed+2026-08-25) this language's three weakest criteria are **originality 0.330**,+**visual_richness 0.375** and **brief_fidelity 0.420** — the lowest three numbers anywhere+in our corpus. The gate agrees from the other side: edge density below **0.002** is+reported as *"a near-flat gradient"*.++Three rules that answer exactly those readings:++1. **Layer at least three depths.** Background, subject, foreground. One full-screen+ gradient with a shape on it is the flat-gradient finding waiting to happen; parallax+ between layers also supplies the frame-to-frame delta.+2. **No single primitive carrying the frame.** Edge density comes from silhouettes and+ high-frequency shading — instanced geometry, particles, structure inside surfaces — not+ from a smooth ramp.+3. **Spend the brief's own nouns.** `brief_fidelity` 0.420 says the frames were generic.+ Every named element in the brief should be findable in the image; build the named thing+ rather than an abstraction that gestures at it.++## Prove it++`gl_probe` after every edit (one frame, compile errors with source line numbers), then+`gl_frames` before finishing — it renders the judged times, returns the per-frame+luminance / colour / detail / motion table and runs the gate. **Look at the contact sheet.**++Code to copy: cookbook `opengl_python` sections *VBO / VAO with interleaved attributes*,+*Instancing*, *Uniforms and matrices*, *FBOs*, *PITFALLS*.++A worked sampled-time feedback loop and the frame-metric table: `references/sampled-time.md`.diff --git a/harness/codeverse/skills/cv3d-opengl-pipeline/references/sampled-time.md b/harness/codeverse/skills/cv3d-opengl-pipeline/references/sampled-time.mdnew file mode 100644index 00000000..ec9511cc--- /dev/null+++ b/harness/codeverse/skills/cv3d-opengl-pipeline/references/sampled-time.md@@ -0,0 +1,88 @@+# Sampled time: how a feedback effect survives five render calls++## What the harness does++`codeverse/languages/opengl_python/wrappers/run_gl.py` builds one sorted schedule from the+judged times and the preview times, then for each entry binds the harness framebuffer,+clears it to `(0, 0, 0, 1)` with depth 1, sets the viewport, and calls+`render(ctx, state, t, i, fbo)`. `i` is the index into that merged schedule.++Judged times are `0, 1, 2.5, 4, 6` (`codeverse/languages/_gl_common.py`, clipped to the+loop duration, always at least 3 samples). The preview GIF adds about a dozen more. So:++* the number of calls is not fixed, and `frame == 2` is not "the third judged frame";+* the gaps between judged frames are 1.0, 1.5, 1.5 and 2.0 seconds;+* nothing guarantees the calls are the only ones, or that they will not be repeated.++The only safe contract is the one the language contract already states: **the same `t` must+produce the same image.**++## The shape of a correct feedback loop++```python+DT = 1.0 / 120.0 # simulation step+MAX_STEPS = 4000 # keep the build inside its timeout++def _reset(state):+ state["read"].write(state["seed_bytes"])+ state["t_sim"] = 0.0++def _advance(ctx, state, t):+ if t < state["t_sim"] - 1e-6:+ _reset(state)+ n = min(MAX_STEPS, int(round((t - state["t_sim"]) / DT)))+ for _ in range(n):+ state["write_fbo"].use()+ state["read"].use(location=0)+ state["sim_vao"].render(mode=moderngl.TRIANGLE_STRIP)+ state["read"], state["write"] = state["write"], state["read"]+ state["read_fbo"], state["write_fbo"] = state["write_fbo"], state["read_fbo"]+ state["t_sim"] += n * DT+```++`render()` then calls `_advance(ctx, state, t)`, binds `fbo`, resets the viewport and draws+the display pass from `state["read"]`. Note what this buys: t = 0 gets the seed, t = 6 gets+720 steps instead of 5, and re-rendering an earlier time still produces the earlier image.++Sources (ink injections, seeds, disturbances) belong inside the step loop as a function of+the simulated time, not in a `if frame == 0:` branch — the judge explicitly marked one of+our runs down for *"ink is only injected at t=0s"*.++## State texture settings that matter++| setting | why |+|---|---|+| `dtype="f4"` | `f2` quantises visibly after a few hundred feedback steps and clips near 65504 |+| `filter = (NEAREST, NEAREST)` | `LINEAR` blurs the state slightly on every read; over hundreds of steps that is a diffusion term you did not ask for |+| `repeat_x = repeat_y = False` | otherwise the domain wraps and structures reappear on the opposite edge |+| two textures, swapped | reading and writing one texture in a single pass is undefined |++## The frame metrics the gate reads++`codeverse/spatial/frame_stats.py`:++| metric | threshold | finding |+|---|---|---|+| mean abs frame-to-frame delta | < 0.002 | static (WARN) |+| mean abs frame-to-frame delta | > 0.35 | flicker (WARN) |+| consecutive frames identical | delta < 1e-4 | duplicate (INFO) |+| mean edge density | < 0.002 | near-flat gradient (WARN) |+| mean luminance | < 0.03 all frames | black (ERROR) |+| mean luminance | > 0.98 all frames | blown (ERROR) |+| any NaN / Inf pixel | any | ERROR |++The gate's own advice for luminance is to aim for a mean between 0.2 and 0.6.++## Measured deltas from our own runs++`graphics_v1_flash` + `graphics_v2_flash`, 5 graded opengl_python runs, mined 2026-08-25.+The gate fired on exactly one of them - `ogl_hard_voxel_city`, final score 0.342 - but it+fired repeatedly: flicker in three separate rounds, with max frame-to-frame deltas of+0.373, 0.392 and 0.416, each barely over the 0.35 line, and each caused by a+discontinuity between two samples 1.5 to 2 seconds apart rather than by per-frame noise.+The same run also produced `edge density 0.0000`, an entirely smooth image. So the gate is+a weak signal at n=5; the judged criteria below are the stronger one.++Judged criterion means for this language over the same 10 rounds: originality 0.330,+visual_richness 0.375, brief_fidelity 0.420, motion_quality 0.510, composition 0.515,+technical_cleanliness 0.605, colour_light 0.610.diff --git a/harness/codeverse/skills/cv3d-scene-lighting/SKILL.md b/harness/codeverse/skills/cv3d-scene-lighting/SKILL.mdnew file mode 100644index 00000000..73bf1a70--- /dev/null+++ b/harness/codeverse/skills/cv3d-scene-lighting/SKILL.md@@ -0,0 +1,96 @@+---+name: cv3d-scene-lighting+description: Light a three.js scene so the frame gate passes and the mood still reads. Use in a scene baseline, env or refine session, and on any round where scene_frames called a frame too dark, blown out or flat. Gives the exact thresholds the gate measures, the key / fill / practical recipe with numbers, and the one thing hex colours hide - how dark an albedo really is once the renderer works in linear light.+license: Apache-2.0+compatibility: three r0.182, headless WebGL; renderer fixed at ACES Filmic tone mapping, exposure 1.0, sRGB output.+metadata:+ evidence: mixed+ evidence_note: 'Thresholds and renderer settings are read from live code, namely spatial/frame_metrics.py and runtime_js/lib/browser/renderer.js, and the luminance figures are computed from those settings. The corpus half is thin and labelled as such, being 4 scene_threejs runs in scenes_v1_flash mined 2026-08-25, so it is quoted as examples and never as a rate.'+ verified: 2026-08-25+---++# Lighting a scene the frame gate will accept++## What is measured, and how hard it bites++The harness renders every camera and scores the pixels (`spatial/frame_metrics.py`):++| finding | fires when | severity |+|---|---|---|+| too dark | mean luminance < **0.12** *or* > **35 %** of pixels near black | ERROR on an authored camera, WARN on a harness rig view |+| blown out | > **20 %** of pixels pure white | same |+| flat frame | one luminance band holds > **85 %** of pixels (> **92 %** makes it an ERROR on an authored camera) | WARN / ERROR |++Two consequences people get wrong:++* **The two dark conditions are independent.** A real finding from `scenes_v1_flash`:+ `frame too dark: mean luminance 0.07, 0% of pixels near black` — a frame with not one+ near-black pixel still failed, because the whole image was dim. Another in the same+ battery: `mean luminance 0.17, 43% of pixels near black` — bright enough on average,+ failed on the black fraction. Fix whichever one the message names.+* **Flat is a contrast failure, not a brightness failure.** Adding light to a flat frame+ usually makes it flatter. Of the 4 scene runs in `scenes_v1_flash` (mined 2026-08-25),+ two produced flat-frame findings and one produced ten separate dark-frame findings.++## Judge dark colours in linear, not in hex++The renderer is fixed: ACES Filmic tone mapping at exposure 1.0, sRGB output+(`runtime_js/lib/browser/renderer.js`). Every hex colour you write is decoded to linear+before any lighting happens, and hex badly understates how dark a dark colour is.++`0x1d3d22` foliage has a relative luminance of **0.037**. `0xf0f4f8` plaster has **0.900**.+That is **24x**, while the raw hex bytes are only about 6x apart. Under one key light, with+everything else equal:++| surface | key x0.5 | key x1 | key x2 |+|---|---|---|---|+| foliage `0x1d3d22` (albedo 0.037) | frame 0.07 | frame **0.15** | frame 0.27 |+| plaster `0xf0f4f8` (albedo 0.900) | frame 0.75 | frame 0.87 | frame 0.94 |++A scene made of dark foliage sits on the gate line **when it is fully lit**, and doubling+the key only moves it to 0.27. Neither more light nor more exposure changes the ratio — only+a lighter albedo does. So: lift the albedos of the large surfaces first, then light. Ground+albedo below about 0.25 is a scene that cannot pass without heroic lighting.++The same arithmetic says where the headroom is: mean frame luminance 0.12 corresponds to a+linear scene luminance of only ~0.03, and the tone curve is steep down there — going from+linear 0.02 to 0.05 moves the frame from 0.08 to 0.20. Small increases pay near the floor.++## The recipe++* **Tint, do not dim.** Dusk and night are coloured darkness. Turning the key down is not+ how you make dusk; changing its hue and the hemisphere's is. Take the whole row from the+ cookbook's time-of-day table rather than inventing a triad.+* **The sun is white at noon and warm only near the horizon.** A warm sun at high elevation+ reads as an error, not as mood.+* **The fill is the opposite hue from the key.** Hemisphere light is sky colour above,+ ground bounce below; keep its colour at least 60 degrees of hue from the sun's. Warm key+ plus warm fill is the monochrome-orange soup that gets marked down.+* **Emissive is a material, not a light.** An emissive surface glows in the image and+ illuminates nothing — and the default pipeline renders without bloom, so it must look+ right unaided. Pair every lantern, window or fire with a small PointLight.+* **Fog colour is the sky's horizon colour**, never white or grey unless the brief says+ overcast, and never a black background.++Working numbers, straight from the gate's own fix hint: DirectionalLight **2-4**,+HemisphereLight **0.5-1.0**, `emissiveIntensity` **2-6** with a PointLight **0.5-2** per+practical, and keep mean luminance **>= 0.15** so you are not sitting on the threshold. If+the frame is blown instead: key <= 3, hemisphere <= 1.0, sky below 0.9 white,+`emissiveIntensity` <= 4 on large surfaces.++For a flat frame, add contrast rather than light: a shadow-casting key, materials with+genuinely different albedos, and a camera aimed at content rather than at sky.++## Prove it++`scene_views`, then read `camera_checks` in `metrics.json` per camera: `mean_lum`,+`dark_frac`, `blown_frac`, `modal_frac`. Those are the same four numbers the gate uses, so+there is no reason to guess. A dark harness rig view is only a WARN, but the code that+writes these findings records a measured case where exactly that cost a battery a 0.60 cap+three rounds running — fix it anyway.++Code and the full palette table: cookbook `scene_threejs` sections *Dusk / night lighting+recipe*, *Atmosphere: time-of-day triads with numbers*.++Worked numbers, the linear-luminance arithmetic and a per-time-of-day check:+`references/exposure-math.md`.diff --git a/harness/codeverse/skills/cv3d-scene-lighting/references/exposure-math.md b/harness/codeverse/skills/cv3d-scene-lighting/references/exposure-math.mdnew file mode 100644index 00000000..f71a3ccd--- /dev/null+++ b/harness/codeverse/skills/cv3d-scene-lighting/references/exposure-math.md@@ -0,0 +1,72 @@+# Exposure arithmetic for this renderer++The renderer is not yours to change (`runtime_js/lib/browser/renderer.js`): ACES Filmic+tone mapping, `toneMappingExposure = 1.0`, sRGB output, three r0.182. So the mapping from+"how bright is this surface in the scene" to "what number does the gate read" is fixed and+computable. Every figure here was computed from those settings on 2026-08-25.++## Step 1 — a hex colour is not its brightness++three decodes every hex colour from sRGB into the linear working space before lighting.+The relative luminance of the decoded colour is the *albedo* that matters.++## Step 2 — albedo, through the tone curve, to the frame value++Read "key x1" as a surface that is fully and directly lit. `frame` is the value the gate+averages into `mean_lum`.++| swatch | linear albedo | frame at key x0.5 | x1 | x2 |+|---|---|---|---|---|+| `0x1d3d22 dark foliage` | 0.037 | 0.07 | 0.15 | 0.27 |+| `0x2f6b2a mid foliage` | 0.113 | 0.22 | 0.37 | 0.56 |+| `0x5a3b22 bark` | 0.054 | 0.11 | 0.21 | 0.36 |+| `0x5e7a3a grass` | 0.166 | 0.30 | 0.48 | 0.67 |+| `0x6b6152 dry earth` | 0.123 | 0.23 | 0.39 | 0.59 |+| `0x8e9aa6 slate` | 0.316 | 0.46 | 0.66 | 0.82 |+| `0xc3cad1 pale stone` | 0.584 | 0.64 | 0.80 | 0.91 |+| `0xf0f4f8 plaster` | 0.900 | 0.75 | 0.87 | 0.94 |+++The gate's dark threshold is 0.12. Dark foliage lands at 0.15 fully lit and 0.07 at half+key — which is why a night woodland scene fails the gate no matter how the lights are+tuned, and the only real fix is a lighter albedo (or emissive practicals that put bright+pixels in the frame).++## Step 3 — where the headroom is++|---|---|+| 0.12 | 0.029 |+| 0.15 | 0.037 |+| 0.20 | 0.051 |+| 0.30 | 0.085 |+| 0.50 | 0.181 |++The curve is steep at the bottom: getting from a frame value of 0.12 to 0.20 needs the+linear scene luminance to go from 0.029 to 0.051, i.e. roughly +75 % of light — but getting+from 0.30 to 0.50 needs it to more than double. Near the gate line, modest increases move+the number a lot; that is the cheapest place to fix a dark scene.++## Step 4 — sanity numbers for the coloured-darkness rows++Relative luminance of the cookbook's dusk and night palette entries, so you can see that+"dark" there means roughly 0.03 and not 0.00:++| swatch | linear luminance |+|---|---|+| dusk zenith `0x33285c` | 0.030 |+| dusk horizon `0xd9703a` | 0.267 |+| night zenith `0x0d1430` | 0.008 |+| night horizon `0x22305a` | 0.032 |+| dusk hemisphere ground `0x3a2e22` | 0.030 |+| night hemisphere ground `0x1a1c24` | 0.012 |++The horizon band is the brightest thing in a dusk frame by an order of magnitude. That is+why a black `scene.background` fails a scene that would otherwise pass: it deletes the one+region carrying the frame's mean.++## Step 5 — the check++`scene_views` writes `camera_checks` into `metrics.json` with `mean_lum`, `dark_frac`,+`blown_frac` and `modal_frac` per camera — the same four numbers the gate thresholds. Aim+for `mean_lum >= 0.15`, `dark_frac <= 0.25`, `blown_frac <= 0.10`. Anything on the+threshold will flip between rounds.