Eve library

Oshun V1 Phase-2 Documentation Index

Guide

Revision 1

On this page

Owner: eng-platform  Implements: V1-P2-0370  Updated: 2026-04-27

This directory holds the per-decision detail files behind the V1 Phase-2 work tracked in docs/releases/v1/specs/todos-p2.md. Every Phase-2 ticket whose verification mentions a strategy decision, vendor audit, or contract sketch resolves to a file in this directory. The backlog file is the source of truth for status; the docs here are the source of truth for rationale.

Conventions in this directory. Each doc opens with a metadata block (Date, Owner, Backlog item, Status), states the decision in the first paragraph, and follows up with constraints, alternatives considered, and a verification section. Do not write design without a backlog ticket — the backlog is what drives prioritisation. New docs land alongside the ticket flip from [ ] to [x].

Per-domain detail files#

Grouped by Phase-2 work area. Each line links the doc, the originating ticket, and the one-line decision summary. Click through for the full design.

Isis (LLM gateway, cost, determinism)#

ML / on-device runtime (V1-P2-021x family)#

Iris (semantic / privacy / desktop / docs)#

TTS / multimedia gateway#

  • OSHUN TTS Gateway Audit — V1-P2-0140 — state of the existing TTS gateway and the work needed before the Tier-A replacement lands.

Aja (motion, GPU pipeline)#

Persistence / database#

Quality / scanner conventions#

  • Stub-Indicator Allow-List Conventions — V1-P2-0353 — // stub:legitimate <reason> / // random:legitimate <reason> conventions consumed by scripts/stub-indicator-scan.sh. Companion to the stub-indicator-scan (V1-P2-0350) and silent-random-scan (V1-P2-0351) CI jobs.

Cross-cutting templates#

These templates are intentionally generic — every Tier-A subsystem fills out its own copy.

  • Architecture Overview — V1-P2-0371 — the canonical data-flow map across domains after foundational work lands. Read this first when joining a new domain.
  • Runbook Template — V1-P2-0372 — mandatory sections (rate limits, outage drill, escalation contacts, vendor SLA, cost guardrails) that every operationally-owned subsystem must complete.
  • Threat Model Template — V1-P2-0373 — STRIDE-aligned template for per-Tier-A subsystem threat models.

Strategy decisions / ADRs#

Phase-2 decisions that span multiple domains live as Architecture Decision Records under docs/adr/ (72 ADRs as of 2026-04-27 covering shell architecture, web/PWA strategy, cross-domain routing, identity, analytics, design system, observability, etc.). Use the index in docs/adr/ and the corresponding ticket in the backlog as your starting point.

Dashboards#

Operational signals for every Phase-2 subsystem land in the Grafana stack at docker/observability/grafana/. The dashboards below are the authoritative live views; runbooks (V1-P2-0372) link directly to the relevant board for each alert / SLO.

Per-domain Grafana dashboards#

Source: docker/observability/grafana/dashboards/.

  • bellona/migration-orchestrator.json — Bellona migration runs: per-stage queue depth, attempt counts, retry budgets, failure rates.
  • hathor/narrative-lattice.json — Hathor lattice: graph-traversal latencies, cache hit rate, contradictions surfaced.
  • isis/asset-lifecycle.json — Isis assets: queued → generating → rendered → published transitions, per-tenant counts.
  • isis/generation-pipeline.json — Isis generation pipeline: token accounting, per-provider latency, cost-quota burn, deterministic-mode divergences.
  • lilith/event-handlers.json — Lilith handlers: per-handler latency histograms, retry/circuit-breaker state.
  • lilith/experience.json — Lilith experience: session-quality metrics (frame-time, audio underruns, motion-tracking confidence).
  • oshun/platform-overview.json — top-of-funnel view across all domains: SLOs, error rate, deploy markers.
  • oshun/infrastructure.json — node/pod/networking signals at the cluster level.
  • sophia/research.json — Sophia research workflows: query latency, rerank quality, ingestion lag.
  • yemaya/creative-studio.json — Yemaya studio: project-open latency, asset-load throughput, autosave health.
  • yemaya/collaboration.json — Yemaya collaboration: per-room presence, CRDT op latency, conflict-resolution counts.
  • infrastructure/{node,elasticsearch,kafka,postgres,redis}.json — baseline infrastructure fleet signals.

Other observability surfaces#

  • Kibana — error tracking and request tracing, dashboards under deploy/elk/kibana-dashboards/ (error-tracking-dashboard.json, performance-monitoring-dashboard.json, service-overview-dashboard.json).
  • CloudWatch — managed AWS metrics; dashboards declared in Terraform at infra/terraform/cloudwatch/dashboards.tf.
  • Saraswati — additional Grafana dashboards declared in docker/observability/saraswati-grafana-dashboards.yml (loaded by the observability profile).

Quality / scanner workflows#

These CI jobs gate the §2.6 quality bar; their detail docs live in this directory or in the workflow files themselves.

  • stub-indicator-scan — V1-P2-0350 / V1-P2-0351 / V1-P2-0356 / V1-P2-0357 — qualitative + silent random + pre-commit verification + sticky PR comment. Allow-list documented in stub-indicator-allowlist.md.
  • adversarial-grep-trend — V1-P2-0355 — nightly per-domain stub-marker count + week-over-week delta. Snapshot artifact retains 90 days.
  • test-coherence-check — V1-P2-0352 — vitest assertion classification (SHAPE / BOOLEAN / COMPUTED / OTHER) and per-file coherence score.
  • external-api-guard — V1-P2-0358 — fail any PR introducing a new outbound HTTP call without retry + circuit breaker + telemetry. Allow-list documented inline in scripts/external-api-guard.mjs (file-level imports + path allow-list + // http:guarded <reason> inline comment).

Adding a new entry#

  1. Pick the next backlog ticket from OSHUN_V1_TODOS_P2.md. The ticket text states the deliverable; this directory holds the rationale.
  2. Create a new file in this directory using kebab-case ( <domain>-<topic>.md). The first heading must include the ticket ID (# <Title> — V1-P2-NNNN) so the doc is grep-able by ticket.
  3. Open with a metadata block: Status, Date, Owner, Backlog item, Audience. Keep all five fields populated, even if the value is "n/a — see linked ADR".
  4. Add an entry to the appropriate group above. The line format is - [Title](./file.md) — V1-P2-NNNN — one-sentence summary.. Keep the summary readable in a 100-column terminal.
  5. Land the doc in the same PR that flips the ticket to [x]. The verification note in the backlog should reference the doc by relative path so reviewers can read both in one click.