The nodes are the specification
The specification is the set of its nodes.
Whatever is generated from them — a readable export (for example, in markdown), the map, the instructions an agent reads — is regenerated after every change to them and never edited, and nothing is ever read back from it into the specification. What is generated from them into the system's code, its types and runtime checks (§s-e877bnfa559tvk9), waits for its nodes instead: it is regenerated only once every node it is generated from is checked, and until then no commit changes it.
Where a generated copy is kept, it is checked against what the nodes produce, unless it waits.
A structure a schema can check is hard for a person to read, so a readable copy is needed; but a copy that is edited, fed back into the nodes or left behind them would be a second version of the rules: sooner or later one version would change and the other not, and whoever read the unchanged one would implement a rule that no longer holds. Regenerated by the tools at every change and checked against the nodes, a copy is a view of the one source rather than a second one.
Code generated from a node is part of the system: regenerated from a node not yet checked, it would implement what the node's owner has not confirmed (§s-utvqbypzhmgndug). Waiting, it lets a change to the node be committed before its confirmation, as a change to any rule is; and since no commit changes it meanwhile, it is still never edited. A copy that waits is left behind its nodes only until every one of them is confirmed, and its lag is reported meanwhile (§s-jau82aq9juv9zzh), so that nobody takes it for current.
The links it makes
The links made to it
The decisions taken on it
- Problem
A changed data record node could not be committed before its confirmation, since its commit passed neither with the generated types left behind it nor with new ones naming an unchecked node, while a rule could; and regenerating code from an unchecked node implemented what its owner had not confirmed.
- Ruling
The owner: code generated from the nodes follows only checked nodes; while one it is generated from is unchecked, it stays as it was and its lag is reported, not refused.
The tests bound to it
- skills/tools/test/unit/generated.test.ts · s-kh8qcd5kxgh9z3j exports every file of the specification to markdown, each node with its sid, text and reason