Add verified LS-IDL registry workflow

Author: a19q3

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- Add first-class LS-IDL publication and discovery for CKB Lock Scripts.
+  `cellc artifact ls-idl` validates the bounded 0.1 schema, appends
+  `SHA-256(raw idl.json)` to an executable, generates a publish-ready bundle,
+  and fetches byte-exact IDL by deployed Script identity. Registry admission,
+  both verifier boundaries, immutable object storage, Postgres lookup,
+  canonical `/v1/ckb/scripts/:code_hash/interfaces/ls-idl` reads, and the
+  compatibility `/idl/:code_hash` route all enforce the same schema and
+  executable-suffix contract. Add curated compatibility vectors, a runnable
+  Rust example, website lookup/detail surfaces, and VS Code validate/bind/fetch
+  commands. Keep implementation correctness and security review outside this
+  byte-identity claim.
 - Ship the 0.24 package and Registry trust closure, informed by Sui Move's
   package-alt separation of resolution from compilation. Replace permissive
   custom version checks with standard SemVer; make `Cell.lock` v3 a

README.md

@@ -641,7 +641,7 @@ CKB cycle/capacity estimates.
 |---|---|---|
 | **CLI** | `cli/` + `main.rs` | `cellc` binary with all subcommands |
 | **LSP** | `lsp/` + `lsp/server.rs` | In-process `LspServer` + `tower-lsp` JSON-RPC over stdio (`cellc --lsp`) |
-| **VS Code** | `editors/vscode-cellscript/` | Shells out to `cellc` for LSP startup, reports, action-builder generation, and package/registry verification |
+| **VS Code** | `editors/vscode-cellscript/` | Shells out to `cellc` for LSP startup, reports, action-builder generation, package/registry verification, and LS-IDL validate/bind/fetch flows |
 | **MCP server** | `cellscript-mcp` (separate bin) | Read-only Model Context Protocol JSON-RPC server that exposes compiler reports and explain commands to MCP-aware agents (Claude Code, Cursor, Aider, Codex, etc.) |
 | **Formatter** | `fmt/` | Idempotent formatter for `cellc fmt` and LSP |
 | **Doc generator** | `docgen/` | HTML/Markdown/JSON docs from AST + metadata |
@@ -809,6 +809,8 @@ Non-CellScript artifact profiles still fail closed.
   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
+- `examples/registry_ls_idl` — runnable LS-IDL validation, executable binding,
+  Registry bundle scaffolding, exact-byte fetch, and compatibility vectors
 - `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`; run an
@@ -899,6 +901,13 @@ the manual, CI, recovery, and external-wallet path.
   `cellscript_source` dependency-resolving; non-CellScript artifact profiles
   remain discoverable through explicit artifact commands and fail closed in
   package resolution
+- Deployable CKB Lock Scripts may attach the versioned
+  `cellscript-registry-ls-idl-interface-v1` profile. Registry admission binds
+  `SHA-256` of the exact IDL bytes to the executable's final 32 bytes, and
+  public reads resolve those bytes by chain-verified Script identity. This is
+  an interface-identity check, not proof of implementation correctness or a
+  security audit. See the
+  [LS-IDL Registry profile](docs/CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md).
 - Git dependencies are explicit remote source fetches; treat them as
   review-required inputs, not the registry production path
 
@@ -951,6 +960,7 @@ the manual, CI, recovery, and external-wallet path.
 | `cellc opt-report` | Compare O0..O3 artifact size and constraints status |
 | `cellc receipt` / `sign-receipt` / `verify-receipt` | Emit, sign, and verify compile receipts over metadata/artifact hashes |
 | `cellc verify-artifact` | Independently check an ELF, metadata, lowering record, and source map; report VM/chain evidence separately; optionally bind a receipt |
+| `cellc artifact ls-idl validate\|bind\|fetch\|bundle` | Validate byte-exact LS-IDL, bind its SHA-256 to a CKB executable, resolve it by deployed Script identity, or scaffold a publish-ready Registry bundle |
 | `cellc test --backend simulator\|ckb-vm\|all` | Execute fail-closed package scenarios with exact outcomes and evidence tiers (`--no-run` is compile-only) |
 | `cellc doc` | Generate API and audit documentation |
 | `cellc fmt` | Format `.cell` sources or check formatting |

docs/CELLSCRIPT_GATE_POLICY.md

@@ -38,6 +38,14 @@ running during locked builds. Registry API checks also validate the complete
 `cellscript-registry-profile-catalog-v1` and prove that only CellScript source
 profiles are dependency-resolving.
 
+The same Registry matrix covers
+`cellscript-registry-ls-idl-interface-v1`: raw ABI schema and size budgets,
+SHA-256 binding, executable suffix placement, publish-time rejection cases,
+SQL/in-memory Script lookup, byte-preserving canonical and compatibility
+responses, ambiguous type-hash rejection, CLI validate/bind/fetch/bundle, and
+both compiler-backed and least-privilege verifier outputs. Passing this matrix
+does not assert that a Lock Script semantically implements its IDL.
+
 `dev` and `ci` run `cellc fmt --check` against
 `examples/language/canonical_style.cell`. The formatter's comma-terminated
 field form is the canonical checked-in surface; the parser may continue to

docs/CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md

@@ -0,0 +1,220 @@
+# LS-IDL Registry Profile
+
+**Status**: CellScript 0.24 protocol and tooling contract
+
+**Profile schema**: `cellscript-registry-ls-idl-interface-v1`
+
+**LS-IDL format version**: `0.1`
+
+This profile lets the CellScript Artifact Registry publish and resolve an
+LS-IDL witness interface for a deployed CKB Lock Script. It preserves the
+upstream commitment rule exactly:
+
+```text
+code Cell data = executable bytes || SHA-256(raw idl.json bytes)
+```
+
+The Registry stores the original IDL object bytes in the immutable release
+bundle. It never parses and reserialises those bytes on the read path.
+
+## What The Profile Proves
+
+An accepted profile proves all of the following:
+
+- the ABI object is valid JSON within the Registry's size and field budgets;
+- the document uses the supported LS-IDL 0.1 schema and witness types;
+- the declared digest equals `SHA-256` of the exact ABI object bytes;
+- the executable object's final 32 bytes equal that digest;
+- the package is a deployable `ckb_executable` with `script_role = "lock"`;
+- a lookup result belongs to an active, public, chain-verified deployment on
+  the requested Registry network.
+
+It does **not** prove that the Lock Script decodes witness data as described,
+that every described field is semantically enforced, that a transaction is
+valid, or that the Script is secure. Build verification and security review
+remain separate evidence.
+
+## Artifact Profile Contract
+
+`profile_contract.interface` is accepted only on deployable CKB executables:
+
+```json
+{
+  "schema": "cellscript-registry-ls-idl-interface-v1",
+  "format": "ls-idl",
+  "format_version": "0.1",
+  "object_role": "abi",
+  "content_type": "application/vnd.ckb.ls-idl+json",
+  "encoding": "linear-le-v0",
+  "commitment": {
+    "algorithm": "sha256",
+    "placement": "code-cell-data-suffix-32",
+    "digest": "<64 lowercase hexadecimal characters>"
+  }
+}
+```
+
+Unknown keys, alternate algorithms, alternate commitment placements, missing
+ABI objects, digest mismatches, and executable-suffix mismatches fail closed.
+The artifact bundle continues to use CKB Blake2b-256 for its executable
+`artifact_hash`; LS-IDL's ABI commitment remains SHA-256. These hashes have
+different roles and are not interchangeable.
+
+## Accepted IDL Document
+
+The document may contain only these top-level fields:
+
+- `idl_version` (optional string, matching upstream clients that default it);
+- `name` (optional string, matching derive output that may omit it);
+- `witness` (required array, at most 256 fields);
+- `description` (optional string);
+- `script_version` (optional string); and
+- `signing` (optional object with non-empty string fields `algorithm`,
+  `message`, and `hasher`).
+
+Each witness field contains only `name`, `type`, `required`, and
+`description`. Names must be unique. The supported types are:
+
+| Type | Encoding |
+| --- | --- |
+| `uint8` | one unsigned byte |
+| `uint32` | four-byte little-endian unsigned integer |
+| `uint64` | eight-byte little-endian unsigned integer |
+| `secp256k1_sig` | 65 bytes |
+| `secp256k1_pubkey` | 33 bytes |
+| `schnorr_sig` | 64 bytes |
+| `bytes` | four-byte little-endian length followed by that many bytes |
+
+The current linear decoder treats `required` as interface metadata. It does
+not introduce a presence bitmap or conditional field skipping, so consumers
+must not interpret `required: false` as a wire-level omission rule.
+
+## Public Read API
+
+The canonical lookup is:
+
+```text
+GET /v1/ckb/scripts/:code_hash/interfaces/ls-idl
+    ?network=mainnet|testnet
+    &hash_type=data|data1|data2|type
+    [&data_hash=0x...]
+```
+
+`data_hash` is mandatory for `hash_type=type`, where a type hash alone may not
+uniquely identify executable data. More than one matching deployment returns
+`409` instead of choosing arbitrarily.
+
+The compatibility route is:
+
+```text
+GET /idl/:code_hash
+```
+
+It is retained for existing LS-IDL clients and returns the same original
+bytes. New integrations should use the canonical route so network, hash type,
+and data-hash identity are explicit.
+
+Successful responses use
+`application/vnd.ckb.ls-idl+json` and expose:
+
+- `ETag`;
+- `x-ls-idl-format-version`;
+- `x-ls-idl-sha256`;
+- `x-ls-idl-coordinate`;
+- `x-ls-idl-commitment`; and
+- `x-ls-idl-verification`.
+
+Clients must hash the response body directly. JSON-equivalent reformatting is
+not byte-equivalent and therefore does not preserve the commitment.
+
+## CLI Workflow
+
+Validate a document and optionally its existing executable binding:
+
+```bash
+cellc artifact ls-idl validate --idl idl.json
+cellc artifact ls-idl validate --idl idl.json --executable lock
+```
+
+Append the raw-byte digest to an executable without silently overwriting it:
+
+```bash
+cellc artifact ls-idl bind \
+  --idl idl.json \
+  --executable lock \
+  --output lock.ls-idl
+```
+
+Generate a publish-ready artifact bundle and manifest:
+
+```bash
+cellc artifact ls-idl bundle \
+  --idl idl.json \
+  --executable lock.ls-idl \
+  --source lock.rs \
+  --namespace example \
+  --name example-lock \
+  --release 0.1.0 \
+  --language rust \
+  --hash-type data1 \
+  --dep-type code \
+  --toolchain rust-1.97.1 \
+  --source-revision <40-hex-git-commit> \
+  --output artifact.bundle.json \
+  --artifact-manifest-output Artifact.toml
+cellc publish --artifact-manifest Artifact.toml --dry-run --json
+```
+
+Fetch exact bytes by deployed Script identity:
+
+```bash
+cellc artifact ls-idl fetch \
+  --code-hash 0x<64-hex> \
+  --hash-type data1 \
+  --network mainnet \
+  --output idl.json
+```
+
+The VS Code extension exposes the validate, bind, and fetch operations through
+the command palette. The Registry website exposes both package-bound interface
+facts and a direct Script-identity lookup.
+
+## Storage And Admission
+
+Migration `0010_ls_idl_interfaces.sql` adds a partial lookup index over public,
+chain-verified deployed evidence. The API narrows candidates in the database,
+then rechecks release identity, immutable bundle identity, one-and-only-one ABI
+object, raw-byte digest, and profile contract before returning bytes.
+
+The normal compiler-backed Registry worker and the least-privilege
+artifact-only verifier both enforce the same profile. The latter has no
+CellScript compiler dependency. A publish that merely labels arbitrary JSON as
+LS-IDL, supplies a detached digest, or binds a digest to the wrong executable
+is rejected before it can become searchable.
+
+## Compatibility Evidence
+
+CellScript's curated vectors live in
+`examples/registry_ls_idl/vectors.json`. The complete upstream client vector
+corpus is intentionally referenced rather than copied:
+
+- `ckb-idl-derive` commit
+  `e7ee35766b9084099e9d840ccd37d2b5d40074a1`;
+- `ckb-idl-client` commit
+  `7d883e0abccba56d423449b673567ee817747936`;
+- upstream `test-vectors.json` SHA-256
+  `a9a6dca4fd0c5fcd2ca7aea6468784be7fdb29d6274049f07090cbab0ce9c1bb`.
+
+The upstream mini Registry example parses and reserialises JSON, so it is not
+used as the byte-preserving production storage contract. One upstream property
+test also constructs a Blake2b commitment while the production client verifies
+SHA-256. CellScript follows the production client and proposal commitment,
+records those upstream revisions, and tests SHA-256 end to end.
+
+## Operational Boundary
+
+Deploying the website does not deploy the Registry API. Operators must apply
+migration `0010_ls_idl_interfaces.sql`, roll the API and verification worker,
+and verify the canonical and compatibility routes before advertising live
+lookup availability. Existing artifact records without an interface contract
+remain valid and are not returned by LS-IDL lookup.

docs/CELLSCRIPT_REGISTRY_PHASE1.md

@@ -254,6 +254,20 @@ build is marked `evidence_required` until
 appropriate build evidence exists; merely uploading output bytes does not prove
 reproducibility.
 
+### LS-IDL Lock Script interface
+
+A deployable `ckb_executable` with `ckb.script_role = "lock"` may add a
+`cellscript-registry-ls-idl-interface-v1` contract. The ABI object is the exact
+LS-IDL JSON byte sequence; its SHA-256 must match the contract and the
+executable's final 32 bytes. Use `cellc artifact ls-idl validate`, `bind`, and
+`bundle` to construct this relationship. The normal and least-privilege
+verifiers independently enforce it.
+
+This adds a discoverable interface identity, not a semantic implementation or
+security claim. The full schema, supported field encodings, compatibility
+vectors, and operator boundary are in
+[`CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md`](CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md).
+
 ## Accepting Reproduction Evidence
 
 The Registry never executes an arbitrary publisher build recipe in its API
@@ -422,6 +436,8 @@ GET  /v1/artifacts
 GET  /v1/artifacts/:namespace/:name
 GET  /v1/artifacts/:namespace/:name/releases/:release/evidence
 GET  /v1/artifacts/:namespace/:name/releases/:release/commitment
+GET  /v1/ckb/scripts/:code_hash/interfaces/ls-idl?network=:network&hash_type=:hash_type[&data_hash=:data_hash]
+GET  /idl/:code_hash
 GET  /artifacts/:namespace/:name/releases/:release.json
 POST /v1/artifacts/:namespace/:name/releases
 POST /v1/artifacts/:namespace/:name/releases/:release/deployments
@@ -454,6 +470,9 @@ that every artifact is installable.
 ## Fail-Closed Rules
 
 - Unknown kinds, profiles, languages, object roles, and state values fail.
+- LS-IDL lookup returns only an active, public, chain-verified deployable Lock
+  Script with a schema-valid, raw-byte SHA-256/suffix-bound interface; type-hash
+  lookup requires `data_hash`, and ambiguous candidates fail.
 - Identifiers are 1–64 lowercase letters or digits; `_` and `-` are allowed
   only between characters.
 - A source dependency resolver rejects every non-CellScript profile.

docs/CELLSCRIPT_REGISTRY_PRODUCTION_BOUNDARY_ADR.md

@@ -140,6 +140,13 @@ CKB/ABI, verifier IPC, reproducibility, or copy semantics to the immutable
 objects. The bundle is bounded to 5 MiB. Unknown fields and unknown or duplicate
 roles fail closed in admission, publisher CLI, and isolated verifier.
 
+Deployable Lock Scripts may attach
+`cellscript-registry-ls-idl-interface-v1`. It binds SHA-256 of the exact ABI
+object bytes to the executable's final 32 bytes. The read API resolves those
+bytes only from active chain-verified deployment evidence and preserves them
+without JSON reserialisation. This is interface identity evidence, not proof of
+implementation correctness or a security audit.
+
 ## Verification Boundary
 
 The worker leases jobs with `FOR UPDATE SKIP LOCKED`, bounded retry, dead-letter
@@ -218,6 +225,11 @@ Static release objects use:
 https://registry.cellscript.dev/artifacts/:namespace/:name/releases/:release.json
 ```
 
+LS-IDL adds a dynamic, chain-identity read at
+`/v1/ckb/scripts/:code_hash/interfaces/ls-idl` and the upstream-compatible
+`/idl/:code_hash` alias. `hash_type=type` requires a data hash, and ambiguity
+fails closed rather than selecting one deployment.
+
 The static origin does not require Postgres. Objects include immutable bundle
 identity, artifact descriptor, all state axes, and accepted evidence. Consumers
 verify object, file, source, build, and deployment hashes independently.
@@ -274,6 +286,10 @@ Migrations are additive after the frozen `0001` baseline. The artifact-model
 migration intentionally refuses to transform non-empty legacy release data
 because no released public contract exists that would justify a lossy mapping.
 
+Migration `0010_ls_idl_interfaces.sql` adds only a partial functional index for
+eligible deployment evidence; exact release, bundle, ABI, digest, and suffix
+checks still run on every response.
+
 Readiness covers database/object access, admin configuration, and the verifier
 heartbeat. Backups contain a Postgres custom dump, object archive, image
 identity, and checksum manifest; restores are rehearsed into empty volumes

docs/README.md

@@ -72,6 +72,9 @@ High-value active references include:
 - `CELLSCRIPT_REGISTRY_PRODUCTION_BOUNDARY_ADR.md` for the accepted production
   boundary of the wallet-rooted public registry write/read architecture and
   isolated Pudge testnet sandbox
+- `CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md` for byte-exact LS-IDL admission,
+  executable suffix commitment, Script-identity lookup, tooling, and operator
+  boundaries
 - `../services/registry-api/README.md` for the Cloudflare Workers + R2 + Neon
   write API implementation and deployment checklist
 - `CELLSCRIPT_COLLECTIONS_SUPPORT_MATRIX.md`
@@ -131,6 +134,8 @@ to current branch-specific evidence or forward design:
   governance scope
 - `CELLSCRIPT_REGISTRY_PHASE1.md` for the current artifact, verification,
   deployment-evidence, and public API contract
+- `CELLSCRIPT_LS_IDL_REGISTRY_PROFILE.md` for the 0.24 Lock Script interface
+  profile and compatibility evidence
 - `archive/0.20/CELLSCRIPT_0_20_ROADMAP.md` for generated TypeScript action builders,
   live-chain registry verification, stateful flow evidence, and the bounded
   CellFabric JSON bridge