Skip to content

feat(plugins): backend-engine-source-cache plugin (Phase 5 #50)#285

Merged
charlie83Gs merged 1 commit intomainfrom
feat/backend-engine-source-cache-plugin
Apr 21, 2026
Merged

feat(plugins): backend-engine-source-cache plugin (Phase 5 #50)#285
charlie83Gs merged 1 commit intomainfrom
feat/backend-engine-source-cache-plugin

Conversation

@charlie83Gs
Copy link
Copy Markdown
Contributor

Summary

  • Third Phase-5 provider plugin: plugins/backend-engine-source-cache/
  • Contributes public-graph SourceCacheProvider matching GraphTypeComposition.source_cache on the default graph type
  • Wraps existing PublicGraphBridge read path exposed on WorkerGraphEngine (lookup_public_cache / import_from_public) — zero behaviour change

What changes

  • PublicGraphSourceCacheProvider implements the SourceCacheProvider ABC. Constructed once per worker; initialize(services) stashes the CoreServices container for idempotent re-init.
  • Per-call engine resolution: each lookup / import_into_target resolves a freshly-bound WorkerGraphEngine for target_graph_id via services.graph_engine(target_graph_id). The engine already carries the right bridge (or none — both calls no-op per contract).
  • Engine's raw ImportResult gets packed into the typed SourceCacheImportResult at the boundary so observability dashboards line up with the ABC.
  • Degraded / malformed results (stale snapshot, missing raw_source_id) resolve to None + log — matches ABC's "cache miss is a degraded result, not an error" contract.
  • Fail-fast on lookup before initialize: silent None would mask wiring bug as indistinguishable from upstream down.
  • ctx.source_graph_id advisory for now — engine binds to default-graph upstream at construction (today's WorkerState.make_worker_engine hardcodes). Custom compositions that want a different upstream need bridge itself to accept source id — follow-up.
  • Registered in kt_config.plugin.load_default_plugins. No worker wiring this PR — mirrors definition / sync plugin-then-wire sequencing.

Test plan

  • uv run --project plugins/backend-engine-source-cache pytest -x -v (12 contract tests green — plugin identity, is_enabled, contribution id, registry round-trip, initialize idempotency, lookup + import delegation, no-bridge no-ops, degraded engine results, not-initialized fail-fast)
  • uv run --project libs/kt-config pytest -x -v (236 green)
  • uv run --frozen ruff format --check . / ruff check .
  • Pre-push hook ran full unit test suite — all green

🤖 Generated with Claude Code

Ships `plugins/backend-engine-source-cache/` — contributes the
`public-graph` `SourceCacheProvider` behind
`GraphTypeComposition.source_cache` on the default graph type.

`PublicGraphSourceCacheProvider` wraps the existing
`PublicGraphBridge` read path already exposed on every
`WorkerGraphEngine` bound to a non-default graph
(`lookup_public_cache` / `import_from_public`). Registry lookups
resolve to an identical cache hit/miss path — zero behaviour change
for existing graphs.

Per-call engine resolution: `initialize(services)` stashes the
`CoreServices` container; each `lookup` / `import_into_target`
call resolves a freshly-bound `WorkerGraphEngine` for
`target_graph_id` via `services.graph_engine(target_graph_id)`.
The engine already carries the right bridge for that graph (or none,
in which case both calls no-op per contract).

Engine's raw `ImportResult` gets packed into the typed
`SourceCacheImportResult` at the boundary so observability
dashboards line up with the ABC. Degraded / malformed results
(stale snapshot, missing raw_source_id) resolve to `None` + log —
matches the ABC's "cache miss is a degraded result, not an error"
contract.

`ctx.source_graph_id` is advisory in this implementation: the
engine binds to the default-graph upstream at construction time
(today's `WorkerState.make_worker_engine` hardcodes that binding).
Custom compositions that want a different upstream target will need
the bridge itself to accept a source id — tracked as a follow-up.

Fail-fast on lookup before initialize: silent `None` would mask
a wiring bug as a cache-miss indistinguishable from upstream down.

Registered in `kt_config.plugin.load_default_plugins`. No worker
wiring this PR — mirrors definition / sync plugin-then-wire
sequencing.

Tests: 12 contract tests pinning plugin identity, `is_enabled`
default, contribution id, registry round-trip, `initialize`
idempotency, lookup + import delegation, no-bridge no-ops, degraded
engine results, and not-initialized fail-fast.
@charlie83Gs charlie83Gs merged commit e5790f3 into main Apr 21, 2026
30 checks passed
@charlie83Gs charlie83Gs deleted the feat/backend-engine-source-cache-plugin branch April 21, 2026 18:24
@github-actions
Copy link
Copy Markdown


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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant