@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/codex/db-graph-in-relational/skill.yaml

@@ -0,0 +1,41 @@
+name: db-graph-in-relational
+version: "1.0.0"
+description: Modeling graph relationships in SQL with recursive queries and knowing when to use a graph DB instead
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-adjacency-list
+  - db-closure-table
+  - db-hierarchical-data
+  - db-query-rewriting
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - graph
+  - edges
+  - vertices
+  - recursive-query
+  - shortest-path
+  - social-graph
+  - network-model
+  - graph-database
+metadata:
+  author: community
+  upstream: "postgresql.org/docs/current/queries-with.html"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-hash-index/SKILL.md

@@ -0,0 +1,176 @@
+# Hash Indexes
+
+> Optimized for equality-only lookups with O(1) average access time, hash indexes are smaller than B-tree when range queries and ordering are never needed.
+
+## When to Use
+
+- Columns queried exclusively with `=` operator (never range, ORDER BY, or IS NULL)
+- High-cardinality columns like UUIDs, session tokens, or API keys
+- Workloads where index size matters and the column is never used in sorting
+- PostgreSQL 10+ environments (hash indexes were not crash-safe before v10)
+
+## Instructions
+
+### Key Concepts
+
+A hash index applies a hash function to each indexed value, mapping it to a bucket. Lookups compute the hash of the search value and jump directly to the matching bucket -- O(1) average time.
+
+**Critical limitation:** Hash indexes only support the `=` operator. They cannot do:
+
+- Range queries (`<`, `>`, `BETWEEN`)
+- Ordering (`ORDER BY`)
+- IS NULL lookups
+- Pattern matching (`LIKE`)
+
+**Syntax:**
+
+```sql
+CREATE INDEX idx_sessions_token ON sessions USING hash (token);
+```
+
+The `USING hash` clause is required -- without it, PostgreSQL creates a B-tree by default.
+
+**Size advantage:** For pure equality workloads, hash indexes are typically 20-40% smaller than equivalent B-tree indexes because they do not store values in sorted order and have a simpler page structure.
+
+### Worked Example
+
+Consider a session lookup table with 50M rows where the only access pattern is `WHERE session_token = ?`:
+
+```sql
+CREATE TABLE sessions (
+  id            SERIAL PRIMARY KEY,
+  session_token UUID NOT NULL,
+  user_id       INT NOT NULL,
+  expires_at    TIMESTAMPTZ NOT NULL
+);
+
+-- Create both index types for comparison:
+CREATE INDEX idx_sessions_hash  ON sessions USING hash (session_token);
+CREATE INDEX idx_sessions_btree ON sessions USING btree (session_token);
+```
+
+**Query using the hash index:**
+
+```sql
+EXPLAIN ANALYZE
+SELECT user_id, expires_at
+FROM sessions
+WHERE session_token = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
+```
+
+```
+Index Scan using idx_sessions_hash on sessions
+  (cost=0.00..2.02 rows=1 width=12)
+  (actual time=0.018..0.019 rows=1 loops=1)
+  Index Cond: (session_token = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890')
+Planning Time: 0.089 ms
+Execution Time: 0.042 ms
+```
+
+**Size comparison:**
+
+```sql
+SELECT
+  pg_size_pretty(pg_relation_size('idx_sessions_hash'))  AS hash_size,
+  pg_size_pretty(pg_relation_size('idx_sessions_btree')) AS btree_size;
+```
+
+```
+ hash_size | btree_size
+-----------+-----------
+ 1.1 GB    | 1.8 GB
+```
+
+The hash index is 40% smaller for the same 50M UUID values, because it stores fixed-size hash values rather than the full sorted UUID.
+
+After confirming the hash index works, drop the redundant B-tree:
+
+```sql
+DROP INDEX idx_sessions_btree;
+```
+
+### Anti-Patterns
+
+1. **Hash index on columns used in ORDER BY.** Hash indexes cannot produce sorted output. If any query needs `ORDER BY session_token`, a B-tree is required.
+
+2. **Hash index on low-cardinality columns.** A status column with 3 distinct values gains nothing from hashing -- all values land in very few buckets. Use a partial index or accept sequential scan.
+
+3. **Hash index on PostgreSQL < 10.** Before version 10, hash indexes were not WAL-logged and could not survive a crash or be replicated. Never use them on older versions.
+
+4. **Choosing hash when size difference is negligible.** If the indexed column is a small integer (4 bytes), B-tree and hash indexes are nearly the same size. Keep B-tree for its broader operator support.
+
+5. **Hash index with UNIQUE constraint.** PostgreSQL does not support UNIQUE hash indexes. If you need uniqueness enforcement, use B-tree.
+
+### PostgreSQL Specifics
+
+**WAL safety (v10+).** Hash indexes became WAL-logged in PostgreSQL 10, making them crash-safe and replication-compatible. Before v10, a crash required a full REINDEX.
+
+**Monitoring usage:**
+
+```sql
+SELECT indexrelname, idx_scan, idx_tup_read
+FROM pg_stat_user_indexes
+WHERE indexrelname = 'idx_sessions_hash';
+```
+
+If `idx_scan` is zero after production traffic, the index is unused and should be dropped.
+
+**REINDEX for bloated hash indexes:**
+
+```sql
+REINDEX INDEX CONCURRENTLY idx_sessions_hash;
+```
+
+Hash indexes can accumulate overflow pages after many inserts and deletes. REINDEX reclaims space.
+
+## Details
+
+### Advanced Topics
+
+**Internal structure.** A hash index consists of four page types:
+
+- **Meta page** (page 0): stores the hash function identifier and current bucket count
+- **Bucket pages**: primary storage for hash entries, one per hash bucket
+- **Overflow pages**: chained from bucket pages when a bucket is full
+- **Bitmap pages**: track which overflow pages are free for reuse
+
+When the number of entries exceeds the bucket capacity, PostgreSQL splits buckets (doubling the bucket count). This split operation is logged in WAL for crash safety.
+
+**Hash collisions.** Different values can hash to the same bucket. PostgreSQL stores the full hash value with each entry and rechecks the actual column value to resolve collisions. High collision rates increase overflow pages and degrade performance.
+
+**Parallel builds.** PostgreSQL 15+ supports parallel hash index builds, reducing creation time for large tables.
+
+### Engine Differences
+
+**MySQL InnoDB** does not support explicit hash indexes. The **Adaptive Hash Index (AHI)** is an internal InnoDB optimization that automatically builds in-memory hash indexes for frequently accessed B-tree pages. You cannot create, drop, or control AHI directly -- it is managed by the `innodb_adaptive_hash_index` setting (ON by default).
+
+**MySQL MEMORY engine** supports explicit hash indexes (`USING HASH`), but the MEMORY engine stores all data in RAM, does not persist across restarts, and is rarely used in production.
+
+**Practical impact:** In MySQL, you always create B-tree indexes. If InnoDB detects a hot equality-lookup pattern, AHI accelerates it transparently. There is no MySQL equivalent to PostgreSQL's explicit `CREATE INDEX ... USING hash`.
+
+### Real-World Case Studies
+
+**API gateway with 200M session tokens.** The gateway authenticated every request by looking up `WHERE token = ?`. Switching from a B-tree to a hash index on the `token` column (UUID type) reduced index size from 8.5GB to 5.1GB (40% reduction) and average lookup latency from 0.23ms to 0.19ms (15% improvement). The savings were meaningful at scale: 50K lookups/second meant the reduced I/O translated to measurably lower CPU and buffer pool pressure.
+
+## Source
+
+- [PostgreSQL Index Types](https://www.postgresql.org/docs/current/indexes-types.html)
+- [PostgreSQL 10 Release Notes -- Hash Index Durability](https://www.postgresql.org/docs/10/release-10.html)
+
+## Process
+
+1. Read the key concepts to understand when hash indexes outperform B-tree.
+2. Apply hash indexes only to columns with exclusively equality lookups and no ordering, range, or NULL requirements.
+3. Verify with EXPLAIN ANALYZE that the planner uses the hash index and compare index sizes.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-btree-index, db-composite-index, db-explain-reading, db-scan-types
+
+## Success Criteria
+
+- Hash indexes are used only for equality-only columns where B-tree's broader operator support is unnecessary.
+- B-tree is preferred when any range, ordering, or NULL lookup is needed.
+- Index size reduction is verified with `pg_relation_size` comparison.

package/dist/agents/skills/codex/db-hash-index/skill.yaml

@@ -0,0 +1,37 @@
+name: db-hash-index
+version: '1.0.0'
+description: Hash indexes for equality-only lookups and when to prefer them over B-tree
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-btree-index
+  - db-composite-index
+  - db-explain-reading
+  - db-scan-types
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - hash-index
+  - equality-lookup
+  - hash-function
+  - index-type
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/indexes-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/db-hierarchical-data/SKILL.md

@@ -0,0 +1,194 @@
+# Hierarchical Data Selection Guide
+
+> Choosing between adjacency list, nested sets, closure table, and materialized path based on read/write ratio, query patterns, and tree depth.
+
+## When to Use
+
+- Any time you need to model a tree or hierarchy in a relational database
+- This skill is the entry point that routes to the specific pattern skills (db-adjacency-list, db-nested-sets, db-closure-table)
+- When evaluating which hierarchy model fits your workload before committing to a schema
+
+## Instructions
+
+### Key Concepts
+
+Four approaches exist for modeling hierarchies in relational databases. Each trades off read performance, write performance, storage, and integrity differently:
+
+| Operation             | Adjacency List     | Nested Sets | Closure Table   | Materialized Path  |
+| --------------------- | ------------------ | ----------- | --------------- | ------------------ |
+| Insert node           | O(1)               | O(n)        | O(depth)        | O(1)               |
+| Delete node           | O(1)               | O(n)        | O(subtree)      | O(subtree)         |
+| Move subtree          | O(1)               | O(n)        | O(subtree^2)    | O(subtree)         |
+| Get children          | O(1) indexed       | O(1)        | O(1)            | O(1) pattern match |
+| Get subtree           | O(depth) recursive | O(1) range  | O(1) join       | O(1) LIKE          |
+| Get ancestors         | O(depth) recursive | O(1) range  | O(1) join       | O(1) split         |
+| Get depth             | Recursive          | Computed    | Stored          | Count separators   |
+| Storage overhead      | None               | 2 cols/row  | O(N log N) rows | 1 col/row          |
+| Referential integrity | FK enforced        | App-level   | FK enforced     | App-level          |
+
+**Decision rules:**
+
+1. **Write-heavy with simple parent-child queries** -- adjacency list. O(1) inserts, recursive CTEs for occasional subtree reads.
+2. **Read-heavy, rarely changing** -- nested sets. O(1) subtree queries via range checks, but O(n) writes.
+3. **Read-heavy with moderate writes, need referential integrity** -- closure table. O(1) reads via join, O(depth) writes.
+4. **Simple hierarchy on PostgreSQL** -- materialized path with `ltree`. Compact, GiST-indexable, good read/write balance.
+
+### Worked Example
+
+Three scenarios demonstrating which model to choose:
+
+**Scenario 1: Comment threading (frequent inserts, rare full-tree reads)**
+
+Choose **adjacency list**. Comments are inserted constantly. Full-thread reads (subtree) happen only when a user opens a thread. The recursive CTE cost is acceptable for occasional reads:
+
+```sql
+-- O(1) insert
+INSERT INTO comments (body, parent_id) VALUES ('Reply', 42);
+
+-- Occasional subtree read via recursive CTE
+WITH RECURSIVE thread AS (
+  SELECT * FROM comments WHERE id = 1
+  UNION ALL
+  SELECT c.* FROM comments c JOIN thread t ON c.parent_id = t.id
+)
+SELECT * FROM thread;
+```
+
+**Scenario 2: Product taxonomy (updated weekly, queried constantly)**
+
+Choose **nested sets** or **closure table**. The taxonomy changes once a week but "all products in Electronics" runs thousands of times per day:
+
+```sql
+-- Nested sets: O(1) subtree read, no recursion
+SELECT * FROM categories WHERE lft BETWEEN 2 AND 11;
+
+-- Closure table: O(1) subtree read via join
+SELECT c.* FROM categories c
+JOIN category_paths cp ON c.id = cp.descendant_id
+WHERE cp.ancestor_id = 5;
+```
+
+If the taxonomy needs referential integrity, prefer closure table. If pure read speed matters most, prefer nested sets.
+
+**Scenario 3: RBAC permission hierarchy (moderate changes, frequent "is ancestor?" checks)**
+
+Choose **closure table**. The "is X an ancestor of Y?" check is a single-row existence query:
+
+```sql
+SELECT EXISTS(
+  SELECT 1 FROM role_paths
+  WHERE ancestor_id = 10 AND descendant_id = 42
+);
+-- 0.2ms with index
+```
+
+### Anti-Patterns
+
+1. **Choosing a model without analyzing read/write ratio.** The decision matrix above exists for a reason. Profile your workload before committing.
+2. **Using nested sets for write-heavy hierarchies.** O(n) per insert is catastrophic for high-write workloads. Use adjacency list.
+3. **Using adjacency list when subtree queries dominate and depth is large.** Recursive CTE performance degrades linearly with depth. For trees deeper than 20 levels with frequent subtree reads, consider closure table.
+4. **Using materialized path without ltree extension.** Manual string parsing (`LIKE '/1/5/%'`) is fragile, prone to injection, and cannot use specialized indexes. Use `ltree` on PostgreSQL.
+5. **Mixing models without documenting which queries use which.** If you maintain both adjacency list and closure table, document that writes go through parent_id and reads go through the closure table.
+
+### PostgreSQL Specifics
+
+**ltree extension** for materialized path -- the recommended default for PostgreSQL users who need hierarchy queries without closure table complexity:
+
+```sql
+CREATE EXTENSION ltree;
+
+CREATE TABLE categories (
+  id   serial PRIMARY KEY,
+  name varchar NOT NULL,
+  path ltree NOT NULL
+);
+
+CREATE INDEX idx_categories_path ON categories USING gist (path);
+
+-- Insert with path
+INSERT INTO categories (name, path) VALUES
+  ('Electronics', 'electronics'),
+  ('Computers', 'electronics.computers'),
+  ('Laptops', 'electronics.computers.laptops');
+```
+
+**ltree operators:**
+
+- `@>` ancestor check: `'electronics' @> 'electronics.computers.laptops'` -- true
+- `<@` descendant check: `'electronics.computers.laptops' <@ 'electronics'` -- true
+- `~` regex match: `path ~ '*.computers.*'`
+- `?` lquery match: `path ? 'electronics.*{1,2}'` -- depth 1-2 under electronics
+
+**GiST index on path** enables fast ancestor/descendant checks without joins or recursion. `ltree` is often the best balance of simplicity and performance for PostgreSQL hierarchies.
+
+## Details
+
+### Advanced Topics
+
+**Hybrid models** combine two approaches for different query patterns:
+
+- **Adjacency list + closure table:** parent_id for simple parent lookups and O(1) inserts; closure table for subtree and ancestor queries. Maintain both on write.
+- **Adjacency list + materialized path:** parent_id for writes; path column (ltree or VARCHAR) for subtree reads. Rebuild paths in batch.
+
+**Migration between models:**
+
+- Adjacency list to closure table: recursive CTE computes all ancestor-descendant pairs
+- Adjacency list to nested sets: recursive traversal assigns lft/rgt numbers
+- Any model to materialized path: recursive CTE builds path strings
+
+**Depth limits and performance cliffs:**
+
+- Adjacency list: linear degradation past depth 20-30 (each recursive step is a query)
+- Nested sets: no depth performance impact (range query regardless of depth)
+- Closure table: no depth performance impact (single join), but storage grows with depth
+- Materialized path: path string length grows linearly; ltree supports up to 65535 labels
+
+### Engine Differences
+
+MySQL lacks the `ltree` extension. Materialized path on MySQL requires:
+
+- VARCHAR column with string path like `/1/5/12/`
+- B-tree index with prefix matching: `WHERE path LIKE '/1/5/%'`
+- No specialized operators -- all path logic is string manipulation
+- Limited to B-tree prefix scans (no GiST)
+
+**MySQL recommendations by workload:**
+
+- Write-heavy: adjacency list with `WITH RECURSIVE` (MySQL 8.0+)
+- Read-heavy: closure table (works identically in MySQL)
+- Simple hierarchy: adjacency list is usually sufficient given MySQL 8.0's CTE support
+
+MySQL nested sets work identically to PostgreSQL but lack exclusion constraints for integrity validation.
+
+### Real-World Case Studies
+
+**Three companies, three choices:**
+
+1. **Slack-like messaging:** Adjacency list. 1B messages total, threads rarely exceed depth 5. Insert latency under 1ms. Recursive CTE for thread display adds 3-8ms -- acceptable since threads are loaded on-demand.
+
+2. **Amazon-like product taxonomy:** Nested sets. 200K categories, rebuilt nightly from the merchandising system. Subtree queries ("all products in Electronics") complete in under 1ms. The nightly rebuild (full renumbering) takes 4 seconds.
+
+3. **AWS-like IAM:** Closure table. 500K permission nodes in a 15-level hierarchy. "Is X an ancestor of Y?" completes in 0.2ms. Node additions average 50/day -- each insert copies ~15 closure rows. The 1.5M closure row overhead (3x node count) is justified by the 40x speedup on ancestry checks.
+
+## Source
+
+- [Bill Karwin -- SQL Antipatterns (Trees chapter)](https://pragprog.com/titles/bksqla/sql-antipatterns/)
+- [PostgreSQL ltree](https://www.postgresql.org/docs/current/ltree.html)
+
+## Process
+
+1. Read the decision matrix to understand the tradeoffs of each hierarchy model.
+2. Profile your read/write ratio and dominant query patterns to select the appropriate model.
+3. Verify the selected model meets performance requirements with EXPLAIN ANALYZE on representative queries.
+
+## Harness Integration
+
+- **Type:** knowledge -- this skill is a reference document, not a procedural workflow.
+- **No tools or state** -- consumed as context by other skills and agents.
+- **related_skills:** db-adjacency-list, db-nested-sets, db-closure-table, db-graph-in-relational
+
+## Success Criteria
+
+- Hierarchy model is selected based on measured read/write ratio and query patterns, not defaulting to adjacency list for every case.
+- The selection decision is documented with rationale.
+- Performance is validated with EXPLAIN ANALYZE on the dominant query pattern.

package/dist/agents/skills/codex/db-hierarchical-data/skill.yaml

@@ -0,0 +1,41 @@
+name: db-hierarchical-data
+version: "1.0.0"
+description: Comparison of adjacency list, nested sets, closure table, and materialized path -- a selection guide
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-adjacency-list
+  - db-nested-sets
+  - db-closure-table
+  - db-graph-in-relational
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - hierarchical-data
+  - tree-model
+  - hierarchy-selection
+  - adjacency-list
+  - nested-sets
+  - closure-table
+  - materialized-path
+  - ltree
+metadata:
+  author: community
+  upstream: "postgresql.org/docs/current/ltree.html"
+state:
+  persistent: false
+  files: []
+depends_on: []