toga-ai 1.0.372 → 1.0.374

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

@@ -33,19 +33,35 @@ reviewer.
 
 ## Design
 
-A single shared table keyed by (local record identity, external system, external id kind):
+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 (sketch):** `id`, `entityType` (e.g. `opportunity`), `entityId` (the local business
-  key, e.g. `netsuiteOpportunityInternalId`), `externalSystem` (e.g. `clickup`), `externalIdKind`
-  (e.g. `task`), `externalId` (the value/sentinel), plus `dtCreated`/`dtUpdated`.
-- **Uniqueness:** a UNIQUE index on `(entityType, entityId, externalSystem, externalIdKind)` — this
-  is the single-row lock that makes the atomic claim (`UPDATE … SET externalId='<uuid sentinel>'
-  WHERE … AND externalId IS NULL`, commit, `affectedRows===1` wins) work exactly as the mandated
-  column approach would, but without touching the Forecast schema.
-- **Atomic claim mechanics are unchanged** from the mandated design — same raw `_Query` guarded
-  UPDATE (ORM `save()` cannot express it — see
-  [model-save-vs-query-atomic-update](../features/model-save-vs-query-atomic-update.md)), same
-  commit-before-external-side-effect, same sentinel-guarded compensation-delete on failure.
+- **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
 
@@ -75,3 +91,7 @@ holds, the mandated column approach is what ships.
 
 - 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)

package/package.json

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