@tangle-network/agent-knowledge 6.0.0 → 6.1.0

package/dist/search-CP0QtBJZ.js

@@ -0,0 +1,113 @@
+//#region src/search.ts
+const RRF_K = 60;
+const STOP_WORDS = /* @__PURE__ */ new Set([
+	"the",
+	"is",
+	"a",
+	"an",
+	"what",
+	"how",
+	"are",
+	"was",
+	"were",
+	"to",
+	"for",
+	"of",
+	"with",
+	"by",
+	"in",
+	"on",
+	"and"
+]);
+function searchKnowledge(index, query, limit = 10) {
+	const trimmed = query.trim();
+	if (trimmed === "") return [];
+	const tokenRanked = rankByTokens(index.pages, trimmed);
+	const graphRanked = rankByGraph(index.pages, tokenRanked);
+	const scores = reciprocalRankFusion([tokenRanked.map((p) => p.id), graphRanked.map((p) => p.id)]);
+	const byId = new Map(index.pages.map((page) => [page.id, page]));
+	const ranked = [...scores.entries()].map(([id, score]) => ({
+		page: byId.get(id),
+		score
+	})).filter((item) => Boolean(item.page)).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
+	const topScore = ranked[0]?.score ?? 0;
+	return ranked.map((item, i) => ({
+		page: item.page,
+		score: item.score,
+		rrfScore: item.score,
+		normalizedScore: topScore > 0 ? item.score / topScore : 0,
+		rank: i + 1,
+		snippet: buildSnippet(item.page.text, trimmed),
+		reasons: reasonsFor(item.page, trimmed)
+	}));
+}
+function tokenizeQuery(query) {
+	const raw = query.toLowerCase().split(/[\s,，。！？、；：""''（）()\-_/\\·~～…]+/).filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+	const tokens = [];
+	for (const token of raw) {
+		if (/[\u4e00-\u9fff\u3400-\u4dbf]/.test(token) && token.length > 2) {
+			const chars = [...token];
+			for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i] + chars[i + 1]);
+			tokens.push(...chars);
+		}
+		tokens.push(token);
+	}
+	return [...new Set(tokens)];
+}
+function reciprocalRankFusion(rankLists, k = RRF_K) {
+	const scores = /* @__PURE__ */ new Map();
+	for (const list of rankLists) list.forEach((id, idx) => {
+		scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1));
+	});
+	return scores;
+}
+function rankByTokens(pages, query) {
+	const tokens = tokenizeQuery(query);
+	const effective = tokens.length > 0 ? tokens : [query.toLowerCase()];
+	return pages.map((page) => ({
+		page,
+		score: tokenScore(page, query, effective)
+	})).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
+}
+function rankByGraph(pages, tokenRanked) {
+	if (tokenRanked.length === 0) return [];
+	const seeds = new Set(tokenRanked.slice(0, 5).map((page) => page.id));
+	return pages.map((page) => ({
+		page,
+		score: page.outLinks.filter((link) => seeds.has(link)).length + page.sourceIds.filter((source) => tokenRanked.some((seed) => seed.sourceIds.includes(source))).length
+	})).filter((item) => item.score > 0).sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path)).map((item) => item.page);
+}
+function tokenScore(page, query, tokens) {
+	const title = page.title.toLowerCase();
+	const path = page.path.toLowerCase();
+	const body = page.text.toLowerCase();
+	const phrase = query.toLowerCase();
+	let score = 0;
+	if (path.endsWith(`${phrase}.md`) || title === phrase) score += 200;
+	if (title.includes(phrase)) score += 50;
+	if (body.includes(phrase)) score += 20;
+	for (const token of tokens) {
+		if (title.includes(token)) score += 5;
+		if (body.includes(token)) score += 1;
+		if (path.includes(token)) score += 3;
+	}
+	return score;
+}
+function buildSnippet(text, query) {
+	const compact = text.replace(/\s+/g, " ").trim();
+	const idx = compact.toLowerCase().indexOf(query.toLowerCase());
+	if (idx < 0) return compact.slice(0, 180);
+	return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100));
+}
+function reasonsFor(page, query) {
+	const lower = `${page.title}\n${page.text}`.toLowerCase();
+	const reasons = [];
+	if (lower.includes(query.toLowerCase())) reasons.push("phrase");
+	if (page.sourceIds.length > 0) reasons.push("sourced");
+	if (page.outLinks.length > 0) reasons.push("linked");
+	return reasons;
+}
+//#endregion
+export { searchKnowledge as n, tokenizeQuery as r, reciprocalRankFusion as t };
+
+//# sourceMappingURL=search-CP0QtBJZ.js.map

package/dist/search-CP0QtBJZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-CP0QtBJZ.js","names":[],"sources":["../src/search.ts"],"sourcesContent":["import type { KnowledgeIndex, KnowledgePage, KnowledgeSearchResult } from './types'\n\nconst RRF_K = 60\nconst STOP_WORDS = new Set([\n  'the',\n  'is',\n  'a',\n  'an',\n  'what',\n  'how',\n  'are',\n  'was',\n  'were',\n  'to',\n  'for',\n  'of',\n  'with',\n  'by',\n  'in',\n  'on',\n  'and',\n])\n\nexport function searchKnowledge(\n  index: KnowledgeIndex,\n  query: string,\n  limit = 10,\n): KnowledgeSearchResult[] {\n  const trimmed = query.trim()\n  if (trimmed === '') return []\n  const tokenRanked = rankByTokens(index.pages, trimmed)\n  const graphRanked = rankByGraph(index.pages, tokenRanked)\n  const scores = reciprocalRankFusion([tokenRanked.map((p) => p.id), graphRanked.map((p) => p.id)])\n  const byId = new Map(index.pages.map((page) => [page.id, page]))\n\n  const ranked = [...scores.entries()]\n    .map(([id, score]) => ({ page: byId.get(id), score }))\n    .filter((item): item is { page: KnowledgePage; score: number } => Boolean(item.page))\n    .sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path))\n    .slice(0, limit)\n\n  // Normalize against the top hit so callers can compare against natural\n  // [0, 1] thresholds. Raw RRF values are typically ~0.016, which reads as\n  // \"no relevance\" to humans even when the result is the best available.\n  // The top hit becomes 1 by definition; lower-ranked hits scale linearly.\n  const topScore = ranked[0]?.score ?? 0\n\n  return ranked.map((item, i) => ({\n    page: item.page,\n    score: item.score,\n    rrfScore: item.score,\n    normalizedScore: topScore > 0 ? item.score / topScore : 0,\n    rank: i + 1,\n    snippet: buildSnippet(item.page.text, trimmed),\n    reasons: reasonsFor(item.page, trimmed),\n  }))\n}\n\nexport function tokenizeQuery(query: string): string[] {\n  const raw = query\n    .toLowerCase()\n    .split(/[\\s,，。！？、；：\"\"''（）()\\-_/\\\\·~～…]+/)\n    .filter((token) => token.length > 1 && !STOP_WORDS.has(token))\n  const tokens: string[] = []\n  for (const token of raw) {\n    if (/[\\u4e00-\\u9fff\\u3400-\\u4dbf]/.test(token) && token.length > 2) {\n      const chars = [...token]\n      for (let i = 0; i < chars.length - 1; i++) tokens.push(chars[i]! + chars[i + 1]!)\n      tokens.push(...chars)\n    }\n    tokens.push(token)\n  }\n  return [...new Set(tokens)]\n}\n\nexport function reciprocalRankFusion(rankLists: string[][], k = RRF_K): Map<string, number> {\n  const scores = new Map<string, number>()\n  for (const list of rankLists) {\n    list.forEach((id, idx) => {\n      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + idx + 1))\n    })\n  }\n  return scores\n}\n\nfunction rankByTokens(pages: KnowledgePage[], query: string): KnowledgePage[] {\n  const tokens = tokenizeQuery(query)\n  const effective = tokens.length > 0 ? tokens : [query.toLowerCase()]\n  return pages\n    .map((page) => ({ page, score: tokenScore(page, query, effective) }))\n    .filter((item) => item.score > 0)\n    .sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path))\n    .map((item) => item.page)\n}\n\nfunction rankByGraph(pages: KnowledgePage[], tokenRanked: KnowledgePage[]): KnowledgePage[] {\n  if (tokenRanked.length === 0) return []\n  const seeds = new Set(tokenRanked.slice(0, 5).map((page) => page.id))\n  return pages\n    .map((page) => ({\n      page,\n      score:\n        page.outLinks.filter((link) => seeds.has(link)).length +\n        page.sourceIds.filter((source) =>\n          tokenRanked.some((seed) => seed.sourceIds.includes(source)),\n        ).length,\n    }))\n    .filter((item) => item.score > 0)\n    .sort((a, b) => b.score - a.score || a.page.path.localeCompare(b.page.path))\n    .map((item) => item.page)\n}\n\nfunction tokenScore(page: KnowledgePage, query: string, tokens: string[]): number {\n  const title = page.title.toLowerCase()\n  const path = page.path.toLowerCase()\n  const body = page.text.toLowerCase()\n  const phrase = query.toLowerCase()\n  let score = 0\n  if (path.endsWith(`${phrase}.md`) || title === phrase) score += 200\n  if (title.includes(phrase)) score += 50\n  if (body.includes(phrase)) score += 20\n  for (const token of tokens) {\n    if (title.includes(token)) score += 5\n    if (body.includes(token)) score += 1\n    if (path.includes(token)) score += 3\n  }\n  return score\n}\n\nfunction buildSnippet(text: string, query: string): string {\n  const compact = text.replace(/\\s+/g, ' ').trim()\n  const idx = compact.toLowerCase().indexOf(query.toLowerCase())\n  if (idx < 0) return compact.slice(0, 180)\n  return compact.slice(Math.max(0, idx - 80), Math.min(compact.length, idx + query.length + 100))\n}\n\nfunction reasonsFor(page: KnowledgePage, query: string): string[] {\n  const lower = `${page.title}\\n${page.text}`.toLowerCase()\n  const reasons: string[] = []\n  if (lower.includes(query.toLowerCase())) reasons.push('phrase')\n  if (page.sourceIds.length > 0) reasons.push('sourced')\n  if (page.outLinks.length > 0) reasons.push('linked')\n  return reasons\n}\n"],"mappings":"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"}

package/dist/sources/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/sources/types.d.ts
 /**
  * Pluggable knowledge source contract.
  *
@@ -30,27 +31,27 @@
  * injected for deterministic tests of change-detection windows.
  */
 interface FetchOpts {
-    /** Abort signal forwarded to the underlying HTTP fetcher. */
-    signal?: AbortSignal;
-    /** Absolute path under which the source may cache raw bytes. */
-    cacheDir?: string;
-    /** Clock injection for deterministic tests. */
-    now?: () => Date;
-    /**
-     * Maximum number of authority pages the source should fetch in this call.
-     * Sources MUST respect this bound — exhaustively crawling Cornell LII on
-     * every cron tick would be both rude and slow. Default is source-specific.
-     */
-    limit?: number;
-    /**
-     * Source-specific selector string. Examples:
-     *   - cornell-lii: `'uscode/text/18/1836'` or `'wex/non-compete'`
-     *   - irs-publications: `'index'` or `'p15'`
-     *   - state-sos: opaque, see `StateSosSourceConfig`
-     *
-     * Sources that don't need a selector ignore this field.
-     */
-    selector?: string;
+  /** Abort signal forwarded to the underlying HTTP fetcher. */
+  signal?: AbortSignal;
+  /** Absolute path under which the source may cache raw bytes. */
+  cacheDir?: string;
+  /** Clock injection for deterministic tests. */
+  now?: () => Date;
+  /**
+   * Maximum number of authority pages the source should fetch in this call.
+   * Sources MUST respect this bound — exhaustively crawling Cornell LII on
+   * every cron tick would be both rude and slow. Default is source-specific.
+   */
+  limit?: number;
+  /**
+   * Source-specific selector string. Examples:
+   *   - cornell-lii: `'uscode/text/18/1836'` or `'wex/non-compete'`
+   *   - irs-publications: `'index'` or `'p15'`
+   *   - state-sos: opaque, see `StateSosSourceConfig`
+   *
+   * Sources that don't need a selector ignore this field.
+   */
+  selector?: string;
 }
 /**
  * The standard provenance shape every fragment carries. Kept separate from
@@ -58,68 +59,68 @@ interface FetchOpts {
  * also dragging the body text.
  */
 interface FragmentProvenance {
-    /** Canonical URL the fragment was extracted from. */
-    url: string;
-    /**
-     * Source-attested timestamp: the time the AUTHORITY last updated this
-     * content, as reported by the source (Last-Modified header, in-page
-     * effective date, registry generated-at, etc). Falls back to the fetch
-     * time only when the authority publishes no timestamp.
-     */
-    sourceUpdatedAt: string;
-    /** ISO timestamp the fragment was fetched. */
-    fetchedAt: string;
-    /**
-     * Jurisdiction the content is binding within, if applicable. Use ISO
-     * country code, US state abbreviation, or 'US-FED' for federal scope.
-     * Statute sources MUST populate this; reference / encyclopedia sources
-     * MAY leave it undefined.
-     */
-    jurisdiction?: string;
-    /**
-     * True iff the configured URL returned an acceptable response and the
-     * expected content was extracted. False on a block page, rate-limit
-     * response, 4xx/5xx, or selector miss. This is not publisher authentication
-     * or cryptographic content verification. Consumers MUST refuse to promote
-     * `verifiable: false` fragments into citable knowledge.
-     */
-    verifiable: boolean;
-    /** If `verifiable === false`, the reason — surfaced to operators. */
-    unverifiableReason?: string;
+  /** Canonical URL the fragment was extracted from. */
+  url: string;
+  /**
+   * Source-attested timestamp: the time the AUTHORITY last updated this
+   * content, as reported by the source (Last-Modified header, in-page
+   * effective date, registry generated-at, etc). Falls back to the fetch
+   * time only when the authority publishes no timestamp.
+   */
+  sourceUpdatedAt: string;
+  /** ISO timestamp the fragment was fetched. */
+  fetchedAt: string;
+  /**
+   * Jurisdiction the content is binding within, if applicable. Use ISO
+   * country code, US state abbreviation, or 'US-FED' for federal scope.
+   * Statute sources MUST populate this; reference / encyclopedia sources
+   * MAY leave it undefined.
+   */
+  jurisdiction?: string;
+  /**
+   * True iff the configured URL returned an acceptable response and the
+   * expected content was extracted. False on a block page, rate-limit
+   * response, 4xx/5xx, or selector miss. This is not publisher authentication
+   * or cryptographic content verification. Consumers MUST refuse to promote
+   * `verifiable: false` fragments into citable knowledge.
+   */
+  verifiable: boolean;
+  /** If `verifiable === false`, the reason — surfaced to operators. */
+  unverifiableReason?: string;
 }
 /**
  * One unit of authoritative content. Stable hash on `(id, body)` lets change
  * detection reason about identity across snapshots.
  */
 interface KnowledgeFragment {
-    /**
-     * Stable identity within (sourceId, selector-space). Two fetches against
-     * the same authority section MUST produce the same `id`. The (sourceId,
-     * id) pair is the primary key for change detection.
-     */
-    id: string;
-    /** Free-form title — section heading, publication name, etc. */
-    title: string;
-    /** Body text, normalised: no HTML tags, line breaks preserved. */
-    body: string;
-    /** SHA-256 of `body`. Pre-computed so consumers don't re-hash on diff. */
-    bodyHash: string;
-    provenance: FragmentProvenance;
-    /**
-     * Eval dimensions an agent-eval campaign should re-score when this
-     * fragment changes. Examples: `citation_hygiene`, `jurisdictional_accuracy`,
-     * `tax_compliance`, `regulatory_currency`. The eval cron treats this as a
-     * set, not a contract — adding a new dimension is non-breaking.
-     *
-     * This is the load-bearing field for the continuous-ingestion story: a
-     * Ryan-LLC-style ruling vacates the FTC non-compete rule → the source
-     * returns a fragment with `jurisdictional_accuracy` in this list →
-     * `detectChanges()` emits a `KnowledgeChange` carrying that hint → the
-     * cron knows exactly which agent-eval campaigns to re-run.
-     */
-    dimensionHints: string[];
-    /** Arbitrary source-specific metadata for debugging / connector wiring. */
-    metadata?: Record<string, unknown>;
+  /**
+   * Stable identity within (sourceId, selector-space). Two fetches against
+   * the same authority section MUST produce the same `id`. The (sourceId,
+   * id) pair is the primary key for change detection.
+   */
+  id: string;
+  /** Free-form title — section heading, publication name, etc. */
+  title: string;
+  /** Body text, normalised: no HTML tags, line breaks preserved. */
+  body: string;
+  /** SHA-256 of `body`. Pre-computed so consumers don't re-hash on diff. */
+  bodyHash: string;
+  provenance: FragmentProvenance;
+  /**
+   * Eval dimensions an agent-eval campaign should re-score when this
+   * fragment changes. Examples: `citation_hygiene`, `jurisdictional_accuracy`,
+   * `tax_compliance`, `regulatory_currency`. The eval cron treats this as a
+   * set, not a contract — adding a new dimension is non-breaking.
+   *
+   * This is the load-bearing field for the continuous-ingestion story: a
+   * Ryan-LLC-style ruling vacates the FTC non-compete rule → the source
+   * returns a fragment with `jurisdictional_accuracy` in this list →
+   * `detectChanges()` emits a `KnowledgeChange` carrying that hint → the
+   * cron knows exactly which agent-eval campaigns to re-run.
+   */
+  dimensionHints: string[];
+  /** Arbitrary source-specific metadata for debugging / connector wiring. */
+  metadata?: Record<string, unknown>;
 }
 /**
  * One pluggable knowledge source.
@@ -130,48 +131,49 @@ interface KnowledgeFragment {
  * the per-tenant isolation contract; see README).
  */
 interface KnowledgeSource {
-    /** Stable id — used to key freshness state. MUST NOT change once shipped. */
-    id: string;
-    /** Human-readable name for dashboards. */
-    name: string;
-    /** One-sentence description: what authority + scope. */
-    description: string;
-    /**
-     * Pull fragments for this source. Sources MUST:
-     *   - rate-limit themselves (>=1 req/sec per source by convention)
-     *   - send a polite User-Agent
-     *   - cache to disk when `opts.cacheDir` is set
-     *   - mark `verifiable: false` rather than throwing on parse/block
-     *   - honour `opts.signal`
-     *   - honour `opts.limit`
-     */
-    fetch(opts: FetchOpts): Promise<KnowledgeFragment[]>;
+  /** Stable id — used to key freshness state. MUST NOT change once shipped. */
+  id: string;
+  /** Human-readable name for dashboards. */
+  name: string;
+  /** One-sentence description: what authority + scope. */
+  description: string;
+  /**
+   * Pull fragments for this source. Sources MUST:
+   *   - rate-limit themselves (>=1 req/sec per source by convention)
+   *   - send a polite User-Agent
+   *   - cache to disk when `opts.cacheDir` is set
+   *   - mark `verifiable: false` rather than throwing on parse/block
+   *   - honour `opts.signal`
+   *   - honour `opts.limit`
+   */
+  fetch(opts: FetchOpts): Promise<KnowledgeFragment[]>;
 }
-
+//#endregion
+//#region src/sources/cornell-lii.d.ts
 interface CornellLiiSelector {
-    /** Either 'uscode' or 'wex'. */
-    kind: 'uscode' | 'wex';
-    /**
-     * For `uscode`: `<title>/<section>` (e.g. `'18/1836'` for DTSA).
-     * For `wex`: the slug (e.g. `'non-compete'`).
-     */
-    path: string;
-    /**
-     * Optional pre-declared eval dimensions affected by this section. If
-     * omitted, defaults are chosen from `kind` + path heuristics.
-     */
-    dimensionHints?: string[];
+  /** Either 'uscode' or 'wex'. */
+  kind: 'uscode' | 'wex';
+  /**
+   * For `uscode`: `<title>/<section>` (e.g. `'18/1836'` for DTSA).
+   * For `wex`: the slug (e.g. `'non-compete'`).
+   */
+  path: string;
+  /**
+   * Optional pre-declared eval dimensions affected by this section. If
+   * omitted, defaults are chosen from `kind` + path heuristics.
+   */
+  dimensionHints?: string[];
 }
 interface CornellLiiSourceOptions {
-    /**
-     * Selectors to fetch on each `fetch()` call. The caller (a per-tenant
-     * workspace config, typically) lists exactly the authorities they need
-     * tracked. There is no auto-discovery; that would crawl Cornell at
-     * cron speed, which is what the polite-fetch contract exists to avoid.
-     */
-    selectors: CornellLiiSelector[];
-    /** Source id override; default is `'cornell-lii'`. */
-    id?: string;
+  /**
+   * Selectors to fetch on each `fetch()` call. The caller (a per-tenant
+   * workspace config, typically) lists exactly the authorities they need
+   * tracked. There is no auto-discovery; that would crawl Cornell at
+   * cron speed, which is what the polite-fetch contract exists to avoid.
+   */
+  selectors: CornellLiiSelector[];
+  /** Source id override; default is `'cornell-lii'`. */
+  id?: string;
 }
 /**
  * Build a Cornell LII source for the listed selectors.
@@ -187,7 +189,8 @@ interface CornellLiiSourceOptions {
  * ```
  */
 declare function createCornellLiiSource(options: CornellLiiSourceOptions): KnowledgeSource;
-
+//#endregion
+//#region src/sources/html.d.ts
 /**
  * Minimal HTML helpers used by the shipped sources.
  *
@@ -218,10 +221,11 @@ declare function innerHtmlById(html: string, id: string): string | undefined;
  * Returns absolute URLs by resolving against `baseUrl`.
  */
 declare function extractLinks(html: string, hrefPattern: RegExp, baseUrl: string): {
-    href: string;
-    text: string;
+  href: string;
+  text: string;
 }[];
-
+//#endregion
+//#region src/sources/http.d.ts
 /**
  * Polite HTTP fetcher shared by remote sources.
  *
@@ -238,40 +242,40 @@ declare const MIN_REQUEST_GAP_MS = 1000;
 /** Maximum response body we will buffer in memory (bytes). */
 declare const MAX_RESPONSE_BYTES: number;
 interface PoliteFetchOptions {
-    signal?: AbortSignal;
-    cacheDir?: string;
-    /**
-     * Cache age beyond which we re-fetch. Default 1 hour, long enough to
-     * batch a cron sweep across many selectors, short enough that hourly
-     * authoritative-page changes get picked up next tick.
-     */
-    cacheTtlMs?: number;
-    /**
-     * Extra request headers. The fetcher always sets `User-Agent` and
-     * `Accept`; callers can add `Accept-Language` etc.
-     */
-    headers?: Record<string, string>;
+  signal?: AbortSignal;
+  cacheDir?: string;
+  /**
+   * Cache age beyond which we re-fetch. Default 1 hour, long enough to
+   * batch a cron sweep across many selectors, short enough that hourly
+   * authoritative-page changes get picked up next tick.
+   */
+  cacheTtlMs?: number;
+  /**
+   * Extra request headers. The fetcher always sets `User-Agent` and
+   * `Accept`; callers can add `Accept-Language` etc.
+   */
+  headers?: Record<string, string>;
 }
 interface PoliteFetchResult {
-    url: string;
-    status: number;
-    /** Decoded UTF-8 body. Truncated to `MAX_RESPONSE_BYTES`. */
-    body: string;
-    /**
-     * Best-effort source-attested timestamp. Reads `Last-Modified`,
-     * falling back to `Date`, falling back to fetch time. Always ISO 8601.
-     */
-    sourceUpdatedAt: string;
-    fetchedAt: string;
-    /** True iff the response was satisfied from disk cache. */
-    fromCache: boolean;
-    /**
-     * False on: non-2xx status, captcha/block page heuristic match, or
-     * decoded body below 200 chars from a host known to serve real content
-     * (Cornell, IRS, state SOS). `unverifiableReason` carries the why.
-     */
-    verifiable: boolean;
-    unverifiableReason?: string;
+  url: string;
+  status: number;
+  /** Decoded UTF-8 body. Truncated to `MAX_RESPONSE_BYTES`. */
+  body: string;
+  /**
+   * Best-effort source-attested timestamp. Reads `Last-Modified`,
+   * falling back to `Date`, falling back to fetch time. Always ISO 8601.
+   */
+  sourceUpdatedAt: string;
+  fetchedAt: string;
+  /** True iff the response was satisfied from disk cache. */
+  fromCache: boolean;
+  /**
+   * False on: non-2xx status, captcha/block page heuristic match, or
+   * decoded body below 200 chars from a host known to serve real content
+   * (Cornell, IRS, state SOS). `unverifiableReason` carries the why.
+   */
+  verifiable: boolean;
+  unverifiableReason?: string;
 }
 /**
  * Fetch one URL with per-host throttling, on-disk cache, and block-page
@@ -287,27 +291,29 @@ declare function politeFetch(url: string, options?: PoliteFetchOptions): Promise
 declare function __resetHttpThrottle(): void;
 /** Cheap heuristic that catches CAPTCHA, WAF block pages, and "Just a moment" interstitials. */
 declare function looksLikeBlockPage(body: string): boolean;
-
+//#endregion
+//#region src/sources/irs-publications.d.ts
 interface IrsPublicationsSourceOptions {
-    /**
-     * Specific publication slugs to fetch (e.g. `['p15', 'p17', 'p463']`).
-     * When `includeIndex` is true (default), the publications index page is
-     * also fetched as a single fragment so change detection can notice
-     * year/revision shifts across the whole catalogue.
-     */
-    publications?: string[];
-    /**
-     * Revenue procedure paths to fetch (e.g. `['/irb/2024-31_IRB']`). The
-     * caller passes the exact path; this source does not auto-discover.
-     */
-    revenueProcedures?: string[];
-    includeIndex?: boolean;
-    id?: string;
+  /**
+   * Specific publication slugs to fetch (e.g. `['p15', 'p17', 'p463']`).
+   * When `includeIndex` is true (default), the publications index page is
+   * also fetched as a single fragment so change detection can notice
+   * year/revision shifts across the whole catalogue.
+   */
+  publications?: string[];
+  /**
+   * Revenue procedure paths to fetch (e.g. `['/irb/2024-31_IRB']`). The
+   * caller passes the exact path; this source does not auto-discover.
+   */
+  revenueProcedures?: string[];
+  includeIndex?: boolean;
+  id?: string;
 }
 /** Default eval dimensions for IRS-sourced fragments. */
 declare const IRS_DIMENSION_HINTS: string[];
 declare function createIrsPublicationsSource(options?: IrsPublicationsSourceOptions): KnowledgeSource;
-
+//#endregion
+//#region src/sources/state-sos.d.ts
 /**
  * Generic Secretary-of-State source.
  *
@@ -326,45 +332,46 @@ declare function createIrsPublicationsSource(options?: IrsPublicationsSourceOpti
  * @experimental Interface will likely grow as we add more state coverage.
  */
 interface StateSosEntity {
-    /** Stable id for this fragment within the state (e.g. 'llc-formation', 'corp-formation'). */
-    id: string;
-    /** Path under the configured `baseUrl` for this entity. */
-    path: string;
-    /**
-     * Extraction selector. Choose one:
-     *   - `{ kind: 'id', value: 'main-content' }` — innermost match of element with that id
-     *   - `{ kind: 'class', value: 'field--name-body' }` — innermost match of element with that class
-     *   - `{ kind: 'regex', value: /<article[\s\S]*?<\/article>/i }` — raw regex
-     *   - `{ kind: 'whole' }` — full body, tags stripped (fallback for unstructured pages)
-     */
-    selector: {
-        kind: 'id';
-        value: string;
-    } | {
-        kind: 'class';
-        value: string;
-    } | {
-        kind: 'regex';
-        value: RegExp;
-    } | {
-        kind: 'whole';
-    };
-    title: string;
-    /** Eval dimensions this entity feeds. */
-    dimensionHints?: string[];
+  /** Stable id for this fragment within the state (e.g. 'llc-formation', 'corp-formation'). */
+  id: string;
+  /** Path under the configured `baseUrl` for this entity. */
+  path: string;
+  /**
+   * Extraction selector. Choose one:
+   *   - `{ kind: 'id', value: 'main-content' }` — innermost match of element with that id
+   *   - `{ kind: 'class', value: 'field--name-body' }` — innermost match of element with that class
+   *   - `{ kind: 'regex', value: /<article[\s\S]*?<\/article>/i }` — raw regex
+   *   - `{ kind: 'whole' }` — full body, tags stripped (fallback for unstructured pages)
+   */
+  selector: {
+    kind: 'id';
+    value: string;
+  } | {
+    kind: 'class';
+    value: string;
+  } | {
+    kind: 'regex';
+    value: RegExp;
+  } | {
+    kind: 'whole';
+  };
+  title: string;
+  /** Eval dimensions this entity feeds. */
+  dimensionHints?: string[];
 }
 interface StateSosSourceConfig {
-    /** US state postal code, e.g. 'CA', 'DE', 'TX'. */
-    state: string;
-    /** Base URL for the state SOS — e.g. 'https://www.sos.ca.gov'. */
-    baseUrl: string;
-    /** Entities this state exposes (LLC, Corp, etc). */
-    entities: StateSosEntity[];
-    /** Source id; default `state-sos:<state>`. */
-    id?: string;
-    /** Display name; default `<state> Secretary of State`. */
-    name?: string;
+  /** US state postal code, e.g. 'CA', 'DE', 'TX'. */
+  state: string;
+  /** Base URL for the state SOS — e.g. 'https://www.sos.ca.gov'. */
+  baseUrl: string;
+  /** Entities this state exposes (LLC, Corp, etc). */
+  entities: StateSosEntity[];
+  /** Source id; default `state-sos:<state>`. */
+  id?: string;
+  /** Display name; default `<state> Secretary of State`. */
+  name?: string;
 }
 declare function createStateSosSource(config: StateSosSourceConfig): KnowledgeSource;
-
-export { type CornellLiiSelector, type CornellLiiSourceOptions, type FetchOpts, type FragmentProvenance, IRS_DIMENSION_HINTS, type IrsPublicationsSourceOptions, type KnowledgeFragment, type KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, type PoliteFetchOptions, type PoliteFetchResult, type StateSosEntity, type StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch };
+//#endregion
+export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeFragment, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch };
+//# sourceMappingURL=index.d.ts.map

package/dist/sources/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/sources/types.ts","../../src/sources/cornell-lii.ts","../../src/sources/html.ts","../../src/sources/http.ts","../../src/sources/irs-publications.ts","../../src/sources/state-sos.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAgCiB;;EAEf,SAAS;;EAET;;EAEA,YAAY;;;;;;EAMZ;;;;;;;;;EASA;;;;;;;UAQe;;EAEf;;;;;;;EAOA;;EAEA;;;;;;;EAOA;;;;;;;;EAQA;;EAEA;;;;;;UAOe;;;;;;EAMf;;EAEA;;EAEA;;EAEA;EACA,YAAY;;;;;;;;;;;;;EAaZ;;EAEA,WAAW;;;;;;;;;;UAWI;;EAEf;;EAEA;;EAEA;;;;;;;;;;EAUA,MAAM,MAAM,YAAY,QAAQ;;;;UCrIjB;;EAEf;;;;;EAKA;;;;;EAKA;;UAGe;;;;;;;EAOf,WAAW;;EAEX;;;;;;;;;;;;;;;iBAgBc,uBAAuB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;iBCrC1D,WAAW;;iBA4BX,WAAW,cAAc,SAAS;;iBAKlC,cAAc,cAAc;;;;;iBAa5B,aACd,cACA,aAAa,QACb;EACG;EAAc;;;;;;;;;;;;;;cCxDN;;cAIA;;cAGA;UAII;EACf,SAAS;EACT;;;;;;EAMA;;;;;EAKA,UAAU;;UAGK;EACf;EACA;;EAEA;;;;;EAKA;EACA;;EAEA;;;;;;EAMA;EACA;;;;;;;;;;;iBAYoB,YACpB,aACA,UAAS,qBACR,QAAQ;;iBAoEK;;iBA6DA,mBAAmB;;;UChLlB;;;;;;;EAOf;;;;;EAKA;EACA;EACA;;;cAIW;iBAEG,4BACd,UAAS,+BACR;;;;;;;;;;;;;;;;;;;;UC5Bc;;EAEf;;EAEA;;;;;;;;EAQA;IACM;IAAY;;IACZ;IAAe;;IACf;IAAe,OAAO;;IACtB;;EACN;;EAEA;;UAGe;;EAEf;;EAEA;;EAEA,UAAU;;EAEV;;EAEA;;iBAGc,qBAAqB,QAAQ,uBAAuB"}