Design canonical Workshop element-count cost analysis

[Teakowa]

Goal

Define and implement a canonical Workshop element-count cost model in workshop-rs so raw Workshop and future OPY/DEL consumers can obtain exact, structured element-usage analysis from the same authoritative target semantics.

Context

OverPy exposes #!debugElementCount, which reports total element usage, per-rule totals, and per-condition/action costs during Workshop emission. Workshop.codes also documents element-count calculation rules and special cases:

• https://workshop.codes/wiki/articles/element-count-calculation
• https://github.com/Zezombye/overpy/blob/master/src/compiler/astToWorkshop.ts

This capability is useful beyond OverPy compatibility. Element count is a Workshop target cost/limit property and belongs with the canonical Workshop semantics rather than in a source-language frontend or in Wright's product layer.

workshop-rs should therefore own the authoritative cost model. Wright, opy-rs, and del-rs may consume the stable API later, but they should not duplicate the calculation rules.

The current canonical language-surface gate in #65 remains higher priority. This issue may establish the design and evidence model now, but implementation should not interfere with #66/#67/#68 or rely on an incomplete canonical WIR surface.

Scope

• Define the Workshop element-count semantics represented by canonical WIR nodes and catalog identities.
• Cover documented ordinary costs and evidence-backed special cases such as rules, actions, conditions, values/literals, arrays, Workshop Settings, Evaluate Once, localized/custom strings, top-level argument adjustments, hero literals, and constructs that contribute zero elements.
• Expose a structured report rather than only a single total. At minimum, support:
  • total element count;
  • per-rule element count;
  • condition/action contributions where canonical provenance allows them to be attributed;
  • stable source/WIR provenance sufficient for higher-level tooling to explain expensive regions.
• Keep the calculator independent of textual formatting, locale spelling, rule ordering, and source-language syntax.
• Validate the model with focused fixtures derived from documented counting rules and differential evidence from OverPy where applicable.
• Add representative real-program checks once the canonical language-surface gate is stable enough to make the result meaningful.
• Document known evidence gaps explicitly instead of guessing undocumented runtime/editor behavior.

Design constraints

• Element count is a property of the generated/canonical Workshop program. High-level source frontends must not estimate cost directly from OPY/DEL source ASTs when lowering, optimization, helper generation, or target encoding can change the result.
• workshop-rs owns the canonical cost model; consumers receive data through a reusable public API.
• Prefer a structured semantic API such as an ElementCountReport/equivalent over emission-time mutable counters tied to one formatter.
• Counting must operate on canonical identities/WIR semantics rather than localized token text.
• Exact compatibility with OverPy's emitted comments or presentation format is not a workshop-rs contract. OverPy is evidence for counting behavior; source-language presentation belongs to opy-rs if/when that integration is implemented.
• Do not add Wright-specific policy thresholds, lint severities, CI budgets, or agent UX here. Those are consumer concerns.

Non-goals

• Implementing #!debugElementCount in opy-rs in this issue.
• Adding an OSTW/DEL syntax surface for element counting.
• Adding Wright CLI, lint, CI-budget, or agent commands before the canonical API is stable.
• Reproducing OverPy's internal nbElements implementation structure or output formatting for its own sake.
• Treating undocumented or anecdotal counting behavior as canonical without reproducible evidence.
• Blocking the active Complete the current Workshop language surface as canonical semantics #65 language-surface gate.

Acceptance criteria

• workshop-rs has a documented canonical element-count model with evidence for each supported special-case rule.
• A reusable API returns the total and structured per-rule/per-node contribution data needed by downstream tooling.
• Counting is locale-independent and does not depend on emitted text formatting.
• Focused positive fixtures cover ordinary elements plus the documented special cases that materially alter counts.
• Differential fixtures compare representative programs against an independent reference such as OverPy where the reference behavior is applicable, with mismatches investigated rather than normalized away.
• Unsupported or evidence-insufficient constructs fail or report incompleteness explicitly instead of silently producing a misleading exact total.
• The implementation is exercised on representative real Workshop programs after the canonical WIR/language surface from Complete the current Workshop language surface as canonical semantics #65 is stable.
• Public API/docs make clear that OPY/DEL/Wright integrations are downstream follow-up work and are not part of this issue.

Dependencies

• Complete the current Workshop language surface as canonical semantics #65 — canonical Workshop language surface. Design work may proceed, but implementation/acceptance should follow the stable canonical WIR/catalog surface established by this gate.

Follow-up direction

After this API is stable and evidence-backed:

1. opy-rs may implement #!debugElementCount compatibility by consuming the canonical Workshop report after lowering.
2. del-rs may expose the same analysis once DEL/OSTW lowering reaches canonical WIR, without inventing a separate cost model.
3. Wright may surface the report through analyze, machine-readable output, CI budgets, lint, and agent tooling.

Do not create or start those consumer integrations merely to satisfy this issue; reassess them against current repository reality after the canonical workshop-rs capability is accepted.