Skip to content

Commit 53cf7a5

Browse files
committed
fix: close syntax audit and Edition profile gaps
1 parent 7228a52 commit 53cf7a5

42 files changed

Lines changed: 658 additions & 256 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎BRANCHES.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@ discussions. Do not use that historical baseline to describe the current
99
## nightly-0.23
1010

1111
`nightly-0.23` is the active edition and native-release-tooling line. It has one
12-
mandatory source/ABI contract, `edition = "2026"`, and deliberately rejects
12+
mandatory source-semantics epoch, `edition = "2026"`, plus an independently
13+
resolved target/assurance/ABI/schema profile, and deliberately rejects
1314
older package, lock, deployment, receipt, builder, and raw entry-witness
1415
identities rather than migrating them. Treat the line as merge-ready only when
1516
the edition/profile identity is consistent across compiler, metadata, WASM,

‎CHANGELOG.md‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,28 @@
22

33
## Unreleased
44

5+
- Close the 0.23 syntax-audit consistency gaps: canonical type declarations
6+
now use comma-terminated fields, syntax-combination gates cover canonical and
7+
comma-free compatibility input, checked example mirrors use named `U64_MAX`
8+
overflow expressions, and `dev` / `ci` reject regressions. CKB-VM crypto
9+
primitive fixtures now place `CSARGv1` through the current
10+
`WitnessArgs.input_type` adapter path instead of the retired raw-witness
11+
alias.
512
- Make `edition = "2026"` the single mandatory CellScript package contract.
6-
The resolved edition profile now binds source semantics, target and primitive
7-
assurance, entry payload ABI, and group-relative
8-
`WitnessArgs.input_type` placement across metadata, cache keys, registry
9-
records, `Cell.lock` v2, `Deployed.toml` v2, compile receipts v2, generated
10-
builders, native APIs, WASM, LSP, and the playground. Missing or different
11-
editions and older persisted schemas are rejected; no migration or
12-
compatibility reader is provided. Generated CKB entries also remove the
13-
raw-`CSARGv1` witness fallback, so Edition 2026 accepts the payload only
14-
inside canonical `WitnessArgs.input_type`. The not-yet-deployed public
15-
registry is defined by one current contract: signed entries, the initial
16-
database schema, CDN JSON, and the website all require Edition 2026 and the
13+
Edition is now explicitly a long-lived source-semantics epoch rather than an
14+
annual release or complete ABI bundle. The resolved compatibility profile
15+
independently composes source semantics, target, primitive assurance, entry
16+
payload and placement ABIs, and metadata schemas under
17+
`cellscript-resolved-compatibility-profile-v1`. Metadata schema 57 carries
18+
those axes, and their hash remains bound across cache keys, registry records,
19+
`Cell.lock` v2, `Deployed.toml` v2, compile receipts v2, generated builders,
20+
native APIs, WASM, LSP, and the playground. Missing or different editions
21+
and older persisted schemas are rejected; no migration or compatibility
22+
reader is provided. Generated CKB entries also remove the raw-`CSARGv1`
23+
witness fallback, so placement ABI v2 accepts the payload only inside
24+
canonical `WitnessArgs.input_type`. The not-yet-deployed public registry is
25+
defined by one current contract: signed entries, the initial database
26+
schema, CDN JSON, and the website require both Edition 2026 and the separate
1727
compatibility-profile hash, with no fallback reader for incomplete entries.
1828
The generic admin API can no longer manufacture `verified_build` or
1929
`deployed` claims without an evidence-specific path. See the

‎README.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -734,11 +734,15 @@ deny_ckb_runtime = false
734734
deny_runtime_obligations = false
735735
```
736736

737-
`edition = "2026"` is mandatory and is the only supported edition. It binds
738-
the source, ABI, metadata, lockfile, deployment, receipt, and builder contract;
739-
older or missing editions are rejected rather than migrated. Command-line
740-
flags can tighten policy checks for a build or CI job. The full contract is in
741-
the [edition policy](docs/CELLSCRIPT_EDITION_POLICY.md).
737+
`edition = "2026"` is mandatory and is the only supported source-semantics
738+
edition. The year is a long-lived epoch label, not an annual release cadence.
739+
Target profile, primitive assurance, metadata schemas, and entry/witness ABIs
740+
remain independently versioned; the resolved compatibility profile combines
741+
those axes with the edition and is bound into lock, deployment, receipt,
742+
registry, and builder identities. Older or missing persisted identities are
743+
rejected rather than migrated. Command-line flags can tighten policy checks
744+
for a build or CI job. The full contract is in the
745+
[edition policy](docs/CELLSCRIPT_EDITION_POLICY.md).
742746

743747
### Package Workflow
744748

‎docs/CELLSCRIPT_EDITION_POLICY.md‎

Lines changed: 95 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,10 @@
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

910
The 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
1718
other than `2026` is an error. The 0.23 line does not provide an edition
1819
migration 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
4783
flowchart 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.

‎docs/CELLSCRIPT_ENTRY_WITNESS_ABI.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,11 @@ therefore named `place_entry_witness_payload_before_signing`, accepts a lock
4242
placeholder, validates the `CSARGv1\0` payload magic, and must run before the
4343
SDK unlock/sign step.
4444

45-
Edition 2026 has no raw-payload compatibility path. The selected group-relative
46-
witness must be a canonical `WitnessArgs`; a raw `CSARGv1\0` payload, malformed
47-
table, absent `input_type`, or payload placed in `lock`/`output_type` fails
48-
closed with runtime error `25 entry-witness-abi-invalid`.
45+
Placement ABI `cellscript-witnessargs-input-type-v2` has no raw-payload
46+
compatibility path. The selected group-relative witness must be a canonical
47+
`WitnessArgs`; a raw `CSARGv1\0` payload, malformed table, absent `input_type`,
48+
or payload placed in `lock`/`output_type` fails closed with runtime error
49+
`25 entry-witness-abi-invalid`.
4950

5051
## Payload Envelope v1
5152

@@ -57,10 +58,11 @@ Every parameterized entry payload that has witness-backed arguments starts with:
5758

5859
This is the ASCII magic `CSARGv1\0`.
5960

60-
The magic remains necessary even though Edition 2026 selects this ABI: the
61-
edition is a compile/tooling rule bundle, while the magic identifies the
62-
runtime bytes inside `input_type`. It prevents unrelated protocol bytes from
63-
being decoded as CellScript positional arguments.
61+
The magic remains necessary even though the resolved compatibility profile
62+
records this ABI: Edition 2026 identifies source semantics, the placement ABI
63+
identifies the witness location, and the magic identifies runtime bytes inside
64+
`input_type`. It prevents unrelated protocol bytes from being decoded as
65+
CellScript positional arguments.
6466

6567
Wrong magic, missing bytes, malformed Molecule, or unsupported parameter
6668
placement fails closed with runtime error `25 entry-witness-abi-invalid`.

‎docs/CELLSCRIPT_GATE_POLICY.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,13 @@ no Python runtime dependency and reject tracked Python source files.
4646

4747
The 0.23 line also has one edition contract: every package declares
4848
`edition = "2026"`, and all emitted evidence binds the resolved compatibility
49-
profile. Missing/non-2026 editions and superseded lock, deployment, receipt,
50-
builder, or raw-witness placement identities are rejected rather than
51-
migrated. See
49+
profile. The edition owns source semantics only; target, primitive assurance,
50+
metadata schemas, and entry/witness ABIs remain independent profile axes.
51+
Missing/non-2026 editions and superseded lock, deployment, receipt, builder, or
52+
raw-witness placement identities are rejected rather than migrated. See
5253
[`CELLSCRIPT_EDITION_POLICY.md`](CELLSCRIPT_EDITION_POLICY.md). Edition-owned
53-
ABI changes require the `backend` gate in addition to ordinary `dev` and `ci`
54+
source changes require complete frontend closure. Independently versioned ABI
55+
changes require the `backend` gate in addition to ordinary `dev` and `ci`
5456
coverage.
5557

5658
The `ci` gate also typechecks, tests, and performs a Wrangler dry-run build of

0 commit comments

Comments
 (0)