22
33** Status** : normative for the 0.23 development line.
44
5- CellScript uses an edition as one explicit name for the complete language and
6- ABI contract selected by a package. It serves the same organizational purpose
7- as a Rust edition, but it also binds CellScript-specific CKB conventions.
5+ CellScript editions are long-lived source-language semantic epochs. An edition
6+ answers one question: how should this CellScript source be understood? The year
7+ in an edition label is an identifier, not an annual release schedule. Edition
8+ 2026 may remain current across multiple compiler release years.
89
910The only supported edition is:
1011
@@ -16,69 +17,111 @@ edition = "2026"
1617` edition ` is mandatory in every package manifest. A missing value or any value
1718other than ` 2026 ` is an error. The 0.23 line does not provide an edition
1819migration command, an implicit alternate edition, or a compatibility parser
19- because Edition 2026 is the first CellScript edition contract.
20+ because Edition 2026 is the first CellScript source-semantics contract.
2021
21- ## What The Edition Selects
22+ ## What The Edition Owns
2223
23- Edition 2026 resolves one compatibility profile from :
24+ An edition owns rules that can change the meaning of the same source text :
2425
25- - source-language semantics ;
26- - target profile ;
27- - primitive-assurance mode ;
28- - entry payload ABI;
29- - CKB ` WitnessArgs ` placement ABI and script-group source .
26+ - keywords, reserved words, and resolution of syntactic ambiguities ;
27+ - name resolution, scope behavior, and the default prelude ;
28+ - type checking, inference defaults, coercions, and flow/resource rules ;
29+ - desugaring and other source-observable semantics; and
30+ - edition-specific deprecation diagnostics and migration lints .
3031
31- For the CKB target, the resolved profile requires:
32+ Edition 2026 currently identifies those rules as
33+ ` cellscript-source-semantics-2026 ` . Because it is the first and only edition,
34+ the frontend has no alternate parser or type-checker branch yet. The edition is
35+ still carried through package loading and emitted identity so a future
36+ semantic break cannot be mistaken for the same source contract.
3237
33- | Contract | Edition 2026 value |
38+ Additive syntax, diagnostics, formatter improvements, and optimizer changes do
39+ not require a new edition when existing source keeps its meaning. A new edition
40+ is justified only when an intentional source-semantic break cannot be handled
41+ by an additive feature, a warning/deprecation cycle, or an independently
42+ versioned schema or ABI.
43+
44+ ## Independent Compatibility Axes
45+
46+ The edition does ** not** own the compiler release, target profile,
47+ primitive-assurance mode, metadata schemas, or CKB wire ABIs. The compiler
48+ assembles those independently versioned values with the source edition into a
49+ resolved compatibility profile:
50+
51+ | Axis | Current 0.23 value |
3452| ---| ---|
53+ | Source edition | ` 2026 ` |
54+ | Source semantics | ` cellscript-source-semantics-2026 ` |
55+ | Compiler release | workspace SemVer (` 0.x.y ` ), recorded separately |
56+ | Target profile | selected independently, normally ` ckb ` |
57+ | Primitive assurance | selected independently, or ` default ` |
3558| Payload ABI | ` cellscript-entry-witness-v1 ` (` CSARGv1\0 ` ) |
3659| Placement ABI | ` cellscript-witnessargs-input-type-v2 ` |
60+ | Metadata schemas | metadata 57, source 2, artifact 1, constraints 2 |
61+
62+ The compiler release is recorded next to the profile but is not part of the
63+ profile itself. A compiler patch may change diagnostics or optimization
64+ without changing compatibility. Conversely, an urgent wire-ABI or metadata
65+ fix can advance its own version immediately without waiting for a new calendar
66+ year or source edition.
67+
68+ For the current CKB placement profile:
69+
70+ | Contract | Value |
71+ | ---| ---|
3772| Placement field | ` WitnessArgs.input_type ` |
3873| Witness source | ` GroupInput#0 ` , then ` GroupOutput#0 ` |
3974| Raw payload alias | rejected |
4075
41- The resolved profile is emitted in compile metadata and hashed into package,
42- registry, lockfile, deployment, receipt, and generated-builder identities.
43- Changing one of these choices therefore changes the identity even when source
44- text is otherwise identical.
76+ The resolved profile uses schema
77+ ` cellscript-resolved-compatibility-profile-v1 ` . It is emitted in compile
78+ metadata and hashed into package, registry, lockfile, deployment, receipt, and
79+ generated-builder identities. Changing any constituent axis changes the
80+ profile identity even when source text and edition stay the same.
4581
4682``` mermaid
4783flowchart LR
48- M["Cell.toml<br/>edition = 2026"] --> R["ResolvedCompatibilityProfile"]
49- T["target_profile + primitive assurance"] --> R
50- R --> C["compiler semantics and codegen"]
51- R --> A["metadata + ABI hash"]
52- R --> P["registry + Cell.lock + Deployed.toml"]
53- R --> B["receipt + generated builder"]
84+ E["Source edition<br/>2026"] --> R["ResolvedCompatibilityProfile"]
85+ T["target profile"] --> R
86+ P["primitive assurance"] --> R
87+ W["entry + placement ABI"] --> R
88+ S["metadata schemas"] --> R
89+ R --> M["compile metadata + profile hash"]
90+ M --> I["registry + Cell.lock + Deployed.toml"]
91+ M --> B["receipt + generated builder"]
5492```
5593
94+ Registry records therefore retain both ` edition ` and
95+ ` compatibility_profile_hash ` . The former tells source consumers how to read the
96+ package; the latter commits to the complete compile/build contract. A registry
97+ consumer must not infer target, primitive, ABI, or metadata versions from the
98+ edition year.
99+
56100## Why ` CSARGv1 ` Still Exists
57101
58- The edition and ` CSARGv1 ` solve different problems.
102+ The source edition and ` CSARGv1 ` solve different problems.
59103
60- - ` edition = "2026" ` tells the compiler and tooling which complete rule bundle
61- to use before a transaction exists.
62- - ` CSARGv1\0 ` identifies the bytes inside ` WitnessArgs.input_type ` while a CKB
104+ - ` edition = "2026" ` selects source-language meaning before a transaction
105+ exists.
106+ - ` CSARGv1\0 ` identifies CellScript positional-argument bytes while a CKB
63107 Script is executing.
108+ - ` cellscript-witnessargs-input-type-v2 ` identifies where those bytes are
109+ placed and how the script-group witness is selected.
64110
65- Without the payload magic, arbitrary protocol bytes could be mistaken for
66- CellScript positional arguments. Without the edition, tools could agree on the
67- same eight magic bytes while disagreeing about placement, source selection, or
68- compile semantics. Edition 2026 selects the payload ABI; it does not remove the
69- payload's on-wire discriminator.
70-
71- The old raw placement form—putting ` CSARGv1 ` directly in the witness instead of
72- inside a canonical ` WitnessArgs.input_type ` —is not accepted. It fails closed
73- with runtime error ` 25 entry-witness-abi-invalid ` .
111+ The current compatibility profile combines all three identities. The old raw
112+ placement form—putting ` CSARGv1 ` directly in the witness instead of inside a
113+ canonical ` WitnessArgs.input_type ` —is not accepted. It fails closed with
114+ runtime error ` 25 entry-witness-abi-invalid ` because the placement ABI says so,
115+ not because calendar year 2026 intrinsically implies a witness layout.
74116
75117## Persisted Format Boundary
76118
77- Edition 2026 deliberately starts new persisted identities:
119+ The 0.23 line deliberately starts new persisted identities:
78120
79121| Surface | Required identity |
80122| ---| ---|
81- | Compile metadata | metadata 56, source 2, artifact 1, constraints 2 |
123+ | Compile metadata | metadata 57, source 2, artifact 1, constraints 2 |
124+ | Compatibility profile | ` cellscript-resolved-compatibility-profile-v1 ` with every independent axis |
82125| ` Cell.lock ` | version 2 |
83126| ` Deployed.toml ` | version 2 and ` cellscript-deployed-v0.23-edition-2026 ` |
84127| Compile receipt | ` cellscript-compile-receipt-v2 ` |
@@ -94,16 +137,22 @@ a package manifest must receive the edition explicitly:
94137
95138- native metadata-only Rust APIs take ` CellScriptEdition ` ;
96139- WASM exports take an edition string and accept only ` "2026" ` ;
97- - browser workers pass ` "2026" ` explicitly;
140+ - browser workers pass ` "2026" ` explicitly; and
98141- LSP package compilation resolves the nearest package manifest.
99142
100143` CompileOptions::default() ` uses the current edition only for in-memory and
101- standalone compiler use. It is not a fallback for a package missing
102- ` edition ` .
144+ standalone compiler use. It is not a fallback for a package missing ` edition ` .
145+
146+ ## Release And Evolution Requirements
147+
148+ Different axes have different closure requirements:
103149
104- ## Release Requirement
150+ - source-semantic changes require a new edition plus parser, formatter, type
151+ checking, lowering, metadata, LSP, migration diagnostics, docs, and tests;
152+ - entry or placement ABI changes require a new ABI identity plus codegen,
153+ builder, metadata, CKB-VM, ` backend ` , ` dev ` , and ` ci ` evidence;
154+ - metadata changes require a schema bump plus every reader/validator update;
155+ - target and primitive changes retain their own profile and gate contracts; and
156+ - compiler-only compatible improvements use ordinary SemVer releases.
105157
106- Changes to an edition-owned rule require matching updates to codegen, metadata,
107- identity hashes, builders, WASM, documentation, and tests. Because witness
108- placement affects generated RISC-V, such a change must pass the ` backend ` gate
109- as well as ` dev ` and ` ci ` .
158+ No edition is created merely because a year or compiler release changed.
0 commit comments