@toa.io/core 1.0.0-alpha.293 → 1.0.0-alpha.299

package/transpiled/outbox.js

@@ -0,0 +1,424 @@
+import { console } from 'openspan';
+import { Connector } from './connector.js';
+import { newid } from './entities/newid.js';
+import * as trail from './trail.js';
+import { environment } from '@toa.io/generic';
+/**
+ * Owns the intent to publish. A row is built before the write so that the storage can commit
+ * it in the same transaction as the entity; publication then happens off the operation's path,
+ * and anything that fails to publish is recovered from the row.
+ *
+ * The mechanism is a safety net: in a healthy system the row is written, published within
+ * milliseconds by the same process, and marked published on that process's next tick.
+ *
+ * A storage that cannot commit a row atomically has no outbox, and this degrades to the
+ * inline emission it replaces.
+ */
+export class Outbox extends Connector {
+    #destinations;
+    #storage;
+    #atom;
+    #gap;
+    #interval;
+    #batch;
+    #defer;
+    /*
+       * Everything a destination is answerable for is held per destination, which is what keeps
+       * one from delaying another: a dead one fills its own in-flight cap and the cycle stops
+       * handing it rows, while the rest go on being published and settled.
+       */
+    /** ids this process has published, by destination, held until a cycle marks them */
+    #published = new Map();
+    /** in-flight publications, by destination, awaited (with a bound) on close */
+    #inflight = new Map();
+    /** rows this replica is publishing right now, so a cycle does not pick them up again */
+    #publishing = new Map();
+    #timer;
+    #off;
+    #pumping = false;
+    /** cycles in a row this replica has been assigned no lane */
+    #unassigned = 0;
+    #closing = false;
+    // eslint-disable-next-line max-params
+    constructor(destinations, storage, atom, options = {}) {
+        super();
+        this.#destinations = destinations;
+        this.#storage = storage;
+        this.#atom = atom;
+        for (const destination of destinations) {
+            this.#published.set(destination.name, new Set());
+            this.#inflight.set(destination.name, new Set());
+            this.#publishing.set(destination.name, new Set());
+        }
+        this.#interval = number('TOA_OUTBOX_INTERVAL', options.interval, INTERVAL);
+        this.#batch = number('TOA_OUTBOX_BATCH', options.batch, BATCH);
+        this.#gap = options.gap ?? this.#interval * K;
+        this.#defer = environment.get('TOA_OUTBOX_DEFER') === '1';
+        // one at a time: an array would link the group it makes rather than its members
+        for (const destination of destinations)
+            this.depends(destination);
+        this.depends(atom);
+        if (storage !== undefined)
+            this.depends(storage);
+    }
+    /** whether the storage can commit a row atomically with the entity */
+    get durable() {
+        return this.#storage?.outbox !== undefined;
+    }
+    /**
+     * An assignment's images are the write's own, so it hands over an event with neither, and
+     * the storage fills them in.
+     */
+    row(event) {
+        const row = {
+            id: newid(),
+            lane: this.#lane(),
+            published: false,
+            pending: Date.now() + this.#gap,
+            outstanding: this.#destinations.map((destination) => destination.name),
+            event: event
+        };
+        /*
+         * This runs on the operation's own path, which is the only moment the chain is in scope:
+         * the pump that publishes the row may be another replica, an hour later. A row that had
+         * no chain stores no field.
+         */
+        const hops = trail.current();
+        if (hops !== undefined)
+            row.trail = hops;
+        return row;
+    }
+    /**
+     * Hands a committed row over. Awaited by the caller only on the legacy path — with an
+     * outbox this returns at once and the broker leaves the operation's path.
+     */
+    publish(row) {
+        // without a durable outbox this is the inline path, and the caller awaits every destination
+        if (!this.durable)
+            return this.#inline(row);
+        /*
+         * A publication started while the pump is closing would outlive the emitters it needs,
+         * and `comq` waits on a connection that is going rather than failing. The row is already
+         * durable, so leaving it is exactly what it is for.
+         */
+        if (this.#closing || this.#defer)
+            return;
+        this.#publish(row);
+    }
+    /**
+     * The inline path, where there is no row to come back to: every destination is attempted and
+     * the operation waits for all of them, so a failure reaches whoever wrote.
+     */
+    async #inline(row) {
+        const sending = this.#destinations
+            .filter((destination) => row.outstanding.includes(destination.name))
+            .map(async (destination) => destination.emit(row));
+        await Promise.all(sending);
+    }
+    async open() {
+        if (!this.durable)
+            return;
+        if (this.#defer)
+            console.warn('Outbox immediate publication is deferred; events are published by the pump only');
+        this.#timer = setInterval(() => {
+            this.#tick();
+        }, this.#interval);
+        this.#timer.unref();
+        /*
+         * A lane changing hands is exactly when rows stranded in it become this replica's to
+         * publish, and the cycle would not notice for up to an interval. Being told costs a cycle
+         * that finds nothing in the usual case, where the claim arrives once and never changes.
+         */
+        this.#off = this.#atom.onassigned(() => {
+            this.#tick();
+        });
+    }
+    async close() {
+        this.#closing = true;
+        this.#off?.();
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+        await this.#drain();
+        await this.#mark();
+    }
+    /**
+     * Publishes one row and swallows the failure: the row stays unpublished and comes back on a
+     * later cycle, which is the whole point of having written it.
+     *
+     * There is no timeout here on purpose. A publication is a confirmed write to a durable
+     * exchange, and `comq` waits for the broker to come back rather than failing — abandoning
+     * it would not stop it, it would only mean the row is published twice once it lands. What
+     * bounds this instead is the in-flight cap and the drain on close.
+     *
+     */
+    /** @returns what it started, so a cycle can wait for it before marking */
+    #publish(row) {
+        const started = [];
+        for (const destination of this.#destinations)
+            if (this.#due(row, destination.name))
+                started.push(this.#send(row, destination));
+        return started;
+    }
+    /**
+     * Whether this row is still this process's to send to that destination. A destination the
+     * row names and this process does not have is not its to send, and is left where it is.
+     */
+    #due(row, destination) {
+        if (!row.outstanding.includes(destination))
+            return false;
+        const published = this.#published.get(destination);
+        if (published === undefined)
+            return false;
+        return !published.has(row.id) && !this.#publishing.get(destination).has(row.id);
+    }
+    /**
+     * Publishes one row to one destination and swallows the failure: the row stays outstanding
+     * for it and comes back on a later cycle, which is the whole point of having written it.
+     * Nothing here reaches the other destinations of the same row.
+     *
+     * There is no timeout on purpose. A publication is a confirmed write to a durable exchange,
+     * and `comq` waits for the broker to come back rather than failing — abandoning it would not
+     * stop it, it would only mean the row is published twice once it lands. What bounds this
+     * instead is the in-flight cap, which is per destination so that a dead one cannot stop the
+     * cycle from feeding the others, and the drain on close.
+     */
+    async #send(row, destination) {
+        const name = destination.name;
+        const published = this.#published.get(name);
+        const publishing = this.#publishing.get(name);
+        const inflight = this.#inflight.get(name);
+        if (inflight.size >= INFLIGHT || published.size >= PUBLISHED)
+            return;
+        publishing.add(row.id);
+        const sending = destination.emit(row);
+        inflight.add(sending);
+        try {
+            await sending;
+            published.add(row.id);
+        }
+        catch (error) {
+            console.warn('Outbox publication failed', { row: row.id, destination: name, error });
+        }
+        finally {
+            inflight.delete(sending);
+            publishing.delete(row.id);
+        }
+    }
+    /**
+     * `comq` retries a publish for as long as the broker is down rather than rejecting, so an
+     * unbounded drain outlives any grace period.
+     *
+     */
+    async #drain() {
+        const inflight = [...this.#inflight.values()].flatMap((set) => [...set]);
+        if (inflight.length === 0)
+            return;
+        await Promise.race([Promise.allSettled(inflight), delay(DRAIN)]);
+    }
+    /**
+     * Reads what is due, publishes it, and marks everything this process has sent — what it just
+     * published and what the immediate path published since the last cycle. One cycle at a time.
+     *
+     */
+    #tick() {
+        if (this.#pumping)
+            return;
+        this.#pumping = true;
+        void this.#pump().finally(() => (this.#pumping = false));
+    }
+    async #pump() {
+        this.#assignment();
+        let page;
+        let after;
+        do {
+            page = await this.#read(after);
+            if (page.length === 0)
+                break;
+            // so a page is never read twice
+            after = page[page.length - 1]?.id;
+            /*
+             * A row is unpublished in the database until a cycle marks it, so a page includes what
+             * this replica is sending right now and what a failed marking left behind. Only this
+             * process knows either.
+             */
+            const rows = page.filter((row) => this.#destinations.some((destination) => this.#due(row, destination.name)));
+            if (rows.length > 0) {
+                console.debug('Outbox recovering unpublished rows', { count: rows.length });
+                // every row is given its chance, at every destination it is still outstanding for;
+                // what a broker refused stays outstanding there and comes back on a later cycle
+                await this.#awaited(rows.flatMap((row) => this.#publish(row)));
+            }
+            // a full page is a page that may have been cut short
+        } while (page.length === this.#batch);
+        await this.#mark();
+    }
+    /**
+     * Says when this replica has owned nothing for long enough that nothing is going to assign
+     * it anything.
+     *
+     * Owning no lane is ordinary for a moment — a replica that has just started has not been
+     * told yet — and is why nothing here refuses at boot: one cycle of it cannot be told from an
+     * atomicity that is absent. Ten in a row can, and what it means is that this outbox recovers
+     * nothing: a publication that failed is never retried, and that change is lost with the
+     * process that failed to make it.
+     *
+     * Said every ten cycles rather than once, so that it is still there to be found in a log
+     * read long after the deployment that broke it, and once when it is over.
+     */
+    #assignment() {
+        const lanes = this.#atom.slots(LANES);
+        if (lanes !== null && lanes.length > 0) {
+            if (this.#unassigned >= UNASSIGNED)
+                console.info('Outbox lanes assigned, recovery resumed');
+            this.#unassigned = 0;
+            return;
+        }
+        this.#unassigned++;
+        if (this.#unassigned % UNASSIGNED === 0)
+            console.warn('Outbox owns no lane and recovers nothing', {
+                cycles: this.#unassigned,
+                interval: this.#interval
+            });
+    }
+    /**
+     * One page of what is due. In a healthy system the first one is empty, every cycle — a row is
+     * due only if the process that wrote it failed to publish or died before marking it.
+     *
+     * Reading is suspended, not stopped, while this replica does not know which lanes are its
+     * own: the cycle keeps running and keeps marking, and reading resumes as soon as an
+     * assignment arrives. Reading without an assignment would be a different guarantee, where
+     * every replica publishes every stranded row.
+     *
+     * @param after the last id of the page before, so a page is never read twice
+     */
+    async #read(after) {
+        const lanes = this.#atom.slots(LANES);
+        if (lanes === null || lanes.length === 0)
+            return [];
+        return this.#storage
+            .outbox.pending(lanes, Date.now(), this.#batch, after)
+            .catch((error) => {
+            console.warn('Outbox read failed', { error });
+            return [];
+        });
+    }
+    /**
+     * Waits for what this cycle started, so that it marks what it sent rather than leaving it to
+     * the next one — but not past its own interval. A publication is never abandoned: it stays in
+     * flight, `#publishing` keeps a later cycle from sending it again, and the drain on close
+     * still waits for it. What is bounded is only how long a cycle waits before marking the rest,
+     * so that one destination with nothing to say cannot hold up the settling of another.
+     */
+    async #awaited(started) {
+        if (started.length === 0)
+            return;
+        await Promise.race([Promise.allSettled(started), delay(this.#interval)]);
+    }
+    /**
+     * One batched write for many rows, which is why the ids are held in memory rather than
+     * marked one by one. Ids that fail to be marked are kept and retried; a row that is never
+     * marked is simply published again, which is within the contract.
+     *
+     * Rows are grouped by the destinations that completed for them, so the ordinary case — every
+     * destination landing in the same window — is one group and one write, as it was when there
+     * was only ever one. A second write happens where the destinations diverged, which is the
+     * failure this exists for.
+     */
+    async #mark() {
+        for (const [destinations, ids] of this.#groups())
+            await this.#settle(destinations, ids);
+    }
+    /** @private */
+    async #settle(destinations, ids) {
+        try {
+            await this.#storage.outbox.settle(ids, destinations);
+        }
+        catch (error) {
+            console.warn('Outbox marking failed', { count: ids.length, error });
+            return;
+        }
+        for (const destination of destinations) {
+            const published = this.#published.get(destination);
+            for (const id of ids)
+                published.delete(id);
+        }
+    }
+    /**
+     * What has been published since the last cycle, as rows sharing the destinations that
+     * completed for them.
+     */
+    #groups() {
+        /** the destinations that completed for an id, in the order the destinations are held */
+        const completed = new Map();
+        for (const [destination, ids] of this.#published)
+            for (const id of ids) {
+                const names = completed.get(id);
+                if (names === undefined)
+                    completed.set(id, [destination]);
+                else
+                    names.push(destination);
+            }
+        const groups = new Map();
+        for (const [id, destinations] of completed) {
+            const key = destinations.join(SEPARATOR);
+            const group = groups.get(key);
+            if (group === undefined)
+                groups.set(key, [destinations, [id]]);
+            else
+                group[1].push(id);
+        }
+        return [...groups.values()];
+    }
+    /**
+     * A lane this replica currently owns, so that in steady state it settles its own rows
+     * before it ever reads them. Any lane at all when it owns none: the row still has to be
+     * written, and whoever ends up owning that lane will pump it.
+     *
+     */
+    #lane() {
+        const owned = this.#atom.slots(LANES);
+        return owned === null || owned.length === 0
+            ? Math.floor(Math.random() * LANES)
+            : owned[Math.floor(Math.random() * owned.length)];
+    }
+}
+function number(variable, declared, fallback) {
+    if (declared !== undefined)
+        return declared;
+    const value = Number(environment.get(variable));
+    return Number.isNaN(value) || value <= 0 ? fallback : value;
+}
+async function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref();
+    });
+}
+/**
+ * Constant, never configuration: rows carry their lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas of one component, and a
+ * power of two so that the common replica counts divide evenly.
+ */
+export const LANES = 128;
+/** one cycle reads, publishes and marks; in steady state it finds nothing to read */
+/**
+ * Cycles owning nothing before that is said out loud, and between one saying and the next.
+ * Long enough that a replica which has just started, or one whose assignment is being redrawn,
+ * says nothing at all.
+ */
+const UNASSIGNED = 10;
+const INTERVAL = 5000;
+/**
+ * `gap = interval * K`. Not a steady-state necessity — a replica writes into a lane it owns
+ * and marks what it published — but a guard for when a lane changes hands between the write
+ * and the settle. Two cycles of separation, plus one of margin.
+ */
+const K = 3;
+/** how many rows one read brings back; the pump reads on while a page comes back full */
+const BATCH = 200;
+const DRAIN = 10_000;
+/** publications in flight at once, per destination */
+const INFLIGHT = 1000;
+const PUBLISHED = 10_000;
+/** what a group of destinations is keyed by; no name can hold it */
+const SEPARATOR = '\u0000';
+//# sourceMappingURL=outbox.js.map

package/transpiled/outbox.js.map

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

package/transpiled/query/options.js

@@ -20,7 +20,7 @@ function projection(projection, properties) {
     for (const property of projection)
         if (properties[property] === undefined)
             throw new QuerySyntaxException(`Projection property '${property}' is not defined`);
-    for (const property of ['VERSION', 'CREATED', 'UPDATED', 'DELETED'])
+    for (const property of ['VERSION', 'CREATED', 'UPDATED', 'DELETED', 'REGION'])
         if (!projection.includes(property))
             projection.push(property);
 }

package/transpiled/query/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../source/query/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAIvD,MAAM,UAAU,OAAO,CAAC,KAA0B,EAAE,UAAsB;IACxE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAEvE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAE5E,OAAO,KAAgB,CAAA;AACzB,CAAC;AAED,SAAS,IAAI,CAAC,IAAc,EAAE,UAAsB;IAClD,MAAM,MAAM,GAA4B,EAAE,CAAA;IAE1C,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAEhD,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,kBAAkB,QAAQ,kBAAkB,CAAC,CAAA;QAE9E,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,IAAI,KAAK,CAAC,CAAC,CAAA;IAC7C,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,UAAU,CAAC,UAAoB,EAAE,UAAsB;IAC9D,KAAK,MAAM,QAAQ,IAAI,UAAU;QAC/B,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,wBAAwB,QAAQ,kBAAkB,CAAC,CAAA;IAEtF,KAAK,MAAM,QAAQ,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC;QACjE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AACjE,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../source/query/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAIvD,MAAM,UAAU,OAAO,CAAC,KAA0B,EAAE,UAAsB;IACxE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAEvE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,UAAU,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;IAE5E,OAAO,KAAgB,CAAA;AACzB,CAAC;AAED,SAAS,IAAI,CAAC,IAAc,EAAE,UAAsB;IAClD,MAAM,MAAM,GAA4B,EAAE,CAAA;IAE1C,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAEhD,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,kBAAkB,QAAQ,kBAAkB,CAAC,CAAA;QAE9E,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,IAAI,KAAK,CAAC,CAAC,CAAA;IAC7C,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,UAAU,CAAC,UAAoB,EAAE,UAAsB;IAC9D,KAAK,MAAM,QAAQ,IAAI,UAAU;QAC/B,IAAI,UAAU,CAAC,QAAQ,CAAC,KAAK,SAAS;YACpC,MAAM,IAAI,oBAAoB,CAAC,wBAAwB,QAAQ,kBAAkB,CAAC,CAAA;IAEtF,KAAK,MAAM,QAAQ,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC;QAC3E,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AACjE,CAAC"}

package/transpiled/receiver.js

@@ -1,6 +1,7 @@
 import { console, decode, run } from 'openspan';
 import { add } from '@toa.io/generic';
 import { Connector } from './connector.js';
+import * as trail from './trail.js';
 export class Receiver extends Connector {
     #conditioned;
     #adaptive;
@@ -50,7 +51,12 @@ export class Receiver extends Connector {
     }
     /** @hot */
     async receive(message) {
-        const { payload, telemetry, ...extensions } = message;
+        /*
+         * `trail` is taken out by name rather than left to `add`, which leaves an array the
+         * request already has alone and shares the deserialized one by reference where it does
+         * not — and validates neither.
+         */
+        const { payload, telemetry, trail: inbound, ...extensions } = message;
         if (this.#conditioned === true && (await this.#bridge?.condition(payload)) === false)
             return;
         const request = await this.#request(payload);
@@ -58,6 +64,13 @@ export class Receiver extends Connector {
         // set after `add`, so that a message field can not spoof the origin
         if (this.#origin !== undefined)
             request.source = this.#origin;
+        /*
+         * The event is a hop of its own. What an operator rewires to break a cycle is the
+         * subscription rather than the operation, so a chain that named only operations would not
+         * say how a component was re-entered. Refusing is left to `Component.invoke`, one hop
+         * later, which acquires and commits nothing before it.
+         */
+        request.trail = [...trail.received(inbound), trail.event(this.#destination)];
         // continue the trace from the producer span
         const remote = telemetry === undefined ? null : decode(telemetry);
         const task = async () => {

package/transpiled/receiver.js.map

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

package/transpiled/remote.js

@@ -1,11 +1,10 @@
-import assert from 'node:assert';
 import { Component } from './component.js';
+import { EndpointException } from './exceptions.js';
 export class Remote extends Component {
     kind = 'client';
     explain(endpoint) {
         if (!(endpoint in this.operations))
-            // `assert.fail`, not `assert.ok`: the message is built only when it is needed
-            assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`);
+            throw new EndpointException(`'${endpoint}' is not provided by '${this.locator.id}'`);
         return this.operations[endpoint].explain();
     }
 }

package/transpiled/remote.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote.js","sourceRoot":"","sources":["../source/remote.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAA;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAQ1C,MAAM,OAAO,MAAO,SAAQ,SAAqB;IAC5B,IAAI,GAAG,QAAiB,CAAA;IAEpC,OAAO,CAAC,QAAgB;QAC7B,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC;YAChC,8EAA8E;YAC9E,MAAM,CAAC,IAAI,CAAC,aAAa,QAAQ,yBAAyB,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAA;QAE/E,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAA;IAC5C,CAAC;CACF"}
+{"version":3,"file":"remote.js","sourceRoot":"","sources":["../source/remote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAQnD,MAAM,OAAO,MAAO,SAAQ,SAAqB;IAC5B,IAAI,GAAG,QAAiB,CAAA;IAEpC,OAAO,CAAC,QAAgB;QAC7B,IAAI,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC;YAChC,MAAM,IAAI,iBAAiB,CAAC,IAAI,QAAQ,yBAAyB,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAA;QAEtF,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAA;IAC5C,CAAC;CACF"}

package/transpiled/state.d.ts

@@ -3,7 +3,7 @@ import type { Readable } from 'node:stream';
 import type { Factory } from './entities/factory.js';
 import type { Entity } from './entities/entity.js';
 import type { Changeset } from './entities/changeset.js';
-import type { Outbox } from './outbox/outbox.js';
+import type { Outbox } from './outbox.js';
 import type { Query, Record, Storage } from './types/storages.js';
 /**
  * What an operation acquires and commits. One method per scope a manifest may declare, which

package/transpiled/trail.d.ts

@@ -0,0 +1,49 @@
+/**
+ * How many times one hop may appear before the call is refused, and how long a chain may grow
+ * at all. Repetition is the signal and names the cycle; depth is the backstop for a chain that
+ * grows without repeating a hop, and it is what bounds the array on the wire.
+ */
+export interface Limits {
+    repeats: number;
+    depth: number;
+}
+/**
+ * What the environment says, read where a component is built rather than once for the process,
+ * as the outbox reads its own — so a composition booted after a variable was set sees it.
+ *
+ * `TOA_TRAIL_REPEATS=0` refuses nothing: the chain is still stamped, carried and bounded. It is
+ * the off switch, and it exists because this refuses calls an application may be making today —
+ * a handshake written as `a > b > a > b > a` is three occurrences of one hop. A breaker with no
+ * way to open it is itself the outage.
+ */
+export declare function limits(): Limits;
+/** The chain that led to the invocation running now, where there is one. */
+export declare function current(): string[] | undefined;
+/** Runs `task` as the hop the chain now ends with. */
+export declare function follow<T>(hops: string[], task: () => Promise<T>): Promise<T>;
+/**
+ * The chain this hop makes, or a raise where it is one hop too many: a hop already taken
+ * `repeats` times is a cycle, and a chain past `depth` is one nothing meant to make. Both are
+ * permanent, so what hits one is set aside rather than tried again into the same loop.
+ *
+ * The chain is copied rather than appended to, which is what makes it a path down the call
+ * tree rather than a log of everything that happened — an operation calling one endpoint fifty
+ * times makes fifty chains of one hop, not one chain of fifty.
+ */
+export declare function extend(inbound: unknown, hop: string, limits: Limits): string[];
+/**
+ * How an event is named in a chain. The sigil is what tells it from an operation: the two are
+ * the same shape, a component may declare one of each under a single name, and `sync` is both
+ * the event every component inherits and an ordinary name for an operation.
+ *
+ * What an operator rewires to break a cycle is the subscription rather than the operation, so a
+ * chain that named only operations would not say how a component was re-entered.
+ */
+export declare function event(destination: string): string;
+/**
+ * What came off the wire, as a chain and nothing else. Neither the request contract nor a
+ * message validates this — a request is not validated at all once it is `authentic` — so a
+ * malformed one would otherwise become a `TypeError` where a named exception was contracted
+ * for. Bounding it is `extend`'s, one hop later, which is the only place the limits are known.
+ */
+export declare function received(value: unknown): string[];