@nuanu-ai/agentify-contracts 0.5.0 → 0.7.0

package/dist/card.js

@@ -25,8 +25,9 @@
  * more shape to keep in step for no gain to anybody.
  */
 import { z } from "zod";
-import { ParamSpecSchema, paramSpecToValidator } from "./param-spec.js";
-import { IdentifierSchema, MoneySchema, TimestampSchema } from "./primitives.js";
+import { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, paramSpecToValidator, } from "./param-spec.js";
+import { notPlainTextIn } from "./plain-text.js";
+import { IdentifierSchema, MoneySchema, OpenWordSchema, TimestampSchema } from "./primitives.js";
 import { SellingStateSchema } from "./selling.js";
 /**
  * When the product reaches the agent, and therefore when the money moves.
@@ -117,8 +118,86 @@ 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");
+/** What a seller's site is held to, said once for the refusal and the description. */
+const SITE_FORM = "a seller's site is https:// and the domain name of their shop, with nothing after it — https://shop.example: in lower case, a domain name rather than an IP address or a single word, with no path, query, fragment, port, credentials or trailing slash";
+/**
+ * The address of a seller's own shop on the web, where an agent takes what an
+ * order cannot answer (ADR-0034).
+ *
+ * Only an https origin, because anything after the host — a path, a query, a
+ * fragment — would be text of the merchant's own reaching every agent that
+ * reads the card, which is the free text the decision refuses. The host is the
+ * one part the merchant writes, so it is held to a domain name too: labels of
+ * letters, digits and hyphens, at most 253 characters, ending in a zone of
+ * letters or a punycode one. Anything a URL parser keeps as written would
+ * otherwise pass — a sentence of instructions, a quote, a host of any length —
+ * and so would a single word or an IP address, which point other people's
+ * agents into somebody's own network. What the pattern cannot do is tell a
+ * public name from a private one: a name in a zone kept for local networks,
+ * or a public one whose address leads into one, passes, and so does a
+ * hyphenated sentence of up to 253 characters that is a valid name. That is
+ * why an agent is told, beside every site, that nobody checked it.
+ *
+ * The pattern says all that in a form the JSON Schema export keeps, and it
+ * stops the check where it fails, so an address copied with a slash at the end
+ * is told once. Asking the URL parser for the origin catches what the pattern
+ * leaves, such as a punycode label the parser would write differently.
+ */
+export const SellerSiteSchema = z
+    .string()
+    .regex(/^https:\/\/(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/, { message: SITE_FORM, abort: true })
+    .refine((site) => {
+    try {
+        return new URL(site).origin === site;
+    }
+    catch {
+        return false;
+    }
+}, SITE_FORM)
+    .meta({ description: `The https origin of a seller's own shop: ${SITE_FORM}.` });
+/**
+ * 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
@@ -219,19 +298,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.
  *
@@ -348,8 +439,14 @@ const CardFieldsSchema = z.strictObject({
      *
      * Written as the two fields, or as the one string that becomes them. What is
      * stored and what an agent reads are the two fields either way.
+     *
+     * Publishing holds it to the price rule in `price-rule.ts`, outside this
+     * schema so that a card stored before the rule stays readable; the export
+     * says so, or a generated client would first meet the rule as a refusal.
      */
-    price: CardPriceSchema,
+    price: CardPriceSchema.meta({
+        description: 'Publishing refuses a price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot ("5.00", "0.001"), so that a price the catalog shows is one a payment can be taken at.',
+    }),
     /** What the agent has to supply to buy. Absent when the purchase needs no input. */
     params: writtenShort(ParamSpecSchema).optional(),
     result: writtenShort(DeclaredResultSchema),
@@ -390,7 +487,7 @@ const CardFieldsSchema = z.strictObject({
  * wait for a synchronous answer is our system-wide budget, the same for every
  * product, so it has no field here at all.
  */
-export const CardSchema = CardFieldsSchema.superRefine((card, ctx) => {
+const cardRules = (card, ctx) => {
     if (card.fulfillment === "confirm") {
         // The gate, and the reason it is a refusal rather than a note somewhere.
         // A confirmation request reaches the merchant before any money moves and
@@ -428,13 +525,106 @@ export const CardSchema = CardFieldsSchema.superRefine((card, ctx) => {
             message: 'a synchronous card delivers inside the system-wide response budget and sets no delivery deadline; "async" and "confirm" do',
         });
     }
-}).meta({
-    // JSON Schema has no way to say "this field only when that one has this
-    // value", and zod drops the rules above when it renders a document. Left at
-    // that, an engineer generating a client from the export would build one that
-    // sends deadlines a card cannot carry and only find out on the first publish.
-    // Saying it in words is weaker than checking it, and better than silence.
-    description: 'A product in the catalog, as the merchant publishes it. Three rules are enforced beyond the shape below. A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own. This document describes the card as it is stored and read back; three fields also take a shorter spelling at publication, which JSON Schema has no way to show alongside the canonical one. price may be written as one string, the amount and the currency code with a single space between them ("5.00 USD"). A field of params or result may be written as its type word alone (access_url: "string") where it carries no title and no required flag. fulfillment may be left out, and a card that leaves it out is "sync". Each of those is opened out into the form below as the card is accepted, so a card generated from this document is accepted unchanged and a card read back is always in this form.',
+};
+// JSON Schema has no way to say "this field only when that one has this
+// value", and zod drops the rules above when it renders a document. Left at
+// that, an engineer generating a client from the export would build one that
+// sends deadlines a card cannot carry and only find out on the first publish.
+// Saying it in words is weaker than checking it, and better than silence.
+const CARD_RULES_IN_WORDS = 'A card cannot be published as fulfillment "confirm" during the pilot: the confirmation request has no shape on the wire yet, so a handler could not tell one from a paid order. confirm_deadline_seconds is only allowed when fulfillment is "confirm", and fulfill_deadline_seconds only when fulfillment is "async" or "confirm" — a synchronous card delivers inside the system-wide response budget and names no deadline of its own.';
+/**
+ * The words on a card that an agent reads: the title, the description, and
+ * the title of each field the card declares.
+ *
+ * It reads whatever arrived rather than a card known to be whole, because the
+ * rule runs beside the shape checks and not after them — a merchant told about
+ * a price first and about their markup on the next attempt fixes one thing per
+ * publish. So anything that is not where a card keeps its words is passed over
+ * here and named by the shape check instead.
+ */
+const wordsOf = (card) => {
+    if (!isRecord(card))
+        return [];
+    const words = [];
+    if (typeof card.title === "string") {
+        words.push({ path: ["title"], text: card.title, called: "title", lines: "one line" });
+    }
+    if (typeof card.description === "string") {
+        words.push({
+            path: ["description"],
+            text: card.description,
+            called: "description",
+            lines: "several lines",
+        });
+    }
+    for (const declaration of ["params", "result"]) {
+        const fields = card[declaration];
+        if (!isRecord(fields))
+            continue;
+        for (const [name, field] of Object.entries(fields)) {
+            if (isRecord(field) && typeof field.title === "string") {
+                words.push({
+                    path: [declaration, name, "title"],
+                    text: field.title,
+                    called: "title",
+                    lines: "one line",
+                });
+            }
+        }
+    }
+    return words;
+};
+/**
+ * The card's words are plain text, and a finding for each kind of thing in them
+ * that is not (see `plain-text.ts` for what counts and why the door refuses
+ * rather than cleans).
+ *
+ * Each finding names the field, what was found in it and where, and what the
+ * field is held to. The sentence is written for the merchant who has to find
+ * the characters in their own editor, which is why it quotes the fragment and
+ * counts the position rather than printing the rule.
+ */
+const plainWords = (card, ctx) => {
+    for (const words of wordsOf(card)) {
+        const heldTo = words.lines === "one line"
+            ? `a ${words.called} is plain text on one line`
+            : `a ${words.called} is plain text`;
+        for (const phrase of notPlainTextIn(words.text, words.lines)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [...words.path],
+                message: `this ${words.called} carries ${phrase}, and ${heldTo}, which an agent reads exactly as it is written`,
+            });
+        }
+    }
+};
+const PLAIN_TEXT_IN_WORDS = "The title, the description and the title of every declared field are plain text, which an agent reads exactly as it is written: a card is refused where one of them carries HTML markup (a tag, or the opening of a comment), an HTML character reference such as & or ’, or a control character, and a description alone may carry line feeds. An ampersand, a comparison or an arrow written as text passes.";
+/**
+ * The card as it is stored and as its merchant reads it back: every rule a
+ * publish holds it to except that its words are plain text.
+ *
+ * That one rule belongs to the door and not to the reader. A card stored
+ * before it may carry markup, and every answer that carries a stored card is
+ * held to its contract on the way out — so holding a stored card to the rule
+ * would fail the merchant's whole list, and the page of the catalog it sits
+ * on, over one old row, and the merchant could not even see the card they were
+ * meant to republish.
+ */
+const StoredCardSchema = CardFieldsSchema.superRefine(cardRules).meta({
+    description: `A product in the catalog, as it is stored and as its merchant reads it back. Three rules hold beyond the shape below. ${CARD_RULES_IN_WORDS} A publish also holds the title, the description and each declared field's title to plain text; reading a card back does not, so a card stored before that rule is read back exactly as it was stored.`,
+});
+/**
+ * A card as a merchant publishes it.
+ *
+ * The plain-text rule runs whatever else is wrong with the card, so a merchant
+ * hears about their markup in the same answer as about their price. The rules
+ * that compare one field with another run only once the shape is right, as
+ * they always have: they need the fields to be what they claim to be.
+ */
+export const CardSchema = CardFieldsSchema.superRefine(cardRules)
+    .superRefine(plainWords, { when: () => true })
+    .meta({
+    description: `A product in the catalog, as the merchant publishes it. Four rules are enforced beyond the shape below. ${CARD_RULES_IN_WORDS} ${PLAIN_TEXT_IN_WORDS} The shape below is the canonical card, the form every card is stored and read back in; three fields also take a shorter spelling at publication, which JSON Schema has no way to show alongside the canonical one. price may be written as one string, the amount and the currency code with a single space between them ("5.00 USD"). A field of params or result may be written as its type word alone (access_url: "string") where it carries no title and no required flag. fulfillment may be left out, and a card that leaves it out is "sync". Each of those is opened out into the form below as the card is accepted, so a card generated from this document is accepted unchanged and a card read back is always in this form.`,
 });
 /**
  * The check an agent's purchase parameters are held to, for this card.
@@ -471,11 +661,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
@@ -488,27 +683,24 @@ 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(),
+    result: declaringAResult(ReadDeclarationSchema),
     /**
      * 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
@@ -519,30 +711,31 @@ 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(),
+})
     .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
@@ -550,7 +743,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. 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. 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.
@@ -562,12 +755,14 @@ 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,
@@ -688,8 +883,11 @@ export const MerchantCardSchema = z
     id: IdentifierSchema,
     /** When this version of the card was published. */
     as_of: TimestampSchema,
-    /** The card exactly as its merchant published it. */
-    card: CardSchema,
+    /**
+     * The card exactly as its merchant published it, held to the rules of a
+     * stored card rather than to the publish door's.
+     */
+    card: StoredCardSchema,
     /** What a purchase of this card meets right now. */
     selling: SellingStateSchema,
     /** Whether the pause is this card's own, rather than the whole catalog's. */