Add backend validation foundation

[alistair3149]

Implements the foundation tier of ADR 21: Add Backend Validation. Adds a SubjectValidator service, extends the PropertyType plugin contract with a validate() method, and exposes two new REST endpoints that return constraint violations without performing a write.

Follows-up to #819 (re-uses the post-PUT-refactor patterns for Application/ use cases and EntryPoints/REST/ adapters).

Summary

• Two new endpoints: POST /neowiki/v0/subject/validate (create-shape body) and POST /neowiki/v0/subject/{subjectId}/validate (update-shape body). Both return 200 {violations: [...]} on well-formed input — violations are not HTTP errors.
• Plugin-contract change: PropertyType interface now requires validate(NeoValue, PropertyDefinition): Violation[]. Implemented on all six built-in types and on RedHerb's ColorType (canonical extension example).
• docs/ValidationCodes.md is the shared-codes contract between PHP and TS, including known gaps.

Scope

In: PHP-side validator + endpoints + plugin contract change. Foundation tier only.

Out (deferred): Edit endpoints unchanged (no validator on POST/PUT /subject); no enforcement config; no pre-existing-vs-new violation differentiation; TS top-level validator still returns boolean (not violations); no UI surface for the new endpoints.

Wire-level changes

POST /neowiki/v0/subject/validate

Body matches POST /subject create:

{ "schema": "Company", "label": "ACME", "statements": { ... } }

200 {violations: [...]} on well-formed input; 400 for missing/malformed body fields; 404 for non-existent schema.

POST /neowiki/v0/subject/{subjectId}/validate

Body matches PUT /subject/{subjectId}:

{ "label": "New", "statements": { ... }, "comment": "ignored" }

200 {violations: [...]} on well-formed input; 400 for invalid subject-id format; 404 for non-existent Subject; 200 with a schema-not-found violation when the Subject's stored Schema has gone missing (asymmetry with the create endpoint is intentional and explained in the handler).

Response shape

{
  "violations": [
    { "propertyName": "Websites", "code": "invalid-url", "args": [], "valuePartIndex": 1 },
    { "propertyName": null, "code": "label-required", "args": [] }
  ]
}

propertyName is the string form (or null for Subject-level violations). args is always present. valuePartIndex is omitted when not applicable. The stable code set is documented in docs/ValidationCodes.md.

Code structure

• src/Domain/Validation/Violation.php — immutable VO with withPropertyName(). SubjectValidator uses the builder to attach the property name (which PropertyType plugins don't know themselves).
• src/Application/Validation/SubjectValidator.php — pure orchestration. Algorithm mirrors the TS SubjectValidator: label check → iterate statements → skip unknown-to-schema properties (schema-drift accommodation) → delegate to PropertyType::validate().
• src/Domain/PropertyType/PropertyType.php — interface gains validate(NeoValue, PropertyDefinition): Violation[]. Built-in implementations port the rules from resources/ext.neowiki/src/domain/propertyTypes/*.ts.
• src/Domain/Subject/SubjectLabel.php — gains createForValidation(string) static that bypasses the empty-rejection constructor via reflection. The closure-->call($instance) alternative was rejected by PHPCS; reflection is the equivalent that passes the standard. Used only by the validate path; the regular constructor still rejects empty labels for write paths.
• src/Domain/Schema/Property/DateTimeProperty.php — gains public static parseStrictDateTime(string): ?DateTimeImmutable so DateTimeType::validate can reuse the existing strict-ISO-8601 + calendar-overflow logic.
• src/Application/SelectStatementResolver.php — gains resolveOrLeave(), a non-throwing variant used only by the validate handlers. Unresolvable select values pass through as-is; SelectType::validate then surfaces them as invalid-option violations rather than the handler erroring out. The throwing resolve() is unchanged for write paths.
• src/EntryPoints/REST/ValidateSubjectApi.php + ValidateSubjectUpdateApi.php — thin adapters. needsWriteAccess() returns false. No CSRF (read auth).
• extension.json — two new RestRoutes entries; ModuleSpecHandler picks them up into the OpenAPI spec automatically.
• tests/RedHerb/src/ColorType.php — real hex-color validation replacing the stub, as the canonical plugin-contract example.

Pre-1.0 stability — docs/RestApi.md already disclaims that /neowiki/v0/* is not stable. No back-compat shims.

Test plan

• All new unit tests pass: ViolationTest, SubjectValidatorTest, the six *TypeValidateTest classes, DateTimePropertyTest, SubjectLabelTest, ColorTypeValidateTest, SelectStatementResolverTest.
• make phpunit filter=ValidateSubjectApiTest — 9/9.
• make phpunit filter=ValidateSubjectUpdateApiTest — 9/10 (1 skipped: testSubjectWithMissingSchemaReturnsSchemaNotFoundViolation — fixture cannot create a findable Subject with a never-existing Schema; the defensive code path is documented).
• make phpunit filter=EntryPoints — 249/249 (1 skip).
• make phpunit filter=ModuleSpecHandlerNeoWikiTest — both new routes appear in the OpenAPI spec (assertion count rose from 376 to 407).
• make cs clean (phpcs + phpstan).
• Live API smoke — both endpoints exercised against demo data; one bug was caught and fixed mid-review (c734dd96).

Manual API Check

Demo data needs to be present first: make import-demo-data. Replace localhost:8484 with your wiki URL.

Create-shape endpoint

# Happy path
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/validate" \
  -H 'Content-Type: application/json' \
  -d '{"schema":"Company","label":"ACME","statements":{"Status":{"propertyType":"select","value":["Active"]}}}'
# Expect: 200 {"violations":[]}

# Empty label
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/validate" \
  -H 'Content-Type: application/json' \
  -d '{"schema":"Company","label":"","statements":{"Status":{"propertyType":"select","value":["Active"]}}}'
# Expect: 200 with a single label-required violation

# Invalid URLs at indices 1 and 2
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/validate" \
  -H 'Content-Type: application/json' \
  -d '{"schema":"Company","label":"ACME","statements":{"Status":{"propertyType":"select","value":["Active"]},"Websites":{"propertyType":"url","value":["https://example.com","not a url","ftp://nope"]}}}'
# Expect: 200 with two invalid-url violations at valuePartIndex 1 and 2

# Invalid select option (regression for the 500 bug fixed in c734dd96)
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/validate" \
  -H 'Content-Type: application/json' \
  -d '{"schema":"Company","label":"ACME","statements":{"Status":{"propertyType":"select","value":["bogus-id"]}}}'
# Expect: 200 with invalid-option violation

# Non-existent schema
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/validate" \
  -H 'Content-Type: application/json' \
  -d '{"schema":"NoSuchSchema","label":"X","statements":{}}'
# Expect: 404

Update-shape endpoint

Find a subject ID first (e.g. via curl http://localhost:8484/rest.php/neowiki/v0/page/{pageId}/subjects), then:

SID='sFromYourWiki00'

# Happy path
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/$SID/validate" \
  -H 'Content-Type: application/json' \
  -d '{"label":"New label","statements":{}}'
# Expect: 200 with violations matching the schema/statements

# Empty label
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/$SID/validate" \
  -H 'Content-Type: application/json' \
  -d '{"label":"","statements":{}}'
# Expect: 200 with label-required violation

# Non-existent subject (valid-format ID)
curl -sS -w '\nHTTP %{http_code}\n' -X POST "http://localhost:8484/rest.php/neowiki/v0/subject/s1aaaaaaaaaaaaa/validate" \
  -H 'Content-Type: application/json' \
  -d '{"label":"X","statements":{}}'
# Expect: 404

# No write should occur: re-read the subject after the calls above and confirm
# the label is still its original value.
curl -sS "http://localhost:8484/rest.php/neowiki/v0/subject/$SID"

Plugin-contract breaking change

The PropertyType interface gains a required validate() method. Extension authors maintaining custom Property Types must implement it. The RedHerb ColorType is updated in this PR as the canonical example.

Known limitations

Documented in docs/ValidationCodes.md. Intentional gaps in the foundation tier:

• Missing-required. Schema properties with no Statement at all are not flagged with required — mirrors the TS behavior. To be fixed when the TS top-level validator is upgraded.
• Empty-Statement-required. StatementListBuilder drops empty-valued Statements before validation; same fix as above.
• TextType min-length / max-length. PHP TextProperty doesn't yet expose those fields; TS does.
• RelationType invalid-subject-id. PHP SubjectId validates at construction, so RelationValue cannot hold an invalid target; PHP doesn't emit this code.

Result of extensive collaborative work with @alistair3149 — brainstorming (where we considered #591 vs. backend validation vs. conditional writes and settled on the latter being a precursor to all three), design, spec, plan, execution, review feedback, and live smoke testing that caught one real defect.
Context: NeoWiki codebase, ADR 21, the TS PropertyType implementations and tests, and PR #819 conventions. Working design + plan at docs/planning/2026-05-14-backend-validation-foundation-{design,plan}.md (uncommitted per project policy).
_{Written by Claude Code, `Opus 4.7`}