DataTalksClub / DataTalksClub/website
Add bounded redacted reasons for ECS terminal-count capture failures
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Parent/related issues: #102, #160, #164
Normative references: _docs/runbooks/development-release.md, _docs/specs/08-aws-development-terraform.md, _docs/specs/10-verification-strategy.md
Problem
The deployment controller correctly fails closed when the captured ECS service or PRIMARY deployment is not terminal, but the current public-safe error is only web captured terminal counts differ. In the recent exact-SHA run 31857913389, automatic prior capture passed and the pre-mutation deploy checkpoint later failed with the same generic message. The evidence intentionally redacts provider payloads, so an authorized operator cannot tell which allowlisted predicate failed without a separate AWS read-only inventory.
Outcome
Add a deterministic, machine-readable, redacted reason code to the deployment error/evidence for each capture-contract failure. The diagnostic must identify the failed contract category and workload, without exposing provider payloads, exact resource identifiers, account/region details, task definitions, environment values, credentials, headers, cookies, or raw response data.
The existing safety contract remains unchanged: capture is still fail-closed, no retry/eventual-convergence override is added, no fallback/fabricated readiness is allowed, and no AWS operation is introduced.
Scope
- Define a versioned allowlist of safe capture reason codes covering the existing checks (service identity/lookup, unique PRIMARY, target mismatch, terminal/failed tasks, and each service/PRIMARY running/pending invariant).
- Preserve the existing human-readable error text where compatibility requires it, while attaching the reason code and workload through the existing redacted deployment-evidence path.
- Keep diagnostics deterministic when more than one predicate is false (document the precedence or ordered list); never include raw provider dictionaries or unbounded exception text.
- Add unit/contract tests for every reason-code branch, redaction, schema/version validation, deterministic ordering, and unchanged fail-closed behavior.
- Update the development-release runbook with the safe diagnostic vocabulary and operator interpretation. No production or AWS configuration changes.
Acceptance criteria
- Every existing
capture_servicefailure branch emits exactly one allowlisted reason code (or a documented ordered bounded list) and workload; unknown/internal exceptions fail closed without leaking details. - The serialized evidence/log projection contains only the approved code, schema version, workload, and existing safe release context; no ARN, account, region, task definition, environment, token, header, cookie, provider payload, exact secret, or raw exception text appears.
- The four terminal-count predicates are distinguishable without revealing raw counts; tests cover service running/desired, service pending, PRIMARY running/desired, and PRIMARY pending.
- Existing return status and mutation ordering are unchanged: mismatches remain fatal before release mutation, with no retry, fallback, or eventual-convergence success path.
- Focused deployment tests, redaction/evidence validation, lint/type/format checks, and the relevant CI contract tests pass under SQLite/ordinary CI.
- Runbook/spec updates are readable and include a bounded operator example; no HTML/template minification or unrelated route/content changes.
- Independent tester and PM acceptance bind the exact candidate; the issue is committed only after the normal process gates.
Non-goals
- No AWS readback, workflow dispatch, deployment rerun, Terraform/IAM/DNS change, or protected data access.
- No weakening of #102's exact terminal-pair/recovery proof or #160's readiness repair.
- No raw ECS counts or provider payloads in public logs/artifacts.
- No changes to application routes, course/content data, email, or frontend.
Follow _docs/PROCESS.md: PM grooming, isolated engineer, independent tester, PM acceptance, local --no-ff merge/push; no pull request.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing capture_service failure branches and the referenced development-release runbook and AWS Terraform and verification specs. Define the bounded reason vocabulary and evidence projection there, then use the focused deployment, redaction/evidence, lint/type/format, and CI contract checks named in the issue; done means every branch is covered without changing fail-closed behavior or mutation ordering.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, python
- Domain
- devops, infrastructure
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100