toga-ai 1.0.374 → 1.0.376

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -2,7 +2,6 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [Proposed — ExternalIdentifiers map table for integration id ↔ external-system linkage](architecture/external-identifiers-map-table.md) | A **proposal / counter-proposal (status: proposed — nothing here is built)** that cross-system identifier linkage (e.g. | _underscore/Model/Forecast/Opportunity.php, worker2/Worker/Netsuite/Opportunity.php |
 | [Proposed — git-sourced base+overlay JSON authoring for the Surface layer](architecture/surface-authoring-proposal.md) | A **proposal / handoff recommendation** (not implemented) that the Surface layer's *authoring* model move off hand-authored SQL against the `SurfaceOverrides` E | _underscore/Model/Core/Surface.php, _underscore/Model/Client/SurfaceOverride.php |
 | [_underscore Framework Architecture](architecture.md) | `_underscore` is the shared PHP backend framework for **all 2.0 applications**. | _underscore/_underscore.php, _underscore/Loader.php, _underscore/Framework.php, _underscore/Model.php, _underscore/Database.php, _underscore/Query.php, _underscore/Route.php, _underscore/Component.php |
 | [ACL Permission Chain (Record & Field Authorization)](features/acl-permission-chain.md) | Authorization in the 2.0 API is **metadata-driven**: whether a role may Create/Read/Update/Delete a record is decided by rows across **four linked tables**, not | api2/Component/Api/V2/V2.php, _underscore/Model/Core/Page.php, dbchanges2/Client/2026-06-03- BLANK_CLIENT_DATABASE.sql, dbchanges2/Client/2026-06-23b - ItemTranslationsAcl.sql |

package/knowledge/2.0/apps/toga25-supply/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [TOGa 2.5 Supply — Architecture](architecture.md) | `toga25-supply` ("TOGa 2.5 Supply") is the **React/TypeScript frontend** for the 2.0 Supply application — an iteration and improvement of `toga2-supply`. | toga25-supply/src/main.tsx, toga25-supply/src/App.tsx, toga25-supply/src/routes.tsx, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/layout/, toga25-supply/src/pages/, toga25-supply/src/hooks/useTableCellInteractions.ts |
 | [Action-Button Rule Engine (Flag / Rule grammar)](features/action-button-rule-engine.md) | A declarative, fully config-driven rule engine that resolves the boolean-ish flags (`isEnabled`, `isVisible`, `isComplete`) on SalesOrder action-button options. | toga25-supply/src/pages/SalesOrders/helpers/evaluateEnableRule.ts, toga25-supply/src/pages/SalesOrders/helpers/buildPatchedTenantFields.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderApprovalModalsLayout/viewModel/useApprovalModalViewModel.tsx |
+| [Client API-Fetch Fields (useClientApiFields / apiFields.json)](features/client-api-fetch-fields.md) | The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` / `join` / `where` to request from the TOGa API for a given page — fr | toga25-supply/src/fieldsConfig/resolveApiConfig.ts, toga25-supply/src/fieldsConfig/useClientApiFields.ts, toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx |
 | [Client-Configurable Fields (useClientFields / fieldsConfig)](features/client-configurable-fields.md) | The mechanism for config that **varies by client** (or client × role) — field overrides, filter buttons, group-by options, column pickers, layout toggles — with | toga25-supply/src/fieldsConfig/index.ts, toga25-supply/src/fieldsConfig/useClientFields.ts, toga25-supply/src/pages/SalesOrders/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/viewModel/FIELDS/, toga25-supply/src/pages/Inventory/README.md, toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/layout/VendorItemRecordModalLayout/viewModel/FIELDS/, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/view/sections/SalesOrderTopBar.tsx, toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/ |
 | [Column Visibility (URL-driven show/hide columns)](features/column-visibility.md) | A "Columns" header button that opens a modal listing every column from the table meta, lets the user show/hide columns, adjusts the table live, and persists the | toga25-supply/src/components/ColumnVisibilityModal/, toga25-supply/src/pages/SalesOrders/SalesOrders.tsx, toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableData.tsx |
 | [Meta-Driven Page & Table Setup](features/meta-driven-table-data.md) | A page in this app is **meta-driven end to end**: the page view model fetches *page meta* (labels, sections, ACL) and *table meta* (the columns/fields + table s | toga25-supply/src/pages/SalesOrders/viewModel/useSalesOrdersPageViewModel.tsx, toga25-supply/src/pages/SalesOrders/hooks/useSalesOrdersTableState.ts, toga25-supply/src/hooks/useTablePageMeta.ts, toga-blox-npm/dist/hooks/useFetchPageMeta.d.ts, toga-blox-npm/dist/hooks/useFetchTablePageMeta.d.ts, toga-blox-npm/dist/hooks/useAssignTableFieldLabels.d.ts, toga-blox-npm/dist/components/Table/hooks/useTableData.d.ts |

package/knowledge/2.0/apps/toga25-supply/features/client-api-fetch-fields.md

@@ -0,0 +1,136 @@
+---
+title: Client API-Fetch Fields (useClientApiFields / apiFields.json)
+framework: "2.0"
+repo: toga25-supply
+project: TOGa 2.5 Supply
+client: shared
+type: feature
+status: active
+updated: 2026-07-20
+owners: [apeterson]
+files:
+  - toga25-supply/src/fieldsConfig/resolveApiConfig.ts
+  - toga25-supply/src/fieldsConfig/useClientApiFields.ts
+  - toga25-supply/src/fieldsConfig/index.ts
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json
+  - toga25-supply/src/pages/SalesOrders/view/SalesOrderRecordModalLayout/viewModel/useSalesOrderRecordModalLayoutModel.tsx
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/FIELDS/apiFields.json
+  - toga25-supply/src/layout/ItemRecordModalLayout/viewModel/useItemRecordModalViewModel.tsx
+related:
+  - client-configurable-fields.md
+  - surface-frontend.md
+---
+
+## What it is
+
+The mechanism that resolves a client's **API-fetch projection** — which `fields` / `ojoin` /
+`join` / `where` to request from the TOGa API for a given page — from **one colocated
+`apiFields.json` file per page**, keyed by client slug. It is the fetch-projection sibling of
+[client-configurable-fields](client-configurable-fields.md) (`useClientFields`): that hook
+resolves **presentation** config (now largely moving to the DB-backed
+[Surface layer](surface-frontend.md)); this hook resolves **what data to fetch**.
+
+The split exists because presentation config migrated to Surface, leaving the API-fetch wiring
+coupled to a now-legacy `orderViewFields`/`*RecordViewFields` blob (formerly the
+`salesOrderDetailsConfig` / `itemRecordDetailsConfig` keys). This mechanism extracts the fetch
+projection into its own scalable per-page file + a shared resolver, keeping the central
+`fieldsConfig/index.ts` registry lean — **each page owns its own `apiFields.json`** rather than
+folding every page's fetch config into `fieldsConfig/index.ts`.
+
+## How it works
+
+Two new files in `src/fieldsConfig/`, re-exported from `fieldsConfig/index.ts`:
+
+1. **`apiFields.json` (per page, colocated in the page's `viewModel/FIELDS/`).** A map keyed by
+   client slug (uppercase — `DEFAULT`, `COMPASS`, `COMPASSCANADA`, `NYCHH`, …). The `DEFAULT`
+   block is the **full base**. Each per-client block is one of two shapes:
+   - **Delta** — `{ "extends": "DEFAULT", ...only the differences }`, merged over its parent.
+     Use for the common 1–3 field tweak; adding a field to `DEFAULT` then reaches every client.
+   - **Full override** — a complete config with **no `extends`**, returned verbatim. Use when a
+     client diverges substantially (many fields / different joins / different `where` clauses).
+
+2. **`resolveApiConfig(map, clientSlug)`** — a pure, recursive deep-merge resolver:
+   - **Array fields** (`fields`, `ojoin`, `join`) support `add<Field>` / `remove<Field>` sugar
+     (`addFields`, `removeFields`, `addOjoin`, …) to tweak the parent's array, **or** you restate
+     the array literally to replace it wholesale (a literal wins over add/remove).
+   - **Nested objects** merge recursively; **scalars / new keys** replace the parent value.
+   - **Array element identity** for dedupe/removal: strings by value, join objects by their
+     **first object key** (e.g. `{ "Items": {...} }` → `Items`), else by JSON form. Results are
+     deduped.
+   - Supports **chained `extends`** (a client can extend another client) with a **cycle guard**
+     (a re-visited slug returns its own delta un-merged). An **unknown client falls back to
+     `DEFAULT`**; a missing `DEFAULT` yields `{}`.
+
+3. **`useClientApiFields(map)`** — reads the client slug via
+   `useHostnameStore.getState().getHostname()` (the **same** slug source as `useClientFields`),
+   then `useMemo`s `resolveApiConfig(map, slug)` so consumers get a **stable object reference**
+   and the react-query fetch cache key does not churn every render. API-fetch fields are
+   **client-only** — there is no role dimension (they describe *what to fetch*, not a per-role
+   view).
+
+The view model consumes it directly:
+
+```ts
+const salesOrderDetailsConfig = useClientApiFields(apiFields) as Parameters<
+  typeof useFetchSalesOrderRecord
+>[1];
+```
+
+## Hybrid dedup model (decision)
+
+The per-client shape is deliberately a **hybrid**: `DEFAULT` base + per-client delta, with a
+full-override escape hatch. Chosen over full-copy-per-client because differences are usually
+1–3 fields (the delta case, kept DRY so a field added to `DEFAULT` reaches every client) but can
+be 5+ fields plus different joins/where clauses (the full-override case). Full-copy-per-client
+drifts too fast across 6+ clients. The resolver location is likewise a decision: a **generic
+colocated hook** (per-page `apiFields.json` + one shared hook), **not** folding every page's
+fetch config into the central `fieldsConfig/index.ts`.
+
+## Adopting the pattern on a page
+
+1. Add `viewModel/FIELDS/apiFields.json`: a `DEFAULT` full base, plus a block per client that
+   diverges (`extends: "DEFAULT"` + `add<Field>`/`remove<Field>` deltas, or a no-`extends` full
+   override). A client whose config is byte-identical to `DEFAULT` can be **omitted** — the
+   resolver's DEFAULT fallback covers it.
+2. Wire the view model to `useClientApiFields(apiFields)`, casting to the fetch hook's param type
+   (`Parameters<typeof useFetch...>[1]`).
+3. Delete the now-dead fetch block from the legacy presentation JSON (single source of truth).
+
+**Adopted so far:**
+- **SalesOrder record modal** — `SalesOrderRecordModalLayout/viewModel/FIELDS/apiFields.json`
+  (DEFAULT full base; COMPASS / COMPASSCANADA as `extends: DEFAULT` + `addFields` deltas, e.g.
+  `_totalLease`, `c_erpEntityId`). The view model's `salesOrderDetailsConfig` now comes from
+  `useClientApiFields(apiFields)` instead of `tenantFields.salesOrderDetailsConfig`; the dead
+  `salesOrderDetailsConfig` block was removed from `FIELDS/DEFAULT/orderViewFields.json`.
+- **Item record modal** — `ItemRecordModalLayout/viewModel/FIELDS/apiFields.json` (DEFAULT full
+  base of 31 fields; COMPASS + COMPASSCANADA as `extends: DEFAULT` + a 6-field `addFields` delta:
+  `_leasePrice`, `_leasePrice12Months`, 4× `personaItems.*`; **NYCHH omitted** — byte-identical to
+  DEFAULT). The view model consumes `useClientApiFields(apiFields)` (dropping its own
+  `useClientFields`; view sections still read `useClientFields` in the view components). The dead
+  `itemRecordDetailsConfig` block was removed from all four client
+  `itemRecordViewFields.json` files, which now hold only presentation keys
+  (`header`/`sections`/`editItem`).
+
+## Gotchas
+
+- **Field order in a `fields` projection array is irrelevant to the TOGa API fetch.** The API
+  returns requested fields regardless of order, and the reshape/view logic reads by key — so
+  append-style delta merges (added fields land at the end) are **safe** and do not change
+  behavior. This is why `add<Field>` sugar can append without needing positional control.
+- **Omit a client that matches `DEFAULT`.** Don't author a byte-identical client block — the
+  resolver falls back to `DEFAULT` for any unknown/absent client, so an identical block is pure
+  drift risk (NYCHH on the Item modal is deliberately absent).
+- **Same slug source as presentation.** The slug comes from `useHostnameStore.getHostname()` (the
+  same source as `useClientFields`); don't introduce a second slug resolution path.
+
+## Change history
+- 2026-07-20 — Built the client-based API-fetch fields mechanism: `resolveApiConfig` (pure
+  recursive deep-merge with `add`/`remove` array sugar, literal-replace, chained `extends` +
+  cycle guard, DEFAULT fallback) + `useClientApiFields` (client-only, slug via `useHostnameStore`,
+  memoized for stable fetch cache keys), each page owning a colocated `apiFields.json`. Adopted on
+  the SalesOrder and Item record modals; removed the dead `salesOrderDetailsConfig` /
+  `itemRecordDetailsConfig` fetch blocks from the legacy presentation JSON. Decision: hybrid
+  DEFAULT-base + per-client-delta with a full-override escape hatch (over full-copy-per-client).
+  Discovered: `fields`-array order is irrelevant to the API fetch. (apeterson)
+</content>
+</invoke>

package/knowledge/2.0/apps/toga25-supply/features/client-configurable-fields.md

@@ -22,6 +22,7 @@ related:
   - ../architecture.md
   - column-visibility.md
   - action-button-rule-engine.md
+  - client-api-fetch-fields.md
 ---
 
 ## What it is
@@ -31,6 +32,14 @@ filter buttons, group-by options, column pickers, layout toggles — without har
 the view model or rebuilding per client. All such config resolves through `src/fieldsConfig`
 and the `useClientFields()` hook.
 
+> **Scope — presentation, not fetch.** This doc covers **presentation/UI** config. A client's
+> **API-fetch projection** (which `fields`/`ojoin`/`join`/`where` to request) now lives in a
+> separate per-page `apiFields.json` resolved by `useClientApiFields` — see
+> [client-api-fetch-fields](client-api-fetch-fields.md). The old fetch keys
+> (`salesOrderDetailsConfig` in `orderViewFields`, `itemRecordDetailsConfig` in
+> `itemRecordViewFields`) were **extracted out** of these presentation JSON files; those files
+> now hold presentation keys only.
+
 ## How it works
 
 1. **Per-client JSON lives next to the consuming page _or layout_**, under `FIELDS/<CLIENT>/`
@@ -159,6 +168,11 @@ modal's chrome from the same per-client JSON, not from the component:
   `vendorItemRecordViewFields` are record-modal-layout examples living under `src/layout/.../viewModel/FIELDS/`.
 
 ## Change history
+- 2026-07-20 — Extracted the **API-fetch projection** out of these presentation JSON blobs into a
+  new per-page `apiFields.json` + `useClientApiFields` mechanism (see
+  [client-api-fetch-fields](client-api-fetch-fields.md)). The `salesOrderDetailsConfig` block was
+  removed from `FIELDS/DEFAULT/orderViewFields.json` and the `itemRecordDetailsConfig` block from
+  all four `itemRecordViewFields.json` files; those files now hold presentation keys only. (apeterson)
 - 2026-07-01 — De-roled `orderViewFields` from client×role to **client-only**: COMPASS/COMPASSCANADA
   now read a flat client JSON via `mergeOrderView(...)` in `fieldsConfig/index.ts` (COMPASSCANADA's
   JSON flattened from byte-identical `{ADMIN,MANAGER}`). Fixed a latent bug where COMPASS's

package/knowledge/2.0/apps/worker2/features/netsuite-opportunity-sync.md

@@ -31,7 +31,6 @@ files:
 related:
   - ./netsuite-salesorder-open-orders-sync.md
   - ../architecture.md
-  - ../../_underscore/architecture/external-identifiers-map-table.md
 ---
 
 ## Summary
@@ -178,9 +177,6 @@ tasks. The fix is a **race-safe DB claim** on the **existing `Forecast.Opportuni
 `NetsuiteOpportunityClickupTask` table in `Client_True`; reviewer Rohan Girish rejected that and mandated
 reusing `Forecast.Opportunities`.)
 
-A counter-proposal (ExternalIdentifiers map table) has been raised — see
-`_underscore/architecture/external-identifiers-map-table.md`; unresolved.
-
 How the claim is race-safe:
 - **Conditional UPDATE = the atomic claim.** A raw `_Query`:
   `UPDATE Opportunities SET clickupTaskId='<uuid sentinel>' WHERE netsuiteOpportunityInternalId=X AND

package/knowledge/INDEX.md

@@ -17,7 +17,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 2.0 framework
 
-- **_underscore** (_Underscore) _(framework core)_ — 35 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
+- **_underscore** (_Underscore) _(framework core)_ — 34 doc(s) → [2.0/apps/_underscore/INDEX.md](2.0/apps/_underscore/INDEX.md)
 - **worker2** (Worker) — 30 doc(s) → [2.0/apps/worker2/INDEX.md](2.0/apps/worker2/INDEX.md)
 - **api2** (API) — 12 doc(s) → [2.0/apps/api2/INDEX.md](2.0/apps/api2/INDEX.md)
 - **dbchanges2** (Database Changes) _(framework core)_ — 3 doc(s) → [2.0/apps/dbchanges2/INDEX.md](2.0/apps/dbchanges2/INDEX.md)
@@ -29,7 +29,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **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)
 - **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) — 9 doc(s) → [2.0/apps/toga25-supply/INDEX.md](2.0/apps/toga25-supply/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)
 - **bdr** (BDR) — 0 doc(s) → [2.0/apps/bdr/INDEX.md](2.0/apps/bdr/INDEX.md)
 

package/package.json

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

package/knowledge/2.0/apps/_underscore/architecture/external-identifiers-map-table.md

@@ -1,97 +0,0 @@
----
-title: Proposed — ExternalIdentifiers map table for integration id ↔ external-system linkage
-framework: "2.0"
-repo: _underscore
-project: _Underscore
-client: shared
-type: architecture
-status: proposed
-updated: 2026-07-17
-owners: ["dfranks"]
-files:
-  - _underscore/Model/Forecast/Opportunity.php
-  - worker2/Worker/Netsuite/Opportunity.php
-related:
-  - ../features/model-save-vs-query-atomic-update.md
-  - ../../worker2/features/netsuite-opportunity-sync.md
----
-
-## Summary
-
-A **proposal / counter-proposal (status: proposed — nothing here is built)** that cross-system
-identifier linkage (e.g. a NetSuite opportunity ↔ its ClickUp task id) live in a dedicated
-**`ExternalIdentifiers` map table** rather than as ad-hoc columns bolted onto whichever business
-table happens to be nearby. The immediate driver is the TRUE-80044 atomic ClickUp-task claim, whose
-currently-mandated approach adds a `clickupTaskId` column to `Forecast.Opportunities`. This doc is
-`dfranks`'s architectural counter-proposal to that mandate, raised for open discussion — **not** a
-silent supersede of the reviewer decision. See the rebuttal section below.
-
-**Critical framing:** This is a **proposal under open discussion**, not the current system and not a
-settled reversal. The mandated approach on record (a `clickupTaskId` column on
-`Forecast.Opportunities`) remains the standing decision until the disagreement is resolved with the
-reviewer.
-
-## Design
-
-A single **source-generic, single-anchor** mapping table in the integration schema
-(`Client_True` / `DB_TRUE`, **not** Forecast). A source system + its record id anchor the entity; a
-target system + its id are the mapping. NetSuite is a `sourceSystem` *value* (`'netsuite'`), never a
-privileged column, and there is deliberately **no** cross-system correlation key (`entityUuid`):
-every integration asks the same single-anchor question — "for this source record, what's its
-ClickUp/Salesforce/… id?" — which needs no id-to-id web.
-
-- **Columns:** `id`, `entityType` (e.g. `opportunity`), `sourceSystem` (e.g. `netsuite`),
-  `sourceId` (the source record id), `targetSystem` (e.g. `clickup`), `targetExternalId` (the value;
-  `NULL` = claimed/in-flight), `dtCreated`/`dtUpdated`. No synthetic row `uuid` — `uq_claim` is the
-  natural key.
-- **Uniqueness:** `UNIQUE (entityType, sourceSystem, sourceId, targetSystem)` = the atomic claim
-  (one mapping per source record per target system); `UNIQUE (targetSystem, entityType,
-  targetExternalId)` = no two source records share one target id (NULLs exempt, so many in-flight
-  rows coexist).
-- **Atomic claim = one `INSERT IGNORE` + `getAffectedRows()`** — no sentinel value, no correlation
-  step: the row's presence is the claim, `targetExternalId IS NULL` marks in-flight. Raw `_Query` is
-  required because the ORM `save()` cannot express a conditional/affected-rows write — see
-  [model-save-vs-query-atomic-update](../features/model-save-vs-query-atomic-update.md). Winner
-  writes `targetExternalId` back via the model; failure path deletes the in-flight row
-  (`… AND targetExternalId IS NULL`). Because the table stands alone, the claim has **no ordering
-  dependency** on the Forecast import (unlike a column claim, which needs the opportunity row
-  upserted first).
-- **Scales without schema change:** a new integration adds rows with a new `targetSystem` value; a
-  new source adds a new `sourceSystem` value. Keyed on the source record id in the integration
-  schema, the mapping is independent of the Forecast DB by construction.
-
-The `entityUuid`/cross-system-correlation variant is deliberately avoided — it only pays off if the
-*source* system (NetSuite) itself stopped being the identity anchor, which is not a concern here.
-
-## Rebuttal to the clickupTaskId-column mandate
-
-`2.0/apps/worker2/features/netsuite-opportunity-sync.md` records reviewer **Rohan Girish** mandating
-(2026-07-15) that the ClickUp-task dedup claim be implemented as a **`clickupTaskId` column on
-`Forecast.Opportunities`**, and rejecting the earlier plan's dedicated table. This doc is `dfranks`'s
-**counter-proposal**, offered as an open architectural disagreement to be resolved *with* the
-reviewer — the mandate stands until then. The three rebuttal arguments:
-
-1. **Separation of concerns.** A ClickUp task id is *integration-linkage* state, not a business
-   attribute of a Forecast opportunity. Storing it on `Forecast.Opportunities` conflates the
-   integration/mapping layer with the forecasting domain model.
-2. **Forecast-schema dumping-ground.** Every future external linkage (a second external system, a
-   different id kind) under the column approach means another one-off nullable column on a business
-   table, accreting integration cruft on the Forecast schema. A map table absorbs all of them with
-   no schema change per linkage.
-3. **Forecast-sync lifecycle decoupling.** The integration mapping must be able to **outlive a
-   possibly-discontinued Forecast sync.** Binding the ClickUp linkage to the Forecast opportunity row
-   ties its lifetime to the Forecast importer; if that sync is ever retired or reworked, the mapping
-   goes with it. A standalone map table keeps the NS↔ClickUp linkage durable independently of
-   Forecast.
-
-This is framed as a disagreement to resolve, not a reversal already taken. If the reviewer position
-holds, the mandated column approach is what ships.
-
-## Change history
-
-- 2026-07-17 — Proposed as a rebuttal to the reviewer-mandated clickupTaskId-column approach
-  (TRUE-80044). (dfranks)
-- 2026-07-17 — Refined to a source-generic, single-anchor design: `(sourceSystem, sourceId,
-  targetSystem)` key with a single `INSERT IGNORE` claim; dropped the `entityUuid` correlation/two-
-  step as over-engineered for the stated concerns (future integrations + Forecast-sync decoupling),
-  both of which the single-anchor key already satisfies. (dfranks)