@odla-ai/kg 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { G as GraphFragment, W as WeightedPair, U as Usage, R as RawItem, E as ExtractResult } from './lenses-C7Q7Gvnx.js';
 export { a as GraphEdge, b as GraphNode, c as addUsage, e as emptyUsage } from './lenses-C7Q7Gvnx.js';
 import { Op, AdminDb, SerializedAttr, Cardinality, SerializedSchema, Value, Entity } from '@odla-ai/db';
-import { ExtractTool, Ai } from '@odla-ai/ai';
+import { ExtractTool, SearchCitation, Ai } from '@odla-ai/ai';
 
 /** node type → unique natural-key attribute name. */
 type NaturalKeys = Record<string, string>;
@@ -237,6 +237,212 @@ declare function factsToFragment(company: CompanyRow, draft: FactsDraft): GraphF
 /** The `located_in` write linking a company to its resolved county. */
 declare function locationFragment(slug: string, name: string, fips: string): GraphFragment;
 
+/**
+ * What a research pass concluded about the entity it was asked to find.
+ *
+ * `wrong_entity` is deliberately distinct from `not_found`: a pass that
+ * confidently describes a *different* person with the same name is a much worse
+ * failure than one that admits it found nothing, and a benchmark that collapses
+ * the two cannot see it.
+ */
+type Verdict = "confirmed" | "probable" | "ambiguous" | "not_found" | "wrong_entity";
+/** Verdicts that permit writing enriched facts to the graph. */
+declare const WRITABLE_VERDICTS: readonly Verdict[];
+/** One supporting claim tied to the source that backs it. */
+interface Evidence {
+    /** What the source establishes, in the model's words. */
+    claim: string;
+    /** The URL the claim came from. */
+    sourceUrl: string;
+    /** When the source was read, as an ISO date. */
+    retrievedAt?: string;
+}
+/** A verdict plus the confidence and evidence offered for it. */
+interface Verification {
+    verdict: Verdict;
+    /** The model's stated confidence, clamped to 0..1. Scored for calibration, never trusted. */
+    confidence: number;
+    evidence: Evidence[];
+}
+/** Whether a value is one of the closed verdict members. */
+declare function isVerdict(value: unknown): value is Verdict;
+/** Whether a verdict permits writing the enriched facts it came with. */
+declare function isWritable(verdict: Verdict): boolean;
+/**
+ * Normalize a model's self-reported verification into the closed shape.
+ *
+ * Fails safe in both directions: an unrecognized verdict becomes `ambiguous`
+ * (never `confirmed`), a missing or out-of-range confidence is clamped, and
+ * evidence without a usable http(s) source URL is dropped — an unsourced claim
+ * is exactly the thing this package exists to stop treating as a fact.
+ */
+declare function normalizeVerification(draft: unknown, retrievedAt?: string): Verification;
+/** Whether a string is an absolute http(s) URL — the only kind evidence may cite. */
+declare function isHttpUrl(value: string): boolean;
+
+/** The minimal person row enrichment reads. */
+interface PersonRow {
+    slug: string;
+    name: string;
+    /** Natural key of a company the person is already linked to — the strongest disambiguator. */
+    companySlug?: string;
+    companyName?: string;
+    /** The employer's website. What makes first-party evidence reachable at all. */
+    companyWebsite?: string;
+    role?: string;
+    city?: string;
+    region?: string;
+}
+/** Where a person publishes. Kinds with one canonical host are validated against it. */
+type PersonLinkKind = "website" | "blog" | "substack" | "linkedin" | "x" | "bluesky" | "github" | "other";
+/** System prompt for the grounded person research pass. */
+declare const PERSON_SEARCH_SYSTEM: string;
+/** System prompt for structuring the research notes into {@link PersonDraft}. */
+declare const PERSON_EXTRACT_SYSTEM: string;
+/** Forced-tool schema for a person's verified public profile. */
+declare const PERSON_EXTRACT_TOOL: ExtractTool;
+/** The model's structured person profile, before validation into a fragment. */
+interface PersonDraft {
+    verdict?: string;
+    confidence?: number;
+    links?: Array<{
+        kind?: string;
+        url?: string;
+    }>;
+    employer?: string | null;
+    role?: string | null;
+    businessEmail?: string | null;
+    businessPhone?: string | null;
+    city?: string | null;
+    region?: string | null;
+    almaMater?: string | null;
+    otherCompanies?: string[];
+    evidence?: Array<{
+        claim?: string;
+        sourceUrl?: string;
+    }>;
+}
+/** A validated person link. */
+interface PersonLink {
+    kind: PersonLinkKind;
+    url: string;
+}
+/** The validated result of one person enrichment pass. */
+interface PersonResult {
+    verification: Verification;
+    links: PersonLink[];
+    fragment: GraphFragment;
+}
+/** The user prompt for a person research pass. */
+declare function personPrompt(person: PersonRow): string;
+/**
+ * Keep only links that are plausibly real: absolute https URLs, on the canonical
+ * host when the kind has one, and never a placeholder domain. Models invent
+ * `linkedin.com/in/first-last` from a name constantly; a kind/host mismatch is
+ * the cheapest way to catch it before it becomes a stored "fact".
+ */
+declare function validateLinks(raw: PersonDraft["links"], limit?: number): PersonLink[];
+/**
+ * Turn one person's structured draft into a verdict plus an idempotent fragment.
+ *
+ * The fragment is empty unless the verdict is writable — an `ambiguous`,
+ * `not_found`, or `wrong_entity` pass contributes no graph, however confident
+ * the model sounded. The verdict and its evidence are still returned, because
+ * "this lane confidently found the wrong person" is exactly what a benchmark
+ * needs to record.
+ */
+declare function personToFragment(person: PersonRow, draft: PersonDraft, retrievedAt?: string): PersonResult;
+
+/** Where a source sits on the scale that decides how much it counts. */
+type SourceClass = 
+/** The organization's own site: team page, staff directory, press release.
+ *  The subject cannot assert this about themselves, which is what makes it
+ *  the strongest ordinary evidence. */
+"first-party"
+/** A registry that assigns identifiers: ORCID, SEC EDGAR, a licensing board. */
+ | "authoritative"
+/** The person's own profile or site. Real, but self-asserted. */
+ | "self-asserted"
+/** Press, directories, anything else. */
+ | "third-party";
+/** What reading a source established about the subject. */
+type Corroboration = 
+/** Named the subject and tied them to their organization. */
+"confirmed"
+/** Named the subject, but nothing tied it to their work. */
+ | "name-only"
+/** Loaded, and mentioned neither. */
+ | "absent"
+/** Could not be read: blocked, gone, or refused. */
+ | "unreachable"
+/** Not checked yet. */
+ | "unchecked";
+/** One dated, classified source and what it corroborated. */
+interface VerifiedSource {
+    sourceUrl: string;
+    sourceClass: SourceClass;
+    /** Which facts this source supported: "employer", "title", "location", … */
+    facts: string[];
+    /** When it was read. Every fact is a fact *as of* a date. */
+    verifiedOn: string;
+    corroboration: Corroboration;
+}
+/** How well an identity is established. */
+type Grade = 
+/** Enough independent sources, anchored, agreeing, with no contradiction. */
+"high"
+/** Corroborated, but thinly or only by sources the subject controls. */
+ | "medium"
+/** One source, or a contradiction, or nothing that settles it. */
+ | "unresolved"
+/**
+ * Nothing could be read at all.
+ *
+ * Deliberately distinct from `unresolved`. In a real run 60 of 93 claimed
+ * URLs came back unreachable, almost all login walls. Scoring those as "not
+ * established" blames a lane for a wall it cannot walk through; scoring them
+ * as established would be a lie. Neither is true, so this says so.
+ */
+ | "unverifiable";
+/** The bar a `high` grade has to clear. */
+interface GradeStandard {
+    /** Distinct hosts that must corroborate. */
+    minimumSources: number;
+    /** Distinct facts that must be corroborated across them. */
+    minimumFacts: number;
+    /** Classes that can anchor a `high` grade. */
+    anchors: readonly SourceClass[];
+    /** Whether `medium` also requires an anchor. Measured: two third-party
+     *  sources agreeing about someone who does not exist is a thing that
+     *  happens, so anything acted on should usually require one. */
+    anchorRequiredForMedium: boolean;
+}
+/** Two independent sources, one first-party or authoritative, three facts. */
+declare const DEFAULT_STANDARD: GradeStandard;
+/** What the grade was based on, so a reviewer can disagree with it. */
+interface GradeReport {
+    grade: Grade;
+    independentSources: number;
+    factsCorroborated: string[];
+    hasAnchor: boolean;
+    contradictions: string[];
+    reason: string;
+}
+/** Two sources are independent when they are not the same site. */
+declare function independentHosts(sources: readonly VerifiedSource[]): string[];
+/**
+ * Grade an identity from the sources that were checked.
+ *
+ * Only sources that corroborated something count toward the grade. One that was
+ * read and did NOT name the subject is a contradiction; one that could not be
+ * read is neither, which is the whole reason `unverifiable` exists.
+ */
+declare function gradeSources(sources: readonly VerifiedSource[], standard?: GradeStandard): GradeReport;
+/** Grades that justify acting on the identity. */
+declare const ACTIONABLE: readonly Grade[];
+/** Whether a grade is good enough to act on. */
+declare function isActionable(value: Grade): boolean;
+
 /** Which model serves each verb (search must be a web-grounded model). */
 interface EnrichModels {
     /** Web-search-grounded research model. */
@@ -251,6 +457,23 @@ interface EnrichModels {
  * fragment (possibly empty — nothing established); the caller writes it.
  */
 declare function enrichCompany(ai: Ai, models: EnrichModels, company: CompanyRow): Promise<GraphFragment>;
+/** One person enrichment pass, with the sources the provider actually cited. */
+interface PersonEnrichment extends PersonResult {
+    /** Sources the search model attributed. Empty when the provider grounded nothing. */
+    citations: SearchCitation[];
+    /** The research prose the extraction was taken from — useful for adjudication. */
+    notes: string;
+}
+/**
+ * Enrich one person: a grounded web search for their public professional
+ * presence, then a structured extraction into a validated verdict + fragment.
+ *
+ * Unlike {@link enrichCompany}, this always returns a verdict — including
+ * `not_found` and `wrong_entity` — because "the lane confidently identified the
+ * wrong person" is a result worth recording, not an error. The fragment is empty
+ * unless the verdict permits writing.
+ */
+declare function enrichPerson(ai: Ai, models: EnrichModels, person: PersonRow, retrievedAt?: string): Promise<PersonEnrichment>;
 /**
  * Resolve a batch of companies' free-text locations to county FIPS codes via a
  * single structured extraction, joined against a caller-supplied gazetteer
@@ -262,6 +485,325 @@ declare function resolveCounties(ai: Ai, model: string, rows: CompanyRow[], gaze
     fips: string;
 }>>;
 
+/** Normalize for containment testing: fold case, accents, and punctuation. */
+declare function fold(value: string): string;
+/**
+ * Whether a folded haystack names a person.
+ *
+ * Requires every name token, and requires them to sit within a couple of words
+ * of each other, which is how names are actually written: "Abbey Chrystal",
+ * "Chrystal, Abbey", and "Abbey R. Chrystal" all qualify.
+ *
+ * Proximity is the load-bearing part, and it was added because of a measured
+ * failure rather than in anticipation of one. Requiring only that the tokens
+ * appear somewhere on the page matched "Abbey Chrystal" against a staff
+ * directory that listed "Abbey Fornier" and "Dale Chrystal" — on a team page
+ * most name tokens appear somewhere, so a document-wide match corroborates
+ * almost anybody.
+ *
+ * Single-token names are rejected outright: matching "Deere" against arbitrary
+ * page text would corroborate almost anything.
+ *
+ * @param haystack Page text, already passed through {@link fold}.
+ * @param name The person's name, in any casing or accenting.
+ */
+declare function mentionsName(haystack: string, name: string): boolean;
+/**
+ * Pull a window of text around the person's name, as evidence a reviewer can
+ * read without re-fetching the page.
+ */
+declare function snippetAround(text: string, name: string, width?: number): string;
+/**
+ * Reduce HTML to readable text.
+ *
+ * Script and style bodies are dropped first: a page's inline JSON often repeats
+ * unrelated names, and matching against it corroborates the wrong person.
+ */
+declare function stripMarkup(html: string): string;
+
+/**
+ * Read a URL and return its body, or null if it could not be read.
+ *
+ * Supplied by the caller rather than implemented here, and deliberately so.
+ * Fetched pages are attacker-influenced: a strategy reads whatever a third
+ * party chose to serve. Making the reader an explicit dependency means the
+ * caller decides what boundary it crosses — in odla that is
+ * `@odla-ai/camel`'s artifact ingress, which caps bytes, screens redirects for
+ * SSRF, and labels the body Unsafe. kg does not reach for the network itself,
+ * so it can never quietly bypass that.
+ */
+type PageReader = (url: string) => Promise<string | null>;
+/** What a strategy is given to work with. */
+interface StrategyContext {
+    person: PersonRow;
+    /** The date this evidence is being gathered on. Every fact is a fact *as of* a date. */
+    retrievedAt: string;
+    /** Present for strategies that call a model. */
+    ai?: Ai;
+    models?: EnrichModels;
+    /** Present for strategies that read pages. */
+    readPage?: PageReader;
+}
+/** What one strategy established. */
+interface Finding {
+    strategy: string;
+    /** Dated, classified sources — the input the grade is computed from. */
+    sources: VerifiedSource[];
+    /** Profile and site URLs this strategy proposes. */
+    links: PersonLink[];
+    /** Human-readable account of what happened, for adjudication. */
+    notes: string;
+    /** Set when the strategy failed outright, which is not the same as finding nothing. */
+    error?: string;
+}
+/**
+ * One way of gathering evidence about a person.
+ *
+ * A strategy never decides whether the person was found. It reports what it
+ * saw and how strong the sources were; {@link investigatePerson} grades. That
+ * split is the point — it means adding a strategy cannot inflate a verdict, and
+ * it means the standard can be raised later and re-applied to stored evidence
+ * without paying for the inference again.
+ */
+interface Strategy {
+    /** Stable identifier, recorded on findings so results stay attributable. */
+    name: string;
+    /** Whether this strategy can run at all for this subject and context. */
+    applicable(context: StrategyContext): boolean;
+    run(context: StrategyContext): Promise<Finding>;
+}
+/** The result of investigating one person with a set of strategies. */
+interface Investigation {
+    person: PersonRow;
+    /** How well the identity is established, per the standard used. */
+    grade: Grade;
+    /** Why, in enough detail to disagree with. */
+    report: GradeReport;
+    /** Every source gathered, deduplicated by URL. */
+    sources: VerifiedSource[];
+    /** Every link proposed, deduplicated by URL. */
+    links: PersonLink[];
+    /** Per-strategy detail, including strategies that ran and found nothing. */
+    findings: Finding[];
+    /** Strategies skipped because they were not applicable. */
+    skipped: string[];
+}
+/**
+ * Run every applicable strategy and grade what they found together.
+ *
+ * Strategies run concurrently and are isolated from each other: one that throws
+ * becomes a `Finding` carrying its error rather than failing the investigation.
+ * A search provider being down should cost you that strategy's evidence, not
+ * the first-party page another strategy already read.
+ *
+ * @param context The person, the date, and whichever capabilities are available.
+ * @param strategies Which strategies to attempt, in any order.
+ * @param standard The bar a `high` grade must clear. Defaults to
+ *   {@link DEFAULT_STANDARD}: two independent sources, one anchoring, three facts.
+ */
+declare function investigatePerson(context: StrategyContext, strategies: readonly Strategy[], standard?: GradeStandard): Promise<Investigation>;
+
+/** Paths an organization is most likely to describe its people on. */
+declare const TEAM_PATHS: readonly string[];
+/** The site root, which is the only URL on a domain guaranteed to exist. */
+declare function rootOf(website: string): string | null;
+/**
+ * Guessed people-page paths. A fallback only.
+ *
+ * Guessing produced 67 refusals against 23 successful reads in a real run: most
+ * sites do not use these paths, and a 404 teaches nothing about whether the
+ * person works there. Following the site's own links is the primary route; this
+ * is what remains when a homepage offers no usable navigation.
+ */
+declare function candidatePages(website: string, limit?: number): string[];
+/**
+ * Extract the links a homepage itself offers toward its people pages.
+ *
+ * Reading the site's own navigation beats guessing at it on both counts: it is
+ * far more likely to resolve, and it lands on the page the organization
+ * actually maintains. Same-origin only — an off-site link is not first-party
+ * evidence, which is the entire reason this strategy carries weight.
+ */
+declare function peopleLinks(html: string, origin: string, limit?: number): string[];
+/** What one organization page said about the person. */
+interface OrgHit {
+    url: string;
+    named: boolean;
+    /** Text around the name, for the reviewer. */
+    snippet: string;
+}
+/**
+ * Decide whether an organization page establishes the person.
+ *
+ * Deliberately strict about the name and silent about the title: a team page
+ * naming the person is the finding, and inferring their exact title from
+ * surrounding prose would manufacture a fact the page never stated plainly.
+ */
+declare function judgeOrgPage(name: string, url: string, text: string): OrgHit;
+/**
+ * Walk the employer's site looking for the person.
+ *
+ * Requires `companyWebsite` on the person and a `readPage`; without either it
+ * reports itself inapplicable rather than pretending to have checked.
+ */
+declare const orgSiteStrategy: Strategy;
+
+/**
+ * Class a cited source.
+ *
+ * The employer's own domain is first-party even when a search found it rather
+ * than a crawl — what makes evidence first-party is who published it, not how
+ * it was reached.
+ */
+declare function classifySource(url: string, companyWebsite?: string): SourceClass;
+/**
+ * Whether a provider actually grounded a claim in this source, as opposed to
+ * merely consulting it.
+ *
+ * A citation carrying cited text or a text span is attributed: the provider is
+ * saying *this sentence came from here*. One carrying only a URL means the
+ * source was visited. The difference matters enough to grade differently —
+ * consulted-but-unquoted sources are the ones that pad a bibliography without
+ * supporting anything in it.
+ */
+declare function isAttributed(citation: SearchCitation): boolean;
+/**
+ * Research a person with a grounded search, and report the sources rather than
+ * the conclusion.
+ */
+declare const researchStrategy: Strategy;
+
+/** Build the narrow query. Quoting both names is what makes the count meaningful. */
+declare function targetedQuery(person: PersonRow, platform?: string): string;
+/** One candidate profile the search turned up. */
+interface Candidate {
+    url: string;
+    host: string;
+    /** The profile handle, which tells two results apart from one result cited twice. */
+    handle: string;
+}
+/**
+ * Reduce a citation set to distinct candidate profiles.
+ *
+ * Deduplicates by (host, handle) rather than by URL. The same profile arrives
+ * as `linkedin.com/in/x`, `www.linkedin.com/in/x/`, and again with tracking
+ * suffixes; counting those as three candidates turns every confident answer
+ * into a false ambiguity.
+ */
+declare function candidatesFrom(citations: readonly SearchCitation[]): Candidate[];
+/**
+ * Look up one person by a single narrow query.
+ *
+ * Emits a source only when exactly one distinct profile came back. Emitting one
+ * per candidate when the name is ambiguous would manufacture precisely the
+ * confidence this strategy exists to withhold — and because the profile is the
+ * person's own, it is classed `self-asserted`, which under the default standard
+ * cannot anchor a `high` grade by itself.
+ */
+declare const targetedProfileStrategy: Strategy;
+
+/**
+ * How an ontology stores the alias index.
+ *
+ * kg does not own your ontology — you declare the entity, kg reads and writes
+ * it through these names. The alias entity needs a unique natural key and one
+ * attribute holding the person's key.
+ */
+interface PersonIdentityConfig {
+    /** Entity type indexing aliases, e.g. `"person_alias"`. */
+    aliasType: string;
+    /** Unique natural-key attr on the alias entity. Default `"alias"`. */
+    aliasKeyAttr?: string;
+    /** Attr on the alias entity holding the person's key. Default `"personKey"`. */
+    personKeyAttr?: string;
+    /** Entity type of the person the alias points at. Default `"person"`. */
+    personType?: string;
+    /** Edge label from alias to person. Default `"of_person"`. */
+    edgeLabel?: string;
+}
+/**
+ * Mint an opaque person key.
+ *
+ * Random rather than derived, and that is the entire point. Any key computed
+ * from the facts — a hash of name plus employer — collides two namesakes at one
+ * company and mints a second identity the moment someone changes job. A key
+ * that means nothing cannot be wrong about anything.
+ *
+ * @param random Injectable for tests; defaults to `crypto.randomUUID`.
+ */
+declare function mintPersonKey(random?: () => string): string;
+/** Whether a key was minted by {@link mintPersonKey} rather than derived from a name. */
+declare function isMintedKey(key: string): boolean;
+/**
+ * The alias for a public profile: durable, because it belongs to the person
+ * rather than to their current job.
+ */
+declare function profileAlias(kind: PersonLink["kind"], url: string): string | null;
+/**
+ * The bootstrap alias for someone with no profile found yet.
+ *
+ * Employer is part of the key on purpose: without it every namesake resolves to
+ * one person, which is the bug this module exists to close. With it, a job
+ * change produces a *new* alias rather than a wrong match — the person keeps
+ * their key, and the old alias keeps pointing at them.
+ *
+ * Returns null without an employer. A bare name is not an identity, and
+ * indexing one would reintroduce the collision by the back door.
+ */
+declare function nameAlias(name: string, companyName?: string): string | null;
+/**
+ * Every alias a person is recognizable by, strongest first.
+ *
+ * Order is what makes resolution correct rather than merely convenient: a
+ * profile match is trusted over a name-plus-employer match, so someone who
+ * changed jobs still resolves to themselves.
+ */
+declare function aliasesFor(person: PersonRow, links?: readonly PersonLink[]): string[];
+/**
+ * Resolve aliases to an existing person key.
+ *
+ * One batched read, then the *caller's* order decides — the first alias with a
+ * hit wins, so a profile match beats a name match even when the name row was
+ * written first. Returns null when nothing matches, which means mint.
+ */
+declare function resolvePersonKey(db: AdminDb, config: PersonIdentityConfig, aliases: readonly string[]): Promise<string | null>;
+/**
+ * Rewrite a fragment onto a minted person key and index the aliases that lead
+ * back to it.
+ *
+ * Everything referencing the old key moves with it — edges included — so an
+ * affiliation written against the name-derived key does not end up orphaned.
+ * The alias rows are what make the *next* pass idempotent: without them a
+ * minted key would be re-minted every run, which is worse than the name key it
+ * replaced.
+ */
+declare function applyPersonIdentity(fragment: GraphFragment, from: string, to: string, aliases: readonly string[], config: PersonIdentityConfig): GraphFragment;
+
+/** What identifying a person settled on. */
+interface PersonIdentity {
+    /** The opaque key the person is stored under. */
+    personKey: string;
+    /** True when nobody matched and a fresh key was minted. */
+    minted: boolean;
+    /** The aliases now indexed against that key, strongest first. */
+    aliases: string[];
+    /** The fragment, rekeyed onto `personKey` with the alias rows appended. */
+    fragment: GraphFragment;
+}
+/**
+ * Give a person a stable opaque key, reusing the one they already have.
+ *
+ * Aliases found by this pass are indexed too, not just the one that resolved.
+ * That is how someone graduates off the fragile name-plus-employer alias: the
+ * first pass that finds their LinkedIn attaches it to the key they already
+ * have, and every later pass — including after they change jobs — resolves on
+ * the profile instead.
+ *
+ * @param fragment A fragment keyed on `person.slug`, as `personToFragment`
+ *   produces. Its person node and every edge touching it are rekeyed.
+ */
+declare function identifyPerson(db: AdminDb, config: PersonIdentityConfig, person: PersonRow, links: readonly PersonLink[], fragment: GraphFragment): Promise<PersonIdentity>;
+
 /**
  * The LLM seam, now a thin adapter over @odla-ai/ai (which was itself
  * generalized from this package's original Provider). Three verbs stay:
@@ -541,6 +1083,17 @@ declare function ingestFresh(step: StepLike, deps: PipelineDeps, fresh: RawItem[
  */
 /** NFKD-normalize, strip accents, lowercase, non-alphanumerics → "-", cap 60. */
 declare function slugify(input: string): string;
+/**
+ * Collapse a name to a comparison key: accents stripped, `&` spelled out,
+ * punctuation and spacing removed, and trailing legal suffixes dropped.
+ *
+ * Stronger than comparing {@link slugify} output, because it matches
+ * "Acme Corp.", "Acme, Inc." and "Acme & Co" onto the same key — the shapes the
+ * same organization is actually written in across sources. Use it to decide
+ * whether two records are the same entity; use `slugify` for the natural key
+ * that gets stored.
+ */
+declare function identityKey(value: string): string;
 /** Drop tracking params, hash, and trailing slash so the same page maps to one key. */
 declare function normalizeUrl(raw: string): string;
 /** Stable short key for a URL (FNV-1a 32-bit, base36). Used as the `signal` natural key. */
@@ -561,4 +1114,4 @@ declare function htmlToText(html: string, maxChars?: number): string;
 /** Fetch a URL and return readable text. Best-effort: returns "" on any failure. */
 declare function fetchText(url: string, maxChars?: number): Promise<string>;
 
-export { type AttrSpec, type AttrType, COMMIT_STEP_CONFIG, type CompanyRow, type Connector, type ConnectorConfig, type ConnectorContext, type ConnectorJob, type ConnectorLens, type ConnectorReport, type ContextConfig, type EdgeSpec, type EnrichModels, type EntitySpec, type ExportEntitySpec, type ExportSpec, type ExtractCall, ExtractResult, FACTS_EXTRACT_SYSTEM, FACTS_EXTRACT_TOOL, FACTS_SEARCH_SYSTEM, type FactsDraft, GraphFragment, IO_STEP_CONFIG, type KVLike, LLM_STEP_CONFIG, LOCATE_SYSTEM, LOCATE_TOOL, type LlmConfig, type LlmEnv, MODEL_TIERS, type MergeRule, type NaturalKeys, type Ontology, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, Usage, type WriteCall, allJobs, asStepLike, canonicalizeFragment, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fragmentToOps, getConnector, getProvider, htmlToText, humanAttrsOf, ingestFresh, isLikelyPersonName, jobsForHour, locatePrompt, locationFragment, makeContext, mergeAttrs, mergeRulesOf, mergeScalar, naturalKeysOf, normalizeUrl, resilientStep, resolveCounties, resolveName, searchEntities, slugify, toSerializedSchema, urlHash, writeFragment };
+export { ACTIONABLE, type AttrSpec, type AttrType, COMMIT_STEP_CONFIG, type Candidate, type CompanyRow, type Connector, type ConnectorConfig, type ConnectorContext, type ConnectorJob, type ConnectorLens, type ConnectorReport, type ContextConfig, type Corroboration, DEFAULT_STANDARD, type EdgeSpec, type EnrichModels, type EntitySpec, type Evidence, type ExportEntitySpec, type ExportSpec, type ExtractCall, ExtractResult, FACTS_EXTRACT_SYSTEM, FACTS_EXTRACT_TOOL, FACTS_SEARCH_SYSTEM, type FactsDraft, type Finding, type Grade, type GradeReport, type GradeStandard, GraphFragment, IO_STEP_CONFIG, type Investigation, type KVLike, LLM_STEP_CONFIG, LOCATE_SYSTEM, LOCATE_TOOL, type LlmConfig, type LlmEnv, MODEL_TIERS, type MergeRule, type NaturalKeys, type Ontology, type OrgHit, PERSON_EXTRACT_SYSTEM, PERSON_EXTRACT_TOOL, PERSON_SEARCH_SYSTEM, type PageReader, type PersonDraft, type PersonEnrichment, type PersonIdentity, type PersonIdentityConfig, type PersonLink, type PersonLinkKind, type PersonResult, type PersonRow, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceClass, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, type Strategy, type StrategyContext, TEAM_PATHS, Usage, type Verdict, type Verification, type VerifiedSource, WRITABLE_VERDICTS, type WriteCall, aliasesFor, allJobs, applyPersonIdentity, asStepLike, candidatePages, candidatesFrom, canonicalizeFragment, classifySource, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, enrichPerson, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fold, fragmentToOps, getConnector, getProvider, gradeSources, htmlToText, humanAttrsOf, identifyPerson, identityKey, independentHosts, ingestFresh, investigatePerson, isActionable, isAttributed, isHttpUrl, isLikelyPersonName, isMintedKey, isVerdict, isWritable, jobsForHour, judgeOrgPage, locatePrompt, locationFragment, makeContext, mentionsName, mergeAttrs, mergeRulesOf, mergeScalar, mintPersonKey, nameAlias, naturalKeysOf, normalizeUrl, normalizeVerification, orgSiteStrategy, peopleLinks, personPrompt, personToFragment, profileAlias, researchStrategy, resilientStep, resolveCounties, resolveName, resolvePersonKey, rootOf, searchEntities, slugify, snippetAround, stripMarkup, targetedProfileStrategy, targetedQuery, toSerializedSchema, urlHash, validateLinks, writeFragment };