fix: correct the v4 catalog envelope and compiler edge wire shapes, a…

[alvagante]

…dd --debug

Two wire-shape assumptions were wrong against a real compiler, each making a successful compilation surface as a PIACE failure.

v4 response envelope. POST /puppet/v4/catalog returns {"catalog": <document>}; POST /puppet/v3/catalog/:node returns the document directly. PIACE read both unwrapped, so a v4 body decoded into wireCatalog with every field absent and was reported as "malformed or unparseable compiler catalog response" against a compiler whose own log recorded a successful compile. catalogDocument now unwraps, keyed on the API that served the response — never target.Candidate.CatalogAPI, which is v4 on the permitted v4-to-v3 fallback path while the response in hand came from v3. No shape sniffing: that would accept either envelope from either endpoint and mask a compiler returning the wrong one.

Sources: puppetserver's compiler.rb returns { catalog: catalog } and master_core.clj's v4-catalog-fn encodes it verbatim; openvox's api/docs/http_catalog.md shows the bare v3 document.

Edge vertex form. A compiler serializes each edge vertex as a Type[title] reference string (Puppet::Relationship#to_data_hash calls source.to_s/target.to_s), not the {type, title} object of PuppetDB's wire format v8 — that object form is produced by the PuppetDB terminus, which converts the strings itself in munge_edges. resourceSpecWire now accepts both, splitting the string with a faithful port of the terminus's own resource_ref_to_hash regex: type stops at the first bracket, title runs greedily to the last, so a composite title such as File[/etc/foo[bar]] survives. Using that exact regex is what makes a candidate identity line up with the PuppetDB baseline's stored source_type/source_title, which the same function produced. A non-matching reference is a reported normalization diagnostic; the Ruby original yields {nil, nil} there, which this package's contract forbids.

Both doc.go files stated the wrong shape outright and are corrected in place, citing the compiler and terminus sources rather than the previous "documented but unverified" framing.

The test fixtures encoded both bugs: internal/compiler served one unwrapped shape from both endpoints, and cmd/piace's compilerCatalog built edge vertices as objects no compiler emits. Both are corrected, with regressions pinning each envelope in both directions, the fallback path's v3 shape, composite titles, mixed vertex forms, and unparseable references. One acceptance test was using the catalogs map to inject a 200 {"error":...} body; that moved to an explicit rawBodies hatch, since a real semantic rejection arrives non-2xx.

--debug. Both failures were diagnosable from one fact PIACE never showed: the response body's top-level keys. An Observer hook on transport.Client.Do — the single chokepoint every compiler and PuppetDB request passes through — feeds two options on all three subcommands:

--debug method, URL, status, duration, body sizes, content
type, and the response's top-level JSON member
names, to stderr. Member names, not values, so it
stays inside requirements.md 3.5 and is safe for a
CI log.
--debug-dump-dir DIR verbatim request/response bodies, 0600 files in a
0700 directory, never a console. Documented in
code and README as a deliberate, operator-requested
bypass of the redaction boundary rather than as
something safe.

Observation is inert: an acceptance test asserts --debug changes neither stdout nor the exit code.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.