[charlielye]

Now that ci3 is shared by more than one repository, consumers need to know what they can rely on. This identifies the public interface by audit and moves everything else under internal/.

Definition

Public is whatever a consuming repository sources or executes, or a person runs by hand. Everything else is internal.

Audit method

For each of the 87 top-level files, across aztec-node and aztec-packages (including .github/ and aztec-packages' ci3-local/), excluding ci3 itself:

• Path-form references (ci3/<name>, $ci3/<name>) in any file.
• Bare-name references in shell-like files only (*.sh, *.yml, Makefiles, extensionless scripts), because ci3 is on PATH and most calls look like denoise "...".
• Markdown was checked separately for tools that are documented rather than scripted.
• References were then read, not just counted: a reference that does nothing does not make a script public, and neither does a mention in a comment. The first pass of this audit matched comment text and had to be corrected for it.

Result

	Count	What happens
Sourced or executed by a consumer	50	stay public
Run by hand (cache_ls, cache_delete, clean_remote_tags, start_interactive)	4	stay public
Documented in a consumer skill (bench_compare)	1	stays public
Used only by other ci3 scripts	17	→ internal/
Referenced by consumers only redundantly	3	→ internal/
Added on main since, used only by ci3 (apply_private_release_patch, from aztec-node#420)	1	→ internal/
Referenced by nothing anywhere	7	→ internal/, removal candidates
Tests never enrolled in the suite	3	→ tests/
Run artifacts committed by accident during this work	2	removed and gitignored

Used only inside ci3: exec_test, filter_cached_test_cmd, get_test_entry, parallelize_strict, sem_sched, semc.c, source_color, source_options, source_stdlib, source_test_params, ssm_send_command, total_mem_gb; and, named in consumer comments but called only from ci3: aws_request_instance_type, log_ci_run, post_github_status, redact, run_test_cmd.

Redundantly referenced: source_redis, source_refname, source_cache. Every consumer reference sat on the line after source ci3/source, which sources all three itself. They are implementation details of that entry point. The consumer PRs drop those lines (ci.sh in both repos, two barretenberg benchmark scripts in aztec-packages), which must land before a consumer bumps its pin to this.

That leaves the sourcing interface as three entry points (source, source_base, source_bootstrap) and two opt-ins (source_npm_auth, source_release_target).

Referenced by nothing (not deleted here; that is a separate call): add_log_time_delta, cpuset_count, docker_has_image, fd_monitor, get_test_owner, source_test, squash_args.

Narrowly used, worth a look later: about 25 public scripts are referenced from three or fewer files. Several have a single caller, e.g. log_ci_run and run_test_cmd (only ci.sh), bench_engine/test_engine/spinner (only the root bootstrap.sh). They are genuinely public today, but are candidates for folding behind fewer entry points.

Mechanics

• internal/ is added to PATH in source_base, so ci3's scripts keep calling each other by name. It is a documented boundary, not an enforced one.
• References rewritten: $ci3/<name> → $ci3/internal/<name>, and self-locating source lines inside internal/ go up one level.
• The three tests now live in tests/, where bootstrap.sh enrolls them. Doing this is what exposed the undefined github_repo_url in upload_benchmarks, fixed separately on main: its test only printed command not found to stderr and passed anyway.

README

Adds an Interface section: the public/internal split; the reverse interface (files ci3 expects from the consuming repository: .test_patterns.yml, scripts/process_flake_log.py, .release-please-manifest.json, build-images/src/home/.gitconfig); and the state that must stay compatible between ci3 versions, since a repository and a submodule of it each pin their own.

Testing

• ci3's suite passes standalone and as a submodule of aztec-node with the working directory inside ci3/: 8 tests, up from 5.
• Smoke test from a consumer: source ci3/source still provides the stdlib functions and colours, and internal commands resolve through PATH to ci3/internal/.
• Not yet run through a consumer's CI. No consumer references anything moved, by construction of the audit, but a pin bump on a consumer PR is the real check.

Rebased on main (2026-10-22)

Rebased onto main after the ports from aztec-node (#304–#544) and the AMI fix. One script was added on main in the meantime, apply_private_release_patch, which only bootstrap_ec2 runs; it moves to internal/ and its call site follows. The suite passes standalone and as a submodule of both consumers (8/8 each), and source ci3/source from a consumer still provides the stdlib, redis and the ref name, with internal commands resolving through PATH. The consumer PRs, aztec-labs-eng/aztec-node#278 and AztecProtocol/aztec-packages#25516, already drop the redundant source_redis/source_refname/source_cache lines.

🤖 Generated with Claude Code