Skip to content

docs(wiki): digest the mdl/backend findings into three bug-pattern pages - #358

Merged
ako merged 1 commit into
docs/bug-patterns-cmd-mxclifrom
docs/bug-patterns-backend
Sep 1, 2026
Merged

docs(wiki): digest the mdl/backend findings into three bug-pattern pages#358
ako merged 1 commit into
docs/bug-patterns-cmd-mxclifrom
docs/bug-patterns-backend

Conversation

@ako

@ako ako commented Sep 1, 2026

Copy link
Copy Markdown
Owner

Stacked on #357 (shared seed table and SYNC_LOG.md) — retarget once that merges.

82 of the 83 mdl/backend findings now fall under a named class, and only three pages are new. Most of the area reuses classes written for mdl/executor and cmd/mxcli — describe round-trips, unauthored-state loss, integration contracts, unloadable writes. That's the digest working rather than a shortcut: the second and third areas should be cheaper than the first.

page findings thesis
engine-divergence 30 a gap on one engine is invisible from inside that engine
mutator-addressing 19 in-place edits to nodes the model does not name
access-rule-reconciliation 6 GRANT looks additive and is a read-modify-write

engine-divergence

The dominant class here, and the framing that took the longest to get right: the interface has two implementations, the newer and less complete one is the default, so a gap is the behaviour most users get while tests and habits formed against legacy still pass.

A gap on one engine is invisible from inside that engine — everything is self-consistent, the write stores what the read returns, and the field that never existed is never missed. The cross-engine DESCRIBE matrix (write with A, read with B, all four combinations) is the only check that sees it.

Two failure modes, and only one is honest. A refusal naming MXCLI_ENGINE=legacy costs the user a flag and tells the truth. A -- Empty action placeholder is worse in every way, because describe → edit → exec then deletes the construct and everything reports success. The worst single instance was neither: a read that reported a restricted page as having no roles, which understates access and reads like a finding rather than a gap.

mutator-addressing

ALTER edits a stored document in place, which means naming a node — and DataGrid 2 columns, Accordion groups, pop-up menu items and layout regions store no Name at all. Derived names are the only option and they move when a caption is edited; persisting the authored name is not available, because there is no slot and inventing one is the write-a-property-Studio-Pro-does-not-declare hazard.

So: make the derivation visible, list the addressable names on a miss, and refuse ambiguity rather than resolving it — two columns deriving one name is a data hazard, not a wart. Hand-built BSON drifts from codec-built BSON in ways only a dump-diff shows, and getting a typed-array marker wrong turns a silent no-op into a project Studio Pro cannot open.

access-rule-reconciliation

Six findings, graded high because both directions of loss report success and the subject is who can read data. Two method points worth keeping: the writer was innocent in the instructive case — it stored all three rules and a later reconcile removed them, so the natural starting point was the wrong end — and the reported trigger was a red herring; a fix scoped to the WHERE clause named in the report would have passed the reproduction and left most of the defect.

A deliberate omission, recorded as one

~33 findings here touch the MCP/PED backend, which already has architecture/mcp-backend.md and models/ped-mutation-constraints.md. Giving them a bug-pattern page would restate content with a canonical home, so they get none — and that decision has its own SYNC_LOG.md row, so the gap reads as a choice rather than an oversight.

Where the digest stands

area findings covered
mdl/executor 248 83%
cmd/mxcli 95 92%
mdl/backend 83 99%
mdl/grammar 53
mdl/visitor 28

🤖 Generated with Claude Code

82 of the 83 mdl/backend findings now fall under a named class. Only
three pages are new: most of the area reuses classes written for
mdl/executor and cmd/mxcli, which is the digest working rather than a
shortcut.

- engine-divergence (30). The dominant class here. Two implementations
  behind one interface, with the newer, less complete one as the
  default — so a gap is the behaviour most users get while tests formed
  against legacy still pass. A gap on one engine is invisible from
  inside that engine: everything is self-consistent, and the field that
  never existed is never missed. The cross-engine DESCRIBE matrix
  (write with A, read with B, all four) is the only check that sees it.
  Two failure modes and only one is honest — a refusal naming
  MXCLI_ENGINE=legacy costs a flag, a `-- Empty action` placeholder
  makes describe→exec delete the construct. The worst instance was a
  read that under-reported page access.

- mutator-addressing (19). ALTER edits a stored document in place,
  which means naming a node — and DataGrid2 columns, object-list items
  and layout regions store no Name at all. Derived names are unstable,
  ambiguity is refused rather than resolved, and hand-built BSON drifts
  from codec-built BSON in ways only a dump-diff shows. Getting a
  typed-array marker wrong turns a silent no-op into an unopenable
  project.

- access-rule-reconciliation (6). Small and graded high: GRANT looks
  additive and is a read-modify-write, so both widening and narrowing
  report success. Records two method points — the writer was innocent
  and a later reconcile removed the rules, and the reported trigger
  (WHERE) was a red herring that a scoped fix would have satisfied.

The ~33 MCP/PED findings are deliberately NOT given a page: that
subsystem already has architecture/mcp-backend.md and
models/ped-mutation-constraints.md, and restating them would break the
never-restate rule. Recorded as its own SYNC_LOG row so the omission
reads as a decision rather than an oversight.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ako
ako merged commit cfafc0b into docs/bug-patterns-cmd-mxcli Sep 1, 2026
7 checks passed
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