Design Geordi native GPU host for Bijou cell buffers - #511
flyingrobots wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughThe PR adds a design record for a Geordi native GPU host that presents Bijou’s existing packed-cell buffers. It defines ownership, endpoint profiles, GPU preparation, validation, evidence, fallback behavior, implementation slices, tests, and acceptance criteria. No runtime code or existing cell contract changes. ChangesNative GPU Host Design
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md (1)
856-863: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAlign the validation plan with the required project gate.
This block lists only
npm run docs:inventoryandgit diff --check. The PR objectives also name installation, build, documentation link checks, formatting checks, and the full project gate. Add the exact commands or link to the authoritative CI gate, and record the relevant results.As per coding guidelines, run
npm run lintplus relevant tests after altering files.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md` around lines 856 - 863, Expand the Validation Plan to include the required installation, build, documentation link, formatting, lint, relevant test, and full project-gate commands, using the authoritative CI gate reference where appropriate. Record the resulting pass/fail outputs alongside the existing docs:inventory and git diff --check results.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md`:
- Around line 611-612: Replace the arbitrary string fields in the claims schema
with versioned claim IDs or structured claim records that can include evidence
references. Add validation for claim combinations against endpoint,
presentation, and cellProduction, rejecting unknown, unsupported, or
contradictory claims, and add negative tests covering those cases.
- Around line 777-783: Define a separate versioned validation-receipt type, or a
phase-discriminated receipt union, for Slice 0 input validation. Keep it limited
to validation-time evidence and exclude prepared-buffer, shader, asset, backend,
presentation, output, and probe claims required by the later receipt interface.
Update the Slice 0 contract to emit this receipt before renderer implementation.
- Around line 578-595: The GeordiNativeBijouCellsReceipt input does not bind all
fields of the canonical PackedBijouCellsReceipt. Update
GeordiNativeBijouCellsReceipt.input to either include widthCells, heightCells,
glyphPolicyId, focus, and chroma with defined hash coverage, or add a canonical
source-receipt digest whose canonicalization rule is explicit; ensure receipts
differing only in those values are distinguishable while cell bytes remain
unchanged.
---
Nitpick comments:
In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md`:
- Around line 856-863: Expand the Validation Plan to include the required
installation, build, documentation link, formatting, lint, relevant test, and
full project-gate commands, using the authoritative CI gate reference where
appropriate. Record the resulting pass/fail outputs alongside the existing
docs:inventory and git diff --check results.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 9150616d-98e2-47ff-92a0-905957e8a33b
📒 Files selected for processing (1)
docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md
| interface GeordiNativeBijouCellsReceipt { | ||
| readonly receiptVersion: 'geordi-native-bijou-cells-receipt/1'; | ||
| readonly input: { | ||
| readonly packedReceiptVersion: 'packed-bijou-cells/1'; | ||
| readonly cellFormatId: 'bijou-packed-cell-u8x10-le/1'; | ||
| readonly sceneHash: string; | ||
| readonly cellBytesHash: string; | ||
| readonly sideTableHash: string; | ||
| }; | ||
| readonly preparation: { | ||
| readonly profileId: string; | ||
| readonly preparedLayoutId: string; | ||
| readonly preparedBufferHash: string; | ||
| readonly glyphRunHash: string; | ||
| readonly glyphAtlasHash: string; | ||
| readonly fontPackHash: string; | ||
| readonly shaderBundleHash: string; | ||
| }; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Bind the complete canonical input in the endpoint receipt.
The supplied PackedBijouCellsReceipt contract in packages/bijou/src/core/packed-bijou-cells-contract.ts, Lines 53-64, includes widthCells, heightCells, glyphPolicyId, focus, and chroma. This input object omits those fields. The schema also does not define whether the existing hashes cover them. The receipt therefore cannot prove which complete canonical receipt produced the frame.
Add a canonical source-receipt digest with an explicit canonicalization rule, or add fields and hashes for the omitted values. Test receipts that vary dimensions, focus, chroma, or glyph policy while keeping cell bytes unchanged.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md` around
lines 578 - 595, The GeordiNativeBijouCellsReceipt input does not bind all
fields of the canonical PackedBijouCellsReceipt. Update
GeordiNativeBijouCellsReceipt.input to either include widthCells, heightCells,
glyphPolicyId, focus, and chroma with defined hash coverage, or add a canonical
source-receipt digest whose canonicalization rule is explicit; ensure receipts
differing only in those values are distinguishable while cell bytes remain
unchanged.
| readonly claims: readonly string[]; | ||
| readonly nonclaims: readonly string[]; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make receipt claims machine-checkable.
claims and nonclaims are arbitrary strings, but Lines 290-303 define named claim classes and mark generic TTY GPU-buffer rendering as unsupported. A consumer cannot reject unknown or contradictory claims from this schema.
Use versioned claim IDs or structured claim records with evidence references. Validate claim combinations against endpoint, presentation, and cellProduction. Add negative tests for unsupported and contradictory claims.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md` around
lines 611 - 612, Replace the arbitrary string fields in the claims schema with
versioned claim IDs or structured claim records that can include evidence
references. Add validation for claim combinations against endpoint,
presentation, and cellProduction, rejecting unknown, unsupported, or
contradictory claims, and add negative tests covering those cases.
| ### Slice 0: Contract And Fixture Intake | ||
|
|
||
| 1. Copy one byte-identical `packed-bijou-cells/1` fixture into the Geordi | ||
| conformance corpus with the originating Bijou revision and digests. | ||
| 2. Implement a strict Rust boundary validator or generated DTO that rejects | ||
| unsupported versions and malformed relationships. | ||
| 3. Emit an input-validation receipt before any renderer exists. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Define a separate validation receipt for Slice 0.
Slice 0 requires an input-validation receipt before a renderer exists. The receipt interface at Lines 578-613 requires prepared-buffer, shader, asset, backend, presentation, output, and probe fields that do not exist at validation time.
Define a versioned validation-receipt type or a phase-discriminated receipt union. Prevent validation receipts from carrying rendering or GPU-presentation claims.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/design/RE-510-geordi-native-gpu-host-for-bijou-cell-buffers.md` around
lines 777 - 783, Define a separate versioned validation-receipt type, or a
phase-discriminated receipt union, for Slice 0 input validation. Keep it limited
to validation-time evidence and exclude prepared-buffer, shader, asset, backend,
presentation, output, and probe claims required by the later receipt interface.
Update the Slice 0 contract to emit this receipt before renderer implementation.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6933b00329
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| readonly sceneHash: string; | ||
| readonly cellBytesHash: string; | ||
| readonly sideTableHash: string; |
There was a problem hiding this comment.
Two valid packed receipts can share these three hashes while differing in scene.nodeIds, scene.cellNodeIds, or focus, because validatePackedBijouScene() only checks the supplied sceneHash syntax and does not derive it from that receipt metadata (packages/bijou/src/core/packed-bijou-cells-validate-scene.ts:30-69). Since ownership and focus do not affect the prepared pixels, such inputs can produce indistinguishable endpoint receipts, defeating the document's provenance and inspectability claims. Include a canonical hash of the complete validated packed receipt, or explicitly bind the scene mappings and focus facts.
Useful? React with 👍 / 👎.
| presence bits remain authoritative for terminal-default colors; packed zero | ||
| channels must not silently become black. Modifier and opacity interpretation | ||
| must be profile-bound. |
There was a problem hiding this comment.
The mandated RE-036 fixture contains cells with unset foreground or background presence bits (tests/fixtures/RE-036/packed-bijou-cells.v1.json:7-10), so the native renderer must choose concrete colors before it can rasterize them. The chroma metadata only identifies presence-bits, while the design leaves both the default-color source and its receipt identity as an open question at lines 976-977. Consequently, the first proof cannot both avoid coercing defaults to black and produce reproducible pixels; define an explicit default palette/theme contract and bind its identity into preparation before treating this as implementable.
Useful? React with 👍 / 👎.
| The first proof should use a deliberately small fixture and one committed font | ||
| pack. It may support only a bounded ASCII or single-glyph subset if unsupported | ||
| graphemes fail before GPU submission. It must not use host font fallback and | ||
| then claim deterministic output. |
There was a problem hiding this comment.
The recommended proof later specifies the landed RE-036 fixture as its one input, but that fixture includes the non-ASCII side-table graphemes é and U+F000 and cells using bold, solid underline, and dashed underline (tests/fixtures/RE-036/packed-bijou-cells.v1.json:7-11). Permitting an ASCII/single-glyph first profile—and leaving the modifier subset unresolved—allows the strict consumer to reject every run before GPU submission, so the planned cycle can satisfy its refusal policy without ever exercising the renderer or meeting the hill. Require a font/glyph/modifier profile that covers this fixture, or name a separate byte-exact renderable fixture.
Useful? React with 👍 / 👎.
| 2. Implement a strict Rust boundary validator or generated DTO that rejects | ||
| unsupported versions and malformed relationships. |
There was a problem hiding this comment.
For receipts containing Unicode graphemes near segmentation or terminal-width boundaries, an independent Rust validator can disagree with Bijou even when both implementations appear strict: Bijou's policy depends on the host Intl.Segmenter plus its own width lookup (packages/bijou/src/core/packed-bijou-cells-glyph-policy.ts:18-28 and packages/bijou/src/core/text/grapheme.part01.ts:19-21), but this design pins neither the Unicode/segmentation version nor a shared algorithm. A generated DTO also cannot enforce those semantic laws by itself. Define an authoritative versioned validation algorithm or cross-language valid-and-invalid conformance corpus before allowing Geordi to accept or reject canonical receipts independently.
Useful? React with 👍 / 👎.
| 13. A headless environment can run the validation and offscreen proof or emits | ||
| a typed capability obstruction rather than silently falling back to software | ||
| while retaining a GPU claim. |
There was a problem hiding this comment.
On a headless CI runner with no acceptable adapter, this test is allowed to pass by emitting only a capability obstruction, so every CI run can remain green without creating an offscreen texture, submitting a draw, or evaluating the promised probes. That contradicts the acceptance criterion that the first GPU proof runs offscreen in CI and leaves the central renderer claim untested. Keep obstruction coverage for unsupported hosts, but require a designated pinned backend/adapter lane to execute the positive render path.
Useful? React with 👍 / 👎.
This branch has not been deployed
1 participant
Goal
Define the V10 architecture for presenting Bijou's canonical packed cell grid through a Geordi native GPU host without changing Bijou cell semantics or claiming that a generic TTY accepts GPU buffers.
Closes #510 when the design record lands.
Design
RE-510 Geordi Native GPU Host For Bijou Cell BuffersThe design records the evidence found in Bijou, Geordi, the tracked project blog, and
agy-readings, then distinguishes:The smallest later implementation proof consumes the landed RE-036 fixture, derives a GPU-aligned prepared buffer and pinned glyph assets, renders through offscreen
wgpu, and emits probes plus a target receipt.Scope
Validation
npm cinpm run buildnpm run docs:inventorygit diff --checkKnown repository state
The clean install reports the dependency advisories already owned by #482 and PR #492. This design does not change that dependency graph.
Summary by CodeRabbit