> 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-session06-cross-topic-substrate-narratives/spec.md).

# Session Specification

**Session ID**: `phase29-session06-cross-topic-substrate-narratives` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-20

***

## 1. Session Overview

This session adds bounded cross-topic substrate narratives to Trend Finder runs. Sessions 02 through 05 added topic-level derived fields for attention, reception, corroboration, and per-evidence rationale. Session 06 now adds the missing run-level synthesis layer: concise narratives that describe patterns shared by two or more real topics without becoming loose editorial summaries or new theme labels.

The implementation should publish a single additive report-level field named `runNarratives`. Each narrative must cite at least two valid topic IDs and only existing topic/evidence references. AI-authored narratives are allowed only after validation; deterministic fallback narratives must be low-confidence and derived from existing theme labels plus shared source, entity, and keyword tokens.

The result should stay inside the existing local Trend Finder privacy boundary. No new source, social reach, comment body, transcript, media, hosted storage, database, or third-party transfer is introduced. Browser and static Brief surfaces receive only bounded display text, safe IDs, confidence labels, and validated references.

***

## 2. Objectives

1. Add a legacy-safe `runNarratives` report field for bounded cross-topic narratives.
2. Extend analyst output and validation so AI narratives cite at least two existing topic IDs and valid evidence IDs.
3. Implement deterministic low-confidence fallback narratives from theme labels and shared source/entity tokens.
4. Surface validated narratives in live Trend Finder summary surfaces and static Brief output without raw/private leakage.
5. Add focused tests for reference validation, fallback behavior, schema defaults, rendering, payload size, and privacy safety.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session05-per-evidence-rationale` - Provides the citation-validation discipline and evidence grounding pattern reused by this session.
* [x] `phase29-session04-corroboration-gate` - Provides current multi-origin caution language and validated source identity context.
* [x] `phase27-session11-theme-rollups-and-outlier-ideas` - Provides existing topic theme labels and deterministic theme grouping inputs.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing theme assignment in `scripts/extensions/trend-finder/theme-rollups.ts`.
* Existing analyst output validation in `scripts/lib/ai-runtime/trend-analyst.ts`.
* Existing Trend Finder schema, view-model, and static Brief projection boundaries.
* Payload-size and static Brief QA utilities for browser-safe output checks.

### Environment Requirements

* Project dependencies installed with Bun.
* `src/data/live-data.example.json` available for fixture and schema validation.
* No new source compliance approval is required because this session reuses already-generated public evidence and topic data.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can publish run-level substrate narratives - Add additive `runNarratives` rows over already-generated topics.
* Each narrative cites real references - Require at least two valid topic IDs and only existing topic/evidence IDs before publication.
* AI output is bounded and validated - Extend analyst output with short narrative title/summary, confidence, topic IDs, and evidence IDs, then reject invented IDs, URLs, dates, source names, and metrics.
* Deterministic fallback works without AI - Build low-confidence rows from existing theme labels plus shared source/entity/keyword tokens.
* Browser payload stays safe - Add schema defaults, length caps, confidence caps, and privacy-safe warnings.
* Operators can read the synthesis - Surface narratives in live Trend Finder summary areas and static Brief output with concise copy and validated citations.
* Release checks prove behavior - Add tests for invalid references, low-confidence fallback, legacy parsing, static rendering, payload budget, and private/raw leak prevention.

### Out of Scope (Deferred)

* New theme or demand-center computation - Reason: this session reuses existing theme labels, groups, and topic/evidence data.
* Narratives with fewer than two valid topic IDs - Reason: those are dropped, not repaired or invented.
* New source collection, social reach, comments, podcasts, transcripts, media embeds, or unreviewed source names - Reason: those remain compliance-gated or explicit Phase 29 non-goals.
* Changing topic scores, action verdicts, or corroboration formulas based on narratives - Reason: narratives are explanatory synthesis, not a new ranking signal.
* Long-form editorial report generation - Reason: the MVP is bounded rows suitable for dense dashboard and static Brief surfaces.

***

## 5. Technical Approach

### Architecture

Create a focused `run-narratives` helper under `scripts/extensions/trend-finder/`. It should own the run narrative contract, fallback derivation, reference validation, issue codes, and deterministic ID generation. Inputs should be already-projected topics, evidence, sources, and theme rollup groups. Outputs should be bounded rows plus safe warnings.

Extend `trend-analyst.ts` so optional analyst output can include `runNarratives`. Analyst validation should require every cited topic ID to be present in the output topics, every cited evidence ID to exist and belong to at least one cited topic where possible, and every row to have at least two valid topic IDs. The validation should reuse the Session 05 public-copy and invented metadata checks for URLs, dates, source names, metrics, and unsupported claims.

Wire narrative generation after theme rollups are assigned and before final browser/static export. Valid AI narratives should win when they pass reference and public-copy validation. Deterministic fallback narratives should fill safe gaps from multi-topic theme groups and shared source/entity tokens, with `confidence` capped to a low band and provenance marked as fallback. Invalid rows are dropped with sanitized warning codes.

Add legacy-safe schema defaults to `src/extensions/trend-finder/schema.ts`. Project `runNarratives` through `view-model.ts` into compact display rows for live Trend Finder pages and static Brief output. Static rendering must escape all text through existing helpers and avoid private paths, raw provider output, prompts, comments, transcripts, source dumps, or unreviewed media.

### Design Patterns

* Additive schema evolution: Legacy payloads parse with `runNarratives: []`.
* Boundary-nearest validation: Analyst rows are rejected before scoring, browser payload, or static export.
* Deterministic fallback before AI enrichment: Useful low-confidence synthesis exists without optional analyst output.
* Projection over source expansion: Narratives summarize existing safe data and do not widen collection.
* Bounded browser projection: Publish short display fields and validated IDs, not raw source material.

### Technology Stack

* TypeScript and Zod for runtime contracts and schema defaults.
* Bun and Vitest for script/runtime tests.
* React 19 view-model and route/component tests with happy-dom.
* Existing static Brief export, renderer, QA, and payload-size utilities.

***

## 6. Deliverables

### Files to Create

| File                                                               | Purpose                                                                                                 | Est. Lines |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/run-narratives.ts`                | Run narrative types, validator, deterministic fallback builder, warning codes, and merge policy.        | \~260      |
| `scripts/extensions/trend-finder/__tests__/run-narratives.test.ts` | Unit coverage for valid references, invalid reference drops, fallback low confidence, and bounded text. | \~240      |

### Files to Modify

| File                                                                      | Changes                                                                                                                   | Est. Lines |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/trend-analyst.ts`                                 | Add optional analyst `runNarratives` schema, prompt guidance, public-copy checks, and reference validation.               | \~180      |
| `scripts/extensions/trend-finder/collector.ts`                            | Generate and attach validated run narratives after theme rollups with sanitized warnings and trace metadata.              | \~120      |
| `scripts/extensions/trend-finder/theme-rollups.ts`                        | Export or adapt theme group inputs needed by deterministic narrative fallback without changing topic assignment behavior. | \~50       |
| `src/extensions/trend-finder/schema.ts`                                   | Add narrative constants, Zod schema, report field defaults, and legacy-safe parsing.                                      | \~130      |
| `src/extensions/trend-finder/view-model.ts`                               | Project run narratives into compact display rows with labels, tones, citations, and safe empty states.                    | \~120      |
| `src/extensions/trend-finder/views/trends-view.tsx`                       | Render narrative summary rows with accessible labels and stable loading/empty/legacy states.                              | \~70       |
| `src/extensions/trend-finder/views/brief-view.tsx`                        | Render narrative rows in the live Brief summary without burying ranked trend content.                                     | \~60       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Include bounded narrative rows in the static Brief report model with validated citations only.                            | \~80       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render escaped narrative rows and citation labels in static Brief output.                                                 | \~70       |
| `scripts/extensions/trend-finder/static-brief-qa.ts`                      | Ensure narrative text is covered by existing private/raw leak scans.                                                      | \~30       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                 | Keep narrative fields visible in payload reporting and budget checks.                                                     | \~20       |
| `src/extensions/trend-finder/fixtures.ts`                                 | Add fixture narratives for AI-valid, fallback, and invalid-reference cases.                                               | \~80       |
| `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts`                  | Cover analyst narrative acceptance, unknown topic/evidence rejection, and unsupported claim rejection.                    | \~120      |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts`             | Cover collector attachment, warning behavior, and fallback when analyst output is unavailable.                            | \~110      |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover schema defaults, view-model projection, citation labels, and empty states.                                          | \~90       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`   | Cover static export model rows and private/raw field exclusion.                                                           | \~80       |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover escaped narrative rendering and citation output.                                                                    | \~70       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `runNarratives` defaults to an empty array for legacy payloads.
* [ ] A narrative with fewer than two valid topic IDs is dropped.
* [ ] A narrative that cites an unknown topic ID or evidence ID is dropped with a sanitized warning.
* [ ] A deterministic fallback emits only low-confidence rows and only from existing topic/theme/evidence data.
* [ ] Valid AI narratives pass only when their topic/evidence references and public copy are grounded.
* [ ] Live Trend Finder and static Brief surfaces render concise narrative rows with safe citation labels.

### Testing Requirements

* [ ] Unit tests written and passing for narrative validation, fallback derivation, and merge/drop behavior.
* [ ] Analyst validator tests cover accepted grounded narratives, unknown references, and unsupported public-copy claims.
* [ ] Schema/view-model/view tests cover legacy defaults, citation labels, empty state, and accessibility text.
* [ ] Static Brief export/renderer/QA tests cover escaped output and private/raw leak prevention.
* [ ] Payload-size check confirms the extension remains under the 1 MB boundary.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] Static Brief and live browser payloads do not expose raw source dumps, private paths, prompts, provider responses, raw model output, comments, transcripts, credentials, or unreviewed media.
* [ ] No new source, collector, media boundary, database, hosted storage path, dependency, or third-party transfer is introduced.
* [ ] Fallback rows are deterministic, low-confidence, bounded, and stable across repeated runs on the same inputs.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] New enum or schema branches use explicit fallback behavior.

***

## 8. Implementation Notes

### Key Considerations

* The public field should be one concept, `runNarratives`, to avoid parallel names such as both `runNarratives` and `themeNarratives`.
* Fallback narratives should prefer topic groups that already have at least two topics and shared tokens; single-topic themes must not publish.
* The helper should return explicit warning codes for dropped analyst rows so implementation notes can record why rows were excluded without leaking raw output.
* Narrative copy must stay short enough for dense dashboard surfaces and static Brief cards.
* Static Brief export should receive projected safe narrative text, not raw analyst output.

### Potential Challenges

* Analyst rows may cite valid topics but unsupported evidence. Mitigation: require evidence IDs to exist and prefer citations already linked to cited topics.
* Fallback grouping may be too generic. Mitigation: reject generic labels and require shared source/entity/keyword evidence before publishing.
* Payload pressure could grow if narratives include many citations. Mitigation: cap narrative count, cited topic IDs, evidence IDs, title length, and summary length.
* UI density could suffer. Mitigation: render compact rows below primary ranked-trend context and keep empty states quiet.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: Narrative rows must be capped, defaultable, and measured against the 1 MB payload budget.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must exclude raw evidence dumps, private paths, local triage notes, prompts, provider responses, and credentials.
* \[P27] **Deterministic fallback before AI enrichment**: Fallback narrative generation must work before and without optional analyst output.
* \[P28] **Direct public source scope is narrow**: This session adds no source and does not widen deferred social or media candidates.
* \[P28] **Trend Finder release validation is bundled**: Payload, privacy, docs/reference checks, and scoped formatting evidence should be recorded during implementation and closeout.
* \[P00] **Do not document planned features as implemented**: Any docs changed during implementation must describe shipped narrative behavior only after code lands.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* A narrative invents a topic, evidence item, date, URL, source name, or metric and still reaches browser-visible output.
* Deterministic fallback publishes a confident-looking story from one topic or weak shared tokens.
* Legacy payloads without `runNarratives` break Trends, Brief, or static Brief rendering.

***

## 9. Testing Strategy

### Unit Tests

* Add `run-narratives` helper tests for valid two-topic rows, invalid one-topic rows, unknown topic IDs, unknown evidence IDs, generic labels, text caps, and fallback low-confidence rows.
* Add analyst validator tests for accepted grounded narratives, invalid references, unsupported source/date/URL/metric claims, and public-copy voice checks.
* Add collector tests proving valid AI rows attach, invalid AI rows drop with warnings, fallback rows publish without analyst output, and raw evidence remains unchanged.

### Integration Tests

* Add schema tests for legacy payload defaults and invalid narrative payload fallback.
* Add view-model and view tests for citation labels, accessibility text, empty-state behavior, and compact rendering.
* Add static Brief export/renderer/QA tests for escaped narrative markup and no private path/raw output leakage.
* Add payload-size validation to confirm narrative fields stay within the extension budget.

### Manual Testing

* Generate or load fixture Trend Finder data and inspect `/extensions/trend-finder/trends` for compact substrate narrative rows.
* Inspect `/extensions/trend-finder/brief` to confirm narratives support the run summary without displacing ranked trends.
* Export a static Brief and confirm narrative rows render with cited topic/evidence labels and no raw/private fields.

### Edge Cases

* Legacy payload has no `runNarratives` field.
* Analyst row cites only one topic.
* Analyst row cites a topic ID not present in the run.
* Analyst row cites evidence not present in the evidence collection.
* Shared theme group has two topics but no meaningful shared token.
* All topics are singletons or generic themes.
* Narrative count or citation count exceeds caps.

***

## 10. Dependencies

### External Libraries

* None. This session should not add dependencies.

### Other Sessions

* **Depends on**: `phase29-session05-per-evidence-rationale`, `phase29-session04-corroboration-gate`, and the Phase 27 theme-rollup foundation.
* **Depended by**: `phase29-session08-required-derived-field-closeout-gate`, `phase29-session13-static-brief-archival-and-richness`, and `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-session06-cross-topic-substrate-narratives/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.