1. 1//! vak-intent: the decision layer that turns a request into a typed,
2. 2//! inspectable, narrowing-only engagement.
3. 3//!
4. 4//! # What this crate is for
5. 5//!
6. 6//! vak decides a great deal before a turn runs — which model, which tools,
7. 7//! which budget, which approval posture, what "done" means — and until now it
8. 8//! made every one of those decisions without any model of what the user was
9. 9//! trying to do. The only classifier in the codebase was a keyword scan that
10. 10//! fired on thirteen English verbs, and the route ladder's demand scorer was
11. 11//! being fed zeros.
12. 12//!
13. 13//! This crate supplies that missing model, as three deliberately separate
14. 14//! things:
15. 15//!
16. 16//! * [`Reading`] — what the request *is*, **inferred** on seven orthogonal
17. 17//! axes ([`Act`], [`Horizon`], [`Stakes`], [`Evidence`], [`Clarity`],
18. 18//! [`Modality`], [`Attendance`]).
19. 19//! * [`Authority`] — what a human has **delegated** ([`Autonomy`] and an
20. 20//! [`Envelope`]). Never inferred, because a resolution bug must not be able
21. 21//! to change what the agent is allowed to do.
22. 22//! * [`Engagement`] — what the runtime will therefore **do**, derived from the
23. 23//! first two.
24. 24//!
25. 25//! # The one rule
26. 26//!
27. 27//! **Intent narrows, never widens.** An [`Engagement`]'s [`Limits`] may
28. 28//! subtract a capability, shorten the route ladder to a prefix, lower a
29. 29//! budget, or *raise* an approval floor. It can never grant a tool, extend a
30. 30//! ladder, raise a cap, or lower a floor.
31. 31//!
32. 32//! That is a property of the types rather than a rule to remember: [`Limits`]
33. 33//! is a meet semilattice whose top element ([`Limits::unrestricted`])
34. 34//! reproduces vak's pre-kernel behaviour, [`Limits::meet`] is the only
35. 35//! composition operator offered, and there is deliberately no `join` to reach
36. 36//! for by accident. [`Limits::is_at_most`] states the invariant as a
37. 37//! predicate, and the inline tests in `limits.rs` prove it holds
38. 38//! across every reading the resolver can produce.
39. 39//!
40. 40//! Two consequences worth stating explicitly:
41. 41//!
42. 42//! * **Intent never gates the permission engine.** Permission is evaluated
43. 43//! exactly as it always was; an engagement can only add an approval
44. 44//! requirement on top. Nothing here can authorize anything.
45. 45//! * **Uncertainty resolves to the orienting engagement.** A reading below the
46. 46//! confidence floor loads the orientation floor (files and memory) and
47. 47//! leaves every other admitted tool one `find_tools` call away; what a human
48. 48//! delegated still applies. Being unsure never removes a capability — it
49. 49//! only sends less up front. [`Engagement::general`], which restricts
50. 50//! nothing at all, is what a *disabled* kernel produces.
51. 51//!
52. 52//! # Reproducibility
53. 53//!
54. 54//! Tiers 0 and 1 are pure functions of recorded inputs, so a decision that
55. 55//! narrowed a turn can be reconstructed from the ledger months later. Tiers 2
56. 56//! and 3 may call a model and are marked `reproducible: false` with the model
57. 57//! id and prompt digest that produced them — the same honesty the routing
58. 58//! ledger applies to `Settlement::Unknown`. Never claim replay fidelity you do
59. 59//! not have.
60. 60
61. 61pub mod authority;
62. 62pub mod axes;
63. 63pub mod control;
64. 64pub mod engage;
65. 65pub mod goal;
66. 66pub mod limits;
67. 67pub mod outcome;
68. 68pub mod reading;
69. 69pub mod resolve;
70. 70pub mod signals;
71. 71pub mod strand;
72. 72
73. 73pub use authority::{
74. 74 ApprovalCeiling, Authority, Autonomy, Envelope, Escalation, GateFallback, PermissionCeiling,
75. 75};
76. 76pub use axes::{
77. 77 Act, Attendance, Clarity, EpistemicStance, Evidence, Horizon, Modality, Satisfaction, Stakes,
78. 78};
79. 79pub use engage::{
80. 80 Cadence, ClarifyPolicy, ContextProfile, DeliveryPosture, DemandHint, Engagement, HilMode,
81. 81 OutputShape, Posture, StopProfile, Urgency, apply_authority, derive,
82. 82};
83. 83pub use engage::{DOMAIN_VOCABULARY, FLOOR_DOMAINS};
84. 84pub use goal::{
85. 85 GoalControlState, GoalRelation, GoalState, GoalUpdate, goal_relation, next_goal_update,
86. 86};
87. 87pub use limits::{DomainSet, Limits};
88. 88pub use outcome::{
89. 89 Command, CompletionVerdict, ControlSource, EvidenceReceipt, EvidenceState,
90. 90 InterventionDecision, InterventionEvaluation, InterventionKind, InterventionRequest,
91. 91 OutcomeRequirement, OutcomeSpec, OutcomeStatus, RequirementEvaluation, RequirementImportance,
92. 92 RequirementKind, RequirementOrigin, RequirementStatus, evaluate_completion,
93. 93 evaluate_intervention, evaluate_requirements, evaluate_requirements_with_evidence,
94. 94 evaluate_requirements_with_receipt, evaluate_requirements_with_state, evaluate_response,
95. 95 evaluate_response_with_failures, evidence_state_from_age, evidence_state_from_receipt,
96. 96 human_review_state, parse_command,
97. 97};
98. 98pub use reading::{Confidences, Intent, Provenance, Reading, Tier};
99. 99pub use resolve::{
100. 100 Classification, Declared, RESOLVER_VERSION, Resolution, ResolverConfig, apply_classification,
101. 101 apply_envelopes, classification_budget, classification_prompt, implied_stakes,
102. 102 parse_classifications, prompt_digest, resolve,
103. 103};
104. 104pub use signals::{
105. 105 Attachment, HistoryFacts, Request, Signal, SignalKind, Surface, WorkspaceFacts, extract,
106. 106};
107. 107pub use strand::{Lineage, LineageHint, Strand, StrandRelation, ThreadFact};
108. 108