[v2] Add spec-level base attributes and give every node a plugins list

[lorisleiva]

Today in v1

The spec defines a pluginNode — a named bag of consumer-defined data that Codama carries through the graph verbatim:

{ "kind": "pluginNode", "name": "explorerHints", "payload": { "icon": "transfer-arrow" } }

But only instructionNode has a plugins attribute to attach them to. Custom data cannot be attached to accounts, types, errors, programs, or the root. codama-idl/codama#73 asked for plugins on RootNode alone; this proposal generalises it to every node.

Proposal

Two changes, one to the meta-model and one to the v2 spec content:

1. Base attributes in the meta-model. The Spec type gains an optional base block declaring attributes that every node has. Codegen targets append them after each node's declared attributes and may emit a shared BaseNode interface. This is version-agnostic and additive: v1 declares no base attributes and is unaffected.

interface Spec {
    version: string;
    base?: { attributes: AttributeSpec[] };
    categories: CategorySpec[];
}

2. v2 declares one base attribute: plugins, an optional array of pluginNode, on every single node.

{
    "kind": "errorNode",
    "name": "invalidAmount",
    "code": 6000,
    "message": "Amount must be greater than zero.",
    "plugins": [{ "kind": "pluginNode", "name": "explorerHints", "payload": { "severity": "warning" } }]
}

Decisions

• Base attributes serialise after declared attributes, so plugins always comes last. The existing empty-array convention applies: an absent plugins means "none".
• Plugins are the sanctioned escape hatch for renderer-specific or not-yet-standardised features. Several other v2 changes lean on this: resolver migration ([v2] Replace instruction arguments with a single data type node #131), translations ([v2] Introduce textNode for all human-facing text #133), and deferred ideas like has_one constraints ([nodes] has_one account resolution codama#605).
• Plugin name becomes a dot-separated namespace (e.g. i18n.es) — specified in [v2] Rename name to identifier and drop the casing mandate #129.

Open question

Should docs also become a base attribute, giving every node documentation? Today some nodes (most type nodes) have no docs attribute at all.

Migration

upgradeV1ToV2 copies instructionNode.plugins as-is; no other v1 node carries plugins.

---

Part of #102 — Tier A.

[lorisleiva]

Resolving the open question: docs does not become a base attribute. Only 14 of 95 nodes carry docs today — the named, user-facing entities — and the 81 that would gain it are structural plumbing with no rendering surface for documentation. The decisive argument is ordering: base attributes serialise last, while docs deliberately sits next to name for IDL readability (as a base attribute, programNode.docs would serialise after the entire instructions array). The one genuine gap is enum variants, which is better fixed surgically: the unified enumVariantTypeNode in #127 should gain an optional docs, matching structFieldTypeNode. If #133 later changes the shape of documentation text, that decision composes either way.

Implementation in #135.