# Specifications

This directory defines the user-visible contracts for Masterbelt. Implementation packages under `internal/` must implement these specifications, not replace them.

## Specification Boundaries

- `language/`: Masterbelt lexical structure, syntax, semantics, modules, names, types, built-ins, standard library, evaluation, and diagnostics.
- `masterdata/`: master data schema, keys, relations, validation, query behavior, imports, and exports.
- `codegen/`: generation model, runtime requirements, and target-language generation.
- `tooling/`: project configuration, CLI, syntax highlighting, symbol tags, formatter, linter, LSP, and developer experience.
- `compatibility.md`: compatibility, versioning, and deprecation policy.

`masterdata/query` describes user-visible query behavior over master data collections. The expression language used inside queries belongs to `language/evaluation`.

## Dependency Shape

The graph uses one arrow meaning only: `A --> B` means specification `A` depends on terms or behavior defined by specification `B`. It is not a runtime data-flow graph.

```mermaid
flowchart TD
  Syntax[language/syntax] --> Lexical[language/lexical]
  Semantics[language/semantics] --> Syntax
  Modules[language/modules] --> Semantics
  Names[language/names] --> Modules
  Types[language/types] --> Names
  Types --> Builtins[language/builtins]
  Types --> Std[language/std]
  Evaluation[language/evaluation] --> Types
  Diagnostics[language/diagnostics] --> Syntax
  Diagnostics --> Names
  Diagnostics --> Types

  Schema[masterdata/schema] --> Types
  Keys[masterdata/keys] --> Schema
  Relations[masterdata/relations] --> Schema
  Validation[masterdata/validation] --> Schema
  Validation --> Query
  Validation --> Configuration
  Query[masterdata/query] --> Relations
  Query --> Evaluation
  ImportCSV[masterdata/import-csv] --> Schema
  ImportXLSX[masterdata/import-xlsx] --> Schema
  ExportJSON[masterdata/export-json] --> Schema
  ExportMsgpack[masterdata/export-msgpack] --> Schema
  ExportSQLite[masterdata/export-sqlite] --> Schema

  CodegenModel[codegen/model] --> Types
  CodegenModel --> Evaluation
  CodegenModel --> Validation
  Runtime[codegen/runtime] --> CodegenModel
  Go[codegen/golang] --> Runtime
  TypeScript[codegen/typescript] --> Runtime
  CSharp[codegen/csharp] --> Runtime

  Configuration[tooling/configuration] --> Modules
  CLI[tooling/cli] --> Configuration
  Formatter[tooling/formatter] --> Syntax
  Highlighting[tooling/highlighting] --> Syntax
  Tags[tooling/tags] --> Syntax
  Linter[tooling/linter] --> Diagnostics
  LSP[tooling/lsp] --> Syntax
  LSP --> Names
  LSP --> Types
  LSP --> Formatter
  LSP --> Highlighting
  LSP --> Tags
  LSP --> Linter
```

## Authoring Rules

- Specify behavior before implementing it under `internal/`.
- Keep specifications focused on user-visible behavior and compatibility.
- Do not use implementation package names as specification boundaries unless the name is also a user-visible concept.