An audit with one question: is adding a fourth cloud cheap? Measured on
integration at 6ece38c (2026-08-10), with the three existing packs as the
sample.
Read the dates before the numbers. The body of this document is the 2026-08-10 measurement, kept as it was written. What has moved since is collected under Since the audit at the end: two of its five recommendations have landed, the packs have grown, and the one figure worth defending — zero provider-named code in
internal/core— is now held by a test instead of by an audit somebody has to redo. The rest of the numbers are a snapshot of a repository that has had a milestone happen to it, and should be re-measured before anything is concluded from them. They are a good sample because they disagree on everything a fourth provider could disagree on: Scaleway signs nothing and is redirected by one variable, Outscale signs the Host header of a POST-action API, Exoscale follows an address the server returns and writes its verbs inside a path segment (PUT /instance/{id}:stop).
The method matters as much as the verdict: grep finds 226 mentions of a
provider name in 47 non-test files outside internal/providers/, which reads
as heavy coupling and is not. 21 lines of them are code; the rest are
comments citing a measured example, which is this repository's documentation
style. The map below covers the 21, plus the non-Go surfaces (mise.toml,
workflows, conformance).
Headline first: internal/core contains zero provider-named code. All of
its mentions are comments. Rule 5 holds under measurement, including in
machine/ and cloudinit/, where provider differences are fields
(Binding.Prefix, Boot.User, AddressKey) that a fourth pack fills without
opening the package.
internal/proxy/redact.go redacts by name pattern: eight substrings
(auth, token, key, secret, signature, cookie, passw,
credential). The three known dialects are covered because their carriers
happen to be named X-Auth-Token and Authorization, and a test holds those
three by name. A fourth dialect is covered only if its header names happen to
contain one of the eight substrings. Real schemes exist whose credential
travels under a name that matches none of them (a consumer key, a session id,
an access header named after the vendor). feint proxy pointed at such a cloud
writes that value verbatim into the transcript.
This is the "well-formed is not authorized" family again: the rule validates the shape of a name where the property that matters is this value is a credential. The list being over-inclusive on purpose does not help a name it never sees.
Two remedies, smallest first:
- Allowlist request headers. Request headers are almost never load-bearing
in a transcript (
Content-Type,Accept,User-Agentare); redact every other request-header value by default and keep the pattern rule for bodies and responses. This is redaction by construction, the same propertyinternal/upstreamalready has by not recording request headers at all, and that package is the model here. The proving test records an exchange whose credential header matches no pattern and asserts the transcript carries no value. - Or an operator-declared carrier (
feint proxy --carrier X-Foo-Session), which works but is a control someone forgets exactly once.
Until one of them lands, the rule is: recording a client of an unknown cloud requires reading its auth scheme against the carriers list first. That is a comment where a control should be, which is why this section is first.
The healthy majority. All of it is keyed by Pack.Name() and consumed by
generic loaders:
| Surface | How the fourth pack plugs in |
|---|---|
| Routes, operations, refusals | Pack.Routes(), Route.Operation, Declined() |
| Environment for real clients | Pack.Env(); feint env iterates mounted packs and names a provider nowhere |
| Contract | contracts/<name>.json, generic contract.Load + drift.ScanContract |
| Coverage and baseline | coverage/<name>-{coverage,baseline}.json, generic reader/writer |
| Shapes catalogue | shapes/<name>.json, generic shape.Catalogue |
| Machine lifecycle | machine.Binding fields; the sequence is shared, the vocabulary is the pack's |
| What the runtime offers a pack | machine.PackSurface() — the closed list, eight service families; a gesture missing from it is a service the driver gains, never a call written around it |
| Probe | reads the contract, no provider code |
| Transcript / proxy / trace | provider is a string field in the exchange |
internal/cli/env.go is the reference implementation of the doctrine: it
derives everything from the mounted packs and states the test in its own
comment ("could this line be written identically for another provider?").
Eleven files, roughly 43 additive lines, none of which changes the behaviour of the three existing packs. Each entry says what would make it data, or why it should stay code.
Two entries this audit originally counted — hardcoded provider lists in
internal/cli/shapes_check.go and internal/cli/docs.go — were fixed on
2026-08-11: both now derive the list from the mounted packs, so a fourth pack
is covered by the shapes gate and printed by the banner by construction.
TestShapesCheckCoversEveryMountedPack holds the first; the second is held by
feint docs --check itself, which regenerates the banner from whatever
packsFor mounts.
| File | Edit | Remedy |
|---|---|---|
internal/cli/cli.go (packsFor) |
+2: import, one constructor | Keep. An explicit registration list beats init() magic, and it is the single mount point. |
internal/upstream/upstream.go |
+3: Provider const, one case in New |
Keep for now. The three dialect conditionals (if c.Provider == Outscale) are doctrine-compliant while exactly one provider deviates; the day a second POST-action provider arrives they become fields of a dialect struct, not before. |
internal/upstream/credentials.go |
+2 dispatch, then a reader (category 3 content) | Keep. Reading a CLI's config file is provider knowledge; the one-file-per-provider seam already exists (sign_*.go pattern). |
internal/upstream/reads.go |
+10 to 15 lines of curated data | Keep. The file says why it is curated, and the entries are data already. |
internal/cli/status.go:289 (productsOfProvider) |
+1 data row | Acceptable. Display-only and it degrades honestly (its comment says so). Could become a Pack method the day a second consumer appears. |
internal/cli/doctor.go (clients table) |
+1 row | Data row, keep. |
internal/cli/docs_clients.go |
+1 to 2 rows | Data row, keep. |
internal/cli/banner.go:100 |
+1 word | The comment explains the wording is deliberate; a human sentence is not a table. |
mise.toml |
~10 lines: upstream:sync source, conformance tasks | Additive task entries. |
tools/contract/update.sh |
~5 lines: one extract block |
Additive. |
.github/workflows/drift.yml |
~5 lines: checkout + one coverage call | Additive. |
One real duplication exists today, not hypothetically: the Outscale dialect
(key prefix, method, path) is written twice, in upstream.request /
operationName and again in shapes_check.callIdentity. Two callers, one
knowledge; a fix in one survives broken in the other, which is this
repository's named failure pattern. The remedy is one exported function in
upstream that both consume. Small, and it has its two callers already.
Measured against the Exoscale history (the honest baseline: bootstrap at 389ad0e, then 98f8df6 serving 30 more operations in one recorded session):
| Work | Measured cost |
|---|---|
| The pack itself | ~79 lines/operation including tests (Exoscale: 2 562 code + 1 076 test for 46 served ops). Ten operations: ~1 100 to 1 500 lines with scaffolding and catalogue fiction. |
| Signer | sign.go is 146 lines for three providers. Budget 40 to 90 lines, plus one trap: each of the three signatures hid one (a throttle disguised as a parameter error, a Host that must be signed, an order that must match the SDK). The fourth will have its own, and only the live cloud reveals it. |
| Credentials reader | ~50 to 70 lines (credentials.go is 237 for three). |
| Conformance suite | ~80 lines of shell at bootstrap (exo-cli.sh started at 79), growing with coverage. Depends on which real client the cloud has, which is a decision, not code. |
| Contract source | If the provider publishes OpenAPI: ~5 lines in update.sh, because the third pack already paid for the generic extractor (extract-outscale.py −132, extract-openapi.py +185) and ScanContract reads any contract.Doc. If it publishes something else: one converter, ~150 to 200 lines, after which everything downstream is unchanged. The scan is designed to host a fourth reader, not to have three. |
| One core dialect lesson | 2 of 3 packs taught the core one URL or body idiom (Outscale: the body consumed before the handler; Exoscale: {id}:action routing, +135 lines in emulator/table.go with its own test). Budget one such change; history shows it lands dialect-neutral and breaks nothing, but it is the least predictable line item. |
Largely industrial. A fourth pack serving ten operations and proving them costs, measured rather than guessed:
- ~43 additive lines across 11 shared files, none of which can regress the three existing packs (every edit is a new case, row, or task);
- ~1 500 lines in its own directory (pack, tests, conformance script);
- ~100 to 350 lines of adapters (signer, credentials, possibly a contract converter, possibly one core routing lesson);
- six classes of human decision: which real client proves it, the drift triage into served/declined, the catalogue fiction values, the curated read list, the credential carriers of its dialect, and (once the mechanism below exists) the field-level declines.
The Exoscale session served 30 operations, conformance green, in one recorded day (2 090 insertions, everything included). Ten operations for a fourth cloud is on the order of half such a session, provided the operator has an account to record against; without one, the shapes half of the proof does not exist.
What is not industrial today is three things, none structural:
- Make proxy redaction hold for dialects nobody has read (security, above). Allowlist request headers; prove it with a recorded exchange whose credential carrier matches no pattern.
- Give the shapes gate a way to record a decision. Done, 2026-08-13
(#91):
emulator.FieldDeclineis the transposition ofDeclined()to fields — declared in the pack via the optionalFieldDeclinerinterface,{operation key, field path, reason}, subtracted byfeint shapes --check, and counted in its output so a growing declined list stays visible. Pack-side code rather than a sidecar JSON, for the same reasonDeclined()is code: a decision needs a review path and a reason next to it, andshapes/*.jsonis regenerated, which is exactly where a human decision must not live. The six fields that kept the gate red are now declared: Scaleway'sper_volume_constraint.l_ssd(a constraint for local volumes the emulator never attaches, anddocs/limits.mdalready documents whymin_sizestays 0), and Exoscale'szones[].idandsecurity-groups[].visibility(live on the wire, absent from the published OpenAPI this emulator enforces as closed; the 98f8df6 commit message recorded the decision in prose, which is the one place a gate cannot read). The two Exoscale entries have since gone: #370 and #371 moved the contract instead, throughtools/contract/exoscale-recorded-fields.yaml, and the same staleness rule named below is what made deleting the declines compulsory once the pack answered the fields. A reason faces the same guard as an operation's (TestEveryDeclinedFieldSaysWhy), and a decline that excuses nothing fails the gate as stale (TestAStaleFieldDeclineFailsTheGate), so the list cannot rot. The gate is wired into every pull request — a go.yml step andTestTheRepositorysShapesAreServedOrDeclinedinsidego test— which was the point of building it. - Derive provider lists from mounted packs in
shapes_check.goanddocs.go. Done, 2026-08-11: both gates readsrv.Packs(), the patternenv.goalready used. "Invisible to the gate" became the honest "no catalogue; nothing to check", andTestShapesCheckCoversEveryMountedPackfails if the list is ever written by hand again. - Deduplicate the Outscale call identity between
upstreamandshapes_check(one exported function, two existing callers). - Watch, do not build: the day a second provider deviates from the
GET-a-path dialect in
upstream, fold the conditionals into a dialect declaration (fields, per the doctrine). With one deviant, theifis the honest form.
- Whether the fourth signature hides a fourth trap. Each of the three did, and each was found only against the live cloud. No account, no measurement.
- The conformance cost. It depends on which real clients the fourth cloud has (a CLI, a Terraform provider, both, neither), and that choice is the first human decision of the pack, upstream of any line of code.
- Whether the fourth URL idiom fits the router. Two of three did not; the budget above assumes one bounded lesson, but its size is the least certain number in this document.
- The shapes proof end-to-end for a hypothetical pack:
--recordrequires an account by design, so a fourth pack built without one ships with the gate honestly saying "nothing to check", which recommendation 3 at least makes visible.
Re-read on 2026-08-17, one milestone later. Only what changed is listed; the body above stands as the 2026-08-10 measurement.
Recommendation 4 has landed. upstream.OutscaleCall(action) (key, method, path) exists, and shapes_check.callIdentity calls it: the dialect is written
once and its two consumers read the same function. That was the audit's one
real duplication, named as this repository's failure pattern, and it is gone.
Recommendations 2 and 3 were already marked done in the body. What is left open
is 1 (proxy redaction for a dialect nobody has read) and 5 (watch, do not build),
and 1 is still the one with a security consequence.
The headline figure is now a control rather than a claim. "internal/core
contains zero provider-named code" was true on 2026-08-10, true again on
2026-08-17, and until now nothing would have noticed it stop being true.
TestTheCoreNamesNoProvider (internal/cli/discipline_test.go) walks every
non-test file under internal/core and fails on a provider name in an identifier
or a string literal. It is falsified by reintroducing the exact defect an audit
once found — the event filter listing "scw-", "osc-", "exo-" — and it
reports all three.
The rule it holds was reworded, because this document refuted the old one.
architecture.md claimed nothing outside a pack's directory should need to
change, while the map above counts eleven shared files. Both were defended and
only one could be true as written. What holds is narrower:
Adding a provider requires no behavioural change to
internal/core; the external registration and integration points may receive additive data.
The size figures are stale, and by a lot. The packs on 2026-08-17, code and test lines counted the same way as the body:
| pack | code | test | operations mounted |
|---|---|---|---|
| Scaleway | 8 713 | 6 093 | 102 |
| Outscale | 8 299 | 5 315 | 85 |
| Exoscale | 4 549 | 2 542 | 72 |
The body's "~79 lines per operation including tests" came from Exoscale at 46 served operations; the same pack now sits at ~98 for 72, and the three together average ~137 (35 511 lines over 259 operations). The per-operation cost has gone up, not down, which is what should be expected as the cheap operations get served first and the shared proofs get finer — every route now owes a contract check, a shapes comparison, an evidence row, and either a client or a stated reason (#174). None of that existed at the ratio the body quotes.
What still has not been measured, and is the reason this section is not a
new audit: the eleven-file, forty-three-line figure for the shared surface. It
requires judging, file by file, whether a fourth pack would have to edit it, and
the answer moved when packsFor, the shapes gate and the docs banner started
deriving their lists from the mounted packs. Re-measure it before quoting it.
Added 2026-08-27 (#517). Everything above is paper, and this document says so about itself in two places: the walkthrough of what a fourth pack provides, and the honest note that no fourth signature has ever been measured. Paper rots. What changed is that the dataplane half of the walkthrough no longer can.
internal/cli/testdata/provider-four/ is a fourth provider that does not
exist — an imaginary minimal cloud with nodes, segments, barriers, anchors and
spreaders — which drives the whole runtime dataplane through the shared
contract alone: it boots a machine, declares a network and joins it at boot and
after boot, publishes and withdraws a public address, hands a rule set over and
re-expands it, asks for a balancer, and keeps two subnets apart. It names no
runtime, and it could not name the driver if it tried: since #511
emulator.Env hands out no driver value, and since #514 there is no exported
name for one — var _ machine.Driver in a pack fails the build, which it did
not until then.
Three things it is deliberately not:
- Not OVHcloud. OVH is the intended fourth pack and nothing of its API has been measured in this repository, so a fake shaped like OVH would be measuring a belief. This one depends on no trait of any real cloud; when the OVH pack starts, this is the recipe it reads and never the model it copies.
- Not a served pack. It has no routes and no wire dialect, is never
mounted, and proves the contract's shape rather than wire fidelity. The polar
star stays with
scw, theexoCLI and Terraform. - Not counted by any instrument. It lives under
testdata/, which Go's./...patterns skip — measured, not assumed:go build ./...does not build it andgo list ./...does not name it, so no coverage, evidence or drift artefact can ever carry a fourth provider that has no upstream SDK. An explicit import still resolves, which is how it compiles at all.
What it is judged by, with no exemption of its own:
TestNoPackReachesPastTheDeclaredDriverSurface (#511) and
TestNoPackKnowsWhichRuntimeIsBehindTheDriver (#516) read it beside the three
real packs, and TestSameIntentSameRuntimeSequenceAcrossPacks (#510, #515)
compares the sequence it asks of the runtime against theirs, on both intents of
the corpus — identical. That comparison is the one worth the lot: the three
real packs were migrated onto the shared order, so each of them knows what it
used to write by hand; Provider Four never wrote one, and still produces the
same sequence.
What it had to supply, and therefore what a real fourth pack will: its binding fields, its plan, its firewall translation and the four enumerators around it, its isolation predicate, its balancer's shape, its own address planning — the runtime contract has no opinion on that last one at all — and every call site, because the contract can refuse a gesture and never require one.
What it received without writing a line: the machine's host-side name and the ownership check on it, the boot order (addresses, then memberships, the firewall last), the published state being the one the effect produced, the refusal to route an address outside its own block, the conditional write-back a delete racing a launch cannot lose, the re-expansion of every rule set a booted machine's groups are named by, the network name recorded only once the runtime accepted it, and the report of what a balancer hand-off actually delivered.
What it can still forget, stated rather than hidden — and each held by a
named test with a planted red in tools/falsify/specs/provider-four.json
rather than by this paragraph:
| forgettable | why nothing can force it | held by |
|---|---|---|
| handing a changed rule set to the host (#475) | only the pack knows its rules changed | TestTheFourthPacksRuleChangeReachesTheRuntime |
| re-expanding the rule sets that named a deleted machine | only the pack knows a machine's groups are gone | TestTheFourthPacksDeleteReExpandsTheBarriersThatNameIt |
| declaring a public block wide enough to cover the host's own network | the guard enforces the block the pack declared | TestTheFourthPackRefusesToRouteAnAddressOutsideItsOwnBlock |
| a wrong isolation predicate | what "may reach" means is upstream knowledge | TestTheFourthPacksSegmentsReachEachOtherOnlyInTheSameRealm |
copying a nested Attrs value before writing it |
resource.Clone shares it with the store |
TestTheFourthPacksNestedAttributesAreNeverWrittenThroughTheStore |
reading a stored number back with a plain .(int) |
Attrs is map[string]any, so a restore yields float64 |
TestTheFourthPacksSpreaderKeepsItsPortAcrossASnapshot |
The first two are #514's named residue, and they are the honest answer to the milestone's own question: forgetting is not made impossible, it is made visible in more than one place.
The last row is the one the list did not predict, and it is the most useful
thing the exercise produced, because the fake pack did not merely risk it —
it committed it. res.Attrs["port"].(int) is what anybody writes, and after a
feint snapshot load it yields zero: a balancer listening on port 0 while the
API still describes 443. It is a rediscovery. exoscale/privatenetworks.go
carries intOf with the sentence "tolerating the float64 a snapshot restore
produces", and the two other real packs do not — outscale/volumes.go and
outscale/snapshots.go read Attrs["Size"].(int) at three sites, where it
costs a shrink refusal that no longer fires, a volume that publishes no size,
and a snapshot recording VolumeSize: 0 (#542). A lesson living in one pack of
three is a lesson a fourth pack cannot inherit, which is #475's shape one
storey below the runtime contract.
A second one came out the same way: a pack that declares GroupSync without
wiring its fields panics on the first boot, and only under a runtime — so
--vm off, which is the default and the whole CI matrix, is exactly the mode
that cannot see it (#543).
The rest of this document — the surface, the wire vocabulary, the drift reader and the versioned baseline a fourth provider also owes — is untouched by #517 and stays paper.