revclamp-mcp 1.20.9 → 1.20.11

package/README.md

@@ -5,18 +5,18 @@
 **`revclamp-mcp`** is a standalone, zero-dependency **Open-Source Model Context Protocol (MCP) Server & CLI** (`index.mjs` + `local_engine.mjs`) implementing **9 deterministic B2B FinOps, Stripe `2025-03-31.basil`, Visa CE 3.0, EU/XI VIES VAT, Shopify Plus B2B Net-15/30/60, and Webhook Security tools** in pure Node.js.
 
 - **100% Local In-Process Execution (Default — Zero Network / Zero API Key Required):** All 9 MCP tools (`initialize`, `tools/list`, and `tools/call`) execute locally in-process inside [`local_engine.mjs`](./local_engine.mjs) using pure Node.js (`node:crypto` HMAC-SHA256 verification, integer-cent double-entry accounting, 72-hour webhook replay state machines, and `18,000` UTF-16 code unit CE 3.0 linting). Zero network calls are ever made unless `REVCLAMP_API_KEY` or `REVCLAMP_MCP_URL` is explicitly configured.
-- **Optional Hosted Cloud Workspace Sync (`REVCLAMP_API_KEY`):** When `REVCLAMP_API_KEY` (`rg_live_...`) is configured, `revclamp-mcp` connects to [**RevClamp Enterprise**](https://revclamp.com) (`https://api.revclamp.com/api/mcp`) to unlock the **90-day SQLite WAL usage & audit ledger**, **24/7 autonomous Stripe dispute & entitlement webhook outbox**, and **real-time EU Commission VIES SOAP gateway consultation numbers**.
+- **Optional Hosted Cloud Workspace Sync (`REVCLAMP_API_KEY`):** When `REVCLAMP_API_KEY` (`rg_live_...`) is configured, `revclamp-mcp` connects to [**RevClamp Enterprise**](https://revclamp.com) (`https://api.revclamp.com/api/mcp`) to unlock the **90-day durable transactional usage & audit ledger**, **24/7 autonomous Stripe dispute & entitlement webhook outbox**, and **real-time EU Commission VIES SOAP gateway consultation numbers**.
 
 ## Local Open-Core (`local_engine.mjs`) vs. Hosted Cloud (`REVCLAMP_API_KEY`)
 
 | Capability | Local Open-Core Default (Zero API Key) | Hosted Cloud (`REVCLAMP_API_KEY`) |
 | :--- | :--- | :--- |
 | **Execution & Network** | 100% in-process (`local_engine.mjs`), zero network calls | HTTPS JSON-RPC to `https://api.revclamp.com/api/mcp` (`redirect: "error"`) |
-| **Usage & Audit Storage** | Stateless evaluation of caller-supplied JSON snapshots | **Persistent 90-day SQLite WAL ledger** + Stripe historical backfill |
+| **Usage & Audit Storage** | Stateless evaluation of caller-supplied JSON snapshots | **Persistent 90-day durable transactional ledger** + Stripe historical backfill |
 | **Dispute & Entitlement Action** | Returns non-destructive `submit: false` draft & `revoke_entitlement` decision | **24/7 autonomous Stripe webhook outbox** (`disputes.update` & signed revoke webhooks) |
 | **EU & `XI` B2B VAT (`VIES`)** | Deterministic syntax & `GR -> EL` normalization (`FORMAT_ONLY` default, `valid: null`) | **Live EU Commission VIES SOAP consultation IDs** + circuit-breaker retry queue (`viesMode: "LIVE"` + `REVCLAMP_API_KEY`) |
 | **Monthly Event Tiers** | Unlimited local in-process evaluations (0 network cost) | **Free Sandbox** (`5,000` events/mo) · **Starter $19/mo** (`100k`) · **Growth $59/mo** (`1M`) · **Scale $199/mo** (`5M`) |
-| **Data Privacy (`INV-SAAS-04`)** | Nothing ever leaves your machine | Only explicit `tools/call` arguments are sent over TLS after local live-secret scrubbing (`scanMcpClientPayloadForSecrets` in `index.mjs` blocks `sk_live_`, non-test `whsec_`, `shpat_` locally) |
+| **Data Minimization & Privacy** | Nothing ever leaves your machine | Only explicit `tools/call` arguments are sent over TLS after local live-secret scrubbing (blocks `sk_live_`, non-test `whsec_`, and `shpat_` locally before any network request) |
 
 ## Open-Source MCP Tools Implemented in `local_engine.mjs` (9)
 
@@ -59,7 +59,13 @@ curl -sS -X POST https://api.revclamp.com/api/mcp \
 
 ```bash
 # Run a <60s local CLI smoke check (verifies all 9 tool schemas & executes a local_engine.mjs sample audit with zero API key)
-npx -y github:lhphong09t2/revclamp-mcp#v1.20.9 --self-test
+npx -y github:lhphong09t2/revclamp-mcp#v1.20.11 --self-test
+
+# Provision a free Cloud Workspace (or reuse REVCLAMP_API_KEY) & send a 6-digit login OTP
+npx -y revclamp-mcp@1.20.11 --init-workspace you@company.com
+
+# Verify the 6-digit OTP using REVCLAMP_API_KEY from environment
+REVCLAMP_API_KEY="rg_live_..." npx -y revclamp-mcp@1.20.11 --verify-otp you@company.com 123456
 
 # List all 9 MCP tools and JSON schemas (runs locally in-process)
 node index.mjs --list-tools

package/index.mjs

@@ -33,10 +33,16 @@ export {
   executeLocalMcpJsonRpc,
 };
 
-export const PACKAGE_VERSION = "1.20.9";
+export const PACKAGE_VERSION = "1.20.11";
 export const DEFAULT_MCP_ENDPOINT = "https://api.revclamp.com/api/mcp";
 export const ALLOWED_MCP_ORIGINS = Object.freeze(
-  new Set(["https://api.revclamp.com", "https://revclamp.com"])
+  new Set([
+    "https://api.revclamp.com",
+    "https://revclamp.com",
+    "https://app.revclamp.com",
+    "http://127.0.0.1",
+    "http://localhost",
+  ])
 );
 export const MAX_PAYLOAD_BYTES = 32_768;
 export const MAX_STDIO_LINE_BYTES = MAX_PAYLOAD_BYTES;
@@ -371,13 +377,19 @@ export async function forwardMcpJsonRpc(
       rpcRequest?.params?.name === "revclamp_validate_eu_vat_vies" &&
       (rawViesMode === "FORMAT_ONLY" || rpcRequest?.params?.arguments?.demo === true);
 
+    const cleanKey = String(apiKey || "").trim();
+
     if (
       String(mode || "").toLowerCase() === "local" ||
       !hasExplicitRemote ||
       isLocalOnlyViesCall
     ) {
       if (isNotification) return null;
-      return executeLocalMcpJsonRpc({ ...rpcRequest, id: safeId }, PACKAGE_VERSION);
+      return executeLocalMcpJsonRpc(
+        { ...rpcRequest, id: safeId },
+        PACKAGE_VERSION,
+        { suppressCloudUpgradeHint: Boolean(cleanKey) }
+      );
     }
 
     const boundedTimeoutMs = Math.min(10_000, Math.max(100, Number(timeoutMs) || REQUEST_TIMEOUT_MS));
@@ -385,7 +397,6 @@ export async function forwardMcpJsonRpc(
       "content-type": "application/json",
       accept: "application/json",
     };
-    const cleanKey = String(apiKey || "").trim();
     if (cleanKey) {
       headers.authorization = `Bearer ${cleanKey}`;
     }
@@ -788,6 +799,9 @@ function printHelp() {
       "  revclamp-mcp --sim-replay [presetKey] [windowSec]    Simulate webhook replay & out-of-order state machine",
       "  revclamp-mcp --lint-evidence [preset]                Lint Stripe dispute evidence UTF-16 & CE 3.0 completeness",
       "  revclamp-mcp --verify-webhook [provider] [rawPayload] [signatureHeader]  Verify webhook HMAC via REVCLAMP_WEBHOOK_SECRET env var",
+      "  revclamp-mcp --init-workspace <email>                Provision a free Cloud Workspace (or reuse REVCLAMP_API_KEY) & send 6-digit OTP",
+      "  revclamp-mcp --resend-otp <email>                    Resend 6-digit OTP using existing REVCLAMP_API_KEY env var",
+      "  revclamp-mcp --verify-otp <email> <code>             Verify 6-digit OTP using REVCLAMP_API_KEY env var & print MCP config snippet",
       "  revclamp-mcp --call <tool_name> '<json_args>'        Invoke any RevClamp MCP tool directly",
       "",
       "Environment Variables:",
@@ -810,17 +824,468 @@ const KNOWN_CLI_FLAGS = new Set([
   "--sim-replay",
   "--lint-evidence",
   "--verify-webhook",
+  "--init-workspace",
+  "--resend-otp",
+  "--verify-otp",
   "--call",
   "--stdio",
   "--url",
   "--endpoint",
 ]);
 
+function resolveValidatedOnboardingOrigin(rawBaseUrl = "https://revclamp.com") {
+  const trimmed = String(rawBaseUrl || "https://revclamp.com").trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, errorCode: "INVALID_MCP_ENDPOINT_URL" };
+  }
+  if (parsed.username || parsed.password) {
+    return { ok: false, errorCode: "UNSAFE_MCP_ENDPOINT_CREDENTIALS" };
+  }
+  const baseOriginWithoutPort = `${parsed.protocol}//${parsed.hostname}`;
+  const isLoopbackHttp =
+    parsed.protocol === "http:" &&
+    (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost") &&
+    ALLOWED_MCP_ORIGINS.has(baseOriginWithoutPort);
+  const isAllowedHttps =
+    parsed.protocol === "https:" && ALLOWED_MCP_ORIGINS.has(parsed.origin);
+  if (!isAllowedHttps && !isLoopbackHttp) {
+    return {
+      ok: false,
+      errorCode: "UNTRUSTED_MCP_ENDPOINT_ORIGIN",
+      origin: parsed.origin,
+    };
+  }
+  return { ok: true, origin: parsed.origin };
+}
+
+/**
+ * Executes CLI-to-Cloud workspace onboarding commands (--init-workspace, --resend-otp, --verify-otp)
+ * enforcing S1 (idempotent key reuse), S2 (partial-failure key preservation), and S3 (zero raw secret in argv).
+ *
+ * @param {object} params
+ * @returns {Promise<object>}
+ */
+export async function runMcpCliOnboardingCommand({
+  mode = "",
+  email = "",
+  otpCode = "",
+  argv = [],
+  env = process.env,
+  baseUrl = "",
+  fetchImpl,
+} = {}) {
+  const scanTokens = [
+    ...(Array.isArray(argv) ? argv : []),
+    email,
+    otpCode,
+  ].map((t) => String(t ?? "").trim());
+
+  for (const tok of scanTokens) {
+    if (
+      /^rg_(?:live|test)_/i.test(tok) ||
+      /(?:^|=)rg_(?:live|test)_/i.test(tok) ||
+      tok === "--api-key" ||
+      tok.startsWith("--api-key=")
+    ) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "RAW_API_KEY_IN_ARGV_FORBIDDEN",
+        message:
+          "Pass REVCLAMP_API_KEY via environment variable, never as a CLI argument.",
+      };
+    }
+  }
+
+  const effectiveEnv = env && typeof env === "object" ? env : process.env;
+  const resolvedBaseUrl =
+    baseUrl ||
+    effectiveEnv.REVCLAMP_API_URL ||
+    effectiveEnv.REVCLAMP_MCP_URL ||
+    effectiveEnv.REVCLAMP_WEB_URL ||
+    effectiveEnv.REVCLAMP_ONBOARDING_URL ||
+    "https://revclamp.com";
+  const originCheck = resolveValidatedOnboardingOrigin(resolvedBaseUrl);
+  if (!originCheck.ok) {
+    return {
+      ok: false,
+      exitCode: 1,
+      errorCode: originCheck.errorCode,
+      message: `Untrusted or invalid onboarding origin: ${String(resolvedBaseUrl)}`,
+    };
+  }
+
+  const cleanEmail = typeof email === "string" ? email.trim().toLowerCase() : "";
+  if (
+    cleanEmail.length < 3 ||
+    cleanEmail.length > 254 ||
+    !/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,63}$/.test(cleanEmail)
+  ) {
+    return {
+      ok: false,
+      exitCode: 1,
+      errorCode: "INVALID_EMAIL_ADDRESS",
+      message: "A valid email address (3..254 characters) is required.",
+    };
+  }
+
+  const normalizedMode = String(mode || "")
+    .trim()
+    .replace(/^--+/, "")
+    .toLowerCase();
+  const effectiveFetch = fetchImpl || globalThis.fetch;
+
+  const postOnboardingJson = async (pathname, payloadObj, apiKeyHeader = "") => {
+    const targetUrl = `${originCheck.origin}${pathname}`;
+    const headers = {
+      "content-type": "application/json",
+      accept: "application/json",
+    };
+    if (apiKeyHeader) {
+      headers.authorization = `Bearer ${apiKeyHeader}`;
+      headers["x-revclamp-tenant-key"] = apiKeyHeader;
+    }
+    try {
+      const res = await effectiveFetch(targetUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payloadObj),
+        redirect: "error",
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+      const status = Number(res?.status || 0);
+      const httpOk =
+        typeof res?.ok === "boolean" ? res.ok : status >= 200 && status < 300;
+      const rawText = await readBoundedResponseText(res, MAX_PAYLOAD_BYTES);
+      let body = null;
+      try {
+        body = rawText ? JSON.parse(rawText) : null;
+      } catch {
+        body = null;
+      }
+      return {
+        httpOk,
+        status,
+        body,
+        errorCode:
+          body && typeof body === "object"
+            ? body.errorCode || body.error || null
+            : null,
+        message:
+          body && typeof body === "object" ? body.message || null : null,
+      };
+    } catch (err) {
+      if (err instanceof Error && err.message === "UPSTREAM_RESPONSE_TOO_LARGE") {
+        return {
+          httpOk: false,
+          status: 502,
+          body: null,
+          errorCode: "UPSTREAM_RESPONSE_TOO_LARGE",
+          message: "Upstream onboarding response exceeded 32,768-byte ceiling.",
+        };
+      }
+      return {
+        httpOk: false,
+        status: 0,
+        body: null,
+        errorCode: "ONBOARDING_NETWORK_ERROR",
+        message: err instanceof Error ? err.message : "Network error",
+      };
+    }
+  };
+
+  const envApiKey =
+    typeof effectiveEnv.REVCLAMP_API_KEY === "string"
+      ? effectiveEnv.REVCLAMP_API_KEY.trim()
+      : "";
+  const hasValidEnvKey = /^rg_live_[a-zA-Z0-9_-]{12,128}$/.test(envApiKey);
+
+  if (normalizedMode === "init-workspace" || normalizedMode === "init") {
+    let activeApiKey = "";
+    let tenantId = null;
+    let reusedExistingEnvKey = false;
+
+    const provisionFreshWorkspace = async () => {
+      const provRes = await postOnboardingJson("/api/dashboard/provision", {
+        tier: "free",
+        acquisitionSurface: "mcp_cli",
+        merchantEmail: cleanEmail,
+      });
+      const provisionedKey =
+        provRes.body && typeof provRes.body.apiKey === "string"
+          ? provRes.body.apiKey.trim()
+          : "";
+      if (!provRes.httpOk || !provisionedKey) {
+        return {
+          ok: false,
+          res: {
+            ok: false,
+            exitCode: 1,
+            stage: "PROVISION_FAILED",
+            errorCode: provRes.errorCode || "PROVISION_WORKSPACE_FAILED",
+            status: provRes.status,
+            message:
+              provRes.message || "Failed to provision free Cloud Workspace.",
+          },
+        };
+      }
+      return {
+        ok: true,
+        apiKey: provisionedKey,
+        tenantId: provRes.body.tenantId || null,
+      };
+    };
+
+    if (hasValidEnvKey) {
+      activeApiKey = envApiKey;
+      reusedExistingEnvKey = true;
+    } else {
+      const freshProv = await provisionFreshWorkspace();
+      if (!freshProv.ok) {
+        return freshProv.res;
+      }
+      activeApiKey = freshProv.apiKey;
+      tenantId = freshProv.tenantId;
+    }
+
+    let otpRes = await postOnboardingJson(
+      "/api/dashboard/send-otp",
+      {
+        email: cleanEmail,
+        purpose: "dashboard_login",
+        acquisitionSurface: "mcp_cli",
+      },
+      activeApiKey
+    );
+
+    if (
+      reusedExistingEnvKey &&
+      (otpRes.status === 401 || otpRes.errorCode === "UNAUTHORIZED_TENANT_KEY")
+    ) {
+      const freshProv = await provisionFreshWorkspace();
+      if (!freshProv.ok) {
+        return freshProv.res;
+      }
+      activeApiKey = freshProv.apiKey;
+      tenantId = freshProv.tenantId;
+      reusedExistingEnvKey = false;
+      otpRes = await postOnboardingJson(
+        "/api/dashboard/send-otp",
+        {
+          email: cleanEmail,
+          purpose: "dashboard_login",
+          acquisitionSurface: "mcp_cli",
+        },
+        activeApiKey
+      );
+    }
+
+    const cmdKeyToken = reusedExistingEnvKey
+      ? '"$REVCLAMP_API_KEY"'
+      : activeApiKey;
+
+    if (!otpRes.httpOk || otpRes.body?.ok === false) {
+      return {
+        ok: false,
+        exitCode: 1,
+        stage: "SEND_OTP_FAILED",
+        errorCode: otpRes.errorCode || "SEND_OTP_FAILED",
+        status: otpRes.status,
+        email: cleanEmail,
+        tenantId: otpRes.body?.tenantId || tenantId,
+        apiKey: activeApiKey,
+        reusedExistingEnvKey,
+        nextStepCommand: `REVCLAMP_API_KEY=${cmdKeyToken} npx -y revclamp-mcp@${PACKAGE_VERSION} --resend-otp ${cleanEmail}`,
+        verifyCommandHint: `REVCLAMP_API_KEY=${cmdKeyToken} npx -y revclamp-mcp@${PACKAGE_VERSION} --verify-otp ${cleanEmail} <6-digit-code>`,
+      };
+    }
+
+    return {
+      ok: true,
+      exitCode: 0,
+      stage: "OTP_DISPATCHED",
+      email: cleanEmail,
+      tenantId: otpRes.body?.tenantId || tenantId,
+      apiKey: activeApiKey,
+      reusedExistingEnvKey,
+      nextStepCommand: `REVCLAMP_API_KEY=${cmdKeyToken} npx -y revclamp-mcp@${PACKAGE_VERSION} --verify-otp ${cleanEmail} <6-digit-code>`,
+      resendCommand: `REVCLAMP_API_KEY=${cmdKeyToken} npx -y revclamp-mcp@${PACKAGE_VERSION} --resend-otp ${cleanEmail}`,
+      upgradeUrl: "https://revclamp.com/pricing?source=mcp_cli",
+    };
+  }
+
+  if (normalizedMode === "resend-otp" || normalizedMode === "resend") {
+    if (!envApiKey) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "MISSING_REVCLAMP_API_KEY_ENV",
+        message:
+          "Set REVCLAMP_API_KEY in the environment before running --resend-otp.",
+      };
+    }
+    if (!hasValidEnvKey) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "INVALID_REVCLAMP_API_KEY_ENV",
+        message:
+          "REVCLAMP_API_KEY must be a valid rg_live_ workspace key.",
+      };
+    }
+
+    const otpRes = await postOnboardingJson(
+      "/api/dashboard/send-otp",
+      {
+        email: cleanEmail,
+        purpose: "dashboard_login",
+        acquisitionSurface: "mcp_cli",
+      },
+      envApiKey
+    );
+
+    if (!otpRes.httpOk || otpRes.body?.ok === false) {
+      return {
+        ok: false,
+        exitCode: 1,
+        stage: "SEND_OTP_FAILED",
+        errorCode: otpRes.errorCode || "SEND_OTP_FAILED",
+        status: otpRes.status,
+        email: cleanEmail,
+        tenantId: otpRes.body?.tenantId || null,
+        reusedExistingEnvKey: true,
+        nextStepCommand: `REVCLAMP_API_KEY="$REVCLAMP_API_KEY" npx -y revclamp-mcp@${PACKAGE_VERSION} --resend-otp ${cleanEmail}`,
+      };
+    }
+
+    return {
+      ok: true,
+      exitCode: 0,
+      stage: "OTP_RESENT",
+      email: cleanEmail,
+      tenantId: otpRes.body?.tenantId || null,
+      reusedExistingEnvKey: true,
+      nextStepCommand: `REVCLAMP_API_KEY="$REVCLAMP_API_KEY" npx -y revclamp-mcp@${PACKAGE_VERSION} --verify-otp ${cleanEmail} <6-digit-code>`,
+      upgradeUrl: "https://revclamp.com/pricing?source=mcp_cli",
+    };
+  }
+
+  if (normalizedMode === "verify-otp" || normalizedMode === "verify") {
+    if (!envApiKey) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "MISSING_REVCLAMP_API_KEY_ENV",
+        message:
+          "Set REVCLAMP_API_KEY in the environment before running --verify-otp.",
+      };
+    }
+    if (!hasValidEnvKey) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "INVALID_REVCLAMP_API_KEY_ENV",
+        message:
+          "REVCLAMP_API_KEY must be a valid rg_live_ workspace key.",
+      };
+    }
+
+    const cleanCode =
+      typeof otpCode === "string" || typeof otpCode === "number"
+        ? String(otpCode).trim()
+        : "";
+    if (!/^\d{6}$/.test(cleanCode)) {
+      return {
+        ok: false,
+        exitCode: 1,
+        errorCode: "INVALID_OTP_CODE_FORMAT",
+        message: "OTP code must be a 6-digit numeric code.",
+      };
+    }
+
+    const verifyRes = await postOnboardingJson(
+      "/api/dashboard/verify-otp",
+      {
+        email: cleanEmail,
+        otpCode: cleanCode,
+        code: cleanCode,
+        purpose: "dashboard_login",
+        acquisitionSurface: "mcp_cli",
+      },
+      envApiKey
+    );
+
+    if (
+      verifyRes.status === 200 &&
+      verifyRes.body?.ok === true &&
+      verifyRes.body?.verified === true
+    ) {
+      return {
+        ok: true,
+        exitCode: 0,
+        verified: true,
+        stage: "WORKSPACE_VERIFIED",
+        email: cleanEmail,
+        tenantId: verifyRes.body?.tenantId || null,
+        mcpServersConfig: {
+          mcpServers: {
+            revclamp: {
+              command: "npx",
+              args: ["-y", `revclamp-mcp@${PACKAGE_VERSION}`],
+              env: {
+                REVCLAMP_API_KEY: "<SET_FROM_ENV_RG_LIVE_KEY>",
+              },
+            },
+          },
+        },
+        upgradeUrl: "https://revclamp.com/pricing?source=mcp_cli",
+      };
+    }
+
+    return {
+      ok: false,
+      exitCode: 1,
+      verified: false,
+      stage: "VERIFY_OTP_FAILED",
+      errorCode: verifyRes.errorCode || "OTP_VERIFICATION_FAILED",
+      status: verifyRes.status,
+      message: verifyRes.message || "OTP verification failed.",
+      nextStepCommand: `REVCLAMP_API_KEY="$REVCLAMP_API_KEY" npx -y revclamp-mcp@${PACKAGE_VERSION} --verify-otp ${cleanEmail} <6-digit-code>`,
+    };
+  }
+
+  return {
+    ok: false,
+    exitCode: 1,
+    errorCode: "UNKNOWN_ONBOARDING_MODE",
+    message: `Unsupported onboarding mode: ${String(mode)}`,
+  };
+}
+
 export async function runCli(argv = process.argv.slice(2), options = {}) {
   const effectiveOptions = { ...options };
   const cleanedArgv = [];
   for (let i = 0; i < argv.length; i += 1) {
     const token = String(argv[i] ?? "");
+    if (
+      token === "--api-key" ||
+      token.startsWith("--api-key=") ||
+      /^rg_(?:live|test)_/i.test(token) ||
+      /(?:^|=)rg_(?:live|test)_/i.test(token)
+    ) {
+      const errOut = {
+        ok: false,
+        exitCode: 1,
+        errorCode: "RAW_API_KEY_IN_ARGV_FORBIDDEN",
+        message:
+          "Pass REVCLAMP_API_KEY via environment variable, never as a CLI argument.",
+      };
+      console.error(JSON.stringify(errOut));
+      return 1;
+    }
     if (token === "--secret" || token.startsWith("--secret=")) {
       console.error(
         "Error: passing webhook secrets via CLI flags (--secret) is forbidden; set REVCLAMP_WEBHOOK_SECRET in the environment."
@@ -1346,6 +1811,83 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
     return !res || res.error || res.result?.isError === true ? 1 : 0;
   }
 
+  const initWorkspaceIdx = cleanedArgv.indexOf("--init-workspace");
+  if (initWorkspaceIdx !== -1) {
+    const rawEmailToken = String(cleanedArgv[initWorkspaceIdx + 1] ?? "").trim();
+    const emailArg = rawEmailToken.startsWith("-") ? "" : rawEmailToken;
+    const out = await runMcpCliOnboardingCommand({
+      mode: "init-workspace",
+      email: emailArg,
+      argv,
+      env: effectiveOptions.env || process.env,
+      baseUrl:
+        effectiveOptions.baseUrl ||
+        effectiveOptions.endpointUrl ||
+        effectiveOptions.apiUrl ||
+        "",
+      fetchImpl: effectiveOptions.fetchImpl,
+    });
+    if (out.ok) {
+      console.log(JSON.stringify(out, null, 2));
+      return 0;
+    }
+    console.error(JSON.stringify(out, null, 2));
+    return 1;
+  }
+
+  const resendOtpIdx = cleanedArgv.indexOf("--resend-otp");
+  if (resendOtpIdx !== -1) {
+    const rawEmailToken = String(cleanedArgv[resendOtpIdx + 1] ?? "").trim();
+    const emailArg = rawEmailToken.startsWith("-") ? "" : rawEmailToken;
+    const out = await runMcpCliOnboardingCommand({
+      mode: "resend-otp",
+      email: emailArg,
+      argv,
+      env: effectiveOptions.env || process.env,
+      baseUrl:
+        effectiveOptions.baseUrl ||
+        effectiveOptions.endpointUrl ||
+        effectiveOptions.apiUrl ||
+        "",
+      fetchImpl: effectiveOptions.fetchImpl,
+    });
+    if (out.ok) {
+      console.log(JSON.stringify(out, null, 2));
+      return 0;
+    }
+    console.error(JSON.stringify(out, null, 2));
+    return 1;
+  }
+
+  const verifyOtpIdx = cleanedArgv.indexOf("--verify-otp");
+  if (verifyOtpIdx !== -1) {
+    const rawEmailToken = String(cleanedArgv[verifyOtpIdx + 1] ?? "").trim();
+    const emailArg = rawEmailToken.startsWith("-") ? "" : rawEmailToken;
+    const rawCodeToken = emailArg
+      ? String(cleanedArgv[verifyOtpIdx + 2] ?? "").trim()
+      : "";
+    const otpCodeArg = rawCodeToken.startsWith("-") ? "" : rawCodeToken;
+    const out = await runMcpCliOnboardingCommand({
+      mode: "verify-otp",
+      email: emailArg,
+      otpCode: otpCodeArg,
+      argv,
+      env: effectiveOptions.env || process.env,
+      baseUrl:
+        effectiveOptions.baseUrl ||
+        effectiveOptions.endpointUrl ||
+        effectiveOptions.apiUrl ||
+        "",
+      fetchImpl: effectiveOptions.fetchImpl,
+    });
+    if (out.ok) {
+      console.log(JSON.stringify(out, null, 2));
+      return 0;
+    }
+    console.error(JSON.stringify(out, null, 2));
+    return 1;
+  }
+
   const callIdx = cleanedArgv.indexOf("--call");
   if (callIdx !== -1) {
     if (cleanedArgv.length > callIdx + 3) {

package/local_engine.mjs

@@ -12,7 +12,7 @@
  *     caller-supplied payloads. Never fabricates live consultation IDs or card-network
  *     dispute evidence unless `demo: true` is explicitly passed (`sample: true`).
  *   - Cloud Workspace Mode (`REVCLAMP_API_KEY` on https://api.revclamp.com/api/mcp):
- *     Unlocks the 90-day SQLite WAL usage ledger, 24/7 autonomous Stripe dispute &
+ *     Unlocks the 90-day durable transactional usage ledger, 24/7 autonomous Stripe dispute &
  *     entitlement webhook outbox, and live European Commission VIES consultation IDs.
  */
 
@@ -145,7 +145,7 @@ export const LOCAL_MCP_RESOURCES = Object.freeze([
     uri: "revclamp://docs/open-core-capabilities",
     name: "RevClamp Open-Core vs Hosted Cloud Capabilities",
     description:
-      "Reference summary of the 9 local deterministic MCP tools vs. hosted REVCLAMP_API_KEY capabilities (90-day SQLite WAL ledger, 24/7 Stripe webhook outbox, and live EU VIES consultation IDs).",
+      "Reference summary of the 9 local deterministic MCP tools vs. hosted REVCLAMP_API_KEY capabilities (90-day durable transactional ledger, 24/7 Stripe webhook outbox, and live EU VIES consultation IDs).",
     mimeType: "application/json",
   }),
 ]);
@@ -189,7 +189,7 @@ const EU_VIES_FORMAT_RULES = Object.freeze({
   DK: /^DK\d{8}$/,
   EE: /^EE\d{9}$/,
   EL: /^EL\d{9}$/,
-  ES: /^ES[A-Z0-9]\d{7}[A-Z0-9]$/,
+  ES: /^ES(?:[A-Z]\d{7}[A-Z0-9]|[0-9]\d{7}[A-Z])$/,
   FI: /^FI\d{8}$/,
   FR: /^FR[A-HJ-NP-Z0-9]{2}\d{9}$/,
   HR: /^HR\d{11}$/,
@@ -214,6 +214,7 @@ const REVCLAMP_START_MARKER = "--- BEGIN REVCLAMP CE3 EVIDENCE ---";
 const REVCLAMP_END_MARKER = "--- END REVCLAMP CE3 EVIDENCE ---";
 const REVCLAMP_BRACKET_START_MARKER = "[RevClamp Verified Product Usage Log]";
 const REVCLAMP_BRACKET_END_MARKER = "[/RevClamp Verified Product Usage Log]";
+const REVCLAMP_BRACKET_ALT_END_MARKER = "[End RevClamp Log]";
 const PRODUCTION_EMPTY_BLOCK_WRAPPER_CHARS =
   REVCLAMP_BRACKET_START_MARKER.length + 1 + REVCLAMP_BRACKET_END_MARKER.length;
 const MAX_ACCESS_ACTIVITY_LOG_CHARS = 18_000;
@@ -654,14 +655,20 @@ export function validateArgsAgainstSchema(schema, args) {
 function normalizeCountryCode(raw) {
   const clean = String(raw || "")
     .trim()
-    .toUpperCase();
-  return clean === "GR" ? "EL" : clean;
+    .toUpperCase()
+    .replace(/[\s.\-/:_]+/g, "");
+  if (clean === "GR") return "EL";
+  if (clean === "GBNIR") return "XI";
+  return clean;
 }
 
 function normalizeVatId(rawVat) {
-  const compact = String(rawVat || "")
+  let compact = String(rawVat || "")
     .toUpperCase()
-    .replace(/[\s.\-/:]+/g, "");
+    .replace(/[\s.\-/:_]+/g, "");
+  if (compact.startsWith("GBNIR")) {
+    compact = `XI${compact.slice(5)}`;
+  }
   if (compact.length < 4) {
     return { validFormat: false, memberState: "", vatNumber: "", fullVatId: compact };
   }
@@ -693,50 +700,107 @@ function sanitizeLogToken(raw, maxLen = 96) {
 
 function stripExistingRevClampBlock(rawNotes) {
   if (typeof rawNotes !== "string" || !rawNotes) {
-    return { ok: true, hadBlock: false, prefix: "", suffix: "", text: "" };
+    return {
+      ok: true,
+      hadBlock: false,
+      prefix: "",
+      suffix: "",
+      text: "",
+      blockUtf16CodeUnits: 0,
+    };
   }
   const hasCanonical =
     rawNotes.includes(REVCLAMP_START_MARKER) || rawNotes.includes(REVCLAMP_END_MARKER);
+  const hasBracketPrimaryEnd = rawNotes.includes(REVCLAMP_BRACKET_END_MARKER);
+  const hasBracketAltEnd = rawNotes.includes(REVCLAMP_BRACKET_ALT_END_MARKER);
   const hasBracket =
-    rawNotes.includes(REVCLAMP_BRACKET_START_MARKER) ||
-    rawNotes.includes(REVCLAMP_BRACKET_END_MARKER);
+    rawNotes.includes(REVCLAMP_BRACKET_START_MARKER) || hasBracketPrimaryEnd || hasBracketAltEnd;
   if (!hasCanonical && !hasBracket) {
-    return { ok: true, hadBlock: false, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+    return {
+      ok: true,
+      hadBlock: false,
+      prefix: rawNotes,
+      suffix: "",
+      text: rawNotes.trim(),
+      blockUtf16CodeUnits: 0,
+    };
   }
-  if (hasCanonical && hasBracket) {
-    return { ok: false, hadBlock: true, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+  if ((hasCanonical && hasBracket) || (hasBracketPrimaryEnd && hasBracketAltEnd)) {
+    return {
+      ok: false,
+      hadBlock: true,
+      prefix: rawNotes,
+      suffix: "",
+      text: rawNotes.trim(),
+      blockUtf16CodeUnits: 0,
+    };
   }
   const activeStart = hasCanonical ? REVCLAMP_START_MARKER : REVCLAMP_BRACKET_START_MARKER;
-  const activeEnd = hasCanonical ? REVCLAMP_END_MARKER : REVCLAMP_BRACKET_END_MARKER;
+  const activeEnd = hasCanonical
+    ? REVCLAMP_END_MARKER
+    : hasBracketAltEnd
+      ? REVCLAMP_BRACKET_ALT_END_MARKER
+      : REVCLAMP_BRACKET_END_MARKER;
   let cursor = 0;
   const prefixSegments = [];
   let trailingSegment = "";
+  let blockUtf16CodeUnits = 0;
   while (cursor < rawNotes.length) {
     const startIdx = rawNotes.indexOf(activeStart, cursor);
     if (startIdx === -1) {
       if (rawNotes.indexOf(activeEnd, cursor) !== -1) {
-        return { ok: false, hadBlock: true, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+        return {
+          ok: false,
+          hadBlock: true,
+          prefix: rawNotes,
+          suffix: "",
+          text: rawNotes.trim(),
+          blockUtf16CodeUnits: 0,
+        };
       }
       trailingSegment = rawNotes.slice(cursor);
       break;
     }
     if (rawNotes.slice(cursor, startIdx).includes(activeEnd)) {
-      return { ok: false, hadBlock: true, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+      return {
+        ok: false,
+        hadBlock: true,
+        prefix: rawNotes,
+        suffix: "",
+        text: rawNotes.trim(),
+        blockUtf16CodeUnits: 0,
+      };
     }
     const contentStart = startIdx + activeStart.length;
     const endIdx = rawNotes.indexOf(activeEnd, contentStart);
     if (endIdx === -1) {
-      return { ok: false, hadBlock: true, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+      return {
+        ok: false,
+        hadBlock: true,
+        prefix: rawNotes,
+        suffix: "",
+        text: rawNotes.trim(),
+        blockUtf16CodeUnits: 0,
+      };
     }
     const nextStartIdx = rawNotes.indexOf(activeStart, contentStart);
     if (nextStartIdx !== -1 && nextStartIdx < endIdx) {
-      return { ok: false, hadBlock: true, prefix: rawNotes, suffix: "", text: rawNotes.trim() };
+      return {
+        ok: false,
+        hadBlock: true,
+        prefix: rawNotes,
+        suffix: "",
+        text: rawNotes.trim(),
+        blockUtf16CodeUnits: 0,
+      };
     }
     const beforeSegment = rawNotes.slice(cursor, startIdx).replace(/\n{1,2}$/, "");
     if (beforeSegment.length > 0) {
       prefixSegments.push(beforeSegment);
     }
-    cursor = endIdx + activeEnd.length;
+    const blockEndCursor = endIdx + activeEnd.length;
+    blockUtf16CodeUnits += blockEndCursor - startIdx;
+    cursor = blockEndCursor;
     if (rawNotes.slice(cursor, cursor + 2) === "\n\n") {
       cursor += 2;
     } else if (rawNotes[cursor] === "\n") {
@@ -752,6 +816,7 @@ function stripExistingRevClampBlock(rawNotes) {
     prefix,
     suffix,
     text: keptTrimmed.join("\n\n").trim(),
+    blockUtf16CodeUnits,
   };
 }
 
@@ -949,14 +1014,37 @@ function evaluateLocalGhostUsage(subscriptionsEnv, usageEvent, dunningGracePerio
         reason: "UNMATCHED_CUSTOMER_ID",
       };
     }
+    const hasPositiveCustomerIdMatch = Boolean(evCustomerId && subCus && subCus === evCustomerId);
+    const hasPositiveEmailMatch = Boolean(evEmail && subEmail && subEmail === evEmail);
+    if (!hasPositiveCustomerIdMatch && !hasPositiveEmailMatch) {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        isGhostUsage: false,
+        decision: "HOLD_CUSTOMER_MISMATCH",
+        reason: subCus ? "UNMATCHED_CUSTOMER_ID" : "UNMATCHED_CUSTOMER_EMAIL",
+      };
+    }
     const st = sub.status.trim();
     if (ENTITLED_SUB_STATUSES.has(st)) {
+      const collectionPaused = Boolean(
+        sub.pause_collection && typeof sub.pause_collection === "object"
+      );
       return {
         ok: true,
         executionMode: "local_open_source_engine",
         isGhostUsage: false,
         decision: "ALLOW_ENTITLED",
         reason: "ACTIVE_SUBSCRIPTION_PRESENT",
+        ...(collectionPaused
+          ? {
+              collectionPaused: true,
+              pauseCollectionBehavior:
+                typeof sub.pause_collection.behavior === "string"
+                  ? sub.pause_collection.behavior
+                  : "void",
+            }
+          : {}),
       };
     }
     if (sub.items?.has_more === true) {
@@ -1093,7 +1181,36 @@ function parseStrictIpv4Octets(str) {
 
 function normalizeIpForCe3Correlation(ip) {
   if (typeof ip !== "string") return null;
-  const clean = ip.trim().replace(/^\[|\]$/g, "").replace(/%[^\s%\]]+$/, "").trim().toLowerCase();
+  let raw = ip.trim().toLowerCase();
+  if (!raw || raw.includes(",")) return null;
+  if (raw.startsWith("ipv4:")) {
+    raw = raw.slice(5).trim();
+  } else if (raw.startsWith("ipv6_64:")) {
+    const v6Match = raw.match(
+      /^ipv6_64:([0-9a-f]{1,4}):([0-9a-f]{1,4}):([0-9a-f]{1,4}):([0-9a-f]{1,4})$/
+    );
+    if (!v6Match) return null;
+    return `ipv6_64:${v6Match
+      .slice(1, 5)
+      .map((w) => Number.parseInt(w, 16).toString(16).padStart(4, "0"))
+      .join(":")}`;
+  }
+  const bracketPortMatch = raw.match(/^\[([^\]]+)\](?::(\d{1,5}))?$/);
+  if (bracketPortMatch) {
+    if (bracketPortMatch[2] !== undefined) {
+      const portNum = Number(bracketPortMatch[2]);
+      if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) return null;
+    }
+    raw = bracketPortMatch[1];
+  } else {
+    const v4PortMatch = raw.match(/^(\d{1,3}(?:\.\d{1,3}){3}):(\d{1,5})$/);
+    if (v4PortMatch) {
+      const portNum = Number(v4PortMatch[2]);
+      if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) return null;
+      raw = v4PortMatch[1];
+    }
+  }
+  const clean = raw.replace(/^\[|\]$/g, "").replace(/%[^\s%\]]+$/, "").trim();
   if (!clean) return null;
   const directV4 = parseStrictIpv4Octets(clean);
   if (directV4) return `ipv4:${directV4.join(".")}`;
@@ -1224,14 +1341,30 @@ function extractNormalizedCe3Identifiers(tx) {
 
 function extractPaymentCredential(tx) {
   if (!tx || typeof tx !== "object") return "";
-  const raw =
-    tx.card_fingerprint ||
-    tx.payment_method_fingerprint ||
-    tx.payment_method ||
-    tx.payment_method_details?.card?.fingerprint ||
-    tx.card?.fingerprint ||
-    "";
-  return sanitizeLogToken(raw, 96);
+  const fpCandidates = [
+    tx.card_fingerprint,
+    tx.payment_method_fingerprint,
+    tx.payment_method_details?.card?.fingerprint,
+    tx.payment_method && typeof tx.payment_method === "object"
+      ? tx.payment_method.card?.fingerprint
+      : "",
+    tx.card?.fingerprint,
+    tx.source?.card?.fingerprint,
+  ];
+  for (const cand of fpCandidates) {
+    if (typeof cand === "string" && cand.trim()) {
+      return sanitizeLogToken(cand.trim(), 96);
+    }
+  }
+  const pmId =
+    typeof tx.payment_method === "string"
+      ? tx.payment_method
+      : tx.payment_method &&
+          typeof tx.payment_method === "object" &&
+          typeof tx.payment_method.id === "string"
+        ? tx.payment_method.id
+        : "";
+  return sanitizeLogToken(pmId, 96);
 }
 
 function evaluateLocalVisaCe3Qualification(disputeReason, disputedTransaction, priorTransactions) {
@@ -1372,7 +1505,34 @@ function evaluateLocalVisaCe3Qualification(disputeReason, disputedTransaction, p
   };
 }
 
-export function executeLocalMcpTool(toolName, rawArgs = {}) {
+export const LOCAL_STATELESS_CLOUD_UPGRADE_HINT = Object.freeze({
+  mode: "LOCAL_STATELESS_OPEN_CORE",
+  message:
+    "Running in stateless local mode. Provision a free or paid Cloud Workspace for 90-day event persistence, automated webhook revocation, and Slack/Email alerts.",
+  command: "npx --yes revclamp-mcp --init-workspace <work_email>",
+  cliActivateCommand: "npx -y revclamp-mcp@1.20.11 --init-workspace you@company.com",
+  upgradeUrl: "https://revclamp.com/pricing?source=mcp_cli",
+});
+
+export function executeLocalMcpTool(toolName, rawArgs = {}, options = {}) {
+  const result = executeLocalMcpToolCore(toolName, rawArgs);
+  const suppressHint = Boolean(options?.suppressCloudUpgradeHint || options?.apiKey);
+  if (
+    !suppressHint &&
+    result &&
+    typeof result === "object" &&
+    result.ok !== false &&
+    !result.error
+  ) {
+    return {
+      ...result,
+      cloudUpgradeHint: LOCAL_STATELESS_CLOUD_UPGRADE_HINT,
+    };
+  }
+  return result;
+}
+
+function executeLocalMcpToolCore(toolName, rawArgs = {}) {
   const inputArgs =
     rawArgs === undefined
       ? {}
@@ -1988,11 +2148,23 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
     const malformedExistingMarkers = Boolean(!strippedNotes.ok);
     const warnings = malformedExistingMarkers ? ["MALFORMED_EXISTING_MARKERS"] : [];
     const trimmedExistingNotes = existingMerchantNotes.trim();
+    const normalizedTrimmedExisting = trimmedExistingNotes.replace(/\r?\n+/g, "\n");
     const outsideMarkerText = `${strippedNotes.prefix || ""}\n${strippedNotes.suffix || ""}`;
+    const outsideJoinedSingle = [strippedNotes.prefix || "", strippedNotes.suffix || ""]
+      .filter(Boolean)
+      .join("\n");
+    const outsideJoinedDouble = [strippedNotes.prefix || "", strippedNotes.suffix || ""]
+      .filter(Boolean)
+      .join("\n\n");
+    const outsideNormalizedNewlines = outsideJoinedSingle.replace(/\r?\n+/g, "\n");
     const preservesMerchantNotes = Boolean(
       nonDestructiveMarkersPresent &&
         strippedNotes.text.length > 0 &&
-        (trimmedExistingNotes === "" || outsideMarkerText.includes(trimmedExistingNotes))
+        (trimmedExistingNotes === "" ||
+          outsideMarkerText.includes(trimmedExistingNotes) ||
+          outsideJoinedSingle.includes(trimmedExistingNotes) ||
+          outsideJoinedDouble.includes(trimmedExistingNotes) ||
+          outsideNormalizedNewlines.includes(normalizedTrimmedExisting))
     );
 
     const extractedNotesLen =
@@ -2004,12 +2176,10 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
     const preSeparatorUnits = capacityPrefix.length > 0 ? 2 : 0;
     const postSeparatorUnits = capacitySuffix.length > 0 ? 2 : 0;
     const merchantNotesUtf16CodeUnits = capacityPrefix.length + capacitySuffix.length;
+    const wrapperOverheadUtf16CodeUnits =
+      preSeparatorUnits + PRODUCTION_EMPTY_BLOCK_WRAPPER_CHARS + postSeparatorUnits;
     const fixedWrapperUtf16CodeUnits =
-      capacityPrefix.length +
-      preSeparatorUnits +
-      PRODUCTION_EMPTY_BLOCK_WRAPPER_CHARS +
-      postSeparatorUnits +
-      capacitySuffix.length;
+      capacityPrefix.length + wrapperOverheadUtf16CodeUnits + capacitySuffix.length;
     const merchantLogAtCapacity = Boolean(
       fixedWrapperUtf16CodeUnits >= MAX_ACCESS_ACTIVITY_LOG_CHARS
     );
@@ -2027,6 +2197,20 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
     const within18kCeiling = utf16CodeUnits <= MAX_ACCESS_ACTIVITY_LOG_CHARS;
     const within20kHardCeiling = utf16CodeUnits <= 20_000;
     const exceeds20kHardCeiling = utf16CodeUnits > 20_000;
+    const segmentBreakdown = {
+      prefixUtf16CodeUnits: capacityPrefix.length,
+      preSeparatorUtf16CodeUnits: preSeparatorUnits,
+      revClampBlockUtf16CodeUnits: strippedNotes.blockUtf16CodeUnits || 0,
+      postSeparatorUtf16CodeUnits: postSeparatorUnits,
+      suffixUtf16CodeUnits: capacitySuffix.length,
+      wrapperOverheadUtf16CodeUnits,
+      totalMergedUtf16CodeUnits: utf16CodeUnits,
+      remainingSafeBudgetUtf16CodeUnits: remainingUtf16Units,
+      overBudgetByUtf16CodeUnits: Math.max(
+        0,
+        utf16CodeUnits - MAX_ACCESS_ACTIVITY_LOG_CHARS
+      ),
+    };
     let overallVerdict = "PASS_CE3_READY";
     if (!within18kCeiling) {
       overallVerdict = "FAIL_UTF16_OVERFLOW";
@@ -2074,6 +2258,7 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       merchantNotesPreserved: preservesMerchantNotes,
       merchantNotesUtf16CodeUnits,
       fixedWrapperUtf16CodeUnits,
+      segmentBreakdown,
       merchantLogAtCapacity,
       stagingActionWhenAtCapacity,
       priorMatchedCount,
@@ -2416,7 +2601,18 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       };
     }
 
-    if (viesMode === "MS_UNAVAILABLE" || viesMode === "GLOBAL_MAX_CONCURRENT_REQ") {
+    const TRANSIENT_SIM_MODES = new Set([
+      "MS_UNAVAILABLE",
+      "GLOBAL_MAX_CONCURRENT_REQ",
+      "MS_MAX_CONCURRENT_REQ",
+      "MS_MAX_CONCURRENT_REQ_TIME",
+      "GLOBAL_MAX_CONCURRENT_REQ_TIME",
+      "SERVICE_UNAVAILABLE",
+      "TIMEOUT",
+      "SERVER_BUSY",
+      "NETWORK_ERROR",
+    ]);
+    if (TRANSIENT_SIM_MODES.has(viesMode)) {
       return {
         ok: true,
         executionMode: "local_open_source_engine",
@@ -2434,7 +2630,25 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       };
     }
 
-    if (viesMode === "INVALID") {
+    if (viesMode === "INVALID_REQUESTER_INFO" || viesMode === "IP_BLOCKED") {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        sample: true,
+        valid: null,
+        formatValid: true,
+        status: "HOLD_UNVERIFIED_VIES_FAULT",
+        reason: `VIES_GATEWAY_FAULT_${viesMode}`,
+        sellerCountry,
+        normalizedVatId: norm.fullVatId,
+        memberState: norm.memberState,
+        reverseChargeEligible: false,
+        zeroRateAllowed: false,
+        consultationId: null,
+      };
+    }
+
+    if (viesMode === "INVALID" || viesMode === "VAT_BLOCKED" || viesMode === "INVALID_INPUT") {
       return {
         ok: true,
         executionMode: "local_open_source_engine",
@@ -2442,7 +2656,25 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
         valid: false,
         formatValid: true,
         status: "HOLD_INVALID_VAT",
-        reason: "VIES_DEFINITE_INVALID",
+        reason: viesMode === "INVALID" ? "VIES_DEFINITE_INVALID" : `VIES_${viesMode}`,
+        sellerCountry,
+        normalizedVatId: norm.fullVatId,
+        memberState: norm.memberState,
+        reverseChargeEligible: false,
+        zeroRateAllowed: false,
+        consultationId: null,
+      };
+    }
+
+    if (viesMode !== "VALID" && viesMode !== "VERIFIED") {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        sample: true,
+        valid: null,
+        formatValid: true,
+        status: "HOLD_UNVERIFIED_VIES_FAULT",
+        reason: "UNRECOGNIZED_VIES_SIMULATION_MODE",
         sellerCountry,
         normalizedVatId: norm.fullVatId,
         memberState: norm.memberState,
@@ -2559,20 +2791,21 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
 
     const effectiveTotalCents = Math.max(0, orderTotalCents - creditNotesCents);
     const hasExplicitDepositCents = args.requiredDepositCents !== undefined;
-    const requiredDepositCents = hasExplicitDepositCents
+    const rawRequiredDepositCents = hasExplicitDepositCents
       ? args.requiredDepositCents
       : Math.ceil((effectiveTotalCents * requiredDepositPercent) / 100);
     if (
-      !Number.isSafeInteger(requiredDepositCents) ||
-      requiredDepositCents < 0 ||
-      requiredDepositCents > effectiveTotalCents
+      !Number.isSafeInteger(rawRequiredDepositCents) ||
+      rawRequiredDepositCents < 0 ||
+      rawRequiredDepositCents > orderTotalCents
     ) {
       const err = new Error(
-        "INVALID_REQUIRED_DEPOSIT_CENTS: requiredDepositCents must be an integer between 0 and effectiveTotalCents."
+        "INVALID_REQUIRED_DEPOSIT_CENTS: requiredDepositCents must be an integer between 0 and totalOrderCents."
       );
       err.code = -32602;
       throw err;
     }
+    const requiredDepositCents = Math.min(rawRequiredDepositCents, effectiveTotalCents);
 
     const shortfallRawCents = Math.max(0, effectiveTotalCents - paidAmountCents);
     const overpaidCents = Math.max(0, paidAmountCents - effectiveTotalCents);
@@ -2898,7 +3131,9 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
         ? args.existingAccessActivityLog
         : typeof args.existingUncategorizedText === "string"
           ? args.existingUncategorizedText
-          : "";
+          : typeof args.existingMerchantNotes === "string"
+            ? args.existingMerchantNotes
+            : "";
     const strippedNotes = stripExistingRevClampBlock(rawExistingLog);
     if (!strippedNotes.ok) {
       const rawUtf8Bytes = Buffer.byteLength(rawExistingLog, "utf8");
@@ -2919,25 +3154,40 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
         },
       };
     }
-    const preservedMerchantNotes = strippedNotes.text;
+    const merchantPrefixLog = strippedNotes.prefix || "";
+    const merchantSuffixLog = strippedNotes.suffix || "";
+    const totalMerchantChars = merchantPrefixLog.length + merchantSuffixLog.length;
+    const preSeparator = merchantPrefixLog.length > 0 ? "\n\n" : "";
+    const postSeparator = merchantSuffixLog.length > 0 ? "\n\n" : "";
     const headerLine = isDemo
       ? `[DEMO SAMPLE - NOT FOR DISPUTE SUBMISSION | dispute=${cleanDisputeId} | customer=${cleanCustomerId} | submit=false]`
       : `[RevClamp Verified Product Usage Log | dispute=${cleanDisputeId} | customer=${cleanCustomerId} | submit=false]`;
 
-    const prefix = preservedMerchantNotes ? `${preservedMerchantNotes}\n\n` : "";
+    const wrapperOverheadUtf16CodeUnits =
+      preSeparator.length +
+      REVCLAMP_START_MARKER.length +
+      1 +
+      REVCLAMP_END_MARKER.length +
+      postSeparator.length;
+    const fixedWrapperChars =
+      merchantPrefixLog.length + wrapperOverheadUtf16CodeUnits + merchantSuffixLog.length;
     const fixedEnvelopeChars =
-      prefix.length +
+      merchantPrefixLog.length +
+      preSeparator.length +
       REVCLAMP_START_MARKER.length +
       1 +
       headerLine.length +
       1 +
-      REVCLAMP_END_MARKER.length;
+      REVCLAMP_END_MARKER.length +
+      postSeparator.length +
+      merchantSuffixLog.length;
     const fixedEnvelopeUtf8Bytes = Buffer.byteLength(
-      `${prefix}${REVCLAMP_START_MARKER}\n${headerLine}\n${REVCLAMP_END_MARKER}`,
+      `${merchantPrefixLog}${preSeparator}${REVCLAMP_START_MARKER}\n${headerLine}\n${REVCLAMP_END_MARKER}${postSeparator}${merchantSuffixLog}`,
       "utf8"
     );
 
     if (
+      fixedWrapperChars >= MAX_ACCESS_ACTIVITY_LOG_CHARS ||
       fixedEnvelopeChars > MAX_ACCESS_ACTIVITY_LOG_CHARS ||
       fixedEnvelopeUtf8Bytes > MAX_LOG_UTF8_BYTES
     ) {
@@ -2949,6 +3199,23 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
         skipped: true,
         reason: "EXISTING_MERCHANT_NOTES_EXCEED_18K_CEILING",
         submit: false,
+        segmentBreakdown: {
+          prefixUtf16CodeUnits: merchantPrefixLog.length,
+          preSeparatorUtf16CodeUnits: preSeparator.length,
+          revClampBlockUtf16CodeUnits: 0,
+          postSeparatorUtf16CodeUnits: postSeparator.length,
+          suffixUtf16CodeUnits: merchantSuffixLog.length,
+          wrapperOverheadUtf16CodeUnits,
+          totalMergedUtf16CodeUnits: totalMerchantChars,
+          remainingSafeBudgetUtf16CodeUnits: Math.max(
+            0,
+            MAX_ACCESS_ACTIVITY_LOG_CHARS - totalMerchantChars
+          ),
+          overBudgetByUtf16CodeUnits: Math.max(
+            0,
+            fixedEnvelopeChars - MAX_ACCESS_ACTIVITY_LOG_CHARS
+          ),
+        },
         evidence: {},
       };
     }
@@ -2969,6 +3236,36 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       currentUtf8Bytes += lineUtf8Bytes;
     }
 
+    if (packedLines.length === 0 && formattedLines.length > 0) {
+      return {
+        ok: true,
+        executionMode: "local_open_source_engine",
+        disputeId: cleanDisputeId,
+        customerId: cleanCustomerId,
+        skipped: true,
+        reason: "EXISTING_MERCHANT_NOTES_EXCEED_18K_CEILING",
+        submit: false,
+        segmentBreakdown: {
+          prefixUtf16CodeUnits: merchantPrefixLog.length,
+          preSeparatorUtf16CodeUnits: preSeparator.length,
+          revClampBlockUtf16CodeUnits: 0,
+          postSeparatorUtf16CodeUnits: postSeparator.length,
+          suffixUtf16CodeUnits: merchantSuffixLog.length,
+          wrapperOverheadUtf16CodeUnits,
+          totalMergedUtf16CodeUnits: totalMerchantChars,
+          remainingSafeBudgetUtf16CodeUnits: Math.max(
+            0,
+            MAX_ACCESS_ACTIVITY_LOG_CHARS - totalMerchantChars
+          ),
+          overBudgetByUtf16CodeUnits: Math.max(
+            0,
+            fixedEnvelopeChars + 1 + formattedLines[0].length - MAX_ACCESS_ACTIVITY_LOG_CHARS
+          ),
+        },
+        evidence: {},
+      };
+    }
+
     const block = [
       REVCLAMP_START_MARKER,
       headerLine,
@@ -2976,7 +3273,7 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       REVCLAMP_END_MARKER,
     ].join("\n");
 
-    const merged = `${prefix}${block}`;
+    const merged = `${merchantPrefixLog}${preSeparator}${block}${postSeparator}${merchantSuffixLog}`;
     const ce3Qualification = evaluateLocalVisaCe3Qualification(
       disputeReason,
       args.disputedTransaction,
@@ -2994,6 +3291,20 @@ export function executeLocalMcpTool(toolName, rawArgs = {}) {
       submit: false,
       utf16CodeUnits: merged.length,
       linesIncluded: packedLines.length,
+      segmentBreakdown: {
+        prefixUtf16CodeUnits: merchantPrefixLog.length,
+        preSeparatorUtf16CodeUnits: preSeparator.length,
+        revClampBlockUtf16CodeUnits: block.length,
+        postSeparatorUtf16CodeUnits: postSeparator.length,
+        suffixUtf16CodeUnits: merchantSuffixLog.length,
+        wrapperOverheadUtf16CodeUnits,
+        totalMergedUtf16CodeUnits: merged.length,
+        remainingSafeBudgetUtf16CodeUnits: Math.max(
+          0,
+          MAX_ACCESS_ACTIVITY_LOG_CHARS - merged.length
+        ),
+        overBudgetByUtf16CodeUnits: Math.max(0, merged.length - MAX_ACCESS_ACTIVITY_LOG_CHARS),
+      },
       evidence: {
         access_activity_log: merged,
       },
@@ -3150,7 +3461,11 @@ function toSafeLocalRpcId(rawId) {
   return null;
 }
 
-export function executeLocalMcpJsonRpc(rpcRequest, packageVersion = "1.20.9") {
+export function executeLocalMcpJsonRpc(
+  rpcRequest,
+  packageVersion = "1.20.11",
+  options = {}
+) {
   if (!rpcRequest || typeof rpcRequest !== "object" || Array.isArray(rpcRequest)) {
     return {
       jsonrpc: "2.0",
@@ -3264,7 +3579,7 @@ export function executeLocalMcpJsonRpc(rpcRequest, packageVersion = "1.20.9") {
               version: packageVersion,
               localExecution: "9 deterministic tools in local_engine.mjs (0 network calls by default)",
               cloudCapabilities: [
-                "90-day SQLite WAL usage & audit ledger",
+                "90-day durable transactional usage & audit ledger",
                 "24/7 autonomous Stripe dispute & entitlement webhook outbox",
                 "Live EU Commission VIES SOAP consultation numbers (viesMode: 'LIVE')",
               ],
@@ -3434,7 +3749,7 @@ export function executeLocalMcpJsonRpc(rpcRequest, packageVersion = "1.20.9") {
     }
 
     try {
-      const structuredContent = executeLocalMcpTool(toolName, effectiveToolArgs);
+      const structuredContent = executeLocalMcpTool(toolName, effectiveToolArgs, options);
       let responseObj = {
         jsonrpc: "2.0",
         id: safeId,

package/mcp-config.json

@@ -26,7 +26,7 @@
   },
   "manifest": {
     "name": "revclamp-mcp",
-    "version": "1.20.9",
+    "version": "1.20.11",
     "tools": [
       "revclamp_audit_revenue_leakage",
       "revclamp_evaluate_ghost_usage",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "revclamp-mcp",
-  "mcpName": "io.github.revclamp/revclamp-mcp",
-  "version": "1.20.9",
+  "mcpName": "com.revclamp/revclamp-mcp",
+  "version": "1.20.11",
   "description": "Model Context Protocol (MCP) server and CLI for Stripe 2025-03-31.basil entitlement checks, Visa CE 3.0 dispute staging (submit: false), EU/XI VIES VAT validation, Shopify Plus B2B Net-15/30/60 reconciliation, webhook HMAC-SHA256 verification, 0% take-rate ROI calculation, 72-hour webhook replay & out-of-order state-machine simulation, and Stripe dispute evidence 18,000 UTF-16 code unit & CE 3.0 completeness linting.",
   "type": "module",
   "main": "./index.mjs",
@@ -46,6 +46,6 @@
     "node": ">=20.0.0"
   },
   "revclamp": {
-    "engineSha256": "775f5ff489a939d0f262ef972da38598e11fef0ce9e1371e6980e3946209fbc5"
+    "engineSha256": "806f9291517805e75ce55636ad1e704e30c1b2a840bd1162c87ba7e92bd9a053"
   }
 }

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "io.github.revclamp/revclamp-mcp",
+  "name": "com.revclamp/revclamp-mcp",
   "title": "RevClamp MCP Server",
   "description": "Zero-take-rate Stripe 2025-03-31.basil, Visa CE 3.0 & EU/XI VIES VAT guardrails MCP server.",
   "repository": {
     "url": "https://github.com/lhphong09t2/revclamp-mcp",
     "source": "github"
   },
-  "version": "1.20.9",
+  "version": "1.20.11",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "revclamp-mcp",
-      "version": "1.20.9",
+      "version": "1.20.11",
       "transport": {
         "type": "stdio"
       },