Freeze hot-path result DTO; add governance docs and testing working model - #3
Merged
Conversation
…odel Post re-review hardening (requirements v0.3), before implementation begins. Contract freeze (ADR 0009): - Freeze the apply()/query() result as a value-or-failure sum type carrying, per feature, the read-your-write level, exact|approximate, definition-version hash, apply status, and a distinguishable failure code (never a silent 0). - Make velocity-spi serialization-neutral; Jackson 3 required in velocity-core. - Scope HLL sketches same-implementation-only; drop cross-backend HLL migration. - Commit both Postgres and Redis as production-grade v1 backends. - New acceptance gates (idempotency-exactness, seed-implemented); AR-5 gains deadline-exceeded/overloaded; KMS key custody for the R11 hash salt. Governance (GR-2/GR-3): add README, GOVERNANCE, SECURITY, CONTRIBUTING, CHANGELOG. Working model / Definition of Done: - Raise the coverage gate to LINE >=80% / BRANCH >=70%; exclude trivial/generated code (records/DTOs, **/dto/**, **/model/**, generated DI) from the denominator. - Add the CONTRIBUTING Definition of Done and a CLAUDE.md working model. - Add a reusable .claude/agents/change-validator reviewer agent. CI: harden Dependabot auto-merge to patch/minor only; majors and github-actions updates now require human review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
wolpert
added a commit
that referenced
this pull request
Jul 19, 2026
… TCK Proves the frozen velocity-spi contract is implementable and provides the harness every backend (JDBI/Redis) must pass (ADR 0004, NFR-13/18, acceptance #3). - InMemoryVelocityBackend: thread-safe, EXACT, ATOMIC reference backend implementing VelocityBackend + Count/Sum/DistinctStore + Sliding/TumblingSupport + SeedSupport. Injectable Clock (backend is the clock authority); raw-event store computed per window at read; sliding = (now-D, now], tumbling = aligned bucket; apply returns one PerFeature per (intent x feature window) and its value already reflects the write (read-your-write); down/unsupported -> distinguishable Failure, never a silent 0. - Conformance TCK (tck/*Scenarios, in src/main so backends reuse it): Count/Sum/ Distinct/Sliding/Tumbling/Seed/Capability/Purge scenarios (27 methods) that advance the clock and assert real windowed values, aging-out / bucket-reset, seeded==recorded merge (acceptance #16), unsupported-window Failure, and declaration<->implementation agreement. - InMemoryVelocityBackendTck drives all 27 scenarios; 48 tests total; coverage 97.8% line / 87% branch (gate 80/70). - velocity-spi: comment-only javadoc clarification on apply* result cardinality (one PerFeature per intent x window); no signature/type change. Validated by the change-validator agent: VERDICT APPROVE ("this TCK would fail a broken backend"). Removed unused testkit deps (jackson/caffeine/slf4j) per the review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Pre-implementation hardening from a second four-role design review (fraud/rules adopter, gateway
security operator, engineering architect, business leader). This lands the fixes that must be in
place before the
velocity-spicontract is frozen and code is written, plus the project'sgovernance docs and a testing working model. Documentation, spec, and build-config only — no
product code yet (modules remain stubs).
Requirements bumped to v0.3.
Contract freeze — ADR 0009
The
apply()/query()result rides on every call andvelocity-spiis additive-only (NFR-17), soits shape must be frozen complete now or a later addition re-cuts a published DTO.
FeatureResult = Success{FeatureValue} | Failure{FailureCode}— carrying, per feature, the read-your-write level,exact|approximate, thedefinition-version hash, an apply status, and a distinguishable
UNAVAILABLE|DEADLINE_EXCEEDED|…(never a silent
0). Completes ADR 0007.velocity-spiis serialization-neutral — Jackson removed from itsapisurface; Jackson 3 isrequired in
velocity-core/the wire layer (ADR 0002 amended).0006/0008, GR-6 scoped to exact aggregates).
deadline-exceeded/overloaded; KMS key custody required for the R11 hash salt.Governance docs (GR-2 / GR-3)
New
README.md,GOVERNANCE.md,SECURITY.md,CONTRIBUTING.md,CHANGELOG.md. The README clearlymarks pre-release status (no functional code / benchmarks / published artifacts yet).
Testing working model / Definition of Done
(records/DTOs,
**/dto/**,**/model/**, generated DI) excluded from the denominator so the floorapplies to logic, not boilerplate.
CONTRIBUTING.mdgains a Definition of Done (tests required, trivial-code carve-out, a featureisn't done without an end-to-end/integration test).
CLAUDE.mdgains a working model: write code+tests → run the build (never "done" on a red/skippedgate) → invoke the reviewer sub-agent.
.claude/agents/change-validator.md(checks tests are meaningful andcode meets its requirement/ADR).
CI
Dependabot auto-merge hardened to patch/minor only; major bumps and all
github-actionsupdatesnow require human review.
Verification
./gradlew clean buildpasses (BUILD SUCCESSFUL). The raised coverage gate currently reportsSKIPPEDbecause no code/tests exist yet; it begins enforcing once modules gain real classes.🤖 Generated with Claude Code