Plan: stabilize slice transport contract and dev auth seam

[leynos]

Summary

Adds a formal ExecPlan for roadmap item 4.4.2 to stabilize the slice transport contract and introduce a development-auth seam, enabling a repeatable local preview path while preserving production long-term auth decisions.

Changes

• New ExecPlan doc added at
  docs/execplans/4-4-2-stabilize-the-slice-transport-contract-and-development-auth-seam.md
  detailing the purpose, constraints, tolerances, risks, progress, decision log, and the plan-of-work.

Rationale

• Provides a structured, approved plan before implementing the slice contract stabilization and development auth seam.
• Establishes clear boundaries, risk mitigations, and go/no-go checkpoints to keep scope tightly aligned with roadmap item 4.4.2.
• Enables a repeatable local preview path without locking in the production auth model prematurely.

Plan of work (Stage A–E)

• Stage A: Lock the slice contract and dependency intake
  • Define exact transport surface and delta with existing RFCs and docs; establish go/no-go criteria.
• Stage B: Harden the backend task transport contract
  • Align response/error shapes with shared primitives; preserve essential detail fields; keep pagination/SSE out of scope.
• Stage C: Implement frontend HTTP adapter and development auth seam
  • Provide http-task-gateway implementation scaffold and a documented development-only auth seam; keep fixture mode available.
• Stage D: Validate contract, auth seam, and unhappy paths
  • Run Rust and frontend tests (rstest, rstest-bdd, pg-embedded-setup-unpriv) and targeted UI tests; verify auth scenarios.
• Stage E: Update design/docs and close the roadmap item
  • Record final contract, update design/docs users-guide, and mark 4.4.2 as done after gates pass.

Validation / Gate checks

• Run gates during implementation:
  • make check-fmt
  • make lint
  • make test TEST_FLAGS='--profile long --all-targets --all-features'
  • make frontend-lint
  • make frontend-typecheck
  • make frontend-test
  • make frontend-e2e
  • make fmt
  • PATH=/root/.bun/bin:$PATH make markdownlint
  • make nixie
• Use set -o pipefail and tee outputs to capture failures without truncation.

Risks & Mitigations

• Risk: contract drift or misalignment with production paths; mitigation: keep 4.4.2 scoped to stabilization and development preview; reserve live path changes for 4.4.3.
• Risk: development-auth seam becoming permanent; mitigation: clearly document as temporary and local-only in this plan.
• Risk: OpenAPI/primitives integration scope grows; mitigation: lock to stage-specific changes and golden fixtures.

Progress (as of PR)

• Draft ExecPlan authored and added to repo; awaiting formal approval to proceed with Stage A.

Context

• This ExecPlan aligns with roadmap 4.4.x series and RFC 0002 guidance, ensuring the slice can depend on stable contracts while enabling a repeatable local preview path.

◳ Generated by DevBoxer ◰

---

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

📎 Task: https://www.devboxer.com/task/cd3fe888-fa85-4bbb-969d-cbf4bed9bfa1

Summary by Sourcery

Documentation:

• Document the staged execution plan, constraints, risks, and validation gates for stabilizing the task slice HTTP transport contract and development auth seam.

[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: 08e0a461-9482-4bf2-813e-12cc88804d18

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 stabilize-transport-contract-auth-seam-83wk8l

---

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

[sourcery-ai]

Reviewer's Guide

Adds a new ExecPlan document for roadmap item 4.4.2 that formalizes how to stabilize the slice task transport contract and introduce a development-only auth seam, including constraints, staged plan of work, risks, tolerances, validation gates, and documentation expectations.

Sequence diagram for development preview HTTP path with auth seam

sequenceDiagram
  actor Developer
  participant Browser
  participant RoutesUI
  participant TaskSliceDomain
  participant Ports
  participant HttpTaskGateway
  participant DevAuthSeam
  participant HttpApi
  participant TaskService

  Developer->>Browser: Start preview mode (fixture or HTTP)
  Browser->>RoutesUI: Navigate to task slice UI
  RoutesUI->>TaskSliceDomain: Render task detail/create view
  TaskSliceDomain->>Ports: Request task operation (create/detail/transition)

  Ports->>HttpTaskGateway: call_task_operation(taskRequest)
  HttpTaskGateway->>DevAuthSeam: attach_dev_auth(request)
  DevAuthSeam-->>HttpTaskGateway: authenticated_request

  HttpTaskGateway->>HttpApi: HTTP call (task route)
  HttpApi->>TaskService: Execute task lifecycle rule
  TaskService-->>HttpApi: TaskResult
  HttpApi-->>HttpTaskGateway: ResponseEnvelope (success or error)

  HttpTaskGateway-->>Ports: TaskResult or TaskGatewayError
  Ports-->>TaskSliceDomain: Normalized task state
  TaskSliceDomain-->>RoutesUI: Updated view model
  RoutesUI-->>Browser: Render updated UI

Loading

Flow diagram for ExecPlan stages A–E and go/no-go checkpoints

flowchart TD
  A["Stage A: Lock slice contract and dependency intake"]
  B["Stage B: Harden backend task transport contract"]
  C["Stage C: Implement frontend HTTP adapter and dev auth seam"]
  D["Stage D: Validate contract, auth seam, unhappy paths"]
  E["Stage E: Update design/docs and close roadmap item"]

  A_Gate{Go/no-go: actix-v2a surface and contract delta explicit?}
  B_Gate{Go/no-go: Stable JSON fixtures for task routes?}
  C_Gate{Go/no-go: Repeatable preview against local API?}
  D_Gate{Go/no-go: All validation gates passing?}

  Start["ExecPlan approved"]
  Stop["Stop and escalate (scope/tolerance breach)"]
  Done["Roadmap 4.4.2 complete"]

  Start --> A
  A --> A_Gate
  A_Gate -- Yes --> B
  A_Gate -- No --> Stop

  B --> B_Gate
  B_Gate -- Yes --> C
  B_Gate -- No --> Stop

  C --> C_Gate
  C_Gate -- Yes --> D
  C_Gate -- No --> Stop

  D --> D_Gate
  D_Gate -- Yes --> E
  D_Gate -- No --> Stop

  E --> Done

Loading

File-Level Changes

Change	Details	Files
Introduce a detailed ExecPlan document that defines scope, constraints, staged implementation, and validation for stabilizing the task slice transport contract and development auth seam.	Add a markdown ExecPlan describing purpose, success criteria, and observable outcomes for roadmap item 4.4.2. Specify architectural constraints for backend hexagonal boundaries, frontend slice boundaries, and allowed auth approaches. Define tolerances for scope, dependencies, auth feasibility, contract alignment, idempotency, and testing coverage as escalation triggers. Document risks around response-envelope mismatch, auth model divergence, frontend drift, idempotency sprawl, premature live adapter activation, and OpenAPI scope creep with mitigations. Capture current progress, surprises, and discoveries about repo state, including existing routes, fixtures, and missing shared primitives. Record an initial decision log clarifying that 4.4.2 is contract hardening plus dev preview only, leaving live route activation to 4.4.3. Lay out a multi-stage plan (Stages A–E) covering contract locking, backend hardening, frontend HTTP adapter and dev auth seam, validation strategy, and final documentation/roadmap closure. Enumerate required validation commands and gates to be run via make, with guidance on using pipefail and tee for logs.	docs/execplans/4-4-2-stabilize-the-slice-transport-contract-and-development-auth-seam.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.