feat(integration): lance-graph-contract 0.2.0 + Glue #2/#4 scaffolds (Sprint 0)#404
Merged
Merged
Conversation
…er, actor) Sprint 0 of the four-repo integration plan. Pure additions; the 0.1.x surface is unchanged so existing surrealdb-core consumers compile without code change at 0.1.x -> 0.2.0. New submodules: - ir: federated planner IR (Operator, OperatorKind, OperatorTree, Cardinality, EngineHint). Cross-engine planner vocabulary distinct from plan::PlannerContract (lance-graph's own planner) and from orchestration::OrchestrationBridge (cross-system step routing). - provider: backend provider markers (BackendId, MvccProvider, TikvBackedProvider, LanceBackedProvider). Zero-dep markers used by the federated planner to compose snapshot-consistent reads across TiKV / Lance / local KV TableProvider impls without pulling in DataFusion / Arrow as deps here. - actor: supervisable-shader vocabulary (SupervisableShader, SupervisionPolicy, RestartBackoff). Distinct from cognitive_shader::CognitiveShaderDriver (in-process driver); consumed by the upcoming cognitive-shader-actor crate to wrap shaders as ractor::Actor with let-it-crash supervision. Each module has doc-tests and unit tests. Zero new dependencies. Per .claude/plans/integration-plan.md (this branch) Sprint 0.
…r-actor (Sprint 0) Adds two new stub crates from the four-repo integration plan as workspace-EXCLUDED scaffolds (additive contract shape; promoted to members in Sprint 1/2 once heavy deps land). * crates/lance-graph-tikv-provider/ (Glue #2, plan §5) TikvNodeTableProvider + TikvEdgeTableProvider stubs implementing datafusion::catalog::TableProvider + lance_graph_contract::provider markers. Bodies are Sprint 1 unimplemented!() with the trait shape pinned. * crates/cognitive-shader-actor/ (Glue #4, plan §6) CognitiveShaderActor<S> wrapping any SupervisableShader (from the new lance_graph_contract::actor module) as a ractor::Actor with ShaderMessage enum + ShaderSupervisor stub. Bodies are Sprint 2 unimplemented!() pending ractor::Actor signature confirmation. Both crates depend only on lance-graph-contract = "0.2" (path) plus their domain crates (tikv-client / ractor); no existing crate gains or loses a dep. Workspace check stays unaffected (excluded). Workers: LG-1, LG-2. Sprint 0 of the four-repo wave.
Both crates/lance-graph-tikv-provider and crates/cognitive-shader-actor are in workspace.exclude, so they generate their own Cargo.lock when checked standalone. Other excluded crates in the workspace (bgz-tensor, bgz17, causal-edge, bge-m3, etc.) already follow this convention — committing the lockfiles pins their deps for standalone builds. Generated by the wave-1 worker verification (cargo check standalone in each crate dir before reporting back to the orchestrator).
…dedness + Arc<PlanProperties> + Debug
Resolves PP-13 savant REJECT verdict: wave-1 LG-1 scaffolded against
DataFusion 51-style APIs but Cargo.lock pins datafusion 53.1.0. The
6 compile errors broke down as:
1. ExecutionMode no longer in datafusion::physical_plan (removed in 53)
→ replaced with EmissionType + Boundedness from
datafusion::physical_plan::execution_plan
2. PlanProperties::new now takes 4 args (eq_props, partitioning,
emission_type, boundedness); the old 3-arg call used ExecutionMode
3. TableProvider now requires Debug on impls
→ manual `impl std::fmt::Debug` for TikvNodeTableProvider /
TikvEdgeTableProvider / TikvScanExec (tikv-client::TransactionClient
doesn't derive Debug, so manual impl just prints the struct name)
4. ExecutionPlan::properties now returns &Arc<PlanProperties> instead
of &PlanProperties → wrap PlanProperties in Arc + return Arc reference
Function bodies remain Sprint 1 unimplemented!("Sprint 1 stub") with
the correct return-type shapes. Bodies are out of scope for this fix;
only the surface compiles now.
Verified: `cargo check --manifest-path crates/lance-graph-tikv-provider/Cargo.toml`
exits 0 (4 warnings on unused imports + dead_code, acceptable for stubs).
Worker: W-LG-3. PP-13 REJECT resolved.
Pins three plan-vs-source mismatches that the savant flagged as AP6 drift, by appending a reconciliation note before §10 Cross-references. In each case the SHIPPED source is better than the original sketch in the §1 Contracts table / §6 example, so the docs are updated to match shipped reality rather than rewriting the source: 1. TikvBackedProvider extends MvccProvider (zero-dep) instead of datafusion::catalog::TableProvider directly. Preserves the contract crate's zero-dep guarantee. 2. The actor-wrapper trait is named SupervisableShader, not CognitiveShader. Avoids colliding with the pre-existing cognitive_shader::CognitiveShaderDriver trait in the same crate (different lifecycle semantics: driver = in-process ShaderDispatch; supervisable = actor lifecycle apply/apply_delta/drain). 3. ShaderMessage<P> is generic over the payload type P. The actor wrapper picks RecordBatch at instantiation; other consumers can pick alternative payloads. Better composition than monomorphic sketch. All three were applied during wave-1 scaffolding; this note pins the docs accordingly. The §1 Contracts table itself will be rewritten in a future plan-revision pass. Per PP-13 savant audit. Wave-3 of the four-repo integration.
…ith #[default] variant CI `clippy` job (PR #404) flagged two `clippy::derivable_impls` warnings in the 0.2.0 additive submodules. Both manual `impl Default` blocks replaced with `#[derive(Default)]` on the enum + `#[default]` attribute on the chosen variant: * SupervisionPolicy: derive Default; mark OneForOne with #[default]. Kept a const fn one_for_one() constructor for call-site readability. * EngineHint: derive Default; mark Auto with #[default]. 441/441 lance-graph-contract lib tests still pass. clippy clean. CI signal: PR #404 clippy.
…aderActor Sprint 1 Glue #4 implementation. Replaces the wave-1 commented-out scaffold with a real `ractor::Actor` impl against ractor 0.15.13: * Associated types: Msg = ShaderMessage<S::Payload>, State = Arc<S>, Arguments = Arc<S>. `S::Error: Into<anyhow::Error>` + `S::Payload: Debug` bounds added. * `pre_start`: identity (shader passed via Arguments lives in State). * `handle` dispatches all three `ShaderMessage` variants: - Apply: shader.apply(input) → reply with anyhow::Result<P> - ApplyDelta: shader.apply_delta(delta), no reply - Drain: spin-yield while inflight > 0, shader.drain(), reply (), `myself.stop(Some("drained"))` * End-to-end test `e2e_apply_doubles_input`: Counter shader (Payload=u32), spawn via `Actor::spawn`, ractor::call!(actor, ShaderMessage::Apply, input=5) → asserts Ok(10). `cargo test --manifest-path crates/cognitive-shader-actor/Cargo.toml`: 1/1 test passes; `cargo check` clean. Worker: W-LG-4. Sprint 1 of the four-repo integration.
Adds dated board-hygiene entry per the Mandatory Board-Hygiene Rule in CLAUDE.md. Records the wave-1..4 additions that landed during this session: * lance-graph-contract 0.2.0 with three new additive submodules (ir, provider, actor) * Two new excluded crates: crates/lance-graph-tikv-provider/ and crates/cognitive-shader-actor/ * Sprint-1 implementation progress checklist (LG-4 Actor impl + the cross-repo SO-6/SO-7 work in sea-orm) * PP-13 savant audit REJECTs resolved (DataFusion 53 API drift, [workspace]-table requirement for excluded ractor crates) Pure append: lines 210-263 prepended after the Last-updated paragraph and before the prior 2026-05-05 entry. No existing entries touched. Worker: W-BOARD-1.
Wave-5 worker W-INT-1. New excluded crate at `crates/four-repo-demo/`
that demonstrates three of the four glue surfaces working together:
* `cognitive-shader-actor::CognitiveShaderActor` wrapping a real
`SupervisableShader` (`SumShader`) — running-sum state via
`Arc<Mutex<i64>>`, payload is `arrow_array::RecordBatch`.
* `lance-graph-contract::actor::SupervisableShader` trait consumed
end-to-end (impl is real, not stub).
* `lance-graph-contract::ir::{Operator, OperatorTree, EngineHint,
Cardinality}` — builds a 3-node tree (RangeScan → Filter →
CognitiveApply) and computes total estimated cardinality.
The example at `examples/run_demo.rs`:
1. Spawns CognitiveShaderActor<SumShader> via ractor 0.15.13
2. Sends two ShaderMessage::Apply with single-row Int64 batches (5, 7)
3. Sends ShaderMessage::Drain
4. Prints the running sum (12) + the operator tree + cardinality estimate
Test results (cargo test --manifest-path crates/four-repo-demo/Cargo.toml):
* sum_shader_actor_running_sum ... ok
* operator_tree_has_three_nodes ... ok
* operator_tree_shape_correct ... ok
* operator_tree_total_cardinality ... ok
* 2 doc-tests pass
* All 6/6 tests pass
NOT demonstrated (and why, in the crate's lib.rs and README):
* Glue #1 surrealdb-ractor — needs a live SurrealDB
* Glue #2 lance-graph-tikv-provider — needs a TiKV cluster
* Glue #3 sea-orm-ractor — needs running Postgres + the derive
Workspace: added to `exclude` (heavy tokio + ractor + arrow deps).
.gitignore: `/crates/four-repo-demo/target/` to keep build artefacts
out of git.
Worker: W-INT-1. Wave-5 of the four-repo integration.
AdaWorldAPI
added a commit
that referenced
this pull request
May 19, 2026
Revert #404 — lance-surrealdb-analysis four-repo integration arc
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
Sprint 0 of the four-repo integration plan (lance-graph ↔ surrealdb ↔ sea-orm ↔ ndarray). All work is additive contract shape — zero existing trait signature changes, zero existing module moves, zero existing file deletes.
lance-graph-contract 0.2.0— three new submodules (ir,provider,actor) carrying the federated planner IR + Arrow provider markers + supervisable-shader vocabulary. Existing 0.1.x surface unchanged so today's surrealdb-core consumers compile without code change.crates/lance-graph-tikv-provider/(new, inworkspace.exclude) — Glue Module 6: #[track_caller] error macros for zero-cost location capture #2: TiKV ranges → ArrowTableProvider. Implements DataFusion 53TableProvider+MvccProvidermarkers from the new contract submodule. Bodies stay Sprint 1unimplemented!().crates/cognitive-shader-actor/(new, inworkspace.exclude) — Glue Claude/setup adaworld repos 4k pex #4: wraps anySupervisableShaderas aractor::ActorwithShaderMessage<P>mailbox +RestartBackoffsupervisor. Bodies stay Sprint 2unimplemented!()..claude/plans/integration-plan.mdfiles with the additive-contract-shape principle codified and cross-referenced across all four repos.Commits in this PR (oldest first)
415a9efc47d10a5b9b532617f6a5344ee931e1840e2dcb1b1Coordinated PRs in sibling repos
claude/lance-surrealdb-analysis-LXmugclaude/lance-surrealdb-analysis-LXmugclaude/lance-surrealdb-analysis-LXmugA
[patch."https://github.com/AdaWorldAPI/lance-graph.git"]block in the surrealdb PR redirectslance-graph-contractto the local path so surrealdb-core sees the 0.2.0 additions immediately during dev.Test plan
cargo check -p lance-graph-contract— passes cleancargo check --manifest-path crates/lance-graph-tikv-provider/Cargo.toml— passes (4 warnings on unused imports + dead_code on stubs, expected)cargo check --manifest-path crates/cognitive-shader-actor/Cargo.toml— passes cleancargo test -p lance-graph-contract— all tests pass (new tests inir,provider,actorsubmodules: cardinality arithmetic, operator builder, snapshot-min, backoff exponential, supervisable shader defaults)cargo check -p surrealdb-core --features lance-graphpicks up the patched 0.2.0 contract cratelance-graph-tikv-provider+cognitive-shader-actor(out of scope of this PR)workspace.excludetomembersonce Sprint 1/2 land (out of scope of this PR)PP-13 savant audit
Ran a PP-13 brutally-honest-tester pass over the wave-1 output. Three REJECTs (DataFusion 53 compile errors in tikv-provider, missing
[workspace]in surrealdb-ractor / sea-orm-ractor) all addressed in wave-3. Three AP6 drift HOLDs reconciled in plan §post-script (commit2dcb1b1). Final compile-verification matrix in the wave-3 commit messages.https://claude.ai/code/session_01LiUiGeUDLje8KMnxB4FfA3
Generated by Claude Code