The batch resolve route joins docs/integrating.md and the OpenAPI
description, and ADR-0035 records why a route for many books exists
when one for a single book already does.
Alongside it, the sequence a device follows on its first day is now
spelled out: name everything, ask where each book stands through
/v1/heads, then sync normally. Every client wants that order and none
of it was written down, which is part of why the first attempt at it
took several refreshes to settle.
ADR-0003 and ADR-0005 are built to their last phase. Leaving them in the
index next to records that still describe unbuilt work makes the directory
harder to read than the code it explains.
They stay where they are rather than moving to an archive directory: every
other record links to them by relative path, and a tidier tree is not worth
breaking those links.
The book-to-work mapping is created lazily, on first resolve, so a reader
who uploads a library and then opens their statistics sees nothing until
they have opened every book one by one. ADR-0003 always allowed a
maintenance command to pre-resolve them, on the condition that it use the
same resolver a client does.
Move the identifier derivation into internal/workident so that the resolve
route and the backfill cannot drift: the same book resolved by an operator
in advance and by a client on first read has to land on one work, or the
reader's position quietly stops following them between devices.
Fuzzy title/author matches are counted, never confirmed. Confirming one
merges two reading histories on a guess, and the operator running a
backfill is not the person who can say whether the guess is right.
Positions attach to a work, but a book fetched from the catalog had no
way to get one: /v1/works/resolve wants identifiers, and a client that
browsed a catalog has never seen the bytes to compute them. So a
downloaded book could be read and not synced, which is most of the point
of keeping the two in one server.
The server supplies the evidence instead, because it is the side that
has it. Two devices then resolve one book from the same identifiers
rather than from whatever each managed to compute.
The mapping stays per user: one shared book becomes two works, so a
shared library does not turn into a shared reading history. A
title/author-only match still answers "low" and stores nothing until the
reader confirms it, and identifiers spanning two works are reported
rather than guessed between.
Closes phase 2 of ADR-0003.
The ADRs described a product with tags, series pages, full-text search,
external metadata lookup, collections, reading lists and a browser reader,
and never said which of those the first release needed. The ordering gave
the answer away: categorization and search were scheduled a phase ahead of
the API that lets a client download a book. A catalog nobody can download
from is not a product, however well organized it is.
So ADR-0001 now names the first release in one sentence — put an EPUB on
the server, read it at the right page in a reader you already own — and
keeps only what those four steps fail without. Everything else moves after
it. The web reader moves furthest: it is the largest feature and the only
one that renders hostile publisher markup, and Liseur already reads EPUBs
on Android and desktop, so it buys the least. ADR-0007 keeps the two
constraints that bind earlier work and defers the rest, including a
per-tab token lifecycle designed years before anyone writes the code.
The other half of this is that the phase sections had become changelogs,
which the README explicitly forbids. ADR-0005's read as one 30-line
paragraph narrating every commit that ever touched ingestion, ending in
the one sentence a reader wants: what is left. Those are now a state and a
remainder, and the convention says plainly that a status needing a
paragraph is a diary.
Nothing here changes a decision the code already implements. Statuses move
to Accepted where the code shipped, the index says what is actually built
rather than Proposed nine times, and the schema block lists the tables
that exist instead of calling them planned.
Kept deliberately, against the urge to compress: hash equality never
proves a rename, only a completed sweep may mark a book missing, and an
allowlisted provider host must be re-checked on every redirect hop. None
is built yet, and each is a constraint rather than a mechanism.
Reviewed for the failure mode that matters in a docs change — claiming
something the code does not do. Five inaccuracies found and fixed, the
worst being a validator that does not yet bound request size.
Implemented the shared catalog, access control, metadata, durable
ingest, and per-user work mapping schemas for SQLite and PostgreSQL.
This addition establishes store operations and atomic catalog resolution
foundations to support multi-user content libraries and synchronization.
Updated documentation to mandate identity reconciliation whenever a
watched file changes hash. Replacing a file at a watched path with a
different publication previously risked inheriting the existing book's
identity, metadata, and per-user work mappings.
Expanded the project architecture documentation and introduced
architecture decision records to plan the transition from a
synchronization-only backend to a full EPUB content server. Users
required built-in book storage, catalog access, metadata management, and
web reading without relying on third-party library tools or compromising
synchronization invariants.
