toga-ai 1.0.465 → 1.0.466

package/knowledge/1.0/apps/tools/features/talos-kb-documents-admin.md

@@ -6,7 +6,7 @@ project: Tools
 client: shared
 type: feature
 status: active
-updated: 2026-07-16
+updated: 2026-07-28
 owners: [jcardinal]
 files:
   - tools/mvc/talos/kb-documents/get.php
@@ -108,7 +108,7 @@ Vectors** (the canonical design — see the architecture note below), and the fl
 3. **S3 Vectors store** — create a dedicated vector bucket + index via
    `App_Talos_Bedrock::createVectorStore()`, capturing the authoritative **`indexArn`**.
 4. **VECTOR KB** — `createKnowledgeBase($bedrock, $slug, $indexArn)` (VECTOR + `S3_VECTORS`
-   storage).
+   storage), **tagged** with the mandatory `App_Talos_Bedrock::KB_TAGS` pair (see below).
 5. **wait for `ACTIVE`** (`waitForKnowledgeBaseActive`).
 6. **S3 data source** — plain `S3` connector + `BEDROCK_DATA_AUTOMATION` parsing.
 7. **`Team.KnowledgeBases`** (`db_team`, Team MySQL cluster).
@@ -163,8 +163,16 @@ orphaned KB).
   float32, euclidean), then **polls `getIndex` for the authoritative index ARN** with a short
   `NotFound` retry; returns an actionable error on `Conflict`/`AlreadyExists` from an orphaned
   prior attempt.
+- **`KB_TAGS`** — the **mandatory** tag pair stamped on every new KB:
+  `['tenant' => 'True', 'model_role' => 'knowledge_base']`. Passed as the top-level `'tags'`
+  parameter of `CreateKnowledgeBase`. Casing is load-bearing: capital-T **`True`**, snake_case
+  **`model_role`**. Verified against the live `development-team-toga-desk` KB (`ZOLCCQZZL1`) with
+  `aws bedrock-agent list-tags-for-resource --resource-arn
+  arn:aws:bedrock:us-east-1:654654170868:knowledge-base/ZOLCCQZZL1 --region us-east-1`. These tags
+  drive **cost allocation and model-inventory reporting** in the togaiq account — an untagged KB is
+  invisible to those reports.
 - `createKnowledgeBase($bedrock, string $slug, string $indexArn)` — creates the VECTOR KB with
-  `S3_VECTORS` storage (signature now takes the index ARN).
+  `S3_VECTORS` storage (signature takes the index ARN) and applies `KB_TAGS`.
 - `waitForKnowledgeBaseActive()` polls `getKnowledgeBase` every `WAIT_INTERVAL_SECONDS` (3s)
   up to **`WAIT_MAX_SECONDS` = 300**. Exits immediately on `ACTIVE`/`FAILED`. 300s sits well
   under the 900s Apache/PHP ceiling.
@@ -191,6 +199,12 @@ orphaned KB).
   `iam:PassRole` on the shared role. Its bedrock create actions were already covered by
   `AmazonBedrockFullAccess` and S3 by `AmazonS3FullAccess`. **`s3vectors` is a SEPARATE service
   NOT covered by `AmazonBedrockFullAccess`** — that was the real missing grant.
+- **⚠ `bedrock:TagResource` (new, NOT yet verified as granted).** AWS authorizes
+  **tagging-on-create separately from the create action itself**. Now that `createKnowledgeBase()`
+  sends `tags`, the `bedrock-model-accessor` user must also hold **`bedrock:TagResource`** on the
+  knowledge-base resource, or `CreateKnowledgeBase` fails with `AccessDeniedException` — even
+  though the *identical call without tags* would have succeeded. Confirm this grant with devops
+  **before the next real KB creation** (see the orphaned-vector-bucket gotcha).
 
 ## Helpers
 
@@ -277,6 +291,17 @@ orphaned KB).
   `Conflict`/`AlreadyExists` on the vector bucket (surfaced as an actionable error) or creates a
   **duplicate** Bedrock KB (Bedrock allows same-name KBs with new ids). After a failed create:
   delete the orphaned vector store + KB and re-run clean, or finish the DB rows manually.
+- **Tagging on create needs its own IAM permission, and failing it orphans a vector bucket.**
+  `bedrock:TagResource` is authorized separately from `CreateKnowledgeBase`. Because the KB is
+  created at **step 4 — after** the S3 Vectors bucket + index (step 3) — a missing `TagResource`
+  grant aborts the flow leaving an **orphaned `bedrock-knowledge-base-{slug}` vector bucket with
+  no KB and no DB rows**, and retrying the same slug then hits `Conflict`/`AlreadyExists`. If a
+  create suddenly starts failing `AccessDeniedException` right after the vector store succeeds,
+  suspect this permission first — not the tag values.
+- **Only the Bedrock KB is tagged — the per-KB S3 Vectors bucket is deliberately NOT.** Scope
+  decision (2026-07-28): `createVectorStore()` leaves `bedrock-knowledge-base-{slug}` untagged.
+  Known gap: the vector bucket is a **separate billable resource**, so vector-storage cost is not
+  attributed by `tenant`/`model_role`. Revisit if cost reporting needs it.
 - **Two prior KBs use the WRONG (fully-MANAGED) type.** `development-team-craftex` and
   `development-team-toga-desk` were created by the earlier MANAGED code and were **intentionally
   left as-is** (this session's scope was code-only). They should be **recreated later** to match
@@ -296,6 +321,14 @@ orphaned KB).
 
 ## Change history
 
+- 2026-07-28 — **Every new Bedrock KB is now tagged** `tenant=True` + `model_role=knowledge_base`
+  via the new `App_Talos_Bedrock::KB_TAGS` constant, passed as the `tags` parameter of
+  `CreateKnowledgeBase` (required for togaiq cost allocation / model-inventory reporting; values
+  and casing verified against the live `toga-desk` KB `ZOLCCQZZL1`). **New IAM prerequisite:**
+  tagging-on-create needs `bedrock:TagResource` on the `bedrock-model-accessor` user — *not yet
+  verified as granted*; without it `CreateKnowledgeBase` returns `AccessDeniedException` and, with
+  no rollback, orphans the already-created S3 Vectors bucket. Scoped decision: the per-KB S3
+  Vectors bucket is left **untagged**, so vector-storage cost is not attributed. (jcardinal)
 - 2026-07-16 — **Corrected the KB-create architecture from MANAGED to VECTOR + S3 Vectors**
   (the canonical design, from `development-team-dunn`; the earlier code was modeled on the WRONG
   `craftex`/MANAGED KB). Rewrote `App_Talos_Bedrock`: KB is now `VECTOR` + `S3_VECTORS` storage;

package/package.json

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