> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session08-dated-predictions-and-story-log/spec.md).

# Session Specification

**Session ID**: `phase27-session08-dated-predictions-and-story-log` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-13

***

## 1. Session Overview

This session extends the existing Trend Finder prediction loop from immediate next-run directional calls into optional dated, lifecycle-targeted calls. The current system already writes private prediction archives, grades future-run retros, tracks pending outcomes, and publishes a capped browser summary. Session 08 keeps that machinery intact while adding explicit target dates, lifecycle at filing, target lifecycle, and deterministic fallback horizon buckets.

The session also adds a Story Log surface: a larger but still bounded browser-safe projection of prediction history with verdict and due-state filtering. This turns the prediction loop into a trust surface: the user can see when a call was filed, what date it targets, and how it was eventually graded without exposing raw archives, prompt payloads, provider responses, private paths, or unbounded cache contents.

The work stays additive and deterministic. Existing next-run prediction and retro behavior must remain compatible, backtest and future-run modes must stay distinct, dated predictions must remain pending until their target date is due, and calibration metrics must count resolved dated outcomes without inflating pending or not-yet-due calls.

***

## 2. Objectives

1. Add optional dated prediction fields with UTC target dates, lifecycle at filing, target lifecycle, provenance, and deterministic fallback buckets.
2. Update retro grading so dated predictions are graded only on or after their target date, with target-date-aware pending and stale semantics.
3. Publish a bounded Story Log projection of prediction and retro history with verdict, due-state, topic, date, and provenance fields safe for browser use.
4. Render Story Log history with deterministic filters in Watchlist and a compact prediction-history summary in Brief.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase27-session01-brief-movement-groups-and-calibration-metrics` - provides calibration summary patterns in Brief and static/report surfaces.
* [x] `phase27-session06-lifecycle-stage-taxonomy` - provides lifecycle stages for lifecycle-at-filing and target-lifecycle prediction fields.

### Required Tools/Knowledge

* Bun 1.3.14 for script and test commands.
* TypeScript, Zod, React 19, Tailwind CSS 4, Vitest, and existing Trend Finder conventions.
* Existing prediction and retro modules in `scripts/lib/ai-runtime/predictions.ts` and `scripts/lib/ai-runtime/retros.ts`.
* Existing collector integration in `scripts/extensions/trend-finder/collector.ts`.
* Existing browser contract, view-model, Watchlist, and Brief surfaces in `src/extensions/trend-finder/schema.ts`, `src/extensions/trend-finder/view-model.ts`, `src/extensions/trend-finder/views/watchlist-view.tsx`, and `src/extensions/trend-finder/views/brief-view.tsx`.

### Environment Requirements

* Repository rooted at `/home/aiwithapex/projects/aios`.
* Phase 27 stubs present under `.spec_system/PRD/phase_27/`.
* No open security findings per `.spec_system/SECURITY-COMPLIANCE.md`.
* Existing fixture and unit-test suites runnable with Bun/Vitest.

***

## 4. Scope

### In Scope (MVP)

* Additive prediction record fields for `targetDate`, `lifecycleAtFiling`, `targetLifecycle`, and dated display copy while preserving legacy next-run fields and defaults.
* Deterministic fallback dated predictions using fixed horizon buckets derived from `generatedAt` and topic lifecycle, with `fallback` provenance.
* AI output validation and prompt updates that allow dated fields but reject unknown topic IDs, unknown evidence IDs, invalid dates, invalid lifecycle stages, oversized text, and sanitized/private metadata.
* Target-date-aware retro grading: predictions before their target date remain pending and not stale; due predictions grade with existing hit/partial/miss/pending outcomes.
* Calibration summary over resolved dated and next-run outcomes while excluding not-yet-due pending calls from resolved math.
* Bounded Story Log browser projection, around 50 rows, built from private archive records and current-run results without raw cache exposure.
* Watchlist Story Log panel with verdict and due-state filters, deterministic ordering, explicit empty states, and accessible controls.
* Brief prediction-history summary that highlights dated calls and recent outcomes without burying the ranked trend surface.
* Tests for fallback determinism, target-date grading windows, stale behavior, projection bounds, legacy parsing, filtering, and UI states.

### Out of Scope (Deferred)

* Breaking or replacing existing next-run prediction records - Reason: dated prediction fields are additive.
* Publishing raw prediction or retro archives - Reason: private cache contents stay local and unbounded data stays out of browser payloads.
* New source adapters, source calls, or compliance reviews - Reason: this session uses already-collected topics, evidence, lifecycle fields, and private prediction caches.
* Backtest CLI behavior changes beyond keeping `backtest` and `future-run` modes distinct - Reason: this session targets future-run dated predictions.
* Point estimates such as `tbts`, peak-day, or time-to-breakout - Reason: Phase 27 rejects those as invented precision.

***

## 5. Technical Approach

### Architecture

Keep dated prediction and Story Log behavior on the same script-first pipeline used by the current prediction/retro loop:

* `src/extensions/trend-finder/schema.ts` adds bounded optional target fields to `PredictionRecordSchema`, bounded optional due-state fields to `RetroRecordSchema` if needed for display, and a new Story Log summary branch under `PredictionRetroSummarySchema` with defaults for legacy payloads.
* `scripts/lib/ai-runtime/predictions.ts` updates prompts, output schema hints, validation, sanitization, deterministic fallback, and archive read/write parsing so every topic can produce a dated call without losing the existing next-run call contract.
* `scripts/lib/ai-runtime/retros.ts` adds target-date eligibility checks, not-yet-due pending behavior, due pending/stale thresholds, and calibration helpers that keep resolved dated outcomes in the math while excluding not-yet-due rows from resolved counts.
* `scripts/extensions/trend-finder/collector.ts` passes lifecycle information into prediction candidates, reads prior prediction/retro archives, projects a capped Story Log from sanitized records, and emits only aggregate counters in Engine Replay trace context.
* `src/extensions/trend-finder/view-model.ts` converts dated predictions, retros, and Story Log rows into display labels, filter counts, ARIA labels, due-state text, and deterministic sort keys.
* `src/extensions/trend-finder/components/story-log-panel.tsx` renders fixed, dense history rows with verdict and due-state segmented filters.
* `src/extensions/trend-finder/views/watchlist-view.tsx` inserts the Story Log panel into the prediction/history area, and `src/extensions/trend-finder/views/brief-view.tsx` renders a compact summary that preserves the Brief first-viewport hierarchy.

Suggested target-date semantics:

* Dates are normalized as UTC `YYYY-MM-DD` strings.
* Dated fallback horizons are deterministic buckets, for example 30, 60, or 90 days from `generatedAt`, chosen from lifecycle stage and current movement.
* A dated prediction is not eligible for grading until `generatedAt` for the current run is on or after `targetDate`.
* Before the target date, the retro row remains pending with a not-yet-due due state and does not increment stale-pending pressure.
* On or after the target date, grading reuses current observed-direction logic and existing outcome enums.
* Stale pending applies only after the target date has passed for the configured pending threshold.

### Design Patterns

* Additive schema defaults: legacy payloads and fixtures parse with empty Story Log data and no dated fields.
* Script-only runtime boundary: dated prediction math, archive projection, and sanitization stay under `scripts/lib/` and `scripts/extensions/`.
* Project before rendering: React components consume view models, not raw archive records or unvalidated payload branches.
* Deterministic ordering: Story Log rows sort by due state, target date, generated date, topic name, and stable IDs.
* Behavioral quality by design: filters have accessible labels, state resets on re-entry, empty/error states are explicit, arrays are bounded, and all enum handling is exhaustive.

### Technology Stack

* TypeScript 6.0.3
* React 19.2.0
* Zod 4.4.3
* Vitest 4.1.6
* Bun 1.3.14

***

## 6. Deliverables

### Files to Create

| File                                                                        | Purpose                                                                    | Est. Lines |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
| `src/extensions/trend-finder/components/story-log-panel.tsx`                | Filterable Story Log panel for Watchlist prediction history.               | \~220      |
| `src/extensions/trend-finder/components/__tests__/story-log-panel.test.tsx` | Component tests for filters, empty states, ARIA labels, and row rendering. | \~160      |

### Files to Modify

| File                                                          | Changes                                                                             | Est. Lines |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------- |
| `src/extensions/trend-finder/schema.ts`                       | Add dated prediction fields, Story Log schemas, defaults, and bounds.               | \~260      |
| `scripts/lib/ai-runtime/predictions.ts`                       | Add dated prompt, validation, fallback, sanitization, and archive parsing.          | \~260      |
| `scripts/lib/ai-runtime/retros.ts`                            | Add target-date eligibility, due-state/stale logic, and calibration handling.       | \~260      |
| `scripts/extensions/trend-finder/collector.ts`                | Pass lifecycle into candidates, build Story Log projection, and trace counters.     | \~180      |
| `src/extensions/trend-finder/view-model.ts`                   | Add dated row labels, Story Log filter models, due-state copy, and sorting.         | \~240      |
| `src/extensions/trend-finder/views/watchlist-view.tsx`        | Render Story Log panel in prediction/history area with resettable filters.          | \~120      |
| `src/extensions/trend-finder/views/brief-view.tsx`            | Render compact dated prediction and recent outcome summary.                         | \~90       |
| `src/extensions/trend-finder/fixtures.ts`                     | Add dated prediction, due, pending, resolved, and legacy fixture states.            | \~160      |
| `src/data/live-data.example.json`                             | Add compact additive dated prediction and Story Log examples.                       | \~90       |
| `scripts/lib/ai-runtime/__tests__/predictions.test.ts`        | Cover dated fallback, prompt validation, sanitization, and legacy archives.         | \~180      |
| `scripts/lib/ai-runtime/__tests__/retros.test.ts`             | Cover target-date grading windows, stale behavior, and calibration math.            | \~180      |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts` | Cover lifecycle candidate wiring, Story Log projection, bounds, and trace counters. | \~160      |
| `src/lib/__tests__/trend-finder-schema.test.ts`               | Cover additive defaults, bounds, malformed dated fields, and legacy parsing.        | \~160      |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`    | Cover Story Log labels, filters, ordering, due states, and empty copy.              | \~180      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Existing next-run prediction records, retro rows, and calibration fields parse and render unchanged.
* [ ] Dated predictions include target date, lifecycle at filing, target lifecycle, display horizon, cited evidence IDs, and provenance.
* [ ] Deterministic fallback produces dated calls without AI and without invented source IDs, evidence IDs, or private metadata.
* [ ] Dated predictions grade only on or after their target date; earlier runs keep them pending and not stale.
* [ ] Due dated predictions use existing hit/partial/miss/pending outcomes and preserve `future-run` versus `backtest` mode distinction.
* [ ] Story Log stays bounded, browser-safe, and sorted deterministically with verdict and due-state filtering.
* [ ] Brief and Watchlist expose prediction history without raw archives, private paths, prompt text, provider responses, or unbounded cache rows.

### Testing Requirements

* [ ] Prediction tests cover dated fallback buckets, valid AI rows, invalid target dates, unknown lifecycle stages, unknown evidence IDs, and legacy archive parsing.
* [ ] Retro tests cover before-target pending, on-target grading, after-target stale behavior, topic disappearance, mode preservation, and calibration counts.
* [ ] Collector tests cover Story Log projection bounds, archive merge ordering, sanitized trace counters, and fallback behavior when archives are absent or malformed.
* [ ] Schema tests cover additive defaults, max-array bounds, malformed Story Log rows, and old payload compatibility.
* [ ] View-model and component tests cover filter counts, reset behavior, empty states, accessible labels, and deterministic row ordering.

### Non-Functional Requirements

* [ ] Browser payload remains bounded and under the shared 1 MB extension payload limit.
* [ ] No new source adapter, credential, AI provider, public collection path, third-party transfer, or bridge endpoint is introduced.
* [ ] Private prediction and retro archives remain local and never appear as raw browser or static-export content.
* [ ] Watchlist and Brief UI remain dense, stable, mobile-safe, and free of horizontal overflow.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Focused tests pass before broader validation

***

## 8. Implementation Notes

### Key Considerations

* The current prediction/retro modules already sanitize records and cap recent browser rows at `PREDICTION_RETRO_SUMMARY_LIMIT`; Story Log should introduce a separate explicit cap rather than reusing a "recent rows" cap by accident.
* The private archive under `.cache/extensions/trend-finder/predictions/` is implementation detail, not a browser contract.
* Dated target fields must be optional so older generated payloads, fixtures, and archives stay valid.
* Dated fallbacks should be deterministic from `generatedAt`, lifecycle, and movement, not from wall-clock execution time.

### Potential Challenges

* Archive merge duplication: Use prediction and retro IDs as stable keys and prefer current-run sanitized records where IDs collide.
* Date boundary drift: Normalize all target comparisons to UTC date strings and cover same-day, before-target, and after-target cases in tests.
* Calibration inflation: Count only resolved outcomes in hit-rate/Brier math and keep not-yet-due pending calls visible but unresolved.
* Payload growth: Cap Story Log rows, truncate display strings, and update payload budget checks during implementation.

### Relevant Considerations

* \[P02] **Extension payloads and demo labels stay bounded**: Story Log arrays must be capped and provenance labels must stay explicit.
* \[P15] **Aggregate collection must stay budgeted**: dated prediction output must not add new source calls or unbounded AI work.
* \[P24] **Browser-safe export and triage boundaries**: private prediction archives and local triage details stay out of browser and export payloads.
* \[P24] **Additive defaults keep legacy payloads alive**: dated fields and Story Log branches must parse old payloads safely.
* \[P05] **Script-only runtime boundary**: prediction math, retro grading, and projection logic stay in scripts/runtime code; browser code renders validated payload only.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Dated predictions could be graded before their target date if due-state logic is not centralized and tested.
* Story Log could expose too much history if archive projection is not capped and sanitized before browser output.
* Watchlist filters could preserve stale UI state across data refreshes if they do not reset or revalidate against the current row set.

***

## 9. Testing Strategy

### Unit Tests

* `scripts/lib/ai-runtime/__tests__/predictions.test.ts`: dated fallback buckets, validation, sanitization, prompt schema hints, and archive compatibility.
* `scripts/lib/ai-runtime/__tests__/retros.test.ts`: target-date eligibility, stale pending, mode preservation, and calibration counts.
* `src/lib/__tests__/trend-finder-schema.test.ts`: schema defaults, bounds, malformed branches, and legacy payload parsing.
* `src/extensions/trend-finder/__tests__/view-model.test.ts`: Story Log labels, filter counts, ordering, due-state copy, and empty copy.

### Integration Tests

* `scripts/extensions/trend-finder/__tests__/collector.test.ts`: lifecycle candidate wiring, archive merge/projection, Story Log bounds, and sanitized trace counters.
* Existing Trend Finder fixture tests should prove `parseTrendFinderData` accepts legacy and new payloads.

### Manual Testing

* Open Watchlist with a fixture containing not-yet-due, due pending, hit, partial, and miss rows; verify filters, labels, and empty states.
* Open Brief and confirm the compact prediction-history section remains below the key Brief summary and does not dominate the first viewport.
* Run a payload-size check against a fully populated Story Log projection.

### Edge Cases

* Target date equals current run date.
* Target date is before generated date in legacy or malformed archive rows.
* Topic disappears between filing and target date.
* Prediction record has no lifecycle because it came from a legacy archive.
* Prior retro archive is malformed or missing.
* Multiple runs produce pending rows for the same prediction before and after target date.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase27-session01-brief-movement-groups-and-calibration-metrics`, `phase27-session06-lifecycle-stage-taxonomy`
* **Depended by**: `phase27-session12-documentation-validation-and-release`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session08-dated-predictions-and-story-log/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.