M2: deterministic validation (upstream Validate() + tinkerdown semantic checks)

[adnaan]

Milestone M2 — deterministic validation, executed per the plan's convention 9 (design expanded at kickoff, then implemented). Four commits: the design expansion, an upstream-release record, and two tinkerdown phases.

What M2 delivers

tinkerdown validate now catches the whole "passes validate, silently breaks at serve" class the M1 Learn kept hitting — and, crucially, the generation context (llm-system-prompt.md/SKILL.md/reference.md) already teaches what the validator now enforces, so the two agree: this is first-pass generation reliability, not just more diagnostics.

Phase 1 — upstream livetemplate.Validate() (released v0.21.0)

The structured, line-numbered parse/reactive-AST diagnostics live in livetemplate's internal/parse (unreachable downstream) and its render path swallows them. livetemplate#519 added Validate(templateText) → []Diagnostic built on the internal primitives, shipped as v0.21.0. Recorded here (commit 984d3b9); no tinkerdown code in this phase.

Phase 2 — tinkerdown consumes Validate() per block (addda7e)

• validate runs each lvt block through livetemplate.Validate() — an unclosed {{range}} now fails with line N: message instead of surfacing only at serve as a silently-dropped block.
• Dropped the /tmp/lvt-*.tmpl temp-file dance for an in-memory WithParseFS (same parseSources path, disk-free).
• The check immediately found a real bug (markdown-data-bookmarks used {{split}}, registered nowhere) → added split as tinkerdown's first base block helper, wired to reach both parse and tree-gen.

Phase 3 — tinkerdown-owned semantic checks (b185ed0)

• Bound-refs — a used lvt-source must resolve to a declared source (per-app config).
• Action-param completeness — every :param a kind:sql action references must be supplied by a form field or data-* (:operator exempt); over-inclusive to bias toward a safe miss.
• State-ref diagnostic now teaches lvt-source, not the undefined state="block-id".
• lvt-persist reports a migration hint.
• The :name scanner is extracted into one scanParams shared by SubstituteParams (runtime) and ReferencedParams (validate) — single source of truth.

Verification

examples/ corpus 55/55, skill corpus 10/10, full suite green (incl. the PII approve→ExecTx→audit e2e through the refactored SubstituteParams). Every new guard has a verified-to-fail test. Each phase's tracker + Learn is in docs/plans/2026-07-09-ephemeral-ui-reframe.md.

Follow-ups noted in the Learn (out of scope)

• Docs llms.txt/playground.html still teach lvt-persist (not corpus-validated); the client-bundle getAttribute("lvt-persist") vestige rides with a client release.
• Field-name/schema validation (.RowCap casing) re-sequenced to M3 — it needs source-schema introspection.

🤖 Generated with Claude Code

https://claude.ai/code/session_018M9pJSPmG6i1D8s6rpEV4h

[claude]

Review: M2 deterministic validation

Nicely scoped PR — the phase split (upstream `Validate()` → per-block consumption → tinkerdown-owned semantics) is clean, the `scanParams`/`ReferencedParams` extraction removes real duplication, and the corpus-as-false-positive-gate discipline shows in the Learn notes (the per-app `sourceConfigForFile` fix is a good catch of exactly the kind of bug this milestone exists to prevent).

Bug: `unsuppliedActionParams` misses frontmatter-declared actions

`cmd/tinkerdown/commands/validate.go:654-684` (`unsuppliedActionParams`) only looks up actions in `fileConfig.Actions` (the `tinkerdown.yaml` map):

```go
func unsuppliedActionParams(page *tinkerdown.Page, fileConfig *config.Config) []string {
if page == nil || fileConfig == nil {
return nil
}
...
for _, actionName := range page.Refs().Actions {
action, ok := fileConfig.Actions[actionName]
if !ok || action.Kind != "sql" {
continue
}
```

But `kind: sql` actions can also be declared in page frontmatter (`PageConfig.Actions`, populated at `page.go:257-268`), and those are real, executable actions — `internal/server/websocket.go:1287` (`getPageActions`) merges `h.page.Config.Actions` into the actions a page can invoke at runtime, and they go through the same `SubstituteParams` call that this check exists to guard. Since `unsuppliedActionParams` never consults `page.Config.Actions`:

1. A frontmatter action referenced by name in `page.Refs().Actions` but absent from `fileConfig.Actions` just `continue`s — silently skipped, not just under-checked.
2. Worse, the early return `if page == nil || fileConfig == nil { return nil }` means a document with no governing `tinkerdown.yaml` at all (frontmatter-only actions) skips the entire check — exactly the "passes validate, breaks at serve" scenario this milestone is meant to close.

Compare with `unresolvedSourceDiags` a few lines up (`validate.go:576-599`), which correctly unions `page.Config.Sources` (frontmatter) with `fileConfig.Sources` before checking — the source check got this right, but the action-param check wasn't given the same treatment. Worth mirroring: build the "declared sql actions" set from `page.Config.Actions ∪ fileConfig.Actions` (dropping the `fileConfig == nil` short-circuit) so frontmatter-only actions are covered too. `TestUnsuppliedActionParams`/`_OperatorExcluded` currently only exercise the `tinkerdown.yaml`-declared path, so this gap isn't caught by the new tests either.

Minor / non-blocking

• `suppliedParamNames` (`validate.go:688`) scans `ServerBlocks`, `InteractiveBlocks`, and `StaticHTML`, but not `WasmBlocks`. Probably fine given actions are server-executed and wasm blocks are unlikely to host action-invoking forms, but worth a one-line confirmation/comment if that's intentional.
• `hasConfigFile`'s filename list (`tinkerdown.yaml`/`lmt.yaml`/`livemdtools.yaml`) duplicates the list `config.LoadFromDir` presumably already knows — you flagged this yourself in the Phase 3 Learn as a DRY risk; a shared exported list would remove the drift risk entirely rather than just documenting it.
• Solid test coverage and Learn documentation otherwise — the fidelity guards (`component_funcs_test.go` pinning `split` in both the parse and tree-gen funcMaps) are exactly the right shape to prevent the split-brain regression you called out.

No security or performance concerns beyond the above — the added checks are O(document size) and run once per file during `validate`, not on the hot serve path.