toko-tooling 0.37.3

Shared development tools, CI helpers and engineering rules for Dragginzgame
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
# Local developer setup
<!-- Shared companions: .github/actions/cache-tool-downloads/action.yml scripts/ci/report-tool-versions.sh docs/tool-store-maintenance.md docs/tool-catalog-bindings.md docs/verification-helpers.md docs/ic-tools.md docs/supported-hosts.md docs/make-interface.md docs/consuming-snapshots.md docs/releases.md TOKO-TOOLING.md rules/cargo-dependencies.md rules/git-hooks.md -->

## Tool selection and diagnostics

`make tools-report` runs all existing host, common Rust and selected local check
targets, retaining individual failures through the shared validation logger.
It returns nonzero if any check fails and never calls install targets. It is an
optional diagnostic, not release admission: `make tools-check` keeps its existing
fail-fast behavior. Local check targets must retain their offline/no-install
contract. The report uses the consumer root even with a nested shared snapshot.

The host, IC and Rust installers accept `--describe` instead of installation,
`--check` or `--preflight`. They print JSON after parsing the same selection
used by normal operation, without creating stores, probing installed binaries,
invoking Cargo/Rustup or downloading. For example:

```bash
bash scripts/dev/install-rust-tools.sh --consumer "$PWD" --describe
bash scripts/dev/install-ic-tools.sh --consumer "$PWD" --tool wasm-opt --describe
```

Catalog selections include absolute consumer/catalog/source paths, the installer
source fingerprint and selected version/digest records. Explicit Cargo recipes
instead report package/version, binary or example, profile, features and lockfile.
Lock-selected recipes still need prepared yq/jq to read the supplied lockfile.
No output claims installed-tool integrity or registry availability. For catalog
agreement, capture the JSON as a [caller observation](tool-catalog-bindings.md);
retain the actual command and its source context. Product pins remain local.

## Common setup

Prepare the declared compiler and the consumer's
[native/system prerequisites](#native-bootstrap-before-cargo-tools) first. Then,
from the checkout root, prepare the common executables explicitly:

```bash
make install-tools
make tools-check
export PATH="$PWD/.tools/host/bin:$PWD/.tools/rust/common/bin:$PATH"
```

Prepare the declared Rust/Cargo toolchain and native build prerequisites first,
even when the repository has no Rust packages. The Makefile uses local tool
paths automatically. Interactive shells need the
export above; setup does not edit shell profiles. Installation downloads tools;
tool checks are offline and never install missing executables. Preparing missing
workspace dependency sources during authorized development/validation follows
the [locked Cargo fetch policy](../rules/cargo-dependencies.md#cargo-network-policy).
Before tool downloads,
`install-tools` uses the Rust installer to admit its selected
platform/pins and probe the consumer's selected `rustc` and `cargo`. This
read-only `--preflight` call creates no tool/build directories and disables
Rustup auto-installation; missing or unavailable toolchains require explicit
bootstrap. This is not a compiler/linker qualification or a toolchain upgrade.
Setup then runs host and Rust installation in that order, followed by declared product tools;
`tools-check` checks the same sets in order. Each stops at the first failure.
Sets activate independently: a later failure preserves earlier completed sets.

### Native bootstrap before Cargo tools

System/native setup that changes Cargo build inputs must finish **before**
`make install-tools`, `make install-rust-tools` or selected Cargo executable
setup, including the release metadata editor. This includes compiler/linker and
SDK setup and the consumer's system packages. The
[standard build identity](#standard-cargo-tool-build-environment) includes native
compiler/linker digests and build-relevant Linux packages or macOS/Xcode/SDK identity;
changing those after Cargo setup correctly invalidates the earlier selection.

Keep an explicit sequence in the consumer's existing setup/release-preparation
adapter:

1. Install required system/native prerequisites and prepare the selected Rust
   toolchain; admit those prerequisites with the consumer's read-only checker.
2. Prepare common Shared tools and selected Cargo executables, including the
   release editor when used.
3. Prepare browser and other product dependencies that leave the compiler/native
   environment unchanged. Any step that changes fingerprinted build inputs
   belongs in the first phase instead.
4. Run offline tool admission and all other prerequisite checks needed by the
   actual release gate, then dispatch validation.

OS package lists, supported-host setup and local names such as
`install-native-tools` / `native-tools-check` remain consumer-owned. The ordered
`LOCAL_TOOL_INSTALL_TARGETS` list runs **after** the common host/Cargo sets, so it
is too late for native bootstrap. Do not add unordered prerequisites to shared
aggregates, replace their recipes or invent another tool catalog. Use the
[consumer adapter example](make-interface.md#native-bootstrap-adapter).

If system packages, a compiler or an SDK change after preparation and offline
admission reports “No prepared Cargo tool selection for the current compiler/build
inputs”, finish native setup and explicitly rerun the affected common/selected
Cargo setup before checking again. Preserve selected deliverables and required diagnostic
evidence; do not edit receipts, bypass fingerprints or make a checker install
packages. `tools-check` admits only its declared common/local tool sets, not every
native or product prerequisite of a release. The consumer must check those too.

## Required tool inventory

This is the common setup list for every repository adopting the
[engineering baseline](../TOKO-TOOLING.md). The host and Cargo-tool sets are required.
The IC bundle is selected only by repositories whose workflows use it. Consumers
add their product prerequisites to local setup documentation; omissions or
different support scopes require an explicitly approved exception.

| Set | Executables | Setup and verification |
| --- | --- | --- |
| System bootstrap | Bash, Git, GNU Make, curl, CA certificates, tar, gzip, xz, Perl, a SHA-256 implementation and standard Unix utilities | Host package manager; see [bootstrap prerequisites]#bootstrap-prerequisites |
| Common host tools | `jq`, Mike Farah `yq`, `rg` with PCRE2, `cloc` | `make install-host-tools`; offline `make host-tools-check`; `.tools/host/bin` |
| Optional product IC tools | `quill`, `icp`, `didc`, `ic-wasm`, `wasm-opt` | `make install-ic-tools`; offline `make ic-tools-check`; `.tools/ic/bin` |
| Common Cargo tools | `cargo-sort`, `cargo-sort-derives` | `make install-rust-tools`; offline `make rust-tools-check`; `.tools/rust/common/bin`. All repositories prepare a declared Rust/Cargo toolchain and native build prerequisites first. |
| Rust development | rustfmt and product compilation targets | Consumer toolchain setup and the [formatter prerequisite check]verification-helpers.md#formatter-prerequisites |
| Workflow-specific tools | ShellCheck, actionlint, Gitleaks, authenticated `gh`, Node/SDKs and other tools used by that repository | Explicit consumer setup; declare the tools required by each workflow |

Shared's archive-license fixtures also require Perl's `Archive::Tar` module.
Registry source-bundle installation requires `Archive::Tar` and
`IO::Uncompress::Gunzip` as well; prepare them through the host's Perl packages
before initial adoption.
Check availability with `perl -MArchive::Tar -e 'exit 0'`; install it through the
host's Perl package setup if absent. The portable prerequisite check refuses a
missing module before allocating suite fixtures. Archive inspection also uses
the bootstrap `gzip` executable; it never extracts archives.

Follow the derive sorter's documented
[macro qualification and pin adoption](../rules/git-hooks.md#derive-macros-and-dollar-prefixed-paths)
before removing corruption-workaround markers. The selected 0.14.1 formatter
requires Rust 1.88 or newer to build; our selected compiler is 1.99.1 under the
[compiler support policy](../rules/cargo-dependencies.md#minimum-supported-rust-version-msrv).
Tool availability and version checks do not establish semantic preservation.

`make install-tools` and `make tools-check` cover the common host/Cargo executables,
regardless of the repository's implementation language. The five IC executables
are optional product tools; their standalone setup/check targets remain available.
Setup does not install a Rust toolchain or authenticate GitHub. Product and workflow-specific
tools extend the aggregate through existing consumer-owned targets:

```make
# Select only when this repository uses IC executables.
IC_TOOLS := ic-wasm wasm-opt
LOCAL_TOOL_INSTALL_TARGETS += install-ic-tools
LOCAL_TOOL_CHECK_TARGETS += ic-tools-check
include make/consumer.mk
export PATH := $(CURDIR)/.tools/ic/bin:$(PATH)
```

IC consumers also publish `.tools/ic/bin` to their CI PATH after successful
setup/check, and include it in their interactive-shell PATH. The common action
publishes only host/Cargo paths; it never activates an unselected IC bundle.

These lists run sequentially after the common sets, including under parallel
Make. Declare each required product setup/check pair; do not add prerequisites
to `install-tools`/`tools-check`, override their recipes, or include an aggregate
in its own extension list. Extensions must not call their enclosing aggregate.
Select independently qualified CLI versions in their existing owner adapters.
Rustfmt, compiler targets, credentials and other product prerequisites retain
their documented setup; executable installation grants no deployment authority.
Common versions and digests come from the reviewed snapshot catalogs below.
Do not maintain a second consumer default list. Explicit qualified exceptions
remain available as described under [catalog selection](#catalog-selection).
dfx is excluded from the common IC set. See the host limits below before setup.
Keep identity stores separate from resettable state as described in
[IC identity storage](ic-tools.md#identity-storage-and-local-resets); installing
executables does not authorize moving keys or wiping a CLI home.

Make and CI must select their own checkout's local tool paths. CI exports them
for subsequent steps explicitly; Make's export does not change the calling
terminal. Follow the [consumer adoption example](consuming-snapshots.md#local-ic-tool-adoption)
for the complete installation/check selections, including ripgrep and cloc.
Those commands are owned by `make/tools.mk`, selected through the
[consumer Make entrypoint](make-interface.md). Consumers include that reviewed
snapshot instead of maintaining copied recipes or installer flags. Toko
Tooling's own Makefile and CI use the same commands. Snapshot adoption brings
command updates; explicit setup brings newly required executables.

The include also selects `make/execution.mk` and its
`scripts/ci/check-make-execution.sh` companion. It rejects dry-run, touch,
question and ignore-errors modes before protected tool recipes execute. Cargo recipes retain
Make's jobserver descriptors for parallel execution; this does not grant
installation authority to an inspection command or change the setup order.

The installed `cloc` executable and local workspace `make cloc` are common setup.
The consumer include exports workspace LOC. Tooling adoption is reviewed through
the [agent audit tasks](https://github.com/dragginzgame/toko-tooling/blob/08cd17240fd60dfd309e35eb131e73323e883e6f/docs/fleet-tools.md#tooling-adoption-audit); consumers need no
fleet reporter or its regression suites.

## Catalog selection

Since 0.10.0, the executing reviewed snapshot owns the defaults:
`ci/tool-versions.env` for host/Cargo tools and `ci/ic-tools.tsv` for IC tools.
Make resolves both relative to `TOKO_TOOLING_ROOT`; standalone installers and
the Cargo freshness checker resolve them relative to their own snapshot.
`--consumer` selects the checkout's installations, not its default catalog.
Missing snapshot catalogs fail; there is no consumer-local fallback.
Snapshot adoption selects the pins but never installs or upgrades executables.

For a justified exception, keep a separate reviewed consumer file and select the
affected set explicitly before including `make/consumer.mk`:

```make
IC_TOOL_PINS := $(CURDIR)/config/qualified-ic-tools.tsv
```

`HOST_TOOL_VERSIONS` and `RUST_TOOL_VERSIONS` independently select alternative
host and Cargo catalogs. A host override does not change Rust or formatting pins.
Each file must contain the complete selection required by its set; no implicit
overlay is merged. Record the reason, affected hosts and native qualification in
consumer governance. Keep snapshot payloads unchanged, including when excepted.
Standalone calls use explicit `--versions` or `--pins`; freshness inspection uses
`--versions`. CI cache-key inputs and direct catalog reads must select the same
catalog as installation. The failure-evidence action defaults to the catalogs
beside its own snapshot; set `host-versions`/`ic-pins` explicitly when using an
exception so successful-tool compaction checks the intended selection.

Common tool catalogs do not own compiler selection; the
[compiler support policy](../rules/cargo-dependencies.md#minimum-supported-rust-version-msrv)
does. Application dependencies, Testkit/PocketIC selections and product tool
adapters remain consumer-owned. Workflow-only
tools may retain consumer selections; merely adopting a catalog does not install
tools outside the common inventory or change a workflow's declared support.

## Toko Tooling's integration editor

Toko Tooling's own `make install-tools` also prepares the released IC Build
editor used by its integration fixtures; `make tools-check` admits that selection
offline. The standalone targets are `make install-release-editor` and
`make release-editor-check`. The latter prints the verified absolute executable
path and never installs it. Its version, profile and fixture byte allowance are
selected in Shared's root Makefile.

The selection is IC Build 0.73.0 with the explicit `cli` feature. Portable CI
includes endpoint-only release-group preparation, rollback and delivery/resume
qualification alongside the coordinated-workspace fixture. An older prepared
editor cannot qualify that contract; rerun `make install-release-editor` after
adopting this selection, then use `make release-editor-check` for offline admission.

`make test-portable` checks that prepared selection before starting any fixtures
and supplies its path and allowance to the suite. CI uses these same setup and
test targets. The cache key includes the owning Makefile, so a changed selection
cannot keep reusing a cache key for an older tool set. Cache presence never
replaces installed-byte admission.

Direct suite and prerequisite-helper calls must also supply
`CARGO_RELEASE_METADATA_EDITOR` (an absolute executable file) and
`CARGO_RELEASE_METADATA_MAX_BYTES` (a positive decimal integer). The prerequisite
helper checks those inputs before fixture allocation without executing the
editor. Prefer `make test-portable`, which supplies the offline-admitted values.

This editor is a Shared-local requirement, not an addition to every consumer's
common Cargo tools. Consumer release adapters retain the explicit selections in
[Cargo candidate rendering](releases.md#cargo-release-candidate-rendering).

Shared's standard release commands prepare and check these tools after fresh
source/changelog admission, before validation. Reconciliation of saved preparation
and standalone `release-preflight` only check prepared tools; neither installs
against interrupted metadata. PR delivery prepares the exact merged checkout's
tools before its fresh validation. Ordinary metadata preparation and late checks
do not install tools.

## Shared executable storage

Toko Tooling owns storage for the common executable sets. Host and IC setup
reuse verified bundles in a per-user store across checkouts with the same host
and pins. Each repository retains its reviewed snapshot and command
selection; changing one repository's selection must not change another's.
Providing every common command does not require duplicating its binary in every
checkout. Consumers must adopt the canonical implementation through reviewed
snapshots rather than create independent stores or new bespoke `.tools`
installers. Reviewed script snapshots remain repository-local.

The default store is `${XDG_DATA_HOME:-$HOME/.local/share}/toko-tooling/tools`.
Set `TOKO_TOOLING_STORE` to an absolute directory to choose another location;
use the same setting for setup, checks and evidence collection. Fixtures use
isolated temporary stores. Store directories must be owned by the current user,
physical, and not writable by other users. Existing ancestor aliases such as
macOS `/var` are resolved; managed directories and payloads cannot redirect
outside their admitted locations. CR/LF paths are refused.

The existing `.tools/host/bin` and `.tools/ic/bin` command paths remain, backed
by lightweight local references to exact shared bundle generations. No new host
or IC payload is stored inside the checkout. A complete matching bundle is
verified again before reuse without downloads. Changed pins or platforms select
a different store entry; updating its reusable selection never retargets other
checkouts. Locks protect setup across repositories as well as local activation.
Offline checks never install or repair tools. Corrupt bundles are refused;
explicit setup can prepare a fresh generation without overwriting retained ones.

Adoption requires refreshed installers, `scripts/dev/tool-store.sh`, and the
evidence selector, followed by `make install-host-tools`, `make install-ic-tools`
and their offline checks. Older physical checkout-local bundles are preserved
but no longer admitted as active installations. Do not manually relocate them
or delete them during adoption. Failed attempts and earlier selections remain
referenced from the originating checkout for evidence collection. The collector
archives those admitted shared bundles, not the entire machine's store. Deleting
a checkout or a reference does not reclaim its stored payload; cleanup remains
an explicitly authorized separate operation.

Cargo tools also live in the shared store. Local `.tools/rust` contains selections
and references; successful compiler scratch is discarded after byte admission.
Current declared requirements across checkouts protect their selections; obsolete
managed Rust generations use [previewed reclamation](tool-store-maintenance.md).
Legacy physical installations require explicit migration. Reuse requires the exact
compiler, native environment, published
source/lock, target and profile under the standard environment described below.
The store's `cargo-cache` holds Cargo-managed registry sources separately from
retained installation generations; preserve it for offline admission and reuse.

## Diagnosing a missing command

Installing tools in Toko Tooling does not select them in another checkout.
Run setup in each checkout; matching host/IC bundles reuse the shared store.
From the affected repository's root, compare:

```bash
.tools/host/bin/cloc --version
command -v cloc
```

If the first command works but the second is missing or points elsewhere, select
this checkout's tools in the current terminal:

```bash
export PATH="$PWD/.tools/host/bin:$PWD/.tools/rust/common/bin:$PATH"
```

Select the paths again when switching repositories; do not permanently select a
sibling checkout's tool directory in a shell profile. Repository Make targets
must work without this manual export. If the local executable is absent, run
`make install-host-tools` and `make host-tools-check` in that repository. If its
setup still omits cloc, adopt the reviewed shared installer, pins and complete
Make/CI selection first. A PATH change cannot supply an uninstalled executable.
Installing `cloc` also does not create a `make cloc` target: Rust LOC report
adoption needs the shared report script and the Make include shown in the
[consumer adoption guide](consuming-snapshots.md#local-ic-tool-adoption).

## Pinned local tool sets

`make install-host-tools` installs jq, **Mike Farah yq** (including its TOML
parser), ripgrep with PCRE2, and cloc under `.tools/host/bin`. `make host-tools-check`
verifies their bytes before executing version and feature checks. Failures report
the exact tool, expected version, selected path, reason and repair command.
Actual version/probe output is included only after all payloads authenticate;
missing or unauthenticated executables are never run for diagnosis. The reviewed selections
live in [ci/tool-versions.env](../ci/tool-versions.env):
[jq 1.8.2](https://github.com/jqlang/jq/releases/tag/jq-1.8.2),
[yq 4.47.2](https://github.com/mikefarah/yq/releases/tag/v4.47.2),
[ripgrep 15.2.0](https://github.com/BurntSushi/ripgrep/releases/tag/15.2.0), and
[cloc 2.10](https://github.com/AlDanial/cloc/releases/tag/v2.10).
Setup itself needs neither parser installed. Distribution packages named `yq`
may provide a different implementation; they do not replace the selected parser.

Host setup downloads official native binaries for Linux x86-64/ARM64 and macOS
Intel/Apple Silicon and cloc's portable standalone Perl script. It checks their
pinned SHA-256 values and exact versions, and
atomically activates the selected set. Previous sets and failed candidates
remain in the shared store, referenced by `.tools/host-set.*`. Locks prevent
simultaneous installation of the same shared selection and local activation;
inspect `.tools/.host-tools.lock/owner` and confirm its process has stopped before
removing an abandoned lock; shared slots also retain `install.lock/owner`.
Offline checks report the shared lock path and refuse while that selection's
shared lock is held, including when another checkout owns the installation.
Host and IC setup attempt both lock releases on exit, even if checkout cleanup
fails. An installation failure keeps its original status and retained candidate;
a cleanup-only failure also returns nonzero. Inspect any remaining lock before
retrying, even when the selected bundle was successfully activated.
Hosted CI should restore pinned asset downloads **before** installing host or CI
tools. Use the shared [download-cache action](../.github/actions/cache-tool-downloads/action.yml)
once with its default `mode: restore`, then `mode: save` immediately after
successful setup, before compilation/tests. Saves are restricted to default-branch
pushes; PR jobs may read. The common-tools action does this when `cache: true`
is selected; callers installing tools earlier must restore before that earlier
step. Do not repeat cache setup for each release group.

The action sets `TOKO_TOOLING_DOWNLOAD_CACHE` to a runner-temporary directory.
Assets are addressed by their pinned SHA-256 and authenticated before reuse or
extraction; corrupt entries are downloaded again, and failed/unverified downloads
are never cached. Installer version/probe checks still run. Cache service failures
fall back to ordinary bounded downloads. Cache keys cover host, job and the pin
catalogs/Makefile, without commit IDs. Custom pin paths must be included in the
caller's `extra-key` fingerprint (common setup forwards `cache-extra-key`). Local setup creates no additional archive cache unless
this variable is explicitly set; that directory is disposable in full.
A cold cache plus an unavailable upstream can still block setup; retain the
infrastructure-failure diagnosis rather than mark qualification successful.

Explicit host, IC and CI asset downloads use curl's transient retry classification,
with at most three retries, a two-second delay and a 60-second retry-start window.
Each attempt keeps its 15-second connection and 300-second transfer limits;
an attempt already in flight can finish after the retry window. Permanent HTTP
errors and checksum/admission failures are not retried. Exhaustion returns curl's
final failure status and preserves the failed candidate and previous selection.
Cleanup remains explicit. The `--versions` option
selects reviewed literal assignment data. Host/Rust installers, freshness checks
and cache identities use the same parser. Shell commands, substitutions, duplicate
keys and nonliteral values refuse before installation or cache output. Replace
computed catalogs with complete literal selections before adopting this cut.

Setup and offline checks admit the literal `.tools/host` link target. Malformed
managed names, including trailing newlines, are refused before tool execution
or downloads; the existing link and bundles remain intact.

Host installation and offline checks always include ripgrep. Consumers add `TOKO_TOOLING_RIPGREP_VERSION`
and the four `TOKO_TOOLING_RIPGREP_SHA256_*` archive digests to their reviewed
versions file.
Offline checks authenticate the retained archive and compare its executable
bytes with installed `rg` before running it. They require the exact version
(allowing the official revision annotation) and a successful `--pcre2-version`.
No Cargo installation, global PATH change or system-package replacement occurs.

Host installation and offline checks also always include the standalone cloc payload.
Consumers adopting it add `TOKO_TOOLING_CLOC_VERSION` and the single
`TOKO_TOOLING_CLOC_SHA256` pin to their reviewed versions file. All four payloads are authenticated
before executing any version check; failed candidates retain the previous active
set. cloc uses the bootstrap Perl interpreter and needs no Cargo build or system
package installation. LOC reports select the prepared local host path themselves
and never install tools during counting.

The [IC set](ic-tools.md) supplies Quill, ICP CLI, didc, ic-wasm and
wasm-opt. dfx is excluded. Linux ARM64 supports the host set only; the full IC
set lacks a matching Quill asset. Native CI qualifies both sets on Linux x86-64
and both macOS architectures; mapping Linux ARM64 is not native qualification.
PocketIC consumers additionally use their selected IC Testkit CLI's explicit
`setup` and offline `check`; follow the
[ownership handoff](ic-tools.md#pocketic-ownership-handoff).

## Rust development tools

After preparing the consumer's declared Rust/Cargo toolchain and compilation
prerequisites, use `make install-rust-tools` and offline `make rust-tools-check`.
The shared helper installs cargo-sort and cargo-sort-derives
into shared build-identity slots and exposes the complete set at `.tools/rust/common/bin`, using their exact versions from
[ci/tool-versions.env](../ci/tool-versions.env) and Cargo's `--locked` installation.
Preflight selects the consumer's prepared compiler, including explicit Rustup
toolchain overrides. Installation then uses that compiler's real Cargo/rustc
binaries in a standard environment, separate from the consumer's build settings.
A relative `--versions`
catalog is read from the caller's directory before entering the consumer;
relative `--lockfile` paths retain their consumer-relative meaning.
`RUST_TOOL_VERSIONS` selects a reviewed alternative catalog; it defaults to
the snapshot's `ci/tool-versions.env`, independently of `HOST_TOOL_VERSIONS`.
Keep qualified version exceptions in that selected catalog,
and remove duplicate consumer constants when adopting the shared pins.

Use [IC Wire for supported controlled application messages](../TOKO-TOOLING.md#ic-application-encoding).
Candid extraction serves the Candid interfaces a product still needs; Wire codec
generation does not require a Candid extractor.

Candid extraction is a product-selected tool. Consumers that extract declarations
own its pin, explicit installation/check target and PATH selection through the
[selected Cargo tool interface](#consumer-selected-cargo-tools). Common setup does
not install it. Qualify that selection before adopting the narrower common set;
retained installation slots are not deleted.

The complete common aggregate includes this set in every repository, including
non-Rust repositories. The narrow commands remain useful for explicit retries
or diagnostics; they do not establish that the complete toolset is ready.
Shared Make commands include `.tools/rust/common/bin` on PATH; interactive shells use
the export at the top of this guide. The standard formatting hook and its
adoption check preserve the original checkout's common host and Rust tool paths
while formatting isolated index inputs. IC formatters select their prepared tool
PATH explicitly; the hook exposes `TOKO_TOOLING_FORMAT_TOOLS_FROM` for product
Make recipes that need the original checkout's tool root. The helper never prepares or upgrades a
toolchain implicitly. Installation may fetch registry dependencies and compile;
failed candidates and install logs remain in shared `rust-<identity>/set.*`
generations, referenced from the originating checkout. Successful compiler scratch
is removed under installation custody; failed scratch has a seven-day retention
window, extendable with an explicit recovery pin. Receipts survive reclamation.
If build identity changes during installation, activation refuses and reports the
changed field names. The retained attempt contains the original `.build` identity
in `inputs.json` and `native-environment.txt`, alongside the exact new observation
in `build-identity.observed.json` and `native-environment.observed.txt`. These files
are included by the normal evidence collector; no automatic rebuild is attempted.
Both common tools and consumer-selected tools use the same locked installer,
Cargo receipt and observed byte-digest admission described below. Common tools
add a successful exact-version probe after byte admission. Shared host tools
(including jq) and the selected Rust toolchain must be prepared first.

The common setup holds `.tools/rust/common.lock`, prepares all three selections, then
atomically selects a retained `common-set.*` directory through the `common` link.
The catalog reader owns the common roster and stable-version admission; setup
projects those admitted records directly into executable selections.
Its `bin` contains only the three selected slot links. A partial failure leaves
the previous complete set active; rerunning setup reuses completed slots. Offline
checks refuse missing selections, locks, changed receipts/bytes and redirected
paths without installing or repairing them. The only permitted projection links
are generated common-set/selection links and validated references into the store.
Shared generations and their executables, builds and receipts must be physical. Existing host/IC links and checkout aliases
remain supported. Path admission does not sandbox Cargo or defend against an
unrelated process replacing admitted paths concurrently.

The 0.6 hard cut requires explicit setup of shared Cargo selections; previous
local installations are retained but never used as a fallback. Refresh the
installers and evidence selector together, then run setup and offline checks.
The evidence action retains the local `.tools/rust` tree without following its
links and separately archives only its admitted shared generations, including
selected output and retained failed attempts. Already discarded successful
compiler scratch is not evidence. This Rust evidence selection remains full even
when host/IC compaction is enabled.
Observed digests detect local changes; they are not publisher signatures or
product/native qualification. Formatting still requires rustfmt and the
[formatter check](verification-helpers.md#formatter-prerequisites).

### Standard Cargo tool-build environment

Explicit Cargo setup waits up to 60 seconds per occupied selected-tool slot
when its physical, user-owned lock has a readable, regular
owner record. Set `TOKO_TOOLING_SETUP_WAIT_SECONDS` to a canonical integer from
0 to 300 to select another budget; `0` retains immediate refusal. Diagnostics name
the slot and recorded owner, then report release or timeout. The record identifies
the claim, not whether its PID is still live. No lock is removed or owner killed.

After waiting, setup rechecks compiler/build identity, lockfile selection and
normal source/receipt/checksum admission before reuse or activation. An owner
failure never makes its partial generation reusable. An admitted owner's record
may disappear during cleanup only while the same physical lock directory remains;
a directory that has disappeared goes back through atomic acquisition. A missing
initial record or a replacement directory without an admitted owner still refuses.
Malformed, redirected or unwritable lock routes fail rather than polling. Atomic
`mkdir` still owns acquisition: if a new owner wins that race, or acquisition fails
for another reason, its diagnostic/status is preserved without a retry. Timeouts
are nonzero and retain previous selections and failed evidence. Plain `--check`,
`--preflight`, checkout locks and Host/IC setup remain immediate. The setup wait
environment variable does not change check behavior.

Cargo admission supports explicit `--check --wait-seconds N`, with a canonical
integer from 0 to 300. It waits only on an admitted exact shared-slot claim for
an already selected tool. Exit **75** means that admitted slot is busy or its
admission wait timed out; missing/corrupt preparation and invalid, inaccessible
or redirected claims remain failures rather than busy results. Consumers should
propagate that status and diagnostic instead of recommending installation or
classifying stderr text. The default budget is zero; setup waiting is unchanged.

After a wait, admission rereads compiler/build and source inputs, supplied
lock/catalog bytes, checkout reference, generation, features, receipts and
checksums. Changed inputs fail; an owner's partial installation cannot be
selected. This path performs no installation, repair, activation, lock acquisition
or foreign-lock cleanup. No consumer sleep/retry loop is needed. An immediate
busy check emits no executable path or installation hint. Successful waiting
prints the same path as an ordinary check, with wait diagnostics only on stderr.

Explicit Cargo-tool setup reports package/version, phase, outcome and elapsed
whole seconds on stderr. Start and completion messages distinguish source
preparation, selection reuse, shared-slot acquisition/waiting, cache reuse,
compilation and receipt/build admission when those paths run. Compilation output
stays in the retained attempt's `install.log`; a failure still replays that log
and returns its original status. Timings are observations, not a speedup claim or
another deadline. Diagnostic write failures do not replace command results.
Stdout remains the selected executable or common-bin path. Successful immediate
`--check` calls remain quiet on stderr; checks, preflight and descriptions add no setup.
These diagnostics do not change installed-tool identities or require rebuilding
an already admitted generation.

Source-cache initialization uses idempotent private directory creation, admitting
existing paths before creation and checking cache routes/configuration before
Cargo dispatch. It has no global installation lock; Cargo owns actual source
download serialization. Old source-preparation slots remain untouched.
The 0.26.8 build-helper change alters its policy digest: after adoption, rerun
explicit Cargo-tool setup to select tools under that policy. Previous generations
remain protected until explicitly migrated to the current maintenance policy,
and offline checks never repair selections.

Tool builds have a cleared environment, a fresh private HOME per attempt, the
selected compiler's bin directory followed by system executable directories,
fixed C locale/UTC timezone, private permissions and two compilation jobs.
Repository flags, wrappers, custom targets, user Cargo configuration and arbitrary
environment variables are not inherited. Application builds are unaffected.
An explicit nonempty `CARGO_NET_OFFLINE` (`true`/`false` or `1`/`0`) takes
precedence over user Cargo `net.offline`. Without that override, `net.offline`
must be a TOML boolean; strings and numbers are rejected before installation or
selection changes. Empty configuration or an absent key defaults to online
permission. Cargo's `config` takes precedence over `config.toml` when both exist.
No check downloads or repairs tools. Custom registries, extra native search paths and
proxy/credential configuration are not supplied to these public crates.io builds.

The key records the exact build-helper and native-classifier digests, Cargo/rustc
verbose identities and executable digests, host, native compiler/linker digests,
build-relevant Linux package identities or macOS/Xcode/SDK
identity, package/version, executable kind/name, profile, published crate digest
and packaged lock digest. Cargo owns registry downloads and `--locked` builds.
Changing the build helper requires explicit setup to select builds under the new
policy digest; earlier generations follow the maintenance policy and offline checks do not repair
their selections.
On Linux, the classifier admits packages owning system headers, public shared or
static libraries/startup objects, pkg-config metadata, GCC/LLVM support files,
native build generators and their support modules. Browser/editor executables,
private application libraries and application data alone do not affect the key.
Malformed or unavailable package inventories refuse admission. Compiler/linker
bytes, kernel/architecture and macOS OS/Xcode/SDK observations remain unchanged.
The whole helper/classifier digests intentionally remain conservative: even a
comment edit requires setup, avoiding a manually maintained policy revision that
could miss a semantic change. This is separate from unrelated OS application
updates. When a role's selection changes, setup reports changed identity fields
and the prior native/source receipt paths.
Missing packaged locks and non-registry dependency sources refuse reuse/builds;
unexpected Cargo configuration in the managed cache is rejected. This contract
supports managed Debian/RPM Linux hosts and the qualified macOS toolchain; it
does not model arbitrary custom native toolchains or out-of-band SDK/library
mutations. Such environments require a separately qualified contract before
sharing tools. It is a same-user build cache, not a hermetic sandbox or a signed
publisher attestation.

### Consumer-selected Cargo tools

The same installer also accepts an exact crates.io package, one binary or example
target, and an explicit `debug` or `release` profile. Prepare the shared host tools
(including jq and Perl) and the consumer-selected Rust toolchain first:

```bash
bash scripts/dev/install-rust-tools.sh --consumer "$PWD" \
  --package ic-blob-storage --version 0.15.1 --example prepare_upload --profile debug
# Repeat the same selection with --check for an offline, non-building check.
```

This example is a caller selection, not a new fleet-wide package pin. Consumers
own package versions, profiles, compiler selection, explicit executable overrides
and product qualification. Use `--bin NAME` for a published binary. This mode
does not install the formatter bundle or read its versions catalog; `make
install-rust-tools` prepares the common formatter tools through this same engine.

For a tool selected by a consumer lockfile, replace `--version` with `--lockfile`:

```bash
bash scripts/dev/install-rust-tools.sh --consumer "$PWD" \
  --package ic-testkit --lockfile Cargo.lock --bin ic-testkit-server \
  --profile release --features cli
bash scripts/dev/install-rust-tools.sh --consumer "$PWD" \
  --package ic-testkit --lockfile Cargo.lock --bin ic-testkit-server \
  --profile release --features cli --check
```

Testkit 0.63 requires `cli` for the server binary. Setup and offline admission
must request the same feature set, which is part of the tool's identity.
Library-only Testkit dependencies should omit `cli`.

Relative lockfile paths resolve beneath `--consumer`; absolute paths select an
explicit independent graph. The prepared host yq/jq tools read TOML without Cargo
resolution, downloads or lockfile writes. Exactly one package with the selected
name must exist, with an exact stable version and the crates.io registry source.
Missing, malformed, symlinked, ambiguous, local/Git/other-registry or prerelease
selections refuse before installation. `--version` and `--lockfile` are mutually
exclusive. Consumer-local `.tools/host/bin` takes precedence for the reader.
The same arguments with `--check` admit the selected installation offline.
Selection is read again before candidate activation and before returning a path;
a changed selection fails and retains any build attempt. Retry against the new
lock selection; prior installations remain intact. Consumers still own the
selected graph, package, target/profile and Testkit's separate server setup/check.

For a target gated by Cargo features, pass `--features NAME[,NAME]...` on both
setup and check. For example, Host's file CLI requires its `cli` feature:

```bash
bash scripts/dev/install-rust-tools.sh --consumer "$PWD" \
  --package ic-host-fs --lockfile Cargo.lock --bin ic-host-file --profile debug \
  --features cli
# Repeat the same arguments with --check for offline admission.
```

Feature lists use comma-separated ASCII names, optionally `dependency/feature`;
repeat `--features` to combine lists. Ordering and duplicates normalize to one
requested set. Empty lists, whitespace and malformed names refuse before setup.
Cargo validates whether the published package supports the requested features;
its refusal retains the attempt without activating it. Package defaults stay
enabled; this interface does not accept `--all-features` or `--no-default-features`.
Feature sets select separate immutable installations and must match the Cargo
receipt. Featureless requests keep their existing input shape. Ambient Cargo
flags cannot supply features, and checks never repair a mismatching selection.

Consumer extensions such as cargo-audit and cargo-machete use this same owner.
Keep their exact pins in the consumer and register their existing setup/check
targets in `LOCAL_TOOL_INSTALL_TARGETS` / `LOCAL_TOOL_CHECK_TARGETS`. For example,
with `AUDIT_VERSION` defined by the consumer's reviewed pins:

```make
AUDIT_TOOL = bash "$(TOKO_TOOLING_ROOT)/scripts/dev/install-rust-tools.sh" --consumer "$(CURDIR)" --package cargo-audit --version "$(AUDIT_VERSION)" --bin cargo-audit --profile release
LOCAL_TOOL_INSTALL_TARGETS += install-audit-tool
LOCAL_TOOL_CHECK_TARGETS += audit-tool-check

.PHONY: install-audit-tool audit-tool-check audit
install-audit-tool:
	+@$(AUDIT_TOOL) > /dev/null
audit-tool-check:
	+@$(AUDIT_TOOL) --check > /dev/null
audit:
	+@tool="$$( $(AUDIT_TOOL) --check )" && "$$tool" audit
```

Use the equivalent package/binary selection for cargo-machete, but its standalone
invocation differs from Audit. With `MACHETE_VERSION` selected by the consumer:

```make
MACHETE_TOOL = bash "$(TOKO_TOOLING_ROOT)/scripts/dev/install-rust-tools.sh" --consumer "$(CURDIR)" --package cargo-machete --version "$(MACHETE_VERSION)" --bin cargo-machete --profile release
LOCAL_TOOL_INSTALL_TARGETS += install-machete-tool
LOCAL_TOOL_CHECK_TARGETS += machete-tool-check

.PHONY: install-machete-tool machete-tool-check machete
install-machete-tool:
	+@$(MACHETE_TOOL) > /dev/null
machete-tool-check:
	+@$(MACHETE_TOOL) --check > /dev/null
machete:
	+@tool="$$( $(MACHETE_TOOL) --check )" && unset CARGO && "$$tool" --with-metadata
```

Audit needs `"$$tool" audit`; standalone Machete 0.9.2 needs
`"$$tool" --with-metadata`, with no extra `machete` argument. That version uses
inherited `CARGO` (when `CARGO_PKG_NAME` is absent) to select Cargo-subcommand
parsing. Unset `CARGO` only in the Machete recipe's shell before the standalone
call; application builds retain their environment. Keep the selected executable
as the final command so its failure status propagates, including on Bash 3.2.

Qualify the consumer's real dependency-check target as well as setup/check reuse.
Use separate Audit and Machete argument fixtures, including inherited `CARGO`,
failed admission with path-shaped stdout, and tool failure status/evidence
retention. An installer pass alone does not establish correct CLI invocation.

Repeated setup
verifies and returns the existing path without Cargo installation or force advice;
checks never build or download. Only the returned path is suppressed above;
failure diagnostics and status remain visible. The `+` prefix preserves Make's
recursive-command handling to the installer; standard tool builds themselves
use the documented two-job limit rather than inheriting the caller's jobserver.
Adopting this route changes global Cargo destinations to shared selections:
update execution callers to use the returned checked path, explicitly prepare
and check the tools, and retain old global installations. Do not add version-probe
fallbacks, force overwrites or another installer around the shared owner.

The command prints the admitted executable path under
`.tools/rust/selected-<build-identity>/bin/`.
Use that returned path in the consumer adapter. Each selection is immutable:
an existing installation must pass physical-path, exact Cargo receipt and local
byte-digest checks. Checks reject changed bytes or receipts without repair or execution;
each receipt must contain exactly one JSON document. Cargo installation failures
return Cargo's original exit status along with the retained attempt location;
no invented `--version` probe runs for examples. Checks invoke rustc for the
selected host and Cargo identity, but never build or download. Digests detect local changes; they
are not publisher signatures. The consumer still owns compiler compatibility.

Missing or invalid selected-installation diagnostics identify the package, exact
version, target kind/name, profile and failing path. Source admission distinguishes
missing archives from ambiguous cached sources; receipt and byte checks identify
the rejected file. Refusals include a shell-quoted explicit installer command
retaining the consumer's catalog or package/lockfile selection, target and profile.
For feature-selected tools, the repair command also retains the requested set.
An ambiguous cache still requires inspecting the named archives; rerunning setup
does not choose between them. Successful selection prints only the executable path.
Dependency updates that change the selected CLI must prepare and check it before
preparation is complete. Authorized releases use the existing setup/check targets
in [preflight](releases.md#selected-executable-tools-before-validation); fetching
Cargo sources alone is insufficient. Complete gates and standalone qualification
check tools offline before builds, without implicit installation.

Setup reuses a matching verified generation or compiles through the same locked
Cargo installation command into a fresh shared attempt. Only an admitted
candidate is activated. Explicit setup can replace a corrupt selection with a
new generation, preserving the old generation and other checkouts' references.
Failed attempts retain logs/builds for the recovery window; current requirements
and expiring recovery pins govern subsequent reclamation. Setup does not reclaim
old executable paths while they might be running.
A directory lock rejects concurrent setup for the same selection; retry after
its owner finishes. An abruptly killed process may leave a lock: inspect that
owner and retained attempt before explicitly removing the empty lock. The tool
never guesses that a lock is stale. Redirected output, receipt and lock paths
refuse. After Cargo returns, setup rechecks the shared directory ancestors and
selection slot before admitting or activating the candidate. As with the common
tools, path admission is not a sandbox against another
process deliberately replacing paths while setup runs. Installation may fetch
dependencies; `CARGO_NET_OFFLINE=true` remains authoritative.

Consumers adopt this mode from a reviewed snapshot, qualify their selected
package/profile on their native hosts, then remove superseded resolver/build
helpers. Local Canic source snapshots and application evidence remain outside
this registry installer. The three-host assessment below exercises the shared
production mode; its earlier Cargo-only results do not qualify this extension.

## Cargo installation assessment

Run `scripts/ci/qualify-cargo-install.sh` in Toko Tooling to exercise Cargo's
native installation contract in a new disposable evidence directory:

```bash
mkdir -p .tools
CARGO_NET_OFFLINE=true bash scripts/ci/qualify-cargo-install.sh "$PWD/.tools/cargo-install-assessment"
```

The offline command requires the registry packages and their locked dependencies
to be prepared already. Explicit online qualification may omit
`CARGO_NET_OFFLINE=true`; it installs only into the new evidence root and retains
builds and logs on both success and failure. Relative evidence paths resolve from
the caller's working directory independently of `CDPATH`; existing roots are
refused before tool probes. It never cleans or changes an existing installation.
The common fixture selects the reviewed cargo-sort version, using the debug
profile for direct Cargo assessment and release for the shared production
installer, including offline reuse and changed-byte refusal. Product compiler
floors and application CLI selections remain consumer-owned.

The frozen published Blob example assessment moves to
[IC Blob Storage PR #80 — Own frozen published-example installation qualification](https://github.com/dragginzgame/ic-blob-storage/pull/80).
Integrate that owner before adopting this snapshot. Its Linux and both native
macOS jobs retain the former example-installation proof
([#280 — Retire frozen Blob example assessment after native owner qualification](https://github.com/dragginzgame/toko-tooling/issues/280)).

It checks Cargo receipt package/registry/version/target/profile identity, offline
reuse, missing-target refusal, concurrent offline installation and preservation
of the executable and receipts after an injected compiler failure. It records
local executable digests and rejects changed bytes using the shared checksum
owner. Those digests detect changes to an observed build; they are not publisher
signatures, and a Cargo receipt alone does not authenticate executable bytes.
For the selected `--debug` command, receipt admission accepts Cargo's `dev` and
`debug` spellings and rejects release profiles; original receipts and toolchain
identity remain in the evidence root.

The manually triggered **Cargo installation qualification** workflow runs this
assessment on Linux and both macOS architectures with GitHub Actions' default
duration limits and failure evidence collection. It does not add registry builds
to the default portable gate. Native results, consumer-specific versions and an actual shared
installer's path/receipt/lock refusal still need qualification before extraction
under [#65](https://github.com/dragginzgame/toko-tooling/issues/65). The current
shared Rust installer remains the supported setup contract.

## Bootstrap prerequisites

Use the host package manager for the shell, Git, GNU Make, curl, archive tools,
Perl and ordinary utilities. For Linux Mint/Ubuntu:

```bash
sudo apt-get update
sudo apt-get install -y bash git make curl ca-certificates tar gzip xz-utils zip unzip perl
```

On macOS, with Xcode Command Line Tools and Homebrew already installed:

```bash
brew install make curl xz
```

macOS supplies Bash, Git (through Command Line Tools), tar, gzip, Perl and shasum.
Homebrew GNU Make is available as `gmake`; use it where the system Make does not
meet a consumer's requirements. These system packages follow the host's package
manager updates; they are not claimed to be checksum-pinned shared binaries.
Shared setup never invokes sudo or installs a package manager implicitly.
The pinned local host set supplies ripgrep and cloc; neither is a bootstrap dependency.

### Toko Tooling's own compiler

Shared pins its development and Cargo-tool-build compiler in its own root
`rust-toolchain.toml`. With Rustup and native build prerequisites available,
prepare the host parser tools, then the selected compiler:

```bash
make install-host-tools
export PATH="$PWD/.tools/host/bin:$PATH"
bash scripts/dev/prepare-rust-toolchain.sh --toolchain-file rust-toolchain.toml
```

Then run `make install-tools` and `make tools-check`. CI prepares this same file
before computing Cargo build-cache identity or qualifying registry builds. The
runtime scanner uses that same prepared compiler; it needs no older-toolchain
installation. Consumers adopt the Rust 1.99.1 support policy explicitly in their
manifests, compiler selection and validation; exporting a snapshot alone does
not edit those files or qualify their builds.
After changing the pin or the shared build-helper policy, rerun explicit setup;
current requirements and required evidence remain protected under the
[retention policy](tool-store-maintenance.md).

### Portable suite prerequisites

Every repository prepares its declared Rust/Cargo toolchain and native build
prerequisites before the common tool setup. Rust development and Toko Tooling's
portable fixtures also need rustfmt. After that bootstrap, use the common setup
and select its paths before invoking scripts directly:

```bash
make install-tools
make tools-check
export PATH="$PWD/.tools/host/bin:$PWD/.tools/rust/common/bin:$PATH"
```

Before starting portable fixtures, `test-portable-tools.sh` checks the required
commands on PATH (including cloc, shasum, jq, Mike Farah yq and ripgrep), the editor
inputs described [above](#toko-toolings-integration-editor), and reuses
the offline formatter prerequisite check. With those inputs supplied, run this
admission independently with `bash scripts/ci/check-portable-prerequisites.sh`.
It reports missing commands together and points back here; it never installs
tools or replaces the individual
fixtures' version, feature and behavior checks. Standard Unix utilities from the
bootstrap environment are still required. This is Toko Tooling's own suite
setup, not a new prerequisite gate for every consumer.
The download retry fixture starts a temporary IPv4 loopback HTTP listener and
uses real curl with test-only transport substitution. It needs permission to bind
`127.0.0.1`, but contacts no public server and adds no TLS/certificate prerequisite.

ShellCheck, actionlint and Gitleaks use the existing explicit CI installers and
pins; GitHub maintenance needs an installed, authenticated `gh`. Consumer-owned
Node/Rust toolchains, SDKs and product dependencies remain part of that repo's
declared setup. See the [complete script dependency table](supported-hosts.md#tool-specific-dependencies).

## Observed common tool versions

After explicit preparation, run `bash scripts/ci/report-tool-versions.sh "$PWD"`
from an adopted snapshot. The reporter checks host and Rust sets through their
installers' read-only `--check` interfaces, then records
catalog-selected command paths, SHA-256 identities and live version output.
An optional `VERSIONS` argument selects the host/Rust catalog. Supplying a
third `IC_PINS` argument explicitly includes IC admission and observations. It never
installs tools; use the same `TOKO_TOOLING_STORE` setting as setup and checks.
Redirect stdout and stderr together when retaining evidence. Failure keeps prior
observations and the failing command's status. Compiler and product-specific CLI
selection/evidence remain consumer-owned.

### Optional IC bundle adoption

This is a breaking setup contract. Consumers needing the IC bundle must register
both ordered targets shown above and publish its PATH explicitly before adopting
the new snapshot. IC-free libraries keep the default common setup. Existing tool
bundles are retained; adoption never deletes installations or changes product pins.
Version reporting defaults to host/Cargo selections. To include an explicitly
selected IC bundle, pass both catalogs:

```bash
bash scripts/ci/report-tool-versions.sh "$PWD" ci/tool-versions.env ci/ic-tools.tsv 'ic-wasm wasm-opt'
```

IC setup/check requires the product's explicit `IC_TOOLS` selection and verifies
its reviewed native-host digests. The complete pin catalog is still validated;
unselected tools need no installation. Product ownership does not weaken admission.