[Eslam93]

Why

These are the verified backend defects from the post-interview audit:

• Refresh-token reuse detection revoked the user's tokens, then rolled the revocation back, so a stolen chain stayed valid.
• 422 responses echoed the submitted value, including a rejected password.
• Unhandled 500s had no request id and no security or CORS headers.
• Provider failures on the text path became generic 500s, while the image path put OpenAI's error text in its 502 body.
• The corrective retry dropped strict mode and told the model its JSON was invalid when the JSON was usually fine.
• Model calls held an idle transaction open.
• Prompts asked the model for stats the brief never gave.
• Compose exposed Postgres (password app) on every interface.
• The UI had no way to know the backend runs in mock mode.

What changed

Commit	Change
fix(auth)	The reuse revocation is committed before the 401, so the request's rollback can't undo it. The integration harness now runs the real get_db_session: the old bare-yield override is why CI never caught this. REQUIRE_DB=1 makes a missing Postgres fail CI instead of skipping the suite.
fix(api) 422	Validation errors keep only loc, msg and type, so Pydantic's input, ctx and url are gone. The envelope shape and the WEAK_PASSWORD remap are unchanged.
fix(api) 500	A pure-ASGI catch-all, innermost in the stack, renders INTERNAL_ERROR inside RequestID, SecurityHeaders and CORS. The 500 now carries request_id, X-Request-ID and the security headers. It reports to Sentry explicitly, because the exception no longer reaches Sentry's ASGI hook. The old Exception handler stays as a last resort.
fix(providers)	One ProviderError family with a typed kind, mapped by a single handler to a fixed status, code and message (table below). Upstream text goes to the log only, never into an exception message or a response. insufficient_quota is no longer retried. AI_RATE_LIMITED forwards Retry-After as a header and as details.retry_after_seconds.
fix(content) strict retry	The corrective retry keeps the same strict json_schema and names each failing field with Pydantic's message, never the value. This applies to content generation and both improver stages.
fix(db)	end_read_transaction() commits the read transaction before every text-path model call, so a 5–30 s call no longer holds a pooled connection idle in transaction.
test(prompts)	Golden files pin the rendered system and user prompts for the four content types and both improver stages. UPDATE_GOLDENS=1 regenerates them.
fix(prompts)	Removes the asks for invented stats (LinkedIn hook, ad copy, persuasive improver). The email sign-off ends in a [Your name] placeholder instead of "— The Magna team". A test asserts that no rendered prompt mentions "Magna". The four changed prompt modules move to v2.
fix(dev)	Compose binds Postgres and the backend to 127.0.0.1. The nginx frontend placeholder and the Redis that nothing read are gone, along with the USE_REDIS / REDIS_URL settings. The frontend runs with pnpm dev, as the README now says.
feat(api)	GET /api/v1/meta is public and returns {"provider_mode": "openai" | "mock" | "bedrock", "app_version": "..."}. It exposes nothing else.
fix(content) cut-off retry	A strict retry that comes back cut off or filtered degrades to stage 3 with attempt 1's output, as before, rather than failing. Its tokens and cost are still counted.
fix(prompts) / ci	blog_post moves to v2 for its new retry wording. The backend-ci comment now says the job fails without Postgres.

New error codes:

Code	Status	When
AI_PROVIDER_AUTH_FAILED	502	OpenAI rejected the server's key (401/403)
AI_RATE_LIMITED	429	Upstream rate limit after retries; carries Retry-After when OpenAI sent one
AI_UNAVAILABLE	503	5xx or a connection failure after retries, or out of quota
AI_TIMEOUT	504	Timed out after retries
AI_OUTPUT_TRUNCATED	502	A strict-schema reply hit the length limit
AI_CONTENT_REJECTED	422	OpenAI's safety system blocked the request
AI_PROVIDER_MISCONFIGURED	503	The server's AI configuration can't work, e.g. a missing API key or an unpriced model
PROVIDER_ERROR	502	Any other provider failure

Behaviour changes to know about

• Two tabs refreshing at once now sign the user out on every device. This was always the documented policy, but the rollback bug kept it from taking effect. The frontend's single-flight refresh only covers one tab (follow-up below).
• Provider failures return the codes above instead of a 500 (text path) or a 502 carrying upstream text (image path).
• Prompt versions move to *.v2, so rows written from now on record the new prompts.
• /health drops its never-probed redis key. Every in-repo caller checks only the status code.
• A stale .env with USE_REDIS / REDIS_URL still boots; a test covers this.
• docker compose up now starts only Postgres and the backend, reachable only from this machine.
• python -m app.scripts.seed now commits part-way through, because the services commit before model calls. The seed is idempotent, so a re-run picks up where it stopped.

Verification

• ruff check, ruff format --check, mypy app (strict) and alembic upgrade head pass.
• pytest with REQUIRE_DB=1: 597 passed (466 on the base branch). Coverage is 90.68%, up from 89.05%. Every commit passes all checks on its own.
• Each regression test was shown to fail on the pre-fix code. For example, with the new commit removed, the refresh-reuse test sees the rotated token still unrevoked.
• Provider error mapping is tested end to end through both real OpenAI providers with httpx.MockTransport scripted responses. A sentinel string checks that no upstream text reaches a response body or an exception message.
• Three independent review passes (security, correctness, tests/CI/docs) found 10 issues, all low severity. 8 are fixed in this PR; the other 2 are listed below.

Not verified: no live OpenAI call was made, because no API key was used. Error classification follows OpenAI's documented error codes and the SDK's exception types.

Follow-ups noticed but not fixed here

• The image path still holds SELECT … FOR UPDATE NOWAIT across the prompt call, the image call and the upload. Fixing it needs a schema change (README section 12, item 7: job-table dedupe for image regeneration).
• With FastAPI 0.136's default request scope, get_db_session commits after the response is sent. The auth routes don't commit explicitly first, so a failed commit there would follow a 200.
• The frontend could dedupe refreshes across tabs (Web Locks or BroadcastChannel) to avoid the sign-out-everywhere effect.
• infra/lib/compute-stack.ts still injects USE_REDIS=false, now dead config, and a few infra comments mention it. Changing it needs CDK snapshot updates.
• The mock LLM's canned email still signs off as "The MagnaCMS team", and the seed's demo brand voice is called "Magna in-house". Both belong with the rename.
• The *_parse_failed_* log events could include the failure note, which names fields but no values.

Stack

PR 2 of 3, stacked on #154 (model catalog and pricing). Merge that first; GitHub retargets this PR once it merges. The frontend PR is stacked on this one.

🤖 Generated with Claude Code