## Problem/Motivation `PaymentClientInterface` is named for the caller's side on the claim that a consumer holding it could be handed a client of a kessai running somewhere else without changing a line. Nothing made that true. A consumer could create a payment and settle it, and could not **find** one. So every consumer went around the contract into kessai's own table: yoyaku wrote the same query by hand in nine places, orchestra added two base fields to `kessai_payment` and swapped its storage schema to index one of them. All of it worked, and all of it only ever works while the consumer and the engine share a database. The contract also asked for things only a local caller can hand over: a loaded entity as the subject, a storage query builder as the answer to "which payments carry a token". And a consumer had to declare a dependency on the engine, because the contract module shipped no services: depending on it alone left every injected client unbound. So installing any consumer put an engine on the site - including the site whose payments are settled elsewhere, which is the one site that must not have one. ## Proposed resolution Give the contract everything a consumer needs, so that reaching past it is never the answer. **What a caller hands over is values.** `create()` takes a `PaymentRequest`, naming its amount, currency, account, kind, subject, deadline, whether to keep a reusable token, and whatever the consumer wants remembered. The subject is a `PaymentSubject`: two strings, not an entity, because a request naming a loaded entity could only be made by a caller sharing this database. **One finder.** `findPayments()` takes a `PaymentQuery` describing the payments wanted: the subject, or a subject type alone where the question is about every order of a kind rather than one; the kind and the states; a token, exactly or at all; what the consumer remembered. Every field narrows and none widens, so a query naming nothing would be every payment on the site and is refused rather than answered. It answers newest first, because callers ask either for all of them or for the current one, and an unordered finder answers the second wrongly without saying so. **Payment metadata.** A consumer has things to say about a payment that kessai has no opinion on - which workflow step asked for it, which order line it pays. It says them as its own names and string values, which kessai stores, indexes and never reads. Written once, as the payment is created: what a consumer wants to recognize its payment by is what it knows when it asks for the payment, so nothing overwrites or forgets a name. Both directions are indexed - reading them off a payment in hand, and asking which payments carry a value, which is what an outcome arriving from a provider needs. **A consumer depends on the contract and never on an implementation.** `kessai` declares its own service name, built from whichever implementation announced itself with the `kessai_payment_client` tag. A consumer's container compiles on a site that has not chosen yet, and the refusal arrives when something first asks to take a payment. A tag rather than a name an implementation overwrites, because module service files load in installation order and an overwritten name has a winner decided by which module sorts later; the engine sits below the default priority so a client a site installed on purpose outranks it. The status report says, as an error, when a site has the contract and nothing behind it. Also on the contract, for the same reason: `isAwaitingProvider()`, so asking whether the payer is away at a provider no longer means holding the session and the secret a return is bound to; `getPayments()`, a consumer's way back from ids it stored; and `deletePayments()`, which takes each payment's claims, refunds and reversals with it. `getTokenPaymentsQuery()` is gone. It answered with a storage query builder, which is this site's own machinery rather than a value, and no kessai anywhere else could have handed one back. ## Remaining tasks The HTTP API and a `RemotePaymentClient` that proves the claim end to end. Everything above is what they need in order to exist; neither is built here. ## User interface changes A status-report error on a site that installs the contract and no implementation of it. ## API changes `PaymentClientInterface::create()` takes a `PaymentRequest`. `findPayments()` replaces `getTokenPaymentsQuery()`. `authorizeToken()` and `chargeToken()` take a `PaymentSubject` rather than an entity. `PaymentInterface` gains `isAwaitingProvider()` and `getMetadata()`. ## Data model changes A `kessai_payment_metadata` table, indexed by payment and by name and value together. Nothing on the payment itself. AI-Generated: Yes (Claude Code was used to help produce this change.)