Fix TaggedValue Iterable masquerade and Enum socket handling

[elinscott]

Summary

Value handling across process boundaries, and — since the enum half of that turned out to be half a contract — where enum socket membership is decided at all.

TaggedValue Iterable masquerade (src/node_graph/socket.py)

isinstance(TaggedValue(1.5), Iterable) was wrongly True — even though actually iterating raised TypeError. TaggedValue.__new__ now dispatches to one of two private subclasses based on whether the wrapped value is iterable:

• _TaggedScalar shadows __iter__ = None, which makes the Iterable ABC subclass hook return False.
• _TaggedIterable keeps ObjectProxy's forwarding behavior.

Enum serialization roundtrip

Enums (incl. str-Enum / int-Enum) are now treated as structured leaves so they survive a process boundary:

• src/node_graph/utils/struct_utils.py: structured_type_info recognizes Enum; coerce_structured_value rebuilds the member from its bare serialized value
• src/node_graph/socket_spec.py: the spec attaches structured_type extras to enum sockets so coerce_inputs_from_spec can reconstruct the member.

Enum socket membership, decided once at assignment

Rebuilding the member on the way out of storage left membership being decided by that coercion — which runs twice, on two different representations. At build it sees the raw object; after serialization it sees the bare value. So a member of a different enum whose value matched was rejected at build and accepted at run, and which applied to a given input depended on where its graph sat rather than on the value. Membership is now decided once, where a value is set on a socket:

• TaskSocket._set_socket_value canonicalizes and checks — the one point an entry graph, a deferred sub-graph and a link from an untyped parent all pass through. Read-back becomes reconstruction with nothing left to reject.
• SocketSpec.__post_init__ applies the same rule to a socket's default, so a default outside the allowed set raises where it is written rather than being accepted in silence.
• Literal[...] derives an enum socket plus its allowed subset, or a base type plus allowed values; link compatibility compares the allowed sets, so Literal[A] flows into Literal[A, B] and not the reverse. Previously a Literal annotation produced a socket that accepted anything, and every Literal looked alike to the link checker.
• Two numbers match only when their types agree, so True is not 1; everything else matches on equality, so a value read back from storage still names its member.
• A refusal names the socket and lists the allowed values.

Deserialize hook in materialize_graph (src/node_graph/utils/graph.py)

New _deserialize_inputs walks the input namespace and applies adapter.deserialize to each leaf before the graph body runs. Symmetric counterpart to the existing serialize-on-write path: a @task.graph body whose signature declares a primitive should receive a primitive even if the engine wrapped it for provenance.

Testing

• TaggedValue regression coverage: a scalar wrapper is not Iterable and iter() raises while arithmetic/equality still proxy; list/tuple/dict/str/set wrappers stay iterable; the socket= tag survives both paths.
• The enum-coercion engine test now feeds the flattened form a str/int-Enum takes across a serialization boundary, so the coercion has a real member to rebuild rather than passing an already-typed value straight through.
• The membership rule is covered across all three graph shapes, with the accepted and refused cases beside each other: a foreign member whose value matches is accepted everywhere, while a value naming no member, a foreign member with no matching value, and a member whose name alone matches are refused at build. The name-only case is the control — a rule keyed on names rather than values would pass the others and fail that one.

[codecov]

Codecov Report

❌ Patch coverage is 93.20557% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.09%. Comparing base (8d85e61) to head (9605a89).

Files with missing lines	Patch %	Lines
src/node_graph/graph.py	57.14%	12 Missing ⚠️
tests/test_enum_literal_sockets.py	95.29%	12 Missing ⚠️
src/node_graph/link.py	92.18%	5 Missing ⚠️
src/node_graph/utils/struct_utils.py	93.05%	5 Missing ⚠️
src/node_graph/socket.py	92.30%	2 Missing ⚠️
src/node_graph/utils/graph.py	90.00%	2 Missing ⚠️
src/node_graph/socket_spec.py	98.11%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #151      +/-   ##
==========================================
+ Coverage   89.68%   90.09%   +0.41%     
==========================================
  Files          81       82       +1     
  Lines        8984     9525     +541     
==========================================
+ Hits         8057     8582     +525     
- Misses        927      943      +16     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[elinscott]

Update

The structured_type overlay this PR added for enums incidentally forced the socket to be required. SocketMeta.required is typed Optional[bool] but defaults to True, and merge_meta prefers any non-None overlay value — so a bare SocketMeta(extras={...}) republishes required=True over the value already computed from the parameter's default.

Now fixed by passing required=None, so the overlay says nothing about requiredness.

Worth noting the same shape exists on main independently of this branch: any Annotated[Optional[int], SocketMeta(help="...")] comes out required, because that overlay defaults the same way.

[elinscott]

Superseded by #177 (masquerade) and #178 (enum/Literal membership). Closing