[Language design] Choose a stable surface for value generics and public API signatures #23

Decision

Before CellScript 0.25 is stabilized, decide whether user-defined value generics are part of the dependency-facing language or remain a package-local implementation mechanism.

Default recommendation: choose Proposal B unless concrete 0.25 packages demonstrate that cross-package user-defined generic libraries are required and Proposal A's normalization rules can be specified completely.

This is a bounded language-design decision. It is not a proposal for generic Cells, generic entry points, dynamic dispatch, traits, or runtime type reflection.

At a glance

flowchart TD
    NEED{"Does 0.25 have a concrete cross-package<br/>user-defined generic requirement?"}
    PROFILE{"Can a closed constraint profile,<br/>derivation rules, and canonical identity<br/>be specified completely?"}
    A["Proposal A<br/>Stabilize restricted public generics"]
    B["Proposal B<br/>Keep user generics package-local"]
    NEED -- "No" --> B
    NEED -- "Yes" --> PROFILE
    PROFILE -- "Yes" --> A
    PROFILE -- "No" --> B

Why this needs an explicit decision

The existing implementation has strong safety properties, but its ordinary source form exposes a large amount of compiler vocabulary:

public struct Pair<T: copy + drop + store + fixed + serializable + non_linear>
    has copy, drop, store, fixed, serializable, non_linear
{
    left: T,
    right: T,
}

The author's intent is much simpler:

T is an ordinary, fixed-width, serializable, non-Cell value.

Three costs currently leak into the user experience:

1. Constraint repetition: six properties appear on both the parameter and the resulting type.
2. Compatibility commitment: exporting a template commits its parameter count, phantom status, bounds, resulting abilities, layouts, and accepted applications.
3. Interface overload: the canonical audit record is appropriately detailed, but that detail is not a good default human review surface.

Current 0.25 baseline

The implementation already provides:

• deterministic, budgeted monomorphization before IR;
• generic structs, enums, and pure functions;
• explicit parameters, phantom parameters, and value-ability constraints;
• built-in Option<T> and generic fixed arrays;
• specialization of imported public templates in their owning module;
• rejection of generic Cell-backed values;
• canonical package interfaces containing exported templates and applied types;
• exclusion of implementation-only monomorphizations from the public interface;
• compatibility comparison across source API, serialized layout, runtime ABI, effects/capabilities, generated builders, and deployment contracts.

Reference comparison: Move and Sui Move

Move is the closest mature reference design, but its execution and package model differ materially from CellScript.

What Move does

Primary implementation references:

• Move generics and type inference
• Move's four abilities and conditional ability derivation
• Generic datatype and function signatures in Move bytecode
• Move bytecode compatibility rules
• Sui package upgrade requirements
• Sui verifier-level private generics

Why the precedent is only partial

flowchart LR
    subgraph MOVE["Move / Sui"]
        MS["Public generic source"] --> MB["Generic bytecode<br/>handles, constraints, instantiations"]
        MB --> MV["Bytecode verifier and Move VM"]
    end

    subgraph CELL["CellScript 0.25"]
        CS["Generic source template"] --> CM["Deterministic bounded<br/>monomorphization before IR"]
        CM --> CI["Concrete IR and CKB-VM artifact"]
    end

Move keeps generic definitions and instantiations as first-class bytecode concepts. CellScript deliberately specializes them before IR and emits concrete CKB-VM code. Consequently, a CellScript public generic template also commits to source availability, package-instance identity, owning-module specialization, specialization budgets, concrete layout, and artifact evidence.

Move also has foundational public-generic use cases such as Coin<phantom T>, Balance<phantom T>, Option<T>, and vector<T>. CellScript's user-defined generics are restricted to non-Cell values, so the need for third-party public generic libraries must be demonstrated separately.

Lesson for this issue

Move supports the direction of Proposal A, but the reusable lesson is not “expose every constraint.” It is:

1. keep the source-level property vocabulary small and closed;
2. infer structural properties where the result is deterministic;
3. treat public generic bounds as ABI commitments;
4. keep the complete representation in compiler-owned metadata;
5. apply additional restrictions at authority-sensitive operations;
6. let tooling, rather than a second handwritten file, enforce compatibility.

Proposal A: restricted public generics with a compact source surface

Public generic templates remain available across packages, but the common source form describes intent instead of repeating the expanded property set.

The name remains an RFC choice; fixed_value is illustrative:

public struct Pair<T: fixed_value> {
    left: T,
    right: T,
}

The compiler would normalize that profile to the precise accepted properties, for example:

copy + drop + store + fixed + serializable + non_linear

Where safe, result abilities are derived structurally from fields. The profile and derivation algorithm must be closed, versioned, deterministic, non-overridable, and independently checkable. Compact and expanded spellings must produce the same semantic interface identity.

Layered interface presentation

flowchart TD
    SRC["Source<br/>Pair&lt;T: fixed_value&gt;"] --> NORM["Canonical normalization<br/>expanded abilities + layouts"]
    NORM --> HUMAN["Default human view<br/>exports, concise signatures, breaking changes"]
    NORM --> JSON["Canonical JSON<br/>full constraints, ABI, builders, deployment"]
    JSON --> CHECK["Registry + standalone checker<br/>hash and compatibility enforcement"]

The default human view could be:

public struct Pair<T: fixed_value>
public fn first<T: fixed_value>(Pair<T>) -> T

Detailed or JSON output would expose the expanded abilities, phantom status, layouts, ABI/profile identities, builder contracts, and deployment identities.

Benefits

• Preserves cross-package generic library reuse.
• Retains the existing monomorphization and interface work.
• Keeps common source and review output concise.
• Preserves complete audit evidence in the machine representation.

Risks

• fixed_value becomes a versioned semantic contract.
• Public generic bounds become long-term compatibility commitments.
• Structural derivation must be specified for structs, enums, tuples, arrays, and future fixed values.
• Cross-package specialization remains coupled to package and owning-module identity.

Gate for choosing A

Choose Proposal A only if all of the following are demonstrated before stabilization:

• at least one concrete 0.25 use case requires cross-package user-defined generics;
• a closed profile can be specified without creating an open trait system;
• all equivalent spellings normalize to one interface identity;
• the default human interface remains concise;
• package-instance and owning-module identities are sufficient for safe specialization;
• compatibility behavior for relaxing and tightening every bound is specified and tested.

Proposal B: keep user-defined generics package-local in 0.25

Keep the generic engine and safety work, but defer dependency-facing user-defined templates.

• User-defined generic structs, enums, and pure functions may be private or public(package).
• A public generic declaration is rejected with a targeted diagnostic.
• Built-in Option<T> and fixed arrays remain supported.
• Concrete applied types such as Option<u64> may appear in public signatures.
• External APIs use concrete exported types or wrapper functions.
• Internal instantiations remain in typed evidence but stay out of the dependency interface.

Benefits

• Keeps the stable public language and interface smaller.
• Preserves most of the implemented generic machinery.
• Avoids premature cross-package specialization commitments.
• Leaves room for a cleaner public-generic design in a later schema/version transition.

Risks

• Third-party packages cannot publish generic value libraries in the 0.25 line.
• Some package boundaries may need concrete wrappers or duplicated declarations.
• Existing nightly packages with public generic templates require migration.

Compatibility rules required by either decision

Unlike Move, CellScript cannot assume that relaxing a bound is automatically safe: a larger accepted type set may cross fixed-layout, serialization, code-size, specialization-budget, builder, or deployment boundaries. All six compatibility dimensions still apply.

Evidence requested before resolution

Please contribute concrete examples rather than syntax preference alone:

1. Which package requires user-defined generics rather than built-in Option<T> or arrays?
2. Which use case specifically requires cross-package specialization?
3. Which exported template cannot reasonably be represented by concrete wrappers?
4. Which ability combinations occur in real packages?
5. Does a real package require phantom identity for a non-Cell value?
6. What should a maintainer see in the default human interface view?

API signatures versus cryptographic signatures

Here, signature means a public type or callable API signature: type parameters, parameter types, return types, effects, and ABI-relevant qualifiers.

Cryptographic signatures are a separate security boundary. Neither proposal introduces implicit signers, hidden sighash defaults, or new signature-verification syntax. Transaction digest/domain, Script group, witness placement, identity binding, verifier/CellDep identity, replay policy, and authorization policy remain explicit.

Acceptance criteria

• One proposal is selected in an accepted language-design decision.
• Source syntax, visibility, and normalization are documented normatively.
• Generic Cell-backed types and generic entries remain rejected.
• Equivalent source forms produce one canonical semantic interface identity.
• Private generic changes do not change the public interface hash.
• Human output is concise and canonical JSON remains complete.
• Interface diffs classify generic changes in the correct compatibility dimensions.
• Registry admission and the independent verifier enforce the selected boundary.
• Typed semantics and the artifact checker retain complete instantiation evidence.
• Parser, formatter, type checker, resolver, monomorphization, IR, codegen, metadata, LSP, VS Code, Playground, docs, and syntax-combination tests agree.
• Migration from the current nightly surface is explicit and tested.
• Release notes describe the accepted boundary without presenting CellScript as a general-purpose generic language.
• The dev, ci, and backend gates pass.

Related work

• [Language/stdlib] Add typed CKB temporal and Since domains #12 needs an explicit decision on the generic spelling of typed Since domains.
• [Toolchain][Resolver][P1] Define and enforce package instance, version, source, and feature unification #16 owns package-instance and version/source/feature identity used by cross-package specialization.
• [Language/ABI] Bind runtime Script values to verified package interfaces #11 binds runtime Script values to verified package interfaces and should consume, not broaden, this boundary.

CellScript references

• 0.25 release notes
• Public interfaces and compatibility
• Generic value syntax-combination seed
• Grammar governance
• Surface elegance and signature boundaries