Merge pull request #7 from CentralInfraCore/feature/5-address-key-fields-formalization

feat: formalize Address key_fields as Shape+Role

Author: sinkog

proposals/atom-grammar/README.md

@@ -220,6 +220,69 @@ Az `opaque` **terminális**: nincs alatta séma-ismert gyermek, és a
 validátor nem lép bele. A `contract` továbbra is alkalmazható rá
 (pl. `pattern` a szerializált alakra), de a belső szerkezetére nem.
 
+### 2.7 Address `key_fields` — formalizálva
+
+A `binding_surface.addresses[].key_fields` a corpuson eddig `{name, type,
+values}` objektumként élt (`compute-resource.yaml:489`, és minden más
+domain-objektum ugyanígy) — nem Shape, nem validált, nincs Contract-algebrája.
+Ez a hiány külön issue-ként lett rögzítve
+(cic-schema-registry-oldalon: `cic-primitives#5`, "Address atom does not
+formalize keyed binding"), miután egy konkrét provider-specializáció
+(`StorageResourceOracleCloud`) megpróbálta kifejezni a `backend`/`provider`
+szűkítését, és nem tudta — nem a specializáció mechanizmusa hiányzott
+(`identity.base` már működik), hanem maga a `key_fields` fogalom nem volt
+Shape-ként deklarálva, amin a szűkítést el lehetett volna végezni.
+
+**A formalizáció**: a `key_fields` minden eleme egy rendes Shape-node,
+`role: key`-vel — ugyanaz a primitívkészlet (Shape/Role/Contract), amit
+minden más mező is használ, nem új mechanizmus. A `schemas/atomic/
+address.yaml` `fields.properties.key_fields` hordozza (`type: list<Shape>`).
+
+```yaml
+binding_surface:
+  addresses:
+    - namespace: "cic:storage"
+      key_fields:
+        - name: backend
+          shape_type: scalar
+          scalar_type: string
+          role: key
+          mandatory: true
+          contract:
+            - type: enum
+              expression: [hypervisor, san, cloud]
+        - name: provider
+          shape_type: scalar
+          scalar_type: string
+          role: key
+          mandatory: true
+        - name: location
+          shape_type: scalar
+          scalar_type: string
+          role: key
+          mandatory: true
+        - name: id
+          shape_type: scalar
+          scalar_type: string
+          role: key
+          mandatory: true
+```
+
+**Miért nem `item_key`.** A §2.3 jegyzete a fordítottját magyarázza (miért
+kapott a Shape-collection összetett kulcsa `item_key` nevet) — ugyanaz a
+válasz erről az oldalról nézve: a `key_fields` egy ENTITÁST azonosít a
+saját Address-én keresztül, az `item_key` egy ELEMET egyetlen entitás
+collection-mezőjén belül. A két fogalom nem esik egybe, csak a nevük
+kollidált volna.
+
+**Grammatikai kezelés** (`check_grammar.py`): a `key_fields` felkerült a
+`NODE_CONTAINERS`-re, tehát minden eleme rendes Shape-node-ként validálódik
+(S2, a JSON Schema réteg). Az `item_fields`-től eltérően — ahol csak
+NÉHÁNY elem kulcs, és az `item_key`/egyetlen-`role:key` levezetés dönti el,
+melyik — a `key_fields` MINDEN eleme kulcs a definíciójából adódóan, tehát
+nincs "levezetés": minden elemnek EXPLICIT `role: key`-t kell hordoznia
+(**C16**), és a hiányzó `role` itt hiba, nem levezethető alapértelmezés.
+
 ---
 
 ## 3. Role — kombinációs algebra (P0.2)
@@ -284,7 +347,7 @@ role:
 | `volatile` **kizárja** a `config`-ot | nem perzisztens értéknek nincs kívánt állapota |
 | `key` **megköveteli** a `config`-ot | a kulcsot a kérő adja meg |
 | `key` **megköveteli** a `mandatory`-t | kulcs nem hiányozhat |
-| `key` **csak** `collection.key_fields`-ben álló mezőn | máshol nincs mit azonosítania |
+| `key` **csak** `item_key`-ben megnevezett/egyetlen-kulcsos `item_fields` mezőn, VAGY egy Address `key_fields` elemén | máshol nincs mit azonosítania. (Ez a sor korábban `collection.key_fields`-et mondott — a §2.3 döntés, ami az `item_key` nevet választotta pont azért, hogy ne ütközzön a §2.7-ben formalizált Address `key_fields`-szel, itt nem lett átvezetve. Javítva, amikor a §2.7 megszületett.) |
 | `key` **kizárja** a `derived`-et és a `volatile`-t | a kulcs a létrehozás után nem változhat |
 | `reference` **megköveteli** a `semantic_type: cic-reference`-t | különben nincs mire mutatnia |
 
@@ -327,6 +390,12 @@ külön dokumentum marad ahelyett, hogy egy nyelv lenne.
 | **C8** | minden listának van kulcsa; összetett kulcsnál `item_key` kötelező, és minden eleme `role: key`-es `item_fields` elem | §2.3 |
 | **C9** | `semantic_type: cic-reference` ⇔ `reference_target` | egyik sem állhat a másik nélkül |
 | **C10** | `reference_target` MUST `{namespace}:{Kind}` alakú legyen, és a `{namespace}` MUST `cic:`-vel kezdődjön | §2.4 |
+| **C16** | Address `key_fields` minden eleme MUST `role: key`-t hordozzon explicit | §2.7 — nincs "levezetés", mert nincs nem-kulcs elem, amitől meg kéne különböztetni |
+
+(C11–C15 a kódban léteznek — `check_role_algebra`/`check_default_against_role`/
+`check_role_against_surface`/`check_duplicate_names` — de sosem kerültek be
+ebbe a táblázatba. Nem ez a szál pótolja őket; a C16-ot azért a valódi
+következő szabad szám alá vettem fel, nem C11 alá, hogy ne ütközzön velük.)
 
 ### Amit szándékosan NEM zárok le
 

proposals/atom-grammar/check_grammar.py

@@ -156,7 +156,22 @@ def expand_role(raw, path: str, out: list[Finding],
 # because they happen to carry `shape_type`. When these members hold a STRING
 # instead of a list they are a reference, and C6/C7 resolve them; the isinstance
 # guard below keeps the two cases apart.
-NODE_CONTAINERS = ("nodes", "fields", "item_fields", "input", "output", "payload")
+#
+# `key_fields` (an Address's key components — README §2.7) is a fourth case
+# added later, not from diffing the walker but from the corpus itself: every
+# `binding_surface.addresses[].key_fields` entry across the live corpus (e.g.
+# `cic-schema-registry` general/storage/storage-resource) is written as
+# `{name, type, values}`, structurally identical to a field descriptor in
+# every way that matters except the member name `type` instead of
+# `shape_type` — a naming accident, not a different kind of thing. Formalizing
+# it here (instead of leaving it corpus-convention-only, as it was) is what
+# lets a Shape/Contract narrowing question about it be asked and checked at
+# all. See §2.7 for why this is NOT the same position as `item_key`/
+# `item_fields`, despite the superficial name collision `key_fields` almost
+# caused (§2.3's note on why the Shape-collection composite key was named
+# `item_key` instead).
+NODE_CONTAINERS = ("nodes", "fields", "item_fields", "input", "output",
+                    "payload", "key_fields")
 
 
 def _node_children(node: dict, here: str):
@@ -205,7 +220,17 @@ def walk_nodes(obj, path: str = "$", in_item_key: frozenset[str] = frozenset(),
                 continue
             for item in entries:
                 if isinstance(item, dict):
-                    yield from _walk_node(item, f"{path}.{key}", in_item_key,
+                    # Every entry of an Address's key_fields is a key
+                    # component by definition — unlike item_fields, which
+                    # holds both key and non-key fields side by side and
+                    # needs item_key/role: key to say which is which,
+                    # key_fields has no non-key entries to distinguish from
+                    # (§2.7). So its own name is always "in the key set"
+                    # here, regardless of whatever in_item_key carried down
+                    # from an enclosing collection.
+                    item_in_key = (frozenset({item.get("name")})
+                                   if key == "key_fields" else in_item_key)
+                    yield from _walk_node(item, f"{path}.{key}", item_in_key,
                                           surface)
         for k, v in obj.items():
             # The containers above are fully handled by _walk_node, and `cases`
@@ -452,7 +477,8 @@ def check_role_algebra(node, role, path, is_key_position, out: list[Finding]) ->
             out.append(Finding(
                 "R-KEY", path,
                 "`role: key` is only meaningful on a field listed in the "
-                "enclosing collection's item_key"))
+                "enclosing collection's item_key, or on an entry of an "
+                "Address's key_fields (§2.7)"))
 
     if "reference" in structural and node.get("semantic_type") != "cic-reference":
         out.append(Finding(
@@ -512,6 +538,39 @@ def check_collection(node, path, out: list[Finding]) -> None:
                 f"`{krole_name}`, not key"))
 
 
+def check_address_key_fields(obj, path: str, out: list[Finding]) -> None:
+    """C16 — every entry of an Address's key_fields carries `role: key` (§2.7).
+
+    Unlike item_fields, key_fields has no non-key entries to tell a key
+    apart from by role — everything in it identifies the entity. So the role
+    is not optional/derivable the way a single-key item_fields list lets it
+    be (§2.3): a key_fields entry that omits `role` would otherwise pass
+    silently, since `expand_role(None, ...)` treats a missing role as a
+    valid empty one, not an error (see check_document). This check is what
+    turns "the field is where a key must be" into "the field also has to
+    say so."
+    """
+    if isinstance(obj, dict):
+        entries = obj.get("key_fields")
+        if isinstance(entries, list):
+            for item in entries:
+                if not isinstance(item, dict):
+                    continue
+                name = item.get("name", "?")
+                if not is_key_role(item.get("role")):
+                    out.append(Finding(
+                        "C16", f"{path}.key_fields.{name}",
+                        f"`{name}` is a key_fields entry but its role is "
+                        f"`{item.get('role')!r}`, not key — every key_fields "
+                        "entry identifies the entity, so none of them are "
+                        "optional about saying so"))
+        for k, v in obj.items():
+            check_address_key_fields(v, f"{path}.{k}", out)
+    elif isinstance(obj, list):
+        for item in obj:
+            check_address_key_fields(item, path, out)
+
+
 def check_reference_target(node, path, out: list[Finding]) -> None:
     """C10 — {namespace}:{Kind}, and the namespace itself carries the cic: prefix."""
     target = node.get("reference_target")
@@ -581,6 +640,7 @@ def check_document(doc, validator) -> list[Finding]:
         check_reference_target(node, path, out)
     check_duplicate_names(doc, "$", out)
     check_shape_references(doc, out)
+    check_address_key_fields(doc, "$", out)
     return out
 
 
@@ -736,6 +796,32 @@ def check_document(doc, validator) -> list[Finding]:
                               "scalar_type": "string", "role": "key",
                               "mandatory": True},
                              {"name": "broken"}]}]}}},
+    "an Address key_fields entry that omits role: key": {
+        "spec": {"binding_surface": {"addresses": [
+            {"namespace": "cic:storage", "key_fields": [
+                {"name": "backend", "shape_type": "scalar",
+                 "scalar_type": "string", "mandatory": True,
+                 "contract": [{"type": "enum",
+                              "expression": ["hypervisor", "san", "cloud"]}]}]}
+        ]}}},
+}
+
+MUST_ACCEPT_DOCS = {
+    "the corpus's real Address key_fields, formalized (§2.7)": {
+        "spec": {"binding_surface": {"addresses": [
+            {"namespace": "cic:storage", "key_fields": [
+                {"name": "backend", "shape_type": "scalar",
+                 "scalar_type": "string", "role": "key", "mandatory": True,
+                 "contract": [{"type": "enum",
+                              "expression": ["hypervisor", "san", "cloud"]}]},
+                {"name": "provider", "shape_type": "scalar",
+                 "scalar_type": "string", "role": "key", "mandatory": True},
+                {"name": "location", "shape_type": "scalar",
+                 "scalar_type": "string", "role": "key", "mandatory": True},
+                {"name": "id", "shape_type": "scalar",
+                 "scalar_type": "string", "role": "key", "mandatory": True},
+            ]}
+        ]}}},
 }
 
 MUST_ACCEPT = {
@@ -814,8 +900,9 @@ def self_test(validator) -> int:
             failures += 1
 
     print("\n--- must be accepted ---")
-    for label, node in MUST_ACCEPT.items():
-        findings = check_document(as_document(node), validator)
+    for label, node in {**{k: as_document(v) for k, v in MUST_ACCEPT.items()},
+                        **MUST_ACCEPT_DOCS}.items():
+        findings = check_document(node, validator)
         if not findings:
             print(f"  \033[92maccepted\033[0m  {label}")
         else:
@@ -824,7 +911,8 @@ def self_test(validator) -> int:
                 print(f)
             failures += 1
 
-    total = len(MUST_REJECT) + len(MUST_REJECT_DOCS) + len(MUST_ACCEPT)
+    total = (len(MUST_REJECT) + len(MUST_REJECT_DOCS)
+             + len(MUST_ACCEPT) + len(MUST_ACCEPT_DOCS))
     print(f"\nself-test: {total - failures}/{total}")
     return 1 if failures else 0
 

schemas/atomic/address.yaml

@@ -66,6 +66,32 @@ spec:
         description: >
           CIC namespace in which this address is interpreted.
           E.g. cic:network, cic:kubernetes, cic:compute
+      key_fields:
+        type: list<Shape>
+        optional: true
+        description: >
+          Ordered list of Shape-typed key components that together identify
+          an entity within this Address's namespace (the corpus convention
+          {backend}:{provider}:{location}:{id}, composed into logical_id as
+          cic:{namespace}:{backend}:{provider}:{location}:{id}). Every entry
+          MUST be a Shape (shape_type: scalar in every corpus occurrence —
+          nothing has needed a composite or collection key component yet)
+          with role: key, per proposals/atom-grammar/README.md §2.7. Formalized
+          here rather than left as a bare {name, type, values} corpus
+          convention, which carried no Shape/Contract typing and so could
+          not be validated at all (cic-schema-registry cic-primitives#5).
+
+          Order matters and is significant: it fixes the position of each
+          component in logical_id and in schema_path/api_path's key
+          expression, the same way a YANG list key's declared order does.
+
+          Distinct from a Shape-collection's own item_key (proposals/
+          atom-grammar/README.md §2.3) despite the near-identical name in
+          the corpus's pre-formalization convention: item_key identifies one
+          ELEMENT within a single entity's own collection-typed field;
+          key_fields identifies the ENTITY itself via its Address. The two
+          were kept apart on purpose when item_key was named, specifically
+          because key_fields was already taken by this field.
       note:
         type: string
         optional: true