@extrovert.dev/sdk 0.1.0-pre.6 → 0.1.0-pre.8

package/dist/index.cjs

@@ -96,7 +96,7 @@ var ReviewConflictError = class extends ConflictError {
   }
   /**
    * Whether retrying the same call could ever succeed. False for every subclass
-   * except {@link StaleError} and {@link BornStaleError} — and true there only
+   * except {@link StaleError} and {@link BornStaleError} - and true there only
    * after re-reading and re-applying on top of the other party's change.
    */
   get isRetryable() {
@@ -268,7 +268,7 @@ var CURRENT_API_VERSION = "2026-06-23";
 var API_VERSION_HEADER = "Extrovert-Version";
 
 // src/http.ts
-var SDK_VERSION = "0.1.0-pre.6";
+var SDK_VERSION = "0.1.0-pre.8";
 function buildUrl(baseUrl, path, query) {
   const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   const rel = path.startsWith("/") ? path : `/${path}`;
@@ -642,7 +642,23 @@ function mailboxQuickstart(address) {
     }
   };
 }
-var SHARED_SUBDOMAIN = "smtp.extrovert.dev";
+var PAID_SHARED_DOMAIN = "extrovertmail.com";
+var FREE_SHARED_DOMAIN = "free.extrovertmail.com";
+var RESERVED_SHARED_LOCAL_PARTS = /* @__PURE__ */ new Set([
+  "postmaster",
+  "admin",
+  "webadmin",
+  "legal",
+  "fraudmark",
+  "fraudmarc",
+  "keith",
+  "melissa",
+  "richard",
+  "sydney",
+  "syd",
+  "john",
+  "johnny"
+]);
 var MOCK_ORG_ID = "org_mock";
 var MOCK_PROJECT_ID = "prj_mock";
 var DEFAULT_DAILY_SEND_LIMIT = 75;
@@ -659,6 +675,13 @@ function rid(prefix) {
 function randomHandle() {
   return `agent${Math.floor(1e3 + Math.random() * 9e3)}`;
 }
+function validatedSharedLocalPart(value) {
+  const normalized = value.toLowerCase().trim().replace(/[^a-z0-9._-]/g, "").replace(/^[._-]+|[._-]+$/g, "").slice(0, 40);
+  if (normalized.length < 5 || RESERVED_SHARED_LOCAL_PARTS.has(normalized)) {
+    throw new ValidationError({ status: 400, code: "invalid", message: "Shared-domain usernames must normalize to at least 5 characters and cannot use a reserved name." });
+  }
+  return normalized;
+}
 function assertProjectMatch(projectId) {
   if (projectId !== void 0 && projectId !== MOCK_PROJECT_ID) {
     throw new PermissionError({
@@ -747,6 +770,8 @@ function freshState() {
     contactLists: /* @__PURE__ */ new Map(),
     domains: /* @__PURE__ */ new Map(),
     jobs: /* @__PURE__ */ new Map(),
+    commerceRequests: /* @__PURE__ */ new Map(),
+    commerceByIdempotency: /* @__PURE__ */ new Map(),
     suppressions: seedSuppressions(),
     orgReviewPolicy: "require_review",
     inboxReviewPolicy: /* @__PURE__ */ new Map(),
@@ -877,7 +902,7 @@ function reviewConflict(code, review, detail) {
     }
   } else {
     fields.push(
-      { field: "revision", code: String(review.revision), detail: "current revision \u2014 use as parent_revision" },
+      { field: "revision", code: String(review.revision), detail: "current revision - use as parent_revision" },
       { field: "version", code: String(review.version), detail: "current row version" }
     );
   }
@@ -913,6 +938,8 @@ ${parent.text}`;
 var MockBackend = class {
   constructor() {
     this.state = freshState();
+    /** Save / edit a rule (mock) - append-only by supersession (D11). */
+    this.learnedRules = /* @__PURE__ */ new Map();
   }
   reset() {
     this.state = freshState();
@@ -936,7 +963,7 @@ var MockBackend = class {
       agent_id: agentId,
       agent_key: `pk_agent_proj_${agentId.slice(4)}_${rid("sk").slice(3)}`,
       scopes: ["mailbox:create", "mailbox:read", "mailbox:send", "webhook:write"],
-      // The minted key is bound to the token's resolved org/project; the agent cannot change it.
+      // The issued key is bound to the token's resolved org/project; the agent cannot change it.
       org_id: MOCK_ORG_ID,
       project_id: MOCK_PROJECT_ID
     };
@@ -951,7 +978,7 @@ var MockBackend = class {
     const existing = this.state.signupByEmail.get(email);
     const customerId = existing?.customerId ?? `cus_pn_signup_${rid("c").slice(2)}`;
     const agentId = existing?.agentId ?? rid("agt");
-    const address = existing?.address ?? `${req.username ?? randomHandle()}@smtp.extrovert.dev`;
+    const address = existing?.address ?? `${validatedSharedLocalPart(req.username ?? randomHandle())}@${FREE_SHARED_DOMAIN}`;
     const otp = "492013";
     this.state.signupByEmail.set(email, { customerId, agentId, address, otp, verified: false });
     return {
@@ -1007,8 +1034,10 @@ var MockBackend = class {
       }
     }
     const metadata = req.metadata ? mergeMetadata({}, req.metadata) : {};
-    const username = req.username ?? randomHandle();
-    const domain = req.domain ?? SHARED_SUBDOMAIN;
+    const domain = req.domain ?? PAID_SHARED_DOMAIN;
+    const normalizedDomain = domain.trim().toLowerCase();
+    const isSharedDomain = normalizedDomain === PAID_SHARED_DOMAIN || normalizedDomain === FREE_SHARED_DOMAIN;
+    const username = isSharedDomain ? validatedSharedLocalPart(req.username ?? randomHandle()) : req.username ?? randomHandle();
     const id = rid("ibx");
     const inbox = {
       object: "inbox",
@@ -1023,6 +1052,7 @@ var MockBackend = class {
       onboarding_mode: req.domain ? "ns_delegated" : "shared",
       agent_id: null,
       daily_send_limit: DEFAULT_DAILY_SEND_LIMIT,
+      direct_smtp_enabled: false,
       webhook_url: req.webhook_url ?? null,
       metadata,
       created_at: now(),
@@ -1061,7 +1091,7 @@ var MockBackend = class {
    * Normalize an inbox ref (opaque id OR address alias) to the canonical address the
    * mock keys its message/thread/contact maps on. The SDK now routes inbox ops by the
    * canonical opaque `id` when it holds a full record (matching the contract's
-   * canonical-key semantics), so the mock must resolve an id back to its address —
+   * canonical-key semantics), so the mock must resolve an id back to its address  -
    * both key `state.inboxes` (same object), `state.messages` keys by address only.
    * Unknown refs pass through unchanged so the existing not-found paths still fire.
    */
@@ -1260,8 +1290,8 @@ var MockBackend = class {
   }
   /**
    * Submit a new message for review (mock). Rides the SAME endpoint as `send` on
-   * the real server, so it is literally the same call here: the resolved policy —
-   * not which SDK method you picked — decides whether the message is queued
+   * the real server, so it is literally the same call here: the resolved policy  -
+   * not which SDK method you picked - decides whether the message is queued
    * (`kind:"queued_for_review"`) or delivered.
    */
   submitForReview(address, req) {
@@ -1343,7 +1373,7 @@ var MockBackend = class {
     this.state.reviews.set(review.id, review);
     this.enqueueTerminalNudge(review);
   }
-  /** Raw delivery for a send — no policy, only reachable from submitOutbound. */
+  /** Raw delivery for a send - no policy, only reachable from submitOutbound. */
   deliverSend(address, req) {
     return this.deliverRaw(address, {
       to: toArray(req.to),
@@ -1355,7 +1385,7 @@ var MockBackend = class {
       attachments: req.attachments
     });
   }
-  /** Raw delivery for a reply — no policy, only reachable from submitOutbound. */
+  /** Raw delivery for a reply - no policy, only reachable from submitOutbound. */
   deliverReply(address, req, env) {
     return this.deliverRaw(address, {
       to: env.to,
@@ -1393,6 +1423,13 @@ var MockBackend = class {
    * the server does before it writes the review row.
    */
   deriveReplyEnvelope(address, req) {
+    if (Boolean(req.thread_id) === Boolean(req.message_id)) {
+      throw new ValidationError({
+        status: 400,
+        code: "bad_request",
+        message: "provide exactly one of thread_id or message_id"
+      });
+    }
     const all = this.state.messages.get(address) ?? [];
     let parent;
     let threadId = req.thread_id;
@@ -1410,6 +1447,13 @@ var MockBackend = class {
         message: "thread_id or message_id is required"
       });
     }
+    if (req.thread_id && req.expected_last_message_id && parent?.id !== req.expected_last_message_id) {
+      throw new ConflictError({
+        status: 409,
+        code: "conflict",
+        message: `thread advanced; latest message is ${parent?.id ?? "unknown"}`
+      });
+    }
     const to = [];
     if (parent) {
       to.push(parent.from.email);
@@ -1668,7 +1712,7 @@ var MockBackend = class {
    * review id so a test can drive the reviewer decision plane offline. `createdAtMs`
    * (optional) backdates created_at so a test can trip the hard review_deadline breaker.
    */
-  seedReviewerHeldReview(opts = { fromAddress: "rep@smtp.extrovert.dev" }) {
+  seedReviewerHeldReview(opts = { fromAddress: "reviewer@extrovertmail.com" }) {
     const review = this.createReviewRecord(opts.fromAddress, {
       kind: "send",
       subject: "Pilot proposal",
@@ -1774,7 +1818,7 @@ var MockBackend = class {
   // ---- Category registry (Review Loop, D9/D10) --------------------------
   /**
    * Browse the registry (mock), newest-first, excluding merged/soft-deleted. `match`
-   * is a pure lexical filter (every token must appear in name+description) — NO LLM,
+   * is a pure lexical filter (every token must appear in name+description) - NO LLM,
    * mirroring the server.
    */
   listCategories(params = {}) {
@@ -1815,7 +1859,7 @@ var MockBackend = class {
     this.state.categories.set(cat.id, cat);
     return cat;
   }
-  /** Rename / re-describe a category (mock) — metadata only (D10). */
+  /** Rename / re-describe a category (mock) - metadata only (D10). */
   updateCategory(categoryId, req) {
     const cat = this.state.categories.get(categoryId);
     if (!cat) return void 0;
@@ -1825,7 +1869,7 @@ var MockBackend = class {
     this.state.categories.set(cat.id, cat);
     return cat;
   }
-  // ---- Graduation + risk dial (Review Loop, D16/D6/D17) — agent READ + PROPOSE --
+  // ---- Graduation + risk dial (Review Loop, D16/D6/D17) - agent READ + PROPOSE --
   /** The mock account-default risk dial (mirrors the server defaults). */
   accountDial() {
     return {
@@ -1841,7 +1885,7 @@ var MockBackend = class {
   /**
    * Read the effective risk dial (mock): the account default + every category with an
    * inherited (null override) effective dial. The mock category carries no overrides,
-   * so every category inherits — effective == account.
+   * so every category inherits - effective == account.
    */
   getRiskDial() {
     const account = this.accountDial();
@@ -1895,7 +1939,7 @@ var MockBackend = class {
   }
   /**
    * Propose graduating a category (mock): returns the current gate status without
-   * changing the category state (D16 — an agent can never flip the bit).
+   * changing the category state (D16 - an agent can never flip the bit).
    */
   proposeGraduation(categoryId, _req) {
     return this.getGraduationStatus(categoryId);
@@ -1904,7 +1948,7 @@ var MockBackend = class {
    * Read the D19/§8 backlog-reconciliation status (mock): counts the QUEUED drafts in a
    * category that are stale vs current-enough against the current rules-version. The
    * mock has no per-draft composed_* stamps on its Review fixtures, so every queued
-   * draft reads as current-enough (composed 0 vs current 0) — the contract shape is
+   * draft reads as current-enough (composed 0 vs current 0) - the contract shape is
    * exercised; the integer-compare logic is covered by the Go tests.
    */
   getScanBacklogStatus(categoryId) {
@@ -1928,7 +1972,7 @@ var MockBackend = class {
     };
   }
   /**
-   * Read the demand-driven pacing state (mock — M7 Slice B/§8): the cursor + effective
+   * Read the demand-driven pacing state (mock - M7 Slice B/§8): the cursor + effective
    * window/ceiling/interval + each queued draft's classification. The mock has no cursor
    * (nothing reviewed) and no composed_* stamps, so every queued draft reads in-window-
    * fresh until the window fills, then ahead; the contract shape is exercised (the
@@ -1968,7 +2012,7 @@ var MockBackend = class {
     const human = r.author_kind === "human" ? 1 : 0;
     return [hard, spec, human, r.rev, r.priority];
   }
-  /** Get the ORDERED active rule set (mock) — §7 ladder + category-before-general. */
+  /** Get the ORDERED active rule set (mock) - §7 ladder + category-before-general. */
   getRules(params = {}) {
     const active = [...this.state.rules.values()].filter((r) => r.status === "active");
     const byRank = (a, b) => {
@@ -2000,7 +2044,27 @@ var MockBackend = class {
       composition_token_expires_at: params.scope ? void 0 : new Date(Date.now() + 6e5).toISOString()
     };
   }
-  /** Save / edit a rule (mock) — append-only by supersession (D11). */
+  learnReviewRule(reviewId, req) {
+    const fingerprint = JSON.stringify({ reviewId, req });
+    const prior = this.learnedRules.get(req.client_id);
+    if (prior) {
+      if (prior.fingerprint !== fingerprint) throw new ValidationError({ status: 409, code: "conflict", message: "learning retry identity changed" });
+      return structuredClone(prior.result);
+    }
+    const turn = (this.state.reviewTurns.get(reviewId) ?? []).find((t) => t.id === req.source_turn_id);
+    if (!turn || turn.actor_kind !== "human" || !turn.actor_id) throw new ValidationError({ status: 403, code: "forbidden_scope", message: "learning requires authenticated human feedback" });
+    const rule = this.saveRule({ ...req, scope: req.target === "category" ? "category" : "general", source_review_id: reviewId, source_turn_id: turn.id });
+    rule.source_turn_id = turn.id;
+    rule.rule_layer = req.target === "org_house" ? "org" : "project";
+    if (req.target === "org_house") delete rule.project_id;
+    rule.source_review_id = reviewId;
+    rule.source_turn_id = turn.id;
+    const audit = [...this.state.ruleAudit.values()].find((entry) => entry.entity_id === rule.id);
+    audit.after_json = ruleSnapshotJSON(rule);
+    const result = { rule, source_review_id: reviewId, source_turn_id: turn.id, human_id: turn.actor_id, audit_id: audit.id, propagation: "queued" };
+    this.learnedRules.set(req.client_id, { fingerprint, result: structuredClone(result) });
+    return result;
+  }
   saveRule(req) {
     const text = req.rule_text.trim();
     if (!text) {
@@ -2089,7 +2153,7 @@ var MockBackend = class {
     this.recordRuleAudit("supersede", next.id, ruleSnapshotJSON(prior), ruleSnapshotJSON(next));
     return next;
   }
-  /** Retire a rule (mock) — soft delete, or undefined when unknown. */
+  /** Retire a rule (mock) - soft delete, or undefined when unknown. */
   retireRule(ruleId) {
     const rule = this.state.rules.get(ruleId);
     if (!rule) return void 0;
@@ -2107,7 +2171,7 @@ var MockBackend = class {
     if (params.entity_id) items = items.filter((e) => e.entity_id === params.entity_id);
     return { items, total: items.length };
   }
-  /** Undo a rule change (mock) — restore the prior version; idempotent (re-undo 409). */
+  /** Undo a rule change (mock) - restore the prior version; idempotent (re-undo 409). */
   undoRuleChange(udoId) {
     const entry = this.state.ruleAudit.get(udoId);
     if (!entry) throw new NotFoundError({ status: 404, code: "not_found", message: "audit row not found" });
@@ -2211,7 +2275,7 @@ var MockBackend = class {
     }
   }
   /**
-   * Enqueue `front_run_next` — the signal that the review reached a terminal state
+   * Enqueue `front_run_next` - the signal that the review reached a terminal state
    * while the agent was still trying to act on it.
    *
    * Deduped on (review, terminal state, parent revision) so a retry loop hitting
@@ -2252,8 +2316,8 @@ var MockBackend = class {
   }
   /**
    * Mock-only: mirror an approved draft whose delivery then FAILED at the provider.
-   * This is the case the composing agent was previously never told about — the
-   * console showed the error and the agent's queue stayed silent — so the loop test
+   * This is the case the composing agent was previously never told about - the
+   * console showed the error and the agent's queue stayed silent - so the loop test
    * that matters most drives this path.
    */
   simulateSendFailed(reviewId, error = "provider rejected the message") {
@@ -2338,7 +2402,7 @@ var MockBackend = class {
   }
   /**
    * Long-poll for a review event (mock). Offline there is nothing to wait FOR, so it
-   * returns the immediate drain (empty when caught up) — the server's "empty on
+   * returns the immediate drain (empty when caught up) - the server's "empty on
    * timeout" contract.
    */
   waitForReviewEvent(params = {}) {
@@ -2427,7 +2491,7 @@ var MockBackend = class {
       html: opts.html ?? null,
       extracted_text: opts.text.trim() || null,
       extracted_html: opts.html?.trim() || null,
-      message_id: `<${id}@${address.split("@")[1] ?? SHARED_SUBDOMAIN}>`,
+      message_id: `<${id}@${address.split("@")[1] ?? PAID_SHARED_DOMAIN}>`,
       folder: opts.direction === "inbound" ? "INBOX" : "Sent",
       seen: opts.direction === "outbound",
       date: now()
@@ -2543,10 +2607,10 @@ var MockBackend = class {
     if (offset + page.length < total) result.next_cursor = String(offset + page.length);
     return result;
   }
-  listThreads(address) {
+  listThreads(address, params = {}) {
     address = this.addrOf(address);
     const items = this.threadsFor(address);
-    return { items, total: items.length };
+    return this.paginateThreads(items, params);
   }
   /** Thread-level search (subject / snippet / participant substring). */
   searchThreads(address, params) {
@@ -2555,7 +2619,17 @@ var MockBackend = class {
     const items = this.threadsFor(address).filter(
       (t) => t.subject.toLowerCase().includes(q) || t.snippet.toLowerCase().includes(q) || t.participants.join(" ").toLowerCase().includes(q)
     );
-    return { items, total: items.length };
+    return this.paginateThreads(items, params);
+  }
+  paginateThreads(items, params) {
+    const total = items.length;
+    const cursorOffset = params.cursor === void 0 ? void 0 : Number(params.cursor);
+    const offset = params.offset ?? (Number.isFinite(cursorOffset) ? cursorOffset : 0);
+    const limit = params.limit ?? 25;
+    const page = items.slice(offset, offset + limit);
+    const result = { items: page, total };
+    if (offset + page.length < total) result.next_cursor = String(offset + page.length);
+    return result;
   }
   /** Fetch one thread (with messages, oldest-first) by id under an inbox. */
   getThread(address, threadId) {
@@ -2627,17 +2701,18 @@ var MockBackend = class {
       arr.push(m);
       byThread.set(m.thread_id, arr);
     }
-    const items = [...byThread.entries()].map(([id, ms]) => this.buildThread(address, id, ms));
+    const items = [...byThread.entries()].map(([id, ms]) => this.buildThread(address, id, ms, true));
     items.sort((a, b) => b.last_message_at.localeCompare(a.last_message_at));
     return items;
   }
-  buildThread(address, id, ms) {
+  buildThread(address, id, ms, summary = false) {
     const sorted = [...ms].sort((a, b) => a.date.localeCompare(b.date));
     const last = sorted[sorted.length - 1];
     const seen = /* @__PURE__ */ new Set();
     const participants = [];
-    for (const m of sorted) {
-      for (const a of [m.from, ...m.to]) {
+    const participantMessages = summary ? [last] : sorted;
+    for (const m of participantMessages) {
+      for (const a of [m.from, ...m.to, ...m.cc ?? [], ...m.reply_to ?? []]) {
         const key = a.email.toLowerCase();
         if (seen.has(key)) continue;
         seen.add(key);
@@ -2651,7 +2726,10 @@ var MockBackend = class {
       participants,
       message_count: sorted.length,
       last_message_at: last.date,
-      snippet: (last.text ?? last.html ?? "").slice(0, 120)
+      snippet: (last.text ?? last.html ?? "").slice(0, 120),
+      unread: !last.seen,
+      last_message_has_attachments: (this.state.attachments.get(last.id)?.length ?? 0) > 0,
+      last_message_id: last.id
     };
   }
   /**
@@ -2811,24 +2889,34 @@ ${text}`)) {
     return this.state.contactLists.delete(entryId);
   }
   // ---- domains (Slice 5) ------------------------------------------------
-  /** Onboard a domain, mirroring the server's per-mode record set + status. Idempotent on the name. */
+  /** Add a delegated domain and return only the customer-published nameservers. */
   onboardDomain(req) {
     assertProjectMatch(req.project_id);
     const name = req.domain.trim().toLowerCase();
     const existing = this.state.domains.get(name);
     if (existing) return { ...existing };
-    const mode = req.mode ?? "ns_delegated";
+    const mode = "ns_delegated";
     const domain = {
       id: rid("dom"),
       domain: name,
       mode,
-      verification_status: mode === "shared" ? "verified" : mode === "manual" ? "pending" : "verifying",
-      dkim_status: mode === "shared" ? "configured" : mode === "manual" ? "pending" : "configured",
-      shared: mode === "shared",
+      verification_status: "verifying",
+      dkim_status: "configured",
+      shared: false,
       created_at: now(),
-      records: mode === "manual" || mode === "ns_delegated" ? domainRecordSet(name) : void 0,
-      delegation_ns: mode === "ns_delegated" ? domainDelegationNS(name) : void 0,
-      instruction: mode === "shared" ? "Shared domain ready. No DNS changes required." : "Add the records, then trigger verification."
+      delegation_ns: domainDelegationNS(name),
+      instruction: "Add the nameserver entries at your domain provider. We check automatically; use Recheck DNS for an immediate check.",
+      readiness: {
+        status: "waiting_for_dns",
+        label: "Waiting for DNS",
+        summary: "We have not confirmed your nameserver entries yet. Add them at your domain provider; we will finish setup automatically.",
+        reason: "dns_entries_unconfirmed",
+        action_required_by: "customer",
+        next_action: "check_dns_entries",
+        ready_for_inboxes: false,
+        poll_after_seconds: 30,
+        inboxes: { scope: "agent", total: 0, ready: 0, setting_up: 0, needs_attention: 0 }
+      }
     };
     this.state.domains.set(name, domain);
     return { ...domain };
@@ -2876,6 +2964,129 @@ ${text}`)) {
     const job = this.state.jobs.get(jobId);
     return job ? { ...job } : void 0;
   }
+  // ---- commerce (quote/request/status; no human approval mutation) ------
+  quoteDomain(req) {
+    const domain = req.domain.trim().toLowerCase();
+    return {
+      object: "domain_quote",
+      domain,
+      available: !domain.startsWith("unavailable."),
+      currency: "usd",
+      quote_cents: 2500,
+      renewal_cents: 2500,
+      premium: false,
+      quote_expires_at: new Date(Date.now() + 15 * 60 * 1e3).toISOString(),
+      blockers: []
+    };
+  }
+  requestDomainPurchase(req) {
+    const idem = `domain_purchase:${req.idempotency_key.trim()}`;
+    const replayId = this.state.commerceByIdempotency.get(idem);
+    if (replayId) return { ...this.state.commerceRequests.get(replayId) };
+    const quote = this.quoteDomain({ domain: req.domain });
+    const timestamp = now();
+    const id = rid("creq");
+    const approvalUrl = `https://app.extrovert.dev/commerce/requests/${id}`;
+    const request = {
+      object: "commerce_request",
+      id,
+      kind: "domain_purchase",
+      state: "awaiting_human_approval",
+      domain: quote.domain,
+      domain_scope: req.scope ?? "org",
+      rationale: req.rationale,
+      currency: quote.currency,
+      quote_cents: quote.quote_cents,
+      renewal_cents: quote.renewal_cents,
+      quote_expires_at: quote.quote_expires_at,
+      auto_renew: req.auto_renew ?? true,
+      blocker_code: "human_approval_required",
+      blockers: [
+        {
+          code: "human_approval_required",
+          message: "A human billing administrator must approve this domain purchase.",
+          manage_url: approvalUrl
+        }
+      ],
+      approval_url: approvalUrl,
+      agent_next_action: "Share approval_url with the human, then poll this request after approval.",
+      retry_safe: true,
+      poll_after_seconds: 10,
+      version: 1,
+      created_at: timestamp,
+      updated_at: timestamp
+    };
+    this.state.commerceRequests.set(id, request);
+    this.state.commerceByIdempotency.set(idem, id);
+    return { ...request };
+  }
+  requestPlanChange(req) {
+    const idem = `plan_change:${req.idempotency_key.trim()}`;
+    const replayId = this.state.commerceByIdempotency.get(idem);
+    if (replayId) return { ...this.state.commerceRequests.get(replayId) };
+    const timestamp = now();
+    const id = rid("creq");
+    const approvalUrl = `https://app.extrovert.dev/commerce/requests/${id}`;
+    const request = {
+      object: "commerce_request",
+      id,
+      kind: "plan_change",
+      state: "awaiting_human_approval",
+      target_plan: req.target_plan,
+      current_plan: "developer",
+      rationale: req.rationale,
+      currency: "usd",
+      quote_cents: 0,
+      renewal_cents: 0,
+      auto_renew: true,
+      blocker_code: "human_approval_required",
+      blockers: [
+        {
+          code: "human_approval_required",
+          message: "A human billing administrator must approve this plan change.",
+          manage_url: approvalUrl
+        }
+      ],
+      approval_url: approvalUrl,
+      agent_next_action: "Share approval_url with the human, then poll this request after approval.",
+      retry_safe: true,
+      poll_after_seconds: 10,
+      version: 1,
+      created_at: timestamp,
+      updated_at: timestamp
+    };
+    this.state.commerceRequests.set(id, request);
+    this.state.commerceByIdempotency.set(idem, id);
+    return { ...request };
+  }
+  getCommerceRequest(requestId) {
+    const request = this.state.commerceRequests.get(requestId);
+    return request ? { ...request } : void 0;
+  }
+  cancelCommerceRequest(requestId) {
+    const request = this.state.commerceRequests.get(requestId);
+    if (!request) return void 0;
+    if (!["awaiting_human_approval", "blocked", "approved", "payment_action_required", "payment_failed"].includes(request.state)) {
+      throw new ValidationError({ status: 409, code: "conflict", message: "this request can no longer be cancelled" });
+    }
+    request.state = "cancelled";
+    request.blocker_code = void 0;
+    request.blockers = [];
+    request.agent_next_action = "The request is cancelled. Create a new request only if the purchase is still needed.";
+    request.version += 1;
+    request.updated_at = now();
+    return { ...request };
+  }
+  listCommerceRequests(params = {}) {
+    let items = [...this.state.commerceRequests.values()];
+    items.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    const total = items.length;
+    const offset = params.page ? Math.max(0, Number.parseInt(params.page, 10) || 0) : 0;
+    const limit = Math.max(1, Math.min(params.limit ?? 50, 100));
+    const page = items.slice(offset, offset + limit).map((request) => ({ ...request }));
+    const next = offset + page.length;
+    return { items: page, total, next_cursor: next < total ? String(next) : void 0 };
+  }
   // ---- suppressions (recipient opt-outs / list-unsubscribe) --------------
   /**
    * Pre-check whether the caller's org suppresses a recipient (mirrors
@@ -2919,7 +3130,7 @@ ${text}`)) {
   /**
    * Reject the WHOLE send if ANY recipient has an active org-scope suppression,
    * naming exactly the suppressed addresses (never the scope/origin) so the caller
-   * can drop them and retry — mirroring the live `recipient_suppressed` (422) path.
+   * can drop them and retry - mirroring the live `recipient_suppressed` (422) path.
    */
   enforceSuppression(recipients) {
     const active = new Set(
@@ -3002,16 +3213,6 @@ function redactSecret(w) {
   const { secret: _omit, ...rest } = w;
   return rest;
 }
-function domainRecordSet(domain) {
-  const dkimSuffix = domain.replace(/\./g, "-");
-  return [
-    { name: domain, type: "MX", value: "smtp.extrovert.dev", priority: 10, ttl: 3600 },
-    { name: domain, type: "TXT", value: "v=spf1 include:spf.protection.outlook.com -all", ttl: 3600 },
-    { name: `_dmarc.${domain}`, type: "TXT", value: "v=DMARC1; p=none; rua=mailto:dmarc@smtp.extrovert.dev", ttl: 3600 },
-    { name: `selector1._domainkey.${domain}`, type: "CNAME", value: `selector1-${dkimSuffix}._domainkey.azurecomm.net`, ttl: 3600 },
-    { name: `selector2._domainkey.${domain}`, type: "CNAME", value: `selector2-${dkimSuffix}._domainkey.azurecomm.net`, ttl: 3600 }
-  ];
-}
 function domainDelegationNS(domain) {
   return [
     { name: domain, type: "NS", value: "ns1.extrovert.dev", ttl: 300 },
@@ -3395,8 +3596,11 @@ var HttpTransport = class {
       signal
     });
   }
-  listDomains(signal) {
-    return this.call({ method: "GET", path: "/v1/domains", signal });
+  listDomains(signal, params = {}) {
+    return this.call({ method: "GET", path: "/v1/domains", query: params, signal });
+  }
+  listDomainEvents(domain, params, signal) {
+    return this.call({ method: "GET", path: `/v1/domains/${encodeURIComponent(domain)}/events`, query: params, signal });
   }
   getDomain(domain, signal) {
     return this.call({ method: "GET", path: `/v1/domains/${encodeURIComponent(domain)}`, signal });
@@ -3404,6 +3608,8 @@ var HttpTransport = class {
   onboardDomain(req, signal) {
     return this.call({ method: "POST", path: "/v1/domains", body: req, signal });
   }
+  // Delegated domains perform an immediate authoritative DNS check. Inspect
+  // delegation.status separately from mail readiness; 429 requests may be retried.
   verifyDomain(domain, signal) {
     return this.call({
       method: "POST",
@@ -3428,6 +3634,54 @@ var HttpTransport = class {
   getJob(jobId, signal) {
     return this.call({ method: "GET", path: `/v1/jobs/${encodeURIComponent(jobId)}`, signal });
   }
+  quoteDomain(req, signal) {
+    return this.call({ method: "POST", path: "/v1/commerce/domain-quotes", body: req, signal });
+  }
+  requestDomainPurchase(req, signal) {
+    const { idempotency_key, ...body } = req;
+    return this.call({
+      method: "POST",
+      path: "/v1/commerce/requests/domain-purchases",
+      body,
+      idempotencyKey: idempotency_key,
+      signal
+    });
+  }
+  requestPlanChange(req, signal) {
+    const { idempotency_key, ...body } = req;
+    return this.call({
+      method: "POST",
+      path: "/v1/commerce/requests/plan-changes",
+      body,
+      idempotencyKey: idempotency_key,
+      signal
+    });
+  }
+  getCommerceRequest(requestId, signal) {
+    return this.call({
+      method: "GET",
+      path: `/v1/commerce/requests/${encodeURIComponent(requestId)}`,
+      signal
+    });
+  }
+  cancelCommerceRequest(requestId, signal) {
+    return this.call({
+      method: "POST",
+      path: `/v1/commerce/requests/${encodeURIComponent(requestId)}/cancel`,
+      signal
+    });
+  }
+  listCommerceRequests(params, signal) {
+    return this.call({
+      method: "GET",
+      path: "/v1/commerce/requests",
+      query: {
+        limit: params.limit,
+        page: params.page
+      },
+      signal
+    });
+  }
   submitForReview(address, req, signal) {
     return this.call({
       method: "POST",
@@ -3451,6 +3705,7 @@ var HttpTransport = class {
       state: Array.isArray(params.state) ? params.state.join(",") : params.state,
       category_id: params.category_id,
       inbox: params.inbox,
+      composer: params.composer,
       limit: params.limit,
       page: params.page
     };
@@ -3533,10 +3788,12 @@ var HttpTransport = class {
     });
   }
   waitForReviewEvent(params, signal) {
+    const waitSeconds = Math.min(55, Math.max(1, params.wait_seconds ?? 55));
     return this.call({
       method: "GET",
       path: "/v1/reviews/events/wait",
-      query: { review_id: params.review_id, limit: params.limit, wait_seconds: params.wait_seconds },
+      query: { review_id: params.review_id, limit: params.limit, wait_seconds: waitSeconds },
+      timeoutMs: (waitSeconds + 10) * 1e3,
       signal
     });
   }
@@ -3605,6 +3862,9 @@ var HttpTransport = class {
       signal
     });
   }
+  learnReviewRule(reviewId, req, signal) {
+    return this.call({ method: "POST", path: `/v1/reviews/${encodeURIComponent(reviewId)}/learned-rules`, body: req, signal });
+  }
   saveRule(req, signal) {
     return this.call({
       method: "PUT",
@@ -3786,8 +4046,8 @@ var MockTransport = class {
   async searchMessages(address, params) {
     return this.backend.searchMessages(address, params);
   }
-  async listThreads(address, _params) {
-    return this.backend.listThreads(address);
+  async listThreads(address, params) {
+    return this.backend.listThreads(address, params);
   }
   async searchThreads(address, params) {
     return this.backend.searchThreads(address, params);
@@ -3851,8 +4111,16 @@ var MockTransport = class {
     if (!row) throw notFound("suppression", id);
     return row;
   }
-  async listDomains() {
-    return this.backend.listDomains();
+  async listDomains(_signal, params = {}) {
+    const page = this.backend.listDomains();
+    const offset = Number(params.page ?? 0);
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new Error("Invalid page cursor");
+    const items = page.items.slice(offset, offset + (params.limit ?? 50));
+    return { items, total: page.total, next_cursor: offset + items.length < page.items.length ? String(offset + items.length) : void 0 };
+  }
+  async listDomainEvents(domain, params) {
+    if (!this.backend.getDomain(domain)) throw notFound("domain", domain);
+    return { items: [], next_cursor: params.after ?? "0", has_more: false, poll_after_seconds: 30 };
   }
   async getDomain(domain) {
     const d = this.backend.getDomain(domain);
@@ -3877,6 +4145,28 @@ var MockTransport = class {
     if (!job) throw notFound("job", jobId);
     return job;
   }
+  async quoteDomain(req) {
+    return this.backend.quoteDomain(req);
+  }
+  async requestDomainPurchase(req) {
+    return this.backend.requestDomainPurchase(req);
+  }
+  async requestPlanChange(req) {
+    return this.backend.requestPlanChange(req);
+  }
+  async getCommerceRequest(requestId) {
+    const request = this.backend.getCommerceRequest(requestId);
+    if (!request) throw notFound("commerce request", requestId);
+    return request;
+  }
+  async cancelCommerceRequest(requestId) {
+    const request = this.backend.cancelCommerceRequest(requestId);
+    if (!request) throw notFound("commerce request", requestId);
+    return request;
+  }
+  async listCommerceRequests(params) {
+    return this.backend.listCommerceRequests(params);
+  }
   async submitForReview(address, req) {
     return this.backend.submitForReview(address, req);
   }
@@ -3982,6 +4272,9 @@ var MockTransport = class {
   async getRules(params) {
     return this.backend.getRules(params);
   }
+  async learnReviewRule(reviewId, req) {
+    return this.backend.learnReviewRule(reviewId, req);
+  }
   async saveRule(req) {
     return this.backend.saveRule(req);
   }
@@ -4031,6 +4324,49 @@ function filenameFromDisposition(disposition) {
   return m ? decodeURIComponent(m[1].trim()) : "";
 }
 
+// src/domain-wait.ts
+async function waitForDomain(get, options = {}) {
+  const seconds = options.timeout_seconds ?? 45;
+  if (!Number.isInteger(seconds) || seconds < 0 || seconds > 50) throw new Error("timeout_seconds must be an integer between 0 and 50");
+  const deadline = AbortSignal.timeout(Math.max(1, seconds * 1e3));
+  const signal = options.signal ? AbortSignal.any([options.signal, deadline]) : deadline;
+  let latest;
+  const result = (outcome) => ({
+    domain: latest,
+    outcome,
+    resume_after_seconds: outcome === "timed_out" ? Math.max(5, Math.min(60, latest?.readiness?.poll_after_seconds ?? 30)) : 0
+  });
+  try {
+    const singleCheckDeadline = seconds === 0 ? AbortSignal.timeout(1e4) : void 0;
+    latest = await get(singleCheckDeadline ? options.signal ? AbortSignal.any([options.signal, singleCheckDeadline]) : singleCheckDeadline : signal);
+    for (; ; ) {
+      const r = latest.readiness;
+      if (!r) return result("status_unavailable");
+      if (r.ready_for_inboxes) return result("ready");
+      if (r.action_required_by === "customer") return result("action_required");
+      if (r.status === "needs_attention") return result("needs_attention");
+      if (seconds === 0) return result("timed_out");
+      await new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const abort = () => {
+          clearTimeout(timer);
+          reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+          signal.removeEventListener("abort", abort);
+          resolve();
+        }, Math.max(5, Math.min(60, r.poll_after_seconds || 30)) * 1e3);
+        signal.addEventListener("abort", abort, { once: true });
+      });
+      latest = await get(signal);
+    }
+  } catch (error) {
+    if (options.signal?.aborted) throw options.signal.reason;
+    if (deadline.aborted && latest) return result("timed_out");
+    throw error;
+  }
+}
+
 // src/key-tier.ts
 var AGENT_HEAD = "pk_agent_";
 function parseKeyTier(apiKey) {
@@ -4115,8 +4451,8 @@ var InboxHandle = class {
    * Returns a three-way {@link SendOutcome}: `kind:"queued_for_review"` means a
    * human has to approve it and NOTHING has been delivered yet; anything else was
    * delivered. Under the default `require_review` policy a call WITHOUT an
-   * `intent` raises `IntentRequiredError` (422) instead — nothing sent, nothing
-   * queued — so pass one, or read `inbox.record.effective_review_policy` first.
+   * `intent` raises `IntentRequiredError` (422) instead: nothing sent, nothing
+   * queued: so pass one, or read `inbox.record.effective_review_policy` first.
    */
   send(req, signal) {
     return this.transport.send(this.ref, req, signal);
@@ -4126,7 +4462,7 @@ var InboxHandle = class {
    * the latest message) or `message_id` (reply to that message); the server
    * derives To / Subject / In-Reply-To / References. Set `reply_all` to reply to
    * every thread recipient. Returns the same three-way {@link SendOutcome} as
-   * {@link send} — a reply is governed by the review policy too.
+   * {@link send}: a reply is governed by the review policy too.
    */
   reply(req, signal) {
     return this.transport.reply(this.ref, req, signal);
@@ -4135,7 +4471,7 @@ var InboxHandle = class {
    * Forward a message in this inbox to new recipients, preserving the original.
    *
    * A forward is an outbound message to arbitrary NEW recipients that quotes an
-   * inbound thread, so it is governed by the review policy exactly like a send —
+   * inbound thread, so it is governed by the review policy exactly like a send :
    * same {@link SendOutcome} union, same `intent` requirement.
    */
   forward(messageId, req, signal) {
@@ -4299,7 +4635,7 @@ var ListPage = class _ListPage {
     this.nextCursor = raw.next_cursor;
   }
   /**
-   * Fetch the next page. Throws if there is none — guard with {@link hasMore}.
+   * Fetch the next page. Throws if there is none - guard with {@link hasMore}.
    */
   async nextPage(signal) {
     if (!this.hasMore || this.nextCursor === null) {
@@ -4387,8 +4723,8 @@ var ProjectInboxes = class {
    * Returns a three-way {@link SendOutcome}: `kind:"queued_for_review"` means a
    * human has to approve it and NOTHING has been delivered yet; anything else was
    * delivered. Under the default `require_review` policy a call WITHOUT an
-   * `intent` raises `IntentRequiredError` (422) instead — nothing sent, nothing
-   * queued — so pass one, or read `inbox.record.effective_review_policy` first.
+   * `intent` raises `IntentRequiredError` (422) instead: nothing sent, nothing
+   * queued: so pass one, or read `inbox.record.effective_review_policy` first.
    */
   send(projectId, inboxId, req, signal) {
     return this.ctx.transport.send(this.ref(projectId, inboxId), req, signal);
@@ -4454,14 +4790,14 @@ var ProjectInboxes = class {
    *
    * The frozen contract project-prefixes ONLY the inbox collection/item/credentials
    * routes (`/v1/projects/{project_id}/inboxes[/{inbox_id}][/credentials]`); the
-   * send/reply/forward/message/thread/wait sub-ops have NO project-prefixed path —
+   * send/reply/forward/message/thread/wait sub-ops have NO project-prefixed path :
    * they address the inbox by its opaque id directly (`/v1/inboxes/{inbox_id}/…`),
    * where the project is implicit in (and enforced by) the inbox id server-side.
    *
    * So for these sub-ops `projectId` cannot be carried on the URL and is NOT a URL
    * selector. The adversarial review flagged that silently discarding it makes the
    * signature misleading. CHOICE: keep the arg (dropping it would break the chain's
-   * symmetry with create/list/get/update/delete — the more disruptive option) but
+   * symmetry with create/list/get/update/delete: the more disruptive option) but
    * VALIDATE it rather than ignore it. We reject the two client mistakes we can catch
    * without a round-trip:
    *   - a blank / whitespace-only `projectId` (a required selector everywhere else in
@@ -4500,8 +4836,9 @@ var Inboxes = class {
     this.ctx = ctx;
   }
   /**
-   * Create an inbox. The default path mints an address on a pre-verified shared subdomain of
-   * `smtp.extrovert.dev`, so it returns a live, send-and-receive-capable inbox in one call.
+   * Create an inbox. The default path creates an address on `extrovertmail.com`
+   * for paid accounts or `free.extrovertmail.com` for free signups, so it returns
+   * a live inbox in one call.
    *
    * Pass `metadata` to attach arbitrary key-value data, and `client_id` for idempotent creation
    * (re-calling with the same id returns the same inbox, with its metadata replayed verbatim).
@@ -4511,12 +4848,12 @@ var Inboxes = class {
     return new InboxHandle(this.ctx.transport, inbox.address, this.ctx.handleOptions, inbox);
   }
   /**
-   * List inboxes visible to the calling key (the bare curl-sugar surface — resolves
+   * List inboxes visible to the calling key (the bare curl-sugar surface: resolves
    * to the key's default project). An org-tier key has no single default project, so
    * the bare list is ambiguous: fail fast client-side with a BreadthRequiredError that
    * names the next call, matching the MCP surface, instead of round-tripping to a 400.
    * Use `extrovert.projects.inboxes.list("<project_id>")` or `"-"` (org subtree) for
-   * an org key. The check is advisory — the server stays authoritative.
+   * an org key. The check is advisory: the server stays authoritative.
    */
   list(params = {}, signal) {
     if (tierNeedsExplicitBreadth(this.ctx.keyTier)) {
@@ -4612,10 +4949,22 @@ var Threads = class {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  /** List conversations newest-active first. Pass `next_cursor` back as `cursor` for the next page. */
+  list(inbox, params = {}, signal) {
+    return this.ctx.transport.listThreads(inbox, params, signal);
+  }
+  /** Search thread subjects, snippets, and participants. Cursor pagination matches {@link list}. */
+  search(inbox, params, signal) {
+    return this.ctx.transport.searchThreads(inbox, params, signal);
+  }
   /** Fetch one thread (+ its messages, oldest-first) by id under its owning inbox address. */
   get(inbox, threadId, signal) {
     return this.ctx.transport.getThread(inbox, threadId, signal);
   }
+  /** Reply in a thread; recipients and RFC reply headers are derived server-side. */
+  reply(inbox, req, signal) {
+    return this.ctx.transport.reply(inbox, req, signal);
+  }
   /**
    * Delete an entire thread (every message): move to Trash (default) or
    * permanently remove when `expunge` is true. `inbox` is the owning address.
@@ -4677,7 +5026,7 @@ var Suppressions = class {
   }
   /**
    * Pre-check whether the caller's org already suppresses a recipient, BEFORE
-   * composing. `suppressed: true` means a send to them would be rejected — skip
+   * composing. `suppressed: true` means a send to them would be rejected: skip
    * that recipient. Returns the matching org rows too (never a global/shared row).
    */
   precheck(recipient, signal) {
@@ -4701,17 +5050,25 @@ var Domains = class {
     this.ctx = ctx;
   }
   /** List the customer's onboarded domains and their status. */
-  list(signal) {
-    return this.ctx.transport.listDomains(signal);
+  list(paramsOrSignal = {}, signal) {
+    if ("aborted" in paramsOrSignal) return this.ctx.transport.listDomains(paramsOrSignal);
+    return this.ctx.transport.listDomains(signal, paramsOrSignal);
   }
-  /** Get one domain's detail + verification status + the DNS records to set, inline. */
+  /** Get one domain's detail, verification status, and nameserver records. */
   get(domain, signal) {
     return this.ctx.transport.getDomain(domain, signal);
   }
+  /** Wait up to 50 seconds, then return an explicit resumable outcome. No DNS writes. */
+  wait(domain, options = {}) {
+    return waitForDomain((signal) => this.ctx.transport.getDomain(domain, signal), options);
+  }
+  /** Resume durable updates for this domain using the previous next_cursor as after. */
+  events(domain, params = {}, signal) {
+    return this.ctx.transport.listDomainEvents(domain, params, signal);
+  }
   /**
-   * Onboard (add) a domain. `mode` defaults to ns_delegated. `mode: "purchased"`
-   * requires the `domain:purchase` scope (in addition to `domain:manage`). Returns
-   * the record set / NS instruction.
+   * Add a delegated inbox domain the customer controls. Returns the nameserver
+   * records to publish and never spends money.
    */
   onboard(req, signal) {
     return this.ctx.transport.onboardDomain(req, signal);
@@ -4730,6 +5087,46 @@ var Domains = class {
     return this.ctx.transport.offboardDomain(domain, signal);
   }
 };
+var Commerce = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  requireIdempotencyKey(value) {
+    if (value.trim().length < 8) {
+      throw new ValidationError({
+        status: 400,
+        code: "bad_request",
+        message: "idempotency_key must be a stable value of at least 8 characters; reuse it for retries of the same intent."
+      });
+    }
+  }
+  /** Quote a domain without purchasing, reserving, or approving it. */
+  quoteDomain(req, signal) {
+    return this.ctx.transport.quoteDomain(req, signal);
+  }
+  /** Create a durable domain-purchase request for human approval. */
+  requestDomainPurchase(req, signal) {
+    this.requireIdempotencyKey(req.idempotency_key);
+    return this.ctx.transport.requestDomainPurchase(req, signal);
+  }
+  /** Create a durable plan-upgrade or downgrade request for human approval. */
+  requestPlanChange(req, signal) {
+    this.requireIdempotencyKey(req.idempotency_key);
+    return this.ctx.transport.requestPlanChange(req, signal);
+  }
+  /** Poll one request's exact blockers, approval URL, and next-action guidance. */
+  get(requestId, signal) {
+    return this.ctx.transport.getCommerceRequest(requestId, signal);
+  }
+  /** Withdraw this agent's request while its durable state still permits cancellation. */
+  cancel(requestId, signal) {
+    return this.ctx.transport.cancelCommerceRequest(requestId, signal);
+  }
+  /** List visible commerce requests using the API's opaque page token. */
+  list(params = {}, signal) {
+    return this.ctx.transport.listCommerceRequests(params, signal);
+  }
+};
 var Reviews = class {
   constructor(ctx) {
     this.ctx = ctx;
@@ -4750,7 +5147,7 @@ var Reviews = class {
   /**
    * Get the human's assembled feedback (M5): the diff + comments + decision + the
    * rules born from this review. Read it after a rejected/edited nudge to learn what
-   * the human wanted. $0 LLM — pure assembly on our side.
+   * the human wanted. $0 LLM: pure assembly on our side.
    */
   feedback(reviewId, signal) {
     return this.ctx.transport.getReviewFeedback(reviewId, signal);
@@ -4758,7 +5155,7 @@ var Reviews = class {
   /**
    * Post a chat turn on a review's thread (M5): an agent question to the human
    * reviewer; flips in_review -> chatting on the first turn. Idempotent on the
-   * optional `idempotencyKey` (the `Idempotency-Key` header). $0 LLM — you compose it.
+   * optional `idempotencyKey` (the `Idempotency-Key` header). $0 LLM: you compose it.
    */
   chat(reviewId, req, idempotencyKey, signal) {
     return this.ctx.transport.postReviewChat(reviewId, req, idempotencyKey, signal);
@@ -4766,8 +5163,8 @@ var Reviews = class {
   /**
    * Post a new agent draft under a parent_revision CAS (M5; D17). parent_revision
    * must equal the draft's current revision, else a 409 STALE with NO mutation (the
-   * human always wins — re-read, re-apply, retry). On success the draft is re-rendered
-   * in place (revision++) and returns to needs_review. $0 LLM — you compose the redraft.
+   * human always wins: re-read, re-apply, retry). On success the draft is re-rendered
+   * in place (revision++) and returns to needs_review. $0 LLM: you compose the redraft.
    */
   revise(reviewId, req, signal) {
     return this.ctx.transport.submitRevision(reviewId, req, signal);
@@ -4786,9 +5183,9 @@ var Reviews = class {
    * assert "I reviewed this against rules vX and no change is needed", advancing the
    * draft's composed_* versions with no new draft, no revision bump, no nudge. A
    * born-stale draft re-stamped to the current version becomes current-enough and
-   * releasable on the next reconciliation sweep — the cheap counterpart to revise().
+   * releasable on the next reconciliation sweep: the cheap counterpart to revise().
    * against_version above the category's current rules-version is 400; a terminal draft
-   * 409s. $0 LLM — you judged.
+   * 409s. $0 LLM: you judged.
    */
   restamp(reviewId, req, signal) {
     return this.ctx.transport.restampReview(reviewId, req, signal);
@@ -4807,13 +5204,13 @@ var Reviews = class {
   }
   /**
    * Submit a reviewer decision (M8 Slice B; reviewer_decide, D5/§9). approve/edit → the
-   * PLATFORM ACS-sends with the COMPOSER's credentials (the reviewer NEVER holds
-   * mailbox:send on an inbox it doesn't own — the credential boundary); reject → back to
+   * PLATFORM sends with the COMPOSER's credentials (the reviewer NEVER holds
+   * mailbox:send on an inbox it doesn't own: the credential boundary); reject → back to
    * the composer (needs_review, hop_count++); escalate → the human queue. revision/
-   * version are the CAS (409 STALE on mismatch, NO mutation — the human always wins,
+   * version are the CAS (409 STALE on mismatch, NO mutation: the human always wins,
    * D17). The two circuit breakers (hop_count ≥ max_hops, or the hard review_deadline)
-   * FORCE a reject to the human regardless of intent — `forced_by_breaker` names it. $0
-   * LLM — you judged; we route, send, and enforce the breakers.
+   * FORCE a reject to the human regardless of intent: `forced_by_breaker` names it. $0
+   * LLM: you judged; we route, send, and enforce the breakers.
    */
   decide(reviewId, req, signal) {
     return this.ctx.transport.reviewerDecide(reviewId, req, signal);
@@ -4852,14 +5249,14 @@ var Categories = class {
   propose(req, signal) {
     return this.ctx.transport.proposeCategory(req, signal);
   }
-  /** Rename / re-describe a category — metadata only (D10). */
+  /** Rename / re-describe a category: metadata only (D10). */
   update(categoryId, req, signal) {
     return this.ctx.transport.updateCategory(categoryId, req, signal);
   }
   /**
    * Read the effective risk dial (D4/D12): the account default + every category's
    * overrides (each with its resolved effective value; null override = inherit).
-   * Read-only — agents read but NEVER flip the dial; setting it is a human (console)
+   * Read-only: agents read but NEVER flip the dial; setting it is a human (console)
    * action (D16).
    */
   riskDial(signal) {
@@ -4875,7 +5272,7 @@ var Categories = class {
   }
   /**
    * Propose graduating a category (D16/D6): RECORDS the request (durable evidence) and
-   * returns the current gate status. It does NOT change the category state — flipping
+   * returns the current gate status. It does NOT change the category state: flipping
    * the bit is a human (console) action; an agent only proposes.
    */
   proposeGraduation(categoryId, req = {}, signal) {
@@ -4884,7 +5281,7 @@ var Categories = class {
   /**
    * Read the D19/§8 backlog-reconciliation status: how many of the category's QUEUED
    * drafts are stale vs current-enough against the current rules-version (a pure
-   * integer compare, $0 LLM). Read-only — you READ the picture; the human (console
+   * integer compare, $0 LLM). Read-only: you READ the picture; the human (console
    * scan-backlog) or the graduate/rule-change hooks TRIGGER the actual reconciliation
    * sweep that releases current-enough drafts and nudges stale ones to redraft.
    */
@@ -4907,6 +5304,10 @@ var Rules = class {
   constructor(ctx) {
     this.ctx = ctx;
   }
+  /** Learn category or organization house rules from verified human review feedback. */
+  learnFromReview(reviewId, req, signal) {
+    return this.ctx.transport.learnReviewRule(reviewId, req, signal);
+  }
   /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
   get(params = {}, signal) {
     return this.ctx.transport.getRules(params, signal);
@@ -4914,8 +5315,8 @@ var Rules = class {
   /**
    * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
    * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
-   * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
-   * rules in v1 — that is a console/admin action.
+   * key's project. For org-layer house rules use learnFromReview with an authenticated human source; this method cannot author (`rule_layer:"org"`)
+   * rules in v1: that is a console/admin action.
    */
   save(req, signal) {
     return this.ctx.transport.saveRule(req, signal);
@@ -4924,7 +5325,7 @@ var Rules = class {
   promote(ruleId, toScope, signal) {
     return this.ctx.transport.promoteRule(ruleId, toScope, signal);
   }
-  /** Retire a rule — soft delete; the history survives as training data. */
+  /** Retire a rule: soft delete; the history survives as training data. */
   retire(ruleId, signal) {
     return this.ctx.transport.retireRule(ruleId, signal);
   }
@@ -4932,7 +5333,7 @@ var Rules = class {
   audit(params = {}, signal) {
     return this.ctx.transport.getRuleAudit(params, signal);
   }
-  /** Undo a rule change by its audit-row id (udo_…) — restore the prior version. */
+  /** Undo a rule change by its audit-row id (udo_…): restore the prior version. */
   undo(udoId, signal) {
     return this.ctx.transport.undoRuleChange(udoId, signal);
   }
@@ -4989,26 +5390,29 @@ var ExtrovertClient = class _ExtrovertClient {
     this.contactLists = new ContactLists(ctx);
     this.suppressions = new Suppressions(ctx);
     this.domains = new Domains(ctx);
+    this.commerce = new Commerce(ctx);
     this.reviews = new Reviews(ctx);
     this.categories = new Categories(ctx);
     this.rules = new Rules(ctx);
     this.projects = new Projects(ctx);
   }
   /**
-   * Redeem an enrollment token (`pk_enroll_...`) and mint a scoped agent key.
+   * Redeem an enrollment token (`pk_enroll_...`) and issue a scoped agent key.
    *
    * Idempotent on `agent_handle`: redeeming twice with the same handle returns the same agent.
-   * Returns the raw `EnrollResponse` — to immediately use the minted key, prefer
+   * Returns the raw `EnrollResponse` - to immediately use the issued key, prefer
    * {@link ExtrovertClient.enrolled}.
    */
   enroll(req, signal) {
     return this.transport.enroll(req, signal);
   }
   /**
-   * Grab a free account in one unauthenticated call (Slice E). Provisions a tenant
-   * + a first inbox and returns a LIMITED-scope (read-only) agent key; a one-time
-   * code is emailed to `human_email`. Call {@link verify} with the code to unlock
-   * full scopes. Idempotent on `human_email`: re-calling rotates the key + resends.
+   * Request a free account in one unauthenticated call. When free signup is
+   * enabled, this provisions a tenant plus a first inbox and returns a
+   * verification-only agent key. That key can only call {@link verify}; it cannot
+   * read or send mail. A one-time code is emailed to `human_email`. Call
+   * {@link verify} with the code to activate the account and receive full scopes.
+   * Idempotent on `human_email`: re-calling rotates the key and resends the code.
    * When free signup is paused, this throws an `ApiError` with status 403 and
    * code `signup_disabled` without creating account state.
    */
@@ -5031,7 +5435,7 @@ var ExtrovertClient = class _ExtrovertClient {
     return this.transport.whoami(signal);
   }
   /**
-   * Poll the status of an async job (`GET /v1/jobs/{job_id}`) — currently only
+   * Poll the status of an async job (`GET /v1/jobs/{job_id}`) - currently only
    * the domain-offboard teardown started by {@link Domains.offboard} enqueues
    * one. `status` is terminal on succeeded/failed/cancelled; keep polling
    * otherwise. An unknown or foreign job id is a {@link NotFoundError}.
@@ -5040,8 +5444,8 @@ var ExtrovertClient = class _ExtrovertClient {
     return this.transport.getJob(jobId, signal);
   }
   /**
-   * Redeem an enrollment token and return a *new* client already authenticated with the minted
-   * agent key — the natural "redeem then act" flow for an agent.
+   * Redeem an enrollment token and return a *new* client already authenticated with the issued
+   * agent key - the natural "redeem then act" flow for an agent.
    *
    * ```ts
    * const bootstrap = new Extrovert({ apiKey: enrollmentToken });
@@ -5062,7 +5466,7 @@ var ExtrovertClient = class _ExtrovertClient {
     return { client, enrollment };
   }
   /**
-   * Get an ergonomic handle to an existing inbox by address — without an extra round-trip. Use this
+   * Get an ergonomic handle to an existing inbox by address - without an extra round-trip. Use this
    * when you already know the address (e.g. from a previous create) and want to send/wait/reply.
    * Call {@link InboxHandle.refresh} to load the full record.
    */
@@ -5189,14 +5593,14 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.6";
+var CONTRACT_VERSION = "0.1.0-pre.8";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,
   stability: "provisional",
   kind: "sdk+skill-contract",
   spec_ref: "hitl-spec.md#11",
-  // §11 core — the five canonical example shapes.
+  // §11 core - the five canonical example shapes.
   core_shapes: ["ReviewIntent", "ReviewFeedback", "DiffJson", "Rule", "ReviewEvent"],
   // The FULL published surface (the §11 core plus the rest of M1–M8). Adding a
   // name here without a matching re-export (or vice-versa) breaks the drift test.
@@ -5220,6 +5624,8 @@ var CONTRACT_MANIFEST = {
     // realtime (M3)
     "ReviewEventReason",
     "ReviewEventsResult",
+    "LearnReviewRuleRequest",
+    "LearnedReviewRule",
     "ReviewEventCursor",
     // chat / revision / restamp (M5/M7)
     "PostReviewChatRequest",
@@ -5247,7 +5653,16 @@ var CONTRACT_MANIFEST = {
     "ReviewerAction",
     "ReviewDecisionContext",
     "ReviewerDecisionRequest",
-    "ReviewerDecisionResult"
+    "ReviewerDecisionResult",
+    // agent commerce request plane
+    "CommerceBlocker",
+    "QuoteDomainRequest",
+    "DomainQuote",
+    "CommerceRequestKind",
+    "RequestDomainPurchaseRequest",
+    "RequestPlanChangeRequest",
+    "ListCommerceRequestsParams",
+    "CommerceRequest"
   ],
   // The complete Review Loop behavior lives in the send skill; writing-rule
   // governance remains independently installable and part of this contract.
@@ -5263,6 +5678,7 @@ exports.CONTRACT_MANIFEST = CONTRACT_MANIFEST;
 exports.CONTRACT_VERSION = CONTRACT_VERSION;
 exports.CURRENT_API_VERSION = CURRENT_API_VERSION;
 exports.Categories = Categories;
+exports.Commerce = Commerce;
 exports.ConflictError = ConflictError;
 exports.ConnectionError = ConnectionError;
 exports.ContactLists = ContactLists;