@starci/hfs 4.7.32 → 4.7.34

package/runtime/engine/db/blob.mjs

@@ -0,0 +1,380 @@
+// blob.mjs — the content-addressed blob store (operational evidence and agent output) beside the two SQLite stores:
+// putBlob/getBlob/statBlob/putJson write and read it; blob bytes are immutable and never removed here.
+//
+// Reading agent output back out of the blob store. A Work record and the
+// draw subsystem cite agent output by {artifact?, sha256}; this is the one place that turns such a citation back into
+// bytes, a readable file with an extension, or a directory.
+//   resolveBlob(ref, {db})   ref = {artifact?, sha256?} | 'blob:<sha>' | '<sha>' → {sha256, file} | null (an artifact id
+//                            alone resolves through the ledger's job_artifacts)
+//   readBlobRef(ref)         the verified bytes
+//   blobAsFile(ref, {ext})   a read-only copy with an extension beside the store (<artifact root>-views; tools that key on the
+//                            extension: an image decoder, a browser), cached by sha
+//   putBundle(dir)           every file under `dir` put as a blob + a starci/blob-bundle@1 manifest {files: {rel: sha}}
+//                            put as a blob; returns the manifest sha (a draw loop: loop.json and every round)
+//   bundleDir(sha)           the bundle materialized as a directory under <artifact root>-views (cached by sha), or null
+// Each materialized view is verified against its cited digest before reuse.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { starciLocalRoot, runtimeStateDir } from '../runtime-root.mjs';
+import { isSpecRun } from '../../scripts/lib/env.mjs';
+import { canonicalPath, insidePath, pathKey } from '../../scripts/lib/path-key.mjs';
+import { byCodeUnit } from '../by-code-unit.mjs';
+import { tempRoot } from '../temp-root.mjs';
+
+export const ARTIFACT_ROOT_ENV = 'STARCI_ARTIFACT_ROOT';
+/**
+ * The blob store: ARTIFACT_ROOT_ENV, else <starciLocalRoot>/artifacts (<runtime root>/.runtime/artifacts on a host). Inside a node --test
+ * process tree a default outside the OS temp directory is replaced by a temp one, so a bare spec never writes into the checkout.
+ */
+export const artifactRoot = (env = process.env) => {
+  if (env[ARTIFACT_ROOT_ENV]) return path.resolve(env[ARTIFACT_ROOT_ENV]);
+  const root = path.resolve(path.join(starciLocalRoot(env), 'artifacts'));
+  return isSpecRun(env) && !insidePath(tempRoot({ env }), root, { key: pathKey }) ? path.join(tempRoot({ env }), 'starci-test-artifacts') : root;
+};
+const SHA = /^[a-f0-9]{64}$/;
+const assertSha = sha => {
+  if (typeof sha !== 'string' || !SHA.test(sha)) throw new TypeError('blob sha must be a lowercase sha256 hex digest');
+  return sha;
+};
+// An explicit root scopes READs only; writers continue to use the default external root.
+const location = (sha, root = null, suffix = '') => {
+  if (root !== null && (typeof root !== 'string' || !root || !path.isAbsolute(root)))
+    throw new TypeError('blob read root must be an absolute path');
+  const file = path.join(root === null ? artifactRoot() : path.resolve(root), assertSha(sha).slice(0, 2), `${sha}${suffix}`);
+  if (root !== null) {
+    regularParents(file, { strict: true, base: root });
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (stat && (!stat.isFile() || stat.isSymbolicLink()
+      || fs.realpathSync.native(file) !== path.join(fs.realpathSync.native(path.dirname(file)), path.basename(file))
+      || !fs.readdirSync(path.dirname(file)).includes(path.basename(file))))
+      throw new Error(`blob read path is not a contained regular file: ${file}`);
+  }
+  return file;
+};
+const metadataPath = (sha, root = null) => location(sha, root, '.json');
+const digest = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+
+// The last matching rule of a file wins, a negation un-ignores, and .gitignore outranks .git/info/exclude (git's own precedence).
+const ignoreVerdict = (file, forms) => {
+  let verdict = null;
+  try {
+    for (const raw of fs.readFileSync(file, 'utf8').split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const negated = line.startsWith('!');
+      if (forms.has(negated ? line.slice(1) : line)) verdict = !negated;
+    }
+  } catch { /* absent or unreadable: no rule */ }
+  return verdict;
+};
+// The state dir relative to the checkout that actually holds it (<top>/.runtime on the source, <app>/.claude/.runtime in an app repo).
+const stateIgnored = (top, stateDir) => {
+  const rel = path.relative(top, stateDir).split(path.sep).join('/');
+  if (!rel || rel.startsWith('..')) return false;
+  const forms = new Set([rel, `${rel}/`, `/${rel}`, `/${rel}/`]);
+  return (ignoreVerdict(path.join(top, '.gitignore'), forms) ?? ignoreVerdict(path.join(top, '.git', 'info', 'exclude'), forms)) === true;
+};
+// A writer root is outside every checkout (including worktrees whose .git is a file), or it is under this runtime's own
+// .runtime directory AND that directory is listed in the checkout's .gitignore (or .git/info/exclude), so a blob store can
+// never be committed. Fail closed: a root under any other path in a checkout, or a .runtime nobody ignores, refuses.
+function ensureExternalRoot(root, stateDirectory = runtimeStateDir()) {
+  const real = canonicalPath(root), stateDir = canonicalPath(stateDirectory); // canonical on both sides: a link into a checkout cannot hide it
+  let cursor = real;
+  while (true) {
+    if (fs.existsSync(path.join(cursor, '.git'))) {
+      if (!insidePath(stateDir, real, { key: pathKey, includeSelf: true })) throw new Error(`artifact root is inside a git checkout: ${root}`);
+      if (!stateIgnored(cursor, stateDir)) throw new Error(`artifact root is inside a git checkout and not git-ignored: ${root}`);
+      return;
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return;
+    cursor = parent;
+  }
+}
+
+function sourceBytes(bufferOrPath) {
+  if (Buffer.isBuffer(bufferOrPath)) return bufferOrPath;
+  if (bufferOrPath instanceof Uint8Array) return Buffer.from(bufferOrPath);
+  if (typeof bufferOrPath === 'string') return fs.readFileSync(bufferOrPath);
+  throw new TypeError('putBlob expects a Buffer, Uint8Array, or file path');
+}
+
+function publishOnce(destination, bytes) {
+  const dir = path.dirname(destination);
+  fs.mkdirSync(dir, { recursive: true });
+  const temp = path.join(dir, `.${path.basename(destination)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+  let owned=false;
+  try {
+    const fd=fs.openSync(temp,'wx');
+    owned=true;
+    try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}
+    try { fs.linkSync(temp, destination); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  } finally { if(owned)fs.rmSync(temp,{force:true}); }
+}
+
+/** Store original bytes under their sha256. A concurrent or repeated put never replaces published bytes. */
+export function putBlob(bufferOrPath, { mediaType = 'application/octet-stream' } = {}) {
+  if (typeof mediaType !== 'string' || !mediaType.trim()) throw new TypeError('mediaType must be a nonempty string');
+  const root = artifactRoot();
+  ensureExternalRoot(root);
+  const bytes = sourceBytes(bufferOrPath);
+  const sha = digest(bytes);
+  const destination = location(sha);
+  const metadata = { size: bytes.length, mediaType, createdAt: new Date().toISOString() };
+  // Metadata is published first so a visible blob always has a sidecar. A crash can leave an orphan sidecar;
+  // the next put completes it. The first published media type and creation time win.
+  publishOnce(metadataPath(sha), Buffer.from(JSON.stringify(metadata)));
+  publishOnce(destination, bytes);
+  const stored = fs.statSync(destination);
+  if (stored.size !== bytes.length) throw new Error(`blob size mismatch: ${sha}`);
+  // Reuse must verify bytes, including a corrupt same-size destination.
+  getBlob(sha);
+  const info = statBlob(sha);
+  // Flush reused files too. Directory/link persistence remains platform-specific;
+  // this local profile does not promise power-loss recovery of acknowledged refs.
+  for(const file of [destination,metadataPath(sha)]){const fd=fs.openSync(file,'r+');try{fs.fsyncSync(fd);}finally{fs.closeSync(fd);}}
+  return { sha, size: info.size, mediaType: info.mediaType };
+}
+
+export function blobPath(sha, { root = null } = {}) {
+  const file = location(sha, root);
+  return fs.existsSync(file) && fs.statSync(file).isFile() ? file : null;
+}
+
+export function getBlob(sha, { root = null, verifyBundle = false } = {}) {
+  const file = blobPath(sha, { root });
+  if (!file) throw Object.assign(new Error(`blob not found: ${sha}`), { code: 'ENOENT' });
+  const bytes = fs.readFileSync(file);
+  if (digest(bytes) !== sha) throw new Error(`blob hash mismatch: ${sha}`);
+  if (root !== null) statBlob(sha, { root });
+  if (verifyBundle) {
+    let manifest;
+    try { manifest = JSON.parse(bytes.toString('utf8')); } catch { /* ordinary blobs need not be JSON */ }
+    if (typeof manifest?.schema === 'string' && manifest.schema.startsWith('starci/blob-bundle@')
+      && !bundleDir(sha, { root }))
+      throw Object.assign(new Error(`blob bundle cannot be verified: ${sha}`), { code: 'EINVALBUNDLE' });
+  }
+  return bytes;
+}
+
+export function statBlob(sha, { root = null } = {}) {
+  const file = blobPath(sha, { root });
+  if (!file) return null;
+  const { size } = fs.statSync(file);
+  const metadata = JSON.parse(fs.readFileSync(metadataPath(sha, root), 'utf8'));
+  if (metadata.size !== size) throw new Error(`blob sidecar size mismatch: ${sha}`);
+  if(typeof metadata.mediaType!=='string'||!metadata.mediaType.trim()||!Number.isFinite(Date.parse(metadata.createdAt)))throw new Error(`blob sidecar metadata invalid: ${sha}`);
+  return { sha, size, mediaType: metadata.mediaType, createdAt: metadata.createdAt };
+}
+
+function canonical(value) {
+  if (value && typeof value === 'object') {
+    if (typeof value.toJSON === 'function') return canonical(value.toJSON());
+    if (Array.isArray(value)) return value.map(item => item === undefined ? null : canonical(item));
+    return Object.fromEntries(Object.keys(value).sort(byCodeUnit).filter(key => value[key] !== undefined).map(key => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+/* ------------------------------------------------------------ citations, views and bundles */
+
+const BUNDLE_SCHEMA = 'starci/blob-bundle@1';
+// Read-only views (files with an extension, materialized bundles) live beside the store, e.g. <runtime root>/.runtime/artifacts-views.
+const viewRoot = (root = null) => `${root === null ? artifactRoot() : path.resolve(root)}-views`;
+const slash = (p) => String(p).replaceAll('\\', '/');
+
+/** The sha256 a citation names: {sha256}, 'blob:<sha>' or a bare sha; an {artifact} alone needs `db`. */
+function shaOfRef(ref, { db = null } = {}) {
+  if (typeof ref === 'string') { const s = ref.trim().replace(/^blob:/, ''); return SHA.test(s) ? s : null; }
+  if (!ref || typeof ref !== 'object') return null;
+  if (typeof ref.sha256 === 'string' && SHA.test(ref.sha256)) return ref.sha256;
+  if (ref.artifact != null && db) return db.prepare('SELECT sha256 FROM job_artifacts WHERE artifact_id=?').get(Number(ref.artifact))?.sha256 ?? null;
+  return null;
+}
+
+/** {sha256, file} of a citation whose bytes are in the local store, else null. */
+export function resolveBlob(ref, { db = null, root = null } = {}) {
+  const sha = shaOfRef(ref, { db });
+  const file = sha ? blobPath(sha, { root }) : null;
+  return file ? { sha256: sha, file } : null;
+}
+
+/** A read-only copy of the blob with `ext` (e.g. '.png'), cached beside the store; null when missing. */
+export function blobAsFile(ref, { ext = '', db = null, root = null } = {}) {
+  const hit = resolveBlob(ref, { db, root });
+  if (!hit) return null;
+  if (typeof ext !== 'string' || (ext !== '' && !/^\.[a-z0-9]{1,16}$/i.test(ext))) throw new TypeError('blob view extension must be a simple suffix');
+  const bytes = getBlob(hit.sha256, { root });
+  const file = path.join(viewRoot(root), 'files', `${hit.sha256}${ext}`);
+  regularParents(file, { strict: root !== null, base: path.dirname(viewRoot(root)) });
+  publishOnce(file, bytes);
+  if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink() || digest(fs.readFileSync(file)) !== hit.sha256)
+    throw new Error(`blob view hash mismatch: ${hit.sha256}`);
+  if (root !== null && (fs.realpathSync.native(file) !== path.join(fs.realpathSync.native(path.dirname(file)), path.basename(file))
+    || !fs.readdirSync(path.dirname(file)).includes(path.basename(file))))
+    throw new Error(`blob view path is linked or has a different spelling: ${file}`);
+  return file;
+}
+
+// The trusted base (the read root, or the directory holding the store and its views) is canonicalised once; only directories BELOW it must be regular and exactly spelled.
+function regularParents(file, { strict = false, base }) {
+  const top = path.resolve(base), levels = []; let real = null;
+  for (let at = path.dirname(path.resolve(file)); at !== top; at = path.dirname(at)) {
+    if (!insidePath(top, at)) throw new Error(`blob path is outside its trusted root: ${file}`); else levels.unshift(at);
+  }
+  for (const cursor of levels) {
+    const stat = fs.lstatSync(cursor, { throwIfNoEntry: false }), name = path.basename(cursor);
+    if (!stat) return;
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`blob view parent is not a regular directory: ${cursor}`);
+    if (!strict) continue;
+    real = path.join(real ?? fs.realpathSync.native(top), name);
+    if (fs.realpathSync.native(cursor) !== real || !fs.readdirSync(path.dirname(cursor)).includes(name))
+      throw new Error(`blob read parent is linked or has a different spelling: ${cursor}`);
+  }
+}
+
+function bundleEntries(manifest) {
+  if (!manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) throw new TypeError('blob bundle files must be a mapping');
+  const entries = Object.entries(manifest.files);
+  const names = new Set();
+  for (const [rel, sha] of entries) {
+    const parts = rel.split('/');
+    if (!rel || rel.includes('\\') || path.posix.isAbsolute(rel) || path.win32.isAbsolute(rel)
+      || parts.some(part => !part || part === '.' || part === '..' || /[<>:"|?*\x00-\x1f]/.test(part) || /[. ]$/.test(part)
+        || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)) || parts[0] === '.complete')
+      throw new TypeError(`unsafe blob bundle path: ${rel}`);
+    assertSha(sha);
+    const key = rel.toLowerCase();
+    if (names.has(key)) throw new TypeError(`blob bundle path collision: ${rel}`);
+    names.add(key);
+  }
+  for (const name of names) {
+    const parts = name.split('/');
+    for (let index = 1; index < parts.length; index += 1) if (names.has(parts.slice(0, index).join('/')))
+      throw new TypeError(`blob bundle file is also a directory: ${name}`);
+  }
+  return entries;
+}
+
+function verifiedBundle(dir, entries, opts) {
+  const { strict } = opts; regularParents(path.join(dir, '.complete'), opts);
+  if (!fs.existsSync(dir)) return false;
+  const expected = new Map(entries);
+  const seen = new Set();
+  const walk = current => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const file = path.join(current, entry.name);
+      const rel = slash(path.relative(dir, file));
+      if (entry.isSymbolicLink()) throw new Error(`blob bundle view contains a link: ${rel}`);
+      if (strict && fs.realpathSync.native(file) !== path.join(fs.realpathSync.native(current), entry.name))
+        throw new Error(`blob bundle view contains a redirected path: ${rel}`);
+      if (entry.isDirectory()) { walk(file); continue; }
+      if (!entry.isFile()) throw new Error(`blob bundle view contains a special file: ${rel}`);
+      if (rel === '.complete') continue;
+      if (!expected.has(rel) || digest(fs.readFileSync(file)) !== expected.get(rel)) throw new Error(`blob bundle view hash mismatch: ${rel}`);
+      seen.add(rel);
+    }
+  };
+  walk(dir);
+  return seen.size === entries.length && fs.existsSync(path.join(dir, '.complete'));
+}
+
+const filesUnder = (dir, out = []) => {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) filesUnder(full, out); else if (e.isFile()) out.push(full);
+  }
+  return out;
+};
+
+/** Put every file under `dir` and its manifest in the blob store; returns the manifest sha. */
+export function putBundle(dir, { mediaTypeOf = () => 'application/octet-stream' } = {}) {
+  const files = {};
+  for (const abs of filesUnder(dir)) files[slash(path.relative(dir, abs))] = putBlob(abs, { mediaType: mediaTypeOf(abs) }).sha;
+  return putBlob(Buffer.from(JSON.stringify({ schema: BUNDLE_SCHEMA, files }, null, 2)), { mediaType: 'application/json' }).sha;
+}
+
+/** The manifest of a bundle: {schema, files: {rel: sha}} or null. */
+function bundleManifest(ref, { db = null, root = null } = {}) {
+  const hit = resolveBlob(ref, { db, root });
+  if (!hit) return null;
+  const bytes = getBlob(hit.sha256, { root });
+  let doc;
+  try { doc = JSON.parse(bytes.toString('utf8')); } catch { return null; }
+  return doc?.schema === BUNDLE_SCHEMA ? doc : null;
+}
+
+/** Direct blob references of a bundle, validated by the storage format owner; ordinary blobs have none. Reads never materialize a view. */
+export function blobReferences(ref, { root = null } = {}) {
+  const manifest = bundleManifest(ref, { root });
+  return manifest ? bundleEntries(manifest).map(([, sha]) => sha) : [];
+}
+
+/**
+ * Remove a staging directory this call made: the files it wrote, then the directories above them, deepest first. It never walks a tree: the link-safe
+ * recursive delete is scripts/api/fs/safe-remove.mjs, which the db tier cannot import, and a staging tree holds only what this call created.
+ */
+function dropStaging(staging, written) {
+  const dirs = new Set([staging]);
+  for (const file of written) {
+    if (fs.existsSync(file)) fs.rmSync(file);
+    for (let dir = path.dirname(file); dir !== staging && !dirs.has(dir); dir = path.dirname(dir)) dirs.add(dir);
+  }
+  for (const dir of [...dirs].sort((a, b) => b.length - a.length)) if (fs.existsSync(dir)) fs.rmdirSync(dir);
+}
+
+/** Write one bundle member set into `staging` (unsafe rel paths refuse); `written` collects every path for dropStaging. */
+function writeBundleStaging(staging, members, sha, written) {
+  for (const [rel, bytes] of members) {
+    const to = path.resolve(staging, ...rel.split('/'));
+    const relative = path.relative(staging, to);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw new Error(`unsafe blob bundle target: ${rel}`);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    written.push(to);
+    fs.writeFileSync(to, bytes, { flag: 'wx' });
+  }
+  written.push(path.join(staging, '.complete'));
+  fs.writeFileSync(written.at(-1), sha, { flag: 'wx' });
+}
+
+/** The bundle as a directory beside the store (cached by sha), or null when it or one file is missing. */
+export function bundleDir(ref, { db = null, root = null } = {}) {
+  const sha = shaOfRef(ref, { db });
+  const manifest = sha ? bundleManifest(sha, { root }) : null;
+  if (!manifest) return null;
+  const entries = bundleEntries(manifest);
+  const members = [];
+  for (const [rel, fileSha] of entries) {
+    try { members.push([rel, getBlob(fileSha, { root })]); }
+    catch (error) { if (error?.code === 'ENOENT') { return null; } throw error; }
+  }
+  const dir = path.join(viewRoot(root), 'bundles', sha), opts = { strict: root !== null, base: path.dirname(viewRoot(root)) };
+  if (verifiedBundle(dir, entries, opts)) return dir;
+  if (fs.existsSync(dir)) throw new Error(`blob bundle view is incomplete: ${sha}`);
+  regularParents(dir, opts);
+  fs.mkdirSync(path.dirname(dir), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(dir), `.${sha}-`));
+  const written = [];
+  try {
+    writeBundleStaging(staging, members, sha, written);
+    try { fs.renameSync(staging, dir); }
+    catch (error) { if (!fs.existsSync(dir) || !verifiedBundle(dir, entries, opts)) throw error; }
+  } finally {
+    dropStaging(staging, written);
+  }
+  if (!verifiedBundle(dir, entries, opts)) throw new Error(`blob bundle publication is incomplete: ${sha}`);
+  return dir;
+}
+
+/**
+ * The readable file of one record asset: a product asset kept in the tree ({path}, a ui direction the owner accepted,
+ * decision Q2) resolves against the record's directory; agent output ({artifact?, sha256, name}) resolves in the blob
+ * store as a copy carrying the extension of its artifact name. Null when neither is readable.
+ */
+export function assetFileOf(recordDir, asset, { db = null, root = null } = {}) {
+  if (!asset || typeof asset !== 'object') return null;
+  if (typeof asset.path === 'string' && asset.path) { const file = path.resolve(recordDir, asset.path); return fs.existsSync(file) ? file : null; }
+  return blobAsFile(asset, { ext: path.extname(String(asset.name ?? '')).toLowerCase(), db, root });
+}

package/runtime/engine/db/event-compact.mjs

@@ -0,0 +1,73 @@
+// event-compact.mjs — the bounded inline view of an event payload, and the one place the event size bound is declared.
+// A launch admission decision (every candidate with its quota snapshot, the pick record) and an admission refusal grow with the number of
+// candidates, so no event may carry one whole: appendEvent (ledger.mjs) stores the full payload as a blob (events.payload_sha) and keeps this
+// summary inline. Readers that need the whole decision read the blob behind the row's payload_sha.
+import { isPlainObject } from '../plain-object.mjs';
+import { list } from '../../scripts/lib/list.mjs';
+import { redactData } from '../../scripts/lib/redact.mjs';
+
+/** Declared sizes: the ledger event bound and the inline summary caps (every cap keeps the summary far below the bound). */
+export const EVENT_LIMITS = Object.freeze({ payloadBytes: 16384, rows: 8, ids: 8, stringChars: 200, lineChars: 600, depth: 8 });
+const ADMISSION_SCHEMA = 'starci/agent-admission@1';
+export const REFUSAL_SCHEMA = 'starci/admission-refusal@1';
+
+const clip = (value, max = EVENT_LIMITS.stringChars) => (typeof value === 'string' && value.length > max ? `${value.slice(0, max)}...` : value);
+
+/** The primitive fields of an object, long strings clipped: quota snapshots and other nested records are dropped. */
+function scalars(value) {
+  if (!isPlainObject(value)) return value ?? null;
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v === null || ['string', 'number', 'boolean'].includes(typeof v)).map(([k, v]) => [k, clip(v)]));
+}
+const rowOf = (row) => ({ id: row?.id ?? null, provider: row?.provider ?? null, model: row?.model ?? null, codes: list(row?.codes).slice(0, EVENT_LIMITS.rows).map((code) => clip(code, 80)) });
+
+function admissionSummary(a) {
+  const receipt = isPlainObject(a.receipt) ? { ...scalars(a.receipt), ...(isPlainObject(a.receipt.scope) ? { scope: scalars(a.receipt.scope) } : {}) } : null;
+  return { schema: a.schema, ok: a.ok === true, reason: clip(a.reason ?? null), policyVersion: a.policyVersion ?? null, chosenBy: clip(a.chosenBy ?? null),
+    overrideApplied: a.overrideApplied === true, resetAt: a.resetAt ?? null, request: scalars(a.request), selected: scalars(a.selected),
+    eligibleCount: list(a.eligible).length, eligible: list(a.eligible).slice(0, EVENT_LIMITS.ids).map((row) => row?.id ?? null),
+    rejectedCount: list(a.rejected).length, rejected: list(a.rejected).slice(0, EVENT_LIMITS.rows).map(rowOf),
+    ...(receipt ? { receipt } : {}), summarized: true };
+}
+
+function refusalSummary(r) {
+  const rows = list(r.rejected), alternatives = list(r.alternatives);
+  return { schema: r.schema, class: r.class ?? null, queuedBecause: r.queuedBecause ?? null, line: clip(r.line ?? null, EVENT_LIMITS.lineChars),
+    rejectedCount: rows.length, rejected: rows.slice(0, EVENT_LIMITS.rows).map(rowOf),
+    alternativesCount: alternatives.length, alternatives: alternatives.slice(0, EVENT_LIMITS.ids).map((entry) => clip(String(entry))), summarized: true };
+}
+
+const SUMMARIES = Object.freeze({ [ADMISSION_SCHEMA]: admissionSummary, [REFUSAL_SCHEMA]: refusalSummary });
+
+/** `{payload, compacted}`: every admission-shaped record in `payload` replaced by its bounded summary; `compacted` says whether one was. */
+function compactEventPayload(payload, depth = 0) {
+  if (depth > EVENT_LIMITS.depth || payload === null || typeof payload !== 'object') return { payload, compacted: false };
+  if (isPlainObject(payload) && typeof payload.schema === 'string' && payload.summarized !== true && SUMMARIES[payload.schema])
+    return { payload: SUMMARIES[payload.schema](payload), compacted: true };
+  let compacted = false;
+  const visit = (value) => { const inner = compactEventPayload(value, depth + 1); compacted ||= inner.compacted; return inner.payload; };
+  const copy = Array.isArray(payload) ? payload.map((item) => visit(item)) : Object.fromEntries(Object.entries(payload).map(([k, v]) => [k, visit(v)]));
+  return { payload: compacted ? copy : payload, compacted };
+}
+
+/** A payload's bounded inline view when it went whole to the blob store: its top-level scalars (long strings clipped) and where the rest is. */
+function spilledView(redacted, bytes, sha) {
+  const flat = isPlainObject(redacted) ? scalars(redacted) : {};
+  return { ...flat, spilled: true, sha256: sha, bytes };
+}
+
+/**
+ * The stored form of an event payload: `{payloadJson, payloadSha}`. The payload is redacted. It goes whole to the blob store (`spill(bytes)`
+ * stores it and returns its sha, kept when the caller already holds one) when it carries an admission record (the bounded summary is the inline
+ * JSON) or when it is over the inline bound (the inline JSON is its top-level scalars and the sha). This is the one path of every event writer:
+ * a payload that grows with its input (a file list, a manifest, a critique, a menu) never fails the write, and a reader that needs the whole
+ * payload goes through engine/db/event-payload.mjs.
+ */
+export function eventPayloadRecord(payload, payloadSha, spill) {
+  if (payload === null || payload === undefined) return { payloadJson: null, payloadSha };
+  const redacted = redactData(payload);
+  const { payload: inline, compacted } = compactEventPayload(redacted);
+  const json = JSON.stringify(inline);
+  if (compacted || payloadSha || json.length <= EVENT_LIMITS.payloadBytes) return { payloadJson: json, payloadSha: compacted && !payloadSha ? spill(Buffer.from(JSON.stringify(redacted))) : payloadSha };
+  const sha = spill(Buffer.from(JSON.stringify(redacted)));
+  return { payloadJson: JSON.stringify(spilledView(redacted, json.length, sha)), payloadSha: sha };
+}

package/runtime/engine/db/ledger-open.mjs

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { installRefResolver } from './ref-value.mjs';
+
+// engine/db/ledger-open.mjs — how a ledger file is opened: bounded retry on a transient CANTOPEN, a reference-resolving handle.
+const require=createRequire(import.meta.url);
+export const need=(ok,message,code)=>{if(!ok)throw Object.assign(new Error(message),code?{code}:{});};
+export const applyPragmas=(db,pragmas)=>db.exec(Object.entries(pragmas).map(([k,v])=>`PRAGMA ${k}=${v};`).join(' '));
+const openSleep=ms=>Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,ms);
+// SQLITE_CANTOPEN is transient on Windows while a concurrent process closes the WAL files: a short bounded retry.
+const OPEN_RETRY_DELAYS_MS=[0,300,900];
+const cantOpen=error=>/unable to open/i.test(String(error?.message??''));
+export function openDb({file,busyTimeoutMs,journalMode='WAL',autoVacuum=false,label,pragmas}){
+  const {DatabaseSync}=require('node:sqlite');
+  need(typeof file==='string'&&file.trim(),`${label} needs a file`);
+  fs.mkdirSync(path.dirname(path.resolve(file)),{recursive:true});
+  let lastError;
+  for(const delay of OPEN_RETRY_DELAYS_MS){
+    if(delay)openSleep(delay);
+    let db;
+    try{
+      db=installRefResolver(new DatabaseSync(file,{timeout:busyTimeoutMs}));
+      // page_size/auto_vacuum only take on an empty database, before WAL and before the first table.
+      if(autoVacuum&&Number(db.prepare('PRAGMA page_count').get().page_count)===0)db.exec('PRAGMA page_size=4096; PRAGMA auto_vacuum=INCREMENTAL;');
+      const sqliteVersion=db.prepare('select sqlite_version() AS version').get().version;
+      const actual=String(db.prepare(`PRAGMA journal_mode=${journalMode}`).get().journal_mode).toUpperCase();
+      need(actual===String(journalMode).toUpperCase(),`${label}: SQLite selected journal mode ${actual}, expected ${journalMode} (a network or UNC path cannot hold WAL)`,'STARCI_LEDGER_NOT_WAL');
+      applyPragmas(db,pragmas);
+      return {db,sqliteVersion,journalMode:actual};
+    }catch(error){
+      try{db?.close();}catch{}
+      if(!cantOpen(error))throw error;
+      lastError=error;
+    }
+  }
+  throw lastError;
+}

package/runtime/engine/db/ledger-paths.mjs

@@ -0,0 +1,87 @@
+// Ledger path identity and ownership resolution; connection policy and caches remain in ledger.mjs.
+import fs from 'node:fs';
+import path from 'node:path';
+import {sha256} from '../digest.mjs';
+import {isUnderTempDir,localProjectsRoot,readMachine} from './machine.mjs';
+import {isSpecRun} from '../../scripts/lib/env.mjs';
+import {pathKey} from '../../scripts/lib/path-key.mjs';
+import {byCodeUnit} from '../by-code-unit.mjs';
+import {tempRoot} from '../temp-root.mjs';
+/** Overrides the projects root (the directory holding <ledger_id>/runtime.sqlite) for this process tree; narrower than machine-db.mjs LOCAL_ROOT_ENV, which this still honors through starciLocalRoot when unset. */
+export const PROJECTS_ROOT_ENV='STARCI_PROJECTS_ROOT';
+const normDir=file=>pathKey(file);
+/** <runtime root>/.runtime/projects (starciLocalRoot, itself overridable by STARCI_LOCAL_ROOT; a node --test process tree gets one under the OS temp directory). */
+export const projectsRootFor=(env=process.env)=>{
+  if(env[PROJECTS_ROOT_ENV])return path.resolve(env[PROJECTS_ROOT_ENV]);
+  const root=localProjectsRoot(env);
+  if(isSpecRun(env)&&!isUnderTempDir(root,{env}))return path.join(tempRoot({env}),'starci-test-projects');
+  return root;
+};
+/** Repository identity: resolved/realpath, forward slashes, case-folded only on Windows. */
+export const repoRootKey=repoRoot=>{let root=path.resolve(repoRoot);try{root=fs.realpathSync.native(root);}catch{}return normDir(root);};
+/**
+ * The ledger id of a repository root until the machine registry (a3-2 machine.ledgers) resolves it: a name-based
+ * UUID of the normalized root, so the same root always names the same ledger and no side registry is needed.
+ */
+const ledgerIdFromKey=key=>{
+  const h=sha256(`starci-ledger:${key}`);
+  return `${h.slice(0,8)}-${h.slice(8,12)}-5${h.slice(13,16)}-${(8|(Number.parseInt(h[16],16)&3)).toString(16)}${h.slice(17,20)}-${h.slice(20,32)}`;
+};
+export const ledgerIdForRepo=repoRoot=>ledgerIdFromKey(repoRootKey(repoRoot));
+/** The registered runtime.sqlite of `repoRoot` in machine.ledgers (a3-2 resolveLedger), or null. */
+function registeredLedgerFile(root,env,openReader){
+  let row;try{row=readMachine(m=>m.resolveLedger({repoRoot:root}),null,{env});}catch{return null;}
+  const file=row?.file&&row.state!=='retired'?path.resolve(row.file):null;
+  if(file&&fs.existsSync(file))assertLedgerRoot(file,root,openReader);
+  return file;
+}
+function assertLedgerRoot(file,root,openReader){
+  const db=openReader(file);let own;try{own=db.prepare("SELECT value FROM meta WHERE key='repo_root'").get()?.value;}finally{db.close();}
+  if(!own||repoRootKey(own)!==repoRootKey(root))throw Object.assign(new Error(`ledger-root-mismatch: ${file} belongs to another or unverified repository; preserve the database and resolve the owner binding with the owner`),{code:'STARCI_LEDGER_ROOT_MISMATCH'});
+}
+function unregisteredLedgerFile(root,env,openReader){
+  const base=projectsRootFor(env),current=path.join(base,ledgerIdForRepo(root),'runtime.sqlite');
+  if(fs.existsSync(current)){assertLedgerRoot(current,root,openReader);return current;}
+  return current;
+}
+/** Resolve the registry or exact owned store; the ledger owner supplies its verified read-only opener. */
+export function resolveLedgerFile(root,{env,openReader}){
+  return registeredLedgerFile(root,env,openReader)??unregisteredLedgerFile(root,env,openReader);
+}
+
+const SYNTHETIC_LEDGER_ID=/^00000000-0000-4000-8000-[0-9a-f]{12}$/;
+const fixtureRefused=message=>{throw new TypeError(`ledger-fixture-refused: ${message}`);};
+const assertFixtureIdentity=fixture=>{
+  if(fixture.sqliteVersion!==undefined&&(typeof fixture.sqliteVersion!=='string'||!/^\d+\.\d+\.\d+(?:\.\d+)?$/.test(fixture.sqliteVersion)))fixtureRefused('sqliteVersion must be a dotted numeric version');
+  if(typeof fixture.ledgerId!=='string'||!SYNTHETIC_LEDGER_ID.test(fixture.ledgerId))fixtureRefused('ledgerId must be a synthetic UUID');
+  if(!Number.isSafeInteger(fixture.createdAt)||fixture.createdAt<=0||!Number.isFinite(new Date(fixture.createdAt).getTime()))fixtureRefused('createdAt must be a positive safe epoch millisecond');
+  const root=fixture.blobRoot;
+  if(typeof root!=='string'||!root||root.includes('\\')||root.trim()!==root||/[<>:"|?*\x00-\x1f]/.test(root)
+    ||path.posix.isAbsolute(root)||root.split('/').some(p=>!p||p==='.'||p==='..'))fixtureRefused('blobRoot must be a portable relative path');
+};
+const assertFixtureFile=file=>{
+  if(typeof file!=='string'||!path.isAbsolute(file)||path.basename(file)!=='runtime.sqlite')fixtureRefused('file must be an explicit absolute runtime.sqlite');
+  for(const suffix of ['','-wal','-shm'])if(fs.lstatSync(file+suffix,{throwIfNoEntry:false}))fixtureRefused('file and WAL/SHM must be absent');
+  const parent=path.dirname(file),stat=fs.lstatSync(parent,{throwIfNoEntry:false});
+  if(!stat?.isDirectory()||stat.isSymbolicLink()||fs.realpathSync.native(parent)!==path.resolve(parent))fixtureRefused('sample parent must be an existing physical directory');
+};
+/** Validate a fresh, initialization-only sample identity. Samples carry portable metadata,
+ * never a repository/machine binding; the ordinary project resolver is not bypassed. */
+export function ledgerFixtureInit(fixture,{file,repoRoot,product,machine,mapped,checkpointer,now}){
+  if(fixture===null){
+    if(typeof file==='string'&&SYNTHETIC_LEDGER_ID.test(path.basename(path.dirname(path.resolve(file)))))fixtureRefused('synthetic identity is reserved for a sample');
+    return null;
+  }
+  if(!fixture||typeof fixture!=='object'||Array.isArray(fixture)
+    ||![Object.prototype,null].includes(Object.getPrototypeOf(fixture))
+    ||!['blobRoot,createdAt,ledgerId','blobRoot,createdAt,ledgerId,sqliteVersion'].includes(Object.keys(fixture).sort(byCodeUnit).join(',')))fixtureRefused('needs ledgerId, createdAt and blobRoot, and may state sqliteVersion');
+  assertFixtureIdentity(fixture);
+  if(repoRoot!==null||product!==null||machine!==null||mapped)fixtureRefused('a sample cannot bind a repository, product, machine or cached project path');
+  if(!checkpointer||now!==Date.now)fixtureRefused('initialization owns its frozen clock and requires a checkpointer');
+  assertFixtureFile(file);
+  return Object.freeze({...fixture,marker:'starci/basic-runtime-fixture@1'});
+}
+/** Refuse sample bytes as an operational ledger before opening a writer or beginning a transaction. */
+export function assertOperationalLedger(meta){
+  if(meta.fixture||SYNTHETIC_LEDGER_ID.test(meta.ledger_id??''))throw new Error('ledger-fixture-read-only: preserve the sample; initialize a new live project store');
+}