@entrorove/skill 0.1.22 → 0.1.24

package/local-formula-engine.mjs

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { Decimal, DECIMAL_POLICY, formulaError } from './local-decimal.mjs';
+import { compileFormulaGraph, evaluateFormulaGraph, formulaKey, formulaObject } from './local-formula-ast.mjs';
+
+export const FORMULA_SCHEMA = 'entrorove.formula-engine/1.0';
+export const FORMULA_RUNTIME_VERSION = 'decimal28-ast/1.0';
+const TYPES = ['number', 'integer', 'money', 'percent', 'text', 'date', 'enum'];
+const NUMERIC = TYPES.slice(0, 4);
+const ID = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+const VERSION = /^\d+\.\d+\.\d+$/;
+
+export function formulaCanonical(value) {
+  if (Array.isArray(value)) return `[${value.map(formulaCanonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${formulaCanonical(value[key])}`).join(',')}}`;
+  const json = JSON.stringify(value);
+  if (json === undefined || (typeof value === 'number' && !Number.isFinite(value))) throw formulaError('FORMULA_JSON_INVALID', 'formula artifacts must contain finite JSON values');
+  return json;
+}
+export const formulaDigest = value => createHash('sha256').update(typeof value === 'string' || ArrayBuffer.isView(value) ? value : formulaCanonical(value)).digest('hex');
+function cloned(value) { return JSON.parse(formulaCanonical(value)); }
+function requiredText(value, field) {
+  if (typeof value !== 'string' || !value.trim()) throw formulaError('ENGINE_REQUIRED_FIELD', `${field} is required`);
+}
+export function normalizeEngine(engine) {
+  formulaObject(engine, 'engine');
+  if (engine.schemaVersion !== 'engine.spec/1') throw formulaError('ENGINE_SCHEMA_VERSION', 'Expected engine.spec/1');
+  if (typeof engine.engineId !== 'string' || !ID.test(engine.engineId)) throw formulaError('ENGINE_ID_INVALID', 'engineId must be an explicit stable lowercase identifier');
+  requiredText(engine.name, 'name');
+  if (typeof engine.semanticVersion !== 'string' || !VERSION.test(engine.semanticVersion)) throw formulaError('ENGINE_VERSION_INVALID', 'semanticVersion must be major.minor.patch');
+  if (engine.decimalPolicy !== 'decimal-string' && formulaCanonical(engine.decimalPolicy ?? null) !== formulaCanonical(DECIMAL_POLICY)) throw formulaError('DECIMAL_POLICY_INVALID', 'engine requires Decimal28 decimal-string with half-away-from-zero rounding');
+  for (const field of ['fields', 'formulas', 'rules', 'views', 'testSuites', 'importProfiles']) {
+    if (!Array.isArray(engine[field])) throw formulaError('ENGINE_REQUIRED_ARRAY', `${field} must be an array`);
+  }
+  if (!engine.fields.length || !engine.formulas.length || engine.fields.length > 1000) throw formulaError('ENGINE_EMPTY', 'engine requires 1..1000 fields and 1..1000 formulas');
+  const keys = new Set();
+  for (const field of engine.fields) {
+    formulaObject(field, 'field'); const key = formulaKey(field.key);
+    if (keys.has(key)) throw formulaError('FIELD_DUPLICATE_KEY', `duplicate field key ${key}`);
+    keys.add(key); requiredText(field.label, 'field label');
+    if (!TYPES.includes(field.type)) throw formulaError('FIELD_TYPE_INVALID', 'unsupported field type');
+    if (NUMERIC.includes(field.type) && typeof field.unit !== 'string') throw formulaError('FIELD_UNIT_MISSING', 'numeric fields require an explicit unit');
+    if (field.required !== undefined && typeof field.required !== 'boolean') throw formulaError('FIELD_REQUIRED_INVALID', 'field required must be boolean');
+  }
+  const graph = compileFormulaGraph(engine.formulas, [...keys]);
+  for (const item of graph.formulas) for (const ref of graph.dependencies[item.key]) {
+    const field = engine.fields.find(entry => entry.key === ref);
+    if (field && !NUMERIC.includes(field.type)) throw formulaError('FORMULA_REF_TYPE', `formula reference ${ref} must be numeric`);
+  }
+  const normalized = cloned(engine);
+  normalized.formulas = engine.formulas.map(item => ({ ...cloned(item), expression: graph.formulas.find(entry => entry.key === item.key).expression }));
+  return { engine: normalized, graph };
+}
+export function validateFormulaEngine(engine) {
+  try { normalizeEngine(engine); return []; }
+  catch (cause) { return [{ severity: 'P0', ruleId: cause.code ?? 'ENGINE_INVALID', entityRef: 'engine', message: cause.message }]; }
+}
+export function buildFormulaEngine(requirements) {
+  formulaObject(requirements, 'requirements'); requiredText(requirements.goal, 'goal');
+  if (!Array.isArray(requirements.inputs) || !Array.isArray(requirements.formulas)) throw formulaError('COMPILE_REQUIREMENTS', 'inputs and formulas are required arrays');
+  const engine = {
+    schemaVersion: 'engine.spec/1', engineId: requirements.engineId, name: requirements.name ?? requirements.goal,
+    semanticVersion: requirements.semanticVersion ?? '1.0.0', status: 'draft', compatibilityProfile: 'legacy-compatible',
+    decimalPolicy: requirements.decimalPolicy ?? 'decimal-string', defaultLocale: requirements.defaultLocale ?? 'zh-CN',
+    category: requirements.category ?? 'general', inputMethod: requirements.inputMethod ?? 'manual', output: requirements.output ?? ['metric-cards'],
+    constraints: requirements.constraints ?? '', fields: requirements.inputs, formulas: requirements.formulas,
+    rules: requirements.rules ?? [], views: requirements.views ?? [], importProfiles: requirements.importProfiles ?? [],
+    reports: requirements.reports ?? [], testSuites: requirements.testSuites ?? [], acceptance: requirements.acceptance ?? '',
+  };
+  return normalizeEngine(engine).engine;
+}
+export function compileFormulaEngine(engine) {
+  const normalized = normalizeEngine(engine);
+  const program = { schemaVersion: FORMULA_SCHEMA, runtimeVersion: FORMULA_RUNTIME_VERSION, decimalPolicy: DECIMAL_POLICY,
+    engineId: normalized.engine.engineId, engineVersion: normalized.engine.semanticVersion,
+    engineDigest: formulaDigest(normalized.engine), engine: normalized.engine,
+    formulas: normalized.graph.formulas, dependencies: normalized.graph.dependencies, order: normalized.graph.order };
+  return { ...program, programDigest: formulaDigest(program) };
+}
+export function verifyFormulaProgram(program, expected = {}) {
+  formulaObject(program, 'compiled formula program');
+  if (program.runtimeVersion !== FORMULA_RUNTIME_VERSION || program.schemaVersion !== FORMULA_SCHEMA) throw formulaError('FORMULA_RUNTIME_VERSION', 'compiled formula runtime version is unsupported');
+  const compiled = compileFormulaEngine(program.engine);
+  if (formulaCanonical(compiled) !== formulaCanonical(program)) throw formulaError('FORMULA_ARTIFACT_BINDING', 'compiled formula artifact or digest does not match its engine');
+  for (const field of ['engineDigest', 'programDigest', 'engineId', 'engineVersion']) {
+    if (expected[field] !== undefined && expected[field] !== compiled[field]) throw formulaError('FORMULA_ARTIFACT_BINDING', `${field} does not match the required engine binding`);
+  }
+  return compiled;
+}
+export function evaluateFormulaProgram(program, inputs = {}, expected = {}) {
+  const verified = verifyFormulaProgram(program, expected); formulaObject(inputs, 'engine inputs');
+  const fields = new Map(verified.engine.fields.map(item => [item.key, item]));
+  for (const [key, value] of Object.entries(inputs)) {
+    const field = fields.get(key);
+    if (!field) throw formulaError('ENGINE_INPUT_UNKNOWN', `unknown input field: ${key}`);
+    if (NUMERIC.includes(field.type)) {
+      const decimal = Decimal.from(value);
+      if (field.type === 'integer' && decimal.scale !== 0) throw formulaError('ENGINE_INPUT_INTEGER', `${key} must be an integer`);
+    } else if (typeof value !== 'string') throw formulaError('ENGINE_INPUT_TYPE', `${key} must be text`);
+  }
+  for (const field of fields.values()) if (field.required && (!Object.hasOwn(inputs, field.key) || inputs[field.key] === '' || inputs[field.key] === null)) throw formulaError('MISSING_INPUT', `missing input: ${field.key}`, { fieldId: field.key });
+  return evaluateFormulaGraph(verified.formulas, Object.fromEntries(Object.entries(inputs).filter(([key]) => NUMERIC.includes(fields.get(key).type))));
+}
+export function formulaImpact(program, changedKeys) {
+  const verified = verifyFormulaProgram(program);
+  if (!Array.isArray(changedKeys) || !changedKeys.length) throw formulaError('FORMULA_IMPACT_INVALID', 'changedKeys must be a non-empty array');
+  const known = new Set([...verified.engine.fields.map(item => item.key), ...verified.formulas.map(item => item.key)]);
+  const affected = new Set(changedKeys.map(formulaKey));
+  for (const key of affected) if (!known.has(key)) throw formulaError('FORMULA_REF_UNKNOWN', `unknown changed key: ${key}`);
+  for (const key of verified.order) if (verified.dependencies[key].some(ref => affected.has(ref))) affected.add(key);
+  return verified.order.filter(key => affected.has(key));
+}

package/local-formula-tests.mjs

@@ -0,0 +1,61 @@
+import { Decimal, formulaError } from './local-decimal.mjs';
+import { formulaObject } from './local-formula-ast.mjs';
+import { compileFormulaEngine, verifyFormulaProgram, evaluateFormulaProgram, formulaCanonical, formulaDigest } from './local-formula-engine.mjs';
+export const FORMULA_GATE_SCHEMA = 'entrorove.calctool-final-gate/1.0';
+
+function suiteValue(suite, primary, alias) {
+  if (Object.hasOwn(suite, primary) && Object.hasOwn(suite, alias) && formulaCanonical(suite[primary]) !== formulaCanonical(suite[alias])) throw formulaError('FORMULA_SUITE_ALIAS', `conflicting ${primary}/${alias} test values`);
+  const value = suite[primary] ?? suite[alias]; formulaObject(value, `test ${primary}`); return value;
+}
+function runSuite(program, suite, index) {
+  formulaObject(suite, 'test suite');
+  const expected = suiteValue(suite, 'expected', 'expect');
+  const inputs = suiteValue(suite, 'input', 'inputs');
+  const keys = Object.keys(expected);
+  if (!keys.length) throw formulaError('FORMULA_TEST_EMPTY', 'test suites must assert at least one formula result');
+  const known = new Set(program.formulas.map(item => item.key));
+  for (const key of keys) if (!known.has(key)) throw formulaError('FORMULA_TEST_KEY_UNKNOWN', `test expectation references unknown formula: ${key}`);
+  const actual = evaluateFormulaProgram(program, inputs);
+  const mismatches = keys.flatMap(key => {
+    const want = Decimal.from(expected[key]).toString();
+    return actual[key] === want ? [] : [{ key, expected: want, actual: actual[key] }];
+  });
+  return { name: suite.name ?? `suite-${index + 1}`, passed: mismatches.length === 0, keys, actual, mismatches };
+}
+export function formulaFinalGate(engine, options = {}) {
+  const started = Date.now(); const findings = []; const tests = []; let program;
+  try { program = compileFormulaEngine(engine); }
+  catch (cause) { findings.push({ severity: 'P0', ruleId: cause.code ?? 'ENGINE_INVALID', entityRef: 'engine', message: cause.message }); }
+  if (program) {
+    const suites = program.engine.testSuites;
+    if (!suites.length) findings.push({ severity: 'P1', ruleId: 'FORMULA_TESTS_EMPTY', entityRef: 'testSuites', message: 'no runnable benchmark samples' });
+    for (const [index, suite] of suites.entries()) {
+      try {
+        const result = runSuite(program, suite, index); tests.push(result);
+        if (!result.passed) findings.push({ severity: 'P1', ruleId: 'FORMULA_TEST_FAIL', entityRef: `testSuites[${index}]`, message: 'formula test expectation mismatch', mismatches: result.mismatches });
+      } catch (cause) {
+        tests.push({ name: suite?.name ?? `suite-${index + 1}`, passed: false, code: cause.code ?? 'FORMULA_TEST_ERROR', message: cause.message });
+        findings.push({ severity: 'P1', ruleId: cause.code ?? 'FORMULA_TEST_ERROR', entityRef: `testSuites[${index}]`, message: cause.message });
+      }
+    }
+    const coverage = new Set(tests.filter(item => item.passed).flatMap(item => item.keys));
+    for (const formula of program.formulas) if (!coverage.has(formula.key)) findings.push({ severity: 'P1', ruleId: 'FORMULA_TEST_UNCOVERED', entityRef: formula.key, message: 'formula has no passing expectation' });
+  }
+  const passed = findings.length === 0;
+  const artifact = { schemaVersion: 'entrorove.formula-test-result/1.0', programDigest: program?.programDigest ?? null, findings, tests };
+  const artifactSha256 = formulaDigest(artifact);
+  const subject = { schemaVersion: 'entrorove.formula-execution-subject/1.0', engineId: engine?.engineId ?? null,
+    engineVersion: program?.engineVersion ?? null, runtimeVersion: program?.runtimeVersion ?? null,
+    engineDigest: program?.engineDigest ?? null, programDigest: program?.programDigest ?? null, artifactSha256,
+    flowId: options.flowId ?? null, stepId: options.stepId ?? null };
+  const evidence = { schemaVersion: 'entrorove.test-evidence/2.0', evidenceId: `formula-${artifactSha256}`,
+    kind: 'test', runner: 'local', command: 'entrorove local formula-final-gate', exitCode: passed ? 0 : 2,
+    durationMs: Math.max(0, Date.now() - started), summary: `${tests.filter(item => item.passed).length}/${tests.length} formula suites passed`,
+    artifactSha256, subject, subjectDigest: formulaDigest(subject),
+    ...(options.flowId ? { flowId: options.flowId } : {}), ...(options.stepId ? { stepId: options.stepId } : {}) };
+  return { schemaVersion: FORMULA_GATE_SCHEMA, status: passed ? 'incomplete' : 'blocked', authority: 'local',
+    computationsPassed: passed, findings, tests, engineId: engine?.engineId ?? null, artifact, evidence: [evidence],
+    ...(program ? { programDigest: program.programDigest, engineDigest: program.engineDigest, engineVersion: program.engineVersion, runtimeVersion: program.runtimeVersion } : {}),
+    guarantee: passed ? 'formula-tests-passed-awaiting-independent-validator' : 'formula-tests-blocked' };
+}
+export function verifyFormulaTests(program, options = {}) { return formulaFinalGate(verifyFormulaProgram(program).engine, options); }

package/local-formula.mjs

@@ -1,130 +1,30 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-
-export const FORMULA_SCHEMA = 'entrorove.formula-engine/1.0';
-export const FORMULA_GATE_SCHEMA = 'entrorove.calctool-final-gate/1.0';
-const MAX_SCALE = 28;
-const DECIMAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
-const SHA256 = /^[0-9a-f]{64}$/;
-
-function error(code, message, details = {}) {
-  const value = new Error(message); value.code = code; Object.assign(value, details); return value;
-}
-function ten(power) { return 10n ** BigInt(power); }
-function normalize(coefficient, scale) {
-  while (scale > 0 && coefficient % 10n === 0n) { coefficient /= 10n; scale -= 1; }
-  return { coefficient, scale };
+import { readBudgetedProjectFile } from './local-budget-reads.mjs';
+import { formulaError } from './local-decimal.mjs';
+import { formulaDigest } from './local-formula-engine.mjs';
+import { formulaFinalGate } from './local-formula-tests.mjs';
+
+export { Decimal, Decimal28, DECIMAL_POLICY } from './local-decimal.mjs';
+export { evaluateFormula, evaluateFormulaGraph, compileFormulaGraph, FORMULA_OPERATORS } from './local-formula-ast.mjs';
+export { FORMULA_SCHEMA, FORMULA_RUNTIME_VERSION, compileFormulaEngine, verifyFormulaProgram,
+  evaluateFormulaProgram, buildFormulaEngine, validateFormulaEngine, formulaImpact } from './local-formula-engine.mjs';
+export { FORMULA_GATE_SCHEMA, formulaFinalGate, verifyFormulaTests } from './local-formula-tests.mjs';
+
+export async function readFormulaFile(input, relativePath = input.enginePath) {
+  if (typeof input?.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) throw formulaError('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
+  if (typeof relativePath !== 'string' || relativePath.normalize('NFC') !== relativePath || path.isAbsolute(relativePath)
+    || /[\u0000-\u001f\u007f]/.test(relativePath) || /^[A-Za-z]:/.test(relativePath)
+    || relativePath.split('/').some(part => !part || part === '.' || part === '..' || part.includes('\\'))) throw formulaError('FORMULA_PATH_INVALID', 'enginePath must be a safe relative file path');
+  const root = await fs.realpath(input.repositoryRoot); const target = path.resolve(root, ...relativePath.split('/'));
+  const stat = await fs.lstat(target);
+  if (!stat.isFile() || stat.isSymbolicLink() || await fs.realpath(target) !== target) throw formulaError('FORMULA_FILE_INVALID', 'enginePath must be a regular file without symlinked ancestors');
+  const source = await readBudgetedProjectFile(input, target, { encoding: 'utf8', sourcePath: relativePath });
+  let engine;
+  try { engine = JSON.parse(source); } catch { throw formulaError('FORMULA_JSON_INVALID', 'enginePath is not valid JSON'); }
+  return { engine, sourceSha256: formulaDigest(source), path: relativePath };
 }
-function round(coefficient, fromScale, toScale) {
-  if (fromScale <= toScale) return coefficient * ten(toScale - fromScale);
-  const divisor = ten(fromScale - toScale); let quotient = coefficient / divisor; const remainder = coefficient % divisor;
-  if ((remainder < 0n ? -remainder : remainder) * 2n >= divisor) quotient += coefficient < 0n ? -1n : 1n;
-  return quotient;
-}
-
-export class Decimal {
-  constructor(value) {
-    if (value instanceof Decimal) { this.coefficient = value.coefficient; this.scale = value.scale; this.value = value.value; return; }
-    const source = String(value ?? '').trim();
-    if (!DECIMAL.test(source) || source === '' || /^(?:[+-]?)(?:nan|infinity)$/i.test(source)) throw error('INVALID_DECIMAL', `Invalid decimal: ${source}`);
-    const negative = source[0] === '-'; const unsigned = source.replace(/^[+-]/, ''); const [integer = '0', fraction = ''] = unsigned.split('.');
-    const digits = `${integer || '0'}${fraction}`.replace(/^0+(?=\d)/, '') || '0';
-    const raw = BigInt(digits) * (negative ? -1n : 1n); const boundedScale = Math.min(fraction.length, MAX_SCALE);
-    const normalized = normalize(round(raw, fraction.length, boundedScale), boundedScale); this.coefficient = normalized.coefficient; this.scale = normalized.scale;
-    this.value = Decimal.format(this.coefficient, this.scale);
-  }
-  static from(value) { return value instanceof Decimal ? value : new Decimal(value); }
-  static fromParts(coefficient, scale) { return new Decimal(Decimal.format(...Object.values(normalize(round(coefficient, scale, Math.min(scale, MAX_SCALE)), Math.min(scale, MAX_SCALE))))); }
-  static format(coefficient, scale) {
-    const negative = coefficient < 0n; const digits = (negative ? -coefficient : coefficient).toString().padStart(scale + 1, '0');
-    const text = scale === 0 ? digits : `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
-    return negative && coefficient !== 0n ? `-${text}` : text;
-  }
-  plus(other) { const right = Decimal.from(other); const scale = Math.max(this.scale, right.scale); return Decimal.fromParts(this.coefficient * ten(scale - this.scale) + right.coefficient * ten(scale - right.scale), scale); }
-  minus(other) { return this.plus(Decimal.from(other).negate()); }
-  negate() { return Decimal.fromParts(-this.coefficient, this.scale); }
-  times(other) { const right = Decimal.from(other); return Decimal.fromParts(this.coefficient * right.coefficient, this.scale + right.scale); }
-  div(other) {
-    const right = Decimal.from(other); if (right.coefficient === 0n) throw error('DIV_ZERO', 'division by zero');
-    const numerator = this.coefficient * ten(right.scale + MAX_SCALE); const denominator = right.coefficient * ten(this.scale); let quotient = numerator / denominator; const remainder = numerator % denominator;
-    if ((remainder < 0n ? -remainder : remainder) * 2n >= (denominator < 0n ? -denominator : denominator)) quotient += (numerator < 0n) !== (denominator < 0n) ? -1n : 1n;
-    return Decimal.fromParts(quotient, MAX_SCALE);
-  }
-  rounded(dp) { if (!Number.isInteger(dp) || dp < 0 || dp > MAX_SCALE) throw error('DECIMAL_SCALE_INVALID', 'decimal places must be 0..28'); return this.scale <= dp ? this : Decimal.fromParts(round(this.coefficient, this.scale, dp), dp); }
-  isZero() { return this.coefficient === 0n; }
-  toString() { return this.value; }
-}
-
-function requireNode(node) { if (!node || typeof node !== 'object' || Array.isArray(node)) throw error('FORMULA_NODE_INVALID', 'formula nodes must be objects'); }
-function requireArgs(node, count, exact = false) {
-  if (!Array.isArray(node.args) || (exact ? node.args.length !== count : node.args.length < count)) throw error('FORMULA_ARGS_INVALID', `${node.op} requires ${exact ? `exactly ${count}` : `at least ${count}`} arguments`);
-}
-
-export function evaluateFormula(node, values = {}) {
-  requireNode(node);
-  if (Object.hasOwn(node, 'ref')) {
-    if (typeof node.ref !== 'string' || !node.ref || values[node.ref] === undefined || values[node.ref] === null || values[node.ref] === '') throw error('MISSING_INPUT', `missing input: ${node.ref}`, { fieldId: node.ref });
-    return Decimal.from(values[node.ref]);
-  }
-  if (Object.hasOwn(node, 'lit')) return Decimal.from(node.lit);
-  const op = node.op; const args = node.args;
-  switch (op) {
-    case 'add': requireArgs(node, 1); return args.reduce((total, item) => total.plus(evaluateFormula(item, values)), Decimal.from('0'));
-    case 'sub': requireArgs(node, 2, true); return evaluateFormula(args[0], values).minus(evaluateFormula(args[1], values));
-    case 'mul': requireArgs(node, 1); return args.reduce((total, item) => total.times(evaluateFormula(item, values)), Decimal.from('1'));
-    case 'div': requireArgs(node, 2, true); return evaluateFormula(args[0], values).div(evaluateFormula(args[1], values));
-    case 'safeDivide': requireArgs(node, 2, true); { const denominator = evaluateFormula(args[1], values); return denominator.isZero() ? Decimal.from('0') : evaluateFormula(args[0], values).div(denominator); }
-    case 'percentOf': requireArgs(node, 2, true); return evaluateFormula(args[0], values).div(evaluateFormula(args[1], values)).times('100');
-    case 'round': requireArgs(node, 1, true); return evaluateFormula(args[0], values).rounded(2);
-    case 'if': requireArgs(node, 3, true); return evaluateFormula(args[0], values).isZero() ? evaluateFormula(args[2], values) : evaluateFormula(args[1], values);
-    default: throw error('UNSUPPORTED_OPERATOR', `Unsupported operator: ${String(op)}`);
-  }
-}
-
-function refs(node, output = []) {
-  requireNode(node); if (Object.hasOwn(node, 'ref')) output.push(node.ref); if (Array.isArray(node.args)) node.args.forEach(item => refs(item, output)); return output;
-}
-export function evaluateFormulaGraph(formulas, inputs = {}) {
-  if (!Array.isArray(formulas)) throw error('FORMULA_GRAPH_INVALID', 'formulas must be an array');
-  const values = Object.fromEntries(Object.entries(inputs).map(([key, value]) => [key, Decimal.from(value)])); const definitions = new Map();
-  for (const formula of formulas) { if (!formula || typeof formula.key !== 'string' || !formula.key || definitions.has(formula.key)) throw error('FORMULA_KEY_INVALID', 'formula keys must be unique non-empty strings'); definitions.set(formula.key, formula); }
-  const visiting = new Set(); const done = new Set();
-  const compute = key => {
-    if (done.has(key)) return values[key]; if (visiting.has(key)) throw error('FORMULA_CYCLE', `formula cycle at ${key}`); const formula = definitions.get(key); if (!formula) throw error('FORMULA_REF_UNKNOWN', `unknown formula: ${key}`);
-    visiting.add(key); for (const ref of refs(formula.expression)) if (definitions.has(ref)) compute(ref); const result = evaluateFormula(formula.expression, values); visiting.delete(key); done.add(key); values[key] = result; return result;
-  };
-  for (const key of definitions.keys()) compute(key);
-  return Object.fromEntries([...definitions.keys()].map(key => [key, values[key].toString()]));
-}
-
-function digest(value) { return value; }
-function engineFindings(engine) {
-  const findings = []; const formulas = Array.isArray(engine?.formulas) ? engine.formulas : [];
-  if (!formulas.length) findings.push({ severity: 'P1', ruleId: 'FORMULA_EMPTY', entityRef: 'formulas', message: 'no formulas declared' });
-  const known = new Set([...(engine?.fields ?? []).map(item => item?.key), ...formulas.map(item => item?.key)]);
-  for (const [index, formula] of formulas.entries()) {
-    if (!formula?.key || !formula?.expression) findings.push({ severity: 'P0', ruleId: 'FORMULA_DECLARATION', entityRef: `formulas[${index}]`, message: 'formula key and expression are required' });
-    try { for (const ref of refs(formula.expression)) if (!known.has(ref)) findings.push({ severity: 'P0', ruleId: 'FORMULA_REF_UNKNOWN', entityRef: `formulas[${index}]`, message: `unknown reference: ${ref}` }); } catch (cause) { findings.push({ severity: 'P0', ruleId: 'FORMULA_NODE_INVALID', entityRef: `formulas[${index}]`, message: cause.message }); }
-  }
-  return findings;
-}
-export function formulaFinalGate(engine, options = {}) {
-  const findings = engineFindings(engine); const formulas = Array.isArray(engine?.formulas) ? engine.formulas : []; const suites = Array.isArray(engine?.testSuites) ? engine.testSuites : [];
-  const tests = []; if (!suites.length) findings.push({ severity: 'P1', ruleId: 'FORMULA_TESTS_EMPTY', entityRef: 'testSuites', message: 'no runnable benchmark samples' });
-  for (const [index, suite] of suites.entries()) {
-    const expected = suite?.expected ?? suite?.expect ?? {}; const inputs = suite?.input ?? suite?.inputs ?? {}; let actual;
-    try { actual = evaluateFormulaGraph(formulas, inputs); } catch (cause) { findings.push({ severity: 'P1', ruleId: 'FORMULA_TEST_ERROR', entityRef: `testSuites[${index}]`, message: cause.message }); continue; }
-    const mismatches = []; for (const [key, expectedValue] of Object.entries(expected)) { try { if (Decimal.from(actual[key]).toString() !== Decimal.from(expectedValue).toString()) mismatches.push({ key, expected: String(expectedValue), actual: actual[key] }); } catch (cause) { mismatches.push({ key, expected: String(expectedValue), actual: actual[key], error: cause.message }); } }
-    tests.push({ name: suite.name ?? `suite-${index + 1}`, passed: mismatches.length === 0, mismatches }); if (mismatches.length) findings.push({ severity: 'P1', ruleId: 'FORMULA_TEST_FAIL', entityRef: `testSuites[${index}]`, message: 'formula test expectation mismatch', mismatches });
-  }
-  return { schemaVersion: FORMULA_GATE_SCHEMA, status: findings.some(item => item.severity === 'P0') ? 'blocked' : findings.length ? 'incomplete' : 'complete', authority: 'trusted-local-runner', findings, tests, engineId: engine?.engineId ?? null, guarantee: findings.length ? 'local-completion-gate-blocked' : 'local-completion-gate-green' };
-}
-
 export async function formulaFinalGateFile(input) {
-  if (typeof input?.repositoryRoot !== 'string' || !path.isAbsolute(input.repositoryRoot)) throw error('ENTROROVE_ROOT_INVALID', 'repositoryRoot must be absolute');
-  if (typeof input.enginePath !== 'string' || path.isAbsolute(input.enginePath) || input.enginePath.split('/').some(part => !part || part === '.' || part === '..' || part.includes('\\'))) throw error('FORMULA_PATH_INVALID', 'enginePath must be a safe relative file path');
-  const root = await fs.realpath(input.repositoryRoot); const target = path.resolve(root, ...input.enginePath.split('/')); const relative = path.relative(root, target); if (relative.startsWith('..') || path.isAbsolute(relative)) throw error('FORMULA_PATH_ESCAPE', 'enginePath escapes repositoryRoot');
-  const stat = await fs.lstat(target); if (!stat.isFile() || stat.isSymbolicLink()) throw error('FORMULA_FILE_INVALID', 'enginePath must be a regular file'); const source = await fs.readFile(target, 'utf8');
-  let engine; try { engine = JSON.parse(source); } catch (cause) { throw error('FORMULA_JSON_INVALID', `enginePath is not valid JSON: ${cause.message}`); }
-  return { ...formulaFinalGate(engine, input), enginePath: input.enginePath, engineSha256: (await import('node:crypto')).createHash('sha256').update(source).digest('hex') };
+  const loaded = await readFormulaFile(input);
+  return { ...formulaFinalGate(loaded.engine, input), enginePath: loaded.path, engineSha256: loaded.sourceSha256 };
 }

package/local-integrity.mjs

@@ -1,10 +1,10 @@
+import { inspectLegacyArchguardPreflight } from './local-merge-archguard-verification.mjs';
 import { createHash, createPublicKey, verify } from 'node:crypto';
+import { verifyTestEvidence } from './local-evidence-verification.mjs';
 
 export const ARCHGUARD_PREFLIGHT_SCHEMA = 'entrorove.archguard-preflight/1.0';
 export const RUNNER_RECEIPT_SCHEMA = 'entrorove.runner-receipt/1.0';
-const EXECUTION_RECEIPT_SCHEMA = 'validator.execution-receipt/1.0';
 const SNAPSHOT_SCHEMA = 'entrorove.snapshot/1.0';
-const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const SHA256 = /^[0-9a-f]{64}$/;
 const REPOSITORY_DIGEST = /^[0-9a-f]{32}$/;
 const SAFE_PATH = /^(?!.*[\\\u0000-\u001f\u007f])(?!.*(?:^|\/)(?:\.|\.\.)(?:\/|$))[^/]+(?:\/[^/]+)*$/;
@@ -21,6 +21,17 @@ export function sha256(value) {
   return createHash('sha256').update(value).digest('hex');
 }
 
+export function snapshotHandoffBinding(value) {
+  if (!Object.hasOwn(value, 'handoffEpoch') && !Object.hasOwn(value, 'handoffBaselineReceiptDigest')) return {};
+  if (!Object.hasOwn(value, 'handoffEpoch') || !Object.hasOwn(value, 'handoffBaselineReceiptDigest')
+    || !Number.isSafeInteger(value.handoffEpoch) || value.handoffEpoch < 0
+    || (value.handoffBaselineReceiptDigest !== null && (typeof value.handoffBaselineReceiptDigest !== 'string'
+      || !SHA256.test(value.handoffBaselineReceiptDigest)))) {
+    throw new Error('Snapshot handoff epoch and baseline receipt binding are invalid');
+  }
+  return { handoffEpoch: value.handoffEpoch, handoffBaselineReceiptDigest: value.handoffBaselineReceiptDigest };
+}
+
 export function verifySnapshotManifest(manifest, binding) {
   if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)
     || manifest.schemaVersion !== SNAPSHOT_SCHEMA || manifest.snapshotId !== binding.snapshotId
@@ -37,6 +48,8 @@ export function verifySnapshotManifest(manifest, binding) {
   }
   const core = { snapshotId: manifest.snapshotId, flowId: manifest.flowId, stepId: manifest.stepId,
     paths: manifest.paths, files: manifest.files, contractDigest: manifest.contractDigest };
+  try { Object.assign(core, snapshotHandoffBinding(manifest)); }
+  catch { return { verified: false, reason: 'snapshot handoff binding is invalid' }; }
   return manifest.snapshotDigest === sha256(canonical(core))
     ? { verified: true } : { verified: false, reason: 'snapshot manifest digest is invalid' };
 }
@@ -67,49 +80,17 @@ function bindingMismatch(attestation, binding) {
     || attestation.snapshotDigest !== binding.snapshotDigest || attestation.contractDigest !== binding.contractDigest;
 }
 
-function verifyExecutionReceipt(receipt, evidence, binding) {
-  if (!receipt || receipt.schemaVersion !== EXECUTION_RECEIPT_SCHEMA || receipt.subjectDigest !== evidence.subjectDigest
-    || !ID.test(String(receipt.nonce ?? '')) || !receipt.result || receipt.result.runner !== 'trusted-runner' || typeof receipt.result.passed !== 'boolean'
-    || receipt.result.exitCode !== evidence.exitCode || receipt.result.durationMs !== evidence.durationMs || receipt.result.summary !== evidence.summary) throw new Error('Trusted execution receipt is not bound');
-  const issuedAt = Date.parse(String(receipt.issuedAt ?? '')); const expiresAt = Date.parse(String(receipt.expiresAt ?? ''));
-  if (!Number.isFinite(issuedAt) || !Number.isFinite(expiresAt) || issuedAt > Date.now() + 60_000 || expiresAt <= Date.now() || expiresAt <= issuedAt || expiresAt - issuedAt > 600_000) throw new Error('Trusted execution receipt lifetime is invalid');
-  const unsigned = Object.fromEntries(Object.entries(receipt).filter(([key]) => key !== 'signature'));
-  if (typeof binding.receiptPublicKey !== 'string') throw new Error('Trusted execution receipt public key is required');
-  return verifyReceipt(receipt, unsigned, { schemaVersion: EXECUTION_RECEIPT_SCHEMA, publicKey: binding.receiptPublicKey });
-}
-
 export function verifyArchguardPreflight(attestation, binding) {
-  if (!attestation || typeof attestation !== 'object' || Array.isArray(attestation)
-    || attestation.schemaVersion !== ARCHGUARD_PREFLIGHT_SCHEMA || attestation.status !== 'passed'
-    || bindingMismatch(attestation, binding) || !attestation.receipt) {
-    return { verified: false, reason: 'ArchGuard preflight is missing or not bound to this flow, step, snapshot, and contract' };
-  }
-  const unsigned = Object.fromEntries(Object.entries(attestation).filter(([key]) => key !== 'receipt'));
-  try {
-    const receipt = verifyReceipt(attestation.receipt, unsigned);
-    return { verified: true, attestation, keyId: receipt.keyId };
-  } catch (error) {
-    return { verified: false, reason: error instanceof Error ? error.message : String(error) };
-  }
+  return inspectLegacyArchguardPreflight(attestation, binding);
 }
 
-export function verifyTrustedEvidence(evidence, binding) {
-  if (!evidence || evidence.runner !== 'trusted-runner' || !evidence.subject
-    || evidence.subject.schemaVersion !== 'validator.validation-subject/1.0'
-    || evidence.subject.chainId !== binding.flowId || evidence.subject.validationRunId !== binding.stepId
-    || evidence.subjectDigest !== sha256(canonical(evidence.subject))
-    || evidence.subject.snapshotDigest !== binding.snapshotDigest
-    || evidence.subject.contractDigest !== binding.contractDigest) {
-    return { verified: false, reason: 'trusted evidence subject is not bound to this flow, step, snapshot, and contract' };
-  }
-  const unsigned = Object.fromEntries(Object.entries(evidence).filter(([key]) => key !== 'receipt'));
-  try {
-    const receipt = evidence.receipt?.schemaVersion === EXECUTION_RECEIPT_SCHEMA
-      ? verifyExecutionReceipt(evidence.receipt, evidence, binding) : verifyReceipt(evidence.receipt, unsigned);
-    return { verified: true, evidence, keyId: receipt.keyId };
-  } catch (error) {
-    return { verified: false, reason: error instanceof Error ? error.message : String(error) };
+export function verifyTrustedEvidence(evidence, binding = {}) {
+  const publicKey = process.env.ENTROROVE_VALIDATOR_RECEIPT_PUBLIC_KEY?.trim();
+  if (publicKey && binding.receiptPublicKey !== undefined && binding.receiptPublicKey !== publicKey) {
+    return { verified: false, authentic: false, successful: false, status: 'blocked', evidenceState: 'blocked',
+      code: 'ENTROROVE_EVIDENCE_KEY', reason: 'Supplied receipt key does not match independent verifier configuration' };
   }
+  return verifyTestEvidence(evidence, { publicKey, binding, requireBinding: true });
 }
 
 export function assertGreen(value, label) {

package/local-invocations.mjs

@@ -0,0 +1,107 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { withStateLock } from './local-state-lock.mjs';
+
+const SHA = /^[a-f0-9]{64}$/;
+const UUID = /^[a-f0-9-]{36}$/;
+const ID = /^[a-z][a-z0-9-]{0,63}$/;
+const COUNTS = ['inputTokens', 'outputTokens', 'durationMs'];
+const events = new Set(['started', 'completed', 'rejected', 'outcome-unknown', 'not-sent', 'status']);
+
+function receipt(value, requestId) {
+  if (!value || !UUID.test(value.usageId) || value.requestId !== requestId
+    || !['pending', 'recorded', 'unknown'].includes(value.state)
+    || !['runtime', 'model'].includes(value.meterKind)
+    || !['not-applicable', 'reported', 'unknown'].includes(value.tokenStatus)) throw new Error('Invalid original request usage receipt');
+  const clean = { usageId: value.usageId, requestId, meterKind: value.meterKind,
+    state: value.state, tokenStatus: value.tokenStatus };
+  for (const key of COUNTS) {
+    if (value[key] !== null && (!Number.isSafeInteger(value[key]) || value[key] < 0)) throw new Error('Invalid original request usage measurement');
+    clean[key] = value[key];
+  }
+  if (value.tokenStatus === 'unknown' && (value.inputTokens !== null || value.outputTokens !== null)) throw new Error('Unknown token usage must not report zero');
+  for (const key of ['providerId', 'modelId']) {
+    if (value[key] !== null && (typeof value[key] !== 'string' || !/^[A-Za-z0-9._:/-]{1,128}$/.test(value[key]))) {
+      throw new Error('Invalid original request model identity');
+    }
+    clean[key] = value[key];
+  }
+  return clean;
+}
+
+async function ledgerFile(home) {
+  if (typeof home !== 'string' || !path.isAbsolute(home)) throw new Error('Invocation ledger home must be absolute');
+  const root = await fs.realpath(home);
+  const directory = path.join(root, '.entrorove');
+  await fs.mkdir(directory, { mode: 0o700 }).catch(cause => { if (cause.code !== 'EEXIST') throw cause; });
+  const stat = await fs.lstat(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || process.platform !== 'win32' && stat.uid !== process.getuid()) {
+    throw new Error('Invocation ledger requires an owned real directory');
+  }
+  if (process.platform !== 'win32') await fs.chmod(directory, 0o700);
+  return path.join(directory, 'invocations.jsonl');
+}
+
+export async function appendInvocation(value, home = os.homedir()) {
+  if (!value || !SHA.test(value.requestId) || !ID.test(value.operation) || !events.has(value.event)
+    || !['remote', 'local'].includes(value.kind)) throw new Error('Invalid invocation ledger metadata');
+  const record = { schemaVersion: 'entrorove.invocation/1.0', eventId: randomUUID(), at: new Date().toISOString(),
+    kind: value.kind, operation: value.operation, requestId: value.requestId, event: value.event };
+  if (value.durationMs !== undefined) {
+    if (!Number.isSafeInteger(value.durationMs) || value.durationMs < 0) throw new Error('Invalid local invocation duration');
+    record.durationMs = value.durationMs;
+  }
+  if (value.usage !== undefined) {
+    if (!Array.isArray(value.usage) || value.usage.length > 100) throw new Error('Invalid invocation usage receipt list');
+    record.usage = value.usage.map(item => receipt(item, value.requestId));
+  }
+  const file = await ledgerFile(home);
+  await withStateLock(file, async () => {
+    const handle = await fs.open(file, constants.O_APPEND | constants.O_WRONLY | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      const stat = await handle.stat();
+      if (!stat.isFile() || stat.nlink !== 1 || process.platform !== 'win32'
+        && (stat.uid !== process.getuid() || (stat.mode & 0o777) !== 0o600)) throw new Error('Invocation ledger must be a private regular file with permissions 0600');
+      await handle.writeFile(`${JSON.stringify(record)}\n`); await handle.sync();
+    } finally { await handle.close(); }
+  });
+  return record;
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+export async function withLocalInvocation(operation, input, work) {
+  const requestId = createHash('sha256').update(operation + canonical(input)).digest('hex');
+  const metadata = { kind: 'local', operation, requestId };
+  await appendInvocation({ ...metadata, event: 'started' }, input.home);
+  const startedAt = performance.now();
+  try {
+    const output = await work();
+    const rejected = ['blocked', 'failed', 'incomplete'].includes(output?.status);
+    await appendInvocation({ ...metadata, event: rejected ? 'rejected' : 'completed',
+      durationMs: Math.max(0, Math.round(performance.now() - startedAt)) }, input.home);
+    return output;
+  } catch (cause) {
+    await appendInvocation({ ...metadata, event: 'outcome-unknown',
+      durationMs: Math.max(0, Math.round(performance.now() - startedAt)) }, input.home);
+    throw cause;
+  }
+}
+
+export async function readInvocations(home = os.homedir()) {
+  const file = await ledgerFile(home);
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16_777_216
+      || process.platform !== 'win32' && (stat.uid !== process.getuid() || (stat.mode & 0o777) !== 0o600)) throw new Error('Invocation ledger is unavailable or invalid');
+    try { return (await handle.readFile('utf8')).trim().split('\n').filter(Boolean).map(line => JSON.parse(line)); }
+    catch { throw new Error('Invocation ledger contains invalid metadata'); }
+  } finally { await handle.close(); }
+}

package/local-ledger.mjs

@@ -1,3 +1,4 @@
+import { operationSchemasFor } from './local-contracts.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -49,10 +50,4 @@ export const LOCAL_LEDGER_OPERATIONS = Object.freeze({
   'chain-init': chainInit, 'chain-resume': chainResume, 'chain-status': chainStatus, 'chain-answer': chainAnswer,
   'branch-create-virtual': branchCreate, 'chain-ledger-init': chainInit, 'chain-ledger-status': chainStatus, 'chain-ledger-query': ledgerQuery,
 });
-const LEDGER_REQUIRED = {
-  'branch-create': ['repositoryRoot', 'name', 'fromRef'], 'branch-list': ['repositoryRoot'], 'branch-switch': ['repositoryRoot', 'branchName'],
-  'diff-report': ['repositoryRoot'], preflight: ['repositoryRoot'], 'ledger-query': ['repositoryRoot'], 'chain-init': ['repositoryRoot', 'plan'],
-  'chain-resume': ['repositoryRoot', 'chainId'], 'chain-status': ['repositoryRoot', 'chainId'], 'chain-answer': ['repositoryRoot', 'chainId', 'answer'],
-  'branch-create-virtual': ['repositoryRoot', 'name', 'fromRef'], 'chain-ledger-init': ['repositoryRoot', 'plan'], 'chain-ledger-status': ['repositoryRoot', 'chainId'], 'chain-ledger-query': ['repositoryRoot'],
-};
-export const LOCAL_LEDGER_SCHEMAS = Object.freeze(Object.fromEntries(Object.keys(LOCAL_LEDGER_OPERATIONS).map(operation => [operation, { type: 'object', additionalProperties: false, required: LEDGER_REQUIRED[operation] ?? [] }])));
+export const LOCAL_LEDGER_SCHEMAS = operationSchemasFor(LOCAL_LEDGER_OPERATIONS);

package/local-merge-archguard-verification.d.mts

@@ -0,0 +1,44 @@
+import type { KeyObject } from 'node:crypto';
+
+export interface MergeInspectionOptions {
+  publicKey?: string;
+  now?: number;
+  consumedNonces?: ReadonlySet<string>;
+}
+export interface MergePreflightInspectionOptions extends MergeInspectionOptions {
+  preparation?: unknown;
+  mergeLease?: unknown;
+  preparationPublicKey?: string;
+  authorityPublicKey?: string;
+  consumedPreparationNonces?: ReadonlySet<string>;
+  consumedLeaseNonces?: ReadonlySet<string>;
+}
+export interface MergeReceiptDetails {
+  authentic?: boolean;
+  status?: 'passed' | 'blocked';
+  reason?: string;
+  preparation?: Record<string, unknown>;
+  preflight?: Record<string, unknown>;
+  attestation?: Record<string, unknown>;
+}
+export type MergeReceiptInspection = MergeReceiptDetails & (
+  { verified: true; keyId: string; nonce: string; receiptDigest: string }
+  | { verified: false; keyId?: string; nonce?: string; receiptDigest?: string }
+);
+export const MERGE_ARCHGUARD_SCHEMA: 'entrorove.archguard-merge-preflight/1.0';
+export const MERGE_PREPARATION_SCHEMA: 'entrorove.merge-preparation-receipt/1.0';
+export const MERGE_PIN_ENV: 'ENTROROVE_ARCHGUARD_RUNNER_PUBLIC_KEY';
+export const MERGE_ARCHGUARD_RUNTIME_SHA256: string;
+export const SHA256: RegExp;
+export const ID: RegExp;
+export function mergeSha256(bytes: string | Uint8Array): string;
+export function mergeCanonical(value: unknown): string;
+export function configuredMergePin(publicKey: string | undefined): { key: KeyObject; der: Buffer; keyId: string; publicKey: string };
+export function verifyMergeSignature(value: unknown, signature: unknown, keyId: unknown, publicKey: string | undefined): string;
+export function verifyMergeLifetime(value: Record<string, unknown>, now?: number, consumedNonces?: ReadonlySet<string>): void;
+export function inspectMergeSignedEnvelope(value: unknown, options: MergeInspectionOptions & { schemaVersion: string }): MergeReceiptInspection;
+export function inspectLegacyArchguardPreflight(value: unknown, binding?: Record<string, unknown>, options?: MergeInspectionOptions): MergeReceiptInspection;
+export function mergeArtifactSha256(files: ReadonlyArray<{ path: string; sha256: string }>): string;
+export function mergePreflightBinding(preparation: Record<string, unknown>): Record<string, unknown>;
+export function inspectMergePreparation(preparation: unknown, binding?: Record<string, unknown>, options?: MergeInspectionOptions): MergeReceiptInspection;
+export function inspectMergeArchguardPreflight(preflight: unknown, binding?: Record<string, unknown>, options?: MergePreflightInspectionOptions): MergeReceiptInspection;