feat: exclusive-access gate -- refuse WS/CF schema changes while FLEx holds the project

[MattGyverLee]

Summary

Shared mode lets the MCP write while FieldWorks has a project open. Two kinds of change are still unsafe from a peer:

• writing-system changes crash the FLEx that holds the project (seen live);
• custom-field definitions are silently lost (from LCM source).

This PR adds the refusal that shared mode was missing, plus the follow-ups around it. Spec: specs/exclusive-access-gate/ (successor to #93).

• New error requires_exclusive_access. It refuses a write-enabled run_module whose script makes such a change when the probe says open_shared or unknown. The refusal comes before confirmation, backup and subprocess. open_exclusive / held_by_other still give project_locked, and read-only runs and ordinary edits are never gated.
  • Detection reuses the read-only certifier's resolved rows (accessor, alias, facade, XOperations(project)) and adds an AST pass for raw LCM names (server/exclusive_access.py).
  • A second AST layer (_facade_generic_matches) catches Create/Delete on an untyped <x>.WritingSystems / <x>.CustomFields receiver, including a local alias, a chained rebind, a module-level alias, or a for loop over a literal list. The certifier leaves these as unresolved_receiver rows. Values derived from the facade (p.WritingSystems.GetAll()) are not gated. Not followed yet: tuple unpacking and with ... as bindings.
  • The error-code count goes from 47 to 48 (main's unknown_method, [WM] Nonexistent method (ParserOperations.TryWord) classified as mutating -> unprotected_writes loop; return unknown_method + did-you-mean #306, took it to 47 first). The change is additive under tool-responses/1.x, with a golden fixture.
• Conditional WritingSystems.Ensure() (FR-002b). An Ensure() is checked first instead of refused outright.
  • The project's active lists (CurVernWss / CurAnalysisWss) are streamed from the .fwdata: no project open, about 150 ms, then cached on (size, mtime).
  • An already-active literal tag runs. A tag that would be added is refused up front with the reason. A non-literal tag, or an unreadable file, is left to flexicon's new peer schema guard (feat(ws): peer schema guard -- refuse WS schema writes from a shared-mode peer flexicon#601), which raises before writing.
  • That runtime refusal is mapped to the same code with stage: runtime. The guard is also on for every write-enabled run on a gated verdict, as a backstop.
  • This fails closed without flexicon#601: Ensure() is refused as before.
• validate_only gains project_lock.exclusive_access = {required, operations, blocking, ...} and makes the same decision as the real run.
• Messages:
  • an open_shared project-open failure no longer says "Close FieldWorks and retry";
  • the open_shared advisory points at the refusal;
  • the gate has its own assistance hint.
• Docs:
  • the remaining undo claims are removed (workflow-summary.md, the style guide, flextools_start's description);
  • SHARED-MODE.md documents the refusal and the conditional Ensure(), how to see an MCP change in FLEx (navigate away and back; F5 alone is not enough), why FLEx's Undo cannot reverse an MCP write, and that the save-conflict hazard is fixed in flexicon 4.6.0.

Merge with main

origin/main is merged in (merge commit, no rebase): #306/#338/#339/#342 unknown_method, #315/#336 project_locked next_steps, #341 archive move of shared-mode-access, and dependency bumps. Conflicts were resolved by keeping both sides:

• docs/TOOL-CONTRACT.md: main's project_locked row with next_steps, next to requires_exclusive_access.

• execution.py _diagnose_project_open_error: main's own-worker holder check (project_locked by a python PID the model cannot end; verify whether holder is the idle parse worker #315) runs first, then the FR-011 open_shared hint.

• response_models.py and the two count tests: both codes listed, and the count is 48 everywhere (TOOL-CONTRACT, response_models, tests, CHANGELOG).

• docs/SHARED-MODE.md: the branch's expanded WS/CF table, Ensure() section and corrected LCM citations. Evidence paths now point to specs/_archive/shared-mode-access/, and so does exclusive_access._WS_LIVE_EVIDENCE.

• "Close FieldWorks" message class: reviews/pattern-audit-close-fieldworks.md. Three sites fixed; three kept, with the reason for each.

• Detector shape (receiver/name matching, role confusion): reviews/sweep-detector.md. No sibling found in the detector. Pre-existing write-gate siblings in validators.py are logged as filing candidates.

• Untyped-facade receivers: nothing else in src/ matches certifier rows by name with a generic-name exclusion. unresolved_receiver rows come only from validators.py:6993/7013, and _raw_matches already uses the whole receiver chain.

• After the merge: the stale error-code counts and specs/shared-mode-access/ paths were swept. Remaining hits are intentional (they point to the predecessor's AS-BUILT, or are historical task text).

Tests

• tests/test_exclusive_access_detect.py (78, including 10 untyped-facade cases), tests/test_exclusive_access_gate.py (43) and tests/test_docs_no_undo_claims.py.
• Contract, diagnosis and advisory tests updated.
• Full offline suite after the merge: 5065 passed, 4 skipped. Goldens up to date; validate_integrity.py server clean; pre-commit clean.

Live verification (Sena 3, FieldWorks PID 27984, sharing on): specs/exclusive-access-gate/evidence/live-gate.md

• V1: Ensure refused; .ldml unchanged; no backup; FLEx responsive
• V2: validate_only gives blocking: true
• V4: an ordinary write proceeds with the new advisory
• V5: sync-at-open made no difference to a read-back (it saw the write because idle FLEx had already flushed), so it is not shipped
• V8a-d: conditional Ensure allowed / refused up front / refused at run time / refused without the guard; WS lists unchanged
• V6: after reopening FLEx the MCP gloss is present and Undo is empty (in-session navigate-away and Undo-omits-peer-write not re-tested; see evidence)
• V7: a peer-added custom-field definition never reached the master, other peers or disk (silently lost, confirmed live)
• V3: no-op Ensure with FLEx closed passes the gate and writes nothing; FLEx reopens cleanly
• Cleanup: zzExclTest entry deleted; qaa-x-zzexcl residue removed

Before merge

• T048 (maintainer): flexicon#601 is merged on flexicon main but not released (latest is 4.11.0). Release it, then regenerate the MCP indexes against that release, and optionally raise the pyflexicon floor (flexicon-first release order). Until then, conditional Ensure() fails closed. This PR stays a draft until T048 is done.
• Filed from the ledger (T035): flexicon#602-#609, bug: run_module drops report messages when the script raises #347-bug: unprotected_writes gate does not accept a compound guard (if modifyAllowed and ...:) #352. Still open, for the maintainer: whether ProjectSettingsOperations.SetDefaultVernacular/Analysis belong in the gated list.

🤖 Generated with Claude Code