# meta-ast Documentation
This directory contains the implementation-facing technical documentation for
`meta-ast`.
The structure is intentionally traceable: specs -> architecture -> structure ->
ADRs -> roadmap -> validation artifacts, so design decisions are easy to trace
back to requirements and forward to tests.
## Document map
- `ARCHITECTURE.md` - system architecture, component boundaries, runtime flow,
output formats, and the `metacall-deploy` feature layer.
- `STRUCTURE.md` - code structure, data structures, design patterns, module layout,
and implementation order.
- `DEV_CRATE_DECISIONS.md` - crate selection rationale and trade-offs.
- `CI_CD.md` - CI/CD architecture and quality gates.
- `ROADMAP.md` - phase-aligned implementation milestones and measurable exit gates.
## Specs
- `specs/requirements.md` - normative requirements and acceptance criteria.
- `specs/graph-model.md` - symbol graph and datagraph contracts, including
`language_id`, project-root-relative `path`, `snapshot_id`, `file_id`,
`visibility`, and `DataNode` semantics.
- `specs/symbol-extraction.md` - language-pack extraction contracts.
- `specs/traceability.md` - mapping from deliverables to implementation/docs/tests.
## Architecture Decision Records (ADRs)
- `adr/0001-stateful-import-resolver.md` - Stateful import resolver trait seam
- `adr/0002-scope-resolution-heuristics.md` - Scope resolution heuristics
- `adr/0003-unresolved-import-policy.md` - Unresolved import handling policy
- `adr/0004-global-scope-synthetic-symbols.md` - Global scope synthetic symbol generation
## Requests for Comments (RFCs)
- `rfcs/0001-language-loading-model.md` - Language loading model
- `rfcs/0002-error-semantics-and-recovery.md` - Error semantics and recovery
- `rfcs/0003-incremental-parsing-strategy.md` - Incremental parsing strategy
- `rfcs/0004-graph-representation-and-scc.md` - Graph representation and SCC
- `rfcs/0005-output-contract-policy.md` - Output contract policy
- `rfcs/0006-type-inference-scope.md` - Type inference scope
- `rfcs/0007-dgraph-integration-scope.md` - Dgraph integration scope
- `rfcs/0008-graph-module.md` - Graph module design
- `rfcs/0009-cross-file-dependency-mapping.md` - Cross-file dependency mapping
## Scope policy
- **MVP (must ship):** symbol extraction, dependency graph + SCC/Deployment Unit
analysis, cross-platform CI.
- **`metacall-deploy` feature:** Cross-Language Call Site detection, Deploy Manifest
generation, Root Manifest assembly, Mesh Annotation from SCC.
- **Stretch:** intra-procedural dataflow beyond simple def-use, live Dgraph sink,
advanced cross-language type matching, expanded language support.
## Update policy
When implementation changes any public contract (schema, CLI behavior, graph
semantics, language support), update the corresponding file in this directory in
the same pull request.