The service must work with read-only access to the documents it indexes.
Writing a user.collection extended attribute needs write access, so the
previous membership design fails on a :ro mount; setfattr returns "Read-only
file system". Verified in the spike container.
Membership now reaches Recoll through metadatacmds in recoll.conf, a documented
facility for external metadata: Recoll runs a helper per file at index time and
the helper answers from our own store. Verified end to end against a read-only
bind mount. Everything previously established about opaque collection IDs,
multi-membership and single-ranked-set OR queries survives unchanged, because
only the transport differs. SQLite becomes the only store of membership rather
than the authoritative one of two, so drift is impossible and the reconcile path
is gone. Extended attributes are no longer a deployment requirement.
Document identity becomes the SHA-256 of file content. Files sharing a name but
differing in content are separate documents; one file reachable by several paths
is a single document with one canonical path, and only that path is reported as
belonging to a collection. Recoll cannot help here: md5 is empty and sig is only
size plus mtime.
Two measured constraints are recorded. A membership change is invisible to both
a plain incremental run and recollindex -i, because the change signature is size
plus mtime; recollindex -i -Z on the affected path picks it up in about 15ms.
And the helper is spawned once per file per index run, so it must start fast: a
400-file index took 0.09s with no helper, 0.13s with shell and awk, and 0.82s
with python3.
The superseded entry in docs/DECISIONS.md is left intact, per that file's
append-only rule, and the new entry links back to it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Records the outcome of the 001 brainstorm and the Recoll spike that backed it.
Decisions: Python + FastAPI managed with uv; the product split into four specs
built in order; collections managed at runtime through the API with SQLite as
the store of record; indexing as an in-process job queue; search scope as an
explicit required parameter; results carrying metadata and snippets; real
authentication in 001 with user administration deferred to 004.
The load-bearing one is collection membership. A collection cannot be a
directory, because files sharing a directory must be able to belong to
different collections, so every document is indexed once into a single Recoll
index and membership is a user.collection extended attribute mapped to a
queryable field. Verified against Recoll 1.43.0 in a throwaway container: the
tag must be an opaque single-token ID rather than the collection name, because
Recoll tokenises the field value and matches case-insensitively, so a tag of
cook-books is also matched by collection:cook and collection:books. Names as
tags would let collections silently bleed into each other. Opaque IDs also make
renaming free, since the index is never touched.
Two operational consequences are recorded in docs/TODO.md: documents must live
on a volume with extended-attribute support, checked loudly at startup, and a
plain incremental recollindex does not notice xattr-only changes, so retagging
must go through recollindex -i on the affected file.
uv 0.12.16 was installed on this host as part of the stack decision; AGENTS.md
is corrected in the same commit, since it previously listed uv as absent.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Empty repository: no commits, no stack. Establishes AGENTS.md as the single
source of truth, thin CLAUDE.md/GEMINI.md pointers, permission config, and the
docs/ progressive-disclosure tree.
Commands section is deliberately unfilled — no stack exists to verify commands
against.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Lucas Winther