@odla-ai/kg 0.5.0 → 0.6.0

package/README.md

@@ -103,10 +103,153 @@ site, blog, Substack, LinkedIn, X/Bluesky, GitHub, employer, and business contac
 points the person or their employer published. Never home addresses, personal
 phones, or personal email.
 
+## Grading, not self-reported confidence
+
+`gradeSources()` derives how well an identity is established from the sources
+that were actually checked, rather than from what a model said about its own
+certainty. Measured, that number is not evidence: across real runs every lane
+confirmed between one and three of four people who do not exist, confidently.
+
+```ts
+const report = gradeSources([
+  { sourceUrl: "https://acme.example/team", sourceClass: "first-party",
+    facts: ["employer", "title", "location"], verifiedOn: "2026-08-03",
+    corroboration: "confirmed" },
+  { sourceUrl: "https://press.example/x", sourceClass: "third-party",
+    facts: ["employer"], verifiedOn: "2026-08-03", corroboration: "confirmed" },
+]);
+// → { grade: "high", independentSources: 2, hasAnchor: true, reason: "…" }
+```
+
+`high` needs independent sources — two pages of one site agree by construction —
+with at least one **first-party or authoritative** anchor and enough agreeing
+facts, and no source naming somebody else. `DEFAULT_STANDARD` is those
+thresholds; pass your own `GradeStandard` to tighten them without touching code.
+Worth knowing before you act on `medium`: two third-party sources agreeing about
+a person who does not exist reached it in a real run, which is what
+`anchorRequiredForMedium` exists to close.
+
+`unverifiable` is deliberately distinct from `unresolved`. In one run 60 of 93
+claimed URLs came back unreachable, almost all login walls. Calling those "not
+established" blames the search for a wall it cannot walk through, and calling
+them established would be a lie.
+
+Sources are what you store; the grade is computed. That ordering is the point —
+changing the standard re-scores stored evidence instead of re-running inference.
+
 Use `identityKey` (not `slugify`) to decide whether two records are the same
 entity: it folds away punctuation, accents, `&`, and trailing legal suffixes, so
 "Acme Corp.", "Acme, Inc." and "Acme & Co" agree.
 
+## Strategies: gather evidence several ways, grade it once
+
+A single research call is the wrong unit. Measured over real runs, a grounded
+research pass found 14 of 18 real people — and also "confirmed" one of four
+people who do not exist. Walking the employer's own website found only 5 of 18,
+and confirmed none of the four, because a company's site does not contain
+someone who does not work there.
+
+They fail in opposite directions, so `investigatePerson` runs several and lets
+`gradeSources` settle it. Composed, the two above reached `high` on 16 of 18,
+with none of the four fabricated people getting there — a bar neither clears
+alone.
+
+```ts
+import { investigatePerson, researchStrategy, orgSiteStrategy, targetedProfileStrategy } from "@odla-ai/kg";
+
+const result = await investigatePerson(
+  {
+    person: { slug: "abbey-chrystal", name: "Abbey Chrystal",
+              companyName: "Rhizos", companyWebsite: "https://rhizos.example" },
+    retrievedAt: "2026-08-03",
+    ai, models: { search: "…", extract: "…" },
+    readPage,          // see below
+  },
+  [researchStrategy, orgSiteStrategy, targetedProfileStrategy],
+);
+// → { grade: "high", sources: [...], links: [...], findings: [...], skipped: [] }
+```
+
+Strategies run concurrently and are isolated: one that throws becomes a
+`Finding` carrying its error, so a search provider being down costs you that
+strategy's evidence rather than the first-party page another already read. One
+that cannot run — `orgSiteStrategy` with no `companyWebsite` — reports itself
+inapplicable instead of pretending to have checked, and is named in `skipped`.
+
+A strategy never decides whether the person was found; it reports what it saw
+and how strong the source was. That split is why adding a strategy cannot
+inflate a verdict, and why `researchStrategy` enters its sources at `name-only`
+at best however confident the model sounded.
+
+`readPage` is yours to supply, deliberately. Fetched pages are attacker-
+influenced, so kg never reaches for the network itself and cannot quietly bypass
+whatever boundary you chose. In odla that is `@odla-ai/camel`'s artifact
+ingress, which caps bytes, screens redirects for SSRF, and labels the body
+`Unsafe`:
+
+```ts
+const web = createWebArtifactIngress({ ingress, readers, limits: { maximumBytes: 512 * 1024 } });
+const readPage = async (url: string) => {
+  try { return (await web.fetchArtifact(url)).body.value; } catch { return null; }
+};
+```
+
+## A person's key should not be their name
+
+kg has been writing person nodes keyed on `slugify(name)`, and that fails in
+both directions. Two people called John Smith at two companies collapse into one
+node, silently merging their employers, links, and evidence. And a person whose
+name is written differently by the next source — a married name, an accent
+restored, "Bob" where the last pass saw "Robert" — mints a second node that
+nothing will reconcile.
+
+`identifyPerson` mints an opaque key once and indexes the ways that person is
+recognized alongside it:
+
+```ts
+const { personKey, minted, fragment } = await identifyPerson(
+  db,
+  { aliasType: "person_alias" },
+  person,
+  result.links,
+  result.fragment,   // keyed on person.slug, as personToFragment produces
+);
+await writeFragment(db, fragment, ontology, mutationId);
+```
+
+The fragment comes back rekeyed onto `personKey`, with every edge that touched
+the old key moved with it, plus one alias row per alias. Those rows are what
+make the next pass idempotent — without them a minted key would be re-minted
+every run, which is strictly worse than the name key it replaces.
+
+Alias order is the contract. A public profile belongs to the person and survives
+them changing jobs, so `linkedin:/in/abbeychrystal` is tried before
+`name:abbeychrystal~rhizosviticulture`. The name alias includes the employer
+because that is what tells namesakes apart; it is the bootstrap for someone with
+no profile found yet, and they graduate off it as soon as any pass finds one —
+the new profile alias attaches to the key they already have.
+
+A person with no employer *and* no profile gets no alias at all, so every pass
+mints them a fresh key. That is deliberate: duplicates are recoverable, a merged
+pair of strangers is not.
+
+**Adopting it.** The alias entity is yours to declare — kg reads and writes it
+through the names in `PersonIdentityConfig` — so add one to your ontology with a
+unique natural key and an attribute holding the person key:
+
+```ts
+person_alias: {
+  naturalKey: "alias",
+  attrs: { alias: { type: "string", unique: true }, personKey: { type: "string", indexed: true } },
+}
+```
+
+Existing graphs keep working: `personToFragment` still keys on `person.slug`,
+and nothing changes until you call `identifyPerson`. To migrate, backfill one
+`name:` alias row per existing person pointing at their current key, then start
+identifying — already-keyed people resolve to themselves and pick up profile
+aliases as passes find them.
+
 ## Provenance & merging
 
 `writeFragment` reads existing nodes by natural key (one batched query), merges