Skip to content

[glue] Introduce commonware-glue#3381

Open
clabby wants to merge 4 commits into
mainfrom
cl/glue
Open

[glue] Introduce commonware-glue#3381
clabby wants to merge 4 commits into
mainfrom
cl/glue

Conversation

@clabby
Copy link
Copy Markdown
Collaborator

@clabby clabby commented Mar 12, 2026

Overview

Adds the commonware-glue crate, which will house opinionated compositions of commonware primitives.

The first module within glue is stateful, which is a composition of commonware-storage's QMDBs and commonware-consensus' Application.

In the future, this crate also may house constructs like application-managed DKGs (a. la. reshare).

Depends On

@clabby clabby self-assigned this Mar 12, 2026
@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented Mar 12, 2026

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Updated (UTC)
✅ Deployment successful!
View logs
commonware-mcp b8b8cdb May 22 2026, 09:30 PM

@cloudflare-workers-and-pages
Copy link
Copy Markdown

cloudflare-workers-and-pages Bot commented Mar 12, 2026

Deploying monorepo with  Cloudflare Pages  Cloudflare Pages

Latest commit: b8b8cdb
Status: ✅  Deploy successful!
Preview URL: https://68b488d3.monorepo-eu0.pages.dev
Branch Preview URL: https://cl-glue.monorepo-eu0.pages.dev

View logs

@clabby clabby linked an issue Mar 12, 2026 that may be closed by this pull request
@clabby clabby force-pushed the cl/glue branch 2 times, most recently from ec309a7 to 96b2c10 Compare March 13, 2026 01:08
@clabby clabby added this to Tracker Mar 14, 2026
@clabby clabby moved this to In Progress in Tracker Mar 14, 2026
@clabby clabby force-pushed the cl/glue branch 3 times, most recently from 6684c46 to 2e52801 Compare March 16, 2026 02:58
Comment thread examples/sync/src/bin/client.rs Outdated
@clabby clabby force-pushed the cl/glue branch 7 times, most recently from 70184bd to 70446b7 Compare March 17, 2026 21:22
@clabby clabby changed the base branch from main to danlaine/batch-arc March 17, 2026 21:22
@clabby clabby force-pushed the cl/glue branch 3 times, most recently from 110ccdb to 490d076 Compare March 20, 2026 00:02
@clabby clabby force-pushed the cl/glue branch 2 times, most recently from 93f92d9 to dde00be Compare March 23, 2026 20:32
Base automatically changed from danlaine/batch-arc to main March 24, 2026 18:23
@clabby clabby force-pushed the cl/glue branch 3 times, most recently from 2ea214b to 88f6634 Compare April 23, 2026 21:42
Comment thread glue/src/simulate/team.rs Outdated
@clabby clabby force-pushed the cl/glue branch 2 times, most recently from c249898 to 2882334 Compare April 27, 2026 20:32
Comment thread glue/src/simulate/reporter.rs
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 4, 2026

Benchmark results

Tip

PASSED: No benchmark exceeded the regression threshold.

Benchmark comparison table
Benchmark Baseline (main) Current Delta Threshold Status
qmdb::merkleize/variant=any::unordered::fixed::mmr keys=10000 ch=false sync=false 1.625 ms 1.584 ms -2.51% 10.00% ✅ PASS
qmdb::merkleize/variant=current::ordered::fixed::mmb chunk=256 keys=10000 ch=true sync=false 3.118 ms 3.044 ms -2.39% 10.00% ✅ PASS

Baseline commit(s): 979d2a2f657f

Comment thread deployer/src/aws/ec2.rs Outdated
Comment thread glue/src/stateful/actor/bootstrap.rs Outdated
Comment thread deployer/src/aws/ec2.rs Outdated
Comment thread glue/src/stateful/actor/mailbox.rs Outdated
Comment thread glue/src/simulate/plan.rs
.unwrap_or(Duration::ZERO);
if time > elapsed {
ctx.sleep(time - elapsed).await;
}
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Schedule events silently misfire when added out of order

Low Severity

Schedule is documented as "A time-ordered sequence of simulation actions" but neither at() nor run_action_scheduler sort or validate chronological order. The scheduler computes elapsed time from start, then only sleeps if time > elapsed. If a user adds events out of order (e.g., 5s then 2s), the second event executes immediately after the first instead of at its intended time, silently producing incorrect simulation behavior. A debug_assert! in at() that the new time is >= the last event's time would catch this.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 31e8c9a. Configure here.

Comment thread glue/src/stateful/actor/core.rs Outdated
Comment thread glue/src/stateful/actor/processor.rs
Comment thread glue/src/stateful/actor/processor.rs
Comment thread glue/src/stateful/actor/core.rs Outdated
Comment thread glue/src/stateful/db/mod.rs Outdated
Comment thread glue/src/stateful/actor/bootstrap.rs Outdated
Comment thread glue/src/stateful/actor/bootstrap.rs
.values()
.filter(|v| **v >= required_view)
.count()
>= total
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Exit counts crashed validators

Medium Severity

The simulation passes target_count as the number of currently active validators, but MinimumFinalizations uses ProgressTracker::all_reached, which counts any validator that ever reported a finalization—including crashed nodes whose handles were removed. A run can end while still-active validators have not reached the required view.

Additional Locations (2)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit d28e265. Configure here.

Comment thread glue/src/stateful/actor/bootstrap.rs Outdated
// the actor sees a contiguous finalized stream after target
// selection. Every later finalized block can then become both a
// sync target update and an acknowledgement toward handoff.
marshal.set_floor(finalization.clone());
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to confirm, you provide marshal genesis on init rather than this directly?

Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 3 total unresolved issues (including 2 from previous reviews).

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 7db57b4. Configure here.

}

syncing.last_acknowledged = height;
acknowledgement.acknowledge();
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acknowledged blocks lost between sync completion and transition

High Severity

In handle_syncing_finalized, when target_sender.send(update) fails (because the sync engine finished and dropped the ring receiver), the code still advances last_acknowledged and calls acknowledgement.acknowledge(). This creates a gap: blocks between the sync engine's final height and last_acknowledged are acknowledged to marshal (so marshal won't redeliver them) but never incorporated into the databases. When try_enter_processing transitions to Processing mode, the processor's last_processed is the sync engine's final height, but the next block marshal delivers is above last_acknowledged. The intervening blocks were effectively swallowed, causing a "finalize replay state root must match block commitments" panic on the first post-transition finalization.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 7db57b4. Configure here.

Copy link
Copy Markdown
Collaborator Author

@clabby clabby May 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is correct. Old code handled this by buffering acks until sync was done to facilitate a graceful handoff to the Processing mode, was working on a tweak for this but ran out of time.

@codecov
Copy link
Copy Markdown

codecov Bot commented May 22, 2026

Codecov Report

❌ Patch coverage is 71.70942% with 1511 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.06%. Comparing base (2ac1695) to head (b8b8cdb).
⚠️ Report is 4 commits behind head on main.

Files with missing lines Patch % Lines
glue/src/stateful/db/current.rs 0.00% 216 Missing ⚠️
glue/src/stateful/db/immutable.rs 0.00% 172 Missing ⚠️
glue/src/stateful/actor/processor.rs 83.43% 135 Missing and 25 partials ⚠️
glue/src/stateful/db/keyless.rs 42.79% 135 Missing ⚠️
glue/src/stateful/db/keyless_unjournaled.rs 73.05% 122 Missing and 6 partials ⚠️
glue/src/stateful/db/compact_p2p/actor.rs 53.75% 106 Missing and 5 partials ⚠️
glue/src/stateful/db/immutable_unjournaled.rs 65.77% 99 Missing and 3 partials ⚠️
glue/src/stateful/db/any.rs 46.23% 100 Missing ⚠️
glue/src/simulate/plan.rs 85.78% 76 Missing and 14 partials ⚠️
glue/src/stateful/db/compact_p2p/handler.rs 16.66% 85 Missing ⚠️
... and 11 more
@@            Coverage Diff             @@
##             main    #3381      +/-   ##
==========================================
- Coverage   95.77%   95.06%   -0.71%     
==========================================
  Files         486      513      +27     
  Lines      201251   208260    +7009     
  Branches     4876     5103     +227     
==========================================
+ Hits       192754   197992    +5238     
- Misses       6862     8535    +1673     
- Partials     1635     1733      +98     
Files with missing lines Coverage Δ
glue/src/simulate/reporter.rs 100.00% <100.00%> (ø)
glue/src/stateful/actor/bootstrap.rs 100.00% <100.00%> (ø)
glue/src/stateful/actor/metrics.rs 100.00% <100.00%> (ø)
glue/src/stateful/db/mod.rs 79.62% <ø> (ø)
glue/src/stateful/db/p2p/metrics.rs 100.00% <100.00%> (ø)
glue/src/stateful/mod.rs 100.00% <100.00%> (ø)
storage/src/journal/contiguous/mod.rs 48.64% <ø> (ø)
storage/src/merkle/mod.rs 83.33% <ø> (ø)
storage/src/qmdb/sync/compact.rs 72.54% <100.00%> (+3.18%) ⬆️
storage/src/qmdb/sync/engine.rs 91.78% <100.00%> (ø)
... and 22 more

... and 28 files with indirect coverage changes


Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 979d2a2...b8b8cdb. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread glue/Cargo.toml
publish = true
version.workspace = true
license.workspace = true
description = "Bootstrap applications with commonware primitive compositions."
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: "Construct stateful applications with efficient synchronization."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Ready for Review

Development

Successfully merging this pull request may close these issues.

Introduce commonware-glue (?)

2 participants