@nuanu-ai/agentify 0.5.0 → 0.5.1

package/dist/backoff.d.ts

@@ -1,55 +1,33 @@
 /**
- * How long the worker waits before asking a gateway that did not answer.
+ * How long the worker waits before asking again a gateway that did not answer.
  *
- * This is protocol behaviour rather than infrastructure, which is why it is
- * written here at all. The hand-rolling rule (ADR-0003 §9) reads a wish to
- * build retries by hand as a signal that the wrong component was chosen — and
- * it is right about the general case. This is not the general case: it is the
- * one wait between two calls of one long poll, three constants and a formula,
- * and a retry framework brought in to hold them would be a dependency in the
- * tree a merchant installs (ADR-0003 §8) for something the loop above it does
- * in four lines. If this file ever grows a policy, a registry or a second
- * caller with different needs, that is the trigger to stop and choose one.
+ * The bounds are chosen for the merchant, not promised by the gateway: half a
+ * second costs nothing visible after a dropped connection, and thirty seconds
+ * is close to one long-poll window, so a worker that waited out an outage is
+ * back within about a window of the gateway's return.
  *
- * The numbers are ours and they are not a claim about the gateway. Half a
- * second is short enough that a dropped connection costs a merchant nothing
- * visible, and thirty seconds is close to the long poll's own window, so a
- * worker that waited out an outage comes back within about one window of the
- * gateway returning rather than an hour later.
- *
- * The jitter is the part that is easy to leave out and expensive to lack. Every
- * worker that lost the same gateway failed in the same second; without jitter
- * they all come back in the same millisecond, forever, and the gateway that was
- * struggling is now being hit by the whole fleet in step. Half the delay is
- * fixed and half is drawn, so the delay stays inside the bounds above while no
- * two workers keep the same phase.
+ * Half of every wait is drawn at random. Workers that lost the same gateway
+ * failed in the same second, and without the draw they would all come back in
+ * the same millisecond, hitting a struggling gateway in step for ever.
  */
 /** The wait after the first failed call. */
 export declare const FIRST_RETRY_MS = 500;
 /**
- * The longest this file will ever ask a worker to wait.
+ * The longest wait between two attempts.
  *
- * Copied outside this package, and the copy is named here rather than only
- * where it is read, because whoever raises this number opens this file and not
- * that one. `DOUBT_MS` in packages/slice/src/subscription.ts is the window a
- * mock merchant waits before it decides its subscription is alive again, and it
- * is this ceiling plus the poll deadline plus a margin. Raise this and that
- * window is too narrow, which makes a healthcheck report a dead subscription as
- * a live one.
+ * `DOUBT_MS` in packages/slice/src/subscription.ts is this ceiling plus the
+ * poll deadline plus a margin. Raise this without raising that, and a
+ * healthcheck reports a dead subscription as a live one.
  */
 export declare const RETRY_CEILING_MS = 30000;
 /** What the wait is multiplied by for each further failure in a row. */
 export declare const RETRY_GROWTH = 2;
 /**
- * The wait before attempt number `attempt`, given one draw from [0, 1].
- *
- * The draw is a parameter rather than a call to `Math.random` inside, because
- * a test cannot assert a bound it cannot reproduce, and a delay whose bounds
- * are not tested is a delay nobody has checked.
+ * The wait before attempt number `attempt`, given one draw from [0, 1]. The
+ * draw is passed in so that a test can reproduce the bounds.
  *
- * Both refusals are bugs in the caller rather than conditions to handle, so
- * they are thrown. A zeroth attempt or a draw outside the range would produce
- * a number outside the bounds this file promises, and nothing downstream could
- * tell that it had.
+ * An attempt that is not a whole number from 1 up, or a draw outside [0, 1],
+ * is a bug in the caller and throws a `TypeError`: either would give a wait
+ * outside the bounds.
  */
 export declare const retryDelayMs: (attempt: number, random: number) => number;

package/dist/backoff.js

@@ -1,56 +1,34 @@
 /**
- * How long the worker waits before asking a gateway that did not answer.
+ * How long the worker waits before asking again a gateway that did not answer.
  *
- * This is protocol behaviour rather than infrastructure, which is why it is
- * written here at all. The hand-rolling rule (ADR-0003 §9) reads a wish to
- * build retries by hand as a signal that the wrong component was chosen — and
- * it is right about the general case. This is not the general case: it is the
- * one wait between two calls of one long poll, three constants and a formula,
- * and a retry framework brought in to hold them would be a dependency in the
- * tree a merchant installs (ADR-0003 §8) for something the loop above it does
- * in four lines. If this file ever grows a policy, a registry or a second
- * caller with different needs, that is the trigger to stop and choose one.
+ * The bounds are chosen for the merchant, not promised by the gateway: half a
+ * second costs nothing visible after a dropped connection, and thirty seconds
+ * is close to one long-poll window, so a worker that waited out an outage is
+ * back within about a window of the gateway's return.
  *
- * The numbers are ours and they are not a claim about the gateway. Half a
- * second is short enough that a dropped connection costs a merchant nothing
- * visible, and thirty seconds is close to the long poll's own window, so a
- * worker that waited out an outage comes back within about one window of the
- * gateway returning rather than an hour later.
- *
- * The jitter is the part that is easy to leave out and expensive to lack. Every
- * worker that lost the same gateway failed in the same second; without jitter
- * they all come back in the same millisecond, forever, and the gateway that was
- * struggling is now being hit by the whole fleet in step. Half the delay is
- * fixed and half is drawn, so the delay stays inside the bounds above while no
- * two workers keep the same phase.
+ * Half of every wait is drawn at random. Workers that lost the same gateway
+ * failed in the same second, and without the draw they would all come back in
+ * the same millisecond, hitting a struggling gateway in step for ever.
  */
 /** The wait after the first failed call. */
 export const FIRST_RETRY_MS = 500;
 /**
- * The longest this file will ever ask a worker to wait.
+ * The longest wait between two attempts.
  *
- * Copied outside this package, and the copy is named here rather than only
- * where it is read, because whoever raises this number opens this file and not
- * that one. `DOUBT_MS` in packages/slice/src/subscription.ts is the window a
- * mock merchant waits before it decides its subscription is alive again, and it
- * is this ceiling plus the poll deadline plus a margin. Raise this and that
- * window is too narrow, which makes a healthcheck report a dead subscription as
- * a live one.
+ * `DOUBT_MS` in packages/slice/src/subscription.ts is this ceiling plus the
+ * poll deadline plus a margin. Raise this without raising that, and a
+ * healthcheck reports a dead subscription as a live one.
  */
 export const RETRY_CEILING_MS = 30_000;
 /** What the wait is multiplied by for each further failure in a row. */
 export const RETRY_GROWTH = 2;
 /**
- * The wait before attempt number `attempt`, given one draw from [0, 1].
- *
- * The draw is a parameter rather than a call to `Math.random` inside, because
- * a test cannot assert a bound it cannot reproduce, and a delay whose bounds
- * are not tested is a delay nobody has checked.
+ * The wait before attempt number `attempt`, given one draw from [0, 1]. The
+ * draw is passed in so that a test can reproduce the bounds.
  *
- * Both refusals are bugs in the caller rather than conditions to handle, so
- * they are thrown. A zeroth attempt or a draw outside the range would produce
- * a number outside the bounds this file promises, and nothing downstream could
- * tell that it had.
+ * An attempt that is not a whole number from 1 up, or a draw outside [0, 1],
+ * is a bug in the caller and throws a `TypeError`: either would give a wait
+ * outside the bounds.
  */
 export const retryDelayMs = (attempt, random) => {
     if (!Number.isInteger(attempt) || attempt < 1) {

package/dist/check-card.d.ts

@@ -1,28 +1,7 @@
 /**
- * Is this card enough for an agent to buy from?
- *
- * The check is the contracts schema and the contract's price rule, and nothing
- * beside them. A second opinion written here would be a second definition of a
- * complete card, and the day the two disagreed a merchant would pass one and be
- * refused by the other. The price rule is read here for exactly that reason:
- * it is the gateway's door that applies it rather than the schema, and a check
- * that skipped it would pass a card priced at zero that publishing refuses.
- *
- * What the check cannot see is worth stating, because a merchant reading a
- * short list of findings would otherwise assume it is the whole list. A card is
- * checked in two stages: first its shape — which fields are there, what they
- * hold, whether any field was invented — and then the rules that compare one
- * field against another, such as a delivery deadline being allowed only on the
- * modes that wait, and the price rule. The second stage is only reached when
- * the first passes. So a card that failed on its shape may still have a finding
- * waiting behind the ones it was given, and the report says so instead of
- * implying a clean second run. A card that passes has passed both stages and
- * there is nothing behind it.
- *
- * What no local check can decide at all: whether the gateway will accept the
- * card. Publishing is the authority — a merchant key already in use, a policy
- * nobody has written into the contract — and this check makes no claim about
- * any of that.
+ * The local check of a card: the contract's card schema and its price rule,
+ * and nothing beside them, so a card it passes is not refused at publication
+ * for its shape or its price.
  */
 import { type Problem } from "@nuanu-ai/agentify-contracts";
 export interface CardCheck {
@@ -33,4 +12,16 @@ export interface CardCheck {
      */
     readonly problems: readonly Problem[];
 }
+/**
+ * Checks a card before it is published, without calling the gateway, and
+ * returns every finding under `problems` in the shape the publish call refuses
+ * with. It never throws.
+ *
+ * The card is checked in two stages: its shape first, then the rules between
+ * fields and the price rule. The second stage runs only once the first
+ * passes, so a card refused on its shape may have more findings behind the
+ * ones it was given. Whether the gateway accepts the card is decided only by
+ * publishing: the merchant's own settings, such as a seller name, are not
+ * checked here.
+ */
 export declare const checkCard: (card: unknown) => CardCheck;

package/dist/check-card.js

@@ -1,31 +1,22 @@
 /**
- * Is this card enough for an agent to buy from?
- *
- * The check is the contracts schema and the contract's price rule, and nothing
- * beside them. A second opinion written here would be a second definition of a
- * complete card, and the day the two disagreed a merchant would pass one and be
- * refused by the other. The price rule is read here for exactly that reason:
- * it is the gateway's door that applies it rather than the schema, and a check
- * that skipped it would pass a card priced at zero that publishing refuses.
- *
- * What the check cannot see is worth stating, because a merchant reading a
- * short list of findings would otherwise assume it is the whole list. A card is
- * checked in two stages: first its shape — which fields are there, what they
- * hold, whether any field was invented — and then the rules that compare one
- * field against another, such as a delivery deadline being allowed only on the
- * modes that wait, and the price rule. The second stage is only reached when
- * the first passes. So a card that failed on its shape may still have a finding
- * waiting behind the ones it was given, and the report says so instead of
- * implying a clean second run. A card that passes has passed both stages and
- * there is nothing behind it.
- *
- * What no local check can decide at all: whether the gateway will accept the
- * card. Publishing is the authority — a merchant key already in use, a policy
- * nobody has written into the contract — and this check makes no claim about
- * any of that.
+ * The local check of a card: the contract's card schema and its price rule,
+ * and nothing beside them, so a card it passes is not refused at publication
+ * for its shape or its price.
  */
 import { CardSchema, priceProblemsOf } from "@nuanu-ai/agentify-contracts";
 import { problemsOf } from "./schema.js";
+/**
+ * Checks a card before it is published, without calling the gateway, and
+ * returns every finding under `problems` in the shape the publish call refuses
+ * with. It never throws.
+ *
+ * The card is checked in two stages: its shape first, then the rules between
+ * fields and the price rule. The second stage runs only once the first
+ * passes, so a card refused on its shape may have more findings behind the
+ * ones it was given. Whether the gateway accepts the card is decided only by
+ * publishing: the merchant's own settings, such as a seller name, are not
+ * checked here.
+ */
 export const checkCard = (card) => {
     const result = CardSchema.safeParse(card);
     return {

package/dist/cli.d.ts

@@ -1,21 +1,11 @@
 #!/usr/bin/env node
 /**
- * The command installed by `@nuanu-ai/agentify` as `agentify`.
+ * The command installed by `@nuanu-ai/agentify` as `agentify`. The work is in
+ * `verify.ts`; this is glue.
  *
- * It is glue and nothing else: the work is in `verify.ts`, which answers with
- * a number and a stream of lines, so that everything the command does can be
- * tested without a process, a shell or a temporary directory of output.
- *
- * What a merchant runs is not this file but `dist/cli.js` compiled from it, and
- * the distinction is the whole reason the package has a build. These sources
- * import each other with `.js` specifiers; Node's type stripping does not
- * rewrite such a specifier, so it would look for a `.js` file that is not
- * there and stop. `tsc` writes exactly that file, and `publishConfig.bin` in
- * `package.json` is what points the installed `agentify` command at it.
- *
- * Nothing in this repository runs the compiled command, so nothing in
- * `pnpm test` can tell you it still starts. `pnpm outside` is what does: it
- * installs the packed tarball into a directory with no path back here and runs
- * the installed `agentify verify` command there.
+ * What a merchant runs is `dist/cli.js`, because Node's type stripping does not
+ * rewrite the `.js` specifiers these sources import each other by. Nothing in
+ * `pnpm test` runs the compiled command; `pnpm outside` installs the packed
+ * tarball elsewhere and runs `agentify verify` there.
  */
 export {};

package/dist/cli.js

@@ -1,22 +1,12 @@
 #!/usr/bin/env node
 /**
- * The command installed by `@nuanu-ai/agentify` as `agentify`.
+ * The command installed by `@nuanu-ai/agentify` as `agentify`. The work is in
+ * `verify.ts`; this is glue.
  *
- * It is glue and nothing else: the work is in `verify.ts`, which answers with
- * a number and a stream of lines, so that everything the command does can be
- * tested without a process, a shell or a temporary directory of output.
- *
- * What a merchant runs is not this file but `dist/cli.js` compiled from it, and
- * the distinction is the whole reason the package has a build. These sources
- * import each other with `.js` specifiers; Node's type stripping does not
- * rewrite such a specifier, so it would look for a `.js` file that is not
- * there and stop. `tsc` writes exactly that file, and `publishConfig.bin` in
- * `package.json` is what points the installed `agentify` command at it.
- *
- * Nothing in this repository runs the compiled command, so nothing in
- * `pnpm test` can tell you it still starts. `pnpm outside` is what does: it
- * installs the packed tarball into a directory with no path back here and runs
- * the installed `agentify verify` command there.
+ * What a merchant runs is `dist/cli.js`, because Node's type stripping does not
+ * rewrite the `.js` specifiers these sources import each other by. Nothing in
+ * `pnpm test` runs the compiled command; `pnpm outside` installs the packed
+ * tarball elsewhere and runs `agentify verify` there.
  */
 import { runVerify } from "./verify.js";
 process.exitCode = await runVerify(process.argv.slice(2), (line) => {