Generated artefacts
Table of Contents
Status: target state. This page describes the framework we are building, not the catalogue as it stands today. Where this page and the current catalogue disagree, the catalogue is what runs.
1. Summary
Anything structural is generated. This document answers the three questions that follow: whether a given artefact is generated, which profile its model binds to, and whether the two have drifted apart.
The drift checks are the framework's sharpest instrument. They are mechanical, they run from outside the work, and they are indifferent to how convincing an agent's reasoning was, which makes them the clearest case of a constraint that binds rather than advises (The Cybernetic Skills Framework).
The variability model owns the profiles and features themselves; this document owns the decision procedure that consumes them.
2. Detail
Figure 1: Generated-ness gates the verbs, the profile names the variability, regeneration proves it.
Codegen is the same architecture applied to code rather than to skills, and it is further along. Its meta-types are typed targets, its eleven named profiles are a closed register, its features are the axes that register is built from, and zero-diff regeneration is a falsifiable predicate. Where this document and the variability model disagree, the variability model wins.
2.1. Why Code Is Generated and the Catalogue Is Not
Regulatory Functions records that this framework departs from MASD over what to do once a schematic and repetitive pattern has been found. MASD generates the instances; the skills catalogue declines to, and computes the pairing at dispatch instead. Read alone, that reads as a rejection of generation. It is not, and this document is the case that shows why.
The divergence turns on the consumer, not on the analysis. A compiler is indifferent to how many files it is handed, so materialising every instance costs nothing and buys locality. An agent is not indifferent, because its catalogue is read at the moment of selection and its size is itself the cost.
Code has a compiler for a consumer. MASD's remedy therefore applies here unchanged, and everything structural is generated. The catalogue has an agent for a consumer, so the same analysis yields the opposite remedy. One method, two consumers, two answers.
2.2. Generated or Hand-written
Ask before touching anything, because the answer decides which verbs are
legal. A codegen model at
projects/ores.<component>/modeling/ores.<component>.<slug>.org, or a
generated-file marker on the artefact, means the artefact is generated.
Hand-editing a generated artefact is not a legal verb, and the dispatcher does not offer it. The edit goes to the model or to the template — see fix the template, never the output.
2.3. Profile Selection
Exact match against the named profiles binds. No exact match means the nearest profile by Hamming distance over the shared feature set, and the diff is one of two things: a gap to close, or a genuinely novel combination worth naming as a new profile.
Never leave an entity with loose knobs and no profile. Unnamed variability is indistinguishable from drift, and an entity nobody has classified is one nobody can tell is broken.
2.4. Drift
Unlike the rest of this page, this section describes what runs today. All three checks exist and all three are enforced in CI.
| Kind | What happened | Guarded by | Enforced |
|---|---|---|---|
| Template drift | A .mustache was edited instead of its literate org source |
template-drift.yml |
Yes, on every push and PR |
| Artefact drift | A generated file was hand-edited, or a model or template changed and the code built from it was never regenerated | check_component_drift.py, run by codegen-drift.yml |
Yes, over the drift-free registry |
| Model drift | An entity names a profile and then declares a feature the profile fixes to another value | check_model_drift.py, run by codegen-drift.yml |
Yes, with named exceptions |
Artefact drift is the one whose second cause is easy to miss. Nobody has to hand-edit anything: change a template, regenerate the components you were thinking about, and every other component built from that template is now behind. Two template changes did exactly that and left 102 generated files behind, both merged green because the check that would have caught them ran nowhere.
Both enforced sets are deliberately partial, and the partiality is what
makes them worth having. check_component_drift.py carries a registry
of components verified to regenerate byte-identical, and a component
joins only once it does; check_model_drift.py carries named
exceptions for bindings that cannot yet be satisfied. A gate that
reports a standing failure teaches people to ignore it, so each check
enforces exactly what is known-clean and fails on anything new. Shrinking
the exception lists is the work; neither list is a place to park a
problem.
These are S3* work: continuous, from outside, and binding (Systems and levels). They are also the most valuable verification available, because they are mechanical and indifferent to how convincing an agent's reasoning was. A drift check does not read the diff and decide whether it is plausible; it regenerates and compares.
2.5. Inventory
Model type, the profile it binds to, and the drift check guarding it.
Not yet written. The registries it would be generated from now exist:
COMPONENTS_UNDER_TEST in component_registry.py names the components
under artefact enforcement, and check_model_drift.py --summary reports
how many models bind to a profile at all. 136 of 245 models carry a
binding, so an inventory written today would be more gap than content.
3. See also
- The Cybernetic Skills Framework — the analysis this page shares with MASD, and the consumer that decides the remedy.
- Skill architecture — the index into the cluster this page belongs to.
- ORE Studio Variability Model — the features and profiles this page consumes.
- Variability Profiles — the closed register a model binds to.
- Verification and evaluation — where drift sits in the ladder.