# The lossless walk

*Building a meta-model · lesson 3 of 6 · ~15 min*

## What you will learn

The traversal contract (ARCH-017): how a model guarantees that any reader can visit every file, know what each one means, and prove nothing was missed.

## Why "read everything" needs a contract

A model is only as trustworthy as a reader's ability to know they have seen all of it. Without a contract, every reader improvises: skims some directories, misses others, guesses at file meanings. Agents are worse: an agent that silently skipped a directory will confidently answer as if it had not. ARCH-017 turns diligence into mechanics.

## The walk declaration

Traversal order is data, declared top-down:

- The repository manifest declares the **ordered list of bundles** (dependency order, foundation first; cycles are non-conforming).
- Each bundle declares its ordered layers; each layer enumerates its content with a **kind** and a one-line meaning.
- Repositories whose filenames carry the kind by convention may instead declare **centralized rules** in the manifest: ordered glob patterns mapping to kinds, first match wins, with a `{prefix}` placeholder so one rule like `kind: "object/{prefix}"` classifies an entire naming convention.

Two walkers given the same repository version must visit the same files in the same order: the canonical walk is deterministic.

## The completeness rule

Every file in the repository falls into exactly one of three classes:

1. **Enumerated**: matched by a declaration or classification rule;
2. **Well-known**: living in a reserved location (canon/, raw/, artifacts/, bootstrap) and inheriting its meaning;
3. **Excluded**: explicitly listed as carrying no model meaning (VCS internals, editor config).

A walker compares the full recursive file listing against the union of the three classes. A file in no class is an **orphan**; a file in two is ambiguous; either is a structural validation failure. Excluding semantic content to pass the check is non-conforming: the exclusion list is a declaration, not a dumping ground.

## Kinds and origins

Every classified file carries a **kind** (what it is *in the model*: object, event, contract, canon, raw, artifact, doc, tool...) and an **origin**: authored, harvested, or generated. Origin decides editability: authored files are edited in place; harvested and generated files never are: the fix belongs at the source or in the generator. This one distinction is what later makes data mastership enforceable.

## What running the walker feels like

Both production models ship a walker (`tools/mu-walk.ps1`) that performs the canonical walk and writes a report into `artifacts/`. From the field:

- Orkestron.AI model: 613 files, 0 orphans. The first run surfaced nothing: a small, disciplined repo.
- DevTeam.Games model: 2613 files on disk, including git-ignored evidence and 146 MB of attached source mirrors. The first run found **47 real orphans**: design prototypes and UI assets nobody had declared, and one record whose kind prefix (`i18n`) broke a naive classification regex. Every orphan became a *rule*, not an exception: the map got truer.
- Both walkers are negative-tested: plant a stray file, the walk fails with exit 1 and names it.

That is the payoff: "nothing lost" stops being a hope and becomes a green check you can demand before trusting a model, and hand over green to the next session.

## Key takeaways

- Order is declared, classification is total, coverage is checked: orphans fail the build.
- Kind says what a file is; origin (authored/harvested/generated) says whether you may edit it.
- Real repos pass: legacy layouts, binary assets and giant mirrors all classify with a handful of rules.

## Go deeper

- [Model traversal and well-known locations (ARCH-017)](/spec/#02-architecture/Model-Traversal-and-Layout.md)
- [Validation levels V0-V5](/spec/#02-architecture/Validation.md)

Next: [Data mastership](04-mastership.md)