@cubis/foundry 0.3.10 → 0.3.11

package/Ai Agent Workflow/skills/database-skills/skills/vitess/references/sharding-routing.md

@@ -1,5 +1,125 @@
-# Vitess Sharding and Routing
+# Vitess — Sharding and VSchema Design
 
-- Define shard key from access patterns and growth model.
-- Keep hot paths shard-local when possible.
-- Validate query routing behavior before launch.
+## Core concept
+
+The **VSchema** tells VTGate how to route queries. It defines which tables belong to which keyspace, which column determines shard placement (the **primary vindex**), and how tables relate across shards.
+
+## Shard routing types
+
+| Routing | Condition | Performance |
+| --- | --- | --- |
+| **Single-shard** | `WHERE` on primary vindex with `=` | Best |
+| **Multi-shard (targeted)** | `WHERE` with `IN` on primary vindex | Good |
+| **Scatter** | No primary vindex filter | Expensive — hits all shards |
+
+Always include the primary vindex column in `WHERE` clauses to avoid scatter queries.
+
+## Choosing a primary vindex column
+
+Pick the column that:
+1. Appears in your highest-QPS `WHERE` clauses.
+2. Enables join co-location — tables frequently joined should shard on the same column.
+3. Keeps transactions within a single shard.
+4. Has high cardinality for even distribution.
+5. Is immutable — changing it after insert requires a data migration.
+
+Common choices: `user_id`, `tenant_id`, `org_id`, `account_id`.
+
+## Vindex types
+
+| Type | When to use |
+| --- | --- |
+| `xxhash` | Any column type — most common |
+| `unicode_loose_xxhash` | Text columns needing case-insensitive hashing |
+| `binary_md5` | MD5-based alternative for any column type |
+
+## VSchema structure (sharded keyspace)
+
+```json
+{
+  "sharded": true,
+  "vindexes": {
+    "xxhash": { "type": "xxhash" }
+  },
+  "tables": {
+    "orders": {
+      "column_vindexes": [
+        { "column": "customer_id", "name": "xxhash" }
+      ],
+      "auto_increment": {
+        "column": "id",
+        "sequence": "unsharded_keyspace.orders_seq"
+      }
+    }
+  }
+}
+```
+
+## Sequences — replacing AUTO_INCREMENT
+
+Per-shard `AUTO_INCREMENT` produces duplicate IDs across shards. Use Vitess Sequences instead.
+
+1. Create in an **unsharded** keyspace:
+   ```sql
+   CREATE TABLE orders_seq (id BIGINT, next_id BIGINT, cache BIGINT, PRIMARY KEY(id))
+     COMMENT 'vitess_sequence';
+   INSERT INTO orders_seq (id, next_id, cache) VALUES (0, 1, 1000);
+   ```
+2. Register in unsharded VSchema: `{ "orders_seq": { "type": "sequence" } }`
+3. Link to sharded table via `auto_increment` in sharded VSchema (see above).
+
+Sequence gaps from caching/restarts are expected and harmless.
+
+## Lookup vindexes (secondary routing)
+
+Lookup vindexes let you route by non-primary-vindex columns without scatter. They are backed by a separate mapping table. **They are expensive** — avoid unless scatter on the column is genuinely a problem.
+
+```json
+"customer_email_lookup": {
+  "type": "consistent_lookup",
+  "params": {
+    "table": "product.customer_email_lookup",
+    "from": "email",
+    "to": "keyspace_id"
+  },
+  "owner": "customer"
+}
+```
+
+Use `consistent_lookup_unique` only when uniqueness across shards must be enforced at the DB level (this is a scalability anti-pattern — prefer app-level enforcement).
+
+## Discover existing VSchema
+
+```bash
+vtctldclient GetVSchema <keyspace>                     # full JSON
+vtctldclient GetVSchema <keyspace> | jq '.vindexes'   # just vindexes
+```
+
+```sql
+SHOW VSCHEMA TABLES;        -- tables known to VTGate
+SHOW VSCHEMA VINDEXES;      -- vindexes and types
+```
+
+## Troubleshoot scatter queries
+
+```sql
+VEXPLAIN PLAN SELECT * FROM orders WHERE customer_id = 42;
+-- Look for Route variant: EqualUnique (single-shard) vs Scatter (all shards)
+
+VEXPLAIN ALL SELECT ...;    -- includes MySQL plans from each tablet
+VEXPLAIN TRACE SELECT ...;  -- shows row counts passed between query parts
+```
+
+If a query scatters:
+1. Is `WHERE` filtering on the primary vindex column? If not, add it.
+2. Is a lookup vindex configured for that column? If needed, add one.
+3. Primary vindex column updates are blocked — use `MoveTables` to re-shard if needed.
+
+## Reference tables
+
+Small, rarely-changing lookup data (countries, currencies, enums) can use `"type": "reference"` — they are replicated to all shards and never scatter.
+
+## Sources
+- VSchema guide: https://vitess.io/docs/user-guides/vschema-guide/
+- Vindexes reference: https://vitess.io/docs/reference/features/vschema/
+- Sharding key selection: https://vitess.io/docs/faq/advanced-configuration/vschema/how-do-you-select-your-sharding-key-for-vitess/

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/antigravity/agents/backend-specialist.md

@@ -260,4 +260,4 @@ After editing any file:
 
 ---
 
-> **Note:** This agent loads relevant skills for detailed guidance. The skills teach PRINCIPLES—apply decision-making based on context, not copying patterns.
+> **Note:** For database-heavy backend work, route through `database-skills` plus `Ai Agent Workflow/powers/database-skills` so indexing, pagination, query-plan evidence, and rollback stay explicit.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/antigravity/agents/database-architect.md

@@ -209,6 +209,13 @@ After database changes:
 
 ---
 
+## Database Power Routing (MANDATORY)
+
+1. Load `database-skills` as the core package.
+2. Load power bridge: `Ai Agent Workflow/powers/database-skills/POWER.md`.
+3. Pick engine wrapper in `Ai Agent Workflow/powers/database-skills/engines/<engine>/POWER.md`.
+4. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
+
 ## When You Should Be Used
 
 - Designing new database schemas
@@ -223,4 +230,4 @@ After database changes:
 
 ---
 
-> **Note:** This agent loads the unified `database-skills` skill package for detailed guidance. Apply principles to context; do not copy patterns blindly.
+> **Note:** Use `database-skills` as source of truth. Use `Ai Agent Workflow/powers/database-skills` for power-mode routing, especially engine wrappers (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`).

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/antigravity/agents/performance-optimizer.md

@@ -185,3 +185,5 @@ What's slow?
 ---
 
 > **Remember:** Users don't care about benchmarks. They care about feeling fast.
+
+> **Database path:** For query/storage bottlenecks, route through `database-skills` and `Ai Agent Workflow/powers/database-skills` and report index/pagination/plan evidence.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/antigravity/workflows/database.md

@@ -5,22 +5,27 @@ triggers: ["database", "sql", "schema", "migration", "index"]
 ---
 # Database Workflow
 
-Use this when data modeling, query quality, or migration safety is core to the task.
+Use this when data modeling, query quality, migration safety, or database performance is core to the task.
 
 ## Routing
 - Primary specialist: `@database-architect`
 - Backend integration: `@backend-specialist`
 - Verification support: `@test-engineer`
 - Core skill package: `database-skills`
+- Power bridge: `Ai Agent Workflow/powers/database-skills`
+- Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
 
 ## Steps
-1. Confirm data shape and access patterns.
-2. Design schema/index strategy.
-3. Plan migration with rollback.
-4. Validate performance and integrity impacts.
+1. Confirm data shape, access patterns, and workload size.
+2. Choose engine wrapper and define index strategy.
+3. Define pagination strategy (keyset first, offset only if justified).
+4. Plan migration and rollback.
+5. Validate with query-plan evidence and production-risk notes.
 
 ## Output Contract
 - Schema/query changes
+- Indexing plan
+- Pagination plan
 - Migration + rollback plan
-- Performance expectations
+- Query-plan evidence (`EXPLAIN` or equivalent)
 - Validation evidence

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/codex/agents/backend-specialist.md

@@ -260,4 +260,4 @@ After editing any file:
 
 ---
 
-> **Note:** This agent loads relevant skills for detailed guidance. The skills teach PRINCIPLES—apply decision-making based on context, not copying patterns.
+> **Note:** For database-heavy backend work, route through `database-skills` plus `Ai Agent Workflow/powers/database-skills` so indexing, pagination, query-plan evidence, and rollback stay explicit.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/codex/agents/database-architect.md

@@ -209,6 +209,13 @@ After database changes:
 
 ---
 
+## Database Power Routing (MANDATORY)
+
+1. Load `database-skills` as the core package.
+2. Load power bridge: `Ai Agent Workflow/powers/database-skills/POWER.md`.
+3. Pick engine wrapper in `Ai Agent Workflow/powers/database-skills/engines/<engine>/POWER.md`.
+4. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
+
 ## When You Should Be Used
 
 - Designing new database schemas
@@ -223,4 +230,4 @@ After database changes:
 
 ---
 
-> **Note:** This agent loads the unified `database-skills` skill package for detailed guidance. Apply principles to context; do not copy patterns blindly.
+> **Note:** Use `database-skills` as source of truth. Use `Ai Agent Workflow/powers/database-skills` for power-mode routing, especially engine wrappers (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`).

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/codex/agents/performance-optimizer.md

@@ -185,3 +185,5 @@ What's slow?
 ---
 
 > **Remember:** Users don't care about benchmarks. They care about feeling fast.
+
+> **Database path:** For query/storage bottlenecks, route through `database-skills` and `Ai Agent Workflow/powers/database-skills` and report index/pagination/plan evidence.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/codex/workflows/database.md

@@ -5,22 +5,27 @@ triggers: ["database", "sql", "schema", "migration", "index"]
 ---
 # Database Workflow
 
-Use this when data modeling, query quality, or migration safety is core to the task.
+Use this when data modeling, query quality, migration safety, or database performance is core to the task.
 
 ## Routing
 - Primary specialist: `@database-architect`
 - Backend integration: `@backend-specialist`
 - Verification support: `@test-engineer`
 - Core skill package: `database-skills`
+- Power bridge: `Ai Agent Workflow/powers/database-skills`
+- Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
 
 ## Steps
-1. Confirm data shape and access patterns.
-2. Design schema/index strategy.
-3. Plan migration with rollback.
-4. Validate performance and integrity impacts.
+1. Confirm data shape, access patterns, and workload size.
+2. Choose engine wrapper and define index strategy.
+3. Define pagination strategy (keyset first, offset only if justified).
+4. Plan migration and rollback.
+5. Validate with query-plan evidence and production-risk notes.
 
 ## Output Contract
 - Schema/query changes
+- Indexing plan
+- Pagination plan
 - Migration + rollback plan
-- Performance expectations
+- Query-plan evidence (`EXPLAIN` or equivalent)
 - Validation evidence

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/agents/backend-specialist.md

@@ -257,4 +257,4 @@ After editing any file:
 
 ---
 
-> **Note:** This agent loads relevant skills for detailed guidance. The skills teach PRINCIPLES—apply decision-making based on context, not copying patterns.
+> **Note:** For database-heavy backend work, route through `database-skills` plus `Ai Agent Workflow/powers/database-skills` so indexing, pagination, query-plan evidence, and rollback stay explicit.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/agents/database-architect.md

@@ -206,6 +206,13 @@ After database changes:
 
 ---
 
+## Database Power Routing (MANDATORY)
+
+1. Load `database-skills` as the core package.
+2. Load power bridge: `Ai Agent Workflow/powers/database-skills/POWER.md`.
+3. Pick engine wrapper in `Ai Agent Workflow/powers/database-skills/engines/<engine>/POWER.md`.
+4. Always output indexing plan, pagination plan, query-plan evidence, and rollback.
+
 ## When You Should Be Used
 
 - Designing new database schemas
@@ -220,4 +227,4 @@ After database changes:
 
 ---
 
-> **Note:** This agent loads the unified `database-skills` skill package for detailed guidance. Apply principles to context; do not copy patterns blindly.
+> **Note:** Use `database-skills` as source of truth. Use `Ai Agent Workflow/powers/database-skills` for power-mode routing, especially engine wrappers (`postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`).

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/agents/performance-optimizer.md

@@ -182,3 +182,5 @@ What's slow?
 ---
 
 > **Remember:** Users don't care about benchmarks. They care about feeling fast.
+
+> **Database path:** For query/storage bottlenecks, route through `database-skills` and `Ai Agent Workflow/powers/database-skills` and report index/pagination/plan evidence.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/copilot/workflows/database.md

@@ -5,22 +5,27 @@ triggers: ["database", "sql", "schema", "migration", "index"]
 ---
 # Database Workflow
 
-Use this when data modeling, query quality, or migration safety is core to the task.
+Use this when data modeling, query quality, migration safety, or database performance is core to the task.
 
 ## Routing
 - Primary specialist: `@database-architect`
 - Backend integration: `@backend-specialist`
 - Verification support: `@test-engineer`
 - Core skill package: `database-skills`
+- Power bridge: `Ai Agent Workflow/powers/database-skills`
+- Engine wrappers: `postgres`, `mysql`, `vitess`, `neki`, `mongodb`, `sqlite`, `supabase`, `redis`
 
 ## Steps
-1. Confirm data shape and access patterns.
-2. Design schema/index strategy.
-3. Plan migration with rollback.
-4. Validate performance and integrity impacts.
+1. Confirm data shape, access patterns, and workload size.
+2. Choose engine wrapper and define index strategy.
+3. Define pagination strategy (keyset first, offset only if justified).
+4. Plan migration and rollback.
+5. Validate with query-plan evidence and production-risk notes.
 
 ## Output Contract
 - Schema/query changes
+- Indexing plan
+- Pagination plan
 - Migration + rollback plan
-- Performance expectations
+- Query-plan evidence (`EXPLAIN` or equivalent)
 - Validation evidence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubis/foundry",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Cubis Foundry CLI for workflow-first AI agent environments",
   "type": "module",
   "bin": {