Document replicate API and stable-surface JSON rename

416620d→main·

Soph·3mo ago·2 files·+52 added/-2 removed

Adds a CHANGELOG describing the replicate mode, the renamed execution.mode -> execution.transfer_mode field on the stable SyncResult surface, and the new top-level operation_mode on syncer.Result. Updates the embedding guide to list Replicate alongside Probe/Plan/Sync and to name the new Execution fields (OperationMode, TransferMode) in the result-handling and retry-guidance sections.

The rename is breaking for external consumers parsing execution.mode; there is no compatibility alias. This is flagged under "Changed (stable API, breaking)" in the CHANGELOG.

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Sessions

bab2cea0784aView transcript
?\ what test coverage do we have now for replicate?Claude Code·Opus 4.6[1m]·1 step

Changes

2

• ACHANGELOG.md+47

• docs

• Membedding.md+5/-2

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# Changelog

Entries are grouped per release. Unreleased changes sit at the top.

## Unreleased

### Added

- `git-sync replicate` subcommand and `git-sync plan --mode replicate` for source-authoritative, relay-only replication. Divergent branches and tags are retargeted against the source; `--prune` deletes orphan managed refs. Relay-only by design: incompatible targets (e.g. advertising `no-thin`) fail with a "use sync instead" message rather than falling back to a materialized push.
- `gitsync.Client.Replicate` on the stable embedding surface.
- `gitsync.OperationMode`, `gitsync.ModeSync`, `gitsync.ModeReplicate`, and `SyncPolicy.Mode` for selecting the mode from library callers.

### Changed (stable API, breaking)

- The stable `SyncResult.Execution` summary has a new field layout:
  - Added `execution.operation_mode` (`"sync"` or `"replicate"`) to describe the high-level product mode the caller requested.
  - Renamed `execution.mode` to `execution.transfer_mode` to describe the low-level engine path that actually executed (`incremental-relay`, `materialized`, `bootstrap-relay`, `replicate`, etc.). The previous `mode` key is no longer emitted.

External embedders that parse `execution.mode` must switch to `execution.transfer_mode`. There is no compatibility alias; the field was renamed in place.

- `syncer.Result` (the CLI-level JSON shape) gains a top-level `operation_mode` field alongside the existing relay fields. Callers consuming the flat CLI JSON can use it to distinguish sync vs replicate results.

### Fixed

- Work around a go-git v6 upload-pack bug where the server emits two consecutive `NAK` pktlines in stateless-RPC mode when the client sends haves that are not reachable from any want. The second NAK would otherwise be misread by the sideband demuxer as a frame with channel byte `'N'` ("unknown channel NAK"). `internal/gitproto.fetchPackV1` and `fetchToStoreV1` now drain trailing NAKs before handing off to the demuxer. See the corresponding go-git fix (`plumbing/transport: don't emit a second NAK after encoding empty ACKs`).

ACHANGELOG.md+47

13 unmodified lines

14
15
16
17
18
19
20
98 unmodified lines

119
120
121
121
122
123
124
125
126
21 unmodified lines

148
149
150
149
151
152
153
154
155

13 unmodified lines

- `Probe`
- `Plan`
- `Sync`
- `Replicate`
- typed requests and results
- injected auth and HTTP client support

98 unmodified lines

- `Counts`
  aggregate applied/skipped/blocked/deleted totals
- `Execution`
  protocol, relay summary, execution mode, and batch summary
  protocol, `operation_mode` (sync or replicate), relay summary,
  `transfer_mode` (the engine path that executed), and batch summary
- `Stats`
  transfer counters when requested
- `Measurement`
- retry on returned `error`
- do not blindly retry on `Counts.Blocked > 0`
- log `Execution.Mode` and `Execution.Reason` for operator visibility
- log `Execution.OperationMode`, `Execution.TransferMode`, and
  `Execution.Reason` for operator visibility

## What Not To Depend On

Mdocs/embedding.md+5/-2