Physical Space

File morphology
- Protected regions
The folder taxonomy
The physical address
Archetype versus artefact
The Physical Metamodel (PMM)
Projections into physical space
See also

The physical domain is the subset of MASD's problem domain comprised of physical artefacts: the files and directories that live on a filesystem. It is the concrete realisation of the logical space — every physical artefact is a projection of a logical entity through a facet.

Figure 1: Figure 1 (Dogen): key entities in the physical domain. Source: Domain Architecture.

The two primitive artefacts are:

File artefacts — generalisations of regular files as defined by the POSIX specification.
Folder artefacts — generalisations of POSIX directories.

For the formal treatment see Domain Architecture and Models and Transformations.

File morphology

A file artefact is segmented into three parts:

Prologue — boilerplate: decoration (editor modeline, copyright, licence) and any header guard.
Body — the core content, sensitive to structural variability: namespace, type documentation, the type definition itself.
Epilogue — closing segments.

Files are further classified along two axes. By origin: exogenous files are created externally and have irregular inclusion paths, whereas endogenous files are generated by MASD and have regular ones. By mode of production: manual (handwritten), automated (generated), or partially automated (a merge of the two).

Protected regions

A partially automated file needs a concrete mechanism for merging handwritten and generated content within one file, across regeneration. The formal term for this mechanism, standard across MDE tool chains, is a protected region: a designated text region in generated output that the generator will not overwrite. A developer inserts handwritten code inside one; the generator "fills in the gaps" on regeneration, typically regenerating structure and signatures while preserving hand-authored bodies.

Mechanics common to every tool's implementation:

Each region is bounded by comments (or another out-of-band marker) carrying a unique ID string.
Before regenerating, the generator scans the previous generated output for these regions, extracts their content, and reinserts it into the newly generated file.

Different MDE tools use different names for the same concept — XPand, Acceleo, EGL, JET, and MOFScript variously call it a "protected area," "user code block," "user region," or "unprotected block." The known drawback across all of them: preservation is not guaranteed. Because handwritten and generated code are physically interleaved in the same file, an unstable or non-unique region ID can silently lose handwritten content on regeneration.

See Greifenberg et al., A Comparison of Mechanisms for Integrating Handwritten and Generated Code for Object-Oriented Programming Languages (2015) for the formal comparison across mechanisms and tools this section summarises.

Files relate to one another: "a file A₁ is related to another file A₂ if the content of A₁ has a functional dependency on A₂" — that is, A₁ references A₂. A relation is constant if it always holds (insensitive to variability) or variable if it depends on structural or non-structural variability.

The folder taxonomy

Folder artefacts form a containment taxonomy. From the outside in:

A component is divided into one or more parts; a component with a single part may omit the part folder.
A part is a container grouping related file artefacts — for C++, the canonical parts are include (public headers) and src (implementation).
A facet is a container for a set of related file artefacts that all belong to the same technical space; it is the mechanism that implements the composition of trivial structural functions.
A module is the physical representation of the programming-language concept of package or namespace.

Figure 2: Figure 15 (Dogen): a simplified part taxonomy. Source: Domain Architecture.

The physical address

Every artefact occupies a point in physical space, written as a four-segment address:

[technical space].[part].[facet].[archetype]

For example:

cpp.include.types.class_header — a C++ class header.
cpp.src.types.class_implementation — its implementation.
csharp.main.types.class — a C# class definition.

A prefix of an address denotes a region: cpp is all C++ content; cpp.include is everything under the C++ include part. The address of an artefact is determined by its containment in the PMM (TS → part → facet → archetype).

Figure 3: Figure 33 (Dogen): notation for points in physical and logical space. Source: Domain Architecture.

Archetype versus artefact

These two are easily confused:

An archetype is a generating function and the abstract template for a class of artefacts — a region of physical space. Each archetype produces exactly one output file per logical entity, and is parameterised by the logical model (entity name, fields, namespace, containment).
An artefact is an instance: a concrete, classified file produced by an archetype for a specific entity.

The Physical Metamodel (PMM)

The Physical Metamodel encodes the full TS→Part→Facet→Archetype geometry as a queryable structure. The generator consults it at runtime to answer questions such as "which facets are defined for the C++ TS?" or "how many archetypes does the types facet contain?".

The PMM sits in a four-level metamodelling hierarchy:

Level	Content
M3	Metametamodel — the `archetypes` (file/folder archetypes)
M2	The PMM — instantiates archetypes into a model
M1	The physical model — artefact instances
M0	The filesystem — actual files and directories

Projections into physical space

A projection transforms a logical entity into its physical artefacts. The transformation is ultimately a Model-to-Text (M2T) operation: the logical model is the input; the rendered archetypes are the output. The same logical entity projects into multiple technical spaces and into multiple facets within each, so a single change to the logical entity propagates across all its artefacts on regeneration. See Logical Space for the originating side of the projection.