Declarations & Symbols

Declarations & Symbols

Part of the Sun ABI draft. These are proposed requirements, not guarantees of current releases. Open decisions must be resolved before stabilization.

Declaration and symbol identity

Consider two independent libraries:

geometry.Point: x and y are integers
screen.Point:   x and y are integers

Equal fields do not make these the same type. Renaming a local import also does not change either type. For a revision of the same explicitly named library, Sun can check whether its Point declaration satisfies a recorded dependency. It must still retain the exact identities of already compiled function bodies.

A bundle retains exact implementation dependencies. An explicitly named library may provide a compatible nominal type from another revision after the importer checks its dependency ABI requirements. Rebuilding a dependency or reusing its library ID alone does not authorize replacement.

Minimal exampleLevelRequirement
Two revisions provide different compiled bodies for make_point.MUSTInclude the defining artifact and portable declaration identity; preserve embedded code and exact symbols across nominal correspondence.
The same named library keeps its geometry.Point declaration across revisions.MUSTUse an explicit persistent library ID, declaration kind, and declaration path, independent of artifact hashes and source order.
A new revision keeps Point fields but changes its ownership rules.MUSTValidate the required semantic ABI, layouts, call and ownership contracts, retained generic code, target, and compiler/runtime requirements before semantic import. Reject missing or ambiguous correspondence.
Importing geometry as g must not create a new Point type.MUST NOTLet aliases, import order, or local names change a declaration's identity.
geometry.Point and screen.Point both contain two integers.MUST NOTTreat types from unrelated library identities as interchangeable just because their names or layouts match.
A new compiler changes its default spelling for make_point.MUSTRead or reproduce the producer's symbol names, including when current naming defaults differ.
A generic instantiated with (A, B) differs from (B, A).MUSTInclude the generic declaration, enclosing specialization if present, and concrete arguments in order.
Two dependencies carry the same generic specialization.MUSTCheck ABI and generic semantics compatibility before merging definitions.
An exported generic calls a private helper.MUSTKeep declarations used by exported generic bodies in the import contract, even when source code cannot name them.
Two imports reach the same library counter.MUSTPreserve one identity when several dependency paths reach the same global.

Experimental implementation

shapes_user.moon embeds shapes v1
app lists shapes_user.moon and shapes v1.1
app calls shapes_user.read(point_from_v1_1)

The call works when both shapes revisions declare the same library_id and have compatible ABI contracts. The reader borrows the v1.1 point; its own code and declarations still come from v1.

If v2 changes Point's layout, passing a v2 point to that reader fails. The app can still use v2 independently alongside the reader's embedded v1.

This currently supports class and enum borrows. A const ref cannot become a mutable ref, and different generic arguments remain distinct.

See the runnable identity example.

Open decisions

Specify the portable-key encoding, symbol spelling, specialization encoding, and collision handling. Content hashes distinguish artifacts; they do not prove that types, layouts, or behavior are compatible.