E12: Connector framework

[gnanirahulnutakki]

Goal. generalize the day-1 hand-written tool adapters into one out-of-process, typed, versioned connector framework — so integrations scale without the in-process, unversioned sprawl that drowned Backstage.

Phase / depends. fast-follow (P2 → P3) · Depends on: E2 (read adapters feed the fleet model), E4 (typed-action adapters host verbs). Build the day-1 six by hand first; generalize once the shape is proven — never a premature ecosystem.

Capabilities: connector framework — Argo CD / Flux / Helm / Prometheus / Loki + Grafana, Elasticsearch / Kibana / OpenSearch, Datadog, Splunk, GitHub; Jira / Zendesk ITSM (later).

Features

• F12.1 — out-of-process gRPC connector SDK
• F12.2 — the three connector kinds
• F12.3 — versioning + one-canonical-connector policy
• F12.4 — generalize the day-1 six

Exit criteria

• Connectors run out-of-process over a versioned gRPC protocol; a crash is isolated.
• Every connector is one of the three kinds; one canonical connector per tool.
• The day-1 six run on the framework with parity; further tools are demand-ranked, not eager.

---

Source: docs/EPICS.md, docs/SITH-NOTION.md · part of the Sith implementation backlog (see the master roadmap issue).

---

2026-07 research addendum (market research §2B/§2F, T6, T10; E2 spec §4 wave matrix, PR #43)

Integration-wave matrix (E2 spec §4). Connectors ship in four waves; each is scored by its verb subset (of the 7-verb contract), the lenses it feeds, its kind (RA read-adapter / BR brokered read-through / TA typed-action), an effort tier (T0–T3), and mode (local/hub/both):

• Wave 1 — daily core (ships with / right behind Phase L): Kubernetes (T0, the substrate), GitHub (T1, read local / gitops.open-pr hub), ArgoCD (T1, richest — 3 lenses + the diff exemplar), Prometheus (T1, query-through), Elasticsearch (T2, logs), AWS (T2, enum/cred). This is exactly the coverage the six brain rules (E14 E14: Investigation Brain (deterministic, rule-based, abstaining root-cause) #46) need.
• Wave 2 — desired-state/diff: Helm, Kustomize, kubectl-diff (desired-state readers; not action targets in v1).
• Wave 3 — viz/tracing/more clouds: Grafana (BR deep-link only), OTel (semconv key backbone), OpenShift, Azure, GCP.
• Wave 4 — long-tail: OpenSearch, Splunk, Fluentd/FluentBit (health-only, not a data source), Istio/Linkerd (mesh → depends-on GRAPH edges), Docker.

Scope-discipline call-outs (anti-drift, SCOPE §10):

• Fluentd/FluentBit are not data sources — read the sinks (ES/OpenSearch/Splunk/Loki), treat shippers as health-only workloads.
• Grafana is deep-link only — brokered read-through, never re-skinned (no iframe-Grafana trap).
• Helm/Kustomize are not action targets in v1 — desired-state readers only.
• T6: R4 config-drift borrows Kubevious's app-centric validation model; drift is the diff/plan verbs; keep drift read + PR, never auto-apply.
• T10: two-layer cloud abstraction (pure-K8s-API + thin enum/mint adapters) — conformance is uniform incl. China (ACK/CCE/TKE); only auth/enumeration differs.

Cost overlay stays a fast-follow (T8, → E13 #31): OSS fleet-rollup gap confirmed (opencost#2638) but crowded/commoditized — sequence after the moat proves out.

[gnanirahulnutakki]

Wave 1 GitHub coverage landed via #212 / #213.

dev merge: 4c1e194e795f5ee9f978f95d8390e3aaa7503397. Exact post-merge CI and CodeQL are green; Dependabot, code-scanning, and secret-scanning open queues are all zero.

Wave 1 now has bounded hand-written contracts for ArgoCD (#206), Prometheus (#209), and GitHub (#212), alongside the Kubernetes substrate. Per the anti-premature-abstraction guardrail, the out-of-process framework is still deferred until the remaining day-1 adapter shapes are proven.

[gnanirahulnutakki]

Wave 1 Elasticsearch evidence normalization landed via #214 / #215.\n\nThe pure projector accepts one already-fetched complete ECS Search API response, rejects partial/raw/ambiguous evidence, and emits at most three bounded Pod-attached R3 TELEMETRY cause facts without adding endpoint, credential, persistence, or mutation capability. The production boundary is structurally pinned after red-team review.\n\ndev merge: 4d1f067a9ef880e418715f31b4160af0d53009d2. Exact post-merge CI and CodeQL are green; Dependabot, code-scanning, and secret-scanning open queues are all zero.\n\nWave 1 now has bounded hand-written contracts for ArgoCD (#206), Prometheus (#209), GitHub (#212), and Elasticsearch (#214), alongside the Kubernetes substrate. The out-of-process framework remains deferred until the remaining day-1 adapter shapes are proven.

[gnanirahulnutakki]

Wave 1 AWS coverage landed via #216 / #217.

The final hand-written daily-core contract converts one already-fetched EKS DescribeNodegroup response into bounded LIVE inventory and provider-health facts for R6 without adding AWS network, credential, persistence, token-minting, or mutation capability. Identity and scaling invariants fail closed, regions are pinned to the currently documented EKS endpoint set, only reviewed closed taxonomies survive, and sensitive provider metadata is discarded. ACTIVE remains provider state rather than a Kubernetes-health claim.

CodeRabbit's valid static-credential and region-boundary findings were fixed before merge; final review had no actionable findings. dev merge: 2b402d2fd7ab430e1ed78cdda0bef9f6c85d5b63. Exact post-merge CI and CodeQL are green; Dependabot, code-scanning, and secret-scanning open queues are all zero.

The complete Wave 1 daily core is now represented by bounded hand-written contracts: Kubernetes substrate, ArgoCD (#206), Prometheus (#209), GitHub (#212), Elasticsearch (#214), and AWS (#216). This satisfies the evidence-shape prerequisite; the out-of-process framework still must respect E12's stated dependency on the typed-action shape from E4 and must not be generalized as an in-process plugin ecosystem.