toga-ai 1.0.689 → 1.0.690

package/knowledge/2.0/apps/talos-backend/INDEX.md

@@ -0,0 +1,5 @@
+# talos-backend (TOGa IQ Backend) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Onboarding a TOGa Supply client to TOGa IQ Backend](workflows/toga-supply-client-onboarding.md) | The TOGa Supply AI launch is one cross-system workflow with two deliberately separate data planes: 1. | talos-backend/docs/toga-supply-client-onboarding-runbook.md, talos-backend/docs/tenant-assistant-onboarding.md, talos-backend/deployments/tenants/compass-usa/manifest.json, talos-backend/deployments/tenants/health-and-hospitals/manifest.json, talos-backend/scripts/onboard_tenant_assistant.py, talos-backend/scripts/update_langfuse_project_registry.py, talos-backend/mcp-servers/toga-platform-mcp/ |

package/knowledge/2.0/apps/talos-backend/workflows/toga-supply-client-onboarding.md

@@ -0,0 +1,297 @@
+---
+title: Onboarding a TOGa Supply client to TOGa IQ Backend
+framework: "2.0"
+repo: talos-backend
+project: TOGa IQ Backend
+client: shared
+type: workflow
+status: active
+updated: 2026-08-28
+owners: [akhokhani]
+files:
+  - talos-backend/docs/toga-supply-client-onboarding-runbook.md
+  - talos-backend/docs/tenant-assistant-onboarding.md
+  - talos-backend/deployments/tenants/compass-usa/manifest.json
+  - talos-backend/deployments/tenants/health-and-hospitals/manifest.json
+  - talos-backend/scripts/onboard_tenant_assistant.py
+  - talos-backend/scripts/update_langfuse_project_registry.py
+  - talos-backend/mcp-servers/toga-platform-mcp/
+related:
+  - ../../api2/features/record-scripts.md
+  - ../../toga2-supply/workflows/client-host-scoping.md
+  - ../../talos/features/observability.md
+  - ../../talos/features/mcp-servers.md
+  - ../../../../clients/compass-usa/profile.md
+  - ../../../../clients/nychh/profile.md
+---
+
+## Summary
+
+The TOGa Supply AI launch is one cross-system workflow with two deliberately
+separate data planes:
+
+1. **TOGaHub/api2 MySQL** owns the user, persona, AI-model grant, record-script
+   ACL, Supply records, and API2 business authorization. Talos does not use
+   these MySQL tables as its application database.
+2. **TOGa IQ Backend PostgreSQL** owns tenant routing, assistant configuration,
+   BLP, MCP assignments, threads, runs, checkpoints, and observability context.
+
+At authentication time Talos sends the current bearer and exact Supply origin
+to `GET /v2/users/me`. The response proves the client identity and supplies the
+active persona-linked AI-model slugs. Talos admits the `toga-supply` assistant
+only when that response contains an active `toga-supply` model. During a Supply
+question, the shared `toga-platform` MCP forwards the same request-scoped bearer
+to API2, whose record/field/script ACLs remain authoritative for business data.
+
+The full executable SQL, curls, verification checklist, rollback procedure, and
+OneUptime agent prompt live in
+`talos-backend/docs/toga-supply-client-onboarding-runbook.md`. This knowledge
+entry records the durable boundaries and ordering that future operators must not
+lose.
+
+## Identity and naming contract
+
+Do not collapse these values into one slug:
+
+| Value | Authority | Example: NYCHH |
+|---|---|---|
+| TOGaHub client schema | API2 client database | `Client_Nychh` |
+| canonical Talos org ID | JWT `id.client.slug` | `Nychh` |
+| external organization identity | `/users/me` `audience.client` | `NYC Health + Hospitals` |
+| Talos physical database | onboarding manifest | `tenant_nychh` |
+
+Talos PostgreSQL databases always use `tenant_<normalized_org_id>`. A name such
+as `iweb_nychh` is invalid for this deployment contract even if `iweb` is used
+elsewhere in the customer's legacy stack.
+
+Working reference mappings:
+
+- Compass USA: `Compass_Usa` / `Compass Group` / `tenant_compass_usa`.
+- NYC Health & Hospitals: `Nychh` / `NYC Health + Hospitals` / `tenant_nychh`.
+
+Tenant resolution is exact and case-sensitive. Never add fuzzy matching or
+client-name branches in Talos runtime code to compensate for a wrong control-
+plane registration.
+
+## Ordered onboarding workflow
+
+### 1. Capture identity from a real beta login
+
+Log in to the intended TOGaHub beta host with the client's exact Supply
+`Origin`, then call `/v2/users/me` with the issued bearer. Record only non-secret
+identity fields: client UUID, JWT client slug, `audience.client`, user UUID,
+origin, and referer.
+
+Stop if `/users/me` is not 200/success or resolves a different client. Do not
+begin Talos provisioning with a guessed org ID.
+
+### 2. Enable `/users/me` in API2 MySQL
+
+The global script definition is in the target environment's
+`Core.RecordScripts`; the role grant is in the client database's
+`AclRecordScripts`.
+
+**`Core.RecordScripts.id` is not stable between environments.** The NYCHH
+onboarding observed ID `21` for `/users/me`, but operators must query the target
+Core database and verify route/method/record before using that number. This is
+different from `Core.Records.id` and `Core.RecordFields.id`, which are team-
+maintained platform constants.
+
+Production physically separates Core and `Client_*` onto different clusters.
+A client migration cannot query `Core.RecordScripts` at runtime. The operator
+must discover the script ID on the Core connection, then apply the literal grant
+on the client connection. A stale numeric grant inserts successfully but API2
+rejects the request at runtime.
+
+Resolve the Base role by name in each client database; do not assume its ID from
+another client. Grant scripted access in `AclRecordScripts`. Do not add ordinary
+record CREATE permissions to repair a scripted API 403: scripted calls bypass
+the CRUD record-permission path.
+
+### 3. Create the TOGa Supply model/persona chain in client MySQL
+
+Inside the intended `Client_<Name>` database, in one reviewed transaction:
+
+1. idempotently upsert active `AiModels.slug = 'toga-supply'`;
+2. idempotently create persona `All`;
+3. link the intended active users through `Users_Personas`;
+4. link `All` through `Personas_AiModels` to `toga-supply`;
+5. grant Base-role reads for the Personas, Users-Personas, AI Models, and
+   Personas-AI Models records;
+6. scope AI-model record reads to the TOGa Supply app where required; and
+7. grant read-only field permissions for every field needed by the nested
+   `/users/me` response.
+
+NYCHH observed record IDs 40 (Personas), 201 (Users-Personas), 227 (AI Models),
+and 228 (Personas-AI Models), with Base role 1 and Supply app 1. Verify every
+target value before mutation. In particular, a record ID and record-field ID
+are different namespaces even when their integers happen to match.
+
+After commit, issue a new bearer and require:
+
+```text
+data.users.me.userPersonas[*].persona.personaAiModels[*].aiModel
+  slug       = toga-supply
+  isActive   = true
+```
+
+The API2/MySQL phase ends here. Talos never reads these MySQL tables directly
+for authentication; `/users/me` is the trust boundary.
+
+### 4. Build the Talos deployment manifest
+
+Copy the current declarative Supply tenant directory and replace every client-
+specific value in `manifest.json`, `persona.txt`, and `toga-supply.blp`.
+
+Required invariants:
+
+- database name `tenant_<normalized_org_id>`;
+- assistant, persona, and ACL slug `toga-supply`;
+- graph `deep_agent`;
+- exact native tool list `[query_business_logic]`;
+- one required shared MCP, slug `toga-platform`;
+- MCP transport `streamable_http` and auth type `user_bearer`;
+- read-only customer persona and Supply BLP;
+- no tenant name in MCP source code or tool-selection logic;
+- approved primary and embedding Bedrock model profiles.
+
+Never store a bearer or service secret in the manifest.
+
+### 5. Dry-run and apply the Talos reconciler
+
+Run `scripts/onboard_tenant_assistant.py` without `--apply`, using the target
+environment file. Review the exact AWS account, org ID, physical database name,
+assistant, model, and profiles. Then repeat with `--apply --confirm-org` where
+the confirmation exactly equals the manifest org ID.
+
+The reconciler idempotently:
+
+- verifies STS account identity;
+- creates/reuses tagged Bedrock application inference profiles;
+- creates the isolated PostgreSQL database;
+- installs extensions and migrates to Alembic head;
+- seeds normalized base infrastructure;
+- writes `organizations` and `tenant_databases` in the control plane;
+- reconciles the deterministic assistant, version, config, persona, model
+  preset, BLP, exact tool boundary, and shared MCP assignment; and
+- runs a bounded Bedrock inference smoke test.
+
+Do not manually create control-plane rows during a normal onboarding. Never
+print `tenant_databases.database_url`; it may carry credentials.
+
+### 6. Create tenant-scoped Langfuse observability
+
+Sign in at `langfuse.togaiq.com` with the approved development-team account from
+1Password. Select the existing organization; **do not create another
+organization**. Create `<Client Name> - TOGa Supply`, generate API keys, and
+store the project ID and keys directly in 1Password.
+
+Run `scripts/update_langfuse_project_registry.py`. It receives keys through
+hidden prompts, verifies them against the exact project ID, preserves other
+tenants, and atomically updates `LANGFUSE_PROJECTS_JSON`. Every tenant/
+environment needs an explicit entry; there is no implicit fallback. Different
+tenants must never share a Langfuse project.
+
+Restart API and worker processes after changing environment registry data.
+Verify the first trace has exactly the intended canonical org/environment tags
+and opens in the intended project.
+
+### 7. Configure OneUptime
+
+Use the repository's `docs/oneuptime-integration-playbook.md` and existing
+tenant-aware reporter. Find or create the monitor idempotently, persist the ID
+in `organizations.oneuptime_monitor_id`, and use `/ready` as the critical Talos
+contract. Preserve the consecutive-failure threshold; one transient failure
+must not immediately publish degradation.
+
+Beta must never report into production OneUptime resources. API keys remain in
+the approved secret facility. Verify by reading the monitor back and observing
+a fresh timestamp/status, not merely by receiving HTTP 200 from a heartbeat.
+
+### 8. Deploy one clean worker generation
+
+Rebuild/restart the target environment and confirm only the intended API and
+worker generation consumes its Redis queue. During Compass/NYCHH validation,
+six orphaned reload workers running different revisions made failures appear
+tenant-specific. Requests randomly reached stale code and returned `MCP action
+is no longer available`.
+
+Resolve exact process IDs before stopping stale processes; never use a broad
+process-name kill on a shared host.
+
+### 9. Run the streaming release suite
+
+Use a fresh bearer and the exact client Origin/Referer:
+
+1. `POST /threads` and retain the returned thread ID;
+2. `POST /threads/{thread_id}/runs/stream` with the tenant assistant ID;
+3. send stream modes `messages`, `updates`, and `custom` with
+   `on_disconnect = continue`;
+4. require an SSE `end` event, persisted successful run, and successful MCP
+   tool messages.
+
+Ask at least these five questions:
+
+1. five most recent sales orders;
+2. five most recent pending-fulfillment orders;
+3. five most recent billed orders;
+4. five most recent fulfilled orders; and
+5. most recent order detail with lines, fulfillment, and approval information.
+
+When the MCP serves multiple clients, execute all five concurrently for two
+clients. Verify separate tenant databases, business records, trusted Supply
+URLs, and Langfuse projects, with no cross-client data. API2 capabilities may
+legitimately differ; missing/hidden data must be reported as partial or
+unavailable rather than replaced with another client's behavior.
+
+## Release gates
+
+- Beta passes before production begins.
+- `/users/me` proves the exact client and active `toga-supply` grant.
+- Talos control plane maps the exact org to `tenant_<normalized_org_id>`.
+- Bedrock profiles are active, tagged, and reused idempotently.
+- The assistant has only its declared BLP/tool/MCP capabilities.
+- MCP auth is required `user_bearer`; no bearer is persisted.
+- Langfuse trace and OneUptime monitor are tenant/environment correct.
+- Five streaming questions pass, including concurrent cross-tenant isolation.
+- The change record contains non-secret run IDs, trace URLs, timestamps, commit
+  SHA, operator, and reviewer.
+
+## Rollback
+
+Prefer suspension and configuration rollback over deletion:
+
+1. suspend the Talos organization or stop client traffic;
+2. restore the previous deployment and Langfuse registry;
+3. disable the incorrect OneUptime mapping/reporter;
+4. remove only the exact API2 ACL/persona/model links introduced by the change,
+   using captured before/after rows; and
+5. preserve the tenant PostgreSQL database and historical traces for audit.
+
+Every manual database operation must record environment, target database, query
+checksum, row counts before/after, transaction result, UTC time, operator, and
+reviewer. Rotate any credential exposed in chat or logs.
+
+## Gotchas / known issues
+
+- `Core.RecordScripts.id` drifts; `/users/me = 21` is evidence from one
+  environment, not a constant.
+- Core and client MySQL databases share a host in non-prod but are physically
+  split in production. A cross-database query that worked in beta can be
+  impossible in production.
+- Talos PostgreSQL and API2 MySQL are separate. Fixing a Talos tenant row cannot
+  repair a missing API2 script/persona ACL, and vice versa.
+- A fresh HTTP 200 run does not prove tool success; inspect SSE termination and
+  persisted tool messages.
+- A cached graph must authorize MCP actions from the live per-run runtime
+  context. A released/stale run reference makes a newly discovered action fail.
+- Multiple worker generations on one Redis queue produce revision-dependent,
+  seemingly client-dependent failures.
+
+## Change history
+
+- 2026-08-28 — Captured the Compass USA and NYC Health & Hospitals TOGa Supply
+  onboarding workflow, including the API2-MySQL versus Talos-PostgreSQL
+  boundary, manifest-driven provisioning, shared user-bearer MCP, Bedrock,
+  tenant-scoped Langfuse, OneUptime, concurrent streaming validation, and the
+  stale-worker failure mode. (akhokhani)

package/knowledge/INDEX.md

@@ -27,6 +27,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-view** (TOGa View Frontend) — 12 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 8 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
+- **talos-backend** (TOGa IQ Backend) — 1 doc(s) → [2.0/apps/talos-backend/INDEX.md](2.0/apps/talos-backend/INDEX.md)
 - **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 - **ai-bdr** (AI-BDR) — 13 doc(s) → [2.0/apps/ai-bdr/INDEX.md](2.0/apps/ai-bdr/INDEX.md)
 - **toga2-commerce** (TOGa Commerce) — 20 doc(s) → [2.0/apps/toga2-commerce/INDEX.md](2.0/apps/toga2-commerce/INDEX.md)

package/knowledge/clients/compass-usa/profile.md

@@ -14,12 +14,13 @@ apps:
   - dbchanges2
   - library
   - test
+  - talos-backend
 project: _Underscore
 client: compass-usa
 type: profile
 status: active
-updated: 2026-08-27
-owners: [jcardinal, bala, tcox, apeterson, dfranks]
+updated: 2026-08-28
+owners: [jcardinal, bala, tcox, apeterson, dfranks, akhokhani]
 files: []
 related:
   - ../../2.0/apps/_underscore/features/sales-order-po-number-sourcing.md

package/knowledge/clients/nychh/profile.md

@@ -11,12 +11,13 @@ apps:
   - worker2
   - worker
   - library
+  - talos-backend
 project: _Underscore
 client: nychh
 type: profile
 status: active
 updated: 2026-08-28
-owners: ["jcardinal", "apeterson", "bala"]
+owners: ["jcardinal", "apeterson", "bala", "akhokhani"]
 files:
   - dbchanges2/Client_Nychh/2026-08-18 - InventoryUnitsItemColumns.sql
   - dbchanges2/Client_Nychh/2026-08-24 - FixInventoryGroupingsUnitsTopologyOverrideIds.sql

package/knowledge/registry.json

@@ -147,6 +147,14 @@
     "role": "app",
     "dependsOn": []
   },
+  {
+    "repo": "talos-backend",
+    "project": "TOGa IQ Backend",
+    "framework": "2.0",
+    "role": "app",
+    "dependsOn": [],
+    "language": "python"
+  },
   {
     "repo": "test",
     "project": "Test",
@@ -243,4 +251,4 @@
     "role": "app",
     "dependsOn": []
   }
-]
+]

package/package.json

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