@starci/hfs 4.11.22 → 4.12.2

package/runtime/engine/db/ref-value.mjs

@@ -7,61 +7,62 @@
 // keeps a short value inline and puts a long one in the blob store. A value is resolved byte for byte: the blob holds exactly the text the writer was given.
 import { createRequire } from 'node:module';
 import { getBlob } from './blob.mjs';
-
 const REF = /^\{"truncated":true,"bytes":(\d+),"sha256":"([0-9a-f]{64})"\}$/;
-
 /** Whether a stored value is a reference. */
 export const isRef = (value) => typeof value === 'string' && value.codePointAt(0) === 123 && REF.test(value);
-
 /** The reference string of a blob. */
 export const refOf = (sha, bytes) => JSON.stringify({ truncated: true, bytes, sha256: sha });
-
 /** The {sha, bytes} a reference names, or null. */
 export function parseRef(value) {
-  const match = typeof value === 'string' && value.codePointAt(0) === 123 ? REF.exec(value) : null;
-  return match ? { sha: match[2], bytes: Number(match[1]) } : null;
+    const match = typeof value === 'string' && value.codePointAt(0) === 123 ? REF.exec(value) : null;
+    return match ? { sha: match[2], bytes: Number(match[1]) } : null;
 }
-
 /** The content behind a stored value: a reference is read from the blob store (utf8), anything else is the content itself. */
 function resolveValue(value) {
-  const ref = parseRef(value);
-  if (!ref) return value;
-  return getBlob(ref.sha).toString('utf8');
+    const ref = parseRef(value);
+    if (!ref)
+        return value;
+    return getBlob(ref.sha).toString('utf8');
 }
-
-
 const resolveRow = (row) => {
-  if (row === null || row === undefined || typeof row !== 'object') return row;
-  for (const key of Object.keys(row)) if (isRef(row[key])) row[key] = resolveValue(row[key]);
-  return row;
+    if (row === null || row === undefined || typeof row !== 'object')
+        return row;
+    const cells = row; // an object row, by the check above
+    for (const key of Object.keys(cells))
+        if (isRef(cells[key]))
+            cells[key] = resolveValue(cells[key]);
+    return row;
 };
-
 /**
  * Makes every row a statement of `db` returns resolve its reference values: get, all and iterate. The handle is changed in place and returned; a handle that was already
  * installed is left alone. Other statement methods (run, columns, ...) are the statement's own.
  */
 /** A SQLite file opened read-only with the given busy timeout, its references resolving. */
 export const openReadOnlyDb = (file, timeoutMs) => installRefResolver(new (createRequire(import.meta.url)('node:sqlite').DatabaseSync)(file, { readOnly: true, timeout: timeoutMs }));
-
 /** A statement over exact stored cells, for self-contained archives that retain references and their original bytes. */
 export const prepareStored = (db, sql, ...rest) => Object.getPrototypeOf(db).prepare.call(db, sql, ...rest);
-
 export function installRefResolver(db) {
-  if (db.__refResolver) return db;
-  // The prototype's prepare is looked up at each call, so a later change of the driver's own method (a spec's mock, a corruption injection) still applies.
-  db.prepare = (sql, ...rest) => {
-    const statement = prepareStored(db, sql, ...rest);
-    return new Proxy(statement, {
-      get(target, name) {
-        const member = target[name];
-        if (typeof member !== 'function') return member;
-        if (name === 'get') return (...args) => resolveRow(member.apply(target, args));
-        if (name === 'all') return (...args) => member.apply(target, args).map(resolveRow);
-        if (name === 'iterate') return (...args) => (function* resolved(iterator) { for (const row of iterator) yield resolveRow(row); })(member.apply(target, args));
-        return member.bind(target);
-      },
-    });
-  };
-  Object.defineProperty(db, '__refResolver', { value: true });
-  return db;
+    if (db.__refResolver)
+        return db;
+    // The prototype's prepare is looked up at each call, so a later change of the driver's own method (a spec's mock, a corruption injection) still applies.
+    db.prepare = (sql, ...rest) => {
+        const statement = prepareStored(db, sql, ...rest);
+        return new Proxy(statement, {
+            get(target, name) {
+                const member = Reflect.get(target, name);
+                if (typeof member !== 'function')
+                    return member;
+                if (name === 'get')
+                    return (...args) => resolveRow(member.apply(target, args));
+                if (name === 'all')
+                    return (...args) => member.apply(target, args).map(resolveRow);
+                if (name === 'iterate')
+                    return (...args) => (function* resolved(iterator) { for (const row of iterator)
+                        yield resolveRow(row); })(member.apply(target, args));
+                return member.bind(target);
+            },
+        });
+    };
+    Object.defineProperty(db, '__refResolver', { value: true });
+    return db;
 }

package/runtime/engine/db/sqlite-types.d.mts

@@ -0,0 +1,28 @@
+/** A bound SQL parameter: the engine passes strings, numbers, null and Buffers (booleans are mapped to 0/1 before binding). */
+export type SqlParam = unknown;
+export type SqlRow = Record<string, any>;
+/** What a write statement reports. */
+export interface SqlRunResult {
+    changes: number;
+    lastInsertRowid: number;
+}
+/** A prepared statement. */
+export interface SqlStatement {
+    run(...params: SqlParam[]): SqlRunResult;
+    get(...params: SqlParam[]): SqlRow | undefined;
+    all<Row = SqlRow>(...params: SqlParam[]): Row[];
+    iterate(...params: SqlParam[]): IterableIterator<SqlRow>;
+}
+/** An open sqlite database handle (a raw `DatabaseSync` or the engine's resilient wrapper over one). */
+export interface SqlDb {
+    prepare(sql: string, ...rest: unknown[]): SqlStatement;
+    exec(sql: string): void;
+    close(): void;
+    readonly isTransaction: boolean;
+}
+/** The part of a machine handle that its row writers use: the connection, the clock and the fenced transaction. */
+export interface StoreHandle {
+    db: SqlDb;
+    now(): number;
+    transaction<T>(fn: (db: SqlDb) => T): T;
+}

package/runtime/engine/db/sqlite-types.mjs

@@ -0,0 +1,4 @@
+// sqlite-types.mts — the shapes of the node:sqlite handle and statement the engine's stores use (types only, no runtime).
+// node:sqlite types its numbers as number | bigint and its rows as an open record; the stores read columns by name and
+// never ask for bigints, so these narrower shapes state what the code relies on.
+export {};

package/runtime/engine/digest.d.mts

@@ -0,0 +1,4 @@
+/** The lowercase hex SHA-256 of `value` (string, Buffer or TypedArray). */
+export declare const sha256: (value: string | NodeJS.ArrayBufferView) => string;
+/** The SHA-256 of the file's exact bytes; throws when the file cannot be read. */
+export declare function sha256File(file: string | number): string;

package/runtime/engine/digest.mjs

@@ -3,14 +3,23 @@
 // never disagree about what their digest is.
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-
 /** The lowercase hex SHA-256 of `value` (string, Buffer or TypedArray). */
 export const sha256 = (value) => createHash('sha256').update(value).digest('hex');
 /** The SHA-256 of the file's exact bytes; throws when the file cannot be read. */
-export function sha256File(file){
-  // A numeric descriptor belongs to the caller; positional reads preserve its offset.
-  const owned=typeof file!=='number',fd=owned?fs.openSync(file,'r'):file;
-  const hash=createHash('sha256'),buffer=Buffer.alloc(1024*1024);
-  try{let at=0,n;while((n=fs.readSync(fd,buffer,0,buffer.length,at))>0){hash.update(buffer.subarray(0,n));at+=n;}return hash.digest('hex');}
-  finally{if(owned)fs.closeSync(fd);}
+export function sha256File(file) {
+    // A numeric descriptor belongs to the caller; positional reads preserve its offset.
+    const owned = typeof file !== 'number', fd = typeof file === 'number' ? file : fs.openSync(file, 'r');
+    const hash = createHash('sha256'), buffer = Buffer.alloc(1024 * 1024);
+    try {
+        let at = 0, n;
+        while ((n = fs.readSync(fd, buffer, 0, buffer.length, at)) > 0) {
+            hash.update(buffer.subarray(0, n));
+            at += n;
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        if (owned)
+            fs.closeSync(fd);
+    }
 }

package/runtime/engine/invalid-config.d.mts

@@ -0,0 +1,13 @@
+/** The one `Invalid config.yaml:` raiser every section validator shares: bad('<rest>') throws it. */
+export type Bad = (message: string) => never;
+export declare const invalid: (section: string) => Bad;
+/** The host roots the owner may relocate (config.yaml `roots`): the archive root, the lanes root and the temp root. */
+export declare const ROOT_KEYS: readonly string[];
+/** The validated config.yaml `roots` block. */
+export interface RootsBlock {
+    archive?: string | null;
+    lanes?: string | null;
+    temp?: string | null;
+}
+/** config.yaml `roots` - {archive?, lanes?, temp?}: absolute directories, or null; an absent key means <starciLocalRoot>/archive and the per-user lanes directory. */
+export declare function validateRoots(roots: unknown): void;

package/runtime/engine/invalid-config.mjs

@@ -1,15 +1,21 @@
 import path from 'node:path';
-import {isPlainObject as plain} from './plain-object.mjs';
-/** The one `Invalid config.yaml:` raiser every section validator shares: bad('<rest>') throws it. */
-export const invalid=section=>message=>{throw new Error(`Invalid config.yaml: ${section}${message}`);};
-
+import { isPlainObject as plain } from './plain-object.mjs';
+export const invalid = (section) => message => { throw new Error(`Invalid config.yaml: ${section}${message}`); };
 /** The host roots the owner may relocate (config.yaml `roots`): the archive root, the lanes root and the temp root. */
-export const ROOT_KEYS=Object.freeze(['archive','lanes','temp']);
+export const ROOT_KEYS = Object.freeze(['archive', 'lanes', 'temp']);
 /** config.yaml `roots` - {archive?, lanes?, temp?}: absolute directories, or null; an absent key means <starciLocalRoot>/archive and the per-user lanes directory. */
-export function validateRoots(roots){
-  if(roots===null)return;
-  const bad=invalid('roots');
-  if(!plain(roots))bad(` must be {archive?: <absolute directory>, lanes?: <absolute directory>, temp?: <absolute directory>} or null.`);
-  for(const key of Object.keys(roots))if(!ROOT_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${ROOT_KEYS.join(', ')}).`);
-  for(const key of ROOT_KEYS)if(roots[key]!==undefined&&roots[key]!==null&&!(typeof roots[key]==='string'&&roots[key].trim()&&path.isAbsolute(roots[key])))bad(`.${key} must be an absolute directory path or null.`);
+export function validateRoots(roots) {
+    if (roots === null)
+        return;
+    const bad = invalid('roots');
+    if (!plain(roots))
+        return bad(` must be {archive?: <absolute directory>, lanes?: <absolute directory>, temp?: <absolute directory>} or null.`);
+    for (const key of Object.keys(roots))
+        if (!ROOT_KEYS.includes(key))
+            bad(` has unknown key ${key} (allowed: ${ROOT_KEYS.join(', ')}).`);
+    for (const key of ROOT_KEYS) {
+        const value = roots[key];
+        if (value !== undefined && value !== null && !(typeof value === 'string' && value.trim() && path.isAbsolute(value)))
+            bad(`.${key} must be an absolute directory path or null.`);
+    }
 }

package/runtime/engine/model-config.d.mts

@@ -0,0 +1,91 @@
+import type { ResourcesBlock } from './resources-config.mjs';
+/** The effort vocabulary, ordered weakest to strongest — the only list of it. */
+export declare const EFFORT_LEVELS: ReadonlySet<string>;
+export declare const MODELS_KEYS: readonly string[];
+/** One agent/model seat of a tier chain. */
+export interface TierMember {
+    agent: string;
+    model: string;
+    effort?: string;
+}
+/** The balance limits of the tier picker. */
+export interface TierBalance {
+    maxStreak: number;
+    maxSharePercent: number;
+}
+/** The usage thresholds of the tier picker. */
+export interface TierUsage {
+    reservePercent: number;
+    biasPercent: number;
+    exhaustedPercent: number;
+}
+/** modules/models/tiers.yaml as shipped: the tier document the picker reads. */
+export interface TiersDoc {
+    tiers: Record<string, TierMember[]>;
+    seats: Record<string, string>;
+    balance: TierBalance;
+    usage: TierUsage;
+    difficulty: Record<string, string>;
+    kindTiers: Record<string, string>;
+    tierOrder: string[];
+    tierUse: Record<string, string>;
+    calls: Record<string, {
+        tier: string;
+    }>;
+}
+/** A pool of modules/models/registry.yaml (merged under `runtimes`). */
+export interface RuntimePool {
+    provider?: string;
+    roles?: string[];
+    maxParallel?: number | string | null;
+    models?: string[];
+    [key: string]: unknown;
+}
+/** A model of modules/models/registry.yaml. */
+export interface RegistryModel {
+    provider?: string;
+    [key: string]: unknown;
+}
+/** modules/models/runtimes.yaml `allocation`: the workers' operating numbers. */
+export interface AllocationSettings {
+    admission?: Record<string, unknown>;
+    slicing?: {
+        gears?: number[];
+        [key: string]: unknown;
+    };
+    resources?: ResourcesBlock;
+    [key: string]: unknown;
+}
+/** modules/models/runtimes.yaml with the registry's pools and models merged in. */
+export interface RuntimeProfile {
+    allocation?: AllocationSettings;
+    runtimes: Record<string, RuntimePool>;
+    models: Record<string, RegistryModel>;
+    [key: string]: unknown;
+}
+/** config.yaml `models`: every key optional, laid over the shipped tier document. */
+export interface ModelsBlock {
+    tiers?: Record<string, unknown>;
+    seats?: Record<string, string>;
+    balance?: Partial<TierBalance>;
+    usage?: Partial<TierUsage>;
+}
+/** The tier document with config.yaml `models` laid over it. */
+export type EffectiveTiers = Omit<TiersDoc, 'tiers' | 'seats' | 'balance' | 'usage'> & {
+    tiers: Record<string, TierMember[]>;
+    seats: Record<string, string>;
+    balance: TierBalance;
+    usage: TierUsage;
+};
+/** Refuse an old-shape config (the removed keys of modules/kernel/removed-vocabulary.yaml), naming every removed key and where its meaning lives now. */
+export declare function refuseRemovedKeys(config: unknown): void;
+/** modules/models/tiers.yaml as shipped, parsed once per file version. */
+export declare function shippedTiers(): TiersDoc;
+/** The tier document the picker reads: the shipped tiers.yaml with config.yaml `models` laid over it. Validated. */
+export declare function effectiveTiers(config: {
+    models?: ModelsBlock | null;
+} | null | undefined, profile: RuntimeProfile): EffectiveTiers;
+/** config.yaml `models` — {tiers?, seats?, balance?, usage?}; the shipped defaults make every key optional. */
+export declare function validateModelsBlock(config: {
+    models?: unknown;
+} | null | undefined, profile: RuntimeProfile): void;

package/runtime/engine/model-config.mjs

@@ -1,90 +1,112 @@
 import fs from 'node:fs';
-import {fileURLToPath} from 'node:url';
-import {parseYaml} from './yaml.mjs';
-import {isPlainObject as plain} from './plain-object.mjs';
-import {invalid} from './invalid-config.mjs';
-import {byCodeUnit} from './by-code-unit.mjs';
-import {removedOfKind} from './removed-vocabulary.mjs';
-
+import { fileURLToPath } from 'node:url';
+import { parseYaml } from './yaml.mjs';
+import { isPlainObject as plain } from './plain-object.mjs';
+import { invalid } from './invalid-config.mjs';
+import { byCodeUnit } from './by-code-unit.mjs';
+import { removedOfKind } from './removed-vocabulary.mjs';
 /** The effort vocabulary, ordered weakest to strongest — the only list of it. */
-export const EFFORT_LEVELS=new Set(['none','minimal','low','medium','high','xhigh','max','ultra']);
-const DIFFICULTIES=['easy','medium','hard','insane'];
-export const MODELS_KEYS=['tiers','seats','balance','usage'];
-const known=names=>[...names].sort(byCodeUnit).join(', ');
-
-const hasPath=(root,dotted)=>dotted.split('.').reduce((node,key)=>(plain(node)&&Object.hasOwn(node,key)?node[key]:undefined),root)!==undefined;
-
+export const EFFORT_LEVELS = new Set(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra']);
+const DIFFICULTIES = ['easy', 'medium', 'hard', 'insane'];
+export const MODELS_KEYS = ['tiers', 'seats', 'balance', 'usage'];
+const known = (names) => [...names].sort(byCodeUnit).join(', ');
+const hasPath = (root, dotted) => dotted.split('.').reduce((node, key) => (plain(node) && Object.hasOwn(node, key) ? node[key] : undefined), root) !== undefined;
 /** Refuse an old-shape config (the removed keys of modules/kernel/removed-vocabulary.yaml), naming every removed key and where its meaning lives now. */
-export function refuseRemovedKeys(config){
-  const found=removedOfKind('config-key').filter(({name})=>hasPath(config,name));
-  if(!found.length)return;
-  const removed=found.map(({name,use})=>`${name} is removed (${use})`).join('; ');
-  throw new Error(`Invalid config.yaml: ${removed}.`);
+export function refuseRemovedKeys(config) {
+    const found = removedOfKind('config-key').filter(({ name }) => hasPath(config, name));
+    if (!found.length)
+        return;
+    const removed = found.map(({ name, use }) => `${name} is removed (${use})`).join('; ');
+    throw new Error(`Invalid config.yaml: ${removed}.`);
 }
-
-let shippedCache=null;
+let shippedCache = null;
 /** modules/models/tiers.yaml as shipped, parsed once per file version. */
-export function shippedTiers(){
-  const file=fileURLToPath(new URL('../modules/models/tiers.yaml',import.meta.url));
-  let stat;try{stat=fs.statSync(file);}catch{throw new Error('Missing modules/models/tiers.yaml');}
-  const version=`${stat.mtimeMs}:${stat.size}`;
-  if(shippedCache?.version!==version)shippedCache={version,doc:parseYaml(fs.readFileSync(file,'utf8'))};
-  return structuredClone(shippedCache.doc);
+export function shippedTiers() {
+    const file = fileURLToPath(new URL('../modules/models/tiers.yaml', import.meta.url));
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        throw new Error('Missing modules/models/tiers.yaml');
+    }
+    const version = `${stat.mtimeMs}:${stat.size}`;
+    if (shippedCache?.version !== version)
+        shippedCache = { version, doc: parseYaml(fs.readFileSync(file, 'utf8')) };
+    return structuredClone(shippedCache.doc);
 }
-
-function validateMember(bad,where,member,profile){
-  if(!plain(member)||Object.keys(member).some(key=>!['agent','model','effort'].includes(key))||typeof member.agent!=='string'||typeof member.model!=='string')
-    bad(`${where} must be {agent, model, effort?}.`);
-  if(profile.models?.[member.model]?.provider!==member.agent)bad(`${where}: model ${member.model} is not declared by agent ${member.agent} in modules/models/registry.yaml models.`);
-  if(member.effort!==undefined&&!EFFORT_LEVELS.has(member.effort))bad(`${where}.effort must use the effort vocabulary.`);
+function validateMember(bad, where, member, profile) {
+    if (!plain(member) || Object.keys(member).some(key => !['agent', 'model', 'effort'].includes(key)) || typeof member.agent !== 'string' || typeof member.model !== 'string')
+        return bad(`${where} must be {agent, model, effort?}.`);
+    if (profile.models?.[member.model]?.provider !== member.agent)
+        bad(`${where}: model ${member.model} is not declared by agent ${member.agent} in modules/models/registry.yaml models.`);
+    if (member.effort !== undefined && !(typeof member.effort === 'string' && EFFORT_LEVELS.has(member.effort)))
+        bad(`${where}.effort must use the effort vocabulary.`);
 }
-
-function validateChains(bad,tiers,profile){
-  for(const [name,chain] of Object.entries(tiers)){
-    if(!Array.isArray(chain)||!chain.length)bad(`.${name} must be a non-empty ordered list of {agent, model, effort?}.`);
-    chain.forEach((member,index)=>validateMember(bad,`.${name}[${index}]`,member,profile));
-    if(new Set(chain.map(member=>`${member.agent}/${member.model}`)).size!==chain.length)bad(`.${name} names each member once.`);
-  }
+function validateChains(bad, tiers, profile) {
+    for (const [name, chain] of Object.entries(tiers)) {
+        if (!Array.isArray(chain) || !chain.length)
+            return bad(`.${name} must be a non-empty ordered list of {agent, model, effort?}.`);
+        chain.forEach((member, index) => validateMember(bad, `.${name}[${index}]`, member, profile));
+        // validateMember refused every member that is not a {agent, model, effort?} record above.
+        const members = chain;
+        if (new Set(members.map(member => `${member.agent}/${member.model}`)).size !== chain.length)
+            bad(`.${name} names each member once.`);
+    }
 }
-
 /** A call tier is taken by a headless call only: no seat, difficulty, kind, order or caller reference may name it, and every call names one. */
-function validateUse(bad,{doc,names,refs}){
-  const callTiers=new Set(Object.entries(doc.tierUse).filter(([,use])=>use==='call').map(([tier])=>tier));
-  for(const tier of Object.keys(doc.tierUse))if(!names.has(tier))bad(`: tierUse names tier ${tier} (known: ${known(names)}).`);
-  for(const [where,tier] of refs)if(callTiers.has(tier))bad(`: ${where} names tier ${tier}, a call tier (tierUse): a headless call is made on it, no seat or op is seated on it.`);
-  for(const [call,spec] of Object.entries(doc.calls))if(!callTiers.has(spec.tier))bad(`: calls.${call}.tier ${spec.tier} must be a tier whose tierUse is call.`);
+function validateUse(bad, { doc, names, refs }) {
+    const callTiers = new Set(Object.entries(doc.tierUse).filter(([, use]) => use === 'call').map(([tier]) => tier));
+    for (const tier of Object.keys(doc.tierUse))
+        if (!names.has(tier))
+            bad(`: tierUse names tier ${tier} (known: ${known(names)}).`);
+    for (const [where, tier] of refs)
+        if (callTiers.has(tier))
+            bad(`: ${where} names tier ${tier}, a call tier (tierUse): a headless call is made on it, no seat or op is seated on it.`);
+    for (const [call, spec] of Object.entries(doc.calls))
+        if (!callTiers.has(spec.tier))
+            bad(`: calls.${call}.tier ${spec.tier} must be a tier whose tierUse is call.`);
 }
-
 /** The tier document the picker reads: the shipped tiers.yaml with config.yaml `models` laid over it. Validated. */
-export function effectiveTiers(config,profile){
-  const doc=shippedTiers(),models=plain(config?.models)?config.models:{};
-  const bad=invalid('models');
-  const tiers={...doc.tiers,...models.tiers};
-  validateChains(bad,tiers,profile);
-  const seats={...doc.seats,...models.seats};
-  const balance={...doc.balance,...models.balance};
-  const usage={...doc.usage,...models.usage};
-  const names=new Set(Object.keys(tiers));
-  const refs=[...Object.entries(seats).map(([seat,tier])=>[`.seats.${seat}`,tier]),...DIFFICULTIES.map(level=>[`difficulty.${level}`,doc.difficulty[level]]),
-    ...Object.entries(doc.kindTiers).map(([kind,tier])=>[`kindTiers.${kind}`,tier]),...doc.tierOrder.map(tier=>['tierOrder',tier])];
-  for(const [where,tier] of refs)if(!names.has(tier))bad(`: ${where} names tier ${tier} (known: ${known(names)}).`);
-  validateUse(bad,{doc,names,refs});
-  if(!(Number.isInteger(balance.maxStreak)&&balance.maxStreak>=1))bad('.balance.maxStreak must be an integer >= 1.');
-  if(!(typeof balance.maxSharePercent==='number'&&balance.maxSharePercent>0&&balance.maxSharePercent<=100))bad('.balance.maxSharePercent must be a number in (0, 100].');
-  const {reservePercent,biasPercent,exhaustedPercent}=usage;
-  if(![reservePercent,biasPercent,exhaustedPercent].every(value=>typeof value==='number'&&value>=0&&value<=100)||!(reservePercent<=biasPercent&&biasPercent<exhaustedPercent))
-    bad('.usage must hold numbers with reservePercent <= biasPercent < exhaustedPercent, each within 0..100.');
-  return {...doc,tiers,seats,balance,usage};
+export function effectiveTiers(config, profile) {
+    const doc = shippedTiers(), models = plain(config?.models) ? config.models : {};
+    const bad = invalid('models');
+    const merged = { ...doc.tiers, ...models.tiers };
+    validateChains(bad, merged, profile);
+    // validateChains refused every chain that is not a non-empty list of {agent, model, effort?} members.
+    const tiers = merged;
+    const seats = { ...doc.seats, ...models.seats };
+    const balance = { ...doc.balance, ...models.balance };
+    const usage = { ...doc.usage, ...models.usage };
+    const names = new Set(Object.keys(tiers));
+    const refs = [...Object.entries(seats).map(([seat, tier]) => [`.seats.${seat}`, tier]), ...DIFFICULTIES.map(level => [`difficulty.${level}`, doc.difficulty[level]]),
+        ...Object.entries(doc.kindTiers).map(([kind, tier]) => [`kindTiers.${kind}`, tier]), ...doc.tierOrder.map(tier => ['tierOrder', tier])];
+    for (const [where, tier] of refs)
+        if (!names.has(tier))
+            bad(`: ${where} names tier ${tier} (known: ${known(names)}).`);
+    validateUse(bad, { doc, names, refs });
+    if (!(Number.isInteger(balance.maxStreak) && balance.maxStreak >= 1))
+        bad('.balance.maxStreak must be an integer >= 1.');
+    if (!(typeof balance.maxSharePercent === 'number' && balance.maxSharePercent > 0 && balance.maxSharePercent <= 100))
+        bad('.balance.maxSharePercent must be a number in (0, 100].');
+    const { reservePercent, biasPercent, exhaustedPercent } = usage;
+    if (![reservePercent, biasPercent, exhaustedPercent].every(value => typeof value === 'number' && value >= 0 && value <= 100) || !(reservePercent <= biasPercent && biasPercent < exhaustedPercent))
+        bad('.usage must hold numbers with reservePercent <= biasPercent < exhaustedPercent, each within 0..100.');
+    return { ...doc, tiers, seats, balance, usage };
 }
-
 /** config.yaml `models` — {tiers?, seats?, balance?, usage?}; the shipped defaults make every key optional. */
-export function validateModelsBlock(config,profile){
-  refuseRemovedKeys(config);
-  const models=config?.models;
-  if(models===undefined||models===null)return;
-  const bad=invalid('models');
-  if(!plain(models)||Object.keys(models).some(key=>!MODELS_KEYS.includes(key)))bad(` must be {${MODELS_KEYS.map(key=>key+'?').join(', ')}} or null (unknown keys are refused).`);
-  if(models.tiers!==undefined&&!plain(models.tiers))bad('.tiers must map tier names to ordered member lists.');
-  for(const key of ['seats','balance','usage'])if(models[key]!==undefined&&!plain(models[key]))bad(`.${key} must be a mapping.`);
-  effectiveTiers(config,profile);
+export function validateModelsBlock(config, profile) {
+    refuseRemovedKeys(config);
+    const models = config?.models;
+    if (models === undefined || models === null)
+        return;
+    const bad = invalid('models');
+    if (!plain(models) || Object.keys(models).some(key => !MODELS_KEYS.includes(key)))
+        return bad(` must be {${MODELS_KEYS.map(key => key + '?').join(', ')}} or null (unknown keys are refused).`);
+    if (models.tiers !== undefined && !plain(models.tiers))
+        bad('.tiers must map tier names to ordered member lists.');
+    for (const key of ['seats', 'balance', 'usage'])
+        if (models[key] !== undefined && !plain(models[key]))
+            bad(`.${key} must be a mapping.`);
+    effectiveTiers(config, profile);
 }

package/runtime/engine/orca-config.d.mts

@@ -0,0 +1,26 @@
+/**
+ * config.yaml `orca` — the owner's Orca app settings the runtime must know. maxWorkerDepth is the deepest worker Orca
+ * lets start under the owner's chat (chat = depth 0, a Kernel or the [Supervisor] 1, an op or a [Worker] 2, the draw
+ * critic 3); a deeper worker-start is refused by Orca with nested_worker_depth_exceeded. Orca exposes no read of that
+ * setting, so it is declared here and MUST equal the Orca app setting: scripts/agent/lib.mjs spawnAgent refuses a launch
+ * deeper than it before worker-start (worker-depth-exceeded), and `start --check` with STARCI_ORCA_LIVE=1 compares it with
+ * a measured probe (scripts/agent/depth-probe.mjs).
+ */
+export declare const ORCA_DEFAULTS: Readonly<{
+    maxWorkerDepth: 4;
+}>;
+/** The validated config.yaml `orca` block. */
+export interface OrcaBlock {
+    maxWorkerDepth?: number | null;
+}
+/** The keys of the orca block. */
+export declare const ORCA_KEYS: readonly string[];
+export declare const MAX_WORKER_DEPTH_CEILING = 16;
+export declare function validateOrca(orca: unknown): void;
+/** The owner's Orca settings: {maxWorkerDepth, source: 'orca'|'default'}. An absent or null block or key is the default. */
+export declare function orcaSettings(config?: {
+    orca?: OrcaBlock | null;
+} | null): {
+    maxWorkerDepth: number;
+    source: 'orca' | 'default';
+};

package/runtime/engine/orca-config.mjs

@@ -1,6 +1,5 @@
-import {isPlainObject as plain} from './plain-object.mjs';
-import {invalid} from './invalid-config.mjs';
-
+import { isPlainObject as plain } from './plain-object.mjs';
+import { invalid } from './invalid-config.mjs';
 /**
  * config.yaml `orca` — the owner's Orca app settings the runtime must know. maxWorkerDepth is the deepest worker Orca
  * lets start under the owner's chat (chat = depth 0, a Kernel or the [Supervisor] 1, an op or a [Worker] 2, the draw
@@ -9,21 +8,27 @@ import {invalid} from './invalid-config.mjs';
  * deeper than it before worker-start (worker-depth-exceeded), and `start --check` with STARCI_ORCA_LIVE=1 compares it with
  * a measured probe (scripts/agent/depth-probe.mjs).
  */
-export const ORCA_DEFAULTS=Object.freeze({maxWorkerDepth:4});
+export const ORCA_DEFAULTS = Object.freeze({ maxWorkerDepth: 4 });
 /** The keys of the orca block. */
-export const ORCA_KEYS=Object.freeze(Object.keys(ORCA_DEFAULTS));
-export const MAX_WORKER_DEPTH_CEILING=16;
-export function validateOrca(orca){
-  if(orca===null)return;
-  const bad=invalid('orca');
-  if(!plain(orca))bad(' must be {maxWorkerDepth?} or null.');
-  for(const key of Object.keys(orca))if(!ORCA_KEYS.includes(key))bad(` has unknown key ${key} (allowed: ${ORCA_KEYS.join(', ')}).`);
-  const v=orca.maxWorkerDepth;
-  if(v!==undefined&&v!==null&&!(Number.isInteger(v)&&v>=1&&v<=MAX_WORKER_DEPTH_CEILING))bad(`.maxWorkerDepth must be an integer from 1 to ${MAX_WORKER_DEPTH_CEILING} equal to the Orca app's worker depth setting (default ${ORCA_DEFAULTS.maxWorkerDepth}), or null.`);
+export const ORCA_KEYS = Object.freeze(Object.keys(ORCA_DEFAULTS));
+export const MAX_WORKER_DEPTH_CEILING = 16;
+export function validateOrca(orca) {
+    if (orca === null)
+        return;
+    const bad = invalid('orca');
+    if (!plain(orca))
+        return bad(' must be {maxWorkerDepth?} or null.');
+    for (const key of Object.keys(orca))
+        if (!ORCA_KEYS.includes(key))
+            bad(` has unknown key ${key} (allowed: ${ORCA_KEYS.join(', ')}).`);
+    const v = orca.maxWorkerDepth;
+    if (v !== undefined && v !== null && !(typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= MAX_WORKER_DEPTH_CEILING))
+        bad(`.maxWorkerDepth must be an integer from 1 to ${MAX_WORKER_DEPTH_CEILING} equal to the Orca app's worker depth setting (default ${ORCA_DEFAULTS.maxWorkerDepth}), or null.`);
 }
 /** The owner's Orca settings: {maxWorkerDepth, source: 'orca'|'default'}. An absent or null block or key is the default. */
-export function orcaSettings(config){
-  if(config?.orca!==undefined)validateOrca(config.orca);
-  const value=plain(config?.orca)?config.orca.maxWorkerDepth:null;
-  return Number.isInteger(value)?{maxWorkerDepth:value,source:'orca'}:{maxWorkerDepth:ORCA_DEFAULTS.maxWorkerDepth,source:'default'};
+export function orcaSettings(config) {
+    if (config?.orca !== undefined)
+        validateOrca(config.orca);
+    const value = plain(config?.orca) ? config.orca.maxWorkerDepth : null;
+    return typeof value === 'number' && Number.isInteger(value) ? { maxWorkerDepth: value, source: 'orca' } : { maxWorkerDepth: ORCA_DEFAULTS.maxWorkerDepth, source: 'default' };
 }

package/runtime/engine/plain-object.d.mts

@@ -0,0 +1,2 @@
+/** True for a non-null, non-array object. Does not check the prototype (a JSON.parse result). */
+export declare const isPlainObject: <T>(value: T) => value is T & Record<string, unknown>;

package/runtime/engine/refuse.d.mts

@@ -0,0 +1,9 @@
+/** An Error carrying `code` and `extra` fields; callers `throw` it or hand it to a result row. */
+export type Refusal<E extends object = object> = Error & {
+    code: string | undefined;
+} & E;
+export declare const refuse: <E extends object = object>(message: string, code?: string, extra?: E) => Refusal<E>;
+/** Throws the refusal `refuse` builds — the spelling used where refusing is the whole statement. */
+export declare function fail(message: string, code?: string, extra?: object): never;
+/** Throws `refuse(message, code)` when `ok` is falsy — the assertion spelling of a refusal. */
+export declare function need(ok: unknown, message: string, code?: string): asserts ok;

package/runtime/engine/refuse.mjs

@@ -1,11 +1,8 @@
 // refuse.mjs — the refusal Error every verb raises: a message plus a stable `code` (and any extra fields the
 // caller attaches). `refuse` builds it, `fail` throws it, `need` throws it when a required condition is false.
-
-/** An Error carrying `code` and `extra` fields; callers `throw` it or hand it to a result row. */
 export const refuse = (message, code, extra = {}) => Object.assign(new Error(message), { code, ...extra });
-
 /** Throws the refusal `refuse` builds — the spelling used where refusing is the whole statement. */
-export const fail = (message, code, extra = {}) => { throw refuse(message, code, extra); };
-
+export function fail(message, code, extra = {}) { throw refuse(message, code, extra); }
 /** Throws `refuse(message, code)` when `ok` is falsy — the assertion spelling of a refusal. */
-export const need = (ok, message, code) => { if (!ok) throw refuse(message, code); };
+export function need(ok, message, code) { if (!ok)
+    throw refuse(message, code); }