@starci/hfs 4.7.23 → 4.7.24

package/runtime/scripts/lib/gate-loosening.mjs

@@ -0,0 +1,248 @@
+// gate-loosening.mjs — what "loosens a gate" means, mechanically (modules/kernel/gate-loosening.yaml), over the unified diff of one change.
+// A loosening is one of:
+//   check-removed      a list item removed from a gate file and not added back in the same file (an item that carries an id is the
+//                      same item while an added item carries that id: a row whose fields change stays a check)
+//   check-narrowed     an enforcer row `{kind, id, editions}` that keeps its kind and id but now runs in fewer editions (a lost restriction or
+//                      a superset of editions is a widening, never a loosening)
+//   threshold-lowered  a number of a gate file moved the loose way: a floor lowered, a ceiling raised
+//   allowlist-added    a list item added to an allowlist file
+//   spec-deleted       a spec file deleted in a change that also changes product code
+//   assertion-weakened a spec that loses more assertions than it gains in a change that also changes product code
+//   spec-skipped       a skip marker added to a spec in a change that also changes product code
+// A change that renames paths (a git rename, `git diff -M`) may MOVE the entries that name them: a removed line and an added line of the
+// same file that are equal once every renamed prefix of the removed line is rewritten to its new name are one entry moved, not a check
+// removed and an exception added (renamedPrefixesOf, movedLinesOf). A moved entry that also changes in any other way (a widened glob, an
+// extra path) is still judged as a removal and an addition.
+// The finding id is `<kind>:<file>:<detail>`. A loosening is always red (owner ruling loosening-always-red, 2026-10-22): there is no
+// approval that lets one through, so a change that loosens a gate is fixed by restoring the gate (looseningStep).
+// Only what a release shipped can be loosened (loosensReleased): a check, a spec or an assertion added after the release and folded
+// away before the next one never was a gate of a release.
+import { byCodeUnit } from './list.mjs';
+
+const LIST_ITEM = /^\s*-\s+\S/;
+const NUMBER_LINE = /^\s*(?:-\s+)?([A-Za-z][\w.-]*):\s*(-?\d+(?:\.\d+)?)\s*(?:#.*)?$/;
+
+/** The files of a unified diff: [{file, deleted, added[], removed[]}] (changed lines without their marker). */
+export function parseDiff(text) {
+  const files = [];
+  let current = null;
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const header = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+    if (header) { current = { file: header[2], deleted: false, added: [], removed: [] }; files.push(current); continue; }
+    if (!current) continue;
+    if (line.startsWith('deleted file mode')) current.deleted = true;
+    else if (line.startsWith('+') && !line.startsWith('+++')) current.added.push(line.slice(1));
+    else if (line.startsWith('-') && !line.startsWith('---')) current.removed.push(line.slice(1));
+  }
+  return files;
+}
+
+/** The rename lines `R<score> <old> <new>` (tab separated) of `git diff --name-status -M`: [{from, to}]. */
+const renamesOf = (nameStatus) => String(nameStatus ?? '').split(/\r?\n/).map((line) => line.split('\t'))
+  .filter((fields) => /^R\d*$/.test(fields[0] ?? '') && fields.length === 3).map(([, from, to]) => ({ from, to }));
+
+/** The moved prefix of one renamed file: its old and new path without the trailing segments they share. */
+function movedPrefixOf({ from, to }) {
+  const before = from.split('/');
+  const after = to.split('/');
+  while (before.length > 1 && after.length > 1 && before.at(-1) === after.at(-1)) { before.pop(); after.pop(); }
+  return { from: before.join('/'), to: after.join('/') };
+}
+
+/**
+ * The path prefixes a change renamed, from its `git diff --name-status -M` output: [{from, to}], longest `from` first. A prefix is kept only
+ * when every renamed file under it moved to the same new prefix; an old prefix that went two ways names no single move and is dropped.
+ */
+export function renamedPrefixesOf(nameStatus) {
+  const targets = new Map();
+  for (const { from, to } of renamesOf(nameStatus).map(movedPrefixOf)) {
+    if (from === to) continue;
+    if (!targets.has(from)) targets.set(from, new Set());
+    targets.get(from).add(to);
+  }
+  return [...targets].filter(([, to]) => to.size === 1).map(([from, to]) => ({ from, to: [...to][0] }))
+    .sort((a, b) => b.from.length - a.from.length || byCodeUnit(a.from, b.from));
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
+/** `line` with every renamed prefix rewritten to its new name; a prefix matches only as a whole path (not inside a longer name). */
+function renamedLine(line, prefixes) {
+  return prefixes.reduce((text, { from, to }) => text.replace(new RegExp(String.raw`(?<![\w./-])${escapeRegExp(from)}(?![\w.-])`, 'g'), to), line);
+}
+
+/**
+ * One file of a change without its moved entries: each removed line whose renamed form is exactly an added line is paired with it, and
+ * both are left out. A line the rename does not touch is never paired, so an entry merely removed or added stays.
+ */
+export function movedLinesOf(entry, prefixes) {
+  if (!prefixes.length) return entry;
+  const unpaired = new Map();
+  for (const line of entry.added) unpaired.set(line, (unpaired.get(line) ?? 0) + 1);
+  const paired = new Map();
+  const removed = entry.removed.filter((line) => {
+    const moved = renamedLine(line, prefixes);
+    if (moved === line || (unpaired.get(moved) ?? 0) <= 0) return true;
+    unpaired.set(moved, unpaired.get(moved) - 1);
+    paired.set(moved, (paired.get(moved) ?? 0) + 1);
+    return false;
+  });
+  const added = entry.added.filter((line) => {
+    if ((paired.get(line) ?? 0) <= 0) return true;
+    paired.set(line, paired.get(line) - 1);
+    return false;
+  });
+  return { ...entry, added, removed };
+}
+
+const keyWords = (key) => key.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+const trimmed = (line) => line.trim();
+const clip = (text) => (text.length > 90 ? `${text.slice(0, 89)}…` : text);
+
+/** What makes a list item the same item: its id when it carries one, else its text. */
+function identityOf(line) {
+  const item = trimmed(line).slice(1).trimStart();
+  const body = (item.startsWith('{') ? item.slice(1) : item).trimStart();
+  if (!body.startsWith('id:')) return trimmed(line);
+  const id = body.slice(3).trimStart().split(/[,}\s]/)[0];
+  return id ? `id:${id}` : trimmed(line);
+}
+
+/** Splits `a: 1, b: [x, y]` at the commas outside square brackets. */
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let from = 0;
+  for (let at = 0; at < text.length; at += 1) {
+    if (text[at] === '[') depth += 1;
+    else if (text[at] === ']') depth -= 1;
+    else if (text[at] === ',' && depth === 0) { parts.push(text.slice(from, at)); from = at + 1; }
+  }
+  parts.push(text.slice(from));
+  return parts;
+}
+
+/** The flow-mapping enforcer row `- {kind: k, id: i, editions: [a, b]}`: {kind, id, editions} (editions null = every edition), or null. */
+function flowRow(line) {
+  const text = line.trim();
+  if (!text.startsWith('-')) return null;
+  const open = text.indexOf('{');
+  const close = text.lastIndexOf('}');
+  if (open < 1 || close < open || text.slice(1, open).trim() !== '') return null;
+  const fields = new Map();
+  for (const part of splitTopLevel(text.slice(open + 1, close))) {
+    const at = part.indexOf(':');
+    if (at > 0) fields.set(part.slice(0, at).trim(), part.slice(at + 1).trim());
+  }
+  if (!fields.has('kind') || !fields.has('id')) return null;
+  const editions = fields.get('editions');
+  const list = editions === undefined ? null : editions.replace('[', '').replace(']', '').split(',').map((value) => value.trim()).filter(Boolean);
+  return { kind: fields.get('kind'), id: fields.get('id'), editions: list };
+}
+
+/** Whether row `after` still runs everywhere row `before` ran: a lost restriction or a superset of editions widens, a subset narrows. */
+const coversEditions = (before, after) => after.editions === null || (before.editions !== null && before.editions.every((edition) => after.editions.includes(edition)));
+
+/** The removed list items of a gate file that no added line restores; an enforcer row that keeps its kind and id may only widen its editions. */
+function checksRemoved(entry) {
+  const back = new Map();
+  for (const line of entry.added.filter((value) => LIST_ITEM.test(value))) back.set(identityOf(line), (back.get(identityOf(line)) ?? 0) + 1);
+  const addedRows = entry.added.map(flowRow).filter(Boolean);
+  return entry.removed.filter((value) => LIST_ITEM.test(value)).flatMap((value) => {
+    const row = flowRow(value);
+    if (row) {
+      const same = addedRows.filter((candidate) => candidate.kind === row.kind && candidate.id === row.id);
+      if (same.length) {
+        if (same.some((candidate) => coversEditions(row, candidate))) return [];
+        return [{ kind: 'check-narrowed', file: entry.file, detail: clip(trimmed(value)) }];
+      }
+    }
+    const left = back.get(identityOf(value)) ?? 0;
+    if (left > 0) { back.set(identityOf(value), left - 1); return []; }
+    return [{ kind: 'check-removed', file: entry.file, detail: clip(trimmed(value)) }];
+  });
+}
+
+const numbersOf = (lines) => lines.map((line) => NUMBER_LINE.exec(line)).filter(Boolean).map((match) => ({ key: match[1], value: Number(match[2]) }));
+
+/** The thresholds of a gate file moved the loose way. */
+function thresholdsLowered(entry, rules) {
+  const added = numbersOf(entry.added);
+  return numbersOf(entry.removed).flatMap((before) => {
+    const after = added.find((candidate) => candidate.key === before.key);
+    if (!after || after.value === before.value) return [];
+    const words = keyWords(before.key);
+    const lowered = words.some((word) => rules.thresholds.floors.includes(word)) && after.value < before.value;
+    const raised = words.some((word) => rules.thresholds.ceilings.includes(word)) && after.value > before.value;
+    return lowered || raised ? [{ kind: 'threshold-lowered', file: entry.file, detail: `${before.key} ${before.value} -> ${after.value}` }] : [];
+  });
+}
+
+const SPEC_NAME = /\.spec\.[cm]?[jt]sx?$/;
+const isSpec = (file, rules) => rules.specRoots.some((root) => file.startsWith(root)) && SPEC_NAME.test(file);
+const countOf = (lines, markers) => lines.filter((line) => markers.some((marker) => line.includes(marker))).length;
+
+const baseName = (file) => file.slice(file.lastIndexOf('/') + 1);
+
+/** Whether a spec of the same name is written elsewhere in the change: a moved spec is not a deleted one. */
+const movedSpec = (entry, files, rules) => files.some((other) => other !== entry && !other.deleted && isSpec(other.file, rules) && baseName(other.file) === baseName(entry.file));
+
+/** The spec findings of one file of a change that also changes product code. */
+function specFindings(entry, files, rules) {
+  if (entry.deleted) return movedSpec(entry, files, rules) ? [] : [{ kind: 'spec-deleted', file: entry.file, detail: 'deleted' }];
+  const weaker = countOf(entry.removed, rules.assertionMarkers) - countOf(entry.added, rules.assertionMarkers);
+  const skipped = countOf(entry.added, rules.skipMarkers) - countOf(entry.removed, rules.skipMarkers);
+  return [...(weaker > 0 ? [{ kind: 'assertion-weakened', file: entry.file, detail: `${weaker} assertion(s) fewer` }] : []),
+    ...(skipped > 0 ? [{ kind: 'spec-skipped', file: entry.file, detail: `${skipped} skip marker(s) added` }] : [])];
+}
+
+const changesProduct = (files, rules) => files.some((entry) => !isSpec(entry.file, rules) && rules.productPrefixes.some((prefix) => entry.file.startsWith(prefix)));
+
+/**
+ * Every loosening of the change `diffText`, sorted: [{id, kind, file, detail}]. `rules` is modules/kernel/gate-loosening.yaml; `renamed`
+ * is the change's renamed prefixes (renamedPrefixesOf), whose moved entries are no loosening.
+ */
+export function looseningsOf(diffText, rules, { renamed = [] } = {}) {
+  const files = parseDiff(diffText).map((entry) => movedLinesOf(entry, renamed));
+  const product = changesProduct(files, rules);
+  const found = files.flatMap((entry) => [
+    ...(rules.gateFiles.includes(entry.file) ? [...checksRemoved(entry), ...thresholdsLowered(entry, rules)] : []),
+    ...(rules.allowlistFiles.includes(entry.file) ? entry.added.filter((value) => LIST_ITEM.test(value)).map((value) => ({ kind: 'allowlist-added', file: entry.file, detail: clip(trimmed(value)) })) : []),
+    ...(product && isSpec(entry.file, rules) ? specFindings(entry, files, rules) : []),
+  ]);
+  return found.map((finding) => ({ ...finding, id: `${finding.kind}:${finding.file}:${finding.detail}` })).sort((a, b) => byCodeUnit(a.id, b.id));
+}
+
+/** One finding as the land gate and the self-check print it. */
+export const looseningLine = (finding) => `${finding.kind} ${finding.file}: ${finding.detail}`;
+
+/**
+ * The land gate's step for a change that loosens a gate: always red, with the way out that exists, restoring the gate. There is no
+ * approval: a loosening never lands (owner ruling loosening-always-red).
+ */
+export const looseningStep = (findings) => ({
+  name: 'gate-loosening', ok: false, findings, output: findings.map(looseningLine).join('\n'),
+  hint: 'a change that loosens a gate never lands (owner ruling loosening-always-red): restore every gate listed above',
+});
+
+const assertionsIn = (text, markers) => String(text ?? '').split('\n').filter((line) => markers.some((marker) => line.includes(marker))).length;
+
+/** The detail of a check-removed finding without its clipping mark: the start of the removed line. */
+const shownDetail = (detail) => (detail.endsWith('…') ? detail.slice(0, -1) : detail);
+
+/**
+ * Whether `finding` loosens the state released at `base`, read through `read(rev, file)` (text, or null when the revision holds no such
+ * file); `rules` gives the assertion markers. A finding stays only when
+ *   check-removed       the removed list item is an item of that gate file at the release commit
+ *   spec-deleted        the spec exists at the release commit
+ *   spec-skipped        the spec exists at the release commit
+ *   assertion-weakened  the spec exists at the release commit and holds fewer assertion lines now than it held there
+ * (every other kind loosens whenever its file existed at the release).
+ */
+export function loosensReleased(finding, { base, read, rules }) {
+  const before = read(base, finding.file);
+  if (before === null) return false;
+  if (finding.kind === 'check-removed') return before.split('\n').some((line) => line.trim().startsWith(shownDetail(finding.detail)));
+  if (finding.kind !== 'assertion-weakened') return true;
+  return assertionsIn(read('HEAD', finding.file), rules.assertionMarkers) < assertionsIn(before, rules.assertionMarkers);
+}

package/runtime/scripts/lib/managed-json.mjs

@@ -0,0 +1,51 @@
+// managed-json.mjs - which JSON files are managed canon rather than authored JSON (knowledge/hfs/slots.yaml `managedBy` /
+// `liteManagedBy`): a template of @starci/hfs that a managed slot names (templates/<scope or common>/<group>/<path, each leading dot
+// dropped>), declared by the slot manifest and nowhere else, and an app's render of one, which `starci app sync` writes. Only a template
+// with no `{{variable}}` is a render candidate, and only a file whose text equals that template (line endings aside) is its render:
+// a file that differs in any byte stays authored.
+import { braceVariants } from './glob.mjs';
+
+const SIDES = Object.freeze(['be', 'fe']);
+const lf = (text) => String(text).replace(/\r\n/g, '\n');
+/** A literal file path of a slot (no wildcard or variable): only those are whole managed files. */
+const literal = (file) => !/[*?[<]/.test(file);
+const undotted = (file) => file.split('/').map((segment) => segment.replace(/^\./, '')).join('/');
+
+/** The scope (app, be or fe) and scope-relative path of an app-relative path, one per profile a slot may hold it in. */
+const placementsOf = (appRel) => [
+  { scope: 'app', file: appRel },
+  ...SIDES.filter((side) => appRel.startsWith(`${side}/`)).map((side) => ({ scope: side, file: appRel.slice(side.length + 1) })),
+];
+
+/**
+ * The template names (relative to the @starci/hfs templates folder) a managed slot of `manifest` renders `appRel` from, in every
+ * edition: [] when no managed slot lists that literal file.
+ */
+export function managedTemplatesOf(manifest, appRel) {
+  const placements = placementsOf(appRel);
+  const matches = managedFilesOf(manifest).filter((managed) => placements.some(({ scope, file }) => managed.scope === scope && managed.file === file));
+  return [...new Set(matches.map((managed) => managed.name))];
+}
+
+/** Every literal file of every managed slot, with its scope and the template name it is rendered from: [{scope, file, name}]. */
+function managedFilesOf(manifest) {
+  return (manifest?.slots ?? []).flatMap((slot) => {
+    const groups = [...new Set([slot.managedBy, slot.liteManagedBy].filter((group) => typeof group === 'string'))];
+    const paths = [slot.path, slot.lite?.path].filter((value) => typeof value === 'string').flatMap(braceVariants).filter(literal);
+    return (slot.profiles ?? []).flatMap((scope) => paths.flatMap((file) => groups.flatMap((group) =>
+      [scope, 'common'].map((dir) => ({ scope, file, name: `${dir}/${group}/${undotted(file)}` })))));
+  });
+}
+
+/**
+ * Every template name a managed slot of `manifest` declares (its literal files in each profile, edition group and scope or common
+ * folder): the canon source `starci app sync` renders from, which the slot manifest itself names, so a template is declared there and
+ * nowhere else.
+ */
+export function declaredTemplateNames(manifest) {
+  return new Set(managedFilesOf(manifest).map((managed) => managed.name));
+}
+
+/** Whether `text` is the render of one of `templates` ([{name, text}]): a template with no variable whose text equals it. */
+export const isManagedRender = (text, templates) =>
+  templates.some((template) => typeof template.text === 'string' && !template.text.includes('{{') && lf(template.text) === lf(text));

package/runtime/scripts/lib/uat-run-folder.mjs

@@ -0,0 +1,118 @@
+// uat-run-folder.mjs - the pure half of `starci uat record` (scripts/uat/uat-record.mjs): what a finished UAT run folder must
+// hold, how a verified blob is curated into an example's fixture store, the work/evidence@1 document of one run and its outcome
+// rule. The verb owns the browser, the UAT slot and the artifact store; this module owns the shapes. It is bundled into
+// @starci/hfs (sync-runtime.mjs), whose spec src/uat-run-folder.spec.mjs proves it (owner ruling no-runtime-specs).
+import crypto from 'node:crypto';
+import { sha256 } from '../../engine/digest.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { byCodeUnit } from '../../engine/by-code-unit.mjs';
+
+export const UAT_RECORD_FLOW_UNKNOWN = 'UAT_RECORD_FLOW_UNKNOWN';
+export const UAT_RECORD_RUN_INCOMPLETE = 'UAT_RECORD_RUN_INCOMPLETE';
+export const UAT_RECORD_ASSET_INVALID = 'UAT_RECORD_ASSET_INVALID';
+const OUTCOMES = new Set(['pass', 'fail', 'partial-pass']);
+const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const WEBM = Buffer.from([0x1a, 0x45, 0xdf, 0xa3]);
+const RUN_PARTS = Object.freeze(['manifest.yaml', 'result.md', 'screens', 'videos']);
+const FOLDERS = Object.freeze([['screens', '.png', 'image/png', PNG], ['videos', '.webm', 'video/webm', WEBM]]);
+
+/** A typed refusal of `starci uat record`. */
+export const uatRecordRefusal = (code, message) => Object.assign(new Error(`${code}: ${message}`), { code });
+
+/** A run id in the evidence schema's shape: <UTC yyyymmddThhmmssZ>-<8 hex>. */
+export const newRunId = (now = new Date(), random = crypto.randomBytes(4).toString('hex')) =>
+  `${now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')}-${random}`;
+
+const startsWith = (file, signature) => {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const head = Buffer.alloc(signature.length);
+    fs.readSync(fd, head, 0, head.length, 0);
+    return head.equals(signature);
+  } finally { fs.closeSync(fd); }
+};
+
+/** The refusal text of a run folder whose top level is not exactly its four parts, or null. */
+function partsProblem(top) {
+  const missing = RUN_PARTS.filter((name) => !top.includes(name));
+  const extra = top.filter((name) => !RUN_PARTS.includes(name));
+  if (!missing.length && !extra.length) return null;
+  const said = [`the run folder holds exactly ${RUN_PARTS.join(', ')}`];
+  if (missing.length) said.push(`missing ${missing.join(', ')}`);
+  if (extra.length) said.push(`unexpected ${extra.join(', ')}`);
+  return said.join('; ');
+}
+
+/**
+ * Check a finished run folder: exactly manifest.yaml, result.md, screens/ (one or more PNG) and videos/ (one or more WebM), every
+ * file non-empty and of its type by its bytes. Returns {manifest, files: [{name, file, mediaType}]} or throws a refusal.
+ */
+export function readRunFolder(runDir) {
+  const problem = partsProblem(fs.readdirSync(runDir).sort(byCodeUnit));
+  if (problem) throw uatRecordRefusal(UAT_RECORD_RUN_INCOMPLETE, problem);
+  const files = [];
+  const add = (name, mediaType, signature) => {
+    const file = path.join(runDir, ...name.split('/'));
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size === 0) throw uatRecordRefusal(UAT_RECORD_ASSET_INVALID, `${name} is empty or not a file`);
+    if (signature && !startsWith(file, signature)) throw uatRecordRefusal(UAT_RECORD_ASSET_INVALID, `${name} is not a ${mediaType} file by its bytes`);
+    files.push({ name, file, mediaType });
+  };
+  add('manifest.yaml', 'application/yaml');
+  add('result.md', 'text/markdown');
+  for (const [dir, ext, mediaType, signature] of FOLDERS) {
+    const names = fs.readdirSync(path.join(runDir, dir)).sort(byCodeUnit);
+    if (!names.length) throw uatRecordRefusal(UAT_RECORD_RUN_INCOMPLETE, `${dir}/ holds no ${ext} file`);
+    for (const name of names) {
+      if (path.extname(name).toLowerCase() !== ext) throw uatRecordRefusal(UAT_RECORD_RUN_INCOMPLETE, `${dir}/${name} is not a ${ext} file`);
+      add(`${dir}/${name}`, mediaType, signature);
+    }
+  }
+  let manifest;
+  try { manifest = parseYaml(fs.readFileSync(path.join(runDir, 'manifest.yaml'), 'utf8')); }
+  catch (error) { throw uatRecordRefusal(UAT_RECORD_RUN_INCOMPLETE, `manifest.yaml does not parse: ${error.message}`); }
+  if (!manifest || !OUTCOMES.has(manifest.outcome)) throw uatRecordRefusal(UAT_RECORD_RUN_INCOMPLETE, 'manifest.yaml carries no outcome of pass, fail or partial-pass');
+  return { manifest, files };
+}
+
+/**
+ * Where one verified blob goes in an example's fixture store (`root`) and what its sidecar says: <root>/<ab>/<sha> and <sha>.json.
+ * The fixture store is tracked source written only by `starci uat record`, which writes these paths and re-hashes the result with
+ * curatedProblem. Pure: no write here.
+ */
+export function curationOf(root, { sha256: digest, bytes, mediaType, createdAt }) {
+  const dir = path.join(root, digest.slice(0, 2));
+  const file = path.join(dir, digest);
+  return { dir, file, sidecar: `${file}.json`, sidecarText: JSON.stringify({ size: bytes.length, mediaType, createdAt }) };
+}
+
+/** The refusal of a curated blob whose stored bytes do not hash to its name, or null. */
+export const curatedProblem = (digest, storedBytes) => (sha256(storedBytes) === digest
+  ? null
+  : uatRecordRefusal(UAT_RECORD_ASSET_INVALID, `the curated blob ${digest.slice(0, 12)} does not hash to its name`));
+
+/** The verdict: pass only when the walk exited 0 and its own manifest says pass. */
+export const recordedOutcome = (exitCode, manifest) => (exitCode === 0 ? manifest.outcome : 'fail');
+
+/**
+ * The work/evidence@1 document of one recorded run. `cited` is [{name, sha256}] for every file of the run folder; `recordDigest`
+ * is the sha256 of the flow record's index.yaml as it stands.
+ */
+export function evidenceOf({ recordId, recordDigest, runId, outcome, cited, command, environment, capturedAt, baseUrl }) {
+  const byDir = (dir) => cited.filter((entry) => entry.name.startsWith(`${dir}/`)).map(({ name, sha256 }) => ({ name, sha256 }));
+  const result = cited.find((entry) => entry.name === 'result.md');
+  const stack = baseUrl
+    ? { stack: `The walk drove the app served at ${baseUrl} and the dev stack its .starcistacks declares, in a real browser recorded by the runtime's Playwright recorder.` }
+    : {};
+  return {
+    schema: 'work/evidence@1',
+    record: recordId,
+    recordDigest,
+    run: { id: runId, outcome, result: { name: result.name, sha256: result.sha256 }, screens: byDir('screens'), videos: byDir('videos') },
+    outcome,
+    assets: cited.map(({ name, sha256 }) => ({ name: `runs/${runId}/${name}`, sha256 })),
+    provenance: { actor: 'uat-record', tool: `starci uat record --flow ${recordId} -- ${command.join(' ')}`, environment, capturedAt, ...stack },
+  };
+}

package/stack/prepare.mjs

@@ -8,7 +8,7 @@ import { approvalMissing, refusal } from './errors.mjs';
 import { installAge } from './age-install.mjs';
 import { describeClash, edgeCollisions } from './edge-alias.mjs';
 import { checkLiveRestore, fixLiveRestore } from './live-restore.mjs';
-import { remoteDocker, shellQuote, withRunner } from './remote.mjs';
+import { releasePointerScript, remoteDocker, shellQuote, withRunner } from './remote.mjs';
 
 const MIN_FREE_GB = 10;
 const ADDRESS = /^[0-9a-zA-Z.:-]+$/u;
@@ -220,11 +220,18 @@ function managedCount(run, kind, stack) {
   return splitLines(remoteDocker(run, [kind, 'ls', '--filter', `label=${stack}.managed=true`, '-q']).stdout).length;
 }
 
-function checkPointers(run, report, config) {
+/** The release pointers (`current`, `previous`) of the stack's releases directory: {current, previous} (null for an absent link); an unreadable pointer is reported bad, never read as absent. */
+export function checkPointers(run, report, config) {
   const base = shellQuote(releasesBase(config));
   const pointers = {};
   for (const pointer of ['current', 'previous']) {
-    const value = run(`cd ${base} 2>/dev/null && [ -L ${pointer} ] && basename "$(readlink ${pointer})" || true`).stdout.trim();
+    const answer = run(releasePointerScript(base, pointer));
+    if (answer.status !== 0) {
+      report.bad(`release ${pointer} could not be read: ${firstLine(answer.stderr)}`);
+      pointers[pointer] = null;
+      continue;
+    }
+    const value = answer.stdout.trim();
     pointers[pointer] = value === '' ? null : value;
     if (value === '') report.ok(`release ${pointer}: none`);
     else if (RELEASE_ID.test(value)) report.ok(`release ${pointer}: ${value}`);

package/stack/release-store.mjs

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { firstLine, lines as splitLines } from './context.mjs';
 import { isReleaseId } from './digest.mjs';
 import { failure, refusal } from './errors.mjs';
+import { releaseListScript, releasePointerScript } from './remote.mjs';
 
 const BASE = /^\/[A-Za-z0-9._/-]+$/u;
 const FILES = ['stack.yaml', 'release.json'];
@@ -45,7 +46,7 @@ export function createReleaseStore(config, ssh) {
   }
 
   async function pointer(name) {
-    const out = await run(`cd "${base}" 2>/dev/null && [ -L ${name} ] && basename "$(readlink ${name})" || true`);
+    const out = await run(releasePointerScript(`"${base}"`, name));
     const id = out.trim();
     return isReleaseId(id) ? id : '';
   }
@@ -80,8 +81,7 @@ export function createReleaseStore(config, ssh) {
     },
     /** The stored releases, newest first: [{ id, current, previous }]. */
     async list() {
-      const pointerScript = (name) => `if [ -L "${base}/${name}" ]; then basename "$(readlink "${base}/${name}")"; else printf '\\n'; fi`;
-      const response = await run(`${pointerScript('current')}; ${pointerScript('previous')}; cd "${base}/releases" 2>/dev/null && ls -1t || true`);
+      const response = await run(`${releasePointerScript(`"${base}"`, 'current')}; ${releasePointerScript(`"${base}"`, 'previous')}; ${releaseListScript(`"${base}"`)}`);
       const [current, previous, ...entries] = response.split('\n');
       const now = isReleaseId(current) ? current : '';
       const before = isReleaseId(previous) ? previous : '';

package/stack/remote.mjs

@@ -30,6 +30,15 @@ export function shellQuote(value) {
   return ["'", text.replaceAll("'", String.raw`'\''`), "'"].join('');
 }
 
+/**
+ * The shell that prints the release the symlink `name` under `quotedBase` (an already-quoted directory) points at, one line; an absent link prints an
+ * empty line and succeeds. Only the absent link is expected: a `readlink` or `basename` that fails fails the script, and the caller reports it.
+ */
+export const releasePointerScript = (quotedBase, name) => `if [ -L ${quotedBase}/${name} ]; then basename "$(readlink ${quotedBase}/${name})"; else printf '\\n'; fi`;
+
+/** The shell that lists the stored releases under `quotedBase`/releases, newest first; no releases directory prints nothing and succeeds, a failing `ls` fails the script. */
+export const releaseListScript = (quotedBase) => `if [ -d ${quotedBase}/releases ]; then ls -1t ${quotedBase}/releases; fi`;
+
 /** Runs `docker <args>` on the manager through `run` (every argument quoted). */
 export const remoteDocker = (run, args) => run(['docker', ...args.map(shellQuote)].join(' '));