@naulon/wayfarer 0.1.1

package/README.md

@@ -0,0 +1,39 @@
+# @naulon/wayfarer
+
+The paying agent. Give it a topic and a budget; it discovers tolled articles,
+decides which are worth citing, pays only those, and answers from what it bought.
+
+The point isn't automation for its own sake — it's that the agent makes a real
+budget decision at each step instead of paying for everything. It ranks candidates
+by relevance-per-dollar, buys greedily under the budget down to a relevance floor,
+reuses anything already paid for, and logs *why* for every candidate. The
+reasoning is the artifact.
+
+## Run
+
+```bash
+npm run -w @naulon/tollgate dev &                    # the gate to pay
+npm run -w @naulon/wayfarer start -- "payment and passage" # the agent
+```
+
+```text
+decisions:
+  [PAY]  the-naulon — relevance 1.00 @ $0.005; $0.095 left
+  [SKIP] on-stillness — relevance 0.00 below floor 0.35
+  ✓ paid $0.005000 for the-naulon
+```
+
+It runs offline against mock settlement. Set `OPENAI_API_KEY` for LLM appraisal
+and answer synthesis instead of the keyword heuristic; set `PAYMENT_MODE=gateway`
+with a funded buyer wallet to pay for real over Circle Gateway on Arc Network.
+
+## What's inside
+
+- **`discover.ts` / `discovery.ts`** — find tollable candidates from a gate or feed.
+- **`appraise.ts` / `decide.ts` / `allocation.ts`** — relevance, the pay/skip call, budget allocation.
+- **`buyer.ts` / `gateway.ts`** — the x402 payment loop (mock and Circle Gateway).
+- **`agent.ts` / `lib.ts`** — the end-to-end research run, also importable as a library.
+
+Exposed as an MCP server by [`@naulon/wayfarer-mcp`](../wayfarer-mcp).
+
+MIT.

package/dist/agent.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The Wayfarer pipeline: discover → price → appraise → decide → pay → ground.
+ *
+ * Each stage is explicit and logged, so the agent's reasoning is auditable — the
+ * decision log is the artifact, not a black box. Paying runs against the
+ * tollgate over the real x402 contract; the Buyer is mock (offline) or Circle
+ * Gateway (PAYMENT_MODE=gateway), chosen at startup.
+ */
+import { type JwkSet } from "@naulon/shared";
+import { type GatewaySigner } from "./gateway.ts";
+import { type MemoSigner } from "./memo.ts";
+import { type RailSigners } from "./rail.ts";
+import type { DecideContext, DecisionPolicy } from "./decide.ts";
+import type { HeldStore } from "./licenseStore.ts";
+import type { RunResult } from "./types.ts";
+import type { AgentWallet } from "./wallet.ts";
+export type Logger = (line: string) => void;
+export declare function tollgateBase(): string;
+export declare function articleUrl(base: string, slug: string): string;
+/** Fetch the gate's public key set so the agent can verify the receipts it holds. */
+export declare function fetchJwks(base: string): Promise<JwkSet | null>;
+/** Verify a captured license against the gate's JWKS. null when JWKS unavailable. */
+export declare function verifyAgainst(jws: string, jwks: JwkSet): boolean;
+/** Optional overrides for a single run. `budgetUsdc` lets a caller spend LESS than
+ *  the configured ceiling for this run (e.g. the MCP clamping the model's requested
+ *  budget to what remains in the session envelope) — it can only narrow, never widen,
+ *  because the caller is expected to pass `min(requested, configCeiling)`. */
+export interface RunOptions {
+    budgetUsdc?: number;
+    /**
+     * Operator policy for this run (allow/deny domains, per-domain cap, approval
+     * threshold, kill-switch). Server/config-supplied, never LLM-controlled — same
+     * principle as `budgetUsdc`. Omitted ⇒ `DEFAULT_POLICY` (the original behavior).
+     */
+    policy?: DecisionPolicy;
+    /** Window state for per-domain rate caps across runs (prior pays per host). */
+    decideContext?: DecideContext;
+    /**
+     * Gate this run settles into (base URL). Server/config-supplied, never
+     * LLM-controlled — same principle as `budgetUsdc`/`policy`. Lets a hosted caller
+     * point one run at a specific fleet tenant's gate. Omitted ⇒ `tollgateBase()`
+     * (the env default), so the OSS single-gate path is unchanged.
+     */
+    tollgateUrl?: string;
+    /**
+     * This run's custody-free session signer (BUY-4 hosted path). When present, tolls
+     * are signed by the injected `MemoSigner` (naulon's grant-checked `/sign-memo` BFF
+     * over an encrypted session key) instead of the env `BUYER_PRIVATE_KEY` — so the
+     * hosted `naulon_research` pays from the buyer's managed session wallet, mirroring
+     * `naulon_pay_and_read`. Omitted ⇒ `selectBuyer()` picks the env buyer (the OSS
+     * self-host path). Server/config-supplied, never LLM-controlled. A `MemoSigner`
+     * (memo/Arc rail) or a `GatewaySigner` (memo-less Circle rails); `run` routes it to
+     * the matching buyer via `supportsMemo(activeNetwork())`, like `selectBuyer()`.
+     */
+    signer?: MemoSigner | GatewaySigner;
+    /**
+     * BOTH rail signers over the same sealed session key (RAS-B mixed fleet). When present, the run
+     * pays through `railBuyer`, which picks memo vs gateway PER-402 from each tenant's advertised
+     * network — exactly like `naulon_pay_and_read` — instead of the fleet-global `supportsMemo`
+     * routing a single `signer` gets. Wins over `signer`. Server/config-supplied, never LLM-controlled.
+     */
+    railSigners?: RailSigners;
+    /**
+     * This run's held-license backend (BUY-4 hosted path). The cloud injects a
+     * per-session store so the composite loop's free re-reads never cross buyer
+     * boundaries in a shared process. Omitted ⇒ the process-global file (OSS path).
+     */
+    heldStore?: HeldStore;
+    /**
+     * The wallet that signs proof-of-possession for this run's cnf-bound held
+     * re-reads. Hosted path injects a signer over the session key (`/sign-pop`);
+     * omitted ⇒ `getWallet()` (the env/dev wallet, unchanged OSS path).
+     */
+    popWallet?: AgentWallet;
+}
+export declare function run(topic: string, log?: Logger, opts?: RunOptions): Promise<RunResult>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAA+D,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAG1G,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAExD,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAGnD,OAAO,KAAK,EAAuC,SAAS,EAAU,MAAM,YAAY,CAAC;AAEzF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,qFAAqF;AACrF,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASpE;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBhE;AAED;;;8EAG8E;AAC9E,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;CACzB;AAED,wBAAsB,GAAG,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAiB,EACtB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,SAAS,CAAC,CAwJpB"}

package/dist/agent.js

@@ -0,0 +1,235 @@
+/**
+ * The Wayfarer pipeline: discover → price → appraise → decide → pay → ground.
+ *
+ * Each stage is explicit and logged, so the agent's reasoning is auditable — the
+ * decision log is the artifact, not a black box. Paying runs against the
+ * tollgate over the real x402 contract; the Buyer is mock (offline) or Circle
+ * Gateway (PAYMENT_MODE=gateway), chosen at startup.
+ */
+import { activeNetwork, getConfig, supportsMemo, usdc, verifyLicense } from "@naulon/shared";
+import { appraise } from "./appraise.js";
+import { quotedTotalAtomic, rereadWithLicense, selectBuyer } from "./buyer.js";
+import { gatewayBuyer } from "./gateway.js";
+import { memoBuyer } from "./memo.js";
+import { railBuyer } from "./rail.js";
+import { decide, DEFAULT_POLICY } from "./decide.js";
+import { discover } from "./discover.js";
+import { decodeHeld, fileHeldStore, isLive } from "./licenseStore.js";
+import { buildPopProof } from "./pop.js";
+import { agentFetch } from "./sign.js";
+import { getWallet } from "./wallet.js";
+export function tollgateBase() {
+    const url = getConfig().TOLLGATE_URL;
+    // No fail-open: an unset gate is a config error surfaced here, not a fabricated
+    // http://localhost target that refuses later with a confusing "unreachable host".
+    // Callers prefer an injected per-session `opts.tollgateUrl`; this is only reached
+    // when neither is set.
+    if (!url)
+        throw new Error("TOLLGATE_URL is not configured");
+    return url;
+}
+export function articleUrl(base, slug) {
+    return `${base.replace(/\/$/, "")}/essays/${encodeURIComponent(slug)}`;
+}
+/** Fetch the gate's public key set so the agent can verify the receipts it holds. */
+export async function fetchJwks(base) {
+    try {
+        const res = await agentFetch(`${base.replace(/\/$/, "")}/.well-known/naulon-jwks.json`);
+        if (!res.ok)
+            return null;
+        const set = (await res.json());
+        return set.keys?.length ? set : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Verify a captured license against the gate's JWKS. null when JWKS unavailable. */
+export function verifyAgainst(jws, jwks) {
+    try {
+        const claims = JSON.parse(Buffer.from(jws.split(".")[1] ?? "", "base64url").toString("utf8"));
+        const r = verifyLicense(jws, {
+            now: Date.now(),
+            expectedIssuer: claims.iss ?? "",
+            expectedAudience: claims.aud ?? "",
+            jwks,
+        });
+        return r.ok;
+    }
+    catch {
+        return false;
+    }
+}
+export async function run(topic, log = () => { }, opts = {}) {
+    const cfg = getConfig();
+    const budget = opts.budgetUsdc ?? cfg.WAYFARER_BUDGET_USDC;
+    const base = opts.tollgateUrl ?? tollgateBase();
+    // Hosted path: sign each leg via the injected cloud session key (custody-free); the
+    // env BUYER_PRIVATE_KEY is never read. Route the injected signer to the active network's
+    // rail — memo-LESS networks (Base + every Gateway chain) settle via gatewayBuyer (the Circle
+    // envelope), memo networks via memoBuyer — mirroring selectBuyer() and naulon_pay_and_read so
+    // hosted research pays from the same wallet on whatever rail the tenant settles on. The cloud
+    // injects the signer matching the network's rail. Default: the BYO-key buyer selectBuyer() picks.
+    const buyer = opts.railSigners
+        ? railBuyer(opts.railSigners)
+        : opts.signer
+            ? supportsMemo(activeNetwork())
+                ? memoBuyer(opts.signer)
+                : gatewayBuyer(opts.signer)
+            : await selectBuyer();
+    // Per-session held store + PoP signer (BUY-4): the injected pair keeps the composite loop's
+    // free re-reads isolated per buyer and signed by the paying session EOA. Omitted ⇒ OSS defaults.
+    const heldStore = opts.heldStore ?? fileHeldStore;
+    const popWallet = opts.popWallet ?? getWallet();
+    log(`topic: "${topic}"`);
+    log(`budget: $${budget} · mode ${cfg.PAYMENT_MODE} · wallet ${buyer.address} · gate ${base}`);
+    await buyer.init();
+    // 1. discover (free teasers)
+    const candidates = await discover(topic);
+    log(`\ndiscovered ${candidates.length} candidate essays`);
+    // 2. price (free x402 probes — no payment yet)
+    const priced = [];
+    // The TRUE total (all legs, atomic micro-USDC) each candidate was quoted at here. The pay step
+    // uses it as the toll-moved ceiling, so a gate that quotes low at appraisal and charges more at
+    // pay time is aborted — the BUY-1.4 guarantee. Budget-remaining alone cannot detect that.
+    const quotedTotals = new Map();
+    for (const c of candidates) {
+        const quoted = await buyer.price(c.url ?? articleUrl(base, c.slug), "citation");
+        if (quoted) {
+            priced.push({ ...c, price: usdc(quoted.priceUsdc) });
+            quotedTotals.set(c.slug, quotedTotalAtomic(quoted));
+        }
+        else
+            log(`  · ${c.slug}: not gated — skipping`);
+    }
+    log(`priced ${priced.length} gated essays`);
+    // 3. appraise
+    const appraised = await appraise(topic, priced);
+    log(`\nappraisal:`);
+    for (const a of appraised)
+        log(`  · ${a.slug}: relevance ${a.relevance.toFixed(2)} — ${a.rationale}`);
+    // 4. decide (the agency). A live license already held for an essay makes it a
+    // zero-cost "cache" — pay once, re-read free.
+    const held = await heldStore.load();
+    const nowSec = Math.floor(Date.now() / 1000);
+    const licensed = new Set([...held.values()].filter((h) => isLive(h, nowSec)).map((h) => h.slug));
+    if (licensed.size)
+        log(`\nholding ${licensed.size} live license(s) — those re-read free`);
+    // gateBase lets decide() resolve a slug-only candidate to the SAME url the pay step below uses,
+    // so domain policy is evaluated against the host that actually gets paid (never Candidate.host).
+    const decisions = decide(appraised, budget, licensed, opts.policy ?? DEFAULT_POLICY, {
+        ...opts.decideContext,
+        gateBase: opts.decideContext?.gateBase ?? base,
+    });
+    log(`\ndecisions:`);
+    for (const d of decisions)
+        log(`  [${d.action.toUpperCase()}] ${d.slug} — ${d.reason}`);
+    // 5. obtain: pay for new sources (capturing + verifying the license), or re-read
+    // already-licensed ones for free.
+    const jwks = await fetchJwks(base);
+    const sources = [];
+    let spent = 0;
+    for (const d of decisions) {
+        const url = d.url ?? articleUrl(base, d.slug);
+        if (d.action === "cache") {
+            const h = held.get(d.slug);
+            if (!h)
+                continue;
+            // Holder-of-key license: sign a fresh proof-of-possession so the gate knows
+            // we still hold the payer wallet, not just a captured token.
+            let proof;
+            if (h.pop) {
+                proof = (await buildPopProof(h, popWallet, Date.now())) ?? undefined;
+                if (!proof) {
+                    log(`  ✗ re-read ${d.slug}: license is holder-of-key but wallet can't sign — paying instead`);
+                    continue;
+                }
+            }
+            const reread = await rereadWithLicense(url, "citation", h.jws, buyer.address, proof);
+            if (reread.ok) {
+                sources.push({ slug: d.slug, title: d.title, content: reread.content ?? "", paidUsdc: 0, licenseId: h.jti });
+                log(`  🎫 re-read ${d.slug} FREE with held license (${h.jti.slice(0, 8)})${h.pop ? " 🔑 proof-of-possession" : ""}`);
+            }
+            else {
+                log(`  ✗ re-read failed for ${d.slug}: ${reread.error}`);
+            }
+            continue;
+        }
+        if (d.action !== "pay")
+            continue;
+        // The pay-time ceiling is the TIGHTER of two independent bounds:
+        //   · toll-moved  — the total this candidate was quoted at in step 2, plus the configured
+        //     tolerance. Catches a gate that quotes low at appraisal and charges more at pay time
+        //     (a budget check alone cannot: the inflated price still "fits").
+        //   · budget      — what is actually left. decide() plans against the AUTHOR-leg price, which
+        //     under-counts a fee'd toll, so its plan can exceed budget.
+        // Whichever is smaller wins; exceeding it aborts the pay having spent nothing.
+        const remainingAtomic = BigInt(Math.max(0, Math.round((budget - spent) * 1_000_000)));
+        const quotedAtomic = quotedTotals.get(d.slug);
+        const bps = BigInt(cfg.WAYFARER_TOLL_TOLERANCE_BPS);
+        const tollCeiling = quotedAtomic === undefined ? undefined : quotedAtomic + (quotedAtomic * bps) / 10000n;
+        const ceiling = tollCeiling === undefined ? remainingAtomic : (tollCeiling < remainingAtomic ? tollCeiling : remainingAtomic);
+        const result = await buyer.fetch(url, "citation", { maxTotalAtomic: ceiling.toString() });
+        if (!result.ok) {
+            log(`  ✗ payment failed for ${d.slug}: ${result.error}`);
+            continue;
+        }
+        // Debit the TRUE total across all legs (costUsdc), not the author leg (paidUsdc) — else a
+        // fee'd toll under-counts spend and the loop keeps buying past budget.
+        spent += result.costUsdc ?? result.paidUsdc ?? d.price;
+        let licenseId;
+        if (result.license) {
+            const decoded = decodeHeld(result.license);
+            const verified = jwks ? verifyAgainst(result.license, jwks) : null;
+            if (decoded) {
+                // Persist the url actually paid alongside the license, so it travels with the
+                // held record (a slug-only re-read can then target the real link, not a template).
+                held.set(d.slug, { ...decoded, jws: result.license, url });
+                licenseId = decoded.jti;
+            }
+            const mark = verified === true ? " → 🎫 license verified" : verified === false ? " → ⚠ license UNVERIFIED" : " → 🎫 license";
+            log(`  ✓ paid $${(result.paidUsdc ?? d.price).toFixed(6)} for ${d.slug} (ref ${result.settlementRef})${mark} ${licenseId?.slice(0, 8) ?? ""}`);
+        }
+        else {
+            log(`  ✓ paid $${(result.paidUsdc ?? d.price).toFixed(6)} for ${d.slug} (ref ${result.settlementRef})`);
+        }
+        sources.push({
+            slug: d.slug,
+            title: d.title,
+            content: result.content ?? "",
+            paidUsdc: result.paidUsdc ?? d.price,
+            settlementRef: result.settlementRef,
+            licenseId,
+        });
+    }
+    await heldStore.save(held);
+    // 6. ground
+    const answer = await ground(topic, sources);
+    log(`\nspent $${spent.toFixed(6)} of $${budget} across ${sources.length} cited source(s)`);
+    return { topic, budget, spent: usdc(spent), decisions, sources, answer };
+}
+async function ground(topic, sources) {
+    if (sources.length === 0) {
+        return `No sources were worth paying for under budget for "${topic}".`;
+    }
+    const citations = sources
+        .map((s, i) => `[${i + 1}] ${s.title} (${s.slug})${s.licenseId ? ` · licensed 🎫 ${s.licenseId.slice(0, 8)}` : ""}`)
+        .join("\n");
+    if (getConfig().OPENAI_API_KEY) {
+        try {
+            const { ChatOpenAI } = await import("@langchain/openai");
+            const model = new ChatOpenAI({ model: "gpt-4o-mini", temperature: 0.2 });
+            const corpus = sources
+                .map((s, i) => `[${i + 1}] ${s.title}\n${s.content.slice(0, 4000)}`)
+                .join("\n\n");
+            const res = await model.invoke(`Answer the topic "${topic}" grounded ONLY in these sources, citing with [n].\n\n${corpus}`);
+            return `${String(res.content)}\n\nSources:\n${citations}`;
+        }
+        catch {
+            // fall through to template
+        }
+    }
+    return (`Grounded answer for "${topic}" (template; set OPENAI_API_KEY for synthesis):\n` +
+        `Paid for and cited ${sources.length} source(s).\n\nSources:\n${citations}`);
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/allocation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cross-source proportional allocation (BUY-3.2) — a BUYER-side policy.
+ *
+ * Keryx splits a citation-reward pool across the sources it actually cited,
+ * weighted by each source's contribution. Wayfarer pays each source a flat
+ * per-article toll; this closes the parity gap as a *policy* on top of those
+ * tolls: given a fixed answer-budget, decide how much of it each cited source
+ * earned, proportional to its appraised contribution.
+ *
+ * It computes numbers — it does NOT pay. There is no new settlement primitive;
+ * a caller that wants to act on the split reuses the existing per-article toll
+ * rail. Money is integer micro-USDC and the split is dust-free (largest-
+ * remainder apportionment, same money-truth discipline as shared `splitMicro`,
+ * here keyed by source slug rather than payee wallet).
+ */
+/** One source's share of the answer-budget. */
+export interface SourceAllocation {
+    slug: string;
+    /** Integer micro-USDC of the pool attributed to this source. */
+    micro: number;
+    /** Normalized 0..1 contribution weight (for display / a citation-reward call). */
+    weight: number;
+}
+/**
+ * Allocate `poolMicro` (integer micro-USDC) across `sources` proportional to each
+ * source's `contribution`. Negative contributions clamp to zero. When the total
+ * contribution is positive, `Σ micro === floor(poolMicro)` exactly — no dust
+ * created or lost; the rounding remainder goes to the largest fractional shares.
+ * When every contribution is zero (or the list is empty), nothing is allocated
+ * (all `micro === 0`) — there is no basis to weight the pool.
+ */
+export declare function allocateByContribution(sources: readonly {
+    slug: string;
+    contribution: number;
+}[], poolMicro: number): SourceAllocation[];
+//# sourceMappingURL=allocation.d.ts.map

package/dist/allocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocation.d.ts","sourceRoot":"","sources":["../src/allocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAAE,EAC1D,SAAS,EAAE,MAAM,GAChB,gBAAgB,EAAE,CAsBpB"}

package/dist/allocation.js

@@ -0,0 +1,45 @@
+/**
+ * Cross-source proportional allocation (BUY-3.2) — a BUYER-side policy.
+ *
+ * Keryx splits a citation-reward pool across the sources it actually cited,
+ * weighted by each source's contribution. Wayfarer pays each source a flat
+ * per-article toll; this closes the parity gap as a *policy* on top of those
+ * tolls: given a fixed answer-budget, decide how much of it each cited source
+ * earned, proportional to its appraised contribution.
+ *
+ * It computes numbers — it does NOT pay. There is no new settlement primitive;
+ * a caller that wants to act on the split reuses the existing per-article toll
+ * rail. Money is integer micro-USDC and the split is dust-free (largest-
+ * remainder apportionment, same money-truth discipline as shared `splitMicro`,
+ * here keyed by source slug rather than payee wallet).
+ */
+/**
+ * Allocate `poolMicro` (integer micro-USDC) across `sources` proportional to each
+ * source's `contribution`. Negative contributions clamp to zero. When the total
+ * contribution is positive, `Σ micro === floor(poolMicro)` exactly — no dust
+ * created or lost; the rounding remainder goes to the largest fractional shares.
+ * When every contribution is zero (or the list is empty), nothing is allocated
+ * (all `micro === 0`) — there is no basis to weight the pool.
+ */
+export function allocateByContribution(sources, poolMicro) {
+    const weights = sources.map((s) => (s.contribution > 0 ? s.contribution : 0));
+    const total = weights.reduce((a, b) => a + b, 0);
+    if (total <= 0)
+        return sources.map((s) => ({ slug: s.slug, micro: 0, weight: 0 }));
+    const pool = Math.max(0, Math.floor(poolMicro));
+    const exact = weights.map((w) => (pool * w) / total);
+    const micro = exact.map((e) => Math.floor(e));
+    let remainder = pool - micro.reduce((a, b) => a + b, 0);
+    // Largest-remainder apportionment: hand each leftover micro-unit to the source
+    // with the biggest fractional part (tie → larger weight, then lower index, for
+    // determinism). remainder is an integer in [0, sources.length], so this closes
+    // the gap exactly without ever over-distributing.
+    const byFraction = exact
+        .map((e, i) => ({ i, frac: e - Math.floor(e), weight: weights[i] }))
+        .sort((a, b) => b.frac - a.frac || b.weight - a.weight || a.i - b.i);
+    for (let k = 0; remainder > 0 && k < byFraction.length; k++, remainder--) {
+        micro[byFraction[k].i]++;
+    }
+    return sources.map((s, i) => ({ slug: s.slug, micro: micro[i], weight: weights[i] / total }));
+}
+//# sourceMappingURL=allocation.js.map

package/dist/allocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocation.js","sourceRoot":"","sources":["../src/allocation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA0D,EAC1D,SAAiB;IAEjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAEnF,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAExD,+EAA+E;IAC/E,+EAA+E;IAC/E,+EAA+E;IAC/E,kDAAkD;IAClD,MAAM,UAAU,GAAG,KAAK;SACrB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;SACpE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,GAAG,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC;QACzE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAE,CAAC,CAAC,CAAE,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;AAClG,CAAC"}

package/dist/appraise.d.ts

@@ -0,0 +1,3 @@
+import type { PricedCandidate, AppraisedCandidate } from "./types.ts";
+export declare function appraise(topic: string, candidates: PricedCandidate[]): Promise<AppraisedCandidate[]>;
+//# sourceMappingURL=appraise.d.ts.map

package/dist/appraise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appraise.d.ts","sourceRoot":"","sources":["../src/appraise.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAa,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAqDjF,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,eAAe,EAAE,GAC5B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQ/B"}

package/dist/appraise.js

@@ -0,0 +1,60 @@
+/**
+ * Appraisal — estimate how relevant each candidate is to the research topic,
+ * from its free teaser alone. Returns a 0..1 score plus a one-line rationale
+ * that surfaces in the decision log.
+ *
+ * With OPENAI_API_KEY set, an LLM judges relevance. Without it, a keyword-overlap
+ * heuristic stands in, so the agent still makes a real (if blunter) judgement
+ * offline — no network, no key, still decides.
+ */
+import { getConfig } from "@naulon/shared";
+const STOP = new Set([
+    "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with", "is",
+    "are", "what", "how", "why", "about", "into", "we", "i", "it", "its", "that",
+]);
+function tokens(s) {
+    return new Set(s
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOP.has(w)));
+}
+/** Keyword-overlap relevance in [0,1]: matched topic terms / topic terms. */
+function heuristicScore(topic, c) {
+    const topicTerms = tokens(topic);
+    const docTerms = tokens(`${c.title} ${c.summary}`);
+    if (topicTerms.size === 0)
+        return { relevance: 0, rationale: "empty topic" };
+    const hits = [...topicTerms].filter((t) => docTerms.has(t));
+    const relevance = hits.length / topicTerms.size;
+    const rationale = hits.length
+        ? `shares ${hits.length}/${topicTerms.size} topic terms (${hits.join(", ")})`
+        : "no topic-term overlap in the teaser";
+    return { relevance, rationale };
+}
+async function llmScore(topic, c) {
+    try {
+        const { ChatOpenAI } = await import("@langchain/openai");
+        const model = new ChatOpenAI({ model: "gpt-4o-mini", temperature: 0 });
+        const res = await model.invoke(`Topic: "${topic}"\nEssay: "${c.title}" — ${c.summary}\n` +
+            `Rate 0-100 how useful this essay is for the topic, then one short reason. ` +
+            `Reply exactly as: SCORE|reason`);
+        const text = String(res.content);
+        const [scoreStr, ...rest] = text.split("|");
+        const score = Number(scoreStr?.trim());
+        if (!Number.isFinite(score))
+            return null;
+        return { relevance: Math.max(0, Math.min(1, score / 100)), rationale: rest.join("|").trim() };
+    }
+    catch {
+        return null; // any failure → caller falls back to heuristic
+    }
+}
+export async function appraise(topic, candidates) {
+    const useLlm = Boolean(getConfig().OPENAI_API_KEY);
+    return Promise.all(candidates.map(async (c) => {
+        const scored = (useLlm ? await llmScore(topic, c) : null) ?? heuristicScore(topic, c);
+        return { ...c, relevance: scored.relevance, rationale: scored.rationale };
+    }));
+}
+//# sourceMappingURL=appraise.js.map

package/dist/appraise.js.map

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