Add Stdlib Support

Adding a New Standard Library Package

End-to-end workflow for porting a ballerina/<name> package from jBallerina (Java) into this repo. Follow the steps in order; do not skip the gates.

All coding rules and the PAL constraint live in AGENTS.md at the repo root — read it before implementing. This skill encodes the process, not the rules. Supporting files in this skill's directory (templates/, references/) hold the manifest/source templates and shared patterns — read each one when its step tells you to.

Golden rule: two things must hold when this port is done — (1) the Ballerina public interface must stay identical to jBallerina's (never break customer code — see validate-stdlib-contract), and (2) if the jBallerina reference root ships a docs/spec/spec.md, its prose must exactly match the Go implementation's actual behaviour for every in-scope feature. A spec sentence describing behaviour the Go code doesn't have, or silent on a divergence the Go code does have, is a defect to resolve (by fixing the implementation to match intended design, or by recording the divergence) before the port is done — not something to leave unreconciled.

If the user wants to fix a gap in a stdlib that already exists under lib/stdlibs/ballerina/<name>/, use fill-stdlib-gap instead — this skill is heavyweight by design.

1. Acquire the jBallerina reference

Ask the user for the path to the corresponding jBallerina library implementation root, e.g. ~/github/ballerina-platform/module-ballerina-<name>/. Do not proceed without it.

That root should contain:

• ballerina/ — the Ballerina-side source (public API, type declarations, extern function signatures).
• native/ (optional) — the Java native implementation backing the extern functions. Pure-Ballerina libraries do not have this directory; that's fine, just note it.
• docs/spec/spec.md (optional) — the package's specification, if the jBallerina repo ships one. Prose written for humans; often states intent, edge-case handling, and constraints that neither .bal signatures nor Java code spell out. Read it alongside ballerina/ and native/, not as a substitute for either.

Then:

• Read every .bal file under <root>/ballerina/, excluding tests/ and build/, to enumerate the full jBallerina feature set and identify which functions are external.
• If <root>/native/ exists, read the Java sources backing those extern functions. This is the authoritative source of truth for runtime semantics — error wording, edge-case handling, parsing rules, numeric behaviour — and is what the Go natives must match for parity (see Step 5). Don't infer behaviour from .bal signatures alone when Java source is available.
• If <root>/docs/spec/spec.md exists, read it in full and note every behavioural claim it makes for features in scope. Treat divergences between the spec and the Java/.bal source as a flag to raise with the user (Step 4), not something to silently resolve one way.

2. Resolve imports and check existing stdlib coverage

Scan the jBallerina source for import ballerina/<X> statements.

• For each <X> not already present under lib/stdlibs/ballerina/<X>/: tell the user that dependency must be implemented first. If they ask to continue anyway, narrow the plan to only features that don't depend on <X>.
• For each <X> already present: read lib/stdlibs/ballerina/<X>/0.0.1/go1.27/README.md and note every row whose status is Not Yet Supported, Partially Supported, or Cannot Support, plus anything under Notable Behavioural Changes. If our in-scope features depend on any of those gaps or divergences, surface them in the plan (Step 4) under a Dependency Limitations section.
• Exception: ballerina/jballerina.java.arrays will not get a Go equivalent. Plan to replace its uses with Go-native equivalents inside the native/ layer.
• Cross-stdlib imports must be declared in Dependencies.toml — see templates/manifests.md for the format and why missing entries cause Unknown import: ballerina/<dep> at runtime.
• Langlib imports need compiler wiring: if the .bal source imports a langlib (import ballerina/lang.<x>;), that import only resolves through the isLangImport switch in semantics/symbol_resolver.go — check the langlib in question is wired there before assuming it works.

Do not silently drop features because of a missing import or inherited dependency gap — always flag and confirm.

If a dependency's README claims a feature is Supported but it actually diverges from its own documented behaviour — a bug, not a catalogued gap — that's separate from the check above: follow references/reporting-limitations.md.

3. Cross-check language support

Read AGENTS.md (root) in full, especially the Interpreter stages and Coding style sections. If a planned feature uses a construct known to fail in this interpreter (distinct error subtypes, readonly & intersections, stream type, XML, full typedesc parameter handling), drop or defer the feature and note it in the plan.

Handling unexpected compile failures during implementation

When the interpreter panics or emits compile errors that are not explained by AGENTS.md, stop and present the developer with these options — do not silently pick one:

Unexpected language limitation found: <construct> is not supported (panic: <message>).

Options:

1. Fix the interpreter — implement this construct in the compiler/BIR pipeline. Requires a separate change.
2. Work around in Ballerina — rewrite the Ballerina source to avoid the construct.
3. Move to Go native — replace the Ballerina function body with = external and implement the logic in native/.
4. Scope out this feature — mark it Not Yet Supported in the README and move on.

Which option do you prefer?

After the developer responds, apply the chosen resolution before continuing. Regardless of which option is chosen, this is a language limitation worth tracking upstream independently of the local workaround — draft an issue per references/reporting-limitations.md and point the developer to https://github.com/ballerina-nutcracker/ballerina/issues.

4. Propose a plan and a showcase .bal file (GATE: wait for user approval)

Produce both:

• Plan — a list of features in scope for this iteration, with explicit "Not Yet Supported" notes for anything left out. Include a Dependency Limitations section listing any inherited gaps from the README of every ballerina/<X> package we import (per Step 2).
• Showcase .bal file — a small program that exercises every feature in scope end-to-end. Use @output markers for expected output.

Wait for the user to approve both the plan and the showcase file before touching any Go code.

5. Behavioral parity analysis (GATE: parity table required)

The Go-native behaviour must match the jBallerina (JVM) behaviour for every supported feature. Users migrating from jBallerina must not observe breaking changes. Before writing any Go code, produce a parity table for each in-scope feature:

Read references/parity-risks.md for the hot-spots to investigate (decimal precision, UTF-8 vs UTF-16, error-message rules, numeric edge cases) plus a domain-specific example. Where a row's behaviour is verifiable by running code, verify it with the run-jballerina skill (bal run the probe on jBallerina, compare against this interpreter) rather than reasoning from documentation.

Spec cross-check (only if docs/spec/spec.md exists)

Add a row to the parity table for every behavioural claim the spec makes about an in-scope feature, and verify the planned Go implementation will match it exactly — same edge-case handling, same defaults, same error conditions. A spec/implementation mismatch is treated the same as a spec/Java mismatch: raise it with the user rather than picking a side silently. This check is repeated against the actual implementation in Step 10 — Step 5 catches mismatches before code is written, Step 10 catches drift introduced while writing it.

Rules

• Avoidable divergences (resolvable in the Go layer) — fix before merging.
• Unavoidable divergences (architectural Go/JVM constraint) — record in the README under Notable Behavioural Changes before implementing.
• A divergence traced to an actual bug in a dependency stdlib (not an architectural constraint, and not already a catalogued gap) — don't just record it as unavoidable; also follow references/reporting-limitations.md to get it tracked upstream.
• Do not proceed to Step 6 without a complete parity table, even if every row says "No risk identified."

6. Evaluate Go libraries (GATE: wait for approval before touching go.mod)

Only if external Go dependencies are needed. For each external functionality, evaluate 2–3 candidate Go libraries on:

Present as a small table with a recommendation. Wait for user approval before adding the dependency to go.mod. If no external deps are needed, skip this step.

7. Implement

File layout

lib/stdlibs/ballerina/<name>/0.0.1/go1.27/
├── Ballerina.toml          # package manifest
├── Bala.toml               # build/platform manifest
├── Dependencies.toml       # package dependencies
├── README.md               # via stdlib-readme-format skill
├── <name>.bal              # public API surface
└── native/                 # OPTIONAL — omit if pure Ballerina
    └── <name>.go           # Go native implementations

Multi-file .bal and multi-file native/ are both supported — see exemplars below. For dotted names like math.vector, the single .bal file is named math.vector.bal.

Real Ballerina submodules (a package with a root module plus genuine sub-modules, matching jBallerina's own multi-module packages) use a modules/<localSubmoduleName>/ directory per sub-module, each with its own .bal file(s) — module discovery is purely filesystem-based (no [[modules]] declaration needed in Ballerina.toml). See lib/stdlibs/ballerina/protobuf/0.0.1/go1.27/ for the exemplar: root protobuf.bal plus modules/types.any/, modules/types.duration/, etc. Prefer this over registering each sub-module as an independent flat top-level package — a package with real sub-modules is one thing with one Ballerina.toml/Bala.toml/Dependencies.toml/version, not several.

Templates:

• Manifests (Ballerina.toml, Bala.toml, Dependencies.toml with/without cross-stdlib deps) — templates/manifests.md.
• Source skeletons (.bal with license header, native/<name>.go) — templates/source-files.md.

Shared patterns — read the relevant file only when the situation applies:

• PAL hookup (new platform interaction: io, fs, http, env, time) — references/pal.md. Three files must change; missing TestPal = nil-pointer panics in corpus tests.
• Native state behind a map/record or object value (parsed keys, compiled patterns, handles) — references/native-state.md. Never add fields to values.Map for this.
• bal↔Go JSON conversion — reuse the shared helpers values.BalToGoJSON / values.GoToBalValue; never duplicate the conversion per-stdlib.

Wire-up checklist (every new stdlib — missing any = silent failure)

1. lib/rt/libs.go — add a blank import so the init() in the native package runs at binary start:

   _ "ballerina/lib/stdlibs/ballerina/<name>/0.0.1/go1.27/native"

   Without this, all = external functions produce "function not found" at runtime even though the binary compiles cleanly. Skip this line if your stdlib has no native/ directory.

2. test_util/testphases/phases.go — append an entry to builtinStdlibs. This list is consumed only by the hand-rolled per-stage corpus drivers (ast/bir/desugar/cfg/etc. corpus_*_test.go, which discover tests under corpus/bal/) — cli/cmd run and the real project pipeline (including corpus/lib/'s TestLibIntegration) resolve ballerina/* imports via lib/stdlibs/ballerina/ on disk regardless of this list. Without an entry here, those specific corpus drivers cannot resolve import ballerina/<name> even though go run ./cli/cmd run works fine.

   • Single-module package (the common case): flatEntry("<name>", "0.0.1", "go1.27").
   • Package with real sub-modules (see File layout above): one flatEntry for the root module, then one subModuleEntry("<pkg>", "<localSubmoduleDir>", "0.0.1", "go1.27") per sub-module — root before its sub-modules, since each entry's ResolveSymbols call sees only previously-listed entries' exported symbols.
   • Either way, place the new entry/entries after any stdlib this one imports, so the loader compiles them in order.

3. Dependencies.toml — if the .bal source imports any other stdlib (import ballerina/<dep>;), declare it per templates/manifests.md. Without this, the full project resolver will not discover the dependency and every user .bal file importing this stdlib will fail with Unknown import: ballerina/<dep>.

4. projects/module_resolver.go — usually no change, even for a dotted 2-level sub-module name (math.vector-style dotted names, <pkg>.<submodule> sub-module names): the existing packageNameCandidates already reduces either shape to the right package name. Read it once to confirm the import in question is covered — and if you're tempted to generalize it further, verify the change is actually load-bearing by reverting it and re-testing before keeping it; it's easy to "fix" a case that was already handled.