Investigate how interlinear data interacts with Send/Receive

[imnasnainaec]

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 Wire a model project into the suggestion engine (surface-form tier) #148 and Wire the output project (back-translation / adaptation) into export, not creation #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 Interlinear project save performance #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 (Add autosaving option #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 Staleness detection for segment-level analyses #139 (staleness), Decide the token/segment identity re-anchoring strategy #136 (re-anchoring), and Warn when persisted segment boundaries are lost on load (reversification / source edits) #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. Tell the user what to do when a record's model version is newer than this build #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 Choose or Create Lexicon #44: if the lexicon side is Harmony/CRDT-backed via FW Lite while glosses ride S/R's Mercurial merge, then entryRef / senseRef / glossSenseRef (Namespace lexicon refs by provider before any ref is persisted #225, Define the lexicon port and capability descriptor #226, FW Lite adapter: resolve lexicon refs for display #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).