Split canonical and acceptance examples

Author: a19q3

CHANGELOG.md

@@ -17,6 +17,9 @@
 - Add lock-boundary surface syntax for `protected` Cell parameters, `witness`
   data parameters, and `require` fail-closed predicates; reserve `lock_args`
   until explicit CKB script-args binding is implemented.
+- Split bundled examples into clean business examples and profiled acceptance
+  examples, so scheduler/effect hints stay in release evidence without
+  crowding the canonical teaching surface.
 - Refresh LSP completions and the VS Code grammar/snippets for the new
   lock-boundary syntax.
 

docs/CELLSCRIPT_0_13_RELEASE_NOTES_DRAFT.md

@@ -33,6 +33,13 @@ New in 0.13 branch work:
   `Vec<Hash>` helper usage without implying full `HashMap<K, V>` support. It is
   a compiler/tooling language example, not part of the seven-example CKB
   production action acceptance matrix.
+- The canonical business examples are now mirrored under `examples/business/`,
+  while production/profile metadata lives under `examples/acceptance/`. The CKB
+  acceptance script compiles the profiled copies when present, keeping
+  `#[effect(...)]` and `#[scheduler_hint(...)]` out of beginner-facing files
+  without dropping release evidence. Subdirectory copies use scoped module
+  namespaces so they can coexist with the canonical top-level examples during
+  module loading.
 - Runtime and constraints metadata expose each checked stack-backed
   fixed-width `Vec<T>` instantiation, including scope, element type/width,
   backing capacity, status, and helper set. Constructor helpers now preserve

docs/CELLSCRIPT_0_13_TODOLIST.md

@@ -171,6 +171,10 @@ Notes:
   - [x] builder-backed on-chain lock valid-spend and invalid-spend matrix for
     all bundled production locks. The matrix is now part of the CKB production
     acceptance report instead of a compile-only claim.
+  - [x] split examples by audience: clean canonical business examples live in
+    `examples/business` and flat `examples/*.cell`; profiled production
+    acceptance copies live in `examples/acceptance`; `registry.cell` is mirrored
+    under `examples/language`.
 
 ---
 

docs/CELLSCRIPT_SURFACE_ELEGANCE_RFC.md

@@ -389,13 +389,22 @@ examples/language/
   bounded_vec.cell
 
 examples/acceptance/
-  token.acceptance.cell
-  timelock.acceptance.cell
-  multisig.acceptance.cell
+  token.cell
+  amm_pool.cell
+  launch.cell
+  vesting.cell
+  nft.cell
+  multisig.cell
+  timelock.cell
 ```
 
-The current flat `examples/` directory may remain until tooling and acceptance
-scripts are ready for the split.
+The flat `examples/*.cell` files remain as compatibility mirrors of the
+canonical business examples. CKB production acceptance compiles
+`examples/acceptance/*.cell` when that directory is present, so scheduler and
+effect-profile metadata can stay out of beginner-facing business files.
+Subdirectory copies use scoped module namespaces (`cellscript::business::*`,
+`cellscript::acceptance::*`, and `cellscript::language::*`) so they can coexist
+with the canonical top-level modules during compiler module loading.
 
 ## Canonical Style Example
 
@@ -445,7 +454,7 @@ This list is the living implementation tracker for the RFC.
 | `protects T { self ... }` sugar | Deferred | Wait until `self` binding and lock-group aggregation semantics are exact. |
 | Hidden sighash defaults | Rejected | Digest mode and signature scope must be visible. |
 | Implicit `Address` as signer | Rejected | Address values do not become authorization proofs by name. |
-| Business/language/acceptance example directory split | Deferred | Keep flat `examples/` until scripts and package tooling are ready. |
+| Business/language/acceptance example directory split | Done | `examples/business` holds clean canonical examples, `examples/acceptance` holds production/profiled examples, and `examples/language` holds `registry.cell`. Flat `examples/*.cell` remains a compatibility mirror for existing commands. |
 | `examples/canonical_style.cell` | Not started | Should become the idiomatic reference once pending syntax is available. |
 | Action production acceptance | Done | Existing bundled action acceptance remains builder-backed. |
 | Lock valid-spend and invalid-spend matrix | Done | Existing bundled locks are exercised through builder-backed local CKB transactions. |

docs/wiki/Tutorial-06-Metadata-Verification-and-Production-Gates.md

@@ -143,6 +143,10 @@ valid-spend and invalid-spend matrices, valid transaction dry-runs, committed
 valid transactions, malformed rejection, measured cycles, consensus-serialized tx
 size, occupied-capacity evidence, no under-capacity outputs, all seven production
 bundled examples deployed, and a passed final production hardening gate.
+The production gate compiles `examples/acceptance/*.cell` when present; those
+files intentionally retain scheduler and effect-profile metadata while
+`examples/*.cell` and `examples/business/*.cell` remain the cleaner business
+reading surface.
 Lock behavior coverage is machine-readable through
 `lock_acceptance_scope.onchain_lock_spend_matrix_scope`; each listed lock must
 have both valid-spend and invalid-spend evidence.

docs/wiki/Tutorial-08-Bundled-Example-Contracts.md

@@ -19,6 +19,14 @@ CellScript language surface and the current production gates.
 | `examples/amm_pool.cell` | Shared pool state, swap, and liquidity effects. |
 | `examples/launch.cell` | Launch/pool composition patterns. |
 
+The top-level `examples/*.cell` files are the canonical business reading
+surface. `examples/business/*.cell` mirrors that clean surface explicitly.
+`examples/acceptance/*.cell` carries production/profile metadata such as
+`#[effect(...)]` and `#[scheduler_hint(...)]`; the CKB acceptance script uses
+those profiled copies when generating release evidence. Subdirectory copies use
+`cellscript::business::*` and `cellscript::acceptance::*` module namespaces so
+they can coexist with the top-level examples during module loading.
+
 `examples/registry.cell` is intentionally outside this seven-example production
 matrix. It is a 0.13 bounded-collection language example for local
 `Vec<Address>` and `Vec<Hash>` helpers, covered by compiler/tooling tests rather

examples/acceptance/amm_pool.cell

@@ -0,0 +1,157 @@
+// amm_pool.cell - Constant Product AMM Liquidity Pool
+
+module cellscript::acceptance::amm_pool
+
+use cellscript::fungible_token::Token
+
+/// LP (Liquidity Provider) receipt
+receipt LPReceipt has store {
+    pool_id: Hash
+    lp_amount: u64
+    provider: Address
+}
+
+shared Pool has store {
+    token_a_symbol: [u8; 8]
+    token_b_symbol: [u8; 8]
+    reserve_a: u64
+    reserve_b: u64
+    total_lp: u64
+    fee_rate_bps: u16
+}
+
+action seed_pool(
+    token_a: Token,
+    token_b: Token,
+    fee_rate_bps: u16,
+    provider: Address
+) -> (Pool, LPReceipt) {
+    assert_invariant(token_a.symbol != token_b.symbol, "same token")
+    assert_invariant(token_a.amount > 0 && token_b.amount > 0, "zero liquidity")
+    assert_invariant(fee_rate_bps <= 10000, "fee too high")
+    
+    let initial_lp = isqrt(token_a.amount * token_b.amount)
+    
+    consume token_a
+    consume token_b
+
+    let pool = create Pool {
+        token_a_symbol: token_a.symbol,
+        token_b_symbol: token_b.symbol,
+        reserve_a: token_a.amount,
+        reserve_b: token_b.amount,
+        total_lp: initial_lp,
+        fee_rate_bps
+    }
+
+    let receipt = create LPReceipt {
+        pool_id: pool.type_hash(),
+        lp_amount: initial_lp,
+        provider
+    } with_lock(provider)
+
+    (pool, receipt)
+}
+
+action swap_a_for_b(
+    pool: &mut Pool,
+    input: Token,
+    min_output: u64,
+    to: Address
+) -> Token {
+    assert_invariant(input.symbol == pool.token_a_symbol, "wrong input token")
+    
+    let fee = input.amount * pool.fee_rate_bps as u64 / 10000
+    let net_input = input.amount - fee
+    
+    let output = pool.reserve_b * net_input / (pool.reserve_a + net_input)
+    
+    assert_invariant(output >= min_output, "slippage exceeded")
+    assert_invariant(output < pool.reserve_b, "insufficient reserves")
+    
+    consume input
+    
+    pool.reserve_a = pool.reserve_a + input.amount
+    pool.reserve_b = pool.reserve_b - output
+
+    create Token {
+        amount: output,
+        symbol: pool.token_b_symbol
+    } with_lock(to)
+}
+
+action add_liquidity(
+    pool: &mut Pool,
+    token_a: Token,
+    token_b: Token,
+    provider: Address
+) -> LPReceipt {
+    assert_invariant(token_a.symbol == pool.token_a_symbol, "wrong token a")
+    assert_invariant(token_b.symbol == pool.token_b_symbol, "wrong token b")
+    
+    let lp_from_a = token_a.amount * pool.total_lp / pool.reserve_a
+    let lp_from_b = token_b.amount * pool.total_lp / pool.reserve_b
+    let lp_amount = min(lp_from_a, lp_from_b)
+    
+    consume token_a
+    consume token_b
+    
+    pool.reserve_a = pool.reserve_a + token_a.amount
+    pool.reserve_b = pool.reserve_b + token_b.amount
+    pool.total_lp = pool.total_lp + lp_amount
+
+    create LPReceipt {
+        pool_id: pool.type_hash(),
+        lp_amount,
+        provider
+    } with_lock(provider)
+}
+
+action remove_liquidity(
+    pool: &mut Pool,
+    receipt: LPReceipt,
+    provider: Address
+) -> (Token, Token) {
+    assert_invariant(receipt.pool_id == pool.type_hash(), "wrong pool")
+    
+    let amount_a = receipt.lp_amount * pool.reserve_a / pool.total_lp
+    let amount_b = receipt.lp_amount * pool.reserve_b / pool.total_lp
+    
+    consume receipt
+    
+    pool.reserve_a = pool.reserve_a - amount_a
+    pool.reserve_b = pool.reserve_b - amount_b
+    pool.total_lp = pool.total_lp - receipt.lp_amount
+
+    let token_a = create Token {
+        amount: amount_a,
+        symbol: pool.token_a_symbol
+    } with_lock(provider)
+
+    let token_b = create Token {
+        amount: amount_b,
+        symbol: pool.token_b_symbol
+    } with_lock(provider)
+
+    (token_a, token_b)
+}
+
+action isqrt(n: u64) -> u64 {
+    if n == 0 {
+        return 0
+    }
+    
+    let mut x = n
+    let mut y = (x + 1) / 2
+    
+    while y < x {
+        x = y
+        y = (x + n / x) / 2
+    }
+    
+    x
+}
+
+action min(a: u64, b: u64) -> u64 {
+    if a < b { a } else { b }
+}

examples/acceptance/launch.cell

@@ -0,0 +1,106 @@
+// launch.cell - Token Launch and Pool Seeding
+
+module cellscript::acceptance::launch
+
+use cellscript::fungible_token::{Token, MintAuthority}
+use cellscript::amm_pool::{Pool, LPReceipt, seed_pool}
+
+/// Launch a new token and seed liquidity pool
+action launch_token(
+    symbol: [u8; 8],
+    max_supply: u64,
+    initial_mint: u64,
+    pool_seed_amount: u64,
+    pool_paired_token: Token,
+    fee_rate_bps: u16,
+    creator: Address,
+    distribution: [(Address, u64); 4]
+) -> (MintAuthority, Pool, LPReceipt) {
+    assert_invariant(initial_mint <= max_supply, "initial exceeds max")
+    assert_invariant(pool_seed_amount <= initial_mint, "pool seed exceeds mint")
+    
+    // Calculate distribution total
+    let dist_total = distribution[0].1 + distribution[1].1 
+                   + distribution[2].1 + distribution[3].1
+    assert_invariant(dist_total + pool_seed_amount <= initial_mint,
+        "allocation exceeds mint")
+
+    // Create mint authority
+    let auth = create MintAuthority {
+        token_symbol: symbol,
+        max_supply,
+        minted: initial_mint
+    } with_lock(creator)
+
+    // Create distribution tokens
+    for (addr, amount) in distribution {
+        if amount > 0 {
+            create Token {
+                amount,
+                symbol
+            } with_lock(addr)
+        }
+    }
+
+    // Create pool seed token
+    let pool_token = create Token {
+        amount: pool_seed_amount,
+        symbol
+    } with_lock(creator)
+
+    // Call pool pattern helper to seed the pool
+    let (pool, lp_receipt) = seed_pool(
+        pool_token,
+        pool_paired_token,
+        fee_rate_bps,
+        creator
+    )
+
+    (auth, pool, lp_receipt)
+}
+
+/// Simple token launch (without liquidity pool)
+action simple_launch(
+    symbol: [u8; 8],
+    max_supply: u64,
+    initial_mint: u64,
+    creator: Address,
+    recipients: [(Address, u64); 8]
+) -> MintAuthority {
+    assert_invariant(initial_mint <= max_supply, "initial exceeds max")
+    
+    // Calculate distribution total
+    let mut total_distributed: u64 = 0
+    for (_, amount) in recipients {
+        total_distributed = total_distributed + amount
+    }
+    assert_invariant(total_distributed <= initial_mint, "distribution exceeds mint")
+
+    // Create mint authority
+    let auth = create MintAuthority {
+        token_symbol: symbol,
+        max_supply,
+        minted: initial_mint
+    } with_lock(creator)
+
+    // Distribute tokens
+    for (addr, amount) in recipients {
+        if amount > 0 {
+            create Token {
+                amount,
+                symbol
+            } with_lock(addr)
+        }
+    }
+
+    // Remaining tokens go to creator
+    let remaining = initial_mint - total_distributed
+    if remaining > 0 {
+        create Token {
+            amount: remaining,
+            symbol
+        } with_lock(creator)
+    }
+
+    auth
+}