productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/slackNango.js

@@ -0,0 +1,208 @@
+// Slack through Nango (slack-discovery-connector-v0, local worker mode).
+// Nango is the credential broker only: productfoo asks Nango for the company's Slack
+// token and then talks to Slack's Web API directly. Every surface productfoo owns is
+// content-free: provider errors and metadata only — message text is fetched by
+// the worker through the proof boundary and never persisted outside process
+// memory (R-005). Slack API shapes below are beliefs owned by the packet's
+// feasibility task (T-001) and pinned by fixtures in test/discoverySlack.test.ts;
+// the live dogfood run (T-007) is what would promote them from belief to verified.
+// Contract-only: this adapter makes no verified-live claim.
+import { createHash } from "node:crypto";
+import { SLACK_CHANNEL_ID, refuseSourceWrite, SLACK_SCOPE_LIMITS } from "./sourceIngress.js";
+export class SlackRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SlackRuntimeError";
+    }
+}
+export const SLACK_POLICY = {
+    policy_version: "slack-local-worker-0.1",
+    max_response_bytes: 4 * 1024 * 1024,
+    fetch_timeout_ms: 90_000,
+    max_model_input_tokens: 100_000,
+    max_replies_per_thread: 200,
+    min_request_interval_ms: 1_100,
+    max_channels_probed: SLACK_SCOPE_LIMITS.max_channels_per_scope,
+};
+const DEFAULT_NANGO_HOST = "https://api.nango.dev";
+const DEFAULT_SLACK_BASE = "https://slack.com";
+const SLACK_READ_API = new Set(["conversations.list", "conversations.info", "conversations.history", "conversations.replies"]);
+const SLACK_AUTH_ERRORS = new Set(["not_authed", "invalid_auth", "account_inactive", "token_revoked", "token_expired"]);
+const SLACK_ACCESS_ERRORS = new Set(["missing_scope", "not_in_channel", "not_allowed_type", "method_not_supported_for_channel_type", "access_denied"]);
+export function slackConnectionConfigured(env) {
+    const viaNango = Boolean(env.NANGO_SECRET_KEY?.trim() && env.FOO_SLACK_NANGO_CONNECTION?.trim());
+    const direct = Boolean(env.FOO_SLACK_BOT_TOKEN?.trim());
+    return viaNango || direct;
+}
+export function slackCredentialBroker(env) {
+    if (env.NANGO_SECRET_KEY?.trim() && env.FOO_SLACK_NANGO_CONNECTION?.trim())
+        return "nango";
+    if (env.FOO_SLACK_BOT_TOKEN?.trim())
+        return "direct";
+    return null;
+}
+function opaqueConnectionRef(integration, connectionId) {
+    // Hash, never log, never store the raw connection id in findings provenance.
+    return `slack:${createHash("sha256").update(`${integration}\n${connectionId}`).digest("hex").slice(0, 16)}`;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error.name === "AbortError") {
+            throw new SlackRuntimeError("provider_timeout", "the Slack runtime timed out");
+        }
+        throw new SlackRuntimeError("network", "the Slack runtime could not reach the network");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function readBounded(response, maxBytes) {
+    const declared = response.headers.get("content-length");
+    if (declared && Number(declared) > maxBytes) {
+        throw new SlackRuntimeError("provider_failure", "the provider response exceeded the size ceiling");
+    }
+    const body = await response.text();
+    if (body.length > maxBytes)
+        throw new SlackRuntimeError("provider_failure", "the provider response exceeded the size ceiling");
+    return body;
+}
+function parseJson(raw, what) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new SlackRuntimeError("provider_failure", `${what} returned something that is not JSON`);
+    }
+}
+async function resolveNangoSlackToken(input) {
+    const secret = input.env.NANGO_SECRET_KEY.trim();
+    const connectionId = input.env.FOO_SLACK_NANGO_CONNECTION.trim();
+    const integration = input.env.FOO_SLACK_NANGO_INTEGRATION?.trim() || "slack";
+    const host = (input.env.NANGO_HOST?.trim() || DEFAULT_NANGO_HOST).replace(/\/+$/, "");
+    const url = `${host}/connection/${encodeURIComponent(connectionId)}?provider_config_key=${encodeURIComponent(integration)}`;
+    let response;
+    try {
+        response = await fetchWithTimeout(input.fetchImpl, url, { method: "GET", headers: { authorization: `Bearer ${secret}`, accept: "application/json" } }, SLACK_POLICY.fetch_timeout_ms);
+    }
+    catch (error) {
+        if (error instanceof SlackRuntimeError)
+            throw error;
+        throw new SlackRuntimeError("network", "the Slack runtime could not reach the network");
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new SlackRuntimeError("not_connected", "Nango refused the secret key; check the NANGO_SECRET_KEY for this runtime");
+    }
+    if (response.status === 404) {
+        throw new SlackRuntimeError("not_connected", "Nango has no Slack connection under FOO_SLACK_NANGO_CONNECTION; connect Slack first");
+    }
+    if (!response.ok)
+        throw new SlackRuntimeError("provider_failure", `Nango answered ${response.status} while resolving the Slack connection`);
+    const body = parseJson(await readBounded(response, 256 * 1024), "Nango");
+    const credentials = (body.credentials ?? {});
+    const token = typeof credentials.access_token === "string" ? credentials.access_token : "";
+    if (!token)
+        throw new SlackRuntimeError("not_connected", "the Nango connection carries no usable Slack token; reconnect Slack");
+    return { connection_ref: opaqueConnectionRef(integration, connectionId), broker: "nango", token };
+}
+export async function resolveSlackConnection(input) {
+    const broker = slackCredentialBroker(input.env);
+    if (broker === null) {
+        throw new SlackRuntimeError("not_connected", "Slack is not connected: set NANGO_SECRET_KEY and FOO_SLACK_NANGO_CONNECTION for the company connection through Nango, or FOO_SLACK_BOT_TOKEN for a direct administrator-issued bot token held in this runtime only");
+    }
+    if (broker === "direct") {
+        const token = input.env.FOO_SLACK_BOT_TOKEN.trim();
+        return { connection_ref: `slack:direct:${createHash("sha256").update(token).digest("hex").slice(0, 16)}`, broker: "direct", token };
+    }
+    return resolveNangoSlackToken(input);
+}
+export class SlackClient {
+    requests = { conversations_list: 0, conversations_info: 0, conversations_history: 0, conversations_replies: 0 };
+    connection;
+    options;
+    lastRequestAt = 0;
+    constructor(connection, options = {}) {
+        this.connection = connection;
+        this.options = {
+            fetchImpl: options.fetchImpl ?? globalThis.fetch,
+            baseUrl: (options.baseUrl ?? DEFAULT_SLACK_BASE).replace(/\/+$/, ""),
+            now: options.now ?? (() => Date.now()),
+            sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+            fetchTimeoutMs: options.fetchTimeoutMs ?? SLACK_POLICY.fetch_timeout_ms,
+        };
+    }
+    // V0's read surface is exactly four conversations.* methods. Anything else —
+    // a POST, a chat.* call, an admin.* call — is refused before it leaves productfoo,
+    // so the Slack API can never be mutated from a discovery run.
+    async request(api, params, maxBytes = SLACK_POLICY.max_response_bytes) {
+        if (!SLACK_READ_API.has(api))
+            refuseSourceWrite(`slack ${api}`);
+        const wait = this.lastRequestAt + SLACK_POLICY.min_request_interval_ms - this.options.now();
+        if (wait > 0)
+            await this.options.sleep(wait);
+        this.lastRequestAt = this.options.now();
+        const url = `${this.options.baseUrl}/api/${api}?${new URLSearchParams(params).toString()}`;
+        let response;
+        try {
+            response = await fetchWithTimeout(this.options.fetchImpl, url, { method: "GET", headers: { authorization: `Bearer ${this.connection.token}`, accept: "application/json" } }, this.options.fetchTimeoutMs);
+        }
+        catch (error) {
+            if (error instanceof SlackRuntimeError)
+                throw error;
+            throw new SlackRuntimeError("network", "the Slack runtime could not reach the network");
+        }
+        if (response.status === 401 || response.status === 403)
+            throw new SlackRuntimeError("auth_expired", "Slack rejected the token; refresh or reconnect");
+        if (response.status === 429)
+            throw new SlackRuntimeError("budget_exhausted", "Slack rate limit reached; no retry was attempted");
+        if (!response.ok)
+            throw new SlackRuntimeError("provider_failure", `Slack answered ${response.status}`);
+        const body = parseJson(await readBounded(response, maxBytes), "Slack");
+        if (body.ok !== true) {
+            const error = typeof body.error === "string" ? body.error : "unknown_error";
+            if (SLACK_AUTH_ERRORS.has(error))
+                throw new SlackRuntimeError("auth_expired", "Slack rejected the token; refresh or reconnect");
+            if (SLACK_ACCESS_ERRORS.has(error))
+                throw new SlackRuntimeError("access_denied", "Slack denied this read; the token lacks the required scope or channel access");
+            if (error === "rate_limited")
+                throw new SlackRuntimeError("budget_exhausted", "Slack rate limit reached; no retry was attempted");
+            throw new SlackRuntimeError("provider_failure", "Slack refused the read; the selected channel or thread may no longer exist");
+        }
+        return body;
+    }
+    // Readiness probe: one metadata-only page of channels. Message text is never
+    // requested here.
+    async probeWorkspace() {
+        this.requests.conversations_list += 1;
+        const body = await this.request("conversations.list", { types: "public_channel,private_channel", limit: "200", exclude_archived: "true" }, 1024 * 1024);
+        return { channels: Array.isArray(body.channels) ? body.channels.length : 0 };
+    }
+    // The one content read in V0: the messages of the explicitly selected
+    // thread, one bounded page.
+    async threadReplies(channelId, threadTs) {
+        if (!SLACK_CHANNEL_ID.test(channelId))
+            throw new SlackRuntimeError("provider_failure", "a single well-formed channel identifier is required");
+        if (!/^\d{10}\.\d{6}$/.test(threadTs))
+            throw new SlackRuntimeError("provider_failure", "a single well-formed thread timestamp is required");
+        this.requests.conversations_replies += 1;
+        const body = await this.request("conversations.replies", { channel: channelId, ts: threadTs, limit: String(SLACK_POLICY.max_replies_per_thread) });
+        const rawMessages = Array.isArray(body.messages) ? body.messages : [];
+        const messages = rawMessages.map((message) => {
+            const record = (message ?? {});
+            return {
+                ts: typeof record.ts === "string" ? record.ts : undefined,
+                user: typeof record.user === "string" ? record.user : undefined,
+                bot_id: typeof record.bot_id === "string" ? record.bot_id : undefined,
+                subtype: typeof record.subtype === "string" ? record.subtype : undefined,
+                text: typeof record.text === "string" ? record.text : undefined,
+            };
+        });
+        return { messages, has_more: body.has_more === true };
+    }
+}

package/dist-public/src/social/arxiv.d.ts

@@ -0,0 +1,19 @@
+import type { AdapterOptions, AdapterResult } from "./types.js";
+/**
+ * Build arXiv's `search_query`, AND-joined.
+ *
+ * This exists because arXiv **silently rewrites bare spaces into OR**. productfoo used to
+ * send `all:kubernetes operator patterns` and arXiv answered — in its own echoed
+ * query — `all:kubernetes OR all:operator OR all:patterns`. "Operator" is one of the
+ * most common words in mathematics, so a Kubernetes question returned quantum
+ * information theory, and a query of pure gibberish returned 25 papers. Those became
+ * "findings", eligible to be typed as evidence in a research paper.
+ *
+ * That is fabricated evidence, and it is the worst thing a research tool can do —
+ * worse than returning nothing, because nothing is honest.
+ *
+ * AND-joining makes the query mean what it says. A topic with no recent literature
+ * now correctly returns zero.
+ */
+export declare function buildArxivQuery(query: string): string;
+export declare function fetchArxiv(query: string, opts?: AdapterOptions): Promise<AdapterResult>;

package/dist-public/src/social/arxiv.js

@@ -0,0 +1,96 @@
+// arXiv adapter — the public query API (export.arxiv.org), keyless, Atom XML.
+// Ranked by relevance to the query (arXiv's own `sortBy=relevance`): a candidate
+// pool is fetched, then the recency window is a post-filter. Newest-first was the
+// bug — it returned the most-recent papers matching the AND-terms, which are
+// often tangential, so a topical query came back as noise. arXiv carries no
+// engagement signal, so `score` is null.
+import { resolveOptions, settleStatus, withinWindow } from "./types.js";
+import { parseAtomEntries } from "./xml.js";
+const QUERY_URL = "https://export.arxiv.org/api/query";
+// Words that carry no topical signal. Left in an AND-chain they only cost recall:
+// "the" appears in every paper, so ANDing it is free, but "vs"/"using" are noise
+// that a title match should not have to satisfy.
+const STOPWORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "how", "in",
+    "is", "of", "on", "or", "the", "to", "vs", "with", "what", "why", "using",
+]);
+/**
+ * Build arXiv's `search_query`, AND-joined.
+ *
+ * This exists because arXiv **silently rewrites bare spaces into OR**. productfoo used to
+ * send `all:kubernetes operator patterns` and arXiv answered — in its own echoed
+ * query — `all:kubernetes OR all:operator OR all:patterns`. "Operator" is one of the
+ * most common words in mathematics, so a Kubernetes question returned quantum
+ * information theory, and a query of pure gibberish returned 25 papers. Those became
+ * "findings", eligible to be typed as evidence in a research paper.
+ *
+ * That is fabricated evidence, and it is the worst thing a research tool can do —
+ * worse than returning nothing, because nothing is honest.
+ *
+ * AND-joining makes the query mean what it says. A topic with no recent literature
+ * now correctly returns zero.
+ */
+export function buildArxivQuery(query) {
+    const terms = query
+        .toLowerCase()
+        .split(/[^a-z0-9+#.]+/i)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t));
+    // Nothing usable left (punctuation, or all stopwords): fall back to the raw
+    // phrase, quoted. Quoting is what stops arXiv reading spaces as OR.
+    if (terms.length === 0)
+        return `all:"${query.replace(/"/g, "")}"`;
+    return terms.map((t) => `all:${t}`).join(" AND ");
+}
+export async function fetchArxiv(query, opts = {}) {
+    const { days, limit, now, fetchImpl, signal } = resolveOptions(opts);
+    // Fetch a relevance-ranked candidate pool, then keep only the recent ones. The
+    // pool is larger than `limit` so the window post-filter has relevant papers to
+    // keep rather than only the newest `limit` results.
+    const pool = Math.max(limit, 50);
+    const url = `${QUERY_URL}?search_query=${encodeURIComponent(buildArxivQuery(query))}` +
+        `&sortBy=relevance&sortOrder=descending&max_results=${pool}`;
+    try {
+        const res = await fetchImpl(url, { headers: { Accept: "application/atom+xml" }, signal });
+        if (!res.ok) {
+            return {
+                source: "arxiv",
+                status: "excluded",
+                reason: `arXiv query API returned HTTP ${res.status}.`,
+                items: [],
+            };
+        }
+        const xml = await res.text();
+        const items = parseAtomEntries(xml)
+            .map((e) => {
+            if (!e.title || !e.id)
+                return null;
+            return {
+                source: "arxiv",
+                id: `arxiv:${e.id}`,
+                title: e.title.replace(/\s+/g, " ").trim(),
+                url: e.link ?? e.id,
+                author: e.author,
+                createdAt: e.published ?? new Date(0).toISOString(),
+                score: null,
+                snippet: e.summary ? e.summary.replace(/\s+/g, " ").slice(0, 280) : null,
+            };
+        })
+            .filter((it) => it !== null)
+            .filter((it) => withinWindow(it.createdAt, now, days))
+            .slice(0, limit);
+        return {
+            source: "arxiv",
+            status: settleStatus("available", items.length),
+            reason: `arXiv returned ${items.length} paper(s) within ${days}d.`,
+            items,
+        };
+    }
+    catch (err) {
+        return {
+            source: "arxiv",
+            status: "excluded",
+            reason: `arXiv fetch failed: ${err.message}`,
+            items: [],
+        };
+    }
+}

package/dist-public/src/social/github.d.ts

@@ -0,0 +1,2 @@
+import type { AdapterOptions, AdapterResult } from "./types.js";
+export declare function fetchGitHub(query: string, opts?: AdapterOptions): Promise<AdapterResult>;

package/dist-public/src/social/github.js

@@ -0,0 +1,78 @@
+// GitHub adapter — the public search/issues API. Works unauthenticated (the
+// free default); an optional GITHUB_TOKEN only raises the rate limit, so it
+// stays a free-tier source (D-004). Unauth search is rate-limited to ~10 req/min
+// and answers 403 when throttled — that degrades honestly with an upsell to set
+// a token, never crashes.
+import { resolveOptions, settleStatus, windowStartMs, withinWindow } from "./types.js";
+const SEARCH_URL = "https://api.github.com/search/issues";
+export async function fetchGitHub(query, opts = {}) {
+    const { days, limit, now, fetchImpl, githubToken, signal } = resolveOptions(opts);
+    const sinceDate = new Date(windowStartMs(now, days)).toISOString().slice(0, 10);
+    const q = `${query} created:>=${sinceDate}`;
+    const url = `${SEARCH_URL}?q=${encodeURIComponent(q)}` +
+        `&sort=updated&order=desc&per_page=${limit}`;
+    const headers = {
+        Accept: "application/vnd.github+json",
+        // GitHub rejects API requests without a User-Agent.
+        "User-Agent": "foo-research",
+    };
+    if (githubToken)
+        headers.Authorization = `Bearer ${githubToken}`;
+    try {
+        const res = await fetchImpl(url, { headers, signal });
+        if (res.status === 403 || res.status === 429) {
+            return {
+                source: "github",
+                status: "degraded",
+                reason: githubToken
+                    ? `GitHub search rate-limited (HTTP ${res.status}) despite a token.`
+                    : `GitHub search rate-limited (HTTP ${res.status}); set GITHUB_TOKEN to raise the free limit.`,
+                items: [],
+            };
+        }
+        if (!res.ok) {
+            return {
+                source: "github",
+                status: "excluded",
+                reason: `GitHub search returned HTTP ${res.status}.`,
+                items: [],
+            };
+        }
+        const body = (await res.json());
+        const issues = Array.isArray(body.items) ? body.items : [];
+        const items = issues
+            .map((issue) => {
+            if (issue.id == null || !issue.title || !issue.html_url || !issue.created_at)
+                return null;
+            const comments = typeof issue.comments === "number" ? issue.comments : 0;
+            const reactions = typeof issue.reactions?.total_count === "number" ? issue.reactions.total_count : 0;
+            return {
+                source: "github",
+                id: `github:${issue.id}`,
+                title: issue.title,
+                url: issue.html_url,
+                author: issue.user?.login ?? null,
+                createdAt: issue.created_at,
+                score: comments + reactions,
+                snippet: null,
+            };
+        })
+            .filter((it) => it !== null)
+            .filter((it) => withinWindow(it.createdAt, now, days))
+            .slice(0, limit);
+        return {
+            source: "github",
+            status: settleStatus("available", items.length),
+            reason: `GitHub returned ${items.length} issue/PR(s) within ${days}d${githubToken ? " (authenticated)" : " (unauthenticated)"}.`,
+            items,
+        };
+    }
+    catch (err) {
+        return {
+            source: "github",
+            status: "excluded",
+            reason: `GitHub fetch failed: ${err.message}`,
+            items: [],
+        };
+    }
+}

package/dist-public/src/social/hackernews.d.ts

@@ -0,0 +1,2 @@
+import type { AdapterOptions, AdapterResult } from "./types.js";
+export declare function fetchHackerNews(query: string, opts?: AdapterOptions): Promise<AdapterResult>;

package/dist-public/src/social/hackernews.js

@@ -0,0 +1,67 @@
+// Hacker News adapter — the cleanest keyless source. Uses the public Algolia
+// search API (hn.algolia.com/api/v1), no key, no cookies. Uses `search`
+// (relevance-ranked), not `search_by_date` (newest-first): a recency-only sort
+// returned the newest stories that mentioned the terms rather than the ones
+// actually about the topic. The recency window stays as a server-side numeric
+// filter plus a post-filter for safety.
+import { resolveOptions, settleStatus, windowStartMs, withinWindow } from "./types.js";
+const SEARCH = "https://hn.algolia.com/api/v1/search";
+function toItem(hit) {
+    if (!hit.objectID || !hit.title || !hit.created_at)
+        return null;
+    const points = typeof hit.points === "number" ? hit.points : 0;
+    const comments = typeof hit.num_comments === "number" ? hit.num_comments : 0;
+    return {
+        source: "hackernews",
+        id: `hn:${hit.objectID}`,
+        title: hit.title,
+        url: hit.url || `https://news.ycombinator.com/item?id=${hit.objectID}`,
+        author: hit.author ?? null,
+        createdAt: hit.created_at,
+        // Engagement = upvotes plus discussion; both are real signal on HN.
+        score: points + comments,
+        snippet: hit.story_text ? hit.story_text.slice(0, 280) : null,
+    };
+}
+export async function fetchHackerNews(query, opts = {}) {
+    const { days, limit, now, fetchImpl, signal } = resolveOptions(opts);
+    const sinceSec = Math.floor(windowStartMs(now, days) / 1000);
+    // Relevance-ranked within the window; fetch a pool larger than `limit` so the
+    // post-filter and slice keep the most relevant in-window stories, not the first
+    // `limit` the API happened to return.
+    const pool = Math.max(limit, 50);
+    const url = `${SEARCH}?query=${encodeURIComponent(query)}` +
+        `&tags=story&numericFilters=created_at_i>=${sinceSec}&hitsPerPage=${pool}`;
+    try {
+        const res = await fetchImpl(url, { headers: { Accept: "application/json" }, signal });
+        if (!res.ok) {
+            return {
+                source: "hackernews",
+                status: "excluded",
+                reason: `HN Algolia returned HTTP ${res.status}.`,
+                items: [],
+            };
+        }
+        const body = (await res.json());
+        const hits = Array.isArray(body.hits) ? body.hits : [];
+        const items = hits
+            .map(toItem)
+            .filter((it) => it !== null)
+            .filter((it) => withinWindow(it.createdAt, now, days))
+            .slice(0, limit);
+        return {
+            source: "hackernews",
+            status: settleStatus("available", items.length),
+            reason: `HN Algolia returned ${items.length} story(ies) within ${days}d.`,
+            items,
+        };
+    }
+    catch (err) {
+        return {
+            source: "hackernews",
+            status: "excluded",
+            reason: `HN Algolia fetch failed: ${err.message}`,
+            items: [],
+        };
+    }
+}

package/dist-public/src/social/index.d.ts

@@ -0,0 +1,10 @@
+import type { AdapterOptions, AdapterResult, SocialItem, SocialSource } from "./types.js";
+export declare const DEFAULT_SOURCES: SocialSource[];
+export interface GatherResult {
+    items: SocialItem[];
+    reports: AdapterResult[];
+}
+export declare function dedupe(items: SocialItem[]): SocialItem[];
+export declare function gatherSocial(query: string, opts?: AdapterOptions & {
+    sources?: SocialSource[];
+}): Promise<GatherResult>;

package/dist-public/src/social/index.js

@@ -0,0 +1,79 @@
+// Social adapter orchestrator — runs the enabled keyless adapters, merges and
+// dedupes their evidence, and returns both the items and honest per-source
+// reports (R-001). The spine (research.ts) reports the `social` class; this is
+// the gather step the agent runs to populate it.
+import { fetchArxiv } from "./arxiv.js";
+import { fetchGitHub } from "./github.js";
+import { fetchHackerNews } from "./hackernews.js";
+import { fetchReddit } from "./reddit.js";
+import { fetchYouTube } from "./youtube.js";
+// V0 sources (D-002). Reddit/HN/arXiv/GitHub are keyless HTTP; YouTube is keyless
+// via the yt-dlp binary (degrades if absent). X and the paid tier are V1 (D-006).
+export const DEFAULT_SOURCES = [
+    "reddit",
+    "hackernews",
+    "arxiv",
+    "github",
+    "youtube",
+];
+// Registry of implemented adapters. Requesting a source not present here yields
+// an honest `excluded` report rather than a silent drop.
+const ADAPTERS = {
+    reddit: fetchReddit,
+    hackernews: fetchHackerNews,
+    arxiv: fetchArxiv,
+    github: fetchGitHub,
+    youtube: fetchYouTube,
+};
+// Dedupe by stable id first, then collapse cross-source near-duplicates that
+// point at the same URL, keeping the higher-scored copy so engagement signal
+// survives the merge.
+export function dedupe(items) {
+    const byId = new Map();
+    for (const it of items) {
+        if (!byId.has(it.id))
+            byId.set(it.id, it);
+    }
+    const byUrl = new Map();
+    for (const it of byId.values()) {
+        const key = normalizeUrl(it.url);
+        const existing = byUrl.get(key);
+        if (!existing || (it.score ?? -1) > (existing.score ?? -1)) {
+            byUrl.set(key, it);
+        }
+    }
+    return [...byUrl.values()];
+}
+function normalizeUrl(url) {
+    try {
+        const u = new URL(url);
+        // Drop trailing slash + tracking-ish query noise for a stable dedupe key.
+        return `${u.hostname.replace(/^www\./, "")}${u.pathname.replace(/\/$/, "")}`.toLowerCase();
+    }
+    catch {
+        return url.toLowerCase();
+    }
+}
+export async function gatherSocial(query, opts = {}) {
+    const sources = opts.sources ?? DEFAULT_SOURCES;
+    const reports = await Promise.all(sources.map((source) => {
+        const adapter = ADAPTERS[source];
+        if (!adapter) {
+            return Promise.resolve({
+                source,
+                status: "excluded",
+                reason: `${source} adapter not yet implemented in this build.`,
+                items: [],
+            });
+        }
+        return adapter(query, opts);
+    }));
+    // "It ran" and "it found something" are different facts, and a research tool
+    // exists to keep them apart. An adapter that returns zero items has not
+    // contributed evidence, whatever it thinks its status is — so the honest zero is
+    // enforced here, once, rather than trusted to each adapter. `degraded` and
+    // `excluded` already carry their own reason and are left alone.
+    const honest = reports.map((r) => r.status === "available" && r.items.length === 0 ? { ...r, status: "empty" } : r);
+    const items = dedupe(honest.flatMap((r) => r.items)).sort((a, b) => (b.score ?? -1) - (a.score ?? -1));
+    return { items, reports: honest };
+}

package/dist-public/src/social/reddit.d.ts

@@ -0,0 +1,2 @@
+import type { AdapterOptions, AdapterResult } from "./types.js";
+export declare function fetchReddit(query: string, opts?: AdapterOptions): Promise<AdapterResult>;