Preserve and restore pending explicit permissions

[marcleblanc2]

Problem

setRepositoryPermissionsForUsers replaces a repo's whole explicit list — real grants AND pending rows (bindIDs that never resolved to a user, i.e. grant-before-first-login). Every overwrite this tool sent silently deleted pending grants on the touched repos, and snapshots only recorded a flat bindID list, so a restore could never recreate them: silent, irreversible data loss.

Server-side mechanics confirmed in sourcegraph/sourcegraph: unresolved bindIDs in the mutation become pending_repo_permissions rows in the same transaction (scoped to service_type='sourcegraph', so code-host-synced pending permissions are unreachable and unaffected), and authorizedUserRepositories falls back to the pending store for bindIDs with no matching user — the only API exposing which repos a pending bindID has.

Change

The script now neither creates nor loses pending explicit permissions:

• Snapshots (schema v5 → v6) capture pending_users: bindID → pending repos, via the authorizedUserRepositories late-binding fallback. Capture re-checks the pending list and drops bindIDs that became real users mid-run; any lookup failure aborts the capture rather than writing a snapshot with missing grants.
• set --full resends each repo's current pending bindIDs in overwrite payloads (from the before-snapshot, or fetched live with --no-backup).
• restore replays the target snapshot's pending grants — including repos that had only pending grants — and wipes pending grants the snapshot does not contain.
• Snapshot diffs report pending bindIDs added/removed/changed; post-apply validation gains a pending-preservation gate; the restore residual check catches pending drift.
• Additive paths (set --users, user-scoped restore) use per-user mutations that never touch pending rows — unchanged.

Testing

• Fixture fake mirrors the real resolver (unknown bindIDs become per-repo pending rows); new cases full-overwrite-preserves-pending and restore-restores-pending, plus a new randomized invariant: "set --full neither creates nor loses pending grants".
• Live coverage automated end-to-end: the live fixture runner seeds per-repo pendingBindIDs from fixture state, independently reads them back, asserts they survive the apply, and restores them away. full-overwrite-unions seeds one pending bindID on a mapped repo (survives its overwrite) and one on an unmapped canary (stays untouched).
• tests/setup.py deletes leftover synthetic pending bindIDs (perms-sync-test-pending-* prefix, from interrupted runs) with --apply, verified by read-back; pending bindIDs of unknown origin are still reported and never deleted.
• Local suite 102/102; full live suite against the test instance 104/104 with clean end-of-run hygiene. Also verified manually against the live instance: seed → get captures it → set --full --apply preserves it → manual wipe → restore --apply recreates it exactly ("VALIDATION OK: post-restore state matches the snapshot exactly").

Caveats

• Snapshot schema bumped to v6: restore refuses before.json files written by older releases (strict version check, consistent with previous bumps).
• The Bitbucket project bulk-permissions worker writes pending rows into the same sourcegraph namespace; this tool preserves those too (indistinguishable from explicit-API pending grants).