@odla-ai/kg 0.4.1 → 0.5.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { G as GraphFragment, W as WeightedPair, U as Usage, R as RawItem, E as ExtractResult } from './lenses-C7Q7Gvnx.cjs';
 export { a as GraphEdge, b as GraphNode, c as addUsage, e as emptyUsage } from './lenses-C7Q7Gvnx.cjs';
 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,120 @@ 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;
+    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;
+
 /** Which model serves each verb (search must be a web-grounded model). */
 interface EnrichModels {
     /** Web-search-grounded research model. */
@@ -251,6 +365,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
@@ -541,6 +672,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 +703,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 { 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 Evidence, 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, PERSON_EXTRACT_SYSTEM, PERSON_EXTRACT_TOOL, PERSON_SEARCH_SYSTEM, type PersonDraft, type PersonEnrichment, type PersonLink, type PersonLinkKind, type PersonResult, type PersonRow, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, Usage, type Verdict, type Verification, WRITABLE_VERDICTS, type WriteCall, allJobs, asStepLike, canonicalizeFragment, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, enrichPerson, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fragmentToOps, getConnector, getProvider, htmlToText, humanAttrsOf, identityKey, ingestFresh, isHttpUrl, isLikelyPersonName, isVerdict, isWritable, jobsForHour, locatePrompt, locationFragment, makeContext, mergeAttrs, mergeRulesOf, mergeScalar, naturalKeysOf, normalizeUrl, normalizeVerification, personPrompt, personToFragment, resilientStep, resolveCounties, resolveName, searchEntities, slugify, toSerializedSchema, urlHash, validateLinks, writeFragment };

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,120 @@ 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;
+    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;
+
 /** Which model serves each verb (search must be a web-grounded model). */
 interface EnrichModels {
     /** Web-search-grounded research model. */
@@ -251,6 +365,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
@@ -541,6 +672,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 +703,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 { 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 Evidence, 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, PERSON_EXTRACT_SYSTEM, PERSON_EXTRACT_TOOL, PERSON_SEARCH_SYSTEM, type PersonDraft, type PersonEnrichment, type PersonLink, type PersonLinkKind, type PersonResult, type PersonRow, type PipelineDeps, type Provider, type ProviderFamily, RawItem, type SearchCall, type SourceConnector, type SourceEntry, type StepConfig, type StepLike, Store, Usage, type Verdict, type Verification, WRITABLE_VERDICTS, type WriteCall, allJobs, asStepLike, canonicalizeFragment, connectorIds, countyKey, createProvider, enabledSources, enrichCompany, enrichPerson, exportFragment, extractJson, extractJsonArray, factsToFragment, fetchText, fetchUrl, findConnectors, fragmentToOps, getConnector, getProvider, htmlToText, humanAttrsOf, identityKey, ingestFresh, isHttpUrl, isLikelyPersonName, isVerdict, isWritable, jobsForHour, locatePrompt, locationFragment, makeContext, mergeAttrs, mergeRulesOf, mergeScalar, naturalKeysOf, normalizeUrl, normalizeVerification, personPrompt, personToFragment, resilientStep, resolveCounties, resolveName, searchEntities, slugify, toSerializedSchema, urlHash, validateLinks, writeFragment };

package/dist/index.js

@@ -345,6 +345,15 @@ function findConnectors(fragment, config) {
 function slugify(input) {
   return input.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60).replace(/-+$/g, "");
 }
+var LEGAL_SUFFIXES = /* @__PURE__ */ new Set(["co", "company", "corp", "corporation", "inc", "incorporated", "llc", "llp", "ltd", "limited", "pllc"]);
+function identityKey(value) {
+  const tokens = value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/&/g, " and ").match(/[a-z0-9]+/g) ?? [];
+  while (tokens.length > 1 && LEGAL_SUFFIXES.has(tokens.at(-1) ?? "")) {
+    tokens.pop();
+    if (tokens.at(-1) === "and") tokens.pop();
+  }
+  return tokens.join("");
+}
 function normalizeUrl(raw) {
   try {
     const u = new URL(raw);
@@ -487,6 +496,160 @@ function locationFragment(slug, name, fips) {
   };
 }
 
+// src/enrich/verify.ts
+var WRITABLE_VERDICTS = ["confirmed", "probable"];
+var ALL = ["confirmed", "probable", "ambiguous", "not_found", "wrong_entity"];
+function isVerdict(value) {
+  return typeof value === "string" && ALL.includes(value);
+}
+function isWritable(verdict) {
+  return WRITABLE_VERDICTS.includes(verdict);
+}
+function normalizeVerification(draft, retrievedAt) {
+  const d = draft ?? {};
+  const verdict = isVerdict(d.verdict) ? d.verdict : "ambiguous";
+  const raw = typeof d.confidence === "number" && Number.isFinite(d.confidence) ? d.confidence : 0;
+  const confidence = Math.min(1, Math.max(0, raw));
+  const evidence = [];
+  for (const item of Array.isArray(d.evidence) ? d.evidence.slice(0, 12) : []) {
+    const e = item ?? {};
+    const sourceUrl = typeof e.sourceUrl === "string" ? e.sourceUrl.trim() : "";
+    const claim = typeof e.claim === "string" ? e.claim.trim() : "";
+    if (!claim || !isHttpUrl(sourceUrl)) continue;
+    evidence.push({ claim: claim.slice(0, 300), sourceUrl, ...retrievedAt ? { retrievedAt } : {} });
+  }
+  if (evidence.length === 0 && isWritable(verdict)) return { verdict: "ambiguous", confidence, evidence };
+  return { verdict, confidence, evidence };
+}
+function isHttpUrl(value) {
+  try {
+    const u = new URL(value);
+    return u.protocol === "https:" || u.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+// src/enrich/person.ts
+var LINK_KINDS = ["website", "blog", "substack", "linkedin", "x", "bluesky", "github", "other"];
+var CANONICAL_HOSTS = {
+  linkedin: ["linkedin.com"],
+  github: ["github.com"],
+  x: ["x.com", "twitter.com"],
+  bluesky: ["bsky.app"]
+};
+var PLACEHOLDER_HOSTS = ["example.com", "example.org", "example.net", "yourdomain.com", "domain.com"];
+var PERSON_SEARCH_SYSTEM = "You are a research assistant with web search, confirming the identity of a specific named person and finding their PUBLIC PROFESSIONAL presence. Look for: a personal website, blog, or Substack; LinkedIn, X/Bluesky, or GitHub profiles; their current employer and role; and a business email or phone that they or their employer have published openly (a company contact page, a conference bio). Do NOT look for or report home addresses, personal phone numbers, or personal email addresses. Also report disambiguating facts: city or region, alma mater, and other companies named alongside them. Names are not unique. If the results describe more than one person with this name and you cannot tell which is meant, say so explicitly. If you find a different person with the same name, say that too. Cite the URL for every claim. Never guess a profile URL from a name pattern \u2014 report only URLs you actually saw. If you found nothing, say so plainly.";
+var PERSON_EXTRACT_SYSTEM = "Extract the structured profile from the research notes. Use null for anything the notes do not establish. Set verdict to 'confirmed' only when the notes identify this exact person beyond doubt; 'probable' when the evidence is strong but circumstantial; 'ambiguous' when several same-named people cannot be told apart; 'not_found' when nothing was established; 'wrong_entity' when the notes describe a different person with the same name. Every claim in evidence must carry the source URL it came from.";
+var PERSON_EXTRACT_TOOL = {
+  name: "person_profile",
+  description: "Verified identity plus public professional profile for one person",
+  parameters: {
+    type: "object",
+    properties: {
+      verdict: { type: "string", enum: ["confirmed", "probable", "ambiguous", "not_found", "wrong_entity"] },
+      confidence: { type: "number", description: "0..1 \u2014 how sure you are this is the right person" },
+      links: {
+        type: "array",
+        description: "Only URLs actually seen in the results; never a guessed profile pattern.",
+        items: {
+          type: "object",
+          properties: {
+            kind: { type: "string", enum: [...LINK_KINDS] },
+            url: { type: "string" }
+          },
+          required: ["kind", "url"]
+        }
+      },
+      employer: { type: ["string", "null"], description: "Current employer name" },
+      role: { type: ["string", "null"], description: "Current title at that employer" },
+      businessEmail: { type: ["string", "null"], description: "Publicly published work email only" },
+      businessPhone: { type: ["string", "null"], description: "Publicly published work phone only" },
+      city: { type: ["string", "null"] },
+      region: { type: ["string", "null"], description: "State, province, or country" },
+      almaMater: { type: ["string", "null"] },
+      otherCompanies: { type: "array", items: { type: "string" }, description: "Companies named alongside them" },
+      evidence: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: { claim: { type: "string" }, sourceUrl: { type: "string" } },
+          required: ["claim", "sourceUrl"]
+        }
+      }
+    },
+    required: ["verdict", "confidence", "links", "evidence"]
+  }
+};
+function personPrompt(person) {
+  const at = person.companyName ? ` (${person.role ? `${person.role}, ` : ""}${person.companyName})` : "";
+  const where = [person.city, person.region].filter(Boolean).join(", ");
+  return `Person: ${person.name}${at}${where ? `
+Known location: ${where}` : ""}
+
+Confirm this is a real, identifiable person and find their public professional presence.`;
+}
+function validateLinks(raw, limit = 8) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of (raw ?? []).slice(0, 24)) {
+    const kind = LINK_KINDS.includes(String(item?.kind)) ? item.kind : "other";
+    const url = String(item?.url ?? "").trim();
+    const parsed = httpsUrl(url);
+    if (!parsed) continue;
+    const host = parsed.hostname.toLowerCase().replace(/^www\./, "");
+    if (PLACEHOLDER_HOSTS.includes(host)) continue;
+    const required = CANONICAL_HOSTS[kind];
+    if (required && !required.some((h) => host === h || host.endsWith(`.${h}`))) continue;
+    if (seen.has(url)) continue;
+    seen.add(url);
+    out.push({ kind, url });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+function personToFragment(person, draft, retrievedAt) {
+  const verification = normalizeVerification(draft, retrievedAt);
+  const links = validateLinks(draft.links);
+  if (!isWritable(verification.verdict)) return { verification, links, fragment: { nodes: [], edges: [] } };
+  const attrs = { name: person.name };
+  for (const link of links) if (!attrs[link.kind]) attrs[link.kind] = link.url;
+  const city = str(draft.city, 60);
+  if (city && !person.city) attrs.city = city;
+  const region = str(draft.region, 60);
+  if (region && !person.region) attrs.region = region;
+  const email = str(draft.businessEmail, 120);
+  if (email && /^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(email)) attrs.businessEmail = email;
+  const phone = str(draft.businessPhone, 40);
+  if (phone) attrs.businessPhone = phone;
+  const almaMater = str(draft.almaMater, 120);
+  if (almaMater) attrs.almaMater = almaMater;
+  const nodes = [{ type: "person", key: person.slug, attrs }];
+  const edges = [];
+  const employer = str(draft.employer, 120);
+  const known = person.companySlug && person.companyName && identityKey(person.companyName) === identityKey(employer);
+  const companySlug = employer ? known ? person.companySlug : slugify(employer) : "";
+  if (employer && companySlug) {
+    const key = `${person.slug}~${companySlug}`;
+    nodes.push({ type: "company", key: companySlug, attrs: { name: known ? person.companyName : employer } });
+    nodes.push({ type: "affiliation", key, attrs: { role: str(draft.role, 60) || person.role || "" } });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "person", key: person.slug }, label: "of_person" });
+    edges.push({ from: { type: "affiliation", key }, to: { type: "company", key: companySlug }, label: "of_company" });
+  }
+  return { verification, links, fragment: { nodes, edges } };
+}
+function str(value, max) {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+function httpsUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
 // src/enrich/run.ts
 async function enrichCompany(ai, models, company) {
   const where = `${company.city ? `, ${company.city}` : ""}${company.region ? ` (${company.region})` : ""}`;
@@ -510,6 +673,27 @@ ${text}`,
   const { value } = await extractOnce().catch(extractOnce);
   return factsToFragment(company, value);
 }
+async function enrichPerson(ai, models, person, retrievedAt) {
+  const { text, citations } = await ai.search({
+    model: models.search,
+    system: PERSON_SEARCH_SYSTEM,
+    user: personPrompt(person),
+    maxTokens: 1200
+  });
+  const extractOnce = () => ai.extract({
+    model: models.extract,
+    system: PERSON_EXTRACT_SYSTEM,
+    user: `Person: ${person.name}
+
+Notes:
+${text}`,
+    tool: PERSON_EXTRACT_TOOL,
+    maxTokens: 4e3
+    // reasoning headroom before the forced tool call
+  });
+  const { value } = await extractOnce().catch(extractOnce);
+  return { ...personToFragment(person, value, retrievedAt), citations, notes: text };
+}
 async function resolveCounties(ai, model, rows, gazetteer) {
   const { value } = await ai.extract({
     model,
@@ -1215,7 +1399,11 @@ export {
   LOCATE_SYSTEM,
   LOCATE_TOOL,
   MODEL_TIERS,
+  PERSON_EXTRACT_SYSTEM,
+  PERSON_EXTRACT_TOOL,
+  PERSON_SEARCH_SYSTEM,
   Store,
+  WRITABLE_VERDICTS,
   addUsage,
   allJobs,
   asStepLike,
@@ -1226,6 +1414,7 @@ export {
   emptyUsage,
   enabledSources,
   enrichCompany,
+  enrichPerson,
   exportFragment,
   extractJson,
   extractJsonArray,
@@ -1238,8 +1427,12 @@ export {
   getProvider,
   htmlToText,
   humanAttrsOf,
+  identityKey,
   ingestFresh,
+  isHttpUrl,
   isLikelyPersonName,
+  isVerdict,
+  isWritable,
   jobsForHour,
   locatePrompt,
   locationFragment,
@@ -1249,6 +1442,9 @@ export {
   mergeScalar,
   naturalKeysOf,
   normalizeUrl,
+  normalizeVerification,
+  personPrompt,
+  personToFragment,
   resilientStep,
   resolveCounties,
   resolveName,
@@ -1256,6 +1452,7 @@ export {
   slugify,
   toSerializedSchema,
   urlHash,
+  validateLinks,
   writeFragment
 };
 //# sourceMappingURL=index.js.map