@chronon-sim/engine 0.1.0

package/dist/components/message-queue.d.ts

@@ -0,0 +1,45 @@
+import { LinkedComponent, type ComponentInit, type MovingEntity, type SimContext } from "../model/index.js";
+import type { ComponentSchema } from "../schema/index.js";
+import type { Lease, PullSource, QueueWaiter } from "./pullable.js";
+/**
+ * SQS-style message queue with a visibility timeout and an optional dead-letter queue.
+ *
+ * A consumer `receive`s a message, which hides it for `visibilityTimeout` seconds. If the consumer
+ * `ack`s in time the message is deleted. Otherwise it becomes visible again (a redelivery). When a
+ * message has been received `maxReceiveCount` times and its visibility timeout expires once more,
+ * it moves to the `deadLetter` link (or is discarded and counted if there is none).
+ *
+ * A consumer whose work outlives the visibility timeout is *not* stopped: it finishes, its ack is
+ * stale (returns false), and the message may be processed again by someone else. That duplicate
+ * processing is the classic visibility-timeout failure mode, and it is modelled on purpose.
+ */
+export declare class MessageQueue extends LinkedComponent implements PullSource {
+    static readonly schema: ComponentSchema<MessageQueue>;
+    readonly redeliversUnacked = true;
+    private readonly visible;
+    private readonly waiters;
+    private readonly visibilityTicks;
+    private readonly maxReceiveCount;
+    private readonly lengthStat;
+    private readonly flightStat;
+    private readonly waitTally;
+    private deadLetter;
+    private flight;
+    private received;
+    private redelivered;
+    private deadLettered;
+    private requests;
+    private readonly pricePerRequest;
+    constructor(ctx: SimContext, init: ComponentInit);
+    private get now();
+    setLink(key: string, target: LinkedComponent): void;
+    addWaiter(waiter: QueueWaiter): void;
+    addEntity(entity: MovingEntity): void;
+    receive(): Lease | null;
+    private expire;
+    private makeVisible;
+    private visibleChanged;
+    private setFlight;
+    resetStatistics(): void;
+}
+//# sourceMappingURL=message-queue.d.ts.map

package/dist/components/message-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-queue.d.ts","sourceRoot":"","sources":["../../src/components/message-queue.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAExH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAUpE;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,SAAQ,eAAgB,YAAW,UAAU;IACrE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,YAAY,CAAC,CAyBnD;IAEF,QAAQ,CAAC,iBAAiB,QAAQ;IAElC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,UAAU,CAAgC;IAClD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;gBAE7B,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;IAUhD,OAAO,KAAK,GAAG,GAEd;IAEQ,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAK5D,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAI3B,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAM9C,OAAO,IAAI,KAAK,GAAG,IAAI;IA6BvB,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,SAAS;IAKR,eAAe,IAAI,IAAI;CAUjC"}

package/dist/components/message-queue.js

@@ -0,0 +1,152 @@
+import { Priority } from "../kernel/index.js";
+import { FifoBuffer, LinkedComponent } from "../model/index.js";
+import { Tally, TimeWeightedStat } from "../stats/index.js";
+/**
+ * SQS-style message queue with a visibility timeout and an optional dead-letter queue.
+ *
+ * A consumer `receive`s a message, which hides it for `visibilityTimeout` seconds. If the consumer
+ * `ack`s in time the message is deleted. Otherwise it becomes visible again (a redelivery). When a
+ * message has been received `maxReceiveCount` times and its visibility timeout expires once more,
+ * it moves to the `deadLetter` link (or is discarded and counted if there is none).
+ *
+ * A consumer whose work outlives the visibility timeout is *not* stopped: it finishes, its ack is
+ * stale (returns false), and the message may be processed again by someone else. That duplicate
+ * processing is the classic visibility-timeout failure mode, and it is modelled on purpose.
+ */
+export class MessageQueue extends LinkedComponent {
+    static schema = {
+        type: "MessageQueue",
+        description: "SQS-style queue: received messages are hidden for a visibility timeout and redelivered unless acknowledged; after maxReceiveCount receives they go to a dead-letter queue.",
+        roles: ["receiver", "pullable"],
+        inputs: [
+            { key: "visibilityTimeout", type: "number", unit: "time", min: 0.000001, default: 30, required: false, description: "Seconds a received message stays hidden before it is redelivered." },
+            { key: "maxReceiveCount", type: "integer", unit: "dimensionless", min: 1, required: false, description: "Receives allowed before a message is dead-lettered (when its visibility timeout expires again). Unlimited if omitted." },
+            { key: "costPerMillionRequests", type: "number", unit: "cost", min: 0, default: 0, required: false, description: "Price per million API requests (each send, receive and delete counts as one)." },
+        ],
+        links: [{ key: "deadLetter", description: "Where messages that exhausted maxReceiveCount are sent. They are discarded (and counted) if omitted.", required: false, accepts: "receiver" }],
+        outputs: [
+            { key: "QueueLength", unit: "dimensionless", series: true, description: "Messages visible and waiting to be received.", get: (q) => q.visible.length },
+            { key: "InFlight", unit: "dimensionless", series: true, description: "Messages received but not yet acknowledged or expired.", get: (q) => q.flight },
+            { key: "Backlog", unit: "dimensionless", series: true, description: "Visible plus in-flight messages (SQS ApproximateNumberOfMessages + NotVisible).", get: (q) => q.visible.length + q.flight },
+            { key: "AverageQueueLength", unit: "dimensionless", description: "Time-weighted average number of visible messages.", get: (q) => q.lengthStat.mean(q.now) },
+            { key: "MaxQueueLength", unit: "dimensionless", description: "Largest number of visible messages.", get: (q) => q.lengthStat.max(q.now) },
+            { key: "AverageInFlight", unit: "dimensionless", description: "Time-weighted average number of in-flight messages.", get: (q) => q.flightStat.mean(q.now) },
+            { key: "AverageQueueTime", unit: "time", description: "Mean time a message was visible before being received (each receive counts).", get: (q) => q.waitTally.mean() },
+            { key: "NumberRequests", unit: "dimensionless", description: "Billable API requests: sends + receives + deletes.", get: (q) => q.requests },
+            { key: "Cost", unit: "cost", description: "Request charges over the measured window.", get: (q) => q.requests * q.pricePerRequest },
+            { key: "NumberReceived", unit: "dimensionless", description: "Receive operations (a redelivered message counts each time).", get: (q) => q.received },
+            { key: "NumberRedelivered", unit: "dimensionless", description: "Messages that became visible again because the visibility timeout expired.", get: (q) => q.redelivered },
+            { key: "NumberDeadLettered", unit: "dimensionless", description: "Messages that exhausted maxReceiveCount.", get: (q) => q.deadLettered },
+        ],
+    };
+    redeliversUnacked = true;
+    visible = new FifoBuffer();
+    waiters = [];
+    visibilityTicks;
+    maxReceiveCount;
+    lengthStat;
+    flightStat;
+    waitTally = new Tally();
+    deadLetter = null;
+    flight = 0;
+    received = 0;
+    redelivered = 0;
+    deadLettered = 0;
+    requests = 0;
+    pricePerRequest;
+    constructor(ctx, init) {
+        super(ctx, init, "Empty");
+        // At least one tick, so a tiny timeout can never expire within the tick of its receive.
+        this.visibilityTicks = Math.max(1, ctx.kernel.secondsToTicks(init.inputs["visibilityTimeout"]));
+        this.maxReceiveCount = init.inputs["maxReceiveCount"];
+        this.pricePerRequest = init.inputs["costPerMillionRequests"] / 1_000_000;
+        this.lengthStat = new TimeWeightedStat(ctx.kernel.currentTick, 0);
+        this.flightStat = new TimeWeightedStat(ctx.kernel.currentTick, 0);
+    }
+    get now() {
+        return this.ctx.kernel.currentTick;
+    }
+    setLink(key, target) {
+        if (key === "deadLetter")
+            this.deadLetter = target;
+        else
+            super.setLink(key, target);
+    }
+    addWaiter(waiter) {
+        this.waiters.push(waiter);
+    }
+    addEntity(entity) {
+        this.noteAdded();
+        this.requests++;
+        this.makeVisible({ entity, receiveCount: 0, visibleAt: this.now });
+    }
+    receive() {
+        const msg = this.visible.shift();
+        if (msg === undefined)
+            return null;
+        msg.receiveCount++;
+        this.received++;
+        this.requests++;
+        this.waitTally.add(this.ctx.kernel.ticksToSeconds(this.now - msg.visibleAt));
+        this.setFlight(this.flight + 1);
+        this.visibleChanged();
+        let active = true;
+        const timer = this.ctx.kernel.schedule(this.visibilityTicks, Priority.DEFAULT, () => {
+            active = false;
+            this.expire(msg);
+        });
+        return {
+            entity: msg.entity,
+            ack: () => {
+                if (!active)
+                    return false;
+                active = false;
+                timer.cancel();
+                this.requests++;
+                this.setFlight(this.flight - 1);
+                this.noteCompleted();
+                return true;
+            },
+        };
+    }
+    expire(msg) {
+        this.setFlight(this.flight - 1);
+        if (this.maxReceiveCount !== undefined && msg.receiveCount >= this.maxReceiveCount) {
+            this.deadLettered++;
+            this.noteCompleted();
+            this.deadLetter?.addEntity(msg.entity);
+            return;
+        }
+        this.redelivered++;
+        msg.visibleAt = this.now;
+        this.makeVisible(msg);
+    }
+    makeVisible(msg) {
+        this.visible.push(msg);
+        this.visibleChanged();
+        for (const w of this.waiters) {
+            if (this.visible.length === 0)
+                break;
+            w.queueHasEntity();
+        }
+    }
+    visibleChanged() {
+        this.lengthStat.set(this.now, this.visible.length);
+        this.setState(this.visible.length === 0 ? "Empty" : "NonEmpty");
+    }
+    setFlight(n) {
+        this.flight = n;
+        this.flightStat.set(this.now, n);
+    }
+    resetStatistics() {
+        super.resetStatistics();
+        this.lengthStat.reset(this.now);
+        this.flightStat.reset(this.now);
+        this.waitTally.reset();
+        this.received = 0;
+        this.redelivered = 0;
+        this.deadLettered = 0;
+        this.requests = 0;
+    }
+}
+//# sourceMappingURL=message-queue.js.map

package/dist/components/message-queue.js.map

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

package/dist/components/pullable.d.ts

@@ -0,0 +1,24 @@
+import type { MovingEntity } from "../model/index.js";
+/** Something that wants to be told when a queue has entities available. */
+export interface QueueWaiter {
+    queueHasEntity(): void;
+}
+/** One received entity. `ack` confirms it was processed. */
+export interface Lease {
+    readonly entity: MovingEntity;
+    /**
+     * Confirm successful processing. Returns false if the lease is stale, i.e. the source already
+     * took the entity back (an SQS visibility timeout expired) and the confirmation has no effect.
+     */
+    ack(): boolean;
+}
+/** A source that workers pull entities from: a plain Queue or a MessageQueue. */
+export interface PullSource {
+    /** True if an entity that is received but never acked comes back (visibility-timeout semantics). */
+    readonly redeliversUnacked: boolean;
+    /** Take the next available entity, or null if there is none. */
+    receive(): Lease | null;
+    /** Register a waiter to be notified whenever an entity becomes available. */
+    addWaiter(waiter: QueueWaiter): void;
+}
+//# sourceMappingURL=pullable.d.ts.map

package/dist/components/pullable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pullable.d.ts","sourceRoot":"","sources":["../../src/components/pullable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,cAAc,IAAI,IAAI,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B;;;OAGG;IACH,GAAG,IAAI,OAAO,CAAC;CAChB;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,oGAAoG;IACpG,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,gEAAgE;IAChE,OAAO,IAAI,KAAK,GAAG,IAAI,CAAC;IACxB,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACtC"}

package/dist/components/pullable.js

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

package/dist/components/pullable.js.map

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

package/dist/components/queue.d.ts

@@ -0,0 +1,32 @@
+import { LinkedComponent, type ComponentInit, type MovingEntity, type SimContext } from "../model/index.js";
+import type { ComponentSchema } from "../schema/index.js";
+import type { Lease, PullSource, QueueWaiter } from "./pullable.js";
+/**
+ * FIFO queue with an optional maximum length. Arrivals beyond `maxLength` are dropped and counted.
+ * Servers pull entities with {@link Queue.poll}; waiting servers are notified on arrival.
+ * WorkerPools pull through the {@link PullSource} interface.
+ */
+export declare class Queue extends LinkedComponent implements PullSource {
+    static readonly schema: ComponentSchema<Queue>;
+    private readonly items;
+    private readonly waiters;
+    private readonly maxLength;
+    private readonly lengthStat;
+    private readonly waitTally;
+    private dropped;
+    constructor(ctx: SimContext, init: ComponentInit);
+    private get now();
+    /** Entities currently waiting. */
+    get length(): number;
+    /** Register a server to be notified whenever an entity is enqueued. */
+    addWaiter(waiter: QueueWaiter): void;
+    addEntity(entity: MovingEntity): void;
+    /** Remove and return the oldest waiting entity, or null if empty. */
+    poll(): MovingEntity | null;
+    /** A plain queue never takes entities back: a received entity is gone, and `ack` always succeeds. */
+    readonly redeliversUnacked = false;
+    receive(): Lease | null;
+    private lengthChanged;
+    resetStatistics(): void;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/components/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/components/queue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAExH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEpE;;;;GAIG;AACH,qBAAa,KAAM,SAAQ,eAAgB,YAAW,UAAU;IAC9D,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,CAAC,CAe5C;IAEF,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiE;IACvF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,OAAO,CAAK;gBAER,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;IAMhD,OAAO,KAAK,GAAG,GAEd;IAED,kCAAkC;IAClC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,uEAAuE;IACvE,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAI3B,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAc9C,qEAAqE;IACrE,IAAI,IAAI,YAAY,GAAG,IAAI;IAS3B,qGAAqG;IACrG,QAAQ,CAAC,iBAAiB,SAAS;IAEnC,OAAO,IAAI,KAAK,GAAG,IAAI;IAKvB,OAAO,CAAC,aAAa;IAKZ,eAAe,IAAI,IAAI;CAMjC"}

package/dist/components/queue.js

@@ -0,0 +1,88 @@
+import { FifoBuffer, LinkedComponent } from "../model/index.js";
+import { Tally, TimeWeightedStat } from "../stats/index.js";
+/**
+ * FIFO queue with an optional maximum length. Arrivals beyond `maxLength` are dropped and counted.
+ * Servers pull entities with {@link Queue.poll}; waiting servers are notified on arrival.
+ * WorkerPools pull through the {@link PullSource} interface.
+ */
+export class Queue extends LinkedComponent {
+    static schema = {
+        type: "Queue",
+        description: "FIFO queue with an optional capacity. Arrivals beyond maxLength are dropped and counted.",
+        roles: ["receiver", "queue", "pullable"],
+        inputs: [
+            { key: "maxLength", type: "integer", unit: "dimensionless", min: 1, required: false, description: "Maximum number of waiting entities. Unlimited if omitted." },
+        ],
+        links: [],
+        outputs: [
+            { key: "QueueLength", unit: "dimensionless", series: true, description: "Entities currently waiting.", get: (q) => q.length },
+            { key: "AverageQueueLength", unit: "dimensionless", description: "Time-weighted average number waiting.", get: (q) => q.lengthStat.mean(q.now) },
+            { key: "MaxQueueLength", unit: "dimensionless", description: "Largest number waiting.", get: (q) => q.lengthStat.max(q.now) },
+            { key: "AverageQueueTime", unit: "time", description: "Mean time an entity waited before leaving the queue.", get: (q) => q.waitTally.mean() },
+            { key: "NumberDropped", unit: "dimensionless", description: "Arrivals rejected because the queue was full.", get: (q) => q.dropped },
+        ],
+    };
+    items = new FifoBuffer();
+    waiters = [];
+    maxLength;
+    lengthStat;
+    waitTally = new Tally();
+    dropped = 0;
+    constructor(ctx, init) {
+        super(ctx, init, "Empty");
+        this.maxLength = init.inputs["maxLength"];
+        this.lengthStat = new TimeWeightedStat(ctx.kernel.currentTick, 0);
+    }
+    get now() {
+        return this.ctx.kernel.currentTick;
+    }
+    /** Entities currently waiting. */
+    get length() {
+        return this.items.length;
+    }
+    /** Register a server to be notified whenever an entity is enqueued. */
+    addWaiter(waiter) {
+        this.waiters.push(waiter);
+    }
+    addEntity(entity) {
+        if (this.maxLength !== undefined && this.items.length >= this.maxLength) {
+            this.dropped++;
+            return;
+        }
+        this.noteAdded();
+        this.items.push({ entity, enteredAt: this.now });
+        this.lengthChanged();
+        for (const w of this.waiters) {
+            if (this.items.length === 0)
+                break;
+            w.queueHasEntity();
+        }
+    }
+    /** Remove and return the oldest waiting entity, or null if empty. */
+    poll() {
+        const item = this.items.shift();
+        if (item === undefined)
+            return null;
+        this.waitTally.add(this.ctx.kernel.ticksToSeconds(this.now - item.enteredAt));
+        this.lengthChanged();
+        this.noteCompleted();
+        return item.entity;
+    }
+    /** A plain queue never takes entities back: a received entity is gone, and `ack` always succeeds. */
+    redeliversUnacked = false;
+    receive() {
+        const entity = this.poll();
+        return entity === null ? null : { entity, ack: () => true };
+    }
+    lengthChanged() {
+        this.lengthStat.set(this.now, this.items.length);
+        this.setState(this.items.length === 0 ? "Empty" : "NonEmpty");
+    }
+    resetStatistics() {
+        super.resetStatistics();
+        this.lengthStat.reset(this.now);
+        this.waitTally.reset();
+        this.dropped = 0;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/components/queue.js.map

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

package/dist/components/rate-limiter.d.ts

@@ -0,0 +1,24 @@
+import { LinkedComponent, type ComponentInit, type MovingEntity, type SimContext } from "../model/index.js";
+import type { ComponentSchema } from "../schema/index.js";
+/**
+ * Token-bucket rate limiter (an API-gateway-style throttle). The bucket starts full with `burst`
+ * tokens and refills continuously at `rate` tokens per second, never exceeding `burst`. Each entity
+ * takes one token and is passed to `next`; with no token it is rejected: sent to `onReject`, or
+ * dropped and counted. Deterministic: it uses no randomness.
+ */
+export declare class RateLimiter extends LinkedComponent {
+    static readonly schema: ComponentSchema<RateLimiter>;
+    private readonly rate;
+    private readonly burst;
+    private tokens;
+    private lastTick;
+    private onReject;
+    private allowed;
+    private rejected;
+    constructor(ctx: SimContext, init: ComponentInit);
+    setLink(key: string, target: LinkedComponent): void;
+    private currentTokens;
+    addEntity(entity: MovingEntity): void;
+    resetStatistics(): void;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/components/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/components/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC5G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1D;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,eAAe;IAC9C,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,WAAW,CAAC,CAkBlD;IAEF,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAK;gBAET,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;IAQvC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAK5D,OAAO,CAAC,aAAa;IAUZ,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAYrC,eAAe,IAAI,IAAI;CAKjC"}

package/dist/components/rate-limiter.js

@@ -0,0 +1,77 @@
+import { LinkedComponent } from "../model/index.js";
+/** Float slack so that e.g. five refills of 0.2 tokens count as one whole token. */
+const EPSILON = 1e-9;
+/**
+ * Token-bucket rate limiter (an API-gateway-style throttle). The bucket starts full with `burst`
+ * tokens and refills continuously at `rate` tokens per second, never exceeding `burst`. Each entity
+ * takes one token and is passed to `next`; with no token it is rejected: sent to `onReject`, or
+ * dropped and counted. Deterministic: it uses no randomness.
+ */
+export class RateLimiter extends LinkedComponent {
+    static schema = {
+        type: "RateLimiter",
+        description: "Token-bucket rate limiter: passes entities while tokens last, rejects the rest.",
+        roles: ["receiver"],
+        inputs: [
+            { key: "rate", type: "number", unit: "rate", min: 0, required: true, description: "Tokens added per second (the sustained allowed rate)." },
+            { key: "burst", type: "number", unit: "dimensionless", min: 1, required: true, description: "Bucket size: the largest burst that passes at once. The bucket starts full." },
+        ],
+        links: [
+            { key: "next", description: "Where allowed entities are sent.", required: false, accepts: "receiver" },
+            { key: "onReject", description: "Where rejected entities are sent. Dropped and counted if omitted.", required: false, accepts: "receiver" },
+        ],
+        outputs: [
+            { key: "NumberAllowed", unit: "dimensionless", description: "Entities that got a token.", get: (l) => l.allowed },
+            { key: "NumberRejected", unit: "dimensionless", description: "Entities rejected for lack of a token.", get: (l) => l.rejected },
+            { key: "RejectionFraction", unit: "dimensionless", description: "Rejected / (allowed + rejected).", get: (l) => (l.allowed + l.rejected === 0 ? NaN : l.rejected / (l.allowed + l.rejected)) },
+            { key: "Tokens", unit: "dimensionless", series: true, description: "Tokens currently in the bucket.", get: (l) => l.currentTokens() },
+        ],
+    };
+    rate;
+    burst;
+    tokens;
+    lastTick;
+    onReject = null;
+    allowed = 0;
+    rejected = 0;
+    constructor(ctx, init) {
+        super(ctx, init, "Idle");
+        this.rate = init.inputs["rate"];
+        this.burst = init.inputs["burst"];
+        this.tokens = this.burst;
+        this.lastTick = ctx.kernel.currentTick;
+    }
+    setLink(key, target) {
+        if (key === "onReject")
+            this.onReject = target;
+        else
+            super.setLink(key, target);
+    }
+    currentTokens() {
+        const now = this.ctx.kernel.currentTick;
+        if (now > this.lastTick) {
+            const seconds = this.ctx.kernel.ticksToSeconds(now - this.lastTick);
+            this.tokens = Math.min(this.burst, this.tokens + seconds * this.rate);
+            this.lastTick = now;
+        }
+        return this.tokens;
+    }
+    addEntity(entity) {
+        if (this.currentTokens() >= 1 - EPSILON) {
+            this.tokens = Math.max(0, this.tokens - 1);
+            this.allowed++;
+            this.noteAdded();
+            this.sendToNext(entity);
+        }
+        else {
+            this.rejected++;
+            this.onReject?.addEntity(entity);
+        }
+    }
+    resetStatistics() {
+        super.resetStatistics();
+        this.allowed = 0;
+        this.rejected = 0;
+    }
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/components/rate-limiter.js.map

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

package/dist/components/registry.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentInit, LinkedComponent, SimContext } from "../model/index.js";
+import type { ComponentSchema } from "../schema/index.js";
+/** A component class: a static schema plus a constructor. */
+export interface ComponentClass {
+    readonly schema: ComponentSchema;
+    new (ctx: SimContext, init: ComponentInit): LinkedComponent;
+}
+/** Maps component type names (as used in model files) to classes. */
+export declare class ComponentRegistry {
+    private readonly classes;
+    register(cls: ComponentClass): this;
+    get(type: string): ComponentClass | undefined;
+    /** Registered type names, in registration order. */
+    types(): string[];
+    schemas(): ComponentSchema[];
+}
+/** A registry containing every built-in component: the generic ones and the cloud ones. */
+export declare function createDefaultRegistry(): ComponentRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/components/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/components/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAW1D,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,KAAK,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa,GAAG,eAAe,CAAC;CAC7D;AAED,qEAAqE;AACrE,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAMnC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,oDAAoD;IACpD,KAAK,IAAI,MAAM,EAAE;IAIjB,OAAO,IAAI,eAAe,EAAE;CAG7B;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,IAAI,iBAAiB,CAWzD"}

package/dist/components/registry.js

@@ -0,0 +1,43 @@
+import { EntityGenerator } from "./generator.js";
+import { Autoscaler } from "./autoscaler.js";
+import { MessageQueue } from "./message-queue.js";
+import { Queue } from "./queue.js";
+import { RateLimiter } from "./rate-limiter.js";
+import { RetryPolicy } from "./retry-policy.js";
+import { Server } from "./server.js";
+import { EntitySink } from "./sink.js";
+import { WorkerPool } from "./worker-pool.js";
+/** Maps component type names (as used in model files) to classes. */
+export class ComponentRegistry {
+    classes = new Map();
+    register(cls) {
+        if (this.classes.has(cls.schema.type))
+            throw new Error(`component type already registered: ${cls.schema.type}`);
+        this.classes.set(cls.schema.type, cls);
+        return this;
+    }
+    get(type) {
+        return this.classes.get(type);
+    }
+    /** Registered type names, in registration order. */
+    types() {
+        return [...this.classes.keys()];
+    }
+    schemas() {
+        return [...this.classes.values()].map((c) => c.schema);
+    }
+}
+/** A registry containing every built-in component: the generic ones and the cloud ones. */
+export function createDefaultRegistry() {
+    return new ComponentRegistry()
+        .register(EntityGenerator)
+        .register(Queue)
+        .register(Server)
+        .register(EntitySink)
+        .register(MessageQueue)
+        .register(WorkerPool)
+        .register(RetryPolicy)
+        .register(RateLimiter)
+        .register(Autoscaler);
+}
+//# sourceMappingURL=registry.js.map

package/dist/components/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/components/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQ9C,qEAAqE;AACrE,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAC;IAE7D,QAAQ,CAAC,GAAmB;QAC1B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAChH,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,oDAAoD;IACpD,KAAK;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;CACF;AAED,2FAA2F;AAC3F,MAAM,UAAU,qBAAqB;IACnC,OAAO,IAAI,iBAAiB,EAAE;SAC3B,QAAQ,CAAC,eAAe,CAAC;SACzB,QAAQ,CAAC,KAAK,CAAC;SACf,QAAQ,CAAC,MAAM,CAAC;SAChB,QAAQ,CAAC,UAAU,CAAC;SACpB,QAAQ,CAAC,YAAY,CAAC;SACtB,QAAQ,CAAC,UAAU,CAAC;SACpB,QAAQ,CAAC,WAAW,CAAC;SACrB,QAAQ,CAAC,WAAW,CAAC;SACrB,QAAQ,CAAC,UAAU,CAAC,CAAC;AAC1B,CAAC"}

package/dist/components/retry-policy.d.ts

@@ -0,0 +1,41 @@
+import { LinkedComponent, type ComponentInit, type MovingEntity, type SimContext } from "../model/index.js";
+import type { ComponentSchema } from "../schema/index.js";
+/**
+ * Retries failed attempts with exponential backoff and jitter.
+ *
+ * Wiring: send entities *into* the RetryPolicy, point `next` at the thing that can fail (a
+ * WorkerPool), and point that thing's `onFailure` / `onThrottle` links back at the RetryPolicy. The
+ * first time an entity arrives it is a fresh request and is forwarded immediately. If it comes back
+ * it is a failed attempt: after a backoff delay it is forwarded again, until `maxAttempts` attempts
+ * have been made, at which point it goes to `giveUp` (or is dropped and counted).
+ *
+ * The attempt count lives on the entity, so an entity should pass through a given RetryPolicy once.
+ *
+ * Delay before retry n (n = attempts made so far, starting at 1):
+ * `d = min(maxDelay, baseDelay * multiplier^(n-1))`, then jitter: `none` uses d, `full` draws
+ * uniformly from [0, d], `equal` draws from [d/2, d] (the AWS Architecture Blog definitions).
+ */
+export declare class RetryPolicy extends LinkedComponent {
+    static readonly schema: ComponentSchema<RetryPolicy>;
+    private readonly attemptKey;
+    private readonly maxAttempts;
+    private readonly baseDelay;
+    private readonly multiplier;
+    private readonly maxDelay;
+    private readonly jitter;
+    private readonly unit;
+    private giveUpTarget;
+    private requests;
+    private attempts;
+    private retries;
+    private givenUp;
+    private waiting;
+    constructor(ctx: SimContext, init: ComponentInit);
+    setLink(key: string, target: LinkedComponent): void;
+    addEntity(entity: MovingEntity): void;
+    private send;
+    /** Delay in seconds before the retry that follows `made` attempts. */
+    private backoff;
+    resetStatistics(): void;
+}
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/components/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../src/components/retry-policy.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE5G,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAY,SAAQ,eAAe;IAC9C,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,WAAW,CAAC,CAuBlD;IAEF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAK;gBAER,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,aAAa;IAYvC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAKnD,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAyB9C,OAAO,CAAC,IAAI;IAKZ,sEAAsE;IACtE,OAAO,CAAC,OAAO;IAYN,eAAe,IAAI,IAAI;CAOjC"}