turnframe_core/
lib.rs

1//! `turnframe-core`: the contract every Turnframe crate is written against.
2//!
3//! **The model proposes meaning, deterministic code decides effects, committed
4//! events decide claims.** Persisted case state is authoritative and the
5//! transcript is history; a [`flow::WorkflowDefinition`] purely projects state
6//! into a view; an [`understanding::Understanding`] says what a turn asks, with the
7//! words behind every value; a [`reduce::TurnReducer`] gives every act an explicit
8//! result; commands travel with a trusted origin, a policy and a
9//! stable idempotency key; execution commits events, and every operational claim
10//! derives from them ([`response::claim_guard`]). The [architecture guide] walks
11//! it step by step.
12//!
13//! [architecture guide]: https://github.com/turnframe-rs/turnframe/blob/main/docs/architecture.md
14//!
15//! It has no async runtime, no HTTP client, no database driver and no provider
16//! wire types: types, pure functions and traits only. Runtime, stores, providers
17//! and the test kit are sibling crates.
18//!
19//! # Modules
20//!
21//! * [`ids`], [`case`], [`locale`], [`hash`], [`schema`]: identity, versions,
22//!   copy, canonical hashing, schema fingerprints.
23//! * [`flow`]: the Flow Map projector, invariants and the erased registry.
24//! * [`turn`], [`plan`], [`target`], [`reduce`], [`policy`], [`command`]: the
25//!   deterministic path from input to executable commands.
26//! * [`interaction`], [`event`], [`response`]: durable cards, the claim ledger
27//!   and the ordered response.
28//! * [`read`], [`knowledge`]: read-only context acquisition.
29//! * [`understanding`]: what a turn was understood to say, the reducer's input.
30//! * [`replay`], [`observe`], [`error`]: audit, metrics and the typed error family.
31//! * [`prompt`]: where prompt text comes from, and which prompt text produced
32//!   a turn. The trait and the reference live here; every concrete source
33//!   lives in `turnframe-prompt`, which this crate does not depend on.
34
35#![forbid(unsafe_code)]
36#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
37
38/// The crate README, compiled as a doc-test so its example cannot rot.
39#[cfg(doctest)]
40#[doc = include_str!("../README.md")]
41mod readme {}
42
43pub mod case;
44pub mod command;
45pub mod effort;
46pub mod error;
47pub mod event;
48pub mod flow;
49pub mod hash;
50pub mod ids;
51pub mod interaction;
52pub mod knowledge;
53pub mod locale;
54pub mod observe;
55pub mod operation;
56pub mod plan;
57pub mod policy;
58pub mod prompt;
59pub mod read;
60pub mod reduce;
61pub mod replay;
62pub mod response;
63pub mod schema;
64pub mod target;
65pub mod turn;
66pub mod understanding;
67
68/// The most used items, for `use turnframe_core::prelude::*`.
69pub mod prelude {
70    pub use crate::case::{CaseKey, CaseRef, Versioned};
71    pub use crate::command::{
72        AtomicityScope, ClaimMode, CommandBatch, CommandEnvelope, CommandOrigin, CommandPolicy,
73        ConfirmationPolicy, IdempotencyKey, ResolutionChannel, RiskClass, origin_satisfies,
74    };
75    pub use crate::error::{
76        DomainRejection, ErasedCallError, ErasureError, ErrorClassification, ExecutionError,
77        HashError, InteractionSpecError, InvariantViolation, OrchestratorError, RejectionCode,
78        RevisionConflict, StoreError,
79    };
80    pub use crate::event::{
81        Commit, CommittedEvent, EventRedaction, EventRef, ExternalStatus, OperationalReceipt,
82        ReceiptEvent, ReceiptSeverity, RedactedEvent,
83    };
84    pub use crate::flow::{
85        ErasedExecutor, ErasedObligation, ErasedWorkflow, ErasedWorkflowView,
86        InteractionRequirement, ObligationId, PhaseOwnership, RegisteredWorkflow,
87        TypedWorkflowAdapter, ViewOf, WorkflowDefinition, WorkflowExecutor, WorkflowNotice,
88        WorkflowRegistry, WorkflowRegistryBuilder, WorkflowView, check_erased_view, check_view,
89    };
90    pub use crate::hash::Digest;
91    pub use crate::ids::{
92        AccountId, AttemptId, BatchId, BlockId, CaseId, CaseRevision, CommandId, ConversationId,
93        EventId, InteractionId, ModelKey, OperationKey, OptionId, ProviderKey, ReceiptId,
94        RedactionAuthority, TargetToken, TurnId, UserId, WorkflowKey, WorkflowVersion,
95    };
96    pub use crate::interaction::{
97        AcceptedResponse, ActionClass, FieldValue, FreeformPolicy, Interaction, InteractionKind,
98        InteractionOption, InteractionPayload, InteractionSpec, InteractionStatus, InteractionView,
99        ReviewDiffEntry, StoredInteractionAction, TextResolutionPolicy, validate_response,
100    };
101    pub use crate::locale::{Locale, LocalizedText};
102    pub use crate::operation::{ArgumentSpec, OperationCatalog, OperationSpec};
103    pub use crate::plan::limits::PlanLimits;
104    pub use crate::plan::{ActAvailability, ActMutability, AnswerBasis, TargetPolicy};
105    pub use crate::policy::{PolicyDecision, PolicySnapshot};
106    pub use crate::prompt::{
107        LoadedPrompt, PromptError, PromptName, PromptRef, PromptSelector, PromptSource,
108        PromptVersion,
109    };
110    pub use crate::reduce::{
111        AnswerTask, CommandRef, PlannedAct, PlannedActResult, ReductionContext, ReductionPlan,
112        TurnReducer,
113    };
114    pub use crate::response::{AssistantTurn, ResponseBlock, ServerNotice};
115    pub use crate::schema::schema_for;
116    pub use crate::target::{ResolvedAct, ResolvedActKind, TargetResolution, TargetTokenMap};
117    pub use crate::turn::{ActorContext, InteractionResponse, TurnInput, TurnLimits};
118    pub use crate::understanding::{
119        ActId, ActStatus, ActTarget, Understanding, UnderstoodAct, UnitId,
120    };
121}
turnframe_core/lib.rs

turnframe_core/
lib.rs
