arcature 2026.2.0

Arcature application framework: a high-level Application facade over the certified Arcature subsystems, with the low-level Axum/Tower escape hatch preserved.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184

//! The Arcature application DX layer (ADR-0001, ADR-0003).
//!
//! This module hosts the *runtime* contracts that the `arcature-dx`
//! proc-macro crate's macros generate code against. The proc-macro crate
//! itself depends on no Arcature runtime crate; its expansions reference
//! these types through absolute `::arcature::` paths, which resolve in the
//! downstream application crate (which has `arcature` on its dependency
//! graph).
//!
//! The module is gated behind the `dx` Cargo feature. Enabling `dx` pulls
//! in the `arcature-dx` proc-macro crate and re-exports its macros at the
//! crate root (`arcature::DxComponent` derive, and in later A-phases:
//! `routes!`, `#[controller]`, etc.).
//!
//! # Current surface (A1–A4)
//!
//! - [`DxComponent`] — a marker trait with a static [`DxComponent::NAME`].
//!   `#[derive(DxComponent)]` generates an `impl DxComponent` with the type
//!   name (or a custom name via `#[dx_component(name = "...")]`).
//! - [`ApplicationGraph`] — the assembled module dependency graph, with
//!   duplicate-module, unknown-import, and circular-dependency validation.
//! - [`ModuleDescriptor`] — a single feature module's metadata (name,
//!   imports, exports, controllers, services, policies, routes).
//! - [`GraphError`] — typed errors from graph validation.
//! - [`RouteMethod`] / [`RouteDescriptor`] — route metadata for the
//!   `routes!` macro (A3). Const-constructible, `&'static`-based.
//! - [`ControllerMethod`] — controller method metadata for `#[controller]`
//!   (A4). Const-constructible for `arc controllers` / `arc check` inspection.
//! - [`Empty`] — 204 No Content response (A4, always available with `dx`).
//! - [`Json`] / [`Page`] — high-level response types (A4, behind `serde`).
//!   Implement `IntoResponse` so controllers return `Result<Json<T>>`,
//!   `Result<Empty>`, `Result<Page<T>>` without manual plumbing.
//! - [`Validated`] — validated JSON request extractor (A5, behind `dx`
//!   and `api`). Delegates to `arcature_api::ValidatedJson<T>`. No
//!   homemade validation engine. Validation is the trust boundary, but
//!   does NOT imply authorization.
//! - [`RouteModel`] — a deliberate model-binding contract (A7, behind `dx`
//!   and `db`). A type implementing `RouteModel` can be loaded from the
//!   database by a route parameter. Binding does NOT imply authorization.
//! - [`Bound`] — a genuine Axum extractor that loads a model by route param
//!   (A7, behind `dx` + `db` + `api`). Returns 404 `Problem` on miss, 400 on
//!   malformed key, 500 on DB error.
//! - [`Resolve`] — typed application resource resolution (A8, ADR-0004).
//!   A type implementing `Resolve<S>` can be constructed from application
//!   state `S` — cheaply, at compile time, with no runtime container.
//!   `#[service]` generates `impl Resolve<S>`; Arcature provides impls for
//!   built-in resources (`Db`).
//! - [`Service`] — a marker for service types (A8). Extends `DxComponent`
//!   with `DEPS` metadata for `arc check` graph validation. Service
//!   dependency cycles are impossible by construction (value composition).
//! - [`Inject`] — an Axum extractor that constructs any `T: Resolve<S>`
//!   from application state (A8). Axum remains the handler runtime.
//! - [`Provider`] — a marker for startup-constructed application resources
//!   (A8, ADR-0004 §4). Carries `Error` and `DEPS`. The developer writes
//!   the init logic (business behavior, not mechanical plumbing).
//!
//! Later A-phases add `Auth<T>`, `Policy`, etc. — all as runtime contracts
//! that the macros generate code against.

pub mod application_graph;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod auth;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod auth_user;
#[cfg(all(feature = "dx", feature = "db", feature = "api"))]
pub mod bound;
#[cfg(all(feature = "dx", feature = "jobs"))]
pub mod command;
pub mod controller_metadata;
#[cfg(all(feature = "dx", feature = "db"))]
pub mod db_from_state;
#[cfg(all(feature = "dx", feature = "serde"))]
pub mod event;
pub mod field_metadata;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod flash;
pub mod graph;
#[cfg(all(feature = "dx", feature = "jobs", feature = "serde"))]
pub mod job;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod policy;
pub mod provider;
#[cfg(feature = "dx")]
pub mod request_cache;
pub mod resolve;
pub mod response;
pub mod route_metadata;
#[cfg(all(feature = "dx", feature = "db"))]
pub mod route_model;
#[cfg(all(feature = "dx", feature = "jobs"))]
pub mod scheduler;
pub mod service;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod session;
#[cfg(all(feature = "dx", feature = "auth"))]
pub mod user_loader;
#[cfg(all(feature = "dx", feature = "api"))]
pub mod validated;

pub use application_graph::{ApplicationGraph, GraphError};
#[cfg(all(feature = "dx", feature = "auth"))]
pub use auth::{
    Auth, AuthError, AuthManager, Current, LoginBuilder, OptionalAuth, OptionalCurrent,
};
#[cfg(all(feature = "dx", feature = "auth"))]
pub use auth_user::AuthUser;
#[cfg(all(feature = "dx", feature = "db", feature = "api"))]
pub use bound::Bound;
#[cfg(all(feature = "dx", feature = "jobs"))]
pub use command::{Command, CommandError, CommandRegistry};
pub use controller_metadata::{ControllerMetadata, ControllerMethod};
#[cfg(all(feature = "dx", feature = "db"))]
pub use db_from_state::DbFromState;
#[cfg(all(feature = "dx", feature = "serde"))]
pub use event::{DispatchError, Dispatcher, Event};
pub use field_metadata::{FieldShape, RequestMetadata, ResourceMetadata};
#[cfg(all(feature = "dx", feature = "auth"))]
pub use flash::{Flash, FlashError, FlashLevel, FlashMessage};
// A12 binding descriptors (`JobBinding`, `CommandBinding`, `ScheduleBinding`,
// `ScheduleCadence`) are pure compile-time metadata defined in `graph`
// (behind `dx` only), exactly like `ListenerBinding`. They are re-exported
// UNGATED (under `dx`) so the UAG / `arcature-build` can serialize them
// WITHOUT pulling the `jobs` runtime subsystem — which drags in
// `db`/`arcature-jobs`/`chrono`/`tokio-util` (AGENTS.md §2: small apps remain
// small). The runtime types (`Command`, `Scheduler`, …) stay behind `jobs`
// in their own submodules. Previously these four were mis-gated behind
// `jobs`; the gate was a bug, not an architectural boundary.
pub use graph::{
    CommandBinding, JobBinding, ListenerBinding, ModuleDescriptor, ModuleNode, ScheduleBinding,
    ScheduleCadence,
};
#[cfg(all(feature = "dx", feature = "jobs", feature = "serde"))]
pub use job::Job;
#[cfg(all(feature = "dx", feature = "auth"))]
pub use policy::{AuthzError, Policy};
pub use provider::Provider;
#[cfg(feature = "dx")]
pub use request_cache::RequestCacheDescriptor;
pub use resolve::Resolve;
pub use response::Empty;
#[cfg(feature = "serde")]
pub use response::{Json, Page, page};
pub use route_metadata::{RouteDescriptor, RouteMethod};
#[cfg(all(feature = "dx", feature = "db"))]
pub use route_model::RouteModel;
#[cfg(all(feature = "dx", feature = "jobs"))]
pub use scheduler::{Scheduler, SchedulerError};
pub use service::{Inject, Service};
#[cfg(all(feature = "dx", feature = "auth"))]
pub use session::{Session, SessionError};
#[cfg(all(feature = "dx", feature = "auth"))]
pub use user_loader::UserLoader;
#[cfg(all(feature = "dx", feature = "api"))]
pub use validated::Validated;

/// A named component of an Arcature application.
///
/// This is the foundation DX trait: it ties a Rust type to a static
/// component name that can be used in application-graph inspection
/// (`arc modules`, `arc services`) without runtime reflection. The
/// `#[derive(DxComponent)]` macro (re-exported as
/// `arcature::DxComponent`) generates an `impl DxComponent` for the
/// annotated type.
///
/// # Example
///
/// ```ignore
/// use arcature::DxComponent;
///
/// #[derive(DxComponent)]
/// #[dx_component(name = "LinkService")]
/// struct LinkService;
///
/// assert_eq!(LinkService::NAME, "LinkService");
/// ```
///
/// The trait is deliberately minimal — it carries only a name. Later
/// A-phases extend the DX layer with richer contracts (route metadata,
/// module graph, service dependencies) as separate types, not by
/// bloating this trait.
pub trait DxComponent {
    /// The static component name used in application-graph inspection.
    const NAME: &'static str;
}