@naulon/wayfarer 0.1.1

package/dist/buyer.d.ts

@@ -0,0 +1,195 @@
+declare const AGENT_UA = "naulon-wayfarer/0.1";
+export interface Quoted {
+    priceUsdc: number;
+    amountAtomic: string;
+    /** Nonce the gate issued on the 402; echo it back in the payment (replay guard). */
+    nonce?: string;
+    requirements: {
+        network: string;
+        asset: string;
+        payTo: string;
+        amount: string;
+        maxTimeoutSeconds: number;
+    };
+    /**
+     * When the publisher declares extra settlement legs (e.g. a control-plane operator
+     * fee), the gate advertises the FULL per-leg list (author first) via the
+     * `extensions.naulonLegs` block, and rejects any payment that doesn't sign every leg.
+     * Present only for such an N-leg quote; absent for the stock single-author toll —
+     * then the buyer pays the bare single payload, byte-identical to before.
+     */
+    legs?: {
+        role: string;
+        payTo: string;
+        amount: string;
+        nonce?: string;
+    }[];
+    /** The 402's `resource` object (`{url, description, mimeType}`), verbatim. The gateway
+     *  rail's payment envelope MUST echo it back — the facilitator's `verify` rejects a
+     *  payload missing `resource` (400 `resource: Required`). Absent on the memo rail, which
+     *  relays the raw authorization and never sends the x402 envelope. */
+    resource?: unknown;
+}
+/** A per-leg requirement the buyer signs — the author requirement with this leg's
+ *  payTo + amount substituted (same network/asset/timeout). */
+export type LegRequirements = Quoted["requirements"];
+/**
+ * Why a paid fetch failed, classified so the host can decide what to do (BUY-1.4).
+ * The point is the `retryable` split: `insufficient_funds` is a HARD stop (fund the
+ * wallet, don't re-call), while `toll_moved` / `expired` / `rejected` are transient
+ * (re-quote and try again may succeed). `not_gated` means there was nothing to pay.
+ */
+export type FetchErrorCode = "not_gated" | "not_found" | "toll_moved" | "insufficient_funds" | "expired" | "rejected" | "origin_error" | "needs_topup" | "grant_expired" | "settlement_ambiguous";
+export interface Fetched {
+    ok: boolean;
+    content?: string;
+    settlementRef?: string;
+    /** The author-leg amount paid, in USDC (back-compat — only the primary leg). */
+    paidUsdc?: number;
+    /** The buyer's TRUE outflow authorized for this read, in USDC — the sum across every
+     *  settlement leg (== quotedTotalAtomic of the quote actually signed). Callers debit
+     *  budgets on THIS, not paidUsdc, so a fee'd toll is never under-counted. */
+    costUsdc?: number;
+    /** Citation License (compact JWS) the gate handed back on a paid read. */
+    license?: string;
+    error?: string;
+    /** Typed failure classification (BUY-1.4); absent on success. */
+    errorCode?: FetchErrorCode;
+    /** True when re-quoting/retrying may succeed (toll moved, validity expired, a
+     *  generic rejection); false for a hard stop (insufficient funds — fund first).
+     *  Absent on success. */
+    retryable?: boolean;
+}
+/**
+ * A pay-time spend ceiling the buyer must not exceed (BUY-1.4). The buyer re-quotes
+ * at pay time (its own pre-pay probe IS the re-quote) and ABORTS — paying nothing —
+ * if the live toll total tops this. The caller (the MCP) sets it to the quote it
+ * already gated the budget on, plus a configured tolerance, so a toll that moved up
+ * between the budget check and the pay can never silently overspend.
+ */
+export interface PayGuard {
+    /** Max atomic (micro-USDC) total across all legs the buyer may pay. */
+    maxTotalAtomic: string;
+}
+export interface Buyer {
+    readonly address: string;
+    /** One-time setup (gateway mode deposits USDC into the Gateway Wallet). */
+    init(): Promise<void>;
+    /** Probe price without paying. null if the article isn't gated. */
+    price(url: string, kind: "read" | "citation"): Promise<Quoted | null>;
+    /** Pay and fetch the content. `guard` (optional) caps the pay-time total — the
+     *  buyer aborts beyond it (toll-moved protection), paying nothing. */
+    fetch(url: string, kind: "read" | "citation", guard?: PayGuard): Promise<Fetched>;
+}
+/**
+ * The buyer's true outflow for a quote, in atomic micro-USDC (integer) — the sum of
+ * every advertised settlement leg, or the single author amount when there are none.
+ * Integer math only (AGENTS.md: money is integer micro-USDC, never floats).
+ */
+export declare function quotedTotalAtomic(quoted: Quoted): bigint;
+/**
+ * The toll-moved guard. If `guard` is set and the LIVE quote's true total tops the
+ * guard ceiling, returns a typed `toll_moved` failure (the buyer pays NOTHING);
+ * otherwise null (clear to pay). This is "re-quote at pay time, abort beyond
+ * tolerance": the buyer's own pre-pay probe is the re-quote, compared here against
+ * the ceiling the caller authorized.
+ */
+export declare function tollMovedOrNull(quoted: Quoted, guard?: PayGuard): Fetched | null;
+/**
+ * Classify a gate's payment-rejection message (BUY-1.4). The gate surfaces the real
+ * reason in its 402 body; this maps the known signals onto a typed code + a retry
+ * verdict. Insufficient funds is the one hard stop — every other rejection is worth a
+ * re-quote. Conservative by design: an unrecognized reason is `rejected` (retryable),
+ * never silently treated as a fundable hard stop.
+ */
+/**
+ * Classify a THROWN session-signer refusal (BUY-4 hosted path). The cloud injects a
+ * grant-guarded session signer whose `signTypedData` throws an Error whose message is the
+ * sign guard's code, optionally suffixed " (remaining <micro>)". Unlike `classifyPaymentError`
+ * (which reads a gate 402 body), this refusal never reached the gate — nothing was paid — and
+ * must NOT be run through the 402 classifier, where `grant_exceeded`/`no_session` would fall
+ * through to a retryable `rejected`, telling the agent to retry a pay that can only fail again.
+ *
+ *   grant_exceeded · leg_too_large · no_session      → needs_topup   (fund the session)
+ *   grant_expired                                     → grant_expired (renew — funds intact)
+ *   bad_from · chain_mismatch · payee_not_allowed     → rejected      (a config error a top-up can't fix)
+ *
+ * Returns null when the message is NOT a known signer code (a real socket / unknown throw the
+ * caller should surface as `origin_error`). Never retryable: every signer refusal needs a
+ * host-side action (fund / renew / fix config), never a blind re-call.
+ */
+export declare function classifySignerRefusal(errorText: string): {
+    errorCode: FetchErrorCode;
+    retryable: boolean;
+} | null;
+export declare function classifyPaymentError(errorText: string): {
+    errorCode: FetchErrorCode;
+    retryable: boolean;
+};
+/**
+ * The classified outcome of a price probe. A probe is NOT just "gated or not" — the
+ * reason it isn't gated matters, and collapsing everything non-402 into one bucket is a
+ * money-correctness bug: a wrong URL (404) or a down origin (5xx) is NOT a free read, and
+ * an agent that treats it as one silently skips paying and reads nothing (or an error
+ * page). This union keeps the four cases apart so every caller can respond correctly:
+ *   - `gated`       — a real 402 with a decodable toll; pay it.
+ *   - `free`        — a genuine 2xx; there is nothing to pay (the one true "not gated").
+ *   - `not_found`   — a 404; the path is wrong/unknown, NOT free. On a slug-only pay this
+ *                     is usually the `/essays/<slug>` fallback missing a publisher that
+ *                     serves `/articles/<slug>` — the fix is to pass the canonical url.
+ *   - `unreachable` — any other non-2xx (5xx, 403, a network throw); transient, retryable.
+ *   - `malformed`   — a 402 whose PAYMENT-REQUIRED header is missing/undecodable/empty;
+ *                     a broken gate, never silently a free read.
+ */
+export type ProbeOutcome = {
+    status: "gated";
+    quoted: Quoted;
+} | {
+    status: "free";
+} | {
+    status: "not_found";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    httpStatus: number;
+} | {
+    status: "malformed";
+    reason: string;
+};
+/** Shared price probe — classify the gate's response by HTTP status, decoding the 402
+ *  PAYMENT-REQUIRED header only for a real toll. Never throws: a broken 402 body or a
+ *  network failure is returned as a typed outcome, not an exception. */
+export declare function probe(url: string, kind: "read" | "citation", agentId: string): Promise<ProbeOutcome>;
+/** Back-compat thin wrapper: the decoded quote for a gated 402, else null. Callers that
+ *  must distinguish free / not_found / unreachable use `probe()` directly. */
+export declare function probePrice(url: string, kind: "read" | "citation", agentId: string): Promise<Quoted | null>;
+/**
+ * Map a NON-gated probe outcome to the typed `Fetched` failure every buyer returns, so a
+ * 404/5xx/malformed response never masquerades as a paid or free success. `not_gated` is
+ * reserved for the one true free (2xx) read; a 404 is `not_found` with a message that
+ * points the agent at the canonical url (the usual cause is the `/essays/<slug>` fallback
+ * not matching a `/articles/<slug>` publisher).
+ */
+export declare function probeFailure(outcome: Exclude<ProbeOutcome, {
+    status: "gated";
+}>, url: string): Fetched;
+/**
+ * Assemble the `payment-signature` header. For an N-leg quote (a publisher with extra
+ * settlement legs, e.g. an operator fee), sign one payload per advertised leg and emit
+ * them as the ARRAY the gate's `verifyAndSettle` parses (leg order, author first). For
+ * a stock single-author quote, emit today's BARE single payload — byte-identical, so a
+ * non-fee toll is untouched. `signLeg` is the payment mode's per-leg signer (mock /
+ * memo / gateway); it receives the leg's substituted requirements + the leg's nonce and
+ * returns the raw payload object (this helper does the single-vs-array framing + base64).
+ */
+export declare function assemblePayment(quoted: Quoted, signLeg: (req: LegRequirements, nonce?: string) => unknown | Promise<unknown>): Promise<string>;
+/**
+ * Re-read an essay using a held Citation License instead of paying. Mode-agnostic
+ * — it's just an authenticated GET; the gate honors the license and serves free.
+ */
+export declare function rereadWithLicense(url: string, kind: "read" | "citation", license: string, agentId: string, 
+/** Holder-of-key proof (`<ts>.<nonce>.<sig>`); required for a cnf-bound license. */
+proof?: string): Promise<Fetched>;
+export declare function selectBuyer(): Promise<Buyer>;
+export { AGENT_UA };
+//# sourceMappingURL=buyer.d.ts.map

package/dist/buyer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyer.d.ts","sourceRoot":"","sources":["../src/buyer.ts"],"names":[],"mappings":"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"}

package/dist/buyer.js

@@ -0,0 +1,254 @@
+/**
+ * Buyer abstraction — how the Wayfarer prices and pays for an article.
+ *
+ * Pricing is the same in both modes: probe the tollgate, read the x402
+ * `PAYMENT-REQUIRED` header (free — no payment yet). Paying differs:
+ *   - mock: sign a simple offline payment-signature the mock gate accepts.
+ *   - gateway: Circle's GatewayClient does the full deposit-backed 402 flow.
+ */
+import { activeNetwork, getConfig, supportsMemo } from "@naulon/shared";
+import { agentFetch } from "./sign.js";
+const AGENT_UA = "naulon-wayfarer/0.1";
+/**
+ * The buyer's true outflow for a quote, in atomic micro-USDC (integer) — the sum of
+ * every advertised settlement leg, or the single author amount when there are none.
+ * Integer math only (AGENTS.md: money is integer micro-USDC, never floats).
+ */
+export function quotedTotalAtomic(quoted) {
+    // Threshold MUST match assemblePayment (> 1): the signer only pays the `legs` array
+    // when there are 2+ legs, otherwise it signs `requirements.amount`. Summing a lone leg
+    // here would check a different number than gets signed — a gate could advertise a real
+    // price in requirements and one fake-cheap leg to slip past the ceiling. Check == sign.
+    if (quoted.legs && quoted.legs.length > 1) {
+        return quoted.legs.reduce((sum, leg) => sum + BigInt(leg.amount), 0n);
+    }
+    return BigInt(quoted.amountAtomic);
+}
+/**
+ * The toll-moved guard. If `guard` is set and the LIVE quote's true total tops the
+ * guard ceiling, returns a typed `toll_moved` failure (the buyer pays NOTHING);
+ * otherwise null (clear to pay). This is "re-quote at pay time, abort beyond
+ * tolerance": the buyer's own pre-pay probe is the re-quote, compared here against
+ * the ceiling the caller authorized.
+ */
+export function tollMovedOrNull(quoted, guard) {
+    if (!guard)
+        return null;
+    const live = quotedTotalAtomic(quoted);
+    const ceiling = BigInt(guard.maxTotalAtomic);
+    if (live <= ceiling)
+        return null;
+    return {
+        ok: false,
+        errorCode: "toll_moved",
+        retryable: true,
+        error: `Toll moved at pay time: the live total is ${live} atomic but only ${ceiling} was authorized ` +
+            `(the quoted total plus tolerance). Re-quote and decide again — nothing was paid.`,
+    };
+}
+/**
+ * Classify a gate's payment-rejection message (BUY-1.4). The gate surfaces the real
+ * reason in its 402 body; this maps the known signals onto a typed code + a retry
+ * verdict. Insufficient funds is the one hard stop — every other rejection is worth a
+ * re-quote. Conservative by design: an unrecognized reason is `rejected` (retryable),
+ * never silently treated as a fundable hard stop.
+ */
+/**
+ * Classify a THROWN session-signer refusal (BUY-4 hosted path). The cloud injects a
+ * grant-guarded session signer whose `signTypedData` throws an Error whose message is the
+ * sign guard's code, optionally suffixed " (remaining <micro>)". Unlike `classifyPaymentError`
+ * (which reads a gate 402 body), this refusal never reached the gate — nothing was paid — and
+ * must NOT be run through the 402 classifier, where `grant_exceeded`/`no_session` would fall
+ * through to a retryable `rejected`, telling the agent to retry a pay that can only fail again.
+ *
+ *   grant_exceeded · leg_too_large · no_session      → needs_topup   (fund the session)
+ *   grant_expired                                     → grant_expired (renew — funds intact)
+ *   bad_from · chain_mismatch · payee_not_allowed     → rejected      (a config error a top-up can't fix)
+ *
+ * Returns null when the message is NOT a known signer code (a real socket / unknown throw the
+ * caller should surface as `origin_error`). Never retryable: every signer refusal needs a
+ * host-side action (fund / renew / fix config), never a blind re-call.
+ */
+export function classifySignerRefusal(errorText) {
+    const code = errorText.toLowerCase().match(/^([a-z_]+)/)?.[1];
+    switch (code) {
+        case "grant_exceeded":
+        case "leg_too_large":
+        case "no_session":
+            return { errorCode: "needs_topup", retryable: false };
+        case "grant_expired":
+            return { errorCode: "grant_expired", retryable: false };
+        case "bad_from":
+        case "chain_mismatch":
+        case "payee_not_allowed":
+            return { errorCode: "rejected", retryable: false };
+        default:
+            return null;
+    }
+}
+export function classifyPaymentError(errorText) {
+    const t = errorText.toLowerCase();
+    if (/insufficient|exceeds balance|transfer amount exceeds|not enough|balance too low/.test(t)) {
+        return { errorCode: "insufficient_funds", retryable: false };
+    }
+    if (/validity_too_short|validity too short|expired|valid ?before|too short|window/.test(t)) {
+        return { errorCode: "expired", retryable: true };
+    }
+    return { errorCode: "rejected", retryable: true };
+}
+/** Shared price probe — classify the gate's response by HTTP status, decoding the 402
+ *  PAYMENT-REQUIRED header only for a real toll. Never throws: a broken 402 body or a
+ *  network failure is returned as a typed outcome, not an exception. */
+export async function probe(url, kind, agentId) {
+    let res;
+    try {
+        res = await agentFetch(url, {
+            headers: { "user-agent": AGENT_UA, "x-naulon-agent": agentId, "x-naulon-kind": kind },
+        });
+    }
+    catch {
+        // A DNS/connection failure is unreachable, not "free" — httpStatus 0 = no response.
+        return { status: "unreachable", httpStatus: 0 };
+    }
+    if (res.status === 402) {
+        const header = res.headers.get("payment-required");
+        if (!header)
+            return { status: "malformed", reason: "missing the PAYMENT-REQUIRED header" };
+        let decoded;
+        try {
+            decoded = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+        }
+        catch {
+            return { status: "malformed", reason: "an undecodable PAYMENT-REQUIRED header" };
+        }
+        const req = decoded.accepts?.[0];
+        if (!req)
+            return { status: "malformed", reason: "a 402 with no payment options (empty accepts)" };
+        // The author leg is what the agent appraises (the content's price), so `priceUsdc`
+        // stays the author amount even when an additive fee leg makes the buyer's TOTAL
+        // higher. `legs` (when present) is the full set the buyer must sign — see assemblePayment.
+        const legs = decoded.extensions?.naulonLegs?.legs;
+        return {
+            status: "gated",
+            quoted: {
+                priceUsdc: Number(req.amount) / 1_000_000,
+                amountAtomic: req.amount,
+                nonce: req.extra?.nonce,
+                requirements: req,
+                ...(decoded.resource !== undefined ? { resource: decoded.resource } : {}),
+                // Only a real multi-leg (>1) quote carries `legs`; an honest gate emits naulonLegs
+                // solely for 2+ legs (build402). A lone-leg array is anomalous — dropping it keeps
+                // the invariant "legs present ⟺ signed as an array" that the ceiling check relies on.
+                ...(legs && legs.length > 1 ? { legs } : {}),
+            },
+        };
+    }
+    if (res.status === 404)
+        return { status: "not_found", httpStatus: 404 };
+    if (res.ok)
+        return { status: "free" };
+    return { status: "unreachable", httpStatus: res.status };
+}
+/** Back-compat thin wrapper: the decoded quote for a gated 402, else null. Callers that
+ *  must distinguish free / not_found / unreachable use `probe()` directly. */
+export async function probePrice(url, kind, agentId) {
+    const outcome = await probe(url, kind, agentId);
+    return outcome.status === "gated" ? outcome.quoted : null;
+}
+/**
+ * Map a NON-gated probe outcome to the typed `Fetched` failure every buyer returns, so a
+ * 404/5xx/malformed response never masquerades as a paid or free success. `not_gated` is
+ * reserved for the one true free (2xx) read; a 404 is `not_found` with a message that
+ * points the agent at the canonical url (the usual cause is the `/essays/<slug>` fallback
+ * not matching a `/articles/<slug>` publisher).
+ */
+export function probeFailure(outcome, url) {
+    switch (outcome.status) {
+        case "free":
+            return {
+                ok: false,
+                errorCode: "not_gated",
+                retryable: false,
+                error: "not gated — the source returned a free (2xx) read; no payment is required.",
+            };
+        case "not_found":
+            return {
+                ok: false,
+                errorCode: "not_found",
+                retryable: false,
+                error: `probed ${url} — HTTP 404. This is NOT a free read: the path was not found. Pass the canonical ` +
+                    `url from naulon_discover — the /essays/<slug> fallback does not match every publisher (many serve ` +
+                    `/articles/<slug> or a custom path).`,
+            };
+        case "unreachable":
+            return {
+                ok: false,
+                errorCode: "origin_error",
+                retryable: true,
+                error: `probed ${url} — HTTP ${outcome.httpStatus || "no response"}. The origin/gate is unreachable or erroring; retry.`,
+            };
+        case "malformed":
+            return {
+                ok: false,
+                errorCode: "rejected",
+                retryable: true,
+                error: `the gate returned a 402 but ${outcome.reason}; cannot quote the toll. Retry or check the gate.`,
+            };
+    }
+}
+/**
+ * Assemble the `payment-signature` header. For an N-leg quote (a publisher with extra
+ * settlement legs, e.g. an operator fee), sign one payload per advertised leg and emit
+ * them as the ARRAY the gate's `verifyAndSettle` parses (leg order, author first). For
+ * a stock single-author quote, emit today's BARE single payload — byte-identical, so a
+ * non-fee toll is untouched. `signLeg` is the payment mode's per-leg signer (mock /
+ * memo / gateway); it receives the leg's substituted requirements + the leg's nonce and
+ * returns the raw payload object (this helper does the single-vs-array framing + base64).
+ */
+export async function assemblePayment(quoted, signLeg) {
+    if (quoted.legs && quoted.legs.length > 1) {
+        const payloads = await Promise.all(quoted.legs.map((leg) => signLeg({ ...quoted.requirements, payTo: leg.payTo, amount: leg.amount }, leg.nonce)));
+        return Buffer.from(JSON.stringify(payloads)).toString("base64");
+    }
+    const payload = await signLeg(quoted.requirements, quoted.nonce);
+    return Buffer.from(JSON.stringify(payload)).toString("base64");
+}
+/**
+ * Re-read an essay using a held Citation License instead of paying. Mode-agnostic
+ * — it's just an authenticated GET; the gate honors the license and serves free.
+ */
+export async function rereadWithLicense(url, kind, license, agentId, 
+/** Holder-of-key proof (`<ts>.<nonce>.<sig>`); required for a cnf-bound license. */
+proof) {
+    const headers = {
+        "user-agent": AGENT_UA,
+        "x-naulon-agent": agentId,
+        "x-naulon-kind": kind,
+        "x-naulon-license": license,
+    };
+    if (proof)
+        headers["x-naulon-proof"] = proof;
+    const res = await agentFetch(url, { headers });
+    if (!res.ok)
+        return { ok: false, error: `re-read returned ${res.status}` };
+    return { ok: true, content: await res.text(), paidUsdc: 0, license };
+}
+export async function selectBuyer() {
+    const cfg = getConfig();
+    if (cfg.PAYMENT_MODE === "gateway") {
+        // On a memo-capable network (Arc) the gate settles via the self-relay rail, which
+        // expects a RAW USDC EIP-3009 authorization (USDC domain), not Circle's Gateway
+        // payload (GatewayWallet domain) — so the buyer signs differently. Field-presence
+        // gate, mirroring the gate's settle routing: a swap to Base falls back to the SDK.
+        if (supportsMemo(activeNetwork())) {
+            const { memoBuyer } = await import("./memo.js");
+            return memoBuyer();
+        }
+        const { gatewayBuyer } = await import("./gateway.js");
+        return gatewayBuyer();
+    }
+    const { mockBuyer } = await import("./pay.js");
+    return mockBuyer();
+}
+export { AGENT_UA };
+//# sourceMappingURL=buyer.js.map

package/dist/buyer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buyer.js","sourceRoot":"","sources":["../src/buyer.ts"],"names":[],"mappings":"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"}

package/dist/decide.d.ts

@@ -0,0 +1,115 @@
+import type { AppraisedCandidate, Decision } from "./types.ts";
+export interface DecisionPolicy {
+    /**
+     * Don't pay for anything below this relevance, however cheap. Protects the
+     * budget from spending on near-misses just because they're affordable.
+     */
+    relevanceFloor: number;
+    /** Hard ceiling on how many essays to pay for in one run. */
+    maxPaid: number;
+    /**
+     * Agent identity this run is attributed to. It does NOT alter spend math here —
+     * a per-agent cap is applied by the caller resolving that agent's remaining
+     * allowance and passing it as `budgetUsdc`. It rides on the policy so the
+     * decision log can be tagged per agent in the audit plane (BUY-3.3).
+     */
+    agentId?: string;
+    /**
+     * Allowlist of publisher hosts. When set, ONLY these hosts are payable; every
+     * other host — and any candidate whose host is unknown — is skipped
+     * (deny-by-default). Host match is exact, case-insensitive.
+     */
+    allowDomains?: string[];
+    /** Hosts that are never paid, even when allowed and affordable. Deny wins over allow. */
+    denyDomains?: string[];
+    /**
+     * Max essays to pay for from any single host. Counts pays made this run plus
+     * any prior pays for the host in the current window (`context.priorDomainCounts`).
+     */
+    perDomainCap?: number;
+    /**
+     * A toll at or above this price is not auto-paid — it becomes an `approve`
+     * decision (human gate) instead. Cheaper tolls pay automatically.
+     */
+    approvalThresholdUsdc?: number;
+    /** Kill-switch: when true, halt all new spend this run (free re-reads still allowed). */
+    killSwitch?: boolean;
+}
+/** Runtime state injected into `decide()` that can't be known from the candidates alone. */
+export interface DecideContext {
+    /**
+     * Pays already made to each host in the current rate-cap window (across earlier
+     * runs), added to this run's per-host count when enforcing `perDomainCap`.
+     */
+    priorDomainCounts?: Record<string, number>;
+    /**
+     * The configured gate base URL. Supplied so `decide()` can resolve a slug-only candidate to the
+     * SAME url the pay step will use (`c.url ?? articleUrl(gateBase, c.slug)`), and evaluate domain
+     * policy against that real target. Without it a slug-only candidate has no derivable host and is
+     * treated as unknown — which an allowlist correctly denies by default.
+     */
+    gateBase?: string;
+}
+/**
+ * The hostname money will actually go to, mirroring the pay step's own resolution
+ * (`c.url ?? articleUrl(gateBase, c.slug)`). This — not the discovery source's `Candidate.host`
+ * field — is what domain policy is evaluated against, so an allow/deny decision can never be made
+ * about a different host than the one that gets paid. Returns undefined when no url is derivable
+ * (an allowlist then denies by default).
+ */
+export declare function payUrlOf(url: string | undefined, gateBase: string | undefined, slug: string): string | undefined;
+export declare function payHostOf(url: string | undefined, gateBase: string | undefined, slug: string): string | undefined;
+/** The shared spend gate's verdict. `approve` means "real, but needs a human" — distinct from
+ *  `skip` so callers can surface a human-approval affordance rather than a flat refusal. */
+export type SpendVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    action: "skip" | "approve";
+    reason: string;
+};
+/**
+ * THE operator-policy gate — the single source of truth for "may I pay this host, at this price,
+ * right now". Every spending path calls this: `decide()` for the composite research run, and the
+ * MCP's granular `naulon_pay_and_read`.
+ *
+ * It exists because the checks previously lived ONLY inside `decide()`, so the granular pay tool
+ * — the path the tool descriptions tell agents to prefer — silently ignored the kill-switch,
+ * deny/allow lists, per-domain cap, and approval threshold an operator had configured. Two
+ * implementations of one rule is how that bug happens; there is now one implementation.
+ *
+ * Order is load-bearing and matches the original `decide()` sequence, so the reason a caller
+ * surfaces when several gates apply is unchanged: kill → deny → allow → maxPaid → perDomainCap →
+ * budget → approval. `paidCount` / `remainingUsdc` are optional; omit them when the caller
+ * enforces those with its own accounting and messaging (the MCP session envelope does).
+ */
+export declare function spendGate(input: {
+    /** Publisher host, already normalized-ish; undefined when unknown (deny-by-default under an allowlist). */
+    host: string | undefined;
+    /** The buyer's TRUE total for this read, in USDC. */
+    priceUsdc: number;
+    policy: DecisionPolicy;
+    /** Pays already made for this host (this run/session + any prior window). */
+    paidForHost?: number;
+    /** Pays already made overall — enables the `maxPaid` gate when provided. */
+    paidCount?: number;
+    /** Budget left in USDC — enables the budget gate when provided. */
+    remainingUsdc?: number;
+}): SpendVerdict;
+/**
+ * TODO(you): this policy is the lever that defines the agent's "taste". The
+ * defaults are sensible, but the interesting choices are yours to make:
+ *
+ *   - relevanceFloor: how picky? Too low → wastes budget on tangential essays.
+ *     Too high → misses useful context. 0.35 is a starting guess.
+ *   - Ranking key: density (relevance/price) favors cheap-and-relevant. Would
+ *     you instead rank by raw relevance (quality at any price), or blend them?
+ *     See `rank()` below — that sort is the whole strategy in one line.
+ *   - maxPaid: a stop so a big budget doesn't over-cite a thin topic.
+ *
+ * Tune these against real runs and watch the decision log; that visible
+ * reasoning is what the judges reward.
+ */
+export declare const DEFAULT_POLICY: DecisionPolicy;
+export declare function decide(candidates: AppraisedCandidate[], budgetUsdc: number, cached?: ReadonlySet<string>, policy?: DecisionPolicy, context?: DecideContext): Decision[];
+//# sourceMappingURL=decide.d.ts.map

package/dist/decide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../src/decide.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAIhB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAOD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYhH;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGjH;AAED;4FAC4F;AAC5F,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAC/B,2GAA2G;IAC3G,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,YAAY,CAwCf;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,EAAE,cAG5B,CAAC;AASF,wBAAgB,MAAM,CACpB,UAAU,EAAE,kBAAkB,EAAE,EAChC,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,WAAW,CAAC,MAAM,CAAa,EACvC,MAAM,GAAE,cAA+B,EACvC,OAAO,GAAE,aAAkB,GAC1B,QAAQ,EAAE,CA2FZ"}