@toa.io/core 1.0.0-alpha.32 → 1.0.0-alpha.320

package/transpiled/state.js

@@ -0,0 +1,131 @@
+import { EntitySet } from './entities/set.js';
+import { StatePreconditionException, StateNotFoundException } from './exceptions.js';
+/**
+ * What an operation acquires and commits. One method per scope a manifest may declare, which
+ * is how an operation reaches the one it was declared with.
+ */
+export class State {
+    storage;
+    #entities;
+    #outbox;
+    /** whether an entity exists by virtue of the identity it is looked up by */
+    #associated;
+    // eslint-disable-next-line max-params
+    constructor(storage, entities, outbox, associated) {
+        this.storage = storage;
+        this.#entities = entities;
+        this.#outbox = outbox;
+        this.#associated = associated === true;
+    }
+    init(id) {
+        return this.#entities.init(id);
+    }
+    fit(values) {
+        this.#entities.fit(values);
+    }
+    /** scope `entry` */
+    async entry(query, mutable = true) {
+        const record = await this.storage.get(query);
+        if (record !== null)
+            return this.#entities.object(record, mutable);
+        // an associated entity is whatever the identity it is looked up by names, so a miss on
+        // that identity alone is a blank rather than an absence
+        if (this.#associated &&
+            query.id !== undefined &&
+            query.criteria === undefined &&
+            query.version === undefined)
+            return this.init(query.id);
+        if (query.version !== undefined)
+            throw new StatePreconditionException();
+        return null;
+    }
+    /** scope `entries` */
+    async entries(query, mutable = true) {
+        const recordset = await this.storage.find(query);
+        const ids = query.ids;
+        const missing = this.#associated && ids !== undefined && recordset.length < ids.length;
+        const init = missing
+            ? ids.filter((id) => !recordset.some((record) => record.id === id))
+            : undefined;
+        return this.#entities.objects(recordset, init, mutable);
+    }
+    /** scope `stream` */
+    async stream(query) {
+        return this.storage.stream(query);
+    }
+    /** scope `changeset` */
+    changeset(query) {
+        return this.#entities.changeset(query);
+    }
+    /** scope `none`: an operation that acquires nothing still asks for its scope */
+    none() {
+        return null;
+    }
+    /** get-or-create, in one indivisible step */
+    /** what the call under this identity answered, or `null` where it was never made */
+    async recall(id) {
+        return (await this.storage.inbox?.recall(id)) ?? null;
+    }
+    // eslint-disable-next-line max-params
+    async ensure(query, properties, input, call) {
+        const object = this.#entities.init();
+        const blank = object.get();
+        Object.assign(blank, properties);
+        object.set(blank);
+        const row = this.#outbox?.row(object.event(input));
+        const record = await this.storage.ensure(query, properties, object.get(), row, call);
+        // whatever came back under another id was already there, and an effect never commits it
+        if (record.id !== blank.id)
+            return this.#entities.object(record, NOT_MUTABLE);
+        await this.#publish(row);
+        return object;
+    }
+    async commit(state, input, call) {
+        if (state instanceof EntitySet)
+            return this.massCommit(state, input);
+        // the row is built before the write so that the storage can commit it in the same
+        // transaction, closing the window this used to have
+        const row = this.#outbox?.row(state.event(input));
+        const ok = await this.storage.store(state.get(), row, call);
+        if (ok)
+            await this.#publish(row);
+        return ok;
+    }
+    async massCommit(state, input) {
+        const outbox = this.#outbox;
+        const rows = outbox === undefined
+            ? undefined
+            : state.events(input).map((event) => outbox.row(event));
+        const ok = await this.storage.massStore(state.get(), rows);
+        if (ok && rows !== undefined)
+            await Promise.all(rows.map(async (row) => this.#publish(row)));
+        return ok;
+    }
+    async apply(state, input, call) {
+        // an assignment's images are the write's own, so the storage fills them in
+        const row = this.#outbox?.row({ input });
+        const result = await this.storage.upsert(state.query, state.export(), row, call);
+        if (result === null)
+            throw state.query.version === undefined
+                ? new StateNotFoundException()
+                : new StatePreconditionException();
+        if (row !== undefined) {
+            // a storage that does not know how leaves the event with what it was given
+            row.event.state ??= result;
+            row.event.origin ??= null;
+            await this.#publish(row);
+        }
+        return result;
+    }
+    /**
+     * Without a durable outbox this is the emission itself, and the operation waits for it;
+     * with one the row is already committed and this returns at once.
+     */
+    async #publish(row) {
+        if (row !== undefined)
+            await this.#outbox?.publish(row);
+    }
+}
+/** an effect never commits what `ensure` hands it, see `Effect` */
+const NOT_MUTABLE = false;
+//# sourceMappingURL=state.js.map

package/transpiled/state.js.map

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

package/transpiled/trail.d.ts

@@ -0,0 +1,78 @@
+/** What one invocation carries for the calls it makes. */
+export interface Invocation {
+    /** the hops it came by, oldest first, ending with its own */
+    hops: string[];
+    /**
+     * The identity of the request being served. Absent where the caller stamped none, which is a
+     * caller from before this existed; a call made under one mints its own identity instead.
+     */
+    id?: string;
+    /**
+     * Whether what it may reach is a safe operation and nothing else. Carried onto every call it
+     * makes, and never dropped: the request that arrived said so, and so does every one below it.
+     */
+    readonly?: boolean;
+    /**
+     * How many calls this invocation has already made to each endpoint. Two calls to one endpoint
+     * are two calls, and their identities have to say so — without this an operation looping over
+     * five items would make one identity five times and have four of them refused.
+     *
+     * Made where the first call is made: most operations make none.
+     */
+    calls?: Map<string, number>;
+}
+/**
+ * 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 invocation running now, where there is one. */
+export declare function current(): Invocation | undefined;
+/** Runs `task` as the invocation the chain now ends with. */
+export declare function follow<T>(invocation: Invocation, task: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function ordinal(invocation: Invocation, endpoint: string): number;
+/**
+ * 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[];

package/transpiled/trail.js

@@ -0,0 +1,112 @@
+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 and the safety of
+ * what may be reached are put in scope; two readers, `Call.invoke`, which puts them 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 calls = (invocation.calls ??= new Map());
+    const made = calls.get(endpoint) ?? 0;
+    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":"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"}

package/transpiled/transition.d.ts

@@ -0,0 +1,14 @@
+import { Operation } from './operation.ts';
+import type { Contracts, Definition, Store } from './operation.ts';
+import type { Cascade } from './cascade.ts';
+import type { State } from './state.ts';
+import type { Query as Translator } from './query.ts';
+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.ts';
+import type { Consumer, Terms } from './types/bindings.ts';
+import type { Request } from './types/request.ts';
+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,58 @@
+import type { Connector } from '../connector.ts';
+/** 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 & {
+        error: Error;
+    }, 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,82 @@
+import type { Readable } from 'node:stream';
+import type { Connector } from '../connector.ts';
+import type { Locator } from '../locator.ts';
+import type { Component } from '../component.ts';
+import type { Receiver } from './receiver.ts';
+import type { Message } from './message.ts';
+import type { Reply, Request } from './request.ts';
+/** 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;
+    /** carries a call whose input holds a stream; an endpoint that takes one is offered to no other */
+    streams?: 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 of an addressed call waits */
+    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, and
+     * `streamed` those that take one of their input properties as a stream.
+     */
+    producer(locator: Locator, endpoints: string[], component: Component, stateful?: string[], streamed?: 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,41 @@
+import type { Readable } from 'node:stream';
+import type { Connector } from '../connector.ts';
+import type { Context } from '../context.ts';
+import type { Event as StateEvent } from './state.ts';
+import type { Reply, Request } from './request.ts';
+/**
+ * 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;
+    ready?: Connector;
+    dispose?: Connector;
+    /** what the component pauses while the process is halted, and takes again after */
+    quiescence?: 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>;
+}