feat(kt-graph): PublicGraphBridge + WorkerGraphEngine wrapping

[charlie83Gs]

Summary

PR4 of the multigraph public-cache series. Lays down the standalone PublicGraphBridge module and wires it through WorkerGraphEngine + WorkerState so PR5's workflow integration is a one-line plumbing change per call site.

What's new

libs/kt-graph/src/kt_graph/public_bridge.py (new)

Standalone bridge with three entry points:

• lookup_cached_source(canonical_url, doi) — read-only query against the default graph's write-db. Returns a detached CachedSourceImport snapshot (raw source + facts + fact_sources + concept/entity nodes + their embeddings) so it can cross worker boundaries safely.
• import_cached_source(snapshot, target_write_session, target_qdrant_prefix) — writes the snapshot into the target graph: upserts the raw source by content_hash, dedups facts against the target Qdrant fact collection (0.92 atomic / 0.85 compound), mirrors fact_source rows, and concept-similarity-matches each cached node against the target node collection (threshold from Settings.public_bridge_concept_match_threshold, default 0.93). Misses create new write_nodes rows with deterministic keys. Compensating Qdrant deletes on partial failure.
• contribute_source_and_facts(raw_source_id, source_write_session, source_qdrant_prefix) — pushes a freshly-decomposed source + its facts upstream to the default graph. Sources and facts only — node structure is NOT contributed (the public graph runs its own pipeline on the accumulated fact pool). Best-effort, all errors swallowed.

⚠️ The bridge is write-db only on both sides — workers never touch graph-db. CachedSourceImport is plain data (no live ORM rows) so the lookup session can close before the import session opens.

libs/kt-graph/src/kt_graph/worker_engine.py

Three pass-through methods on WorkerGraphEngine (lookup_public_cache, import_from_public, contribute_to_public). Each no-ops gracefully when _public_bridge is None — that is the universal "skip" signal so workflow code stays free of self-reference guards. The engine fills in its own session + Qdrant prefix on every call.

libs/kt-hatchet/src/kt_hatchet/lifespan.py

WorkerState now carries default_graph_id (resolved once at startup from graphs.is_default = TRUE) and exposes a make_worker_engine() factory that constructs a PublicGraphBridge only when the current graph_id differs from default_graph_id. Every worker (ingest/bottomup/nodes/synthesis) inherits cross-graph capability for free through this single factory — no per-workflow wiring.

libs/kt-config/src/kt_config/settings.py

Two new fields under a new public_bridge YAML section:

• public_bridge_concept_match_threshold (default 0.93) — high on purpose; false matches collapse distinct concepts which is far worse than the cost of an occasional duplicate that the local dedup pipeline merges later.
• public_cache_refresh_after_days (default 365) — cache hits older than this still serve immediately but flag the snapshot as stale. The async refresh workflow itself lands in PR7.

libs/kt-hatchet/pyproject.toml

Adds kt-graph as a workspace dep. No cycle (kt-graph never imports kt-hatchet — verified with grep).

Test plan

libs/kt-graph/tests/test_public_bridge.py — 13 unit tests (mocked sessions + Qdrant) covering:

• Engine pass-throughs no-op when bridge is None (lookup → None, import → None, contribute → no raise).
• Engine delegates to the bridge with the correct session + prefix when one is wired.
• lookup_cached_source short-circuits cleanly: missing keys, no Qdrant, resolver failure → all return None.
• Happy-path lookup with mocked sessions + Qdrant → returns a fully populated CachedSourceImport with embeddings on facts and nodes.
• Staleness threshold: zero disables, recent is fresh, ancient is stale, None retrieved_at is fresh (defensive).

Full end-to-end integration with a real schema + Qdrant lands in PR5 when the bridge is wired into ingest.py.

• uv run --project libs/kt-config pytest libs/kt-config/tests/ -q — 35 passed
• uv run --project libs/kt-db pytest libs/kt-db/tests/ -q — 205 passed
• uv run --project libs/kt-hatchet pytest libs/kt-hatchet/tests/ -q — 40 passed
• uv run --project libs/kt-graph pytest libs/kt-graph/tests/ -q — 86 passed (13 new)
• CI all green

PR sequence

1. PR1 — Provider classification ✅ feat(kt-providers): classify search/fetch providers as public or private #186
2. PR2 — Canonicalization helpers ✅ feat(kt-providers): canonical URL + DOI helpers for multigraph cache lookup #187
3. PR3 — Schema migrations ✅ feat(kt-db): graph public cache toggles + raw_source canonical_url/doi #191
4. PR4 — PublicGraphBridge + WorkerState wiring ← this PR
5. PR5 — Ingest workflow integration (cache check + contribute hooks + refresh_public_source_wf scaffold)
6. PR6 — API surface + Frontend
7. PR7 — Robustness/sweeper + refresh workflow

🤖 Generated with Claude Code

[github-actions]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}