Investigate how interlinear data interacts with Send/Receive

Bắt đầu với src/services/projectStorage.ts và các API extension-storage và project-data-provider được dẫn chiếu để so sánh bộ nhớ theo từng người dùng với project ExtensionData. Sau đó, lần theo auto-sync-blocking-service.ts, onSyncWriteLockChanged, onSyncStateChanged và onSyncProgress, cùng với C# provider được dẫn chiếu và tài liệu phân vùng PT9. Được xem là hoàn tất khi có một bản ghi quyết định bao quát vị trí lưu trữ, mức độ chi tiết của việc hợp nhất, cơ chế kiểm soát ghi, xử lý dữ liệu nhận được, các phiên bản model và các issue cần theo dõi tiếp.

Split out of an aside on #44: "Will the in-interlinearizer lexicon be in the interlinear project envelope or being saved to file? Will we implement it with Harmony? How will the project interact with send/receive that's now enabled in PT10?" Nothing about S/R has been decided. Where our data lives today answers the question by accident rather than by design, and the answer it gives is "not at all".

Investigation and a decision record; no implementation in this issue.

Where the data is now

Every read and write goes through papi.storage.readUserData / writeUserData in src/services/projectStorage.ts. Core resolves those to app://<extension data dir>/interlinearizer/user-data/<base64url key> (paranext-core: src/extension-host/services/extension-storage.service.ts:67-138, buildUserDataUri) — per user, per machine, per extension, outside every Paratext project folder.

Consequences, none of them chosen:

• An interlinear project cannot be shared with a team at all, by any mechanism.
• It does not follow the user to another machine, and is not backed up with the project.
• S/R cannot see it, so it also cannot conflict — the only upside.

What PT9 does, for contrast

PT9 interlinear data is a first-class synced project file type. S/R's ProjectFileType list includes interlinear ("Any file name that starts with Interlinear_") alongside lexicon (Lexicon.xml or WordAnalyses.xml) and pluginData (paranext-core: src/@types/paratext-bible-send-receive/index.d.ts:142-179). PT9 partitions as Interlinear_<lang>_<book>.xml (src/parsers/pt9/pt9-xml.md), which is also its merge granularity.

So a PT9 team already shares glosses, and a PT10 team using this extension would not — a regression from the tool we are replacing. It also breaks #150 in a specific way: importing from a synced Interlinear_*.xml into unsynced per-user storage means the two copies diverge from the first receive onward, with nothing detecting it.

The alternative that already exists

Every PDP has an ExtensionData endpoint — getExtensionData / setExtensionData scoped by { extensionName, dataQualifier } (paranext-core: src/shared/models/project-data-provider.model.ts:14-130). For a Paratext project, core's C# writes it to <project>/shared/platform.bible/extensions/<extensionName>/<dataQualifier> (paranext-core: c-sharp/Projects/ParatextProjectDataProvider.cs:327-386, c-sharp/Projects/LocalParatextProjects.cs:19) — inside the project's shared directory, which S/R classifies as sharedFiles.

That is the switch: moving there is what makes the data travel, and it is also what exposes our blob to Mercurial merge.

Questions to answer

1. In the project, or per user? Is an interlinear draft team data or personal scratch? Note the model already assumes project-scoped identity in places: sourceProjectId / targetProjectId, and the model-project and output-project pointers in #148 and #149 are PAPI project ids, which are not portable to another machine. If the answer is "team data", the storage layer is the change, and projectStorage.ts is the only place that touches storage.

2. Merge granularity. One JSON blob per project conflicts on every concurrent edit, and TextAnalysis is flat unordered arrays — close to worst case for a line-based merge. PT9's per-book/per-language split and #87's proposed per-book partitioning point the same way. Find out what PT10 offers here: PT9 had PluginDataMergeKeys.xml for exactly this problem (it is in the pluginData file type), and whether anything equivalent applies to shared/platform.bible/extensions needs to be established, not assumed.

3. The sync write gate. Core exposes one: paratextBibleSendReceive.onSyncWriteLockChanged and getAutoSyncBlocking drive auto-sync-blocking-service.ts, which blocks writes to a syncing project. On the C# side SetExtensionData runs inside EnterSyncWriteScope() and an entire-project write lock (paranext-core: ParatextProjectDataProvider.cs:345-373). Our autosave (#119) writes on every edit and knows nothing about any of this. Note the gate only ever arms in Paratext 10 Studio builds — in plain Platform.Bible there is no S/R and one not-blocking baseline snapshot per backend start — so this is a Studio-only concern, which is also why it will not show up in our own testing.

4. Reacting to a receive. onSyncStateChanged / onSyncProgress carry FileChangesInfo: which ProjectFileTypes changed and, for books, which book numbers (paranext-core: seam file :98-196, :478-492). A receive that rewrites the source text of the book on screen is exactly the drift scenario #139 (staleness), #136 (re-anchoring), and #156 (lost segment boundaries) describe — and today we would neither notice nor tell the user, whichever storage we use. Decide whether we subscribe, and what we do when the answer is "the book you are glossing just changed".

5. Model version across a team. assertSupportedModelVersion refuses a record stamped newer than this build. Over S/R a teammate on a newer build pushes exactly that, into a file we then refuse to read and refuse to overwrite. #232 covers telling the user; S/R turns it from an edge case into a routine one, and the recovery story ("wait for your build to update, and do not touch it") needs to be deliberate.

6. Two sync systems over one set of references. The lexicon half of #44: if the lexicon side is Harmony/CRDT-backed via FW Lite while glosses ride S/R's Mercurial merge, then entryRef / senseRef / glossSenseRef (#225, #226, #227) are references crossing between two sync systems with different merge semantics and different conflict outcomes. Establish which system owns what, and what a dangling cross-system reference looks like after a conflict.

Deliverable

A decision record covering: where analysis data lives, at what partition granularity, whether we participate in the write gate, and whether we react to receive events — plus follow-up issues for whatever it commits to. Not a code change.

Related

One per question above: #44 (source of the question), #150 (imports from a synced file into unsynced storage), #87 (per-book partitioning is also the merge granularity), #119 (autosave versus the write gate), #139 (a receive is the drift trigger), #232 (a teammate's newer build), #225 (refs crossing two sync systems).