> 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-session09-source-death-baseline-alarm/spec.md).

# Session Specification

**Session ID**: `phase29-session09-source-death-baseline-alarm` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-20

***

## 1. Session Overview

This session adds a private source-death baseline alarm for Trend Finder source collection. The current collector can describe the latest run through source summaries, collection health, Engine Replay, and private diagnostics, but it does not remember whether a previously live configured source suddenly returned zero accepted evidence. That makes a broken adapter or feed look too similar to a genuinely quiet run.

The implementation should persist a private last-good per-source accepted-evidence baseline keyed by source ID, compare the next run against it, and surface only browser-safe warning labels when a previously live configured source returns zero accepted rows. Disabled, unconfigured, credential-missing, restricted, placeholder, skipped fallback, and first-run sources must not trip the alarm.

The warning belongs near the source-collection boundary, after current evidence counts and source setup state are known and before Engine Replay, collection health, and browser payload handoff are built. The private baseline file path and prior accepted-evidence counts stay out of browser state, Engine Replay, static Brief, logs, docs, and generated public artifacts.

***

## 2. Objectives

1. Persist a private last-good accepted-evidence baseline per configured source ID.
2. Detect zeroed-live sources without alarming on first-run, disabled, unconfigured, or skipped sources.
3. Surface source-death warnings through collection health, Sources, and Engine Replay using safe labels only.
4. Keep baseline paths, prior counts, private cache names, and raw diagnostics out of browser-safe payloads.
5. Add focused tests for zeroed-live, first-run, disabled-source, privacy, and schema default cases.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session07-per-stage-validation-narration` - Provides the narrated trace and warning path that this alarm uses for Engine Replay surfacing.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing Trend Finder collector source flow in `scripts/extensions/trend-finder/collector.ts`.
* Existing private diagnostics writer in `scripts/extensions/trend-finder/private-diagnostics.ts`.
* Existing source setup state in `src/extensions/trend-finder/schema.ts` and `scripts/extensions/trend-finder/sources/source-setup.ts`.
* Existing Engine Replay trace sanitization in `scripts/extensions/trend-finder/engine-trace.ts` and `src/extensions/trend-finder/engine-trace.ts`.

### Environment Requirements

* Project dependencies installed with Bun.
* Local cache directory available through the collector context.
* No new source, media, credential, database, hosted storage, or third-party transfer approval is required.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder can persist private source baselines - Add a script-only helper that reads and writes a private last-good accepted-evidence baseline keyed by source ID.
* Trend Finder can detect source death - Flag a configured and enabled source that previously had accepted evidence and now has zero accepted evidence.
* Non-run states remain distinct - Exclude disabled, unconfigured, credential-missing, restricted, placeholder, skipped fallback, and first-run sources from alarms.
* Collection health shows safe warning state - Add bounded alarm count and label fields without exposing prior counts or private paths.
* Sources view shows safe source warning labels - Mark affected source summaries with a safe warning message and degraded warning state.
* Engine Replay shows source-death proof safely - Include the alarm in sanitized trace collection health and source rail metrics without private baseline details.
* Private diagnostics stay private - Keep baseline file path, prior count values, cache path, and raw diagnostic details out of browser payloads and static artifacts.
* Release checks prove behavior - Add unit, collector, schema, Engine Replay, Sources, payload, privacy, and ASCII validation coverage.

### Out of Scope (Deferred)

* Auto-disabling or re-enabling sources - Reason: the alarm informs the operator but does not mutate source enablement.
* Publishing baseline counts, baseline file names, or cache paths - Reason: this session exposes only safe warning labels and aggregate alarm presence.
* New source adapters or wider collection scope - Reason: Session 09 is reliability polish over existing sources.
* Static Brief archival, seed-candidate artifacts, industry events, security lens, or podcast work - Reason: later Phase 29 sessions own those areas.
* Changing source-local scoring baselines - Reason: source-death is a per-source run-health baseline, not the existing per-evidence source-local lift model.

***

## 5. Technical Approach

### Architecture

Create a focused `source-death-baseline` helper under `scripts/extensions/trend-finder/`. The helper should own the private baseline schema, safe read/write behavior, eligibility rules, alarm derivation, warning formatting, and a bounded browser-safe projection. It should use source IDs as stable keys and store only private run-health state under the collector cache directory.

The collector should call the helper after source setup state is resolved, source summaries are enriched with setup state, collection health is available, and accepted evidence counts by source are known. The helper should return updated source summaries, updated collection-health fields, safe warnings, and private write warnings. Sources with accepted evidence update their last-good baseline. Sources with zero accepted evidence are flagged only when the previous private baseline says they were previously live and the current source/setup state is eligible.

Eligibility should be explicit and test-covered. A source is eligible only when it is configured, enabled, reviewed enough to run, not credential-missing, not restricted, not placeholder, not a skipped direct or Apify fallback, and represented as an active or degraded source in the current run. First-run sources with no baseline should record current good evidence if present but not warn.

Browser payload changes should be additive and defaulted in `src/extensions/trend-finder/schema.ts`. `TrendCollectionHealth` can expose safe alarm presence, such as a warning count and short label. `TrendSourceSummary.errorMessage` can expose a bounded operator-safe message for affected sources, but it must not include the private baseline path or prior count values. Engine Replay trace mapping should carry only the safe collection-health fields and warning states.

### Design Patterns

* Script-only private state: Baseline persistence stays under `scripts/extensions/trend-finder/` and uses private cache files.
* Boundary-nearest warning: Alarm derivation runs where source state, setup state, and accepted evidence counts are all known.
* Additive schema defaults: New browser-safe fields default to neutral values for legacy payloads.
* Sanitized diagnostics: Browser surfaces expose safe labels, source IDs/names, and alarm presence only.
* Deterministic eligibility: Disabled, unconfigured, skipped, and first-run sources are excluded by explicit rules.

### Technology Stack

* TypeScript for helper contracts, schema defaults, and trace mapping.
* Zod schemas with `.default()` for backwards-compatible parsing.
* Bun and Vitest for script, schema, collector, and component tests.
* React 19 component tests for Sources and Engine Replay warning surfacing.
* Existing private-artifact and payload-size checks for boundary validation.

***

## 6. Deliverables

### Files to Create

| File                                                                      | Purpose                                                                                                         | Est. Lines |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/source-death-baseline.ts`                | Private baseline read/write helper, eligibility rules, alarm derivation, safe warning projection.               | \~260      |
| `scripts/extensions/trend-finder/__tests__/source-death-baseline.test.ts` | Unit coverage for first-run, zeroed-live, disabled, unconfigured, skipped, corrupt-baseline, and privacy cases. | \~260      |

### Files to Modify

| File                                                                           | Changes                                                                                                         | Est. Lines |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/collector.ts`                                 | Run source-death baseline evaluation after collection health and before Engine Replay/browser payload handoff.  | \~120      |
| `scripts/extensions/trend-finder/engine-trace.ts`                              | Carry sanitized source-death collection-health fields and warnings from `sources.collected`.                    | \~60       |
| `scripts/extensions/trend-finder/private-diagnostics.ts`                       | Share path-sanitization/write patterns or record manifest-safe artifact state if the helper reuses diagnostics. | \~40       |
| `src/extensions/trend-finder/schema.ts`                                        | Add defaulted browser-safe collection-health/source warning fields and any new literal types.                   | \~80       |
| `src/extensions/trend-finder/engine-trace.ts`                                  | Add defaulted Engine Replay collection-health alarm fields and parser coverage.                                 | \~70       |
| `src/extensions/trend-finder/view-model.ts`                                    | Project source-death warning labels and tones for collection health, source warnings, and source summaries.     | \~90       |
| `src/extensions/trend-finder/views/sources-view.tsx`                           | Surface safe source-death warning copy in the source health and warning panels.                                 | \~50       |
| `src/extensions/trend-finder/engine-replay-model.ts`                           | Add a source-death health metric and source rail label using sanitized trace/payload fields.                    | \~80       |
| `src/extensions/trend-finder/components/engine-source-rail.tsx`                | Render the new metric without layout shift or private detail exposure.                                          | \~30       |
| `src/extensions/trend-finder/fixtures.ts`                                      | Add fixture variants for normal, source-death, first-run, and disabled-source warning states.                   | \~80       |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts`                  | Cover collector integration, safe warning propagation, and no warning for ineligible sources.                   | \~140      |
| `scripts/extensions/trend-finder/__tests__/engine-trace.test.ts`               | Cover sanitized trace mapping and private sentinel exclusion.                                                   | \~70       |
| `src/extensions/trend-finder/__tests__/view-model.test.ts`                     | Cover default parsing and warning projection labels.                                                            | \~60       |
| `src/extensions/trend-finder/components/__tests__/engine-source-rail.test.tsx` | Cover Engine Replay source-death metric rendering without private strings.                                      | \~50       |
| `docs/extensions/trend-finder-pipeline.md`                                     | Document the private source-death baseline step and safe warning boundary.                                      | \~50       |
| `docs/extensions/trend-finder-sources.md`                                      | Document source-death warning semantics and excluded states.                                                    | \~50       |
| `docs/extensions/trend-finder-runtime-and-provenance.md`                       | Document Engine Replay source-death surfacing and privacy limits.                                               | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] A configured source with a private last-good baseline and zero current accepted evidence produces a source-death warning.
* [ ] A first run with zero accepted evidence does not produce a source-death warning.
* [ ] Disabled, unconfigured, credential-missing, restricted, placeholder, and skipped fallback sources do not produce source-death warnings.
* [ ] Sources with current accepted evidence update the private last-good baseline.
* [ ] Collection health, Sources, and Engine Replay show safe source-death warning labels.
* [ ] Browser payloads expose no private baseline path, cache path, file name, prior accepted-evidence count, raw diagnostic payload, stack trace, prompt, provider response, token, or credential-shaped string.

### Testing Requirements

* [ ] Unit tests written and passing for baseline read/write, eligibility, zeroed-live alarm, first-run no-op, disabled no-op, corrupt baseline fallback, and privacy-safe formatting.
* [ ] Collector tests prove alarm integration, safe warning propagation, baseline update behavior, and no warnings for ineligible sources.
* [ ] Schema/view-model tests prove legacy default parsing and browser-safe warning labels.
* [ ] Engine Replay and Sources component tests prove warning visibility without private strings or layout instability.
* [ ] Payload-size and private-artifact checks remain green.

### Non-Functional Requirements

* [ ] Browser payload stays under the 1 MB extension budget.
* [ ] The private baseline helper is deterministic, bounded, and linear in source count.
* [ ] Private baseline writes use safe path segments and atomic write behavior.
* [ ] 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 enum or schema branches use explicit fallback behavior.

***

## 8. Implementation Notes

### Key Considerations

* Do not use source-local lift baselines for this feature. Source-death is a run-health baseline keyed by source ID, not an evidence metric baseline.
* The private baseline should keep prior accepted-evidence counts private. Browser surfaces may say that a previously live source is now empty, but they must not show the previous count.
* Warning eligibility should prefer source setup state where available. Source summaries alone cannot reliably distinguish disabled, unconfigured, credential-missing, and skipped fallback cases.
* The collector should still complete when the private baseline file is missing or corrupt. Treat corrupt or unreadable baseline state as unavailable, emit a safe private warning, and avoid source-death alarms for that run.
* Existing source warnings and collection-health states should remain meaningful. Source-death can degrade collection health but should not overwrite unrelated source error messages unless the source has no safer, more specific warning.

### Potential Challenges

* Direct-source fallback ambiguity: Use direct readiness and source setup fallback labels to avoid alarming on intentionally skipped Apify fallback sources.
* Legacy payload compatibility: Add schema defaults so older generated data parses with neutral source-death fields.
* Trace sanitizer false positives: Keep new trace values to short codes, counts, and labels; avoid private paths and baseline filenames in trace payloads.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: The alarm must expose bounded labels and keep the 1 MB payload limit green.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief, Sources, and Engine Replay must not expose private baseline paths, local triage state, raw evidence, or private diagnostics.
* \[P28] **Direct public source scope is narrow**: This session adds no source and must keep fallback eligibility explicit.
* \[P28] **Direct source fallback labels are release-critical**: A skipped paid fallback behind a successful direct public API path is not source death.
* \[P00] **Do not document planned features as implemented**: Docs should describe source-death behavior only after implementation ships.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* False-positive alarms on first-run, disabled, unconfigured, or intentionally skipped sources.
* Private baseline paths or previous accepted-evidence counts leaking into browser payload, Engine Replay, static Brief, logs, or docs.
* Alarm state being hidden behind generic degraded labels instead of a clear operator-safe warning.

***

## 9. Testing Strategy

### Unit Tests

* Test baseline read/write with atomic write dependencies and safe path segment handling.
* Test zeroed-live alarm when prior baseline exists and the current configured source has zero accepted evidence.
* Test no alarm for first-run, disabled, unconfigured, credential-missing, restricted, placeholder, skipped fallback, and corrupt-baseline cases.
* Test safe warning formatting excludes private path, baseline file name, prior counts, and credential-shaped sentinels.

### Integration Tests

* Test collector integration with mocked source adapters, source setup state, cache directory, and baseline helper dependencies.
* Test Engine Replay trace mapping from `sources.collected` into sanitized collection-health metrics.
* Test schema and view-model parsing for legacy payloads missing the new fields.

### Manual Testing

* Run a focused mocked collector test pass, then inspect Sources and Engine Replay fixtures for source-death warning copy.
* Confirm source health still distinguishes quiet run, degraded source, offline source, and source-death warning states.

### Edge Cases

* Baseline file missing, unreadable, corrupt, or containing unknown source IDs.
* Source renamed but source ID unchanged.
* Source returns items but zero accepted evidence after quality filtering.
* Source intentionally skipped because direct public API succeeded and paid fallback was not needed.
* Source setup file missing or source not present in private source config.

***

## 10. Dependencies

### External Libraries

* No new external libraries.

### Other Sessions

* **Depends on**: `phase29-session07-per-stage-validation-narration`
* **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-session09-source-death-baseline-alarm/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.