[SimonHeybrock]

Stacked on #194 (base branch 184-record-of-another-spec), which is stacked on #193 and #192. Merge those first, in order, or this PR lands in its base branch and not in main.

Implements ADR 0010: a file is identified by its catalogue identifier, or else by its path.

The problem. FolderFiles gave every file the identity path:<absolute path>. Moving a workspace's folder changed every identity, so a trigger loop reduced its runs again and a batch's rows no longer matched their records. The same raw file seen through two file sources had two identities.

The rule. FolderFiles takes root=, the workspace's folder, which folder_files passes:

pid:20.500.12269/<uuid>     a table row with a pid: a file the catalogue lists
path:masks/main.xml         any other file inside root
path:/data/other/run-1.nxs  any other file outside root, or without root (local())

A person names a file as before, by run, by pid, or by path. A relative path a person writes, in file(path=...), in a Path param, or in a batch's text form, is relative to the working directory. The folder-relative form exists only as the identity a record holds. Only the file source's path() turns an identity into a path.

LoKI's read_metadata gives the pid of a raw file that carries entry/entry_identifier_uuid. The prefix 20.500.12269 is written in one place, ess.apps.files.catalogue_identifier. The files of the detector test at Larmor carry no identifier and are identified by path.

The log format is 4, since records hold identities.

What a move does now. A test renames a folder and opens it again: the records' files match the file source, the outputs read, the trigger loop finds nothing to do, and the batch's table is unchanged.

Costs to be aware of.

• A file first listed without a pid and later with one changes identity. Running essapps-batch files again after files gained identifiers has this effect, and a trigger loop then reduces those files again. ADR 0010 and batch.md say so.
• File cells of a table the batch writes show pid:20.500.12269/<uuid> where they showed a path. The row key still shows the run, and the web and Panel views show run N. Writing the run number in those cells needs the file's metadata where the table is written, so it is left for a follow-up.
• An exported _record.json with a folder-relative identity does not name the folder.
• Two rows with one pid are refused, so a catalogue dataset that holds several files cannot be listed. Raw files have one file per dataset. Noted under Open in the ADR.

Review. A fresh reviewer probed moved folders, symlinks, and every reader of an identity. Fixed from it: a relative file(path=...) was taken against the folder while the batch's text form took it against the working directory; a folder reached through a symlink with a ../ row named a file that does not exist (real paths are used now); a pid not written in full was accepted (now refused, the prefix is not guessed); a record resumed after its file left the file source failed with KeyError: FileRef(...) as its reason (now a sentence that names the file).

🤖 Generated with Claude Code