@harness-engineering/cli 1.24.0 → 1.24.3

package/dist/agents/skills/gemini-cli/db-document-in-relational/skill.yaml

@@ -0,0 +1,42 @@
+name: db-document-in-relational
+version: "1.0.0"
+description: JSONB columns for semi-structured data -- when to embed vs normalize, indexing JSON, and hybrid modeling
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-entity-attribute-value
+  - db-polymorphic-associations
+  - db-first-normal-form
+  - db-denormalization
+  - db-expression-index
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - JSONB
+  - JSON
+  - document-store
+  - semi-structured
+  - embed-vs-normalize
+  - GIN-index
+  - hybrid-model
+  - schemaless
+metadata:
+  author: community
+  upstream: "postgresql.org/docs/current/datatype-json.html"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/db-entity-attribute-value/SKILL.md

@@ -0,0 +1,186 @@
+# Entity-Attribute-Value (EAV)
+
+> A schema pattern for storing dynamic, user-defined attributes as rows instead of columns -- usually avoided in favor of JSONB or polymorphic alternatives, but occasionally justified for genuinely unbounded attribute sets.
+
+## When to Use
+
+- Truly user-defined attributes where the attribute set is unknown at design time (e.g., product catalog with 10K+ varying attributes across categories)
+- Medical records with thousands of possible observation types
+- Legacy systems where the EAV pattern is already entrenched and migration cost is prohibitive
+- Multi-tenant platforms where each tenant defines custom fields
+
+## Instructions
+
+### Key Concepts
+
+EAV stores data as `(entity_id, attribute_name, attribute_value)` triples instead of columns:
+
+```sql
+CREATE TABLE product_attributes (
+  product_id     int REFERENCES products(id),
+  attribute_name varchar NOT NULL,
+  attribute_value text,
+  PRIMARY KEY (product_id, attribute_name)
+);
+```
+
+Each attribute becomes a row instead of a column. An entity with 20 attributes produces 20 rows.
+
+**Core tradeoffs:**
+
+- Maximum flexibility for schema evolution -- new attributes require no DDL changes
+- Loss of type safety -- all values stored as text in a single column
+- No per-attribute constraints -- cannot enforce NOT NULL, CHECK, or FK per attribute
+- Query complexity -- pivoting rows back to columns for reporting requires crosstab queries
+- EAV violates First Normal Form: values of different types (dates, numbers, strings) share one column
+
+### Worked Example
+
+An e-commerce product catalog. Products have standard columns in a relational table plus dynamic attributes in EAV:
+
+```sql
+CREATE TABLE products (
+  id    serial PRIMARY KEY,
+  name  varchar NOT NULL,
+  price numeric(10,2) NOT NULL,
+  sku   varchar UNIQUE NOT NULL
+);
+
+-- EAV for varying attributes
+INSERT INTO product_attributes VALUES
+  (1, 'color', 'red'),
+  (1, 'size', 'large'),
+  (1, 'material', 'cotton'),
+  (2, 'color', 'blue'),
+  (2, 'wattage', '60');
+```
+
+**Querying "all products where color = red AND size = large"** requires a self-join:
+
+```sql
+SELECT p.id, p.name
+FROM products p
+JOIN product_attributes a1
+  ON p.id = a1.product_id AND a1.attribute_name = 'color' AND a1.attribute_value = 'red'
+JOIN product_attributes a2
+  ON p.id = a2.product_id AND a2.attribute_name = 'size' AND a2.attribute_value = 'large';
+```
+
+**The same query with JSONB** (preferred alternative):
+
+```sql
+ALTER TABLE products ADD COLUMN attrs jsonb DEFAULT '{}';
+
+-- Single-row update instead of multiple EAV inserts
+UPDATE products SET attrs = '{"color": "red", "size": "large", "material": "cotton"}' WHERE id = 1;
+
+-- Dramatically simpler query
+SELECT id, name FROM products
+WHERE attrs->>'color' = 'red' AND attrs->>'size' = 'large';
+```
+
+The JSONB approach is simpler to query, supports GIN indexing, and stores all attributes in one row. **Prefer JSONB for most EAV use cases.**
+
+### Anti-Patterns
+
+1. **Using EAV for attributes known at design time.** If the attributes are stable, just add columns -- they provide type safety, constraints, and simple queries.
+2. **Storing typed data as text without validation.** Dates, numbers, and booleans all become strings. Application bugs go undetected until downstream processing fails.
+3. **Not adding a `value_type` discriminator column.** When EAV is unavoidable, include a type column (`text`, `integer`, `date`) and separate typed value columns.
+4. **Using EAV when JSONB would serve the same purpose.** JSONB provides better indexing, simpler queries, and containment operators.
+5. **Missing indexes on `(attribute_name, attribute_value)`.** Without them, every attribute filter is a sequential scan on the entire EAV table.
+
+### PostgreSQL Specifics
+
+JSONB is the primary alternative to EAV in PostgreSQL. It supports:
+
+- **GIN indexing** for containment queries:
+
+```sql
+CREATE INDEX ON products USING gin (attrs jsonb_path_ops);
+
+-- Uses the GIN index:
+SELECT * FROM products WHERE attrs @> '{"color": "red"}';
+```
+
+- **Path queries** with expression indexes for specific fields:
+
+```sql
+CREATE INDEX ON products ((attrs->>'color'));
+```
+
+- **Key-exists checks** with `?`, `?&`, `?|` operators
+- **hstore extension** as a lightweight key-value alternative when full JSON structure is not needed
+
+## Details
+
+### Advanced Topics
+
+**Crosstab queries** with the `tablefunc` extension pivot EAV rows into columns:
+
+```sql
+SELECT * FROM crosstab(
+  'SELECT product_id, attribute_name, attribute_value
+   FROM product_attributes ORDER BY 1, 2',
+  'SELECT DISTINCT attribute_name FROM product_attributes ORDER BY 1'
+) AS ct(product_id int, color text, material text, size text, wattage text);
+```
+
+**Typed EAV** uses separate value columns per type:
+
+```sql
+CREATE TABLE product_attributes (
+  product_id     int REFERENCES products(id),
+  attribute_name varchar NOT NULL,
+  value_type     varchar NOT NULL CHECK (value_type IN ('text', 'integer', 'date', 'numeric')),
+  text_value     text,
+  int_value      integer,
+  date_value     date,
+  numeric_value  numeric,
+  PRIMARY KEY (product_id, attribute_name)
+);
+```
+
+**Performance at scale:** EAV tables with 100M+ rows require careful indexing. Partition by entity type or attribute category to keep individual partitions manageable. Consider composite indexes on `(attribute_name, attribute_value, product_id)` for attribute-first lookups.
+
+### Engine Differences
+
+MySQL 5.7+ supports JSON columns but with weaker indexing than PostgreSQL JSONB:
+
+- MySQL lacks GIN indexes and containment operators (`@>`)
+- JSON path queries require generated columns with B-tree indexes:
+
+```sql
+ALTER TABLE products
+  ADD COLUMN color varchar(50) GENERATED ALWAYS AS (JSON_UNQUOTE(attrs->'$.color')) VIRTUAL;
+CREATE INDEX idx_color ON products(color);
+```
+
+- MySQL multi-valued indexes (8.0.17+) can index JSON arrays but not arbitrary key-value pairs
+- For MySQL stacks, EAV may remain more practical than JSON for complex attribute filtering, though the query complexity cost remains
+
+### Real-World Case Studies
+
+**Healthcare system with 50K distinct observation types.** Original EAV schema held 2B rows. Patient timeline queries took 30+ seconds because each observation required a self-join. Migration strategy: kept EAV for rare attributes (the long tail below 100 queries/day), moved the top-100 most-queried attributes (covering 95% of all queries) to dedicated columns on the patient record. Common lookup query time dropped from 30s to 200ms. Rare-attribute queries remained in EAV at acceptable latency for their low frequency.
+
+## Source
+
+- [SQL Antipatterns by Bill Karwin -- EAV chapter](https://pragprog.com/titles/bksqla/sql-antipatterns/)
+- [PostgreSQL JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)
+
+## Process
+
+1. Read the key concepts to understand the EAV tradeoffs and when it is justified.
+2. Evaluate whether JSONB, polymorphic associations, or dedicated columns better serve your use case before choosing EAV.
+3. If EAV is chosen, verify that indexing, type discrimination, and query patterns are documented and tested.
+
+## 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-polymorphic-associations, db-document-in-relational, db-first-normal-form, db-denormalization
+
+## Success Criteria
+
+- EAV is only used when the attribute set is genuinely unbounded and unknown at design time.
+- JSONB is preferred over EAV for most dynamic-attribute needs.
+- When EAV is used, typed value columns and proper indexing are in place.

package/dist/agents/skills/gemini-cli/db-entity-attribute-value/skill.yaml

@@ -0,0 +1,39 @@
+name: db-entity-attribute-value
+version: "1.0.0"
+description: EAV pattern for dynamic attributes -- when justified, why usually avoided, and alternatives
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-polymorphic-associations
+  - db-document-in-relational
+  - db-first-normal-form
+  - db-denormalization
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - EAV
+  - entity-attribute-value
+  - dynamic-schema
+  - key-value
+  - sparse-columns
+  - metadata-table
+metadata:
+  author: community
+  upstream: "en.wikipedia.org/wiki/Entity%E2%80%93attribute%E2%80%93value_model"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/db-eventual-consistency/SKILL.md

@@ -0,0 +1,226 @@
+# Eventual Consistency
+
+> If no new updates are made, all replicas will eventually converge to the same value -- a consistency model that trades immediate agreement for higher availability and lower latency.
+
+## When to Use
+
+- Designing systems with read replicas where slight staleness is acceptable
+- Understanding and measuring replication lag behavior
+- Choosing conflict resolution strategies for multi-writer distributed systems
+- Working with distributed caches, queues, or event-driven architectures
+- Implementing read-your-writes patterns for user-facing applications
+
+## Instructions
+
+### BASE Properties
+
+BASE is the counterpoint to ACID for distributed systems:
+
+- **Basically Available:** The system appears to work most of the time. Individual node failures do not take down the whole system. Partial failures are tolerated.
+- **Soft state:** The system's state may change without explicit input because replicas are still converging. A read now and a read 2 seconds later may return different values even if no writes occurred.
+- **Eventually consistent:** Given sufficient time without new updates, all replicas converge to the same value. "Sufficient time" is typically milliseconds to seconds but can be longer under load or partition.
+
+**ACID vs. BASE comparison:**
+
+```
+ACID                          BASE
+────                          ────
+Strong consistency            Eventual consistency
+Pessimistic (lock first)      Optimistic (resolve later)
+Availability sacrifice        Consistency sacrifice
+Single-node focus             Distributed-system focus
+```
+
+### Replication Lag in PostgreSQL
+
+PostgreSQL streaming replication introduces observable lag between primary and replica:
+
+```sql
+-- On the replica: measure how far behind the primary we are
+SELECT
+  now() - pg_last_xact_replay_timestamp() AS replication_lag;
+```
+
+**Real-world scenario:** A user updates their profile name on the primary. The application immediately redirects to a profile page that reads from a replica. The replica has not received the update yet. The user sees their old name -- a classic eventual consistency artifact.
+
+Typical replication lag under normal conditions is 1-100ms. Under write-heavy load or network congestion, it can reach seconds or minutes.
+
+### Convergence Strategy 1: Last-Write-Wins (LWW)
+
+The simplest conflict resolution: the write with the latest timestamp wins.
+
+```sql
+-- Two nodes receive concurrent writes for the same row
+-- Node A: UPDATE users SET name = 'Alice B.' WHERE id = 1;  -- timestamp 12:00:00.001
+-- Node B: UPDATE users SET name = 'Alice C.' WHERE id = 1;  -- timestamp 12:00:00.003
+
+-- LWW resolution: 'Alice C.' wins because its timestamp is later
+```
+
+**Problem:** Clock skew between nodes can cause the "earlier" logical write to have a later timestamp. A valid update gets silently discarded. LWW is acceptable only when losing a concurrent update is tolerable (profile pictures, status messages) -- never for counters or financial data.
+
+### Convergence Strategy 2: Version Vectors
+
+Each node maintains a version counter per node. Concurrent writes are detected (not silently resolved) and flagged for manual or application-level resolution.
+
+```
+Node A version vector: {A: 3, B: 2}
+Node B version vector: {A: 2, B: 3}
+
+-- Neither dominates the other -> conflict detected
+-- System flags both versions for resolution
+```
+
+Used by: Riak (sibling values), DynamoDB (conditional writes with version checks).
+
+### Convergence Strategy 3: CRDTs
+
+Conflict-free Replicated Data Types are data structures designed to merge automatically without coordination.
+
+**G-Counter example (distributed page view counting):**
+
+```
+Node A counter: {A: 150, B: 0, C: 0}   -- A has seen 150 views
+Node B counter: {A: 0, B: 230, C: 0}   -- B has seen 230 views
+Node C counter: {A: 0, B: 0, C: 95}    -- C has seen 95 views
+
+-- Merge: take max of each node's count
+-- Total = 150 + 230 + 95 = 475
+```
+
+Each node only increments its own counter. Merging takes the maximum per node. No conflicts possible -- the merge is commutative, associative, and idempotent.
+
+**Common CRDT types:**
+
+- **G-Counter:** Grow-only counter (page views, likes)
+- **PN-Counter:** Counter that supports increment and decrement
+- **OR-Set:** Observed-Remove Set (shopping cart items, tag sets)
+- **LWW-Register:** Single value with last-write-wins semantics
+
+### Convergence Strategy 4: Application-Level Resolution
+
+When business logic determines the merge, no generic strategy works. The system stores all conflicting versions and the application resolves them.
+
+**Example -- shopping cart merge:**
+
+```
+User adds item A on their phone:    cart = {A, B}
+User adds item C on their laptop:   cart = {B, C}
+
+-- Application resolution: union of both carts
+-- Merged cart = {A, B, C}
+```
+
+Amazon's Dynamo paper (2007) uses this approach: the shopping cart is a CRDT-like set where the merge function is union.
+
+### Read-Your-Writes Consistency
+
+A pattern that ensures the session that wrote data can immediately read it back, even in an eventually consistent system:
+
+**Option 1 -- route reads to primary after writes:**
+
+```
+-- Pseudocode
+if (session.has_recent_write):
+    read_from(primary)
+else:
+    read_from(replica)
+```
+
+**Option 2 -- wait for replica to catch up:**
+
+```sql
+-- PostgreSQL: ensure replica has applied up to this LSN
+SELECT pg_last_wal_replay_lsn() >= 'A/B1C2D3E'::pg_lsn;
+```
+
+**Option 3 -- synchronous replication for specific transactions:**
+
+```sql
+-- On the primary: wait for replica to apply before returning
+SET synchronous_commit = remote_apply;
+UPDATE users SET name = 'Alice' WHERE id = 1;
+```
+
+### Worked Example: Notification Service
+
+A notification service writes new notifications to the primary and reads the notification count from a replica for the badge display. After sending a notification, the count badge does not update for 200ms (replication lag).
+
+Fix: After writing a notification, include the primary's WAL LSN in the response. The frontend sends this LSN with the badge count request. The read path waits for the replica to reach that LSN before querying:
+
+```sql
+-- Wait up to 5 seconds for replica to catch up to the given LSN
+SELECT pg_wal_replay_wait('0/16B3748'::pg_lsn, 5000);
+SELECT COUNT(*) FROM notifications WHERE user_id = 42 AND read = false;
+```
+
+### Anti-Patterns
+
+1. **Assuming eventual means "consistent soon enough."** Without measuring actual replication lag, "eventually" could mean seconds or minutes under load. Monitor lag with `pg_stat_replication` and set alerts for unacceptable values.
+
+2. **Using eventual consistency for operations that require read-your-writes.** If a user changes their email and immediately needs to log in with it, eventual consistency on the auth read path causes login failures.
+
+3. **Ignoring conflict resolution strategy.** If two writers can update the same data, you need a conflict resolution strategy. "Conflicts probably will not happen" is not a strategy -- they will happen, and silent data loss is the result.
+
+4. **Treating all reads equally.** Not every read needs strong consistency. Classify your read operations by staleness tolerance and route accordingly.
+
+## Details
+
+### The Consistency Spectrum
+
+From strongest to weakest:
+
+```
+Strong (linearizable)    -- Every read sees the latest write. Single source of truth.
+Sequential               -- All nodes see operations in the same order (but not necessarily the latest).
+Causal                   -- Operations that are causally related are seen in order. Concurrent operations may be seen differently.
+Eventual                 -- All replicas converge given enough time. No ordering guarantees.
+```
+
+Most applications need causal consistency at minimum for user-facing operations and can tolerate eventual consistency for background or analytics operations.
+
+### PostgreSQL Logical Replication and Conflicts
+
+PostgreSQL logical replication (used for selective table replication and version upgrades) uses last-write-wins by default. If the same row is updated on both publisher and subscriber, the subscriber's local change is overwritten when the publisher's change arrives.
+
+```sql
+-- Logical replication conflict handling
+ALTER SUBSCRIPTION my_sub SET (disable_on_error = true);
+```
+
+Conflicts in logical replication are logged but not automatically resolved. Monitor `pg_stat_subscription` for error states.
+
+### MySQL Callout
+
+MySQL Group Replication offers a "virtually synchronous" mode where transactions are certified (checked for conflicts) across all group members before committing. This provides a stronger consistency guarantee than pure asynchronous replication while maintaining higher availability than fully synchronous replication. It is MySQL's closest equivalent to PostgreSQL's synchronous replication with `remote_apply`.
+
+### Real-World Case Study: E-Commerce Inventory
+
+An e-commerce platform used eventually consistent read replicas for product pages. Inventory counts on product pages were served from replicas with 100-500ms lag. Problem: customers saw "In Stock" on the product page but got "Out of Stock" errors at checkout (which hit the primary).
+
+Solution: A hybrid approach. Product descriptions, images, and reviews were served from replicas (eventual consistency -- staleness is invisible). Inventory counts and prices were served from the primary via a dedicated API endpoint with connection pooling. The extra primary load was minimal (inventory is a single indexed lookup) and eliminated the customer-visible inconsistency.
+
+## Source
+
+- [PostgreSQL Warm Standby](https://www.postgresql.org/docs/current/warm-standby.html)
+- [PostgreSQL Streaming Replication](https://www.postgresql.org/docs/current/streaming-replication.html)
+- Vogels, W. "Eventually Consistent" (2008)
+- Shapiro, M. et al. "A Comprehensive Study of Convergent and Commutative Replicated Data Types" (2011)
+- DeCandia, G. et al. "Dynamo: Amazon's Highly Available Key-value Store" (2007)
+
+## Process
+
+1. Read the BASE properties and convergence strategies in this document.
+2. Classify each read operation in your system by staleness tolerance, and route reads to primary or replica accordingly.
+3. For multi-writer scenarios, choose and implement an explicit conflict resolution strategy before deployment.
+
+## 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-cap-theorem, db-acid-properties
+
+## Success Criteria
+
+- Read operations are classified by staleness tolerance, with critical reads routed to the primary.
+- A conflict resolution strategy is explicitly chosen and implemented for any multi-writer data paths.

package/dist/agents/skills/gemini-cli/db-eventual-consistency/skill.yaml

@@ -0,0 +1,38 @@
+name: db-eventual-consistency
+version: '1.0.0'
+description: BASE properties, convergence strategies, and conflict resolution patterns for eventually consistent systems
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths: []
+related_skills:
+  - db-cap-theorem
+  - db-acid-properties
+stack_signals:
+  - postgresql
+  - mysql
+  - database
+keywords:
+  - eventual-consistency
+  - BASE
+  - conflict-resolution
+  - CRDTs
+  - last-write-wins
+  - convergence
+  - replication-lag
+metadata:
+  author: community
+  upstream: postgresql.org/docs/current/warm-standby.html
+state:
+  persistent: false
+  files: []
+depends_on: []