Upstream Integration Analysis · T3 Trade ← T3 Code

The divergence at a glance

Both branches share a common ancestor at a8e05cbb (chore(release): prepare v0.0.31, 2026-07-29). Since then they have moved in parallel for six days. The numbers below come from git rev-list --count and git merge-tree against the freshly-fetched remotes.

Fork ahead

143

commits on origin/main not in upstream/main — the entire trading layer

Upstream ahead

commits on upstream/main not in origin/main — features & fixes to absorb

Common ancestor

6 days

of parallel divergence since v0.0.31 (Jul 29 → Aug 4)

Textual conflicts

files Git cannot auto-merge · plus 1 hidden semantic collision

Fork is ahead

143

commits — trading domain, Hyperliquid integration, branding

Fork is behind

commits — search, terminal rendering, mobile, Effect β.103, Linux desktop

What we observed vs. what we infer

Integration decisions must rest on evidence, not guesses. The left column is verifiable from the remotes; the right column is reasoned inference that an execution agent should confirm before acting.

● Observed facts (from git)

Remotes: origin → 0xgeorgemathew/t3trade, upstream → pingdotgg/t3code (push disabled).
Both main branches descend from a8e05cbb (v0.0.31 release prep).
Fork carries 143 unique commits; upstream carries 80 unique commits.
Fork adds 10 migrations (035–044) for trading tables; upstream adds 1 migration (035) for title regeneration.
Migration number 035 collides: fork = 035_TradingDomain, upstream = 035_ProjectionThreadTitleRegeneration.
Effect catalog: fork pinned at β.102, upstream advanced to β.103.
git merge-tree dry-run reports exactly 12 textual conflicts and 41 clean auto-merges.
Fork introduces two new packages (packages/trading-contracts, packages/hyperliquid) untouched by upstream — zero conflict.
Fork has a scripts/check-fork-independence.ts guard that rejects upstream infrastructure URLs.

▲ Assumptions & inferences

The migration-035 collision is a data-integrity hazard, not just a text conflict — renumbering is required (inferred from migration semantics).
Effect β.102 → β.103 is likely backward compatible for this codebase, but the contracts changes suggest some API drift worth a typecheck (inferred from minor version bump).
Upstream's searchThreads and ThreadTitleRegeneration additions to contracts/orchestration.ts are additive and should coexist with fork's trading command additions (inferred from diff regions).
The 41 auto-merged files are probably safe but still need a typecheck + test pass — auto-merge ≠ correct (standard caveat).
Branding conflicts (README.md, docs/README.md) are intentional fork divergences and should resolve in favor of the fork (inferred from fe092c004 chore(branding)).
bootService/selfUpdate conflicts likely involve fork's fork-independence hardening — must preserve fork intent (inferred from check-fork-independence.ts existence).

Remote & branch map

A single merge-base, two fast-moving tips. The fork's 143 commits are almost entirely new packages and trading features; upstream's 80 touch many of the same shared files (contracts, orchestration, web UI, cloud services).

merge-base (shared ancestor)

origin/main (fork)

upstream/main

integration path

conflict zone

The 12 textual conflicts, ranked

From git merge-tree --write-tree upstream/main origin/main. Risk is scored by combining how many lines each side changed in overlapping regions and whether the file is load-bearing for the trading layer.

File	Conflict region	Fork Δ	Upstream Δ
packages/contracts/src/orchestration.tsWS methods, command unions, OrchestrationThread	+88 lines	+76 lines	High
apps/server/src/serverRuntimeStartup.tsservice wiring / startup layers	+2 lines	+342 lines	High
apps/server/src/cloud/bootService.tsfork-independence hardening vs upstream rewrite	+6 lines	+288 lines	High
apps/server/src/cloud/selfUpdate.tsupdate endpoint / rollback logic	+4 lines	+463 lines	High
apps/web/src/components/settings/SettingsSidebarNav.tsxsidebar nav entries	+5 lines	+288 lines	Medium
apps/server/src/cloud/bootService.test.tstest scaffolding	+2 lines	+611 lines	Medium
apps/server/src/persistence/Migrations.tsimport list + migration manifest	+20 lines	+6 lines	High
apps/desktop/src/app/DesktopEnvironment.tsenvironment identity	+6 lines	+24 lines	Medium
apps/mobile/app.config.tsapp metadata / scheme	+12 lines	+22 lines	Medium
apps/server/src/cli/connect.tsconnect command	+2 lines	+15 lines	Low
README.mdbranding (intentional fork divergence)	+177 lines	+27 lines	Low
docs/README.mddocs index (branding)	fork-only	+upstream	Low

41 additional files auto-merge cleanly — but verify anyway

Files like apps/server/src/orchestration/decider.ts (fork +220 / upstream +38) and apps/server/src/ws.ts (fork +68 / upstream +141) auto-merge without textual conflict, but they are load-bearing for the trading state machine. Auto-merge success does not guarantee semantic correctness — a typecheck and the trading test suite are mandatory after any integration.

Hidden risks Git will not warn you about

These problems do not appear as <<<<<<< markers. They are silent collisions in shared numeric namespaces and version catalogs. An execution agent that ignores them will produce a tree that typechecks but is broken at runtime.

Migration 035 collision — the single most dangerous finding

Both sides claimed migration slot 35. The fork uses it for 035_TradingDomain.ts (creates the core trading tables); upstream uses it for 035_ProjectionThreadTitleRegeneration.ts (thread title regen column). If both files land under the same number, the migration loader will apply only one and the other's schema change silently never runs — leading to missing tables or missing columns depending on load order. The fork's migrations 035–044 must be renumbered to 036–045 (or higher) so upstream's 035 keeps its slot. This is a manual edit to Migrations.ts plus a file rename — it will not surface as a text conflict.

▲

Effect catalog drift: β.102 → β.103

Upstream bumped the entire Effect catalog from 4.0.0-beta.102 to 4.0.0-beta.103 (commit 2b1d4fecb). The fork still sits on β.102. A β-bump can carry breaking schema/API changes — upstream's own contracts/orchestration.ts edit (removing effect/Option import, adding TrimmedString) is evidence of API drift. The integration must adopt β.103 wholesale and re-run the full typecheck. pnpm-lock.yaml will conflict but should be regenerated rather than merged by hand.

▲

Fork-independence guard rails

The fork ships scripts/check-fork-independence.ts, which fails CI if any source file references pingdotgg/t3code infrastructure. Upstream's bootService.ts, selfUpdate.ts, and connect.ts naturally contain such references. Resolving those conflicts "in favor of upstream" would re-introduce a live dependency on upstream's infra and break the guard. These three files must be resolved in favor of the fork's redirection logic, then re-validated by running the independence check.

Integration strategies compared

Five viable paths, each with a different trade-off between history cleanliness, conflict exposure, and reversibility. The green-bordered card is the recommendation.

A · Merge upstream into a feature branch

git merge upstream/main — preserve both histories

Recommended

Create sync/upstream-2026-08-04 off origin/main, run git merge upstream/main, resolve the 12 conflicts plus the migration renumber, typecheck, test, then fast-forward main. History is preserved; a merge commit records the synchronization point.

Best for: This exact situation — long-lived fork, ongoing relationship with upstream.
Conflict risk: Medium — bounded to the known 12 files + migration renumber.
History: Preserved on both sides; one merge commit.
Force-push?: No — if done on a feature branch merged by PR.
Reversible?: Yes — delete the branch / revert the merge commit.

12 conflicts migration renumber Effect β-bump

Exact commands

shell

# 0. Backup the current tip
git branch backup/main-pre-sync-$(date +%Y%m%d) origin/main

# 1. Fresh integration branch off the fork
git checkout -b sync/upstream-2026-08-04 origin/main

# 2. Ensure upstream is current
git fetch upstream

# 3. Merge — expect 12 conflicts
git merge upstream/main --no-ff --no-commit

# 4. Resolve conflicts (see phased plan), then:
git add -A
git commit -m "sync(upstream): merge pingdotgg/t3code main (80 commits) into T3 Trade

- renumber fork migrations 035-044 -> 036-045 to free slot 035 for upstream
- adopt Effect catalog beta.103
- preserve fork-independence hardening in bootService/selfUpdate/connect
- resolve 12 textual conflicts per upstream-integration-analysis-2026-08-04"

# 5. Verify before pushing
pnpm install
pnpm run typecheck
pnpm test run apps/server/src/persistence packages/contracts packages/trading-contracts

# 6. Push the branch and open a PR — do NOT force-push main
git push -u origin sync/upstream-2026-08-04

B · Rebase the fork onto upstream

git rebase upstream/main — linear history

Risky

Replay all 143 fork commits on top of upstream/main. Produces a perfectly linear history, but every fork commit that touches a conflicting file may pause for resolution, and the same conflict can recur multiple times across the 143-commit range.

Best for: Short forks with few commits — not this one.
Conflict risk: High — conflicts may repeat per-commit; 143 replays.
History: Rewritten — every fork commit gets a new SHA.
Force-push?: Yes — mandatory; all SHAs change.
Reversible?: Only via the backup branch / ORIG_HEAD.

repeated conflicts force-push 143 replays

Exact commands

shell

# Backup is mandatory — rebasing rewrites history
git branch backup/main-pre-rebase origin/main

git checkout -b rebase/upstream-2026-08-04 origin/main
git fetch upstream
git rebase upstream/main

# On each conflict: resolve, git add, git rebase --continue
# To abandon: git rebase --abort

# Force-push ONLY after full verification
git push --force-with-lease origin rebase/upstream-2026-08-04

C · Cherry-pick selected upstream commits

take only what you want

Targeted

Pick individual upstream commits (e.g. 5c9358aca title regen, 4b71a2ae2 thread search, 61514c129 npx t3 pair) onto origin/main. Useful if you want only a subset of upstream and can defer the rest.

Best for: When only a few upstream features are wanted now.
Conflict risk: Variable — depends on which commits and order.
History: Fork commits preserved; cherry-picks appended with new SHAs.
Force-push?: No — appended normally.
Reversible?: Yes — revert individual cherry-picks.

partial sync low blast radius manual triage

Exact commands

shell

git checkout -b cherry/upstream-selective origin/main
git fetch upstream

# Example: thread title regeneration + search (additive to contracts)
git cherry-pick 5c9358aca   # feat(web): regenerate thread titles
git cherry-pick 4b71a2ae2   # feat(search): find threads by content
git cherry-pick abc409c2d   # project file picker + content search

# Resolve per-commit, then:
pnpm run typecheck && pnpm test run packages/contracts
git push -u origin cherry/upstream-selective

D · Reset fork main to upstream

start over from upstream — destructive

Destructive

Point main at upstream/main, then re-apply the trading layer as a new commit (or series of commits) on top. Cleanest possible base, but discards all fork history and requires re-porting 143 commits worth of work.

Best for: Never, for this fork — 143 commits of trading logic is too much to re-port.
Conflict risk: N/A — there is nothing to conflict with; you start clean.
History: Destroyed — fork SHAs orphaned (recoverable from backup only).
Force-push?: Yes — mandatory.
Reversible?: Only via backup branch.

history loss re-port 143 commits

Exact commands (not recommended)

shell

# MANDATORY backup
git branch backup/main-pre-reset origin/main

git checkout main
git fetch upstream
git reset --hard upstream/main
git push --force-with-lease origin main

# Then manually re-port the trading layer from backup/main-pre-reset

E · Phased manual port

group upstream changes, port by theme

Patient

Split upstream's 80 commits into thematic batches (contracts/schema, web UI, mobile, desktop, cloud/infra, deps) and merge or cherry-pick each batch separately behind its own feature branch and PR. Slower, but each batch is independently reviewable and revertible.

Best for: When you want review gates per concern and can spread the work over days.
Conflict risk: Medium — same total conflicts, but surfaced in smaller pieces.
History: Preserved; one merge commit per batch.
Force-push?: No.
Reversible?: Yes — revert per-batch PR.

slower reviewable ordering care

Which strategy should you pick?

Answer honestly, then follow the recommendation. This encodes the trade-offs above into a decision path grounded in the observed fork state (143 ahead, 80 behind, 12 conflicts).

Q1Do you want to absorb all of upstream, or just specific features?

All → Go to Q2.

Only some → Use Strategy C (cherry-pick). Pick the commits you want; defer the rest. Lowest blast radius, but you'll still owe a full sync later.

Q2Is linear history worth rewriting 143 fork commit SHAs?

No → Go to Q3.

Yes → Use Strategy B (rebase) — but expect repeated conflicts across 143 commits and a mandatory force-push. Not recommended for a fork this size.

Q3Do you need per-concern review gates, or one synchronized PR?

One PR → Use Strategy A (merge) — the recommendation. Single integration branch, all 12 conflicts resolved in one place, one merge commit records the sync point.

Per-concern PRs → Use Strategy E (phased port). Slower but each batch (contracts, web, mobile, cloud, deps) ships behind its own reviewable, revertible PR.

★

Recommendation for this fork, today

Strategy A (merge) on a dedicated sync/upstream-2026-08-04 branch, merged via PR. It is the safest strategy (no force-push, fully reversible, both histories preserved), the fastest reasonable one (one conflict-resolution pass, not 143), and the cleanest long-term (the merge commit becomes a durable record of the synchronization point). If you later want finer-grained review, Strategy E is the natural fallback.

Recommended execution sequence

Six phases for Strategy A. Each phase is independently verifiable and abortable. Do not skip the backup — if anything goes sideways, backup/main-pre-sync-* is the restore point.

Backup & branch

Establish a restore point and an isolated workspace.

Create backup/main-pre-sync-YYYYMMDD pointing at current origin/main.
Create sync/upstream-2026-08-04 off origin/main.
Confirm working tree is clean (commit or stash the .vscode/settings.json change and untracked artifacts/reports/*).
git fetch upstream to ensure upstream/main is current.

Merge & triage conflicts

Surface every conflict in one pass.

git merge upstream/main --no-ff --no-commit — expect 12 textual conflicts.
List them: git diff --name-only --diff-filter=U.
Confirm the count matches the 12 in this report; if higher, stop and investigate before resolving.

Resolve the semantic risks first

Fix what Git will not warn you about.

Migration renumber: rename fork's 035_TradingDomain→036, …, 044_TradingAccountObservations→045; update Migrations.ts import list and manifest array to match. Leave upstream's 035_ProjectionThreadTitleRegeneration as slot 35.
Effect catalog: accept upstream's pnpm-workspace.yaml (β.103); discard the fork's lock fragment. Regenerate pnpm-lock.yaml with pnpm install rather than merging it.
Fork-independence: in bootService.ts, selfUpdate.ts, connect.ts — keep the fork's redirection logic; re-apply upstream's behavioral fixes around it, not over it.

Resolve the textual conflicts

Settle the 12 files, lowest-risk first.

Branding (low): README.md, docs/README.md → take fork side (intentional divergence).
Low-risk misc: apps/server/src/cli/connect.ts → re-apply fork's redirect on top of upstream's new behavior.
Mobile/desktop metadata (medium): apps/mobile/app.config.ts, apps/desktop/src/app/DesktopEnvironment.ts, apps/web/.../SettingsSidebarNav.tsx → merge both sides' additions.
Tests (medium): apps/server/src/cloud/bootService.test.ts → keep fork's assertions, add upstream's new cases.
Schema (high): packages/contracts/src/orchestration.ts → union both sides' WS methods, command additions, and OrchestrationThread fields. Both are additive.
Startup/cloud (high): apps/server/src/serverRuntimeStartup.ts, bootService.ts, selfUpdate.ts → port upstream's fixes, preserve fork's independence layer.

Verify

Prove the integrated tree is correct, not just conflict-free.

pnpm install (regenerates lockfile at β.103).
pnpm run typecheck — must pass; watch for Effect β.103 API drift.
pnpm test run apps/server/src/persistence — proves migrations load 036–045 + upstream's 035.
pnpm test run packages/contracts packages/trading-contracts — proves the unioned schemas decode.
pnpm test run apps/server/src/orchestration — proves decider/projector still behave.
Run scripts/check-fork-independence.ts — must still pass (no upstream infra URLs leaked in).

Commit, push, review

Land the integration behind a reviewable PR.

git commit with the message template from Strategy A.
git push -u origin sync/upstream-2026-08-04 — not a force-push.
Open a PR into main; request review before merging.
After merge, delete the sync branch; keep backup/main-pre-sync-* until the next sync is green.

Handoff checklist for the execution agent

Interactive — click a row to mark it done. This is the contract between this analysis and whoever runs the integration. Do not begin execution until every "before" box is checked.

BEFORE: Backup branch backup/main-pre-sync-YYYYMMDD created from origin/main.

BEFORE: Working tree clean — .vscode/settings.json committed/stashed, untracked reports stashed.

BEFORE: git fetch upstream run; upstream/main confirmed at 2b1d4fecb.

BEFORE: Integration branch sync/upstream-2026-08-04 created off origin/main.

DURING: Migration 035 collision resolved — fork's 035–044 renumbered to 036–045; upstream's 035 keeps its slot.

DURING: Effect catalog accepted at β.103; pnpm-lock.yaml regenerated, not hand-merged.

DURING: Fork-independence preserved in bootService.ts, selfUpdate.ts, connect.ts.

DURING: All 12 textual conflicts resolved; git diff --diff-filter=U is empty.

DURING: Branding files (README.md, docs/README.md) resolved in favor of the fork.

VERIFY: pnpm install succeeds with no lockfile drift.

VERIFY: pnpm run typecheck is green (watch for Effect β.103 API changes).

VERIFY: Persistence, contracts, trading-contracts, and orchestration test suites pass.

VERIFY: scripts/check-fork-independence.ts still passes.

AFTER: Branch pushed as sync/upstream-2026-08-04 (no force-push to main).

AFTER: PR opened; backup branch retained until next sync is confirmed green.

ROLLBACK (if needed): git checkout main && git reset --hard backup/main-pre-sync-YYYYMMDD — no force-push to shared main without sign-off.

▲

Rollback plan

If verification fails and a clean fix is not obvious, abort the merge (git merge --abort if unresolved, or abandon the branch), restore from backup/main-pre-sync-YYYYMMDD, and re-attempt with Strategy E (phased) to isolate which upstream batch introduced the failure. Never force-push main without explicit sign-off.