plan+feat(cognition+transaction): normalized-entity-holy-grail-v1 Stage 1 (D-NEH-1a..g)#431
Merged
Merged
Conversation
…EXT-1..6 + jit + MailboxSoA Adds `.claude/plans/normalized-entity-holy-grail-v1.md` — the canonical trunk plan that ties every prior architectural deliverable into ONE typed consumer pipeline grammar: - Carrier: `NormalizedEntity<Stage>` — single struct, 4-way inheritance slots (Odoo → OGIT → OWL → DOLCE → FIBU/FIBO), typed lens into a `MailboxSoA` row, phantom-typed Stage enforces traversal order at compile time - Algebra: five universal verbs (`resolve` / `hydrate` / `classify` / `align` / `think`) — closure analogue of the Vsa16k algebra - Execution: `Op<I,O>` trait with three call sites (`apply` cold / `apply_stream` warm / `apply_soa` hot, JIT-compiled), shared const data, shader-dispatched - Contexts: typed `Interactive` / `Bulk` / `Periodisch` transaction enclosures own commit semantics + Baton epoch + Lance version policy + cascade traversal mode (sync DFS / async batched / JIT fixed-point) - Cascade: Odoo's 6 overlapping mechanisms collapse into ONE typed graph on `EdgeColumn` Re-encodes Odoo's 15-year-old three-regime decomposition as compile-time typed boundaries instead of stringly-typed `env.context` flags + lock-date wizards. The decomposition is borrowed; the failure timing (compile-time vs runtime) is the improvement. PREPENDS 8 driver epiphanies to EPIPHANIES.md in the same commit: E-NORMALIZED-ENTITY-1, E-OP-FIVE-VERBS-1, E-OP-THREE-CALLSITES-1, E-TRANSACTION-CONTEXT-1, E-CASCADE-AS-EDGECOLUMN-1, E-ODOO-AS-PRIOR-ART-1, E-CONSUMER-CANNOT-INTERPRET-1 (iron-rule candidate — regex/hand-rolled if-chains structurally banned via missing-function), E-NO-AUTOMATIC-REGIME-PICK-1 (mid-session correction). PREPENDS plan entry to INTEGRATION_PLANS.md per CCA2A mandatory board-hygiene rule. Stage-1 deliverables D-NEH-1a..g (~2 500 LOC, typed signatures + compile-fail tests + doc-level example) follow in a subsequent commit on this branch. Subsequent stages (v2..v7) sketched in the plan: kernel bodies, consumer DSL macros, stream+ractor wiring, Jahresabrechnung JIT kernel, palantir-foundry parity audit, elixir-OTP parity audit. When v6+v7 audits show ≥80% parity, the workspace has earned the "better palantir foundry / better elixir" framing. https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
…il-v1 Stage 1 contract surface scaffold
Adds the typed consumer pipeline grammar per
`.claude/plans/normalized-entity-holy-grail-v1.md` — the trunk that
unifies BP-1 + EXT-1..6 + jit + MailboxSoA into one surface.
Modules:
- `cognition::{stages, entity, op, advance, cascade}` — phantom-typed
Stage markers (sealed trait; 9 canonical stages), `NormalizedEntity<S>`
carrier (Copy, zero-dep placeholder handles for Odoo/OGIT/OWL/FIBU
refs; Stage 2 replaces with real types), `Op<I,O>` trait with 3 call
sites (Stage 1 ships `apply`; `apply_stream` + `apply_soa` deferred
to Stage 2 per zero-dep constraint), 5-verb advancement methods
(`resolve_ogit` fully wired for the ctx dispatch; verbs 2-4 are
`todo!()` pending Stage 2 ontology dep), cascade traversal trait
(`CascadeKind` 8 discriminants, `TraversalMode` 3 modes,
`CascadeWalker` trait for EdgeColumn impl in Stage 2)
- `transaction::{interactive, bulk, periodisch, ctx}` — 3 typed context
shapes + 4 per-stage `*Ctx` traits (sealed Context base); all three
contexts implement all 4 traits with `todo!()` bodies; Interactive
+ Bulk + Periodisch have `new()` + `Default` impls
Compile-fail tests (`tests/cognition_typestate.rs`): 4 `compile_fail`
doctests document what the type system forbids; 7 positive `#[test]`
functions confirm permitted forms compile + run.
Crate doc: `cognition/mod.rs` has a full invoice-flow example chain
as a `no_run` doctest. `docs/COGNITION_HOLY_GRAIL.md` pointer doc.
Stage-1 `/// work` markers (count: ~35): flag OGIT codebook lookup,
OWL hydrator dispatch, DOLCE classifier wiring, MailboxSoA column
write-back, `apply_stream` async backend choice, `apply_soa` SoA dep,
EdgeColumn impl, Output shape, DolceCategory sub-enum expansion, and
frozen Lance version API. Main thread reviews + strips markers before PR.
Board hygiene: AGENT_LOG entry prepended + STATUS_BOARD D-NEH-1a..g
rows (status: In PR).
Tests: `cargo check -p lance-graph-contract` clean (0 errors);
`cargo test -p lance-graph-contract --lib` green (472 tests, was 472
baseline — no regressions); `cargo test -p lance-graph-contract --test
cognition_typestate` green (7 new tests).
Plan: `.claude/plans/normalized-entity-holy-grail-v1.md`.
https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
…2) (main-thread review pass) Per the new agent workflow (plan → Sonnet → /// work markers → main-thread review → strip → PR → bot review → fix): main thread reviewed the 45 `/// work` doc-comment markers the Sonnet agent left across the cognition + transaction modules and converted them to plain `// TODO(Stage 2):` line comments. Rationale: - `///` doc-comments would render the deferred-work notes into cargo doc output as part of the public surface — wrong audience - `// TODO(Stage 2):` keeps the context visible in source (so a future agent picks them up) without polluting the rendered documentation - All 45 markers carried meaningful Stage-2-wiring notes (OGIT codebook dispatch, OWL hydrator, DOLCE classifier, FIBU overlay, MailboxSoA column writes, async Stream backend choice, EdgeColumn impl, etc.) — none were stripped wholesale; all preserved as TODOs Build: cargo check -p lance-graph-contract clean. Tests: 472 lib tests still green (zero regression from the agent's commit). https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
📝 WalkthroughWalkthroughThis PR ships a Stage‑1 contract surface for a typed normalized‑entity consumer pipeline: a phantom‑typed NormalizedEntity carrier with sealed stages, a step‑based Op trait, partial five‑verb advancement APIs (resolve implemented; others todo), cascade walker contract, sealed transaction contexts (Interactive/Bulk/Periodisch) as placeholders, typestate tests, and planning/board docs. ChangesTyped Normalized Entity Consumer Pipeline
🎯 4 (Complex) | ⏱️ ~60 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
![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: 8b3efca03f
ℹ️ 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".
| /// Not callable on the advancement verbs themselves (those use it | ||
| /// internally); exposed `pub` so external Op implementors can | ||
| /// construct stage-transitioned entities in their `apply` bodies. | ||
| pub fn advance_stage<T: Stage>(self) -> NormalizedEntity<T> { |
There was a problem hiding this comment.
Because advance_stage is public, any downstream crate can skip the required pipeline by calling, for example, raw.advance_stage::<Reported>().output() without resolving OGIT/OWL/DOLCE/FIBU or running chk_data/review/abduct. That bypasses the typestate guarantees this API is documenting and allows invalid entities with empty normalization slots to be treated as completed, so the cast needs to be restricted to trusted verb/Op plumbing rather than exposed as a general public method.
Useful? React with 👍 / 👎.
| /// Wide enough for PR #427's witness_table widening. | ||
| pub mailbox_ref: u32, | ||
| /// Row inside the per-mailbox SoA (64 K–256 K envelope). | ||
| pub row_idx: u16, |
There was a problem hiding this comment.
For mailboxes in the documented 64K–256K envelope, rows above 65,535 cannot be represented by this u16 field. Any cascade or Op dispatch that needs to address those upper rows would be unable to construct a valid MailboxRow (or would have to truncate elsewhere), so this should be widened to match the advertised per-mailbox capacity before consumers start depending on the handle layout.
Useful? React with 👍 / 👎.
…ation Clippy 1.95 reads a leading `+` at the start of a doc-comment line as a markdown list-bullet starter, then complains the next line doesn't have indented continuation. The text was prose, not a list — reworded `+ lock-date` → `plus lock-date` so the lint goes quiet. Build: cargo clippy -p lance-graph-contract --lib --tests -- -D warnings clean. https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
…ke Ops Clippy `-D warnings` rejects 5 unused-struct errors on the fake Op types (`NoopOp`, `FakeChkData`, `FakeReview`, `FakeAbduct`, `FakeReport`) that are referenced only by `compile_fail` doctests above. Regular `cargo test` builds the crate without those doctest snippets, leaving the structs unused. `#[allow(dead_code)]` with a brief explanatory comment per struct is the clean way to silence the lint without sacrificing the doctests' documentary value. https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
crates/lance-graph-contract/src/cognition/cascade.rs (1)
1-187: ⚡ Quick winAdd focused unit tests in this module.
This new contract file has no local
#[cfg(test)]coverage. Please add focused unit tests (e.g., enum equality/hash behavior and basic trait-shape compile checks) alongside the implementation.As per coding guidelines, “
crates/**/*.rs: Add Rust unit tests alongside implementations via#[cfg(test)]modules; prefer focused scenarios over broad integration tests”.🤖 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 `@crates/lance-graph-contract/src/cognition/cascade.rs` around lines 1 - 187, Add a #[cfg(test)] mod tests in this file with focused unit tests: 1) test equality and Hash behavior for CascadeKind (e.g., insert variants into a HashSet and assert contains/len) and for TraversalMode; 2) a compile-time shape test for the CascadeWalker trait by declaring a tiny local struct that implements CascadeWalker (implement walk_dependents as a no-op) and calling its walk_dependents with a dummy MailboxRow, Option<CascadeKind> and TraversalMode to ensure signatures (refer to CascadeKind, TraversalMode, CascadeWalker, and MailboxRow); keep tests scoped and small, using assert_eq!/assert_ne! and basic HashSet assertions.
🤖 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 @.claude/board/AGENT_LOG.md:
- Line 3: Update the log entry that currently states the deferred bodies are
marked with "/// work" to reflect the actual comment style used in the codebase:
replace the phrase "/// work" with the exact text "// TODO(Stage 2)" in the
board entry so grep-based follow-ups match the source; ensure the sentence still
mentions that advancement verbs past resolve_ogit have TODO comments and keep
the rest of the wording intact (reference the phrase "advancement verbs past
`resolve_ogit`" and the marker strings "/// work" → "// TODO(Stage 2)").
In `@crates/lance-graph-contract/src/cognition/advance.rs`:
- Around line 37-60: Add a colocated #[cfg(test)] module in this file that
contains focused unit tests for the stage-transition and chaining behavior:
write tests that construct a NormalizedEntity<Raw>, call resolve_ogit (using a
test double or mock OgitCtx that returns a known URI) and assert the returned
NormalizedEntity<WithOgit> has ogit populated and other fields preserved; add
tests for advance_stage and any chain transition methods to verify stages change
as expected and that output (if present) produces the expected result when
invoked; keep tests small and targeted (one scenario per test), reference the
functions resolve_ogit, advance_stage, output and any chain transition methods
to locate code, and put them under #[cfg(test)] mod tests with simple test
helpers/mocks for OgitCtx.
In `@crates/lance-graph-contract/src/cognition/cascade.rs`:
- Around line 80-86: The doc comment for the enum is inconsistent: it claims
server actions are encoded as `Other`+tag but the enum already exposes a
`ServerAction` variant; update the documentation for the enum (referencing the
`ServerAction` and `Other` variants) so they follow one model—either (A)
document that server actions are represented by the `ServerAction` variant and
describe its encoding/usage, or (B) remove/adjust the `ServerAction` variant and
document that server actions are encoded via `Other`+tag; ensure the comment
clarifies which variant to use and how tags are interpreted to prevent
misimplementation.
- Around line 167-186: The CascadeWalker trait's walk_dependents currently
returns () so callers cannot obtain the produced dependent set; change the API
to surface dependents by either (a) changing fn walk_dependents(&self, from:
MailboxRow, kind_filter: Option<CascadeKind>, mode: TraversalMode) -> Box<dyn
Iterator<Item = MailboxRow> + '_> (or an associated Iterator type) or (b) add a
callback/sink parameter (e.g., &mut dyn FnMut(MailboxRow) or a &mut
Vec<MailboxRow>) so implementors of CascadeWalker can yield each dependent;
update the trait definition and all implementors and callers of
CascadeWalker::walk_dependents (and any tests) to use the chosen return/consumer
form so the Stage 2 fan-out can be expressed at the type level.
In `@crates/lance-graph-contract/src/cognition/entity.rs`:
- Around line 26-27: The documented envelope allows up to 256K rows but the
entity field row_idx is declared as u16 (in the struct in
crates/lance-graph-contract/src/cognition/entity.rs), which overflows at 65,535;
change the field type from u16 to a wider integer (e.g., u32) in the struct(s)
and any other locations referencing row_idx, update constructors/serializers and
pattern matches to use the new type, and adjust the doc comment to remain
consistent (or lower the documented limit if you intend to keep u16); ensure any
tests or conversions that assumed u16 are updated accordingly.
- Around line 144-185: NormalizedEntity's public stage fields (eg. ogit, owl,
dolce, fibu, and the row lens) and its public advance_stage method allow callers
to bypass the typestate sequencing; make the stage slots private (remove pub
from ogit, owl, dolce, fibu and the row field) and restrict direct mutation,
then replace/limit advance_stage visibility (make advance_stage pub(crate) or
private) and provide explicit controlled advancement APIs (eg. methods named
resolve_ogit, hydrate_owl, classify_dolce, align_fibu on NormalizedEntity that
perform the validations and set the corresponding private fields), plus public
getters (as_refs) for read-only access; reference NormalizedEntity, the
ogit/owl/dolce/fibu fields, row, and advance_stage when applying the changes.
In `@crates/lance-graph-contract/src/transaction/interactive.rs`:
- Around line 54-107: Add a small #[cfg(test)] mod tests that verifies the
Interactive contract surface: create an Interactive via Interactive::new() and
assert Default::default() == Interactive::new() (or that default constructs an
Interactive), then call the trait methods resolve_ogit, hydrate_owl,
classify_dolce, and align_fibu (via the Interactive instance or trait object)
and assert each currently panics/todos (use std::panic::catch_unwind or
#[should_panic] with the expected todo! messages) so the constructor/default and
trait-impl stubs are covered; reference the Interactive type and its new(),
Default impl, and the OgitCtx::resolve_ogit, OwlCtx::hydrate_owl,
DolceCtx::classify_dolce, FibuCtx::align_fibu methods to locate where to add the
tests.
In `@crates/lance-graph-contract/tests/cognition_typestate.rs`:
- Around line 1-66: The compile_fail doctests in tests/cognition_typestate.rs
aren’t run by CI because that file lives under tests/ and the crate is tested
with --lib; move the proof examples into crate documentation under
crates/lance-graph-contract/src (e.g., lib.rs or a dedicated module doc) so
rustdoc will run them, or add a trybuild harness in
crates/lance-graph-contract/src/tests/ that asserts the same failures (using
examples referencing NormalizedEntity<Raw>, NormalizedEntity<Reviewed>,
NormalizedEntity<Reported>, Stage and the sealed supertrait) and/or update CI to
invoke cargo test --manifest-path crates/lance-graph-contract/Cargo.toml --doc
so the existing compile_fail blocks are executed.
In `@docs/COGNITION_HOLY_GRAIL.md`:
- Around line 27-28: Update the docs text that currently refers to `/// work`
markers so it instead mentions the current anchor format `// TODO(Stage 2)` used
in the codebase (e.g., in `op.rs`); change the phrase "see `/// work` markers"
to something like "see `// TODO(Stage 2)` markers" and ensure any surrounding
explanatory text directs readers to search for `// TODO(Stage 2)` call-site
anchors.
---
Nitpick comments:
In `@crates/lance-graph-contract/src/cognition/cascade.rs`:
- Around line 1-187: Add a #[cfg(test)] mod tests in this file with focused unit
tests: 1) test equality and Hash behavior for CascadeKind (e.g., insert variants
into a HashSet and assert contains/len) and for TraversalMode; 2) a compile-time
shape test for the CascadeWalker trait by declaring a tiny local struct that
implements CascadeWalker (implement walk_dependents as a no-op) and calling its
walk_dependents with a dummy MailboxRow, Option<CascadeKind> and TraversalMode
to ensure signatures (refer to CascadeKind, TraversalMode, CascadeWalker, and
MailboxRow); keep tests scoped and small, using assert_eq!/assert_ne! and basic
HashSet assertions.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: d6272fec-d869-4aec-ad99-47b15c82e40c
📒 Files selected for processing (19)
.claude/board/AGENT_LOG.md.claude/board/EPIPHANIES.md.claude/board/INTEGRATION_PLANS.md.claude/board/STATUS_BOARD.md.claude/plans/normalized-entity-holy-grail-v1.mdcrates/lance-graph-contract/src/cognition/advance.rscrates/lance-graph-contract/src/cognition/cascade.rscrates/lance-graph-contract/src/cognition/entity.rscrates/lance-graph-contract/src/cognition/mod.rscrates/lance-graph-contract/src/cognition/op.rscrates/lance-graph-contract/src/cognition/stages.rscrates/lance-graph-contract/src/lib.rscrates/lance-graph-contract/src/transaction/bulk.rscrates/lance-graph-contract/src/transaction/ctx.rscrates/lance-graph-contract/src/transaction/interactive.rscrates/lance-graph-contract/src/transaction/mod.rscrates/lance-graph-contract/src/transaction/periodisch.rscrates/lance-graph-contract/tests/cognition_typestate.rsdocs/COGNITION_HOLY_GRAIL.md
Comment on lines
+37
to
+60
| impl NormalizedEntity<Raw> { | ||
| /// Stage 1 → Stage 2: resolve Odoo model_name → OGIT URI. | ||
| /// | ||
| /// Dispatches into the OGIT codebook via the transaction context | ||
| /// (which implements [`OgitCtx`]). Returns a `NormalizedEntity` | ||
| /// with the `ogit` slot populated. | ||
| /// | ||
| /// Per E-CODEBOOK-INHERITS-FROM-OGIT: the resolved URI is a | ||
| /// stable codebook row index, not a freshly hashed value. | ||
| /// | ||
| // TODO(Stage 2): also need to write back the resolved OGIT identity | ||
| // into the owning mailbox's SoA fingerprint column. Stage 2 | ||
| // wires this once `cognitive-shader-driver` is a hard dep of | ||
| // contract (or the write-back goes through a trait adapter). | ||
| pub fn resolve_ogit<C: OgitCtx>(self, ctx: &C) -> NormalizedEntity<WithOgit> { | ||
| let ogit = ctx.resolve_ogit(self.odoo.0); | ||
| // Use advance_stage to copy the struct without touching _stage directly, | ||
| // then overwrite the ogit field via a fresh struct built from the advanced base. | ||
| // We need to set ogit, so we build from scratch using the public fields. | ||
| let mut advanced = self.advance_stage::<WithOgit>(); | ||
| advanced.ogit = Some(ogit); | ||
| advanced | ||
| } | ||
| } |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Add colocated #[cfg(test)] unit tests for advancement and chain methods.
The file adds core behavior (resolve_ogit, chain transitions, output) but has no alongside unit-test module. Please add focused in-file tests for stage transition correctness and slot population on the implemented paths.
As per coding guidelines, "Add Rust unit tests alongside implementations via #[cfg(test)] modules; prefer focused scenarios over broad integration tests".
Also applies to: 118-228
🤖 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 `@crates/lance-graph-contract/src/cognition/advance.rs` around lines 37 - 60,
Add a colocated #[cfg(test)] module in this file that contains focused unit
tests for the stage-transition and chaining behavior: write tests that construct
a NormalizedEntity<Raw>, call resolve_ogit (using a test double or mock OgitCtx
that returns a known URI) and assert the returned NormalizedEntity<WithOgit> has
ogit populated and other fields preserved; add tests for advance_stage and any
chain transition methods to verify stages change as expected and that output (if
present) produces the expected result when invoked; keep tests small and
targeted (one scenario per test), reference the functions resolve_ogit,
advance_stage, output and any chain transition methods to locate code, and put
them under #[cfg(test)] mod tests with simple test helpers/mocks for OgitCtx.
Comment on lines
+54
to
+107
| impl Interactive { | ||
| /// Construct a new `Interactive` context. | ||
| /// | ||
| /// In Stage 1 this is a no-op constructor. Stage 2 wires the live | ||
| /// Lance read handle and Baton emission queue. | ||
| pub fn new() -> Self { | ||
| Self { _placeholder: () } | ||
| } | ||
| } | ||
|
|
||
| impl Default for Interactive { | ||
| fn default() -> Self { | ||
| Self::new() | ||
| } | ||
| } | ||
|
|
||
| // ── Trait impls ─────────────────────────────────────────────────────────────── | ||
|
|
||
| impl Context for Interactive {} | ||
|
|
||
| impl OgitCtx for Interactive { | ||
| fn resolve_ogit(&self, _model_name: &'static str) -> OgitUriRef { | ||
| // TODO(Stage 2): dispatch into `crate::callcenter::ogit_uris` for the | ||
| // canonical OGIT URI lookup. The codebook maps `model_name` | ||
| // to a stable `OgitUriRef` via `OntologyRegistry::resolve`. | ||
| // Stage 2 also writes the resolved code into the owning | ||
| // mailbox's SoA fingerprint column via the Baton emission | ||
| // queue (E-CODEBOOK-INHERITS-FROM-OGIT). | ||
| todo!("D-NEH-2 wires the real OGIT codebook lookup via callcenter::ogit_uris") | ||
| } | ||
| } | ||
|
|
||
| impl OwlCtx for Interactive { | ||
| fn hydrate_owl(&self, _ogit_uri: OgitUriRef) -> OwlClassRef { | ||
| // TODO(Stage 2): dispatch OWL hydration via the TTL-join registry. | ||
| // Stage 2 wires this against the EXT-1 OWL extraction. | ||
| todo!("D-NEH-2 wires the OWL hydrator (TTL join on OGIT URI)") | ||
| } | ||
| } | ||
|
|
||
| impl DolceCtx for Interactive { | ||
| fn classify_dolce(&self, _owl_class: OwlClassRef) -> DolceCategory { | ||
| // TODO(Stage 2): dispatch into lance_graph_ontology::dolce_odoo::DolceClassifier. | ||
| todo!("D-NEH-2 wires the DOLCE classifier from lance-graph-ontology::dolce_odoo") | ||
| } | ||
| } | ||
|
|
||
| impl FibuCtx for Interactive { | ||
| fn align_fibu(&self, _dolce: DolceCategory, _odoo: OdooEntityRef) -> FibuAlignmentRef { | ||
| // TODO(Stage 2): dispatch into the Kontenerkennung alignment tables | ||
| // (SKR03/SKR04, UStVA Kennzahlen, GoBD wiring). | ||
| todo!("D-NEH-2 wires the FIBU/FIBO alignment overlay from EXT-1..6") | ||
| } | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether this file already has colocated unit tests.
rg -n -C2 'cfg\(test\)|mod tests' crates/lance-graph-contract/src/transaction/interactive.rsRepository: AdaWorldAPI/lance-graph
Length of output: 49
Add focused local #[cfg(test)] coverage for Interactive contract surface.
crates/lance-graph-contract/src/transaction/interactive.rs currently has no colocated #[cfg(test)] / mod tests, so the constructor/default and trait-impl contract remains unguarded.
♻️ Proposed patch
impl FibuCtx for Interactive {
fn align_fibu(&self, _dolce: DolceCategory, _odoo: OdooEntityRef) -> FibuAlignmentRef {
// TODO(Stage 2): dispatch into the Kontenerkennung alignment tables
// (SKR03/SKR04, UStVA Kennzahlen, GoBD wiring).
todo!("D-NEH-2 wires the FIBU/FIBO alignment overlay from EXT-1..6")
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn assert_ctx_impls<T: Context + OgitCtx + OwlCtx + DolceCtx + FibuCtx>() {}
+
+ #[test]
+ fn interactive_implements_all_stage_context_traits() {
+ assert_ctx_impls::<Interactive>();
+ }
+
+ #[test]
+ fn interactive_new_and_default_construct() {
+ let _ = Interactive::new();
+ let _ = Interactive::default();
+ }
+}🤖 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 `@crates/lance-graph-contract/src/transaction/interactive.rs` around lines 54 -
107, Add a small #[cfg(test)] mod tests that verifies the Interactive contract
surface: create an Interactive via Interactive::new() and assert
Default::default() == Interactive::new() (or that default constructs an
Interactive), then call the trait methods resolve_ogit, hydrate_owl,
classify_dolce, and align_fibu (via the Interactive instance or trait object)
and assert each currently panics/todos (use std::panic::catch_unwind or
#[should_panic] with the expected todo! messages) so the constructor/default and
trait-impl stubs are covered; reference the Interactive type and its new(),
Default impl, and the OgitCtx::resolve_ogit, OwlCtx::hydrate_owl,
DolceCtx::classify_dolce, FibuCtx::align_fibu methods to locate where to add the
tests.
|
Actionable comments posted: 0 |
…row_idx + cascade sink + stale-marker fixes Addresses Codex P1 + P2 and 6 CodeRabbit findings on the normalized-entity-holy-grail-v1 Stage 1 surface. Two findings (colocated unit tests in advance.rs + interactive.rs) deferred to Stage 2 when concrete kernel bodies exist. CRITICAL — typestate teeth (Codex P1): - NormalizedEntity::advance_stage was pub; external code could cast Raw → Reported. Renamed to advance_stage_internal and demoted to pub(crate). External Op implementors cannot construct any NormalizedEntity<S> for S != Raw. - Op trait redesigned: implementors override only step() (a validation + side-effect hook with default no-op success) + kind(). No more public apply() to override. Framework's chain methods (op / chk_data / review / abduct / report) call op.step() then perform the sealed transition. - New OpError type carries a &'static str for Stage 1; Stage 2 widens to typed reason enum + row ref for audit trail. CORRECTNESS — row_idx widening (Codex P2 + CodeRabbit 5): - MailboxRow::row_idx: u16 → u32. Matches PR #427's symmetric mailbox_ref widening; satisfies the documented 64K-256K per-mailbox envelope. API DESIGN — CascadeWalker sink (CodeRabbit 4): - CascadeWalker::walk_dependents now takes on_dependent: &mut dyn FnMut(MailboxRow). The walker output is expressible at the type level. DOC DRIFT (CodeRabbit 1, 3, 9): - cascade.rs: ServerAction doc no longer claims "encoded as Other + tag" (it IS its own variant). - AGENT_LOG.md first entry + docs/COGNITION_HOLY_GRAIL.md: stale /// work references → // TODO(Stage 2): to match the post-strip state. INTEGRATION TEST FIXUP: - tests/cognition_typestate.rs: 5 fake Op impls (NoopOp, FakeChkData, FakeReview, FakeAbduct, FakeReport) updated to the new step()-only shape. Their old apply() overrides (which called the now-pub(crate) advance_stage) removed; default no-op step() suffices. DEFERRED TO STAGE 2 (CodeRabbit 2, 7): - Colocated #[cfg(test)] tests in advance.rs + interactive.rs. Tests post-fix: - cargo clippy -D warnings clean - cargo test --lib green (472 tests) - cargo test --test cognition_typestate green (7 tests) - cargo test --doc green (3 tests; new compile_fail block in src/cognition/mod.rs proves the typestate seal) https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@crates/lance-graph-contract/src/cognition/op.rs`:
- Around line 129-143: The trait method step(&self, entity:
&NormalizedEntity<I>) -> Result<(), OpError> currently promises Err(...) halts
progression but advance.rs ignores that; update the chain execution in
advance.rs so that callers of Op::step check the Result and stop advancing
(propagate/return the OpError) when Err is returned, ensuring entities are not
moved to later stages on validation failure; adjust any intermediate chain
methods to propagate the Result<_, OpError> instead of discarding it so the halt
semantics declared by step (and types NormalizedEntity<I>/O and OpError) are
honored.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 9a08678a-f7d5-4d3c-b3c6-588334ac43e1
📒 Files selected for processing (8)
.claude/board/AGENT_LOG.mdcrates/lance-graph-contract/src/cognition/advance.rscrates/lance-graph-contract/src/cognition/cascade.rscrates/lance-graph-contract/src/cognition/entity.rscrates/lance-graph-contract/src/cognition/mod.rscrates/lance-graph-contract/src/cognition/op.rscrates/lance-graph-contract/tests/cognition_typestate.rsdocs/COGNITION_HOLY_GRAIL.md
✅ Files skipped from review due to trivial changes (2)
- docs/COGNITION_HOLY_GRAIL.md
- .claude/board/AGENT_LOG.md
🚧 Files skipped from review as they are similar to previous changes (3)
- crates/lance-graph-contract/src/cognition/mod.rs
- crates/lance-graph-contract/src/cognition/cascade.rs
- crates/lance-graph-contract/src/cognition/advance.rs
AdaWorldAPI
pushed a commit
that referenced
this pull request
May 28, 2026
…nd-v1 Hand-crafted Stage 2 trunk plans for the holy-grail substrate, per the 2026-05-28 architectural session: 1. `.claude/plans/unified-spo-nars-codegen-v1.md` (~400 lines) — THE trunk follow-up to `normalized-entity-holy-grail-v1` Stage 1 (PR #431). Absorbs four architectural layers identified during the session: per-verb NARS auto-emission, capability-level method emergence from predicate conjunctions, meta-capability analogical transfer across domains, and the LabelDTO compression. Final consequence: substrate is one DTO type + one codebook + one chain; all typed shapes codegen'd from `format:domain:ogit` URNs. Six waves of deliverables (D-USN-1..Σ-3): typed surface + OGIT root vocabulary additions + HydratorCodegen pipeline + auto-emission + medical-side EXT projection + capabilities + meta-capabilities + LabelDTO carrier compression. 2. `.claude/plans/lance-graph-elixir-frontend-v1.md` (~250 lines) — Stage 5/8: Elixir-syntax script frontend that domain experts read + write; tree-sitter-elixir parser + typestate-aware resolver + Rust codegen against the codebook. **No BEAM at runtime** — Elixir is the SURFACE only; substrate stays typed Rust + SIMD + JIT. Eight deliverables (D-LGE-1..8); gated on `unified-spo-nars -codegen-v1` Wave D + Σ shipping the codebook target. Plus board hygiene: - INTEGRATION_PLANS.md PREPENDed with both plan entries - EPIPHANIES.md PREPENDed with 15 load-bearing epiphanies from the session: E-LABEL-DTO-IS-THE-SUBSTRATE-1, E-FORMAT-DOMAIN-OGIT-IS -THE-URN-SCHEME-1, E-CODEBOOK-IS-THE-COMPILATION-TARGET-1, E-SHARE -SUBSTRATE-SEPARATE-OPERATIONS-1 (the SoC correction to LabelDTO), E-HYDRATOR-AS-OGIT-CODEGEN-1, E-EVERY-VERB-EMITS-NARS-METHODS-1, E-SPO-IS-THE-COMMON-OUTPUT-1, E-CAPABILITY-FROM-PREDICATE-CONJUNCTION -1, E-CROSS-DOMAIN-CAPABILITY-1, E-NARS-COMPOUND-TERM-IS-THE -CAPABILITY-1, E-META-CAPABILITY-PATTERN-1, E-NARS-CLOSED-UNDER-META -ELEVATION-1, E-NEW-DOMAIN-AUTO-METABOLIZES-1, E-MEDICAL-MIRRORS -FINANCIAL-1, E-FOUR-AXIS-DECOMPOSITION-1. Plans authored on main thread (Opus accumulation); deliverable execution is delegation-ready per the new agent workflow (per-wave Sonnet spawning; main-thread review at wave boundaries; PRs against adaworldapi/lance-graph + adaworldapi/OGIT). https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
…-1 halt docs + CI gates Three of the four remaining review findings on PR #431 (the typestate cast is already locked via `advance_stage_internal` + `pub(crate)`; the remaining items are field visibility, halt-semantics doc, and compile_fail-gating in CI). ## Fix 1 — Lock NormalizedEntity fields to `pub(crate)` (coderabbit Major, entity.rs:144-185) Public stage slots (`odoo` / `ogit` / `owl` / `dolce` / `fibu` / `row`) allowed external code to construct an arbitrary-stage entity directly via struct-literal syntax, bypassing the five-verb algebra. Made all six fields `pub(crate)`; external consumers continue to use the already-existing public getters (`odoo()`, `ogit()`, `owl()`, `dolce()`, `fibu()`, `row()`) for read access. The typestate guarantee now holds: every write goes through `advance_stage_internal` (also `pub(crate)`), which is only callable from the verb methods defined in `advance.rs`. ## Fix 2 — Document Stage-1 non-halting chain execution (coderabbit Major, op.rs:129-143 + advance.rs:140-145) `Op::step()` doc claimed `Err(...)` halts the chain, but the chain methods on `NormalizedEntity` (`op`, `chk_data`, `review`, `abduct`, `report`) actually discard the `Result` via `let _ = ...` and advance regardless. The current advance.rs comment ("Stage 1: ignore step errors") only flagged this on `op()`. Updated `Op::step()` rustdoc with a new "## Stage 1 halt semantics" section that explicitly says: chain methods drop the Result; implementors needing to halt must `panic!` or return a stage with no further chain methods. Stage 2 (D-NEH-2) wires real `Result` propagation through the chain. ## Fix 3 — Gate `compile_fail` typestate proofs in CI (coderabbit Major, tests/cognition_typestate.rs:1-66) `crates/lance-graph-contract` runs only `cargo test --lib` in CI, so: - the integration test under `tests/cognition_typestate.rs` was never executed, and - the `compile_fail` doctests in its `//!` module-level docs were silently un-gated (rustdoc doesn't run doctests on integration test crates). Two-part fix: 1. Moved the 4 `compile_fail` proofs into `src/cognition/mod.rs` under a new "## What the type system forbids (compile-fail proofs)" section. `cargo test --doc` reliably picks them up there (verified locally: doctest count 6 → 10, all 4 new tests pass). 2. Added two CI steps to `rust-test.yml`: - `cargo test ... --tests` runs the integration test crate (positive `#[test]` functions). - `cargo test ... --doc` runs library doctests including the new `compile_fail` blocks. The integration test file is reduced to a docstring pointing at the canonical location plus its existing positive `#[test]` functions (constructor smoke, Op trait impl, OpKind/Output coverage). ## Verification (orchestrator-run, contract crate only) - `cargo test ... --lib` → 472/472 passed (no regression). - `cargo test ... --tests` → 4/4 passed (new CI gate). - `cargo test ... --doc` → 7 passed + 3 ignored = 10 total (was 3 + 3 = 6; +4 compile_fail proofs now enforced). - `cargo fmt --check` → clean on the 4 files touched. No new dependencies; lance-graph-contract stays zero-dep std-only.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/rust-test.yml (1)
24-84:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd least-privilege
permissionsforGITHUB_TOKENinrust-test.yml
.github/workflows/rust-test.ymlhas no top-levelpermissions:block, soGITHUB_TOKENscopes fall back to repo/org defaults. Because the workflow only checks out code and runs tests, restrict the token to read-only (at leastcontents: read).Suggested fix
name: Rust Tests on: push: @@ pull_request: @@ - .github/workflows/rust-test.yml + +permissions: + contents: read🤖 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 @.github/workflows/rust-test.yml around lines 24 - 84, Add a top-level permissions block to the workflow to follow least-privilege for GITHUB_TOKEN: set permissions: contents: read (and any other minimal read-only scopes needed) for the entire workflow that defines the "test" job and its steps (e.g., the checkout and test steps), ensuring the GITHUB_TOKEN does not inherit broader repo/org defaults.
🤖 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.
Outside diff comments:
In @.github/workflows/rust-test.yml:
- Around line 24-84: Add a top-level permissions block to the workflow to follow
least-privilege for GITHUB_TOKEN: set permissions: contents: read (and any other
minimal read-only scopes needed) for the entire workflow that defines the "test"
job and its steps (e.g., the checkout and test steps), ensuring the GITHUB_TOKEN
does not inherit broader repo/org defaults.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: af935e41-f8de-4195-b0b0-87553f234ef5
📒 Files selected for processing (5)
.github/workflows/rust-test.ymlcrates/lance-graph-contract/src/cognition/entity.rscrates/lance-graph-contract/src/cognition/mod.rscrates/lance-graph-contract/src/cognition/op.rscrates/lance-graph-contract/tests/cognition_typestate.rs
🚧 Files skipped from review as they are similar to previous changes (2)
- crates/lance-graph-contract/src/cognition/mod.rs
- crates/lance-graph-contract/src/cognition/op.rs
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
2 participants
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.
Summary
Ships Stage 1 of
normalized-entity-holy-grail-v1(the canonical trunk plan that unifies the workspace's OGIT/OWL/DOLCE/Odoo inheritance + cognitive shader + JIT + MailboxSoA into ONE typed consumer pipeline grammar). Plan + 8 anchoring epiphanies + INTEGRATION_PLANS entry + the contract surface scaffold (~1750 LOC of typed signatures + compile-fail tests + crate-level example).3 commits:
1695a9a— plan file + 8 prepended epiphanies + INTEGRATION_PLANS entryb96baf3— Sonnet agent's contract surface scaffold (D-NEH-1a..g)8b3efca— main-thread/// work→// TODO(Stage 2):strip pass (45 markers reviewed + converted; nothing dropped)The shape
NormalizedEntity<S>— single struct, 4-way inheritance slots (Odoo → OGIT → OWL → DOLCE → FIBU/FIBO, last optional), typed lens into aMailboxSoArow, phantom-typedStageforbids out-of-order traversal at compile timeresolve_ogit/hydrate_owl/classify_dolce/align_fibu/op|chk_data|review|abduct|report|output) — 4 + 1; the chain methods together ARE thethinkverbapply(cold, ships in Stage 1),apply_stream(warm, Stage 2 with futures-rs),apply_soa(hot, Stage 2 with cognitive-shader-driver dep) — one trait, three speeds, shared const dataInteractive/Bulk/Periodisch) own commit + Baton epoch + Lance version policy + cascade traversal mode — consumer's typed enclosure picks the regime, NOT the shaderEdgeColumnwith 8CascadeKinddiscriminants (collapses Odoo's 6 overlapping mechanisms into one typed surface)Anchoring epiphanies (8 prepended to EPIPHANIES.md)
E-NORMALIZED-ENTITY-1— single typed carrier holds the 4-way inheritanceE-OP-FIVE-VERBS-1— only 5 universal verbs (4 + 1)E-OP-THREE-CALLSITES-1— same Op trait, three speeds, shared const dataE-TRANSACTION-CONTEXT-1— typed contexts own commit + epoch + versionE-CASCADE-AS-EDGECOLUMN-1— 6 Odoo cascade mechanisms collapse into 1 typed graphE-ODOO-AS-PRIOR-ART-1— Odoo solved the 3 regimes 15 years ago; we re-encode as compile-time typestate instead of stringly-typedenv.contextE-CONSUMER-CANNOT-INTERPRET-1(iron-rule candidate) — business heuristics MUST be SIMD-amenable const data; regex / hand-rolledif x.starts_with("84")becomes a MISSING FUNCTION, not a code-review concernE-NO-AUTOMATIC-REGIME-PICK-1— shader does NOT autonomously pick hot/warm/cold; the consumer's typed context does (correction of an earlier framing)What's IN this Stage 1
compile_faildoctests + 7 positive#[test]functions)no_runexample chain (woa-rs invoice flow) renderable viacargo doc// TODO(Stage 2):source comments flagging the wiring deferred to Stage 2 (OGIT codebook dispatch, OWL hydrator, DOLCE classifier, FIBU overlay, MailboxSoA column writes, async Stream backend choice, EdgeColumn impl, JIT chain handle)docs/COGNITION_HOLY_GRAIL.mdpointer to the planWhat's OUT (Stage 2..7, sketched in the plan)
woa_think!/medcare_think!/smb_think!) — pipe-style ergonomics on top of the typestate chainaccount.fiscal.year.closewizard)Test plan
cargo check -p lance-graph-contract— cleancargo test -p lance-graph-contract --lib— 472 lib tests green (zero regression from baseline)cargo test -p lance-graph-contract --test cognition_typestate— new typestate test crate green// TODO(Stage 2):source comments (visible to future agents; invisible in cargo doc output)Note for reviewers
This is a scaffold + plan PR. Most of
cognition/advance.rs,transaction/{interactive,bulk,periodisch}.rs, andop.rs'sapply_stream/apply_soapaths aretodo!()bodies behind typed signatures; bodies land in Stage 2 once the cognitive-shader-driver + futures dependencies are wired. The typestate gate, the trait shape, the cascade discriminants, and the docs are real and meant to stabilise here.https://claude.ai/code/session_017gZ6sPRXYPj5n7uJ7NBtRv
Generated by Claude Code
Summary by CodeRabbit
New Features
Documentation
Tests
Chores