Applied MASD

1. The logical element itself — Logical Space's Structural package: the entity's primary key, natural keys, and columns. This is the entity's shape — its object graph. Adding a column changes it.
2. Authored variability, at element scope — configuration that tunes how the (unchanged) shape above is projected into physical artefacts: naming, chrome, feature toggles. ORE Studio Variability Model catalogues these as authored feature bundles, applying Variability's test for telling this concern apart from the first: a property is variability only if the model author sets it and the generator merely reads it through; if the generator instead computes the value from the object graph (has_tenant_id, is_uuid, and the rest of that document's "Excluded: structural predicates" table), it is a consequence of concern (1), not a configuration choice, however boolean-shaped it looks in the property drawer.
3. Protected regions — Physical Space's partially automated mode of production: hand-written fragments — a bespoke query, a custom NATS message — merged into an otherwise fully generated file. ORE Studio calls its instance of this mechanism a paste block; see the Paste blocks page for the mechanics and its point of divergence from the textbook implementation (model-sourced and stateless, rather than round-tripped from the previous generated output).

None of these three is reducible to either of the others. A column addition (1) cannot be expressed as a variability feature (2) without violating the "variability is non-structural" discipline that makes (2) tractable at all; a custom query body (3) cannot be expressed as either, because no amount of declarative configuration produces arbitrary imperative code. Classical MDE therefore usually keeps them in separate artefacts — a class diagram for (1), a configuration model or profile for (2), round-trip markers scanned from generated output for (3) — synchronised by tooling. ORE Studio instead writes all three into one .org file, in adjacent sections of the same document.

The justification is not that the distinction is false — the taxonomy above is exactly as real in ORE Studio as in any other MASD instantiation, and is the reason ORE Studio Variability Model can state a mechanical test for it at all. The justification is that co-location has a reader, and that reader is not only the generator. A literate document — in Knuth's original sense, prose and machine-consumed structure interleaved for a human audience — lets an engineer (or an LLM) see an entity's shape, its configured behaviour, and the one hand-written exception to its otherwise total regenerability, in a single pass, without cross-referencing a separate configuration file and a separate generated-output diff. ORE Studio Variability Model makes the same trade explicitly for concern (2) alone — "ORE Studio has no intermediate feature graph with inheritance and resolution… this keeps the system simple to maintain and to hand to an LLM, at the cost of the fine-grained, scoped per-feature resolution that a full VMM enables" — and the same calculus applies to bundling concerns (1)-(3) into one file: simplicity and legibility, purchased with the loss of MASD's clean separation of concerns as an enforced property of the toolchain. Nothing today stops an author writing a structural predicate into what should be a Behavioural knob's slot, or vice versa, except the discipline documented on the meta-model pages that describe each facet. The Codegen org-entity meta-model and its segment pages are, in this light, best read as the taxonomy that a formal VMM/LMM split would have enforced structurally, maintained instead as documentation discipline.

The nearest classical-MDE analogue is a UML class stereotyped and tagged with a Profile: the class itself is concern (1); its stereotype's tagged values are concern (2); and — where the tool supports it — a protected region inside the generated class body is concern (3). Seen this way, ORE Studio has not invented a new problem; it has re-solved an old one with different mechanics:

The UML mechanism keeps the three concerns in three places precisely because a diagramming tool, a profile-application mechanism, and a text editor are three different pieces of software with three different strengths; nothing in the concepts forces the separation. Org-mode, being plain text with a lightweight structure a parser can walk, removes the reason to keep them apart: a heading, a property drawer, and a babel block are all the same kind of thing to both a human reader and org_loader.py, so nothing is lost by writing all three concerns as headings in one file. The cost — no tool-enforced boundary between "this is structure" and "this is configuration" — is the same cost UML pays whenever an author puts a modelling decision in the wrong diagram; ORE Studio just pays it in one file instead of three.

An entity is a concept in the logical model — something the domain cares about. Examples: currency, country, book. An entity is what a developer authors in an org-mode model file under modeling/. It is a logical object: it has fields and relationships, but no language, no file, no namespace yet.

Every entity has a metatype — the classification of what kind of entity it is. The metatype is not a property of the entity in the domain sense; it is metadata about the entity that the code generator uses to decide which archetypes to apply.

Examples of metatypes in ORE Studio:

The metatype is distinct from the entity's identity. currency is the entity; domain_entity is its metatype. Saying "currency is a type" is true in the programming-language sense but wrong in the MASD sense — in MASD, currency is an instance of the metatype domain_entity.

A note on UML stereotypes. In UML, a stereotype is the mechanism for attaching metadata to a model element — you annotate an element with <<value>> to indicate it is a value type. In ORE Studio we do not use UML or stereotypes: models are authored in org-mode and metadata is conveyed through the file's frontmatter (#+options, property drawers, and heading keywords). The concept we care about is the metatype; the mechanism we use is org-mode frontmatter. Do not use "stereotype" to mean "metatype" — they refer to different things.

A transform is a model-to-text operation that takes a logical entity and produces physical artefacts. In ORE Studio the transform engine is ores.codegen (projects/ores.codegen). It reads the entity's model file, resolves its metatype, selects the applicable archetypes, and renders each one to a file on disk. The act of running the generator for a given entity and address is one transform execution.

A facet is a named grouping of related archetypes within a technical space. Think of it as a package or namespace in physical space — not a subdivision of the technical space itself, but a classification of artefacts by the role they play for an entity.

Example: the domain facet groups every archetype that contributes to the domain representation of an entity in C++: the struct header, the JSON I/O header, the JSON I/O implementation. The repository facet groups the archetypes for persistence: entity, mapper, repository (header and implementation for each). These are distinct roles, so they are distinct facets.

Facets are defined as nodes in the ores physical-space graph (projects/ores.codegen/library/templates/).

An archetype is a single template within a facet — the generating function for exactly one output file. Each archetype:

• Belongs to exactly one facet.
• Binds to one or more metatypes: it only fires when the entity's metatype matches. The domain::entity_header archetype binds to domain_entity; it does not apply to enumeration or junction.
• Is parameterised by the logical model: the entity's name, fields, namespace, and relationships are substituted at render time.
• Produces one output file — the artefact — per entity it is applied to.

Putting it together with a concrete case:

1. currency is a logical entity with metatype domain_entity.
2. A developer runs compass codegen generate --model ores.refdata.currency.org --address ores.cpp.domain.
3. The transform (ores.codegen) reads the model, confirms the metatype is domain_entity.
4. It resolves the domain facet from the ores.cpp.domain node in the physical-space graph.
5. The domain facet contains three archetypes that bind to domain_entity:
   • domain::entity_header → currency.hpp
   • domain::json_io_header → currency_json_io.hpp
   • domain::json_io_implementation → currency_json_io.cpp
6. The transform renders each archetype against the model, producing three artefacts on disk.

If the metatype were enumeration instead, the domain facet would apply a different (smaller) set of archetypes — only those that bind to enumeration.

An address is the ORE Studio selector: a physical-space path (ores.cpp.domain, ores.cpp, ores.sql.schema, …) that restricts a run to the facets under it. --address ores.cpp activates the domain, generator, repository, service, and protocol facets simultaneously — the whole C++ technical space in one invocation. Address is not a core MASD concept — MASD talks about facet activation through the variability model; ORE Studio surfaces this as the physical-space graph's own node paths, so there is no separate naming scheme to maintain (an entity's ores.* drawer binding and its --address selector are the same address vocabulary).

Terms to avoid and their replacements:

A model type is a tag that classifies each model file and controls which facet's archetypes can apply to it. A facet's model_types list acts as the filter: only a model whose type appears in that list is a valid target for the facet. Model type is derived from the filename suffix (JSON route) or the #+type: frontmatter field (org-mode route):

This filter prevents, for instance, the component scaffold facet from inadvertently running against entity models, and the domain facet from running against SQL-only table models.

Generation is scoped at invocation time via the CLI's --address:

./projects/ores.codegen/codegen.sh generate \
  --component refdata \
  --address ores.cpp.domain

Omitting --address generates the entity's full supported set; giving an address restricts the run to the facets under that physical-space subtree. Component scope is handled by src/codegen/manifest.py: the manifest maps component names to their model discovery roots (models_dir for legacy JSON models; modeling_dir for org-mode model files). It does not assign a default address — that is always either omitted (full supported set) or given explicitly by the developer, a skill, or a compass recipe. Product scope — activation applying across the whole product — is expressed the same way, by a technical-space or root address (ores.cpp, ores), and by skills that bundle common multi-facet invocations into a single command.

The target set \(T\) is what to generate in this particular run. Default: \(T = S_e\), the entity's own supported set. The CLI --address argument overrides \(T\):

# T = S_e — generate everything the entity supports
./projects/ores.codegen/codegen.sh generate --component refdata

# T = all sql archetypes
./projects/ores.codegen/codegen.sh generate --component refdata --address sql

# T = all cpp.qt archetypes
./projects/ores.codegen/codegen.sh generate --component refdata --address cpp.qt

There is no --profile flag; the entity's ores.* binding IS the generation footprint, and --address is a filter on it, never an expansion. What generates for entity \(e\) is \(T \cap S_e\). When \(T \cap S_e = \emptyset\) the run emits a warning ("<entity>: nothing to generate for address <addr>") and continues; an --address value unknown to the facet catalogue is an error.

The TS→facet map lives in each technical space's own * Facets table in the ores physical-space graph — ores.cpp, ores.sql, and the other TS root nodes — which is the sole source of truth for which facets belong to which technical space; it is not reproduced here. All supported/target set logic lives in codegen/physical_space.py — isolated from dispatch code and covered by a dedicated test suite (tests/test_physical_space.py); this is deliberately complex logic and must not be diffused across multiple modules.

Per-facet references: Type definition facet, Entity lifecycle (repository and service), Service application facet, ORE Studio Messaging Reference (protocol), Qt facet.

See SQL facet.

See Build facet, Assets facet, Documentation facet.

These facets are authored rather than generated, and documented for parity: Shell facet, CLI facet, HTTP facet, Wt facet.

The key attributes of a logical element live in the domain facet — regular C++ defining the domain struct. Each element lives on its native component (e.g. account in ores.iam) and is created via the Domain Type Creator skill, which bundles several facets together; other facets refer to the domain type files to extract the information they need.