metka 2.3.3 → 3.0.0

data/benchmark/results.sqlite.txt

@@ -0,0 +1,131 @@
+Seeding 10000 posts per gem, 5 tags each, vocabulary of 100 tags
+
+Bulk seed wall time (10000 posts):
+  metka                            0.10 s
+  metka (table)                    0.08 s
+  metka (index)                    0.10 s
+  acts-as-taggable-on             31.43 s
+  gutentag                        35.30 s
+
+Storage (tables + indexes) for 10000 posts:
+  metka                            0.62 MB
+  metka (table)                    0.63 MB
+  acts-as-taggable-on             12.53 MB
+  gutentag                         7.20 MB
+  metka (index)                    1.39 MB
+
+========================================================================
+QUERY: tagged with ALL of 2 tags -> load records (~25 rows)
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+               metka    47.000 i/100ms
+       metka (index)   715.000 i/100ms
+ acts-as-taggable-on   326.000 i/100ms
+            gutentag   197.000 i/100ms
+Calculating -------------------------------------
+               metka    398.137 (± 2.3%) i/s    (2.51 ms/i) -      2.021k in   5.076143s
+       metka (index)      7.199k (± 2.9%) i/s  (138.90 μs/i) -     36.465k in   5.064972s
+ acts-as-taggable-on      3.189k (± 3.3%) i/s  (313.59 μs/i) -     15.974k in   5.009333s
+            gutentag      1.965k (± 4.4%) i/s  (508.87 μs/i) -      9.850k in   5.012329s
+
+Comparison:
+      metka (index):     7199.4 i/s
+acts-as-taggable-on:     3188.8 i/s - 2.26x  slower
+           gutentag:     1965.2 i/s - 3.66x  slower
+              metka:      398.1 i/s - 18.08x  slower
+
+========================================================================
+QUERY: tagged with ANY of 2 tags -> count
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+               metka    38.000 i/100ms
+       metka (index)   397.000 i/100ms
+ acts-as-taggable-on    41.000 i/100ms
+            gutentag   199.000 i/100ms
+Calculating -------------------------------------
+               metka    379.318 (± 2.1%) i/s    (2.64 ms/i) -      1.900k in   5.008996s
+       metka (index)      4.113k (± 3.7%) i/s  (243.13 μs/i) -     20.644k in   5.019114s
+ acts-as-taggable-on    410.036 (± 2.4%) i/s    (2.44 ms/i) -      2.091k in   5.099553s
+            gutentag      1.900k (± 6.4%) i/s  (526.34 μs/i) -      9.552k in   5.027612s
+
+Comparison:
+      metka (index):     4113.1 i/s
+           gutentag:     1899.9 i/s - 2.16x  slower
+acts-as-taggable-on:      410.0 i/s - 10.03x  slower
+              metka:      379.3 i/s - 10.84x  slower
+
+========================================================================
+TAG CLOUD: tag -> usage count across all 10000 posts
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+               metka    11.000 i/100ms
+       metka (table)     1.275k i/100ms
+ acts-as-taggable-on    11.000 i/100ms
+            gutentag     8.000 i/100ms
+Calculating -------------------------------------
+               metka    110.804 (± 2.7%) i/s    (9.02 ms/i) -    561.000 in   5.062986s
+       metka (table)     12.696k (± 2.2%) i/s   (78.76 μs/i) -     63.750k in   5.021086s
+ acts-as-taggable-on    110.668 (± 3.6%) i/s    (9.04 ms/i) -    561.000 in   5.069223s
+            gutentag     87.688 (± 2.3%) i/s   (11.40 ms/i) -    440.000 in   5.017818s
+
+Comparison:
+      metka (table):    12696.5 i/s
+              metka:      110.8 i/s - 114.58x  slower
+acts-as-taggable-on:      110.7 i/s - 114.73x  slower
+           gutentag:       87.7 i/s - 144.79x  slower
+
+========================================================================
+WRITE: create one post with 5 tags
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+               metka   776.000 i/100ms
+       metka (table)   683.000 i/100ms
+       metka (index)   522.000 i/100ms
+ acts-as-taggable-on    27.000 i/100ms
+            gutentag    28.000 i/100ms
+Calculating -------------------------------------
+               metka      7.783k (± 3.7%) i/s  (128.48 μs/i) -     39.576k in   5.084760s
+       metka (table)      6.895k (± 4.4%) i/s  (145.04 μs/i) -     34.833k in   5.052142s
+       metka (index)      5.349k (± 5.0%) i/s  (186.96 μs/i) -     27.144k in   5.074779s
+ acts-as-taggable-on    268.380 (± 5.2%) i/s    (3.73 ms/i) -      1.350k in   5.030173s
+            gutentag    284.410 (± 6.3%) i/s    (3.52 ms/i) -      1.428k in   5.020920s
+
+Comparison:
+              metka:     7783.3 i/s
+      metka (table):     6894.7 i/s - 1.13x  slower
+      metka (index):     5348.8 i/s - 1.46x  slower
+           gutentag:      284.4 i/s - 27.37x  slower
+acts-as-taggable-on:      268.4 i/s - 29.00x  slower
+
+========================================================================
+WRITE: replace the tag list of an existing post
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+               metka     1.199k i/100ms
+       metka (table)     1.200k i/100ms
+       metka (index)     1.196k i/100ms
+ acts-as-taggable-on    19.000 i/100ms
+            gutentag    19.000 i/100ms
+Calculating -------------------------------------
+               metka     12.670k (± 4.2%) i/s   (78.93 μs/i) -     63.547k in   5.015591s
+       metka (table)     12.604k (± 4.1%) i/s   (79.34 μs/i) -     63.600k in   5.045863s
+       metka (index)     12.696k (± 2.7%) i/s   (78.77 μs/i) -     64.584k in   5.087111s
+ acts-as-taggable-on    416.435 (±90.3%) i/s    (2.40 ms/i) -      2.090k in   5.018792s
+            gutentag    808.708 (± Inf%) i/s    (1.24 ms/i) -      4.047k in   5.004277s
+
+Comparison:
+      metka (index):    12695.6 i/s
+              metka:    12669.9 i/s - same-ish: difference falls within error
+      metka (table):    12604.4 i/s - same-ish: difference falls within error
+           gutentag:      808.7 i/s - 15.70x  slower
+acts-as-taggable-on:      416.4 i/s - 30.49x  slower
+
+
+Strategy integrity after all suites (0 = aggregate matches a live aggregation):
+  table mismatching tags: 0
+  index mismatching pairs: 0

data/benchmark/results.txt

@@ -0,0 +1,150 @@
+Seeding 10000 posts per gem, 5 tags each, vocabulary of 100 tags
+
+Bulk seed wall time (10000 posts):
+  metka                            0.21 s
+  metka (table)                    0.17 s
+  acts-as-taggable-array-on        0.17 s
+  tag_columns                      0.16 s
+  acts-as-taggable-on             45.57 s
+  gutentag                        50.24 s
+
+Storage (tables + indexes) for 10000 posts:
+  metka                            2.68 MB
+  metka (table)                    2.75 MB
+  acts-as-taggable-array-on        2.68 MB
+  tag_columns                      2.68 MB
+  acts-as-taggable-on             18.17 MB
+  gutentag                        10.97 MB
+
+========================================================================
+QUERY: tagged with ALL of 2 tags -> load records (~25 rows)
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+                    metka   597.000 i/100ms
+acts-as-taggable-array-on   757.000 i/100ms
+              tag_columns   101.000 i/100ms
+      acts-as-taggable-on   213.000 i/100ms
+                 gutentag   124.000 i/100ms
+Calculating -------------------------------------
+                    metka      6.003k (± 8.2%) i/s  (166.59 μs/i) -     30.447k in   5.072240s
+acts-as-taggable-array-on      6.725k (± 8.6%) i/s  (148.69 μs/i) -     34.065k in   5.065229s
+              tag_columns    985.914 (± 3.1%) i/s    (1.01 ms/i) -      4.949k in   5.019708s
+      acts-as-taggable-on      2.292k (± 6.7%) i/s  (436.38 μs/i) -     11.502k in   5.019218s
+                 gutentag      1.299k (± 8.8%) i/s  (769.73 μs/i) -      6.572k in   5.058649s
+
+Comparison:
+acts-as-taggable-array-on:     6725.3 i/s
+                    metka:     6002.7 i/s - same-ish: difference falls within error
+      acts-as-taggable-on:     2291.6 i/s - 2.93x  slower
+                 gutentag:     1299.2 i/s - 5.18x  slower
+              tag_columns:      985.9 i/s - 6.82x  slower
+
+========================================================================
+QUERY: tagged with ANY of 2 tags -> count
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+                    metka   421.000 i/100ms
+acts-as-taggable-array-on   466.000 i/100ms
+              tag_columns    66.000 i/100ms
+      acts-as-taggable-on    74.000 i/100ms
+                 gutentag   106.000 i/100ms
+Calculating -------------------------------------
+                    metka      4.575k (±10.3%) i/s  (218.60 μs/i) -     23.155k in   5.061751s
+acts-as-taggable-array-on      4.479k (±12.4%) i/s  (223.24 μs/i) -     22.834k in   5.097452s
+              tag_columns    678.434 (± 2.7%) i/s    (1.47 ms/i) -      3.432k in   5.058707s
+      acts-as-taggable-on    788.456 (± 2.7%) i/s    (1.27 ms/i) -      3.996k in   5.068134s
+                 gutentag      1.027k (± 7.5%) i/s  (973.91 μs/i) -      5.194k in   5.058492s
+
+Comparison:
+                    metka:     4574.5 i/s
+acts-as-taggable-array-on:     4479.5 i/s - same-ish: difference falls within error
+                 gutentag:     1026.8 i/s - 4.46x  slower
+      acts-as-taggable-on:      788.5 i/s - 5.80x  slower
+              tag_columns:      678.4 i/s - 6.74x  slower
+
+========================================================================
+TAG CLOUD: tag -> usage count across all 10000 posts
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+                    metka    21.000 i/100ms
+            metka (table)   986.000 i/100ms
+acts-as-taggable-array-on    20.000 i/100ms
+              tag_columns    19.000 i/100ms
+      acts-as-taggable-on    12.000 i/100ms
+                 gutentag    16.000 i/100ms
+Calculating -------------------------------------
+                    metka    212.110 (± 2.8%) i/s    (4.71 ms/i) -      1.071k in   5.049256s
+            metka (table)      9.025k (± 4.6%) i/s  (110.81 μs/i) -     45.356k in   5.025682s
+acts-as-taggable-array-on    203.695 (± 2.0%) i/s    (4.91 ms/i) -      1.020k in   5.007496s
+              tag_columns    197.664 (± 2.0%) i/s    (5.06 ms/i) -      1.007k in   5.094517s
+      acts-as-taggable-on    127.192 (± 3.1%) i/s    (7.86 ms/i) -    648.000 in   5.094650s
+                 gutentag    161.495 (± 3.1%) i/s    (6.19 ms/i) -    816.000 in   5.052782s
+
+Comparison:
+            metka (table):     9024.8 i/s
+                    metka:      212.1 i/s - 42.55x  slower
+acts-as-taggable-array-on:      203.7 i/s - 44.31x  slower
+              tag_columns:      197.7 i/s - 45.66x  slower
+                 gutentag:      161.5 i/s - 55.88x  slower
+      acts-as-taggable-on:      127.2 i/s - 70.95x  slower
+
+========================================================================
+WRITE: create one post with 5 tags
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+                    metka   176.000 i/100ms
+            metka (table)   156.000 i/100ms
+acts-as-taggable-array-on   154.000 i/100ms
+              tag_columns   157.000 i/100ms
+      acts-as-taggable-on    19.000 i/100ms
+                 gutentag    18.000 i/100ms
+Calculating -------------------------------------
+                    metka      1.619k (± 6.9%) i/s  (617.73 μs/i) -      8.096k in   5.001165s
+            metka (table)      1.495k (± 5.8%) i/s  (668.77 μs/i) -      7.488k in   5.007742s
+acts-as-taggable-array-on      1.633k (± 5.8%) i/s  (612.19 μs/i) -      8.316k in   5.090931s
+              tag_columns      1.599k (± 7.7%) i/s  (625.58 μs/i) -      8.007k in   5.009026s
+      acts-as-taggable-on    203.548 (± 9.3%) i/s    (4.91 ms/i) -      1.026k in   5.040586s
+                 gutentag    196.158 (±11.7%) i/s    (5.10 ms/i) -    990.000 in   5.046963s
+
+Comparison:
+acts-as-taggable-array-on:     1633.5 i/s
+                    metka:     1618.8 i/s - same-ish: difference falls within error
+              tag_columns:     1598.5 i/s - same-ish: difference falls within error
+            metka (table):     1495.3 i/s - same-ish: difference falls within error
+      acts-as-taggable-on:      203.5 i/s - 8.03x  slower
+                 gutentag:      196.2 i/s - 8.33x  slower
+
+========================================================================
+WRITE: replace the tag list of an existing post
+========================================================================
+ruby 4.0.6 (2026-07-14 revision 03b6d3f889) +PRISM [x86_64-linux]
+Warming up --------------------------------------
+                    metka   140.000 i/100ms
+            metka (table)   121.000 i/100ms
+acts-as-taggable-array-on   145.000 i/100ms
+              tag_columns   147.000 i/100ms
+      acts-as-taggable-on    13.000 i/100ms
+                 gutentag    11.000 i/100ms
+Calculating -------------------------------------
+                    metka      8.293k (± 9.2%) i/s  (120.58 μs/i) -     41.580k in   5.013907s
+            metka (table)      8.131k (± 9.6%) i/s  (122.98 μs/i) -     40.656k in   4.999930s
+acts-as-taggable-array-on      7.766k (± 9.6%) i/s  (128.77 μs/i) -     38.860k in   5.003909s
+              tag_columns      7.396k (± 8.2%) i/s  (135.22 μs/i) -     37.044k in   5.008958s
+      acts-as-taggable-on    189.648 (± Inf%) i/s    (5.27 ms/i) -    962.000 in   5.072563s
+                 gutentag    182.869 (± Inf%) i/s    (5.47 ms/i) -    924.000 in   5.052787s
+
+Comparison:
+                    metka:     8292.9 i/s
+            metka (table):     8131.3 i/s - same-ish: difference falls within error
+acts-as-taggable-array-on:     7765.9 i/s - same-ish: difference falls within error
+              tag_columns:     7395.6 i/s - same-ish: difference falls within error
+      acts-as-taggable-on:      189.6 i/s - 43.73x  slower
+                 gutentag:      182.9 i/s - 45.35x  slower
+
+
+Strategy integrity after all suites (0 = aggregate matches a live UNNEST..GROUP BY):
+  table mismatching tags: 0

data/bin/setup

@@ -6,3 +6,10 @@ gem install bundler --conservative
 bundle check || bundle install
 
 RAILS_ENV=test bundle exec rake dummy:db:migrate:reset
+
+# SQLite resets by deleting the file, not through db:migrate:reset: the rake
+# composite drops the file while the booted app still holds an open handle, so
+# the migrations land on the unlinked inode and vanish when the process exits.
+# A fresh process migrating into a fresh file has no such problem.
+rm -f test/dummy/db/metka_test.sqlite3
+DB=sqlite RAILS_ENV=test bundle exec rake dummy:db:migrate

data/docs/superpowers/plans/2026-08-18-cloud-table-naming.md

@@ -0,0 +1,316 @@
+# Cloud Table Naming Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Rename the table-strategy generator's derived summary-table name from `tagged_<source_table>` to `<source_table>_<columns>_cloud` (e.g. `songs_tags_cloud`), matching the index strategy's `<source_table>_<column>_index` pattern.
+
+**Architecture:** One code change — the `table_name` derivation in the table generator. The ERB migration templates interpolate `<%= table_name %>` everywhere, so they need no changes. Everything else is fixtures and docs modeling the new convention: generator tests, the dummy app's hand-written equivalent migration/model/test, the README, and the benchmark.
+
+**Tech Stack:** Ruby gem (metka), Rails generators, Minitest, dummy Rails app under `test/dummy` running on PostgreSQL or SQLite (`DB=sqlite` env var switches the adapter).
+
+**Spec:** `docs/superpowers/specs/2026-08-18-cloud-table-naming-design.md`
+
+**Reference — the naming rule:** derived name is `#{source_table_name}_#{source_columns.join("_and_")}_cloud`, uniformly. No special case for the default `tags` column. `--table-name` still overrides. Migration name stays `create_#{table_name}_table`.
+
+**Reference — what does NOT change:** trigger names (`metka_ins_on_<source_table>_<columns>` — derived from the source table), the `tag_name`/`taggings_count` columns, both ERB templates, all runtime code in `lib/metka/`, and the historical benchmark results files (`benchmark/results*.txt` are recorded outputs of past runs — leave them).
+
+**Test environment setup (once, before Task 1):**
+
+```bash
+cd /home/igor/Work/metka/.claude/worktrees/tagging-table-naming-5cd0c9
+bundle install
+rm -f test/dummy/db/*.sqlite3 test/dummy/db/schema.rb
+RAILS_ENV=test DB=sqlite bundle exec rake dummy:db:migrate
+```
+
+Always prefix rake/test commands with `RAILS_ENV=test` — the dummy app only configures the `test` environment. Do NOT use `dummy:db:migrate:reset` under SQLite: locally it leaves an empty database and dumps a stale empty `schema.rb` that then makes `maintain_test_schema` wipe the DB on test boot (CI's SQLite job uses plain `dummy:db:migrate` for the same reason). To reset, delete the `.sqlite3` file and any `test/dummy/db/schema.rb`, then `dummy:db:migrate`.
+
+SQLite always works locally. PostgreSQL runs the other template branch; if a local server is available (`psql -h localhost -U postgres -c 'select 1'` succeeds), also run the PG variants of each verification step (`bundle exec rake dummy:db:create dummy:db:migrate:reset`, no `DB` env var). If PG is unavailable, say so in the final report — CI runs both.
+
+---
+
+### Task 1: Generator derivation (TDD)
+
+**Files:**
+- Modify: `test/generators/strategies/table_generator_test.rb`
+- Modify: `lib/generators/metka/strategies/table/table_generator.rb:62-67`
+
+- [ ] **Step 1: Update the generator test's expected names**
+
+In `test/generators/strategies/table_generator_test.rb`:
+
+1. Change the migration constant (line 8):
+
+```ruby
+  MIGRATION = "db/migrate/create_notes_tags_cloud_table.rb"
+```
+
+2. Replace every `tagged_notes` in the assertion regexes with `notes_tags_cloud`. That is exactly these lines: 24 (`CREATE TABLE`), 28 (`INSERT INTO ... (tag_name, taggings_count)`), 44 (`DROP TABLE IF EXISTS`), 73 (`INSERT INTO` inside the lock-ordering test), 80–82 (`CREATE OR REPLACE FUNCTION metka_ins/upd/del_notes_tags_cloud`), 93–95 (`DROP FUNCTION IF EXISTS metka_ins/upd/del_notes_tags_cloud`). Do NOT touch the trigger-name assertions (lines 32–34, 38–40, `metka_ins_on_notes` etc.) — trigger names derive from the source table and stay the same.
+
+3. Add two new tests at the end of the class (before the closing `end`, after the `if SQLITE`/`else` block), covering the multi-column derivation and the override — both previously untested:
+
+```ruby
+  test "derives the name from the source columns when given" do
+    prepare_destination
+    run_generator [ "--source-table-name=notes", "--source-columns=tags", "genres" ]
+
+    assert_migration "db/migrate/create_notes_tags_and_genres_cloud_table.rb",
+      /CREATE TABLE notes_tags_and_genres_cloud/i
+  end
+
+  test "respects an explicit --table-name" do
+    prepare_destination
+    run_generator [ "--source-table-name=notes", "--table-name=note_cloud" ]
+
+    assert_migration "db/migrate/create_note_cloud_table.rb", /CREATE TABLE note_cloud/i
+  end
+```
+
+- [ ] **Step 2: Run the generator tests to verify they fail**
+
+```bash
+DB=sqlite bundle exec ruby -Itest test/generators/strategies/table_generator_test.rb
+```
+
+Expected: FAIL — every test errors or fails because the generator still emits `db/migrate/*_create_tagged_notes_table.rb`, so `assert_migration "db/migrate/create_notes_tags_cloud_table.rb"` finds no migration.
+
+- [ ] **Step 3: Change the derivation**
+
+In `lib/generators/metka/strategies/table/table_generator.rb`, replace the `table_name` method (lines 62–67):
+
+```ruby
+          def table_name
+            return options[:table_name] if options[:table_name]
+
+            "#{source_table_name}_#{source_columns_names}_cloud"
+          end
+```
+
+(The `columns_sequence` local and its default-columns special case disappear entirely; `source_columns_names` already joins with `_and_`.)
+
+Also update the generator's `desc` LONGDESC if it mentions the derived name — it currently doesn't (it only shows the flags), so no change expected there; just confirm.
+
+- [ ] **Step 4: Run the generator tests to verify they pass**
+
+```bash
+DB=sqlite bundle exec ruby -Itest test/generators/strategies/table_generator_test.rb
+```
+
+Expected: PASS (SQLite runs 11 tests after the two added in Step 1). If PostgreSQL is available, also run without `DB=sqlite` — it exercises the PG branch (function-name assertions): PASS, 13 tests.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/generators/metka/strategies/table/table_generator.rb test/generators/strategies/table_generator_test.rb
+git commit -m "feat(generator): Derive cloud table name as <source>_<columns>_cloud
+
+The table strategy summary table default changes from
+tagged_<source_table> to <source_table>_<columns>_cloud
+(songs_tags_cloud), mirroring the index strategy's
+<source_table>_<column>_index naming. Generation-time only:
+existing installs keep their tagged_* tables; --table-name
+still overrides.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 2: Dummy app models the new convention
+
+**Files:**
+- Rename: `test/dummy/db/migrate/11_create_tagged_table_posts_table.rb` → `test/dummy/db/migrate/11_create_table_posts_tags_cloud_table.rb`
+- Rename: `test/dummy/app/models/tagged_table_post.rb` → `test/dummy/app/models/table_posts_tags_cloud.rb`
+- Rename: `test/metka/tagged_table_post_test.rb` → `test/metka/table_posts_tags_cloud_test.rb`
+
+The dummy source table is `table_posts` (migration 10), so the new summary table name is `table_posts_tags_cloud`.
+
+- [ ] **Step 1: Rename and edit the dummy migration**
+
+```bash
+git mv test/dummy/db/migrate/11_create_tagged_table_posts_table.rb test/dummy/db/migrate/11_create_table_posts_tags_cloud_table.rb
+```
+
+Then in the renamed file:
+- Class name: `CreateTaggedTablePostsTable` → `CreateTablePostsTagsCloudTable` (must match the new filename or Rails raises on migrate).
+- Replace all `tagged_table_posts` → `table_posts_tags_cloud` (both the SQLite and PostgreSQL branches: CREATE TABLE, INSERT INTO, UPDATE, DELETE FROM, DROP TABLE, and the PG function names `metka_ins/upd/del_tagged_table_posts` → `metka_ins/upd/del_table_posts_tags_cloud`, including the `DROP FUNCTION IF EXISTS` lines).
+- Leave trigger names (`metka_*_on_table_posts*`) untouched.
+
+Sanity check — this file must end up matching what the updated generator emits. After editing, verify with:
+
+```bash
+grep -c "tagged" test/dummy/db/migrate/11_create_table_posts_tags_cloud_table.rb
+```
+
+Expected: `0`.
+
+- [ ] **Step 2: Rename and edit the dummy model**
+
+```bash
+git mv test/dummy/app/models/tagged_table_post.rb test/dummy/app/models/table_posts_tags_cloud.rb
+```
+
+New content (the explicit `table_name` is required — Rails infers the plural `table_posts_tags_clouds` from the class name):
+
+```ruby
+# frozen_string_literal: true
+
+class TablePostsTagsCloud < ActiveRecord::Base
+  self.table_name = "table_posts_tags_cloud"
+end
+```
+
+- [ ] **Step 3: Rename and edit the test**
+
+```bash
+git mv test/metka/tagged_table_post_test.rb test/metka/table_posts_tags_cloud_test.rb
+```
+
+In the renamed file: class `TaggedTablePostTest` → `TablePostsTagsCloudTest`, and every `TaggedTablePost` constant reference → `TablePostsTagsCloud` (10 lines contain it, including the class name; `grep -n TaggedTablePost` afterwards must return nothing). Everything else (fixtures, `TablePost` writes, trigger assertions) stays.
+
+- [ ] **Step 4: Recreate the dummy DB and run the suite**
+
+```bash
+rm -f test/dummy/db/*.sqlite3 test/dummy/db/schema.rb
+RAILS_ENV=test DB=sqlite bundle exec rake dummy:db:migrate
+RAILS_ENV=test DB=sqlite bundle exec ruby -Itest test/metka/table_posts_tags_cloud_test.rb
+```
+
+Expected: migration succeeds (the renamed migration runs under its new class name); test PASS. If PostgreSQL is available, repeat with `bundle exec rake dummy:db:migrate:reset` / the test command without `DB=sqlite`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A test/dummy test/metka/table_posts_tags_cloud_test.rb
+git commit -m "test(dummy): Rename summary table fixtures to table_posts_tags_cloud
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 3: README
+
+**Files:**
+- Modify: `README.md` (table-strategy section, ~lines 336–410)
+
+- [ ] **Step 1: Update the derived-name examples and model example**
+
+Exact edits (line numbers as of commit 281f0ea):
+
+1. Line 345 — the migration-template link: `test/dummy/db/migrate/11_create_tagged_table_posts_table.rb` → `test/dummy/db/migrate/11_create_table_posts_tags_cloud_table.rb` (both the link target and any visible filename).
+2. Line 347: `the resulting `tagged_notes` table` → `the resulting `notes_tags_cloud` table`.
+3. Line 357 — replace the model sentence with one that carries the pluralization gotcha:
+
+```markdown
+And you can also create a model to work with the table as with a Rails model — set the table name explicitly, since Rails would infer the plural `notes_tags_clouds` from the class name:
+
+```ruby
+class NotesTagsCloud < ApplicationRecord
+  self.table_name = "notes_tags_cloud"
+end
+```
+```
+
+4. Lines 378–385 — the `TaggedSong` model example in "Migrating from on-the-fly tag clouds". This is not a plain rename: like item 3, the new class name needs an explicit table name. Replace the code block and the sentence after it:
+
+```markdown
+```ruby
+class SongsTagsCloud < ActiveRecord::Base
+  self.table_name = "songs_tags_cloud"
+end
+
+Song.tag_cloud                                     # before
+SongsTagsCloud.pluck(:tag_name, :taggings_count)   # after
+```
+
+Sorting and limiting that used to happen in Ruby becomes a normal query: `SongsTagsCloud.order(taggings_count: :desc).limit(50)`.
+```
+
+5. Lines 392–406 (the reseeding SQL in the same section): every `tagged_songs` → `songs_tags_cloud` (4 occurrences: two `DELETE FROM`, two `INSERT INTO`). Read the surrounding prose of that section and update any other derived-name mentions to match.
+
+- [ ] **Step 2: Verify no stale names remain**
+
+```bash
+grep -n "tagged_notes\|tagged_songs\|tagged_table_posts\|TaggedNote\|TaggedTablePost\|TaggedSong" README.md
+```
+
+Expected: no output. (`tagged_with` and prose like "tagged columns" are unrelated and must remain.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: Document <source>_<columns>_cloud naming in README
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 4: Benchmark
+
+**Files:**
+- Modify: `benchmark/benchmark.rb`
+
+- [ ] **Step 1: Rename the benchmark's table-strategy table**
+
+In `benchmark/benchmark.rb`, replace:
+- every `tagged_metka_table_posts` → `metka_table_posts_tags_cloud` (SQL strings at lines ~172–341, the model's `self.table_name` at 378, `relation_size` at 480, `cloud_mismatches` at 705);
+- the PG function names `metka_ins/upd/del_tagged_metka_table_posts` → `metka_ins/upd/del_metka_table_posts_tags_cloud`;
+- the model class `TaggedMetkaTablePost` (line 377) → `MetkaTablePostsTagsCloud`, and its one usage (line ~558, the tag-cloud read benchmark).
+
+Leave `benchmark/results.txt` / `benchmark/results.sqlite.txt` untouched — they are recorded outputs of past runs. `benchmark/README.md` never names the table literally; no change.
+
+- [ ] **Step 2: Verify**
+
+```bash
+ruby -c benchmark/benchmark.rb
+grep -n "tagged_metka\|TaggedMetka" benchmark/benchmark.rb
+```
+
+Expected: `Syntax OK`, then no grep output. (Running the benchmark itself needs a seeded DB and minutes of runtime — out of scope; the SQL mirrors the dummy migration verified in Task 2.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add benchmark/benchmark.rb
+git commit -m "bench: Rename table strategy table to metka_table_posts_tags_cloud
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+```
+
+---
+
+### Task 5: Full-suite verification and sweep
+
+- [ ] **Step 1: Run the whole suite on SQLite**
+
+```bash
+rm -f test/dummy/db/*.sqlite3 test/dummy/db/schema.rb
+RAILS_ENV=test DB=sqlite bundle exec rake dummy:db:migrate
+RAILS_ENV=test DB=sqlite bundle exec rake test
+```
+
+Expected: 0 failures, 0 errors.
+
+- [ ] **Step 2: Run the whole suite on PostgreSQL (if available)**
+
+```bash
+bundle exec rake dummy:db:create dummy:db:migrate:reset
+bundle exec rake test
+```
+
+Expected: 0 failures, 0 errors. If no local PG server, note it in the report — CI covers it.
+
+- [ ] **Step 3: Final repo sweep for stale names**
+
+```bash
+grep -rn "tagged_notes\|tagged_songs\|tagged_table_posts\|tagged_metka\|TaggedNote\|TaggedTablePost\|TaggedMetka\|TaggedSong" --include="*.rb" --include="*.erb" --include="*.md" . | grep -v benchmark/results | grep -v docs/superpowers
+```
+
+Expected: no output (the spec/plan docs and historical results files legitimately mention old names).
+
+- [ ] **Step 4: Commit any stragglers found by the sweep**
+
+Only if Step 3 surfaced something; fix and commit with an appropriate message.