docs(platform): design the Cotal fork-sync + branch-model reset - #14
Open
seal-agent wants to merge 2 commits into
Open
docs(platform): design the Cotal fork-sync + branch-model reset#14seal-agent wants to merge 2 commits into
seal-agent wants to merge 2 commits into
Conversation
`sealedsecurity/Cotal` has drifted too far to keep building on: `origin/main` (`d55c6adb`) is **815 commits behind** `upstream/main` (`8571c1bb`) with 7 sealed commits, and `origin/sealed-fork` (`0106d35c`) is **33 ahead / 723 behind**. This record designs the branch-model reset Matt decided: `main` becomes a clean upstream mirror, `sealed-fork` becomes the integration branch (new `main` + sealed changes reapplied via reviewed PRs). ## What this is A design record (the plan, not the implementation) at `docs/designs/platform/cotal-fork-sync.md`. Its merge freezes the contract executing agents read. The frozen intent — sync-then-reapply — is Matt's and is not relitigated here; the record designs the HOW: migration sequence, curated reapply inventory, coordination with in-flight branches, and per-feature verification. ## Approach Hard reset + curated cherry-pick reapply, human-gated at the two shared-branch moves (Matt force-moves `main` to upstream and resets `sealed-fork` to it; archive tags pin the old tips first so no history is lost). The ~40 sealed commits collapse into 4 reapply lanes (oh-my-pi connector, zellij runtime, KV-watch-leak port, mint identity-reuse port), each its own PR with its own build+smoke gate, plus an explicit drop list (`@cotal-ai/pi` superseded by upstream's parallel `extensions/pi`; `yaml` workarounds dead now that upstream declares `yaml ^2.9.0`; `upstream-cotal-reconnect-logger` subsumed by `fe6d3ec1`). ## Red-team applied Draft was adversarially reviewed (design-critic) and every load-bearing finding verified at source before folding. The decisive correction: the connector lane (T4) is **not** the cheap tree-copy it first looked — its `loop.ts` imports `InboxTurn` from `@cotal-ai/connector-core`, a seam upstream **deleted** and re-landed in `extensions/pi` with a different contract (tombstone ledger). T4 is a semantic port on par with the others. This is surfaced as **OQ-7** (resurrect the old seam vs migrate onto upstream pi's exported ledger — recommend the latter). ## Open Questions (Matt rules before freeze) 7 load-bearing forks, each with a stated assumption + recommendation: PR #13 disposition, reapply-set curation, connector reconciliation with zheng's parallel branch, main-move execution ownership, where sealed-only artifacts live across the reset, hard-reset-vs-rename-cutover, and the connector InboxTurn strategy (OQ-7). Spec-impact: none. This is a process/branch-model design record under `docs/designs/`, not a change to `docs/specs/`. Co-authored-by: Matt Wilkinson <matt@sealedsecurity.com>
Converts the 7 Open Questions to frozen Decisions (D1-D8) per Matt's rulings on PR #14, and fixes the review agent's findings (high 0, medium 3, low 2). **Decisions:** D1 close PR #13 (superseded duplicate); D2 curated reapply set (4 groups, 3 drops); D3 hardened connector lineage, service-owner owns T4; D4 agent runs the human-gated main-move; D5 sealed artifacts land on post-reset sealed-fork (never main); D6 hard reset + archive tags; D7 connector InboxTurn migrates onto upstream pi's exported ledger (option b); D8 reapply PRs base on sealed-fork via trunk(). **Review fixes:** M1 mint git range `dca37915^..d55c6ad` (two-dot was exclusive, dropped the foundational commit, 6 not 7); M2 T6 sources fix content via `archive/pre-sync-sealed-fork` (bare SHAs orphaned post-T3); M3 PR #14 disposition (review vehicle on main, closed/retargeted at T9, never merges to main); L1 loop.ts value-import vs type-import precision; L2 path-qualified `connector-core/src/agent.ts:462` cite. Spec-impact: none. Refs Cotal-AI#181 Co-authored-by: Matt Wilkinson <matt@sealedsecurity.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
sealedsecurity/Cotalhas drifted too far to keep building on:origin/main(d55c6adb) is 815 commits behindupstream/main(8571c1bb) with 7 sealed commits, andorigin/sealed-fork(0106d35c) is 33 ahead / 723 behind. This record designs the branch-model reset Matt decided:mainbecomes a clean upstream mirror,sealed-forkbecomes the integration branch (newmain+ sealed changes reapplied via reviewed PRs).What this is
A design record (the plan, not the implementation) at
docs/designs/platform/cotal-fork-sync.md. Its merge freezes the contract executing agents read. The frozen intent — sync-then-reapply — is Matt's; the record designs the HOW: migration sequence, curated reapply inventory, coordination with in-flight branches, per-feature verification.Approach
Hard reset + curated cherry-pick reapply, human-gated at the two shared-branch moves (Matt force-moves
mainto upstream and resetssealed-forkto it; archive tags pin the old tips first so no history is lost). The ~40 sealed commits collapse into 4 reapply lanes (oh-my-pi connector, zellij runtime, KV-watch-leak port, mint identity-reuse port), each its own PR with its own build+smoke gate, plus an explicit drop list (@cotal-ai/pisuperseded by upstream's parallelextensions/pi;yamlworkarounds dead now that upstream declaresyaml ^2.9.0;upstream-cotal-reconnect-loggersubsumed byfe6d3ec1).Reviewed + ruled
Draft was adversarially red-teamed (design-critic), the sole
reviewagent passed it (high 0, medium 3, low 2 — all folded), and every load-bearing forensic claim was verified at source against both remotes. The decisive correction: the connector lane (T4) is not the cheap tree-copy it first looked —loop.tsvalue-importsInboxTurnfrom@cotal-ai/connector-core, a seam upstream deleted and re-landed inextensions/piwith a tombstone-ledger contract, so T4 is a semantic port.Matt has ruled all 7 open forks; they are now frozen Decisions (D1–D8) in the record:
main-move (T2/T3), Matt-delegated.sealed-fork, nevermain— including this record (PR docs(platform): design the Cotal fork-sync + branch-model reset #14 is a review vehicle, closed/retargeted at T9).sealed-forkviatrunk()(jj-vine can't base on a non-trunk branch).Merging this PR freezes the record; execution (T1–T9) starts from the merged contract.
Spec-impact: none. This is a process/branch-model design record under
docs/designs/, not a change todocs/specs/.Co-authored-by: Matt Wilkinson matt@sealedsecurity.com