Skip to content

docs(claims): make every engine count state what it counts, and stop two thirteens colliding (#424) - #444

Merged
cevheri merged 1 commit into
mainfrom
docs/phase0-wrapup-claims
Aug 20, 2026
Merged

cevheri merged 1 commit into
mainfrom
docs/phase0-wrapup-claims

Conversation

@cevheri

@cevheri cevheri commented Aug 20, 2026

Copy link
Copy Markdown
Member

The Phase 0 wrap-up item in #424 asks that the published engine claims agree. This is that sweep,
measured surface by surface rather than assumed.

The collision this repo created for itself

Taking the wire-compatible relatives from nine to thirteen in #442 put a second, disjoint
thirteen directly beside the thirteen shipped drivers — in both README.md and DOCKERHUB.md,
separated only by the word "more". A skimmer reading the bolded lead-ins saw "Thirteen engines" and
then "Thirteen more engines" and had no cue they were different sets.

Both now name their denominator, and the README states what the two make together: thirteen
drivers reaching twenty-six named engines
.

DOCKERHUB.md had the same fault twice:

  • "Thirteen engines" sat above a table with fourteen rows — the fourteenth is the embedded
    LibreDB store, so a reader who counts gets a different number than the one stated.
  • The relatives table below stated no number at all, and renders thirteen engines in ten
    rows
    because engines that behave identically share a row. A reader tallying rows got ten.

Stale copy, each verified against the code

Surface Was Now
charts/libredb-studio/README.md seven engines thirteen — Chart.yaml's own enumeration
operator/helm-charts/.../README.md seven engines same (byte-identical copy)
operator CSV keywords seven engines thirteen
deploy/rancher/E2E_VALIDATION_TASK.md "Chart.yaml still names seven engines" Chart.yaml names thirteen
packaging/winget/...locale.en-US.yaml.tmpl header thirteen, body seven body agrees

The chart README one matters most: that string is what ArtifactHub renders, so it undersold the
product to exactly the reader who checks a claim by reading it.

The operator keywords left Couchbase, ClickHouse, Druid, Elasticsearch, OpenSearch and Trino
invisible to OperatorHub search. Added to operator/config and propagated with
make -C operator bundle — the bundle diff is the six keyword lines and nothing else, createdAt
untouched.

What was deliberately NOT changed

The Rancher catalog prose still says ten engines. An audit flagged five sites there as wrong.
They are not: that wording is version-scoped and frozen on purpose — the catalog page describes a
released version and stays at ten until a tag carries the three new engines — and
CATALOG_LISTING.md:15-37 says so in its own accuracy gate. Changing it would have undone a
decision, so the only edit in that area is the E2E task file, which described a mismatch that no
longer exists.

Two relatives named in the listings

Under a rule the owner settled: a relative is named only where its caveats are cosmetic (it
reports a different version string). A marketplace listing is read during buyer diligence, so
anything with a data-correctness caveat stays out.

  • Added: TiDB (mysql family), FerretDB (mongodb family) — joining MariaDB and the three Redis
    forks in the flatpak/flatpark metainfo and the Azure description.
  • Excluded despite being full tier: Citus, TimescaleDB, YugabyteDB — all three report row
    counts that are wrong or zero rather than missing.
  • Excluded on tier: StarRocks, CockroachDB, Materialize, RisingWave.

The Azure bullet still tallies to thirteen slots, each relative folded into its driver's slot, so
its "thirteen engines" headline stays honest.

Chart version 0.1.40 -> 0.1.41

charts/libredb-studio/README.md is a packaged chart file and 0.1.40 is already published
(confirmed against the live index), so #167 requires the bump. appVersion stays 0.12.0. The
operator's chart copy moves with it — two independent guards enforce byte-identity between
charts/libredb-studio/ and operator/helm-charts/libredb-studio/.

B53: what this PR deliberately did not fix

Ten sites in docs/AGENT.md, docs/AGENT_DATA_FLOW.md and src/lib/agent/ say the composed
grounding path leaves "the other nine engines" to their providers. Nine was correct when the
factory built eleven type-ids. It now builds fourteen.

The replacement is not the obvious one, which is why this is recorded rather than patched. The
thirteen external engines give eleven; the original basis — every type-id, embedded libredb
included — gives twelve. The sites never say which they count, and that ambiguity is the
defect. B49 complicates it further: a libredb connection can never be grounded at all, so
"twelve" is arithmetically faithful but describes a path one of the twelve cannot complete. Picking
a digit silently would repeat exactly the fault this PR exists to fix.

Gates

format · lint (0 errors) · typecheck · knip · test (all 30 groups) · build — green.
Plus the guards this change touches, each run directly: chart:check strict
(chart 0.1.41 / appVersion 0.12.0 in sync), readme:check
(13 engines and the install commands match README.md in README_zh.md, README_ja.md),
helm lint --strict (0 failed), the operator bundle freshness gate reproduced as CI runs it
against the commit (exit=0), the two chart trees confirmed byte-identical, and
appstreamcli validate on both metainfo files.

…two thirteens colliding (#424)

Phase 0's wrap-up asks that the published engine claims agree. They did not, and the
sharpest case was one this repo created for itself: taking the wire-compatible
relatives from nine to thirteen in #442 put a second, disjoint "thirteen" next to the
thirteen shipped drivers, in both README.md and DOCKERHUB.md, with only the word
"more" separating them. Both now say which thirteen they mean, and the README states
the total the two make - thirteen drivers reaching twenty-six named engines.

DOCKERHUB carried the same fault twice over: "Thirteen engines" sat above a table with
fourteen rows, the fourteenth being the embedded LibreDB store, and the relatives table
below it stated no number at all while rendering thirteen engines in ten rows. Both are
now explicit about their denominator and about the merged rows.

Genuinely stale copy, each verified against the code rather than assumed:

- The two chart READMEs still named SEVEN engines while their own sibling Chart.yaml
  named thirteen. That is the string ArtifactHub shows, so it undersold the product to
  exactly the reader who checks. Fixed to Chart.yaml's own enumeration so the two cannot
  drift apart again.
- The operator CSV keywords named seven engines, leaving Couchbase, ClickHouse, Druid,
  Elasticsearch, OpenSearch and Trino invisible to OperatorHub search. Added to
  operator/config and propagated with `make -C operator bundle`; the bundle diff is the
  six keywords and nothing else.
- deploy/rancher/E2E_VALIDATION_TASK.md told a human tester to expect Chart.yaml to name
  seven engines against an app-readme of ten. Chart.yaml names thirteen. The instruction
  now describes the mismatch that actually exists.
- The winget locale contradicted itself inside one file: ShortDescription said thirteen
  engines, the body enumerated seven as though complete.

Deliberately NOT changed: the Rancher catalog prose still says ten engines. That wording
is version-scoped and frozen on purpose - the catalog page describes a released version
and waits for a tag to carry Elasticsearch, OpenSearch and Trino - and its own accuracy
gate says so. A sweep that reads "ten" as staleness would undo a decision.

Two relatives are now named in the marketplace listings, under a rule the owner settled:
a relative is named only where its caveats are cosmetic. So TiDB and FerretDB join
MariaDB and the three Redis forks in the flatpak/flatpark metainfo and the Azure
description, and Citus, TimescaleDB and YugabyteDB stay out despite being full-tier,
because they report row counts that are wrong rather than missing. StarRocks,
CockroachDB, Materialize and RisingWave stay out on their tiers.

Chart version 0.1.40 -> 0.1.41: charts/libredb-studio/README.md is a packaged file and
0.1.40 is already published, so #167 requires the bump. appVersion stays 0.12.0. The
operator's chart copy moves with it, being byte-identical under two guards.

B53 records what this PR deliberately did not fix: ten sites say the composed grounding
path leaves "the other nine engines" to their providers, which is stale, but the
replacement is not the obvious one. Nine was fourteen type-ids ago; the external reading
gives eleven and the original basis gives twelve, the sites never say which they count,
and B49 means one of the twelve cannot be grounded at all. Picking a digit silently
would repeat the fault this PR exists to fix.
@sonarqubecloud

Copy link
Copy Markdown

@cevheri
cevheri merged commit 27e19cf into main Aug 20, 2026
25 checks passed
@cevheri
cevheri deleted the docs/phase0-wrapup-claims branch August 20, 2026 13:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant