feat(callcenter): LanceMembrane::commit_event — action-commit sole-writer sibling (gate 1)

[AdaWorldAPI]

LanceMembrane::commit_event — gate 1, runtime side

Adds the action-commit sole-writer sibling the cross-session contract needs.
OGAR-AST-CONTRACT §3 (OGAR PR #11) wires LanceCommitHook::on_commit →
LanceMembrane::commit_event(row) -> u64; this is that fn.

pub fn commit_event(&self, row: CognitiveEventRow) -> u64 {
    let version = self.version.fetch_add(1, Ordering::AcqRel) + 1;
    #[cfg(feature = "realtime")]
    self.watcher.bump(row);
    #[cfg(not(feature = "realtime"))]
    let _ = row;
    version
}

Why a sibling, not a trait method. It stays on the concrete LanceMembrane,
not on the zero-dep ExternalMembrane trait — so the contract crate keeps zero
deps and action commits never get forced through the cognitive-cycle ShaderBus
shape that project() requires. project() is for cognitive cycles; this is for
explicit action commits (the Rubicon Pending → Committed crossing).

Semantics. Unlike project() (whose fan-out is gated by the server filter /
MembraneGate), the action commit is the authoritative audit event — the
rubberstamp — so it always ticks the version and fans out. Returns the new
monotonic Lance version.

Verified: cargo check -p lance-graph-callcenter green in both realtime
and default; test commit_event_ticks_version_and_returns_new passes.

Closes the runtime side of gate 1 (tracked in CROSS_SESSION_COORDINATION.md
grill #10). Companion to OGAR #11 (§3) + ractor_actors feat/state-machine-actor.

https://claude.ai/code/session_01VysoWJ6vsyg3wEGc5v7T5v

Summary by CodeRabbit

• New Features
  • Added event commit functionality with atomic version tracking to ensure consistent event processing state.
  • Included real-time event propagation support when enabled.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a new public commit_event method to LanceMembrane that atomically increments and returns a monotonic version counter. When the realtime feature is enabled, it forwards the provided CognitiveEventRow to LanceVersionWatcher::bump(); otherwise it discards the row. Includes unit test verifying monotonic version advancement.

Changes

Event commit path

Layer / File(s)	Summary
Monotonic version event commit crates/lance-graph-callcenter/src/lance_membrane.rs	commit_event method atomically increments and returns the membrane's version counter; under realtime feature, forwards the CognitiveEventRow to LanceVersionWatcher::bump(); unit test validates monotonic version advancement from 0 → 1 → 2.

Sequence Diagram

sequenceDiagram
  participant Client
  participant LanceMembrane
  participant VersionCounter
  participant LanceVersionWatcher

  Client->>LanceMembrane: commit_event(CognitiveEventRow)
  LanceMembrane->>VersionCounter: increment and fetch
  VersionCounter-->>LanceMembrane: new version value
  alt realtime feature enabled
    LanceMembrane->>LanceVersionWatcher: bump(row)
    LanceVersionWatcher-->>LanceMembrane: acknowledged
  else non-realtime build
    LanceMembrane->>LanceMembrane: discard row
  end
  LanceMembrane-->>Client: return version (u64)

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A membrane so fine, with versioning true,
Each event commits—version counter's new brew.
With realtime hops or silent grace,
Monotonic progress, one event per trace. 🐰✨

🚥 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 accurately describes the main change: adding a new LanceMembrane::commit_event method as the action-commit sole-writer path, with the reference to 'gate 1' reflecting the PR's role in closing gate 1 of the cross-session coordination contract.
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.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

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.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

crates/lance-graph-callcenter/src/lance_membrane.rs (1)

289-293: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify when the version counter increments.

The doc comment states "ticks on each CollapseGate Persist", but the implementation only increments the version counter in commit_event (line 316), not in project(). Since commit_event is the "action-commit sole-writer" (line 295), the documentation should clarify that the version ticks on action commits, not on all CollapseGate events.

📝 Suggested doc comment revision

-    /// Current Lance version counter (monotonic; ticks on each CollapseGate
-    /// Persist). Phase D wires this to the Lance dataset version.
+    /// Current Lance version counter (monotonic; incremented by action commits
+    /// via `commit_event`). Phase D wires this to the Lance dataset version.
     pub fn version(&self) -> u64 {

🤖 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-callcenter/src/lance_membrane.rs` around lines 289 - 293,
The doc comment for the version() method is misleading: it says the counter
"ticks on each CollapseGate Persist" but the code only increments the counter in
commit_event (the action-commit sole-writer) and not in project(); update the
documentation to state that the version counter increments on action commits
handled by commit_event (or when the action-commit path persists), not on every
CollapseGate persistence, and mention that project() does not advance the
version to avoid implying incorrect semantics.

🧹 Nitpick comments (1)

crates/lance-graph-callcenter/src/lance_membrane.rs (1)

551-564: 💤 Low value

Consider adding test coverage for the realtime feature path.

The current test verifies the version increment behavior, which is excellent. For additional confidence, consider adding a test that verifies watcher.bump() is called when the realtime feature is enabled, perhaps by subscribing and checking that the row is received.

💡 Example test structure

#[cfg(feature = "realtime")]
#[test]
fn commit_event_bumps_watcher_under_realtime() {
    let m = LanceMembrane::new();
    let rx = m.subscribe(CommitFilter::default());
    
    let row = CognitiveEventRow {
        thinking: 42,
        ..Default::default()
    };
    m.commit_event(row);
    
    let snapshot = rx.current();
    assert_eq!(snapshot.thinking, 42, "watcher should receive the committed row");
}

🤖 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-callcenter/src/lance_membrane.rs` around lines 551 - 564,
Add a feature-gated test that exercises the realtime path: under #[cfg(feature =
"realtime")] add a test (e.g., commit_event_bumps_watcher_under_realtime) that
creates a LanceMembrane via LanceMembrane::new(), calls
m.subscribe(CommitFilter::default()) to obtain an rx, commits a known
CognitiveEventRow with m.commit_event(...), and then asserts the watcher
received the committed row (e.g., via rx.current() or the watcher API used in
the code); this verifies watcher.bump()/realtime propagation when the realtime
feature is enabled.

🤖 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 `@crates/lance-graph-callcenter/src/lance_membrane.rs`:
- Around line 289-293: The doc comment for the version() method is misleading:
it says the counter "ticks on each CollapseGate Persist" but the code only
increments the counter in commit_event (the action-commit sole-writer) and not
in project(); update the documentation to state that the version counter
increments on action commits handled by commit_event (or when the action-commit
path persists), not on every CollapseGate persistence, and mention that
project() does not advance the version to avoid implying incorrect semantics.

---

Nitpick comments:
In `@crates/lance-graph-callcenter/src/lance_membrane.rs`:
- Around line 551-564: Add a feature-gated test that exercises the realtime
path: under #[cfg(feature = "realtime")] add a test (e.g.,
commit_event_bumps_watcher_under_realtime) that creates a LanceMembrane via
LanceMembrane::new(), calls m.subscribe(CommitFilter::default()) to obtain an
rx, commits a known CognitiveEventRow with m.commit_event(...), and then asserts
the watcher received the committed row (e.g., via rx.current() or the watcher
API used in the code); this verifies watcher.bump()/realtime propagation when
the realtime feature is enabled.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 23eae038-eabc-4308-b122-a113eb13b461

📥 Commits

Reviewing files that changed from the base of the PR and between e948e91 and 6e6f57f.

📒 Files selected for processing (1)

• crates/lance-graph-callcenter/src/lance_membrane.rs