Module state 

Non-interactive frontier state transitions.

Write commands are proposal-first. Pending proposals are review artifacts; accepted proposals become canonical state events through one reducer.

Structs

FindingDraftOptions

ReviewOptions

ReviseOptions

StateCommandReport

Functions

add_artifact

Deposit a generic content-addressed artifact and emit an artifact.asserted canonical event. The full artifact is carried inline on the event payload so a future replay reconstructs the artifact table without reading .vela/artifacts.

add_finding

add_finding_entity

v0.79: Append a new entity tag to an existing finding. Lands as a signed finding.entity_added event. Idempotent on (finding_id, entity_name): re-applying with the same name + type is a no-op so federation re-sync stays clean. Closes the v0.78.4 honest gap that forced reviewers to append new findings just to add a tag.

add_negative_result

v0.49: Add a NegativeResult to the frontier, emitting a negative_result.asserted canonical event.

add_note

append_trajectory_step

v0.50: Append a step to an existing Trajectory. Step kind one of hypothesis | tried | ruled_out | observed | refined. Idempotent on duplicate step content-addresses (so an agent that re-runs an append after a crash doesn’t double-append).

caveat_finding

create_trajectory

v0.50: Open a new Trajectory and emit a trajectory.created canonical event. Returns the new vtr_* id in the report’s finding_id field (the StateCommandReport schema reuses that field for the primary mutated object id).

deposit_prediction

v0.70: deposit a Prediction record onto the frontier as a signed canonical prediction.deposited event. Mirror of deposit_replication for the Prediction primitive.

deposit_replication

v0.70: deposit a Replication record onto the frontier as a signed canonical replication.deposited event. Idempotent under re-application: if the vrep_* id already exists on the frontier, the helper refuses with a clear error rather than silently no-op’ing. The event is appended to the canonical event log; the reducer arm projects it onto Project.replications on subsequent loads.

finding_context

history

history_as_of

v0.55: time-travel replay. When as_of is Some(ts), the returned events / review_events / confidence_updates are filtered to records whose timestamp is <= ts (RFC3339 lexicographic compare), the confidence field reports the score at that time (last confidence update at-or-before cutoff, or genesis if none), and a replayed_at_score field surfaces it explicitly so a caller doesn’t need to walk the updates array.

record_attestation

v0.80.1: Per-event attestation. Emit an attestation.recorded canonical event pointing at a target vev_* id, recording who attested it, the scope, and an optional Carina Proof primitive id + Ed25519 signature. Append-only: re-attesting the same target event by the same attester writes a new attestation event (each carries a unique id).

reject_finding

repair_evidence_atom_locator

v0.56: Mechanically repair a missing evidence-atom locator by copying the locator from the parent source record. If locator is None the resolver pulls the value from frontier.sources for the atom’s parent. The proposal carries both the resolved locator and the source id it was derived from so a fresh replay reconstructs the derivation without re-resolving.

repair_finding_span

v0.57: Mechanically repair a missing evidence-span on a finding by appending a {section, text} span. The proposal lands as a finding.span_repair and the canonical event as finding.span_repaired.

resolve_finding_entity

v0.57: Resolve a single named entity inside a finding’s assertion.entities to a canonical id with resolution metadata. Clears the entity’s needs_review flag. Lands as a signed finding.entity_resolved event.

resolve_frontier_conflict

v0.59: record a reviewer’s verdict on a previously detected federation conflict. Pairs with the existing frontier.conflict_detected event by conflict_event_id. The conflict event itself is not modified; this helper appends a new frontier.conflict_resolved canonical event to the log.

retract_finding

review_finding

revise_confidence

set_causal

v0.38: Set or revise a finding’s causal_claim and (optionally) causal_evidence_grade. Appends an assertion.reinterpreted_causal event capturing the prior reading, the new reading, and the actor. Bypasses the proposal flow because (a) the mutation is local and reversible by another call, and (b) the schema layer ships ahead of the reasoning surface — the next milestone will route this through proposals once the do-calculus layer needs it.

set_tier

v0.51: Re-classify the access tier of a finding / negative_result / trajectory / artifact. Emits a tier.set canonical event so the reclassification is replay-deterministic and auditable.

state_transitions

supersede_finding

v0.14: build the proposal that supersedes old_id with a new finding bundle.