boc/SIL/SYSTEM_INTELLIGENCE_LAYER.md

# System Intelligence Layer (SIL)

> Ett lager mellan kodbasen och alla AI-agenter.
> Inte en sökmotor. Inte en chatbot. En systemkognitiv plattform.

---

## Arkitektur

```
┌─────────────────────────────────────────────────────────────┐
│                    AI-AGENTER (Bernt, etc.)                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              SYSTEM INTELLIGENCE LAYER (SIL)                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  OBSERVER   │  │  REASONER   │  │   PLANNER   │         │
│  │  (Ingest)   │  │  (Query)    │  │  (Action)   │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         └────────────────┼────────────────┘                 │
│                          │                                  │
│                   ┌──────┴──────┐                          │
│                   │  CONFIDENCE │                          │
│                   │   SYSTEM    │                          │
│                   └──────┬──────┘                          │
│                          │                                  │
│                   ┌──────┴──────┐                          │
│                   │ CONTINUOUS  │                          │
│                   │REALITY CHECK│                          │
│                   └─────────────┘                          │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    KUNSKAPSGRAF (Graph DB)                   │
│  Noder: Services, APIs, Tables, Deployments, Tests, etc.    │
│  Kanter: Med confidence, källa, verifieringsdatum            │
└─────────────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                      VERKLIGHET (Reality)                    │
│  Git · AST · Databases · K8s · Logs · Metrics · Traces      │
└─────────────────────────────────────────────────────────────┘
```

---

## 1. OBSERVER (Ingest)

### Källor

| Källa | Vad som extraheras | Frekvens | Confidence |
|-------|-------------------|----------|------------|
| Git commits | Ändrade filer, nya endpoints, borttagna tabeller | Real-time (webhook) | 0.99 |
| AST (abstrakt syntaxträd) | Faktiska funktionsanrop, imports, beroenden | Vid build | 0.98 |
| Databasscheman | Tabeller, kolumner, constraints, index | Vid migration | 0.97 |
| API-kontrakt | OpenAPI, GraphQL schema, protobuf | Vid deploy | 0.96 |
| Kubernetes-resurser | Deployments, services, configmaps | Real-time (watch) | 0.95 |
| CI/CD pipelines | Testresultat, deployment-status | Real-time | 0.94 |
| Loggar | Felmeddelanden, access patterns | Strömmande | 0.85 |
| Metrics | CPU, minne, latency, errors | Strömmande | 0.90 |
| Traces | Request-flöden, beroenden | Sampling | 0.88 |
| Feature flags | Aktiva/inaktiva features | Vid ändring | 0.92 |
| Testresultat | Pass/fail, coverage | Vid körning | 0.93 |
| Driftstatus | Health checks, alerts | Real-time | 0.91 |

### Ingestion Pipeline

```
Reality → Extract → Transform → Validate → Store → Notify
```

1. **Extract**: Läs rådata från källan
2. **Transform**: Konvertera till graf-noder och kanter
3. **Validate**: Kolla konsistens mot befintlig graf
4. **Store**: Spara med confidence-metadata
5. **Notify**: Meddela agenter om signifikanta ändringar

---

## 2. REASONER (Query)

### Frågetyper

#### Konsekvensanalys (Impact Analysis)
```
Input: "Ändra Wallet Service"
Output:
  - Direkt påverkan: wallets-tabell, transactions-tabell, Stripe API
  - Indirekt påverkan: Payout Service, Mission Flow (zoomer får inte betalt)
  - Tester som måste köras: wallet-transactions, payout-request
  - Risker: Finansiell data, compliance
  - Rollback-strategi: Database migration rollback
```

#### Riskbedömning (Risk Assessment)
```
Input: "Deploya ny KYC-algoritm"
Output:
  - Risk: Zoomer-onboarding kan brytas
  - Sannolikhet: Medium (ny kod)
  - Impact: Högt ( blockerar nya användare)
  - Mitigation: Canary deployment, feature flag
```

#### Arkitekturregelkoll (Architecture Compliance)
```
Input: "Lägg till direkt databasanrop från App"
Output:
  - REGELBROTT: Frontend ska inte prata direkt med databas
  - Förväntat: App → API → Service → DB
  - Förslag: Skapa nytt API-endpoint
```

#### Motstridiga beslut (Conflict Detection)
```
Input: "Använd Redis för sessioner"
Output:
  - KONFLIKT: Arkitekturen säger stateless services
  - Tidigare beslut: "All state i PostgreSQL" (2026-05-15)
  - Förslag: Diskutera med arkitekturgrupp
```

---

## 3. PLANNER (Action)

### Plan-generering

```
Input: "Lägg till Apple Pay"

Plan:
1. Påverkade tjänster:
   - Wallet Service (ny betalningsmetod)
   - Auth Service (ny consent)
   
2. Databasändringar:
   - ALTER TABLE wallets ADD COLUMN apple_pay_token
   - Ny migration: 2026_07_01_add_apple_pay.sql
   
3. API-ändringar:
   - POST /wallet/apple-pay/setup
   - POST /wallet/apple-pay/charge
   
4. Säkerhetsgranskning:
   - PCI DSS compliance check
   - Apple Pay certificate validation
   
5. Tester:
   - Unit: ApplePayServiceTest
   - Integration: WalletApplePayFlowTest
   - E2E: ApplePayCheckoutTest
   
6. Deployment-ordning:
   a. Databas-migration
   b. Wallet Service (ny version)
   c. App (ny UI)
   
7. Rollback-strategi:
   - Feature flag: apple_pay_enabled
   - Database rollback script
   - Circuit breaker på Apple Pay API
```

---

## 4. VERIFIER (Validate)

### Verifieringsfrågor

Efter varje ändring:

```
✅ Mål uppnått?
   - Apple Pay fungerar i testmiljö
   
✅ Graf konsistent?
   - Nya noder: apple_pay_token, ApplePayService
   - Nya kanter: Wallet → ApplePayService → Apple API
   - Ingen konflikt med befintlig arkitektur
   
✅ Nya beroenden?
   - Extern: Apple Pay API (confidence: 0.95)
   - Intern: Wallet Service (confidence: 0.99)
   
✅ Tester täcker?
   - Coverage: 87% (krav: >80%)
   - Integrationstester: 12 st
   - E2E-tester: 3 st
   
✅ Prestanda påverkad?
   - Latency: +15ms (acceptabelt)
   - CPU: ingen förändring
   
✅ Säkerhetsyta ändrad?
   - Ny attack-yta: Apple Pay token storage
   - Mitigation: Kryptering, rotation
```

---

## Confidence System

### Metadata per kant

```json
{
  "from": "Wallet Service",
  "to": "Stripe API",
  "relation": "calls",
  "confidence": {
    "score": 0.99,
    "source": "AST",
    "last_verified": "2026-06-30T14:23:00Z",
    "verification_method": "Static analysis of wallet-service/src/payment/stripe.rs",
    "verified_by": "sil-observer",
    "history": [
      {"date": "2026-06-15", "score": 0.95, "source": "README"},
      {"date": "2026-06-30", "score": 0.99, "source": "AST"}
    ]
  }
}
```

### Confidence-nivåer

| Score | Nivå | Beskrivning |
|-------|------|-------------|
| 0.99-1.00 | Verifierad | AST, runtime traces, automatisk verifiering |
| 0.90-0.98 | Hög | Manuell kodgranskning, tester |
| 0.70-0.89 | Medium | Dokumentation, konfiguration |
| 0.50-0.69 | Låg | README, kommentarer |
| <0.50 | Osäker | Gissning, legacy, outdaterad |

---

## Continuous Reality Check

### Tre modeller som jämförs

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   INTENDED      │     │   ACTUAL        │     │   OBSERVED      │
│   (Architecture)│     │   (Code)        │     │   (Runtime)     │
│                 │     │                 │     │                 │
│ "KYC skapar     │     │ KYC skapar      │     │ 8% av användare │
│  alltid wallet" │     │ inte wallet     │     │ saknar wallet   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                                 ▼
                    ┌─────────────────────┐
                    │     AVVIKELSE       │
                    │  Arkitektur ≠ Kod   │
                    │  Kod ≠ Runtime      │
                    └─────────────────────┘
```

### Exempel på avvikelsedetektion

```
🚨 AVVIKELSE DETEKTERAD

Typ: Arkitektur ≠ Kod
Allvarlighet: Medium
Beskrivning: Arkitekturen säger att KYC skapar wallet, men koden gör det inte.

Påverkan:
  - 8% av nya zoomers saknar wallet (från metrics)
  - Payouts misslyckas för dessa användare
  
Förslag:
  1. Lägg till wallet-skapande i KYC-flödet
  2. Backfill befintliga användare
  3. Uppdatera arkitekturdokumentation

Ägare: backend-team
Deadline: 2026-07-07
```

---

## Implementation

### Faser

#### Experiment-fas (NU — 2-4 veckor)
- [x] Kunskapsgraf (JSON)
- [x] PR-analysator med provenance
- [x] Diagnostiska metriker (recall, precision, FNR, FPR, calibration)
- [x] Gold Set-byggare (ground truth)
- [x] Webhook-server (event-driven)
- [x] Veckovis experimentrapport
- [ ] Samla data (50-100 PR:er)
- [ ] Utvärdera mot kriterier

#### Kriterier för aktivering
| Metrik | Mål |
|--------|-----|
| Recall | > 85% |
| Precision | > 80% |
| False Negative Rate | < 10% |
| Calibration Error | < 10% |

#### Fas 2: Reality (efter aktivering)
- [ ] AST-parser (Rust/TypeScript)
- [ ] Database schema scanner
- [ ] API-kontrakt scanner
- [ ] Continuous reality check

#### Fas 3: Autonomi (senare)
- [ ] Plan-generator
- [ ] Verifierare
- [ ] Agent-integration
- [ ] Dashboard

---

*System Intelligence Layer - Design Document*
*Version: 0.1*
*Författare: Bernt (AI-agent) med vägledning från Erik Svensson*