feat!: name-based linkage, field-side declarations, and anchored timers (v4.0.0)

[kamronbatman]

Summary

The v4 redesign of field↔method linkage and timer serialization, per the agreed design: order-based linkage is removed outright (v3.0.0 is the last release supporting it), linkage is declared on the field only, and timers become intuitive, anchored, and gated.

New surface

One linkage style — everything is declared on the serializable field, naming its companion methods:

[SerializableField(0)]
[SaveFlag(nameof(ShouldSerializeCharges), nameof(ChargesDefaultValue))]   // default method optional
private int _charges;

private bool ShouldSerializeCharges() => _charges != 8;
private int ChargesDefaultValue() => 8;

// Setter hooks are arguments of [SerializableField] itself: they configure the generated
// setter, like the getter/setter/isVirtual arguments.
[SerializableField(1, allowFieldChange: nameof(AllowLevelChange), fieldChanged: nameof(OnLevelChanged))]
private int _level;

private bool AllowLevelChange(ref int value)
{
    value = Math.Clamp(value, 0, 100);   // coerce, or return false to veto
    return true;
}

The generated setter pipeline is equality check → allowFieldChange (coerce/veto) → assign → dirty tracking → fieldChanged. The gate needs no oldValue parameter: it runs before assignment, so the field itself still holds the old value.

The method-side attributes ([SerializableFieldSaveFlag], [SerializableFieldDefault], [SerializableFieldChanged]) are removed entirely. Field-side declaration makes the old failure modes unrepresentable by construction: a default cannot exist without a save flag, a linkage cannot reference a missing field, duplicates are compiler-enforced (AllowMultiple = false), styles cannot conflict, and setter hooks cannot be declared on a [SerializableProperty] — whose user-written setter they could never hook. [SaveFlag] and [DeserializeTimer] remain standalone attributes because they are serialization concerns that legitimately apply to both fields and properties (property support unit-pinned).

Why the gate earns its place: a survey of all 204 [SerializableProperty] sites in the engine found value coercion (clamps, value ?? \"\" normalization) to be the single largest reason for hand-written setters (~50 sites), ahead of post-change side effects (~55, covered by fieldChanged) and vetoes (~5). With both hooks, roughly three quarters of hand-written properties become expressible as plain [SerializableField] declarations; hand-written properties remain for custom getters (~45 sites) and exotic setter semantics.

Timers — one attribute on the field, replacing [TimerDrift] + [DeserializeTimerField]:

[SerializableField(0)]
[DeserializeTimer(nameof(RestartDecayTimer))]      // drift default → anchored time
private Timer _decayTimer;

Drift stores Next as anchored time (downtime no longer consumes the remaining delay, bytes are save-stable); wallClock: true keeps absolute deadlines with the unchanged format. The restart method is invoked only when a timer was running — the TimeSpan.MinValue sentinel is gone.

Compatibility

• Removed attributes remain as error-[Obsolete] shells whose messages are the migration instructions; the generator carries zero support code for them.
• The "@TimerDrift" delta-time read fossil survives permanently for old-version migration schemas — pinned by a fixture whose v0 schema replays ReadDeltaTime while the current version reads anchored time, in the same generated file.
• Save-flag/default/changed conversions are wire-neutral (their Expected snapshots are byte-identical across the change); only drifting timers change bytes and need a class version bump + MigrateFrom. The setter hooks never touch the wire.

Diagnostics

With the mistakes unrepresentable, most of the planned diagnostics deleted themselves: SG3010/SG3014/SG3016/SG3017 are retired (numbers reserved, never reused). What remains is SG3015 — the named method is missing or has the wrong signature — covering save-flag, default, changed, gate, and timer shapes, none of which were validated before v4 (mistakes silently generated broken code) — plus new SG3018: a setter hook (fieldChanged or allowFieldChange) on a field with no generated setter (readonly, or omitted setter), where it could never fire. SG3008 is reworded for [DeserializeTimer].

Also

• README: the install snippet named a nonexistent package id at a stale version — fixed; v4 patterns and a migration guide documented.
• Back-to-back benchmarks vs main on identical machine state: warm single-edit 18.7 → 19.8ms, cold ~equal, overlapping error bars — no measurable impact.
• 101/101 tests green, in both snapshot-pin and regeneration modes; the gate emission is compile-gated in the FieldSideLinkage snapshot and the pipeline order is unit-asserted. Packages bump to 4.0.0.

The engine-side migration (~240 linkage sites; 8 drift-timer classes with version bumps) follows as a separate PR after publish, scripted — and can now also fold eligible [SerializableProperty] sites down to [SerializableField] with hooks.