One Name, Two Languages: Giving Siunertaq a Canonical Namespace.

This is the third post in a series on Siunertaq, a small Scala 3 project that

models computation as a stack machine and cross-validates it across languages.

Previously: One Stack Machine, Two Runtimes: Cross-Validating Scala and Perl with a Shared JSON IR

introduced the batch layer; the JSON IR post covered how PerlBridge and

Siunertaq::StackMachine.pm cross-validate the same Program in Scala and Perl

via a shared JSON format.

This post is about a smaller, quieter problem that shared JSON doesn't solve on

its own: once two languages agree on *what ran, how do you name the thing that

ran the same way in both of them?*

🎯 The Problem Shared JSON Doesn't Solve

The last post left things in a good place. ClassASTBridge reads a .class file

and emits StackInstr JSON. Program.toJson does the same from the Scala side.

Siunertaq::StackMachine->execute_json consumes that JSON in Perl. Three

producers/consumers, one wire format, no code generation.

But once both sides are pushing rows into ClickHouse — bytecode_instructions

for JVM extractions, forth_words for compiled Forth definitions — a new

question shows up that JSON doesn't answer: how do you find the row that

corresponds to the same logical thing?

Concretely: io.siunertaq.expr.Program's toJson method, on the JVM side, is

identified by class_name = "io.siunertaq.expr.Program",

method_name = "toJson". The Perl mirror of that same logic, once it exists,

would live in a package like Siunertaq::Expr::Program, in a sub named

to_json. Same concept. Completely different strings. WHERE class_name =

method_name was never going to work, and neither was anything close to it.

We needed a name that both sides could compute independently and land on

the same value — a join key that doesn't require either side to know

anything about the other's naming convention, only about a shared,

neutral one.

❌ The Tempting Wrong Answer: A Reversible Mapping

The instinctive fix is to write a bijection: given a JVM name, derive the exact

Perl name it corresponds to, and vice versa. It's tempting because it feels more

complete — you'd get a real two-way translator, not just a comparison key.

It falls apart on the return trip. Going JVM → Perl is mostly fine:

toJson → to_json is an unambiguous, mechanical camelCase-to-snake_case

conversion. Going Perl → JVM is not:

to_json  →  toJson   ? toJSON   ? ToJson   ?

All three are plausible JVM spellings of the same snake_case name, and Perl

code has no way of telling you which one the original author picked. A

"reversible" mapping that silently guesses wrong for some fraction of names is

worse than no mapping — it would produce canonical_name collisions and

splits that look authoritative but aren't.

So we gave up on reversibility as a goal entirely.

💡 The Actual Design: Fold, Don't Translate

Instead of mapping JVM ↔ Perl, NamespaceCanon maps both down to a single,

neutral, lossy key. Neither side is treated as authoritative over the other;

both are folded toward the same normal form:

object NamespaceCanon:



  private val JvmRootPrefix  = "io.siunertaq."

  private val PerlRootPrefix = "Siunertaq::"



  def fromJvm(className: String, methodName: String): String =

    val stripped = className.stripPrefix(JvmRootPrefix).stripSuffix("$")

    val segments = stripped.split('.').filter(_.nonEmpty).map(_.toLowerCase)

    (segments :+ camelToSnake(methodName)).mkString(".")



  def fromPerl(perlPackage: String, subName: String): String =

    val stripped = perlPackage.stripPrefix(PerlRootPrefix)

    val segments = stripped.split("::").filter(_.nonEmpty).map(_.toLowerCase)

    (segments :+ subName.toLowerCase).mkString(".")



  private def camelToSnake(s: String): String =

    s.replaceAll("([a-z0-9])([A-Z])", "$1_$2").toLowerCase

Both calls below converge on the same string, which is the only property

that actually matters:

fromJvm("io.siunertaq.expr.Program", "toJson")

  == fromPerl("Siunertaq::Expr::Program", "to_json")

  == "expr.program.to_json"

Nobody has to guess to_json's JVM spelling, because nobody is trying to

recover it. fromPerl doesn't reconstruct toJson; it just lowercases

to_json and leaves it alone, betting — correctly, for this codebase's

naming convention — that the JVM side would fold to the same string via its

own camelCase→snake_case rule. The two functions don't need to agree on an

inverse. They only need to agree on a fixed point.

There's a second, explicitly non-reversible pair of helpers,

suggestPerlPackage / suggestPerlSub, for the opposite situation: scaffolding

a new .pm file from an existing Scala class. Those are best-effort code

generation helpers, not part of the join-key contract, and the naming makes

that distinction obvious at the call site.

📦 Where It Actually Lands: ClickHouse

canonical_name had to exist somewhere queryable, not just as a Scala

function. ClickHouseSync computes it once, at the JSON-serialization

boundary, and never touches the underlying row types to do it:

private def withCanonicalName(row: MecrispCompiler.BytecodeRow): Json =

  row.toJson.mapObject(

    _.add("canonical_name", NamespaceCanon.fromJvm(row.className, row.methodName).asJson)

  )

MecrispCompiler.BytecodeRow and MecrispWordDef stay exactly as they were;

canonical_name is injected into the JSON on the way out, which meant this

shipped without touching either of those types.

On the ClickHouse side, a migration adds the column to both tables and

backfills existing rows with a SQL expression that mirrors the Scala logic

sentence-for-sentence — replaceRegexpAll for the camelCase split, lower()

for the fold:

ALTER TABLE bytecode_instructions

    ADD COLUMN IF NOT EXISTS canonical_name LowCardinality(String) DEFAULT '';



ALTER TABLE bytecode_instructions

    UPDATE canonical_name =

        concat(

            lower(replaceAll(class_name, 'io.siunertaq.', '')),

            '.',

            lower(replaceRegexpAll(method_name, '([a-z0-9])([A-Z])', '\\1_\\2'))

        )

    WHERE canonical_name = '';

Keeping the Scala version as the one authoritative implementation and the SQL

as "a faithful translation of that logic for in-database use" (it says so

right in the migration's header comment) was a deliberate choice — the two

were never going to be enforced identical by the type system the way

Program.toJson and Siunertaq::StackMachine->execute_json are, so the

comment does the job a compiler can't.

The payoff is a view:

CREATE OR REPLACE VIEW cross_language_equivalences AS

SELECT

    canonical_name,

    countIf(language = 'jvm')  AS jvm_count,

    countIf(language = 'perl') AS perl_count,

    ...

FROM ( ... UNION ALL of bytecode_instructions and forth_words ... )

GROUP BY canonical_name

HAVING jvm_count > 0 AND perl_count > 0;

🚧 The Honest Status: One Hand Clapping

Here's the part that's easy to gloss over and shouldn't be: this view is

empty of anything interesting right now. HAVING jvm_count > 0 AND

perl_count > 0 means a canonical name only shows up once both sides have

written a row under it — and only the JVM side writes rows today.

forth_words even grew a language column with a default of 'jvm' in

anticipation of this, but nothing populates language = 'perl' yet.

That's not a bug, it's a sequencing decision. Building the fold function and

the schema first, before the second producer exists, meant the join key's

design could be tested against real JVM data and a NamespaceCanonSpec before

committing to it. The alternative — building the Perl-side writer first —

would have meant designing the canonical format against a single example

instead of the actual shape of two independent naming conventions.

🔧 A Related, Less Glamorous Fix: ClassASTBridge Had to Stop Guessing

None of the above is worth much if the JVM-side rows it's keying aren't

trustworthy. While wiring up canonical_name, we found ClassASTBridge had

two quiet correctness gaps: an unrecognized opcode was silently dropped from

the output instead of failing, and a target method name that happened to be

overloaded had its bytecode silently merged across every overload. Both are

"confidently wrong" — the caller gets back a JSON array that looks complete.

Since the whole point of canonical_name is "this row is a faithful record

of what the JVM ran," it made sense to close both gaps at the same time:

final case class UnsupportedBytecodeException(

  className: String, methodName: String, methodDescriptor: String, opcode: Int

) extends RuntimeException(...)



final case class OverloadedMethodException(

  className: String, methodName: String, descriptors: List[String]

) extends RuntimeException(...)

An unsupported opcode now aborts extraction instead of vanishing from the

array; an ambiguous overload now aborts instead of conflating two methods'

bytecode into one instruction stream (pass targetDescriptor, e.g. "(I)I",

to disambiguate). A ClassASTBridgeSpec exercises both failure paths against

.class files compiled in-memory by the JDK's own javac, rather than

hand-crafted byte arrays.

🔮 What's Next: PmASTBridge

The obvious next step is the thing cross_language_equivalences is actually

waiting on: a Perl-side bridge that reads a .pm file's AST, computes

NamespaceCanon.fromPerl for each sub, and writes forth_words rows tagged

language = 'perl'. Once that exists, the view stops being a one-sided

placeholder and starts being the thing it was built to be — a live diff

surface between what the JVM runs and what Perl runs, keyed on a name neither

side had to learn from the other.

Code is at github.com/Yoshyhyrro/Siunertaq.

NamespaceCanon lives in modules/core; the ClickHouse migration is

modules/postgres-bridge/extension/clickhouse_schema_v2_canonical_name.sql.

As always, issues and PRs welcome — particularly if you've solved the

Perl→JVM name-guessing problem in a way that isn't "don't." 🙏