%unimsg 0 findings/typed-arrays-in-the-graphic-vocabulary/v0

-- The kernel gained a typed array on 2026-09-02. @vocab/graphic/v0 was the
-- vocabulary with the most to gain from it and the one least able to take it,
-- and this document is what closing that gap cost and bought.
--
-- 49% OF THE CBOR on the file the vocabulary was read off. The prerequisite was
-- not the typed array at all: it was a declared coordinate grid, which docs/26
-- parked as a v1 question and @vocab/spatial/v0 later proved.

typed-arrays-in-the-graphic-vocabulary @findings/typed-arrays-in-the-graphic-vocabulary/v0 {
  title    "Typed arrays in the graphic vocabulary: 49% of the bytes, and the grid that had to come first"
  status   :open
  subject  -> @vocab/graphic/v0
  evidence [ -> @findings/the-transcript-writer/v0 ]
  assessed 2026-09-04

  the-question "WHICH OTHER VOCABULARIES GAIN FROM THE TYPED ARRAY, once
     @vocab/spatial/v0's transcript had taken it and halved. The survey was
     short: a typed array is a run of homogeneous numbers, and most of this
     repository's vocabularies hold trees, prose and claims. @vocab/ruleset/v0,
     @vocab/ui/v0, @vocab/rich-document/v0, @vocab/work/v0,
     @vocab/board-presentation/v0, @vocab/language/v0, @vocab/lexicon/v0 and
     @vocab/encyclopaedia/v0 have no such run to gain from.
     @vocab/measurement/v0 was built on it. ONE VOCABULARY HAD A LARGE ONE AND
     COULD NOT USE IT."

  why-a-path-could-not-be-a-typed-array "AND IT IS STRUCTURAL RATHER THAN A
     MATTER OF TASTE. A path was `d [ :move, 10, 20, :cubic, … ]` — one flat
     array of opcodes interleaved with numbers — and a typed array is
     HOMOGENEOUS. No amount of tuning reaches it from there. The opcodes and
     the numbers had to part company first, which is a breaking change to the
     one construct that vocabulary spends the most bytes on."

  the-grid-was-the-real-prerequisite "AND IT WAS ALREADY BEING CHOSEN, in
     private, by the only application that writes these documents continuously.

     @vocab/graphic/v0's own strongest evidence is marasim, which holds a
     document of that shape as its live editing model, and which reports — in
     the vocabulary's own words, quoting that project — that `a pointer event is
     a float and the scene refuses floats, so every number is quantised on ENTRY
     rather than on write`. A GRID WAS THEREFORE ALREADY PICKED AND NO DOCUMENT
     RECORDED IT. Two such documents could sit on different grids with nothing
     saying so.

     docs/26 PARKED THIS EXACT KEY as a v1 question and gave the right reason to
     want it — a declared resolution is `a thing an author should have to state
     rather than a thing an encoding should do quietly` — and lacked a reason to
     pay for it. @vocab/spatial/v0 supplied the first: its :precision is what
     makes a rotated coordinate comparable at all. The typed array supplied the
     second, because scaled integers need a scale.

     SO :precision LANDED FIRST AND THE ENCODING FOLLOWED. It would have been
     worth adding on its own."

  what-it-measured [
    | artefact                                        text          cbor          "gzipped text"
    | "the Ottoman arms, as it was"                   "2,661,062"   "2,082,610"   "496,816"
    | "the same, through tools/gupgrade"              "2,720,391"   "1,065,817"   "482,653"
    | "the source SVG, for reference"                 "1,946,176"   "—"           "392,366"
  ]

  the-binary-halves-and-the-text-does-not "49% OF THE CBOR — 2,082,610 to
     1,065,817 — and the document moves from 7% LARGER than the SVG it was
     converted from to 45% SMALLER.

     THE TEXT FORM GROWS BY 2%, because a scaled integer is a longer numeral
     than the decimal it replaces: `10101` against `0.010101` is a wash, but
     `1906437983` against `1906.437983` is not. That is the honest shape of the
     trade and it is in the vocabulary rather than only here."

  findings [
    | id    finding                                                                                      answer
    | "T1"  "a path is opcodes interleaved with numbers, and a typed array is homogeneous"               "split into :ops and :coords. The breaking change is recorded in the vocabulary, per @vocab/vocabulary/v0's draft rule"
    | "T2"  "there was no declared grid, so there was no scale to store integers against"                ":precision, required, with a :coordinate quantum and a :rounding rule"
    | "T3"  "an opcode was a symbol, and a symbol is not a number"                                       "a code from a closed six-row table. It costs legibility and it is 8 bytes to 1"
    | "T4"  "`:d` was a path's data AND the fourth component of an affine matrix"                        "the split ends the collision. Found by the converter mistaking a rotation for a path, not by reading the tables"
    | "T5"  "an opcode could repeat its arguments, which a two-array form cannot express without lookahead"  "one code per command. It costs 13,733 opcode bytes against a saving of a million"
    | "T6"  ":points looked like a second candidate and is a table of x and y rows"                      "left alone. Flattening a legible ten-row table to save a rounding error is not a trade"
  ]

  what-was-changed [
    | artefact                          change
    | "vocab/subjects/graphic-v0.umsg"  "amended in place, with the break recorded — the identifier does not move, because a draft that narrows records what stopped conforming instead"
    | "tools/gupgrade"                  "new. Carries a document of the earlier draft into the amended one, refusing rather than rounding when a coordinate misses the grid"
    | "tools/gcheck"                    "the gate reads :precision and the two arrays, and decodes RFC 8746 integer arrays itself, since the syntax package presents the tag and not the elements"
    | "tools/dgrender"                  "multiplies the integers back out by the quantum. Verified on the crescent: move 100,40 and an arc with its flags intact"
    | "tools/svg2umsg"                  "emits the amended shape and a :precision block"
    | "the three graphic examples"      "upgraded in place, and all three pass the amended gate"
  ]

  what-is-still-owed [
    | item                                                        why
    | "marasim"                                                   "it holds this shape as its live editing model and will not read the amended one. It is the same repository's project, so this is coordination rather than a compatibility problem — but nothing has been changed there"
    | "generated/graphic/ottoman.umsg"                            "regenerable, and the upgraded copy sits beside it as ottoman-typed.umsg rather than replacing it"
    | "a second real file"                                        "one 1.9 MB file measured the win. It is the same count of one docs/26 was honest about"
    | "whether a DOCUMENT should hold scaled integers at all"     "@vocab/spatial/v0 records the same question as open for its own documents, on the legibility argument. THIS DOCUMENT ANSWERS IT ONE WAY FOR ARTWORK — where the reader is a machine and the file is 1.9 MB — and that does not settle it for a scene somebody hand-writes"
  ]
}