Swift SDK: edge checks refuse duplicates and full ends, check moves, and carry refusal details #819

Summary

The Swift SDK's working copy now refuses a duplicate edge and an edge that would overfill an end in Edges.check(from:to:type:) and in the edge writes, gains Edges.check(_:moving:) to check an edge move before it is made, and carries the core's structured details on MarfaError.validation. Developers of Swift apps that write edges need to know all three, and the third breaks code that matches MarfaError.validation.

Context

Carried by the next marfa-swift release, from withmarfa/marfa-swift#445. It pins the marfa core from withmarfa/marfa#2629 (bfeca9818f9def67bb5e0f2d29ae0cae99df4e9e, to be tagged v0.0.58).

This follows #815, which covers the core, the CLI and the Node module and says the Swift SDK pages change once marfa-swift exposes the move check. This is that change.

What changed for a Swift app:

• Edges.check(from:to:type:) judges two more refusals. As well as an end in the bin, an end's type, nesting and a cycle, it now refuses validation with code edge_constraint_violation when the edge would repeat an edge of the same type between the same two items, or would give an end that holds its one edge of the type a second one. create(from:to:type:), update(_:_:) and the edges of an item create are refused the same way before anything is queued. The order is the core's: an end in the bin, an end's type or nesting, a duplicate, cardinality, a cycle.
• New move check. Edges.check(_ id: String, moving move: EdgeEdit.Move) async throws answers what update(_:_:) would throw for the same move, and queues nothing.
• MarfaError.validation gains details. It is now validation(code: String, message: String, details: JSONValue?). For a refusal of an edge write by the working copy, details is the core's object: details["constraint"] is "duplicate" or "cardinality" for the two new refusals, "nesting" for nesting, and the object also names the edge type and the items or end concerned. It is nil for every other refusal, including a server's answer to a direct request. This is a breaking change: code that matches .validation with two bindings must add a third.
• Correction to Working copies refuse duplicate and cardinality-breaking edge writes, and check moves #815. That issue says a device refusal carries no details.constraint. At the core pinned here, it does: the working copy's duplicate and cardinality refusals carry details with constraint, which the Swift SDK now exposes.

Acceptance criteria

• The Swift SDK pages say that Edges.check(from:to:type:) and the edge writes refuse a duplicate and a full end, in the core's order.
• The Swift SDK pages document Edges.check(_:moving:).
• The Swift SDK pages document details on MarfaError.validation and how to read details["constraint"].
• No page says a working-copy refusal carries no details.constraint.

Out of scope

• The CLI and Node module changes, which Working copies refuse duplicate and cardinality-breaking edge writes, and check moves #815 covers.

Notes

Pages that likely change:

• Items and edges: today it says check judges only an end's type, nesting, the bin and a cycle, and that a move is refused when the end that stays can hold more than one edge of the type.
• Errors and testing: where MarfaError.validation is described, and the fake copy in MarfaTesting, which now makes the same refusals.