docs(e2): F2.1 source-abstract fleet model + connector/source-adapter contract (#38)#41
Merged
Merged
Conversation
Design the seam every integration plugs into: the 7-verb connector contract (discover/read/query/diff/plan/execute/verify) as idiomatic Go, translated from the incident-derived corpus dataclasses. - Capability-scoped interfaces (Reader/Differ/Planner/Executor/Verifier) so read-only sources implement only what they can do and the compiler proves what a connector supports. - Capability enum + Registry with fail-safe registration (a declared capability must implement its interface) and capability-based lookup; one canonical connector per tool, closed three-kind taxonomy (E12). - Normalized source-abstract model: ResourceRef, Evidence/Provenance, Fact, Query/Selector, Coverage, and the operational-graph shape (typed relations) that makes cross-cluster correlation first-class. - First adapter: local-kubeconfig as a Reader-only read adapter (discover/read/query) — list contexts, fan out across contexts, surface unreachable, credentials never leave the machine. - AsSource bridge keeps Slice-0's fleet.Source seam intact (no redefinition); Slice 1 swaps one injection line. - W1-W4 additivity table: adding a connector is one package + one Register call, zero changes above the seam. Spec-only; a builder implements Slice 1 (#38 + #32). Open decisions recorded in the doc, not blocking. Refs: #38, #20 Signed-off-by: Gnani Rahul <89947795+gnanirahulnutakki@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Design spec for F2.1 (#38) under epic E2 read federation (#20): the source-abstract fleet model and the connector / source-adapter contract — the seam every integration plugs into.
Adds one file:
docs/specs/F2.1-source-adapter-contract.md. Spec/design only — no product Go. A builder session implements Slice 1 from it.The interface design (summary)
7-verb contract → idiomatic Go, split by capability (not one fat interface):
ReaderDifferPlanner/Executor/VerifierCapabilityenum +Registrywith fail-safe registration: a connector must declare a capability and implement its interface — declared-but-unimplemented is a registration error; a read adapter can never be obtained as anExecutor. One canonical connector per tool; closed three-kind taxonomy (read-adapter/brokered-read-through/typed-action, from E12).internal/fleet:ResourceRef,Evidence/Provenance,Fact,Query/Selector, extendedCoverage(+Stale/Complete()), and the operational-graph shape (typedRelationedges) that makes cross-cluster correlation a first-class traversal.execute/plan/verifymap onto ADR-0004 (closed vocabulary, dry-run-first, PEP-only execution post-PDP). Never reachable from local mode.First adapter —
local-kubeconfig(Slice 1, #38 + #32): aReader-only read adapter.Discoverlists every kubeconfig context (surfacing unreachable, never fatal, exec-plugins run locally, creds never leave the machine);Queryfans out across contexts concurrently with honestCoverage.Stays additive: adding any W1–W4 connector = one new package + one
Registercall, zero changes above the seam. W1–W4 mapping table included.Relationship to Slice 0 (does not redefine the foundation)
Slice-0's
fleet.Sourcesnapshot seam is kept verbatim. The connector contract sits beneath it; a one-wayconnector.AsSource(Reader) fleet.Sourcebridge (dependency directionkubeconfig → connector → fleet, no cycle) letssith clustersconsume a real connector by changing one injection line.Notes for reviewers
SLICE-0-foundation.md,BUILD-SEQUENCE.md,CONVENTIONS.mdresolve once the parallel Slice-0 / build-plan branch merges intodev(this spec layers on that seam PR).devfor review per the branch model.Refs #38, #20