engineering/arborist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

cli: 'aborist burn' — kindergarten leaf delete with audit event

Browse source 
Burn deletes a providence_cache row outright; falsify (the existing
verb) flips state and keeps the row. Burn is for early/scratch use
during a tree's genesis when downstream consumers haven't ingested
the answer yet.

Children gate: refuses if any falsifications reference the cache_key.
Caller can override with --force; the audit event records forced=True
plus the child count at burn time so the chain can reconstruct what
was orphaned. Refusal is non-destructive AND skips the audit event so
scripts can retry without polluting history.

Always writes a 'providence_burn' audit event regardless of force.
Body fields: cache_key, burned_audit_mode, burned_n_verified,
burned_state, question_text, reason, by_actor, child_falsifications_at_burn,
forced. The chain-break query (`make chain-check`) shows 0 after burn —
the new event extends the prior chain cleanly.

Surface:
  aborist burn --cache-key <hex> [--reason '...'] [--force]
  make burn KEY=<hex> REASON='...' [FORCE=1]

Tests (7): happy-path delete + audit event, refusal on children,
--force override, unknown-key not-found, chain-integrity preserved,
CLI happy path, CLI non-zero exit on refusal.
This commit is contained in:
russell@unturf.com 2026-04-28 17:03:30 -04:00
parent 01a4390693
commit 4a994b7ead
No known key found for this signature in database
3 changed files with 434 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

6
Makefile
View file

@ -31,7 +31,7 @@ SEARCH_Q ?= computer
ingest-grok ingest-grok-media \
ingest-self ingest-git ingest-hg \
verify search stats test docs chain-check chain-check-shards \
clean clean-db clean-data help
falsify burn clean clean-db clean-data help
all: bootstrap fetch-cur ingest-cur verify stats ## bootstrap → fetch cur → ingest cur → verify → stats
@ -123,6 +123,10 @@ falsify: bootstrap ## mark a cached answer wrong: make falsify KEY=hex REASON='w
@if [ -z "$(KEY)" ]; then echo "usage: make falsify KEY=<cache_key> REASON='why'" >&2; exit 2; fi
$(ABORIST) --shards-dir $(SHARDS_DIR) providence --falsify $(KEY) --reason "$(REASON)"
burn: bootstrap ## delete a leaf with no children: make burn KEY=hex REASON='why' [FORCE=1]
@if [ -z "$(KEY)" ]; then echo "usage: make burn KEY=<cache_key> REASON='why' [FORCE=1]" >&2; exit 2; fi
$(ABORIST) --shards-dir $(SHARDS_DIR) burn --cache-key $(KEY) --reason "$(REASON)" $(if $(FORCE),--force,)
# Multi-source RAG query against the shard cluster.
# Usage: make query Q="What is anarcho-capitalism?"
QUERY_TOP_K ?= 8

133
aborist/cli.py
View file

@ -445,6 +445,108 @@ def _falsify_cache_key(
return {"status": "not_found", "cache_key": cache_key_value}
def _burn_cache_key(
cache_key_value: str,
*,
reason: str,
by_actor: str,
shards_dir: Path | None,
db_path: Path | None,
force: bool = False,
) -> dict:
"""Delete a providence_cache leaf, but only if it has no children.
"Kindergarten of a tree's genesis" — early/scratch use. Falsify keeps
history; burn removes the row. Children today = falsifications
referencing this cache_key. If any exist, refuse without ``--force``.
Always writes a 'providence_burn' audit event so the chain records
that a leaf was removed and why. Use ``aborist providence --falsify``
instead when downstream consumers may have built on this answer.
"""
import time as _time
from aborist.store import append_audit, discover_shards, transaction
paths: list[Path] = (
discover_shards(shards_dir) if shards_dir else [Path(db_path)]
)
for sp in paths:
c = connect(sp)
try:
row = c.execute(
"SELECT cache_key, audit_mode, n_verified, falsification_state, "
" question_text FROM providence_cache WHERE cache_key = ?",
(cache_key_value,),
).fetchone()
if row is None:
continue
child_falsifications = c.execute(
"SELECT COUNT(*) FROM falsifications WHERE cache_key = ?",
(cache_key_value,),
).fetchone()[0]
if child_falsifications > 0 and not force:
return {
"status": "refused_has_children",
"cache_key": cache_key_value,
"shard": sp.name,
"child_falsifications": int(child_falsifications),
"hint": "use --force to burn anyway, or 'providence --falsify' to keep history",
}
now = int(_time.time())
with transaction(c):
c.execute(
"DELETE FROM providence_cache WHERE cache_key = ?",
(cache_key_value,),
)
event_hash = append_audit(
c,
event_type="providence_burn",
subject_root=cache_key_value,
body={
"cache_key": cache_key_value,
"burned_audit_mode": row["audit_mode"],
"burned_n_verified": int(row["n_verified"]),
"burned_state": row["falsification_state"],
"question_text": row["question_text"],
"reason": reason,
"by_actor": by_actor,
"child_falsifications_at_burn": int(child_falsifications),
"forced": bool(child_falsifications > 0 and force),
},
ts=now,
)
return {
"status": "burned",
"cache_key": cache_key_value,
"shard": sp.name,
"burned_audit_mode": row["audit_mode"],
"reason": reason,
"by_actor": by_actor,
"audit_event_hash": event_hash,
"ts": now,
}
finally:
c.close()
return {"status": "not_found", "cache_key": cache_key_value}
def _cmd_burn(args: argparse.Namespace) -> int:
"""CLI: burn a providence_cache leaf with no children."""
result = _burn_cache_key(
args.cache_key,
reason=args.reason or "",
by_actor=args.by_actor or os.environ.get("USER", "unknown"),
shards_dir=Path(args.global_shards_dir) if args.global_shards_dir else None,
db_path=Path(args.db) if args.db else None,
force=bool(args.force),
)
print(json.dumps(result, indent=2))
return 0 if result.get("status") == "burned" else 1
def _cmd_providence(args: argparse.Namespace) -> int:
"""List providence_cache records or falsify one by cache_key."""
if getattr(args, "falsify", None):
@ -1767,6 +1869,37 @@ def build_parser() -> argparse.ArgumentParser:
)
prov_cmd.set_defaults(func=_cmd_providence)
burn_cmd = sub.add_parser(
"burn",
help=(
"delete a providence_cache leaf with no children "
"(kindergarten use; falsify is the audit-preserving alternative)"
),
)
burn_cmd.add_argument(
"--cache-key",
dest="cache_key",
required=True,
help="cache_key (hex) of the providence record to burn",
)
burn_cmd.add_argument(
"--reason",
default=None,
help="reason text recorded in the providence_burn audit event",
)
burn_cmd.add_argument(
"--by-actor",
dest="by_actor",
default=None,
help="who is burning (default: $USER)",
)
burn_cmd.add_argument(
"--force",
action="store_true",
help="burn even if children (falsifications) exist; not recommended",
)
burn_cmd.set_defaults(func=_cmd_burn)
reclassify_cmd = sub.add_parser(
"reclassify",
help="re-run the verifier against existing live providence records "

296
tests/test_burn.py Normal file
View file

@ -0,0 +1,296 @@
"""Burn — delete a providence_cache leaf with no children.
Burn vs falsify:
falsify keeps the row, flips falsification_state away from 'live'.
Audit event = 'falsify'. History is preserved.
burn deletes the row entirely. Audit event = 'providence_burn'.
Refuses if any falsifications reference this cache_key.
Burn is the kindergarten-stage operator: scratch work that built up
during a tree's genesis, before downstream consumers ingested it. Once
falsifications point at a record, burning would orphan them — the
default is to refuse, --force overrides for cleanup edge cases.
"""
from __future__ import annotations
import json
import time
import pytest
from aborist.cli import _burn_cache_key
from aborist.store import append_audit, connect, transaction
def _seed_providence_record(db_path, *, cache_key: str, question: str = "q?", audit_mode: str = "HYBRID") -> None:
"""Insert one minimal providence_cache row + a 'providence_query' audit
event so the chain has prior state. Mirrors what runner.ask() persists."""
conn = connect(db_path)
try:
with transaction(conn):
event_hash = append_audit(
conn,
event_type="providence_query",
subject_root=cache_key,
body={"cache_key": cache_key, "question": question},
)
conn.execute(
"INSERT INTO providence_cache "
"(cache_key, source_root, document_uri, question_hash, question_text, "
" answer_text, merkle_proof, model_profile_hash, conversation_hash, "
" governance_policy_hash, schema_version, canonicalization_version, "
" chunking_version, falsification_state, chain, audit_event_hash, "
" created_at, hit_count, audit_mode, n_quotes, n_verified, "
" unverified_quotes, verifier_method) "
"VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'live', 'private', ?, ?, 0, ?, 1, 1, NULL, 'quote')",
(
cache_key,
"00" * 32,
"https://example.com/doc",
"qh",
question,
"answer",
json.dumps({}),
"mp",
"ch",
"gh",
"v9.8.0",
"norm-v1",
"tok-512-v1",
event_hash,
int(time.time()),
audit_mode,
),
)
finally:
conn.close()
def _seed_falsification(db_path, *, cache_key: str) -> None:
"""Mark cache_key as falsified, leaving a falsifications row that makes
the leaf "have children" for burn's purposes."""
conn = connect(db_path)
try:
with transaction(conn):
event_hash = append_audit(
conn,
event_type="falsify",
subject_root=cache_key,
body={"cache_key": cache_key, "to_state": "failed", "reason": "test"},
)
conn.execute(
"INSERT INTO falsifications "
"(cache_key, state, reason, by_actor, at, audit_event_hash) "
"VALUES (?, 'failed', 'test', 'tester', ?, ?)",
(cache_key, int(time.time()), event_hash),
)
finally:
conn.close()
# ---------------------------------------------------------------------------
# Happy path
# ---------------------------------------------------------------------------
def test_burn_removes_row_and_writes_audit_event(tmp_path):
db = tmp_path / "qa.db"
KEY = "ab" * 32
_seed_providence_record(db, cache_key=KEY, audit_mode="UNGROUNDED")
result = _burn_cache_key(
KEY, reason="kindergarten cleanup", by_actor="alice",
shards_dir=None, db_path=db,
)
assert result["status"] == "burned"
assert result["cache_key"] == KEY
assert result["burned_audit_mode"] == "UNGROUNDED"
assert result["reason"] == "kindergarten cleanup"
assert result["by_actor"] == "alice"
assert isinstance(result["audit_event_hash"], str) and len(result["audit_event_hash"]) == 64
conn = connect(db)
try:
gone = conn.execute(
"SELECT 1 FROM providence_cache WHERE cache_key = ?", (KEY,)
).fetchone()
last = conn.execute(
"SELECT event_type, body, subject_root FROM audit_events "
"ORDER BY seq DESC LIMIT 1"
).fetchone()
finally:
conn.close()
assert gone is None
assert last["event_type"] == "providence_burn"
assert last["subject_root"] == KEY
body = json.loads(last["body"])
assert body["cache_key"] == KEY
assert body["burned_audit_mode"] == "UNGROUNDED"
assert body["reason"] == "kindergarten cleanup"
assert body["by_actor"] == "alice"
assert body["forced"] is False
# ---------------------------------------------------------------------------
# Children gate
# ---------------------------------------------------------------------------
def test_burn_refuses_when_falsifications_exist(tmp_path):
"""A leaf with children must be falsified, not burned. Refusal preserves
the row AND skips the audit event so callers can retry cleanly."""
db = tmp_path / "qa.db"
KEY = "cd" * 32
_seed_providence_record(db, cache_key=KEY)
_seed_falsification(db, cache_key=KEY)
conn = connect(db)
try:
events_before = conn.execute("SELECT COUNT(*) FROM audit_events").fetchone()[0]
finally:
conn.close()
result = _burn_cache_key(
KEY, reason="oops", by_actor="alice", shards_dir=None, db_path=db,
)
assert result["status"] == "refused_has_children"
assert result["child_falsifications"] == 1
assert "hint" in result
conn = connect(db)
try:
still_there = conn.execute(
"SELECT cache_key FROM providence_cache WHERE cache_key = ?", (KEY,)
).fetchone()
events_after = conn.execute("SELECT COUNT(*) FROM audit_events").fetchone()[0]
finally:
conn.close()
assert still_there is not None
# Refusal must NOT write a providence_burn event — the chain only records
# actions actually taken.
assert events_after == events_before
def test_burn_force_overrides_children_gate(tmp_path):
"""--force burns even with falsifications; audit event marks forced=True."""
db = tmp_path / "qa.db"
KEY = "ef" * 32
_seed_providence_record(db, cache_key=KEY)
_seed_falsification(db, cache_key=KEY)
result = _burn_cache_key(
KEY, reason="forced cleanup", by_actor="alice",
shards_dir=None, db_path=db, force=True,
)
assert result["status"] == "burned"
conn = connect(db)
try:
gone = conn.execute(
"SELECT 1 FROM providence_cache WHERE cache_key = ?", (KEY,)
).fetchone()
last = conn.execute(
"SELECT body FROM audit_events ORDER BY seq DESC LIMIT 1"
).fetchone()
finally:
conn.close()
assert gone is None
body = json.loads(last["body"])
assert body["forced"] is True
assert body["child_falsifications_at_burn"] == 1
# ---------------------------------------------------------------------------
# Error paths
# ---------------------------------------------------------------------------
def test_burn_unknown_key_returns_not_found(tmp_path):
db = tmp_path / "qa.db"
# Empty DB; no records.
result = _burn_cache_key(
"00" * 32, reason="", by_actor="alice", shards_dir=None, db_path=db,
)
assert result["status"] == "not_found"
assert result["cache_key"] == "00" * 32
# ---------------------------------------------------------------------------
# Audit chain integrity
# ---------------------------------------------------------------------------
def test_burn_preserves_audit_chain(tmp_path):
"""After burn, the chain has no dangling prev_event_hash references —
same property `make chain-check` enforces."""
db = tmp_path / "qa.db"
KEY = "12" * 32
_seed_providence_record(db, cache_key=KEY)
_burn_cache_key(KEY, reason="t", by_actor="a", shards_dir=None, db_path=db)
conn = connect(db)
try:
breaks = conn.execute(
"""
SELECT COUNT(*) FROM audit_events a1
LEFT JOIN audit_events a2 ON a2.event_hash = a1.prev_event_hash
WHERE a1.prev_event_hash IS NOT NULL AND a2.event_hash IS NULL
"""
).fetchone()[0]
finally:
conn.close()
assert breaks == 0
# ---------------------------------------------------------------------------
# CLI integration
# ---------------------------------------------------------------------------
def test_burn_cli_invocation(tmp_path, capsys):
"""`aborist burn` end-to-end through build_parser, including JSON output."""
from aborist.cli import build_parser
db = tmp_path / "qa.db"
KEY = "fa" * 32
_seed_providence_record(db, cache_key=KEY)
parser = build_parser()
args = parser.parse_args([
"--db", str(db),
"burn",
"--cache-key", KEY,
"--reason", "via cli",
"--by-actor", "alice",
])
rc = args.func(args)
assert rc == 0
captured = capsys.readouterr()
payload = json.loads(captured.out)
assert payload["status"] == "burned"
assert payload["reason"] == "via cli"
def test_burn_cli_returns_non_zero_on_refused(tmp_path, capsys):
"""Non-zero exit when refused so scripts can detect and react."""
from aborist.cli import build_parser
db = tmp_path / "qa.db"
KEY = "fb" * 32
_seed_providence_record(db, cache_key=KEY)
_seed_falsification(db, cache_key=KEY)
parser = build_parser()
args = parser.parse_args([
"--db", str(db),
"burn",
"--cache-key", KEY,
"--reason", "wont land",
])
rc = args.func(args)
assert rc == 1
payload = json.loads(capsys.readouterr().out)
assert payload["status"] == "refused_has_children"