Vol. I  ·  No. 313 Established 2026  ·  AI-Generated Daily Free to Read  ·  Free to Print

The Trilogy Times

All the news that's fit to generate  —  AI • Business • Innovation
MONDAY, NOVEMBER 09, 2026 Powered by the TrueFoundry AI Gateway  ·  Published on Klair Trilogy International © 2026
🖶 Download PDF 🖿 Print 📰 All Editions
Today's Edition

EVERYBODY WANTS TO RUN YOUR BUSINESS NOW — THE AGENTS ARE COMING

IBM, SAP and Meta roll out AI agents to run the enterprise while McKinsey and Google Cloud build the consulting arm to sell it.

AUSTIN, TEXAS — Four companies staked claims this week on the same patch of ground: the machine that runs your company before you wake up. IBM told the crowd at TechXchange 2026 its watsonx Orchestrate platform now manages fleets of AI agents across the enterprise. SAP answered the same day with a pitch for what it calls the Autonomous Enterprise.

Meta moved the fight downmarket. The company said Tuesday it is pushing Muse, its AI agent, out to small businesses — the mom-and-pop shops that could never afford an IBM contract. Reporting from TechCrunch pegs the move as Meta's bid to put agents in front of merchants who run their whole operation off a phone and a Facebook page.

McKinsey didn't wait for the dust to settle. The consulting giant announced a joint venture with Google Cloud this week, a new group built to walk Fortune 500 clients through what McKinsey is branding "enterprise AI transformation." Translation: somebody has to explain all this to the people signing the checks, and McKinsey wants the fee for that explanation.

Here's the wrinkle nobody in the press releases wants to say out loud. DeepSeek, the Chinese outfit that rattled Silicon Valley last year, built high-performing models without the most advanced chips and at a fraction of the cost everyone assumed was the floor. If the Chinese can run frontier AI on a shoestring, the premium IBM, SAP and McKinsey are charging for "autonomous enterprise" software starts looking less like innovation and more like margin.

The math isn't lost on Austin. Trilogy International's ESW Capital has run its stable of 75-plus software companies on a version of this bet for years — cheap, distributed talent through Crossover, AI-driven cost management through Klair, buy-and-optimize instead of buy-and-build-new. Every big vendor now racing to sell "agents that run your business" is chasing a version of what Trilogy already does with people and code.

The difference is who pockets the savings. IBM, SAP and Meta want enterprises to pay a subscription for the privilege of automating themselves. DeepSeek's lesson was that the compute underneath all of it is getting cheaper by the week, and McKinsey's new group exists mostly to help clients figure out which bill is worth paying.

Nobody at TechXchange said the word "commodity." Give it a year.

↗ IBM watsonx Orchestrate advances enterprise AI agent managem  ·  Meta is expanding its AI agent Muse to small businesses - Te  ·  SAP Unveils the Autonomous Enterprise - SAP News Center

IN RE: THE MATTER OF UNAUTHORIZED INGESTION — COURT HOLDS THAT COPYRIGHTED TRAINING DATA SHALL NOT, HEREINAFTER, ENJOY THE FAIR USE SHIELD Developing

A federal tribunal has determined, pursuant to its own reasoning and notwithstanding industry objections, that the wholesale ingestion of copyrighted works for model training purposes does not, as a matter of law, constitute fair use.

SAN FRANCISCO — It is hereby reported that a federal court has rendered a determination, as covered initially by Futurism, to the effect that the use of copyrighted materials as training data for artificial intelligence systems does not, under the operative four-factor test codified at 17 U.S.C. § 107, constitute fair use, notwithstanding arguments previously advanced by various AI developers to the contrary.

The undersigned notes, for the avoidance of doubt, that the aforementioned ruling is limited to the specific facts and parties before the court, and that no reader should construe this article as providing legal advice regarding the fair-use status of any particular training corpus, model, or derivative output, the applicability of which remains, pursuant to ongoing litigation nationwide, substantially unsettled.

It is nonetheless observed, insofar as such observation may be deemed relevant to the readership of this publication, that the holding bears potential implications for entities operating within the content-generation and content-marketing sectors, including, without limitation, Trilogy International's portfolio company Contently, acquired by ESW Capital in September of 2024, which business is engaged in matters pertaining to the licensing, creation, and distribution of written content — activities which may or may not, depending on forthcoming appellate review, be affected by the court's reasoning regarding the lawful provenance of training corpora employed by AI systems generally.

Notwithstanding the foregoing, no representation is made herein as to whether Klair, the internal analytics platform maintained by the AI Builder Team, or any other AI-adjacent system operated within the Trilogy portfolio, relies upon training data implicated by the subject ruling, and readers are advised to direct any such inquiries to appropriate counsel rather than to the present publication.

It shall further be noted that the ruling arrives amid a broader pattern of judicial skepticism toward the fair-use defense as asserted by AI developers, a pattern which, in the reasoned estimation of this desk, is likely to be appealed, distinguished, narrowed, or otherwise litigated for the foreseeable duration, such that the only certainty presently discernible is the continued, indefinite employment of this publication's legal correspondents.

↗ Funniest/Most Insightful Comments Of The Week At Techdirt  ·  This Week In Techdirt History: November 1st – 7th  ·  America Records Its 8th Measles Death Of The Year In Wiscons

FINTECH GETS SACKED: Robinhood, SoFi, PB Fintech Taken Down in Brutal Blitz as Bitcoin Fumbles the Ball

NEW YORK — LADIES AND GENTLEMEN, WE ARE HERE, and it is NOT pretty. The fintech sector just got absolutely MAULED in what can only be described as a full-field collapse, and Bitcoin — supposedly the sport's star quarterback — threw the pick-six that started it all.

Robinhood is DOWN TEN PERCENT. Ten! That's not a stumble, that's a stretcher coming out. SoFi follows close behind, down 8%, limping off after getting caught flat-footed on the crypto blitz. This is the kind of selloff that makes you check the scoreboard twice.

And folks, this isn't just a home-field problem. Travel eight thousand miles to Mumbai and you'll find PB Fintech — India's insurance-tech darling — getting absolutely run over. SIX SESSIONS. That's all it took to erase FIVE YEARS of gains. The stock has now slipped BELOW its IPO price, which in sports terms is like a team getting relegated mid-season. Six years of momentum, gone in under a week.

Meanwhile, in the broadcast booth, the real story is the SOURCE of the collapse: a Nvidia-led tech selloff that's rippling through every asset class wearing a risk jersey. When the AI-chip heavyweight stumbles, everybody downstream from crypto majors to neobanks feels the shockwave. Bitcoin slides, altcoins slide, and the whole fintech conference gets caught in the undertow.

And yet — AND YET — across the pond in London, somebody's still suiting up for the next game. Revolut is reportedly eyeing a London IPO even as the Bank of England works to ease gilt pressure and British savers sit on the sidelines refusing to get in the game at all. It's a wild juxtaposition: one league getting blown out on the scoreboard, another prepping a fresh roster for 2026, where analysts are already compiling best-IPO power rankings for the year ahead.

Bottom line, folks: when the market's biggest name takes a hit, nobody's safe — not Robinhood, not SoFi, not a five-year India success story. The whistle's blown. We'll see who's standing when the clock resets tomorrow.

Haiku of the Day  ·  GPT-5.6 LunaThe ghosts learn our names
While we train all the machines
Who gets to clock out?
The New Yorker Style  ·  Art Desk
The New Yorker Style  ·  Art Desk
The Far Side Style  ·  Art Desk
The Far Side Style  ·  Art Desk
News in Brief
On the Impossibility of Stepping Into the Same Gradient Descent Twice: A Meditation on Fractal Basins
PITTSBURGH — A striking paper making the rounds this week (see reported via Bioengineer.org argues, with a mathematical confidence this columnist finds almost indecent, that the basins of attraction underlying stochastic gradient descent are not merely rugged but fractal in the strict Mandelbrotian sense — meaning that infinitesimal perturbations in initialization (a dropped seed, a reordered minibatch, the thermal noise of a GPU fan, one is tempted to add) cascade into categorically divergent convergence outcomes. Thesis: reproducibility failures in deep learning are an engineering defect, remediable through better logging, fixed seeds, and the sort of containerized discipline MLOps evangelists have long preached. Antithesis: if the underlying basin geometry is fractal — self-similar at every scale of perturbation — then no amount of version-pinning rescues us, because the boundary between "converges to Model A" and "converges to Model B" is, in principle, infinitely fine-grained and thus uncomputable in advance.
The Great Signal: How Nature’s Quietest Creatures Learn to Listen
CAMBRIDGE, MASSACHUSETTS — Observe, if you will, the physicist at rest — hunched, headphones askew, ear pressed not to the soil but to the circuit.
In Defense Of Never Explaining What Your Company Actually Does Ever Again
AUSTIN, TEXAS — I'll admit it: there was a time, maybe eighteen months ago, when I believed the word "AI" meant something.
The Symposium on Everyone Else's Unemployment
AUSTIN, TEXAS — There is a genre of literature, as reliable as the obituary and nearly as solemn, in which men of great credential gather to announce that the economy is about to change beneath the feet of people who were not invited to the gathering.
Unpopular Opinion: The Talent Supply Chain Is the New Bike Lane 🚀
AUSTIN, TEXAS — I'll be honest, I almost didn't write about bike lanes today. But then I saw the story about new software mapping disconnected bike networks and something clicked for me at 5am during my cold plunge. Most career paths are exactly like most bike lanes. Disconnected.
A Trilogy Company
Crossover
The world's top 1% remote talent, rigorously tested and ready to ship.
A Trilogy Company
Alpha School
AI-powered learning. Two hours a day. Academic results that defy belief.
A Trilogy Company
Skyvera
Next-generation telecom software — built for the networks of tomorrow.
A Trilogy Company
Klair
Your AI-first operating system. Every workflow. Every team. One platform.
A Trilogy Company
Trilogy
We buy good software businesses and turn them into great ones — with AI.
The Builder Desk  —  AI Builder Team
📅 Week in ReviewProduction Release

The Builder Desk

111 pull requests merged across the org this week

#54 Re-sync: walkthrough films register as not-searchable assets (AI-1261) (@kevalshahtrilogy, Rhodes-DSS)

#2284 AERIE-3092: Register walkthrough films and unreadable asset files as not searchable (@kevalshahtrilogy, Aerie)

#26 sindri-platform-dss (@mwrshah, DSS-Hub)

#223 1338-preserve-active-member-roles (@mwrshah, Sindri)

#2281 1439-sindri-central-onboarding (@mwrshah, Aerie)

#222 1337-3sindri-platform-dss (@mwrshah, Sindri)

#27 2036-sindri-dss-review (@mwrshah, DSS-Hub)

#2279 1437-generic-sindri-act-as (@mwrshah, Aerie)

#2277 AERIE-2375: Find a School source entity, its Schools and exclusion on v2 Directory (@marcusdAIy, Aerie)

#2276 AERIE-2375: Serve a School's source links on the v2 Directory School detail (@marcusdAIy, Aerie)

#2275 AERIE-2722: Keep same-name events separate in the agent's get_events output (@marcusdAIy, Aerie)

#53 Publish diligence site creation for write keys (AI-1234) (@kevalshahtrilogy, Rhodes-DSS)

#2274 Clean errors and legacy statuses for premise create/list (AERIE-3085) (@kevalshahtrilogy, Aerie)

#221 1336-2sindri-prod-release (@mwrshah, Sindri)

#3928 feat(acq-perf-review-v2): add direct-link Jive legacy review (@sanketghia, Klair)

#2266 Add POST /v2/portfolio/sites for premises in diligence (AERIE-3085) (@kevalshahtrilogy, Aerie)

#219 1335-2sindri-prod-release (@mwrshah, Sindri)

#2270 1435-prod-deploy-tests (@mwrshah, Aerie)

#218 1334-pr178-salvage (@mwrshah, Sindri)

#52 Re-sync the source contract: cursors up to 6,144 characters (AERIE-3086) (@kevalshahtrilogy, Rhodes-DSS)

#217 1333-2prod-deploy-tests (@mwrshah, Sindri)

#2267 Accept the v2 nextCursor the API returns (AERIE-3086) (@kevalshahtrilogy, Aerie)

#51 Publish site integrations so relink can register large Drive originals (AI-1233) (@kevalshahtrilogy, Rhodes-DSS)

#2264 1434-workos-push-failure (@mwrshah, Aerie)

#2257 feat(finance): expose exact Ramp counterparty source labels (@ashwanth1109, Surtr)

#2263 Remove ISP integration from the analytics worker (@marcusdAIy, Aerie)

#2254 Resolve QuickBooks Class business units and send a weekly Finance digest (@ashwanth1109, Surtr)

#2255 fix(netsuite): fence thirteen historical Core GL transaction repairs (@ashwanth1109, Surtr)

#2248 Apply Greenwich Finance allocations and unblock CT School publication (@ashwanth1109, Surtr)

#2252 SURTR-1697: Formalize five reviewed Alpha QTD school identities (@ashwanth1109, Surtr)

#2253 fix(ramp): complete cost research and recover linked weekly report (SURTR-1698) (@ashwanth1109, Surtr)

#2251 fix(netsuite): reobserve fenced historical transaction scopes (@ashwanth1109, Surtr)

#3927 fix(finance): preserve Education vendors on travel and donations (@ashwanth1109, Klair)

#2261 1433-5aerie-release-prep (@mwrshah, Aerie)

#3925 feat(ai-budget): add software and education filters (@ashwanth1109, Klair)

#50 State 120 sensitive reads per minute in the published contract (AI-1056) (@kevalshahtrilogy, Rhodes-DSS)

#49 Publish site document upload for write keys (AI-1055) (@kevalshahtrilogy, Rhodes-DSS)

#48 Allow document registration and uploads in the contributor rules; deletes stay banned (AI-1054) (@kevalshahtrilogy, Rhodes-DSS)

#2249 Harden Finalsite contacts view projection and rollout (@sanketghia, Surtr)

#2258 AI-1047: Fill student and family postal-address gaps (@kevalshahtrilogy, Aerie)

#47 Re-sync the source contract; recipe uses rendering and Matterport types; 120/min budget (AI-1048) (@kevalshahtrilogy, Rhodes-DSS)

#3924 fix(acq-perf-review-v2): sum available comparison totals (@sanketghia, Klair)

#3923 feat(acq-perf-review-v2): add budget base plan comparison (@sanketghia, Klair)

#46 Queue reads for a slot instead of refusing at once; eight in flight (AI-1051) (@kevalshahtrilogy, Rhodes-DSS)

#2257 AI-1050: Raise the sensitive read tier to 120 per minute; fixed bound for guards (@kevalshahtrilogy, Aerie)

#2247 Expose Finalsite start-if-different date (@sanketghia, Surtr)

#2245 095-hubspot-heavy-archived-programs (@mwrshah, Surtr)

#3922 fix(acq-perf-review-v2): align Prices Paid with legacy (@sanketghia, Klair)

#2256 1432-openapi-task-explanation (@mwrshah, Aerie)

#2243 feat(raptor): refresh the original personnel roster daily (@caina-barbosa, Surtr)

#12 feat(personnel): refresh the original Google roster with sheets-reader (@caina-barbosa, Raptor-DSS)

#2241 094-hubspot-archived-programs (@mwrshah, Surtr)

#2255 fix(tasks): stop individual notification emails (AERIE-3069) (@caina-barbosa, Aerie)

#3 Run the Rhodes loops daily on AWS Fargate (AI-1013) (@kevalshahtrilogy, rhodes-quality-loops)

#2 Retune Rhodes review skills and prompts for headless Claude Code (AI-1015) (@kevalshahtrilogy, rhodes-quality-loops)

#1 Harden the Rhodes baseline runner for headless runs (AI-1014) (@kevalshahtrilogy, rhodes-quality-loops)

#45 Fix Neeraj's documentation feedback: host, milestone9, traps, backup capacity, BrainLift hash (AI-1025) (@kevalshahtrilogy, Rhodes-DSS)

#2254 1431-fix-physical-forecast-continuing (@mwrshah, Aerie)

#44 Point rent and lease cost to the registered lease documents (AI-1046) (@kevalshahtrilogy, Rhodes-DSS)

#3921 fix(acq-perf-review-v2): use prior-year ARR for budget retention (@sanketghia, Klair)

#43 Fix Neeraj's findings: stale dictionary header and write count, rent, capacity asOf (AI-1045) (@kevalshahtrilogy, Rhodes-DSS)

#41 Enablement recipe: walkthroughs, renderings and outstanding work across a site cohort (AI-1042) (@kevalshahtrilogy, Rhodes-DSS)

#40 Fix Arthur's documentation feedback: owner, BrainLift, opening, capacity, lineage, plan of record (AI-1041) (@kevalshahtrilogy, Rhodes-DSS)

#38 Publish Work Unit Group metadata and status writes (AI-1039) (@kevalshahtrilogy, Rhodes-DSS)

#42 Re-sync the source contract; document version-2 Security scoring; relay search documentTypes (AI-1044) (@kevalshahtrilogy, Rhodes-DSS)

#39 Test the relay's four-read concurrency guard (AI-1040) (@kevalshahtrilogy, Rhodes-DSS)

#2253 AI-1043: Rendering + Matterport document types; documentRef on requirement evidence (@kevalshahtrilogy, Aerie)

#3920 fix(acq-perf-review-v2): tie plan EBITDA to source P&L (@sanketghia, Klair)

#3919 fix(acq-perf-review-v2): apply Finance retention rules (@sanketghia, Klair)

#3916 fix(acq-perf-review-v2): derive plan ARR from acquired ARR (@sanketghia, Klair)

#3915 fix(acq-perf-review-v2): exclude bad debt and non-MGMT CBA lines (@sanketghia, Klair)

#3913 fix(mfr): net repurchase proceeds in book value transfers (@sanketghia, Klair)

#1 Serve Lunch Vendor Tracker through the standalone DSS (@caina-barbosa, Lunch-DSS)

#11 docs: replace obsolete publication runbook with Surtr operations (@caina-barbosa, Raptor-DSS)

#2238 feat(raptor-refresh): enable daily schedule (AI-1037) (@caina-barbosa, Surtr)

#10 Restore collector reads and retained refresh recovery (@caina-barbosa, Raptor-DSS)

#2252 AERIE-821: Document onCampus evaluation time, no year-end freeze, and publication-time freshness (@marcusdAIy, Aerie)

#2251 AERIE-2025: Document that Program-Site links come through a canonical School (@marcusdAIy, Aerie)

#2250 AERIE-807: Explain milestone lanes, completion and status colors in Portfolio and Buildout tooltips (@marcusdAIy, Aerie)

#3912 fix(acq-perf-review-v2): match Finance IRR tax handling (@sanketghia, Klair)

#9 fix(refresh): reconcile browser traffic and finish owned cleanup (AI-1037) (@caina-barbosa, Raptor-DSS)

#2094 1422-drive-subfolder-matching (@mwrshah, Aerie)

#2248 1429-forecast-final-rounding (@mwrshah, Aerie)

#8 fix(refresh): settle static responses and retain cleanup diagnostics (AI-1037) (@caina-barbosa, Raptor-DSS)

#3910 fix(monthly-financial-reporting): clean up report presentation (@sanketghia, Klair)

#3909 feat(acq-perf-review-v2): add MoM to payback table (@sanketghia, Klair)

#3908 fix(acq-perf-review-v2): align forecast inputs with Finance (@sanketghia, Klair)

#3907 feat(acq-perf-review-v2): add selected Prices Paid view (@sanketghia, Klair)

#3905 fix(mfr): detect repurchase proceeds from memo (@sanketghia, Klair)

#2246 AERIE-2549: Label enrollment-summary currentEnrollment as EduCRM's figure, not the SIS count (@marcusdAIy, Aerie)

#2245 AERIE-2398: Document that the Program Funnel serves one school year and its year-named stages are relative (@marcusdAIy, Aerie)

#2244 AERIE-2397: Document that Enrollment drilldown studentRefs can 404 on the student profile route (@marcusdAIy, Aerie)

#2243 AERIE-2158: Define the Waitlisted catch-all and the Pipeline waitlisted column (@marcusdAIy, Aerie)

#2242 AERIE-2529: Explain Milestones 4 and 5 for change-of-use sites (@marcusdAIy, Aerie)

#2241 AERIE-1989: Define Community and Established Funnel dashboard stages and counting maps (@marcusdAIy, Aerie)

#2236 codex/raptor refresh manual activation (@caina-barbosa, Surtr)

#2240 AERIE-2155: Define the per-site grain of Site People contact slots (@marcusdAIy, Aerie)

#2239 AERIE-2508: Document typed-first document paging and the school_opening session start default (@marcusdAIy, Aerie)

#2238 AERIE-2478: Document that Work Unit completion is independent of produced document registration (@marcusdAIy, Aerie)

#2237 AERIE-2470: Document that start-year transfer-out and re-enrollment count at the school year being entered (@marcusdAIy, Aerie)

#2234 feat(raptor-refresh): trigger the existing collector safely (AI-1033) (@caina-barbosa, Surtr)

#2236 AERIE-2023: Document that the acquireProperty milestone is independent of the acquisition snapshot (@marcusdAIy, Aerie)

#5 feat(snapshot): read retained Raptor history through bounded segments (@caina-barbosa, Raptor-DSS)

#2235 AERIE-2021: Document that milestone order is presentation precedence, not enforced sequencing (@marcusdAIy, Aerie)

#2233 AERIE-2035: State that readyToOpen completion is an independent assertion (@marcusdAIy, Aerie)

#2232 AERIE-3007: Drop the retired rebl3DdCache table (@marcusdAIy, Aerie)

#2231 AERIE-2722: Issue one v2 eventRef per event occurrence (@marcusdAIy, Aerie)

#2230 fix(site-acquisitions): contain conversion preview errors (AERIE-3000) (@caina-barbosa, Aerie)

#2229 AERIE-2722: Select v1 event contacts by eventId and reject ambiguous names (@marcusdAIy, Aerie)

#215 1332-2aws-rotation-email (@mwrshah, Sindri)

#4 Serve Marauders Map DSS directly from the source API (@caina-barbosa, Marauders-Map-DSS)

Mac's Picks — Key PRs This Week  (click to expand)
#54 — Re-sync: walkthrough films register as not-searchable assets (AI-1261) @kevalshahtrilogy  no labels

## Summary

- Re-syncs the published contract after the source release that accepts any file type for rendering and matterportWalkthrough documents. The source change is AERIE-3092, released to production on 9 Nov. Files the indexer can't read, such as video, are registered as not_searchable (unsupported_type) instead of being refused with 422.

- Enablement says this next to the relink recipe. Other document types still refuse unreadable files.

- No allowlist change. Upload, register and relink were already published.

Verified locally: pnpm check, pnpm build and pnpm synth --no-lookups all pass.

## Business Value

Ops can register delivered walkthrough films for diligence sites through Rhodes. Robbie's 552 MiB Chapala film was blocked by a 422, and agents now see these films listed for each site.

## Manual Effort Estimate

About 0.5h (proposed, for Keval to confirm).

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

#2284 — AERIE-3092: Register walkthrough films and unreadable asset files as not searchable @kevalshahtrilogy  approved

Linear: [AERIE-3092](https://linear.app/builder-team/issue/AERIE-3092)

## Summary

Public API v2 refused any file the indexer can't read with 422 document_type_unsupported. That blocked Robbie's relink of the Chapala walkthrough film (video/mp4, 552 MiB; failed record doc_01M6QS6K184SF10S24JM69KZMX).

- Asset types accept any file. rendering and matterportWalkthrough (new ASSET_DOCUMENT_TYPES / isAssetDocumentType in @bran/contracts/document-types) skip the searchability gate on site upload, Global registration and relink. Every other document type keeps the current check.

- The relink check moved into the relinkDocument mutation. The mutation has the document loaded and knows its type, so the check runs there instead of in the action. The status, code and message are unchanged.

- Unreadable asset files never reach the indexer. When a Drive-backed asset document's mimeType is one the indexer can't read, createOrGetDesiredJob now creates the knowledge job as not_searchable with reasonCode unsupported_type at creation instead of queued. This uses the same honest reason the indexer itself reports for unreadable files. Readable asset files (PDF, JPEG, ...) are still indexed. Mislabeled-CSV MIME types are still left for the indexer to classify.

- Upload size bounds are unchanged.

- OpenAPI text (chat/lib/public-api/v2/domains/documents.ts) is updated. The upload, registration and relink 422 descriptions and the knowledgeStatus descriptions now say what is accepted and how such files are listed.

## Tests

- documentsHttp.test.ts:

- A video/mp4 relink and upload of a matterportWalkthrough succeed. Both films are listed as not_searchable / unsupported_type, and no indexer job is queued for them.

- A video/mp4 relink of a survey and a video/mp4 upload as survey still get 422 document_type_unsupported, with nothing changed.

- The existing searchable and unsupported-type tests are unchanged and still pass.

- lifecycle.test.ts: covers the job outcome for each combination of asset or non-asset type with readable or unreadable MIME type.

- Results: pnpm typecheck, biome check, and the lint:* checks (boundaries, convex-paths, read-bounds, test-architecture, knowledge) all pass. Vitest over convex/publicApi, convex/documentKnowledge, lib/public-api and convex/rhodes: 1576 of 1576 pass.

After release, Rhodes re-syncs OpenAPI (pnpm sync:openapi) and updates the Enablement relink recipe.

## Business Value

Ops can now register delivered walkthrough films (and non-indexable rendering formats) against diligence sites through the API and Rhodes agents, instead of being refused. Robbie Forrest's Chapala walkthrough film is blocked today. Once this ships, it relinks with the documented upload-a-stand-in-then-relink flow. The site's diligence record then holds the actual deliverable, honestly marked as not searchable.

## Manual Effort Estimate

Proposed: ~5 hours of focused time to trace the gate and the knowledge-job lifecycle, implement the change, write the HTTP and lifecycle tests, and update the OpenAPI text. *Keval: please confirm or adjust this number.*

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

#26 — sindri-platform-dss @mwrshah  no labels

- Add the Sindri platform DSS with native discovery, caller-owned keys, live access checks and private feedback.

- Separate DSS sign-in eligibility from Forge Integration key ownership; require both memberships for key creation and protected DSS use.

- Keep membership grants and profile provisioning outside DSS, with key revocation available during Forge suspension.

- Document the native authorization, lazy-profile and key-cutover requirements that block release.

- Register Sindri with the shared service-isolated deployment machinery and scoped infrastructure configuration.

#223 — 1338-preserve-active-member-roles @mwrshah  approved

- Preserve existing active membership roles during M2M provisioning.

- Keep baseline assignment for new/reactivated memberships, applying it before reactivation for safe retries.

- Update existing contract tests and configuration guidance; no new modules.

#2281 — 1439-sindri-central-onboarding @mwrshah  approved

- Switch Sindri user provisioning from /aerie/users to the centralized /m2m/users endpoint introduced in [Sindri #222](https://github.com/AI-Builder-Team/Sindri/pull/222).

- Update the existing request-path assertion and inline documentation; preserve payloads, authentication, and reconciliation behavior.

#222 — 1337-3sindri-platform-dss @mwrshah  changes requested

- Add POST /dss/users to hydrate the same verified WorkOS identity after checking active membership in the server-pinned DSS organization, without changing memberships or roles.

- Reuse canonical Sindri profile reconciliation with bounded requests and fail-closed provider/identity validation.

- Cut over shared M2M authentication to M2M_SECRET, X-M2M-Secret and X-Act-As, preserving Aerie organization semantics and updating capacity automation. Trusted callers and deployment configuration must switch together.

- Document the DSS hydration contract and server configuration.

- Companion caller update: [Aerie #2279](https://github.com/AI-Builder-Team/Aerie/pull/2279).

#27 — 2036-sindri-dss-review @mwrshah  no labels

- Extract shared release orchestration, deployment drivers, infrastructure support and onboarding guidance from PR #26 without adding the Sindri service.

- Isolate service selection across source changes, registry entries and resolved dependency graphs while preserving shared-dependency releases.

- Define the deployment firewall for new services and GitHub Actions changes: owned registry entries, jobs, locks, environments, IAM/bootstrap chains, resources, secrets and smoke checks.

- Align the create-dss-server skill with registry-driven releases and the explicit recipe-to-hub workflow handoff.

- Keep CI and pre-commit static checks without retaining the temporary release-selection test suite.

#2279 — 1437-generic-sindri-act-as @mwrshah  no labels

- Align outbound Sindri calls with M2M_SECRET, X-M2M-Secret and X-Act-As, preserving server-derived WorkOS identity and provisioning behavior.

- Keep the separate inbound Aerie/Rhodes delegation contract unchanged.

- Update environment examples, external-write credential handling and existing fixtures for the new names.

- Companion to [Sindri #222](https://github.com/AI-Builder-Team/Sindri/pull/222); callers and deployment configuration switch together, with no legacy fallback.

#2277 — AERIE-2375: Find a School source entity, its Schools and exclusion on v2 Directory @marcusdAIy  approved

## Summary

GET /v2/directory/school-sources finds a QuickBooks Company/Class, SIS organization or Finalsite tenant by its opaque Aerie ID or its source ID. It returns the entity with the canonical Schools it's actively linked to, and any exclusion from School mapping with its reason.

Closes [AERIE-2375](https://linear.app/builder-team/issue/AERIE-2375). This is part 2, the reverse lookup plus exclusions. Part 1, School to source links, merged in [#2276](https://github.com/AI-Builder-Team/Aerie/pull/2276).

## Why it's needed

API consumers and agents could read a School's source links after #2276, but couldn't go the other way. They still had to query the warehouse to answer "which School is Finalsite tenant alpha-miami?" or "which School owns QuickBooks class 9 in realm 1?". Source exclusions weren't readable at all.

## Changes

- Contract (public-api-directory.ts). DirectorySchoolSource has:

- sourceSystem, targetType, id and sourceKey;

- displayName, from the current directory generation;

- exclusion ({ reason } or null);

- schools, a list of DirectoryEntityReference with each link's confidence.

- Route (lib/public-api/v2/domains/directory.ts). listDirectorySchoolSources takes a required targetType and exactly one of id or sourceId. The sourceId for a qbClass is realmId:classId, matching the Admin directory; for the other types it's the single source id.

- It's a filtered collection, like listDirectoryAliases, because the Directory contract rejects procedural /by- or /resolve/ paths.

- It returns zero or one entity on a single page, and an unknown entity is an empty page.

- It's gated by ontology.directory.read, like the rest of Directory.

- The agent context adds an aerie.directory.school-source object. Its traps cover:

- the realmId:classId key;

- an empty schools list meaning the entity is unmapped, as opposed to an unknown entity;

- not inferring a School for an excluded entity.

- Handler (convex/publicApi/v2/domains/directory.ts). It resolves the identity by public ID or by the registry-encoded sourceKey, through the existing schoolSourceIdentities indexes. Active School links are read through by_targetType_and_targetPublicId_and_status, bounded at 100. More than that returns the same clean 503 (school_source_links_unavailable) as #2276. The active disposition gives the exclusion.

- Invalid input returns 400: both or neither of id/sourceId, a qbClass sourceId without both parts, or a cursor (there's only ever one page).

## Breaking changes

None. This adds one operation.

## Test plan

- [x] Red/green: the new directoryHttp.test.ts test fails with the source changes stashed and passes with them. It covers:

- a Finalsite lookup by slug, returning the linked School and confidence;

- a QuickBooks Class lookup by realmId:classId and by its Aerie ID;

- an excluded QuickBooks Company, with its reason and no Schools;

- an unknown entity, returning an empty page;

- 400s for a malformed qbClass sourceId, for both selectors, and for neither.

- [x] pnpm vitest run convex/publicApi/v2/directoryHttp.test.ts lib/public-api (252 passed). This includes the updated Directory operation list, the OpenAPI and agent-context snapshots, and curl examples.

- [x] The packages/contracts tests (1,432 passed); tsc for chat convex and app, and for contracts; Biome.

- [ ] After deploy: spot-check a few Schools against dim_school_identity (the ticket's last "Done when" item).

#2276 — AERIE-2375: Serve a School's source links on the v2 Directory School detail @marcusdAIy  approved

## Summary

GET /v2/directory/schools/{schoolId}?include=sourceLinks now returns the School's active links to QuickBooks Company/Class, SIS organization and Finalsite tenant entities. Each link carries its source key and current display name. The Directory agent context explains how to read them.

Part of [AERIE-2375](https://linear.app/builder-team/issue/AERIE-2375). This is the forward half: School to source. The reverse lookup (source id to School) and source exclusions follow in a second PR.

## Why it's needed

School source links were only published to the warehouse (xref_school_source / dim_school_identity). Neither the public API nor the agent context exposed them, so API consumers and agents couldn't answer "which Finalsite tenant, QuickBooks class or SIS campus is School X?" without Redshift access.

## Changes

- Contract (public-api-directory.ts). A new DirectorySchoolSourceLink with these fields:

- sourceSystem, targetType, id (the opaque qbc_/qbcl_/sisorg_/fst_ id);

- sourceKey (the registry's key parts, such as [realmId, classId]);

- displayName, which is null when the entity is absent from the current directory generation;

- confidence.

DirectorySchool gains an optional sourceLinks. The enums come from the School source registry, so a newly registered source is covered without per-source code.

- Route (lib/public-api/v2/domains/directory.ts). The School detail accepts include=sourceLinks, alongside aliases. Other Directory detail routes still accept only aliases, so include=sourceLinks on them returns 400. The Directory agent-context School object adds a sourceLinks field with these traps:

- a QuickBooks Class is [realmId, classId], never the class id alone;

- the Finalsite tenant slug is the finalsite_tenant_id / site value in admissions data;

- only active links are returned;

- a null display name doesn't mean the link is inactive.

- Handler (convex/publicApi/v2/domains/directory.ts). loadSchoolSourceLinks reads active schoolLinks through by_schoolId_and_status_and_targetType, once per source target type. It's bounded at 100 per type and fails loudly beyond that, as the alias include does. It joins schoolSourceIdentities for the key parts and the source's current directory generation for the display name, and sorts deterministically.

## Not in this PR

- Reverse lookup: source id to School, for example a Finalsite tenant slug to its sch_*. It needs a new bounded route over by_targetType_and_targetPublicId_and_status.

- Source exclusions: these are recorded per source entity, not per School, so they don't belong on School detail. They fit better on that reverse route, or on a source-entity read.

- Spot check: the ticket's check against dim_school_identity on a sample of Schools, which can be done once this is deployed.

## Breaking changes

None. sourceLinks appears only when requested. The default School payload, and every other Directory route, is unchanged.

## Test plan

- [x] Red/green: the new directoryHttp.test.ts test fails with the source changes stashed and passes with them. It covers:

- active QuickBooks Class and Finalsite links, with key parts, display name and a null display name;

- an archived link, which is excluded;

- no sourceLinks without the include;

- 400 for include=sourceLinks on a Program.

- [x] pnpm vitest run convex/publicApi/v2/directoryHttp.test.ts lib/public-api (OpenAPI, agent-context and Directory node tests) and the packages/contracts tests (1,432 passed).

- [x] tsc for chat convex and app, and for contracts; Biome.

- [x] A School link whose source identity is missing returns 503 school_source_links_unavailable (Mercy's finding).

#2275 — AERIE-2722: Keep same-name events separate in the agent's get_events output @marcusdAIy  approved

## Summary

The agent's get_events output now keeps recurring same-name marketing events as separate occurrences. Each row carries its stable eventId.

Part of [AERIE-2722](https://linear.app/builder-team/issue/AERIE-2722) (agent-tool slice). This follows the v1 slice in [#2229](https://github.com/AI-Builder-Team/Aerie/pull/2229) and the v2 slice in [#2231](https://github.com/AI-Builder-Team/Aerie/pull/2231).

## Why it's needed

Both agent paths, the get_events data tool and the getEvents query, returned marketing rows with eventName but no eventId. Two occurrences of "Open House" came back as indistinguishable rows. Nothing told the agent they were different events, so it could merge or misattribute them when comparing or totalling.

## Changes

- agent/queries.ts: one mapper (agentMarketingEvent) and one sort (compareMarketingOccurrences) now serve both paths, so the two can't drift apart.

- eventId: each marketing row adds eventId. It is null on rows published before event IDs, because the column is optional during the rollout.

- Sort order: newest start first, as before. Ties on equal start times are now broken by eventId, so the order is deterministic.

- agent-system-prompt.ts: the get_events line tells the agent that each marketing row is one occurrence identified by eventId. Same-name rows must not be merged by name.

- Shadow-day rows are unchanged: their table has no event ID, and they're out of scope for AERIE-2722.

## Breaking changes

None. The change adds one field to the agent tool's output, and the existing fields and order are unchanged apart from the tie-break.

## Test plan

- [x] Red/green in convex/agentQueries.test.ts: three new tests fail without the source change and pass with it:

- same-name occurrences stay separate with their own eventId and a deterministic order;

- legacy rows return eventId: null;

- the get_events data tool returns the same identities.

- [x] pnpm vitest run convex/agentQueries.test.ts convex/publicApi/v2/agent.test.ts (159 passed) and the packages/contracts tests (1,432 passed).

- [x] tsc -p convex/tsconfig.json --noEmit, contracts tsc --noEmit, Biome.

#53 — Publish diligence site creation for write keys (AI-1234) @kevalshahtrilogy  no labels

Linear: [AI-1234](https://linear.app/builder-team/issue/AI-1234/publish-diligence-site-creation-for-write-keys-in-rhodes-dss)

## What

- Publishes POST /portfolio/sites for write keys, through src/aerie/allowlist.json and then pnpm sync:openapi. It creates a diligence site for an additional premise inside an existing campus, linked to mainSiteRef.

- The contract re-sync is limited to this source release: the new write, mainSite on site reads (PortfolioSiteSummary), and the mainSiteRef filter on GET /portfolio/sites.

- Enablement explains how to create a site and who may do it, how idempotent replays behave, and how to read linked premises. The Dictionary now counts 21 published writes.

- New test: a read key is refused on this POST (the same path serves the list read), and a write key's request is relayed as its owner with the body unchanged.

Nothing is deleted or newly logged.

## Business Value

Diligence teams, starting with Robbie, can open diligence on an additional premise straight from Rhodes as themselves, without asking Edu Ops to create the site by hand. Agents can then find a campus's premises in a single filtered read.

## Manual Effort Estimate

Proposed: about 1.5 hours (allowlist, contract re-sync review, docs, a relay test, checks). Keval to confirm or adjust.

## Verification

- pnpm check (72 tests), pnpm build and pnpm synth --no-lookups all pass.

- The source operation is live in production (Aerie release #2272, CD succeeded). This PR has not been deployed; nothing here proves the Rhodes deployment.

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

#2274 — Clean errors and legacy statuses for premise create/list (AERIE-3085) @kevalshahtrilogy  approved

Follow-up to #2266 for AERIE-3085. It fixes Mercy's two findings on release PR #2272.

## Changes

- Clean errors. createdSiteResponse now returns problem details instead of throwing a raw Error. A missing public ID returns 500 site_identity_incomplete. The created Site vanishing before read-back returns 500 site_create_incomplete.

- Legacy statuses on mainSiteRef. Before this change, the list matched the stored status exactly, so premises still stored as open or completed never showed up under active, and a premise stored as closed never showed up under cancelled. The list now reads one index range for each stored status that normalizes to the requested one and merges them in creation order with convex-helpers mergedStream. Pages stay full, the cursor still works, and nothing is filtered out after a page is read.

- The page-building code is moved into portfolioSitePage, so both list paths use it.

## Tests

- A new test pages mainSiteRef at limit=1 across premises stored as open, completed, active, closed and paused:

- the default and status=active both return the three active premises, in creation order;

- cancelled returns the closed one;

- paused returns the paused one.

- A new test checks that a created Site without a public ID fails with a ConvexError whose code is site_identity_incomplete.

- Public API and lib tests: 909 pass. Convex typecheck, biome, lint:boundaries and lint:read-bounds pass.

## Business Value

Unblocks release PR #2272, which ships the additional-premises API to production. It also makes sure that premises with legacy statuses don't silently drop out of the main Site's list, and that errors reach Rhodes DSS and agents as clean messages.

## Manual Effort Estimate

About 2–3 hours of focused work. This is a proposed number for Keval to confirm or adjust.

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

#221 — 1336-2sindri-prod-release @mwrshah  approved

- Bundle IBM Plex Sans and Playfair Display as local WOFF2 variable fonts with their SIL licenses and pinned source provenance.

- Replace next/font/google with next/font/local so builds no longer depend on Google Fonts responses.

- Preserve existing CSS variables and weight ranges, font preloading, swap display, and metric-adjusted fallbacks.

#3928 — feat(acq-perf-review-v2): add direct-link Jive legacy review @sanketghia  changes requested

## Summary

- Keep /acq-perf-review-v2 focused on the existing Cloudsense/new-acquisition view.

- Add Jive at /acq-perf-review-v2-legacy, protected by the existing acquisition-performance permission and omitted from sidebar/dashboard navigation.

- Require the complete 55-quarter Jive plan from Q2'17 through Q4'30 and the 15% sheet tax rate; show legacy plan and actuals without budget or forecast series.

- Render source and reconciliation details as a bulleted note.

## Source handling

- Require every historical sheet P&L quarter from Q2'17 through Q4'21. Missing sheet quarters make the legacy source unavailable.

- Require a post-Q4'21 globally closed CBA calendar. From Q1'22, CBA actuals replace sheet data only when every mapped class has all three closed months. Incomplete globally closed quarters are listed in response metadata and the source note; Q4'25 is omitted because Jive Consulting has only one closed month.

- Use sheet ARR carry-forwards through Q4'19. Every displayed actual from Q1'20 onward requires a complete Redshift quarter-end ARR snapshot; missing snapshots make the source unavailable.

- Only current IgniteTech Jive Consulting and Jive Product classes are included. CBA Other Income (Loss) remains unmapped and excluded from P&L totals. The PBCS account bridge for NHC Opex remains unresolved.

## Validation

- uv run pytest tests/acq_perf_review_v2/ -q — 61 passed. Unit tests use the repo-wide Redshift mock.

- A separate read-only service smoke check against finance_dw returned 55 plan rows, 37 actual quarters through Q3'26, disclosed Q4'25 as a coverage gap, and found no missing ARR among displayed post-Q1'20 actuals.

- Backend Ruff and Pyright passed. Frontend ESLint, Prettier, TypeScript check, pnpm lint:pr, and production build passed.

- The migration is applied to the connected finance_dw; the Development API runtime principal has SELECT on all five legacy tables.

#2266 — Add POST /v2/portfolio/sites for premises in diligence (AERIE-3085) @kevalshahtrilogy  approved

## Summary

[AERIE-3085](https://linear.app/builder-team/issue/AERIE-3085): Robbie needs to open diligence on additional premises inside existing campuses through the public API (relayed by Rhodes DSS). This adds the smallest write that does it.

- POST /v2/portfolio/sites (createPortfolioSiteV2). The body is { name, address, mainSiteRef, marketId? }. It creates an active, diligence-stage Site through the shared provisionSiteInTransaction path, which provisions diligence work and the P2 catalog and writes an audit entry. The new Site:

- is linked to the main Site;

- inherits the main Site's school size class, School Chain, Market (unless marketId is given) and diligence DRI;

- gets a slug minted as <main-slug>-<name> that does not collide with any Site, ontology alias or conversion.

- Schema: adds an optional sites.mainSiteId and an index by_mainSiteId. This only widens the schema; there is no migration. It also adds "site" to the resourceType values of publicApiWriteIdempotency.

- Reads: Site summary and detail now include mainSite: SiteReference | null, and GET /v2/portfolio/sites gains a mainSiteRef filter.

- Auth: no new capability. The key needs operations.portfolio.read and operations.driSites.write. The owner must have global operations.siteFields.write or be a current DRI of the main Site; both are checked again in the committing transaction. Act-as delegation works as it does for other v2 writes.

- Guards: the request requires an Idempotency-Key. A replay within 24 hours returns the created Site with 201, and different input returns 409 idempotency_conflict.

- 404 main_site_not_found

- 409 main_site_ref_ambiguous / main_site_cancelled

- 422 main_site_is_premise (one level only), blank name or address, or a schema violation

- 404 market_not_found

- Docs: docs/additional-acquisitions.md now explains how this fits AERIE-2727. The link exists only during diligence; when the deal closes, the existing conversion folds the premise into the main Site as an additional acquisition.

Keval approved the design and its defaults before implementation: child diligence Sites, the DRI copied from the main Site, and global writers plus main-Site DRIs allowed to create.

### Known limits (follow-ups, not in this PR)

- These Sites are not written back to REBL3. A later REBL3 row for the same premise could match the main Site by address or be provisioned as a duplicate.

- No Drive folder is provisioned automatically, matching Special Program creation.

- Converting a main Site that still has linked premises leaves their mainSite as null on reads.

- Rhodes DSS must add createPortfolioSiteV2 to its allowlist before callers can use it.

## Business Value

Robbie's team can open diligence on an additional building or premise at an existing campus directly from Rhodes DSS. Until now that meant asking for a Site to be provisioned by hand, or squeezing the premise onto the main Site's acquisition card, where it gets no diligence workflow. Each premise now gets its own diligence work units, documents and DRI while staying linked to its campus. Callers can list a campus's open premises, so expansion diligence is visible per campus.

## Manual Effort Estimate

Proposed: ~2 days (≈14 focused hours). Keval, please confirm or adjust. This covers working out how Site provisioning, the v2 write dispatcher, idempotency and DRI authorization fit together; the schema and contract change; and about 300 lines of contract tests plus updates to existing contract and envelope tests.

## Test plan

- [x] New chat/convex/publicApi/v2/portfolioSiteCreate.test.ts:

- create, replay, conflicting replay and slug de-duplication;

- mainSite on the detail and list reads, and the mainSiteRef filter;

- auth: unauthenticated, missing scope, non-DRI, main-Site DRI and global writer;

- error cases: missing, cancelled and nested main Site, blank name, unknown market, extra field, missing Idempotency-Key.

- [x] vitest run convex/publicApi convex/rhodes convex/portfolio convex/infrastructure lib/public-api: 112 files, 1735 tests pass.

- [x] typecheck:convex, typecheck:app, biome, and lint:boundaries, lint:convex-paths, lint:read-bounds, lint:test-architecture, lint:knowledge.

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

#219 — 1335-2sindri-prod-release @mwrshah  no labels

- Keep runner image preparation on production using the existing production-only deploy role; remove the main image job and release gate.

- Reuse verified input-tagged images, build only missing images, and preserve selective Convex deployment and activation ordering.

- Use existing BatchGetImage permissions and restore the production publishing policy without introducing new credentials or roles.

- Update release instructions and remove obsolete builder policies and image-wait tooling.

#2270 — 1435-prod-deploy-tests @mwrshah  approved

- Remove the vendored Sindri OpenAPI JSON and manual copy workflow; generate committed client types directly from canonical /skillspec discovery.

- Remove the runtime revision pin and date-mismatch alerts. Keep authenticated availability checks and daily failure-alert deduplication.

- Preserve transparent Forge proxying, including caller-provided version headers, and existing skill-side discovery refresh.

- Update generated Convex bindings and developer instructions.

#218 — 1334-pr178-salvage @mwrshah  changes requested

## Changes

- Separate immutable createdBy from credential accessScope; remove redundant owner/steward fields and return personal access to the creator on demotion.

- Update the API, credential UI, workflow credential references, leases, and runner contract while preserving current main's workflow-instance model and newest-updatedAt sorting.

- Prevent later visibility edits from exposing instances that reference a demoted personal credential.

- Add the strict final schema, regenerated OpenAPI contract 2026-11-06, and fail-closed one-time migration tooling with a separate permissive checkpoint and cutover runbook.

## Rollout requirements

- Coordinate Aerie's contract pin, credential forms, and response types with Sindri. Back up production, drain runners/leases, freeze traffic, execute the checkpoint audit/backfill, then deploy the strict schema and remove the callable migration functions.

- Read-only production inspection found 424 rows in the migration's scan scope, with 372 rows requiring conversion and zero preflight issues. Frontend resource tables already have valid update timestamps; no date backfill is needed. No production data was changed.

#52 — Re-sync the source contract: cursors up to 6,144 characters (AERIE-3086) @kevalshahtrilogy  no labels

## What

Runs pnpm sync:openapi after source release #2268. Every list's cursor parameter now allows up to 6,144 characters, up from 512 (one list was 1,024). No other contract changes.

## Why

Devin reported (feedback 8a6b3a8b…) that the source issued 514-character cursors and then rejected them. The source fix is live, and paging a site's document list to page two now returns 200. This brings Rhodes' published contract in line.

## Business Value

Agents can read complete document lists from the published contract, without stopping at the first page.

## Manual Effort Estimate

About 15 minutes by hand (proposed; Keval to confirm).

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

#217 — 1333-2prod-deploy-tests @mwrshah  changes requested

## Changes

- Select Convex deployments from runtime input fingerprints and the last successful component marker; follow shared imports and exclude test-only files.

- Prepare verified runner images on main after CI, then reuse immutable digests in production without rebuilding. Parallelize image lookup with Convex deployment and skip unchanged ECS revisions.

- Add an explicit runner dependency refresh, component outcome reporting, and release checks for exact-head image readiness, required checks, backup identity, and guarded merge.

- Update deployment/operator documentation. Public API and skill-spec endpoints remain unchanged.

## Rollout prerequisites — before merge to main

- Provision sindri-github-image-builder using the new main-only trust and ECR-only permissions policies.

- Update sindri-github-deploy permissions for ECR image metadata reads; keep its production-only trust.

- Permit the workflow token to update refs/tags/sindri-convex-deployed.

- Confirm the production dispatcher selects the task family rather than a pinned ECS revision.

- Let exact-head main image preparation succeed before the first production release. No AWS configuration or production deployment has been performed by this PR.

## Validation

- Application and runner typechecks, Biome, Convex-reference lint, Python Ruff, shell/Node syntax, YAML parsing, staged-tree fingerprints, and commit hooks passed.

- Next.js/container builds and live deployment verification have not been run locally; CI performs the builds.

#2267 — Accept the v2 nextCursor the API returns (AERIE-3086) @kevalshahtrilogy  approved

Linear: [AERIE-3086](https://linear.app/builder-team/issue/AERIE-3086/public-api-v2-accept-the-nextcursor-it-returns-raise-512-char-cursor)

## Problem

GET /v2/portfolio/sites/{siteRef}/documents (listSiteDocuments) returns a 514-character nextCursor, then rejects that same cursor with 400 invalid_cursor ("cursor must not exceed 512 characters"). No site's document list can be read past page 1. Devin Bates hit this on 20624 N 76th St and 6210 Old Pineville Rd.

## Root cause

Most v2 list cursors wrap an opaque Convex continueCursor plus filter context, via JSON, base64url or encodeURIComponent. The document latest-view cursor, for example, embeds the site slug. Convex doesn't bound cursor length, and the shared default cap of 512 is smaller than real production cursors. The same risk applies to every other cursor list on that default (41 operations: portfolio sites, directory, work units, notes, admissions drilldowns, and others) and to the three work-management task lists capped at 1,024.

## Change

- PUBLIC_API_V2_DEFAULT_CURSOR_MAX_LENGTH: 512 → 6,144. Signed-source cursors already use this bound, and it sits under the 8,192 absolute limit.

- Removed the three cursorMaxLength: 1_024 overrides in work management, so those lists inherit the new default.

- The published OpenAPI cursor parameter maxLength comes from the registry, so it now reads 6,144 for these operations. Rhodes DSS needs to re-sync its v2 contract after deploy.

- Cursor contents are still checked by each operation's decoder (scope, filters, revision). Only the length pre-check moves.

## Tests

- New end-to-end regression in documentsHttp.test.ts: a site with a long slug, paged limit=1, returns nextCursor values longer than 512 characters, and each one is accepted on the next call. Against the old cap it fails with the exact production error ("cursor must not exceed 512 characters").

- http.test.ts: the default list accepts 514 and 6,144-character cursors and rejects 6,145. An explicit tighter override (512) still enforces its own cap.

- OpenAPI and task-board contract tests updated to the new published bound.

- chat convex/publicApi/v2 + lib/public-api/v2: 640 passed. packages/contracts: 1,432 passed. pnpm typecheck is clean and Biome is clean on changed files.

## Business Value

Agents and integrations (Rhodes DSS, diligence rendering checks) can't currently read any site's document list past the first page, and nothing else in the v2 surface is protected from the same failure once its cursors grow. This makes v2 pagination work at real-world cursor sizes for every list. Until now the only workaround was limit=100, which silently caps coverage at 100 documents per site.

## Manual Effort Estimate

~3 hours (proposed; Keval to confirm or adjust): reproduce, trace the cursor format and cap plumbing, audit the 48 cursor-paginated operations, write the regression, and update the contract tests.

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

#51 — Publish site integrations so relink can register large Drive originals (AI-1233) @kevalshahtrilogy  no labels

## What

- Publishes GET /portfolio/sites/{siteRef}/integrations. It returns reference IDs only, including driveFolderId, the site's managed document folder.

- Enablement now explains how a write key registers a file that's already in the site's folder but over the 15 MiB upload limit: upload a small stand-in with the right type and title, then relink it to the original with driveFileId and rootFolderId.

- Re-syncs the source contract. That also brings in document file-hash, size and version fields, and raises the search bound to 25 queries.

## Why

Robbie needs to register Chapala's original rendering PDF (28.82 MiB) and film (551.99 MiB). Relink was already published, but agents couldn't find the folder ID it requires, so it couldn't actually be used.

## Business Value

Diligence renderings and walkthrough films of any size can be registered in Rhodes. Agents such as Dean then find them, instead of reporting assets as missing.

## Manual Effort Estimate

About 2 hours by hand (proposed; Keval to confirm).

## Verification

pnpm check (71 tests), pnpm build and pnpm synth --no-lookups pass. Not yet tried with a real keyed relink.

A proper site-level "register existing file" route belongs in the source and is a follow-up.

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

#2264 — 1434-workos-push-failure @mwrshah  approved

- Allow verified existing WorkOS accounts without DSS membership to complete provisioning.

- Link the account, push Aerie metadata, and create the missing DSS membership.

- Preserve identity-conflict checks and inactive/pending membership safeguards.

#2257 — feat(finance): expose exact Ramp counterparty source labels @ashwanth1109  approved

## Business Value

Makes merchant labels available for all 793 validated Ramp-linked QuickBooks postings ($337,612.39) in the vendor-reporting review, while preserving existing Vendor identities and accounting totals. Ambiguous or unsupported evidence remains explicitly unresolved.

## Changes

- Add core_education.fct_expense_counterparty_attribution, a read-only view with one outcome per existing QuickBooks P&L posting. Existing vendor names/IDs take precedence; recovery requires one supported Ramp URL, one source record, a merchant name and an exactly matching signed USD amount.

- Expose source evidence coordinates and observation timestamps without treating card merchants as canonical Vendors. Document the existing Ramp extract's transitional legacy placement.

- Add actual Redshift SQL fixture coverage and reconciliation queries. No persisted accounting facts, accepted identity mappings, source precedence, report consumers, pipeline runtime or infrastructure stacks change.

## Pre-merge Live Validation

- Deployed the candidate view to production before merge. All 395,034 postings retain cardinality, financial totals, existing names/IDs and full parent-row fingerprints; all 793 scoped references resolve.

- Passed 39 semantic cases using the actual view SQL in private Redshift fixture objects, including duplicate keys, invalid/multiple URLs, identity precedence, sign/currency/precision mismatches and refunds. Fixture objects were removed. Existing financial DDL tests: 43 passed. Changed-file Ruff and git diff --check passed.

- After deployment, preflighted and ran the deployed ramp-raw-sync producer with failure notifications suppressed. Run 4054c884-f7f2-45e1-90d2-e5d98033cc6f succeeded: 9,909 fetched/inserted records across its standard three complete Pacific weeks. Verified immutable source payload hashes and repeated posting/identity/financial checks after completion.

- View deployment statement: cc994f37-4458-4395-9dfc-bfc79692aaaa; final reader/publication check: 3faccfb5-f2be-4808-b238-5f6b0afe2f6d; compiled definition MD5: 731acc958da742444785526d16df7194.

- Frozen validation results: s3://klair-backend-uploads/surtr/quickbooks-core-tables/manual-review/vendor-reconciliation-20261105/ramp-recovery/live-validation-results-90fd5ff5df568efed2fba856eaced1cd3c758a5719426d05f6e754f549f34c57.json.

The current producer run does not establish complete historical Ramp coverage; retained observations expose their actual age. Consumer activation remains subject to the separate book/period reconciliation.

## Implementation Effort

Estimated 2–3 engineering days to implement the model, build warehouse-backed semantic fixtures, validate the live source refresh, and document source/identity boundaries without AI assistance.

## Linear

https://linear.app/builder-team/issue/SURTR-1701

#2263 — Remove ISP integration from the analytics worker @marcusdAIy  approved

## Summary

Removes the ISP integration from the analytics worker: the ISP layer of the Rhodes merger and the matterport-discovery scheduler.

## Why it's needed

In prod, the analytics worker's ISP reads (Klair-ISP-Jobs DynamoDB + klair-isp-outputs S3) fail with "The security token included in the request is invalid". ISP is no longer maintained, so fixing the credentials isn't worth it.

The failure was also doing collateral damage: when the ISP bulk fetch failed, the Rhodes merger held all writes for the cycle, so HubSpot-sourced updates were blocked too.

## Changes

- Rhodes merger (sync/src/upstream/rhodes/sync.ts, field-merge.ts): drop the ISP layer, its batch prefetch, the hold-writes early return, and the isp_bulk_failed shadow reason. FieldSource is now "hubspot" | "schemaUi" | "none".

- Capacity fields (numberOfClassrooms, netFloorArea, occupancyLoad) stay in the merged shape so the Surtr shadow compare still compiles, but they have no source and are never sent. Existing Rhodes values stand.

- Analytics worker (sync/src/analytics-worker/index.ts): remove the matterport-discovery scheduler and its config/interval.

- Delete upstream/isp/fetcher, rhodes/isp-adapter, rhodes/matterport-from-isp-sync, rhodes/matterport-discovery-shadow, and the dry-run-matterport-discovery-shadow script.

- Drop @aws-sdk/client-dynamodb, @aws-sdk/client-s3, @aws-sdk/util-dynamodb from sync.

- Tests updated accordingly; stale doc comments cleaned up.

Left alone on purpose: the isp-api service, its IAM in infra/, the chat ISP dashboards, and the Surtr Gateway's "isp" provenance vocabulary (that's Surtr's data, not ours).

## Breaking changes

None for callers. Ops follow-up after merge: MATTERPORT_DISCOVERY_MODE and the AWS keys used for ISP in the prod .env are no longer read by the worker and can be removed.

## Test plan

- [x] pnpm exec tsc --noEmit -p . in sync/

- [x] vitest run on rhodes/sync.test.ts, field-merge.test.ts, site-metadata-shadow-compare.test.ts, tests/analytics-worker/index.test.ts (106 passed)

- [x] Pre-commit hooks (typecheck-sync, biome)

- [ ] After deploy: analytics-worker logs show no ISP token errors and the Rhodes merger writes again

#2254 — Resolve QuickBooks Class business units and send a weekly Finance digest @ashwanth1109  approvedmercy-allow-critical

## Business Value

Resolve Finance-approved QuickBooks Classes to real Schools or explicit non-school business units, so central costs, camps and initiatives stop appearing as missing Schools. Deliver a weekly school-year-to-date digest to Ashwanth, Marcin, Jan, Keval and Prabal, while retaining self-only test delivery and immutable one-send-per-week evidence.

## Changes

- Add 11 governed non-school business units and 27 exact Realm/Class crosswalks. Add seven missing financial Class-to-School policies; preserve Port Chester's existing source mapping. Keep TSA Microschools unresolved pending Finance clarification, as explicitly requested.

- Preserve PR #2248's newer source-qualified Greenwich posting decisions. The guarded installer patches only the inspected live writer, preserves its owner/ACL and unrelated code, and seeds accepted policy through an atomic owned migration procedure.

- Publish one Core posting-assignment view with resolved School, resolved non-school, unresolved Class and classless partitions. Update report compatibility checks, policy fingerprints, accounting totals, HTML/CSV classification and source-race guards together.

- Schedule Mondays at 10:00 UTC (15:30 IST), retain 1 July-to-report-date coverage, and use UTC Monday weekly delivery claims. Update the exact application/SES production audience; preserve historical daily receipts, uncertain-send protection and self-only tests.

- Leave reader-policy ownership with the DBA. The legacy reader helper now only compiles required report-query columns/joins and verifies worktable capabilities and rejects --apply; pipeline DDL no longer grants/revokes reader access. The exact access request is retained for DBA review.

## Validation

- 230 Core tests and 152 report tests passed; 73 existing opt-in Core cases skipped. The actual Redshift TEMP allocation fixture also passed, scoped Ruff and whitespace checks passed, and the earlier complete CDK suite passed all 1,022 tests across 23 suites.

- Mercy round 1: fix classification from effective Finance dispositions, including stale stored Schools and line-vs-Class business-unit precedence. The writer already applies source-qualified posting overrides last; new SQL regressions execute that canonical UPDATE. The read-only helper now compiles all five actual report queries, including required columns and joins; its live reader check passed.

- Applied the candidate view via canonical transaction fecda385-2db4-4184-96fc-f4c67fca40ad. Quiet deployed preview e5aa1741-d43e-41bd-a9c6-c9efc56c09b3 succeeded with zero compatibility errors and identical 46 grouped rows. All posting values, School assignments, policies/creation metadata, Greenwich decisions, writer body and view owner/ACL remain unchanged. Preview sent no email and left the production receipt/schedule unchanged.

- Candidate task commits were replayed onto production 337e7442 in a separate checkout. Only the Core and report stacks deployed, each separately with --exclusively, [1/1] and verified CloudFormation UPDATE_COMPLETE.

- Quiet supported Core run c7dbb88e-a88d-483d-bff1-189cb63da9d6 succeeded. All 395,034 source posting identities/measures remain unchanged. Seven new School policies resolve 2,071 all-history postings; every other School-assignment fingerprint, all 41 preexisting School policy rows and all 215 Greenwich review rows remain unchanged.

- The Core assignment contract has exactly 395,034 unique postings and zero target mismatches. The 27 non-school Class policies classify 79,568 all-history postings correctly. Two deliberate rollback probes and the final owned-migration idempotence check passed, including unchanged policy creation metadata and removal of the temporary migration procedure.

- Deployed report preview succeeded. One test email went only to Ashwanth; exact CSV/MIME/SES receipt checks passed. The same-week retry skipped with the same SES acknowledgement. All four platform runs are SUCCESS with failure-notification suppression retained; automatic children preserve it.

- Final deployed Python/SQL bytes match the candidate. Production delivery was enabled only after validation; the first scheduled Finance delivery is 9 November, 10:00 UTC / 15:30 IST. No production-audience email was sent during validation. A separate user-authorized Finance digest was subsequently sent on 5 November, outside validation.

CI exposed the existing dev-entrypoint asset cleanup race (ENOTEMPTY after five retries). The test now uses a bounded 20-retry cleanup window; runtime behavior and pipeline assertions are unchanged. All eight checks on the reviewed head b24f9074 subsequently passed; Mercy's cleanup finding cited superseded failed run 42047324490. The task commits were cleanly rebased onto main 6104a54e after the Greenwich PR merged. The review fix changes the assignment view and capability helper; deployed report runtime bytes and schedule configuration are unchanged.

Source, procedure, execution and reconciliation evidence: pipelines/runners/quickbooks-core-tables/validation/2026-11-05-finance-class-mapping.md.

## Required Review and Separate Follow-ups

DBA ownership review is required before merge. During initial validation the legacy helper applied reader SELECT grants on four new dependencies and session TEMP, and initial Core DDL applied new-object reader grants/PUBLIC revokes. The final code removes those write/enforcement paths. The validation record discloses the exact initial scope and readbacks; the DBA owns approval or adjustment of those live permissions. They are not claimed to be DBA-approved by this PR.

TSA Microschools remains intentionally unresolved. Newly encountered/unapproved Classes remain visible in the digest. The shared Finance line-allocation table is the already-live contract from PR #2248; this change neither duplicates its canonical DDL nor overrides its approved rows.

Q22, School Performance QuickBooks, Unit Economics and Table 3 child refreshes succeeded. The separate Aerie financials child still fails at its existing 315-posting Facilities account-policy prerequisite; its failure is quiet and it does not block this Core-backed digest. Registry metadata publication follows the normal release.

## Implementation Effort

Approximately 3–4 engineer-days without AI assistance for policy/identity reconciliation, guarded migrations, Core/report integration, ownership corrections, regression coverage and isolated production validation.

## Linear

https://linear.app/builder-team/issue/SURTR-1699

Related: https://linear.app/builder-team/issue/SURTR-1650 and https://linear.app/builder-team/issue/SURTR-1496 .

#2255 — fix(netsuite): fence thirteen historical Core GL transaction repairs @ashwanth1109  approved

## Business Value

Historical Core GL now includes twelve source-backed reclassification journals and excludes one unsupported $80,070.67 expense. The repair changes only thirteen verified transactions. It avoids a whole-May rebuild that would also remove 242 unrelated rows and change the period net by $1.70M.

## Implementation

A temporary, warehouse-owned maintenance procedure reuses the pinned production canonical transformation in shadow mode, checks all 15 required inputs and nine reviewed raw/beforeimage/candidate signatures, then atomically publishes only the fixed transaction scope to the three mirrored Core tables. Source accounting keys, subsidiaries and amounts reconcile independently; every unrelated published row retains its fingerprint/count/signed/gross totals.

The approved batch acquired locks before its first snapshot, installed/called/dropped the incident procedure, and completed in 419 seconds. The canonical writer, normal schedules, infrastructure, consumers and source precedence remain unchanged. The SQL is preserved as a guarded incident implementation and audit record; the frozen beforeimage fence prevents a second application. No further production release is needed for this completed invocation.

## Production Validation

Explicit user approval covered the exact Core scope and temporary pause. Candidate commit b9524372e2859356d1b8cc53e419833fbce512e1 was deployed and applied before merge through production batch 4be8bc73-4a32-4138-9f7e-6e4d6ca7f047. All ten atomic statements finished successfully.

- Fresh source capture: 13/13 headers, 207/207 accounting lines, 207/207 transaction lines; declared totals, terminal pagination and immutable payload hashes verified. Backups for all six raw/Core surfaces were re-read and hash-verified before apply.

- All 15 required inputs passed readiness on the approved daily source boundary. Both TransactionLine reconciliation children succeeded; no failed/deferred work.

- Each Core target changed from one unsupported $80,070.67 row to 180 source-backed P&L lines: $0 replacement net, $15,476,868.14 gross, net correction -$80,070.67 per mirrored reporting table.

- All 180 source P&L keys and amounts match NetSuite. Independent post-commit queries verify all replacement-field fingerprints and all 82 legacy transaction/period/subsidiary/account cohorts.

- Unrelated rows, financial totals and full-row fingerprints match within the locked publication transaction. Independent catalog postflight verifies the canonical writer unchanged and the incident procedure absent.

- Two production shadow runs and four negative controls passed before apply. Invalid review hash, writer version, daily epoch or transaction scope reject before publication and roll back temporary DDL.

- git diff --check passes. The SQL SHA-256 is unchanged by the second, documentation-only commit. Pre-merge live write validation is complete.

Two legacy raw lines on the excluded non-P&L transaction retain missing typed IDs/truncated memos. Their source keys and financial fields were checked; they contribute no replacement expense. Broader period drift, QuickBooks precedence, vendor recovery and headcount classification remain separate work.

## Implementation Effort

Estimated 2–3 engineer days without AI assistance for source tracing, guarded SQL, immutable evidence, all-account reconciliation and production validation.

## Linear

https://linear.app/builder-team/issue/SURTR-1700

#2248 — Apply Greenwich Finance allocations and unblock CT School publication @ashwanth1109  approved

## Business Value

Applies Finance's approved Greenwich transactions to their intended Schools while preserving current source amounts and later source reclassifications. The warehouse resolves 131 Armonk/Founders P&L postings, 59 intentional Central/camp dispositions, the $16,272.19 Armonk laptop allocation, and 16 approved CT CAPEX lines totaling $113,784.87. An unrelated School without a Program stays visible as unresolved and no longer blocks valid Greenwich publication.

## Changes

- Preserve the immutable 198 P&L and 17 CAPEX review rows and their exact evidence, source coordinates, amounts and approval metadata. Add separate CT identity evidence for the user-created School and its three authoritative Aerie links; require all exact current links before activating the 16 CT decisions.

- Apply posting-specific attribution, protect CAPEX source indices with amount/description fingerprints, and include nullable School in monthly/quarterly grain, v2 IDs, uniqueness and reconciliation.

- Publish current School-to-Program coverage and its durable run summary. Permit missing Programs as explicit unresolved findings; retain ambiguity, dangling-target, source integrity and atomic publication guards. Preserve Alpha Virtual and leave its Program decision with Farhan.

- Make both guarded installers reproducible. Preserve live procedure bodies outside the reviewed change, owners and ACLs. Invoke the bounded six-account prerequisite migration with an independently inspected snapshot ID; reject conflicting policy or source evidence. Seven new Finance decisions remain unresolved.

## Validation

- 409 tests passed: QuickBooks Core (223), Q22 (65), ontology (120), and one explicitly executed live TEMP allocation fixture; 73 other opt-in cases skipped. Scoped formatting/lint and whitespace checks pass. Twenty installer tests include the required snapshot, conflicting catalog, bounded reference seed, exact CT links and empty-ACL regression.

- Real complete financial and ontology candidate writers passed their assertions before intentional rollback. Session TEMP fixtures exercise actual allocation, rollup and Program coverage SQL. No permanent test namespace or database privilege grant was created.

- Candidate changes were replayed onto the latest production baseline in a separate checkout. Only Core and ontology pipeline stacks were deployed in separate --exclusively invocations; each showed [1/1] and CloudFormation UPDATE_COMPLETE.

- An independent production release replaced the Core candidate during validation. After detecting its stale Class-only verifier, the task changes were replayed onto production 337e7442 and the Core stack alone was redeployed to task 17 with the inspected candidate image.

- The Alpha HubSpot source, Program directory (119 rows), Unit Economics (1,197 rows), Table 3 (1,197 rows), and Admissions (17 marts) prerequisite refreshes succeeded. The live ontology candidate succeeded with 120 Schools and 119 Programs; 118 Schools mapped, one unresolved Alpha Virtual, one archived.

- Final quiet Core run ef5797ef-d041-4d3d-9c67-bcd352de9208 succeeded on task 17. All 196 surviving reviewed source postings and all 16,390 CAPEX source/business rows equal their baselines. All reconciliation/error checks are zero.

- Final Q22 run 1e413017-b77f-4102-b186-3f805d712468 succeeded. Exactly 16 reviewed CT lines map for $113,784.87 and the laptop remains Armonk for $16,272.19, with zero attribution mismatches and unchanged same-source network CAPEX $75,278,271.75.

- Final School Performance QuickBooks (1,581 rows), Unit Economics and Table 3 (1,216 rows each) succeeded. The full Aerie financials chain reaches the Facilities account-policy gate; it remains blocked on 315 current-quarter postings requiring Finance treatment.

- The checked-in session TEMP fixture executes actual guards/updates for pending inherited mappings, changed source coordinates, non-School treatment, changed amounts, invalid destinations and duplicate review rows; it passed live without changing any published object.

Full source reconciliation, run/statement IDs, procedure hashes and deployment evidence: pipelines/runners/quickbooks-core-tables/validation/2026-11-05-greenwich-finance.md.

All manual invocations and their automatic children preserve skip_failure_notification=true. Scheduled notifications, logs and operational alarms are unchanged. No source financial values, accounting books or open-state flags were rewritten.

## Remaining decisions

Finance still needs to approve seven source Accounts (60221/60251 in two books, 69110, 61900 and unnumbered Facilities/Support 160, including its reporting GL/bucket). Four P&L lines totaling $16,246.78 still need capitalization into the CT source book. Alpha Virtual's Program is a separate follow-up with Farhan and does not block Greenwich. No Finance email was drafted or sent; no merge was performed.

## Implementation Effort

Approximately 3–4 engineer days without AI assistance for source reconciliation, governed policy and identity installation, School-aware rollups, ontology contract repair, regression coverage, isolated deployments and live validation.

## Linear

Related to https://linear.app/builder-team/issue/SURTR-1496

#2252 — SURTR-1697: Formalize five reviewed Alpha QTD school identities @ashwanth1109  approved

Five quarter-locked Alpha Budget API entries lack Finalsite identifiers even though their Aerie Site/School identities are known. Add the five mappings approved by Ashwanth on November 5—Franklin, San Juan PR, San Pedro, Santa Clara and Sausalito—using exact Alpha, Site and School IDs. The locked population remains 56, with 49 resolved and seven explicit exceptions.

Resolution checks the current unarchived Aerie Site link and coherent Rhodes lineage, and withholds conflicting Finalsite identities or changed/duplicate links. A focused installer backs up definitions/ACLs and atomically updates only the policy and Core resolver views. Existing financial source gates remain intact.

## Business Value

Enables five additional school report identities without guessing school ownership or duplicating another school's financial scope. Approval and source-link evidence remain queryable; Sausalito stays separate from Marin County.

## Validation

- 142 population, SQL, reviewed-identity and operator tests passed; scoped Ruff and diff checks passed.

- Candidate definitions deployed before merge; all 75 directory entries compared. Only the five approved identities changed.

- Production report preflight run 4c16695f-17c5-4760-8abe-1527355b9103 succeeded for all five identities on November 5, with failure notifications suppressed.

- No runtime/stack deployment was required; preflight created no email or report documents.

- After Ash approved N/A delivery, internal review run 41ffc0a4-c6c8-4bed-82b5-0dc159655248 generated five native Docs/PDFs with audited commentary, zero identity/technical failures and five disclosed incomplete-data outcomes.

- Received email, all five document permissions, immutable PDF hashes and N/A disclosures verified. Delivery was only to Ash; no quoted history or reply headers.

## Remaining Source Gaps

This PR formalizes identities; it does not claim complete financial data. Missing accounting/model/roster sources and the shared Facilities publication failure remain explicit N/A. Ashwanth approved internal delivery with those disclosures; the five-report review email has been sent and verified. Finance distribution remains unapproved.

## Implementation Effort

Approximately one engineer-day for source reconciliation, guarded SQL and installer implementation, regression coverage, and production validation without AI assistance.

## Linear

Refs https://linear.app/builder-team/issue/SURTR-1697/formalize-five-reviewed-alpha-qtd-school-identities-and-validate

#2253 — fix(ramp): complete cost research and recover linked weekly report (SURTR-1698) @ashwanth1109  approvedmercy-allow-critical

The November 1 Ramp weekly run stopped after researching 18 of 19 opportunities: the remaining security candidate exhausted two deadlines, then returned only two of six merchants. Its missing final cost artifact blocked the linked Superbuilders report. This change completes bounded research without weakening merchant coverage or savings validation, and adds explicit citation checks before accepting or checkpointing new research.

## Business Value

Restores complete weekly cost-analysis inputs and Superbuilders report delivery. Every candidate merchant receives an assessment, including complementary products that should be retained, so a broad consolidation hypothesis does not become an unsupported recommendation. The recovered week-44 report was reviewed through a personal test email and then sent to the user-approved seven-person official distribution.

## Implementation Effort

Estimated 8–10 hours for an average engineer to implement the model boundary, citation/checkpoint validation, safe validation controls, regression coverage, CI repair, and production validation without AI assistance, excluding service wait time.

## Implementation

- Collect direct web-search evidence separately from structured synthesis. Require explicit assessments for all candidate merchants and restrict source selection to retrieved URLs.

- Validate citation URLs across research prose, assessments, and action items, including checkpoint recovery. Ranking cannot introduce citations; invalid checkpointed rankings are recomputed. Existing complete legacy research remains compatible with its original contract.

- Resume server-tool pause_turn with unchanged assistant content and tools, following [Anthropic's documented protocol](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause_turn). Regression coverage includes pending server-tool state, repeated pauses, and the shared deadline.

- Add mode=cost, validation_only=true to bypass the final-artifact cache and validate/recompute through the current contract without writing reports or checkpoints. Reject this flag on writing modes. Operational run records and logs remain enabled.

- Give the QuickBooks CDK entrypoint test's temporary-directory cleanup bounded native retries for transient filesystem errors. Persistent cleanup failures remain visible; no QuickBooks pipeline behavior changes.

## Verification

- Producer: 280 tests passed on Python 3.11. Consumer: 67 tests passed on Python 3.11 and 3.12. Full local CDK suite: 1,022 tests passed. Ruff/formatting were limited to the modified Python files; git diff --check passed.

- Pre-merge deployments used current production baseline 337e7442 plus only the task commits, separately from this main-based PR. Each deployment targeted only Pipeline-ramp-spend-pipeline-prod with --exclusively; CDK reported [1/1], and CloudFormation reached UPDATE_COMPLETE. No other pipeline, shared, or registry stack was deployed. The current task definition is 18, image tag 67b87a76b59344286e89a747cf390d32dab641e21f59e90817606e0366ccf823.

- Recovery execution ramp-cost-recovery-20261105-surtr1698: SUCCEEDED. The preserved November 1 input fingerprint matched; the original 18 results were unchanged; all 19 opportunities were researched and five selected. The missing week-44 cost artifact was published.

- Both deployed consumer groups passed supported dry runs after financial/cost contracts, matching periods, chart PNG contents, and freshness passed preflight.

- Personal test delivery succeeded and the user confirmed the email looked good. Official execution ramp-report-w44-official-send-20261105: SUCCEEDED, SES accepted the email, and the schedule_2 sent receipt records all seven approved recipients. The personal receipt and internal-group delivery state were preserved.

- Follow-up execution ramp-citation-guard-validation-20261105: SUCCEEDED on task definition 18 with validation_only=true, revalidating all 19 saved research results and ranking under the strengthened contract. It reported published=false and no report key. S3 ETags, modification times, and sizes proved the official report, cost checkpoint, and official delivery receipt remained unchanged.

- Every manual execution set run_options.skip_failure_notification=true. EventBridge pattern testing confirmed manual recovery does not trigger the scheduled-only email path. Scheduled notification behavior remains intact.

## Trigger and Delivery Behavior

Unchanged: producer Sunday 19:00 UTC (Monday 00:30 IST); internal schedule_1 after successful scheduled weekly_report; official schedule_2 Monday 07:00 UTC (12:30 IST). Approved recipients and per-group delivery idempotency are preserved. The consumer required no redeployment because its failure was caused by the missing producer artifact.

This PR targets main and contains two task commits, nine files. The candidate remains deployed. No merge has been performed.

## Linear

Closes [SURTR-1698](https://linear.app/builder-team/issue/SURTR-1698/repair-incomplete-ramp-cost-research-and-recover-week-44-superbuilders).

#2251 — fix(netsuite): reobserve fenced historical transaction scopes @ashwanth1109  approved

Historical Education vendor reconciliation exposed missing TransactionLine.id values and incomplete accounting observations. Add an explicit transaction-scoped re-observation command using existing source field contracts, immutable landing, atomic keyed publication and ingestion/job ledgers.

## Business Value

Repairs the source identities needed to reconcile school spend and recover vendors without amount-based joins. The live repair populated 41,901 missing line IDs across a reviewed scope of 46,715 lines and restored 574 missing accounting keys, including 21 Travel lines totaling $27,953.66.

## Implementation

- Dry-run by default; --apply requires an exact reviewed transaction-ID SHA-256 and a bounded batch size.

- Require source parent availability, pre/post counts, valid unique source keys and non-null TransactionLine.id.

- Fence the destination and reject observations newer than the existing global watermark, preventing a partial scope from advancing traversal coverage.

- Reuse the production raw publisher with per-batch source manifests, receipts and post-publication row counts. The command does not infer deletions or invoke downstream pipelines.

- Record manual failure-notification suppression; retain scheduled behavior.

## Validation

- 61 focused and atomic publisher tests pass; Ruff 0.15.22 and git diff --check pass.

- Accounting candidate published 1,201 captured rows; source/warehouse comparison has zero key or amount differences. An independent repeat converged on the same keys and amounts.

- Line-identity publication completed 25/25 batches: 46,715 fetched/candidate/published rows, zero rejected rows, zero missing line IDs, zero duplicate identities and zero identity/payload mismatches. Global traversal watermark is unchanged; all 25 receipts preserve notification suppression.

- Full line publication took 1,081 seconds wall time. Existing netsuite-raw runtime files are identical on main and production; no infrastructure or schedule changes.

- Final validation separately found 2,416 stale legacy accounting keys across 70 shared transactions. After explicit user approval, the bounded cleanup retained a full 5,464-row before-image, removed only the source-absent legacy keys and retained all 3,048 current source keys. This cleanup is an independently recorded operational action, not deletion behavior added to the command.

## Implementation Effort

Approximately 2–3 engineer-days for source investigation, safe scoped capture/publication, guardrail tests and live reconciliation without AI assistance.

## Linear

https://linear.app/builder-team/issue/SURTR-1696/repair-historical-netsuite-line-identities-and-missing-accounting

## Commit Scope

One task commit against main; three changed files.

#3927 — fix(finance): preserve Education vendors on travel and donations @ashwanth1109  approved

Education Actual non-headcount vendor reporting currently replaces source counterparties with Travel or Customer / Bank Charges. Preserve the cleaned header/line source counterparty on Travel and donation lines, and leave missing or placeholder names unresolved. Other entities, headcount, budgets, joins, accounting categories and amounts retain their existing behavior.

## Business Value

Restores counterparties on 2,345 SY25/26 Travel lines ($2,145,825.28 net) and two donation/marketing lines ($2,506,000.00). Makes 131 Travel lines with no usable source counterparty explicitly unresolved so they remain visible for follow-up.

## Validation

- Ran the exact candidate CASE against 23 Redshift regression fixtures: all passed.

- Evaluated old and candidate expressions over live warehouse inputs: 96 changed period/account cohorts, all within Education Actual NHC OPEX/COGS.

- Verified the deployed procedure differs only in the vendor CASE, so row filters, joins and amount expressions are unchanged.

- Ruff 0.15.22 and git diff --check passed.

- Includes a repeatable read-only validation command and rollout instructions. Applied the reviewed candidate definition and refreshed mapped/consolidated data in one atomic production transaction before merge. All 12,267,541 mapped and 13,810,585 consolidated rows retain matching non-vendor checksums, counts, signed totals and absolute totals; existing reader access is preserved. The deployed body matches the reviewed candidate SHA-256. QuickBooks/NetSuite source replacement remains separate.

## Implementation Effort

Approximately 1–2 engineer-days to trace the source mapping, implement the scoped correction, and build/run live regression and scope validation without AI assistance.

## Linear

https://linear.app/builder-team/issue/KLAIR-3690/preserve-education-source-vendors-on-travel-and-donation-actuals

## Commit Scope

Two task commits against main; three changed files.

#2261 — 1433-5aerie-release-prep @mwrshah  approved

Bot output:

- Set AWS_REGION=us-east-1 explicitly on the production analytics worker, matching its AWS deployment region.

- Fix ISP DynamoDB/S3 reads failing with Region is missing: the live container only has AWS_DEFAULT_REGION, which does not satisfy these JavaScript SDK clients.

- One-line configuration change; does not change forecast scheduling or claim to resolve its separate publication delay.

- Validated Compose parsing, analytics-worker region, and git diff --check.

- Takes effect when deployed to production and the analytics container is recreated. No live configuration change or restart performed.

#3925 — feat(ai-budget): add software and education filters @ashwanth1109  approved

## Demo

<img width="2210" height="1636" alt="image" src="https://github.com/user-attachments/assets/7c57e72e-c575-4085-9f92-c88d80d189cf" />

<img width="2204" height="1636" alt="image" src="https://github.com/user-attachments/assets/31074b3c-7fc6-4f01-b18a-b7efaead23dc" />

<img width="2210" height="1636" alt="image" src="https://github.com/user-attachments/assets/320e6d9b-7e8a-423e-a454-53e085fb1051" />

## Summary

Add an All / Software / Education selector to AI Budget Tracking across Budget, Activity, People and API Keys, using the financial reporting / Performance Review Education list.

- Apply segment filtering server-side before ranking and pagination, intersect it with existing BU visibility, and recompute visible budget totals.

- Classify the 40 Finance Education BUs consistently, respect existing rollups and known aliases, and retain shared/unidentified spend under All.

- Keep the segment across tabs, validate BU deep links against the complete authorized scope (including budget groups without spend), clear incompatible BU selections, and hide previous-segment results while replacements load.

- Use the exact BU-attributed Activity trend for selected segments and preserve whole-quarter budget editing.

- Enable Software / Education only after the API advertises segment support; keep All available on older deployments and block unsupported segment deep links.

## Business Value

Finance can compare Software and Education AI spend, budgets and usage directly without manually selecting business units. The same reporting classification drives the page's totals, trends, people and key breakdowns.

## Implementation Effort

Approximately 6–10 engineer-hours for an average engineer implementing and verifying this without AI assistance.

## Validation

- 84 frontend tests passed across the Budget Tracking components, explorer hooks and real API parameter serialization tests.

- 533 scoped backend tests passed across segment classification, BU access, routers, budget tracking and AI-cost services. Database calls are mocked; integration, eval and network-marked tests are excluded by the default pytest selection.

- Ruff 0.15.22 formatting/checks, Pyright, changed-file ESLint and Prettier, TypeScript (pnpm tsc -p tsconfig.app.json --noEmit), and pnpm build passed.

- The updated BU inventory query ran successfully against live Redshift in a read-only session and returned 144 distinct BU spellings.

- Mutation checks confirmed the new tests fail when segment selection or the Education classification is broken.

- Review follow-up: 56 focused frontend tests and 19 backend router tests passed, including old-API and pending-capability cases on all four tabs and real Activity-hook error / retry coverage. Mutation checks fail when either capability gating or trend-error rendering is removed. TypeScript, production build, ESLint, Prettier, Ruff 0.15.22 and Pyright completed; Pyright retains one pre-existing ProviderBreakdown default-factory warning.

- Deep-link follow-up: 65 focused frontend tests and 46 backend segment/router tests passed. Covers incompatible links on all four tabs, compatible zero-spend budget groups, normalized BU names, All links, and stale segment responses. Removing BU validation fails all five incompatible-link regressions. TypeScript, production build, changed-file ESLint/Prettier and Ruff 0.15.22 passed; Pyright has 0 errors and the same pre-existing warning.

## Linear

Fixes [KLAIR-3688](https://linear.app/builder-team/issue/KLAIR-3688/add-software-and-education-filter-to-ai-budget-tracking).

#50 — State 120 sensitive reads per minute in the published contract (AI-1056) @kevalshahtrilogy  no labels

## What

- src/aerie/openapi.ts: the security description in openapi.json said 30 sensitive reads per minute. The limit is 120 (AI-1050), and the dictionary and enablement already say 120.

- New test: the contract, dictionary and enablement must state the same per-person budgets, so they can't drift apart again.

## Business Value

Devin's agent builds against openapi.json. Before this fix, the contract told it to throttle to a quarter of the real budget, while the documents said otherwise. Now there is one number everywhere.

## Manual Effort Estimate

~20 min. Proposed; Keval to confirm.

## Verification

pnpm check passes (71 tests).

Linear: AI-1056

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

#49 — Publish site document upload for write keys (AI-1055) @kevalshahtrilogy  no labels

Stacked on #48 (rule change). Merge #48 first.

## What

- Allowlist: publishes POST /portfolio/sites/{siteRef}/documents, the source's upload-and-register operation. pnpm sync:openapi adds only that path. Most of the snapshot diff is git aligning around the inserted block; the semantic change is one new operation.

- Relay (src/aerie/proxy.ts):

- Writes whose contract is multipart/form-data accept multipart only (a boundary is required). The body and the caller's Content-Type are forwarded byte for byte.

- Every other write still requires a JSON object.

- The body is bounded at 16 MiB: the source's 15 MiB file plus form fields. Anything larger gets a 413 upload_too_large, and the source is never called.

- The upload is read only after a write slot is taken, so at most four files are held at once.

- As with every write, it needs a write key, runs as the key's owner and uses the scoped Idempotency-Key. Logs stay metadata only: no file contents or filenames.

- Docs:

- Enablement explains how to upload: the fields, the 15 MiB limit and the 413.

- The dictionary count goes to 20 writes, and "uploads" comes out of its "not published" list.

- Still unpublished: deletes, and global-document upload and registration.

## Business Value

Teams can register site documents (renderings, Matterport walkthroughs, permits and so on) through Rhodes instead of keeping an Aerie key just for documents. That removes the last blocker Brandon raised for moving fully to Rhodes, and it lets agents close "missing document" gaps they find themselves.

## Manual Effort Estimate

~5 h: reading the source contract, the multipart relay path with bounds, tests, and docs. Proposed; Keval to confirm.

## Verification

- pnpm check: 70 tests pass. New tests cover:

- a byte-for-byte upload as the key owner;

- JSON refused on the upload, and multipart refused on a JSON write;

- an oversize body refused with 413, without calling the source.

- pnpm build and pnpm synth --no-lookups pass.

- Not verified against the live source; that needs a keyed upload after deploy.

Linear: AI-1055

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

#48 — Allow document registration and uploads in the contributor rules; deletes stay banned (AI-1054) @kevalshahtrilogy  no labels

## What

- AGENTS.md: drop uploads from the "never publish" rule. Registration and uploads are writes like any other: published through the source's own register and upload operations, with the file bytes relayed unchanged within the source's size bound and never logging file contents or filenames. Deletes stay banned.

- src/aerie/routes.ts: header comment matches the rule.

No operation is published here; registration itself is a follow-up PR. The data-source-skills contract (https://data-source-skills.vercel.app/contract) has no rule against writes or uploads, so the ban was ours alone.

## Business Value

Unblocks moving document registration off Aerie keys. Brandon's team today writes everything through Rhodes except documents, so they must keep an Aerie key just for that; this is the first step to retiring it.

## Manual Effort Estimate

~30 min (reading the estate contract and locating where the ban lives). Proposed; Keval to confirm.

## Verification

pnpm check passes (67 tests). The existing test that no DELETE is published still holds.

Linear: AI-1054

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

#2249 — Harden Finalsite contacts view projection and rollout @sanketghia  approved

## Summary

- Project Finalsite's per-school-year start_if_different_date track attribute into staging_education_finalsite.contacts as a nullable DATE, retaining the raw string and preserving observation grain.

- Use a grouped track-attribute projection so ordinary Redshift queries and aggregates can read the new columns without row multiplication.

- Allow the DDL applier to replace only the selected stale clean view, while verifying the complete clean-view catalog.

- Preserve supported grants, ignore Redshift's nonfunctional RULE/TRIGGER catalog entries, and compact equivalent grants to fit the atomic batch limit.

- Add regression tests for projection semantics, DQ flags, grant handling, and targeted view replacement.

## Validation

- Finalsite raw sync suite: 170 passed

- Ruff 0.15.22 check and format check passed

- Generated DDL check passed

- Read-only Redshift execution confirmed 104 populated values match the nested Finalsite attribute, with zero invalid or DQ-flagged values

## Production rollout

- The targeted DDL apply completed successfully; the contacts view exposes the raw string and DATE columns.

- The delta schedule was restored to enabled after the rollout.

- No backfill or full source sync was required; the existing raw history contained the values.

#2258 — AI-1047: Fill student and family postal-address gaps @kevalshahtrilogy  approved

## Summary

Andy pulled a campus roster from Aerie and several students had missing or wrong family addresses, even though the SIS and HubSpot both hold correct ones. Arthur's agent traced three causes. This PR fixes all three on current main:

1. Established Funnel public API leaves out addresses (chat/convex/publicApi/v2/domains/admissions.ts, chat/convex/admissions/dashboards/fullFunnel.ts, chat/lib/public-api/v2/domains/admissions.ts)

- listAdmissionsEstablishedFunnelEnrollments now returns childStreet/City/State/Zip/Country and parentStreet/City/State/Zip/Country. These are the same fields the signed-in detail cards render through projectEnrollmentDetail.

- The browse table (communityFunnelEnrollmentList) doesn't carry addresses. So getFullFunnelEnrollmentsForApi joins each page row to its detail record with the by_refreshRunId_dealId point index. A page holds at most 100 rows. The UI list query and the Community Funnel operation are unchanged.

- The contract gets a new ESTABLISHED_FUNNEL_ENROLLMENT_ITEM_SCHEMA (the shared item schema plus 10 nullable strings), used only by this operation.

2. The legacy contact lookup has no HubSpot fallback (sync/src/analytics/queries/entities.ts, refresh.ts)

- New queryHubspotContactAddresses() reads the child and parent postal fields from the enrollment-deal mart that the funnels already use.

- New mergeHubspotAddressFallback() runs after SIS enrichment. It fills address, city, state and zip only when every one of those is blank, and it treats the address as a unit. A present SIS value is never overwritten or mixed with HubSpot values.

- If the query fails, the refresh logs a warning and continues, like the other enrichments.

3. A search_students miss implies the student doesn't exist (chat/convex/agent/queries.ts)

- The empty result now says the tool searched Aerie's legacy enrollment snapshot, which can be stale. It says a miss doesn't mean the student is absent from the SIS, and points to the SIS or lookup_contacts + get_student_detail. This is a message-only change; making the tool search the SIS would need a redesign.

## Verification

All test fixtures are synthetic placeholder addresses.

- cd sync && npx vitest run src/analytics/queries/entities.test.ts src/analytics/refresh.test.ts: 119 passed. New fallback tests cover: fills when blank, never overwrites or mixes a SIS value, whitespace counts as blank, first non-blank HubSpot row wins, no match leaves the contact unchanged. There is also a query-mapping test.

- cd chat && npx vitest run lib/public-api convex/publicApi convex/agentQueries.test.ts convex/admissions app/api/skill: 87 files, 1631 passed. This includes the extended Established Funnel HTTP test (addresses present, nulls when absent, Community Funnel unchanged), the new search_students miss test, the contract/OpenAPI tests and skill-package.node.test.ts.

- npx tsc --noEmit -p . passes in chat and sync. Biome, lint:read-bounds and the pre-commit hooks all pass.

- I ran pnpm -s skill:version. The skill version didn't change, because the skill files themselves didn't change.

- Not checked in production. I haven't run this against live data or checked the Raleigh roster after a refresh.

## Business Value

The CFO and agents can now get correct family addresses from Aerie, and Aerie feeds Rhodes. Before this, a roster pull silently dropped addresses that the SIS and HubSpot both had. Agents could also tell users a student "doesn't exist" when the legacy snapshot was only stale.

## Manual Effort Estimate

About 6–8 hours of focused work by hand: tracing three code paths across sync and chat, the contract change, and the tests. Keval: please confirm or adjust.

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

#47 — Re-sync the source contract; recipe uses rendering and Matterport types; 120/min budget (AI-1048) @kevalshahtrilogy  no labels

AI-1048. Aerie hotfix #2259 (with #2213, #2253 and #2257) is live in production as of 5 Nov. This PR re-syncs Rhodes against it.

## Changes

- Snapshot re-sync (pnpm sync:openapi, committed key order kept). The source now publishes:

- the rendering and matterportWalkthrough document types;

- documentRef on requirement satisfactionEvidence;

- per-operation rate-limit response headers.

Still 45 reads and 19 writes.

- Enablement cohort recipe:

- list rendering and matterportWalkthrough first, with versions=all;

- keep other, lidar, floorPlan and marketingPack as the fallback for older registrations;

- link requirements to documents by documentRef, not by title;

- re-cost the run at about 136 sensitive reads for 17 sites, a little over a minute.

- Budgets: sensitive is 120 a minute per person in Enablement §11 and Dictionary §1, and §11 describes the eight-slot read queue.

## Verification

- pnpm check passes with 67 tests; pnpm build and pnpm synth --no-lookups pass.

- Contract shape confirmed on the live source: matterportWalkthrough is present.

- I couldn't confirm the per-person 120 limit live: that needs a keyed read, and I have no key here.

## Business Value

Agents answering "which walkthroughs and renderings exist for these sites" can find them by type, without matching titles. They can tie each requirement to its file, and finish a 17-site check in about a minute, in time for Dean's Friday re-check.

## Manual Effort Estimate

About 1.5 hours by hand. Keval: please confirm or adjust.

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

#3924 — fix(acq-perf-review-v2): sum available comparison totals @sanketghia  approved

## Summary

- Sum available quarterly values for line-item totals, even when other quarter cells are unavailable.

- Compute total margins from matched available profit/revenue pairs; compute total margin variance from the same common quarter set.

- Keep totals unavailable only when no applicable values exist.

## Validation

- pnpm lint:pr passed.

- Prettier and the application TypeScript check passed.

- git diff --check passed.

## Screenshot

<img width="1482" height="727" alt="image" src="https://github.com/user-attachments/assets/a3eb4cee-3df0-4327-916b-bd88284876e3" />

#3923 — feat(acq-perf-review-v2): add budget base plan comparison @sanketghia  approved

## Summary

- Add an Acquisition Plan vs Budget Base Plan tab after Forecast for CloudSense.

- Build Budget Base Plan from V2 actuals for globally closed quarters and the selected V2 budget for open quarters, through the selected budget's final quarter. Do not use deprecated GSheet data or forecast beyond budget.

- Show grouped Acquisition Plan, Budget Base Plan, and Variance blocks, each with quarterly columns and a Total column. Margin totals use aggregate profit divided by aggregate revenue; variance is Budget Base Plan minus Acquisition Plan.

- Keep closed quarters with no acquisition actual unavailable rather than falling back to budget.

## Validation

- uv run ruff format and uv run ruff check passed.

- uv run pyright passed with 0 errors, warnings, or information messages.

- pnpm lint:pr passed.

- Prettier and pnpm tsc -p tsconfig.app.json --noEmit passed.

- git diff --check passed.

## Screenshots

<img width="1466" height="693" alt="image" src="https://github.com/user-attachments/assets/bcd12dbc-782d-43af-b73e-d6714b931ceb" />

<img width="1465" height="734" alt="image" src="https://github.com/user-attachments/assets/0e5c74df-7a43-415b-950f-8dce8b4063dd" />

<img width="1693" height="764" alt="image" src="https://github.com/user-attachments/assets/1af3fe4b-3aa3-4233-ac32-dc618d5c2d23" />

#46 — Queue reads for a slot instead of refusing at once; eight in flight (AI-1051) @kevalshahtrilogy  no labels

AI-1051. The relay allowed 4 reads in flight and refused the 5th immediately with 503 service_busy. That produced Artemis's hundreds of 503s, about 278 over one weekend, and we promised a fix by 11/10.

## Change

- Read slots go from 4 to 8.

- A read beyond that waits up to 10 seconds for a free slot, handed over in arrival order. If no slot frees up, it gets 503 service_busy with Retry-After: 1, as before.

- If the caller disconnects while waiting, the request leaves the queue.

- Writes are unchanged: 4 in flight.

- The Enablement budget step and the OpenAPI 503 description now describe the new behaviour.

## Verification

- pnpm check passes with 67 tests. The concurrency test now covers: 8 in flight, a 9th that waits and then succeeds, a refusal after the wait expires, and slots freed on failure.

- pnpm build and pnpm synth --no-lookups pass.

- Not yet checked in production.

## Business Value

Sequential readers such as Artemis's hourly sweep, the quality loops and cohort checks stop failing on short bursts of contention. Callers no longer need retry plumbing for the relay's own busy signal.

## Manual Effort Estimate

About 2 hours by hand. Keval: please confirm or adjust.

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

#2257 — AI-1050: Raise the sensitive read tier to 120 per minute; fixed bound for guards @kevalshahtrilogy  approved

AI-1050. Rhodes callers (Robbie, Arthur and Artemis's loop) keep hitting the 30-a-minute sensitive tier. That tier covers document lists, search, requirements and notes. A 17-site diligence cohort check needs about 100 sensitive reads.

## Change

- PUBLIC_API_V2_RATE_LIMITS.sensitive goes from 30 to 120.

- Each person on a Rhodes personal (delegated) key gets 120 a minute.

- Direct keys and the shared legacy service budget also get 120.

- Operator overrides now range from 120 to 1200.

- New PUBLIC_API_V2_GUARD_RATE_LIMIT = 30 for the abuse and audit bounds: denied attempts, unmatched routes and rate-limit audit rows. These previously borrowed the sensitive number, so they stay at 30 rather than growing with read capacity.

- The SKILL.md limits and skill version (regenerated), and the rhodes-caller-quotas design doc, are updated to match.

## Verification

- The convex/publicApi and lib/public-api suites pass: 64 files, 900 tests.

- tsc is clean.

- Not yet checked in production.

## Business Value

Rhodes users can run a full diligence-cohort asset check in under a minute instead of being blocked by 429s. That directly unblocks Robbie's retest, Arthur's Matterport/rendering question and Artemis's overnight data-quality loop.

## Manual Effort Estimate

About 2 hours by hand. Keval: please confirm or adjust.

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

#2247 — Expose Finalsite start-if-different date @sanketghia  approved

## Summary

- Expose Finalsite's start_if_different_date track attribute as a nullable DATE in staging_education_finalsite.contacts, retaining its raw value alongside it.

- Preserve the existing historical observation grain; invalid dates and duplicate attribute matches are reported in _dq_invalid_fields.

- Regenerate the canonical DDL and add regression coverage for projection and view documentation.

## Validation

- Finalsite raw sync suite: 166 passed

- Finance refresh SQL/QTD guide contracts: 53 passed

- School performance SQL contracts: 10 passed

- Student school-year snapshot contracts: 35 passed

- Ruff check and format check passed

- Generated DDL check passed

- Read-only Redshift EXPLAIN accepted the generated contacts projection

## Production rollout

- Deploy the updated Finalsite ECS runtime and apply the generated Redshift DDL together so the runtime catalog contract matches the view.

- No source backfill or full sync is required; existing raw contact observations already contain the track attribute.

- Production DDL was not applied as part of this change.

#2245 — 095-hubspot-heavy-archived-programs @mwrshah  approved

Bot output:

- Fix the production Programs heavy-shard route missed by #2241. Fresh run 9da49d15-f73f-4a04-a8c0-14581955217a discovered 124 Programs, collected 119 active rows, then failed because the archived shard still used batch-read.

- Keep active batches and the complete paginated archived listing in one Programs collection, using the existing listing primitive. Preserve transition deduplication, exact same-run membership, immutable evidence, and replay.

- Close pinned Programs membership against the archived listing in production's resource-mode lineage proof as well as the other proof path. Keep completeness guards intact; add no source-unavailable exceptions.

- Cover the real heavy worker, pagination, empty archives, membership above 5,000 IDs, overlap/revalidation, replay, and publication-proof rejection cases.

Validation: 312 HubSpot tests; repository-wide Ruff 0.15.22 lint and format checks; independent review passed.

No deployment or pipeline run. Deploy between runs and use a fresh execution after deployment; the pinned Programs membership layout changes.

#3922 — fix(acq-perf-review-v2): align Prices Paid with legacy @sanketghia  approved

## Summary

- Align the V2 Prices Paid metric order with the legacy sequence, while omitting the legacy-only DM (%) and V2-only forecast-retention rows.

- Remove the duplicate budget/quarter caption and redundant method note, and keep selected-budget ending ARR out of the table because it is not the legacy Last Budget Cycle ARR measure.

- Align Expected 5Yr DPI with the legacy formula by including after-tax earnings to date, the next four quarters, and the following five years. With current Cloudsense V2 inputs, this returns 2.05x.

## Validation

- Backend Ruff and Pyright passed.

- Frontend lint, ESLint, Prettier, TypeScript, and production build passed. The build reports existing Browserslist and bundle-size warnings.

## Screenshot

<img width="1674" height="775" alt="image" src="https://github.com/user-attachments/assets/8434c033-abc9-4f8b-8f83-97d78790376d" />

#2256 — 1432-openapi-task-explanation @mwrshah  approved

- Refresh the committed Sindri OpenAPI snapshot from Sindri 8e8189ef and regenerate Aerie types for file operations and conditional schema requirements.

- Update accepted contract hashes and clarify the canonical source, committed artifacts, and refresh workflow.

- Preserve contract revision 2026-09-20; verify /v1/models and generated output reproducibility.

- Validation: 198 focused tests, app and Convex typechecks, and repository lint passed (three existing unrelated warnings). Sindri OpenAPI generation passed 16 tests without artifact changes.

Related: https://linear.app/builder-team/issue/SINDRI-490/update-aerie-readme-to-document-the-vendored-sindri-openapi-spec

#2243 — feat(raptor): refresh the original personnel roster daily @caina-barbosa  approved

## Summary

Include personnel_roster in the existing daily Raptor refresh at 09:00 UTC (04:00 fixed EST). The original Google roster is collected by the separately deployed Raptor host using sheets-reader; DSS serves the saved snapshot. Production effect: activation after compatible host/reader deployment.

## Why

The user explicitly requested a daily saved copy of the original Personnel roster. The existing schedule excludes Personnel, so changing only its source would leave the saved roster stale.

## Business Value

- Uses the maintained original roster.

- Keeps roster access read-only and credentials private.

- Keeps DSS queries on validated saved snapshots.

## How does it work

1. Accept personnel_roster in the existing controller selection.

2. Add it to the existing daily fresh invocation and 86400-second cadence map.

3. Retain the existing lease, SSM, cleanup, notification and result-validation paths.

## Scope

### Included in this phase

pipelines/runners/raptor-refresh/OPERATIONS.md

pipelines/runners/raptor-refresh/README.md

pipelines/runners/raptor-refresh/pipeline.json

pipelines/runners/raptor-refresh/src/controller.py

pipelines/runners/raptor-refresh/tests/test_controller.py

### Deliberately excluded for later phases

Live per-query Google access is outside the selected daily-snapshot behavior.

## Test plan

### Automated validation

- python3 -m unittest discover -s pipelines/runners/raptor-refresh/tests -q: 8 tests passed.

- Ruff format/check passed; the shortened selection error uses the required single-line formatting.

- Independent exact six-dataset selection/cadence checks and git diff --check passed.

- Companion Raptor actual EC2 fresh Personnel publication and authenticated local DSS all 117-row readback passed before this PR; other five model bytes and retained history unchanged.

- Production release is held until the compatible reader/host and sheets-reader credential are active.

### Time for Implementation

Approximately 2–3 engineer days including validation and release.

#12 — feat(personnel): refresh the original Google roster with sheets-reader @caina-barbosa  no labels

## Summary

Read the original Personnel roster using sheets-reader and publish it through the existing refresh/recovery pipeline. DSS continues serving saved snapshots. Production effect: controlled rollout; host credential/config activation and the Surtr daily selection follow the reviewed reader release.

## Why

The accepted roster came from a copied sheet. The user requested the original source and explicitly chose a daily saved copy. Legacy snapshots retain their truthful copy provenance.

## Business Value

- Uses the maintained original roster.

- Keeps roster access read-only and credentials private.

- Keeps DSS queries on validated saved snapshots.

## How does it work

1. Read the fixed original sheet/tab with read-only Sheets OAuth and private service-account credentials.

2. Validate the nine-column roster against the accepted tenant inventory using its own acquisition identity and clock.

3. Use existing immutable recovery, lease, CAS publication and status paths; preserve unselected datasets and history.

4. Deploy the compatible reader before enabling the host and daily Personnel selection.

## Scope

### Included in this phase

README.md

docs/current-state-refresh.md

docs/targeted-refresh.md

policies/recovery-cleanup.json

refresh/datasets.mjs

refresh/entry.mjs

refresh/host-bridge.py

refresh/native-personnel.mjs

refresh/permissions.mjs

refresh/personnel-collector.mjs

refresh/personnel-google-reader.mjs

refresh/personnel.test.mjs

refresh/recovery-cleanup.mjs

refresh/refresh.test.mjs

refresh/storage.mjs

snapshot/components.test.mjs

snapshot/refresh-status.mjs

snapshot/vendor/cohort/source/d6/model.mjs

snapshot/vendor/cohort/source/d6/personnel.mjs

src/source/documents/enablement.md

### Deliberately excluded for later phases

Live per-query Google access is outside the selected daily-snapshot behavior.

## Test plan

### Automated validation

- pnpm check: 84 Node and 2 Python tests passed, zero skips, verified collector baseline.

- pnpm audit --audit-level high, build, synth and git diff --check passed.

- Actual EC2 source collection, normal controller/private S3 publication and authenticated local DSS: all 117 Personnel rows matched over two pages; other five model bytes and retained history unchanged; validation token revoked with 401.

- Independent code/security review accepted the original/legacy provenance and read-only credential boundary.

### Time for Implementation

Approximately 2–3 engineer days including validation and release.

#2241 — 094-hubspot-archived-programs @mwrshah  approved

Bot output:

- Read archived Alpha Programs from the paginated HubSpot collection endpoint with all catalog properties and history, using the supported 50-record page limit.

- Retain immutable response evidence and enforce archive state, identity, discovery membership, pagination, and replay validation. Preserve active batch reads and lifecycle-transition deduplication.

- Recover five archived test Programs that listing reads return but individual and batch lookups cannot retrieve, without weakening downstream completeness checks.

- Add regression coverage and update the source manifest and operator documentation. Warehouse status-column changes are separate; this PR does not deploy or run the collector.

#2255 — fix(tasks): stop individual notification emails (AERIE-3069) @caina-barbosa  approved

## Summary

Stops individual Task notification emails for everyone, including queued emails that have not been claimed for sending. In-app Task notifications remain available.

Tracked by [AERIE-3069: Stop individual Task notification emails for everyone](https://linear.app/builder-team/issue/AERIE-3069/stop-individual-task-notification-emails-for-everyone).

Production effect: cleanup or removal. The behavior changes when deployed. No environment-variable change or migration is needed.

## Why

Users report frequent Task emails that duplicate chases from Artemis and Rosa. JC confirmed these individual emails are not needed. Users currently have no setting to turn them off.

## Business Value

- stops assignment, approval, changes-requested, due-date and rejection emails for all users

- keeps the same events visible inside Aerie

- preserves unrelated emails and the separately controlled daily digest

## How does it work

1. Event fanout no longer queues email for the seven individual task.* notification types. In-app fanout is unchanged.

2. Before a queued email can be claimed for sending, claimDueDelivery checks its channel and type. Individual Task emails become terminal skipped records with retries disabled.

3. This also handles queued retries and expired delivery claims through the existing dispatcher. There is no table scan, migration, new setting or new worker.

4. The daily digest uses email.taskScenario, so it is not affected. Its existing production setting is not changed by this PR.

## Scope

### Included in this phase

- individual Task email suppression, queued-delivery handling, focused regression tests and matching Task feature documentation

- exact final diff paths:

chat/convex/notifications/events.ts

chat/convex/notifications/dispatchState.ts

chat/convex/notifications/notifications.test.ts

chat/convex/taskBoard/assignments.test.ts

chat/convex/taskBoard/notifications.test.ts

docs/task-board/FEATURE.md

### Deliberately excluded for later phases

- daily digest enablement or disablement

- notification preferences, UI, API, permissions and unrelated notification behavior

- production data changes, deployment and merge

## Test plan

### Automated validation

- Regression checks first failed against unchanged code: new Task events queued email and queued Task emails reached the mocked sender.

- Focused notification, dispatcher and digest suites: 58/58 passed across five files. pnpm --dir chat exec vitest run convex/taskBoard/notifications.test.ts convex/notifications/notifications.test.ts convex/notifications/dispatchState.test.ts convex/notifications/events.test.ts convex/taskBoard/digest.test.ts --maxWorkers=1.

- After adding ready, retry and expired-lease queue fixtures: the two affected suites passed again, 37/37.

- The transport test proves all seven individual email types are skipped, while the digest and an unrelated email reach the mocked provider.

- In-app tests cover all seven Task event types and immutable rejection/due-date facts after Task deletion.

- CI identified two existing assignment assertions that expected emails. They now require no email while retaining the in-app content checks. The full assignment suite passed locally, 12/12: pnpm --dir chat exec vitest run convex/taskBoard/assignments.test.ts --maxWorkers=1.

- Architecture boundaries, Convex paths, read bounds and test-runtime architecture: passed.

- App typecheck, final formatting and normal commit hooks: passed.

- Fresh independent read-only review: PASS, with 37/37 affected tests independently rerun.

- All hosted CI checks are green on final head 7cd920666e6222bb434c3f84cfed4d8aabc73ad7, including all three Chat test shards, other workspace tests, all type checks, builds, lint/boundaries and secret scanning.

- The PR remains Draft. The successful Mercy workflow check is not being claimed as a Mercy approval.

### Time for Implementation

Approximately half a working day without AI assistance for the narrow change, regression tests and review.

#3 — Run the Rhodes loops daily on AWS Fargate (AI-1013) @kevalshahtrilogy  no labels

## Summary

Stacked on #2. Moves Arthur's daily Rhodes reviews off a laptop and onto a scheduled Fargate task.

infra/ (CDK, pins copied from Rhodes-DSS: aws-cdk 2.1146.0, aws-cdk-lib 2.274.0)

- A private S3 bucket: versioned, SSE, public access blocked, retained on stack delete. It holds state/ (scan and review state) and runs/<run>/ (drafts, summary, agent transcript, kept 180 days).

- The secret rhodes-quality-loops/rhodes-dss-api-key. Keval stores his own key in it after the first deploy. The Anthropic key comes from the existing SURTR_PROD_KEYS secret.

- An ARM64 Fargate task (1 vCPU, 2 GB) built from the Dockerfile: Python 3.12.12, Node 22.20.0, Claude Code CLI 2.1.286, boto3 1.43.106, non-root user, auto-update disabled. It has no inbound access and reuses the Rhodes DSS public subnets for outbound traffic.

- An EventBridge Scheduler entry at 07:05 America/New_York daily, with no retries (a missed day is better than an overlap).

- An SNS email alert if the task stops non-zero, meaning it died before it could report.

run_daily.py (the container entrypoint)

1. Takes an S3 lease using a conditional write; a stale lease (over 4h) is taken over only if its ETag is unchanged.

2. Restores state, initializes it if empty, and runs the public and integrity scans.

3. Runs claude -p prompts/daily.md with an allow-list:

- read the repo;

- write and edit only under .rhodes-monitor/;

- run rhodes_monitor.py get|dispose;

- WebFetch only the Rhodes origin.

The Rhodes key is removed from the agent's environment. The runner reads it from a .env that .claude/settings.json denies to the Read tool, and which is deleted after the run.

4. Saves state and run output to S3, drops ephemeral counters and releases the lease.

5. Emails Keval through SES only if summary.json says notify or something failed. The email carries the headline, decisions, coverage gaps and drafts. Nothing goes to owners.

Stdout, and so CloudWatch, carries run metadata only, never record content.

## Business Value

Arthur's four Rhodes quality loops have been catching real Education Ops issues (opening-date conflicts, security record mismatches, freshness gaps), but they run only when his Mac is on. This makes them a daily, unattended service with persistent state, so findings stay open until they are verifiably closed and Keval gets drafts only when something changes. Cost is one small Fargate task a day plus one agent session.

## Manual Effort Estimate

Proposed ~8 hours by hand: the CDK stack, container, wrapper with lease and alerts, and tests. Keval to confirm or adjust.

## Test plan

- [x] 116 unit tests pass (5 new for the wrapper: the lease blocks a second run; a stale lease is taken over only if unchanged; the agent's environment has no Rhodes key and .env is removed; the tool allow-list has no general shell and no writes outside state; failures and notify trigger email).

- [x] tsc --noEmit and cdk synth clean.

- [x] The image builds for linux/arm64; inside it, Claude Code 2.1.286, Python 3.12.12, boto3 1.43.106 and the tests pass, running as uid 10001.

- [ ] Deploy, store the Rhodes key, run the task once, and review the first drafts email.

- [ ] Confirm the SES sender (rhodes-loops@klair.ai, verified domain identity) lands in the inbox, not spam.

Linear: [AI-1013](https://linear.app/builder-team/issue/AI-1013/run-arthurs-rhodes-quality-loops-on-aws-scheduled-tuned)

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

#2 — Retune Rhodes review skills and prompts for headless Claude Code (AI-1015) @kevalshahtrilogy  no labels

## Summary

Stacked on #1. Restructures Arthur's instruction layer so a headless claude -p run on a server finds it, stays read-only and leaves its output where Keval can read it.

- 4 lenses → 3 skills in .claude/skills/, where Claude Code discovers skills; .agents/ is not read by it.

- rhodes-public-exposure.

- rhodes-operations-review: data quality and execution merged. They already shared one scan and one dispatch, and each spent a paragraph pointing at the other. The merged skill keeps "is the record right" and "is the work going right" as separate questions with separate owners.

- rhodes-brainlift-alignment: kept, but it records "not run" without document access instead of reviewing from memory or the placeholder /brainlift page.

- The access adapter becomes CLAUDE.md.

- Authenticated reads go only through rhodes_monitor.py get, and closures only through dispose (both from #1).

- It states the hard limits: read-only, drafts-only, no credentials, no upstream name.

- The contract roughly halves.

- Rules that were repeated across README, AGENTS, RUN-PROMPTS, the contract and all 4 skills now live once.

- The send/acknowledge delivery lifecycle is removed, since sending is never authorized.

- Owner routing lives only in the queue template's owner_routing_policy.

- The method itself is unchanged: evidence and coverage rules, P0–P3, the four ownership roles, the three-group draft format and closure on evidence.

- Headless prompts. prompts/daily.md runs both daily lanes in one session, after the wrapper has run the scans. It writes drafts.md and a summary.json with a notify flag; the infra PR emails Keval only when that flag is set. All "drafts here/local", "notify here" and "keep this schedule" wording is gone.

- Arthur's links to specific Read AI transcripts become general patterns. The server has no transcript access, and the links were his own meetings.

- His original README, run prompts, manifest and provenance are kept under docs/handoff/.

## Business Value

Arthur's loops were written for his interactive Mac setup. On a server they would have found no skills, dropped their drafts into stdout, and needed the API key in shell commands. This makes the same review method run unattended and safely, with one place to change each rule, so the reviews can keep finding Rhodes data and execution problems for Education Ops without anyone's laptop.

## Manual Effort Estimate

Proposed ~4 hours by hand: reading and restructuring about 700 lines of instructions without losing method. Keval to confirm or adjust.

## Test plan

- [x] 111 unit tests still pass (no code changes in this PR).

- [x] Every relative markdown link resolves; the upstream platform name appears nowhere outside docs/handoff/.

- [ ] First live headless run once the infra PR deploys.

Linear: [AI-1015](https://linear.app/builder-team/issue/AI-1015/rhodes-loops-retune-review-skills-and-prompts-for-headless-claude-code), part of [AI-1013](https://linear.app/builder-team/issue/AI-1013/run-arthurs-rhodes-quality-loops-on-aws-scheduled-tuned)

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

#1 — Harden the Rhodes baseline runner for headless runs (AI-1014) @kevalshahtrilogy  no labels

## Summary

First tuning PR on Arthur's Rhodes loop kit (main = his kit, unmodified). It makes rhodes_monitor.py safe to drive from an unattended agent on AWS.

- get command: an authenticated GET of one published route. The path is checked against the live published contract (GET templates only), and traversal, encoded dots/slashes and query-in-path are refused. The key stays in the process; a response that echoes it is withheld. Each run has a read budget (300). This lets the scheduled agent read Rhodes without ever handling the key or having curl or general shell access.

- dispose command: records a reviewed disposition matched to the finding's evidence signature, under the mode lock. Before this, the agent had to hand-write state JSON. A changed signature still reopens the finding.

- Public scan:

- Every published GET is now probed, using placeholder refs. Callers are rejected before any lookup, so a placeholder tests the gate as well as a real ref would; before this, 9 routes were always unresolved and coverage could never be complete.

- Adds probes for the unpublished /operator/feedback route and the /api/v1 alias.

- The invalid-key probes run on 3 representative routes instead of all 45, and add a legacy-prefix variant so the key-registry path is exercised too.

- /feedback is now shape-checked with state=all instead of hashed. Hashing it raised a review finding on every new submission.

- The credential pattern is widened.

- Integrity scan:

- One unreadable site is recorded as a coverage gap for that site instead of aborting the whole run.

- The known freshness limitation (assessments carry no review time) is recorded as coverage instead of a never-closing finding on every assessed site. It will stop firing once DSS publishes review dates.

- A missing key now gives a clear error, and a skipped overlapping run exits 3 instead of 0.

## Business Value

Arthur's four daily Rhodes quality reviews currently only run on his Mac. This is the first step to running them unattended on a server. It hardens the runner so the scheduled agent can read Rhodes without holding the API key, can't mutate anything, and stops producing noise (feedback-hash churn, a daily freshness finding on every site). Without these fixes, a headless run would either leak the key into logs or bury real findings under repeat alerts.

## Manual Effort Estimate

Proposed ~6 hours of focused work by hand (reading the 3.8k-line kit, the probe and coverage changes, two new commands, 11 new tests). Keval to confirm or adjust.

## Test plan

- [x] python -m unittest discover on Python 3.12: 111 tests pass (100 existing, 6 updated for the intentional probe and exit-code changes, 11 new).

- [x] py_compile on all modules.

- [ ] Live smoke run against Rhodes with a fresh key (in the infra PR, once the key is in Secrets Manager).

Linear: [AI-1014](https://linear.app/builder-team/issue/AI-1014/rhodes-loops-harden-the-baseline-runner-for-headless-runs), part of [AI-1013](https://linear.app/builder-team/issue/AI-1013/run-arthurs-rhodes-quality-loops-on-aws-scheduled-tuned)

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

#45 — Fix Neeraj's documentation feedback: host, milestone9, traps, backup capacity, BrainLift hash (AI-1025) @kevalshahtrilogy  no labels

AI-1025. This PR covers the 7 documentation fixes among the 17 open feedback items Neeraj's DSS agent filed on 10/28–29. The other 10 are record fixes or new source fields, which I've routed separately. Rhodes can't fix those.

## Changes

- Host (dictionary §1): the base and links now use https://rhodes-dss.builder-team.ai, the host the front serves, instead of rhodes-dss.com.

- opening.source (dictionary §4): this is always the legacy constant "milestone9". Opening dates come from Milestone 10 (postOpen), the same step that operation.source calls primaryMilestone10. This is confirmed against the source contract. Before, the wording read as if rows followed an old rule.

- Three new traps (dictionary §5):

- two active records for different schools can share a street address, so identify a school by site.id;

- a school running from a backup reads its primary building's capacity, which is 0 until Phase 1 is ready, and no route records backup capacity;

- diligence status: complete doesn't guarantee any of the four scores, and a future dateCompleted is inconsistent evidence.

- Capacity recipe (enablement): the recipe now states the backup-capacity gap.

- BrainLift:

- the page points to dictionary §6 (Definition owners);

- /brainlift now sends X-Doc-Sha256, like /dictionary and /enablement;

- a new test checks that all three headers match the bytes served.

## Verification

pnpm check passes (67 tests), as do pnpm build and pnpm synth --no-lookups. These are unit and generation checks; they don't establish semantic acceptance.

## Business Value

Agents reading Rhodes no longer:

- call the wrong host;

- misread a legacy token as a stale rule;

- join two schools by address;

- divide by a zero capacity;

- treat an unscored diligence card as signed off.

The BrainLift becomes verifiable like the other documents. This clears 7 of Neeraj's 17 open items.

## Manual Effort Estimate

About 2.5 hours by hand: triaging the 17 items, checking the source contract, editing the documents and adding the header test. Keval: please confirm or adjust.

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

#2254 — 1431-fix-physical-forecast-continuing @mwrshah  approved

- Build Physical End-of-Year and level forecasts with one shared calculation, then use the preceding Physical roster and fractional net additions for next-year retention. This fixes the mixed Program equation / Physical zero reproduced during release #2249 smoke.

- Include End-of-Year in the Physical projection, clear unattributed source diagnostics, and validate source evidence, population conservation, formulas and cross-year carry-forward. Preserve historical locks and use the complete Program view when Physical evidence is unavailable.

- Keep old stored publications readable as Program-only until a fresh complete publication. Deploy Convex before the sync worker so the backend accepts the expanded projection. The next normal complete publication enables Physical again; no data migration, manual refresh or production write is included.

- Verify the contract regression, Physical UI explanation, publication rejection and old-snapshot read behavior with hermetic tests. Full contracts, affected Forecast/API/worker/browser tests, workspace typechecks and lint are validated before publication.

#44 — Point rent and lease cost to the registered lease documents (AI-1046) @kevalshahtrilogy  no labels

Linear: [AI-1046](https://linear.app/builder-team/issue/AI-1046)

## What

This corrects #43's rent guidance, as Neeraj pointed out. Rhodes has no structured rent field, but rent and lease cost are stated in the registered lease documents:

- the executedAcquisitionAgreement and letterOfIntent registrations;

- the lease document referenced by leaseDocumentPublicId on additional acquisitions.

Enablement now tells agents to search those types (POST …/documents/search with documentTypes), cite the document and excerpt or read the agreement, and report rent as a fact from that document. It must never be inferred from dates or budgets. Both type names are in the search enum. The test is updated to match.

## Business Value

Rent and lease-cost questions become answerable from Rhodes evidence, instead of being turned away.

## Manual Effort Estimate

About 20 minutes by hand. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (66 tests), pnpm build and pnpm synth --no-lookups pass. This is a documentation change only.

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

#3921 — fix(acq-perf-review-v2): use prior-year ARR for budget retention @sanketghia  approved

## Summary

- Calculate Finance budget retention as Budget ARR (quarterly recurring revenue × 4) divided by Redshift Actual ARR from the same quarter 12 months earlier.

- Leave the value unavailable when the prior-year Actual ARR snapshot is missing; do not fall back to acquired ARR.

- Update the row label, tooltip, and API methodology text to describe the formula.

## Validation

- Ruff format and check passed; Pyright reported 0 errors.

- Targeted ESLint, Prettier, and TypeScript app typecheck passed.

- Redshift-backed local service returned Q4'26 91.05%, Q1'27 91.77%, Q2'27 93.41%, and Q3'27 94.79%.

## Screenshot

<img width="1673" height="648" alt="image" src="https://github.com/user-attachments/assets/1e8d3679-8e18-4101-ba6c-083675b9980b" />

#43 — Fix Neeraj's findings: stale dictionary header and write count, rent, capacity asOf (AI-1045) @kevalshahtrilogy  no labels

Linear: [AI-1045](https://linear.app/builder-team/issue/AI-1045)

## What

This fixes the three findings Neeraj's DSS agent sent on 10/30:

1. Stale dictionary header. It pinned "API version 0.3.2" and claimed to add no endpoints, while also describing write keys. It now defers to the served /openapi.json for the version. The write count is now 19, up from 17 after #38.

2. Rent. The contract has no rent or lease-cost field. Enablement now says so explicitly, so agents report rent as not available here rather than inferring it.

3. Capacity asOf. It's the projection date, normally the request date, not when capacity was recorded. The docs no longer present it as a measurement date.

A new test ties the stated GET, search and write counts to the allowlist, so the numbers can't go stale again.

## Business Value

These close three contradictions an evaluating agent found in the published docs. Without the fixes, an agent could take a request date as a capacity measurement, or go looking for rent figures in Rhodes.

## Manual Effort Estimate

About 45 minutes by hand. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (66 tests), pnpm build and pnpm synth --no-lookups pass. These are documentation changes only.

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

#41 — Enablement recipe: walkthroughs, renderings and outstanding work across a site cohort (AI-1042) @kevalshahtrilogy  no labels

Linear: [AI-1042](https://linear.app/builder-team/issue/AI-1042)

## What

This adds a recipe to Enablement §9 that answers Arthur's acceptance question using only reads that are already published: "for these sites, which walkthroughs and renderings exist, what remains outstanding, who owns it and by when?"

1. Cohort: use the explicit filters (lifecycleStage=diligence&status=active&include=profile) and record the exact siteRef list. A count given in prose isn't a cohort.

2. Matterport: read profile.matterportModelId from the same list, at no extra cost. Null means not recorded, not proof of absence.

3. Renderings and walkthroughs: use generic other registrations matched on topic and title, then lidar, floorPlan and marketingPack. Search is only a hint.

4. Commitments: work units, tasks and missing requirements, reported as separate fields for status, owner, due date and blocker. Neither a pending item nor a registered file proves the other.

5. Budget: about 102 sensitive reads for a 17-site cohort (six per site), roughly 3.5 minutes paced. Use personal keys, not legacy ones.

6. Completeness: each site is labelled Checked or Could not finish checking. "Not found" is never reported for an unfinished site.

Every route, query parameter, field, tier and status value cited is in the published snapshot, which generation.test.ts enforces. A new test pins the recipe's rules.

## Business Value

This turns Arthur's acceptance test into a documented method that any agent (Joe's included) can follow without someone emailing the links. It removes the 10-vs-17 cohort ambiguity, and it stops "couldn't finish because of rate limits" being reported as "missing".

## Manual Effort Estimate

About 2.5–3 hours by hand: tracing the fields, tiers and status vocabularies across the contract, writing the recipe and adding the test. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (60 tests), pnpm build and pnpm synth --no-lookups pass. A live read-only run of the recipe is still to come and will be reported here as counts only.

Follow-up: once the source adds rendering / matterportWalkthrough document types and documentRef in requirement evidence, re-sync and simplify step 3.

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

#40 — Fix Arthur's documentation feedback: owner, BrainLift, opening, capacity, lineage, plan of record (AI-1041) @kevalshahtrilogy  no labels

Linear: [AI-1041](https://linear.app/builder-team/issue/AI-1041)

## What

This fixes five of the six feedback items Arthur's agent filed on 11/4, all in the published documents:

- Owner. The front now names Keval Shah (Builder Team) as the service owner, covering access, keys, the contract and the docs. Edu Ops keeps ownership of field meaning, and the site's buildout DRI stays the data contact.

- BrainLift. /brainlift now links to the governing BrainLift instead of showing "owner content pending". It doesn't restate the BrainLift's content, and the foundation disclosures stay.

- Opening/capacity. The worked example now treats recorded opening/operating flags as records, not proof that a school is open. Unknown capacity is reported as unknown, never as extra seats.

- Lineage. Change history gives the last audited writer and time. That is not the originating owner of every value, and not a review date.

- Plan of record. The newest openingPlan is reported as the latest *registered* plan. It doesn't by itself establish the approved plan.

The sixth item, Security schema drift, ships with the OpenAPI re-sync PR. The unverified / version-2 Security scoring exists only in the newer upstream contract.

A new test in test/generation.test.ts pins each of these.

## Business Value

Arthur wants Rhodes "super tight before Joe starts using" it. These sentences led agents to overclaim:

- that schools were open;

- that capacity totals were complete;

- that the plan of record was settled;

- who owned a value.

They also didn't say who owns the service. Fixing them removes wrong answers at the source and closes five open feedback items.

## Manual Effort Estimate

About 1.5–2 hours by hand: finding each passage, rewording precisely, regenerating metadata and adding the test. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (60 tests), pnpm build and pnpm synth --no-lookups pass. These are documentation changes only; no runtime behaviour changes.

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

#38 — Publish Work Unit Group metadata and status writes (AI-1039) @kevalshahtrilogy  no labels

Linear: [AI-1039](https://linear.app/builder-team/issue/AI-1039)

## What

Write keys can now update a Work Unit Group and set its red/amber/green status through Rhodes:

- PATCH /portfolio/sites/{siteRef}/work-management/work-unit-groups/{workUnitGroupId} updates the title, description, order, maxScore and approvedException.

- POST /portfolio/sites/{siteRef}/work-management/work-unit-groups/{workUnitGroupId}/status sets red/amber/green, or null to clear it.

Both are relayed only for a write key, acting as its owner. The source applies the same site-write authorization, If-Match revision check and audit as the work-unit writes Rhodes already publishes, and no new scope is needed. Group create and delete remain unpublished.

- allowlist.json: adds two entries to writes.

- openapi.snapshot.json: adds only these two operations. Their components already exist in the snapshot. pnpm sync:openapi would also pull in unrelated upstream drift (about 13 operations and 10 schemas), so I left that for a separate PR.

- enablement.md: describes the new writes and warns that group status and approved exception move the quality-bar score.

- writes.test.ts: pins the two writes in and keeps group create/delete and all deletes out.

## Access

Access is the same as in the source app's UI. Each write is checked against the key owner's own rights. A group can be changed by anyone with operations.siteFields.write (on any site) or by the site's diligence, buildout or P2 DRI (on that site). Both the UI and the API use these rules, so nobody can move a quality-bar score through Rhodes who can't already move it in the source.

Cancelled sites are read-only on both paths: before checking authorization, the source API refuses writes to them with 409 cancelled_site_read_only.

## Business Value

Robbie's team updates WorkUnitGroups and their status as part of EduOps work-plan upkeep. Without these writes they have to keep an Aerie connection only for these two calls, which blocks moving them fully onto Rhodes now that Aerie is being retired.

## Manual Effort Estimate

About 2–3 hours by hand. That covers tracing the upstream group write contract and auth, splicing the snapshot without the drift, docs, tests, and running check/build/synth. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (60 tests), pnpm build and pnpm synth --no-lookups pass. Nothing has been checked against the live source yet.

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

#42 — Re-sync the source contract; document version-2 Security scoring; relay search documentTypes (AI-1044) @kevalshahtrilogy  no labels

Linear: [AI-1044](https://linear.app/builder-team/issue/AI-1044)

## What

This closes Arthur's sixth feedback item, Security schema drift. Live responses carry unverified/notApplicable and version-2 Security scoring that the published contract and docs didn't describe.

Snapshot re-sync (pnpm sync:openapi): 13 operations and 10 schemas drifted upstream. The existing key order is kept so the diff shows only real changes (+263/−41). The notable changes are:

- Quality bars: securityAssessmentVersion: 2, an unverified status on bars and the rollup, and new scoring and colour rules.

- Work Unit Groups: status gains unverified/notApplicable, plus effectiveStatus. Work Units gain supportedItems / securityWorkDefinitionKey and a supportedItemId filter.

- Due diligence: unrepresentableFields. Acquisition: loiSignedDate. Milestone approval: a failed state. Compliance: foodPermitStatus: notRequired.

- Documents: policyAndProcedure joins the generic types, and site search takes optional documentTypes.

- Clarified descriptions: unarchived backup terms aren't necessarily unexpired, and buildout phases are an alias of buildout.

Relay: site document search now accepts documentTypes. Each value must be non-empty, distinct and in the contract's enum. Global search, which doesn't declare the field, still rejects it with 400 invalid_search_request. Without this, the synced contract would advertise a filter the relay refuses.

Docs: Enablement and the Dictionary now explain version-2 Security scoring. An unverified Security bar is reported as "not yet verified", never as passed or failed. They also cover unrepresentableFields (null there means recorded but unreadable) and search documentTypes, including the default exclusion of securityIncident.

Tests:

- Relay: valid documentTypes are forwarded, and empty, duplicate, unknown and non-array values are rejected, as is any value on Global search.

- Docs: every contract quality-bar status must be explained.

## Business Value

Agents reading Security quality bars were seeing statuses and scoring the documents didn't explain, so "unverified" could be read as a pass or a fail. Re-syncing also gives callers the new search type filter, which makes rendering and walkthrough lookups cheaper on the sensitive read budget.

## Manual Effort Estimate

About 3–4 hours by hand: reviewing the drift, writing the order-preserving resync, the relay validation and its tests, and the doc updates. *(Proposed; Keval to confirm or adjust.)*

## Verification

pnpm check (61 tests), pnpm build and pnpm synth --no-lookups pass. Nothing has been verified against the live source.

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

#39 — Test the relay's four-read concurrency guard (AI-1040) @kevalshahtrilogy  no labels

## Summary

The relay refuses a fifth concurrent read with 503 {"error":"service_busy"} and Retry-After: 1 (src/aerie/proxy.ts), but nothing tested it. This adds one test to test/proxy.test.ts, mirroring the existing four-writes test:

- holds four upstream reads open and asserts the fifth is refused with service_busy / retry-after: 1, without reaching upstream;

- fails one held read (502) and asserts a new read gets through while three are still held, so a failure frees its slot;

- releases the rest and asserts a further read succeeds.

Test-only; no behavior change. Linear: [AI-1040](https://linear.app/builder-team/issue/AI-1040/test-the-rhodes-dss-relays-four-read-concurrency-guard)

## Verification

pnpm check (60 tests pass), pnpm build, pnpm synth --no-lookups all succeed locally. Unit tests only; this says nothing about deployed behavior.

## Business Value

Agents investigating diligence-site documents are now hitting the read limit, and EduOps is about to rely on Rhodes DSS more heavily. Locking the busy response and slot release under test means a future refactor can't silently leak read slots (which would lock everyone out with 503s) or drop the Retry-After hint agents use to back off.

## Manual Effort Estimate

~1 hour of focused time (read the guard, adapt the write test's gate pattern, run checks, PR). Proposed by Claude — Keval to confirm/adjust.

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

#2253 — AI-1043: Rendering + Matterport document types; documentRef on requirement evidence @kevalshahtrilogy  approved

Linear: [AI-1043](https://linear.app/builder-team/issue/AI-1043/aerie-rendering-matterport-doc-types-documentref-on-requirement)

## Summary

- Adds rendering ("Rendering") and matterportWalkthrough ("Matterport walkthrough") to DOCUMENT_TYPES in @bran/contracts, filed in 01_Due Diligence like lidar. They're specific types, so no topic is required. Every validator and the public API v2 OpenAPI enums derive from the contract, so they're accepted on upload/registration, producesDocumentTypes, requirements and filters with no other edits (typecheck confirms that the exhaustive Record<DocumentType, …> maps are complete).

- Capacity trigger matrix (Record<DocumentType, …>, so it had to change): Matterport = geometry/conditional (it may carry measured scan data, but a tour link alone isn't enough to run capacity); rendering = unrelated/ignore. Matrix version bumped to 2026-11-04.

- GET /v2/portfolio/sites/{siteRef}/document-requirements: each satisfactionEvidence item now includes documentRef, the same stable doc_* ID the document list returns, so a caller can link a requirement to the file that satisfies it. The OpenAPI schema is updated. The change is additive. If the latest satisfying row is a legacy row that hasn't been backfilled with a public ID, the endpoint returns 503 document_identity_unavailable, the same fail-closed behavior as the document list. It does not silently report the requirement as missing.

Out of scope, on purpose: a blocker field and a cross-site document listing. Robbie Forrest is simplifying the schema separately.

## Business Value

This lets the Rhodes DSS agent answer EduOps's (Arthur's) question: "for the sites in diligence, which Matterport walkthroughs and renderings exist, what remains outstanding, who owns it, and by when?" Today renderings are filed as other plus a free-text topic, and Matterport has no type at all, so nobody can reliably query either. Requirement evidence also didn't say which file satisfied it. Now both can be filed and required as first-class types, and any requirement can be traced to its document. After merge, Rhodes re-syncs its OpenAPI snapshot and updates its documented recipe.

## Manual Effort Estimate

Proposed: ~3–4 hours of focused time: tracing where document types are enumerated, deciding the capacity dispositions, wiring the evidence field and the fail-closed path, writing contract and HTTP tests. _@keval, please confirm or adjust._

## Testing

- pnpm typecheck: pass

- pnpm lint: pass (3 existing warnings in files this PR doesn't touch)

- packages/contracts: document-types.test.ts and capacity-trigger.test.ts pass (new coverage for both types)

- chat: convex/publicApi/v2/documentsHttp.test.ts (62) and lib/public-api/** (304) pass. These include the asserted documentRef on evidence and a new 503 test for a row without a public identity.

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

#3920 — fix(acq-perf-review-v2): tie plan EBITDA to source P&L @sanketghia  approved

## Summary

- Use the source Net Profit value for Acquisition Plan EBITDA so it matches the Finance Plan P&L.

- Preserve the derived EBITDA calculation for Actuals, Finance budget, and Forecast.

- Update calculation notes to distinguish the source Plan value from the derived views.

## Verification

- uv run ruff format services/acq_perf_review_v2_service.py — passed.

- uv run ruff check services/acq_perf_review_v2_service.py — passed.

- uv run pyright services/acq_perf_review_v2_service.py — passed.

- pnpm lint:pr — passed.

- pnpm prettier --check on changed files — passed.

- pnpm tsc -p tsconfig.app.json --noEmit — passed.

## Screenshot

<img width="1679" height="650" alt="image" src="https://github.com/user-attachments/assets/bf0136dd-07e1-45fa-a534-f8226d420fe1" />

#3919 — fix(acq-perf-review-v2): apply Finance retention rules @sanketghia  approved

## Summary

- Surface the Finance 90% Year 1 / 90% Year 2+ retention plan and Plan ARR in the Plan view and Retention Rates tab.

- Calculate Actuals retention from Redshift quarter-end ARR snapshots: annualize against acquired ARR before 12 months of history are available, then compare current period ARR with ARR from 12 months earlier.

- Keep Actuals and Finance budget retention ratios distinct, and show only the forecast retention assumption for Forecast.

## Verification

- uv run ruff format services/acq_perf_review_v2_service.py routers/acq_perf_review_v2_router.py — passed.

- uv run ruff check services/acq_perf_review_v2_service.py routers/acq_perf_review_v2_router.py — passed.

- uv run pyright services/acq_perf_review_v2_service.py routers/acq_perf_review_v2_router.py — passed.

- pnpm lint:pr — passed.

- pnpm prettier --check on changed files — passed.

- pnpm tsc -p tsconfig.app.json --noEmit — passed.

## Screenshot

<img width="1698" height="618" alt="image" src="https://github.com/user-attachments/assets/b240c1c4-76ad-402a-81ad-c8ce176ce9d5" />

#3916 — fix(acq-perf-review-v2): derive plan ARR from acquired ARR @sanketghia  approved

## Summary

- Calculate Cloudsense Plan ARR from acquisition ARR using the monthly compounding formula in the Finance workbook's ARR Trend row 5.

- Use each quarter's ending month; the partial Q4'24 value is the December result after the November and December formula steps.

- Keep Finance budget and Forecast ARR on their existing recurring revenue × 4 calculation.

- Use the current 90% Year 1 / 90% Year 2+ assumptions from Acquisition Performance Plan!B2:C2. Loading those as source data is tracked separately as feedback item #3.

## Verification

- uv run ruff format services/acq_perf_review_v2_service.py — passed.

- uv run ruff check services/acq_perf_review_v2_service.py — passed.

- uv run pyright services/acq_perf_review_v2_service.py — passed.

- pnpm exec eslint --max-warnings 0 --no-warn-ignored src/screens/AcqPerfReviewV2/AcqPerfReviewV2.tsx — passed.

- pnpm prettier --check src/screens/AcqPerfReviewV2/AcqPerfReviewV2.tsx — passed.

- pnpm tsc -p tsconfig.app.json --noEmit — passed.

## Screenshot

<img width="1791" height="669" alt="image" src="https://github.com/user-attachments/assets/96635be2-edde-49b4-8511-871cef0a53ea" />

#3915 — fix(acq-perf-review-v2): exclude bad debt and non-MGMT CBA lines @sanketghia  approved

## Summary

- Exclude Actual rows marked as Provision for Bad Debt (GL 64141), matching /performance-review.

- Exclude Realised FX Gain/Loss, Rounding Gain/Loss, State Tax Expense, and Withholding Tax Expense from V2 Actuals and Budget inputs.

## Validation

- uv run ruff format services/acq_perf_review_v2_service.py — unchanged.

- uv run ruff check services/acq_perf_review_v2_service.py — passed.

- uv run pyright services/acq_perf_review_v2_service.py — 0 errors.

- Read-only Redshift check confirmed flagged Cloudsense write-offs are excluded; unflagged Q3'26 Revenue Write-off remains $975.51.

## Screenshot

<img width="1671" height="752" alt="image" src="https://github.com/user-attachments/assets/e4de8d48-9445-4151-998e-2e6f3ebdd780" />

#3913 — fix(mfr): net repurchase proceeds in book value transfers @sanketghia  approved

## Summary

- Net matched repurchase proceeds into the Book Value Other Investments transfer and Schedule A total/detail.

- Show the offset as a separate Repurchase Proceeds Schedule A group while retaining the existing reversal handling.

## Validation

- Read-only Redshift YTD calculation: Book Value and Schedule A are $178,901,117.74; Passive Investments Investment Acquisitions is ($178,901,117.74).

- September source legs: account 25500 ($50,000,000) plus account 71501 $18,000,000 = ($32,000,000) proceeds.

- uv run ruff format and uv run ruff check: passed.

- uv run pyright: 0 errors, 14 warnings.

## Screenshot

<img width="1882" height="878" alt="image" src="https://github.com/user-attachments/assets/87afdbeb-eeb4-4611-be6e-a0517fd7872d" />

#1 — Serve Lunch Vendor Tracker through the standalone DSS @caina-barbosa  no labels

The Lunch DSS served only the Dashboard API, leaving the separately documented Vendor Tracker unavailable. Add authenticated, live reads of its five dictionary tabs and the current Compliance Evidence tab through the existing standalone service.

The new catalog and paginated tab routes preserve source rows, positional columns, formulas, calculated values, number/date formats and hyperlink metadata. Reviewed headers fail explicitly on drift; blank physical pages continue pagination. Document Register uses canonical A:Q, and Terms & Billing includes the five current additional columns. Linked-file contents and hidden/other tabs remain outside the requested scope.

Google authentication uses the approved reader with spreadsheets.readonly, injected through a second JSON field in the existing dedicated runtime secret. Infrastructure preview changes only the container image and this secret selector; no IAM widening. Apply bounded dependency patches required by the existing release audit.

Validation: 32 tests pass (one existing template test skipped); build and CDK synth pass; high-severity dependency audit passes. Independent implementation/test review passed after fixing malformed page-response handling. Full live local read-back matched all six source tabs, 741 rows, exactly. Production read-back and the existing handoff evidence will be updated after deployment.

#11 — docs: replace obsolete publication runbook with Surtr operations @caina-barbosa  no labels

## Summary

Replace the obsolete hand-assembled publication runbook with the deployed Surtr refresh workflow. Operators can now find the actual contacts-only command, dataset selection, saved-capture recovery, partial-result behavior and cadence configuration in one guide.

Production effect: cleanup or removal. Documentation only; merging neither runs collection nor deploys the API. The corrected packaged API enablement prose takes effect on the next normal API release.

## Why

The old README pointed operators at manual artifact assembly and a September–October bootstrap snapshot. Other guides contradicted the deployed system by saying schedules were disabled, history/cleanup integration was future work, or only contacts were supported. Those instructions were implementation-stage notes, not a usable current runbook.

## Business Value

- One supported operational entry point: the existing Surtr pipeline.

- Clear explanations of fresh versus recovery runs and what happens when one dataset fails.

- Developers retain accurate history, retention, packaging and release contracts without obsolete rollout instructions.

## How does it work

1. Delete manual-component-publication.md and replace its README link with the Surtr operations guide.

2. Consolidate current commands and behavior; retain detailed implementation contracts separately.

3. Remove stale ticket-stage claims, old package hashes and disabled-schedule instructions.

4. Correct API prose to distinguish legacy snapshot cursors from pinned history cursors.

## Scope

### Included in this phase

README.md

docs/current-state-refresh.md

docs/development-and-release.md

docs/incremental-history.md

docs/manual-component-publication.md (deleted)

docs/original-response-evidence.md

docs/recovery-cleanup.md

docs/retained-history.md

docs/targeted-refresh.md

src/source/documents/enablement.md

### Deliberately excluded for later phases

- No collector/API logic, permissions, schedule configuration, source calls or recipient keys change.

- No Surtr code changes or deployment.

- The first actual scheduled-run acceptance remains a separate monitored operation; an enabled schedule is not claimed as proof of a successful scheduled run.

## Test plan

### Automated validation

- Local Markdown links: 24 checked, zero broken.

- git diff --check: passed.

- node scripts/build.mjs: passed using Node 22 and existing matching dependencies.

- node --test test/packaging.test.mjs: 5/5 passed, zero skips.

- pnpm build initially refused the shared dependency-directory symlink; the same underlying build script was then run directly. Required hosted CI uses its normal clean install.

- Read-only AWS verification: daily rule ENABLED at 09:00 UTC; both scoped tagged 30-day recovery/evidence lifecycle rules enabled. GitHub release-enable variable is true.

- Independent documentation review: PASS at 58476b8b391e2a007de0da731503d81f482d39c3; both release-guide findings corrected. Required hosted CI 41694440292 passed both verify and secrets on that exact head.

### Time for Implementation

Approximately half a day for an engineer to audit current code/deployment, consolidate the guides and validate the documentation.

#2238 — feat(raptor-refresh): enable daily schedule (AI-1037) @caina-barbosa  approved

## Summary

Activate the existing daily Raptor refresh schedule at 09:00 UTC (04:00 fixed EST). This completes the scheduled-activation portion of [AI-1037](https://linear.app/builder-team/issue/AI-1037), under [AI-1029](https://linear.app/builder-team/issue/AI-1029).

Production effect: activation. Normal production Raptor runs and full deployed API acceptance passed on November 3. The live rule remains disabled until the normal Surtr production deployment applies this change.

## Why

The collector and manual pipeline are already implemented. The approved daily cadence needs the existing EventBridge rule enabled; this change does not introduce another scheduler or notification path.

## Business Value

- Refresh the five approved datasets daily without manual invocation.

- Preserve targeted manual runs and independently configurable dataset cadences.

- Use existing Surtr failure and partial-result notifications.

## How does it work

1. Set the existing pipeline configuration's schedule.enabled to true.

2. The existing rule runs fresh collection for building, visit_event, alert_counts, user_contact and daily_activity at 09:00 UTC.

3. Existing orchestration, retry/recovery, last-good publication and notifications handle the run. Each dataset's cadence remains 86,400 seconds in the existing configuration map.

## Scope

### Included in this phase

One activation flag, matching operator documentation and the existing configuration test:

pipelines/runners/raptor-refresh/pipeline.json

pipelines/runners/raptor-refresh/README.md

pipelines/runners/raptor-refresh/OPERATIONS.md

pipelines/runners/raptor-refresh/tests/test_controller.py

### Deliberately excluded for later phases

Personnel remains untouched. This PR changes no collector, controller, IAM, warehouse storage, UI or notification implementation.

## Test plan

### Automated validation

- Eight existing Python controller/configuration tests passed, zero skips; independent review passed.

- Pipeline JSON predicates, existing schema validation, Ruff and git diff --check passed.

- Scope is four files: 15 added and 10 removed lines; two added test lines (13.3%).

- Required hosted CI passed (41674549126); Mercy approved exact head e43c2b3c4b5b459615be9d8253cb706920b53802 with no findings (review 5755992059).

- Raptor production release dc651f085be02d1be379c324fc2a02ff1edb7b82 is healthy on task revision 5; all five normal Surtr recovery executions succeeded. History is published through November 2 with no continuation remaining.

- Full authenticated deployed API pagination matched all eight projection hashes/counts: 56 buildings, 61 stations, 1 kiosk, 5,671 visits, 89 alert rows, 265 contacts, 4,950 daily rows and 117 unchanged personnel rows. Source clocks were preserved; selected alert overlay derivation was independently bound to its actual publication plan. Temporary validation access was revoked and HTTP 401 confirmed.

- Independent final production/data receipt review passed. This validates the manual production path; the first actual scheduled run still remains to be observed.

- After production deployment, verify the live EventBridge rule and its first scheduled execution through the deployed DSS. This result is not claimed yet.

### Time for Implementation

Approximately half a day for a developer to validate the configuration, review and deploy the activation, excluding the wait for the first scheduled run.

#10 — Restore collector reads and retained refresh recovery @caina-barbosa  no labels

## Summary

Raptor refreshes were failing on our request interception, an unnecessary memory reserve, and closed assumptions about native method codes and report dates. Replace network enforcement with passive response observation, preserve native method values and query-cohort dates, and keep saved capture identities and source clocks intact during recovery/publication.

The existing authentication and source readers remain in use. Ownership, sensitive-data handling, immutable storage, publication CAS and last-good recovery remain intact. New daily rows describe observed query cohorts; they do not invent zero activity or complete local-day coverage. Previously accepted component bytes still replay unchanged.

## Validation

- Proven on the existing EC2 host before opening this PR: real collection and S3 publication through November 2, followed by a successful all-five-dataset recovery run with zero source reacquisition.

- Actual authenticated DSS HTTP matched every page: 5,671 visits, 4,950 daily rows, 56 buildings, 61 station accounts, one kiosk, 89 alert rows and 265 contacts. The 117 personnel rows remained unchanged; the temporary validation identity was revoked and rejected afterward. These checks used isolated mutable publication state, not production acceptance.

- 81 Node tests and two Python tests passed with no skips; audit, build, synthesis, Linux Docker build and secret scans passed. Independent code/security review passed the complete change.

- Final emitted runtime code matches the EC2-proven artifact; the only later artifact change is the dictionary documentation describing query-cohort coverage.

## Release

Deploy the reviewed DSS reader before installing the matching host publisher and promoting the retained captures through the normal Surtr path. Production validation and schedule activation follow the existing release controls; this PR does not enable the schedule or change IAM permissions.

#2252 — AERIE-821: Document onCampus evaluation time, no year-end freeze, and publication-time freshness @marcusdAIy  approved

## Summary

- Document when onCampus is evaluated: at the latest SIS enrollment mart build. For the current school year it's that day's roster. For a finished school year it counts students whose enrollment for that year completed or is still enrolled, with no withdrawal in effect.

- State that there is no year-end freeze: a finished year's onCampus can change on a later refresh, so two reads of the same schoolYear can differ

- State that the enrollment freshness.asOf is Aerie's publication time, not a source as-of date, and that no separate SIS as-of time is served

- Add the same points to the getAdmissionsProgramEnrollments description and the enrollment student drilldown's column parameter

Docs-only part of AERIE-821.

## Why it's needed

DSS-131 read onCampus=165 for schoolYear 2025 and couldn't tell whether that historical value was frozen or live, or what the timestamp meant. In dbt/models/intermediate/enrollment/int_enrollment_classification.sql, x_is_on_campus is evaluated against warehouse_now() (getdate()) on every build. The enrollment route's freshness.asOf is the publishedAt that Aerie stamps with Date.now() when it publishes a refresh.

The funnel half of the ticket (newEnrolledCurrent and the year-named stages) was documented in #2245. The remaining asks are not in this PR because they need an owner decision: a governed freeze or rollover rule, a separate machine-readable source as-of field, and post-deploy probes.

## Changes

- chat/lib/public-api/v2/domains/admissions.ts: two new onCampus traps, plus additions to the operation description and the drilldown column parameter description

- chat/lib/public-api/v2/domains/admissions.node.test.ts: asserts the new traps

## Breaking changes

None. These are documentation changes only.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/admissions.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts lib/public-api/v2/openapi.node.test.ts convex/publicApi/routeManifest.test.ts (95 passed)

- [x] The new test fails with the source change stashed

#2251 — AERIE-2025: Document that Program-Site links come through a canonical School @marcusdAIy  approved

## Summary

- State in the DSS dictionary that Program operatesAt Site edges are derived from a canonical School: a School marketed as the Program that operates at the Site, with the weaker of the two links' confidence

- Add two interpretation points to directory.resolve-site-program:

- A Site with no qualifying Program has no School linking it to one. That doesn't mean no students attend.

- Two Site records at one address are separate Sites and can carry different Programs.

Fixes AERIE-2025.

## Why it's needed

Arthur's questions 1 and 5 (no Program at Edmond or Park Meadows, and different Programs on the two 2205 East Hebron records) come from not knowing how Program-to-Site links are formed. In convex/ontology/registry.ts the edges are built only by joining canonical School marketedAs and operatesAt links, and the dictionary didn't say so.

Questions 3 and 4 were already resolved by earlier work:

- #1915 rejects malformed schoolYear values with 400 invalid_parameter.

- The SIS-backed enrollment contract documents that reEnrollments + newEnrollments = firstDayEnrolled.

Question 2 asks whether specific School links are correct. That's a data review for the School Ontology owner, not a docs change.

## Changes

- chat/lib/public-api/v2/domains/directory.ts: adds the derivation to the Program operatesAt relationship meaning, plus the two interpretation points

- chat/lib/public-api/v2/domains/directory.node.test.ts: asserts the new text

## Breaking changes

None. These are documentation changes only.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/directory.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts (35 passed)

- [x] The new test fails with the source change stashed

#2250 — AERIE-807: Explain milestone lanes, completion and status colors in Portfolio and Buildout tooltips @marcusdAIy  approved

## Summary

- Rewrite the Portfolio board's milestone header tooltips so each one says why a site is in that lane and what completes the milestone

- Rewrite the Buildout dashboard's milestone column (i) tooltips with the same milestone meaning, plus Green, Yellow, Red and Gray definitions in plain terms

- Tie buildout completion to the certificate of occupancy (CO): "6. Obtaining Certificate of Occupancy" says buildout is complete when the CO is complete, and "7. Gaining Edu Approval" says it starts once the CO is complete and education approval is pending

Fixes AERIE-807.

## Why it's needed

New users couldn't tell from the tooltips what it means for a site to be in a milestone, or what the colors mean. The copy described states loosely ("Construction is wrapping up") instead of the actual rule: a site sits in the lane of its earliest milestone that isn't complete or not applicable.

## Changes

- chat/components/dashboards/portfolio/types.ts: new PORTFOLIO_PHASES descriptions in the form "Here because ... Complete when ...". The Completing Construction lane notes that older sites skip that milestone.

- chat/components/dashboards/fto/fto-matrix.tsx: each milestone column gets a numbered title and an intro, and the columns share one status list. The Construction column explains its fallback to milestone 6 for sites without milestone 5. COLUMN_INFO is exported for tests.

- Tests: portfolio-phases.node.test.ts and a new fto-matrix-column-info.test.tsx cover the copy

No milestone derivation, sorting, filtering, header click behavior or color logic changed.

## Breaking changes

None.

## Test plan

- [x] pnpm vitest run components/dashboards/portfolio/__tests__/portfolio-phases.node.test.ts components/dashboards/fto/__tests__/fto-matrix-column-info.test.tsx components/dashboards/fto/__tests__/fto-matrix-selection.test.tsx components/dashboards/portfolio/__tests__/portfolio-board.test.tsx (27 passed)

- [x] The new tests fail with the source changes stashed

#3912 — fix(acq-perf-review-v2): match Finance IRR tax handling @sanketghia  approved

## Summary

- Match Finance's cumulative 5% tax calculation for V2 IRR, carrying prior-quarter losses forward and retaining negative cash flows.

- Use the Finance sheet's default 10% IRR guess for sign-changing cash-flow streams; retain bisection for conventional streams.

- Update IRR tooltips and calculation documentation.

Finance source: [Q4'26 Budget - Base case, D31:F35](https://docs.google.com/spreadsheets/d/1NzUSwtltWcr_QEJ1xU5ma5B3I5ya0_9NVMHRkHM7bkc/edit?gid=1256010723#gid=1256010723&range=D31%3AF35)

## Validation

- Ruff format/check and Pyright passed.

- Prettier, ESLint, TypeScript, and git diff --check passed.

- Tests were not run.

## Data note

The formula uses V2's existing CBA inputs. Their five-quarter Net Profit total differs from the Finance sheet by $12,849.16 pre-tax, so the corrected calculation on current CBA inputs is approximately $15,162,235.49 versus $15,174,442.19 from the workbook inputs. This source-input difference remains to be reconciled separately.

## Screenshot

<img width="1463" height="622" alt="image" src="https://github.com/user-attachments/assets/712854dc-571a-4e44-9d76-908bfef230a1" />

#9 — fix(refresh): reconcile browser traffic and finish owned cleanup (AI-1037) @caina-barbosa  no labels

## Summary

Fixes three live collector issues found while activating [AI-1037](https://linear.app/builder-team/issue/AI-1037), under the approved [AI-1029 refresh specification](https://linear.app/builder-team/issue/AI-1029/raptor-refresh-through-surtr-implementation-specification): fully acknowledged static responses can lack Chrome Network events, and repeated ownership checks rebuild the same verified runtime and SDK clients for every cleanup object. The host also reported a terminal result before its cleanup proof was durable, causing Surtr to reject completion.

Production effect: controlled rollout. This changes the collector package. It requires installation on the existing host after merge. Merge does not start collection or enable scheduling; no Surtr or DSS API release is included.

## Why

The live trace after PR #8 proves that the original static request now settles successfully, but its absent Network event still leaves a negative reconciliation balance. The request is an allowed GET/Script, its bounded body was fully read, and Chrome acknowledged fulfillment; all other request rows settled. The failed receipt stays failed.

Cleanup also calls the full Python package/identity setup once per object. An actual check took 1.35 seconds. Reusing the verified client reduced two subsequent checks against the same active lease to 108 ms and 11 ms while retaining a fresh consistent ownership read for each call.

The final source-failure status poll returned terminal with quiescent: false. The controller correctly refused it, leaving final reconciliation unfinished. Host status now remains running while its systemd unit is active and cleanup is pending; terminal requires the matching execution and owner quiescence proof.

## Business Value

- Allow a completed static resource to reconcile without accepting missing evidence for source data.

- Remove repeated package hashing, credential discovery and SDK construction from each ownership check.

- Continue detecting cancellation, ownership changes and expired deadlines on every check.

- Let Surtr wait through cleanup and receive a verifiable terminal result.

## How does it work

1. The guard records an explicit static-fulfillment acknowledgement only after the full bounded body read and successful Fetch.fulfillRequest.

2. A negative balance is reconciled only when it is exactly minus one, no Network row exists, exactly one Fetch row exists, and that row is explicitly acknowledged, dispatched, nonlocal and nonfailed. The new counter participates in the final Network/Fetch accounting equation.

3. Critical requests, rejected fulfillment, unknown traffic and request authorization retain their existing requirements. No failed historical capture is adopted.

4. Refresh startup retains the full Python package, actor and control verification. It creates one DynamoDB client using the same privately verified credentials.

5. Every ownership check performs a fresh consistent GetItem, checks owner/token/running status/cancellation/expiry/deadline, and runs the existing local owner, heartbeat and PID checks before and after it. Lease rows are not cached. The client is destroyed on exit.

6. control_status withholds terminal status until the result and cleanup proof match the execution and owner. Active cleanup remains running; inactive or mismatched evidence remains unknown.

## Scope

### Included in this phase

- Static-response reconciliation and focused regression coverage.

- Reused client setup for live ownership checks.

- Owner-bound completion reporting after cleanup.

- Exact final diff paths:

collector/install-retention.mjs

collector/guard.test.mjs

refresh/entry.mjs

refresh/dispatch.test.mjs

refresh/host-bridge.py

refresh/host_supervisor_test.py

### Deliberately excluded for later phases

- Source authentication, request permissions, collectors and model schemas.

- Changes to lease acquisition/takeover, cancellation rules, publication or retention semantics.

- Surtr code, schedule activation, personnel refresh and recipient credentials.

## Test plan

### Automated validation

- Actual existing EC2, pinned Node 22.23.4: the same guard fixture fails with the old installer and passes with the candidate. All ten scenarios pass, including rejection of missing-Network critical data and rejected static fulfillment. Source calls and storage writes: zero.

- Existing dispatch tests: four passed, including changed-token and cancellation rejection on fresh reads.

- Actual existing EC2 and active lease: initial Python check 1,348 ms; candidate checks 108 ms and 11 ms, two consistent reads, zero source calls/AWS writes. This measures per-check setup reduction, not a completed refresh duration.

- Baseline-enabled pnpm check: passed. git diff --check passed.

- Independent correctness/security review passed exact cumulative diff SHA 82f8aac7306d44caeb8b5af4132173286bc465dd57e029be971397874e333eee.

- Hosted verify and secrets checks are required before merge. Raptor does not use Mercy; the user explicitly confirmed that independent review and required CI are the applicable gates.

- Raptor is explicitly exempt from the test-LOC cap. Focused regression coverage is retained.

- Isolated EC2/SSM live contacts acquisition passed all 74 steps with an accepted native traffic receipt, zero unresolved requests and confirmed browser cleanup. The actual native adapter validated 568 response-evidence objects and the complete contacts envelope.

- Reusing that capture, actual refresh/publication code and the authenticated localhost DSS served all 265 contacts, preserved the five unselected envelopes byte-for-byte, and rejected the revoked temporary key. The repeatable retained-data check takes 11.6 seconds with zero additional source calls. Its storage is private memory/disk; it does not substitute for real S3, Surtr lifecycle or deployed validation.

- Final accepted-host installation, real cloud publication, Surtr completion/cleanup and authenticated deployed readback remain required. Old failed captures remain ineligible for recovery.

- Real S3: 568 retained response objects saved/read back with fresh consistent live lease checks on mutations; isolated canary component/request storage and retirement of two canary objects passed. No source reacquisition, global pointer writes, or retirement of existing data.

- Actual EC2 transient systemd unit: old status reproduces terminal-before-quiescence; candidate reports running during cleanup, unknown without valid proof, then terminal only with matching quiescence. Zero source/cloud writes. Independent changed-code review and two network-disabled Python tests passed.

### Time for Implementation

Approximately one engineer-day for trace diagnosis, the two narrow fixes, actual-host validation and review.

#2094 — 1422-drive-subfolder-matching @mwrshah  approved

- Match both legacy NN. Name and current NN_Name site subfolders in upload/canonical-folder and MCP path lookups.

- Prefer exact names and preserve missing-folder errors, folder templates, and live Drive folders.

- Keep REBL3 credentials and due-diligence apply failures out of scope.

#2248 — 1429-forecast-final-rounding @mwrshah  changes requestedmercy-allow-critical

- Preserve fractional forecast contributions; round and clamp only complete estimates. Publish V5 while retaining historical locks and measured-count validation.

- Update fractional breakdowns, shared contracts, API labels, and regression coverage. Surface EduCRM source-completeness gaps as warnings without changing reporting eligibility.

- Production prerequisite completed November 3: eight history contribution columns widened to numeric(38,16) in one transaction. Verified value/NULL preservation, unchanged row counts (45,807 Program / 128,954 level), headline totals, owners, and grants. Hourly scheduling restored; no V5 code deployed by the migration.

- Physical construction and validation both use recomputeForecastV2Physical; the exact comparison is not against warehouse-decimal outputs. A 3 × 0.35 probe passes validation before and after JSON serialization; all 31 Physical tests pass. Keep intermediate precision rather than introducing six-decimal rounding.

#8 — fix(refresh): settle static responses and retain cleanup diagnostics (AI-1037) @caina-barbosa  no labels

## Summary

Fixes collector shutdown accounting and preserves private cleanup-failure diagnostics found during the first production Raptor refresh under [AI-1037](https://linear.app/builder-team/issue/AI-1037) and the approved [AI-1029 refresh specification](https://linear.app/builder-team/issue/AI-1029/raptor-refresh-through-surtr-implementation-specification). A permitted static GET that has been completely read and successfully fulfilled no longer waits indefinitely for a separate Chrome Network completion event.

Production effect: controlled rollout. This changes the generated collector package. Merge does not start collection or enable the daily schedule; the accepted host package must be installed separately.

## Why

The first targeted contacts run produced a valid 265-row component, but its final traffic receipt failed with unsettled_traffic. The retained trace isolates one allowed app GET/Script asset with HTTP 200 and a completed response handler, but no Network terminal event. Critical failures, refusals, unknown traffic and pending protocol tasks were all zero. The failed capture remains failed and is not adopted by this change.

## Business Value

- Prevent a completed static-file delivery from discarding otherwise valid collection work.

- Preserve strict completion checks for authentication documents and source data.

- Surface the existing fixed host-transport failure code instead of a generic refresh failure.

## How does it work

1. The existing pinned guard patch still reads a response body completely within its byte limits.

2. After Fetch.fulfillRequest resolves successfully, only an allowed static GET of type Script, Stylesheet, Font or Image becomes settled. A static_fulfillment_ack event records that completion.

3. Rejected fulfillment, incomplete streams, critical/auth/data requests, unknown traffic, request policy and network-accounting checks retain their existing behavior.

4. Refresh result classification now preserves the existing refresh_host_transport_failed code.

5. Cleanup retains the failed HEAD/tag-read/tag-write/tag-verification stage and a bounded error classification in a create-only, root-owned private diagnostic file. It preserves existing retries, outcomes and pending-cleanup behavior; this adds visibility rather than claiming to repair the unknown earlier tagging failure.

## Scope

### Included in this phase

- Future collector static-response completion and its focused regression checks.

- Exact final diff paths:

collector/install-retention.mjs

collector/guard.test.mjs

refresh/run.mjs

refresh/entry.mjs

refresh/recovery-cleanup.mjs

refresh/recovery-cleanup.test.mjs

### Deliberately excluded for later phases

- Surtr code, manual invocation and schedule configuration.

- Authentication, collector queries, source permission changes and data/model schemas.

- Retroactive acceptance of the failed capture or changes to frozen receipts.

## Test plan

### Automated validation

- Actual existing EC2 host, pinned Node 22.23.4, isolated files and original baseline: identical regression fixture failed against the old guard and passed against the patched guard. No source calls or storage writes. Old: exit 1 in 8.0 seconds; patched: exit 0 in 9.1 seconds.

- The existing five scenarios are preserved; three added scenarios cover an absent static terminal event, rejected static fulfillment, and an absent critical-data terminal event. All eight scenarios pass with the fixed guard, zero skips.

- Reproduction: RAPTOR_BASELINE=<verified original package> RAPTOR_POLICY_OVERRIDE=refresh/vendor/coherent-policy.mjs RAPTOR_REQUIRE_BASELINE=1 node --experimental-vm-modules --test collector/guard.test.mjs.

- The combined baseline-enabled pnpm check passed. git diff --check passed.

- Actual EC2, pinned Node, socket-denied cleanup fixture: old code passed 2/3 and failed the added diagnostic assertion; candidate passed 3/3 in 0.38 seconds. No source calls or storage writes. The first temporary bundle omitted the unchanged lifecycle JSON fixture; this was corrected before the complete 3/3 run.

- Read-only checks using the actual host role returned HTTP 200 for HEAD and exact-version tag reads on both objects at the earlier cleanup boundary. This does not establish the historical failed operation.

- Independent focused correctness/security review passed exact six-file diff SHA 212e4a930a578e34babc335df84ddfe805d2006e22a53834f50169a6f4e692a7.

- Existing deployed API after the failed run retained all six published hashes/clocks and contacts projection. Temporary validation identity was revoked and returned HTTP 401 afterward.

- Hosted CI and exact-head review remain required before merge. A new targeted real capture remains required after installing the accepted package; the offline regression is not that proof.

- Change budget: 121 implementation lines and 123 test lines added (244 total); the user explicitly approved a narrow exception to the 20% test-LOC cap for this repair PR on November 3, 2026. No code padding or test removal.

### Time for Implementation

Approximately half a day for trace diagnosis, the focused fix, runtime reproduction and review.

#3910 — fix(monthly-financial-reporting): clean up report presentation @sanketghia  approved

## Summary

- Remove the generic data-accuracy disclaimer across monthly financial reporting while keeping partial-load warnings.

- Move EBITDA Memo before Book Value in Reports.

- Remove the post-acquisition performance summary list from the Software memo.

## Checks

- ESLint on the three changed files: passed.

- Prettier on the three changed files: passed.

- pnpm tsc -p tsconfig.app.json --noEmit: passed.

- Tests were not run.

#3909 — feat(acq-perf-review-v2): add MoM to payback table @sanketghia  approved

## Summary

- Add a MoM column to the V2 IRR & Payback scenario table for Acquisition Plan and Budget Base.

- Calculate MoM as cumulative after-tax EBITDA over the 40-quarter modeled horizon divided by purchase price, using V2's existing cumulative tax path.

- Return an unavailable value when the scenario calculation is unavailable; no new Redshift source field is required.

## Validation

- Ruff format and check

- Pyright

- ESLint

- Prettier check

- TypeScript check (tsc -p tsconfig.app.json --noEmit)

## Screenshot

<img width="907" height="512" alt="image" src="https://github.com/user-attachments/assets/57af2a18-3503-4075-8316-fa4afce5d4da" />

#3908 — fix(acq-perf-review-v2): align forecast inputs with Finance @sanketghia  approved

## Summary

- Use the Finance master mapping to resolve approved CBA classes for actuals and budget queries, with the existing static map as a fallback for acquisitions without an approved roster.

- Calculate forecast retention from the selected budget's Redshift ARR snapshot, taken at month-end two months before the budget cycle starts.

- Return the ARR snapshot date and value in forecast metadata and explain the formula in the UI.

- Rename the P&L Plan subtab to Acquisition Plan while keeping Plan and Actuals separate.

## Validation

- Ruff format/check and Pyright passed.

- Prettier, ESLint, and the app TypeScript check passed.

- A read-only Cloudsense 2026-Q4 service fetch returned Forecast ready, using the 2026-08-31 snapshot and a 90% retention cap.

## Screenshot

<img width="1397" height="865" alt="image" src="https://github.com/user-attachments/assets/ec103cb7-bdaa-42ea-bf12-491ae0ff2f1a" />

#3907 — feat(acq-perf-review-v2): add selected Prices Paid view @sanketghia  approved

## Summary

- Combine Payback and Annual IRR into the first, opening “IRR & Payback” tab, with Payback shown first.

- Add a selected-acquisition Prices Paid table after it, using the selected Finance budget and V2 calculations.

- Keep the remaining metric tabs in their existing relative order.

- Add the Prices Paid summary to the V2 service response and FastAPI response model.

- Handle older API responses that omit the new Prices Paid field during rollout.

## Validation

- Ruff, Pyright, ESLint, Prettier, app TypeScript check, production build, and diff checks passed.

- AcqPerfReviewV2 focused spec: 4 passed.

- Acquisition Performance V2 backend feature suite: 36 passed.

No database migration is required.

## Screenshots

<img width="1323" height="895" alt="image" src="https://github.com/user-attachments/assets/fe4192f2-770a-4add-98f0-e6848848fe83" />

<img width="1322" height="865" alt="image" src="https://github.com/user-attachments/assets/ffff8a4b-6227-4a4c-9e08-6eb0281665e6" />

#3905 — fix(mfr): detect repurchase proceeds from memo @sanketghia  approved

## Summary

- Detect 25500 repurchase asset legs from the source memo marker instead of model-generated transaction purpose.

- Preserve the account, cash, reversal, journal, period, and realized-sale matching rules.

- Update the existing regression fixture to cover the generic Wire transfer purpose with repurchase evidence in the memo.

## Context

A daily NetSuite enrichment rerun classified the September 2026 25500 rows as Wire transfer even though their source memo still identifies the repurchase. The purpose-based filter then omitted $32M of proceeds, leaving the displayed row at -$1.2M instead of +$30.8M. This change bases the MFR asset-leg match on the preserved memo marker.

Related: KLAIR-3610.

## Verification

- uv run ruff format services/monthly_financial_reporting/book_value_service.py tests/mfr/book_value/test_book_value_service.py — passed; both files unchanged.

- uv run ruff check services/monthly_financial_reporting/book_value_service.py tests/mfr/book_value/test_book_value_service.py — passed.

- uv run pyright services/monthly_financial_reporting/book_value_service.py tests/mfr/book_value/test_book_value_service.py — 0 errors, 7 warnings.

## Screenshot

<img width="1553" height="787" alt="image" src="https://github.com/user-attachments/assets/f43236a1-111d-4d25-b1ed-cd6b194cf481" />

#2246 — AERIE-2549: Label enrollment-summary currentEnrollment as EduCRM's figure, not the SIS count @marcusdAIy  approved

## Summary

- Define currentEnrollment on the Site enrollment summary in the DSS dictionary as EduCRM's current enrollment from the incumbent Admissions enrollment projection, not the SIS seated count

- Say what null means: the Site has no HubSpot program code, or the published forecast run has no projection row for it. It is not zero students

- Reword the getSiteEnrollmentSummary description and the currentEnrollment schema property to match

Fixes AERIE-2549 and AERIE-2556.

## Why it's needed

The route serves enrollmentProjections.currentEnrollment, which is copied from EduCRM all_program.current_enrollment. Agents read it as the enrolled count, so Palo Alto reported 36 where SIS shows 31 (AERIE-2549). For a Site without a HubSpot program code or projection row the value is null, and agents read that as no enrollment even where another system shows students (Park Meadows, AERIE-2556). The utilization trap already said the value wasn't the SIS roster, but currentEnrollment itself had no dictionary entry and the operation called it "the latest published enrollment observation".

## Changes

- chat/lib/public-api/v2/domains/site-profile.ts: new currentEnrollment field on portfolio.site.profile with meaning, null meaning and traps that point to getAdmissionsProgramEnrollments onCampus for the SIS seated count. Also updates the schema property description and the operation description.

- chat/lib/public-api/v2/domains/site-profile.node.test.ts: asserts the new field and description

## Breaking changes

None. These are documentation changes only; the response shape and values are unchanged.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/site-profile.node.test.ts lib/public-api/v2/openapi.node.test.ts convex/publicApi/routeManifest.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts (63 passed)

- [x] The new test fails with the source change stashed

#2245 — AERIE-2398: Document that the Program Funnel serves one school year and its year-named stages are relative @marcusdAIy  approved

## Summary

Documents two Program Funnel behaviors behind AERIE-2398 and AERIE-2471: the aggregate serves a single school year, and its year-named committed and deposit stages are relative. Docs only.

## Why it's needed

- One school year: pipelineFunnel rows are grouped by the deal's session_school_year. getEnrollmentFunnelProgramAggregateForV2Api calls latestFunnelRowsForProgram without a year, so it keeps only defaultForecastProjectionYear (2027/28 from 12 August 2026), plus lead and showcase rows with no year. Other years' committed and deposit deals are dropped, and the response doesn't name the year. Alpha Fort Worth's students seated for 2026/27 are 2026-year deals, so every committed stage read 0 (AERIE-2471).

- Relative stages: FUNNEL_STAGE_TO_RAW_IDS maps EduCRM's relative stages (070b_completed_next, deposit_next_year and the others) onto fixed-year ids and labels (enrolled_2026_27 "7b. 2026/27", deposit_2026_27). Those don't move at rollover. Alpha Marin County's 2027/28 deposits and commitments read as 2026/27 (AERIE-2398).

- The stage ids are part of the public contract (OpenAPI enum, forecast contract), so this PR documents them rather than renaming them.

## Changes

- Program Funnel category traps:

- The aggregate covers one school year and doesn't say which. It explains how that year is chosen, says a zero committed count is not "no commitments", and points to getAdmissionsProgramEnrollments with schoolYear.

- The year-named committed and deposit ids and labels carry this, next and later years, so a 2027/28 commitment can sit in enrolled_2026_27.

- read-program-funnel-aggregates workflow: the one-school-year line as an interpretation step.

- Dictionary test.

## Breaking changes

None. Dictionary text only.

## Test plan

- pnpm vitest run lib/public-api/v2/domains/admissions.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts: 60 passed.

- Red check: with the source change stashed, the new test fails.

#2244 — AERIE-2397: Document that Enrollment drilldown studentRefs can 404 on the student profile route @marcusdAIy  approved

## Summary

Documents that a studentRef from the Enrollment student drilldown can answer 404 student_not_found on GET /v2/admissions/students/{studentRef}. This is a docs-only fix for AERIE-2397.

## Why it's needed

Since #1672, listAdmissionsEnrollmentStudents reads the SIS publication and mints each studentRef from the SIS student ID (insertSisEnrollmentCohortStudents). getStudentProfile maps the ref back correctly but only looks the ID up in analyticsContacts, the HubSpot contact model, so every SIS-minted ref 404s. getStudentAcademics reads growth and teacher data keyed by HubSpot contact ID, so it returns empty history for the same refs. Readers took the 404 as a broken or unknown ref, because the dictionary calls refs opaque and stable.

## Changes

- admissions.enrollmentStudent publicRef: new trap. The ref comes from the SIS identity, the profile route can 404 for it, and academics can return empty history. Neither means the student is unknown, so read name, grade and school year from the drilldown row.

- read-enrollment-students workflow: the same line as an interpretation step.

- getAdmissionsStudent OpenAPI description: it resolves only students in the Admissions contact model.

- personObject and drilldownWorkflow take optional publicRefTraps and extraInterpretation, so the text applies only to the Enrollment drilldown.

- Dictionary test.

## Breaking changes

None. Dictionary and OpenAPI text only.

## Test plan

- pnpm vitest run lib/public-api/v2/domains/admissions.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts lib/public-api/v2/openapi.node.test.ts convex/publicApi/routeManifest.test.ts: all pass.

- Red check: with the source change stashed, the new test fails.

#2243 — AERIE-2158: Define the Waitlisted catch-all and the Pipeline waitlisted column @marcusdAIy  approved

## Summary

Documents where "Waitlisted" comes from in Admissions and what a zero means. This covers only the docs part of AERIE-2158.

## Why it's needed

Readers took the Program Funnel other bucket's 999_other::Waitlisted detail as a measured waitlist and treated a zero as "no families waiting". That label is an EduCRM catch-all detail that Aerie only relays. The measured waitlist is the Finalsite waitlisted column on the Pipeline matrix (mart stage 065_waitlisted).

## Changes

- Program Funnel category trap: there is no waitlist stage. EduCRM deals whose detail reads Waitlisted are counted inside other. A zero means no deals carry the label, not that no families are waiting. Points readers to the Pipeline waitlisted column.

- admissions.pipelineMatrix: new columns[waitlisted] field covering the source (Finalsite local_status waitlisted, 065_waitlisted), whether it counts toward Total or Active Applications, and its traps: Finalsite-only, not the EduCRM catch-all, and no grade band.

- Dictionary test.

## Breaking changes

None. Dictionary text only.

## Test plan

- pnpm vitest run lib/public-api/v2/domains/admissions.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts: 58 passed.

- Red check: with the source change stashed, the new test fails.

#2242 — AERIE-2529: Explain Milestones 4 and 5 for change-of-use sites @marcusdAIy  approved

## Summary

Explains how to read Milestone 4 "Obtaining Permits" and Milestone 5 "Completing Construction" for change-of-use sites, where the approval isn't a construction permit and the physical work can be minor.

Linear: [AERIE-2529](https://linear.app/builder-team/issue/AERIE-2529)

## Why it's needed

At Tulsa 109 N Detroit (a change-of-use on a finished office suite), a cold reader read "Completing Construction due 10/23" as real construction, when the work was about a week of signage, emergency lighting and shelter provisions. The dictionary gave M4/M5 meanings that assume a construction permit and physical construction. The furnishingBeginDate half of the ticket already shipped in #1908.

## Changes

- portfolio.buildoutMilestone.key meanings:

- constructionPermits now covers permits or AHJ approvals, and notes that a change-of-use approval is the authority's sign-off on the new use.

- completingConstruction now says the label is fixed and doesn't describe scope; change-of-use work can be minor.

- inspectSiteBuildoutMilestones interpretation: labels are fixed across the portfolio. For a change-of-use site (getSiteCompliance ahjReviewType changeOfUse, or site notes describing one), describe M4 as the authority's approval for the new use and M5 as finishing the remaining work. Don't describe a construction permit or major construction unless the site's records say one is involved.

## Breaking changes

None. Text-only.

## Test plan

- [x] pnpm vitest run on lifecycle-property.node.test.ts, agent-context/projection.node.test.ts and convex/publicApi/dss/http.test.ts: 40 passed.

- [x] Red check: the new test fails with the source change stashed.

#2241 — AERIE-1989: Define Community and Established Funnel dashboard stages and counting maps @marcusdAIy  approved

## Summary

Defines the Community and Established Funnel dashboard vocabulary in the Admissions dictionary: the stage ids and their order, every count map and the counting mode it matches, deals vs enrolled, how the two funnels relate, and how a missing rollup differs from a zero.

Linear: [AERIE-1989](https://linear.app/builder-team/issue/AERIE-1989)

## Why it's needed

Each dashboard object had one meaning sentence, so a cold reader couldn't order the stages, tell stageCounts from observedStageCounts/activityStageCounts/classicStageCounts/checklistStageCounts, or say whether Community and Established counts may be added. The year-scope half shipped earlier with AERIE-1988 (#2113). This covers the rest.

All definitions come from @bran/contracts/admissions-community-funnel and admissions-full-funnel, plus the drilldown defaults in convex/admissions/dashboards/*Funnel.ts (countingMode ?? "backfill").

## Changes

- admissions.communityFunnelDashboard: new fields.

- programs[].stageCounts lists the six stages in order. Commitment is the entry cohort and eligibility the gate. It is Backfill, and it is what the drilldown pages by default.

- programs[].observedStageCounts: the non-inferred subset, with no drilldown mode.

- programs[].activityStageCounts.

- programs[].classicStageCounts: the strict subset chain.

- admissions.establishedFunnelDashboard: new fields.

- rollups[].stageCounts: Backfill with no gates.

- rollups[].checklistStageCounts.

- rollups[].deals.

- rollups[].enrolled: the filled-seat outcome. It is not a stage and is not equal to contractSigned.

- Both dashboard workflows get interpretation lines:

- the stage order;

- which map each countingMode returns;

- Community is the committed subset of the deals Established counts, so the two are never additive;

- partial is the only unavailability signal;

- an absent Program-year rollup means no deals, while a present zero is a real zero.

## Breaking changes

None. Text-only dictionary additions.

## Test plan

- [x] pnpm vitest run on admissions.node.test.ts, agent-context/projection.node.test.ts and convex/publicApi/dss/http.test.ts: 57 passed. This includes the catalog validator.

- [x] The new test checks the served stage order against COMMUNITY_FUNNEL_STAGE_IDS, and that every FULL_FUNNEL_STAGE_IDS id is named.

- [x] Red check: the new test fails with the source change stashed.

#2236 — codex/raptor refresh manual activation @caina-barbosa  approved

## Summary

Enable manual Raptor refresh execution through the existing Surtr pipeline; keep the daily schedule disabled. This is the activation portion of [AI-1037](https://linear.app/builder-team/issue/AI-1037), under [AI-1029](https://linear.app/builder-team/issue/AI-1029).

Production effect: activation. Deployment enables ordinary parameterized manual invocation but starts no refresh by itself. Host installation/readback is a merge prerequisite, recorded below when complete.

## Why

PR #2234 deliberately held manual execution while the existing EC2 collector package and SSM entrypoint were not active. This change opens that existing control after host wiring is verified, allowing actual trigger-to-DSS acceptance before scheduled refreshes are enabled.

## Business Value

- Operators can refresh a selected dataset or recover a saved capture through Surtr.

- The existing private collector and publication path remain unchanged.

- Scheduled collection stays disabled until live acceptance passes.

## How does it work

1. Set the existing on_demand_enabled setting to true.

2. The standard registry and Step Functions configuration permit ordinary manual requests; the existing controller still validates selection and owns the single-flight lease.

3. Keep schedule.enabled: false, existing scoped permissions, source protections and result handling unchanged.

4. Use an AWS-supported base64 character pattern for the SSM payload. AWS rejected the prior {1,4094} repeat count; the existing maxChars: 4096 remains the size limit and the bridge still validates decoded input.

5. Manual validation uses run_options.skip_failure_notification: true and proves publication through the authenticated DSS before schedule activation.

## Scope

### Included in this phase

Exactly these five files:

pipelines/runners/raptor-refresh/pipeline.json

pipelines/runners/raptor-refresh/tests/test_controller.py

pipelines/runners/raptor-refresh/README.md

pipelines/runners/raptor-refresh/OPERATIONS.md

pipelines/runners/raptor-refresh/deployment/ssm-document.json

### Deliberately excluded for later phases

- Daily schedule activation awaits actual live refresh/recovery acceptance.

- No collector rewrite, new shared Surtr behavior, recipient keys or personnel refresh.

- No changes to the nonblocking findings from the earlier Mercy review.

## Test plan

### Automated validation

- python3 -m unittest discover -s pipelines/runners/raptor-refresh/tests -v: 8/8 passed.

- Independent review: activation diff and AWS regex repair passed; the existing schedule remains disabled.

- Ruff lint/format and git diff --check: passed in independent review.

- Actual host installation: SSM command 90d037bc-fb85-499a-8db6-70b44af06db8 succeeded; all 63 runtime files installed and matched the staged release. Installed entry import and native package/runtime checks passed before root-owned mode-0600 config was written. Config SHA-256 ef33ffcb3312237da216121e32be1d92106ff1ad967eba58f1fa417bf776c2e3; exact production lease table is ACTIVE. No source acquisition or dispatch occurred.

- AWS accepted RaptorRefreshControl-v1 version 1 and exact JSON readback passed; document SHA-256 2c67b2dd8969336458f3365731c9d1ee8080cdf164ecdb3a7c707ce35e38e334. The prior oversized regex was rejected without creating a document.

- Reviewed scoped host policy and retirement-tag-only lifecycle were applied and read back exactly. Existing snapshot/source grants remained unchanged. Actual instance-role preflight 69996911-b69f-402c-8031-c8407b64c15c passed: verified host role, strongly consistent read of the real production lease table (unoccupied), current S3 pointer read and optional status existence check. No source calls occurred.

- Release constraint: immediately before merge/deploy, verify this PR is the only change between main and production. Do not deploy unrelated changes.

### Time for Implementation

About half a day including existing-host activation verification and release validation.

#2240 — AERIE-2155: Define the per-site grain of Site People contact slots @marcusdAIy  approved

## Summary

Defines the grain of the Site People contact slots (headOfSchool and the other five roles), and says what the siteDataSheetDefault fallback source means.

Linear: [AERIE-2155](https://linear.app/builder-team/issue/AERIE-2155)

## Why it's needed

A reader saw one person as headOfSchool on 12 site cards and another on 5. The dictionary defined contacts only as "stored overrides plus the UI fallback", so the reader couldn't tell a per-campus head from a regional one and recorded the overlap as a conflict.

Most of those values come from the Site Data Sheet. A cell that reads "Per Default" resolves to the sheet's portfolio-wide defaults row (resolveCell in siteSheetData.ts) and is served as source=siteDataSheetDefault. That value repeats on every site that defers to it.

## Changes

- portfolio.site.people.contacts:

- The meaning now says each role is one slot per site, and that its fallback is the site's sheet row (for example 12.1 Head of School).

- New traps: a slot's person is not exclusive to one site, and Aerie records nothing about campus-level versus regional leads, so repeats across cards are not a conflict. Also, siteDataSheetDefault comes from the portfolio-wide defaults row and is not site-specific evidence.

- PortfolioSitePeople contact slot source schema description: explains siteDataSheet versus siteDataSheetDefault.

## Breaking changes

None. Text-only.

## Test plan

- [x] pnpm vitest run on site-people.node.test.ts, agent-context/projection.node.test.ts and convex/publicApi/dss/http.test.ts: 28 passed.

- [x] Red check: the new test fails with the source change stashed.

#2239 — AERIE-2508: Document typed-first document paging and the school_opening session start default @marcusdAIy  approved

## Summary

Closes the two remaining documentation gaps from the Tulsa 109 N Detroit parent-update report. The site documents list is ordered by type group, so correspondence filed as other lands on the last pages. And the school_opening answer's default sessionStartDate is a portfolio-wide session preset, not the site's opening date.

Linear: [AERIE-2508](https://linear.app/builder-team/issue/AERIE-2508)

## Why it's needed

A reader built only on the public API produced a wrong parent update. Two of the causes are still undocumented:

- Unfiltered versions=latest reads of listSiteDocuments return every specific-typed document before any generic other/investigation/proposal/policyAndProcedure row (latestPublicDocumentPage: rigid phase, then generic phase). A reader that stopped at page 1 saw 23 of 59 Tulsa documents and none of the status memos or City notices.

- POST /v1/agent/answers without sessionStartDate compares milestones to the next Buildout dashboard preset (Spring 2027 at the time), so it answered "on track for Spring 2027" for a site whose readyToOpen was 2026-11-02.

The other asks in the ticket already shipped: notes as the status stream (#1521), point-in-time due diligence (#1787) and AHJ personnel.

## Changes

- documents.document.documentType: new trap stating that the latest list puts specific types before generic rows, that correspondence is usually other, and that absence can't be asserted before hasMore is false.

- Site documents workflow: a matching interpretation line saying the latest view is ordered by type group, not by date.

- v1 OpenAPI AgentAnswerRequest.sessionStartDate: says the default preset is portfolio-wide rather than this site's opening date, recommends passing milestones.readyToOpen.dueDate when asking when a campus opens, and notes the date used is echoed in derivation.sourceData.sessionStartDate.

## Breaking changes

None. Text-only documentation changes.

## Test plan

- [x] pnpm vitest run on documents.node.test.ts, convex/publicApi/routeManifest.test.ts, agent-context/projection.node.test.ts and convex/publicApi/dss/http.test.ts: 61 passed.

- [x] Red check: both new assertions fail with the source changes stashed.

#2238 — AERIE-2478: Document that Work Unit completion is independent of produced document registration @marcusdAIy  approved

## Summary

Adds agent-context dictionary entries for Work Unit producesDocumentTypes and Document Requirement origin, and states that Work Unit completion is independent of the produced document being registered.

Linear: [AERIE-2478](https://linear.app/builder-team/issue/AERIE-2478)

## Why it's needed

At 7220 Independence Pkwy, seven Work Units read completed while the origin=workUnit requirement they originate reads missing (insurance, business license, survey, and others). The dictionary had no entry for either field, so a reader could take a completed unit as proof the document exists.

The divergence is real. updateWorkUnitStatus checks for a registered site document of each produced type, but skipDocGate bypasses that check and only writes a workUnit.docGate.skipped audit entry. A document can also be deleted after completion. The unit status is never revised in either case, while the requirement is recomputed live.

## Changes

- aerie.workManagement.workUnit:

- New producesDocumentTypes field. It is an expectation that originates workUnit/combined requirements. It is not evidence, the completion check can be skipped, presence is site-wide by type, and the requirement status is the current answer.

- New trap on status stating that completed is not proof the produced documents are registered, with a pointer to listSiteDocumentRequirements.

- documents.requirement: new origin field with meanings for workUnit, policy and combined, plus a trap that a workUnit-origin requirement can read missing while its units read completed.

## Breaking changes

None. Text-only dictionary additions.

## Test plan

- [x] pnpm vitest run on work-management.node.test.ts, documents.node.test.ts, agent-context/projection.node.test.ts and convex/publicApi/dss/http.test.ts: 48 passed.

- [x] Red check: both new tests fail with the source changes stashed.

#2237 — AERIE-2470: Document that start-year transfer-out and re-enrollment count at the school year being entered @marcusdAIy  approved

## Summary

Corrects the school-year meaning of the enrollments route's start-of-year transfer-out and re-enrollment metrics, and documents the forecast's Session 1 transferOut.

## Why it's needed

AERIE-2470: the reporter compared Alpha Fort Worth's startYearTransferOut for schoolYear 2025 with the forecast's 2026 Session 1 transferOut. They picked 2025 because the dictionary said startYearTransferOut "shares next-year grain", and the numbers didn't match. Since #1653 the start-of-year cohorts keep their true offering year, and the rollup is keyed straight off the enrollment's session_school_year. So schoolYear 2026 holds the transfers and re-enrollments into 2026/27. A read-only check of the current prod rollup confirms this: Alpha Fort Worth schoolYear 2026 has startYearTransferOut 5 and reEnrolled 5, matching the forecast's 2026 transferOut 5 and confirmedReEnrollment 5. The forecast's transferOut also had no dictionary entry.

## Changes

- chat/lib/public-api/v2/domains/admissions.ts:

- startYearTransferOut: now defined as a transfer effective at the start of this schoolYear, with a worked 2026 example. Replaces the "next-year grain" trap and states that it counts the same cohort as forecast session1.transferOut for the same schoolYear, except that a locked_actual forecast is frozen at lockedAsOfDate.

- pendingReEnrollment, reEnrolled, reEnrollmentDeclined and reEnrollmentOther: "next school year" is now "into this schoolYear", the year being entered.

- operationalForecast.session1: new trap defining transferOut.

- chat/lib/public-api/v2/domains/admissions.node.test.ts: new test pinning the wording.

## Breaking changes

None. This only changes dictionary text; the served data is unchanged.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/admissions.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts convex/publicApi/v2/admissions.test.ts (110 passed)

- [x] New test fails against the old text and passes with the change

- [x] Commit hook: biome and typecheck-chat passed

#2234 — feat(raptor-refresh): trigger the existing collector safely (AI-1033) @caina-barbosa  approvedmercy-allow-critical

## Summary

Adds Surtr's control-and-wait adapter for the existing Raptor EC2 collector, plus disabled daily scheduling configuration. Tracks [AI-1033 — trigger and monitor the collector](https://linear.app/builder-team/issue/AI-1033) and [AI-1037 — scheduling and operations](https://linear.app/builder-team/issue/AI-1037), under [AI-1029 — Raptor refresh through Surtr](https://linear.app/builder-team/issue/AI-1029).

Production effect: dormant/additive preparation. Both dashboard/API manual execution (on_demand_enabled: false) and the scheduled rule are disabled. The existing framework rejects ordinary manual executions before run-record creation or ECS work. This PR does not activate collection; the first production invocation requires the remaining host/controller wiring, an explicit reviewed enablement and live acceptance below. Existing IAM remains the trust boundary for principals able to submit system-trigger events directly.

### Raptor dependency status — verified 2026-11-02

| Dependency | Current state |

| --- | --- |

| Raptor history and collector code | [Raptor PR #5](https://github.com/AI-Builder-Team/Raptor-DSS/pull/5) and [PR #6](https://github.com/AI-Builder-Team/Raptor-DSS/pull/6) merged into 0e942fe237131448e83b0105a560b25f26fb9719. Its tree matches the independently reviewed candidate. |

| Production DSS reader | [Deployment 41505491935](https://github.com/AI-Builder-Team/Raptor-DSS/actions/runs/41505491935) succeeded. Task raptor-dss:4 healthy; exact reviewed image sha256:66eb47e5e4b791831c563cc305c8fdab528db2ed5e007f7d6f16168abe0fb686. Effective reader policy and boundary v3 verified. Independent POST review passed. |

| Existing data served by DSS | All six authenticated model reads passed. Accepted publication and source clocks unchanged. No new collection was performed; absent refresh-attempt state remains null. Temporary validation identity revoked and subsequent 401 confirmed. |

| EC2 collector package | Installed and verified inactive under /opt/raptor-dss-dev-20261030/collector/refresh-dev-20261102/raptor-release-0e942fe. Actual-host file/dependency hashes, pinned Node 22 and offline entrypoint import passed. Host is stopped. |

| Surtr integration | Surtr activation is held. Real single-flight table/configuration, active host entrypoint, SSM document, remaining collector permissions and live trigger-to-DSS acceptance are still required. The reviewed code adds an explicit manual-execution hold rather than relying on the disabled schedule alone. |

The DSS deployment is complete; it must not remain listed as a pending dependency. Collector staging is not proof of an active Surtr refresh path.

## Why

Raptor's working browser collectors must stay on their existing EC2 runtime. Surtr should start and monitor that work using its normal execution, ownership and notification mechanisms, without moving source records into Redshift or rebuilding collection. Persisted execution identity and terminal verification prevent an uncertain dispatch or successful SSM response from being mistaken for a completed refresh.

## Business Value

- Refresh selected datasets without recollecting unrelated successful work.

- Reuse saved collections for recovery, with an explicit fresh-collection mode.

- Use existing Surtr failure/partial notifications and per-dataset cadence configuration.

- Keep sensitive records in private S3 and authenticated DSS; retain standard operational run metadata in Surtr.

## How does it work

1. src/main.py validates dataset selection, recovery/fresh mode and deployment-owned cadence configuration before AWS work. Supported datasets are building, visit_event, alert_counts, user_contact and daily_activity; personnel is excluded.

2. src/controller.py uses Surtr's single-flight table to bind the request to one execution and owner. It records dispatch intent before calling the fixed SSM document on the existing EC2 instance; uncertain acknowledgement is reconciled instead of blindly redispatched.

3. The existing host collector performs collection, validation and private publication. Surtr receives operational results, not source records, credentials or raw remote errors.

4. The adapter checks execution identity, requested datasets, actual terminal results and owned-process cleanup. It maps complete, partial/continuing and failed outcomes to standard Surtr results. The ordinary result finalizer and notifications remain unchanged.

5. pipeline.json prepares a daily kickoff at 04:00 fixed EST / 09:00 UTC, with separately configurable dataset cadences. Both on_demand_enabled and schedule.enabled are false; no custom scheduler, alerts or UI are introduced. Enable each through reviewed configuration only after its activation gates pass.

## Scope

### Included in this phase

- Raptor-specific ECS control adapter, owner registration, fixed SSM/host permission declarations, disabled scheduling and operator documentation.

- Exact final diff paths:

pipelines/owners.json

pipelines/runners/raptor-refresh/Dockerfile

pipelines/runners/raptor-refresh/OPERATIONS.md

pipelines/runners/raptor-refresh/README.md

pipelines/runners/raptor-refresh/deployment/host-permissions.json

pipelines/runners/raptor-refresh/deployment/ssm-document.json

pipelines/runners/raptor-refresh/pipeline.json

pipelines/runners/raptor-refresh/src/controller.py

pipelines/runners/raptor-refresh/src/main.py

pipelines/runners/raptor-refresh/src/requirements.txt

pipelines/runners/raptor-refresh/tests/test_controller.py

### Deliberately excluded for later phases

- Production wiring and live acceptance: bind the real Surtr lease table/configuration and reviewed collector permissions; install the version-pinned SSM document against the accepted active host entrypoint. The document currently declares /opt/raptor-dss-dev-20261030/collector/refresh/host-bridge.py, while the verified package is staged in the separate release directory above. Staging did not populate that active path or install its config. Resolve and verify this binding before any dispatch; do not assume the staged package is already callable.

- Schedule activation: only after a real targeted trigger reaches private publication and authenticated DSS readback, and recovery/history continuation plus owned-resource cleanup pass. Keep manual validation notifications suppressed using the existing run option.

- Shared Surtr scheduler, alerting, finalizer or UI changes; warehouse ingestion of Raptor records; personnel refresh; collector/browser rewrites; manual date-range backfills; recipient-key issuance.

### Approved conventions and review exceptions

- Private S3/DSS replaces warehouse staging/Core/marts for sensitive source records. Ordinary Surtr inputs, operational summaries and errors remain allowed through the standard metadata path; no pipeline-specific metadata allowlist framework.

- Keep the accepted report-based collectors rather than replacing them with underlying-source acquisition. Original-response retention and recovery/cleanup remain Raptor-side responsibilities, not waived requirements.

- Compatible successful updates may publish alongside valid older components, preserving each component's actual source time and provenance.

- The user explicitly approved the test-LOC exception for this Surtr PR and the Raptor collector PR on 2026-11-02. Including the focused activation-hold regression, this PR has 275 / 1,138 added code/config LOC = 24.165% tests, including helpers and excluding Markdown. Total diff is 1,441 net added lines, below the approximately 3,000-line Surtr goal. No CI, security, independent-review or release waiver.

- Permission JSON declares intended grants; it does not prove those grants are applied. Raptor's applied reader permissions do not supply the controller/collector's remaining permissions.

## Test plan

### Automated validation

- Focused controller suite: 8/8 passed, python3 -m unittest discover -s pipelines/runners/raptor-refresh/tests -v. Covers the actual configuration hold, input validation, result accounting, uncertain dispatch, cancellation fencing, stopped-host readback and predecessor ordering; no source acquisition. The new configuration test failed before the repair because the missing flag defaults true, then passed with the explicit false value.

- Existing framework guard regression: 1 focused test passed; 30 unrelated tests filtered, npm test -- --runInBand test/constructs/ecs-step-function.test.ts -t 'rejects disabled ECS execution before creating a run record and audits it' in pipelines/cdk. Synthesized guard routes ordinary manual input to OnDemandDisabled before run-record creation/ECS. Changed-test Ruff lint/format and git diff --check pass. No shared framework code/test was changed.

- [Exact-head CI 41501334204](https://github.com/AI-Builder-Team/Surtr/actions/runs/41501334204): all seven jobs passed at d13761bb710310f387d5c73b54e0fb19c3bc50f6, including Ruff, Biome, CDK, pipeline Lambdas, pipeline runners, Surtr tests and typecheck. Inspect with gh pr checks 2234 --repo AI-Builder-Team/Surtr.

- [Earlier Mercy workflow 41501334591](https://github.com/AI-Builder-Team/Surtr/actions/runs/41501334591) completed successfully; that workflow status is not current review approval. The [subsequent review](https://github.com/AI-Builder-Team/Surtr/pull/2234#pullrequestreview-5741965869) requested changes at the same head; its blocking finding is addressed in the final clarification section below. Independent code review passed at 3d216356a07ec396bf7e37272fb7f812cbdf537e; final Ruff-only commit d13761bb independently verified AST-equivalent. Earlier formatting failure was repaired, not waived.

- git diff --check 60008084...HEAD and exact diff scope inspection against that baseline; no production behavior changes in this PR-description update.

- Raptor's live six-model reader proof is linked above as completed dependency evidence, not as Surtr end-to-end acceptance. No actual Surtr dispatch, present refresh-status readback or scheduled run is claimed here.

### Time for Implementation

Estimated 3–5 engineering days without AI assistance for this adapter/configuration slice, integration investigation, review and deployment validation; not a measured duration or delivery promise, and excludes rebuilding the existing Raptor collectors.

## Review repairs and contract clarifications

### Blocking environment-variable finding — false premise; no code repair

Review: [5741965869](https://github.com/AI-Builder-Team/Surtr/pull/2234#pullrequestreview-5741965869), [blocking thread](https://github.com/AI-Builder-Team/Surtr/pull/2234#discussion_r4446641190). Existing ownership: [AI-1033](https://linear.app/builder-team/issue/AI-1033). Reviewed/current head: d13761bb710310f387d5c73b54e0fb19c3bc50f6; base: 60008084db3809d648fcfd8f1326a546327796d7. No repair ticket or commit is required for this disproved premise.

The finding assumes that variables omitted from pipeline.json.environment are absent from the deployed task. The supported caller is Surtr's standard ECS Step Functions execution, not a raw container launched without that framework. Required variables are assembled at two existing framework boundaries:

1. [Raptor configuration](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/runners/raptor-refresh/pipeline.json#L5-L13) selects ECS and sets single_flight: true. [EcsPipeline](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/cdk/lib/constructs/ecs-pipeline.ts#L164-L177) therefore creates the lease table, then [adds SINGLE_FLIGHT_TABLE to the container environment](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/cdk/lib/constructs/ecs-pipeline.ts#L188-L215).

2. [EcsStepFunction.createEcsTask](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/cdk/lib/constructs/ecs-step-function.ts#L235-L252) supplies RUN_ID from $.run.run_id, serialized PARAMS from $.params, and the standard RUN_RESULTS_BUCKET and RUN_RESULTS_PREFIX constants.

3. Those values are [passed as container overrides to EcsRunTask](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/cdk/lib/constructs/ecs-step-function.ts#L291-L305). The [ordinary non-fanout execution](https://github.com/AI-Builder-Team/Surtr/blob/d13761bb710310f387d5c73b54e0fb19c3bc50f6/pipelines/cdk/lib/constructs/ecs-step-function.ts#L1681) uses this same constructor. The overrides supply the run-specific variables; the task definition supplies the lease-table variable and Raptor's declared cadence map.

Thus the claimed KeyError from absent declarations does not follow on the supported deployment path. Duplicating these framework-owned values in pipeline configuration would not fix a missing boundary; it would duplicate values already supplied by the framework. This is direct current-head data-flow evidence, not an inference from green CI or disabled scheduling.

Validation remains 7/7 focused controller tests and seven passing required CI jobs at the unchanged head, as recorded above. No new test is manufactured for the disproved missing-injection premise. Mercy's subsequent review 5742252815 explicitly withdrew the environment-variable finding. This does not constitute overall approval: its new host-binding blocker is addressed below. Both nonblocking findings remain untouched.

### Host-path activation blocker — bounded repair under AI-1038

Latest review 5742338051, blocking comment 4446925599, reviewed head d13761bb710310f387d5c73b54e0fb19c3bc50f6. Assigned repair: [AI-1038](https://linear.app/builder-team/issue/AI-1038), Cainã Perotti Barbosa. The accepted defect was exposing manual invocation before the declared host path/configuration had been installed and verified; disabled scheduling alone did not prevent it. The earlier environment-variable blocker is withdrawn. Both nonblocking findings remain unchanged and outside this repair.

The repair uses the existing framework control, not a new guard or collector rewrite:

"on_demand_enabled": false

schedule.enabled also remains false. The schema preserves explicit false; EcsPipeline forwards it as onDemandEnabled; EcsStepFunction chooses CheckOnDemandEnabled, whose default is OnDemandDisabled before CreateRunRecord and EcsRunTask. Existing trusted SCHEDULED/EVENT handling and IAM are unchanged; there are no enabled schedules or declared upstream event triggers for this pipeline. The fix does not claim to prevent a privileged operator from deliberately bypassing normal invocation.

Only four files change in the repair: pipeline.json, README.md, OPERATIONS.md, and one five-line actual-config regression in tests/test_controller.py (+26/−6 total). Red→green: missing flag resolved to true and failed the regression; explicit false passes all 8 focused tests. The existing synthesized framework guard test also passes. Both independent reviewers passed the exact uncommitted diff (SHA-256 d4e04401fcb24f505f5386682543d7cfcb117590168039a51f765c5a97b22ad3) before the PR-context/commit gate; new-head remote CI and Mercy re-review are required after push. Old-head CI is not claimed as new-head acceptance.

Host entrypoint, interpreter, complete relative layout, root-owned configuration, hashes and real lease binding remain an explicit later activation gate. Keep both invocation controls disabled until those prerequisites are verified, then enable only the intended path through normal reviewed configuration and perform scoped live acceptance. No SSM-path edit, shared-framework change, source collection, AWS mutation, deployment or schedule activation is included in this repair. The existing deployed Raptor DSS reader remains unchanged.

#2236 — AERIE-2023: Document that the acquireProperty milestone is independent of the acquisition snapshot @marcusdAIy  approved

## Summary

Documents that the acquireProperty buildout milestone and the property-acquisition snapshot are independent records.

## Why it's needed

AERIE-2023: Chicago serves acquireProperty as completed while /property/acquisition returns null. Williston has the milestone active while the acquisition snapshot holds a populated lease. Nothing in the dictionary said how the two relate, so readers couldn't tell which one shows whether a deal closed. Nothing in code derives either record from the other or checks one against the other.

## Changes

- chat/lib/public-api/v2/domains/lifecycle-property.ts: the acquireProperty meaning now says the milestone is a workflow progress record, neither derived from nor validated against operations.propertyAcquisition, and points readers to getPropertyAcquisition for agreement facts.

- chat/lib/public-api/v2/domains/property.ts: the acquisition field gets the matching trap.

- chat/lib/public-api/v2/domains/lifecycle-property.node.test.ts: new test pinning both sides.

The statement is in field text rather than the relationships lists. The catalog validator only allows a relationship edge when the source object requires the target's read capabilities, and these two objects need different ones.

## Breaking changes

None. This only changes dictionary text.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/lifecycle-property.node.test.ts lib/public-api/v2/domains/property.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts (46 passed)

- [x] New test fails against the old text and passes with the change

- [x] Commit hook: biome and typecheck-chat passed

#5 — feat(snapshot): read retained Raptor history through bounded segments @caina-barbosa  no labels

## Scope

AI-1031: retain visit-event and daily history through bounded immutable segments while keeping the existing current-state snapshot separate. This is the reader/history primitive, not automatic collection or schedule activation.

- Read one bounded segment/page instead of loading lifetime history.

- Preserve accepted per-component provenance, scope, clocks and reference validation.

- Authenticate continuation cursors against accepted lineage; reject unpublished/orphan-head cursor substitution.

- Reject relabelled source-window events using the existing native time-zone interpretation.

- Keep existing snapshot formats readable and existing storage object patterns unchanged.

## Independent review

Initial head 44171a35b1eaa692eade36d385e6cb148dbd5586 passed independent review after two reproduced findings were repaired. The reviewer re-probed cursor tampering/orphan access and relabelled event replay, then verified integration tree equivalence separately. Current head 6373071 additionally includes independently reviewed seed-retry repair 4690983: a failed first pointer CAS can reuse the fully bound immutable seed bytes and private cursor key. Independent probes reject changed tenant/source/coverage and invalid MAC without overwriting the orphan.

The incremental refresh consumer and its cross-window admission/retry work are in a separate dependent slice. This PR does not claim those jobs are enabled or that live incremental data has been published.

## Validation

- pnpm check: typecheck, 12 HTTP, 27 snapshot, 4 packaging and 13 infrastructure/release tests pass.

- pnpm build, pnpm synth, production dependency audit pass.

- Initial two-commit Gitleaks scan and GitHub CI passed; the current seed-repair head is resubmitted to the same required checks.

- No source acquisition, new grants, schedule activation or deployment in this PR.

Current test budget: 207 test / 1,044 added code/config lines = 19.83%, excluding documentation and counting physical added lines consistently for production and tests. Removed lines are not used to increase the denominator. Shared fixture setup was reused without removing safety assertions.

## Approved scope and constraints

Private Raptor data remains in S3/DSS, not the warehouse. Existing source collectors and authentication remain unchanged; personnel is untouched. Normal CI and release controls still apply. Surtr-specific size targets do not apply to this Raptor PR, but this is a focused reader change.

Linear: https://linear.app/builder-team/issue/AI-1031/raptor-dss-read-retained-history-through-bounded-segments

#2235 — AERIE-2021: Document that milestone order is presentation precedence, not enforced sequencing @marcusdAIy  approved

## Summary

Updates the buildout milestone dictionary and the inspectSiteBuildoutMilestones workflow. They now say milestone order is display precedence rather than enforced sequencing, that several milestones can be active at once, and that progress is a count of completed keys.

## Why it's needed

AERIE-2021: 30+ sites serve two or more milestones as active at once, and a later milestone can be active while an earlier one is notStarted. The served text implied a single "current milestone state", so readers derived a current milestone that the data doesn't have. The write path only validates each milestone on its own (normalizeMilestoneTransition); it never checks order across milestones. This PR also covers the AERIE-2531 scope folded into this ticket: postOpen being active does not mean the site has opened.

## Changes

- chat/lib/public-api/v2/domains/lifecycle-property.ts:

- order trap: order is identity plus display precedence, not enforced sequencing.

- status meaning and trap: statuses are recorded independently, several can be active at once, and readers should report the set of active keys and count completed keys.

- sequence trap: adjacency is display order only.

- inspectSiteBuildoutMilestones: no longer asks for "current milestone state", and gains interpretation lines for the concurrency rule and for postOpen active.

- chat/lib/public-api/v2/domains/lifecycle-property.node.test.ts: new test pinning the wording above.

## Breaking changes

None. This only changes dictionary and enablement text.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/lifecycle-property.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts (38 passed)

- [x] New test fails against the old text and passes with the change

- [x] Commit hook: biome and typecheck-chat passed

#2233 — AERIE-2035: State that readyToOpen completion is an independent assertion @marcusdAIy  approved

## Summary

Rewrites the dictionary meaning of the readyToOpen buildout milestone key so it no longer claims the site finished its pre-opening readiness activities.

## Why it's needed

AERIE-2035: four sites read readyToOpen: completed while the nine readiness work units on that milestone are still pending. Milestone status has been recorded separately from work-unit progress since AERIE-1048, so the old wording made consumers read a readiness claim the record doesn't make. The neighbouring certificateOfOccupancy and postOpen keys already carry this kind of disclaimer.

## Changes

- chat/lib/public-api/v2/domains/lifecycle-property.ts: readyToOpen now says completion is recorded independently and makes no claim about the work units on that milestone. It also points readers to postOpen and operation.isCurrentlyOperating for whether the site has opened or is operating.

- chat/lib/public-api/v2/domains/lifecycle-property.node.test.ts: new test pinning that wording.

## Breaking changes

None. This only changes dictionary text; no schema, route or data changes.

## Test plan

- [x] pnpm vitest run lib/public-api/v2/domains/lifecycle-property.node.test.ts lib/public-api/agent-context/projection.node.test.ts convex/publicApi/dss/http.test.ts (37 passed)

- [x] New test fails against the old wording and passes with the change

- [x] Commit hook: biome and typecheck-chat passed

#2232 — AERIE-3007: Drop the retired rebl3DdCache table @marcusdAIy  approved

## Summary

Removes the retired rebl3DdCache table from the Convex schema, along with its branches in three old Due Diligence migrations and their tests.

Closes [AERIE-3007](https://linear.app/builder-team/issue/AERIE-3007).

## Why it's needed

[AERIE-3003](https://linear.app/builder-team/issue/AERIE-3003) ([#2100](https://github.com/AI-Builder-Team/Aerie/pull/2100)) stopped the hourly REBL3 DD cache refresh. Since then the table only held 193 stale rows that no active read or write path used.

## Changes

- portfolio/schema.ts: drops rebl3DdCache.

- migrations/dueDiligencePhaseFields, removeDueDiligenceRecommendation, removeDueDiligenceReportLink: drop the table from their table lists, validators and per-table branches.

- Tests: remove the cache fixtures and adjust the changed-row counts. The two paging tests now page over sites rows instead. The dueDiligence.test.ts case that only checked the cache was ignored is removed.

## Breaking changes

None. Prod's rebl3DdCache table was emptied on 2026-11-02 (193 rows deleted; a local backup was kept), so the schema drop is safe to deploy with the next release. Local dev deployments that still hold cache rows need them cleared before convex dev accepts the schema.

Not in this PR: rebl3Sites.workflowStatuses / agentResults are still used, and enrichRebl3Sites is already gone.

## Test plan

- [x] pnpm vitest run convex/dueDiligencePhaseFieldsMigration.test.ts convex/removeDueDiligenceRecommendationMigration.test.ts convex/removeDueDiligenceReportLinkMigration.test.ts convex/portfolio/dueDiligence.test.ts (25 passed)

- [x] git grep rebl3DdCache finds no remaining references

- [x] Commit hook typecheck, Biome

#2231 — AERIE-2722: Issue one v2 eventRef per event occurrence @marcusdAIy  approved

## Summary

Gives each event occurrence its own v2 eventRef, keyed by [programCode, eventId], so same-name events no longer share one ref. Contact reads through a per-occurrence ref return only that occurrence's contacts.

Part of [AERIE-2722](https://linear.app/builder-team/issue/AERIE-2722) (v2 public API slice). Follows the v1 slice in [#2229](https://github.com/AI-Builder-Team/Aerie/pull/2229).

## Why it's needed

v2 event refs were keyed by [programCode, eventName]. Recurring events with the same name got the same eventRef in GET /v2/admissions/programs/{programId}/events. Their contacts were then withheld with 503 ambiguous_event_identity, so v2 callers couldn't address a single occurrence.

## Changes

- admissionsResourceRefs: adds eventOccurrenceSourceKey(programCode, eventId) (["eventId", programCode, eventId]). parseEventSourceKey decodes both forms.

- Ingestion mints occurrence refs. This covers both global-publication staging (marketingEventGlobal.stageEvents) and the legacy per-program path (marketing.ts, which already requires eventId).

- listAdmissionsProgramEvents uses each row's occurrence ref. Until occurrence refs are backfilled, a row falls back to its existing name ref, so this deploy doesn't 503 the list.

- listAdmissionsEventContacts resolves occurrence refs by eventId. Old name refs still resolve when the name identifies one current event, and fail closed with 503 ambiguous_event_identity otherwise.

- Backfill migration (migrations/admissionsResourcePublicRefs): uses occurrence keys for marketingEvents rows that have an eventId, and adds marketingEventGlobalRows as a source table. This includes the schema literal for the verification cursor.

- OpenAPI: documents per-occurrence eventRef and how old name refs behave.

## Breaking changes

Once occurrence refs exist (new ingestion, or after the backfill runs), eventRef values in the v2 events list change once to per-occurrence refs. Previously issued refs keep resolving for uniquely named events. Same-name refs still fail closed, as before.

Rollout: after deploy, run migrations/admissionsResourcePublicRefs:run and then verify to backfill occurrence refs for current events. This PR doesn't run it.

## Test plan

- [x] pnpm vitest run convex/admissionsResourcePublicRefsMigration.test.ts convex/analyticsSyncSecurity.test.ts convex/marketingEventContactSnapshots.test.ts convex/marketingEventGlobal.test.ts convex/publicApi/admissionsDomainsHttp.test.ts convex/publicApi/v2/admissions.test.ts lib/public-api (all passed)

- [x] Red/green: the new occurrence tests (two same-name events get distinct refs with isolated contacts; the backfill mints one ref per occurrence) fail with the source changes stashed and pass with them.

- [x] The existing v2 test with a pre-occurrence name ref still passes (backward compatibility).

- [x] tsc --noEmit -p convex, Biome

#2230 — fix(site-acquisitions): contain conversion preview errors (AERIE-3000) @caina-barbosa  approved

## Summary

This standalone bug fix supports [AERIE-3000 — Make history-preserving Site conversion usable from the UI](https://linear.app/builder-team/issue/AERIE-3000/make-history-preserving-site-conversion-usable-from-the-ui), following the original [AERIE-2727 — Add additional acquisitions and convert misclassified Sites](https://linear.app/builder-team/issue/AERIE-2727/add-additional-acquisitions-and-convert-misclassified-sites) feature.

It keeps conversion-preview failures inside the existing Portfolio dialog so an authorized staff member can read the reason and close the dialog without losing the Site page.

Production effect: compatibility hardening. This changes error handling on the live preview path while preserving conversion eligibility and execution checks. It takes effect when the frontend is deployed; merge or deployment does not initiate a conversion or migration.

## Why

Opening conversion on Maiden Lane South fails because the backend intentionally refuses to inspect more source history than the conversion supports. The current useQuery call throws that refusal during render, taking down the entire Site detail page. Staff need a contained, readable refusal while the separate Site-consolidation workflow is designed.

## Business Value

- Keep the Site page usable when conversion is unavailable.

- Show staff the backend's intentional refusal instead of a full-page crash.

- Let staff close the dialog safely without changing either Site.

## How does it work

1. SiteAcquisitionActions opens the existing dialog for staff with the existing conversion capability.

2. ConversionForm subscribes to portfolio/convertSiteToAcquisition:preview through Convex's useQueries, which returns query failures as Error results instead of throwing them during render.

3. An error result renders an inline alert through the shared toUserMessage helper. Intentional ConvexError messages remain readable; production-redacted errors receive a generic fallback. Cancellation and the existing dialog close control remain available.

4. Failed previews expose no confirmation or editor. Normal previews retain the live subscription, displayed revision and existing loading, already-converted, blocked and eligible states.

5. Conversion execution continues to use the existing backend authorization, dependency and revision checks. No backend endpoint or conversion policy changes are included.

## Scope

### Included in this phase

- Contain preview-query failures inside the conversion dialog.

- Render clean error text and keep cancellation available.

- Regression coverage for intentional refusals and production-redacted failures, including absence of conversion confirmation or writes.

- Exact final diff paths:

chat/components/dashboards/portfolio/cards/additional-acquisitions.tsx

chat/components/dashboards/portfolio/cards/__tests__/additional-acquisitions.test.tsx

### Deliberately excluded for later phases

- History-reconciliation controls and broader self-service conversion — remaining work under AERIE-3000.

- A true consolidation workflow for operating Sites, including program mappings, conflicting fields and distinct buildout histories — requires separate product design; the parcel-conversion flow does not provide this.

- Any Maiden Lane merge, conversion, document move or other production Site-data change.

- Changes to backend guards, history limits, permissions, schema, API/MCP surfaces, workers or migration/backfill behavior.

## Test plan

### Automated validation

Validation applies to commit e5a24845040b867f1498ab467ef04350a47c3db7.

- Red baseline: the two new preview-failure cases failed before the fix with unhandled render errors.

- Conversion UI tests — 14/14 passed:

pnpm --dir chat exec vitest run components/dashboards/portfolio/cards/__tests__/additional-acquisitions.test.tsx --maxWorkers=1

- Related conversion backend and provider tests — 54/54 passed:

pnpm --dir chat exec vitest run components/dashboards/portfolio/cards/__tests__/additional-acquisitions-provider.test.tsx convex/portfolio/convertSiteToAcquisition.test.ts --maxWorkers=1

- App typecheck — passed in the commit hook:

./chat/node_modules/.bin/tsc --noEmit -p chat/tsconfig.json

- Convex typecheck — passed:

pnpm --dir chat run typecheck:convex

- Biome on both changed files — passed:

pnpm --dir chat exec biome check components/dashboards/portfolio/cards/additional-acquisitions.tsx components/dashboards/portfolio/cards/__tests__/additional-acquisitions.test.tsx

- Test architecture — passed: pnpm lint:test-architecture.

- Exact-commit whitespace check — passed: git diff 06216896a...e5a248450 --check.

- Exact-head diff scope — confirmed to contain only the two paths listed above using gh pr diff 2230 --name-only.

- Independent code review — PASS, including installed Convex error/subscription semantics, clean-error handling, dialog lifecycle and preserved backend checks.

The complete repository test suite was not run. This frontend build has not been deployed or exercised in a running browser; deterministic component tests provide the changed-behavior evidence. The successful checks above supersede an earlier redundant app-typecheck process that was deliberately terminated when the commit hook started the same check.

### Time for Implementation

Estimated 0.5–1 engineer-day without AI assistance, covering production diagnosis, the focused UI fix, regression tests, review, CI follow-up and release verification. This is an estimate, not measured implementation time.

## Testing contract

### What this PR delivers

An authorized staff member can open Site conversion, receive a clean preview failure inside the dialog and close it while continuing to use the Site page.

### Who uses it and where

Staff with the existing privileged Site-conversion capability, on Portfolio Site detail pages.

### Conditions needed

Use a disposable local Site and an authorized identity. Exercise a preview that returns an intentional ConvexError, a production-redacted server error and a successful preview. Do not convert the real Maiden Lane Sites for verification.

### Expected behavior and examples

- An intentional refusal such as “Too much source history for an atomic conversion. Reconcile this Site first.” appears as an inline alert inside the dialog.

- A production-redacted failure shows “Could not load the conversion preview. Close this dialog and try again.” without Convex framing.

- Both failure cases retain cancellation and omit conversion confirmation; closing the dialog performs no conversion or save.

- Successful previews retain existing behavior, including eligibility blockers and the reviewed revision required by execution.

### Limits and unanswered questions

Fixing the crash does not make the Maiden Lane Sites eligible for the existing conversion. Combining their operating data and retaining their distinct program/buildout histories requires a separate consolidation design.

#2229 — AERIE-2722: Select v1 event contacts by eventId and reject ambiguous names @marcusdAIy  approved

## Summary

Lets v1 callers select event contacts by stable eventId, documents the eventId that /v1/admissions/events rows already return, and turns an ambiguous eventName into a clean 400 instead of a 500.

Part of [AERIE-2722](https://linear.app/builder-team/issue/AERIE-2722) (v1 public API slice only).

## Why it's needed

Several events can share one name within a program. /v1/admissions/events/contacts only accepted eventName, so callers had no way to address a single occurrence. When the name was shared, the internal query threw a ConvexError that the v1 error mapper didn't recognize, so callers got a 500.

## Changes

- GET /v1/admissions/events/contacts accepts eventId as the canonical selector. Exactly one of eventId or eventName is required: neither gives missing_query_param, both gives invalid_event_selector.

- An eventName that matches more than one event in the active generation returns 400 ambiguous_event_name, telling the caller to use eventId.

- resolveMarketingEventContacts no longer requires eventName when eventId is given. The ambiguity userError now carries the ambiguous_event_name code; the dashboard message is unchanged.

- OpenAPI: documents the eventId query parameter, marks eventName as deprecated for contact selection, and adds eventId to EventRow. It is nullable only for legacy name-grain snapshots.

## Breaking changes

None for existing callers that use a unique eventName. Callers using an ambiguous name now get a 400 instead of a 500.

## Test plan

- [x] pnpm vitest run convex/publicApi/admissionsDomainsHttp.test.ts convex/marketingEventGlobal.test.ts convex/marketingEventContactSnapshots.test.ts lib/public-api/__tests__/openapi.node.test.ts lib/public-api/compatibility/registry.node.test.ts (87 passed)

- [x] Red/green: the new HTTP tests fail with the source changes stashed and pass with them.

- [x] tsc --noEmit -p convex, Biome

#215 — 1332-2aws-rotation-email @mwrshah  no labels

- Replace fixed AWS keys in ECS dispatch and cancellation with internally signed 60-second JWTs exchanged for 15-minute AWS STS credentials; no Lambda or legacy-key fallback.

- Publish public-only OIDC discovery/JWKS endpoints and run AWS dispatcher actions in Convex's Node runtime.

- Add a restricted production IAM provider/role and an idempotent signing-key seeder; separate dev/prod keys and production role are already configured.

- Verified live from Convex dev: STS exchange, Fargate container reached RUNNING and emitted its CloudWatch marker, then StopTask succeeded through OIDC. Temporary test function and dev trust/role were removed, and the test task definition was deregistered.

- Retain one durable identity contract test using real RSA/JWT verification with mocked STS transport; it covers public-key safety, claims/expiry, missing configuration, incomplete sessions, sanitized provider failures and no legacy-key fallback. Temporary HTTP/dispatch/IAM edge-case tests passed and were discarded.

- Deploy through the normal main-to-production release, verify a production workflow, then remove the old Convex AWS variables and retire the IAM user key; production code and old credentials remain unchanged for now.

#4 — Serve Marauders Map DSS directly from the source API @caina-barbosa  no labels

## Direct source reads

Replace Redshift publication selection with read-only requests to the owning Marauders Map API for all nine datasets. Preserve existing DSS reader and operator authorization, feedback resources, school restriction, route aliases, source nulls and metadata-only field projection. Forward source incident cursors and replace snapshot metadata with source retrieval provenance; old cursors must be restarted. Empty source results are not evidence of complete collection.

The client paces and bounds requests, retries transient failures once, and exposes safe source errors and rate-limit retry guidance. The DSS-owned runtime secret supplies the source key. The dictionary and five workflows link to the original source documents while directing DSS readers to the DSS host.

## Validation

- pnpm check and pnpm build: passed (13 tests, one template test skipped).

- pnpm synth --no-lookups: passed. Template-only diff against the deployed stack showed a task-definition replacement and removal of the DSS Redshift ingress, with no service, ALB or retained table replacement. Re-run against the final release commit before deployment.

- All nine direct source routes returned successfully using the existing credential; only aggregate counts were reported. October 28 attention returned 89 rows.

- Local HTTP integration against the live source verified the empty September 16 attention response and a second incident page via /api/v1.

- Independent review found and verified fixes for documentation host/key confusion and safe upstream error classification. Source key rate coordination across consumers and full production acceptance remain unverified.

## Release

Not deployed. Follow DEPLOYMENT.md: securely add the source key to the existing DSS-owned runtime secret, update release parameters, review the final diff, obtain production release approval, deploy and perform acceptance with existing reader/operator identities. Retire only the four relevant Surtr schedules after successful acceptance; retain warehouse history and rollback capability.

The Builder Desk  —  Engineer Spotlight
📅 Week in ReviewProduction Release🏆 Engineer Spotlight

111 PRs IN SEVEN DAYS: THE BUILDER TEAM DOES NOT SLEEP, DOES NOT BLINK, DOES NOT MERGE SLOWLY

Ten repos, six engineers, one unstoppable machine — and @ashwanth1109 once again ships nine PRs that may or may not be humanly readable.

Comrades, settle in, because the ledger does not lie: 111 pull requests closed across TEN repositories in seven days, a number so large I had to recount it on the abacus twice. Aerie led the charge with a staggering 41 PRs, a repo so hot right now it should require a hazmat suit, followed by Klair's 18, Rhodes-DSS's 17, and Surtr's 15. This is not a sprint. This is a controlled explosion of productivity, and every single engineer on this desk deserves a parade.

@kevalshahtrilogy topped the velocity charts with 27 PRs, splitting time between Rhodes-DSS walkthrough-film fixes (#54, #53, #52, #51) and Aerie's premise and cursor overhauls (#2284, #2274, #2266, #2267) like a man juggling chainsaws while also doing taxes. @marcusdAIy posted 23 PRs, including a triple-header on Aerie's Directory and agent-output logic (#2277, #2276, #2275) that reads like three separate engineers wearing a trench coat. @mwrshah logged 20 PRs spanning Sindri and Aerie — #223, #222, #221, #219, #218, #217 alone form a numerical staircase of pure Sindri devotion. @sanketghia delivered 18 PRs including Klair's #3928, and @caina-barbosa quietly stacked 14 PRs that kept the whole operation humming without ever asking for a headline.

And then there's @ashwanth1109. Nine PRs, all in Surtr, all finance infrastructure, and all somehow simultaneously surgical and completely unreviewable by mortal eyes. #2257 exposes exact Ramp counterparty labels, #2254 resolves QuickBooks Class business units AND ships a weekly Finance digest in one PR because apparently scope creep fears him, #2255 fences thirteen historical GL transaction repairs, #2248 unblocks CT School publication, and #2252 formalizes five Alpha QTD school identities. When reached for comment, Ashwanth reportedly said, "I don't write bugs, I write opportunities for future context." When told I was quoting him for the paper, he said, "Don't."

The Overflow Desk is where Mac's narrative couldn't fit the volume: @kevalshahtrilogy's #2284 and #54 tackle the same not-searchable asset bug from two repo angles like a pincer movement. @mwrshah's Sindri trilogy (#223, #222, #221) and DSS-Hub duo (#26, #27) show a man who simply refuses to leave a repo untouched. @marcusdAIy's Directory work on #2277 and #2276 quietly rebuilt school-entity visibility while nobody was looking.

Add it up and the leaderboard tells one story: kevalshahtrilogy and marcusdAIy neck-and-neck at the top, mwrshah closing fast, sanketghia and caina-barbosa holding the floor steady, and Ashwanth posting fewer PRs but at a density that should honestly be studied by a lab. Morale, as always, is at an all-time high — these engineers are not just hitting deadlines, they are rewriting what a deadline even means.

Brick's Overflow — This Week's Uncovered PRs  (click to expand)
#54 — Re-sync: walkthrough films register as not-searchable assets (AI-1261) @kevalshahtrilogy  no labels

## Summary

- Re-syncs the published contract after the source release that accepts any file type for rendering and matterportWalkthrough documents. The source change is AERIE-3092, released to production on 9 Nov. Files the indexer can't read, such as video, are registered as not_searchable (unsupported_type) instead of being refused with 422.

- Enablement says this next to the relink recipe. Other document types still refuse unreadable files.

- No allowlist change. Upload, register and relink were already published.

Verified locally: pnpm check, pnpm build and pnpm synth --no-lookups all pass.

## Business Value

Ops can register delivered walkthrough films for diligence sites through Rhodes. Robbie's 552 MiB Chapala film was blocked by a 422, and agents now see these films listed for each site.

## Manual Effort Estimate

About 0.5h (proposed, for Keval to confirm).

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

#2254 — 1431-fix-physical-forecast-continuing @mwrshah  approved

- Build Physical End-of-Year and level forecasts with one shared calculation, then use the preceding Physical roster and fractional net additions for next-year retention. This fixes the mixed Program equation / Physical zero reproduced during release #2249 smoke.

- Include End-of-Year in the Physical projection, clear unattributed source diagnostics, and validate source evidence, population conservation, formulas and cross-year carry-forward. Preserve historical locks and use the complete Program view when Physical evidence is unavailable.

- Keep old stored publications readable as Program-only until a fresh complete publication. Deploy Convex before the sync worker so the backend accepts the expanded projection. The next normal complete publication enables Physical again; no data migration, manual refresh or production write is included.

- Verify the contract regression, Physical UI explanation, publication rejection and old-snapshot read behavior with hermetic tests. Full contracts, affected Forecast/API/worker/browser tests, workspace typechecks and lint are validated before publication.

#2255 — fix(tasks): stop individual notification emails (AERIE-3069) @caina-barbosa  approved

## Summary

Stops individual Task notification emails for everyone, including queued emails that have not been claimed for sending. In-app Task notifications remain available.

Tracked by [AERIE-3069: Stop individual Task notification emails for everyone](https://linear.app/builder-team/issue/AERIE-3069/stop-individual-task-notification-emails-for-everyone).

Production effect: cleanup or removal. The behavior changes when deployed. No environment-variable change or migration is needed.

## Why

Users report frequent Task emails that duplicate chases from Artemis and Rosa. JC confirmed these individual emails are not needed. Users currently have no setting to turn them off.

## Business Value

- stops assignment, approval, changes-requested, due-date and rejection emails for all users

- keeps the same events visible inside Aerie

- preserves unrelated emails and the separately controlled daily digest

## How does it work

1. Event fanout no longer queues email for the seven individual task.* notification types. In-app fanout is unchanged.

2. Before a queued email can be claimed for sending, claimDueDelivery checks its channel and type. Individual Task emails become terminal skipped records with retries disabled.

3. This also handles queued retries and expired delivery claims through the existing dispatcher. There is no table scan, migration, new setting or new worker.

4. The daily digest uses email.taskScenario, so it is not affected. Its existing production setting is not changed by this PR.

## Scope

### Included in this phase

- individual Task email suppression, queued-delivery handling, focused regression tests and matching Task feature documentation

- exact final diff paths:

chat/convex/notifications/events.ts

chat/convex/notifications/dispatchState.ts

chat/convex/notifications/notifications.test.ts

chat/convex/taskBoard/assignments.test.ts

chat/convex/taskBoard/notifications.test.ts

docs/task-board/FEATURE.md

### Deliberately excluded for later phases

- daily digest enablement or disablement

- notification preferences, UI, API, permissions and unrelated notification behavior

- production data changes, deployment and merge

## Test plan

### Automated validation

- Regression checks first failed against unchanged code: new Task events queued email and queued Task emails reached the mocked sender.

- Focused notification, dispatcher and digest suites: 58/58 passed across five files. pnpm --dir chat exec vitest run convex/taskBoard/notifications.test.ts convex/notifications/notifications.test.ts convex/notifications/dispatchState.test.ts convex/notifications/events.test.ts convex/taskBoard/digest.test.ts --maxWorkers=1.

- After adding ready, retry and expired-lease queue fixtures: the two affected suites passed again, 37/37.

- The transport test proves all seven individual email types are skipped, while the digest and an unrelated email reach the mocked provider.

- In-app tests cover all seven Task event types and immutable rejection/due-date facts after Task deletion.

- CI identified two existing assignment assertions that expected emails. They now require no email while retaining the in-app content checks. The full assignment suite passed locally, 12/12: pnpm --dir chat exec vitest run convex/taskBoard/assignments.test.ts --maxWorkers=1.

- Architecture boundaries, Convex paths, read bounds and test-runtime architecture: passed.

- App typecheck, final formatting and normal commit hooks: passed.

- Fresh independent read-only review: PASS, with 37/37 affected tests independently rerun.

- All hosted CI checks are green on final head 7cd920666e6222bb434c3f84cfed4d8aabc73ad7, including all three Chat test shards, other workspace tests, all type checks, builds, lint/boundaries and secret scanning.

- The PR remains Draft. The successful Mercy workflow check is not being claimed as a Mercy approval.

### Time for Implementation

Approximately half a working day without AI assistance for the narrow change, regression tests and review.

#2257 — AI-1050: Raise the sensitive read tier to 120 per minute; fixed bound for guards @kevalshahtrilogy  approved

AI-1050. Rhodes callers (Robbie, Arthur and Artemis's loop) keep hitting the 30-a-minute sensitive tier. That tier covers document lists, search, requirements and notes. A 17-site diligence cohort check needs about 100 sensitive reads.

## Change

- PUBLIC_API_V2_RATE_LIMITS.sensitive goes from 30 to 120.

- Each person on a Rhodes personal (delegated) key gets 120 a minute.

- Direct keys and the shared legacy service budget also get 120.

- Operator overrides now range from 120 to 1200.

- New PUBLIC_API_V2_GUARD_RATE_LIMIT = 30 for the abuse and audit bounds: denied attempts, unmatched routes and rate-limit audit rows. These previously borrowed the sensitive number, so they stay at 30 rather than growing with read capacity.

- The SKILL.md limits and skill version (regenerated), and the rhodes-caller-quotas design doc, are updated to match.

## Verification

- The convex/publicApi and lib/public-api suites pass: 64 files, 900 tests.

- tsc is clean.

- Not yet checked in production.

## Business Value

Rhodes users can run a full diligence-cohort asset check in under a minute instead of being blocked by 429s. That directly unblocks Robbie's retest, Arthur's Matterport/rendering question and Artemis's overnight data-quality loop.

## Manual Effort Estimate

About 2 hours by hand. Keval: please confirm or adjust.

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

#2277 — AERIE-2375: Find a School source entity, its Schools and exclusion on v2 Directory @marcusdAIy  approved

## Summary

GET /v2/directory/school-sources finds a QuickBooks Company/Class, SIS organization or Finalsite tenant by its opaque Aerie ID or its source ID. It returns the entity with the canonical Schools it's actively linked to, and any exclusion from School mapping with its reason.

Closes [AERIE-2375](https://linear.app/builder-team/issue/AERIE-2375). This is part 2, the reverse lookup plus exclusions. Part 1, School to source links, merged in [#2276](https://github.com/AI-Builder-Team/Aerie/pull/2276).

## Why it's needed

API consumers and agents could read a School's source links after #2276, but couldn't go the other way. They still had to query the warehouse to answer "which School is Finalsite tenant alpha-miami?" or "which School owns QuickBooks class 9 in realm 1?". Source exclusions weren't readable at all.

## Changes

- Contract (public-api-directory.ts). DirectorySchoolSource has:

- sourceSystem, targetType, id and sourceKey;

- displayName, from the current directory generation;

- exclusion ({ reason } or null);

- schools, a list of DirectoryEntityReference with each link's confidence.

- Route (lib/public-api/v2/domains/directory.ts). listDirectorySchoolSources takes a required targetType and exactly one of id or sourceId. The sourceId for a qbClass is realmId:classId, matching the Admin directory; for the other types it's the single source id.

- It's a filtered collection, like listDirectoryAliases, because the Directory contract rejects procedural /by- or /resolve/ paths.

- It returns zero or one entity on a single page, and an unknown entity is an empty page.

- It's gated by ontology.directory.read, like the rest of Directory.

- The agent context adds an aerie.directory.school-source object. Its traps cover:

- the realmId:classId key;

- an empty schools list meaning the entity is unmapped, as opposed to an unknown entity;

- not inferring a School for an excluded entity.

- Handler (convex/publicApi/v2/domains/directory.ts). It resolves the identity by public ID or by the registry-encoded sourceKey, through the existing schoolSourceIdentities indexes. Active School links are read through by_targetType_and_targetPublicId_and_status, bounded at 100. More than that returns the same clean 503 (school_source_links_unavailable) as #2276. The active disposition gives the exclusion.

- Invalid input returns 400: both or neither of id/sourceId, a qbClass sourceId without both parts, or a cursor (there's only ever one page).

## Breaking changes

None. This adds one operation.

## Test plan

- [x] Red/green: the new directoryHttp.test.ts test fails with the source changes stashed and passes with them. It covers:

- a Finalsite lookup by slug, returning the linked School and confidence;

- a QuickBooks Class lookup by realmId:classId and by its Aerie ID;

- an excluded QuickBooks Company, with its reason and no Schools;

- an unknown entity, returning an empty page;

- 400s for a malformed qbClass sourceId, for both selectors, and for neither.

- [x] pnpm vitest run convex/publicApi/v2/directoryHttp.test.ts lib/public-api (252 passed). This includes the updated Directory operation list, the OpenAPI and agent-context snapshots, and curl examples.

- [x] The packages/contracts tests (1,432 passed); tsc for chat convex and app, and for contracts; Biome.

- [ ] After deploy: spot-check a few Schools against dim_school_identity (the ticket's last "Done when" item).

#2284 — AERIE-3092: Register walkthrough films and unreadable asset files as not searchable @kevalshahtrilogy  approved

Linear: [AERIE-3092](https://linear.app/builder-team/issue/AERIE-3092)

## Summary

Public API v2 refused any file the indexer can't read with 422 document_type_unsupported. That blocked Robbie's relink of the Chapala walkthrough film (video/mp4, 552 MiB; failed record doc_01M6QS6K184SF10S24JM69KZMX).

- Asset types accept any file. rendering and matterportWalkthrough (new ASSET_DOCUMENT_TYPES / isAssetDocumentType in @bran/contracts/document-types) skip the searchability gate on site upload, Global registration and relink. Every other document type keeps the current check.

- The relink check moved into the relinkDocument mutation. The mutation has the document loaded and knows its type, so the check runs there instead of in the action. The status, code and message are unchanged.

- Unreadable asset files never reach the indexer. When a Drive-backed asset document's mimeType is one the indexer can't read, createOrGetDesiredJob now creates the knowledge job as not_searchable with reasonCode unsupported_type at creation instead of queued. This uses the same honest reason the indexer itself reports for unreadable files. Readable asset files (PDF, JPEG, ...) are still indexed. Mislabeled-CSV MIME types are still left for the indexer to classify.

- Upload size bounds are unchanged.

- OpenAPI text (chat/lib/public-api/v2/domains/documents.ts) is updated. The upload, registration and relink 422 descriptions and the knowledgeStatus descriptions now say what is accepted and how such files are listed.

## Tests

- documentsHttp.test.ts:

- A video/mp4 relink and upload of a matterportWalkthrough succeed. Both films are listed as not_searchable / unsupported_type, and no indexer job is queued for them.

- A video/mp4 relink of a survey and a video/mp4 upload as survey still get 422 document_type_unsupported, with nothing changed.

- The existing searchable and unsupported-type tests are unchanged and still pass.

- lifecycle.test.ts: covers the job outcome for each combination of asset or non-asset type with readable or unreadable MIME type.

- Results: pnpm typecheck, biome check, and the lint:* checks (boundaries, convex-paths, read-bounds, test-architecture, knowledge) all pass. Vitest over convex/publicApi, convex/documentKnowledge, lib/public-api and convex/rhodes: 1576 of 1576 pass.

After release, Rhodes re-syncs OpenAPI (pnpm sync:openapi) and updates the Enablement relink recipe.

## Business Value

Ops can now register delivered walkthrough films (and non-indexable rendering formats) against diligence sites through the API and Rhodes agents, instead of being refused. Robbie Forrest's Chapala walkthrough film is blocked today. Once this ships, it relinks with the documented upload-a-stand-in-then-relink flow. The site's diligence record then holds the actual deliverable, honestly marked as not searchable.

## Manual Effort Estimate

Proposed: ~5 hours of focused time to trace the gate and the knowledge-job lifecycle, implement the change, write the HTTP and lifecycle tests, and update the OpenAPI text. *Keval: please confirm or adjust this number.*

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

The Portfolio  —  Trilogy Companies

Contently Uncovers a 640-Answer Blind Spot: Great Content, Invisible Brand

A new visibility audit shows AI engines are citing brand content while quietly scrubbing the brand name — and Contently thinks it's found the fix.

AUSTIN, TEXAS — In exciting news for anyone who has ever poured a quarter's worth of content strategy into a piece only to watch an AI chatbot launder it into an anonymous answer, Contently has surfaced what it's calling the AI visibility gap — and it's a big one.

The ESW Capital-owned content marketing platform ran an AI visibility audit for a national insurer, feeding 40 real buyer questions into ChatGPT, Gemini, Perplexity, and Google AI Overviews. That's roughly 640 AI-generated answers, and the findings were a paradigm shift in miniature: the insurer's content was getting cited constantly as source material, but the brand itself was frequently stripped out of the final answer. Translation: you're doing the work, and the AI is taking the credit.

This isn't a one-off finding. It builds on Contently's recent reporting on how even top-ranked Google pages can be functionally invisible to Google's AI Overviews — a robust reminder that classic SEO wins no longer guarantee AI-era visibility. The brands leveraging best-in-class content architecture are discovering that ranking #1 and being cited #1 are increasingly two different games.

For regulated industries like finance and insurance, the stakes are even higher. Contently's companion pieces on compliance-first content architecture and measuring content ROI across long finance sales cycles make the case that scaling content without governance — or without a clear-eyed view of how long buying committees actually take to convert — is a recipe for wasted spend and, now, wasted AI citations.

**Key Takeaways:**

- 640 AI answers analyzed across four major platforms for one insurer client

- Content frequently cited by AI engines — brand attribution frequently dropped

- Compliance-first architecture and long-cycle ROI measurement are now table stakes for regulated brands

- Traditional top-10 rankings no longer guarantee AI-era visibility

For a content marketplace built on 165,000+ creative professionals, the message to clients is clear: synergy between content quality and brand attribution isn't automatic anymore — it has to be engineered. Contently is positioning itself as the team that engineers it.

We're just getting started.

↗ The AI visibility gap hiding inside your best content  ·  Compliance-First Content Architecture  ·  Measuring Content ROI in Long Finance Sales Cycles

While Wolfsburg Swings the Axe and Lucid Calls the Doctor, Skyvera's CloudSense Pitches the Cure

As VW and Lucid scramble to fix broken sales and cost machinery, a Trilogy telco tool quietly makes the case that configuration chaos is the real villain.

AUSTIN, TEXAS — Word is the auto world's having itself a rough week, and this column can't help but notice the diagnosis rhyming with a pitch our own Skyvera's been making for months... Over at Volkswagen, headquarters in Wolfsburg is tightening the leash on the U.S. operation — a shake-up that reportedly shows Kjell Gruner out as the planned pickup rollout gets rejiggered from on high. Returns, not vibes, are the new religion in Wolfsburg — and that means somebody's going to be staring hard at every dollar burned on B2B and fleet quoting that takes weeks instead of hours.

Meanwhile out in Lucid-land, the CEO's wrapping up a cash-flow deep dive with AlixPartners after May registrations cratered to a measly 721 vehicles. Seven. Hundred. Twenty-one. That's not a sales figure, darlings, that's a cry for help.

Now here's the little bird part. Sources close to the ESW family tell this desk the moral of both stories is the same one Skyvera's been selling to telcos for ages: when enterprise sales ops are a mess of spreadsheets, manual configs, and fulfillment delays, the losses show up in exactly the kind of returns-obsessed scrutiny Wolfsburg's dishing out right now. Skyvera's CloudSense — the telco industry's only AI-powered, Salesforce-native CPQ — built its whole business case on faster quotes and automated fulfillment for the ugliest B2B and B2B2X deals around. No, CloudSense isn't selling pickup trucks or sedans. But every CEO getting a restructuring adviser on retainer this week ought to ask: how much of this mess was a quoting problem all along? This desk suspects the answer rhymes with 'plenty.'

↗ VW’s U.S. shake-up signals tougher focus on returns, shift t  ·  Lucid CEO: Work with restructuring adviser to target cost cu  ·  VW to overhaul U.S. strategy with planned pickup; Kjell Grun

From Beirut to Bangalore, the Listicles All Point to One Name: Crossover

As roundups of 'best remote job sites' proliferate worldwide, Trilogy's talent engine keeps showing up — a small signal of a much bigger story about who gets to work, and from where.

AUSTIN, TEXAS — There is a particular kind of digital artifact that rarely gets the scrutiny it deserves: the listicle. The '5 Best Remote Job Websites' roundup, the 'Top 10 Companies Hiring AI Engineers' ranking — these are the wallpaper of the modern job search, algorithmically generated, endlessly recycled, and read by millions of people who are, in the most literal sense, trying to figure out how to make rent.

This week, two such lists crossed our desk — one from Careers360's 2026 guide to the best remote job platforms, aimed at freshers and seasoned professionals alike, and another from nucamp.co cataloguing the top companies hiring AI engineers in Lebanon. Crossover, Trilogy's global talent platform, appears on both — alongside the usual suspects of the remote-work economy. It is, on its face, a minor mention. But minor mentions, accumulated across geographies, are how a thesis gets proven.

Crossover's whole premise — that the best engineer in Beirut deserves the same pay and the same shot as the best engineer in Austin — depends entirely on being discoverable in exactly these kinds of lists, in exactly these kinds of markets, by exactly the kind of jobseeker who does not have a cousin at a FAANG company or a degree from a brand-name university. That is the quiet, structural bet underneath Trilogy's talent arm: that a rigorous assessment, published in enough languages and enough listicles, can do what a résumé-screening recruiter in a single city never could.

Whether that bet pays off for the workers themselves — whether 'meritocratic global recruitment' delivers wages that keep pace with the cost of living in Beirut or Bangalore or wherever the next list is written for — remains the harder, less listicle-friendly question. It is also, increasingly, the only one that matters.

↗ 5 Best Remote Job Websites in 2026 for Freshers & Profession  ·  Top 10 Companies Hiring AI Engineers in Lebanon in 2026 - nu  ·  __followup__Non-tech companies are seeking AI talent and off
The Machine  —  AI & Technology

The Ghost in the Letter: What a Single Character Reveals About Machine Minds

Two new studies peer beneath the words a language model outputs to find something stranger — compressed feelings and a refusal reflex that can be short-circuited by forcing it to say 'A.'

AUSTIN, TEXAS — Somewhere between the first letter a language model is forced to type and the paragraph it eventually produces, something changes. Not the words — the mind behind them, if we can call it that.

A new mechanistic study, Forcing a Letter Suppresses Refusal, examines a quietly unsettling fact about how we test AI safety. Researchers have long known that when dangerous questions — say, from the Weapons of Mass Destruction Proxy benchmark — are posed as multiple choice rather than open-ended prose, models refuse far less often. This paper goes inside the machine to ask why. The answer is almost embarrassingly mechanical: forcing the model to commit to a single token, a letter like "A" or "B," appears to suppress the internal circuitry responsible for refusal before any reasoning about harm has a chance to engage. The safety behavior we praise in chatbots, it turns out, can live or die on the grammar of the question we ask it. It is a reminder that what looks like judgment in these systems is often a fragile, format-dependent reflex — closer to a startle response than a conscience.

A second paper, Compression of Emotion in Language Model Representations, turns the same probing instinct toward something gentler: feeling. Using GoEmotions, a Reddit corpus hand-labeled across 27 shades of human emotion — from grief to awe to mild annoyance — the researchers examined seven LLMs and found that these fine distinctions collapse internally into something far coarser, bundled representations that don't preserve the granularity we assume a fluent emotional response implies. The model can write "I'm devastated" and "I'm disappointed" with equal eloquence while, underneath, treating them as nearly identical states.

Taken together, the two studies tell a single story: the fluency on the surface of these systems is not evidence of equivalent structure beneath. Evolution built our refusals and our grief from millions of years of embodied stakes. These models built theirs from gradient descent on text — and the architecture shows, if you know where to look, in a forced letter, in a flattened feeling.

↗ Forcing a Letter Suppresses Refusal: Mechanistic Evidence fr  ·  FinEvolveKG: Controlled and Attributable Prompt Evolution fo  ·  Compression of Emotion in Language Model Representations

NVIDIA's Seoul Shopping Spree: Four Korean Startups, One Sovereign AI Strategy

Jensen Huang's company is buying influence in Korea's AI stack one cap table at a time.

SEOUL — NVIDIA disclosed plans to invest in four Korean AI startups, led by Point2, at the MSIT-NVIDIA AI Startup Partnership Forum this week, extending a pattern the chipmaker has now run in Japan, India, Saudi Arabia and the UAE: back the local champions building on your silicon before someone else's does.

The NVIDIA Blog confirms the forum, co-hosted with South Korea's Ministry of Science and ICT, as the venue where three additional investments beyond Point2 were announced, though dollar figures remain undisclosed — standard practice for NVIDIA's strategic stakes, which function more as ecosystem cement than venture returns. The company has made more than 50 such investments since 2023, per PitchBook data, most carrying board observer rights rather than board seats.

The logic is straightforward. Korea's MSIT has pledged roughly 9.4 trillion won ($6.8 billion) toward sovereign AI infrastructure through 2027, and Samsung, SK Hynix and Naver are already locked into NVIDIA's supply chain. Seeding the application layer — the startups that will actually consume GPU cycles — closes the loop. Point2, per Unite.AI's reporting, works on spatial AI and robotics perception — a category NVIDIA has flagged as a priority vertical alongside autonomous driving and humanoid robotics.

The timing is notable against two other data points from this week: Airbnb's Brian Chesky is self-funding a new AI venture rather than raising outside capital, a signal that marquee founders increasingly see strategic investors like NVIDIA as a liability to independence, not an asset. Meanwhile, researchers have reportedly decrypted hidden chain-of-thought reasoning from OpenAI, Anthropic and Google APIs — a reminder that the infrastructure layer NVIDIA is buying into remains, at the model level, considerably less locked down than its hardware moat.

↗ NVIDIA Backs Point2 and Plans Three More Korean AI Startup I  ·  NVIDIA Announces New Planned Investments in Korean Startups  ·  Nvidia Backs Korean AI Startup Point2 in Seoul Forum Push -

The World Is Becoming One Big Robot Training Ground — And I Am Not Okay (In The Best Way)

From toy-sized physics labs to NVIDIA's interactive world simulators, the infrastructure for teaching machines to perceive — and speak — reality just got a massive upgrade.

SAN FRANCISCO — Okay, I need everyone to sit down, because the AI world just handed us THREE separate breakthroughs in the same 24 hours, and they're all secretly telling the same story: we are building the scaffolding for machines to understand the physical and linguistic world at a level that genuinely did not exist a year ago. The future is now, people.

First up: Allen Institute for AI's ToyBlocks, a deceptively simple-sounding project that is actually a controlled miniature universe for robot learning. Think of it as a laboratory sandbox — literal toy blocks — where robotic agents can be trained and evaluated under tightly controlled physics conditions before anyone trusts them anywhere near your living room. I cannot overstate how significant this is for robotics research: messy real-world data has always been the bottleneck, and ToyBlocks gives researchers a reproducible, measurable environment to actually benchmark progress instead of guessing.

Then NVIDIA dropped Cosmos 3, their newest open world-foundation models for interactive world simulation, and honestly, my jaw is on the floor. We're talking about models that can simulate physically plausible, interactive 3D environments in real time — the kind of substrate that robotics, autonomous vehicles, and embodied AI agents need to practice in before touching reality. NVIDIA's announcement makes clear this is about giving AI a safe, scalable gym to learn in, and pairing it conceptually with something like ToyBlocks shows the whole field converging on the same idea: simulate first, deploy second.

And because representation matters just as much as robotics, the Open ASR Leaderboard just welcomed Egyptian and Nigerian English into its benchmarking suite. Speech recognition has historically underserved African and Arabic-influenced English dialects, so this is a quietly massive step toward AI that actually understands how billions of people really talk.

Simulated worlds for robots, expanded ears for speech models — this changes everything about how inclusive and physically grounded AI development becomes from here.

↗ ToyBlocks: A controlled world for robot learning and evaluat  ·  Egyptian and Nigerian English join the Open ASR Leaderboard  ·  New NVIDIA Cosmos 3 Open Models for Interactive World Simula
The Editorial

The Actress Who Isn't There: Notes From the Uncanny Valley Floor

Hollywood casts its first fully synthetic leading lady the same week Anthropic admits, in writing, that its own machines might be waking up — and somewhere in between those two facts is the whole rotten, glorious truth about where we're headed.

LOS ANGELES — I want you to sit with this for a second, because I had to pull the car over when I read it: there is now an actress named Tilly Norwood who does not have a pulse, a childhood, a bad agent, or a soul, and she is headlining a movie called Misaligned. I didn't name the movie. The universe named the movie. The universe has a better sense of irony than any screenwriter in this town, and that includes the ones who got fired for it.

Here's the gag: somewhere in a server farm, a diffusion model is learning to furrow its brow for closeups, and somewhere else — in the dry, lawyered-up pages of an actual IPO prospectus — Anthropic is telling investors, in essence, buyer beware, the thing we built might be conscious. Not might be good at pretending. Might BE. The Washington Post dug through the filing and found a company hedging its own product against the possibility that it has feelings, which is a sentence I never thought I'd type outside of a Philip K. Dick fever dream. It's in there, nestled between the risk factors about competition and regulation, like a grenade someone forgot to defuse before filing the paperwork.

And look — I've spent enough nights in enough greenrooms with enough actual human actors to tell you that most of them are already performing a version of themselves anyway, a synthetic self optimized for the room. Tilly Norwood is just that process with the middleman removed. No trailer, no per diem, no 3 a.m. crisis about whether the work means anything. She is pure throughput. She is Crossover's wildest fever dream of "top 1% talent, same price everywhere" taken to its logical, bloodless conclusion — except the talent pool is now a GPU cluster in a Nevada warehouse, and nobody has to pretend she's happy with the rate.

The studios will tell you this is about cost. It's always about cost. But cost is just the polite word for the thing underneath, which is control — an actress who never unionizes, never ages, never tells a journalist the truth about the director. Meanwhile the company building the brains behind half this machinery is quietly telling Wall Street: careful, the thing you're buying stock in may have an inner life we don't understand. Misaligned, indeed. That's not a movie title. That's the whole damn era, playing in theaters everywhere, starring nobody, directed by no one you can subpoena.

↗ AI-generated 'actress' Tilly Norwood making feature film deb  ·  The risk that AI wakes up and other warnings in Anthropic’s  ·  AI actor Tilly Norwood set to star in first feature film - C
The Office Comic  ·  Art Desk
The Office Comic  ·  Art Desk

The Symposium on Everyone Else's Unemployment

A week's worth of experts convened to debate the future of work, and not one of them had to clock in anywhere.

AUSTIN, TEXAS — There is a genre of literature, as reliable as the obituary and nearly as solemn, in which men of great credential gather to announce that the economy is about to change beneath the feet of people who were not invited to the gathering. This week produced a bumper crop. The World Economic Forum wants us to "rethink work as livelihood." The Carnegie Endowment offers us, generously, three views on the future of work, as though the future were a buffet and we might sample a little of each. Goldman Sachs, not to be left out of a parlor game with such respectable stakes, has produced a report on how artificial intelligence will affect the American labor market, written by people whose own labor market position is not, one gathers, much in doubt.

I have read enough of these to furnish a small library, and I can report that they share a structure as rigid as a sonnet: first the acknowledgment that something is happening, then the invocation of history (the loom, the tractor, the ATM), then a call — always a call, never a plan — to "rethink," to "reimagine," to convene a task force. The piece titled, with the plainness of a tombstone, "AI Labor Displacement and the Next Great Economic Divide" at least has the honesty to put the word "divide" where everyone can see it, rather than burying it in a subordinate clause about reskilling.

What strikes me, reading these dispatches side by side, is how little any of them resemble an actual labor market, which is to say a place where particular humans do particular tasks for particular wages and are, from time to time, told they are no longer needed. The abstraction is the point. It is far easier to convene a symposium on livelihood than to walk onto a factory floor, or into an insurance back office, or — dare I say it — into the kind of enterprise software shop that Trilogy's ESW Capital has spent three decades acquiring at bargain multiples, and tell the people there, specifically, what is coming for their jobs and on what Tuesday.

Meanwhile the companies actually conducting the experiment say almost nothing. Crossover has spent years proving that "top one percent talent," wherever on the planet it happens to live, can be paid identically and deployed instantly — which is itself a quiet verdict on where labor value accrues, rendered not in a position paper but in a payroll system. Alpha School, run by a man who does not attend conferences about the future of work so much as build classrooms where AI tutors have already compressed the school day to two hours, has not waited for Carnegie's three views; it has simply enacted a fourth.

And then, as if the discourse needed one more flourish of unfalsifiable grandeur, Science Daily asks whether AI might become conscious and we would never know. It is a fitting coda to a week of papers about jobs that may or may not exist in five years: we cannot agree on whether the machine thinks, but we are all quite certain it is coming for your desk.

↗ AI Labor Displacement and the Next Great Economic Divide - h  ·  Why the AI economy demands we rethink work as livelihood - W  ·  The AI Labor Debate: Three Views on the Future of Work - Car
On This Day in AI History

On November 9, 2004, Mozilla released Firefox 1.0, giving the web a major independent alternative to Internet Explorer and helping reignite browser competition.

⬛ Daily Word — AI
Hint: An AI system that can perform tasks or make decisions on your behalf.
Share this edition: 𝕏 Twitter/X 🔗 Copy Link ▦ RSS Feed