g8_core/lib.rs
1//! `g8-core` — canonical data model for the G8.
2//!
3//! This crate is the root of the g8 crate DAG. It owns all shared types;
4//! every other workspace crate consumes them. No I/O, no tokio, no rusqlite.
5//!
6//! # Modules
7//! - [`ids`] — typed ID newtypes (nanoid-backed)
8//! - [`model`] — domain structs: ConvergenceSpace, Project, Capability, Intent, Plan, Decision
9//! - [`annotation`] — Annotation, AnnotationKind, SourceLocation, RawAnnotation
10//! - [`plan`] — PlanStatus, PlanDraft, FitReport, Recommendation, and free functions
11//! - [`conflict`] — Conflict, ConflictKind, Severity, Evidence
12//! - [`contract`] — CheckPayload, CheckErrorItem, PairingReason (`g8 check --json`)
13//! - [`substrate`] — SubstrateName, SubstrateBudget
14//! - [`owner`] — Owner
15//! - [`error`] — G8Error top-level enum
16//! - [`time`] — EpochMillis newtype + helpers
17
18pub mod annotation;
19pub mod conflict;
20pub mod contract;
21pub mod error;
22pub mod ids;
23pub mod model;
24pub mod owner;
25pub mod plan;
26pub mod substrate;
27pub mod time;
28
29// ── Flat re-exports of all public types ─────────────────────────────────────
30
31pub use annotation::{Annotation, AnnotationKind, AnnotationValue, RawAnnotation, SourceLocation};
32pub use conflict::{Conflict, ConflictKind, Evidence, Severity};
33pub use contract::{CheckErrorItem, CheckPayload, PairingReason};
34pub use error::G8Error;
35pub use ids::{AnnotationId, CapabilityId, DecisionId, IntentId, PlanId, ProjectId, SpaceId};
36pub use model::{
37 Capability, CapabilityStatus, ConvergenceSpace, Decision, DecisionStatus, Intent, IntentKind,
38 IntentSourceKind, Plan, Project,
39};
40pub use owner::Owner;
41pub use plan::{
42 BottleneckPlan, BudgetStatus, DecisionInput, DriftHint, ExistingMatch, FitReport,
43 IntentOverlap, MatchKind, OverlapKind, ParkedIdeaMatch, PlanDraft, PlanIntentRelation,
44 PlanStatus, Recommendation,
45};
46pub use substrate::SubstrateBudget;
47pub use time::EpochMillis;
48
49// ── Free functions ───────────────────────────────────────────────────────────
50
51/// Returns the current wall-clock time as epoch milliseconds.
52///
53/// # Examples
54///
55/// ```
56/// let ms = g8_core::now_millis();
57/// // It should be a reasonably large number (post-2020 epoch).
58/// assert!(ms.as_i64() > 1_600_000_000_000);
59/// ```
60pub fn now_millis() -> EpochMillis {
61 time::now_millis()
62}
63
64/// Parse a magic-comment annotation string into a [`RawAnnotation`].
65///
66/// Accepts the `@g8.<kind>(key = "value", ...)` form as produced by the
67/// extractor after stripping comment prefixes (`//` or `#`). Whitespace
68/// between tokens is ignored; multi-line forms should be concatenated by the
69/// caller before parsing.
70///
71/// # Examples
72///
73/// ```
74/// use g8_core::parse_annotation_grammar;
75///
76/// // Single-line capability annotation
77/// let raw = parse_annotation_grammar(
78/// r#"@g8.capability(name = "http-fetch", status = "in_flight", substrate = "net")"#
79/// ).unwrap();
80/// assert_eq!(raw.kind_str, "capability");
81/// assert!(raw.fields.contains_key("name"));
82///
83/// // Multi-line form (caller concatenates with spaces after stripping // prefix)
84/// let multi = parse_annotation_grammar(
85/// r#"@g8.capability(name = "claim-validation", consumes = ["Claim", "Source"], produces = ["Event"])"#
86/// ).unwrap();
87/// let produces = multi.fields.get("produces").unwrap();
88/// let json = serde_json::to_string(produces).unwrap();
89/// assert!(json.contains("Event"));
90/// ```
91pub fn parse_annotation_grammar(raw: &str) -> Result<RawAnnotation, G8Error> {
92 annotation::parse_annotation_grammar(raw)
93}
94
95/// Derive a [`Recommendation`] from a [`DecisionInput`] via a fixed lookup table.
96///
97/// The lookup table is deterministic: same input always yields same output.
98/// Order matters — first matching branch wins.
99///
100/// # Examples
101///
102/// ```
103/// use g8_core::{recommend, DecisionInput, Recommendation};
104///
105/// let proceed = recommend(&DecisionInput {
106/// any_over_budget: false,
107/// has_exact_match: false,
108/// near_match_count: 0,
109/// has_parked_match: false,
110/// bottleneck_count: 0,
111/// });
112/// assert_eq!(proceed, Recommendation::Proceed);
113///
114/// let drop = recommend(&DecisionInput {
115/// any_over_budget: false,
116/// has_exact_match: true,
117/// near_match_count: 1,
118/// has_parked_match: false,
119/// bottleneck_count: 0,
120/// });
121/// assert_eq!(drop, Recommendation::Drop);
122/// ```
123pub fn recommend(input: &DecisionInput) -> Recommendation {
124 plan::recommend(input)
125}
126
127/// Validate a [`PlanStatus`] transition, returning an error if the transition
128/// is illegal per the plan lifecycle graph.
129///
130/// Legal transitions:
131/// - `Idea` → `Scoped | Parked`
132/// - `Scoped` → `Dispatched | Parked`
133/// - `Dispatched` → `Blocked | Done | Parked`
134/// - `Blocked` → `Dispatched | Parked`
135/// - `Parked` → `Scoped`
136/// - `Done` — terminal; no outgoing edges
137///
138/// # Examples
139///
140/// ```
141/// use g8_core::{validate_status_transition, PlanStatus};
142///
143/// // Legal transition
144/// assert!(validate_status_transition(PlanStatus::Idea, PlanStatus::Scoped).is_ok());
145///
146/// // Illegal: Done is terminal
147/// assert!(validate_status_transition(PlanStatus::Done, PlanStatus::Idea).is_err());
148/// ```
149pub fn validate_status_transition(from: PlanStatus, to: PlanStatus) -> Result<(), G8Error> {
150 plan::validate_status_transition(from, to)
151}
152
153/// Default WIP cap applied per-substrate when no override is configured.
154pub const DEFAULT_WIP_CAP: u32 = 3;