eden/docs/parallel-worktrees.md

# First implementation batch: parallel worktree tasks

**Status:** this document is the approved task plan. T01–T04 have since been worked in parallel; see [first-wave integration evidence](first-wave-verification.md) for implemented scope, checks and remaining gates. This plan itself does not authorize deployment or public signup.

**Prototype order:** the project is pre-production with no users beyond the operator's test character. Prioritize a functional disposable local prototype first: first login, authenticated linking, capability consent/upgrades, reduced-grant invalidation, primary switching, cancellation, sync/read fencing and tenant isolation. Defer CI/deployed-artifact proof, browser failure injection, restore/migration rollback rehearsals, retention/GC, public quotas/admission, production hardening and similar release evidence until the operator approves that prototype. Essential server-derived authorization, tenant isolation, scope allowlists, one-time OAuth, no token leakage and fail-closed ownership remain prototype requirements. Before public launch, wipe/reseed local data rather than add costly migration/retention compatibility; this exception ends at production, where migration/retention gates remain mandatory.

**Scope:** the seven work items in [roadmap §15](roadmap.md#15-first-implementation-batch-after-this-plan), split into independently reviewable tasks. The roadmap remains authoritative for security, correctness and definition of done. Later milestones and the remaining M0/public hardening stay in the backlog.

**Planning baseline:** `fdcc486` (`Initial Commit`). The roadmap records an earlier 97-test gate; each prototype change reruns the current local suite. Existing `jobs`, `userPreferences` and `referenceSyncMetadata` tables are placeholders, not services.

**T06/T07/T08 evidence:** The centralized ESI client has fixed typed asset,
asset-name, asset-location, wallet-balance, and market-read strategies with bounded
response bytes/rows/pages, bounded retries, abort-first cleanup, validators,
canonical int64 helper bodies, complete scoped authority-context cache identity,
cooldown queries, and runtime schemas. T07 durable scheduling/worker orchestration
and T08 location/containment enrichment are implemented as local prototypes. The
combined suite currently records 254 passing tests; that count includes parallel-core
T09/T13 tests and is not a T08-only count. T08 is implemented and undeployed;
production/live ESI/live Convex-capacity evidence remains deferred. T09 inventory
projection/query and T13 wallet work remain separate roadmap tasks with no
completion claim here. The narrow `beginSync` expected-authority fence is part of T06's
atomic bridge contract: it prevents transport cache authority from being published
under a different T05 grant/revision/credential fence; it is not T07 durable worker
orchestration.

## Execution model

- One task per branch/worktree; branch suggestions below are labels, not created branches.
- A dependency means **merged and verified on the integration base**, not merely started. Rebase dependent worktrees before implementation. Contract-only preparation against mocks can happen earlier but is not integration-ready work.
- Use one integration owner for shared-file patches. Each task supplies its own required schema/store/wiring changes and tests; the integration owner serializes those patches and reruns the combined suite. This is a role, not permission to postpone authorization until integration.
- Prefer feature-local modules and tests over expanding central files. Proposed paths are implementation boundaries, not established APIs. Do not undertake a general architecture rewrite.
- Ready tasks need not all run at once. Assign available agents to independent lanes; more worktrees do not remove dependency or shared-file constraints.
- Every worktree uses synthetic users, isolated Convex state, separate ports/Compose project names, output directories and keys. Do not copy `.env.local`, production volumes, grants or live instance credentials. Never run existing live smoke scripts without reviewing their targets and obtaining consent. Disposable local data may be wiped/reseeded after schema/auth changes; do not build prototype-only migration machinery.
- No branch enables public signup, changes the current ingress gate, performs real-user write smoke tests, or commits secrets. New functionality stays behind the server-side gate from T01 until its acceptance criteria pass.

## Task graph and suggested waves

| ID | Task / suggested branch | Hard dependencies | Size |
|---|---|---|---|
| T01 | Release/test isolation and rollout gate — `batch/release-safety` | None | L |
| T02 | Dataset, identity and feature contracts — `batch/contracts` | None | M |
| T03 | Reference search and station readers — `batch/reference-readers` | None | M–L |
| T04 | Signed decimal ingestion and money formatting — `batch/exact-money` | None | S–M |
| T05 | Dataset authorization and incremental consent — `batch/dataset-consent` | T01, T02 | L |
| T06 | Typed ESI transport extensions — `batch/esi-transport` | T02, T04 | M |
| T07 | Durable asset queue and worker — `batch/asset-worker` | T01, T05, T06 | L |
| T08 | Private locations, custom names and containment — `batch/inventory-locations` | T03, T05, T06 | M–L |
| T09 | Generation-bound inventory projections and query service — `batch/inventory-query` | T03, T07, T08 | L |
| T10 | Inventory browsing UI — `batch/inventory-ui` | T09 | M |
| T11 | Inventory assistant parity — `batch/inventory-assistant` | T09 | M |
| T12 | Saved views and private exports — `batch/inventory-exports` | T09 | M–L |
| T13 | Wallet balance vertical slice — `batch/wallet-balances` | T04, T07 | M–L |
| T14 | Combined regression and private-release evidence — `batch/integration-proof` | T10, T11, T12, T13 | M |

Sizes describe scope, not time estimates. Split an L task further if its contract review reveals independent changes; do not create parallel branches that both redesign the same foundation.

**Suggested schedule (dependency edges, not wave numbers, determine readiness):**

1. **Local prototype wave:** land the minimum T01/T02 contracts and gates needed for T05, then prioritize **T05 + T06** and the existing local asset flow. T03/T04 can continue independently where they unblock functionality.
2. Start **T07 + T08** once their inputs land. Serialize any ESI/application wiring overlap; do not expand into production worker/restore evidence yet.
3. Start **T09 + T13** once their inputs land: this is the inventory/finance split. Wallet balances do not wait for inventory queries.
4. Start **T10 + T11 + T12** once T09 lands; T13 can continue alongside them.
5. **Prototype approval gate:** operator reviews functional local flows and decides whether to invest in operations/release evidence.
6. **Post-approval production wave:** run T01's deferred CI/deployed proof, browser failure injection, backup/restore/migration rollback, retention/GC, quotas/admission and hardening, then run T14 on the approved merged result. Passing prototype tests alone never permits public beta.

## Shared-file ownership and merge discipline

| Collision surface | Change order / owner rule |
|---|---|
| `src/lib/domain/{model,capabilities}.ts` | T02 fixes contracts first; T05 implements dataset gates. T09/T13 add inventory/wallet registrations through serialized patches, not independent contract rewrites. |
| `src/convex/{schema,functions,status}.ts`, `src/lib/server/store.ts` | T05 → T07 foundations. T08, T09, T12 and T13 own only their feature additions; integration owner merges one additive schema/store patch at a time and verifies indexes/migrations. Prefer new feature modules where supported. |
| `src/lib/server/application.ts`, `config.ts`, `compose.yaml` | T01 gate/environment baseline → T05 auth wiring → T07 worker wiring; later feature factories wired serially. T01 owns deployment-tooling changes initially. |
| `src/lib/server/esi/index.ts` | T04 owns only decimal-conversion extraction; T06 follows with transport changes. T07/T08 adapters must not independently rewrite transport; coordinate any remaining central edits. |
| `src/lib/server/reference/*`, `workers/reference.ts` | T03 owns compiler/readers. T08 consumes these contracts, not a competing station importer. |
| `src/lib/components/AssetResult.svelte`, `/assets` | T10 owns browse rendering; T12 adds controls in a follow-on patch after coordinating with T10. T11 consumes the shared result contract without redesigning this component. |
| Assistant intent/service and `/api/chat` | T11 owns inventory adaptation. T13's wallet registration lands serially with T11; finance service work remains independent. |
| `package.json`, `bun.lock`, generated Convex files | Integration owner coordinates dependency changes/code generation. Do not hand-edit generated files or regenerate them independently to mask unresolved schema conflicts. |
| Existing broad test files | Preserve regressions. Prefer task-specific new test files; coordinate modifications to shared fixtures. |

Before merging: review dependency commits, migrations and permissions; run task-specific tests plus `bun test`, `bun run check`, and `bun run build` in the isolated environment. Record results rather than copying the roadmap's historical count. T14 repeats this on the combined tree.

## Worktree briefs

### T01 — Release/test isolation and rollout gate

**Own:** isolated CI/browser/backend fixtures, release/operator scripts, deployment configuration, gate implementation and dedicated tests. Coordinate `package.json`, lockfile and application wiring centrally.

**Deliver:** reproducible test/check/build and deployed-artifact checks; synthetic OAuth/browser fixtures for native forms, callback cookies, linking, logout and pending-request resume; immutable application release identifiers; baseline secret-exclusion review; isolated backup/restore and compatible migration/rollback rehearsal. Back up instance credentials as well as application data and reference artifacts; restored sessions must not reopen traffic with obsolete grants.

**Decision gate:** obtain approval for the server-side rollout mechanism before coding it. No CI-hosting platform, production admission rule or RPO/RTO is selected here. Gates must cover routes, assistant dispatch, jobs and subscriptions, not only UI.

**Done:** baseline regressions remain green; fixtures cannot target the persistent backend accidentally; a restored isolated instance and rollback have recorded evidence; disabled capabilities fail closed across all entry points. No production backup secrets enter logs or artifacts.

### T02 — Dataset, identity and feature contracts

**Own:** typed domain contracts, contract fixtures and a short design record; coordinate changes to `model.ts`/`capabilities.ts`. No production behavior or broad schema migration in this task.

**Deliver:** a reviewed contract for dataset status/coverage, resource principal, required scopes, selected resources, grant/authorization revision, credential version, job/publication fence, and report provenance. Distinguish snapshot generations from append checkpoints and fetched time from unknown upstream effective time.

Define incremental consent, one-time OAuth/session binding, revocation/transfer quarantine, stale-authority behavior, callback failure recovery and refresh uncertainty **before** finalizing the worker. Keep token rotation versions distinct from authorization revisions. Define current user versus server-owned jobs without granting users system authority.

Also freeze the first inventory query/result/filter/cursor contract, reference/location reader interfaces, wallet-balance result, and money normalization policy. Specify `isSingleton` as unknown on legacy rows; selected totals must not mean page totals. A cursor pins authorized resources, revisions, generations, reference and price versions; possession is not authorization.

**Decision gate:** unresolved recovery/stale-authority policies require operator approval; retain roadmap defaults meanwhile. Do not invent a password recovery path, merge accounts by owner hash or decide public quotas here.

**Done:** examples and contract tests cover reduced grants, transfer, stale sessions/workers, partial coverage, large IDs and ambiguous entities. Downstream tasks have explicit requests/results/error states rather than needing to guess. Mark proposed schema changes separately from implemented services.

### T03 — Reference search and station readers

**Own:** `src/lib/server/reference/{schema,types,normalize,compiler,production,repository}.ts`, reference fixtures and dedicated tests; necessary `workers/reference.ts` changes.

**Deliver:** indexed normalized type search, group/category and system/region readers, plus NPC station import from a verified source. Version compiler/schema changes and retain release/source provenance, integrity checks and rollback compatibility. Extend repository contracts agreed in T02 when integrating; initial source investigation and compiler work do not depend on T02.

**Done:** fixture artifact tests exercise search/group/location relationships and station coverage; readers reject incompatible artifacts; unknown locations remain explicit. Verify the actual deployed reader/artifact in an isolated deployment, not only worker stdout. No private structure names enter public SQLite. An unverified station source blocks station completion rather than producing invented coverage.

### T04 — Signed decimal ingestion and money formatting

**Own:** `src/lib/domain/money.ts`, a shared money formatter, focused arithmetic tests; narrow extraction from the current private ESI price converter and existing formatting call sites.

**Deliver:** lossless signed decimal-to-integer-cent conversion with explicit rounding, negative formatting and safe quantity boundaries. Preserve the existing non-negative price validation as a separate policy; do not silently accept negative market estimates. Coordinate policy with T02 before merge.

**Done:** negative fractions, large debits/balances, rounding boundaries, zero and invalid numeric input have golden/property tests. No monetary parsing passes through an imprecise JavaScript number. Existing asset totals/formatting remain correct. This task does not implement a wallet or change valuation methods.

### T05 — Dataset authorization and incremental consent

**Own:** SSO/security/auth routes, dataset capability gates, character management status/actions, initial schema/store/status changes and dedicated auth tests.

**Deliver:** persisted per-dataset status, a single primary login role plus data-only linked roles, grant revisions and credential/authorization epochs; server-allowlisted capability scopes; one-time OAuth binding to requested scopes, operation/link intent and initiating session; verified actual grants; deliberate preservation of required existing scopes. Support upgrade/reconnect, reduced/denied grants, authenticated primary switching, local dataset cancellation/invalidation and visible missing requirements. Keep wallet behind its release capability.

Implement the prototype identity enforcement needed by the pipeline: revalidate linking authority at persistence, local owner/revocation quarantine and job/cache invalidation, and atomic session replacement where practical. Never replay a consumed OAuth code; full transfer-to-new-owner recovery, unlink/delete/session-management UX and production orphan/retention policy remain deferred.

**Done:** scalar/array scopes, stale link sessions, primary-character reauthentication, signed-out data-only rejection, distinct owner bindings, reduced grants, primary switching, cancellation and borrowed selectors pass isolated tests. Transfer cannot expose prior-user data; quarantined credentials cannot service reads or future jobs. This pre-production branch may wipe/reseed local data instead of implementing legacy migrations/lazy normalization; production migration/retention gates remain required before P.

### T06 — Typed ESI transport extensions

**Own:** `src/lib/server/esi/` transport and endpoint-specific adapters/fixtures, plus `docs/esi-operations.md` changes.

**Deliver:** typed endpoint/pagination strategies, explicitly read-only POST support for asset names, lossless outbound int64 serialization and canonical request-body/auth-context cache keys. Add bounded asset-name, location and balance adapter contracts, keeping service orchestration in their respective tasks. Verify routes/scopes against the [planning matrix](research/expansion-data-contracts.md) and pinned fixtures before use.

**Done:** IDs above `2^53`, canonical body variations, grant-revision changes, cache isolation, retry/cooldown/TTL handling, schema failures and page caps have tests. OAuth exchange/refresh does not inherit safe-read retries. No arbitrary URL/method executor, unlimited paging or partial-as-complete result is introduced. Provide the scheduling/cooldown hooks T07 needs without a second independent scheduler.

### T07 — Durable asset queue and worker

**Status:** implemented local prototype; no deployment, live ESI, or production-readiness claim.

**Own:** `workers/sync.ts`, feature-local job/credential modules, job schema/store operations, `/api/sync` and replacement of request-bound sync orchestration; Compose wiring and restricted operator startup.

**Deliver:** enqueue/status instead of long-running request work; typed deduplicated jobs, bounded attempts/due times, cancellation, fair scheduling/backpressure, shared cooldown/error budgets, renewable leases and fenced success **and failure** publication. Stage/validate assets before active-generation publication and retain validated `isSingleton` facts throughout ingestion.

Share a per-character refresh lease across web and workers, retaining token CAS. At-least-once delivery is not exactly-once remote refresh: an uncertain rotated result produces actionable reauthorization instead of automatic replay. Keep reference extraction separate and minimize worker secrets. Public feeds must be coordinated rather than independently refreshed per process. The worker requires the distinct `CONVEX_SYNC_WORKER_SECRET`; standalone startup uses a worker-only environment and Compose startup uses the explicit `worker` profile. T08 adds only `REFERENCE_DIR` and a read-only reference-data volume to this environment; the worker opens an immutable artifact reader and has no import/write credentials.

**Verified locally:** process kill/restart, long paging beyond the old five-minute lease, duplicate delivery, cancellation, scope loss, stale-worker completion/failure, refresh races, uncertain rotation, restricted runtime startup and configuration boundaries. T08 enrichment is staged and atomically published at the post-assets/pre-publication seam; production migration/release evidence remains deferred.

### T08 — Private locations, custom names and containment

**Status:** implemented local prototype; undeployed. No live ESI, live Convex-capacity, production-reference, or production-readiness claim.

**Checkpoint manifest:** see [the exact T08 manifest in the verification record](verification.md#exact-t08-checkpoint-manifest). T09 projection/query files/tests/fixtures and T13 wallet files/tests/fixtures are explicitly excluded.

**Own:** location/containment modules, feature-local authorization-context caches, typed ESI structure adapter, incremental consent wiring, generation enrichment persistence and tests. Consume T03 readers; the shared ESI adapter is extended only with the fixed structure operation.

**Deliver:** parent/item relationships, fitted flags, breadcrumb inputs and unresolved reasons. Resolve NPC stations from reference facts and private structures/custom names only under valid character scope/evidence. Integrate bounded enrichment with dataset freshness and revision invalidation; enrichment failures must remain explicit and cannot authorize or fabricate a complete location result.

**Done locally:** nested/fitted items, identical names, cycles, missing parents, stale/forbidden structures, large IDs, multi-batch helper observations and 50k bounded chains pass synthetic tests. The worker stages private rows against the exact asset generation and authority/reference pin, publishes partial coverage honestly, and exposes generation-matching manifest/chunk reads. Public/private source facts are pinned and validated against persisted rows; oversized optional enrichment falls back before staging. No numeric-ID guessing, hull/contents multiplier, docking inference or cross-character private-name leakage. T09 receives versioned/pinned enrichment inputs rather than mutable names. The limits are conservative prototype bounds, not measured live Convex capacity.

### T09 — Inventory projections and query service

**Status:** separate accepted core task; not claimed complete by this T08 checkpoint. Its projection/query files, tests and fixture are excluded from the T08 manifest.

**Own:** generation-bound indexed inventory rows, inventory query service/repository and dedicated query tests; additive schema/store changes coordinated with T13.

**Deliver:** staged projections published with validated generations; validated filters for character/type/custom name/category/group/quantity/location/system/region/pricing/BPC state; stable sorting and server-side paging. Pin selected input generations, location enrichment, reference/price versions and authorization revisions. Reuse or extend `AssetService` authorization/valuation rather than cloning it.

Compute selected summaries across **all matching rows**, not the visible page, with measured bounded operations. Expose the same deterministic result to UI, chat and exports. Define cursor expiry and reference-retention hooks so future GC cannot remove live inputs.

**Done:** two-user/cross-character and borrowed-cursor tests; stable page boundaries during new publications; singleton/legacy unknown fields; large-account index/read/write budgets; matching summary/page aggregation; missing and stale inputs; auth loss invalidates subsequent requests. Queries that exceed caps fail visibly. No full-inventory scans disguised as bounded paging.

### T10 — Inventory browsing UI

**Own:** `src/routes/assets/`, `src/lib/components/AssetResult.svelte` and inventory-specific components/browser tests.

**Deliver:** search, character/location selectors, grouping/sorting/paging, container breadcrumbs/fitted contents, complete selected totals and explicit missing/stale/unknown states against T09. Do not compute a separate client-side valuation engine.

**Decision gate:** confirm interaction/layout preferences before implementing a significant UX redesign; preserve existing native form behavior and manual flows.

**Done:** isolated native-browser and keyboard tests cover filter changes, paging, ambiguous names, containment, refresh and revoked access; UI report totals match the service. Operator walkthrough evidence uses approved fixture or consenting data. Coordinate export/view controls with T12 rather than both rewriting the page.

### T11 — Inventory assistant parity

**Own:** `src/lib/server/assistant/{intent,service}.ts`, inventory capability registration, manual commands and dedicated intent/parity tests.

**Deliver:** validated item/location/character filters, deterministic resolution within the caller's allowed set, clarification for ambiguous entities, and T09 report consumption. Preserve `/assets` and `/value` fallback behavior; unsupported filters cannot become unfiltered all-assets answers.

**Done:** pinned UI/chat equality, ambiguous and forbidden selectors, malformed model output, prompt injection and unsupported requests have tests. External classification receives no inventories, grants or private location-cache dumps. Persist bounded versioned result summaries/input references rather than introducing new full-report history payloads; expired detail is explicitly unavailable. Coordinate wallet capability registration with T13.

### T12 — Saved views and private exports

**Own:** validated saved-view preferences, private export/report services/routes and tests; feature components with a coordinated T10 wiring patch.

**Deliver:** schema-validated filters, private report references and CSV over T09's exact scope/pinned inputs. Enforce tenant/resource/revision checks on creation, resume and every download. Keep generated files outside public static storage; support expiration, cancellation, retention and deletion hooks.

**Decision gate:** approve concrete export/view quotas and retention before enabling them; no unlimited defaults or public share links.

**Done:** formula-injection escaping, borrowed view/report/export IDs, revoked grants, expired cursors, bounded size/time and cleanup are tested. Summary totals match the entire exported selection. Partial/failed exports never appear complete. Already downloaded files are explicitly not recallable. Coordinate schema changes with T13 and preserve referenced inputs until expiry.

### T13 — Wallet balance vertical slice

**Status:** separate accepted task; not claimed complete by this T08 checkpoint. All wallet files, tests and fixtures are excluded from the T08 manifest.

**Own:** new wallet domain/service/ESI-adapter orchestration, balance snapshot storage, wallet job handler, compact finance component/route and tests. Central schema/capability/application/assistant registrations land serially with other feature tasks.

**Deliver:** opt-in balance capability using T05 consent/T07 jobs, exact signed cents from T04 and independently timestamped balance coverage. Ship a deterministic balance service, conventional UI and typed assistant/manual query adapter. Keep the wallet amount a **separately labelled component**, not a combined wealth total.

**Done:** new/reduced scopes, two-user isolation, lossless negative/large balances, duplicate jobs, stale publication, refresh failure and partial multi-character coverage pass tests. UI/chat use identical pinned results. Unsupported journal, transaction, own-order and historical-profit requests remain unsupported. No combined asset-plus-wallet wealth calculation or invented balance history.

### T14 — Combined regression and private-release evidence

**Own:** cross-feature browser/adversarial scenarios and updates to verification/operator documentation; implementation defects return to their owning task.

**Deliver:** integration evidence for login/upgrade → enqueue/restart → inventory filter/container → saved view/export → matching chat and separate wallet balance. Run test/check/build against the merged tree, isolated deployment/artifact checks and migration/rollback rehearsal with the expanded schemas.

**Done:** two users cannot cross-read through IDs, subscriptions, caches, jobs, cursors or downloads; invalidation races fail closed; query/export/queue resource budgets are recorded; backup/restore preserves required instance credentials and invalidates stale sessions/grants. Distinguish mock, fixture and consenting live evidence. List unverified provider behavior and remaining release blockers. No public-readiness claim follows from passing this batch.

## Roadmap coverage and explicit deferrals

| Roadmap §15 item | Task coverage |
|---|---|
| 1. Baseline/release safety | T01, combined rehearsal in T14 |
| 2. Dataset, scope and identity contracts | T02, T05; consumers tested in T07/T14 |
| 3. Durable asset job slice | T06, T07 |
| 4. Reference/location slice | T03, T06, T08 |
| 5. Inventory query slice | T09; interface parity in T10/T11 |
| 6. Inventory UX slice | T10, T11, T12 |
| 7. First finance slice | T04, T13 |

**Deferred, not waived:** complete M0 identity lifecycle (unlink/delete, session-management/recovery UX and transfer reconciliation), global retention/GC and interaction-history migration, encryption/signing/bridge-key rotation, ongoing reference release scheduling, remaining public quotas/privacy/security/ingress controls, and the entire P release checklist. Local first-batch invalidation, cleanup and safe bounds are still required now.

M1 snapshot-difference history remains a separate follow-up. M2 journals/transactions, own orders and wealth reconciliation follow wallet balances as separately reviewed vertical slices. M3–M8 remain in [the roadmap](roadmap.md); do not create speculative implementation worktrees for them in this batch.

## Task handoff checklist

When assigning a task, include this document, its T-number, the roadmap's shared rules/definition of done, the exact integration-base commit and merged dependency commits. The agent should report:

1. Owned files and any shared-file patches needing a merge reservation.
2. Unresolved decisions requiring operator input before implementation.
3. Request/result contracts, schema migration and rollback impact.
4. Test commands/results, resource limits and isolation evidence.
5. Remaining blockers and a concise handoff for dependent tasks.

A task is complete only when its acceptance evidence survives integration—not when its worktree happens to pass alone.