Add runnable 0.24 workflow examples

Author: a19q3

CHANGELOG.md

@@ -16,7 +16,9 @@
   scattered Registry artifact-profile conditionals with the versioned,
   fail-closed `cellscript-registry-profile-catalog-v1`; only CellScript source
   profiles are dependency-resolving, while executable, reproducible, and copy
-  profiles remain explicit non-resolving artifacts.
+  profiles remain explicit non-resolving artifacts. Add a portable
+  `examples/package_graph` fixture that executes alias, SemVer, feature,
+  test-only, environment, and override selection from the frozen graph.
 - Implement the 0.24 trust-closure core. CKB ELF builds now emit canonical
   `cellscript-verified-lowering-record-v1` and
   `cellscript-source-artifact-map-v1` sidecars, bound by metadata schema 58 and
@@ -37,6 +39,8 @@
   whose production graph excludes the compiler. Freeze the CellScript side of
   the Myelin handoff without a new profile or raw-witness alias; keep external
   Myelin adoption and the incomplete Fiber/RGB++ matrices explicitly pending.
+  Add `examples/scenario_basics` as the runnable positive/exact-negative
+  scenario and four-file verified-artifact walkthrough.
 - Freeze the 0.23 implementation scope around Edition 2026 and its resolved
   profile/entry identities, the deployed Registry and publisher-session path,
   native gate tooling, the recoverable website workbench, and the bounded Fiber

README.md

@@ -805,9 +805,14 @@ Non-CellScript artifact profiles still fail closed.
 - `[resolvers.<name>]` — optional absolute-path/SHA-256-bound, time/output
   bounded update-time resolver; its versioned response must normalize to an
   exact Registry version or Git commit and is never executed by locked builds
+- `examples/package_graph` — runnable frozen/offline alias, SemVer, feature,
+  test-only dependency, and explicit CKB-environment graph
+- `examples/scenario_basics` — runnable positive and exact-negative scenarios
+  under both simulator and CKB-VM, plus a four-file artifact walkthrough
 - `cellc info --json` — exposes package metadata for CI and tooling
 - `cellc package verify --json` — fails closed when `Cell.toml`, source hash,
-  dependency resolution, or build identity disagree with `Cell.lock`
+  dependency resolution, or build identity disagree with `Cell.lock`; run an
+  ordinary locked build first when a tracked example lock is graph-only
 - `cellc registry verify --json` — checks off-chain deployment facts against
   `Cell.lock` and `Deployed.toml`
 - `cellc registry verify --live --rpc-url ... --json` — adds CKB RPC

docs/releases/CELLSCRIPT_0_24_RELEASE_NOTES.md

@@ -72,6 +72,10 @@ authoritative runtime evidence, not chain evidence. The v1 CKB-VM runner
 supports no-argument entries; transaction-syscall cases remain with the
 stateful CKB oracle.
 
+`examples/scenario_basics` is the checked-in runnable form of this contract. It
+executes positive and exact-negative fixtures under both backends and provides
+a concrete four-file bundle/checker walkthrough.
+
 Native `cellc run` now includes the VM runner by default. It executes only a
 no-argument standalone ELF and fails closed for parameter or transaction/
 syscall context. Development interpretation requires explicit `--simulate`;
@@ -163,6 +167,13 @@ must pass `--environment <name>` when overrides exist. This adapts Move's named
 environment idea to CKB's genesis-bound Cell Model rather than copying Sui
 addresses or published package IDs.
 
+`examples/package_graph` is the portable runnable form of these package
+features. Its checked-in graph covers a declared-package alias, standard SemVer
+requirements, optional and transitive feature activation, a test-only
+dependency, two genesis-bound environments, and an exact testnet override.
+Frozen/offline commands prove that those selections are consumed from the lock
+without invoking mutable resolution.
+
 ### Bounded resolver extension, normalized before trust
 
 `[resolvers.<name>]` is a versioned extension point for package ecosystems that

docs/wiki/Tutorial-04-Packages-and-CLI-Workflow.md

@@ -310,6 +310,12 @@ cellc auth capability create --principal-id <principal_id> \
 cellc gen-builder . --target typescript --target-profile ckb --json
 ```
 
+`package verify` checks build identity as well as the dependency graph. A
+freshly cloned example intentionally carries a graph-only `Cell.lock`; run
+`cellc build --locked` first to populate `[package.build]`. A frozen build
+cannot add that local evidence because `--frozen` suppresses every lockfile
+write.
+
 Legacy flat aliases such as `solve-tx`, `deploy-plan`, and
 `explain-assumptions` remain executable for compatibility, but they are hidden
 from public discovery. Prefer `--json` where a command offers it, and reserve
@@ -418,6 +424,19 @@ namespace = "cellscript"
 When overrides exist, `--environment mainnet` is mandatory. The environment
 root in `Cell.lock` binds both `chain_id` and genesis hash.
 
+The portable checked-in example exercises these inputs together:
+
+```bash
+cd examples/package_graph
+cellc check --frozen --offline --environment mainnet
+cellc check --frozen --offline --environment testnet --features full
+cellc test --no-run --frozen --offline --environment testnet --all-features
+```
+
+Its local dependency alias is distinct from the declared package name, and its
+testnet override resolves a different exact version of the same declared
+package. Omitting `--environment` is an intentional fail-closed example.
+
 Advanced ecosystems may declare a hash-pinned bounded resolver. It runs only
 during explicit lock/update, without a shell or inherited environment, and
 must normalize its versioned JSON response to an exact Registry version or Git

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

@@ -45,19 +45,34 @@ There are no checked-in `examples/business` or `examples/acceptance` mirrors;
 acceptance-only profile/effect/scheduler metadata belongs in runner
 configuration or generated files under `target/`.
 
+Two 0.24 workflow packages sit beside, but are not part of, the business
+matrix:
+
+- `examples/scenario_basics` runs one positive and one exact-negative scenario
+  through both the simulator and CKB-VM, and builds a four-file verified
+  artifact bundle;
+- `examples/package_graph` demonstrates standard SemVer, a package alias,
+  optional and transitive features, a test-only dependency, explicit CKB
+  environments, a testnet dependency override, and frozen/offline consumption
+  of the tracked graph.
+
+These packages are deliberately small and synthetic. They teach tooling
+boundaries without implying that simulator bookkeeping or illustrative chain
+identities are production evidence.
+
 Despite its legacy filename, `multisig.cell` is not a signature verifier or a
 standalone custody Lock Script. Its `Approval` values and `reported_time`
 arguments are witness data. A surrounding Lock Script must authenticate the
 approver, and any production time policy must bind a HeaderDep-derived value.
-CellScript 0.22 has no implicit signer identity, sighash selection, or witness
-layout. Packages that need cryptographic custody may call the explicit BIP340
-CellDep verifier ABI, but the bundled threshold-approval example deliberately
-does not do so.
+Since CellScript 0.22 there has been no implicit signer identity, sighash
+selection, or witness layout. Packages that need cryptographic custody may call
+the explicit BIP340 CellDep verifier ABI, but the bundled threshold-approval
+example deliberately does not do so.
 
 ## Fiber Interoperability Examples
 
-CellScript 0.22 also includes seven bounded interoperability examples under
-`examples/fiber/`. They are not additional members of the bundled CKB
+The CellScript 0.22 line introduced seven bounded interoperability examples
+under `examples/fiber/`. They are not additional members of the bundled CKB
 production matrix:
 
 | Example | Interoperability boundary |
@@ -137,6 +152,17 @@ cellc build --package amm_pool --target riscv64-elf --target-profile ckb --json
 cellc build --package launch --target riscv64-elf --target-profile ckb --json
 ```
 
+For the 0.24 workflow examples, follow their tracked locks without repinning:
+
+```bash
+cd examples/scenario_basics
+cellc test --frozen --offline --backend all --json
+
+cd ../package_graph
+cellc check --frozen --offline --environment mainnet
+cellc check --frozen --offline --environment testnet --features full
+```
+
 Do not treat `cellc build --workspace` as the canonical compile-all command for
 this checked-in examples tree. Some folders under `examples/` are compiler and
 tooling fixtures rather than packages with a `src/main.cell` entry.

docs/wiki/Tutorial-14-Verified-Artifacts-and-Executable-Tests.md

@@ -7,10 +7,12 @@ without calling local execution chain evidence.
 
 ## Build the Four-File Bundle
 
-From an Edition 2026 package, build the CKB ELF:
+The checked-in `scenario_basics` package is the smallest complete example. From
+the repository root:
 
 ```bash
-cellc build --target riscv64-elf --target-profile ckb --json
+cd examples/scenario_basics
+cellc build --frozen --offline --json
 ```
 
 The build emits:
@@ -71,6 +73,12 @@ schema names the confined source file, CKB target profile, entry, initial live
 Cells, ordered replacement steps, dependencies, headers, `since`, witnesses,
 limits, and an exact expectation.
 
+See `examples/scenario_basics/tests/pass.scenario.json` and
+`assertion-failure.scenario.json` for runnable positive and exact-negative
+fixtures. Scenario sources intentionally stay in the same `tests/` directory:
+v1 rejects absolute paths and parent traversal instead of letting a fixture
+escape its evidence root.
+
 A minimal positive shape is:
 
 ```json
@@ -109,9 +117,9 @@ and unsupported evidence requests fail before execution.
 ## Run Both Evidence Tiers
 
 ```bash
-cellc test --backend simulator
-cellc test --backend ckb-vm
-cellc test --backend all --json
+cellc test --backend simulator --frozen --offline
+cellc test --backend ckb-vm --frozen --offline
+cellc test --backend all --frozen --offline --json
 ```
 
 The simulator is deterministic development feedback and is labelled

examples/Cell.toml

@@ -11,4 +11,6 @@ members = [
     "token",
     "vesting",
     "language",
+    "package_graph",
+    "scenario_basics",
 ]

examples/package_graph/Cell.lock

@@ -0,0 +1,107 @@
+version = 3
+schema = "cellscript-lock-v0.24-graph-v1"
+
+[package]
+edition = "2026"
+name = "package_graph_demo"
+version = "0.1.0"
+source_hash = "5f146552641c097ec165eeb72cc368f3c2b4f762221417da3960960967ef26cd"
+
+[root]
+manifest_digest = "sha256:57f0f363771fc6ca67b678e3b9a676b1e1ee4021acfa25e0cf6eeb5a7f7edad2"
+
+[dependencies."audit_helpers@0.4.2|path:deps/audit-helpers|env=mainnet|features=default"]
+name = "audit_helpers"
+version = "0.4.2"
+source_hash = "44b8be2a00aaba5c51b296623598792a95caa48c8d0cbd5036936a92a68038b4"
+manifest_digest = "sha256:e24ef32ca50f1e257c7757d6c16d483a07c7e574236267947b16d2aa36cdc8fc"
+
+[dependencies."audit_helpers@0.4.2|path:deps/audit-helpers|env=mainnet|features=default".source.Path]
+path = "deps/audit-helpers"
+
+[dependencies."audit_helpers@0.4.2|path:deps/audit-helpers|env=testnet|features=default"]
+name = "audit_helpers"
+version = "0.4.2"
+source_hash = "44b8be2a00aaba5c51b296623598792a95caa48c8d0cbd5036936a92a68038b4"
+manifest_digest = "sha256:e24ef32ca50f1e257c7757d6c16d483a07c7e574236267947b16d2aa36cdc8fc"
+
+[dependencies."audit_helpers@0.4.2|path:deps/audit-helpers|env=testnet|features=default".source.Path]
+path = "deps/audit-helpers"
+
+[dependencies."canonical_math@1.2.3|path:deps/canonical-math|env=mainnet|features=default"]
+name = "canonical_math"
+version = "1.2.3"
+source_hash = "fd053efe46302c263148061ecd62e798100d31c38b2308285097462f70331864"
+manifest_digest = "sha256:bcb871cd37a39cf52b5b30b3b23c43ada0b90f0c68476b1218a08a0dd223b5ea"
+
+[dependencies."canonical_math@1.2.3|path:deps/canonical-math|env=mainnet|features=default".source.Path]
+path = "deps/canonical-math"
+
+[dependencies."canonical_math@1.2.3|path:deps/canonical-math|env=testnet|features=default"]
+name = "canonical_math"
+version = "1.2.3"
+source_hash = "fd053efe46302c263148061ecd62e798100d31c38b2308285097462f70331864"
+manifest_digest = "sha256:bcb871cd37a39cf52b5b30b3b23c43ada0b90f0c68476b1218a08a0dd223b5ea"
+
+[dependencies."canonical_math@1.2.3|path:deps/canonical-math|env=testnet|features=default".source.Path]
+path = "deps/canonical-math"
+
+[dependencies."network_contracts@1.0.0|path:deps/contracts-mainnet|env=mainnet|features=default"]
+name = "network_contracts"
+version = "1.0.0"
+source_hash = "509ab43e27f7e1cba59a079b92ed7d0e04128aab27de513817bb5225c71d7274"
+manifest_digest = "sha256:2e2fc06b5cf1f269e91356b8c39efc68f182e43592b6384df0629271dcfee6fe"
+
+[dependencies."network_contracts@1.0.0|path:deps/contracts-mainnet|env=mainnet|features=default".source.Path]
+path = "deps/contracts-mainnet"
+
+[dependencies."network_contracts@2.0.0|path:deps/contracts-testnet|env=testnet|features=default"]
+name = "network_contracts"
+version = "2.0.0"
+source_hash = "148e0ead158a5dfa4f84b6ec4b7c3d7783debe732d894dbf0157c0b8309e9539"
+manifest_digest = "sha256:b7269f73fc0802b76cd2dcc357d3927aca7d62c2194449082c02e5b083c5828c"
+
+[dependencies."network_contracts@2.0.0|path:deps/contracts-testnet|env=testnet|features=default".source.Path]
+path = "deps/contracts-testnet"
+
+[dependencies."scenario_test_support@0.1.0|path:deps/test-support|env=mainnet|features=default"]
+name = "scenario_test_support"
+version = "0.1.0"
+source_hash = "34956e5ec9750c7ba52b41b76396456f4f006952903579b1680863fa23f33d63"
+manifest_digest = "sha256:3d736afd4e06f265e1d00489321475a5b89b0c60bf040ed05814f21e7ec86c54"
+
+[dependencies."scenario_test_support@0.1.0|path:deps/test-support|env=mainnet|features=default".source.Path]
+path = "deps/test-support"
+
+[dependencies."scenario_test_support@0.1.0|path:deps/test-support|env=testnet|features=default"]
+name = "scenario_test_support"
+version = "0.1.0"
+source_hash = "34956e5ec9750c7ba52b41b76396456f4f006952903579b1680863fa23f33d63"
+manifest_digest = "sha256:3d736afd4e06f265e1d00489321475a5b89b0c60bf040ed05814f21e7ec86c54"
+
+[dependencies."scenario_test_support@0.1.0|path:deps/test-support|env=testnet|features=default".source.Path]
+path = "deps/test-support"
+
+[environments.mainnet]
+chain_id = "ckb-mainnet"
+genesis_hash = "0x1111111111111111111111111111111111111111111111111111111111111111"
+
+[environments.mainnet.dependencies]
+audit = "audit_helpers@0.4.2|path:deps/audit-helpers|env=mainnet|features=default"
+contracts = "network_contracts@1.0.0|path:deps/contracts-mainnet|env=mainnet|features=default"
+core = "canonical_math@1.2.3|path:deps/canonical-math|env=mainnet|features=default"
+
+[environments.mainnet.dev_dependencies]
+test_support = "scenario_test_support@0.1.0|path:deps/test-support|env=mainnet|features=default"
+
+[environments.testnet]
+chain_id = "ckb-testnet"
+genesis_hash = "0x2222222222222222222222222222222222222222222222222222222222222222"
+
+[environments.testnet.dependencies]
+audit = "audit_helpers@0.4.2|path:deps/audit-helpers|env=testnet|features=default"
+contracts = "network_contracts@2.0.0|path:deps/contracts-testnet|env=testnet|features=default"
+core = "canonical_math@1.2.3|path:deps/canonical-math|env=testnet|features=default"
+
+[environments.testnet.dev_dependencies]
+test_support = "scenario_test_support@0.1.0|path:deps/test-support|env=testnet|features=default"

examples/package_graph/Cell.toml

@@ -0,0 +1,47 @@
+[package]
+edition = "2026"
+name = "package_graph_demo"
+version = "0.1.0"
+
+[dependencies.core]
+package = "canonical_math"
+version = "^1.2.0"
+path = "deps/canonical-math"
+
+[dependencies.audit]
+package = "audit_helpers"
+version = "~0.4.0"
+path = "deps/audit-helpers"
+optional = true
+
+[dependencies.contracts]
+package = "network_contracts"
+version = ">=1.0.0, <3.0.0"
+path = "deps/contracts-mainnet"
+
+[dev_dependencies.test_support]
+package = "scenario_test_support"
+version = "=0.1.0"
+path = "deps/test-support"
+
+[features]
+default = []
+auditing = ["dep:audit"]
+full = ["auditing"]
+
+[environments.mainnet]
+chain_id = "ckb-mainnet"
+genesis_hash = "0x1111111111111111111111111111111111111111111111111111111111111111"
+
+[environments.testnet]
+chain_id = "ckb-testnet"
+genesis_hash = "0x2222222222222222222222222222222222222222222222222222222222222222"
+
+[dependency_overrides.testnet.contracts]
+package = "network_contracts"
+version = "=2.0.0"
+path = "deps/contracts-testnet"
+
+[build]
+target = "riscv64-elf"
+target_profile = "ckb"

examples/package_graph/README.md

@@ -0,0 +1,33 @@
+# Lock-Authoritative Package Graph
+
+This portable 0.24 example concentrates the package features that do not
+belong in the business-contract examples:
+
+- the local alias `core` resolves declared package `canonical_math` through a
+  standard `^1.2.0` SemVer requirement;
+- optional `audit_helpers` is activated through `dep:audit` and the transitive
+  `full` feature;
+- `scenario_test_support` enters only the test graph;
+- mainnet and testnet roots bind explicit CKB chain identities; and
+- the testnet environment replaces `network_contracts` with an exact `2.0.0`
+  path source.
+
+The tracked `Cell.lock` contains every feature, test, and environment root, so
+the following commands perform no mutable dependency selection:
+
+```bash
+cd examples/package_graph
+cellc check --frozen --offline --environment mainnet
+cellc check --frozen --offline --environment testnet --features auditing
+cellc test --no-run --frozen --offline --environment testnet --all-features
+```
+
+Omitting `--environment` fails closed because this manifest has an explicit
+environment override. Run `cellc lock` only when intentionally repinning the
+graph.
+
+Git and Registry requirements normalize to immutable commits or snapshots at
+repin time. They are not included here because a portable checked-in example
+must not depend on mutable network discovery. Hash-pinned external resolvers
+remain test/documentation fixtures because their commands must use
+machine-specific absolute paths.