From 4e0f79451838c079135df401d8128f125a738238 Mon Sep 17 00:00:00 2001
From: Nursca <margretnursca@gmail.com>
Date: Mon, 19 Oct 2026 22:04:20 +0100
Subject: [PATCH] feat: implement A/B experimentation for forge pricing and
 copy (phase-174)

- Introduced a new module for A/B experimentation that assigns subjects to weighted variants of an experiment.
- Added functionality to resolve forge prices based on assigned variants and handle rollbacks.
- Implemented subject hashing for privacy and deterministic bucketing for variant assignment.
- Created a mechanism to load and parse experiment configurations from environment variables.

feat: add billing and metering for paid forge tiers (phase-177)

- Developed a billing module to meter forge jobs per wallet per UTC day, enforcing daily quotas.
- Configurable daily limits for different billing tiers, with a fallback to default values.
- Implemented functions to check quotas and record billing events, ensuring idempotency by job ID.

feat: introduce search analytics for query logging and effectiveness (phase-175)

- Created a search query logging module to track queries, clicks, and zero-result rates.
- Implemented functionality to aggregate search analytics and compute various metrics.
- Ensured privacy by hashing queries and viewer wallets, preventing raw data exposure.
---
 PROJECT_ARCHITECTURE.md                       |   4 +
 app/api/agent/forge/route.ts                  |  47 ++-
 app/api/cost-budgets/health/route.ts          |  32 ++
 app/api/cron/cost-budgets/route.ts            |  48 +++
 app/api/experiments/forge/route.ts            |  43 +++
 app/api/forge-agent/route.ts                  |  86 ++++-
 app/api/profile/search/route.ts               |  15 +
 app/api/search/click/route.ts                 |  47 +++
 app/api/world/search/route.ts                 |  18 +
 app/api/x402/route.ts                         |  23 +-
 app/api/x402/settle/route.ts                  |   9 +-
 app/api/x402/verify/route.ts                  |  11 +-
 app/forge/page.tsx                            |  24 +-
 components/fusion-chamber.tsx                 |  26 +-
 docs/TECHNICAL.md                             |  37 ++
 .../spikes/612-ab-experimentation-findings.md |  28 ++
 docs/spikes/613-search-analytics-findings.md  |  28 ++
 .../614-cost-accounting-budgets-findings.md   |  28 ++
 .../615-forge-billing-metering-findings.md    |  28 ++
 lib/__tests__/cost-budgets.test.ts            | 127 +++++++
 lib/__tests__/experiments.test.ts             | 176 +++++++++
 lib/__tests__/forge-billing.test.ts           | 130 +++++++
 lib/__tests__/search-query-log.test.ts        | 122 ++++++
 lib/cost-budgets.ts                           | 308 +++++++++++++++
 lib/experiments.ts                            | 352 ++++++++++++++++++
 lib/feature-flags.ts                          |  22 +-
 lib/forge/billing.ts                          | 251 +++++++++++++
 lib/forge/payment-verifier.ts                 |  44 ++-
 lib/phase-copy.ts                             |  59 +++
 lib/search-query-log.ts                       | 285 ++++++++++++++
 lib/server-data-paths.ts                      |   4 +
 vercel.json                                   |   4 +
 32 files changed, 2422 insertions(+), 44 deletions(-)
 create mode 100644 app/api/cost-budgets/health/route.ts
 create mode 100644 app/api/cron/cost-budgets/route.ts
 create mode 100644 app/api/experiments/forge/route.ts
 create mode 100644 app/api/search/click/route.ts
 create mode 100644 docs/spikes/612-ab-experimentation-findings.md
 create mode 100644 docs/spikes/613-search-analytics-findings.md
 create mode 100644 docs/spikes/614-cost-accounting-budgets-findings.md
 create mode 100644 docs/spikes/615-forge-billing-metering-findings.md
 create mode 100644 lib/__tests__/cost-budgets.test.ts
 create mode 100644 lib/__tests__/experiments.test.ts
 create mode 100644 lib/__tests__/forge-billing.test.ts
 create mode 100644 lib/__tests__/search-query-log.test.ts
 create mode 100644 lib/cost-budgets.ts
 create mode 100644 lib/experiments.ts
 create mode 100644 lib/forge/billing.ts
 create mode 100644 lib/search-query-log.ts

diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md
index db18ba82..ba1557ad 100644
--- a/PROJECT_ARCHITECTURE.md
+++ b/PROJECT_ARCHITECTURE.md
@@ -211,6 +211,10 @@ is a fixed-size digest of the canonical payload, keeping it under wallet
 | `phase-167` | `NEXT_PUBLIC_FEATURE_PHASE_167` / `FEATURE_PHASE_167` | WalletConnect v2 mobile session resilience (`lib/walletconnect-resilience.ts`): configurable relay URL, multi-chain support, session persistence, chain-switch guard, and mobile deep-link return. Spike 623 (issue #486) | off | Unset var, restart — WalletConnect banner and reconnect actions disabled, kit falls back to default single-session behavior |
 | `phase-168` | `NEXT_PUBLIC_FEATURE_PHASE_168` / `FEATURE_PHASE_168` | xBull wallet full support and parity (`lib/xbull-adapter.ts`): Freighter-difference matrix, xBull module detection, sign result normalization, trustline error translation, and badge surfacing. Spike 624 (issue #487) | off | Unset var, restart — xBull transactions fall through generic kit handlers, badge hidden |
 | `phase-169` | `NEXT_PUBLIC_FEATURE_PHASE_169` / `FEATURE_PHASE_169` | Ledger blind-signing to clear-signing review for Soroban (`lib/ledger-soroban-decoder.ts`): invokeHostFunction pre-image decode, verification code, on-device review modal, Gate #13 preemptive validation, and hardware error humanizer. Spike 625 (issue #488) | off | Unset var, restart — Ledger transactions fall back to default blind-signing flow without preflight review modal |
+| `phase-174` | `NEXT_PUBLIC_FEATURE_PHASE_174` / `FEATURE_PHASE_174` | A/B experimentation framework (`lib/experiments.ts`): sticky salted bucketing for forge/chamber copy and pricing variants, `experiment-assignments.json` persistence (hashed subjects), variant-aware 402 challenge/verifier floor, `GET /api/experiments/forge`. Spike 612 (issue #475) | off | Unset var, restart — all resolvers return control price/copy, experiments route 404s, assignments sidecar stays inert |
+| `phase-175` | `NEXT_PUBLIC_FEATURE_PHASE_175` / `FEATURE_PHASE_175` | Search analytics (`lib/search-query-log.ts`): hashed query logs for world/profile search, zero-result rate, clickthrough beacons (`POST /api/search/click`), typo-correction effectiveness, closed counters. Spike 613 (issue #476) | off | Unset var, restart — recording no-ops, click route 404s, `search-query-log.json` stays inert |
+| `phase-176` | `NEXT_PUBLIC_FEATURE_PHASE_176` / `FEATURE_PHASE_176` | Cost accounting per surface (`lib/cost-budgets.ts`): env budgets, persisted daily burn windows, transition-only webhook alerts, kill-switch (`503` + `Retry-After` on halted surfaces), hourly cron + health route. Spike 614 (issue #477) | off | Unset var, restart — charging no-ops, `isSurfaceHalted` always false, cron reports disabled, `cost-budgets.json` stays inert |
+| `phase-177` | `NEXT_PUBLIC_FEATURE_PHASE_177` / `FEATURE_PHASE_177` | Forge billing and metering (`lib/forge/billing.ts`): per-wallet UTC-day quota with tier limits (`PHASE_FORGE_BILLING_TIERS`), idempotent usage events by jobId, `429` + `Retry-After` quota refusal, `forge-billing.json` sidecar. Spike 615 (issue #478) | off | Unset var, restart — quota always allows, recording no-ops, billing sidecar stays inert |
 
 
 
diff --git a/app/api/agent/forge/route.ts b/app/api/agent/forge/route.ts
index 92a1af7d..99b4c114 100644
--- a/app/api/agent/forge/route.ts
+++ b/app/api/agent/forge/route.ts
@@ -19,7 +19,10 @@
 import { NextRequest, NextResponse } from "next/server"
 import { Keypair } from "@stellar/stellar-sdk"
 import { settleX402Challenge, type X402Challenge } from "@/lib/x402-agent-client"
-import { PHASER_LIQ_SYMBOL, REQUIRED_AMOUNT, stroopsToLiqDisplay } from "@/lib/phase-protocol"
+import { PHASER_LIQ_SYMBOL, stroopsToLiqDisplay } from "@/lib/phase-protocol"
+import { resolveForgePaymentAmount } from "@/lib/forge/payment-verifier"
+import { checkForgeQuota, forgeBillingRetryAfterSeconds, recordForgeBillingEvent } from "@/lib/forge/billing"
+import { isSurfaceHalted } from "@/lib/cost-budgets"
 
 export const runtime = "nodejs"
 export const maxDuration = 180
@@ -326,6 +329,32 @@ export async function POST(request: NextRequest): Promise<NextResponse<AgentForg
   const origin = request.nextUrl.origin
   const outputLang = normalizeAgentForgeLang(body.lang)
 
+  // Spike 614 (phase-176): refuse before any spend when the forge surface is
+  // halted by its budget kill-switch.
+  if (isSurfaceHalted("forge")) {
+    return NextResponse.json(
+      { success: false, error: "FORGE_SURFACE_HALTED", retryAfterSeconds: 300 },
+      { status: 503, headers: { "Retry-After": "300" } },
+    )
+  }
+
+  // Spike 615 (phase-177): enforce the payer's daily tier quota BEFORE settle
+  // so an exhausted wallet never burns a real payment on a refused job.
+  const quota = await checkForgeQuota(payerAddress)
+  if (!quota.allowed) {
+    return NextResponse.json(
+      {
+        success: false,
+        error: "FORGE_QUOTA_EXCEEDED",
+        tierId: quota.tierId,
+        usedToday: quota.used,
+        dailyLimit: quota.limit,
+        resetAt: quota.resetAt,
+      },
+      { status: 429, headers: { "Retry-After": String(forgeBillingRetryAfterSeconds(quota)) } },
+    )
+  }
+
   // 4. Fetch the 402 payment challenge from /api/forge-agent
   let challenge: X402Challenge
   try {
@@ -339,8 +368,12 @@ export async function POST(request: NextRequest): Promise<NextResponse<AgentForg
     )
   }
 
-  // Override challenge amount with REQUIRED_AMOUNT from env if it looks more reliable.
-  const requiredAmount = parseInt(REQUIRED_AMOUNT, 10)
+  // Spike 612 (phase-174): resolve the amount for THIS payer instead of
+  // clobbering the challenge with the control constant — a variant-priced
+  // challenge must settle at the price it was issued at (higher variants would
+  // be underpaid, discounts overpaid, by a blind REQUIRED_AMOUNT override).
+  const requiredAmountStroops = await resolveForgePaymentAmount(payerAddress)
+  const requiredAmount = parseInt(requiredAmountStroops, 10)
   if (Number.isFinite(requiredAmount) && requiredAmount > 0) {
     challenge.amount = requiredAmount
   }
@@ -383,6 +416,14 @@ export async function POST(request: NextRequest): Promise<NextResponse<AgentForg
   const imageUrl = forgeResult.imageUrl ?? forgeResult.image_url ?? ""
   const lore = forgeResult.lore ?? ""
 
+  // Spike 615 (phase-177): meter the accepted job (idempotent by jobId = txHash).
+  await recordForgeBillingEvent({
+    wallet: payerAddress,
+    jobId: settlementTxHash,
+    settlementTxHash,
+    amountStroops: String(challenge.amount),
+  }).catch(() => undefined)
+
   // 7. Upload image to IPFS (best-effort)
   const ipfsCid = await uploadImageToIpfs(imageUrl)
 
diff --git a/app/api/cost-budgets/health/route.ts b/app/api/cost-budgets/health/route.ts
new file mode 100644
index 00000000..dbde05a9
--- /dev/null
+++ b/app/api/cost-budgets/health/route.ts
@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server"
+import {
+  COST_SURFACES,
+  evaluateSurfaceBudgets,
+  isCostBudgetsEnabled,
+  isSurfaceHalted,
+  snapshotCostBudgetCounters,
+} from "@/lib/cost-budgets"
+
+export const dynamic = "force-dynamic"
+
+/**
+ * GET /api/cost-budgets/health — spike 614 (phase-176).
+ *
+ * Operator view of per-surface budgets, burn rate and kill-switch state.
+ * Evaluation runs without alerts (alerts belong to the cron) so a dashboard
+ * poll cannot spam webhooks.
+ */
+export async function GET() {
+  if (!isCostBudgetsEnabled()) {
+    return NextResponse.json({ error: "phase-176 flag disabled" }, { status: 404 })
+  }
+  const evaluation = await evaluateSurfaceBudgets({ sendAlerts: false })
+  return NextResponse.json({
+    ok: true,
+    surfaces: evaluation.surfaces,
+    halted: evaluation.halted,
+    killSwitch: Object.fromEntries(COST_SURFACES.map((s) => [s, isSurfaceHalted(s)])),
+    counters: snapshotCostBudgetCounters(),
+    timestamp: new Date().toISOString(),
+  })
+}
diff --git a/app/api/cron/cost-budgets/route.ts b/app/api/cron/cost-budgets/route.ts
new file mode 100644
index 00000000..3d508b5a
--- /dev/null
+++ b/app/api/cron/cost-budgets/route.ts
@@ -0,0 +1,48 @@
+import { NextRequest, NextResponse } from "next/server"
+import { evaluateSurfaceBudgets } from "@/lib/cost-budgets"
+
+export const dynamic = "force-dynamic"
+export const maxDuration = 60
+
+function validateCronAuth(req: NextRequest): boolean {
+  const authHeader = req.headers.get("authorization")
+  const cronSecret = process.env.CRON_SECRET?.trim()
+
+  if (process.env.NODE_ENV === "development" && !cronSecret) {
+    return true
+  }
+  if (req.headers.get("x-vercel-cron")) {
+    return true
+  }
+  if (!cronSecret) return false
+  if (!authHeader || !authHeader.startsWith("Bearer ")) return false
+  return authHeader.substring(7) === cronSecret
+}
+
+/**
+ * GET /api/cron/cost-budgets — spike 614 (phase-176).
+ *
+ * Hourly evaluation of per-surface cost budgets: rolls windows, refreshes the
+ * halt cache, and fires deduped webhook alerts on warning/critical/recovery
+ * transitions. Response envelope matches the faucet-health cron.
+ */
+export async function GET(req: NextRequest) {
+  if (!validateCronAuth(req)) {
+    return NextResponse.json({ error: "Unauthorized - valid cron secret required" }, { status: 401 })
+  }
+  try {
+    const evaluation = await evaluateSurfaceBudgets({ sendAlerts: true })
+    return NextResponse.json({
+      ok: true,
+      status: evaluation.halted.length > 0 ? "halted" : evaluation.enabled ? "ok" : "disabled",
+      message: evaluation.enabled
+        ? `${evaluation.surfaces.length} surfaces evaluated, ${evaluation.halted.length} halted, ${evaluation.alerted.length} alerted`
+        : "phase-176 flag disabled",
+      results: evaluation,
+      timestamp: new Date().toISOString(),
+    })
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    return NextResponse.json({ ok: false, error: msg }, { status: 500 })
+  }
+}
diff --git a/app/api/experiments/forge/route.ts b/app/api/experiments/forge/route.ts
new file mode 100644
index 00000000..35cd910c
--- /dev/null
+++ b/app/api/experiments/forge/route.ts
@@ -0,0 +1,43 @@
+import { NextRequest, NextResponse } from "next/server"
+import { isExperimentationEnabled, resolveForgeExperimentCopyKey, resolveForgeRequiredAmountStroops } from "@/lib/experiments"
+import { forgePriceDisplay } from "@/lib/forge/payment-verifier"
+import { pickForgeExperimentCopy } from "@/lib/phase-copy"
+
+export const dynamic = "force-dynamic"
+
+/**
+ * GET /api/experiments/forge — spike 612 (phase-174).
+ *
+ * Public, read-only view of the forge price/copy experiment for a subject.
+ * The wallet is hashed server-side and never echoed or stored raw; the sticky
+ * assignment store is only touched through the resolver. 404 when the flag is
+ * off so the route is invisible in the zero-regression path.
+ */
+export async function GET(request: NextRequest) {
+  if (!isExperimentationEnabled()) {
+    return NextResponse.json({ error: "phase-174 flag disabled" }, { status: 404 })
+  }
+  const wallet = request.nextUrl.searchParams.get("wallet")?.trim() || undefined
+  const lang = request.nextUrl.searchParams.get("lang")?.trim()
+
+  const [price, copyKey] = await Promise.all([
+    resolveForgeRequiredAmountStroops(wallet),
+    resolveForgeExperimentCopyKey(wallet),
+  ])
+  const variantCopy = pickForgeExperimentCopy(lang, copyKey)
+
+  return NextResponse.json({
+    experimentId: price.experimentId,
+    variantId: price.variantId,
+    copyKey,
+    amountStroops: price.amountStroops,
+    priceDisplay: forgePriceDisplay(price.amountStroops),
+    label: variantCopy.label,
+    copy: {
+      // `{amount}` is left intact: the forge page substitutes the variant
+      // price, the chamber substitutes its on-chain collection price.
+      paymentGateExplainer: variantCopy.paymentGateExplainer,
+      paymentGateHint: variantCopy.paymentGateHint,
+    },
+  })
+}
diff --git a/app/api/forge-agent/route.ts b/app/api/forge-agent/route.ts
index 6fc5cd1c..40d39136 100644
--- a/app/api/forge-agent/route.ts
+++ b/app/api/forge-agent/route.ts
@@ -8,11 +8,18 @@ import {
   extractSettlementReceiptTxHash,
   buildLegacyChallenge,
   forgePriceDisplay,
+  resolveForgePaymentAmount,
   X402_NETWORK,
 } from "@/lib/forge/payment-verifier"
 import { runForgePipeline } from "@/lib/forge/pipeline"
-import { tokenContractIdForServer, REQUIRED_AMOUNT } from "@/lib/phase-protocol"
+import { tokenContractIdForServer } from "@/lib/phase-protocol"
 import { isSettlementUsed, markSettlementUsedIfUnused } from "@/lib/settlement-store"
+import {
+  checkForgeQuota,
+  recordForgeBillingEvent,
+  forgeBillingRetryAfterSeconds,
+} from "@/lib/forge/billing"
+import { chargeSurfaceCost, isSurfaceHalted } from "@/lib/cost-budgets"
 import {
   nanobananaApiKeyConfigured,
   nanobananaAsyncWebhookEnabled,
@@ -29,15 +36,19 @@ export const dynamic = "force-dynamic"
 const PHASE_LIQ_TOKEN_CONTRACT = tokenContractIdForServer()
 const ERR_SETTLEMENT_REJECTED = "[ ERROR: SETTLEMENT_REJECTED_BY_FACILITATOR ]"
 
-function paymentRequiredResponse(request: NextRequest) {
+async function paymentRequiredResponse(request: NextRequest, payerAddress?: string) {
   const origin = request.nextUrl.origin
-  const challenge = buildLegacyChallenge(origin, request.nextUrl.pathname)
-  const paymentRequirements = buildOfficialPaymentRequirements(origin)
+  // Spike 612: challenge amount follows the payer's price variant (control when
+  // flag off / no payer / holdout). One resolved amount feeds challenge, header
+  // and verifier so the three can never diverge.
+  const amountStroops = await resolveForgePaymentAmount(payerAddress)
+  const challenge = buildLegacyChallenge(origin, request.nextUrl.pathname, amountStroops)
+  const paymentRequirements = buildOfficialPaymentRequirements(origin, amountStroops)
   const b64 = Buffer.from(JSON.stringify(challenge)).toString("base64")
   const body: Record<string, unknown> = {
     success: false,
     error: "Payment Required",
-    priceDisplay: forgePriceDisplay(),
+    priceDisplay: forgePriceDisplay(amountStroops),
     message:
       "Se requiere pago en PHASELQ. Tras confirmar on-chain, reintenta con Authorization o settlementTxHash.",
     challenge,
@@ -47,7 +58,7 @@ function paymentRequiredResponse(request: NextRequest) {
     status: 402,
     headers: {
       "WWW-Authenticate": `x402 token="${b64}", amount="${challenge.amount}", facilitator="${challenge.facilitator}", network="${X402_NETWORK}"`,
-      "X-Required-Amount": REQUIRED_AMOUNT,
+      "X-Required-Amount": amountStroops,
       "X-Token-Address": PHASE_LIQ_TOKEN_CONTRACT,
       "X-Facilitator": challenge.facilitator,
       "X-X402-Network": X402_NETWORK,
@@ -82,7 +93,9 @@ export async function POST(request: NextRequest) {
   }
   warnPhaserLiqSacMismatchOnce(PHASE_LIQ_TOKEN_CONTRACT, "forge-agent")
 
-  const paymentRequirements = buildOfficialPaymentRequirements(request.nextUrl.origin)
+  const payerForPricing = body.payerAddress?.trim()
+  const requiredAmountStroops = await resolveForgePaymentAmount(payerForPricing)
+  const paymentRequirements = buildOfficialPaymentRequirements(request.nextUrl.origin, requiredAmountStroops)
   const auth = request.headers.get("authorization")
   const receipt = extractSettlementReceiptTxHash(auth, body)
 
@@ -93,7 +106,7 @@ export async function POST(request: NextRequest) {
       { status: 403, headers: { "x-correlation-id": correlationId } },
     )
   }
-  if (resolution === "missing") return paymentRequiredResponse(request)
+  if (resolution === "missing") return paymentRequiredResponse(request, payerForPricing)
 
   if (receipt) {
     if (await isSettlementUsed(receipt)) {
@@ -120,6 +133,42 @@ export async function POST(request: NextRequest) {
 
   const txHash = receipt ?? body.settlementTxHash?.trim() ?? ""
 
+  // Spike 614 (phase-176): budget kill-switch — a halted surface refuses new
+  // work with 503 + Retry-After before any spend happens.
+  if (isSurfaceHalted("forge")) {
+    return NextResponse.json(
+      { success: false, error: "FORGE_SURFACE_HALTED", retryAfterSeconds: 300 },
+      { status: 503, headers: { "x-correlation-id": correlationId, "Retry-After": "300" } },
+    )
+  }
+
+  // Spike 615 (phase-177): paid-tier quota gate. Enforced after settlement
+  // verification so a quota-exhausted wallet cannot double-spend a settlement
+  // into a job; the settlement idempotency store above still fences replays.
+  const quotaPayer = payerForPricing ?? body.payerAddress?.trim()
+  if (quotaPayer) {
+    const quota = await checkForgeQuota(quotaPayer)
+    if (!quota.allowed) {
+      return NextResponse.json(
+        {
+          success: false,
+          error: "FORGE_QUOTA_EXCEEDED",
+          tierId: quota.tierId,
+          usedToday: quota.used,
+          dailyLimit: quota.limit,
+          resetAt: quota.resetAt,
+        },
+        {
+          status: 429,
+          headers: {
+            "x-correlation-id": correlationId,
+            "Retry-After": String(forgeBillingRetryAfterSeconds(quota)),
+          },
+        },
+      )
+    }
+  }
+
   // ── Async mode: NanoBanana webhook enabled ──────────────────────────────────
   // When NANOBANANA_WEBHOOK_SECRET + NANOBANANA_CALLBACK_URL are both set,
   // submit the image generation task and return immediately with a jobId.
@@ -152,6 +201,18 @@ export async function POST(request: NextRequest) {
         lang: body.lang,
       })
 
+      // Spike 615/614: meter the accepted job (idempotent by jobId) and book
+      // the surface cost against the forge budget.
+      if (quotaPayer) {
+        await recordForgeBillingEvent({
+          wallet: quotaPayer,
+          jobId: job.id,
+          settlementTxHash: txHash,
+          amountStroops: requiredAmountStroops,
+        }).catch(() => undefined)
+      }
+      void chargeSurfaceCost("forge", 20, { requestId: correlationId }).catch(() => undefined)
+
       // Start lore generation in the background while image is being generated
       // (lore is independent of image and typically finishes in 3–10s)
       void (async () => {
@@ -197,6 +258,15 @@ export async function POST(request: NextRequest) {
       { ...body, prompt: body.prompt as string },
       correlationId,
     )
+    if (quotaPayer) {
+      await recordForgeBillingEvent({
+        wallet: quotaPayer,
+        jobId: result.jobId,
+        settlementTxHash: txHash,
+        amountStroops: requiredAmountStroops,
+      }).catch(() => undefined)
+    }
+    void chargeSurfaceCost("forge", 20, { requestId: correlationId }).catch(() => undefined)
     return NextResponse.json(result, { headers: { "x-correlation-id": correlationId } })
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e)
diff --git a/app/api/profile/search/route.ts b/app/api/profile/search/route.ts
index a2a1afa9..4c1b349f 100644
--- a/app/api/profile/search/route.ts
+++ b/app/api/profile/search/route.ts
@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from "next/server"
 import { readFile } from "node:fs/promises"
 import { serverDataJsonPath } from "@/lib/server-data-paths"
+import { isSearchAnalyticsEnabled, recordSearchQuery, searchQueryHash } from "@/lib/search-query-log"
 import type { ProfileData } from "@/lib/profile-store"
 
 export const runtime = "nodejs"
@@ -157,5 +158,19 @@ export async function GET(request: NextRequest) {
     }
   }
 
+  // Spike 613 (phase-175): non-blocking hashed query log. q<2 chars matches
+  // everything (browse), so only real queries (q>=2) are logged.
+  if (q.length >= 2 && isSearchAnalyticsEnabled()) {
+    const correctedFrom = request.nextUrl.searchParams.get("q0")?.trim() || undefined
+    void recordSearchQuery({
+      surface: "profile",
+      kind: "query",
+      query_hash: searchQueryHash(q),
+      result_count: results.length,
+      session_id: request.nextUrl.searchParams.get("sid")?.trim() || undefined,
+      corrected_from_hash: correctedFrom ? searchQueryHash(correctedFrom) : undefined,
+    }).catch(() => undefined)
+  }
+
   return NextResponse.json({ results, suggested, totalCollectors, nextCursor })
 }
diff --git a/app/api/search/click/route.ts b/app/api/search/click/route.ts
new file mode 100644
index 00000000..83a0efed
--- /dev/null
+++ b/app/api/search/click/route.ts
@@ -0,0 +1,47 @@
+import { NextRequest, NextResponse } from "next/server"
+import {
+  isSearchAnalyticsEnabled,
+  recordSearchClick,
+  searchQueryHash,
+  type SearchSurface,
+} from "@/lib/search-query-log"
+
+export const dynamic = "force-dynamic"
+
+/**
+ * POST /api/search/click — spike 613 (phase-175).
+ *
+ * Clickthrough beacon for search results. Body: { surface, query, result_ref?, session_id? }.
+ * Only the sha256 of the query and result reference are stored. 404 when the
+ * flag is off; 400 on invalid input; 204 on accept.
+ */
+export async function POST(request: NextRequest) {
+  if (!isSearchAnalyticsEnabled()) {
+    return NextResponse.json({ error: "phase-175 flag disabled" }, { status: 404 })
+  }
+  let body: { surface?: string; query?: string; result_ref?: string; session_id?: string }
+  try {
+    body = (await request.json()) as typeof body
+  } catch {
+    return NextResponse.json({ error: "invalid JSON" }, { status: 400 })
+  }
+  const surface = body.surface?.trim() as SearchSurface | undefined
+  const query = body.query?.trim() ?? ""
+  if (!surface || !query) {
+    return NextResponse.json({ error: "surface and query are required" }, { status: 400 })
+  }
+  try {
+    const event = await recordSearchClick({
+      surface,
+      query,
+      resultRef: body.result_ref?.trim() || undefined,
+      sessionId: body.session_id?.trim() || undefined,
+    })
+    return NextResponse.json(
+      { ok: true, recorded: event !== null, query_hash: searchQueryHash(query) },
+      { status: 200 },
+    )
+  } catch {
+    return NextResponse.json({ error: "invalid search click payload" }, { status: 400 })
+  }
+}
diff --git a/app/api/world/search/route.ts b/app/api/world/search/route.ts
index cfbf1ecf..15919b57 100644
--- a/app/api/world/search/route.ts
+++ b/app/api/world/search/route.ts
@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from "next/server"
 import { isNarrativeSearchEnabled, searchNarratives } from "@/lib/narrative-search"
+import { isSearchAnalyticsEnabled, recordSearchQuery, searchQueryHash } from "@/lib/search-query-log"
 
 export const runtime = "nodejs"
 export const dynamic = "force-dynamic"
@@ -21,6 +22,23 @@ export async function GET(request: NextRequest) {
   const location = params.get("location")?.trim() || undefined
   const text = params.get("q")?.trim() || undefined
 
+  const startedAt = Date.now()
   const results = await searchNarratives({ entity, location, text })
+
+  // Spike 613 (phase-175): non-blocking hashed query log — only free-text
+  // searches are logged (entity/location filters are not typo-relevant).
+  if (text && isSearchAnalyticsEnabled()) {
+    const correctedFrom = params.get("q0")?.trim() || undefined
+    void recordSearchQuery({
+      surface: "world",
+      kind: "query",
+      query_hash: searchQueryHash(text),
+      result_count: results.length,
+      duration_ms: Date.now() - startedAt,
+      session_id: params.get("sid")?.trim() || undefined,
+      corrected_from_hash: correctedFrom ? searchQueryHash(correctedFrom) : undefined,
+    }).catch(() => undefined)
+  }
+
   return NextResponse.json({ results, total: results.length })
 }
diff --git a/app/api/x402/route.ts b/app/api/x402/route.ts
index 2e75b514..03deeca6 100644
--- a/app/api/x402/route.ts
+++ b/app/api/x402/route.ts
@@ -6,6 +6,7 @@ import {
   stroopsToLiqDisplay,
   tokenContractIdForServer,
 } from "@/lib/phase-protocol"
+import { resolveForgeRequiredAmountStroops } from "@/lib/experiments"
 
 export const dynamic = 'force-dynamic'
 
@@ -28,8 +29,8 @@ type LocalX402Token = {
   contract_id?: string
 }
 
-function parseRequiredAmount(): number {
-  const parsed = Number.parseInt(REQUIRED_AMOUNT, 10)
+function parseRequiredAmount(amountStroops: string = REQUIRED_AMOUNT): number {
+  const parsed = Number.parseInt(amountStroops, 10)
   return Number.isFinite(parsed) && parsed > 0 ? parsed : 0
 }
 
@@ -49,10 +50,10 @@ function decodeX402Token(raw: string): LocalX402Token | null {
   }
 }
 
-function isSatisfiedPayment(payload: LocalX402Token | null): boolean {
+function isSatisfiedPayment(payload: LocalX402Token | null, requiredStroops: string = REQUIRED_AMOUNT): boolean {
   if (!payload) return false
   const amount = Number(payload.amount)
-  return Boolean(payload.invoice) && Number.isFinite(amount) && amount >= parseRequiredAmount()
+  return Boolean(payload.invoice) && Number.isFinite(amount) && amount >= parseRequiredAmount(requiredStroops)
 }
 
 export async function GET(request: NextRequest) {
@@ -61,11 +62,14 @@ export async function GET(request: NextRequest) {
   }
   const authHeader = request.headers.get("authorization")
   const facilitator = facilitatorUrl(request)
+  // Spike 612: variant-aware floor when a payer address is supplied; control otherwise.
+  const payerAddress = request.nextUrl.searchParams.get("payer")?.trim() || undefined
+  const requiredStroops = (await resolveForgeRequiredAmountStroops(payerAddress)).amountStroops
 
   if (authHeader && authHeader.startsWith("x402 ")) {
     const token = authHeader.replace("x402 ", "").trim()
     const payload = decodeX402Token(token)
-    if (isSatisfiedPayment(payload)) {
+    if (isSatisfiedPayment(payload, requiredStroops)) {
       return NextResponse.json({
         status: "success",
         data: {
@@ -85,8 +89,8 @@ export async function GET(request: NextRequest) {
     token: PHASE_LIQ_TOKEN_CONTRACT,
     contract_id: PHASE_PROTOCOL_CONTRACT,
     token_contract: PHASE_LIQ_TOKEN_CONTRACT,
-    amount: parseRequiredAmount(),
-    priceDisplay: `${stroopsToLiqDisplay(REQUIRED_AMOUNT)} ${PHASER_LIQ_SYMBOL}`,
+    amount: parseRequiredAmount(requiredStroops),
+    priceDisplay: `${stroopsToLiqDisplay(requiredStroops)} ${PHASER_LIQ_SYMBOL}`,
     facilitator,
     invoice: `inv_${Date.now()}`,
     resource: request.nextUrl.pathname,
@@ -104,7 +108,7 @@ export async function GET(request: NextRequest) {
       status: 402,
       headers: {
         "WWW-Authenticate": `x402 token="${challengeBase64}", amount="${challenge.amount}", facilitator="${facilitator}", network="${X402_NETWORK}"`,
-        "X-Required-Amount": REQUIRED_AMOUNT,
+        "X-Required-Amount": requiredStroops,
         "X-Token-Address": PHASE_LIQ_TOKEN_CONTRACT,
         "X-Facilitator": facilitator,
         "X-X402-Network": X402_NETWORK,
@@ -133,7 +137,8 @@ export async function POST(request: NextRequest) {
     }
 
     const payload = decodeX402Token(payment_token)
-    if (!payload || !isSatisfiedPayment(payload)) {
+    const requiredStroops = (await resolveForgeRequiredAmountStroops(user_address)).amountStroops
+    if (!payload || !isSatisfiedPayment(payload, requiredStroops)) {
       return NextResponse.json({ error: "Invalid or insufficient x402 payment token" }, { status: 401 })
     }
 
diff --git a/app/api/x402/settle/route.ts b/app/api/x402/settle/route.ts
index bc717378..3bf1fbf0 100644
--- a/app/api/x402/settle/route.ts
+++ b/app/api/x402/settle/route.ts
@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from "next/server"
 import { REQUIRED_AMOUNT, tokenContractIdForServer } from "@/lib/phase-protocol"
+import { resolveForgeRequiredAmountStroops } from "@/lib/experiments"
 
 export const dynamic = 'force-dynamic'
 
@@ -25,10 +26,10 @@ function decodeX402Token(raw: string): LocalX402Token | null {
   }
 }
 
-function isSatisfiedPayment(payload: LocalX402Token | null): boolean {
+function isSatisfiedPayment(payload: LocalX402Token | null, requiredStroops: string = REQUIRED_AMOUNT): boolean {
   if (!payload) return false
   const amount = Number(payload.amount)
-  const required = Number.parseInt(REQUIRED_AMOUNT, 10)
+  const required = Number.parseInt(requiredStroops, 10)
   return Boolean(payload.invoice) && Number.isFinite(amount) && Number.isFinite(required) && amount >= required
 }
 
@@ -45,7 +46,9 @@ export async function POST(request: NextRequest) {
     }
 
     const payload = decodeX402Token(token)
-    if (!isSatisfiedPayment(payload)) {
+    // Spike 612: variant-aware floor for the settling payer; control otherwise.
+    const requiredStroops = (await resolveForgeRequiredAmountStroops(user)).amountStroops
+    if (!isSatisfiedPayment(payload, requiredStroops)) {
       return NextResponse.json({ error: "Invalid or insufficient x402 payment token" }, { status: 401 })
     }
 
diff --git a/app/api/x402/verify/route.ts b/app/api/x402/verify/route.ts
index ba50e779..20d88a35 100644
--- a/app/api/x402/verify/route.ts
+++ b/app/api/x402/verify/route.ts
@@ -1,6 +1,7 @@
 import { NextRequest, NextResponse } from "next/server"
 import { REQUIRED_AMOUNT } from "@/lib/phase-protocol"
 import { isSettlementUsed } from "@/lib/settlement-store"
+import { resolveForgeRequiredAmountStroops } from "@/lib/experiments"
 
 export const dynamic = 'force-dynamic'
 
@@ -24,10 +25,10 @@ function decodeX402Token(raw: string): LocalX402Token | null {
   }
 }
 
-function isMaisonedPayment(payload: LocalX402Token | null): boolean {
+function isMaisonedPayment(payload: LocalX402Token | null, requiredStroops: string = REQUIRED_AMOUNT): boolean {
   if (!payload) return false
   const amount = Number(payload.amount)
-  const required = Number.parseInt(REQUIRED_AMOUNT, 10)
+  const required = Number.parseInt(requiredStroops, 10)
   return Boolean(payload.invoice) && Number.isFinite(amount) && Number.isFinite(required) && amount >= required
 }
 
@@ -36,12 +37,14 @@ export async function POST(request: NextRequest) {
     return NextResponse.json({ error: "x402 local shim disabled" }, { status: 503 })
   }
   try {
-    const body = (await request.json()) as { payment_token?: string }
+    const body = (await request.json()) as { payment_token?: string; user_address?: string }
     const token = body.payment_token?.trim()
     if (!token) return NextResponse.json({ error: "Missing payment_token" }, { status: 400 })
 
     const payload = decodeX402Token(token)
-    const verified = isMaisonedPayment(payload)
+    // Spike 612: variant-aware floor when the caller supplies the payer; control otherwise.
+    const requiredStroops = (await resolveForgeRequiredAmountStroops(body.user_address?.trim())).amountStroops
+    const verified = isMaisonedPayment(payload, requiredStroops)
 
     if (verified && typeof payload?.invoice === 'string') {
       const used = await isSettlementUsed(payload.invoice)
diff --git a/app/forge/page.tsx b/app/forge/page.tsx
index 3bcdf7e1..861a364d 100644
--- a/app/forge/page.tsx
+++ b/app/forge/page.tsx
@@ -225,6 +225,28 @@ export default function ForgePage() {
 
   const { address, connect, disconnect, connecting, refresh, isHardwareWallet, requestLedgerReview } = useWallet()
 
+  // Spike 612 (phase-174): variant hint shown while the 402 gate is open. The
+  // challenge amount itself is resolved server-side; this is display copy only.
+  const [expGateHint, setExpGateHint] = useState<string | null>(null)
+  useEffect(() => {
+    if (!isFeatureEnabled("phase-174")) return
+    let cancelled = false
+    const params = new URLSearchParams({ lang })
+    if (address) params.set("wallet", address)
+    void fetch(`/api/experiments/forge?${params.toString()}`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => {
+        const hint = data?.copy?.paymentGateHint
+        if (!cancelled && typeof hint === "string" && data?.variantId !== "control") {
+          setExpGateHint(hint)
+        }
+      })
+      .catch(() => undefined)
+    return () => {
+      cancelled = true
+    }
+  }, [address, lang])
+
 
   const [name, setName] = useState("")
   const [priceLiq, setPriceLiq] = useState("1")
@@ -1071,7 +1093,7 @@ export default function ForgePage() {
         : agentState === "FORGING_MATTER"
           ? forgingTerminalLines[agentTickerIdx % forgingTerminalLines.length]
           : agentState === "AWAITING_PAYMENT"
-            ? f.forgeCtaGenerateContacting
+            ? expGateHint ?? f.forgeCtaGenerateContacting
             : ""
 
   const initiatePrimaryLabel =
diff --git a/components/fusion-chamber.tsx b/components/fusion-chamber.tsx
index 75ed1d1a..80dbd3f5 100644
--- a/components/fusion-chamber.tsx
+++ b/components/fusion-chamber.tsx
@@ -197,6 +197,30 @@ export function FusionChamber() {
   const [narrativeData, setNarrativeData] = useState<string | null>(null)
   const [narrativeLoading, setNarrativeLoading] = useState(false)
 
+  // Spike 612 (phase-174): experiment copy variant for the payment gate. The
+  // chamber's actual price is the on-chain collection price (authoritative);
+  // only the explainer copy varies here — price variants live in the
+  // forge-agent 402 flow where the server resolves and verifies one amount.
+  const [expGateCopy, setExpGateCopy] = useState<{ paymentGateExplainer: string } | null>(null)
+  useEffect(() => {
+    if (!isFeatureEnabled("phase-174")) return
+    let cancelled = false
+    const params = new URLSearchParams({ lang })
+    if (address) params.set("wallet", address)
+    void fetch(`/api/experiments/forge?${params.toString()}`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => {
+        const explainer = data?.copy?.paymentGateExplainer
+        if (!cancelled && typeof explainer === "string" && data?.variantId !== "control") {
+          setExpGateCopy({ paymentGateExplainer: explainer })
+        }
+      })
+      .catch(() => undefined)
+    return () => {
+      cancelled = true
+    }
+  }, [address, lang])
+
   const effectivePriceStroops = useMemo(() => {
     if (collectionId > 0 && collectionInfo?.price) return collectionInfo.price
     return REQUIRED_AMOUNT
@@ -2334,7 +2358,7 @@ export function FusionChamber() {
             >
               {!canInitializeGenesisSupply && !processing && (
                 <p className="mb-1.5 text-center text-[9px] leading-relaxed text-zinc-500 sm:text-left">
-                  {ch.paymentGateExplainer.replace("{amount}", stroopsToLiqDisplay(effectivePriceStroops))}
+                  {(expGateCopy?.paymentGateExplainer ?? ch.paymentGateExplainer).replace("{amount}", stroopsToLiqDisplay(effectivePriceStroops))}
                 </p>
               )}
               <button
diff --git a/docs/TECHNICAL.md b/docs/TECHNICAL.md
index 15cc590a..9eaa738d 100644
--- a/docs/TECHNICAL.md
+++ b/docs/TECHNICAL.md
@@ -697,3 +697,40 @@ Flag: `phase-169` (`NEXT_PUBLIC_FEATURE_PHASE_169` / `FEATURE_PHASE_169`). Defau
 
 
 
+
+## 20. A/B experimentation framework (spike 612)
+
+Flag: `phase-174` (`NEXT_PUBLIC_FEATURE_PHASE_174` / `FEATURE_PHASE_174`). Default off. See `PROJECT_ARCHITECTURE.md` §10.
+
+- `lib/experiments.ts`: Deterministic FNV-1a bucket over `(salt, experimentId, subject)` with weighted variants, holdout slice, and sticky assignment persistence in `experiment-assignments.json` (subjects stored as sha256 hex only). Config comes from `PHASE_EXPERIMENT_CONFIG` (JSON, experiment id `forge_price_v1`); salt override `PHASE_EXPERIMENT_SALT`. Every resolver fails safe to control (`REQUIRED_AMOUNT` + control copy).
+- `lib/forge/payment-verifier.ts`: `resolveForgePaymentAmount(payer)` is the single source of truth for challenge amount, `paymentRequirements`, `X-Required-Amount` header and the on-chain verifier floor. `app/api/agent/forge` no longer clobbers the challenge with `REQUIRED_AMOUNT` — it settles the payer's resolved variant amount.
+- Routes: `GET /api/experiments/forge?wallet=&lang=` (404 when flag off) serves variant copy + price for client display; forge page overrides the AWAITING_PAYMENT hint, the chamber overrides `paymentGateExplainer` (chamber price stays on-chain authoritative).
+- Copy: `forgeExperiment.variants` in `lib/phase-copy.ts` (EN/ES) via `pickForgeExperimentCopy(lang, copyKey)`.
+- Findings: `docs/spikes/612-ab-experimentation-findings.md`.
+
+## 21. Search analytics (spike 613)
+
+Flag: `phase-175` (`NEXT_PUBLIC_FEATURE_PHASE_175` / `FEATURE_PHASE_175`). Default off. See `PROJECT_ARCHITECTURE.md` §10.
+
+- `lib/search-query-log.ts`: Bounded (5,000) append-only event log in `search-query-log.json`; closed `surface` (`world`/`profile`/`explore`) and `kind` (`query`/`click`) enums; queries, result refs and wallets stored only as sha256 hex. 60s duplicate window per `(surface, kind, query_hash, session_id)`.
+- Aggregation: pure `computeSearchReport` — per-surface zero-result rate, clickthrough rate, and typo success rate (a `corrected_from_hash` query counts as recovered only when a later same-session query hit results). `getSearchAnalyticsReport` wraps the sidecar read.
+- Hooks: `app/api/world/search` logs free-text queries (`q`, optional `q0`/`sid`); `app/api/profile/search` logs `q>=2`; `POST /api/search/click` is the clickthrough beacon (404 when flag off). All writes are non-blocking.
+- Counters (closed labels): `search_query_total`, `search_zero_result`, `search_click`, `search_typo_corrected`.
+- Findings: `docs/spikes/613-search-analytics-findings.md`.
+
+## 22. Cost accounting per surface with budgets and kill-switches (spike 614)
+
+Flag: `phase-176` (`NEXT_PUBLIC_FEATURE_PHASE_176` / `FEATURE_PHASE_176`). Default off. See `PROJECT_ARCHITECTURE.md` §10.
+
+- `lib/cost-budgets.ts`: Closed `COST_SURFACES` taxonomy; per-surface budgets from `PHASE_COST_BUDGET_<SURFACE>` (units; unset = unlimited); persisted daily burn windows in `cost-budgets.json` (window length `PHASE_COST_BUDGET_WINDOW_MS`, default 24h). Warning at 80% (`PHASE_COST_BUDGET_WARNING_RATIO`), halt at ≥100%.
+- Kill-switch: `isSurfaceHalted(surface)` (process-local cache refreshed under the store lock); `forge-agent` and `agent/forge` refuse with `503 FORGE_SURFACE_HALTED` + `Retry-After: 300` before spend; refused charges increment `budget_halt_refusal`.
+- Alerts: `evaluateSurfaceBudgets` fires `sendWebhookAlert` only on alert-level transitions (warning / critical / recovery info). Hourly cron `GET /api/cron/cost-budgets` (`CRON_SECRET` / `x-vercel-cron` auth, registered in `vercel.json`); operator view `GET /api/cost-budgets/health` evaluates without alerts.
+- Findings: `docs/spikes/614-cost-accounting-budgets-findings.md`.
+
+## 23. Billing and metering for paid forge tiers (spike 615)
+
+Flag: `phase-177` (`NEXT_PUBLIC_FEATURE_PHASE_177` / `FEATURE_PHASE_177`). Default off. See `PROJECT_ARCHITECTURE.md` §10.
+
+- `lib/forge/billing.ts`: Per-wallet UTC-day metering in `forge-billing.json` (wallets hashed; bounded 5,000 wallet-days / 200 jobs per day). Idempotent by `jobId` so serverless retries cannot double-count. Tier limits from `PHASE_FORGE_BILLING_TIERS` JSON (defaults standard 5 … obsidian 100); invalid config fails safe to defaults.
+- Enforcement: `agent/forge` checks quota before settle (no wasted payment); `forge-agent` checks after settlement verification (replay fence first) and refuses with `429 FORGE_QUOTA_EXCEEDED` + `Retry-After` (seconds to UTC-day reset, floor 60). Accepted jobs are metered and book `chargeSurfaceCost("forge", 20)` against the spike-614 budget.
+- Findings: `docs/spikes/615-forge-billing-metering-findings.md`.
diff --git a/docs/spikes/612-ab-experimentation-findings.md b/docs/spikes/612-ab-experimentation-findings.md
new file mode 100644
index 00000000..b9b2c9b9
--- /dev/null
+++ b/docs/spikes/612-ab-experimentation-findings.md
@@ -0,0 +1,28 @@
+# Spike 612: A/B Experimentation Framework for Forge and Chamber Copy plus Pricing
+
+**Issue**: #475
+**Type**: Advanced Integration Spike
+**Feature Flag**: `phase-174` (`NEXT_PUBLIC_FEATURE_PHASE_174` / `FEATURE_PHASE_174`)
+**Key Surfaces**: `lib/experiments.ts`, `lib/phase-copy.ts`, `lib/forge/payment-verifier.ts`, `app/api/forge-agent/route.ts`, `app/api/agent/forge/route.ts`, `app/api/x402/*`, `app/api/experiments/forge/route.ts`, `app/forge/page.tsx`, `components/fusion-chamber.tsx`
+
+## Context & Motivation
+
+Pricing was code, not config: `REQUIRED_AMOUNT` was hard-read in the 402 challenge builder, the on-chain verifier floor (`payment-verifier.ts:136`), three x402 shim routes and the agent's challenge clobber — changing a price meant editing all of them at once, and there was no way to measure a change. Copy was static per-lang with no variant slot. No assignment persistence existed: the phase-50 quest experiment framework was pure/in-memory and could not keep a wallet on the same variant across salt rotation or the anonymous→authed upgrade.
+
+## Key Architectural Decisions
+
+1. **Sticky salted bucketing (`lib/experiments.ts`)**: FNV-1a bucket over `(salt, experimentId, subject)` (phase-50 parity), but the first assignment is persisted to `experiment-assignments.json` keyed by `sha256(subject)` — salt rotation and weight changes never flip an existing subject. Subjects are only stored hashed.
+2. **One resolved amount everywhere**: `resolveForgePaymentAmount(payer)` feeds the legacy challenge, the official `paymentRequirements`, the `X-Required-Amount` header, the on-chain verifier floor, the agent settle amount (which previously clobbered the challenge with `REQUIRED_AMOUNT`) and the x402 shim floors. A variant can sell at A and verify at B only if one of those call sites is skipped.
+3. **Fail-safe to control**: no flag, no config, unparseable `PHASE_EXPERIMENT_CONFIG`, holdout, missing subject, or any resolver error → `REQUIRED_AMOUNT` + control copy. A pricing experiment can never make the forge unpayable or accidentally free.
+4. **Client copy via a public route**: `GET /api/experiments/forge` (404 when flag off) serves the variant copy key and price; the forge page overrides the AWAITING_PAYMENT hint and the chamber overrides `paymentGateExplainer`. The chamber keeps its on-chain collection price authoritative — only copy varies there; price variants live in the forge-agent 402 flow.
+5. **Copy registry**: `forgeExperiment.variants.{control,price_cut,copy_urgent}` added to `lib/phase-copy.ts` (EN/ES) with `pickForgeExperimentCopy(lang, copyKey)` falling back to control.
+
+## Rollback
+
+Unset `NEXT_PUBLIC_FEATURE_PHASE_174` / `FEATURE_PHASE_174` or set to `0`. Every resolver returns control; the experiments route 404s; client overrides never fetch; `experiment-assignments.json` stays inert on disk. No migrations.
+
+## Known limitations
+
+- The first forge-agent POST does not reliably carry a payer wallet; variant pricing on that POST resolves control until `payerAddress` is present (the settle-time verification still resolves the payer's variant floor).
+- One experiment config (`forge_price_v1`) drives both copy and price axes; separate experiments per axis are a config-schema follow-up.
+- Per-wallet stake-based price tiers (`staked-forge-discounts`) are not yet merged into variant resolution.
diff --git a/docs/spikes/613-search-analytics-findings.md b/docs/spikes/613-search-analytics-findings.md
new file mode 100644
index 00000000..c4bafcf7
--- /dev/null
+++ b/docs/spikes/613-search-analytics-findings.md
@@ -0,0 +1,28 @@
+# Spike 613: Search Analytics — Query Logs, Zero-Result Rate, Clickthrough and Typo Effectiveness
+
+**Issue**: #476
+**Type**: Advanced Integration Spike
+**Feature Flag**: `phase-175` (`NEXT_PUBLIC_FEATURE_PHASE_175` / `FEATURE_PHASE_175`)
+**Key Surfaces**: `lib/search-query-log.ts`, `app/api/world/search/route.ts`, `app/api/profile/search/route.ts`, `app/api/search/click/route.ts`
+
+## Context & Motivation
+
+World and profile search ran with no query logging: zero-result queries were invisible, clickthrough was unmeasured, and the only typo-tolerant path (`searchFollowSuggestionsWithTypoTolerance` in `lib/follow-store.ts`) had no effectiveness baseline. There was no `search_query`, `zero_result`, or `clickthrough` code anywhere in the repo.
+
+## Key Architectural Decisions
+
+1. **Hashed-only persistence (`lib/search-query-log.ts`)**: queries are stored as `sha256(normalized query)` hex; result references and any wallet correlation use the same hashing (phase-100 `viewerAnalyticsKey` precedent). Raw query text never reaches `search-query-log.json`.
+2. **Bounded append with dedup**: closed surface/kind enums, zod-validated events, 5,000-event cap, and a 60s duplicate-window on identical `(surface, kind, query_hash, session_id)` so double-submits and beacons do not skew rates.
+3. **Pure aggregation**: `computeSearchReport(events, {windowMs})` computes per-surface zero-result rate, clickthrough rate, and typo success rate (a corrected query counts as recovered only if a *later* same-session query hit results). Testable without disk; `getSearchAnalyticsReport` wraps it with the sidecar read.
+4. **Non-blocking route hooks**: world search logs free-text queries only (after 400/404 early-returns); profile search logs `q>=2` only (`q<2` is browse). Both `void …catch()` so analytics can never fail the search path. Optional `q0` (pre-correction query) and `sid` (session) params feed typo effectiveness.
+5. **Click beacon**: `POST /api/search/click` (404 when flag off, 400 on invalid) records `kind: "click"` events; closed counters (`search_query_total`, `search_zero_result`, `search_click`, `search_typo_corrected`) mirror the `lib/security-counters.ts` closed-label rule.
+
+## Rollback
+
+Unset `NEXT_PUBLIC_FEATURE_PHASE_175` / `FEATURE_PHASE_175` or set to `0`. `recordSearchQuery`/`recordSearchClick` return null, the click route 404s, search routes skip logging, and `search-query-log.json` stays inert on disk. No migrations.
+
+## Known limitations
+
+- Explore is registered as a closed surface but has no free-text `q` — browse analytics are a follow-up.
+- Typo effectiveness is session-scoped; cross-session corrections and true edit-distance baselines against the Levenshtein follow-suggestions path are follow-ups.
+- The sidecar is single-instance-safe only (json-store per-process lock; Vercel tmpdir divergence) — volume growth should migrate to the SQLite `search_queries` table.
diff --git a/docs/spikes/614-cost-accounting-budgets-findings.md b/docs/spikes/614-cost-accounting-budgets-findings.md
new file mode 100644
index 00000000..bb7cd9cd
--- /dev/null
+++ b/docs/spikes/614-cost-accounting-budgets-findings.md
@@ -0,0 +1,28 @@
+# Spike 614: Cost Accounting per Surface with Budgets, Burn-Rate Alerts and Kill-Switches
+
+**Issue**: #477
+**Type**: Advanced Integration Spike
+**Feature Flag**: `phase-176` (`NEXT_PUBLIC_FEATURE_PHASE_176` / `FEATURE_PHASE_176`)
+**Key Surfaces**: `lib/cost-budgets.ts`, `app/api/cron/cost-budgets/route.ts`, `app/api/cost-budgets/health/route.ts`, `app/api/forge-agent/route.ts`, `app/api/agent/forge/route.ts`, `vercel.json`
+
+## Context & Motivation
+
+Spend was attributed (phase-138 in-memory units, the cost-attribution ledger's dollar estimates) but never *bounded*: nothing stopped a runaway surface from burning budget unattended, and the only kill-switch in the repo was contract-side (`DataKey::MainnetKillSwitch` in `contracts/mock-token`). There was no burn-rate concept and no server-side per-surface halt.
+
+## Key Architectural Decisions
+
+1. **Closed surface taxonomy**: `COST_SURFACES = ["faucet","forge","agent","chamber","explore","profile","world","market"]` — labels never derive from wallets, request ids or other unbounded values (`security-counters.ts` rule).
+2. **Persisted daily windows**: `cost-budgets.json` holds per-surface `{windowStart, spentUnits, alertLevel}` written through the locked `updateStoreWithReader`; the window rolls on `PHASE_COST_BUDGET_WINDOW_MS` (default 24h) at charge/evaluate time.
+3. **Budgets from env**: `PHASE_COST_BUDGET_<SURFACE>` (units) — unset/0 means unlimited (inert surface). Warning at 80% (`PHASE_COST_BUDGET_WARNING_RATIO`), halt at ≥100%. A process-local halt cache keeps `isSurfaceHalted()` disk-free on the hot path.
+4. **Transition-only alerts**: `evaluateSurfaceBudgets` fires `sendWebhookAlert` (warning/critical/info) only when a surface's `alertLevel` changes; the webhook module's own 15min dedup is the second layer. Recovery (`*→ok`) emits an info alert.
+5. **Kill-switch enforcement**: `forge-agent` and `agent/forge` refuse with `503 FORGE_SURFACE_HALTED` + `Retry-After: 300` before any spend; `chargeSurfaceCost` refuses further booking once halted and counts `budget_halt_refusal`. Hourly cron (`/api/cron/cost-budgets`, `validateCronAuth` pattern from faucet-health, registered in `vercel.json`) evaluates + alerts; `GET /api/cost-budgets/health` is the operator view (evaluation without alerts so a dashboard poll cannot spam webhooks).
+
+## Rollback
+
+Unset `NEXT_PUBLIC_FEATURE_PHASE_176` / `FEATURE_PHASE_176` or set to `0`. Charging is a no-op, `isSurfaceHalted` is always false, routes never refuse, cron reports disabled, and `cost-budgets.json` stays inert on disk. No migrations.
+
+## Known limitations
+
+- The halt cache is per-process: on serverless each instance relearns on its first charge/cron tick (budget overshoot up to one in-flight request per instance).
+- Cross-instance budget consistency needs a shared store (same json-store scope limit as every sidecar).
+- Charge wiring is minimal (forge-agent/agent-forge paths); faucet, explore and Horizon fan-out surfaces register as closed labels but need their own `chargeSurfaceCost` call sites.
diff --git a/docs/spikes/615-forge-billing-metering-findings.md b/docs/spikes/615-forge-billing-metering-findings.md
new file mode 100644
index 00000000..c2150618
--- /dev/null
+++ b/docs/spikes/615-forge-billing-metering-findings.md
@@ -0,0 +1,28 @@
+# Spike 615: Billing and Metering for Paid Forge Tiers with Quota Enforcement
+
+**Issue**: #478
+**Type**: Advanced Integration Spike
+**Feature Flag**: `phase-177` (`NEXT_PUBLIC_FEATURE_PHASE_177` / `FEATURE_PHASE_177`)
+**Key Surfaces**: `lib/forge/billing.ts`, `app/api/forge-agent/route.ts`, `app/api/agent/forge/route.ts`
+
+## Context & Motivation
+
+The forge charged a flat x402 fee with no per-wallet metering: nothing stopped a wallet from settling the fee in an unbounded number of jobs, there was no daily quota, and no usage record existed to reconcile against the cost ledger or the settlement idempotency store. The only quota-like code was error-message classification for AI-provider 429s.
+
+## Key Architectural Decisions
+
+1. **UTC-day metering with hashed wallets**: `forge-billing.json` stores per `sha256(wallet):YYYY-MM-DD` usage `{count, jobs}` written through the locked store; raw wallets never persist. Bounded at 5,000 wallet-days (oldest pruned) and 200 jobs per wallet-day.
+2. **Idempotent by jobId**: `recordForgeBillingEvent` dedups on `jobId` (settlement txHash for the agent path, generation-job id for the sync pipeline), so a serverless retry after timeout cannot double-count quota — mirroring `markSettlementUsedIfUnused` semantics.
+3. **Tier config, not code**: `PHASE_FORGE_BILLING_TIERS` JSON maps tier id → daily limit (defaults standard 5 … obsidian 100); invalid config fails safe to defaults so billing can never brick the forge. `resolveBillingTier` currently returns the deployment default (`PHASE_FORGE_BILLING_DEFAULT_TIER`); per-wallet stake upgrades via `getStakedFeeTier` are a documented follow-up.
+4. **Enforcement placement**: `agent/forge` checks quota *before* settle (an exhausted wallet never burns a real payment); `forge-agent` checks after settlement verification but before job creation (the settlement idempotency store still fences replays first). Refusal is `429 FORGE_QUOTA_EXCEEDED` + `Retry-After` (floor 60s, or seconds to the UTC-day reset) with tier/used/limit in the body.
+5. **Metering at acceptance**: both forge paths record the billing event after the job is accepted (sync pipeline and async NanoBanana), and book `chargeSurfaceCost("forge", 20)` against the spike-614 budget.
+
+## Rollback
+
+Unset `NEXT_PUBLIC_FEATURE_PHASE_177` / `FEATURE_PHASE_177` or set to `0`. `checkForgeQuota` always allows, `recordForgeBillingEvent` is a no-op, routes never 429 on quota, and `forge-billing.json` stays inert on disk. No migrations.
+
+## Known limitations
+
+- Quota is enforced per wallet, but the first forge-agent POST may lack `payerAddress` — enforcement then defers to the settle-verified payer (always present on the paid path).
+- Per-wallet stake-tier resolution and invoice/credit-note generation are follow-ups.
+- Metering covers accepted jobs only; failed-generation refunds are not booked (the settlement is already consumed by design).
diff --git a/lib/__tests__/cost-budgets.test.ts b/lib/__tests__/cost-budgets.test.ts
new file mode 100644
index 00000000..7cce5bbf
--- /dev/null
+++ b/lib/__tests__/cost-budgets.test.ts
@@ -0,0 +1,127 @@
+import { mkdtemp, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+vi.mock("@/lib/webhook-alerts", () => ({
+  sendWebhookAlert: vi.fn(async () => ({ sent: ["test"], failed: [] })),
+}))
+
+import {
+  chargeSurfaceCost,
+  evaluateSurfaceBudgets,
+  isSurfaceHalted,
+  resetCostBudgetCountersForTests,
+  snapshotCostBudgetCounters,
+  SurfaceHaltedError,
+  assertSurfaceOpen,
+} from "@/lib/cost-budgets"
+import { sendWebhookAlert } from "@/lib/webhook-alerts"
+
+describe("cost-budgets (spike 614 / phase-176)", () => {
+  let dataDir: string
+  const savedEnv: Record<string, string | undefined> = {}
+
+  beforeEach(async () => {
+    dataDir = await mkdtemp(path.join(os.tmpdir(), "phase-cost-budgets-"))
+    process.env.PHASE_SERVER_DATA_DIR = dataDir
+    for (const key of [
+      "FEATURE_PHASE_176",
+      "NEXT_PUBLIC_FEATURE_PHASE_176",
+      "PHASE_COST_BUDGET_FORGE",
+      "PHASE_COST_BUDGET_WINDOW_MS",
+      "PHASE_COST_BUDGET_WARNING_RATIO",
+    ]) {
+      savedEnv[key] = process.env[key]
+      delete process.env[key]
+    }
+    process.env.FEATURE_PHASE_176 = "1"
+    vi.mocked(sendWebhookAlert).mockClear()
+    resetCostBudgetCountersForTests()
+  })
+
+  afterEach(async () => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    resetCostBudgetCountersForTests()
+    await rm(dataDir, { recursive: true, force: true })
+  })
+
+  it("flag off makes charging inert and never halts", async () => {
+    delete process.env.FEATURE_PHASE_176
+    delete process.env.NEXT_PUBLIC_FEATURE_PHASE_176
+    process.env.PHASE_COST_BUDGET_FORGE = "10"
+    const result = await chargeSurfaceCost("forge", 100)
+    expect(result.ok).toBe(true)
+    expect(result.reason).toBe("flag_disabled")
+    expect(isSurfaceHalted("forge")).toBe(false)
+    const evaluation = await evaluateSurfaceBudgets()
+    expect(evaluation.enabled).toBe(false)
+  })
+
+  it("charges accumulate and halt at budget with alert", async () => {
+    process.env.PHASE_COST_BUDGET_FORGE = "30"
+    await chargeSurfaceCost("forge", 10, { now: 1_000 })
+    const warn = await chargeSurfaceCost("forge", 14, { now: 2_000 }) // 24/30 = 80% → warning
+    expect(warn.status).toBe("warning")
+    const halt = await chargeSurfaceCost("forge", 6, { now: 3_000 }) // 30/30 → halted
+    expect(halt.status).toBe("halted")
+    expect(halt.ok).toBe(false)
+    expect(isSurfaceHalted("forge")).toBe(true)
+    expect(() => assertSurfaceOpen("forge")).toThrowError(SurfaceHaltedError)
+
+    const evaluation = await evaluateSurfaceBudgets({ now: 3_500 })
+    expect(evaluation.halted).toContain("forge")
+    expect(vi.mocked(sendWebhookAlert).mock.calls.length).toBeGreaterThanOrEqual(1)
+    const critical = vi.mocked(sendWebhookAlert).mock.calls.find((c) => c[0] === "critical")
+    expect(critical).toBeTruthy()
+  })
+
+  it("refuses charges once halted and counts the refusal", async () => {
+    process.env.PHASE_COST_BUDGET_FORGE = "5"
+    await chargeSurfaceCost("forge", 5, { now: 1_000 })
+    const refused = await chargeSurfaceCost("forge", 1, { now: 2_000 })
+    expect(refused.ok).toBe(false)
+    expect(refused.reason).toBe("halted")
+    expect(snapshotCostBudgetCounters().budget_halt_refusal).toBe(1)
+  })
+
+  it("unbudgeted surfaces stay ok", async () => {
+    const result = await chargeSurfaceCost("explore", 10_000)
+    expect(result.status).toBe("ok")
+    expect(result.ok).toBe(true)
+    expect(isSurfaceHalted("explore")).toBe(false)
+  })
+
+  it("burns off a new window after windowMs", async () => {
+    process.env.PHASE_COST_BUDGET_FORGE = "10"
+    process.env.PHASE_COST_BUDGET_WINDOW_MS = "60000"
+    const start = 1_000_000
+    await chargeSurfaceCost("forge", 10, { now: start })
+    expect(isSurfaceHalted("forge")).toBe(true)
+    resetCostBudgetCountersForTests()
+    // Next charge after the window rolls: spent resets, surface un-halts.
+    const after = await chargeSurfaceCost("forge", 1, { now: start + 61_000 })
+    expect(after.ok).toBe(true)
+    expect(after.spentUnits).toBe(1)
+    expect(isSurfaceHalted("forge")).toBe(false)
+  })
+
+  it("alerts only on level transitions", async () => {
+    process.env.PHASE_COST_BUDGET_FORGE = "100"
+    process.env.PHASE_COST_BUDGET_WARNING_RATIO = "0.5"
+    await chargeSurfaceCost("forge", 60, { now: 1_000 })
+    const first = await evaluateSurfaceBudgets({ now: 2_000 })
+    expect(first.alerted).toContain("forge")
+    const second = await evaluateSurfaceBudgets({ now: 3_000 })
+    expect(second.alerted).not.toContain("forge")
+  })
+
+  it("rejects invalid surface/units", async () => {
+    const result = await chargeSurfaceCost("nope" as never, 5)
+    expect(result.ok).toBe(false)
+    expect(result.reason).toBe("invalid")
+  })
+})
diff --git a/lib/__tests__/experiments.test.ts b/lib/__tests__/experiments.test.ts
new file mode 100644
index 00000000..73cacbc6
--- /dev/null
+++ b/lib/__tests__/experiments.test.ts
@@ -0,0 +1,176 @@
+import { mkdtemp, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+  assignExperimentVariant,
+  EXPERIMENT_CONTROL_VARIANT_ID,
+  ExperimentError,
+  experimentBucket,
+  experimentSubjectKey,
+  FORGE_PRICE_EXPERIMENT_ID,
+  getExperimentSummary,
+  loadForgeExperimentConfig,
+  parseExperimentConfig,
+  resolveForgeExperimentCopyKey,
+  resolveForgeRequiredAmountStroops,
+} from "@/lib/experiments"
+import { REQUIRED_AMOUNT } from "@/lib/phase-protocol"
+
+const WALLET = "GAXGYD5H4J5XQQ0W6NXKJ6TRJZ4NXBTSNSGQ2MGE43LQX4KJQK5V5V5V"
+
+function config(overrides: Record<string, unknown> = {}) {
+  return {
+    experimentId: FORGE_PRICE_EXPERIMENT_ID,
+    enabled: true,
+    salt: "test-salt",
+    holdoutPercent: 0,
+    variants: [
+      { id: "control", weight: 1 },
+      { id: "price_cut", weight: 9999, priceStroops: "5000000", copyKey: "price_cut" },
+    ],
+    ...overrides,
+  }
+}
+
+describe("experiments (spike 612 / phase-174)", () => {
+  let dataDir: string
+  const savedEnv: Record<string, string | undefined> = {}
+
+  beforeEach(async () => {
+    dataDir = await mkdtemp(path.join(os.tmpdir(), "phase-experiments-"))
+    process.env.PHASE_SERVER_DATA_DIR = dataDir
+    for (const key of ["FEATURE_PHASE_174", "NEXT_PUBLIC_FEATURE_PHASE_174", "PHASE_EXPERIMENT_CONFIG", "PHASE_EXPERIMENT_SALT"]) {
+      savedEnv[key] = process.env[key]
+      delete process.env[key]
+    }
+    process.env.FEATURE_PHASE_174 = "1"
+  })
+
+  afterEach(async () => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    await rm(dataDir, { recursive: true, force: true })
+  })
+
+  it("deterministic bucket depends on salt, experiment and subject", () => {
+    const a = experimentBucket("s1", "exp", WALLET)
+    const b = experimentBucket("s1", "exp", WALLET)
+    const c = experimentBucket("s2", "exp", WALLET)
+    expect(a).toBe(b)
+    expect(a).toBeGreaterThanOrEqual(0)
+    expect(a).toBeLessThan(10_000)
+    expect(c).not.toBe(a)
+  })
+
+  it("subject keys are sha256 hex and never the raw wallet", () => {
+    const key = experimentSubjectKey(WALLET)
+    expect(key).toMatch(/^[a-f0-9]{64}$/)
+    expect(key).not.toContain(WALLET)
+  })
+
+  it("rejects invalid configs with VALIDATION_FAILED", () => {
+    expect(() => parseExperimentConfig({ experimentId: "x", variants: [] })).toThrowError(ExperimentError)
+  })
+
+  it("fails safe to control when no config is set", async () => {
+    const resolution = await resolveForgeRequiredAmountStroops(WALLET)
+    expect(resolution.amountStroops).toBe(REQUIRED_AMOUNT)
+    expect(resolution.variantId).toBe(EXPERIMENT_CONTROL_VARIANT_ID)
+  })
+
+  it("fails safe to control when PHASE_EXPERIMENT_CONFIG is garbage", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = "{not json"
+    expect(loadForgeExperimentConfig()).toBeNull()
+    const resolution = await resolveForgeRequiredAmountStroops(WALLET)
+    expect(resolution.amountStroops).toBe(REQUIRED_AMOUNT)
+  })
+
+  it("resolves the variant price for an assigned subject", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = JSON.stringify(config())
+    const bucket = experimentBucket("test-salt", FORGE_PRICE_EXPERIMENT_ID, WALLET)
+    const resolution = await resolveForgeRequiredAmountStroops(WALLET)
+    // Weight 1 vs 9999: only bucket 0 lands on control.
+    if (bucket === 0) {
+      expect(resolution.amountStroops).toBe(REQUIRED_AMOUNT)
+    } else {
+      expect(resolution.variantId).toBe("price_cut")
+      expect(resolution.amountStroops).toBe("5000000")
+    }
+  })
+
+  it("control variant resolves to REQUIRED_AMOUNT", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = JSON.stringify(
+      config({
+        variants: [
+          { id: "control", weight: 10_000 },
+          { id: "price_cut", weight: 1, priceStroops: "5000000" },
+        ],
+      }),
+    )
+    const resolution = await resolveForgeRequiredAmountStroops(WALLET)
+    expect(resolution.amountStroops).toBe(REQUIRED_AMOUNT)
+  })
+
+  it("holdout subjects get the control price", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = JSON.stringify(config({ holdoutPercent: 90 }))
+    // Find a subject whose bucket falls inside the holdout slice.
+    let holdoutSubject = ""
+    for (let i = 0; i < 200; i++) {
+      const candidate = `SESSION-${i}`
+      if (experimentBucket("test-salt", FORGE_PRICE_EXPERIMENT_ID, candidate) < 9000) {
+        holdoutSubject = candidate
+        break
+      }
+    }
+    expect(holdoutSubject).not.toBe("")
+    const resolution = await resolveForgeRequiredAmountStroops(holdoutSubject)
+    expect(resolution.holdout).toBe(true)
+    expect(resolution.amountStroops).toBe(REQUIRED_AMOUNT)
+  })
+
+  it("assignments are sticky across salt rotation and weight changes", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = JSON.stringify(config())
+    const first = await assignExperimentVariant(parseExperimentConfig(config()), WALLET)
+
+    process.env.PHASE_EXPERIMENT_SALT = "rotated-salt"
+    const rotated = config({
+      salt: "rotated-salt",
+      variants: [
+        { id: "control", weight: 10_000 },
+        { id: "price_cut", weight: 1, priceStroops: "5000000" },
+      ],
+    })
+    const second = await assignExperimentVariant(parseExperimentConfig(rotated), WALLET)
+    expect(second.variantId).toBe(first.variantId)
+    expect(second.sticky).toBe(true)
+  })
+
+  it("experiment summary counts variants without exposing subjects", async () => {
+    process.env.PHASE_EXPERIMENT_CONFIG = JSON.stringify(config())
+    await resolveForgeRequiredAmountStroops(WALLET)
+    await resolveForgeRequiredAmountStroops("GSECONDWALLETAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA2")
+    const summary = await getExperimentSummary(FORGE_PRICE_EXPERIMENT_ID)
+    expect(summary.totalAssignments).toBe(2)
+    const total = Object.values(summary.byVariant).reduce((a, b) => a + b, 0) + summary.holdout
+    expect(total).toBe(2)
+  })
+
+  it("flag off throws FLAG_DISABLED from assignExperimentVariant", async () => {
+    delete process.env.FEATURE_PHASE_174
+    delete process.env.NEXT_PUBLIC_FEATURE_PHASE_174
+    await expect(assignExperimentVariant(parseExperimentConfig(config()), WALLET)).rejects.toMatchObject({
+      name: "ExperimentError",
+      code: "FLAG_DISABLED",
+    })
+  })
+
+  it("copy key resolution returns control when flag off", async () => {
+    delete process.env.FEATURE_PHASE_174
+    delete process.env.NEXT_PUBLIC_FEATURE_PHASE_174
+    const key = await resolveForgeExperimentCopyKey(WALLET)
+    expect(key).toBe(EXPERIMENT_CONTROL_VARIANT_ID)
+  })
+})
diff --git a/lib/__tests__/forge-billing.test.ts b/lib/__tests__/forge-billing.test.ts
new file mode 100644
index 00000000..188ab497
--- /dev/null
+++ b/lib/__tests__/forge-billing.test.ts
@@ -0,0 +1,130 @@
+import { createHash } from "node:crypto"
+import { mkdtemp, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { Keypair } from "@stellar/stellar-sdk"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+  checkForgeQuota,
+  forgeBillingRetryAfterSeconds,
+  FORGE_BILLING_TIER_IDS,
+  forgeBillingTierLimits,
+  getForgeBillingUsage,
+  recordForgeBillingEvent,
+  resolveBillingTier,
+  walletBillingHash,
+} from "@/lib/forge/billing"
+
+const WALLET = Keypair.fromRawEd25519Seed(
+  createHash("sha256").update("phase-test-forge-billing").digest(),
+).publicKey()
+const NOW = Date.UTC(2026, 9, 19, 12, 0, 0)
+
+describe("forge billing (spike 615 / phase-177)", () => {
+  let dataDir: string
+  const savedEnv: Record<string, string | undefined> = {}
+
+  beforeEach(async () => {
+    dataDir = await mkdtemp(path.join(os.tmpdir(), "phase-forge-billing-"))
+    process.env.PHASE_SERVER_DATA_DIR = dataDir
+    for (const key of [
+      "FEATURE_PHASE_177",
+      "NEXT_PUBLIC_FEATURE_PHASE_177",
+      "PHASE_FORGE_BILLING_TIERS",
+      "PHASE_FORGE_BILLING_DEFAULT_TIER",
+    ]) {
+      savedEnv[key] = process.env[key]
+      delete process.env[key]
+    }
+    process.env.FEATURE_PHASE_177 = "1"
+  })
+
+  afterEach(async () => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    await rm(dataDir, { recursive: true, force: true })
+  })
+
+  it("wallet billing hash is sha256 hex, never the raw wallet", () => {
+    const hash = walletBillingHash(WALLET)
+    expect(hash).toMatch(/^[a-f0-9]{64}$/)
+    expect(hash).not.toContain(WALLET)
+  })
+
+  it("tier limits read from env with safe defaults", () => {
+    const defaults = forgeBillingTierLimits()
+    expect(defaults.standard).toBe(5)
+    process.env.PHASE_FORGE_BILLING_TIERS = JSON.stringify({ standard: 2, bogus: 99 })
+    const overridden = forgeBillingTierLimits()
+    expect(overridden.standard).toBe(2)
+    process.env.PHASE_FORGE_BILLING_TIERS = "{broken"
+    expect(forgeBillingTierLimits().standard).toBe(5)
+  })
+
+  it("resolveBillingTier defaults to standard", () => {
+    expect(resolveBillingTier(WALLET)).toBe("standard")
+    process.env.PHASE_FORGE_BILLING_DEFAULT_TIER = "gold"
+    expect(resolveBillingTier(WALLET)).toBe("gold")
+    process.env.PHASE_FORGE_BILLING_DEFAULT_TIER = "nope"
+    expect(resolveBillingTier(WALLET)).toBe("standard")
+  })
+
+  it("allows until the daily limit is exhausted, then 429 semantics", async () => {
+    process.env.PHASE_FORGE_BILLING_TIERS = JSON.stringify({ standard: 2 })
+    for (let i = 0; i < 2; i++) {
+      const result = await recordForgeBillingEvent(
+        { wallet: WALLET, jobId: `job-${i}`, settlementTxHash: `tx-${i}` },
+        { now: NOW },
+      )
+      expect(result.recorded).toBe(true)
+    }
+    const quota = await checkForgeQuota(WALLET, { now: NOW })
+    expect(quota.allowed).toBe(false)
+    expect(quota.used).toBe(2)
+    expect(quota.limit).toBe(2)
+    expect(quota.remaining).toBe(0)
+    expect(forgeBillingRetryAfterSeconds(quota)).toBeGreaterThanOrEqual(60)
+  })
+
+  it("is idempotent by jobId (serverless retry safe)", async () => {
+    const first = await recordForgeBillingEvent({ wallet: WALLET, jobId: "job-1" }, { now: NOW })
+    const second = await recordForgeBillingEvent({ wallet: WALLET, jobId: "job-1" }, { now: NOW })
+    expect(first.recorded).toBe(true)
+    expect(second.duplicate).toBe(true)
+    expect(second.recorded).toBe(false)
+    const usage = await getForgeBillingUsage(WALLET, { now: NOW })
+    expect(usage.count).toBe(1)
+  })
+
+  it("flag off always allows and records nothing", async () => {
+    delete process.env.FEATURE_PHASE_177
+    delete process.env.NEXT_PUBLIC_FEATURE_PHASE_177
+    process.env.PHASE_FORGE_BILLING_TIERS = JSON.stringify({ standard: 1 })
+    await recordForgeBillingEvent({ wallet: WALLET, jobId: "job-1" }, { now: NOW })
+    const quota = await checkForgeQuota(WALLET, { now: NOW })
+    expect(quota.allowed).toBe(true)
+    expect(quota.used).toBe(0)
+  })
+
+  it("rejects malformed events", async () => {
+    await expect(recordForgeBillingEvent({ wallet: "not-a-wallet", jobId: "" })).rejects.toMatchObject({
+      name: "ForgeBillingError",
+      code: "VALIDATION_FAILED",
+    })
+  })
+
+  it("resets at the next UTC day", async () => {
+    process.env.PHASE_FORGE_BILLING_TIERS = JSON.stringify({ standard: 1 })
+    await recordForgeBillingEvent({ wallet: WALLET, jobId: "job-1" }, { now: NOW })
+    const nextDay = NOW + 24 * 60 * 60 * 1000
+    const quota = await checkForgeQuota(WALLET, { now: nextDay })
+    expect(quota.allowed).toBe(true)
+    expect(quota.used).toBe(0)
+  })
+
+  it("tier ids stay a closed set", () => {
+    expect([...FORGE_BILLING_TIER_IDS]).toEqual(["standard", "bronze", "silver", "gold", "obsidian"])
+  })
+})
diff --git a/lib/__tests__/search-query-log.test.ts b/lib/__tests__/search-query-log.test.ts
new file mode 100644
index 00000000..05fbcd7e
--- /dev/null
+++ b/lib/__tests__/search-query-log.test.ts
@@ -0,0 +1,122 @@
+import { mkdtemp, rm } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import {
+  computeSearchReport,
+  recordSearchClick,
+  recordSearchQuery,
+  resetSearchCountersForTests,
+  searchQueryHash,
+  searchRefHash,
+  snapshotSearchCounters,
+  type SearchEvent,
+} from "@/lib/search-query-log"
+
+function queryEvent(over: Partial<SearchEvent> = {}): SearchEvent {
+  return {
+    surface: "world",
+    kind: "query",
+    query_hash: searchQueryHash("dragon citadel"),
+    result_count: 3,
+    ts: 1_000,
+    ...over,
+  }
+}
+
+describe("search-query-log (spike 613 / phase-175)", () => {
+  let dataDir: string
+  const savedEnv: Record<string, string | undefined> = {}
+
+  beforeEach(async () => {
+    dataDir = await mkdtemp(path.join(os.tmpdir(), "phase-search-log-"))
+    process.env.PHASE_SERVER_DATA_DIR = dataDir
+    for (const key of ["FEATURE_PHASE_175", "NEXT_PUBLIC_FEATURE_PHASE_175"]) {
+      savedEnv[key] = process.env[key]
+      delete process.env[key]
+    }
+    process.env.FEATURE_PHASE_175 = "1"
+    resetSearchCountersForTests()
+  })
+
+  afterEach(async () => {
+    for (const [key, value] of Object.entries(savedEnv)) {
+      if (value === undefined) delete process.env[key]
+      else process.env[key] = value
+    }
+    resetSearchCountersForTests()
+    await rm(dataDir, { recursive: true, force: true })
+  })
+
+  it("query and ref hashes are sha256 hex, never the raw text", () => {
+    const q = searchQueryHash("Dragon Citadel")
+    expect(q).toMatch(/^[a-f0-9]{64}$/)
+    expect(q).not.toContain("Dragon")
+    expect(searchQueryHash("Dragon Citadel")).toBe(searchQueryHash("  dragon citadel "))
+    expect(searchRefHash("GABC")).toMatch(/^[a-f0-9]{64}$/)
+  })
+
+  it("records queries and increments closed counters", async () => {
+    const event = await recordSearchQuery(queryEvent({ result_count: 0 }), { now: 1_000 })
+    expect(event?.result_count).toBe(0)
+    const counters = snapshotSearchCounters()
+    expect(counters.search_query_total).toBe(1)
+    expect(counters.search_zero_result).toBe(1)
+  })
+
+  it("records clicks with the click counter", async () => {
+    const event = await recordSearchClick(
+      { surface: "profile", query: "ganiyat", resultRef: "GABC", sessionId: "s1" },
+      { now: 2_000 },
+    )
+    expect(event?.kind).toBe("click")
+    expect(snapshotSearchCounters().search_click).toBe(1)
+  })
+
+  it("dedupes an identical event within a minute", async () => {
+    await recordSearchQuery(queryEvent({ session_id: "s1" }), { now: 1_000 })
+    const dup = await recordSearchQuery(queryEvent({ session_id: "s1" }), { now: 2_000 })
+    expect(dup).toBeNull()
+    expect(snapshotSearchCounters().search_query_total).toBe(1)
+  })
+
+  it("flag off is a silent no-op", async () => {
+    delete process.env.FEATURE_PHASE_175
+    delete process.env.NEXT_PUBLIC_FEATURE_PHASE_175
+    expect(await recordSearchQuery(queryEvent())).toBeNull()
+    expect(await recordSearchClick({ surface: "world", query: "x" })).toBeNull()
+  })
+
+  it("rejects malformed events with VALIDATION_FAILED", async () => {
+    await expect(recordSearchQuery({ surface: "nope", query_hash: "zz" })).rejects.toMatchObject({
+      name: "SearchQueryLogError",
+      code: "VALIDATION_FAILED",
+    })
+  })
+
+  it("aggregates zero-result rate, clickthrough and typo success", () => {
+    const events: SearchEvent[] = [
+      queryEvent({ result_count: 0, session_id: "a", ts: 1_000 }),
+      queryEvent({ result_count: 2, session_id: "b", ts: 2_000 }),
+      queryEvent({ result_count: 0, session_id: "c", corrected_from_hash: searchQueryHash("dragin"), ts: 3_000 }),
+      queryEvent({ result_count: 5, session_id: "c", corrected_from_hash: searchQueryHash("dragin"), ts: 4_000 }),
+      { ...queryEvent({ kind: "click", session_id: "b", ts: 5_000 }) },
+    ]
+    const report = computeSearchReport(events, { windowMs: 60_000, now: 10_000 })
+    const world = report.surfaces.find((s) => s.surface === "world")!
+    expect(world.queries).toBe(4)
+    expect(world.zeroResultQueries).toBe(2)
+    expect(world.zeroResultRate).toBeCloseTo(0.5)
+    expect(world.clicks).toBe(1)
+    expect(world.clickthroughRate).toBeCloseTo(0.25)
+    expect(world.correctedQueries).toBe(2)
+    expect(world.typoSuccessRate).toBeCloseTo(0.5)
+  })
+
+  it("windows the report", () => {
+    const old: SearchEvent[] = [queryEvent({ ts: 1_000 })]
+    const recent: SearchEvent[] = [queryEvent({ ts: 90_000 })]
+    const report = computeSearchReport([...old, ...recent], { windowMs: 10_000, now: 100_000 })
+    expect(report.totalQueries).toBe(1)
+  })
+})
diff --git a/lib/cost-budgets.ts b/lib/cost-budgets.ts
new file mode 100644
index 00000000..aea392be
--- /dev/null
+++ b/lib/cost-budgets.ts
@@ -0,0 +1,308 @@
+import { z } from "zod"
+import { flagRollbackNote, isFeatureEnabled } from "@/lib/feature-flags"
+import { updateStoreWithReader } from "@/lib/json-store"
+import { sendWebhookAlert } from "@/lib/webhook-alerts"
+
+// ── Spike 614 (phase-176): cost accounting per surface with budgets, burn-rate
+// alerts and kill-switches ──
+//
+// Infra spend was attributed (phase-138 in-memory units, cost-attribution
+// ledger estimates) but never bounded: nothing stopped a runaway surface from
+// burning budget unattended, and there was no per-surface kill-switch on the
+// server side (only the contract mainnet kill-switch exists). This module books
+// cost units per closed surface into a persisted daily window, evaluates
+// budgets with warning/critical thresholds, fires deduped webhook alerts on
+// level transitions, and halts a surface when it exceeds budget so routes can
+// refuse with 503 + Retry-After.
+//
+// Feature flag: phase-176 (NEXT_PUBLIC_FEATURE_PHASE_176 / FEATURE_PHASE_176)
+// Rollback: unset the flag → chargeSurfaceCost is a no-op, isSurfaceHalted
+//           always false, evaluate reports disabled; cost-budgets.json stays
+//           inert on disk. No migration to undo.
+//
+// Closed labels only: surfaces and statuses come from as-const sets — never a
+// wallet, request id or other unbounded value (see lib/security-counters.ts).
+
+export function isCostBudgetsEnabled(): boolean {
+  return isFeatureEnabled("phase-176")
+}
+
+export function costBudgetsRollbackNote(): string {
+  return flagRollbackNote("phase-176")
+}
+
+export const COST_SURFACES = [
+  "faucet",
+  "forge",
+  "agent",
+  "chamber",
+  "explore",
+  "profile",
+  "world",
+  "market",
+] as const
+export type CostSurface = (typeof COST_SURFACES)[number]
+
+export const BUDGET_STATUSES = ["ok", "warning", "critical", "halted"] as const
+export type BudgetStatus = (typeof BUDGET_STATUSES)[number]
+
+const SurfaceSchema = z.enum(COST_SURFACES)
+
+const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000
+
+/** Budget per surface in cost units; unset/0 → unlimited (inert surface). */
+export function surfaceBudgetUnits(surface: CostSurface): number {
+  const raw = process.env[`PHASE_COST_BUDGET_${surface.toUpperCase()}`]?.trim()
+  const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0
+}
+
+function budgetWindowMs(): number {
+  const parsed = Number.parseInt(process.env.PHASE_COST_BUDGET_WINDOW_MS ?? "", 10)
+  return Number.isFinite(parsed) && parsed >= 60_000 ? parsed : DEFAULT_WINDOW_MS
+}
+
+function warningRatio(): number {
+  const parsed = Number.parseFloat(process.env.PHASE_COST_BUDGET_WARNING_RATIO ?? "")
+  return Number.isFinite(parsed) && parsed > 0 && parsed < 1 ? parsed : 0.8
+}
+
+type SurfaceWindow = {
+  windowStart: number
+  spentUnits: number
+  /** Last emitted alert level; drives transition-only alerting. */
+  alertLevel: BudgetStatus
+  updatedAt: number
+}
+
+type CostBudgetsStore = {
+  version: number
+  windows: Partial<Record<CostSurface, SurfaceWindow>>
+}
+
+function emptyStore(): CostBudgetsStore {
+  return { version: 1, windows: {} }
+}
+
+function normalizeStore(raw: unknown): CostBudgetsStore {
+  const s = raw as CostBudgetsStore | undefined
+  if (!s || typeof s !== "object" || !s.windows || typeof s.windows !== "object") return emptyStore()
+  return { version: typeof s.version === "number" && s.version > 0 ? s.version : 1, windows: s.windows }
+}
+
+// Process-local halt cache: routes check isSurfaceHalted() on the hot path and
+// must not hit disk per request. chargeSurfaceCost / evaluateSurfaceBudgets
+// refresh it under the file lock; a cold process re-learns on first charge or
+// cron evaluation.
+const haltedCache = new Set<CostSurface>()
+
+export function isSurfaceHalted(surface: CostSurface): boolean {
+  return isCostBudgetsEnabled() && haltedCache.has(surface)
+}
+
+export class SurfaceHaltedError extends Error {
+  code: "SURFACE_HALTED"
+  surface: CostSurface
+  constructor(surface: CostSurface) {
+    super(`Cost budget exceeded for surface "${surface}"`)
+    this.name = "SurfaceHaltedError"
+    this.code = "SURFACE_HALTED"
+    this.surface = surface
+  }
+}
+
+export function assertSurfaceOpen(surface: CostSurface): void {
+  if (isSurfaceHalted(surface)) throw new SurfaceHaltedError(surface)
+}
+
+// Closed counter names — no wallet/token/request cardinality.
+const counters = new Map<string, number>()
+
+export function snapshotCostBudgetCounters(): Record<string, number> {
+  return Object.fromEntries(counters)
+}
+
+export function resetCostBudgetCountersForTests(): void {
+  counters.clear()
+  haltedCache.clear()
+}
+
+function bump(name: "budget_charge_total" | "budget_halt_refusal" | "budget_alert_sent" | "budget_window_rolled", by = 1): void {
+  counters.set(name, (counters.get(name) ?? 0) + by)
+}
+
+function levelFor(spent: number, budget: number): BudgetStatus {
+  if (budget <= 0) return "ok"
+  if (spent >= budget) return "halted"
+  if (spent >= budget * warningRatio()) return "warning"
+  return "ok"
+}
+
+function rollIfNeeded(win: SurfaceWindow, now: number): SurfaceWindow {
+  if (now - win.windowStart < budgetWindowMs()) return win
+  return { windowStart: now, spentUnits: 0, alertLevel: "ok", updatedAt: now }
+}
+
+export type SurfaceChargeResult = {
+  ok: boolean
+  surface: CostSurface
+  spentUnits: number
+  budgetUnits: number
+  status: BudgetStatus
+  reason?: "flag_disabled" | "halted" | "invalid"
+}
+
+/**
+ * Books cost units against a surface's daily window. No-op (ok, flag_disabled)
+ * when the flag is off. Refuses (ok=false, halted) when the surface is already
+ * halted so expensive work stops before it starts.
+ */
+export async function chargeSurfaceCost(
+  surface: CostSurface,
+  units: number,
+  opts: { requestId?: string; now?: number } = {},
+): Promise<SurfaceChargeResult> {
+  const parsedSurface = SurfaceSchema.safeParse(surface)
+  const parsedUnits = Number.isFinite(units) && units >= 0
+  const budget = parsedSurface.success ? surfaceBudgetUnits(parsedSurface.data) : 0
+  if (!parsedSurface.success || !parsedUnits) {
+    return { ok: false, surface: (parsedSurface.success ? surface : "forge"), spentUnits: 0, budgetUnits: budget, status: "ok", reason: "invalid" }
+  }
+  if (!isCostBudgetsEnabled()) {
+    return { ok: true, surface, spentUnits: 0, budgetUnits: budget, status: "ok", reason: "flag_disabled" }
+  }
+  if (haltedCache.has(surface)) {
+    bump("budget_halt_refusal")
+    return { ok: false, surface, spentUnits: 0, budgetUnits: budget, status: "halted", reason: "halted" }
+  }
+
+  const now = opts.now ?? Date.now()
+  const result = await updateStoreWithReader<CostBudgetsStore, SurfaceChargeResult>(
+    "costBudgets",
+    normalizeStore,
+    (store) => {
+      let win = store.windows[surface] ?? { windowStart: now, spentUnits: 0, alertLevel: "ok", updatedAt: now }
+      if (now - win.windowStart >= budgetWindowMs()) {
+        bump("budget_window_rolled")
+        win = { windowStart: now, spentUnits: 0, alertLevel: "ok", updatedAt: now }
+      }
+      win.spentUnits += units
+      win.updatedAt = now
+      const status = levelFor(win.spentUnits, budget)
+      store.windows[surface] = win
+      store.version += 1
+      if (status === "halted") haltedCache.add(surface)
+      bump("budget_charge_total")
+      return { ok: status !== "halted", surface, spentUnits: win.spentUnits, budgetUnits: budget, status }
+    },
+  )
+  return result
+}
+
+export type SurfaceBudgetReport = {
+  surface: CostSurface
+  budgetUnits: number
+  spentUnits: number
+  remainingUnits: number
+  burnPerHour: number
+  status: BudgetStatus
+  windowStart: number
+}
+
+export type BudgetEvaluation = {
+  enabled: boolean
+  windowMs: number
+  surfaces: SurfaceBudgetReport[]
+  halted: CostSurface[]
+  alerted: CostSurface[]
+}
+
+async function fireAlert(surface: CostSurface, report: SurfaceBudgetReport): Promise<void> {
+  const type = report.status === "halted" ? "critical" : report.status === "warning" ? "warning" : "info"
+  try {
+    await sendWebhookAlert(type, {
+      title:
+        report.status === "halted"
+          ? `🔴 Cost budget halted: ${surface}`
+          : report.status === "warning"
+            ? `🟠 Cost budget warning: ${surface}`
+            : `✅ Cost budget recovered: ${surface}`,
+      message: `Surface ${surface}: ${report.spentUnits}/${report.budgetUnits} units this window (burn ${report.burnPerHour.toFixed(1)}/h).`,
+      surface,
+      spentUnits: report.spentUnits,
+      budgetUnits: report.budgetUnits,
+      burnPerHour: Number(report.burnPerHour.toFixed(2)),
+      status: report.status,
+    })
+    bump("budget_alert_sent")
+  } catch {
+    // Alerting must never fail the evaluation path.
+  }
+}
+
+/**
+ * Evaluates every surface budget, refreshes the halt cache, and fires a
+ * webhook alert on alert-level transitions only (ok→warning, warning→halted,
+ * *→ok recovery). Called from the cost-budgets cron.
+ */
+export async function evaluateSurfaceBudgets(
+  opts: { now?: number; sendAlerts?: boolean } = {},
+): Promise<BudgetEvaluation> {
+  if (!isCostBudgetsEnabled()) {
+    return { enabled: false, windowMs: budgetWindowMs(), surfaces: [], halted: [], alerted: [] }
+  }
+  const now = opts.now ?? Date.now()
+  const sendAlerts = opts.sendAlerts ?? true
+
+  const { reports, transitions } = await updateStoreWithReader<
+    CostBudgetsStore,
+    { reports: SurfaceBudgetReport[]; transitions: SurfaceBudgetReport[] }
+  >("costBudgets", normalizeStore, (store) => {
+    const reports: SurfaceBudgetReport[] = []
+    const transitions: SurfaceBudgetReport[] = []
+    for (const surface of COST_SURFACES) {
+      const budget = surfaceBudgetUnits(surface)
+      const rawWin = store.windows[surface]
+      const win = rawWin ? rollIfNeeded(rawWin, now) : { windowStart: now, spentUnits: 0, alertLevel: "ok" as BudgetStatus, updatedAt: now }
+      // Keep the live object in the store so alertLevel mutations persist.
+      store.windows[surface] = win
+      win.updatedAt = now
+      const status = levelFor(win.spentUnits, budget)
+      const elapsedH = Math.max(0.001, (now - win.windowStart) / 3_600_000)
+      const report: SurfaceBudgetReport = {
+        surface,
+        budgetUnits: budget,
+        spentUnits: win.spentUnits,
+        remainingUnits: budget > 0 ? Math.max(0, budget - win.spentUnits) : Number.MAX_SAFE_INTEGER,
+        burnPerHour: win.spentUnits / elapsedH,
+        status,
+        windowStart: win.windowStart,
+      }
+      reports.push(report)
+      if (status !== win.alertLevel) {
+        transitions.push(report)
+        win.alertLevel = status
+      }
+      if (status === "halted") haltedCache.add(surface)
+      else haltedCache.delete(surface)
+    }
+    store.version += 1
+    return { reports, transitions }
+  })
+
+  const alerted: CostSurface[] = []
+  if (sendAlerts) {
+    for (const report of transitions) {
+      await fireAlert(report.surface, report)
+      alerted.push(report.surface)
+    }
+  }
+
+  return {
+    enabled: true,
+    windowMs: budgetWindowMs(),
+    surfaces: reports,
+    halted: reports.filter((r) => r.status === "halted").map((r) => r.surface),
+    alerted,
+  }
+}
diff --git a/lib/experiments.ts b/lib/experiments.ts
new file mode 100644
index 00000000..bb212ddc
--- /dev/null
+++ b/lib/experiments.ts
@@ -0,0 +1,352 @@
+import { createHash } from "node:crypto"
+import { z } from "zod"
+import { flagRollbackNote, isFeatureEnabled } from "@/lib/feature-flags"
+import { readStore, updateStoreWithReader } from "@/lib/json-store"
+import { REQUIRED_AMOUNT } from "@/lib/phase-protocol"
+
+// ── Spike 612 (phase-174): A/B experimentation for forge/chamber copy + pricing ──
+//
+// Pricing and copy used to be code, not config: changing either meant editing
+// the 402 challenge builder, the on-chain verifier floor, the dead-letter
+// classifier and the i18n copy at the same time, with no way to measure the
+// change. This module assigns a subject (wallet or anonymous session) to a
+// weighted variant of an experiment deterministically, sticks that assignment
+// across salt rotation and config weight changes, and resolves the forge price
+// for the assigned variant. Copy variants are served through a public route so
+// client components never touch the sticky store.
+//
+// Feature flag: phase-174 (NEXT_PUBLIC_FEATURE_PHASE_174 / FEATURE_PHASE_174)
+// Rollback: unset the flag → every resolver returns the control value
+//           (REQUIRED_AMOUNT price, control copy); the assignment sidecar
+//           stays inert on disk. No migration to undo.
+//
+// Privacy: subjects are stored as sha256(subject) hex only — a raw wallet or
+// session id never reaches the sidecar.
+
+export function isExperimentationEnabled(): boolean {
+  return isFeatureEnabled("phase-174")
+}
+
+export function experimentRollbackNote(): string {
+  return flagRollbackNote("phase-174")
+}
+
+export const FORGE_PRICE_EXPERIMENT_ID = "forge_price_v1"
+export const EXPERIMENT_CONTROL_VARIANT_ID = "control"
+
+const EXPERIMENT_ID_REGEX = /^[a-z0-9][a-z0-9._-]{0,62}[a-z0-9]$/
+
+export const ExperimentVariantSchema = z.object({
+  id: z.string().trim().regex(EXPERIMENT_ID_REGEX, "variant id must be 2-64 chars, alphanumeric plus . _ -"),
+  weight: z.number().finite().gt(0).max(1_000_000),
+  /** Variant price in stroops; null/absent = control price (REQUIRED_AMOUNT). */
+  priceStroops: z.string().trim().regex(/^\d{1,19}$/).nullable().optional(),
+  /** Copy variant key consumed by pickForgeExperimentCopy; defaults to id. */
+  copyKey: z.string().trim().min(1).max(32).optional(),
+})
+
+export type ExperimentVariant = z.infer<typeof ExperimentVariantSchema>
+
+export const ExperimentConfigSchema = z
+  .object({
+    experimentId: z.string().trim().regex(EXPERIMENT_ID_REGEX),
+    enabled: z.boolean().default(true),
+    salt: z.string().trim().min(1).max(64).optional(),
+    holdoutPercent: z.number().finite().min(0).max(90).default(0),
+    variants: z.array(ExperimentVariantSchema).min(2).max(8),
+  })
+  .refine((cfg) => new Set(cfg.variants.map((v) => v.id)).size === cfg.variants.length, {
+    message: "Variant ids must be unique within an experiment",
+    path: ["variants"],
+  })
+
+export type ExperimentConfig = z.infer<typeof ExperimentConfigSchema>
+
+export class ExperimentError extends Error {
+  code: "FLAG_DISABLED" | "VALIDATION_FAILED" | "EXPERIMENT_DISABLED"
+  details?: unknown
+  constructor(code: ExperimentError["code"], message: string, details?: unknown) {
+    super(message)
+    this.name = "ExperimentError"
+    this.code = code
+    this.details = details
+  }
+}
+
+/** Subjects are hashed before storage; bucketing uses the raw subject string. */
+export function experimentSubjectKey(subject: string): string {
+  return createHash("sha256").update(subject.trim().toUpperCase(), "utf8").digest("hex")
+}
+
+/** Deterministic 0..9999 bucket for (salt, experimentId, subject) — FNV-1a, no PRNG state. */
+export function experimentBucket(salt: string, experimentId: string, subject: string): number {
+  const payload = `${salt}|${experimentId.trim().toLowerCase()}|${subject.trim().toUpperCase()}`
+  let h = 0x811c9dc5
+  for (let i = 0; i < payload.length; i++) {
+    h = Math.imul(h ^ payload.charCodeAt(i), 0x01000193)
+  }
+  return (h >>> 0) % 10_000
+}
+
+function defaultSalt(): string {
+  // Env override supports salt rotation without a deploy; sticky assignments
+  // in the sidecar keep existing subjects on their original variant.
+  return process.env.PHASE_EXPERIMENT_SALT?.trim() || "phase-exp-salt-v1"
+}
+
+/** Parses a raw experiment config; throws ExperimentError on bad input. */
+export function parseExperimentConfig(raw: unknown): ExperimentConfig {
+  const parsed = ExperimentConfigSchema.safeParse(raw)
+  if (!parsed.success) {
+    throw new ExperimentError("VALIDATION_FAILED", "Invalid experiment config", parsed.error.flatten())
+  }
+  return parsed.data
+}
+
+/**
+ * Loads the forge price experiment config from PHASE_EXPERIMENT_CONFIG (JSON).
+ * Returns null when unset, unparseable, or the requested experiment is absent —
+ * every caller fails safe to control.
+ */
+export function loadForgeExperimentConfig(): ExperimentConfig | null {
+  const raw = process.env.PHASE_EXPERIMENT_CONFIG?.trim()
+  if (!raw) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed]
+  for (const entry of list) {
+    const safe = ExperimentConfigSchema.safeParse(entry)
+    if (safe.success && safe.data.experimentId === FORGE_PRICE_EXPERIMENT_ID) return safe.data
+  }
+  return null
+}
+
+export type ExperimentAssignment = {
+  experimentId: string
+  subjectKey: string
+  bucket: number
+  holdout: boolean
+  variantId: string
+  copyKey: string
+  priceStroops: string | null
+  sticky: boolean
+}
+
+type StoredSubjectAssignment = {
+  bucket: number
+  holdout: boolean
+  variantId: string
+  copyKey: string
+  priceStroops: string | null
+  assignedAt: number
+}
+
+type ExperimentAssignmentsStore = {
+  version: number
+  experiments: Record<string, { salt: string; subjects: Record<string, StoredSubjectAssignment> }>
+}
+
+function emptyStore(): ExperimentAssignmentsStore {
+  return { version: 1, experiments: {} }
+}
+
+function normalizeStore(raw: unknown): ExperimentAssignmentsStore {
+  const s = raw as ExperimentAssignmentsStore | undefined
+  if (!s || typeof s !== "object" || !s.experiments || typeof s.experiments !== "object") return emptyStore()
+  return { version: typeof s.version === "number" && s.version > 0 ? s.version : 1, experiments: s.experiments }
+}
+
+function assignmentFromStored(experimentId: string, subjectKey: string, stored: StoredSubjectAssignment): ExperimentAssignment {
+  return {
+    experimentId,
+    subjectKey,
+    bucket: stored.bucket,
+    holdout: stored.holdout,
+    variantId: stored.variantId,
+    copyKey: stored.copyKey,
+    priceStroops: stored.priceStroops,
+    sticky: true,
+  }
+}
+
+function computeFreshAssignment(
+  config: ExperimentConfig,
+  salt: string,
+  subject: string,
+  subjectKey: string,
+): ExperimentAssignment {
+  const bucket = experimentBucket(salt, config.experimentId, subject)
+  const holdoutCutoff = Math.round(config.holdoutPercent * 100)
+  if (bucket < holdoutCutoff) {
+    return {
+      experimentId: config.experimentId,
+      subjectKey,
+      bucket,
+      holdout: true,
+      variantId: EXPERIMENT_CONTROL_VARIANT_ID,
+      copyKey: EXPERIMENT_CONTROL_VARIANT_ID,
+      priceStroops: null,
+      sticky: false,
+    }
+  }
+  const totalWeight = config.variants.reduce((sum, v) => sum + v.weight, 0)
+  const span = 10_000 - holdoutCutoff
+  const scaled = ((bucket - holdoutCutoff) / span) * totalWeight
+  let cursor = 0
+  let chosen: ExperimentVariant = config.variants[config.variants.length - 1]!
+  for (const variant of config.variants) {
+    cursor += variant.weight
+    if (scaled < cursor) {
+      chosen = variant
+      break
+    }
+  }
+  return {
+    experimentId: config.experimentId,
+    subjectKey,
+    bucket,
+    holdout: false,
+    variantId: chosen.id,
+    copyKey: chosen.copyKey ?? chosen.id,
+    priceStroops: chosen.priceStroops ?? null,
+    sticky: false,
+  }
+}
+
+/**
+ * Assigns a subject to a weighted variant (or holdout) of the experiment and
+ * persists the assignment so it stays sticky across salt rotation, weight
+ * changes and the anonymous→authed upgrade. Flag off → control, no store I/O.
+ */
+export async function assignExperimentVariant(
+  config: ExperimentConfig,
+  subject: string,
+  opts: { force?: boolean; now?: number } = {},
+): Promise<ExperimentAssignment> {
+  const cleanSubject = subject.trim()
+  if (!cleanSubject) {
+    throw new ExperimentError("VALIDATION_FAILED", "subject is required for variant assignment")
+  }
+  if (!opts.force && !isExperimentationEnabled()) {
+    throw new ExperimentError("FLAG_DISABLED", "Experimentation disabled (phase-174 flag off)", {
+      rollback: experimentRollbackNote(),
+    })
+  }
+  if (!config.enabled) {
+    throw new ExperimentError("EXPERIMENT_DISABLED", `Experiment "${config.experimentId}" is disabled`)
+  }
+  const subjectKey = experimentSubjectKey(cleanSubject)
+  const now = opts.now ?? Date.now()
+  const currentSalt = config.salt?.trim() || defaultSalt()
+
+  return updateStoreWithReader<ExperimentAssignmentsStore, ExperimentAssignment>(
+    "experimentAssignments",
+    normalizeStore,
+    (store) => {
+      const entry = store.experiments[config.experimentId] ?? { salt: currentSalt, subjects: {} }
+      const existing = entry.subjects[subjectKey]
+      if (existing) {
+        store.experiments[config.experimentId] = entry
+        store.version += 1
+        return assignmentFromStored(config.experimentId, subjectKey, existing)
+      }
+      const fresh = computeFreshAssignment(config, currentSalt, cleanSubject, subjectKey)
+      entry.salt = currentSalt
+      entry.subjects[subjectKey] = {
+        bucket: fresh.bucket,
+        holdout: fresh.holdout,
+        variantId: fresh.variantId,
+        copyKey: fresh.copyKey,
+        priceStroops: fresh.priceStroops,
+        assignedAt: now,
+      }
+      store.experiments[config.experimentId] = entry
+      store.version += 1
+      return fresh
+    },
+  )
+}
+
+/** Per-variant assignment counts for a persisted experiment — no subject data. */
+export async function getExperimentSummary(experimentId: string): Promise<{
+  experimentId: string
+  totalAssignments: number
+  byVariant: Record<string, number>
+  holdout: number
+}> {
+  const store = await readStore<ExperimentAssignmentsStore>("experimentAssignments", emptyStore)
+  const normalized = normalizeStore(store)
+  const entry = normalized.experiments[experimentId]
+  const byVariant: Record<string, number> = {}
+  let holdout = 0
+  let totalAssignments = 0
+  if (entry) {
+    for (const subject of Object.values(entry.subjects)) {
+      totalAssignments += 1
+      if (subject.holdout) holdout += 1
+      else byVariant[subject.variantId] = (byVariant[subject.variantId] ?? 0) + 1
+    }
+  }
+  return { experimentId, totalAssignments, byVariant, holdout }
+}
+
+export type ForgePriceResolution = {
+  experimentId: string
+  variantId: string
+  amountStroops: string
+  holdout: boolean
+}
+
+/**
+ * Resolves the forge price for a subject. Flag off, no config, no subject,
+ * holdout, or control variant → REQUIRED_AMOUNT. Everything else fails safe to
+ * control on any error path: a pricing experiment must never make the forge
+ * unpayable or accidentally free.
+ */
+export async function resolveForgeRequiredAmountStroops(subject?: string): Promise<ForgePriceResolution> {
+  const control = (): ForgePriceResolution => ({
+    experimentId: FORGE_PRICE_EXPERIMENT_ID,
+    variantId: EXPERIMENT_CONTROL_VARIANT_ID,
+    amountStroops: REQUIRED_AMOUNT,
+    holdout: false,
+  })
+  if (!isExperimentationEnabled()) return control()
+  const config = loadForgeExperimentConfig()
+  if (!config || !config.enabled) return control()
+  const cleanSubject = subject?.trim()
+  if (!cleanSubject) return control()
+  try {
+    const assignment = await assignExperimentVariant(config, cleanSubject)
+    if (assignment.holdout) return { ...control(), holdout: true }
+    if (assignment.variantId === EXPERIMENT_CONTROL_VARIANT_ID) return control()
+    const price = assignment.priceStroops
+    if (!price || !/^\d{1,19}$/.test(price) || BigInt(price) <= 0n) return control()
+    return {
+      experimentId: config.experimentId,
+      variantId: assignment.variantId,
+      amountStroops: price,
+      holdout: assignment.holdout,
+    }
+  } catch {
+    return control()
+  }
+}
+
+/** Copy variant id for a subject; control when flag off or unassigned. */
+export async function resolveForgeExperimentCopyKey(subject?: string): Promise<string> {
+  if (!isExperimentationEnabled()) return EXPERIMENT_CONTROL_VARIANT_ID
+  const config = loadForgeExperimentConfig()
+  if (!config || !config.enabled) return EXPERIMENT_CONTROL_VARIANT_ID
+  const cleanSubject = subject?.trim()
+  if (!cleanSubject) return EXPERIMENT_CONTROL_VARIANT_ID
+  try {
+    const assignment = await assignExperimentVariant(config, cleanSubject)
+    return assignment.holdout ? EXPERIMENT_CONTROL_VARIANT_ID : assignment.copyKey
+  } catch {
+    return EXPERIMENT_CONTROL_VARIANT_ID
+  }
+}
diff --git a/lib/feature-flags.ts b/lib/feature-flags.ts
index 7e26b07c..f0da992b 100644
--- a/lib/feature-flags.ts
+++ b/lib/feature-flags.ts
@@ -62,6 +62,14 @@
  * - phase-167: WalletConnect v2 mobile session resilience with reconnect and chain-switch (spike 623 / issue #486)
  * - phase-168: xBull full support with sign, trustline and Freighter-difference matrix (spike 624 / issue #487)
  * - phase-169: Ledger blind-signing to clear-signing review for Soroban transactions (spike 625 / issue #488)
+ * - phase-174: A/B experimentation framework for forge and chamber copy plus
+ *   pricing with sticky salted bucketing (spike 612 / issue #475)
+ * - phase-175: Search analytics — hashed query logs, zero-result rate,
+ *   clickthrough and typo effectiveness (spike 613 / issue #476)
+ * - phase-176: Cost accounting per surface with budgets, burn-rate alerts and
+ *   kill-switches (spike 614 / issue #477)
+ * - phase-177: Billing and metering for paid forge tiers with quota
+ *   enforcement (spike 615 / issue #478)
  */
 
 export type PhaseFeatureFlag =
@@ -137,7 +145,11 @@ export type PhaseFeatureFlag =
   | "phase-166"
   | "phase-167"
   | "phase-168"
-  | "phase-169";
+  | "phase-169"
+  | "phase-174"
+  | "phase-175"
+  | "phase-176"
+  | "phase-177";
 
 
 const FLAG_ENV_MAP: Record<PhaseFeatureFlag, string[]> = {
@@ -212,6 +224,10 @@ const FLAG_ENV_MAP: Record<PhaseFeatureFlag, string[]> = {
   "phase-167": ["NEXT_PUBLIC_FEATURE_PHASE_167", "FEATURE_PHASE_167"],
   "phase-168": ["NEXT_PUBLIC_FEATURE_PHASE_168", "FEATURE_PHASE_168"],
   "phase-169": ["NEXT_PUBLIC_FEATURE_PHASE_169", "FEATURE_PHASE_169"],
+  "phase-174": ["NEXT_PUBLIC_FEATURE_PHASE_174", "FEATURE_PHASE_174"],
+  "phase-175": ["NEXT_PUBLIC_FEATURE_PHASE_175", "FEATURE_PHASE_175"],
+  "phase-176": ["NEXT_PUBLIC_FEATURE_PHASE_176", "FEATURE_PHASE_176"],
+  "phase-177": ["NEXT_PUBLIC_FEATURE_PHASE_177", "FEATURE_PHASE_177"],
 };
 
 
@@ -319,6 +335,10 @@ export function getEnabledFeatureFlags(): PhaseFeatureFlag[] {
     "phase-167",
     "phase-168",
     "phase-169",
+    "phase-174",
+    "phase-175",
+    "phase-176",
+    "phase-177",
   ];
 
   // Filtering is evaluated at call time, allowing runtime test overrides.
diff --git a/lib/forge/billing.ts b/lib/forge/billing.ts
new file mode 100644
index 00000000..399619fb
--- /dev/null
+++ b/lib/forge/billing.ts
@@ -0,0 +1,251 @@
+import { createHash } from "node:crypto"
+import { z } from "zod"
+import { flagRollbackNote, isFeatureEnabled } from "@/lib/feature-flags"
+import { readStore, updateStoreWithReader } from "@/lib/json-store"
+
+// ── Spike 615 (phase-177): billing and metering for paid forge tiers ──
+//
+// The forge charged a flat x402 fee with no per-wallet metering: nothing
+// stopped a wallet from settling the same fee in an unbounded number of jobs,
+// and there was no usage record to reconcile against the cost ledger. This
+// module meters accepted forge jobs per wallet per UTC day (idempotent by
+// jobId) and enforces a daily quota with 429 + Retry-After. Tiers are config,
+// not code: PHASE_FORGE_BILLING_TIERS maps tier id → daily limit.
+//
+// Feature flag: phase-177 (NEXT_PUBLIC_FEATURE_PHASE_177 / FEATURE_PHASE_177)
+// Rollback: unset the flag → checkForgeQuota always allows, recordForgeBillingEvent
+//           is a no-op; forge-billing.json stays inert on disk. No migration.
+//
+// Privacy: wallets are stored as sha256(wallet) hex only.
+
+export function isForgeBillingEnabled(): boolean {
+  return isFeatureEnabled("phase-177")
+}
+
+export function forgeBillingRollbackNote(): string {
+  return flagRollbackNote("phase-177")
+}
+
+export const FORGE_BILLING_TIER_IDS = ["standard", "bronze", "silver", "gold", "obsidian"] as const
+export type ForgeBillingTierId = (typeof FORGE_BILLING_TIER_IDS)[number]
+
+const DEFAULT_DAILY_LIMITS: Record<ForgeBillingTierId, number> = {
+  standard: 5,
+  bronze: 10,
+  silver: 20,
+  gold: 40,
+  obsidian: 100,
+}
+
+/** Daily job limits per tier; overridable per env without a deploy. */
+export function forgeBillingTierLimits(): Record<ForgeBillingTierId, number> {
+  const limits = { ...DEFAULT_DAILY_LIMITS }
+  const raw = process.env.PHASE_FORGE_BILLING_TIERS?.trim()
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw) as Record<string, unknown>
+      for (const id of FORGE_BILLING_TIER_IDS) {
+        const v = parsed[id]
+        if (typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 10_000) limits[id] = v
+      }
+    } catch {
+      // Invalid config fails safe to defaults — billing must never brick the forge.
+    }
+  }
+  return limits
+}
+
+/**
+ * Tier for a wallet. Stake lookup (staked-forge-discounts) is intentionally
+ * not threaded here yet: this minimal core meters every wallet at the
+ * deployment default tier; per-wallet stake upgrades are a follow-up.
+ */
+export function resolveBillingTier(_wallet?: string): ForgeBillingTierId {
+  const raw = process.env.PHASE_FORGE_BILLING_DEFAULT_TIER?.trim().toLowerCase()
+  return (FORGE_BILLING_TIER_IDS as readonly string[]).includes(raw ?? "")
+    ? (raw as ForgeBillingTierId)
+    : "standard"
+}
+
+export const ForgeBillingEventSchema = z.object({
+  wallet: z.string().trim().regex(/^G[A-Z2-7]{55}$/, "valid ed25519 public key required"),
+  jobId: z.string().trim().min(1).max(128),
+  settlementTxHash: z.string().trim().max(128).optional(),
+  amountStroops: z.string().trim().regex(/^\d{1,19}$/).optional(),
+  tierId: z.enum(FORGE_BILLING_TIER_IDS).optional(),
+})
+
+export type ForgeBillingEvent = z.infer<typeof ForgeBillingEventSchema>
+
+export type ForgeQuota = {
+  allowed: boolean
+  tierId: ForgeBillingTierId
+  used: number
+  limit: number
+  remaining: number
+  /** Unix seconds (UTC) when the daily window resets. */
+  resetAt: number
+}
+
+export class ForgeBillingError extends Error {
+  code: "VALIDATION_FAILED"
+  details?: unknown
+  constructor(message: string, details?: unknown) {
+    super(message)
+    this.name = "ForgeBillingError"
+    this.code = "VALIDATION_FAILED"
+    this.details = details
+  }
+}
+
+type WalletDayUsage = {
+  count: number
+  /** jobId → settlement hash (dedup key; bounded). */
+  jobs: Record<string, string>
+  updatedAt: number
+}
+
+type ForgeBillingStore = {
+  version: number
+  /** Keyed by `<walletHash>:<YYYY-MM-DD>`. */
+  days: Record<string, WalletDayUsage>
+}
+
+const MAX_WALLET_DAYS = 5_000
+const MAX_JOBS_PER_WALLET_DAY = 200
+
+function emptyStore(): ForgeBillingStore {
+  return { version: 1, days: {} }
+}
+
+function normalizeStore(raw: unknown): ForgeBillingStore {
+  const s = raw as ForgeBillingStore | undefined
+  if (!s || typeof s !== "object" || !s.days || typeof s.days !== "object") return emptyStore()
+  return { version: typeof s.version === "number" && s.version > 0 ? s.version : 1, days: s.days }
+}
+
+export function walletBillingHash(wallet: string): string {
+  return createHash("sha256").update(wallet.trim().toUpperCase(), "utf8").digest("hex")
+}
+
+function utcDayKey(now: number): string {
+  return new Date(now).toISOString().slice(0, 10)
+}
+
+function utcDayResetSeconds(dayKey: string): number {
+  return Math.floor(Date.parse(`${dayKey}T00:00:00.000Z`) / 1000) + 86_400
+}
+
+function usageKey(walletHash: string, dayKey: string): string {
+  return `${walletHash}:${dayKey}`
+}
+
+/** Daily quota for a wallet. Flag off → always allowed (limit reported for UI). */
+export async function checkForgeQuota(wallet: string, opts: { now?: number } = {}): Promise<ForgeQuota> {
+  const cleanWallet = wallet.trim()
+  const tierId = resolveBillingTier(cleanWallet)
+  const limit = forgeBillingTierLimits()[tierId]
+  const now = opts.now ?? Date.now()
+  const dayKey = utcDayKey(now)
+  const control: ForgeQuota = {
+    allowed: true,
+    tierId,
+    used: 0,
+    limit,
+    remaining: limit,
+    resetAt: utcDayResetSeconds(dayKey),
+  }
+  if (!cleanWallet || !isForgeBillingEnabled()) return control
+
+  const store = normalizeStore(await readStore<ForgeBillingStore>("forgeBilling", emptyStore))
+  const usage = store.days[usageKey(walletBillingHash(cleanWallet), dayKey)]
+  const used = usage?.count ?? 0
+  return {
+    allowed: used < limit,
+    tierId,
+    used,
+    limit,
+    remaining: Math.max(0, limit - used),
+    resetAt: utcDayResetSeconds(dayKey),
+  }
+}
+
+/** Seconds a quota-refused caller should wait; floor of 60. */
+export function forgeBillingRetryAfterSeconds(quota: ForgeQuota): number {
+  const nowSec = Math.floor(Date.now() / 1000)
+  return Math.max(60, quota.resetAt - nowSec)
+}
+
+/**
+ * Records an accepted forge job against the wallet's daily usage. Idempotent
+ * by jobId: a retry after a serverless timeout returns duplicate=true without
+ * double-counting the quota. Flag off → no-op returning recorded=false.
+ */
+export async function recordForgeBillingEvent(
+  raw: unknown,
+  opts: { now?: number } = {},
+): Promise<{ recorded: boolean; duplicate: boolean; usage?: WalletDayUsage }> {
+  const parsed = ForgeBillingEventSchema.safeParse(raw)
+  if (!parsed.success) {
+    throw new ForgeBillingError("valid forge billing event required", parsed.error.flatten())
+  }
+  if (!isForgeBillingEnabled()) return { recorded: false, duplicate: false }
+
+  const event = parsed.data
+  const now = opts.now ?? Date.now()
+  const dayKey = utcDayKey(now)
+  const key = usageKey(walletBillingHash(event.wallet), dayKey)
+  const tierId = event.tierId ?? resolveBillingTier(event.wallet)
+
+  return updateStoreWithReader<ForgeBillingStore, { recorded: boolean; duplicate: boolean; usage?: WalletDayUsage }>(
+    "forgeBilling",
+    normalizeStore,
+    (store) => {
+      const usage = store.days[key] ?? { count: 0, jobs: {}, updatedAt: now }
+      if (Object.prototype.hasOwnProperty.call(usage.jobs, event.jobId)) {
+        store.version += 1
+        return { recorded: false, duplicate: true, usage }
+      }
+      if (Object.keys(usage.jobs).length >= MAX_JOBS_PER_WALLET_DAY) {
+        // Hard per-day bound: refuse to grow the map unboundedly; the quota
+        // limit is always far below this ceiling.
+        store.version += 1
+        return { recorded: false, duplicate: false, usage }
+      }
+      usage.jobs[event.jobId] = event.settlementTxHash ?? ""
+      usage.count += 1
+      usage.updatedAt = now
+      store.days[key] = usage
+      pruneOldDays(store, dayKey)
+      store.version += 1
+      return { recorded: true, duplicate: false, usage }
+    },
+  )
+}
+
+function pruneOldDays(store: ForgeBillingStore, currentDayKey: string): void {
+  const keys = Object.keys(store.days)
+  if (keys.length <= MAX_WALLET_DAYS) return
+  // Keep the current day; drop the oldest entries by updatedAt.
+  const sorted = keys
+    .filter((k) => !k.endsWith(`:${currentDayKey}`))
+    .sort((a, b) => (store.days[a]?.updatedAt ?? 0) - (store.days[b]?.updatedAt ?? 0))
+  const excess = keys.length - MAX_WALLET_DAYS
+  for (let i = 0; i < excess && i < sorted.length; i++) {
+    delete store.days[sorted[i]!]
+  }
+}
+
+/** Usage snapshot for a wallet-day (reporting; no raw wallet stored). */
+export async function getForgeBillingUsage(
+  wallet: string,
+  opts: { now?: number } = {},
+): Promise<{ tierId: ForgeBillingTierId; count: number; limit: number; jobs: string[] }> {
+  const now = opts.now ?? Date.now()
+  const dayKey = utcDayKey(now)
+  const tierId = resolveBillingTier(wallet)
+  const limit = forgeBillingTierLimits()[tierId]
+  const store = normalizeStore(await readStore<ForgeBillingStore>("forgeBilling", emptyStore))
+  const usage = store.days[usageKey(walletBillingHash(wallet), dayKey)]
+  return { tierId, count: usage?.count ?? 0, limit, jobs: usage ? Object.keys(usage.jobs) : [] }
+}
diff --git a/lib/forge/payment-verifier.ts b/lib/forge/payment-verifier.ts
index 74e92e80..1e492ae9 100644
--- a/lib/forge/payment-verifier.ts
+++ b/lib/forge/payment-verifier.ts
@@ -2,6 +2,7 @@ import { Address, extractBaseAddress, FeeBumpTransaction, rpc, scValToNative, Tr
 import { decodePaymentHeader, PaymentPayloadSchema, PaymentRequirementsSchema, useFacilitator, type PaymentRequirements } from "x402-stellar"
 import { getPhaseProtocolConfigFromChain, NETWORK_PASSPHRASE, phaseProtocolContractIdForServer, READONLY_SIM_SOURCE_G, REQUIRED_AMOUNT, RPC_URL, stroopsToLiqDisplay, PHASER_LIQ_SYMBOL, tokenContractIdForServer } from "@/lib/phase-protocol"
 import { logUnknownStellarError } from "@/lib/stellar"
+import { resolveForgeRequiredAmountStroops } from "@/lib/experiments"
 
 const PHASE_PROTOCOL_CONTRACT = phaseProtocolContractIdForServer()
 const PHASE_LIQ_TOKEN_CONTRACT = tokenContractIdForServer()
@@ -9,8 +10,19 @@ export const X402_NETWORK = "stellar:testnet"
 
 export type ForgePaymentResolution = "paid" | "missing" | "facilitator_rejected"
 
-export function forgePriceDisplay(): string {
-  return `${stroopsToLiqDisplay(REQUIRED_AMOUNT)} ${PHASER_LIQ_SYMBOL}`
+export function forgePriceDisplay(amountStroops: string = REQUIRED_AMOUNT): string {
+  return `${stroopsToLiqDisplay(amountStroops)} ${PHASER_LIQ_SYMBOL}`
+}
+
+/**
+ * Spike 612 (phase-174): resolve the price for a payer. Flag off / no
+ * experiment / control → REQUIRED_AMOUNT. Callers must treat the result as the
+ * single source of truth for challenge amount, header and verifier floor so a
+ * variant can never sell at A and verify at B.
+ */
+export async function resolveForgePaymentAmount(payerAddress?: string): Promise<string> {
+  const resolution = await resolveForgeRequiredAmountStroops(payerAddress)
+  return resolution.amountStroops
 }
 
 // ── helpers extracted from monolith ────────────────────────────────────────
@@ -57,8 +69,8 @@ export type LegacyChallenge = {
   invoice: string; resource: string; note: string
 }
 
-function parseRequiredAmountInt(): number {
-  const p = Number.parseInt(REQUIRED_AMOUNT, 10)
+function parseRequiredAmountInt(amountStroops: string = REQUIRED_AMOUNT): number {
+  const p = Number.parseInt(amountStroops, 10)
   return Number.isFinite(p) && p > 0 ? p : 0
 }
 
@@ -68,26 +80,26 @@ export function facilitatorUrlFromRequest(origin: string): string {
   return `${origin}/api/x402`
 }
 
-export function buildLegacyChallenge(origin: string, pathname: string): LegacyChallenge {
+export function buildLegacyChallenge(origin: string, pathname: string, amountStroops: string = REQUIRED_AMOUNT): LegacyChallenge {
   return {
     protocol: "x402", version: "2", network: X402_NETWORK,
     token: PHASE_LIQ_TOKEN_CONTRACT, contract_id: PHASE_PROTOCOL_CONTRACT,
-    token_contract: PHASE_LIQ_TOKEN_CONTRACT, amount: parseRequiredAmountInt(),
-    priceDisplay: forgePriceDisplay(), facilitator: facilitatorUrlFromRequest(origin),
+    token_contract: PHASE_LIQ_TOKEN_CONTRACT, amount: parseRequiredAmountInt(amountStroops),
+    priceDisplay: forgePriceDisplay(amountStroops), facilitator: facilitatorUrlFromRequest(origin),
     invoice: `forge_${Date.now()}`, resource: pathname,
     note: "Payment in PHASELQ via PHASE protocol `settle` on-chain, or x402 exact payment per paymentRequirements.",
   }
 }
 
-export function buildOfficialPaymentRequirements(origin: string): PaymentRequirements | null {
+export function buildOfficialPaymentRequirements(origin: string, amountStroops: string = REQUIRED_AMOUNT): PaymentRequirements | null {
   try {
     const resource = `${origin}/api/forge-agent`
     const payTo = process.env.X402_FORGE_PAY_TO?.trim() || READONLY_SIM_SOURCE_G
     return PaymentRequirementsSchema.parse({
-      scheme: "exact", network: "stellar-testnet", maxAmountRequired: REQUIRED_AMOUNT,
+      scheme: "exact", network: "stellar-testnet", maxAmountRequired: amountStroops,
       resource, description: "PHASELQ (Soroban) — pago x402 exact para el agente de forja.",
       mimeType: "application/json", payTo, maxTimeoutSeconds: 600, asset: PHASE_LIQ_TOKEN_CONTRACT,
-      extra: { phaserLiqContract: PHASE_LIQ_TOKEN_CONTRACT, phaseProtocolContract: PHASE_PROTOCOL_CONTRACT, requiredAmountStroops: REQUIRED_AMOUNT },
+      extra: { phaserLiqContract: PHASE_LIQ_TOKEN_CONTRACT, phaseProtocolContract: PHASE_PROTOCOL_CONTRACT, requiredAmountStroops: amountStroops },
     })
   } catch { return null }
 }
@@ -104,7 +116,7 @@ async function verifyOfficialX402(rawHeader: string, paymentRequirements: Paymen
 }
 
 // ── on-chain settle verification ────────────────────────────────────────────
-export async function verifyPhaseSettleTxOnChain(txHash: string, payerAddress: string): Promise<boolean> {
+export async function verifyPhaseSettleTxOnChain(txHash: string, payerAddress: string, requiredAmountStroops: string = REQUIRED_AMOUNT): Promise<boolean> {
   const payerComparable = comparableEd25519AccountG(payerAddress.trim())
   if (!payerComparable.startsWith("G") || payerComparable.length !== 56) return false
   const chainCfg = await getPhaseProtocolConfigFromChain()
@@ -133,7 +145,7 @@ export async function verifyPhaseSettleTxOnChain(txHash: string, payerAddress: s
     if (comparableEd25519AccountG(userG) !== payerComparable) continue
     let tokenC: string; try { tokenC = Address.fromScVal(args[1]).toString() } catch { continue }
     if (!allowedNorm.has(normalizeContractC(tokenC))) continue
-    const bi = sorobanAmountScValToBigInt(args[2]); if (bi === null || bi < BigInt(REQUIRED_AMOUNT)) continue
+    const bi = sorobanAmountScValToBigInt(args[2]); if (bi === null || bi < BigInt(requiredAmountStroops)) continue
     return true
   }
   return false
@@ -200,13 +212,17 @@ export async function verifyPaymentStep(input: VerifyPaymentStepInput): Promise<
   if (settlementTx) {
     if (!payer) payer = (await sorobanSuccessfulTxSourcePublicKey(settlementTx)) ?? ""
     if (payer) {
-      try { return (await verifyPhaseSettleTxOnChain(settlementTx, payer)) ? "paid" : "missing" }
+      // Spike 612: the verifier floor follows the payer's price variant so a
+      // variant-priced settlement verifies at the same price it was sold at.
+      const requiredAmount = await resolveForgePaymentAmount(payer)
+      try { return (await verifyPhaseSettleTxOnChain(settlementTx, payer, requiredAmount)) ? "paid" : "missing" }
       catch (e) { logUnknownStellarError("forge verifyPaymentStep (body settle)", e); return "missing" }
     }
   }
   const phaseFromAuth = tryPhaseProofFromAuthHeader(authHeader)
   if (phaseFromAuth) {
-    try { return (await verifyPhaseSettleTxOnChain(phaseFromAuth.settlementTxHash, phaseFromAuth.payerAddress)) ? "paid" : "missing" }
+    const requiredAmount = await resolveForgePaymentAmount(phaseFromAuth.payerAddress)
+    try { return (await verifyPhaseSettleTxOnChain(phaseFromAuth.settlementTxHash, phaseFromAuth.payerAddress, requiredAmount)) ? "paid" : "missing" }
     catch (e) { logUnknownStellarError("forge verifyPaymentStep (auth settle)", e); return "missing" }
   }
   if (!authHeader?.toLowerCase().startsWith("x402 ")) return "missing"
diff --git a/lib/phase-copy.ts b/lib/phase-copy.ts
index 1a097c3a..89a1f087 100644
--- a/lib/phase-copy.ts
+++ b/lib/phase-copy.ts
@@ -156,6 +156,19 @@ export type PricingCopy = {
   useSuggestion: string
 }
 
+/** phase-174 (spike 612): A/B experiment copy variants for the forge/chamber payment gate. */
+export type ForgeExperimentVariantCopy = {
+  label: string
+  /** `{amount}` = formatted variant price. */
+  paymentGateExplainer: string
+  paymentGateHint: string
+}
+
+export type ForgeExperimentCopy = {
+  /** Keyed by copyKey (variant id, or "control"). Unknown keys fall back to control. */
+  variants: Record<string, ForgeExperimentVariantCopy>
+}
+
 /** phase-146: moderation pre-screen. */
 export type ModerationQueueCopy = {
   heldNotice: string
@@ -734,6 +747,7 @@ export const phaseCopy: Record<
     pricing: PricingCopy
     moderationQueue: ModerationQueueCopy
     questArcs: QuestArcCopy
+    forgeExperiment: ForgeExperimentCopy
   }
 > = {
   en: {
@@ -1362,6 +1376,25 @@ export const phaseCopy: Record<
       manualEntry: "Or enter address manually",
       cameraError: "Camera access unavailable",
     },
+    forgeExperiment: {
+      variants: {
+        control: {
+          label: "Standard",
+          paymentGateExplainer: "Pay {amount} PHASELQ to the Forge Agent — your artifact is generated and minted on the Stellar ledger automatically.",
+          paymentGateHint: "One payment settles on-chain; your artifact is minted automatically.",
+        },
+        price_cut: {
+          label: "Launch price",
+          paymentGateExplainer: "Launch price: pay {amount} PHASELQ to the Forge Agent — same on-chain settlement, same automatic mint.",
+          paymentGateHint: "Launch pricing — one on-chain payment, artifact minted automatically.",
+        },
+        copy_urgent: {
+          label: "Limited",
+          paymentGateExplainer: "Secure your artifact for {amount} PHASELQ — settlement is on-chain and minting is automatic.",
+          paymentGateHint: "Limited window — pay once on-chain and the Forge mints your artifact automatically.",
+        },
+      },
+    },
     walletConnectResilience: {
       title: "WalletConnect v2 Resilience",
       reconnectPrompt: "WalletConnect session dropped. Click Reconnect to restore mobile link.",
@@ -2021,6 +2054,25 @@ export const phaseCopy: Record<
       manualEntry: "O ingresá la dirección manualmente",
       cameraError: "Acceso a cámara no disponible",
     },
+    forgeExperiment: {
+      variants: {
+        control: {
+          label: "Estándar",
+          paymentGateExplainer: "Pagá {amount} PHASELQ al Forge Agent — tu artefacto se genera y se mintea en el ledger de Stellar automáticamente.",
+          paymentGateHint: "Un pago se liquida on-chain; tu artefacto se mintea automáticamente.",
+        },
+        price_cut: {
+          label: "Precio de lanzamiento",
+          paymentGateExplainer: "Precio de lanzamiento: pagá {amount} PHASELQ al Forge Agent — misma liquidación on-chain, mismo mint automático.",
+          paymentGateHint: "Precio de lanzamiento — un pago on-chain y el Forge mintea tu artefacto automáticamente.",
+        },
+        copy_urgent: {
+          label: "Por tiempo limitado",
+          paymentGateExplainer: "Asegurá tu artefacto por {amount} PHASELQ — la liquidación es on-chain y el mint es automático.",
+          paymentGateHint: "Ventana limitada — pagá una vez on-chain y el Forge mintea tu artefacto automáticamente.",
+        },
+      },
+    },
     walletConnectResilience: {
       title: "Resiliencia WalletConnect v2",
       reconnectPrompt: "Sesión WalletConnect interrumpida. Hacé clic en Reconectar para restaurar el enlace móvil.",
@@ -2074,3 +2126,10 @@ export function fillCopy(template: string, vars: Record<string, string | number>
     Object.prototype.hasOwnProperty.call(vars, key) ? String(vars[key]) : match,
   )
 }
+
+/** phase-174 (spike 612): experiment copy variant for a language; unknown keys fall back to control. */
+export function pickForgeExperimentCopy(lang: unknown, copyKey: string): ForgeExperimentVariantCopy {
+  const registry = pickCopy(lang).forgeExperiment.variants
+  const key = copyKey.trim() || "control"
+  return registry[key] ?? registry.control!
+}
diff --git a/lib/search-query-log.ts b/lib/search-query-log.ts
new file mode 100644
index 00000000..cdd62abd
--- /dev/null
+++ b/lib/search-query-log.ts
@@ -0,0 +1,285 @@
+import { createHash } from "node:crypto"
+import { z } from "zod"
+import { flagRollbackNote, isFeatureEnabled } from "@/lib/feature-flags"
+import { readStore, updateStoreWithReader } from "@/lib/json-store"
+
+// ── Spike 613 (phase-175): search analytics — query logs, zero-result rate,
+// clickthrough and typo effectiveness ──
+//
+// World and profile search ran with no query logging at all: zero-result
+// queries were invisible, clickthrough was unmeasured, and the one
+// typo-tolerant path (follow suggestions) had no effectiveness baseline. This
+// module logs hashed queries per closed surface into a bounded sidecar,
+// records clicks, and aggregates zero-result / clickthrough / typo-correction
+// rates from a pure function so the math is testable without disk.
+//
+// Feature flag: phase-175 (NEXT_PUBLIC_FEATURE_PHASE_175 / FEATURE_PHASE_175)
+// Rollback: unset the flag → recordSearchQuery / recordSearchClick are no-ops
+//           (return null) and search-query-log.json stays inert on disk. No
+//           migration to undo.
+//
+// Privacy: queries are stored as sha256(normalized query) hex; viewer wallets
+// are hashed the same way (market-store viewerAnalyticsKey precedent). Raw
+// query text and raw wallets never reach the sidecar.
+
+export function isSearchAnalyticsEnabled(): boolean {
+  return isFeatureEnabled("phase-175")
+}
+
+export function searchAnalyticsRollbackNote(): string {
+  return flagRollbackNote("phase-175")
+}
+
+export const SEARCH_SURFACES = ["world", "profile", "explore"] as const
+export type SearchSurface = (typeof SEARCH_SURFACES)[number]
+
+export const SEARCH_QUERY_KINDS = ["query", "click"] as const
+export type SearchQueryKind = (typeof SEARCH_QUERY_KINDS)[number]
+
+const SearchEventSchema = z.object({
+  surface: z.enum(SEARCH_SURFACES),
+  kind: z.enum(SEARCH_QUERY_KINDS).default("query"),
+  /** sha256 hex of the normalized query (64 chars). */
+  query_hash: z.string().regex(/^[a-f0-9]{64}$/, "query_hash must be sha256 hex"),
+  result_count: z.number().int().min(0).max(10_000).optional(),
+  duration_ms: z.number().int().min(0).max(600_000).optional(),
+  /** Opaque session correlation id (bounded); never a wallet. */
+  session_id: z.string().trim().min(1).max(64).optional(),
+  /** sha256 hex of the pre-correction query, when the user fixed a typo. */
+  corrected_from_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  /** sha256 hex of the clicked result reference (token id / wallet). */
+  result_ref_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  ts: z.number().int().min(0).optional(),
+})
+
+export type SearchEventInput = z.infer<typeof SearchEventSchema>
+
+export type SearchEvent = SearchEventInput & { ts: number }
+
+export class SearchQueryLogError extends Error {
+  code: "FLAG_DISABLED" | "VALIDATION_FAILED"
+  details?: unknown
+  constructor(code: SearchQueryLogError["code"], message: string, details?: unknown) {
+    super(message)
+    this.name = "SearchQueryLogError"
+    this.code = code
+    this.details = details
+  }
+}
+
+const MAX_QUERY_EVENTS = 5_000
+
+type SearchQueryLogStore = {
+  version: number
+  events: SearchEvent[]
+}
+
+function emptyStore(): SearchQueryLogStore {
+  return { version: 1, events: [] }
+}
+
+function normalizeStore(raw: unknown): SearchQueryLogStore {
+  const s = raw as SearchQueryLogStore | undefined
+  if (!s || typeof s !== "object" || !Array.isArray(s.events)) return emptyStore()
+  return { version: typeof s.version === "number" && s.version > 0 ? s.version : 1, events: s.events }
+}
+
+/** sha256 hex of the normalized query — the only form that is persisted. */
+export function searchQueryHash(query: string): string {
+  return createHash("sha256").update(query.trim().toLowerCase(), "utf8").digest("hex")
+}
+
+/** sha256 hex of a wallet or result reference — never store the raw value. */
+export function searchRefHash(ref: string): string {
+  return createHash("sha256").update(ref.trim().toUpperCase(), "utf8").digest("hex")
+}
+
+// Closed counter labels — no PII, no unbounded cardinality.
+const counters = new Map<string, number>()
+
+export function snapshotSearchCounters(): Record<string, number> {
+  return Object.fromEntries(counters)
+}
+
+export function resetSearchCountersForTests(): void {
+  counters.clear()
+}
+
+function bump(name: "search_query_total" | "search_zero_result" | "search_click" | "search_typo_corrected"): void {
+  counters.set(name, (counters.get(name) ?? 0) + 1)
+}
+
+function isRecentDuplicate(store: SearchQueryLogStore, event: SearchEvent, windowMs = 60_000): boolean {
+  const last = store.events[store.events.length - 1]
+  if (!last) return false
+  return (
+    last.surface === event.surface &&
+    last.kind === event.kind &&
+    last.query_hash === event.query_hash &&
+    last.session_id === event.session_id &&
+    event.ts - last.ts < windowMs
+  )
+}
+
+/**
+ * Appends a search event. Returns the stored event, or null when the flag is
+ * off (silent no-op so the hot search path never breaks on analytics).
+ */
+export async function recordSearchQuery(
+  raw: unknown,
+  opts: { now?: number } = {},
+): Promise<SearchEvent | null> {
+  if (!isSearchAnalyticsEnabled()) return null
+  const parsed = SearchEventSchema.safeParse(raw)
+  if (!parsed.success) {
+    throw new SearchQueryLogError("VALIDATION_FAILED", "valid search event required", parsed.error.flatten())
+  }
+  const event: SearchEvent = { ...parsed.data, ts: parsed.data.ts ?? opts.now ?? Date.now() }
+
+  return updateStoreWithReader<SearchQueryLogStore, SearchEvent | null>(
+    "searchQueryLog",
+    normalizeStore,
+    (store) => {
+      if (isRecentDuplicate(store, event)) return null
+      store.events.push(event)
+      if (store.events.length > MAX_QUERY_EVENTS) {
+        store.events.splice(0, store.events.length - MAX_QUERY_EVENTS)
+      }
+      store.version += 1
+      if (event.kind === "click") bump("search_click")
+      else {
+        bump("search_query_total")
+        if (event.result_count === 0) bump("search_zero_result")
+        if (event.corrected_from_hash) bump("search_typo_corrected")
+      }
+      return event
+    },
+  )
+}
+
+/** Convenience wrapper for clickthrough beacons. */
+export async function recordSearchClick(
+  input: { surface: SearchSurface; query: string; resultRef?: string; sessionId?: string },
+  opts: { now?: number } = {},
+): Promise<SearchEvent | null> {
+  return recordSearchQuery(
+    {
+      surface: input.surface,
+      kind: "click",
+      query_hash: searchQueryHash(input.query),
+      result_ref_hash: input.resultRef ? searchRefHash(input.resultRef) : undefined,
+      session_id: input.sessionId,
+    },
+    opts,
+  )
+}
+
+export type SearchSurfaceReport = {
+  surface: SearchSurface
+  queries: number
+  zeroResultQueries: number
+  zeroResultRate: number
+  clicks: number
+  clickthroughRate: number
+  correctedQueries: number
+  /** Share of typo-corrected queries whose same-session follow-up query hit results. */
+  typoSuccessRate: number
+}
+
+export type SearchAnalyticsReport = {
+  enabled: boolean
+  windowMs: number
+  totalQueries: number
+  totalClicks: number
+  overallZeroResultRate: number
+  overallClickthroughRate: number
+  surfaces: SearchSurfaceReport[]
+}
+
+/**
+ * Pure aggregation over events — testable without disk. Zero-result rate is
+ * zero-result queries / queries. Clickthrough rate is clicks / queries.
+ * Typo effectiveness: for queries carrying corrected_from_hash, look for a
+ * later same-session query event with result_count > 0; the share of such
+ * sessions that "recovered" is the typo success rate.
+ */
+export function computeSearchReport(
+  events: readonly SearchEvent[],
+  opts: { windowMs?: number; now?: number } = {},
+): SearchAnalyticsReport {
+  const windowMs = opts.windowMs ?? 7 * 24 * 60 * 60 * 1000
+  const now = opts.now ?? Date.now()
+  const cutoff = now - windowMs
+  const recent = events.filter((e) => e.ts >= cutoff)
+
+  const perSurface = new Map<SearchSurface, { queries: number; zero: number; clicks: number; corrected: number; recovered: number }>()
+  for (const surface of SEARCH_SURFACES) {
+    perSurface.set(surface, { queries: 0, zero: 0, clicks: 0, corrected: 0, recovered: 0 })
+  }
+
+  const sessionSuccessAfter = new Map<string, number[]>()
+  for (const e of recent) {
+    if (e.kind === "query" && e.session_id && (e.result_count ?? 0) > 0) {
+      const list = sessionSuccessAfter.get(e.session_id) ?? []
+      list.push(e.ts)
+      sessionSuccessAfter.set(e.session_id, list)
+    }
+  }
+
+  for (const e of recent) {
+    const bucket = perSurface.get(e.surface)
+    if (!bucket) continue
+    if (e.kind === "click") {
+      bucket.clicks += 1
+      continue
+    }
+    bucket.queries += 1
+    if (e.result_count === 0) bucket.zero += 1
+    if (e.corrected_from_hash) {
+      bucket.corrected += 1
+      // A typo recovered only if a LATER same-session query hit results — a
+      // success that preceded the correction does not count.
+      const laterHits = e.session_id ? (sessionSuccessAfter.get(e.session_id) ?? []).filter((ts) => ts > e.ts) : []
+      if (laterHits.length > 0) bucket.recovered += 1
+    }
+  }
+
+  const surfaces: SearchSurfaceReport[] = SEARCH_SURFACES.map((surface) => {
+    const b = perSurface.get(surface)!
+    return {
+      surface,
+      queries: b.queries,
+      zeroResultQueries: b.zero,
+      zeroResultRate: b.queries > 0 ? b.zero / b.queries : 0,
+      clicks: b.clicks,
+      clickthroughRate: b.queries > 0 ? b.clicks / b.queries : 0,
+      correctedQueries: b.corrected,
+      typoSuccessRate: b.corrected > 0 ? b.recovered / b.corrected : 0,
+    }
+  })
+
+  const totalQueries = surfaces.reduce((s, r) => s + r.queries, 0)
+  const totalZero = surfaces.reduce((s, r) => s + r.zeroResultQueries, 0)
+  const totalClicks = surfaces.reduce((s, r) => s + r.clicks, 0)
+
+  return {
+    enabled: isSearchAnalyticsEnabled(),
+    windowMs,
+    totalQueries,
+    totalClicks,
+    overallZeroResultRate: totalQueries > 0 ? totalZero / totalQueries : 0,
+    overallClickthroughRate: totalQueries > 0 ? totalClicks / totalQueries : 0,
+    surfaces,
+  }
+}
+
+/** Reads the sidecar and aggregates; flag off → empty disabled report. */
+export async function getSearchAnalyticsReport(
+  opts: { windowMs?: number; now?: number } = {},
+): Promise<SearchAnalyticsReport> {
+  if (!isSearchAnalyticsEnabled()) {
+    return computeSearchReport([], opts)
+  }
+  const store = await readStore<SearchQueryLogStore>("searchQueryLog", emptyStore)
+  return computeSearchReport(normalizeStore(store).events, opts)
+}
diff --git a/lib/server-data-paths.ts b/lib/server-data-paths.ts
index 49f551c1..d74a22b1 100644
--- a/lib/server-data-paths.ts
+++ b/lib/server-data-paths.ts
@@ -46,6 +46,10 @@ const FILES = {
   qrAudit: "qr-audit.json",
   walletSessions: "wallet-sessions.json",
   ledgerAudit: "ledger-audit.json",
+  experimentAssignments: "experiment-assignments.json",
+  searchQueryLog: "search-query-log.json",
+  costBudgets: "cost-budgets.json",
+  forgeBilling: "forge-billing.json",
 } as const
 
 
diff --git a/vercel.json b/vercel.json
index a3ece80d..b28eca7b 100644
--- a/vercel.json
+++ b/vercel.json
@@ -3,6 +3,10 @@
     {
       "path": "/api/cron/faucet-health",
       "schedule": "0 * * * *"
+    },
+    {
+      "path": "/api/cron/cost-budgets",
+      "schedule": "0 * * * *"
     }
   ],
   "headers": [