fix: an ingest refusal at a typed union names the admitted types

[dereuromark]

What

When no branch of a typed node union matches, the refusal names the offending type and the admitted set instead of a required field from whichever branch happens to be first.

Why

figure.target admits an image, a block quote, a table, a code block or a paragraph. Feed it a node of a type the position does not admit - a heading, say - and this engine refused the payload, correctly, and then described the wrong problem:

Error: The payload does not satisfy the AST schema: $.children[0].target is missing
`src`, which the schema requires. PART 12 §12(d) validates the whole payload against
`resources/ast-schema.json` ...

src is the required property of the image branch, which is simply the first alternative in the oneOf. A producer reading that message would add src to a heading.

carve-js, from the same schema, says the useful thing:

a "heading" node sits where the schema admits only block_quote, code_block, image, paragraph, table

The cause

AstSchema::checkComposition returns $first, the failure of the first branch that failed, whenever no branch of an anyOf or oneOf matched. For a union of typed node definitions that is nearly always the wrong story: the branches differ by TYPE, so the first one's missing field is an artifact of branch order rather than a fact about the payload.

What changed

A union of typed node definitions now reports the type mismatch:

$.children[0].target holds a "heading" node where the schema admits only
block_quote, code_block, image, paragraph, table

Two conditions are required before that message is built, and anything else keeps $first exactly as before:

• the value identifies itself as a node, carrying a string type;
• every branch resolves to a schema pinning a type constant.

That is what stops the change from swallowing a useful message. An image at figure.target with no src is a type the position DOES admit, so the missing field is the real problem there and is still what gets reported. A target that is not even an object keeps its missing-type report.

Which payloads are accepted and refused does not change; only what the refusal says.

The fixture is a heading on purpose

A block_quote would have read better and is deliberately not used: markup-carve/carve#1161 removed it from the admitted set and markup-carve/carve#1213 has since put it back, so a case built on it would have asserted the opposite of the pinned schema within days. A heading is not a captionable host under any version of the clause. The admitted set inside the expectation moves with the spec pin; the refused type does not.

The four tests pin the four paths: a refused type, an admitted type missing a field, a value with no type at all, and a legitimate image target.

Related

markup-carve/carve-rs#982 is the reciprocal gap: carve-rs accepted that same payload rather than refusing it. markup-carve/carve#1211 adds the schema-side test for the admitted set.

[codecov]

Codecov Report

❌ Patch coverage is 84.00000% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Ast/AstSchema.php	84.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[dereuromark]

Still valid, with one edit pending. The diagnostic change stands on its own - a typed node union should name the admitted types rather than the first branch's required field. But the new test uses a block_quote at figure.target as its example of a refused type, and the section 4a revert makes block_quote an admitted target again. The example moves to a type that is genuinely not admitted (a heading, which the existing data provider already uses). Holding until the revert lands in markup-carve/carve.