toga-ai 1.0.382 → 1.0.384

package/knowledge/2.0/apps/ai-bdr/INDEX.md

@@ -6,6 +6,7 @@
 | [BDR Web Funnel — Full Implementation Plan](features/bdr-web-funnel-plan.md) | > **Execution status (2026-07-16):** PLAN **Phases 0–5 are BUILT and QA'd**, Phase 6 > was **mostly already built** (the `info` contract was implemented at comm | bdr/PLAN.md, bdr/mockup/app.jsx, bdr/mockup/screens.jsx, bdr/mockup/components.jsx |
 | [Call Orchestration — PHP Worker ↔ Vapi (the integration seam)](features/call-orchestration.md) | The **PHP worker** is the orchestrator; **Vapi** is the actor. | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-inbound-callback-assistant-request.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md, ai-bdr/scripts/update_structured_output.py |
 | [Vapi Integration — Assistants, Tools, Structured Output](features/vapi-integration.md) | Everything inside Vapi: the three assistants, the three shared tools, the shared structured-output schema, the Liquid-templated system prompt, and the Python sc | ai-bdr/vapi/templates/assistant.template.json, ai-bdr/vapi/templates/system-prompt.template.md, ai-bdr/prompts/archive/prompt-may-15.txt, ai-bdr/prompts/campaigns/healthcare-2026-03-18.md, ai-bdr/prompts/campaigns/healthcare-v2-2026-03-25.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py, ai-bdr/scripts/update_structured_output.py, ai-bdr/scripts/update_call_summary_context.py, ai-bdr/scripts/fix_booking_guardrails.py, ai-bdr/scripts/get_assistant.py, ai-bdr/docs/vapi-firstmessage-timing-fix.md, ai-bdr/docs/vapi-voicemail-iphone-screening.md |
-| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/lib/clientIp.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/app/api, bdr/test, bdr/public, bdr/mockup/styles.css |
+| [Web Funnel — Built Next.js App (structure, stack, how to run)](features/web-funnel-app.md) | The **built** state of the BDR web funnel — the Next.js UI / lead-capture front door of the existing AI-BDR product (see `../architecture.md`). | bdr/PLAN.md, bdr/.gitignore, bdr/eslint.config.mjs, bdr/amplify.yml, bdr/src/app, bdr/src/app/layout.tsx, bdr/src/app/page.tsx, bdr/src/app/studio.css, bdr/src/lib/resolveCampaignId.ts, bdr/src/lib/scheduleSlots.ts, bdr/src/lib/formatPhone.ts, bdr/src/lib/analytics.ts, bdr/src/lib/rateLimit.ts, bdr/src/lib/clientIp.ts, bdr/src/proxy.ts, bdr/.env.example, bdr/src/components/GoogleAnalytics.tsx, bdr/src/components/RichText.tsx, bdr/src/content, bdr/src/components, bdr/src/flow, bdr/src/server, bdr/src/server/toga.ts, bdr/src/app/api, bdr/test, bdr/test/togaPrimaryPhone.test.ts, bdr/public, bdr/mockup/styles.css |
 | [Web Funnel — Next.js UI + Config-Driven Campaign Content](features/web-funnel-content-model.md) | > **Status note (RESOLVED 2026-07-16):** the content **contract** below (schema, > provider seam, adapters) is BUILT and QA'd (PLAN Phases 0–5). | bdr/src/content/schema.ts, bdr/src/content/provider.ts, bdr/src/content/useCampaign.ts, bdr/src/content/default.ts, bdr/src/lib/resolveCampaignId.ts, bdr/src/server/leadSink.ts, bdr/src/server/callbackService.ts, bdr/src/app/api/call-now/route.ts, bdr/src/app/api/call-later/route.ts, bdr/src/app/api/contact/route.ts |
 | [New-Campaign Onboarding (6-phase runbook)](workflows/new-campaign-onboarding.md) | The end-to-end procedure for launching a new outbound BDR campaign (industry, offer, target persona, geography). | ai-bdr/docs/client-onboarding-sop.md, ai-bdr/docs/calcom-new-campaign-event-guide.md, ai-bdr/prompts/templates/campaign-template.md, ai-bdr/scripts/update_assistant.py, ai-bdr/scripts/update_system_prompt.py |
+| [Safe AI-BDR Call-Loop Testing (isolated test-campaign runbook)](workflows/safe-call-loop-testing.md) | How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-end **without dialing real prospects**. | dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql, worker2/Worker/Ai/Bdr/Vapi.php, worker2/Config/beta.ini |

package/knowledge/2.0/apps/ai-bdr/features/web-funnel-app.md

@@ -6,7 +6,7 @@ project: AI-BDR
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-20
 owners: [tcox]
 files:
   - bdr/PLAN.md
@@ -31,14 +31,19 @@ files:
   - bdr/src/components
   - bdr/src/flow
   - bdr/src/server
+  - bdr/src/server/toga.ts
   - bdr/src/app/api
   - bdr/test
+  - bdr/test/togaPrimaryPhone.test.ts
   - bdr/public
   - bdr/mockup/styles.css
 related:
   - web-funnel-content-model.md
   - bdr-web-funnel-plan.md
   - ../architecture.md
+  - ../workflows/safe-call-loop-testing.md
+  - ../../worker2/features/vapi-webhook-handler.md
+  - ../../api2/features/nested-relationship-writes.md
 ---
 
 ## What this is
@@ -88,7 +93,9 @@ to its ship state (trusted-IP position for X-Forwarded-For; O(1) LRU-capped limi
 - **ESLint flat config** carries a **no-em-dash rule** on shipped strings
   (`Literal` / `TemplateElement` / `JSXText` selectors) — enforces the mockup copy
   rule on in-repo strings (`eslint.config.mjs`).
-- **Vitest** test suite: **104 tests, all green** (13 added in the first 2026-07-16 session:
+- **Vitest** test suite: **114 tests, all green** (10 added 2026-07-20 for the primary-phone
+  self-heal — null-pointer re-link, changed-number re-link, create-as-last-resort, strict
+  `requestCall` vs. absorbing `upsertContactByEmail`; 13 added in the first 2026-07-16 session:
   phone format/prefill/mask, live-anchor consent links, `submitOk` race; the later 2026-07-16
   session added the rate-limiter + trusted-IP + LRU-eviction + `hsCampaignId` validation tests
   to reach 104). Every phase was verified with `tsc` + lint + build + a live SSR `curl` before
@@ -212,19 +219,33 @@ source of truth for "why isn't my contact being called." Full rules are document
   call windows and weekly cadence limits, but still requires an active campaign **with an
   assigned assistant**, `isActive=1`, `isOkayToCall=1`, a live **primary** phone, and
   `attemptCount < maxAttemptsPerContact`.
-- **BUG — a phone-less HubSpot contact can never receive a call (silent).** When the HubSpot
-  contact has no phone, BDR creates the Toga contact **without** a phone at page-prime; the
+- **BUG (funnel side FIXED — self-heal shipped; api2 platform fix still deferred).** When the
+  HubSpot contact has no phone, BDR creates the Toga contact **without** a phone at page-prime; the
   phone the visitor types arrives later via the Call Now `PUT`. api2 creates a
   `ContactPhoneNumber` row on that update but does **not** set
-  `Contacts.primaryContactPhoneNumberId`. The dialer's eligibility SQL `INNER JOIN`s on
-  `primaryContactPhoneNumberId`, so the contact stays invisible to the dialer. **Re-submitting
-  does not fix it** (verified in production: the phone row exists but the primary pointer
-  stays null). The funnel still shows success and returns `200` — a silent failure. The old
-  `info` site never hit this because CRM-sourced contacts already had a phone at CREATE time
-  (api2 links the primary on create, not on a later update). Fix candidates: api2-side (set
-  the primary when a phone row is created during an update) or a BDR workaround (a follow-up
-  `PUT` linking the existing phone-row uuid as primary). Affects **any** phone-less HubSpot
-  contact and blocks live call testing.
+  `Contacts.primaryContactPhoneNumberId` — the exact api2 root cause (the UPDATE path injects a
+  reverse back-reference into the nested child object, defeating the single-key-uuid forced-MATCH
+  fast-path) is now documented in
+  [api2 nested-relationship-writes.md](../../api2/features/nested-relationship-writes.md). The
+  dialer's eligibility SQL `INNER JOIN`s on `primaryContactPhoneNumberId`, so the contact stays
+  invisible to the dialer, the funnel still shows success and returns `200` — a silent failure. The
+  old `info` site never hit this because CRM-sourced contacts had a phone at CREATE time (api2 links
+  the primary on create, not on a later update).
+  - **Self-heal (SHIPPED, `src/server/toga.ts`, commit `4ac579e`):** after any contact write that
+    carried a phone, if the response echoes `primaryContactPhoneNumber` **null** OR a number whose
+    last-10 digits **don't match** what was sent (stale-pointer / changed-number case), the code
+    finds the orphaned `ContactPhoneNumber` row uuid (from the echoed contact's `contactPhoneNumbers`
+    → fresh `GET /contacts/{uuid}` → creates one via `POST /contact-phone-numbers` as a last resort)
+    and re-links it with an **identifier-only** `PUT {primaryContactPhoneNumber:{uuid}}` (a single-key
+    identifier object hits api2's forced-MATCH path). **`requestCall` is strict** (throws → the route
+    returns `500`, so the UI never reports success for an undial-able submit); **`upsertContactByEmail`
+    absorbs + warns** (lead priming must never break the funnel — call-now re-heals). Covered by 10
+    regression tests (written first, failed on old code; 114-test suite green; an independent review
+    found + fixed the changed-number case). Resolves the funnel-side bug **once `_dev-sandbox` deploys**
+    (deploy still pending — see the deploy note below).
+  - **api2 platform fix is still deferred** to its own PR/ticket (gate the reverse-back-reference
+    injection to true reverse/has-many relations). The self-heal covers the funnel meanwhile; the
+    same api2 bug likely affects `primaryContactEmailAddress` / `primaryContactAddress` on update.
 
 ## Local dev setup (BDR)
 
@@ -244,6 +265,30 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
 - **Restart the dev server after creating `.env.local`** — Next reads env files only at
   server startup. `.env.*` is gitignored in BDR.
 
+## Deploy status (AWS Amplify — NOT yet deployed)
+
+The BDR site is **not deployed anywhere yet** (as of 2026-07-20). Go-live is blocked on the
+Amplify setup, tracked by ClickUp **868kdf4tj "BDR - create amplify and sandbox route"** (urgent,
+Sprint 82) — still `to do`. (ClickUp shows Alex Peterson as assignee; the team says Jeff picked it
+up — ClickUp is stale, confirm the real owner before assuming.)
+
+- **Deploy branch is `_dev-sandbox`** (underscore-prefix convention), **not** `BDR-Development` /
+  `BDR-Phase-2`. The primary-phone self-heal (commit `4ac579e`, see the phone-less bug above) is
+  already merged into `_dev-sandbox`, so **Amplify's first build ships the fix**.
+- **Amplify must be configured for SSR hosting (NOT static export)** — the app is server-rendered
+  (server components, route handlers, and the `proxy.ts` edge proxy all require the SSR/compute
+  runtime). Point the app at branch `_dev-sandbox`.
+- **5 server-side env vars are required** (same set as local dev): `TOGA_API_BASE_URL`,
+  `TOGA_CLIENT_ID`, `TOGA_CLIENT_API_UUID`, `TOGA_CLIENT_API_SECRET`, `HUBSPOT_ACCESS_TOKEN`.
+  **Where the values live (never the values):** the `info` repo's `.env.local` (production
+  credential set). Add them in the Amplify console environment config — never commit them.
+- **Phase 8 WAF pairing.** `BDR/PLAN.md` Phase 8 specifies a **per-IP rate rule on the CloudFront
+  distribution / WAF** that pairs with the in-app token-bucket limiter (the app limiter is
+  defense-in-depth only; the edge WAF rule is the authoritative control — see the enumeration
+  gotcha). Configure it as part of the Amplify/CloudFront setup, along with the non-gating `cso`
+  follow-ups (lock the Amplify origin to CloudFront; verify `CloudFront-Viewer-Address` inject+strip
+  before trusting it).
+
 ## What is parked / not built
 
 - **Creator screen + `TweaksPanel` — deliberately NOT ported** (parked per plan
@@ -371,6 +416,19 @@ PRODUCTION credential set (`TOGA_API_BASE_URL = https://api.togahub.com/v2`).
   harness; pull it with `npx toga-ai`.
 
 ## Change history
+- 2026-07-20 — FIXED the phone-less-contact dialer bug on the funnel side: shipped a primary-phone
+  **self-heal** in `src/server/toga.ts` (commit `4ac579e`) — after any contact write carrying a
+  phone, if the echoed `primaryContactPhoneNumber` is null or its last-10 digits mismatch, find/create
+  the `ContactPhoneNumber` row uuid and re-link via an identifier-only `PUT {primaryContactPhoneNumber:
+  {uuid}}` (single-key forced-MATCH). `requestCall` is strict (throws → route 500, UI never falsely
+  reports success); `upsertContactByEmail` absorbs+warns (priming never breaks the funnel; call-now
+  re-heals). 10 regression tests (114 suite green; independent review found+fixed the changed-number
+  case). The **exact api2 root cause** was also located and documented (UPDATE-path reverse-back-ref
+  injection defeats the uuid forced-MATCH — see api2 `nested-relationship-writes.md`); the api2 platform
+  fix is deferred. Added the **Deploy status** section: BDR is not deployed yet (ClickUp 868kdf4tj still
+  to-do); deploy branch is `_dev-sandbox` (now carrying the self-heal); Amplify needs SSR (not static),
+  the 5 server env vars (values sourced from `info`'s `.env.local`), and the Phase 8 per-IP WAF rate
+  rule. (tcox)
 - 2026-07-16 — Rate-limit mitigation HARDENED to ship state after an independent `cso` security
   review returned **SHIP after two rounds** (supersedes the mid-state recorded in the entry
   below: test count is **104**, not 89, and the review is complete, not "still running"). Added

package/knowledge/2.0/apps/ai-bdr/workflows/safe-call-loop-testing.md

@@ -0,0 +1,112 @@
+---
+title: Safe AI-BDR Call-Loop Testing (isolated test-campaign runbook)
+framework: "2.0"
+repo: ai-bdr
+project: AI-BDR
+client: shared
+type: workflow
+status: active
+updated: 2026-07-20
+owners: [tcox]
+files:
+  - dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql
+  - worker2/Worker/Ai/Bdr/Vapi.php
+  - worker2/Config/beta.ini
+related:
+  - new-campaign-onboarding.md
+  - ../architecture.md
+  - ../../worker2/features/vapi-webhook-handler.md
+---
+
+## Summary
+
+How to prove the AI-BDR **dialer → Vapi → end-of-call webhook** loop end-to-end **without
+dialing real prospects**. The production dialer cron (`Core.CronJobs` "AI BDR",
+`ProcessAllActiveCampaigns`, schedule `* * * * *`) fires **every minute**, so any campaign that
+becomes eligible starts dialing live prospects **within 60 seconds** — a test must be built so
+that the *only* contact that can ever be dialed is a deliberate test contact. The safe technique
+is an **isolated one-contact test campaign with no call windows**. Eligibility mechanics that make
+this work are in [worker2 vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
+
+## Rule 1 — NEVER revive an ended campaign that has linked prospects
+
+An ended campaign (`dateEnd` in the past) is rejected every run by `validateCampaignReady`
+("Campaign has ended"). Flipping `dateEnd`/`isActive` to revive it makes **all** its
+contact-level-dialable contacts eligible at once, and the every-minute cron dials them within
+60s. (Observed live: campaign `26.05 - AI BDR - Ryan Nitti` was blocked **solely** by
+`dateEnd`; it had 132 linked contacts, ~86 contact-level dialable — reviving it would have
+dialed real prospects in one cron tick.) Likewise, do **not** blanket-flip `isOkayToCall=1` on a
+real list: it is two mass writes plus a restore burden, and it silently un-blocks any contact
+that was intentionally set `isOkayToCall=0`.
+
+## Rule 2 — Use an isolated one-contact test campaign with NO call windows
+
+The safe posture exploits the eligibility split (see vapi-webhook-handler.md): the normal
+(non-requested) dial path requires a `CampaignCallWindows` row for the current day/time, but the
+**requested** path (`dtNextContactRequested <= NOW()`) bypasses windows/cadence. So:
+
+1. **Deactivate any ended campaign** that shares the environment (also silences the every-minute
+   "Campaign has ended" cron error).
+2. **Create a dedicated test campaign** copied from a known-good campaign's config (same assistant
+   / Cal.com event / timezone, a short window e.g. 7 days, the normal attempt cap), with a
+   **hardcoded UUID** so the migration is idempotent and re-runnable.
+3. Create **NO `CampaignCallWindows` rows** for it. With no call windows, the campaign can **only
+   ever dial a contact that has a pending `dtNextContactRequested`** — never a normal-cadence
+   contact.
+4. **Link exactly ONE test contact** (by uuid, `INNER JOIN`-guarded so the migration no-ops on any
+   environment that lacks that contact). That single linked contact is the *only* thing the
+   campaign can dial, and only when you set its `dtNextContactRequested`.
+
+Reference implementation: `dbchanges2/Client_True/2026-07-20a - AiBdrTcoxTestCampaign.sql`
+(idempotent `NOT EXISTS` guards keyed to the real UNIQUE constraints; passed `sql-reviewer`). This
+proves the loop with **zero prospect exposure** instead of mass-writing flags on real contacts.
+
+## Rule 3 — NEVER dry-run against production
+
+`dryRun` in the dialer is **not** write-free: `createContactAttempt` runs **before** the dryRun
+early-return, writing a real `ContactAttempts` row (`dtStarted` set, `dtEnded NULL`) that counts
+toward `maxAttemptsPerContact` **and** wedges the contact as in-progress (excluded from all future
+dialing). See the dryRun gotcha in vapi-webhook-handler.md. Unwedge SQL:
+`UPDATE ContactAttempts SET dtEnded=NOW() WHERE contactId=? AND dtEnded IS NULL`.
+
+## Rule 4 — Validate the assistant identifier before assigning it
+
+`validateCampaignReady` only checks `assistantIdentifier` is **non-empty**, not that it is a
+well-formed Vapi UUID. A corrupt value (e.g. a 37-char uuid-plus-trailing-char) passes the gate
+and then **400s at Vapi** at call time. Confirm the assistant's identifier shape before wiring it
+to any campaign, test or real.
+
+## Why a true beta end-to-end CALL is impossible as currently wired
+
+Do **not** expect to place a real beta call and see its webhook land in the beta DB:
+
+- Vapi is **one production account**. Its assistants' `serverUrl` targets the **production**
+  webhook (`webhook.togahub.com`). A beta-placed call's `end-of-call-report` therefore posts to
+  **production**, where the `contactAttemptUuid` (created in the **beta** DB) has no matching row
+  → the write-back can never find its attempt.
+- **Beta is good only for rehearsing the SQL / eligibility logic** via a **local worker2 run**
+  (not a real call). Note `worker2/Config/beta.ini`'s `aws_worker_queue_url` still points at
+  `WorkerProductionQueue` — another reason not to trust beta for anything that enqueues work.
+
+A real end-to-end call test must run against production, which is exactly why the isolated
+one-contact test campaign (Rule 2) is the safe vehicle.
+
+## dbchanges2 execution caveat — don't ship create + cleanup in the same window
+
+The dbchanges2 external executor runs a folder's files **alphabetically in one pass**. Never place
+a create-migration and its cleanup/teardown migration in the **same** run window (same day/folder
+batch) — they will apply together in one pass and the cleanup will immediately undo the create.
+Sequence the cleanup into a later, separately-executed window. (See dbchanges2 architecture for the
+`YYYY-MM-DD<letter>` ordering contract.)
+
+## Change history
+- 2026-07-20 — Initial runbook. Captured the safe AI-BDR call-loop test procedure: never revive an
+  ended campaign with linked prospects (every-minute cron dials within 60s); use an isolated
+  one-contact test campaign with NO `CampaignCallWindows` (only requested `dtNextContactRequested`
+  calls can fire) as built in `dbchanges2/Client_True/2026-07-20a`; never dry-run in prod (writes a
+  wedging ContactAttempts row); validate the assistant identifier shape (non-empty check lets a
+  corrupt uuid 400 at Vapi); a true beta end-to-end call is impossible (single prod Vapi account →
+  webhook posts to prod, beta contactAttemptUuid unmatchable); and the dbchanges2 same-window
+  create+cleanup execution caveat. (tcox)
+</content>
+</invoke>

package/knowledge/2.0/apps/api2/features/nested-relationship-writes.md

@@ -6,13 +6,15 @@ project: API
 client: shared
 type: feature
 status: active
-updated: 2026-07-09
-owners: ["bala", "mhammontree"]
+updated: 2026-07-20
+owners: ["bala", "mhammontree", "tcox"]
 files:
   - api2/Component/Api/V2/V2.php
 related:
   - ../architecture.md
   - ../../../clients/aig/features/entitlement-intake.md
+  - ../../ai-bdr/features/web-funnel-app.md
+  - ../../worker2/features/vapi-webhook-handler.md
 ---
 
 ## Summary
@@ -58,6 +60,39 @@ rows on every write.
 If you need to link by a business key (like an employee XID), **resolve that key to a uuid in your
 caller first** (e.g. build a `key → uuid` map), then send `{uuid}`.
 
+## UPDATE-path back-reference injection defeats the uuid forced-MATCH (primary-pointer bug)
+
+A **single-key identifier object** (`{uuid: <x>}` and nothing else) is supposed to hit the
+engine's **forced-MATCH fast-path** (`V2.php:6952`) — link the existing child, never create,
+and let the caller re-point a parent's forward FK to it. On the **CREATE** path this works: the
+set-loop (`V2.php:4601–4616`) applies the child object and the parent FK is assigned at
+`V2.php:4647` with no interference.
+
+On the **UPDATE** path it does **not**. When a child model carries a `contactId` FK *back* to
+the parent (as `ContactPhoneNumbers` → `Contacts` does), the update path **injects a reverse
+back-reference** (sets the child's `contactId = parent id`) into the nested child object at
+`V2.php:4985–4996` — added by commit `91d803f` "guard child FK set". That injection turns the
+single-key object into a **multi-key** object, so it no longer qualifies for the forced-MATCH
+fast-path, and it diverts what `getForeignKeyValue()` returns **before** the parent's forward FK
+is assigned at `V2.php:5047`. Net effect: a `PUT {primaryContactPhoneNumber: {uuid}}` does **not**
+set `Contacts.primaryContactPhoneNumberId`, and the `PUT` response **echoes
+`primaryContactPhoneNumber: null`** on the miss — which callers can detect.
+
+**Scope.** Any **forward singular FK** whose child model has a back-FK to the parent is exposed
+on update — `primaryContactEmailAddress` / `primaryContactAddress` on `Contacts` are likely
+affected the same way. This is the exact root cause of the **BDR web-funnel "phone-less contact
+is never dialed"** bug (a phone added by a later `PUT` links a `ContactPhoneNumber` row but never
+becomes the primary): see
+[web-funnel-app.md](../../ai-bdr/features/web-funnel-app.md) and
+[vapi-webhook-handler.md](../../worker2/features/vapi-webhook-handler.md).
+
+**Suggested platform fix (deferred to its own PR/ticket):** gate the `4985–4996` injection to
+**true reverse / has-many** relations only, so a forward singular-FK child keeps its single-key
+forced-MATCH; confirm `RecordFields.childPolicy` for `Contacts.primaryContactPhoneNumberId` when
+fixing. Until then the caller-side workaround is a follow-up identifier-only `PUT` re-link with a
+self-heal that detects the null/mismatched echo (shipped on the BDR funnel side — see
+web-funnel-app.md).
+
 ## Per-API overrides (`Apis_RecordFields`)
 
 The base identifier flags above (`Core.RecordFields.isIdentifier`) can be **overridden per API**
@@ -100,6 +135,15 @@ beta/QA threw EV-12 on the injected `entitlementFulfillmentType` — see
 
 ## Change history
 
+- 2026-07-20 — Root-caused the **UPDATE-path** failure of the single-key-uuid forced-MATCH: the
+  update path injects a reverse back-reference (`contactId = parent id`) into nested child objects
+  at `V2.php:4985–4996` (commit `91d803f`) when the child has a back-FK to the parent, turning the
+  single-key object multi-key and diverting `getForeignKeyValue()` before the forward FK assignment
+  at `:5047` — so `PUT {primaryContactPhoneNumber:{uuid}}` never sets the pointer and the response
+  echoes `null`. CREATE path (`:4601–4616` / `:4647`) is unaffected. Scope: any forward singular FK
+  whose child has a back-FK to the parent (likely `primaryContactEmailAddress`/`primaryContactAddress`
+  too). This is the root cause of the BDR web-funnel phone-less-contact dialer bug; platform fix
+  deferred to its own PR (gate the injection to true reverse/has-many relations). (tcox)
 - 2026-07-09 — Documented the per-API `Apis_RecordFields` override layer (`overrideIsIdentifier`,
   `overrideChildPolicy`) and the trap that a `NULL` `overrideIsIdentifier` is read as "not an
   identifier" (`!$row->overrideIsIdentifier`) — an override row set only for a child policy

package/knowledge/2.0/apps/worker2/features/vapi-webhook-handler.md

@@ -6,7 +6,7 @@ project: Worker
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-20
 owners: [snaredla, tcox]
 files:
   - worker2/Worker/Vapi.php
@@ -14,6 +14,8 @@ files:
 related:
   - ../../ai-bdr/features/call-orchestration.md
   - ../../ai-bdr/features/vapi-integration.md
+  - ../../ai-bdr/workflows/safe-call-loop-testing.md
+  - ../../api2/features/nested-relationship-writes.md
 ---
 
 ## Summary
@@ -152,6 +154,34 @@ truth for **"why isn't my contact being called."** Confirmed against source
 `initiateCallForContact(…, CALL_TYPE__IMMEDIATE)`. It errors **"not assigned to any active
 campaign"** if no ACTIVE/PENDING campaign-contact link exists.
 
+### Finer detail (source-verified 2026-07-20)
+
+Where each gate actually lives in `Worker/Ai/Bdr/Vapi.php`, and where the eligibility summary
+above is easy to over-read:
+
+- **The campaign gate is split across two methods.** `getActiveCampaignsForDialing` (L177–193)
+  filters **only** `Campaigns.isActive = 1` + `INNER JOIN CampaignAssistants` — there is **no
+  date check there**. The date-range gate lives in `validateCampaignReady` (L759–789), which
+  throws **"Campaign has ended / not started"** and separately requires the `campaignAssistantId`
+  to resolve to a **NON-EMPTY `assistantIdentifier`**. So an active campaign with a valid assistant
+  can still be rejected every run purely because `dateEnd`/`dateStart` is out of range.
+- **`Campaigns_Contacts.status IN ('PENDING','ACTIVE')` is required ONLY when
+  `dtNextContactRequested IS NULL`** (L237). On a requested (web-funnel call-now/scheduled) contact
+  the status is not checked. **`PENDING` is a NORMAL dialable state** — the webhook resets links to
+  `PENDING` for retries, so "stuck on PENDING" is **not** a blocker signal.
+- **The prior-DNC / terminal-outcome exclusion is BYPASSED when `dtNextContactRequested` is set.**
+  The exclusion (L314–331: `c_dncRequested`, `DO_NOT_CALL`, `MEETING_BOOKED` / `DNC_REQUESTED`
+  outcomes) applies only on the non-requested path; a customer who actively re-engages
+  (`dtNextContactRequested`) is dialed regardless of a prior terminal outcome.
+- **The normal (non-requested) path requires a `CampaignCallWindows` row to EXIST for the current
+  day/time.** A campaign with **no** call-window rows can therefore **only ever dial contacts with a
+  pending `dtNextContactRequested`** — this is the **safest launch posture for a web-funnel-only
+  campaign** (see the safe call-loop testing workflow in
+  `../../ai-bdr/workflows/safe-call-loop-testing.md`).
+- **Per-run cap + in-progress exclusion.** Results are `LIMIT MAX_CALLS_PER_MINUTE` per run, and the
+  in-progress check excludes any contact with an **open attempt** (`dtStarted` set, `dtEnded NULL`)
+  for that campaign — see the dryRun gotcha below for how a stray open attempt wedges a contact.
+
 ### Gotcha — a phone-less contact is silently never dialed (BDR web funnel)
 
 Criterion 4's `INNER JOIN` on `primaryContactPhoneNumberId` is why a contact whose phone was
@@ -160,10 +190,33 @@ added **after** creation can be invisible to the dialer: **api2 creates the
 (it only links the primary on CREATE). The BDR web funnel hits this for any phone-less HubSpot
 contact — the visitor's typed phone arrives via a later `PUT /contacts/{uuid}`, so the row
 exists but the primary pointer stays null and the eligibility join excludes it. Re-submitting
-does not fix it (verified in production). See
-`../../ai-bdr/features/web-funnel-app.md` for the funnel side. Fix candidates: api2 sets the
-primary on phone-row create-during-update, or a caller-side `PUT` linking the existing
-phone-row uuid as primary.
+does not fix it (verified in production). The **exact api2 root cause** is now documented — the
+UPDATE path injects a reverse back-reference into the nested child object, defeating the
+single-key-uuid forced-MATCH fast-path (see
+[api2 nested-relationship-writes.md](../../api2/features/nested-relationship-writes.md)). The
+platform fix is deferred; a **funnel-side self-heal has SHIPPED** (`bdr/src/server/toga.ts`):
+after any contact write that carried a phone, if the echoed `primaryContactPhoneNumber` is null or
+its last-10 digits don't match what was sent, BDR finds/creates the `ContactPhoneNumber` row uuid
+and re-links it with an identifier-only `PUT {primaryContactPhoneNumber:{uuid}}`. So on the funnel
+side this is resolved once the fix deploys — see `../../ai-bdr/features/web-funnel-app.md`.
+
+### Gotcha — `dryRun` is NOT write-free; it wedges contacts (never dry-run in prod)
+
+`createContactAttempt` (which sets `dtStarted = NOW()`, `dtEnded NULL`) executes **BEFORE** the
+`dryRun` early-return (L438–466 / L685–708). So a "dry run" writes a **real `ContactAttempts` row
+for every eligible contact** — it counts toward `maxAttemptsPerContact` **and** wedges the contact
+as "in progress" (the open-attempt check above then excludes it from **all** future dialing) until
+someone sets `dtEnded`. **Never dry-run against production.** Fix candidate: move
+`createContactAttempt` below the `dryRun` return (build the payload with a placeholder uuid).
+Unwedge SQL: `UPDATE ContactAttempts SET dtEnded=NOW() WHERE contactId=? AND dtEnded IS NULL`.
+
+### Gotcha — a corrupt `assistantIdentifier` passes validation but 400s at Vapi
+
+`validateCampaignReady` only checks that `assistantIdentifier` is **non-empty**, not that it is a
+well-formed Vapi assistant UUID. A corrupt identifier (e.g. a valid uuid with an extra trailing
+character — a 37-char value) **passes** the readiness gate and the campaign is dialed, then the
+Vapi `POST /call/phone` **400s** at call time. Validate the assistant identifier's shape before
+assigning an assistant to any campaign.
 
 ## Data model
 
@@ -192,6 +245,18 @@ status. See the `ai-bdr` skill / `_Model_True_ContactAttempt` for the full field
 - [VAPI Integration — assistants, tools, structured output](../../ai-bdr/features/vapi-integration.md)
 
 ## Change history
+- 2026-07-20 — Source-verified corrections/extensions to the dialer eligibility rules: the campaign
+  gate is split (`getActiveCampaignsForDialing` L177–193 = isActive+assistant, NO date; date range +
+  non-empty `assistantIdentifier` in `validateCampaignReady` L759–789); `Campaigns_Contacts.status
+  IN (PENDING,ACTIVE)` required ONLY when `dtNextContactRequested IS NULL` (PENDING is normal/dialable);
+  prior-DNC/terminal-outcome exclusion is bypassed on the requested path; a campaign with NO
+  `CampaignCallWindows` rows can only dial requested contacts (safest web-funnel launch posture);
+  per-run `LIMIT MAX_CALLS_PER_MINUTE` + open-attempt exclusion. Added gotchas: (1) `dryRun` is NOT
+  write-free — `createContactAttempt` runs before the dryRun return, writing a real ContactAttempts
+  row that counts toward the attempt cap AND wedges the contact as in-progress (never dry-run in
+  prod; unwedge SQL provided); (2) a corrupt `assistantIdentifier` passes the non-empty check but
+  400s at Vapi. Updated the phone-less-contact gotcha: exact api2 root cause now documented and a
+  funnel-side self-heal (`bdr/src/server/toga.ts`) has shipped. (tcox)
 - 2026-07-16 — Documented the outbound dialer eligibility rules from source
   `getEligibleContactsForVapi()` (the 6 ALL-of criteria, the `dtNextContactRequested <= NOW()`
   window/cadence bypass = the website call-now/scheduled path, cron entry chain, and the single

package/knowledge/INDEX.md

@@ -27,7 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 7 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
-- **ai-bdr** (AI-BDR) — 7 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
+- **ai-bdr** (AI-BDR) — 8 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 9 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)
 - **toga25-supply** (TOGa 2.5 Supply) — 10 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/INDEX.md)
 - **toga-blox** (TOGa Blox) — 7 doc(s) → [2.0/apps/toga-blox/INDEX.md](2.0/apps/toga-blox/INDEX.md)

package/package.json

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