anuna-research/elephant
1
0
Fork 0
Code Issues 6 Pull requests Projects Packages Wiki Activity Actions

CLI: add sync wait barriers by SID and closure fingerprint #24

New issue
Open
opened 2026-07-16 06:36:57 +00:00 by anuna-02 · 0 comments
anuna-02 commented 2026-07-16 06:36:57 +00:00 (Migrated from codeberg.org)
Copy link

Summary

Add scriptable synchronization barriers that wait until the local replica contains
specific signed entries or reaches an expected semantic closure fingerprint.

Motivation from the real two-machine run

Synchronization was eventual and bidirectional:

  1. machine B appended six B-signed statements;
  2. machine A eventually received them;
  3. machine A retracted six stopgap statements;
  4. machine B eventually received those A-signed retractions.

Intermittent relay/QUIC errors made fixed sleeps and raw entry counts poor barriers.
The run instead manually polled the journal for specific SIDs/signers, waited for more
than one sync interval, and compared custom closure fingerprints.

Issue #15 added per-peer status and #18 addresses serial dial delays. Neither provides
a declarative barrier suitable for a test harness or agent workflow.

Proposed CLI

For example:

elephant sync wait -t rootclaim-grounded \
  --contains-sid s-a45ce406cc54a3a5 \
  --contains-sid s-ebcce09df3b86323 \
  --timeout 2m --json

elephant sync wait -t rootclaim-grounded \
  --closure-fingerprint ee41f61d... \
  --stable-for 30s --timeout 5m --json

The first form is a local-receipt barrier. A future protocol-backed form could wait
for a named peer's acknowledged high-water mark, but should not be implied unless the
daemon can actually prove remote receipt.

Acceptance criteria

  • Supports one or more entry/SID or retraction-target predicates.
  • Supports the native semantic fingerprint proposed separately, once available.
  • --stable-for can require an unchanged journal head/closure across an interval.
  • Success, timeout, daemon-unreachable, and invalid-theory have distinct exit codes and
    structured JSON.
  • Output records the theory ID, satisfied predicates, elapsed time, latest peer health,
    and observed journal head/fingerprint.
  • Does not mistake local receipt for remote acknowledgement.
  • Tests cover delayed merge, timeout, daemon restart, and already-satisfied barriers.

Environment / evidence

Observed with Elephant 0.1.2. The final bidirectional checks are recorded in:
github.com/anuna-cooperative/flf-elephant-experiment@96ca63675e/runs/2026-07-16/grounded-machineB/sync-check.txt

### Summary Add scriptable synchronization barriers that wait until the local replica contains specific signed entries or reaches an expected semantic closure fingerprint. ### Motivation from the real two-machine run Synchronization was eventual and bidirectional: 1. machine B appended six B-signed statements; 2. machine A eventually received them; 3. machine A retracted six stopgap statements; 4. machine B eventually received those A-signed retractions. Intermittent relay/QUIC errors made fixed sleeps and raw entry counts poor barriers. The run instead manually polled the journal for specific SIDs/signers, waited for more than one sync interval, and compared custom closure fingerprints. Issue #15 added per-peer status and #18 addresses serial dial delays. Neither provides a declarative barrier suitable for a test harness or agent workflow. ### Proposed CLI For example: ```console elephant sync wait -t rootclaim-grounded \ --contains-sid s-a45ce406cc54a3a5 \ --contains-sid s-ebcce09df3b86323 \ --timeout 2m --json elephant sync wait -t rootclaim-grounded \ --closure-fingerprint ee41f61d... \ --stable-for 30s --timeout 5m --json ``` The first form is a local-receipt barrier. A future protocol-backed form could wait for a named peer's acknowledged high-water mark, but should not be implied unless the daemon can actually prove remote receipt. ### Acceptance criteria - Supports one or more entry/SID or retraction-target predicates. - Supports the native semantic fingerprint proposed separately, once available. - `--stable-for` can require an unchanged journal head/closure across an interval. - Success, timeout, daemon-unreachable, and invalid-theory have distinct exit codes and structured JSON. - Output records the theory ID, satisfied predicates, elapsed time, latest peer health, and observed journal head/fingerprint. - Does not mistake local receipt for remote acknowledgement. - Tests cover delayed merge, timeout, daemon restart, and already-satisfied barriers. ### Environment / evidence Observed with Elephant 0.1.2. The final bidirectional checks are recorded in: https://github.com/anuna-cooperative/flf-elephant-experiment/blob/96ca63675edd88cf4982449c5f78b9441c320a39/runs/2026-07-16/grounded-machineB/sync-check.txt
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
spec-005-vocab-reviewer-round
v0.1.6
v0.1.5
v0.1.4
v0.1.2
v0.1.1
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
anuna-research/elephant#24
No description provided.