API Stability

This document defines which flydsl APIs may be relied on across releases and the compatibility commitments that apply when they are changed. Its scope is limited to python/flydsl/. Below, fx refers to flydsl.expr.

A release means a minor-version increment (for example, 0.3 → 0.4). A patch release must not break a stable API.

1. Summary and general rules

• stable: backward compatible across minor releases. Previously valid call paths, signatures, and semantics must continue to work.

• unstable: everything else. These APIs may change or be removed in any minor release without notice.

deprecated is not a third stability level. It is a lifecycle marker for a stable API: during its deprecation window, it remains stable and protected by this document’s compatibility rules; it may be removed only after that window ends.

Returned-object rule

An object returned by a stable API has a stable public result interface: its non-underscore members and Python special methods are stable when reached through that result. This rule applies recursively to objects returned by those members.

The concrete implementation class, its constructor, and its import path are not promised by this rule. They may change if the replacement preserves the result interface’s public members, signatures, and semantics. For example, flyc.from_torch_tensor(x).mark_shape_dynamic(0) is stable, while flyc.from_torch_tensor(x)._ensure_spec() is unstable.

Determine stability by the mechanical process below. A public export from an expr direct-child module has several equivalent access forms: fx.<name>, fx.<module>.<name>, and from flydsl.expr.<module> import <name> have the same stability. Otherwise, classify the path that a caller actually uses, not the object’s identity.

2. Determining stability

Apply the following branches by path prefix:

1. A module-global name or namespace segment beginning with _ is unstable. On stable types and returned objects, only __...__ Python special methods may begin with _; all other underscore-prefixed members are unstable.

2. A path under flydsl.expr: classify it only under §2.1; it is unstable if it does not qualify.

3. A path under flydsl.compiler: direct members in compiler.__all__, and members in compiler.protocol.__all__, are stable. Other deep paths are stable only when listed exactly in §2.3.

4. Every other path is stable only when listed exactly in §2.3.

For a member reached through a returned object, first classify its producing API under these branches, then apply the returned-object rule in §1.

2.1 flydsl.expr

expr/__init__.py is the sole top-level aggregation manifest. It has no __all__ of its own; stability is determined exclusively by the following two export chains.

Symbols exported from direct-child modules

Subject to the first branch above, <name> in a direct-child module <module> is stable if and only if:

1. expr/__init__.py aggregates that direct-child module through from .<module> import *;

2. <name> is in that child module’s __all__.

Names satisfying these conditions have identical stability when accessed via fx.<name>, fx.<module>.<name>, or a direct import. Those direct-child modules and their public export paths are part of the compatibility commitment. Therefore, both fx.Int32 and fx.numeric.Int32 are stable. Members omitted from __all__ remain unstable; fx.arith._to_raw is unstable under the first branch even if it was listed in a historical __all__.

Backend entry points and recursive child namespaces

fx.<backend>...<name> is stable if and only if:

1. the first-level <backend> appears in _BACKEND_MODULES in expr/__init__.py;

2. every following child namespace appears in the __all__ of its direct parent package; and

3. the final <name> appears in the __all__ of its owning module or package.

The first-level backend entry point, and intermediate child namespaces that satisfy condition 2, are stable namespaces as well. This rule applies recursively and has no path-depth limit.

For example, fx.rocdl.cdna3.s_waitcnt satisfies the complete export chain and is stable, while fx.rocdl.cluster.* is unstable when cluster is not listed in rocdl.__all__. An upstream-MLIR ODS builder that is re-exported but omitted from the final __all__ is unstable as well.

__all__ is not access control: an attribute may exist and be callable while still failing the stability test above.

2.2 flydsl.compiler

Only direct members of flydsl.compiler.__all__ are stable. For example, if jit is in that manifest, flydsl.compiler.jit is stable.

flydsl.compiler.protocol is an exception: every non-underscore flydsl.compiler.protocol.<name> in its __all__ is stable. It is the public extension namespace for user implementations of JIT / DSL-value protocols.

This rule is otherwise not recursive: flydsl.compiler.<submodule>.<name> does not become stable merely because <submodule> is importable; it must be listed explicitly in §2.3.

2.3 Other explicitly stable APIs

The following full paths are stable. This table is the only exception list; a new commitment must add an explicit row.

API	Description
flydsl.runtime.device.get_rocm_arch	Query the target ROCm architecture
flydsl.runtime.device.is_rdna_arch	Choose between CDNA and RDNA paths

2.4 All other APIs

Every API that does not satisfy §2.1 or §2.2, and is not listed exactly in §2.3, is unstable. This includes undeclared flydsl.* submodules, flydsl._mlir.*, and every underscore-prefixed name.

Direct invocation of an upstream MLIR dialect op is allowed but unstable: its name, arguments, and semantics are controlled by upstream MLIR, and FlyDSL provides no compatibility commitment for it.

Stable API catalog

Generate the complete non-deprecated stable API catalog from the checked-out source:

python3 scripts/list_stable_apis.py
python3 scripts/list_stable_apis.py --format json

The script reads export manifests without importing FlyDSL. It lists canonical module paths, omitting equivalent top-level flydsl.expr aliases. Deprecated APIs remain compatible but are intentionally excluded from this catalog.

3. Stable but deprecated

The APIs in the table below satisfy the stable rules in §2 but are marked as deprecated. They remain stable during the §5 window; new code must not use them, and a replacement must be provided before removal.

For direct-child module exports under §2.1, the deprecated status in this table also applies to fx.<name>, fx.<module>.<name>, and direct-import forms. This table is maintained separately as the compatibility-debt list and is excluded from the catalog above.

API	Replacement or required work before removal	Declared removal release
fx.get	fx.get_().unpack() or IntTuple[].unpack()	v0.4
fx.index_cast	fx.Index(x)	v0.4
fx.constant_vector	Numeric and Vector member functions	v0.4
fx.tdm_ops and content reached through this alias	fx.rocdl.tdm_ops; the latter is a target-specific unstable path	v0.4
fx.Numeric.maximumf, fx.Numeric.minimumf	fx.arith.maximumf(x, y), fx.arith.minimumf(x, y)	v0.4
fx.Numeric.shrui, fx.Numeric.addf	fx.arith.shrui(x, amount), x + y with a fastmath context	v0.4
fx.Numeric.exp2	fx.math.exp2(x)	v0.4
fx.Numeric.shuffle_xor	fx.gpu.shuffle_xor(x, offset, width)	v0.4

4. What counts as a breaking change

For a stable API, each of the following is a breaking change:

• removing a stable API or breaking its export chain: removing an entry from a direct-child module’s __all__, flydsl.compiler.__all__, or flydsl.compiler.protocol.__all__; or removing a §2.3 entry without a new rule that covers it;

• removing an argument, renaming an argument that may be passed by keyword, reordering positional arguments, removing a default, or changing a default;

• narrowing accepted types, architectures, or value ranges;

• changing a returned scalar or value type, tuple arity, or a returned object’s stable public result interface (including non-private members and __...__ Python special methods), or the numerical, layout, or emitted-op semantics for previously valid input.

The following are not breaking changes:

• adding an API, or adding an optional keyword argument whose default preserves existing behavior;

• widening accepted input;

• improving an error message, converting undefined behavior into a clear error, or changing the exception type on failure;

• replacing a returned object’s concrete implementation class while preserving its stable public result interface;

• changing only unstable APIs.

5. Changing or retiring a stable API

1. Provide a replacement first, normally exposing it from an appropriate stable path.

2. Mark the original API as deprecated at its definition or export declaration, and add the API and replacement to §3.

3. Retain the old API in the release where it is marked, N, and in the next minor release, N+1.

4. Remove the old API no earlier than N+2, and remove its corresponding §3 entry at the same time.