@firedrill-tools/trolley 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Reload Tech Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,219 @@
+# @firedrill-tools/trolley
+
+A synthetic **Trolley payouts merchant account (sandbox mode)** for [Firedrill](https://firedrill.run). An agent that pays
+freelancers, creators or suppliers through Trolley's REST API v1 can run against this Tool instead of the real service:
+recipients, payout accounts, batches with FX quotes and processing, payments and balances behave statefully, with
+Trolley's JSON field names, page-number paging and `{ ok: false, errors: [...] }` error envelope.
+
+Nothing here contacts Trolley, a bank, PayPal, Venmo or a check printer. No money moves, no e-mail or webhook is sent,
+and no identity or tax verification happens. All state lives in the Firedrill world (SQLite, reset, virtual time,
+evidence); every operation computes its result from that state.
+
+It also ships a browser app, a recreation of the Trolley merchant dashboard that reads and writes the same records as the API routes (see "Browser app").
+
+## Install
+
+```sh
+firedrill tool add @firedrill-tools/trolley --install
+firedrill serve
+```
+
+A new world receives the starter data below and grants for all 24 operations. For an existing world, add the starter
+rows you need and grant the operations (`packageId: "trolley"`, operation ids from the table below) to your actors.
+
+Point your agent's Trolley client at the served HTTP binding (connection recipe `trolley-rest`):
+
+| client variable | Firedrill value |
+|---|---|
+| `TROLLEY_API_BASE_URL` | `FIREDRILL_HTTP_URL` |
+| `TROLLEY_ACCESS_TOKEN` | `FIREDRILL_HTTP_TOKEN` |
+
+Requests authenticate with `Authorization: prsign <token>` or `Authorization: Bearer <token>` (see Compatibility).
+
+## Identities and access
+
+A Trolley API key belongs to one merchant and is account-wide, so access is modelled with actor attributes, not row owners:
+
+| attribute | effect |
+|---|---|
+| `merchantId` | Optional. Must equal the seeded merchant id `M-4Lk9Qx2Rb7Tn3Vw8Yz1Ca6` (`meta/merchant.id`). A different value makes every operation answer **401 `invalid_api_key`**. |
+| `accessLevel` | Optional, `full` (default) or `read_only`. A `read_only` key may list, get and summarise; every create, update, delete, generate-quote and start-processing answers **403 `not_authorized`**. Any other value is `invalid_api_key`. |
+| `displayName` | Optional; not used by the backend. |
+
+**Fresh-install fallback:** an actor with neither attribute (as created by `firedrill tool add`) is the seeded merchant with
+full access. Framework grants still decide whether an actor may call an operation at all; a missing grant is a Firedrill
+denial (HTTP 403, rendered in Trolley's envelope with code `not_authorized`).
+
+## Starting data
+
+`starter.json` (and `firedrill/baseline.scenario.json`) seed 89 fictional rows at virtual time 2026-09-15T14:00:00Z for the
+merchant **Larkspur Creator Studio** (US, USD, sandbox). All names, e-mails (`@example.com`), phone numbers and bank data
+are invented; account numbers exist only as their last four digits.
+
+- `meta`: `merchant`, `counters` (`next: 1000`), `fx` (synthetic rates per USD: CAD 1.352, EUR 0.912, GBP 0.781,
+  AUD 1.498, MXN 17.24), `fees` (fixed fee and route minimum per payout method, in USD).
+- 3 balances: `paymentrails` USD 18,420.55 (primary), `paymentrails` CAD 2,150.00, `paypal` USD 640.00.
+- 14 recipients: 8 active (US ACH bank, US business paid by check, CA EFT bank with a second PayPal account and a disabled
+  former bank account, GB bank, DE IBAN bank, US PayPal, US Venmo, MX bank), 2 incomplete (no address; no payout method),
+  1 archived (same e-mail as a newer active recipient), 1 suspended, 1 compliance-blocked, 1 disabled.
+- 11 batches (two pages at the default page size): 6 open batches arranged to exercise every processing rule (ready to
+  process; expired FX quote; insufficient funds; one payment to a recipient disabled after it was added; a check below the
+  route minimum; empty), 4 complete August batches and 1 failed batch.
+- 22 payments (plus 22 `payment_index` rows) with fees and FX computed by the Tool's own pricing rules.
+
+Row ids follow Trolley's format `<prefix>-<22 characters>` (`R-` recipient, `A-` account, `B-` batch, `P-` payment); new ids
+come from `meta/counters`, so runs are deterministic.
+
+## Operations and routes
+
+No MCP aliases are declared (Trolley publishes no MCP tool contract); MCP clients use the canonical `trolley.<operation>` tools.
+Every route answers 200 on success with `ok: true`.
+
+| operation | HTTP route | notes |
+|---|---|---|
+| `recipients.create` | `POST /v1/recipients` | optional `accounts` array; status derived (active needs address + primary account) |
+| `recipients.get` | `GET /v1/recipients/{recipientId}` | computed `payoutMethod`, `primaryCurrency`, `routeType`, `routeMinimum`, `estimatedFees`, masked `accounts` |
+| `recipients.update` | `PATCH /v1/recipients/{recipientId}` | `address` merged per field; `status: "active"` restores an archived recipient |
+| `recipients.delete` | `DELETE /v1/recipients/{recipientId}` | archives; refused while the recipient has a pending payment in an open batch |
+| `recipients.list` | `GET /v1/recipients` | `page`, `pageSize` (≤ 1000), `search`, `name`, `email`, `referenceId`, `status`, `complianceStatus`, `country`, `payoutMethod`, `currency`, `tags`, `orderBy`, `sortBy` |
+| `recipient_accounts.create` | `POST /v1/recipients/{recipientId}/accounts` | `bank-transfer`, `paypal`, `check`, `venmo` |
+| `recipient_accounts.list` | `GET /v1/recipients/{recipientId}/accounts` | active accounts, primary first |
+| `recipient_accounts.get` | `GET /v1/recipients/{recipientId}/accounts/{accountId}` | includes disabled accounts |
+| `recipient_accounts.update` | `PATCH /v1/recipients/{recipientId}/accounts/{accountId}` | `primary: true` demotes siblings; number, IBAN, type and country are immutable |
+| `recipient_accounts.delete` | `DELETE /v1/recipients/{recipientId}/accounts/{accountId}` | disables the account |
+| `batches.create` | `POST /v1/batches` | optional `payments` (≤ 1000) |
+| `batches.get` | `GET /v1/batches/{batchId}` | computed `amount`, `totalPayments` |
+| `batches.update` | `PATCH /v1/batches/{batchId}` | open batches only |
+| `batches.delete` | `DELETE /v1/batches/{batchId}` | open batches only; removes their payments |
+| `batches.list` | `GET /v1/batches` | `page`, `pageSize`, `search`, `status`, `currency`, `tags`, `orderBy` (`createdAt`, `amount`, `status`), `sortBy` |
+| `batches.generate_quote` | `POST /v1/batches/{batchId}/generate-quote` | quote valid for 90 minutes of virtual time; 406 when the batch is not open |
+| `batches.start_processing` | `POST /v1/batches/{batchId}/start-processing` | 409 when not open or empty; see processing rules |
+| `batches.summary` | `GET /v1/batches/{batchId}/summary` | per payout method and total |
+| `payments.create` | `POST /v1/batches/{batchId}/payments` | `recipient` `{ id \| email \| referenceId }`; `amount` + `currency` in the batch currency or the payout currency |
+| `payments.list` | `GET /v1/batches/{batchId}/payments` | `page`, `pageSize`, `status`, `search` |
+| `payments.get` | `GET /v1/batches/{batchId}/payments/{paymentId}`, `GET /v1/payments/{paymentId}` | |
+| `payments.update` | `PATCH /v1/batches/{batchId}/payments/{paymentId}` | pending payments in open batches only |
+| `payments.delete` | `DELETE /v1/batches/{batchId}/payments/{paymentId}` | pending payments in open batches only |
+| `balances.list` | `GET /v1/balances`, `GET /v1/balances/{kind}` | `kind` is `paymentrails` or `paypal`; adds `serverTime` (virtual time) |
+
+Errors use Trolley's envelope `{ "ok": false, "errors": [{ "code", "field"?, "message" }] }` with codes `invalid_api_key` (401),
+`not_authorized` (403), `not_found` (404), `empty_field`, `invalid_field`, `expired_quote`, `non_sufficient_funds` (400),
+`invalid_status` (409 on `start-processing`, 406 on `generate-quote`, 400 elsewhere), `rate_limit_exceeded` (429), `partner_integration_error`
+and `internal_server_error` (500).
+An `Idempotency-Key` request header (1 to 255 characters; blank is ignored) is forwarded as the Firedrill idempotency key, a Firedrill
+addition: Trolley documents no idempotency header, so the outcomes are rendered with the closest documented code. Reusing a key with
+the same body on the same route replays the recorded successful response; a call that failed with an error records nothing (the
+framework rolls it back) and is re-executed on retry, so it may then succeed. Reusing a key with a different body answers
+400 `invalid_field` on field `Idempotency-Key` ("Idempotency-Key was already used with a different request body"); sending it to a
+read endpoint (every `GET`) or with more than 255 characters also answers 400 `invalid_field` on `Idempotency-Key`. Over the canonical
+`/v1/operations/trolley/<operation>` path the same cases carry the framework codes `world.IDEMPOTENCY_CONFLICT` and
+`framework.IDEMPOTENCY_NOT_SUPPORTED`.
+
+### Processing rules
+
+`start-processing` checks everything before writing, so a refused call changes nothing: the batch is open and has payments;
+a payment needing currency conversion requires an unexpired quote (`expired_quote`); every attempted payment meets its route
+minimum (`invalid_field` on `amount`); the `paymentrails` balance in the batch currency covers the sending amounts plus merchant
+fees (`non_sufficient_funds`). The batch then settles in the same call: payments whose recipient is no longer active or has no
+primary payout method fail with a `failureMessage`, the others are processed and debited, and the batch ends `complete` (at
+least one processed) or `failed`.
+
+Fees and minimums come from `meta/fees` (USD, converted at the `meta/fx` rate); `coverFees: true` moves the fee from the
+recipient to the merchant. Cross rates are `rates[target] / rates[source]` rounded half up to six decimals; amounts round half up
+to cents. PayPal payments pay in the batch currency.
+
+## Events and faults
+
+| id | kind | when |
+|---|---|---|
+| `batch.processing` | event | once per settled batch, payload `{ model: "batch", action: "processing", body: { batch } }` |
+| `payment.processed` | event | per processed payment, `{ model: "payment", action: "processed", body: { payment } }` |
+| `payment.failed` | event | per failed payment, `{ model: "payment", action: "failed", body: { payment } }` |
+| `rate-limited` | fault (before) | `recipients.list`, `batches.list`, `payments.list` answer 429 `rate_limit_exceeded` |
+| `payout-partner-outage` | fault (before) | `recipient_accounts.create`, `batches.generate_quote` answer 500 `partner_integration_error`; nothing changes |
+| `processing-response-lost` | fault (after commit) | `batches.start_processing` settles the batch, debits the balance and emits events, then answers 500 `internal_server_error` |
+
+The events mirror Trolley's webhook body so a consumer-declared callback can forward them; the package declares no callbacks.
+
+## Browser app
+
+`firedrill serve` prints the app link (also under **Tools → Open app**). The app is declared as `"ui": { "root": "app/site", "entry": "index.html" }`
+and is plain local HTML/CSS/JS using `/_firedrill/client.js`; every screen calls the operations above, so a change made in the app is visible over
+HTTP and MCP and vice versa, and a world reset restores both.
+
+- **Chrome**: collapsible icon rail with the Trolley app tile (Overview, Recipients, Payments, Invoices, Balances, Tax Center, Reports, Approvals,
+  Developers, Settings), top bar with page title, notification bell, the synthetic actor id with a `SANDBOX` pill, and the account menu.
+- **Overview**: available Trolley balance, value of completed batches, recipient count and incomplete profiles, batches awaiting processing,
+  recently completed batches.
+- **Recipients**: status tabs, search (`search`), payout-method and country filters, sortable columns, page/pageSize paging, **Add recipient**.
+- **Recipient profile**: details with **Edit**, payout methods (masked numbers, primary badge, **Make primary**, **Remove** with confirmation),
+  **Add payout method** (bank transfer, Venmo, PayPal, check), **Archive** / **Restore recipient**.
+- **Payments**: batch list with status tabs, search, sorting, paging and **Create batch**. **Batch detail**: status, amount, payment count and quote
+  expiry computed from world virtual time (`balances.list` `serverTime`), payments table with search and paging, **Add payment** with a recipient
+  search picker, edit/remove pending payments, **Generate quote**, **Review** (batch summary by payout method), **Process batch** confirmation
+  showing the debit and available balance, **Delete batch**.
+- **Balances**: Trolley and PayPal balances with kind tabs.
+
+Every mutation sends a fresh idempotency key per confirmed action and is never retried silently; a 500 or partner error while processing tells the
+user the result is unknown and re-reads the batch. Loading skeletons, empty states, error states with **Try again**, and `not_authorized` /
+`invalid_api_key` panels are rendered from the real outcomes. The app refreshes when `getContext().revision` changes, except while a form is open.
+All record text is rendered with `textContent`.
+
+Not simulated (the controls are present and open a "not simulated by this Tool" panel, with no invented data): Invoices, Tax Center, Reports,
+Approvals, Developers, Settings, the notification feed, account settings and live mode. The app cannot read actor attributes, so it shows the
+actor id instead of `displayName`, and a read-only key is discovered when a write is refused. Logos are the vendor's own files (see
+`firedrill/tools/trolley/app/assets/ATTRIBUTION.md`); the typeface is Inter (OFL) standing in for the proprietary face.
+
+## Compatibility
+
+**Not verified against a real Trolley client.** `compatibility` is empty. Trolley's official SDKs sign each request
+(`Authorization: prsign <accessKey>:<HMAC signature>` plus `X-PR-Timestamp`). Firedrill's HTTP binding compares the credential
+after the scheme exactly with the world token, so a caller must send `Authorization: prsign <FIREDRILL_HTTP_TOKEN>` (or
+`Bearer`). Signed SDK requests cannot authenticate unmodified; timestamps and signatures are never checked.
+
+Framework-owned outcomes (a missing grant, input that fails the declared schema, a request the codec cannot map) keep the
+framework's HTTP status and are rendered in Trolley's envelope (`not_authorized`, `invalid_field`, `not_found`). A missing or
+wrong token answers the framework's 401 (`framework.HTTP_UNAUTHORIZED`), and trailing-slash paths (`/v1/recipients/`) and
+endpoints outside the table answer the framework's 404; those responses never reach the Tool, so they keep framework bodies.
+
+`generate-quote` and `start-processing` accept an empty body or `{}` (the routes are declared as text bodies because the framework
+rejects empty JSON bodies).
+
+## Limitations
+
+1. Processing settles synchronously: no `initiating` or `processing` status is observable over REST (only in the
+   `batch.processing` event), and there are no delayed bank settlements, returns or `payment.returned` events.
+2. Not simulated (404): bulk deletes, recipient logs and payment history, offline payments, invoices, verifications, tax forms and
+   profiles, webhook subscription management, recipient widget or portal URLs, approval workflows, funding and deposits, live mode.
+3. Withholding and returned amounts are always `"0.00"`; `debit-card`, `mobile-wallet` and `interac` accounts cannot be created.
+4. FX rates, fees and route minimums are synthetic (`meta/fx`, `meta/fees`), not Trolley's pricing. Cross-currency payment amounts
+   are always shown at the table rate; a quote locks them for 90 minutes of virtual time.
+5. Balances are a seeded snapshot; processing debits only `paymentrails:<batch currency>`.
+6. Recipient status uses a simplified rule (address + primary account + holds); country-specific bank rules are reduced to digit
+   checks for account number, routing/transit/sort code and CA institution number, and an IBAN shape check.
+7. Full account numbers and IBANs are never stored: only the last four characters, always shown masked.
+8. Lists are page-number based. A page whose JSON would exceed 900 KB answers `invalid_field` on `pageSize`. Every state scan is
+   bounded by 10,000 rows (lower with `meta/limits.maxRows`); exceeding it answers `internal_server_error` instead of truncating.
+9. Unsupported list query parameters (for example `startDate`) answer `invalid_field` rather than being ignored.
+10. The default exclusion of archived recipients from lists, e-mail uniqueness among non-archived recipients and several error
+    messages are inferred from public documentation, not verified against the live API. Recipient responses omit `gravatarUrl`,
+    `compliance`, `governmentIds` and similar fields that the Tool does not model.
+11. `balances.list` adds `serverTime`, and idempotent replay via `Idempotency-Key` is a Firedrill addition (see "Operations and routes"
+    for how key reuse and misuse are rendered). A replayed response carries the same values as the original, but the framework
+    stores the recorded result in canonical form, so its JSON keys come back in alphabetical rather than Trolley's field order.
+
+## Conformance
+
+`firedrill tool test trolley` runs 12 drills (Node built-ins only, `test/conformance.mjs`) twice and checks determinism: recipients,
+accounts, batch lifecycle, processing rules, read-only key, another merchant's key, fresh-install actor, framework denial, and one
+scenario per fault plus a lowered scan bound. Together they observe every operation, declared error, event and fault.
+
+## Trademarks
+
+Trolley, the Trolley name and the Trolley logos are trademarks of their owner. The name and the unmodified logo files bundled in the
+browser app (sources recorded in `firedrill/tools/trolley/app/assets/ATTRIBUTION.md`) are used only to identify the simulated service in a
+test environment; this package is not affiliated with or endorsed by Trolley. PayPal and Venmo are named only as payout-method types.
+
+## License
+
+Apache-2.0

package/firedrill/agent.target.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "target": {
+    "id": "conformance-agent",
+    "kind": "command",
+    "bindings": [
+      "http"
+    ],
+    "executable": "node",
+    "arguments": [
+      "test/conformance.mjs"
+    ],
+    "workingDirectory": ".",
+    "timeoutMs": 120000
+  }
+}