toga-ai 1.0.686 → 1.0.687

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

@@ -5,13 +5,15 @@ project: _Underscore
 client: shared
 type: standard
 status: active
-updated: 2026-07-29
-owners: [jcardinal, ajean]
+updated: 2026-08-28
+owners: [jcardinal, ajean, apeterson]
 files: []
 related:
   - ../apps/_underscore/architecture.md
   - ../apps/worker2/architecture.md
   - ../apps/api2/architecture.md
+  - ../apps/dbchanges2/architecture.md
+  - ../apps/dbchanges2/features/surface-layer-schema.md
 ---
 
 # Framework 2.0 (_underscore) Rules
@@ -137,6 +139,14 @@ 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.**
 
+**Verified empirically in production, 2026-08-28:** the Core reader exposes only `Core`,
+`Forecast`, `Forecast_Archive` and `Team`; the client reader exposes only `Client_*`. This is a
+**physical** boundary, not a permissions setting to be widened — a `Client_*` file naming `Core.*`
+does not fail an authorization check, it cannot resolve at all. Corollary for **reviewers**: "it
+ran locally" and "it ran on beta" are both worthless as evidence of production-runnability, because
+every non-prod environment is all-in-one. The only meaningful checks are the hook, or a
+connection-scoped run against a user granted just the one database.
+
 ### `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
@@ -161,6 +171,58 @@ This is also what makes the `dbchanges2` isolation rule above workable: a `Clien
 never has to read `Core` to resolve a `recordFieldId`. Full detail and examples:
 `2.0/apps/dbchanges2/architecture.md` → *`Core.Records` / `Core.RecordFields`*.
 
+#### ⚠ Bounded exemption — the Surface tables
+
+**`Core.Surfaces`, `Core.SurfaceElements` and `Core.Messages` also carry team-reserved literal `id`
+blocks.** This is a **specific exemption for the Surface layer, not a general precedent** — do not
+cite it to justify hardcoding ids for any other feature. Reserving them was forced by the cluster
+split above: `SurfaceOverrides` lives in the **Client** DB while the elements it overrides live in
+**Core**, so a `Client_*` override file must reference a Core id it is forbidden to look up at run
+time. Without a stable literal there is nothing for that file to hardcode.
+
+When seeding into these three tables:
+
+- **Verify the block is actually free** — run both `SELECT MAX(id)` *and*
+  `SELECT id FROM … WHERE id BETWEEN <lo> AND <hi>`. Confirm whether a number you were handed means
+  **"next free"** or **"highest used"**; reading one as the other has already caused a live
+  collision.
+- **Use a plain `INSERT`, never `INSERT IGNORE`.** `IGNORE` turns a primary-key collision — the one
+  error that must halt the migration — into a silent mis-wiring. Put idempotency in a `NOT EXISTS`
+  guard on a *semantic* key, or in a paired `UPDATE`.
+
+Blocks in use, the authoring house style, and the collision incident:
+[surface-layer-schema](../apps/dbchanges2/features/surface-layer-schema.md).
+
+### A committed migration records INTENT, not deployed state
+
+**Never infer what an environment contains by reading `dbchanges2`. Query the environment.**
+
+There is no automated executor. A human applies each `.sql` per environment, and where the
+isolation rule bites — a client-side file that needs a Core id — the operator resolves the id
+against the target's Core and **hand-writes the literal statement at run time**. Those
+transpositions have historically **not been written back to the repo**. The consequence is
+permanent and structural, not a backlog item:
+
+- A file in the repo may never have run anywhere.
+- A file that *did* run may have run in an edited form that exists nowhere in version control.
+- Deployed rows can therefore have no committed file that would reproduce them.
+
+So before authoring anything whose correctness depends on current state — an override, a
+correction, an `INSERT … NOT EXISTS` guard, an id block — **establish that state with read-only
+`SELECT`s against the target environment's read replicas.** Connect using the `readhost` keys of
+the `[database]` and `[databaseClient]` groups in `api2/Config/production.ini`; never copy
+credential values into a doc, a ticket, a commit or a chat message.
+
+**The hook cannot save you here.** `dbchanges2-cluster-isolation.js` is a static check on the text
+of a file, so it catches a cross-database *reference* at authoring time. It cannot know whether a
+file ever ran, ran in edited form, or matches the target environment. Cluster isolation is
+mechanically enforced; state verification is **on you**.
+
+Worked examples of both failure modes — a file unrunnable in prod, and prod rows with no
+corresponding committed file — are in
+[surface-layer-schema](../apps/dbchanges2/features/surface-layer-schema.md) and
+[surface-resolver](../apps/_underscore/features/surface-resolver.md).
+
 ## 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):
@@ -230,6 +292,22 @@ and not how the convention works. Use a non-`c_` column when you *do* want the f
 ACL-governed field treatment.
 
 ## Change history
+- 2026-08-28 — Extended § Schema migrations with the production-state rules. Recorded that cluster
+  isolation is **physical** (verified: the prod Core reader exposes only Core/Forecast/
+  Forecast_Archive/Team, the client reader only `Client_*`), so a cross-database reference cannot
+  resolve rather than merely being denied — and that neither a local nor a beta run is evidence of
+  prod-runnability, since every non-prod environment is all-in-one. Added a **bounded exemption**
+  to the hardcoded-id rule for the Surface tables only (`Core.Surfaces`/`SurfaceElements`/
+  `Messages` carry reserved literal blocks because `Client_*` override files must reference Core
+  ids across the cluster split and cannot resolve them at run time) — **explicitly not a general
+  precedent**; the platform rule that only `Core.Records`/`Core.RecordFields` have team-maintained
+  ids is unchanged. Attached the seeding safeguards to that exemption (verify the block is free
+  with `MAX(id)` *and* a `BETWEEN` check; "next free" vs "highest used"; plain `INSERT`, never
+  `INSERT IGNORE`). New subsection: **a committed migration records intent, not deployed state** —
+  there is no automated executor, operators hand-transpose Core ids at run time and historically
+  did not write them back, so current state must be established with read-only queries against the
+  target environment, and the cluster-isolation hook catches cross-database references but
+  **cannot** catch state drift. (apeterson)
 - 2026-07-29 — Documented the `c_`-prefixed framework-dynamic column convention (schema-only,
   no model-class/RecordFields/ACL declaration), generalized from the transcript AI-model routing
   work. (ajean)

package/package.json

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