refactor: rename storage module to datastore and update all imports (SDK + providers)

Author: nielsweistra

.github/agents/ITLPartnerDeveloper.agent.md

@@ -0,0 +1,55 @@
+# Agent Design (concept)
+
+Dit is een beknopt, uitvoerbaar designvoorstel voor een ITL Resource Provider. Het bevat placeholders en aannames — pas waar nodig aan na intake.
+
+**Provider namespace**: Partner.Example
+
+**Resource types**
+- `instances` (hoofdkernresource)
+  - Properties: `sku` (required, object), `region` (required), `configuration` (optional), `provisioningState` (read-only)
+  - Uniqueness: per subscription + resourceGroup
+- `backups` (child van `instances`)
+  - Properties: `timestamp`, `status`, `sizeMB`
+
+**API mapping (CRUD routes)**
+- Create: POST /subscriptions/{sub}/resourceGroups/{rg}/providers/Partner.Example/instances
+- Get:    GET  /.../instances/{name}
+- List:   GET  /.../instances
+- Delete: DELETE /.../instances/{name}
+
+Samengestelde `type` antwoord: `Partner.Example/instances`
+
+**Provisioning model**
+- Standaard antwoord op create: 202 Accepted met `provisioningState: Creating`.
+- Achtergrondtask voert externe API calls uit; bij succes `provisioningState: Succeeded`, bij fout `Failed` + `error` property.
+- Polling model: GET resource retourneert actuele provisioningState.
+
+**Externe integratie**
+- Client: `httpx.AsyncClient` met configurable `base_url` en auth header.
+- Timeouts en retries: exponential backoff, max 5 retries voor idempotente calls.
+
+**Storage / state**
+- Aanbevolen: PostgreSQL (asyncpg) voor persistente metadata en provisioning state.
+- Alternatief: vertrouw op upstream API en bewaar alleen index/metadata lokaal.
+
+**Events / notificaties**
+- Optioneel: publiceer events bij create/succeed/fail naar RabbitMQ of webhook endpoint.
+
+**Errors & retry**
+- Map externe 4xx -> `ValidationError` / `ResourceConflictError` waar passend.
+- 5xx en netwerkfouten -> `ExternalServiceError` met retry.
+
+**Security**
+- Credentials via environment variables or mounted secret store (CONFIG: `EXTERNAL_API_KEY`, `EXTERNAL_BASE_URL`).
+
+**Tests / CI**
+- `pytest` async tests: create/get/list/delete happy path + failure simulation (mock client).
+- GH Actions: lint, unit tests, build docker image.
+
+**Acceptance criteria**
+- Create returns 202 and resource shows `provisioningState: Succeeded` after background task.
+- CRUD routes conform to expected ARM-style id and type fields.
+- Tests groen in CI.
+
+---
+Als dit design akkoord is, scaffold ik de providercode (stap 3). Als je wilt, kan ik nu al concrete voorbeelden en bestanden genereren.

.github/agents/ITLResourceProvider.agent.md

@@ -0,0 +1,60 @@
+---
+agent: plan
+---
+
+<!--
+Agent intake document — vul de antwoorden in tijdens de intake.
+Gebruik deze checklist om het provider-design later te kunnen uitvoeren.
+-->
+# Agent Intake — DISCOVERY
+
+Vul de onderstaande vragen zo volledig mogelijk in. Antwoord in Nederlands.
+
+1) Dienst / bedrijf (in één zin)
+- Naam dienst / bedrijf:
+- Korte beschrijving:
+
+2) Welke resources beheren jullie?
+- Resource types (lijst):
+- Relaties (parent/child):
+
+3) Bestaande API (beschrijf kort)
+- Base URL:
+- Belangrijkste endpoints (POST/GET/DELETE etc.) met voorbeeldpaden:
+- Authenticatie (API key / OAuth2 / Bearer / anders):
+
+4) Wat gebeurt er bij create?
+- Direct provisioning of async (duurtijd indicatie):
+- Externe acties (calls naar API, DB writes, queues):
+
+5) Properties per resource type
+- Voorbeeld schema per type (verplicht / optioneel / read-only):
+
+6) Uniqueness & scope
+- Uniek per subscription / resourceGroup / global / anders:
+
+7) Opslag en state
+- Gebruikelijke storage (DB type of alleen externe API):
+- Moeten we provisioning state persistent houden? (ja/nee):
+
+8) Events / notificaties
+- Moet er een event gestuurd worden bij create/update/delete? (ja/nee)
+- Zo ja: bestemming (webhook, queue, topic):
+
+9) Foutscenario's en retry-beleid
+- Verwachte fouten van externe API (codes / meldingen):
+- Gewenst retry-beleid en backoff:
+
+10) Security / secrets
+- Hoe verstrekken we credentials aan de provider (env vars / secret store):
+
+11) Acceptatiecriteria
+- Wanneer beschouwen we een resource als "Succeeded":
+- Welke tests moeten slagen voor oplevering:
+
+12) Extra opmerkingen / voorbeelden
+- Voorbeeld request JSON:
+- Voorbeeld response JSON:
+
+---
+Vul dit document in en geef aan of je wilt dat ik op basis hiervan direct een designvoorstel (`agent-design.md`) genereer.

.github/designs/agent-design.plan.md

@@ -0,0 +1,36 @@
+---
+description: Richtlijnen voor het maken van consistente prompts en instructies voor interne agents en contributors.
+---
+# Richtlijnen voor prompts & instructions (voor repo maintainers)
+
+Doel: consistente, bruikbare prompts en instructies maken voor interne agents en contributors.
+
+Principes:
+- Wees specifiek: geef voorbeelden en verwachte outputs.
+- Kort en scanbaar: gebruik opgesomde vragen en voorbeeldantwoorden.
+- Eén doel per prompt: voorkom gecombineerde vragen.
+- Varianten: maak een korte (1-2 regels) en uitgebreide versie.
+
+Bestandsstructuur:
+- `.github/prompts/`: gebruiker-vriendelijke prompt-templates (MD-bestanden).
+- `.github/instructions/`: richtlijnen, usage voorbeelden, policies.
+
+Hoe een nieuwe prompt toevoegen:
+1. Maak `X_prompt.md` in `.github/prompts/`.
+2. Bovenaan: korte omschrijving en doel.
+3. Voeg genummerde vragen toe en een kort voorbeeldantwoord.
+4. Voeg optioneel een `Voorbeeld` sectie met JSON.
+
+Hoe een instruction schrijven:
+- Leg uit wanneer je de prompt gebruikt.
+- Geef voorbeelden van juiste en foute antwoorden.
+- Voeg links naar relevante documenten (bijv. `ITL.ControlPlane.SDK/.github/agents/ITLPartnerDeveloper.agent.md`).
+
+Review checklist:
+- Is de prompt begrijpelijk zonder extra context?
+- Staat er een concreet voorbeeld bij?
+- Is taal consistent (Nederlands voor conversatie, Engels voor code)?
+
+Onderhoud:
+- Houd prompts up-to-date met veranderingen in de SDK of API-contracten.
+- Gebruik PR-templates voor wijzigingen in `.github/prompts`.

.github/designs/agent-intake.plan.md

@@ -0,0 +1,32 @@
+# Voorbeelden: gebruik van prompts
+
+Kort overzicht van typische workflows en welke prompt te gebruiken.
+
+1) Nieuwe provider ontwerpen
+- Gebruik: `new_provider_prompt.md`
+- Stappen: verzamel antwoorden, stuur terug designvoorstel, wacht goedkeuring.
+
+2) Bestaande API wrappen
+- Gebruik: `wrap_api_prompt.md`
+- Stappen: vraag OpenAPI of voorbeeldrequests, identificeer auth en async gedrag, maak provider-scaffold.
+
+3) Debugging
+- Gebruik: `debug_provider_prompt.md`
+- Stappen: vraag reproducerende stappen en logs, probeer minimal reproducerend request lokaal.
+
+Snelle command voorbeelden (lokale tests):
+
+```powershell
+# Start provider (voorbeeld)
+python -m src.main
+
+# Run tests
+pytest -q
+```
+
+Plaats altijd volgende info bij een issue of PR:
+- Link naar de gebruikte prompt-template
+- Korte samenvatting van antwoorden
+- Relevante codebestanden of tests
+
+Contact: gebruik teamkanaal of vermeld `@itlusions/sdk` voor urgente vragen.

.github/instructions/prompt_creation.instructions.md

@@ -0,0 +1,33 @@
+# Plan (agentPlan)
+
+- Intake & discovery
+  - Stel de volledige DISCOVERY-vragen (dienstnaam, resources, bestaande API endpoints, auth, provisioning gedrag, properties, unique scope, DB/enqueue requirements).
+  - Resultaat: ingevuld intake-document (.github/designs/agent-intake.md) met concrete antwoorden en voorbeelden. Gebruik de vragenlijst uit .github/instructions/prompt_creation.instructions.md als checklist.
+
+- Design voorstel maken
+  - Vertaal de intake naar een concreet design: provider namespace, resource types, resource model (properties verplicht/optioneel), UniquenessScope, endpoints (create/get/list/delete), async vs sync provisioning, events/notifications, storage en retry-beleid.
+  - Resultaat: agent-design.md in .github/designs/ met ER-diagram en API mapping.
+
+- Scaffold project
+  - Genereer projectstructuur voor de provider: pyproject.toml, Dockerfile, entrypoint.py, provider.py, src/routers/*.py, src/services/*, tests/.
+  - Plaats scaffold onder ITL.ControlPlane.ResourceProvider.{AgentName} en voeg provider.yaml metadata toe. Acceptance: project kan builden en start FastAPI app.
+
+- Implementatie core
+  - Implementeer ResourceProvider subclass in provider.py met create_or_update_resource, get_resource, list_resources, delete_resource.
+  - Voeg externe API-client (httpx async), foutafhandeling (ExternalServiceError etc.), en async provisioning (tasking) toe wanneer nodig. Resultaat: werkende handler met voorbeeld responses.
+
+- Tests & CI
+  - Schrijf pytest async tests voor create/get/list/delete en edge-cases.
+  - Voeg GH Actions workflow voor lint, test, build. Acceptance: tests draaien groen lokaal en in CI.
+
+- Documentatie & README
+  - Maak README.md met quickstart, run-commando's, API voorbeelden, en ontwikkelnotities. Voeg provider.yaml en CHANGELOG.md.
+  - Resultaat: duidelijke on-boarding sectie in repository root.
+
+- Review & oplevering
+  - Doe code-review, run volledige test-suite, prepareer PR met beschrijving en release-notes.
+  - Maak deploy-stappen (Docker image, helm chart pointers) en mijlpalen. Resultaat: PR klaar voor merge en release instructies.
+
+---
+
+Wil je dat ik nu scaffold genereer of eerst het intake-document met jouw antwoorden laat invullen?

.github/instructions/usage_examples.md

@@ -0,0 +1,35 @@
+---
+agent: agent
+---
+# Provider Debug Prompt
+
+Gebruik deze template om snel een bug of fout in een provider te beschrijven.
+
+1. Samenvatting van het probleem (1-2 zinnen):
+
+2. Reproducerende stappen:
+   - Welke API-call / request body / headers gebruik je?
+   - Welke stappen leiden tot de fout?
+
+3. Verwachte gedrag vs werkelijke gedrag:
+
+4. Foutmelding / stack trace (volledige tekst):
+
+5. Relevante bestanden of code-fragmenten:
+   - `provider.py`, `main.py`, router-bestanden, tests
+
+6. Hoe draai je de service lokaal?
+   - `python -m`, Docker, of Helm?
+   - Environment variables die gezet zijn
+
+7. Recent changes (git commit ids of korte beschrijving):
+
+8. Extra observaties / debugging stappen al geprobeerd:
+   - Logs, curl/httpx requests, mock responses
+
+Kort voorbeeld:
+- Probleem: "Create request geeft 500 en `ExternalServiceError`"
+- Repro: `POST /subscriptions/.../providers/Acme.Database/servers` met body {...}
+- Fout: `httpx.HTTPError: 502 Bad Gateway`
+
+Plak altijd relevante logregels en een minimal reproducerend request.

.github/prompts/agentPlan.prompt.md

@@ -0,0 +1,47 @@
+---
+agent: agent
+---
+# Nieuwe Provider — Intake Prompt
+
+Gebruik deze template om snel de benodigde informatie te verzamelen voor het ontwerpen van een ITL Resource Provider.
+
+1. Dienst / Bedrijf (1 zin):
+   - Wat doet jullie dienst?
+
+2. Resource types:
+   - Welke "dingen" moeten beheerd worden? (bijv. servers, databases, clusters)
+
+3. Huidige API / integratie:
+   - Base URL:
+   - Belangrijke endpoints (POST, GET, LIST, DELETE):
+   - Authenticatie (API key / OAuth / bearer):
+
+4. Provisioning gedrag:
+   - Moet aanmaken/provisioning sync of async verlopen?
+   - Welke externe systemen worden aangeroepen?
+   - Verwachte duur van provisioning (sec/min/uren):
+
+5. Resource properties:
+   - Verplicht vs optioneel (voorbeeld JSON of lijst):
+   - Zijn er enums/keuzes (SKU, tiers, regio's)?
+
+6. Uniciteit / scope:
+   - Uniek per subscription / resource group / globaal?
+
+7. Persistentie:
+   - Gebruik je eigen DB (Postgres / Mongo / enz.) of alles via externe API?
+
+8. Events / notificaties:
+   - Moeten events worden gepubliceerd bij create/update/delete? Zo ja: waarheen?
+
+9. Extra wensen / acties:
+   - Speciale acties (restart, failover, backup) of read-only velden?
+
+Voorbeeldantwoord (kort):
+- Dienst: "Managed Postgres clusters"
+- Resources: `servers`, `databases`, `backups`
+- API: `https://api.acme.com/v1`, auth: Bearer
+- Provisioning: async, 3-5 minuten
+- Uniciteit: per subscription
+
+Voeg concrete voorbeeldrequests/responses toe voor snellere scaffolding.

.github/prompts/debug_provider.prompt.md

@@ -0,0 +1,43 @@
+---
+agent: agent
+---
+# Bestaande API Wrappen — Prompt
+
+Gebruik deze prompt wanneer je een bestaande REST API wilt ontsluiten als ITL Provider.
+
+1. OpenAPI / Docs URL (of korte endpoint-lijst):
+
+2. Authenticatie:
+   - Type: API key / OAuth2 / Basic
+   - Hoe verkrijgt de provider de credentials?
+
+3. Belangrijke endpoints (voor elke resource):
+   - POST /path  (create)
+   - GET /path/{id} (get)
+   - GET /path (list)
+   - DELETE /path/{id} (delete)
+   - Overige acties (POST /path/{id}/action)
+
+4. Voorbeelden:
+   - Voorbeeld create request (JSON)
+   - Voorbeeld create response (JSON)
+
+5. Foutafhandeling:
+   - Welke statuscodes en foutpayloads geeft de API terug?
+
+6. Provisioning-tijd:
+   - Direct (sync) of langdurig (async)? Hoe lang?
+
+7. Rate limits / throttling:
+   - Zijn er limieten of retry-richtlijnen?
+
+8. Security / netwerkroutes:
+   - Zijn er IP-allowlists, private endpoints of mTLS vereisten?
+
+Voorbeeld kort antwoord:
+- Base URL: `https://api.example.com/v2`
+- Auth: API key in header `X-Api-Key`
+- Endpoints: `POST /clusters`, `GET /clusters/{id}`
+- Provisioning: async, 2-10 minuten
+
+Bij voorkeur: voeg een OpenAPI-spec mee of kort JSON-voorbeeld.