# Project History

Detailed chronological history of ows-coda development milestones.

---

## Week 1 — Foundation (2026-03-03 – 2026-03-07)

### Project Bootstrap (2026-03-03)

Initial repository creation via Terraform. Set up the Express API server with AWS Bedrock (Claude) integration for the Abacus royalties platform.

### CI/CD & Core Server (2026-03-04 – 2026-03-05)

- Jenkins QA pipeline setup (`ACC-9762`)
- CORS configuration
- Migrated from graphql-abacus, cleaned up dead code
- Optimized tool calling — deterministic temperature and topP parameters
- Initial tool definitions for Abacus domain queries

### React Client (2026-03-06 – 2026-03-07)

- Added Vite-based React client (`#11`)
- Docker configuration for local development (`#13`, `#14`)
- Integrated rate limiting (express-rate-limit)

---

## Week 2 — Platform Build-Out (2026-03-08 – 2026-03-12)

### Conversations & UX (2026-03-08)

- Enabled persistent conversations (`ACC-9944`)
- Page load optimizations (`ACC-9946`)
- File compression support
- Environment variable management

### Tool Integration (2026-03-08)

- Integrated ows-ledger service tools (`ACC-9937`, `#24`)
- Integrated ows-abacus-account history and reference tools (`ACC-9948`, `#25`)
- Integrated ows-royalties statement periods, run controllers, and payment entities (`ACC-9950`, `#26`)

### Observability & UX Polish (2026-03-09 – 2026-03-10)

- Sentry integration for runtime and build (`ACC-9950`, `#29`)
- Haiku-based automatic conversation naming (`ACC-9960`)
- Redis extraction for shared state (`ACC-9962`)
- User name display in conversations

### Internationalization (2026-03-10)

- i18n support with 19 locales (`ACC-9964`, `#38`)
- Language selector with smart locale preloading

### Documentation (2026-03-11)

- Initial documentation pass (`ACC-9940`, `#45`)
- HTTPS configuration attempted and reverted (`ACC-9974`)

### Data Sources (2026-03-12)

- Updated royalties data sources (`ACC-9938`, `#49`, `#50`)
- Subaccounts support

---

## Week 3 — Snowflake, Skills & DB (2026-03-13 – 2026-03-16)

### Snowflake Integration (2026-03-13 – 2026-03-14)

- Snowflake read-only query tools (`ACC-9964`, `#51`)
- Secure connection pool with session variable injection for RBAC
- Tool catalog enrichment — domain, hints, examples, core/deferred split
- Colocated tool definitions and handlers per domain directory
- Deferred tool loading for non-core tools

See: [Snowflake views documentation](docs/snowflake-views.md)

### AI Skills (2026-03-14 – 2026-03-15)

- Account overview skill (account details + recent activity)
- Contract overview skill (contract terms + attachments)
- Revenue overview skill (revenue trends + period data)
- GraphQL explore skill (suggested queries, scalar/relation split)
- Snowflake explore skill (schema search + query builder)
- Provider decoupled from Bedrock — abstracted for multi-provider support

### Concurrent Streaming (2026-03-15)

- Per-conversation stream session isolation
- Multi-tab support via concurrent stream sessions

### Coda Database (2026-03-15 – 2026-03-16)

- Custom Snowflake-based persistence layer (`@coda/db`)
- TypeScript types for all Coda database tables
- HMAC-SHA256 and AES-256-GCM identity crypto
- CodaPool read/write connection pool
- User, chat, message, satellite data, and feedback queries
- Message tree queries with CTEs and leaf cache propagation
- Async persister and conversation loader
- Security setup script for Snowflake roles and dynamic data masking
- RSA key-pair authentication (replacing password auth)
- Model seeding at startup

See: [DB package TRD](docs/decisions/trds/db-package-extraction.md)

---

## Week 4 — Infrastructure & Architecture (2026-03-16 – 2026-03-20)

### DB Package Extraction (2026-03-16)

Extracted `@coda/db` — Prisma schema, migrations, client factory, crypto utilities — into a shared workspace package. All import paths updated across server and API packages.

See: [DB package extraction TRD](docs/decisions/trds/db-package-extraction.md) | [Design spec](docs/superpowers/specs/2026-03-16-db-package-extraction-design.md) | [Plan](docs/superpowers/plans/2026-03-16-db-package-extraction.md)

### Docker Compose Environment (2026-03-17)

Full local development environment: MySQL, Redis, S3 (MinIO), migrations, server with HMR, client with Vite HMR. Three profiles: dev, preview, production. All test tiers run in containers.

See: [Docker documentation](docs/guides/docker.md) | [Docker Compose TRD](docs/decisions/trds/docker-compose-environment.md) | [Design spec](docs/superpowers/specs/2026-03-17-docker-compose-local-environment-design.md)

### Offline Client & API Pagination (2026-03-17)

IndexedDB local store with cross-tab BroadcastChannel sync, leader election, and mutation queue. Server-side cursor pagination endpoints designed but not yet implemented.

See: [Offline client PRD](docs/decisions/prds/offline-client-cursor-pagination.md) | [Design spec](docs/superpowers/specs/2026-03-17-offline-client-cursor-pagination-design.md)

### Build System Migration (2026-03-18)

- Server migrated to tsdown (CommonJS output for dd-trace compatibility)
- All packages standardized to build ESM only
- dd-trace resolution fixes across Docker and production builds (`#64`–`#68`)

### Message Status & Stream Persister (2026-03-18)

Incremental `StreamPersister` class — creates both messages at stream start, persists satellite records as they arrive. `MessageStatus` enum (`pending`, `streaming`, `complete`, `error`, `cancelled`) on the messages table.

See: [Stream persister TRD](docs/decisions/trds/message-status-stream-persister.md) | [Design spec](docs/superpowers/specs/2026-03-18-message-status-stream-persister-design.md)

### Message Feedback (2026-03-18)

Thumbs up/down on assistant messages with optional comment. Persisted via `message_feedback` table.

See: [Message feedback PRD](docs/decisions/prds/message-feedback.md) | [Design spec](docs/superpowers/specs/2026-03-18-message-feedback-design.md)

### Get Single Chat Endpoint (2026-03-18)

`GET /api/v1/chats/:id` — eliminates pagination workaround in `MutationQueue.refreshFromServer()`.

See: [Get single chat TRD](docs/decisions/trds/get-single-chat-endpoint.md) | [Design spec](docs/superpowers/specs/2026-03-18-get-single-chat-endpoint-design.md)

### Functional Tests (2026-03-18)

Full-stack functional test infrastructure with real MySQL + Redis, `FakeProvider` for deterministic LLM responses. Covers conversation lifecycle, tool execution, edge cases, streaming events.

See: [Functional tests TRD](docs/decisions/trds/functional-tests.md) | [Design spec](docs/superpowers/specs/2026-03-18-functional-tests-design.md)

### Sandbox Engine Design (2026-03-18)

`@coda/sandbox` — V8 isolate execution engine for LLM-generated JavaScript. Message-passing API, memory-gapped sandbox, bridge protocol for data access.

See: [Sandbox engine PRD](docs/decisions/prds/sandbox-engine.md) | [Design spec](docs/superpowers/specs/2026-03-18-sandbox-engine-design.md) | [Sandbox architecture](docs/architecture/sandbox.md)

### Auth Error Page (2026-03-19)

Dedicated error page for Auth0 callback and SDK initialization failures. Breaks the infinite redirect loop on auth failures.

See: [Auth error page PRD](docs/decisions/prds/auth-error-page.md) | [Design spec](docs/superpowers/specs/2026-03-19-auth-error-page-design.md)

### Auth0 Configuration (2026-03-19 – 2026-03-23)

- Switched to dedicated coda-login Auth0 client (`ACC-9993`, `#79`)
- Auth0 audience and domain passed to client build (`#80`, `#81`)
- Client optimizations and smart locale preloading (`#71`, `#72`)

### Stream Module (2026-03-20)

Typed SSE reader/writer pair in `@coda/core-api`. Centralizes streaming protocol with compile-time safety (`StreamEventMap`, `StreamWriter`, `StreamReader`).

See: [Stream module TRD](docs/decisions/trds/stream-module.md) | [Design spec](docs/superpowers/specs/2026-03-20-stream-module-design.md)

### Codebase Review (2026-03-20)

Comprehensive codebase audit identifying 30+ issues across P0/P1/P2 severity levels. Led to targeted fixes and ongoing remediation tracked in todos.

See: [Codebase review](docs/superpowers/specs/2026-03-20-codebase-review.md) | [Remediation TRD](docs/decisions/trds/codebase-review-remediation.md)

### File Splits & Dedup (2026-03-20)

- Extracted shared `tokenize()` utility from catalog and schema-index
- Split `schema-index.ts` (507 lines) into `introspect.ts`, `search.ts`, and facade
- Replaced O(n^2) `toolResults.find()` with Map lookups
- Extracted `useConversationMutations` hook from `chat-provider.tsx`

See: [File splits TRD](docs/decisions/trds/file-splits-dedup.md) | [Plan](docs/superpowers/plans/2026-03-20-file-splits-dedup.md)

---

## Week 5 — Search, Common Package & Polish (2026-03-21 – 2026-03-24)

### Semantic Schema Search (2026-03-21)

Hybrid search engine combining vector similarity (MiniLM embeddings via ONNX/Transformers.js), keyword matching (inverted index), and domain glossary boosting. Auto-derived FK graph for GraphQL schema. Quantized uint8 vectors for fast dot-product similarity.

See: [Semantic search TRD](docs/decisions/trds/semantic-schema-search.md) | [Design spec](docs/superpowers/specs/2026-03-21-semantic-schema-search-design.md)

### Collections Consistency (2026-03-21)

Normalized `has()`/`delete()` methods across List/Heap collection interfaces in `@coda/common`.

See: [Collections TRD](docs/decisions/trds/collections-consistency.md) | [Plan](docs/superpowers/plans/2026-03-21-collections-consistency.md)

### `@coda/common` Package (2026-03-21 – 2026-03-23)

Shared workspace package with:

- **Collections**: ArrayList, LinkedList, DoublyLinkedList, SkipList, BinaryHeap, SkewHeap, AATree, AVLTree, ArrayQueue, LinkedQueue, ArrayStack, LinkedStack
- **Algorithms**: Binary search, top-k, string utils, tree traversal, heap operations
- **Search**: HybridSearch, InvertedIndex, VectorIndex, glossary matching, tokenizer, trie, quantization
- **Graph**: Graph data structure, BFS, disjoint set union
- **Cache**: LRU cache, ring buffer
- **Utils**: Async helpers (semaphore, yield, retry), error types, math, u32 operations

### Snowflake Schema Index (2026-03-22)

Two-phase index for Snowflake catalog: ACCOUNT_USAGE-based table/view/column discovery at startup, inferred FK graph from `_ID` column naming conventions, 20-minute polling for changes. Keyword-only index built immediately, vector embeddings computed in background.

See: [Snowflake index TRD](docs/decisions/trds/snowflake-schema-index.md) | [Design spec](docs/superpowers/specs/2026-03-22-snowflake-schema-index-design.md)

### Ephemeral Environments (2026-03-22)

PR-comment-triggered ephemeral environments via Jenkins. Create/destroy/list commands, TTL tagging, capacity checks, nightly cleanup.

See: [Ephemeral environments TRD](docs/decisions/trds/ephemeral-environments.md) | [Design spec](docs/superpowers/specs/2026-03-22-ephemeral-environments-design.md) | [User guide](docs/operations/ephemeral-environments.md)

### Logging Improvements (2026-03-22)

Request-scoped traceability via AsyncLocalStorage + pino mixin. Structured fields (`requestId`, `identityHash`, `conversationId`) for Datadog faceting.

See: [Logging TRD](docs/decisions/trds/logging-improvements.md) | [Design spec](docs/superpowers/specs/2026-03-22-logging-improvements-design.md)

### Glossary & Search Tuning (2026-03-23)

- Domain-specific glossaries for Snowflake and GraphQL schemas
- Tools glossary for semantic tool selection
- Search quality improvements: glossary context injection, primary priority boosting, cumulative multi-entry scoring

### Incremental Snowflake Index (2026-03-24)

Made the Snowflake schema indexer's polling incremental — only fetches and re-indexes changed tables instead of rebuilding everything:

- **`VectorIndex`**: Switched from array to Map storage, added `remove()` method
- **`HybridSearch`**: Replaced `build()` with `create()` + `add()`/`update()`/`remove()` mutation methods
- **`fetchCatalogDiff()`**: Replaced `fetchCatalog()` with `LAST_ALTERED`-filtered incremental queries. Initial load (epoch 0) returns full catalog; subsequent polls return only changes
- **Schema-index facade**: `applyDiffToIndexes()` surgically updates keyword index, vector index, and FK graph. `pollInProgress` guard prevents concurrent polls

See: [Design spec](docs/superpowers/specs/2026-03-24-incremental-snowflake-index-design.md) | [Plan](docs/superpowers/plans/2026-03-24-incremental-snowflake-index.md)

### Embedding Provider Enhancements (2026-03-24)

- Added `embedQuery()` to `EmbeddingProvider` interface for asymmetric query/document embeddings
- Configurable mean/CLS pooling in `TransformersEmbeddingProvider`

See: [Embedding provider design spec](docs/superpowers/specs/2026-03-24-embedding-provider-refactor-design.md)

---

## Architecture Reference

For current system design and technical decisions, see [ARCHITECTURE.md](ARCHITECTURE.md).

For API endpoints and streaming protocol, see [API Reference](docs/api/server.md).

For the full tool and skill catalog, see [Tool Catalog](docs/api/tool-catalog.md).

For open work items, see [Roadmap](docs/roadmap.md) and [Todos](docs/todos.md).

---

_Last updated: 2026-03-24_