feat(blueprint): specify how an authored parameter binds to component inputs

[justinmerrell]

What changes

Blueprint §5 defined derivation in full and left the override path — the one §5.2 recommends — undefined. New §5.3 Authored parameters defines it: binding is by key, and three semantic rules follow. Along the way it fixes a live inconsistency that made §5.2's recommended remedy not actually remedy.

Also folds in the dev-container tooling fix that blocked task check locally, plus the two open dependabot bumps.

Why

Closes #20. Supersedes #33 and #34 (both cherry-picked here with dependabot's authorship intact).

The mechanism was already settled — by the platform, not by us

ParameterBindings.values is documented as "Keyed by the input key of each USER ComponentInput on the template", and one flat mapping is handed to every node, each taking the keys it recognises (blueprint/acl/component/adapter.py). Binding is by key, in one namespace shared across the graph. The seed importer confirms the override is wholesale — parameters = manifest.blueprint.parameters or _derived_parameters(manifest) — and performs no correspondence check at all.

So both of the issue's questions are genuine gaps in both projects rather than undocumented behaviour. This is the specification deciding, not transcribing.

§5.3 — three rules

A parameter MUST cover something — ERR_UNBOUND_PARAMETER at /spec/parameters/<key>. The install form asks a deploying user for a value and nothing in the composition reads it. §3 already makes exactly this argument about an unreferenced component document: permitted, these accumulate, and nothing says which entries are live.

An input the deploying user must supply MUST be covered — ERR_UNCOVERED_REQUIRED_INPUT at /spec/parameters. In scope when the input is USER-supplied, required, and carries no generator, no platformDefault and no schema.default — i.e. when nothing but a person can supply it. The mirror of ERR_UNWIRED_REQUIRED_INPUT on the CONNECTION side, and the same argument: no later chance to supply it.

type MUST agree — ERR_INCOMPATIBLE_PARAMETER_TYPE. Exactly the axis §4.2 chose for connections, and nothing else compared. format, enum, pattern, default, isSensitive and ui are recorded as silences in §4.2's own words. semanticType is not compared because a parameter has none — an install form is not where a value acquires a backing-service tag.

The isRequired trap, and why coverage tests guarantees rather than keys

isRequired defaults to true on a component input and to false on a blueprint parameter. An override that copies a required input's key and says nothing else has quietly made it optional.

Tested by key alone, the second rule would be evaded by the act of satisfying it: name the key, leave it optional, and the form still never compels the value. So a parameter covers such an input only if it guarantees a value — isRequired: true, or a generator, or a schema.default. semantic-018 is that case, and it is the one worth reviewing hardest.

A hole on the authored path that the derived path did not have

Component §6.1 obliges a generated input to declare schema.isSensitive: true, and §5.1 says a derived parameter takes the input's schema unchanged — so on the derivation path the marking is guaranteed. On the authored path it was not, and isSensitive defaults to false, so losing it took no more than not mentioning it. Now structural, both halves: an absent isSensitive is ERR_MISSING_FIELD and one written false is ERR_INVALID_VALUE — the same dual phrasing §4 already uses for spec.components.

Three findings worth a reviewer's attention

1. §5.2's recommended remedy did not work, and this PR is what makes it true. §5.2 tells an author that two components disagreeing on an input schema is resolved by writing spec.parameters outright. tools/src/semantic.ts never read spec.parameters, so checkInputMerge ran regardless and ERR_CONFLICTING_INPUT_SCHEMA fired anyway. §5 already said an override is "used in place of derivation rather than merged with it" — if derivation does not run, there is nothing to conflict. checkGraphAgainstItem now takes one path or the other.

semantic-020 is the regression pin: two nodes declaring one key with differing patterns, reconciled by an override. It fails against the previous implementation and passes now — verified, not asserted.

2. semantic-020 also shows the limit of the remedy. The two nodes disagree on pattern, not on type. An override can reconcile a disagreement below type; it cannot reconcile one about type, because rule three would then reject whichever half the parameter picked. That is the right boundary — a STRING and an INTEGER are not one value asked for twice — but it is a narrower remedy than §5.2's sentence implies on its own, so §5.3 states it.

3. The only published example of an authored override is unverifiable, and now says so. examples/web-and-database.yaml authors siteTitle against component documents that deliberately do not exist — examples/ carries no item root by design, so §5.3's rules cannot fire there. The block arrived with no comment at all. It now explains the by-key correspondence and why siteTitle is the only entry, so it teaches the rule rather than sitting beside it unexplained.

Tooling, in the same PR

actionlint was orphaned. Nothing in the repo installed it — not a Feature, not mise.toml, not any .devcontainer script. The binary answering on PATH was hand-placed, built for x86-64, and died with exec format error on this aarch64 host, so task check could not complete and #35 had to be pushed with --no-verify. It is now pinned in .devcontainer/mise.toml at 1.7.11 (matching ci.yml), resolved per-architecture and attestation-verified by mise.

verify_tools was checking the wrong property. It logged $("$cmd" --version || echo installed), which swallowed the failure — it would have called the broken binary installed. Being on the PATH is not what matters; being runnable is. It now fails on a non-zero --version, and actionlint and shellcheck join the verified list since task check runs both. Confirmed against a deliberately unrunnable binary.

Taskfile.yml also drops LEFTHOOK_VERSION and ACTIONLINT_VERSION, both dead — the latter a declared intent with nothing enforcing it.

Dependabot #33 and #34 are cherry-picked with -x and their original authorship. One loose end they left: the biome bump changed the CLI but not the $schema URL in tools/biome.json, so every biome ci run reported a version mismatch. biome migrate closes it in a separate commit.

Compatibility

• Breaking — a previously valid document now fails.

Three new semantic codes and one structural narrowing.

No new v<N> directory, and the reason is that v1 has never been published. git tag -l is empty and .github/release-please/manifest.json reads 0.0.0 for all three families, so component §3's guarantee has no released v1.0.0 to run from. This is #35's argument and #31's before it, with the same expiry: it dies the moment release PRs #1, #2 or #3 merge. This needs to land before them.

Corpus impact — checked, not assumed

Only two authored parameters blocks exist in the entire repository, and neither is affected:

• examples/web-and-database.yaml — validated with no item root, so no semantic rule reaches it.
• structural/005-nested-unknown-field — a case.yaml, so no item root either.

Every other occurrence in the corpus is the empty literal parameters: {}, which takes the derivation path and is untouched. semantic-009-conflicting-input-schema is empty too, so gating the merge leaves it green.

One thing to note downstream: the platform runs this corpus as a contract test (tests/contract/spec_conformance/test_blueprint_corpus.py) with a DivergencePin mechanism, so these three codes will surface there as new divergences until it implements them — relevant to open issue #24.

Checklist

• task check passes locally — including check:workflow, which is the point of the tooling half
• schemas/dist/ regenerated with task bundle and committed (never edited by hand)
• Conformance fixtures added for every behavioural change, each citing a clause
• Normative prose updated in the affected spec.md — schema descriptions are explanatory, not normative
• Commit messages are Conventional and correctly scoped (the scope drives release-please)
• Commits are DCO signed off (git commit -s)

7 new fixtures, 107 → 114 cases, 0 skipped. No new UNCOVERED entry — every code here is semantic or structural and therefore testable, unlike #35's capability code. Each negative fixture was run against the pre-change tree and confirmed to report "expected to fail but validated cleanly"; semantic-020 was confirmed to fail in the opposite direction.

Blueprint spec.md now carries no TODO sections at all. Only listing still does.

🤖 Generated with Claude Code