Protocols and implementations

A protocol body contains function signatures.

impl Protocol<Type> supplies definitions for one protocol and a complete conforming type. An explicit binder list precedes the protocol name for a conditional implementation. The protocol application has exactly one conforming type argument. Type aliases are expanded, and generic heads match the resolved static type through type equality, not value subtyping. A protocol call chooses the conformance before execution.

impl Type declares receiver methods for a nominal type owned by the current module. For a generic receiver, write explicit binders before its complete target, as in impl<T> Box<T>. Those binders enter method signatures and bodies; a method may introduce its own nested binders. The first bare self retains the instantiated receiver type even if a method binder shadows an outer name. The existing receiver name, field-collision, and export rules apply to every instantiation.

A protocol declaration has no explicit type parameter list. Use Self for its conforming type. An explicit receiver binder is rejected during parsing with TPZ2001.

Within a protocol method signature, Self denotes the conforming type.

A protocol method has an implicit conforming type parameter named Self. It may occur in any parameter or result type. Methods may have no value parameters. A call infers Self from its arguments and expected result through the ordinary generic-call rules. An explicit call type-argument list supplies Self first, followed by the method parameters. Dispatch requires one resolved conforming type; a call without enough inference evidence must supply that complete list.

Every protocol method requires an explicit return annotation, including -> () for unit. An omitted annotation produces TPZ5022.

Protocol signatures use the type parameter, bound, annotated parameter, variadic, and default-expression rules of named functions. Method binders are distinct from implicit Self and are in scope throughout that method signature, including bounds and result types. They do not enter another method. Parameters remain immutable. Required fixed parameters precede the defaulted suffix; one final variadic parameter has no default and binds an array. The protocol declaration owns each default. Its names resolve in the protocol declaration environment, where value parameters are unavailable. Supplied arguments and omitted defaults follow ordinary call evaluation order.

Redeclaring a user protocol name in the same module produces TPZ3008 during resolution.

Declaring the same method name twice in a protocol produces TPZ5008.

Redeclaring the built-in protocols Eq, Order, Show, or JSON produces TPZ5008.

Reusing a declared type name for a protocol in the same module produces TPZ3008 during resolution.

A protocol or implementation declaration inside a block produces TPZ5022.

The implementing module must define either the resolved protocol or the target type's outermost nominal declaration. A module may therefore define its own protocol for int, string, a structural type, or a generic type pattern. A foreign protocol requires an own-module record, enum, or newtype as the target's outermost constructor. A local type argument inside a foreign Array or Map does not transfer ownership. Transparent aliases preserve the underlying type and its owner. Implementing a foreign protocol for a foreign type produces TPZ5520. Every admitted implementation also passes the complete dependency graph's uniqueness check.

An implementation supplies every declared protocol method and no undeclared method. A missing or undeclared method produces TPZ5022.

Implementing the same method twice in a protocol implementation produces TPZ5008.

Substitute the complete target for Self, keep implementation binders rigid, and pair method binders by position. Method binder counts, their sets of resolved protocol bounds, fixed parameter types, variadic position and element type, and result type must match. Type aliases and binder names do not create differences; bound order and parameter names do not affect a positional call. Repeated bounds still follow the ordinary duplicate-bound rule. The implementation may neither strengthen nor weaken a method's bound set. An explicit result annotation must equal the protocol result. When it is omitted, use the protocol result as the ordinary expected result while checking the body. Each return and tail must be assignable to that result; omission does not narrow the public signature. A signature mismatch produces TPZ5022.

An implementation method is checked as an ordinary function against the protocol signature. Matching method generics and a matching variadic tail are admitted, and the result annotation may be omitted. Method-level export and parameter-default initializers produce TPZ5022. Conformance visibility already exposes the promised operations, and the protocol declaration already supplies omitted arguments. An implementation cannot create a second export or default contract, even by repeating the same default expression.

At most one conformance may apply to a resolved protocol and normalized target type throughout the complete resolved dependency graph. Expand aliases, retain defining-module nominal identities, and rename each declaration's binders before comparing target heads. Heads overlap when some consistent substitution makes their full target types equal. Repeated variables must keep the same substitution. Different positive bound sets cannot establish disjointness, even when no current type satisfies both. Reject every overlap with TPZ5521 before module initialization, whether it is manual/manual, manual/derive, or derive/derive. A concrete implementation has no priority over a generic one. Declaration order, import order, aliases, and method bodies cannot choose a winner. Distinct heads that cannot unify remain independent. Overlap diagnostics use the target of the later manual declaration in deterministic dependency-first module and source order. A conflict involving derive points to the derived protocol head; two derives use the later clause by the same order.

An implementation places its type binders before its head, as in impl<T: Eq> Eq<Box<T>>. A receiver implementation uses the same placement, impl<T> Box<T>. Resolve the head to distinguish a protocol application from a nominal receiver; spelling, capitalization, and whitespace do not choose the meaning. Implementation binders scope over their bounds, the complete target type, and every method signature and body. Every implementation binder must occur in the target, so the selected target determines its arguments. Method binders have ordinary nested lexical scope and may shadow outer binders; matching uses resolved binder identities, never name strings. Each binder list has distinct names. A protocol method already has implicit Self in its binder scope. Bounds must have independent conformance evidence; an active obligation cannot prove itself. A generic nominal writes an explicit conditional derive binder list even when it has no bounds. Those binders scope only over that clause, correspond positionally to the nominal parameters, and may be renamed. Each derive target is the declaring nominal applied to all of those binders in declaration order. Fields and enum payloads keep the nominal declaration binders. Concrete and conditional manual and derived conformances use the same uniqueness rule.

Resolve the protocol and method, then apply the ordinary generic-function call rules. The call type-parameter list is Self followed by the method binders in declaration order. Infer the complete list, or write it after the method name as Protocol.method<Receiver, MethodType>(arguments). Implementation binders are determined by the selected conforming type and are not extra call arguments. Parentheses around the callee preserve the same declaration signature. No separate Protocol<Type>.method call form is introduced.

Check conformance for the resolved Self type, independently of whether a value of that type occurs first, later, or only in the result. A generic body may use its declared protocol bound as conformance evidence. A concrete type without the required conformance produces TPZ5522. Dispatch uses that one conformance and does not select an implementation from the runtime value or from argument order.

Protocol calls supply positional values and may spread an array into a declared variadic tail. Fixed omissions use the protocol defaults. The callee and supplied arguments are evaluated once from left to right; missing defaults follow in parameter order. Spread cannot fill an unsatisfied fixed slot. A named argument is rejected during parsing with TPZ2001, as in every other call.

A function protocol bound checks the inferred concrete type argument through conformance lookup. An unsatisfied bound produces TPZ5522.

Manual and derived conformances are available in the defining module and in modules that import the nominal type. Import aliases preserve that conformance.

Resolve a conformance by the protocol declaration identity and the normalized receiver type. User protocols and nominal types retain their defining module through selected or namespace imports and aliases. Same-spelled declarations in different modules remain distinct. Manual and derived conformances in the resolved dependency graph participate in the same coherence check. Import paths, aliases, and item order do not create or select another conformance. A manual call uses the implementation from the conformance-defining module. A receiver without an applicable conformance is rejected with TPZ5522. Conformance ownership and overlap follow the implementation rules.

A protocol declaration creates a non-value protocol binding in the same lexical and module name table as other declarations. It is private unless prefixed with export. Selected imports, selected aliases, and namespace imports resolve that binding by its defining module and declaration. Use P or ns.P in protocol bounds and conformance heads, and P.method or ns.P.method for calls. Aliases preserve identity; equal spellings in different modules remain different protocols. A same-scope name collision follows the module duplicate-binding rule. A nearer value or namespace owns an expression member access and is not reinterpreted as a protocol. Eq, Order, Show, and JSON remain predeclared protocol identities. Protocol names are not runtime values or nominal value types. A public callable may expose a user-protocol bound when that protocol is exported; a private bound is rejected with TPZ5524. Exported protocol method signatures obey the ordinary public-type visibility check. Importing a public type does not implicitly export the private protocols in its defining module. Derive eligibility is unchanged by importing a protocol name.

For a nongeneric record, enum, or newtype, derives requests Eq, Order, Show, or JSON conformance. Another protocol name produces TPZ5530.

Show derivation for a nongeneric record, enum, or newtype requires no member capability test. A newtype is displayed by its type name followed by its rendered base value in parentheses.

Eq, Order, and JSON derivation check every record field, enum payload, or newtype base for equality, total ordering, or both JSON conversion operations. Each operation uses the capability domain described below. JSON decoding follows the declared normalization rules, including Option null conversion. A member that lacks the required capability produces TPZ5530.

JSON is an ordinary conformance with encode(value: Self) -> Result<JSONValue, string> and decode(value: JSONValue) -> Result<Self, string>. An implementation supplies both methods. An empty marker produces the missing-method error TPZ5022. The ordinary protocol call rules infer Self or select it through the first explicit call type argument, as in JSON.decode<Token>(tree). std.json.stringify calls encode and then the canonical JSONValue writer. std.json.parseAs<T> parses the text and calls the same decode implementation selected by JSON.decode<T>. A codec returns an Err result for invalid input or a value it cannot encode. These failures do not become checker diagnostics. The manual decoder owns the accepted JSONValue shape. Derived record decoders ignore unknown object fields and use declared field defaults when a field is missing. A missing required field, wrong kind, unknown enum tag, or wrong payload arity returns an Err result. Malformed text fails before the decoder is called. JSON promises both conversion operations, with the representation and normalization defined for the type. Conversion may normalize distinct source values to the same decoded value. Existing Option conversion maps None() to null and Some(v) to the representation of v, so Some(None()) and Some(()) normalize to None() when decoded through an enclosing Option. Decode a JSONValue with JSON.decode<T>(tree). The receiver member tree.decode<T>() is removed and produces the ordinary missing-member diagnostic TPZ5006. Parsing text and writing text remain distinct operations through parseAs and stringify.

The built-in method signatures are Show.show(value: Self) -> string, Eq.equals(a: Self, b: Self) -> bool, Order.compare(a: Self, b: Self) -> int, JSON.encode(value: Self) -> Result<JSONValue, string>, and JSON.decode(value: JSONValue) -> Result<Self, string>. JSONValue is the parsed JSON tree type exported by std.json. JSON decode uses the ordinary protocol rule for selecting Self when there is no conforming input value.

Deriving Eq, Order, or JSON composes the same operation on every record field, enum payload, or newtype base. A nested nominal uses its applicable manual or derived conformance after type arguments are substituted in its defining module. A manual method replaces structural inspection of that nominal; an outer derive must not bypass it or reject it because of private representation fields. A nested nominal with no required conformance produces TPZ5530. Built-in component families use the corresponding operation domain below.

Declared recursive and mutually recursive conformances may refer to one another. A recursive edge closes a declared conformance reference; it does not excuse a missing component capability elsewhere in the cycle. Establish each conditional instance using independent generic bound evidence before linking its recursive descriptors. An active generic bound cannot prove itself; a back-edge between already applicable declared derives is a descriptor reference, not evidence for that bound. A descriptor is identified by defining module, nominal declaration, and normalized type arguments. Keep references and captured substitutions and instantiate them as values are traversed, rather than eagerly expanding a schema tree. Imported aliases keep the same descriptor identity. Conditional generic instances follow the ordinary binder and coherence rules.

A derived JSON decoder follows the finite input tree. Each recursive aggregate step consumes a child JSON value; a descriptor loop that revisits the same input without structural progress returns Err. JSON starts at depth zero, permits depths through 128, and increments depth when descending to a record field, array element, map value, or enum payload. Descriptor references, Option wrapping, and newtype wrapping do not add a level. Data values follow value semantics. A depth above 128 returns an Err string beginning JSON_LIMIT:. The same traversal context covers nested derived dispatch. Descriptor expansion does not reset it. Manual method bodies retain ordinary function evaluation and resource behavior.

Derived equality and ordering use the same nested conformance as direct protocol calls. A declared nominal Eq or Order implementation also supplies the corresponding comparison operators, so moving a comparison inside a wrapper does not change its meaning. A structural comparison that exhausts its budget raises the existing TPZ5007 guard. Show retains its total debug rendering operation and does not introduce an Eq, Order, or JSON member requirement.

Derivation follows the operation it generates. Eq asks whether two values are equal. Order supplies a total comparison. JSON supplies conversion to and from a JSON tree under the type's documented representation. These are different obligations, so admission is determined by the operation rather than a common whitelist. A nested nominal always uses the conformance described above. This table defines the listed component families; it does not assign capabilities to other built-ins. Duration capabilities follow its operations rule.

Map and Set equality reuse the key identity already used by lookup and membership. A custom Eq method does not replace stored-key equality. Map values use their Eq operation, including a manual nominal implementation. Insertion order does not affect either equality result. Functions and resources have no data-value equality, and regex denotation has no general equality operation. JSONValue and TOMLValue preserve representation information and require decoding or an explicit projection into the intended equality domain. Templates, ranges, mutable ByteBuffer values, and namespaces likewise have no automatic Eq conformance. Bytes compare bytes; Path and URL compare their canonical representations; Date, BigInt, and Decimal compare their values; Match and RoundingMode retain their declared value equality. IEEE equality is not an equivalence relation for NaN-containing values: NaN differs from itself and positive and negative zero compare equal. Eq does not promise otherwise.

For Order, Bytes compare bytewise; Path and URL compare canonical strings; Date compares calendar days; BigInt and Decimal compare numbers. A record uses sorted field names, including a nominal record, so rearranging declarations cannot change priority. A derived enum compares variant names in Unicode scalar order and then positional payloads. A newtype compares its base. Each component must itself have Order. Map and Set describe membership rather than a selected key order; a heterogeneous union has no declared cross-type priority. A nominal manual implementation can state those application-specific choices. Float keeps its ordinary IEEE relational predicates, which may all be false for NaN, and therefore does not satisfy total Order. Opaque families without a declared total order do not gain one through derivation.

JSON uses the existing record object, enum tag/values object, and transparent newtype representations. Result uses the enum representation rather than treating an Err payload as codec failure. Option converts through null and its payload values. Some(None()) and Some(()) can decode as None(). This normalization can map distinct source values to the same decoded value. JSONValue conversion preserves its tree, including stored number lexemes. Semantic scalar types such as Bytes, Path, URL, Date, BigInt, Decimal, Match, and RoundingMode need an explicitly chosen external schema through a nominal manual JSON implementation. Conversion does not silently pick a binary encoding, path base, unit, precision loss, or tag convention. Functions, resources, and templates cannot be reconstructed as data values. Derived conversion failure is TPZ5530 when a component type has no JSON capability. Malformed data and value-level encoding failures return an Err result during conversion.

Finite float encoding chooses the shortest decimal significand that recovers the identical binary64 value under nearest, ties-to-even decoding. If shortest candidates differ, choose the decimal closest to the exact binary value, then the candidate with an even final significand digit. Render fixed notation when the normalized decimal exponent is at least -6 and below 21; otherwise use lowercase e, with no plus sign or redundant exponent zeroes. Omit redundant fractional zeroes. Positive zero is 0 and negative zero is -0. A nonfinite input returns Err without substituting null or a string. Decoding accepts any JSON number, including integer lexemes, rounds once to binary64 with nearest, ties-to-even, preserves a negative zero sign, and rejects overflow to a nonfinite result. Underflow rounds to a finite subnormal or signed zero. The shortest-number rule applies when encoding a float; parsing and re-serializing an existing JSONValue preserves its accepted number lexeme, and numberText/asInt retain their existing semantics. Recursive conversion follows the depth rule above and value semantics. Show remains the total debug-render operation and has no member capability gate.

Conformance uniqueness