Maintainer Manual

This is the handoff document for continuing 0x0 without outside help. It

explains what to run, where to make changes, and how to avoid breaking the

self-hosting chain.

First Rule

Never accept a language change only because one path works. A real 0x0 feature

must move through:

source syntax -> compiler source -> OISA -> self-host -> examples/tests -> docs

For runtime/compiler features, also keep the C compatibility path and direct ELF

path honest until a later documented release removes one of them.

Command Map

Daily quick check:

make doctor

Full confidence check:

make maintainer-check

Required before committing any repository change:

make selfhost-guard

Release check and package:

make release

Recover or audit the first trusted compiler from the seed:

make bootstrap-from-seed

Direct script equivalents:

sh tools/doctor.sh quick
sh tools/doctor.sh full
sh tools/doctor.sh release

Create a feature plan:

sh tools/new-feature.sh typed-conditionals

Create an example scaffold:

sh tools/new-example.sh my-example 42

Repository Map

• compiler/main.0x0: the production compiler. Start here for parser, OISA,

validation, and direct ELF backend changes.

• compiler/compat-main.0x0: compatibility compiler source used to build

zero-native, including the optional C and legacy GAS object paths.

• seed/zero.s: stage -1 seed. Treat it as a bootstrap substrate, not language

ownership.

• examples/*.0x0: executable language examples. Add one for every user-visible

feature.

• tests/smoke.sh: end-to-end gate across source compiler, OISA compiler,

generated native compiler, C executable path, direct ELF path, and ELF compiler

artifact.

• tools/doccheck.0x0: executable documentation and source-format policy.
• tools/pkg-lock.0x0: executable package manifest and lockfile policy.
• tools/zero-lsp.py: v0.1.0 editor LSP shim.
• editors/: Neovim, Zed, and Tree-sitter editor support.
• docs/: language, compiler, release, editor, roadmap, and maintenance guides.

Feature Workflow

1. Create a feature plan:

```sh

sh tools/new-feature.sh feature-name

```

2. Write down the smallest vertical slice:

```txt

one source form or builtin

one example

one expected output

one self-hosting effect

```

3. Update compiler/main.0x0 in the smallest place that owns the behavior:

- parser/lexer for source syntax;

- OISA emitter for canonical compiler output;

- C compatibility backend for generated C behavior;

- direct ELF backend for normal native behavior;

- source comments for new invariants.

4. Add or update an example.

5. Update docs:

- docs/language.html for source behavior;

- docs/compiler.html for compiler/backend/runtime behavior;

- docs/packages.html for manifest, lockfile, or dependency behavior;

- docs/editors.html when syntax/LSP/editor behavior changes;

- docs/release.html when release artifacts change.

6. Run:

```sh

make doctor

make selfhost-guard

```

7. Commit only after the self-host guard passes.

Backend Change Workflow

Use this when touching the direct ELF backend or the linkable object backend:

1. Name the ABI or layout invariant before editing code.

2. Update the section comments near the affected backend code.

3. Add an example that reaches the new path through build-elf, build-obj,

or build-linked.

4. Run make selfhost-guard.

5. If the guard fails, reduce to the smallest example before continuing.

6. If generated ELF fails, compare:

```sh

./bin/zero-native elf examples/add.0x0 --out build/native/add.elf.hex

./bin/zero-native build-elf examples/add.0x0 -o build/native/add.elf

./build/native/add.elf

./bin/zero-native build-obj examples/add.0x0 -o build/native/add.obj.o

cc build/native/add.obj.o -o build/native/add.obj

./build/native/add.obj

```

Debugging Failures

stage2.oisa != stage3.oisa

This means the compiler is not at a fixed point.

Check:

• Did compiler/main.0x0 emit nondeterministic text?
• Did annotations/comments accidentally enter emitted OISA?
• Did a helper change source order?
• Did the seed path and OISA path parse different source?

Keep both stage files and inspect the first difference:

cmp -l build/stage2.oisa build/stage3.oisa | head

ELF OISA compiler differs from stage2.oisa

This means zero-oisa-compiler is not equivalent to the stage 2 OISA compiler.

Check:

• value/tag register preservation;
• string/list runtime helpers;
• file read/write behavior;
• function call arity and stack cleanup;
• unsupported builtin used by compiler/main.0x0.

docs-check fails

Fix the source file, not the checker, unless the policy is genuinely wrong.

Every .0x0 file must have top-of-file docs, balanced parentheses, and no raw

tabs or carriage returns. Files under tools/, lib/, and frameworks/ must

document every function.

editor-check fails

Check:

• python3 is available;
• tools/zero-lsp.py --check examples/add.0x0 works;
• tools/zed-extension.sh can generate build/editors/zed-0x0;
• Neovim and Zed support files still exist.

Release Workflow

1. Ensure VERSION is correct.

2. If the trusted release compiler already exists, run:

```sh

make release

make release-verify

```

make release uses TRUSTED_VERSION=0.1.0 by default. Pass

TRUSTED_VERSION=<version> only when intentionally moving the trusted root.

To recreate v0.1.0 from first principles, run the heavier seed audit path:

```sh

make clean bootstrap-from-seed

```

3. Smoke-test the release OISA compiler:

```sh

build/release/v$(cat VERSION)/bin/zero-oisa-compiler \

examples/add.0x0 \

build/release/v$(cat VERSION)/add.oisa

```

4. Smoke-test the trusted compiler builder:

```sh

build/release/v$(cat VERSION)/bin/zero-elf-compiler \

compiler/main.0x0 \

build/release/v$(cat VERSION)/zero-next

build/release/v$(cat VERSION)/zero-next \

compiler/main.0x0 \

build/release/v$(cat VERSION)/zero-stage2

```

5. Smoke-test the release LSP:

```sh

ZERO_LSP_COMPILER="$PWD/build/release/v$(cat VERSION)/bin/zero-oisa-compiler" \

build/release/v$(cat VERSION)/bin/zero-lsp --check examples/add.0x0

```

6. Archive or tag only after make selfhost-guard and make release-verify

pass.

When To Edit The Seed

Avoid editing seed/zero.s unless one of these is true:

• the compiler cannot run far enough to rebuild itself;
• bootstrap file I/O is broken;
• the OISA evaluator is wrong;
• the seed no longer matches documented bootstrap semantics.

If the change is language behavior, it belongs in compiler/main.0x0, not

the seed.

Maturity Principle

Grow 0x0 by real vertical slices:

small syntax -> compiler support -> runtime/backend support -> tests -> docs

Do not add decorative architecture. Do not promise modules, packages, types,

effects, GC, or object files until the repo has executable semantics and gates

for them.