> 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-session03-reception-signal-aggregate-only/spec.md).

# Session Specification

**Session ID**: `phase29-session03-reception-signal-aggregate-only` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-19

***

## 1. Session Overview

This session adds aggregate-only reception polarity to Trend Finder without crossing the comment-body boundary. Session 02 already created the polarity/attention grid with a reserved reception column; this session fills that column with a bounded `receptionSignal` field derived only from metrics that already exist in normalized evidence.

The implementation keeps Trend Finder's privacy posture intact. It may use aggregate values such as points, comment counts, upvotes, and exposed upvote ratios where those fields already exist, but it must not read, cache, classify, summarize, or publish comment bodies. Unsupported sources and thin evidence must return an explicit `unavailable` state.

The new signal also affects action safety. Topics marked `ratioed` or `contested` get a `contested-reception` risk flag and must be capped below `act_now` before action recommendations are attached, while the core opportunity score remains explainable and compatible with existing score adjustment behavior.

***

## 2. Objectives

1. Add a schema-defaulted `receptionSignal` field with `endorsed`, `contested`, `ratioed`, `mixed`, and `unavailable` states.
2. Derive reception only from already-collected aggregate metrics and return `unavailable` when the metric basis is not defensible.
3. Add a `contested-reception` risk flag and action-priority cap so `ratioed` and `contested` topics cannot become `act_now`.
4. Replace the reserved reception grid cell in live and static surfaces with bounded, accessible reception labels.
5. Prove no comment body reaches browser payloads, sanitized Engine Replay traces, or static Brief output.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session01-editorial-quick-wins` - Provides the title/noise hygiene baseline used by the current Trend Finder run.
* [x] `phase29-session02-attention-pattern-and-polarity-grid` - Provides the live and static polarity grid with the reserved reception column.
* [x] `phase28-session15-documentation-validation-and-release` - Provides the prior Trend Finder payload, privacy, static Brief, and release validation baseline.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Vitest tests for script runtime, schema, view-model, component, and static Brief behavior.
* Current Trend Finder collector ordering, especially scoring, source breakdown derivation, and action recommendation attachment.
* Existing privacy boundary docs for browser payloads, static Brief export, and Engine Replay sanitization.

### Environment Requirements

* Project dependencies installed with Bun.
* `src/data/live-data.example.json` available for fixture and payload-size validation.
* No source/media compliance approval is needed because this session adds no source and reads no comment bodies.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can publish `receptionSignal` as an additive topic field - Implement with enum constants, schema defaults, and legacy-safe parsing.
* Trend Finder can derive reception from aggregate metrics only - Implement a deterministic helper over existing normalized evidence metrics and supported source roles/types.
* Trend Finder can identify hostile or contested aggregate reception - Implement `contested-reception` risk flag propagation for `ratioed` and `contested` states.
* Trend Finder can keep contested reception below action wording - Implement action-priority caps and warnings that prevent `act_now` for `ratioed` and `contested` topics.
* Operators can read reception in live and static grids - Replace the Session 03 placeholder with label, tone, description, and accessible cell text.
* Release validation can prove privacy and payload safety - Add focused tests for no comment-body leakage, static Brief privacy, and bounded payload fields.

### Out of Scope (Deferred)

* Reading, storing, summarizing, or classifying comment bodies - Reason: This would cross the explicit Phase 29 privacy boundary.
* New source adapters, media collection, or social reply harvesting - Reason: Session 03 is aggregate-only and source-neutral.
* AI sentiment classification - Reason: The session requires deterministic aggregate derivation, not model-based sentiment.
* New opportunity score factor - Reason: Reception affects risk/action safety in this slice; broader scoring changes require a separate calibration session.
* Podcast, transcript, thumbnail, or media handling - Reason: Sessions 16 and 17 own that compliance gate and any gated implementation.

***

## 5. Technical Approach

### Architecture

Add a small aggregate reception helper under `scripts/lib/ai-runtime/` that accepts normalized topic evidence and returns a bounded enum plus derivation metadata used only for tests and safe diagnostics. The helper should understand which aggregate metrics are defensible for reception and should return `unavailable` for unsupported or thin inputs.

Wire the helper before `attachTrendActionRecommendations()` runs in the collector path. The current collector derives source breakdowns before action recommendations, so `deriveTopicSourceBreakdowns()` is the natural integration point for assigning `receptionSignal` and merging `contested-reception` into `riskFlags`. Action priority can then cap `contested` and `ratioed` topics using the risk flag or the topic field.

Browser and static surfaces should continue to consume projected view-model fields, not raw topic payload rows. The grid cell should use existing tone and label patterns, preserve the four-column grid contract from Session 02, and remain accessible on desktop and mobile.

### Design Patterns

* Additive schema evolution: Legacy payloads parse to `receptionSignal: "unavailable"`.
* Deterministic derived field: Runtime computes a short enum with no AI dependency.
* Boundary-nearest validation: Aggregate metric inputs are normalized and unsupported shapes return `unavailable`.
* Enum-only browser payload: Browser-visible reception state is a short label, not raw metric detail.
* Existing action cap model: Use the established action cap/warning contract instead of introducing a second verdict system.

### Technology Stack

* TypeScript and Zod for schema validation.
* Bun and Vitest for script/runtime tests.
* React 19 view-model and component tests with happy-dom.
* Static Brief projection and renderer tests under `scripts/extensions/trend-finder/__tests__/`.

***

## 6. Deliverables

### Files to Create

| File                                                        | Purpose                                                                                     | Est. Lines |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- |
| `scripts/lib/ai-runtime/reception-signal.ts`                | Aggregate-only reception derivation helper with bounded states and unavailable fallback.    | \~180      |
| `scripts/lib/ai-runtime/__tests__/reception-signal.test.ts` | Unit coverage for thresholds, unsupported metrics, mixed state, and comment-body exclusion. | \~180      |

### Files to Modify

| File                                                                                | Changes                                                                                        | Est. Lines |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/trend-finder/schema.ts`                                             | Add reception enum/default/schema/type field plus risk/action enum additions.                  | \~90       |
| `scripts/lib/ai-runtime/source-breakdown.ts`                                        | Attach reception signal and merge contested-reception risk flag before action recommendations. | \~60       |
| `scripts/lib/ai-runtime/action-priority.ts`                                         | Add reception-aware action cap, warning, calibration, and no-act-now behavior.                 | \~90       |
| `src/extensions/trend-finder/view-model.ts`                                         | Add reception labels, tones, risk flag copy, and grid cell projection.                         | \~110      |
| `scripts/extensions/trend-finder/collector.ts`                                      | Add enum-only trace summary fields without copying raw evidence text.                          | \~25       |
| `scripts/extensions/trend-finder/static-brief-export.ts`                            | Preserve projected reception cells in static Brief report output and schema.                   | \~35       |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                          | Keep rendered reception cells escaped, bounded, and layout-safe.                               | \~20       |
| `scripts/extensions/trend-finder/measure-payload-size.ts`                           | Include reception signal in payload pressure reporting.                                        | \~20       |
| `src/extensions/trend-finder/fixtures.ts`                                           | Add fixture reception states for live surface coverage.                                        | \~35       |
| `scripts/lib/ai-runtime/__tests__/source-breakdown.test.ts`                         | Cover source-breakdown attachment and risk flag propagation.                                   | \~80       |
| `scripts/lib/ai-runtime/__tests__/action-priority.test.ts`                          | Cover contested/ratioed action caps and endorsed non-cap behavior.                             | \~80       |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                          | Cover legacy defaults, labels, tones, and grid rows.                                           | \~80       |
| `src/extensions/trend-finder/components/__tests__/polarity-attention-grid.test.tsx` | Replace reserved-cell assertions with actual reception states and accessibility checks.        | \~50       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`             | Cover projected reception cells and privacy scan behavior.                                     | \~60       |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts`           | Cover escaped reception cell HTML and no private strings.                                      | \~50       |
| `scripts/extensions/trend-finder/__tests__/engine-trace.test.ts`                    | Prove serialized trace uses enum-only reception and excludes comment-body sentinels.           | \~50       |
| `docs/extensions/trend-finder-scoring.md`                                           | Document reception states, aggregate-only derivation, risk flag, and action cap.               | \~90       |
| `docs/extensions/trend-finder-ui-surfaces.md`                                       | Document live/static reception grid behavior and privacy boundary.                             | \~50       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `receptionSignal` defaults to `unavailable` for legacy or unsupported payloads.
* [ ] A high-engagement hostile-ratio fixture resolves to `ratioed`, receives `contested-reception`, and cannot produce `act_now`.
* [ ] Topics with no defensible aggregate metric remain `unavailable`.
* [ ] Endorsed or mixed aggregate cases render as bounded labels without suppressing valid evidence rows.
* [ ] Live and static polarity grids show reception values instead of the Session 03 placeholder.

### Testing Requirements

* [ ] Unit tests written and passing for reception derivation, source-breakdown wiring, and action caps.
* [ ] Schema/view-model/component tests cover legacy defaults, labels, tones, accessibility labels, and long text safety.
* [ ] Static Brief export/renderer tests cover projected reception cells and privacy scan behavior.
* [ ] Engine Trace tests prove no comment-body sentinel reaches sanitized trace output.
* [ ] Focused test commands recorded in implementation notes during the implement step.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] Static Brief and Engine Replay remain browser-safe and do not expose raw source rows, private paths, prompts, provider responses, or comment bodies.
* [ ] No new source, collector, media boundary, database, or hosted storage path is introduced.

### Quality Gates

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

***

## 8. Implementation Notes

### Key Considerations

* Derivation must use aggregate metrics only. Counts such as `comments` are allowed when already normalized; comment text is not.
* Action recommendation attachment happens after source breakdown derivation in `collector.ts`, so risk flag propagation must happen before `attachTrendActionRecommendations()`.
* `contested-reception` should be distinct from `single-source-signal`; a topic can be multi-source and still contested by aggregate metrics.
* Static Brief should receive projected view-model cells and must not inspect raw source rows to render reception.
* Any diagnostic trace field should be enum-only and should not include metric ratios unless the existing trace sanitizer already approves the value class.

### Potential Challenges

* Ambiguous aggregate metrics: Mitigate by returning `unavailable` unless a supported metric basis and minimum sample threshold are present.
* False-positive ratioed state: Mitigate with documented thresholds and tests for neutral/mixed cases.
* Action cap drift: Mitigate by adding action-priority tests that assert `ratioed` and `contested` cannot produce `act_now`.
* Payload drift: Mitigate with enum-only payload shape, static Brief projection tests, and payload measurement.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: `receptionSignal` is a short enum with explicit `unavailable` state and bounded display labels.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must use projected rows only and must not include browser-local triage notes, raw evidence, private paths, or raw source payloads.
* \[P27] **Deterministic fallback before AI enrichment**: Reception is deterministic and must not depend on optional AI runtime.
* \[P28] **Direct public source scope is narrow**: This session adds no source and does not widen deferred social or media candidates.
* \[P00] **Do not document planned features as implemented**: Docs should describe shipped reception behavior only after implementation succeeds.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Contested topics accidentally still receive `act_now` because action caps run before reception risk is attached.
* Browser/static surfaces expose raw comment text or raw source rows while trying to explain reception.
* Unsupported sources show confident reception labels instead of explicit `unavailable` states.

***

## 9. Testing Strategy

### Unit Tests

* Add reception helper tests for `endorsed`, `contested`, `ratioed`, `mixed`, and `unavailable` states.
* Add source-breakdown tests proving reception is attached, risk flags are merged deterministically, and unsupported sources stay unavailable.
* Add action-priority tests proving `contested-reception` caps below `act_now` while endorsed topics remain eligible for normal action priority.

### Integration Tests

* Add schema/view-model tests for legacy payload defaults, risk flag labels, reception grid cell copy, and summary labels.
* Add static Brief export and renderer tests for projected reception cells, escaped strings, bounded rows, and privacy scan behavior.
* Add Engine Replay trace tests for enum-only reception summaries and no comment-body sentinels.

### Manual Testing

* Review the live Trends polarity grid with fixture data containing at least one `ratioed`, one `endorsed`, and one `unavailable` topic.
* Export a static Brief and verify reception cells render with the same bounded labels and no Session 03 placeholder.
* Inspect action verdicts for contested/ratioed topics and confirm they are `monitor`, `review`, or `ignore`, never `act_now`.

### Edge Cases

* Evidence has comments but zero points.
* Evidence has high points and low comments.
* Multiple evidence rows disagree and should produce `mixed`.
* Evidence has raw text containing a comment-body sentinel in title/snippet fixtures; serialized browser payload and trace must not copy it as a reception explanation.
* Legacy payload omits `receptionSignal`, `riskFlags`, or action-cap enum values.

***

## 10. Dependencies

### External Libraries

* Zod: Existing schema validation dependency.
* Vitest: Existing unit and component test runner.
* Playwright: Existing e2e runner if implement expands visible-grid browser coverage.

### Other Sessions

* **Depends on**: `phase29-session02-attention-pattern-and-polarity-grid`
* **Depended by**: `phase29-session08-required-derived-field-closeout-gate`, `phase29-session13-static-brief-archival-and-richness`, `phase29-session14-one-to-watch-surface`

***

## 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-session03-reception-signal-aggregate-only/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.