@toa.io/core 1.0.0-alpha.3 → 1.0.0-alpha.300

package/transpiled/trail.js

@@ -0,0 +1,110 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { environment } from '@toa.io/generic';
+import { LoopException } from './exceptions.js';
+/**
+ * What the invocation running now came by: the chain of hops it passed through and the rule that
+ * refuses one that has come back to where it had been, and the identity of the call it is
+ * serving, from which the identity of every call it makes is derived.
+ *
+ * Ambient, like the trace context and for the same reason: an algorithm's `context` is built
+ * once per operation at boot and shared by every invocation of it, so nothing per-invocation
+ * can be handed to it. It is not the trace context's own store, which `console.span` replaces
+ * on every span and does not enter at all when the trace is unsampled — a chain that
+ * disappears under sampling is a breaker that stops breaking in production.
+ *
+ * One writer, `Component.invoke`, where the hop is appended and the identity is put in scope;
+ * two readers, `Call.invoke`, which puts both on the request it is about to send, and
+ * `Outbox.row`, which writes the chain onto the row so it outlives the operation that caused it.
+ */
+// as openspan holds its own: a process may carry two copies of this module, and a chain that
+// is empty because the writer sat in the other one is a breaker that never fires. The name says
+// what is stored, so a copy carrying the chain alone does not answer where the whole is expected
+const KEY = Symbol.for('toa.core.invocation');
+const storage = (globalThis[KEY] ??= new AsyncLocalStorage());
+/**
+ * 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 function limits() {
+    return {
+        repeats: number('TOA_TRAIL_REPEATS', 3),
+        depth: number('TOA_TRAIL_DEPTH', 32)
+    };
+}
+/** The invocation running now, where there is one. */
+export function current() {
+    return storage.getStore();
+}
+/** Runs `task` as the invocation the chain now ends with. */
+export async function follow(invocation, task) {
+    return storage.run(invocation, task);
+}
+/**
+ * The ordinal of the call `invocation` is about to make to `endpoint`, counting from zero, and
+ * counts it. Read once per call, on the caller's own path, which is where the order is the order
+ * the algorithm made them in.
+ */
+export function ordinal(invocation, endpoint) {
+    const made = invocation.calls.get(endpoint) ?? 0;
+    invocation.calls.set(endpoint, made + 1);
+    return made;
+}
+/**
+ * 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 function extend(inbound, hop, limits) {
+    const hops = clip(received(inbound), limits.depth);
+    const trail = [...hops, hop];
+    if (limits.repeats === 0)
+        return trail;
+    if (trail.length > limits.depth)
+        throw new LoopException(`Call chain is ${trail.length} hops deep`, trail);
+    let seen = 0;
+    for (const passed of hops)
+        if (passed === hop)
+            seen++;
+    if (seen + 1 >= limits.repeats)
+        throw new LoopException(`'${hop}' is hop ${seen + 1} of this chain`, trail);
+    return trail;
+}
+/**
+ * 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 function event(destination) {
+    return '~' + destination;
+}
+/**
+ * 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 function received(value) {
+    return Array.isArray(value) ? value.filter((hop) => typeof hop === 'string') : [];
+}
+// with the hop being appended that is one past the cap, which is enough to be refused; the
+// rest is a message buying memory, and where the rule is off it is what bounds the chain
+function clip(hops, depth) {
+    return hops.length > depth ? hops.slice(0, depth) : hops;
+}
+function number(variable, fallback) {
+    const declared = Number(environment.get(variable));
+    return Number.isNaN(declared) || declared < 0 ? fallback : declared;
+}
+//# sourceMappingURL=trail.js.map

package/transpiled/trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trail.js","sourceRoot":"","sources":["../source/trail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/C;;;;;;;;;;;;;;GAcG;AAEH,6FAA6F;AAC7F,gGAAgG;AAChG,iGAAiG;AACjG,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAA;AAI7C,MAAM,OAAO,GAAG,CAAE,UAAoB,CAAC,GAAG,CAAC,KAAK,IAAI,iBAAiB,EAAc,CAAC,CAAA;AA+BpF;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM;IACpB,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC,iBAAiB,EAAE,EAAE,CAAC;KACrC,CAAA;AACH,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,OAAO;IACrB,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAA;AAC3B,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,UAAsB,EACtB,IAAsB;IAEtB,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,UAAsB,EAAE,QAAgB;IAC9D,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IAEhD,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;IAExC,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,OAAgB,EAAE,GAAW,EAAE,MAAc;IAClE,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAClD,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAA;IAE5B,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAEtC,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK;QAC7B,MAAM,IAAI,aAAa,CAAC,iBAAiB,KAAK,CAAC,MAAM,YAAY,EAAE,KAAK,CAAC,CAAA;IAE3E,IAAI,IAAI,GAAG,CAAC,CAAA;IAEZ,KAAK,MAAM,MAAM,IAAI,IAAI;QAAE,IAAI,MAAM,KAAK,GAAG;YAAE,IAAI,EAAE,CAAA;IAErD,IAAI,IAAI,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO;QAC5B,MAAM,IAAI,aAAa,CAAC,IAAI,GAAG,YAAY,IAAI,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAA;IAE7E,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,KAAK,CAAC,WAAmB;IACvC,OAAO,GAAG,GAAG,WAAW,CAAA;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AACnF,CAAC;AAED,2FAA2F;AAC3F,yFAAyF;AACzF,SAAS,IAAI,CAAC,IAAc,EAAE,KAAa;IACzC,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AAC1D,CAAC;AAED,SAAS,MAAM,CAAC,QAAgB,EAAE,QAAgB;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;IAElD,OAAO,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;AACrE,CAAC"}

package/transpiled/transition.d.ts

@@ -0,0 +1,14 @@
+import { Operation } from './operation.js';
+import type { Contracts, Definition, Store } from './operation.js';
+import type { Cascade } from './cascade.js';
+import type { State } from './state.js';
+import type { Query as Translator } from './query.js';
+export declare class Transition extends Operation {
+    #private;
+    /** a transition is the only operation that commits */
+    protected mutable: boolean;
+    constructor(cascade: Cascade, scope: State, contract: Contracts, query: Translator, definition: Definition);
+    protected process(store: Store): Promise<any>;
+    protected acquire(store: Store): Promise<void>;
+    protected commit(store: Store): Promise<void>;
+}

package/transpiled/transition.js

@@ -0,0 +1,51 @@
+import { retry } from '@toa.io/generic';
+import { Operation } from './operation.js';
+import { StateConcurrencyException, StateNotFoundException } from './exceptions.js';
+export class Transition extends Operation {
+    /** a transition is the only operation that commits */
+    mutable = true;
+    #concurrency;
+    // eslint-disable-next-line max-params
+    constructor(cascade, scope, contract, query, definition) {
+        super(cascade, scope, contract, query, definition);
+        this.#concurrency = definition.concurrency;
+    }
+    async process(store) {
+        return retry(async (retry) => this.#retry(store, retry), RETRY);
+    }
+    async acquire(store) {
+        const { request } = store;
+        store.scope =
+            request.query === undefined ? this.scope.init() : await this.query(request.query);
+        const entity = store.scope;
+        if (entity === null ||
+            (entity.deleted && request.query?.options?.deleted !== true))
+            throw new StateNotFoundException();
+        store.state = entity.get();
+    }
+    async commit(store) {
+        const { scope, state, reply, retry } = store;
+        if (reply.error !== undefined)
+            return;
+        const entity = scope;
+        entity.set(state);
+        const result = await this.scope.commit(entity, store.request.input, this.call(store));
+        if (result !== false)
+            return;
+        if (this.#concurrency === 'retry')
+            await retry?.();
+        else
+            throw new StateConcurrencyException();
+    }
+    async #retry(store, retry) {
+        store.retry = retry;
+        return super.process(store);
+    }
+}
+const RETRY = {
+    base: 10,
+    max: 5000,
+    dispersion: 1,
+    retries: 32
+};
+//# sourceMappingURL=transition.js.map

package/transpiled/transition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition.js","sourceRoot":"","sources":["../source/transition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAOnF,MAAM,OAAO,UAAW,SAAQ,SAAS;IACvC,sDAAsD;IACnC,OAAO,GAAG,IAAI,CAAA;IAExB,YAAY,CAAoB;IAEzC,sCAAsC;IACtC,YACE,OAAgB,EAChB,KAAY,EACZ,QAAmB,EACnB,KAAiB,EACjB,UAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;QAElD,IAAI,CAAC,YAAY,GAAG,UAAU,CAAC,WAAW,CAAA;IAC5C,CAAC;IAEkB,KAAK,CAAC,OAAO,CAAC,KAAY;QAC3C,OAAO,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAA;IACjE,CAAC;IAEkB,KAAK,CAAC,OAAO,CAAC,KAAY;QAC3C,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAA;QAEzB,KAAK,CAAC,KAAK;YACT,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnF,MAAM,MAAM,GAAG,KAAK,CAAC,KAAsB,CAAA;QAE3C,IACE,MAAM,KAAK,IAAI;YACf,CAAC,MAAM,CAAC,OAAO,IAAK,OAAO,CAAC,KAAa,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;YAErE,MAAM,IAAI,sBAAsB,EAAE,CAAA;QAEpC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,GAAG,EAAE,CAAA;IAC5B,CAAC;IAEkB,KAAK,CAAC,MAAM,CAAC,KAAY;QAC1C,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;QAE5C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAM;QAErC,MAAM,MAAM,GAAG,KAAe,CAAA;QAE9B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAEjB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAErF,IAAI,MAAM,KAAK,KAAK;YAAE,OAAM;QAE5B,IAAI,IAAI,CAAC,YAAY,KAAK,OAAO;YAAE,MAAM,KAAK,EAAE,EAAE,CAAA;;YAC7C,MAAM,IAAI,yBAAyB,EAAE,CAAA;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAY,EAAE,KAAyB;QAClD,KAAK,CAAC,KAAK,GAAG,KAAK,CAAA;QAEnB,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;CACF;AAED,MAAM,KAAK,GAAG;IACZ,IAAI,EAAE,EAAE;IACR,GAAG,EAAE,IAAI;IACT,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,EAAE;CACZ,CAAA"}

package/transpiled/transmission.d.ts

@@ -0,0 +1,8 @@
+import { Connector } from './connector.js';
+import type { Consumer, Terms } from './types/bindings.js';
+import type { Request } from './types/request.js';
+export declare class Transmission extends Connector {
+    #private;
+    constructor(bindings: Consumer[]);
+    request(request: Request, terms?: Terms): Promise<any>;
+}

package/transpiled/transmission.js

@@ -0,0 +1,30 @@
+import { Connector } from './connector.js';
+import { TransmissionException } from './exceptions.js';
+export class Transmission extends Connector {
+    #bindings;
+    constructor(bindings) {
+        super();
+        this.#bindings = bindings;
+        this.depends(bindings);
+    }
+    async request(request, terms) {
+        let reply = false;
+        let i = 0;
+        while (reply === false && i < this.#bindings.length) {
+            const binding = this.#bindings[i];
+            i++;
+            if (request?.task === true) {
+                if (binding.task === undefined)
+                    continue;
+                await binding.task(request);
+                reply = null;
+            }
+            else
+                reply = await binding.request(request, terms);
+        }
+        if (reply === false)
+            throw new TransmissionException(`All (${this.#bindings.length}) bindings rejected.`);
+        return reply;
+    }
+}
+//# sourceMappingURL=transmission.js.map

package/transpiled/transmission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transmission.js","sourceRoot":"","sources":["../source/transmission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAIvD,MAAM,OAAO,YAAa,SAAQ,SAAS;IAChC,SAAS,CAAY;IAE9B,YAAmB,QAAoB;QACrC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAA;QACzB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACxB,CAAC;IAEM,KAAK,CAAC,OAAO,CAAC,OAAgB,EAAE,KAAa;QAClD,IAAI,KAAK,GAAQ,KAAK,CAAA;QACtB,IAAI,CAAC,GAAG,CAAC,CAAA;QAET,OAAO,KAAK,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;YACpD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;YAEjC,CAAC,EAAE,CAAA;YAEH,IAAI,OAAO,EAAE,IAAI,KAAK,IAAI,EAAE,CAAC;gBAC3B,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;oBAAE,SAAQ;gBAExC,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBAC3B,KAAK,GAAG,IAAI,CAAA;YACd,CAAC;;gBAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACtD,CAAC;QAED,IAAI,KAAK,KAAK,KAAK;YACjB,MAAM,IAAI,qBAAqB,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,MAAM,sBAAsB,CAAC,CAAA;QAEtF,OAAO,KAAK,CAAA;IACd,CAAC;CACF"}

package/transpiled/types/atomicity.d.ts

@@ -0,0 +1,56 @@
+import type { Connector } from '../connector.js';
+/** Which of the group this replica is, and how many of them there are. */
+export interface Assignment {
+    i: number;
+    n: number;
+}
+/**
+ * What one group of replicas decides together, in one place. The decisions here are the ones
+ * processes cannot arrange by talking to each other: they need a single arbiter and a step
+ * indivisible from its point of view.
+ */
+export interface Atom extends Connector {
+    /**
+     * An exclusive claim on slots of `0..total`: while this replica holds one, no other
+     * replica of the group does. Answered from memory, so it costs nothing to ask.
+     *
+     * `null` while this replica owns nothing — after a restart, during a rollout, or while
+     * coordination is unreachable. Whoever asks must be able to stand down: acting on a claim
+     * that cannot be supported is a different guarantee, not a degraded one.
+     */
+    slots(total: number): number[] | null;
+    /**
+     * Calls `listener` with the assignment this replica holds, and again whenever it changes —
+     * one arrived, was lost, or the group resized. Answers with what removes the listener
+     * again.
+     *
+     * A change and not a heartbeat: a group that stays as it is never calls back. It is called
+     * once as it is added, with the claim as it stands.
+     */
+    onassigned(listener: (assignment: Assignment | null) => void): () => void;
+    /**
+     * Debt the group has run up under each key, in milliseconds. Every call adds its own deltas
+     * and reads back where the group stands, so a replica reports what it alone has spent and
+     * still decides on what all of them have.
+     *
+     * Rejects where there is nothing to arbitrate through.
+     */
+    meter(keys: string[], deltas: number[]): Promise<number[]>;
+    /**
+     * Runs `routine` holding `keys`, and while it holds them no other replica of the group
+     * does. Waits for as long as it takes to acquire them.
+     *
+     * The lease is extended for as long as the routine runs. An extension that fails aborts the
+     * signal the routine is given, which is the only way it learns it no longer holds what it
+     * is working under.
+     *
+     * Rejects where there is nothing to arbitrate through.
+     */
+    lock<T>(keys: string | string[], routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>;
+}
+export interface Factory {
+    /** @param group what the replicas deciding together have in common */
+    atom(group: string, options?: {
+        interval?: number;
+    }): Atom;
+}

package/transpiled/types/atomicity.js

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

package/transpiled/types/atomicity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomicity.js","sourceRoot":"","sources":["../../source/types/atomicity.ts"],"names":[],"mappings":""}

package/transpiled/types/bindings.d.ts

@@ -0,0 +1,77 @@
+import type { Readable } from 'node:stream';
+import type { Connector } from '../connector.js';
+import type { Locator } from '../locator.js';
+import type { Component } from '../component.js';
+import type { Receiver } from './receiver.js';
+import type { Message } from './message.js';
+import type { Reply, Request } from './request.js';
+/** What a binding module exports beside its factory. */
+export interface Properties {
+    /** delivers asynchronously; an event's binding must */
+    async?: boolean;
+    /** in-process: its producers are connected first and torn down last */
+    local?: boolean;
+}
+/**
+ * How a call is carried, as its caller settled it. None of it is part of the request, and none of
+ * it is sent as part of one.
+ */
+export interface Terms {
+    /** the process an addressed call goes to */
+    instance?: string;
+    /** milliseconds the caller waits, where it waits for a set time */
+    timeout?: number;
+    /** aborts when the caller stops waiting */
+    signal?: AbortSignal;
+}
+export interface Consumer extends Connector {
+    /**
+     * `false` says this binding does not carry the endpoint, and the transmission tries the
+     * next one. A `Readable` is a streamed reply.
+     */
+    request(request: Request, terms?: Terms): Promise<Reply | Readable | false>;
+    /**
+     * Absent where the binding cannot enqueue — a transmission skips a binding that offers
+     * no `task` rather than failing over it.
+     */
+    task?(request: Request): Promise<void>;
+}
+export interface Emitter extends Connector {
+    emit(message: Message): Promise<void>;
+}
+export interface Broadcast<L extends string = string> extends Connector {
+    transmit<T>(label: L, payload: T): Promise<void>;
+    receive<T>(label: L, callback: (payload: T) => void | Promise<void>): Promise<void>;
+}
+export interface Factory {
+    /** `stateful` are the endpoints among `endpoints` that take addressed calls only */
+    producer(locator: Locator, endpoints: string[], component: Component, stateful?: string[]): Connector;
+    consumer(locator: Locator, endpoint: string): Consumer;
+    /** only the binding an event declares is asked for one */
+    emitter?(locator: Locator, label: string): Emitter;
+    /** `group` is absent for an exclusive subscription */
+    receiver?(locator: Locator, label: string, group: string | undefined, receiver: Receiver): Connector;
+    broadcast?(name: string, group?: string): Broadcast;
+    /**
+     * A channel is a name the caller picks, from which the binding derives whatever its
+     * transport needs, and `uris` are the brokers to carry it over — so a second broker set
+     * costs the binding no configuration and no variable of its own.
+     */
+    outbound?(channel: string, uris: string[]): Outbound;
+    /** what arrives on `channel` under `label` */
+    inbound?(channel: string, uris: string[], label: string, sink: Inbound): Connector;
+}
+/**
+ * Publishes to a channel, addressed by label. It forwards messages and nothing else: what
+ * `send` is handed is what is published, with no envelope, no field and no header of the
+ * binding's own, and none stripped — because a message shape is often somebody else's
+ * contract, and an extension shipping changes into another system must be able to send
+ * exactly what that system accepts.
+ */
+export interface Outbound extends Connector {
+    send(label: string, message: object): Promise<void>;
+}
+/** What a binding hands a message to. */
+export interface Inbound {
+    accept(message: object): Promise<void>;
+}

package/transpiled/types/bindings.js

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

package/transpiled/types/bindings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../../source/types/bindings.ts"],"names":[],"mappings":""}

package/transpiled/types/bridges.d.ts

@@ -0,0 +1,38 @@
+import type { Readable } from 'node:stream';
+import type { Connector } from '../connector.js';
+import type { Context } from '../context.js';
+import type { Event as StateEvent } from './state.js';
+import type { Reply, Request } from './request.js';
+/**
+ * What runs one endpoint. `mount` and `unmount` are the component author's, called by the
+ * bridge as it opens and closes; core only ever asks for `execute`.
+ */
+export interface Algorithm extends Connector {
+    execute(input: any, scope?: object | object[]): Promise<Reply | Readable>;
+}
+export interface Event extends Connector {
+    condition(event: StateEvent): Promise<boolean>;
+    payload(event: StateEvent): Promise<object>;
+}
+export interface Receiver extends Connector {
+    condition(payload: object): Promise<boolean>;
+    /** the trailing arguments are what the receiver declaration named */
+    request(payload: object, ...args: unknown[]): Promise<Request>;
+}
+/** Runs on every change to an entity's state, before the contract is applied. */
+export interface Guard {
+    fit(state: object, origin: object | null): boolean;
+}
+/** Connectors whose lifecycle moments are the component's. */
+export interface RunCommands {
+    preflight?: Connector;
+    settle?: Connector;
+    dispose?: Connector;
+}
+export interface Factory {
+    algorithm(path: string, endpoint: string, context: Context): Algorithm | Promise<Algorithm>;
+    event?(path: string, label: string, context: Context): Event | Promise<Event>;
+    receiver?(path: string, label: string): Receiver | Promise<Receiver>;
+    guard?(path: string, name: string, context: Context): Guard | Promise<Guard>;
+    rc?(path: string, context: Context): Promise<RunCommands | undefined>;
+}

package/transpiled/types/bridges.js

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

package/transpiled/types/bridges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridges.js","sourceRoot":"","sources":["../../source/types/bridges.ts"],"names":[],"mappings":""}

package/transpiled/types/extensions.d.ts

@@ -0,0 +1,92 @@
+import type { Connector } from '../connector.js';
+import type { Locator } from '../locator.js';
+import type { Component } from '../component.js';
+import type { Remote } from '../remote.js';
+import type { Receiver } from './receiver.js';
+import type { Context } from '../context.js';
+import type { Storage } from './storages.js';
+import type { Broadcast, Emitter, Inbound, Outbound } from './bindings.js';
+import type { Atom } from './atomicity.js';
+import type { Source } from './request.js';
+import type { Destination } from './outbox.js';
+/**
+ * What the process hosting an extension provides to it: the counterpart of a component's
+ * context. What is returned is a connector the extension depends on.
+ */
+export interface Host {
+    /** a component of the context, by locator */
+    remote(locator: Locator, source?: Source): Promise<Remote>;
+    /** a channel of the messaging binding */
+    broadcast<L extends string = string>(channel: string, group?: string): Promise<Broadcast<L>>;
+    /** components to run inside the extension's own process */
+    composition(paths: string[]): Promise<Connector>;
+    /** a consumer of an event of the context, `namespace.component.event` */
+    receive(label: string, receiver: Receiver): Promise<Connector>;
+    /** what the replicas of one group decide together */
+    atom(group: string): Atom;
+    /** where this deployment publishes a channel, over the brokers named */
+    outbound(binding: string, channel: string, uris: string[]): Promise<Outbound>;
+    /** what arrives on a channel under one label */
+    inbound(binding: string, channel: string, uris: string[], label: string, sink: Inbound): Promise<Connector>;
+}
+/**
+ * `Manifest` is a type parameter rather than an import: `@toa.io/norm` depends on core, so
+ * core cannot name its types.
+ */
+export interface Factory<Manifest = unknown> {
+    tenant?(locator: Locator, declaration: any, manifest: Manifest): Connector | Promise<Connector>;
+    aspect?(locator: Locator, declaration: any): Aspect | Aspect[];
+    /**
+     * Where a committed state change of this component goes, beside its own events. Read before
+     * the storage is made, because one of these is what gives a component an outbox when it
+     * declares no event at all.
+     */
+    destination?(locator: Locator, declaration: any, manifest: Manifest): Destination | Promise<Destination> | undefined;
+    /** what the extension runs as a process of its own; `null` where it is off here */
+    service?(): Connector | null | Promise<Connector | null>;
+    /**
+     * What the extension keeps in every process, whatever that process runs — the counterpart of
+     * `tenant` for a process rather than a component. Asked of every extension the process has
+     * loaded, and the predefined ones are loaded by every process for this.
+     *
+     * `null` where the extension keeps nothing here.
+     */
+    resident?(host: Host): Resident | null | Promise<Resident | null>;
+    component?(component: Component): Component;
+    context?(context: Context): Context;
+    manage?(composition: Connector): Connector;
+    storage?(storage: Storage, locator: Locator): Storage;
+    emitter?(emitter: Emitter, label: string, locator: Locator): Emitter;
+    receiver?(receiver: Receiver, locator: Locator): Receiver;
+}
+/**
+ * A connector that lives as long as the process, whatever the process runs.
+ *
+ * It connects before what the process was built with and goes after it, which is what makes it
+ * the place for something that answers for the process rather than for anything in it — the
+ * readiness probe is the one this was written for.
+ */
+export interface Resident extends Connector {
+    /** Everything the process was built with has connected. */
+    complete?: () => Promise<void>;
+}
+export interface Aspect extends Connector {
+    /** the key it takes on the context; a duplicate is a boot error */
+    readonly name: string;
+    invoke(...args: any[]): any;
+}
+/**
+ * What an extension puts on a component's context, as the extension states it. How it is
+ * presented there is the bridge's — a bash bridge has no context to put anything on — and
+ * what is declared here is the key and what it holds.
+ */
+export interface Contribution {
+    /** the key on the context */
+    name: string;
+    /** what the key holds, as TypeScript */
+    type?: string;
+    /** what `type` names, by the module it comes from */
+    imports?: Record<string, string[]>;
+    /** a JSON Schema to read the type from instead, where a component states one */
+    schema?: object;
+}

package/transpiled/types/extensions.js

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

package/transpiled/types/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../source/types/extensions.ts"],"names":[],"mappings":""}

package/transpiled/types/inbox.d.ts

@@ -0,0 +1,22 @@
+/**
+ * What a call was, kept so that the same call arriving again is refused rather than made twice.
+ *
+ * Everything about it is core's, as the outbox row is: core builds it and hands it to the write,
+ * and the storage commits it in the transaction the entity is committed in. Written only for a
+ * call that changed something — an operation that refused, or that raised, leaves nothing, and a
+ * call that arrives again after one of those is made again and refuses again.
+ */
+export interface Call {
+    /** the identity of the request, which is the key it is refused on */
+    id: string;
+    /** what the call answered, so that a duplicate of it is answered rather than refused */
+    reply: object;
+}
+/**
+ * The read side of an inbox. What writes a record is the storage's own: it happens inside the
+ * transaction the storage opened, which core never reaches into.
+ */
+export interface Inbox {
+    /** what the call under this identity answered, or `null` where it was never made */
+    recall(id: string): Promise<object | null>;
+}

package/transpiled/types/inbox.js

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

package/transpiled/types/inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.js","sourceRoot":"","sources":["../../source/types/inbox.ts"],"names":[],"mappings":""}

package/transpiled/types/index.d.ts

@@ -0,0 +1,14 @@
+export * as atomicity from './atomicity.js';
+export * as bindings from './bindings.js';
+export * as bridges from './bridges.js';
+export * as extensions from './extensions.js';
+export * as operations from './operations.js';
+export * as inbox from './inbox.js';
+export * as outbox from './outbox.js';
+export * as storages from './storages.js';
+export type { Contribution } from './extensions.js';
+export type { Event } from './state.js';
+export type { Message } from './message.js';
+export type { Receiver } from './receiver.js';
+export type { Call, Guard, Observation, Transition } from './operations.js';
+export type { Envelope, Maybe, Options, Query, Reply, RemoteError, Request, Source } from './request.js';

package/transpiled/types/index.js

@@ -0,0 +1,9 @@
+export * as atomicity from './atomicity.js';
+export * as bindings from './bindings.js';
+export * as bridges from './bridges.js';
+export * as extensions from './extensions.js';
+export * as operations from './operations.js';
+export * as inbox from './inbox.js';
+export * as outbox from './outbox.js';
+export * as storages from './storages.js';
+//# sourceMappingURL=index.js.map

package/transpiled/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA;AAC3C,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA;AACzC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;AAC7C,OAAO,KAAK,KAAK,MAAM,YAAY,CAAA;AACnC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAA"}

package/transpiled/types/message.d.ts

@@ -0,0 +1,16 @@
+export interface Message<T = any> {
+    payload: T;
+    /**
+     * What this message is, so that a receiver's state change happens once however many times it
+     * arrives. Derived from the outbox row it was published from, which is committed once, so the
+     * immediate path, the pump and a redelivery all carry the one identity.
+     */
+    id?: string;
+    /** W3C traceparent */
+    telemetry?: string;
+    /**
+     * The hops that led to the state change this is about, so a receiver of it continues the
+     * chain rather than starting one. See `core/source/trail.ts`.
+     */
+    trail?: string[];
+}

package/transpiled/types/message.js

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

package/transpiled/types/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../source/types/message.ts"],"names":[],"mappings":""}

package/transpiled/types/operations.d.ts

@@ -0,0 +1,15 @@
+import type { Request } from './request.js';
+export type type = 'transition' | 'observation' | 'assignment' | 'computation' | 'effect' | 'unmanaged';
+export type scope = 'object' | 'objects' | 'changeset' | 'stream' | 'none';
+/**
+ * How an endpoint is called. What it resolves to is what the operation declares — `toa types`
+ * writes that per operation, and these are what a hand-written context says instead.
+ */
+export type Call<Output = any, Input = any> = (request: Request<Input>) => Promise<Output>;
+export type Observation<Output = any, Input = never, Entity = unknown> = (request: Request<Input, Entity>) => Promise<Output extends unknown[] ? Output : Output | null>;
+export type Transition<Output = any, Input = never, Entity = unknown> = (request: Request<Input, Entity>) => Promise<Output | null>;
+/**
+ * Runs on every change to an entity's state, before the contract is applied. `false` refuses
+ * the change as `EntityGuard`.
+ */
+export type Guard<T, C = unknown> = (state: T, origin: T | null, context: C) => boolean;

package/transpiled/types/operations.js

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

package/transpiled/types/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../source/types/operations.ts"],"names":[],"mappings":""}