feat(templates): lint keys the compiler ignores, at template compile (D67)

[angel-manuel]

Closes #539.

Why

A template document is an untyped serde_json::Value from parse_yaml all the way to compile_service, so a key nothing reads is not an error — it is nothing at all. services/metabase.yaml carried response_type: binary on export_query for months: a real concept, in a position that never reads it (the compiler derives the response type from responses:), so a large xlsx export was buffered against max_response_body_bytes and the only evidence was the absent prefer_stream hint. D57 fixed that instance. Nothing would have caught the next one.

Neither motivating bug is a misspelling, and that decided the scope. response_type is a ServiceAction field name and D55's resolve: is an alias, so a lint over x-overslash-* names alone would have caught neither — while a closed-world bare-key check alone would have missed x-overslash-download on an HTTP operation and every stray key at an open-world position. Each half misses the other's motivating case.

What

openapi::lint_extensions runs on the alias-normalized document at every validation entry point and reports four classes, each asked where as well as what:

Code	Catches
unknown_extension	an x-overslash-* name nothing reads, with a closest_match suggestion
misplaced_extension	a real extension at a position whose extractor does not read it
unprefixed_alias_ignored	the bare spelling where the normalizer does not rewrite it
unknown_template_key	an unrecognized bare key at a position whose fields we enumerate — this is what catches response_type:

Position comes from openapi::ext, and every extractor now reads through it. ext::get(obj, pos, ext) carries a debug_assert! against the READS matrix, so a reader added without its entry fails in its own unit test rather than teaching the lint to warn about a correct template months later. no_extension_getter_bypasses_the_accessor bans the obj.get("x-overslash-…") spelling in openapi/ production code. That mechanism earned itself during this PR: #550 landed x-overslash-icon on dev mid-flight, and the guard failed on the unregistered reader on the first run after rebasing.

Severity: warnings on every path, never errors

Both strict options are worse than the disease. An error at registry::load_from_dir means the template is skipped — a stray key would remove a service where before it removed a field. An error on create/update would make an already-active stored org or user template un-saveable by its owner, on tenant data nobody can survey, over a key that was inert the whole time.

So the teeth are in CI: shipped_services_lint_clean, filtered on LINT_CODES rather than warnings.is_empty() so an unrelated warning can neither disarm nor break the gate. And template_resolve lints the stored document into the resolution report the catalog already badges — the only place a row written before the lint existed is ever looked at, which is how the affected tenant population becomes visible without a migration or a grandfathering table.

The sweep

services/ was already clean — a strict closed-world scan over all 23 shipped templates found zero findings, confirmed by shipped_services_lint_clean passing on its first run. The real offenders were elsewhere:

• dashboard/.../templates/new/+page.svelte seeded x-overslash-prefix on a type: apiKey scheme. D35 removed that key and extract_api_key rejects it outright, so the default scaffold could not be saved at all. Nothing tested it, because it lived in a string literal in a component; scaffold_skeleton_is_valid_and_lint_clean now reads the skeleton out of the Svelte source so the two cannot drift.
• APIKEY_HTTP_SEC_ALIASES split into APIKEY_SEC_ALIASES / HTTP_SEC_ALIASES: extract_http_auth reads only default_secret_name and label, so normalizing template:/secret_source:/optional: onto an http scheme only ever produced a canonical key nothing then read.
• normalize_body_properties_in — the alias walk never descended into a request body's schema, though collect_body_parameters reads the canonical keys there. This is the HTTP twin of D55's input_schema fix, and a live behaviour change with zero shipped-template impact (all nine body-property annotations already use the canonical spelling).
• Two doc comments naming x-overslash-sql, a key that never existed (it is sql-field).

Path-item level stays un-extended on purpose: risk: hoisted out of a method is not a concept, so the lint reporting it is the right outcome.

Dashboard

Both surfaces were silent before. The editor footer claimed ✓ Valid over a list of warnings; the draft page rendered import_warnings and dropped validation.warnings entirely; the layer editor rendered warnings with no path.

The two fixes in 466fe09 came from looking at the screenshots: the message read "read on an MCP tool and an MCP tool" (two positions share a description on purpose), and the editor asserted ✓ Valid for a document it had never checked, since remote validation only runs on a document change.

Notes for review

• One deliberate deviation from the issue text. It asks for findings "reported through template_validation::validate_service_definition". That function takes the compiled ServiceDefinition, where extension keys no longer exist, so the lint runs in template_validation's three YAML entry points instead — the same wrapper layer that already owns check_duplicate_operation_ids for the same reason. Both consumers the issue names are reached: the shipped-template test and the user/org authoring path.
• Open-world positions are the design's load-bearing restraint. Request-body and MCP tool-input schema properties, a pasted discovered_tools snapshot, a platform-action param, and an unrecognized security-scheme type accept unknown bare keys, because their sibling keys are vocabulary we do not own. data_fields_sharing_a_concept_name_are_not_flagged pins the false positive that matters — a payload field genuinely named risk or template. The gate caught one such bug in the lint itself before merge: x-overslash-mcp.auth.provider is a read field that shares a name with an oauth2 scheme's provider alias, so a position's own fields now win over the extension vocabulary.
• TECH_DEBT.md records the one drift direction the accessor cannot close: a READS entry claiming a position no extractor reads makes the lint silent, and nothing detects that. Entries cite their reader lines, so it is reviewed, not proven.
• /vet --agentic clean. 693 core unit tests + 13 template_validation integration tests pass; cargo clippy --workspace --all-targets and svelte-check clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hpwv2iQAGpmQykiZDgj86F

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
overslash	Ready	Preview	Aug 12, 2026 5:39pm

[codecov]

Codecov Report

❌ Patch coverage is 95.26814% with 60 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...tes/overslash-core/src/template_validation/yaml.rs	84.46%	16 Missing ⚠️
...ates/overslash-core/src/openapi/extract/schemes.rs	80.00%	9 Missing ⚠️
...rates/overslash-core/src/service_layer/validate.rs	92.85%	8 Missing ⚠️
crates/overslash-core/src/openapi/lint/vocab.rs	94.87%	6 Missing ⚠️
crates/overslash-core/src/openapi/ext.rs	96.37%	5 Missing ⚠️
crates/overslash-core/src/openapi/compile.rs	84.21%	3 Missing ⚠️
crates/overslash-core/src/openapi/lint/walk.rs	96.05%	3 Missing ⚠️
crates/overslash-core/src/openapi/extract/mcp.rs	86.66%	2 Missing ⚠️
crates/overslash-core/src/openapi/lint/rules.rs	98.31%	2 Missing ⚠️
crates/overslash-core/src/registry.rs	33.33%	2 Missing ⚠️
... and 3 more

📢 Thoughts on this report? Let us know!