kaloko 0.16.0 → 0.17.0

package/src/lib/cli-args.mjs

@@ -50,13 +50,21 @@ export const HIDDEN = {
  */
 export const STRICT = new Set(['prune', 'trash', 'restore', 'keep', 'archive', 'public', 'release', 'comment', 'projects create', 'projects rename', 'projects sync'])
 
+/**
+ * Options a command takes more than once (kaloko start --ref A --ref B): their value is the list of every value given.
+ * Elsewhere the same name keeps the last value (kaloko spec --ref design).
+ */
+export const REPEATABLE = { start: ['ref'] }
+
 /**
  * argv → { _: positional, <option>: value | true }. `--key=value` splits at the first `=` only; `--key value` takes
- * the next word unless it is another option; `-h` and `-v` are --help and --version.
+ * the next word unless it is another option; `-h` and `-v` are --help and --version. An option REPEATABLE for the
+ * command (the first positional) collects its values in a list.
  */
 export function parseArgs (argv) {
   const args = { _: [] }
   const short = { '-h': 'help', '-v': 'version' }
+  const seen = {}
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a.startsWith('--')) {
@@ -66,9 +74,11 @@ export function parseArgs (argv) {
       if (eq >= 0) args[k] = a.slice(eq + 1)
       else if (next && !next.startsWith('--') && !short[next]) args[k] = argv[++i]
       else args[k] = true
+      ;(seen[k] ||= []).push(args[k])
     } else if (short[a]) args[short[a]] = true
     else args._.push(a)
   }
+  for (const k of REPEATABLE[args._[0]] || []) if (seen[k]) args[k] = seen[k]
   return args
 }
 
@@ -136,13 +146,76 @@ export function closest (word, words) {
 
 /**
  * Options `args` has that `name` does not take: a UsageError for commands in STRICT (nothing has happened yet), a
- * list of warning lines for the others (they run as before, without the unknown option).
+ * list of warning lines for the others (they run as before, without the unknown option). `update` is the line that
+ * says a newer kaloko takes the options in `newer`: those get no "Did you mean", and the line comes last (as the next
+ * step of the error, or as the last warning).
  */
-export function checkOptions (help, name, args) {
+export function checkOptions (help, name, args, { update = null, newer = [] } = {}) {
   const known = optionsFor(help, name)
-  const unknown = Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
+  const unknown = unknownOptions(help, name, args)
   if (!unknown.length) return []
-  const lines = unknown.map((k) => { const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}` })
-  if (STRICT.has(name) || STRICT.has(`${name} ${args._?.[0]}`)) throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
-  return lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`)
+  const lines = unknown.map((k) => {
+    if (update && newer.includes(k)) return `kaloko ${name} does not take --${k} in this kaloko.`
+    const guess = closest(k, [...known]); return `kaloko ${name} does not take --${k}.${guess ? ` Did you mean --${guess}?` : ''}`
+  })
+  if (STRICT.has(name) || STRICT.has(`${name} ${args._?.[0]}`)) {
+    if (update) throw Object.assign(new UsageError(`${lines.join('\n')}\nNothing was changed.`, { next: update }), { update: true })
+    throw new UsageError(`${lines.join('\n')}\nNothing was changed. kaloko help ${name} lists its options.`)
+  }
+  return [...lines.map((l) => `! ${l} It is ignored (kaloko help ${name} lists the options).`), ...(update ? [update] : [])]
+}
+
+/** The usage part of an entry's first line: what follows "  <name> " up to the description column. */
+const usageOf = (entry, name) => entry.lines[0].slice(name.length + 3).split(/\s{3,}/)[0]
+
+/** The help entries that start with `name` (not the ones that only mention it after " | "). */
+const ownEntries = (help, name) => helpEntries(help).filter((e) => e.lines[0].startsWith(`  ${name} `) || e.lines[0] === `  ${name}`)
+
+/**
+ * The sub-commands of a command with the options each one's help names: "tokens pull|push|check|validate",
+ * "export run …", and after the first one the words after " | " ("video list | trace --step <id> | tools").
+ */
+export function subcommandsFor (help, name) {
+  const subs = new Map()
+  for (const e of ownEntries(help, name)) {
+    const [first, ...rest] = usageOf(e, name).split(' | ')
+    const words = first.match(/^([a-z][a-z-]*(?:\|[a-z][a-z-]*)*)(?=\s|$)/)?.[1].split('|') || []
+    if (words.length) for (const seg of rest) { const w = seg.match(/^([a-z][a-z-]*)(?=\s|$)/)?.[1]; if (w) words.push(w) }
+    const flags = e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || []
+    for (const w of words) { if (!subs.has(w)) subs.set(w, new Set()); for (const f of flags) subs.get(w).add(f.slice(2)) }
+  }
+  return subs
+}
+
+/**
+ * Whether a command takes a word of its own after its name other than a sub-command: "validate <scenario.yml>",
+ * "spec [step]", "release [<version>]". "projects [--json]" and "doctor [--json] [--fix]" take none.
+ */
+export function takesWords (help, name) {
+  return ownEntries(help, name).some((e) => { const u = usageOf(e, name); return !/^[a-z]/.test(u) && /(^|[\s[(])<|\[(?!-)/.test(u) })
+}
+
+/**
+ * The commands of this kaloko as data (kaloko help --json, and the service's /cli/latest.json): each documented
+ * command with its documented and common options and its sub-commands with theirs. Hidden aliases stay out.
+ */
+export function catalogue (help, names, version) {
+  const commands = {}
+  for (const name of [...names].sort()) {
+    const entries = helpEntries(help).filter((e) => e.commands.has(name))
+    if (!entries.length && name !== 'help' && name !== 'version') continue
+    const named = entries.flatMap((e) => e.lines.join('\n').match(/--[a-z][a-z0-9-]*/g) || []).map((f) => f.slice(2))
+    const subs = [...subcommandsFor(help, name)].sort(([a], [b]) => a.localeCompare(b))
+    commands[name] = {
+      flags: [...new Set([...named, ...COMMON_OPTIONS])].sort(),
+      ...(subs.length ? { subcommands: Object.fromEntries(subs.map(([s, f]) => [s, { flags: [...f].sort() }])) } : {})
+    }
+  }
+  return { version, commands }
+}
+
+/** The options in `args` that `name` does not take. */
+export function unknownOptions (help, name, args) {
+  const known = optionsFor(help, name)
+  return Object.keys(args).filter((k) => k !== '_' && k !== '' && !known.has(k))
 }

package/src/lib/docs-core.mjs

@@ -419,12 +419,14 @@ function blocks (lines, o) {
 
 /** A list item: its first paragraph inline (tight lists), the rest as blocks (nested lists, pictures, code). */
 function listItem (lines, o) {
+  // lists nest at most 16 deep, like quotes; deeper items are text (1 000 levels of "- - -" would overflow the stack)
+  if ((o.listDepth || 0) >= 16) return inlineHtml(lines.join(' ').trim(), o)
   const first = []
   let i = 0
   while (i < lines.length && lines[i].trim() && !LIST.test(lines[i]) && !/^\s{0,3}(```|~~~)/.test(lines[i])) first.push(lines[i++])
   const { imgs, words } = picturesOf(first.join('\n'))
   const rest = lines.slice(i)
-  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null }) : ''}`
+  return `${words ? inlineHtml(words.replace(/\n/g, ' '), o) : ''}${imgs.length ? pics(imgs, o) : ''}${rest.some((l) => l.trim()) ? blocks(rest, { ...o, notice: null, listDepth: (o.listDepth || 0) + 1 }) : ''}`
 }
 
 function pics (imgs, o) {

package/src/lib/doctor.mjs

@@ -15,6 +15,8 @@ import { visionSettings, VISION_WEIGHT } from './vision-core.mjs'
 import { serviceUrl } from './service.mjs'
 import { videoTools, recordingChecks } from './video.mjs'
 import { productChecks } from './changelog.mjs'
+import { versionCheck } from './update-check.mjs'
+import { packageRoot } from './schema.mjs'
 
 const portFree = (port) => new Promise((done) => {
   const s = createServer().once('error', () => done(false)).once('listening', () => s.close(() => done(true)))
@@ -43,8 +45,10 @@ async function reach (url, fetchImpl, ms = 6000, headers = {}) {
  * @param {boolean} [o.fix] repair what can be repaired here: install missing Playwright browsers, create the run and
  *   scenario folders, write org: from the token into the config, ask macOS for permissions
  * @param {Function} [o.installBrowser] async (engine) => void — installs a Playwright engine (--fix)
+ * @param {Function} [o.newest] async () => { detail } — this kaloko and the newest one (default: the service's
+ *   /cli/latest.json, cached for a day; never a failure)
  */
-export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall, legacy = [] }) {
+export async function doctor ({ config, root, file = null, fetchImpl = fetch, launchChrome = defaultLaunch, env = process.env, fix = false, engines = null, launchEngine = defaultEngine, tools = null, os = process.platform, videoToolsImpl = null, scenarios = [], installBrowser = defaultInstall, legacy = [], newest = null }) {
   const checks = []
   const add = (name, ok, detail = '', hint = '', fixed = null) => checks.push({ name, ok, detail, hint, ...(fixed ? { fixed } : {}) })
   // --fix: install an engine, then look again; returns the version or throws what the install said
@@ -52,6 +56,12 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
 
   const major = Number(process.versions.node.split('.')[0])
   add('node', major >= 20, `Node ${process.versions.node}`, major >= 20 ? '' : 'Kaloko needs Node 20 or newer.')
+  // this kaloko, and the newest released one when it is newer: information, never a failure
+  try {
+    const installed = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
+    const v = newest ? await newest(installed) : await versionCheck({ installed, config, env: { ...process.env, ...env }, fetchImpl, root: packageRoot })
+    add('kaloko', true, v.detail)
+  } catch {}
 
   add('config', true, `${file || `${root}/kaloko.config.yml`} · org ${config.org || '—'} · ${Object.keys(config.environments || {}).length} environments`)
   // names from before the rename that still work (legacy.mjs): listed with their new names, never a failure

package/src/lib/evidence-core.mjs

@@ -6,12 +6,14 @@
 //   evidenceOf(record, extras)   the evidence document of one run, derived from its signed acceptance record
 //   releaseEvidenceOf(...)       the evidence document of a release: its runs and one trace matrix over all of them
 //   traceRows(evidence)          the trace matrix: requirement → criterion → step/locale/viewport → evidence → result
-//                                → human decision; TRACE_COLUMNS is the column order of the CSV
+//                                → human decision, with the step's session (role) and lane; TRACE_COLUMNS is the
+//                                column order of the CSV
 //   signatureSubject(...)        what an electronic signature is bound to; verifySignatures(record) recomputes it
 //   packageManifest / verifyPackageFiles   the MANIFEST.json of an evidence package and its check
 //
 // The JSON is the contract; CSV is a convenience for people (cells that start like a formula get a leading ').
 import { canonicalJson, sha256Hex, recordSha256, verifyRecord } from './signoff-core.mjs'
+import { stepPlaces, flowStructure } from './lanes-core.mjs'
 
 export const EVIDENCE_SCHEMA = 'qawalk.evidence.v1'
 export const MANIFEST_FILE = 'MANIFEST.json'
@@ -26,7 +28,9 @@ export const TRACE_COLUMNS = [
   'criterion_id', 'criterion_text', 'criterion_type', 'locale', 'viewport', 'evidence_file', 'evidence_sha256',
   'result', 'assessed_by', 'assessor', 'advisory',
   'step_decision', 'step_decided_by', 'step_decided_at', 'step_decided_via', 'step_signature_meaning', 'step_signer_name', 'step_signed_at', 'step_signer_time_zone', 'step_comment',
-  'run_verdict', 'run_decided_by', 'run_decided_at', 'run_decided_via', 'run_signature_meaning', 'run_signer_name', 'run_signed_at', 'run_signer_time_zone'
+  'run_verdict', 'run_decided_by', 'run_decided_at', 'run_decided_via', 'run_signature_meaning', 'run_signer_name', 'run_signed_at', 'run_signer_time_zone',
+  // added later, so they come last: a reader that takes columns by position keeps working
+  'session', 'session_title', 'lane', 'lane_label'
 ]
 export const AUDIT_COLUMNS = ['at', 'actor', 'action', 'target', 'via', 'agent', 'country', 'source', 'detail']
 
@@ -87,11 +91,15 @@ const sigCols = (s, prefix) => ({ [`${prefix}_signature_meaning`]: s?.meaning ??
 /**
  * The evidence document of a run (qawalk.evidence.v1, kind run) from its acceptance record. extras: { record_sha256,
  * signed (the record carries the service's signature), audit (rows of the run's audit trail), generated_at,
- * public_keys (URL of the well-known keys) }.
+ * public_keys (URL of the well-known keys), manifest (the run's run.json: the record names its SHA-256; it gives each
+ * step its session and lane, and the scenario its lanes and sessions) }.
  */
-export function evidenceOf (record, { record_sha256: recordSha = null, signed = !!record?.signature, audit = [], generated_at: at = new Date().toISOString(), public_keys: keysUrl = null } = {}) {
+export function evidenceOf (record, { record_sha256: recordSha = null, signed = !!record?.signature, audit = [], generated_at: at = new Date().toISOString(), public_keys: keysUrl = null, manifest = null } = {}) {
   const r = record || {}
   const run = r.run || {}
+  const places = manifest ? stepPlaces(manifest) : null
+  const flow = manifest ? flowStructure(manifest) : null
+  const placed = (s) => ({ session: places?.get(s.id)?.session ?? s.session ?? null, lane: places?.get(s.id)?.lane ?? s.lane ?? null })
   const ev = {
     schema: EVIDENCE_SCHEMA,
     kind: 'run',
@@ -102,8 +110,8 @@ export function evidenceOf (record, { record_sha256: recordSha = null, signed =
     acceptance: r.acceptance ?? (r.verdict?.verdict === 'accepted' ? 'accepted' : r.verdict?.verdict === 'returned' ? 'returned' : 'none'),
     signing: r.signing ?? ((r.signatures || []).some((x) => !x.withdrawn) ? 'in_kaloko' : 'none'),
     record: { schema: r.schema ?? null, kind: r.kind ?? (r.verdict?.verdict === 'accepted' ? 'acceptance' : 'execution'), sha256: recordSha, signed: !!signed, kid: r.signature?.kid ?? null, issued_at: r.issued_at ?? null, exported_by: r.exported_by ?? null },
-    run: { id: run.id ?? null, url: run.url ?? null, project: run.project ?? null, started_at: run.started_at ?? null, finished_at: run.finished_at ?? null, version: run.version ?? null, app_version: run.app_version ?? null },
-    scenario: { id: run.scenario?.id ?? null, title: run.scenario?.title ?? null, version: run.scenario?.version ?? null, file: run.scenario?.file ?? null, sha256: run.scenario?.sha256 ?? null, refs: cleanRefs(run.scenario?.refs) },
+    run: { id: run.id ?? null, url: run.url ?? null, project: run.project ?? null, started_at: run.started_at ?? null, finished_at: run.finished_at ?? null, version: run.version ?? null, app_version: run.app_version ?? null, refs: Array.isArray(run.refs) ? run.refs.filter((x) => typeof x === 'string') : [], purpose: run.purpose ?? null },
+    scenario: { id: run.scenario?.id ?? null, title: run.scenario?.title ?? null, version: run.scenario?.version ?? null, file: run.scenario?.file ?? null, sha256: run.scenario?.sha256 ?? null, refs: cleanRefs(run.scenario?.refs), lanes: flow?.lanes ?? null, sessions: flow?.sessions ?? null },
     environment: run.environment || null,
     git: run.git || null,
     tools: r.tools || null,
@@ -113,7 +121,7 @@ export function evidenceOf (record, { record_sha256: recordSha = null, signed =
     summary: r.summary || null,
     ai: r.ai || null,
     advisory: r.advisory ?? null,
-    steps: (r.steps || []).map((s) => ({ ...s, refs: cleanRefs(s.refs), criteria: (s.criteria || []).map((c) => ({ ...c, refs: cleanRefs(c.refs) })) })),
+    steps: (r.steps || []).map((s) => ({ ...s, ...placed(s), refs: cleanRefs(s.refs), criteria: (s.criteria || []).map((c) => ({ ...c, refs: cleanRefs(c.refs) })) })),
     signatures: r.signatures || [],
     decision_changes: r.decision_changes || [],
     audit: (audit || []).map(auditEntry)
@@ -130,7 +138,7 @@ export function auditEntry (a) {
 }
 
 /** The evidence document of a release (kind release): its runs' evidence and one trace matrix over all of them. */
-export function releaseEvidenceOf ({ release, runs, missing = [], org = null, issuer = null, generated_at: at = new Date().toISOString() }) {
+export function releaseEvidenceOf ({ release, runs, missing = [], org = null, issuer = null, generated_at: at = new Date().toISOString(), filter = null }) {
   return {
     schema: EVIDENCE_SCHEMA,
     kind: 'release',
@@ -141,6 +149,8 @@ export function releaseEvidenceOf ({ release, runs, missing = [], org = null, is
     runs,
     // runs of the release with no evidence: not accepted, deleted or out of reach, each with the reason
     missing,
+    // ?ref= / ?purpose= narrowed the release to the runs of one record or purpose (#126)
+    ...(filter && Object.keys(filter).length ? { filter } : {}),
     trace: runs.flatMap((r) => r.trace || [])
   }
 }
@@ -161,6 +171,7 @@ export function traceRows (ev) {
     const d = s.decision || (s.carried ? { state: 'approved', by: s.carried.approved_by, at: s.carried.approved_at, via: 'carried' } : null)
     const stepCols = { step_decision: d?.state ?? null, step_decided_by: d?.by ?? null, step_decided_at: d?.at ?? null, step_decided_via: d?.via ?? null, ...sigCols(stepSig, 'step'), step_comment: d?.note || null }
     const stepRefs = cleanRefs(s.refs)
+    const placeCols = { session: s.session?.key ?? null, session_title: s.session?.title ?? null, lane: s.lane?.index ?? null, lane_label: s.lane?.label ?? null }
     const caps = new Map((s.captures || []).map((c) => [`${c.locale}|${c.viewport}`, c]))
     for (const c of s.criteria || []) {
       const refs = [...cleanRefs(c.refs).map((x) => [x, 'criterion']), ...stepRefs.map((x) => [x, 'step']), ...scenarioRefs.map((x) => [x, 'scenario'])]
@@ -175,7 +186,7 @@ export function traceRows (ev) {
             step_id: s.id, step_title: s.title ?? null, criterion_id: c.id, criterion_text: c.text ?? null, criterion_type: c.type ?? null,
             locale: cell.locale ?? null, viewport: cell.viewport ?? null, evidence_file: cap?.path ?? null, evidence_sha256: cap?.sha256 ?? null,
             result: cell.verdict ?? null, assessed_by: cell.assessed_by ?? null, assessor: cell.assessor ?? null, advisory: !!cell.advisory,
-            ...stepCols, ...runCols
+            ...stepCols, ...runCols, ...placeCols
           })
         }
       }
@@ -287,7 +298,7 @@ export function packageReadme ({ run, service, recordSha }) {
     'record/kaloko-signoff.json  the acceptance record, signed by Kaloko (Ed25519)',
     'record/kaloko-signoff.pdf   the same record for people, with the JSON attached',
     'evidence.json               everything below in one machine-readable file (schema qawalk.evidence.v1)',
-    'trace.json, trace.csv       requirement → criterion → step, locale, viewport → screenshot (SHA-256) → result → decision',
+    'trace.json, trace.csv       requirement → criterion → step (role, lane), locale, viewport → screenshot (SHA-256) → result → decision',
     'audit.csv                   the audit trail of the run',
     'captures/                   the screenshots the record names',
     'decisions/                  files attached to step decisions (approve / return), as the record names them',

package/src/lib/lanes-core.mjs

@@ -0,0 +1,61 @@
+// Lanes (sub-processes) and sessions (roles) of a flow: which lane and which person a step belongs to, with the names
+// the canvas shows. Pure, no Node APIs: shared by the scenario layout (scenario.mjs), the quality evidence
+// (evidence-core.mjs, CLI and service) and the MCP run summary. The canvas (viewer/index.html) keeps a byte-identical
+// copy of laneLabels; test/lanes.test.mjs checks that the two stay the same.
+//
+// A scenario names its lanes in `lanes:`. Without them, its sessions draw the lanes: one per session, in declaration
+// order. The lane index of a step is resolved once, by the layout when the run is built (run.json nodes[].lane), and
+// every reader takes it from there.
+
+/** Lane index of each session when the sessions draw the lanes (no `lanes` declared); null when `lanes` are declared. */
+export function sessionLanes (lanes, sessions) {
+  if (!sessions || (Array.isArray(lanes) && lanes.length)) return null
+  return new Map(Object.keys(sessions).map((k, i) => [k, i]))
+}
+
+/**
+ * Names of the lanes, index = lane: the scenario's `lanes`, or (none declared) the titles of its sessions in
+ * declaration order. A localized title reads in `locale`, else its default, else its first language. Self-contained:
+ * the canvas carries the same function.
+ */
+export function laneLabels (lanes, sessions, locale) {
+  const text = (v) => v == null ? '' : typeof v === 'string' ? v : (v[locale] ?? v.default ?? Object.values(v)[0] ?? '')
+  return Array.isArray(lanes) && lanes.length ? lanes.map((l) => text(l)) : Object.entries(sessions || {}).map(([k, s]) => text(s?.title) || k)
+}
+
+/** A plain or localized title as text (the same reading as laneLabels). */
+export const textOf = (v, locale = null) => v == null ? '' : typeof v === 'string' ? v : (v[locale] ?? v.default ?? Object.values(v)[0] ?? '')
+
+/**
+ * Where each step of a run manifest (qawalk.run.v1) sits: Map step id → { session: { key, title } | null,
+ * lane: { index, label } | null }. label is null for a lane without a name (a flow without lanes or sessions, or an
+ * extra row the layout opened for an alternative branch).
+ */
+export function stepPlaces (manifest, locale = null) {
+  const m = manifest || {}
+  const labels = laneLabels(m.lanes, m.sessions, locale)
+  const out = new Map()
+  for (const n of m.nodes || []) {
+    const key = typeof n.session === 'string' && n.session ? n.session : null
+    out.set(n.id, {
+      session: key ? { key, title: textOf(m.sessions?.[key]?.title, locale) || key } : null,
+      lane: Number.isInteger(n.lane) ? { index: n.lane, label: labels[n.lane] || null } : null
+    })
+  }
+  return out
+}
+
+/**
+ * The lanes and sessions of a run manifest as a portal lists them: lanes [{ index, label }] (every named lane and
+ * every lane a step sits in) and sessions [{ key, title }] in declaration order.
+ */
+export function flowStructure (manifest, locale = null) {
+  const m = manifest || {}
+  const labels = laneLabels(m.lanes, m.sessions, locale)
+  const used = new Set(labels.map((_, i) => i))
+  for (const n of m.nodes || []) if (Number.isInteger(n.lane)) used.add(n.lane)
+  return {
+    lanes: [...used].sort((a, b) => a - b).map((index) => ({ index, label: labels[index] || null })),
+    sessions: Object.entries(m.sessions || {}).map(([key, s]) => ({ key, title: textOf(s?.title, locale) || key }))
+  }
+}

package/src/lib/run-refs.mjs

@@ -0,0 +1,55 @@
+// Run references and purpose (#126): the external records a run serves (a change-control record CC-2026-001, a
+// validation protocol) and why it was walked (dry_run, formal, smoke). Set with kaloko start --ref / --purpose or
+// KALOKO_REFS / KALOKO_PURPOSE, kept in the run manifest (refs, purpose) and checked again by the service
+// (worker/src/manifest.js), which stores them so GET …/runs?ref= and ?purpose= can filter. No node: imports: the
+// Worker uses it too.
+
+/** A reference as people write record ids: letters, digits and . _ - / : # +, starting with a letter or digit. */
+export const RUN_REF = /^[A-Za-z0-9][A-Za-z0-9._:/#+-]{0,79}$/
+export const MAX_RUN_REFS = 20
+export const RUN_PURPOSES = ['dry_run', 'formal', 'smoke']
+
+/**
+ * References from options or the environment: an array of values (--ref repeated) or one string, each split at
+ * commas and white space. Trimmed, empty pieces dropped, duplicates removed in order. Not validated: see refProblems.
+ */
+export function splitRunRefs (value) {
+  const list = Array.isArray(value) ? value : value == null || value === true || value === false ? [] : [value]
+  const out = []
+  for (const v of list) for (const piece of String(v).split(/[\s,]+/)) if (piece && !out.includes(piece)) out.push(piece)
+  return out
+}
+
+/** What is wrong with a list of references ([] when it is fine). */
+export function refProblems (refs) {
+  if (!Array.isArray(refs)) return ['refs must be a list of references.']
+  const problems = []
+  if (refs.length > MAX_RUN_REFS) problems.push(`A run takes at most ${MAX_RUN_REFS} references; this one has ${refs.length}.`)
+  for (const r of refs) if (typeof r !== 'string' || !RUN_REF.test(r)) problems.push(`"${String(r).slice(0, 100)}" is not a reference Kaloko keeps: up to 80 letters, digits and . _ - / : # +, starting with a letter or digit.`)
+  if (new Set(refs).size !== refs.length) problems.push('refs names a reference twice.')
+  return problems
+}
+
+/**
+ * The references and purpose of kaloko start: --ref (repeated or comma separated) or else KALOKO_REFS, --purpose or
+ * else KALOKO_PURPOSE. Returns { refs, purpose, problems }; problems name the option or variable they came from.
+ */
+export function startRefs (args = {}, env = {}) {
+  const fromFlag = args.ref !== undefined && args.ref !== true && !(Array.isArray(args.ref) && args.ref.every((v) => v === true))
+  const refs = splitRunRefs(fromFlag ? [].concat(args.ref).filter((v) => v !== true) : env.KALOKO_REFS)
+  const problems = []
+  if (args.ref === true || (Array.isArray(args.ref) && args.ref.includes(true))) problems.push('--ref takes a reference, e.g. --ref CC-2026-001.')
+  for (const p of refProblems(refs)) problems.push(`${fromFlag ? '--ref' : 'KALOKO_REFS'}: ${p}`)
+  const given = typeof args.purpose === 'string' ? args.purpose : args.purpose === true ? '' : env.KALOKO_PURPOSE
+  const purpose = normalizePurpose(given)
+  if (args.purpose === true) problems.push(`--purpose takes one of ${RUN_PURPOSES.join(', ')}.`)
+  else if (purpose === undefined) problems.push(`${typeof args.purpose === 'string' ? '--purpose' : 'KALOKO_PURPOSE'} is "${String(given).slice(0, 40)}"; use ${RUN_PURPOSES.join(', ')}.`)
+  return { refs, purpose: purpose || null, problems }
+}
+
+/** dry_run | formal | smoke from what people type (dry-run, Formal); null when empty; undefined when not a purpose. */
+export function normalizePurpose (value) {
+  if (value == null || value === '') return null
+  const p = String(value).trim().toLowerCase().replace(/-/g, '_')
+  return RUN_PURPOSES.includes(p) ? p : undefined
+}

package/src/lib/run.mjs

@@ -37,7 +37,7 @@ export function newRunId (scenario, date = new Date()) {
   return { id: `${today(date)}-${slugify(scenario.id)}-${short}`, short }
 }
 
-export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, appVersion = null, product = null, pii = null }) {
+export async function createRun ({ output, scenario, scenarioFile, env, scope, git, executor, root, project = null, issue = null, refs = [], purpose = null, appVersion = null, product = null, pii = null }) {
   const { id, short } = newRunId(scenario)
   const dir = resolve(root, output, id)
   await mkdir(dir, { recursive: true })
@@ -54,6 +54,9 @@ export async function createRun ({ output, scenario, scenarioFile, env, scope, g
     executor,
     project,
     issue,
+    // the records the run serves (change control, protocol) and why it was walked (#126; src/lib/run-refs.mjs)
+    ...(refs?.length ? { refs } : {}),
+    ...(purpose ? { purpose } : {}),
     app_version: appVersion,
     // personal data hidden in every capture (#64): { mode: redact | pseudonymize, allow }
     ...(pii ? { pii } : {}),

package/src/lib/scenario.mjs

@@ -4,6 +4,7 @@ import { schemaErrors } from './schema.mjs'
 import { UserError } from './util.mjs'
 import { expandPacks } from './packs.mjs'
 import { jsGuard } from './assertions.mjs'
+import { sessionLanes } from './lanes-core.mjs'
 
 // a scenario holds thousands of values, not millions: aliases (&a, *a) can expand a few kilobytes of YAML into
 // billions that validation and its JSON copy would walk ("billion laughs"), so the expanded size has a ceiling
@@ -156,7 +157,7 @@ export function layout (scenario) {
   const taken = new Set()
   const claim = (c, l) => { while (taken.has(`${c}:${l}`)) l++; taken.add(`${c}:${l}`); return l }
   // sessions without explicit lanes: one swimlane per person, in declaration order
-  const sessionLane = scenario.sessions && !(scenario.lanes || []).length ? new Map(Object.keys(scenario.sessions).map((k, i) => [k, i])) : null
+  const sessionLane = sessionLanes(scenario.lanes, scenario.sessions)
   for (const n of [...nodes].sort((a, b) => col.get(a.id) - col.get(b.id) || order.get(a.id) - order.get(b.id))) {
     let wanted = n.lane
     if (wanted == null && sessionLane && n.session != null && sessionLane.has(n.session)) wanted = sessionLane.get(n.session)

package/src/lib/signoff.mjs

@@ -143,6 +143,10 @@ export async function evidenceCmd ({ config, args, say, client, runId = null })
     const product = typeof args.product === 'string' ? args.product : Object.keys(config.products || {}).length === 1 ? Object.keys(config.products)[0] : (config.project || null)
     if (!product) throw new UsageError('Name the product of the release: --product <slug>.')
     path = `/orgs/${config.org}/evidence?product=${encodeURIComponent(product)}&version=${encodeURIComponent(release)}`
+    // only the release's runs of one record or purpose (#126)
+    const ref = typeof args.ref === 'string' ? args.ref : null
+    if (ref) path += `&ref=${encodeURIComponent(ref)}`
+    if (typeof args.purpose === 'string') path += `&purpose=${encodeURIComponent(args.purpose)}`
   } else path = `/orgs/${config.org}/runs/${encodeURIComponent(runId)}/evidence`
   const ev = await client.request('GET', path)
   const text = args.csv ? traceCsv(ev.trace || []) : JSON.stringify(ev, null, 2)

package/src/lib/update-check.mjs

@@ -0,0 +1,132 @@
+// "Is this in a newer kaloko?": when someone types a command, sub-command or option this kaloko does not know, the
+// commands of the newest released kaloko (GET <service>/cli/latest.json, cached for a day) say whether updating
+// helps. A line says so only when that version is newer than this one and has exactly what was typed; offline, a
+// slow answer, an odd answer or KALOKO_NO_UPDATE_CHECK=1 mean no line, never an error or a wait over 1.5 s.
+import { readFile, writeFile, mkdir } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname, sep } from 'node:path'
+import { serviceUrl } from './service.mjs'
+import { compareVersions } from './changelog-core.mjs'
+
+export const CATALOGUE_PATH = '/cli/latest.json'
+export const TIMEOUT_MS = 1500
+const FRESH_MS = 24 * 3600e3 // a catalogue read from the service
+const RETRY_MS = 3600e3 // no answer: ask again after an hour, not on every typo
+const NAME = /^[a-z][a-z0-9-]*$/
+
+/** Off with KALOKO_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER, the npm convention) and with --offline. */
+export const updateCheckOff = (env = process.env, args = {}) => !!(truthy(env.KALOKO_NO_UPDATE_CHECK) || truthy(env.NO_UPDATE_NOTIFIER) || args.offline)
+const truthy = (v) => v !== undefined && v !== '' && v !== '0' && v !== 'false'
+
+/** Where the catalogue is kept: KALOKO_CACHE_DIR, else the OS cache folder (~/.cache/kaloko, %LOCALAPPDATA%\kaloko). */
+export function cacheDir (env = process.env, os = process.platform) {
+  if (env.KALOKO_CACHE_DIR) return env.KALOKO_CACHE_DIR
+  if (os === 'win32' && env.LOCALAPPDATA) return join(env.LOCALAPPDATA, 'kaloko', 'cache')
+  return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'kaloko')
+}
+
+/** A catalogue as the service sends it, or null when it is not one: { version, commands: { name: { flags, subcommands } } }. */
+export function validCatalogue (c) {
+  if (!c || typeof c !== 'object' || typeof c.version !== 'string' || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(c.version)) return null
+  if (!c.commands || typeof c.commands !== 'object' || Array.isArray(c.commands)) return null
+  const names = (list) => Array.isArray(list) && list.every((f) => typeof f === 'string' && NAME.test(f))
+  for (const [name, cmd] of Object.entries(c.commands)) {
+    if (!NAME.test(name) || !cmd || !names(cmd.flags)) return null
+    if (cmd.subcommands !== undefined && (typeof cmd.subcommands !== 'object' || !Object.entries(cmd.subcommands).every(([s, v]) => NAME.test(s) && v && names(v.flags)))) return null
+  }
+  return c
+}
+
+/**
+ * The newest kaloko's catalogue: from the cache while it is fresh, else from the service (one try, `timeout` ms).
+ * Null when the check is off or nothing usable came back.
+ */
+export async function newestCatalogue ({ config = {}, env = process.env, fetchImpl = fetch, now = Date.now(), timeout = TIMEOUT_MS, args = {} } = {}) {
+  if (updateCheckOff(env, args)) return null
+  let url
+  try { url = `${serviceUrl(config, env)}${CATALOGUE_PATH}` } catch { return null }
+  const file = join(cacheDir(env), 'cli-latest.json')
+  let cached = null
+  try { cached = JSON.parse(await readFile(file, 'utf8')) } catch {}
+  if (cached?.url === url && typeof cached.fetched_at === 'number' && cached.fetched_at <= now) {
+    const age = now - cached.fetched_at
+    if (cached.catalogue && age < FRESH_MS) return validCatalogue(cached.catalogue)
+    if (!cached.catalogue && age < RETRY_MS) return null
+  }
+  let catalogue = null
+  const ctl = new AbortController()
+  const timer = setTimeout(() => ctl.abort(), timeout)
+  try {
+    const res = await fetchImpl(url, { signal: ctl.signal, redirect: 'follow', headers: { Accept: 'application/json', 'User-Agent': 'kaloko-cli' } })
+    if (res.ok) catalogue = validCatalogue(JSON.parse(await res.text()))
+  } catch {} finally { clearTimeout(timer) }
+  try { await mkdir(dirname(file), { recursive: true }); await writeFile(file, JSON.stringify({ url, fetched_at: now, catalogue })) } catch {}
+  return catalogue
+}
+
+/**
+ * What a newer kaloko has of what was typed, or null: `catalogue` must be newer than `installed` and have the command,
+ * the sub-command or the options exactly. { words: 'projects create', version } or { words: 'init --site', version }.
+ */
+export function newerHas (catalogue, installed, { command, sub = null, options = [] }) {
+  if (!validCatalogue(catalogue) || !installed || compareVersions(catalogue.version, installed) <= 0) return null
+  const cmd = Object.hasOwn(catalogue.commands, command) ? catalogue.commands[command] : null
+  if (!cmd) return null
+  const out = (words) => ({ words: `${command} ${words}`.trim(), version: catalogue.version })
+  if (sub && cmd.subcommands && Object.hasOwn(cmd.subcommands, sub)) return out(sub)
+  const known = options.filter((o) => cmd.flags.includes(o))
+  if (known.length) return { ...out(known.map((o) => `--${o}`).join(' ')), options: known }
+  if (!sub && !options.length) return out('')
+  return null
+}
+
+/**
+ * How this project gets a newer kaloko: the package manager's add command when package.json lists kaloko (lockfile
+ * decides npm, pnpm, yarn or bun), npx kaloko@latest when this kaloko runs from the npx cache, else both.
+ */
+export function installCommand ({ cwd = process.cwd(), root = null, words = '' } = {}) {
+  const npx = `npx kaloko@latest${words ? ` ${words}` : ''}`
+  if (root && root.split(sep).includes('_npx')) return { run: npx }
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    const pkg = join(dir, 'package.json')
+    if (existsSync(pkg)) {
+      let p = null
+      try { p = JSON.parse(readFileSync(pkg, 'utf8')) } catch {}
+      const dev = !!p?.devDependencies?.kaloko
+      if (!dev && !p?.dependencies?.kaloko) break
+      const d = dev ? ' -D' : ''
+      const pm = existsSync(join(dir, 'pnpm-lock.yaml')) ? `pnpm add${d}` : existsSync(join(dir, 'yarn.lock')) ? `yarn add${d}` : existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock')) ? `bun add${dev ? ' -d' : ''}` : `npm i${d}`
+      return { update: `${pm} kaloko@latest` }
+    }
+    if (dirname(dir) === dir) break
+  }
+  return { update: 'npm i -D kaloko@latest', run: npx }
+}
+
+/** "kaloko projects create is in kaloko 0.16.0 (you have 0.15.0). Update: npm i -D kaloko@latest" */
+export function updateLine ({ words, version }, installed, how) {
+  const what = `kaloko ${words} ${/ --\S+ --/.test(` ${words}`) ? 'are' : 'is'} in kaloko ${version} (you have ${installed}).`
+  if (how.update && how.run) return `${what} Update: ${how.update} (or run ${how.run})`
+  return how.update ? `${what} Update: ${how.update}` : `${what} Run it with ${how.run}`
+}
+
+/**
+ * For something this kaloko does not know (`typed`: { command, sub, options }), or null: the cached or fetched
+ * catalogue must be newer and have it. { line, update: line, newer: [the options it takes] }.
+ */
+export async function updateHint (typed, { installed, config = {}, env = process.env, fetchImpl = fetch, cwd = process.cwd(), root = null, args = {}, now } = {}) {
+  const catalogue = await newestCatalogue({ config, env, fetchImpl, args, ...(now ? { now } : {}) })
+  const has = catalogue && newerHas(catalogue, installed, typed)
+  if (!has) return null
+  const line = updateLine(has, installed, installCommand({ cwd, root, words: has.words }))
+  return { line, update: line, newer: has.options || [] }
+}
+
+/** The doctor line: this version, and the newest one when it is newer (from the same cached catalogue). */
+export async function versionCheck ({ installed, config = {}, env = process.env, fetchImpl = fetch, cwd = process.cwd(), root = null }) {
+  const catalogue = await newestCatalogue({ config, env, fetchImpl })
+  if (!catalogue || compareVersions(catalogue.version, installed) <= 0) return { installed, newest: catalogue?.version || null, newer: false, detail: catalogue ? `${installed} (the newest)` : installed }
+  const how = installCommand({ cwd, root })
+  return { installed, newest: catalogue.version, newer: true, detail: `${installed} · a newer kaloko is available: ${catalogue.version} (${how.update ? how.update : how.run})` }
+}