@chronon-sim/engine 0.1.0

package/dist/run/results.d.ts

@@ -0,0 +1,72 @@
+import type { AssertionDefinition } from "../format/index.js";
+import type { UnitCategory } from "../schema/index.js";
+/** Settings actually used for a run (after CLI overrides). */
+export interface RunSettingsUsed {
+    duration: number;
+    warmUp: number;
+    seed: number;
+    replications: number;
+    ticksPerSecond: number;
+}
+/** Values of every output in one replication, keyed by output id "<component>.<OutputKey>"; null = undefined (NaN). */
+export interface ReplicationResult {
+    index: number;
+    /** The seed this replication actually used (derived from the base seed and the index). */
+    seed: number;
+    eventsProcessed: number;
+    outputs: Record<string, number | null>;
+}
+/** Cross-replication summary of one output. */
+export interface OutputSummary {
+    /** "<component>.<OutputKey>" */
+    id: string;
+    component: string;
+    componentType: string;
+    key: string;
+    unit: UnitCategory;
+    description: string;
+    /** Number of replications with a defined value. */
+    n: number;
+    mean: number | null;
+    stdDev: number | null;
+    /** 95% confidence interval for the mean (Student t); null with fewer than 2 replications. */
+    ci95: {
+        low: number;
+        high: number;
+        halfWidth: number;
+    } | null;
+}
+/** Sampled series for one replication; `values[id][i]` is the value at `times[i]` seconds. */
+export interface TimeSeriesReplication {
+    replication: number;
+    times: number[];
+    values: Record<string, (number | null)[]>;
+}
+export interface TimeSeriesResult {
+    interval: number;
+    outputs: string[];
+    replications: TimeSeriesReplication[];
+}
+/** The outcome of checking one assertion against the results. */
+export interface AssertionResult {
+    assertion: AssertionDefinition;
+    /** The compared number, or null if it was undefined (e.g. no CI with one replication). */
+    actual: number | null;
+    passed: boolean;
+    /** Human-readable one-liner, e.g. "sink.p99 (mean) = 1.84 <= 2". */
+    message: string;
+}
+/** The full, JSON-serialisable result of running a model. Every renderer works from this. */
+export interface RunResults {
+    /** Version of this results structure. */
+    resultsVersion: 1;
+    modelName: string | null;
+    settings: RunSettingsUsed;
+    /** One entry per component output, in model order. */
+    outputs: OutputSummary[];
+    replications: ReplicationResult[];
+    timeSeries?: TimeSeriesResult;
+    /** Present when the model (or the caller) defined assertions. */
+    assertions?: AssertionResult[];
+}
+//# sourceMappingURL=results.d.ts.map

package/dist/run/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../src/run/results.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,uHAAuH;AACvH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,6FAA6F;IAC7F,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/D;AAED,8FAA8F;AAC9F,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,qBAAqB,EAAE,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,mBAAmB,CAAC;IAC/B,0FAA0F;IAC1F,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,6FAA6F;AAC7F,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,cAAc,EAAE,CAAC,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,sDAAsD;IACtD,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,iEAAiE;IACjE,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC"}

package/dist/run/results.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=results.js.map

package/dist/run/results.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.js","sourceRoot":"","sources":["../../src/run/results.ts"],"names":[],"mappings":""}

package/dist/run/run.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentRegistry } from "../components/index.js";
+import type { AssertionDefinition, ModelDefinition, TimeSeriesConfig } from "../format/index.js";
+import type { RunResults } from "./results.js";
+/** Overrides applied on top of the model's own settings. */
+export interface RunOptions {
+    seed?: number;
+    replications?: number;
+    /** Sample these outputs over time, overriding the model's `timeSeries` setting. */
+    timeSeries?: TimeSeriesConfig;
+    /** Extra assertions to check in addition to the model's own. */
+    assertions?: AssertionDefinition[];
+    registry?: ComponentRegistry;
+    /** Stop with a SimulationLimitError if this many events run at one instant (default 10 million): guards against zero-delay loops. */
+    maxEventsPerTick?: number;
+    /** Stop with a SimulationLimitError after this many events in one replication (default unlimited). */
+    maxEvents?: number;
+}
+/**
+ * The time series sampled by default when a caller asks for one but the model configures none:
+ * every output flagged `series` (current-value outputs like QueueLength), ~200 samples per run.
+ */
+export declare function defaultTimeSeries(model: ModelDefinition, registry?: ComponentRegistry): TimeSeriesConfig;
+/** Replication `i` runs with a seed derived from the base seed and `i`. */
+export declare function replicationSeed(baseSeed: number, index: number): number;
+/**
+ * Run all replications of a validated model and return the structured, JSON-serialisable results.
+ */
+export declare function runModel(model: ModelDefinition, options?: RunOptions): RunResults;
+//# sourceMappingURL=run.d.ts.map

package/dist/run/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAIjG,OAAO,KAAK,EAAiB,UAAU,EAAyB,MAAM,cAAc,CAAC;AAGrF,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,gEAAgE;IAChE,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,qIAAqI;IACrI,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,GAAE,iBAA2C,GAAG,gBAAgB,CAQjI;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,UAAe,GAAG,UAAU,CAoDrF"}

package/dist/run/run.js

@@ -0,0 +1,80 @@
+import { createDefaultRegistry } from "../components/index.js";
+import { deriveSeed } from "../rng/index.js";
+import { summarize } from "../stats/index.js";
+import { evaluateAssertions } from "./assertions.js";
+import { Simulation } from "./simulation.js";
+/**
+ * The time series sampled by default when a caller asks for one but the model configures none:
+ * every output flagged `series` (current-value outputs like QueueLength), ~200 samples per run.
+ */
+export function defaultTimeSeries(model, registry = createDefaultRegistry()) {
+    const outputs = [];
+    for (const c of model.components) {
+        for (const o of registry.get(c.type)?.schema.outputs ?? []) {
+            if (o.series)
+                outputs.push(`${c.name}.${o.key}`);
+        }
+    }
+    return { interval: model.settings.duration / 200, outputs };
+}
+/** Replication `i` runs with a seed derived from the base seed and `i`. */
+export function replicationSeed(baseSeed, index) {
+    return deriveSeed(baseSeed, index);
+}
+/**
+ * Run all replications of a validated model and return the structured, JSON-serialisable results.
+ */
+export function runModel(model, options = {}) {
+    const registry = options.registry ?? createDefaultRegistry();
+    const seed = options.seed ?? model.settings.seed;
+    const replications = options.replications ?? model.settings.replications;
+    if (!Number.isInteger(replications) || replications < 1)
+        throw new RangeError("replications must be a positive integer");
+    const tsConfig = options.timeSeries ?? model.settings.timeSeries ?? null;
+    const reps = [];
+    const series = [];
+    for (let i = 0; i < replications; i++) {
+        const sim = new Simulation(model, replicationSeed(seed, i), i, tsConfig, registry, {
+            ...(options.maxEventsPerTick !== undefined ? { maxEventsPerTick: options.maxEventsPerTick } : {}),
+            ...(options.maxEvents !== undefined ? { maxEvents: options.maxEvents } : {}),
+        });
+        const { result, timeSeries } = sim.runToEnd();
+        reps.push(result);
+        if (timeSeries)
+            series.push(timeSeries);
+    }
+    const outputs = [];
+    for (const def of model.components) {
+        const schema = registry.get(def.type).schema;
+        for (const o of schema.outputs) {
+            const id = `${def.name}.${o.key}`;
+            const s = summarize(reps.map((r) => r.outputs[id] ?? NaN));
+            outputs.push({
+                id,
+                component: def.name,
+                componentType: def.type,
+                key: o.key,
+                unit: o.unit,
+                description: o.description,
+                n: s.n,
+                mean: s.mean,
+                stdDev: s.stdDev,
+                ci95: s.ci95,
+            });
+        }
+    }
+    const { duration, warmUp, ticksPerSecond } = model.settings;
+    const results = {
+        resultsVersion: 1,
+        modelName: model.name ?? null,
+        settings: { duration, warmUp, seed, replications, ticksPerSecond },
+        outputs,
+        replications: reps,
+        ...(tsConfig ? { timeSeries: { interval: tsConfig.interval, outputs: tsConfig.outputs, replications: series } } : {}),
+    };
+    const assertions = [...(model.assertions ?? []), ...(options.assertions ?? [])];
+    if (assertions.length > 0)
+        results.assertions = evaluateAssertions(results, assertions);
+    return results;
+}
+//# sourceMappingURL=run.js.map

package/dist/run/run.js.map

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

package/dist/run/simulation.d.ts

@@ -0,0 +1,34 @@
+import { type ComponentRegistry } from "../components/index.js";
+import type { ModelDefinition, TimeSeriesConfig } from "../format/index.js";
+import { Kernel, type KernelLimits } from "../kernel/index.js";
+import type { LinkedComponent } from "../model/index.js";
+import type { ReplicationResult, TimeSeriesReplication } from "./results.js";
+/** One instantiated replication of a model: kernel, components, warm-up and sampling wired up. */
+export declare class Simulation {
+    readonly seed: number;
+    readonly index: number;
+    readonly kernel: Kernel;
+    /** Components by name, in model order. */
+    readonly components: Map<string, LinkedComponent>;
+    private readonly registry;
+    private readonly model;
+    private readonly series;
+    private readonly seriesConfig;
+    /**
+     * @param model a validated model (from `loadModel`)
+     * @param seed the seed for this replication
+     * @param index replication index (recorded in results)
+     * @param timeSeries optional sampling configuration
+     * @param limits optional safety limits (see {@link KernelLimits})
+     */
+    constructor(model: ModelDefinition, seed: number, index?: number, timeSeries?: TimeSeriesConfig | null, registry?: ComponentRegistry, limits?: KernelLimits);
+    /** Read one output by id "<component>.<OutputKey>" (NaN if unknown or undefined). */
+    readOutput(id: string): number;
+    private recordSample;
+    /** Run to the model's duration and collect every output. */
+    runToEnd(): {
+        result: ReplicationResult;
+        timeSeries: TimeSeriesReplication | null;
+    };
+}
+//# sourceMappingURL=simulation.d.ts.map

package/dist/run/simulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simulation.d.ts","sourceRoot":"","sources":["../../src/run/simulation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAY,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAA4B,MAAM,mBAAmB,CAAC;AAEnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE7E,kGAAkG;AAClG,qBAAa,UAAU;IAkBnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,KAAK;IAlBhB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,+BAAsC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IAEvD;;;;;;OAMG;gBAED,KAAK,EAAE,eAAe,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,SAAI,EAClB,UAAU,GAAE,gBAAgB,GAAG,IAAW,EAC1C,QAAQ,GAAE,iBAA2C,EACrD,MAAM,GAAE,YAAiB;IAgD3B,qFAAqF;IACrF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAQ9B,OAAO,CAAC,YAAY;IASpB,4DAA4D;IAC5D,QAAQ,IAAI;QAAE,MAAM,EAAE,iBAAiB,CAAC;QAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAA;KAAE;CAgBpF"}

package/dist/run/simulation.js

@@ -0,0 +1,104 @@
+import { createDefaultRegistry } from "../components/index.js";
+import { Kernel, Priority } from "../kernel/index.js";
+import { Rng } from "../rng/index.js";
+/** One instantiated replication of a model: kernel, components, warm-up and sampling wired up. */
+export class Simulation {
+    seed;
+    index;
+    kernel;
+    /** Components by name, in model order. */
+    components = new Map();
+    registry;
+    model;
+    series;
+    seriesConfig;
+    /**
+     * @param model a validated model (from `loadModel`)
+     * @param seed the seed for this replication
+     * @param index replication index (recorded in results)
+     * @param timeSeries optional sampling configuration
+     * @param limits optional safety limits (see {@link KernelLimits})
+     */
+    constructor(model, seed, index = 0, timeSeries = null, registry = createDefaultRegistry(), limits = {}) {
+        this.seed = seed;
+        this.index = index;
+        this.model = model;
+        this.registry = registry;
+        this.kernel = new Kernel(model.settings.ticksPerSecond, limits);
+        let nextId = 0;
+        const kernel = this.kernel;
+        const ctx = {
+            kernel,
+            rng: (streamId) => new Rng(seed, streamId),
+            createEntity: () => ({ id: nextId++, createdAt: kernel.currentTick, attributes: {} }),
+        };
+        for (const def of model.components) {
+            const cls = registry.get(def.type);
+            if (!cls)
+                throw new Error(`unknown component type ${def.type}`); // unreachable for validated models
+            this.components.set(def.name, new cls(ctx, { name: def.name, stream: def.stream ?? def.name, inputs: def.inputs }));
+        }
+        for (const def of model.components) {
+            const c = this.components.get(def.name);
+            for (const [key, target] of Object.entries(def.links)) {
+                c.setLink(key, this.components.get(target));
+            }
+        }
+        for (const c of this.components.values())
+            c.start();
+        const { warmUp, duration } = model.settings;
+        if (warmUp > 0) {
+            kernel.schedule(kernel.secondsToTicks(warmUp), Priority.HIGHEST, () => {
+                for (const c of this.components.values())
+                    c.resetStatistics();
+            });
+        }
+        this.seriesConfig = timeSeries;
+        this.series = timeSeries ? { replication: index, times: [], values: Object.fromEntries(timeSeries.outputs.map((o) => [o, []])) } : null;
+        if (timeSeries) {
+            const total = Math.floor(duration / timeSeries.interval + 1e-9);
+            const sample = (i) => {
+                this.recordSample();
+                if (i < total) {
+                    const next = kernel.secondsToTicks((i + 1) * timeSeries.interval);
+                    kernel.schedule(next - kernel.currentTick, Priority.LOWEST, () => sample(i + 1));
+                }
+            };
+            kernel.schedule(0, Priority.LOWEST, () => sample(0));
+        }
+    }
+    /** Read one output by id "<component>.<OutputKey>" (NaN if unknown or undefined). */
+    readOutput(id) {
+        const dot = id.lastIndexOf(".");
+        const comp = this.components.get(id.slice(0, dot));
+        const def = this.model.components.find((c) => c.name === id.slice(0, dot));
+        const spec = def ? this.registry.get(def.type)?.schema.outputs.find((o) => o.key === id.slice(dot + 1)) : undefined;
+        return comp && spec ? spec.get(comp) : NaN;
+    }
+    recordSample() {
+        const s = this.series;
+        s.times.push(this.kernel.currentSeconds);
+        for (const id of this.seriesConfig.outputs) {
+            const v = this.readOutput(id);
+            s.values[id].push(Number.isFinite(v) ? v : null);
+        }
+    }
+    /** Run to the model's duration and collect every output. */
+    runToEnd() {
+        this.kernel.runUntil(this.kernel.secondsToTicks(this.model.settings.duration));
+        const outputs = {};
+        for (const def of this.model.components) {
+            const schema = this.registry.get(def.type).schema;
+            const comp = this.components.get(def.name);
+            for (const o of schema.outputs) {
+                const v = o.get(comp);
+                outputs[`${def.name}.${o.key}`] = Number.isFinite(v) ? v : null;
+            }
+        }
+        return {
+            result: { index: this.index, seed: this.seed, eventsProcessed: this.kernel.eventsProcessed, outputs },
+            timeSeries: this.series,
+        };
+    }
+}
+//# sourceMappingURL=simulation.js.map

package/dist/run/simulation.js.map

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

package/dist/schema/index.d.ts

@@ -0,0 +1,5 @@
+export { describeSchema } from "./types.js";
+export type { UnitCategory, InputType, InputSpec, OutputSpec, LinkSpec, ComponentSchema, ValidationError, SchemaDescription, } from "./types.js";
+export { validateInputs, asSampler, asRateProfile } from "./validate.js";
+export type { InputValidation, RateSegment } from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EACV,YAAY,EACZ,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/schema/index.js

@@ -0,0 +1,3 @@
+export { describeSchema } from "./types.js";
+export { validateInputs, asSampler, asRateProfile } from "./validate.js";
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAW5C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}

package/dist/schema/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Unit categories. All time quantities in the JSON format are seconds and all rates are per second,
+ * regardless of the model's tick resolution. `cost` is an abstract currency amount (whatever unit
+ * the model's prices use).
+ */
+export type UnitCategory = "time" | "rate" | "cost" | "dimensionless";
+/** The kinds of values a component input can take. */
+export type InputType = "number" | "integer" | "boolean" | "string" | "enum" | "sampler" | "rateProfile";
+/** Declares one input of a component. Pure data. */
+export interface InputSpec {
+    key: string;
+    type: InputType;
+    unit: UnitCategory;
+    description: string;
+    required: boolean;
+    /** Value used when the input is omitted. Ignored when `required` or `requiredWhen` applies. */
+    default?: unknown;
+    /** Inclusive lower bound (number, integer, and constant samplers). */
+    min?: number;
+    /** Inclusive upper bound (number, integer, and constant samplers). */
+    max?: number;
+    /** Allowed values when `type` is "enum". */
+    options?: readonly string[];
+    /** Input is additionally required when another input has the given value. */
+    requiredWhen?: {
+        input: string;
+        equals: unknown;
+    };
+}
+/** Declares one output (statistic) of a component. Pure data except for the getter. */
+export interface OutputSpec<T = any> {
+    key: string;
+    unit: UnitCategory;
+    description: string;
+    /** Include in the default time series (current-value outputs such as QueueLength). */
+    series?: boolean;
+    /** Read the value from a live component. Return NaN when undefined (e.g. no observations). */
+    get(component: T): number;
+}
+/** Declares a link from one component to another. Pure data. */
+export interface LinkSpec {
+    key: string;
+    description: string;
+    required: boolean;
+    /** Role the target component must have (see {@link ComponentSchema.roles}). */
+    accepts: string;
+}
+/** The schema of a component class: its inputs, links and outputs. */
+export interface ComponentSchema<T = any> {
+    /** Component type name used in model files, e.g. "Queue". */
+    type: string;
+    description: string;
+    /** Roles this component plays, matched against `LinkSpec.accepts` (e.g. "receiver", "queue"). */
+    roles: readonly string[];
+    inputs: readonly InputSpec[];
+    links: readonly LinkSpec[];
+    outputs: readonly OutputSpec<T>[];
+}
+/** A structured validation problem. Never a thrown string. */
+export interface ValidationError {
+    /** Component name, or null for model-level problems. */
+    component: string | null;
+    /** Input/link/setting key the problem is about, or null if it concerns the component as a whole. */
+    key: string | null;
+    message: string;
+}
+/** A schema with the getters stripped: plain JSON, e.g. for SDK type or documentation generation. */
+export interface SchemaDescription {
+    type: string;
+    description: string;
+    roles: readonly string[];
+    inputs: readonly InputSpec[];
+    links: readonly LinkSpec[];
+    outputs: readonly {
+        key: string;
+        unit: UnitCategory;
+        description: string;
+        series?: boolean;
+    }[];
+}
+/** Convert a schema to plain, JSON-serialisable data. */
+export declare function describeSchema(schema: ComponentSchema): SchemaDescription;
+//# sourceMappingURL=types.d.ts.map

package/dist/schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,eAAe,CAAC;AAEtE,sDAAsD;AACtD,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,MAAM,GACN,SAAS,GACT,aAAa,CAAC;AAElB,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,6EAA6E;IAC7E,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CACnD;AAED,uFAAuF;AACvF,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8FAA8F;IAC9F,GAAG,CAAC,SAAS,EAAE,CAAC,GAAG,MAAM,CAAC;CAC3B;AAED,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,iGAAiG;IACjG,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;CACnC;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oGAAoG;IACpG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qGAAqG;AACrG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IAC7B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CAChG;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAgBzE"}

package/dist/schema/types.js

@@ -0,0 +1,19 @@
+/** Convert a schema to plain, JSON-serialisable data. */
+export function describeSchema(schema) {
+    return {
+        type: schema.type,
+        description: schema.description,
+        roles: schema.roles,
+        inputs: schema.inputs,
+        links: schema.links,
+        outputs: schema.outputs.map((o) => {
+            const d = {
+                key: o.key,
+                unit: o.unit,
+                description: o.description,
+            };
+            return o.series ? { ...d, series: true } : d;
+        }),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"AAuFA,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,MAAuB;IACpD,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAChC,MAAM,CAAC,GAAyC;gBAC9C,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;aAC3B,CAAC;YACF,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,CAAC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/schema/validate.d.ts

@@ -0,0 +1,19 @@
+import { type SamplerSpec } from "../rng/index.js";
+import type { ComponentSchema, ValidationError } from "./types.js";
+/** One piecewise-constant segment of a rate profile: from `start` seconds, `rate` arrivals/second. */
+export type RateSegment = readonly [startSeconds: number, ratePerSecond: number];
+/** Result of {@link validateInputs}: normalised values (defaults applied) plus all errors found. */
+export interface InputValidation {
+    values: Record<string, unknown>;
+    errors: ValidationError[];
+}
+/**
+ * Validate a component's raw `inputs` object against its schema, applying defaults.
+ * Collects every problem rather than stopping at the first.
+ */
+export declare function validateInputs(schema: ComponentSchema, raw: unknown, componentName: string): InputValidation;
+/** Narrow a validated sampler input. */
+export declare function asSampler(v: unknown): SamplerSpec;
+/** Narrow a validated rate profile input. */
+export declare function asRateProfile(v: unknown): RateSegment[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/schema/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAa,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9E,sGAAsG;AACtG,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;AAEjF,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AA+DD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,MAAM,GACpB,eAAe,CA0CjB;AAED,wCAAwC;AACxC,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,CAEjD;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,CAEvD"}

package/dist/schema/validate.js

@@ -0,0 +1,120 @@
+import { validateSamplerSpec } from "../rng/index.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function finite(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function checkBounds(spec, v) {
+    if (spec.min !== undefined && v < spec.min)
+        return `must be >= ${spec.min}`;
+    if (spec.max !== undefined && v > spec.max)
+        return `must be <= ${spec.max}`;
+    return null;
+}
+/** Check one raw value against its input spec. Returns an error message or null. */
+function checkValue(spec, v) {
+    switch (spec.type) {
+        case "number": {
+            if (!finite(v))
+                return "must be a finite number";
+            return checkBounds(spec, v);
+        }
+        case "integer": {
+            if (!finite(v) || !Number.isInteger(v))
+                return "must be an integer";
+            return checkBounds(spec, v);
+        }
+        case "boolean":
+            return typeof v === "boolean" ? null : "must be true or false";
+        case "string":
+            return typeof v === "string" ? null : "must be a string";
+        case "enum":
+            return typeof v === "string" && (spec.options ?? []).includes(v)
+                ? null
+                : `must be one of ${(spec.options ?? []).map((o) => JSON.stringify(o)).join(", ")}`;
+        case "sampler": {
+            const problems = validateSamplerSpec(v);
+            if (problems.length > 0)
+                return problems.join("; ");
+            if (finite(v))
+                return checkBounds(spec, v);
+            const c = v;
+            if (c.dist === "constant" && typeof c.value === "number")
+                return checkBounds(spec, c.value);
+            return null;
+        }
+        case "rateProfile": {
+            if (!Array.isArray(v) || v.length === 0) {
+                return "must be a non-empty array of [startSeconds, ratePerSecond] pairs";
+            }
+            let prev = -Infinity;
+            for (let i = 0; i < v.length; i++) {
+                const seg = v[i];
+                if (!Array.isArray(seg) || seg.length !== 2 || !finite(seg[0]) || !finite(seg[1])) {
+                    return `segment ${i} must be a [startSeconds, ratePerSecond] pair of numbers`;
+                }
+                if (seg[0] < 0)
+                    return `segment ${i}: startSeconds must be >= 0`;
+                if (seg[1] < 0)
+                    return `segment ${i}: ratePerSecond must be >= 0`;
+                if (seg[0] <= prev)
+                    return `segment ${i}: startSeconds must be strictly increasing`;
+                prev = seg[0];
+            }
+            return null;
+        }
+    }
+}
+/**
+ * Validate a component's raw `inputs` object against its schema, applying defaults.
+ * Collects every problem rather than stopping at the first.
+ */
+export function validateInputs(schema, raw, componentName) {
+    const errors = [];
+    const values = {};
+    const err = (key, message) => errors.push({ component: componentName, key, message });
+    if (raw !== undefined && !isRecord(raw)) {
+        err("inputs", "must be an object");
+        return { values, errors };
+    }
+    const given = (raw ?? {});
+    const known = new Set(schema.inputs.map((i) => i.key));
+    for (const key of Object.keys(given)) {
+        if (!known.has(key)) {
+            err(key, `unknown input for ${schema.type} (known inputs: ${[...known].join(", ")})`);
+        }
+    }
+    for (const spec of schema.inputs) {
+        const v = given[spec.key];
+        if (v === undefined || v === null) {
+            const conditional = spec.requiredWhen !== undefined &&
+                (given[spec.requiredWhen.input] ?? schema.inputs.find((i) => i.key === spec.requiredWhen.input)?.default) ===
+                    spec.requiredWhen.equals;
+            if (spec.required || conditional) {
+                err(spec.key, conditional && !spec.required
+                    ? `required when ${spec.requiredWhen.input} is ${JSON.stringify(spec.requiredWhen.equals)}`
+                    : "required input is missing");
+            }
+            else if (spec.default !== undefined) {
+                values[spec.key] = spec.default;
+            }
+            continue;
+        }
+        const problem = checkValue(spec, v);
+        if (problem)
+            err(spec.key, problem);
+        else
+            values[spec.key] = v;
+    }
+    return { values, errors };
+}
+/** Narrow a validated sampler input. */
+export function asSampler(v) {
+    return v;
+}
+/** Narrow a validated rate profile input. */
+export function asRateProfile(v) {
+    return v;
+}
+//# sourceMappingURL=validate.js.map