docs: plan first implementation batch across parallel worktrees

README.md

@@ -96,6 +96,7 @@ docs/research/             current official-source evidence and captured ESI con
 
 - [Architecture](docs/architecture.md) and [milestone scope](docs/milestone.md)
 - [Remaining-feature roadmap](docs/roadmap.md): inventory and personal finances first, public signup readiness, then markets, industry, capital logistics, and corporation workspaces
+- [First-batch parallel worktree tasks](docs/parallel-worktrees.md): task briefs, dependency waves, shared-file ownership and acceptance gates
 - [Reference lifecycle and production imports](docs/reference-operations.md)
 - [ESI cache, pagination and compatibility operations](docs/esi-operations.md)
 - [EVE/SSO and 2026 structure/ACL evidence](docs/research/eve.md)

docs/parallel-worktrees.md

@@ -0,0 +1,223 @@
+# 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](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 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](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
+
+**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](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.

docs/roadmap.md

@@ -313,7 +313,7 @@ Acceptance: per-capability adversarial/evaluation corpora, measured routing/clar
 
 ## 15. First implementation batch after this plan
 
-Keep the initial branch focused; do not start every milestone at once.
+Keep the initial branch focused; do not start every milestone at once. See the [parallel-worktree task plan](parallel-worktrees.md) for first-batch task briefs, dependencies, file ownership and merge order.
 
 | Work item | Concrete output | Proof of completion |
 |---|---|---|