Offer alignment-format gaps upstream to Scripture Burrito

[imnasnainaec]

Asks against the Scripture Burrito and alignment-format specs, each a defensible general-use improvement that also removes something we would otherwise invent for ourselves. Evidence is in the #129 (b) findings.

Most of what we would ask for is already claimed by an open upstream thread, so the work here is mostly contributing evidence to existing issues, not filing new ones.

Upstream state

• bible-technology/alignment-spec — the reference and record model. v0.4, last commit 2024-09-18, two open issues (both by the author, early 2025), no open PRs. It says outright that "It has not yet been decided what reference schemes, alignment types, or alignment metadata are required to be supported by an implementation to be compliant with this specification." The author still files issues but has not shipped in ~2 years, so expect asks here to sit.
• bible-technology/scripture-burrito — the alignment flavor and the core metadata schemas. Active, and where the people are.

Two things to know before leaning on the flavor page we cite in #129:

1. It is new and self-described as provisional. docs/flavors/alignment_flavor.rst was added on 2026-05-29 in caad42c, whose message reads "Simplified version of the spec, adding all current flavors. Current working copy for discussion." The same commit removed the parascriptural word alignment flavor. Its MUST-level reference rules are ~3 months old, not settled committee text.
2. Nothing validates them. schema/alignment/alignment.schema.json constrains only name: "alignment"; the ingredient payload has no schema. The reference-unit MUSTs live in prose alone.

Also worth correcting our own framing: per #350, parascriptural word alignment is not merely a different artifact — it is the deprecated predecessor, "superseded by the alignment flavor type, which is now the standard way to represent word-level alignment between texts."

Overlap with open upstream threads

Our ask	Upstream state	Move
Record id + defined meta vocabulary	Unclaimed. alignment-spec #6 quotes a live ClearAligner record already carrying meta.id, meta.origin, meta.status, meta.note[]	File on alignment-spec — our strongest ask
Per-reference-unit meta	#353 proposes per-side meta.source / meta.target; does not reach a side holding several references	Comment on #353
Opaque-id scheme + idAuthorities reconciliation	#340 (authority-declared ontologies), #334 (what docid should be), #321 (constrain schemes per flavor)	Join #340 / #334; do not open cold
Three schema defects	#346 collects exactly this class; all three land in files it already touches, one inside the same oneOf as its item 3	Filed — comment
x- convention for custom reference schemes	#321 asks whether to constrain schemes per flavor; #266 owns x-/extensibility conformance; #353's comments show a live disagreement over what x- means	Fold into the #321 comment; low priority
State the alignment flavor's status	Tracked twice — #350, #355 — plus governance #354	Do not file
A lexical-resource reference	#20 open since 2019, unowned	Still a non-goal; #20 is the venue when we have a model

1. Record identity and a defined meta vocabulary — file this

The format has no record-identity concept and Appendix 3 is a note-to-self: "I think at a bare minimum we want a timestamp and who is responsible for the record. But there are other use cases to discuss including confident level, curation, etc."

The general-use argument does not need us at all. alignment-spec #6, opened by the format's own author, quotes a real ClearAligner record:

"meta": {
  "id": "d6820b2b-1a30-4247-a16f-18ed0c89b469",
  "origin": "manual",
  "status": "needsReview",
  "note": [ { "note": "…", "id": "…", "authorEmail": "…" } ]
}

So the main producer of alignment data has already reinvented record id, origin, curation status, and notes as unspecified custom keys — and the spec author has that example in front of him in his own issue tracker. The ask writes itself: promote the de-facto vocabulary (id, creator, timestamp, confidence, origin, status, note) to specified fields, and give confidence a stated scale. Undefined confidence is worse than absent: the spec's example is 0.9, with no statement of whether that is a probability, a tool-internal score, or comparable across tools, so consumers will compare numbers that are not comparable.

Without record ids an alignment file can only be replaced wholesale — no diffing, no incremental review, no attaching a review decision to one record, no merge. Any collaborative aligner hits this.

For us: AlignmentLink.id, origin, confidence, status, notes — the whole set, currently mappable only to custom meta keys.

2. Per-reference-unit meta — contribute to #353, don't duplicate it

#353 asks for per-side review metadata and proposes doing it inside record-level meta:

"meta": { "source": { "flag": "unverified" }, "target": { "flag": "possible-omission" } }

That is the right shape for a reviewer's assessment of a link, and it needs no structural change. It does not reach our case, and saying why is a useful contribution rather than a competing ask: a reference unit is a set of references, so a side can hold several selectors — #6's own ClearAligner example has a target of four. meta.target cannot say which of those four drifted. What we need to attach is per-reference, not per-side: a snapshot of what a single reference pointed at when the link was made, so a consumer re-reading the file can distinguish "this alignment is wrong" from "the text changed underneath it."

The format already permits a non-hoisted unit to be an object ({scheme, docid, selectors}), so an optional meta there is a consistency fix rather than a new concept.

For us: the only field of ours with no home at all — TokenSnapshot.surfaceText, and the derived 'stale' status that depends on it.

3. Opaque, system-minted ids — join #340 and #334

Every scheme the specs ship is positional — BCVWP, ws-token, nfc-char, u23003, vtt-timecode — which assumes an alignment can be recomputed from the document's surface. Tools with database-backed tokenizations (treebank node ids, Platform.Bible token refs, manuscript token ids, our own tokenRefs) have stable opaque ids that are more durable than offsets, and no scheme fits them.

Two live threads already occupy this ground, so the ask should join them:

• #334 wants docid to follow the burrito's own ingredient keying, noting the spec's four examples each depend on the scheme in use.
• #340 treats idAuthorities as "a clean mechanism for registering external identifier systems" and asks to extend it so an authority can declare its own vocabulary.

Our contribution is the second half of the same coherence problem: state how docid relates to idAuthorities — for example, that inside a burrito an alignment file's docid MAY be a prefixedId resolving against the burrito's declared authorities. One standards family currently has two unrelated ways to say "this id belongs to system X," and the alignment format uses neither.

There is also a concrete inconsistency to raise on #340: its Option A writes acai:person with a single colon, while core prefixedId mandates double (^[0-9a-zA-Z][0-9a-zA-Z\-]{1,31}::\S+$), and #346 quotes a real one in the wild — "id": "agmt::irvmal-4-wh". If both land as proposed the family gets two prefix syntaxes.

Frame the scheme half honestly: we will mint a scheme either way, so the choice on offer is whether it happens in the spec or only in our repo.

For us: exactly what #225 went looking for and did not find.

4. Schema defects — filed

Three over-permissive schema defects, added to #346 as this comment: the x- pattern's broken A-za-z character range (five sites across four files, plus the canonical xToken definition the other sites inline instead of $ref-ing), prefixedId admitting prefixes that idAuthorityLabel forbids, and alignment/alignment.schema.json validating nothing beyond the flavor name.

The one outcome we need back is which lexis wins for a prefixedId prefix, because #225 is choosing provider identifiers now. Staying inside the tighter ^[a-z][a-z0-9-]*[a-z0-9]$ is valid under either resolution, so that is what we use until it is answered.

Governance — read before filing anything

Authority over the spec is itself disputed. #354 ("Who is steering Scripture Burrito?") and #355 ("Which branch is being used for the burrito.bible website?") are open, a founding committee member has said he will escalate publicly to ETEN, and the restructuring wave that produced the alignment flavor page is what prompted them. #350 records that the flavor swap happened without a tracked decision.

Consequences for us:

• The defect reports are filed (§4) — mechanical, useful to everyone, and taking no side, which is why they went first.
• Contribute the two design asks (§1–2) as evidence on existing threads, where the argument stands on ClearAligner's behaviour rather than on our needs.
• Hold §3 until the branch question settles. It is the ask that depends most on knowing which document is the standard.
• Do not file "state the flavor's status." It is tracked twice over and would read as taking a side in #354.
• Check whether there is an existing SIL seat on the committee before filing as strangers; that would change the channel for all of the above.

Non-goals

Do not ask for a lexical-resource reference. The family has flavors for scripture text, audio, print, braille, sign language, and stories; nothing lexical, and no scheme that points at a dictionary entry or a sense. #20 has tracked this since 2019 and is unowned — a committee member noted then that nobody had done the work. Register interest there once we have a lexicon model of our own to offer; do not ask them to design one.

Sequencing

None of this gates #225 or #226 — the ref shape is self-contained and needs nothing upstream. Nothing here should end up sequenced ahead of ref work.

Size

S for §1–2 (one new alignment-spec issue, one comment on #353). M for §3, which needs a worked example to be credible and should wait. §4 is done.