README-WITHIN-CHANNEL-ANALYSIS.md

# Generic Within-Channel Performance Analysis Overlay

This overlay adds the within-channel performance analysis flow to the generic YouTube Ecosystem Intelligence project. It is ecosystem-agnostic and reads the active database path from `config.js`.

## Contents

- `src/analysis/within-channel-*`: deterministic statistics, analysis, persistence/schema, observational queue evidence, and report generation.
- `src/stages/31-within-channel-performance.js`: calculates a new immutable analysis run.
- `src/stages/32-within-channel-performance-report.js`: regenerates reports from a persisted run.
- `tests/within-channel-performance.test.js`: unit tests for the analysis logic.
- `package.json`: complete replacement from the supplied project dump, including the three npm scripts below.

## Run from the project root

```bash
npm install
npm run test:within-channel
npm run within-channel:analyze -- --dry-run
npm run within-channel:analyze
npm run within-channel:report
```

Optional: use `npm run within-channel:analyze -- --as-of=2026-10-17T12:00:00.000Z` for a reproducible reference time. To regenerate a particular run's reports, use `npm run within-channel:report -- --run-id=<run-id>`.

## Data and safety boundaries

- The analysis creates independent `within_channel_*` tables in the database selected by `config.js`.
- It deduplicates channel/video relationships and supplements them from the videos table where available.
- Lifetime-view outliers and age-adjusted performance are separate signals. Age-adjusted labels require reliable exact publication dates.
- Small samples are explicitly marked as insufficient/preliminary rather than treated as equally reliable.
- Queue evidence is observational only. Existing queue scores, queue ranks, and their history are not read or modified by the analysis stage.
- The report is written under `reports/within-channel-performance/<run-id>/`.

## Overlay layout

The ZIP paths are relative to the project root. Extract into the root of the generic project and allow file replacement. Keep a backup of any local edits to files included in the overlay before replacing them.