> 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-session11-industry-events-rollup/spec.md).

# Session Specification

**Session ID**: `phase29-session11-industry-events-rollup` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-21

***

## 1. Session Overview

This session adds a bounded industry-events rollup to Trend Finder using only the existing `rss-ai-news` and `google-ai-news` news evidence paths. It borrows the useful "what happened in the industry this cycle" lens from the TrendingAI comparison without adding podcasts, social sources, transcript processing, or a new collection boundary.

The implementation should cluster current news evidence into event rows, require at least two independent publishers before an event is published, and cite only real evidence IDs from the generated payload. It should reuse the Session 04 corroboration model and existing browser-safe publisher metadata from `sourceLocal.entityKind: "publisher"` where possible, with URL-host fallback only when the existing metadata is absent.

The result should be visible in the browser-safe payload, live view model, and static Brief as a compact cycle-level lens. Single-publisher events must be suppressed, AI-produced event copy must be validator-gated with deterministic fallback, and payload/privacy checks must remain green.

***

## 2. Objectives

1. Derive bounded `industryEvents` rows from existing news evidence only.
2. Require two independent publishers for every published event row.
3. Provide deterministic shared-token clustering and fallback summaries when no AI runtime is available or accepted.
4. Add schema defaults, view-model projection, and static Brief rendering for industry events.
5. Prove single-publisher suppression, two-publisher publication, privacy cleanliness, and payload budget behavior with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session04-corroboration-gate` - Provides the corroboration model and originator-only caution this session reuses.
* [x] `phase28-session14-direct-first-party-source-adapters` - Provides the reviewed RSS and Google News direct adapter paths.
* [x] `phase29-session08-required-derived-field-closeout-gate` - Provides the generated-payload closeout pattern for required derived branches.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing news evidence normalization in `scripts/extensions/trend-finder/normalize.ts`.
* Existing corroboration helper in `scripts/lib/ai-runtime/corroboration.ts`.
* Existing demand-cluster pattern in `scripts/extensions/trend-finder/demand-clusters.ts`.
* Existing static Brief projection, renderer, QA, and payload-size scripts.

### Environment Requirements

* Project dependencies installed with Bun.
* No new source, credential, media, database, hosted storage, dependency, or third-party transfer approval is required.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can derive industry events from existing news adapters - Select only `rss-ai-news` and `google-ai-news` evidence with validated filters and explicit unavailable states.
* Event rows explain why they publish - Include title, summary, publisher count, cited evidence IDs, related topic IDs, provenance labels, and reason codes.
* Two independent publishers are required - Reuse publisher source-local metadata and corroboration-style entity evidence to suppress single-publisher events.
* Deterministic fallback is complete - Cluster on shared entity/title tokens and build bounded fallback summaries without AI runtime availability.
* Optional AI copy is validator-gated - Accept only summaries tied to real event IDs and evidence IDs; degrade to deterministic fallback on invalid output.
* Browser and static Brief surfaces can show the lens - Add schema defaults, view-model projection, static Brief projection/rendering, QA coverage, and payload-size visibility.
* Release checks prove behavior - Add unit, integration, privacy, payload, and ASCII validation coverage.

### Out of Scope (Deferred)

* Podcast transcripts or cross-show references - Reason: Sessions 16-17 own the podcast source/media boundary.
* Adding any new source beyond current news adapters - Reason: this session explicitly reuses existing reviewed news evidence.
* Reading raw article bodies or comments - Reason: the rollup uses already normalized metadata only.
* Changing topic scores, action verdict caps, or canonical seed files - Reason: this is a report lens, not a scoring or seed mutation path.
* Static Brief archival, One-to-Watch, pre-run estimates, security lens, or podcast work - Reason: later Phase 29 sessions own those areas.

***

## 5. Technical Approach

### Architecture

Create a focused `industry-events` helper under `scripts/extensions/trend-finder/`. The helper should own news-evidence selection, publisher identity extraction, tokenization, deterministic clustering, row bounds, two-publisher enforcement, fallback summary generation, AI summary merging, and privacy-safe row projection.

The helper should consume already-normalized evidence, topics, sources, and optional analyst event briefs. It should never call collectors, fetch article bodies, add source adapters, read transcripts, or infer new source approval. Publisher identity should prefer `sourceLocal.entityKind === "publisher"` and fall back to the public URL hostname only when necessary. Event rows should be sorted deterministically by publisher support, evidence support, recency, and event ID.

Add a root-level `industryEvents` branch to the Trend Finder payload with Zod defaults for legacy data. Surface the rows through `view-model.ts`, `brief-export-model.ts`, `static-brief-export.ts`, and `static-brief-renderer.ts`. Update static Brief QA and payload-size reporting so the new branch is monitored and remains browser-safe.

### Design Patterns

* Derived-field shape: derive, validate/default, sanitize, surface, prove, and document.
* Existing source boundary: use current reviewed news adapters only.
* Corroboration reuse: publisher identity and independent-entity counts decide whether an event can publish.
* Deterministic fallback: event rows remain useful without accepted AI output.
* Additive schema defaults: older generated payloads parse with no events.
* Safe failure mode: derivation failures produce warnings and an empty `industryEvents` array, not private details or partial unvalidated rows.

### Technology Stack

* TypeScript for derivation, analyst contracts, schemas, collector wiring, and projections.
* Zod schemas with `.default()` and `.catch()` for backwards-compatible parsing.
* Bun and Vitest for helper, analyst, collector, schema, projection, and static Brief tests.
* Existing Playwright/static Brief checks for browser-visible export behavior.

***

## 6. Deliverables

### Files to Create

| File                                                                | Purpose                                                                  | Est. Lines |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------- |
| `scripts/extensions/trend-finder/industry-events.ts`                | Industry-event derivation, publisher checks, fallback summaries, bounds. | \~320      |
| `scripts/extensions/trend-finder/__tests__/industry-events.test.ts` | Unit tests for clustering, suppression, AI merge, ordering, and privacy. | \~360      |

### Files to Modify

| File                                                                      | Changes                                                                                        | Est. Lines |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/trend-analyst.ts`                                 | Add optional industry-event brief candidate/output contract and validation.                    | \~120      |
| `scripts/extensions/trend-finder/collector.ts`                            | Build industry events after scored topics and before browser payload validation with warnings. | \~90       |
| `src/extensions/trend-finder/schema.ts`                                   | Add `TrendIndustryEvent` constants, schema, defaults, type, and `industryEvents` root branch.  | \~140      |
| `src/extensions/trend-finder/view-model.ts`                               | Add industry-events presentation model, labels, tones, empty copy, and sorting.                | \~120      |
| `src/extensions/trend-finder/brief-export-model.ts`                       | Project industry events into the export document and Markdown output.                          | \~90       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Include industry events in the static Brief report contract.                                   | \~70       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render an industry-events section with bounded citations and empty state.                      | \~110      |
| `scripts/extensions/trend-finder/static-brief-qa.ts`                      | Add structure and privacy checks for the new Brief section.                                    | \~70       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                 | Track `data.industryEvents` as a high-pressure browser payload branch.                         | \~20       |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts`             | Cover collector integration, safe failure, and no new source collection.                       | \~90       |
| `scripts/lib/ai-runtime/__tests__/trend-analyst.test.ts`                  | Cover event brief validation and invalid-output fallback behavior.                             | \~80       |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                | Cover industry-events labels, empty state, ordering, and cited evidence projection.            | \~80       |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover section rendering, citation bounds, and no private strings.                              | \~80       |
| `scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts`       | Cover QA section checks and privacy failure mapping.                                           | \~70       |
| `docs/extensions/trend-finder-pipeline.md`                                | Document the industry-events step, source boundary, and payload/privacy behavior.              | \~40       |
| `docs/extensions/trend-finder-ui-surfaces.md`                             | Document the Brief/live surface behavior and empty states.                                     | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] News evidence from `rss-ai-news` and `google-ai-news` can produce bounded `industryEvents` rows.
* [ ] Single-publisher event fixtures are suppressed and expose no published event row.
* [ ] Events supported by at least two independent publishers publish with bounded rows, cited evidence IDs, publisher counts, and related topic IDs.
* [ ] Deterministic fallback clustering works without AI runtime output.
* [ ] Invalid AI event output is rejected when it cites unknown event IDs, evidence IDs, dates, URLs, source names, or ungrounded claims.
* [ ] Browser payloads and static Brief output expose no raw article bodies, comment bodies, transcripts, prompts, provider responses, private paths, tokens, credential-shaped strings, or raw source payloads.
* [ ] Existing RSS and Google News adapter behavior remains source-compatible and does not emit Google redirect URLs as public event links.

### Testing Requirements

* [ ] Unit tests written and passing for clustering, publisher identity, single-publisher suppression, two-publisher publication, row bounds, deterministic ordering, and AI merge rejection.
* [ ] Collector tests prove no source widening, safe warnings on derivation failure, and valid `industryEvents` payload output.
* [ ] Schema and view-model tests prove legacy defaults, empty state, labels, ordering, cited evidence projection, and privacy-safe presentation.
* [ ] Static Brief renderer and QA tests prove the section renders, remains privacy-clean, and fails on private fields or strings.
* [ ] Payload-size and static Brief privacy scans remain green.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] Event derivation is deterministic and bounded by configured row and citation limits.
* [ ] Derivation errors degrade to warnings plus an empty branch without blocking unrelated Trend Finder output.
* [ ] No new source, media, credential flow, database, hosted storage, dependency, or third-party transfer is introduced.

### Quality Gates

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

***

## 8. Implementation Notes

### Key Considerations

* Use only normalized metadata already present in the generated evidence rows.
* Prefer `sourceLocal.entityKind === "publisher"` for publisher identity, then use public URL hostname fallback only when source-local publisher metadata is missing.
* Keep the rollup report-level. It should not mutate topic scores, action verdicts, risk flags, canonical seeds, keyword packs, or source declarations.
* Event rows should cite evidence IDs and related topic IDs, not raw article content or private source payloads.
* The static Brief section should remain compact and useful even when no events pass the two-publisher threshold.
* Payload-size reporting should make `industryEvents` visible so future phases can manage cumulative browser payload growth.

### Potential Challenges

* Publisher identity collisions: Normalize publisher labels and URL hosts conservatively, then suppress rows when independence is ambiguous.
* Sparse current-source news: Keep a clear empty state rather than weakening the two-publisher requirement.
* AI overreach: Reject summaries that cite unknown evidence, invent dates, or imply raw article/body inspection.
* Payload pressure: Cap event rows, cited evidence IDs, and summary lengths.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: The new branch must stay compact and explicitly labeled as derived, fallback, or unavailable.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief and browser payloads must not expose raw evidence, private paths, transcripts, prompts, or local triage state.
* \[P27] **Deterministic fallback before AI enrichment**: Industry events must publish deterministic fallback rows before optional analyst copy is accepted.
* \[P28] **Direct public source scope is narrow**: Reuse reviewed RSS and Google News evidence only; do not imply new source approval.
* \[P28] **Trend Finder release validation is bundled**: Keep payload-size, static Brief privacy, and documentation validation together.
* \[P00] **Do not document planned features as implemented**: Docs touched during implementation must describe only shipped behavior.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Single-publisher news stories being presented as corroborated industry events.
* AI-generated event copy inventing claims, source names, URLs, dates, or citations.
* Raw article bodies, transcripts, provider responses, or private paths leaking into browser payloads or static Brief output.

***

## 9. Testing Strategy

### Unit Tests

* Test single-publisher RSS-only or Google-only fixtures are suppressed.
* Test two independent publishers with shared event tokens publish one bounded event row with cited evidence IDs and related topic IDs.
* Test publisher identity extraction from source-local publisher metadata and public URL host fallback.
* Test deterministic clustering, event ID generation, sorting, max row limits, max citation limits, and empty/unavailable states.
* Test accepted and rejected AI event brief output, including unknown IDs, invented citations, overlong summaries, and fallback retention.

### Integration Tests

* Test collector integration with mocked evidence, topics, sources, AI output, and derivation failure dependencies.
* Test schema parsing for legacy payloads without `industryEvents`.
* Test view-model and Brief export projections with populated and empty events.
* Test static Brief QA catches private fields/strings in the industry-events section.

### Manual Testing

* Run focused Vitest suites for industry events, analyst validation, collector, schema/view-model projection, static Brief rendering, and static Brief QA.
* Run payload-size reporting and static Brief privacy checks against a generated or fixture payload.
* Inspect the rendered static Brief section to confirm the event lens is compact and cites only safe evidence IDs/public links.

### Edge Cases

* No news evidence in the current payload.
* News evidence has missing or ambiguous publisher metadata.
* Multiple publishers syndicate the same article with identical title text.
* Event candidates share common AI terms but no meaningful entity tokens.
* AI runtime returns event rows with unknown evidence IDs, unknown event IDs, private-looking paths, or invented URLs.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase29-session04-corroboration-gate`
* **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-session11-industry-events-rollup/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.