Technical Debt Register

AEGIS TECHNICAL DEBT REGISTER

» **Purpose:** Track every architectural compromise explicitly. Nothing is carried silently. Per Engineering Playbook §8.
» **Rule:** "We'll fix it later" is only acceptable if written here with a **risk** and a **review date**.
» **Status:** Living — updated as slices complete and decisions change.

---


REGISTER

  # | Deferred | Reason | Risk | Priority | Owner | Review date
  1 | **Mock broker auto-connects in dev** | No real credentials needed; proves the runtime live. Deliberate for dev UX. | Mock data could be mistaken for real in a demo. Mitigate: positions are clearly `source:"broker"` but broker is `mock`. | Low | Platform | 2026-08-18
  2 | **Zerodha/Groww adapters are API-shaped, not end-to-end live** | **PARTIALLY CLOSED (Slice 7, 2026-08-04).** Zerodha adapter: complete OAuth flow (getLoginUrl → token exchange → SHA-256 checksum → access_token), all API methods (positions, holdings, orders, capital, margins, history, stream). Verification layer validates shapes. Settings view with broker onboarding UI. Remaining: live OAuth token exchange with real credentials, WebSocket realtime verification. | Live OAuth end-to-end test pending. | High | Platform · Broker | 2026-08-18
  3 | **BrokerRuntime `mark()` is a no-op** | Status transitions rely on emitted events + health snapshot; a full state-machine registry deferred. | Per-broker textual status may drift from true lifecycle. | Low | Platform | 2026-08-18
  4 | **`useBrokerData` polls on an interval** | Simple refresh cadence beats building a full subscription graph now. | Extra renders + potential races; should become event-driven (PositionUpdated). | Med | Platform · UI | 2026-08-18
  5 | **Broker reconnect backoff not fully jittered** | Exponential with small jitter added; ideal exponential-with-full-jitter deferred. | Rare synchronized reconnect storms with many brokers. | Low | Platform | 2026-08-25
  6 | **SecretVault defaults to localStorage** | **CLOSED (Slice 6, 2026-08-04).** SecureVault implemented: AES-GCM + PBKDF2 key derivation, session mode (key held in memory, never serialized), `createEncryptedBrokerStorage()` wraps the vault, tamper detection, lock/unlock lifecycle, rotation. localStorage now holds only ciphertext blobs. | — | — | —
  7 | **Mission Control «Protection» widget shows static «Ready»** | **CLOSED (Slice 3, 2026-08-04).** Protection Engine runtime built; Mission Control Protection widget now reads live armed/triggered count + mode. | — | — | — | —
  8 | **`BrokerRuntime.sync` emits PortfolioUpdated per sync, no batching** | Fine at 1 broker; may spam at 20 brokers × 30s. | Event volume / render churn at scale. | Med | Platform · Sync | 2026-09-01
  9 | **No realtime tick subscription to Mission Control yet** | Runtime has realtime; widgets refresh on interval + sync. | Live P&L lags by up to 5s in dev. | Med | Platform · UI | 2026-08-18
  10 | **SDK `registerSettingsScreen` is a no-op** | Settings workspace not built (Phase 2). | Silent no-op could hide future misuse. | Low | Platform | 2026-09-01
  11 | **No undo/redo on Command Bus yet** | Runtime spec §4 defines it; not implemented. | Some irreversible user actions lack safety net. | Med | Platform · Core | 2026-09-01
  12 | **No formal idempotency keys on broker syncs** | At-least-once replay defined; not implemented. | Reconnect could double-apply a position update. | Med | Platform · Broker | 2026-09-01
  13 | **`verify-architecture.ts` reads source via fs for the no-React check** | Cheap structural assertion; fragile to import-style changes. | False safety if import paths change. | Low | Platform | 2026-08-25
  14 | **`persistent-storage.ts` superseded by the Broker Auth Platform** | **SUPERSEDED (Sprint 10, 2026-08-06).** `bootBrokerPlatform` now uses `createPlatformBrokerStorage("aegis")` (platform-owned sessions, per app+broker). The legacy `src/platform/broker/persistent-storage.ts` remains only because the verify suite still exercises it as a regression guard; no runtime path imports it. Next step: either delete it (after porting its verify assertions to the platform store) or keep as documented legacy. | Drift risk: two session stores if a future path writes the old one. | Low | Platform | 2026-08-25

---


DEDUCTIONS FROM THE REGISTER

• **Highest risk before production:** #2 (real broker adapters unverified) and #6 (SecretVault security) — both must land before any live-money integration.
• **Highest user-facing risk:** ~~#7~~ CLOSED via Slice 3 — the Protection Engine is live and the Mission Control widget no longer implies safety that isn't there.
• **Performance budgets stated (Playbook §7) apply to:** Broker sync <250ms, Mission Control refresh <100ms, Protection eval <20ms, widget render <16ms, command <50ms. No subsystem is "done" without its budget.

---


REVIEW SCHEDULE
• Re-audit this register at the **end of every implementation slice**, and **before any production / live-money deployment**.
• Escalate any High-priority item with a review date that has passed to the owner.