@evomap/evolver-core 2.0.0-beta.2 → 2.0.0-beta.22

package/dist/ops/evolutionGraphProjection.js

@@ -0,0 +1,315 @@
+// Read-only Evolution Graph projection over already-emitted root_events.
+//
+// PURE: a function over a root-event snapshot. It never appends events, writes assets, or mutates selection —
+// projecting is strictly an observability concern (same posture as ops/reuseOutcomes.ts). The graph it returns is
+// evidence for "which variant was selected on what basis, and was that later contradicted", not a new actuator.
+//
+// Every edge carries provenance back to the root_event seq that justified it, so a dashboard card can always be
+// traced to a specific emitted event instead of a narrative summary.
+import { deriveEvolutionGraphDashboardSummary, EVOLUTION_GRAPH_SCHEMA_VERSION, } from '../schema/evolutionGraph.js';
+import { HOST_SUPPRESS_CLASSES } from '../algo/cycleFailureClassifier.js';
+const DEFAULT_MAX_EVENTS = 5_000;
+const MAX_LABEL = 120;
+const RESOLUTION_STATUSES = new Set([
+    'pending',
+    'suppressed_observationally',
+    'resolved_by_evidence',
+    'regressed',
+    'inconclusive',
+]);
+export function projectEvolutionGraph(events, options = {}) {
+    const maxEvents = boundedLimit(options.maxEvents, DEFAULT_MAX_EVENTS);
+    const window = events.length > maxEvents ? events.slice(events.length - maxEvents) : events;
+    const builder = new GraphBuilder();
+    for (const event of window)
+        builder.absorb(event);
+    const nodes = builder.nodes();
+    const edges = builder.edges();
+    const newestTs = window.length > 0 ? text(window[window.length - 1]?.ts) : '';
+    return {
+        schemaVersion: EVOLUTION_GRAPH_SCHEMA_VERSION,
+        graphId: options.graphId ?? 'graph:evolution:root-events',
+        generatedAt: options.generatedAt ?? (isoTimestamp(newestTs) ?? '1970-01-01T00:00:00.000Z'),
+        nodes,
+        edges,
+        dashboard: deriveEvolutionGraphDashboardSummary({ nodes, edges }),
+        extensions: {},
+    };
+}
+class GraphBuilder {
+    nodesById = new Map();
+    edgesById = new Map();
+    variantByLifecycle = new Map();
+    /** cycleId can be reused; only events in the current lifecycle may share evidence or graph nodes. */
+    lifecycleByCycle = new Map();
+    nodes() {
+        return [...this.nodesById.values()].sort((left, right) => left.id.localeCompare(right.id));
+    }
+    edges() {
+        return [...this.edgesById.values()].sort((left, right) => left.id.localeCompare(right.id));
+    }
+    absorb(event) {
+        const at = isoTimestamp(text(event.ts));
+        if (!at)
+            return;
+        const payload = event.payload ?? {};
+        const cycleId = opaqueId(payload['cycleId']);
+        switch (event.type) {
+            case 'cycle.started': {
+                if (cycleId)
+                    this.beginLifecycle(cycleId);
+                return;
+            }
+            case 'capsule.produced': {
+                if (!cycleId)
+                    return;
+                const capsuleId = opaqueId(payload['capsuleId']);
+                const status = resolutionStatus(payload['resolutionStatus']);
+                if (!capsuleId || !status)
+                    return;
+                const lifecycle = this.activeLifecycle(cycleId);
+                lifecycle.capsule = {
+                    capsuleId,
+                    resolutionStatus: status,
+                    producedValue: payload['producedValue'] === true,
+                    event,
+                };
+                return;
+            }
+            case 'decision.gene_selected': {
+                if (!cycleId)
+                    return;
+                const lifecycle = this.decisionLifecycle(cycleId, event);
+                const variant = this.variant(lifecycle, at);
+                const gene = opaqueId(payload['selectedAssetId']) ?? opaqueId(payload['selectedGeneId']);
+                if (gene) {
+                    const spec = this.node(`spec:${gene}`, 'spec', `gene ${gene}`, at);
+                    this.edge('derivation', spec, variant, at, event, 'variant derived from the selected gene');
+                }
+                const selection = this.node(`selection:${lifecycle.key}`, 'selection', `selection for cycle ${cycleId}`, at);
+                const reason = text(payload['selectedReason']) || text(event.human?.title) || 'gene selected by cycle engine';
+                this.edge('selected', variant, selection, at, event, reason);
+                return;
+            }
+            case 'mutation.built': {
+                if (!cycleId)
+                    return;
+                const lifecycle = this.activeLifecycle(cycleId);
+                if (!lifecycle.key)
+                    return;
+                const variant = this.variant(lifecycle, at);
+                const mutationId = opaqueId(payload['mutationId']);
+                if (!mutationId)
+                    return;
+                const code = this.node(`code:${mutationId}`, 'code', `mutation ${mutationId}`, at);
+                this.edge('derivation', variant, code, at, event, 'variant produced a mutation');
+                return;
+            }
+            case 'cycle.solidified': {
+                if (!cycleId)
+                    return;
+                const lifecycle = this.activeLifecycle(cycleId);
+                lifecycle.terminal = true;
+                if (!lifecycle.key)
+                    return;
+                const score = terminalOutcomeScore(payload['outcome'], 'success');
+                if (score === null)
+                    return;
+                const variant = this.variant(lifecycle, at);
+                const run = this.node(`run:${lifecycle.key}`, 'run', `cycle ${cycleId}`, at);
+                this.edge('evaluated_by', variant, run, at, event, 'cycle completed with a measured outcome');
+                const evidence = this.matchingCapsuleEvidence(lifecycle, payload, true);
+                if (evidence?.resolutionStatus === 'resolved_by_evidence'
+                    && evidence.producedValue
+                    && payload['producedValue'] === true) {
+                    this.edge('fixed', variant, run, at, event, 'cycle resolved by output-backed validation evidence', {
+                        metric: 'cycle_outcome_score',
+                        after: score,
+                        direction: 'improved',
+                    }, [evidence.event]);
+                }
+                return;
+            }
+            case 'cycle.failed': {
+                if (!cycleId)
+                    return;
+                const lifecycle = this.activeLifecycle(cycleId);
+                lifecycle.terminal = true;
+                if (!lifecycle.key)
+                    return;
+                const score = terminalOutcomeScore(payload['outcome'], 'failed');
+                const failureClass = text(payload['failure_class']);
+                if (score === null || text(payload['failureKind']) || suppressesFailure(failureClass))
+                    return;
+                const variant = this.variant(lifecycle, at);
+                const run = this.node(`run:${lifecycle.key}`, 'run', `cycle ${cycleId}`, at);
+                this.edge('evaluated_by', variant, run, at, event, 'cycle completed with a measured failed outcome');
+                const capsule = this.matchingCapsuleEvidence(lifecycle, payload);
+                const inlineStatus = resolutionStatus(payload['resolutionStatus']);
+                if (hasOwn(payload, 'resolutionStatus') && !inlineStatus)
+                    return;
+                const status = inlineStatus ?? capsule?.resolutionStatus ?? null;
+                if (inlineStatus && capsule && inlineStatus !== capsule.resolutionStatus)
+                    return;
+                if (status === 'regressed') {
+                    this.edge('regressed', variant, run, at, event, failureClass || 'measured cycle regression', {
+                        metric: 'cycle_outcome_score',
+                        after: score,
+                        direction: 'regressed',
+                    }, capsule ? [capsule.event] : []);
+                }
+                return;
+            }
+            case 'cycle.aborted': {
+                if (cycleId)
+                    this.activeLifecycle(cycleId).terminal = true;
+                return;
+            }
+            case 'value.reuse_outcome': {
+                const assetId = opaqueId(payload['assetId']);
+                if (!assetId)
+                    return;
+                const spec = this.node(`spec:${assetId}`, 'spec', `gene ${assetId}`, at);
+                const feedback = this.node(`feedback:${assetId}:${event.seq}`, 'feedback', `reuse outcome ${text(payload['outcome']) || 'negative'}`, at);
+                this.edge('derivation', feedback, spec, at, event, 'reuse feedback recorded against the gene');
+                return;
+            }
+            case 'anti_gene.rollout_result': {
+                const suite = opaqueId(payload['suite']) ?? `seq-${event.seq}`;
+                const test = this.node(`test:${suite}`, 'test', `anti-gene rollout ${suite}`, at);
+                const verdict = text(payload['verdict']);
+                const variant = this.node(`variant:rollout:${suite}`, 'variant', `anti-gene arm ${suite}`, at);
+                this.edge('evaluated_by', variant, test, at, event, verdict || 'anti-gene rollout evaluated');
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    beginLifecycle(cycleId) {
+        const lifecycle = {
+            cycleId,
+            key: '',
+            decisionSeen: false,
+            capsule: null,
+            terminal: false,
+        };
+        this.lifecycleByCycle.set(cycleId, lifecycle);
+        return lifecycle;
+    }
+    activeLifecycle(cycleId) {
+        const current = this.lifecycleByCycle.get(cycleId);
+        return !current || current.terminal ? this.beginLifecycle(cycleId) : current;
+    }
+    decisionLifecycle(cycleId, event) {
+        let lifecycle = this.lifecycleByCycle.get(cycleId);
+        if (!lifecycle || lifecycle.decisionSeen || lifecycle.capsule || lifecycle.terminal) {
+            lifecycle = this.beginLifecycle(cycleId);
+        }
+        lifecycle.key = `${cycleId}:seq:${event.seq}`;
+        lifecycle.decisionSeen = true;
+        lifecycle.capsule = null;
+        return lifecycle;
+    }
+    variant(lifecycle, at) {
+        const existing = this.variantByLifecycle.get(lifecycle.key);
+        if (existing)
+            return this.nodesById.get(existing);
+        const node = this.node(`variant:${lifecycle.key}`, 'variant', `variant from cycle ${lifecycle.cycleId}`, at);
+        this.variantByLifecycle.set(lifecycle.key, node.id);
+        return node;
+    }
+    matchingCapsuleEvidence(lifecycle, payload, requireCapsuleId = false) {
+        const evidence = lifecycle.capsule;
+        if (!evidence)
+            return null;
+        if (!hasOwn(payload, 'capsuleId'))
+            return requireCapsuleId ? null : evidence;
+        const capsuleId = opaqueId(payload['capsuleId']);
+        return !capsuleId || capsuleId !== evidence.capsuleId ? null : evidence;
+    }
+    node(id, kind, label, at) {
+        const existing = this.nodesById.get(id);
+        if (existing)
+            return existing;
+        const node = {
+            id,
+            kind,
+            label: label.slice(0, MAX_LABEL) || id,
+            createdAt: at,
+            metrics: [],
+            tags: [],
+            extensions: {},
+        };
+        this.nodesById.set(id, node);
+        return node;
+    }
+    edge(kind, from, to, at, event, reason, metricDelta, supportingEvents = []) {
+        const id = `edge:${kind}:${from.id}->${to.id}:${event.seq}`;
+        if (this.edgesById.has(id))
+            return;
+        this.edgesById.set(id, {
+            id,
+            kind,
+            from: from.id,
+            to: to.id,
+            createdAt: at,
+            provenance: provenanceFor([...supportingEvents, event]),
+            ...(metricDelta ? { metricDelta } : {}),
+            reason: reason.slice(0, MAX_LABEL),
+            extensions: {},
+        });
+    }
+}
+function boundedLimit(value, fallback) {
+    if (!Number.isFinite(value) || value === undefined || value <= 0)
+        return fallback;
+    return Math.min(fallback, Math.floor(value));
+}
+function text(value) {
+    return typeof value === 'string' ? value.replace(/[\r\n\t]+/g, ' ').trim() : '';
+}
+/** Opaque local identifiers only: no control characters, bounded, so a graph id cannot smuggle payload text. */
+function opaqueId(value) {
+    const candidate = text(value);
+    if (!candidate || candidate.length > 160)
+        return null;
+    return /^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(candidate) ? candidate : null;
+}
+function isoTimestamp(value) {
+    if (!value)
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function terminalOutcomeScore(value, expectedStatus) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const outcome = value;
+    if (outcome['status'] !== expectedStatus)
+        return null;
+    const score = outcome['score'];
+    return typeof score === 'number' && Number.isFinite(score) ? score : null;
+}
+function resolutionStatus(value) {
+    return typeof value === 'string' && RESOLUTION_STATUSES.has(value)
+        ? value
+        : null;
+}
+function suppressesFailure(value) {
+    return value !== '' && HOST_SUPPRESS_CLASSES.has(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function provenanceFor(events) {
+    const seen = new Set();
+    return events.flatMap((event) => {
+        const capturedAt = isoTimestamp(text(event.ts));
+        const ref = `seq:${event.seq}`;
+        if (!capturedAt || seen.has(ref))
+            return [];
+        seen.add(ref);
+        return [{ kind: 'root_event', ref, capturedAt, summary: event.type }];
+    });
+}

package/dist/ops/index.d.ts

@@ -4,4 +4,5 @@ export * from './selfUpdate.js';
 export * from './valueLedger.js';
 export * from './valueOutreach.js';
 export * from './recall.js';
-export * from './reuseOutcomes.js';
+export * from './reuseOutcomes.js';
+export * from './evolutionGraphProjection.js';

package/dist/ops/index.js

@@ -4,4 +4,5 @@ export * from './selfUpdate.js';
 export * from './valueLedger.js';
 export * from './valueOutreach.js';
 export * from './recall.js';
-export * from './reuseOutcomes.js';
+export * from './reuseOutcomes.js';
+export * from './evolutionGraphProjection.js';

package/dist/ops/savingsCore.js

@@ -6,8 +6,7 @@
 // gate (it reads the vendored files at runtime, so this module stays free of cross-rootDir JSON
 // imports), and savings-core's daily drift-check locks the vendored copies to upstream. To change a
 // coefficient: change savings-core first, regenerate vectors there, bump spec_version, then
-// re-vendor here AND in evomap-hub / evomap-private / evox-online-deck / evomap-desktop / evox /
-// evolver-private-dev / evolver-v2-enterprise-dev.
+// re-vendor it into each consuming distribution.
 //
 // Core purity contract holds: no I/O, no Date.now/Math.random — pure functions over numbers.
 export const SAVINGS_SPEC_VERSION = '0.3.0';

package/dist/ops/selfUpdate.d.ts

@@ -91,6 +91,14 @@ export interface DownloadedArtifact {
     /** Or a precomputed lowercase-hex sha256, if the caller hashed during streaming (avoids buffering). */
     sha256?: string;
 }
+/**
+ * Parse a configured public key (PEM, raw 32-byte base64, SPKI DER base64, or a KeyObject) into a node KeyObject.
+ *
+ * The base64 forms mirror scripts/release-update-manifest.mjs parsePublicKey exactly: the release pipeline and the
+ * built-in channel key ship the full SPKI DER blob (44 bytes for Ed25519), while operator overrides may supply the
+ * bare 32-byte raw key. Anything that does not decode to a valid Ed25519 SPKI key throws (fail-closed).
+ */
+export declare function toPublicKey(publicKey: string | KeyObject): KeyObject;
 /**
  * Verify downloaded artifacts against the manifest. PURE + deterministic (takes already-read bytes/hashes; does
  * NO I/O). Two layers:
@@ -103,4 +111,13 @@ export interface DownloadedArtifact {
  *
  * 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;
+export declare function verifyManifest(manifest: unknown, downloaded: readonly DownloadedArtifact[], publicKey?: string | KeyObject): VerifyResult;
+/**
+ * Verify exactly one explicitly selected download against a complete release manifest.
+ *
+ * Unlike verifyManifest, this verifier does not require downloading every platform artifact. When a public key is
+ * configured it first verifies the Ed25519 signature over the complete canonical manifest, then requires exactly
+ * one downloaded artifact and exactly one manifest entry with the same path, and finally checks that artifact's
+ * sha256. The complete manifest is never filtered or reconstructed before signature verification.
+ */
+export declare function verifySelectedManifestArtifact(manifest: unknown, downloaded: readonly DownloadedArtifact[], publicKey?: string | KeyObject): VerifyResult;

package/dist/ops/selfUpdate.js

@@ -224,19 +224,54 @@ export function canonicalManifestBytes(manifest) {
     };
     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) {
+/**
+ * Parse a configured public key (PEM, raw 32-byte base64, SPKI DER base64, or a KeyObject) into a node KeyObject.
+ *
+ * The base64 forms mirror scripts/release-update-manifest.mjs parsePublicKey exactly: the release pipeline and the
+ * built-in channel key ship the full SPKI DER blob (44 bytes for Ed25519), while operator overrides may supply the
+ * bare 32-byte raw key. Anything that does not decode to a valid Ed25519 SPKI key throws (fail-closed).
+ */
+export 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' });
+    const decoded = Buffer.from(trimmed, 'base64');
+    // Raw 32-byte Ed25519 key, base64 → wrap in DER SPKI so createPublicKey accepts it;
+    // any other length is assumed to already be a full SPKI DER blob.
+    const der = decoded.length === 32
+        ? Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), decoded])
+        : decoded;
+    let key;
+    try {
+        key = createPublicKey({ key: der, format: 'der', type: 'spki' });
+    }
+    catch {
+        throw new Error('ed25519 public key must be a raw 32-byte or SPKI DER base64 key');
+    }
+    if (key.asymmetricKeyType !== 'ed25519')
+        throw new Error('ed25519 public key must be an Ed25519 key');
+    return key;
+}
+/** Verify the signature over the complete canonical manifest when a public key is configured. */
+function verifyConfiguredManifestSignature(manifest, publicKey) {
+    if (!publicKey)
+        return { ok: true, reason: 'signature_not_required' };
+    if (!manifest.signature)
+        return { ok: false, reason: 'signature_required_but_missing' };
+    if (manifest.signatureAlg && manifest.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(manifest), key, Buffer.from(manifest.signature, 'base64'));
+        return ok ? { ok: true, reason: 'signature_verified' } : { ok: false, reason: 'signature_invalid' };
+    }
+    catch (err) {
+        return { ok: false, reason: `signature_verify_error: ${err instanceof Error ? err.message : String(err)}` };
+    }
 }
 /**
  * Verify downloaded artifacts against the manifest. PURE + deterministic (takes already-read bytes/hashes; does
@@ -274,21 +309,51 @@ export function verifyManifest(manifest, downloaded, publicKey) {
             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)}` };
-        }
+    const signature = verifyConfiguredManifestSignature(m, publicKey);
+    if (!signature.ok)
+        return signature;
+    return { ok: true, reason: 'verified' };
+}
+/**
+ * Verify exactly one explicitly selected download against a complete release manifest.
+ *
+ * Unlike verifyManifest, this verifier does not require downloading every platform artifact. When a public key is
+ * configured it first verifies the Ed25519 signature over the complete canonical manifest, then requires exactly
+ * one downloaded artifact and exactly one manifest entry with the same path, and finally checks that artifact's
+ * sha256. The complete manifest is never filtered or reconstructed before signature verification.
+ */
+export function verifySelectedManifestArtifact(manifest, downloaded, publicKey) {
+    const structErr = manifestStructuralError(manifest);
+    if (structErr)
+        return { ok: false, reason: structErr };
+    const m = manifest;
+    const signature = verifyConfiguredManifestSignature(m, publicKey);
+    if (!signature.ok)
+        return signature;
+    if (downloaded.length !== 1) {
+        return { ok: false, reason: `downloaded_artifact_count_invalid: ${downloaded.length}` };
+    }
+    const selected = downloaded[0];
+    if (!selected || typeof selected.path !== 'string' || !selected.path) {
+        return { ok: false, reason: 'downloaded_artifact_path_invalid' };
+    }
+    const matches = m.artifacts.filter((artifact) => artifact.path === selected.path);
+    if (matches.length === 0)
+        return { ok: false, reason: `artifact_missing: ${selected.path}` };
+    if (matches.length !== 1)
+        return { ok: false, reason: `artifact_duplicate: ${selected.path}` };
+    const expected = matches[0];
+    if (!expected)
+        return { ok: false, reason: `artifact_missing: ${selected.path}` };
+    let digest;
+    if (selected.sha256)
+        digest = selected.sha256.toLowerCase();
+    else if (selected.bytes)
+        digest = sha256Hex(selected.bytes);
+    else
+        return { ok: false, reason: `artifact_no_content: ${selected.path}` };
+    if (digest !== expected.sha256.toLowerCase()) {
+        return { ok: false, reason: `sha256_mismatch: ${selected.path}` };
     }
     return { ok: true, reason: 'verified' };
 }

package/dist/ops/valueOutreach.d.ts

@@ -67,4 +67,6 @@ export declare function digestShouldSend(summary: ValueSummary): boolean;
  * caller then delivers nothing — no empty digest, ever). measured and estimated stay on separate lines. Pure:
  * the window label + the period string are passed in so the digest is deterministic.
  */
-export declare function buildValueDigest(summary: ValueSummary, period: string): string | null;
+export declare function buildValueDigest(summary: ValueSummary, period: string, extras?: {
+    pendingReviewCount?: number;
+}): string | null;

package/dist/ops/valueOutreach.js

@@ -221,7 +221,7 @@ export function digestShouldSend(summary) {
  * caller then delivers nothing — no empty digest, ever). measured and estimated stay on separate lines. Pure:
  * the window label + the period string are passed in so the digest is deterministic.
  */
-export function buildValueDigest(summary, period) {
+export function buildValueDigest(summary, period, extras = {}) {
     if (!digestShouldSend(summary))
         return null;
     const L = [];
@@ -238,6 +238,10 @@ export function buildValueDigest(summary, period) {
         for (const g of summary.topGenes.slice(0, 5))
             L.push(`- ${g.assetId} — reused ×${g.reuses}`);
     }
+    if ((extras.pendingReviewCount ?? 0) > 0) {
+        L.push('');
+        L.push(`${extras.pendingReviewCount} gene(s) still awaiting review — run \`evolver review\` so they can enter SessionStart.`);
+    }
     L.push('');
     L.push('_Run `evolver value` any time for the full breakdown. Turn this digest off with `EVOLVER_VALUE_DIGEST=0`._');
     return L.join('\n');