g8_core/model.rs
1//! Core domain structs: ConvergenceSpace, Project, Capability, Intent, Decision, Plan.
2//!
3//! These are the persisted entities. Annotation is the *transient* extractor
4//! output (see [`crate::annotation`]) that the store converts into these rows.
5
6use std::path::PathBuf;
7
8use chrono::NaiveDate;
9use serde::{Deserialize, Serialize};
10
11use crate::{
12 annotation::SourceLocation,
13 ids::{CapabilityId, DecisionId, IntentId, PlanId, ProjectId, SpaceId},
14 owner::Owner,
15 plan::PlanStatus,
16 time::EpochMillis,
17};
18
19/// A ConvergenceSpace groups one or more projects for federated queries.
20///
21/// # Examples
22///
23/// ```
24/// use g8_core::{ConvergenceSpace, SpaceId, EpochMillis};
25/// use std::path::PathBuf;
26///
27/// let space = ConvergenceSpace {
28/// id: SpaceId::derive(&["docs", "space"]),
29/// name: "platform".into(),
30/// root_path: PathBuf::from("/home/user/platform"),
31/// created_at: EpochMillis::from_i64(1_700_000_000_000),
32/// updated_at: EpochMillis::from_i64(1_700_000_000_000),
33/// members: vec![],
34/// meta: None,
35/// };
36/// assert_eq!(space.name, "platform");
37/// ```
38#[derive(Debug, Clone, Serialize, Deserialize)]
39pub struct ConvergenceSpace {
40 pub id: SpaceId,
41 pub name: String,
42 /// Absolute, canonicalized path to the space root directory.
43 pub root_path: PathBuf,
44 pub created_at: EpochMillis,
45 pub updated_at: EpochMillis,
46 /// ProjectIds that are members of this space; populated by the store loader.
47 pub members: Vec<ProjectId>,
48 /// Arbitrary extensibility bag — serde_json::Value for v0.1 flexibility.
49 pub meta: Option<serde_json::Value>,
50}
51
52/// A single source-controlled directory tree within a space.
53///
54/// # Examples
55///
56/// ```
57/// use g8_core::{Project, ProjectId, SpaceId, EpochMillis};
58/// use std::path::PathBuf;
59///
60/// let proj = Project {
61/// id: ProjectId::derive(&["docs", "project"]),
62/// space_id: SpaceId::derive(&["docs", "space"]),
63/// name: "checkout-api".into(),
64/// description: Some("News ranking service".into()),
65/// root_path: PathBuf::from("/home/user/checkout-api"),
66/// language: Some("rust".into()),
67/// created_at: EpochMillis::from_i64(1_700_000_000_000),
68/// updated_at: EpochMillis::from_i64(1_700_000_000_000),
69/// meta: None,
70/// };
71/// assert_eq!(proj.name, "checkout-api");
72/// ```
73#[derive(Debug, Clone, Serialize, Deserialize)]
74pub struct Project {
75 pub id: ProjectId,
76 pub space_id: SpaceId,
77 /// Human-readable label; not globally unique (unique within a space).
78 pub name: String,
79 pub description: Option<String>,
80 /// Absolute, canonicalized path to the project root.
81 pub root_path: PathBuf,
82 /// Detected primary language: `"rust"` | `"ts"` | `"py"` | `"go"` |
83 /// `"mixed"` | or an arbitrary unknown value.
84 pub language: Option<String>,
85 pub created_at: EpochMillis,
86 pub updated_at: EpochMillis,
87 /// Arbitrary extensibility bag — serde_json::Value for v0.1 flexibility.
88 pub meta: Option<serde_json::Value>,
89}
90
91/// A typed unit of behavior declared by a `// @g8.capability(...)` annotation.
92///
93/// Capabilities are project-scoped; the same kebab-case name in two projects
94/// is two distinct capabilities unless an alias resolves them.
95#[derive(Debug, Clone, Serialize, Deserialize)]
96pub struct Capability {
97 pub id: CapabilityId,
98 pub project_id: ProjectId,
99 /// Kebab-case name; project-scoped (per SPEC Decision 3).
100 pub name: String,
101 pub description: Option<String>,
102 /// Substrate this capability belongs to (string label, not a foreign key).
103 pub substrate: Option<String>,
104 /// Free-form substrate-typed identifiers of things this capability consumes.
105 pub consumes: Vec<String>,
106 /// Free-form substrate-typed identifiers of things this capability produces.
107 pub produces: Vec<String>,
108 pub status: CapabilityStatus,
109 /// `true` when the annotation carries `stub = true`.
110 pub stub: bool,
111 /// ISO date from which the stub exemption was granted (`since` field).
112 pub stub_since: Option<NaiveDate>,
113 pub owner: Option<Owner>,
114 /// Where in source the annotation was found.
115 pub source: SourceLocation,
116 /// The raw annotation string (for debugging / round-trip).
117 pub annotation_raw: String,
118 /// Set when extractor flagged `dev_only=true`, `cfg_attr`, or `tests/` dir.
119 pub conditional: bool,
120 pub created_at: EpochMillis,
121 pub updated_at: EpochMillis,
122 /// Arbitrary extensibility bag — serde_json::Value for v0.1 flexibility.
123 pub meta: Option<serde_json::Value>,
124}
125
126/// Six-state lifecycle for a capability (SPEC Decision 2).
127///
128/// # Examples
129///
130/// ```
131/// use g8_core::CapabilityStatus;
132///
133/// let s = CapabilityStatus::InFlight;
134/// assert!(matches!(s, CapabilityStatus::InFlight));
135/// let json = serde_json::to_string(&s).unwrap();
136/// assert_eq!(json, r#""in_flight""#);
137/// ```
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
139#[serde(rename_all = "snake_case")]
140pub enum CapabilityStatus {
141 Proposed,
142 InFlight,
143 Landed,
144 Stale,
145 Superseded,
146 Parked,
147}
148
149/// A directional statement about what a directory or file is *for*.
150///
151/// Parsed from AGENTS.md, CLAUDE.md, or `*.g8.md` sidecar files. Lives at
152/// directory level; Capability lives at symbol level.
153#[derive(Debug, Clone, Serialize, Deserialize)]
154pub struct Intent {
155 pub id: IntentId,
156 pub space_id: SpaceId,
157 /// `None` when the intent attaches to the space root (not a specific project).
158 pub project_id: Option<ProjectId>,
159 pub kind: IntentKind,
160 /// Heading text from the Markdown section.
161 pub heading: String,
162 /// Body text of the section.
163 pub description: String,
164 /// Directory path this intent applies to.
165 pub scope_path: PathBuf,
166 /// Directory depth from space root; higher = more specific = higher precedence.
167 pub scope_depth: u32,
168 pub substrate: Option<String>,
169 pub owner: Option<Owner>,
170 pub source: SourceLocation,
171 pub source_kind: IntentSourceKind,
172 pub created_at: EpochMillis,
173 pub updated_at: EpochMillis,
174 /// Arbitrary extensibility bag — serde_json::Value for v0.1 flexibility.
175 pub meta: Option<serde_json::Value>,
176}
177
178/// Classifies an intent by the Markdown section heading it was parsed from.
179///
180/// # Examples
181///
182/// ```
183/// use g8_core::IntentKind;
184///
185/// let k = IntentKind::Boundary;
186/// assert!(matches!(k, IntentKind::Boundary));
187/// let json = serde_json::to_string(&k).unwrap();
188/// assert_eq!(json, r#""boundary""#);
189/// ```
190#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
191#[serde(rename_all = "snake_case")]
192pub enum IntentKind {
193 /// `# Architecture`, `# Design`, `# Overview`
194 ArchitecturalScope,
195 /// `# Boundaries`, `# Never do`, `# Constraints`
196 Boundary,
197 /// `# Commands`, `# Build`, `# Test`, `# Testing` — deprioritized in planner
198 Operational,
199 /// `# Stack`, `# Dependencies`
200 TechStack,
201 /// `# Intent` — g8-native explicit section
202 ExplicitIntent,
203 /// Any heading not matching a known pattern
204 Unclassified,
205}
206
207/// Which file type was the source of an intent annotation.
208///
209/// # Examples
210///
211/// ```
212/// use g8_core::IntentSourceKind;
213///
214/// let k = IntentSourceKind::AgentsMd;
215/// assert!(matches!(k, IntentSourceKind::AgentsMd));
216/// let json = serde_json::to_string(&k).unwrap();
217/// assert_eq!(json, r#""agents_md""#);
218/// ```
219#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
220#[serde(rename_all = "snake_case")]
221pub enum IntentSourceKind {
222 AgentsMd,
223 ClaudeMd,
224 G8Sidecar,
225 InlineComment,
226 Manual,
227}
228
229/// An architectural decision record stored in the space.
230///
231/// Decisions are space-scoped (per the data-model table in ARCHITECTURE.md §4).
232#[derive(Debug, Clone, Serialize, Deserialize)]
233pub struct Decision {
234 pub id: DecisionId,
235 pub space_id: SpaceId,
236 pub title: String,
237 pub status: DecisionStatus,
238 /// The situation or problem statement (context for the decision).
239 pub context: Option<String>,
240 /// Body text — the decision, rationale, and consequences.
241 pub body: String,
242 /// Source file that produced this decision record (e.g. an AGENTS.md).
243 pub source_file: Option<PathBuf>,
244 pub created_at: EpochMillis,
245 pub updated_at: EpochMillis,
246 /// Arbitrary extensibility bag — serde_json::Value for v0.1 flexibility.
247 pub meta: Option<serde_json::Value>,
248}
249
250/// Lifecycle state for a decision record.
251///
252/// # Examples
253///
254/// ```
255/// use g8_core::DecisionStatus;
256///
257/// let s = DecisionStatus::Accepted;
258/// assert!(matches!(s, DecisionStatus::Accepted));
259/// let json = serde_json::to_string(&s).unwrap();
260/// assert_eq!(json, r#""accepted""#);
261/// ```
262#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
263#[serde(rename_all = "snake_case")]
264pub enum DecisionStatus {
265 Proposed,
266 Accepted,
267 Rejected,
268 Superseded,
269 RuledOut,
270}
271
272/// A unit of work tracked through the plan lifecycle.
273///
274/// # Examples
275///
276/// ```
277/// use g8_core::{
278/// model::Plan, PlanId, SpaceId, EpochMillis,
279/// plan::PlanStatus,
280/// };
281///
282/// let plan = Plan {
283/// id: PlanId::derive(&["docs", "plan"]),
284/// space_id: SpaceId::derive(&["docs", "space"]),
285/// project_id: None,
286/// title: "streaming-export".into(),
287/// description: Some("Add streaming export to the export pipeline".into()),
288/// status: PlanStatus::Idea,
289/// substrate: Some("export-pipeline".into()),
290/// touched_capabilities: vec![],
291/// derived_from_intents: vec![],
292/// governed_by_decisions: vec![],
293/// wip_weight: 1,
294/// parked_reason: None,
295/// blocked_reason: None,
296/// dispatched_at: None,
297/// completed_at: None,
298/// created_at: EpochMillis::from_i64(1_700_000_000_000),
299/// updated_at: EpochMillis::from_i64(1_700_000_000_000),
300/// // Plan.meta: serde_json::Value chosen for v0.1 flexibility;
301/// // typed PlanMeta with extra: HashMap deferred to v0.2
302/// meta: None,
303/// };
304/// assert_eq!(plan.title, "streaming-export");
305/// assert_eq!(plan.status, PlanStatus::Idea);
306/// ```
307#[derive(Debug, Clone, Serialize, Deserialize)]
308pub struct Plan {
309 pub id: PlanId,
310 pub space_id: SpaceId,
311 /// `None` for space-level plans not tied to a single project.
312 pub project_id: Option<ProjectId>,
313 pub title: String,
314 pub description: Option<String>,
315 pub status: PlanStatus,
316 pub substrate: Option<String>,
317 pub touched_capabilities: Vec<CapabilityId>,
318 pub derived_from_intents: Vec<IntentId>,
319 pub governed_by_decisions: Vec<DecisionId>,
320 /// WIP weight: how many WIP-cap slots this plan consumes (almost always 1).
321 pub wip_weight: u32,
322 pub parked_reason: Option<String>,
323 pub blocked_reason: Option<String>,
324 pub dispatched_at: Option<EpochMillis>,
325 pub completed_at: Option<EpochMillis>,
326 pub created_at: EpochMillis,
327 pub updated_at: EpochMillis,
328 /// Plan.meta: serde_json::Value chosen for v0.1 flexibility;
329 /// typed PlanMeta with extra: HashMap deferred to v0.2
330 pub meta: Option<serde_json::Value>,
331}