Axir Language Backend

AxIR Language Backend

Use this for work on generated Ax libraries such as Python, Java, C++, Go, or future Rust. This is not an Ax product skill from src/ax/skills/; it is repo-local guidance for compiler/backend implementation.

First Checks

• Confirm the target is a generated Ax user library, not a public AxIR API.
• Inspect current target seams before editing: tools/axir/internal/axir/codegen.go, verify.go, runtime_model.go, the existing *_core_emit.go files, and target templates.
• Check user-facing package names in docs before choosing names. Do not expose axir, ax-go, or compiler-internal branding in generated library metadata.

Backend Implementation Rules

• Keep semantics Core-owned. Provider mapping, Agent context/runtime behavior, Flow graph semantics, optimizer/GEPA behavior, envelopes, state, logs, and traces should come from Core helpers/descriptors.
• Keep target code idiomatic but thin. Target templates own language wrappers, dynamic value representation, transports, error boundary shape, package metadata, and examples.
• Prefer standard-library dependencies for base packages. Optional runtime profiles may remain dependency-bearing and opt-in.
• Use deterministic ordering for generated output, JSON/string rendering, prompt fields, snapshots, catalogs, action logs, and conformance output.
• Public APIs should feel native in the target language while preserving Ax concepts. Document unavoidable naming differences in generated README/examples.
• Capability manifests must be truthful. Do not list unsupported_capabilities for a generated package that is included in default verification; either implement the surface or remove the public/manifest claim.
• Concrete public generated methods must never be placeholder-only bodies such as pass, return None, return null, return nil, Value::Null, empty vectors, or generic "not implemented"/"unsupported" fallbacks. Validation errors remain acceptable for invalid inputs, unknown provider names, and unknown runtime protocol ops.
• Abstract/base interfaces may describe fallible boundaries, but every concrete generated class/struct that is advertised by the manifest must implement claimed provider, router, balancer, runtime session, AxGen, AxAgent, AxFlow, and optimizer operations.
• Conformance dispatch must be explicit for all claimed feature groups. Do not add a silent catch-all that makes unsupported fixture kinds pass without executing an implementation path.
• Conformance coverage must be semantic, not just dispatch-shaped. Every generated package must emit conformance-coverage.json with each claimed fixture kind/operation classified as semantic, validation-error, transport-boundary, or explicitly-not-claimed; default-verified targets must not use presence-only.
• Runner code must reject guard-only shortcuts: no broad expectation helpers, empty fixture arms, suite-name-only dispatch, self-comparisons, or checks that only prove an expected key exists. If a fixture expects a validation error, tie the generated error to the fixture expectation and keep the implementation path explicit.
• Provider API and no-key examples must cover every claimed public surface class: chat, stream, embeddings, audio/realtime mapping helpers when claimed, routers/balancers, runtime protocol, AxGen, AxAgent, AxFlow, and optimizer artifacts.

Required Touchpoints

• Compiler target registration: Compile, CLI help, default verify target list, package name mapping, capability manifest, target idiom metadata.
• Code generation: target Core emitter, target templates, package metadata, README text, examples, conformance runner, runtime protocol/client support.
• Verification: target compile, manifest guard, no-key examples, conformance suites, package smoke/install or external-consumer smoke, and optional runtime-profile checks where applicable.
• Coverage gates: add target entries to generated-output audits in tools/axir/internal/axir/axir_test.go, including negative cases for placeholder runner patterns and positive markers for AxAgent, AxFlow, AxAI, runtime protocol, and optimizer coverage.
• Repo examples: scripts/run-example.mjs, src/examples/<language>/, src/examples/README.md, and root package.json convenience scripts if needed.
• User-facing example lists: update npm run example -- list, the root README "Run examples" block, examples README command blocks, package convenience scripts, and release/compiler docs so the new backend is discoverable without reading compiler internals.
• Docs: README.md, docs/COMPILER.md, docs/RELEASE.md, and docs/ARCHITECTURE.md. Edit canonical docs in docs/, not generated docs under website/.generated/.
• Website language docs: for any public backend feature or capability claim, update src/examples/<language>/<group>/ with provider-backed ax-example headers and run the website-md language docs workflow so generated markdown stays aligned.

Acceptance Bar

• npm run test:axir passes and includes the new target in default verification once the backend is claimed as current.
• axir verify --targets python,java,cpp,<new-target> passes for all default suites: signature, schema, validation, prompt, axgen, axai, axagent, axoptimize, axprogram, and axflow.
• Generated package metadata is shippable for the ecosystem and uses the Ax product namespace.
• User-facing examples are honest: no-key examples are deterministic, provider API examples use real provider transport and require explicit environment keys.
• Public website examples are real provider-backed files under src/examples/<language>/; keep mock, no-key, scripted, debug, and conformance-only material under internal tests or packages/<language>/examples.
• Public example coverage stays in sync with language claims: generation, short-agents, flows, optimization, and audio each need beginner, intermediate, and advanced examples when the language is listed on the website.
• Generated-output audits pass for the target: no unsupported manifest entries, no placeholder concrete public methods, no dead Core helper stubs, and explicit conformance/example guards for every claimed Core-owned feature group.
• The conformance runner proves claimed behavior with fixture-level assertions over outputs, requests, state, traces, artifacts, runtime envelopes, and expected errors. Placeholder-free code is necessary but not sufficient for default test:axir inclusion.

Avoid

• Do not put repo-maintainer backend guidance in src/ax/skills/; those files are Ax product subsystem docs.
• Do not implement provider or Agent semantics directly in target templates when a Core descriptor/helper exists.
• Do not present scripted/no-key examples as provider API examples or claim registry publishing before workflows and credentials exist.
• Do not widen runtime profile semantics while adding a language backend unless a concrete conformance gap proves it is necessary.
• Do not ship a thinner v1 target by leaving stream/audio/realtime/router/runtime/optimizer methods as placeholders while the manifest or README claims full AxIR support.

Session validation and cancellation

Raw session schema patterns are defined in ir/axcore/regex.axir; see regex.md for UTF-16 semantics and matcher invariants. Keep pattern decisions in Core and run the TypeScript-derived session-ecmascript-pattern-validation.json fixture in every target. Native agent tests must also exercise valid invocation after invalid-argument correction, not only pattern matching in isolation.

For cancellation changes, run the native transport tests as well as scripted session tests. C++ release verification builds a second session test binary with libcurl enabled so stalled HTTP cleanup is exercised; the core-only binary cannot prove that behavior. Delegated MCP tests abort only after the child starts its imported tool and assert settlement, retained usage, and closed parent callbacks.