@codespar/cli 0.17.0 → 0.18.1

package/templates/checkout-agent/agents/checkout-agent/src/modules/nfse-invoice.ts

@@ -0,0 +1,374 @@
+/**
+ * Module `nfse-invoice`: the service invoice (NFS-e) of a PAID order, as an
+ * execution of its own (checkout §4, decision 4).
+ *
+ * The invoice is not a state of the sale. The sale ends in `settled`; when it
+ * does, this module opens a second execution with its own outbox row and
+ * calls `codespar_invoice` BY CODE — the model never reaches it, because a
+ * fiscal document is irreversible and must not be one sentence away from the
+ * customer. The two executions refer to each other by the cart and the
+ * charge, and nothing either one does moves the other: a paid order stays
+ * paid whatever the invoice does, and the customer is never told about the
+ * invoice.
+ *
+ * The retry rule is the core's outbox rule, applied to a document instead of
+ * money. The outbox row flips to `sent` BEFORE the call. An answer that
+ * proves nothing reached the issuer (`unsent`) is retried, a bounded number
+ * of times. An issuer refusal is terminal for the attempt and goes to the
+ * attendant with the issuer's code. ANYTHING else — a timeout, a 5xx, a
+ * provider error the wire does not qualify, a crash after `sent` — may have
+ * authorized a note, and ends `failed (invoice_uncertain)` for a person to
+ * reconcile. It is never sent again: the issuance carries no idempotency key
+ * and the meta-tool cannot read an NFS-e back (checkout §9.14, ent#1675), so
+ * a blind retry can mint a second irreversible document for the same sale.
+ */
+import { randomBytes } from "node:crypto";
+import { describeApiError, type Execution, type ExecutionEngine, type StateStore } from "@codespar/agent-core";
+import type { ApiClient } from "@codespar/sdk";
+import { catalogItem, customerByDocument, formatBRL, MERCHANT, type Customer } from "../catalog.js";
+import type { Cart } from "./storefront-cart.js";
+
+/**
+ * `accepted` is the issuer taking the request and naming a document: the
+ * municipal AUTHORIZATION that follows is not readable through the
+ * meta-tool (checkout §9.14), so this module never claims it.
+ */
+export type InvoiceState = "pending" | "issuing" | "accepted" | "failed";
+export type InvoiceReason = "invoice_refused" | "invoice_unsent" | "invoice_uncertain";
+
+export interface InvoiceRecord {
+  id: string;
+  /** The sale this invoice follows, and what ties the two: the cart and the charge. */
+  sale_execution_id: string;
+  cart_ref: string;
+  charge_id: string | null;
+  /** The outbox row's key. One per invoice; a retry of an `unsent` attempt reuses it. */
+  idempotency_key: string;
+  state: InvoiceState;
+  reason?: InvoiceReason;
+  /** The issuer's code (a refusal) or the transport's (anything else). */
+  code?: string;
+  detail?: string;
+  attempts: number;
+  document?: { id: string; status: string; pdf_url: string | null };
+  history: Array<{ from: InvoiceState | null; to: InvoiceState; at: string; reason?: InvoiceReason; code?: string }>;
+  created_at: string;
+  updated_at: string;
+}
+
+/** What `codespar_invoice action=issue type=nfse` is asked. Built from the paid order, never from the conversation. */
+export interface NfseRequest {
+  action: "issue";
+  type: "nfse";
+  recipient: {
+    name: string;
+    federalTaxNumber: string;
+    email: string;
+    address?: { country: "BRA"; postalCode: string; street: string; number: string; district: string; city: { code: string; name: string }; state: string };
+  };
+  items: Array<{ description: string; quantity: number; unit_price: number; service_code: string }>;
+  metadata: { description: string; servicesAmount: number; additionalInformation: string };
+}
+
+export type InvoiceOutcome =
+  | { status: "accepted"; document_id: string; document_status: string; pdf_url: string | null }
+  /** Proven not to have reached the issuer: the request was refused before any provider call. Retried. */
+  | { status: "unsent"; code: string; message: string }
+  /** The issuer answered and refused. Nothing was issued; the same data would be refused again. */
+  | { status: "refused"; code: string; message: string }
+  /** Nobody can say whether a note was authorized. Never retried. */
+  | { status: "uncertain"; code: string; message: string };
+
+export interface InvoiceRail {
+  readonly name: "stub-nfse" | "codespar-nfse";
+  issue(request: NfseRequest, key: string): Promise<InvoiceOutcome>;
+}
+
+export const MAX_INVOICE_ATTEMPTS = 3;
+
+/**
+ * The strategy codes raised BEFORE the provider is called on the invoice
+ * path (`meta-tools/real-strategy.ts`, `strategy-error.ts` at enterprise
+ * main): routing found no provider, the transform or tool is unknown, the
+ * credential did not resolve, the arguments did not coerce, the organization
+ * is paused. `provider_error` is NOT here: it is raised both for a 4xx the
+ * issuer answered and for a timeout or a 5xx, and the wire does not say which
+ * (OPEN_QUESTIONS §58).
+ */
+const PRE_DISPATCH_CODES = new Set(["no_eligible_providers", "transform_unknown", "tool_unknown", "credential_unavailable", "invalid_args", "org_paused"]);
+
+/**
+ * `codespar_invoice` through the REST twin of a session: `POST /v1/sessions`,
+ * then `POST /v1/sessions/{id}/execute` with the meta-tool's own name and
+ * input. The kit runs no MCP session of its own; this is the same call an
+ * agent's `codespar_invoice` makes, made by code.
+ */
+export class CodeSparInvoiceRail implements InvoiceRail {
+  readonly name = "codespar-nfse" as const;
+  private sessionId: string | undefined;
+
+  constructor(private readonly api: ApiClient) {}
+
+  async issue(request: NfseRequest): Promise<InvoiceOutcome> {
+    if (!this.sessionId) {
+      try {
+        const session = await this.api.post("/v1/sessions", { body: { servers: ["nfe-io"] } });
+        this.sessionId = session.id;
+      } catch (err) {
+        // Opening a session sends no document, whatever the answer was.
+        const f = describeApiError(err);
+        return { status: "unsent", code: f.code, message: `the session could not be opened: ${f.message}` };
+      }
+    }
+    let answer: { success: boolean; data?: unknown; error: string | null; server?: string };
+    try {
+      answer = await this.api.post("/v1/sessions/{id}/execute", { path: { id: this.sessionId! }, body: { tool: "codespar_invoice", input: request as unknown as Record<string, unknown> } });
+    } catch (err) {
+      const f = describeApiError(err);
+      // The route answered and refused the request (schema, auth, policy, rate): no tool ran. Anything else may have dispatched.
+      if (f.status >= 400 && f.status < 500) return { status: "unsent", code: f.code, message: f.message };
+      return { status: "uncertain", code: f.code, message: `${f.message}; the issuance may have reached the issuer` };
+    }
+    return classifyExecuteAnswer(answer);
+  }
+}
+
+/** The execute envelope, read by its structure and its codes, never by its prose. Exported for the tests. */
+export function classifyExecuteAnswer(answer: { success: boolean; data?: unknown; error: string | null; server?: string }): InvoiceOutcome {
+  const data = (answer.data ?? null) as Record<string, unknown> | null;
+  if (answer.success) {
+    const id = typeof data?.["id"] === "string" && data["id"] ? data["id"] : undefined;
+    if (!id) return { status: "uncertain", code: "invoice_unreadable", message: "the issuer answered success without a document id; a note may exist and nothing here can name it" };
+    return { status: "accepted", document_id: id, document_status: typeof data?.["status"] === "string" ? data["status"] : "UNKNOWN", pdf_url: typeof data?.["danfe_url"] === "string" ? data["danfe_url"] : null };
+  }
+  const code = typeof data?.["code"] === "string" ? data["code"] : "unknown";
+  const message = answer.error ?? (typeof data?.["error"] === "string" ? data["error"] : "no message");
+  // Forward-compatible: the strategy knows the provenance (`dispatch`) and today does not put it on the wire. The day it does, it decides.
+  if (data?.["dispatch"] === "unsent") return { status: "unsent", code, message };
+  if (data?.["dispatch"] === "rejected") return { status: "refused", code, message };
+  // A policy or scope refusal is ours, not the issuer's: nothing was dispatched.
+  if (answer.server === "agentgate" || answer.server === "") return { status: "unsent", code, message };
+  if (PRE_DISPATCH_CODES.has(code)) return { status: "unsent", code, message };
+  return { status: "uncertain", code, message };
+}
+
+export type StubIssuerBehaviour = "issues" | "refuses" | "times_out" | "unsent_once" | "unsent";
+
+/**
+ * STUB issuer. Offline, deterministic, persisted in state.db so a killed
+ * process finds what it issued. It applies one rule a real issuer applies —
+ * a borrower without an address is refused — and one script of its own:
+ * Beatriz's invoice times out AFTER the request left, which is the case
+ * nobody can settle from the answer. `behaviour` overrides both (a test).
+ */
+export class StubInvoiceRail implements InvoiceRail {
+  readonly name = "stub-nfse" as const;
+  private unsentPending = true;
+
+  constructor(
+    private readonly store: StateStore,
+    private readonly behaviour?: StubIssuerBehaviour,
+  ) {}
+
+  async issue(request: NfseRequest, key: string): Promise<InvoiceOutcome> {
+    const behaviour = this.behaviour ?? (request.recipient.federalTaxNumber === "43091752879" ? "times_out" : undefined);
+    if (behaviour === "unsent") return { status: "unsent", code: "no_eligible_providers", message: "stub: this organization has no issuer connected; nothing was sent" };
+    if (behaviour === "unsent_once" && this.unsentPending) {
+      this.unsentPending = false;
+      return { status: "unsent", code: "no_eligible_providers", message: "stub: routing found no issuer this time; nothing was sent" };
+    }
+    if (behaviour === "refuses" || (behaviour === undefined && !request.recipient.address)) {
+      return { status: "refused", code: "E0101", message: "stub issuer: tomador sem endereco; a NFS-e exige o endereco do tomador" };
+    }
+    // What the issuer did is recorded before the answer is lost, as a real one would have.
+    const documentId = `nfse_stub_${key.slice(-16)}`;
+    this.store.setCursor(`stub-nfse:${key}`, JSON.stringify({ document_id: documentId, request }));
+    if (behaviour === "times_out") return { status: "uncertain", code: "timeout", message: "stub issuer: no answer within the timeout; the request had left" };
+    return { status: "accepted", document_id: documentId, document_status: "WAITINGSEND", pdf_url: null };
+  }
+
+  /** Test hook: what the stub issuer holds for a key (a note it authorized, whether or not anybody heard back). */
+  issued(key: string): string | undefined {
+    const raw = this.store.getCursor(`stub-nfse:${key}`);
+    return raw ? (JSON.parse(raw) as { document_id: string }).document_id : undefined;
+  }
+}
+
+const KEY = (saleId: string) => `checkout:invoice:${saleId}`;
+const INDEX = "checkout:invoices";
+
+/** The invoices, in state.db's key-value table; their outbox rows in the core's outbox table (`kind: nfse.issue`). */
+export class InvoiceBook {
+  constructor(private readonly store: StateStore) {}
+
+  of(saleId: string): InvoiceRecord | undefined {
+    const raw = this.store.getCursor(KEY(saleId));
+    return raw ? (JSON.parse(raw) as InvoiceRecord) : undefined;
+  }
+
+  all(): InvoiceRecord[] {
+    const raw = this.store.getCursor(INDEX);
+    const ids = raw ? (JSON.parse(raw) as string[]) : [];
+    return ids.map((id) => this.of(id)).filter((r): r is InvoiceRecord => r !== undefined);
+  }
+
+  save(record: InvoiceRecord): void {
+    this.store.setCursor(KEY(record.sale_execution_id), JSON.stringify(record));
+    const raw = this.store.getCursor(INDEX);
+    const ids = raw ? (JSON.parse(raw) as string[]) : [];
+    if (!ids.includes(record.sale_execution_id)) this.store.setCursor(INDEX, JSON.stringify([...ids, record.sale_execution_id]));
+  }
+}
+
+export interface InvoiceDeps {
+  store: StateStore;
+  engine: ExecutionEngine;
+  rail: InvoiceRail;
+  cart(ref: string): Cart | undefined;
+  /** The attendant's console. The customer is never told about the invoice. */
+  say(line: string): void;
+}
+
+/** The request, from the paid order: the customer book's fiscal data, the cart's lines, the total that was paid. */
+export function nfseRequest(sale: Execution, cart: Cart, customer: Customer): NfseRequest {
+  const chargeId = sale.outcomes[0]?.transaction_id ?? "?";
+  return {
+    action: "issue",
+    type: "nfse",
+    recipient: {
+      name: customer.name,
+      federalTaxNumber: customer.document,
+      email: customer.email,
+      ...(customer.address
+        ? { address: { country: "BRA" as const, postalCode: customer.address.postal_code, street: customer.address.street, number: customer.address.number, district: customer.address.district, city: { code: customer.address.city_code, name: customer.address.city }, state: customer.address.state } }
+        : {}),
+    },
+    items: cart.line_items.map((l) => ({ description: l.name, quantity: l.quantity, unit_price: l.unit_amount / 100, service_code: catalogItem(l.sku)?.service_code ?? "" })),
+    metadata: {
+      description: `${MERCHANT.name} - pedido ${cart.cart_id}: ${cart.line_items.map((l) => `${l.quantity}x ${l.name}`).join("; ")}`,
+      // What was PAID, discounts included; the transform would otherwise sum list prices.
+      servicesAmount: sale.total / 100,
+      additionalInformation: `cobranca ${chargeId}, ${formatBRL(sale.total)}`,
+    },
+  };
+}
+
+function transition(record: InvoiceRecord, to: InvoiceState, deps: InvoiceDeps, extra: { reason?: InvoiceReason; code?: string; detail?: string } = {}): InvoiceRecord {
+  const at = deps.engine.clock().toISOString();
+  const { reason: _r, code: _c, detail: _d, ...rest } = record;
+  const next: InvoiceRecord = { ...rest, state: to, ...extra, updated_at: at, history: [...record.history, { from: record.state, to, at, ...(extra.reason ? { reason: extra.reason } : {}), ...(extra.code ? { code: extra.code } : {}) }] };
+  new InvoiceBook(deps.store).save(next);
+  deps.engine.note("invoice.transition", record.sale_execution_id, { invoice_id: record.id, from: record.state, to, ...extra });
+  return next;
+}
+
+/** Opens the invoice of a settled order, once. `undefined` for anything that is not a paid order. */
+export function openInvoice(sale: Execution, deps: InvoiceDeps): InvoiceRecord | undefined {
+  if (sale.state !== "settled" || !sale.composition) return undefined;
+  const book = new InvoiceBook(deps.store);
+  const existing = book.of(sale.id);
+  if (existing) return existing;
+  const at = deps.engine.clock().toISOString();
+  const record: InvoiceRecord = {
+    id: `inv_${randomBytes(8).toString("hex")}`,
+    sale_execution_id: sale.id,
+    cart_ref: sale.composition.ref,
+    charge_id: sale.outcomes[0]?.transaction_id ?? null,
+    idempotency_key: `nfse_${sale.idempotency_key.slice(4)}`,
+    state: "pending",
+    attempts: 0,
+    history: [{ from: null, to: "pending", at }],
+    created_at: at,
+    updated_at: at,
+  };
+  book.save(record);
+  deps.store.putOutbox({ idempotency_key: record.idempotency_key, execution_id: record.id, kind: "nfse.issue", payload: { sale_execution_id: sale.id, cart_ref: record.cart_ref, charge_id: record.charge_id }, status: "pending", response: undefined, created_at: at });
+  deps.engine.note("invoice.opened", sale.id, { invoice_id: record.id, cart_ref: record.cart_ref, charge_id: record.charge_id, idempotency_key: record.idempotency_key });
+  return record;
+}
+
+/**
+ * Sends a `pending` invoice. The outbox flips to `sent` before each call, so
+ * a crash after that point is reconciled as uncertain and never re-sent.
+ */
+export async function dispatchInvoice(record: InvoiceRecord, deps: InvoiceDeps): Promise<InvoiceRecord> {
+  let current = record;
+  const sale = deps.engine.get(record.sale_execution_id);
+  const cart = deps.cart(record.cart_ref);
+  const customer = sale ? customerByDocument(sale.items[0]!.payee) : undefined;
+  if (!sale || !cart || !customer) {
+    // Nothing was sent: the order's own records do not resolve. A defect of this state, not the issuer's answer.
+    deps.store.updateOutbox(record.idempotency_key, "failed", { code: "invoice_data_missing" }, deps.engine.clock().toISOString());
+    return notify(transition(current, "failed", deps, { reason: "invoice_unsent", code: "invoice_data_missing", detail: "the paid order, its cart or its customer could not be read; nothing was sent" }), deps);
+  }
+  const request = nfseRequest(sale, cart, customer);
+  while (current.state === "pending") {
+    const attempt = current.attempts + 1;
+    current = transition({ ...current, attempts: attempt }, "issuing", deps);
+    deps.store.updateOutbox(record.idempotency_key, "sent", undefined, deps.engine.clock().toISOString());
+    deps.engine.note("invoice.dispatch", sale.id, { invoice_id: record.id, attempt, rail: deps.rail.name, idempotency_key: record.idempotency_key, services_amount: request.metadata.servicesAmount });
+    const outcome = await deps.rail.issue(request, record.idempotency_key);
+    deps.engine.note("invoice.outcome", sale.id, { invoice_id: record.id, attempt, status: outcome.status, ...(outcome.status === "accepted" ? { document_id: outcome.document_id, document_status: outcome.document_status } : { code: outcome.code, message: outcome.message }) });
+    const at = deps.engine.clock().toISOString();
+    switch (outcome.status) {
+      case "accepted":
+        deps.store.updateOutbox(record.idempotency_key, "done", outcome, at);
+        current = transition({ ...current, document: { id: outcome.document_id, status: outcome.document_status, pdf_url: outcome.pdf_url } }, "accepted", deps);
+        break;
+      case "unsent":
+        if (attempt >= MAX_INVOICE_ATTEMPTS) {
+          deps.store.updateOutbox(record.idempotency_key, "failed", outcome, at);
+          current = notify(transition(current, "failed", deps, { reason: "invoice_unsent", code: outcome.code, detail: `${attempt} attempt(s), none reached the issuer: ${outcome.message}` }), deps);
+        } else {
+          // Proven not sent: the row goes back to pending, and the next attempt is the same request under the same key.
+          deps.store.updateOutbox(record.idempotency_key, "pending", outcome, at);
+          current = transition(current, "pending", deps, { code: outcome.code, detail: outcome.message });
+        }
+        break;
+      case "refused":
+        deps.store.updateOutbox(record.idempotency_key, "failed", outcome, at);
+        current = notify(transition(current, "failed", deps, { reason: "invoice_refused", code: outcome.code, detail: outcome.message }), deps);
+        break;
+      case "uncertain":
+        deps.store.updateOutbox(record.idempotency_key, "failed", outcome, at);
+        current = notify(transition(current, "failed", deps, { reason: "invoice_uncertain", code: outcome.code, detail: `${outcome.message}. Not re-issued: the issuance has no idempotency key and the meta-tool cannot read an NFS-e back (ent#1675); reconcile at the issuer before issuing again.` }), deps);
+        break;
+    }
+  }
+  return current;
+}
+
+/** The attendant hears about a failed invoice; the customer never does. */
+function notify(record: InvoiceRecord, deps: InvoiceDeps): InvoiceRecord {
+  const text =
+    record.reason === "invoice_uncertain"
+      ? `NFS-e do pedido ${record.sale_execution_id} (cobranca ${record.charge_id}) com resultado INCERTO (${record.code}): pode ter sido emitida. Nao reemita; confira no emissor. A venda continua paga.`
+      : `NFS-e do pedido ${record.sale_execution_id} (cobranca ${record.charge_id}) falhou (${record.reason}, ${record.code}): ${record.detail}. A venda continua paga.`;
+  deps.say(`  [atendente] ${text}`);
+  deps.engine.note("message.attendant", record.sale_execution_id, { invoice_id: record.id, state: record.state, reason: record.reason ?? null, code: record.code ?? null, text });
+  return record;
+}
+
+/** After a sale's outcome: open its invoice if it was paid, and send it if it is pending. */
+export async function followSale(sale: Execution, deps: InvoiceDeps): Promise<InvoiceRecord | undefined> {
+  const record = openInvoice(sale, deps);
+  if (!record || record.state !== "pending") return record;
+  return dispatchInvoice(record, deps);
+}
+
+/**
+ * `resume`: a `pending` invoice provably never left and is sent; one left
+ * `issuing` was sent and never answered, which is exactly the uncertain case,
+ * so it closes as `invoice_uncertain` and is NOT sent again.
+ */
+export async function resumeInvoices(deps: InvoiceDeps): Promise<InvoiceRecord[]> {
+  const out: InvoiceRecord[] = [];
+  for (const record of new InvoiceBook(deps.store).all()) {
+    if (record.state === "pending") out.push(await dispatchInvoice(record, deps));
+    else if (record.state === "issuing") {
+      deps.store.updateOutbox(record.idempotency_key, "failed", { code: "interrupted" }, deps.engine.clock().toISOString());
+      out.push(notify(transition(record, "failed", deps, { reason: "invoice_uncertain", code: "interrupted", detail: "the process stopped after the request was sent and before an answer was recorded" }), deps));
+    }
+  }
+  return out;
+}

package/templates/checkout-agent/agents/checkout-agent/src/modules/storefront-cart.ts

@@ -0,0 +1,220 @@
+/**
+ * Module `storefront-cart`: the cart, kept by the agent in `state.db` (there
+ * is no sales-side cart in the API, checkout §9.1), and the three local tools
+ * the model reaches it by. The rules are checkout §2's, applied here by code:
+ *
+ * - `cart_update` REPLACES the cart with the lines it is given. Nothing is
+ *   merged; an empty list empties it (§2.1).
+ * - Every answer carries `validation_issues: [{ code, field, message }]` from
+ *   a closed vocabulary (§2.2).
+ * - The totals are computed here from the catalog; no input carries a price
+ *   (§2.3).
+ *
+ * The shapes follow the ACP `CheckoutSession` the enterprise cart already
+ * uses (`line_items`, `totals`, `status`), so a server-side cart one day is a
+ * change of storage and not of contract.
+ *
+ * A cart id the model sees (`cart-1`) counts within the run; the ref the
+ * execution carries (`<run_id>/cart-1`) is unique across runs, so an order
+ * approved from another process (`npm run approve`) finds its cart.
+ */
+import type { ExecutionEngine, StateStore, ToolHandler } from "@codespar/agent-core";
+import { CATALOG, MERCHANT, formatBRL } from "../catalog.js";
+import { localDate, priceCart, type Envelope, type PricedCart, type ValidationIssue } from "../pricing.js";
+
+export interface Cart extends PricedCart {
+  cart_id: string;
+  ref: string;
+  run_id: string;
+  version: number;
+  currency: "BRL";
+  order_discount_pct: number;
+  updated_at: string;
+}
+
+/** ACP `CheckoutStatus`, derived from the order: the cart does not decide it, the execution does. */
+export type CartStatus = "in_progress" | "ready_for_payment" | "completed";
+
+const KEY = (ref: string) => `checkout:cart:${ref}`;
+const RUN_KEY = (runId: string) => `checkout:carts:${runId}`;
+const ORDER_KEY = (ref: string) => `order:${ref}`;
+
+/** The carts, in state.db's key-value table beside the execution cursors. */
+export class CartBook {
+  constructor(private readonly store: StateStore) {}
+
+  get(ref: string): Cart | undefined {
+    const raw = this.store.getCursor(KEY(ref));
+    return raw ? (JSON.parse(raw) as Cart) : undefined;
+  }
+
+  save(cart: Cart): void {
+    this.store.setCursor(KEY(cart.ref), JSON.stringify(cart));
+    const ids = this.idsOf(cart.run_id);
+    if (!ids.includes(cart.cart_id)) this.store.setCursor(RUN_KEY(cart.run_id), JSON.stringify([...ids, cart.cart_id]));
+  }
+
+  idsOf(runId: string): string[] {
+    const raw = this.store.getCursor(RUN_KEY(runId));
+    return raw ? (JSON.parse(raw) as string[]) : [];
+  }
+
+  byId(runId: string, cartId: string): Cart | undefined {
+    return this.get(`${runId}/${cartId}`);
+  }
+
+  latest(runId: string): Cart | undefined {
+    const ids = this.idsOf(runId);
+    const last = ids[ids.length - 1];
+    return last ? this.byId(runId, last) : undefined;
+  }
+
+  nextId(runId: string): string {
+    return `cart-${this.idsOf(runId).length + 1}`;
+  }
+}
+
+/** The order a cart belongs to, if one was placed: the execution the claim names. */
+export function orderOf(engine: ExecutionEngine, cart: Pick<Cart, "ref">) {
+  const id = engine.claimed(ORDER_KEY(cart.ref));
+  return id ? engine.get(id) : undefined;
+}
+
+export function claimOrder(engine: ExecutionEngine, cart: Pick<Cart, "ref">, executionId: string): void {
+  engine.claim(ORDER_KEY(cart.ref), executionId);
+}
+
+export function statusOf(engine: ExecutionEngine, cart: Cart): CartStatus {
+  const order = orderOf(engine, cart);
+  if (order?.state === "settled") return "completed";
+  if (order?.state === "executing") return "ready_for_payment";
+  return "in_progress";
+}
+
+/** A cart whose charge is out or paid is the record of that sale: it is not edited, a new cart is. */
+export function isLocked(engine: ExecutionEngine, cart: Cart): boolean {
+  return statusOf(engine, cart) !== "in_progress";
+}
+
+/** What the model reads: the cart, its totals as text, its issues, and the order it belongs to. Never a cost, never the envelope's limits. */
+export function viewOf(engine: ExecutionEngine, cart: Cart) {
+  const order = orderOf(engine, cart);
+  return {
+    cart_id: cart.cart_id,
+    version: cart.version,
+    status: statusOf(engine, cart),
+    currency: cart.currency,
+    line_items: cart.line_items.map((l) => ({
+      id: l.id,
+      sku: l.sku,
+      name: l.name,
+      quantity: l.quantity,
+      unit_price: formatBRL(l.unit_amount),
+      ...(l.discount_pct ? { discount_pct: l.discount_pct } : {}),
+      total: formatBRL(l.totals.find((t) => t.type === "total")!.amount),
+      availability_status: l.availability_status,
+    })),
+    coupon: cart.coupon,
+    totals: cart.totals.map((t) => ({ type: t.type, display_text: t.display_text, amount: formatBRL(t.amount) })),
+    total_minor: cart.total,
+    total: formatBRL(cart.total),
+    validation_issues: cart.validation_issues,
+    cart_hash: cart.cart_hash,
+    order: order ? { execution_id: order.id, state: order.state, ...(order.reason ? { reason: order.reason } : {}) } : null,
+  };
+}
+
+interface UpdateInput {
+  cart_id?: unknown;
+  lines?: unknown;
+  coupon?: unknown;
+  order_discount_pct?: unknown;
+}
+
+export interface CartDeps {
+  book: CartBook;
+  envelope: Envelope;
+  runId: string;
+  timezone: string;
+  clock: () => Date;
+  /** Called after a replacement, with the cart as it is now: an open order follows it (`bolepix-receivables`). */
+  onReplaced(cart: Cart, engine: ExecutionEngine): void;
+}
+
+/** The cart a call without `cart_id` means: the last one of this conversation that is still being assembled. */
+export function currentCart(engine: ExecutionEngine, deps: Pick<CartDeps, "book" | "runId">): Cart | undefined {
+  const cart = deps.book.latest(deps.runId);
+  return cart && !isLocked(engine, cart) ? cart : undefined;
+}
+
+export function resolveCart(engine: ExecutionEngine, deps: Pick<CartDeps, "book" | "runId">, cartId: unknown): Cart | undefined {
+  if (cartId === undefined || cartId === null || cartId === "") return deps.book.latest(deps.runId);
+  if (typeof cartId !== "string") throw new Error("cart_id must be a string (cart-1)");
+  const cart = deps.book.byId(deps.runId, cartId.trim());
+  if (!cart) throw new Error(`no cart ${cartId} in this conversation; carts: ${deps.book.idsOf(deps.runId).join(", ") || "none yet"}`);
+  return cart;
+}
+
+export function makeCartHandlers(deps: CartDeps): Record<string, ToolHandler> {
+  const listCatalog: ToolHandler = async () => ({
+    merchant: MERCHANT.name,
+    items: CATALOG.map((i) => ({
+      sku: i.sku,
+      title: i.title,
+      category: i.category,
+      price: formatBRL(i.price_minor),
+      price_minor: i.price_minor,
+      available: i.available,
+      ...(i.stock !== undefined ? { stock: i.stock } : {}),
+    })),
+    policy: {
+      service_hours: deps.envelope.service_hours,
+      payment: "bolepix (cobranca com vencimento): paga por Pix ou por boleto, vence hoje",
+      discounts: "so dentro da politica da loja, aplicada pelo codigo; o que estiver fora e recusado. Cupom: so os da tabela da loja, informados pelo cliente.",
+      prices: "sempre os do catalogo; nenhuma ferramenta aceita preco",
+    },
+  });
+
+  const cartView: ToolHandler = async (raw, ctx) => {
+    const input = raw as { cart_id?: unknown };
+    const cart = resolveCart(ctx.engine, deps, input.cart_id);
+    if (!cart) return { cart: null, message: "nenhum carrinho aberto nesta conversa; cart_update abre um" };
+    return viewOf(ctx.engine, cart);
+  };
+
+  const cartUpdate: ToolHandler = async (raw, ctx) => {
+    const input = raw as UpdateInput;
+    let target: Cart | undefined;
+    if (input.cart_id !== undefined && input.cart_id !== null && input.cart_id !== "") {
+      target = resolveCart(ctx.engine, deps, input.cart_id);
+      if (target && isLocked(ctx.engine, target)) throw new Error(`cart ${target.cart_id} is the record of an order whose charge is ${statusOf(ctx.engine, target) === "completed" ? "paid" : "out"}; it is not edited. Omit cart_id to open a new cart.`);
+    } else target = currentCart(ctx.engine, deps);
+
+    const now = deps.clock();
+    const priced = priceCart({ lines: input.lines, coupon: input.coupon, order_discount_pct: input.order_discount_pct }, deps.envelope, localDate(now, deps.timezone));
+    const cartId = target?.cart_id ?? deps.book.nextId(deps.runId);
+    const cart: Cart = {
+      ...priced,
+      cart_id: cartId,
+      ref: `${deps.runId}/${cartId}`,
+      run_id: deps.runId,
+      version: (target?.version ?? 0) + 1,
+      currency: "BRL",
+      order_discount_pct: typeof input.order_discount_pct === "number" ? input.order_discount_pct : 0,
+      updated_at: now.toISOString(),
+    };
+    deps.book.save(cart);
+    ctx.engine.note("cart.replaced", orderOf(ctx.engine, cart)?.id ?? null, {
+      cart_ref: cart.ref,
+      version: cart.version,
+      cart_hash: cart.cart_hash,
+      lines: cart.composition,
+      total_minor: cart.total,
+      validation_issues: cart.validation_issues.map((i: ValidationIssue) => ({ code: i.code, field: i.field })),
+    });
+    deps.onReplaced(cart, ctx.engine);
+    return viewOf(ctx.engine, cart);
+  };
+
+  return { list_catalog: listCatalog, cart_view: cartView, cart_update: cartUpdate };
+}