@evomap/evolver-core 2.0.0-beta.0

package/dist/ops/selfUpdate.d.ts

@@ -0,0 +1,106 @@
+import { type KeyObject } from 'node:crypto';
+export interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export interface NormalizedSelfUpdateVersion {
+    ok: true;
+    version: string;
+}
+export interface InvalidSelfUpdateVersion {
+    ok: false;
+    reason: string;
+}
+export type SelfUpdateVersionResult = NormalizedSelfUpdateVersion | InvalidSelfUpdateVersion;
+export declare const SELF_UPDATE_VERSION_MAX = 32;
+/** Parse a version under the self-update contract. Invalid strings default to 0.0.0 for this legacy helper. */
+export declare function parseVersion(v: string | null | undefined): ParsedVersion;
+/** -1 if a<b, 0 if equal, 1 if a>b (SemVer precedence; build metadata ignored). */
+export declare function compareVersions(a: string | null | undefined, b: string | null | undefined): -1 | 0 | 1;
+/** True if `current` >= `required` (faithful to v1 isAtLeast: equal counts as satisfied). */
+export declare function isAtLeast(current: string | null | undefined, required: string | null | undefined): boolean;
+export declare function normalizeSelfUpdateVersion(value: unknown, field?: string): SelfUpdateVersionResult;
+export declare function requireSelfUpdateVersion(value: unknown, field?: string): string;
+/** Normalize a concrete semver value under the self-update contract. */
+export declare function normalizeConcreteVersion(value: unknown): string | undefined;
+/** Normalize the hub's required_version floor. Mirrors v1 forceUpdate.js strip + validate behavior. */
+export declare function normalizeRequiredVersion(value: unknown): string | undefined;
+export declare function compareConcreteVersions(left: string, right: string): -1 | 0 | 1 | null;
+export declare function currentSatisfiesRequiredVersion(current: unknown, required: unknown): boolean;
+/** One downloadable artifact the release pipeline must publish a hash for. */
+export interface UpdateArtifact {
+    /** Path/name of the artifact relative to the package root (e.g. `dist/evolver.tar.gz`). */
+    path: string;
+    /** Lowercase hex sha256 the release pipeline computed for this artifact. */
+    sha256: string;
+}
+/**
+ * The release manifest the hub points the node at. The release-CI side publishes this alongside the GitHub
+ * Release. `signature` + `signatureAlg` are OPTIONAL on the wire but REQUIRED to pass when a public key is
+ * configured on the node (fail-closed). The signature is over the canonical JSON of {version, artifacts}.
+ */
+export interface UpdateManifest {
+    /** The version this manifest publishes (e.g. `1.4.0`). */
+    version: string;
+    /** Per-artifact sha256 list — MUST be non-empty (nothing to verify = nothing to trust). */
+    artifacts: readonly UpdateArtifact[];
+    /** base64 Ed25519 signature over canonicalManifestBytes({version, artifacts}). Optional on wire. */
+    signature?: string;
+    /** Signature algorithm tag; only 'ed25519' is accepted. */
+    signatureAlg?: string;
+}
+export type UpdateAction = 'proceed' | 'noop' | 'reject';
+export interface UpdateDecision {
+    action: UpdateAction;
+    reason: string;
+    targetVersion?: string;
+}
+/**
+ * Decide whether to apply an update. PURE. Fail-closed: a missing/malformed manifest, or a target that does not
+ * advance past `current`, never proceeds.
+ *   - reject : manifest missing/malformed, or required target not satisfiable by the manifest version.
+ *   - noop   : current already satisfies the requested target (no restart needed) — v1's NOOP branch.
+ *   - proceed: manifest is valid AND advances current. Caller must STILL verifyManifest before applying.
+ *
+ * `required` is the hub's force_update `required_version` (what the hub demands). `manifest.version` is what the
+ * download would deliver. We refuse if the manifest can't actually satisfy the requirement.
+ */
+export declare function decideUpdate(input: {
+    current: string;
+    required?: string;
+    manifest: unknown;
+}): UpdateDecision;
+/** sha256 hex of the given bytes — the digest each downloaded artifact is checked against. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+/**
+ * Canonical bytes the signature is computed over: a deterministic JSON of {version, artifacts:[{path,sha256}]}
+ * with artifacts sorted by path and sha256 lowercased, so signer and verifier agree byte-for-byte regardless of
+ * key order or casing. The release pipeline MUST sign exactly these bytes.
+ */
+export declare function canonicalManifestBytes(manifest: Pick<UpdateManifest, 'version' | 'artifacts'>): Uint8Array;
+export interface VerifyResult {
+    ok: boolean;
+    reason: string;
+}
+/** A downloaded artifact's content, supplied to verifyManifest as already-read bytes (or a precomputed digest). */
+export interface DownloadedArtifact {
+    path: string;
+    /** Raw bytes of the downloaded file (preferred). */
+    bytes?: Uint8Array;
+    /** Or a precomputed lowercase-hex sha256, if the caller hashed during streaming (avoids buffering). */
+    sha256?: string;
+}
+/**
+ * Verify downloaded artifacts against the manifest. PURE + deterministic (takes already-read bytes/hashes; does
+ * NO I/O). Two layers:
+ *   1. sha256-per-artifact (ALWAYS): every manifest artifact must have a matching downloaded artifact whose
+ *      sha256 equals the manifest's. Missing, extra-unmatched, or mismatched → reject.
+ *   2. Ed25519 signature (ONLY when `publicKey` is configured): the manifest MUST carry a valid signature over
+ *      canonicalManifestBytes. A configured key + missing/badly-signed/wrong-alg manifest → reject (fail-closed).
+ *      With NO key configured, signature is not required (sha256 is still mandatory) — the node operator opts into
+ *      the strong form by configuring a key. No key is ever hardcoded.
+ *
+ * Fail-closed everywhere: any doubt (bad structure, hash gap, signature failure, thrown crypto error) → reject.
+ */
+export declare function verifyManifest(manifest: unknown, downloaded: readonly DownloadedArtifact[], publicKey?: string | KeyObject): VerifyResult;

package/dist/ops/selfUpdate.js

@@ -0,0 +1,294 @@
+// Self-update DECISION + VERIFY core (ported from v1 src/forceUpdate.js — parseVer/isAtLeast/version compare —
+// PLUS the security gate v1 lacked). This module is PURE and hub-agnostic: it makes the
+// update/noop/reject decision and verifies already-downloaded artifact bytes/hashes against a signed manifest.
+// It performs NO I/O — no download, no filesystem write, no process control. Those live in the proxy executor
+// (evolver-proxy/src/selfUpdate/executor.ts) which CALLS verifyManifest before touching disk (verify-before-apply).
+//
+// Why split this way (the boundary rule): a compromised hub must not equal fleet RCE. The decision of whether to
+// apply AND the verification of what to apply are deterministic, fully unit-testable, and must never depend on
+// who is calling. The risky part (writing files, exit(78)) is isolated in proxy behind injected seams.
+import { createHash, verify as cryptoVerify, createPublicKey } from 'node:crypto';
+const SEMVER_NUMERIC_IDENTIFIER = '0|[1-9]\\d*';
+const SEMVER_PRERELEASE_IDENTIFIER = '(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)';
+const SEMVER_BUILD_IDENTIFIER = '[0-9A-Za-z-]+';
+const CONCRETE_SEMVER_RE = new RegExp(`^(${SEMVER_NUMERIC_IDENTIFIER})\\.(${SEMVER_NUMERIC_IDENTIFIER})\\.(${SEMVER_NUMERIC_IDENTIFIER})`
+    + `(?:-(${SEMVER_PRERELEASE_IDENTIFIER}(?:\\.${SEMVER_PRERELEASE_IDENTIFIER})*))?`
+    + `(?:\\+(${SEMVER_BUILD_IDENTIFIER}(?:\\.${SEMVER_BUILD_IDENTIFIER})*))?$`);
+export const SELF_UPDATE_VERSION_MAX = 32;
+/** Parse a version under the self-update contract. Invalid strings default to 0.0.0 for this legacy helper. */
+export function parseVersion(v) {
+    const version = normalizeConcreteVersion(v);
+    const parsed = version ? parseConcreteVersion(version) : undefined;
+    return parsed ? { major: parsed.major, minor: parsed.minor, patch: parsed.patch } : { major: 0, minor: 0, patch: 0 };
+}
+/** -1 if a<b, 0 if equal, 1 if a>b (SemVer precedence; build metadata ignored). */
+export function compareVersions(a, b) {
+    return compareConcreteVersions(normalizeConcreteVersion(a) ?? '0.0.0', normalizeConcreteVersion(b) ?? '0.0.0') ?? 0;
+}
+/** True if `current` >= `required` (faithful to v1 isAtLeast: equal counts as satisfied). */
+export function isAtLeast(current, required) {
+    return compareVersions(current, required) >= 0;
+}
+export function normalizeSelfUpdateVersion(value, field = 'version') {
+    if (typeof value !== 'string')
+        return { ok: false, reason: `${field}_missing` };
+    const normalized = value.replace(/^[>=^~\s]+/, '').replace(/^v/, '');
+    if (normalized.length === 0)
+        return { ok: false, reason: `${field}_missing` };
+    if (normalized.length > SELF_UPDATE_VERSION_MAX)
+        return { ok: false, reason: `${field}_too_long` };
+    if (!CONCRETE_SEMVER_RE.test(normalized))
+        return { ok: false, reason: `${field}_invalid` };
+    return { ok: true, version: normalized };
+}
+export function requireSelfUpdateVersion(value, field = 'version') {
+    const normalized = normalizeSelfUpdateVersion(value, field);
+    if (!normalized.ok)
+        throw new Error(normalized.reason);
+    return normalized.version;
+}
+/** Normalize a concrete semver value under the self-update contract. */
+export function normalizeConcreteVersion(value) {
+    const normalized = normalizeSelfUpdateVersion(value);
+    return normalized.ok ? normalized.version : undefined;
+}
+/** Normalize the hub's required_version floor. Mirrors v1 forceUpdate.js strip + validate behavior. */
+export function normalizeRequiredVersion(value) {
+    return normalizeConcreteVersion(value);
+}
+export function compareConcreteVersions(left, right) {
+    const leftVersion = normalizeConcreteVersion(left);
+    const rightVersion = normalizeConcreteVersion(right);
+    if (!leftVersion || !rightVersion)
+        return null;
+    const a = parseConcreteVersion(leftVersion);
+    const b = parseConcreteVersion(rightVersion);
+    if (!a || !b)
+        return null;
+    const majorCmp = compareNumericIdentifierStrings(a.majorRaw, b.majorRaw);
+    if (majorCmp !== 0)
+        return majorCmp < 0 ? -1 : 1;
+    const minorCmp = compareNumericIdentifierStrings(a.minorRaw, b.minorRaw);
+    if (minorCmp !== 0)
+        return minorCmp < 0 ? -1 : 1;
+    const patchCmp = compareNumericIdentifierStrings(a.patchRaw, b.patchRaw);
+    if (patchCmp !== 0)
+        return patchCmp < 0 ? -1 : 1;
+    if (a.prerelease.length === 0 && b.prerelease.length === 0)
+        return 0;
+    if (a.prerelease.length === 0)
+        return 1;
+    if (b.prerelease.length === 0)
+        return -1;
+    const max = Math.max(a.prerelease.length, b.prerelease.length);
+    for (let i = 0; i < max; i += 1) {
+        const av = a.prerelease[i];
+        const bv = b.prerelease[i];
+        if (av === undefined)
+            return -1;
+        if (bv === undefined)
+            return 1;
+        const cmp = comparePrereleaseIdentifiers(av, bv);
+        if (cmp !== 0)
+            return cmp < 0 ? -1 : 1;
+    }
+    return 0;
+}
+export function currentSatisfiesRequiredVersion(current, required) {
+    const currentVersion = normalizeConcreteVersion(current);
+    const requiredVersion = normalizeRequiredVersion(required);
+    if (!currentVersion || !requiredVersion)
+        return false;
+    const cmp = compareConcreteVersions(currentVersion, requiredVersion);
+    return cmp !== null && cmp >= 0;
+}
+function parseConcreteVersion(value) {
+    const match = CONCRETE_SEMVER_RE.exec(value);
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        majorRaw: match[1] ?? '0',
+        minorRaw: match[2] ?? '0',
+        patchRaw: match[3] ?? '0',
+        prerelease: match[4] ? match[4].split('.') : [],
+    };
+}
+function isNumericPrereleaseIdentifier(value) {
+    return /^\d+$/.test(value);
+}
+function compareNumericIdentifierStrings(left, right) {
+    if (left.length !== right.length)
+        return left.length - right.length;
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function comparePrereleaseIdentifiers(left, right) {
+    const leftNumeric = isNumericPrereleaseIdentifier(left);
+    const rightNumeric = isNumericPrereleaseIdentifier(right);
+    if (leftNumeric && rightNumeric)
+        return compareNumericIdentifierStrings(left, right);
+    if (leftNumeric)
+        return -1;
+    if (rightNumeric)
+        return 1;
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+/** Shallow structural validation of a manifest — returns null if structurally usable, else a reject reason. */
+function manifestStructuralError(manifest) {
+    if (!manifest || typeof manifest !== 'object')
+        return 'manifest_missing';
+    const m = manifest;
+    if (typeof m.version !== 'string' || !m.version.trim())
+        return 'manifest_no_version';
+    if (!normalizeConcreteVersion(m.version))
+        return 'manifest_bad_version';
+    if (!Array.isArray(m.artifacts) || m.artifacts.length === 0)
+        return 'manifest_no_artifacts';
+    for (const a of m.artifacts) {
+        if (!a || typeof a.path !== 'string' || !a.path.trim())
+            return 'manifest_bad_artifact_path';
+        if (typeof a.sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(a.sha256))
+            return 'manifest_bad_artifact_sha256';
+    }
+    return null;
+}
+/**
+ * Decide whether to apply an update. PURE. Fail-closed: a missing/malformed manifest, or a target that does not
+ * advance past `current`, never proceeds.
+ *   - reject : manifest missing/malformed, or required target not satisfiable by the manifest version.
+ *   - noop   : current already satisfies the requested target (no restart needed) — v1's NOOP branch.
+ *   - proceed: manifest is valid AND advances current. Caller must STILL verifyManifest before applying.
+ *
+ * `required` is the hub's force_update `required_version` (what the hub demands). `manifest.version` is what the
+ * download would deliver. We refuse if the manifest can't actually satisfy the requirement.
+ */
+export function decideUpdate(input) {
+    const structErr = manifestStructuralError(input.manifest);
+    if (structErr)
+        return { action: 'reject', reason: structErr };
+    const manifest = input.manifest;
+    const manifestVersion = normalizeConcreteVersion(manifest.version);
+    if (!manifestVersion)
+        return { action: 'reject', reason: 'manifest_bad_version' };
+    const required = input.required !== undefined && String(input.required) !== ''
+        ? normalizeRequiredVersion(input.required)
+        : manifestVersion;
+    if (!required)
+        return { action: 'reject', reason: 'required_version_invalid' };
+    // The manifest must be able to deliver at least the required version, otherwise applying it is pointless/unsafe.
+    const manifestCmp = compareConcreteVersions(manifestVersion, required);
+    if (manifestCmp === null)
+        return { action: 'reject', reason: 'manifest_bad_version' };
+    if (manifestCmp < 0) {
+        return { action: 'reject', reason: 'manifest_below_required', targetVersion: manifestVersion };
+    }
+    // Already at/above what the hub requires → nothing to do, do NOT restart (v1 NOOP).
+    const currentVersion = normalizeConcreteVersion(input.current);
+    if (!currentVersion)
+        return { action: 'reject', reason: 'current_version_invalid' };
+    const currentCmp = compareConcreteVersions(currentVersion, required);
+    if (currentCmp !== null && currentCmp >= 0) {
+        return { action: 'noop', reason: 'already_satisfied', targetVersion: required };
+    }
+    return { action: 'proceed', reason: 'update_available', targetVersion: manifestVersion };
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Manifest verification (the security gate v1 lacked). sha256-per-artifact is MANDATORY; Ed25519 signature is the
+// strong form, enforced ONLY when a public key is configured — and then fail-closed.
+// ---------------------------------------------------------------------------------------------------------------
+/** sha256 hex of the given bytes — the digest each downloaded artifact is checked against. */
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+/**
+ * Canonical bytes the signature is computed over: a deterministic JSON of {version, artifacts:[{path,sha256}]}
+ * with artifacts sorted by path and sha256 lowercased, so signer and verifier agree byte-for-byte regardless of
+ * key order or casing. The release pipeline MUST sign exactly these bytes.
+ */
+export function canonicalManifestBytes(manifest) {
+    const canonical = {
+        version: requireSelfUpdateVersion(manifest.version, 'manifest_version'),
+        artifacts: [...manifest.artifacts]
+            .map((a) => ({ path: a.path, sha256: a.sha256.toLowerCase() }))
+            .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+    };
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+/** Parse a configured public key (PEM, raw 32-byte base64, or a KeyObject) into a node KeyObject. */
+function toPublicKey(publicKey) {
+    if (typeof publicKey !== 'string')
+        return publicKey;
+    const trimmed = publicKey.trim();
+    if (trimmed.includes('BEGIN PUBLIC KEY'))
+        return createPublicKey(trimmed);
+    // Raw 32-byte Ed25519 key, base64 → wrap in DER SPKI so createPublicKey accepts it.
+    const raw = Buffer.from(trimmed, 'base64');
+    if (raw.length !== 32)
+        throw new Error('ed25519 raw key must be 32 bytes');
+    const der = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), raw]);
+    return createPublicKey({ key: der, format: 'der', type: 'spki' });
+}
+/**
+ * Verify downloaded artifacts against the manifest. PURE + deterministic (takes already-read bytes/hashes; does
+ * NO I/O). Two layers:
+ *   1. sha256-per-artifact (ALWAYS): every manifest artifact must have a matching downloaded artifact whose
+ *      sha256 equals the manifest's. Missing, extra-unmatched, or mismatched → reject.
+ *   2. Ed25519 signature (ONLY when `publicKey` is configured): the manifest MUST carry a valid signature over
+ *      canonicalManifestBytes. A configured key + missing/badly-signed/wrong-alg manifest → reject (fail-closed).
+ *      With NO key configured, signature is not required (sha256 is still mandatory) — the node operator opts into
+ *      the strong form by configuring a key. No key is ever hardcoded.
+ *
+ * Fail-closed everywhere: any doubt (bad structure, hash gap, signature failure, thrown crypto error) → reject.
+ */
+export function verifyManifest(manifest, downloaded, publicKey) {
+    const structErr = manifestStructuralError(manifest);
+    if (structErr)
+        return { ok: false, reason: structErr };
+    const m = manifest;
+    // Layer 1: sha256 per artifact (mandatory). Index downloads by path; every manifest entry must match.
+    const byPath = new Map();
+    for (const d of downloaded)
+        byPath.set(d.path, d);
+    for (const art of m.artifacts) {
+        const got = byPath.get(art.path);
+        if (!got)
+            return { ok: false, reason: `artifact_missing: ${art.path}` };
+        let digest;
+        if (got.sha256)
+            digest = got.sha256.toLowerCase();
+        else if (got.bytes)
+            digest = sha256Hex(got.bytes);
+        else
+            return { ok: false, reason: `artifact_no_content: ${art.path}` };
+        if (digest !== art.sha256.toLowerCase())
+            return { ok: false, reason: `sha256_mismatch: ${art.path}` };
+    }
+    // Layer 2: Ed25519 signature — enforced ONLY when a key is configured (then fail-closed).
+    if (publicKey) {
+        if (!m.signature)
+            return { ok: false, reason: 'signature_required_but_missing' };
+        if (m.signatureAlg && m.signatureAlg !== 'ed25519')
+            return { ok: false, reason: 'signature_alg_unsupported' };
+        try {
+            const key = toPublicKey(publicKey);
+            const ok = cryptoVerify(null, // Ed25519 ignores the digest-name arg
+            canonicalManifestBytes(m), key, Buffer.from(m.signature, 'base64'));
+            if (!ok)
+                return { ok: false, reason: 'signature_invalid' };
+        }
+        catch (err) {
+            return { ok: false, reason: `signature_verify_error: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    return { ok: true, reason: 'verified' };
+}

package/dist/ops/valueLedger.d.ts

@@ -0,0 +1,205 @@
+/** USD price per single token, split by token class (Anthropic-style usage breakdown). All optional: an
+ *  absent class is treated as 0 so a sparse table still prices what it can. */
+export interface ModelPrice {
+    /** USD per input token. */
+    input?: number;
+    /** USD per output token. */
+    output?: number;
+    /** USD per cache-creation (write) input token. */
+    cacheCreation?: number;
+    /** USD per cache-read input token. */
+    cacheRead?: number;
+}
+/**
+ * Model → price lookup. INJECTED, never hardcoded in core (acceptance: a price update must not touch core
+ * code). A lookup is tolerant: an unknown model returns undefined and that turn simply contributes no cost
+ * (we never invent a price). The adapter owns the concrete data file + loader.
+ */
+export interface PriceTable {
+    priceOf(model: string): ModelPrice | undefined;
+}
+/** Build a PriceTable from a plain {model: ModelPrice} map (the shape a JSON data file deserializes to). */
+export declare function priceTableFromMap(map: Readonly<Record<string, ModelPrice>>): PriceTable;
+/** Per-turn token usage, matching the proxy trace's `usage` block by field name (input_tokens, …). */
+export interface TokenUsage {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/**
+ * A single LLM-turn trace record, as the proxy appends it to `llm-trace-YYYYMMDD.jsonl`. Declared structurally
+ * here (only the fields the ledger reads) so core never imports the proxy package. The caller parses the JSONL
+ * and passes the records in.
+ */
+export interface TraceRecord {
+    /** ISO timestamp of the turn (the ledger's `at` for a route entry — never a local clock). */
+    ts: string;
+    /** What the client asked for. */
+    original_model: string | null;
+    /** What the router actually sent (a cheaper tier model when routing fired). */
+    chosen_model: string | null;
+    /** Routing tier, when the router rewrote the model. Absent/null → no route savings for this turn. */
+    tier?: string | null;
+    usage?: TokenUsage;
+}
+/** root_events type appended on a reuse-before-solve HIT — the replayable source for source=reuse entries. */
+export declare const VALUE_REUSE_HIT_EVENT = "value.reuse_hit";
+/**
+ * Payload of a `value.reuse_hit` root_event. Carries exactly what the ledger needs to account a reuse saving:
+ * which asset was reused, in which cycle, the actual token cost the fetch incurred (≈0 - metadata + payload,
+ * no fresh solve), and an OPTIONAL measured baseline (historical avg solve-fresh tokens for this signal class).
+ * When `baselineTokens` is present the saving is `measured`; when absent the ledger records the reuse with
+ * unknown/zero savings instead of inventing a task-level token delta. The signal fingerprint is carried for
+ * baseline attribution upstream.
+ */
+export interface ReuseHitPayload {
+    assetId: string;
+    cycleId: string;
+    /** Signal fingerprint of the reused problem (for baseline cohorting / explainability). */
+    signalFingerprint?: string;
+    /** Tokens the fetch actually consumed (cache/payload pull — typically 0). Defaults to 0. */
+    fetchTokens?: number;
+    /** Measured baseline: historical avg solve-fresh token cost for this signal class. Absent → estimated. */
+    baselineTokens?: number;
+    /** Model whose price values the saved tokens (so cost uses the real tier, not a guess). Optional. */
+    model?: string;
+}
+/** A minimal root_event view the ledger reads (matches the events module's ReportEvent shape). */
+export interface LedgerRootEvent {
+    type: string;
+    ts: string;
+    payload?: Record<string, unknown>;
+}
+/** root_events type appended when SessionStart injects genes — recorded for outcome attribution only. */
+export declare const VALUE_INJECT_EVENT = "value.inject";
+/** Payload of a `value.inject` root_event: which genes were injected and the session outcome. No savings. */
+export interface InjectPayload {
+    geneIds: readonly string[];
+    cycleId?: string;
+    /** The runtime session id this injection went into, when known (#205). Lets recall tie an inject to the exact
+     *  session transcript it produced, rather than assuming "the most recent inject". Absent for runtimes with no id. */
+    sessionId?: string;
+    /** Free-form session outcome label (solved/abandoned/…); attribution only, never scored into a number. */
+    outcome?: string;
+}
+export type ValueSource = 'route' | 'reuse' | 'inject';
+export type ValueConfidence = 'measured' | 'estimated';
+/**
+ * One derived ledger entry. Append-only + content-derived: replaying the same trace + root_events yields the
+ * identical entry. `tokensSaved` is the token delta (0 for route — routing saves cost on the SAME tokens, not
+ * tokens; and 0 for inject — inject reports no number). `costSavedUsd` is the USD delta. `refs` ties the entry
+ * back to its source material (assetId, cycleId, models) for audit / drift checks.
+ */
+export interface ValueEntry {
+    /** Timestamp from the source record (route: trace.ts; reuse/inject: event.ts). Never a local clock. */
+    at: string;
+    source: ValueSource;
+    tokensSaved: number;
+    costSavedUsd: number;
+    confidence: ValueConfidence;
+    refs: {
+        assetId?: string;
+        cycleId?: string;
+        originalModel?: string;
+        chosenModel?: string;
+        /** gene ids, for inject entries (and topGenes attribution). */
+        geneIds?: readonly string[];
+        /** free-form outcome, for inject entries. */
+        outcome?: string;
+    };
+}
+/** Legacy savings-core E1 coefficient for "one cross-node asset reuse". The value ledger no longer uses this
+ *  as a fallback baseline for live `value.reuse_hit` events: without a measured baseline, reuse savings stay
+ *  zero/unknown. Kept exported so savings-core conformance and older consumers can detect spec drift. */
+export declare const ESTIMATED_SOLVE_FRESH_TOKENS: number;
+/**
+ * Derive route-downgrade savings from trace records. A turn saves COST (not tokens) only when the router
+ * actually rewrote the model (`original_model !== chosen_model`, both present): the saving is the price delta
+ * of the SAME usage between the model the client asked for and the cheaper model that ran. Always `measured`
+ * (the usage is real). A turn whose price delta is ≤0 (no cheaper, or model unpriced) contributes nothing.
+ */
+export declare function deriveRouteEntries(traces: readonly TraceRecord[], prices: PriceTable): ValueEntry[];
+/**
+ * Derive reuse savings from `value.reuse_hit` root_events. Saving = (baseline solve-fresh tokens) - (actual
+ * fetch tokens), but only when the event carries `baselineTokens` (a real historical average for the signal
+ * class). Without that measured baseline, the entry still records the reuse but keeps tokensSaved/costSavedUsd
+ * at zero so a small-step reuse inside a large task cannot be promoted into fabricated whole-task ROI.
+ * Each entry's refs point at the real `assetId` + `cycleId` from the hit - the audit anchor.
+ */
+export declare function deriveReuseEntries(events: readonly LedgerRootEvent[], prices: PriceTable): ValueEntry[];
+/**
+ * Derive inject records from `value.inject` root_events. Attribution-only: which genes were injected and the
+ * session outcome. tokensSaved / costSavedUsd are ALWAYS 0 (the issue: inject is a weak signal — record it,
+ * never report a savings number). Marked `estimated` so it can never land on the measured rail, and the
+ * summary excludes inject from both savings totals regardless.
+ */
+export declare function deriveInjectEntries(events: readonly LedgerRootEvent[]): ValueEntry[];
+export interface DeriveInput {
+    /** Parsed proxy trace records (one per LLM turn). */
+    traces?: readonly TraceRecord[];
+    /** Parsed root_events (the reuse-hit + inject records live here). */
+    events?: readonly LedgerRootEvent[];
+    /** Injected price table — core never hardcodes prices. */
+    prices: PriceTable;
+}
+/**
+ * Derive the full set of value entries from trace + root_events, sorted by `at` (stable, ties broken by source
+ * then assetId/models) so the ledger is a deterministic, replayable timeline. Pure: same input → same output,
+ * byte-for-byte. This is the function a `replay` re-runs after discarding the materialized ledger.
+ */
+export declare function deriveValueEntries(input: DeriveInput): ValueEntry[];
+/** Serialize entries to append-only JSONL (one entry per line). Deterministic given the entries. */
+export declare function serializeLedger(entries: readonly ValueEntry[]): string;
+/** Parse a ledger JSONL back into entries (the materialized view; the source of truth is still trace+events). */
+export declare function parseLedger(jsonl: string): ValueEntry[];
+export interface SourceBucket {
+    tokensSaved: number;
+    costSavedUsd: number;
+    entries: number;
+}
+/**
+ * The aggregated value view. CRITICAL HONESTY INVARIANT: `measured` and `estimated` are SEPARATE rails — the
+ * top-level totals (`totalTokensSaved` / `totalCostUsd`) count ONLY measured savings, and estimated savings
+ * live solely under `estimated`. There is no field that merges the two. A consumer that wants a combined figure
+ * must add them itself and label it — the ledger never does it silently.
+ */
+export interface ValueSummary {
+    /** MEASURED savings only (the trustworthy number). */
+    totalTokensSaved: number;
+    totalCostUsd: number;
+    /** Per-source breakdown (measured rail). */
+    bySource: Record<ValueSource, SourceBucket>;
+    /** ESTIMATED savings, on their OWN rail — never folded into the totals above. */
+    estimated: {
+        totalTokensSaved: number;
+        totalCostUsd: number;
+        entries: number;
+    };
+    /** Top reused genes by frequency, with measured/estimated saving kept separate per gene. */
+    topGenes: Array<{
+        assetId: string;
+        reuses: number;
+        measuredTokensSaved: number;
+        estimatedTokensSaved: number;
+    }>;
+    /** Inject attribution (no savings number): genes injected, by frequency. */
+    injectedGenes: Array<{
+        geneId: string;
+        injections: number;
+    }>;
+    /** Number of entries considered (after window filter). */
+    entries: number;
+}
+export interface SummaryWindow {
+    /** Inclusive lower bound (ISO). Entries with `at` < since are excluded. */
+    since?: string;
+    /** Exclusive upper bound (ISO). Entries with `at` >= until are excluded. */
+    until?: string;
+}
+/**
+ * Aggregate entries into a ValueSummary over an optional time window. Pure. Measured and estimated are summed
+ * on separate rails by construction — there is deliberately NO branch that adds an estimated entry into the
+ * measured totals (the honesty invariant; a test asserts no such path exists).
+ */
+export declare function valueSummary(entries: readonly ValueEntry[], window?: SummaryWindow): ValueSummary;