The Trilogy Times

## Summary

- Prepare Shipyard 0.6.10 with the approved public release notes.

## Business Value

- Gives users read-only Companion lookups across Shipyard data, more dependable replay evaluations, clearer Pomodoro transitions, and resilient Pi image attachments.

## Implementation Effort

- Metadata-only change: one version bump and one public release-notes file.

## Test Plan

- [x] pnpm test:release

- [x] git diff --check

Linear: AERIE-2548 (blocked by AERIE-2329)

> CI has never run on this PR. Its base is feat/camp-gateway-parity-check (#1478), not main, so the workflows don't trigger. CI will only run after #1478 merges and this PR is retargeted to main. All evidence below is local.

## Summary

Stacked on #1478 (base branch feat/camp-gateway-parity-check). #1478 only watches: it shadow-compares the 7 raw camp entities over the Surtr Gateway against Supabase and never publishes from the Gateway. This PR adds the cutover path, an A4-style read gate on refreshCampData:

CAMP_SOURCE_READ=pg|shadow|gateway (the name and values fixed in the migration spec's A5 tab; pg is the direct Supabase/Postgres read)

| Mode | Publishes from | Behaviour |

|---|---|---|

| pg (default, also any unrecognized value) | Supabase | Today's code path: the same 7 sequential reads, per-table upserts, and purge/projection rules. The read step moved into a helper; its behaviour is unchanged and covered by the existing refresh.test.ts camp tests. |

| shadow | Supabase | Publishes exactly as pg. After that, it compares the rows it just published (no second Supabase read) against the Gateway, using #1478's runCampSourceShadowCheck and its PII redaction. It logs one summary line. Gateway failures are logged and swallowed, and result is never touched. |

| gateway | Surtr Gateway (#1478's 7 readers) | Uses the same upserts, projection snapshot and mark-and-sweep purge as today. The gate is all-or-nothing: if any check below fails, nothing is upserted, purged or published. The previous snapshot stays live and the tick reports degraded. Once the gate passes, writes follow the same contract as pg (see Design choices). |

The gateway checks, all applied before the first write. Any failure refuses the whole cycle:

1. Every entity reads and passes its Zod schema, population floor and non-empty source_run_id (the #1478 readers).

2. No duplicate supabaseId in any entity.

3. Exactly one source_run_id within each entity, and the same one across all 7. Surtr's sp_refresh_camps publishes the 7 core tables atomically from one raw-sync run, so a mismatch means the reads straddled a publish.

4. Forward references resolve (9 relationships: location/week/registration → program, registration → location/parent/child, registration-week → registration/week, child → parent). This catches a short read of a *referenced* entity only.

5. Purge bound (added 2026-09-29). The worker lists each Convex camp table's current supabaseIds through a new read-only, paginated Convex op, listCampSupabaseIdsBatch. It then counts how many rows the purge would delete. If any table would lose more than CAMP_GATEWAY_MAX_PURGE_PCT (default 5%) of its current rows, or the listing fails, the cycle is refused. This covers the short reads that checks 1 and 4 miss: a registration-week, child or parent read that is short but above its floor and breaks no forward reference.

sourceRunId is stripped before the Convex upserts, because the Convex v.object validators reject unknown fields. The summer-camps scheduler requires SURTR_GATEWAY_API_KEY instead of Supabase in gateway mode; pg/shadow still require Supabase.

Also added:

- sync/src/scripts/dry-run-camp-gateway-publish.ts. It runs checks 1 to 4 plus the projection size bounds against the live Gateway, and prints counts, the run id and a verdict. It never talks to Convex, so it does not evaluate the purge bound (check 5).

- CAMP_SOURCE_READ and CAMP_GATEWAY_MAX_PURGE_PCT in .env.example.

### Design choices

- Refusal is all-or-nothing in gateway, even though pg is per-table. In pg, a failed Supabase table still lets the other six upsert. In gateway, a partial snapshot is refused, because the purge that follows would delete real rows.

- After the gate passes, the writes themselves are not one transaction, in either mode. This is unchanged from pg:

- Each table is upserted in atomic batches.

- The purge and the projection switch run only after every batch of every table succeeded.

- The request-path projections flip in one pointer change (publishCampProjectionSnapshot).

So a transient Convex failure mid-write skips the purge and the switch: no row is lost and the previous projection stays live. Detail readers of the raw camp* tables can briefly see this cycle's upserted rows next to the previous cycle's, until the next successful cycle, exactly as in pg today. Making the raw tables switch atomically would need versioned tables and reader changes across Convex for both modes. That's a separate design, flagged for Keval rather than bolted onto this gate.

- Only forward references are enforced; reverse references are not guaranteed by the data. Live Supabase on 2026-09-29 (counts only) had:

- 240 registrations with no week row

- 266 children and 259 parents with no registration

- 105 parents with no child

- 29 weeks with no booking

Requiring those directions would refuse every cycle. The purge bound covers them instead. The forward check is strict, because all 9 forward relationships had 0 dangling references in live Supabase on both 2026-09-26 and 2026-09-29.

- Purge-bound baseline: current Convex rows, not the last published count. The current Convex table is exactly the population the purge deletes from. It is correct on the first cycle after the shadow → gateway flip and after a worker restart. A "last published count" would need to be persisted somewhere; kept in process memory, it has no baseline after every deploy. The bound counts the *rows that would be purged*, not just the net count change, so a short read hidden by new rows is still caught. It implies the plain count-drop check.

- Threshold: 5%, configurable, fail-closed. An invalid value falls back to 5, never to unbounded. An empty Convex table allows anything, because there is nothing to purge. A real upstream bulk deletion over 5% keeps gateway refusing until an operator raises CAMP_GATEWAY_MAX_PURGE_PCT for one cycle or flips back to pg.

- Shadow runs after the publish. It cannot delay or alter what gets published.

- Errors never include row values. Every camp catch, in both modes, goes through describeCaughtCampValue. It reports non-Error values by type only, and it cuts a Convex error body where Convex starts quoting the rejected value (Value: / Object:). Gateway read errors in both modes go through #1478's describeCampReadError: issue count plus the first 3 issues, with invalid_enum_value/custom messages masked to their code. Duplicate, lineage, reference and purge-bound failures report counts and run ids only. The refusal tests check that sentinel PII values never reach console.*. That covers the tested paths, not every possible log line.

## Business Value

This is the missing cutover step for A5, the object that holds the whole summer-camps SaaS data set, including children's health data and parents' contact details. Without it, #1478 can prove parity but can never move Aerie off its direct Supabase credential. With it, the flip is an env change (pg → shadow → gateway) with an instant rollback. The gateway path refuses rather than publishes when a read looks incomplete, and it can't purge more than the configured share (default 5%) of any table in one cycle. That guard is only as good as its checks and its threshold; it is not a guarantee. Cutting A5 over removes one of the dependencies that block analytics-worker teardown.

## Manual Effort Estimate

Proposal for Keval to confirm or adjust: ~11 focused hours (was ~9 before the 2026-09-29 purge-bound round). The extra time went to working out that reverse references aren't guaranteed, adding the Convex listing op and its test, and the production-scale refusal tests.

## Testing / evidence

Local only (see the CI note at the top). Latest run: 2026-09-29 on ea5eca6f0, rebased onto #1478 at b2e8855dc (Mercy-approved).

- Typecheck: sync and chat (a Convex op was added) are clean.

- Lint: pnpm lint exits 0. The 2 warnings are pre-existing, in chat/skill/forge-api/scripts/sindri.mjs.

- Sync tests (--maxWorkers=2): 1,507 passed, including 57 in camp-source-read.test.ts.

- Targeted chat tests: only 4 files were run: campsAtomicUpsert.test.ts (touched here), the sync-route security test, and the two Data Health camp tests from #1478. 67 tests passed. The full chat suite was not run.

- What the gate tests cover:

- Mode parsing, and the default and unrecognized values keeping Supabase.

- The gateway publish path.

- Refusal with zero writes on a reader failure, cross-entity lineage mismatch, dangling reference, or Convex listing failure.

- The reviewer's scenario: 2,000 of 2,704 registration weeks, at live scale, refused with nothing written or purged.

- Children and parents missing only unregistered rows (the forward check alone accepts this snapshot) refused.

- A 5-row genuine deletion still publishing, and CAMP_GATEWAY_MAX_PURGE_PCT=0 refusing a single deletion.

- Shadow never publishing Gateway values.

- Mutation checks: disabling the purge bound fails 4 tests. Earlier rounds showed that disabling the lineage/reference guards fails 4, and making shadow publish from the Gateway fails 2.

- Read-only Supabase checks, counts only:

- Row counts: 27 / 27 / 183 / 2,614 / 2,704 / 2,522 / 1,883.

- 0 duplicate ids, and 0 dangling forward references.

- The reverse-orphan counts listed in Design choices.

- The gate's snapshot checks (1 to 4) accept today's rows as a synthetic single-run snapshot. The purge bound was not exercised against real Convex; nothing touched a Convex deployment.

## Not covered

- CI, see the top of this description.

- The live Gateway leg. There's no SURTR_GATEWAY_API_KEY locally, and the 7 raw camp sources aren't granted to any key yet (Keval's step, X4).

- The purge bound against a real deployment. listCampSupabaseIdsBatch ships in this PR's Convex code, so the worker change and the Convex deploy must go out in the same release. If the op is missing, gateway refuses every cycle (fail-closed), so the risk is a stuck cutover, not data loss.

- Grants, prod shadow, flip. These need Keval's approval, the EC2 .env (X3), an Aerie release (Benji, X2), then CAMP_SOURCE_READ=shadow for about 24 clean hourly cycles before gateway.

- Precondition for gateway: Surtr's Redshift client must follow NextToken (https://github.com/AI-Builder-Team/Surtr/pull/2036, merged 2026-09-23). The readers use 5,000-row pages.

- No freshness guard. The readers don't read refreshed_at, and that column's presence on the Gateway sources is unverified.

- Legacy deletion (Supabase reads and env vars, parity schedulers) comes after cutover.

## Open questions for Keval

1. Is 5% the right default for CAMP_GATEWAY_MAX_PURGE_PCT? Camp rows are rarely hard-deleted upstream, so a tighter value (1 to 2%) is also defensible.

2. Add a staleness guard (refuse if the mart's refreshed_at is older than N hours)? That needs the column confirmed on the 7 Gateway sources.

3. With CAMP_SOURCE_READ=shadow on, CAMP_SOURCE_SHADOW_CHECK_ENABLED duplicates it (a second Gateway read each hour). Should both stay on during the shadow window, or only this one?

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

Plan object A1 (rhodes-merger, AERIE-2610). The analytics worker's rhodes-merger can now run in shadow mode against Surtr's published merge. Surtr already builds the same per-field merge hourly (core_education.site_operational_metadata, Gateway source aerie-site-operational-metadata). Aerie's prod Gateway key can already read it.

- Gate: RHODES_MERGER_READ=legacy|shadow, default legacy. Merging and deploying changes nothing.

- Shadow: computes the merge and writes to Rhodes exactly as legacy. Afterwards, at most once an hour, it reads the Surtr snapshot and logs one rhodes_merger_shadow_check JSON line, a field-level diff keyed on site slug across the 9 written fields plus their provenance. It never publishes anything read from the Gateway. A Gateway or validation failure is logged as status: "degraded" and swallowed, and the tick's own clean/degraded status is never changed by shadow. The tick summary gets a ; shadow <status> suffix.

- Throttle: the task ticks every 5 min, but Surtr publishes hourly. One throttle per worker allows one Gateway read per hour; a failed read also uses its slot.

- Skips: the compare is skipped (the slot stays free) when the ISP or HubSpot bulk fetch failed. In that case the cycle's merge is partial, and comparing it would report false divergences.

### Files

- sync/src/analytics/queries/site-operational-metadata-gateway.ts: the Gateway reader.

- Zod validation. An absent column fails; only null/"" mean no value.

- One page (pageSize: 1000, maxPages: 1), so a read can't straddle a republish. A full page (possible truncation) is refused.

- Numeric fields must be non-negative, and classrooms and occupancy must be integers.

- A floor of 100 rows.

- A single refreshed_at with a 3 h max age and a future-timestamp guard. The table has no source_run_id, so refreshed_at stands in for it.

- Tuition arrives as a NUMERIC string and is converted to a number; schema_ui is mapped to schemaUi; NULL becomes absent.

- The client is built lazily, so importing the module never captures env before dotenv loads.

- sync/src/upstream/rhodes/site-metadata-shadow-compare.ts: compares the two merges per field. Each field is counted as same / differs / only-incumbent / only-Surtr / both-absent, plus a separate provenance-mismatch count.

- Duplicate slugs are never compared and never clean.

- Tuition is compared to the cent.

- Contact (email/phone) values are redacted in examples; presence is kept.

- Examples and slug lists are capped at 10; counts are exact.

- Also holds the throttle.

- sync/src/upstream/rhodes/sync.ts: the gate, collecting the merge, the shadow run, and the skip rules.

- sync/src/analytics-worker/index.ts: the throttle is created once per worker, and the shadow suffix is added to the summary.

- sync/src/scripts/dry-run-rhodes-merger-shadow.ts (pnpm run dry-run-rhodes-merger-shadow): runs the real merger once in shadow mode with a no-op Rhodes writer. It prints counts and slugs only. It follows the ESM rule: dotenv first, then dynamic import().

- .env.example: documents RHODES_MERGER_READ.

### Why there is no gateway mode

Where merged values should be written after cutover is undecided (Benji + Keval). The options are the external Rhodes deployment (archived per AI-183), an Aerie-local, override-aware apply step (depends on AERIE-2365), or retiring the task. A gateway mode would publish from Surtr, so it has to wait for that decision; building it now would mean guessing the write contract. Shadow doesn't depend on the decision, and its evidence feeds into it.

## Business Value

A1 is the last and most complex object keeping analytics-worker on the EC2 box. This PR lets the Surtr replacement be checked against the live merge in production with no behaviour change and no new write path. The write-target decision can then rest on measured per-field agreement instead of the one-off analysis in closed #1427. The local run below already shows 0 value disagreements on any field where both merges have a value. Every divergence is a value Surtr has and Aerie's merge lacks, and each one traces to a known join difference. That lowers the risk of the eventual cutover or retirement, which in turn removes ~4 merge modules and a 5-minute scheduler from the worker.

## Manual Effort Estimate

~12 hours of focused work by hand, proposed for Keval to confirm or adjust. Breakdown:

- ~2 h: reading the merger, field-merge, the A4 pattern, and the Surtr procedure/table.

- ~3 h: reader and validation.

- ~3 h: compare, gate, and throttle.

- ~3 h: tests.

- ~1 h: dry-run script and the live run.

## Testing / evidence

- pnpm --filter @bran/sync typecheck: clean. biome check and the root pnpm lint (boundaries, convex paths, read bounds, test architecture, knowledge): clean. The 2 warnings are pre-existing and in unrelated files.

- Sync tests with vitest run --maxWorkers=2: 83 files, 1424 tests passed. That includes 61 new tests: 33 for the reader, 12 for compare/throttle, and 16 for the gate/orchestrator.

- New orchestrator tests prove:

- legacy never calls the Gateway.

- shadow makes exactly the same Rhodes upserts as legacy.

- A Gateway error leaves both writes and errors untouched.

- The throttle allows 1 read per hour across 5-min ticks.

- ISP and HubSpot bulk failures skip the compare without using the throttle slot.

- An absent column fails validation; it never becomes NULL.

- Error messages never echo field values.

- Live read-only dry-run (details are in a PR comment): the real Gateway read (172 rows, one page) plus Aerie's merge computed locally (HubSpot from Redshift, ISP from DynamoDB/S3). Nothing was written to Rhodes, Convex or Redshift. Rhodes listSites was stubbed, because no Rhodes credentials exist locally. The stub reads Surtr's Redshift mirror of Aerie sites (staging_education_rhodes.raw_sites) with a read-only SELECT.

## Not covered

- Cutover and the write target: there is no gateway mode (see above).

- Prod shadow window: setting RHODES_MERGER_READ=shadow on EC2 is Keval's step (X3). Shadow only runs where the merger itself runs, i.e. where RHODES_CONVEX_SITE_URL + RHODES_API_KEY are set. Whether A1 runs in prod at all is still the spec's HARD blocker to verify.

- Surtr lineage columns (source_run_id / source_published_at / TIMESTAMPTZ): not added. The reader parses the naive refreshed_at as UTC (GETDATE()).

- Deleting the legacy merge files happens in a follow-up, after the decision.

Linear: AERIE-2610

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

Binds the delegated Sindri identity and validates what Sindri returns before Aerie records a result (AERIE-2582: Yibin #9 on Aerie #1439). This completes the ticket.

- One capacity user. Capacity automation now runs as a single Aerie user: the one in CAPACITY_AUTOMATION_ACTOR_EMAIL (already the user that files record-mode DD requests). That setting is now required, and CAPACITY_SINDRI_ACT_AS_WORKOS_USER_ID is gone.

- Before anything is uploaded, the run looks up that user's Sindri link. If there isn't one yet, it sets it up automatically, the same way Aerie does for anyone on first Sindri use. If setup fails (for example, Sindri is down), the run retries later instead of ending.

- The run then pins that Sindri identity (WorkOS user, Aerie user, org) as sindriIdentity. Every later call for the run acts as the pinned identity, and each dispatch and poll re-checks it. If the link is removed or changes mid-run, the run ends.

- Ownership checks.

- Start: the response's workflowInstanceId and workflow.workflowInstanceId must be the configured instance, or the run is not marked running.

- Poll: once Sindri reports a terminal status, the status response and then the inspect response must report the same run id, the run's workflowInstanceId, and startedBy equal to the pinned WorkOS user. This happens before anything is recorded or any artifact is copied. Sindri's run responses carry no org field; Sindri scopes these reads to the pinned org.

- A run still in progress, or a response with no status, keeps polling as before. The check runs once there is something to record.

- Failures end the run unresolved with a new unresolvedCause: identity. There are no retries, because this is a configuration or routing error.

- Keeping data inside Aerie until the site is cleared (the third part of Yibin #9) was already done in AERIE-2356: capacitySiteAllowed gates at enqueue, before evidence is assembled or sent.

- Not changed:

- Sindri. Its act-as door already pins the org and checks live membership.

Rollout note (AERIE-2499): set CAPACITY_AUTOMATION_ACTOR_EMAIL to the capacity user and drop CAPACITY_SINDRI_ACT_AS_WORKOS_USER_ID. No manual Sindri setup is needed. Sindri's setup script (author-capacity-workflow.mjs) still prints the old variable; ignore that line.

## Test plan

- [x] chat: vitest run convex/capacityAutomation.test.ts convex/capacityAutomation/config.test.ts (190 passed)

- Start: a response naming another instance, a mismatched workflow, or no instance is rejected and never marked running.

- Poll: a finished run reporting another run, instance, or starter, or no owner fields, ends identity without copying artifacts. A failed run with the wrong starter is identity, not sindri. An inspect response for another run is rejected. An in-progress run keeps polling. An owned run is recorded.

- Binding: pins the capacity user's link. Asks for setup when there is no link or only a deactivated one. Refuses an unknown email and a link without an org. Keeps the pinned identity after the configured user changes. Refuses a pinned link that was deactivated, moved org, or relinked. Refuses an inactive run.

- Through the actions: a queued run whose capacity user doesn't exist ends identity with no fetch. A run whose Sindri setup fails is requeued, not ended. A running run whose pinned link was removed ends identity without polling Sindri.

- [x] tsc --noEmit (chat), Biome, and the pre-commit hook.

## Summary

- Accept previous-quarter CollectIQ data through 13:00 UTC on day 2 of the new quarter and keep the snapshot labeled with its source quarter.

- After the cutoff, fail immediately if the source still reports the previous quarter; require Forecast and QTD labels to agree.

- Handle the Q4-to-Q1 year rollover and pass the same run timestamp through the local runner.

## Verification

- uv run --extra dev pytest — 60 passed

- ruff check src tests scripts/run_local.py — passed

- Local live-sheet dry run — 8 business units, 2026-Q3, no Redshift or S3 writes.

## Operational note

- The full-replace table behavior is unchanged. The new quarter replaces the previous-quarter rows when its source data arrives. This change has not been deployed.

## Demo


User-approved POC acceptance: PASS. The attached smoke evidence records the replay as Blocked because the production-only node input is unavailable; this is accepted for this proof of concept and is not a production-readiness claim.

## Linear

https://linear.app/builder-team/issue/AI-942/evals-execute-real-node-replays-from-immutable-entry-snapshots

## Summary

- Capture immutable node-entry snapshots with repository state, prompt/template provenance, runtime settings, and content-addressed evidence.

- Restore those snapshots into owned replay worktrees and execute production node and feature replays through the registered Codex engine.

- Persist real thread, turn, action, artifact, lifecycle, interruption, and recovery evidence while keeping fixture execution explicitly marked.

- Support candidate template byte substitution with hash validation and preserve dynamic/path provenance.

## Business Value

Eval comparisons now exercise the real node runtime from the exact captured entry boundary, so regressions can be attributed to the product or template with reproducible repository and prompt evidence instead of fixture-only behavior or mutable current checkouts.

## Implementation Effort

Large: this spans SQLite capture/export, eval manifest validation, immutable bundle restoration, real agent execution, lifecycle controls, feature replay orchestration, reporting, TypeScript contracts, documentation, and focused regression coverage.

## Test Plan

- [x] cargo test --locked --manifest-path src-tauri/Cargo.toml --lib (318 passed, 2 ignored)

- [x] pnpm test:replay-reports

- [x] pnpm exec tsc --noEmit

- [x] cargo check --locked --manifest-path src-tauri/Cargo.toml

- [x] git diff --check

- [x] Focused replay, eval-contract, feature-replay, eval-scoring, and workflow checks passed.

## Acceptance Limitations

- A live Codex provider turn was not run in this environment; real-agent coverage uses the provider-neutral engine boundary and recorded fixture regression seams. The production path blocks when Codex cannot prove the run-owned workspace and records that limitation as evidence.

- This POC is accepted with its production-node limitation; production readiness is explicitly out of scope for this merge.

## Smoke test result

PASS: User explicitly accepted the blocked POC replay and requested merge; no production-readiness claim.

## Demo


## Summary

Pomodoro phase changes (Focus → Break, Break → Focus) now play a macOS system sound and show a notification banner, including when Shipyard is behind other apps or minimized.

- src/pomodoro.ts: new refreshPomodoroTimer returns { state, phaseChange }. A refresh that crosses one or more boundaries reports a single change for the current phase, so sleeping through several phases gives one alert. advancePomodoroTimer now wraps it.

- PomodoroTray: transitions are computed against a ref, outside React state updaters, so StrictMode double-invocation cannot double-alert. Only the running refresh loop announces. Start, Pause, Resume and Reset never do. Start requests notification permission once.

- src/pomodoroAlerts.ts: plays the sound through a new play_pomodoro_sound command (AppKit NSSound: Glass when a break starts, Hero when focus starts) and sends a silent banner ("Break started · 5 min" / "Focus started · 25 min") via tauri-plugin-notification. If the native sound fails, a short Web Audio tone plays instead.

- Skip control: a new Skip button jumps to the start of the next phase. Its accessible name is "Skip to break" or "Skip to focus". If the timer is running, it keeps running and plays the normal phase-change alert, so you can test alerts without waiting 25 minutes. If the timer is idle or paused, Skip moves to the next phase silently and leaves it idle or paused.

- tauri-plugin-notification ~2.4 (Rust + JS) is registered, and notification:default is added to the capability. It is pinned to 2.4 because 2.5 requires a Tauri upgrade.

- tauri.conf.json: the main window gets "backgroundThrottling": "disabled" so WKWebView keeps the 1 s timer running while hidden or minimized (macOS 14+).

### Implementation note

On desktop, the plugin always reports notification permission as granted and cannot tell whether macOS actually shows the banner. So the sound is played natively and separately from the banner rather than attached to the notification. That way the sound still plays if the user turns off Shipyard banners in System Settings, and the sound doesn't play twice.

## Tests

- pnpm test:pomodoro: covers a single change firing once, Focus → Break → Focus titles, a multi-cycle sleep collapsing to one change, manual controls never firing, Skip behaviour when running, idle and paused, and UI-level alerts under StrictMode (once per change, hidden popover, visibilitychange after a long sleep).

- cargo test --lib pomodoro::

- pnpm build, pnpm theme:check

### Manual check (pending)

> In pnpm tauri dev, the notification plugin sends banners as Terminal (com.apple.Terminal) because the dev binary isn't a bundled app. macOS only shows them if Terminal is allowed to send notifications. To check banners, use a bundled build, or allow Terminal in System Settings → Notifications.

- [ ] Start the timer and press Skip, confirm that Glass and the "Break started · 5 min" banner appear right away.

- [ ] Start Focus, minimise or hide Shipyard, confirm that Glass and the "Break started · 5 min" banner arrive on time.

- [ ] Confirm that Break → Focus plays Hero.

- [ ] Deny notifications in System Settings, confirm that the sound still plays.

## Linear

https://linear.app/builder-team/issue/AI-949/play-a-sound-and-show-a-macos-notification-when-the-pomodoro-timer

## Summary

- Prepare Shipyard 0.6.10 with the approved public release notes.

## Business Value

- Gives users read-only Companion lookups across Shipyard data, more dependable replay evaluations, clearer Pomodoro transitions, and resilient Pi image attachments.

## Implementation Effort

- Metadata-only change: one version bump and one public release-notes file.

## Test Plan

- [x] pnpm test:release

- [x] git diff --check

> [!IMPORTANT]

> Merge/deploy companion: [AI-Builder-Team/Surtr#2091](https://github.com/AI-Builder-Team/Surtr/pull/2091) (SURTR-1542). It applies the identical package latest-week tie-break (ORDER BY week_start DESC, id DESC) to Surtr's mart_education.sp_refresh_aerie_xo_contractor_package. The two must merge and deploy together; otherwise this repo's query and Surtr's mart pick differently on any future tie, and the shadow compare diverges. Deploy order for this PR: Convex first or together with the worker (see *Partial publishes* below).

> [!WARNING]

> Source freshness: the upstream ledger is about 3 weeks behind. As of 2026-09-29, SELECT MAX(week_start), COUNT(*) FROM staging_finance_xo.raw_contractor_invoices returns 2026-09-07 / 152,718 rows, so the latest invoiced week is 22 days old. Ingest is alive: on 2026-09-25 the max was 2026-08-31 with about 151k rows. Whichever read mode ships, contractor package rates and trailing-52-week totals will be only as current as this table. That also means neither side of the shadow compare can be fresher than 2026-09-07. It's worth confirming with the xo-contractor-invoices-refresh owner whether a ~3-week lag is normal XO invoicing lag or a stalled window.

## The live bug (fixed first, independent of the migration below)

sync/src/redshift/xo-contractor-identity.ts and xo-contractor-package.ts queried core_finance.xo_contractor_invoices_raw, a table that no longer exists in the warehouse. Surtr's seed-gateway-aerie.ts (dated 2026-08-31) flagged that Aerie's contractor sync should be repointed.

These two tasks are not behind LEGACY_EDUCATION_WAREHOUSE_READS_ENABLED (financial-worker's own comment: *"XO contractor tasks remain active"*). They run in production, and since the underlying table moved, every run has failed its query and published nothing. The failure wasn't silent: each tick returned status: "degraded" with error: query: …. The data just never refreshed.

The real, current table is staging_finance_xo.raw_contractor_invoices, and it has an exact column match for these queries. Both queries now point at it.

Verified against real production Redshift when this was first opened: the fixed queries return 3,059 identity and 3,026 package contractors. Surtr's mart_education.aerie_xo_contractor_identity / aerie_xo_contractor_package return 3,058 / 3,026. Surtr's procedures are a verbatim lift of these same queries, so near-equal counts are expected. The counts confirm the repoint reads the right ledger. They are not an independent cross-check.

pg output order changes in this PR. The identity query's alias LISTAGG now has a full sort key (see below), so the aliases array order differs from what the old query would have produced. No consumer has seen the old order recently: the pg path has published nothing since the table moved. The Convex alias index also re-sorts longest-first on read.

## The migration (F1/F2, matching A4's pattern)

Surtr exposes both marts as Gateway sources, aerie-xo-contractor-identity and aerie-xo-contractor-package, already granted to the live Aerie key.

- Gateway readers. redshift/xo-contractor-identity-gateway.ts / xo-contractor-package-gateway.ts are field-complete and Zod-validated. The identity reader drops rows whose aliases all trim away, exactly as the pg reader does.

- Payload shape. Every published row, from pg or the Gateway, is mapped field by field to a new shared wire contract, @bran/contracts/xo-contractor-sync. Package optionals are omitted when null, never sent as null. This matters because Gateway rows carry sourceRunId, and Convex's upsertXoContractor* validators reject undeclared fields. The first version of this PR would have failed every gateway-mode batch. The contract is locked from both sides:

- a chat test reads the registered mutations' own validators via exportArgs()

- sync tests check every record the worker sends

- a convex-test case proves a record carrying sourceRunId is rejected

- Lineage. sourceRunId is used only to validate and log, never published. gateway mode refuses a read whose rows span two mart publishes (mixed sourceRunId); that tick degrades and the next one retries. Otherwise it logs the one source run it published.

- Deterministic package pick (Keval's decision, 2026-09-29). When a contractor has several regular-payment rows in their latest week, the pick is now ROW_NUMBER() OVER (PARTITION BY contractor_id ORDER BY week_start DESC, id DESC): the highest invoice row id wins. week_start DESC alone tied, and Redshift breaks ROW_NUMBER ties nondeterministically, so the published rate could change run to run.

- A read-only check on 2026-09-29 found id unique and non-null: 152,718 rows, 152,718 non-null ids, 152,718 distinct ids.

- A before/after comparison changed no output: 3,046 rows under both orders, 0 rows in only one of them, and 0 contractors with a tied latest week.

- The Surtr side is the companion PR above.

- Partial publishes are reported, not hidden. Publication is not atomic: each 100-row batch is its own Convex mutation, and each mutation isolates every record's write. Both refreshes now publish through analytics/xo-contractor-publish.ts.

- records is the count Convex confirmed it wrote, never the attempted count.

- Any shortfall is an error naming it, for example PARTIAL publish: 200 of 3046 rows confirmed before this batch failed or Convex rejected 3 of 3046 rows. The tick degrades, and the next tick re-sends every row (upserts are idempotent per contractorId).

- To make per-record rejections visible, upsertXoContractorIdentity now returns { errors, total }, as upsertXoContractorPackage already did (XoContractorUpsertResult). This is a small Convex change that ships with this PR.

- Fail-closed: a batch counts as written only if its response acknowledges exactly that batch. A missing, malformed or wrong-total response counts as unacknowledged and is reported. Deploy Convex before, or together with, the worker; otherwise identity ticks report "unacknowledged" (degraded) until Convex catches up, although the rows are still sent.

- External error text (Gateway, Redshift, Convex responses) is flattened to one line and capped at 300 characters before it reaches a log line or tick summary (boundedErrMsg).

- Population floor. A read that "succeeds" with too few rows is refused before anything is published, in every mode (analytics/xo-contractor-population.ts). This covers the direct Redshift path, not just the Gateway: an empty read used to publish nothing and still report success with records: 0. The floor is 500 rows, the same as the Gateway readers' own guard, which stays in place; production has about 3,050 rows per entity. A read below it is an error, nothing is sent, and the tick degrades.

- Strict, all-or-nothing parsing, on both sides.

- z.coerce.number() turned null and "" into 0 and true into 1, and z.coerce.string() turned null into "null". An incomplete row could become a plausible contractor id, dollar amount or date.

- All XO readers (pg and Gateway, identity and package) now use the same parsers from redshift/xo-contractor-fields.ts:

- contractorIdNumber: a positive integer

- requiredFiniteNumber / nullableFiniteNumber: a finite number, or a string that is wholly a plain decimal (so 0x10 and 1e3 are rejected)

- isoDateText: the whole value must be an ISO date (optionally with a time part) naming a real calendar day, normalised to YYYY-MM-DD (so 2026-02-30 and 2026-01-01garbage are rejected)

- Optional team_name / company / currency use one nullableText parser, so "" is treated as absent on both sides; pg used to publish "" where the Gateway omitted it.

- source_run_id must be one printable, whitespace-free token (lineageRunId), because it goes into worker log lines.

- Monetary columns keep their sign. The ledger and the mart DDL put no sign constraint on them, and trailing_52w_paid_usd sums every invoice row.

- The pg readers now use parseRowsStrict instead of safeParseRows. One invalid row fails the whole read (the tick degrades and Convex keeps the last good snapshot) rather than silently dropping the row and publishing a partial snapshot as a success. The Gateway readers already worked this way.

- Shadow compare. analytics/xo-contractor-shadow-compare.ts compares field by field, keyed by contractorId. The pg side has no sourceRunId (it recomputes live on every call), so lineage is checked on the Gateway side only, as in A5.

- A failed or unclean shadow check is visible. In shadow mode, if the Gateway read or compare fails, or the check runs but comes back not clean, the rows are still published from Redshift. The refresh returns shadowIssue, which is PII-free:

- check failed: …, or

- not clean: N mismatched, N pg-only, N Gateway-only row(s), <lineage>

- incomplete: trailing52wPaidUsd not compared (pg day X vs mart publish day Y) when the run was clean but skipped the date-anchored field

The financial worker reports that tick as degraded, so a run without complete, clean parity evidence can't pass for a clean check. The compare result also counts duplicate contractor ids on each side. All shadow-side work sits inside one try, so nothing on the shadow side can block publishing from pg.

- XO_CONTRACTOR_READ typos are visible. An unrecognised value (e.g. gatewayy) still falls back to pg, so data keeps publishing, but the tick is degraded with a config: note.

- Deterministic aliases. The pg identity query now uses Surtr's mart ordering exactly: ORDER BY LENGTH(a.alias) DESC, a.alias ASC. LENGTH DESC alone left same-length aliases tied, and Redshift breaks LISTAGG ties nondeterministically. Aliases are compared order-sensitively, which is only safe because both sides now share that key.

- snapshotDate is not field-compared. It's a run-date stamp: pg gets the worker's CURRENT_DATE on every tick. The mart gets its own publish date, and Surtr's replay-idempotency guard deliberately leaves an already-published source run untouched, so that date can trail the worker's by a day or more. Comparing it would flag every row on any tick that lands on a different UTC day than the mart's last publish, which says nothing about data agreement. Surtr's own replay diff excludes snapshot_date for the same reason. Both dates are still reported as pgSnapshotDate / gatewaySnapshotDate.

- trailing52wPaidUsd is compared only when the days match. It sums a window anchored on that same CURRENT_DATE. When the two days differ it goes into skippedFields instead of producing a false mismatch.

- PII safety. Every compared field is redacted in a mismatch record. Canonical names, aliases and weekly pay are real compensation data tied to real people, so a mismatch shows which field and which id, and never a name or dollar amount in a CloudWatch log line. Dates are not redacted.

- Env gate. XO_CONTRACTOR_READ=pg|shadow|gateway (xo-contractor-read-mode.ts, documented in .env.example) defaults to pg. Both refresh functions share it, since they are the same migration object and always move together.

- Dry-run scripts.

- dry-run-xo-contractor-pg-fix proves the table fix against real Redshift. It exits 1 below the 500-row floor, so an empty read can't pass as confirmation.

- dry-run-xo-contractor-shadow runs a full shadow compare with PII-redacted output. It also prints both snapshot dates, any skipped fields and duplicate counts, and exits 0 only when the run is clean AND complete.

- Both scripts print only bounded error text. It uses await import() rather than a static import for credential-dependent modules, per the ESM/dotenv-ordering fix Mercy flagged on the A5 PR.

The existing regression-guard test that asserted the *old* table name has been fixed. It now asserts the new table and guards against regressing back to the dead one.

## Verified locally

- Real production Redshift: the table fix (counts above) and today's freshness query (warning at the top). Both were read-only.

- Live Gateway shadow dry-run, 2026-09-29. This ran dry-run-xo-contractor-shadow against real Redshift and the real Surtr Gateway. It was read-only: nothing was sent to Convex, and only counts and field names were printed.

- Identity: 3,078 / 3,078 matched, clean.

- Package: 3,046 / 3,046 matched, clean.

- Later runs used the strict, all-or-nothing, whole-value parsers, and no row was rejected on either side. They landed on a day when the pg date and the mart publish date were aligned (2026-09-29), so trailing52wPaidUsd was compared as well. The latest run reported "Clean and complete".

- Verbatim output is in the PR comments.

- Tests:

- sync: 90 files, 1,585 tests, all green

- @bran/contracts: 93 files, 1,259 tests, including the new contract test

- chat, touched files only: financialContractorPackage.test.ts (9 tests, including the validator-contract and upsert-result tests) and analyticsSyncSecurity.test.ts (18 tests)

- the full chat suite was not run

- Typecheck: clean across the workspace.

- Lint: clean. The only output is 2 warnings in chat/skill/forge-api/scripts/sindri.mjs, which this PR doesn't touch.

## Known limitations (not fixed here)

- Gateway mode still needs Redshift credentials. In financial-worker, both XO tasks are still gated on isRedshiftConfigured(), so gateway mode can't run without Redshift env vars. That's fine while pg stays the rollback; it needs revisiting before Redshift creds are torn down.

Linear: [AERIE-2489](https://linear.app/builder-team/issue/AERIE-2489/f1f2-fix-broken-xo-contractor-sync-gateway-parity-identity-package)

## Business Value

This fixes a production task that has failed on every run for weeks. Contractor identity and compensation data feeding Aerie's finance dashboards stopped refreshing when the source table moved; the worker reported degraded ticks, but nothing repointed it. That makes this a real correctness fix, not just migration progress.

It also lands the F1/F2 Gateway migration object, following the A4 pattern. Gateway mode can now actually publish, and the shadow compare is deterministic, so a clean shadow run means real parity rather than noise. Once shadow is confirmed clean, this sync can cut over to Surtr's Gateway the way School Directories already has, moving one more EC2 worker task closer to full teardown.

## Manual Effort Estimate

About 2 days by hand. Proposed; Keval to confirm or adjust.

- Diagnosing the break: trace which table Aerie queries, confirm it no longer exists, find the real table and its pipeline, and check column and shape compatibility.

- Fixing it: repoint both queries and validate against real Redshift.

- Migration half: Gateway readers, the PII-aware shadow compare, the env gate, two dry-run scripts and about 40 tests.

- Fix round:

- the shared Convex payload contract with validator-derived tests

- lineage validation

- alias tie-break alignment against the Surtr procedure

- date-aware compare semantics

- the population floor, strict numeric parsing and shadow-failure observability

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

chat/components/dashboards/financials/qtd-reports-view.test.tsx started failing on main (6df20f88f) on 2026-10-01. Linear: [AERIE-2662](https://linear.app/builder-team/issue/AERIE-2662/fix-qtd-reports-test-broken-by-the-q4-quarter-rollover).

Root cause: QtdReportsView (qtdCurrentPeriodCode()) and QtdContractorTrace (getQuarterBoundaries()) work out the current quarter from the real clock, but the test fixtures describe 2026-Q3 (Jul-Sep 2026). Once the clock entered Q4, the fixture QB transactions and XO invoices fell into the trace's "Previous Quarter" bucket. Four drilldown tests could then no longer find the ... current quarter QuickBooks transactions tables or the XO invoice toggle.

Fix (test-only): the test now fakes only Date (vi.useFakeTimers({ toFake: ["Date"] }), the same convention as app/(main)/sync/__tests__/page.test.tsx). It pins the clock to 2026-08-18T12:00:00Z, which is inside the fixtures' quarter and the day after their 2026-08-17 reporting cutoff, and restores real timers in afterEach. The component is untouched.

## Business Value

This unblocks CI. The Test job has been red on every Aerie PR since the quarter rolled over, so nothing could show a green check. The suite also stops depending on the calendar, so it won't break again at the next quarter boundary.

## Manual Effort Estimate

About 1 hour of focused work by hand: reproduce, trace the quarter logic through the view and contractor trace, pin the clock, sweep the package for other clock-dependent quarter tests, and run checks. *Proposed by Claude. Keval, please confirm or adjust.*

## Testing

- vitest run components/dashboards/financials/qtd-reports-view.test.tsx: before the fix, 4 failed and 30 passed; after it, 34/34 pass. These are the same 4 failures CI shows on recent PRs (for example run 36818755046), and that is the only failing file there.

- Sweep for other clock-dependent quarter/period tests: I ran the 51 other chat test files that touch quarter, period, QTD, YTD or fiscal logic (financials, education P&L, consolidated, school-year-period, the finance Convex dashboards, the public API, and others). All passed (1405 passed, 17 skipped), so nothing else needed fixing.

- biome check on the touched file, pnpm lint:test-architecture, and tsc --noEmit (chat) are clean. The pre-commit hook (biome and chat typecheck) passed.

## Not covered

- No component changes. The quarter-boundary maths in qtd-contractor-trace.tsx and qtdCurrentPeriodCode() is correct across the Q4 to Q1 year wrap.

- Possible follow-up, not changed here: several QTD column labels are hardcoded to the first school-year quarter: "Q1 SY 26/27 Model" and "QTG for Q1" (guide staffing and leadership comparison), "Q1 SY26/27" (facilities), and "Q1 HC" (unit economics). They pair with the q1* budget fields. The page now asks for 2026-Q4 (SY Q2) on its period-scoped sections, so these labels may no longer describe what users see. Someone who owns QTD should check this.

- I did not verify that the warehouse has 2026-Q4 QTD data yet. On the first days of a quarter the page asks for a period that may still be nearly empty.

## Testing contract

### What this PR delivers

A test-only fix that makes the QTD Reports view tests independent of the current date, so CI Test goes green again.

### Who uses it and where

Aerie engineers and CI. There is no change to the product surface (Financials → QTD Reports).

### Conditions needed

None beyond the unit test environment. The test pins the clock itself.

### Expected behavior and examples

qtd-reports-view.test.tsx passes on any real date: inside Q3, after the Q4 rollover, and across the Q4 to Q1 year boundary. Production behavior is unchanged.

### Limits and unanswered questions

See "Not covered" above.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

## Summary

- Remove pg_temp from the Q118 Core procedure SECURITY DEFINER search path because Redshift rejects it as a nonexistent schema at call time.

- Add a regression contract preventing the unsupported search-path entry.

## Verification

- Full runner suite: 232 passed.

- Pinned Ruff and format checks passed.

- Corrected procedure DDL applied to Production.

- Core-only recovery succeeded for June source run 748ad378-0c92-4252-9bd7-dafae187d163.

- June recovery now has 419 raw rows, 18 Core rows, and one Core receipt.

- No new QuickBooks pull or raw publication was performed during recovery.