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::{
126        decide_object_revision_v1, validate_checkpoint_head_v1, InMemorySyncOutbox,
127        ObjectRevisionV1, ReplicationLog, RevisionChainV1, RevisionDecisionV1, SyncError,
128        SyncMessage, SyncOutbox, SyncResult,
129    };
130}
131
132/// Opt-in AI contracts; they are never required by the deterministic SDK core.
133/// Enable with the `ai` feature.
134#[cfg(feature = "ai")]
135pub mod ai {
136    pub use appcore_ai::{
137        AiExecutionMode, AiLimits, AiPrivacyMode, AiRequest, AiResponse, AiResult, AiRuntime,
138        AiTask, CancellationToken,
139    };
140}
141
142/// Opt-in deterministic document contracts. Enable with the `filemaker`
143/// feature.
144#[cfg(feature = "filemaker")]
145pub mod filemaker {
146    pub use appcore_filemaker::{
147        export_bytes, Compiler, CompilerBuilder, DataValue, ExportContext, ExportFormat,
148        ExportRequest, FileMakerError, FontAsset, FontManager, LayoutEngine, LayoutOptions,
149        ResourceLimits, Result, TemplateSourceV1,
150    };
151}
152
153pub use application::Application;
154#[cfg(feature = "scheduler")]
155pub use application::{ApplicationTaskRegistry, RegisteredApplicationTask};
156pub use capability::{
157    command_name, declare_command_capability, CapabilityClass, CapabilityCoverage,
158    CapabilityDeclaration, CapabilityMode, CapabilityOutcome, CapabilityOutcomeError,
159    CapabilityRegistry, CapabilityVisibility, MAX_CAPABILITY_ENTRIES,
160};
161#[cfg(feature = "deployment")]
162pub use context::{DeploymentContext, DeploymentEnvironmentValue, ResolvedVolumeMount};
163pub use diagnostics::{
164    DiagnosticBundleBuilder, DiagnosticBundleV1, DiagnosticComponent, DiagnosticError,
165    DiagnosticPrivacy, DiagnosticStatus, DIAGNOSTIC_BUNDLE_SCHEMA_V1, MAX_DIAGNOSTIC_ERRORS,
166    MAX_DIAGNOSTIC_STATUS_BYTES, MAX_DIAGNOSTIC_TEXT_BYTES,
167};
168pub use environment::{
169    EnvironmentProfile, EnvironmentStage, EnvironmentTopology, ReleaseKind, RuntimeSurface,
170    MAX_ENVIRONMENT_LABEL_BYTES,
171};
172pub use error::{AppError, AppResult};
173pub use prepared::PreparedApplication;
174pub use simple_app::{run, App};
appcore_sdk/lib.rs

appcore_sdk/
lib.rs
