diff --git a/docs/design/EPIC-001-First-Verified-Decision.md b/docs/design/EPIC-001-First-Verified-Decision.md index a3157ed10..4e761fe4a 100644 --- a/docs/design/EPIC-001-First-Verified-Decision.md +++ b/docs/design/EPIC-001-First-Verified-Decision.md @@ -377,6 +377,19 @@ These are important but don't help reach the first verified workflow. **Architecture Goal:** Every artifact must be traceable backward to its source and forward to its decision. +**Architecture Principle:** +**LandveX Intelligence Lab does not produce AI results. It produces verified Decision Cases through a reproducible and traceable pipeline.** + +## Core Objects + +Three fundamental objects: + +| Object | Purpose | +|--------|---------| +| **Session** | Organizes field work | +| **Artifact** | Organizes everything produced (video, dataset, models, reports, Decision Cases) | +| **Event** | Organizes history and makes the entire chain reproducible | + ## Development Rule **No Story may start with UI. Every Story starts with:** @@ -388,14 +401,205 @@ These are important but don't help reach the first verified workflow. This keeps architecture clean and allows testing each part without frontend. +## Hierarchy + +``` +Field Session + ↓ +Mission + ↓ +Mission Asset + ↓ +Observation + ↓ +Evidence + ↓ +Finding + ↓ +Decision + ↓ +Action + ↓ +Outcome +``` + +**Session is the root.** A pilot day produces many missions. + +## Event Sourcing + +**Never overwrite status. Status is a projection of history.** + +``` +MissionCreated + ↓ +AssetUploaded + ↓ +AssetValidated + ↓ +ObservationCreated + ↓ +EvidenceLinked + ↓ +DecisionApproved +``` + +Always replayable. + +## Artifact Registry + +First-class object. Not just buckets. + +``` +Artifact +├── id +├── type // video | dataset | model | decision_case | evaluation_report | replay +├── version +├── hash +├── created +├── created_by +├── storage_uri +├── parent +└── lineage +``` + +Everything becomes traceable. + +## Decision Case Immutability + +Never modify a Decision Case. + +``` +Decision Case + ↓ +Review + ↓ +Revision + ↓ +Approved Version +``` + +Like Git. + +## Review Task + +``` +Review Task + ↓ +Assigned + ↓ +Reviewed + ↓ +Approved + ↓ +Closed +``` + +Makes future quality assurance much easier. + +## Processing Graph + +Not a list of pipelines. Each step is a node. + +``` +Mission + ↓ +Dataset + ↓ +Annotation + ↓ +Evaluation + ↓ +Decision + ↓ +Learning +``` + +Swap models without changing the rest: +``` +YOLO → Grounding DINO → Custom model +``` + +## Data Quality Domain + +``` +Quality Issue +├── Blur +├── Duplicate +├── Bad GPS +├── Low Resolution +├── Missing Metadata +├── Wrong Timestamp +└── Occlusion +``` + +Then: Quality Report. + +## Decision Case Comparison + +``` +Decision A + ↓ +Decision B +``` + +Show exactly: +- What changed? +- Which evidence? +- Which confidence? +- Which model? +- Which human? + +## Golden Missions & Golden Datasets + +| Level | Description | +|-------|-------------| +| **Golden Mission** | Real mission that never changes | +| **Golden Dataset** | Selected observations from Golden Mission | + +## Domain Event Viewer + +Timeline, not logs: + +``` +09:42 Mission Created +09:43 Video Uploaded +09:44 GPS Extracted +09:45 AI Analysis +09:47 Human Review +09:50 Decision Approved +``` + +Incredibly useful. + +## KPI: Verified Decision Throughput + +Not number of models. Not number of missions. + +``` +Verified Decision Throughput = Verified decisions per day +``` + +This is your factory capacity. + ## Story 1: Mission Import — Implementation Plan ### PR-001: Domain Model ```typescript +// FieldSession +interface FieldSession { + id: string; // session_20260814_000001 + location: Location; + date: Date; + status: SessionStatus; + missions: string[]; // mission IDs + createdAt: Date; +} + // Mission interface Mission { id: string; // mission_20260814_000123 + sessionId: string; status: MissionStatus; location: Location; device: Device; @@ -433,9 +637,23 @@ interface Upload { completedAt?: Date; } +// Artifact +interface Artifact { + id: string; + type: ArtifactType; + version: number; + hash: string; + createdBy: string; + storageUri: string; + parentId?: string; + lineage: string[]; +} + // Enums +type SessionStatus = 'planned' | 'active' | 'completed'; type MissionStatus = 'created' | 'uploading' | 'processing' | 'completed' | 'failed'; type AssetType = 'image' | 'video'; +type ArtifactType = 'video' | 'dataset' | 'model' | 'decision_case' | 'evaluation_report' | 'replay'; type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed'; ``` @@ -453,8 +671,11 @@ type UploadStatus = 'pending' | 'in_progress' | 'completed' | 'failed'; ### PR-003: API ``` -POST /missions +POST /sessions +POST /sessions/{id}/missions POST /missions/{id}/assets +GET /sessions/{id} +GET /sessions GET /missions/{id} GET /missions ``` @@ -462,10 +683,14 @@ GET /missions ### PR-004: Events ``` +SessionCreated + ↓ MissionCreated -↓ + ↓ AssetUploaded -↓ + ↓ +AssetValidated + ↓ RawDatasetReady ``` @@ -501,6 +726,7 @@ This is the first proof. | Entity | ID Format | Example | |--------|-----------|---------| +| Session | `session_YYYYMMDD_NNNNNN` | `session_20260814_000001` | | Mission | `mission_YYYYMMDD_NNNNNN` | `mission_20260814_000123` | | Asset | `asset_NNNNNN` | `asset_000456` | | Observation | `obs_NNNNNN` | `obs_000981` |