# Jinkendo – Entitlements, Usage & Quotas Blueprint **v0.1 · 16.10.2026 · Spezialblueprint 4 nach Release, KI-Gateway und Workflow-Laufzeit · technischer Entwurf V/K** ## 1. Ziel und bestehende Verträge Dieser Blueprint spezifiziert produktlokale Funktionsfreigaben, Verbrauchserfassung und atomare Kontingentgrenzen. Er konkretisiert `EntitlementPolicy` der Application Foundation und den `UsageBudgetPort` des KI-Gateways. Cursor kann damit einen benannten Fachfall umsetzen, sobald ein Implementierungsauftrag vorliegt. Hier wird ausschließlich dieses Dokument erstellt. Grundlagen: - [Technische Referenzarchitektur A v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/A_Jinkendo_Technical_Reference_Architecture.md), [Application Foundation B v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/B_Implementation_Blueprint_Application_Foundation.md), [Entscheidungen C v0.3](C:/Dev/jinkendo-phase3-2-technical-reference-architecture-v0.3-2026-10-16/C_Technical_Decisions_Open_Issues.md). - [Auth, Session & Scope](C:/Dev/jinkendo-phase3-3-auth-session-scope-blueprint-2026-10-16/Jinkendo_Auth_Session_Scope_Blueprint.md), [Release, Betrieb & Recovery](C:/Dev/jinkendo-release-betrieb-recovery-blueprint-2026-10-16/Jinkendo_Release_Betrieb_Recovery_Blueprint.md), [KI-Gateway](C:/Dev/jinkendo-ki-gateway-provider-privacy-blueprint-2026-10-16/Jinkendo_AI_Gateway_Provider_Privacy_Blueprint.md) und [Prompt-/Platzhalter-/Workflow-Laufzeit](C:/Dev/jinkendo-prompt-placeholder-workflow-blueprint-2026-10-16/Jinkendo_Prompt_Placeholder_Workflow_Blueprint.md). - Beschlossene ADR-01 bis ADR-14 aus dem [Entscheidungsregister](C:/Dev/jinkendo-architecture-consolidation-phase2-v0.2-2026-10-15/05_Architecture_Decision_Register.md), insbesondere ADR-10 für atomare harte Grenzen und ADR-13 für produktlokale Umsetzung. Historische Freigabeformulierungen eröffnen keine neue Freigabeschleife; ADR-15/16 bleiben offen. - [Phase-3.1-Wissenselemente](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/A01_knowledge_elements.json): KI-MIT-05, KI-SHK-03 und ergänzend KI-KAI-05; [Quellenregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/sources.json), [Testregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/tests.jsonl), [Guardrailregister](C:/Dev/jinkendo-phase3-1-technical-knowledge-inventory-2026-10-15/guardrails_source_register.jsonl). Es entsteht kein zentraler Billingdienst, Zahlungsanbieter, Checkout, Rechnungswesen oder gemeinsamer Tenantstore. Preise, Steuern, Zahlungsbedingungen und neue Produktpakete werden nicht festgelegt. Die Begriffe Kosten/Verbrauch beschreiben technische Budgetkontrolle, keine Rechnung an Kunden. Shinkans manuell gesetzte Vereinspläne bleiben ein zulässiger lokaler Einstieg. Ein Produkt ohne kommerzielle Kontingente benötigt nur seine tatsächlich erforderlichen Funktions- und technischen Sicherheitsgrenzen. | Nachweisgrad | Aussage | |---|---| | **V** | Vorgeschlagener technischer Standard für eine spätere Umsetzung | | **I** | Statisch gelesene vorhandene Implementierung oder Dokumentquelle | | **T** | Tatsächlich ausgeführte Prüfung mit ausdrücklich begrenztem Umfang | | **K** | Noch nicht integrierte/getestete Kombination | Alle neuen Schnittstellen, SQLmuster und Abläufe sind **V/K**. Bestehende Testdateien sind **I**, kein bestandener Testlauf. Der abschließende Dokumentcheck ist nur T für Dateiintegrität, Verweise und Beispielsyntax. Blueprint und Foundation sind keine bereits produktionsreife Referenzimplementierung. ### 1.1 Verbindliche Architekturverträge und technische Defaults | Verbindlich | Anpassbarer technischer Default | |---|---| | Identität, Scope, Capability, Objektzugriff und Entitlement getrennt; alle nötigen Prüfungen bestehen | Benennung von Features, Plänen und Capabilities | | Server bestimmt Kontingentsubjekt und Messgröße; kein Client wählt ein fremdes oder günstigeres Konto | Lokale Abbildung Account/Profil bei Mitai, Club bei Shinkan | | Harte Grenze erfordert atomare Zulassung und idempotente Buchung; unbekannte Wirkung ist keine Null | Produktlokale PostgreSQLzeilensperren und Ledgerstruktur | | Fehlende/defekte Policy ist keine unbegrenzte Erlaubnis | UTC-Kalendermonate als erste periodische Variante | | Externe Kosten ohne belastbare obere Schranke dürfen keine zugesicherte harte Kostengrenze passieren | Zuerst harte Callanzahl; Token-/Kostenmetriken zunächst beobachtend | | Kein Netzwerk in offener Fachtransaktion; Resultat, Callabschluss, Verbrauch und Audit konsistent | Adapter-/Dateipfade, technische Größen-/Zeitgrenzen | | Quoten-Ausnahme erteilt keine Objekt-, Privacy- oder Maschinenrechte | Befristete featurebezogene Ausnahmen mit bestehender Capabilitytechnik | | Release-Gates, Quell-/Buildzuordnung und menschliche Produktionsfreigabe nach ADR-11 | R1 bevorzugt; kontrollierte separate Builds R2 bleiben zulässig | Ein anderer Default ist bei begründetem Produktbedarf möglich. Dazu gehören ein anderes Kalenderfenster oder eine andere klar benannte Verbrauchseinheit. Eine Änderung der verkauften Einheit wird dadurch nicht automatisch autorisiert; dieser Blueprint legt keine neuen Kundenzusagen fest. ## 2. Gezielte Implementierungsreferenzen | Quelle I | Wiederverwenden | Gezielte Ergänzung V/K | |---|---|---| | Mitai [Featureprüfung](C:/Dev/mitai-jinkendo/backend/auth.py:173), [Tarifauflösung](C:/Dev/mitai-jinkendo/backend/auth.py:129), KI-MIT-05 | Registrierung bekannter Features, lokale Plans-/Grantauflösung, differenzierte Ablehnungsgründe | Auslesen und späteres Erhöhen ist keine atomare Zulassung. Fehlende Profile nicht als Free-Identität behandeln. Kein interner Commit beim prüfenden Aufruf. | | Mitai [Verbrauchserhöhung](C:/Dev/mitai-jinkendo/backend/auth.py:318), [Subscriptionansicht](C:/Dev/mitai-jinkendo/backend/routers/subscription.py:16), [Featuremapping](C:/Dev/mitai-jinkendo/.claude/docs/technical/FEATURE_ENFORCEMENT_MAPPING.md:1) | Nutzerverständliche Limits/Verbrauch und Zuordnung von Funktionen zu Features | Historisches Mapping und Statusvermerke beweisen keine aktuelle vollständige Routeabdeckung. Eigene Connection/Commit und Reset beim Lesen nicht übernehmen. | | Mitai [Widgetentitlements](C:/Dev/mitai-jinkendo/backend/dashboard_widget_entitlements.py:27), [mehrere Anforderungen](C:/Dev/mitai-jinkendo/backend/widget_feature_requirements_db.py:29) | Explizite AND-Verknüpfung benötigter Features, unbekannte Widget-ID geschlossen | UIentscheidung ist keine APIautorität. „Keine Anforderung“ muss bewusst registriert sein, nicht durch Ladefehler entstehen. | | Shinkan [Entitlements](C:/Dev/shinkan-jinkendo/backend/entitlements.py:57), [Registry](C:/Dev/shinkan-jinkendo/backend/rights_registry.py:20), KI-SHK-03 | Account-/Clubrollen, Capabilities und Vereinsfeatures getrennt zu einem Snapshot zusammenführen; `enforcement_subject` | Neues Snapshotmodell aus verifiziertem Scope, ohne ungesicherte Queryumleitung. Registryduplikate als Fehler behandeln; keine automatische DDL-/Planänderung im Startup. | | Shinkan [Clubpläne/Overrides](C:/Dev/shinkan-jinkendo/backend/club_features.py:60), [Bestandszählung](C:/Dev/shinkan-jinkendo/backend/club_features.py:131) | Verein als Kontingentsubjekt und explizite Bestandsfilter, etwa aktive Mitglieder | Bestand, periodischer Verbrauch und Boolean getrennt typisieren. Defekte numerische Limits nicht zu `None`/unbegrenzt normalisieren. | | Shinkan [Consume](C:/Dev/shinkan-jinkendo/backend/club_features.py:423), [Planningmeter](C:/Dev/shinkan-jinkendo/backend/planning_llm_usage.py:19) | Zentrale Verbrauchsfassade und Zählen tatsächlicher untergeordneter Modellaufrufe | Der ContextVar-Zähler zählt erfolgreiche Antworten im Requestspeicher. Er deckt weder Crash noch parallele Reservierung oder unbekannte Kosten. Kein pauschales „ein Workflow = ein Call“. | | Shinkan [Quoten-Ausnahmen](C:/Dev/shinkan-jinkendo/backend/club_quota_bypass.py:83) | Benannte Capability statt pauschaler Adminsonderfall | Aufnahmeausnahme befristen/binden/auditieren; Verbrauch weiterhin erfassen. Keine Ausnahme von Privacy-/Objekt-/technischen Kostenlimits. | | [Familienmodell](C:/Dev/shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md:25), [offene Atomarität](C:/Dev/shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md:287) | Vier unabhängige Prüfebenen und produktspezifisches zahlendes Subjekt | Diese konkrete Reservierungs-/Buchungsspezifikation schließt die technische Lücke für neue Implementierungen; keine Bestandskonformität behaupten. | | Shinkan [lokale Abozusammenfassung](C:/Dev/shinkan-jinkendo/docs/product-readiness/03-abo-entitlements-abrechnung.md:1) | Bestehende Vereinsgrenze und manuell gesetzter Plan; Zahlungsdienst bleibt späterer Adapter | Kein Kopieren des persönlichen Mitai-Tiers nach Shinkan; keine neue Pricing-/Reifeanalyse. | | Kairo [Featureregistrierung](C:/Dev/kairo-jinkendo/backend/feature_registry.py:37), [Entitlementsnapshot](C:/Dev/kairo-jinkendo/backend/entitlements.py:37), KI-KAI-05 | Ergänzend Duplikatsperre und explizite Metadatenregistrierung | Aktive globale Features und `probe` belegen weder lokale Planzusage noch harte Quoten. Kein Kairo-KI-/Workflowausbau. | Die [Mitai-Featurelogs](C:/Dev/mitai-jinkendo/backend/feature_logger.py:36) und [Shinkan-Featurelogs](C:/Dev/shinkan-jinkendo/backend/club_feature_logger.py:43) sind Diagnosemuster; eine Logzeile ist keine atomare Verbrauchsbuchung. Importseitiges Anlegen von Logdateien und `allowed=True` als Fehlerfallback gehören nicht in die Foundation. Kanshōs Privacy bleibt über das Gateway wirksam; hier wird keine neue Kanshō-Subscription oder zentrale Familienabrechnung erfunden. Tsumugu ist keine Implementierungsquelle. ## 3. Begriffe, Subjekte und Prüfreihenfolge ### 3.1 Vier unabhängige Fragen Eine Aktion benötigt eine aktuelle Identität, die fachliche Capability, den konkreten Objektzugriff und die erforderliche Funktions-/Kontingentfreigabe. Die AccessPolicy des Auth-Blueprints prüft Identität, Scope und Objekt. Die EntitlementPolicy ersetzt sie nicht. Vor der Ausgabe kommerzieller Detailinformationen wird bereits Objektsichtbarkeit geprüft; ein fremder Datensatz liefert weiterhin 404, nicht „dessen Tarif ist erschöpft“. `EntitlementPolicy.require(context, feature, tx)` prüft in derselben UoW die aktuelle Funktionsfreigabe. Für eine harte mengenabhängige Aktion ist anschließend zusätzlich die atomare Mengenprüfung/Buchung nötig; ein früherer `require`-Aufruf oder UI-Snapshot reserviert nichts. Planname, Kaufstatus und Rollen werden nicht in Router-/Widgetbedingungen vermischt. ### 3.2 Actor, Datenraum und Kontingentsubjekt | Begriff | Bedeutung | Beispiel | |---|---|---| | Principal | Wer den Auftrag verantwortlich ausführt | Lokales aktives Nutzerkonto oder künftig echte begrenzte Maschinenidentität | | Scope | In welchem autorisierten Datenraum die Aktion stattfindet | Persönlicher Raum bzw. ausgewählter Club | | QuotaSubject | Wessen Kontingent belastet wird | Mitais persönliches Konto, Shinkans Club | | OperationalBudget | Zusätzliche technische Begrenzung des Produktbetriebs | Produktlokales externes Modellbudget, falls tatsächlich benötigt | `QuotaSubjectResolver` ermittelt das Subjekt ausschließlich serverseitig aus dem verifizierten Scope und einer registrierten Produkt-/Featurebindung. Bei Mitai kann der lokale Adapter das vorhandene Profil als Kontingentschlüssel beibehalten, muss es aber eindeutig dem authentifizierten Account zuordnen. Profil-ID und Principal sind keine austauschbaren Begriffe. Shinkans gemeinsamer Vereinsverbrauch bleibt am Club; ein Trainerwechsel oder anderes Mitglied erzeugt kein neues Kontingent. Für einen persönlichen Scope darf kein Club als Sponsor gewählt werden und für einen Clubauftrag kein persönlicher Free-Tarif als Ausweichkonto. Hybrid-/Sponsoringmodelle sind erst mit einer konkreten Produktregel zulässig, nicht durch ein Requestfeld `billing_subject_id`. Im ersten Schnitt belastet jedes Feature genau ein kommerzielles Subjekt. Optionale technische Produktbudgets werden zusätzlich per AND geprüft und besitzen eine eigene lokale Budgetklasse; sie schaffen keine gemeinsame Fachdatenbank. Ein Quotenstatus enthält keine persönlichen Fachwerte, Prompttexte oder fremden Nutzernamen. Ein Clubmitglied darf nicht allein durch Ausführungsrecht die detaillierten Einzelverbräuche aller Mitglieder sehen. `entitlements.read`, `usage.read_own` und gegebenenfalls `usage.read_club_summary` sind eigene Capabilities. ## 4. Registrierte Features und effektive Freigaben ### 4.1 Featurevertrag Ein `FeatureSpec` trägt ID, Revision, Modul, Beschreibung, erlaubte Scopearten, `subject_binding`, erforderliche Capabilityzuordnung, `kind`, Messgrößen/Einheiten, Periodenregel, Defaultpolicy und explizite Semantik der Zählauslöser. Registrierung erfolgt im Bootstrap, danach wird die Registry eingefroren. Doppelte IDs/Revisionen, unbekannte Meter, unvollständige Bindungen oder nicht implementierte Handler schließen das betroffene Modul. Code definiert die verfügbaren Funktionen; ein späterer Zahlungsdienst darf nur registrierte Plan-/Vertragszustände aktualisieren. | `kind` | Bedeutung | Beispiel / Behandlung | |---|---|---| | `boolean` | Funktion erlaubt/verweigert | Workflowfunktion an/aus; kein Mengenverbrauch | | `periodic` | Verbrauch von Ereignissen in einem klaren Zeitfenster | Modell-Sendeversuche oder angelegte Einheiten pro UTC-Monat | | `inventory` | Aktueller fachlich definierter Bestand | Aktive Mitglieder, nicht archivierte Übungen | Ein fehlender Eintrag ist `not_configured`, eine ausdrücklich unbegrenzte registrierte Menge ist `unlimited`, eine ausgeschaltete Funktion ist `disabled`. Diese Zustände werden nicht gemeinsam als SQL-/JSON-`null` interpretiert. Im lokalen Kompatibilitätsadapter kann `NULL` aus einer tatsächlich vorhandenen Limitzeile weiterhin unbegrenzt bedeuten; keine Zeile, ungültiger Typ oder negative Zahl darf dadurch nicht unbegrenzt werden. Legacy `-1` erfordert eine ausdrücklich benannte Übersetzung, keine großzügige Laufzeitnormalisierung. Booleanwerte sind echte Booleans, keine numerischen `limit=1` im neuen DTO. Mengen sind nichtnegative ganze Einheiten. Bei `limit=0` werden keine positiven Mengen zugelassen; das ist von der generellen Funktionsfreigabe unterscheidbar. `0`, fehlend, unbegrenzt und defekt sind vier verschiedene Zustände. Ein Feature ohne kommerzielles Gate wird ausdrücklich mit freier Policy registriert; Ladefehler erzeugen diesen Zustand nicht. `observe` erfasst Mengen ohne Kapazitätszusage, `soft` ergänzt erkennbare Überschreitungshinweise ohne Sperre durch die Mengenhöhe, `hard` erzwingt die atomare Admission. Identitäts-, Capability-, Objekt-, Funktions- und Privacyregeln gelten in allen drei Modi. Der Modus ist eine registrierte Produktpolicy, kein Request-/Environmentflag zum Abschalten eines zugesicherten Hardlimits. Auch beobachtende Mengen behalten ehrliche Unknownzustände. ### 4.2 Plan, Grant, Override und Sperre Pläne sind versionierte lokale Zuordnungen bekannter Features; Subjektzustand besitzt eine monotone `entitlement_revision`. Änderungen an Plan, Override, Grant, Ausnahme oder Sperre sperren dieselbe stabile Subjektzeile wie Zulassungen und erhöhen die Revision. Keine neue Bucket-ID durch bloßen Planwechsel. Pragmatische Auflösung: registriertes Feature und technischer Kill-Switch zuerst; aktive explizite Sperre/Verweigerung gewinnt; ein gültiger Featureoverride ersetzt die konkrete kommerzielle Policy; ansonsten genau ein aktiver benannter Plangrant, dann lokale aktive Subscription/Planbindung, dann ein ausdrücklich registrierter Basistarif. Unklare/überlappende Grants ohne definierte Priorität werden beim Schreiben verweigert; defekte Bestandsdaten ergeben `policy_unavailable`. Nicht anhand des spätesten Ablaufdatums oder lexikografisch höchsten Tarifnamens raten. Ein zeitlicher Grant gilt im halboffenen Intervall `[valid_from, valid_until)`. Die Produktsemantik für `past_due`, Kündigung und Probephase wird als lokale Policy hinterlegt. Default einer neuen technischen Implementierung: kein automatischer Gratiszeitraum; ein beendeter Grant fällt nur auf eine ausdrücklich vorhandene Basispolicy zurück. Konto-/Objektrechte bleiben unabhängig. Kein erneuter Governanceentscheid und keine Änderung bestehender Kundenverträge durch diesen Blueprint. Eine Planreduktion löscht weder Daten noch Verbrauch. Liegen Bestand oder bereits beanspruchte Menge über der neuen Grenze, bleiben aktuelle Lese-/Lösch-/Korrekturrechte nach Authvertrag erhalten; neue positive Inanspruchnahmen werden gesperrt. Bestehende Nutzerinhalte nicht erst hinter einer neu erworbenen Rolle verstecken. Produkte definieren die nötigen nichtkommerziellen Datenzugangs-/Auskunftsprozesse separat; ein Premiumexportflag ist dafür keine allgemeine Autorisierungsentscheidung. ## 5. Komponenten und Python-Schnittstellen Defaultstruktur: `app/modules/entitlements/{registry,models,resolver,policy,repository,service,api}.py` und `app/modules/usage/{models,periods,quota,repository,gateway_budget,reconcile}.py`. Kein eigener Netzwerkdienst. `create_app(settings, providers)` verdrahtet produktlokale Adapter. Registrierung ist DB-/netzfrei; explizite SQLmigrationen/Seeds ändern das Schema und bekannte Katalogstände vor Runtime gemäß Foundation, nicht im Import oder Appstart. ```python from dataclasses import dataclass from datetime import datetime from typing import Literal, Protocol from app.core.context import RequestContext, Tx @dataclass(frozen=True, slots=True) class QuotaSubjectRef: kind: Literal["account", "club", "organization"] subject_id: str @dataclass(frozen=True, slots=True) class PeriodRef: policy_revision: str starts_at: datetime ends_at: datetime @dataclass(frozen=True, slots=True) class FeatureDecision: feature_id: str enabled: bool reason: str entitlement_revision: int subject: QuotaSubjectRef class QuotaSubjectResolver(Protocol): def resolve(self, tx: Tx, context: RequestContext, feature_id: str) -> QuotaSubjectRef: ... class EntitlementPolicy(Protocol): def require(self, context: RequestContext, feature: str, tx: Tx) -> None: ... class LocalUsagePort(Protocol): def consume(self, tx: Tx, context: RequestContext, *, operation_id: str, feature_id: str, quantity: int) -> None: ... ``` `FeatureDecision` ist ein interner Snapshot, keine dauerhaft gültige Freigabe. `quantity` ist eine strikt positive serverseitig aus der tatsächlichen Fachoperation ermittelte Ganzzahl, kein Clientverbrauch. Der Port gilt für registrierte periodische lokale Ereignisse und besitzt einen eindeutigen Operationseintrag; Bestand nutzt den eigenen Adapter aus Abschnitt 11. `Tx` stammt aus der Foundation; sämtliche beteiligten Repositories nutzen denselben Handle und committen nicht selbst. Für KI wird der bestehende Port **unverändert** verwendet; seine Typen werden nicht parallel nachdefiniert: ```python from typing import Protocol from app.core.context import RequestContext from app.modules.ai.contracts import BudgetEnvelope, UsageReport class UsageBudgetPort(Protocol): def reserve(self, tx: object, context: RequestContext, call_id: str, upper_bound: BudgetEnvelope) -> str: ... def settle(self, tx: object, reservation_id: str, actual: UsageReport) -> None: ... def mark_unknown(self, tx: object, reservation_id: str) -> None: ... def release_unsent(self, tx: object, reservation_id: str) -> None: ... ``` Der konkrete Adapter verlangt intern einen echten Foundation-Tx; `object` erhält die bereits veröffentlichte Signatur. `BudgetEnvelope` enthält `call_count`, `upper_input_tokens`, `upper_output_tokens`, `maximum_cost` und `cost_basis_revision`. `UsageReport` enthält optionale Input-/Outputtokens, `reported_cost`, `currency` und `status='reported'|'estimated'|'unknown'`. `reserve` löst Feature, kommerzielles Subjekt, Währung und optionale technische Budgets aus der serverseitigen Call-/Purposebindung auf, nicht aus zusätzlichen frei wählbaren Parametern. Ein internes `GatewayBudgetCoordinator.require_dispatchable(tx, context, call_id)` prüft nach vorhandener Callbindung die aktuelle Admission-/Policy-/Perioden-/Ausnahmebindung in T2. Das ist ein lokaler Koordinatorvertrag, keine neue öffentliche Gatewaymethode. `settle/mark_unknown/release_unsent` erhalten ihre Autorität aus dem unveränderlichen Call-/Reservierungsbezug und einem vertrauenswürdigen Gateway-/Recoverypfad; sie sind keine öffentlichen Kundenendpoints. ## 6. Messgrößen und belastbare Obergrenzen ### 6.1 Erste sichere Einheit: Modell-Sendeversuch Technischer Default für neue Modellkontingente ist **ein logischer Generate-Sendeversuch pro Call**, als Meter `generate_attempt`. Eine externe Antwort einschließlich Ablehnung/429/ungültigem Output belegt einen Versuch; sie garantiert keine fachlich erfolgreiche Analyse und keinen bestimmten Providerpreis. Sicher vor Sendbeginn verweigerte Arbeit zählt nicht. Möglicher Versand ohne Nachweis bleibt reserviert/ungeklärt. Das ist ausdrücklich eine technische Einheit. Ein Bestandsfeature namens `ai_calls`, das bisher erfolgreiche Analysen zählt, darf nicht stillschweigend umgedeutet werden. Sein Produktadapter muss die tatsächlich zugesicherte Einheit abbilden oder bei späterer Einführung eine versionierte neue Meterdefinition verwenden. Keine Kundentarife werden hier verändert. Unabhängig von der kommerziellen Einheit erfasst das technische Ledger jeden externen Versuch und jede Kostenunsicherheit. Ein Workflow mit drei ausgeführten Analysisnodes kann drei solche Versuche verursachen. Übersprungene Nodes verursachen keinen Generateverbrauch; lokale Pure Nodes ebenfalls nicht. Detection-/Tool-/Renderingkosten sind gegebenenfalls getrennte registrierte Zwecke und laufen nicht unsichtbar unter „ein erfolgreicher Workflow“. Im bisherigen Gatewaystandard ist Detection lokal; entsteht dort ein tatsächlich zu begrenzender Kostenverbrauch, benötigt er einen eigenen wirksamen Adapter. ### 6.2 Token- und Kostenbudgets Token-/Kostenmetriken können beobachtend, soft oder hart sein. `estimated` bleibt eine Schätzung. Keine Umdeutung in `reported`, keine fehlende Usage als Null. Die Generate-Callzahl besitzt die klare Obergrenze eins. Für Token-/Kostenobergrenzen reicht weder Zeichenlänge noch ein pauschales „Tokens ungefähr Zeichen/4“. Eine harte Tokenobergrenze verlangt einen für das konkrete Modell/Tokenizer-/Providerprofil gültigen oberen Inputwert einschließlich aller versendeten System-/Schema-/Fragefelder und einer wirksam erzwungenen Obergrenze aller erfassten Output-/Reasoninganteile. Eine harte Kostenobergrenze verlangt zusätzlich eine überprüfte versionierte Kostenbasis mit Währung, Preis-/Rundungsregel und allen erfassten Komponenten. Routing, Cachepreise, Reasoning, Tools und Gebühren dürfen keine ungebundene zusätzliche Wirkung erlauben. Der konkrete Adapter muss dies vor realer Nutzung nachweisen; in dieser Dokumentphase wird kein solcher Provider ausgewählt oder qualifiziert. Default ist deshalb harte Callanzahl plus beobachtende Tokens/Kosten. Wenn eine Produktpolicy eine harte Token-/Kostengrenze fordert und eine notwendige obere Schranke im `BudgetEnvelope` `None` ist, bleibt der Call mit `budget_bound_unavailable` geschlossen. Das ist keine Aufforderung, eine Schätzung als Maximum einzutragen. Technische Längen-/Outputgrenzen des Gateways bleiben zusätzlich bestehen. Kosten werden intern mit `Decimal` und festen ganzzahligen Untereinheiten je registrierter Währung geführt; Default Skala sechs Nachkommastellen. Obergrenzen und erfasste Beträge werden konservativ zur nächsten Untereinheit aufgerundet, nie nach unten oder über Binärfloat konvertiert. Die zugrunde liegende normalisierte Dezimalbeobachtung kann getrennt erhalten bleiben. Kein automatischer Währungswechsel oder FXkurs. Währung und Preisbasis stammen aus dem gebundenen Serverprofil; Widerspruch/Missingwert bedeutet unbekannte Kosten, keine Währungsvorgabe aus dem Browser. `reported_cost` ist zunächst eine validierte Providerbeobachtung. Ob sie für das jeweilige Budget als endgültige Kostengröße taugt, bestimmt der qualifizierte Adapter. Ein Providerfeld ist keine Kundenrechnung und keine Zusage über spätere externe Korrekturen. Ohne entsprechende Endgültigkeit bleibt die Restbindung eines harten Kostenbudgets bestehen. ## 7. Persistenz und rechnerische Invarianten Logische produktlokale Tabellen; konkrete Namen sind Defaults. Ein bestehendes Produkt darf seine Plan-/Granttabellen über Adapter weiterverwenden, sofern der vollständige Transaktionsvertrag erfüllt wird. Neue Tabellen werden nicht vorsorglich für ungenutzte Features angelegt. | Tabelle | Felder / Constraints | |---|---| | `entitlement_subjects` | PK aus Subjektart/lokaler ID; `entitlement_revision`, `row_version`, `recovery_blocked`, `integrity_blocked`; stabile Sperrzeile unabhängig von Plan und Monat | | bestehende Plan-/Grant-/Overridetabellen | Bekannte Plan-/Featurerevision, explizite enabled-/Limitpolicy, Gültigkeitsfenster, erwartete Version, Auditactor; keine unbekannten Tarifnamen als freie Berechtigung | | `quota_buckets` | Unique `(subject_kind, subject_id, meter_id, period_start, period_end, currency)`; Meterschema-/Periodenrevision, `used_known`, `held_total`, `held_unknown`, separat entsprechende Exemptmengen, `row_version`; nichtnegative Integer | | `usage_reservations` | UUID, unique `call_id`; unveränderliche Actor-/Scope-/QuotaSubjectbindung, Purpose-/Meterrevisionen, Input-/Envelope-HMAC samt Key-ID, Admissionzeit/-revision, Entitlement-/Kostenbasisrevision, Ausnahmebezug, Zustand/Version; FK zum bestehenden `ai_calls` | | `usage_reservation_lines` | Unique `(reservation_id, bucket_id)`; obere Menge, bekannte endgültige Menge, verbleibender Hold, Teilstatus, validierte Beobachtung; alle Einheiten explizit | | `usage_events` | Append-only ID, unique `(operation_id, event_kind, meter_id, revision)`; Reservation-/Callbezug oder lokale Fachoperation, Mengenänderung, Evidence-/Reasoncode, UTCzeit; kein Prompt-/Responsevolltext | | `quota_exemptions` | Bekannte Capability-/Feature-/Subjektbindung, Gültigkeitsfenster, Grantrevision, vergeben durch/Begründung; nur soweit Produkt solche Ausnahmen benötigt | | bestehendes Audit und `ai_calls` | Fach-/Administrationsaudit und Callzustand weiterverwenden; kein zweiter Provider-Callledger | `currency` ist ein nichtnull kanonischer Wert: ISOcode bei Kosten, registrierter neutraler Wert für Zählmetriken. Damit erzeugen SQL-NULLs keine mehrfachen scheinbar gleichen Buckets. FK-/Unique-Bindungen verhindern das Vertauschen von Call, Scope, Reservation und Subjekt; UUIDbesitz allein verleiht kein Buchungsrecht. Alte Subjekte werden bei Kontolöschung nicht als neue unbelastete Identität wiederverwendet. Minimalnachweise folgen dem lokalen Lösch-/Recoveryvertrag. Für eine endliche Menge `L` gelten bei einer neuen normalen Zulassung mit Obergrenze `q`: ```text beansprucht = used_known + held_total zulassen genau dann, wenn enabled und nicht gesperrt und q >= 0 und beansprucht + q <= L remaining = max(0, L - used_known - held_total) 0 <= held_unknown <= held_total ``` `held_unknown` ist eine Teilmenge des gesamten Holds, wird also bei `remaining` nicht nochmals abgezogen. Verbindliche technische Budgets zählen zusätzlich alle als kommerziell exempt markierten Mengen. Alle betroffenen Dimensionen/Subjekte bestehen per AND oder die gesamte Reservierung rollt zurück. Kein erfolgreiches Reservieren der Callzahl, wenn die notwendige Kostendimension gleichzeitig scheitert. Für einen Generatecall ist `BudgetEnvelope.call_count` strikt eins; zusätzliche Mengenobergrenzen können ausdrücklich null sein, wenn dieser Wert tatsächlich belastbar ist. Nullkosten sind kein Ersatz für fehlende Kosteninformation. Lokaler Ereignisverbrauch verlangt weiterhin eine positive serverseitige Menge. Integerüberlauf und übergroße numerische Eingaben werden vor Addition bzw. SQLwrite verweigert. Die Bedingung wird unter DBsperre geprüft und mit Bucket-/Reservierungs-/Event-/Auditwrite gemeinsam committed. Es gibt keinen DBconstraint `used+held <= aktueller Planlimit`: Downgrades und echte Providerabweichungen können einen bereits entstandenen Überhang verursachen. Dieser wird wahrheitsgemäß gespeichert und sperrt neue Zulassungen; er darf nicht zum Verlust tatsächlicher Usage führen. Nichtnegative Mengen, FKs, eindeutige Ereignisse und Zustandsversionen bleiben technisch erzwungen. Ein Bucket ist die atomar gepflegte Projektion des Ledgers. Reconciliation prüft beide Richtungen und markiert Abweichungen `integrity_blocked`; sie erfindet keine fehlenden Buchungen aus Logs. Bei Unsicherheit keine neue harte Zulassung. Reservations-/Operationstombstones verhindern nach Cleanup die erneute Buchung desselben bekannten Vorgangs. ## 8. Atomarität, Sperren und Idempotenz ### 8.1 Gemeinsame Sperrordnung Für Fachphasen gilt weiterhin der Auth-/Workflowvertrag: **Account → Session → Datenraum → Mitgliedschaft → geschütztes Fachobjekt bzw. Execution → Node/Call**. Der Quotenvertrag ergänzt danach **Entitlement-/Budgetsubjekte in stabiler Reihenfolge → Buckets in stabiler Reihenfolge → Reservation/Ereignis → Ergebnis/Audit**. Die Subjektreihenfolge ist kanonisch nach Klasse, Art und ID; keine Sortierung nach veränderlichem Plannamen. Jeder Adapter hält dieselbe Reihenfolge ein. Plan-/Grantänderungen sperren nur die betroffenen Entitlementsubjekte und danach ihre Konfiguration/Audit; sie laden anschließend keine Fachobjekte/Calls unter Sperre nach. Technische Usageabschlüsse finden die unveränderlichen Bezüge zuerst lesend, sperren dann nötige Execution-/Callzeilen und Subjekte in obiger Ordnung, niemals später ein Nutzerkonto. Bereits gehaltene Transaktionslocks bleiben bis Commit bestehen; keine zweite Connection für den Quotencheck. Ein Subjekt wird kontrolliert provisioniert oder per eindeutiger `INSERT ... ON CONFLICT DO NOTHING`-Anlage erzeugt und anschließend gesperrt. Zwei erstmalige Zugriffe dürfen keine parallelen freien Zähler erzeugen. Mit `READ COMMITTED` werden nach Erwerb der stabilen Sperre die effektive Policy und Buckets frisch gelesen. Andere Isolationsstufen benötigen passende Serialisierungsbehandlung; kein blinder Retry um eine Phase, die externen Versand enthalten könnte. ### 8.2 Reservieren `reserve` wird vom Gateway in **T2**, nach Rendering, Privacy-/Providerprüfung und Feststellung der belastbaren Bounds, unmittelbar vor dem Dispatchintent aufgerufen. T1 prüft frühzeitig die Funktion und Materialisierungsrechte; sie reserviert noch keine unbekannten Token-/Kostenwerte. Kostenpflichtige vorgelagerte Arbeit benötigte ihren eigenen registrierten Budgetvertrag. Die T2-UoW prüft aktuelle Identität, Scope/Objekt, Executionfence/Cancelzustand, Quellen und Policy; sperrt die Callbindung und alle nötigen Quotasubjekte; bestimmt DBzeit/Perioden und aktuelle Entitlementrevision; prüft alle Dimensionen; erzeugt Reservation, Holds und Reservierungsevent. Danach schreibt **dieselbe** UoW Dispatchintent/Bindings/Audit und markiert die Reservation als `dispatched` bzw. möglicherweise versendbar. Commit erst nach vollständigem Erfolg. Bei fehlgeschlagenem Commit gibt es keine gültige Dispatchpermit und keinen Send. Admissionzeit ist ein einmalig **nach Erwerb der Sperren** gelesener aktueller DBzeitwert, in PostgreSQL beispielsweise `clock_timestamp()`. Ein beim Transaktionsbeginn eingefrorenes `CURRENT_TIMESTAMP` darf nach Wartezeit nicht einen bereits abgelaufenen Grant oder Vormonat freigeben. Derselbe erfasste Wert bestimmt Gültigkeits- und Periodenentscheid; die Dispatchpermit begrenzt anschließend die Zeit bis Sendbeginn. Wiederholtes `reserve` derselben Call-ID mit derselben unveränderlichen Eingabe/Envelopebindung liefert dieselbe Reservation ohne zweiten Hold. Es muss den Ledgerzustand beachten: `dispatched/unknown` ist keine erneute Versanderlaubnis. Unterschiedliches Subjekt, Input, Purpose oder Envelope ergibt `reservation_conflict`. Eine legitime Sessionerneuerung verändert den HMAC der Facheingabe nicht, erfordert aber aktuelle Authprüfung. Der Gatewaykoordinator behandelt eine neue Policy-/Preis-/Quellenbindung als `context_changed`, nicht als kostenloses Resize einer bereits dispatchten Reservation. Eine Erneuerung der kurzen Gatewaypermit ohne jemals begonnenen Transport darf die bestehende Reservierung nur nach überprüfbarer exklusiver Sendkontrolle weiterverwenden. Kann der Adapter den Nichtversand nicht sicher belegen, bleibt `unknown`. Ein abgelaufenes Permit oder eine freie Workerlease allein ist kein Nachweis. Eine inzwischen andere Kalenderperiode oder kommerzielle Limitrevision erfordert gegebenenfalls Freigabe der sicher unversendeten alten Bindung und eine konsistente neue Admission. Inhaltliche Eingabe, Gateway-/Privacy-/Providerpolicy, Route und unveränderliche Envelopebindung werden dabei nicht still geändert; solche Änderungen bleiben `context_changed` und benötigen nach Gateway-/Workflowvertrag eine neue Ausführung. Für einen belegbar `failed_unsent`/`released_unsent` gebliebenen Call kann der interne Koordinator eine neue `admission_revision` derselben Reservation/Call-ID anlegen und Holds erneut atomar erwerben. Vorherige Admissions bleiben als Events erhalten; aktuelle Lines sind ihre Projektion, Ereignisschlüssel enthalten die Admissionrevision. Keine reaktive Admission bei `dispatched/unknown`, endgültig verbrauchter Menge oder fehlendem Nichtversandnachweis. Das ist der explizite Wiederaufnahmefall unversendeter Arbeit aus dem Workflow-Blueprint, kein allgemeiner Modellretry. Ein gewöhnliches Wiederholen von `reserve` allein reaktiviert keine freigegebene Reservation. ### 8.3 Idempotente Buchung und begrenzte Korrektur `settle`, `mark_unknown` und `release_unsent` sind zustandsgeprüfte Ereignisse mit eindeutigen Schlüsseln. Gleiches erneut angewendetes Ereignis ist ein No-op. Ein anderes angebliches Endergebnis für eine bereits endgültig gebuchte Metrik liefert `usage_conflict`; spätere tatsächliche Korrekturen laufen als benannte Reconciliationereignisse mit eigener Revision/Evidence, nicht als Überschreiben der Historie. `release_unsent` ist ausschließlich für bewiesenen Nichtversand zulässig. Ein nach Dispatchintent verlorener Prozess kann das nicht allein anhand fehlender Antwort beweisen. Im üblichen T2-Ablauf entstehen Reserve und Dispatchintent zusammen; es gibt daher kein reguläres langes „reserviert, aber noch nicht entschieden“-Zeitfenster. Ein benötigter lokaler Vorhaltefall muss die Reservation ausdrücklich `held_unsent` lassen und darf noch keinen Dispatch erlauben. Kein Kunde kann Reservation-ID, Usagewerte, `not_sent` oder einen Bypass per Body bestätigen. Interne Operationen sind fest an Call und registrierte Provideradapter gebunden. Begrenzte DBwiederholungen vor Dispatch bleiben lokale Transaktionswiederholungen; sie erzeugen keine zusätzlichen Modellversuche. ## 9. Abschluss, unbekannte Wirkung und Reconciliation ### 9.1 Zustände je Reservation und Metrik | Zustand | Bedeutung | Buchungsfolge | |---|---|---| | `held_unsent` | Nur vorgehalten, Sendbeginn sicher ausgeschlossen | Obergrenze belegt; nach erneutem Check dispatchen oder beweisbar freigeben | | `dispatched` | Dispatchintent committed, externe Wirkung möglich | Hold bleibt belegt; kein Replay und kein TTLrefund | | `unknown` | Versand/Verbrauch nicht abschließend geklärt | Ungeklärte Holds zählen weiter; neue externe Zulassung nach Default gesperrt | | `partially_settled` | Einige Metriken endgültig, andere unsicher | Bekannte Werte buchen; nur ungeklärte Restmetriken halten | | `settled` | Alle benötigten Budgetmetriken endgültig geklärt | Endgültige Mengen und freigegebene Restbindungen dokumentiert | | `released_unsent` | Nichtversand bewiesen | Alle nicht verbrauchten Holds atomar freigegeben; Calltombstone bleibt | `mark_unknown` verschiebt den noch offenen Hold in den Unknownanteil, ohne ihn zu erhöhen oder freizugeben. Für Metriken ohne endliche Reservierung wird eine sichere Unknownbeobachtung erfasst; fehlende Boundwerte werden nicht zu Null. `settle` kann z. B. die bekannte Callzahl eins und gemeldete Inputtokens buchen, während fehlende Kosten weiter unbekannt bleiben. Eine Headerphase wird aus allen Lines abgeleitet; sie ersetzt deren Gewissheitszustand nicht. Für eine endgültig verlässliche tatsächliche Menge `a <= q` verschiebt Settlement atomar `a` nach `used_known` und entfernt den gesamten zugehörigen Hold `q`; `q-a` wird damit frei. Für einen geschätzten Wert wird nur die Beobachtung gespeichert, nicht die harte Restbindung freigegeben. Ein tatsächlich gemeldeter endgültiger Nullwert ist möglich; ein nicht vorhandenes Feld ist kein Nullnachweis. Kosten und Tokens haben jeweils eigene Qualifikations-/Endgültigkeitsregeln, auch wenn `UsageReport.status` als Gesamthinweis nur einen Wert besitzt. Ein validierter tatsächlicher Verbrauch oberhalb der angenommenen Obergrenze wird vollständig und unverfälscht gebucht. Zusätzlich Integritätsincident und Sperre für neue betroffene Aufrufe; im Default keine fachliche Erfolgsfreigabe für den verletzten Budgetvertrag. Kein Clampen auf das reservierte Maximum und kein Rollback, das echte externe Wirkung verschwinden lässt. Eine harte Grenze kann nur unter der Voraussetzung nachgewiesener und eingehaltenen Transport-/Providerbounds zugesichert werden; die reine Reservierung verhindert keine Falschmeldung oder vertragswidrige Mehrverarbeitung des Providers. ### 9.2 Abschluss zusammen mit Gateway/Workflow Erfolgsfall T3: aktuelle Ausgabe-/Quellenrechte, Gatewayvalidierung und gegebenenfalls `WorkflowResultSink`; Ergebnis-/Nodecheckpoint, Callabschluss, `settle` und Audit in **derselben** Foundation-UoW. Scheitert ein auditpflichtiger Teil, ist der Fachcommit nicht erfolgreich. Der Workflow erhöht keine Zähler nochmals am Endknoten oder in einem HTTPresponsehook. Bei Entzug, Cancel, ungültigem Output oder fehlgeschlagenem Fachcommit kann bereits Verbrauch existieren. Ein enger interner Gatewayabschluss schreibt dann in einer **eigenen kurzen technischen UoW** ausschließlich bekannte Usage oder `unknown`, Calloutcome und Audit unter der unveränderten ursprünglichen Subjekt-/Reservierungsbindung. Er gibt keine Fachrechte, speichert keinen verworfenen persönlichen Output und erzeugt keinen neuen Call. `settle` verlangt deshalb keinen weiterhin berechtigten Endnutzercontext; seine Autorität ist die vertrauenswürdige technische Callbindung. Diese Ausnahme von fachlicher Nutzerfreigabe berechtigt ausschließlich zur wahrheitsgemäßen Buchung bereits entstandener Wirkung. Ist die Datenbank nicht verfügbar oder stürzt auch dieser Abschluss ab, bleibt der vorher atomar gespeicherte Dispatchhold bestehen. Recovery setzt offene `dispatched`-Vorgänge konservativ auf `unknown`, statt erneut zu senden oder die Reservation freizugeben. Ein HTTPfehler, Provider429, Timeout, verlorenes Browserfenster oder Cancel ist allein keine Aussage über Kostenfreiheit. ### 9.3 Ungeklärte Fälle und spätere Belege Ein automatischer Job darf bekannte Ledgerzustände rekonstruieren, Holds prüfen und auf Integritätsfehler schließen. Er darf keine modellgenerierende Wiederholung auslösen. Lesende providerbezogene Statusklärung ist nur über einen bereits qualifizierten Adapter mit stabiler Requestreferenz und ohne zusätzlichen Generate zulässig; ein solcher Adapter ist keine Voraussetzung dieses ersten Schnitts und wird hier nicht entwickelt. Ohne technische Endinformation bleibt der Fall blockiert oder wird über einen ausdrücklich berechtigten lokalen Reconciliationservice geklärt. Dieser erhält einen vorhandenen Call-/Reservierungsbezug, erwartete Version, eindeutigen Evidencebezug, betroffene Metrik und die begründete Art `final_usage` oder `proved_unsent`. Er prüft keine freien Kundendaten als Beweis. Konfligierende Belege oder fehlende klare Zuordnung verweigern die Änderung. Kein öffentliches „Verbrauch zurücksetzen“-Endpoint. Eine kulante zusätzliche Nutzungsfreigabe ist eine eigene befristete Entitlement-/Allowanceänderung. Sie darf im Ledger nicht so tun, als sei der alte unsichere Call kostenlos gewesen; technische Kostenlimits und Unknownsperre bleiben bestehen, soweit die neue Freigabe sie nicht unter einem ausdrücklich begrenzten echten Risiko-/Reconciliationvertrag adressiert. Dieser Blueprint führt keinen solchen automatischen Kreditmechanismus ein. ## 10. Perioden, Planwechsel und Quoten-Ausnahmen ### 10.1 Unveränderliche Zeitfenster Default sind UTC-Kalendertag oder UTC-Kalendermonat in `[starts_at, ends_at)`; ein Monatsende ist kein Zeitraum von pauschal 30 Tagen. Die DBzeit beim verbindlichen T2-/lokalen Buchungsentscheid bestimmt die Zuordnung, nicht Browserzeit, Antwortzeit oder letzter Login. Der bis zum Sendbeginn höchstens kurz gültige Dispatchpermit kann über eine Periodengrenze reichen; Zuordnung bleibt ausdrücklich der dokumentierte Dispatchentscheidzeitpunkt. Ein neuer Monat erzeugt einen neuen Bucket, setzt aber keinen alten Zähler auf Null. Späte Antworten und Korrekturen buchen weiter in die ursprünglichen Buckets. Reads sind nebenwirkungsfrei und benötigen keinen Resetcommit. `inventory` hat keine Monatsperiode; `never` ist kein Synonym für „jeden Monat neu“ und in diesem ersten Schnitt kein pauschaler unendlicher Ereigniszähler. Unknowns werden durch einen Periodenwechsel nicht vergessen. Konservativer Default: ein ungeklärter externer Call sperrt neue externe Reservations desselben kommerziellen Subjekts und derselben Purpose-/Metergruppe auch über Perioden hinweg, bis er geklärt ist. Endgültig bekannte Metriken ohne unbekannte harte Budgetkomponente lösen diese Sperre nicht aus. Beobachtend fehlende Token-/Kostenfelder sperren reine Callkontingente nicht, solange der Callversuch selbst geklärt ist. Ein Produkt kann statt dieser konservativen Sperre später eine nachgewiesen begrenzte offene Risikoobergrenze verwenden; bloßes TTLablaufen reicht nicht. Zeitzone, Periodenart, Metersemantik und Währung werden innerhalb eines laufenden Fensters nicht gewechselt. Eine notwendige spätere Umstellung benötigt ausdrücklich gebundene Übergangsfenster ohne kostenlose Doppelkontingente; im ersten Schnitt nur zum kompatiblen Folgebeginn. Ein Client kann keine Monats-ID mitsenden und so einen alten/unbelasteten Bucket auswählen. ### 10.2 Plan-/Grantwechsel Upgrade, Downgrade und zeitlicher Grant ändern die effektive verfügbare Menge, **nicht** die Bucketidentität oder den bisherigen Verbrauch. Vor Dispatch wird die aktuelle Revision unter derselben Subjektsperre geprüft. Eine nach Dispatch geänderte Berechtigung ändert die historische Subjekt-/Ausnahme-/Preisbindung dieses bereits möglichen Verbrauchs nicht. Aufnahme und neue Nodes müssen den aktuellen Stand erneut bestehen. Für sicher unversendete Vorreservierungen prüft T2 bei Planänderung neu. Reicht der neue Plan nicht, keine Dispatchfreigabe; alte unversendete Holds werden konsistent freigegeben. Bereits mögliche externe Wirkung wird weiterhin gebucht, selbst wenn der neue Plan keinen weiteren Call mehr erlauben würde. Grantablauf kann auch ohne DBupdate eintreten; daher Zeitfenster und nächste Gültigkeitsgrenze bei jedem Aufnahme-/Dispatchentscheid frisch prüfen, nicht nur `entitlement_revision` vergleichen. ### 10.3 Explizite Ausnahmen Shinkans Bypasscapabilities bleiben die geeignete Referenz. Im neuen Vertrag braucht eine Ausnahme eine bekannte Capability, ein Feature/Meter, ein zulässiges Subjekt, Zeitraum, Grantrevision und Audit. Kein pauschales `is_admin => unlimited`, kein `ENFORCE=0` für harte zugesagte Features. Vergabe/Änderung einer privilegierten Ausnahme nutzt aktuelle Betreiberrechte und MFA-Step-up des Auth-Blueprints. Default maximal 30 Tage, danach nur erneute ausdrücklich begründete Verwaltung, kein automatisches Verlängern. Die kommerzielle Ausnahme überspringt nur die bezeichnete endliche kommerzielle Menge. Feature-Kill-Switch, fehlende Funktionsfreigabe, AccessPolicy, Quell-/Privacygrenzen, Maschinenbefugnisse und technische Betriebsbudgets bleiben wirksam. Eine Freischaltung einer sonst deaktivierten Funktion ist ein eigener expliziter Grant. Exemptverbrauch wird vollständig mit derselben Call-/Operationidentität erfasst, als solcher getrennt ausgewiesen und im Default nicht vom normalen Vereinskontingent abgezogen; technische Gesamtkostenbudgets zählen ihn mit. Dazu gehören auch Exemptholds und Unknownmengen. Ein entfallener Grant nach Dispatch macht historische Vorgänge nicht rückwirkend normal oder kostenfrei. Der gewählte Admissionstatus bleibt im Ledger gebunden; neue Aktionen erhalten keine alte Ausnahme. ## 11. Lokale Fachwrites und Bestandsgrenzen ### 11.1 Periodischer lokaler Verbrauch Bei einer reinen DBfachaktion werden aktuelle Rechte, Featurefreigabe, atomare Kapazität, fachlicher Write, Verbrauchsevent und Audit in einer Transaktion verarbeitet. Eine separate Reservation über Netzwerkphasen ist dafür unnötig. `LocalUsagePort.consume` und Fachwrite dürfen niemals unabhängig committen. Illustration V/K für einen registrierten lokalen periodischen Zähler; Services und Repositories sind konkret im Zielprodukt zu verdrahten: ```python def create_training_unit(self, context, command): with self.uow.transaction() as tx: self.access.require(context, "training_units.create", None, tx) self.entitlements.require(context, "training_units", tx) existing = self.operations.find_existing(tx, context, command.operation_id) if existing is not None: result = self.units.read_authorized(tx, context, existing.result_id) else: self.usage.consume( tx, context, operation_id=command.operation_id, feature_id="training_units", quantity=1, ) row = self.units.create(tx, context, command) self.operations.complete(tx, context, command.operation_id, row.id) self.audit.changed(tx, context, "training_unit.created", row.id) result = self.outputs.training_unit(row) return result ``` `operations.find_existing` steht für den transaktionalen Idempotenzadapter: er bindet Subject/Scope und Input-HMAC, verhindert parallele Doppelaufnahme durch Uniqueconstraint/Sperre und liefert bei anderer Eingabe 409. Der dargestellte Kontrollfluss allein wäre ohne diese Semantik nicht konkurrenzsicher. Auch ein Wiederabruf prüft aktuelle Objektleserechte. Auditfehler, fachlicher Konflikt oder nicht erfolgreicher Commit rollen Verbrauch und Fachwrite zusammen zurück. Bei periodischem Ereignisverbrauch gibt das Löschen einer früher angelegten Einheit das historische Ereignis nicht automatisch zurück. Die jeweilige Zähleinheit muss dies klar sagen. Ein Bestandslimit verhält sich dagegen wie folgt. ### 11.2 Inventar / Bestand Der Bestandsadapter zählt exakt die in der registrierten Definition festgelegten Objekte, z. B. aktive Mitgliedschaften oder nicht archivierte Übungen des Clubs. Alle bestandsändernden Pfade – Anlegen, Löschen, Archivieren, Wiederherstellen, Statuswechsel, Import und administrative Mutation – sperren dieselbe stabile Subjektzeile und prüfen Delta und tatsächlichen Bestand in derselben Fach-UoW. Der Subjektlock serialisiert diese Writer; ein nacktes `SELECT COUNT` ohne gemeinsamen Writervertrag genügt nicht. Für den ersten Schnitt ist der echte indizierte DBbestand unter Sperre maßgeblich; keine unqualifizierte Synchronisierung eines separaten In-Memory-Zählers. `delta>0` verlangt `Bestand + delta <= Limit`. Bestandssenkung bleibt bei bestehendem Zugriffsrecht auch nach Downgrade möglich. Doppelte/deaktivierte Datensätze, Wiederaktivierung und mehrere physische Tabellen derselben Fachmenge müssen im registrierten Selektor ausdrücklich definiert sein. Shinkans Livebestandsfilter sind dafür gezielte Ausgangspunkte, kein universeller `COUNT(*)` über alle Tabellen. Harte Bestandsgrenzen sind erst nachgewiesen, wenn **alle** Writer im Zielprodukt diesen Vertrag erfüllen. Direkte privilegierte DBwrites und unadaptierte Altrouten können ihn umgehen; bis deren tatsächliche Abdeckung geklärt ist, nur Softlimit zusagen. Dieser Blueprint behauptet diese Bestandsabdeckung nicht und nimmt keine Repoanpassung vor. ### 11.3 Bulk/Import und technische Abgrenzung Ein Import bindet valide Eingaben und tatsächliche Duplikat-/Änderungsregeln; unter dem Subjektlock wird die wirkliche positive Menge bestimmt. Default: gesamter begrenzter Batch in einer UoW, keine Teilerfolge ohne expliziten Fachvertrag. Limitverletzung oder Auditfehler rollt alle neuen Zeilen und die Buchung zurück. Bereits vorhandene Duplikate verbrauchen bei einem Bestandslimit keinen zusätzlichen Platz; historische periodische Importereignisse sind eine andere registrierte Einheit. Keine Usageeinheit aus dem Dateinamen oder der Zahl ungeprüfter Uploadzeilen ableiten. Dateispeicher, Renderingjobs, Webhooks und andere externe Wirkungen sind kein reiner DBwrite. Sie benötigen ihren eigenen passenden Wirkungs-/Reservierungsadapter; der lokale `consume`-Port ist dafür allein ungeeignet. Dieser Blueprint erfindet keine neue Medien-/Importengine und keinen Zahlungswebhook. An bestehende Adapterschnittstellen später gezielt anschließen. ## 12. API, Fehler und Frontend ### 12.1 Lesender Entitlementsnapshot Default `GET /api/v1/me/entitlements` verwendet den verifizierten Scope aus Phase 3.3; kein frei umleitender Queryparameter für fremde Clubs. Er liefert aktuelle Capabilitydarstellung und registrierte Featureentscheidungen. Der kommerzielle Teil enthält `quota_subject` nur soweit sichtbar, `entitlement_revision`, UTC-`as_of`, Feature-/Meterrevisionen, Zähleinheit, Periodenbezug, `admission_mode='observe'|'soft'|'hard'` und sichere Reasoncodes. Bei sichtbarer endlicher Menge: expliziter Limitmodus und Wert, `used_known`, `held_total`, `held_unknown`, `remaining`, getrennte Exemptaggregate und `period_start/end`. Bei unbegrenzt: `limit.mode='unlimited'`, kein behauptetes unendliches Remaining. Bei nicht erlaubter Verbrauchssicht: `visibility='hidden'` und keine Beträge; dies bedeutet nicht unbegrenzt. Ein berechtigtes Mitglied kann trotzdem `feature.enabled` und eine sichere Aussage `available/exhausted/temporarily_blocked` für seine Aktion sehen. Einzelne fremde Verbräuche bleiben verborgen. Beispiel eines synthetischen sichtbaren Featureausschnitts; Menge/Plan ist keine Produktempfehlung: ```json { "feature_id": "analysis_generate", "enabled": true, "meter_id": "generate_attempt.v1", "unit": "generate_attempt", "admission_mode": "hard", "visibility": "summary", "limit": {"mode": "finite", "value": 10}, "used_known": 3, "held_total": 2, "held_unknown": 0, "remaining": 5, "period_start": "2026-10-01T00:00:00Z", "period_end": "2026-11-01T00:00:00Z", "reason": "available" } ``` `GET /api/v1/usage` liefert nur berechtigte eigene/ausdrücklich freigegebene aggregierte Einträge mit `{items,next_cursor}`. Ein Clubsummary erfordert die benannte Capability. Ein Defaultnutzer erhält keine ProviderrequestIDs, internen Evidencebelege, anderen Actor-IDs oder Kosten anderer Räume. Detailedger ist eine getrennte Betreiber-/Abrechnungsfunktion mit aktuellem Zugriffs-/MFAvertrag, kein allgemeiner Frontendzustand. Schreibende Fachrouten bleiben beim Produkt/Gateway. Es gibt kein öffentliches `POST reserve`, `settle`, `increment`, `refund` oder `reset_usage`. Lokale Plan-/Grant-/Ausnahmeverwaltung nutzt bestehende privilegierte Verwaltungsrouten oder einen schmalen späteren Adapter mit `expected_version`, vollständiger Subjektbindung und Audit. Neue Payment-/Checkoutendpoints werden nicht angelegt. ### 12.2 Fehlervertrag RFC-9457-`application/problem+json` gemäß Foundation mit sicheren Codes und `request_id`; keine Rohprovider-, SQL-, Usage-Evidence- oder persönlichen Werte in Errors. | HTTP / Code | Bedeutung / Verhalten | |---|---| | 401 `session_required/session_expired` | Keine aktuelle Identität; keine Reservierung/Neuzulassung | | 403 `capability_required/feature_not_enabled` | Eigene Aktion fachlich oder kommerziell nicht freigeschaltet | | 404 `not_found` | Fremdes/unsichtbares Objekt, Quotasubjekt oder Consumptiondetail | | 409 `quota_exhausted/inventory_limit` | Verbindliche Aktion passt nicht in vorhandene Kapazität; keine automatische Mutationwiederholung | | 409 `context_changed/reservation_conflict/usage_conflict/version_conflict` | Bindung, Policy oder erwarteter Stand ist widersprüchlich | | 409 `usage_unresolved/quota_recovery_required` | Mögliche externe Wirkung bzw. wiederhergestellter unvollständiger Stand blockiert neue harte Aufnahme | | 422 `input_invalid/quota_quantity_invalid` | Ungültige fachliche Eingabe, negative/typfalsche Menge; keine großzügige Konvertierung | | 429 `execution_capacity/rate_limited` | Technische Frequenz-/Parallelitätsgrenze, nicht das erworbene Monatskontingent | | 503 `entitlement_policy_unavailable/budget_bound_unavailable/quota_integrity_failed` | Erforderliche technische Policy/Bound/Integrität fehlt; kein Fallback auf unbegrenzt | Ein erschöpftes Monatskontingent kann einen sicheren `period_end`-Hinweis enthalten; das Frontend startet deshalb keinen automatischen POSTretry. Provider429 bleibt der Gatewayfehler und wird nicht als sichere Quotenfreigabe interpretiert. Ein GET des eigenen Laufstatus kann weiterhin 200 mit `paused_unknown` oder anderer sicherer Statusinformation liefern; das bedeutet keine erfolgreiche Neuzulassung. ### 12.3 Frontendanschluss Plan-/Featureentscheidungen kommen vom Snapshot, nicht aus hardcodierten Tarifnamen. Widgetanforderungen verwenden dieselbe explizite Featurezuordnung wie Backend und Registry; bei mehreren Anforderungen gilt AND. Neue Requirements und fehlgeschlagene Loads werden nicht als „keine Anforderungen“ behandelt. Ausblenden/Deaktivieren im UI ersetzt niemals die erneute serverseitige Prüfung der Fachaktion. Nach relevanter Mutation kann der Server einen sicheren aktuellen Usageausschnitt aus dem committed Zustand liefern. Der Client darf ihn lesen und später neu laden; er erhöht keine Zähler optimistisch als Wahrheit. Bestehender gemeinsamer APIclient, HttpOnly-/Secure-/SameSite-Cookies, CSRF/Origin, `no-store`, Scopeepoch und Abort gelten unverändert. Nach Scopewechsel alte Erfolgs-/Fehler-/401-/Usageantworten verwerfen. Keine Tokens oder persönlichen Consumptiondetails in LocalStorage/PWAcache. Ein Planupgradebutton ist in dieser Phase kein Auftrag für Checkout oder Zahlungsintegration. ## 13. Betrieb, Restore und Datenschutz Aufbewahrung bezieht sich auf minimale technische Mengen, Actor-/Scope-/Call-/Reservationsbezüge und sichere Evidencecodes; keine Prompt-/Outputvolltexte, Gesundheitswerte, E-Mailadressen oder Credentialinhalte im Usageledger. Interne Kontoreferenzen sind geschützt, keine frei exportierbaren anonymen Statistiken. Finale technische Buchungsdaten bleiben standardmäßig für den laufenden und die zwölf vorherigen Kalendermonate verfügbar; das ist ein anpassbarer technischer Ausgangswert, keine gesetzliche Aufbewahrungsfrist. Private Fachdaten folgen weiterhin ihren eigenen Fristen. Offene/ungeklärte, referenzierte und für zugesicherte Idempotenz benötigte Bindungen werden nicht durch eine pauschale Retention gelöscht. Nach zulässiger Verdichtung bleiben erforderliche Outcome-/Deduptombstones und Aggregatkonsistenz erhalten. Cleanup gibt keine Holds frei, setzt keine unbekannten Werte auf Null und schafft keine neue freie Operation. HMAC-Key-ID und nötige alte Keyversionen folgen dem Gateway-/Recoveryvertrag. Backup/Restore umfasst Buckets, Reservations, Events, Callledger und fachliche Ergebnisreferenzen im selben Datenkonsistenzpunkt. Writerfreeze beinhaltet Gateway-T2/T3, Workflowrunner, lokale Fachwriter, Reconciliation, Plan-/Grantverwaltung und Cleanup. Bei Restore auf einen älteren Stand können bereits versendete, im Backup aber fehlende Calls existieren. Ein leerer wiederhergestellter Zähler ist deshalb kein Beweis freien Budgets. Default nach Restore: aktuelle Sessions/Claims gemäß Auth-/Recoveryvertrag invalidieren und alle betroffenen wiederhergestellten Quotasubjekte für neue harte Zulassungen `recovery_blocked` setzen. Das betrifft neben externen Calls auch historische periodische DBereignisse, soweit deren Ledger seit dem Backup unvollständig sein kann. Offene Dispatches/Reservierungen bleiben ungeklärt, alte Workflows starten nicht automatisch neu. Fehlende Buchungen seit Backup werden aus vertrauenswürdigen vorhandenen Belegen rekonstruiert oder konservativ als ungeklärte Risikoexposition behandelt; bloßes Neuansetzen des laufenden Monats reicht nicht. Reine Bestandsgrenzen können nach überprüfter Integrität am tatsächlich restaurierten Bestand wieder qualifiziert werden; sie beweisen keinen vollständigen historischen Ereignisverbrauch. Ohne ausreichenden Nachweis bleibt die betroffene harte Aufnahme geschlossen. Freischaltung ist eine gezielte protokollierte Recoveryoperation, kein neuer pauschaler Familienfreigabeprozess. Es wird kein zusätzlicher zentraler Dienst oder vermeintlich atomarer DB-/Provider-/Dateijournalmechanismus verlangt. Bestehendes geschütztes Operationsjournal und tatsächlich verfügbare Provider-/Operationsbelege können beim späteren Reconcile helfen; ihre Vollständigkeit wird nicht vorausgesetzt. Image-Rollback auf eine unveränderte aktuelle DB setzt keine Kontingente zurück; tatsächlicher Datenrestore braucht die obige Nachbehandlung. Reconciliation und Recovery sind selbst idempotent und mit erwarteter Ziel-/Zeilenversion geschützt. ## 14. Technische Defaults und Anti-Patterns | Default | Wahl / Grenze | |---|---| | Erste KI-Hardquota | Call-/Generateversuchseinheit, ausdrücklich produktseitig benannt; Tokens/Kosten beobachtend | | Perioden | UTC-Kalendermonat, bei tatsächlichem Bedarf UTC-Kalendertag; keine rollierende 30-Tage-Imitation | | Mengen | Nichtnegative `BIGINT`-Untereinheiten, strikte Eingabegrenzen vor Arithmetic; Kosten Decimal, Skala 6, konservatives Aufrunden | | Konkurrenz | Produktlokale PostgreSQLsperren, stabile Subjektzeile; kein prozesslokaler Lock als einzige Garantie | | Vorhaltefrist | Falls wirklich `held_unsent` benötigt: 2 Minuten; Freigabe nur mit positivem Nichtversandnachweis; dispatched/unknown ohne TTLrefund | | Unknownverhalten | Neue externe Aufnahme derselben Subjekt-/Purposegruppe blockiert, soweit ein harter Budgetbestandteil ungeklärt ist | | Verwaltung | `expected_version`, begründete Änderungen, bestehendes MFA; Quoten-Ausnahme im Default höchstens 30 Tage | | Lokaler Bulk | Maximal 1.000 fachlich validierte Zeilen pro atomarem Batch; engere Produkt-/DBgrenzen gelten | | Readmodel | Persönlich/Scopegebunden, no-store; im ersten Schnitt keine erlaubnisgebende Entitlementcache-Schicht | | Ledgerretention | Laufender plus 12 vorherige Monate für finale technische Buchungen; offene/referenzierte Bindungen gesondert erhalten | Vermeiden: - Plan/Tier als Rolle oder Objekterlaubnis verwenden; UIbadge als APIgate; fremdes `billing_subject_id` aus einem Request akzeptieren. - Fehlender Featureeintrag, kaputter Integer, SQLfehler oder nicht konfigurierter Adapter ergibt `unlimited`; probe/off als zugesicherte harte Grenze ausgeben. - `check → externer Call → increment` ohne Reservation; Parallelität mit einem Pythonlock oder einer ContextVar als gelöst betrachten. - Monatlichen Zähler beim GET zurücksetzen; Planwechsel erzeugt neuen Bucket; spätes Ergebnis dem Antwortmonat zurechnen. - Schätzung als Obergrenze, fehlende Usage als Null, Timeout/Cancel/429 als Kostenfreiheit oder TTL als Refundbeleg behandeln. - Usage nur nach gültigem Fachoutput buchen; Callledger erfolgreich abschließen und Ergebnis-/Verbrauchscommit später getrennt schreiben. - Pauschaler Adminbypass oder Ausnahme ohne Scope/Feature/Zeit; exempten Verbrauch unsichtbar machen oder technische Gesamtkostenbudgets umgehen. - Bestand und historische Ereignisse vermischen; Duplikate oder Löschungen mit unpassender Zähleinheit buchen; unadaptierte Writer bei Hardquotazusage ignorieren. - Alte Calls durch Retention/Restore vergessen, bekannte Call-ID erneut ausführen, unterschiedliche Endabrechnungen still überschreiben oder echte Überhänge wegclampen. ## 15. Automatisierte Sicherheits-, Konkurrenz- und Negativtests Die Matrix ist ein **Testauftrag V/K**, kein Bericht bestandener Prüfungen. Synthetische Fixtures: zwei persönliche Subjekte, zwei Clubs mit mehreren Mitgliedern, ein Operator ohne private Objektleserechte, eine explizite begrenzte Ausnahme, zwei Planrevisionen, kontrollierte UTCzeit sowie mindestens zwei echte unabhängige DBconnections. Modell-/Providerzugriff ausschließlich als Fake mit Sendzähler und genau gesetzten Crashbarrieren. | ID | Prüfung | Erwartung | |---|---|---| | EUQ-01 | Unbekanntes Feature, Meter, doppelte Registry-ID oder nicht implementierter Adapter | Geschlossen; kein stilles Defaultrecht | | EUQ-02 | Missing, `0`, `NULL` in vorhandener Limitzeile, negativer/defekter Wert | Disabled/finite/unlimited/unavailable eindeutig; kein unfreiwilliges Unlimited | | EUQ-03 | Fehlendes/fremdes Profil, manipuliertes billing_subject oder Clubscope | Keine Fallbackidentität; kein fremdes oder billigeres Kontingent | | EUQ-04 | Zweites Mitglied desselben Clubs führt denselben Featuretyp aus | Gemeinsamer Clubbucket, keine Quote pro Session/Trainer | | EUQ-05 | Capability fehlt trotz freiem Kontingent; fremdes Objekt trotz Premium | AccessPolicy verweigert; kein kommerzielles Gate erweitert Objektzugriff | | EUQ-06 | Zwei Features nötig, eines gesperrt; UIrequirementsload scheitert | AND verweigert; Ladefehler wird nicht zur leeren Anforderung | | EUQ-07 | Operator ohne Ausnahme und ohne private Leserechte | Kein automatischer Bypass und kein Fremdledgerzugriff | | EUQ-08 | Aktive/abgelaufene/fremde featurebezogene Ausnahme | Nur exakt gebundene zulässig; Ablauf bei Aufnahme erneut geprüft | | EUQ-09 | Exemptcall mit technischem Produktbudget nahe Grenze | Kommerziell getrennt erfasst; technisches Gesamtbudget weiter bindend | | EUQ-10 | Zwei unabhängige Reservierungen bei `L=1` gleichzeitig | Genau eine neue Aufnahme, ein Hold; zweiter Call null Sends | | EUQ-11 | Gleiche Call-ID parallel und später erneut, gleiche/andere Envelopebindung | Eine Reservation; idempotenter Wiederabruf oder 409, kein Doppelhold | | EUQ-12 | Erstmalige konkurrierende Subjekt-/Bucketanlage | Eine stabile Sperrzeile/ein Bucket; keine freie Parallelkapazität | | EUQ-13 | Mehrere Metriken/Subjekte, zweite Grenze erschöpft | Vollständiger Rollback aller ersten Holds/Events | | EUQ-14 | Audit-/Reservierungs-/Dispatchwrite oder Commit in T2 scheitert | Kein Send, keine gültige Permit; keine Teilbuchung | | EUQ-15 | Crash unmittelbar nach T2commit, vor/bei/nach Sendbeginn | Persistenter Hold; konservativ unknown, keine automatische Generatewiederholung | | EUQ-16 | Erfolgreiche Antwort und Crash nach T3commit vor Rückgabe | Ergebnis-/Node-/Call-/Usagecheckpoint gemeinsam; kein doppelter Verbrauch | | EUQ-17 | Fach-/Node-/Auditwrite scheitert in T3 nach bekanntem Verbrauch | Kein Facherfolg; enger technischer Abschluss erfasst bekannte Usage/unknown | | EUQ-18 | Rechteentzug, Sessionexpiry, Cancel oder Scopewechsel während Await | Keine verspätete Fachfreigabe; ursprünglicher Verbrauch bleibt korrekt zugeordnet | | EUQ-19 | Ungültiger Output, Refusal, HTTP429/5xx, Timeout und Clientdisconnect | Kein Refund aus Fehlerstatus allein; bekannte Versuche und unsichere Metriken unterschieden | | EUQ-20 | `release_unsent` nach bewiesenem Nichtversand vs. nach Dispatchintent ohne Beweis | Nur erster Fall gibt Hold frei; zweiter bleibt ungeklärt | | EUQ-21 | Wiederholtes mark_unknown, settle und release; widersprüchlicher Endreport | No-op für Gleiches; sicherer Konflikt für Widerspruch | | EUQ-22 | Report enthält bekannte Callzahl/Inputtokens, aber keine Kosten/Outputtokens | Teilsettlement; kein fehlendes Feld als Null; Resthold bleibt | | EUQ-23 | Estimated gegenüber endgültig qualifiziertem reported-Wert | Estimate gibt Hardhold nicht frei; Endbeleg erlaubt korrekte Differenzfreigabe | | EUQ-24 | Tatsächlicher Verbrauch über Bound | Vollständig gebucht, Incident und Neuaufnahmesperre; kein Clampen/Verlust | | EUQ-25 | Harte Tokens/Kosten verlangt, notwendiger Bound None oder nur Schätzung | budget_bound_unavailable, Sendzähler null | | EUQ-26 | Dezimalgrenzen, Float/NaN/Infinity, negative Menge, falsche Währung | Strikte Ablehnung bzw. sichere Unklarheit; korrektes konservatives Rundungsverhalten | | EUQ-27 | Monatswechsel, Dezember/Januar, UTCgrenze, verspätete Antwort | Exakte halboffene Fenster; ursprünglicher Bucket für Antwort/Settlement | | EUQ-28 | GET am Periodenende und wiederholte Snapshots | Nebenwirkungsfrei, kein Reset-/Commit-/Usageevent | | EUQ-29 | Unknown aus Vormonat und Beginn neuen Monats | Historischer Hold bleibt; Default-Neuaufnahmesperre wirksam | | EUQ-30 | Wechsel Plan/Override/Grant unmittelbar vor/nach Dispatch | Frische Zulassung; historische Bindung nach Dispatch bleibt; kein freies Neukontingent | | EUQ-31 | Grantablauf ohne Update der Revision | Zeitprüfung erkennt Ablauf trotzdem | | EUQ-32 | Überlappende Grants, kaputte Planzuordnung oder nicht erlaubte Periodenumstellung | Schreiben/Admission geschlossen; keine willkürliche Auswahl | | EUQ-33 | Downgrade unter Bestand/used+held | Keine Datenlöschung; neue positive Menge blockiert, erlaubtes Lesen/Löschen möglich | | EUQ-34 | Zwei lokale DBcreates für letzten Ereignis-/Bestandsplatz | Höchstens ein zusätzlicher Commit; Ledger und Fachdaten stimmen | | EUQ-35 | Fehlgeschlagener lokaler Write, Duplicate/Idempotenzretry, Auditfehler | Kein Phantomverbrauch, keine doppelte fachliche Operation | | EUQ-36 | Archivieren, Reaktivieren, Löschen und neuer Import desselben Bestands | Exakter registrierter Filter/Delta; alle Writer teilen den Lock | | EUQ-37 | Bulk mit Duplikaten, Limit mitten im Batch oder ungültiger Zeile | Wirkliche Menge; Default vollständiger Rollback bei Verletzung | | EUQ-38 | Periodischer Ereignisverbrauch und spätere Löschung | Kein unberechtigter Refund; Bestandssicht separat korrekt | | EUQ-39 | Workflow mit drei Analysisnodes, einem Skip und einem Pure Node | Nur tatsächliche logische Modellversuche gezählt; kein zweites Endknotenbilling | | EUQ-40 | Caller versucht UsageReport, not_sent oder Exemption frei einzusenden | Öffentliche DTOs verweigern; nur vertrauenswürdiger interner Adapter | | EUQ-41 | Fremder Club-/Member-/Reservierungslookup und vertauschte FKs | Kein Fremdverbrauch/Leak; sichere 404/403; DB-/Servicebindung wirksam | | EUQ-42 | Scopeepochwechsel mit altem Usageerfolg/Fehler/401 | Alte Antworten verworfen; kein falsches Quotenbadge/Logout | | EUQ-43 | Verlorene HMAC-Keyversion, Bucket-/Eventdrift, kaputte Projektion | integrity_blocked; keine neue freie Operation oder automatische Kostenlöschung | | EUQ-44 | Cleanup von finalem vs. offenem/referenziertem Ledger | Fristen korrekt, benötigte Tombstones/Holds bleiben; kein Replay | | EUQ-45 | Restore eines Backups vor weiteren externen Calls | Recoveryblocked statt vollem frischem Budget; alte Sessions/Claims gesperrt | | EUQ-46 | Doppelte Reconciliation, fremder/mehrdeutiger Beleg oder stale Version | Eindeutiger idempotenter Abschluss oder Verweigerung; keine Doppelgutschrift | | EUQ-47 | Logs/Problem-/Status-/Entitlement-DTO mit privaten Canarywerten | Keine Prompt-/Output-/Credential-/Fremdmitgliedswerte; Sichtbarkeit korrekt | | EUQ-48 | Import API/Runner ohne DB/Provider, Ausfall erforderlicher Policy | Keine Importnebenwirkung; geschlossene Runtimeentscheidung statt Unlimited | | EUQ-49 | Parallel Planwechsel, reservieren, canceln, settle und reconcile | Einheitliche Lockordnung; keine Doppelbuchung, kein unkontrollierter Retry | | EUQ-50 | Kompatibilitätsadapter für bestehendes `ai_calls` mit anderer Einheit | Explizite Version/Zuordnung; keine stille Umdeutung erfolgreicher Analyse in Sendeversuch | | EUQ-51 | Sperrwartezeit über Monats-/Grantgrenze | Nach Lock gelesene aktuelle DBzeit entscheidet; kein Freigeben mit alter Transaktionsstartzeit | | EUQ-52 | Resume nach bewiesenem failed_unsent/released_unsent gegenüber unknown | Explizite neue Admissionrevision derselben Call-/Reservation-ID nur im belegbar unversendeten Fall; keine Doppelholds/Replay | PostgreSQL-Parallelität, FKs, echte Commits/Rollbacks, Erstzeilenrennen, Perioden und Lockordnung werden gegen eine isolierte echte PostgreSQLinstanz mit Foundationtreiber getestet. SQLite oder ausschließlich Mocks reichen dafür nicht. Keine echten Providerkeys/-calls oder produktiven Datenbanken. Die Testauswahl muss die Fall-IDs tatsächlich sammeln; übersprungene Assertions oder bloße Dateiexistenz sind kein Nachweis einer Hardquota. Vorhandene Testquellen I: Shinkan [Entitlementsnapshot](C:/Dev/shinkan-jinkendo/backend/tests/test_entitlements.py:8), [Limit-/Resethelpers](C:/Dev/shinkan-jinkendo/backend/tests/test_club_features.py:7), [M5-Verbrauchsfassade](C:/Dev/shinkan-jinkendo/backend/tests/test_club_feature_m5.py:25), [Ausnahmen](C:/Dev/shinkan-jinkendo/backend/tests/test_club_feature_exemptions.py:38), [Planningmeter](C:/Dev/shinkan-jinkendo/backend/tests/test_planning_llm_usage.py:13); Mitai [Import-Enforcement](C:/Dev/mitai-jinkendo/backend/tests/test_activity_import_feature_enforcement.py:12), [Widgets](C:/Dev/mitai-jinkendo/backend/tests/test_dashboard_widget_entitlements.py:5), [mehrere Featureanforderungen](C:/Dev/mitai-jinkendo/backend/tests/test_widget_feature_requirements_db.py:4). Diese wurden hier nicht ausgeführt. Vor Übernahme Assertions prüfen: bestehende Tests für negative Limits oder deaktiviertes Enforcement bestätigen gerade nicht die neue Fail-Closed-Semantik. ## 16. Implementierungsanweisung für Cursor 1. **Einen Ziel-Fachfall benennen und vorhandene Adapter verwenden.** Kein Familienbilling auf Vorrat. Persönliche Quoten zuerst am eindeutigen Mitai-Account-/Profilbezug, Vereinsquoten am Shinkan-Clubvertrag ausrichten. Lokale produktbezogene Arbeitsregeln bei der tatsächlichen Umsetzung lesen. Keine Produktänderung durch diesen Dokumentauftrag. 2. **Messgröße und Zusage explizit registrieren.** Boolean, Ereignis oder Bestand trennen; lokale Meter-/Perioden-/Defaultpolicyversion festlegen. Bestehende `ai_calls`-Semantik prüfen, nicht umdeuten. Zunächst harte Callanzahl und beobachtende Token-/Kostendaten, sofern keine andere konkrete Zusage vorliegt. 3. **Foundation/Auth anschließen.** `EntitlementPolicy` bleibt zusätzlich zu aktueller AccessPolicy. Server bestimmt Subjekt und Scope. Strikte DTOs, sichere Fehler, no-store, vorhandenes MFA für privilegierte Verwaltung; kein allow-all/probe-Schalter als Hardquotaersatz. 4. **Registry und Policyauflösung adaptieren.** Mitai-/Shinkan-Feature-/Planmuster und Shinkans Capability-/Bypassgrenzen wiederverwenden. Defekte Limits, Überschneidungen und unbekannte Features schließen. Keine automatische Zahlungsintegration, globale Billingdatenbank oder Startup-DDL/Planmutation. 5. **Ledger und stabile Sperrzeile migrieren.** Nur benötigte Tabellen/FKs/Uniqueconstraints, gemeinsame Lockordnung, Zeitfenster, HMAC-/Keybindung, Idempotenz und Audit. Explizite isolierte SQLmigration gemäß Foundation; keine Anwendung gegen produktive Datenbanken. 6. **Zuerst echte Konkurrenz nachweisen.** Zwei DBconnections, letzter freier Platz, Erstzeilenrennen, gleiche/andere Callbindung, Mehrfachdimension, Rollback und Planwechsel. Ein Unit-Test von `remaining` genügt nicht. 7. **Gateway-T2/T3 verbinden.** Unveränderten `UsageBudgetPort` implementieren; Reservation und Dispatchintent zusammen; Ergebnis/Workflowcheckpoint/Usage/Callabschluss/Audit zusammen. Enger technischer Abschluss bei Widerruf oder fachlichem Fehler. Kein automatisch erzeugter Ersatzcall. 8. **Unknown, Perioden und lokale Fachwrites qualifizieren.** Keine TTLrefunds; Teilsettlement; Originalfenster; zeitlicher Grantablauf; Inventarwriter und Bulksemantik vollständig abdecken. Nicht belegte Token-/Kostenbounds halten eine geforderte Hardquota geschlossen. 9. **UI und Betrieb ergänzen.** Entitlementsnapshot mit klarer Einheit/Limitmodus/Sichtbarkeit, keine Tariflogik im UI; Scopeepochtests. Cleanup/Reconciliation/Restoreblockierung an bestehenden Recoveryvertrag anschließen, Writerdrain ergänzen. Kein Zählerreset durch Restore oder Imagewechsel. 10. **Nachweis abliefern und anhalten.** Ausgeführte EUQ-Fälle mit Code-/Buildstand, Umgebung, Ergebnis und verbleibenden K-Punkten dokumentieren. Pflicht-Gates und menschliche Produktionsfreigabe bleiben erhalten; R1 und R2 gemäß ADR-11 sind zulässig. Kein Live-Rollout, Zahlungsanbieter oder weiterer Blueprint ohne konkreten Auftrag. Abnahme eines implementierten ersten Fachfalls verlangt: **aktueller Principal/Scope + Objektzugriff → wirksame Featurepolicy → eindeutiges Kontingentsubjekt → atomare Zulassung → tatsächliche Wirkung → idempotente Buchung oder ausdrücklich unknown**, einschließlich Parallelität, Widerruf, Plan-/Periodenwechsel und Crash nach möglichem Versand. Ein Entitlementsnapshot oder ein nach Erfolg erhöhter Zähler allein erfüllt dies nicht. ## 17. Prüfstand dieser Lieferung Es wurden die vorhandenen Phase-3.1-Register und gezielt die in Abschnitt 2 benannten Mechanismen gelesen. Keine umfassende Repository-Neuanalyse, keine erneute Governance-/Produktreifebewertung und keine zusätzlichen ADRs. Bestehende Anwendungen und bisherige Ergebnisdokumente wurden nicht geändert. Keine Implementierung, Provideranfrage, produktive Datenbank, Zugangsdaten, Migration, Zahlungsintegration oder umfassender Bestands-Testlauf. **T – mechanischer Dokumentcheck am 16.10.2026:** 41 lokale Dateiverweise einschließlich angegebener Zeilen geprüft; drei Pythonbeispiele erfolgreich als AST geparst und ein JSONbeispiel erfolgreich gelesen; 52 eindeutige und lückenlos nummerierte Testspezifikationen erfasst; 25 Quellhashes gegen den lokalen Stand geprüft. Alle 49 zur Kontrolle erfassten Bestandsdateien sind gegenüber der Aufnahme vor Erstellung unverändert. Das Ergebnisverzeichnis enthält ausschließlich dieses Markdowndokument. Keines der Beispiele wurde als Anwendung ausgeführt; die 52 Testfälle sind nicht implementiert oder ausgeführt. Die Quellhashes unten sind kein Nachweis einer produktionsreifen Lösung. ### 17.1 Lokaler Quellstand SHA-256 der gezielt verwendeten vorhandenen Quellen; relative Pfade ab `C:/Dev`. Produktdokumente und Testdateien sind Referenzen I, keine bestätigten Laufresultate. | Quelle | SHA-256 | |---|---| | `mitai-jinkendo/backend/auth.py` | `25d666b3f69cac0d18fa7abc969f51b16b889d6b6ff41d6f054d0d39941e8c1b` | | `mitai-jinkendo/backend/routers/subscription.py` | `ffdd96e1184efc2f69974db6c6df552a13f76346f10bd86a93260725019e1b0d` | | `mitai-jinkendo/backend/routers/features.py` | `96db39825e27c54e1a649baefaf9e23f9f3d47504caa98d474a862074d383141` | | `mitai-jinkendo/backend/feature_logger.py` | `9d609d90fedc0febbbccc2eba947aec89b8365d0aa8166c25ab594965a18af37` | | `mitai-jinkendo/backend/dashboard_widget_entitlements.py` | `cadcfe5da58260f44d65c5dc47ec22a03f2bb2cdf9a68ec50071bebd6bc4f821` | | `mitai-jinkendo/backend/widget_feature_requirements_db.py` | `1b8f2b04046e1efc6bea46e4dc0fdb7bc810668f557bf40a03711400d4e1ea52` | | `mitai-jinkendo/.claude/docs/technical/FEATURE_ENFORCEMENT_MAPPING.md` | `71d24076a247b28e4950ac0eedb07ee20f0852bb7f6d956670bca2ce75a9dc0e` | | `mitai-jinkendo/backend/tests/test_activity_import_feature_enforcement.py` | `fca5134d3cbae3dc63fcc8b07054781806876fa1c73a57b91e00713921ae6f91` | | `mitai-jinkendo/backend/tests/test_dashboard_widget_entitlements.py` | `cd53efad484673fd320998a659f07c0c2e07c2436dcb3d4a3449ab956728d7bf` | | `mitai-jinkendo/backend/tests/test_widget_feature_requirements_db.py` | `51f0e2af1535989e2ef5e678f69c42a4a5d7a74e482b760e4197646fef1a1587` | | `shinkan-jinkendo/backend/entitlements.py` | `b92c71806ba8394fc8055e50893e1ea66c8f38163a120d90ac796768d1a963cc` | | `shinkan-jinkendo/backend/rights_registry.py` | `49992f1993b2e0d0e3bc7e50d44862d423bd68907b5a5d7f2f019edb99385555` | | `shinkan-jinkendo/backend/club_features.py` | `429c68551bd8b0515ce9a4e5a372927c5074cdeb41dabc968e8ab8a3152788c9` | | `shinkan-jinkendo/backend/club_quota_bypass.py` | `74e7eec110b28032cd0d93fb2451a19424c238fe4f33d33429254a3ebbf8a1e4` | | `shinkan-jinkendo/backend/planning_llm_usage.py` | `955f65799572b1fe9031d8df6cea1c16618a1b980735b0b4b43b1bbfd9cc73cd` | | `shinkan-jinkendo/backend/club_feature_logger.py` | `fa08d9527625f04016832b42ebf98e377dd2571e471331df36cc85ee121e94d4` | | `shinkan-jinkendo/backend/tests/test_entitlements.py` | `0cf0d986adf340c4191a6f8fd575cddb42884a48c89e4c91819f72af77cb2eed` | | `shinkan-jinkendo/backend/tests/test_club_features.py` | `cf0db96c17b14efa9ebd01fd704f2734e6d7e9c2f6adc8b09f44e5ec2243c512` | | `shinkan-jinkendo/backend/tests/test_club_feature_m5.py` | `f9c9a8608c7902391537ed06ca27ea226ed8b0a435176f55f565eb78cad9fda8` | | `shinkan-jinkendo/backend/tests/test_club_feature_exemptions.py` | `25115cdee347bde330772f78d5e783bd6ab748ec55507e149558312f09cb5623` | | `shinkan-jinkendo/backend/tests/test_planning_llm_usage.py` | `3f7da3a5d6eb5824d48e5e034c0f75fc2fd4e2592ff37e819911f70d8c67b1bb` | | `shinkan-jinkendo/docs/jinkendo-family/FAMILY_ENTITLEMENT_MODEL.md` | `ca43f58181b971ab6f5d508d38a0c78980037f6f75ab61d7df8fa8a95b42d1bf` | | `shinkan-jinkendo/docs/product-readiness/03-abo-entitlements-abrechnung.md` | `43142140594d2f53c49c750dbc784658124eb5f78b8ca41443fc1da38d37a44a` | | `kairo-jinkendo/backend/feature_registry.py` | `9e37bc6bda763ea99c960aa183b9165a9b11a8be1f20f73095b408b1b7a99c47` | | `kairo-jinkendo/backend/entitlements.py` | `76a5b3a972c752619579042a932d3d0c1b413ce6a18606d0bde2343b174846a1` |