@reventlessdev/reventless-spec 3.0.0-alpha.81 → 3.0.0-alpha.83

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.83 (2026-07-28)
+
+### Features
+
+* **platform:** provision object stores from the fields that declare them ([b5e2a1e](https://github.com/ReventlessDev/reventless-core/commit/b5e2a1ec88099941c113e4963f9c4b346b96b0d6))
+
+
+# 3.0.0-alpha.82 (2026-07-28)
+
+### Features
+
+* **spec:** one semantic marker every typed semantic marks itself with ([aa18afc](https://github.com/ReventlessDev/reventless-core/commit/aa18afcf04c8edad9afe27e6fa4261d01e184da7))
+* **spec:** StorageRef — the first semantic type, declared on the field's type ([44f15c3](https://github.com/ReventlessDev/reventless-core/commit/44f15c37de71261d701d18a9f1ada6f481c4a8dc))
+
+
 # 3.0.0-alpha.81 (2026-07-26)
 
 ### Features

package/package.json

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

package/src/components/Plugin.res

@@ -374,6 +374,21 @@ type pluginStructure = {
   // read as []). js_nullable keeps it JSON-safe inside union variant payloads.
   extensionPoints: @s.matches(extensionPointDefArrayOptionSchema)
   option<array<extensionPointDef>>,
+  /**
+   The object stores this plugin's fields declare they need, deduplicated and
+   fully qualified as `{plugin}.{store}`.
+
+   A field typed as a storage ref states a *requirement*: the deployment needs
+   that store to exist. Collecting the requirement here is what lets it be read
+   without re-walking every component's schema — the same reason
+   `producedEventTypes` is carried rather than recomputed.
+
+   Qualified even for the common same-plugin case, so one entry has one shape
+   and the string is directly the store's identity. Optional and js_nullable for
+   the same reason as `extensionPoints`: definitions persisted before this field
+   existed still decode (absent → None, read as []).
+   */
+  requiredStores: @s.matches(stringArrayOptionSchema) option<array<string>>,
 }
 
 let pluginStructureOptionSchema = _jsNullable(pluginStructureSchema, ())

package/src/components/Plugin.res.mjs

@@ -186,7 +186,8 @@ let pluginStructureSchema = S.schema(s => ({
   outboundTranslationSlices: s.m(S.array(outboundTranslationSliceDefSchema)),
   inboundTranslationSlices: s.m(S.array(inboundTranslationSliceDefSchema)),
   extensions: s.m(S.array(extensionDefSchema)),
-  extensionPoints: s.m(extensionPointDefArrayOptionSchema)
+  extensionPoints: s.m(extensionPointDefArrayOptionSchema),
+  requiredStores: s.m(stringArrayOptionSchema)
 }));
 
 let pluginStructureOptionSchema = SuryResMjs.js_nullable(pluginStructureSchema);

package/src/components/Reference.res

@@ -1,8 +1,5 @@
 /** Identifies which entity a reference field points to. */
-type target = {entity: string, plugin: option<string>}
-
-/** Sury metadata ID for entity reference annotation. */
-let referenceId: S.Metadata.Id.t<target> = S.Metadata.Id.make(~namespace="reventless", ~name="reference")
+type target = Semantic.referenceTarget
 
 /**
 A sury string schema annotated as an entity reference field.
@@ -28,10 +25,14 @@ Prefer the `@ref("EntityName")` ppx shorthand over writing `@s.matches(...)` by
 ```
 */
 let to_ = (~plugin=?, ~key=?, entity: string): S.t<string> => {
+  // Reference-ness and DCB-tagged-ness are two independent facts that happen to
+  // co-occur here: this constructor declares both. `toWithoutDcbTag` declares
+  // only the first, and plain `DcbTag.string` only the second — so no consumer
+  // may infer either one from the other.
   let base =
     S.string
     ->S.Metadata.set(~id=DcbTag.dcbTagId, true)
-    ->S.Metadata.set(~id=referenceId, {entity, plugin})
+    ->Semantic.mark(~id=Semantic.Id.reference, ~payload=ReferenceTo({entity, plugin}))
   switch key {
   | Some(k) => base->S.Metadata.set(~id=DcbTag.dcbTagKeyOverrideId, k)
   | None => base
@@ -40,7 +41,10 @@ let to_ = (~plugin=?, ~key=?, entity: string): S.t<string> => {
 
 /** Returns the reference target if the schema carries `Reference.to_(...)` metadata. */
 let getTarget = (schema: S.t<unknown>): option<target> =>
-  S.Metadata.get(schema, ~id=referenceId)
+  switch Semantic.get(schema) {
+  | Some({payload: ReferenceTo(target)}) => Some(target)
+  | _ => None
+  }
 
 /**
 Like `to_` but does not imply DCB tag semantics.
@@ -48,4 +52,4 @@ Use with `@ref("Entity") @noDcbTag` when the field references another entity
 but should not participate in content-based event routing.
 */
 let toWithoutDcbTag = (~plugin=?, entity: string): S.t<string> =>
-  S.string->S.Metadata.set(~id=referenceId, {entity, plugin})
+  S.string->Semantic.mark(~id=Semantic.Id.reference, ~payload=ReferenceTo({entity, plugin}))

package/src/components/Reference.res.mjs

@@ -2,13 +2,15 @@
 
 import * as S from "sury/src/S.res.mjs";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
-
-let referenceId = S.Metadata.Id.make("reventless", "reference");
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
 function to_(plugin, key, entity) {
-  let base = S.Metadata.set(S.Metadata.set(S.string, DcbTag$Reventless.dcbTagId, true), referenceId, {
-    entity: entity,
-    plugin: plugin
+  let base = Semantic$Reventless.mark(S.Metadata.set(S.string, DcbTag$Reventless.dcbTagId, true), Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin
+    }
   });
   if (key !== undefined) {
     return S.Metadata.set(base, DcbTag$Reventless.dcbTagKeyOverrideId, key);
@@ -18,20 +20,31 @@ function to_(plugin, key, entity) {
 }
 
 function getTarget(schema) {
-  return S.Metadata.get(schema, referenceId);
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let target = match.payload;
+  if (typeof target !== "object" || target.TAG !== "ReferenceTo") {
+    return;
+  } else {
+    return target._0;
+  }
 }
 
 function toWithoutDcbTag(plugin, entity) {
-  return S.Metadata.set(S.string, referenceId, {
-    entity: entity,
-    plugin: plugin
+  return Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin
+    }
   });
 }
 
 export {
-  referenceId,
   to_,
   getTarget,
   toWithoutDcbTag,
 }
-/* referenceId Not a pure module */
+/* S Not a pure module */

package/src/semantic/Semantic.res

@@ -0,0 +1,67 @@
+/**
+The one marker every typed semantic marks itself with.
+
+A semantic type says what a field's value *is* — a date-time, a reference to
+another entity, a ref into an object store — as a property of the field's
+**type**, not as a string stapled beside it. Every layer downstream then derives
+from that single declaration: validation, the wire contract, the UI widget it
+gets rendered with, and eventually the infrastructure provisioned for it.
+
+Typed markers predate this module, and each was bespoke: `DateTime` carried its
+own metadata id, `Reference` carried another, and the schema walk detected both
+by hardcoded special case. That made every new typed marker new detection code.
+One shared marker means the walk reads a semantic generically and a new semantic
+type is a new *value*, not a new branch.
+
+The payload is a real variant rather than free-form JSON. The semantic
+vocabulary is framework-owned — an application declares a field *is* a storage
+ref, it does not invent what a storage ref means — so the set is closed, and a
+closed set typed here is one the compiler checks at every producer and consumer.
+It also keeps `Reference.getTarget` a total typed function instead of a decode
+that can fail at runtime.
+*/
+
+/** Which entity a reference field points to. */
+type referenceTarget = {entity: string, plugin: option<string>}
+
+/** Which object store a storage-ref field's value lives in. `plugin` is absent
+    when the store belongs to the declaring plugin, which is the common case. */
+type storeTarget = {plugin: option<string>, store: string}
+
+/** Per-semantic detail, for the semantics that carry any. */
+type payload =
+  | Plain
+  | ReferenceTo(referenceTarget)
+  | StoredIn(storeTarget)
+
+/** A field's semantic: the vocabulary id, plus its detail. */
+type t = {id: string, payload: payload}
+
+/**
+The semantic ids the framework itself defines.
+
+These strings are the wire vocabulary — they are what `x-reventless-semantic`
+carries, and the same vocabulary the string annotation path already uses, so the
+type path and the annotation path converge on one wire format rather than two.
+*/
+module Id = {
+  let dateTime = "dateTime"
+  let reference = "reference"
+  let storageRef = "storageRef"
+}
+
+let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")
+
+/** Mark a schema as carrying a semantic. */
+let mark = (schema: S.t<'a>, ~id: string, ~payload: payload=Plain): S.t<'a> =>
+  schema->S.Metadata.set(~id=semanticId, {id, payload})
+
+/** The semantic a field's schema carries, if any. */
+let get = (fieldSchema: S.t<'a>): option<t> => S.Metadata.get(fieldSchema, ~id=semanticId)
+
+/** Whether a field's schema carries this specific semantic. */
+let has = (fieldSchema: S.t<'a>, ~id: string): bool =>
+  switch get(fieldSchema) {
+  | Some(s) => s.id === id
+  | None => false
+  }

package/src/semantic/Semantic.res.mjs

@@ -0,0 +1,41 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+let Id = {
+  dateTime: "dateTime",
+  reference: "reference",
+  storageRef: "storageRef"
+};
+
+let semanticId = S.Metadata.Id.make("reventless", "semantic");
+
+function mark(schema, id, payloadOpt) {
+  let payload = payloadOpt !== undefined ? payloadOpt : "Plain";
+  return S.Metadata.set(schema, semanticId, {
+    id: id,
+    payload: payload
+  });
+}
+
+function get(fieldSchema) {
+  return S.Metadata.get(fieldSchema, semanticId);
+}
+
+function has(fieldSchema, id) {
+  let s = S.Metadata.get(fieldSchema, semanticId);
+  if (s !== undefined) {
+    return s.id === id;
+  } else {
+    return false;
+  }
+}
+
+export {
+  Id,
+  semanticId,
+  mark,
+  get,
+  has,
+}
+/* semanticId Not a pure module */

package/src/semantic/StorageRef.res

@@ -0,0 +1,124 @@
+/**
+A reference to an object living in one of the platform's object stores.
+
+The value is the ref string a store's presign service minted — an origin-relative
+path rooted at the store's served prefix, which the UI renders directly because
+the store is fronted read-only on the app's own origin.
+
+## Why this is a type and not a convention
+
+An event log is append-only, so whatever a command accepts into it is permanent.
+Before this type, an `imageUrl: string` field accepted *anything* — including an
+`https://` URL pointing at somebody else's server, or a multi-megabyte `data:`
+URI inlined into the event itself. Both deploy green, both are unfixable after
+the fact, and neither is what the field means. Declaring the field's type makes
+the wrong values unrepresentable at the boundary, before `decide` ever runs.
+
+The declaration also states a *requirement*: a field of this type says the
+deployment needs a store called `store` to exist. Nothing provisions that store
+yet, and that is a deliberate resting point — the validation hole is closed and
+the requirement is written down, which is strictly better than the status quo
+even if automatic provisioning never lands.
+
+## The grammar
+
+A ref is an absolute, origin-relative path of at least two non-empty segments:
+
+    /uploads/2f8c1e94-.../photo.jpg
+    /uploads/user-42/2f8c1e94-.../photo.jpg
+
+Rejected: anything with a scheme (`https://…`, `data:…`), protocol-relative
+`//host/path`, relative paths, empty segments, and `.`/`..` traversal.
+
+The framework mints refs in exactly this form — the presign service builds the
+object key as `{servedPrefix}/{identity}{uuid}/{fileName}` and returns `/{key}` —
+so the grammar is the framework's to define, not an application's.
+
+Note what is *not* checked: that the ref's prefix belongs to this specific store.
+Today every store shares one served prefix, so there is nothing store-specific to
+check against; the store identity is carried in the field's semantic payload,
+where provisioning and the UI read it. When stores gain per-store prefixes, this
+check tightens from a structural one to a per-store one without the type, the
+wire format, or any stored value changing.
+
+@example
+```rescript
+@schema type command =
+  | ChangeProductImage({
+      productId: @s.matches(DcbTag.string) string,
+      imageUrl: @storageRef("productImages") string,
+    })
+```
+*/
+
+/** The ref's representation. Transparent `string` on purpose: the marker refines
+    an existing `string` field rather than replacing it, so the field's runtime
+    representation — and therefore every stored event — is unchanged. A sealed
+    type here would defeat that, and would also be unattachable via `@s.matches`,
+    which requires the schema's type to match the field's. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+let segmentIsSafe = (segment: string) =>
+  segment !== "" && segment !== "." && segment !== ".."
+
+/**
+Validate a raw string as a storage ref, saying why when it is not one.
+
+This is the single definition of the grammar. `forStore`'s sury schema is derived
+from it rather than hand-rolling a second check, so the constructor and the
+schema validation cannot drift apart.
+*/
+let fromString = (raw: string): result<t, string> =>
+  if !String.startsWith(raw, "/") {
+    Error(
+      `expected an origin-relative storage ref starting with "/", got ${raw->JSON.Encode.string->JSON.stringify}. External URLs and data: URIs are not storage refs.`,
+    )
+  } else if String.startsWith(raw, "//") {
+    Error(`protocol-relative refs are not storage refs: ${raw}`)
+  } else {
+    let segments = raw->String.slice(~start=1, ~end=String.length(raw))->String.split("/")
+    if segments->Array.length < 2 {
+      Error(`a storage ref needs a prefix and an object path, got ${raw}`)
+    } else if !(segments->Array.every(segmentIsSafe)) {
+      Error(`a storage ref may not contain empty or traversal segments, got ${raw}`)
+    } else {
+      Ok(raw)
+    }
+  }
+
+/**
+The sury schema for a field holding a ref into a named store.
+
+Prefer the `@storageRef("<store>")` ppx shorthand over writing this by hand.
+Qualify the store as `"<plugin>.<store>"` to point at another plugin's store.
+*/
+let forStore = (~plugin: option<string>=?, ~store: string): S.t<t> =>
+  S.string
+  ->S.refine(s => value =>
+    // The empty string is admitted as the "no object" sentinel. The fields this
+    // marks are non-optional today, and a producer with nothing to reference —
+    // a supplier feed carrying no image, say — already writes `""` to mean
+    // absence. Rejecting it here would break a legitimate existing value and
+    // force an event-schema change, which this marker exists to avoid: it
+    // refines an existing `string` field without altering what is stored.
+    //
+    // Note this is a strictly weaker guarantee than `fromString`, which stays
+    // exact. Making these fields properly optional would let the sentinel go.
+    if value !== "" {
+      switch fromString(value) {
+      | Ok(_) => ()
+      | Error(why) => s.fail(why)
+      }
+    }
+  )
+  ->Semantic.mark(~id=Semantic.Id.storageRef, ~payload=StoredIn({plugin, store}))
+
+/** The store a field's schema declares its refs live in, if any. */
+let getStore = (schema: S.t<'a>): option<Semantic.storeTarget> =>
+  switch Semantic.get(schema) {
+  | Some({payload: StoredIn(target)}) => Some(target)
+  | _ => None
+  }

package/src/semantic/StorageRef.res.mjs

@@ -0,0 +1,85 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function segmentIsSafe(segment) {
+  if (segment !== "" && segment !== ".") {
+    return segment !== "..";
+  } else {
+    return false;
+  }
+}
+
+function fromString(raw) {
+  if (!raw.startsWith("/")) {
+    return {
+      TAG: "Error",
+      _0: `expected an origin-relative storage ref starting with "/", got ` + JSON.stringify(raw) + `. External URLs and data: URIs are not storage refs.`
+    };
+  }
+  if (raw.startsWith("//")) {
+    return {
+      TAG: "Error",
+      _0: `protocol-relative refs are not storage refs: ` + raw
+    };
+  }
+  let segments = raw.slice(1, raw.length).split("/");
+  if (segments.length < 2) {
+    return {
+      TAG: "Error",
+      _0: `a storage ref needs a prefix and an object path, got ` + raw
+    };
+  } else if (segments.every(segmentIsSafe)) {
+    return {
+      TAG: "Ok",
+      _0: raw
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a storage ref may not contain empty or traversal segments, got ` + raw
+    };
+  }
+}
+
+function forStore(plugin, store) {
+  return Semantic$Reventless.mark(S.refine(S.string, s => (value => {
+    if (value === "") {
+      return;
+    }
+    let why = fromString(value);
+    if (why.TAG === "Ok") {
+      return;
+    } else {
+      return s.fail(why._0, undefined);
+    }
+  })), Semantic$Reventless.Id.storageRef, {
+    TAG: "StoredIn",
+    _0: {
+      plugin: plugin,
+      store: store
+    }
+  });
+}
+
+function getStore(schema) {
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let target = match.payload;
+  if (typeof target !== "object" || target.TAG === "ReferenceTo") {
+    return;
+  } else {
+    return target._0;
+  }
+}
+
+export {
+  segmentIsSafe,
+  fromString,
+  forStore,
+  getStore,
+}
+/* S Not a pure module */

package/src/types/DateTime.res

@@ -21,13 +21,9 @@ type state = {
 ```
 */
 
-/** Internal sury metadata ID used to mark a date-time string field. */
-let dateTimeId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(~namespace="reventless", ~name="dateTime")
-
 /** A sury string schema annotated as an ISO-8601 date-time field.
     Use with `@s.matches(Reventless.DateTime.string)`. */
-let string: S.t<string> = S.string->S.Metadata.set(~id=dateTimeId, true)
+let string: S.t<string> = S.string->Semantic.mark(~id=Semantic.Id.dateTime)
 
 /** Whether a field schema carries the date-time marker. */
-let isDateTime = (fieldSchema: S.t<unknown>) =>
-  S.Metadata.get(fieldSchema, ~id=dateTimeId)->Option.isSome
+let isDateTime = (fieldSchema: S.t<unknown>) => fieldSchema->Semantic.has(~id=Semantic.Id.dateTime)

package/src/types/DateTime.res.mjs

@@ -1,19 +1,16 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
-import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
-let dateTimeId = S.Metadata.Id.make("reventless", "dateTime");
-
-let string = S.Metadata.set(S.string, dateTimeId, true);
+let string = Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.dateTime, undefined);
 
 function isDateTime(fieldSchema) {
-  return Stdlib_Option.isSome(S.Metadata.get(fieldSchema, dateTimeId));
+  return Semantic$Reventless.has(fieldSchema, Semantic$Reventless.Id.dateTime);
 }
 
 export {
-  dateTimeId,
   string,
   isDateTime,
 }
-/* dateTimeId Not a pure module */
+/* string Not a pure module */