You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Follow-up to #340, which covers one instance. This is the frame it came out of.
EdgeType declares 24 relations across three layers. That is not an enum, it is a modelling language — the vocabulary every consumer of the graph reasons in, and the thing that decides what questions can be asked at all.
Keet's The What and How of Modelling Information and Knowledge (2023), ch. 7.3, sets out a procedure for designing one (adapted from Frank's waterfall by Fillottrani & Keet 2020). Its step 3 is "ontological commitments", with the observation that matters here:
Ontological commitments are embedded in each language, even if you thought not.
Ours were made implicitly, by adding relations as extractors needed them. That is the normal way these grow and it is not a criticism of any single addition. But the result is a vocabulary whose relations have no declared properties, and several places where the same fact is expressible two ways or where a name promises more than the artefact delivers.
Instances found so far
1. CONTAINS / DECLARES — one relation split by the type of the child node. Tracked separately in #340.
2. DEPENDS_ON beside CALLS, USES, REFERENCES, IMPORTS — five behavioural relations with no declared relationship between them. Is DEPENDS_ON the transitive closure of the others? Their union? A distinct fact an extractor emits directly? A consumer cannot tell from the vocabulary, and docs/architecture/ONTOLOGY.md does not say. Whichever it is, cgis_analyze_impact and the drift gate are computing over it.
3. L3 is called "the OWL-Lite Layer" in core/models.py while carrying no OWL semantics — no axioms, no reasoner, no consistency checking, no entailment. The name sets an expectation the layer does not meet, and someone arriving with OWL in mind will look for machinery that is not there. Either the semantics or the name should move. (Naming an artefact for what it actually provides is cheap and pays for itself; we do the same thing elsewhere when a format is honest about what it lacks.)
4. No relation declares its properties. Nothing anywhere states that structural containment is transitive and asymmetric, that EXTENDS is transitive and asymmetric, that CALLS is neither, that DOMAIN_DEPENDS_ON is derived rather than observed. Traversals encode those assumptions implicitly — cycle-safe walkers, recursive CTEs, BFS propagation — so the assumptions exist and are load-bearing; they are simply not written down where they could be checked.
What would actually be worth doing
Not adopting RDF/OWL. The SQLite backend with recursive CTEs is a stated advantage of this project and swapping it for a triple store to gain formal tidiness would trade something that works for something that is correctly named.
The cheap and useful version is a relation properties table in docs/architecture/ONTOLOGY.md: for each edge type, whether it is transitive, symmetric/asymmetric, reflexive/irreflexive, and whether it is observed by an extractor or derived by the resolver. That alone would:
turn the assumptions the traversals already make into statements someone can check;
let cgis_validate report violations (a cycle in an asymmetric relation is an integrity finding, not a hazard to survive);
give agents consuming the graph a reason to trust a transitive query rather than an implementation detail to rely on.
A second, larger step would be running Keet's seven-step procedure over the vocabulary properly — scope, requirements, ontological analysis, specification. Worth it only if the vocabulary is expected to keep growing, which given the language-extractor roadmap it probably is.
Not urgent
Nothing here is broken. Everything the graph reports today is correct. This is about whether the vocabulary stays coherent as it grows from 24 relations to 40, and about what a consumer is entitled to assume when they see an edge type they have not met before.
Follow-up to #340, which covers one instance. This is the frame it came out of.
EdgeTypedeclares 24 relations across three layers. That is not an enum, it is a modelling language — the vocabulary every consumer of the graph reasons in, and the thing that decides what questions can be asked at all.Keet's The What and How of Modelling Information and Knowledge (2023), ch. 7.3, sets out a procedure for designing one (adapted from Frank's waterfall by Fillottrani & Keet 2020). Its step 3 is "ontological commitments", with the observation that matters here:
Ours were made implicitly, by adding relations as extractors needed them. That is the normal way these grow and it is not a criticism of any single addition. But the result is a vocabulary whose relations have no declared properties, and several places where the same fact is expressible two ways or where a name promises more than the artefact delivers.
Instances found so far
1.
CONTAINS/DECLARES— one relation split by the type of the child node. Tracked separately in #340.2.
DEPENDS_ONbesideCALLS,USES,REFERENCES,IMPORTS— five behavioural relations with no declared relationship between them. IsDEPENDS_ONthe transitive closure of the others? Their union? A distinct fact an extractor emits directly? A consumer cannot tell from the vocabulary, anddocs/architecture/ONTOLOGY.mddoes not say. Whichever it is,cgis_analyze_impactand the drift gate are computing over it.3. L3 is called "the OWL-Lite Layer" in
core/models.pywhile carrying no OWL semantics — no axioms, no reasoner, no consistency checking, no entailment. The name sets an expectation the layer does not meet, and someone arriving with OWL in mind will look for machinery that is not there. Either the semantics or the name should move. (Naming an artefact for what it actually provides is cheap and pays for itself; we do the same thing elsewhere when a format is honest about what it lacks.)4. No relation declares its properties. Nothing anywhere states that structural containment is transitive and asymmetric, that
EXTENDSis transitive and asymmetric, thatCALLSis neither, thatDOMAIN_DEPENDS_ONis derived rather than observed. Traversals encode those assumptions implicitly — cycle-safe walkers, recursive CTEs, BFS propagation — so the assumptions exist and are load-bearing; they are simply not written down where they could be checked.What would actually be worth doing
Not adopting RDF/OWL. The SQLite backend with recursive CTEs is a stated advantage of this project and swapping it for a triple store to gain formal tidiness would trade something that works for something that is correctly named.
The cheap and useful version is a relation properties table in
docs/architecture/ONTOLOGY.md: for each edge type, whether it is transitive, symmetric/asymmetric, reflexive/irreflexive, and whether it is observed by an extractor or derived by the resolver. That alone would:cgis_validatereport violations (a cycle in an asymmetric relation is an integrity finding, not a hazard to survive);A second, larger step would be running Keet's seven-step procedure over the vocabulary properly — scope, requirements, ontological analysis, specification. Worth it only if the vocabulary is expected to keep growing, which given the language-extractor roadmap it probably is.
Not urgent
Nothing here is broken. Everything the graph reports today is correct. This is about whether the vocabulary stays coherent as it grows from 24 relations to 40, and about what a consumer is entitled to assume when they see an edge type they have not met before.