SY-4068: Strongly Typed Schematic Node and Edge Configs

[emilbon99]

Issue Pull Request

Linear Issue

SY-4068

Description

Replaces the schematic's opaque per-element config storage with a fully typed model, end to end. The schema now declares every symbol and edge configuration: a NodeConfig union over all 100 node variants (44 static labeled symbols, 31 telemetry-actuated toggles, and 7 local dummy toggles share three payload structs; the remaining 18 symbols get bespoke structs), an EdgeConfig union over the 7 edge styles, and an ElementConfig union composed from both via union extends. The configs map flips from map<string, record> to map<string, ElementConfig>, so configs are validated on every write path instead of trusted: the Go reducer decodes merged action payloads through the union (normalizing the camelCase keys the Console previously stored verbatim, with telem props and custom-symbol state overrides exempt since their keys are semantic), and the TS reducer parses through elementConfigZ for parity.

Pluto's hand-written schemas become re-exports of the generated ones: symbol and edge factories resolve their config schemas from the generated schema maps, every singleton config file re-exports its generated variant schema, and the registries' variant enums come from the generated types with satisfies guards against schema/registry drift. Telemetry source/sink references are modeled as single-variant unions on value_type with role-pinned variants and opaque, factory-validated props, preserving the existing per-value-type compile-time narrowing. Border radius moves into a new border module following the color pattern: a canonical generated struct with a crude-accepting Go UnmarshalJSON and a hand-written crude zod union in x.

Optional config fields whose absence is meaningful (enums, colors, dimensions, telem specs, nested configs) are hard-optional so absence round-trips faithfully instead of collapsing to zero values that downstream optional schemas reject; only fields where zero and absent coincide stay soft-optional. Map keys stay verbatim on the wire via the new preserve_keys domain while value fields convert like any typed payload.

Storage migrates losslessly: the migration chain re-anchors on the v56 snapshot, the v55 blob lift moves into the v56 mirror package, and a new v56_typed_element_configs step normalizes stored camelCase config keys and decodes them into the union, dropping entries that match no variant. Without the migration, pre-flip datastores would silently shed multi-word config fields on read.

Stacked on #2416, which gained the generator capabilities this branch exercises: union composition via extends, union pb translators and orc codec support, multi-word discriminator camelization, nil-variant null marshaling, the preserve_keys caseconv mode, and skipping auto-copy for fields whose union-ness changed.

Basic Readiness

• I have performed a self-review of my code.
• I have added relevant, automated tests to cover the changes.
• I have updated documentation to reflect the changes.

Greptile Summary

This PR replaces the schematic's opaque map<string, record> config storage with a fully typed map<string, ElementConfig> union covering all 100+ node variants and 7 edge styles, validated end-to-end on every read and write path. A two-step migration chain (v55→v56 blob lift, then v56→current key normalization + telem arg extraction + union decode) converts existing stored camelCase configs losslessly, with the same logic mirrored in the TypeScript console migration.

• Migration pipeline: v56/migrate.go does the structural reshape (node/edge lift, stump stripping); migrate.go does the new v56→current step that normalizes camelCase keys, extracts legacy telem pipeline specs into semantic args (channel, rolling_average, etc.), and decodes through the typed union—dropping only entries that fail to decode.
• Action handlers (SetNodePayload, SetConfigPayload) now run every write through normalizeConfigKeys + decodeElementConfig, rejecting configs that match no known variant; telem arg extraction is intentionally omitted from the live write path since new Console clients use the semantic-arg schema directly.
• Border radius gains a new module with a custom UnmarshalJSON that accepts bare numbers, {x,y} pairs, per-corner numbers, and the canonical per-corner pair form for backward-compatible deserialization of legacy data.

Confidence Score: 5/5

Safe to merge; the migration chain is correctly ordered and losslessly converts stored camelCase configs to the typed union, and the live write path rejects invalid configs rather than silently storing them.

All migration steps are well-tested with snapshot fixtures, unit tests for telem extraction, and an end-to-end schema validation test on the Console side. The three concerns flagged in earlier review threads are the only known issues, all of which affect theoretical paths or documentation rather than data correctness. No new correctness issues were found during this review.

core/pkg/service/schematic/actions.go — the edge source-color inheritance guard has a logic inversion noted in a previous thread. core/pkg/service/schematic/migrate.go — the doc comment on the drop condition is broader than stated, also from a previous thread.

Important Files Changed

Filename	Overview
core/pkg/service/schematic/convert.go	New file implementing camelCase→snake_case key normalization, opaque field handling for telem pipeline props, and legacy telem arg extraction. Logic is correct and mirrors the TS side faithfully.
core/pkg/service/schematic/migrate.go	New v56→current migration step: normalize keys, extract telem args, decode through typed union. Previously-flagged doc comment understates the drop condition (any decode failure, not just unknown variants). Core logic is sound.
core/pkg/service/schematic/actions.go	Write handlers now validate configs through the typed union. Edge color inheritance has a theoretical logic inversion flagged in a previous review thread. Source-color path works correctly in all current callers since marshal of opaque maps never fails.
core/pkg/service/schematic/migrations/v56/migrate.go	v55→v56 migration moved here from the top-level package; reshapes nodes, edges (stump stripping), and props. Logic is unchanged and correct.
console/src/schematic/types/v6.ts	Adds extractTelemArgs mirroring the Go logic and applies caseconv.camelToSnake to variant keys during props-to-configs migration. Edge and node paths are symmetric with the server side.
x/go/border/border.go	New border package with custom UnmarshalJSON accepting four legacy radius shapes; well-tested with round-trip test. Corner key aliasing (camelCase/snake_case) enables lossless migration of pre-typed configs.
core/pkg/service/schematic/service.go	Inserts the new v56_typed_element_configs migration step between v55_lift_typed_schematic and the current schema; dependency chain is correctly ordered.
console/src/schematic/services/import.spec.ts	New test cases cover camelCase→snake_case variant normalization, telem channel extraction, rolling average, zero-channel sentinel, authority extraction, and end-to-end schema validation for legacy imports.
core/pkg/service/schematic/actions_test.go	Updated tests now use typed configs and helper factories; adds rejection test for configs that match no variant. Covers all previously tested scenarios plus the new validation contract.
core/pkg/service/schematic/migrations/migrate_test.go	Updated to run the full two-step migration chain; adds tests for telem arg extraction and camelCase key normalization through the typed union. Existing edge/stump tests adapted for typed config assertions.
x/ts/src/border/border.ts	New TS border module exporting radiusZ with four accepted formats as a zod union, matching the Go custom unmarshaler.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[v55 Schematic\nopaque blob] -->|v55_lift_typed_schematic| B[v56 Schematic\nConfigs: map string EncodedJSON]
    B -->|v56_typed_element_configs| C[Current Schematic\nConfigs: map string ElementConfig]

    subgraph v56_step["v56→current: migrateConfigEntry"]
        D[normalizeConfigKeys\ncamelCase→snake_case keys\nvariant value normalized] --> E[extractTelemArgs\nlift telem pipeline specs\ninto semantic args]
        E --> F[decodeElementConfig\nvalidate through\nElementConfig union]
        F -->|decode fails| G[drop entry silently]
        F -->|decode succeeds| H[typed ElementConfig]
    end

    B --> D

    subgraph live_write["Live Write Path: SetConfigPayload.Handle"]
        I[p.Config EncodedJSON] --> J[normalizeConfigKeys]
        J -->|existing entry| K[elementConfigFields\nmarshal→unmarshal typed→map]
        K --> L[maps.Copy merge]
        L --> M[decodeElementConfig]
        J -->|new entry + edge| N[source color inheritance\nfrom srcCfg]
        N --> M
        M -->|error| O[return error to caller]
        M -->|ok| P[store typed ElementConfig]
    end

Loading

_{Reviews (2): Last reviewed commit: "Merge branch 'sy-3999-oracle-support-for..." | Re-trigger Greptile}