# Phase 4 Execution Plan

> **Flow:** Shared personal timeline over the first three ecosystem flows
> **Status:** Done
> **Owner:** `learning_ai_common_plat`
> **Purpose:** Turn the personal timeline PRD into a reusable contract and baseline aggregator so the first three ecosystem flows can be rendered as one coherent activity stream.

---

## 1. Scope

Phase 4 defines and implements:

1. the canonical `TimelineItem` shape
2. baseline event-to-timeline mapping rules
3. a pure aggregator that converts canonical ecosystem events into timeline items
4. the first hosted platform-service API for timeline ingest and timeline query

This phase now establishes the shared data contract, the first persisted service surface, and the first hosted internal timeline UI.

---

## 2. Code Surface

- `packages/events/src/timeline.ts`
- `packages/events/src/timeline.test.ts`
- `packages/events/src/index.ts`
- `services/platform-service/src/modules/timeline/types.ts`
- `services/platform-service/src/modules/timeline/repository.ts`
- `services/platform-service/src/modules/timeline/routes.ts`
- `services/platform-service/src/modules/timeline/routes.test.ts`
- `dashboards/admin-web/src/app/api/timeline/route.ts`
- `dashboards/admin-web/src/app/(dashboard)/timeline/page.tsx`
- `dashboards/admin-web/src/__tests__/timeline.test.ts`
- `dashboards/admin-web/src/__tests__/timeline-view.test.ts`
- `dashboards/admin-web/src/lib/timeline-view.ts`

---

## 3. Covered Inputs

The baseline mapper covers the high-value events already implemented in Phases 1 to 3:

- `capture.transcript.created`
- `artifact.created`
- `artifact.linked`
- `memory.entry.created`

This is enough to render:

- transcript -> note -> memory
- plan -> routine -> habit
- trail-report -> note -> memory

---

## 4. Verification

- `cd learning_ai_common_plat/packages/events && pnpm exec vitest run src/timeline.test.ts`
- `cd learning_ai_common_plat && pnpm --filter @bytelyst/events build`
- `cd learning_ai_common_plat && pnpm --filter @lysnrai/platform-service exec vitest run src/modules/timeline/routes.test.ts src/server.test.ts`
- `cd learning_ai_common_plat && pnpm --filter @lysnrai/platform-service exec tsc --noEmit`
- `cd learning_ai_common_plat/dashboards/admin-web && npm run test -- src/__tests__/timeline.test.ts src/__tests__/timeline-view.test.ts`
- `cd learning_ai_common_plat/dashboards/admin-web && npm run typecheck`

Observed baseline:

- Phase 1, Phase 2, and Phase 3 sample events now produce one sorted timeline list
- each item preserves:
  - event identity
  - product identity
  - artifact refs
  - related event refs
  - actor type
  - correlation ID
- platform-service now exposes `POST /api/timeline/ingest` for canonical ecosystem-event ingestion
- platform-service now exposes `GET /api/timeline` for unified timeline query
- non-admin JWT callers are scoped to their own timeline while admin and API-key callers can query broader product timelines
- admin-web now exposes the first hosted internal timeline UI at `/timeline`
- the hosted UI now supports explicit product scope selection, correlation-chain grouping, user/artifact/event filters, and focused timeline helper tests

---

## 5. Done Criteria

- [x] define `TimelineItem` contract
- [x] define baseline event-to-timeline mapping rules
- [x] implement pure timeline aggregation over canonical events
- [x] verify that Phase 1 to Phase 3 events render in one unified stream
- [x] add first hosted timeline ingest/query API in platform-service
- [x] choose first hosted timeline UI

---

## 6. Commits

- `3f2482b` timeline contract and aggregator baseline
- `e377351` platform-service timeline ingest + query baseline
- `6f3a563` admin-web hosted timeline dashboard
- `d328c7a` admin-web product-scope and correlation-grouping hardening
