> 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/phases/phase_15/session_02_live_data_merge_boundary.md).

# Session 02: Live Data Merge Boundary And Shared Write Lock

**Session ID**: `phase15-session02-live-data-merge-boundary` **Status**: Complete **Estimated Tasks**: \~16 **Estimated Duration**: 3-4 hours

***

## Objective

Create the safe write infrastructure needed for multiple scheduler jobs to update different parts of `src/data/live-data.json`.

This session must land before any scoped scheduler job handler is implemented. Its output is the branch ownership and write-safety contract used by `agent-aggregate`, `trend-finder`, and cross-job validation.

***

## Scope

### In Scope (MVP)

* Inventory live-data branches emitted by `scripts/aggregate.ts`
* Define host/local and extension branch ownership
* Add a shared generated-data write lock distinct from scheduler run locks
* Add stale-lock recovery aligned with current scheduler lock behavior
* Add a merge writer that preserves untouched branches
* Validate merged output through existing live-data validation
* Tests for branch preservation, invalid existing data fallback, lock blocking, and stale-lock recovery
* Runbook documentation for ownership boundaries

### Out of Scope

* New scheduler job handlers
* Aggregate orchestration refactor beyond write boundary extraction
* SQLite storage or projection changes
* Timer rendering, installation, or local timer mutation

***

## Detailed Tasks

1. Inventory the branches currently emitted by `scripts/aggregate.ts`.
2. Define host/local branches owned by the future `agent-aggregate` job.
3. Define extension branches owned by the future `trend-finder` job.
4. Add a generated-data write lock shared across scoped scheduler jobs.
5. Ensure the shared lock is distinct from per-job scheduler run locks.
6. Add stale-lock recovery rules consistent with current scheduler locks.
7. Add a merge writer helper for `src/data/live-data.json`.
8. Preserve untouched branches when a scoped job writes its owned branch.
9. Validate merged output through the existing live-data write validation.
10. Keep `src/data/live-data.example.json` as the fallback when live data is missing.
11. Add tests for preserving extension data during host/local writes.
12. Add tests for preserving host/local data during Trend Finder writes.
13. Add tests for invalid existing live data fallback behavior.
14. Add tests for shared-lock blocking and stale-lock recovery.
15. Ensure private paths, raw command bodies, prompts, auth JSON, and source dumps remain excluded from status and log output.
16. Document the write ownership boundary in the scheduled aggregate runbook.

***

## Prerequisites

* [ ] Session 01 complete.
* [ ] Current full aggregate write behavior understood and preserved.

***

## Deliverables

1. Generated-data lock helper.
2. Live-data ownership map and merge writer.
3. Tests proving scoped writes preserve the other branch.

***

## Handoff Gate

* [ ] Host/local and extension branch ownership is documented in code.
* [ ] Scoped writes preserve the other branch.
* [ ] Shared lock behavior is tested, including blocking and stale-lock recovery.
* [ ] Full aggregate writes still validate unchanged.

***

## Success Criteria

* [ ] Two scoped scheduler jobs cannot write `src/data/live-data.json` at the same time.
* [ ] A scoped write preserves the other scope's latest valid data.
* [ ] Merged output still passes privacy/write validation.
* [ ] Full `bun run aggregate` behavior remains unchanged.


---

# 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/phases/phase_15/session_02_live_data_merge_boundary.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.