ORE Studio Variability Model

This document is the catalogue: the concrete answer to which features ORE Studio's code generator actually recognises, what each one does, and how the two responsibilities Variability assigns to any VMM instantiation — activation and projection configuration — are discharged here specifically. For the abstract distinction between non-structural variability and structure, and for the mechanical test that tells a genuine feature apart from a value the generator merely computes, see Variability § "Distinguishing a feature from a computed predicate"; that distinction is the single most important discipline this document follows, and is not restated here.

ORE Studio discharges the VMM's two responsibilities as follows:

1. Physical-space activation — enabling and disabling regions of the physical space: which facets (and therefore which templates) are generated for a given model. ORE Studio realises this with the ores physical-space graph (root → technical space → facet → archetype).
2. Projection configuration — tuning how an enabled projection renders a fixed entity: naming, extensions, and feature toggles. ORE Studio realises this with a catalogue of authored features on the model — the ores.sql.schema, ores.cpp.qt and licence features below.

Both responsibilities are authored the same way, mechanically: as key-value pairs in an org-mode property drawer — the :PROPERTIES: ... :END: block org-mode allows immediately under any heading, holding metadata that is distinct from, and never rendered as part of, that heading's own prose body. ORE Studio's entity model files use this mechanism pervasively, and everywhere this document shows a :some_property: value line, it is this mechanism it is pointing at. A model file's top-level heading carries the property drawer that activation reads — its ores.* bindings, introduced below — and each facet-specific section of the same file, its SQL heading, its Qt heading, carries its own property drawer of the projection-configuration features that facet's own templates read. org_loader.py parses these drawers directly when it loads a model; a feature's authored value lives nowhere else in the file, and nowhere else in the toolchain.

Applying the abstract test to a concrete generator requires knowing where to look, and it is worth being precise about that: the operative source is projects/ores.codegen/src/codegen/core.py, org_loader.py, and the library/templates/*.mustache templates themselves. What actually distinguishes a feature from a computed predicate, though, is not which file happens to consult its value — it is the direction the value travels. A feature's value flows from the model's author to the generator unchanged, a plain read-through with no computation in between; a computed predicate's value flows the other way, derived by the generator from other facts the entity already carries, with no human choice involved at all. That distinction does not always show up as a Python accessor a reader can grep for, which is itself worth knowing before hunting for one: several features are never touched by name in core.py or org_loader.py, and are read instead purely by Mustache's own dotted-path section lookup, direct off the parsed model — domain_entity.qt.has_change_reason_cache, for instance, resolves entirely inside the template, with no corresponding Python-side .get() call to find. A computed predicate, by contrast, always shows up as a derivation in the source: table['has_tenant_in_pk'] is set from has_tenant_id together with a check on system_scope, and field['is_uuid'] is set from the column's own declared type — in both cases the generator is computing something from facts the entity already has, not consulting a choice its author made. Predicates of this kind are catalogued separately, under Excluded: structural predicates, precisely so a reader is never tempted to read one of them as configuration.

The pair :has_tenant_id: and :has_workspace_id: (documented on Keys and columns) is the case where this test is easiest to apply wrongly, and working through it in full is instructive precisely because of that. Both properties look exactly like computed predicates at first glance: setting either one causes a real tenant_id=/ =workspace_id column to appear in the generated table, and a reader who equates "produces a column" with "is structural" will file them under Excluded without checking further. That equation is exactly the mistake the abstract test exists to prevent — structure is measured by where a value came from, not by what it goes on to produce. Read against the generator's actual source, both properties are read straight off the model's frontmatter, with nothing more than a default applied (bool(table.get('has_tenant_id', True))); no other fact about the entity feeds into that value. They are therefore genuine, authored features by the test's own definition, however structural their consequence looks, and are documented on Keys and columns rather than under Excluded. The instructive contrast is has_tenant_in_pk, which looks similar on the surface but fails the test in exactly the way has_tenant_id passes it: its value is computed from has_tenant_id together with other already-known facts, never authored directly, and it is correctly excluded as a result.

An entity's ores.* property-drawer bindings are a genuinely authored feature, no different in kind from anything the projection-configuration catalogue below defines — an entity's author declares which technical spaces, facets, or individual archetypes apply to it. Everything about how that declaration is then resolved at build time — CLI address syntax, the target-set/supported-set intersection, model-type filtering, and which facets exist under which technical space — is physical-space addressing mechanism, not itself an authored per-entity choice, and is documented in Applied MASD § "Address resolution: the physical-space graph and element-scope binding".

Once a facet is activated, its projection is tuned by features — authored configuration points the model file sets and the generator reads through. They are grouped into feature bundles, one per facet (plus a cross-facet licence bundle). Each bundle is a cohesive "variability entity": a named set of features that configure one projection, corresponding one-to-one with the facet whose rendering it tunes — the ores.sql.schema bundle below configures exactly what the ores.sql.schema facet produces, and likewise for ores.cpp.qt. The licence bundle is the one exception, and deliberately so: licence decoration is not tied to any single facet's own semantics, so it stays a cross-facet bundle rather than living inside one.

Every feature below passes Variability § "Distinguishing a feature from a computed predicate" — each is read, never computed, in the generator (§ "Telling variability from structure" above names which files), and none of them adds or removes a logical attribute on its own account. Where a feature has a structural consequence (e.g. tenant-scoping changes a column's nullability) it is flagged; those are candidates to migrate into the logical model proper.

Variability defines a profile as "a bundle of configuration points that can be bound to logical elements… named after the ability they confer," composing Base → Component → Element scope. This entity's own ores.* facet address instantiates this at the activation half of the VMM. Profiles instantiate the other half: named bundles of feature values — the ores.sql.schema=/=ores.cpp.qt features above plus Keys and columns's has_tenant_id=/=has_workspace_id — bound at element scope when authoring a new entity.

This supersedes projects/ores.codegen/src/doc_generate.py's ENTITY_ORG_SHAPE_PRESETS (the compass add entity_org --shape presets: simple-text-key, fk-scoped, hierarchical-composite, richest, timeseries). That scheme sampled 5 points from the feature space and named each after whichever reference entity happened to sit there — the samples were never mutually exclusive (a self-referencing hierarchy and CSV/XML export + version navigation can genuinely co-occur; the old scheme just never sampled that combination) and two of the five features it toggled (has_parent_scoping, boolean-shaped has_insert_trigger_validations) turned out not to be real generation-time features at all (§ "Scaffold-only features" above).

Reference material: not part of the argument above, consulted as needed.

• Variability — the MASD variability concept: features, profiles, VMM.
• Facet — the MASD facet concept the profiles activate.
• Applied MASD — address resolution (CLI syntax, target/supported-set intersection, the technical-space-to-facet map) and the full ORE Studio facet catalogue.
• ORE Studio Technical Spaces — TS/Part/Facet/Archetype index.
• C++ Technical Space — C++ profile-to-facet mapping.
• SQL Technical Space — SQL profile-to-facet mapping.
• ores.codegen — the code generator implementing this model.