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)#
- Isis LLM Gateway Audit — V1-P2-0001 — audit the
existing
libs/isis/llm-providers/implementation; identify gaps before the Tier-A replacement work begins. - Isis Cost-Tracking and Quota Contract — V1-P2-0005 — token-accounting + per-tenant quota model the cost middleware must enforce.
- Isis Deterministic-Mode Contract — V1-P2-0021 — replay/snapshot semantics for golden-test runs.
ML / on-device runtime (V1-P2-021x family)#
- On-Device ML Runtime Strategy — V1-P2-0210 — ONNX Runtime Web (browser) + ONNX Runtime Node (server); WASM for fallback.
- Pose Estimation Provider — V1-P2-0211 — default provider + accuracy/latency contract.
- Object Detection Provider — V1-P2-0212 —
ONNX YOLOv8 (
nands) as the real-time default. - ASR / VAD Provider — V1-P2-0213 — ONNX Whisper family
(
tiny.en/base.en/small.en/medium.en). - Speaker Identification Provider — V1-P2-0214 — selected speaker-ID stack and accuracy budget.
- Emotion Detection Provider — V1-P2-0215 — voice (wav2vec2-emotion) + image (FER) provider choice.
- Cross-Encoder Reranker — V1-P2-0216 — BAAI
BGE-Reranker (
bge-reranker-v2-m3/v2-large) for the rerank stage.
Iris (semantic / privacy / desktop / docs)#
- Embedding Provider Stack Decision —
V1-P2-0030 —
IrisEmbeddingClientprovider chain (BGE / OpenAI / fallback). - OCR Strategy Decision — V1-P2-0060 — selected OCR engine and per-page latency budget.
- Vision LLM Strategy Decision — V1-P2-0064 — vision-LLM provider with accuracy/cost/refusal-mode contract.
- Document Layout Analysis Strategy — V1-P2-0066 — DLA pipeline for ingested PDFs / scans / screenshots.
- Desktop Automation Stack Decision — V1-P2-0090 — pointer/keyboard/clipboard/screen-capture stack.
- Crypto Replacement Targets — V1-P2-0176 —
sites in
libs/aje/,libs/aphrodite/,libs/airmid/,libs/iris/memory/privacy/,libs/iris/a2a/,libs/iris/privacy/security/dlp/whose stub crypto must move to the real primitives, and the migration order.
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)#
- Aja Readiness Audit — V1-P2-0330 — full inventory
of
libs/aja/*andapps/aja/*against the §2.6 quality bar. - Aja V1 Descope Decision — V1-P2-0331 — what stays in V1 vs. what slips to V2, driven by the readiness audit.
- Aja Kubernetes Runtime Strategy — V1-P2-0333 — V1 deployment posture for Aja services.
- Aja GPU Pipeline Strategy — V1-P2-0334 — per-stage GPU pipeline, batching, and back-pressure plan.
Persistence / database#
- Drizzle / Persistence Completion Targets —
V1-P2-0233 — the sites under
libs/andapps/whoseDrizzle/persistence layer is currently a placeholder, and the order in which they migrate.
Quality / scanner conventions#
- Stub-Indicator Allow-List Conventions —
V1-P2-0353 —
// stub:legitimate <reason>/// random:legitimate <reason>conventions consumed byscripts/stub-indicator-scan.sh. Companion to thestub-indicator-scan(V1-P2-0350) andsilent-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 instub-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 inscripts/external-api-guard.mjs(file-level imports + path allow-list +// http:guarded <reason>inline comment).
Adding a new entry#
- Pick the next backlog ticket from
OSHUN_V1_TODOS_P2.md. The ticket text states the deliverable; this directory holds the rationale. - 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. - 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". - 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. - 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.