keystate_core/lib.rs
1//! # keystate-core
2//!
3//! Canonical domain model, extraction ports, completeness verification, and
4//! idempotent output for **Keystate** — a read-only tool that pulls the
5//! complete, verified configuration state of an IAM system out of its
6//! database as a single backend-agnostic JSON document.
7//!
8//! Core is deliberately **backend-agnostic** and carries no runtime or
9//! database dependency. Adapters (own repos) implement the [`Extractor`],
10//! [`CompletenessVerifier`] and [`OutputSink`] ports against one backend's
11//! schema. The canonical structs are a thin set of *common* fields plus an
12//! open `native` escape hatch, per the architecture document:
13//!
14//! ```text
15//! {
16//! "id": "a1b2c3d4",
17//! "name": "my-client",
18//! "enabled": true,
19//! "native": { /* backend-faithful representation, adapter-owned */ }
20//! }
21//! ```
22//!
23//! The three guarantees this crate provides are:
24//!
25//! 1. **Completeness** — a [`FieldManifest`] describing every field a backend
26//! version must carry, checked by the [`ManifestVerifier`] into a
27//! [`VerificationReport`] that is part of the output, not a side log.
28//! 2. **Idempotency** — [`canonical_bytes`] produces byte-stable output and
29//! [`content_hash`] fingerprints the *config* portion only, so a git diff
30//! on the output reflects real configuration change, never extraction
31//! noise or volatile churn.
32//! 3. **Testability** — the [`testing`] module is a shared contract suite
33//! every adapter runs as part of CI.
34//!
35//! See `ARCHITECTURE.md` in this repository for the full design.
36//!
37//! # Module map
38//!
39//! - [`model`] — canonical entities and the extraction envelope.
40//! - [`port`] — the traits adapters implement.
41//! - [`verify`] — manifests, reports, the verification engine, path resolution.
42//! - [`canonical`] — deterministic serialization and content hashing.
43//! - [`error`], [`version`] — cross-cutting types.
44
45#![warn(missing_docs)]
46
47pub mod canonical;
48pub mod error;
49pub mod model;
50pub mod port;
51pub mod testing;
52pub mod verify;
53pub mod version;
54
55pub use canonical::{canonical_bytes, config_bytes, content_hash, roundtrip};
56pub use error::{Error, Result};
57pub use model::*;
58pub use port::{CompletenessVerifier, Extractor, OutputSink};
59pub use verify::{
60 EntityExpectation, EntityPresence, FieldExpectation, FieldManifest, IssueKind,
61 ManifestVerifier, Severity, VerificationIssue, VerificationReport, resolve_path,
62};
63pub use version::Version;