docs: design account spend control

[royosherove]

Problem / Motivation

LowKey can currently provision complicated AWS prototypes through a builder role with AdministratorAccess, but it has no account-local mechanism to estimate committed spend, deny additional paid operations, freeze supported resources, notify the owner, or expose controlled release/override actions.

Why it matters

A delayed AWS Budget alert cannot prevent an agent from creating persistent infrastructure or continuing paid runtime calls. A useful monthly cap therefore needs an explicit guarantee boundary, synchronous admission for unbounded paths, service-specific accounting, protected freeze controls, and visible uncertainty rather than an invoice-cap promise.

What changed (motivation → approach → change)

Adds an initial 1,123-line technical design for same-account spend control:

• separates observe-only builder, strict controlled_builder, broker, and external-root trust models;
• defines conservative accrued/committed/projected accounting and residual liability;
• uses multi-Region CloudTrail/EventBridge invalidation, SQS reconciliation, inventory repair, adapters, delayed billing backstops, and fail-closed readiness;
• defines NORMAL, WARNING, THROTTLED, RECONCILING, FROZEN, and UNSAFE semantics plus orthogonal override leases;
• specifies IAM self-protection, credential-class freeze behavior, owner authorization, recovery, notifications, and the CloudFront/Cognito control application;
• assesses aws-samples/sample-bedrock-spend-budget-guardrails as reusable Bedrock-runtime prior art while explicitly denying the uncovered bedrock-mantle:CreateInference path in strict mode; and
• records a read-only empirical CloudTrail analysis plus a 229-key exact-name baseline catalog grouped into P0/P1/P2 controls.

The requested 30-day empirical window was not fully recoverable: no CloudTrail Lake event data store exists and the integrated CloudWatch Logs group retains only 14 days. The design therefore labels its exact 2,228,017-record snapshot as retention-limited and does not infer the missing first 16 days.

Tests

• Independent senior AWS/IAM/FinOps subagent review; its conditional-reject findings for strict mode were incorporated.
• Read-only CloudTrail subagent analysis using deterministic AWS MCP scripts across 17 enabled Regions.
• git diff --check origin/main...HEAD.
• Markdown heading, fence, table, link, duplicate-catalog-key, and aggregate-arithmetic validation.
• 201 coverage-driven operation names validated against 37 locally bundled AWS service models.

Manual verification

• Verified current LowKey IAM, CloudFormation, Cognito, custom-resource, model-mode, and profile behavior against the design.
• Verified the referenced AWS Bedrock sample and its Mantle endpoint limitation.
• Confirmed only docs/design/spend-control.md is included in the commit.

Screenshots / video

Why no screenshot: documentation-only design change; no rendered product UI changes.

no linked issue: this PR introduces the requested design for maintainer review.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 662db2d781

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add an independent fail-closed mechanism for regional outages

For the controlled_builder option, a home-Region outage also takes down the controller that would enter UNSAFE and attach the deny, while already issued role credentials and their static permissions remain usable. Quotas limit maximum exposure but do not cause paid operations to be denied after this health window, so the stated fail-closed behavior cannot occur without an independently evaluated, expiring authorization lease or an external watchdog; otherwise this guarantee must be restricted to paths that exclusively use such a gateway.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Delay FROZEN until the principal deny is active

When an owner selects Freeze now, this workflow first persists and publishes FROZEN, then attempts to attach the deny and close the gateways. If either enforcement step is delayed or fails, the UI, email, and integration event can report FROZEN even though the agent can still initiate paid writes, contradicting the state table's promise that FROZEN means an explicit deny is in effect. Use an intermediate enforcement state and commit FROZEN only after the principal/gateway controls acknowledge, while surfacing failed enforcement as unsafe.

Useful? React with 👍 / 👎.