ADR-012: Five Engines Platform Architecture + Economic Engine

- LANDVEX_PLATFORM_ARCHITECTURE.md: Five Engines (Reality, Knowledge,
  Decision, Mission, Economic)
- Credit: first-class economic object with types (mission, validation,
  training, priority, emergency)
- IntelligenceLedger: tracks value creation separate from financial accounting
- KnowledgeGap: missing information that drives missions
- Hotspot: composite score for mission generation
- Contradiction: conflicting information as opportunity

Key principle: Every component answers 'What value is created here?
Who pays for it?'

Next: PR-005A — Minimal Mission Import UI for MVP-0

docs/design/LANDVEX_PLATFORM_ARCHITECTURE.md

@@ -0,0 +1,184 @@
+# LandveX Platform Architecture
+
+## Five Engines
+
+LandveX is not an image analysis platform. It is an **economic control system for control intelligence**.
+
+Five engines work together:
+
+```
+Reality Engine
+  ↓
+Knowledge Engine
+  ↓
+Decision Engine
+  ↓
+Mission Engine
+  ↓
+Economic Engine
+```
+
+User experiences sit on top:
+- **quiXzoom** — data collection (Zoomers)
+- **LandveX Dashboard** — decision makers
+- **Intelligence Lab** — development and validation
+
+---
+
+## 1. Reality Engine
+
+**Purpose:** Capture reality from the field.
+
+**Flow:**
+```
+Phone → Video/Images → Upload → Immutable Archive
+```
+
+**Key objects:**
+- `ArchiveArtifact` — original file, never changed
+- `FieldSession` — organizes field work
+- `Mission` — single data collection task
+
+**Value question:** What reality was captured?
+
+---
+
+## 2. Knowledge Engine
+
+**Purpose:** Convert raw data to structured knowledge.
+
+**Flow:**
+```
+Archive Artifact → Knowledge Extraction → Knowledge Graph
+```
+
+**Key objects:**
+- `KnowledgeArtifact` — extracted knowledge (observations, segmentations, embeddings)
+- `Observation` — what was seen
+- `Evidence` — supporting data
+- `Finding` — interpreted result
+
+**Value question:** What does it mean in our domain?
+
+---
+
+## 3. Decision Engine
+
+**Purpose:** Produce verified decisions from knowledge.
+
+**Flow:**
+```
+Finding → Decision → Review → Approved Decision Case
+```
+
+**Key objects:**
+- `DecisionCase` — complete decision chain
+- `Review` — human validation
+- `Decision` — recommended action
+
+**Value question:** What should we do?
+
+---
+
+## 4. Mission Engine
+
+**Purpose:** Generate and manage data collection missions.
+
+**Flow:**
+```
+Knowledge Gap → Coverage Analysis → Mission Proposal → Budget Check → Mission Created
+```
+
+**Key objects:**
+- `KnowledgeGap` — missing information
+- `Hotspot` — high-value area
+- `Contradiction` — conflicting information
+- `Mission` — data collection task
+
+**Value question:** Where should we collect data?
+
+---
+
+## 5. Economic Engine
+
+**Purpose:** Manage budgets, credits, and ROI.
+
+**Flow:**
+```
+Budget → Credit Allocation → Mission Funding → Verified Delivery → Settlement → ROI
+```
+
+**Key objects:**
+- `Credit` — first-class object (Mission, Validation, Training, Priority, Emergency)
+- `IntelligenceLedger` — tracks value creation
+- `Settlement` — payment to Zoomers
+
+**Value question:** What did this decision cost?
+
+---
+
+## Cross-Cutting Objects
+
+### Contradiction Engine
+```
+Source A vs Source B → Confidence → Potential Value → Suggested Mission
+```
+
+Example:
+- Municipality register: "Road is newly paved"
+- Our observations: "Severe cracking"
+- System: "Verify this contradiction"
+
+### Hotspot Engine
+```
+Observation Density + Contradictions + Customer Requests + Risk Trend + Business Value
+  ↓
+Hotspot Score → Mission Generator
+```
+
+### Knowledge Gap
+```
+Area + Coverage + Confidence + Priority + Estimated Value + Budget
+  ↓
+Recommended Mission
+```
+
+---
+
+## Intelligence Ledger
+
+Separate from financial accounting:
+
+| Field | Description |
+|-------|-------------|
+| Mission | Which mission |
+| Budget | Credits allocated |
+| Credits Reserved | Committed |
+| Credits Consumed | Spent |
+| Knowledge Produced | Observations created |
+| Decision Produced | Verified decisions |
+| Business Impact | Measured value |
+| ROI | Return on investment |
+
+**Questions answered:**
+- How many kronor did this verified Decision Case cost?
+- Which municipality gives highest knowledge return per invested krona?
+
+---
+
+## Architecture Principles
+
+1. **Every component answers:** What value is created here? Who pays for it?
+2. **Ontology before model** — taxonomy answers "what does it mean?"
+3. **AI models trained on curated datasets**, not whole archive
+4. **Knowledge gaps drive missions**, not just customer orders
+5. **Contradictions are opportunities**, not errors
+6. **Economic engine as important as AI models**
+
+---
+
+## Related Documents
+
+- ADR-011: Four-Layer Data Architecture
+- DECISION_MODEL_v1.0.md
+- EPIC-001-First-Verified-Decision.md

docs/design/adr/ADR-012-Economic-Engine.md

@@ -0,0 +1,41 @@
+# ADR-012: Economic Engine
+
+## Status
+Accepted
+
+## Context
+LandveX is not just an image analysis platform. It is an economic control system for control intelligence. Every component must answer: What value is created here? Who pays for it?
+
+## Decision
+Model Credits as first-class objects with types:
+
+- **Mission Credits** — fund data collection
+- **Validation Credits** — pay for human review
+- **Training Credits** — fund AI model training
+- **Priority Credits** — expedite processing
+- **Emergency Credits** — handle urgent cases
+
+## Intelligence Ledger
+
+Separate from financial accounting:
+
+| Field | Description |
+|-------|-------------|
+| Mission | Which mission |
+| Budget | Credits allocated |
+| Credits Reserved | Committed |
+| Credits Consumed | Spent |
+| Knowledge Produced | Observations created |
+| Decision Produced | Verified decisions |
+| Business Impact | Measured value |
+| ROI | Return on investment |
+
+## Key Questions
+
+- How many kronor did this verified Decision Case cost?
+- Which municipality gives highest knowledge return per invested krona?
+
+## Related
+
+- ADR-011: Four-Layer Data Architecture
+- LANDVEX_PLATFORM_ARCHITECTURE.md

packages/domain/src/economic/credit.ts

@@ -0,0 +1,57 @@
+/**
+ * Credit — First-class economic object
+ *
+ * ADR-012: Economic Engine
+ * Credits are not just balances. They are typed, budgeted, tracked.
+ */
+
+export type CreditType = 'mission' | 'validation' | 'training' | 'priority' | 'emergency';
+
+export interface Credit {
+  readonly id: string;
+  readonly type: CreditType;
+  readonly amount: number; // In smallest unit (öre/cents)
+  readonly currency: 'SEK' | 'EUR' | 'USD';
+  readonly budgetId: string;
+  readonly missionId?: string;
+  readonly status: 'reserved' | 'consumed' | 'released';
+  readonly createdAt: Date;
+  readonly expiresAt?: Date;
+}
+
+export interface CreditBudget {
+  readonly id: string;
+  readonly name: string;
+  readonly totalAmount: number;
+  readonly consumedAmount: number;
+  readonly reservedAmount: number;
+  readonly creditTypes: CreditType[];
+  readonly validFrom: Date;
+  readonly validTo: Date;
+}
+
+export class CreditFactory {
+  static create(params: {
+    id: string;
+    type: CreditType;
+    amount: number;
+    currency: 'SEK' | 'EUR' | 'USD';
+    budgetId: string;
+    missionId?: string;
+    expiresAt?: Date;
+  }): Credit {
+    return {
+      ...params,
+      status: 'reserved',
+      createdAt: new Date(),
+    };
+  }
+
+  static consume(credit: Credit): Credit {
+    return { ...credit, status: 'consumed' };
+  }
+
+  static release(credit: Credit): Credit {
+    return { ...credit, status: 'released' };
+  }
+}

packages/domain/src/economic/intelligence-ledger.ts

@@ -0,0 +1,53 @@
+/**
+ * Intelligence Ledger — Track value creation
+ *
+ * ADR-012: Economic Engine
+ * Separate from financial accounting.
+ * Tracks: knowledge produced, decisions made, business impact, ROI.
+ */
+
+export interface IntelligenceLedgerEntry {
+  readonly id: string;
+  readonly missionId: string;
+  readonly budgetId: string;
+  readonly creditsAllocated: number;
+  readonly creditsConsumed: number;
+  readonly observationsProduced: number;
+  readonly decisionsProduced: number;
+  readonly businessImpact?: string;
+  readonly roi?: number; // Percentage
+  readonly createdAt: Date;
+}
+
+export interface IntelligenceLedger {
+  readonly entries: IntelligenceLedgerEntry[];
+
+  // Queries
+  totalKnowledgeProduced(): number;
+  totalDecisionsProduced(): number;
+  averageRoi(): number;
+  costPerDecision(): number;
+}
+
+export class IntelligenceLedgerFactory {
+  static createEntry(params: {
+    id: string;
+    missionId: string;
+    budgetId: string;
+    creditsAllocated: number;
+    creditsConsumed: number;
+    observationsProduced: number;
+    decisionsProduced: number;
+    businessImpact?: string;
+  }): IntelligenceLedgerEntry {
+    const roi = params.creditsConsumed > 0
+      ? ((params.observationsProduced + params.decisionsProduced * 10) / params.creditsConsumed) * 100
+      : 0;
+
+    return {
+      ...params,
+      roi,
+      createdAt: new Date(),
+    };
+  }
+}

packages/domain/src/index.ts

@@ -65,6 +65,27 @@ export {
   DataLifecycleStep,
   DataLifecycleRules,
 } from './artifacts/data-lifecycle';
+
+// Economic Engine
+export {
+  Credit,
+  CreditType,
+  CreditBudget,
+  CreditFactory,
+} from './economic/credit';
+
+export {
+  IntelligenceLedger,
+  IntelligenceLedgerEntry,
+  IntelligenceLedgerFactory,
+} from './economic/intelligence-ledger';
+
+// Mission Engine
+export {
+  KnowledgeGap,
+  Hotspot,
+  Contradiction,
+} from './mission/knowledge-gap';
 export * from './common/enums';
 export * from './common/errors';
 

packages/domain/src/mission/knowledge-gap.ts

@@ -0,0 +1,54 @@
+/**
+ * Knowledge Gap — Missing information that drives missions
+ *
+ * ADR-012: Mission Engine
+ * Knowledge gaps drive new missions, not just customer orders.
+ */
+
+import { GeoLocation } from '../common/value-objects';
+
+export interface KnowledgeGap {
+  readonly id: string;
+  readonly areaId: string;
+  readonly location: GeoLocation;
+  readonly coverage: number; // 0.0 to 1.0
+  readonly confidence: number; // 0.0 to 1.0
+  readonly priority: 'low' | 'medium' | 'high' | 'critical';
+  readonly estimatedValue: number; // In credits
+  readonly budgetId?: string;
+  readonly recommendedMissionType: 'inspection' | 'verification' | 'survey';
+  readonly createdAt: Date;
+}
+
+export interface Hotspot {
+  readonly id: string;
+  readonly areaId: string;
+  readonly location: GeoLocation;
+  readonly score: number; // Composite score
+  readonly factors: {
+    readonly observationDensity: number;
+    readonly contradictions: number;
+    readonly customerRequests: number;
+    readonly riskTrend: number;
+    readonly businessValue: number;
+  };
+  readonly recommendedMissions: string[]; // KnowledgeGap IDs
+}
+
+export interface Contradiction {
+  readonly id: string;
+  readonly sourceA: {
+    readonly type: 'observation' | 'register' | 'prediction';
+    readonly id: string;
+    readonly value: string;
+  };
+  readonly sourceB: {
+    readonly type: 'observation' | 'register' | 'prediction';
+    readonly id: string;
+    readonly value: string;
+  };
+  readonly confidence: number;
+  readonly potentialValue: number;
+  readonly suggestedMissionId?: string;
+  readonly createdAt: Date;
+}