Repository navigation
[Docs/strategy] Separate executable-surface closure from product capability completeness #14
Description
Summary
Document a precise distinction between:
- executable-surface closure — whether every syntax/IR shape already admitted by CellScript is complete, bounded, shape-gated, compile-time-only, or reserved; and
- product capability completeness — whether important CKB protocol workflows have a first-class language, artifact, builder, and evidence model at all.
The current executable-surface registry is valuable and should remain authoritative for admitted compiler shapes. It cannot prove that no important capability is missing outside the current AST/IR universe.
This issue creates a durable capability-gap ledger and connects it to the post-0.25 strategy without weakening the 0.25 scope freeze.
Why the distinction matters
A registry can be complete over its declared entries while an entire product-level feature remains unmodeled:
flowchart TB
ALL["CKB protocol capability space"] --> IN["Admitted CellScript surface"]
ALL --> OUT["Not-yet-modeled capabilities"]
IN --> COMPLETE["complete / bounded"]
IN --> SHAPE["shape-gated"]
IN --> RESERVED["reserved / fail-closed"]
OUT --> BUNDLE["multi-artifact ProtocolBundle"]
OUT --> ROLES["typed cross-Script roles"]
OUT --> HANDLE["interface-bound Script handles"]
OUT --> TEMP["typed temporal domains"]
OUT --> COMMIT["typed committed substate"]
REG["Executable-surface registry"] --> IN
REG -. "does not enumerate" .-> OUT
Without this distinction, wording such as “the only remaining feature gap” can accidentally mean either:
- the only reserved entry in the current registry; or
- the only product capability CellScript lacks.
Only the first claim can be established by enumerating the existing compiler surface.
Proposed documentation taxonomy
Every tracked capability should declare:
| Field | Meaning |
|---|---|
| capability ID | stable human/machine identifier |
| category | language, consensus runtime, artifact, builder, tooling, assurance, ecosystem |
| admission state | absent, research, reserved, shape-gated, bounded, complete |
| on-chain status | none, metadata-only, fail-closed, executable |
| builder status | none, scaffold, checked, complete transaction path |
| evidence status | none, simulator, CKB-VM, stateful, chain |
| interface status | absent, private, package, public/versioned |
| owner/RFC | accountable owner and accepted design record |
| dependencies | other issues/capabilities |
| release eligibility | experimental, candidate, stable |
| non-goals | explicitly excluded adjacent features |
The executable-surface JSON remains the machine truth for admitted compiler entries. A separate capability ledger may reference those IDs but must not duplicate or overwrite their statuses.
Initial capability ledger
Admitted but reserved consensus/runtime work
- [Candidate][Consensus runtime] Implement executable bounded Cell-group consumption #7 — executable bounded Cell-group consumption.
- [Candidate][Consensus runtime] Implement executable bounded output-plan correspondence #8 — executable bounded output-plan correspondence.
Not yet modeled as first-class product capabilities
- [Architecture][Builder] Add an artifact-only multi-Script ProtocolBundle #9 — artifact-only multi-Script ProtocolBundle.
- [Language design] Model typed cross-Script transaction roles without runtime linkage #10 — typed cross-Script transaction roles.
- [Language/ABI] Bind runtime Script values to verified package interfaces #11 — interface-bound runtime Script handles.
- [Language/stdlib] Add typed CKB temporal and Since domains #12 — typed CKB temporal and
Sincedomains. - [Language design] Add explicit typed openings for digest-committed substate #13 — explicit typed openings for digest-committed substate.
These issues are not all release blockers. The ledger must distinguish priority and stabilization state rather than presenting a flat “missing features” list.
Toolchain correctness and product gaps
- [Toolchain][CKB environment][P0] Make transitive dependency selection chain-identity-safe #17 — chain-identity-safe transitive environment selection and panic removal; current correctness P0.
- [Toolchain][Workspace][P1] Replace member-loop builds and synthetic workspace locks with a canonical graph #15 — canonical workspace resolve/build graph.
- [Toolchain][Resolver][P1] Define and enforce package instance, version, source, and feature unification #16 — normative package instance and unification semantics.
- [Toolchain][Compatibility][P1] Enforce package-declared CellScript compiler requirements #18 — active compiler-requirement enforcement.
- [Toolchain][Introspection] Expose a stable package resolve graph and build-unit plan #19 — stable read-only resolve graph and build-unit plan.
- [Toolchain][Upgrade] Add a transactional package, interface, and deployment upgrade plan #20 — transactional package/interface/deployment upgrade planning.
These are not additional language features. They are prerequisites for making higher-level composition and upgrade claims reproducible and inspectable.
Required strategy wording
Post-0.25 planning should use wording equivalent to:
Bounded lifecycle collection execution is the highest-risk consensus-semantic gap already admitted into CellScript syntax and IR. It remains a candidate workstream until Evidence Review accepts its use cases, owner, reviewer, capacity, and stop conditions.
It should avoid an unqualified claim that bounded collections are the only missing product capability.
The strategy should also say:
- 0.25 remains a stability and release-closure line;
- [Candidate][Consensus runtime] Implement executable bounded Cell-group consumption #7 and [Candidate][Consensus runtime] Implement executable bounded output-plan correspondence #8 require accepted consensus-facing specifications and portfolio evidence review before positive lowering;
- [Architecture][Builder] Add an artifact-only multi-Script ProtocolBundle #9 may begin as an artifact/tooling prototype without new syntax;
- [Language design] Model typed cross-Script transaction roles without runtime linkage #10 and [Language/ABI] Bind runtime Script values to verified package interfaces #11 remain research/RFC work until ProtocolBundle supplies evidence;
- [Language/stdlib] Add typed CKB temporal and Since domains #12 is a bounded type-safety improvement with edition migration;
- [Language design] Add explicit typed openings for digest-committed substate #13 is optional and use-case-driven, not a core-language completeness blocker;
- no issue receives a release promise without an owner, reviewer, acceptance criteria, and evidence gate.
Relationship diagram
graph TD
F["0.25 stable closure"] --> C1["#7 bounded consume"]
C1 --> C2["#8 bounded create correspondence"]
F --> PB["#9 ProtocolBundle prototype"]
PB --> XR["#10 typed cross-Script roles"]
PB --> IH["#11 exact interface-bound handles"]
XR --> OPEN["open-role stabilization"]
IH --> OPEN
F --> TT["#12 typed temporal domains"]
F --> CS["#13 committed substate research"]
ASSURE["semantic assurance / checker / CKB-VM"] --> C1
ASSURE --> C2
ASSURE --> PB
ASSURE --> XR
ASSURE --> IH
ASSURE --> TT
ASSURE --> CS
This is a dependency map, not a release schedule.
Documentation changes
Update the appropriate tracked documents after the post-0.25 strategy is accepted:
- documentation map;
- post-0.25 strategy/RFC;
- executable-surface documentation;
- collections matrix;
- public-interface and builder boundary docs;
- edition policy for [Language/stdlib] Add typed CKB temporal and Since domains #12;
- language/tooling tutorials when a capability advances state.
Add a short rule to the documentation conventions:
“Complete” must always name its universe: compiler surface, selected shapes, artifact boundary, builder path, evidence tier, or product capability.
Completion criteria
- A tracked document defines executable-surface closure versus product capability completeness.
- The executable-surface registry remains authoritative and unmodified in meaning.
- A separate versioned capability ledger records absent/research capabilities.
- Each initial capability links to [Candidate][Consensus runtime] Implement executable bounded Cell-group consumption #7–[Toolchain][Upgrade] Add a transactional package, interface, and deployment upgrade plan #20 and records status, priority, owner, dependencies, evidence, and non-goals.
- Post-0.25 strategy wording qualifies the bounded-lifecycle claim precisely.
- The documentation makes clear that the dependency diagram is not a release promise.
- Every “complete” claim names its scope and evidence universe.
- Docs, website/release copy, generated surface matrix, and tutorials use consistent terminology.
- A documentation test or gate rejects invalid capability/admission-state values and broken issue/RFC links.
- No absent/research capability is advertised as implemented.
Non-goals
- expanding 0.25 implementation scope;
- assigning release dates;
- converting every idea into a language feature;
- weakening E2105 or fail-closed policy;
- duplicating the executable-surface registry;
- treating issue creation as feature acceptance;
- claiming the Argent comparison is a production-equivalence assessment.
Activity
a19q3 commentedon Aug 27, 2026
Research update: capability ledger should now include the package/toolchain audit
Comment audit
There were no prior comments on this issue at the time of review.
The deep comparison produced two categories of findings:
I opened six detailed toolchain issues:
These should be first-class entries in the capability ledger, but not in the executable-surface registry because none is an AST/IR executable shape.
Code-level comparison result
Important positive findings
The comparison does not imply that CellScript's package toolchain is primitive. It already has several stronger or more security-oriented properties:
The future direction should preserve these boundaries.
What to borrow from Cargo
Borrow the architectural ideas:
Do not copy arbitrary build.rs execution. Cargo's build scripts are powerful but add environment, filesystem, toolchain, and rerun tracking complexity. CellScript's current fail-closed [build.dependencies] policy is correct until a real use case justifies a capability-bounded, deterministic, isolated build action model.
What to borrow from Move/Sui
Borrow:
Do not copy account/object package publishing into CKB. CellScript should express code CellDeps, data hashes, Type-hash/TYPE_ID deployment lines, Script Groups, and genesis-bound environments in CKB-native terms.
Priority recommendation
This is a dependency ordering, not a release schedule:
Immediate correctness
Tooling foundation
Delivery and ecosystem
Capability ledger structure
The audit suggests three linked but non-overlapping ledgers:
Each entry should carry:
A generated validator should reject an entry that says complete without naming the universe and required evidence fields.
Wording recommendation
A precise post-0.25 statement is:
This preserves the value of the executable-surface registry without turning it into a claim about the whole product space.
Primary code references
Cargo:
Move/Sui:
Conclusion
This issue should be expanded from a language/product ledger into a cross-layer capability ledger with explicit ownership. The new toolchain findings do not make the 0.25 executable-language surface incomplete. However, #17 is a current resolver correctness issue and must be triaged into release closure rather than hidden as future capability work; #15, #16, #18, #19, and #20 remain separately prioritized toolchain follow-ups.
a19q3 commentedon Sep 11, 2026
Implemented on the 0.30 branch in 1e2f642.
The branch now has:
Repository-side acceptance scope is complete and the ledger recommends close-after-merge/readback. This comment does not claim that 0.30 itself is release-complete.
a19q3 commentedon Sep 11, 2026
Repository scope is complete. The versioned capability ledger and validator landed in
1e2f6425, keep executable-surface status distinct from product/release evidence, and now reflect exact scenario/runtime evidence plus explicit closure/defer dispositions throughcdc5b53c. Release-facing issues remain open; closing this documentation/strategy issue does not claim 0.30 release completion. No TAC or release workflow was invoked.a19q3 commentedon Sep 19, 2026
The release-facing ledger enforcement is now complete in candidate 74cff5fd. Both release modes invoke the strict
check-business-corpus --releasepreflight before CI; it requires the accepted corpus, stable required capabilities, completed release evidence, and an assigned reviewer unless review is explicitly waived. The current strict check passes for 8 families and 76 evidence files.Release eligibility still does not mean public publication. #25/#26 are now closed after their evidence and product gitlinks were pushed; #27 remains open under the no-TAC constraint, while #22/#28/#29 remain deferred. The dated audit records all 24 issue dispositions and corrects stale repository status wording. This issue remains closed for its accepted documentation/ledger scope.