toga-ai 1.0.423 → 1.0.425

package/knowledge/2.0/apps/toga-blox/workflows/dynamic-publish-pipeline.md

@@ -6,8 +6,8 @@ project: TOGa Blox
 client: shared
 type: workflow
 status: active
-updated: 2026-07-21
-owners: [jcardinal]
+updated: 2026-07-23
+owners: [jcardinal, apeterson]
 files:
   - toga-blox/.github/workflows/publish.yml
   - toga-blox/src/utils/getFontAwesomeIcon.tsx
@@ -35,6 +35,26 @@ resolve in a consuming app's build, or touching `publish.yml`.
 - **Every** branch (including `_production`) publishes a **prerelease** version
   `X.Y.Z-<mode>.<run>` under dist-tag `<mode>`. There is no longer a production special case.
   Verified live: `production:1.0.315-production.96`, `sandbox-client:1.0.315-sandbox-client.97`.
+  Observed 2026-07-23: `sandbox-client:1.0.317-sandbox-client.101`, `sandbox-dev:1.0.316-sandbox-dev.102`.
+
+### Version derivation (CI owns the suffix; dev owns only the base)
+
+- CI reads `version` from `package.json`, **strips any `-<suffix>`**, does **`patch + 1`**, then
+  appends `-<mode>.<GITHUB_RUN_NUMBER>`. So base `1.0.317` on `_sandbox-client` run 104 publishes
+  `1.0.318-sandbox-client.104` under dist-tag `sandbox-client`.
+- **The developer controls only the BASE version** committed in `package.json` on the feature
+  branch. **Never hand-write the `-<mode>.N` prerelease suffix** — CI generates it. There is no
+  manual `npm publish`; CI is the only publisher.
+
+### Deploy procedure (e.g. `_sandbox-client`)
+
+1. Ensure a clean tree; optionally bump the base version in `package.json` on the feature branch.
+2. Merge the feature branch into `_sandbox-client`, then push (this triggers the CI publish).
+3. Monitor with `gh run watch`; verify with `npm dist-tag ls @agilant/toga-blox`.
+4. Consuming apps (e.g. `toga25-supply` on `_sandbox-client`) install from the `sandbox-client`
+   dist-tag or a pinned `1.0.x-sandbox-client.N` version and must **re-install** to pick up a new
+   build. The `deploy-sandbox-client` project skill (`.claude/skills/` in this repo) drives this
+   procedure end-to-end.
 
 ### What was removed (and why it's safe)
 
@@ -66,6 +86,12 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
 - **Publish before build.** `npm install @agilant/toga-blox@<mode>` fails `ETARGET No matching
   version` in the app build until this repo has published that channel. GitHub Actions runs the
   workflow version *on the pushed branch*, so the branch must carry the current `publish.yml`.
+- **`publish.yml` has diverged across branches (2026-07-23).** The dynamic `_*` wildcard trigger
+  lives on `_sandbox-client`, but older/feature branches (e.g. `feature-new-table`) still carry the
+  *old* `publish.yml` that triggers only on `_production/_gamma/_beta`. Because Actions runs the
+  copy on the pushed branch, a new `_<mode>` channel will **not** publish unless the branch you push
+  carries the wildcard-trigger version. When standing up a new channel, merge from a branch that has
+  the dynamic `publish.yml` (or update it first).
 - **FontAwesome v7 `style`-prop TS2322** (fixed 2026-07-21 in `getFontAwesomeIcon.tsx`, and a
   reusable pattern for any consumer). FA v7 types the `FontAwesomeIcon` `style` prop as
   `CSSProperties & CSSVariables`, where `CSSVariables` requires a `--fa-*` custom-property index
@@ -78,6 +104,11 @@ environment needs its own maintained `_<mode>` branch in `toga-blox-npm`.
   the pattern the consuming apps should follow (see the commerce workflow's secret-hygiene note).
 
 ## Change history
+- 2026-07-23 — Documented CI version derivation (strip suffix → patch+1 → append `-<mode>.<run>`;
+  dev owns only the base version, never the suffix) and the `_sandbox-client` deploy procedure now
+  driven by the `deploy-sandbox-client` project skill. Recorded that `publish.yml` has diverged
+  across branches: the dynamic `_*` trigger is on `_sandbox-client` while older/feature branches
+  still trigger only on `_production/_gamma/_beta`. (apeterson)
 - 2026-07-21 — Made `publish.yml` fully dynamic: trigger `_*`, branch→dist-tag by stripping the
   leading underscore (mode == channel 1:1), every branch (incl. `_production`) publishes a
   `X.Y.Z-<mode>.<run>` prerelease; removed the `_production`→`latest` special case (workflow no

package/knowledge/clients/rate/INDEX.md

@@ -8,5 +8,5 @@
 | [Rate SAML SSO](features/saml-sso.md) | 2.0 | Rate uses Azure AD as its IdP (`login.rate.com`). | _underscore/Model/Rate/ClientAuthentication.php, saml/Controller/Index.php, toga2-view/src/hooks/useAuthenticationFlow.ts |
 | [Service Card Entitlement Display](features/service-card-entitlements.md) | 2.0 | Rate's home and services pages display one service card per purchased entitlement. | src/components/ServiceCard/ServiceCard.tsx, src/components/ServiceCard/index.ts, src/hooks/useBundleServices.ts, src/hooks/useActiveServices.ts, src/pages/Home/api/homeApi.ts, src/pages/Home/view/HomePage.tsx, src/pages/Home/viewModels/useHomePageViewModel.ts, src/pages/Services/view/ServicesPage.tsx, src/pages/Services/viewModels/useServicePageViewModel.ts, src/api/serviceAddressApi.ts, src/api/apiErrors.ts |
 | [Rate Service-Purchase Confirmation Emails (Tech / Warranty)](features/service-purchase-emails.md) | 2.0 | When a Rate customer purchases a service, a confirmation email is sent. | _underscore/Model/Rate/Entitlement.php, worker2/Worker/Notification/EmailTemplate.php, dbchanges2/Client_Rate/2026-06-30a - Rate purchase email templates.sql |
-| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | > **⚠ DEPLOYING beta→production, NOT YET PROD-VERIFIED (as of 2026-07-23).** TRUE-79533 is > beta-verified (PM Paulina tested the WH purchase flow on beta) and | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
+| [Rate Whole Home Warranty Per-Address Purchase Guard](features/whole-home-warranty-purchase-guard.md) | 2.0 | > **⚠ DEPLOYING beta→production, NOT YET PROD-VERIFIED (as of 2026-07-23).** TRUE-79533 is > beta-verified (PM Paulina tested the WH purchase flow on beta) and | _underscore/Model/Rate/Entitlement.php, _underscore/Model/Client/Entitlement.php, _underscore/Model/Client/Address.php, dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql, dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql, dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql, test/@Mark/Rate/verify_wholehome_per_address_guard.php |
 | [Rate](profile.md) | 2.0 | Rate is a mortgage/lending client. |  |

package/knowledge/clients/rate/features/whole-home-warranty-purchase-guard.md

@@ -14,7 +14,7 @@ files:
   - _underscore/Model/Client/Address.php
   - dbchanges2/Client/2026-07-22a - EntitlementServiceAddressId.sql
   - dbchanges2/Core/2026-07-22a - EntitlementServiceAddressIdField.sql
-  - dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
+  - dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql
   - test/@Mark/Rate/verify_wholehome_per_address_guard.php
 related:
   - clients/rate/profile.md
@@ -32,11 +32,12 @@ related:
 > **shared-interceptor merge hazard** gotcha and the **dangling-pin** / **unguarded prod
 > interceptor** gotchas before merging to `_production`.
 >
-> **🚨 LAUNCH BLOCKER (added 2026-07-23, tcox) — the standard `serviceAddressId` field has NO
-> READ ACL grant.** The custom→standard redesign shipped the column + `Core.RecordFields` row
-> but **not** the `AclFieldPermissions` read grant, so `GET /v2/entitlements?fields=serviceAddressId`
-> returns **403 `EZ-2`** for roles 1/2/4. Prod does **not** launch clean without the new
-> `Client/2026-07-23a` field-permission migration below — see
+> **🚨 LAUNCH BLOCKER — RESOLVED (migration built 2026-07-23, mhammontree; found 2026-07-23,
+> tcox) — the standard `serviceAddressId` field had NO READ ACL grant.** The custom→standard
+> redesign shipped the column + `Core.RecordFields` row but **not** the `AclFieldPermissions`
+> read grant, so `GET /v2/entitlements?fields=serviceAddressId` returned **403 `EZ-2`**. The fix
+> now ships as **`dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`**
+> (committed `b74f42a` on TRUE-79533) — see
 > **[Launch blocker: standard field needs a READ ACL grant](#launch-blocker-true-79533--the-standard-field-needs-a-read-acl-grant)**.
 
 ## Summary
@@ -144,7 +145,7 @@ during backend review (Jeff). This is the single biggest change since the beta b
 
 **The custom→standard redesign shipped the column and the `Core.RecordFields` row but NOT the
 `AclFieldPermissions` READ grant.** Probe-verified on **beta 2026-07-23**:
-`GET /v2/entitlements?fields=serviceAddressId` returns **403 `EZ-2`** for roles 1, 2, and 4
+`GET /v2/entitlements?fields=serviceAddressId` returns **403 `EZ-2`** (no read ACL row)
 (Entitlements has `Core.Records.aclDatabase = 'CLIENT'`, so the grant lives in each client DB).
 Without the grant, **production launches with the exact `EZ-2` failure beta hit** — the field is
 registered but unreadable, so the service cards cannot fetch the pin.
@@ -157,16 +158,20 @@ field is authorized through **`AclFieldPermissions`**, keyed by the **`Core.Reco
 because the `CustomRecordFields` row for `c_serviceAddressId` was deleted in the standard-field
 redesign. The read grant now has to be an **`AclFieldPermissions`** row instead.
 
-**Needed migration (proposed, on the TRUE-79533 branch):**
-`dbchanges2/Client/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`, following the
-existing `Client/2026-07-02c - TrackingNumberNeedsReturnLabelFieldPermission.sql` precedent:
-- Resolve field ids via `Core.RecordFields` / `Core.Records` subselects (route `'entitlements'`,
-  fields `'serviceAddressId'` **and** its sibling `'number'`) — never hardcode ids.
-- **Mirror the sibling `number` field's per-role grants**, but force **`isWritable = 0`**:
-  `serviceAddressId` is written **server-side** by the guard's `postPost`, never by the API caller,
-  so it must be read-only.
-- Guard each INSERT with `NOT EXISTS` (verified against the Client blank DDL:
-  `AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`).
+**The migration that ships (built + committed `b74f42a` on TRUE-79533):**
+`dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`:
+- Resolves field ids via cross-schema `Core.RecordFields` / `Core.Records` subselects (route
+  `'entitlements'`, field `'serviceAddressId'`) — never hardcodes ids.
+- **Grants READ only (`isWritable = 0`)** — `serviceAddressId` is written **server-side** by
+  `_Model_Rate_Entitlement::postPost` via raw SQL, never by the API caller.
+- **Mirrors the reader ROLE(s) of the sibling standard FK `saleItemId` — which is `role 1` in
+  `Client_Rate`** (the same role the earlier `c_serviceAddressId` custom grant used). Although
+  the cross-role probe showed roles 1/2/4 all lacked a grant, **role 1 is the only actual reader**
+  of this field (Rate's toga2-view service cards), so the grant is role-1 only.
+- Guards each INSERT with `NOT EXISTS` — safe no-op until the field is registered
+  (`AclFieldPermissions` is `UNIQUE (recordFieldId, roleId)`).
+- **Scoped to `Client_Rate`, not a `Client/` fan-out** — Rate is the only client whose UI reads
+  the field today. A `Client/` fan-out grant is the follow-up if another client's UI needs it.
 
 ## Beta data migration — old-column pins are orphaned by the redesign (beta only, NO prod impact)
 
@@ -289,6 +294,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
   the deleted `2026-07-07a` interceptor registration was redundant — and why keeping it would have
   been a latent hazard: a fresh environment running both would **double-register**, firing
   `prePost` twice. **Recommend adding a `NOT EXISTS` guard to the `2026-07-15` file.**
+- **`AclFieldPermissions` has NO `isReadable` column — a ROW grants READ; `isWritable`
+  *additionally* grants WRITE** (reusable platform fact, verified against the api2 enforcement
+  code, not just schema). In `api2/Component/Api/V2/V2.php`, `getAclFieldPermissions()` (~line
+  5731) sets the field key regardless of `isWritable`, and the read-authorization checks test key
+  **presence** (`isset`/`array_key_exists`). Consequences: to make a field API-**readable** you
+  insert an `AclFieldPermissions` row (`isWritable = 0` for read-only); to make it **writable** set
+  `isWritable = 1`. And promoting a custom (`c_`) field to a **standard** field means its read grant
+  must be **re-created** as a standard `AclFieldPermissions` row (keyed by the `Core.RecordFields`
+  id) — the old `AclCustomFieldPermissions` grant (keyed by `CustomRecordFields` id) does **not**
+  carry over. This is exactly why the `c_serviceAddressId` grant did not cover the standard field
+  and the launch-blocker migration above was needed.
 - **`Core.RecordFields` has no `foreignRecordId` column** — FK resolution for `serviceAddressId`
   is entirely **model-side** (the `_Model_Client_Entitlement` FK declaration). The RecordField row
   only carries type/identifier/childPolicy/precision, mirroring sibling FKs `saleItemId`/`vendorId`.
@@ -297,6 +313,17 @@ live carrier waterfall is opt-in via `RUN_LIVE=1` (defaults off). Verified **18/
 
 ## Change history
 
+- 2026-07-23 — **READ-ACL grant BUILT — launch blocker resolved** (TRUE-79533, committed `b74f42a`).
+  Added `dbchanges2/Client_Rate/2026-07-23a - EntitlementServiceAddressIdFieldPermission.sql`: a
+  READ-only (`isWritable = 0`) `AclFieldPermissions` grant for the standard `serviceAddressId`,
+  resolving field ids cross-schema (route `entitlements`), `NOT EXISTS`-guarded. Final scope
+  corrected vs. the earlier proposal: **`Client_Rate` (not a `Client/` fan-out), role 1 only** —
+  mirroring the sibling standard FK `saleItemId`'s reader role (role 1 is the sole actual reader,
+  the toga2-view service cards). Recorded the reusable platform fact that **`AclFieldPermissions`
+  has no `isReadable` column — row presence grants READ, `isWritable` additionally grants WRITE**
+  (verified in `api2/Component/Api/V2/V2.php` `getAclFieldPermissions()` ~line 5731), which is why
+  a custom→standard promotion must re-create the read grant as an `AclFieldPermissions` row.
+  (mhammontree)
 - 2026-07-23 — **LAUNCH BLOCKER found: the standard `serviceAddressId` field has NO read ACL grant**
   (tcox). Probe-verified on beta: `GET /v2/entitlements?fields=serviceAddressId` → 403 `EZ-2` for
   roles 1/2/4 (`aclDatabase=CLIENT`). Standard fields are authorized via **`AclFieldPermissions`**

package/package.json

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