toga-ai 1.0.787 → 1.0.788

package/knowledge/2.0/apps/dbchanges2/architecture.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-09-04
+updated: 2026-09-09
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -72,19 +72,21 @@ team-maintained `id`s** — ask the developer for the next value before insertin
 > trailing-space quirk like `2026-06-03- BLANK_CLIENT_DATABASE.sql`). The **only** hard rule
 > is the leading `YYYY-MM-DD<letter>` so ordering holds.
 
-## One file per type per build (keep change files consolidated)
+## One file per realm per turn (keep change files consolidated)
 
-**Prefer a single `.sql` file per database type (folder) per build.** When a session produces
-several changes for the same target — e.g. three separate files under `Core/`, or four under
-`Client/` — **consolidate them into one dated file** for that folder instead. Multiple same-type
-files in one build are not forbidden, but they have become too common; keep it to one per type
-unless they genuinely must be separate (for example, an ordering gap where another folder's file
-must run between them).
+**Prefer a single `.sql` file per realm (folder) per turn.** A *realm* is the target database a
+folder maps to — `Core`, the shared `Client`, a single tenant like `Client_True`, `Logs`, a module,
+and so on. When one response produces several changes for the **same** realm — e.g. three separate
+files under `Core/`, or four under `Client/` — **consolidate them into one dated file** for that
+folder instead of writing several. This is a **strong preference**, not an absolute rule: multiple
+same-realm files in one turn are allowed when they genuinely must be separate (for example, an
+ordering gap where another folder's file must run **between** them).
 
-- Combine same-folder statements into one `YYYY-MM-DD<letter> - <Description>.sql`.
-- Different folders (types) stay in their own files — that split is required (see isolation).
-- The `dbchanges2-file-sprawl` hook warns when a second file of the same type is created in a
-  session, as a reminder to consolidate.
+- Combine same-realm statements into one `YYYY-MM-DD<letter> - <Description>.sql`.
+- Different realms (folders) stay in their own files — that split is **required** (see isolation);
+  never mix two realms in one file.
+- The `dbchanges2-file-sprawl` hook warns when a second file for the same realm is created in a
+  turn, as a reminder to consolidate.
 
 ## Folder → database mapping
 
@@ -362,12 +364,23 @@ its own header.)
    the relevant clients list `<module>` in their `_modules.txt`.
 5. Never edit or re-date an already-applied file — add a new dated file instead. Never put new
    work in a `HISTORIC` folder.
-6. **Never seed a `uuid` column with MySQL `UUID()`.** The 2.0 standard requires a fully-random
-   **v4** UUID; `UUID()` is time/MAC-based (v1) and violates it. Since a migration can't call
-   `_String::generateUuid()`, **pre-generate a v4 UUID literal** (e.g. a v4 generator) and
-   hardcode the literal string in the `VALUES` clause. One earlier migration
-   (`Core/2026-05-08 … CronJobs_WorkerCleanup_insert`) used `UUID()` — that is a known violation,
-   not a precedent to copy. First applied correctly in
+6. **Never seed a `uuid` column with MySQL `UUID()` — not even in a bulk insert.** The 2.0 standard
+   requires a fully-random **v4** UUID; `UUID()` is time/MAC-based (v1) and violates it. Since a
+   migration can't call `_String::generateUuid()`:
+   - **Single-row insert:** **pre-generate a v4 UUID literal** (a real v4 generator) and hardcode
+     the literal string in the `VALUES` clause.
+   - **Multi-row / bulk `INSERT … SELECT`:** use the inline `RANDOM_BYTES()` v4 expression (see
+     `features/rerunnable-additive-inserts.md` → *Generating a real UUID4 inline*), never `UUID()`.
+
+   **Every UUID must be freshly, fully random — never derive one from another.** Do **not** take a
+   known uuid and bump a digit (`…-0001`, `…-0002`, …), copy-and-tweak, or otherwise pattern them.
+   When a file needs several literals, generate each one independently at random. (Patterned uuids
+   are guessable and defeat the uniqueness guarantee.) The one intended exception is a fan-out
+   `Client/` grant, which **reuses the same** literal per row across tenants on purpose for safe
+   rollback — that is deliberate reuse, not incrementing (see the feature doc).
+
+   One earlier migration (`Core/2026-05-08 … CronJobs_WorkerCleanup_insert`) used `UUID()` — that is
+   a known violation, not a precedent to copy. First applied correctly in
    `Core/2026-07-21b - Insert - SprintLockScheduled CronJob.sql`.
 7. **Guard every registration/seed insert with `NOT EXISTS` (or `INSERT IGNORE`).** Rows that
    register platform behavior — `ApiPayloadInterceptors`, `Core.RecordFields`/`CustomRecordFields`,
@@ -562,8 +575,9 @@ Wrap the existing-set subquery in a **derived table** (with `DISTINCT` or `LIMIT
 
 ```sql
 -- CORRECT — the derived table snapshots the "already present" set before any insert
+-- (uuid: inline RANDOM_BYTES() v4 expression, never UUID() — see rule #6 / the feature doc)
 INSERT INTO TranscriptPromptTerms (uuid, category, term, isActive, c_trueAiModelId)
-SELECT UUID(), t.category, t.term, t.isActive, m.mid
+SELECT LOWER(CONCAT(HEX(RANDOM_BYTES(4)), '-', …)), t.category, t.term, t.isActive, m.mid
 FROM <base rows> t
 CROSS JOIN <active model ids> m
 WHERE m.mid NOT IN (
@@ -591,6 +605,15 @@ tables that `_Model_*` classes map to.
 
 ## Change history
 
+- 2026-09-09 — **Two team-wide authoring changes (jcardinal).** (1) **UUIDs must be freshly, fully
+  random — never derived from another.** Sharpened rule #6: do not bump a digit / copy-and-tweak /
+  pattern uuid literals; generate each independently at random. Reaffirmed **never `UUID()` — not
+  even in bulk** (bulk uses the `RANDOM_BYTES()` v4 expression); fixed the doc's own
+  `TranscriptPromptTerms` example, which still used `UUID()`. The fan-out `Client/` same-literal
+  reuse is the one intended exception (deliberate reuse for safe rollback, not incrementing).
+  (2) **One file per realm per turn** — renamed/strengthened the consolidation section: prefer a
+  single `.sql` file per realm (`Core`, `Client`, `Client_<Name>`, …) per turn; a strong preference,
+  not absolute; different realms still split (never mix two realms in one file). (jcardinal)
 - 2026-08-18 - Added **rule 10**: a fan-out `Client/` file must never reference a
   `customRecordFieldId` or a client-specific label, because `CustomRecordFields` ids are per-client
   `AUTO_INCREMENT` - the same numeric id names a different field in every tenant and mis-wires

package/knowledge/2.0/apps/dbchanges2/features/rerunnable-additive-inserts.md

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: feature
 status: active
-updated: 2026-09-08
+updated: 2026-09-09
 owners: [bala, kyalamarthi, apeterson, ajean, jcardinal]
 files:
   - dbchanges2/Client_Compass/2026-08-26a - CompassCreativeStudioPersona.sql
@@ -52,6 +52,14 @@ and `SUBSTRING('89ab', …)` picks the variant nibble. Verified working on prod
 that is *not* v4-shaped (older migrations concatenated `RANDOM_BYTES` without the version/variant
 nibbles). They are fine and must not be "fixed" — but do not use them as the template for new SQL.
 
+**⚠ When a file needs several hardcoded literals, generate each one independently at random — never
+derive one from another.** Do not paste one uuid and bump a digit (`…-0001`, `…-0002`, …) or
+copy-and-tweak to make the next. Patterned uuids are guessable and undercut the uniqueness the column
+exists to give. Generate each literal fresh from a real v4 generator. (The **one** intended exception
+is the fan-out rule just below, which reuses the **same** literal per row across tenants on purpose —
+deliberate reuse for a safe rollback, not incrementing.) `UUID()` is never allowed, in single-row or
+bulk inserts — bulk uses the `RANDOM_BYTES()` expression above.
+
 ### ⚠ In a FAN-OUT grant migration, use HARDCODED uuid literals — generated uuids make rollback unsafe
 
 The generator above is right for a normal additive insert. It is **wrong for a `Client/` fan-out
@@ -310,6 +318,11 @@ concluding a migration is production-safe.
   [FIELD_SQL calculated fields](../../_underscore/features/calculated-sql-fields.md).
 
 ## Change history
+- 2026-09-09 — Added the rule that **every hardcoded uuid literal must be generated independently at
+  random** — never bump a digit / copy-and-tweak / pattern them (guessable, defeats uniqueness); the
+  fan-out same-literal reuse is the one intended exception. Restated **never `UUID()`, single-row or
+  bulk** (bulk uses the `RANDOM_BYTES()` v4 expression). Team-wide authoring change alongside
+  architecture rule #6. (jcardinal)
 - 2026-09-08 — Extended the **`Core.CronJobs` registration** shape with three mechanics confirmed on
   `Core/2026-09-08e - Insert QcBatch CronJob.sql`: reference `CronJobs` **unqualified** in a `Core/`
   file (a `Core.` prefix is a cross-database reference that breaks in prod); **always set

package/package.json

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