rvlib-shipkit 2.1.1 → 2.3.0

package/src/review/store.ts

@@ -0,0 +1,1002 @@
+// the one feedback store on disk (wiki build/shipkit/review.md): `.shipkit/review/<id>/`, gitignored: `item.json`, the
+// media, and `thread/`, one file per message, never rewritten. An item is built in a dot folder and renamed, every file
+// written beside its place and renamed, so no reader sees half of one. The format is pkm-multi's verbatim. A folder of
+// the old shape (request.json, feedback.json, a message with `seen`) fails loud
+import * as fs from 'node:fs'
+import { existsSync, readdirSync, readFileSync, statSync, watch } from 'node:fs'
+import { basename, dirname, extname, join, resolve } from 'node:path'
+import { LAYOUT } from '../core/layout.ts'
+import { ffmpeg } from '../trailer/ffmpeg.ts'
+import { probe, sizeOf, stillAt } from './media.ts'
+import {
+    AGENT_RE,
+    allowed,
+    FILE_RE,
+    ID_RE,
+    idOf,
+    isApproved,
+    isAudioFile,
+    isClipFile,
+    isMarkItem,
+    itemProblems,
+    MESSAGE_FILE_RE,
+    MESSAGE_RE,
+    messageIdOf,
+    messageProblems,
+    NO_SPEC,
+    specProblems,
+    stateOf,
+    subjectKey,
+    laneOf,
+    textOf,
+    toAcknowledge,
+    verdictMessageOf,
+    verdictOf,
+    withdrawnOf,
+    type GalleryTile,
+    type Item,
+    type Message,
+    type Op,
+    type Origin,
+    type Party,
+    type Rect,
+    type ReviewClip,
+    type ReviewFiles,
+    type ReviewItem,
+    type ReviewMark,
+    type ReviewView,
+    type Spec,
+    type Subject,
+} from './model.ts'
+import { beatRole, roleOf } from './role.ts'
+import { chainOf, coveringHead, followedIds, isFollowed } from './threads.ts'
+import { liveWatchers } from './watchers.ts'
+
+/** the store of a repo */
+export const storeDir = (root: string): string => join(root, LAYOUT.review)
+
+/** each store's spec, the model's part of its repo's review unit (unit.ts), bound by whoever loaded the unit: the cli,
+ *  the hub. A store no one bound reads with NO_SPEC */
+const specs = new Map<string, Spec>()
+
+export const bindSpec = (dir: string, spec: Spec): void => void specs.set(resolve(dir), spec)
+export const specOf = (dir: string): Spec => specs.get(resolve(dir)) ?? NO_SPEC
+
+const IMAGE_EXT = /^\.(png|jpe?g|webp)$/
+const CLIP_EXT = /^\.(webm|mp4)$/
+
+/** this process's writes to a store, counted at once: the listing tag moves before the watcher reports them */
+let wrote = 0
+const renameSync = (a: string, b: string): void => (fs.renameSync(a, b), touched(a), touched(b))
+const rmSync = (p: string, o?: fs.RmOptions): void => (fs.rmSync(p, o), touched(p))
+const copyFileSync = (a: string, b: string): void => (fs.copyFileSync(a, b), touched(b))
+const writeFileSync = (p: string, d: string): void => (fs.writeFileSync(p, d), touched(p))
+const mkdirSync = (p: string, o?: fs.MakeDirectoryOptions): void => (fs.mkdirSync(p, o), touched(p))
+
+function writeJson(file: string, v: unknown): void {
+    const tmp = `${file}.tmp`
+    writeFileSync(tmp, `${JSON.stringify(v, null, 4)}\n`)
+    renameSync(tmp, file)
+}
+
+/** one view as given: a label, and an image, a clip, a sound or a pair (a clip or a sound goes anywhere an image goes,
+ *  by its extension), or a gallery of images */
+export interface ViewInput {
+    label: string
+    image?: string
+    video?: string
+    audio?: string
+    before?: string
+    after?: string
+    /** a list of small images shown as a wrapping grid, each with its label; never the first view */
+    gallery?: { file: string; label: string }[]
+}
+
+export interface AddInput {
+    title: string
+    what: string
+    /** what is judged; a plain shot by default */
+    subject?: Subject
+    topic?: string
+    image?: string
+    video?: string
+    audio?: string
+    before?: string
+    after?: string
+    commit?: string
+    /** the lane that made it; else SK_AGENT */
+    lane?: string
+    supersedes?: string
+    /** the raised items (a report, his note) this card answers, by id */
+    answers?: string[]
+    /** what a new version of an approved look keeps of it: required then */
+    keeps?: string
+    /** another subject on purpose, next to an active card: needs `why` */
+    fresh?: boolean
+    why?: string
+    /** the first view's label, and the other views of the same subject */
+    label?: string
+    views?: ViewInput[]
+    /** the rings over the subject, per view, as the repo read them from its own shots */
+    marks?: ReviewMark[][]
+    /** the shots used the review light over a dark place */
+    light?: 'review'
+    /** a draft card on a live shot: its image a live frame, no verdict until it is ready */
+    wip?: { live: string }
+    now?: Date
+}
+
+/** a view whose files were checked: its sources by name, its one size, and on a clip its length, its rate and the file
+ *  its poster comes from */
+interface Loaded {
+    label: string
+    sources: [name: 'image' | 'video' | 'audio' | 'before' | 'after', path: string][]
+    size: { w: number; h: number }
+    clip?: { duration: number; fps: number; from: string }
+    /** a sound: its length, and the files its waveforms are drawn from (the after's or the one's, then the before's) */
+    audio?: { duration: number; from: string; before?: string }
+    tiles?: { path: string; label: string; size: { w: number; h: number } }[]
+}
+
+/** a view's files checked and sized, a pair of one size (and one length, two clips); throws with the reason, naming the view */
+async function loadView(v: ViewInput, which: string): Promise<Loaded> {
+    if (v.gallery !== undefined) {
+        if (v.image !== undefined || v.video !== undefined || v.audio !== undefined || v.before !== undefined || v.after !== undefined)
+            throw new Error(`${which}: a gallery is a list of images, no --image, --video or pair beside it`)
+        if (v.gallery.length === 0) throw new Error(`${which}: a gallery needs at least one image`)
+        const tiles = await Promise.all(
+            v.gallery.map(async (t) => {
+                const path = resolve(t.file)
+                if (!existsSync(path)) throw new Error(`${path}: no such file`)
+                if (!IMAGE_EXT.test(extname(path).toLowerCase())) throw new Error(`${which}: ${path}: a gallery holds png, jpg or webp images, never a clip`)
+                return { path, label: t.label.trim(), size: await sizeOf(path) }
+            }),
+        )
+        return { label: v.label.trim(), sources: [], size: tiles[0]?.size ?? { w: 0, h: 0 }, tiles }
+    }
+    if ([v.image, v.video, v.audio].filter((x) => x !== undefined).length > 1) throw new Error(`${which}: give one of an image, a clip or a sound`)
+    const one = v.image ?? v.video ?? v.audio
+    const pair = v.before !== undefined || v.after !== undefined
+    if ((one !== undefined) === pair || (pair && (v.before === undefined || v.after === undefined))) throw new Error(`${which}: give one image, clip or sound, or a before and an after`)
+    const sources: Loaded['sources'] =
+        one !== undefined
+            ? [[isClipFile(one) ? 'video' : isAudioFile(one) ? 'audio' : 'image', resolve(one)]]
+            : [
+                  ['before', resolve(v.before ?? '')],
+                  ['after', resolve(v.after ?? '')],
+              ]
+    for (const [, p] of sources) {
+        if (!existsSync(p)) throw new Error(`${p}: no such file`)
+        const ext = extname(p).toLowerCase()
+        if (v.video !== undefined && !CLIP_EXT.test(ext)) throw new Error(`--video ${p}: a webm or mp4`)
+        if (v.audio !== undefined && !isAudioFile(p)) throw new Error(`--audio ${p}: a wav, mp3, flac, ogg, opus or m4a`)
+        if (!IMAGE_EXT.test(ext) && !CLIP_EXT.test(ext) && !isAudioFile(p)) throw new Error(`${p}: a png, jpg or webp, a webm or mp4 clip, or a wav, mp3, flac, ogg, opus or m4a sound`)
+    }
+    const clips = sources.filter(([, p]) => isClipFile(p)).length
+    const sounds = sources.filter(([, p]) => isAudioFile(p)).length
+    if ((clips > 0 && clips < sources.length) || (sounds > 0 && sounds < sources.length)) throw new Error(`${which}: a pair is two images, two clips or two sounds, never one of each`)
+    if (sounds > 0) {
+        const lengths = sources.map(([, p]) => soundLength(p))
+        const main = sources[sources.length - 1] as Loaded['sources'][number]
+        return {
+            label: v.label.trim(),
+            sources,
+            size: WAVE_SIZE,
+            audio: { duration: Math.max(...lengths), from: main[1], ...(sources.length > 1 ? { before: sources[0]?.[1] ?? '' } : {}) },
+        }
+    }
+    if (clips === 0) {
+        const sizes = await Promise.all(sources.map(([, p]) => sizeOf(p)))
+        const size = sizes[0] ?? { w: 0, h: 0 }
+        const odd = sizes.find((s) => s.w !== size.w || s.h !== size.h)
+        if (odd) throw new Error(`${which}: before is ${size.w}x${size.h}, after is ${odd.w}x${odd.h}: a pair shares one size (shoot both at the same size)`)
+        return { label: v.label.trim(), sources, size }
+    }
+    const infos = sources.map(([, p]) => clipInfo(p))
+    const a = infos[0] as (typeof infos)[number]
+    const b = infos[infos.length - 1] as (typeof infos)[number]
+    if (a.w !== b.w || a.h !== b.h || a.fps !== b.fps || Math.abs(a.duration - b.duration) > 1 / a.fps + 1e-3)
+        throw new Error(
+            `${which}: before is ${a.w}x${a.h}, ${a.duration} s at ${a.fps} fps, after is ${b.w}x${b.h}, ${b.duration} s at ${b.fps} fps: a pair of clips shares one size and one length`,
+        )
+    const main = sources[sources.length - 1] as Loaded['sources'][number]
+    return { label: v.label.trim(), sources, size: { w: b.w, h: b.h }, clip: { duration: b.duration, fps: b.fps, from: main[1] } }
+}
+
+/** what a card records of a clip: its size, its length and its rate, to the millisecond */
+function clipInfo(file: string): { w: number; h: number; duration: number; fps: number } {
+    let p: ReturnType<typeof probe>
+    try {
+        p = probe(file)
+    } catch (e) {
+        throw new Error(`${file}: not a clip ffprobe reads (${(e as Error).message})`)
+    }
+    if (!p.video || !(p.video.fps > 0)) throw new Error(`${file}: no video stream with a size, a length and a frame rate`)
+    const ms = (n: number): number => Math.round(n * 1000) / 1000
+    return { w: p.video.width, h: p.video.height, duration: ms(p.duration), fps: ms(p.video.fps) }
+}
+
+/** a sound's length in seconds, to the millisecond */
+function soundLength(file: string): number {
+    try {
+        return Math.round(probe(file).duration * 1000) / 1000
+    } catch (e) {
+        throw new Error(`${file}: not a sound ffprobe reads (${(e as Error).message})`)
+    }
+}
+
+/** the waveform a sound view shows, one size for every sound so a pair reads side by side */
+const WAVE_SIZE = { w: 1600, h: 240 }
+
+/** view `n`'s waveforms, drawn into `folder` beside their place and renamed */
+async function writeWaves(v: Loaded, n: number, folder: string): Promise<void> {
+    if (!v.audio) return
+    const draw = async (from: string, name: string): Promise<void> => {
+        const to = join(folder, `${prefix(n)}${name}.png`)
+        await ffmpeg(['-i', from, '-filter_complex', `showwavespic=s=${WAVE_SIZE.w}x${WAVE_SIZE.h}:split_channels=0:colors=0x8fb3ff`, '-frames:v', '1', '-f', 'image2', '-c:v', 'png', `${to}.tmp`])
+        renameSync(`${to}.tmp`, to)
+    }
+    await draw(v.audio.from, 'wave')
+    if (v.audio.before) await draw(v.audio.before, 'before-wave')
+}
+
+const prefix = (n: number): string => (n > 0 ? `v${n}-` : '')
+
+/** the file name of tile `k` of gallery view `n` */
+const tileName = (n: number, k: number, path: string): string => `v${n}-g${k}${extname(path).toLowerCase()}`
+
+function viewOf(v: Loaded, n: number, marks: readonly ReviewMark[] = []): ReviewView {
+    if (v.tiles) return { label: v.label, gallery: v.tiles.map((t, k): GalleryTile => ({ file: tileName(n, k, t.path), label: t.label, size: t.size })) }
+    const audio = v.audio ? { audio: { duration: v.audio.duration, wave: `${prefix(n)}wave.png`, ...(v.audio.before ? { waveBefore: `${prefix(n)}before-wave.png` } : {}) } } : {}
+    return { label: v.label, files: filesOf(v, n), size: v.size, ...clipOf(v, n), ...audio, ...(marks.length > 0 ? { marks: [...marks] } : {}) }
+}
+
+/** the file names of view `n` in the folder: `image.png` on the first, `v2-before.png` on a later one */
+const filesOf = (v: Loaded, n: number): ReviewFiles => Object.fromEntries(v.sources.map(([name, p]) => [name, `${prefix(n)}${name}${extname(p).toLowerCase()}`])) as ReviewFiles
+
+const clipOf = (v: Loaded, n: number): { clip: ReviewClip } | Record<string, never> =>
+    v.clip ? { clip: { poster: `${prefix(n)}poster.png`, duration: v.clip.duration, fps: v.clip.fps } } : {}
+
+/** the first frame of view `n`'s clip, written into `folder` beside its place and renamed */
+async function writePoster(v: Loaded, n: number, folder: string): Promise<void> {
+    if (!v.clip) return
+    const to = join(folder, `${prefix(n)}poster.png`)
+    await stillAt(v.clip.from, 0, `${to}.tmp`)
+    renameSync(`${to}.tmp`, to)
+}
+
+/** why an active card refuses a new one, and every way out */
+function coveredText(c: { head: ReviewItem; by: 'subject' | 'near' | 'title' }): string {
+    const r = c.head.item
+    const by = c.by === 'subject' ? 'the same subject' : c.by === 'near' ? 'the same topic and a subject near it' : 'a title this close'
+    return [
+        `one subject is one card: the active card ${r.id} "${r.title}" (${r.topic ?? 'no topic'}) already covers it, ${by}.`,
+        `  a new version of it: --supersedes ${r.id}`,
+        `  another angle of it: sk review add-view ${r.id} "<label>" <image> [<after>]`,
+        `  truly another subject: --new --why "<reason>"`,
+    ].join('\n')
+}
+
+/** the Claude Code session that runs this process, null outside one */
+export const sessionId = (): string | null => process.env.CLAUDE_CODE_SESSION_ID?.trim() || null
+
+/** the agent that acts: its lane name (SK_AGENT), else `agent` */
+export const agentName = (): string => process.env.SK_AGENT?.trim() || 'agent'
+
+/** copies the media in and writes item.json; throws with the reason on a bad input */
+export async function addItem(dir: string, input: AddInput): Promise<Item> {
+    const spec = specOf(dir)
+    if (!input.title.trim()) throw new Error('--title: required')
+    if (!input.what.trim()) throw new Error('--what: required, what changed and why')
+    const first = input.image !== undefined || input.video !== undefined || input.audio !== undefined || input.before !== undefined || input.after !== undefined
+    const given: ViewInput[] = [...(first ? [{ label: input.label ?? '', image: input.image, video: input.video, audio: input.audio, before: input.before, after: input.after }] : []), ...(input.views ?? [])].map(
+        (v) => Object.fromEntries(Object.entries(v).filter(([, x]) => x !== undefined)) as unknown as ViewInput,
+    )
+    if (given.length === 0) throw new Error('give --image, --video or --audio, or --before and --after, or --view "<label>" <image>')
+    for (const [i, v] of given.entries()) if (i > 0 && !v.label.trim()) throw new Error('--view: every view after the first needs its label')
+    if (given[0]?.gallery) throw new Error('a gallery is never the first view: give the card an --image (or a pair, or a clip) first')
+    const loaded = await Promise.all(given.map((v, i) => loadView(v, i === 0 ? 'the first view' : `--view "${v.label}"`)))
+    if (input.supersedes !== undefined && !existsSync(join(dir, input.supersedes, 'item.json'))) throw new Error(`--supersedes ${input.supersedes}: no such card in ${dir}`)
+    if (input.supersedes !== undefined && readItem(dir, input.supersedes)?.item.origin.by !== 'agent')
+        throw new Error(`--supersedes ${input.supersedes}: a report or a note is answered, never superseded: --answers ${input.supersedes}`)
+    const answers = [...new Set(input.answers ?? [])]
+    for (const a of answers) {
+        const y = ID_RE.test(a) ? readItem(dir, a) : null
+        if (!y) throw new Error(`--answers ${a}: no such item in ${dir}`)
+        if (y.item.origin.by === 'agent') throw new Error(`--answers ${a}: an agent's card; a new version of it passes --supersedes ${a}`)
+    }
+    const subject: Subject = input.subject ?? { kind: 'shot' }
+    const topic = input.topic?.trim() || undefined
+    const wrong = specProblems({ subject, ...(topic ? { topic } : {}) } as Item, spec)
+    if (wrong.length > 0) throw new Error(wrong.join('; '))
+    if (input.wip && (given.length > 2 || given.slice(1).some((v) => !v.gallery))) throw new Error('--wip: the card shows the live frame, and its history as a gallery, nothing else')
+    if (input.marks && input.marks.length > given.length) throw new Error(`marks: ${input.marks.length} lists for ${given.length} views`)
+    if (input.supersedes !== undefined && !input.keeps?.trim()) {
+        const all = readAll(dir).items
+        const old = all.find((x) => x.item.id === input.supersedes)
+        const answered = old ? chainOf(old, all).find((x) => verdictOf(x)) : undefined
+        const v = answered ? verdictOf(answered) : null
+        if (answered && v && isApproved(v.status))
+            throw new Error(
+                `${answered.item.id} "${answered.item.title}" was approved: an approval locks the look. Keep what he approved, say what stays with --keeps "<what of the approved version stays>", and say the change in --what`,
+            )
+    }
+    if (input.supersedes === undefined) {
+        if (input.fresh === true) {
+            if (!input.why?.trim()) throw new Error('--new needs --why "<reason>": why this is another subject than the active card next to it')
+        } else {
+            const others = readAll(dir).items.filter((x) => !answers.includes(x.item.id))
+            const c = coveringHead({ title: input.title, ...(topic ? { topic } : {}), subject }, others, spec)
+            if (c) throw new Error(coveredText(c))
+        }
+    }
+    const lane = input.lane?.trim() || process.env.SK_AGENT?.trim() || undefined
+    if (lane !== undefined && !AGENT_RE.test(lane)) throw new Error(`--lane: « ${lane} » is no lane id (${AGENT_RE.source})`)
+    mkdirSync(dir, { recursive: true })
+    const now = input.now ?? new Date()
+    const base = idOf(now, input.title)
+    let id = base
+    for (let n = 2; existsSync(join(dir, id)); n++) id = `${base}-${n}`
+    const session = sessionId()
+    const item: Item = {
+        id,
+        created: now.toISOString(),
+        subject,
+        origin: { by: 'agent', ...(lane ? { lane } : {}), ...(session ? { session } : {}) },
+        title: input.title.trim(),
+        what: input.what.trim(),
+        ...(topic ? { topic } : {}),
+        ...(input.commit ? { commit: input.commit } : {}),
+        views: loaded.map((v, n) => viewOf(v, n, input.marks?.[n])),
+        ...(input.supersedes ? { supersedes: input.supersedes } : {}),
+        ...(answers.length > 0 ? { answers } : {}),
+        ...(input.fresh && input.why ? { why: input.why.trim() } : {}),
+        ...(input.supersedes && input.keeps?.trim() ? { keeps: input.keeps.trim() } : {}),
+        ...(input.light ? { light: input.light } : {}),
+        ...(input.wip ? { wip: { live: input.wip.live, frame: 1 } } : {}),
+    }
+    const problems = itemProblems(item)
+    if (problems.length > 0) throw new Error(problems.join('; '))
+    const tmp = join(dir, `.${id}.tmp`)
+    rmSync(tmp, { recursive: true, force: true })
+    mkdirSync(tmp)
+    loaded.forEach((v, n) => copyFiles(v, n, tmp))
+    await Promise.all(loaded.map((v, n) => Promise.all([writePoster(v, n, tmp), writeWaves(v, n, tmp)])))
+    writeJson(join(tmp, 'item.json'), item)
+    renameSync(tmp, join(dir, id))
+    return item
+}
+
+/** every file of view `n` into the folder, each as `<name>.tmp` renamed, so no reader sees half of one */
+function copyFiles(v: Loaded, n: number, into: string): void {
+    const files = filesOf(v, n) as Record<string, string>
+    const copies: [string, string][] = [...v.sources.map(([name, p]): [string, string] => [p, files[name] ?? name]), ...(v.tiles ?? []).map((t, k): [string, string] => [t.path, tileName(n, k, t.path)])]
+    for (const [from, name] of copies) {
+        const to = join(into, name)
+        copyFileSync(from, `${to}.tmp`)
+        renameSync(`${to}.tmp`, to)
+    }
+}
+
+/** another angle of an open card's subject, appended as its next view; refused once he answered */
+export async function addView(dir: string, id: string, v: ViewInput, o: { marks?: ReviewMark[]; light?: 'review' } = {}): Promise<Item> {
+    const x = readItem(dir, id)
+    if (!x) throw new Error(`no card ${id}`)
+    if (verdictOf(x)) throw new Error(`${id} has his answer already: a new version passes --supersedes ${id}`)
+    if (!v.label.trim()) throw new Error('add-view: the view needs its label')
+    const loaded = await loadView(v, `the view "${v.label}"`)
+    const n = x.item.views.length
+    const folder = join(dir, id)
+    // the files land before the head names them, so no reader sees a view without its images
+    copyFiles(loaded, n, folder)
+    await writePoster(loaded, n, folder)
+    await writeWaves(loaded, n, folder)
+    const item: Item = { ...x.item, views: [...x.item.views, viewOf(loaded, n, o.marks)], ...(x.item.light || o.light ? { light: 'review' as const } : {}) }
+    writeJson(join(folder, 'item.json'), item)
+    return item
+}
+
+export interface ReadAll {
+    items: ReviewItem[]
+    /** a folder whose item.json or a message does not read, or still of the old shape: loud, never skipped in silence */
+    broken: { id: string; error: string }[]
+}
+
+const OLD_FILE = /^(request|feedback(\..+)?)\.json$/
+
+/** one item as its repo's unit reads it: a subject or a topic the unit refuses throws, like a broken file */
+export function readItem(dir: string, id: string): ReviewItem | null {
+    const x = readRaw(dir, id)
+    const wrong = x ? specProblems(x.item, specOf(dir)) : []
+    if (wrong.length > 0) throw new Error(`item.json: ${wrong.join('; ')}`)
+    return x
+}
+
+/** one item as the file says, whatever the unit: what the index keeps */
+function readRaw(dir: string, id: string): ReviewItem | null {
+    if (!ID_RE.test(id)) return null
+    const folder = join(dir, id)
+    if (!existsSync(folder)) return null
+    const old = readdirSync(folder).filter((n) => OLD_FILE.test(n))
+    if (old.length > 0) throw new Error(`the old shape (${old.join(', ')}): written by a process older than the one store`)
+    const f = join(folder, 'item.json')
+    if (!existsSync(f)) return null
+    const item = JSON.parse(readFileSync(f, 'utf8')) as unknown
+    const problems = itemProblems(item)
+    if (problems.length > 0) throw new Error(`item.json: ${problems.join('; ')}`)
+    return { item: item as Item, thread: readThread(dir, id) }
+}
+
+/** the messages of an item, oldest first; a message file that does not read throws, never skipped in silence */
+function readThread(dir: string, id: string): Message[] {
+    const t = join(dir, id, 'thread')
+    if (!existsSync(t)) return []
+    const names = readdirSync(t).filter((n) => n.endsWith('.json'))
+    const odd = names.find((n) => !MESSAGE_RE.test(n.slice(0, -5)))
+    if (odd) throw new Error(`thread/${odd}: not a message name`)
+    // by id, never by file name: `.json` sorts after `-`, so `…-owner-2.json` would come before `…-owner.json`
+    return names
+        .sort((a, b) => (a.slice(0, -5) < b.slice(0, -5) ? -1 : 1))
+        .map((n) => {
+            const m = JSON.parse(readFileSync(join(t, n), 'utf8')) as unknown
+            const problems = messageProblems(m, n.slice(0, -5))
+            if (problems.length > 0) throw new Error(`thread/${n}: ${problems.join('; ')}`)
+            return m as Message
+        })
+}
+
+/** appends one message to an item's thread, its image copied in beside it; the id never collides */
+export function appendMessage(dir: string, id: string, m: Omit<Message, 'id' | 'at'>, o: { image?: string; now?: Date } = {}): Message {
+    const now = o.now ?? new Date()
+    if (o.image !== undefined) {
+        if (!existsSync(o.image)) throw new Error(`${o.image}: no such file`)
+        if (!IMAGE_EXT.test(extname(o.image).toLowerCase())) throw new Error(`${o.image}: a png, jpg or webp`)
+    }
+    const folder = join(dir, id, 'thread')
+    mkdirSync(folder, { recursive: true })
+    const base = messageIdOf(now, m.who)
+    let mid = base
+    for (let n = 2; existsSync(join(folder, `${mid}.json`)); n++) mid = `${base}-${n}`
+    const file = o.image === undefined ? undefined : `${mid}${extname(o.image).toLowerCase()}`
+    if (o.image !== undefined && file) copyFileSync(o.image, join(folder, file))
+    const out: Message = { id: mid, at: now.toISOString(), ...m, ...(file ? { image: file } : {}) }
+    writeJson(join(folder, `${mid}.json`), out)
+    return out
+}
+
+/** a reply on an item from `who` (the owner, or an agent by its name), with an optional image; throws with the reason */
+export function addMessage(dir: string, id: string, who: string, text: unknown, image?: string, now = new Date()): Message {
+    if (!readItem(dir, id)) throw new Error(`no card ${id}`)
+    const t = textOf(text)
+    if ('error' in t) throw new Error(t.error)
+    return appendMessage(dir, id, { who, text: t.text }, { ...(image !== undefined ? { image } : {}), now })
+}
+
+/** `party` read what the other party wrote on an item: one `seen` message naming them; how many it read */
+export function markRead(dir: string, id: string, party: Party, who: string = party === 'owner' ? 'owner' : agentName(), now = new Date()): number {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x) return 0
+    const of = toAcknowledge(x, party)
+    if (of.length > 0) appendMessage(dir, id, { who, op: 'seen', of }, { now })
+    return of.length
+}
+
+/** the path of a message's image, null for any other name */
+export function threadImage(dir: string, id: string, name: string): string | null {
+    if (!ID_RE.test(id) || !MESSAGE_FILE_RE.test(name)) return null
+    const f = join(dir, id, 'thread', name)
+    return existsSync(f) ? f : null
+}
+
+/** an item's stamp: its folder and its thread. Every write renames a file into one of them (the head into the folder, a
+ *  message into thread/), which moves that directory's change time, so any write moves it. Two stats an item, never
+ *  three: on a 3000 item store each stat is 10 ms of every read */
+function stampOf(folder: string): string {
+    const one = (f: string): string => {
+        const s = statSync(f, { bigint: true, throwIfNoEntry: false })
+        return s ? `${s.ctimeNs}.${s.size}.${s.ino}` : '-'
+    }
+    return `${one(folder)}:${one(`${folder}/thread`)}`
+}
+
+/** the index of a store: beside it, never inside it. Its own name, never `.review-index.json`: a second code that reads
+ *  the same store keys its index on its own code, and two codes sharing one file each throw the other's away */
+export const indexFile = (dir: string): string => join(dirname(resolve(dir)), `.${basename(dir)}-index.shipkit.json`)
+
+type Read = { x: ReviewItem } | { error: string }
+
+interface StoreIndex {
+    /** the code that reads and checks an item: another code reads every item again */
+    code: string
+    items: Record<string, { stamp: string; read: Read }>
+}
+
+let codeKey: string | null = null
+const indexCode = (): string => (codeKey ??= new Bun.CryptoHasher('sha1').update(readFileSync(import.meta.path)).update(readFileSync(join(import.meta.dir, 'model.ts'))).digest('hex'))
+
+function readOne(dir: string, id: string): Read {
+    try {
+        const x = readRaw(dir, id)
+        return x ? { x } : { error: ID_RE.test(id) ? 'no item.json' : 'not a review id' }
+    } catch (e) {
+        return { error: (e as Error).message }
+    }
+}
+
+/** every item of the store as its unit reads it: an item its unit refuses (a subject kind or a topic it does not
+ *  declare, a subject's problems) is broken; the index keeps the raw reads, so a unit's change never invalidates it */
+export const readAll = (dir: string): ReadAll => checked(readRaws(dir), specOf(dir))
+
+const checks = new WeakMap<ReadAll, { spec: Spec; all: ReadAll }>()
+
+function checked(raw: ReadAll, spec: Spec): ReadAll {
+    if (spec === NO_SPEC) return raw
+    const held = checks.get(raw)
+    if (held?.spec === spec) return held.all
+    const all: ReadAll = { items: [], broken: [...raw.broken] }
+    for (const x of raw.items) {
+        const wrong = specProblems(x.item, spec)
+        if (wrong.length === 0) all.items.push(x)
+        else all.broken.push({ id: x.item.id, error: `item.json: ${wrong.join('; ')}` })
+    }
+    all.broken.sort((a, b) => (a.id < b.id ? -1 : 1))
+    checks.set(raw, { spec, all })
+    return all
+}
+
+/** every item of the store, through its index: an item whose stamp moved is read again */
+function readRaws(dir: string): ReadAll {
+    const out: ReadAll = { items: [], broken: [] }
+    if (!existsSync(dir)) return out
+    const file = indexFile(dir)
+    const code = indexCode()
+    let was: StoreIndex['items'] = {}
+    try {
+        const ix = JSON.parse(readFileSync(file, 'utf8')) as StoreIndex
+        if (ix.code === code) was = ix.items
+    } catch {
+        // no index yet, or one of another shape: read every item
+    }
+    const next: StoreIndex = { code, items: {} }
+    let moved = false
+    for (const id of readdirSync(dir).sort()) {
+        if (id.startsWith('.')) continue
+        const stamp = stampOf(join(dir, id))
+        const held = was[id]
+        const read = held && held.stamp === stamp ? held.read : readOne(dir, id)
+        if (read !== held?.read) moved = true
+        next.items[id] = { stamp, read }
+        if ('x' in read) out.items.push(read.x)
+        else out.broken.push({ id, error: read.error })
+    }
+    if (moved || Object.keys(was).length !== Object.keys(next.items).length)
+        try {
+            const tmp = `${file}.${process.pid}.tmp`
+            fs.writeFileSync(tmp, JSON.stringify(next))
+            fs.renameSync(tmp, file)
+        } catch {
+            // a read only store: the next read pays the whole read again
+        }
+    return out
+}
+
+/** the owner's verdict, checked against its item, appended as his message */
+export function writeVerdict(dir: string, id: string, body: unknown, now = new Date()): { ok: true; message: Message } | { ok: false; errors: string[] } {
+    const x = readItem(dir, id)
+    if (!x) return { ok: false, errors: [`no card ${id}`] }
+    if (x.item.wip) return { ok: false, errors: [`${id} is a draft card: the agent makes it ready before a verdict; a comment goes in a reply`] }
+    if (x.item.origin.by !== 'agent') return { ok: false, errors: [`${id} was raised, not shown by an agent: a verdict goes on the card that shows its fix; a word goes in a reply`] }
+    const r = verdictMessageOf(body, x.item)
+    if (!r.ok) return r
+    return { ok: true, message: appendMessage(dir, id, { who: 'owner', ...r.message }, { now }) }
+}
+
+/** an agent acted on the verdict and the owner's replies; false when the item has neither */
+export function markSeen(dir: string, id: string, now = new Date()): boolean {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x) return false
+    const read = markRead(dir, id, 'agent', agentName(), now)
+    return verdictOf(x) !== null || read > 0
+}
+
+/** takes an unanswered card back: false when it is unknown or already answered */
+export function withdraw(dir: string, id: string, why: string, now = new Date()): boolean {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x || verdictOf(x) || withdrawnOf(x) !== undefined) return false
+    appendMessage(dir, id, { who: agentName(), op: 'withdraw', note: why }, { now })
+    return true
+}
+
+/** an answered card waits for his answer again: its verdict stays in the thread, before the reopen; false when it has none */
+export function reopen(dir: string, id: string, now = new Date()): boolean {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x || !verdictOf(x)) return false
+    appendMessage(dir, id, { who: agentName(), op: 'reopen' }, { now })
+    return true
+}
+
+/** the path of one image, clip or poster of an item, null for any other name */
+export function imageFile(dir: string, id: string, name: string): string | null {
+    if (!ID_RE.test(id) || !FILE_RE.test(name)) return null
+    const f = join(dir, id, name)
+    return existsSync(f) ? f : null
+}
+
+export interface RaiseInput {
+    /** its id when the caller names it (a player's report: by its server and number); else from its time and title */
+    id?: string
+    subject: Subject
+    origin: Exclude<Origin, { by: 'agent' }>
+    title: string
+    /** an auto item's markdown, what its rule saw: shown as a card's `what` */
+    what?: string
+    topic?: string
+    commit?: string
+    /** his or the player's words: the first message; none on an item opened for marks or raised by a rule */
+    text?: string
+    /** the rectangles or pins drawn with them, on the image */
+    rects?: Rect[]
+    /** the image the item shows, copied in as its first view */
+    image?: string
+    now?: Date
+}
+
+/** a record the owner, a player or a rule raises: its image the first view, the words and rectangles the first message;
+ *  built in a dot folder and renamed, so two pullers of one report write it once */
+export async function raiseItem(dir: string, input: RaiseInput): Promise<ReviewItem> {
+    const text = input.text?.trim()
+    if (input.text !== undefined && !text) throw new Error('a note says something')
+    const lane = input.origin.by === 'player' ? undefined : input.origin.lane
+    if (lane !== undefined && !AGENT_RE.test(lane)) throw new Error(`origin.lane: « ${lane} » is no lane id (${AGENT_RE.source})`)
+    if (input.origin.by === 'auto' && input.text !== undefined) throw new Error('an auto item says what its rule saw in `what`, never as a message')
+    if (input.image !== undefined && (!existsSync(input.image) || !IMAGE_EXT.test(extname(input.image).toLowerCase()))) throw new Error(`${input.image}: a png, jpg or webp`)
+    const now = input.now ?? new Date()
+    mkdirSync(dir, { recursive: true })
+    if (input.id !== undefined && (!ID_RE.test(input.id) || existsSync(join(dir, input.id)))) throw new Error(`${input.id}: no item id, or taken`)
+    const base = input.id ?? idOf(now, input.title)
+    let id = base
+    for (let n = 2; existsSync(join(dir, id)); n++) id = `${base}-${n}`
+    const image = input.image === undefined ? undefined : `image${extname(input.image).toLowerCase()}`
+    const item: Item = {
+        id,
+        created: now.toISOString(),
+        subject: input.subject,
+        origin: input.origin,
+        title: input.title.trim(),
+        ...(input.what?.trim() ? { what: input.what.trim() } : {}),
+        ...(input.topic ? { topic: input.topic } : {}),
+        ...(input.commit ? { commit: input.commit } : {}),
+        views: input.image !== undefined && image ? [{ label: '', files: { image }, size: await sizeOf(input.image) }] : [],
+    }
+    const problems = [...itemProblems(item), ...specProblems(item, specOf(dir))]
+    if (problems.length > 0) throw new Error(problems.join('; '))
+    const tmp = join(dir, `.${id}.tmp`)
+    rmSync(tmp, { recursive: true, force: true })
+    mkdirSync(tmp)
+    if (input.image !== undefined && image) copyFileSync(input.image, join(tmp, image))
+    writeJson(join(tmp, 'item.json'), item)
+    renameSync(tmp, join(dir, id))
+    const who = input.origin.by === 'player' ? 'player' : 'owner'
+    if (text) appendMessage(dir, id, { who, text, ...(input.rects && input.rects.length > 0 ? { rects: input.rects } : {}) }, { now })
+    return readItem(dir, id) as ReviewItem
+}
+
+
+
+/** the owner's mark on a subject (stars, a mark and a note): one `rate` message on the subject's marks item, opened on
+ *  the first mark; the older marks stay as its history */
+export async function rateSubject(
+    dir: string,
+    o: { subject: Subject; from: string; title: string; topic?: string; rate: NonNullable<Message['rate']>; text?: string; now?: Date },
+): Promise<Message> {
+    const spec = specOf(dir)
+    const key = subjectKey(o.subject, spec)
+    if (key === null) throw new Error(`a mark names its subject: kind « ${o.subject.kind} » names none (its key)`)
+    const mine = readAllCached(dir)
+        .items.filter((x) => isMarkItem(x) && subjectKey(x.item.subject, spec) === key)
+        .sort((a, b) => b.item.created.localeCompare(a.item.created))[0]
+    const x = mine ?? (await raiseItem(dir, { subject: o.subject, origin: { by: 'owner', from: o.from }, title: o.title, ...(o.topic ? { topic: o.topic } : {}), ...(o.now ? { now: o.now } : {}) }))
+    const text = o.text?.trim()
+    return appendMessage(dir, x.item.id, { who: 'owner', rate: o.rate, ...(text ? { text } : {}) }, o.now ? { now: o.now } : {})
+}
+
+/** the owner approves a subject he raised from a tool (an entry he checked), or takes it back: a verdict with the commit, or a
+ *  reopen, on the newest item he raised on that subject from that tool */
+export async function ownerVerdict(dir: string, o: { subject: Subject; from: string; title: string; ok: boolean; commit?: string; now?: Date }): Promise<void> {
+    const spec = specOf(dir)
+    const key = subjectKey(o.subject, spec)
+    if (key === null) throw new Error(`a verdict on a subject names it: kind « ${o.subject.kind} » names none (its key)`)
+    const mine = readAllCached(dir)
+        .items.filter((x) => x.item.origin.by === 'owner' && x.item.origin.from === o.from && subjectKey(x.item.subject, spec) === key)
+        .sort((a, b) => b.item.created.localeCompare(a.item.created))[0]
+    if (!o.ok && (!mine || !verdictOf(mine))) return
+    const x = mine ?? (await raiseItem(dir, { subject: o.subject, origin: { by: 'owner', from: o.from }, title: o.title, ...(o.now ? { now: o.now } : {}) }))
+    const at = o.now ? { now: o.now } : {}
+    if (o.ok) appendMessage(dir, x.item.id, { who: 'owner', verdict: 'approved', ...(o.commit ? { fix: { commit: o.commit } } : {}) }, at)
+    else appendMessage(dir, x.item.id, { who: 'owner', op: 'reopen' }, at)
+}
+
+/** the lock of one item while an act is checked and written: a folder made atomically, waited on for at most 2 s */
+function locked<T>(dir: string, id: string, fn: () => T): T {
+    const lock = join(dir, id, '.lock')
+    const until = Date.now() + 2000
+    for (;;) {
+        try {
+            mkdirSync(lock)
+            break
+        } catch {
+            if (Date.now() > until) {
+                // a lock left by a dead process: older than the wait itself
+                if (Date.now() - statSync(lock).mtimeMs > 2000) {
+                    rmSync(lock, { recursive: true, force: true })
+                    continue
+                }
+                throw new Error(`${id}: locked by another process`)
+            }
+            Bun.sleepSync(10)
+        }
+    }
+    try {
+        return fn()
+    } finally {
+        rmSync(lock, { recursive: true, force: true })
+    }
+}
+
+/** a state change on an item by `who`, checked by `allowed` under the item's lock, so two workers claiming at once
+ *  never both win; throws with the reason it is refused. The dispatcher's ops need the repo's unit to declare one, and
+ *  its holder; a topic is one the unit declares */
+export function act(dir: string, id: string, op: Exclude<Op, 'seen'>, who: string, o: { note?: string; text?: string; commit?: string; topic?: string; now?: Date } = {}): Message {
+    const spec = specOf(dir)
+    if (who !== 'owner' && who !== 'agent' && !AGENT_RE.test(who)) throw new Error(`« ${who} » is no agent name (${AGENT_RE.source})`)
+    if (!ID_RE.test(id) || !readItem(dir, id)) throw new Error(`no item ${id}`)
+    if ((op === 'wontfix' || op === 'blocked' || op === 'drop') && !o.note?.trim()) throw new Error(`${op} says why (--note)`)
+    if ((op === 'ask' || op === 'answer') && !o.text?.trim()) throw new Error(`${op} says something`)
+    if (op === 'dispatch' && !o.topic) throw new Error('dispatch names a topic')
+    if (o.topic !== undefined && Object.keys(spec.topics).length > 0 && !spec.topics[o.topic]) throw new Error(`no topic « ${o.topic} »: ${Object.keys(spec.topics).join(', ')}`)
+    if (o.commit !== undefined && !/^[0-9a-f]{7,40}$/.test(o.commit)) throw new Error(`« ${o.commit} » is no commit`)
+    const now = o.now ?? new Date()
+    return locked(dir, id, () => {
+        const x = readItem(dir, id) as ReviewItem
+        const superseded = isFollowed(id, readAll(dir).items)
+        const role = spec.dispatcher ? (roleOf(dir)?.name ?? null) : null
+        const why = op === 'claim' && superseded && x.item.origin.by === 'agent' ? 'a newer card redoes it: claim that one' : allowed(stateOf(x, superseded), op, who, role, spec.dispatcher)
+        if (why) throw new Error(`${id}: ${why}`)
+        const m = appendMessage(
+            dir,
+            id,
+            {
+                who,
+                op,
+                ...(o.text?.trim() ? { text: o.text.trim() } : {}),
+                ...(o.note?.trim() ? { note: o.note.trim() } : {}),
+                ...(o.commit ? { fix: { commit: o.commit } } : {}),
+                ...(o.topic ? { topic: o.topic } : {}),
+            },
+            { now },
+        )
+        if (role !== null && role === who) beatRole(dir, now)
+        return m
+    })
+}
+
+/** `who` claims the oldest open item raised to a lane, or of a topic, and gets it read back; null when none is open.
+ *  Each claim runs under the item's lock, so two workers never take one item */
+export function claimNext(dir: string, by: { lane: string } | { topic: string }, who: string): ReviewItem | null {
+    const store = readAll(dir).items
+    const followed = followedIds(store)
+    const routed = specOf(dir).dispatcher
+    const open = store
+        .filter((x) => x.item.origin.by !== 'agent' && ('lane' in by ? laneOf(x) === by.lane : true))
+        .filter((x) => {
+            const st = stateOf(x, followed.has(x.item.id))
+            return (st.state === 'open' || (!routed && st.state === 'new')) && ('topic' in by ? st.topic === by.topic : true)
+        })
+        .sort((a, b) => a.item.created.localeCompare(b.item.created) || a.item.id.localeCompare(b.item.id))
+    for (const x of open) {
+        try {
+            act(dir, x.item.id, 'claim', who)
+            return readItem(dir, x.item.id)
+        } catch {
+            // taken by another worker meanwhile: the next one
+        }
+    }
+    return null
+}
+
+/** the owner deletes what he raised himself (a note he takes back): its folder goes; an agent's card is never deleted
+ *  this way */
+export function deleteRaised(dir: string, id: string): void {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x) throw new Error(`no item ${id}`)
+    if (x.item.origin.by !== 'owner') throw new Error(`${id} was not raised by the owner: never deleted from the hub`)
+    rmSync(join(dir, id), { recursive: true, force: true })
+}
+
+/** a player's report removed from the store, once its source deleted it there */
+export function deleteReport(dir: string, id: string): void {
+    const x = ID_RE.test(id) ? readItem(dir, id) : null
+    if (!x) throw new Error(`no item ${id}`)
+    if (x.item.origin.by !== 'player') throw new Error(`${id} is no player's report`)
+    rmSync(join(dir, id), { recursive: true, force: true })
+}
+
+/** a player's report by its ref (`live#3`: its server and number), or an item by its id. A pulled report's item is named
+ *  after it (`…-live-3`): its name first, the whole store only when no name holds it */
+export function itemOfRef(dir: string, ref: string): ReviewItem | null {
+    const m = /^([a-z][a-z0-9-]*)#(\d+)$/.exec(ref.trim())
+    if (!m) return ID_RE.test(ref) ? readItem(dir, ref) : null
+    const holds = (x: ReviewItem | null): x is ReviewItem => x !== null && x.item.origin.by === 'player' && x.item.origin.server === m[1] && x.item.origin.serverId === Number(m[2])
+    const tail = `-${m[1]}-${m[2]}`
+    for (const n of existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(tail)).sort() : []) {
+        try {
+            const x = readItem(dir, n)
+            if (holds(x)) return x
+        } catch {
+            // a broken folder of that name: the whole store next
+        }
+    }
+    return readAll(dir).items.find(holds) ?? null
+}
+
+/** a player's report as the owner names it: `live#85`; any other item by its id */
+export const refOf = (x: ReviewItem): string => (x.item.origin.by === 'player' ? `${x.item.origin.server}#${x.item.origin.serverId}` : x.item.id)
+
+/** a draft card's live frame and its history again: the first view's image replaced, the history a gallery view; the
+ *  draft's frame count moves */
+export async function refreshDraft(dir: string, id: string, o: { image: string; history?: { file: string; label: string }[] }): Promise<Item> {
+    const x = readItem(dir, id)
+    if (!x) throw new Error(`no card ${id}`)
+    const r = x.item
+    if (!r.wip || verdictOf(x)) throw new Error(`${id} is not a draft card waiting`)
+    const f0 = r.views[0]
+    if (!f0 || !('files' in f0) || !('image' in f0.files)) throw new Error(`${id}: its first view is no image`)
+    const folder = join(dir, id)
+    const main = await loadView({ label: f0.label, image: o.image }, 'the live frame')
+    const image = f0.files.image
+    copyFileSync(main.sources[0]?.[1] ?? '', join(folder, `${image}.tmp`))
+    renameSync(join(folder, `${image}.tmp`), join(folder, image))
+    // a draft's one gallery is its history
+    const label = r.views.find((v) => 'gallery' in v)?.label ?? HISTORY
+    let views: ReviewView[] = [{ ...f0, size: main.size }, ...r.views.slice(1).filter((v) => !('gallery' in v))]
+    if (o.history && o.history.length > 0) {
+        const n = views.length
+        const loaded = await loadView({ label, gallery: o.history }, label)
+        for (const f of readdirSync(folder)) if (new RegExp(`^v${n}-g\\d+\\.`).test(f)) rmSync(join(folder, f))
+        copyFiles(loaded, n, folder)
+        views = [...views, viewOf(loaded, n)]
+    }
+    const next: Item = { ...r, views, wip: { live: r.wip.live, frame: r.wip.frame + 1 } }
+    writeJson(join(folder, 'item.json'), next)
+    return next
+}
+
+/** the label of a draft card's history view */
+export const HISTORY = 'history'
+
+/** a draft card made a card he answers: its image the last frame or `image`, the draft state gone */
+export async function readyItem(dir: string, id: string, o: { image?: string; now?: Date } = {}): Promise<Item> {
+    const x = readItem(dir, id)
+    if (!x) throw new Error(`no card ${id}`)
+    const { wip, ...rest } = x.item
+    if (!wip) throw new Error(`${id} is not a draft card: it already takes a verdict`)
+    let item: Item = rest
+    if (o.image !== undefined) {
+        const f0 = rest.views[0]
+        if (!f0 || !('files' in f0)) throw new Error(`${id} has no image to replace`)
+        const loaded = await loadView({ label: f0.label, image: o.image }, '--image')
+        const folder = join(dir, id)
+        const old = 'image' in f0.files ? f0.files.image : undefined
+        copyFiles(loaded, 0, folder)
+        const files = filesOf(loaded, 0)
+        const now = 'image' in files ? files.image : undefined
+        if (old && old !== now) rmSync(join(folder, old), { force: true })
+        item = { ...rest, views: [{ ...f0, files, size: loaded.size }, ...rest.views.slice(1)] }
+    }
+    writeJson(join(dir, id, 'item.json'), item)
+    appendMessage(dir, id, { who: agentName(), op: 'ready' }, o.now ? { now: o.now } : {})
+    return item
+}
+
+/** a store watched by this process: `moved` counts the writes under it, by any process; `dirty` names the items they
+ *  touched since the last read, `held` every item as last read (null until a first whole read); null once the watch failed */
+interface Watched {
+    moved: number
+    dirty: Set<string>
+    held: Map<string, Read> | null
+    all: ReadAll | null
+}
+const watched = new Map<string, Watched | null>()
+const BOOT = Date.now().toString(36)
+
+/** a write by this process: the item it touched is dirty at once, before the watcher reports it */
+function touched(path: string): void {
+    wrote++
+    const p = resolve(path)
+    for (const [key, w] of watched) if (w && p.startsWith(`${key}/`)) w.dirty.add(p.slice(key.length + 1).split('/')[0] ?? '')
+}
+
+function watchOf(dir: string): Watched | null {
+    const key = resolve(dir)
+    if (watched.has(key)) return watched.get(key) ?? null
+    const w: Watched = { moved: 0, dirty: new Set(), held: null, all: null }
+    try {
+        // a thumbnail or an item's lock is no change of the list
+        const watcher = watch(key, { recursive: true }, (_, name) => {
+            if (name && (name.startsWith('.thumbs') || name.endsWith('.lock'))) return
+            w.moved++
+            if (name) w.dirty.add(name.split('/')[0] ?? '')
+            else w.held = null
+        })
+        watcher.on('error', () => watched.set(key, null))
+        watcher.unref()
+        watched.set(key, w)
+        return w
+    } catch {
+        watched.set(key, null)
+        return null
+    }
+}
+
+/** changes when anything the list is built from changes: watched, a count of writes; else a scan. The list's ETag */
+export function storeStamp(dir: string): string {
+    if (!existsSync(dir)) return 'none'
+    const w = watchOf(dir)
+    return w ? `${BOOT}.${w.moved}.${wrote}` : scanStamp(dir)
+}
+
+/** the store's stamp and who listens (the live watchers' pids), so a watch that starts or dies moves it too */
+export const listingStamp = (dir: string): string => `${storeStamp(dir)}~${liveWatchers(dir).map((w) => w.pid).join(',')}`
+
+/** the stamp from a scan of every item's files: the safety net of a watcher that may miss an event */
+export function scanStamp(dir: string): string {
+    const h = new Bun.CryptoHasher('sha1')
+    if (!existsSync(dir)) return 'none'
+    const mark = (f: string): void => {
+        const s = statSync(f, { throwIfNoEntry: false })
+        h.update(`${f}:${s ? `${s.mtimeMs}:${s.size}` : '-'}\n`)
+    }
+    for (const id of readdirSync(dir).sort()) {
+        if (id.startsWith('.')) continue
+        for (const f of ['', 'item.json']) mark(join(dir, id, f))
+        const thread = join(dir, id, 'thread')
+        if (existsSync(thread)) for (const n of readdirSync(thread).sort()) mark(join(thread, n))
+    }
+    return h.digest('hex').slice(0, 16)
+}
+
+let cached: { dir: string; tag: string; all: ReadAll } | null = null
+
+/** readAll kept while nothing it reads changed: watched, only the items written since are read again */
+export const readAllCached = (dir: string): ReadAll => checked(readRawsCached(dir), specOf(dir))
+
+function readRawsCached(dir: string): ReadAll {
+    const w = existsSync(dir) ? watchOf(dir) : null
+    if (!w) {
+        const tag = listingStamp(dir)
+        if (cached?.dir !== dir || cached.tag !== tag) cached = { dir, tag, all: readRaws(dir) }
+        return cached.all
+    }
+    if (!w.held || !w.all) {
+        w.dirty.clear()
+        const all = readRaws(dir)
+        w.held = new Map<string, Read>([...all.items.map((x) => [x.item.id, { x }] as const), ...all.broken.map((b) => [b.id, { error: b.error }] as const)])
+        w.all = all
+        return all
+    }
+    if (w.dirty.size === 0) return w.all
+    for (const id of w.dirty) {
+        if (id === '' || id.startsWith('.')) continue
+        if (existsSync(join(dir, id))) w.held.set(id, readOne(dir, id))
+        else w.held.delete(id)
+    }
+    w.dirty.clear()
+    const out: ReadAll = { items: [], broken: [] }
+    for (const id of [...w.held.keys()].sort()) {
+        const read = w.held.get(id) as Read
+        if ('x' in read) out.items.push(read.x)
+        else out.broken.push({ id, error: read.error })
+    }
+    w.all = out
+    return out
+}