> 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-session04-harden-dream-projection/spec.md).

# Session Specification

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

***

## 1. Session Overview

This session adds the deliberately small Dream Review branch to the static Cloudflare Pages public demo snapshot. Sessions 01 through 03 captured and froze reviewed local output, then hardened the Trend Finder projection; the remaining public fixture gap is that the committed Pages snapshot still exports `dream: null` even though the local generated input has a populated Dream Review output.

The session keeps Dream Review static-only and browser-safe. It does not run Dream Review during Pages builds, expose private Dream files directly, add hosted Dream controls, or polish hosted UI labels. Instead it extends the snapshot exporter with a narrow allowlist, privacy scanning, metadata count summaries, and tests proving the exported shape still works with the existing home-dashboard Dream transforms.

The result prepares Session 05 to present Dream Review as a frozen real local snapshot in public demo mode and Session 06 to run final scan, build, route smoke, and deployment gates.

***

## 2. Objectives

1. Preserve a bounded public-safe Dream Review projection in the committed Pages demo snapshot when reviewed Dream prescriptions are present.
2. Drop or reject private Dream fields, provider/model/runtime metadata, raw prompts, raw logs, local paths, credentials, and token-like strings.
3. Update snapshot manifest and metadata so Dream field policy and count summaries describe the exported allowlist instead of a deferred null branch.
4. Add positive and negative regression coverage proving the public Dream projection parses, scans cleanly, and drives `deriveDreamData()`.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase33-session01-capture-local-demo-runs` - produced and reviewed the local Trend Finder and Dream Review candidate output.
* [x] `phase33-session02-freeze-public-fixtures` - established committed Pages fixtures, snapshot metadata, and Dream field-policy entries.
* [x] `phase33-session03-harden-trend-finder-projection` - hardened Trend Finder projection and preserved public-demo static-only boundaries.

### Required Tools Or Knowledge

* Bun 1.3.14 and project scripts from `package.json`.
* Existing Dream contracts in `scripts/lib/dream/contracts.ts` and validation behavior in `scripts/lib/dream/output-validation.ts`.
* Existing public demo snapshot exporter in `scripts/lib/pages-demo-snapshot.ts`.
* Existing home dashboard Dream transform behavior in `src/lib/home-transforms.ts` and `src/lib/transforms/dream.ts`.

### Environment Requirements

* Work from the repository root.
* Do not require Cloudflare credentials, hosted runtime credentials, source collector credentials, account auth, or Dream runtime credentials.
* Use committed fixtures and local generated input only; do not run Dream Review, collectors, schedulers, bridge endpoints, uploads, analytics, or admin mutations during this session.

***

## 4. Scope

### In Scope (MVP)

* `scripts/lib/pages-demo-snapshot.ts` projects `input.dream` through a bounded allowlist instead of always writing `dream: null`.
* The public Dream projection preserves top-level `generatedAt`, plus `date` or `lastRun` only when useful and safe for UI labels.
* Each retained prescription preserves safe `id`, `title`, `summary`, `rationale`, `nextAction`, `priority`, `tags`, `evidence`, `command`, `dollarImpact`, and `timeImpactMins` when each field passes public privacy scanning.
* The projection drops `model`, provider labels, runtime metadata, raw material, prompts, request context, output paths, warnings, diagnostics, local paths, token-like strings, and private fields.
* The projection keeps the prescription array bounded by the Dream contract and deterministic for repeated snapshot runs.
* Snapshot metadata and `demo-website/snapshot-manifest.json` include Dream allowlist field policy, count summary, and frozen public-demo labels.
* Focused tests cover safe Dream projection, empty/unavailable fallback, private-field rejection or removal, token/path/prompt/provider leak prevention, and home transform compatibility.
* Committed public fixtures are regenerated after projection hardening.

### Out Of Scope (Deferred)

* Public demo UI copy, disabled Dream run controls, and route-state polish - Reason: Session 05 owns public demo UI states.
* Cloudflare Pages build, route smoke, budget, and deployment verification - Reason: Session 06 owns final release gates.
* Running Dream Review during Cloudflare Pages builds - Reason: Pages remains a static fixture deployment.
* Exposing private Dream output files directly - Reason: the public contract is the committed `demo/live-data.snapshot.json` projection.
* Adding hosted Dream runtime, hosted run controls, collector actions, scheduler actions, uploads, analytics, or writes - Reason: Phase 33 keeps the public demo static-only.

***

## 5. Technical Approach

### Architecture

Keep the projection boundary inside `scripts/lib/pages-demo-snapshot.ts`, next to the existing Trend Finder public projection. Add a small Dream-specific projector that accepts the validated `LiveData.dream` branch, reads only allowlisted fields, passes all strings through the existing `collectPublicDemoPrivacyIssues()` and redaction counters, and returns either a minimal Dream object or `null`.

The projector should build the Dream branch in this order: safe generated timestamp, optional safe date or last-run label, bounded prescriptions, then final validation through `validateLiveData()`. Tests should additionally call `deriveDreamData()` against the projected `LiveData` so the home dashboard consumer is verified without adding UI behavior to this session.

The snapshot manifest and metadata should derive Dream counts from the projected branch: exported/not-exported state, prescription count, evidence line count, tag count, present impact fields, and generated timestamp presence. The field policy should move from deferred unavailable language to allowlisted frozen-demo language when Dream data is exported.

### Design Patterns

* Allowlist projection: Preserve only fields explicitly needed by public demo surfaces and home dashboard transforms.
* Privacy scan at projection time: Treat unsafe strings as redacted or rejectable before fixture files are written.
* Parser-backed LiveData boundary: Use `validateLiveData()` after projection to keep the public snapshot shape compatible with the app.
* Transform-backed consumer proof: Use `deriveDreamData()` in focused tests to prove exported prescriptions become dashboard-ready suggestions.
* Static-only fixture generation: Keep Dream runtime, bridge reads, and hosted mutation paths out of public demo generation.

***

## 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 Dream allowlist projection, privacy handling, count summary updates, and field policy updates.                         | \~180      |
| `scripts/lib/__tests__/pages-demo-snapshot.test.ts`                                    | Add safe Dream fixture coverage, privacy regression tests, empty fallback tests, and transform compatibility assertions.   | \~240      |
| `src/lib/__tests__/home-transforms.test.ts`                                            | Add or adjust focused Dream transform coverage if exporter tests do not already cover the public projection consumer path. | \~80       |
| `demo-website/public/demo/live-data.snapshot.json`                                     | Regenerate public fixture after hardened Dream projection.                                                                 | generated  |
| `demo-website/public/demo/snapshot-metadata.json`                                      | Regenerate metadata count summary and Dream field policy.                                                                  | generated  |
| `demo-website/snapshot-manifest.json`                                                  | Regenerate manifest count summary and Dream field policy.                                                                  | generated  |
| `.spec_system/specs/phase33-session04-harden-dream-projection/implementation-notes.md` | Record commands, count deltas, projection decisions, and verification results without raw private Dream content.           | \~120      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Public snapshot contains a non-null Dream branch when local generated Dream Review data is populated and passes privacy projection.
* [ ] Safe Dream titles, summaries, rationales, next actions, priorities, tags, evidence lines, commands, dollar impact, and time impact survive when present.
* [ ] Current local Dream candidate with 4 prescriptions can project into committed public fixtures without exposing raw private content.
* [ ] Empty or unsafe Dream input falls back to an unavailable public snapshot state instead of leaking private output.
* [ ] Private Dream fields, local paths, raw logs, prompts, provider bodies, model names, runtime diagnostics, credentials, and token-like strings are removed or rejected.
* [ ] Dream projection output remains compatible with `validateLiveData()`, `transformDream()`, and `deriveDreamData()`.
* [ ] Snapshot manifest and metadata accurately report Dream count summary and allowlisted field policy.

### Testing Requirements

* [ ] Focused snapshot exporter tests are written and passing.
* [ ] Focused Dream transform tests are written or exporter tests prove transform compatibility.
* [ ] Privacy scan tests are passing for Dream leak cases.
* [ ] `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.
* [ ] Public demo remains static-only and does not invoke collectors, schedulers, Dream runtime, local bridge endpoints, uploads, analytics, or admin mutations.
* [ ] Dream public payload remains small, bounded, and limited to fields needed by public demo and home dashboard presentation.

### 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 04 is the next executable session. Evidence: deterministic analysis reported Phase 33 in progress, completed sessions 01 through 03, no active current session, and Session 04 as the earliest incomplete candidate.
* The current local Dream candidate is suitable as projection input after allowlist scanning. Evidence: `src/data/live-data.json` has a Dream branch with `generatedAt`, `date`, and 4 prescriptions whose current key set is `id`, `title`, `summary`, `rationale`, `nextAction`, `priority`, and `tags`; the public fixture currently exports `dream: null`.
* Impact, evidence, and command fields are optional in the current local candidate. Evidence: the Session 04 stub requires preserving those fields when safe, while the current generated key set does not include them; planning can proceed by implementing optional preservation and tests with fixture data that includes those fields.

### Conflict Resolutions

* The Session 04 stub asks to preserve safe Dream fields, while the current manifest says Dream projection is deferred to this same session. Chosen interpretation: update the exporter and manifest policy in this session so Dream becomes `allowlisted` when data is exported. Evidence: Phase 33 PRD lists Session 04 as "Add an allowlisted Dream Review projection", and the current manifest reason explicitly names this session as the deferred allowlist work.
* The Phase 33 plan requires realistic frozen Dream Review output, but Session 05 owns public demo UI labels. Chosen interpretation: Session 04 changes fixture data, metadata, tests, and projection policy only; user-facing copy and disabled-control polish remain deferred. Evidence: Session 05 stub explicitly owns Dream Review provenance labels, run-button behavior, and empty states.

### Key Considerations

* Keep Dream Review public data smaller than private `DreamOutput`.
* Do not rely on private Dream output files at runtime or during Pages builds.
* Do not log or document raw Dream prescription bodies in implementation notes.
* Keep the public demo honest: data can be frozen and useful, but runtime execution stays disabled on hosted Pages.

### Potential Challenges

* Optional field drift: Use allowlist helpers that tolerate missing optional fields and preserve them only when safe.
* False-positive privacy scans: Prefer dropping unsafe optional fields over weakening scan patterns.
* Home transform mismatch: Verify `deriveDreamData()` against the projected fixture shape before regenerating committed files.

### Relevant Considerations

* \[P31/P32] **Pages demo stays static-only**: This session must not add `/__*` bridge calls, hosted writes, collectors, analytics, Functions, or advanced Workers.
* \[P31/P32] **Public-demo release gates stay bundled**: Keep fixture projection work compatible with later `demo:build:pages`, `demo:scan:pages`, route smoke, and budget gates.
* \[P31] **Static public-demo projection scales**: Continue using `VITE_AI_OS_PUBLIC_DEMO`, allowlist-first fixtures, and Pages dist assembly instead of hosted runtime reads.
* \[P31] **Metadata-backed provenance beats diagnostics**: Use metadata and count summaries to explain capture state without exposing private Dream diagnostics.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Privacy leak risk from raw Dream fields, local paths, prompts, provider text, model names, logs, and token-like strings.
* Empty or partial Dream input causing the hosted demo to look broken instead of intentionally unavailable.
* Projected Dream prescriptions drifting away from the home dashboard transform shape.

***

## 9. Testing Strategy

### Unit Tests

* Add `pages-demo-snapshot` tests for safe Dream projection, deterministic counts, field policy changes, generated timestamp preservation, optional field preservation, and `validateLiveData()` success.
* Add `pages-demo-snapshot` negative tests for private Dream fields, local paths, raw prompts, raw logs, provider/model metadata, bridge URLs, credential-shaped strings, and token-like strings.
* Add or adjust `home-transforms` tests to prove projected Dream prescriptions become dashboard suggestions.

### Integration Tests

* Run the focused snapshot exporter and privacy scan tests together.
* Run `bun run demo:snapshot --dry-run --json` before fixture writes.
* Run `bun run demo:scan:pages --fixtures` after fixture regeneration.

### Runtime Verification

* Inspect regenerated `demo-website/public/demo/live-data.snapshot.json` for a bounded Dream branch and no private Dream metadata.
* Inspect regenerated `demo-website/snapshot-manifest.json` and `demo-website/public/demo/snapshot-metadata.json` for exported Dream counts and allowlisted field policy.

### Edge Cases

* Dream branch missing or `null`.
* Dream branch present with empty prescriptions.
* Prescription present but missing optional fields.
* Prescription with unsafe optional strings.
* Prescription with local path, prompt marker, provider body, model metadata, raw logs, bridge URL, or token-like string.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase33-session01-capture-local-demo-runs`, `phase33-session02-freeze-public-fixtures`, `phase33-session03-harden-trend-finder-projection`.
* Depended by: `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-session04-harden-dream-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.