@reventlessdev/reventless-core 3.0.0-alpha.238 → 3.0.0-alpha.240

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -132,6 +132,21 @@ let deriveObjectTypeWithNested = (
 ): array<string> =>
   switch SchemaType.fromSuryObject(~typeName, schema) {
   | Some(fields) =>
+    // `@internal` joins the caller's exclusions rather than replacing them. The
+    // caller's list is a decision made where the query entry is assembled; this
+    // one is a declaration on the field itself, and the schema is the better
+    // place for it — a hand-written list has to be kept in step with the record
+    // by whoever next edits it, which is the drift that made a hand-maintained
+    // `pluginExcludeFields` necessary in the first place.
+    //
+    // This is the single point for the SDL: every generated object type is
+    // derived here, so a field declared internal is absent from all of them
+    // without any entry having to say so.
+    let declaredInternal =
+      Reventless.StateAnnotations.getSpec(schema)
+      ->Option.flatMap(spec => spec.internal)
+      ->Option.getOr([])
+    let excludeFields = Array.concat(excludeFields, declaredInternal)
     let filteredFields = if excludeFields->Array.length > 0 {
       let d = Dict.make()
       fields
@@ -411,9 +426,16 @@ let deriveObjectQueryField = (
   ~subIdField: option<string>=?,
 ): string =>
   if includeIdParam {
+    // `includeRetired` reaches this door for the reason it reaches the list: a
+    // caller the server would serve a retired row to had, until it did, no way
+    // to ask for one *singly*. The archive toggle put such rows on screen and
+    // clicking one read a door that refuses them to everybody — `decideRetired`
+    // withholds from `Elevated` and `System` too until they ask, and here there
+    // was nothing to ask with.
     switch subIdField {
-    | Some(sortField) => `  ${singleFieldName}(id: ID!, ${sortField}: String!): ${typeName}`
-    | None => `  ${singleFieldName}(id: ID!): ${typeName}`
+    | Some(sortField) =>
+      `  ${singleFieldName}(id: ID!, ${sortField}: String!, includeRetired: Boolean): ${typeName}`
+    | None => `  ${singleFieldName}(id: ID!, includeRetired: Boolean): ${typeName}`
     }
   } else {
     `  ${singleFieldName}: ${typeName}`
@@ -434,7 +456,38 @@ let deriveByIdsQueryField = (
   ~listFieldName: string,
   ~returnTypeName: string,
 ): string =>
-  `  ${listFieldName}ByIds(ids: [String!]!): [${returnTypeName}!]!`
+  `  ${listFieldName}ByIds(ids: [String!]!, includeRetired: Boolean): [${returnTypeName}!]!`
+
+// ── The reference door ─────────────────────────────────────────────────────
+//
+// What a caller holding a pointer to a row may learn about it: its id, the label
+// a reference resolves to, and — where the view declares a retirement — whether
+// this row is in one and which state that is.
+//
+// The narrowness is the *type's*, which is the whole reason this is a separate
+// field rather than an argument on the by-ids door. A rule that answered a
+// retired row on the existing door "as long as only the safe fields were asked
+// for" would have to be re-implemented, identically, in four backends and to
+// survive aliases, fragments and `__typename`. Here a caller cannot ask for a
+// price, because the type has no price.
+//
+// Emitted for every view, not only for the ones that opted in, on exactly the
+// reasoning `includeRetired` states above: a field that appears and disappears
+// with an annotation makes adding or removing that annotation a breaking schema
+// change, and forces every client to feature-detect. What the annotation decides
+// is not whether the door exists but whether a *retired* row comes through it —
+// without it this is a cheap label read that narrows exactly as every other door
+// does.
+let deriveRefTypeSdl = (~returnTypeName: string): string =>
+  `type ${returnTypeName}Ref {\n  id: ID!\n  label: String!\n  retired: Boolean!\n  retiredState: String\n}`
+
+// `retiredState` is null in two cases that do not need telling apart by a
+// consumer: a live row, and a boolean-form retirement, where the field is the
+// state and `retired: true` has already said everything there is to say.
+let deriveRefsQueryField = (
+  ~listFieldName: string,
+  ~returnTypeName: string,
+): string => `  ${listFieldName}Refs(ids: [ID!]!): [${returnTypeName}Ref!]!`
 
 // `includeRetired` sits beside the paging arguments rather than inside `filter`,
 // and that placement is the point. `filter` is the caller's description of the
@@ -459,6 +512,63 @@ let deriveConnectionQueryField = (
   `  ${listFieldName}(filter: ${filterTypeName}${orderByArg}, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ${singularTypeName}Connection!`
 }
 
+// ── The by-index door ──────────────────────────────────────────────────────
+//
+// One derivation, called by every backend that serves this field, because the
+// alternative was tried and did not survive contact. The field used to be
+// emitted here for AppSync and again, independently, in the local adapter, and
+// the two agreed on neither its name, its argument nor its return type. Both
+// were wrong in the same way: each disagreed with the resolver standing behind
+// it. The AppSync shape declared `id: ID!` while its resolver read the index
+// field, so the value could not be passed at all; the local shape promised
+// `[String]` while its resolver returned whole rows, so every call failed to
+// serialise. A door that answers on no backend is a door whose signature can be
+// chosen on the merits, which is what the one below is.
+
+/** The row field an index is keyed on.
+
+For a named index (`@index("byOwner") ownerId`) the index name and the field it
+indexes differ, and it is the *field* every resolver filters on; for an unnamed
+index the two are the same string. */
+let indexKeyField = (indexConfig: Reventless.ReadModel.indexConfig): string =>
+  indexConfig.idField->Option.getOr(indexConfig.index)
+
+/** `<single>By<Index>`, dropping a leading `by` from the index name so
+`@index("byOwner")` reads `XByOwner` rather than `XByByOwner`. */
+let indexQueryFieldName = (~singleFieldName: string, ~index: string): string => {
+  let stripped = if index->String.startsWith("by") && index->String.length > 2 {
+    index->String.slice(~start=2, ~end=index->String.length)
+  } else {
+    index
+  }
+  singleFieldName ++ "By" ++ stripped->String.capitalize
+}
+
+/** The by-index door's signature.
+
+Paging and `includeRetired` are here for the reasons `deriveConnectionQueryField`
+gives above — this door reads a secondary index that can carry as many rows as
+the list, and an elevated caller that can widen every other door but this one
+would find the archive reachable by id and by list and not by the index that
+exists to look rows up. */
+let deriveIndexQueryField = (
+  ~singleFieldName: string,
+  ~indexConfig: Reventless.ReadModel.indexConfig,
+  ~connectionTypeName: string,
+): string => {
+  let fieldName = indexQueryFieldName(~singleFieldName, ~index=indexConfig.index)
+  let keyField = indexKeyField(indexConfig)
+  // An index with a sort key can be narrowed to one exact value on it. Optional,
+  // unlike the partition argument: naming the index value is what the door is
+  // for, narrowing further is a refinement. The AppSync sort template has read
+  // this argument all along, against an SDL that never offered it.
+  let sortArg = switch indexConfig.subIdField {
+  | Some(sortField) => `${sortField}: String, `
+  | None => ""
+  }
+  `  ${fieldName}(${keyField}: String!, ${sortArg}first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ${connectionTypeName}!`
+}
+
 // ── Mutation field derivation ──────────────────────────────────────────────
 
 let deriveMutationFieldFromObject = (
@@ -546,7 +656,7 @@ let generate = (
     // schema shape — see `mutationSchemaEntry.injectIdArg`.
     let injectIdArg = entry.injectIdArg->Option.getOr(true)
     switch schema {
-    | Union({anyOf}) =>
+    | AnyOf({anyOf}) =>
       // Map each fieldName to its variant in anyOf by matching the constructor
       // name. Position-based pairing (anyOf index ↔ fieldNames index) breaks
       // when `@noApi` filters out some variants but the schema still carries
@@ -555,17 +665,8 @@ let generate = (
       // index 1, leaking a stale `_0: Platform_Plugin_Deactivate_0` arg.
       let variantNames = anyOf->Array.map(v =>
         switch v {
-        | Object({items}) =>
-          items
-          ->Array.find(item => item.location == "TAG")
-          ->Option.flatMap(item =>
-            switch item.schema {
-            | String({const}) => Some(const)
-            | _ => None
-            }
-          )
-          ->Option.getOr("")
-        | String({const}) => const
+        | Object({properties}) => SchemaWalker.tagConstOf(properties)->Option.getOr("")
+        | String({const: ?Some(const)}) => const
         | _ => ""
         }
       )
@@ -652,6 +753,23 @@ let generate = (
           ~returnTypeName=entry.returnTypeName,
         ),
       )
+
+      // The reference door, under the by-ids condition because it is the same
+      // read. Emitted here rather than per-backend so the field a backend
+      // provisions a resolver for is one this SDL declares: the AppSync adapter
+      // registers `<list>Refs` for every queryable on exactly that premise, and
+      // a door named in one half and not the other fails the deploy outright.
+      let refTypeName = entry.returnTypeName ++ "Ref"
+      if !(seenTypes->Set.has(refTypeName)) {
+        seenTypes->Set.add(refTypeName)
+        types->Array.push(deriveRefTypeSdl(~returnTypeName=entry.returnTypeName))
+      }
+      queries->Array.push(
+        deriveRefsQueryField(
+          ~listFieldName=entry.listFieldName,
+          ~returnTypeName=entry.returnTypeName,
+        ),
+      )
     }
 
     let listFieldName = entry.listFieldName
@@ -677,17 +795,15 @@ let generate = (
     switch entry.indexQueries {
     | Some(indexes) =>
       let connectionTypeName = entry.returnTypeName ++ "Connection"
-      indexes->Array.forEach(({index}) => {
-        let stripped = if index->String.startsWith("by") && index->String.length > 2 {
-          index->String.slice(~start=2, ~end=index->String.length)
-        } else {
-          index
-        }
-        let fieldName = entry.singleFieldName ++ "By" ++ stripped->String.capitalize
+      indexes->Array.forEach(indexConfig =>
         queries->Array.push(
-          `  ${fieldName}(id: ID!, first: Int, after: String, last: Int, before: String): ${connectionTypeName}!`,
+          deriveIndexQueryField(
+            ~singleFieldName=entry.singleFieldName,
+            ~indexConfig,
+            ~connectionTypeName,
+          ),
         )
-      })
+      )
     | None => ()
     }
 

package/src/components/Api/GraphQL_FragmentGenerator.res.mjs

@@ -5,6 +5,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as Api_Naming$ReventlessCore from "./Api_Naming.res.mjs";
 import * as SchemaType$ReventlessCore from "./SchemaType.res.mjs";
+import * as SchemaWalker$ReventlessCore from "../../plugin/component/SchemaWalker.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as GraphQL_Stitcher$ReventlessCore from "./GraphQL_Stitcher.res.mjs";
 
@@ -116,12 +117,14 @@ function deriveObjectTypeWithNested(typeName, excludeFieldsOpt, includeIdParamOp
   if (fields === undefined) {
     return [];
   }
+  let declaredInternal = Stdlib_Option.getOr(Stdlib_Option.flatMap(StateAnnotations$Reventless.getSpec(schema), spec => spec.internal), []);
+  let excludeFields$1 = excludeFields.concat(declaredInternal);
   let filteredFields;
-  if (excludeFields.length !== 0) {
+  if (excludeFields$1.length !== 0) {
     let d = {};
     Object.entries(fields).forEach(param => {
       let k = param[0];
-      if (!excludeFields.some(ex => ex === k)) {
+      if (!excludeFields$1.some(ex => ex === k)) {
         d[k] = param[1];
         return;
       }
@@ -354,9 +357,9 @@ function deriveObjectQueryField(singleFieldName, typeName, includeIdParamOpt, su
   let includeIdParam = includeIdParamOpt !== undefined ? includeIdParamOpt : true;
   if (includeIdParam) {
     if (subIdField !== undefined) {
-      return `  ` + singleFieldName + `(id: ID!, ` + subIdField + `: String!): ` + typeName;
+      return `  ` + singleFieldName + `(id: ID!, ` + subIdField + `: String!, includeRetired: Boolean): ` + typeName;
     } else {
-      return `  ` + singleFieldName + `(id: ID!): ` + typeName;
+      return `  ` + singleFieldName + `(id: ID!, includeRetired: Boolean): ` + typeName;
     }
   } else {
     return `  ` + singleFieldName + `: ` + typeName;
@@ -368,7 +371,15 @@ function deriveListQueryField(listFieldName, pluralTypeName) {
 }
 
 function deriveByIdsQueryField(listFieldName, returnTypeName) {
-  return `  ` + listFieldName + `ByIds(ids: [String!]!): [` + returnTypeName + `!]!`;
+  return `  ` + listFieldName + `ByIds(ids: [String!]!, includeRetired: Boolean): [` + returnTypeName + `!]!`;
+}
+
+function deriveRefTypeSdl(returnTypeName) {
+  return `type ` + returnTypeName + `Ref {\n  id: ID!\n  label: String!\n  retired: Boolean!\n  retiredState: String\n}`;
+}
+
+function deriveRefsQueryField(listFieldName, returnTypeName) {
+  return `  ` + listFieldName + `Refs(ids: [ID!]!): [` + returnTypeName + `Ref!]!`;
 }
 
 function deriveConnectionQueryField(listFieldName, singularTypeName, filterTypeName, hasOrderByOpt) {
@@ -377,6 +388,23 @@ function deriveConnectionQueryField(listFieldName, singularTypeName, filterTypeN
   return `  ` + listFieldName + `(filter: ` + filterTypeName + orderByArg + `, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ` + singularTypeName + `Connection!`;
 }
 
+function indexKeyField(indexConfig) {
+  return Stdlib_Option.getOr(indexConfig.idField, indexConfig.index);
+}
+
+function indexQueryFieldName(singleFieldName, index) {
+  let stripped = index.startsWith("by") && index.length > 2 ? index.slice(2, index.length) : index;
+  return singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+}
+
+function deriveIndexQueryField(singleFieldName, indexConfig, connectionTypeName) {
+  let fieldName = indexQueryFieldName(singleFieldName, indexConfig.index);
+  let keyField = indexKeyField(indexConfig);
+  let sortField = indexConfig.subIdField;
+  let sortArg = sortField !== undefined ? sortField + `: String, ` : "";
+  return `  ` + fieldName + `(` + keyField + `: String!, ` + sortArg + `first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ` + connectionTypeName + `!`;
+}
+
 function deriveMutationFieldFromObject(fieldName, collectedTypes, seenTypes, variantSchema) {
   let fields = SchemaType$ReventlessCore.fromSuryObject(fieldName, variantSchema);
   if (fields === undefined) {
@@ -419,7 +447,7 @@ function generate(mutationEntries, queryEntries) {
         } else {
           return;
         }
-      case "union" :
+      case "anyOf" :
         let anyOf = schema.anyOf;
         let variantNames = anyOf.map(v => {
           switch (v.type) {
@@ -431,16 +459,7 @@ function generate(mutationEntries, queryEntries) {
                 return "";
               }
             case "object" :
-              return Stdlib_Option.getOr(Stdlib_Option.flatMap(v.items.find(item => item.location === "TAG"), item => {
-                let match = item.schema;
-                if (match.type !== "string") {
-                  return;
-                }
-                let $$const = match.const;
-                if ($$const !== undefined) {
-                  return $$const;
-                }
-              }), "");
+              return Stdlib_Option.getOr(SchemaWalker$ReventlessCore.tagConstOf(v.properties), "");
             default:
               return "";
           }
@@ -481,6 +500,12 @@ function generate(mutationEntries, queryEntries) {
     queries.push(singleField);
     if (includeIdParam && entry.subIdField === undefined) {
       queries.push(deriveByIdsQueryField(entry.listFieldName, entry.returnTypeName));
+      let refTypeName = entry.returnTypeName + "Ref";
+      if (!seenTypes.has(refTypeName)) {
+        seenTypes.add(refTypeName);
+        types.push(deriveRefTypeSdl(entry.returnTypeName));
+      }
+      queries.push(deriveRefsQueryField(entry.listFieldName, entry.returnTypeName));
     }
     let listFieldName = entry.listFieldName;
     let _sf = entry.subIdField;
@@ -495,11 +520,8 @@ function generate(mutationEntries, queryEntries) {
     let indexes = entry.indexQueries;
     if (indexes !== undefined) {
       let connectionTypeName = entry.returnTypeName + "Connection";
-      indexes.forEach(param => {
-        let index = param.index;
-        let stripped = index.startsWith("by") && index.length > 2 ? index.slice(2, index.length) : index;
-        let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
-        queries.push(`  ` + fieldName + `(id: ID!, first: Int, after: String, last: Int, before: String): ` + connectionTypeName + `!`);
+      indexes.forEach(indexConfig => {
+        queries.push(deriveIndexQueryField(entry.singleFieldName, indexConfig, connectionTypeName));
       });
     }
     if (connectionSpec) {
@@ -579,7 +601,12 @@ export {
   deriveObjectQueryField,
   deriveListQueryField,
   deriveByIdsQueryField,
+  deriveRefTypeSdl,
+  deriveRefsQueryField,
   deriveConnectionQueryField,
+  indexKeyField,
+  indexQueryFieldName,
+  deriveIndexQueryField,
   deriveMutationFieldFromObject,
   mutationArgTypes,
   generate,

package/src/components/Api/GraphQL_SchemaInspector.res

@@ -29,7 +29,7 @@ let inspectMutationFields = (~fieldPrefix: string, commandSchema: S.t<'a>): arra
   let collectedTypes: array<string> = []
   let seenTypes = Set.make()
   switch schema {
-  | Union({anyOf}) =>
+  | AnyOf({anyOf}) =>
     let constructorNames = Reventless.DcbTag.extractAllVariantNames(commandSchema)
     anyOf->Array.forEachWithIndex((variantSchema, i) => {
       let fieldName = switch constructorNames->Array.get(i) {

package/src/components/Api/GraphQL_SchemaInspector.res.mjs

@@ -27,7 +27,7 @@ function inspectMutationFields(fieldPrefix, commandSchema) {
         fields.push(field);
       });
       break;
-    case "union" :
+    case "anyOf" :
       let constructorNames = DcbTag$Reventless.extractAllVariantNames(commandSchema);
       commandSchema.anyOf.forEach((variantSchema, i) => {
         let name = constructorNames[i];

package/src/components/Api/MCP_SchemaGenerator.res

@@ -52,7 +52,7 @@ let generateTools = (
     let entryDescription = entry.description->Option.getOr("")
 
     switch schema {
-    | Union({anyOf}) =>
+    | AnyOf({anyOf}) =>
       // Aggregate commands: each variant is a separate tool.
       // Inject an "id" property (aggregate instance ID) since aggregate
       // commands target a specific instance.

package/src/components/Api/MCP_SchemaGenerator.res.mjs

@@ -33,7 +33,7 @@ function generateTools(pluginName, mutationEntries) {
           inputSchema: inputSchema
         });
         return;
-      case "union" :
+      case "anyOf" :
         schema.anyOf.forEach((variantSchema, i) => {
           let fieldName = Stdlib_Option.getOr(entry.fieldNames[i], "");
           if (fieldName.length <= 0) {

package/src/components/Api/SchemaType.res

@@ -99,15 +99,11 @@ and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): s
     | BigInt(_) => ScalarBigInt
     | Array({items, additionalItems}) =>
       let itemType = switch items->Array.get(0) {
-      | Some({schema: itemSchema}) =>
-        fromSury(
-          ~parentName,
-          ~fieldName,
-          itemSchema->(Obj.magic: S.t<unknown> => S.t<unknown>),
-        )
+      | Some(itemSchema) => fromSury(~parentName, ~fieldName, itemSchema)
       | None =>
-        // sury stores the item schema in additionalItems (not items) for S.array().
-        // additionalItems is @unboxed: Strip="strip", Strict="strict", Schema(t) = the schema object.
+        // For a homogeneous S.array() sury stores the element schema in
+        // additionalItems (items holds fixed tuple positions). additionalItems is
+        // @unboxed: Strip="strip" | Strict="strict" | Schema(t) = the schema object.
         switch additionalItems {
         | Schema(s) => fromSury(~parentName, ~fieldName, s)
         | _ => ScalarString
@@ -135,7 +131,7 @@ and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): s
       } else {
         ObjectRef(nestedName, fields)
       }
-    | Union({anyOf}) =>
+    | AnyOf({anyOf}) =>
       let nonNullVariants = anyOf->Array.filter(v =>
         switch v {
         | Null(_) | Undefined(_) => false
@@ -196,7 +192,7 @@ let optionalFieldNames = (schema: S.t<unknown>): array<string> =>
     ->Dict.toArray
     ->Array.filterMap(((propName, propSchema)) =>
       switch propSchema {
-      | Union({anyOf}) =>
+      | AnyOf({anyOf}) =>
         anyOf->Array.some(v =>
           switch v {
           | Null(_) | Undefined(_) => true

package/src/components/Api/SchemaType.res.mjs

@@ -92,8 +92,8 @@ function shapeOf(parentName, fieldName, schema) {
       };
     case "array" :
       let additionalItems = schema.additionalItems;
-      let match = schema.items[0];
-      let itemType = match !== undefined ? fromSury(parentName, fieldName, match.schema) : (
+      let itemSchema = schema.items[0];
+      let itemType = itemSchema !== undefined ? fromSury(parentName, fieldName, itemSchema) : (
           additionalItems === "strip" || additionalItems === "strict" ? "ScalarString" : fromSury(parentName, fieldName, additionalItems)
         );
       let itemType$1 = (isIdsFieldName(fieldName) || isIdFieldName(fieldName)) && itemType === "ScalarString" ? "EntityId" : itemType;
@@ -120,7 +120,7 @@ function shapeOf(parentName, fieldName, schema) {
           _1: fields
         };
       }
-    case "union" :
+    case "anyOf" :
       let anyOf = schema.anyOf;
       let nonNullVariants = anyOf.filter(v => {
         switch (v.type) {
@@ -173,7 +173,7 @@ function optionalFieldNames(schema) {
   if (schema.type === "object") {
     return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
       let propSchema = param[1];
-      if (propSchema.type === "union" && propSchema.anyOf.some(v => {
+      if (propSchema.type === "anyOf" && propSchema.anyOf.some(v => {
           switch (v.type) {
             case "null" :
             case "undefined" :

package/src/components/Api/StorageRefFields.res

@@ -78,7 +78,7 @@ to qualify a store the annotation left unqualified.
 */
 let fromEventSchema = (~plugin: string, eventSchema: S.t<unknown>): array<eventRefFields> =>
   switch eventSchema {
-  | Union({anyOf}) => anyOf->Array.filterMap(v => fromVariant(~plugin, v))
+  | AnyOf({anyOf}) => anyOf->Array.filterMap(v => fromVariant(~plugin, v))
   | other => fromVariant(~plugin, other)->Option.mapOr([], e => [e])
   }
 

package/src/components/Api/StorageRefFields.res.mjs

@@ -44,7 +44,7 @@ function fromVariant(plugin, variant) {
 }
 
 function fromEventSchema(plugin, eventSchema) {
-  if (eventSchema.type === "union") {
+  if (eventSchema.type === "anyOf") {
     return Stdlib_Array.filterMap(eventSchema.anyOf, v => fromVariant(plugin, v));
   } else {
     return Stdlib_Option.mapOr(fromVariant(plugin, eventSchema), [], e => [e]);

package/src/components/Api/SuryToJsonSchema.res

@@ -137,6 +137,14 @@ let mergeAnnotations = (
       }
       let entries =
         r.label === "" ? entries : Array.concat([("label", JSON.Encode.string(r.label))], entries)
+      // `namedWhenRetired` travels only when true, on the omit-the-default rule
+      // the keys above follow: false is what every record said before the opt-in
+      // existed, and writing it would put a key on every retirement to say
+      // nothing changed.
+      let entries =
+        r.namedWhenRetired
+          ? Array.concat(entries, [("namedWhenRetired", JSON.Encode.bool(true))])
+          : entries
       obj->Dict.set("x-reventless-retired", JSON.Encode.object(Dict.fromArray(entries)))
     | _ => ()
     }
@@ -255,8 +263,19 @@ and objectRefToJsonSchema = (
 ): JSON.t => {
   let props = Dict.make()
   let required: array<string> = []
+  // `@internal` fields are dropped rather than annotated. A marker would be the
+  // right answer for a field that is on the surface and merely unwanted (that is
+  // `@hidden`); this one is not on the surface at all, so there is nothing for a
+  // consumer to describe and an entry here would advertise a field the SDL does
+  // not declare — which is precisely the mismatch that made read-model queries
+  // reference fields the server rejects.
+  //
+  // This is the single point for every JSON-Schema consumer: `queryableDef.schema`,
+  // the MCP generator and the manifest all derive through this walk.
+  let internal = annotations->Option.flatMap(spec => spec.internal)->Option.getOr([])
   fields
   ->Dict.toArray
+  ->Array.filter(((fieldName, _)) => !(internal->Array.includes(fieldName)))
   ->Array.forEach(((fieldName, fieldType)) => {
     let baseSchema = fromSchemaType(fieldType)
     let withAnnotations = switch annotations {

package/src/components/Api/SuryToJsonSchema.res.mjs

@@ -119,20 +119,24 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
           "label",
           r.label
         ]].concat(entries$1);
-    obj["x-reventless-retired"] = Object.fromEntries(entries$3);
+    let entries$4 = r.namedWhenRetired ? entries$3.concat([[
+          "namedWhenRetired",
+          true
+        ]]) : entries$3;
+    obj["x-reventless-retired"] = Object.fromEntries(entries$4);
   }
   let match$4 = spec.metric.find(param => param[0] === fieldName);
   if (match$4 !== undefined) {
     let m = match$4[1];
-    let entries$4 = [[
+    let entries$5 = [[
         "aggregate",
         m.aggregate
       ]];
-    let entries$5 = m.label === "" ? entries$4 : entries$4.concat([[
+    let entries$6 = m.label === "" ? entries$5 : entries$5.concat([[
           "label",
           m.label
         ]]);
-    obj["x-reventless-metric"] = Object.fromEntries(entries$5);
+    obj["x-reventless-metric"] = Object.fromEntries(entries$6);
   }
   return obj;
 }
@@ -277,7 +281,8 @@ function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, fields) {
   let owners = ownersOpt !== undefined ? ownersOpt : [];
   let props = {};
   let required = [];
-  Object.entries(fields).forEach(param => {
+  let internal = Stdlib_Option.getOr(Stdlib_Option.flatMap(annotations, spec => spec.internal), []);
+  Object.entries(fields).filter(param => !internal.includes(param[0])).forEach(param => {
     let fieldType = param[1];
     let fieldName = param[0];
     let baseSchema = fromSchemaType(fieldType);

package/src/components/AutomationSlice/AutomationSlice_Callback.res

@@ -1,4 +1,3 @@
-S.enableJson()
 // AutomationSlice callback — implements the TODO list pattern with mixed-source
 // dispatch (Plan 04).
 //
@@ -143,7 +142,7 @@ module Make = (
           | Some(_) => () // Already exists — skip
           | None =>
             let row: todoRow = {
-              item: item->S.reverseConvertToJsonOrThrow(Spec.todoItemSchema),
+              item: item->Reventless.Util_Sury.toJson(Spec.todoItemSchema),
               status: Pending,
               createdAt: now(),
               retryCount: 0,
@@ -198,7 +197,7 @@ module Make = (
     let commands = []
 
     pending->Array.forEach(((id, row)) => {
-      let item = try row.item->S.parseJsonOrThrow(Spec.todoItemSchema)->Some catch {
+      let item = try row.item->Reventless.Util_Sury.fromJson(Spec.todoItemSchema)->Some catch {
       | exn =>
         let errMsg =
           exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown")
@@ -214,7 +213,7 @@ module Make = (
         | Some((targetId, command)) =>
           todoItems->Dict.set(id, {...row, status: Processing, processedAt: now()})
           let commandJson = try command
-          ->S.reverseConvertToJsonOrThrow(Spec.commandSchema)
+          ->Reventless.Util_Sury.toJson(Spec.commandSchema)
           ->Some catch {
           | exn =>
             let errMsg =