@nuanu-ai/agentify-contracts 0.5.0 → 0.6.0

package/dist/api.js

@@ -897,7 +897,7 @@ export const API_ROUTES = Object.freeze({
         method: "POST",
         path: "/v0/quotes/:price_id/answer",
         auth: "merchant_key",
-        description: "The price and availability for a question that came off the worker stream, against the price_id that question carried. The acknowledgement says whether the answer arrived in time to price the purchase; when it did not, stock held against the question can be released.",
+        description: "The price and availability for a question that came off the worker stream, against the price_id that question carried. The acknowledgement says whether the answer arrived in time to price the purchase; when it did not, stock held against the question can be released. A price that is zero, not in USD or USDC, or written with fewer than two or more than six digits after the dot is refused as malformed_body with the reason as its message, and the question stays open for a corrected answer.",
         request: QuoteResponseSchema,
         response: { document: QuoteAnswerAckSchema },
     },

package/dist/card.d.ts

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

package/dist/card.js

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

package/dist/index.d.ts

@@ -41,6 +41,9 @@ export type { OrderStatus } from "./order-status.js";
 export { ORDER_STATUSES, OrderStatusSchema } from "./order-status.js";
 export type { FieldSpec, FieldSpecInput, ParamSpec, ParamSpecDirection, ParamSpecInput, ParamType, } from "./param-spec.js";
 export { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, PROTOTYPE_KEY_IS_DROPPED, paramSpecToValidator, } from "./param-spec.js";
+export type { TextLines } from "./plain-text.js";
+export { notPlainTextIn } from "./plain-text.js";
+export { PAYABLE_CURRENCIES, PAYABLE_DECIMALS, priceProblemsOf } from "./price-rule.js";
 export type { Amount, CurrencyCode, Identifier, Money, SalePrice, Timestamp, } from "./primitives.js";
 export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export type { QuotePurpose, QuoteRequest, QuoteResponse } from "./quote.js";

package/dist/index.js

@@ -46,6 +46,8 @@ export { CabinetKeySchema, DisabledKeySchema, ForgottenCabinetKeySchema, IssuedK
 export { OrderSchema } from "./order.js";
 export { ORDER_STATUSES, OrderStatusSchema } from "./order-status.js";
 export { FieldSpecSchema, ParamNameSchema, ParamSpecSchema, ParamTypeSchema, PROTOTYPE_KEY_IS_DROPPED, paramSpecToValidator, } from "./param-spec.js";
+export { notPlainTextIn } from "./plain-text.js";
+export { PAYABLE_CURRENCIES, PAYABLE_DECIMALS, priceProblemsOf } from "./price-rule.js";
 export { AmountSchema, CurrencyCodeSchema, IdentifierSchema, MoneySchema, SalePriceSchema, TimestampSchema, } from "./primitives.js";
 export { QuotePurposeSchema, QuoteRequestSchema, QuoteResponseSchema } from "./quote.js";
 export { ReceiptOutcomeSchema, ReceiptSchema } from "./receipt.js";

package/dist/plain-text.d.ts

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

package/dist/plain-text.js

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

package/dist/price-rule.d.ts

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

package/dist/price-rule.js

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

package/dist/primitives.d.ts

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

package/dist/primitives.js

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

package/dist/quote.js

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

package/package.json

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