@reventlessdev/reventless-spec 3.0.0-alpha.124 → 3.0.0-alpha.125

package/src/types/Trait.res

@@ -0,0 +1,62 @@
+// What a domain trait says about itself, so that a graft leaves a trace.
+//
+// A graft becomes ordinary host source — that is the design, and it is why every
+// other signal a trait leaves is source-side: the package dependency, the variant
+// spread, the `module X = Trait_Rules` alias, the conformance binding under
+// `tests/`. None of them survives into a deployed plugin, so a running estate
+// cannot answer "which of my components came from a trait" at all.
+//
+// This is the one fact that does survive, because it travels the way
+// `capabilityNeeds` does: a value the trait exports and the host names, collected
+// into `pluginStructure` while it is assembled and re-emitted whole on every
+// registration.
+//
+// **Nothing here is typed by a human.** The trait exports its own identity, so a
+// renamed or removed trait is a build error rather than a stale row; the version
+// is read from the trait's own package rather than restated; and the component is
+// filled in by the structure, which is the only party that knows which component
+// declared it. That is the whole reason this is a value rather than an
+// annotation — an attribute's fields would all be strings the compiler never
+// checks, which is the failure this program exists to remove.
+//
+// **A declaration is a claim about origin, never about behaviour.** After a graft
+// the developer owns the files and may edit them freely. So this says "grafted
+// from trait X", and it does NOT say "still behaves like trait X" — the thing that
+// answers the second question is the trait's conformance suite, which runs in the
+// consumer's build and reports separately. A reader that paints a declared graft
+// as verified is drawing a conclusion this field cannot support.
+
+/** Whether the graft reports back into the host it is grafted onto.
+
+    `WritesBack` publishes commands to its host — the geocoding shape, where the
+    slice reports its answer back onto the aggregate. `Observes` reads host events
+    and writes nothing back. `SelfContained` brings its own components and grafts
+    only by reading — the notification shape, which is what broke the
+    write-back assumption the first two specimens shared. */
+type posture =
+  | WritesBack
+  | Observes
+  | SelfContained
+
+let postureToString = (p: posture): string =>
+  switch p {
+  | WritesBack => "WritesBack"
+  | Observes => "Observes"
+  | SelfContained => "SelfContained"
+  }
+
+/**
+One trait's own account of itself, exported by the trait package.
+
+`version` is read from the trait's package at load time rather than restated in
+source — see `PackageVersion.fromModuleUrl`, which the certification CLI already
+resolves trait versions with. A trait whose package.json cannot be found reports
+`"0.0.0"`, which is visibly wrong rather than quietly stale.
+*/
+type t = {
+  /** The package, as it is depended on: `"@reventlessdev/trait-attachments"`. */
+  trait: string,
+  /** Resolved from the trait's own package, never written by hand. */
+  version: string,
+  posture: posture,
+}

package/src/types/Trait.res.mjs

@@ -0,0 +1,18 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function postureToString(p) {
+  switch (p) {
+    case "WritesBack" :
+      return "WritesBack";
+    case "Observes" :
+      return "Observes";
+    case "SelfContained" :
+      return "SelfContained";
+  }
+}
+
+export {
+  postureToString,
+}
+/* No side effect */

package/src/types/Transition.res

@@ -0,0 +1,71 @@
+// The lifecycle edge a command owns, declared as a value rather than as an
+// attribute on the constructor.
+//
+// `@transition([Orders.Placed] => Orders.Shipped)` says the same thing and is
+// still the shorter spelling for a command a host declares itself. It cannot say
+// it for a command a host did NOT declare: a variant spread splices members,
+// while the annotation lowers to a dict on the parent union, so a spliced
+// command arrives carrying no edge at all. Nor can the annotation be checked —
+// the PPX extracts leaf identifiers as strings, and the states belong to another
+// component's enum, so a misspelling survives to the plugin structure.
+//
+// A `command => t<'state>` switch answers both. It is exhaustive, so a spliced
+// constructor is a compile error until the host says what it does; and `'state`
+// is the view's own lifecycle enum, so `Customers.Active` is a constructor the
+// compiler resolves rather than a string nobody reads.
+//
+// `'state` is one type across the whole switch, which is a third thing the
+// annotation cannot do: every arm of one component's edges must name the same
+// lifecycle, and a from-set drawn from one enum with a target from another does
+// not compile.
+//
+// The type stays parameterised all the way down rather than storing names,
+// because erasing a constructor to its own name means asserting its runtime
+// representation — and this is the module that exists so nothing has to be
+// asserted. The erasure happens once, at the framework's type-erasure boundary
+// (`Plugin_Structure`), which already reads every spec member that way.
+//
+// The reference costs nothing at run time. A lifecycle enum's arms are
+// payload-less, so `[Customers.Active]` compiles to `["Active"]` and the
+// generated module imports nothing from the view — which is also why it cannot
+// cycle: a view spec holds no reference back to the aggregate it projects.
+//
+// Read the same way `commandAuthorization` is: `Plugin_Structure.toCommandDef`
+// evaluates it against a synthetic value per constructor.
+//
+// No `@schema`: nothing serialises a transition. It is read once, while the
+// plugin structure is assembled, and what leaves is the pair of names the
+// structure already carried.
+type t<'state> =
+  /** No edge declared: legal in every state, moves the row nowhere. The honest
+      answer for a report a slice publishes, which must not be refused because
+      the row moved on while the report was in flight. */
+  | Unrestricted
+  /** Brings the row into existence, so there is no state it could come from.
+      Distinct from `Unrestricted`, which draws no edge at all. */
+  | Creates('state)
+  /** Legal in these states, and moves the row nowhere. A positive claim rather
+      than an omission. */
+  | Guards(array<'state>)
+  /** Legal in these states, and lands the row in that one. */
+  | Moves(array<'state>, 'state)
+
+/** The from-set, or `None` for a command that names no states to come from —
+    which `Creates` and `Unrestricted` both do, for different reasons the target
+    tells apart. */
+let allowedStates = (transition: t<'state>): option<array<'state>> =>
+  switch transition {
+  | Unrestricted
+  | Creates(_) => None
+  | Guards(states)
+  | Moves(states, _) => Some(states)
+  }
+
+/** The state the command's handler writes, or `None` for one that moves nothing. */
+let targetState = (transition: t<'state>): option<'state> =>
+  switch transition {
+  | Unrestricted
+  | Guards(_) => None
+  | Creates(state)
+  | Moves(_, state) => Some(state)
+  }

package/src/types/Transition.res.mjs

@@ -0,0 +1,36 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+
+function allowedStates(transition) {
+  if (typeof transition !== "object") {
+    return;
+  }
+  switch (transition.TAG) {
+    case "Creates" :
+      return;
+    case "Guards" :
+    case "Moves" :
+      return transition._0;
+  }
+}
+
+function targetState(transition) {
+  if (typeof transition !== "object") {
+    return;
+  }
+  switch (transition.TAG) {
+    case "Creates" :
+      return Primitive_option.some(transition._0);
+    case "Guards" :
+      return;
+    case "Moves" :
+      return Primitive_option.some(transition._1);
+  }
+}
+
+export {
+  allowedStates,
+  targetState,
+}
+/* No side effect */