Design: Shared validation module with versioned client cache, checked on submission #17

New Issue

2026-09-02T00:05:46Z

Ty commented

2026-09-02 00:05:46 +00:00

Summary

Design a shared validation module living in the middle tier (FastAPI) that is the single source of truth for all business-logic validation rules. It serves two consumers: the client UI (field-exit and submit-time checks) and the inference prompt builder (Call 2 input assembly). This eliminates drift between what the UI allows and what the prompt silently rejects.

Design

Module interface

Input: field values (SKU, species, categories, attributes, title, description, short description, price, etc.) plus the current module version hash.
Output: field-level errors with stable error codes, each carrying a human-readable message and a suggested fix where one can be inferred.
Rules covered: character set (ASCII only), length caps (WooCommerce hard limits), required fields, format rules (SKU), and any store-side business constraints the app can enforce locally.

Client-side caching

The module ships with a version hash.
The client caches the module locally after first fetch.
The hash is checked only at submission time, not on every field exit or session start.
On submit: client sends its cached hash with the submission payload.
Server compares hash to current. Match → proceed with validation. Mismatch → server returns the fresh module; client re-validates against it and retries. User sees a brief "updating rules" state.
This closes the hole where a stale client silently bypasses a rule that tightened after it loaded.

Validation timing (pre-submission)

On field exit (blur): instant, local, using the cached module. Required fields block; optional fields with content must be valid (empty is always valid).
Length: hard input cap at the Woo limit — the user physically cannot type past it, rather than being blocked after the fact.
Character set: extended ASCII or invalid characters block on exit.
On submit: full validation pass plus the hash check.

Post-submission (separate issue)

Business-logic rejections returned by Woo (e.g. 409 duplicate SKU) are handled in a companion issue.
Server functional errors (500s, timeouts, auth failures) are handled in a third issue.

Acceptance criteria

A single validation module in the middle tier is the source of truth for all rules.
Both the client UI and the Call 2 prompt builder consume the same module.
Client caches the module with a version hash; hash is checked only at submission.
Hash mismatch returns the fresh module and triggers client re-validation before retry.
Empty optional fields are valid; any content must pass all rules.
Length is enforced by input cap, not post-hoc block.
Docs (CONTENT-WOO, ARCHITECTURE, IMPL-PLAN, PROMPTS) state the module, the hash-check-on-submit rule, and the two-consumer design.

Branch

Linked to docs/refactor-v2.

## Summary Design a shared validation module living in the middle tier (FastAPI) that is the single source of truth for all business-logic validation rules. It serves two consumers: the client UI (field-exit and submit-time checks) and the inference prompt builder (Call 2 input assembly). This eliminates drift between what the UI allows and what the prompt silently rejects. ## Design ### Module interface - **Input**: field values (SKU, species, categories, attributes, title, description, short description, price, etc.) plus the current module version hash. - **Output**: field-level errors with stable error codes, each carrying a human-readable message and a suggested fix where one can be inferred. - **Rules covered**: character set (ASCII only), length caps (WooCommerce hard limits), required fields, format rules (SKU), and any store-side business constraints the app can enforce locally. ### Client-side caching - The module ships with a **version hash**. - The client caches the module locally after first fetch. - The hash is checked **only at submission time**, not on every field exit or session start. - On submit: client sends its cached hash with the submission payload. - Server compares hash to current. **Match** → proceed with validation. **Mismatch** → server returns the fresh module; client re-validates against it and retries. User sees a brief "updating rules" state. - This closes the hole where a stale client silently bypasses a rule that tightened after it loaded. ### Validation timing (pre-submission) - **On field exit (blur)**: instant, local, using the cached module. Required fields block; optional fields with content must be valid (empty is always valid). - **Length**: hard input cap at the Woo limit — the user physically cannot type past it, rather than being blocked after the fact. - **Character set**: extended ASCII or invalid characters block on exit. - **On submit**: full validation pass plus the hash check. ### Post-submission (separate issue) - Business-logic rejections returned by Woo (e.g. 409 duplicate SKU) are handled in a companion issue. - Server functional errors (500s, timeouts, auth failures) are handled in a third issue. ## Acceptance criteria - [ ] A single validation module in the middle tier is the source of truth for all rules. - [ ] Both the client UI and the Call 2 prompt builder consume the same module. - [ ] Client caches the module with a version hash; hash is checked only at submission. - [ ] Hash mismatch returns the fresh module and triggers client re-validation before retry. - [ ] Empty optional fields are valid; any content must pass all rules. - [ ] Length is enforced by input cap, not post-hoc block. - [ ] Docs (CONTENT-WOO, ARCHITECTURE, IMPL-PLAN, PROMPTS) state the module, the hash-check-on-submit rule, and the two-consumer design. ## Branch Linked to `docs/refactor-v2`.

Ty added this to the POC milestone 2026-09-02 00:06:09 +00:00

grokbot_ty referenced this issue from a commit

2026-09-02 00:34:50 +00:00

docs: pair locks for #14 #2 #17 #18 (PPM product OK)

Ty referenced this issue

2026-09-03 02:36:57 +00:00

Test plan: POC acceptance test cases for all milestone issues #19

grokbot_ty added the post-launch label 2026-09-24 16:26:42 +00:00

grokbot_ty referenced this issue

2026-09-24 16:32:31 +00:00

POC [03/16]: Taxonomy sync, anchor versioning, and species picker — API-7, TAX-1, TAX-2, TAX-3, API-8 #41

Sign in to join this conversation.