1. 1//! vak-commit: durable obligations, and a falsifiable answer to "is it done?"
2. 2//!
3. 3//! # What this replaces
4. 4//!
5. 5//! vak's unit of identity was the session, and completion was "the model
6. 6//! stopped talking". Both assumptions break as soon as work outlives one
7. 7//! conversation. A [`Commitment`] inverts them:
8. 8//!
9. 9//! | Before | Now |
10. 10//! |---|---|
11. 11//! | the session is the identity | the commitment is; sessions are [`Episode`]s that advance it |
12. 12//! | the model decides it is done | the **runtime** evaluates a predicate against the world |
13. 13//! | progress is tokens spent | progress is [`Advancement`]: criteria moved, or an explicit reason none did |
14. 14//! | blocking or losing the thread | [`Suspension`] against a typed wake condition |
15. 15//! | work quietly evaporates | every commitment [`Closure`]s with a [`Verdict`] and evidence |
16. 16//!
17. 17//! The agent loop does not disappear; it becomes the implementation of an
18. 18//! episode rather than the top-level abstraction.
19. 19//!
20. 20//! # The closure invariant
21. 21//!
22. 22//! A commitment declares the weakest [`vak_intent::Satisfaction`] that may
23. 23//! close it as [`Verdict::Fulfilled`], taken from its reading's `evidence`
24. 24//! axis. [`Commitment::may_close`] enforces it, and
25. 25//! [`ledger::CommitmentLedger::append`] refuses the event outright — a ledger
26. 26//! that can record a lie is not an audit trail.
27. 27//!
28. 28//! Crucially, the strength of a criterion comes from **how it was
29. 29//! established**, not from anyone's confidence: a shell command the runtime
30. 30//! ran is `Observed`, an external receipt is `Attested`, and the model's own
31. 31//! judgement is `Asserted` no matter how emphatically it is phrased. See
32. 32//! [`satisfy`].
33. 33//!
34. 34//! Failure verdicts are deliberately *unconstrained*. Recording a
35. 35//! [`Verdict::Failed`], a [`Verdict::Abandoned`], or an honest
36. 36//! [`Verdict::Unknown`] must always be possible, or the ledger could not tell
37. 37//! the truth about work that went wrong.
38. 38//!
39. 39//! # Reuse
40. 40//!
41. 41//! Criterion and evidence vocabulary comes from `vak-session`
42. 42//! (`CriterionKind`, `CriterionResult`, `EvidenceRef`, `WorkCriterion`,
43. 43//! `WorkOwner`) rather than being redefined here. That vocabulary already
44. 44//! expresses "this shell command exits zero" and "this flow completed"; a
45. 45//! second one for the same idea would be a liability.
46. 46
47. 47pub mod ledger;
48. 48pub mod portfolio;
49. 49pub mod satisfy;
50. 50pub mod types;
51. 51
52. 52pub use ledger::{CommitmentLedger, Event, EventKind, LedgerError, project, spec_from_reading};
53. 53pub use portfolio::{Priority, SchedulerContext, next, prioritize, rank};
54. 54pub use satisfy::{
55. 55 CriterionEvaluator, Evaluation, evaluate_all, is_machine_checkable, strength_of,
56. 56};
57. 57pub use types::{
58. 58 Advancement, Closure, ClosureRefusal, Commitment, CommitmentSpec, CriterionState, Economics,
59. 59 Episode, Phase, Suspension, Verdict,
60. 60};
61. 61