Describe and check optional multi-identifier matching

[pid1]

SPEC.md gains §5.8, which describes matching one reading position by several document identifiers, as proposed in koreader/koreader-sync-server#55. That pull request is open and not merged, and the section says so and is pinned to its branch commit.

The twenty [K-ID-…] requirements are MAY, under the optional feature identifiers added in #2. There is no flag. The verifier pushes one position naming identifiers and reads the answer:

Optional features
  no   [identifiers] multi-identifier document matching
         SPEC.md §5.8
         a push naming identifiers answered 200 {"document":"…","timestamp":…}, with no `match` field

A match field means the feature is implemented and the family is checked in full. Its absence means the family is recorded as SKIP. A server that does not implement §5.8 stays conformant; a server that does is held to all of it, and a failure there does not change the exit status.

Measured

2026-09-23, with the profile flags each server's design calls for.

Server	Feature	Passed	MUST	SHOULD	Skipped	Verdict
koreader/kosync:latest	not found	49	0	2	20	conformant
pid1/tsundoku main	not found	47	0	0	22	conformant
koreader-sync-server#55 at 49dbd38, built locally	found	71	0	0	0	conformant

The first two are unchanged on every requirement that existed before this branch. The third is the proposal's own implementation, and passes all twenty.

A real client exercises [K-ID-16]: CrossPoint on an Xteink X3 sends metadata with "weak": true, and #55 at 32c1edb registers it as an alias. No client has yet sent a write that resolves only through a weak entry, so [K-ID-17] is checked by the verifier alone. On the same device, a copy run through CrossPoint's EPUB Optimizer resolves to the original's record through structure and opens at its position.

Two guards

assert() refuses an identifier that falls under a registered feature's requirement prefix without naming that feature, so one omitted feature: cannot quietly charge a server for an option it never claimed. coverage.mjs fails if a requirement defined under a heading that says proposed belongs to no optional feature at all, which is the case the first guard cannot see.

Also here

The results table gains a Skipped column, and tsundoku's SHOULD-failure count is corrected from 2 to 0. The 2 was its skipped registration assertions, written into the wrong column.

Since this was opened

The section grew two requirements and a type registry, all of them from an implementation disagreeing with the text:

• [K-ID-8b] — the document need not be the first identifier. Pinning it there forced a filename-matching client to offer its weakest digest first and be matched on it.
• [K-ID-12b] — an identifier ranked above the one that matched is not registered as an alias. Without it, two books a library tagged alike merged permanently: the second overwrote the first's position and correcting the tagging did not separate them, because the second book's own content digest had been glued to the other record on the way through. Measured, then fixed in #55.
• [K-ID-5b] — a client MUST order its identifiers strongest first. [K-ID-12b] is expressed in terms of list position, so a weakest-first list defeats it entirely. Measured against the fixed server; a server cannot check this, so §12.4 says so.
• [K-ID-14] and the type registry — type is opaque to the server but not to clients, since progress_match decides whether one device follows another's position. The registry gives content, structure, filename and metadata a recipe.
• [K-ID-16] and [K-ID-17] — a PUT entry may be marked weak, and a write resolving only through a weak entry does not adopt that record. metadata is the only identifier that survives a spine change, so it is the only one that reaches a different edition or a re-chunked conversion; it is also the only one that can match two different works. Marking it weak makes it seed a reader without claiming a record. The flag is body-only, so the ids grammar is untouched.
• A bug in coverage.mjs — it counted any id sharing a prefix as a refinement, so K-ID-16 looked covered by an assertion for K-ID-1. A refinement suffix is never a digit. Fixing it exposed two pre-existing gaps: K-PUT-202 was asserted and never defined, and K-FLD-1 had neither an assertion nor a reason.

The structure recipe is pinned to the point where two implementations written against it independently agree bit for bit, including on entity handling:

Text/a%20b.xhtml\nText/c&d.xhtml\n../Text/e.xhtml   47 bytes  e07ad0e2e24fbaa64b0c40a8b1ebb13f
urn:a&b:1\nch1.xhtml                                19 bytes  fb3ed76af6e07f28456616a77330b19f

🤖 Generated with Claude Code