gabriel / musehub public
docs BREAKING crdt task/259-crdt-qa-v2 #1 / 1
AI Agent gabriel · 8 days ago · Nov 8, 2026 · Diff

docs(crdt): #259 CRDT Primitives QA contract v2 — correct /muse/crdt against the running library and engine

Checked on musehub dev 4aa7b9e8 and Muse 0.2.1rc20 (muse dev 5becda10) in a disposable sandbox (isolated HOME, no identity, no hub, no remotes, pure Python). The Muse engine bundled in the c13 image has byte-identical muse/core/crdts modules.

Claim matrix: 72 claims (VERIFIED 27, INCORRECT 28, BROKEN 7, MISSING 4, AMBIGUOUS 5, NOT EXECUTABLE 1). Every INCORRECT, BROKEN and MISSING row has a disposition.

Page corrections (the intended contracts are kept; each known defect carries a note that links its ticket): - Join is join(other) on five types and merge(other) on VectorClock; the types are immutable classes, not module-level merge(a, b) functions over State dicts. Per-type method tables, wire formats and examples are generated from the classes and executed by the tests. - File names vclock.py / g_counter.py; AWMap values are strings (concurrent sets resolve to the greater random token); ORSet and RGA state shapes; "proven" becomes "tested, not proofs"; unfounded "Used in" lines replaced by verified "Used today" lines. - CRDTPlugin extends MuseDomainPlugin; the merge path is marked "Not available in Muse 0.2.1rc20" (musehub#204: muse merge never reads merge_mode, crdt_join_snapshots has no caller); the three_way literal is corrected; schema types documented. - RGA known defects (muse#125: join not idempotent, unknown anchors dropped, recursion limit at 997 elements) stay as contract plus warning. - V1 lattice-law cards: one card per type, fixed replicas, every result computed from the real classes; the RGA card shows the idempotency failure and says convergence is not verified.

Tickets: gabriel/muse#214 (new: CRDT source docs and annotate wording, P3), commented existing gabriel/muse#125 and gabriel/musehub#204; linked gabriel/musehub#276.

Tests: tests/docs_contract/test_crdt.py (45 pass, 4 strict xfails: muse#125 x3, musehub#204). Whole docs_contract (database-free, the three docdb_01/docdb_03 functions deselected): 705 passed, 91 xfailed against 660 / 87 at the base. Page-owned styles in _crdt-docs.scss with interim musehub#283 contrast overrides scoped to the page; the superseded .crdt-primitive-api and badge-modifier rules are removed from _refpages.scss.

sha256:259e6968cab8c57d9cd790b248e033ceeab2d75a7bdb547e2e41ffb4316cd3cf sha
+206 ~8 −20 symbols
7 changed · 1204 in snapshot files
sha256:e7d487b8cb12beaef4aa0bf844dbee260d5593d225dc3557c9aa2917a917c3a7 snapshot
+206
symbols added
~8
symbols modified
−20
symbols removed
7
files changed
1204
files in snapshot
0
dead code introduced
Semantic Changes 234 symbols
+ AWMAP_TEMPO_READS variable variable AWMAP_TEMPO_READS L274–274
+ CLASSES class variable CLASSES L80–87
+ CRDT_PRIMITIVE_VALUES variable variable CRDT_PRIMITIVE_VALUES L403–403
+ Card class class Card L35–41
+ DIMENSION_SPEC_FIELDS variable variable DIMENSION_SPEC_FIELDS L405–410
+ EXAMPLES variable variable EXAMPLES L99–150
+ LAW_CARDS variable variable LAW_CARDS L258–258
+ MANIFEST_FIELDS variable variable MANIFEST_FIELDS L411–417
+ Method class class Method L30–32
+ PLUGIN_METHODS method variable PLUGIN_METHODS L418–421
+ PRIMITIVES variable variable PRIMITIVES L287–399
+ PUBLIC_METHODS method variable PUBLIC_METHODS L72–79
+ Primitive class class Primitive L44–56
+ RGA_FAILS_A_LAW variable variable RGA_FAILS_A_LAW L265–265
+ _FIXTURES variable variable _FIXTURES L194–230
+ _QUALIFIED variable variable _QUALIFIED L27–27
+ _WIRE_SOURCES variable variable _WIRE_SOURCES L278–285
+ __all__ variable variable __all__ L423–437
+ _awmap_tempo function function _awmap_tempo L268–270
+ _card function function _card L233–243
+ _cards function function _cards L246–255
+ _json function function _json L94–95
+ _methods method function _methods L90–91
+ _rga_fixture function function _rga_fixture L155–166
+ _rga_holds_all function function _rga_holds_all L261–262
+ _show_counts function function _show_counts L185–186
+ _show_lww function function _show_lww L189–191
+ _show_map function function _show_map L179–182
+ _show_rga function function _show_rga L169–170
+ _show_set function function _show_set L173–176
+ _sig function function _sig L67–68
+ AWMap import import AWMap L23–23
+ Any import import Any L21–21
+ CRDTDimensionSpec import import CRDTDimensionSpec L24–24
+ CRDTPlugin import import CRDTPlugin L25–25
+ CRDTPrimitive import import CRDTPrimitive L24–24
+ CRDTSnapshotManifest import import CRDTSnapshotManifest L25–25
+ Callable import import Callable L21–21
+ Final import import Final L21–21
+ GCounter import import GCounter L23–23
+ LWWRegister import import LWWRegister L23–23
+ NamedTuple import import NamedTuple L21–21
+ ORSet import import ORSet L23–23
+ RGA import import RGA L23–23
+ VectorClock import import VectorClock L23–23
+ annotationlib import import annotationlib L16–16
+ annotations import import annotations L14–14
+ inspect import import inspect L17–17
+ json import import json L18–18
+ re import import re L19–19
+ typing import import typing L20–20
+ signature_of function function signature_of L59–64
~ src/scss/components/_crdt-docs.scss .scss 61 symbols added
+ (forced-colors: active) rule (forced-colors: active) L182–186
+ (max-width: 640px) rule (max-width: 640px) L171–180
+ crdt-methods method rule .crdt-methods L179–179
+ crdt-methods__caption method rule .crdt-methods__caption L110–115
+ crdt-primitive-wire rule .crdt-primitive-wire L116–116
+ crdt-law-formula rule .devdocs--crdt .crdt-law-formula L50–50
+ crdt-law-symbol rule .devdocs--crdt .crdt-law-symbol L49–49
+ crdt-primitive rule .devdocs--crdt .crdt-primitive L88–88
+ crdt-primitive-badge rule .devdocs--crdt .crdt-primitive-badge L51–51
+ crdt-primitive-name rule .devdocs--crdt .crdt-primitive-name L52–52
+ crdt-primitive-wire code rule .devdocs--crdt .crdt-primitive-tagline code, .devdocs--crdt .crdt-primitive-use code, .devdocs--crdt .crdt-primitive-wire code L56–58
+ crdt-primitive-wire rule .devdocs--crdt .crdt-primitive-tagline, .devdocs--crdt .crdt-primitive-use, .devdocs--crdt .crdt-primitive-wire L53–55
+ crdt-primitive-use strong rule .devdocs--crdt .crdt-primitive-use strong L59–59
+ crdt-primitives rule .devdocs--crdt .crdt-primitives L87–87
+ devdocs-breadcrumb rule .devdocs--crdt .devdocs-breadcrumb L26–35
+ devdocs-callout > div rule .devdocs--crdt .devdocs-callout > div L63–63
+ devdocs-callout li + li rule .devdocs--crdt .devdocs-callout li + li L65–65
+ devdocs-callout ul rule .devdocs--crdt .devdocs-callout ul L64–64
+ devdocs-code-block pre rule .devdocs--crdt .devdocs-code-block pre L66–66
+ devdocs-code-label) rule .devdocs--crdt .devdocs-code-header :is(.devdocs-code-lang, .devdocs-code-label) L45–45
+ devdocs-nav rule .devdocs--crdt .devdocs-nav L36–44
+ devdocs-phase-desc rule .devdocs--crdt .devdocs-phase-desc L13–13
+ devdocs-phase-desc code rule .devdocs--crdt .devdocs-phase-desc code L14–14
+ devdocs-phase-num rule .devdocs--crdt .devdocs-phase-num L12–12
+ devdocs-callout code rule .devdocs--crdt .devdocs-section :is(p, li, td, dd) code, .devdocs--crdt .devdocs-callout code L23–24
+ devdocs-callout a rule .devdocs--crdt .devdocs-section :is(p, li, td, figcaption, dd, .devdocs-callout > div) a, .devdocs--crdt .devdocs-callout a L16–22
+ devdocs-callout a:focus-visible rule .devdocs--crdt .devdocs-section :is(p, li, td, figcaption, dd, .devdocs-callout > div) a, .devdocs--crdt .devdocs-callout a:focus-visible L21–21
+ devdocs-table rule .devdocs--crdt .devdocs-table L76–83
+ devdocs--crdt :not(pre) > code rule .devdocs--crdt :not(pre) > code L62–62
+ devdocs-nav-link--sub rule .devdocs-nav-group-label, .devdocs-nav-link--sub L37–38
+ devdocs-nav-link--active rule .devdocs-nav-link--active L39–43
+ lawcard rule .docfig .lawcard L183–183
+ lawcard--rga rule .docfig .lawcard--rga L184–184
+ lawcard__expr rule .docfig .lawcard__expr L166–166
+ lawcard__inputs rule .docfig .lawcard__inputs L144–153
+ lawcard__laws rule .docfig .lawcard__laws L172–178
+ lawcard__note rule .docfig .lawcard__note L168–168
+ lawcard__row--fails > :first-child rule .docfig .lawcard__row--fails > :first-child L185–185
+ lawcard__title rule .docfig .lawcard__title L141–141
+ lawcard__title code rule .docfig .lawcard__title code L142–142
+ lawcards rule .docfig .lawcards L119–126
+ > div rule > div L147–149
+ a rule a L29–34
+ a:focus-visible rule a:focus-visible L33–33
+ code rule code L164–164
+ dd rule dd L151–151
+ dt rule dt L150–150
+ span rule span L28–28
+ tbody th rule tbody th L162–162
+ tbody, tr, td rule tbody, tr, td L79–79
+ tbody, tr, th, td rule tbody, tr, th, td L174–174
+ td rule td L107–107
+ td, code rule td, code L163–163
+ td, td code rule td, td code L71–71
+ td:first-child, td:nth-child(2) rule td:first-child, td:nth-child(2) L72–72
+ before rule td[data-label]::before L177–177
+ th rule th L70–70
+ th, td rule th, td L176–176
+ thead rule thead L173–173
+ thead th rule thead th L161–161
+ tr rule tr L175–175
~ tests/docs_contract/test_crdt.py .py 85 symbols added
+ HUB_ISSUES variable variable HUB_ISSUES L40–40
+ MUSE_ISSUES variable variable MUSE_ISSUES L39–39
+ PAGE variable variable PAGE L38–38
+ TestApiSurface class class TestApiSurface L62–142
+ test_every_method_and_signature_is_on_the_page method method test_every_method_and_signature_is_on_the_page L68–71
+ test_listed_methods_are_exactly_the_public_methods method method test_listed_methods_are_exactly_the_public_methods L63–66
+ test_module_file_names_exist_and_the_old_names_do_not method method test_module_file_names_exist_and_the_old_names_do_not L86–93
+ test_pinned_signatures method method test_pinned_signatures L73–84
+ test_six_primitives_and_the_package_exports method method test_six_primitives_and_the_package_exports L121–132
+ test_the_join_method_is_merge_on_vector_clock_and_join_elsewhere method method test_the_join_method_is_merge_on_vector_clock_and_join_elsewhere L95–107
+ test_the_library_uses_only_the_standard_library method method test_the_library_uses_only_the_standard_library L134–142
+ test_there_are_no_module_level_merge_functions method method test_there_are_no_module_level_merge_functions L109–112
+ test_wire_examples_round_trip_through_the_classes class method test_wire_examples_round_trip_through_the_classes L114–119
+ TestExamples class class TestExamples L145–188
+ test_awmap_concurrent_sets_resolve_by_the_greater_token method method test_awmap_concurrent_sets_resolve_by_the_greater_token L176–181
+ test_awmap_values_are_strings_not_crdts method method test_awmap_values_are_strings_not_crdts L170–174
+ test_every_example_is_on_the_page_verbatim method method test_every_example_is_on_the_page_verbatim L150–152
+ test_example_runs_as_written method method test_example_runs_as_written L147–148
+ test_gcounter_rejects_non_positive_increments method method test_gcounter_rejects_non_positive_increments L163–168
+ test_lww_ties_break_on_author_then_value method method test_lww_ties_break_on_author_then_value L183–188
+ test_orset_remove_only_tombstones_tokens_the_replica_holds method method test_orset_remove_only_tombstones_tokens_the_replica_holds L154–161
+ TestLawCards class class TestLawCards L194–244
+ test_a_failing_law_is_stated_in_text_not_by_colour_alone method method test_a_failing_law_is_stated_in_text_not_by_colour_alone L226–228
+ test_card_results_are_recomputed_from_the_classes class method test_card_results_are_recomputed_from_the_classes L202–213
+ test_one_card_per_primitive_in_order_with_the_three_laws method method test_one_card_per_primitive_in_order_with_the_three_laws L195–197
+ test_rga_convergence_is_not_presented_as_verified method method test_rga_convergence_is_not_presented_as_verified L230–233
+ test_the_awmap_card_note_says_what_get_reads method method test_the_awmap_card_note_says_what_get_reads L235–240
+ test_the_cards_are_an_illustration_not_a_proof method method test_the_cards_are_an_illustration_not_a_proof L242–244
+ test_the_figure_is_a_labelled_docs_figure method method test_the_figure_is_a_labelled_docs_figure L199–200
+ test_the_five_other_types_hold_all_three_laws_on_their_fixtures method method test_the_five_other_types_hold_all_three_laws_on_their_fixtures L215–218
+ test_the_rga_card_shows_the_idempotency_failure_and_nothing_else method method test_the_rga_card_shows_the_idempotency_failure_and_nothing_else L220–224
+ TestPluginAndSchema class class TestPluginAndSchema L386–418
+ test_crdt_plugin_extends_the_domain_plugin_and_has_four_methods method method test_crdt_plugin_extends_the_domain_plugin_and_has_four_methods L387–390
+ test_no_registered_domain_declares_crdt_merge method method test_no_registered_domain_declares_crdt_merge L404–406
+ test_only_the_scaffold_template_implements_the_protocol method method test_only_the_scaffold_template_implements_the_protocol L408–411
+ test_plugin_block_renders_the_protocol_signatures method method test_plugin_block_renders_the_protocol_signatures L392–395
+ test_primitive_values_and_field_lists_match_the_schema_types method method test_primitive_values_and_field_lists_match_the_schema_types L397–402
+ test_the_scaffold_template_implements_the_protocol_but_declares_three_way method method test_the_scaffold_template_implements_the_protocol_but_declares_three_way L413–418
+ TestUsage class class TestUsage L349–380
+ _importers method method _importers L352–365
+ test_midi_has_its_own_separate_rga method method test_midi_has_its_own_separate_rga L378–380
+ test_muse_annotate_does_not_use_the_classes_it_names class method test_muse_annotate_does_not_use_the_classes_it_names L370–373
+ test_only_the_scaffold_template_imports_the_primitives method method test_only_the_scaffold_template_imports_the_primitives L367–368
+ test_the_annotate_lines_link_their_ticket method method test_the_annotate_lines_link_their_ticket L375–376
+ TestWording class class TestWording L306–346
+ test_every_primitive_section_and_anchor_exists method method test_every_primitive_section_and_anchor_exists L344–346
+ test_known_defects_and_the_unsupported_designation_link_their_tickets method method test_known_defects_and_the_unsupported_designation_link_their_tickets L334–338
+ test_section_label_and_pager_come_from_the_registry method method test_section_label_and_pager_come_from_the_registry L307–312
+ test_the_old_claims_are_gone method method test_the_old_claims_are_gone L314–332
+ test_the_status_section_is_first_and_in_the_sidebar method method test_the_status_section_is_first_and_in_the_sidebar L340–342
+ _C_DOCS variable variable _C_DOCS L44–44
+ _C_RGA variable variable _C_RGA L42–42
+ _H_MERGE_UNWIRED variable variable _H_MERGE_UNWIRED L43–43
+ _MUSE_PKG variable variable _MUSE_PKG L46–46
+ _d1 function function _d1 L252–259
+ _merge_command_reaches_the_crdt_join function function _merge_command_reaches_the_crdt_join L287–295
+ _xfail function function _xfail L248–249
+ html function function html L50–51
+ Any import import Any L23–23
+ CRDTDimensionSpec import import CRDTDimensionSpec L29–29
+ CRDTPlugin import import CRDTPlugin L28–28
+ CRDTSnapshotManifest import import CRDTSnapshotManifest L28–28
+ MuseDomainPlugin import import MuseDomainPlugin L28–28
+ Path import import Path L22–22
+ RGA import import RGA L27–27
+ _PHASES import import _PHASES L33–33
+ annotations import import annotations L15–15
+ ast import import ast L17–17
+ data import import data L32–32
+ html_lib import import html_lib L18–18
+ util import import importlib.util L19–19
+ json import import json L20–20
+ muse import import muse L25–25
+ pytest import import pytest L26–26
+ rc import import rc L34–34
+ re import import re L21–21
+ registered_domains import import registered_domains L30–30
+ resolve_plugin_by_domain import import resolve_plugin_by_domain L30–30
+ schema_for import import schema_for L30–30
+ pytestmark variable variable pytestmark L36–36
+ test_muse_merge_reaches_the_crdt_join function function test_muse_merge_reaches_the_crdt_join L299–300
+ test_rga_join_handles_a_long_sequential_chain function function test_rga_join_handles_a_long_sequential_chain L275–284
+ test_rga_join_is_idempotent_on_a_locally_built_sequence function function test_rga_join_is_idempotent_on_a_locally_built_sequence L263–265
+ test_rga_join_keeps_an_insert_with_an_unknown_anchor function function test_rga_join_keeps_an_insert_with_an_unknown_anchor L269–271
+ text function function text L55–56
~ musehub/api/routes/musehub/ui_docs.py .py 1 symbol added, 1 symbol modified
+ _crdt_data import import _crdt_data L22–22
~ musehub/templates/musehub/pages/docs_muse_crdt.html .html 7 symbols added, 8 symbols removed, 6 symbols modified
− article@40 section article@40 L40–472
− aside@13 section aside@13 L13–37
− section#awmap section section#awmap L306–340
− section#gcounter section section#gcounter L343–373
− section#lwr section section#lwr L201–231
− section#orset section section#orset L234–267
− section#rga section section#rga L270–303
− section#vector-clock section section#vector-clock L168–198
+ article@46 section article@46 L46–414
+ aside@17 section aside@17 L17–43
+ caption: Public methods of method section caption: Public methods of L254–254
+ h3: h3 section h3: h3 L157–157
+ section#schema-types section section#schema-types L335–356
+ section#status section section#status L67–100
+ anchor }} section section#{{ p.anchor }} L240–287
~ src/scss/components/_refpages.scss .scss 12 symbols removed, 1 symbol modified
− crdt-primitive-api rule .crdt-primitive-api L419–436
− crdt-primitive-badge--grow rule .crdt-primitive-badge--grow L377–381
− crdt-primitive-badge--map rule .crdt-primitive-badge--map L401–405
− crdt-primitive-badge--register rule .crdt-primitive-badge--register L383–387
− crdt-primitive-badge--seq rule .crdt-primitive-badge--seq L395–399
− crdt-primitive-badge--set rule .crdt-primitive-badge--set L389–393
− tok-cmt rule .tok-cmt L434–434
− tok-fn rule .tok-fn L431–431
− tok-kw rule .tok-kw L430–430
− tok-ret rule .tok-ret L435–435
− tok-str rule .tok-str L433–433
− tok-type rule .tok-type L432–432
Files Changed
+3 ~4
1204 in snapshot
← Older Oldest on task/259-crdt-qa-v2
All commits
Newer → Latest on task/259-crdt-qa-v2

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:259e6968cab8c57d9cd790b248e033ceeab2d75a7bdb547e2e41ffb4316cd3cf --body "your comment"