@tangle-network/starter-foundry 0.5.3 → 0.7.0

package/dist/lib/telemetry/stream.js

@@ -0,0 +1,153 @@
+/**
+ * Real-time telemetry stream.
+ *
+ * createTelemetryStream() produces a lightweight batching sink that accepts
+ * BuildoutEvent (or any JSON-serializable payload) and POSTs batches to a
+ * webhook endpoint on a timer (default: 60s) or when the batch hits a size
+ * cap. When the endpoint is unreachable — network error, non-2xx, timeout —
+ * events are appended to an on-disk outbox file so nothing is lost, and the
+ * next flush retries the outbox first.
+ *
+ * This is the consumer-facing side of the real-time aggregator. Aggregators
+ * and dashboards live elsewhere; this lib just guarantees delivery.
+ */
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const DEFAULT_OUTBOX_PATH = '.evolve/telemetry-outbox.jsonl';
+export function createTelemetryStream(options) {
+    if (!options.endpoint)
+        throw new Error('createTelemetryStream: endpoint is required');
+    const batchSize = options.batchSize ?? 50;
+    const flushIntervalMs = options.flushIntervalMs ?? 60_000;
+    const outboxPath = options.outboxPath ?? DEFAULT_OUTBOX_PATH;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    let pending = [];
+    let timer = null;
+    let closed = false;
+    function scheduleTimer() {
+        if (flushIntervalMs <= 0 || timer || closed)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            flush().catch(() => {
+                // Errors already routed to outbox.
+            });
+        }, flushIntervalMs);
+        // Don't keep the event loop alive just for the timer.
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    }
+    async function appendOutbox(events) {
+        await mkdir(dirname(outboxPath), { recursive: true });
+        const body = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+        await appendFile(outboxPath, body, 'utf8');
+    }
+    async function drainOutbox() {
+        let raw;
+        try {
+            raw = await readFile(outboxPath, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const rows = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                rows.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines rather than re-enter them forever.
+            }
+        }
+        return rows;
+    }
+    async function truncateOutbox() {
+        try {
+            await writeFile(outboxPath, '', 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    async function postBatch(events) {
+        if (!events.length)
+            return true;
+        const batchId = `${now()}-${Math.random().toString(36).slice(2, 10)}`;
+        const controller = new AbortController();
+        const tid = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const headers = { 'content-type': 'application/json' };
+            if (options.authToken)
+                headers.authorization = `Bearer ${options.authToken}`;
+            const res = await fetchImpl(options.endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ batchId, events }),
+                signal: controller.signal,
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(tid);
+        }
+    }
+    async function emit(event) {
+        if (closed)
+            throw new Error('telemetry stream closed');
+        pending.push({ ...event, emittedAt: event.emittedAt ?? new Date().toISOString() });
+        scheduleTimer();
+        if (pending.length >= batchSize) {
+            await flush();
+        }
+    }
+    async function flush() {
+        // Pick up outbox first so ordering is preserved.
+        const outboxEvents = await drainOutbox();
+        const inMemory = pending;
+        pending = [];
+        const all = [...outboxEvents, ...inMemory];
+        if (!all.length)
+            return { delivered: 0, buffered: 0 };
+        // Clear the outbox now that we have its contents in memory. If the
+        // send fails we re-append everything below.
+        await truncateOutbox();
+        let delivered = 0;
+        let buffered = 0;
+        for (let i = 0; i < all.length; i += batchSize) {
+            const chunk = all.slice(i, i + batchSize);
+            const ok = await postBatch(chunk);
+            if (ok)
+                delivered += chunk.length;
+            else {
+                await appendOutbox(chunk);
+                buffered += chunk.length;
+            }
+        }
+        return { delivered, buffered };
+    }
+    async function close() {
+        closed = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        await flush();
+    }
+    return {
+        emit,
+        flush,
+        close,
+        pendingCount: () => pending.length,
+    };
+}
+//# sourceMappingURL=stream.js.map

package/dist/lib/telemetry/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/lib/telemetry/stream.ts"],"names":[],"mappings":"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"}

package/dist/lib/telemetry.d.ts

@@ -30,6 +30,12 @@ export interface ComposeEvent {
     partner: string | null;
     industry: string | null;
     durationMs: number;
+    /** Template-library version the diverse-serve selector WOULD pick for
+     * this compose. Null when the family isn't in the library. Observability
+     * signal only — compose still resolves files from registry/. */
+    templateVersion?: string | null;
+    /** Whether STARTER_FOUNDRY_DIVERSE_SERVE was set at compose time. */
+    diverseServe?: boolean;
 }
 export interface CapabilityEvent {
     family: string;
@@ -45,17 +51,6 @@ type EventHandler<T> = (event: T) => void;
 export declare function on<K extends keyof TelemetryEvents>(event: K, handler: EventHandler<TelemetryEvents[K]>): void;
 export declare function off<K extends keyof TelemetryEvents>(event: K, handler: EventHandler<TelemetryEvents[K]>): void;
 export declare function emit<K extends keyof TelemetryEvents>(event: K, data: TelemetryEvents[K]): void;
-interface OtelSpan {
-    setAttribute(key: string, value: string | number | boolean): void;
-    setStatus(status: {
-        code: number;
-        message?: string;
-    }): void;
-    end(): void;
-}
-export declare function startSpan(name: string): OtelSpan | null;
-export declare function endSpan(span: OtelSpan | null, attrs?: Record<string, string | number | boolean>): void;
-export declare function failSpan(span: OtelSpan | null, error: string): void;
 export declare function traced<T>(name: string, fn: () => Promise<T>): Promise<{
     result: T;
     durationMs: number;

package/dist/lib/telemetry.js

@@ -60,10 +60,10 @@ function getTracer() {
     const api = getOtel();
     return api?.trace.getTracer('starter-foundry', '0.1.0') ?? null;
 }
-export function startSpan(name) {
+function startSpan(name) {
     return getTracer()?.startSpan(name) ?? null;
 }
-export function endSpan(span, attrs) {
+function endSpan(span, attrs) {
     if (!span)
         return;
     if (attrs) {
@@ -76,7 +76,7 @@ export function endSpan(span, attrs) {
         span.setStatus({ code: api.SpanStatusCode.OK });
     span.end();
 }
-export function failSpan(span, error) {
+function failSpan(span, error) {
     if (!span)
         return;
     const api = getOtel();

package/dist/lib/telemetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqCH,MAAM,QAAQ,GAA0E,EAAE,CAAA;AAE1F,MAAM,UAAU,EAAE,CAAkC,KAAQ,EAAE,OAAyC;IACrG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,CAAA;IAC1C,QAAQ,CAAC,KAAK,CAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,GAAG,CAAkC,KAAQ,EAAE,OAAyC;IACtG,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC5B,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IACjC,IAAI,GAAG,IAAI,CAAC;QAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;AACnC,CAAC;AAED,MAAM,UAAU,IAAI,CAAkC,KAAQ,EAAE,IAAwB;IACtF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC5B,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAA;QACf,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;IACH,CAAC;AACH,CAAC;AAwBD,IAAI,OAAO,GAAmB,IAAI,CAAA;AAClC,IAAI,YAAY,GAAG,KAAK,CAAA;AAExB,SAAS,OAAO;IACd,IAAI,YAAY;QAAE,OAAO,OAAO,CAAA;IAChC,YAAY,GAAG,IAAI,CAAA;IACnB,IAAI,CAAC;QACH,8DAA8D;QAC9D,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAY,CAAA;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,IAAI,CAAA;IAChB,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,SAAS,SAAS;IAChB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAA;IACrB,OAAO,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC,IAAI,IAAI,CAAA;AACjE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,SAAS,EAAE,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAqB,EAAE,KAAiD;IAC9F,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACzB,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,EAAE,CAAA;IACrB,IAAI,GAAG;QAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC,CAAA;IACxD,IAAI,CAAC,GAAG,EAAE,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAqB,EAAE,KAAa;IAC3D,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,MAAM,GAAG,GAAG,OAAO,EAAE,CAAA;IACrB,IAAI,GAAG;QAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAC3E,IAAI,CAAC,GAAG,EAAE,CAAA;AACZ,CAAC;AAED,uCAAuC;AAEvC,MAAM,CAAC,KAAK,UAAU,MAAM,CAAI,IAAY,EAAE,EAAoB;IAChE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAA;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAA;QACzB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAA;QACxD,OAAO,CAAC,IAAI,EAAE,EAAE,6BAA6B,EAAE,UAAU,EAAE,CAAC,CAAA;QAC5D,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;IAC/B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAChE,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/lib/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/lib/template-quality.d.ts

@@ -0,0 +1,61 @@
+interface AuditPhase {
+    phase: string;
+    ok?: boolean;
+    skipped?: string;
+    durationMs?: number;
+    checksTotal?: number;
+    checksPassed?: number;
+}
+interface AuditReport {
+    layerId: string;
+    family?: string;
+    pm?: string;
+    skipped?: string;
+    phases?: AuditPhase[];
+}
+interface EnrichmentSummary {
+    familyId: string;
+    completed: boolean;
+    shotsUsed: number;
+    finalPass: boolean;
+    finalScore?: number;
+    wallMs: number;
+    shots: Array<{
+        shot: number;
+        pass: boolean;
+        durationMs: number;
+    }>;
+}
+interface QualityScore {
+    score: number;
+    /** Individual weighted components that sum to `score`. */
+    components: {
+        validationPass: number;
+        bundleBuildOk: number;
+        typecheckOk: number;
+        installOk: number;
+        richness: number;
+        firstShotBonus: number;
+        freshness: number;
+    };
+    /** Raw dimensions — useful for debugging, not part of the score. */
+    dimensions: {
+        installMs: number | null;
+        buildMs: number | null;
+        tscMs: number | null;
+        validationMs: number | null;
+        fileCount: number;
+        shotsUsed: number;
+        daysOld: number;
+    };
+}
+interface ScoreInput {
+    audit: AuditReport;
+    summary?: EnrichmentSummary | null;
+    /** Number of files in the layer's files/ directory (1 point per file, capped). */
+    fileCount: number;
+    /** Version creation timestamp. */
+    createdAt: string;
+}
+export declare function scoreVersion(input: ScoreInput): QualityScore;
+export {};

package/dist/lib/template-quality.js

@@ -0,0 +1,84 @@
+// Quality scoring for template-library versions. Computed from the audit
+// output + the enrichment run's summary. Used by promote-template.mjs to
+// pick `current` and by gc-template-library.mjs to decide what to keep.
+//
+// Formula is stable and deterministic so re-runs produce reproducible
+// rankings — a version's score never drifts unless the raw audit/summary
+// changes. Weights live here (not in the scripts) so tuning is one-file.
+const WEIGHTS = {
+    validationPass: 0.30,
+    bundleBuildOk: 0.25,
+    typecheckOk: 0.15,
+    installOk: 0.10,
+    richness: 0.10,
+    firstShotBonus: 0.05,
+    freshness: 0.05,
+};
+function phaseOk(audit, name) {
+    const p = audit.phases?.find((ph) => ph.phase === name);
+    if (!p)
+        return null;
+    if (p.skipped)
+        return true; // skip-clean (e.g., no-tsconfig) counts as ok
+    return p.ok === true;
+}
+function phaseMs(audit, name) {
+    const p = audit.phases?.find((ph) => ph.phase === name);
+    if (!p || typeof p.durationMs !== 'number')
+        return null;
+    return p.durationMs;
+}
+function validationScore(audit) {
+    const p = audit.phases?.find((ph) => ph.phase === 'validationChecks');
+    if (!p)
+        return 0;
+    if (p.skipped === 'none-declared')
+        return 0.5; // no ground truth declared — partial credit
+    if (p.skipped)
+        return 0;
+    if (typeof p.checksTotal === 'number' && typeof p.checksPassed === 'number' && p.checksTotal > 0) {
+        return p.checksPassed / p.checksTotal;
+    }
+    return p.ok === true ? 1 : 0;
+}
+export function scoreVersion(input) {
+    const { audit, summary, fileCount, createdAt } = input;
+    const validation = validationScore(audit);
+    const buildOk = phaseOk(audit, 'build');
+    const tscOk = phaseOk(audit, 'typecheck');
+    const installOk = phaseOk(audit, 'install');
+    // Build: if phase absent (not run), give full credit so the bar isn't
+    // retroactively applied to v1 snapshots that predated --build.
+    const buildComponent = buildOk === null ? 1 : buildOk ? 1 : 0;
+    const tscComponent = tscOk === null ? 0 : tscOk ? 1 : 0;
+    const installComponent = installOk === null ? 0 : installOk ? 1 : 0;
+    const richness = Math.min(1, fileCount / 10);
+    const shotsUsed = summary?.shotsUsed ?? 0;
+    const firstShotBonus = shotsUsed === 1 ? 1 : shotsUsed <= 3 ? 0.5 : shotsUsed <= 10 ? 0.2 : 0;
+    const daysOld = Math.max(0, (Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24));
+    const freshness = Math.max(0, 1 - Math.min(1, daysOld / 365));
+    const components = {
+        validationPass: WEIGHTS.validationPass * validation,
+        bundleBuildOk: WEIGHTS.bundleBuildOk * buildComponent,
+        typecheckOk: WEIGHTS.typecheckOk * tscComponent,
+        installOk: WEIGHTS.installOk * installComponent,
+        richness: WEIGHTS.richness * richness,
+        firstShotBonus: WEIGHTS.firstShotBonus * firstShotBonus,
+        freshness: WEIGHTS.freshness * freshness,
+    };
+    const score = Object.values(components).reduce((a, b) => a + b, 0);
+    return {
+        score: Math.max(0, Math.min(1, score)),
+        components,
+        dimensions: {
+            installMs: phaseMs(audit, 'install'),
+            buildMs: phaseMs(audit, 'build'),
+            tscMs: phaseMs(audit, 'typecheck'),
+            validationMs: phaseMs(audit, 'validationChecks'),
+            fileCount,
+            shotsUsed,
+            daysOld,
+        },
+    };
+}
+//# sourceMappingURL=template-quality.js.map

package/dist/lib/template-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-quality.js","sourceRoot":"","sources":["../../src/lib/template-quality.ts"],"names":[],"mappings":"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"}

package/dist/lib/validate-plan.d.ts

@@ -0,0 +1,10 @@
+import type { ComposeSpec, WorkspaceSpec } from '../types.js';
+export interface PlanValidationIssue {
+    path: string;
+    message: string;
+}
+export interface PlanValidationResult {
+    ok: boolean;
+    issues: PlanValidationIssue[];
+}
+export declare function validatePlan(spec: ComposeSpec | WorkspaceSpec): Promise<PlanValidationResult>;

package/dist/lib/validate-plan.js

@@ -0,0 +1,74 @@
+// Pre-compose validation for a ComposeSpec or WorkspaceSpec.
+// Downstream consumers (blueprint-agent, VB, any bench) can call this to
+// ensure a plan will compose cleanly without actually writing files.
+//
+// Checks:
+//   - family exists in the loaded registry
+//   - every referenced layer exists
+//   - each layer's appliesTo includes the family
+//   - partner (if present) exists and is compatible with the family
+//   - every slot selection is in the family's slot options
+//
+// Does NOT check: file-render outcomes, validation-check command success.
+// Those require the compose step to actually run.
+import { loadRegistry } from './registry.js';
+export async function validatePlan(spec) {
+    const registry = await loadRegistry();
+    const issues = [];
+    const check = (s, path) => {
+        const family = registry.families.get(s.family);
+        if (!family) {
+            issues.push({ path: `${path}.family`, message: `unknown family "${s.family}"` });
+            return;
+        }
+        for (const layerRef of s.layers ?? []) {
+            const layer = registry.layers.get(layerRef);
+            if (!layer) {
+                issues.push({ path: `${path}.layers`, message: `unknown layer "${layerRef}"` });
+                continue;
+            }
+            if (Array.isArray(layer.appliesTo) && !layer.appliesTo.includes(s.family)) {
+                issues.push({
+                    path: `${path}.layers`,
+                    message: `layer "${layerRef}" does not apply to family "${s.family}" (appliesTo: ${layer.appliesTo.join(', ')})`,
+                });
+            }
+        }
+        if (s.partner) {
+            const partner = registry.partners.get(s.partner);
+            if (!partner) {
+                issues.push({ path: `${path}.partner`, message: `unknown partner "${s.partner}"` });
+            }
+            else if (Array.isArray(partner.appliesTo) && !partner.appliesTo.includes(s.family)) {
+                issues.push({
+                    path: `${path}.partner`,
+                    message: `partner "${s.partner}" does not apply to family "${s.family}" (appliesTo: ${partner.appliesTo.join(', ')})`,
+                });
+            }
+        }
+        for (const [slotName, selection] of Object.entries(s.slots ?? {})) {
+            const slotConfig = family.slots?.[slotName];
+            if (!slotConfig) {
+                issues.push({ path: `${path}.slots.${slotName}`, message: `family "${s.family}" has no slot "${slotName}"` });
+                continue;
+            }
+            if (Array.isArray(slotConfig.options) && !slotConfig.options.includes(selection)) {
+                issues.push({
+                    path: `${path}.slots.${slotName}`,
+                    message: `slot "${slotName}" selection "${selection}" not in options (${slotConfig.options.join(', ')})`,
+                });
+            }
+        }
+    };
+    if ('projects' in spec) {
+        for (let i = 0; i < spec.projects.length; i++) {
+            const project = spec.projects[i];
+            check(project.spec, `projects[${i}]`);
+        }
+    }
+    else {
+        check(spec, 'spec');
+    }
+    return { ok: issues.length === 0, issues };
+}
+//# sourceMappingURL=validate-plan.js.map

package/dist/lib/validate-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-plan.js","sourceRoot":"","sources":["../../src/lib/validate-plan.ts"],"names":[],"mappings":"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"}

package/dist/lib/vb-outcomes.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shape of events emitted by blueprint-agent / vibecode-bench (VB) to
+ * `<starter-foundry-root>/.evolve/traces/vb-execution-<variant>.jsonl`.
+ * The producer lives in blueprint-agent repo (lib/vb-execution-trace.ts)
+ * commit 9f9e381f4. This is the real-outcome signal the training loop
+ * was missing — every event is a full downstream scaffold buildout
+ * with its labeled pass/fail outcome per layer category.
+ */
+export interface VBExecutionTrace {
+    scenarioId: string;
+    partner: string;
+    latencyMs: number;
+    timestamp: string;
+    error: string | null;
+    execution: {
+        verticalId: string;
+        generation: number;
+        variantName: string;
+        model: string;
+        outcome: 'satisfied' | 'max-wall-time' | 'error' | string;
+        blendedScore: number;
+        allPass: boolean;
+        failingLayers: string[];
+        shotsToConvergence: number | null;
+        shotsRun: number;
+        wallMs: number;
+        totalCostUsd: number | null;
+        toolCallsTotal: number;
+        toolCallSuccesses: number;
+        toolCallFailures: number;
+        filesTouchedCount: number;
+        bashCommandsTop: Array<{
+            cmd: string;
+            count: number;
+        }>;
+        sessionDir: string;
+    };
+}
+/** Aggregate stats per scenarioId — the training-relevant projection. */
+interface ScenarioOutcome {
+    scenarioId: string;
+    partner: string;
+    runs: number;
+    passed: number;
+    passRate: number;
+    meanBlendedScore: number;
+    meanWallMs: number;
+    meanToolCalls: number;
+    failingLayersByKind: Record<string, number>;
+    failingLayersPerRun: number;
+}
+/** Load every VB trace file from the traces directory. */
+export declare function loadVBTraces(tracesDir?: string): Promise<VBExecutionTrace[]>;
+/** Roll up per-scenario stats. */
+export declare function aggregateByScenario(traces: VBExecutionTrace[]): ScenarioOutcome[];
+/** Flat failure-category histogram across every trace. */
+export declare function failingLayerHistogram(traces: VBExecutionTrace[]): Record<string, number>;
+/** Scenarios with zero pass rate — the scaffolds that never build. */
+export declare function brokenScenarios(outcomes: ScenarioOutcome[]): ScenarioOutcome[];
+/** Scenarios consistently reaching satisfied — high-confidence positives. */
+export declare function strongScenarios(outcomes: ScenarioOutcome[]): ScenarioOutcome[];
+export {};

package/dist/lib/vb-outcomes.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/** Load every VB trace file from the traces directory. */
+export async function loadVBTraces(tracesDir = '.evolve/traces') {
+    let entries;
+    try {
+        entries = await fs.readdir(tracesDir);
+    }
+    catch {
+        return [];
+    }
+    const files = entries.filter((f) => f.startsWith('vb-execution-') && f.endsWith('.jsonl'));
+    const all = [];
+    for (const file of files) {
+        const raw = await fs.readFile(path.join(tracesDir, file), 'utf8');
+        for (const line of raw.trim().split('\n')) {
+            if (!line)
+                continue;
+            try {
+                all.push(JSON.parse(line));
+            }
+            catch {
+                // skip malformed
+            }
+        }
+    }
+    return all;
+}
+/** Roll up per-scenario stats. */
+export function aggregateByScenario(traces) {
+    const byScenario = new Map();
+    for (const t of traces) {
+        const key = `${t.scenarioId}::${t.partner}`;
+        let s = byScenario.get(key);
+        if (!s) {
+            s = {
+                scenarioId: t.scenarioId,
+                partner: t.partner,
+                runs: 0,
+                passed: 0,
+                passRate: 0,
+                meanBlendedScore: 0,
+                meanWallMs: 0,
+                meanToolCalls: 0,
+                failingLayersByKind: {},
+                failingLayersPerRun: 0,
+            };
+            byScenario.set(key, s);
+        }
+        s.runs++;
+        if (t.execution.allPass)
+            s.passed++;
+        s.meanBlendedScore += t.execution.blendedScore;
+        s.meanWallMs += t.execution.wallMs;
+        s.meanToolCalls += t.execution.toolCallsTotal;
+        for (const layer of t.execution.failingLayers ?? []) {
+            s.failingLayersByKind[layer] = (s.failingLayersByKind[layer] ?? 0) + 1;
+        }
+    }
+    for (const s of byScenario.values()) {
+        s.passRate = s.runs > 0 ? s.passed / s.runs : 0;
+        s.meanBlendedScore /= s.runs || 1;
+        s.meanWallMs /= s.runs || 1;
+        s.meanToolCalls /= s.runs || 1;
+        s.failingLayersPerRun =
+            Object.values(s.failingLayersByKind).reduce((a, b) => a + b, 0) / (s.runs || 1);
+    }
+    return [...byScenario.values()].sort((a, b) => b.passRate - a.passRate);
+}
+/** Flat failure-category histogram across every trace. */
+export function failingLayerHistogram(traces) {
+    const hist = {};
+    for (const t of traces) {
+        for (const layer of t.execution.failingLayers ?? []) {
+            hist[layer] = (hist[layer] ?? 0) + 1;
+        }
+    }
+    return hist;
+}
+/** Scenarios with zero pass rate — the scaffolds that never build. */
+export function brokenScenarios(outcomes) {
+    return outcomes.filter((o) => o.passRate === 0 && o.runs >= 2);
+}
+/** Scenarios consistently reaching satisfied — high-confidence positives. */
+export function strongScenarios(outcomes) {
+    return outcomes.filter((o) => o.passRate === 1 && o.meanBlendedScore >= 0.9 && o.runs >= 2);
+}
+//# sourceMappingURL=vb-outcomes.js.map

package/dist/lib/vb-outcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vb-outcomes.js","sourceRoot":"","sources":["../../src/lib/vb-outcomes.ts"],"names":[],"mappings":"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"}

package/dist/lib/version-history.d.ts

@@ -0,0 +1,15 @@
+export interface RollbackRecord {
+    schemaVersion: 1;
+    loggedAt: string;
+    fromVersion: string;
+    toTag: string;
+    newVersion: string;
+    reason: string;
+    dryRun?: boolean;
+    actor?: string;
+}
+/** Version that was rolled back AWAY from — consumers should avoid pinning this. */
+export declare function isVersionRolledBack(version: string): boolean;
+/** Returns the latest version we've seen a successful rollback to (or null). */
+export declare function getLastKnownGoodVersion(): string | null;
+export declare function listRollbacks(): RollbackRecord[];