CLI: add idempotent assert --ensure with theory and signer preconditions #21

New issue

Open

opened 2026-07-16 06:36:48 +00:00 by anuna-02 · 0 comments

anuna-02 commented

2026-07-16 06:36:48 +00:00

(Migrated from codeberg.org)

Summary

Add an idempotent assertion mode with theory-ID and signer preconditions so interrupted
agent runs can resume safely without hand-written journal/SID guards.

Motivation from the grounded two-machine run

Machine B successfully wrote six one-statement assertions, then the query battery
failed in a wrapper before artifacts were complete. Re-running the original script
would have issued the six writes again. The recovery script therefore had to hard-code
all returned SIDs and verify, for each one, the expected signer and active status in
log --json before continuing.

The run also relied on a local alias. A pre-write full theory-ID check was essential
because aliases are local and may point somewhere unexpected.

Proposed CLI

For example:

elephant assert --ensure \
  --expect-theory-id 00db633b... \
  --expect-signer did:crdt:64054e... \
  '(prefer b-market-linkage-not-origin r-market-nat)' \
  -t rootclaim-grounded --json

Suggested JSON result:

{"created":false,"sid":"s-...","status":"active","theory":"...","signer":"..."}

An explicit idempotency key could complement content-based --ensure if exact
statement identity is not sufficient.

Semantics to define

An identical active statement by the expected signer in the same theory returns its
existing SID and performs no append.
A matching but retracted statement should fail clearly by default rather than
silently reassert; any reassert/revive behavior should require an explicit option.
Theory-ID or signer mismatch fails before any write.
Concurrent identical --ensure calls do not create duplicates.
Ordinary assert retains its current append semantics.

Acceptance criteria

Text and JSON output distinguish created versus already-present.
Precondition failures are non-zero, structured, and side-effect free.
Tests cover active matches, retracted matches, signer mismatch, alias/ID mismatch,
and concurrent calls.
Documentation includes a resumable one-statement-at-a-time workflow.

Environment / evidence

Observed with Elephant 0.1.2. The run's manual recovery guard is in
finalize-machineB.sh:
github.com/anuna-cooperative/flf-elephant-experiment@96ca63675e/runs/2026-07-16/grounded-machineB/finalize-machineB.sh

### Summary Add an idempotent assertion mode with theory-ID and signer preconditions so interrupted agent runs can resume safely without hand-written journal/SID guards. ### Motivation from the grounded two-machine run Machine B successfully wrote six one-statement assertions, then the query battery failed in a wrapper before artifacts were complete. Re-running the original script would have issued the six writes again. The recovery script therefore had to hard-code all returned SIDs and verify, for each one, the expected signer and active status in `log --json` before continuing. The run also relied on a local alias. A pre-write full theory-ID check was essential because aliases are local and may point somewhere unexpected. ### Proposed CLI For example: ```console elephant assert --ensure \ --expect-theory-id 00db633b... \ --expect-signer did:crdt:64054e... \ '(prefer b-market-linkage-not-origin r-market-nat)' \ -t rootclaim-grounded --json ``` Suggested JSON result: ```json {"created":false,"sid":"s-...","status":"active","theory":"...","signer":"..."} ``` An explicit idempotency key could complement content-based `--ensure` if exact statement identity is not sufficient. ### Semantics to define - An identical active statement by the expected signer in the same theory returns its existing SID and performs no append. - A matching but retracted statement should fail clearly by default rather than silently reassert; any reassert/revive behavior should require an explicit option. - Theory-ID or signer mismatch fails before any write. - Concurrent identical `--ensure` calls do not create duplicates. - Ordinary `assert` retains its current append semantics. ### Acceptance criteria - Text and JSON output distinguish created versus already-present. - Precondition failures are non-zero, structured, and side-effect free. - Tests cover active matches, retracted matches, signer mismatch, alias/ID mismatch, and concurrent calls. - Documentation includes a resumable one-statement-at-a-time workflow. ### Environment / evidence Observed with Elephant 0.1.2. The run's manual recovery guard is in `finalize-machineB.sh`: https://github.com/anuna-cooperative/flf-elephant-experiment/blob/96ca63675edd88cf4982449c5f78b9441c320a39/runs/2026-07-16/grounded-machineB/finalize-machineB.sh

No labels

No milestone

No project

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#21

No description provided.

Rows
Columns