base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Record prepared validation ownership decision

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-05 19:07:52 +00:00
parent 5f56c65427
commit f660b6e0fc
1 changed files with 49 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
docs/roadmap/audit/A1-responsibility.md
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.
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
is accepted as a decision to preserve current runtime behavior. Implementation
has not begun under this document. Finding 4 remains open in its entirety,
including both the smoke syntax check and standalone validation retirement.
recorded below. Findings 1–7 are accepted for remediation, and finding 8 is
accepted as a decision to preserve current runtime behavior. Implementation
has not begun under this document. All findings have an accepted disposition.
Existing explicit decisions remain authoritative except where a later accepted
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
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
the existing workflow pending that discussion.
**Status:** Accepted; implementation pending.
**Confidence:** High for the syntax-check simplification. **Owner:** smoke
diagnostics report syntax validity separately from schema conformance.
**Confidence:** High for consolidating the validation lifecycle. **Owner:** the
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)
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
`json.Valid` with context checks. It does not use the schema directory.
**Removal impact:** Direct use of `json.Valid` preserves the Boolean fact without
the extra validator object, interface field, output contract, and validation
result projection. Preserve cancellation checks and the distinction between
invalid JSON and schema-not-evaluated. JSON scalars remain valid syntax even
when they fail the diagnostic schema.
Concrete host/`fs.FS` validators also expose direct `Validate(artifact, contract)`
methods and separate on-demand schema-loading callbacks. The runner now consumes
only `ValidationPreparer`. The identified production direct-validation call is
the smoke JSON-only call; direct schema workflows are exercised by internal
tests, not public injection.
**Proposed syntax-check approach:** Use the standard-library syntax check at
that diagnostic operation and retain the prepared schema plan for schema conformance.
**Accepted decision:** Use the existing prepared-validation lifecycle for both
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
still expose direct `Validate(artifact, contract)` methods and separate on-demand
schema-loading callbacks. The runner now consumes only `ValidationPreparer`.
The identified production direct-validation call is the smoke JSON-only call;
direct schema workflows are exercised by internal tests, not public injection.
After migrating that smoke caller, retire the standalone direct-validation
interface, methods, and redundant on-demand loading workflow. Move meaningful
source/schema tests to prepared-plan validation. Keep shared instance validation
and source-specific root loading; do not reproduce the removed convenience
interface in tests.
**Proposed lifecycle approach:** Retire the standalone validation lifecycle
if the smoke syntax simplification is selected, moving meaningful source/schema
cases to prepared-plan validation. This is a separate choice from the direct
syntax check, even though it depends on removing that production caller.
**Rationale:** Direct `json.Valid` in smoke orchestration is a reasonable, slightly
simpler option. However, the output-validation component remains necessary for
execution and schema validation regardless of this choice. Using its existing
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
decode-before-schema-I/O behavior. Retiring it is therefore a deliberate change
to a previously selected **private** workflow, not an automatic dead-code fix.
It need not change the public API or make schema errors lazy again. Keep shared
instance validation and source-specific root loading; do not duplicate them in
tests to preserve the removed convenience interface.
decode-before-schema-I/O behavior. This decision supersedes that selection for
the removed **private** workflow. It does not change the public `ValidateRequest`
API, which checks request variables and inputs, or make schema errors lazy again.
**Review recommendation, not yet accepted:** Select both simplifications. The
syntax check removes an object/interface used only to report a Boolean fact;
prepared validation already serves public execution. Retaining the standalone
lifecycle solely for its tests would preserve an alternate private workflow.
**Viable alternatives:** Keep the existing smoke validator mediation to reuse
its cancellation/result handling, at the cost of unnecessary setup and projection
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.
**Alternatives considered:** Calling `json.Valid` directly in smoke diagnostics
would remove a plan and result projection, but would place syntax validation
and its cancellation handling outside the component that owns other output
validation. Retaining the standalone direct-validation lifecycle would avoid
migrating its tests and preserve its decode-before-schema-I/O behavior, but would
retain a second private workflow without an identified production need after
smoke migration. Neither alternative is selected.
### 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
one copy does not relocate it into another helper. Implement schema-budget
removal under finding 7's explicit decision, preserving runtime behavior under
finding 8. Finding 4's syntax-check and direct-validation proposals remain open;
do not include them as selected implementation work before discussion.
finding 8. For finding 4, migrate smoke syntax validation to a prepared plan
before retiring the standalone direct-validation lifecycle and migrating its
meaningful tests.
Any implementation plan should include retiring the corresponding private-path
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,
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
open: whether to use `json.Valid` directly in smoke diagnostics and whether to
retire the standalone direct-validation lifecycle. Its proposed recommendation
and viable alternatives are recorded with the finding. All other findings have
an accepted disposition; none is marked implemented by this documentation update.
All eight findings have an accepted disposition. No open decisions remain in
this audit; implementation planning can proceed on the selected scope. None is
marked implemented by this documentation update.