@nuanu-ai/agentify 0.4.0 → 0.5.1

package/dist/transport.js

@@ -1,65 +1,25 @@
 /**
- * Making one call of the surface.
+ * Making one call of the surface. Every address, method and answer document
+ * comes from the route table in `@nuanu-ai/agentify-contracts`, and the key's
+ * header is built by `merchantKeyHeaderValue` from the same package, so this
+ * package writes down no path and no header of its own.
  *
- * Every address, method and answer document comes out of the route table in
- * `@nuanu-ai/agentify-contracts`. No path is written down in this package, and the
- * table's own `expandPath` does the substituting, because an identifier we
- * accept may hold a slash or a space and pasted into an address unencoded it
- * becomes two segments and a different route.
+ * The answer is read the same way whatever its HTTP status: the route's
+ * document if it is one, otherwise the gateway's error envelope if it is one,
+ * and only otherwise a failure this package describes itself, with the status.
  *
- * The table deliberately leaves out three things that a program actually
- * making the calls cannot avoid deciding, and it is worth saying here what was
- * decided, because each of them is a place where the two sides can disagree
- * without either of them noticing.
- *
- * The first is the header the merchant's key travels in. The table says which
- * door a call is behind and not how the door is built, so the choice is the
- * gateway's and ours to match — and matching it by each writing the same two
- * strings down was agreement by luck, where a call behind that door fails with
- * an authorisation error and nothing in either repository says why. So the name
- * and the scheme live in `@nuanu-ai/agentify-contracts`, in the one place both sides
- * already import: `merchantKeyHeaderValue` builds the value this package sends,
- * and `merchantKeyFrom` is what the gateway reads it back with.
- *
- * The second is the status code, about which the table says nothing either.
- * Some of the answers this surface gives are refusals that are still documents
- * — a card that was not accepted, an order call that did not go through — and
- * rather than guess which of those arrive under a 200 and which under a 400,
- * the answer is read the same way whatever the status. If the body is the
- * document the route names, that is the answer. Otherwise it is asked whether
- * it is the one envelope every route refuses in, and if it is, what the caller
- * is told is the gateway's own code and its own sentence rather than a
- * complaint from here about a document that did not parse — the gateway is the
- * side that knows why, and the reason it wrote is the only thing the caller
- * can act on. Only a body that is neither is a failure this package has to
- * describe itself, and then the status is part of what it says.
- *
- * The third is what a failure is at all. Nothing here throws: a call comes
- * back either as the document or as a failure carrying a sentence and, where
- * there was one, the body that could not be read. The layer above decides
- * which of those the merchant is entitled to see as a return value and which
- * is an exception, and that decision is in `client.ts`, where the contract
- * says which calls have a failure branch of their own. The body travels with
- * the failure because one caller needs it: a poll answer this SDK cannot parse
- * may still name the contract version the gateway speaks, and that is how a
- * genuine difference of dialects is told apart from a broken gateway.
+ * Nothing here throws. A call comes back as the document or as a failure;
+ * `client.ts` decides which failures a merchant sees returned and which
+ * thrown. The body travels with a failure because a poll answer this SDK
+ * cannot parse may still name the gateway's contract version.
  */
 import { API_ROUTES, ErrorEnvelopeSchema, expandPath, MERCHANT_KEY_HEADER, merchantKeyHeaderValue, } from "@nuanu-ai/agentify-contracts";
 /**
- * What is known about whether the call got there.
- *
- * Three and not two, and the third is the one that matters. A first draft had
- * a boolean, which meant every failure that was not an answer was filed as
- * "it did not reach us" — including a request that was fully sent and then
- * abandoned when the worker stopped, or one whose connection broke after the
- * gateway had it. Those are not the same fact, and a merchant reconciling
- * their books from the wrong one of them is reconciling from something we made
- * up.
- *
- * `not_received` is claimed only where the network says so plainly: the
- * connection was refused or the name did not resolve, so nothing was ever
- * handed over. Everything else that produced no readable answer is `unknown`,
- * because it is.
+ * What is known about whether the call got there. `not_received` is claimed
+ * only where the network says plainly that nothing was handed over: the
+ * connection was refused or the name did not resolve. Everything else without
+ * a readable answer is `unknown`, so that a merchant never reconciles their
+ * books from something this package made up.
  */
 export const REACH = Object.freeze({
     /** No connection was made, so the gateway certainly has nothing. */
@@ -67,31 +27,23 @@ export const REACH = Object.freeze({
     /** The gateway answered, and the answer is not one this package can read. */
     ANSWERED: "answered",
     /**
-     * The exchange was cut short. What the call did is not known here.
-     *
-     * Deliberately silent about direction, because three different things end
-     * up here and they do not agree about it: an abort that may have fired
-     * before the request left, a connection that broke once it was under way,
-     * and an answer that started arriving and stopped. What they share is that
-     * no complete answer was had, and that is all this may be read as saying.
+     * The exchange was cut short, and what the call did is not known here. It
+     * says nothing about direction: an abort may have fired before the request
+     * left, a connection may have broken under way, or an answer may have
+     * stopped arriving.
      */
     UNKNOWN: "unknown",
 });
 /**
- * The three codes the network gives us that mean nothing was handed over.
- *
- * Kept short on purpose: every code not on this list is read as "unknown",
- * which is the answer that claims least. A code added here is a claim that the
- * request certainly never arrived, and it should be added only when that is
- * true of it.
+ * The network codes that mean nothing was handed over. Every other code reads
+ * as unknown, so add one here only if it certainly means the request never
+ * arrived.
  */
 const NOTHING_WAS_SENT = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN"]);
 /**
- * The network's own codes for why a call failed, however many there were.
- *
- * There can be several: a name that resolves to more than one address is tried
- * at each of them, and what comes back is one error holding the others. All of
- * them have to say nothing was sent before we say it.
+ * The network's own codes for why a call failed. A name that resolves to
+ * several addresses is tried at each and fails with one error holding the
+ * others, so there can be several.
  */
 const codesUnder = (cause) => {
     const inner = cause?.cause;
@@ -105,12 +57,9 @@ const codesUnder = (cause) => {
     return typeof code === "string" ? [code] : [];
 };
 /**
- * What a failed `fetch` says about whether anything was handed over.
- *
- * Exported for its own test rather than only through a socket: the rule that
- * every address tried has to say nothing was sent — not merely one of them —
- * is not reachable from a test that can only produce one address at a time,
- * and a rule nothing checks is a rule that will be relaxed by accident.
+ * What a failed `fetch` says about whether anything was handed over: nothing,
+ * only where every address tried says so. Exported for its own test, which
+ * can produce several addresses where a socket test cannot.
  */
 export const reachOf = (cause) => {
     const codes = codesUnder(cause);
@@ -119,13 +68,9 @@ export const reachOf = (cause) => {
         : REACH.UNKNOWN;
 };
 /**
- * How much of an answer we could not read is quoted back in the failure.
- *
- * A quote is worth more than a length — an HTML error page from a proxy names
- * the thing that is actually broken — and a whole one is worth less than
- * nothing, because a gateway can answer with a megabyte and this text ends up
- * in a merchant's log. What is cut is said in the same sentence rather than
- * left as an ellipsis a reader has to interpret.
+ * How much of an unreadable answer is quoted back in the failure. A proxy's
+ * error page often names what is broken, but a whole one can be a megabyte in
+ * a merchant's log; what is cut is said in the same sentence.
  */
 const QUOTED_CHARACTERS = 200;
 const quote = (text) => text.length <= QUOTED_CHARACTERS
@@ -144,36 +89,18 @@ const failure = (route, reason, reach, body, refusal) => ({
     },
 });
 /**
- * What is known about a failed call, in a clause that can be dropped into a
- * sentence about whatever the call was carrying.
- *
- * It lives here rather than in each caller so that the four cases are
- * described in one place and cannot drift into four different vocabularies.
- * Three of them are the reaches; the fourth is a refusal the gateway wrote in
- * words we recognise, which is the one failure here that is not a silence and
- * so does not belong to any of them.
+ * What is known about a failed call, as a clause to put before the failure's
+ * own `reason`: one for each reach, and one for a refusal the gateway wrote in
+ * words this package recognises.
  *
- * Each clause is held to what its own case actually knows, and the last reach
- * is the one that has to be written carefully, because it is one sentence in
- * front of three different situations. A call abandoned on an abort throws
- * with no code at all and may never have left this process. A connection that
- * broke in flight was certainly sent. And an answer that stopped mid-sentence
- * means the gateway certainly had the call — a status and part of a body came
- * back. So this clause says nothing about direction: not that the call was
- * sent, not that nothing came back, and not that whether it arrived is
- * unknown, because on the third road it is known and the answer is yes. What
- * the three share is that the exchange was cut short, and so what the call did
- * is not known — and that is the whole of what may be claimed here. The
- * specifics belong to the failure's own `reason`, which every caller prints
- * immediately after this clause and which names the road it came down.
+ * The clause for `unknown` covers three situations (an abort before sending, a
+ * connection broken in flight, an answer cut off mid-way), so it claims only
+ * that the exchange did not finish and what the call did is not known; the
+ * `reason` that follows names which it was.
  */
 export const whatIsKnown = (failure) => {
-    // The fourth case, ahead of the three reaches. Each of those says some
-    // version of "we cannot tell you what this call did"; here the gateway told
-    // us, in a shape we recognise, that it would not do it. Sending a merchant
-    // "what came back could not be read" in front of a reason we are about to
-    // quote is the message arguing with itself, and the half they believe is the
-    // first one.
+    // A refusal comes first: the gateway said what it would not do, and "what
+    // came back could not be read" in front of its reason would contradict it.
     if (failure.refusal !== undefined) {
         return "it reached us and the answer says the call did not go through";
     }
@@ -188,13 +115,11 @@ export const whatIsKnown = (failure) => {
 };
 /**
  * One call, answered with the route's document or with a sentence about why
- * there is no document.
+ * there is none.
  *
- * The cast at the end is the one place this file steps outside what the
- * compiler can follow. `API_ROUTES[name]` for an unresolved `name` is a union
- * of every route, so the schema reached at runtime is the right one while its
- * static type is the union of all of them. `DocumentOf<N>` names the same
- * schema for the caller, and the two are the same object.
+ * The cast at the end is safe though the compiler cannot follow it: for an
+ * unresolved `name` the static type of the schema is a union of every route's,
+ * while at runtime it is the right one.
  */
 export const callRoute = async (gateway, name, options = {}) => {
     const route = API_ROUTES[name];
@@ -225,9 +150,8 @@ export const callRoute = async (gateway, name, options = {}) => {
         text = await response.text();
     }
     catch (cause) {
-        // The gateway answered and the answer was not read to the end. Saying
-        // "answered with something that is not JSON" here would be blaming it for
-        // a connection that broke on our side of the exchange.
+        // The gateway answered and the answer was not read to the end; calling it
+        // "not JSON" would blame the gateway for a connection broken on our side.
         return failure(name, `${name} at ${url.href} began answering ${response.status} and the answer could not be read to the end: ${String(cause)}`, REACH.UNKNOWN);
     }
     let body;
@@ -241,27 +165,12 @@ export const callRoute = async (gateway, name, options = {}) => {
     if (parsed.success) {
         return { ok: true, document: parsed.data };
     }
-    // A body that is not the route's document is asked whether it is the
-    // envelope every route says no in, and if it is, the caller is handed what
-    // the gateway said rather than our complaint about being unable to read it.
-    // That is the difference between telling a merchant their order is over and
-    // sending them to read our schemas.
-    //
-    // What keeps this from swallowing one of the surface's own documents is not
-    // the order of these two reads. Some of those documents are refusals — an
-    // order call that did not go through says so inside the shape its route
-    // promises — and the envelope declines them on its own: its outer object is
-    // strict, so a body carrying anything beside `error` is not one, and the
-    // `ok` discriminator those answers lead with is exactly such a field. The
-    // guarantee is held where it can be checked rather than here, by a case in
-    // `api.test.ts` that puts an envelope to every route's document and demands
-    // a refusal from each. Reversing these two reads is not what would break it,
-    // which is why this paragraph does not claim the order is load-bearing.
-    //
-    // The status is not consulted, here or above. Which refusals of this surface
-    // arrive under which code is the gateway's to decide and is written down
-    // nowhere both sides read, so a rule keyed on it would be a guess; the shape
-    // of the answer is the agreement, and it is the same at 402 as at 500.
+    // A body that is not the route's document may be the error envelope, and
+    // then the caller gets what the gateway said. Refusals that live inside a
+    // route's own document cannot be mistaken for it, because the envelope's
+    // outer object is strict and those documents carry `ok`; a test in
+    // `api.test.ts` holds that for every route. The HTTP status is not
+    // consulted: which refusal arrives under which status is the gateway's.
     const refused = ErrorEnvelopeSchema.safeParse(body);
     if (refused.success) {
         const { code, message, retryable } = refused.data.error;

package/dist/verify.d.ts

@@ -1,74 +1,23 @@
 /**
- * `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.
- */
-/**
- * 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.
+ * `agentify verify`: the check a merchant runs on their card files before
+ * publishing them, whether each card is enough for an agent to assemble a
+ * correct purchase, read the way publication reads it.
+ *
+ * Whether the merchant's handler holds against one order delivered twice
+ * cannot be tried by a command holding only card files, so the output says it
+ * is not checked here and where it is proved instead; it does not count
+ * against the exit code. The cards to check are named on the command line,
+ * because nothing says where a merchant keeps them.
  */
+/** What the command answers with. */
 export declare const VERIFY_EXIT: Readonly<{
-    /** Every check ran and every check passed. */
+    /** Every card it was given is complete as far as the contract can tell. */
     PASSED: 0;
-    /** A check ran and found something. */
+    /** A card has findings. */
     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 declare const IDEMPOTENCY_IS_NOT_BUILDABLE: string;
 /** The code a finding carries when the file held no card to check at all. */
 export declare const NOT_JSON = "not_json";
 export type Say = (line: string) => void;

package/dist/verify.js

@@ -1,90 +1,33 @@
 /**
- * `agentify verify` — the check a merchant runs on themselves before they
- * ask us to look.
+ * `agentify verify`: the check a merchant runs on their card files before
+ * publishing them, whether each card is enough for an agent to assemble a
+ * correct purchase, read the way publication reads it.
  *
- * 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.
+ * Whether the merchant's handler holds against one order delivered twice
+ * cannot be tried by a command holding only card files, so the output says it
+ * is not checked here and where it is proved instead; it does not count
+ * against the exit code. The cards to check are named on the command line,
+ * because nothing says where a merchant keeps them.
  */
 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.
- */
+/** What the command answers with. */
 export const VERIFY_EXIT = Object.freeze({
-    /** Every check ran and every check passed. */
+    /** Every card it was given is complete as far as the contract can tell. */
     PASSED: 0,
-    /** A check ran and found something. */
+    /** A card has findings. */
     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.",
+/** What this command does not check, and where that is proved instead. */
+const NOT_CHECKED_HERE = [
+    "Repeats of one order: not checked by this command.",
+    "  Whether a second delivery of the same order makes second goods is proved",
+    "  against your own delivery system, with a test purchase: the buyer has to",
+    "  keep what the first delivery carried.",
 ].join("\n");
 /** The code a finding carries when the file held no card to check at all. */
 export const NOT_JSON = "not_json";
@@ -99,49 +42,16 @@ const USAGE = [
     "",
     "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.",
+    "Answers: 0 every card is complete as far as the contract can tell, 1 a card",
+    "has findings, 2 called with something it cannot work from. Whether your",
+    "handler holds against an order delivered twice is not checked here.",
 ].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` and applies the same
- * price rule this package does, so the cards on it passed this check on the
- * day they went out — which is not the same as passing it now. The schema can
- * move, and the price rule is applied only at publication: a stored card is
- * parsed again on its way back out against the schema alone, so a card
- * published before the price rule tightened is read back as it was, and one
- * that no longer fits a schema that moved fails that read. And a
- * command that builds no client can never learn which version of the contract
- * the gateway is speaking. Publishing is more than this check, too: it can
- * refuse a card for reasons the contract does not carry, 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 all but
- * always pass — they got onto it by passing this very check — 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.
+ * What the bare command, with no card files, answers. This command takes no
+ * key and builds no client, so it cannot see published cards; and checking
+ * them would all but always pass, since a card is published only after the
+ * same check. A green that cannot fail teaches a merchant to stop reading it.
+ * The card files are what the next publish carries, so they are what to name.
  */
 const NOTHING_TO_CHECK = [
     "agentify verify was given no card files, and it does not go looking for them:",
@@ -195,7 +105,7 @@ export const runVerify = async (argv, say) => {
         say(NOTHING_TO_CHECK);
         say("");
         say(USAGE);
-        return VERIFY_EXIT.COULD_NOT_RUN;
+        return VERIFY_EXIT.USAGE;
     }
     const checked = [];
     for (const file of files) {
@@ -218,19 +128,15 @@ export const runVerify = async (argv, say) => {
     }
     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.
+        // The truncation, said out loud: the rules between fields are reached
+        // only once the shape passes, so one round of fixes may not be 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(NOT_CHECKED_HERE);
     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;
+        ? "Verdict: the cards have findings."
+        : "Verdict: the cards are complete as far as the contract can tell.");
+    return faulted.length > 0 ? VERIFY_EXIT.PROBLEMS : VERIFY_EXIT.PASSED;
 };