@nuanu-ai/agentify 0.2.4

package/dist/verify.js

@@ -0,0 +1,232 @@
+/**
+ * `agentify verify` — the check a merchant runs on themselves before they
+ * ask us to look.
+ *
+ * The portal describes two checks. Is the card enough for an agent to assemble
+ * a correct purchase, and does the merchant's handler hold idempotency — that
+ * is, does a second delivery appear when one and the same order arrives twice.
+ *
+ * The first is here in full. The second is not, and this file refuses to
+ * pretend otherwise: it names what is missing, in the same words anyone can
+ * check against the route table, and answers with a code of its own that says
+ * "did not run" rather than "passed" or "failed". The reasons are written out
+ * in `IDEMPOTENCY_IS_NOT_BUILDABLE` below and are worth reading before anybody
+ * tries to add the check, because the gap is not in this package.
+ *
+ * Which cards are checked is asked for rather than discovered. Nothing in this
+ * package, in the contract or in any decision says where a merchant keeps
+ * their cards, and a command that went looking would be inventing a
+ * convention — a file name, a directory, a manifest — that nobody agreed to
+ * and that every merchant would then have to work around.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { checkCard } from "./check-card.js";
+import { describeProblems } from "./schema.js";
+/**
+ * What the command answers with.
+ *
+ * Four and not two, because a build that branches on this needs to tell a
+ * check that failed from a check that never ran. Collapsing the two would make
+ * a missing check look like a passing one on the day somebody decides that
+ * anything non-zero is a failure and anything else is fine.
+ */
+export const VERIFY_EXIT = Object.freeze({
+    /** Every check ran and every check passed. */
+    PASSED: 0,
+    /** A check ran and found something. */
+    PROBLEMS: 1,
+    /** The command was called with something it cannot work from. */
+    USAGE: 2,
+    /** A check could not be run at all, so nothing is claimed about it. */
+    COULD_NOT_RUN: 3,
+});
+/**
+ * Why the idempotency run is not in this version, stated so it can be checked
+ * rather than taken on trust.
+ *
+ * The run the portal describes needs a test order to exist: the same order
+ * delivered twice through the live subscription, marked `test`, against a card
+ * that is published but not yet in any catalog. Four things it needs are
+ * absent, and none of them is ours to add here.
+ *
+ * There is no route that asks for one. The only way an order comes into being
+ * on this surface is `purchase_item`, and that is the payment exchange itself
+ * — an agent buying — not a request a merchant can make about their own card.
+ *
+ * `PurchaseRequestSchema` is closed and carries the purchase parameters and
+ * nothing else, so there is nowhere in a purchase to say "this one is a test".
+ *
+ * Nothing says how an order's `test` flag comes to be true. The order carries
+ * it, the handler is told to branch on it, and no document in the contract
+ * describes who sets it or from what.
+ *
+ * And a card carries no marker for "published, not yet in catalogs", which is
+ * the state the portal says these orders are raised against.
+ *
+ * What is missing is not an environment to run it in. There are two sites, the
+ * test one settles against test funds, and a key says which it belongs to
+ * (ADR-0020) — so a merchant already has somewhere to try their integration
+ * without spending anything. What is missing is a way to make an order happen
+ * there: no route raises one, and the four absences above are the whole of what
+ * would have to exist first. Inventing a route or a field here would be
+ * designing that, and this is not the place where it is designed.
+ */
+export const IDEMPOTENCY_IS_NOT_BUILDABLE = [
+    "The idempotency run needs a test order, and nothing on the surface can ask for one:",
+    "  - no route raises an order for a merchant's own card; the only way an order",
+    "    comes into being is purchase_item, which is an agent's payment exchange",
+    "  - purchase_item's body carries the purchase parameters and nothing else, so",
+    "    there is nowhere in it to say that a purchase is a test",
+    "  - nothing in the contract says how an order's test flag comes to be true",
+    "  - a card carries no marker for published-but-not-yet-in-catalogs, which is",
+    "    the state the documentation raises these orders against",
+    "The test site is not what is missing: it exists, it settles against test",
+    "funds, and a csk_test_ key belongs to it. What is missing is a way to make",
+    "an order happen there, and inventing a route or a field here would be",
+    "designing one.",
+].join("\n");
+/** The code a finding carries when the file held no card to check at all. */
+export const NOT_JSON = "not_json";
+const nameOf = (file, card) => {
+    const key = typeof card === "object" && card !== null && "merchant_item_id" in card
+        ? card.merchant_item_id
+        : undefined;
+    return typeof key === "string" && key !== "" ? `${file} (${key})` : file;
+};
+const USAGE = [
+    "Usage: agentify verify <card.json> [more-cards.json ...]",
+    "",
+    "Checks each card against the published contract before it is published.",
+    "",
+    "Answers: 1 a check found something, 2 called with something it cannot work",
+    "from, 3 a check could not be run. Zero, which means every check passed, is",
+    "not reachable today: the idempotency run cannot be built, and this command",
+    "will not report success for a check that never happened.",
+].join("\n");
+/**
+ * Why the bare command the documentation shows does not run.
+ *
+ * `agentify verify` with nothing after it would check the cards the merchant
+ * has already published. The binding reason it cannot is the plainest one:
+ * this command takes no key and no address, builds no client and asks the
+ * gateway nothing, so it has no way to see anything that was published.
+ *
+ * The call it would have needed does exist, and saying so is the honest half
+ * of the answer: `list_merchant_cards` returns published cards whole, each of
+ * them the card its author wrote rather than an agent's projection of it. What
+ * that route promises is worth repeating exactly, because every part of it is
+ * easy to overstate. Whose cards it returns is settled: the merchant whose key
+ * the call was made with, and nobody else. A card reaches that list by being accepted at
+ * `publish_card`, which parses the same `CardSchema` this package parses, so
+ * the cards on it passed this check on the day they went out — which is not
+ * the same as passing it now, because the schema can move, nothing parses a
+ * stored card again on the way back out, and a command that builds no client
+ * can never learn which version of the contract the gateway is speaking. And
+ * publishing is more than this check: it can refuse a card for reasons no
+ * schema carries, which `checkCard` says in its own words.
+ *
+ * Taking no key is a choice and not a hole, which is worth saying here because
+ * the first line of the message reads like a limitation somebody would set out
+ * to remove. A check that read published cards over that route would always
+ * pass — they got onto it by passing this very schema — and a green that cannot
+ * fail teaches a merchant to stop reading it. What would earn a keyed mode is a
+ * dry run of publishing, which can refuse for reasons no schema carries; there
+ * is no such route (`docs/research/00-open-questions.md`).
+ *
+ * So this is a stop and not a scolding, and it is answered with the code that
+ * means "did not run". The way through it is to name the card files, which are
+ * the copy the merchant can still change — the file is what the next publish
+ * carries, whether the card is new or an edit to one already out.
+ */
+const NOTHING_TO_CHECK = [
+    "agentify verify was given no card files, and it does not go looking for them:",
+    "  - this command takes no key and no address and builds no client, so it",
+    "    cannot ask us anything about what you have published",
+    "  - the call that would answer such a question does exist, list_merchant_cards,",
+    "    and it returns published cards whole — but a card reaches that list by",
+    "    being accepted at publish, which runs this same check, so what comes back",
+    "    is cards that passed this check on the day they went out",
+    "  - neither this command nor the contract says where you keep the cards you",
+    "    publish from, and looking for a file name or a directory would invent a",
+    "    convention nobody agreed to",
+    "Name the card files instead. The file is what your next publish carries,",
+    "whether the card is new or an edit to one already out.",
+].join("\n");
+const checkFile = (path) => {
+    const name = basename(path);
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (cause) {
+        throw new Error(`${path} could not be read: ${String(cause)}`);
+    }
+    let card;
+    try {
+        card = JSON.parse(text);
+    }
+    catch (cause) {
+        return {
+            path,
+            name,
+            problems: [
+                {
+                    path: [],
+                    code: NOT_JSON,
+                    message: `${name} is not JSON, so there is no card in it to check: ${String(cause)}`,
+                },
+            ],
+        };
+    }
+    return { path, name: nameOf(name, card), problems: checkCard(card).problems };
+};
+export const runVerify = async (argv, say) => {
+    const [command, ...files] = argv;
+    if (command !== "verify") {
+        say(command === undefined ? USAGE : `agentify does not know "${command}".\n\n${USAGE}`);
+        return VERIFY_EXIT.USAGE;
+    }
+    if (files.length === 0) {
+        say(NOTHING_TO_CHECK);
+        say("");
+        say(USAGE);
+        return VERIFY_EXIT.COULD_NOT_RUN;
+    }
+    const checked = [];
+    for (const file of files) {
+        try {
+            checked.push(checkFile(file));
+        }
+        catch (cause) {
+            say(String(cause instanceof Error ? cause.message : cause));
+            return VERIFY_EXIT.USAGE;
+        }
+    }
+    say("Card completeness");
+    for (const card of checked) {
+        if (card.problems.length === 0) {
+            say(`  ${card.name}: complete as far as the contract can tell`);
+            continue;
+        }
+        say(`  ${card.name}: ${card.problems.length} finding${card.problems.length === 1 ? "" : "s"}`);
+        say(describeProblems(card.problems));
+    }
+    const faulted = checked.filter((card) => card.problems.length > 0);
+    if (faulted.length > 0) {
+        // The truncation, said out loud. A card is checked in two stages and the
+        // second — the rules that compare one field against another — is only
+        // reached when the first passes, so a short list is not a promise that
+        // one round of fixes is enough.
+        say("  Fix these and run again: a card whose shape is wrong is not checked against the rules that compare one field with another, so there may be more behind them.");
+    }
+    say("");
+    say("Idempotency");
+    say("  could not be run.");
+    say(IDEMPOTENCY_IS_NOT_BUILDABLE);
+    say("");
+    say(faulted.length > 0
+        ? "Verdict: the cards have findings, and the idempotency run did not happen."
+        : "Verdict: the cards are complete. Nothing is claimed about idempotency — that check did not run.");
+    return faulted.length > 0 ? VERIFY_EXIT.PROBLEMS : VERIFY_EXIT.COULD_NOT_RUN;
+};

package/dist/worker.d.ts

@@ -0,0 +1,347 @@
+/**
+ * The one loop that carries everything the merchant's process receives.
+ *
+ * The transport is HTTP long polling against the gateway (ADR-0004): the
+ * worker asks for the next batch, the gateway holds the request until
+ * something arrives or its own window closes, and the answer is a batch of
+ * envelopes or an empty one. An empty batch is the ordinary answer to a quiet
+ * window and not a failure. There is one loop and not three, because the
+ * stream carries three kinds on one connection and the portal promises the
+ * merchant one subscription.
+ *
+ * How each kind is answered is the part worth reading before changing
+ * anything, because the three are answered in three different places and none
+ * of them is an acknowledgement of the envelope itself.
+ *
+ * An order is given to the merchant's handler, and whatever the handler
+ * returns is posted to the order's answer route — in every mode, without the
+ * merchant asking. In the synchronous mode that return is the whole of the
+ * merchant's answer; in the asynchronous one it is usually an acceptance, and
+ * the goods follow later through the explicit `deliver` call, which is the
+ * merchant's to make and not this loop's.
+ *
+ * A price question is given to the price handler and the answer goes to the
+ * quote route against the `price_id` the question carried.
+ *
+ * An event is handed over and nothing is sent back. An event notifies, it does
+ * not ask for work.
+ *
+ * What happens when a handler throws is the design decision the rest follows
+ * from: nothing is sent. An order nobody answered comes back on its own,
+ * because the gateway's own order machine is watching for that answer and
+ * decides there should be another attempt — that is the machine's meaning of
+ * "not delivered". A retry written on this side would be a second machine with
+ * a second opinion about how many times a merchant's handler may run, and the
+ * two would disagree the first time one of them restarted. The same holds for a
+ * handler that answers with something the contract refuses, and for an envelope
+ * that arrives with no handler registered for its kind: the merchant is told
+ * through the problem channel, and an order or a price question comes back on
+ * its own.
+ *
+ * An event is the exception and it is worth knowing about. It carries no
+ * acknowledgement, so nothing here can ask for one again and nothing on the
+ * other side is waiting for a reply to notice that it went unanswered. The
+ * contract makes no promise that one is ever sent a second time, and whether a
+ * particular gateway sends one anyway is that gateway's business. A handler
+ * that throws on an event has lost what it carried.
+ *
+ * The transport failures are the one thing this loop does retry, because there
+ * is nothing else to do with them: a poll that did not reach the gateway
+ * delivered no envelope to anybody. That retry is the backoff in
+ * `backoff.ts` and nothing more.
+ */
+import { type HandlerAnswer, type Order, type OrderEvent, type QuoteRequest, type QuoteResponse } from "@nuanu-ai/agentify-contracts";
+import { type Gateway } from "./transport.js";
+/**
+ * What this loop calls with one paid order off the stream.
+ *
+ * It is not what a merchant writes. The order a merchant's handler receives
+ * carries the calls that close it, and putting those on it is `client.ts`'s
+ * job: this loop reads the envelope and knows nothing about a gateway address
+ * or an API key beyond the one it polls with. So the client registers a
+ * function of this shape which wraps the merchant's own.
+ */
+export type OrderDispatch = (order: Order) => HandlerAnswer | Promise<HandlerAnswer>;
+/** The same, for "how much is this and is it there". */
+export type QuoteDispatch = (question: QuoteRequest) => QuoteResponse | Promise<QuoteResponse>;
+/**
+ * How this delivery of a message is named, for the one kind that needs it.
+ *
+ * `id` names this message and `sent_at` names when it went out. What the pair is
+ * not is a dependable way to recognise a repeat: a gateway sending an order
+ * again builds a fresh envelope around it under a fresh `id`, and what holds
+ * still across such a repeat is the order's own identifier in the payload.
+ */
+export interface Delivered {
+    readonly id: string;
+    readonly sent_at: string;
+}
+/**
+ * What the merchant's code does with something that happened to an order.
+ *
+ * The second argument is this delivery's own name, and it is the reason this
+ * signature is not just the event. An order is answered against its own
+ * identifier and a price question against its `price_id`; an event is answered
+ * against nothing at all, so this pair is the only thing naming the message
+ * itself rather than the order it is about, which is what a log line or a
+ * question to us afterwards needs.
+ *
+ * It is not there to be deduplicated against. Nothing acknowledges an event, so
+ * nothing asks for one again, and the contract makes no promise that one is ever
+ * sent twice — which means the risk an event handler is written against is a
+ * message that never arrives rather than one that arrives twice.
+ */
+export type EventHandler = (event: OrderEvent, delivered: Delivered) => void | Promise<void>;
+/**
+ * The things the worker has to tell the merchant about, under the names their
+ * code can branch on.
+ *
+ * They are one vocabulary rather than several channels because every one of
+ * them has the same shape of consequence — something did not get through — and
+ * a merchant who wants to count them wants to count them together.
+ */
+export declare const WORKER_PROBLEM_KINDS: Readonly<{
+    /** The gateway speaks another dialect of the contract. The loop stops. */
+    readonly CONTRACT_VERSION_MISMATCH: "contract_version_mismatch";
+    /** A poll did not reach the gateway or did not come back as an answer. */
+    readonly POLL_FAILED: "poll_failed";
+    /** The merchant's handler threw. Nothing was answered and the work returns. */
+    readonly HANDLER_FAILED: "handler_failed";
+    /** The handler answered with something the contract does not accept. */
+    readonly HANDLER_ANSWER_REFUSED: "handler_answer_refused";
+    /** Something arrived that nobody had registered a handler for. */
+    readonly NO_HANDLER: "no_handler";
+    /** The answer was produced and could not be delivered to the gateway. */
+    readonly ANSWER_FAILED: "answer_failed";
+    /** The gateway would not take the answer: it names an order it cannot close. */
+    readonly ANSWER_REFUSED: "answer_refused";
+    /** A price answer arrived too late to price the purchase it was asked for. */
+    readonly QUOTE_ANSWER_UNUSED: "quote_answer_unused";
+    /** The worker stopped part-way through a batch and the rest went unread. */
+    readonly BATCH_ABANDONED: "batch_abandoned";
+    /** The loop itself failed in a way nothing here anticipated. A defect in this SDK. */
+    readonly WORKER_FAILED: "worker_failed";
+    /** A delivery carried the one field name this contract removes in silence. */
+    readonly DELIVERY_FIELD_DROPPED: "delivery_field_dropped";
+}>;
+export type WorkerProblemKind = (typeof WORKER_PROBLEM_KINDS)[keyof typeof WORKER_PROBLEM_KINDS];
+export interface WorkerProblem {
+    readonly kind: WorkerProblemKind;
+    /** What happened, in one sentence a person can act on. */
+    readonly message: string;
+    /** Whether the loop stopped because of it. */
+    readonly fatal: boolean;
+    /** The exception behind it, where there was one. */
+    readonly cause?: unknown;
+    /** The order or the price question it is about, where it is about one. */
+    readonly subject?: string;
+}
+export type ProblemReporter = (problem: WorkerProblem) => void;
+/**
+ * Calls a merchant's reporter and lets nothing it does escape.
+ *
+ * Reporting must not be able to end the loop that reports. A merchant's
+ * reporter is their code — a logger over a stream that closed during shutdown,
+ * a client that was never configured — and an exception out of it would
+ * otherwise unwind the worker and, from the worker's own last-resort handler,
+ * escape as an unhandled rejection and take the host process down with it.
+ * There is nowhere left to report a reporter that throws, so it is swallowed.
+ *
+ * Both ways of throwing, and the second is the one that hid. A reporter
+ * declared `void` may still be an `async` function — TypeScript allows it, and
+ * a merchant shipping problems to an HTTP logger will write one — and such a
+ * reporter does not throw, it returns a promise that rejects a turn later, past
+ * this `catch`, with nothing holding it. That is the unhandled rejection this
+ * comment claims not to allow, arriving by the door the `try` does not cover.
+ * So what comes back is settled too, and its failure dropped in the same
+ * silence and for the same reason.
+ *
+ * It is at the top of the file rather than inside the loop because the loop is
+ * not the only thing that reports: a merchant calling `deliver` on an order
+ * directly has a reporter too, and the same reasoning covers it exactly.
+ */
+export declare const reportSafely: (reporter: ProblemReporter, problem: WorkerProblem) => void;
+/**
+ * The one loss in this contract that nobody is told about, said out loud here
+ * because this is the place it would reach the agent.
+ *
+ * A field named `__proto__` is removed while a delivery is parsed, before any
+ * check runs — it is neither carried nor refused, and the merchant's handler
+ * has no way to know that what it returned is not what went out. The contracts
+ * package names the delivery as the place the loss lands in what the agent is
+ * handed — `DeliverySchema` in its `handler.ts` — and a delivery is written
+ * here, so this file says it too.
+ *
+ * No card can declare such a field, so nothing legitimate reaches here; a
+ * merchant only meets it by delivering a name nobody asked for.
+ *
+ * It is one function because there are two roads to the same gateway and the
+ * loss is the same on both: the worker answering with what a handler returned,
+ * and a merchant calling `deliver` on an order himself. Written twice, one of
+ * them would drift or, as it did, never be written at all.
+ */
+export declare const droppedFieldWarning: (orderId: string, delivered: Readonly<Record<string, unknown>> | undefined) => WorkerProblem | null;
+/**
+ * Which registration each kind on the stream is answered by, in the word a
+ * merchant passes to `on`.
+ *
+ * This table is the vocabulary, and everything that has to know the stream's
+ * kinds is derived from it rather than written out again: what a merchant may
+ * register, what the registry holds, what `start` counts as an answer, and the
+ * sentence that names a registration a merchant is missing. It is written over
+ * the contract's own kinds, so a fourth kind added to the envelope — the
+ * confirmation request, whose shape the contract does not carry yet — stops
+ * this file compiling until it has a word of its own here. The `switch` in
+ * `dispatch` below is the second half of that guard, and it is the one that
+ * demands the behaviour.
+ */
+export declare const REGISTERED_AS: Readonly<{
+    readonly order: "order";
+    readonly quote_request: "quote";
+    readonly order_event: "event";
+}>;
+/**
+ * The words a merchant registers something on the stream under.
+ *
+ * Indexed by the table's own keys and not by the contract's kinds, which reads
+ * the same today and behaves very differently on the day a fourth kind is
+ * added. Indexing by a key the table does not have yet collapses this type, and
+ * with it `Handlers[Kind]` and the contextual type of every `agentify.on(...)`
+ * call — so the first compile after the contract grows reports sixty errors, of
+ * which fifty-five are implicit-any at call sites that are not the problem, and
+ * the three places that do need a hand are buried among them. Indexed this way
+ * that same compile names two places, both real.
+ *
+ * Completeness is not what was lost: the `satisfies` clause on the table above
+ * is what demands a word per contract kind, and it still fires.
+ */
+export type StreamHandlerKind = (typeof REGISTERED_AS)[keyof typeof REGISTERED_AS];
+/** What answers each of them, in the shape this loop calls. */
+export interface StreamDispatch {
+    order: OrderDispatch;
+    quote: QuoteDispatch;
+    event: EventHandler;
+}
+/**
+ * The handlers the loop dispatches to, read at the moment an envelope is
+ * handled rather than captured when the loop starts.
+ *
+ * The registry belongs to the client and outlives any one loop. A merchant
+ * registers what their process answers, starts, stops, and starts again on the
+ * same handlers — and a handler registered while a loop is already running is
+ * in place for the next envelope rather than for the next loop.
+ */
+export type HandlerRegistry = {
+    [Kind in StreamHandlerKind]?: StreamDispatch[Kind] | undefined;
+} & {
+    problem: ProblemReporter;
+};
+/**
+ * Time, as the loop sees it.
+ *
+ * A seam rather than a call to `setTimeout` in the middle of the loop, so that
+ * a test can assert which delays were asked for without waiting through them.
+ * It is not part of the published surface: a merchant has no business
+ * replacing the clock their worker runs on.
+ */
+export interface WorkerClock {
+    now(): number;
+    sleep(ms: number, signal: AbortSignal): Promise<void>;
+    random(): number;
+}
+export declare const systemClock: WorkerClock;
+/**
+ * The shortest a quiet poll may take before the next one.
+ *
+ * The gateway holds a poll open for its own window, so in ordinary work this
+ * costs nothing: by the time an empty batch comes back, the floor has long
+ * passed and the next poll goes out at once — which is what keeps a waiting
+ * agent's price question free of any polling lag (ADR-0004 §4). It exists for
+ * the gateway that is not holding requests at all, misconfigured or half
+ * broken, where a loop with no floor turns into as many requests a second as
+ * the network allows. One second is the whole of the claim: slow enough that
+ * nothing is hammered, fast enough that it is invisible against a window
+ * measured in tens of seconds.
+ */
+export declare const QUIET_POLL_FLOOR_MS = 1000;
+/**
+ * How long the worker asks the gateway to hold a poll open, per ADR-0004 §1.
+ *
+ * It is a request and not an expectation. The gateway holds it for its own
+ * window at most, and the contract says as much, so a shorter answer is
+ * ordinary rather than a fault. Asking is what makes the number visible on the
+ * wire, where a gateway that wanted to answer sooner can see it.
+ */
+export declare const POLL_WAIT_SECONDS = 25;
+/**
+ * How long the worker will wait for a poll before giving up on it.
+ *
+ * A window asked for is not a promise kept: a connection dropped silently by
+ * something in the middle — a load balancer that recycled it, a firewall that
+ * forgot it — leaves this side waiting on an answer that will never come, with
+ * nothing reported and nothing retried. Without a deadline of our own the only
+ * thing that eventually breaks that is whatever timeout the runtime happens to
+ * default to, which is a number nobody here chose and which is measured in
+ * minutes against a window measured in seconds.
+ *
+ * Twice the window, so a gateway that holds the full window and answers late is
+ * never cut off, and a connection that has gone quiet costs one window of
+ * silence rather than several minutes of it.
+ *
+ * This worker never comes near it against the gateway in this repository, and
+ * that is not luck: every poll names the window it wants, and that gateway
+ * holds a poll for the smaller of the window asked for and its own, so the wait
+ * is bounded by the twenty-five seconds above however the gateway is
+ * configured. Naming the window is this side's guarantee. The deadline is for
+ * the other case — a connection that died without saying so.
+ *
+ * A second belt exists on the gateway's side, and it is not for this worker.
+ * The window is optional on the wire, and a poll that names none is held for
+ * the gateway's whole configured window instead; that window is refused above a
+ * ceiling set under this number (`WORKER_POLL_WAIT_CEILING_MS` in
+ * `apps/gateway/src/config.ts`), which is where this figure is copied. The
+ * gateway depends on the contracts and the core machine rather than on the SDK,
+ * so it cannot read it, and nothing checks that the copy still matches:
+ * changing what is written here means changing it there in the same breath.
+ *
+ * It is also the reason two poll failures can be a minute and a half apart,
+ * which matters to anybody counting them from outside. A gateway that refuses
+ * connections fails a poll at once and the backoff is the whole gap; one that
+ * accepts and never answers fails only when this deadline runs out, so the gap
+ * is this plus the backoff. `DOUBT_MS` in packages/slice/src/subscription.ts is
+ * that sum, and it is named here because raising this number silently narrows
+ * it — and a window too narrow reads the quiet between two failures as a
+ * recovery.
+ */
+export declare const POLL_DEADLINE_MS: number;
+/** What `startWorker` hands its caller, which is the client and never a merchant. */
+export interface RunningWorker {
+    /**
+     * Stops the loop and waits for it to finish. Safe to call twice.
+     *
+     * Two things are abandoned rather than finished, and they are not abandoned
+     * on the same terms. A poll parked at the gateway is dropped, and whatever
+     * it would have carried was never handed to anybody, so it is redelivered.
+     * An answer already on its way — a delivery the handler produced a moment
+     * ago — is dropped too, and there the honest thing to say is that nobody on
+     * this side knows whether it arrived first: the order may already be closed
+     * by it, or may come back. The merchant is told which of their orders that
+     * happened to, because on their side the work happened.
+     *
+     * Stopping does not drain. The contract has a word for a poll that asks for
+     * whatever is queued right now and comes straight back, and it is not what a
+     * worker shutting down wants: draining pulls more work into a process that
+     * is going away.
+     */
+    stop(): Promise<void>;
+    /** Whether the loop is still going. False once it has stopped for any reason. */
+    running(): boolean;
+}
+export declare const startWorker: (gateway: Gateway, handlers: HandlerRegistry, clock?: WorkerClock, 
+/**
+ * The deadline is a parameter for the same reason the clock is: a test
+ * cannot wait out fifty seconds to find out whether the worker gives up on a
+ * poll, and a deadline nothing exercises is a deadline nobody has seen work.
+ * It is not part of anything a merchant passes.
+ */
+deadlineMs?: number) => RunningWorker;