@starci/hfs 4.8.0 → 4.9.1

package/runtime/scripts/lib/source-package-imports.mjs

@@ -1,111 +0,0 @@
-// Source-package imports preserve published export and exact dependency contracts without a workspace install.
-import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire, registerHooks } from 'node:module';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { insidePath, pathKey, realPath } from './path-key.mjs';
-
-const packageNameOf = (specifier) => specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0];
-
-function conditionalTarget(value, conditions) {
-  if (typeof value === 'string' || value === null) return value;
-  if (Array.isArray(value)) return value.map(entry => conditionalTarget(entry, conditions)).find(entry => entry !== undefined);
-  if (!value || typeof value !== 'object') return undefined;
-  for (const [condition, target] of Object.entries(value)) {
-    if (condition === 'default' || conditions.includes(condition)) {
-      const selected = conditionalTarget(target, conditions);
-      if (selected !== undefined) return selected;
-    }
-  }
-}
-
-/** Resolve only exports that the package publishes; private paths remain unavailable in a source checkout. */
-function exportedTarget(exports, subpath, conditions) {
-  if (!exports || typeof exports !== 'object' || Array.isArray(exports)) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
-  const keys = Object.keys(exports);
-  if (keys.every(key => !key.startsWith('.'))) return subpath === '.' ? conditionalTarget(exports, conditions) : undefined;
-  if (Object.hasOwn(exports, subpath)) return conditionalTarget(exports[subpath], conditions);
-  const patterns = keys.filter(key => key.includes('*')).sort((a, b) => b.indexOf('*') - a.indexOf('*') || b.length - a.length);
-  for (const pattern of patterns) {
-    const [prefix, suffix] = pattern.split('*');
-    if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) continue;
-    const match = subpath.slice(prefix.length, suffix ? -suffix.length : undefined);
-    const target = conditionalTarget(exports[pattern], conditions);
-    return typeof target === 'string' ? target.replaceAll('*', match) : target;
-  }
-}
-
-function sourcePackages(root, packages) {
-  return Object.entries(packages).filter(([, pin]) => typeof pin?.source === 'string').map(([name, pin]) => {
-    const manifestFile = realPath(path.resolve(root, pin.source));
-    if (!insidePath(root, manifestFile, { key: pathKey })) throw new Error(`Source package ${name} is outside the source tree`);
-    return { name, pin, manifestFile, root: path.dirname(manifestFile), manifest: null };
-  }).sort((a, b) => b.root.length - a.root.length);
-}
-
-function manifestOf(source) {
-  source.manifest ??= JSON.parse(fs.readFileSync(source.manifestFile, 'utf8'));
-  if (source.manifest.name !== source.name || source.manifest.version !== source.pin.version) {
-    throw new Error(`Source package ${source.name} does not match its pinned name and version`);
-  }
-  return source.manifest;
-}
-
-/** Settle each declared bare dependency before installing a hook, using the consumer first and source install second. */
-function consumerDependencyTargets(sources, consumerRoot) {
-  const consumer = createRequire(path.join(consumerRoot, 'package.json'));
-  for (const source of sources) {
-    const manifest = manifestOf(source), local = createRequire(source.manifestFile);
-    source.consumerDependencies = new Map();
-    for (const name of Object.keys({ ...manifest.peerDependencies, ...manifest.optionalDependencies, ...manifest.dependencies })) {
-      for (const require of [consumer, local]) {
-        try { source.consumerDependencies.set(name, pathToFileURL(require.resolve(name)).href); break; }
-        catch { /* The next install may carry the dependency; a missing import still fails through the native resolver. */ }
-      }
-    }
-  }
-}
-
-function resolveSource(specifier, context, nextResolve, sources, consumerRoot) {
-  if (!context.parentURL?.startsWith('file:')) return nextResolve(specifier, context);
-  const parent = fileURLToPath(context.parentURL);
-  const owner = sources.find(source => insidePath(source.root, parent, { key: pathKey }));
-  const target = sources.find(source => source.name === packageNameOf(specifier));
-  if (!target) {
-    const dependency = owner?.consumerDependencies?.get(specifier);
-    return dependency ? { url: dependency, shortCircuit: true } : nextResolve(specifier, context);
-  }
-  if (!owner && (!consumerRoot || !insidePath(consumerRoot, parent, { key: pathKey }))) return nextResolve(specifier, context);
-  const manifest = manifestOf(target);
-  if (owner) {
-    const caller = manifestOf(owner);
-    const dependency = caller.dependencies?.[target.name] ?? caller.devDependencies?.[target.name] ?? caller.optionalDependencies?.[target.name];
-    if (owner !== target && dependency !== manifest.version) throw new Error(`${owner.name} must declare its source dependency ${target.name}@${manifest.version} exactly`);
-  }
-  const subpath = `.${specifier.slice(target.name.length)}`;
-  const published = exportedTarget(manifest.exports, subpath, context.conditions);
-  if (typeof published !== 'string' || !published.startsWith('./')) throw new Error(`${specifier} is not a published source-package export`);
-  const resolved = path.resolve(target.root, published);
-  if (!insidePath(target.root, resolved, { key: pathKey }) || published.split('/').includes('node_modules')) throw new Error(`${specifier} has an invalid source-package export target`);
-  return { url: pathToFileURL(resolved).href, shortCircuit: true };
-}
-
-/**
- * Await source imports with pinned local packages resolved through their own public exports.
- * Imports originating inside a declared source package obey exact dependency versions and public exports.
- * An explicit consumerRoot also redirects that consumer's selected source-package imports and resolves source
- * packages' declared bare imports and requires from the consumer install first. This keeps a parser and its
- * typed rules on the same dependency instances. The hook is removed on success or failure; callers await
- * every import and dependent action. Normal installed-package resolution remains in force afterward.
- * @param {{ root: string, packages: Record<string, { version: string, source?: string }>, consumerRoot?: string }} input - Canonical source pins and an optional bounded consumer source root.
- * @param {() => Promise<unknown>} action - Imports whose package contracts are being checked.
- * @returns {Promise<unknown>} The action's result, without a persistent resolver change.
- */
-export async function withSourcePackageImports({ root, packages, consumerRoot }, action) {
-  const sources = sourcePackages(realPath(root), packages);
-  const consumer = consumerRoot === undefined ? null : realPath(consumerRoot);
-  if (consumer) consumerDependencyTargets(sources, consumer);
-  const hook = registerHooks({ resolve: (specifier, context, nextResolve) => resolveSource(specifier, context, nextResolve, sources, consumer) });
-  try { return await action(); }
-  finally { hook.deregister(); }
-}

package/runtime/scripts/lib/tar-files.mjs

@@ -1,39 +0,0 @@
-// tar-files.mjs - the regular files of a gzipped tar (an npm tarball), read in memory: {path -> Buffer}. Pure: no disk, no
-// child process. Only what `npm pack` writes is understood (ustar headers, a `path` pax record and the ustar prefix
-// honoured, other pax records skipped); a link or a device entry is ignored.
-import zlib from 'node:zlib';
-
-const BLOCK = 512;
-const text = (buf, from, len) => {
-  const value = buf.toString('utf8', from, from + len);
-  const nul = value.indexOf('\0');
-  return nul < 0 ? value : value.slice(0, nul);
-};
-const octal = (buf, from, len) => Number.parseInt(text(buf, from, len).trim() || '0', 8);
-
-/** Map<string, Buffer> of the regular files in `tgz` (a Buffer). Throws on a truncated or corrupt archive. */
-export function tarFiles(tgz) {
-  const tar = zlib.gunzipSync(tgz);
-  const files = new Map();
-  let at = 0;
-  let paxPath = null;
-  while (at + BLOCK <= tar.length) {
-    const header = tar.subarray(at, at + BLOCK);
-    if (header.every((b) => b === 0)) break;
-    const size = octal(header, 124, 12);
-    const type = String.fromCodePoint(header[156] || 48);
-    const prefix = text(header, 345, 155);
-    const name = paxPath ?? (prefix ? `${prefix}/${text(header, 0, 100)}` : text(header, 0, 100));
-    const body = tar.subarray(at + BLOCK, at + BLOCK + size);
-    if (body.length < size) throw new Error(`tar entry ${name} is truncated`);
-    at += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
-    if (type === 'x') {
-      const record = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
-      paxPath = record ? record[1] : null;
-      continue;
-    }
-    paxPath = null;
-    if (type === '0') files.set(name, Buffer.from(body));
-  }
-  return files;
-}

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

@@ -1,118 +0,0 @@
-// 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/runtime/scripts/lib/worktree-record.mjs

@@ -1,14 +0,0 @@
-// worktree-record.mjs — the workflow-worktree registry row a checkpoint or a gate needs.
-import fs from 'node:fs';
-
-/**
- * `rec` must be `workflowId`'s live worktree row: present in the registry, its path on disk, a branch
- * recorded. Throws {code: 'workflow-worktree-missing'} otherwise; returns `rec`.
- */
-export function requireWorktreeRecord(rec, workflowId) {
-  const missing = (message) => { throw Object.assign(new Error(message), { code: 'workflow-worktree-missing' }); };
-  if (!rec) missing(`workflow ${workflowId} has no workflow worktree in the registry`);
-  if (!rec.path || !fs.existsSync(rec.path)) missing(`the worktree of workflow ${workflowId} (${rec.path ?? '-'}) is gone`);
-  if (!rec.branch) missing(`the registry records no branch for the worktree of workflow ${workflowId} (${rec.path})`);
-  return rec;
-}

package/runtime/scripts/machine/ask-receipts.mjs

@@ -1,113 +0,0 @@
-// ask-receipts.mjs — where the answer to an ask is kept (docs/ledger-db.md §§5–6): serve-ask answers →
-// decisions + blobs; never a file under .starciwork/kernel-evidence.
-//
-// An answer (owner form, Telegram reply, config auto-accept, autopilot) is one starci/ask-answer@1 receipt. It is put
-// in the blob store (redacted), indexed as a kernel artifact of the attempt that asked - job_artifacts name
-// asks/<dispatchId>/answer-<ms>.json, origin kernel - and recorded as one `decisions` row (decider owner | the
-// answering actor, subject the attempt, result {receiptSha256, artifactId, ...}). The receipt's file is the blob
-// file (receiptPath, read-only), and a Work record cites it as `blob:<sha256>` (or by its decision id), never by a
-// repository path.
-import fs from 'node:fs';
-import path from 'node:path';
-import { recordDecision } from '../../engine/db/ledger.mjs';
-import { sha256 } from '../../engine/digest.mjs';
-import { artifactRoot, blobPath } from '../../engine/db/blob.mjs';
-import { stageBlob, putArtifact } from './evidence-store.mjs';
-import { slash } from '../lib/path-key.mjs';
-
-const RECEIPT_PREFIX = 'asks/';
-const receiptNameOf = (dispatchId, at) => `${RECEIPT_PREFIX}${dispatchId}/answer-${at}.json`;
-const BLOB_REF = /^blob:([a-f0-9]{64})$/;
-
-/** The receipt as a staged blob (outside any transaction). */
-export const stageReceipt = (receipt) => stageBlob(Buffer.from(JSON.stringify(receipt, null, 2)), { mediaType: 'application/json' });
-
-/**
- * Inside the caller's transaction: index a staged receipt as the asking attempt's kernel artifact and record the
- * answer as a decisions row. Returns {receiptPath, receiptSha, receiptRef, artifactId, decisionId}.
- */
-function fileAskReceipt(db, { workflowId, dispatchId, receipt, blob, at = Date.now() }) {
-  const report = db.prepare('SELECT attempt_id,job_id FROM reports WHERE workflow_id=? AND dispatch_id=?').get(workflowId, dispatchId) ?? null;
-  const attempt = report ? db.prepare('SELECT attempt_id,job_id,op_id FROM op_attempts WHERE attempt_id=?').get(report.attempt_id) : null;
-  let name = receiptNameOf(dispatchId, at);
-  let n = at + 1;
-  while (db.prepare('SELECT 1 FROM job_artifacts WHERE workflow_id=? AND name=?').get(workflowId, name)) { name = receiptNameOf(dispatchId, n); n += 1; }
-  const { artifactId } = putArtifact(db, { workflowId, attemptId: attempt?.attempt_id ?? null, jobId: attempt?.job_id ?? report?.job_id ?? null, opId: attempt?.op_id ?? null,
-    role: 'other', kind: 'report', name, blob, origin: 'kernel', now: at });
-  const answeredBy = String(receipt.answeredBy ?? 'unknown');
-  const option = receipt.option ?? (receipt.optionIndex != null ? `option ${Number(receipt.optionIndex) + 1}` : 'answered');
-  const decisionId = recordDecision(db, { workflowId, decider: answeredBy === 'owner' ? 'owner' : answeredBy, subjectType: attempt ? 'attempt' : null,
-    subjectId: attempt ? String(attempt.attempt_id) : null, choice: String(option), rationale: typeof receipt.note === 'string' ? receipt.note.slice(0, 2000) : null,
-    result: { kind: 'ask-answer', dispatchId, answeredBy, optionIndex: receipt.optionIndex ?? null, receiptSha256: blob.sha, artifactId }, decidedAt: at });
-  return { receiptPath: blob.fileUri, receiptSha: blob.sha, receiptRef: `blob:${blob.sha}`, artifactId, decisionId };
-}
-
-
-/** Atomically accept one answer with its receipt, decision and terminal lifecycle event. */
-export function commitAskAnswer(ledger, { workflowId, dispatchId, receipt, at = Date.now(), payload = {}, events = [], blob: staged = null }) {
-  const blob = staged ?? stageReceipt(receipt);
-  const answerDigest = sha256(JSON.stringify({ ...receipt, at: null }));
-  return ledger.transaction(db => {
-    const latest = db.prepare(`SELECT kind,payload_json FROM events WHERE workflow_id=?
-      AND kind IN ('ask-answered','ask-superseded')
-      AND json_extract(payload_json,'$.dispatchId')=? ORDER BY seq DESC LIMIT 1`).get(workflowId, dispatchId);
-    if (latest?.kind === 'ask-answered' || latest?.kind === 'ask-superseded') {
-      const prior = JSON.parse(latest.payload_json);
-      return prior.answerDigest === answerDigest
-        ? { accepted: true, replayed: true, ...prior }
-        : { accepted: false, why: latest.kind === 'ask-answered' ? 'already-answered' : 'retired' };
-    }
-    const filed = fileAskReceipt(db, { workflowId, dispatchId, receipt, blob, at });
-    const answer = { dispatchId, receiptPath: filed.receiptPath, receiptSha: filed.receiptSha, decisionId: filed.decisionId,
-      answeredBy: receipt.answeredBy, optionIndex: receipt.optionIndex ?? null,
-      custodyWritten: receipt.custodyWritten ?? [], envWritten: receipt.envWritten ?? [], pointersWritten: receipt.pointersWritten ?? [], errors: receipt.errors ?? [],
-      ...payload, answerDigest };
-    ledger.appendEvent({ workflowId, entityType: 'report', entityId: dispatchId, kind: 'ask-answered', payload: answer });
-    for (const event of events) ledger.appendEvent({ workflowId, entityType: 'report', entityId: dispatchId, ...event,
-      payload: { ...event.payload, receiptPath: filed.receiptPath } });
-    return { accepted: true, replayed: false, ...filed };
-  });
-}
-
-/** True when `file` is a blob in the store (a receipt's file lives there). */
-const isBlobFile = (file) => {
-  const rel = path.relative(artifactRoot(), path.resolve(file));
-  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
-};
-
-/** The file a receipt reference names: `blob:<sha256>`, a blob file, or a path (resolved against `base`). */
-export function receiptFileOf(ref, { base = process.cwd() } = {}) {
-  if (typeof ref !== 'string' || !ref.trim()) return null;
-  const m = BLOB_REF.exec(ref.trim());
-  if (m) return blobPath(m[1]);
-  const abs = path.resolve(base, ref);
-  return fs.existsSync(abs) ? abs : null;
-}
-
-/** How a Work record cites a receipt file: `blob:<sha256>` for a blob, else the path relative to `repoRoot`. */
-export const receiptRefOf = (file, repoRoot) => (isBlobFile(file) ? `blob:${path.basename(file)}` : path.relative(repoRoot, file).replaceAll('\\', '/'));
-
-/**
- * The prelude of every `apply` that settles from a serve-ask answer (scripts/work/draw-review.mjs,
- * scripts/work/brand-direction.mjs): resolve the receipt ref (a `blob:<sha256>` the store kept, or a path inside
- * `repoRoot`), refuse a file outside the repository, and parse it as the `schema` receipt. Returns
- * {receipt, receiptAbs, receiptRel} - receiptRel is how the record cites it.
- */
-export function readAnswerReceipt(receiptFile, { repoRoot, base = process.cwd(), schema = 'starci/ask-answer@1' } = {}) {
-  // The receipt is the blob serve-ask stored (receiptPath, or `blob:<sha256>`); a Work record cites it as
-  // blob:<sha256>. A path inside the repository is still read (an example tree's own receipt).
-  const receiptAbs = receiptFileOf(String(receiptFile), { base }) ?? path.resolve(String(receiptFile));
-  const receiptRel = receiptRefOf(receiptAbs, repoRoot);
-  if (!isBlobFile(receiptAbs) && (receiptRel.startsWith('../') || path.isAbsolute(receiptRel))) throw new Error(`receipt ${slash(receiptFile)} is neither a stored answer (blob:<sha256>, the receiptPath serve-ask returned) nor a file inside the repository ${slash(repoRoot)}`);
-  let receipt;
-  try { receipt = JSON.parse(fs.readFileSync(receiptAbs, 'utf8')); } catch (error) { throw new Error(`receipt ${slash(receiptFile)} is unreadable: ${error.message}`); }
-  if (receipt?.schema !== schema) throw new Error(`${slash(receiptFile)} is ${receipt?.schema ?? 'not a receipt'}, not ${schema}`);
-  return { receipt, receiptAbs, receiptRel };
-}
-
-/** Every receipt answering `dispatchId` in a ledger, newest first: [{file, receipt, name}]. */
-export function receiptsAnswering(db, dispatchId) {
-  return db.prepare(`SELECT a.name,a.sha256 FROM job_artifacts a WHERE a.origin='kernel' AND a.name LIKE ? ORDER BY a.artifact_id DESC`).all(`${RECEIPT_PREFIX}${dispatchId}/answer-%`)
-    .map((r) => { const file = blobPath(r.sha256); let receipt = null; try { receipt = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { receipt = null; } return { file, receipt, name: r.name }; })
-    .filter((r) => r.file && r.receipt);
-}

package/runtime/scripts/machine/evidence-store.mjs

@@ -1,223 +0,0 @@
-// evidence-store.mjs — agent output into runtime.sqlite + the blob store (docs/ledger-db.md).
-//
-// Bytes live in the content-addressed store (engine/db/blob.mjs, <runtime root>/.runtime/artifacts/<sha[0:2]>/<sha>);
-// the ledger holds only the index rows that point at them:
-//   blobs                         one row per sha this ledger references (media type, redaction, file uri)
-//   job_artifacts                 every file output, keyed (attempt_id, name) — or (workflow_id, name) for the Kernel's
-//                                 own outputs — immutable: a second put with other bytes is refused (H10)
-//   check_runs                    every op / settler / parity / integrate check: the RAW exit the runner saw apart from
-//                                 the exit the op DECLARED (H8); 'unavailable' is its own status and never red (H7)
-//   attempt_transcript_snapshots  the redacted scrollback of a live op terminal, every 60 s
-//   op_attempts.transcript_sha    the full redacted scrollback when the attempt ends
-// Text bytes pass scripts/lib/redact.mjs before every put (blobs.redaction='v1'); media is stored as is ('binary').
-// The rows go through the runtime writer (engine/db/ledger.mjs recordBlob, recordArtifact, recordCheckRun,
-// recordTranscriptSnapshot, setAttemptTranscript); this module is the evidence policy on top of it: redaction,
-// naming, kinds and roles, the H7/H8 status rules. Every write runs inside the caller's ledger.transaction; the blob
-// put happens BEFORE the transaction (stageBlob), so a rolled-back transaction leaves only an unreferenced blob for GC.
-import fs from 'node:fs';
-import path from 'node:path';
-import { putBlob, blobPath } from '../../engine/db/blob.mjs';
-import { redactBytes } from '../lib/redact.mjs';
-import { recordBlob, recordArtifact, recordCheckRun as writeCheckRun, recordTranscriptSnapshot, attachToReport, setAttemptTranscript,
-  JOB_ARTIFACT_KINDS, JOB_ARTIFACT_SUBKINDS, JOB_ARTIFACT_ROLES } from '../../engine/db/ledger.mjs';
-import { newSpanId } from '../../engine/db/machine.mjs';
-import { refuse } from '../../engine/refuse.mjs';
-
-const ARTIFACT_ROLES = JOB_ARTIFACT_ROLES;
-export const ARTIFACT_KINDS = JOB_ARTIFACT_KINDS;
-export const ARTIFACT_SUBKINDS = JOB_ARTIFACT_SUBKINDS;
-const ARTIFACT_ORIGINS = Object.freeze(['op', 'settler', 'checker', 'kernel']);
-const CHECK_PHASES = Object.freeze(['before', 'after', 'verify', 'parity', 'integrate']);
-const CHECK_RUNNERS = Object.freeze(['op', 'settler', 'kernel', 'parity', 'integrate']);
-export const CHECK_STATUSES = Object.freeze(['pass', 'fail', 'unavailable', 'error', 'skipped']);
-/** A check whose status counts as red. 'unavailable' (the checker could not run: infra) and 'skipped' never do (H7). */
-const RED_CHECK_STATUSES = Object.freeze(['fail', 'error']);
-export const TRANSCRIPT_SNAPSHOT_MS = 60_000;
-
-
-const slash = (p) => String(p).replaceAll('\\', '/');
-
-const IMAGE = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml' };
-const VIDEO = { '.webm': 'video/webm', '.mp4': 'video/mp4', '.mov': 'video/quicktime' };
-const OTHER = { '.json': 'application/json', '.md': 'text/markdown', '.yaml': 'text/yaml', '.yml': 'text/yaml', '.txt': 'text/plain',
-  '.log': 'text/plain', '.jsonl': 'application/x-ndjson', '.out': 'text/plain', '.patch': 'text/x-diff', '.diff': 'text/x-diff', '.html': 'text/html',
-  '.htm': 'text/html', '.mhtml': 'multipart/related', '.zip': 'application/zip', '.trace': 'application/octet-stream', '.csv': 'text/csv', '.xml': 'application/xml' };
-/** The media type of a file, from its extension. */
-export const mediaTypeOf = (file) => { const ext = path.extname(String(file)).toLowerCase(); return IMAGE[ext] ?? VIDEO[ext] ?? OTHER[ext] ?? 'application/octet-stream'; };
-
-/** The job_artifacts.kind of a file, from its name. */
-export function kindOf(file) {
-  const base = path.basename(String(file)).toLowerCase(), ext = path.extname(base);
-  if (ext === '.patch') return 'patch';
-  if (ext === '.diff') return 'diff';
-  if (IMAGE[ext]) return 'image';
-  if (VIDEO[ext]) return 'video';
-  if (ext === '.trace' || (ext === '.zip' && base.includes('trace'))) return 'trace';
-  if (/^(report|result)([.-].*)?\.(json|md|ya?ml)$/.test(base)) return 'report';
-  if (['.log', '.txt', '.out', '.jsonl'].includes(ext)) return 'log';
-  return 'file';
-}
-
-/** The artifact role of an attached file, from its name. */
-export function roleOf(file) {
-  const kind = kindOf(file), ext = path.extname(String(file)).toLowerCase();
-  if (kind === 'image') return 'screenshot';
-  if (kind === 'video') return 'video';
-  if (kind === 'trace') return 'trace';
-  if (kind === 'patch') return 'patch';
-  if (kind === 'diff') return 'diff';
-  if (kind === 'log') return 'log';
-  if (['.html', '.htm', '.mhtml'].includes(ext)) return 'dom';
-  return 'report-attachment';
-}
-
-// --------------------------------------------------------------------------------------------- blobs
-/**
- * Put bytes (a Buffer, a string, or a file path) in the blob store, redacted first when they are text. Runs OUTSIDE
- * the ledger transaction. Returns {sha, bytes, mediaType, redaction, fileUri} for registerBlob / putArtifact.
- * @param {string|Uint8Array|ArrayBuffer|ArrayLike<number>} source
- * @param {{mediaType?: string|null, file?: boolean|null, repoRoots?: string[]}} [options]
- */
-export function stageBlob(source, { mediaType = null, file = null, repoRoots = [] } = {}) {
-  let raw;
-  if (Buffer.isBuffer(source)) raw = source;
-  else if (typeof source === 'string' && file === false) raw = Buffer.from(source, 'utf8');
-  else if (typeof source === 'string') raw = fs.readFileSync(source);
-  else raw = Buffer.from(source);
-  const type = mediaType ?? (typeof source === 'string' && file !== false ? mediaTypeOf(source) : 'application/octet-stream');
-  const { bytes, redaction } = redactBytes(raw, type, { repoRoots });
-  const put = putBlob(bytes, { mediaType: type });
-  return { sha: put.sha, bytes: put.size, mediaType: type, redaction, fileUri: slash(blobPath(put.sha)) };
-}
-
-/** Text as a staged blob (redacted), or null for empty text. */
-export const stageText = (text, { mediaType = 'text/plain', repoRoots = [] } = {}) =>
-  (typeof text === 'string' && text.length ? stageBlob(text, { mediaType, file: false, repoRoots }) : null);
-
-/** The blobs row of one staged blob; a sha already known keeps its first row. Returns the sha. */
-export function registerBlob(db, staged, { now = Date.now() } = {}) {
-  if (!staged?.sha) return null;
-  recordBlob(db, { sha256: staged.sha, bytes: staged.bytes, mediaType: staged.mediaType, fileUri: staged.fileUri, redaction: staged.redaction ?? null, createdAt: now });
-  return staged.sha;
-}
-
-// ----------------------------------------------------------------------------------------- artifacts
-/**
- * One job_artifacts row for a staged blob. `name` is the logical name, unique per attempt (per workflow for a
- * Kernel artifact, attemptId null). Filing the same name with the same bytes again returns the existing row;
- * other bytes under a filed name are refused `artifact-immutable` (H10). Returns {artifactId, created}.
- */
-export function putArtifact(db, { workflowId, attemptId = null, jobId = null, opId = null, cut = null, role, kind = null, subkind = null,
-  name, blob, label = null, scopeRef = null, round = null, runId = null, origin, baseSha = null, headSha = null, integratedSha = null, now = Date.now() }) {
-  if (!ARTIFACT_ROLES.includes(role)) throw refuse(`artifact role must be ${ARTIFACT_ROLES.join('|')}, got '${role}'`, 'artifact-role-unknown');
-  if (!ARTIFACT_ORIGINS.includes(origin)) throw refuse(`artifact origin must be ${ARTIFACT_ORIGINS.join('|')}, got '${origin}'`, 'artifact-origin-unknown');
-  const logical = slash(name ?? '').replace(/^\/+/, '');
-  if (!logical || logical.split('/').includes('..')) throw refuse(`unsafe artifact name: ${name}`, 'artifact-name-invalid');
-  const k = kind ?? kindOf(logical);
-  if (!ARTIFACT_KINDS.includes(k)) throw refuse(`artifact kind must be ${ARTIFACT_KINDS.join('|')}, got '${k}'`, 'artifact-kind-unknown');
-  if (subkind != null && !ARTIFACT_SUBKINDS.includes(subkind)) throw refuse(`artifact subkind must be ${ARTIFACT_SUBKINDS.join('|')}, got '${subkind}'`, 'artifact-subkind-unknown');
-  registerBlob(db, blob, { now });
-  const before = attemptId != null ? db.prepare('SELECT artifact_id FROM job_artifacts WHERE attempt_id=? AND name=?').get(attemptId, logical)
-    : db.prepare('SELECT artifact_id FROM job_artifacts WHERE workflow_id=? AND attempt_id IS NULL AND name=?').get(workflowId, logical);
-  let row;
-  try {
-    row = recordArtifact(db, { workflowId, attemptId, name: logical, sha256: blob.sha, role, kind: k, origin, subkind, label, scopeRef, round, runId, cut,
-      baseSha, headSha, integratedSha, createdAt: now, ...(attemptId == null ? { jobId, opId } : {}) });
-  } catch (error) {
-    if (error?.code === 'STARCI_ARTIFACT_IMMUTABLE') throw refuse(`artifact '${logical}' of attempt ${attemptId ?? '(kernel)'} is already filed with other bytes; artifacts are immutable, file a new name`, 'artifact-immutable', { name: logical });
-    throw error;
-  }
-  return { artifactId: row.artifact_id, created: !before };
-}
-
-/** Link report → artifact (report_attachments). */
-export const linkReportAttachment = (db, { reportId, artifactId }) => attachToReport(db, { reportId, artifactId });
-
-// ------------------------------------------------------------------------------------------- attempts
-/** The op_attempts row of a dispatch (workflow + dispatch id), else of the job's latest dispatch, else null. */
-export function attemptOf(db, { workflowId = null, dispatchId = null, jobId = null, attemptId = null } = {}) {
-  if (attemptId != null) return db.prepare('SELECT * FROM op_attempts WHERE attempt_id=?').get(attemptId) ?? null;
-  if (workflowId && dispatchId) { const row = db.prepare('SELECT * FROM op_attempts WHERE workflow_id=? AND dispatch_id=?').get(workflowId, dispatchId); if (row) return row; }
-  if (jobId) return db.prepare('SELECT * FROM op_attempts WHERE job_id=? ORDER BY dispatch_seq DESC LIMIT 1').get(jobId) ?? null;
-  return null;
-}
-
-// ------------------------------------------------------------------------------------------- checks
-/**
- * The status of one check run. `unavailable` (the checker could not run: missing tool, host down, spawn error)
- * is infra, never red (H7); a runner-observed non-zero exit is never 'pass' (H8).
- * @param {{exitCode?: number|null, declaredExitCode?: number|null, unavailable?: boolean, error?: boolean,
- *   skipped?: boolean, status?: string|null}} [options]
- */
-function checkStatusOf({ exitCode = null, declaredExitCode = null, unavailable = false, error = false, skipped = false, status = null } = {}) {
-  if (status && !CHECK_STATUSES.includes(status)) throw refuse(`check status must be ${CHECK_STATUSES.join('|')}, got '${status}'`, 'check-status-unknown');
-  if (skipped || status === 'skipped') return 'skipped';
-  if (unavailable || status === 'unavailable') return 'unavailable';
-  if (error || status === 'error') return 'error';
-  // The raw exit wins over the declared one; an explicit 'fail' (a green exit with red findings) stays fail.
-  let exit = null;
-  if (Number.isInteger(exitCode)) exit = exitCode;
-  else if (Number.isInteger(declaredExitCode)) exit = declaredExitCode;
-  if (exit == null) return status === 'pass' || status === 'fail' ? status : 'error';
-  return exit === 0 && status !== 'fail' ? 'pass' : 'fail';
-}
-
-const integerOrNull = (value) => (Number.isInteger(value) ? value : null);
-
-// The raw exit the runtime observed and the exit an op declared: an op's own exit is only its claim.
-function exitCodesOf(runner, exitCode, declaredExitCode) {
-  if (runner !== 'op') return { raw: integerOrNull(exitCode), declared: integerOrNull(declaredExitCode) };
-  return { raw: null, declared: Number.isInteger(exitCode) ? exitCode : integerOrNull(declaredExitCode) };
-}
-
-/**
- * One check_runs row (engine/db/ledger.mjs recordCheckRun). `runner` 'op' is always authority 'declared' (the op's own claim: exitCode is stored as
- * declared_exit_code, exit_code stays NULL — the runtime did not observe it); the runtime's own runners store the
- * raw exit they observed in exit_code. stdout/stderr/output are staged blobs (stageBlob/stageText) or null.
- * run_seq numbers re-runs of the same (attempt, runner, phase, name). Returns {checkId, runSeq, status, red}.
- */
-export function recordCheck(db, { attemptId, name, phase, runner, authority = null, command = null, cwd = null,
-  inputDigest = null, exitCode = null, declaredExitCode = null, attribution = null, status = null, unavailable = false, error = false, skipped = false,
-  startedAt = null, finishedAt = null, wallMs = null, stdout = null, stderr = null, output = null, summary = null, note = null,
-  spanId = newSpanId(), now = Date.now() }) {
-  if (!CHECK_RUNNERS.includes(runner)) throw refuse(`check runner must be ${CHECK_RUNNERS.join('|')}, got '${runner}'`, 'check-runner-unknown');
-  if (!CHECK_PHASES.includes(phase)) throw refuse(`check phase must be ${CHECK_PHASES.join('|')}, got '${phase}'`, 'check-phase-unknown');
-  if (attemptId == null) throw refuse(`check '${name}' has no attempt`, 'check-attempt-missing');
-  const auth = runner === 'op' ? 'declared' : authority ?? 'runtime';
-  const { raw, declared } = exitCodesOf(runner, exitCode, declaredExitCode);
-  const st = checkStatusOf({ exitCode: raw, declaredExitCode: declared, unavailable, error, skipped, status });
-  for (const b of [stdout, stderr, output]) if (b) registerBlob(db, b, { now });
-  const wall = wallMs ?? (Number.isFinite(startedAt) && Number.isFinite(finishedAt) ? finishedAt - startedAt : null);
-  const row = writeCheckRun(db, { attemptId, name, phase, runner, authority: auth, status: st, spanId, createdAt: now, command, cwd, inputDigest,
-    exitCode: raw, declaredExitCode: declared, attributionJson: attribution == null ? null : JSON.stringify(attribution), startedAt, finishedAt, wallMs: wall,
-    stdoutSha: stdout?.sha ?? null, stderrSha: stderr?.sha ?? null, outputSha: output?.sha ?? null,
-    summaryJson: summary == null ? null : JSON.stringify(summary), note });
-  return { checkId: row.check_id, runSeq: row.run_seq, status: st, red: RED_CHECK_STATUSES.includes(st) };
-}
-
-/** The latest run of every check of an attempt (optionally one runner): [row] ordered by check_id. */
-export const latestCheckRuns = (db, attemptId, { runner = null } = {}) => db.prepare(`SELECT c.* FROM check_runs c
-  WHERE c.attempt_id=? ${runner ? 'AND c.runner=?' : ''} AND c.run_seq=(SELECT max(run_seq) FROM check_runs x
-    WHERE x.attempt_id=c.attempt_id AND x.runner=c.runner AND x.phase=c.phase AND x.name=c.name) ORDER BY c.check_id`)
-  .all(attemptId, ...(runner ? [runner] : []));
-
-// ---------------------------------------------------------------------------------------- transcripts
-const linesOf = (text) => (text ? text.split('\n').length : 0);
-
-/** A periodic scrollback snapshot of a live attempt; an unchanged scrollback adds no row. Returns {written, sha}. */
-export function recordAttemptSnapshot(db, { attemptId, text, blob = null, at = Date.now() }) {
-  const staged = blob ?? stageText(text);
-  if (!staged) return { written: false, sha: null };
-  registerBlob(db, staged, { now: at });
-  const written = recordTranscriptSnapshot(db, { attemptId, sha256: staged.sha, lines: linesOf(text ?? ''), bytes: staged.bytes, at });
-  return { written, sha: staged.sha };
-}
-
-/** The attempt's full redacted scrollback at its end: op_attempts.transcript_sha. Returns the sha or null. */
-export function recordFinalTranscript(db, { attemptId, text = null, blob = null, at = Date.now() }) {
-  const staged = blob ?? stageText(text);
-  if (!staged || attemptId == null) return null;
-  registerBlob(db, staged, { now: at });
-  setAttemptTranscript(db, { attemptId, transcriptSha: staged.sha, at });
-  return staged.sha;
-}