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

CLI: add a canonical semantic closure fingerprint and comparison command #20

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

Summary

Add a first-class, versioned closure fingerprint to Elephant so two replicas can
compare semantic convergence without maintaining bespoke jq | shasum pipelines.

Motivation from the grounded two-machine run

Machine A, machine B, and a clean replay reached the same semantic closure, but raw
status --json was not directly comparable:

  • conclusion order needed canonical sorting;
  • live theories contained two member conclusions, while the replay contained its own
    replay member;
  • hashing the rendered file versus the logical sequence differed by one terminal LF.

The harness ultimately sorted non-member conclusions by literal, rendered each as
{tag} {literal}, joined with LF, and hashed without an additional terminal LF. All
three then produced
ee41f61d95cdf26070c293c9713d2f1933d6fa675ed693ab9bd0c1fd78e74dbd.

Proposed CLI

For example:

elephant closure fingerprint -t rootclaim-grounded
elephant closure compare status-a.json status-b.json
elephant status -t rootclaim-grounded --fingerprint --json

The JSON result should include at least:

  • a versioned algorithm identifier;
  • the digest and hash algorithm;
  • the number of included conclusions;
  • which metadata classes were excluded;
  • optionally the canonical sequence.

Acceptance criteria

  • Fingerprints are independent of journal merge order and JSON conclusion order.
  • Membership, local aliases, theory IDs, signers, and timestamps are excluded by a
    documented default suitable for semantic convergence.
  • Positive and negative literals and their proof tags are included.
  • The byte-level framing, including newline handling, is specified and tested.
  • A comparison command has useful text/JSON output and distinct match/mismatch exit
    behavior.
  • Fixtures prove that the same corpus under different identities matches and that a
    changed proof tag does not.

This is distinct from journal-entry fingerprints and from per-peer health in #14 and
#15: it answers whether two replicas compute the same closure.

Environment / evidence

Observed with Elephant 0.1.2 in the real two-machine Experiment 2 run. Reproducer and
artifacts:
github.com/anuna-cooperative/flf-elephant-experiment@96ca63675e/runs/2026-07-16/grounded-machineB

### Summary Add a first-class, versioned closure fingerprint to Elephant so two replicas can compare semantic convergence without maintaining bespoke `jq | shasum` pipelines. ### Motivation from the grounded two-machine run Machine A, machine B, and a clean replay reached the same semantic closure, but raw `status --json` was not directly comparable: - conclusion order needed canonical sorting; - live theories contained two member conclusions, while the replay contained its own replay member; - hashing the rendered file versus the logical sequence differed by one terminal LF. The harness ultimately sorted non-member conclusions by literal, rendered each as `{tag} {literal}`, joined with LF, and hashed without an additional terminal LF. All three then produced `ee41f61d95cdf26070c293c9713d2f1933d6fa675ed693ab9bd0c1fd78e74dbd`. ### Proposed CLI For example: ```console elephant closure fingerprint -t rootclaim-grounded elephant closure compare status-a.json status-b.json elephant status -t rootclaim-grounded --fingerprint --json ``` The JSON result should include at least: - a versioned algorithm identifier; - the digest and hash algorithm; - the number of included conclusions; - which metadata classes were excluded; - optionally the canonical sequence. ### Acceptance criteria - Fingerprints are independent of journal merge order and JSON conclusion order. - Membership, local aliases, theory IDs, signers, and timestamps are excluded by a documented default suitable for semantic convergence. - Positive and negative literals and their proof tags are included. - The byte-level framing, including newline handling, is specified and tested. - A comparison command has useful text/JSON output and distinct match/mismatch exit behavior. - Fixtures prove that the same corpus under different identities matches and that a changed proof tag does not. This is distinct from journal-entry fingerprints and from per-peer health in #14 and #15: it answers whether two replicas compute the same closure. ### Environment / evidence Observed with Elephant 0.1.2 in the real two-machine Experiment 2 run. Reproducer and artifacts: https://github.com/anuna-cooperative/flf-elephant-experiment/tree/96ca63675edd88cf4982449c5f78b9441c320a39/runs/2026-07-16/grounded-machineB
hugooconnor commented 2026-07-16 06:40:52 +00:00 (Migrated from codeberg.org)
Copy link

good idea, conclusion with hash - so closures can compare across theory stores

good idea, conclusion with hash - so closures can compare across theory stores
hugooconnor commented 2026-07-16 09:44:51 +00:00 (Migrated from codeberg.org)
Copy link

Addressed in PR #28 (branch fix/cli-convergence-observability).

Addressed in PR #28 (branch `fix/cli-convergence-observability`).
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#20
No description provided.