Design: Gadmaz core model (Entity/Zuordnung) -- bootstrap vocabulary, contract instances, lifecycle #13

New issue

Open

opened 2026-09-23 06:54:44 +02:00 by michael · 0 comments

michael commented

2026-09-23 06:54:44 +02:00

Owner

Goal

Track follow-up design work on the Gadmaz core storage contract. This
issue does not propose a schema version yet -- it records where a
long design session landed and names the concrete next questions.

Full session record (decisions, insights, open questions, with
reasoning): .anagild/sessions/1f8fe794-81bd-4dce-8f89-3f299c9239c8.finding
(session_insight/v1). This issue tracks the open_question entries
from that file that need dedicated follow-up work; it does not
duplicate the reasoning already captured there.

Where the session landed (accepted)

Gadmaz's core storage contract is exactly two structures:
ENTITY(UUID, Value) and ZUORDNUNG(Primary UUID, Type UUID, Secondary UUID), all three ZUORDNUNG positions referencing
Entities.
Tested against DAW/daw-category-standard, DAW/daw-product-schema
and the Anagild entry/relation_entry model: none of them requires a
third structural primitive. Categories, types, contracts, and
relations-with-properties all reduce to Entities connected by
ordinary Zuordnungen.
Reification rule: a Zuordnung represents a fact, not its occurrence
in a source. Only when the fact's assertion, provenance, validity,
priority, or rating must itself be described does that describable
thing become its own Entity.
Cardinality (UNIQUE/MULTIPLE/...) is not a property of a Type; it
is declared per contract usage (a slot/Verwendung within a
Vertrag). A well-known verwendet Zuordnung-type marks which facts
a concrete contract instance relies on, so independent contracts
never compete over the same mutable state and never need to agree
on cardinality for a shared Type.
Storage backend (LMDB, SQL, ...) is explicitly out of scope for the
Gadmaz contract: Gadmaz defines what is stored, not how.

Open questions to resolve here

Bootstrap root set: the minimal set of well-known Entity
UUIDs needed to bootstrap self-discovery of the rest of the
system vocabulary (candidate: UUID(system),
UUID(systemrelevant)), and how well-known UUIDs beyond that
root are defined, versioned, and distributed across
independent Gadmaz instances without becoming a rigid global
schema. Generalizes daw-category-standard's system=true /
seed-file mechanism beyond categories.
Vertrag vs. Vertragsinstanz: the precise relationship
between a contract (describing required/allowed relationship
patterns) and a concrete instance of it (the dataset marking
which existing facts it uses via verwendet), including how
slots/Verwendungen and their cardinality are described.
Lifecycle/deletion: garbage-collection/tombstone semantics
are explicitly not part of the Gadmaz core ("no Zuordnungen
point here" is not a sufficient deletion rule, since edge
types differ in lifecycle significance). Needs rules defined
outside the core, per relevant edge-type, likely at the
contract level.

Explicit non-goals for this issue

No gadmaz_core/v1 schema version yet.
No storage backend decision.
No implementation in any consuming repo.

DAW/daw-modul-berhtjan-core#12 (contribution.json / label model,
touches the same Entity/Zuordnung question from the module side)
DAW/daw-modul-berhtjan-core#15 (authorization filtering; the
personalization/view-engine question from the same session is
recorded in the finding file above, not yet assigned an owner)

## Goal Track follow-up design work on the Gadmaz core storage contract. This issue does not propose a schema version yet -- it records where a long design session landed and names the concrete next questions. Full session record (decisions, insights, open questions, with reasoning): .anagild/sessions/1f8fe794-81bd-4dce-8f89-3f299c9239c8.finding (session_insight/v1). This issue tracks the open_question entries from that file that need dedicated follow-up work; it does not duplicate the reasoning already captured there. ## Where the session landed (accepted) - Gadmaz's core storage contract is exactly two structures: `ENTITY(UUID, Value)` and `ZUORDNUNG(Primary UUID, Type UUID, Secondary UUID)`, all three ZUORDNUNG positions referencing Entities. - Tested against DAW/daw-category-standard, DAW/daw-product-schema and the Anagild entry/relation_entry model: none of them requires a third structural primitive. Categories, types, contracts, and relations-with-properties all reduce to Entities connected by ordinary Zuordnungen. - Reification rule: a Zuordnung represents a fact, not its occurrence in a source. Only when the fact's assertion, provenance, validity, priority, or rating must itself be described does that describable thing become its own Entity. - Cardinality (UNIQUE/MULTIPLE/...) is not a property of a Type; it is declared per contract usage (a slot/Verwendung within a Vertrag). A well-known `verwendet` Zuordnung-type marks which facts a concrete contract instance relies on, so independent contracts never compete over the same mutable state and never need to agree on cardinality for a shared Type. - Storage backend (LMDB, SQL, ...) is explicitly out of scope for the Gadmaz contract: Gadmaz defines what is stored, not how. ## Open questions to resolve here - [ ] **Bootstrap root set**: the minimal set of well-known Entity UUIDs needed to bootstrap self-discovery of the rest of the system vocabulary (candidate: UUID(system), UUID(systemrelevant)), and how well-known UUIDs beyond that root are defined, versioned, and distributed across independent Gadmaz instances without becoming a rigid global schema. Generalizes daw-category-standard's system=true / seed-file mechanism beyond categories. - [ ] **Vertrag vs. Vertragsinstanz**: the precise relationship between a contract (describing required/allowed relationship patterns) and a concrete instance of it (the dataset marking which existing facts it uses via `verwendet`), including how slots/Verwendungen and their cardinality are described. - [ ] **Lifecycle/deletion**: garbage-collection/tombstone semantics are explicitly not part of the Gadmaz core ("no Zuordnungen point here" is not a sufficient deletion rule, since edge types differ in lifecycle significance). Needs rules defined outside the core, per relevant edge-type, likely at the contract level. ## Explicit non-goals for this issue - No `gadmaz_core/v1` schema version yet. - No storage backend decision. - No implementation in any consuming repo. ## Related DAW/daw-modul-berhtjan-core#12 (contribution.json / label model, touches the same Entity/Zuordnung question from the module side) DAW/daw-modul-berhtjan-core#15 (authorization filtering; the personalization/view-engine question from the same session is recorded in the finding file above, not yet assigned an owner)

michael added the

coordination/cross-repo

labels

2026-09-23 06:54:44 +02:00