> 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/phase29-session15-pre-run-estimate/spec.md).

# Session Specification

**Session ID**: `phase29-session15-pre-run-estimate` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-21

***

## 1. Session Overview

This session adds a bounded pre-run estimate for Trend Finder runs. Before an operator starts a run, the scheduler and run-control surfaces should show projected spend, reviewed cadence, and expected wall-clock information derived from existing safe accounting and scheduler status data.

The work is Tier 3 operator polish from the TrendingAI comparison. It improves transparency before execution without adding a hard spend cap, changing actual post-run spend accounting, or expanding any source or media boundary.

The implementation should reuse the current Trend Finder spend-accounting, scheduler-status, browser schema, and view-model paths. UI copy must be explicit that values are estimates and must keep retrospective actual-spend labels unchanged.

***

## 2. Objectives

1. Add a browser-safe pre-run estimate contract for spend, cadence, and wall-clock projection.
2. Surface the estimate in the scheduler first-run panel before a run starts.
3. Surface the estimate in Trend Finder run control before a manual run starts.
4. Prove missing-cost and configured paid-source cases without regressing actual-spend accounting, payload budget, or privacy boundaries.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase28-session02-delta-aware-enrichment-spend-accounting` - Provides spend accounting and configured charge-cap estimate behavior.
* [x] `phase24-session05-scheduler-first-run-live-progress-controls` - Provides the scheduler first-run and live progress surfaces that this session extends.
* [x] `phase29-session14-one-to-watch-surface` - Keeps current Phase 29 operator-polish ordering complete before this session.

### Required Tools/Knowledge

* Bun 1.3.14 with existing `bun run test` and focused Vitest commands.
* Existing Trend Finder scheduler status bridge and token-gated local endpoints.
* Existing Tailwind, Radix, and compact dashboard component conventions.

### Environment Requirements

* Local generated data and scheduler state may be absent; implementation must handle first-run and missing-cost states.
* No `.env`, token, raw provider response, private cache path, or scheduler log path may enter browser payloads.

***

## 4. Scope

### In Scope (MVP)

* Operator can see a pre-run estimate before execution - Compute a bounded estimate from existing spend summary, selected cadence, and safe scheduler duration facts.
* Operator can understand estimate confidence - Label unavailable, estimated, mixed, exact, and not-applicable cases without implying an unenforced spend cap.
* Operator can see the estimate in scheduler first-run panel - Add dense, compact estimate metrics beside cadence and generated-data facts.
* Operator can see the estimate in manual run control - Add pre-run estimate copy near runtime/source readiness before the run button.
* Maintainer can validate edge cases - Add tests for missing-cost and configured paid-source cases plus browser schema defaults.

### Out of Scope (Deferred)

* Introducing or enforcing a new hard spend cap - Reason: the session is transparency only and the runner does not enforce a new cap.
* Changing post-run actual-spend accounting - Reason: retrospective spend labels must remain unchanged.
* Adding new sources, providers, podcast behavior, or media collection - Reason: source/media scope remains owned by later compliance sessions.
* Changing scheduler cadence options beyond existing reviewed candidates - Reason: this session consumes cadence, it does not define new schedules.

***

## 5. Technical Approach

### Architecture

Add a typed `preRunEstimate` projection to the Trend Finder scheduler status payload. The script-side builder should use existing spend summary fields, selected scheduler cadence, source counts, latest safe run duration when available, and explicit unavailable fallbacks. Browser parsing should add defaults so legacy generated data remains valid.

The view model should format a concise estimate for UI consumers and should keep the existing `recurringSpend` path intact for compatibility. The scheduler first-run panel can render the richer estimate directly. Trend run control should accept the scheduler estimate when available and degrade gracefully when the scheduler bridge is unavailable, offline, or still loading.

### Design Patterns

* Parser-backed contracts: Use Zod defaults for backward-compatible browser payload parsing.
* Safe projection before rendering: Convert script-side scheduler and spend details into browser-safe labels before UI surfaces consume them.
* Existing operational UI density: Reuse compact metric blocks, tabular money/duration formatting, and current run-control layout patterns.
* Deterministic unavailable state: Show unavailable labels for missing cost or duration instead of inventing spend or wall-clock values.

### Technology Stack

* TypeScript for scripts, schemas, view models, and React components.
* React 19 with existing local components and Tailwind CSS 4 classes.
* Vitest and Testing Library for script, schema, view-model, and component coverage.
* Existing Playwright e2e route coverage for browser-visible Trend Finder scheduler/run surfaces.

***

## 6. Deliverables

### Files to Create

| File | Purpose                                                                     | Est. Lines |
| ---- | --------------------------------------------------------------------------- | ---------- |
| None | This session extends existing Trend Finder scheduler and run-control paths. | \~0        |

### Files to Modify

| File                                                                         | Changes                                                            | Est. Lines |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
| `scripts/extensions/trend-finder/spend-accounting.ts`                        | Add reusable bounded pre-run spend/cadence estimate helpers.       | \~80       |
| `scripts/lib/trend-finder-scheduler-status.ts`                               | Add script-side pre-run estimate payload to scheduler status.      | \~120      |
| `src/extensions/trend-finder/scheduler-status.ts`                            | Add browser schema/defaults/types for pre-run estimate.            | \~90       |
| `src/extensions/trend-finder/view-model.ts`                                  | Add formatting and tone projection for pre-run estimate.           | \~100      |
| `src/extensions/trend-finder/run-control.ts`                                 | Add optional pre-run estimate presentation to run-control model.   | \~50       |
| `src/extensions/trend-finder/components/scheduler-first-run-panel.tsx`       | Render pre-run spend, cadence, and wall-clock estimate.            | \~60       |
| `src/extensions/trend-finder/components/trend-run-control.tsx`               | Render pre-run estimate before manual run action.                  | \~60       |
| `src/extensions/trend-finder/components/__tests__/scheduler-status.test.tsx` | Cover schema, view-model, and component estimate states.           | \~120      |
| `scripts/lib/__tests__/trend-finder-scheduler-status.test.ts`                | Cover script-side missing-cost and paid-source estimate cases.     | \~100      |
| `scripts/lib/__tests__/trend-finder-scheduler-status-bridge.test.ts`         | Prove bridge response includes safe pre-run estimate headers/body. | \~40       |
| `docs/extensions/trend-finder-pipeline.md`                                   | Document estimate behavior as implemented when session ships.      | \~30       |
| `docs/extensions/trend-finder-ui-surfaces.md`                                | Document scheduler and run-control estimate surfaces.              | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] A pre-run spend/cadence/wall-clock estimate renders before execution in scheduler first-run and run-control surfaces.
* [ ] Missing-cost states render as unavailable or partial estimates, not zero spend unless the source is explicitly not-applicable.
* [ ] Configured paid-source cases use existing estimated/max-charge fields and cadence projection.
* [ ] Post-run actual-spend accounting and labels remain unchanged.
* [ ] UI copy labels the projection as an estimate and does not imply a hard spend cap.

### Testing Requirements

* [ ] Unit tests written and passing for script-side projection states.
* [ ] Component/view-model tests cover configured paid-source, missing-cost, and legacy payload defaults.
* [ ] Browser-visible scheduler/run-control validation completed or covered by existing focused e2e route tests.
* [ ] Manual testing completed for first-run, configured paid-source, and missing-cost states.

### Non-Functional Requirements

* [ ] Browser payload remains within the 1 MB budget.
* [ ] No token, raw provider response, private cache path, scheduler log path, or generated private artifact reaches browser-visible estimate data.
* [ ] Estimate copy stays compact and scannable in the existing dense Trend Finder operational UI.

### Quality Gates

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

***

## 8. Implementation Notes

### Key Considerations

* Wall-clock projection should use safe prior scheduler facts when available, such as last completed duration, and otherwise show an explicit unavailable state.
* Existing `recurringSpend` should remain intact unless fully migrated with compatibility defaults; prefer additive `preRunEstimate` to reduce regression risk.
* Run-control rendering should handle scheduler status loading, error, and offline states without blocking the manual run readiness model.
* Copy must distinguish "estimated cost" from "maximum charged" and should not introduce a hard cap claim.

### Potential Challenges

* Missing first-run duration: Show an unavailable duration label and keep spend/cadence visible.
* Legacy payload compatibility: Add Zod defaults and fixtures so old generated data parses cleanly.
* UI density: Use compact metric blocks and avoid pushing primary trend content below the fold.
* Privacy drift: Reuse existing sanitized labels and avoid raw runner identifiers in estimate reasons.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: Keep pre-run estimates small, explicit, and within the browser payload limit.
* \[P11] **Scheduler state/log privacy boundary**: Surface only labels, statuses, durations, exit codes, warnings, lock outcomes, and freshness metadata; never raw scheduler logs or paths.
* \[P24] **Browser-safe export and triage boundaries**: Keep raw evidence, private paths, and local triage data out of browser-visible estimate data.
* \[P28] **Direct source fallback labels are release-critical**: Preserve zero-cost public API labels and explicit fallback eligibility.
* \[P28] **Do not treat zero-cost labels as future guarantees**: Label estimate values as projections for the next run, not guarantees for all future runs.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Missing or partial cost data could be misread as zero spend.
* A projection could look like an enforced cap even when the runner does not enforce one.
* Scheduler bridge errors or offline states could hide run readiness or produce blank estimate UI.
* Browser parsing could reject legacy generated data if defaults are incomplete.

***

## 9. Testing Strategy

### Unit Tests

* Test pre-run estimate projection for configured paid sources, missing costs, public no-cost sources, mixed sources, and cadence-unavailable states.
* Test scheduler status payload generation for safe duration, spend, cadence, source count, and unavailable labels.
* Test schema parsing with legacy payloads that do not include `preRunEstimate`.

### Integration Tests

* Test the scheduler status bridge returns pre-run estimate data with no-store and safe headers.
* Test view-model output for scheduler and run-control estimate labels and tones.
* Test component rendering and disabled/loading/offline behavior for scheduler and run-control surfaces.

### Manual Testing

* Open Trend Finder trends and verify the scheduler first-run panel displays estimate values before running.
* Verify manual run control displays estimate copy before the run button is clicked.
* Verify missing generated data and missing-cost paths remain readable and do not show blank metric blocks.

### Edge Cases

* No latest run duration exists.
* Spend summary is absent from generated data.
* Paid source has only max-charge estimate and no actual usage.
* All sources are public/no-cost.
* Scheduler status bridge is offline, loading, or returns an error.
* Legacy live data parses without the new field.

***

## 10. Dependencies

### External Libraries

* None.

### Other Sessions

* **Depends on**: `phase28-session02-delta-aware-enrichment-spend-accounting`, `phase24-session05-scheduler-first-run-live-progress-controls`, `phase29-session14-one-to-watch-surface`.
* **Depended by**: `phase29-session18-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/phase29-session15-pre-run-estimate/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.