@starci/hfs 4.0.9 → 4.0.10

package/runtime/engine/config.mjs

@@ -6,6 +6,8 @@ import {parseYaml} from './yaml.mjs';
 import {isPlainObject as plain} from './plain-object.mjs';
 import {invalid,validateRoots} from './invalid-config.mjs';
 import {validateOrca} from './orca-config.mjs';
+import {ENV_NAME,secretEnv,connectorSecret} from './secrets.mjs';
+export {readDotenv,connectorSecret} from './secrets.mjs';
 
 export const configRoot=skillRoot;
 export const NON_OPERATION_ROLES={planner:'plan',kernelManager:'decide',validator:'verify'};
@@ -40,6 +42,29 @@ export function runtimeProfile(){
  * here; a literal copy of any of them in a source file would be a second authority.
  */
 export function allocationSettings(){return runtimeProfile()?.allocation??{};}
+// These are current owner declarations, never a historical runtime owner's consent.
+function validateOwnerProfile(value,name,pathsKey){
+  if(value===null)return;
+  const bad=invalid(name);
+  if(!plain(value))bad(' must be an owner approval mapping or null.');
+  const keys=['approvedBy','approvalRef',pathsKey,...(name==='launchTrust'?['profile']:[])];
+  for(const key of Object.keys(value))if(!keys.includes(key))bad(` has unknown key ${key}.`);
+  if(value.approvedBy!=='owner')bad('.approvedBy must be owner; adoption must come from the current owner.');
+  if(typeof value.approvalRef!=='string'||!value.approvalRef.trim())bad('.approvalRef must identify the current owner approval.');
+  if(name==='launchTrust'&&!['automatic','declined'].includes(value.profile))bad('.profile must be automatic or declined.');
+  const paths=value[pathsKey];
+  if(!Array.isArray(paths)||!paths.length||paths.some(p=>typeof p!=='string'||!(path.isAbsolute(p)||path.win32.isAbsolute(p))||/[\r\n\0]/.test(p)))bad(`.${pathsKey} must list exact absolute repository roots.`);
+}
+export function launchTrustSettings(config=loadConfig()){
+  const value=config?.launchTrust??null;validateOwnerProfile(value,'launchTrust','roots');return value;
+}
+export function workflowPurgeSettings(config=loadConfig()){
+  const retention=config?.retention??null;
+  if(retention===null)return null;
+  const bad=invalid('retention');
+  if(!plain(retention)||Object.keys(retention).some(k=>k!=='workflowPurge'))bad(' must be {workflowPurge?} or null.');
+  const value=retention.workflowPurge??null;validateOwnerProfile(value,'retention.workflowPurge','repos');return value;
+}
 /** One positive millisecond value out of `allocation`, by dotted key. Refuses when the contract omits it. */
 export function allocationMs(dotted){
   const raw=dotted.split('.').reduce((node,key)=>(node==null?node:node[key]),allocationSettings());
@@ -75,13 +100,11 @@ const CLOUDFLARE_MODES=['off','quick','named'];
 /** The serve-ask port band, both ends included (scripts/kernel/ask-server.mjs scans [first..last]); the gateway stays outside it. */
 export const ASK_PORT_BAND=[6969,7069];
 export const CONNECTOR_DEFAULTS=Object.freeze({
-  secretsFile:null,
   repos:[],
   gateway:{port:7070},
   cloudflare:{mode:'off',tunnel:null,credentialsFile:null,tokenEnv:'CLOUDFLARE_TUNNEL_TOKEN',hostname:null,access:false},
   telegram:{enabled:false,botTokenEnv:'TELEGRAM_BOT_TOKEN',chatId:null,exposeCredentialAsks:false},
 });
-const ENV_NAME=/^[A-Z_][A-Z0-9_]{0,63}$/;
 const HOSTNAME=/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
 const TUNNEL_REF=/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
 const CHAT_ID=/^(?:-?\d{1,20}|@[A-Za-z][A-Za-z0-9_]{4,31})$/;
@@ -89,7 +112,7 @@ const SECRET_KEYS=['token','tunnelToken','botToken','secret','apiToken','passwor
 function validateConnectors(connectors){
   if(connectors===null)return;
   const bad=invalid('connectors');
-  if(!plain(connectors))bad(' must be {secretsFile?, repos?, gateway?, cloudflare?, telegram?} or null.');
+  if(!plain(connectors))bad(' must be {repos?, gateway?, cloudflare?, telegram?} or null.');
   const closed=(node,where,keys)=>{
     if(!plain(node))bad(`.${where} must be a mapping.`);
     for(const key of Object.keys(node)){
@@ -97,8 +120,7 @@ function validateConnectors(connectors){
       if(!keys.includes(key))bad(`.${where} has unknown key ${key} (allowed: ${keys.join(', ')}).`);
     }
   };
-  closed(connectors,'',['secretsFile','repos','gateway','cloudflare','telegram']);
-  if(connectors.secretsFile!==undefined&&connectors.secretsFile!==null&&(typeof connectors.secretsFile!=='string'||!connectors.secretsFile.trim()))bad('.secretsFile must be a dotenv file path (relative to the skill root) or null.');
+  closed(connectors,'',['repos','gateway','cloudflare','telegram']);
   if(connectors.repos!==undefined&&(!Array.isArray(connectors.repos)||connectors.repos.some(repo=>typeof repo!=='string'||!repo.trim())))bad('.repos must be a list of repository paths.');
   if(connectors.gateway!==undefined){
     closed(connectors.gateway,'gateway',['port']);
@@ -132,46 +154,14 @@ function validateConnectors(connectors){
     if(tg.enabled===true&&(tg.chatId===undefined||tg.chatId===null))bad('.telegram.enabled needs telegram.chatId.');
   }
 }
-/**
- * The secret an env var NAME resolves to: `env[name]`, else the contents of the file `env[name + '_FILE']`
- * points at (the custody pointer convention). Returns null when neither is set. Callers pass the value to
- * the one API that needs it and never print it.
- */
-/** Parse a dotenv file (KEY=VALUE lines, # comments, optional export/quotes). An absent file is {}. */
-export function readDotenv(file){
-  let text='';try{text=fs.readFileSync(file,'utf8');}catch(error){if(error?.code==='ENOENT')return {};throw error;}
-  const out={};
-  for(const line of text.split(/\r?\n/)){
-    const m=line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
-    if(!m)continue;
-    let value=m[2];
-    if(value.length>=2&&(value[0]==='"'||value[0]==="'")&&value.at(-1)===value[0])value=value.slice(1,-1);
-    out[m[1]]=value;
-  }
-  return out;
-}
-/** The dotenv file connectors.secretsFile names, resolved against the skill root; null when unset. */
-const connectorSecretsFile=(config,root=configRoot)=>{const file=config?.connectors?.secretsFile;return typeof file==='string'&&file.trim()?path.resolve(root,file):null;};
-/**
- * The environment the connectors resolve secrets from: connectors.secretsFile's values under the process
- * environment (a real env var wins). It holds secrets — hand it to connectorSecret, never print it.
- */
-export function connectorEnv(config,env=process.env,root=configRoot){const file=connectorSecretsFile(config,root);return file?{...readDotenv(file),...env}:env;}
-export function connectorSecret(name,env=process.env){
-  if(typeof name!=='string'||!ENV_NAME.test(name))return null;
-  const direct=typeof env[name]==='string'?env[name].trim():'';
-  if(direct)return direct;
-  const pointer=typeof env[`${name}_FILE`]==='string'?env[`${name}_FILE`].trim():'';
-  if(!pointer)return null;
-  try{const value=fs.readFileSync(pointer,'utf8').trim();return value||null;}catch{return null;}
-}
+/** Load connector credentials from the explicitly verified runtime main; never print the returned environment. */
+export function connectorEnv(config,env=process.env,verifiedRuntimeRoot){return secretEnv(verifiedRuntimeRoot,env);}
 /**
  * The normalized `connectors` block: defaults filled in, the secrets' PRESENCE (booleans, never values),
  * whether each connector is ready to run, and the owner-facing warnings the security posture earns.
  */
 export function connectorsConfig(config=loadConfig(),env=process.env,root=configRoot){
   validateConfig(config);
-  env=connectorEnv(config,env,root);
   const raw=plain(config?.connectors)?config.connectors:{},d=CONNECTOR_DEFAULTS;
   const cloudflare={...d.cloudflare,...(raw.cloudflare??{})},telegram={...d.telegram,...(raw.telegram??{})};
   if(cloudflare.credentialsFile)cloudflare.credentialsFile=path.resolve(root,cloudflare.credentialsFile.replace(/^~(?=[\\/])/,env.USERPROFILE??env.HOME??'~'));
@@ -189,7 +179,7 @@ export function connectorsConfig(config=loadConfig(),env=process.env,root=config
   if(cloudflare.auth==='token'&&!cloudflare.tokenPresent)warnings.push(`cloudflare.mode named: the tunnel token is not set — export ${cloudflare.tokenEnv} (or ${cloudflare.tokenEnv}_FILE).`);
   if(telegram.enabled&&!telegram.botTokenPresent)warnings.push(`telegram.enabled: the bot token is not set — export ${telegram.botTokenEnv} (or ${telegram.botTokenEnv}_FILE).`);
   if(telegram.exposeCredentialAsks)warnings.push('telegram.exposeCredentialAsks is true: credential asks are posted as public links; Telegram cloud chats are not end-to-end encrypted.');
-  return {secretsFile:connectorSecretsFile(config,root),repos:[...(raw.repos??d.repos)],gateway:{...d.gateway,...(raw.gateway??{})},cloudflare,telegram,warnings};
+  return {repos:[...(raw.repos??d.repos)],gateway:{...d.gateway,...(raw.gateway??{})},cloudflare,telegram,warnings};
 }
 /**
  * config.yaml `asks` — whether an owner ask that carries a recommended option is answered with it
@@ -305,7 +295,9 @@ function validateAgentSeat(seat,name,profile){
   if(seat.effort!==undefined&&seat.effort!==null&&!EFFORT_LEVELS.includes(seat.effort))throw Error(`Invalid config.yaml: ${name}.effort must use the effort vocabulary.`);
 }
 export function validateConfig(config){
-  const allowed=['language','model','effort','models','debug','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','coreDebug','orca','roots'],models=config?.models,profile=runtimeProfile(),runtimes=profile?.runtimes??{};
+  const allowed=['language','model','effort','models','debug','allocation','kernel','budgets','supervisor','parallel','delegation','connectors','asks','uat','specs','reconciler','coreDebug','orca','roots','launchTrust','retention'],models=config?.models,profile=runtimeProfile(),runtimes=profile?.runtimes??{};
+  if(config?.launchTrust!==undefined)launchTrustSettings(config);
+  if(config?.retention!==undefined)workflowPurgeSettings(config);
   if(config?.connectors!==undefined)validateConnectors(config.connectors);
   if(config?.asks!==undefined)validateAsks(config.asks);
   if(config?.uat!==undefined)validateUat(config.uat);
@@ -372,8 +364,8 @@ export function validateConfig(config){
   }
   if(config?.budgets!==undefined){
     const budgets=config.budgets;
-    if(!plain(budgets)||Object.keys(budgets).some(key=>!['maxOps','perOpMs','dailyTokens'].includes(key))||Object.values(budgets).some(value=>value!==null&&!(Number.isInteger(value)&&value>0)))
-      throw Error('Invalid config.yaml: budgets must be {maxOps?, perOpMs?, dailyTokens?} with positive-integer-or-null values.');
+    if(!plain(budgets)||Object.keys(budgets).some(key=>!['maxOps'].includes(key))||Object.values(budgets).some(value=>value!==null&&!(Number.isInteger(value)&&value>0)))
+      throw Error('Invalid config.yaml: budgets must be {maxOps?} with positive-integer-or-null values.');
   }
   if(!plain(config)||Object.keys(config).some(key=>!allowed.includes(key))||typeof config.language!=='string'||!/^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/.test(config.language)||!(config.model===null||typeof config.model==='string'&&config.model.trim())||!EFFORT_LEVELS.includes(config.effort)||!plain(models)||Object.keys(models).some(key=>!['pools','nonOperation','selection'].includes(key))||models.selection!=='quota-aware'||!plain(models.pools)||!plain(models.nonOperation)||Object.keys(models.pools).length!==Object.keys(DEFAULT_MODEL_POOLS).length||Object.keys(models.pools).some(key=>!Object.hasOwn(DEFAULT_MODEL_POOLS,key))||Object.keys(models.nonOperation).length!==Object.keys(NON_OPERATION_ROLES).length||Object.keys(models.nonOperation).some(key=>!Object.hasOwn(NON_OPERATION_ROLES,key)))throw Error('Invalid config.yaml: expected language, model, effort and the closed quota-aware model pools/non-operation role map.');
   for(const [pool,members] of Object.entries(models.pools))if(!Array.isArray(members)||members.length!==2||new Set(members).size!==2||members.some(id=>typeof id!=='string'||!plain(runtimes[id]))||!(members.length===DEFAULT_MODEL_POOLS[pool].length&&members.every(id=>DEFAULT_MODEL_POOLS[pool].includes(id))))throw Error(`Invalid config.yaml: models.pools.${pool} must contain its canonical pair of two unique known runtime ids.`);
@@ -444,7 +436,7 @@ export function inspectOwnerConfig(root=configRoot){
  *             or `starci kernel run-deferred-tests`); e2e.verify then runs the FULL e2e suite.
  * An absent, null or unreadable owner file reads as the defaults: harness off, unit on, e2e off.
  */
-export const SPEC_FAMILIES=Object.freeze(['harness','unit','e2e']);
+const SPEC_FAMILIES=Object.freeze(['harness','unit','e2e']);
 export const SPEC_DEFAULTS=Object.freeze({harness:false,unit:true,e2e:false});
 export function specsSettings(config){const specs=plain(config?.specs)?config.specs:{};return Object.fromEntries(SPEC_FAMILIES.map(key=>[key,typeof specs[key]==='boolean'?specs[key]:SPEC_DEFAULTS[key]]));}
 /** specs.harness of the owner file under `root` (tolerant read: inspectOwnerConfig): true only when the owner opted in to `--specs all`. */

package/runtime/engine/db/blob.mjs

@@ -0,0 +1,315 @@
+// 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

@@ -0,0 +1,83 @@
+// 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');
+}