fix(customization): enforce approved content type quota

Serialize tenant-wide count and registration before the existing concept
lock. Apply the approved distinct-key accounting without changing default
unlimited entitlements or lifecycle authority. Keep hard-limit refusals
consistent across HTTP, audit and job classification.

Register both CI Python tools in the exact source inventory; unknown
formats still fail closed. Retain the failed CI and planted-lock evidence.

ADR: 0021, 0040, 0045
Module: Customization
I18n: lockey_limit_exceeded

Author: cemililik

backend/src/LearnStack.Api/Common/HttpStatusMap.cs

@@ -27,6 +27,7 @@ public static int For(Error error)
         "forbidden" => (int)HttpStatusCode.Forbidden,
         "resource_scope_violation" => (int)HttpStatusCode.Forbidden,
         "feature_disabled" => (int)HttpStatusCode.Forbidden,
+        "limit_exceeded" => (int)HttpStatusCode.Forbidden,
         "not_found" => (int)HttpStatusCode.NotFound,
         "method_not_allowed" => (int)HttpStatusCode.MethodNotAllowed,
         "payload_too_large" => (int)HttpStatusCode.RequestEntityTooLarge,

backend/src/LearnStack.Application/Audit/AuditExecutionCoordinator.cs

@@ -381,7 +381,7 @@ private async Task DeclareAsync(
     /// </remarks>
     private static AuditOutcome OutcomeOf(Error error) => error.Code switch
     {
-        "forbidden" or "resource_scope_violation" or "feature_disabled" => AuditOutcome.Denied,
+        "forbidden" or "resource_scope_violation" or "feature_disabled" or "limit_exceeded" => AuditOutcome.Denied,
         _ => AuditOutcome.Failed,
     };
 

backend/src/LearnStack.Infrastructure/Jobs/BackgroundJobFailurePolicy.cs

@@ -73,7 +73,7 @@ internal static TimeSpan GetRetryDelay(int committedNormalAttempts) => committed
     {
         "concurrency_conflict" or "rate_limited" or "dependency_unavailable" or "audit_unavailable" => Retry(code),
         "validation_failed" or "unauthorized" or "forbidden" or "tenant_mismatch" or "resource_scope_violation"
-            or "not_found" or "business_rule_violation" or "feature_disabled" or "unsupported_locale"
+            or "not_found" or "business_rule_violation" or "feature_disabled" or "limit_exceeded" or "unsupported_locale"
             or "audit_unclassified_operation" => Permanent(),
         _ => Retry("unexpected_fault"),
     };

backend/src/Modules/Customization/LearnStack.Modules.Customization.Application/Abstractions/CustomizationStores.cs

@@ -4,8 +4,8 @@
 
 namespace LearnStack.Modules.Customization.Application.Abstractions;
 
-/// <summary>The <c>TenantContentType</c> aggregate's writes, and the two reads a
-/// publish needs.</summary>
+/// <summary>The <c>TenantContentType</c> aggregate's writes, coordination and reads
+/// for registration and publication.</summary>
 /// <remarks>
 /// <para>
 /// Declared here and implemented across the boundary, for the reason
@@ -34,6 +34,12 @@ namespace LearnStack.Modules.Customization.Application.Abstractions;
 public interface ITenantContentTypeStore
     : IAggregateWriteStore<TenantContentType, TenantContentTypeId>
 {
+    /// <summary>Serializes custom-key registrations for the tenant until transaction end, before taking a concept lock.</summary>
+    Task LockRegistrationsAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>Distinct nondeleted custom keys and whether this key already has a nondeleted revision; excludes the built-in card.</summary>
+    Task<ContentTypeQuotaUsage> ReadQuotaUsageAsync(string key, CancellationToken cancellationToken = default);
+
     /// <summary>Serializes registration and initialization for this tenant's concept until transaction end.</summary>
     Task LockConceptAsync(string key, CancellationToken cancellationToken = default);
 
@@ -56,6 +62,9 @@ public interface ITenantContentTypeStore
         string key, CancellationToken cancellationToken = default);
 }
 
+/// <summary>The tenant's authoring usage; revisions share one custom-key slot.</summary>
+public sealed record ContentTypeQuotaUsage(long CustomKeyCount, bool HasNondeletedRevision);
+
 /// <summary>The <c>TenantLevelTaxonomy</c> aggregate's writes, and the two reads a
 /// publish needs.</summary>
 /// <remarks>

backend/src/Modules/Customization/LearnStack.Modules.Customization.Application/Customization/CustomizationFailures.cs

@@ -1,4 +1,5 @@
 using LearnStack.SharedKernel.Localization;
+using LearnStack.SharedKernel.Entitlements;
 using LearnStack.SharedKernel.Results;
 using LearnStack.SharedKernel.Validation;
 
@@ -9,8 +10,8 @@ namespace LearnStack.Modules.Customization.Application.Customization;
 /// </summary>
 /// <remarks>
 /// The top-level code stays a cross-cutting one — <c>validation_failed</c>,
-/// <c>not_found</c>, <c>business_rule_violation</c>, <c>concurrency_conflict</c>
-/// and <c>tenant_mismatch</c> are the five this module emits — because
+/// <c>not_found</c>, <c>business_rule_violation</c>, <c>concurrency_conflict</c>,
+/// <c>limit_exceeded</c> and <c>tenant_mismatch</c> are the six this module emits — because
 /// <c>HttpStatusMap</c> is a closed table and a module-specific key there falls
 /// through to <c>500</c>: the one answer a refusal must never give. What is
 /// module-specific goes in the field entry, where a client reads it.
@@ -118,6 +119,21 @@ internal static Result<T> Stale<T>() =>
     internal static Result<T> BusinessRule<T>(string field, string reason) =>
         Field<T>(BusinessRuleViolation, field, reason);
 
+    internal static Result<T> ContentTypeLimit<T>(long limit)
+    {
+        var message = new LocalizedMessage("lockey_limit_exceeded", new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["limitKey"] = LimitKeys.MaxCustomContentTypes.Value,
+            ["limit"] = limit.ToString(System.Globalization.CultureInfo.InvariantCulture),
+        });
+        return Result<T>.Fail(new Error(message, new Dictionary<string, IReadOnlyList<LocalizedMessage>>(StringComparer.Ordinal)
+        {
+            // Problem Details projects parameters from field messages, so the
+            // refusal names the ceiling on the actual wire as well as the Result.
+            ["Key"] = [message],
+        }));
+    }
+
     internal static Result<T> Field<T>(string code, string field, string reason) =>
         Result.FailFor<Result<T>>(new Error(
             new LocalizedMessage(code),

backend/src/Modules/Customization/LearnStack.Modules.Customization.Application/Customization/RegisterTenantContentTypeCommandHandler.cs

@@ -1,6 +1,7 @@
 using LearnStack.Modules.Customization.Application.Abstractions;
 using LearnStack.Modules.Customization.Application.Contracts.Customization;
 using LearnStack.Modules.Customization.Domain;
+using LearnStack.SharedKernel.Entitlements;
 using LearnStack.SharedKernel.Identifiers;
 using LearnStack.SharedKernel.Localization;
 using LearnStack.SharedKernel.Persistence;
@@ -37,6 +38,7 @@ internal sealed class RegisterTenantContentTypeCommandHandler(
     ICustomizationGenerationStore generations,
     ITenantLevelTaxonomyCatalog taxonomies,
     IJsonSchemaValidator schemas,
+    IFeatureFlags features,
     ITenantContext tenantContext,
     IClock clock)
     : IRequestHandler<RegisterTenantContentTypeCommand, Result<TenantContentTypeDto>>
@@ -96,7 +98,22 @@ public async Task<Result<TenantContentTypeDto>> Handle(
 
         try
         {
+            // All custom-key registrars take the tenant lock before the concept
+            // lock. Different keys otherwise race the same tenant-wide ceiling.
+            // Card does not consume a slot; initialization keeps its history lock.
+            var custom = request.Key != BuiltInCustomizations.Card.Key;
+            if (custom) await contentTypes.LockRegistrationsAsync(cancellationToken);
             await contentTypes.LockConceptAsync(request.Key, cancellationToken);
+            if (custom && !await features.IsEnabledAsync(FeatureKeys.UnlimitedContentTypes, cancellationToken))
+            {
+                var limit = await features.GetLimitAsync(LimitKeys.MaxCustomContentTypes, cancellationToken);
+                if (limit != LimitKeys.Unlimited)
+                {
+                    var usage = await contentTypes.ReadQuotaUsageAsync(request.Key, cancellationToken);
+                    if (!usage.HasNondeletedRevision && usage.CustomKeyCount >= limit)
+                        return CustomizationFailures.ContentTypeLimit<TenantContentTypeDto>(limit);
+                }
+            }
             await contentTypes.AddAsync(contentType, cancellationToken);
         }
         catch (AggregateConflictException conflict)

backend/src/Modules/Customization/LearnStack.Modules.Customization.Infrastructure/Persistence/CustomizationConceptHistory.cs

@@ -2,6 +2,7 @@
 using System.Security.Cryptography;
 using System.Text;
 using LearnStack.Modules.Customization.Domain;
+using LearnStack.Modules.Customization.Application.Contracts.Customization;
 using LearnStack.SharedKernel.Identifiers;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Storage;
@@ -19,6 +20,18 @@ internal static async Task LockAsync(
         // A stable namespace includes tenant and kind, but deliberately no revision.
         // A hash collision only serializes unrelated writers; it cannot grant access.
         var identity = $"customization:{tenant.Value:D}:{(taxonomy ? "taxonomy" : "content-type")}:{key}";
+        await LockIdentityAsync(identity, connection, transaction, cancellationToken);
+    }
+
+    internal static async Task LockRegistrationsAsync(CustomizationDbContext db, CancellationToken cancellationToken)
+    {
+        var (tenant, connection, transaction) = RequireContext(db, BuiltInCustomizations.Card.Key);
+        await LockIdentityAsync($"customization:{tenant.Value:D}:content-type-quota", connection, transaction, cancellationToken);
+    }
+
+    private static async Task LockIdentityAsync(string identity, NpgsqlConnection connection,
+        NpgsqlTransaction transaction, CancellationToken cancellationToken)
+    {
         var digest = SHA256.HashData(Encoding.UTF8.GetBytes(identity));
         var lockKey = BinaryPrimitives.ReadInt64BigEndian(digest);
         await using var command = new NpgsqlCommand(

backend/src/Modules/Customization/LearnStack.Modules.Customization.Infrastructure/Persistence/CustomizationWriteStores.cs

@@ -1,5 +1,6 @@
 using LearnStack.Infrastructure.Persistence;
 using LearnStack.Modules.Customization.Application.Abstractions;
+using LearnStack.Modules.Customization.Application.Contracts.Customization;
 using LearnStack.Modules.Customization.Domain;
 using LearnStack.Modules.Customization.Infrastructure.Projections;
 using Microsoft.EntityFrameworkCore;
@@ -41,6 +42,19 @@ namespace LearnStack.Modules.Customization.Infrastructure.Persistence;
 /// </remarks>
 public sealed class TenantContentTypeStore(CustomizationDbContext db, CustomizationReadState reads) : ITenantContentTypeStore
 {
+    public Task LockRegistrationsAsync(CancellationToken cancellationToken = default) =>
+        CustomizationConceptHistory.LockRegistrationsAsync(db, cancellationToken);
+
+    public async Task<ContentTypeQuotaUsage> ReadQuotaUsageAsync(string key, CancellationToken cancellationToken = default)
+    {
+        CustomizationKey.EnsureValid(key, nameof(key));
+        var customKeys = db.TenantContentTypes
+            .Where(row => row.DeletedAt == null && row.Key != BuiltInCustomizations.Card.Key)
+            .Select(row => row.Key).Distinct();
+        return new(await customKeys.LongCountAsync(cancellationToken),
+            await customKeys.AnyAsync(existing => existing == key, cancellationToken));
+    }
+
     public Task LockConceptAsync(string key, CancellationToken cancellationToken = default) =>
         CustomizationConceptHistory.LockAsync(db, taxonomy: false, key, cancellationToken);