Plan cache-key canonicalization contract tests

[leynos]

Summary

• Adds a living ExecPlan doc for roadmap item 5.1.4: Add contract tests for cache key canonicalization (sorted themes, rounded coordinates, SHA-256 key format).

Changes

• Introduces docs/execplans/backend-5-1-4-cache-key-canonicalization-contract-tests.md detailing goals, constraints, tolerances, risks, ownership, and a staged implementation plan.

Implementation outline (Stage A–E)

• Stage A: settle the production seam by adding a domain-owned cache-key derivation seam next to RouteCacheKey.
• Stage B: add focused rstest contract tests around canonicalization rules (themes, coordinates, key format).
• Stage C: extend Redis behavioural coverage with rstest-bdd, reusing existing Redis harness.
• Stage D: update architecture docs with final contract (route:v1:, coordinate precision, sorted themes) and mark 5.1.4 done after gates.
• Stage E: full validation with focused tests and final gate runs.

Test plan

• Focused unit tests using rstest to lock canonicalization rules.
• BDD scenarios with rstest-bdd against live Redis to prove observable behaviour.
• Ensure invalid inputs fail before Redis interaction and production key format is emitted as route:v1:<64 hex chars>.

Documentation

• Update docs/wildside-backend-architecture.md to reflect final canonical key design.
• Update docs/backend-roadmap.md to mark 5.1.4 done after gates pass.

Constraints and risks

• Scope limited to 5.1.4; domain-owned cache-key seam must be production-ready.
• Hexagonal boundary preserved: domain handles key semantics; Redis adapter handles transport; HTTP layer must remain Redis-agnostic.
• Risks include drift between architecture wording and actual implementation, Redis harness availability, and repository gate stability. Mitigations described in the ExecPlan.

Progress

• Approval gate: need reviewer approval.
• Stage A: settle domain seam implementation.
• Stage B: contract rstest tests added.
• Stage C: Redis BDD scenarios extended.
• Stage D: architecture docs updated and 5.1.4 closed.
• Stage E: final gates run with logs captured.

Surprises & discoveries

• Note any deviations observed during planning.

Decision log

• Summaries of key decisions (A1, A2, A3) will be recorded during execution.

Ownership

• Coordinator, Domain key-contract, Unit-test, Behavioural-test, and Documentation roles defined in the ExecPlan.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/013b1644-7ade-47fd-a954-ba6ec8fda3ff

Summary by Sourcery

Document an execution plan for adding cache-key canonicalization contract tests and related production seam, testing, and documentation work for roadmap item 5.1.4.

Documentation:

• Add a detailed ExecPlan document describing goals, constraints, risks, ownership, staged implementation, and validation steps for cache-key canonicalization contract tests for roadmap item 5.1.4.

Chores:

• Record current analysis, progress, surprises, and decision log entries for the planned cache-key canonicalization work without changing production code.

[sourcery-ai]

Reviewer's Guide

Adds a detailed ExecPlan document for roadmap item 5.1.4, defining how to introduce a domain-owned cache-key derivation seam, contract tests, Redis BDD coverage, documentation updates, and gating for cache-key canonicalization without yet changing production code.

File-Level Changes

Change	Details	Files
Introduce an ExecPlan document that specifies the staged implementation and testing strategy for cache-key canonicalization contract tests.	Describe current cache-key gaps and desired post-change behaviour for a domain-owned canonicalization seam and Redis adapter interaction. Define constraints, tolerances, and risks around scope, hexagonal boundaries, dependencies, and documentation alignment for cache-key work. Lay out staged implementation (Stages A–E) covering seam creation, rstest contract tests, rstest-bdd Redis scenarios, architecture and roadmap documentation updates, and final gate commands and evidence capture. Specify ownership roles, progress tracking, surprises/discoveries logging, and a decision log to guide and record execution of roadmap item 5.1.4.	docs/execplans/backend-5-1-4-cache-key-canonicalization-contract-tests.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5b4cda4b-c9e8-4580-8a3e-25bdbedee62c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-cache-key-canonicalization-tests-xb3l0v

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}