@jhlagado/azm 0.2.8 → 0.2.10

package/docs/codebase/04-ops-and-register-contracts.md

@@ -0,0 +1,237 @@
+---
+layout: default
+title: 'Chapter 4 - Ops and Register Contracts'
+parent: 'AZM Engineering Manual'
+nav_order: 4
+---
+
+[<- Assembly and Z80 Emission](03-assembly-and-z80-emission.md) | [Interfaces and Output Artifacts ->](05-interfaces-and-output-artifacts.md)
+
+# Chapter 4 - Ops and Register Contracts
+
+Ops and register contracts are the two AZM-specific subsystems that sit above plain
+Z80 instruction assembly. Ops expand source into visible inline assembly.
+Register contract analysis checks the resulting routines and calls.
+
+These features belong together in the codebase tour because they meet at the
+same boundary: parsed source items. Ops produce source items. Register contract analysis
+reads source items.
+
+## Ops as Visible Expansion
+
+Ops are named inline instruction idioms. They let source define a small
+operation once and expand it visibly at each use site. The implementation lives
+in `src/expansion/`. `op-expansion.ts` coordinates the subsystem. Operand
+splitting, overload selection, selected expansion, instruction instantiation
+and local-label rewriting live in focused helper modules.
+
+An op is closer to a typed inline template than to a text macro. The op parser
+understands operands, chooses an overload and parses the expanded body back
+through the normal AZM parser. The result is visible assembly with the same
+diagnostic and register contract behaviour as handwritten source.
+
+For example:
+
+```asm
+op clear(reg8 r)
+        xor     r
+end
+
+        clear a
+```
+
+The expansion stage matches `a` as a register operand, substitutes it into the
+template and emits the source item for `xor a`. Address planning and emission
+then treat that instruction exactly like a line written directly in the source.
+
+## Op Collection and Invocation
+
+`collectOps()` scans logical lines before normal parsing. It finds top-level
+`op` blocks, parses their parameter lists, records the body template and marks
+the source lines that belong to the definition body.
+
+An op declaration has:
+
+- a name
+- a parameter list
+- matcher information for overload selection
+- a body template
+- source location metadata for diagnostics
+
+The registry is complete before invocation parsing starts. `parseOpInvocation()`
+checks whether a source line could be an op call. If the name matches a
+collected op, `expandOpInvocation()` selects an overload and instantiates the
+body.
+
+The parser handles op invocations before `parseLogicalLine()`. An op head can
+look like an instruction head at the source level. The expansion stage resolves
+it before ordinary line parsing.
+
+## Overloads and Templates
+
+Ops support overloads. `op-selection.ts` compares invocation operands against
+each candidate signature. It prefers the most specific matching overload and
+emits diagnostics for arity errors, unsupported operands, ambiguous matches and
+invalid expansions.
+
+The matcher vocabulary recognises fixed tokens, registers, register pairs,
+immediates, conditions, ports and indexed operands. It stays close to the Z80
+operand model, so op dispatch and instruction parsing describe operands in the
+same terms.
+
+An op body template is parsed into template items. During expansion, operands
+from the call site are substituted into the template by
+`op-instruction-instantiation.ts`. The result is formatted as ordinary source
+text and parsed through the same line parser used for top-level source.
+
+Local label rewriting lives in `op-local-labels.ts`. A local label in an op
+expansion becomes unique at the use site so each expansion receives its own
+generated label. Once the rewritten labels become source items, address planning
+defines and resolves them through the ordinary symbol path.
+
+## Op Diagnostics and Register Contracts
+
+Op diagnostics point at the call site while explaining the definition that
+matched or failed. Invalid expanded instructions are reported as op expansion
+failures with the underlying Z80 parser diagnostic included.
+
+Ops expand before register contract analysis builds routines. AZM sees the
+expanded instructions. An op is visible inline assembly, so its register effects
+belong to the caller.
+
+## Register Contract Analysis
+
+Register contract analysis checks how routines use Z80 registers. It reads routine
+boundaries, instruction effects and AZMDoc contract comments, then reports
+conflicts where a caller still needs a register value that a callee may change.
+
+The implementation lives in `src/register-contracts/`. The public analysis entry
+point is `analyzeRegisterContracts()` in `src/register-contracts/analyze.ts`.
+
+Register contract analysis is a data-flow analysis over assembled source
+structure. It works with routines, calls, instruction effects and contracts. It
+analyses the source structure to find values live across a call and callee
+summaries that can change those values.
+
+## A Register Contract Conflict
+
+This source shape captures the problem:
+
+```asm
+@Caller:
+        ld      b,8
+Loop:
+        call    Worker
+        djnz    Loop
+        ret
+
+;! clobbers B
+@Worker:
+        ld      b,0
+        ret
+```
+
+`Caller` uses `B` as the `djnz` counter. `Worker` declares that it clobbers
+`B`. Liveness sees that `B` is still needed after the call because `djnz Loop`
+reads it. The register contract conflict is at the call site: `Caller` passes
+through a routine boundary that may change a live unit.
+
+The programmer can preserve `B`, choose a different counter register, change
+`Worker` so it leaves `B` unchanged or update the calling sequence. Register
+contract analysis identifies the conflict and the source location where the
+caller crosses the boundary.
+
+## Routine Model and Contracts
+
+`src/register-contracts/programModel.ts` builds the program model from parsed source
+items. Routine-specific extraction is split into
+`programModel-boundaries.ts` and `programModel-routines.ts`. Together they find
+routine boundaries, direct calls, labels and instructions. Routine entry labels
+use `@` in source and become callable public routine names after the marker is
+removed.
+
+`src/register-contracts/smartComments.ts` reads AZMDoc comments from the comment maps
+captured during loading. Comment-block splitting and token parsing live in
+`smartCommentBlocks.ts` and `smartCommentParsing.ts`. External `.asmi`
+contracts are parsed in `interfaceContracts.ts`.
+
+Contracts can describe:
+
+- inputs
+- outputs
+- clobbered registers
+- preserved registers
+- expected outputs at call sites
+
+Source comments and external interfaces describe the same kind of fact: a
+routine contract. Source comments attach to routines in the current program.
+`.asmi` entries attach to routines whose source is assembled elsewhere.
+
+## Effects, Summaries and Liveness
+
+Register contract analysis depends on `src/z80/effects.ts`. Effects describe which registers
+and flags an instruction reads, writes or preserves. `instruction-head.ts`,
+`instruction-operands.ts`, `instruction-predicates.ts` and
+`operand-register-name.ts` translate between Z80 instruction shapes and
+register contract units such as `A`, `HL`, `carry` and register pairs.
+
+`src/register-contracts/summary.ts` infers a summary for a single routine. Boundary,
+contract, result, state and token-transfer logic now lives in
+`summary-boundary.ts`, `summary-contract.ts`, `summary-result.ts`,
+`summary-state.ts` and `summary-token-transfer.ts`. `routine-summaries.ts` and
+`summaries.ts` combine routine summaries, external contracts and profile
+summaries into lookup tables. A summary records the observable contract of a
+routine: the units it reads, writes, preserves, clobbers and returns as outputs.
+
+`src/register-contracts/liveness.ts` performs the caller-side analysis. It works
+backwards through each routine. At a call, it compares the live-after set with
+the callee summary. A live unit that the callee clobbers becomes a conflict. A
+unit produced by the callee and read by the caller becomes an output candidate.
+
+Stack behaviour is part of routine summaries. `summary.ts` tracks push, pop,
+exchange-top and unknown stack effects. `routine-summaries.ts` infers summaries
+to a fixed point so internal routine calls can see optimistic boundary
+summaries before the final pass. Strict mode uses `stackBalanced` and
+`hasUnknownStackEffect` to distinguish balanced stack use from a routine whose
+boundary may leave the stack in an unknown state.
+
+## Reports, Interfaces and Tooling
+
+`report.ts` renders human-readable `.regcontracts.txt` reports and `.asmi` interface
+metadata. `annotate.ts`, `annotations.ts`, `fix.ts` and `sourceText.ts` support
+source updates for generated AZMDoc comments and conservative fixes.
+
+The CLI can request these behaviours through:
+
+- `--reg-report`
+- `--reg-interface`
+- `--contracts`
+- `--fix`
+- `--accept-out`
+
+`src/register-contracts/tooling.ts` exposes editor-friendly diagnostics and code
+actions through `analyzeRegisterContractsForTools()`. Tooling diagnostics carry
+file, line, column, message, fixability and optional text edits. An editor can
+show the same register contract information that the CLI reports while using
+normal editor actions for accepted fixes.
+
+## Changing Ops or Register Contracts
+
+Op changes belong in `src/expansion/`, with tests under
+`test/unit/expansion/` and integration tests for source-level behaviour.
+Register contract changes usually begin in one of these files:
+
+- Routine boundaries and calls: `programModel.ts`
+- AZMDoc parsing: `smartComments.ts`, `smartCommentBlocks.ts`,
+  `smartCommentParsing.ts`, `interfaceContracts.ts`
+- Instruction effects: `z80/effects.ts`, `instruction-head.ts`,
+  `instruction-operands.ts`, `instruction-predicates.ts`
+- Summary inference: `summary.ts`
+- Caller liveness: `liveness.ts`
+- Output text: `report.ts`
+- Source edits: `annotate.ts`, `fix.ts`, `annotations.ts`
+- Tooling surface: `tooling.ts`
+
+Run unit tests under `test/unit/register-contracts/`, integration tests under
+`test/integration/register-contracts/` and CLI tests in
+`test/cli/register_contracts_cli.test.ts`.

package/docs/codebase/05-interfaces-and-output-artifacts.md

@@ -0,0 +1,253 @@
+---
+layout: default
+title: 'Chapter 5 - Interfaces and Output Artifacts'
+parent: 'AZM Engineering Manual'
+nav_order: 5
+---
+
+[<- Ops and Register Contracts](04-ops-and-register-contracts.md) | [Verification and Maintenance ->](06-verification-and-maintenance.md)
+
+# Chapter 5 - Interfaces and Output Artifacts
+
+AZM has three public entry surfaces: the command-line binary, the compile API
+and the tooling API. They all use the same compiler pipeline. Output writers
+then serialize assembled facts for users, Debug80 and package consumers.
+
+This chapter covers the boundary between the compiler and its callers: package
+exports, CLI flow, public TypeScript APIs and artifact shapes.
+
+## Package Exports
+
+`package.json` exposes:
+
+```text
+@jhlagado/azm
+@jhlagado/azm/compile
+@jhlagado/azm/tooling
+@jhlagado/azm/cli
+@jhlagado/azm/package.json
+```
+
+`src/index.ts` re-exports the stable public surface. `src/api-compile.ts` backs
+`@jhlagado/azm/compile`. `src/api-artifacts.ts` isolates assembly artifact
+creation for the compile API. `src/api-register-contracts.ts` isolates register contract
+analysis, interface loading and register contract artifact creation.
+`src/api-tooling.ts` backs `@jhlagado/azm/tooling`. `src/cli.ts` is the
+executable entry.
+
+The root export gives consumers a broad import. The `/compile` path is the
+build-system path. The `/tooling` path is the editor and analysis path. The
+`/cli` path backs the executable entry. The `/package.json` path exposes package
+metadata for tools that need the installed version.
+
+## CLI Flow
+
+The executable path in `package.json` points to `dist/src/cli.js`, compiled from
+`src/cli.ts`. That file calls `runCli(process.argv.slice(2))` and sets the
+process exit code.
+
+`src/cli/run.ts` owns the CLI control flow:
+
+```text
+runCli(argv)
+  parseCliArgs(argv)
+  artifactBase(entryFile, outputType, outputPath)
+  compile(entryFile, buildCompileOptions(parsed, base))
+  sort and print diagnostics
+  writeArtifacts(base, artifacts, outputType)
+  return exit code
+```
+
+The CLI returns `0` for a successful assembly, `1` when diagnostics include an
+error and `2` for argument or unexpected runtime failures. Diagnostics are
+printed to standard error. The primary output path is printed to standard output
+when artifact writing succeeds.
+
+`src/cli/parse-args.ts` parses switches and validates the command shape.
+`src/cli/usage.ts` owns help text. The parser recognises output selection,
+artifact suppression, include paths, source-root, case-style linting, directive
+aliases and register contract options.
+
+`src/cli/write-artifacts.ts` maps parsed options into
+`CompileNextFunctionOptions` and calculates the output stem.
+`src/cli/artifact-files.ts` writes in-memory artifacts to disk. If the user
+supplies `--output build/program.bin`, the primary artifact is written to that
+path and side artifacts use the same base. If the user supplies only
+`program.asm`, AZM writes outputs next to the entry source using the source
+stem.
+
+## Compile API
+
+`src/api-compile.ts` exports:
+
+```ts
+export async function compile(
+  entryFile: string,
+  options: CompileNextFunctionOptions = {},
+  deps: CompileNextDependencies = { formats: defaultFormatWriters },
+): Promise<CompileNextResult>;
+```
+
+The compile API is file-backed. It reads source from disk, expands includes,
+analyses the program, assembles it and returns artifacts in memory.
+
+Important options include:
+
+| Option                                       | Meaning                                 |
+| -------------------------------------------- | --------------------------------------- |
+| `includeDirs`                                | Include search paths.                   |
+| `directiveAliasFiles`                        | Project alias profile files.            |
+| `caseStyle`                                  | Case-style lint mode.                   |
+| `outputType`                                 | Primary output type, `hex` or `bin`.    |
+| `sourceRoot`                                 | Root used for portable D8 map paths.    |
+| `d8mInputs`                                  | Artifact paths recorded in D8 metadata. |
+| `emitBin`, `emitHex`, `emitD8m`, `emitAsm80` | Artifact selection.                     |
+| `registerContracts`                          | Register contract mode.                 |
+| `emitRegisterReport`                         | Emit `.regcontracts.txt` artifact.      |
+| `emitRegisterInterface`                      | Emit `.asmi` artifact.                  |
+| `emitRegisterAnnotations`                    | Emit source annotation artifact.        |
+| `fixRegisterContracts`                       | Apply conservative source fixes.        |
+| `acceptRegisterOutputCandidates`             | Promote selected output candidates.     |
+| `registerContractsProfile`                   | Built-in external contract profile.     |
+| `registerContractsInterfaces`                | External `.asmi` contract files.        |
+| `skipAssembly`                               | Run loading and analysis only.          |
+
+`compile()` returns:
+
+```ts
+export interface CompileNextResult {
+  readonly diagnostics: readonly Diagnostic[];
+  readonly artifacts: readonly Artifact[];
+}
+```
+
+Diagnostics describe every warning or error observed during loading, analysis,
+register contract analysis, assembly or artifact creation. Artifacts contain the
+in-memory outputs requested by options.
+
+The older option names `registerCare`, `registerCareProfile` and
+`registerCareInterfaces` remain as deprecated aliases for package consumers.
+New callers should use the `registerContracts...` names.
+
+## Tooling API
+
+`src/tooling/api.ts` exports `loadProgramNext()` and `analyzeProgramNext()`.
+`src/api-tooling.ts` re-exports those functions with register contract tooling
+helpers.
+
+`loadProgramNext()` returns a loaded program with source items, source texts and
+source line comments. `analyzeProgramNext()` runs semantic checks and returns
+symbols. `analyzeRegisterContractsForTools()` returns register contract
+diagnostics and code actions in a form suitable for editors.
+
+The tooling loader now recognises both `.include` and `.import`. Both directives
+flatten source into one parse stream. `.import` also marks parsed spans with a
+new source ownership unit, while `.include` keeps the surrounding owner's unit.
+Editor features can use `item.span.sourceUnit` and `item.span.sourceRelation`
+to distinguish module-owned declarations from text included into another unit.
+Diagnostics, symbols and source segments continue to use physical source file
+paths, so imported files appear as their own files in editor and Debug80 map
+metadata.
+
+An editor integration usually starts with:
+
+```ts
+const loaded = await loadProgramNext({
+  entryFile: '/project/src/main.asm',
+  includeDirs: ['/project/include'],
+  preloadedText: editorText,
+});
+```
+
+When `loaded.loadedProgram` is present, the editor can call
+`analyzeProgramNext()` for symbols and case-style diagnostics. It can also call
+`analyzeRegisterContractsForTools()` for register contract candidate diagnostics
+and code actions.
+
+## Artifact Types
+
+The output layer uses structured artifact objects from `src/outputs/types.ts`:
+
+- `BinArtifact`
+- `HexArtifact`
+- `D8mArtifact`
+- `Asm80Artifact`
+- `RegisterContractsReportArtifact`
+- `RegisterContractsInterfaceArtifact`
+- `RegisterContractsAnnotationsArtifact`
+
+Each artifact has a `kind` field. Callers can switch on `kind` to find the
+artifact they need:
+
+```ts
+const d8m = result.artifacts.find((artifact) => artifact.kind === 'd8m');
+const bin = result.artifacts.find((artifact) => artifact.kind === 'bin');
+```
+
+This shape keeps the compile API independent from output paths. A caller can
+write artifacts to disk, keep them in memory, send them to another process or
+compare them in a test.
+
+## Byte Maps, BIN and HEX
+
+Assembly produces an `EmittedByteMap`. It represents sparse output: addresses
+map to byte values and source segments describe where those bytes came from.
+
+`src/outputs/range.ts` provides range helpers. `getWrittenSegments()` identifies
+contiguous written address ranges. `getWrittenRange()` returns the overall
+written span.
+
+`src/outputs/write-bin.ts` writes flat binary. It chooses the written range,
+fills gaps as needed and returns a `Uint8Array` artifact.
+`src/outputs/write-hex.ts` wraps `src/outputs/hex.ts`, which writes Intel HEX
+records and checksums.
+
+## D8 Debug Maps
+
+`src/outputs/write-d8.ts` writes Debug80 metadata. It records generator details,
+input artifact paths, source files, source segments, addressable symbols and
+value-only constants.
+
+The writer normalizes source paths through `sourceRoot` when provided. It also
+coalesces source segments and clips them to written ranges so Debug80 receives a
+clean map of source lines to emitted bytes.
+
+The D8 map distinguishes addressable symbols from constants. Labels and
+addressable data carry addresses. Constants carry values. Debug80 can then use
+addressable symbols for breakpoints and display constants as metadata.
+
+## Lowered ASM80 and Register Contract Artifacts
+
+`src/outputs/write-asm80.ts` serializes accepted AZM source items as
+ASM80-compatible `.z80` text. It lowers supported AZM constructs into forms that
+can be compared against ASM80 output. The writer is larger than the other
+writers because it turns structured items back into source text.
+
+Lowered ASM80 output currently rejects programs that use `.import`. Imported
+source units carry visibility semantics that would be misleading if silently
+flattened into compatibility text. The compile API reports `AZMN_ASM80` for
+this output combination while native BIN, HEX and D8 artifacts remain
+supported.
+
+Register contract report, interface and annotation artifacts are created through
+`runRegisterContracts()` in `src/api-register-contracts.ts` and flow through
+the same compile result and CLI write path. The report is human-readable. The `.asmi`
+interface is metadata that can be loaded by later compile runs through
+`--interface`. Annotation artifacts write source files when `--contracts` or
+`--fix` is used.
+
+## Public API Compatibility
+
+The public API is defined by package exports and exported TypeScript types.
+Major-version planning is the point where these shapes can change:
+
+- exported function names
+- option object property names
+- result object shapes
+- artifact kinds
+- diagnostic object shape
+- D8 map type exports
+- register contract tooling result shapes
+
+The type tests are the safety net for this boundary. When a public type changes,
+the change should be intentional and reflected in package documentation.

package/docs/codebase/06-verification-and-maintenance.md

@@ -0,0 +1,202 @@
+---
+layout: default
+title: 'Chapter 6 - Verification and Maintenance'
+parent: 'AZM Engineering Manual'
+nav_order: 6
+---
+
+[<- Interfaces and Output Artifacts](05-interfaces-and-output-artifacts.md) | [Appendices ->](appendices/)
+
+# Chapter 6 - Verification and Maintenance
+
+AZM's verification suite is organised by compiler boundary. A parser change has
+a parser test. A byte-emission change has an encoder or integration test. A
+public API change has a type-surface test. Reading the tests beside the
+implementation is often the fastest way to understand a subsystem.
+
+## Test Directory Map
+
+```text
+test/
+  unit/
+  integration/
+  cli/
+  asm80/
+  differential/
+  fixtures/
+  helpers/
+  types/
+```
+
+Start with the narrowest useful test, then add the integration or CLI coverage
+that proves the user-facing behaviour.
+
+## Unit and Integration Tests
+
+Unit tests live under `test/unit/` and mirror implementation directories:
+
+| Directory                  | Boundary                                                            |
+| -------------------------- | ------------------------------------------------------------------- |
+| `unit/syntax/`             | Line parsing, expression parsing and directive aliases.             |
+| `unit/source/`             | Logical line and comment handling.                                  |
+| `unit/z80/`                | Instruction parsing, diagnostics and encoding.                      |
+| `unit/outputs/`            | Artifact writer behaviour.                                          |
+| `unit/expansion/`          | Op collection and expansion.                                        |
+| `unit/register-contracts/` | Register contract carriers, summaries, liveness, reports and fixes. |
+
+Unit tests are small and direct. A new indexed operand form belongs in
+`test/unit/z80/` before it appears in a full source fixture. The unit test proves
+the instruction parser and encoder agree on that one form.
+
+Integration tests under `test/integration/` assemble real source snippets
+through multiple compiler stages. Layout features, ops and register contracts
+interactions usually need this level of test because the behaviour exists
+between modules rather than inside one helper.
+
+Source-loading and tooling provenance changes belong here as well. The
+`stage-11-tooling-api.test.ts` integration suite covers include and import
+resolution, recursive load failures and the span ownership metadata that tools
+read from parsed items.
+
+## CLI, ASM80 and Differential Tests
+
+`test/cli/` verifies the command-line contract: options, artifact writing,
+failure modes, determinism, case-style linting and register contract switches.
+Users experience the command-line behaviour through argument parsing,
+diagnostics, output paths and exit status.
+
+CLI tests also protect deterministic output. `compareDiagnosticsForCli()` sorts
+diagnostics by file, line, column, severity, code and message. A CLI test can
+catch changes that leave the compiler correct but make terminal output unstable.
+
+`test/asm80/` and `test/differential/` protect compatibility and byte parity.
+These tests compare AZM behaviour against ASM80 expectations, lowered output and
+real-program fixtures. For an assembler, a one-byte difference is a behavioural
+change.
+
+## Fixtures and Helpers
+
+`test/fixtures/` contains small source programs named after the issue or
+behaviour they cover. A good fixture shows the source shape that matters. It
+includes enough context to assemble and diagnose the behaviour, then stops.
+
+`test/helpers/` contains shared helpers for CLI runs, diagnostics, temporary
+source files and acceptance tests. Use helpers for repetitive setup. Keep test
+expectations close to the test itself so failures stay easy to read.
+
+`test/types/` and `test/public_api_surface.test.ts` protect the package export
+surface. Run them whenever changing `src/index.ts`, `src/api-compile.ts`,
+`src/api-tooling.ts`, `src/outputs/types.ts` or `package.json` exports.
+
+## Guardrails
+
+The main package scripts are:
+
+```sh
+npm run build
+npm run typecheck
+npm run lint
+npm run test:azm:alpha
+npm run test:azm:corpus
+npm run next:guardrails:core
+npm run next:guardrails:package
+npm run next:guardrails:quality
+npm run next:guardrails
+npm test
+```
+
+Additional guardrails live under `scripts/ci/` and `scripts/dev/`. They answer
+larger questions: does the alpha lane still pass, does ASM80 parity still hold,
+does the package work after build output is generated, does lowered ASM80 still
+cover the intended source set, do source files remain within the size budget and
+does the corpus still match the accepted compatibility baseline.
+
+Use this map when choosing a verification lane:
+
+| Change                      | Tests                                                                |
+| --------------------------- | -------------------------------------------------------------------- |
+| Parser or expression syntax | `test/unit/syntax/**`, relevant integration tests.                   |
+| Source loading or tooling provenance | `test/integration/stage-11-tooling-api.test.ts`, relevant unit tests in `test/unit/source/**`. |
+| Z80 instruction support     | `test/unit/z80/**`, diagnostic matrices, ASM80 parity when relevant. |
+| Layout semantics            | layout integration tests and output tests.                           |
+| Ops                         | `test/unit/expansion/**`, op integration tests.                      |
+| Register contracts          | register contract unit, integration and CLI tests.                   |
+| CLI options                 | `test/cli/**`.                                                       |
+| Output artifacts            | `test/unit/outputs/**`, CLI artifact tests.                          |
+| Public API                  | type tests, public API surface tests and tooling API tests.          |
+| ASM80 lowering or parity    | `check:asm80-coverage`, `test:ci:asm80-parity`, corpus guardrails.   |
+| Package export surface      | `test:package`, public API surface tests.                            |
+
+For subtle compiler changes, use a narrow test that names the broken layer and
+a broader test that proves the public behaviour. That combination makes failures
+easy to diagnose.
+
+## Maintenance Boundaries
+
+AZM is stable enough that changes should preserve the existing boundaries. A
+maintainer can usually decide where a change belongs before editing code:
+source loading, parsing, expression evaluation, address planning, Z80 encoding,
+op expansion, register contracts, artifact writing, CLI or public API.
+
+Ask what kind of fact the change affects:
+
+- Text and files belong in `node/` and `source/`.
+- Syntax belongs in `syntax/` or the structural parsing section of
+  `core/compile.ts`.
+- Assembler-time facts belong in `assembly/` and `semantics/`.
+- Instruction forms belong in `z80/`.
+- Inline source generation belongs in `expansion/`.
+- Routine contracts and liveness belong in `register-contracts/`.
+- Artifact shape belongs in `outputs/`.
+- User commands belong in `cli/`.
+- Package consumers belong in `api-compile.ts`, `api-tooling.ts` and
+  `index.ts`.
+
+This boundary choice determines the files to read, the tests to write and the
+documentation to update.
+
+## Structured Data and Compatibility
+
+AZM passes structured data between stages. When a later stage needs more
+information, add it to the earlier structured model and carry it forward.
+Source provenance belongs on logical lines and source items. Syntax shape
+belongs in `SourceItem`. Instruction shape belongs in `Z80Instruction`. Layout
+facts belong in layout records and type expressions. Artifact metadata belongs
+in output types.
+
+Directive aliases and ASM80 lowering serve compatibility. Native AZM syntax
+stays clean inside the compiler model when compatibility forms are converted to
+canonical source items early and compatibility output is serialized late.
+
+## Diagnostics and Manual Updates
+
+Diagnostics should name the source location, the failing construct and the
+reason. Parser diagnostics should recover where possible. Assembly diagnostics
+should be deterministic. CLI output should sort diagnostics consistently.
+
+This book should change when:
+
+- a source directory is added, removed or repurposed
+- the compile flow changes
+- public package exports change
+- CLI option groups change
+- output artifact shapes change
+- a major subsystem gains a new responsibility
+- tests or guardrails are reorganised
+
+Small implementation changes usually need test updates. Structural changes need
+tests and manual updates.
+
+## Suggested Change Workflow
+
+1. Identify the boundary.
+2. Read the relevant chapter and appendix entry.
+3. Add or revise the closest test for the behaviour.
+4. Change the implementation.
+5. Run the focused test.
+6. Run the broader guardrail that matches the public behaviour.
+7. Update docs when the contract or architecture changed.
+
+This workflow leaves evidence at the level where future maintainers will look:
+the affected boundary, the public behaviour and the engineering manual when the
+structure changes.