toga-ai 1.0.488 → 1.0.489

package/.claude/settings.json

@@ -41,6 +41,26 @@
             "timeout": 3000
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-cluster-isolation.js\"",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \".claude/hooks/toga/dbchanges2-record-ids.js\"",
+            "timeout": 3000
+          }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -6,7 +6,7 @@ project: Database Changes
 client: shared
 type: architecture
 status: active
-updated: 2026-07-29
+updated: 2026-07-31
 owners: [jcardinal, mhammontree, bala, ajean]
 files:
   - Core/
@@ -43,6 +43,9 @@ UI config) — **not just schema**; a schema-only blank produces non-functional
 `Archive_*`, `Logs*`, and `Cache` are on **separate production clusters**, so any
 `OtherDatabase.Table` reference is unrunnable in production even though it works locally
 (see *Database isolation* below; enforced by the `dbchanges2-cluster-isolation` hook).
+**`Core.Records` and `Core.RecordFields` are the only two tables platform-wide with
+team-maintained `id`s** — ask the developer for the next value before inserting (never
+`AUTO_INCREMENT`), and hardcode those `id`s wherever they are referenced, foreign keys included.
 
 ## File naming convention (the execution contract)
 
@@ -189,6 +192,61 @@ literals are stripped first, and table **aliases** (`rf.id`, `sibling.roleId`) a
 > is **not** subject to it. If the hook ever misfires on legitimate SQL, `DBCHANGES2_ISOLATION_DISABLED=1`
 > is an escape hatch **for false positives only** — never to land a cross-database query.
 
+## `Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the platform
+
+These **two tables, and only these two**, have **team-maintained primary keys**. Their `id`
+values are treated as **stable, platform-wide constants**: the team tracks the next available
+value **in the developer chat**, and every environment carries the same `id` for the same record
+/ field. Nothing else on the platform may have a hardcoded `id`.
+
+This is what makes the *Database isolation* rule above practical — it is the reason a
+`Client_<Tenant>` migration never needs to read `Core` to find a `recordFieldId`.
+
+### Inserting into them — ASK FIRST, never rely on AUTO_INCREMENT
+
+**When a change inserts into `Core.Records` or `Core.RecordFields`, stop and ask the developer
+for the next `id` value(s)**, then write them as explicit literals:
+
+```sql
+# Core/2026-07-31a - Add entitlements serviceAddressId field.sql
+# id values 4187, 4188 assigned by the team (developer chat) — do NOT let AUTO_INCREMENT pick.
+INSERT INTO RecordFields (id, uuid, recordId, `field`)
+VALUES (4188, '<pre-generated v4 uuid>', 219, 'serviceAddressId');
+```
+
+**Never omit `id` and let MySQL's `AUTO_INCREMENT` assign it.** The column's `AUTO_INCREMENT`
+definition still exists, but it is **not the source of truth** — allowing it to assign a value
+lets environments drift apart, and every hardcoded reference to that `id` (in other databases,
+in PHP, in other migrations) then points at the wrong row or nothing at all. There is no way to
+detect this from inside the migration; it simply produces silently wrong ACL/field wiring.
+
+Because the `id`s must be reserved by a human, **this cannot be guessed or derived** — asking is
+mandatory, not a courtesy. Record the assigned values in a comment at the top of the file so the
+next reader knows they were allocated, not invented.
+
+### Referencing them — hardcode the `id`, including foreign keys
+
+Anywhere a query references one of these rows — **and anywhere a foreign key points at them**
+(`recordId`, `recordFieldId`, and their equivalents) — **hardcode the numeric `id`**. Do not look
+it up:
+
+```sql
+# Client_Compass/2026-07-31a - Grant serviceAddress field write.sql
+# recordFieldId 4188 = Core.RecordFields entitlements.serviceAddressId (team-assigned constant)
+INSERT INTO AclFieldPermissions (uuid, recordFieldId, roleId, isWritable)
+VALUES ('<pre-generated v4 uuid>', 4188, 3, 1);
+```
+
+This applies equally to SQL embedded in PHP in `worker2` / `api2` / `_underscore` — a hardcoded
+`recordFieldId` is correct and preferred there too.
+
+> **Always comment what the number is.** A bare `4188` is unreadable and unverifiable six months
+> later. Name the record/field it refers to, as above.
+
+Note that the `uuid` on these rows is **also** stable and environment-consistent, so
+`WHERE uuid = '<literal>'` is a valid alternative when a readable key is preferred — but the
+`id` is the team-maintained one, and it is what foreign keys store.
+
 ## `_modules` — reusable, opt-in change-sets
 
 Some change-sets aren't applied to every client — only to clients that use a given **module**
@@ -295,6 +353,12 @@ its own header.)
    foreign ids with a hardcoded v4 UUID literal or an in-database slug/natural key, or split the
    work into one file per database folder. See *Database isolation* above — enforced by the
    `dbchanges2-cluster-isolation` hook.
+9. **Inserting into `Core.Records` or `Core.RecordFields`? ASK the developer for the next `id`.**
+   These are the **only two tables on the platform with team-maintained primary keys** (tracked in
+   the developer chat). Write the assigned `id` as an explicit literal — **never** let
+   `AUTO_INCREMENT` assign it. Conversely, **always hardcode** these `id`s where they are
+   referenced, including in foreign keys (`recordId`, `recordFieldId`) from other databases. See
+   *`Core.Records` / `Core.RecordFields`* above.
 
 ## Bulk data loads — batch, and stage large sets in a temp table
 
@@ -447,7 +511,16 @@ defined in `2.0/apps/_underscore/architecture.md`, and its change files create/a
 tables that `_Model_*` classes map to.
 
 ## Change history
-- 2026-07-29 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
+- 2026-07-31 — **Added *`Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the
+  platform* + rule #9.** These two tables are the **only** ones platform-wide whose `id` is a
+  team-maintained constant: the next available value is tracked **in the developer chat**, so a
+  migration inserting into them must **ask the developer for the `id`** and write it as an explicit
+  literal — `AUTO_INCREMENT` must never assign it (silent per-environment drift breaks every
+  hardcoded reference). Conversely these `id`s **should** be hardcoded wherever referenced,
+  including foreign keys (`recordId`, `recordFieldId`) from client databases and in PHP query
+  strings. This is what makes *Database isolation* workable — no client migration needs to read
+  `Core` to resolve a `recordFieldId`. Enforced by the `dbchanges2-record-ids` hook. (jcardinal)
+- 2026-07-31 — **Added *Database isolation — never query across databases* (HARD RULE) + rule #8.**
   A `dbchanges2` `.sql` file may only reference tables in the one database its folder targets, and
   must reference them unqualified; fan-out folders (`Client/`, `Logs_Client/`, `_modules/`) permit
   no database qualifier at all. Rationale: in production `Core`, `Client_<Tenant>`,

package/knowledge/2.0/standards/framework-rules.md

@@ -137,6 +137,30 @@ Enforced mechanically by the `PreToolUse` hook
 examples, and the approved rewrites: `2.0/apps/dbchanges2/architecture.md` → *Database
 isolation*. **Applies to `dbchanges2` only — the 1.0 `dbchanges` repo is exempt.**
 
+### `Core.Records` / `Core.RecordFields` — the only hardcoded `id`s on the platform
+
+**These two tables, and only these two, have team-maintained primary keys.** Their `id` values are
+**stable platform-wide constants**, identical in every environment, and the next available value is
+tracked by the team **in the developer chat**. No other table on the platform may have a hardcoded
+`id`.
+
+**Inserting into them — ask first.** When a change inserts a row into `Core.Records` or
+`Core.RecordFields`, **stop and ask the developer for the next `id`**, then write it as an explicit
+literal. **Never let `AUTO_INCREMENT` assign it** — the column is still defined that way, but it is
+not the source of truth, and a value it picks silently drifts between environments and invalidates
+every hardcoded reference to that row. The `id` must be reserved by a human, so it cannot be
+guessed or derived — asking is mandatory.
+
+**Referencing them — hardcode the `id`.** Anywhere these rows are referenced, and anywhere a
+**foreign key** points at them (`recordId`, `recordFieldId`, and equivalents), use the numeric
+literal rather than a lookup — including in SQL embedded in PHP in `worker2` / `api2` /
+`_underscore`. Always add a comment naming the record/field the number refers to; a bare `4188` is
+unverifiable later.
+
+This is also what makes the `dbchanges2` isolation rule above workable: a `Client_<Tenant>` change
+never has to read `Core` to resolve a `recordFieldId`. Full detail and examples:
+`2.0/apps/dbchanges2/architecture.md` → *`Core.Records` / `Core.RecordFields`*.
+
 ## Checking dependencies before touching shared code
 
 `dependsOn` in `knowledge/registry.json` means a repo extends or depends on another repo's classes. Before modifying a class in a dependency repo (e.g. `_underscore` core):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.488",
+  "version": "1.0.489",
   "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/scripts/hooks/dbchanges2-cluster-isolation.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * dbchanges2-cluster-isolation.js — DETERMINISTIC enforcement of the dbchanges2
+ * single-database rule.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * In production, the 2.0 databases are NOT on one server. Core, Client_<Tenant>,
+ * Archive_<Tenant>, Logs/Logs_<Tenant>, and Cache each live on an ENTIRELY
+ * SEPARATE cluster. A query that joins or sub-selects across those names is
+ * physically impossible in production — it cannot resolve the foreign schema.
+ *
+ * Locally and in non-prod every database happens to sit behind one endpoint, so a
+ * cross-database query runs fine there and the migration looks correct right up
+ * until it reaches production and dies. That silent local success is exactly why
+ * prose alone was not enough and this check is mechanical.
+ *
+ * THE RULE (hard, no exceptions)
+ * ------------------------------
+ * A .sql file in dbchanges2 may only reference tables in the ONE database its
+ * folder targets. References to that database are UNQUALIFIED. Any qualified
+ * `OtherDatabase.Table` reference is a violation — including in fan-out folders
+ * (Client/, Logs_Client/, _modules/), where the database name varies per tenant
+ * and therefore NOTHING may be qualified.
+ *
+ * Instead of reading a foreign database to resolve an id, use a hardcoded v4 UUID
+ * literal, a slug/natural key that exists inside the target database, or split the
+ * work into one file per database folder.
+ *
+ * SCOPE
+ * -----
+ * Only .sql files under a dbchanges2 checkout. The 1.0 `dbchanges` repo is
+ * explicitly NOT affected (its path is excluded). Every other write passes
+ * through untouched.
+ *
+ * Fail-open: any internal/parse error allows the write. A crashing guard must
+ * never brick editing.
+ *
+ * Escape hatch (false positives ONLY, not for writing cross-database SQL):
+ *   DBCHANGES2_ISOLATION_DISABLED=1
+ */
+
+const fs = require('fs');
+
+/* ---------- input: read stdin JSON (CC standard), fall back to env ---------- */
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.tool_name && process.env.CLAUDE_TOOL_NAME) data.tool_name = process.env.CLAUDE_TOOL_NAME;
+  if (!data.tool_input && process.env.CLAUDE_TOOL_INPUT) {
+    try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) {}
+  }
+  return data;
+}
+
+/* Known 2.0 database families. We match against this bounded set rather than a
+ * generic `x.y` pattern so ordinary table aliases (`rf.id`, `sibling.roleId`)
+ * never trip the check. */
+const DB_FAMILIES = ['Core', 'Client', 'Logs', 'Archive', 'Cache', 'Team'];
+
+/* Strip comments and string literals so a database name mentioned in prose or in
+ * a quoted value is not reported as a reference. Newlines are preserved so the
+ * reported line numbers still match the original file. */
+function stripNonCode(sql) {
+  const blanked = (m) => m.replace(/[^\n]/g, ' ');
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, blanked)   // /* block comments */
+    .replace(/(^|[^\w$])#[^\n]*/g, (m) => m[0] === '#' ? blanked(m) : m[0] + blanked(m.slice(1)))
+    .replace(/--[ \t][^\n]*/g, blanked)      // -- line comments (MySQL needs the space)
+    .replace(/'(?:\\.|''|[^'\\])*'/g, blanked) // 'string literals'
+    .replace(/"(?:\\.|""|[^"\\])*"/g, blanked); // "string literals"
+}
+
+/* Resolve which database a file targets from its folder, and whether that folder
+ * fans out across tenants (in which case no qualifier at all is permitted). */
+function resolveTarget(filePath) {
+  const norm = filePath.replace(/\\/g, '/');
+  const m = norm.match(/\/dbchanges2\/(.+)$/i);
+  if (!m) return null;
+  const rel = m[1];
+  const seg = rel.split('/')[0];
+  if (!seg || seg === rel) return null;               // file sits at repo root, no DB folder
+  if (/^_modules$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'a module change-set applied inside each opted-in client database' };
+  }
+  if (/^Client$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'fan-out to every Client_<Tenant> database' };
+  }
+  if (/^Logs_Client$/i.test(seg)) {
+    return { folder: seg, db: null, fanout: true, why: 'fan-out to every Logs_<Tenant> database' };
+  }
+  return { folder: seg, db: seg, fanout: false, why: 'the ' + seg + ' database only' };
+}
+
+/* Find every qualified reference to a known database family. */
+function findQualifiedRefs(sql) {
+  const code = stripNonCode(sql);
+  const names = DB_FAMILIES.join('|');
+  // `Core`.`Records` / Core.Records / Client_Aig.SalesOrders / USE Core
+  const re = new RegExp(
+    '`?\\b((?:' + names + ')(?:_[A-Za-z0-9]+)?)`?\\s*\\.\\s*`?[A-Za-z_][A-Za-z0-9_]*`?',
+    'g'
+  );
+  const useRe = new RegExp('\\bUSE\\s+`?((?:' + names + ')(?:_[A-Za-z0-9]+)?)`?', 'gi');
+  const found = [];
+  const push = (index, db, text) => {
+    const line = code.slice(0, index).split('\n').length;
+    found.push({ line, db, text: text.trim() });
+  };
+  let hit;
+  while ((hit = re.exec(code)) !== null) push(hit.index, hit[1], hit[0]);
+  while ((hit = useRe.exec(code)) !== null) push(hit.index, hit[1], hit[0]);
+  return found;
+}
+
+function main() {
+  if (process.env.DBCHANGES2_ISOLATION_DISABLED === '1') return;
+
+  const data = readPayload();
+  const tool = data.tool_name || '';
+  if (!/^(Write|Edit|MultiEdit)$/.test(tool)) return;
+
+  const input = data.tool_input || {};
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!/\.sql$/i.test(filePath)) return;
+
+  const target = resolveTarget(filePath);
+  if (!target) return;                                  // not a dbchanges2 .sql file (1.0 dbchanges excluded)
+  if (/\/HISTORIC\//i.test(filePath.replace(/\\/g, '/'))) return; // archive, never executed
+
+  // Gather the SQL this call would introduce, across all three tool shapes.
+  let sql = '';
+  if (typeof input.content === 'string') sql += input.content + '\n';
+  if (typeof input.new_string === 'string') sql += input.new_string + '\n';
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') sql += e.new_string + '\n';
+    }
+  }
+  if (!sql.trim()) return;
+
+  const violations = findQualifiedRefs(sql).filter((v) => {
+    if (target.fanout) return true;                     // no qualifier is ever valid here
+    return v.db.toLowerCase() !== target.db.toLowerCase();
+  });
+  if (!violations.length) return;
+
+  const lines = [];
+  lines.push('BLOCKED by dbchanges2 database isolation — this SQL reads across a database boundary.');
+  lines.push('');
+  lines.push('  File:   ' + filePath);
+  lines.push('  Folder: ' + target.folder + '/  → targets ' + target.why);
+  lines.push('');
+  lines.push('  Foreign reference' + (violations.length === 1 ? '' : 's') + ':');
+  for (const v of violations.slice(0, 20)) {
+    lines.push('    line ' + v.line + ': ' + v.text + '   ← ' + v.db + ' is a different database');
+  }
+  if (violations.length > 20) lines.push('    … and ' + (violations.length - 20) + ' more');
+  lines.push('');
+  lines.push('In PRODUCTION, Core / Client_<Tenant> / Archive_<Tenant> / Logs / Cache are on');
+  lines.push('ENTIRELY SEPARATE CLUSTERS. This query cannot resolve there — it only appears to');
+  lines.push('work locally and in non-prod, where every database shares one endpoint.');
+  lines.push('');
+  if (target.fanout) {
+    lines.push('This folder fans out across tenants, so the database name is not fixed:');
+    lines.push('reference tables UNQUALIFIED only — no database prefix at all.');
+  } else {
+    lines.push('Reference only tables in ' + target.db + ', and reference them UNQUALIFIED.');
+  }
+  lines.push('');
+  lines.push('Rewrite it without the cross-database read:');
+  lines.push('  • hardcode a pre-generated v4 UUID literal instead of SELECTing an id;');
+  lines.push('  • resolve rows by a slug / natural key that exists in the target database;');
+  lines.push('  • split the work into one file per database folder.');
+  lines.push('');
+  lines.push('See knowledge/2.0/apps/dbchanges2/architecture.md → "Database isolation".');
+  lines.push('(The 1.0 dbchanges repo is not subject to this rule.)');
+  // A PreToolUse deny (exit 2) surfaces its reason from STDERR — writing to stdout
+  // blocks the call but shows the agent nothing, so the explanation is lost.
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exit(2);
+}
+
+try { main(); } catch (e) { /* fail-open */ }

package/scripts/hooks/dbchanges2-record-ids.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * dbchanges2-record-ids.js — DETERMINISTIC enforcement of the team-maintained
+ * primary keys on Core.Records and Core.RecordFields.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * These two tables are the ONLY tables on the 2.0 platform whose `id` is a
+ * team-maintained constant. The next available value is tracked by the team in the
+ * developer chat, and the same row carries the same `id` in every environment —
+ * which is what lets every other database (and PHP query) hardcode `recordId` /
+ * `recordFieldId` instead of joining out to Core.
+ *
+ * If a migration omits `id` and lets MySQL's AUTO_INCREMENT assign one, the value
+ * differs per environment. Nothing fails at run time: the insert succeeds, and
+ * every hardcoded reference to that row silently points at the wrong record or at
+ * nothing. That is unrecoverable without a manual audit, so it has to be caught
+ * before the file is written.
+ *
+ * THE RULE
+ * --------
+ * An INSERT/REPLACE into Records or RecordFields must assign `id` explicitly.
+ * The developer must be ASKED for the value first — it cannot be derived, so this
+ * hook deliberately offers no way to satisfy it automatically.
+ *
+ * SCOPE
+ * -----
+ * .sql files under dbchanges2 whose folder targets Core (or which reference the
+ * tables Core-qualified). The 1.0 `dbchanges` repo is NOT affected. Sibling tables
+ * whose names merely END in RecordFields (CustomRecordFields, SectionRecordFields)
+ * are NOT covered — only the two exact tables.
+ *
+ * Fail-open on any internal error.
+ *
+ * Escape hatch (false positives ONLY): DBCHANGES2_RECORD_IDS_DISABLED=1
+ */
+
+const fs = require('fs');
+
+function readPayload() {
+  let raw = '';
+  try { raw = fs.readFileSync(0, 'utf8'); } catch (e) { /* no stdin */ }
+  let data = {};
+  if (raw && raw.trim()) {
+    try { data = JSON.parse(raw); } catch (e) { data = {}; }
+  }
+  if (!data.tool_name && process.env.CLAUDE_TOOL_NAME) data.tool_name = process.env.CLAUDE_TOOL_NAME;
+  if (!data.tool_input && process.env.CLAUDE_TOOL_INPUT) {
+    try { data.tool_input = JSON.parse(process.env.CLAUDE_TOOL_INPUT); } catch (e) {}
+  }
+  return data;
+}
+
+/* Blank out comments and string literals, preserving newlines so reported line
+ * numbers still line up with the original file. */
+function stripNonCode(sql) {
+  const blanked = (m) => m.replace(/[^\n]/g, ' ');
+  return sql
+    .replace(/\/\*[\s\S]*?\*\//g, blanked)
+    .replace(/(^|[^\w$])#[^\n]*/g, (m) => (m[0] === '#' ? blanked(m) : m[0] + blanked(m.slice(1))))
+    .replace(/--[ \t][^\n]*/g, blanked)
+    .replace(/'(?:\\.|''|[^'\\])*'/g, blanked)
+    .replace(/"(?:\\.|""|[^"\\])*"/g, blanked);
+}
+
+/* Which database does this file's folder target? */
+function targetDb(filePath) {
+  const norm = filePath.replace(/\\/g, '/');
+  const m = norm.match(/\/dbchanges2\/(.+)$/i);
+  if (!m) return null;
+  const seg = m[1].split('/')[0];
+  if (!seg || seg === m[1]) return null;
+  return seg;
+}
+
+/* Find INSERT/REPLACE statements targeting the two protected tables and report any
+ * that do not assign `id`. */
+function findUnassignedIds(sql) {
+  const code = stripNonCode(sql);
+  // (?<![A-Za-z0-9_`]) prevents matching CustomRecordFields / SectionRecordFields.
+  const re = /\b(?:INSERT(?:\s+IGNORE)?|REPLACE)\s+INTO\s+(?:`?Core`?\s*\.\s*)?`?(?<![A-Za-z0-9_])(Records|RecordFields)`?/gi;
+  const found = [];
+  let hit;
+  while ((hit = re.exec(code)) !== null) {
+    const table = hit[1];
+    const after = code.slice(hit.index + hit[0].length, hit.index + hit[0].length + 2000);
+    let assignsId = false;
+
+    // Form A: INSERT INTO t (col, col, ...) VALUES/SELECT ...
+    const colList = after.match(/^\s*\(([\s\S]*?)\)/);
+    if (colList) {
+      assignsId = colList[1]
+        .split(',')
+        .map((c) => c.trim().replace(/`/g, '').toLowerCase())
+        .includes('id');
+    } else {
+      // Form B: INSERT INTO t SET id = 4188, ...
+      const setClause = after.match(/^\s*SET\b([\s\S]*?)(?:;|$)/i);
+      if (setClause) assignsId = /(^|[\s,`])id\s*=/i.test(setClause[1]);
+      // Form C: INSERT INTO t SELECT ... — no column list, cannot verify; treat as
+      // unassigned so it gets a human look.
+    }
+
+    if (!assignsId) {
+      found.push({
+        line: code.slice(0, hit.index).split('\n').length,
+        table,
+        text: hit[0].replace(/\s+/g, ' ').trim(),
+      });
+    }
+  }
+  return found;
+}
+
+function main() {
+  if (process.env.DBCHANGES2_RECORD_IDS_DISABLED === '1') return;
+
+  const data = readPayload();
+  if (!/^(Write|Edit|MultiEdit)$/.test(data.tool_name || '')) return;
+
+  const input = data.tool_input || {};
+  const filePath = typeof input.file_path === 'string' ? input.file_path : '';
+  if (!/\.sql$/i.test(filePath)) return;
+
+  const db = targetDb(filePath);
+  if (!db) return;                                                 // not a dbchanges2 .sql file
+  if (/\/HISTORIC\//i.test(filePath.replace(/\\/g, '/'))) return;  // archive, never executed
+
+  let sql = '';
+  if (typeof input.content === 'string') sql += input.content + '\n';
+  if (typeof input.new_string === 'string') sql += input.new_string + '\n';
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') sql += e.new_string + '\n';
+    }
+  }
+  if (!sql.trim()) return;
+
+  // Records/RecordFields live in Core. Only inspect files that target Core, or that
+  // name the tables Core-qualified (the isolation hook handles the latter's legality).
+  if (!/^Core$/i.test(db) && !/`?Core`?\s*\.\s*`?(Records|RecordFields)\b/i.test(stripNonCode(sql))) return;
+
+  const violations = findUnassignedIds(sql);
+  if (!violations.length) return;
+
+  const out = [];
+  out.push('BLOCKED: insert into ' + violations.map((v) => v.table).filter((t, i, a) => a.indexOf(t) === i).join(' / ') +
+    ' without an explicit `id`.');
+  out.push('');
+  out.push('  File: ' + filePath);
+  for (const v of violations.slice(0, 20)) {
+    out.push('    line ' + v.line + ': ' + v.text + '   ← no `id` assigned');
+  }
+  if (violations.length > 20) out.push('    … and ' + (violations.length - 20) + ' more');
+  out.push('');
+  out.push('Core.Records and Core.RecordFields are the ONLY two tables on the platform with');
+  out.push('TEAM-MAINTAINED primary keys. The next available id is tracked by the team in the');
+  out.push('developer chat, and the same row must carry the same id in EVERY environment —');
+  out.push('that is what lets other databases hardcode recordId / recordFieldId instead of');
+  out.push('joining out to Core.');
+  out.push('');
+  out.push('Letting AUTO_INCREMENT assign the id fails silently: the insert succeeds, the id');
+  out.push('differs per environment, and every hardcoded reference to that row then points at');
+  out.push('the wrong record or at nothing.');
+  out.push('');
+  out.push('REQUIRED: ask the developer what the next id value(s) are, then write them as');
+  out.push('explicit literals and note in a comment that the team assigned them:');
+  out.push('');
+  out.push('    # id 4188 assigned by the team (developer chat)');
+  out.push('    INSERT INTO RecordFields (id, uuid, recordId, `field`)');
+  out.push("    VALUES (4188, '<v4 uuid literal>', 219, 'serviceAddressId');");
+  out.push('');
+  out.push('This value cannot be derived or guessed — you must ask.');
+  out.push('See knowledge/2.0/apps/dbchanges2/architecture.md → "Core.Records / Core.RecordFields".');
+  // exit 2 surfaces the reason from STDERR; stdout would block silently.
+  process.stderr.write(out.join('\n') + '\n');
+  process.exit(2);
+}
+
+try { main(); } catch (e) { /* fail-open */ }