@nuanu-ai/agentify-contracts 0.4.0 → 0.6.0

package/dist/api.d.ts

@@ -783,7 +783,7 @@ export type ErrorEnvelope = z.infer<typeof ErrorEnvelopeSchema>;
  * has to act on it belongs to the route that sends it and to the sentence the
  * refusal carries.
  */
-export declare const ERROR_CODES: readonly ["body_too_large", "body_undecodable", "call_refused", "charset_unsupported", "encoding_unsupported", "gateway_failed", "key_made_for_a_cabinet", "key_opened_this_call", "malformed_body", "malformed_query", "merchant_departed", "no_such_item", "no_such_key", "no_such_order", "no_such_route", "not_a_cabinet_key", "not_authorised", "not_invited", "not_selling", "not_this_purchase", "order_closed_before_it_was_priced", "order_not_priced_yet", "params_do_not_fit", "payment_already_spent", "payment_not_taken", "payment_not_verified"];
+export declare const ERROR_CODES: readonly ["body_too_large", "body_undecodable", "call_refused", "charset_unsupported", "encoding_unsupported", "gateway_failed", "key_made_for_a_cabinet", "key_opened_this_call", "malformed_body", "malformed_query", "merchant_departed", "no_such_item", "no_such_key", "no_such_order", "no_such_route", "not_a_cabinet_key", "not_authorised", "not_invited", "not_selling", "not_this_purchase", "order_closed_before_it_was_priced", "order_not_priced_yet", "params_do_not_fit", "payment_already_spent", "payment_not_taken", "payment_not_verified", "wallet_change_not_announced", "wallet_change_nobody_to_tell", "wallet_change_raced", "wallet_change_unconfirmed"];
 /** One of the codes this gateway is known to refuse a call with. */
 export type ErrorCode = (typeof ERROR_CODES)[number];
 /**
@@ -1280,6 +1280,10 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 payout_wallet: z.ZodNullable<z.ZodString>;
+                pending: z.ZodNullable<z.ZodObject<{
+                    payout_wallet: z.ZodString;
+                    takes_effect_at: z.ZodISODateTime;
+                }, z.core.$strict>>;
             }, z.core.$strict>;
         };
     };
@@ -1294,6 +1298,10 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 payout_wallet: z.ZodNullable<z.ZodString>;
+                pending: z.ZodNullable<z.ZodObject<{
+                    payout_wallet: z.ZodString;
+                    takes_effect_at: z.ZodISODateTime;
+                }, z.core.$strict>>;
             }, z.core.$strict>;
         };
     };

package/dist/api.js

@@ -105,7 +105,7 @@ export const MerchantCardListSchema = z
     cards: z.array(MerchantCardSchema),
 })
     .meta({
-    description: "A merchant's own catalog: every card they have published, and whether they are taking new orders at all. The merchant's own selling word is here as well as on each card because the two are different facts, and neither can be worked out from the other. A card reads open only where all of it holds at once: the merchant is selling, the card is not paused in its own right, the merchant has a name for it to be sold under, and — on a deployment that settles on a real chain — a wallet for the money to be paid into. So a card can read paused while this field reads open, and this field does not say which of the reasons it was. What does say is the refusal at the publish and the merchant's own settings, each of which names the piece that is missing. This document does not say whether it is the whole catalog: paging is not designed, and when it is, this object grows the field that answers it.",
+    description: "A merchant's own catalog: every card they have published, and whether they are taking new orders at all. The merchant's own selling word is here as well as on each card because the two are different facts, and neither can be worked out from the other. A card reads open only where all of it holds at once: the merchant is selling, the card is not paused in its own right, the merchant has a name for it to be sold under, on a deployment that settles on a real chain a wallet for the money to be paid into, and on the live deployment the operator's approval. So a card can read paused while this field reads open, and this field does not say which of the reasons it was. What does say is the refusal at the publish, whose findings about the merchant carry the codes no_seller_name, no_payout_wallet and no_operator_approval, and the merchant's own settings. This document does not say whether it is the whole catalog: paging is not designed, and when it is, this object grows the field that answers it.",
 });
 /**
  * Every receipt this merchant has.
@@ -680,6 +680,10 @@ export const ERROR_CODES = Object.freeze([
     "payment_already_spent",
     "payment_not_taken",
     "payment_not_verified",
+    "wallet_change_not_announced",
+    "wallet_change_nobody_to_tell",
+    "wallet_change_raced",
+    "wallet_change_unconfirmed",
 ]);
 /**
  * Every call of the surface, under the name it is known by in both programs.
@@ -714,7 +718,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/catalog/publish",
         auth: "merchant_key",
-        description: "Publishes one product, or says what is wrong with the card. Republishing under the same merchant_item_id is how a card is changed rather than how a second one appears. The catalog identifier comes back beside ok, and from then on it is what an agent, a purchase and a receipt all use. A card that is not published comes back as ok:false under the code card_rejected, never retryable, with every finding named in the error's problems. Three findings this can come back with are not about the card at all. A merchant who has not set the name their products are sold under gets no_seller_name, and the way past it is POST /v0/seller-name: a card published without one reaches a buyer's agent inside a payment request that names no seller. On a deployment that settles on a real chain, a merchant who has set no wallet gets no_payout_wallet, with POST /v0/payout-wallet as the way past it: the money from that card's sales is paid to the merchant's own address directly, and without one there is nowhere for it to go. On the live deployment, a merchant the operator has not admitted once gets no_operator_approval. That decision has no merchant API: test publication remains available, while live publication remains closed until the operator grants it. Every applicable finding comes back in the same problems list as whatever is wrong with the card, so one answer carries everything standing between this card and the catalog.",
+        description: "Publishes one product, or says what is wrong with the card. Republishing under the same merchant_item_id is how a card is changed rather than how a second one appears. The catalog identifier comes back beside ok, and from then on it is what an agent, a purchase and a receipt all use. A card that is not published comes back as ok:false under the code card_rejected, never retryable, with every finding named in the error's problems. Three findings this can come back with are not about the card at all. A merchant who has not set the name their products are sold under gets no_seller_name, and the way past it is POST /v0/seller-name: a card published without one reaches a buyer's agent inside a payment request that names no seller. On a deployment that settles on a real chain, a merchant who has set no wallet gets no_payout_wallet, and the way past it is the Settings screen of the merchant's cabinet, where a person signed in sets one: the money from that card's sales is paid to the merchant's own address directly, and without one there is nowhere for it to go. On the live deployment, a merchant the operator has not admitted once gets no_operator_approval. That decision has no merchant API: test publication remains available, while live publication remains closed until the operator grants it. Every applicable finding comes back in the same problems list as whatever is wrong with the card, so one answer carries everything standing between this card and the catalog.",
         request: CardSchema,
         response: { document: PublishResultSchema },
     },
@@ -757,7 +761,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/merchants",
         auth: "none",
-        description: "Makes a merchant and the key whoever registered them will call as them with — both of those or neither. It takes no key because nobody registering has one yet; what stands in the door instead is an invitation code out of the gateway's own configuration, and a gateway with no code configured refuses every registration in the same words a wrong code gets, so this call is not a way of finding out whether registration is open. The key comes back once and is readable nowhere afterwards, and it is a key made for a cabinet: it is in no list of the merchant's keys and is not disabled through them, so no row for it comes back here — only the key itself. What the new merchant does not have is a name: they are listed under nothing until somebody sets one at POST /v0/seller-name, and until then publishing a card is refused, so a cabinet that registers a person and takes them straight to a publish screen has built a dead end. Nothing about an account, an address or a password reaches this call either: those belong to whatever signs a person in, on the other side of it. Unlike every other call on this surface that writes something, a repeat of this one is not safe and there is nothing here that could make it so: two calls make two merchants, and the caller holds a key to only the second. A caller whose connection drops before the answer arrives cannot find out from here whether the first landed — it has no key with which to ask — and the merchant it may have made cannot be swept away afterwards, because a merchant is what every card, order and receipt is owned by.",
+        description: "Makes a merchant and the key whoever registered them will call as them with — both of those or neither. This call is not on the public origin: only the cabinet makes it, from inside the stack, when a signed-in person presses its one control, and from outside the path answers as one the site does not have. It takes no key because nobody registering has one yet; what stands in the door instead is an invitation code out of the gateway's own configuration, and a gateway with no code configured refuses every registration in the same words a wrong code gets, so this call is not a way of finding out whether registration is open. The key comes back once and is readable nowhere afterwards, and it is a key made for a cabinet: it is in no list of the merchant's keys and is not disabled through them, so no row for it comes back here — only the key itself. What the new merchant does not have is a name: they are listed under nothing until somebody sets one at POST /v0/seller-name, and until then publishing a card is refused, so a cabinet that registers a person and takes them straight to a publish screen has built a dead end. Nothing about an account, an address or a password reaches this call either: those belong to whatever signs a person in, on the other side of it. Unlike every other call on this surface that writes something, a repeat of this one is not safe and there is nothing here that could make it so: two calls make two merchants, and the caller holds a key to only the second. A caller whose connection drops before the answer arrives cannot find out from here whether the first landed — it has no key with which to ask — and the merchant it may have made cannot be swept away afterwards, because a merchant is what every card, order and receipt is owned by.",
         request: RegistrationRequestSchema,
         response: { document: RegisteredMerchantSchema },
     },
@@ -780,14 +784,14 @@ export const API_ROUTES = Object.freeze({
         method: "GET",
         path: "/v0/payout-wallet",
         auth: "merchant_key",
-        description: "The address the sales of the merchant this call's own key belongs to are paid into. Payments here are not held by anybody on the way: a buyer's agent pays this address directly and no balance of the merchant's is ever held on our side, which is why the address has to be theirs and why this call exists. Null is the ordinary answer for a merchant who has set none, and it is an answer rather than a refusal — a merchant with no wallet exists and has a settings screen to draw. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent to set it, so a screen showing it shows what the merchant copied out of their wallet character for character.",
+        description: "The address the sales of the merchant this call's own key belongs to are paid into now, and any change of it that is waiting. Payments here are not held by anybody on the way: a buyer's agent pays this address directly and no balance of the merchant's is ever held on our side, which is why the address has to be theirs and why this call exists. Any key of the merchant's reads it, the keys made for their own code included; only the merchant's cabinet sets it. Null is the ordinary answer for a merchant who has set none, and it is an answer rather than a refusal — a merchant with no wallet exists and has a settings screen to draw. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent to set it, so a screen showing it shows what the merchant copied out of their wallet character for character. On the live deployment a replacement for an address already set takes effect forty-eight hours after it was announced to the merchant, and until then this answers with the address still paid and names the waiting one, with the moment it takes effect, under pending. Null there means nothing is waiting, which is always the answer on the test channel and in a sandbox.",
         response: { document: PayoutWalletSchema },
     },
     set_payout_wallet: {
         method: "POST",
         path: "/v0/payout-wallet",
         auth: "merchant_key",
-        description: "Sets the address the sales of the merchant this call's own key belongs to are paid into. The answer is the address as it now stands, read back from what was written rather than echoed, in the mixed-case spelling a wallet shows. Setting the same address twice changes nothing and answers the same way, so a retry after a dropped connection is safe. An address whose capital letters do not agree with the rest of it is refused and nothing is written, because those capitals are a checksum and letters that disagree mean a character is wrong — and an address that is wrong is another perfectly good address belonging to somebody else. What this call will not do is take an address away: null is refused, because without an address there is nowhere to send the money and every published card would quietly come off sale — ending the selling under the name of editing a setting; somebody reaching for that wants either a different address, which is this same call, or an end to selling, which is the pause. On a deployment that settles on a real chain, a merchant with no wallet set here cannot publish a card, and the refusal at the publish says so.",
+        description: "Sets the address the sales of the merchant this call's own key belongs to are paid into. Only the merchant's cabinet makes this call, with the key made for it, from inside the stack, when a person sets the wallet on its Settings screen: keys operate the shop, and where the shop's money goes is set through the cabinet. The public origin does not route this call at all, so from outside it is a path the site does not have; at the gateway a key made for the merchant's own code is refused under not_a_cabinet_key, for the first address as for any other, and nothing is written or announced. The first address a merchant sets applies at once; on the live deployment every cabinet account of the merchant is then told of it, and a message that cannot be sent refuses nothing. On the live deployment a different address after that does not: before anything is written, every account that names the merchant is sent a message saying what changes, when, and that it was asked for in the cabinet, and the change takes effect forty-eight hours after those messages were handed to the mail provider. Until then every payment request names the address that applies now, and the answer carries the waiting one under pending with the moment it takes effect. Asking again for the address already waiting changes nothing, sends no second message and restarts no clock, and answers with the same pending change, so a retry after a dropped connection is safe; a different address replaces the waiting one and starts the forty-eight hours again; asking for the address that applies now cancels the waiting change. On the test channel and in a sandbox every change applies at once and no message is sent. The answer is the wallet as it now stands, read back from what was written rather than echoed, in the mixed-case spelling a wallet shows. Setting the address that already applies, with nothing waiting, changes nothing and answers the same way. An address whose capital letters do not agree with the rest of it is refused and nothing is written, because those capitals are a checksum and letters that disagree mean a character is wrong — and an address that is wrong is another perfectly good address belonging to somebody else. What this call will not do is take an address away: null is refused, because without an address there is nowhere to send the money and every published card would quietly come off sale — ending the selling under the name of editing a setting; somebody reaching for that wants either a different address, which is this same call, or an end to selling, which is the pause. On a deployment that settles on a real chain, a merchant with no wallet set here cannot publish a card, and the refusal at the publish says so.",
         request: PayoutWalletRequestSchema,
         response: { document: PayoutWalletSchema },
     },
@@ -817,14 +821,14 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/keys/cabinet",
         auth: "merchant_key",
-        description: "Makes a key for a cabinet to call as this merchant with, and hands it back once. It is a key of a different kind from the ones at /v0/keys: the merchant did not ask for it, never sees it, and it appears in no list of theirs — so nothing comes back but the key itself. What this is for is a cabinet that replaces its own credential every time somebody signs in, which is what keeps a copy of a cabinet's database from being a set of working keys for long. The call is refused to a key made for the merchant's own code, under not_a_cabinet_key: these two calls are the cabinet's own, and a merchant asking for one would be asking for a credential to a cabinet they are not standing in.",
+        description: "Makes a key for a cabinet to call as this merchant with, and hands it back once. This call and the forgetting beside it are not on the public origin: only the cabinet makes them, from inside the stack, and from outside the path answers as one the site does not have. It is a key of a different kind from the ones at /v0/keys: the merchant did not ask for it, never sees it, and it appears in no list of theirs — so nothing comes back but the key itself. What this is for is a cabinet that replaces its own credential every time somebody signs in, which is what keeps a copy of a cabinet's database from being a set of working keys for long. The call is refused to a key made for the merchant's own code, under not_a_cabinet_key: these two calls are the cabinet's own, and a merchant asking for one would be asking for a credential to a cabinet they are not standing in.",
         response: { document: CabinetKeySchema },
     },
     forget_cabinet_key: {
         method: "DELETE",
         path: "/v0/keys/cabinet",
         auth: "merchant_key",
-        description: "Removes the key this call was made with, and no other. It is removed rather than revoked: a merchant never issued one, never sees one and would never read a revoked one back, so a row kept for the history would be history for nobody. There are no parameters, and that is not a convenience — a key belonging to anybody else, this merchant included, is unreachable here by construction, because the only way to name a key is to be holding it. What a caller does with this is put a key of its own beyond use once it has stopped signing in with it: ask for a fresh key, write it down where the account is kept, then forget the one that was there. A caller that forgets first can be left naming a key that no longer exists, which is the one order that locks somebody out. Made a second time with the same key it is refused as a key that does not exist, which is safe and is the confirmation the first one landed: either way that key is gone and nothing else has moved. It is refused to a key made for the merchant's own code, under not_a_cabinet_key: those are revoked from the list they appear on, at an instant their owner can read back, and removing the row outright would take that history away.",
+        description: "Removes the key this call was made with, and no other. Like the call that makes such a key, it is not on the public origin: only the cabinet makes it, from inside the stack. It is removed rather than revoked: a merchant never issued one, never sees one and would never read a revoked one back, so a row kept for the history would be history for nobody. There are no parameters, and that is not a convenience — a key belonging to anybody else, this merchant included, is unreachable here by construction, because the only way to name a key is to be holding it. What a caller does with this is put a key of its own beyond use once it has stopped signing in with it: ask for a fresh key, write it down where the account is kept, then forget the one that was there. A caller that forgets first can be left naming a key that no longer exists, which is the one order that locks somebody out. Made a second time with the same key it is refused as a key that does not exist, which is safe and is the confirmation the first one landed: either way that key is gone and nothing else has moved. It is refused to a key made for the merchant's own code, under not_a_cabinet_key: those are revoked from the list they appear on, at an instant their owner can read back, and removing the row outright would take that history away.",
         response: { document: ForgottenCabinetKeySchema },
     },
     get_order: {
@@ -893,7 +897,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/quotes/:price_id/answer",
         auth: "merchant_key",
-        description: "The price and availability for a question that came off the worker stream, against the price_id that question carried. The acknowledgement says whether the answer arrived in time to price the purchase; when it did not, stock held against the question can be released.",
+        description: "The price and availability for a question that came off the worker stream, against the price_id that question carried. The acknowledgement says whether the answer arrived in time to price the purchase; when it did not, stock held against the question can be released. A price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot is refused as malformed_body with the reason as its message, and the question stays open for a corrected answer.",
         request: QuoteResponseSchema,
         response: { document: QuoteAnswerAckSchema },
     },

package/dist/card.d.ts

@@ -76,11 +76,12 @@ export declare const ServiceNameSchema: z.ZodString;
  */
 export declare const TagsSchema: z.ZodArray<z.ZodString>;
 /**
- * Both deadlines are shown to the agent before it pays, which is why a card
- * may only carry the ones its own mode uses. A synchronous card advertising a
- * delivery deadline would be advertising a wait that never happens — and the
- * wait for a synchronous answer is our system-wide budget, the same for every
- * product, so it has no field here at all.
+ * A card as a merchant publishes it.
+ *
+ * The plain-text rule runs whatever else is wrong with the card, so a merchant
+ * hears about their markup in the same answer as about their price. The rules
+ * that compare one field with another run only once the shape is right, as
+ * they always have: they need the fields to be what they claim to be.
  */
 export declare const CardSchema: z.ZodObject<{
     merchant_item_id: z.ZodString;

package/dist/card.js

@@ -26,6 +26,7 @@
  */
 import { z } from "zod";
 import { ParamSpecSchema, paramSpecToValidator } from "./param-spec.js";
+import { notPlainTextIn } from "./plain-text.js";
 import { IdentifierSchema, MoneySchema, TimestampSchema } from "./primitives.js";
 import { SellingStateSchema } from "./selling.js";
 /**
@@ -348,8 +349,14 @@ const CardFieldsSchema = z.strictObject({
      *
      * Written as the two fields, or as the one string that becomes them. What is
      * stored and what an agent reads are the two fields either way.
+     *
+     * Publishing holds it to the price rule in `price-rule.ts`, outside this
+     * schema so that a card stored before the rule stays readable; the export
+     * says so, or a generated client would first meet the rule as a refusal.
      */
-    price: CardPriceSchema,
+    price: CardPriceSchema.meta({
+        description: 'Publishing refuses a price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot ("5.00", "0.001"), so that a price the catalog shows is one a payment can be taken at.',
+    }),
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
     params: writtenShort(ParamSpecSchema).optional(),
     result: writtenShort(DeclaredResultSchema),
@@ -390,7 +397,7 @@ const CardFieldsSchema = z.strictObject({
  * wait for a synchronous answer is our system-wide budget, the same for every
  * product, so it has no field here at all.
  */
-export const CardSchema = CardFieldsSchema.superRefine((card, ctx) => {
+const cardRules = (card, ctx) => {
     if (card.fulfillment === "confirm") {
         // The gate, and the reason it is a refusal rather than a note somewhere.
         // A confirmation request reaches the merchant before any money moves and
@@ -428,13 +435,106 @@ export const CardSchema = CardFieldsSchema.superRefine((card, ctx) => {
             message: 'a synchronous card delivers inside the system-wide response budget and sets no delivery deadline; "async" and "confirm" do',
         });
     }
-}).meta({
-    // JSON Schema has no way to say "this field only when that one has this
-    // value", and zod drops the rules above when it renders a document. Left at
-    // that, an engineer generating a client from the export would build one that
-    // sends deadlines a card cannot carry and only find out on the first publish.
-    // Saying it in words is weaker than checking it, and better than silence.
-    description: 'A product in the catalog, as the merchant publishes it. Three rules are enforced beyond the shape below. A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own. This document describes the card as it is stored and read back; three fields also take a shorter spelling at publication, which JSON Schema has no way to show alongside the canonical one. price may be written as one string, the amount and the currency code with a single space between them ("5.00 USD"). A field of params or result may be written as its type word alone (access_url: "string") where it carries no title and no required flag. fulfillment may be left out, and a card that leaves it out is "sync". Each of those is opened out into the form below as the card is accepted, so a card generated from this document is accepted unchanged and a card read back is always in this form.',
+};
+// JSON Schema has no way to say "this field only when that one has this
+// value", and zod drops the rules above when it renders a document. Left at
+// that, an engineer generating a client from the export would build one that
+// sends deadlines a card cannot carry and only find out on the first publish.
+// Saying it in words is weaker than checking it, and better than silence.
+const CARD_RULES_IN_WORDS = 'A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own.';
+/**
+ * The words on a card that an agent reads: the title, the description, and
+ * the title of each field the card declares.
+ *
+ * It reads whatever arrived rather than a card known to be whole, because the
+ * rule runs beside the shape checks and not after them — a merchant told about
+ * a price first and about their markup on the next attempt fixes one thing per
+ * publish. So anything that is not where a card keeps its words is passed over
+ * here and named by the shape check instead.
+ */
+const wordsOf = (card) => {
+    if (!isRecord(card))
+        return [];
+    const words = [];
+    if (typeof card.title === "string") {
+        words.push({ path: ["title"], text: card.title, called: "title", lines: "one line" });
+    }
+    if (typeof card.description === "string") {
+        words.push({
+            path: ["description"],
+            text: card.description,
+            called: "description",
+            lines: "several lines",
+        });
+    }
+    for (const declaration of ["params", "result"]) {
+        const fields = card[declaration];
+        if (!isRecord(fields))
+            continue;
+        for (const [name, field] of Object.entries(fields)) {
+            if (isRecord(field) && typeof field.title === "string") {
+                words.push({
+                    path: [declaration, name, "title"],
+                    text: field.title,
+                    called: "title",
+                    lines: "one line",
+                });
+            }
+        }
+    }
+    return words;
+};
+/**
+ * The card's words are plain text, and a finding for each kind of thing in them
+ * that is not (see `plain-text.ts` for what counts and why the door refuses
+ * rather than cleans).
+ *
+ * Each finding names the field, what was found in it and where, and what the
+ * field is held to. The sentence is written for the merchant who has to find
+ * the characters in their own editor, which is why it quotes the fragment and
+ * counts the position rather than printing the rule.
+ */
+const plainWords = (card, ctx) => {
+    for (const words of wordsOf(card)) {
+        const heldTo = words.lines === "one line"
+            ? `a ${words.called} is plain text on one line`
+            : `a ${words.called} is plain text`;
+        for (const phrase of notPlainTextIn(words.text, words.lines)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...words.path],
+                message: `this ${words.called} carries ${phrase}, and ${heldTo}, which an agent reads exactly as it is written`,
+            });
+        }
+    }
+};
+const PLAIN_TEXT_IN_WORDS = "The title, the description and the title of every declared field are plain text, which an agent reads exactly as it is written: a card is refused where one of them carries HTML markup (a tag, or the opening of a comment), an HTML character reference such as & or ’, or a control character, and a description alone may carry line feeds. An ampersand, a comparison or an arrow written as text passes.";
+/**
+ * The card as it is stored and as its merchant reads it back: every rule a
+ * publish holds it to except that its words are plain text.
+ *
+ * That one rule belongs to the door and not to the reader. A card stored
+ * before it may carry markup, and every answer that carries a stored card is
+ * held to its contract on the way out — so holding a stored card to the rule
+ * would fail the merchant's whole list, and the page of the catalog it sits
+ * on, over one old row, and the merchant could not even see the card they were
+ * meant to republish.
+ */
+const StoredCardSchema = CardFieldsSchema.superRefine(cardRules).meta({
+    description: `A product in the catalog, as it is stored and as its merchant reads it back. Three rules hold beyond the shape below. ${CARD_RULES_IN_WORDS} A publish also holds the title, the description and each declared field's title to plain text; reading a card back does not, so a card stored before that rule is read back exactly as it was stored.`,
+});
+/**
+ * A card as a merchant publishes it.
+ *
+ * The plain-text rule runs whatever else is wrong with the card, so a merchant
+ * hears about their markup in the same answer as about their price. The rules
+ * that compare one field with another run only once the shape is right, as
+ * they always have: they need the fields to be what they claim to be.
+ */
+export const CardSchema = CardFieldsSchema.superRefine(cardRules)
+    .superRefine(plainWords, { when: () => true })
+    .meta({
+    description: `A product in the catalog, as the merchant publishes it. Four rules are enforced beyond the shape below. ${CARD_RULES_IN_WORDS} ${PLAIN_TEXT_IN_WORDS} The shape below is the canonical card, the form every card is stored and read back in; three fields also take a shorter spelling at publication, which JSON Schema has no way to show alongside the canonical one. price may be written as one string, the amount and the currency code with a single space between them ("5.00 USD"). A field of params or result may be written as its type word alone (access_url: "string") where it carries no title and no required flag. fulfillment may be left out, and a card that leaves it out is "sync". Each of those is opened out into the form below as the card is accepted, so a card generated from this document is accepted unchanged and a card read back is always in this form.`,
 });
 /**
  * The check an agent's purchase parameters are held to, for this card.
@@ -688,8 +788,11 @@ export const MerchantCardSchema = z
     id: IdentifierSchema,
     /** When this version of the card was published. */
     as_of: TimestampSchema,
-    /** The card exactly as its merchant published it. */
-    card: CardSchema,
+    /**
+     * The card exactly as its merchant published it, held to the rules of a
+     * stored card rather than to the publish door's.
+     */
+    card: StoredCardSchema,
     /** What a purchase of this card meets right now. */
     selling: SellingStateSchema,
     /** Whether the pause is this card's own, rather than the whole catalog's. */

package/dist/index.d.ts

@@ -33,22 +33,25 @@ export type { EvmAddress } from "./evm-address.js";
 export { checksummedAddressOf, EvmAddressSchema } from "./evm-address.js";
 export type { Acceptance, Delivery, HandlerAnswer, Refusal, RefusalCode } from "./handler.js";
 export { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RECOMMENDED_REFUSAL_CODES, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-export type { CabinetKey, DisabledKey, ForgottenCabinetKey, IssuedKey, IssueKeyRequest, MerchantKey, MerchantKeyList, PayoutWallet, PayoutWalletRequest, RegisteredMerchant, RegistrationRequest, SellerName, SellerNameRequest, } from "./merchant.js";
-export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+export type { CabinetKey, DisabledKey, ForgottenCabinetKey, IssuedKey, IssueKeyRequest, MerchantKey, MerchantKeyList, PayoutWallet, PayoutWalletRequest, PendingPayoutWallet, RegisteredMerchant, RegistrationRequest, SellerName, SellerNameRequest, } from "./merchant.js";
+export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 export type { Order } from "./order.js";
 export { OrderSchema } from "./order.js";
 export type { OrderStatus } from "./order-status.js";
 export { ORDER_STATUSES, OrderStatusSchema } from "./order-status.js";
 export type { FieldSpec, FieldSpecInput, ParamSpec, ParamSpecDirection, ParamSpecInput, ParamType, } from "./param-spec.js";
 export { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, PROTOTYPE_KEY_IS_DROPPED, paramSpecToValidator, } from "./param-spec.js";
+export type { TextLines } from "./plain-text.js";
+export { notPlainTextIn } from "./plain-text.js";
+export { PAYABLE_CURRENCIES, PAYABLE_DECIMALS, priceProblemsOf } from "./price-rule.js";
 export type { Amount, CurrencyCode, Identifier, Money, SalePrice, Timestamp, } from "./primitives.js";
 export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export type { QuotePurpose, QuoteRequest, QuoteResponse } from "./quote.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export type { Receipt, ReceiptOutcome } from "./receipt.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
-export type { CallError, OrderCallResult, Problem, PublishResult } from "./results.js";
-export { CARD_REJECTED, CallErrorSchema, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
+export type { CallError, MerchantFinding, OrderCallResult, Problem, PublishResult, } from "./results.js";
+export { CARD_REJECTED, CallErrorSchema, MERCHANT_FINDINGS, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
 export type { SellingState } from "./selling.js";
 export { SELLING_STATES, SellingStateSchema } from "./selling.js";
 /**
@@ -616,10 +619,18 @@ export declare const schemas: Readonly<{
     }>;
     payout_wallet: z.ZodObject<{
         payout_wallet: z.ZodNullable<z.ZodString>;
+        pending: z.ZodNullable<z.ZodObject<{
+            payout_wallet: z.ZodString;
+            takes_effect_at: z.ZodISODateTime;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     payout_wallet_request: z.ZodObject<{
         payout_wallet: z.ZodPipe<z.ZodString, z.ZodString>;
     }, z.core.$strict>;
+    pending_payout_wallet: z.ZodObject<{
+        payout_wallet: z.ZodString;
+        takes_effect_at: z.ZodISODateTime;
+    }, z.core.$strict>;
     price_check: z.ZodUnion<readonly [z.ZodLiteral<"handler">, z.ZodObject<{
         url: z.ZodURL;
     }, z.core.$strict>]>;

package/dist/index.js

@@ -27,7 +27,7 @@ import { WorkerEnvelopeSchema } from "./envelope.js";
 import { OrderEventSchema, RefundDueReasonSchema } from "./events.js";
 import { EvmAddressSchema } from "./evm-address.js";
 import { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-import { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+import { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 import { OrderSchema } from "./order.js";
 import { OrderStatusSchema } from "./order-status.js";
 import { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, } from "./param-spec.js";
@@ -42,14 +42,16 @@ export { WORKER_ENVELOPE_KINDS, WORKER_ENVELOPE_PAYLOADS, WorkerEnvelopeSchema,
 export { ORDER_EVENT_TYPES, OrderEventSchema, RefundDueReasonSchema } from "./events.js";
 export { checksummedAddressOf, EvmAddressSchema } from "./evm-address.js";
 export { AcceptanceSchema, DeliverySchema, HandlerAnswerSchema, RECOMMENDED_REFUSAL_CODES, RefusalCodeSchema, RefusalSchema, } from "./handler.js";
-export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
+export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedKeySchema, IssueKeyRequestSchema, MerchantKeyListSchema, MerchantKeySchema, PayoutWalletRequestSchema, PayoutWalletSchema, PendingPayoutWalletSchema, RegisteredMerchantSchema, RegistrationRequestSchema, SellerNameRequestSchema, SellerNameSchema, } from "./merchant.js";
 export { OrderSchema } from "./order.js";
 export { ORDER_STATUSES, OrderStatusSchema } from "./order-status.js";
 export { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, PROTOTYPE_KEY_IS_DROPPED, paramSpecToValidator, } from "./param-spec.js";
+export { notPlainTextIn } from "./plain-text.js";
+export { PAYABLE_CURRENCIES, PAYABLE_DECIMALS, priceProblemsOf } from "./price-rule.js";
 export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";
-export { CARD_REJECTED, CallErrorSchema, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
+export { CARD_REJECTED, CallErrorSchema, MERCHANT_FINDINGS, ORDER_CALL_ERROR_CODES, ORDER_CALL_RESULTS, OrderCallResultSchema, ProblemSchema, PublishResultSchema, } from "./results.js";
 export { SELLING_STATES, SellingStateSchema } from "./selling.js";
 /**
  * The version of the public contract. It grows when the meaning of the fields
@@ -109,6 +111,7 @@ export const schemas = Object.freeze({
     param_type: ParamTypeSchema,
     payout_wallet: PayoutWalletSchema,
     payout_wallet_request: PayoutWalletRequestSchema,
+    pending_payout_wallet: PendingPayoutWalletSchema,
     price_check: PriceCheckSchema,
     problem: ProblemSchema,
     public_card: PublicCardSchema,

package/dist/merchant.d.ts

@@ -177,6 +177,25 @@ export declare const SellerNameSchema: z.ZodObject<{
 export declare const SellerNameRequestSchema: z.ZodObject<{
     seller_name: z.ZodPipe<z.ZodString, z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A change of the wallet that has been asked for, announced, and has not taken
+ * effect yet.
+ *
+ * It exists because a replacement does not apply at once where the money is
+ * real (ADR-0019). The address a merchant is paid at is the one setting whose
+ * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * one sitting in their own server's environment — so on the live deployment a
+ * replacement is told to every account of the merchant first and takes effect
+ * forty-eight hours after that. What this document says is the two facts a
+ * merchant needs in that window: what replaces the address, and from when.
+ *
+ * Both are required. An address with no moment says nothing about when the
+ * money moves, and a moment with no address says it moves without saying where.
+ */
+export declare const PendingPayoutWalletSchema: z.ZodObject<{
+    payout_wallet: z.ZodString;
+    takes_effect_at: z.ZodISODateTime;
+}, z.core.$strict>;
 /**
  * The wallet a merchant's sales are paid into, as the merchant reads it back.
  *
@@ -200,9 +219,27 @@ export declare const SellerNameRequestSchema: z.ZodObject<{
  * address in lower case they cannot tell it from a different address without
  * comparing character by character. On the one field money is sent to, that
  * glance is the whole of the checking anybody does.
+ *
+ * `pending` is the change waiting beside it, and it is always present for the
+ * same reason `payout_wallet` is: null says nothing is waiting, and an absent
+ * field would be a silence. It is the field that keeps a caller from taking its
+ * own write for a failure — a merchant who asked for a new address on the live
+ * deployment reads the old one back, correctly, for forty-eight hours, and
+ * without this they would ask again, or conclude the change was lost.
+ *
+ * It is carried without moving `CONTRACT_VERSION`, which is the one known
+ * exception to the rule that a new required field moves it (ADR-0006 §2): no
+ * worker of the SDK reads this route, so the version would stop every
+ * installed worker for a field none of them sees. What that costs is that a
+ * merchant's own code holding this schema from an older release of this
+ * package refuses the answer until the package is upgraded.
  */
 export declare const PayoutWalletSchema: z.ZodObject<{
     payout_wallet: z.ZodNullable<z.ZodString>;
+    pending: z.ZodNullable<z.ZodObject<{
+        payout_wallet: z.ZodString;
+        takes_effect_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * What a merchant sends to change where their sales are paid.
@@ -270,6 +307,7 @@ export type SellerName = z.infer<typeof SellerNameSchema>;
 export type SellerNameRequest = z.infer<typeof SellerNameRequestSchema>;
 export type PayoutWallet = z.infer<typeof PayoutWalletSchema>;
 export type PayoutWalletRequest = z.infer<typeof PayoutWalletRequestSchema>;
+export type PendingPayoutWallet = z.infer<typeof PendingPayoutWalletSchema>;
 export type MerchantKey = z.infer<typeof MerchantKeySchema>;
 export type MerchantKeyList = z.infer<typeof MerchantKeyListSchema>;
 export type IssueKeyRequest = z.infer<typeof IssueKeyRequestSchema>;

package/dist/merchant.js

@@ -51,6 +51,33 @@ import { IdentifierSchema, TimestampSchema } from "./primitives.js";
 const KeyLabelSchema = z
     .string()
     .regex(/^\S(?:[\s\S]*\S)?$/u, "a label must not be empty or padded with spaces");
+/**
+ * The longest label a key is issued with.
+ *
+ * A label used to have no bound, on the argument that no channel outside us
+ * carries it. One does now: on the live deployment the message that tells a
+ * merchant of a new key, or of a wallet change made with one, names the key
+ * by its label (ADR-0019), and that message is Agentify's words in somebody's
+ * inbox. A hundred characters is a line on a list and in a message, and
+ * longer than any name a person gives a worker.
+ */
+const LONGEST_KEY_LABEL = 100;
+/**
+ * A label as a new key is issued with it: the rule above, on one line, and no
+ * longer than {@link LONGEST_KEY_LABEL}.
+ *
+ * Only the request carries the bound. The keys a merchant already holds are
+ * read back under whatever they were named, including a key issued at the
+ * server's terminal, because refusing the list over one old row would hide
+ * every key on it; the message that names such a key cuts it to one line of
+ * the same length itself.
+ */
+const IssuedKeyLabelSchema = KeyLabelSchema.max(LONGEST_KEY_LABEL, `a label is at most ${LONGEST_KEY_LABEL} characters, the one line a key is known by`).regex(
+// Written as code-point ranges rather than a Unicode property, because this
+// pattern is published in the JSON Schema a validator in another language
+// reads, and not every one of those knows the property escapes.
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+/^[^\u0000-\u001F\u007F-\u009F\u2028\u2029]*$/u, "a label is one line: it cannot carry a line break, a tab or another control character");
 /**
  * The key itself, in the only form its owner will ever see it.
  *
@@ -164,10 +191,10 @@ export const MerchantKeyListSchema = z
 /** What a merchant sends to have a key made. */
 export const IssueKeyRequestSchema = z
     .strictObject({
-    label: KeyLabelSchema,
+    label: IssuedKeyLabelSchema,
 })
     .meta({
-    description: "What a merchant asks for when they want another key: the name they will know it by, and nothing else. There is nowhere here to put a secret, because a key is generated rather than chosen — one somebody picks is one somebody reuses somewhere else.",
+    description: "What a merchant asks for when they want another key: the name they will know it by, and nothing else. The name is one line of at most 100 characters, not empty and not padded with spaces; on the live deployment it is also how the message telling the merchant of the new key names it. There is nowhere here to put a secret, because a key is generated rather than chosen — one somebody picks is one somebody reuses somewhere else.",
 });
 /**
  * A key that has just been made: the row, and the secret, once.
@@ -306,6 +333,31 @@ export const SellerNameRequestSchema = z
     .meta({
     description: "What a merchant sends to change the name their products are sold under. The same rule as the answer — at most 32 characters of printable ASCII, the catalog's rule rather than ours — and one difference: null is refused. A merchant goes from no name to a name and from one name to another, never back to none, because a payment request names the seller and there would be nobody to name: every card they have published would come off sale, which is an end to their selling arriving under the name of editing a setting. Somebody reaching for null wants one of two other things: a different name, which is this call with a different value, or an end to selling, which is the pause.",
 });
+/**
+ * A change of the wallet that has been asked for, announced, and has not taken
+ * effect yet.
+ *
+ * It exists because a replacement does not apply at once where the money is
+ * real (ADR-0019). The address a merchant is paid at is the one setting whose
+ * change redirects money, and any key of theirs reaches it — the cabinet's, or
+ * one sitting in their own server's environment — so on the live deployment a
+ * replacement is told to every account of the merchant first and takes effect
+ * forty-eight hours after that. What this document says is the two facts a
+ * merchant needs in that window: what replaces the address, and from when.
+ *
+ * Both are required. An address with no moment says nothing about when the
+ * money moves, and a moment with no address says it moves without saying where.
+ */
+export const PendingPayoutWalletSchema = z
+    .strictObject({
+    /** The address the merchant will be paid at once the wait is over. */
+    payout_wallet: EvmAddressSchema,
+    /** The moment it replaces the address paid now. */
+    takes_effect_at: TimestampSchema,
+})
+    .meta({
+    description: "A replacement wallet that has been asked for and announced and has not taken effect yet. payout_wallet is the address sales will be paid into from takes_effect_at on, in the mixed-case spelling a wallet shows; until that moment every payment request still names the address paid now. The change takes effect then only if it is still the one waiting: asking for the address paid now cancels it, and asking for a different address replaces it and starts the wait again.",
+});
 /**
  * The wallet a merchant's sales are paid into, as the merchant reads it back.
  *
@@ -329,14 +381,30 @@ export const SellerNameRequestSchema = z
  * address in lower case they cannot tell it from a different address without
  * comparing character by character. On the one field money is sent to, that
  * glance is the whole of the checking anybody does.
+ *
+ * `pending` is the change waiting beside it, and it is always present for the
+ * same reason `payout_wallet` is: null says nothing is waiting, and an absent
+ * field would be a silence. It is the field that keeps a caller from taking its
+ * own write for a failure — a merchant who asked for a new address on the live
+ * deployment reads the old one back, correctly, for forty-eight hours, and
+ * without this they would ask again, or conclude the change was lost.
+ *
+ * It is carried without moving `CONTRACT_VERSION`, which is the one known
+ * exception to the rule that a new required field moves it (ADR-0006 §2): no
+ * worker of the SDK reads this route, so the version would stop every
+ * installed worker for a field none of them sees. What that costs is that a
+ * merchant's own code holding this schema from an older release of this
+ * package refuses the answer until the package is upgraded.
  */
 export const PayoutWalletSchema = z
     .strictObject({
-    /** Where this merchant's sales are paid, or nothing at all. */
+    /** Where this merchant's sales are paid now, or nothing at all. */
     payout_wallet: EvmAddressSchema.nullable(),
+    /** A replacement that has been announced and is waiting, or nothing. */
+    pending: PendingPayoutWalletSchema.nullable(),
 })
     .meta({
-    description: "The address a merchant's sales are paid into. Payments are not held by anybody on the way: a buyer's agent pays this address directly, and it is the payTo of every payment request made for this merchant's products. Null means nobody has set one, which is where every merchant starts; the field is always present rather than left out, because an absent field is indistinguishable from a client that dropped it. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent — so what a merchant reads back on a screen is character for character what they copied out of their wallet. On a deployment that settles on a real chain a merchant with no wallet here cannot publish a card, because the money from that card's sales would have nowhere to go.",
+    description: "The address a merchant's sales are paid into, and any change of it that is waiting. Payments are not held by anybody on the way: a buyer's agent pays payout_wallet directly, and it is the payTo of every payment request made for this merchant's products now. Null means nobody has set one, which is where every merchant starts; the field is always present rather than left out, because an absent field is indistinguishable from a client that dropped it. The address comes back in the mixed-case spelling a wallet shows, whichever of the two accepted spellings was sent — so what a merchant reads back on a screen is character for character what they copied out of their wallet. On a deployment that settles on a real chain a merchant with no wallet here cannot publish a card, because the money from that card's sales would have nowhere to go. pending is a replacement that has been asked for and has not taken effect: on the live deployment a merchant who already has a wallet and asks for a different one is told of it by message, and the new address takes effect forty-eight hours later, so until takes_effect_at this answer names the address still paid and the waiting one beside it. A caller reading its old address back beside a pending change has not failed to write; the change is waiting. Null means nothing is waiting, which is every answer on the test channel and in a sandbox, where a change applies at once.",
 });
 /**
  * What a merchant sends to change where their sales are paid.

package/dist/plain-text.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Plain text: what the words on a card are written in.
+ *
+ * A card's title, its description and the title of each field it declares are
+ * read by a buying program exactly as they were written. Nothing between the
+ * merchant and the agent renders HTML, so markup reaches the agent as markup —
+ * `<p>Valid for twelve months.</p>` is read with its angle brackets, and
+ * `Coffee &#038; Brunch` with its number — and a discovery catalog that does
+ * render HTML would swallow some of it and show the rest. Either way the words
+ * an agent acts on are not the words the merchant meant.
+ *
+ * The door refuses such text rather than cleaning it, and that choice is the
+ * whole of this file. Cleaning would make an agent read text the merchant never
+ * wrote: stripping a tag can join two sentences, decoding a reference is a
+ * guess about which table it came from, and dropping an invisible character
+ * changes a string somebody may be matching on. And the merchant would never
+ * learn that their text was being rewritten, so the source stays broken for
+ * every other place it goes. A refusal that names what it found and where is
+ * the version of this a merchant can act on. A shop connector whose source is
+ * HTML turns it into text on its own side, before the door, and asks this same
+ * rule whether it succeeded.
+ *
+ * What is refused is what reads as markup or as a reference, and nothing that
+ * merely shares a character with them. An ampersand between words, a
+ * comparison and an arrow are text: `Tea & coffee`, `5 < 10`, `a -> b`, `AT&T`
+ * and `R&D;` all pass, and so does a space after a bracket, `List< String >`,
+ * which an HTML parser reads as text too.
+ *
+ * Three more shapes pass, and for them the rule is a choice rather than a fact
+ * about HTML: an address in angle brackets, `<jane@example.com>` or
+ * `<https://example.com>`, a bracket that is never closed, `x<y`, and a
+ * bracket before a name HTML would not give an element, `Map<String, Integer>`.
+ * A browser would swallow each of them as a tag, or drop it. They pass because
+ * each is how plain text has always been written, the rule is about text
+ * written as HTML rather than about everything a renderer might misread, and
+ * no reader between the merchant and an agent renders HTML.
+ *
+ * The rule is the publish door's and not the reader's. A card stored before it
+ * may carry anything it refuses, and every answer that carries a stored card is
+ * held to its contract on the way out — so a rule applied on reading would turn
+ * one old row into a failed catalog for every agent and a merchant who cannot
+ * see the card they are meant to fix.
+ */
+/**
+ * Whether a piece of text is one line, as a title is, or may run to several, as
+ * a description may.
+ */
+export type TextLines = "one line" | "several lines";
+/**
+ * What in this text is not plain text, one phrase for each kind of thing found
+ * — markup, character references, control characters — and nothing when all of
+ * it is.
+ *
+ * Each phrase says what was found, how often, and where the first of it is, as
+ * in `HTML markup in 4 places, the first "<p>" at character 1`, and quotes
+ * nothing it would have to print as a control character. It is the one
+ * definition of plain text: the publish door refuses a card with it, and a
+ * connector that turns a shop's HTML into text asks it whether it succeeded.
+ */
+export declare const notPlainTextIn: (text: string, lines: TextLines) => readonly string[];

package/dist/plain-text.js

@@ -0,0 +1,191 @@
+/**
+ * Plain text: what the words on a card are written in.
+ *
+ * A card's title, its description and the title of each field it declares are
+ * read by a buying program exactly as they were written. Nothing between the
+ * merchant and the agent renders HTML, so markup reaches the agent as markup —
+ * `<p>Valid for twelve months.</p>` is read with its angle brackets, and
+ * `Coffee &#038; Brunch` with its number — and a discovery catalog that does
+ * render HTML would swallow some of it and show the rest. Either way the words
+ * an agent acts on are not the words the merchant meant.
+ *
+ * The door refuses such text rather than cleaning it, and that choice is the
+ * whole of this file. Cleaning would make an agent read text the merchant never
+ * wrote: stripping a tag can join two sentences, decoding a reference is a
+ * guess about which table it came from, and dropping an invisible character
+ * changes a string somebody may be matching on. And the merchant would never
+ * learn that their text was being rewritten, so the source stays broken for
+ * every other place it goes. A refusal that names what it found and where is
+ * the version of this a merchant can act on. A shop connector whose source is
+ * HTML turns it into text on its own side, before the door, and asks this same
+ * rule whether it succeeded.
+ *
+ * What is refused is what reads as markup or as a reference, and nothing that
+ * merely shares a character with them. An ampersand between words, a
+ * comparison and an arrow are text: `Tea & coffee`, `5 < 10`, `a -> b`, `AT&T`
+ * and `R&D;` all pass, and so does a space after a bracket, `List< String >`,
+ * which an HTML parser reads as text too.
+ *
+ * Three more shapes pass, and for them the rule is a choice rather than a fact
+ * about HTML: an address in angle brackets, `<jane@example.com>` or
+ * `<https://example.com>`, a bracket that is never closed, `x<y`, and a
+ * bracket before a name HTML would not give an element, `Map<String, Integer>`.
+ * A browser would swallow each of them as a tag, or drop it. They pass because
+ * each is how plain text has always been written, the rule is about text
+ * written as HTML rather than about everything a renderer might misread, and
+ * no reader between the merchant and an agent renders HTML.
+ *
+ * The rule is the publish door's and not the reader's. A card stored before it
+ * may carry anything it refuses, and every answer that carries a stored card is
+ * held to its contract on the way out — so a rule applied on reading would turn
+ * one old row into a failed catalog for every agent and a merchant who cannot
+ * see the card they are meant to fix.
+ */
+/**
+ * Markup: an HTML comment's opening, or a tag.
+ *
+ * A comment is refused on its opening alone, because nobody writing prose
+ * writes `<!--`, and matching on to the close would cost a scan to the end of
+ * the text for every opening in it.
+ *
+ * A tag is an angle bracket, an optional slash, a name, and then the bracket's
+ * close — at once, after a slash, or after whitespace and whatever attributes
+ * follow. The name begins with a letter and carries letters and digits, joined
+ * by a colon or a hyphen where there is one, which is how `<o:p>`, the tag a
+ * word processor leaves in pasted text, and a custom element are written. An
+ * attribute value in quotation marks may carry either bracket, as the alt text
+ * a block editor writes into an image does: `<img alt="Mug <3 coffee">` is one
+ * tag. A quotation mark that opens no value — the apostrophe in
+ * `<img alt=Mom's>`, or `<your friend's name>` — does not hide its tag either:
+ * where the tag cannot be read with its quotation marks paired, it is read to
+ * the first closing bracket, as it was before quoted values were known. What
+ * the name does not take is the rest of what can follow a bracket —
+ * a digit, a space, an `@`, a `:/` — which is why `<3`, `List< String >` and
+ * `<https://example.com>` are not tags here. The close has to be there, so
+ * `x<y` is not one either.
+ *
+ * The scan is linear in the length of the text however it is written: outside
+ * quotation marks everything stops at the next angle bracket, a quoted value
+ * stops at its own closing mark, and a quotation mark can be read only one
+ * way at any point, so no stretch of text is read over and over from one
+ * bracket. The tests hold it at a quarter of a megabyte, which is more than a
+ * publish body may carry, and on the short inputs that turn exponential the
+ * moment a quotation mark may be read two ways.
+ */
+const MARKUP = /<!--|<\/?[A-Za-z][A-Za-z0-9]*(?:[:-][A-Za-z0-9]+)*(?:(?:[\t\n\f\r /](?:[^<>"']|"[^"]*"|'[^']*')*)?>|[\t\n\f\r /][^<>]*>)/g;
+/**
+ * A character reference: an ampersand, a number or a name, and a semicolon.
+ *
+ * The semicolon, and a name of at least two characters, are what separate a
+ * reference from an ampersand in prose. HTML has no name of one letter, so
+ * `AT&T`, `A&B` and `R&D;` are text. A name of two or more is refused whether
+ * or not HTML's own list carries it: `&eacute;` and `&foo;` are both text
+ * written for an HTML reader, and a merchant who meant a character writes the
+ * character.
+ */
+const REFERENCE = /&(?:#[0-9]+|#[xX][0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]+);/g;
+/**
+ * Control characters: C0, DEL and C1. A description may carry a line feed,
+ * U+000A, and nothing else from this range.
+ *
+ * A line feed is the one line break every reader agrees on, and a description
+ * is prose of up to five hundred characters that may run to paragraphs. A
+ * carriage return is refused there with the rest, because `\r\n` is a second
+ * spelling of the same break and a carriage return on its own sends a terminal
+ * back to the start of the line it is printing. A title and a field's title are
+ * one line, so they carry no line break at all. The rest of the range shows
+ * nothing, and a character that shows nothing makes two strings that look
+ * identical and are not.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+const CONTROL_IN_ONE_LINE = /[\u0000-\u001F\u007F-\u009F]/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what it refuses
+const CONTROL_IN_LINES = /[\u0000-\u0009\u000B-\u001F\u007F-\u009F]/g;
+/**
+ * The names a merchant knows the commonest control characters by, in text of
+ * each shape.
+ *
+ * A carriage return in a description is nearly always half of the `\r\n` a
+ * form on Windows submits between two lines, so there it is named together
+ * with the one line break a description does take.
+ */
+const CONTROL_NAMES = {
+    "one line": { "\t": "a tab", "\n": "a line break", "\r": "a carriage return" },
+    "several lines": {
+        "\t": "a tab",
+        "\r": "a carriage return; a description breaks its lines with a line feed, U+000A, alone",
+    },
+};
+/**
+ * The longest piece of the text quoted back in a finding.
+ *
+ * A tag can carry an address of any length, and a finding is a line a person
+ * reads; forty characters is enough to recognise the tag by. Where one is cut,
+ * the finding says so.
+ */
+const QUOTED_AT_MOST = 40;
+/** A character by its code point, as `U+0007`. */
+const codeOf = (character) => `U+${(character.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0")}`;
+/**
+ * DEL and C1, which a quotation leaves as they are.
+ *
+ * `JSON.stringify` escapes C0 and a lone surrogate and nothing else, so a
+ * control character inside a quoted tag would otherwise reach the merchant's
+ * terminal as itself — and U+009B is the start of an escape sequence there.
+ */
+const UNESCAPED_BY_JSON = /[\u007F-\u009F]/g;
+/**
+ * A piece of the text as a finding quotes it: in quotation marks, with every
+ * control character escaped, and cut where it is long.
+ *
+ * The cut is made between two characters and never inside one: a character
+ * outside the basic plane is two units long, and a cut through the middle of
+ * it would quote half a character as an escape nobody wrote.
+ */
+const quoted = (fragment) => {
+    const whole = fragment.length <= QUOTED_AT_MOST;
+    const head = whole ? fragment : fragment.slice(0, QUOTED_AT_MOST).replace(/[\uD800-\uDBFF]$/, "");
+    const shown = JSON.stringify(head).replace(UNESCAPED_BY_JSON, (character) => `\\u${(character.codePointAt(0) ?? 0).toString(16).padStart(4, "0")}`);
+    return whole ? shown : `${shown}… (cut short)`;
+};
+/** A control character as a finding names it: by its code, never printed. */
+const namedIn = (lines) => (character) => {
+    const name = CONTROL_NAMES[lines][character];
+    return name === undefined ? codeOf(character) : `${codeOf(character)} (${name})`;
+};
+/**
+ * One kind of thing that is not plain text, said once for all the places it
+ * occurs: how many there are, and the first of them, where it is.
+ *
+ * The position counts from one, in the same units a description's length is
+ * counted in: UTF-16 code units, so a character outside the basic plane — an
+ * emoji — counts as two, and the number can run ahead of what an editor shows
+ * by one for each such character before it. It is the same count in both
+ * places, which is what lets a merchant set one number against the other.
+ */
+const found = (text, pattern, one, many, shown) => {
+    const matches = [...text.matchAll(pattern)];
+    const first = matches[0];
+    if (first === undefined)
+        return null;
+    const where = `${shown(first[0])} at character ${first.index + 1}`;
+    return matches.length === 1
+        ? `${one}, ${where}`
+        : `${many} in ${matches.length} places, the first ${where}`;
+};
+/**
+ * What in this text is not plain text, one phrase for each kind of thing found
+ * — markup, character references, control characters — and nothing when all of
+ * it is.
+ *
+ * Each phrase says what was found, how often, and where the first of it is, as
+ * in `HTML markup in 4 places, the first "<p>" at character 1`, and quotes
+ * nothing it would have to print as a control character. It is the one
+ * definition of plain text: the publish door refuses a card with it, and a
+ * connector that turns a shop's HTML into text asks it whether it succeeded.
+ */
+export const notPlainTextIn = (text, lines) => [
+    found(text, MARKUP, "HTML markup", "HTML markup", quoted),
+    found(text, REFERENCE, "an HTML character reference", "HTML character references", quoted),
+    found(text, lines === "one line" ? CONTROL_IN_ONE_LINE : CONTROL_IN_LINES, "a control character", "control characters", namedIn(lines)),
+].filter((phrase) => phrase !== null);

package/dist/price-rule.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a price a merchant sets has to be before Agentify will sell at it.
+ *
+ * A price comes in by two doors: on a card, when it is published, and in the
+ * answer to a price question, when a purchase is priced live. The gateway holds
+ * both to the rule below, and the merchant SDK's own check of a card holds it
+ * to the same rule, so a card the check passes is not refused at publication
+ * for its price. Three parts, each standing for a payment that cannot be
+ * taken.
+ *
+ * A price of zero is refused, by design. A payment request for nothing asks
+ * for something that cannot be done, and a gateway that took free items would
+ * be hosting content rather than selling it. A merchant gives a free item away
+ * from their own site, with no payment request in front of it (ADR-0002 §2).
+ *
+ * A currency other than the dollar is refused, because there is no exchange
+ * rate anywhere in this system to charge it at.
+ *
+ * An amount is written in dollars with at least two digits after the dot, so
+ * that a merchant who counts in cents and writes "500" for five dollars is
+ * refused rather than listed at five hundred. Fractions of a cent stay allowed,
+ * because a price per call is often below one, down to the finest amount the
+ * token a buyer pays in can carry and no further: past that there is no exact
+ * amount to charge, and a rounded charge is a different charge.
+ *
+ * So a price the door took is a price the payment edge can charge. The edge
+ * reads the currencies from here, and the places its token carries on every
+ * chain it can charge on are held equal to `PAYABLE_DECIMALS` by a test beside
+ * it, so the door and the edge cannot become two answers.
+ *
+ * It is a rule applied at the doors rather than part of any schema, and that is
+ * the point of it being a function. The schemas also read back every document
+ * already written — every answer that carries a card is held to the contract
+ * on its way out — so a rule written into the card's schema would turn the
+ * whole list of a merchant who published such a price before the rule existed
+ * into a failure, for cards they could otherwise see, pause and replace.
+ */
+import type { Money } from "./primitives.js";
+import type { Problem } from "./results.js";
+/**
+ * The currencies a price may be written in, and the one conversion Agentify
+ * makes.
+ *
+ * A card priced in dollars is charged in the network's own dollar-denominated
+ * asset, one for one. That is a decision and not the absence of one, so it is
+ * written here rather than left to be inferred from the fact that it works: a
+ * merchant who writes "USD" is charging their buyer USDC on the configured
+ * chain, and the two are held to be the same number of dollars.
+ *
+ * Everything else is refused. Nobody has decided where an exchange rate would
+ * come from, and a charge based on an invented one would be the clearest
+ * possible claim beyond the evidence.
+ */
+export declare const PAYABLE_CURRENCIES: readonly string[];
+/**
+ * How many places after the dot a price may carry: the places of USDC, which is
+ * what a buyer pays in. Its smallest unit is a millionth of a dollar, so
+ * "0.000001" is the finest price there is an exact charge for.
+ */
+export declare const PAYABLE_DECIMALS = 6;
+/**
+ * What stands between this price and a sale, as findings on the fields of the
+ * document that carried it — empty where nothing does.
+ *
+ * The paths name `price` because a card and a price answer both carry the
+ * price under that name, so one finding reads right in either. An amount gets
+ * at most one finding: zero is said before the places, because "0" written as
+ * "0.00" would only be refused again.
+ *
+ * The amount has already passed `AmountSchema`, so it is digits with at most
+ * one dot, and the places are what follows the dot.
+ */
+export declare function priceProblemsOf(price: Money): Problem[];

package/dist/price-rule.js

@@ -0,0 +1,104 @@
+/**
+ * What a price a merchant sets has to be before Agentify will sell at it.
+ *
+ * A price comes in by two doors: on a card, when it is published, and in the
+ * answer to a price question, when a purchase is priced live. The gateway holds
+ * both to the rule below, and the merchant SDK's own check of a card holds it
+ * to the same rule, so a card the check passes is not refused at publication
+ * for its price. Three parts, each standing for a payment that cannot be
+ * taken.
+ *
+ * A price of zero is refused, by design. A payment request for nothing asks
+ * for something that cannot be done, and a gateway that took free items would
+ * be hosting content rather than selling it. A merchant gives a free item away
+ * from their own site, with no payment request in front of it (ADR-0002 §2).
+ *
+ * A currency other than the dollar is refused, because there is no exchange
+ * rate anywhere in this system to charge it at.
+ *
+ * An amount is written in dollars with at least two digits after the dot, so
+ * that a merchant who counts in cents and writes "500" for five dollars is
+ * refused rather than listed at five hundred. Fractions of a cent stay allowed,
+ * because a price per call is often below one, down to the finest amount the
+ * token a buyer pays in can carry and no further: past that there is no exact
+ * amount to charge, and a rounded charge is a different charge.
+ *
+ * So a price the door took is a price the payment edge can charge. The edge
+ * reads the currencies from here, and the places its token carries on every
+ * chain it can charge on are held equal to `PAYABLE_DECIMALS` by a test beside
+ * it, so the door and the edge cannot become two answers.
+ *
+ * It is a rule applied at the doors rather than part of any schema, and that is
+ * the point of it being a function. The schemas also read back every document
+ * already written — every answer that carries a card is held to the contract
+ * on its way out — so a rule written into the card's schema would turn the
+ * whole list of a merchant who published such a price before the rule existed
+ * into a failure, for cards they could otherwise see, pause and replace.
+ */
+/**
+ * The currencies a price may be written in, and the one conversion Agentify
+ * makes.
+ *
+ * A card priced in dollars is charged in the network's own dollar-denominated
+ * asset, one for one. That is a decision and not the absence of one, so it is
+ * written here rather than left to be inferred from the fact that it works: a
+ * merchant who writes "USD" is charging their buyer USDC on the configured
+ * chain, and the two are held to be the same number of dollars.
+ *
+ * Everything else is refused. Nobody has decided where an exchange rate would
+ * come from, and a charge based on an invented one would be the clearest
+ * possible claim beyond the evidence.
+ */
+export const PAYABLE_CURRENCIES = Object.freeze(["USD", "USDC"]);
+/**
+ * How many places after the dot a price may carry: the places of USDC, which is
+ * what a buyer pays in. Its smallest unit is a millionth of a dollar, so
+ * "0.000001" is the finest price there is an exact charge for.
+ */
+export const PAYABLE_DECIMALS = 6;
+/**
+ * What stands between this price and a sale, as findings on the fields of the
+ * document that carried it — empty where nothing does.
+ *
+ * The paths name `price` because a card and a price answer both carry the
+ * price under that name, so one finding reads right in either. An amount gets
+ * at most one finding: zero is said before the places, because "0" written as
+ * "0.00" would only be refused again.
+ *
+ * The amount has already passed `AmountSchema`, so it is digits with at most
+ * one dot, and the places are what follows the dot.
+ */
+export function priceProblemsOf(price) {
+    const problems = [];
+    const written = JSON.stringify(price.amount);
+    const places = price.amount.split(".")[1]?.length ?? 0;
+    if (!/[1-9]/.test(price.amount)) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and nothing is sold through Agentify at a price of zero: a free item is offered from your own site, without a payment`,
+        });
+    }
+    else if (places < 2) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and a price is written in dollars with at least two digits after the dot — five dollars is "5.00" — so that an amount counted in cents is never charged as dollars`,
+        });
+    }
+    else if (places > PAYABLE_DECIMALS) {
+        problems.push({
+            path: ["price", "amount"],
+            code: "custom",
+            message: `the price is ${written}, and a price carries at most ${PAYABLE_DECIMALS} digits after the dot, the finest amount USDC can be paid in, so there is no exact amount to charge for it`,
+        });
+    }
+    if (!PAYABLE_CURRENCIES.includes(price.currency)) {
+        problems.push({
+            path: ["price", "currency"],
+            code: "custom",
+            message: `the price is in ${JSON.stringify(price.currency)}, which Agentify cannot charge: it takes USD, paid as USDC one for one, or USDC itself, and holds no exchange rate to anything else`,
+        });
+    }
+    return problems;
+}

package/dist/primitives.d.ts

@@ -39,13 +39,13 @@ export declare const AmountSchema: z.ZodString;
  * does not yet say which of the two it carries, so the shape has to admit
  * both: a national code is three letters (`USD`), and a token ticker is longer
  * and sometimes carries a digit (`USDC`, `USD1`). Eight admits every ticker
- * this contract has had to carry; which currencies are accepted is the
- * gateway's to decide.
+ * this contract has had to carry.
  *
- * What this does not do is check membership in any list. We hold no currency
- * table, and a schema that pretended to would be claiming knowledge the
- * package does not have. Which currencies the gateway accepts is a gateway
- * question, and it is not answered here.
+ * What this does not do is check membership in any list. Which currencies a
+ * merchant may set a price in is answered once, by the price rule in
+ * `price-rule.ts`, at the moment a price comes in. This shape also reads back
+ * every document already written, and a list here would make one written
+ * before the list changed unreadable.
  */
 export declare const CurrencyCodeSchema: z.ZodString;
 /** A sum of money: how much, in what. */

package/dist/primitives.js

@@ -41,13 +41,13 @@ export const AmountSchema = z
  * does not yet say which of the two it carries, so the shape has to admit
  * both: a national code is three letters (`USD`), and a token ticker is longer
  * and sometimes carries a digit (`USDC`, `USD1`). Eight admits every ticker
- * this contract has had to carry; which currencies are accepted is the
- * gateway's to decide.
+ * this contract has had to carry.
  *
- * What this does not do is check membership in any list. We hold no currency
- * table, and a schema that pretended to would be claiming knowledge the
- * package does not have. Which currencies the gateway accepts is a gateway
- * question, and it is not answered here.
+ * What this does not do is check membership in any list. Which currencies a
+ * merchant may set a price in is answered once, by the price rule in
+ * `price-rule.ts`, at the moment a price comes in. This shape also reads back
+ * every document already written, and a list here would make one written
+ * before the list changed unreadable.
  */
 export const CurrencyCodeSchema = z
     .string()

package/dist/quote.js

@@ -82,7 +82,9 @@ export const QuoteRequestSchema = z.strictObject({
 export const QuoteResponseSchema = z.discriminatedUnion("available", [
     z.strictObject({
         available: z.literal(true),
-        price: MoneySchema,
+        price: MoneySchema.meta({
+            description: 'Held to the rule a card\'s price meets at publication: above zero, in USD or USDC, with two to six digits after the dot ("5.00", "0.001"); an answer that breaks it is refused and prices nothing.',
+        }),
         as_of: TimestampSchema,
     }),
     z.strictObject({

package/dist/results.d.ts

@@ -194,6 +194,30 @@ export declare const CallErrorSchema: z.ZodObject<{
  * writes the branch that reads it.
  */
 export declare const CARD_REJECTED = "card_rejected";
+/**
+ * The findings of a refused publish that are about the merchant rather than
+ * the card.
+ *
+ * Each arrives in the refusal's `problems` with an empty path, beside whatever
+ * is wrong with the card, and none of them is cleared by editing the card: the
+ * merchant has no name set for buyers to read, no wallet set for their sales to
+ * be paid into, or no approval from the operator for the live catalog. The
+ * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
+ * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * merchant's code may say where the money goes; and the approval is the
+ * operator's decision, with no call. The name is asked for everywhere, the
+ * wallet wherever a payment settles and the approval on the live deployment
+ * alone, as the publish route's description says; a program needs no copy of
+ * that rule, because it learns what is missing where it is refused, at the
+ * publish.
+ */
+export declare const MERCHANT_FINDINGS: Readonly<{
+    readonly NO_SELLER_NAME: "no_seller_name";
+    readonly NO_PAYOUT_WALLET: "no_payout_wallet";
+    readonly NO_OPERATOR_APPROVAL: "no_operator_approval";
+}>;
+/** One of the findings about the merchant, as its code travels on the wire. */
+export type MerchantFinding = (typeof MERCHANT_FINDINGS)[keyof typeof MERCHANT_FINDINGS];
 /**
  * The answer to publishing a card: the catalog id, or what stands in its way.
  *

package/dist/results.js

@@ -167,8 +167,16 @@ export const ProblemSchema = z
      * indistinguishable from a path nobody filled in.
      */
     path: z.array(z.string()),
-    /** What kind of finding it is, for the code that reads it. */
-    code: z.string().regex(/\S/, "a finding carries a code"),
+    /**
+     * What kind of finding it is, for the code that reads it.
+     *
+     * Open, because a finding about a field carries whatever the check that
+     * found it calls it. The three about the merchant are promised, and they
+     * are described for the export for the reason the error's codes are.
+     */
+    code: z.string().regex(/\S/, "a finding carries a code").meta({
+        description: 'What kind of finding it is, for the program that reads it. The set is open: a finding about a field of what was sent carries the name the check gave it. Three are promised, always with an empty path, and each says the merchant rather than the card is missing something, so no edit to the card clears it: "no_seller_name" (no name set for buyers to read), "no_payout_wallet" (no wallet set for the sales to be paid into, asked for wherever a payment settles) and "no_operator_approval" (the operator has not admitted this merchant to the live catalog, which only the operator can change).',
+    }),
     /** The same finding in words, for the person who has to fix the card. */
     message: z.string().regex(/\S/, "a finding carries an explanation a person can read"),
 })
@@ -219,7 +227,7 @@ export const CallErrorSchema = z.strictObject({
      * is the field the whole shape is named after.
      */
     problems: z.array(ProblemSchema).min(1).optional().meta({
-        description: 'What was wrong with what was sent, one finding at a time: where it is, a code for the program that reads it, and the same finding in words. Present where the call is refusing what it was handed — a card that was not published, a delivery that is not what its card declares — and absent where the refusal is about a state of the world instead: a refund already settled is about the order, not about a field of the request. Never empty where it is present, and a refused publish always carries it. This field is the complete account of what stands in the way, and it is the one to read the findings from. The error\'s "message" is a single line written to be read in a log and does not carry the list: it says how many findings there are, quotes one or a few of them, and marks the place where a long one was cut — so a reader can always tell a short refusal from a shortened account of a long one.',
+        description: "What was wrong with what was sent, one finding at a time: where it is, a code for the program that reads it, and the same finding in words. Present where the call is refusing what it was handed — a card that was not published, a delivery that is not what its card declares — and absent where the refusal is about a state of the world instead: a refund already settled is about the order, not about a field of the request. Never empty where it is present, and a refused publish always carries it. This field is the complete account of what stands in the way, and it is the one to read the findings from. The error's \"message\" is a single line written to be read in a log and does not carry the list. Where what stands in the way is the merchant's own — no seller name, no payout wallet, no operator approval — the message names each of those plainly; for the rest it says how many findings there are, quotes one of them, and marks the place where a long one was cut — so a reader can always tell a short refusal from a shortened account of a long one.",
     }),
 });
 /**
@@ -230,6 +238,28 @@ export const CallErrorSchema = z.strictObject({
  * writes the branch that reads it.
  */
 export const CARD_REJECTED = "card_rejected";
+/**
+ * The findings of a refused publish that are about the merchant rather than
+ * the card.
+ *
+ * Each arrives in the refusal's `problems` with an empty path, beside whatever
+ * is wrong with the card, and none of them is cleared by editing the card: the
+ * merchant has no name set for buyers to read, no wallet set for their sales to
+ * be paid into, or no approval from the operator for the live catalog. The
+ * name is set with a call of the merchant's own (`POST /v0/seller-name`) or in
+ * the cabinet; the wallet in the cabinet's Settings alone, since no key of the
+ * merchant's code may say where the money goes; and the approval is the
+ * operator's decision, with no call. The name is asked for everywhere, the
+ * wallet wherever a payment settles and the approval on the live deployment
+ * alone, as the publish route's description says; a program needs no copy of
+ * that rule, because it learns what is missing where it is refused, at the
+ * publish.
+ */
+export const MERCHANT_FINDINGS = Object.freeze({
+    NO_SELLER_NAME: "no_seller_name",
+    NO_PAYOUT_WALLET: "no_payout_wallet",
+    NO_OPERATOR_APPROVAL: "no_operator_approval",
+});
 /**
  * The error a refused publish carries: the shared shape, with the findings made
  * required.
@@ -237,11 +267,10 @@ export const CARD_REJECTED = "card_rejected";
  * "Refused, and here is nothing" is the one answer a merchant cannot act on,
  * and publishing is the call where that would be easiest to send — a card is
  * refused precisely because something about it is wrong, so there is always
- * something to name. Not every finding is about the card. A merchant who has
- * set no name for buyers to read is refused here too, and so is one who has set
- * no wallet for their sales to be paid into; both ride in the same list, so one
- * answer carries everything standing between this card and the catalog rather
- * than handing it over one round trip at a time.
+ * something to name. Not every finding is about the card: the merchant's own
+ * missing settings (`MERCHANT_FINDINGS`) ride in the same list, so one answer
+ * carries everything standing between this card and the catalog rather than
+ * handing it over one round trip at a time.
  */
 const PublishRefusalSchema = CallErrorSchema.extend({
     problems: z.array(ProblemSchema).min(1),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuanu-ai/agentify-contracts",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "The Agentify wire contract as code: the schemas for cards, orders, price checks and receipts that the gateway and the merchant SDK both read.",
   "keywords": [