@nuanu-ai/agentify-contracts 0.6.0 → 0.8.0

package/dist/card.js

@@ -25,21 +25,29 @@
  * more shape to keep in step for no gain to anybody.
  */
 import { z } from "zod";
-import { ParamSpecSchema, paramSpecToValidator } from "./param-spec.js";
+import { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, paramSpecToValidator, } from "./param-spec.js";
 import { notPlainTextIn } from "./plain-text.js";
-import { IdentifierSchema, MoneySchema, TimestampSchema } from "./primitives.js";
+import { IdentifierSchema, MoneySchema, OpenWordSchema, TimestampSchema } from "./primitives.js";
+import { SellerSiteSchema } from "./seller-site.js";
 import { SellingStateSchema } from "./selling.js";
+import { ShipToSchema } from "./ship-to.js";
+import { ShipmentSchema } from "./shipment.js";
 /**
  * When the product reaches the agent, and therefore when the money moves.
  *
  * `sync` — in the answer to the purchase, and the payment executes last, after
  * the merchant has delivered. `async` — later, by a separate call, and the
  * payment executes at the moment of purchase. `confirm` — the merchant is
- * asked first, and the payment executes right after they say yes.
+ * asked first, and the payment executes right after they say yes. `ship` — a
+ * parcel the merchant hands to a carrier (ADR-0033): the payment executes at
+ * the moment of purchase, as in `async`, and the order carries the buyer's
+ * address until the merchant takes it on, or it ends without them.
  */
-export const FulfillmentSchema = z.enum(["sync", "async", "confirm"]).meta({
-    description: 'When the product reaches the agent, and so when the money moves. "sync" — in the answer to the purchase, payment last. "async" — later, by a separate call, payment at the moment of purchase. "confirm" — the merchant is asked first and the payment follows their yes. A card cannot be published as "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.',
+export const FulfillmentSchema = z.enum(["sync", "async", "confirm", "ship"]).meta({
+    description: 'When the product reaches the agent, and so when the money moves. "sync" — in the answer to the purchase, payment last. "async" — later, by a separate call, payment at the moment of purchase. "confirm" — the merchant is asked first and the payment follows their yes. "ship" — a parcel the merchant hands to a carrier, payment at the moment of purchase; the purchase carries the address it goes to. A card cannot be published as "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.',
 });
+/** The longest a parcel's card may give its merchant to hand it to a carrier: thirty days. */
+const SHIP_WITHIN_AT_MOST_SECONDS = 2_592_000;
 /**
  * How the price and availability of this card are asked for, if they are.
  *
@@ -118,8 +126,49 @@ const listedText = (what) => z
  * holds it is the merchants table, so this schema is the rule alone, applied
  * wherever a merchant's listing name is written down.
  */
-export const ServiceNameSchema = listedText("service name").meta({
-    description: "The name a seller is listed under in a discovery catalog. At most 32 characters of printable ASCII, because that is what the catalog carries; a name outside that is refused here rather than truncated there, where nobody would be told.",
+export const ServiceNameSchema = listedText("service name")
+    .superRefine((name, ctx) => {
+    // Every agent reads the name on every card and order of the merchant's
+    // (ADR-0034), so the door holds it to the card's own plain-text rule
+    // (ADR-0017): markup and character references are refused and named,
+    // not cleaned into words the merchant never wrote.
+    for (const phrase of notPlainTextIn(name, "one line")) {
+        ctx.addIssue({
+            code: "custom",
+            message: `this service name carries ${phrase}, and a service name is plain text, which an agent reads exactly as it is written`,
+        });
+    }
+})
+    .meta({
+    description: "The name a seller is listed under in a discovery catalog and shown to every agent beside their products. At most 32 characters of printable ASCII, because that is what the catalog carries; a name outside that is refused here rather than truncated there, where nobody would be told. It is plain text: HTML markup and character references such as & are refused, and an ampersand written as text passes.",
+});
+/**
+ * The name as it is stored and read back: every rule the door holds it to
+ * except that it is plain text.
+ *
+ * That rule belongs to the door and not to the reader, for the reason the
+ * card's own words give (ADR-0017): a name stored before the rule may carry
+ * markup, every answer is held to its contract on the way out, and one old row
+ * would fail every card and order of its merchant's instead of being put right
+ * the next time the merchant sets their name.
+ */
+const StoredServiceNameSchema = listedText("service name");
+/**
+ * Who sells, as an agent reads it beside a product and on an order: the name
+ * the merchant sells under and the site of their shop (ADR-0034).
+ *
+ * Both are the merchant's own word and nothing here checked either, which the
+ * description says to the reader who acts on it — a name and a site can be
+ * anybody's. Null is "none given": a merchant who gave no site has none here,
+ * and a name is missing only from an order whose merchant has since lost it.
+ */
+export const SellerSchema = z
+    .strictObject({
+    name: StoredServiceNameSchema.nullable(),
+    site: SellerSiteSchema.nullable(),
+})
+    .meta({
+    description: "Who sells: the name the merchant sells under and the https address of their shop's own site, both as the merchant gave them. Agentify did not check either, so a name and a site can be anybody's. The site is where to take what an order cannot answer — a parcel that did not arrive, a return, the shop's terms. Either is null where the merchant has given none.",
 });
 /**
  * The words a merchant puts on one product so an agent searching a catalog can
@@ -220,19 +269,31 @@ const DescriptionSchema = z
  * JSON Schema, so the same constraint goes into the metadata as
  * `minProperties`, where a generator can still see it.
  *
- * One schema, used by the published card and by the projection below, because
+ * One rule, held by the published card and by the projection below, because
  * the promise is the same one: what the agent reads before paying is what the
  * merchant is held to afterwards. Two copies of a refinement would be two
- * promises, and the export would carry whichever was edited last.
+ * promises, and the export would carry whichever was edited last. The two
+ * declarations it is put on differ only in what else a field may carry: the
+ * merchant's is closed, and the agent's takes what is added later
+ * (ADR-0006 §5).
  */
-const DeclaredResultSchema = ParamSpecSchema.refine(
+const declaringAResult = (declaration) => declaration
+    .refine(
 // Not merely non-empty: at least one field that actually arrives. A
 // declaration of one field marked `required: false` satisfies "at least
 // one" and promises the agent exactly as much as an empty one does.
-(spec) => Object.values(spec).some((field) => field.required !== false), "a card declares at least one field of what the agent receives, and at least one of them arrives every time").meta({
+(spec) => Object.values(spec).some((field) => field.required !== false), "a card declares at least one field of what the agent receives, and at least one of them arrives every time")
+    .meta({
     description: "What the agent receives on delivery. At least one field, and at least one of the fields is not marked required: false — a result that might be entirely absent promises nothing.",
     minProperties: 1,
 });
+const DeclaredResultSchema = declaringAResult(ParamSpecSchema);
+/**
+ * A declaration as an agent reads it: the merchant's fields, each open to what
+ * is added to a field later (ADR-0006 §5), so a new attribute of one field
+ * leaves the card readable to an agent built before it.
+ */
+const ReadDeclarationSchema = z.record(ParamNameSchema, FieldSpecSchema.loose());
 /**
  * The short forms a card may be written in, and the one form they all become.
  *
@@ -355,11 +416,15 @@ const CardFieldsSchema = z.strictObject({
      * says so, or a generated client would first meet the rule as a refusal.
      */
     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.',
+        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. On a "ship" card it is the goods without shipping: the price a purchase goes through at is the merchant\'s price handler\'s answer, which includes shipping to the buyer\'s place.',
     }),
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
     params: writtenShort(ParamSpecSchema).optional(),
-    result: writtenShort(DeclaredResultSchema),
+    /**
+     * What the agent receives. Every card declares it except a parcel's, whose
+     * mode fixes it: the record of the parcel's shipment (ADR-0033).
+     */
+    result: writtenShort(DeclaredResultSchema).optional(),
     /**
      * Words for an agent searching a discovery catalog. Absent on a card whose
      * merchant named none, and never invented for them.
@@ -389,6 +454,16 @@ const CardFieldsSchema = z.strictObject({
     confirm_deadline_seconds: z.int().positive().optional(),
     /** How long the merchant may take to deliver an order it has accepted. */
     fulfill_deadline_seconds: z.int().positive().optional(),
+    /**
+     * On a parcel's card, how long the merchant may take to hand it to a carrier,
+     * counted from the charge (ADR-0033). A name of its own rather than the
+     * delivery deadline's, because on an asynchronous card that number is the
+     * time to deliver, and a number read under the wrong name tells a person
+     * their parcel arrives when it merely leaves. The ceiling is thirty days, the
+     * longest the marketplaces give a seller, and it bounds how long a buyer's
+     * money sits with a merchant before the order becomes a refund owed.
+     */
+    ship_within_seconds: z.int().positive().max(SHIP_WITHIN_AT_MOST_SECONDS).optional(),
 });
 /**
  * Both deadlines are shown to the agent before it pays, which is why a card
@@ -419,8 +494,8 @@ const cardRules = (card, ctx) => {
         // card that has one problem, and lifting the gate later would uncover it.
         return;
     }
-    // Past the gate only "sync" and "async" remain, and neither is ever asked to
-    // confirm — which is why this needs no test on the mode of its own.
+    // Past the gate no mode is ever asked to confirm — which is why this needs no
+    // test on the mode of its own.
     if (card.confirm_deadline_seconds !== undefined) {
         ctx.addIssue({
             code: "custom",
@@ -428,6 +503,24 @@ const cardRules = (card, ctx) => {
             message: `only a card with fulfillment "confirm" is asked to confirm; this one is "${card.fulfillment}"`,
         });
     }
+    if (card.fulfillment === "ship") {
+        parcelRules(card, ctx);
+        return;
+    }
+    if (card.ship_within_seconds !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ship_within_seconds"],
+            message: `only a card with fulfillment "ship" hands its goods to a carrier and names a time to ship; this one is "${card.fulfillment}"`,
+        });
+    }
+    if (card.result === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["result"],
+            message: 'result is required: a card declares what the agent receives, and only a parcel\'s, fulfillment "ship", leaves that to its mode',
+        });
+    }
     if (card.fulfillment === "sync" && card.fulfill_deadline_seconds !== undefined) {
         ctx.addIssue({
             code: "custom",
@@ -436,12 +529,62 @@ const cardRules = (card, ctx) => {
         });
     }
 };
+/**
+ * What a parcel's card is held to (ADR-0033), beside what every card is.
+ *
+ * Each rule is about a word an agent or a merchant would otherwise read wrong.
+ * The time to ship is required because it is the one promise the agent is
+ * given about when the goods leave. A result is refused because the mode fixes
+ * it — the record of the shipment — and one a merchant declared would be a
+ * second promise beside it. A delivery deadline is refused because the number
+ * would read as the time the parcel arrives. The price is the merchant's
+ * handler's to answer, because shipping depends on where the parcel goes, and
+ * only the merchant knows what it costs to send it there. And the address is
+ * not one of the card's parameters, because it travels in its own block.
+ */
+const parcelRules = (card, ctx) => {
+    if (card.ship_within_seconds === undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["ship_within_seconds"],
+            message: `a parcel's card names ship_within_seconds, the time to hand it to a carrier counted from the charge, at most ${SHIP_WITHIN_AT_MOST_SECONDS} (thirty days)`,
+        });
+    }
+    if (card.result !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["result"],
+            message: "a parcel's card declares no result: its mode fixes what the agent receives, the record of the parcel's shipment",
+        });
+    }
+    if (card.fulfill_deadline_seconds !== undefined) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["fulfill_deadline_seconds"],
+            message: "a parcel's card names the time to ship, ship_within_seconds, and no delivery deadline: under that name the number would read as the time the parcel arrives",
+        });
+    }
+    if (card.price_check !== "handler") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["price_check"],
+            message: "a parcel's price is asked of the merchant's own price handler, price_check: \"handler\", whose answer is the whole price with shipping to the buyer's place",
+        });
+    }
+    if (card.params !== undefined && "ship_to" in card.params) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["params", "ship_to"],
+            message: "a parcel's card asks for no ship_to among its parameters: the address travels in a block of its own beside them",
+        });
+    }
+};
 // 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.';
+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. result is required on every card except one whose fulfillment is "ship". A "ship" card, a parcel, names ship_within_seconds and is the only card that may; it declares no result and no fulfill_deadline_seconds, its price_check is "handler", and it asks for no ship_to among its params, because the purchase carries the address in a block 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.
@@ -546,8 +689,12 @@ export const CardSchema = CardFieldsSchema.superRefine(cardRules)
  * place that picks.
  */
 export const purchaseCheckFor = (card) => paramSpecToValidator(card.params ?? {}, "purchase");
-/** The check this card's delivery is held to. */
-export const deliveryCheckFor = (card) => paramSpecToValidator(card.result, "delivery");
+/**
+ * The check this card's delivery is held to: the goods its `result` declared,
+ * or for a parcel, which is not delivered with goods at all, its shipment
+ * (ADR-0033).
+ */
+export const deliveryCheckFor = (card) => card.result === undefined ? ShipmentSchema : paramSpecToValidator(card.result, "delivery");
 /**
  * The fields of a card as an agent reads it in a catalog.
  *
@@ -571,11 +718,16 @@ export const deliveryCheckFor = (card) => paramSpecToValidator(card.result, "del
  * gateway's, and this document does not claim to know it.
  *
  * Both deadlines stay, because they are the merchant's promise to the agent
- * about how long it may wait, and the agent is told them before it pays. They
- * sit on the modes that have them, as branches of a union rather than as a
- * rule attached to one object: JSON Schema cannot say "this field only when
- * that one has this value", and zod drops such a rule without a word, so as
- * branches the constraint crosses whole into the export.
+ * about how long it may wait, and the agent is told them before it pays. The
+ * projection writes each only on a mode that has it, and the document says so
+ * in words rather than as structure: it takes fields added later (ADR-0006
+ * §5), so a field an agent does not expect is one it ignores, not one it can
+ * refuse.
+ *
+ * The mode is a word whose known values are listed beside it, for the same
+ * reason. The storefront has no version, so a mode added later reaches agents
+ * that still hold this contract, and to them it has to be a card to pass over
+ * rather than a catalog they cannot read.
  *
  * `as_of` is added: the moment the price shown here was published. A price
  * with no moment behind it cannot be judged stale, and this is the only
@@ -588,27 +740,28 @@ export const deliveryCheckFor = (card) => paramSpecToValidator(card.result, "del
  * page — so carrying them here would put a foreign catalog's constraint in
  * front of a reader who has no use for it.
  *
- * One thing an agent might reasonably want is not here, and saying so is
- * better than leaving it to be discovered: nothing in this document names who
- * is selling. There is a shape in this contract for one name a seller carries —
- * `ServiceNameSchema`, the name a discovery catalog lists them under — and it
- * is deliberately not this. That name exists to satisfy one channel's rules,
- * a merchant may have none, and standing it in for a public identity would
- * answer a question — who "we" are to the buyer, and who the merchant is —
- * that is still open.
+ * Who sells is here as the merchant gave it, a name and the site of their
+ * shop (ADR-0034), and as nothing more: no profile, no contact of ours, and no
+ * claim that either was checked. Who "we" are to the buyer is a question this
+ * document still does not answer.
  */
-const PublicCardFieldsSchema = z.strictObject({
+export const PublicCardSchema = z
+    .looseObject({
     /** Our catalog identifier, the one a purchase, a receipt and a status use. */
     id: IdentifierSchema,
     title: TitleSchema,
     description: DescriptionSchema,
     /** The price in the catalog: what an agent compares when it is choosing. */
-    price: MoneySchema,
+    price: MoneySchema.loose(),
     /** When the price above was published. */
     as_of: TimestampSchema,
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
-    params: ParamSpecSchema.optional(),
-    result: DeclaredResultSchema,
+    params: ReadDeclarationSchema.optional(),
+    /**
+     * What the agent receives. Absent on a parcel, whose mode fixes it: the
+     * record of the parcel's shipment.
+     */
+    result: declaringAResult(ReadDeclarationSchema).optional(),
     /**
      * Whether the merchant is asked for this product's price and availability at
      * the moment of purchase, so the sale may go through at a price other than
@@ -619,30 +772,36 @@ const PublicCardFieldsSchema = z.strictObject({
      * about to move, read as true it distrusts a price that never moves.
      */
     price_checked_at_purchase: z.boolean(),
-});
-export const PublicCardSchema = z
-    .discriminatedUnion("fulfillment", [
-    // Synchronous: the product arrives in the answer to the purchase, inside our
-    // own response budget — one number for every product on the platform, which
-    // is why no card names it and no card may name a delivery deadline instead.
-    PublicCardFieldsSchema.extend({ fulfillment: z.literal("sync") }),
-    // Asynchronous: the money moves at the purchase and the product comes later,
-    // within the merchant's own delivery deadline where they set one.
-    PublicCardFieldsSchema.extend({
-        fulfillment: z.literal("async"),
-        fulfill_deadline_seconds: z.int().positive().optional(),
-    }),
-    // With confirmation: the merchant is asked first and the payment follows
-    // their yes, so both waits exist. No card can be published in this mode
-    // during the pilot; the branch is here because the mode is in the
-    // vocabulary, and a branch missing from a projection would be a second gate
-    // in a second place for whoever lifts the first one.
-    PublicCardFieldsSchema.extend({
-        fulfillment: z.literal("confirm"),
-        confirm_deadline_seconds: z.int().positive().optional(),
-        fulfill_deadline_seconds: z.int().positive().optional(),
-    }),
-])
+    /**
+     * Who sells this product, in the merchant's own words and unchecked. It is
+     * read with the catalog rather than copied onto the card at publishing, so
+     * a merchant who changes their name or gives a site is found by it on every
+     * card they already sell.
+     */
+    seller: SellerSchema.loose(),
+    /**
+     * How the product is sold: "sync", "async" or "confirm" today, and a word
+     * added later reaches this same document. A reader keeps a default arm,
+     * and a card whose mode it does not know is one to pass over.
+     *
+     * Two branches rather than a bare string, so the known values cross into
+     * the exported document as a list a client can switch over, beside the
+     * branch that reads any other word (`OpenWordSchema`). A declared field's
+     * type, inside params and result, stays a closed list: a card with a type
+     * a reader does not know is one it cannot fill in, and it is passed over
+     * like a card of an unknown mode.
+     */
+    fulfillment: z.union([FulfillmentSchema, OpenWordSchema]),
+    /** On "async" and "confirm": how long the merchant has to deliver, in seconds. */
+    fulfill_deadline_seconds: z.int().positive().optional(),
+    /** On "confirm": how long the merchant has to say yes, in seconds. */
+    confirm_deadline_seconds: z.int().positive().optional(),
+    /**
+     * On "ship": how long the merchant has to hand the parcel to a carrier,
+     * counted from the charge, in seconds. When it leaves, not when it arrives.
+     */
+    ship_within_seconds: z.int().positive().optional(),
+})
     .meta({
     // Everything below is written in prose above as well, and it has to be
     // written twice: the reader this matters most to is the one holding the
@@ -650,7 +809,7 @@ export const PublicCardSchema = z
     // money on what this card claims. `as_of` in particular means something
     // narrower here than the same name means elsewhere in this contract, and a
     // reader who assumed otherwise would trust a stale number.
-    description: "A product an agent can buy, projected from the card its merchant published. as_of is when the price shown here was published, and nothing more: on a card whose price is checked at purchase it says nothing about how fresh that check will be — elsewhere in this contract the same name means the moment a live answer was true. price_checked_at_purchase says the merchant is asked for a price at the moment of purchase, not that they answer; what happens when they are silent depends on the mode and belongs to the gateway. The number above is what an agent compares when choosing and may not be what the sale goes through at. Two rules hold beyond the shape: a synchronous product names no delivery deadline, because it is delivered inside a response budget that is the same for every product on the platform, and only a product whose merchant is asked to confirm names a confirmation deadline. No field here names who is selling: this contract has no shape for a merchant's public identity.",
+    description: "A product an agent can buy, projected from the card its merchant published. as_of is when the price shown here was published, and nothing more: on a card whose price is checked at purchase it says nothing about how fresh that check will be — elsewhere in this contract the same name means the moment a live answer was true. price_checked_at_purchase says the merchant is asked for a price at the moment of purchase, not that they answer; what happens when they are silent depends on the mode and belongs to the gateway. The number above is what an agent compares when choosing and may not be what the sale goes through at. Three rules hold beyond the shape: a synchronous product names no delivery deadline, because it is delivered inside a response budget that is the same for every product on the platform; only a product whose merchant is asked to confirm names a confirmation deadline; and a parcel, fulfillment \"ship\", names ship_within_seconds — the time to hand it to a carrier counted from the charge, not the time it arrives — and no result, because what the agent receives is the record of its shipment, while every other product names a result. On a parcel the price shown is the goods without shipping, and the purchase goes through at the merchant's answer for the whole, shipping to the buyer's place included. seller is who sells, as the merchant gave it: Agentify did not check the name or the site. fulfillment is a word whose known values are listed beside it, and more may be added: a reader keeps a default arm, and a card whose mode it does not know is one to pass over, not a reason to stop reading the catalog. This document and every part inside it may also gain fields; a reader ignores the ones it does not know. The type of a declared field in params and result is a closed list, and a card with a type a reader does not know is one to pass over too.",
 });
 /**
  * The card as an agent reads it, built from the card the merchant published.
@@ -662,18 +821,20 @@ export const PublicCardSchema = z
  * every agent by default, and the first anybody heard of it would be a
  * merchant's pricing address in a public catalog.
  *
- * The two things the card cannot know are passed in: the catalog identifier we
- * issued when it was published, and the moment its price was published.
+ * The three things the card cannot know are passed in: the catalog identifier
+ * we issued when it was published, the moment its price was published, and
+ * who sells it as their merchant stands now.
  */
 export const publicCardOf = (card, issued) => {
     const common = {
         id: issued.id,
+        seller: issued.seller,
         title: card.title,
         description: card.description,
         price: card.price,
         as_of: issued.as_of,
         ...(card.params === undefined ? {} : { params: card.params }),
-        result: card.result,
+        ...(card.result === undefined ? {} : { result: card.result }),
         price_checked_at_purchase: card.price_check !== undefined,
     };
     switch (card.fulfillment) {
@@ -698,6 +859,14 @@ export const publicCardOf = (card, issued) => {
                     ? {}
                     : { fulfill_deadline_seconds: card.fulfill_deadline_seconds }),
             };
+        case "ship":
+            return {
+                ...common,
+                fulfillment: "ship",
+                ...(card.ship_within_seconds === undefined
+                    ? {}
+                    : { ship_within_seconds: card.ship_within_seconds }),
+            };
     }
 };
 /**
@@ -732,9 +901,40 @@ const exampleOf = (spec) => Object.fromEntries(Object.entries(spec).map(([name,
  * inside another schema, so that one line is dropped here.
  */
 const purchaseBodySchemaOf = (card) => {
-    const { $schema, ...body } = z.toJSONSchema(z.strictObject({ params: purchaseCheckFor(card) }));
+    const { $schema, ...body } = z.toJSONSchema(z.strictObject({
+        params: purchaseCheckFor(card),
+        // A parcel's purchase carries the address it goes to beside its
+        // parameters, and is refused without one (ADR-0032).
+        ...(card.fulfillment === "ship" ? { ship_to: ShipToSchema } : {}),
+    }));
     return body;
 };
+/**
+ * Where a parcel goes, in a listing's example purchase: Agentify's own office
+ * (ADR-0033), with the number taken out of it, so that the example is a real
+ * place and nobody's home.
+ */
+const LISTED_SHIP_TO = {
+    name: "Agentify",
+    line_one: "Jl. Raya Kediri, Beraban",
+    line_two: "Nuanu Creative City",
+    city: "Tabanan",
+    state: "BA",
+    postal_code: "82121",
+    country: "ID",
+    phone_number: "+62 000 0000 0000",
+};
+/**
+ * A recorded shipment, in a listing's example output, written as every other
+ * example here is: each field standing for what goes there, and the instant
+ * at the start of the clock rather than a date that looks like one somebody
+ * shipped on.
+ */
+const LISTED_SHIPMENT = {
+    carrier: "string",
+    tracking_number: "string",
+    shipped_at: "1970-01-01T00:00:00Z",
+};
 /**
  * The card as a discovery catalog reads it.
  *
@@ -754,9 +954,14 @@ export const bazaarDeclarationOf = (card, listed) => ({
         ...(listed.serviceName === null ? {} : { serviceName: listed.serviceName }),
         ...(card.tags === undefined ? {} : { tags: card.tags }),
     },
-    input: { params: exampleOf(card.params ?? {}) },
+    input: {
+        params: exampleOf(card.params ?? {}),
+        ...(card.fulfillment === "ship" ? { ship_to: LISTED_SHIP_TO } : {}),
+    },
     inputSchema: purchaseBodySchemaOf(card),
-    output: { example: exampleOf(card.result) },
+    // What the agent is finally handed: the goods the card declared, or for a
+    // parcel the record of its shipment.
+    output: { example: card.result === undefined ? LISTED_SHIPMENT : exampleOf(card.result) },
 });
 /**
  * One card as the merchant who published it reads it back.

package/dist/envelope.d.ts

@@ -73,12 +73,35 @@ export declare const WORKER_ENVELOPE_PAYLOADS: Readonly<{
             as_of: z.ZodISODateTime;
         }, z.core.$strict>;
         price_id: z.ZodOptional<z.ZodString>;
+        ship_to: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            line_one: z.ZodString;
+            line_two: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            postal_code: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            phone_number: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            erased_at: z.ZodISODateTime;
+        }, z.core.$strict>]>>;
         test: z.ZodBoolean;
     }, z.core.$strict>;
     /** "How much is this and is it there", asked before a sale goes through. */
     readonly quote_request: z.ZodObject<{
         merchant_item_id: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        ship_to: z.ZodOptional<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         price_id: z.ZodString;
         purpose: z.ZodEnum<{
             purchase: "purchase";
@@ -128,6 +151,23 @@ export declare const WorkerEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             as_of: z.ZodISODateTime;
         }, z.core.$strict>;
         price_id: z.ZodOptional<z.ZodString>;
+        ship_to: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            line_one: z.ZodString;
+            line_two: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            postal_code: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            phone_number: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            erased_at: z.ZodISODateTime;
+        }, z.core.$strict>]>>;
         test: z.ZodBoolean;
     }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
@@ -137,6 +177,12 @@ export declare const WorkerEnvelopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     payload: z.ZodObject<{
         merchant_item_id: z.ZodString;
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        ship_to: z.ZodOptional<z.ZodObject<{
+            country: z.ZodString;
+            state: z.ZodOptional<z.ZodString>;
+            city: z.ZodString;
+            postal_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         price_id: z.ZodString;
         purpose: z.ZodEnum<{
             purchase: "purchase";