> 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/phase33-session03-harden-trend-finder-projection/spec.md).

# Session Specification

**Session ID**: `phase33-session03-harden-trend-finder-projection` **Phase**: 33 - Cloudflare Pages Real Product Fixtures **Status**: Not Started **Created**: 2026-06-25

***

## 1. Session Overview

This session hardens the Trend Finder branch of the Cloudflare Pages public demo snapshot. Sessions 01 and 02 selected and froze a real local run, but the current projection still trims away important Trend Finder product proof: sanitized Engine Replay state, run narratives, industry events, movement analyses, and richer reference-linked evidence.

The session keeps the hosted demo static-only. It improves `scripts/lib/pages-demo-snapshot.ts` so the committed snapshot preserves useful public fields, filters all dependent artifacts against retained topic and evidence IDs, keeps schema-valid provenance states, and fails explicitly when a selected sanitized trace would otherwise be exported as missing.

The result prepares Session 04 to add Dream Review projection and Session 05 to polish public demo UI states without changing hosted runtime behavior, collectors, source adapters, Cloudflare deployment, or Dream output policy.

***

## 2. Objectives

1. Preserve safe Trend Finder demo artifacts with relationship-aware limits and deterministic ordering.
2. Preserve sanitized Engine Replay state when present and fail explicitly when required trace data cannot be exported coherently.
3. Keep public snapshot provenance schema-valid while using labels and notes to explain frozen real demo data and hosted runtime disablement.
4. Add regression coverage proving exported Trend Finder data parses, has positive counts, and has no missing retained references or private leaks.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase33-session01-capture-local-demo-runs` - produced and reviewed the selected local Trend Finder and Dream Review input.
* [x] `phase33-session02-freeze-public-fixtures` - wrote the first committed public fixture set and recorded count deltas showing Trend Finder projection gaps.

### Required Tools Or Knowledge

* Bun 1.3.14 and project scripts from `package.json`.
* Existing Trend Finder schemas in `src/extensions/trend-finder/schema.ts`.
* Existing Engine Replay trace contract in `src/extensions/trend-finder/engine-trace.ts`.
* Existing public demo snapshot exporter and tests under `scripts/lib/`.

### Environment Requirements

* Work from the repository root.
* Do not require Cloudflare credentials, hosted runtime credentials, source collector credentials, or Dream runtime credentials.
* Use committed fixtures and local generated input only; do not run hosted collectors or mutate production state.

***

## 4. Scope

### In Scope (MVP)

* Public demo snapshot exporter preserves retained Trend Finder topics, evidence, sources, watchlist rows, movement rows, prediction/retro/story rows, run narratives, demand clusters, industry events, collection health, backtest aggregate summary, and sanitized Engine Replay state.
* Trend Finder retention is relationship-aware: retained topics choose cited evidence, evidence chooses source summaries, and dependent artifacts are filtered to retained topic and evidence IDs.
* Public snapshot keeps schema-valid provenance values, including `dataState: "fixture-demo"` and `sourceState: "fixture-demo"`, with frozen real demo meaning carried in labels and notes.
* Public snapshot preserves the selected run's valid `analysisState` instead of inventing a new schema value.
* Snapshot exporter rejects or fails explicitly when a selected input has sanitized Engine Replay state that cannot be preserved coherently.
* `scripts/lib/__tests__/pages-demo-snapshot.test.ts` covers positive exported counts, schema parsing through `parseTrendFinderData()`, reference coherence, and privacy rejection for retained Trend Finder artifacts.
* Committed public fixtures and metadata are regenerated after projection hardening so the checked-in demo data matches the hardened exporter.

### Out Of Scope (Deferred)

* Dream Review public projection - Reason: Session 04 owns the Dream allowlist and privacy coverage.
* Public demo UI copy and disabled-control polish - Reason: Session 05 owns user-facing public demo states.
* Cloudflare Pages deployment and hosted smoke testing - Reason: Session 06 owns scan, build, route smoke, and deploy verification.
* New Trend Finder source adapters or hosted collectors - Reason: Phase 33 keeps the Pages demo static-only.
* New provenance state strings - Reason: existing Trend Finder schemas already define the allowed public states.

***

## 5. Technical Approach

### Architecture

Keep all projection logic inside `scripts/lib/pages-demo-snapshot.ts`, using the existing `parseTrendFinderData()` contract as the authoritative parser for Trend Finder browser data. Add small helper functions that first choose retained IDs, then project each dependent artifact through public-safe allowlists and the existing `scrubPublicValue()` privacy boundary.

The exporter should build the public Trend Finder branch in this order: retained topics, cited evidence plus a bounded reserve, retained sources, watchlist and movement rows for retained topics, prediction/retro/story rows for retained topics, run narratives with retained topic/evidence references, demand clusters and industry events with retained references, and finally Engine Replay summaries filtered to the same retained IDs. The final projected branch must parse through `parseTrendFinderData()` before fixture writes.

If the source branch has `engineTrace.state: "sanitized"` and non-empty trace content, the public projection must not silently default to missing trace data. It should preserve a public-safe fixture trace or raise a `PagesDemoSnapshotError` with a clear error code and message.

### Design Patterns

* Parser-backed boundary: Reuse `parseTrendFinderData()` to reject malformed projected data and reference drift.
* Allowlist projection: Preserve only public-safe fields needed by demo surfaces and counts.
* Relationship-aware trimming: Filter dependent arrays by retained IDs instead of independently slicing arrays.
* Static-only fixture generation: Keep `demo:snapshot` separate from Pages build and deployment scripts.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                            | Est. Lines |
| ---- | -------------------------------------------------- | ---------- |
| None | No new source files are required for this session. | \~0        |

### Files To Modify

| File                                                                                          | Changes                                                                                                                                    | Est. Lines |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `scripts/lib/pages-demo-snapshot.ts`                                                          | Add relationship-aware Trend Finder projection helpers, explicit trace failure handling, field policy updates, and final parse validation. | \~220      |
| `scripts/lib/__tests__/pages-demo-snapshot.test.ts`                                           | Add populated Trend Finder fixture coverage, positive count/parsing assertions, reference-coherence tests, and privacy regression tests.   | \~260      |
| `demo-website/public/demo/live-data.snapshot.json`                                            | Regenerate public fixture after hardened Trend Finder projection.                                                                          | generated  |
| `demo-website/public/demo/snapshot-metadata.json`                                             | Regenerate metadata count summary after hardened projection.                                                                               | generated  |
| `demo-website/snapshot-manifest.json`                                                         | Regenerate manifest and Trend Finder field policy after hardened projection.                                                               | generated  |
| `.spec_system/specs/phase33-session03-harden-trend-finder-projection/implementation-notes.md` | Record commands, count deltas, assumptions, and verification results without raw private payload bodies.                                   | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Exported Trend Finder data includes real public evidence titles and URLs.
* [ ] Exported Trend Finder data retains up to 8 ranked topics and up to 32 evidence items using cited evidence first.
* [ ] Exported Trend Finder sources, watchlist rows, movement analyses, prediction/retro/story rows, run narratives, demand clusters, and industry events reference only retained topic and evidence IDs.
* [ ] Exported Engine Replay data preserves trace state, run ID, sections, sources, evidence counts, runtime summary, artifact summaries, decision timeline, stage narrations, topics, and watchlist summaries when present.
* [ ] Exported Trend Finder data parses through `parseTrendFinderData()` with positive counts for trace, source health, topics, evidence, watchlist, and Brief-supporting artifacts.
* [ ] Snapshot provenance remains schema-valid and uses frozen public demo labels or notes instead of new state strings.
* [ ] Private fields, local paths, credentials, raw logs, prompts, provider bodies, protected asset bridge URLs, and token-like strings are removed or rejected.

### Testing Requirements

* [ ] Focused snapshot exporter tests are written and passing.
* [ ] Privacy scan tests are passing.
* [ ] `bun run demo:snapshot --dry-run --json` passes after hardening.
* [ ] `bun run demo:scan:pages --fixtures` passes after fixture regeneration.

### Non-Functional Requirements

* [ ] Projection remains deterministic for repeated dry runs with the same captured timestamp and source commit.
* [ ] Fixture data remains static-only and does not invoke collectors, schedulers, Dream runtime, local bridge endpoints, uploads, analytics, or admin mutations.
* [ ] Trend Finder browser payload remains bounded by existing schema limits and public demo payload budget expectations.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces are unchanged in this session.

***

## 8. Implementation Notes

### Working Assumptions

* The repository is not a monorepo. Evidence: `analyze-project.sh --json` returned `monorepo: null`, empty `packages`, and `detected: false`; planning can proceed without package scoping.
* Session 03 is the next executable session. Evidence: the analysis script reports `phase33-session01-capture-local-demo-runs` and `phase33-session02-freeze-public-fixtures` complete, with Session 03 as the first incomplete candidate.
* The selected local input contains sanitized Trend Finder Engine Replay data. Evidence: Session 02 implementation notes recorded input `engineTrace.state` as `sanitized` with non-empty decisions, sources, artifacts, sections, narrations, topics, and watchlist rows. Planning can proceed because the exporter will fail explicitly if implementation finds that required trace shape is no longer present.
* Existing Trend Finder schemas are authoritative. Evidence: `src/extensions/trend-finder/schema.ts` already validates cross-references for demand clusters, industry events, and run narratives, and imports the Engine Replay schema.

### Conflict Resolutions

* Session 02 already regenerated public fixtures, while Session 03 focuses on projection policy. The chosen interpretation is to regenerate the committed fixtures again after hardening because Pages consumes committed static fixtures and the fixture must reflect the hardened exporter output.
* The session requires frozen real demo meaning, but Trend Finder schema values should stay stable. The chosen interpretation is to keep schema-valid states such as `fixture-demo` and carry frozen real meaning in labels and notes, matching the Phase 33 stub and avoiding a schema migration.

### Key Considerations

* Keep generated private runtime data out of git.
* Keep Trend Finder as a repo-local extension inside AI OS.
* Keep Cloudflare Pages public demo static-only.
* Avoid route or component changes in this session.

### Potential Challenges

* Relationship-aware trimming can accidentally remove evidence needed by a retained artifact. Mitigation: add parser-backed coherence tests and validate after projection.
* Engine Replay contains many nested summaries. Mitigation: project public-safe summary fields and reuse the Engine Replay schema instead of copying raw traces.
* Privacy scans may reject useful text from real artifacts. Mitigation: keep allowlists narrow, scrub text through existing helpers, and record count-only review notes.

### Relevant Considerations

* \[P31/P32] **Pages demo stays static-only**: Projection hardening must not add `/__*` bridge calls, hosted writes, collectors, analytics, Pages Functions, or advanced Workers.
* \[P31/P32] **Public-demo release gates stay bundled**: This session adds exporter and fixture evidence that Session 06 will include in the final scan, build, smoke, budget, and deployment gate bundle.
* \[P24] **Browser-safe export and triage boundaries**: Public fixture output must keep local triage notes, private paths, and raw evidence out of browser-visible data.
* \[P02] **Extension payloads and labels stay bounded**: Retained artifacts must remain bounded and explicitly labeled as fixture/demo/frozen public output.
* \[P29] **Comparison adoption works when ideas become bounded projections**: Advanced artifacts should be bounded projections from existing evidence, not new source risk.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Relationship drift after trimming retained topics, evidence, and dependent artifacts.
* Silent fallback from sanitized Engine Replay data to missing trace output.
* Private local paths, prompts, provider bodies, token-like strings, or protected bridge URLs leaking through newly retained fields.

***

## 9. Testing Strategy

### Unit Tests

* Add a populated Trend Finder fixture in `scripts/lib/__tests__/pages-demo-snapshot.test.ts` with multiple topics, cited evidence, sources, watchlist rows, movement analyses, run narratives, industry events, and sanitized Engine Replay state.
* Assert projected data parses through `parseTrendFinderData()` and has positive counts for retained artifacts.
* Assert dependent artifacts reference only retained topic, evidence, and source IDs after trimming.
* Assert private field, local path, prompt/provider body, protected bridge URL, and token-like string regressions are removed or rejected.

### Integration Tests

* Run `bun run test -- scripts/lib/__tests__/pages-demo-snapshot.test.ts scripts/lib/__tests__/pages-demo-privacy-scan.test.ts`.
* Run `bun run demo:snapshot --dry-run --json` to verify end-to-end projection without writing files.
* Run `bun run demo:scan:pages --fixtures` after regenerating committed public fixtures.

### Runtime Verification

* Inspect count summaries in `demo-website/public/demo/snapshot-metadata.json` and `demo-website/snapshot-manifest.json` for non-empty Trend Finder trace and artifact counts.
* Inspect `demo-website/public/demo/live-data.snapshot.json` with count-only queries; do not print raw private payload bodies in session notes.

### Edge Cases

* Input contains sanitized trace data but the projection cannot preserve it.
* Input contains dependent artifact references to trimmed topics or evidence.
* Input contains more than the retention caps for topics, evidence, sources, movement rows, prediction/retro/story rows, narratives, clusters, or events.
* Input contains local paths, provider text, prompts, credential-like strings, or protected asset bridge URLs in newly retained fields.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase33-session01-capture-local-demo-runs`, `phase33-session02-freeze-public-fixtures`.
* Depended by: `phase33-session04-harden-dream-projection`, `phase33-session05-polish-public-demo-ui-states`, `phase33-session06-scan-build-and-deploy`.

***

## Next Steps

Run the `implement` workflow step to begin 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/phase33-session03-harden-trend-finder-projection/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.