Language-independent policy is transcribed once per language

[jeremy]

Six idiomatic SDKs is the product, and six hand-written generators follow from it. That is not the problem. The problem is that language-independent policy is transcribed once per language, so a rule with one meaning has six implementations that can and do diverge.

Four instances surfaced in a single day:

• The emittable-verb set. Five verbs, copied into six generators plus generate-url-routes plus scripts/gen-catalog. An operation on any other verb was dropped from every SDK in silence (Generators iterate a five-verb list, so an operation on any other HTTP method is silently dropped from every SDK #925). Fixed in Find operations by what they are not, so no HTTP verb can drop one in silence #931 by removing the enumeration rather than correcting the copies.
• The declaration loaders. Once the verb set moved to spec/generated-verbs.json, six hand-written loaders disagreed about what the file means — five times, for five different reasons: Kotlin's jsonPrimitive.content coercing a number to text, Rust's filter_map dropping non-strings, Ruby's ASCII-oriented String#strip, Swift's String.allSatisfy being vacuously true for the empty string, and JavaScript's $ matching before a final line terminator. Three different predicates were tried; each relocated the disagreement rather than closing it. One validator, six readers: stop the generators disagreeing about the shared declaration #933 is in progress.
• The service split. SERVICE_SPLITS and TAG_TO_SERVICE are hand-transcribed in kotlin/.../Config.kt, kotlin/.../OperationParser.kt, python/scripts/generate_services.py, ruby/scripts/generate-services.rb, rust/generator/names.toml and rust/generator/src/naming.rs — then restated in SPEC.md and enforced by check-operation-assignment-parity, check-service-inventory-parity and sync-doc-constants.rb. Every retag this week (Tag the recordings operations as their own domain, and require a tag on every operation #922, Let the Recordings tag reach the Rust generator #928, Tag a recording's event history as Recordings, not Automation #929, Split the Automation catch-all into six real domains #930) had to edit all of them, and Split the Automation catch-all into six real domains #930's notes record that one table's usefulness depends on staying "eye-diffable" — a human-maintenance property standing in for a machine-checked one.
• Operation identification. Each generator decided independently what counts as an operation in a path item, which is what let additionalOperations be skipped silently in four of them (A refusal must not destroy generated output: fixed in Kotlin and TypeScript, swept across the rest #932).

The pattern is the same each time: the parity checks prove the six copies agree, but nothing prevents them from encoding the rule six ways in the first place, and a checker that compares copies cannot see a rule that every copy gets wrong identically.

The question worth deciding

For each policy below, should it keep N hand-written expressions with parity checks, or have one definition that the generators consume without re-deriving?

Policy	Expressed in	Current guard
Emittable verbs	(resolved — enumeration removed in #931)	—
Declaration validity	6 loaders	#933 in progress
Tag → service	6 generators + SPEC.md	3 parity checkers
Service splits	6 generators	3 parity checkers
Operation identification	6 generators	drift checks only

Not a proposal to collapse the generators. The generators should stay hand-written and idiomatic — that is why the SDKs are worth using. The question is only whether a rule that is the same in every language should be written in every language.

Why this is filed rather than fixed in passing

Each instance is individually small, which is how all four got written, and fixing them opportunistically inside whatever PR happens to surface one produces half-migrations. Worth deciding as a set, then sequencing.

[jeremy]

Declaration validity is resolved as a question, and the answer is not a validator

#933 attempted the row in the table above — one validator in front of six loaders — and is being closed rather than landed. It did not fail for want of finishing. It produced the evidence that the approach cannot work, and that evidence is worth more than the gate would have been.

Why one validator cannot define validity

Two findings settle it, and they are the same finding twice:

• jq accepts a stream of top-level JSON values. Two consecutive objects each carrying verbs pass the gate; Python's json.loads and TypeScript's JSON.parse reject the trailing data.
• jq accepts a UTF-8 BOM. The same two loaders reject it.

So the validator is a seventh implementation with its own JSON semantics. It cannot assert that a file is valid — only that it reads the file a particular way, and hope the other six agree. "Valid JSON" is not one thing across seven parsers, which is the whole premise failing on its own terms.

Patching those two was declined deliberately. They would have been predicates six and seven of the exact class the design existed to end — after Kotlin's jsonPrimitive coercion, Rust's filter_map, Ruby's ASCII strip, Swift's allSatisfy being vacuously true for "", and JavaScript's $ matching before a final line terminator. Five predicates had already relocated the disagreement rather than closed it; two more would have made the count seven and the lesson zero.

The second, independent failure: there is no "every path"

Placing the gate turned into an enumeration that reached eight entry points in two review rounds — the root *-generate targets, swift/Makefile and rust/Makefile's own generate, the release workflows, the standalone *-check-drift targets, and finally ordering within check-targets, where make -j can schedule the validator concurrently with the checks it is meant to precede. Plus the override splitting the gate from the generators: Ruby, Python and TypeScript honour BASECAMP_GENERATED_VERBS while Kotlin, Swift and Rust take --verbs or a default path their recipes never forward — so with it set, the gate validates one file and three generators read another.

Six languages, six Makefiles, six CI jobs, seven release workflows. A gate on every path is fighting the repository's shape, and the count is the argument rather than any single instance.

The resolution: a generated constant, not a validated input

Keep spec/generated-verbs.json as the single definition — that is #925's lesson and it holds. Stop reading it as an input. One emitter writes the verb list as a constant into each language's generated tree, and the drift gates that already exist prove each committed copy matches.

Every one of the six already has a committed generated directory produced by a generator and proven current by a regenerate-to-temp-and-byte-diff check: python/src/basecamp/generated, ruby/lib/basecamp/generated, typescript/src/generated, rust/basecamp-sdk/src/generated, swift/Sources/Basecamp/Generated, and Kotlin's 164 files. This is one more generated artifact riding machinery that is already in place on every path that generates.

What that dissolves rather than guards:

Open problem in #933	Under a generated constant
Seven parsers disagreeing about valid JSON	One parser. Validity means one thing to one reader.
BOM and JSON-stream acceptance	No shared file is read, so nothing can disagree about it
BASECAMP_GENERATED_VERBS splitting gate from generators	No override; nothing to forward
Eight generation entry points to gate	None. The drift checks are already on every generating path
make -j scheduling the gate concurrently	No gate to order

An earlier framing of this — "bake the verb set in at build time" — was rejected here on the grounds that three of the six languages have no build step. That objection killed the phrasing, not the idea: baking does not need a build step, only a committed generated file, which works identically in an interpreted language. The drift check is the build step.

The honest hole

The emitter still parses JSON, and if it mis-parses, no drift check can see it — the same emitter sits on both sides of the diff. That is real. What changes is the failure class: today six parsers can disagree and produce divergent SDKs silently, which is exactly #925. With one emitter every language receives identical bytes by construction, so a mis-parse becomes a uniform wrong answer visible in a committed diff at review time. Strictly better, and aimed at the failure that actually occurred.

Not urgent, and worth saying why

The exposure is latent: no operation in the committed spec uses a verb outside the five, so nothing has ever fallen through the hole this chain has been closing. The file is also a generation-time input, not a runtime one — no shipped SDK source reads it, only the six generators, scripts/gen-catalog, and the test harnesses. Nothing in a customer's process touches it.

So this should be sequenced with the rest of the table rather than rushed. main is fine as it stands.

Updating the row:

Policy	Expressed in	Status
Declaration validity	6 loaders	#933 closed — resolved as a generated constant, not a validator; unscheduled