storage: provider-agnostic StorageBucket domain composition

.github/workflows/gate.yml

@@ -0,0 +1,65 @@
+---
+# The schema gate. Runs the same checks `make validate` runs locally, but
+# without Docker: CI calls `make validate.local`, so the gate has one
+# definition (the Makefile) instead of one there and a copy here.
+#
+# What it proves:
+#   * the atom grammar's self-test still rejects all 19 deliberately broken
+#     fixtures — a gate nobody has shown capable of failing is not a gate
+#   * every live composition satisfies the grammar
+#   * every schema still validates against the meta-schema, and every
+#     DomainComposition against its base aggregate
+#
+# Deliberately NOT here: pledge, release and verify-release. Those need Vault
+# credentials and are a release action, not a gate.
+
+name: gate
+
+on:
+  push:
+    branches: [main, devel]
+  pull_request:
+    branches: [main, devel]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: gate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install pinned dependencies
+        # requirements.txt is the lock file; using it as a constraints file
+        # keeps the pins without installing the linting and mutation-testing
+        # stack a validation run does not need.
+        #
+        # The extras are stripped because pip rejects them in a constraints
+        # file ("Constraints cannot have extras" — coverage[toml] is the one
+        # such line). Stripping keeps every pin; it only drops the optional
+        # dependency groups, which are irrelevant here since these packages
+        # are constraints, not installs.
+        run: |
+          python -m pip install --upgrade pip
+          sed -E 's/\[[^]]*\]//' requirements.txt > /tmp/gate-constraints.txt
+          pip install -c /tmp/gate-constraints.txt pyyaml jsonschema semver requests
+        # `requests` is not used by the validate path, but compiler.py imports
+        # it at module level (line 7) alongside semver, so the module will not
+        # load without it. Listed here rather than made lazy, because changing
+        # the import structure of the release tooling is not this change's job.
+
+      - name: Gate
+        run: make validate.local

CLAUDE.md

@@ -1,15 +1,34 @@
-# CIC Primitives — Claude kontextus
+# CIC Storage — Claude kontextus
+
+## Branch szabály — KÖTELEZŐ
+
+**Érdemi fejlesztés kizárólag a `devel` ágon történhet.**
+
+- `main` — csak merge fogad (devel → main), közvetlen commit tilos
+- `storage/releases/v*` — kizárólag release tag célra
+- `devel` — ez az aktív fejlesztési ág
+
+Ha nem `devel`-en vagyunk: figyelmeztetés, és átváltás `devel`-re mielőtt bármilyen
+schema, kód vagy dokumentáció változtatás történik.
 
 ## Mi ez a rendszer
 
-A `cic-primitives` a CentralInfraCore **meta-séma rétege** — az a szint, amelyből
-minden domain objektum (switch interface, kubernetes pod, service, database, policy)
-schema-szinten levezethető.
+A `cic-storage` egy **domain-repó** — a `cic-primitives` meta-séma rétegére épülve
+storage objektumokat ír le, schema-szinten, **szándékosan provider-agnosztikus
+módon**: a kívánt tárolási állapotot (bucket, tier, titkosítás, hozzáférés)
+mondja ki, nem azt, hogy egy adott felhő (OCI/AWS/Azure/on-prem) hogyan
+valósítja meg. A tényleges létrehozás/felügyelet külön `cic-module-<provider>`
+modulok feladata a `cic:provider` WASM ABI-n keresztül.
 
-Nem domain modell. Nem IaC tool. Nem YANG leíró.
+A `schemas/atomic/`+`schemas/aggregate/` alatti fájlok **öröklöttek** a
+`cic-primitives`-ból (a `base` remote-on át) — ez a repó nem definiálja őket.
+A saját munka a domain-kompozíció: `schemas/examples/storage-bucket.yaml`
+(`StorageBucket`). A `kubernetes-pod.yaml` a `cic-primitives` öröklött
+sablon-demója, nem ennek a repónak a munkája.
 
 A primitívek azok az **irreducibilis szemantikai atomok és kompozícióik**, amelyekből
-bármilyen menedzselt objektum strukturált, validálható, verziózott YAML sémává fordítható.
+bármilyen menedzselt objektum strukturált, validálható, verziózott YAML sémává fordítható
+— ezt a réteget a `cic-primitives` adja, nem ez a repó.
 
 Részletes architektúra: `ai/SYSTEM_CONTEXT.md`
 Következő konkrét feladatok: `ai/PROMPTMAP.yaml`
@@ -42,24 +61,23 @@ Amíg ez a négy pont nincs meg, ne tegyél tényállításokat a primitive mode
 
 | Elem | Státusz | Megjegyzés |
 |---|---|---|
-| git repo bootstrap | **defined** | `git merge base@0.5.0` kész |
-| `dependency.yaml` | **defined** | `base@0.5.0` composition lock |
-| `project.yaml` | **defined** | `x-cic.repo_type: primitive` |
-| `schemas/` struktúra | **defined** | atomic/ + aggregate/ + index.yaml |
-| aggregate skeletonök | **defined** | ConfigSurface, StateSurface, OperationSurface, ManagedEntity |
-| atomic layer (7 atom) | **defined** | Shape, Role, Behavior, Contract, Address, Identity, Event |
-| aggregate completion | **defined** | atomic ref-ek bekötve |
-| domain példa | **defined** | `schemas/examples/kubernetes-pod.yaml` |
+| git repo bootstrap | **defined** | `git merge base@0.5.0` a `cic-primitives`-on át (nem közvetlen) |
+| `dependency.yaml` | **defined** | `base@0.5.0` composition lock (örökölt) |
+| `project.yaml` | **defined** | `x-cic.repo_type: domain` |
+| `schemas/` struktúra | **defined** | atomic/ + aggregate/ (örökölt) + examples/storage-bucket.yaml (saját) |
+| atomic/aggregate réteg | **öröklött** | Shape, Role, Behavior, Contract, Address, Identity, Event, Access + surface-aggregate-ek |
+| `StorageBucket` domain composition | **defined** | provider-agnosztikus, teljes surface-készlet, `make validate` zöld |
+| Provider modul kötés | **partial** | `cic-module-oracle-cloud` implemented; aws/azure/onprem concept |
 | `make validate` zöld | **defined** | Docker-alapú tooling, Vault nélkül is fut |
-| első signed release | **concept** | Vault + `make release VERSION=x` |
+| signed release pipeline | **defined** | lefutott (lásd git tag-ek) |
 
 ---
 
 ## A két szint
 
 ```
 atomic primitive   = irreducibilis szemantikai atom
-                     Shape · Role · Behavior · Contract · Address · Identity · Event
+                     Shape · Role · Behavior · Contract · Address · Identity · Event · Access
                    → ezekből schema fragment generálható
 
 aggregate primitive = szemantikai kompozíció sealed/defaulted/required slot-okkal
@@ -78,9 +96,9 @@ Az objektum mindig következmény, soha nem kiindulópont.
 ```
 base-repo (upstream sablon)
     │  remote: base → git merge base@0.5.0
-    └──► cic-primitives  (ez a repo)
+    └──► cic-primitives
               │  remote: base → git merge base@0.5.0
-              └──► domain repók (cic-yang, cic-network, stb.)
+              └──► cic-storage  (ez a repo)  ·  cic-network, cic-storage, stb. (testvér domain repók)
 ```
 
 A fájlstruktúra IS az interface contract. A merge konfliktus = séma sértés.
@@ -130,9 +148,10 @@ Immersion módban tilos hiányt feltételezni ott, ahol scaffold szándékos.
 
 | Repo | Remote | Mit ad |
 |---|---|---|
-| `base-repo` | `base` | tooling, signing hook, CI, Makefile, mk/infra.mk |
-| `CIC-Schemas` | referencia | template-schema minta, séma pipeline, signing lánc |
-| `CIC-Relay` | — | a runtime ami a primitívekből épülő sémákat futtatja |
+| `cic-primitives` | `base` | atomic/aggregate primitívák, tooling, signing hook, CI, Makefile, mk/infra.mk |
+| `base-repo` | közvetett (a `cic-primitives` saját `base` remote-ja) | eredeti tooling-sablon |
+| `cic-module-oracle-cloud` | — | provider modul, a `StorageBucket` intent egyik konkrét megvalósítója |
+| `CIC-Relay` | — | a runtime, ami a provider modulokat futtatja a `storage-bucket.yaml` kompozíció ellen |
 
 ---
 

Dockerfile

@@ -12,6 +12,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
     curl \
     jq \
+    && curl -fsSL https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 \
+       -o /usr/local/bin/yq && chmod +x /usr/local/bin/yq \
     && rm -rf /var/lib/apt/lists/*
 
 # Trust the mounted project directory (host uid != container uid)

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Schema Development Environment
 
-.PHONY: all help up down shell validate release test repo.init infra.deps infra.coverage infra.clean fmt lint check typecheck build
+.PHONY: all help up down shell validate grammar grammar.local validate.local pledge release verify-release verify-release-strict test mutation-test repo.init infra.deps infra.coverage infra.clean fmt lint check typecheck build
 
 # Default to showing help
 all: help
@@ -29,20 +29,70 @@ build:
 # Main Development Tasks
 # =============================================================================
 
-validate:
+validate: grammar
 	@echo "--- Validating all schemas against the meta-schema ---"
 	@docker compose exec builder python tools/compiler.py validate
 
+# The atom grammar closes what index.yaml cannot: the instance form of Shape
+# and Role, and the constraints that cross primitive boundaries. The self-test
+# runs first on purpose — a gate nobody has shown capable of failing is not a
+# gate. See proposals/atom-grammar/README.md.
+grammar:
+	@echo "--- Atom grammar: self-test ---"
+	@docker compose exec builder python proposals/atom-grammar/check_grammar.py --self-test
+	@echo "--- Atom grammar: live compositions ---"
+	@docker compose exec builder sh -c \
+	  'python proposals/atom-grammar/check_grammar.py schemas/examples/*.yaml \
+	     $$(ls schemas/domain/*.yaml 2>/dev/null)'
+
+# =============================================================================
+# Container-free gate — what CI runs
+# =============================================================================
+# The docker targets above and these must stay equivalent. CI calls
+# validate.local, so the gate has ONE definition rather than one here and a
+# second one copied into the workflow YAML.
+
+# Every composition this repository ships. Wildcards, not a fixed list, so a
+# new composition is gated the moment it lands. Both directories matter:
+# examples/ holds the demonstrations, domain/ holds the real domain objects —
+# and domain/ is where the richest ones live (cic-compute's compute-resource).
+GRAMMAR_COMPOSITIONS := $(wildcard schemas/examples/*.yaml) $(wildcard schemas/domain/*.yaml)
+
+grammar.local:
+	@echo "--- Atom grammar: self-test ---"
+	@python3 proposals/atom-grammar/check_grammar.py --self-test
+	@echo "--- Atom grammar: live compositions ---"
+	@python3 proposals/atom-grammar/check_grammar.py $(GRAMMAR_COMPOSITIONS)
+
+validate.local: grammar.local
+	@echo "--- Validating all schemas against the meta-schema ---"
+	@python3 tools/compiler.py validate
+
+pledge:
+	@echo "--- Developer commitment: validity + createdBy signed by Vault ---"
+	@docker compose exec builder python tools/compiler.py pledge
+
 release:
 	@echo "--- Building and signing release schemas ---"
 	@docker compose exec builder python tools/compiler.py release
-	@tools/release.sh project.yaml
-	@git add project.yaml
+
+verify-release:
+	@if [ -z "$(FILE)" ]; then echo "Usage: make verify-release FILE=release/<name>-vX.Y.Z.yaml [STRICT=1]"; exit 1; fi
+	@docker compose exec builder python tools/compiler.py verify-release $(FILE) $(if $(STRICT),--strict,)
+
+verify-release-strict:
+	@if [ -z "$(FILE)" ]; then echo "Usage: make verify-release-strict FILE=release/<name>-vX.Y.Z.yaml"; exit 1; fi
+	@docker compose exec builder python tools/compiler.py verify-release $(FILE) --strict
 
 test:
 	@echo "--- Running pytest for the compiler infrastructure ---"
 	@docker compose exec builder python -m pytest --cov=tools.compiler --cov-report=term-missing tests/
 
+mutation-test:
+	@echo "--- Running mutation tests (mutmut) ---"
+	@docker compose exec builder mutmut run
+	@docker compose exec builder mutmut results
+
 fmt:
 	@echo "--- Formatting Python code with Black and Isort ---"
 	@docker compose exec builder python -m black .
@@ -104,8 +154,11 @@ help:
 	@echo ""
 	@echo "Main Tasks:"
 	@echo "  validate      Run fast, offline validation of all schemas."
-	@echo "  release       Build, checksum, and sign all non-dev schemas (requires Vault)."
+	@echo "  pledge        Generate a signed developer commitment (validity + createdBy) to commitment.yaml."
+	@echo "  release       Build, checksum, and sign all non-dev schemas (requires Vault + commitment.yaml)."
+	@echo "  verify-release FILE=<path>  Verify a PrimitiveRelease bundle (content_hash + meta_hash)."
 	@echo "  test          Run pytest for the compiler infrastructure code."
+	@echo "  mutation-test Run mutmut mutation tests against tools/compiler.py."
 	@echo "  fmt           Format Python code with Black and Isort."
 	@echo "  lint          Lint Python code with Ruff and YAML files with yamllint."
 	@echo "  typecheck     Run static type checking with MyPy."

README.hu.md

@@ -0,0 +1,102 @@
+# cic-storage
+
+> Ez nem klasszikus repo. Ez AI-operált domain schema layer.
+> Emberi belépő: ez a README. AI belépő: `ai/ONBOARDING.md`.
+
+A `cic-storage` a `cic-primitives` **meta-séma rétegére** épülő domain-repó —
+storage objektumokat ír le, a `cic-primitives` atomic/aggregate primitíváinak
+kompozíciójaként.
+
+**Fontos architekturális elv: ez a repó szándékosan provider-agnosztikus.**
+A `cic-storage` azt írja le, MIT akarunk (kívánt tárolási állapot — bucket,
+tier, titkosítás, hozzáférés), nem azt, hogy egy konkrét felhő (OCI/AWS/Azure/
+on-prem) hogyan valósítja meg. A tényleges létrehozást/felügyeletet külön
+`cic-module-<provider>` modulok végzik a `cic:provider` WASM ABI-n keresztül
+(pl. `cic-module-oracle-cloud` — jelenleg az egyetlen implemented modul).
+Provider-specifikus részletek (path-ok, HTTP-igék, SDK-anomáliák) szándékosan
+NEM jelennek meg itt — azok a modul saját correspondence/binding rétegében élnek.
+
+---
+
+## Két szint
+
+| Szint | Mit képvisel | Hol van | Eredet |
+|---|---|---|---|
+| **atomic primitive** | 8 irreducibilis atom — Shape, Role, Behavior, Contract, Address, Identity, Event, Access | `schemas/atomic/` | öröklött a `cic-primitives`-ból |
+| **aggregate primitive** | Kompozíció sealed/defaulted/required slot-okkal | `schemas/aggregate/` | öröklött a `cic-primitives`-ból |
+| **domain composition** | `StorageBucket` — provider-agnosztikus object-storage intent | `schemas/examples/storage-bucket.yaml` | **ennek a repónak a saját munkája** |
+
+A domain objektum mindig következmény, soha nem kiindulópont — ez itt a
+`StorageBucket`, ami a `ManagedEntity` aggregate-et alkalmazza a `cic:storage`
+domain-ra, provider-független szinten.
+
+---
+
+## Gyors start
+
+```bash
+make validate    # séma validáció — ha ez nem zöld, semmi sem kész
+make release     # signed artifact (Vault szükséges)
+```
+
+---
+
+## AI belépési pontok
+
+| Fájl | Mire való |
+|---|---|
+| `ai/ONBOARDING.md` | Boot protokoll — minden session elején |
+| `ai/MAINTENANCE_CONTRACT.md` | Mit szabad, mit nem, mikor kell döntés |
+| `ai/SYSTEM_CONTEXT.md` | Teljes architekturális kontextus |
+| `ai/PROMPTMAP.yaml` | Task queue — mi a következő konkrét lépés |
+| `ai/DECISIONS.md` | Döntési history — miért úgy van ahogy van |
+
+---
+
+## Aktuális állapot
+
+| Réteg | Státusz | Megjegyzés |
+|---|---|---|
+| Örökölt atomic/aggregate primitívák | **defined** | `schemas/atomic/`, `schemas/aggregate/` — a `cic-primitives`-ból, `base` remote-on át |
+| `StorageBucket` domain composition | **defined** | `schemas/examples/storage-bucket.yaml` — provider-agnosztikus, teljes surface-készlet (Config/State/Operation/Notification/Policy/Binding) |
+| Provider modul kötés | **partial** | `cic-module-oracle-cloud` = implemented; aws/azure/onprem modulok = concept (lásd composition `derivation_chain.provider_mapping`) |
+| KubernetesPod sablon-példa | **öröklött, nem storage-specifikus** | `schemas/examples/kubernetes-pod.yaml` — a `cic-primitives` demója, nem ennek a repónak a munkája |
+| Signed release pipeline | **defined** | Vault Transit + ECDSA, a pipeline maga lefutott (lásd git tag-ek) |
+| Production trust-chain | **not implemented** | CIC-Relay + CIC-Schemas feladata |
+
+---
+
+## Kapcsolódó repók
+
+| Repo | Kapcsolat |
+|---|---|
+| `cic-primitives` | közvetlen upstream — atomic/aggregate primitívák + tooling, `git remote base` |
+| `base-repo` | közvetett upstream (a `cic-primitives` saját `base@0.5.0` merge-én keresztül) |
+| `cic-module-oracle-cloud` | provider modul — a `StorageBucket` intent egyik konkrét megvalósítója, `cic:provider` WASM ABI-n keresztül |
+| `CIC-Relay` | runtime — a provider modulokat futtatja, amik a `storage-bucket.yaml` kompozíciót reconcile-olják |
+
+---
+
+## Release artifact — GHCR
+
+A séma release OCI artifactként érhető el a GitHub Container Registry-ben.
+
+**ORAS-szal:**
+
+```bash
+oras pull ghcr.io/centralinfracore/schema/cic-storage:v0.1.2-src2026
+```
+
+**curl-lel (ORAS nélkül):**
+
+```bash
+REPO="centralinfracore/schema/cic-storage"; TAG="v0.1.2-src2026"; \
+TOKEN=$(curl -fsSL "https://ghcr.io/token?scope=repository:${REPO}:pull" | jq -r .token); \
+DIGEST=$(curl -fsSL \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "Accept: application/vnd.oci.image.manifest.v1+json" \
+  "https://ghcr.io/v2/${REPO}/manifests/${TAG}" | jq -r '.layers[0].digest'); \
+curl -fL -H "Authorization: Bearer ${TOKEN}" \
+  "https://ghcr.io/v2/${REPO}/blobs/${DIGEST}" \
+  -o cic-storage-v0.1.2.yaml
+```