@reventlessdev/reventless-spec 3.0.0-alpha.116 → 3.0.0-alpha.118

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.118 (2026-08-18)
+
+### Bug Fixes
+
+* **core:** report the real reason a decode failed ([233c835](https://github.com/ReventlessDev/reventless-core/commit/233c835be47cb83fbd247ab0d8a7073cad622fee)), closes [DZakh/sury#392](https://github.com/DZakh/sury/issues/392)
+* feat(sury)!: migrate to sury 11.0.0-rc.1 ([2cf8969](https://github.com/ReventlessDev/reventless-core/commit/2cf8969a222ce1b775563668a4126cb20611966c))
+### Features
+
+* **spec,ppx:** uploadable types that derive their store from the field name ([722b404](https://github.com/ReventlessDev/reventless-core/commit/722b4044a2e8dfb6a34231d6bfb529526de38b20))
+* **spec:** ImageRef and FileRef, for media the platform does not own ([a63425c](https://github.com/ReventlessDev/reventless-core/commit/a63425cba5fd381da6deaabccc94501739e3ad59))
+
+### BREAKING CHANGES
+
+* sury is a direct dependency of the published packages and
+its schema and serialization surface changed; consumers must migrate to
+sury 11.
+
+
+
+# 3.0.0-alpha.117 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** declare the reference door in the SDL every backend is built from ([5c1857e](https://github.com/ReventlessDev/reventless-core/commit/5c1857ea90ff40305a1c44a9e57043528e6a93aa))
+### Features
+
+* **core:** let a reference name a retired row, and let an elevated caller open one ([9e2623a](https://github.com/ReventlessDev/reventless-core/commit/9e2623a4b22487561607fcc0ca19d51726069ee4))
+
+
 # 3.0.0-alpha.116 (2026-08-16)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.116",
+  "version": "3.0.0-alpha.118",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -18,10 +18,10 @@
   },
   "dependencies": {
     "jsonschema2graphql": "1.1.1",
-    "sury": "11.0.0-alpha.4",
-    "sury-ppx": "11.0.0-alpha.2",
+    "sury": "11.0.0-rc.1",
+    "sury-ppx": "11.0.0-rc.1",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.8"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/schema/platform-api.graphql

@@ -178,6 +178,13 @@ enum Platform_PluginKind {
   PlatformInfrastructure
 }
 
+type Platform_PluginRef {
+  id: ID!
+  label: String!
+  retired: Boolean!
+  retiredState: String
+}
+
 enum Platform_PluginStatus {
   Connected
   Disconnected
@@ -215,6 +222,7 @@ type Platform_ReadSideDef {
   lifecycleField: String
   linkedWriteSide: [String!]!
   name: String!
+  namedWhenRetired: Boolean!
   ownerField: String
   queryField: String!
   requiredAccess: [String!]
@@ -290,10 +298,11 @@ type PluginStatusChangeEvent {
 
 type Query {
   Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!
-  Platform_Plugin(id: ID!): Platform_Plugin
+  Platform_Plugin(id: ID!, includeRetired: Boolean): Platform_Plugin
   Platform_PluginStructures: [Platform_PluginStructureEntry!]!
   Platform_Plugins(after: String, before: String, filter: Platform_PluginFilter, first: Int, includeRetired: Boolean, last: Int): Platform_PluginConnection!
-  Platform_PluginsByIds(ids: [String!]!): [Platform_Plugin!]!
+  Platform_PluginsByIds(ids: [String!]!, includeRetired: Boolean): [Platform_Plugin!]!
+  Platform_PluginsRefs(ids: [ID!]!): [Platform_PluginRef!]!
   Platform_UIFragments: [Platform_UIFragmentEntry!]!
 }
 

package/src/components/CapabilityManifest.res

@@ -67,7 +67,7 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
     no source change must produce a byte-identical file, so the committed
     manifest never churns. */
 let render = (manifest: t): string =>
-  JSON.stringify(manifest->S.reverseConvertToJsonOrThrow(schema), ~space=2) ++ "\n"
+  JSON.stringify(manifest->Util_Sury.toJson(schema), ~space=2) ++ "\n"
 
 /** One call for the emit CLI: structure in, `capabilities.json` content out. */
 let renderForStructure = (structure: Plugin.pluginStructure): string =>

package/src/components/CapabilityManifest.res.mjs

@@ -1,25 +1,26 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
-let kindSchema = S.literal("ObjectStore");
+let kindSchema = Sury.literal("ObjectStore");
 
-let provenanceSchema = S.schema(s => ({
-  component: s.m(S.string),
-  field: s.m(S.string),
-  annotation: s.m(S.option(S.string))
+let provenanceSchema = Sury.$schema(s => ({
+  component: s.m(Sury.string),
+  field: s.m(Sury.string),
+  annotation: s.m(Sury.$option(Sury.string))
 }));
 
-let entrySchema = S.schema(s => ({
+let entrySchema = Sury.$schema(s => ({
   kind: s.m(kindSchema),
-  key: s.m(S.string),
-  declaredBy: s.m(S.array(provenanceSchema))
+  key: s.m(Sury.string),
+  declaredBy: s.m(Sury.array(provenanceSchema))
 }));
 
-let schema = S.schema(s => ({
-  capabilities: s.m(S.array(entrySchema))
+let schema = Sury.$schema(s => ({
+  capabilities: s.m(Sury.array(entrySchema))
 }));
 
 function fromStructure(structure) {
@@ -42,7 +43,7 @@ function fromStructure(structure) {
 }
 
 function render(manifest) {
-  return JSON.stringify(S.reverseConvertToJsonOrThrow(manifest, schema), undefined, 2) + "\n";
+  return JSON.stringify(Util_Sury$Reventless.toJson(manifest, schema), undefined, 2) + "\n";
 }
 
 function renderForStructure(structure) {

package/src/components/DcbDecode.res

@@ -14,11 +14,11 @@ type variantKind =
 let buildVariantLookup = (schema: S.t<unknown>): dict<variantKind> => {
   let lookup = Dict.make()
   switch schema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.forEach(variantSchema =>
       switch variantSchema {
-      | Object({items, properties}) =>
-        switch DcbTag.variantTagName(items) {
+      | Object({properties}) =>
+        switch DcbTag.variantTagName(properties) {
         | Some(name) =>
           let kind = if properties->Dict.keysToArray->Array.length == 0 {
             PayloadLess
@@ -34,9 +34,9 @@ let buildVariantLookup = (schema: S.t<unknown>): dict<variantKind> => {
       | _ => ()
       }
     )
-  | Object({items}) =>
+  | Object({properties}) =>
     // Single-variant schema with fields
-    switch DcbTag.variantTagName(items) {
+    switch DcbTag.variantTagName(properties) {
     | Some(name) => lookup->Dict.set(name, WithFields)
     | None => ()
     }
@@ -64,12 +64,12 @@ let buildPayloadLessConstructors = (schema: S.t<'event>, lookup: dict<variantKin
   // For payload-less variants, we need to figure out what ReScript value
   // corresponds to each TAG name. sury's schema for a union with payload-less
   // variants encodes them as bare strings. So `| ItemCreated` serializes to
-  // JSON string "ItemCreated". We can use S.parseJsonOrThrow with the string.
+  // JSON string "ItemCreated". We can use Util_Sury.fromJson with the string.
   lookup->Dict.toArray->Array.forEach(((tagName, kind)) =>
     switch kind {
     | PayloadLess =>
       try {
-        let value = JSON.String(tagName)->S.parseJsonOrThrow(schema)
+        let value = JSON.String(tagName)->Util_Sury.fromJson(schema)
         constructors->Dict.set(tagName, value)
       } catch {
       | _ => ()
@@ -100,7 +100,7 @@ let makeDecoder = (schema: S.t<'event>): makeDecoderResult<'event> => {
       let jsonDict = data->Dict.copy
       jsonDict->Dict.set("TAG", JSON.String(eventType))
       try {
-        Some(JSON.Object(jsonDict)->S.parseJsonOrThrow(schema))
+        Some(JSON.Object(jsonDict)->Util_Sury.fromJson(schema))
       } catch {
       | _ =>
         // A parse failure here means a stored event no longer matches the

package/src/components/DcbDecode.res.mjs

@@ -1,8 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
+import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
 function buildVariantLookup(schema) {
   let lookup = {};
@@ -14,12 +14,12 @@ function buildVariantLookup(schema) {
       }
       break;
     case "object" :
-      let name$1 = DcbTag$Reventless.variantTagName(schema.items);
+      let name$1 = DcbTag$Reventless.variantTagName(schema.properties);
       if (name$1 !== undefined) {
         lookup[name$1] = "WithFields";
       }
       break;
-    case "union" :
+    case "anyOf" :
       schema.anyOf.forEach(variantSchema => {
         switch (variantSchema.type) {
           case "string" :
@@ -31,11 +31,12 @@ function buildVariantLookup(schema) {
               return;
             }
           case "object" :
-            let name$1 = DcbTag$Reventless.variantTagName(variantSchema.items);
+            let properties = variantSchema.properties;
+            let name$1 = DcbTag$Reventless.variantTagName(properties);
             if (name$1 === undefined) {
               return;
             }
-            let kind = Object.keys(variantSchema.properties).length === 0 ? "PayloadLess" : "WithFields";
+            let kind = Object.keys(properties).length === 0 ? "PayloadLess" : "WithFields";
             lookup[name$1] = kind;
             return;
           default:
@@ -55,7 +56,7 @@ function buildPayloadLessConstructors(schema, lookup) {
       return;
     }
     try {
-      let value = S.parseJsonOrThrow(tagName, schema);
+      let value = Util_Sury$Reventless.fromJson(tagName, schema);
       constructors[tagName] = value;
       return;
     } catch (exn) {
@@ -80,7 +81,7 @@ function makeDecoder(schema) {
     let jsonDict = Object.assign({}, data);
     jsonDict["TAG"] = eventType;
     try {
-      return Primitive_option.some(S.parseJsonOrThrow(jsonDict, schema));
+      return Primitive_option.some(Util_Sury$Reventless.fromJson(jsonDict, schema));
     } catch (exn) {
       console.warn("DcbDecode: dropped event `" + eventType + "` — payload does not match the current schema (drift?)");
       return;
@@ -97,4 +98,4 @@ export {
   buildPayloadLessConstructors,
   makeDecoder,
 }
-/* S Not a pure module */
+/* DcbTag-Reventless Not a pure module */

package/src/components/DcbTag.res

@@ -339,17 +339,18 @@ let extractTagsFromProperties = (properties: dict<S.t<unknown>>, jsonDict: dict<
   )
 
 // Extract the discriminating TAG constructor name from a variant Object schema's
-// `items`. sury compiles a record-payload variant `Foo({...})` to an Object whose
-// `items` carry one entry at location "TAG" holding a `String` const = "Foo".
-// Returns None for a non-tagged object (no TAG item, or a non-const schema).
+// `properties`. sury (11) compiles a record-payload variant `Foo({...})` to an
+// Object whose `properties` include a `"TAG"` key holding a `String` const = "Foo".
+// Returns None for a non-tagged object (no TAG property, or a non-const schema).
 // Single source for the ~dozen previously-inlined identical extractions across
-// this file, DcbDecode and DcbValidation.
-let variantTagName = (items: array<S.item>): option<string> =>
-  items
-  ->Array.find(item => item.location == "TAG")
-  ->Option.flatMap(item =>
-    switch item.schema {
-    | String({const}) => Some(const)
+// this file, DcbDecode and DcbValidation. (sury 11 replaced the alpha.4
+// `items`/`location` introspection with `properties` — see docs/plans/sury-11-migration.md.)
+let variantTagName = (properties: dict<S.t<unknown>>): option<string> =>
+  properties
+  ->Dict.get("TAG")
+  ->Option.flatMap(schema =>
+    switch schema {
+    | String({const: ?Some(name)}) => Some(name)
     | _ => None
     }
   )
@@ -362,7 +363,7 @@ only the fields of the matching variant branch are inspected.
 */
 let extractTagsFromJson = (schema: S.t<unknown>, json: JSON.t): array<tag> =>
   switch schema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     switch json->JSON.Decode.object {
     | Some(jsonDict) =>
       let jsonTag = jsonDict->Dict.get("TAG")->Option.flatMap(j =>
@@ -376,8 +377,8 @@ let extractTagsFromJson = (schema: S.t<unknown>, json: JSON.t): array<tag> =>
           acc
         } else {
           switch variantSchema {
-          | Object({items, properties}) =>
-            if variantTagName(items) == jsonTag {
+          | Object({properties}) =>
+            if variantTagName(properties) == jsonTag {
               extractTagsFromProperties(properties, jsonDict)
             } else {
               []
@@ -415,7 +416,7 @@ let tags = DcbTag.extractTags(
 ```
 */
 let extractTags = (schema: S.t<'a>, value: 'a): array<tag> =>
-  extractTagsFromJson(schema->toUnknownSchema, value->S.reverseConvertToJsonOrThrow(schema))
+  extractTagsFromJson(schema->toUnknownSchema, value->Util_Sury.toJson(schema))
 
 // --- Extract variant constructor names from a tagged union schema ---
 // For a variant type like `type event = ItemCreated({...}) | ItemRenamed({...})`,
@@ -431,10 +432,10 @@ Used by the DCB runtime to build `queryItem.eventTypes` arrays automatically.
 */
 let extractVariantNames = (schema: S.t<'a>): array<string> => {
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.filterMap(variantSchema =>
       switch variantSchema {
-      | Object({items}) => variantTagName(items)
+      | Object({properties}) => variantTagName(properties)
       // Payload-less variants (sury-compiled `S.literal("Name")` strings) are
       // intentionally excluded here: DCB event-type lookups can't WHERE-clause
       // on bare-string events, so Plugin_Structure.consumedEventTypes and
@@ -446,7 +447,7 @@ let extractVariantNames = (schema: S.t<'a>): array<string> => {
       | _ => None
       }
     )
-  | Object({items}) => variantTagName(items)->Option.mapOr([], t => [t])
+  | Object({properties}) => variantTagName(properties)->Option.mapOr([], t => [t])
   | _ => []
   }
 }
@@ -463,15 +464,15 @@ WHERE-clause filtering.
 */
 let extractAllVariantNames = (schema: S.t<'a>): array<string> => {
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.filterMap(variantSchema =>
       switch variantSchema {
-      | Object({items}) => variantTagName(items)
+      | Object({properties}) => variantTagName(properties)
       | String({const}) => Some(const)
       | _ => None
       }
     )
-  | Object({items}) => variantTagName(items)->Option.mapOr([], t => [t])
+  | Object({properties}) => variantTagName(properties)->Option.mapOr([], t => [t])
   | String({const: ?Some(name)}) => [name]
   | _ => []
   }
@@ -494,14 +495,14 @@ let isVariantPayloadBearing = (schema: S.t<'a>, name: string): bool => {
     false
   } else {
     switch schema->toUnknownSchema {
-    | Union({anyOf}) =>
+    | AnyOf({anyOf}) =>
       anyOf->Array.some(variantSchema =>
         switch variantSchema {
-        | Object({items}) => variantTagName(items)->Option.mapOr(false, t => t == name)
+        | Object({properties}) => variantTagName(properties)->Option.mapOr(false, t => t == name)
         | _ => false
         }
       )
-    | Object({items}) => variantTagName(items)->Option.mapOr(false, t => t == name)
+    | Object({properties}) => variantTagName(properties)->Option.mapOr(false, t => t == name)
     | _ => false
     }
   }
@@ -552,7 +553,7 @@ instead of a single tag with the stringified array.
 */
 let extractTagsFromJsonExpanded = (schema: S.t<unknown>, json: JSON.t): array<tag> =>
   switch schema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     switch json->JSON.Decode.object {
     | Some(jsonDict) =>
       let jsonTag = jsonDict->Dict.get("TAG")->Option.flatMap(j =>
@@ -566,8 +567,8 @@ let extractTagsFromJsonExpanded = (schema: S.t<unknown>, json: JSON.t): array<ta
           acc
         } else {
           switch variantSchema {
-          | Object({items, properties}) =>
-            if variantTagName(items) == jsonTag {
+          | Object({properties}) =>
+            if variantTagName(properties) == jsonTag {
               extractTagsFromPropertiesExpanded(properties, jsonDict)
             } else {
               []
@@ -599,7 +600,7 @@ let tags = DcbTag.extractTagsExpanded(
 ```
 */
 let extractTagsExpanded = (schema: S.t<'a>, value: 'a): array<tag> =>
-  extractTagsFromJsonExpanded(schema->toUnknownSchema, value->S.reverseConvertToJsonOrThrow(schema))
+  extractTagsFromJsonExpanded(schema->toUnknownSchema, value->Util_Sury.toJson(schema))
 
 // --- Automatic query construction from command schema ---
 
@@ -610,7 +611,7 @@ Used to automatically determine whether to build single-clause or multi-clause q
 */
 let hasTaggedArrayFields = (schema: S.t<'a>): bool =>
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.some(variantSchema =>
       switch variantSchema {
       | Object({properties}) =>
@@ -657,14 +658,14 @@ let extractTagKeysByEventType = (schema: S.t<'a>): dict<array<string>> => {
   let result = Dict.make()
   let addVariant = (variantSchema: S.t<unknown>) =>
     switch variantSchema {
-    | Object({items, properties}) =>
-      variantTagName(items)->Option.forEach(eventType =>
+    | Object({properties}) =>
+      variantTagName(properties)->Option.forEach(eventType =>
         result->Dict.set(eventType, tagKeysOfProperties(properties))
       )
     | _ => ()
     }
   switch schema->toUnknownSchema {
-  | Union({anyOf}) => anyOf->Array.forEach(addVariant)
+  | AnyOf({anyOf}) => anyOf->Array.forEach(addVariant)
   | Object(_) as obj => addVariant(obj)
   | _ => ()
   }
@@ -789,7 +790,7 @@ For `CatalogEventLog.event` returns `["categoryId", "productId"]`.
 */
 let extractTaggedFields = (schema: S.t<'event>): array<string> => {
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     // For union types, collect tagged fields from all variants
     let allFields = anyOf->Array.flatMap(variantSchema =>
       switch variantSchema {
@@ -860,7 +861,7 @@ returns `["studentId"]`.
 */
 let extractCrossPartitionTagKeys = (schema: S.t<'event>): array<string> => {
   let keys = switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.flatMap(variantSchema =>
       switch variantSchema {
       | Object({properties}) => crossPartitionKeysOfProperties(properties)
@@ -905,8 +906,8 @@ return a single shape.
 let eventShapesOfSchema = (schema: S.t<'a>): array<DcbScopeInference.eventShape> => {
   let ofVariant = (variantSchema: S.t<unknown>): option<DcbScopeInference.eventShape> =>
     switch variantSchema {
-    | Object({items, properties}) =>
-      variantTagName(items)->Option.map(eventType => {
+    | Object({properties}) =>
+      variantTagName(properties)->Option.map(eventType => {
         DcbScopeInference.eventType,
         idFields: idFieldsOfProperties(properties),
       })
@@ -914,7 +915,7 @@ let eventShapesOfSchema = (schema: S.t<'a>): array<DcbScopeInference.eventShape>
     | _ => None
     }
   switch schema->toUnknownSchema {
-  | Union({anyOf}) => anyOf->Array.filterMap(ofVariant)
+  | AnyOf({anyOf}) => anyOf->Array.filterMap(ofVariant)
   | Object(_) as obj => ofVariant(obj)->Option.mapOr([], s => [s])
   | _ => []
   }
@@ -927,7 +928,7 @@ Extracts field names annotated with `@s.matches(DcbTag.partition)` from an event
 */
 let extractPartitionTagFields = (schema: S.t<'event>): array<string> => {
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     let allFields = anyOf->Array.flatMap(variantSchema =>
       switch variantSchema {
       | Object({properties}) =>
@@ -1063,7 +1064,7 @@ If so, a partition tag annotation is needed to disambiguate.
 */
 let hasMultiTagVariant = (schema: S.t<unknown>): bool =>
   switch schema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.some(variantSchema =>
       switch variantSchema {
       | Object({properties}) => {
@@ -1096,14 +1097,14 @@ let findMultiTagVariantNames = (schema: S.t<unknown>): array<string> => {
   // Extract the variant name from a single object-variant schema via its TAG item.
   let variantName = (variantSchema: S.t<unknown>): option<string> =>
     switch variantSchema {
-    | Object({items, properties}) => {
+    | Object({properties}) => {
         let tagCount =
           properties
           ->Dict.toArray
           ->Array.filter(((_, fieldSchema)) => isTagged(fieldSchema))
           ->Array.length
         if tagCount > 1 {
-          Some(variantTagName(items)->Option.getOr("(unknown)"))
+          Some(variantTagName(properties)->Option.getOr("(unknown)"))
         } else {
           None
         }
@@ -1112,7 +1113,7 @@ let findMultiTagVariantNames = (schema: S.t<unknown>): array<string> => {
     }
 
   switch schema {
-  | Union({anyOf}) => anyOf->Array.filterMap(variantName)
+  | AnyOf({anyOf}) => anyOf->Array.filterMap(variantName)
   | _ =>
     // Single-variant event type — schema is the object directly
     switch variantName(schema) {
@@ -1159,7 +1160,7 @@ let extractCompositePartitionFields = (schema: S.t<'event>): array<compositePart
       }
     })
   switch schema->toUnknownSchema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     anyOf->Array.flatMap(variantSchema =>
       switch variantSchema {
       | Object({properties}) => collect(properties)