Use polymake's JSON format, require polymake 4

[fingolfin]

Resolves #22.

Net: +787 / −1224 lines.

What was there

polymaking spoke to polymake through the pre-4 plain format: it wrote files in
it, and pm_script_arg.pl stringified results so GAP could scrape them off
standard output. Rebuilding typed values from that text needed
ObjectConverters, a table mapping 58 keywords to hand-written parsers -- one
of which guessed whether a block was a matrix or a list of sets by checking for
a {.

What it is now

lib/pm.pl evaluates each requested property, serializes it with polymake's
own serializer, and writes one JSON file that GAP reads with the json
package. A file rather than stdout, because polymake's own output shares that
channel and one stray line would corrupt the document.

Values are decoded by polymake's type, not by keyword, so properties
polymaking has never heard of decode correctly too. What survives is only what
the type genuinely cannot tell us:

• stripping the homogenizing 1 (POINTS, VERTICES, REL_INT_POINT,
  VALID_POINT, VERTEX_BARYCENTER) -- VERTICES and FACETS are both
  Matrix<Rational> and only one is a list of points;
• two node indices that are plain integers (TOP_NODE, BOTTOM_NODE).

The 0-based to 1-based shift is derivable: Set<Int>, IncidenceMatrix and
GraphAdjacency are index containers, while Array<Int> (e.g.
FACET_DEGREES) holds values. That is what retires
ConvertPolymakeMatrixOrListOfSetsToGAP{,PlusOne}.

So convert.gd/gi (20 parsers), ObjectConverters.gd/gi (58 entries),
workaround_maps.gd/gi and pm_script_arg.pl are gone; json.gd/gi and
pm.pl replace them.

Consequences

• Files are written as JSON, so polymake never converts them and never says
  so. That is the remainder of Allow to silence certain polymake messages to stderr #23 -- verified: loading a polymaking-written
  file produces completely empty stderr.
• Nested properties are addressable: Polymake(poly, "HASSE_DIAGRAM.FACES").
  This is the "fully support HASSE_DIAGRAM again" the issue asks for. FACES,
  ADJACENCY and GRAPH remain as aliases.
• Polymake(poly,"GRAPH") works again -- on master it fails outright with
  POSITION_SUBSTRING: <string> must be a string.
• Keywords are evaluated independently, so one failure no longer discards
  the other results.
• Floating point properties return a GAP float instead of a rational
  approximation with a warning.

Things worth knowing before reviewing

Two findings changed the design, and both came from probing polymake 4.15
rather than from the docs:

Serializing a nested big object is a trap. It emits only the properties
that happen to be computed and storable, and carries no _type at all:

GRAPH         => {"CONNECTED":true}                       # ADJACENCY missing
HASSE_DIAGRAM => {"ADJACENCY":…,"DECORATION":…,…}          # FACES missing

Requested individually the same values are complete and typed. So polymaking
always asks for leaf properties, and GRAPH is an alias for GRAPH.ADJACENCY.

DIMS is genuinely gone. polymake 4.15 warns available properties insufficient to compute 'DIMS' and returns null, so it is not aliased. The
existing fail expectation in the test suite was recording exactly that.

Also worth noting: Rational and Integer serialize as JSON strings, even
when integral, and Vector<Integer> gives ["8","12","6"] while Array<Int>
gives [8,12,6] -- so the scalar decoder accepts both spellings. Sparse
matrices carry a trailing {"cols": n}; cube(3)->FACETS is sparse, so this
is a common path, not an exotic one.

Breaking changes

• polymake 4.0 or newer is required. polymake 3 cannot read the files
  polymaking now writes, so this is a hard error on the first call rather than
  an obscure later failure. The version is detected lazily; loading the package
  still spawns no processes. Users needing polymake 3 should stay on polymaking
  0.8.9.
• json is a new needed dependency.
• AppendToPolymakeObject(poly, name, value) takes a GAP value, not a
  string to append verbatim; JSON is not append-friendly, so the file is
  rewritten from the properties set so far. Consequently polymaking refuses to
  write to a file it did not create, instead of corrupting it.
• ConvertMatrixToPolymakeString, ObjectConverters and the
  ConvertPolymake... functions are removed.
• NamesKnownPropertiesOfPolymakeObject returns names in a different order
  (it always returned RecNames, i.e. unordered).

Testing

• Full suite: 0 failures in 4 files, under the default backend and under cdd
  and beneath_beyond.
• New tst/json.tst unit-tests the decoder against the exact shapes polymake
  emits: string and native scalars, big integers, sparse vectors and matrices,
  the trailing cols marker, index shifting vs. plain integer arrays,
  dehomogenization, and the writer.
• New integration checks that HASSE_DIAGRAM.FACES agrees with FACES, that
  GRAPH has the documented shape, and that the file on disk really is
  polymake JSON.
• Every decoded value was diffed against what the old converters produced for
  the same polytope before the old code was deleted.
• makedoc.g builds with no warnings and no unresolved references.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 87.75000% with 49 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.44%. Comparing base (661f50f) to head (702efbb).

Files with missing lines	Patch %	Lines
lib/construct.gi	81.60%	23 Missing ⚠️
lib/json.gi	92.90%	10 Missing ⚠️
lib/environment.gi	89.87%	8 Missing ⚠️
lib/userpref.gi	72.22%	5 Missing ⚠️
lib/Objects.gi	85.71%	3 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           master      #29       +/-   ##
===========================================
+ Coverage   72.23%   83.44%   +11.20%     
===========================================
  Files          15       11        -4     
  Lines         868      767      -101     
===========================================
+ Hits          627      640       +13     
+ Misses        241      127      -114     

Files with missing lines	Coverage Δ
lib/Objects.gd	100.00% <100.00%> (ø)
lib/construct.gd	100.00% <100.00%> (ø)
lib/environment.gd	100.00% <100.00%> (ø)
lib/json.gd	100.00% <100.00%> (ø)
lib/Objects.gi	71.18% <85.71%> (+11.75%)	⬆️
lib/userpref.gi	82.17% <72.22%> (-5.12%)	⬇️
lib/environment.gi	89.10% <89.87%> (+1.60%)	⬆️
lib/json.gi	92.90% <92.90%> (ø)
lib/construct.gi	81.48% <81.60%> (+6.93%)	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.