@starci/hfs 4.0.10 → 4.1.0

package/runtime/engine/db/blob.mjs

@@ -1,315 +0,0 @@
-// 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 (alpha.3, ARCHITECTURE-DB §5.3). 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 os from 'node:os';
-import path from 'node:path';
-import crypto from 'node:crypto';
-
-export const ARTIFACT_ROOT_ENV = 'STARCI_ARTIFACT_ROOT';
-export const artifactRoot = (env = process.env) => path.resolve(env[ARTIFACT_ROOT_ENV] || path.join(os.homedir(), '.starci', 'artifacts'));
-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 });
-    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');
-
-// Reject roots inside a checkout, including worktrees whose .git is a file.
-function ensureExternalRoot(root) {
-  let cursor = root;
-  while (true) {
-    if (fs.existsSync(path.join(cursor, '.git'))) throw new Error(`artifact root is inside a git checkout: ${root}`);
-    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)try { fs.unlinkSync(temp); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
-}
-
-/** 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 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().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. ~/.starci/artifacts-views.
-const viewRoot = (root = null) => `${root === null ? artifactRoot() : path.resolve(root)}-views`;
-const slash = (p) => String(p).replace(/\\/g, '/');
-
-/** 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 });
-  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;
-}
-
-function regularParents(file, { strict = false } = {}) {
-  let cursor = path.dirname(file);
-  while (true) {
-    const stat = strict ? fs.lstatSync(cursor, { throwIfNoEntry: false }) : (fs.existsSync(cursor) ? fs.lstatSync(cursor) : null);
-    if (stat) {
-      if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`blob view parent is not a regular directory: ${cursor}`);
-      const parent = path.dirname(cursor);
-      if (strict && parent !== cursor
-        && (fs.realpathSync.native(cursor) !== path.join(fs.realpathSync.native(parent), path.basename(cursor))
-          || !fs.readdirSync(parent).includes(path.basename(cursor))))
-        throw new Error(`blob read parent is linked or has a different spelling: ${cursor}`);
-    }
-    const parent = path.dirname(cursor);
-    if (parent === cursor) return;
-    cursor = parent;
-  }
-}
-
-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, { strict = false } = {}) {
-  regularParents(path.join(dir, '.complete'), { strict });
-  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;
-}
-
-/** 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);
-  if (verifiedBundle(dir, entries, { strict: root !== null })) return dir;
-  if (fs.existsSync(dir)) throw new Error(`blob bundle view is incomplete: ${sha}`);
-  regularParents(dir, { strict: root !== null });
-  fs.mkdirSync(path.dirname(dir), { recursive: true });
-  const staging = fs.mkdtempSync(path.join(path.dirname(dir), `.${sha}-`));
-  try {
-    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 });
-      fs.writeFileSync(to, bytes, { flag: 'wx' });
-    }
-    fs.writeFileSync(path.join(staging, '.complete'), sha, { flag: 'wx' });
-    try { fs.renameSync(staging, dir); }
-    catch (error) { if (!fs.existsSync(dir) || !verifiedBundle(dir, entries, { strict: root !== null })) throw error; }
-  } finally {
-    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
-  }
-  if (!verifiedBundle(dir, entries, { strict: root !== null })) 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/ledger-paths.mjs

@@ -1,83 +0,0 @@
-// Ledger path identity and ownership resolution; connection policy and caches remain in ledger.mjs.
-import fs from 'node:fs';
-import os from 'node:os';
-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';
-/** 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);
-/** %LOCALAPPDATA%/StarCi/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(os.tmpdir(),'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|(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&&row.state!=='retired'&&row.file?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(Error(`ledger-root-mismatch: ${file} belongs to another or unverified repository; preserve the database and resolve the owner binding before migration`),{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;}
-  // Preserve a pre-fix POSIX binding only when its own exact repo_root proves
-  // this repository. Never silently move, rename or merge an old folded store.
-  const legacy=path.join(base,ledgerIdFromKey(repoRootKey(root).toLowerCase()),'runtime.sqlite');
-  if(legacy!==current&&fs.existsSync(legacy)){assertLedgerRoot(legacy,root,openReader);return legacy;}
-  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}`);};
-/** 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))
-    ||Object.keys(fixture).sort().join(',')!=='blobRoot,createdAt,ledgerId')fixtureRefused('needs exactly ledgerId, createdAt and blobRoot');
-  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');
-  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');
-  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');
-  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');
-}