refactor: move the mechanism band under internal/#178
Merged
Conversation
Top level now reads as the module's API surface: the agent facade, the ports a host implements or consumes, and the domain nouns. The 28 mechanism packages (parsers, guards, stores, probes, adapters) move to internal/, removing them from the public import surface before any external importers exist. The public set was derived mechanically, not by intuition: a go/types audit over the declared Band 1/2 packages found seven mechanism packages referenced in exported signatures (approval, brakes, bus, harness, hlc, jobs, netguard), which therefore stay public, and the audit closes at a fixed point with no further leaks. driver and inbox stay public as ports third parties implement; instance and archetype move internal because their kinds surface through the controlplane API as JSON, not Go types. Also updates the depguard deny path for spinesink, the rigor gate's grandfather and fuzz-required package keys, and rewrites the ARCHITECTURE.md sections that framed internal/ as deferred to v1.0: surface (internal/) and structure (depguard) are complementary controls, and the move is cheapest before ignition.
ion-alpha-dev
force-pushed
the
feat/repo-layout-v2-internal
branch
from
d6c3b92 to
d91e6d1
Compare
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 subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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
Moves the 28 mechanism packages (parsers, guards, stores, probes, adapters) under
internal/, so the top level reads as the module's API surface: theagentfacade, the ports a host implements or consumes, and the domain nouns. One commit,git mvrenames throughout sogit log --followtracks history.Why
Every exported package in a public Go module is formally API; before this change all 65 top-level packages carried that promise.
internal/removes the plumbing from the import surface (and from godoc) while the code stays world-readable, and doing it now, while the module has no external importers, is the cheapest this move can ever be.depguardkeeps governing layer direction;internal/governs the external surface - complementary controls, and ARCHITECTURE.md now says so instead of deferring the move to v1.0.The public set was derived mechanically, not by intuition: a
go/typesaudit over the exported signatures of the declared surface found seven mechanism packages that leak into public signatures (approval,brakes,bus,harness,hlc,jobs,netguard) - they stay public, and the audit closes at a fixed point with no further leaks.driverandinboxstay public as ports third parties implement;instanceandarchetypemove internal because their kinds surface through the controlplane API as JSON, not Go types.How to verify
dev/check(build, vet, race tests, lint) passes; the rigor gate's package keys and the depguard deny path forspinesinkare updated with the move.go docon any moved package now fails outside the module, and the packages listed in ARCHITECTURE.md's stability tiers are exactly the importable set.Notes for reviewers
No code changes beyond import paths, the two path-keyed config/gate updates (
.golangci.yml,internal/rigor), and the ARCHITECTURE.md/README rewrite. The linter's glob- and regex-based rules (**/hardware/**,(^|/)netguard/,(^|/)(clock|migrate)/) match underinternal/unchanged.