77 KiB
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, Application Foundation B v0.3, Entscheidungen C v0.3.
- Auth, Session & Scope, Release, Betrieb & Recovery, KI-Gateway und Prompt-/Platzhalter-/Workflow-Laufzeit.
- Beschlossene ADR-01 bis ADR-14 aus dem Entscheidungsregister, 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: KI-MIT-05, KI-SHK-03 und ergänzend KI-KAI-05; Quellenregister, Testregister, Guardrailregister.
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_idaus einem Request akzeptieren. - Fehlender Featureeintrag, kaputter Integer, SQLfehler oder nicht konfigurierter Adapter ergibt
unlimited; probe/off als zugesicherte harte Grenze ausgeben. check → externer Call → incrementohne 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
- 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.
- 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. - Foundation/Auth anschließen.
EntitlementPolicybleibt 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. - 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.
- 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.
- Zuerst echte Konkurrenz nachweisen. Zwei DBconnections, letzter freier Platz, Erstzeilenrennen, gleiche/andere Callbindung, Mehrfachdimension, Rollback und Planwechsel. Ein Unit-Test von
remaininggenügt nicht. - Gateway-T2/T3 verbinden. Unveränderten
UsageBudgetPortimplementieren; Reservation und Dispatchintent zusammen; Ergebnis/Workflowcheckpoint/Usage/Callabschluss/Audit zusammen. Enger technischer Abschluss bei Widerruf oder fachlichem Fehler. Kein automatisch erzeugter Ersatzcall. - 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.
- 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.
- 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 |