@reventlessdev/reventless-spec 3.0.0-alpha.101 → 3.0.0-alpha.103

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.103 (2026-08-09)
+
+### Bug Fixes
+
+* **aws:** heal a persisted structure that predates a required list field ([dc4c42c](https://github.com/ReventlessDev/reventless-core/commit/dc4c42cab5a7db538d90edbce6d13b949830aad6))
+
+
+# 3.0.0-alpha.102 (2026-08-08)
+
+### Features
+
+* **core,spec:** surface a write-side component's declared error types ([c9c2505](https://github.com/ReventlessDev/reventless-core/commit/c9c25057c70595fe27d73447c9aef9b451f86168))
+
+
 # 3.0.0-alpha.101 (2026-08-05)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.101",
+  "version": "3.0.0-alpha.103",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/Plugin.res

@@ -288,6 +288,24 @@ type eventDef = {
   references: array<fieldReference>,
 }
 
+/**
+One declared error of a write side, with its field schema. Same shape and same
+derivation as `eventDef` — a refusal is a variant of `Spec.errorSchema` exactly as
+an emitted fact is a variant of `Spec.eventSchema`, so a consumer reading an
+error's payload walks it with the code path it already uses for an event. `name`
+is the variant name (e.g. `CategoryNotFound`) — the same string the runtime puts
+on `errorCode` when a decision is rejected (see `CommandTopic_Helpers`), so a
+caller can match what it reads here against what it receives. Payload-less
+variants (the common case for errors) carry an empty `schema` object and no
+references.
+*/
+@schema
+type errorDef = {
+  name: string,
+  schema: string,
+  references: array<fieldReference>,
+}
+
 @schema
 type writableDef = {
   name: string,
@@ -296,10 +314,24 @@ type writableDef = {
   consumedEventTypes: array<string>,
   linkedViews: array<string>,
   consistencyRead: @s.matches(stringOptionSchema) option<string>,
-  /** Emitted-event field schemas (Phase 6.3). Required like the other write-side
-  arrays; `[]` when there are none. The structure is re-derived on every build/
-  deploy, so no persisted-data back-compat shim is needed. */
+  /** Emitted-event field schemas. Required like the other write-side arrays; `[]`
+  when there are none. */
   events: array<eventDef>,
+  /** Declared-error field schemas — what this component can refuse a command with.
+  Required, on the same reasoning as `events`: the persisted copy is never decoded
+  through this schema (the event log carries it as an offload reference, and the
+  serving path reads it as raw JSON), so `[]` honestly means "declares no errors"
+  rather than "an older deploy could not say".
+
+  Being required does NOT make it safe to add such a field without a read-path
+  shim. A structure is re-derived on every build, but it is only RE-REGISTERED
+  when a plugin re-runs the connect handshake — which a plugin whose version never
+  changes may not do for a long time. Until then the serving path reads a
+  persisted structure that has no key for the new field, and against a `[T!]!` SDL
+  field that null propagates to the root and answers the whole query with `data:
+  null`. Both admin resolvers therefore heal absent required lists to `[]` on
+  read; a new one has to be added to that list too. */
+  errors: array<errorDef>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
   chapter: @s.matches(stringOptionSchema) option<string>,
 }

package/src/components/Plugin.res.mjs

@@ -127,6 +127,12 @@ let eventDefSchema = S.schema(s => ({
   references: s.m(S.array(fieldReferenceSchema))
 }));
 
+let errorDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  schema: s.m(S.string),
+  references: s.m(S.array(fieldReferenceSchema))
+}));
+
 let writableDefSchema = S.schema(s => ({
   name: s.m(S.string),
   commands: s.m(S.array(commandDefSchema)),
@@ -135,6 +141,7 @@ let writableDefSchema = S.schema(s => ({
   linkedViews: s.m(S.array(S.string)),
   consistencyRead: s.m(stringOptionSchema),
   events: s.m(S.array(eventDefSchema)),
+  errors: s.m(S.array(errorDefSchema)),
   chapter: s.m(stringOptionSchema)
 }));
 
@@ -248,6 +255,7 @@ export {
   commandDefSchema,
   queryableDefSchema,
   eventDefSchema,
+  errorDefSchema,
   writableDefSchema,
   automationSliceDefSchema,
   outboundTranslationSliceDefSchema,