PT-4214 Stage U: backend-authoritative per-project S/R block signal (E2E defects 2+3)

[rolfheij-sil]

What

PT-4214 Stage U slice: the backend SendReceiveWriteLock becomes the single, per-project
block-signal authority for ALL sync types (manual, scheduled, startup/shutdown), and the
renderer consumes it as a snapshot. Fixes two of Rolf's 2026-07-16 E2E defects at the root:

• Manual S/R now blocks editing of the synced project (defect 2): the signal originates
  from the gate the Streamlined a number of npm scripts #164 bracket arms on every sync path — no UI path can miss it.
• Only the synced projects' editors are blocked (defect 3): rejection and the renderer
  driver are both per-project now (previously: global latch, every Scripture editor frozen).

C# (public core, inert upstream)

• SendReceiveWriteLock.EnterWrite rejection is now per-project (armed ∧ projectId ∈ blocked set); the drain stays global. This deliberately reverses the "global gate"
  rejection semantics shipped in PT-4159: auto-sync blocking overlay (edit block for scheduled S/R) #2555/PT-4159: Rebuild S/R write gate without thread affinity #2564: an armed gate rejecting writes to projects it
  isn't syncing is exactly E2E defect 3 at the data layer (once Streamlined a number of npm scripts #164 arms the gate for real),
  and PT9 parity locks only the syncing project. Memory-ordering is unchanged and safe: the
  volatile blocked set is published before the arming CAS, so an armed reader always observes
  the matching set (reasoning documented at the check; reviewed adversarially — verdict sound).
  The EnterWrite_WhileAnotherProjectSyncs_RejectsAllProjects_GlobalGate test was consciously
  replaced by per-project equivalents.
• New change surface: BlockStateChanged event + GetBlockState() snapshot (raised post-arm /
  post-real-disarm only; stale-token and no-op clears don't raise; out-of-order delivery in
  off-contract crash-recovery races documented as accepted YAGNI).
• New SendReceiveBlockNotifierService: forwards gate transitions as network event
  paratextBibleSendReceive.onSyncWriteLockChanged ({ isBlocking, projectIds } snapshots) and
  serves paratextBibleSendReceive.getAutoSyncBlocking — the command Auto-sync edit-block follow-ups from #2555 review (PT-4159 / PT-4214 Stage T) #2571's init-seeding
  already calls but nothing served until now. Deviation from PT-4214's open item: the ticket
  suggested registering that command ext-side; serving it from C# is the Stage U end state (the
  gate IS the authority, and it works for all sync types + before extension activation). Round 4: the event is now
  formally registered with main's central event registry at init via a generic
  network:registerEvent request (that method already serves every websocket client; no new
  API — mirrors RegisterRequestHandlerAsync's network:registerMethod call), so the boot-time
  “announced but is not registered” deprecation warning no longer applies to this event. Emission
  itself still follows the SharedStore SendEventAsync precedent; the other C#-origin events
  (<id>-pdp-data:onDidUpdate, shared-store:change) remain on the legacy unregistered-announce
  path — platform-wide migration debt, out of scope here.
• Sentinel (SR_EDIT_BLOCKED) byte-identical; SetSyncing/Clear/EnterWrite signatures
  unchanged (the in-flight Streamlined a number of npm scripts #164 patch bracket compiles against this unmodified).

Renderer

• auto-sync-blocking-store: ref-count latch → snapshot of blocked projectIds (200 ms
  show-grace kept). The Stage-T per-blocker safety leashes are deleted, not retained — per
  the ratified PT-4214 §5.2 ("a second, timer-driven opinion about blocking is precisely the
  drift findings 7/8/16 indict"); resilience is re-query of the authority.
• auto-sync-blocking-service: subscribes onSyncWriteLockChanged only — the ext-emitted
  onAutoSyncBlockingChanged subscription is removed (single source, finding 16). Init
  consult of getAutoSyncBlocking kept (now actually served), live-event-wins guard kept,
  malformed payloads fail safe to unblocked.
• auto-sync-edit-block-driver: flags an editor iff definition.projectId is in the blocked
  set; handles partial set transitions ({A,B}→{A}, {A}→{B} swap) with the
  unsubscribe-before-unflag ordering preserved (the PT-4159: auto-sync blocking overlay (edit block for scheduled S/R) #2555 live-E2E permanent-block bug class);
  regression tests cover full clear, shrink, swap, grow, rebuilt-mid-block, no-projectId.

Runtime pairing (IMPORTANT)

The signal only fires once the studio patch arms the gate — merge in the same window as
studio #164 (gate arming + stall watchdog). Pairings:

• this PR + Streamlined a number of npm scripts #164 ⇒ full per-project blocking for all sync types (target state);
• Streamlined a number of npm scripts #164 without this PR ⇒ today's behavior (ext-driven block-all on scheduled syncs) + backend
  global rejection — no regression;
• this PR without Streamlined a number of npm scripts #164 ⇒ no edit-block UI in dev builds until Streamlined a number of npm scripts #164 lands (the ext event chain
  loses its listener). Don't ship a build in that window.

Once merged, the ext engine's onAutoSyncBlockingChanged emit chain
(in the send-receive extension's activation + engine setBlocking path) is vestigial —
removal tracked on PT-4214 (Stage U cleanup), not done here to keep #186's review diff stable.

Out of scope (Stage U remainder, tracked on PT-4214)

Finding 18's editor-mount refactor (driver deletion), the shared latch-store extraction,
throwOnDrainTimeout upgrade path, seam d.ts declarations for the new event/command (deferred
to avoid colliding with #2570's d.ts re-home; the renderer/service use local types).

Verification

C# dotnet test: full suite 1528 passed / 0 failed / 6 skipped (now 1529 with the review-fix
test); SendReceive-filtered 66/0; CSharpier clean. Renderer: targeted 50/0 across
store/service/driver; full core TS suite 1018/0 including app.component.test; typecheck clean
(one pre-existing unrelated buildInfo.json error). Both halves adversarially reviewed
(finder→refuter); all surviving findings fixed in 438d1dd / 506e9fc, including a truthful
armed-empty-set warning and observed (logged) notifier faults. Round 4: central-registry
registration added in 756d33e (SendReceive-filtered 67/0; full C# suite 1530/0).

Rebase note (2026-07-17) — re-seated on #2571's review-fix round

Rebased onto #2571's new tip 56b9934560a (lyonsil's 19-finding review fix round: identity release
tokens in both stores, inert seeding cut, hook types, smalls). Expected supersession: #2571's
auto-sync store/service fixes conflict with this branch's snapshot rewrite and resolve to this
branch's versions — the snapshot model makes the anonymous-pairing problem the #2571 fixes
mitigated unrepresentable. One reconciliation commit added:

• 08d0d3d31ac — drops Auto-sync edit-block follow-ups from #2555 review (PT-4159 / PT-4214 Stage T) #2571's anonymous-boolean integration test (its event seam —
  onAutoSyncBlockingChanged + raise/clear pairing — no longer exists here), updates the
  index.tsx startup comment for the reintroduced async init consult (Auto-sync edit-block follow-ups from #2555 review (PT-4159 / PT-4214 Stage T) #2571 review finding 13),
  reconciles the AUTO_SYNC_MAX_DURATION_MS doc (keeps Auto-sync edit-block follow-ups from #2555 review (PT-4159 / PT-4214 Stage T) #2571's app-driven definition + this
  branch's leash-deletion paragraph), and commits the papi.d.ts drift.

Post-rebase verification: renderer suite 548 passed, full typecheck clean (all workspaces), C#
suite 1530 passed / 0 failed, stack linearity verified (#2571 → #2574 → #2575).

Follow-up rebase (2026-07-17): rebased onto 37d955d1583 (papi.d.ts regen fix).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VkhEPs8ocAzX4117dtfWLA

Self-review — 2026-07-17 (review-paratext methodology)

No Critical/Important defects; the per-project reversal of #2564's global gate is sound and correctly re-tested. Four analysis passes (api / style / compliance / ux) per .claude/agents/review-analyzer.md, run by a review-lead agent; author interview substituted with the PR body + PRD design records; every finding adversarially verified against code and tests.

#	severity	finding	disposition
1	minor	SendReceiveBlockNotifierServiceTests doesn't exercise the registration-failure/exception paths (DummyPapiClient hard-codes success)	fixed in 234e46a
2	minor	leash deletion means a lost mid-session event leaves a stale read-only banner until the next transition/reload	author-context: addressed (ratified design §5.2; PT-4214 tracks editor-mount re-query)
3	minor	isProjectBlocked is exported and unit-tested but has no production consumer in this PR	author-context: addressed (#2575 consumer)

Verified wins: the per-project EnterWrite reversal is sound (narrowing rejection can only allow more writes, never fewer); the memory-ordering argument (volatile publish-then-flag / acquire-release pairing) is correct.

Gates: C# SendReceive-filtered 67/0, renderer targeted 50/0, typecheck:core clean (one pre-existing unrelated build-artifact error).

---

This change is 

[lyonsil]

A few review comments below, from an AI-assisted review pass with my guidance. These are a curated subset of findings, mostly cleanups plus a couple of correctness notes (the lost-disarm recovery gap and the renderer case-sensitivity). Happy to discuss any of them.

(AI-assisted, with my guidance)

[lyonsil]

Lost-disarm recovery gap — please add a pointer comment, not a code fix.

The SAFETY_TIMEOUT_MS leash is gone and this init consult is the only backend re-query — there's no re-query on websocket reconnect, C# data-provider restart, or editor mount. So if a disarm is ever lost (the data provider restarts mid-sync and comes back disarmed without re-emitting a disarm for the old arm; a fire-and-forget SendEventAsync faults; an off-contract raise reorders), the store stays non-empty and the affected editors are stuck read-only until the next transition or a full renderer reload — strictly worse than the deleted 10-minute leash, which recovered from exactly this.

I'm not asking for a code fix here — the editor-mount / reconnect re-query is the real fix and it's tracked as out-of-scope Stage-U work. But please add a short comment at this consult noting it's the only re-seed today and that lost-event recovery depends on the PT-4214 editor-mount re-query, so the gap is visible to the next reader rather than implied by the "resilience is re-query of the authority" line in the PR description.

(AI-assisted, with my guidance)

[lyonsil]

Normalize project-id case once, at ingestion — don'''t rely on the front end matching case.

The C# gate matches ids with StringComparer.OrdinalIgnoreCase (its field comment even says "project ID casing varies across call sites"), but everything on the renderer side is case-sensitive: this new Set(projectIds), isProjectBlocked'''s Set.has, and the driver'''s isEditorBlocked. On any casing skew between the synced id and an editor'''s projectId, no banner shows while the backend still rejects each save with the sentinel → silent type-and-revert.

There are too many spots in the TS to make each comparison case-insensitive, and Set/map keys can'''t express a case-insensitive compare cleanly anyway. Let'''s canonicalize to a single case once at ingestion — here where the snapshot enters the store — and canonicalize the editor projectId the same way before the has check in the driver.

Confirmed the canonical case is upper: ProjectMetadata.Id is id.ToUpperInvariant() (c-sharp/Projects/ProjectMetadata.cs:15) and the editor'''s projectId flows from projectMetadata.id, so .toUpperCase() on both sides. Keep the C# OrdinalIgnoreCase as a nice backend fallback, but the front end shouldn'''t assume it can handle mixed case.

(AI-assisted, with my guidance)

[lyonsil]

Don't advance appliedBlockedProjectIds when the apply silently failed.

applyBlockedSetToAllEditors(next) swallows a getAllOpenWebViewDefinitionsSync throw and returns early without flagging anything (the dock-not-registered case), but we still record appliedBlockedProjectIds = new Set(next) here. If the set then stays the same, the areSetsEqual guard at the top of syncState short-circuits every later notification, so any editor that was open-but-unenumerable at that instant never gets flagged for the rest of the sync (only newly opened/rebuilt ones get caught by the handlers).

Have applyBlockedSetToAllEditors report whether it actually applied, and only advance appliedBlockedProjectIds on success.

(AI-assisted, with my guidance)

[lyonsil]

Subscribe to the gate before the registration round-trip.

We subscribe to BlockStateChanged here, after awaiting network:registerEvent. A gate transition during that await window isn't forwarded (no subscriber yet). Since an early unregistered announce is harmless (main just logs the deprecation warning), moving the += above the registration await closes the window. Startup-only and inert in core, but cheap to make airtight.

(AI-assisted, with my guidance)

[lyonsil]

Arm event fires before the drain → editors flash read-only on a throwOnDrainTimeout rollback.

This raises (true, ids) before the drain. On the throwOnDrainTimeout rollback path the arm still fires this event → the renderer flags the project's editors read-only after the grace → the drain times out (seconds) → the rollback Clear(token) raises (false, []) and unblocks. Net: editors are needlessly read-only for the whole failed-drain window on a sync that aborted and touched no files.

throwOnDrainTimeout is out-of-scope here so not a blocker, but worth a note (or defer the arm-side raise until after a successful drain on that path) for whoever wires it.

(AI-assisted, with my guidance)

[lyonsil]

rawBlockedProjectIds writes are dead in 2 of 3 branches.

rawBlockedProjectIds is written on every setBlockedProjects call but read only in the grace-timer callback. In the cleared branch the write is immediately followed by cancelling the only timer that reads it, and in the already-visible branch there's no pending grace to read it — so those two writes are dead stores (and the empty-input case allocates a throwaway Set). Scoping the assignment to the arming branch would make it clear raw is only consumed by the grace.

(AI-assisted, with my guidance)

[lyonsil]

Not-blocking snapshot is built at three sites.

new SendReceiveBlockState(false, []) is constructed here, in Clear(long), and in GetBlockState's empty branch. A single private static readonly SendReceiveBlockState NotBlocking = new(false, []) (fine for a readonly record struct) would centralize it and keep the empty shape consistent across the disarm and pull paths.

(AI-assisted, with my guidance)

[lyonsil]

Consider a PapiClient.RegisterEventAsync wrapper instead of a raw SendRequestAsync.

This hand-rolls the network:registerEvent + accepted-bool protocol. PapiClient already centralizes the sibling network:registerMethod in RegisterRequestHandlerAsync (with its timeout-log path and optional documentation arg) but has no symmetric event wrapper. Adding RegisterEventAsync(eventType) on PapiClient and calling it here keeps the event-registration wire contract beside the method one (TS already encapsulates it in createNetworkEventEmitterAsync).

(AI-assisted, with my guidance)

[lyonsil]

Reuse isString.

platform-bible-utils exports an isString type guard, so projectIds.filter(isString) reuses the canonical guard instead of the inline (id): id is string => typeof id === 'string'. (The rest of readBlockedProjectIds's hand-rolled shape check is fine — there's no generic PAPI-payload validator to reuse.)

(AI-assisted, with my guidance)

[lyonsil]

isProjectBlocked has no consumer in this PR.

Exported and unit-tested but unused in production here (the driver uses getBlockedProjectIds + its own isEditorBlocked). Documented as ahead of the #2575 project-settings UI, so fine — just flagging it's speculative surface until that lands. (The case-normalization point applies to its Set.has too.)

(AI-assisted, with my guidance)

[lyonsil]

Re-review note on a cleanup that can't be anchored inline (its file isn't in this PR's diff):

src/renderer/services/workspace-updating-store.ts:29-30 still reads "(Same pattern as auto-sync-blocking-store; extracting a shared abstraction is deliberately deferred — PT-4214...)". This PR rewrote auto-sync-blocking-store away from that ref-count/leash model, so the reciprocal comment now points at a vanished commonality. Worth updating or removing it in the same change — the blocking store already dropped its half of the note.

(AI-assisted, with my guidance)