feat(edgesync): bundle acknowledgment, closing the air-gap loop (#569)

[xe-nvdk]

PR 9d of 4 — the last of item 9. Follows #580 (ledger state), #581 (export), #582 (import). This closes #569's phase 1.

Summary

On a successful import the hub writes a signed ack.json into the bundle directory, so the drive going back carries its own receipt and cannot be separated from what it answers. The spoke verifies it and advances those files from exported to synced.

That advance is the whole point. Before it, synced was unreachable on an air-gapped spoke: PruneSynced never pruned and the ledger grew without bound on the box least able to receive a site visit. Verified live:

after export:   pending 0   exported 4   synced 0
after import:   (hub holds 4 files, writes ack.json to the drive)
after ack:      pending 0   exported 0   synced 4

A fourth HMAC family, sync-ack (length 8 — distinct from sync-file 9, sync-bundle 11, sync-reconcile 14, so length-prefixing keeps all four non-interchangeable). The hub signs with the same per-spoke secret the spoke signs with: it is symmetric, so the key that proves authorship also proves receipt. No new key material.

The spoke recomputes the path digest rather than trusting the one in the file. The MAC binds the digest, so a tampered path list carrying a stale digest would otherwise validate and license marking files synced that no hub ever received — silent data loss, since the spoke then stops re-sending them.

Conflicted paths are not acknowledged. A conflict means the hub holds different content there, so the spoke's copy was never delivered; those stay exported and are reported for a human.

The cross-PR regression

Found by tracing 9b against 9d, not by any test: writing ack.json into the bundle broke BundleReader.Verify. 9b's rejectUndeclared refuses any file not named in entries.jsonl — added in response to a review finding, and exactly what caught this. An operator auditing a returned drive got "unsigned payload", and a re-import was refused with 422 instead of 409.

ack.json is now exempt from the manifest digest (it cannot be covered — it is created after the manifest is signed) but not from its own signature: a replaced ack still fails ReadAck, and a decoy beside it still fails verification. The exemption is an exact match, so ack.json.bak, ack.json2, case variants, and a directory of that name are all still refused.

Review findings, fixed

AckResult.Unknown collapsed three cases that mean opposite things: already-synced (benign replay), untracked (a restored spoke), and a terminally failed entry the hub says it holds. Only the third means something is wrong, and it was invisible — an ack naming one never-tracked and one failed path reported unknown=2, indistinguishable. Now split, with a warning on the discrepancy case only. A failed entry is still never resurrected.

Test plan

• 8 ack tamper cases: path added, path removed, MAC, bundle ID, import time, another hub, another spoke, namespace escape
• Round trip verified to fail without ack writing (mutant compiled first)
• Re-verification exemption verified to fail without it
• Conflicts not acknowledged; re-applying is a no-op; missing ack distinguishable from invalid; oversized ack refused; non-advanced paths classified
• Live two-process round trip: import 4, acknowledged drive re-imports as 409 not 422, ack advances exported 0 / synced 4, replay reports already_synced: 3 with no discrepancy
• go test -race, go vet, gofmt clean on a cleared test cache

Docs

Basekick-Labs/docs.basekick.net#23 — stacked on #22.

🤖 Generated with Claude Code