appcore_sdk/lib.rs
1// =============================================================================
2// #######
3// ### ### F: lib.rs
4// ## ## ## ## P: AppCore-Runtime
5// ## ##
6// C: 2026/09/04 00:00:00 by dnettoRaw
7// ## ## ## ## U: 2026/09/04 00:00:00 by dnettoRaw
8// ########### S: 1.0.0-rc.1
9// =============================================================================
10
11//! # `AppCore` SDK
12//!
13//! `appcore-sdk` is the stable, application-facing entry point for `AppCore`.
14//! It deliberately presents contracts and small adapters rather than owning a
15//! host, provider selection, storage engine, scheduler, gateway, or protocol.
16//! Those systems remain independently usable in their owning crates.
17//!
18//! ## Hello World
19//!
20//! ```
21//! use appcore_sdk::prelude::*;
22//!
23//! fn main() -> AppResult<()> {
24//! appcore_sdk::run("hello-world", |app| {
25//! app.log("Hello, world!");
26//! Ok(())
27//! })
28//! }
29//! ```
30//!
31//! This local entry point validates the application identifier and provides a
32//! bounded, structured logging boundary. It intentionally does not start a
33//! network listener or infer deployment policy. A deployed application owns its
34//! process boundary and uses explicit manifests; add specialized crates only
35//! when a capability is needed.
36//!
37//! ## Learning path
38//!
39//! 1. Start with [`run`] and [`prelude`].
40//! 2. Use [`App`] as the validated local application context.
41//! 3. Replace its canonical defaults with explicit [`manifest`] contracts when
42//! installation policy must be supplied externally.
43//! 4. Implement [`Application`] and call [`App::prepare`] to collect commands,
44//! events, states, decisions, handlers, queries and scheduled tasks.
45//! 5. Enable `storage`, `api`, `sync`, `ai` or `filemaker` only when
46//! that capability is genuinely required.
47//! 6. Enable `deployment` for provider-resolved bindings and `scheduler` for
48//! bounded task definitions.
49//! 7. Select an explicit deployment process for distributed composition,
50//! clustering and lifecycle. The `SDK` never makes a low-level crate depend
51//! on it.
52//!
53//! ## Escape hatches
54//!
55//! The namespaced reexports are intentionally selective. Import an owning
56//! `appcore-*` crate directly for an advanced API not represented here. That is
57//! an explicit choice, not a limitation of the `SDK`.
58
59#![deny(missing_docs)]
60
61pub mod application;
62pub mod capability;
63#[cfg(feature = "deployment")]
64pub mod context;
65pub mod diagnostics;
66pub mod environment;
67pub mod error;
68pub mod prelude;
69mod prepared;
70mod simple_app;
71
72/// Canonical manifest contracts accepted by every compatible `AppCore` Runtime.
73pub mod manifest {
74 pub use appcore_contracts::{
75 ApplicationId, ApplicationManifestV1, DeploymentManifestV1, InstallationId, NetworkConfig,
76 ProviderConfig, ProviderId, RuntimeHealthStatus, RuntimeMode, RuntimeRequirements,
77 ServiceId,
78 };
79}
80
81/// Bounded structured logging configuration used by [`App::logging`].
82pub mod logging {
83 pub use appcore_log::{
84 FileArchiveConfig, FileSinkConfig, LogConfigError, LogOutputMode, LogPolicy, LoggerConfig,
85 PathAliases, Sensitivity, Severity, Verbosity, LOG_SIZE_16_MIB, LOG_SIZE_1_MIB,
86 LOG_SIZE_2_MIB, LOG_SIZE_32_MIB, LOG_SIZE_4_MIB, LOG_SIZE_64_MIB, LOG_SIZE_8_MIB,
87 };
88}
89
90/// Opt-in HTTP query contracts; applications with only commands and events do
91/// not need this capability. Enable with the `api` feature.
92#[cfg(feature = "api")]
93pub mod api {
94 pub use appcore_api::{ApiRequest, ApiResponse, ApiRouter, QueryEndpoint, QueryName};
95}
96
97/// Opt-in provider-backed deployment binding contracts. Enable with the
98/// `deployment` feature.
99#[cfg(feature = "deployment")]
100pub mod deployment {
101 pub use crate::{DeploymentContext, DeploymentEnvironmentValue, ResolvedVolumeMount};
102}
103
104/// Opt-in scheduled-work contracts; background work is absent from the core
105/// facade. Enable with the `scheduler` feature.
106#[cfg(feature = "scheduler")]
107pub mod scheduler {
108 pub use crate::application::{
109 ApplicationTaskRegistry, RegisteredApplicationTask, RetryPolicy, ScheduledTask,
110 TaskContext, TaskResult, TaskSchedule,
111 };
112}
113
114/// Opt-in storage contracts; applications that only register behavior do not
115/// pay for a storage implementation. Enable with the `storage` feature.
116#[cfg(feature = "storage")]
117pub mod storage {
118 pub use appcore_storage::{FileStorageProvider, StorageProvider, StorageStatus};
119}
120
121/// Opt-in replication contracts exposing common subsystem types. Enable with
122/// the `sync` feature.
123#[cfg(feature = "sync")]
124pub mod sync {
125 pub use appcore_sync::availability::{
126 operation_binding_hash, operation_identity_hash, AvailabilityErrorV1,
127 AvailabilityObservationV1, AvailabilityReadinessV1, AvailabilityRetryV1,
128 AvailabilityRoleV1, DurableOperationReceiptV1, NegotiatedPeerOperationV1,
129 PeerOperationCallErrorV1, PeerOperationOutcomeV1,
130 };
131 pub use appcore_sync::{
132 decide_object_revision_v1, validate_checkpoint_head_v1, InMemorySyncOutbox,
133 ObjectRevisionV1, ReplicationLog, RevisionChainV1, RevisionDecisionV1, SyncError,
134 SyncMessage, SyncOutbox, SyncResult,
135 };
136}
137
138/// Opt-in AI contracts; they are never required by the deterministic SDK core.
139/// Enable with the `ai` feature.
140#[cfg(feature = "ai")]
141pub mod ai {
142 pub use appcore_ai::{
143 AiExecutionMode, AiLimits, AiPrivacyMode, AiRequest, AiResponse, AiResult, AiRuntime,
144 AiTask, CancellationToken,
145 };
146}
147
148/// Opt-in deterministic document contracts. Enable with the `filemaker`
149/// feature.
150#[cfg(feature = "filemaker")]
151pub mod filemaker {
152 pub use appcore_filemaker::{
153 export_bytes, Compiler, CompilerBuilder, DataValue, ExportContext, ExportFormat,
154 ExportRequest, FileMakerError, FontAsset, FontManager, LayoutEngine, LayoutOptions,
155 ResourceLimits, Result, TemplateSourceV1,
156 };
157}
158
159pub use application::Application;
160#[cfg(feature = "scheduler")]
161pub use application::{ApplicationTaskRegistry, RegisteredApplicationTask};
162pub use capability::{
163 command_name, declare_command_capability, CapabilityClass, CapabilityCoverage,
164 CapabilityDeclaration, CapabilityMode, CapabilityOutcome, CapabilityOutcomeError,
165 CapabilityRegistry, CapabilityVisibility, MAX_CAPABILITY_ENTRIES,
166};
167#[cfg(feature = "deployment")]
168pub use context::{DeploymentContext, DeploymentEnvironmentValue, ResolvedVolumeMount};
169pub use diagnostics::{
170 DiagnosticBundleBuilder, DiagnosticBundleV1, DiagnosticComponent, DiagnosticError,
171 DiagnosticPrivacy, DiagnosticStatus, DIAGNOSTIC_BUNDLE_SCHEMA_V1, MAX_DIAGNOSTIC_ERRORS,
172 MAX_DIAGNOSTIC_STATUS_BYTES, MAX_DIAGNOSTIC_TEXT_BYTES,
173};
174pub use environment::{
175 EnvironmentProfile, EnvironmentStage, EnvironmentTopology, ReleaseKind, RuntimeSurface,
176 MAX_ENVIRONMENT_LABEL_BYTES,
177};
178pub use error::{AppError, AppResult};
179pub use prepared::PreparedApplication;
180pub use simple_app::{run, App};