Skip to content

Commit 3cefa86

Browse files
committed
consolidate(codegen): update docs and boundary rules for schema extraction
Update module header in mod.rs from five to six files with schema.rs description and explicit exclusion of cell operation policy. Replace legacy monolith description in CODING_STYLE.md with current multi-file backend structure. Add module boundary rule: schema.rs owns layout computation and field access, must not absorb cell operation policy or state-transition verification.
1 parent 2861ef7 commit 3cefa86

4 files changed

Lines changed: 388 additions & 434 deletions

File tree

‎CODING_STYLE.md‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,13 @@ project contract.
2323

2424
## Backend And Codegen Rules
2525

26-
`src/codegen/mod.rs` is currently a legacy monolith covering layout planning,
27-
CKB syscall lowering, verifier pattern emission, RISC-V assembly generation, the
28-
internal ELF assembler, and backend-shape tests. New code should reduce coupling
29-
where practical and must not make the implicit backend contracts more implicit.
26+
`src/codegen/mod.rs` is the orchestration layer of a multi-file backend.
27+
Sub-modules handle separate concerns: `schema.rs` (layout data model and
28+
type-width helpers), `assembler.rs` (RISC-V machine code and ELF),
29+
`runtime.rs` (helper functions and CKB syscall wrappers), `abi.rs` (calling
30+
convention and entry witness envelope), and `collections.rs` (collection
31+
lowering). New code should respect these boundaries and must not make the
32+
implicit backend contracts more implicit.
3033

3134
- Treat emitted assembly as a compiler contract. Any new mnemonic or pseudo-op
3235
emitted by codegen, stdlib, or collection helpers must be supported by the
@@ -142,3 +145,22 @@ sub-module (e.g. `assembler.rs`, `runtime.rs`, `abi.rs`):
142145
5. **Brace-count after every deletion.** Use `python3 -c` to verify brace
143146
balance before attempting compilation. Off-by-one `sed` ranges can leave
144147
orphaned lines or eat closing braces.
148+
149+
### Module Boundary: Schema vs Cell Operations
150+
151+
`schema.rs` owns layout computation and field access helpers. It must **not**
152+
absorb cell operation policy or state-transition verification. Specifically:
153+
154+
- **Schema module may contain**: type-width helpers (`fixed_scalar_width`,
155+
`fixed_byte_width`, `type_static_length`, etc.), aggregate/tuple layout
156+
computation, Molecule table field bounds/span helpers, fixed-byte comparison
157+
and loading, prelude u64 value resolution, and field access dispatch.
158+
- **Schema module must not contain**: destruction policy, identity/field
159+
uniqueness checks, create-output field verification, state-transition edge
160+
matching, consume/destroy/replace/transfer/settle lowering, mutate
161+
replacement transition checks, or any code that decides *whether* a cell
162+
operation is valid.
163+
164+
If a helper is shared by schema access code and cell operation code, it should
165+
stay in `mod.rs` until the cell operations module is extracted. Cross-module
166+
call dependencies are acceptable; semantic ownership boundaries are not.

0 commit comments

Comments
 (0)