Record prepared validation ownership decision

This commit is contained in:
2026-11-05 19:07:52 +00:00
parent 5f56c65427
commit f660b6e0fc

View File

@@ -18,10 +18,9 @@ implementations were not audited. No production code or tests were changed.
These findings are not a claim that every candidate is a bug or release blocker. These findings are not a claim that every candidate is a bug or release blocker.
The evidence describes the audited baseline; subsequent review decisions are The evidence describes the audited baseline; subsequent review decisions are
recorded below. Findings 1–3 and 5–7 are accepted for remediation, and finding 8 recorded below. Findings 1–7 are accepted for remediation, and finding 8 is
is accepted as a decision to preserve current runtime behavior. Implementation accepted as a decision to preserve current runtime behavior. Implementation
has not begun under this document. Finding 4 remains open in its entirety, has not begun under this document. All findings have an accepted disposition.
including both the smoke syntax check and standalone validation retirement.
Existing explicit decisions remain authoritative except where a later accepted Existing explicit decisions remain authoritative except where a later accepted
decision deliberately changes them. A test, private interface, or historical decision deliberately changes them. A test, private interface, or historical
@@ -151,13 +150,13 @@ This is not a recommendation to remove every convenient internal constructor
or useful test double. For example, a no-repair runner fixture can remain cheap or useful test double. For example, a no-repair runner fixture can remain cheap
without maintaining a second rendering or repository-resolution workflow. without maintaining a second rendering or repository-resolution workflow.
### 4. Use The Native JSON Syntax Check In Smoke Diagnostics ### 4. Use Prepared Validation For Smoke Syntax And Schema Checks
**Status:** Open for discussion. Neither subproposal below is approved; retain **Status:** Accepted; implementation pending.
the existing workflow pending that discussion.
**Confidence:** High for the syntax-check simplification. **Owner:** smoke **Confidence:** High for consolidating the validation lifecycle. **Owner:** the
diagnostics report syntax validity separately from schema conformance. output-validation component owns syntax and schema checks; smoke diagnostics
orchestrate those checks and report their separate results.
**Evidence:** [Smoke inference](../../../internal/usecase/smoke_inference_case.go) **Evidence:** [Smoke inference](../../../internal/usecase/smoke_inference_case.go)
constructs a `StandardValidator` with an empty schema directory solely for constructs a `StandardValidator` with an empty schema directory solely for
@@ -166,46 +165,46 @@ a separate prepared schema plan. The relevant branch in
[standard validation](../../../internal/validate/standard_validator.go) performs [standard validation](../../../internal/validate/standard_validator.go) performs
`json.Valid` with context checks. It does not use the schema directory. `json.Valid` with context checks. It does not use the schema directory.
**Removal impact:** Direct use of `json.Valid` preserves the Boolean fact without Concrete host/`fs.FS` validators also expose direct `Validate(artifact, contract)`
the extra validator object, interface field, output contract, and validation methods and separate on-demand schema-loading callbacks. The runner now consumes
result projection. Preserve cancellation checks and the distinction between only `ValidationPreparer`. The identified production direct-validation call is
invalid JSON and schema-not-evaluated. JSON scalars remain valid syntax even the smoke JSON-only call; direct schema workflows are exercised by internal
when they fail the diagnostic schema. tests, not public injection.
**Proposed syntax-check approach:** Use the standard-library syntax check at **Accepted decision:** Use the existing prepared-validation lifecycle for both
that diagnostic operation and retain the prepared schema plan for schema conformance. smoke checks: prepare a JSON-only plan for syntax validity and retain the schema
plan for conformance. A JSON-only plan needs no schema loading or compilation.
Run the schema check only after valid syntax, preserving cancellation handling
and the distinction between invalid JSON and schema-not-evaluated. JSON scalars
remain valid syntax even when they fail the diagnostic schema.
There is a related larger deletion candidate: concrete host/`fs.FS` validators After migrating that smoke caller, retire the standalone direct-validation
still expose direct `Validate(artifact, contract)` methods and separate on-demand interface, methods, and redundant on-demand loading workflow. Move meaningful
schema-loading callbacks. The runner now consumes only `ValidationPreparer`. source/schema tests to prepared-plan validation. Keep shared instance validation
The identified production direct-validation call is the smoke JSON-only call; and source-specific root loading; do not reproduce the removed convenience
direct schema workflows are exercised by internal tests, not public injection. interface in tests.
**Proposed lifecycle approach:** Retire the standalone validation lifecycle **Rationale:** Direct `json.Valid` in smoke orchestration is a reasonable, slightly
if the smoke syntax simplification is selected, moving meaningful source/schema simpler option. However, the output-validation component remains necessary for
cases to prepared-plan validation. This is a separate choice from the direct execution and schema validation regardless of this choice. Using its existing
syntax check, even though it depends on removing that production caller. prepared plans keeps output-validation responsibility, cancellation handling,
and result semantics together. The modest difference in code complexity does
not outweigh that architectural benefit. This decision reuses the existing
abstraction; it does not call for a composite validator or a new diagnostic
framework.
The previous roadmap explicitly retained direct validation and its The previous roadmap explicitly retained direct validation and its
decode-before-schema-I/O behavior. Retiring it is therefore a deliberate change decode-before-schema-I/O behavior. This decision supersedes that selection for
to a previously selected **private** workflow, not an automatic dead-code fix. the removed **private** workflow. It does not change the public `ValidateRequest`
It need not change the public API or make schema errors lazy again. Keep shared API, which checks request variables and inputs, or make schema errors lazy again.
instance validation and source-specific root loading; do not duplicate them in
tests to preserve the removed convenience interface.
**Review recommendation, not yet accepted:** Select both simplifications. The **Alternatives considered:** Calling `json.Valid` directly in smoke diagnostics
syntax check removes an object/interface used only to report a Boolean fact; would remove a plan and result projection, but would place syntax validation
prepared validation already serves public execution. Retaining the standalone and its cancellation handling outside the component that owns other output
lifecycle solely for its tests would preserve an alternate private workflow. validation. Retaining the standalone direct-validation lifecycle would avoid
migrating its tests and preserve its decode-before-schema-I/O behavior, but would
**Viable alternatives:** Keep the existing smoke validator mediation to reuse retain a second private workflow without an identified production need after
its cancellation/result handling, at the cost of unnecessary setup and projection smoke migration. Neither alternative is selected.
for a syntax-only check. Alternatively, use `json.Valid` in smoke diagnostics but
retain direct validation as an internal convenience. That avoids migrating its
tests and preserves decode-before-schema-I/O behavior for private callers, but
retains a second lifecycle without an identified production need. The next
discussion should settle these choices explicitly, not infer approval from the
other accepted findings.
### 5. Separate Accepted-Value Detachment From Repeated Input Validation ### 5. Separate Accepted-Value Detachment From Repeated Input Validation
@@ -414,8 +413,9 @@ Then align private lookup/rendering collaborators with captured configuration.
Address copy validation and prepared snapshot ownership together so that deleting Address copy validation and prepared snapshot ownership together so that deleting
one copy does not relocate it into another helper. Implement schema-budget one copy does not relocate it into another helper. Implement schema-budget
removal under finding 7's explicit decision, preserving runtime behavior under removal under finding 7's explicit decision, preserving runtime behavior under
finding 8. Finding 4's syntax-check and direct-validation proposals remain open; finding 8. For finding 4, migrate smoke syntax validation to a prepared plan
do not include them as selected implementation work before discussion. before retiring the standalone direct-validation lifecycle and migrating its
meaningful tests.
Any implementation plan should include retiring the corresponding private-path Any implementation plan should include retiring the corresponding private-path
tests and internal prose while retaining meaningful public/ownership regressions. tests and internal prose while retaining meaningful public/ownership regressions.
@@ -425,10 +425,8 @@ framework, performance guarantees, or additional release gates. The retained
machinery table remains applicable, including artifact defensive copying, machinery table remains applicable, including artifact defensive copying,
prepared-handle lifecycle, and separate admission/active-permit responsibilities. prepared-handle lifecycle, and separate admission/active-permit responsibilities.
## Open Decisions ## Decision Status
Only [finding 4](#4-use-the-native-json-syntax-check-in-smoke-diagnostics) remains All eight findings have an accepted disposition. No open decisions remain in
open: whether to use `json.Valid` directly in smoke diagnostics and whether to this audit; implementation planning can proceed on the selected scope. None is
retire the standalone direct-validation lifecycle. Its proposed recommendation marked implemented by this documentation update.
and viable alternatives are recorded with the finding. All other findings have
an accepted disposition; none is marked implemented by this documentation update.