From 49495af196e27de87fa617525ec8e0348c6e7ead Mon Sep 17 00:00:00 2001 From: JB Date: Fri, 18 Sep 2026 23:33:13 -0400 Subject: [PATCH] docs: plan first implementation batch across parallel worktrees --- README.md | 1 + docs/parallel-worktrees.md | 223 +++++++++++++++++++++++++++++++++++++ docs/roadmap.md | 2 +- 3 files changed, 225 insertions(+), 1 deletion(-) create mode 100644 docs/parallel-worktrees.md diff --git a/README.md b/README.md index bd5024f..cf5b3dd 100644 --- a/README.md +++ b/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) diff --git a/docs/parallel-worktrees.md b/docs/parallel-worktrees.md new file mode 100644 index 0000000..1439825 --- /dev/null +++ b/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. diff --git a/docs/roadmap.md b/docs/roadmap.md index e69ba9c..f202408 100644 --- a/docs/roadmap.md +++ b/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 | |---|---|---|