## Title
feat(alpha-ops): connect authenticated storage endpoints (AI-1087)
---
## Summary
This is Phase 4 of the four planned backend slices in [AI-1057 — Migrate Ops Portal storage to Rhodes](https://linear.app/builder-team/issue/AI-1057), tracked under [AI-1087 — Prepare the production target and inactive historical copy](https://linear.app/builder-team/issue/AI-1087). It connects the accepted portal-record and transfer operations to two authenticated HTTP endpoints, building on the schema, codecs and internal Chat/control operations from the preceding slices.
Production effect: activation. Deployment registers /alpha-ops/v1/application and /alpha-ops/v1/transfer in Aerie's existing router. Access retains the accepted separate tokens, source and destination checks. The code starts no import, scheduled synchronization or provider action, and changes no portal database setting. Deploying the combined series and importing production data remain separate, user-controlled steps.
---
## Why
The previously added internal storage functions need the accepted external interface before the existing portal adapter and transfer commands can use them. This slice preserves complete collection reads, staged saves and transfer operations while adapting their function references to Aerie's module paths. Composing the existing router keeps Aerie's unrelated endpoints in place.
---
## Business Value
- Gives the existing portal adapter a compatible Rhodes storage endpoint.
- Supports the reviewed initial copy, final update and recovery procedures without automatically running them.
- Preserves source content and complete reads while users save later changes.
---
## How does it work
1. Root http.ts calls registerAlphaOpsRoutes to add the two Alpha Ops routes alongside existing Aerie routes.
2. The handler reuses Aerie's bearer-token validation and constant-time comparison. It checks the configured source/destination and retains application-versus-transfer operation permissions before calling storage functions.
3. general.ts opens a complete collection version for a reader and returns its records in batches. An existing reader keeps its original version when a later save is published.
4. generalWrite.ts stages ordinary portal saves and publishes their complete content. storage.ts provides the accepted transfer operations, including the AI-1083 update/removal behavior.
5. Internal references use the alphaOps/ namespace and Aerie's generated registration helpers. Source fields, tokens, metadata, ordering and existing errors remain governed by the reviewed upstream implementation; no new product policy is introduced.
---
## Scope
### Included in this phase
- Accepted general-record reads/writes, transfer storage and authenticated HTTP composition.
- Focused HTTP tests using the exact captured collection and SQL envelope; an ordinary edit to the copied collection checks old/new read separation.
- Generated API declarations and the updated backend guide.
- Exact final diff paths:
chat/convex/_generated/api.d.tschat/convex/alphaOps/general.ts
chat/convex/alphaOps/generalWrite.ts
chat/convex/alphaOps/http.test.ts
chat/convex/alphaOps/http.ts
chat/convex/alphaOps/storage.ts
chat/convex/http.ts
docs/alpha-ops-ingestion.md
Measured diff against updated main: 2,756 additions / 11 deletions = 2,767 changed lines. Tests: 204 lines (7.3726%); runtime: 2,523; generated declarations: 8; root-router integration: 2; documentation: 30. These counts were verified against main after PR3 #2289 merged.
### Deliberately excluded for later phases
- Production deployment, environment configuration, initial import, final data update and portal switch — separately authorized operations; none runs on merge.
- Maintenance-script adaptations — still deferred pending Sam's usage confirmation.
- UI changes, new permissions, product improvements, CI configuration changes and cleanup of the original database adapter — outside this slice.
---
## Test plan
### Automated validation
- New HTTP tests 3/3 passed: pnpm --dir chat exec vitest run convex/alphaOps/http.test.ts --maxWorkers=1. They check authentication, target and scope rejection; exact captured collection transfer; a normal edited save with distinct old/new reads; and exact captured SQL-envelope transfer.
- Assembled focused suite 18/18 passed: pnpm --dir chat exec vitest run convex/alphaOps convex/rhodesMigrationRetirement.test.ts --maxWorkers=1 (17 Alpha Ops checks plus the existing Rhodes migration retirement regression).
- Application and Convex typechecks — passed: pnpm --dir chat run typecheck:app and pnpm --dir chat run typecheck:convex.
- Full pnpm lint, exact-file Biome and git diff --check — passed. Existing warnings/nonblocking upstream style suggestions remain; no check was weakened.
- Independent high-effort review freshly ran the new HTTP suite 3/3 and checked runtime equivalence against the accepted source, all fixture components against the private capture, complete module coverage and preservation of existing root routes. No findings. The actual new-code packet contains no invented operational fixture or compatibility expansion.
- Updated-main alignment passed: head 3694b73a1669d805d435d164fe425b59241c9462 is based on main a9b5a360a4e751dc6808600ee7223eeddbe477c6. Its complete code tree is identical to independently reviewed checkpoint 11ae63890bfbec7a17ff3240e92107e1ba688c3a; only Git history changed. Normal commit hooks passed before rebase.
- Hosted CI 15/15 jobs passed at head 3694b73a1669d805d435d164fe425b59241c9462: [run 42631422678](https://github.com/AI-Builder-Team/Aerie/actions/runs/42631422678). No deployment, live source write, import or provider action was performed.
- Runtime named-export inventory accounts for all 31 accepted upstream modules, including the intentional reuse of Aerie's shared authentication implementation. This structural check does not replace behavioral review.
### Time for Implementation
Estimated 3–5 working days for an engineer without AI assistance to integrate the accepted storage code and router, reconcile strict types and internal references, verify source contracts, test the HTTP boundary and complete review and release preparation. This is a human-effort estimate, not measured runtime or the full migration duration.
## Review repairs and contract clarifications
Blocking-only triage of [review 5827095647](https://github.com/AI-Builder-Team/Aerie/pull/2290#pullrequestreview-5827095647), at unchanged head 3694b73a1669d805d435d164fe425b59241c9462, under the existing [AI-1087](https://linear.app/builder-team/issue/AI-1087) scope. No repair ticket or code change is warranted: the sole blocking finding rests on an array-only contract that this storage port does not have.
The collection address identifies an original public.store row. The captured source schema declares data jsonb DEFAULT '[]'::jsonb NOT NULL and a primary key on name; it has no array-only CHECK. The default does not constrain subsequent JSON values. All 43 captured collection rows are arrays, and the original lease/sentinel writers also insert arrays. Supporting raw JSON is preservation of the source column/accepted transfer contract, not a claim that those captured rows contain objects or scalars.
The full value flow is explicit:
1. [protocol.ts:91–93](https://github.com/AI-Builder-Team/Aerie/blob/3694b73a1669d805d435d164fe425b59241c9462/chat/convex/alphaOps/protocol.ts#L91-L93) parses collection JSON before any materialization. Invalid JSON throws; it does not reach a successful publish.
2. [records.ts:3–6](https://github.com/AI-Builder-Team/Aerie/blob/3694b73a1669d805d435d164fe425b59241c9462/chat/convex/alphaOps/records.ts#L3-L6) distinguishes a valid non-array from invalid JSON. Returning null means a valid raw root.
3. [http.ts:727–753](https://github.com/AI-Builder-Team/Aerie/blob/3694b73a1669d805d435d164fe425b59241c9462/chat/convex/alphaOps/http.ts#L727-L753) rejects incomplete staging, checks every chunk, validates JSON, preserves the exact text, and publishes arrays as ordered records or a non-array as exactly one record with rootKind: 'raw'. It does not silently relabel that root as an array.
4. The accepted staged-import path independently allows exactly array or raw, requiring one record for raw roots ([general.ts:288–297](https://github.com/AI-Builder-Team/Aerie/blob/3694b73a1669d805d435d164fe425b59241c9462/chat/convex/alphaOps/general.ts#L288-L297)). Published heads/snapshots and read pins retain that root kind. The accepted portal adapter reconstructs an array only for an array root; otherwise it parses the original single raw token. Array-dependent helpers retain the source errors for non-array values.
Thus HTTP 200 for valid non-array JSON is intentional storage compatibility, not acceptance of malformed source data. Requiring arrays would introduce a new source constraint and change the approved port. The source snapshot/importer and accepted adapter already use this same array/raw distinction. No code/test change or synthetic fixture was added. An earlier explanation tying raw support specifically to scalar/object leases was inaccurate; actual lease writes use [] and are not the justification.
The other three findings are explicitly nonblocking in the review metadata (two hardening suggestions and a deferred coverage gap). They are not included in this blocking-only response. Deployment/environment provisioning remains the already excluded operational phase. Existing evidence remains 18/18 assembled local tests, 3/3 independently rerun HTTP tests and 15/15 hosted CI jobs at this exact head; no redundant test campaign, commit, push, merge, deployment or import was performed.