The Trilogy Times

## Summary

- Add a synchronous school_opening agent answers endpoint at POST /v1/agent/answers

- Add the school-opening matrix/profile contracts, Buildout session-start resolution, and structured answer/QC runtime

- Document the endpoint in OpenAPI and cover public API, matrix, provider-failure, and output-quality paths with tests

## Why

We need a deployable short-term API surface for the first Agent-in-a-Box use case without taking on the larger durable agent hosting migration in this PR. The endpoint answers one bounded school-opening question using the configured prompt, skill rules, Buildout session start, inspected milestone data, and a QC pass.

## Business Value

External or internal agents can now ask Aerie for a structured school-opening answer that includes the direct answer, selected matrix cell, parent message, underlying data, methodology/worked example, evidence, and the brainlift/config context used to produce it.

## Breaking changes

None. This adds a new authenticated public API route and new contract exports.

## Test plan

- [x] PNPM_STORE_DIR=/Users/alghurab/Library/pnpm/store/v10 pnpm --filter @bran/chat lint

- [x] PNPM_STORE_DIR=/Users/alghurab/Library/pnpm/store/v10 pnpm --filter @bran/chat typecheck

- [x] PNPM_STORE_DIR=/Users/alghurab/Library/pnpm/store/v10 pnpm --filter @bran/contracts typecheck

- [x] PNPM_STORE_DIR=/Users/alghurab/Library/pnpm/store/v10 pnpm --filter @bran/chat exec vitest run lib/__tests__/agent-answer-school-opening.test.ts convex/publicApi/agentAnswersHttp.test.ts lib/public-api/__tests__/openapi.test.ts convex/publicApi/operationsHttp.test.ts convex/publicApi/admissionsDomainsHttp.test.ts convex/publicApi/financialsHttp.test.ts convex/publicApi/ontologyHttp.test.ts convex/publicApi/http.test.ts

- [x] PNPM_STORE_DIR=/Users/alghurab/Library/pnpm/store/v10 pnpm --filter @bran/contracts test -- src/school-opening-matrix.test.ts

- [x] Live dev API sweep: 5/5 answered across Austin, Houston, Edmond, Boca Raton, plus Spring 27 session-start override; bad generic scheduled-opening phrasing count was 0

Live response artifacts are saved locally at /tmp/aerie-school-opening-pr-gate-2026-06-19T05-56-49-894Z.

## Demo

<img width="2237" height="1636" alt="image" src="https://github.com/user-attachments/assets/99f0bbaa-9ba3-4ad5-aa39-8e0496f6c9c6" />

19 June Financials batch — three changes, all on the "Actual vs Model" Financials surface.

## 1. AERIE-421 — Live-Redshift Financials migration ([#449](https://github.com/AI-Builder-Team/Aerie/pull/449))

Serve every Financials "Actual vs Model" surface (consolidated + per-school P&L, headcount, programs, facilities, unitemized, drill-downs, CSV export) live from Redshift via Convex "use node" actions, replacing the nightly-synced plMonthlyRecords / plTransactions tables.

- New chat/convex/finance/dashboards/financialLive.ts — one action per surface; each opens a one-shot Redshift connection, maps rows into the same pure reducers the synced queries used, so the two paths can't drift.

- Pure reducers extracted to ctx-free modules (consolidatedShared.ts, consolidatedReducers.ts, consolidatedDetailReducers.ts, perSchoolReducers.ts) — one source of truth, unit-tested in isolation.

- Frontend reads through a new useLiveSection hook: a one-shot action mapped into the same SectionResult shape the synced useQuery sections exposed, so the table components are unchanged (on-demand "Refresh" rather than a live subscription).

- Dropped the plMonthlyRecords + plTransactions tables and all their sync / prune / backfill code (sync worker, analytics refresh jobs, upsert/prune Convex mutations + tests) — this is the bulk of the −16k diff.

- Authorization runs requireSchoolPlAccess at the action boundary before any Redshift connection (docs/endpoint-hardening.md). Quarter/period inputs are regex-validated and inlined as literals (static SQL, no injection surface).

- Why: reading current Redshift state directly makes the dashboard immune to the additive-only sync's orphan / phantom-overage artifacts (the root cause behind the AAC / Lake Forest / Nova Bastrop overage diagnoses).

- New deps: pg@8.17.2, @types/pg@8.11.11 (exact-pinned).

## 2. Pin "Schools – Actual vs Model" to a single period + rename page

- Remove the quarter picker — PERIOD_OPTIONS had a single entry, so it was a no-op dropdown; period is now a fixed const (dropped the dead periodOptions memo + setPeriod).

- Drop the "Jan–Jun 2026" date prefix from the Consolidated P&L subtitle (removed the now-unused subtitleLabel prop).

- Rename the page "Schools – Actual vs Model" → "Actual vs Model (Schools)".

## 3. Test fix — align stale tests with the migration

- financials-kpi-cards.test.tsx and use-consolidated-unitemized.test.tsx still mocked the old reactive queries, leaving api.finance.dashboards.financialLive undefined → 9 tests threw at render in CI.

- Re-pointed both at useLiveSection / the financialLive actions, and rewrote the unitemized test for the new single-action, server-side fan-out shape (drops the obsolete client-side useQueries dedup / per-school-partial-failure cases; adds the {schools, years} payload, all-or-nothing failure fold, loading gate, and disabled / empty-schools short-circuits).

## Testing

- pnpm typecheck, pnpm biome check, and the full vitest suite are green in CI.

- The authorized success path of the live actions needs a real Redshift connection, so it is validated manually against the dev deployment, not in CI — the auth-rejection gate and the pure mapper/reducer paths are covered by unit tests.

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

## Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/8d57277f-90f3-4059-ab9b-591543ca81f9" />

Proves the fix: the per-school P&L reader now includes a dedicated QB entity's whole realm, so Alpha Anywhere Center's unclassed (Not Specified) tuition is no longer dropped — Q1'26 tuition reads the true $446,807 instead of $307,500.

Backend — per-school P&L includes the dedicated entity's whole realm

Ran python3 /tmp/demo-aerie434.py, which executes the reader's per-school predicate (the exact WHERE the diff adds to financialLive.ts) against Redshift, OLD vs NEW:

Q1'26 50000 Tuition — Alpha Anywhere Center
OLD (class-only)               =   307,500.00
NEW (class + dedicated realm)  =   446,807.02   (QuickBooks: 446,807.02)

The NEW predicate matches QuickBooks to the cent.

Changed code is exercised directly — pnpm vitest run convex/finance/dashboards/financialLive.test.ts. The suite imports and calls the new plMonthlyBySchoolSql / plTransactionsBySchoolSql, asserting both substitute every {CLASS_IN} (the replace→replaceAll guard) and emit the dedicated-entity arm:

✓ convex/finance/dashboards/financialLive.test.ts (30 tests)
Test Files  1 passed (1)
Tests  30 passed (30)

Most at risk — over-including another school's data (the new arm pulls a *whole* realm). Verified the self-identifying subquery resolves to exactly one dedicated entity, and the read pulls only Alpha Anywhere Center's rows across its three realms:

dedicated companies resolved: ['alpha_anywhere_center_llc']
(company_id, class_name) the NEW query pulls:
alpha                        | Alpha Anywhere Center
alpha_anywhere_center_llc    | Alpha Anywhere Center
alpha_anywhere_center_llc    | Not Specified      <- the previously-dropped rows
alpha_schools_llc            | Alpha Anywhere Center

No other school's data enters the result. The consolidated "All Schools" reader is untouched by this PR (see the Scope note below).

---

## Summary

On Actual vs Model (Schools), a school backed by a dedicated QuickBooks entity lost any of that entity's rows booked without a class (class_name = 'Not Specified'). The per-school live reader (financialLive.ts) scoped purely by class_name IN (canonical + aliases), so the dedicated entity's unclassed rows — real revenue/spend — were silently dropped.

Alpha Anywhere Center, Q1'26: Tuition read $307,500 instead of $446,807 (−$139,307). Food Service, Financial Aid and Sibling Discount were undercounted the same way; Stripe Fees matched to the dollar because it has no unclassed rows. Unclassed bookings continue Apr–Jun (June tuition $209k unclassed), so Q2'26 and SY totals were affected too.

## Root cause

PL_MONTHLY_SELECT_BY_SCHOOL and PL_TRANSACTIONS_SELECT_BY_SCHOOL filtered only on class_name IN ({CLASS_IN}) — no company_id arm — so a dedicated entity's rows survived only when they happened to carry the canonical class. This violates the documented *"the whole dedicated realm IS the school"* semantic. Pre-existing (the retired synced path keyed school_display_name = class_name identically); exposed now by unclassed data starting Jan 2026.

## Fix

Add a self-identifying company_id arm to both per-school reads — a dedicated entity is any non-shared company_id that carries the school's class, so no external company→school map is needed:

WHERE class_name IN ({CLASS_IN})
OR company_id IN (
SELECT DISTINCT company_id FROM staging_education.quickbooks_pl_monthly
WHERE class_name IN ({CLASS_IN}) AND company_id NOT IN ('alpha','alpha_schools_llc')
)

The per-school reducers already filter only by year/period (never by schoolDisplayName), so fetching the extra rows is sufficient — no row-mapper change. SQL building is extracted into exported pure plMonthlyBySchoolSql / plTransactionsBySchoolSql so the shape is unit-tested without a Redshift connection (and to guard the replace → replaceAll substitution now that {CLASS_IN} appears twice).

## Verification

Ran the old vs new reader SQL against Redshift:

| | Q1'26 50000 Tuition |

|---|--:|

| OLD (class-only) | $307,500.00 |

| NEW (class + dedicated realm) | $446,807.02 ✅ |

The dedicated-entity subquery resolves to exactly alpha_anywhere_center_llc — no other school's data is pulled in.

## Test plan

- [x] pnpm vitest run convex/finance/dashboards/financialLive.test.ts — 30 pass (4 new)

- [x] pnpm typecheck — clean

- [x] pnpm biome check — clean

- [x] Redshift reconciliation: AAC Q1'26 tuition 307,500 → 446,807

## Scope / follow-up

In scope: per-school P&L + transaction live readers (the reported symptom). Related (separate ticket): the consolidated "All Schools" rollup leaks the same money — dedicated unclassed rows bucket to a Not Specified pseudo-school, which is in EXCLUDED_SCHOOLS, so they drop from the total. A robust fix needs company→school attribution in the consolidated reducer.

---

Stacked on #461 (AERIE-433). Linear: AERIE-434.

## What & why

Mercy (the @mercy PR-review bot) produces rich per-review data — verdict, findings, downgrade reasons, and (in the Claude CLI envelope) token usage + dollar cost — but today it all evaporates into 7-day GitHub artifacts. There's no way to answer "how many reviews ran, what did they cost, what's the approval/block rate, which repos use mercy."

This adds durable telemetry end-to-end and a Surtr /mercy dashboard to visualize it.

## How it works

mercy workflow (any repo)              Surtr (ECS) + AWS
emit_telemetry.py  ──POST(Bearer)──▶  /internal/mercy/telemetry (Hono, bearer-auth)
(fail-open, ./.trusted)                 └─ PutItem → DynamoDB surtr_mercy_telemetry
▲
/mercy page ◀── tRPC mercyStats/listMercyReviews ───────┘

- Emit (scripts/pr-review/emit_telemetry.py): fail-open, stdlib-only, runs from ./.trusted so a PR author can't tamper. Assembles one record from decision.json / review_output.json / the raw CLI envelope + github.* context and POSTs it as the workflow's last step. Never blocks a review.

- Ingest (/internal/mercy/telemetry): bearer-auth Hono route mirroring the existing observer-sweep route. Idempotent on a deterministic review_id so re-runs upsert.

- Storage: new CDK-owned DynamoDB surtr_mercy_telemetry (PK review_id; GSI per-repo; GSI global by month bucket; PITR + deletion-protection).

- Dashboard (/mercy): stat cards (reviews, approval/block rate, cost, latency p50/p95, active repos), reviews-/cost-per-day charts, findings-by-category, a per-repo table, and recent reviews with a drill-down drawer. Hand-rolled SVG charts — no new dependency.

## Multi-repo by design

Identity comes entirely from github.* context and the emit step lives in the workflow, so it drops unchanged into the future central/reusable mercy workflow — any adopting repo emits automatically once its two repo-level settings are present.

## Config already applied (this repo)

- SURTR_PROD_KEYS.MERCY_TELEMETRY_TOKEN added in Secrets Manager (us-east-1).

- Repo-level (not org-level) secrets.MERCY_TELEMETRY_TOKEN + vars.MERCY_TELEMETRY_URL set on AI-Builder-Team/Surtr.

## Still required to go live

1. cdk deploy SurtrApp-prod — creates the table, grants the ECS task role, injects the token/table env into the container.

2. Merge this PR — emit runs from the trusted (default-branch) checkout, so telemetry only starts flowing after merge (this PR itself emits nothing; fail-open). Same self-activation pattern as decide_review --ci-status.

## Test plan

- 6 new Python tests (test_emit_telemetry.py), 16 new Vitest tests (stats aggregation + ingest route auth/validation).

- 451 existing unit tests still green; tsc (src + infra) clean; cdk synth confirms the table with both GSIs + PITR + deletion-protection.

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

## Summary

Adds a daily per-team AI-spend leaderboard email — a scheduled job that ranks the members of a team/BU by their AI spend and emails the stack-rank to configurable recipients. First target: the Superbuilders team (Tech Super Builders).

Built across four increments (each brainstormed → spec → plan → TDD → reviewed):

1. Core leaderboard email — roster-first membership, per-provider split (OpenAI/Cursor + Anthropic key-name recovery), stats, fuzzy empty-group guard.

2. Branded email — Klair design system (dark bands, stat cards, rank-badge table), <$1 sub-dollar formatting.

3. Per-subscription Cc/Bcc — additive send_basic_email Cc/Bcc + config columns.

4. Single-day window — new default preceding_day (yesterday); --date for explicit day (testing/backfill); --window trailing_7d retained; global-max freshness guard skips the run when the target day isn't loaded.

## Architecture

- Standalone ECS cron (crons/ai_spend_rank_cron.py) on the existing klair-scheduled-jobs infra — deliberately decoupled from the deprecating digest/report_subscriptions engine.

- Data: reads mart_saas_metrics.fct_ai_spend + staging_gsheets.esw_people_accounts (directory). Window computed by a resolve_window helper; build_leaderboard takes explicit bounds.

- Config: standalone mart_alerts.ai_spend_rank_subscriptions table (group_by + value + recipients/cc/bcc + cadence).

- Send: reuses SES send_basic_email (extended additively with cc/bcc).

## Files (21)

klair-api/services/ai_spend_rank/ (models, config, leaderboard, render), crons/ai_spend_rank_cron.py, database/scripts/Alerts/ai_spend_rank/…create.sql, utils/email_service.py (additive cc/bcc), tests, and docs/superpowers/ (specs, plans, deploy runbook). No klair-client changes.

## Testing

- 60 unit tests pass (full feature + crons regression); ruff + pyright clean.

- Live Redshift integration test passes (Tech Super Builders).

- Validated in prod ECS: built/pushed an isolated dated image tag (not :latest), ran a --dry-run and a real send task on the klair-scheduled-jobs cluster — both exit 0, sent=1; :latest untouched, temp task-def revisions cleaned up.

## Deployment status (NOT yet live)

The EventBridge rule klair-ai-spend-rank-prod is already created but DISABLED (cron(45 12 * * ? *), 12:45 UTC daily). The config table exists with test recipients only (To = me, Bcc = a test address). Go-live steps (see docs/superpowers/ai-spend-rank-deploy-runbook.md):

1. Merge this PR.

2. Rebuild + push :latest from main.

3. Set real recipients in the config table.

4. aws events enable-rule --name klair-ai-spend-rank-prod.

Send-time caveat: 12:45 UTC must be after the daily raw+mart refresh; otherwise the freshness guard skips (safe, no email) or the global-max guard could let a provider-incomplete day through.

## Screenshot of Mail

<img width="1034" height="761" alt="image" src="https://github.com/user-attachments/assets/462da13b-6a27-4859-a7bf-1a5fa6faaaef" />

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

## Summary

- Wires the Budget Bot Google Docs add-on sidebar to klair-api's real review engine for the read path only, keyed by a bare google_doc_id, behind a new Google-OIDC auth path.

- Adds an indexed google_doc_id -> session lookup (new by_google_doc_id GSI) and a slim GET /board-doc/addon/review projection of a session's persisted findings.

- Read-only: no /propose, no write-back (later slices — the targeted-write path still carries the parked table-boundary bug).

## Why it's needed

Part of the KLAIR-2906 epic (Budget Bot Google Docs add-on, supersedes P4.5 sync). The de-risking spike proved the auth spine + UX against a canned stub; this replaces that stub with the live engine so the add-on can show real review findings for a doc the user has open, reusing existing Klair BU-scoping and session ownership rather than inventing a parallel access model.

## Changes

- Auth dependency (klair-api/utils/auth.py): get_user_from_google_oidc verifies the add-on's OIDC token (signature + aud against BBOT_ADDON_OAUTH_CLIENT_ID), gates on hd=trilogy.com + email_verified, resolves the Google email to a Klair user via UserService.get_user_by_email (no auto-create — unknown email → 401), and returns the same dict shape as get_user_from_clerk.

- google_doc_id → session resolution (session_store.py): writes a top-level google_doc_id attribute on save (only when bound); adds the by_google_doc_id GSI to the table definition; adds get_by_google_doc_id() (most-recently-updated_at wins for cloned docs) to the Protocol, in-memory, and DynamoDB backends.

- Endpoint (routers/board_doc_router.py): GET /board-doc/addon/review?google_doc_id=... with Depends(get_user_from_google_oidc); resolves doc→session (404 if none); access gate = owner OR superuser OR _assert_board_doc_bu_allowed; maps review_results → AddonReviewResponse (derived 0–100 score + one-line summary; findings flattened to severity/title/detail/section_id; pass+dismissed dropped; open-only score). Returns a needs_review state when no review has run.

- Migration script (scripts/backfill_bbot_doc_id_index.py): --ensure-gsi (UpdateTable add) + attribute backfill of legacy sessions; dry-run by default, --execute to apply.

- Add-on client (budget-bot-addon-spike/, kept local — not in this PR): getReview() now calls the real GET /addon/review; DEMO=false.

## Breaking changes

None. New endpoint + additive storage attribute/GSI; existing read/write paths unchanged. The endpoint requires the new BBOT_ADDON_OAUTH_CLIENT_ID env var (returns 500 if unset), but it is not wired into any existing flow.

## Test plan

- [x] uv run pytest tests/board_doc/test_addon_read_slice.py — 14 pass (auth dep: valid / bad aud→401 / wrong hd→403 / unverified+unknown email→401 / missing config→500; get_by_google_doc_id: hit/miss/dup→newest; /addon/review: mapping, needs_review, 404, non-owner-no-BU→403).

- [x] Regression: test_session_store.py + test_review_endpoint_persistence.py + new file — 41 pass.

- [x] ruff format + ruff check clean on changed files; pyright introduces no new errors.

- [x] Prod migration executed: by_google_doc_id GSI ACTIVE, existing docs backfilled (21/21, 0 errors).

- [ ] Live add-on round-trip (sidebar → endpoint) — pending BBOT_ADDON_OAUTH_CLIENT_ID set in a reachable klair-api env + Editor Add-on test deployment.

## Migration / rollout

- GSI by_google_doc_id already provisioned + backfilled on prod Klair-BudgetBotSessions.

- Set BBOT_ADDON_OAUTH_CLIENT_ID (the add-on's OAuth client aud) in the klair-api environment before the endpoint is usable.

## Out of scope (follow-ups)

- /propose (live section rewrite, return-without-applying).

- /apply write-back (targeted batchUpdate) — blocked on the table-boundary corruption fix.

- Editor Add-on test/Marketplace deployment for cross-doc availability.

## Summary

Connects the two SpaceX valuation surfaces so /passive-investments shows SpaceX net of estimated GP carry at the current market price, matching the /spacex-valuation page. Previously /passive-investments showed the gross market value ($6.91B = 37,339,135 SPCX shares × $185) while /spacex-valuation showed $5.90B net of ~$1.0B carry. Both pages already stand on the identical gross basis — passive-investments simply never applied the carry haircut.

At the current $185 reference price, SpaceX now shows $5.90B (net of carry) everywhere on /passive-investments, reconciling exactly with the valuation page.

## What changed (backend only — no frontend changes)

- New klair-api/config/spacex_carry.py — a faithful Python mirror of the frontend carry model (SpaceXValuationV3/data/funds.ts + calculations/valuation.ts): the 7 SPVs (gross shares, invested capital, noCarry flags) and the 20%-over-ICC carry formula. Exposes net_of_carry_from_gross(gross_value), which recovers the per-snapshot price as gross / TOTAL_SHARES (volume is constant at 37,339,135 = the SPV share sum) and returns the netted value.

- get_assets_list — nets the Public SPCX row's current / 1-day-ago / 1-year-ago values. Because the page's rollups are summed server-side, netting before accumulation cascades the haircut into the SpaceX row, the portfolio total, the Public category subtotal, and the day/year deltas — keeping the page footing.

- get_asset_detail (Asset Details dialog) — nets currentValue. The frontend derives Total Value, Total P&L, Profit/Loss, Total Return, Annualized Return, and Investment Multiple from it, so one netting cascades to all of them; the IRR cash flow uses the net value too.

- get_historical_data (the dialog's "Monthly Holding Value" chart + Current Holding / Period High-Low stat cards) — nets each Public SPCX data point's holding_value. closing_price is intentionally left as the real per-share market price (carry is a value-level GP haircut, not a price change), so the price line and price-based "Period Return %" stay true.

The stored holding_value pipeline (Kubera / trade-recalc) is untouched — netting is applied at read time only.

## Carry model (per SPV, ported from valuation.ts)

valuation = gross_shares × price
carry     = 0                                if noCarry (Gigafund 0.8, Strauss)
max(0, 0.20 × (valuation − icc))  otherwise
net       = valuation − carry

## Verification

- Parity test (tests/test_spacex_carry.py, 10 tests) locks the Python mirror to the valuation-page figures at $185: net $5.900B, carry $1.008B, shares 37,339,135, per-SPV nets, and noCarry/floor behavior — so the two copies can't silently drift.

- Simulated all three endpoints against live Redshift data: SpaceX row $6.91B → $5.90B, Multiple 22.40x → 19.13x, chart/Current Holding $5.90B — all reconcile with /spacex-valuation to the dollar.

- ruff format + ruff check clean; pyright error count unchanged (36 before = 36 after; new lines add zero).

- Full passive-investments router suite + new carry suite: 34 passed, 4 skipped.

## Notes

- IRR still displays "— 0%" for SpaceX (pre-existing: a single Commit trade with no realized cash-flow pair → IRR computes to 0 regardless of gross vs net). The net value is fed into its cash-flow calc so it stays consistent.

- The "$0 Period Low" on the historical chart is a pre-existing seed row (2026-06-11, price=0/value=0) in the gross data, not introduced here.

## Screenshots

<img width="1372" height="633" alt="image" src="https://github.com/user-attachments/assets/53eb70c1-adeb-4412-8226-b9930f650e2a" />

<img width="1255" height="318" alt="image" src="https://github.com/user-attachments/assets/43a05275-78bf-4230-991e-e8f272f77f39" />

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

## Summary

Aligns the Monthly Financial Reporting memos (on-screen UI and exported Google Doc) with the hand-authored reference memos at quarter-end and in Q1. Three related table behaviors, all keyed off calendar-quarter logic:

### 1. Education vertical / summary / physical-schools tables — collapse at quarter-end

In the last month of a quarter (Mar/Jun/Sep/Dec) the "months-elapsed" and "full-quarter QTD" column groups are mathematically identical, so the dual 6-column layout collapses to a single 3-column group headed by the quarter (e.g. Q1'26). Mid-quarter keeps the dual layout.

### 2. Financial statements (IS / EBITDA / Cash Flows) — quarter-labeled at quarter-end (Group, Software, Education)

At quarter-end the QTD window equals the full quarter, so the QTD columns are labeled by the quarter — Q1 2026 / Q1 2025 / Q1 2026 Bud — instead of the month (Mar-26 QTD). Mid-quarter keeps the month-QTD labels. Shared via apply_quarter_end_statement_labels (backend) and qtdStatementColumns (frontend).

### 3. Notes to Financial Statements — Note 2 (OpEx % of Revenue) & Note 8 (Other Expense) — Group/Software

Same quarter-end QTD relabel in the export; the Note 8 YTD pair stays month-anchored (Jun-26 YTD). The UI inherits these labels automatically from the IS table columns (no separate FE change).

### 4. IS-YTD table hidden in Q1 (all three memos)

YTD ≈ QTD in Q1, so the YTD Income Statement is dropped in Q1 — mirroring the existing EBITDA-YTD and YTD-cash-flow Q1 gating. Previously it always rendered.

## Business Value

Produces memos that match the Finance-authored reference documents exactly, removing redundant/duplicate columns and a confusing always-present YTD table in Q1. This is immediately visible: the production period floor is 2026-03-01 (a quarter-end month), so March 2026 is the first period users see.

## Test plan

- Backend: pytest tests/mfr/ tests/docx_reports/ tests/test_education_vertical_data.py — all green (2038+ passed), incl. golden/package-smoke (no regeneration needed). New tests cover: vertical collapse widths/headers (quarter-end vs mid-quarter), IS-YTD hiding (Q1 vs Q2), statement header relabel, and Note 2/Note 8 quarter-end labels.

- Frontend: tsc --noEmit + ESLint clean on changed files; all 1209 monthly-financial-reporting specs pass. New specs cover qtdStatementColumns (quarter-end, all entities, "Bud", correct quarter number) and the vertical-collapse config builders.

- Manual: compared March 2026 (quarter-end Q1) and May 2026 (mid-quarter Q2) on-screen and exported docs against education-memo-march-2026.docx / education-memo-may-2026.docx.

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

http://localhost:3001/monthly-financial-reporting

https://github.com/user-attachments/assets/6ef3b8a8-ade5-4646-bef5-12c22b3f14b8

## What

Makes every mercy consumer repo (Klair, Aerie, Sindri, trilogy-drones, and any future adopter) emit one telemetry record per review to the Surtr /mercy dashboard — today only Surtr does, via its own standalone pr-review-agent.yml. This ports that proven path into the central reusable harness so it lights up everywhere with no per-repo code.

## Changes

- harness/emit_telemetry.py (new) — fail-open, stdlib-only POST of a per-review record (identity, verdict, decision detail, findings, model, cost/tokens, timing). Wire shape matches Surtr/src/mercy/types.ts (the same contract Surtr already emits). Verbatim port of Surtr's scripts/pr-review/emit_telemetry.py.

- .github/workflows/mercy.yml — adds Mark run start + Emit telemetry steps and an optional MERCY_TELEMETRY_TOKEN workflow_call secret. Emit is gated on idem.go (exactly when ./.trusted is checked out and the review pipeline ran) and !cancelled(), runs from the trusted harness, and is continue-on-error — a review can never be failed by telemetry. Also exports the review attempt count (retry-rate metric).

- Callers — thread MERCY_TELEMETRY_TOKEN through the workflow template + the consumers/* reference copies. (mercy-self.yml already uses secrets: inherit.)

- docs/ADMIN-SETUP.md — documents the optional org secret + URL default.

- harness/tests/test_emit_telemetry.py (new) — golden tests for build_payload.

## Safety

- Token unset → emit logs and skips (fail-open). No review behavior changes until the org secret exists.

- URL defaults to https://surtr.klair.ai/internal/mercy/telemetry; override via the optional MERCY_TELEMETRY_URL org var.

- Idempotent on review_id (repo+pr+head_sha) → re-runs upsert.

## Local verification

- actionlint (CI invocation) — PASS on all workflows

- ruff check + ruff format --check harness — clean

- pytest harness/tests — 103 passed (incl. 6 new emit tests)

## ⚠️ Required to actually turn it on (admin, after merge)

1. Add MERCY_TELEMETRY_TOKEN as an org secret scoped to Klair/Aerie/Sindri/trilogy-drones (value = SURTR_PROD_KEYS.MERCY_TELEMETRY_TOKEN).

2. Move the v1 tag to this commit so the four @v1 callers pick up the emit step.

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

## Summary

- Collapse active workflow execution around agent nodes, Output Format, Quality Bar, durable Outcome Attempts, and Improvement Suggestions.

- Remove Script/Webhook workflow primitives, workflow-level evaluation compatibility, and legacy QC vocabulary from active runtime, UI, schema, and tests.

- Move internal research/spec docs under research/ and refresh the Lightpost around Sindri as a UI-neutral control plane.

## Why

The Outcomes/flywheel model had too many overlapping concepts: agent outcomes, workflow criteria, node overrides, script/webhook nodes, and legacy QC compatibility. This made the platform harder to explain, harder to inspect, and riskier to expose beyond the UI. This PR commits to the simpler agent-first model so future API/MCP/control-plane work has one clean foundation.

## Business Value

Users get a clearer, more durable model: agents define what good looks like, workflows compose agents, runs expose the evidence, and improvement suggestions remain reviewable rather than hidden. The same foundation can now be driven by UI, API, MCP, or agent sessions without carrying old workflow-quality concepts forward.

## Breaking changes

- Active Script/Webhook workflow primitives and Forge script authoring surfaces are removed.

- Workflow-level success criteria/evaluation contracts and legacy QC compatibility fields are removed from active platform contracts.

## Test plan

- [x] pnpm check

- [x] pnpm test

- [x] pnpm --dir agent-runner check

- [x] pnpm --dir agent-runner test

- [x] Retired-contract search audit for active code/docs

## Demo

<img width="2237" height="1636" alt="image" src="https://github.com/user-attachments/assets/99f0bbaa-9ba3-4ad5-aa39-8e0496f6c9c6" />

19 June Financials batch — three changes, all on the "Actual vs Model" Financials surface.

## 1. AERIE-421 — Live-Redshift Financials migration ([#449](https://github.com/AI-Builder-Team/Aerie/pull/449))

Serve every Financials "Actual vs Model" surface (consolidated + per-school P&L, headcount, programs, facilities, unitemized, drill-downs, CSV export) live from Redshift via Convex "use node" actions, replacing the nightly-synced plMonthlyRecords / plTransactions tables.

- New chat/convex/finance/dashboards/financialLive.ts — one action per surface; each opens a one-shot Redshift connection, maps rows into the same pure reducers the synced queries used, so the two paths can't drift.

- Pure reducers extracted to ctx-free modules (consolidatedShared.ts, consolidatedReducers.ts, consolidatedDetailReducers.ts, perSchoolReducers.ts) — one source of truth, unit-tested in isolation.

- Frontend reads through a new useLiveSection hook: a one-shot action mapped into the same SectionResult shape the synced useQuery sections exposed, so the table components are unchanged (on-demand "Refresh" rather than a live subscription).

- Dropped the plMonthlyRecords + plTransactions tables and all their sync / prune / backfill code (sync worker, analytics refresh jobs, upsert/prune Convex mutations + tests) — this is the bulk of the −16k diff.

- Authorization runs requireSchoolPlAccess at the action boundary before any Redshift connection (docs/endpoint-hardening.md). Quarter/period inputs are regex-validated and inlined as literals (static SQL, no injection surface).

- Why: reading current Redshift state directly makes the dashboard immune to the additive-only sync's orphan / phantom-overage artifacts (the root cause behind the AAC / Lake Forest / Nova Bastrop overage diagnoses).

- New deps: pg@8.17.2, @types/pg@8.11.11 (exact-pinned).

## 2. Pin "Schools – Actual vs Model" to a single period + rename page

- Remove the quarter picker — PERIOD_OPTIONS had a single entry, so it was a no-op dropdown; period is now a fixed const (dropped the dead periodOptions memo + setPeriod).

- Drop the "Jan–Jun 2026" date prefix from the Consolidated P&L subtitle (removed the now-unused subtitleLabel prop).

- Rename the page "Schools – Actual vs Model" → "Actual vs Model (Schools)".

## 3. Test fix — align stale tests with the migration

- financials-kpi-cards.test.tsx and use-consolidated-unitemized.test.tsx still mocked the old reactive queries, leaving api.finance.dashboards.financialLive undefined → 9 tests threw at render in CI.

- Re-pointed both at useLiveSection / the financialLive actions, and rewrote the unitemized test for the new single-action, server-side fan-out shape (drops the obsolete client-side useQueries dedup / per-school-partial-failure cases; adds the {schools, years} payload, all-or-nothing failure fold, loading gate, and disabled / empty-schools short-circuits).

## Testing

- pnpm typecheck, pnpm biome check, and the full vitest suite are green in CI.

- The authorized success path of the live actions needs a real Redshift connection, so it is validated manually against the dev deployment, not in CI — the auth-rejection gate and the pure mapper/reducer paths are covered by unit tests.

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

## Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/8d57277f-90f3-4059-ab9b-591543ca81f9" />

Proves the fix: the per-school P&L reader now includes a dedicated QB entity's whole realm, so Alpha Anywhere Center's unclassed (Not Specified) tuition is no longer dropped — Q1'26 tuition reads the true $446,807 instead of $307,500.

Backend — per-school P&L includes the dedicated entity's whole realm

Ran python3 /tmp/demo-aerie434.py, which executes the reader's per-school predicate (the exact WHERE the diff adds to financialLive.ts) against Redshift, OLD vs NEW:

Q1'26 50000 Tuition — Alpha Anywhere Center
OLD (class-only)               =   307,500.00
NEW (class + dedicated realm)  =   446,807.02   (QuickBooks: 446,807.02)

The NEW predicate matches QuickBooks to the cent.

Changed code is exercised directly — pnpm vitest run convex/finance/dashboards/financialLive.test.ts. The suite imports and calls the new plMonthlyBySchoolSql / plTransactionsBySchoolSql, asserting both substitute every {CLASS_IN} (the replace→replaceAll guard) and emit the dedicated-entity arm:

✓ convex/finance/dashboards/financialLive.test.ts (30 tests)
Test Files  1 passed (1)
Tests  30 passed (30)

Most at risk — over-including another school's data (the new arm pulls a *whole* realm). Verified the self-identifying subquery resolves to exactly one dedicated entity, and the read pulls only Alpha Anywhere Center's rows across its three realms:

dedicated companies resolved: ['alpha_anywhere_center_llc']
(company_id, class_name) the NEW query pulls:
alpha                        | Alpha Anywhere Center
alpha_anywhere_center_llc    | Alpha Anywhere Center
alpha_anywhere_center_llc    | Not Specified      <- the previously-dropped rows
alpha_schools_llc            | Alpha Anywhere Center

No other school's data enters the result. The consolidated "All Schools" reader is untouched by this PR (see the Scope note below).

---

## Summary

On Actual vs Model (Schools), a school backed by a dedicated QuickBooks entity lost any of that entity's rows booked without a class (class_name = 'Not Specified'). The per-school live reader (financialLive.ts) scoped purely by class_name IN (canonical + aliases), so the dedicated entity's unclassed rows — real revenue/spend — were silently dropped.

Alpha Anywhere Center, Q1'26: Tuition read $307,500 instead of $446,807 (−$139,307). Food Service, Financial Aid and Sibling Discount were undercounted the same way; Stripe Fees matched to the dollar because it has no unclassed rows. Unclassed bookings continue Apr–Jun (June tuition $209k unclassed), so Q2'26 and SY totals were affected too.

## Root cause

PL_MONTHLY_SELECT_BY_SCHOOL and PL_TRANSACTIONS_SELECT_BY_SCHOOL filtered only on class_name IN ({CLASS_IN}) — no company_id arm — so a dedicated entity's rows survived only when they happened to carry the canonical class. This violates the documented *"the whole dedicated realm IS the school"* semantic. Pre-existing (the retired synced path keyed school_display_name = class_name identically); exposed now by unclassed data starting Jan 2026.

## Fix

Add a self-identifying company_id arm to both per-school reads — a dedicated entity is any non-shared company_id that carries the school's class, so no external company→school map is needed:

WHERE class_name IN ({CLASS_IN})
OR company_id IN (
SELECT DISTINCT company_id FROM staging_education.quickbooks_pl_monthly
WHERE class_name IN ({CLASS_IN}) AND company_id NOT IN ('alpha','alpha_schools_llc')
)

The per-school reducers already filter only by year/period (never by schoolDisplayName), so fetching the extra rows is sufficient — no row-mapper change. SQL building is extracted into exported pure plMonthlyBySchoolSql / plTransactionsBySchoolSql so the shape is unit-tested without a Redshift connection (and to guard the replace → replaceAll substitution now that {CLASS_IN} appears twice).

## Verification

Ran the old vs new reader SQL against Redshift:

| | Q1'26 50000 Tuition |

|---|--:|

| OLD (class-only) | $307,500.00 |

| NEW (class + dedicated realm) | $446,807.02 ✅ |

The dedicated-entity subquery resolves to exactly alpha_anywhere_center_llc — no other school's data is pulled in.

## Test plan

- [x] pnpm vitest run convex/finance/dashboards/financialLive.test.ts — 30 pass (4 new)

- [x] pnpm typecheck — clean

- [x] pnpm biome check — clean

- [x] Redshift reconciliation: AAC Q1'26 tuition 307,500 → 446,807

## Scope / follow-up

In scope: per-school P&L + transaction live readers (the reported symptom). Related (separate ticket): the consolidated "All Schools" rollup leaks the same money — dedicated unclassed rows bucket to a Not Specified pseudo-school, which is in EXCLUDED_SCHOOLS, so they drop from the total. A robust fix needs company→school attribution in the consolidated reducer.

---

Stacked on #461 (AERIE-433). Linear: AERIE-434.

## Demo

Proves the new backfill.py runner works and that running it actually landed Q3'25 (Jul–Sep) Anthropic token usage into core_finance.ai_spend_claude_token_usage — without disturbing any existing rows. All output below is real, captured from running the changed code directly via the runner's own CLI (no HTTP layer).

Pipeline — Q3'25 backfill executed (backfill --start-month 2025-07 --end-month 2025-09 --execute, run locally 2026-06-21)

Each month invokes the existing handler.handler with an end-exclusive window:

MONTH 2025-07 done: fetched=3291 deleted=0 inserted=3291
MONTH 2025-08 done: fetched=3541 deleted=0 inserted=3541
MONTH 2025-09 done: fetched=3907 deleted=0 inserted=3907
Backfill execute finished (exit_code=0).

deleted=0 across all months = clean inserts (no pre-existing Q3 rows). 10,739 rows total.

Data — before vs after (backfill verify, read-only)

| Check | Before | After |

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

| MIN(report_date) | 2025-10-01 | 2025-07-01 |

| Total rows | 89,842 | 100,581 (+10,739) |

| Q3'25 rows [2025-07-01, 2025-09-30] | 0 | 10,739 |

New Q3 months vs already-billed cost-reports actuals (magnitude sanity check):

2025-07   3291 rows   list-price $52,592   | cost-reports actual $43,078   (1.22x)
2025-08   3541 rows   list-price $55,467   | cost-reports actual $48,593   (1.14x)
2025-09   3907 rows   list-price $87,212   | cost-reports actual $82,639   (1.06x)

List-price slightly above billed is expected (list price excludes negotiated/committed-use discounts — exactly the gap the Klair "Reconciled Cost" line reconciles); same order of magnitude. ✅

Runner safety — dry-run is the default + unit tests

Dry-run (no --execute) writes nothing and shows the exact scope:

# DRY-RUN — NO HANDLER CALLS, NO ANTHROPIC FETCH, NO DB WRITES
WOULD process 2025-07 : start_date=2025-07-01 end_date=2025-08-01 (end exclusive) | BUs=ALL
WOULD process 2025-08 : start_date=2025-08-01 end_date=2025-09-01 (end exclusive) | BUs=ALL
WOULD process 2025-09 : start_date=2025-09-01 end_date=2025-10-01 (end exclusive) | BUs=ALL

$ uv run pytest tests/test_backfill.py -q
22 passed in 0.14s

Most at risk from this change — checked and held:

1. No regression to existing Oct'25→Jun'26 rows (the --execute path writes to the prod table). The before/after verify shows every existing month is byte-identical — counts *and* cost sums unchanged, e.g. 2025-10 = 4,522 / $81,562.48 and 2026-05 = 17,246 / $827,028.32 in both runs. The idempotent per-(bu, report_date) delete-insert touched nothing outside Q3.

2. Month-window boundaries (off-by-one / inclusive end). Unit tests assert [first-of-month, first-of-next-month) exclusive windows incl. year rollover (Dec→Jan); Sep correctly maps to 2025-09-01 → 2025-10-01.

3. Scope creep beyond Q3. Both the dry-run plan and the execute log show exactly the three Q3 months; the optional Dec'24→Jun'25 extension was not run.

---

## Summary

Operational backfill for the Claude token-spend pipeline. The Lambda handler is already date-parameterized (params.start_date / params.end_date / params.bus_to_process) and idempotent per (bu, report_date) (delete-then-insert), so replaying a historical window requires no change to core pipeline or Klair logic. The only deliverable in this PR is an additive, reviewable runner — src/backfill.py — that orchestrates the existing handler over month-by-month windows, plus a read-only probe and read-only verification SQL.

Linear: [SURTR-220](https://linear.app/builder-team/issue/SURTR-220)

## Why the gap exists

The daily cron pulls forward-only (each run fetches day-before-yesterday → yesterday), so core_finance.ai_spend_claude_token_usage has a hard floor at 2025-10-01. That floor is a go-live boundary that was never backfilled — not an Anthropic API retention limit. Meanwhile ~$174K of Q3'25 billed Anthropic spend already exists in the cost-reports table with zero corresponding token-usage rows, so the AI Spend page shows nothing for Jul–Sep 2025.

## Read-only probe results ✅

The orchestrator ran the read-only probe mode live against Anthropic's Usage Report API (zero DB writes, zero handler invocation). Anthropic still serves Q3'25 usage, confirming the backfill is feasible:

- probe --date 2025-09-15 (BU IgniteTech): YES — 32 usage items returned (standard tier; 0 fast).

Sample record: {report_date: 2025-09-15, model: claude-3-5-sonnet-20241022, uncached_input_tokens: 2372, output_tokens: 561, ...}

- probe --date 2025-07-15 (BU IgniteTech): YES — 19 usage items returned.

(Confirms both edges of the Q3 window are retrievable, not just the tail.)

- Secret Anthropic-Usage-Keys resolved 7 BUs.

- The probe made zero database calls.

Conclusion: the historical data is retrievable from Anthropic, so the Q3'25 backfill is feasible.

## What's in this PR

- pipelines/runners/claude-token-spend-pipeline/src/backfill.py — additive CLI runner with three modes:

- probe — read-only check that Anthropic returns Q3'25 data (no handler, no DB).

- backfill — chunked per-calendar-month replay of the existing handler.handler(...) path. Dry-run by default; real writes require an explicit --execute (alias --no-dry-run).

- verify — read-only validation SELECTs (bounds / monthly / Q3-presence / cost-reports cross-check); --sql-only prints SQL without an AWS session.

- 22 unit tests (tests/test_backfill.py).

- Spec 05 (05-q325-token-usage-backfill) and the FEATURE.md changelog update.

No new dependencies (stdlib + already-bundled boto3 / requests). AWS clients are imported lazily, so CI and the unit tests need no AWS session.

## Not in this PR (operator runs the actual backfill)

The production, DB-writing backfill is intentionally NOT executed by this PR. Scope here is *tooling + read-only probe only*. After review, the operator runs backfill --execute locally (authenticated via saml2aws). The dry-run default and the explicit --execute gate make the write path opt-in by construction.

## Operator runbook

Copy-pasteable sequence (run from the worktree / repo root unless noted):

1. Authenticate:

   saml2aws login --profile default --force --username ashwanth.r \
--role "arn:aws:iam::479395885256:role/RAM-AWS-Int-CentralFunctions-CentralFinance-Admin" \
--skip-prompt

2. (optional) re-probe Q3'25 availability:

   cd pipelines/runners/claude-token-spend-pipeline && uv run python src/backfill.py probe

3. Dry-run preview (shows the month/BU plan, writes nothing):

   uv run python src/backfill.py backfill

4. Execute — ideally one month at a time for safety:

   uv run python src/backfill.py backfill --start-month 2025-07 --end-month 2025-07 --execute
uv run python src/backfill.py backfill --start-month 2025-08 --end-month 2025-08 --execute
uv run python src/backfill.py backfill --start-month 2025-09 --end-month 2025-09 --execute

(or all three at once: --start-month 2025-07 --end-month 2025-09 --execute).

Run locally — a 3-month all-BU window exceeds the 600s Lambda timeout, which is why the runner chunks per month and is run from a workstation rather than the Lambda.

5. Verify (read-only — bounds / monthly / Q3-presence / cost-reports cross-check):

   uv run python src/backfill.py verify

Re-runs are safe: writes are idempotent per (bu, report_date), and existing Oct'25+ rows are never touched by a Q3'25 replay.

6. Optional extension — close the full ~$277.5K pre-go-live gap (Dec'24 → Jun'25) with the same procedure:

   uv run python src/backfill.py backfill --start-month 2024-12 --end-month 2025-06 --execute

## Test coverage

22 passing unit tests (uv run pytest tests/test_backfill.py -q) covering:

- Month-window math — [first-of-month, first-of-next-month) with exclusive ends, including year rollover (Dec → Jan).

- CLI parsing / defaults — Q3'25 defaults require no arguments; --start-month after --end-month raises ValueError.

- Dry-run safety — in dry-run the handler is never invoked and nothing is written.

- Verify SQL — all four queries are SELECT-only (no write path).

## Spec

[features/surtr/ai-spend-pipeline/specs/05-q325-token-usage-backfill/spec.md](features/surtr/ai-spend-pipeline/specs/05-q325-token-usage-backfill/spec.md)

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

## KLAIR-2870 — Raw Data Reports: Anthropic — Token Usage (grouped tree)

Super-admin Raw Data Reports → Anthropic — Token Usage inspection view for core_finance.ai_spend_claude_token_usage, presented as an expandable BU → Workspace → API-key tree with server-side, per-workspace pagination.

Linear: https://linear.app/builder-team/issue/KLAIR-2870

### Demo

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/c298b1a3-5263-4502-8cb4-fb001fe25eab" />

<img width="2624" height="1636" alt="image" src="https://github.com/user-attachments/assets/0c519a3e-4018-4789-a210-ca2cf739ca77" />

https://docs.google.com/spreadsheets/d/12_b8GyjXqHJVd54P2ofrpvlQ77_RgfdrahiGj2R5-WU/edit?usp=sharing

### What's built

- Expandable BU → Workspace → API-key tree. Group rows (BU, workspace) show summed token/cost totals; workspaces also show an api_key_count. Default window is 7 days (presets 7d / 30d / 90d).

- Server-side pagination at the API-key level, scoped per workspace (page size 25, lazy-loaded on expand). Keys are aggregated per api_key_id — summed across days + models within the window.

- Three super-admin endpoints:

- GET /api/ai-costs/raw/anthropic-token-usage/groups — BU→workspace rollup with grand totals + counts. Loaded once per window.

- GET /api/ai-costs/raw/anthropic-token-usage/keys?bu&workspace_id&page&page_size — one paginated page of aggregated-per-key rows for a workspace (total_keys drives page count). Loaded lazily on expand / page change. Omitting workspace_id targets the no-workspace (NULL) bucket.

- GET /api/ai-costs/raw/anthropic-token-usage (existing flat endpoint) — retained solely to power the full raw-row CSV export (fetched on demand client-side).

### Files changed

- Backend: models/ai_costs_models.py (6 new models incl. shared AnthropicTokenUsageTotals), services/ai_costs_service.py (get_anthropic_token_usage_groups, get_anthropic_token_usage_keys), routers/ai_costs_router.py (2 new routes; _resolve_anthropic_window gained a default_days param — token-usage=7, cost-reports stay 30).

- Frontend: new hooks useAnthropicTokenUsageGroups + useAnthropicWorkspaceKeys; useAnthropicTokenUsage refactored to on-demand fetchRows() for CSV; AnthropicTokenUsageView rewritten as the tree; helpers (pageCount, formatInt, formatUsd, workspaceLabel, apiKeyLabel); registry description; types.

- Docs: spec 04 + FEATURE.md synced to the redesign (revision note records the flat-table → grouped-tree supersession).

### Tests (92)

- Backend (41): groups folding/totals/total_tokens + api_key_count null bucket; keys pagination offset math + workspace_id IS NULL clause + bound-param order; super-admin gate; 7-day default window; 422 on malformed dates.

- Frontend (51): groups + workspace-keys hooks (enabled gating, workspace_id omission for the null bucket, re-fetch on page change), on-demand fetchRows CSV path, helpers, registry.

### Self-review

No CRITICAL/IMPORTANT issues. Two MINOR items fixed: reset the workspace page when the window changes (avoids a stale out-of-range offset), and corrected the BU-ordering docstrings (alphabetical by bu).

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