rvlib-shipkit 2.2.0 → 2.4.0

package/src/review/model.ts

@@ -0,0 +1,896 @@
+// the one feedback store's model (wiki build/shipkit/review.md): every record the owner, a player or an agent raises
+// is an ITEM, a head (`item.json`: a typed subject, who raised it, the views) and an append only thread of messages
+// (verdicts, replies, ratings, state changes, read marks). The state is derived from the thread, never stored, so the
+// hub and every CLI write at once with no lost update. Pure and browser safe: the store, the routes and the hub page
+// share it. The on disk shape is pkm-multi's (scripts/review/store.ts) verbatim, so either store opens in the other.
+
+/** WHAT is judged: `shot` (a plain image or clip), `screen`, `frame` (a frame of a trailer cut), or a kind a repo names
+ *  for itself (pkm-multi's place, creature, song...), read as is */
+export interface Subject {
+    kind: string
+    [k: string]: unknown
+}
+
+/** a frame of a trailer cut: THE ANCHOR is its shot's name and the seconds into it, so it survives a new render */
+export interface FrameSubject extends Subject {
+    kind: 'frame'
+    trailer: string
+    cut: string
+    /** the render on screen when it was written, its mtime in ms */
+    version?: string
+    time: number
+    frame: number
+    shot: string
+    shotTime: number
+    section: string | null
+}
+
+export const isFrame = (s: Subject): s is FrameSubject => s.kind === 'frame'
+
+/** what a repo's `review({...})` unit says of one subject kind that the pure model reads (review/unit.ts holds the rest):
+ *  its words, and on the server its key, its near rule and its problems. The hub gets the words alone */
+export interface SpecKind {
+    label: string
+    icon?: string
+    /** what names one subject of this kind exactly, the kind left out; null names nothing */
+    key?(s: Subject): string | null
+    /** two subjects of this kind, in one topic, close enough to be one card */
+    near?(a: Subject, b: Subject): boolean
+    /** what is wrong with a subject of this kind; empty: nothing */
+    problems?(s: Subject): string[]
+}
+
+/** an area raised items are routed to, and the pages its worker reads first */
+export interface SpecTopic {
+    label: string
+    covers?: string
+    read?: readonly string[]
+}
+
+/** a repo's review parts as the model reads them; NO_SPEC for a repo with no unit */
+export interface Spec {
+    kinds: Record<string, SpecKind>
+    topics: Record<string, SpecTopic>
+    /** one session holds the dispatcher role and routes what is raised */
+    dispatcher: boolean
+}
+
+/** the kinds every repo has, whatever its unit declares */
+export const BUILTIN_KINDS: Record<string, SpecKind> = { shot: { label: 'images' }, screen: { label: 'screens' }, frame: { label: 'trailer frames' } }
+
+export const NO_SPEC: Spec = { kinds: {}, topics: {}, dispatcher: false }
+
+/** the words the list's subject filter shows; a kind no unit names shows its own name */
+export const subjectLabel = (kind: string, spec: Spec = NO_SPEC): string => (spec.kinds[kind] ?? BUILTIN_KINDS[kind])?.label ?? kind
+
+/** a topic's words, its id when no unit names it */
+export const topicLabel = (topic: string, spec: Spec = NO_SPEC): string => spec.topics[topic]?.label ?? topic
+
+/** WHO raised it: an agent's card goes back to its lane on a rejection */
+export type Origin =
+    | { by: 'agent'; lane?: string; session?: string }
+    | { by: 'owner'; from: string; kind?: string; lane?: string }
+    | { by: 'player'; player: string; server: string; serverId: number; client: string; context: Record<string, unknown> }
+    | { by: 'auto'; rule: string; key: string; lane: string }
+
+/** what names one subject exactly, null when it names nothing (a plain shot, a screen): two items of different keys
+ *  are never one subject. A kind the unit declares names it by its own `key`, or names nothing without one; a kind no
+ *  unit declares by its first of species, key, slug, id */
+export function subjectKey(s: Subject, spec: Spec = NO_SPEC): string | null {
+    if (isFrame(s)) return `frame:${s.trailer}/${s.cut}/${s.shot}`
+    const kind = spec.kinds[s.kind]
+    if (kind) {
+        const k = kind.key?.(s)
+        return k ? `${s.kind}:${k}` : null
+    }
+    for (const k of ['species', 'key', 'slug', 'id'] as const) if (typeof s[k] === 'string' && s[k] !== '') return `${s.kind}:${s[k] as string}`
+    return null
+}
+
+/** an image, a clip, a sound, or a pair: two images, two clips or two sounds */
+export type ReviewFiles = { image: string } | { video: string } | { audio: string } | { before: string; after: string }
+
+/** a clip view's first frame (a png of the folder), its length in seconds, its frames a second */
+export interface ReviewClip {
+    poster: string
+    duration: number
+    fps: number
+}
+
+/** a sound view: its length in seconds, and its waveform, a png of the folder (the after's, and the before's on a pair);
+ *  the view's `size` is the waveform's */
+export interface ReviewAudio {
+    duration: number
+    wave: string
+    waveBefore?: string
+}
+
+/** a ring a repo drew over its own shot (pkm-multi's world tiles): its center normalized 0..1, its radius as a share of
+ *  the image width; `side` only on a pair */
+export interface ReviewMark {
+    tile: [number, number]
+    edge?: 'n' | 'e' | 's' | 'w'
+    x: number
+    y: number
+    r: number
+    side?: Side
+}
+
+/** one view of a card's subject: an image or a pair, its size, its marks; the first view's label may be empty */
+export interface MediaView {
+    label: string
+    files: ReviewFiles
+    size: { w: number; h: number }
+    clip?: ReviewClip
+    audio?: ReviewAudio
+    marks?: ReviewMark[]
+    /** a line on this view alone (an option's description on a choice card) */
+    note?: string
+}
+
+/** one image of a gallery view, a file of the folder (`v<n>-g<k>.<ext>`) */
+export interface GalleryTile {
+    file: string
+    label: string
+    size: { w: number; h: number }
+}
+
+/** a view that is a list of small images, shown as a wrapping grid; never the first view */
+export interface GalleryView {
+    label: string
+    gallery: GalleryTile[]
+}
+
+export type ReviewView = MediaView | GalleryView
+
+export const isGallery = (v: ReviewView): v is GalleryView => 'gallery' in v
+
+/** `item.json`: the head, written at creation, changed only by `add-view` */
+export interface Item {
+    id: string
+    /** ISO time */
+    created: string
+    subject: Subject
+    origin: Origin
+    title: string
+    /** an agent card's markdown: what changed and why */
+    what?: string
+    topic?: string
+    commit?: string
+    /** the first is a media view, never a gallery */
+    views: ReviewView[]
+    /** an earlier card this one is a new version of; never a raised item */
+    supersedes?: string
+    /** the raised items (a report, his note) this card answers: one thread per bug */
+    answers?: string[]
+    /** what this new version keeps of the approved look it follows */
+    keeps?: string
+    /** why this card passed --new next to an active card */
+    why?: string
+    light?: 'review'
+    /** a draft card of a repo that shoots live: no verdict until it is ready */
+    wip?: { live: string; frame: number }
+    /** a choice: every view is an option, he scores them and picks one */
+    choice?: true
+}
+
+/** a choice card: he picks one of its views */
+export const isChoice = (i: Item): boolean => i.choice === true
+
+/** a view that plays on its own: one clip or one sound, never a pair */
+export const isPlayable = (v: ReviewView | undefined): v is MediaView => v !== undefined && !isGallery(v) && !isPair(v.files) && (v.clip !== undefined || v.audio !== undefined)
+
+/** a card shown as options, one thin row a view: a choice, or two views or more that each play on their own */
+export const asOptions = (i: Item): boolean => isChoice(i) || (i.views.length >= 2 && i.views.every(isPlayable))
+
+/** the most stars a reaction gives */
+export const STARS = 5
+
+/** a view's name as the page and the CLI show it: its label, or « view n » */
+export const viewName = (v: ReviewView | undefined, i: number): string => v?.label || `view ${i + 1}`
+
+/** the first view, media when there is one; a note with no image has none */
+export const firstView = (i: Item): MediaView | undefined => i.views[0] as MediaView | undefined
+
+/** the file that stands for a view in a list: a clip's first frame, the after of a pair, the image */
+export function thumbFileOf(v: ReviewView): string {
+    if (isGallery(v)) return v.gallery[0]?.file ?? ''
+    if (v.clip) return v.clip.poster
+    if (v.audio) return v.audio.wave
+    const f = v.files
+    return 'image' in f ? f.image : 'video' in f ? f.video : 'audio' in f ? f.audio : f.after
+}
+
+/** a rectangle drawn at clip time `t` is on the frame shown at `time` */
+export const onFrame = (t: number, time: number, fps: number): boolean => Math.floor(t * fps + 1e-6) === Math.floor(time * fps + 1e-6)
+
+export type Side = 'before' | 'after'
+
+/** a rectangle on a view, normalized 0..1; w = h = 0 is a pin. `view` the index of its view, absent on the first;
+ *  `side` only on a pair; `t` only on a clip */
+export interface Rect {
+    x: number
+    y: number
+    w: number
+    h: number
+    comment: string
+    view?: number
+    side?: Side
+    /** the clip time it was drawn at, in seconds */
+    t?: number
+    world?: { x0: number; y0: number; x1: number; y1: number }
+    nodes?: string[]
+}
+
+/** `approved-with-fix` counts as approved: its comment and rectangles are a small follow up; `archived` is set aside
+ *  with no verdict, so it asks nothing of the agent */
+export const STATUSES = ['approved', 'approved-with-fix', 'rejected', 'archived'] as const
+export type ReviewStatus = (typeof STATUSES)[number]
+
+export const isApproved = (s: ReviewStatus): boolean => s === 'approved' || s === 'approved-with-fix'
+
+/** the owner's reaction to one view, or to one tile of a gallery view; one per view or tile */
+export interface ReviewReaction {
+    view: number
+    tile?: number
+    status?: ReviewStatus
+    comment: string
+    /** his score of the view, 1 to STARS */
+    stars?: number
+}
+
+/** a state change, or a read mark (`seen`, with the ids it read in `of`) */
+export const OPS = ['dispatch', 'ask', 'answer', 'reassign', 'claim', 'release', 'blocked', 'fixed', 'done', 'wontfix', 'drop', 'withdraw', 'reopen', 'ready', 'seen'] as const
+export type Op = (typeof OPS)[number]
+
+/** one act on an item, one file of `thread/`, never rewritten */
+export interface Message {
+    id: string
+    /** ISO time */
+    at: string
+    /** `owner`, `player`, or an agent: its lane name, `agent` when unnamed */
+    who: string
+    text?: string
+    /** a file of the folder's `thread/` beside it */
+    image?: string
+    rects?: Rect[]
+    reactions?: ReviewReaction[]
+    verdict?: ReviewStatus
+    /** the view he picked on a choice card, its index */
+    pick?: number
+    /** a repo's own mark on a subject (stars, a song's mark): kept as written */
+    rate?: { stars?: number; mark?: string; part?: string }
+    op?: Op
+    /** the op's reason or answer */
+    note?: string
+    /** `dispatch`: where it goes */
+    topic?: string
+    /** `seen`: the messages it read */
+    of?: string[]
+    fix?: { commit: string }
+}
+
+/** what the store reads of one folder, what the list sends */
+export interface ReviewItem {
+    item: Item
+    /** oldest first */
+    thread: Message[]
+}
+
+/** the two parties of a thread: the owner and the players on one side, the agents on the other */
+export type Party = 'agent' | 'owner'
+export const partyOf = (who: string): Party => (who === 'owner' || who === 'player' ? 'owner' : 'agent')
+
+/** a message one party says to the other: a reply, a verdict, a rating, a question and its answer; never another op */
+const isTalk = (m: Message): boolean => m.op === undefined || ((m.op === 'ask' || m.op === 'answer') && m.text !== undefined)
+
+/** a reply: talk with words that is no verdict and no rating (a message moving a pin alone is no reply) */
+export const isReply = (m: Message): boolean => isTalk(m) && m.verdict === undefined && m.rate === undefined && m.text !== undefined
+
+export const MESSAGE_RE = /^\d{8}-\d{6}-\d{3}-(agent|owner|player)(-[a-z0-9]+)*$/
+export const MESSAGE_FILE_RE = /^\d{8}-\d{6}-\d{3}-(agent|owner|player)(-[a-z0-9]+)*\.(png|jpe?g|webp)$/
+const MAX_TEXT = 4000
+
+/** an agent's name: its lane (`L135`, `REVIEW`) */
+export const AGENT_RE = /^[A-Za-z][A-Za-z0-9-]{0,23}$/
+
+const two = (n: number): string => String(n).padStart(2, '0')
+const stampOf = (at: Date): string => `${at.getFullYear()}${two(at.getMonth() + 1)}${two(at.getDate())}-${two(at.getHours())}${two(at.getMinutes())}${two(at.getSeconds())}`
+
+/** `YYYYMMDD-HHMMSS-mmm-<owner|player|agent>`, local time: the names sort in time */
+export function messageIdOf(at: Date, who: string): string {
+    const role = who === 'owner' || who === 'player' ? who : 'agent'
+    return `${stampOf(at)}-${String(at.getMilliseconds()).padStart(3, '0')}-${role}`
+}
+
+/** a message's text as sent, trimmed; an error is the reason it is refused */
+export function textOf(v: unknown): { text: string } | { error: string } {
+    if (typeof v !== 'string' || v.trim() === '') return { error: 'text: required' }
+    if (v.length > MAX_TEXT) return { error: `text: at most ${MAX_TEXT} characters` }
+    return { text: v.trim() }
+}
+
+/** every message id a party marked read */
+const readBy = (x: ReviewItem, party: Party): Set<string> =>
+    new Set(x.thread.flatMap((m) => (m.op === 'seen' && partyOf(m.who) === party ? (m.of ?? []) : [])))
+
+/** the talk of the other party that `party` has not read: replies, verdicts, ratings */
+const unreadTalk = (x: ReviewItem, party: Party): Message[] => {
+    const read = readBy(x, party)
+    return x.thread.filter((m) => isTalk(m) && partyOf(m.who) !== party && !read.has(m.id))
+}
+
+/** the replies of the other party `party` has not read; a verdict is no reply (verdictOf says whether it was seen) */
+export const unreadBy = (x: ReviewItem, party: Party): Message[] => unreadTalk(x, party).filter(isReply)
+
+/** what a `seen` of `party` reads on `x`: every message of the other party it has not read yet */
+export const toAcknowledge = (x: ReviewItem, party: Party): string[] => unreadTalk(x, party).map((m) => m.id)
+
+/** the owner's verdict as the card shows it: the latest one since the last reopen; `seen`: an agent read it */
+export interface Verdict {
+    id: string
+    status: ReviewStatus
+    comment: string
+    rects: Rect[]
+    reactions?: ReviewReaction[]
+    /** the view he picked, on a choice card */
+    pick?: number
+    at: string
+    seen: boolean
+}
+
+export function verdictOf(x: ReviewItem): Verdict | null {
+    let m: Message | undefined
+    let text: string | undefined
+    let rects: Rect[] | undefined
+    for (const n of x.thread) {
+        if (n.op === 'reopen') [m, text, rects] = [undefined, undefined, undefined]
+        else if (n.verdict !== undefined) {
+            if (m?.verdict !== n.verdict) [text, rects] = [undefined, undefined]
+            m = n
+            if (n.text !== undefined) text = n.text
+            if (n.rects !== undefined) rects = n.rects
+        }
+    }
+    if (!m?.verdict) return null
+    return {
+        id: m.id,
+        status: m.verdict,
+        // a bare repeat of the same verdict keeps the words and rectangles said with it before
+        comment: text ?? '',
+        rects: rects ?? [],
+        ...(m.reactions && m.reactions.length > 0 ? { reactions: m.reactions } : {}),
+        ...(m.pick !== undefined ? { pick: m.pick } : {}),
+        at: m.at,
+        seen: readBy(x, 'agent').has(m.id),
+    }
+}
+
+/** why the agent took the card back unanswered; undefined when it did not */
+export const withdrawnOf = (x: ReviewItem): string | undefined => x.thread.filter((m) => m.op === 'withdraw').at(-1)?.note
+
+/** what the list says of an item: an agent's card by the owner's verdict, what he or a player raised by its state */
+export type ShownStatus = 'pending' | 'wip' | ReviewStatus | 'superseded' | 'withdrawn' | 'raised' | 'fixed' | 'wontfix' | 'rated'
+
+export const STATUS_LABEL: Record<ShownStatus, string> = {
+    pending: 'waiting',
+    wip: 'in progress',
+    approved: 'approved',
+    'approved-with-fix': 'ok with a fix',
+    rejected: 'rejected',
+    archived: 'archived, later',
+    superseded: 'replaced',
+    withdrawn: 'withdrawn',
+    raised: 'open',
+    fixed: 'done',
+    wontfix: 'not done',
+    rated: 'rated',
+}
+
+/** the lifecycle (wiki build/shipkit/review.md, The lifecycle) */
+export type State = 'draft' | 'new' | 'question' | 'open' | 'claimed' | 'blocked' | 'asks' | 'closed'
+type ClosedWhy = ReviewStatus | 'fixed' | 'wontfix' | 'dropped' | 'superseded' | 'withdrawn' | 'rated'
+
+export interface ItemState {
+    state: State
+    why?: ClosedWhy
+    topic?: string
+    /** who holds a claim */
+    worker?: string
+    /** the time of the `claim` that holds it; none on the claim the owner's verdict gives the card's lane until it is read */
+    since?: string
+}
+
+/** whose move it is: the owner's (asks, question, blocked), the agents' (new, open, claimed), nobody's (draft, closed) */
+export type Move = 'owner' | 'agents' | 'none'
+export const moveOf = (s: State): Move =>
+    s === 'asks' || s === 'question' || s === 'blocked' ? 'owner' : s === 'new' || s === 'open' || s === 'claimed' ? 'agents' : 'none'
+
+export const MOVE_LABEL: Record<Move, string> = { owner: 'mine', agents: 'in work', none: 'done' }
+
+/** where an item starts: an agent's card asks for the owner's verdict (a draft waits); what he raises from a tool that named
+ *  its topic (the trailer view: `film`) is open, else it waits on a dispatcher; an auto rule's item is open */
+const startOf = (i: Item): ItemState =>
+    i.origin.by === 'agent'
+        ? { state: i.wip ? 'draft' : 'asks' }
+        : i.topic || i.origin.by === 'auto'
+          ? { state: 'open', ...(i.topic ? { topic: i.topic } : {}) }
+          : { state: 'new' }
+
+/** the state of an item, folded from its thread. A verdict wins over a withdrawal, as on the card; `superseded`: a
+ *  later version follows it. « fix » and « no » give the card back to its author until an agent reads them */
+export function stateOf(x: ReviewItem, superseded: boolean): ItemState {
+    const i = x.item
+    const lane = i.origin.by === 'agent' ? i.origin.lane : undefined
+    let s: ItemState = startOf(i)
+    // what his latest verdict left: a released or superseded rework of an agent's card goes back to it
+    let given: ItemState = s
+    const read = readBy(x, 'agent')
+    for (const m of x.thread) {
+        const keep = s.topic ? { topic: s.topic } : {}
+        if (m.verdict !== undefined) {
+            const v = m.verdict
+            if (v === 'approved' || v === 'archived' || read.has(m.id)) s = { ...keep, state: 'closed', why: v }
+            else s = { ...keep, state: 'claimed', ...(lane ? { worker: lane } : {}) }
+            given = s
+            continue
+        }
+        if (m.rate !== undefined) {
+            s = { ...keep, state: 'closed', why: 'rated' }
+            continue
+        }
+        // the owner's words on a question answer it: it goes back to the dispatcher
+        if (m.op === undefined && partyOf(m.who) === 'owner' && m.text !== undefined && s.state === 'question') {
+            s = { ...keep, state: 'new' }
+            continue
+        }
+        switch (m.op) {
+            case 'dispatch':
+            case 'reassign':
+                s = { state: 'open', ...(m.topic ? { topic: m.topic } : keep) }
+                break
+            case 'ask':
+                s = { ...keep, state: 'question' }
+                break
+            case 'answer':
+                s = { ...keep, state: 'new' }
+                break
+            case 'claim':
+                s = { ...keep, state: 'claimed', worker: m.who, since: m.at }
+                break
+            case 'release':
+                s = i.origin.by === 'agent' ? given : { ...keep, state: 'open' }
+                break
+            case 'blocked':
+                s = { ...keep, state: 'blocked' }
+                break
+            case 'fixed':
+                s = { ...keep, state: 'closed', why: 'fixed' }
+                break
+            case 'done':
+                s = { ...keep, state: 'closed', why: verdictOf(x)?.status === 'approved-with-fix' ? 'approved-with-fix' : 'fixed' }
+                break
+            case 'wontfix':
+                s = { ...keep, state: 'closed', why: 'wontfix' }
+                break
+            case 'drop':
+                s = { ...keep, state: 'closed', why: 'dropped' }
+                break
+            case 'reopen':
+                s = i.origin.by === 'agent' ? { ...keep, state: 'asks' } : { ...keep, state: s.topic || i.origin.by === 'auto' ? 'open' : 'new' }
+                break
+            default:
+                break
+        }
+    }
+    // the card that redoes it landed: the rework is over
+    if (superseded && i.origin.by === 'agent' && s.since !== undefined) return given
+    if (verdictOf(x) === null) {
+        if (withdrawnOf(x) !== undefined) return { state: 'closed', why: 'withdrawn' }
+        if (superseded && s.state !== 'closed') return { ...(s.topic ? { topic: s.topic } : {}), state: 'closed', why: 'superseded' }
+    }
+    return s
+}
+
+/** the states each op leaves from */
+const FROM: Record<Exclude<Op, 'seen'>, readonly State[]> = {
+    dispatch: ['new', 'blocked'],
+    ask: ['new', 'blocked'],
+    answer: ['question'],
+    reassign: ['open', 'claimed'],
+    drop: ['new', 'question', 'open', 'blocked'],
+    claim: ['open', 'claimed', 'closed'],
+    release: ['claimed'],
+    blocked: ['claimed'],
+    fixed: ['open', 'claimed'],
+    done: ['claimed'],
+    wontfix: ['open', 'claimed'],
+    withdraw: ['draft', 'asks'],
+    reopen: ['closed', 'claimed'],
+    ready: ['draft'],
+}
+const DISPATCHER_OPS = new Set<Op>(['dispatch', 'ask', 'drop', 'reassign'])
+const WORKER_OPS = new Set<Op>(['release', 'blocked', 'fixed', 'done', 'wontfix'])
+
+/** null when `who` may do `op` on an item in state `s`, else why not. The dispatcher (null: nobody holds the role)
+ *  routes, a worker acts on its own claim, the owner answers and may act over a claim. `routed` false: the repo has no
+ *  dispatcher, so a worker takes a new item as it is */
+export function allowed(s: ItemState, op: Op, who: string, dispatcher: string | null, routed = true): string | null {
+    if (op === 'seen') return null
+    if (op === 'answer' && who !== 'owner') return 'only the owner answers a question'
+    if (DISPATCHER_OPS.has(op)) {
+        if (!routed) return 'this repo routes nothing: its review unit declares no dispatcher'
+        if (dispatcher === null) return 'nobody holds the dispatcher role: sk review dispatcher --as <name>'
+        if (who !== dispatcher) return `only the dispatcher (${dispatcher}) may ${op}`
+    }
+    if (!routed && s.state === 'new' && (op === 'claim' || op === 'fixed' || op === 'wontfix')) return op === 'claim' && who === 'owner' ? 'a worker claims, never the owner' : null
+    if (op === 'claim' && (who === 'owner' || who === dispatcher)) return `a worker claims, never ${who === 'owner' ? 'the owner' : 'the dispatcher'}`
+    if (WORKER_OPS.has(op) && who !== 'owner' && s.worker !== undefined && s.worker !== who) return `claimed by ${s.worker}, not by ${who}`
+    if (op === 'claim' && s.state === 'claimed' && s.since !== undefined && s.worker !== who) return `already claimed by ${s.worker}: release it first (--as ${s.worker})`
+    if (op === 'claim' && s.state === 'closed' && s.why !== 'rejected' && s.why !== 'approved-with-fix')
+        return `claim needs open, or a card he answered « fix » or « no », it is closed (${s.why})`
+    if (!FROM[op].includes(s.state)) {
+        if (op === 'claim' && s.state === 'claimed') return `already claimed by ${s.worker ?? 'an agent'}`
+        if (op === 'claim' && s.state === 'new') return 'not dispatched yet: only the dispatcher sends an item to a topic'
+        return `${op} needs ${FROM[op].join(' or ')}, it is ${s.state}${s.why ? ` (${s.why})` : ''}`
+    }
+    return null
+}
+
+/** a claim with no message for this long is stale: the dispatcher may take it back, a rework stops showing */
+export const STALE_CLAIM_MS = 2 * 60 * 60 * 1000
+
+/** a claim no message touched for STALE_CLAIM_MS */
+export const isStale = (x: ReviewItem, now: Date): boolean =>
+    stateOf(x, false).state === 'claimed' && now.getTime() - Date.parse(x.thread.at(-1)?.at ?? x.item.created) > STALE_CLAIM_MS
+
+/** the lane working on an item now: it claimed it, no later card redoes it, the claim is not stale; `until` is when it
+ *  goes stale with no new message. Null when nobody does */
+export function reworkOf(x: ReviewItem, superseded: boolean, now: Date): { lane: string; since: string; until: number } | null {
+    const s = stateOf(x, superseded)
+    if (s.state !== 'claimed' || s.since === undefined || s.worker === undefined) return null
+    const until = Date.parse(x.thread.at(-1)?.at ?? s.since) + STALE_CLAIM_MS
+    return now.getTime() > until ? null : { lane: s.worker, since: s.since, until }
+}
+
+/** an item the owner opened for marks only: every message a rating (an empty one is a marks item just opened) */
+export const isMarkItem = (x: ReviewItem): boolean => x.item.origin.by === 'owner' && x.item.views.length === 0 && x.thread.every((m) => m.rate !== undefined || m.op === 'seen')
+
+/** the lane an item belongs to: the lane that made a card, or the one he raised an item to */
+export const laneOf = (x: ReviewItem): string | undefined => (x.item.origin.by === 'player' ? undefined : x.item.origin.lane)
+
+/** what a watch keeps: one session's cards (`--mine`), one lane's items (`--lane`); null keeps all */
+export interface WatchFilter {
+    session: string | null
+    lane: string | null
+}
+
+/** a live `sk review watch`: its process, its filter, when it started */
+export interface Watcher extends WatchFilter {
+    pid: number
+    started: string
+}
+
+/** a watch with this filter reads his answers on `x` */
+export const coversCard = (f: WatchFilter, x: ReviewItem): boolean =>
+    (f.session === null || (x.item.origin.by === 'agent' && x.item.origin.session === f.session)) && (f.lane === null || laneOf(x) === f.lane)
+
+/** the live watchers that will read his answer on any of these cards */
+export const listenersOf = (cards: readonly ReviewItem[], watchers: readonly Watcher[]): Watcher[] => watchers.filter((w) => cards.some((x) => coversCard(w, x)))
+
+/** a card's own session has this long after its last message to claim it before a watch calls it untaken */
+export const UNTAKEN_GRACE_MS = 2 * 60 * 1000
+/** a card nobody takes is told again this often */
+export const UNTAKEN_AGAIN_MS = STALE_CLAIM_MS
+
+/** why an item waits on the agents and nobody holds it, else null; `superseded`: a later card follows it */
+export function untakenOf(x: ReviewItem, superseded: boolean, watchers: readonly Watcher[], now: Date, routed = true): string | null {
+    if (superseded) return null
+    const quiet = now.getTime() - Date.parse(x.thread.at(-1)?.at ?? x.item.created)
+    if (quiet < UNTAKEN_GRACE_MS) return null
+    const s = stateOf(x, false)
+    if (s.state === 'new') return routed ? 'raised, never dispatched' : 'raised, nobody claimed it'
+    if (s.state === 'open') return `raised${s.topic ? ` on ${s.topic}` : ''}, nobody claimed it`
+    if (s.state !== 'claimed') return null
+    if (s.since !== undefined) return quiet > STALE_CLAIM_MS ? `${s.worker ?? 'its'} claim went stale` : null
+    return listenersOf([x], watchers).length === 0 ? `the owner's verdict went back to ${s.worker ?? 'its author'}, and no watch reads it` : null
+}
+
+export const ID_RE = /^\d{8}-\d{6}-[a-z0-9-]+$/
+export const FILE_RE = /^((v\d+-)?((image|before|after|poster|wave|before-wave)\.(png|jpe?g|webp)|(video|before|after)\.(webm|mp4)|(audio|before|after)\.(wav|mp3|flac|ogg|opus|m4a))|v\d+-g\d+\.(png|jpe?g|webp))$/
+const TILE_RE = /^v\d+-g\d+\.(png|jpe?g|webp)$/
+const POSTER_RE = /^(v\d+-)?poster\.png$/
+
+/** a clip by its extension: webm or mp4 */
+export const isClipFile = (name: string): boolean => /\.(webm|mp4)$/i.test(name)
+
+/** a sound by its extension */
+export const isAudioFile = (name: string): boolean => /\.(wav|mp3|flac|ogg|opus|m4a)$/i.test(name)
+
+const WAVE_RE = /^(v\d+-)?(wave|before-wave)\.png$/
+
+export const isPair = (f: ReviewFiles): f is { before: string; after: string } => 'before' in f
+
+/** what a card is about, as the list and the CLI name it: its topic, then its subject (once when they say the same) */
+export function aboutText(i: Item, spec: Spec = NO_SPEC): string {
+    const subject = subjectLabel(i.subject.kind, spec)
+    const topic = i.topic ? topicLabel(i.topic, spec) : subject
+    return topic === subject ? subject : `${topic} · ${subject}`
+}
+
+/** the lowercase ascii words of a title */
+export const wordsOf = (title: string): string[] =>
+    title
+        .normalize('NFD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w !== '')
+
+/** the lowercase ascii words of a title, for the id, cut on a word */
+function slugOf(title: string): string {
+    let s = ''
+    for (const w of wordsOf(title)) {
+        if (s && s.length + 1 + w.length > 40) break
+        s = s ? `${s}-${w}` : w.slice(0, 40)
+    }
+    return s || 'request'
+}
+
+/** `YYYYMMDD-HHMMSS-<slug>`, local time */
+export const idOf = (at: Date, title: string): string => `${stampOf(at)}-${slugOf(title)}`
+
+const obj = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v)
+const unit = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1
+const EPS = 1e-6
+/** a clip's last frame can read a hair past its length */
+const EPS_T = 0.05
+
+function subjectProblems(s: unknown, spec: Spec): string[] {
+    if (!obj(s) || typeof s.kind !== 'string' || s.kind === '') return ['subject: { kind }']
+    const kind = spec.kinds[s.kind]
+    const declared = Object.keys(spec.kinds)
+    if (!kind && !BUILTIN_KINDS[s.kind] && declared.length > 0) return [`subject: kind « ${s.kind} » is none of ${[...declared, ...Object.keys(BUILTIN_KINDS)].join(', ')}`]
+    if (kind?.problems) return kind.problems(s as Subject).map((p) => `subject: ${p}`)
+    if (s.kind !== 'frame') return []
+    const str = (k: string): boolean => typeof s[k] === 'string' && s[k] !== ''
+    const num = (k: string): boolean => typeof s[k] === 'number' && Number.isFinite(s[k])
+    return str('trailer') && str('cut') && str('shot') && num('time') && num('frame') && num('shotTime') ? [] : ['subject: a frame has trailer, cut, time, frame, shot, shotTime']
+}
+
+/** what the unit says is wrong with an item that reads well otherwise: its subject's kind and problems, its topic */
+export function specProblems(i: Item, spec: Spec): string[] {
+    const out = subjectProblems(i.subject, spec)
+    const topics = Object.keys(spec.topics)
+    if (i.topic !== undefined && topics.length > 0 && !spec.topics[i.topic]) out.push(`topic: « ${i.topic} » is none of ${topics.join(', ')}`)
+    return out
+}
+
+function originProblems(o: unknown): string[] {
+    if (!obj(o)) return ['origin: { by }']
+    const text = (k: string): string[] => (o[k] === undefined || typeof o[k] === 'string' ? [] : [`origin.${k}: a text`])
+    if (o.by === 'agent') return [...text('lane'), ...text('session')]
+    if (o.by === 'owner') return [...(typeof o.from === 'string' ? [] : ['origin.from: where he raised it']), ...text('lane')]
+    if (o.by === 'player')
+        return typeof o.player === 'string' && typeof o.server === 'string' && Number.isInteger(o.serverId) && typeof o.client === 'string' && obj(o.context)
+            ? []
+            : ['origin: a player has player, server, serverId, client, context']
+    if (o.by === 'auto') return ['rule', 'key', 'lane'].every((k) => typeof o[k] === 'string' && o[k] !== '') ? [] : ['origin: an auto item has its rule, key and lane']
+    return ['origin.by: agent, owner, player or auto']
+}
+
+/** every reason an item.json read back is not an item; empty: it is one */
+export function itemProblems(v: unknown): string[] {
+    if (!obj(v)) return ['not an object']
+    const out: string[] = []
+    for (const k of ['id', 'created', 'title']) if (typeof v[k] !== 'string' || v[k] === '') out.push(`${k}: a text`)
+    if (typeof v.id === 'string' && !ID_RE.test(v.id)) out.push(`id: ${v.id} is not YYYYMMDD-HHMMSS-slug`)
+    out.push(...subjectProblems(v.subject, NO_SPEC), ...originProblems(v.origin))
+    if (v.topic !== undefined && typeof v.topic !== 'string') out.push('topic: a text')
+    const agent = obj(v.origin) && v.origin.by === 'agent'
+    if (!Array.isArray(v.views) || (agent && v.views.length === 0)) out.push(`views: a list${agent ? ', the first a media view' : ''}`)
+    else
+        v.views.forEach((w: unknown, i: number) => {
+            if (i > 0 && (!obj(w) || typeof w.label !== 'string' || w.label.trim() === '')) out.push(`views[${i}].label: a text`)
+            if (obj(w) && w.gallery !== undefined) out.push(...(i === 0 ? ['views[0]: never a gallery'] : galleryProblems(w, `views[${i}].`)))
+            else out.push(...viewProblems(obj(w) ? w : {}, `views[${i}].`))
+        })
+    if (v.answers !== undefined && !(Array.isArray(v.answers) && v.answers.length > 0 && v.answers.every((a) => typeof a === 'string' && ID_RE.test(a))))
+        out.push('answers: a list of item ids')
+    for (const k of ['what', 'commit', 'supersedes', 'why', 'keeps']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
+    if (v.light !== undefined && v.light !== 'review') out.push('light: review, or absent')
+    if (v.wip !== undefined && !(obj(v.wip) && typeof v.wip.live === 'string' && v.wip.live !== '' && Number.isInteger(v.wip.frame))) out.push('wip: { live, frame }, or absent')
+    if (v.choice !== undefined && !(v.choice === true && Array.isArray(v.views) && v.views.length >= 2)) out.push('choice: true on a card of two views or more, or absent')
+    return out
+}
+
+/** every reason a thread file read back is not a message; empty: it is one */
+export function messageProblems(v: unknown, name: string): string[] {
+    if (!obj(v)) return ['not an object']
+    const out: string[] = []
+    if (v.id !== name) out.push(`id: ${String(v.id)} is not its file name ${name}`)
+    if (typeof v.at !== 'string' || typeof v.who !== 'string' || v.who === '') out.push('at, who: texts')
+    if ('seen' in v) out.push('seen: a message of the old shape, before the one store')
+    if (v.op !== undefined && !OPS.includes(v.op as Op)) out.push(`op: one of ${OPS.join(', ')}`)
+    if (v.verdict !== undefined && !STATUSES.includes(v.verdict as ReviewStatus)) out.push(`verdict: one of ${STATUSES.join(', ')}`)
+    for (const k of ['text', 'image', 'note']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
+    if (v.pick !== undefined && !(Number.isInteger(v.pick) && (v.pick as number) >= 0 && v.verdict !== undefined)) out.push('pick: a view index, on a verdict')
+    if (v.op === 'seen' && !(Array.isArray(v.of) && v.of.every((x) => typeof x === 'string'))) out.push('of: the ids a seen message read')
+    if (v.op === undefined && v.verdict === undefined && v.rate === undefined && typeof v.text !== 'string' && !Array.isArray(v.rects))
+        out.push('a message says something: text, rects, verdict, rate or op')
+    return out
+}
+
+/** what is wrong with a gallery view: at least one image tile, each its file, its label and its size, and no media field */
+function galleryProblems(v: Record<string, unknown>, at: string): string[] {
+    const g = v.gallery
+    if (!Array.isArray(g) || g.length === 0) return [`${at}gallery: a list of at least one { file, label, size }`]
+    const out: string[] = []
+    g.forEach((t: unknown, k: number) => {
+        const ok = obj(t) && typeof t.file === 'string' && TILE_RE.test(t.file) && typeof t.label === 'string' && obj(t.size) && Number(t.size.w) > 0 && Number(t.size.h) > 0
+        if (!ok) out.push(`${at}gallery[${k}]: { file: v<n>-g<k>.<png|jpg|webp>, label, size: { w, h } }`)
+    })
+    for (const k of ['files', 'size', 'clip', 'marks']) if (v[k] !== undefined) out.push(`${at}${k}: none on a gallery view`)
+    return out
+}
+
+/** what is wrong with one view's files, size and marks, each reason under `at` */
+function viewProblems(v: Record<string, unknown>, at: string): string[] {
+    const out: string[] = []
+    if (typeof v.label !== 'string') out.push(`${at}label: a text`)
+    if (v.note !== undefined && typeof v.note !== 'string') out.push(`${at}note: a text`)
+    const f = v.files
+    const okImage = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && !isClipFile(n) && !isAudioFile(n)
+    const okClip = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && isClipFile(n)
+    const okAudio = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && isAudioFile(n)
+    const clipFiles = obj(f) && (okClip(f.video) || (okClip(f.before) && okClip(f.after)))
+    const audioFiles = obj(f) && (okAudio(f.audio) || (okAudio(f.before) && okAudio(f.after)))
+    if (!obj(f) || !(okImage(f.image) || (okImage(f.before) && okImage(f.after)) || clipFiles || audioFiles))
+        out.push(`${at}files: { image }, { video }, { audio } or { before, after }, a pair two images, two clips or two sounds`)
+    const a = v.audio
+    if (audioFiles) {
+        const pair = obj(f) && typeof f.before === 'string'
+        if (!obj(a) || !(Number(a.duration) > 0) || typeof a.wave !== 'string' || !WAVE_RE.test(a.wave) || (pair && (typeof a.waveBefore !== 'string' || !WAVE_RE.test(a.waveBefore))))
+            out.push(`${at}audio: { duration, wave${obj(f) && typeof f.before === 'string' ? ', waveBefore' : ''} } on a sound`)
+        if (v.marks !== undefined) out.push(`${at}marks: none on a sound`)
+    } else if (a !== undefined) out.push(`${at}audio: only on a sound`)
+    const s = v.size
+    if (!obj(s) || !(Number(s.w) > 0) || !(Number(s.h) > 0)) out.push(`${at}size: { w, h } in pixels`)
+    const c = v.clip
+    if (clipFiles) {
+        if (!obj(c) || typeof c.poster !== 'string' || !POSTER_RE.test(c.poster) || !(Number(c.duration) > 0) || !(Number(c.fps) > 0)) out.push(`${at}clip: { poster, duration, fps } on a clip`)
+        if (v.marks !== undefined) out.push(`${at}marks: none on a clip`)
+    } else if (c !== undefined) out.push(`${at}clip: only on a clip`)
+    if (v.marks !== undefined) {
+        const pair = obj(f) && typeof f.before === 'string'
+        const ok =
+            Array.isArray(v.marks) &&
+            v.marks.every(
+                (m: unknown) =>
+                    obj(m) &&
+                    Array.isArray(m.tile) &&
+                    m.tile.length === 2 &&
+                    m.tile.every(Number.isInteger) &&
+                    (m.edge === undefined || ['n', 'e', 's', 'w'].includes(m.edge as string)) &&
+                    unit(m.x) &&
+                    unit(m.y) &&
+                    unit(m.r) &&
+                    (pair ? m.side === 'before' || m.side === 'after' : m.side === undefined),
+            )
+        if (!ok) out.push(`${at}marks: each { tile: [x, y], edge?, x, y, r } normalized, with a side on a pair`)
+    }
+    return out
+}
+
+/** the verdict the page sends for an item, checked: every rectangle inside its view, a side exactly on a pair */
+export function verdictMessageOf(body: unknown, item: Item): { ok: true; message: Pick<Message, 'verdict' | 'text' | 'rects' | 'reactions' | 'pick'> } | { ok: false; errors: string[] } {
+    if (!obj(body)) return { ok: false, errors: ['not an object'] }
+    const errors: string[] = []
+    if (!STATUSES.includes(body.status as ReviewStatus)) errors.push(`status: one of ${STATUSES.join(', ')}`)
+    if (body.comment !== undefined && typeof body.comment !== 'string') errors.push('comment: a text')
+    const rects = body.rects ?? []
+    if (!Array.isArray(rects)) errors.push('rects: a list')
+    const views = item.views
+    const out: Rect[] = []
+    for (const [i, r] of (Array.isArray(rects) ? rects : []).entries()) {
+        if (!obj(r) || !unit(r.x) || !unit(r.y) || !unit(r.w) || !unit(r.h) || r.w === 0 || r.h === 0) {
+            errors.push(`rects[${i}]: x, y, w, h between 0 and 1, w and h above 0`)
+            continue
+        }
+        if (r.x + r.w > 1 + EPS || r.y + r.h > 1 + EPS) errors.push(`rects[${i}]: leaves the image`)
+        if (r.comment !== undefined && typeof r.comment !== 'string') errors.push(`rects[${i}].comment: a text`)
+        const view = r.view === undefined ? 0 : r.view
+        const on = typeof view === 'number' && Number.isInteger(view) && (r.view === undefined || view >= 1) ? views[view] : undefined
+        if (!on) {
+            errors.push(`rects[${i}].view: the index of one of the card's other views (absent on the first)`)
+            continue
+        }
+        if (isGallery(on)) {
+            errors.push(`rects[${i}].view: no rectangle on a gallery view, react to its tile instead`)
+            continue
+        }
+        if (on.audio) {
+            errors.push(`rects[${i}].view: no rectangle on a sound, react to the view instead`)
+            continue
+        }
+        const pair = isPair(on.files)
+        if (pair && r.side !== 'before' && r.side !== 'after') errors.push(`rects[${i}].side: before or after, on a pair`)
+        if (!pair && r.side !== undefined) errors.push(`rects[${i}].side: none on a single image`)
+        const clip = on.clip
+        const t = r.t
+        if (clip && (typeof t !== 'number' || !Number.isFinite(t) || t < 0 || t > clip.duration + EPS_T)) errors.push(`rects[${i}].t: the clip time it was drawn at, 0 to ${clip.duration} s`)
+        if (!clip && t !== undefined) errors.push(`rects[${i}].t: none on an image`)
+        const rect: Rect = { x: r.x, y: r.y, w: r.w, h: r.h, comment: typeof r.comment === 'string' ? r.comment : '' }
+        if (view !== 0) rect.view = view as number
+        if (pair) rect.side = r.side as Side
+        if (clip && typeof t === 'number') rect.t = t
+        out.push(rect)
+    }
+    const reactions = reactionsOf(body.reactions, views, errors, isChoice(item))
+    const pick = body.pick
+    if (pick !== undefined) {
+        if (!isChoice(item)) errors.push('pick: only on a choice card')
+        else if (!(typeof pick === 'number' && Number.isInteger(pick) && pick >= 0 && pick < views.length)) errors.push(`pick: the index of one of the card's ${views.length} views`)
+        else if (!isApproved(body.status as ReviewStatus)) errors.push('pick: goes with approved or approved-with-fix; rejecting every option is a plain rejected')
+    }
+    if (errors.length > 0) return { ok: false, errors }
+    const comment = typeof body.comment === 'string' ? body.comment : ''
+    return {
+        ok: true,
+        message: {
+            verdict: body.status as ReviewStatus,
+            ...(comment ? { text: comment } : {}),
+            ...(out.length > 0 ? { rects: out } : {}),
+            ...(reactions.length > 0 ? { reactions } : {}),
+            ...(typeof pick === 'number' ? { pick } : {}),
+        },
+    }
+}
+
+/** the reactions the page sends, checked against the card's views: each on a view, a tile only on a gallery, one per view
+ *  or tile; an empty one is dropped */
+function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[], choice: boolean): ReviewReaction[] {
+    if (v === undefined) return []
+    if (!Array.isArray(v)) {
+        errors.push('reactions: a list')
+        return []
+    }
+    const out: ReviewReaction[] = []
+    const seen = new Set<string>()
+    for (const [i, r] of v.entries()) {
+        const on = obj(r) && typeof r.view === 'number' && Number.isInteger(r.view) ? views[r.view] : undefined
+        if (!obj(r) || !on) {
+            errors.push(`reactions[${i}].view: the index of one of the card's views`)
+            continue
+        }
+        const tiles = isGallery(on) ? on.gallery.length : 0
+        const tile = r.tile
+        if (tile !== undefined && !(typeof tile === 'number' && Number.isInteger(tile) && tile >= 0 && tile < tiles)) errors.push(`reactions[${i}].tile: the index of one tile of a gallery view`)
+        if (r.status !== undefined && !STATUSES.includes(r.status as ReviewStatus)) errors.push(`reactions[${i}].status: one of ${STATUSES.join(', ')}`)
+        if (r.comment !== undefined && typeof r.comment !== 'string') errors.push(`reactions[${i}].comment: a text`)
+        const stars = r.stars
+        if (stars !== undefined && !(choice && typeof stars === 'number' && Number.isInteger(stars) && stars >= 1 && stars <= STARS))
+            errors.push(choice ? `reactions[${i}].stars: 1 to ${STARS}` : `reactions[${i}].stars: only on a choice card`)
+        const key = `${String(r.view)}/${String(tile ?? '')}`
+        if (seen.has(key)) errors.push(`reactions[${i}]: a second reaction on the same view or tile`)
+        seen.add(key)
+        const comment = typeof r.comment === 'string' ? r.comment.trim() : ''
+        if (r.status === undefined && comment === '' && stars === undefined) continue
+        out.push({
+            view: r.view as number,
+            ...(typeof tile === 'number' ? { tile } : {}),
+            ...(r.status !== undefined ? { status: r.status as ReviewStatus } : {}),
+            comment,
+            ...(typeof stars === 'number' ? { stars } : {}),
+        })
+    }
+    return out
+}
+
+/** what a reaction or a rectangle is on, as the CLI prints it: `[from above]`, `[trees / oak-v2]` */
+export function placeText(r: { view?: number | undefined; tile?: number | undefined }, views: readonly ReviewView[]): string {
+    const i = r.view ?? 0
+    const v = views[i]
+    const tile = r.tile !== undefined && v && isGallery(v) ? ` / ${v.gallery[r.tile]?.label || `image ${r.tile + 1}`}` : ''
+    return `[${viewName(v, i)}${tile}]`
+}