This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Loki/docs/architecture.md
2026-06-09 17:04:38 +01:00

56 lines
2.2 KiB
Markdown

# Loki Architecture
## Objective
Expose local Chrome tab state as provider-owned, typed service state for
CultMesh/Eve consumers while keeping Chrome installation easy for the operator.
## Current Mechanism
The Chrome extension observes tab metadata with explicit Chrome permissions and
posts reports to Loki's localhost ingest endpoint. On command, it also uses
`chrome.debugger` to attach to debuggable tabs, probe Chrome Debugger Protocol
domains, and detach. Chrome can also expose DevTools metadata on
`127.0.0.1:{port}` when started with `--remote-debugging-port`. Loki normalizes
these sources into one snapshot and writes typed witness documents from that
state.
```mermaid
flowchart LR
Extension["Chrome extension"] --> Ingest["extension ingest"]
Debugger["chrome.debugger sweep"] --> Ingest
Chrome["Chrome CDP endpoint"] --> Observe["observe CDP"]
Config["Loki config"] --> Ingest
Config --> Observe
Ingest --> Combine["combined snapshot"]
Observe --> Combine
Combine --> Snapshot["chrome_snapshot.cc"]
Combine --> Debug["chrome_debug_probe.cc"]
Snapshot --> Provider["provider_advertisement.cc"]
Snapshot --> Surface["eve_surface.cc"]
```
## Invariants
- CDP reachability is observed state, not assumed capability.
- Extension reachability is observed state, not assumed capability.
- Debug sweeps are explicit observations, not continuous hidden attachment.
- Chrome owns page reality; Loki owns only the observation snapshot.
- `.cc` witnesses are the durable local state surface.
- Eve/CultUI output is derived from the same snapshot as the witness.
- No renderer or dashboard can override the daemon's observation state.
## Intended Change Path
1. Add CultCacheTS-backed binary `.cc` persistence behind the current writer.
2. Add CultNet/CultMesh publication of the same documents.
3. Add command handling only through `gamecult.eve.command.v1`.
4. Add consentful CDP actions, starting with read-only page metadata and
operator-approved screenshot capture.
## Command Boundary
Loki currently advertises no executable tab commands. This is deliberate. A
daemon that can evaluate JavaScript inside live user tabs is holding a sharp
tool; it needs an explicit command document, audit log, origin, target tab id,
and denial path before it should act.