htm 0.0.10 → 0.0.14

data/db/migrate/00010_add_soft_delete_to_associations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class AddSoftDeleteToAssociations < ActiveRecord::Migration[7.0]
+  def change
+    # Add deleted_at to robot_nodes for soft delete support
+    unless column_exists?(:robot_nodes, :deleted_at)
+      add_column :robot_nodes, :deleted_at, :datetime, null: true
+    end
+    unless index_exists?(:robot_nodes, :deleted_at)
+      add_index :robot_nodes, :deleted_at
+    end
+
+    # Add deleted_at to node_tags for soft delete support
+    unless column_exists?(:node_tags, :deleted_at)
+      add_column :node_tags, :deleted_at, :datetime, null: true
+    end
+    unless index_exists?(:node_tags, :deleted_at)
+      add_index :node_tags, :deleted_at
+    end
+
+    # Add deleted_at to tags for soft delete support
+    unless column_exists?(:tags, :deleted_at)
+      add_column :tags, :deleted_at, :datetime, null: true
+    end
+    unless index_exists?(:tags, :deleted_at)
+      add_index :tags, :deleted_at
+    end
+  end
+end

data/db/migrate/00011_add_performance_indexes.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+class AddPerformanceIndexes < ActiveRecord::Migration[7.1]
+  def change
+    # Partial index for soft-delete filter (used in almost every query)
+    # This complements idx_nodes_not_deleted_created_at for queries that
+    # don't need created_at ordering but still filter by deleted_at IS NULL
+    add_index :nodes, :id,
+              name: 'idx_nodes_active',
+              where: 'deleted_at IS NULL',
+              comment: 'Partial index for active (non-deleted) node queries'
+
+    # Composite index for embedding-based searches on active nodes
+    # Helps vector_search and hybrid_search which filter by deleted_at IS NULL
+    # and embedding IS NOT NULL
+    execute <<-SQL
+      CREATE INDEX idx_nodes_active_with_embedding ON nodes (id)
+        WHERE deleted_at IS NULL AND embedding IS NOT NULL
+    SQL
+  end
+end

data/db/migrate/00012_add_tags_trigram_index.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class AddTagsTrigramIndex < ActiveRecord::Migration[7.0]
+  def up
+    # Add GIN trigram index on tags.name for fuzzy search
+    # Enables queries like: WHERE name % 'postgrsql' (typo-tolerant)
+    # Also speeds up LIKE '%pattern%' queries
+    execute <<~SQL
+      CREATE INDEX idx_tags_name_trgm ON tags USING gin(name gin_trgm_ops);
+    SQL
+  end
+
+  def down
+    execute <<~SQL
+      DROP INDEX IF EXISTS idx_tags_name_trgm;
+    SQL
+  end
+end

data/db/migrate/00013_enable_lz4_compression.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class EnableLz4Compression < ActiveRecord::Migration[7.0]
+  def up
+    # Switch TOAST compression from pglz to lz4 for better read performance
+    # LZ4 decompression is ~32% faster than pglz with only marginally lower compression ratio
+    # See: https://www.depesz.com/2025/11/29/using-json-json-vs-jsonb-pglz-vs-lz4-key-optimization-parsing-speed/
+
+    # nodes.metadata - JSONB column for flexible key-value storage
+    execute <<~SQL
+      ALTER TABLE nodes ALTER COLUMN metadata SET COMPRESSION lz4;
+    SQL
+
+    # nodes.content - TEXT column containing memory content
+    execute <<~SQL
+      ALTER TABLE nodes ALTER COLUMN content SET COMPRESSION lz4;
+    SQL
+
+    # file_sources.frontmatter - JSONB column for parsed YAML frontmatter
+    execute <<~SQL
+      ALTER TABLE file_sources ALTER COLUMN frontmatter SET COMPRESSION lz4;
+    SQL
+
+    # Note: Existing rows retain their original compression until rewritten.
+    # To recompress existing data, run: VACUUM FULL nodes; VACUUM FULL file_sources;
+    # This is optional and can be done during a maintenance window.
+  end
+
+  def down
+    # Revert to default pglz compression
+    execute <<~SQL
+      ALTER TABLE nodes ALTER COLUMN metadata SET COMPRESSION pglz;
+    SQL
+
+    execute <<~SQL
+      ALTER TABLE nodes ALTER COLUMN content SET COMPRESSION pglz;
+    SQL
+
+    execute <<~SQL
+      ALTER TABLE file_sources ALTER COLUMN frontmatter SET COMPRESSION pglz;
+    SQL
+  end
+end

data/db/schema.sql

@@ -38,6 +38,7 @@ CREATE TABLE public.file_sources (
     created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
 );
+ALTER TABLE ONLY public.file_sources ALTER COLUMN frontmatter SET COMPRESSION lz4;
 
 --
 -- Name: TABLE file_sources; Type: COMMENT; Schema: public; Owner: -
@@ -106,7 +107,8 @@ CREATE TABLE public.node_tags (
     id bigint NOT NULL,
     node_id bigint NOT NULL,
     tag_id bigint NOT NULL,
-    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
+    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    deleted_at timestamp(6) without time zone
 );
 
 --
@@ -171,6 +173,8 @@ CREATE TABLE public.nodes (
     metadata jsonb DEFAULT '{}'::jsonb NOT NULL,
     CONSTRAINT check_embedding_dimension CHECK (((embedding_dimension IS NULL) OR ((embedding_dimension > 0) AND (embedding_dimension <= 2000))))
 );
+ALTER TABLE ONLY public.nodes ALTER COLUMN content SET COMPRESSION lz4;
+ALTER TABLE ONLY public.nodes ALTER COLUMN metadata SET COMPRESSION lz4;
 
 --
 -- Name: TABLE nodes; Type: COMMENT; Schema: public; Owner: -
@@ -285,7 +289,9 @@ CREATE TABLE public.robot_nodes (
     last_remembered_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     remember_count integer DEFAULT 1 NOT NULL,
     created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
+    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    working_memory boolean DEFAULT false NOT NULL,
+    deleted_at timestamp(6) without time zone
 );
 
 --
@@ -324,6 +330,12 @@ COMMENT ON COLUMN public.robot_nodes.last_remembered_at IS 'When this robot last
 
 COMMENT ON COLUMN public.robot_nodes.remember_count IS 'Number of times this robot has tried to remember this content';
 
+--
+-- Name: COLUMN robot_nodes.working_memory; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.working_memory IS 'True if this node is currently in the robot working memory';
+
 --
 -- Name: robot_nodes_id_seq; Type: SEQUENCE; Schema: public; Owner: -
 --
@@ -408,7 +420,8 @@ CREATE TABLE public.schema_migrations (
 CREATE TABLE public.tags (
     id bigint NOT NULL,
     name text NOT NULL,
-    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
+    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    deleted_at timestamp(6) without time zone
 );
 
 --
@@ -446,65 +459,6 @@ CREATE SEQUENCE public.tags_id_seq
 
 ALTER SEQUENCE public.tags_id_seq OWNED BY public.tags.id;
 
---
--- Name: working_memories; Type: TABLE; Schema: public; Owner: -
---
-
-CREATE TABLE public.working_memories (
-    id bigint NOT NULL,
-    robot_id bigint NOT NULL,
-    node_id bigint NOT NULL,
-    added_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-    token_count integer
-);
-
---
--- Name: TABLE working_memories; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON TABLE public.working_memories IS 'Per-robot working memory state (optional persistence)';
-
---
--- Name: COLUMN working_memories.robot_id; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.working_memories.robot_id IS 'Robot whose working memory this belongs to';
-
---
--- Name: COLUMN working_memories.node_id; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.working_memories.node_id IS 'Node currently in working memory';
-
---
--- Name: COLUMN working_memories.added_at; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.working_memories.added_at IS 'When node was added to working memory';
-
---
--- Name: COLUMN working_memories.token_count; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.working_memories.token_count IS 'Cached token count for budget tracking';
-
---
--- Name: working_memories_id_seq; Type: SEQUENCE; Schema: public; Owner: -
---
-
-CREATE SEQUENCE public.working_memories_id_seq
-    START WITH 1
-    INCREMENT BY 1
-    NO MINVALUE
-    NO MAXVALUE
-    CACHE 1;
-
---
--- Name: working_memories_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: -
---
-
-ALTER SEQUENCE public.working_memories_id_seq OWNED BY public.working_memories.id;
-
 --
 -- Name: file_sources id; Type: DEFAULT; Schema: public; Owner: -
 --
@@ -541,12 +495,6 @@ ALTER TABLE ONLY public.robots ALTER COLUMN id SET DEFAULT nextval('public.robot
 
 ALTER TABLE ONLY public.tags ALTER COLUMN id SET DEFAULT nextval('public.tags_id_seq'::regclass);
 
---
--- Name: working_memories id; Type: DEFAULT; Schema: public; Owner: -
---
-
-ALTER TABLE ONLY public.working_memories ALTER COLUMN id SET DEFAULT nextval('public.working_memories_id_seq'::regclass);
-
 --
 -- Name: file_sources file_sources_pkey; Type: CONSTRAINT; Schema: public; Owner: -
 --
@@ -596,13 +544,6 @@ ALTER TABLE ONLY public.schema_migrations
 ALTER TABLE ONLY public.tags
     ADD CONSTRAINT tags_pkey PRIMARY KEY (id);
 
---
--- Name: working_memories working_memories_pkey; Type: CONSTRAINT; Schema: public; Owner: -
---
-
-ALTER TABLE ONLY public.working_memories
-    ADD CONSTRAINT working_memories_pkey PRIMARY KEY (id);
-
 --
 -- Name: idx_file_sources_hash; Type: INDEX; Schema: public; Owner: -
 --
@@ -645,6 +586,24 @@ CREATE UNIQUE INDEX idx_node_tags_unique ON public.node_tags USING btree (node_i
 
 CREATE INDEX idx_nodes_access_count ON public.nodes USING btree (access_count);
 
+--
+-- Name: idx_nodes_active; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_nodes_active ON public.nodes USING btree (id) WHERE (deleted_at IS NULL);
+
+--
+-- Name: INDEX idx_nodes_active; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON INDEX public.idx_nodes_active IS 'Partial index for active (non-deleted) node queries';
+
+--
+-- Name: idx_nodes_active_with_embedding; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_nodes_active_with_embedding ON public.nodes USING btree (id) WHERE ((deleted_at IS NULL) AND (embedding IS NOT NULL));
+
 --
 -- Name: idx_nodes_content_gin; Type: INDEX; Schema: public; Owner: -
 --
@@ -742,48 +701,46 @@ CREATE INDEX idx_robot_nodes_robot_id ON public.robot_nodes USING btree (robot_i
 CREATE UNIQUE INDEX idx_robot_nodes_unique ON public.robot_nodes USING btree (robot_id, node_id);
 
 --
--- Name: idx_tags_name_pattern; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_robot_nodes_working_memory; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_tags_name_pattern ON public.tags USING btree (name text_pattern_ops);
+CREATE INDEX idx_robot_nodes_working_memory ON public.robot_nodes USING btree (robot_id, working_memory) WHERE (working_memory = true);
 
 --
--- Name: idx_tags_name_unique; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_tags_name_pattern; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name);
+CREATE INDEX idx_tags_name_pattern ON public.tags USING btree (name text_pattern_ops);
 
 --
--- Name: idx_working_memories_node_id; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_tags_name_trgm; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_working_memories_node_id ON public.working_memories USING btree (node_id);
+CREATE INDEX idx_tags_name_trgm ON public.tags USING gin (name public.gin_trgm_ops);
 
 --
--- Name: idx_working_memories_robot_id; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_tags_name_unique; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_working_memories_robot_id ON public.working_memories USING btree (robot_id);
+CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name);
 
 --
--- Name: idx_working_memories_unique; Type: INDEX; Schema: public; Owner: -
+-- Name: index_node_tags_on_deleted_at; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE UNIQUE INDEX idx_working_memories_unique ON public.working_memories USING btree (robot_id, node_id);
+CREATE INDEX index_node_tags_on_deleted_at ON public.node_tags USING btree (deleted_at);
 
 --
--- Name: working_memories fk_rails_2c1d8b383c; Type: FK CONSTRAINT; Schema: public; Owner: -
+-- Name: index_robot_nodes_on_deleted_at; Type: INDEX; Schema: public; Owner: -
 --
 
-ALTER TABLE ONLY public.working_memories
-    ADD CONSTRAINT fk_rails_2c1d8b383c FOREIGN KEY (node_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
+CREATE INDEX index_robot_nodes_on_deleted_at ON public.robot_nodes USING btree (deleted_at);
 
 --
--- Name: working_memories fk_rails_4b7c3eb07b; Type: FK CONSTRAINT; Schema: public; Owner: -
+-- Name: index_tags_on_deleted_at; Type: INDEX; Schema: public; Owner: -
 --
 
-ALTER TABLE ONLY public.working_memories
-    ADD CONSTRAINT fk_rails_4b7c3eb07b FOREIGN KEY (robot_id) REFERENCES public.robots(id) ON DELETE CASCADE;
+CREATE INDEX index_tags_on_deleted_at ON public.tags USING btree (deleted_at);
 
 --
 -- Name: nodes fk_rails_920ad16d08; Type: FK CONSTRAINT; Schema: public; Owner: -
@@ -824,4 +781,4 @@ ALTER TABLE ONLY public.robot_nodes
 -- PostgreSQL database dump complete
 --
 
-\unrestrict DUrF24Zrve4qSBwlDrJ4qAzzZhvhX5s2S57oHYVJ0ZPbaDC4ItMZ29Pv9oI3Q9d
+\unrestrict bjkKIo8iBhvKUCAsIDDWdDnwALL0oxUsmZVbvgEad6ZmhcLmalGL4Ih7bfe9nlh

data/docs/api/index.md

@@ -1,6 +1,6 @@
 # API Reference
 
-Complete API documentation for HTM (Hierarchical Temporary Memory).
+Complete API documentation for HTM (Hierarchical Temporal Memory).
 
 ## Overview
 

data/docs/api/yard/HTM.md

@@ -2,7 +2,7 @@
 **Inherits:** Object
     
 
-HTM (Hierarchical Temporary Memory) error classes
+HTM (Hierarchical Temporal Memory) error classes
 
 All HTM errors inherit from HTM::Error, allowing you to catch all HTM-related
 errors with a single rescue clause.
@@ -75,6 +75,4 @@ Reset configuration to defaults
 ## configuration[RW] {: #attribute-c-configuration }
 Get current configuration
 
-**`@return`** [HTM::Configuration] 
-
-
+**`@return`** [HTM::Configuration]

data/docs/architecture/index.md

@@ -1,6 +1,6 @@
 # Architecture Overview
 
-HTM (Hierarchical Temporary Memory) implements a sophisticated two-tier memory system designed specifically for LLM-based applications ("robots"). This architecture enables robots to maintain long-term context across sessions while managing token budgets efficiently.
+HTM (Hierarchical Temporal Memory) implements a sophisticated two-tier memory system designed specifically for LLM-based applications ("robots"). This architecture enables robots to maintain long-term context across sessions while managing token budgets efficiently.
 
 ## System Overview
 

data/docs/development/index.md

@@ -4,7 +4,7 @@ Welcome to the HTM development documentation! This guide will help you contribut
 
 ## About HTM Development
 
-HTM (Hierarchical Temporary Memory) is an open-source Ruby gem that provides intelligent memory management for LLM-based applications. The project is built with modern Ruby practices, comprehensive testing, and a focus on developer experience.
+HTM (Hierarchical Temporal Memory) is an open-source Ruby gem that provides intelligent memory management for LLM-based applications. The project is built with modern Ruby practices, comprehensive testing, and a focus on developer experience.
 
 ### Project Values
 

data/docs/getting-started/index.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-Welcome to HTM (Hierarchical Temporary Memory)! This section will help you get up and running quickly.
+Welcome to HTM (Hierarchical Temporal Memory)! This section will help you get up and running quickly.
 
 ## Overview
 

data/docs/guides/index.md

@@ -1,6 +1,6 @@
 # HTM User Guides
 
-Welcome to the HTM (Hierarchical Temporary Memory) user guide collection. These guides will help you understand and effectively use HTM for building intelligent LLM-based applications with persistent memory.
+Welcome to the HTM (Hierarchical Temporal Memory) user guide collection. These guides will help you understand and effectively use HTM for building intelligent LLM-based applications with persistent memory.
 
 ## What is HTM?
 

data/docs/images/telemetry-architecture.svg

@@ -0,0 +1,153 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 500" style="background: transparent;">
+  <defs>
+    <!-- Gradients for visual depth -->
+    <linearGradient id="appGradient" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#3b82f6;stop-opacity:0.9"/>
+      <stop offset="100%" style="stop-color:#1d4ed8;stop-opacity:0.9"/>
+    </linearGradient>
+    <linearGradient id="telemetryGradient" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#8b5cf6;stop-opacity:0.9"/>
+      <stop offset="100%" style="stop-color:#6d28d9;stop-opacity:0.9"/>
+    </linearGradient>
+    <linearGradient id="nullGradient" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#6b7280;stop-opacity:0.8"/>
+      <stop offset="100%" style="stop-color:#4b5563;stop-opacity:0.8"/>
+    </linearGradient>
+    <linearGradient id="sdkGradient" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#10b981;stop-opacity:0.9"/>
+      <stop offset="100%" style="stop-color:#059669;stop-opacity:0.9"/>
+    </linearGradient>
+    <linearGradient id="backendGradient" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#f59e0b;stop-opacity:0.9"/>
+      <stop offset="100%" style="stop-color:#d97706;stop-opacity:0.9"/>
+    </linearGradient>
+
+    <!-- Arrow marker -->
+    <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#94a3b8"/>
+    </marker>
+    <marker id="arrowheadGreen" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+      <polygon points="0 0, 10 3.5, 0 7" fill="#10b981"/>
+    </marker>
+  </defs>
+
+  <!-- HTM Application Container -->
+  <rect x="50" y="30" width="700" height="280" rx="12" ry="12"
+        fill="none" stroke="#3b82f6" stroke-width="2" stroke-dasharray="5,5"/>
+  <text x="400" y="55" text-anchor="middle" fill="#e2e8f0" font-family="system-ui, sans-serif" font-size="16" font-weight="600">
+    HTM Application
+  </text>
+
+  <!-- Job boxes at top -->
+  <rect x="80" y="75" width="180" height="50" rx="8" ry="8" fill="url(#appGradient)"/>
+  <text x="170" y="105" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="13" font-weight="500">
+    GenerateEmbeddingJob
+  </text>
+
+  <rect x="310" y="75" width="180" height="50" rx="8" ry="8" fill="url(#appGradient)"/>
+  <text x="400" y="105" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="13" font-weight="500">
+    GenerateTagsJob
+  </text>
+
+  <rect x="540" y="75" width="180" height="50" rx="8" ry="8" fill="url(#appGradient)"/>
+  <text x="630" y="105" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="13" font-weight="500">
+    Search Methods
+  </text>
+
+  <!-- Arrows from jobs to telemetry -->
+  <line x1="170" y1="125" x2="170" y2="155" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+  <line x1="400" y1="125" x2="400" y2="155" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+  <line x1="630" y1="125" x2="630" y2="155" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- Horizontal connector line -->
+  <line x1="170" y1="155" x2="630" y2="155" stroke="#94a3b8" stroke-width="2"/>
+  <line x1="400" y1="155" x2="400" y2="170" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- HTM::Telemetry box -->
+  <rect x="280" y="175" width="240" height="45" rx="8" ry="8" fill="url(#telemetryGradient)"/>
+  <text x="400" y="203" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="14" font-weight="600">
+    HTM::Telemetry
+  </text>
+
+  <!-- Three branches from telemetry -->
+  <line x1="400" y1="220" x2="400" y2="240" stroke="#94a3b8" stroke-width="2"/>
+
+  <!-- Branch lines -->
+  <line x1="150" y1="240" x2="650" y2="240" stroke="#94a3b8" stroke-width="2"/>
+  <line x1="150" y1="240" x2="150" y2="255" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+  <line x1="400" y1="240" x2="400" y2="255" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+  <line x1="650" y1="240" x2="650" y2="255" stroke="#94a3b8" stroke-width="2" marker-end="url(#arrowhead)"/>
+
+  <!-- Three meter options -->
+  <rect x="70" y="260" width="160" height="55" rx="8" ry="8" fill="url(#nullGradient)"/>
+  <text x="150" y="283" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="12" font-weight="500">
+    NullMeter
+  </text>
+  <text x="150" y="300" text-anchor="middle" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="10">
+    (when disabled)
+  </text>
+
+  <rect x="320" y="260" width="160" height="55" rx="8" ry="8" fill="url(#sdkGradient)"/>
+  <text x="400" y="283" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="12" font-weight="500">
+    OpenTelemetry
+  </text>
+  <text x="400" y="300" text-anchor="middle" fill="#d1fae5" font-family="system-ui, sans-serif" font-size="10">
+    SDK Meter
+  </text>
+
+  <rect x="570" y="260" width="160" height="55" rx="8" ry="8" fill="url(#nullGradient)"/>
+  <text x="650" y="283" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="12" font-weight="500">
+    NullMeter
+  </text>
+  <text x="650" y="300" text-anchor="middle" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="10">
+    (SDK missing)
+  </text>
+
+  <!-- Arrows to outcomes -->
+  <line x1="150" y1="315" x2="150" y2="345" stroke="#6b7280" stroke-width="2" stroke-dasharray="4,4"/>
+  <line x1="400" y1="315" x2="400" y2="345" stroke="#10b981" stroke-width="2" marker-end="url(#arrowheadGreen)"/>
+  <line x1="650" y1="315" x2="650" y2="345" stroke="#6b7280" stroke-width="2" stroke-dasharray="4,4"/>
+
+  <!-- Outcome labels -->
+  <text x="150" y="365" text-anchor="middle" fill="#9ca3af" font-family="system-ui, sans-serif" font-size="12" font-style="italic">
+    No-op
+  </text>
+
+  <text x="400" y="365" text-anchor="middle" fill="#10b981" font-family="system-ui, sans-serif" font-size="12" font-weight="500">
+    OTLP Export
+  </text>
+
+  <text x="650" y="365" text-anchor="middle" fill="#9ca3af" font-family="system-ui, sans-serif" font-size="12" font-style="italic">
+    No-op
+  </text>
+
+  <!-- Arrow to backend -->
+  <line x1="400" y1="380" x2="400" y2="410" stroke="#10b981" stroke-width="2" marker-end="url(#arrowheadGreen)"/>
+
+  <!-- Backend box -->
+  <rect x="250" y="420" width="300" height="60" rx="10" ry="10" fill="url(#backendGradient)"/>
+  <text x="400" y="448" text-anchor="middle" fill="#ffffff" font-family="system-ui, sans-serif" font-size="14" font-weight="600">
+    Observability Backend
+  </text>
+  <text x="400" y="468" text-anchor="middle" fill="#fef3c7" font-family="system-ui, sans-serif" font-size="11">
+    (Jaeger, Datadog, Prometheus, etc.)
+  </text>
+
+  <!-- Legend -->
+  <rect x="600" y="380" width="140" height="80" rx="6" ry="6" fill="#1e293b" fill-opacity="0.7" stroke="#475569" stroke-width="1"/>
+  <text x="670" y="398" text-anchor="middle" fill="#94a3b8" font-family="system-ui, sans-serif" font-size="10" font-weight="600">
+    LEGEND
+  </text>
+  <line x1="615" y1="410" x2="645" y2="410" stroke="#10b981" stroke-width="2"/>
+  <text x="720" y="414" text-anchor="end" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="10">
+    Active flow
+  </text>
+  <line x1="615" y1="430" x2="645" y2="430" stroke="#6b7280" stroke-width="2" stroke-dasharray="4,4"/>
+  <text x="720" y="434" text-anchor="end" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="10">
+    Disabled path
+  </text>
+  <circle cx="630" cy="450" r="6" fill="url(#telemetryGradient)"/>
+  <text x="720" y="454" text-anchor="end" fill="#d1d5db" font-family="system-ui, sans-serif" font-size="10">
+    HTM component
+  </text>
+</svg>