Skip to content

Compare v3 flat-methods YAML authoring - #36

Closed
addshore wants to merge 1 commit into
refine-v3-yaml-authoringfrom
draft/lb-1588-methods-yaml-comparison
Closed

addshore wants to merge 1 commit into
refine-v3-yaml-authoringfrom
draft/lb-1588-methods-yaml-comparison

Conversation

@addshore

@addshore addshore commented Nov 4, 2026

Copy link
Copy Markdown
Member

Purpose

YAML-only comparison of LB-1588's proposed flat methods structure with PR #30, as requested. This is a schema/authoring prototype, not a merge-ready consumer migration.

Base: refine-v3-yaml-authoring, pinned during preparation to ec974430a87c04483a2808e580894b08ff23134e. Stacking on #30 makes this diff exactly one YAML file and isolates the alternative from #30's existing renderer and byte-formatting changes. #30 is unchanged.

No parser, builder, renderer, generated SDK, or workflow changes. The unchanged consumers do not yet support this mixed flat-list schema, so a rendered preview is not evidence for this comparison. No build or deployment was requested or performed.

Comparable source size

Physical lines in each complete message definition, from its numeric message key to the next message key, including shared fields, prose, examples, and blank/comment lines. This measures the actual authored source, not generated output; wrapping and compact lists affect these figures.

Same PR #30 case Before Flat methods Change
MT34 Device Status 218 173 -45
MT35 Device IDs 81 71 -10
MT39 GPS Control 135 104 -31
MT58 Message Box 423 383 -40
Comparable four-message total 857 731 -126 (-14.7%)

Maximum indentation in MT39 drops from 16 to 12 spaces and MT58 from 20 to 14 spaces. MT34/35 still reach 18 because the existing captured exchanges remain attached. The flatter lists remove exchange, per-method versions, and contexts nesting; lifecycle and error prose remains explicit, and common prose can repeat across flat version entries.

The three additional worked proposal examples are a separate coverage increase, not evidence that the new syntax is bigger for equivalent content:

Additional proposal case Before After
MT14 Config 149 196
MT31 GSM Control 44 90
MT33 SIM Settings 57 109
All seven cases together 1107 1126

MT31's new conditional rules reach 18-space indentation versus 12 before. Fewer wrapper levels do not make conditional semantics disappear. The MT14 count includes two new scope-caveat comments; the global prototype banner is excluded from message-block counts.

Content and preservation

  • Flat named operations with direct request, response, and publication stages; compact presence lists; fixed values separate from defaults, fallbacks, constraints, and conditional rules.
  • MT14 demonstrates separate summary/value GETs and a NONE maintenance operation; MT31 demonstrates default/fallback and precedence; MT33 demonstrates separate SIM1/SIM2 SETs and read-only ICCID metadata.
  • MT58 retains both wire versions, top-level format labels/applicability, canonical header-22 selectors, the legacy default, empty-value cache clearing, ignored checksum inputs, lifecycle/errors, and the separate NONE tracking upload.
  • methods remains optional. All 44 unrelated message definitions and every protocol header are unchanged. Existing messages that lack operation metadata remain valid source material; no claim is made that all communication must be expressed as a method.
  • Shared data definitions are unchanged except MT33 field 8's proposed readonly: true. Existing raw examples and the complete MT34/35 captured exchanges remain deeply equal after parsing, including bytes, encodings, targets, descriptions, and provenance. No captures or example bytes were invented.
  • MT58 UNSUBSCRIBE's header-22 meaning survives in operation prose: it is ignored and does not select or reset the publication format. No unsupported header-description override syntax was invented.

Explicit prototype choices and remaining decisions

  • key is a prototype extension: stable operation identity is separate from editable name, following the latest discussion. Existing operation keys are retained for a later renderer to preserve links. Repeated keys have distinct versions. This YAML-only change itself does not implement link preservation.
  • The existing captured-example metadata is carried into flat operations. Its consumer integration is not specified by the proposal yet.
  • Existing explicit ACK envelope details are retained where already documented instead of assuming that type: 5 alone fully formalizes them. Shared ACK/error semantics and consumer integration remain open.
  • Presence means wire presence; required bytes can still be empty. Defaults/fallbacks describe effective receiver values and do not insert fields. The explicit zero/false/empty distinctions are preserved.
  • Rules are proposed documentation metadata, not an implemented validator or packet-classification language. Evaluation order/conflicts, default/fallback precedence on the same field, capability-dependent output, general predicates, and header-description overrides remain unresolved.
  • MT14 here is the scalar proposal. Firmware batch SET and expected-length GET still need reconciliation. No new wire version is invented. Summary exchange patterns remain described outside these named helpers.
  • Haptics and File Data are unchanged because their proposed structures are not worked through yet.

Validation

Passed on the final YAML:

  • Strict YAML parse with duplicate-key checking: 0 errors, 0 warnings.
  • git diff --check.
  • Independent parsed-object comparison of headers, all unrelated messages, shared data definitions, and all existing example objects.
  • Local authoring audit of 22 operations, 46 stages, 168 listed header/field references, and 3 conditional rules: IDs resolve to the correct message/header definitions, presence lists do not conflict, fixed/default/override references are listed, fallback source IDs exist, and operation key/version identities are unique.
  • Targeted assertions for NONE upload stages, H22 ignored UNSUBSCRIBE, false/empty defaults, and required MT58 bytes with only the 1024-byte maximum.

Not run: consumer test suite, build, or rendered browser comparison, deliberately excluded from this YAML-only request. The audits above are syntax/reference/preservation checks, not a complete formal schema validator or verification of proposed firmware semantics.

@addshore addshore closed this Nov 10, 2026
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