> 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/phase24-session01-source-local-scoring-signals/implementation-notes.md). # Implementation Notes **Session ID**: `phase24-session01-source-local-scoring-signals` **Started**: 2026-06-07 22:22 **Last Updated**: 2026-06-07 22:40 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 25 / 25 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-06-07 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Bun 1.3.14 available * [x] Directory structure ready *** ### Task T001 - Verify current scoring, schema, source normalization, and Engine Replay extension points **Started**: 2026-06-07 22:20 **Completed**: 2026-06-07 22:22 **Duration**: 2 minutes **Notes**: * Reviewed `scripts/lib/ai-runtime/scoring.ts`, `src/extensions/trend-finder/schema.ts`, `scripts/extensions/trend-finder/normalize.ts`, `scripts/extensions/trend-finder/sources/apify-normalizers.ts`, and Engine Replay trace/model files. * Confirmed existing score semantics are six fixed factors with weighted opportunity scoring, and source quality already controls scoring evidence selection. * Confirmed browser data parsing uses additive Zod defaults, making new fields compatible with legacy payloads when defaulted. * Confirmed Engine Replay uses sanitized trace counters and safe labels, not raw source records. **Files Changed**: * `.spec_system/specs/phase24-session01-source-local-scoring-signals/implementation-notes.md` - recorded initial contract review. *** ### Task T002 - Record source compliance review for entity identity and placement fields **Started**: 2026-06-07 22:22 **Completed**: 2026-06-07 22:22 **Duration**: 1 minute **Notes**: * Reviewed source compliance docs and current source declarations before exposing entity identity or placement flags. * Allowed entity identity is limited to public source/container labels already approved for display: GitHub repository full name, Reddit subreddit/community name, Product Hunt launch/product slug, YouTube channel title, RSS/news feed or source label, and Hugging Face model namespace. * Hacker News author identity stays unavailable and is not used for baseline grouping. * Author usernames, profile URLs, maker/profile details, comments, transcripts, Dataset IDs, Actor IDs, raw payloads, private paths, and provider details remain outside browser and analyst payloads. * Placement flags are limited to reviewed public row state fields indicating pinned, stickied, promoted, sponsored, or ad-like placement. Unsupported or unknown placement state must degrade explicitly instead of guessing. **Files Changed**: * `.spec_system/specs/phase24-session01-source-local-scoring-signals/implementation-notes.md` - recorded source compliance boundary. *** ### Task T003 - Create session security and compliance note shell **Started**: 2026-06-07 22:22 **Completed**: 2026-06-07 22:22 **Duration**: 1 minute **Notes**: * Created a session security/compliance shell documenting data boundaries, initial review, and verification follow-up. **Files Changed**: * `.spec_system/specs/phase24-session01-source-local-scoring-signals/security-compliance.md` - added session shell. *** ### Tasks T004-T008 - Source-local contracts and additive schemas **Started**: 2026-06-07 22:23 **Completed**: 2026-06-07 22:31 **Duration**: 8 minutes **Notes**: * Added `source-local-signals.ts` with bounded ratio, baseline, band, actionability, placement, and trace summary contracts. * Extended source adapter metadata, browser schema, analyst evidence schema, and Engine Trace schema with optional additive source-local fields. * Kept legacy payload behavior additive by making source-local evidence/topic fields optional and bounded. **Files Changed**: * `scripts/extensions/trend-finder/source-local-signals.ts` - added source-local baseline and summary helper. * `scripts/extensions/trend-finder/sources/types.ts` - added adapter metadata contracts. * `src/extensions/trend-finder/schema.ts` - added browser-safe source-local schema fields. * `scripts/lib/ai-runtime/trend-analyst.ts` - added analyst evidence source-local contract. * `src/extensions/trend-finder/engine-trace.ts` - added bounded source-local summary contract. **BQC Fixes**: * Contract alignment: mirrored source-local fields between script, analyst, browser, and trace boundaries. *** ### Tasks T009-T017 - Source-local extraction, collection, scoring, trace, and UI **Started**: 2026-06-07 22:31 **Completed**: 2026-06-07 22:35 **Duration**: 4 minutes **Notes**: * Added Apify entity and placement extraction from reviewed public fields only. * Preserved Hacker News unsupported-baseline behavior without author identity. * Applied source-local computation in collection before analyst preparation, scoring, trace generation, and browser payload assembly. * Added capped source-local lift support to existing score factors without adding or replacing score factors. * Added sanitized Engine Trace summary mapping and Engine Replay baseline/exclusion counters. * Added evidence chips and score-breakdown context for source-local ratio and actionability states. **Files Changed**: * `scripts/extensions/trend-finder/sources/apify-normalizers.ts` - added safe entity, placement, and source-local metadata extraction. * `scripts/extensions/trend-finder/normalize.ts` - added explicit Hacker News unsupported baseline state. * `scripts/extensions/trend-finder/collector.ts` - applied helper and emitted sanitized summary counts. * `scripts/lib/ai-runtime/scoring.ts` - added capped source-local lift contribution. * `scripts/extensions/trend-finder/engine-trace.ts` - mapped source-local trace counters. * `src/extensions/trend-finder/view-model.ts` - added source-local chip view models. * `src/extensions/trend-finder/components/evidence-metric-chips.tsx` - rendered focusable metric/actionability chips. * `src/extensions/trend-finder/engine-replay-model.ts` - modeled source-local baseline summary. * `src/extensions/trend-finder/components/engine-evidence-filter.tsx` - rendered source-local counters. * `src/extensions/trend-finder/components/score-breakdown.tsx` - added source-local context without changing factor list semantics. * `src/extensions/trend-finder/components/trend-card.tsx` - passed topic source-local context. * `src/extensions/trend-finder/views/hidden-gems-view.tsx` - passed topic source-local context. * `src/extensions/trend-finder/views/watchlist-view.tsx` - passed topic source-local context. * `src/extensions/trend-finder/components/signal-radar.tsx` - passed topic source-local context. **BQC Fixes**: * Trust boundary enforcement: raw source payloads, authors, profiles, Dataset IDs, Actor IDs, and private paths remain excluded from browser and analyst payloads. * Failure path completeness: missing entity, missing metric, low sample, unsupported source, placement excluded, and missing baseline states are explicit. * Contract alignment: `bun run typecheck:scripts` and `bun run typecheck` passed after implementation. * Accessibility: new metric chips include `aria-label`, `title`, and keyboard focus styling. *** ### Tasks T018-T020 - Source-local scoring, source, and provenance documentation **Started**: 2026-06-07 22:35 **Completed**: 2026-06-07 22:36 **Duration**: 1 minute **Notes**: * Documented source-local ratio formula, unavailable states, capped scoring support, and actionability bands. * Documented reviewed source entity fields and conservative pinned/promoted handling. * Documented Engine Replay source-local counters and explicit unavailable/zero-count states. **Files Changed**: * `docs/extensions/trend-finder-scoring.md` - added source-local formula, caps, and actionability semantics. * `docs/extensions/trend-finder-sources.md` - added reviewed entity and placement handling notes. * `docs/extensions/trend-finder-runtime-and-provenance.md` - added Engine Replay source-local counter labels. *** ### Tasks T021-T025 - Focused tests and verification **Started**: 2026-06-07 22:36 **Completed**: 2026-06-07 22:40 **Duration**: 4 minutes **Notes**: * Added helper tests for ratios, low samples, missing fields, placement exclusions, and extreme bands. * Extended Apify normalizer tests for reviewed entity identity, pinned placement exclusion, and private field rejection. * Extended scoring tests for bounded lift and six-factor preservation. * Extended schema tests for legacy source-local absence, malformed source-local defaults, and trace summary parsing. * Ran focused tests, typechecks, formatting, and ASCII verification. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/source-local-signals.test.ts` - added source-local helper unit tests. * `scripts/extensions/trend-finder/sources/__tests__/apify-normalizers.test.ts` - extended entity/placement/private-field coverage. * `scripts/lib/ai-runtime/__tests__/scoring.test.ts` - extended bounded lift coverage. * `src/lib/__tests__/trend-finder-schema.test.ts` - extended schema and trace source-local coverage. * `package.json` - no package script changes; existing scripts were used for verification. **Verification**: * [x] `bun run typecheck:scripts` * [x] `bun run typecheck` * [x] `bun run test -- scripts/extensions/trend-finder/__tests__/source-local-signals.test.ts scripts/extensions/trend-finder/sources/__tests__/apify-normalizers.test.ts scripts/lib/ai-runtime/__tests__/scoring.test.ts src/lib/__tests__/trend-finder-schema.test.ts` * [x] ASCII scan across touched files *** --- # 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/phase24-session01-source-local-scoring-signals/implementation-notes.md?ask=&goal= ``` `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.