feat(soa+ogar): cycle-aware write contract + DO-arm ActionDef/ActionInvocation + OGAR consumer API

[AdaWorldAPI]

What

Implements the S2.5 cycle-aware write contract + the OGAR DO arm (the one wire both the 4-agent sale_order probe and the merged cross-repo PR survey agreed was missing), with a consumer-facing OGAR API doc. Stacked on #537 (the plans this implements); base retargets to main when #537 merges.

All mailbox-thoughtspace work is default-OFF; the substrate-sanity harness runs on the default build. Green: contract + driver lib/doc tests, harness 8/8, w2_differential 4/4 under the feature.

1. Write deinterlacing (mailbox_soa.rs)

• write_row(row, cycle, &WriteCell) -> WriteOutcome{Accepted,Stale,Future} — the one cycle-aware mutator. Wrap-aware gate (current_cycle.wrapping_sub + half-range) so a post-u32-wrap straggler is Stale, not mis-read Future.
• last_write_cycle: [u32; N] (second stamp, separate from the last_active_cycle consumption stamp; cleared in reset_row). stale_write_count telemetry. Infallible WriteOutcome (ownership compile-proven — stale/future is an outcome, not a failure).
• WriteCell field-presence staging (only Some fields applied).
• BackingStoreWrite::write_row routes the Mailbox arm through the gate; the Singleton(&BindSpace) arm is cycle-blind by construction (no current_cycle; the gate is a Mailbox-only guarantee until W7 deletes BindSpace).

2. Kanban / planner / SurrealQL cycle-awareness

• KanbanMove::cycle() accessor over the already-stamped witness_chain_position — the move, the planner that consumes it, and a ExecTarget::SurrealQl read-as-of are cycle-aware off one source of truth, without growing the ≤16 B baton.

3. NaN / tautology harness (tests/substrate_sanity.rs, 8 tests)

Verdict: the substrate is NaN-free and non-tautological on every surface tested — qualia f32 projection finite over the full i4 range; energy finite through consume; the write gate genuinely discriminates current/stale/future and is wrap-aware; field-presence honored; distinct writes stay distinct; zero-edge fabricates no energy.

4. The OGAR DO arm (lance-graph-contract::action)

The Perdurant complement of the Endurant field-set:

• ActionDef (static, const-constructible like MethodSig): predicate (= harvested has_function), object_class (classid), exec (ExecTarget incl SurrealQl), guard (StateGuard), required_role (RBAC), overrides (OGAR classid→ClassView inheritance).
• ClassActions + actions_for (zero-fallback); effective_actions(parent, child) = OGAR inheritance (child overrides parent by predicate).
• ActionInvocation (dynamic, Copy): lifecycle Pending→Committed|Failed|Cancelled, S2.5 cycle stamp, idempotency/trace keys, HLC emitted_at_millis.
• commit gate (the egress): RBAC first (auth::ActorContext must hold required_role or be admin → else Failed), then MUL impact (mul::GateDecision: Flow→Committed+stamped, Hold→Pending/escalate, Block→Cancelled). This is "commit to the external consumer (odoo/openproject/woa/tesseract) after the cycle decides sound." Dispatched via UnifiedStep/ExecTarget, never a per-crate endpoint.

5. docs/OGAR_CONSUMER_API.md

The consumer contract for odoo-rs / openproject-nexgen-rs / woa-rs / tesseract-rs: THINK + DO surfaces, the harvest→generate recipe, the Core-First iron rules, and the minimal AR→DO existence proof.

Board hygiene

LATEST_STATE.md Contract Inventory updated (D-DO-ARM-1) in the same commit as the type.

Honest remaining (not in this PR)

• Generating per-consumer ClassActions from each model's has_function (codegen, downstream, like ClassMethods).
• ClassView::{compute_dag, constraints} extension (the named Core gap for computed-field recompute/validation dispatch).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CcpLeEC3XK8Eye53GKBVvi

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Action invocation system with role-based authorization and state validation
  • Cycle-aware write tracking with stale/future write detection
  • Cycle accessor for move operations

• Tests

  • Comprehensive substrate sanity tests for numerical safety and write validation

• Documentation

  • Added OGAR consumer API specification
  • Added stack scaffold reference guide

[coderabbitai]

Warning

Review limit reached

@AdaWorldAPI, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 50 minutes and 29 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 73fc7a70-2f2b-4b6f-88f3-25205e8f4ca1

📥 Commits

Reviewing files that changed from the base of the PR and between 56a077f and 2821a03.

📒 Files selected for processing (2)

• .claude/board/INTEGRATION_PLANS.md
• .claude/plans/lite-unified-surrealql-lance-v1.md

📝 Walkthrough

Walkthrough

Adds the OGAR "DO arm" action IR to lance-graph-contract (ActionDef, ClassActions, ActionInvocation with a gated commit() state machine) and introduces a cycle-aware write API to MailboxSoA (WriteOutcome, WriteCell, write_row with wrap-safe cycle classification). Also adds KanbanMove::cycle(), fixes FakeSoa cycle stamping, adds a substrate sanity test suite, and publishes consumer-facing and stack-scaffold documentation.

Changes

OGAR DO Arm — Action IR Contract

Layer / File(s)	Summary
Action static types, registry, and module wiring crates/lance-graph-contract/src/lib.rs, crates/lance-graph-contract/src/action.rs	Declares ActionState, StateGuard, ActionDef, ClassActions, actions_for, and effective_actions (with inheritance-aware predicate merging); registers the module as pub mod action in lib.rs.
ActionInvocation lifecycle and commit state machine crates/lance-graph-contract/src/action.rs	Defines ActionInvocation with pending() constructor and commit() enforcing def-match → RBAC → optional state guard → MUL gate ordering with sticky terminal states; comprehensive unit tests cover all adjudication branches.
OGAR consumer API documentation and board state docs/OGAR_CONSUMER_API.md, .claude/board/LATEST_STATE.md	Adds OGAR_CONSUMER_API.md covering THINK/DO arms, commit adjudication order, UnifiedStep dispatch, iron rules, per-consumer wiring recipe, status section, and an end-to-end Rust example; updates board state with the DO arm inventory entry.

MailboxSoA Cycle-Aware Write Infrastructure

Layer / File(s)	Summary
WriteOutcome, WriteCell types and MailboxSoA field additions crates/cognitive-shader-driver/src/mailbox_soa.rs	Introduces WriteOutcome (Accepted/Stale/Future), WriteCell field-presence staging struct, adds last_write_cycle per-row field (sentinel u32::MAX) and stale_write_count telemetry to MailboxSoA, and initializes them in new().
write_row cycle-gate, reset_row extension, KanbanMove::cycle, and FakeSoa fix crates/cognitive-shader-driver/src/mailbox_soa.rs, crates/lance-graph-contract/src/kanban.rs, crates/lance-graph-contract/src/soa_view.rs, crates/lance-graph-contract/src/scheduler.rs	Implements write_row with wrap-aware cycle classification; extends reset_row to clear last_write_cycle; adds KanbanMove::cycle() exposing witness_chain_position; fixes FakeSoa::advance_phase to stamp the live cycle value instead of 0; updates scheduler comment to reference KanbanMove::cycle().
BackingStoreWrite::write_row and substrate sanity test suite crates/cognitive-shader-driver/src/backing.rs, crates/cognitive-shader-driver/tests/substrate_sanity.rs	Adds BackingStoreWrite::write_row dispatching to MailboxSoA::write_row under the mailbox-thoughtspace feature or applying all present cell fields via singleton setters; adds substrate sanity harness covering NaN/Inf safety, cycle-gate discrimination, wrap-around, field-presence isolation, content distinctness, projection discriminativeness, and zero-energy edge.
Stack scaffold reference documentation docs/STACK_SCAFFOLD.md	Adds STACK_SCAFFOLD.md describing three-pillar runtime wiring (ndarray, ractor, surrealdb), example Cargo.toml with forked dependencies and kv-lance gap notes, and a reference Dockerfile with mold/multi-stage build.

Sequence Diagram(s)

sequenceDiagram
  participant Consumer
  participant ActionInvocation
  participant ActorContext
  participant GateDecision
  participant UnifiedStep

  Consumer->>ActionInvocation: pending(classid, target_guid, action_predicate)
  Consumer->>ActionInvocation: commit(def, actor, gate_decision, guard_val, now_millis)
  ActionInvocation->>ActorContext: check admin || required_role
  ActorContext-->>ActionInvocation: authorized / denied (→ Cancelled)
  ActionInvocation->>ActionInvocation: optional StateGuard field/value check (→ Cancelled on mismatch)
  ActionInvocation->>GateDecision: evaluate Flow / Hold / Block
  GateDecision-->>ActionInvocation: Committed (stamp emitted_at) / Pending / Cancelled
  ActionInvocation-->>Consumer: ActionState
  Consumer->>UnifiedStep: dispatch(ExecTarget) if Committed

Loading

sequenceDiagram
  participant Planner
  participant BackingStoreWrite
  participant MailboxSoA

  Planner->>BackingStoreWrite: write_row(row, cycle, &WriteCell)
  alt mailbox-thoughtspace feature enabled
    BackingStoreWrite->>MailboxSoA: write_row(row, cycle, cell)
    MailboxSoA->>MailboxSoA: wrap-aware cycle compare vs current_cycle
    alt cycle == current_cycle
      MailboxSoA-->>BackingStoreWrite: WriteOutcome::Accepted (fields applied, last_write_cycle stamped)
    else cycle < current_cycle
      MailboxSoA-->>BackingStoreWrite: WriteOutcome::Stale (stale_write_count++)
    else cycle > current_cycle
      MailboxSoA-->>BackingStoreWrite: WriteOutcome::Future (no mutation)
    end
  else singleton arm
    BackingStoreWrite->>BackingStoreWrite: apply present cell fields via per-field setters
    BackingStoreWrite-->>Planner: WriteOutcome::Accepted
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• AdaWorldAPI/lance-graph#427: Evolves the same MailboxSoA API surface in cognitive-shader-driver, adding thoughtspace columns and accessors that this PR builds on with write_row/WriteOutcome cycle-stamping.
• AdaWorldAPI/lance-graph#437: Modifies the same lance-graph-contract Kanban/SoA contract slice that this PR extends with KanbanMove::cycle() and FakeSoa::advance_phase cycle stamping.
• AdaWorldAPI/lance-graph#439: Extends KanbanMove lifecycle enforcement in the same kanban.rs and phase-stamping surface that this PR modifies with the cycle() accessor.

Poem

🐇 Hoppity-hop through the action lane,
A commit gate guards each Flow and Chain,
WriteCell arrives with its cycle stamp true,
Stale writes bounce back — only fresh ones go through!
The DO arm awakens, the THINK arm cheers,
And the substrate sanity test suite clears. 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title comprehensively captures the three main changes: cycle-aware write contract (S2.5), OGAR DO arm (ActionDef/ActionInvocation), and consumer API documentation.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9292652009

ℹ️ 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".

[chatgpt-codex-connector]

Reject mismatched action definitions before RBAC

When commit is called with an ActionDef that does not match this invocation's object_class/predicate, the method still authorizes against that unrelated definition's required_role. With a registry containing a guarded action_confirm and an unguarded action_cancel, a caller can build an action_confirm invocation, pass the cancel definition, and reach Committed under GateDecision::Flow without the confirm role. Since these fields are documented as identifying the realized ActionDef, validate the definition match before applying RBAC/MUL.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Enforce state guards before committing actions

For actions with guard: Some(StateGuard { field: "state", value: "draft" }), commit has no object-state input and proceeds solely from RBAC plus MUL, so a guarded action can be committed even when the target record is in a non-eligible state such as sent or cancelled. The new API docs and ActionDef comments say guards mean the action fires only when field == value; the egress should either evaluate the guard before Flow -> Committed or refuse guarded actions until a checked state is supplied.

Useful? React with 👍 / 👎.