eden/docs/parallel-worktrees.md

First implementation batch: parallel worktree tasks

Status: planning only. No implementation, worktrees, commits, deployment changes or public-signup approval are performed by this document.

Scope: the seven work items in roadmap §15, 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 97 passing tests; this planning pass did not rerun them. Reconfirm the baseline before implementation. Existing jobs, userPreferences and referenceSyncMetadata tables are placeholders, not services.

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.
• 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. Start T01 + T02 + T03 + T04 independently.
2. Start T05 + T06 once their inputs land. T03 can continue independently.
3. Start T07 + T08 once their inputs land. Serialize any ESI/application wiring overlap.
4. Start T09 + T13 once their inputs land: this is the inventory/finance split. Wallet balances do not wait for inventory queries.
5. Start T10 + T11 + T12 once T09 lands; T13 can continue alongside them.
6. Run T14 on the merged result. Passing it permits only the agreed private slice, not public beta or a complete wealth claim.

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 dataset status and grant revisions; 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, local dataset cancellation/invalidation and visible missing requirements.

Implement the identity enforcement needed by the new pipeline: revalidate linking authority at persistence, trusted-character step-up for credential additions, local transfer/revocation quarantine and job/cache invalidation. Callback persistence/session replacement must be atomic where possible or explicitly compensating with bounded orphan cleanup. Uncertain consumed-code outcomes require recovery, not blind replay. Full unlink/delete/session-management UX remains later M0 work.

Done: scalar/array scopes, stale link sessions, same-character reauth, distinct owner bindings, reduced grants, persistence/cookie-delivery failures and borrowed selectors pass isolated tests. Transfer cannot expose prior-user data; quarantined credentials cannot service reads or future jobs. Schema migration is backward compatible and legacy missing state fails conservatively.

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 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

Own: proposed workers/sync.ts, feature-local job/credential modules, job schema/store operations, /api/sync and replacement of request-bound sync orchestration; Compose wiring follows T01.

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.

Done: process kill/restart, long paging beyond the old five-minute lease, duplicate delivery, cancellation, scope loss, stale-worker completion/failure, refresh races and uncertain rotation preserve the newest valid generation. Caps fail visibly. User-supplied jobs cannot gain system authority. Isolated migration/rollback and minimal worker configuration are exercised.

T08 — Private locations, custom names and containment

Own: proposed location/containment modules, feature-local authorization-context caches and tests. Consume T03 readers/T06 adapters; no second reference compiler or transport.

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: nested/fitted items, identical names, cycles, missing parents, stale/forbidden structures and large IDs pass tests. No numeric-ID guessing, hull/contents multiplier or cross-character private-name leakage. Provide versioned/pinned enrichment inputs for T09, not mutable names that silently change a cursor's filter results.

T09 — Inventory projections and query service

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

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; 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.