toga-ai 1.0.374 → 1.0.375

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/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.374",
+  "version": "1.0.375",
   "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)