Damaged MAT input warns and shows what was read, instead of shifting values, overflowing the stack or opening as editable text

[ww-mw]

Implements the maintainer's 2026-10-16 group E ruling.

This PR covers six theme 1 items from the backlog, one commit each. The ruling for theme 1 (damaged input) says: "warn and show what was read; never refuse the file and never crash." The maintainer agreed each item's recommendation ("Agree your suggestions ... Add unit tests to lock down the fix."). Each recommendation is quoted below.

All six follow the same pattern. A damaged value is shown as a <RxC class, not decoded> row with no editor and no child rows, and the rest of the file reads as before:

• A .mat file warns with part-unreadable, through the existing collectUndecoded / parsed.warnings path.
• A model workspace does not warn, per the C-232 ruling.
• A dictionary value shows the not-decoded row.

#122's warnings sink (recordPartialDecode) is for values that decoded in part, so no item here uses it, and no second sink is added. src/index.ts is unchanged. Every test was written first, and each one runs the real reader or session. Each commit includes its own rebuilt dist/, and npm run verify was green at each commit.

Gate

• Head (f4150a9): rm -rf dist && npm run build leaves the tree clean. npm run verify returns rc 0. Test files: 246 passed / 1 skipped. Tests: 8131 passed / 26 skipped, 53 of them new. The smoke, pack, leak and browser checks pass. CI's dist step (rm -rf dist, build, porcelain on dist) prints nothing.
• Merged with current main (641fca9): main has taken LookupTable, Breakpoint, VariantBank and Signal properties follow MATLAB #124 and addEntry refuses a name MATLAB cannot use, and a paste of an mpt entry MATLAB already wrote is admitted #125 since this branch was cut from c3dee1a. No file is changed on both sides, and git merge-tree reports no conflict. In the merged tree, the committed dist/ is byte-identical to a fresh build. Verify there: 250 files / 8246 passed / 26 skipped, with typecheck, smoke, pack, leak and browser all OK.

C-069: a struct array field slot that is not a matrix (c5850a7)

Recommendation: "(a): only damaged files reach it, it reuses the arm's existing damaged-struct refusal, and it keeps the change inside parseMatrix." Option (a) is: "Record the whole struct array as undecoded ('element k's field f is not a matrix'), as pastItsEnd does."

What was wrong: in a .mat struct array, if one element's field slot held a data element that is not a matrix, the slot was skipped and left no gap. That field's later values moved onto earlier elements, with no warning. Example: in a 1x3 array, element 3's a (5) was shown as element 2's.

Root cause: parseMatrix's struct-array field loop only adds a value when the slot is MI_MATRIX, then steps past the slot. So the field's list gets shorter, and structElementsHeld sizes the rows to the longest list.

Fix (MatParser.ts): a new branch in that loop. If the array has more than one element and the slot's tag is complete, the whole array is recorded as not decoded, with the reason element K's field F is not a matrix (a data element of type T). This matches the existing pastItsEnd branch. A 1x1 struct, and a tag cut short by the end of the bytes, are read as before. The node layer already builds the not-decoded row.

Tests:

• matParser.test.ts "records a struct ARRAY with a field slot that is not a matrix as not decoded, and shifts no element onto another". It covers a 1x3 with a miDOUBLE slot (checking the exact variable, the exact warning, and that the next variable is unchanged), a miINT32 slot in a 2x2, and the nested paths t.f and c{2}.
  • Failed before: value was null, there was no undecoded, and the field lists were a:[1,5], b:[2,4,6].
• matStructArray.test.ts runs the same case through createSession().addMatSource. The row is now <1x3 struct, not decoded> with 0 rows, and there is exactly one warning.
  • Failed before: the row was <1x3 struct> with 3 rows.
• A cut control, "reads a struct array cut inside a field tag as one cut short", passes before and after.
• Mutation checks: dropping the complete-tag guard fails only the cut control. Dropping the more-than-one-element guard fails only the existing "skips a field slot whose element is not a matrix".

Existing tests changed: none.

Left out: a 1x1 struct with a non-matrix slot still drops that field silently. Nothing can shift in that case, and the existing test pins it. This could be a follow-up. dex-core's G75 ports the old shift.

C-231: nesting with no depth limit (00e209f)

Recommendation: "(a), with a cap well under the measured ~1,200-level ceiling and checked against the node layer's own recursion depth." Option (a) is: "Thread a depth through parseMatrix. Past a cap, record the subtree as undecoded with a reason, which collectUndecoded already reports, and keep the rest of the file."

What was wrong: a value nested about 1,500 levels deep made the whole open fail with RangeError: Maximum call stack size exceeded. In a model workspace the section came out empty, and in a text dictionary the entry showed as <1x320033 char>.

Root cause: parseMatrix recurses into struct fields and cell elements with no limit, and the record walk does not catch the error.

Fix (MatParser.ts):

• A new MAX_NESTING = 128. It is exported from the module only, not from the package. 128 is dex-core's cap.
• parseMatrix(..., depth = 0). The struct-field and cell-element calls pass depth + 1.
• At depth 128 or more, the reader reads the flags, dims and name, then records the value as not decoded with the reason nested more than 128 levels deep, so it was not read. The value's bytes are kept.
• Every other caller starts at depth 0.
• In mcosTypedNode.ts, the comment that said "a struct nested a few thousand deep is a legal file" is corrected.

Tests (new test/matNesting.test.ts, 9 cases; chains are built byte by byte): all 9 failed before, each for the reason given here.

• The cap is 128. Before: undefined.
• 5,000-deep cell and struct chains open. Level 129 is exactly the not-decoded value and holds the remaining levels' bytes. There is exactly one warning, and the variables around the chain equal a control file's. Before: RangeError.
• Boundary: 128 levels are read in full with no warning. In a 129-level chain, only the leaf is recorded. Before: the leaf was read as double 7.
• Through addMatSource, every row down to level 129 is present, and the last one is not decoded and not editable. toRow and serializeValue do not throw. Before: RangeError.
• Dictionaries: decodeMatStream, a text dictionary (sparse_text.sldd entry c) and a binary one (sparse_binary.sldd entry c) open to the cap, and an untouched save writes the value back unchanged. Before: ok:false / <1x320033 char>.
• Model workspace (cases.slx, synthetic workspace): both variables are shown, with no warning. Before: the section was empty.
• Mutation checks: an off-by-one cap is caught by 8 cases, dropping the cell depth + 1 by 5, and dropping the struct one by 4.

Existing tests changed: none.

Left out:

• The top row of a 5,000-deep cell shows 128 pairs of braces, which is the node layer's existing display for nested cells.
• A capped cell element copies as its placeholder text, as every not-decoded cell element already does.
• dex-core's G78 reads 129 levels and shows class unknown. It should follow this reader.

C-068: a numeric value whose bytes end before its data (7c9b670)

Recommendation: "(b), ruled together with the agenda's 'Short values in the node layer' bullet." Option (b) is: "The node layer builds a not-decoded node (_createUndecoded with a reason such as 'its payload is missing') whenever a numeric variable declares elements and has value null, real or complex."

What was wrong: a numeric variable (real, complex, logical or integer) that declares elements but whose bytes end before its data was shown as null / [null], editable, with no warning. Before #116, the complex case threw and lost the whole file. #116 stopped the throw by building the value as a real one.

Root cause: the parser keeps value: null with no undecoded mark, and its tests pin that. Neither _createFromMatNumeric nor collectUndecoded handled this case.

Fix:

• MatlabVariableNode._createFromMatNumeric builds the not-decoded node when the value is null, more than 0 elements are declared, and the class is not unknown. A model whose workspace part is cut short opens even when the cut lands in a complex variable #116's guard is kept for 0 elements or negative dims.
• MatParser: a new holdsNoData check gives "P" declares N element(s) and holds no data, so its value was not read. A variable already named by a "read short" warning is skipped, so a cut record warns once.
• The parser's value: null is unchanged.

Tests (new test/matNoPayload.test.ts, 7 cases):

• Real 1x1 and 2x3, complex 1x1 and 1x2, logical, and int16 3x2 variables, each with no data, show <RxC cls, not decoded>, read-only with 0 rows. A 0x0 variable still shows [ ]. There are exactly 6 warnings.
• Nested s.a and c{1} cases.
• A cut plain or compressed record warns once.
• A parser control, which passes before and after.
• A synthetic workspace, with no warnings.
• complex_ws.slx z at all 31 lengths of A model whose workspace part is cut short opens even when the cut lands in a complex variable #116's window.
• A text dictionary's cdata and a binary dictionary's hex. An untouched save writes them back unchanged.

Before the fix, 6 of the 7 failed on the row (null, [null], editable). With only the node half applied, cases 1 and 2 still failed because warnings was undefined, so the warning half fails for its own reason too. Mutation checks: dropping the dedupe fails only case 3. >= 0 in either bound fails case 1. Dropping the unknown exclusion fails exactly the two dictionary tests that pin a damaged class-unknown stream, so the exclusion stays.

Existing tests changed: none.

Left out:

• A cell element copies as its placeholder text. A top-level variable or struct field copies as the bytes it was read from, where before it copied as null.
• The legacy .slx modelworkspace.mat path passes on parseMat's warnings, so there this value warns. That path already warns for every other undecoded reason.
• dex-core's G81 should follow.

C-014: a text dictionary's MAT stream that does not decode (f8719f2)

Recommendation: "(c). It mirrors the existing reportUndecoded harvest and needs no change to the NodeClassType interface. Use a dedicated flag rather than _undecoded, so the char node's write-back is unchanged."

What was wrong: when a text dictionary's cdata failed to decode, it was shown as an ordinary char holding the encoded text. It was editable and raised no warning.

Root cause: a silent catch (_e) in MatlabVariableNode.parseCdata. NodeClassType.parse has no warnings channel.

Fix:

• There is still no interface change, and _undecoded is not used.
• The harvest reuses the per-entry decode-failure channel that the binary hex path already uses (recordDecodeFailure / takeDecodeFailures, drained by SlddNode.parse for each entry). Option (c)'s "post-build walk" would have been a second harvest in the same loop. Both arms of parseCdata now record the reason with shownAs = 'its encoded text', then build the same char as before.
• The char is marked _readFromStream = true, which is the dedicated flag, so it is display-only under the C-012 ruling.
• The write-back is unchanged, because _rawInput is replayed.
• MatlabVariable.md documents this.

Message: "c" holds a value stored encoded that could not be read, because its MAT stream did not decode (...); it is shown as its encoded text and saved unchanged.

Tests (new test/cdataDecodeFailure.test.ts, 10 cases):

• A damaged flags word in sparse_text.sldd c{1} gives exactly one warning, and every other entry is as in the intact file.
• c{1} is display-only and setProperty('Value') refuses it, while c{2} stays editable.
• An untouched save is byte-identical.
• A rename keeps the cdata and warns under the new name.
• A damaged whole-entry stream (nd_text.sldd A) warns and is display-only.
• Two damaged preambles (endian mark, reserved word) are covered.
• Guards: the binary hex message is unchanged, a failed paste is not reported against the next open, and all 23 intact text fixtures (99 streams) raise no warning.

Before the fix, 6 failed (warnings undefined, valueEditable true) and the 4 guards passed. Mutation checks: no record call fails 5 tests, no display-only flag fails 4, and hard-coding "not decoded" fails 5.

Existing tests changed: none.

Left out:

• The edit refusal still says the entry "is stored as a MAT-file stream", which is still true. The warning is what says the stream could not be read.
• Two cases pin V8's TypeError text.

The class-255 workspace variable: a flags word that is overwritten (7091bba)

Recommendation (agenda, group C): "(a) catch it per variable and leave that variable out, as #114 does for a struct array with no element read (the reviewer's suggestion: catch in addWorkspaceEntry) ... Recommendation: (a), which matches the ruling's 'no refusal'."

What was wrong: a variable whose flags word was overwritten (for example with 0xFFFFFFFF over complex_ws.slx's z) threw TypeError: Cannot read properties of null (reading 're'). That refused the whole model, or the whole .mat.

Root cause: the class is unknown with the complex bit set. That reaches _createFromMatNumeric's complex branch with a null value, and C-068's branch deliberately excludes unknown.

Fix:

• There is a per-variable catch in ModelSectionNode.addWorkspaceEntry (no warning, per C-232) and in MatNode.fromParsed.
• MatNode.fromParsed warns "z" could not be read (<reason>), so it is shown as not decoded. It skips that warning when an existing warning already names the variable or a part of it (z, z., z(, z{).
• A new MatlabVariableNode.createNotDecoded builds the row, and C-068's branch now uses it.

One departure from the recommendation: the caught variable is not left out. It is shown as a <1x1 unknown, not decoded> row that keeps its bytes. That follows the theme 1 ruling's "show what was read", and it matches how a dictionary already shows a damaged class-unknown stream.

Tests (new test/unmodelledClassVariable.test.ts, 18 cases):

• Four workspace variables (complex_ws.slx z, cases.slx cplxScalar and cplxVec, sparse_ws.slx dComplex), each with its parsed flags word (asserted to be class 6, complex) set to 3 values. Every other row and section equals the intact file's, with no warnings.
• The same damage nested in a cell and in a struct.
• Three .mat files, where the only warning is the reader's own.
• Nested .mat cases, which give exactly one warning per element.
• A host parse that keeps only a zz warning, which catches a bare prefix match.

Before the fix, all 18 failed on the TypeError and none on an assertion. Mutation checks: an exact-name-only match fails only case 17, a bare prefix match only case 18, no dedupe cases 14-17, and no fallback warning only case 18.

Existing tests changed: none. The two dictionary tests that pin a damaged class-unknown stream pass unchanged.

Left out:

• A real (not complex) value of an unmodelled class still opens as an editable null, class unknown. That is a display question, not a refusal.
• Damage nested inside a variable turns the whole top-level variable not decoded (the cell c, not only c{1}), as in the binary dictionary.

C-210: a System Composer definition with no type (f4150a9)

Recommendation: "(b), at low priority. A present-but-typeless record is damage, not absence, and the test's own comment calls the result 'a wrong answer that looks exactly like a right one'." Option (b) is: "Warn part-unreadable, naming the definition, from both the text and the binary catalog reader."

What was wrong: if a catalog definition lost its type, a StructType was shown as a Data Interface (its Simulink class), with no warning.

Root cause: both readers recorded a missing type as '' and stayed silent: SlddNode._parseSystemComposer for text, and ScCatalog.scanScXml for binary.

Fix:

• A new ScCatalog.untypedDefinitions(catalog).
• SlddNode.parse adds one part-unreadable per untyped definition, at the one place both formats pass through: The System Composer definition "X" has no type, so its Kind is taken from its Simulink class and may be wrong (a struct type reads as a Data Interface).
• The text reader also records a non-string type as ''.
• Unchanged: Kind still comes from the class. An absent or empty catalog stays silent, as measured against MATLAB. A type string that is present but not recognised stays silent.

Tests:

• slddNode.test.ts, new: a numeric type is recorded as '' with one warning. Controls: a FutureType string gives no warning, and pristine arch.sldd gives none.
• scCatalog.test.ts, new:
  • The type is cut from arch_binary.sldd's tag, which gives exactly one warning for StructType.
  • The same cut in its text twin arch_binary_as_text.sldd gives an identical warning list, catalog and Kinds.
  • Both intact files give no warning.
• Before the fix, 4 failed on an assertion and the 3 controls passed. Mutation checks: text-only, binary-only, modeled-types-only, no string check, and warning on an unrecognised type each fail their own tests.

Existing test changed: slddNode.test.ts "degrades a definition whose record lost its type to the entry's raw Simulink class". Its expect(warnings).toEqual([]) now expects two part-unreadable warnings, naming DataInterface and StructType. The test pinned exactly the silence this ruling removes; its own comment said "pinned rather than fixed". Its Kind and '' assertions are kept, and its comment and the file header are reworded.

Left out: the corpus was not re-measured. The scope found 0 untyped definitions out of 29,200 at 8e33408, and string types are read as before. vscode needs no change, since it shows warnings in the generic banner.