README.md — core-channel

1# core-channel

3`core-channel` is the ordinary Sigil library repository behind the authenticated

4`core/` environment-package scope. Reviewed package definitions live under

5`src/` and are imported like any other Sigil modules. The signed snapshot and

6catalogue authenticate that source tree and its exported canonical package

7objects. Generated toolchains, source archives, build output, and the seed

8tarball are deliberately not committed.

10## Clone, bootstrap, enter

12On x86_64 Linux, a checkout becomes a working `--channel` directory with:

14```sh

15./bootstrap

16export SIGIL_REGISTRY_METADATA=/path/to/root-signed/registry.json

17SIGIL_CHANNEL="$PWD" sigil env lock -f demo/env.sgl --lock-file env.lock

18sigil env shell -f env.lock -- hello

19```

21`sigil env shell` consumes an `env.lock`, never environment source, so the lock

22step is separate and comes first. Only the lock step needs the channel and the

23registry metadata; consumption deliberately needs neither. Requires sigil

240.18.0 or newer, which is the first release with `env`.

26`bootstrap` downloads the seed and Zig archives from their manifest URLs,

27verifies their SHA-256 hashes before installation, and refuses altered or

28unexpected content. It requires `sh`, `sha256sum`, `tar`, and either `curl` or

29`wget` on the host.

31Authenticated package values are published under the `core/` scope by the

32catalogue. For example, `(core packages wasm)` defines Binaryen 112 and the

33catalogue exports it as `core/binaryen`. `sigil project lock` evaluates only

34the snapshot-pinned `src/` closure, verifies the exported package identity,

35realizes missing outputs, and seals those results into referenced locks.

37The older `recipes/` directory remains for the original external-build channel

38prototype. New authenticated package definitions use normal modules under

39`src/`; do not duplicate them in `recipes/`.

41## Repository layout

43- `package.sgl`: ordinary Sigil library metadata.

44- `src/`: reviewed authenticated package-definition modules.

45- `objects/`: canonical package values named by their SHA-256 identity.

46- `snapshot.sgl`: signed source/toolchain snapshot.

47- `channel.catalogue.sgl`: signed exported binding-to-package map.

48- `channel.sgl`: executable curator declaration for public package bindings.

49- `recipes/`: legacy external-build prototype recipes.

50- `seed/MANIFEST`: pinned downloadable seed artifact.

51- `seed/MANIFEST.sources` and `seed/scripts/`: pinned seed sources and the

52 reproducible seed build.

53- `toolchain/MANIFEST`: pinned Zig distribution.

55After editing channel source or bindings, run `sigil channel publish` with the

56channels-role signing context. `make check` deterministically re-derives the

57sealed objects and roots and refuses stale committed artifacts; CI should run

58the same target. The metadata under `test/` and the currently committed root

59signatures use public, unlocked test keys and are not deployable production

60artifacts.

61- `bootstrap`: verified materialization of ignored binary inputs.

62- `scripts/gate-*`: permanent reproducibility, isolation, tamper, and

63 concurrency checks.

65Release `seed-v1` must carry `seed-x86_64-linux.tar.gz` with the exact hash in

66`seed/MANIFEST`. The release asset is produced with

67`seed/scripts/build-seed.sh`; it is never added to Git.

69## Gates

71```sh

72scripts/gate-hash-verify.sh

73scripts/gate-crosscheckout.sh

74scripts/gate-crosspath.sh

75SIGIL_BIN="$(command -v sigil)" scripts/gate-concurrency.sh

76```

78The fresh-clone gate accepts `SIGIL_BOOTSTRAP_SEED_URL` and

79`SIGIL_BOOTSTRAP_ZIG_URL` solely to test unpublished release assets or local

80mirrors. Overrides change locations, never expected hashes.