Files
tsumugu/docs/reference/Jinkendo_Entitlements_Usage_Quotas_Blueprint.md
T
LarsandCursor d6b70d8f92
Deploy Development / deploy (push) Successful in 28s
Test Suite / pytest-backend (push) Failing after 2m18s
Test Suite / smoke-dev (push) Successful in 0s
Test Suite / frontend-build (push) Successful in 10s
Schließe die Connector-Kapselung ab, damit Paperless, IMAP und weitere Quellen über dieselbe Anbindung laufen.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-19 15:00:50 +02:00

77 KiB
Raw Blame History

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:

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, Tarifauflösung, 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, Subscriptionansicht, Featuremapping 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, mehrere Anforderungen 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, Registry, 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, Bestandszählung 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, Planningmeter 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 Benannte Capability statt pauschaler Adminsonderfall Aufnahmeausnahme befristen/binden/auditieren; Verbrauch weiterhin erfassen. Keine Ausnahme von Privacy-/Objekt-/technischen Kostenlimits.
Familienmodell, offene Atomarität 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 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, Entitlementsnapshot, 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 und Shinkan-Featurelogs 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.

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:

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:

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:

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:

{
  "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, Limit-/Resethelpers, M5-Verbrauchsfassade, Ausnahmen, Planningmeter; Mitai Import-Enforcement, Widgets, mehrere Featureanforderungen. 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