Roll to gts-spec v0.14.4 and decompose the store/validation layer

.gts-spec-version

@@ -1 +1 @@
-v0.14.2
+v0.14.4

Directory.Build.props

@@ -0,0 +1,12 @@
+<Project>
+
+  <!-- Settings shared by every project in the solution. Project files override
+       or extend these as needed (e.g. OutputType, RootNamespace, RollForward). -->
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Version>0.1.0</Version>
+  </PropertyGroup>
+
+</Project>

Gts.Application/Gts.Application.csproj

@@ -1,9 +1,6 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net8.0</TargetFramework>
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
     <RootNamespace>Gts.Application</RootNamespace>
   </PropertyGroup>
 

Gts.Application/GtsEntityOperations.cs

@@ -7,13 +7,14 @@ namespace Gts.Application;
 /// <summary>Adds entities to a registry with the same rules as the GTS HTTP API.</summary>
 public static class GtsEntityOperations
 {
-    public sealed record AddResult(bool Ok, string Id, string? SchemaId, bool IsSchema, string? Error);
+    public sealed record AddResult(bool Ok, string Id, string? SchemaId, bool IsSchema, string? Error, bool Conflict = false);
 
     public static async Task<AddResult> TryAddAsync(
         GtsRegistry registry,
         JsonObject body,
         bool validate,
         GtsExtractOptions? extractOptions = null,
+        GtsRefValidationMode refValidationMode = GtsRefValidationModes.Default,
         CancellationToken cancellationToken = default)
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -24,7 +25,7 @@ public static async Task<AddResult> TryAddAsync(
         if (!entity.IsSchema)
         {
             if (string.IsNullOrEmpty(entity.SelectedEntityField))
-                return new AddResult(false, "", null, false, "Instance must have an id field");
+                return new AddResult(false, "", null, false, "Unable to detect GTS ID in instance entity");
             if (entity.GtsId is { IsInstance: true } instanceId && instanceId.Segments.Count == 1)
                 return new AddResult(false, instanceId.Id, null, false, "Single-segment instance IDs are not allowed");
         }
@@ -39,11 +40,17 @@ public static async Task<AddResult> TryAddAsync(
             var rawId = body.TryGetPropertyValue("$id", out var idn) && idn is JsonValue idValue && idValue.TryGetValue<string>(out var id)
                 ? id
                 : null;
-            if (validate && !string.IsNullOrEmpty(rawId) && rawId.StartsWith("gts.", StringComparison.Ordinal) &&
-                !rawId.StartsWith("gts://", StringComparison.Ordinal))
+            if (validate && !string.IsNullOrEmpty(rawId) && rawId.StartsWith(GtsConstants.IdPrefix, StringComparison.Ordinal) &&
+                !rawId.StartsWith(GtsConstants.UriPrefix, StringComparison.Ordinal))
                 return new AddResult(false, "", null, true, "Schema $id must use gts:// URI format, not plain gts. prefix");
-            if (!TryGetSupportedDialect(body, out var dialectError))
+            if (!GtsTypeSchema.TryGetSupportedDialect(body, out _, out var dialectError))
                 return new AddResult(false, entity.GtsId?.Id ?? "", null, true, dialectError);
+            var keywordErrors = GtsSchemaKeywordValidator.Validate(body);
+            if (keywordErrors.Count > 0)
+                return new AddResult(false, entity.GtsId?.Id ?? "", null, true, string.Join("; ", keywordErrors));
+            var refErrors = GtsRefValidator.ValidatePatterns(body, entity.GtsId?.Id ?? "");
+            if (refErrors.Count > 0)
+                return new AddResult(false, entity.GtsId?.Id ?? "", null, true, "x-gts-ref validation failed: " + string.Join("; ", refErrors));
         }
 
         try
@@ -55,59 +62,129 @@ public static async Task<AddResult> TryAddAsync(
             return new AddResult(false, "", null, entity.IsSchema, ex.Message);
         }
 
+        GtsJsonEntity? existing = entity.GtsId is not null
+            ? await registry.GetAsync(entity.GtsId).ConfigureAwait(false)
+            : !string.IsNullOrEmpty(extract.Id)
+                ? await registry.GetByInstanceIdAsync(extract.Id).ConfigureAwait(false)
+                : null;
+        if (existing is not null)
+        {
+            if (JsonNode.DeepEquals(existing.Content, entity.Content) && !validate)
+                return new AddResult(true, extract.Id ?? entity.GtsId?.Id ?? "", entity.SchemaId, entity.IsSchema, null);
+            if (!JsonNode.DeepEquals(existing.Content, entity.Content))
+                return new AddResult(false, extract.Id ?? entity.GtsId?.Id ?? "", entity.SchemaId, entity.IsSchema,
+                    "Entity already exists with different content", true);
+        }
+
         if (entity.IsSchema && entity.GtsId is not null)
         {
             if (validate)
             {
-                var schemaVr = await registry.ValidateSchemaAsync(entity.GtsId, entity.Content, cancellationToken)
+                var registered = await registry.SnapshotForReadAsync().ConfigureAwait(false);
+                var constraintErrors = GtsRefValidator.ValidateConstraints(entity.Content, entity.GtsId.Id, registered, refValidationMode);
+                if (constraintErrors.Count > 0)
+                    return new AddResult(false, entity.GtsId.Id, entity.SchemaId, true, "x-gts-ref validation failed: " + string.Join("; ", constraintErrors));
+                var schemaVr = await registry.ValidateSchemaAsync(entity.GtsId, entity.Content, cancellationToken, refValidationMode)
                     .ConfigureAwait(false);
                 if (!schemaVr.Ok)
                 {
                     var msg = schemaVr.Errors is { Count: > 0 }
                         ? string.Join("; ", schemaVr.Errors)
-                        : (schemaVr.FailureReason ?? "Schema validation failed");
+                        : (schemaVr.FailureReason?.ToWire() ?? "Schema validation failed");
                     return new AddResult(false, entity.GtsId.Id, entity.SchemaId, true, msg);
                 }
             }
 
-            await registry.SaveAsync(entity).ConfigureAwait(false);
+            if (await registry.TrySaveAsync(entity).ConfigureAwait(false) == GtsSaveOutcome.Conflict)
+                return new AddResult(false, entity.GtsId.Id, entity.SchemaId, true, "Entity already exists with different content", true);
 
             var schemaIdOut = entity.GtsId.Id;
             return new AddResult(true, schemaIdOut, string.IsNullOrEmpty(entity.SchemaId) ? null : entity.SchemaId, true, null);
         }
 
-        await registry.SaveAsync(entity).ConfigureAwait(false);
-
-        if (validate && !entity.IsSchema && entity.GtsId is not null)
+        if (validate && !entity.IsSchema)
         {
-            var vr = await registry.ValidateInstanceAsync(entity.GtsId.Id, cancellationToken).ConfigureAwait(false);
-            if (!vr.Ok)
-                return new AddResult(false, entity.GtsId.Id, entity.SchemaId, false, vr.FailureReason ?? "Validation failed");
+            if (string.IsNullOrEmpty(entity.SchemaId) || !GtsId.TryParse(entity.SchemaId, out var schemaId) || schemaId is null || !schemaId.IsType)
+                return new AddResult(false, entity.GtsId?.Id ?? extract.Id ?? "", entity.SchemaId, false, "Unable to determine instance type");
+            var validation = await registry.ValidateJsonAsync(entity.Content, schemaId, entity.GtsId?.Id ?? extract.Id, cancellationToken, refValidationMode)
+                .ConfigureAwait(false);
+            if (!validation.Ok)
+            {
+                var error = validation.SchemaErrors is { Count: > 0 }
+                    ? string.Join("; ", validation.SchemaErrors)
+                    : validation.FailureReason?.ToWire() ?? "Validation failed";
+                return new AddResult(false, entity.GtsId?.Id ?? extract.Id ?? "", entity.SchemaId, false, error);
+            }
         }
 
         var idOut = entity.GtsId?.Id ?? extract.Id ?? "";
+        if (await registry.TrySaveAsync(entity).ConfigureAwait(false) == GtsSaveOutcome.Conflict)
+            return new AddResult(false, idOut, entity.SchemaId, entity.IsSchema, "Entity already exists with different content", true);
         return new AddResult(true, idOut, string.IsNullOrEmpty(entity.SchemaId) ? null : entity.SchemaId, entity.IsSchema, null);
     }
 
-    private static bool TryGetSupportedDialect(JsonObject body, out string? error)
+    /// <summary>
+    /// Runs the structural checks for a batch Type Schema entry (canonical $schema/$id, dialect, GTS
+    /// keyword placement, $ref format and x-gts-ref patterns) and builds the entity WITHOUT touching the
+    /// store. Returns the entity on success or an error message. Mirrors the schema branch of
+    /// <see cref="TryAddAsync"/> so a batch entry is checked exactly like a single POST /entities schema.
+    /// </summary>
+    public static (GtsJsonEntity? Entity, string? Error) PrepareSchema(JsonObject body, GtsExtractOptions? extractOptions = null)
     {
-        error = null;
-        if (!body.TryGetPropertyValue("$schema", out var node) || node is not JsonValue value ||
-            !value.TryGetValue<string>(out var dialect) || string.IsNullOrEmpty(dialect))
+        var opt = extractOptions ?? GtsExtractOptions.Default;
+        var entity = GtsJsonEntity.ExtractEntity(body, opt);
+        if (!entity.IsSchema || entity.GtsId is null)
+            return (null, "Unable to detect GTS ID in schema");
+
+        var rawId = body.TryGetPropertyValue("$id", out var idn) && idn is JsonValue idValue && idValue.TryGetValue<string>(out var id)
+            ? id
+            : null;
+        if (!string.IsNullOrEmpty(rawId) && rawId.StartsWith(GtsConstants.IdPrefix, StringComparison.Ordinal) &&
+            !rawId.StartsWith(GtsConstants.UriPrefix, StringComparison.Ordinal))
+            return (null, "Schema $id must use gts:// URI format, not plain gts. prefix");
+        if (!GtsTypeSchema.TryGetSupportedDialect(body, out _, out var dialectError))
+            return (null, dialectError);
+        var keywordErrors = GtsSchemaKeywordValidator.Validate(body);
+        if (keywordErrors.Count > 0)
+            return (null, string.Join("; ", keywordErrors));
+        var refErrors = GtsRefValidator.ValidatePatterns(body, entity.GtsId.Id);
+        if (refErrors.Count > 0)
+            return (null, "x-gts-ref validation failed: " + string.Join("; ", refErrors));
+        try
         {
-            error = "Schema must contain a supported $schema dialect";
-            return false;
+            GtsSchemaRefFormatValidator.ValidateRefs(body);
         }
+        catch (Exception ex)
+        {
+            return (null, ex.Message);
+        }
+        return (entity, null);
+    }
 
-        if (dialect is "http://json-schema.org/draft-07/schema#" or
-            "https://json-schema.org/draft-07/schema#" or
-            "https://json-schema.org/draft/2019-09/schema" or
-            "https://json-schema.org/draft/2019-09/schema#" or
-            "https://json-schema.org/draft/2020-12/schema" or
-            "https://json-schema.org/draft/2020-12/schema#")
-            return true;
-
-        error = $"Unsupported JSON Schema dialect: {dialect}";
-        return false;
+    /// <summary>
+    /// Runs the semantic validation of a staged schema (x-gts-ref existence, derivation/traits) against the
+    /// current staged+committed set, returning an error message on failure or null on success. Does not
+    /// mutate the store: the caller commits the staged entry on success or discards it on failure.
+    /// </summary>
+    public static async Task<string?> ValidateStagedSchemaAsync(
+        GtsRegistry registry,
+        GtsJsonEntity entity,
+        GtsRefValidationMode refValidationMode,
+        CancellationToken cancellationToken = default,
+        string? stagingSessionId = null)
+    {
+        if (entity.GtsId is null)
+            return "Unable to detect GTS ID in schema";
+        var registered = await registry.SnapshotForReadAsync(stagingSessionId).ConfigureAwait(false);
+        var constraintErrors = GtsRefValidator.ValidateConstraints(entity.Content, entity.GtsId.Id, registered, refValidationMode);
+        if (constraintErrors.Count > 0)
+            return "x-gts-ref validation failed: " + string.Join("; ", constraintErrors);
+        var schemaVr = await registry.ValidateSchemaAsync(entity.GtsId, entity.Content, cancellationToken, refValidationMode, stagingSessionId)
+            .ConfigureAwait(false);
+        if (!schemaVr.Ok)
+            return schemaVr.Errors is { Count: > 0 }
+                ? string.Join("; ", schemaVr.Errors)
+                : (schemaVr.FailureReason?.ToWire() ?? "Schema validation failed");
+        return null;
     }
 }