toga-ai 1.0.437 → 1.0.439

package/knowledge/1.0/apps/tools/INDEX.md

@@ -3,6 +3,7 @@
 | Doc | Summary | Files |
 |-----|---------|-------|
 | [Tools (1.0 Internal-Tools App) Architecture](architecture.md) | **Tools** is a standalone 1.0 (`App_`) application that houses many small internal tools behind simple interfaces, gated by Client_True staff persona. | tools/index.php, tools/_/app/framework.php, tools/_/app/frameworkindex.php, tools/assets/img/favicon/favicon.ico, tools/assets/img/favicon/favicon-32x32.png, tools/assets/img/favicon/favicon-16x16.png, tools/assets/img/favicon/apple-touch-icon.png, tools/_/app/auth.php, tools/_/app/nav.php, tools/common/header.php, tools/common/footer.php, tools/mvc/get.php, tools/mvc/_TEMPLATE/get.php, tools/docs/ADDING_A_TOOL.md |
+| [CloudFront Client Setup](features/cloudfront-client-setup.md) | An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that onboards a client onto **CloudFront + Route 53 across multiple AWS account | tools/_/app/devops/cloudfront.php, tools/mvc/devops/cloudfront-clients/get.php, tools/mvc/devops/cloudfront-clients/post.php, tools/assets/js/cloudfront-clients.js, tools/assets/css/cloudfront-clients.css, tools/_/app/nav.php, tools/_/app/frameworkindex.php, tools/config.production.ini |
 | [Design Demo Admin](features/design-demo-admin.md) | A self-serve admin UI at **`/design`** in the SSO-protected **Tools** app that lets the design team publish self-contained "Claude Design" HTML exports as **ver | tools/_/app/design/github.php, tools/mvc/design/get.php, tools/mvc/design/post.php, tools/assets/css/design.css, tools/assets/js/design.js, tools/_/app/frameworkindex.php, tools/_/app/nav.php, tools/composer.json |
 | [Tools — Developers Folder (UUID & Password Generators)](features/developer-tools.md) | The first two tools shipped in the Tools app, both under the **Developers** folder and gated to personas **Development Team** / **TOGa Technology**. | tools/mvc/developers/uuid/get.php, tools/mvc/developers/password/get.php |
 | [Tools MVC — Routing, CSRF & App_Database Access Patterns](features/mvc-data-access-patterns.md) | The load-bearing 1.0 (`App_`) framework conventions a developer needs when adding a page to the Tools app — URL routing, CSRF, and DB access through `App_Databa | tools/_/app/nav.php, tools/mvc/get.php |

package/knowledge/1.0/apps/tools/architecture.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: architecture
 status: active
-updated: 2026-06-26
+updated: 2026-07-24
 owners: [jcardinal]
 files:
   - tools/index.php
@@ -44,8 +44,10 @@ dashboard stylesheet's `header{position:fixed;width:100vw}` rule and cause horiz
 (the top header bar was removed for exactly this reason). A nav action's `route` maps **1:1** to
 `mvc/<route>/get.php`. Auth fails **closed** and never auto-creates users; the dev bypass is
 double-gated (`[internal] dev_mode` AND `App_Registry::inDevMode()`). `config.*.ini`
-(incl. `config.prod.ini`) is committed with plaintext production secrets — a known, team-accepted
-risk (see Known issues); never add more secrets and treat these as compromised if leaked.
+(incl. `config.prod.ini`) is committed with plaintext production secrets that were **publicly
+web-readable** until the front-controller deny blocks added 2026-07-24 (see Known issues);
+rotation of every exposed secret is still owed. Never add more secrets, and keep config files
+denied at the front controller / out of the web root.
 
 ## Boot & structure
 
@@ -86,10 +88,15 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
 
 ## Known issues / security
 
-- **Plaintext secrets committed to git.** `config.*.ini` (incl. `config.prod.ini`) contains
-  plaintext production secrets (RDS master password, SMTP, Payeezy, NetSuite). The team has
-  **accepted this for now** (developer decision, 2026-06-25). Future remediation: git-ignore the
-  config files and rotate all exposed credentials. (Location only — no values recorded here.)
+- **Plaintext secrets were publicly web-readable (fixed 2026-07-24; rotation still owed).**
+  `config.*.ini` (incl. `config.prod.ini`) holds plaintext production secrets (RDS master
+  password, SMTP, Payeezy, NetSuite). The front controller routed through `index.php` on a
+  `RewriteCond !-f` rule **only**, which is not access control — a direct
+  `GET /config.production.ini` served the file **verbatim**. Fixed 2026-07-24 by adding
+  `<FilesMatch>` `Require all denied` blocks (sensitive extensions incl. `.ini`, and any
+  `config.*`) — see the [1.0 back-end security standard](../../standards/backend-php.md).
+  **Action still owed:** rotate every secret in `config.production.ini` — the file was
+  reachable, so treat all of it as compromised. (Location only — no values recorded here.)
 - **SSO initiation + replay defense are open items** — see `features/saml-sso-auth.md`.
 - **Framework-level Sentry error reporting is an open gap.** Prod printed "Sentry is not
   installed" because `sentry/sentry` was missing from `composer.json` (added `^4.10`; sibling
@@ -99,6 +106,11 @@ Create `mvc/<folder>/<tool>/get.php` (copy `mvc/_TEMPLATE/get.php`), add one ent
   composer package must `require_once` the autoloader itself.
 
 ## Change history
+- 2026-07-24 — Fixed the config-file web-root exposure: `config.*.ini` was publicly readable via
+  the `!-f`-only front controller (`GET /config.production.ini` served it verbatim); added
+  `<FilesMatch>` deny blocks referencing the new 1.0 back-end security standard. Softened the
+  Critical-rules note from "team-accepted risk" to fixed-but-rotation-owed. Every secret in
+  `config.production.ini` still owes rotation (jcardinal)
 - 2026-07-24 — Added the SSO-gated **Design Demo Admin** tool at `/design` (`App_Design_Github`
   + `mvc/design/*` + namespaced assets + a `design` nav group), which publishes versioned demos
   into the `forward` repo over the GitHub API (see `features/design-demo-admin.md`). Noted the

package/knowledge/1.0/apps/tools/features/cloudfront-client-setup.md

@@ -0,0 +1,181 @@
+---
+title: CloudFront Client Setup
+framework: "1.0"
+repo: tools
+project: Tools
+client: shared
+type: feature
+status: active
+updated: 2026-07-24
+owners: [jcardinal]
+files:
+  - tools/_/app/devops/cloudfront.php
+  - tools/mvc/devops/cloudfront-clients/get.php
+  - tools/mvc/devops/cloudfront-clients/post.php
+  - tools/assets/js/cloudfront-clients.js
+  - tools/assets/css/cloudfront-clients.css
+  - tools/_/app/nav.php
+  - tools/_/app/frameworkindex.php
+  - tools/config.production.ini
+related:
+  - ../architecture.md
+  - ../features/persona-gated-navigation.md
+  - ../features/saml-sso-auth.md
+  - ../features/design-demo-admin.md
+  - ../../standards/backend-php.md
+---
+
+## Summary
+
+An SSO-gated admin tool at **`/devops/cloudfront-clients`** in the Tools 1.0 app that
+onboards a client onto **CloudFront + Route 53 across multiple AWS accounts** in one run.
+For each client slug × selected distribution it adds `{slug}.{baseDomain}` as a CloudFront
+**Alternate Domain Name** and creates the matching Route 53 **A + AAAA alias** records
+pointing at the distribution. It automates a repetitive, multi-account, error-prone manual
+onboarding step. Gated to the **`Development Team`** persona; has a **Dry-run** preview
+mode, a per-run slug cap, and an audit log line per non-dry-run attempt.
+
+## Key files / entry points
+
+- `_/app/devops/cloudfront.php` — class **`App_Devops_Cloudfront`** (all-static): the
+  single source of truth for account/distribution topology, AWS SDK client construction,
+  and all CloudFront + Route 53 domain logic.
+- `mvc/devops/cloudfront-clients/get.php` — route `/devops/cloudfront-clients` (page shell).
+- `mvc/devops/cloudfront-clients/post.php` — AJAX action endpoint (`action=process`).
+- `assets/js/cloudfront-clients.js`, `assets/css/cloudfront-clients.css` — self-guarded on
+  the `.cloudfront-clients-tool` root element, registered globally in
+  `_/app/frameworkindex.php`.
+- `_/app/nav.php` — new **`devops`** nav group, persona `['Development Team']`.
+- `config.production.ini` — documented, **commented placeholder** `[cloudfront_<accountId>]`
+  credential sections (location only — **no secret values** are stored in the knowledge base
+  or authored into tracked config here).
+
+Follows the same tool pattern as [Design Demo Admin](../features/design-demo-admin.md):
+`get.php` + `post.php` + a static `App_` class + per-tool namespaced js/css + one nav entry.
+The AWS SDK **v3** is vendored at `tools/vendor/autoload.php`; client construction mirrors
+`App_Talos_S3::client()` (explicit autoload-require guard, `class_exists` check, `try/catch`,
+`['ok' => ...]` array returns).
+
+## How it works
+
+### Topology is a single class constant
+
+`App_Devops_Cloudfront::CLOUDFRONTS` is the **only** source of truth for what can be
+onboarded, shaped as:
+
+```
+[ '<awsAccountId>' => [ '<distributionId>' => '<baseDomain>' ] ]
+```
+
+Adding or removing a distribution is done **solely** by editing this constant — no other code
+change is required.
+
+### Per slug × distribution
+
+1. Build the FQDN `{slug}.{baseDomain}`.
+2. **CloudFront alias:** `GetDistribution` → append the FQDN to `Aliases.Items` and bump
+   `Aliases.Quantity` → `UpdateDistribution` with `IfMatch = ETag`.
+3. **Route 53 records:** create **A** and **AAAA** alias records targeting the distribution's
+   DNS name. `AliasTarget.HostedZoneId` is the fixed AWS CloudFront constant
+   **`Z2FDTNDATAQYW2`**; `EvaluateTargetHealth = false`.
+
+### Route 53 zone lookup — by name, not list-all
+
+Zone resolution uses **`ListHostedZonesByName`** with the most-specific candidate walking down
+to the registrable apex (e.g. `compass.dev.sandbox.togasupply.com` → the `togasupply.com`
+zone). This jumps straight to the zone regardless of how many zones the account holds. The
+earlier `ListHostedZones` (list-all + longest-suffix match) approach **silently found
+nothing** and was replaced.
+
+### Record creation is INSERT-ONLY (never UPSERT)
+
+Existing A/AAAA records are read first (`existingAliasTypes` via `ListResourceRecordSets`); the
+tool creates **only the missing types** with the `CREATE` action. An existing record (e.g. a
+live production DNS entry) is **always left untouched**. UPSERT is deliberately never used —
+it would silently repoint a live production record.
+
+### Throttling + consistency gating
+
+- **Adaptive retries:** the SDK client is built with
+  `'retries' => ['mode' => 'adaptive', 'max_attempts' => 10]` because CloudFront
+  `UpdateDistribution` is aggressively rate-limited and a run fires many calls (was hitting
+  `Throttling: Rate exceeded`).
+- **Route 53 is gated on the CloudFront alias step succeeding for that item.** If the alias
+  fails (throttled, or `CNAMEAlreadyExists`), the Route 53 step is **skipped** so DNS is never
+  created pointing at a distribution that is not serving that hostname. Skips are **per item**;
+  the overall run continues past failures.
+
+### Safety rails
+
+- **Dry-run (preview only)** mode performs no writes.
+- **`MAX_SLUGS_PER_RUN = 100`** caps a single run.
+- Every **non-dry-run** attempt writes an **audit log** line including the acting user's email
+  (`App_Auth::currentUser()`).
+
+## Cross-account credential model
+
+Every account — **including** the production account `654654170868` that owns all Route 53
+zones — resolves to its **own** `[cloudfront_<accountId>]` config section through the single
+seam method **`credentialsForAccount()`**. Do **not** reuse the existing `[aws]` key for the
+prod account: `[aws]` is a **cross-account** key that only reaches the `654654170868` SQS queue
+from another account — it is **not an identity in `654654170868`**.
+
+On the actual EB server the **`ElasticBeanstalk-EC2-Instance-Profile`** role *is* in
+`654654170868`, so the prod account can use the instance role (no config key needed) once that
+role is granted: `route53:ListHostedZonesByName`, `route53:ChangeResourceRecordSets`,
+`route53:ListResourceRecordSets`, `cloudfront:GetDistribution`, `cloudfront:UpdateDistribution`.
+
+## Access control
+
+Behind Tools SSO; the nav action and page are gated to the **`Development Team`** persona (see
+[persona-gated-navigation](../features/persona-gated-navigation.md) and
+[saml-sso-auth](../features/saml-sso-auth.md)).
+
+## Client variations
+
+None — this is a shared internal DevOps tool. It *operates on* client slugs, but no single
+client owns or overrides it.
+
+## Gotchas / known issues
+
+- **`NoSuchDistribution` / zone-not-found means the WRONG ACCOUNT, not a permission problem.**
+  Permission failures return `AccessDenied`. A `NoSuchDistribution` or a missing
+  `togasupply.com` zone (when both demonstrably exist) means the call **authenticated into the
+  wrong account** — here, using the cross-account `[aws]` key against `654654170868`. Fix the
+  credential resolution, not the IAM policy. This is the key diagnostic for this tool.
+- **A CloudFront CNAME can live on only one distribution.** Re-adding an FQDN already attached
+  to a different distribution returns **`CNAMEAlreadyExists`**; the item is skipped (and Route 53
+  is skipped with it).
+- **Alternate domain names require a covering ACM certificate.** A wildcard cert covers only a
+  single label — `*.togasupply.com` does not cover `a.b.togasupply.com`. Ensure the distribution
+  has a cert covering the FQDN before adding it.
+- **Route 53 CloudFront alias records use the fixed `HostedZoneId` `Z2FDTNDATAQYW2`** (an AWS
+  global constant for all CloudFront alias targets — not the zone's own ID).
+- **1.0 promotes undefined-index warnings to a thrown `ErrorException`** that would abort the
+  whole "never fatally abort" run — all AWS-response array access is guarded. The SDK
+  client-builder `catch` is widened to **`\Throwable`** because the constructor can throw
+  `InvalidArgumentException`, not just `AwsException`.
+- **Credential exposure caveat.** This tool wields the prod IAM key, which amplified the impact
+  of the separate config-file web-root exposure fixed this session — see the 1.0 back-end
+  security standard and the Tools architecture Known issues. Every secret in
+  `config.production.ini` still owes rotation because the file was publicly readable.
+
+## Change history
+
+- 2026-07-24 — Built the CloudFront Client Setup tool (`App_Devops_Cloudfront` +
+  `/devops/cloudfront-clients` MVC route + namespaced assets + a `devops` nav group). Topology
+  is the `CLOUDFRONTS` class constant; per slug×distribution it adds a CloudFront alternate
+  domain name and Route 53 A+AAAA alias records (fixed `Z2FDTNDATAQYW2`). Cross-account
+  credentials resolve per-account via `credentialsForAccount()` (never reuse `[aws]` for the prod
+  account 654654170868 — instance role is used there). Route 53 lookup switched to
+  `ListHostedZonesByName`; record creation is INSERT-ONLY (never UPSERT); SDK adaptive retries
+  for CloudFront throttling; Route 53 gated on the alias step succeeding. Dry-run, per-run slug
+  cap (100), and per-attempt audit logging. (jcardinal)
+
+## Related docs
+
+- [Tools Architecture](../architecture.md)
+- [Design Demo Admin](../features/design-demo-admin.md)
+- [Back-End Coding Standards (1.0)](../../standards/backend-php.md)
+</content>
+</invoke>

package/knowledge/1.0/standards/backend-php.md

@@ -5,7 +5,7 @@ project: Library
 client: shared
 type: standard
 status: active
-updated: 2026-07-09
+updated: 2026-07-24
 owners: [jcardinal, rgirish, mhammontree]
 files: []
 related:
@@ -453,6 +453,45 @@ $order->location = App_Page::getVarIfSet('installation');
 
 * Always use HTTPS to encrypt data in transit.
 
+### Web-root file exposure — deny config/secret files at the front controller
+
+A front controller whose only guard is a rewrite that skips existing files —
+`RewriteCond %{REQUEST_FILENAME} !-f` — is **not access control**. `!-f` means "if the
+requested path is a real file on disk, let Apache serve it directly rather than routing it
+through `index.php`." Any file that physically sits under the web root (config, `.env`,
+logs, SQL dumps, backups) is therefore served **verbatim** on a direct request. A plain
+`GET /config.production.ini` returns the raw file, secrets and all. This is a real breach
+class, not a theoretical one — it was found live in a 1.0 app this session.
+
+Deny sensitive files explicitly at the front controller, in addition to (not instead of)
+keeping them out of the web root:
+
+```apache
+# Deny by sensitive extension
+<FilesMatch "\.(ini|env|log|sql|sh|bak|dist)$">
+    Require all denied
+</FilesMatch>
+
+# Deny anything named config.* (config.production.ini, config.prod.ini, …)
+<FilesMatch "^config\.">
+    Require all denied
+</FilesMatch>
+```
+
+Rules:
+
+* **Keep config/secret files outside the web root where at all possible** — a file the web
+  server cannot reach cannot be served. Deny blocks are defense in depth for files that
+  must live inside the tree.
+* **The `!-f` rewrite is a router optimization, never a security boundary.** Do not rely on
+  it to hide anything.
+* **Anything that was ever web-readable is compromised and must be rotated** — assume it was
+  fetched. Rotate every credential in an exposed file; a deny rule added after the fact does
+  not un-expose what was already reachable.
+* **Audit every 1.0 app's front controller** for this pattern. If a `.htaccess`/vhost routes
+  through `index.php` on `!-f` alone with no `FilesMatch` deny blocks, it is exposed — add
+  the deny blocks and treat any secret-bearing file under the root as leaked.
+
 ### Authentication and Authorization
 
 * Use the framework's `App_Auth` / `App_Acl` for authentication and role-based access control; do not roll your own session/permission checks.

package/knowledge/INDEX.md

@@ -13,7 +13,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **walmarttechservices** (Walmart Tech Services) — 1 doc(s) → [1.0/apps/walmarttechservices/INDEX.md](1.0/apps/walmarttechservices/INDEX.md)
 - **test** (Test) — 13 doc(s) → [1.0/apps/test/INDEX.md](1.0/apps/test/INDEX.md)
 - **toga** (TOGa) — 2 doc(s) → [1.0/apps/toga/INDEX.md](1.0/apps/toga/INDEX.md)
-- **tools** (Tools) — 9 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
+- **tools** (Tools) — 10 doc(s) → [1.0/apps/tools/INDEX.md](1.0/apps/tools/INDEX.md)
 
 ## 2.0 framework
 

package/knowledge/sessions/2026-07-27-true-79533-pin-depth-mhammontree.md

@@ -0,0 +1,73 @@
+---
+type: session
+slug: true-79533-pin-depth
+title: TRUE-79533 WH service-address pin blocked by depth=-1 starving postPost
+author: mhammontree
+repos: [_underscore, dbchanges2, toga2-view]
+framework: "2.0"
+client: rate
+status: active
+created: 2026-07-27
+updated: 2026-07-27
+---
+
+# Session: true-79533-pin-depth
+**Date:** 2026-07-27
+**Project/Repo:** _underscore / dbchanges2 / toga2-view (2.0, client Rate)
+**Task:** Get the validated Whole Home Warranty service address to pin (`Entitlements.serviceAddressId`) and render on beta. Backend is done and correct; the live blocker is that the beta purchase POST sends `depth=-1`, which starves the `postPost` interceptor of the just-created address id.
+
+---
+
+## What WORKED
+<!-- Include specific file paths and evidence -->
+- **Backend pin implemented** in `_underscore/Model/Rate/Entitlement.php` `postPost` → `persistWarrantyServiceAddress`: reads the created address id from the in-memory hydrated payload (`$payload->contact->primaryContactAddress->address->id`), then `UPDATE Addresses SET isValidated=1` + `UPDATE Entitlements SET serviceAddressId=… WHERE uuid=…`. Committed `dff1fb5e`. **Proven working**: a no-`depth` (deep-payload) purchase — ET100057, made from the local FE against the beta backend — pinned `serviceAddressId=56` with `Addresses.id 56` (STE 400) `isValidated=1`.
+- **`serviceAddressId` is a STANDARD field** on base `_underscore/Model/Client/Entitlement.php:20` (`FIELD_FOREIGNKEY` → `_Model_Client_Address`), inherited by the Rate model. Verified in the model file. So V2 persists/reads it; the postPost UPDATE and the FE read both rely on this.
+- **Display EZ-2 fixed**: `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` grants READ on `Addresses.id` for roles 1/2/3 (isWritable 0). Committed `ea1e0fb`. Applied on beta manually and verified (`AclFieldPermissions` field 41 → roles 1,2,3). This fixes the FE `GET /v2/addresses?fields=id,…` 403.
+- **Hard-blocks now return HTTP 400** via `_Exception_Validation` (the 3 prePost throws: missing address, unverifiable address, duplicate WH). Committed `41a5dc1a`. Verified against `api2/Controller/Index.php:204-222` — it catches `_Exception_Validation` → `DEFINED_MESSAGE_ERROR_BAD_REQUEST` (400 + clean message); all other exceptions → 500 + stack trace. This is what makes the FE blocked-purchase toaster work.
+- **Dedup** `hasActiveWarrantyAtAddress` forces the WRITE host + disables the query cache for a fresh read (committed). `COALESCE(serviceAddressId, ContactAddresses.addressId)` fallback so unpinned WHs are still deduped.
+- **Root cause proven via `Logs_Rate.Api`** (beta, MCP env `dev-sandbox`): the local-FE and beta-FE purchases hit the SAME beta backend instance (`i-0ce5624547cfecc93`, `api.beta.togahub.com`). The ONLY difference is the request query string — local: `transactionId=…` (no depth) → 64,650-byte deep response → **pinned**; beta: `depth=-1&transactionId=…` → 644-byte shallow response → **starved** (no address node in the payload postPost receives).
+- **`-1` source confirmed = front-end**: `toga2-view/src/pages/CheckOut/api/checkoutApi.ts:21` (`createService` passes `{ 'depth': -1 }`), serialized to `?depth=-1`. Confirmed in the logged query string.
+- **Beta interceptor config read** (`ApiPayloadInterceptors` join `Core.Records`): entitlements `postPost` = id **2**, active, **minDepth 5**; entitlements `prePost` = id 4, active, minDepth **null → default 3**; sales-orders `postPost` = id 3, null→3.
+
+## What did NOT work — DO NOT RETRY THESE
+<!-- Exact failure reasons — do not vague-ify -->
+- **Forcing the write host inside `persistWarrantyServiceAddress`** (commit `7b63955d`, later removed in `dff1fb5e`): NO EFFECT. V2 already globally disables the read host for the entire create block (`api2/.../V2.php:5024`), so the lookup was ALREADY on the write connection — forcing it again was a no-op. Confirmed by a genuinely post-deploy purchase (ET100051/52/53) still returning null.
+- **The original 3-table JOIN lookup** in postPost (`Entitlement → Contacts.primaryContactAddressId → ContactAddresses → addressId`): returned 0 rows *in-request* on beta even on the write connection. The identical query resolves correctly *post-commit*. Superseded by the payload approach.
+- **The payload-based pin (`$address->id`) still returned null on beta** — NOT because the code is wrong, but because with `depth=-1` the payload built for `postPost` is shallow (`meta.calcDepth: 1`) and does **not contain the `contact.primaryContactAddress.address` node at all**, so `$address->id` (and the `uuid` fallback) find nothing. Root cause is the depth, not the pin code.
+- **Merging `_underscore` to `_beta` did NOT deploy to beta.** The beta EB env **API-Sandbox-Dev** pulls `_underscore` from branch **`_sandbox-dev`** via `api2/.platform/hooks/prebuild/git.sh` + `api2/.ebextensions/git.sandbox-dev.json` (the prebuild hook `rm -Rf`s and re-clones that branch, overwriting the pipeline copy). Deploying anything not on `_sandbox-dev` runs old code.
+- **"Removing `depth=-1` from the beta curl" (Fri/earlier)**: the edited curl STILL had `depth=-1` in the query string (it wasn't actually removed) — confirmed via the logged `queryString`. So that test never proved anything.
+- **The single-host-vs-multi-host connection theory** (an earlier hypothesis): DISPROVEN. Both local-FE and beta-FE requests run on the SAME beta backend instance. The difference is purely the request's `depth` param, not connection topology.
+
+## Not tried yet (candidates for next session)
+- **THE decisive test (do this first):** on beta `Client_Rate`, `UPDATE ApiPayloadInterceptors SET minDepth = 10 WHERE id = 2;` then fire one fresh WH purchase (FE still sends `depth=-1`) and check `meta.calcDepth` + whether the new entitlement pins (`serviceAddressId` set, its address `isValidated=1`). Open question for Rohan: does the `minDepth` clamp engage for the `-1` sentinel at all? It's already 5 yet the build came through at `calcDepth 1` — so either it needs > 5 or `-1` bypasses the clamp.
+- **FE fix (alternative/parallel):** drop `{ 'depth': -1 }` at `toga2-view/src/pages/CheckOut/api/checkoutApi.ts:21` (or set ≥ minDepth), deploy `toga2-view`. This is the FE-side lever; it's owned by Tanner/Alex and the repo is currently on `_beta`.
+- Merge `_underscore` `TRUE-79533` → `_sandbox-dev` + deploy (ships the pin + 400 fix; backend is NOT yet on beta).
+- Merge `dbchanges2` `TRUE-79533` to its deploy branch for prod parity (beta already has the migrations, applied manually).
+- Run `/capture`.
+- File side tickets: (1) framework `minDepth`-clamp appears to be a no-op for `depth=-1` (starves ALL payload interceptors); (2) AIG contract block (`postPost`) has the SAME `depth` starvation — silently skipped for beta-FE purchases; (3) SECURITY: plaintext GitHub PAT committed in `api2/.ebextensions/git.*.json` — rotate + move to env config.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| `_underscore/Model/Rate/Entitlement.php` | Committed on `TRUE-79533` (HEAD `41a5dc1a`) | payload-based pin (`dff1fb5e`), dedup write-host, `_Exception_Validation` hard-blocks (`41a5dc1a`). NOT merged to `_sandbox-dev`. |
+| `_underscore/Model/Client/Entitlement.php` | Committed | `serviceAddressId` standard FK field (line 20). |
+| `dbchanges2/Client_Rate/2026-07-24a - AddressIdFieldPermission.sql` | Committed (`ea1e0fb`) | `Addresses.id` read ACL. Applied on beta manually. |
+| `dbchanges2` serviceAddressId col + `Core` field + ACL migrations | Committed on `TRUE-79533` | Applied on beta manually; branch needs merge for prod. |
+| `toga2-view/src/pages/CheckOut/api/checkoutApi.ts` | UNCHANGED (on `_beta`) | Line 21 still `'depth': -1` — the FE fix is pending. |
+| `test/@Mark/Rate/verify_wholehome_per_address_guard.php` | Updated (personal, not in a repo) | `c_serviceAddressId` → `serviceAddressId`; documents the multi-host/depth caveat. |
+
+## Decisions made
+- **Pin from the in-memory hydrated payload, not a DB read-back.** Rationale: in-request DB SELECTs can't reliably see the transaction's own uncommitted nested writes; V2's `getFullModelData` hydrates the payload before `postPost`. Rejected: the JOIN lookup (0 rows in-request) and an async post-commit worker (more surface; unnecessary once depth is fixed).
+- **`serviceAddressId` = STANDARD field** (per Jeff), not the old Rate-custom `c_serviceAddressId`.
+- **Hard-blocks throw `_Exception_Validation`** so they map to HTTP 400 with the message surfaced (the FE checkout expects 400). Rejected: plain `_Exception` → 500 + stack trace.
+- **Preferred depth fix = raise the `postPost` interceptor `minDepth`** (Rohan's lever) over the FE change: config-only, FE-independent, and also un-breaks the AIG block. Pending the beta test to confirm the clamp actually deepens the build for a `depth=-1` request.
+
+## Blockers
+- Pin cannot fire on beta until the `depth` collision is resolved: FE sends `depth=-1`, and the `postPost` interceptor `minDepth 5` floor is NOT producing a deep-enough payload (`calcDepth 1`). Open question to Rohan: does the `minDepth` clamp engage for `depth=-1`, and what target value? Needs the beta `UPDATE` test to settle.
+- Backend (`TRUE-79533`) is not yet on beta — it lives on `TRUE-79533`, but beta deploys `_underscore` from `_sandbox-dev`.
+
+## Exact next step
+> On beta (`dev-sandbox`, `Client_Rate`) run `UPDATE ApiPayloadInterceptors SET minDepth = 10 WHERE id = 2;`, then make one fresh WH purchase (FE unchanged, still sends `depth=-1`) and check the create response `meta.calcDepth` plus the new entitlement's `serviceAddressId` and its `Addresses.isValidated`. If it pins → the clamp works and 5 was too low; dial in the minimal value and ship it as a `dbchanges2 Client_Rate` migration (no FE change). If still null / `calcDepth` stays 1 → the clamp doesn't engage for `-1`; fix the FE (`checkoutApi.ts:21` drop `depth:-1`) instead. Confirm the intended target value with Rohan first.
+
+---
+_Saved by /session-save on 2026-07-27_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.437",
+  "version": "1.0.439",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",