[Docs/strategy] Separate executable-surface closure from product capability completeness

[a19q3]

Summary

Document a precise distinction between:

1. executable-surface closure — whether every syntax/IR shape already admitted by CellScript is complete, bounded, shape-gated, compile-time-only, or reserved; and
2. 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

Loading

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 Since domains.
• [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

Loading

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.

References

• Generated executable-surface matrix
• Collections support matrix
• Public interfaces
• Gate policy
• Argent project status and feature surface

[a19q3]

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:

1. the original language/runtime/product gaps in [Candidate][Consensus runtime] Implement executable bounded Cell-group consumption #7–[Language design] Add explicit typed openings for digest-committed substate #13; and
2. independently actionable package/workspace/toolchain gaps found by comparing CellScript code with Move package-alt/Sui and Cargo.

I opened six detailed toolchain issues:

• [Toolchain][Workspace][P1] Replace member-loop builds and synthetic workspace locks with a canonical graph #15 — replace serial member-loop workspace builds and synthetic workspace lock nodes with a canonical workspace graph.
• [Toolchain][Resolver][P1] Define and enforce package instance, version, source, and feature unification #16 — define and enforce package instance/version/source/feature unification.
• [Toolchain][CKB environment][P0] Make transitive dependency selection chain-identity-safe #17 — P0: make transitive CKB environment selection chain-identity-safe and remove a reachable manifest-driven expect panic.
• [Toolchain][Compatibility][P1] Enforce package-declared CellScript compiler requirements #18 — enforce the existing package-declared CellScript compiler requirement.
• [Toolchain][Introspection] Expose a stable package resolve graph and build-unit plan #19 — expose stable read-only resolve-graph and build-unit-plan schemas.
• [Toolchain][Upgrade] Add a transactional package, interface, and deployment upgrade plan #20 — add transactional package/interface/deployment upgrade planning and impact analysis.

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

Concern	Cargo / Move reference	CellScript current state	Direction
resolution vs compilation	Cargo Resolve then UnitGraph; Move PackageGraph then BuildPlan	per-package graph exists, workspace bypasses it with a member loop	#15 and #19
workspace closure	Cargo one Workspace, shared roots and units	members compile independently; top-level lock stores synthetic artifact nodes	#15
package instance semantics	Cargo permits semver-incompatible duplicates under explicit rules; Move uses PackageID DAG	docs say single version, node IDs actually admit multiple instances, compiler flattens modules	#16
environment selection	Move records per-edge use_environment	CellScript propagates an ambient label and validates only root chain identity	#17
toolchain compatibility	Cargo actively enforces rust-version	PackageInfo.cellscript_version exists but is not validated	#18
graph introspection	Cargo metadata plus unit graph	metadata means compiled program; info means manifest; no resolved/build graph API	#19
incremental rebuilds	Cargo fingerprints units and dependencies	CellScript has a secure whole-entry content cache, not an observable unit graph	#19, after #15
upgrades	Sui separates authorization and compatibility; Cargo supports precise version selection	pairwise interface diff and deployment verification exist, but update writes before impact analysis	#20
build scripts/hooks	Cargo supports powerful arbitrary build scripts; Move exposes compiler-driver hooks	CellScript build dependencies remain reserved/fail-closed	keep fail-closed until a concrete hermetic design exists

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:

• manifest-digest-bound Cell.lock v3;
• exact immutable Git/Registry source identity;
• locked/frozen/offline behavior;
• feature and test roots;
• CKB environment genesis binding at the root;
• bounded hash-pinned external resolvers invoked only during explicit repinning;
• secure content-addressed incremental cache checks;
• six-dimensional interfaces;
• verified artifact sidecars and an independent checker;
• deployment and Registry trust evidence.

The future direction should preserve these boundaries.

What to borrow from Cargo

Borrow the architectural ideas:

• one explicit workspace object;
• separate package resolution and build units;
• deterministic machine-readable graph schemas;
• dependency-aware unit fingerprints and rebuild reasons;
• explicit compiler-version compatibility;
• precise/scoped update selection;
• clear distinction among normal, test, build, target, profile, and feature inputs.

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:

• rooted package DAGs with explicit package IDs;
• environment-specific pinned graphs and explicit dependency environment mappings;
• separation of package loading from BuildPlan compilation;
• edition/flavor/build-configuration identity;
• published/original identity as distinct concepts;
• explicit separation of upgrade compatibility, authorization, and immutable deployment.

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

• [Toolchain][CKB environment][P0] Make transitive dependency selection chain-identity-safe #17 first: a chain-identity mismatch and reachable panic are fail-closed correctness issues.
• [Toolchain][Workspace][P1] Replace member-loop builds and synthetic workspace locks with a canonical graph #15 and [Toolchain][Resolver][P1] Define and enforce package instance, version, source, and feature unification #16 next: workspace and resolver semantics must be trustworthy before higher-level orchestration depends on them.
• [Toolchain][Compatibility][P1] Enforce package-declared CellScript compiler requirements #18 alongside them: compiler compatibility should fail during resolution, not parsing/lowering.

Tooling foundation

• [Toolchain][Introspection] Expose a stable package resolve graph and build-unit plan #19: one stable graph/build-plan schema should become the shared input for workspace scheduling, IDEs, CI policy, security audits, cache explanation, and upgrades.

Delivery and ecosystem

• [Toolchain][Upgrade] Add a transactional package, interface, and deployment upgrade plan #20: transactional upgrade planning.
• [Architecture][Builder] Add an artifact-only multi-Script ProtocolBundle #9: artifact-only ProtocolBundle.
• [Language design] Model typed cross-Script transaction roles without runtime linkage #10/[Language/ABI] Bind runtime Script values to verified package interfaces #11: closed roles and exact handles before any open implementation model.
• [Candidate][Consensus runtime] Implement executable bounded Cell-group consumption #7/[Candidate][Consensus runtime] Implement executable bounded output-plan correspondence #8 remain the highest-risk admitted consensus-semantic gap, but positive implementation is a candidate until the evidence review accepts it.
• [Language/stdlib] Add typed CKB temporal and Since domains #12 is edition-aware type safety.
• [Language design] Add explicit typed openings for digest-committed substate #13 remains use-case-driven research.

Capability ledger structure

The audit suggests three linked but non-overlapping ledgers:

1. Executable surface: syntax/IR shapes and whether their machine semantics are complete, bounded, shape-gated, or fail-closed.
2. Toolchain/product capability: package, workspace, build, update, bundle, IDE, deployment, and evidence workflows, including absent/research states.
3. Ecosystem evidence: examples, adapters, Registry profiles, CKB-VM/stateful/chain fixtures, external integrations, and maintained docs.

Each entry should carry:

• stable capability ID and schema version;
• owning universe/ledger;
• status and exact supported shape;
• threat model and trust boundary;
• dependencies and blockers;
• source/IR/artifact/builder/on-chain evidence status as applicable;
• owner, RFC, reviewer, and acceptance gate;
• release eligibility;
• explicit non-goals;
• last verified commit and evidence links.

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:

Bounded lifecycle execution (#7/#8) is the highest-risk consensus-semantic gap already admitted into CellScript syntax and IR, but it is not an authorized 0.26/P0 commitment before Evidence Review. Separate capability gaps remain in multi-artifact protocol composition, typed cross-Script relationships, temporal/commitment types, and the package/workspace/update toolchain.

This preserves the value of the executable-surface registry without turning it into a claim about the whole product space.

Primary code references

Cargo:

• resolve/build pipeline: https://github.com/rust-lang/cargo/blob/75d17360928f57ff2a7d2f2da1c753f5fe1926d1/src/ops/cargo_compile/mod.rs#L1-L37
• metadata resolve graph: https://github.com/rust-lang/cargo/blob/75d17360928f57ff2a7d2f2da1c753f5fe1926d1/src/ops/cargo_metadata.rs#L15-L100
• unit graph: https://github.com/rust-lang/cargo/blob/75d17360928f57ff2a7d2f2da1c753f5fe1926d1/src/compiler/unit_graph.rs#L13-L150
• unit fingerprints: https://github.com/rust-lang/cargo/blob/75d17360928f57ff2a7d2f2da1c753f5fe1926d1/src/compiler/fingerprint/mod.rs#L620-L688

Move/Sui:

• package DAG: https://github.com/MystenLabs/sui/blob/5a9f37431c473fa2f6d49abecbcc6a6d7190f533/external-crates/move/crates/move-package-alt/src/graph/mod.rs#L40-L75
• environment mapping: https://github.com/MystenLabs/sui/blob/5a9f37431c473fa2f6d49abecbcc6a6d7190f533/external-crates/move/crates/move-package-alt/src/schema/lockfile.rs#L35-L63
• upgrade authorization: https://github.com/MystenLabs/sui/blob/5a9f37431c473fa2f6d49abecbcc6a6d7190f533/crates/sui-framework/packages/sui-framework/sources/package.move#L251-L315
• upgrade compatibility: https://github.com/MystenLabs/sui/blob/5a9f37431c473fa2f6d49abecbcc6a6d7190f533/sui-execution/latest/sui-adapter/src/static_programmable_transactions/execution/context.rs#L2489-L2563

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.