Skip to content

Commit 6f33ca0

Browse files
donjor-agent[bot]donjor
authored andcommitted
feat(fork-sync): resolutions persist as git data between runs (#1849)
* feat(fork-sync): resolutions persist as git data between runs Fork-Domain: fork-meta Fork-Tier: core * fix(fork-sync): exports keep every imported rerere id; fixups apply only to a fresh rebase Fork-Domain: fork-meta Fork-Tier: core * fix(fork-sync): a kept worktree pins its imported resolution Fork-Domain: fork-meta Fork-Tier: core * refactor(fork-sync): resolution transport moves out of the driver Fork-Domain: fork-meta Fork-Tier: core --------- Co-authored-by: donjor <[email protected]>
1 parent 01547bb commit 6f33ca0

7 files changed

Lines changed: 511 additions & 74 deletions

File tree

‎.agents/skills/fork-sync/SKILL.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,7 @@ The expected-old lease lost; someone landed first.
9595

9696
## Unblock
9797

98-
The driver resolves every seam it can: local rerere replays resolutions within the run's rebase, and hook re-apply re-inserts marked fork hooks.
98+
The driver resolves every seam it can: rerere replays resolutions from this rebase and [`sync/resolution`](#job-mode), and hook re-apply re-inserts marked fork hooks.
9999
Only a `manual` row stops the run.
100100

101101
In the rebase, resolve minimally: upstream's text stands, and a marked fork hook goes back verbatim.
@@ -143,6 +143,31 @@ The body keeps its open-since date, target count, and last five runs; a clean ru
143143
3. `git reset --hard <sha>`.
144144
4. Rerun `vp run fork:sync <tag>`.
145145

146+
## Job mode
147+
148+
A job resolves a blocked sync without writing the trunk or the candidate.
149+
It hands its resolutions to the next run as data on `sync/resolution`.
150+
151+
1. Run `vp run fork:sync <tag> --dry-run`
152+
2. Resolve `manual` paths per [Conflict](#conflict)
153+
3. `git add` them in the kept worktree; rerun
154+
4. Repeat until the rebase finishes
155+
5. Commit tip adaptation there; rerun once
156+
6. `git update-ref --no-deref HEAD refs/fork-sync/resolution`
157+
7. Report `committed`: rsi-pr-agent pushes `HEAD`
158+
159+
Every rebase rewrites `refs/fork-sync/resolution` before `ci`, so a `ci` failure in the job is expected.
160+
It is one parentless commit:
161+
162+
```text
163+
rr-cache/<id>/preimage one per resolved stop
164+
rr-cache/<id>/postimage
165+
fixups.mbox tip commits above the rebase
166+
```
167+
168+
The next run imports it before it rebases: rerere replays each stop, and the fixups apply when its `Fork-Sync-Tag` matches.
169+
Anything else on the branch fails the run.
170+
146171
## Never
147172

148173
- **Post** to `pingdotgg/t3code`

‎docs/fork/operations/fork-sync.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ Conflict resolution is machine-owned, in this order.
9090

9191
| # | Rule |
9292
| --- | ------------------------------------------------------------------------------------------------------------------------------ |
93-
| 1 | Local rerere replays resolutions within the run's rebase and stages them |
93+
| 1 | Rerere replays resolutions from the run's rebase and [`sync/resolution`](#resolution-data), and stages them |
9494
| 2 | Hook re-apply re-inserts the marked fork hooks a conflicted file declares, from the fork side onto the upstream text |
9595
| 3 | An upstream delete of a path whose fork trunk blob still equals the base blob (a net-zero fork edit) is accepted with `git rm` |
9696
| 4 | A [regenerable file](#regenerable-files) regenerates once every other path in the stop resolves |
@@ -100,6 +100,27 @@ Only upstream moved: upstream's text stands.
100100
A marked fork hook goes back in verbatim, shifted only when upstream re-indented its anchor.
101101
There is no "upstream superseded this" rule: retirement is a traced verdict written in [fork-delta](../internals/fork-delta.md), never a merge rule.
102102

103+
## Resolution data
104+
105+
Every CI run starts on a fresh runner, so `.git/rr-cache` and tip fixups die with it.
106+
The driver keeps them as git data instead.
107+
108+
- **Export:** `refs/fork-sync/resolution`, per rebase
109+
- **Shape:** one parentless commit, no workflows
110+
- **Contents:** resolved rerere, `fixups.mbox`
111+
- **Scope:** this sync's stops and every import
112+
- **Push:** rsi-pr-agent or a hand resolver
113+
- **Import:** each run, before the rebase
114+
- **Rerere:** joins rr-cache, never replacing
115+
- **Fixups:** `git am --3way` atop a fresh rebase
116+
- **Fixup gate:** `Fork-Sync-Tag` is the target
117+
- **Kept worktree:** pins its import; a moved branch refuses
118+
- **Carry plus fixups:** refuses the run
119+
- **Refusal:** any other path fails the run
120+
121+
The driver reads the branch as data only; nothing on it executes.
122+
The [job mode](../../../.agents/skills/fork-sync/SKILL.md#job-mode) runbook produces it.
123+
103124
## Attention issue lifecycle
104125

105126
Every red run (blocked or failed) rewrites one standing sync attention issue through plain `gh`, after writing its report.

‎scripts/fork-sync.test.ts‎

Lines changed: 84 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,18 @@ import {
1717
refuseDroppedLinks,
1818
resolveFixups,
1919
publishAttention,
20-
realRunner,
2120
rebaseOnto,
2221
readReport,
2322
REGENERATION_ROUTES,
2423
resolverText,
2524
renderReport,
2625
reportPath,
2726
run,
28-
type CommandRunner,
2927
type ForkSyncReport,
3028
} from "./fork-sync.ts";
3129
import { runCommand, type CommandResult } from "./lib/fork-command.ts";
3230
import { GENERATED_HOOK_PATH } from "./lib/fork-hook-guard.ts";
31+
import { realRunner, type CommandRunner } from "./lib/fork-sync-git.ts";
3332
import { FOLD_MESSAGES_ENV, placeFixups, sequenceEditor } from "./lib/fork-sync-todo.ts";
3433

3534
const ok = (stdout = ""): CommandResult => ({ status: 0, stdout, stderr: "" });
@@ -324,6 +323,89 @@ it("stops at a conflict rerere and hooks cannot resolve, then applies after a ha
324323
);
325324
});
326325

326+
it("carries a hand resolution and its fixups to a fresh runner through sync/resolution", () => {
327+
withFixture(
328+
{
329+
forkContent: "line1\nline2 fork\nline3\n",
330+
upstreamContent: "line1\nline2 upstream\nline3\n",
331+
},
332+
(f) => {
333+
const resolve = (): number =>
334+
capture(() => run(["v1.0.0", "--dry-run"], { runner: exec().runner, root: f.root })).value;
335+
assert.strictEqual(resolve(), 1);
336+
NodeFS.writeFileSync(
337+
NodePath.join(f.worktree, "shared.txt"),
338+
"line1\nline2 resolved\nline3\n",
339+
);
340+
f.git(["add", "shared.txt"], f.worktree);
341+
assert.strictEqual(resolve(), 0);
342+
NodeFS.writeFileSync(NodePath.join(f.worktree, "fix.txt"), "fix\n");
343+
f.git(["add", "fix.txt"], f.worktree);
344+
f.git(["commit", "--quiet", "-m", "fix: the candidate needs this"], f.worktree);
345+
assert.strictEqual(resolve(), 0);
346+
347+
// the export: one parentless commit of rerere entries and the fixups
348+
const exported = "refs/fork-sync/resolution";
349+
const exportedRerere = (): string => f.git(["ls-tree", "-r", exported, "rr-cache"], f.root);
350+
assert.strictEqual(f.git(["rev-list", "--count", exported], f.root), "1");
351+
assert.match(
352+
f.git(["ls-tree", "-r", "--name-only", exported], f.root),
353+
/^fixups\.mbox\nrr-cache\/[0-9a-f]+\/postimage\nrr-cache\/[0-9a-f]+\/preimage$/,
354+
);
355+
const pushed = exportedRerere();
356+
assert.strictEqual(
357+
f.git(["log", "-1", "--format=%(trailers:key=Fork-Sync-Tag,valueonly)", exported], f.root),
358+
"v1.0.0",
359+
);
360+
f.git(["push", "--quiet", "origin", `${exported}:refs/heads/sync/resolution`], f.root);
361+
362+
// a fresh runner: no worktree, no state, no rr-cache
363+
f.git(["worktree", "remove", "--force", f.worktree], f.root);
364+
NodeFS.rmSync(NodePath.join(f.root, ".t3", "fork-sync", "worktree.json"));
365+
NodeFS.rmSync(NodePath.join(f.root, ".git", "rr-cache"), { recursive: true });
366+
assert.strictEqual(resolve(), 0);
367+
const tip = readReport(f.root, "v1.0.0").trunk.after!;
368+
assert.strictEqual(
369+
f.git(["show", `${tip}:shared.txt`], f.root),
370+
"line1\nline2 resolved\nline3",
371+
);
372+
assert.strictEqual(
373+
f.git(["log", "-1", "--format=%s", tip], f.root),
374+
"fix: the candidate needs this",
375+
);
376+
// the replayed stop records nothing, yet exports again
377+
assert.strictEqual(exportedRerere(), pushed);
378+
// a rerun on that finished worktree keeps its tip; the fixups never stack twice
379+
const rerun = capture(() =>
380+
run(["v1.0.0", "--dry-run"], { runner: exec().runner, root: f.root }),
381+
);
382+
assert.strictEqual(rerun.value, 0);
383+
assert.notMatch(rerun.output, /applying the fixups/);
384+
assert.strictEqual(readReport(f.root, "v1.0.0").trunk.after, tip);
385+
386+
// a resolution the kept worktree never imported refuses its adoption
387+
const moved = f.git(
388+
["commit-tree", `${exported}^{tree}`, "-m", "other", "-m", "Fork-Sync-Tag: v1.0.0"],
389+
f.root,
390+
);
391+
f.git(
392+
["push", "--quiet", "--force", "origin", `${moved}:refs/heads/sync/resolution`],
393+
f.root,
394+
);
395+
assert.strictEqual(resolve(), 1);
396+
assert.match(readReport(f.root, "v1.0.0").error ?? "", /sync\/resolution moved to/);
397+
398+
// the branch is data only: a tree of anything else refuses the run
399+
f.git(["push", "--quiet", "--force", "origin", "hyprws:refs/heads/sync/resolution"], f.root);
400+
assert.strictEqual(resolve(), 1);
401+
assert.match(
402+
readReport(f.root, "v1.0.0").error ?? "",
403+
/sync\/resolution holds shared\.txt, which is not resolution data/,
404+
);
405+
},
406+
);
407+
});
408+
327409
it("runs the repo's worktree setup once, so the first stop already has its dependencies", () => {
328410
withFixture(
329411
{

0 commit comments

Comments
 (0)