@idlekit/core 0.2.1 → 0.3.0

package/dist/sim/analysis/analyzers.js

@@ -0,0 +1,1076 @@
+import { analyzeGrowth } from "./growth";
+import { etaAnalytic, etaEstimateAlgorithmVersion, etaEstimateSchemaId, etaSimulate, } from "./eta";
+import { observationContract } from "../observation";
+import { createRunFactory } from "../runFactory";
+import { runScenario } from "../simulator";
+/**
+ * Analyzer registry.
+ * ModelAnalysisAdapter stays the model-capability registry.
+ * This module wraps growth and ETA. It does not fit growth or divide amounts again.
+ * Jev is not an analyzer. This file does not import the CLI, a network stack, or the filesystem.
+ */
+const GROWTH_ANALYZER_ID = "growth";
+const GROWTH_ANALYZER_VERSION = "1";
+const GROWTH_ANALYZER_ALGORITHM_VERSION = "growth-report-v1";
+const ETA_ANALYZER_ID = "eta";
+const ETA_ANALYZER_VERSION = "1";
+const GROWTH_OUTPUT_CONTRACT = "idlekit.growth-report.v1";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-registry-conflicts Duplicate ids, cycles, missing dependencies, and bad params fail before a body runs.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-registry-conflicts #ddadf25 Re-read the section: a thrown body is an error result and a postprocess fresh-run cost is refused, an explicit dependency with other semantics and a malformed body result are handled before dependents run, a malformed validateParams result, bad semantics, a cycle, a duplicate, a missing dependency, bad params, an incomplete definition, a fresh-run cost above one, a version with @, and a malformed resolved demand do not call the body, an implied dependency takes its parent's semantics, and a dependent of a failed dependency does not run.
+ */
+export const analyzerRegistryConflicts = "fail-before-run";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-custom-analyzer A caller registers a metric and an analyzer. Core does not name that metric.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-custom-analyzer #0eb3cb9 Re-read the section: the caller-owned metric stays outside the builtin list, and a resolved demand names the metrics checked.
+ */
+export const analyzerCustomRegistration = "caller-metric-and-analyzer";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-insufficient-observation A short observation returns insufficient-data and a rerun plan. The growth body is not called.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-insufficient-observation #0be001c Re-read the section: summary coverage does not satisfy a trace demand, a malformed supply meets nothing, a postprocess sample cost is budgeted, and the registry checks every postprocess demand before the body.
+ */
+export const analyzerInsufficientObservation = "insufficient-observation-rerun-plan";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-execution-budget An execution analyzer receives a RunFactory and a budget. A short budget does not start the body.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-execution-budget #2ec64cc Re-read the section: ETA semantics must match the scenario step and seed, a refused grant is not cached for the group, a strategyKey other than the scenario strategy throws, each member reserves its own cost in dependency order, horizon past the budget is refused, a zero run budget does not call execute, samples are reserved across the batch, blocked groups and groups skipped for a failed dependency reserve nothing, a NaN budget throws, missing-scenario is kept, analytic ETA costs no run, and simulated ETA is checked on maxDurationSec.
+ */
+export const analyzerExecutionBudget = "explicit-budget-not-silent-run";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-same-algorithm Growth and ETA adapters return the existing algorithm version and the existing numeric value.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-same-algorithm #162ee6f Re-read the section: the growth report is analyzeGrowth, and ETA seconds stay on eta-estimate-v1.
+ */
+export const analyzerSameAlgorithm = "adapter-keeps-algorithm-version";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-observation-plan The same session, strategy, horizon, and observation semantics share one fresh run. A different horizon does not.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-observation-plan #2fa0460 Re-read the section: a failed shared run is attempted once, freshScenario gives each group run its own compile, a traced window finer than the trace spacing is refused, sharedWith lists only members whose body ran, cadence rounds down onto the execution plan and is on provenance, a cadence without a trace is refused, a different horizon or a sharesRun false definition is a separate group, the key is JSON, group members get one shared RunResult, and blocked peers are not in sharedWith.
+ */
+export const analyzerObservationPlan = "demand-on-plan-and-provenance";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-plugin-isolation A plugin analyzer is refused before permission. One rejected definition does not drop builtins.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-plugin-isolation #cf67732 Re-read the section: allow-plugin is required, and a duplicate registration is isolated.
+ */
+export const analyzerPluginIsolation = "permission-before-load-and-isolate-failure";
+/**
+ * @evidence docs/requirements/active/analyzer-registry.md#req-dx02-local-output JSON and Markdown render the result. The default path does not use a network, and Jev is not registered.
+ * @evidenceReview docs/requirements/active/analyzer-registry.md#req-dx02-local-output #ab80c47 Re-read the section: the markdown fence contains the algorithm version, and the builtin ids are eta and growth.
+ */
+export const analyzerLocalOutput = "json-markdown-local-not-judge";
+export const analyzerNotJudge = "analyzer-creates-evidence-judge-interprets";
+export function growthAnalyzerAlgorithmVersion() {
+    return GROWTH_ANALYZER_ALGORITHM_VERSION;
+}
+export class AnalyzerRegistryError extends Error {
+    issues;
+    constructor(message, issues = [message]) {
+        super(message);
+        this.name = "AnalyzerRegistryError";
+        this.issues = issues;
+    }
+}
+const coverageRank = {
+    missing: 0,
+    summary: 1,
+    window: 2,
+    trace: 3,
+};
+export function analyzerSemantics(overrides = {}) {
+    return {
+        sessionKey: "none",
+        strategyKey: "none",
+        horizonSec: 1,
+        stepSec: 1,
+        seed: null,
+        ...overrides,
+    };
+}
+export function observationDemand(overrides = {}) {
+    return {
+        windowSec: null,
+        sampleCadenceSec: null,
+        coverage: "summary",
+        metricIds: [],
+        observationSchema: observationContract,
+        ...overrides,
+    };
+}
+export function analyzerKey(id, version) {
+    return `${id}@${version}`;
+}
+function compareIdentity(left, right) {
+    if (left.id < right.id)
+        return -1;
+    if (left.id > right.id)
+        return 1;
+    if (left.version < right.version)
+        return -1;
+    if (left.version > right.version)
+        return 1;
+    return 0;
+}
+/** A supply from a runtime caller is checked first: NaN or an unknown coverage would pass every comparison. */
+function supplyIsWellFormed(supply) {
+    const temporal = (value) => value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0);
+    return (typeof supply.schema === "string" &&
+        Object.prototype.hasOwnProperty.call(coverageRank, supply.coverage) &&
+        temporal(supply.windowSec) &&
+        temporal(supply.sampleCadenceSec) &&
+        Array.isArray(supply.metricIds) &&
+        supply.metricIds.every((metricId) => typeof metricId === "string"));
+}
+export function observationMeets(demand, supply) {
+    if (!supply || typeof supply !== "object" || !supplyIsWellFormed(supply))
+        return false;
+    if (supply.schema !== demand.observationSchema)
+        return false;
+    if (coverageRank[supply.coverage] < coverageRank[demand.coverage])
+        return false;
+    if (demand.windowSec !== null) {
+        if (supply.windowSec === null || supply.windowSec > demand.windowSec)
+            return false;
+    }
+    if (demand.sampleCadenceSec !== null) {
+        if (supply.sampleCadenceSec === null || supply.sampleCadenceSec > demand.sampleCadenceSec)
+            return false;
+    }
+    for (const metricId of demand.metricIds) {
+        if (!supply.metricIds.includes(metricId))
+            return false;
+    }
+    return true;
+}
+// Absorbs float division noise such as 0.3 / 0.1, so an exact multiple is not rounded one step finer.
+const cadenceTolerance = 1e-9;
+export function executionPlanForDemand(semantics, demand) {
+    const cadence = demand.sampleCadenceSec;
+    // Round down: the traced cadence must not be coarser than the demand. A demand finer than one
+    // step still gets every step, and the registry refuses that plan as unable to meet the demand.
+    const everySteps = cadence === null ? 1 : Math.max(1, Math.floor(cadence / semantics.stepSec + cadenceTolerance));
+    const traced = demand.coverage === "window" || demand.coverage === "trace";
+    return {
+        contract: "idlekit.execution-plan",
+        version: 1,
+        stepSec: semantics.stepSec,
+        durationSec: semantics.horizonSec,
+        ...(semantics.seed === null ? {} : { seed: semantics.seed }),
+        strategyId: semantics.strategyKey,
+        ...(traced ? { trace: { everySteps, keepActionsLog: false } } : {}),
+    };
+}
+function planMeetsDemand(plan, demand) {
+    const spacing = plan.trace ? plan.stepSec * (plan.trace.everySteps ?? 1) : null;
+    // A traced window finer than the trace spacing cannot be resolved from that trace.
+    if (demand.windowSec !== null && spacing !== null && spacing > demand.windowSec * (1 + cadenceTolerance)) {
+        return false;
+    }
+    if (demand.sampleCadenceSec === null)
+        return true;
+    // A cadence with summary coverage gets no trace, so the plan has no samples at that cadence.
+    if (spacing === null)
+        return false;
+    return spacing <= demand.sampleCadenceSec * (1 + cadenceTolerance);
+}
+export function analyzerModuleBoundaryIssues(source) {
+    const rules = [
+        [/from\s+["']@idlekit\/cli["']/, "cli"],
+        [/from\s+["'][^"']*\/jev[^"']*["']/, "jev"],
+        [/from\s+["']node:fs["']/, "filesystem"],
+        [/from\s+["']fs["']/, "filesystem"],
+        [/from\s+["']node:https?["']/, "network"],
+        [/from\s+["']node:net["']/, "network"],
+        [/\bfetch\s*\(/, "network"],
+    ];
+    return rules.filter(([pattern]) => pattern.test(source)).map(([, issue]) => issue);
+}
+export function assertAnalyzerPluginsPermitted(allowPlugin, pluginPaths) {
+    if (pluginPaths.length > 0 && !allowPlugin) {
+        throw new AnalyzerRegistryError("Plugin loading is disabled by default. Pass --allow-plugin true to enable local plugin modules.");
+    }
+}
+export function registerAnalyzerIsolated(registry, definition) {
+    try {
+        registry.register(definition);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : "analyzer registration failed";
+    }
+}
+export function analyzerResultMarkdown(result) {
+    return `\`\`\`json\n${JSON.stringify(result, null, 2)}\n\`\`\``;
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isCount(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isIdentity(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const item = value;
+    return isNonEmptyString(item.id) && isVersion(item.version);
+}
+/** No `@` in a version, so `id@version` splits at its last `@` and two identities never share a key. */
+function isVersion(value) {
+    return isNonEmptyString(value) && !value.includes("@");
+}
+function demandIssues(label, value) {
+    if (!value || typeof value !== "object")
+        return [`${label} must be an object`];
+    const demand = value;
+    const issues = [];
+    if (demand.windowSec !== null && !isCount(demand.windowSec))
+        issues.push(`${label}.windowSec must be null or a number`);
+    if (demand.sampleCadenceSec !== null && !isCount(demand.sampleCadenceSec)) {
+        issues.push(`${label}.sampleCadenceSec must be null or a number`);
+    }
+    if (demand.coverage !== "summary" && demand.coverage !== "window" && demand.coverage !== "trace") {
+        issues.push(`${label}.coverage must be summary, window, or trace`);
+    }
+    if (!isStringList(demand.metricIds))
+        issues.push(`${label}.metricIds must be a string list`);
+    if (!isNonEmptyString(demand.observationSchema))
+        issues.push(`${label}.observationSchema must be a string`);
+    return issues;
+}
+/** A group shares one fresh run, so a declared cost above one run could not be honored. */
+function costIssues(value) {
+    const cost = value;
+    if (!cost || typeof cost !== "object" || (cost.freshRuns !== 0 && cost.freshRuns !== 1) || !isCount(cost.samples)) {
+        return ["cost.freshRuns must be 0 or 1 and cost.samples a number >= 0"];
+    }
+    return [];
+}
+/** A plugin definition is a runtime value. Every field `run` reads is checked before the definition is stored. */
+function assertDefinition(input) {
+    if (!input || typeof input !== "object")
+        throw new AnalyzerRegistryError("analyzer definition must be an object");
+    const definition = input;
+    if (!isNonEmptyString(definition.id) || !isNonEmptyString(definition.version)) {
+        throw new AnalyzerRegistryError("analyzer id and version are required");
+    }
+    if (!isVersion(definition.version)) {
+        throw new AnalyzerRegistryError(`analyzer version must not contain @ (${definition.id})`);
+    }
+    const key = analyzerKey(definition.id, definition.version);
+    if (definition.kind !== "postprocess" && definition.kind !== "execution") {
+        throw new AnalyzerRegistryError(`unsupported analyzer kind for ${key}`);
+    }
+    if (definition.kind === "postprocess" && typeof definition.postprocess !== "function") {
+        throw new AnalyzerRegistryError(`postprocess analyzer ${definition.id} has no postprocess body`);
+    }
+    if (definition.kind === "execution" && typeof definition.execute !== "function") {
+        throw new AnalyzerRegistryError(`execution analyzer ${definition.id} has no execute body`);
+    }
+    const issues = [];
+    if (typeof definition.validateParams !== "function")
+        issues.push("validateParams must be a function");
+    if (definition.resolveDemand !== undefined && typeof definition.resolveDemand !== "function") {
+        issues.push("resolveDemand must be a function");
+    }
+    if (definition.resolveCost !== undefined && typeof definition.resolveCost !== "function") {
+        issues.push("resolveCost must be a function");
+    }
+    if (definition.sharesRun !== undefined && typeof definition.sharesRun !== "boolean") {
+        issues.push("sharesRun must be a boolean");
+    }
+    const requires = definition.requires;
+    if (!requires || typeof requires !== "object") {
+        issues.push("requires must be an object");
+    }
+    else {
+        if (!isStringList(requires.capabilities))
+            issues.push("requires.capabilities must be a string list");
+        if (!isStringList(requires.metricIds))
+            issues.push("requires.metricIds must be a string list");
+        if (!isNonEmptyString(requires.observationSchema))
+            issues.push("requires.observationSchema must be a string");
+    }
+    issues.push(...demandIssues("observation", definition.observation));
+    if (!isNonEmptyString(definition.outputContract))
+        issues.push("outputContract must be a string");
+    if (!isNonEmptyString(definition.algorithmVersion))
+        issues.push("algorithmVersion must be a string");
+    issues.push(...costIssues(definition.cost));
+    if (definition.kind === "postprocess" && definition.cost?.freshRuns !== 0) {
+        issues.push("a postprocess analyzer cannot request a run, so cost.freshRuns must be 0");
+    }
+    if (!Array.isArray(definition.dependencies) || !definition.dependencies.every(isIdentity)) {
+        issues.push("dependencies must be a list of id and version");
+    }
+    if (issues.length > 0) {
+        throw new AnalyzerRegistryError(`incomplete analyzer ${key}: ${issues.join("; ")}`, issues);
+    }
+}
+function sameSemantics(left, right) {
+    return (left.sessionKey === right.sessionKey &&
+        left.strategyKey === right.strategyKey &&
+        left.horizonSec === right.horizonSec &&
+        left.stepSec === right.stepSec &&
+        left.seed === right.seed);
+}
+function introducesCycle(map, definition) {
+    const visiting = new Set();
+    const visit = (current) => {
+        const key = analyzerKey(current.id, current.version);
+        if (visiting.has(key))
+            return true;
+        visiting.add(key);
+        for (const dependency of current.dependencies) {
+            const next = map.get(analyzerKey(dependency.id, dependency.version));
+            if (!next)
+                continue;
+            if (visit(next))
+                return true;
+        }
+        visiting.delete(key);
+        return false;
+    };
+    return visit(definition);
+}
+function resolvedDemand(definition, params) {
+    return definition.resolveDemand ? definition.resolveDemand(params) : definition.observation;
+}
+function resolvedCost(definition, params) {
+    return definition.resolveCost ? definition.resolveCost(params) : definition.cost;
+}
+/** JSON of the fields, so a `|` or `,` inside a key cannot make two different groups equal. */
+function groupKey(definition, semantics, demand) {
+    return JSON.stringify([
+        definition.kind,
+        semantics.sessionKey,
+        semantics.strategyKey,
+        semantics.horizonSec,
+        semantics.stepSec,
+        semantics.seed,
+        demand.observationSchema,
+        demand.coverage,
+        demand.windowSec,
+        demand.sampleCadenceSec,
+        [...demand.metricIds].sort(),
+        definition.sharesRun === false ? analyzerKey(definition.id, definition.version) : null,
+    ]);
+}
+function rerunPlan(reason, demand, semantics, budget) {
+    const note = reason === "budget"
+        ? "refusing a fresh run that exceeds the explicit budget"
+        : reason === "execution-not-requested"
+            ? "refusing a fresh run that was not requested"
+            : reason === "missing-scenario"
+                ? "refusing a fresh run without a compiled scenario"
+                : "observation does not meet the analyzer demand";
+    return { reason, demand, semantics, budget, note };
+}
+function envelope(definition, status, value, issues, provenance) {
+    return {
+        schemaVersion: 1,
+        id: definition.id,
+        version: definition.version,
+        algorithmVersion: definition.algorithmVersion,
+        outputContract: definition.outputContract,
+        status,
+        kind: definition.kind,
+        issues,
+        provenance,
+        value,
+    };
+}
+function eligibilityBlock(definition, demand, request) {
+    const capability = capabilityStatus(definition, request.capabilities);
+    if (capability)
+        return { status: capability, issue: `capability ${capability}` };
+    // A parameter-resolved demand names the metrics this request reads. The static list is the union.
+    const needed = definition.resolveDemand ? demand.metricIds : definition.requires.metricIds;
+    const available = request.availableMetricIds;
+    if (available && needed.some((metricId) => !available.includes(metricId))) {
+        return { status: "unsupported", issue: "required metric is not registered" };
+    }
+    return null;
+}
+export function createAnalyzerRegistry() {
+    const map = new Map();
+    return {
+        register(definition) {
+            assertDefinition(definition);
+            const key = analyzerKey(definition.id, definition.version);
+            if (map.has(key))
+                throw new AnalyzerRegistryError(`duplicate analyzer ${key}`);
+            map.set(key, definition);
+            if (introducesCycle(map, definition)) {
+                map.delete(key);
+                throw new AnalyzerRegistryError(`dependency cycle at ${key}`);
+            }
+        },
+        get(id, version) {
+            return isVersion(version) ? map.get(analyzerKey(id, version)) : undefined;
+        },
+        list() {
+            return [...map.values()]
+                .map((definition) => ({ id: definition.id, version: definition.version }))
+                .sort(compareIdentity);
+        },
+        run(request) {
+            return runRegistered(map, request);
+        },
+    };
+}
+/** validateParams is plugin code, so its result is checked before `ok` or `params` is read. */
+function parseParams(definition, input, key) {
+    const parsed = definition.validateParams(input);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.ok !== "boolean") {
+        throw new AnalyzerRegistryError(`bad params result for ${key}: validateParams must return { ok }`);
+    }
+    const result = parsed;
+    if (result.ok === false) {
+        const issues = isStringList(result.issues) ? result.issues : ["validateParams returned no issue list"];
+        throw new AnalyzerRegistryError(`bad params for ${key}`, issues);
+    }
+    if (!("params" in result)) {
+        throw new AnalyzerRegistryError(`bad params result for ${key}: an ok result must carry params`);
+    }
+    return result.params;
+}
+function semanticsIssues(value) {
+    if (!value || typeof value !== "object")
+        return ["semantics must be an object"];
+    const semantics = value;
+    const issues = [];
+    if (typeof semantics.sessionKey !== "string")
+        issues.push("sessionKey must be a string");
+    if (typeof semantics.strategyKey !== "string")
+        issues.push("strategyKey must be a string");
+    const positive = (field) => typeof field === "number" && Number.isFinite(field) && field > 0;
+    if (!positive(semantics.horizonSec))
+        issues.push("horizonSec must be a finite number > 0");
+    if (!positive(semantics.stepSec))
+        issues.push("stepSec must be a finite number > 0");
+    if (semantics.seed !== null && !(typeof semantics.seed === "number" && Number.isFinite(semantics.seed))) {
+        issues.push("seed must be null or a finite number");
+    }
+    return issues;
+}
+/** NaN passes no comparison and JSON writes it as null, so it would slip past budgets and merge group keys. */
+function checkedSemantics(value, label) {
+    const issues = semanticsIssues(value);
+    if (issues.length > 0)
+        throw new AnalyzerRegistryError(`bad semantics for ${label}`, issues);
+    return value;
+}
+const analysisStatuses = new Set([
+    "ok",
+    "censored",
+    "unsupported",
+    "insufficient-data",
+    "invalid",
+    "error",
+    "unknown",
+]);
+const rerunReasons = new Set([
+    "insufficient-data",
+    "budget",
+    "execution-not-requested",
+    "missing-scenario",
+]);
+/** A thrown body is recorded as `error`, so the batch continues and dependents see the failure. */
+function callBody(call) {
+    try {
+        return checkedBody(call());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { status: "error", value: null, issues: [`analyzer body threw: ${message}`] };
+    }
+}
+/** A body is plugin code. A malformed result is recorded as `error`, so dependents see it failed. */
+function checkedBody(raw) {
+    const invalid = (issue) => ({ status: "error", value: null, issues: [issue] });
+    if (!raw || typeof raw !== "object")
+        return invalid("analyzer body returned no result object");
+    const body = raw;
+    if (typeof body.status !== "string" || !analysisStatuses.has(body.status)) {
+        return invalid("analyzer body returned an unknown status");
+    }
+    if (body.issues !== undefined && !isStringList(body.issues))
+        return invalid("analyzer body issues must be strings");
+    if (body.rerun !== undefined && typeof body.rerun !== "boolean")
+        return invalid("analyzer body rerun must be a boolean");
+    if (body.rerunReason !== undefined && (typeof body.rerunReason !== "string" || !rerunReasons.has(body.rerunReason))) {
+        return invalid("analyzer body rerunReason is unknown");
+    }
+    return raw;
+}
+/** A demand that asks for nothing observed is met without a supply. */
+function demandIsEmpty(demand) {
+    return (demand.coverage === "summary" &&
+        demand.windowSec === null &&
+        demand.sampleCadenceSec === null &&
+        demand.metricIds.length === 0);
+}
+function runRegistered(map, request) {
+    checkedSemantics(request.semantics, "the request");
+    // NaN fails every comparison, so an unchecked budget would admit every run.
+    const requestBudget = request.budget ?? null;
+    if (requestBudget &&
+        ![requestBudget.maxFreshRuns, requestBudget.maxDurationSec, requestBudget.maxSamples].every(isCount)) {
+        throw new AnalyzerRegistryError("budget limits must be finite numbers >= 0");
+    }
+    const seen = new Set();
+    const requested = [];
+    const params = new Map();
+    const semanticsByKey = new Map();
+    for (const entry of request.requests) {
+        const key = analyzerKey(entry.id, entry.version);
+        if (seen.has(key))
+            throw new AnalyzerRegistryError(`duplicate analyzer ${key}`);
+        seen.add(key);
+        const definition = isVersion(entry.version) ? map.get(key) : undefined;
+        if (!definition)
+            throw new AnalyzerRegistryError(`missing analyzer ${key}`);
+        const entryParams = parseParams(definition, entry.params, key);
+        requested.push(definition);
+        params.set(key, entryParams);
+        semanticsByKey.set(key, entry.semantics ? checkedSemantics(entry.semantics, key) : request.semantics);
+    }
+    // An unrequested dependency runs under the semantics of the analyzer that pulled it in.
+    // Two parents with different semantics would need two instances of one id, so that fails here.
+    const implicit = new Set();
+    const ordered = [];
+    const visiting = new Set();
+    const visit = (definition) => {
+        const key = analyzerKey(definition.id, definition.version);
+        if (ordered.some((item) => analyzerKey(item.id, item.version) === key))
+            return;
+        if (visiting.has(key))
+            throw new AnalyzerRegistryError(`dependency cycle at ${key}`);
+        visiting.add(key);
+        const parentSemantics = semanticsByKey.get(key) ?? request.semantics;
+        const dependencies = [...definition.dependencies].sort(compareIdentity);
+        for (const dependency of dependencies) {
+            const dependencyKey = analyzerKey(dependency.id, dependency.version);
+            const next = map.get(dependencyKey);
+            if (!next)
+                throw new AnalyzerRegistryError(`missing dependency ${dependencyKey}`);
+            if (!params.has(dependencyKey)) {
+                params.set(dependencyKey, parseParams(next, {}, dependencyKey));
+                semanticsByKey.set(dependencyKey, parentSemantics);
+                implicit.add(dependencyKey);
+            }
+            else {
+                // One instance per id serves every parent, so every parent must share its semantics,
+                // whether the dependency was implied or requested.
+                const current = semanticsByKey.get(dependencyKey) ?? request.semantics;
+                if (!sameSemantics(current, parentSemantics)) {
+                    throw new AnalyzerRegistryError(implicit.has(dependencyKey)
+                        ? `dependency ${dependencyKey} is implied with different semantics; request it with explicit semantics`
+                        : `dependency ${dependencyKey} is requested with different semantics than ${key}`);
+                }
+            }
+            visit(next);
+        }
+        visiting.delete(key);
+        ordered.push(definition);
+    };
+    for (const definition of [...requested].sort(compareIdentity))
+        visit(definition);
+    // `ordered` lists dependencies first, so a blocked dependency is known before its dependents.
+    const blockByKey = new Map();
+    const prepared = ordered.map((definition) => {
+        const key = analyzerKey(definition.id, definition.version);
+        const itemParams = params.get(key);
+        const semantics = semanticsByKey.get(key) ?? request.semantics;
+        const demand = resolvedDemand(definition, itemParams);
+        // resolveDemand is plugin code whose result depends on params, so it is checked per request.
+        const demandProblems = demandIssues("resolved demand", demand);
+        if (demandProblems.length > 0)
+            throw new AnalyzerRegistryError(`bad demand for ${key}`, demandProblems);
+        const cost = resolvedCost(definition, itemParams);
+        const costProblems = costIssues(cost);
+        if (costProblems.length > 0)
+            throw new AnalyzerRegistryError(`bad cost for ${key}`, costProblems);
+        if (definition.kind === "postprocess" && cost.freshRuns !== 0) {
+            throw new AnalyzerRegistryError(`bad cost for ${key}`, ["a postprocess analyzer cannot request a run"]);
+        }
+        const blockedDependency = definition.dependencies
+            .map((dependency) => analyzerKey(dependency.id, dependency.version))
+            .find((dependencyKey) => blockByKey.get(dependencyKey));
+        const dependencyBlock = blockedDependency ? blockByKey.get(blockedDependency) : null;
+        const block = eligibilityBlock(definition, demand, request) ??
+            (dependencyBlock && blockedDependency
+                ? { status: dependencyBlock.status, issue: `dependency ${blockedDependency} ${dependencyBlock.status}` }
+                : null);
+        blockByKey.set(key, block);
+        // The shared run executes the scenario's compiled strategy, so a different strategyKey would
+        // label and group one strategy's run as another's. `none` names no strategy.
+        const compiledStrategy = request.scenario?.strategy?.id ?? "none";
+        if (definition.kind === "execution" &&
+            request.scenario &&
+            semantics.strategyKey !== "none" &&
+            semantics.strategyKey !== compiledStrategy) {
+            throw new AnalyzerRegistryError(`strategy ${semantics.strategyKey} for ${key} is not the scenario strategy ${compiledStrategy}`);
+        }
+        return {
+            definition,
+            params: itemParams,
+            semantics,
+            demand,
+            cost,
+            key: groupKey(definition, semantics, demand),
+            block,
+        };
+    });
+    // Budget is reserved per member, when that member is reached in dependency order after its
+    // dependencies finished. A group holds at most one fresh run and its largest sample cost, so a
+    // member tops up the group's reservation by the difference. Blocked members and members skipped
+    // for a failed dependency are never admitted, so they reserve nothing for themselves or a peer.
+    const budget = request.budget ?? null;
+    const allowExecution = request.allowExecution === true;
+    const groupRefusal = new Map();
+    const groupReserved = new Map();
+    let reservedRuns = 0;
+    let reservedSamples = 0;
+    const runGroups = new Set();
+    const groupKeys = [...new Set(prepared.map((item) => item.key))].sort();
+    const refusalForGroup = (item) => {
+        if (groupRefusal.has(item.key))
+            return groupRefusal.get(item.key) ?? null;
+        const refusal = !allowExecution || !budget
+            ? "execution-not-requested"
+            : planMeetsDemand(executionPlanForDemand(item.semantics, item.demand), item.demand)
+                ? null
+                : "insufficient-data";
+        groupRefusal.set(item.key, refusal);
+        return refusal;
+    };
+    const admit = (item) => {
+        const refusal = refusalForGroup(item);
+        if (refusal || !budget)
+            return refusal ?? "execution-not-requested";
+        // Costs are 0 or 1 fresh runs (checked at register and on resolveCost): a group holds at most one.
+        const held = groupReserved.get(item.key) ?? { freshRuns: 0, samples: 0 };
+        const runs = Math.max(0, item.cost.freshRuns - held.freshRuns);
+        const samples = Math.max(0, item.cost.samples - held.samples);
+        if ((item.cost.freshRuns > 0 && item.semantics.horizonSec > budget.maxDurationSec) ||
+            reservedRuns + runs > budget.maxFreshRuns ||
+            reservedSamples + samples > budget.maxSamples) {
+            return "budget";
+        }
+        reservedRuns += runs;
+        reservedSamples += samples;
+        groupReserved.set(item.key, { freshRuns: held.freshRuns + runs, samples: held.samples + samples });
+        if (item.cost.freshRuns > 0)
+            runGroups.add(item.key);
+        return "run";
+    };
+    // sharedWith is filled in after the loop from the members whose body was actually called.
+    const participants = new Map();
+    const participate = (item, identity) => {
+        const list = participants.get(item.key) ?? [];
+        list.push(identity);
+        participants.set(item.key, list);
+    };
+    const sharedRuns = new Map();
+    const openSharedRun = (item, plan) => {
+        if (sharedRuns.has(item.key))
+            return sharedRuns.get(item.key) ?? null;
+        const scenario = request.scenario ?? null;
+        const factory = request.runFactory ?? null;
+        let result = null;
+        // The attempt is the group's one counted run: if it throws, peers get null instead of a second run.
+        sharedRuns.set(item.key, null);
+        if (scenario && factory) {
+            // A fresh compile per group run gives new model and strategy instances, so one group's run
+            // cannot start from closure state another run advanced.
+            const binding = factory.bind(request.freshScenario ? request.freshScenario() : scenario);
+            try {
+                // strategyKey groups runs. The strategy that runs is the one compiled into the scenario.
+                const { strategyId: _strategyKey, ...runPlan } = plan;
+                result = runScenario(binding.fresh({ trialId: `analyzer:${item.key}`, plan: runPlan }).scenario);
+            }
+            finally {
+                binding.release();
+            }
+        }
+        sharedRuns.set(item.key, result);
+        return result;
+    };
+    // Accepted grants are shared per group. A refusal is not cached for the group: it can come only
+    // from the group's reservation at that moment, and a later member may top the group up to a run.
+    const grants = new Map();
+    const itemGrants = new Map();
+    let freshRuns = 0;
+    const requestRun = (item, identity) => {
+        const grant = (() => {
+            const existing = grants.get(item.key);
+            if (existing)
+                return existing;
+            const plan = executionPlanForDemand(item.semantics, item.demand);
+            // A group that reserved no fresh run (cost 0) is refused, so an unbudgeted run is never opened.
+            if (!budget ||
+                !runGroups.has(item.key) ||
+                freshRuns >= budget.maxFreshRuns ||
+                item.semantics.horizonSec > budget.maxDurationSec) {
+                return { accepted: false, plan, run: () => null };
+            }
+            freshRuns += 1;
+            const accepted = { accepted: true, plan, run: () => openSharedRun(item, plan) };
+            grants.set(item.key, accepted);
+            return accepted;
+        })();
+        itemGrants.set(identity, grant);
+        return grant;
+    };
+    const results = [];
+    const statusByKey = new Map();
+    const record = (result) => {
+        statusByKey.set(analyzerKey(result.id, result.version), result.status);
+        results.push(result);
+    };
+    for (const item of prepared) {
+        const identity = analyzerKey(item.definition.id, item.definition.version);
+        const plan = executionPlanForDemand(item.semantics, item.demand);
+        const baseProvenance = {
+            demand: item.demand,
+            supply: request.supply ?? null,
+            semantics: item.semantics,
+            executionPlan: item.definition.kind === "execution" ? plan : null,
+            groupKey: item.key,
+            sharedWith: [],
+            budget,
+        };
+        if (item.block) {
+            record(envelope(item.definition, item.block.status, null, [item.block.issue], {
+                ...baseProvenance,
+                freshRuns: 0,
+                rerun: item.block.status === "insufficient-data"
+                    ? rerunPlan("insufficient-data", item.demand, item.semantics, budget)
+                    : null,
+            }));
+            continue;
+        }
+        // A dependency that ran but did not finish ok leaves its dependents without a prerequisite.
+        const failedDependency = item.definition.dependencies
+            .map((dependency) => analyzerKey(dependency.id, dependency.version))
+            .find((dependencyKey) => {
+            const status = statusByKey.get(dependencyKey);
+            return status !== undefined && status !== "ok";
+        });
+        if (failedDependency) {
+            record(envelope(item.definition, "insufficient-data", null, [`dependency ${failedDependency} ${statusByKey.get(failedDependency)}`], {
+                ...baseProvenance,
+                freshRuns: 0,
+                rerun: rerunPlan("insufficient-data", item.demand, item.semantics, budget),
+            }));
+            continue;
+        }
+        if (item.definition.kind === "postprocess") {
+            // The registry checks the observation before the body, so a body cannot trust a short supply.
+            if (!demandIsEmpty(item.demand) && !observationMeets(item.demand, request.supply ?? null)) {
+                record(envelope(item.definition, "insufficient-data", null, ["insufficient observation"], {
+                    ...baseProvenance,
+                    freshRuns: 0,
+                    rerun: rerunPlan("insufficient-data", item.demand, item.semantics, budget),
+                }));
+                continue;
+            }
+            // Samples are a batch-wide budget, so a postprocess sample cost is reserved like any other.
+            if (budget && item.cost.samples > 0) {
+                if (reservedSamples + item.cost.samples > budget.maxSamples) {
+                    record(envelope(item.definition, "insufficient-data", null, ["budget"], {
+                        ...baseProvenance,
+                        freshRuns: 0,
+                        rerun: rerunPlan("budget", item.demand, item.semantics, budget),
+                    }));
+                    continue;
+                }
+                reservedSamples += item.cost.samples;
+            }
+            participate(item, identity);
+            const body = callBody(() => item.definition.postprocess?.(item.params, {
+                demand: item.demand,
+                supply: request.supply ?? null,
+                input: request.input,
+                plan,
+            }));
+            const insufficient = body.status === "insufficient-data" || body.rerun === true;
+            record(envelope(item.definition, body.status, body.value, body.issues ?? [], {
+                ...baseProvenance,
+                freshRuns: 0,
+                rerun: insufficient
+                    ? rerunPlan(body.rerunReason ?? "insufficient-data", item.demand, item.semantics, budget)
+                    : null,
+            }));
+            continue;
+        }
+        const decision = admit(item);
+        if (decision !== "run") {
+            record(envelope(item.definition, "insufficient-data", null, [decision], {
+                ...baseProvenance,
+                freshRuns: 0,
+                rerun: rerunPlan(decision, item.demand, item.semantics, budget),
+            }));
+            continue;
+        }
+        participate(item, identity);
+        const body = callBody(() => item.definition.execute?.(item.params, {
+            runFactory: request.runFactory ?? null,
+            budget: budget,
+            plan,
+            semantics: item.semantics,
+            demand: item.demand,
+            scenario: request.scenario ?? null,
+            requestRun: () => requestRun(item, identity),
+        }));
+        const grant = itemGrants.get(identity);
+        const insufficient = body.status === "insufficient-data" || body.rerun === true;
+        const reason = body.rerunReason ?? (grant && !grant.accepted ? "budget" : "insufficient-data");
+        record(envelope(item.definition, body.status, body.value, body.issues ?? [], {
+            ...baseProvenance,
+            executionPlan: grant?.plan ?? plan,
+            freshRuns: grant?.accepted ? 1 : 0,
+            rerun: insufficient ? rerunPlan(reason, item.demand, item.semantics, budget) : null,
+        }));
+    }
+    // A result shares with the other members of its group whose body was called, and only if its own was.
+    const shared = results.map((result) => {
+        const identity = analyzerKey(result.id, result.version);
+        const group = participants.get(result.provenance.groupKey) ?? [];
+        const sharedWith = group.includes(identity) ? group.filter((member) => member !== identity).sort() : [];
+        return { ...result, provenance: { ...result.provenance, sharedWith } };
+    });
+    shared.sort((left, right) => compareIdentity(left, right));
+    return { results: shared, freshRuns, groupKeys };
+}
+function capabilityStatus(definition, capabilities) {
+    if (!capabilities)
+        return null;
+    for (const name of definition.requires.capabilities) {
+        const knowledge = capabilities[name] ?? "unknown";
+        if (knowledge === "unsupported")
+            return "unsupported";
+        if (knowledge === "unknown")
+            return "insufficient-data";
+    }
+    return null;
+}
+function validateGrowthParams(input) {
+    if (!input || typeof input !== "object")
+        return { ok: false, issues: ["growth params must be an object"] };
+    const series = input.series;
+    const windowSec = input.windowSec;
+    const issues = [];
+    if (series !== "money" && series !== "netWorth")
+        issues.push("series must be money or netWorth");
+    if (typeof windowSec !== "number" || !Number.isFinite(windowSec) || windowSec <= 0) {
+        issues.push("windowSec must be a finite number greater than 0");
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    if (series !== "money" && series !== "netWorth")
+        return { ok: false, issues };
+    if (typeof windowSec !== "number" || !Number.isFinite(windowSec) || windowSec <= 0)
+        return { ok: false, issues };
+    return { ok: true, params: { series, windowSec } };
+}
+function growthDemand(params) {
+    return {
+        windowSec: params.windowSec,
+        sampleCadenceSec: null,
+        coverage: "trace",
+        metricIds: [params.series],
+        observationSchema: observationContract,
+    };
+}
+function isGrowthInput(value) {
+    return !!value && typeof value === "object" && "run" in value;
+}
+function growthDefinition() {
+    return {
+        id: GROWTH_ANALYZER_ID,
+        version: GROWTH_ANALYZER_VERSION,
+        kind: "postprocess",
+        validateParams: validateGrowthParams,
+        requires: {
+            capabilities: ["metrics"],
+            metricIds: ["money", "netWorth"],
+            observationSchema: observationContract,
+        },
+        observation: observationDemand({ coverage: "trace", metricIds: ["money", "netWorth"] }),
+        resolveDemand: growthDemand,
+        outputContract: GROWTH_OUTPUT_CONTRACT,
+        algorithmVersion: growthAnalyzerAlgorithmVersion(),
+        cost: { freshRuns: 0, samples: 0 },
+        dependencies: [],
+        postprocess(params, ctx) {
+            if (!observationMeets(ctx.demand, ctx.supply)) {
+                return { status: "insufficient-data", value: null, issues: ["insufficient observation"], rerun: true };
+            }
+            if (!isGrowthInput(ctx.input)) {
+                return { status: "invalid", value: null, issues: ["growth input is not a run"] };
+            }
+            return {
+                status: "ok",
+                value: analyzeGrowth({
+                    run: ctx.input.run,
+                    scenario: ctx.input.scenario,
+                    series: params.series,
+                    windowSec: params.windowSec,
+                }),
+            };
+        },
+    };
+}
+function validateEtaParams(input) {
+    if (!input || typeof input !== "object")
+        return { ok: false, issues: ["eta params must be an object"] };
+    const mode = input.mode;
+    const maxDurationSec = input.maxDurationSec;
+    const target = input.target;
+    const issues = [];
+    if (mode !== "simulate" && mode !== "analytic")
+        issues.push("mode must be simulate or analytic");
+    if (typeof maxDurationSec !== "number" || !Number.isFinite(maxDurationSec) || maxDurationSec <= 0) {
+        issues.push("maxDurationSec must be a finite number greater than 0");
+    }
+    if (!target || (target.kind !== "money" && target.kind !== "netWorth") || typeof target.value !== "string") {
+        issues.push("target must be money or netWorth with a string value");
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    return {
+        ok: true,
+        params: {
+            mode: mode,
+            maxDurationSec: maxDurationSec,
+            target: { kind: target.kind, value: target.value },
+        },
+    };
+}
+function etaDemand(params) {
+    return {
+        windowSec: params.maxDurationSec,
+        sampleCadenceSec: null,
+        coverage: "summary",
+        metricIds: [params.target.kind === "money" ? "money" : "netWorth"],
+        observationSchema: observationContract,
+    };
+}
+function etaDefinition() {
+    return {
+        id: ETA_ANALYZER_ID,
+        version: ETA_ANALYZER_VERSION,
+        kind: "execution",
+        validateParams: validateEtaParams,
+        requires: {
+            capabilities: ["metrics", "goals"],
+            metricIds: ["money", "netWorth"],
+            observationSchema: observationContract,
+        },
+        observation: observationDemand({ coverage: "summary", metricIds: ["money", "netWorth"] }),
+        resolveDemand: etaDemand,
+        outputContract: etaEstimateSchemaId(),
+        algorithmVersion: etaEstimateAlgorithmVersion(),
+        cost: { freshRuns: 1, samples: 1 },
+        // Analytic ETA does not simulate, so it needs no fresh run.
+        resolveCost: (params) => (params.mode === "analytic" ? { freshRuns: 0, samples: 0 } : { freshRuns: 1, samples: 1 }),
+        // etaSimulate runs its own simulation and stops at the target, so it cannot share a group run.
+        sharesRun: false,
+        dependencies: [],
+        execute(params, ctx) {
+            // No grant is requested without a scenario, so a missing scenario does not spend a fresh run.
+            if (!ctx.scenario) {
+                return {
+                    status: "insufficient-data",
+                    value: null,
+                    issues: ["missing scenario"],
+                    rerun: true,
+                    rerunReason: "missing-scenario",
+                };
+            }
+            // ETA runs the scenario as compiled, so semantics that name another step or seed would
+            // record a configuration that did not produce the result.
+            if (ctx.semantics.stepSec !== ctx.scenario.run.stepSec || ctx.semantics.seed !== (ctx.scenario.ctx.seed ?? null)) {
+                return {
+                    status: "invalid",
+                    value: null,
+                    issues: ["semantics stepSec and seed must match the scenario's run step and seed"],
+                };
+            }
+            if (params.mode === "analytic") {
+                return { status: "ok", value: etaAnalytic({ scenario: ctx.scenario, target: params.target }) };
+            }
+            // The simulation runs for maxDurationSec, so that is the duration the budget and horizon must cover.
+            if (params.maxDurationSec > ctx.semantics.horizonSec || params.maxDurationSec > ctx.budget.maxDurationSec) {
+                return {
+                    status: "insufficient-data",
+                    value: null,
+                    issues: ["maxDurationSec exceeds the run horizon or the duration budget"],
+                    rerun: true,
+                    rerunReason: "budget",
+                };
+            }
+            const grant = ctx.requestRun("eta");
+            if (!grant.accepted) {
+                return { status: "insufficient-data", value: null, issues: ["budget"], rerun: true, rerunReason: "budget" };
+            }
+            const value = etaSimulate({
+                scenario: ctx.scenario,
+                target: params.target,
+                maxDurationSec: params.maxDurationSec,
+            });
+            return { status: "ok", value };
+        },
+    };
+}
+export function createBuiltinAnalyzerRegistry() {
+    const registry = createAnalyzerRegistry();
+    registry.register(growthDefinition());
+    registry.register(etaDefinition());
+    return registry;
+}
+export function runGrowthAnalyzer(args) {
+    const batch = createBuiltinAnalyzerRegistry().run({
+        requests: [
+            {
+                id: GROWTH_ANALYZER_ID,
+                version: GROWTH_ANALYZER_VERSION,
+                params: { series: args.series, windowSec: args.windowSec },
+            },
+        ],
+        semantics: args.semantics ?? analyzerSemantics(),
+        supply: args.supply,
+        input: { run: args.run, scenario: args.scenario },
+        allowExecution: false,
+    });
+    const result = batch.results[0];
+    if (!result)
+        throw new AnalyzerRegistryError("growth analyzer produced no result");
+    return result;
+}
+export function runEtaAnalyzer(args) {
+    const batch = createBuiltinAnalyzerRegistry().run({
+        requests: [
+            {
+                id: ETA_ANALYZER_ID,
+                version: ETA_ANALYZER_VERSION,
+                params: { mode: args.mode, target: args.target, maxDurationSec: args.maxDurationSec },
+            },
+        ],
+        semantics: args.semantics ?? analyzerSemantics({
+            horizonSec: args.maxDurationSec,
+            stepSec: args.scenario.run.stepSec,
+            seed: args.scenario.ctx.seed ?? null,
+        }),
+        scenario: args.scenario,
+        budget: args.budget,
+        allowExecution: true,
+        runFactory: args.runFactory ?? createRunFactory(),
+    });
+    const result = batch.results[0];
+    if (!result)
+        throw new AnalyzerRegistryError("eta analyzer produced no result");
+    return result;
+}
+//# sourceMappingURL=analyzers.js.map