@nuanu-ai/agentify-contracts 0.3.2 → 0.5.0

package/README.md

@@ -23,7 +23,7 @@ The contract is versioned, and the version is how an SDK and a gateway agree
 that they read the same vocabulary; a worker whose version the gateway does not
 share stops at startup rather than half understanding a document. What the
 merchant-facing side of all this looks like in use is at
-<https://app.agentify.ad/docs/>.
+<https://agentify.ad/docs/>.
 
 ## License
 

package/dist/api.d.ts

@@ -225,9 +225,11 @@ export declare const ReceiptListSchema: z.ZodObject<{
 /**
  * The question a merchant puts in the query string when listing orders.
  *
- * `open=true` narrows the list to the orders that are still owed something —
- * which includes the two that stay open after the purchase itself is over, an
- * order owing a refund and one delivered but never paid for. Leaving it out
+ * `open=true` narrows the list to the orders a restarted worker should walk:
+ * ones the merchant was handed and has not finished, and the two that stay
+ * open after the purchase itself is over, an order owing a refund and one
+ * delivered but never paid for. An order that was priced and never paid, and
+ * never reached the handler, is not in that narrowing. Leaving the field out
  * asks for everything.
  *
  * The value is text and not a boolean, because that is what a query string
@@ -455,9 +457,9 @@ export declare const PurchaseRequestSchema: z.ZodObject<{
 /**
  * What became of a purchase, told to the agent that made it.
  *
- * Four fields, and the shape of the list is the decision rather than its
- * length. This document is what the buyer is owed — where their order stands,
- * what it cost them, and the goods once those exist — and it is deliberately
+ * The shape of the list is the decision rather than its length. This document
+ * is what the buyer is owed — where their order stands, what it cost them, the
+ * goods once those exist, and where to ask again — and it is deliberately
  * smaller than the merchant's own view of the same order. It carries no
  * merchant, no merchant's key for the product, none of the parameters the
  * buyer sent and nothing about any other order, because whoever holds an
@@ -490,6 +492,7 @@ export declare const PurchaseRequestSchema: z.ZodObject<{
  */
 export declare const AgentOrderStatusSchema: z.ZodObject<{
     order_id: z.ZodString;
+    status_url: z.ZodURL;
     status: z.ZodEnum<{
         delivered: "delivered";
         in_progress: "in_progress";
@@ -780,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];
 /**
@@ -1277,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>;
         };
     };
@@ -1291,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>;
         };
     };
@@ -1826,6 +1837,7 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 order_id: z.ZodString;
+                status_url: z.ZodURL;
                 status: z.ZodEnum<{
                     delivered: "delivered";
                     in_progress: "in_progress";
@@ -1861,6 +1873,7 @@ export declare const API_ROUTES: Readonly<{
         response: {
             document: z.ZodObject<{
                 order_id: z.ZodString;
+                status_url: z.ZodURL;
                 status: z.ZodEnum<{
                     delivered: "delivered";
                     in_progress: "in_progress";

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.
@@ -129,9 +129,11 @@ export const ReceiptListSchema = z
 /**
  * The question a merchant puts in the query string when listing orders.
  *
- * `open=true` narrows the list to the orders that are still owed something —
- * which includes the two that stay open after the purchase itself is over, an
- * order owing a refund and one delivered but never paid for. Leaving it out
+ * `open=true` narrows the list to the orders a restarted worker should walk:
+ * ones the merchant was handed and has not finished, and the two that stay
+ * open after the purchase itself is over, an order owing a refund and one
+ * delivered but never paid for. An order that was priced and never paid, and
+ * never reached the handler, is not in that narrowing. Leaving the field out
  * asks for everything.
  *
  * The value is text and not a boolean, because that is what a query string
@@ -146,7 +148,7 @@ export const OrderListQuerySchema = z
     open: z.enum(["true", "false"]).optional(),
 })
     .meta({
-    description: 'Which orders to list. Written as text because a query string carries text. "true" narrows the list to the orders that are still owed something, which includes the two that stay open after the purchase itself is over: an order owing a refund, and one delivered but never paid for. Leaving the field out asks for everything.',
+    description: 'Which orders to list. Written as text because a query string carries text. "true" narrows the list to the orders a restarted worker should walk: ones the merchant was handed and has not finished, an order owing a refund, and one delivered but never paid for. An order that was priced and never paid, and never reached the handler, is not in that narrowing. Leaving the field out asks for everything.',
 });
 /**
  * What a worker asks of one poll.
@@ -309,9 +311,9 @@ export const PurchaseRequestSchema = z
 /**
  * What became of a purchase, told to the agent that made it.
  *
- * Four fields, and the shape of the list is the decision rather than its
- * length. This document is what the buyer is owed — where their order stands,
- * what it cost them, and the goods once those exist — and it is deliberately
+ * The shape of the list is the decision rather than its length. This document
+ * is what the buyer is owed — where their order stands, what it cost them, the
+ * goods once those exist, and where to ask again — and it is deliberately
  * smaller than the merchant's own view of the same order. It carries no
  * merchant, no merchant's key for the product, none of the parameters the
  * buyer sent and nothing about any other order, because whoever holds an
@@ -345,6 +347,38 @@ export const PurchaseRequestSchema = z
 export const AgentOrderStatusSchema = z
     .strictObject({
     order_id: IdentifierSchema,
+    /**
+     * Where this order is read again: the whole address of its status route,
+     * scheme and host included.
+     *
+     * It exists for the agent that bought goods that come later. That agent
+     * holds this document and nothing else, it has already paid, and the
+     * goods are collected at this address. The path is not something it could
+     * work out from what it holds — the purchase was made at an address that
+     * names the product rather than the order — and a guess that misses is
+     * answered `no_such_route`, which says nothing about the order at all.
+     *
+     * Absolute, so that it is called as it stands: a bare path would have to
+     * be joined onto a host the agent was never told was the right one. It is
+     * built from the address the gateway is configured to answer as and never
+     * from the request that asked, because behind the proxy that ends an
+     * agent's TLS connection the request says plain http and names whatever
+     * host the proxy or the caller wrote. Plain http is allowed by the pattern
+     * all the same, because a gateway on a developer's own machine answers on
+     * it; a deployment's address is https because its configuration is.
+     *
+     * The scheme is a pattern rather than zod's own protocol option for the
+     * reason the price hook's is (`PriceCheckSchema` in `card.ts`): a pattern
+     * is what survives into the JSON Schema export, so a client generated from
+     * that document refuses a bare path as well. It is case-sensitive because
+     * a flag on a pattern does not survive that export, and a schema that read
+     * the scheme without regard to case would accept what the exported
+     * document refuses. Nothing is lost by it: the gateway's configuration
+     * already requires its public address in lower case.
+     */
+    status_url: z
+        .url()
+        .regex(/^https?:\/\//, "an order's status address is a whole http or https address, not a path"),
     status: OrderStatusSchema,
     /**
      * The price this order was priced at, or null where nobody ever named one
@@ -412,7 +446,7 @@ export const AgentOrderStatusSchema = z
     refusal: RefusalSchema.optional(),
 })
     .meta({
-    description: 'What became of one purchase, in the words an agent and a merchant both read: where the order stands, what it was priced at, the goods once they are the buyer\'s, and why the merchant would not sell where that is what ended it. It is smaller than the merchant\'s own view of the same order on purpose — no merchant, no merchant\'s own key for the product, none of the purchase parameters and nothing about any other order. The price is what the buyer was asked for and not proof that anything was charged: an order that was priced and then ended without a sale still carries it, and the status is what says which happened. A null price means nobody ever named one for this order, and a null delivery means there are no goods here to hand over; both fields are always present, because an absent field is a silence a reader cannot tell from an oversight. "refusal" is the exception and is present only where a merchant refused: their own short code to branch on and their own sentence to show, carried across unchanged. The code is an open set — "out_of_stock", "invalid_params" and "cannot_fulfill" are read the same way by everybody, and a merchant whose reason fits none of them sends their own word, so an unfamiliar code has to fall through to the sentence rather than break a reader. An absent "refusal" means there is no refusal to quote and never that one was dropped, which leaves two endings still coarse: "rejected" also covers a product that was gone and a payment that failed its check, and neither of those was worded by anybody — the first because a price answer of "not available" carries no words, the second because it is refused at the door in an error envelope instead. A null delivery is likewise not a promise that no goods were ever made: a purchase whose charge failed or went unanswered can leave goods the buyer has not paid for, and this document withholds them rather than describing them. Every answer says whether the money behind the purchase was real: a gateway settling against nothing produces every other field here exactly as a real charge would, so a reader taking this for proof of a payment has to read that word first.',
+    description: 'What became of one purchase, in the words an agent and a merchant both read: where the order stands, what it was priced at, the goods once they are the buyer\'s, and why the merchant would not sell where that is what ended it. "status_url" is where this document is read again — the whole address of the order\'s status route, and the place an agent that bought goods that come later collects them. It is absolute and called as it stands, and it is the address the gateway is configured to answer as, never one taken from the request that asked. It is smaller than the merchant\'s own view of the same order on purpose — no merchant, no merchant\'s own key for the product, none of the purchase parameters and nothing about any other order. The price is what the buyer was asked for and not proof that anything was charged: an order that was priced and then ended without a sale still carries it, and the status is what says which happened. A null price means nobody ever named one for this order, and a null delivery means there are no goods here to hand over; both fields are always present, because an absent field is a silence a reader cannot tell from an oversight. "refusal" is the exception and is present only where a merchant refused: their own short code to branch on and their own sentence to show, carried across unchanged. The code is an open set — "out_of_stock", "invalid_params" and "cannot_fulfill" are read the same way by everybody, and a merchant whose reason fits none of them sends their own word, so an unfamiliar code has to fall through to the sentence rather than break a reader. An absent "refusal" means there is no refusal to quote and never that one was dropped, which leaves two endings still coarse: "rejected" also covers a product that was gone and a payment that failed its check, and neither of those was worded by anybody — the first because a price answer of "not available" carries no words, the second because it is refused at the door in an error envelope instead. A null delivery is likewise not a promise that no goods were ever made: a purchase whose charge failed or went unanswered can leave goods the buyer has not paid for, and this document withholds them rather than describing them. Every answer says whether the money behind the purchase was real: a gateway settling against nothing produces every other field here exactly as a real charge would, so a reader taking this for proof of a payment has to read that word first.',
 });
 /**
  * The catalog as an agent reads it.
@@ -646,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.
@@ -680,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. Two of the 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 a finding whose code is 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. And on a deployment that settles on a real chain, a merchant who has set no wallet gets one whose code is 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. Both come 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 },
     },
@@ -723,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 },
     },
@@ -746,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 },
     },
@@ -783,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: {
@@ -804,7 +842,7 @@ export const API_ROUTES = Object.freeze({
         method: "GET",
         path: "/v0/orders",
         auth: "merchant_key",
-        description: "Orders and the states they are in. With open=true, only the ones still owed something — which includes the two that stay open after the purchase itself is over, an order owing a refund and one delivered but never paid for. One kind of order is not in this list at all, with or without the flag: one that closed before anybody named a price for it, because the product was gone or a price question went unanswered. Every row here is written in a document that carries a sale price and those orders have none, so they are readable one at a time by their identifier, where the refusal says what became of them. A merchant reconciling against this list is reconciling against the orders that were priced.",
+        description: "Orders and the states they are in. With open=true, only the ones a restarted worker should walk — ones the merchant was handed and has not finished, which includes the two that stay open after the purchase itself is over, an order owing a refund and one delivered but never paid for. An order that was priced and never paid, and never reached the handler, is not in that narrowing; it is readable by its identifier, where its status is the buyer's word for a purchase that has not finished. One kind of order is not in this list at all, with or without the flag: one that closed before anybody named a price for it, because the product was gone or a price question went unanswered. Every row here is written in a document that carries a sale price and those orders have none, so they are readable one at a time by their identifier, where the refusal says what became of them. A merchant reconciling against this list is reconciling against the orders that were priced.",
         query: OrderListQuerySchema,
         response: { document: OrderListSchema },
     },
@@ -874,7 +912,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/x402/:item_id/purchase",
         auth: "none",
-        description: "Buying one product. The payment is what stands in for authorisation, so there is no key on this call. It begins with the payment exchange of the x402 protocol: a call with no payment on it is answered with a challenge, which travels in a header and carries no document. What a paid purchase is answered with is the state of the order it made — the same document the status route answers with, whatever the card's mode and whether the purchase ended in the goods or in something else, so an agent that bought and an agent that came back later read one shape. No receipt of ours is in it: a receipt is the merchant's record of the sale and is read behind the merchant's key. What an agent is told about its own money is the price and the word for whether that money was real, and, where the payment executed as the last step of this exchange, the settlement the payment layer signs into a header on this answer — a card whose money moves as the order is opened has already spent that step, so no settlement comes back here and the two fields are the whole of it. The address answers on GET as well as on POST, because that is how the validators and crawlers that list a paid resource ask for it. An unpaid call that carries no document — a GET, or a POST with nothing or with an empty document — is answered with the challenge and never a purchase, and a GET is never read for payment; the challenge describes the purchase, which is a POST with a JSON body. An unpaid POST that carries that document is answered with the price of the very order it opened, and a document of some other shape is refused with the fields that are wrong. A product that is not on sale answers neither method with a challenge: it is refused, so that a catalog built from these challenges never carries a product nobody can buy.",
+        description: "Buying one product. The payment is what stands in for authorisation, so there is no key on this call. It begins with the payment exchange of the x402 protocol: a call with no payment on it is answered with a challenge, which travels in a header and carries no document. What a paid purchase is answered with is the state of the order it made — the same document the status route answers with, whatever the card's mode and whether the purchase ended in the goods or in something else, so an agent that bought and an agent that came back later read one shape. That document names, in status_url, the whole address where the order is read again, which is where goods that come later are collected. No receipt of ours is in it: a receipt is the merchant's record of the sale and is read behind the merchant's key. What an agent is told about its own money is the price and the word for whether that money was real, and, where the payment executed as the last step of this exchange, the settlement the payment layer signs into a header on this answer — a card whose money moves as the order is opened has already spent that step, so no settlement comes back here and the two fields are the whole of it. The address answers on GET as well as on POST, because that is how the validators and crawlers that list a paid resource ask for it. An unpaid call that carries no document — a GET, or a POST with nothing or with an empty document — is answered with the challenge and never a purchase, and a GET is never read for payment; the challenge describes the purchase, which is a POST with a JSON body. An unpaid POST that carries that document is answered with the price of the very order it opened, and a document of some other shape is refused with the fields that are wrong. A product that is not on sale answers neither method with a challenge: it is refused, so that a catalog built from these challenges never carries a product nobody can buy.",
         request: PurchaseRequestSchema,
         also_answers_on: ["GET"],
         response: { document: AgentOrderStatusSchema },
@@ -883,7 +921,7 @@ export const API_ROUTES = Object.freeze({
         method: "GET",
         path: "/x402/orders/:order_id/status",
         auth: "order_id",
-        description: "What became of a purchase, for the agent that made it: where the order stands, what it sold for, and the goods once they are the buyer's. It is the route an agent that bought a product whose goods come later collects them on, and without it half a catalogue takes money and hands back an order nobody can act on. Knowing the order's identifier is the proof (ADR-0011), so this call takes no key: an agent has no account and no registration, and the identifier is handed to exactly one party. No answer of ours hands the agent this address either — it is built from the order's identifier and the address the agent already bought at, which is why it is written the way a stranger would write it and carries no version to guess at. Two things follow for whoever mounts it. Which door a call is behind is read off auth and never off the address, whatever the prefixes happen to agree on today. And an identifier that names no order must be answered exactly as any other unknown one is, or the refusal becomes a way of counting the orders behind it.",
+        description: "What became of a purchase, for the agent that made it: where the order stands, what it sold for, and the goods once they are the buyer's. It is the route an agent that bought a product whose goods come later collects them on, and without it half a catalogue takes money and hands back an order nobody can act on. Every answer that carries the order document names this address in status_url, whole and ready to call, the purchase's own answer included. An order whose goods come later is owed them by the delivery deadline its card carried when the order was opened, counted from its payment: fulfill_deadline_seconds where the card names one, and a day where it names none. An order still without goods at that deadline becomes refund_due, and a paid order the merchant refuses or leaves behind becomes it sooner: the merchant owes the buyer the goods or the money back. That is not an ending, and it carries no further deadline. Goods the merchant delivers after it still appear here and settle the debt, and the order becomes delivered. Nor does refund_due say whether the money has come back: the merchant returns it from their own wallet, the gateway has no way yet to record that they did, and until it has one no order moves on to refunded — a buyer already paid back still reads refund_due here. So an agent holding refund_due can still collect goods here, nothing here tells it when to stop asking, and its own wallet is where a refund shows. Knowing the order's identifier is the proof (ADR-0011), so this call takes no key: an agent has no account and no registration, and the identifier is handed to exactly one party. Two things follow for whoever mounts it. Which door a call is behind is read off auth and never off the address, whatever the prefixes happen to agree on today. And an identifier that names no order must be answered exactly as any other unknown one is, or the refusal becomes a way of counting the orders behind it.",
         response: { document: AgentOrderStatusSchema },
     },
 });

package/dist/index.d.ts

@@ -33,8 +33,8 @@ 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";
@@ -47,8 +47,8 @@ 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";
 /**
@@ -76,6 +76,7 @@ export declare const schemas: Readonly<{
     }, z.core.$strict>;
     agent_order_status: z.ZodObject<{
         order_id: z.ZodString;
+        status_url: z.ZodURL;
         status: z.ZodEnum<{
             delivered: "delivered";
             in_progress: "in_progress";
@@ -615,10 +616,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,14 @@ 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 { 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 +109,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/order-status.js

@@ -68,8 +68,10 @@ export const ORDER_STATUSES = Object.freeze([
      */
     "rejected",
     /**
-     * Closed, and nobody can say whether the buyer was charged: the payment
-     * network was asked and never answered.
+     * Nobody can say whether the buyer was charged: the payment network was
+     * asked and never answered. The order may still be open — the goods may
+     * already be made — and a later read can still move. Closed is not what
+     * this word says.
      *
      * Deliberately not `rejected`, and this is the fifth gate in one value. An
      * agent told its purchase did not happen goes and buys the same thing
@@ -88,7 +90,18 @@ export const ORDER_STATUSES = Object.freeze([
     "expired",
     /** The merchant left, and orders still open closed with them. */
     "cancelled",
-    /** The money moved and the delivery did not happen. */
+    /**
+     * The money moved and the goods have not come: the merchant owes the buyer
+     * the goods or the money back. Not an ending, and it carries no deadline of
+     * its own. Goods the merchant delivers after it still reach the buyer, settle
+     * the debt and make the order `delivered`.
+     *
+     * What it cannot say is whether the money has already gone back. The
+     * merchant pays a refund from their own wallet and the gateway has no way yet
+     * to record that they did, so until it has one nothing moves an order on to
+     * `refunded`, and a buyer the merchant has already paid back still reads
+     * this word.
+     */
     "refund_due",
     /** That debt has since been paid back to the buyer. */
     "refunded",

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

@@ -161,18 +161,27 @@ export const ProblemSchema = z
      * value, and it covers two kinds of finding that a merchant tells apart by
      * the words rather than by the shape: one about the whole of what was
      * sent, and one about the merchant sending it — their having set no name
-     * for buyers to read, or no wallet for their sales to be paid into.
+     * for buyers to read, no wallet for their sales to be paid into, or no
+     * operator approval for the live catalogue.
      * Leaving the field out entirely would make an empty path
      * 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"),
 })
     .meta({
-    description: 'One thing wrong with what was sent: where it is, a code for the program that reads it, and the same finding in words for the person who has to fix it. The path names the field, innermost last — ["params", "email", "type"] — and an empty path is a statement rather than a missing value: the finding is about the whole of what was sent, or about the sender — a merchant with no name set for buyers, or no wallet set for their sales to be paid into, is refused with an empty path too — and not about any one field, which is also what a document that could not be read at all produces. The field is always present for that reason, because an absent path and an empty one would be indistinguishable. Findings never travel alone: they arrive as the problems list inside the error of a call that refused what it was handed — a card that was not published, a delivery that is not what its card declares, a body or a set of purchase parameters that did not fit.',
+    description: 'One thing wrong with what was sent: where it is, a code for the program that reads it, and the same finding in words for the person who has to fix it. The path names the field, innermost last — ["params", "email", "type"] — and an empty path is a statement rather than a missing value: the finding is about the whole of what was sent, or about the sender — a merchant with no name set for buyers, no wallet set for their sales to be paid into, or no operator approval for the live catalogue is refused with an empty path too — and not about any one field, which is also what a document that could not be read at all produces. The field is always present for that reason, because an absent path and an empty one would be indistinguishable. Findings never travel alone: they arrive as the problems list inside the error of a call that refused what it was handed — a card that was not published, a delivery that is not what its card declares, a body or a set of purchase parameters that did not fit.',
 });
 /**
  * Why a call did not go through: a code to branch on, a sentence to print, and
@@ -202,7 +211,7 @@ export const CallErrorSchema = z.strictObject({
     code: z.string().regex(/\S/, "an error carries a code").meta({
         // Same reason as the refusal code: the dictionary travels with the field
         // or it does not reach the reader the export exists for.
-        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name or payout wallet where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call does not exist for this card\'s mode — refusing separately does not, in the synchronous one, where the handler\'s own answer is the refusal). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
+        description: 'Why the call did not go through. The set is open, and five are promised to mean one thing each — but not on the same calls, and which call a code can arrive on is part of what is promised about it. Publishing a card is refused with one word and no other: "card_rejected" (the card was not published, and every finding standing between it and the catalog is named in the error\'s problems — the fields at fault, and the merchant\'s own missing name, payout wallet or live operator approval where those are what is missing; it is never retryable, because the same card gets the same answer and what changes the outcome is fixing what the problems name). The calls that close an order — delivering, refusing, taking one on — are refused with the other four, and never with the first: "refund_already_settled" (the debt was paid back, so there is nothing left to deliver against). "order_already_closed" (the order reached an ending that no call reopens). "not_applicable_in_mode" (the call does not exist for this card\'s mode — refusing separately does not, in the synchronous one, where the handler\'s own answer is the refusal). "delivery_does_not_match_card" (the goods are not the ones the card for this order declares it delivers — nothing was written down, the problems name the fields that did not fit, and the message says whether the order still stands or has already ended). The last of those is retryable in a different sense from a lost connection: the call arrived and was understood, so sending the same goods again gives the same refusal, and what clears it is delivering what the card declares. It is not retryable at all where the order has already ended, because there is nothing left to deliver against.',
     }),
     message: z.string().regex(/\S/, "an error carries an explanation a person can read"),
     retryable: z.boolean(),
@@ -218,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.",
     }),
 });
 /**
@@ -229,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.
@@ -236,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.3.2",
+  "version": "0.5.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": [
@@ -9,7 +9,7 @@
     "zod-schemas",
     "json-schema"
   ],
-  "homepage": "https://app.agentify.ad/docs/",
+  "homepage": "https://agentify.ad/docs/",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",