Product / Language
A declarative specification for structure
You describe the structure a system should have as a declaration rather than a script. That is what makes the same file checkable before a run, comparable against a workspace, and verifiable afterwards.
Declarative model
A specification states what the structure should be, not the steps to build it. There is no ordering to get right and no script to re-run carefully, because the description is not a sequence of actions.
That is what makes the same file usable at every stage: it can be checked before anything runs, compared against a workspace to produce a plan, and compared again afterwards to verify the result.
Core concepts
- Name
- structure.name declares the directory the specification governs. It is resolved relative to where the command runs, and it is the root of everything the engine creates.
- Directories
- structure.directories is a flat list of directory entries beneath that root. Each entry is one node — the unit validation, planning and verification operate on.
- Version and style
- version declares the format the file is written against. style is optional and accepts enterprise, technical or hybrid; both participate in the specification's fingerprint.
- A closed surface
- The current Alpha accepts four root keys — version, structure, style and policy — and rejects anything else. The format is deliberately small, and grows only when the engine implements more.
A specification
The smallest useful specification is a version and a structure.
structure.yaml
version: 1
structure:
name: project
directories:
- src
- data
- docsThis page explains the model rather than enumerating the format. Every accepted key, its allowed values and the rules applied to directory entries are listed in the Specification Reference.
Specification and structure
The specification and the directory hierarchy are two representations of one thing. The specification is the contract; the hierarchy is the state that contract governs.
Structure on disk
- platform/
- core/
- data/
- docs/
structure.yaml
version: 1
structure:
name: platform
directories:
- core
- data
- docsWhy validation is possible
Because the specification is a description rather than a program, it can be examined before it is used. Malformed structure, unreadable definitions and structural problems are found by reading the specification, not by running it and observing what breaks.
Validation therefore happens before planning, and planning before anything reaches the filesystem.