@reventlessdev/reventless-core 3.0.0-alpha.219 → 3.0.0-alpha.221

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.221 (2026-08-09)
+
+### Features
+
+* **ppx,spec,core:** [@live](https://github.com/live) on state declarations → top-level x-reventless-live schema key ([0f38f38](https://github.com/ReventlessDev/reventless-core/commit/0f38f38dc83c38da2fde6615b89a98cd7fda6fed))
+
+
+# 3.0.0-alpha.220 (2026-08-09)
+
+### Features
+
+* **core,aws:** bundle a runtime extension's companion packages, guard imports at deploy ([e975175](https://github.com/ReventlessDev/reventless-core/commit/e9751758f51582a8e46db362219f725bb5f1bcde))
+
+
 # 3.0.0-alpha.219 (2026-08-09)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.219",
+  "version": "3.0.0-alpha.221",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,21 +29,21 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.2",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.3",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.2",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.3",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.130",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.3",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.132",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.104"
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.106"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.62"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.64"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/adapter/RuntimeExtension/RuntimeExtension.res

@@ -90,6 +90,28 @@ trade than a loud, skipped hook.
 */
 module type Extension = {
   let moduleUrl: string
+  /**
+  `import.meta.url` of one module per COMPANION package this extension imports at
+  runtime — packages that must ride into the code archive alongside the
+  extension's own. `[]` for an extension importing nothing outside the
+  framework-provided set.
+
+  Needed because a companion is invisible to every conventional lookup: the
+  ecosystem convention for split packages declares the neutral core as a
+  `peerDependency` (true in the deploy program's process, false in the Lambda),
+  so a `dependencies` walk finds nothing; and a companion named by bare package
+  name has no resolution root the framework could use — the one thing that
+  resolves robustly is a module URL the companion states about itself, exactly
+  like `moduleUrl`. A companion package exposes one by exporting
+  `let moduleUrl: string = %raw("import.meta.url")` from any module the
+  extension already imports (spec modules can lift the
+  `@@reventless.spec`-injected one).
+
+  Companions are bundle-only: the entry shell imports only the extension
+  modules, and Node resolves companions from the archive's `node_modules` like
+  any other import.
+  */
+  let companionModuleUrls: array<string>
   let onColdStart: coldStartHook
 }
 
@@ -127,6 +149,18 @@ let moduleUrls = (): array<string> =>
     E.moduleUrl
   })
 
+/**
+Every registered extension's companion module URLs, flattened in registration
+order. Read only by the provider's code-archive builder — unlike `moduleUrls`,
+these never reach a runtime's config: companions are bundled so the extension's
+own imports resolve, not imported by the entry shell.
+*/
+let companionModuleUrls = (): array<string> =>
+  extensions.contents->Array.flatMap(e => {
+    module E = unpack(e)
+    E.companionModuleUrls
+  })
+
 let log = Logger.fromEnv()
 
 /**

package/src/adapter/RuntimeExtension/RuntimeExtension.res.mjs

@@ -26,6 +26,10 @@ function moduleUrls() {
   return extensions.contents.map(e => e.moduleUrl);
 }
 
+function companionModuleUrls() {
+  return extensions.contents.flatMap(e => e.companionModuleUrls);
+}
+
 let log = Logger$ReventlessCore.fromEnv();
 
 function runHook(hook, index, runtimeKind, component, plugin, platform) {
@@ -52,6 +56,7 @@ export {
   reset,
   isEmpty,
   moduleUrls,
+  companionModuleUrls,
   log,
   runHook,
   notifyColdStartHooks,

package/src/components/Api/SuryToJsonSchema.res

@@ -229,13 +229,22 @@ let deriveObjectSchema = (schema: S.t<unknown>): JSON.t =>
       ~optional=SchemaType.optionalFieldNames(schema),
       fields,
     )
-    // Surface component-level visibility on the top-level object schema.
-    // Omitted entirely for the default `Public` (None) so schemas stay compact.
+    // Surface component-level hints on the top-level object schema.
+    // Visibility is omitted entirely for the default `Public` (None) so schemas
+    // stay compact; live is emitted only when declared — an absent key means
+    // the consumer's own default applies.
     switch annotations {
-    | Some({visibility: Some(name)}) =>
+    | Some({visibility, live}) if visibility->Option.isSome || live->Option.isSome =>
       switch objSchema->JSON.Decode.object {
       | Some(obj) =>
-        obj->Dict.set("x-reventless-visibility", JSON.Encode.string(name))
+        switch visibility {
+        | Some(name) => obj->Dict.set("x-reventless-visibility", JSON.Encode.string(name))
+        | None => ()
+        }
+        switch live {
+        | Some(b) => obj->Dict.set("x-reventless-live", JSON.Encode.bool(b))
+        | None => ()
+        }
         JSON.Encode.object(obj)
       | None => objSchema
       }

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

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as SchemaType$ReventlessCore from "./SchemaType.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
@@ -267,13 +268,19 @@ function deriveObjectSchema(schema) {
   if (annotations === undefined) {
     return objSchema;
   }
-  let name = annotations.visibility;
-  if (name === undefined) {
+  let live = annotations.live;
+  let visibility = annotations.visibility;
+  if (!(Stdlib_Option.isSome(visibility) || Stdlib_Option.isSome(live))) {
     return objSchema;
   }
   let obj = Stdlib_JSON.Decode.object(objSchema);
   if (obj !== undefined) {
-    obj["x-reventless-visibility"] = name;
+    if (visibility !== undefined) {
+      obj["x-reventless-visibility"] = visibility;
+    }
+    if (live !== undefined) {
+      obj["x-reventless-live"] = live;
+    }
     return obj;
   } else {
     return objSchema;

package/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs

@@ -50,7 +50,8 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
   metric: [],
   status: undefined,
   groupBy: "kind",
-  visibility: undefined
+  visibility: undefined,
+  live: undefined
 });
 
 let name = "Plugins";

package/tests/adapter/RuntimeExtensionHookReachTest.res

@@ -47,6 +47,7 @@ describe("RuntimeExtension reaches the runtime callback hooks", () => {
     let seenAtColdStart: array<string> = []
     module Gatekeeper: RuntimeExtension.Extension = {
       let moduleUrl = "file:///pkg/gatekeeper.res.mjs"
+      let companionModuleUrls = []
       let onColdStart = (~runtimeKind as _, ~component, ~plugin as _, ~platform as _) => {
         seenAtColdStart->Array.push(component)
         CommandGenerator_Callback.registerCommandInterceptor(async (

package/tests/adapter/RuntimeExtensionHookReachTest.res.mjs

@@ -53,6 +53,7 @@ globalThis.describe("RuntimeExtension reaches the runtime callback hooks", () =>
   });
   globalThis.test("an interceptor registered at cold start denies a later command", async () => {
     let seenAtColdStart = [];
+    let companionModuleUrls = [];
     let onColdStart = (param, component, param$1, param$2) => {
       seenAtColdStart.push(component);
       CommandGenerator_Callback$ReventlessCore.registerCommandInterceptor(async (param, componentName, param$1, tag, param$2) => ({
@@ -62,6 +63,7 @@ globalThis.describe("RuntimeExtension reaches the runtime callback hooks", () =>
     };
     let Gatekeeper = {
       moduleUrl: "file:///pkg/gatekeeper.res.mjs",
+      companionModuleUrls: companionModuleUrls,
       onColdStart: onColdStart
     };
     RuntimeExtension$ReventlessCore.use(Gatekeeper);

package/tests/adapter/RuntimeExtensionTest.res

@@ -7,11 +7,12 @@ type call = {
   platform: option<string>,
 }
 
-let recorderNamed = (label: string, into: array<(string, call)>): module(
+let recorderNamed = (~companions: array<string>=[], label: string, into: array<(string, call)>): module(
   RuntimeExtension.Extension
 ) => {
   module R = {
     let moduleUrl = `file:///pkg/${label}.res.mjs`
+    let companionModuleUrls = companions
     let onColdStart = (~runtimeKind, ~component, ~plugin, ~platform) =>
       into->Array.push((label, {runtimeKind, component, plugin, platform}))
   }
@@ -32,6 +33,7 @@ describe("RuntimeExtension", () => {
   testSync("empty registry is the default and notifyColdStart is silent", () => {
     expect(RuntimeExtension.isEmpty())->toBe(true)
     expect(RuntimeExtension.moduleUrls())->toEqual([])
+    expect(RuntimeExtension.companionModuleUrls())->toEqual([])
     fireAggregate()
     expect(true)->toBe(true)
   })
@@ -77,10 +79,38 @@ describe("RuntimeExtension", () => {
     ])
   })
 
+  testSync("companionModuleUrls flattens every registration's companions, in order", () => {
+    let calls: array<(string, call)> = []
+    RuntimeExtension.use(
+      recorderNamed(
+        ~companions=["file:///pkg/companion-a.res.mjs", "file:///pkg/companion-b.res.mjs"],
+        "tracing",
+        calls,
+      ),
+    )
+    RuntimeExtension.use(recorderNamed("accounting", calls))
+    RuntimeExtension.use(
+      recorderNamed(~companions=["file:///pkg/companion-c.res.mjs"], "quota", calls),
+    )
+
+    expect(RuntimeExtension.companionModuleUrls())->toEqual([
+      "file:///pkg/companion-a.res.mjs",
+      "file:///pkg/companion-b.res.mjs",
+      "file:///pkg/companion-c.res.mjs",
+    ])
+    // Companions are bundle-only: the entry shell's import list is untouched.
+    expect(RuntimeExtension.moduleUrls())->toEqual([
+      "file:///pkg/tracing.res.mjs",
+      "file:///pkg/accounting.res.mjs",
+      "file:///pkg/quota.res.mjs",
+    ])
+  })
+
   testSync("a throwing extension is skipped; the runtime and its siblings survive", () => {
     let calls: array<(string, call)> = []
     module Broken: RuntimeExtension.Extension = {
       let moduleUrl = "file:///pkg/broken.res.mjs"
+      let companionModuleUrls = []
       let onColdStart = (~runtimeKind as _, ~component as _, ~plugin as _, ~platform as _) =>
         JsError.throwWithMessage("extension blew up")
     }

package/tests/adapter/RuntimeExtensionTest.res.mjs

@@ -3,7 +3,8 @@
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as RuntimeExtension$ReventlessCore from "../../src/adapter/RuntimeExtension/RuntimeExtension.res.mjs";
 
-function recorderNamed(label, into) {
+function recorderNamed(companionsOpt, label, into) {
+  let companions = companionsOpt !== undefined ? companionsOpt : [];
   let moduleUrl = `file:///pkg/` + label + `.res.mjs`;
   let onColdStart = (runtimeKind, component, plugin, platform) => {
     into.push([
@@ -18,6 +19,7 @@ function recorderNamed(label, into) {
   };
   return {
     moduleUrl: moduleUrl,
+    companionModuleUrls: companions,
     onColdStart: onColdStart
   };
 }
@@ -31,12 +33,13 @@ globalThis.describe("RuntimeExtension", () => {
   globalThis.test("empty registry is the default and notifyColdStart is silent", () => {
     globalThis.expect(RuntimeExtension$ReventlessCore.isEmpty()).toBe(true);
     globalThis.expect(RuntimeExtension$ReventlessCore.moduleUrls()).toEqual([]);
+    globalThis.expect(RuntimeExtension$ReventlessCore.companionModuleUrls()).toEqual([]);
     fireAggregate();
     globalThis.expect(true).toBe(true);
   });
   globalThis.test("a registered extension receives the runtime's full identity", () => {
     let calls = [];
-    RuntimeExtension$ReventlessCore.use(recorderNamed("tracing", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "tracing", calls));
     fireAggregate();
     globalThis.expect(calls).toEqual([[
         "tracing",
@@ -50,8 +53,8 @@ globalThis.describe("RuntimeExtension", () => {
   });
   globalThis.test("several extensions compose, in registration order", () => {
     let calls = [];
-    RuntimeExtension$ReventlessCore.use(recorderNamed("tracing", calls));
-    RuntimeExtension$ReventlessCore.use(recorderNamed("accounting", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "tracing", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "accounting", calls));
     fireAggregate();
     globalThis.expect(calls.map(param => param[0])).toEqual([
       "tracing",
@@ -60,23 +63,44 @@ globalThis.describe("RuntimeExtension", () => {
   });
   globalThis.test("moduleUrls reports every registration, in order", () => {
     let calls = [];
-    RuntimeExtension$ReventlessCore.use(recorderNamed("tracing", calls));
-    RuntimeExtension$ReventlessCore.use(recorderNamed("accounting", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "tracing", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "accounting", calls));
     globalThis.expect(RuntimeExtension$ReventlessCore.isEmpty()).toBe(false);
     globalThis.expect(RuntimeExtension$ReventlessCore.moduleUrls()).toEqual([
       "file:///pkg/tracing.res.mjs",
       "file:///pkg/accounting.res.mjs"
     ]);
   });
+  globalThis.test("companionModuleUrls flattens every registration's companions, in order", () => {
+    let calls = [];
+    RuntimeExtension$ReventlessCore.use(recorderNamed([
+      "file:///pkg/companion-a.res.mjs",
+      "file:///pkg/companion-b.res.mjs"
+    ], "tracing", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "accounting", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(["file:///pkg/companion-c.res.mjs"], "quota", calls));
+    globalThis.expect(RuntimeExtension$ReventlessCore.companionModuleUrls()).toEqual([
+      "file:///pkg/companion-a.res.mjs",
+      "file:///pkg/companion-b.res.mjs",
+      "file:///pkg/companion-c.res.mjs"
+    ]);
+    globalThis.expect(RuntimeExtension$ReventlessCore.moduleUrls()).toEqual([
+      "file:///pkg/tracing.res.mjs",
+      "file:///pkg/accounting.res.mjs",
+      "file:///pkg/quota.res.mjs"
+    ]);
+  });
   globalThis.test("a throwing extension is skipped; the runtime and its siblings survive", () => {
     let calls = [];
+    let companionModuleUrls = [];
     let onColdStart = (param, param$1, param$2, param$3) => Stdlib_JsError.throwWithMessage("extension blew up");
     let Broken = {
       moduleUrl: "file:///pkg/broken.res.mjs",
+      companionModuleUrls: companionModuleUrls,
       onColdStart: onColdStart
     };
     RuntimeExtension$ReventlessCore.use(Broken);
-    RuntimeExtension$ReventlessCore.use(recorderNamed("accounting", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "accounting", calls));
     fireAggregate();
     globalThis.expect(calls.map(param => param[0])).toEqual(["accounting"]);
   });
@@ -96,7 +120,7 @@ globalThis.describe("RuntimeExtension", () => {
   });
   globalThis.test("reset clears the registry", () => {
     let calls = [];
-    RuntimeExtension$ReventlessCore.use(recorderNamed("tracing", calls));
+    RuntimeExtension$ReventlessCore.use(recorderNamed(undefined, "tracing", calls));
     RuntimeExtension$ReventlessCore.reset();
     fireAggregate();
     globalThis.expect(RuntimeExtension$ReventlessCore.isEmpty()).toBe(true);

package/tests/api/SuryToJsonSchemaTest.res

@@ -34,6 +34,7 @@ let emptySpec: Reventless.StateAnnotations.stateAnnotationSpec = {
   status: None,
   groupBy: None,
   visibility: None,
+  live: None,
 }
 
 describe("SuryToJsonSchema:", () => {
@@ -427,6 +428,41 @@ describe("SuryToJsonSchema:", () => {
       let json = SuryToJsonSchema.deriveObjectSchema(schema')
       expect(getProperty(json, "x-reventless-visibility"))->toBe(None)
     })
+
+    testSync("emits x-reventless-live at top level when live is declared", () => {
+      let schema = S.schema(s => {"id": s.matches(S.string)})->S.castToUnknown
+      let offJson = SuryToJsonSchema.deriveObjectSchema(
+        schema->withSpec({...emptySpec, live: Some(false)}),
+      )
+      let onJson = SuryToJsonSchema.deriveObjectSchema(
+        schema->withSpec({...emptySpec, live: Some(true)}),
+      )
+      expect((
+        getProperty(offJson, "x-reventless-live")->Option.flatMap(JSON.Decode.bool),
+        getProperty(onJson, "x-reventless-live")->Option.flatMap(JSON.Decode.bool),
+      ))->toEqual((Some(false), Some(true)))
+    })
+
+    testSync("omits x-reventless-live when live is None (no annotation)", () => {
+      let schema = S.schema(s => {"id": s.matches(S.string)})->S.castToUnknown
+      let schema' = schema->withSpec({...emptySpec, live: None})
+      let json = SuryToJsonSchema.deriveObjectSchema(schema')
+      expect(getProperty(json, "x-reventless-live"))->toBe(None)
+    })
+
+    testSync("emits x-reventless-live and x-reventless-visibility together", () => {
+      let schema = S.schema(s => {"id": s.matches(S.string)})->S.castToUnknown
+      let schema' = schema->withSpec({
+        ...emptySpec,
+        visibility: Some("Internal"),
+        live: Some(false),
+      })
+      let json = SuryToJsonSchema.deriveObjectSchema(schema')
+      expect((
+        getProperty(json, "x-reventless-visibility")->Option.flatMap(JSON.Decode.string),
+        getProperty(json, "x-reventless-live")->Option.flatMap(JSON.Decode.bool),
+      ))->toEqual((Some("Internal"), Some(false)))
+    })
   })
 
   // Parity sanity-check: deriveObjectSchema and the legacy S.toJSONSchema must

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -81,7 +81,8 @@ let emptySpec = {
   metric: emptySpec_metric,
   status: undefined,
   groupBy: undefined,
-  visibility: undefined
+  visibility: undefined,
+  live: undefined
 };
 
 globalThis.describe("SuryToJsonSchema:", () => {
@@ -129,7 +130,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let entityIdSchema = getPropertyOf(json, "entityId");
@@ -161,7 +163,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let envSchema = getPropertyOf(json, "environment");
@@ -196,7 +199,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let versionSchema = getPropertyOf(json, "version");
@@ -227,7 +231,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let ownerIdSchema = getPropertyOf(json, "ownerId");
@@ -258,7 +263,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let categorySchema = getPropertyOf(json, "category");
@@ -286,7 +292,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let nameSchema = getPropertyOf(json, "name");
@@ -314,7 +321,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let deploymentIdSchema = getPropertyOf(json, "deploymentId");
@@ -349,7 +357,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let pluginNameSchema = getPropertyOf(json, "pluginName");
@@ -387,7 +396,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let componentsSchema = getPropertyOf(json, "components");
@@ -428,7 +438,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let componentsSchema = getPropertyOf(json, "components");
@@ -459,7 +470,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let componentsSchema = getPropertyOf(json, "components");
@@ -487,7 +499,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let statusSchema = getPropertyOf(json, "status");
@@ -522,7 +535,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let nameSchema = getPropertyOf(json, "name");
@@ -560,7 +574,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let totalSchema = getPropertyOf(json, "total");
@@ -601,7 +616,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
           ]],
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let metricObj = Stdlib_Option.flatMap(getPropertyOf(json, "total"), s => getProperty(s, "x-reventless-metric"));
@@ -640,7 +656,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
           ]],
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let metricObj = Stdlib_Option.flatMap(getPropertyOf(json, "total"), s => getProperty(s, "x-reventless-metric"));
@@ -674,7 +691,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: "kind",
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let kindSchema = getPropertyOf(json, "kind");
@@ -709,7 +727,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       let primarySchema = getPropertyOf(json, "primaryResource");
@@ -743,7 +762,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: "Internal"
+        visibility: "Internal",
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       globalThis.expect(Stdlib_Option.flatMap(getProperty(json, "x-reventless-visibility"), Stdlib_JSON.Decode.string)).toBe("Internal");
@@ -769,11 +789,124 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
       globalThis.expect(getProperty(json, "x-reventless-visibility")).toBe(undefined);
     });
+    globalThis.test("emits x-reventless-live at top level when live is declared", () => {
+      let schema = S.schema(s => ({
+        id: s.m(S.string)
+      }));
+      let offJson = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(withSpec(schema, {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: emptySpec_semantic,
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: undefined,
+        live: false
+      }));
+      let onJson = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(withSpec(schema, {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: emptySpec_semantic,
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: undefined,
+        live: true
+      }));
+      globalThis.expect([
+        Stdlib_Option.flatMap(getProperty(offJson, "x-reventless-live"), Stdlib_JSON.Decode.bool),
+        Stdlib_Option.flatMap(getProperty(onJson, "x-reventless-live"), Stdlib_JSON.Decode.bool)
+      ]).toEqual([
+        false,
+        true
+      ]);
+    });
+    globalThis.test("omits x-reventless-live when live is None (no annotation)", () => {
+      let schema = S.schema(s => ({
+        id: s.m(S.string)
+      }));
+      let schema$p = withSpec(schema, {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: emptySpec_semantic,
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: undefined,
+        live: undefined
+      });
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
+      globalThis.expect(getProperty(json, "x-reventless-live")).toBe(undefined);
+    });
+    globalThis.test("emits x-reventless-live and x-reventless-visibility together", () => {
+      let schema = S.schema(s => ({
+        id: s.m(S.string)
+      }));
+      let schema$p = withSpec(schema, {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: emptySpec_semantic,
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: "Internal",
+        live: false
+      });
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
+      globalThis.expect([
+        Stdlib_Option.flatMap(getProperty(json, "x-reventless-visibility"), Stdlib_JSON.Decode.string),
+        Stdlib_Option.flatMap(getProperty(json, "x-reventless-live"), Stdlib_JSON.Decode.bool)
+      ]).toEqual([
+        "Internal",
+        false
+      ]);
+    });
   });
   globalThis.describe("parity with S.toJSONSchema for unannotated objects:", () => {
     let getKeys = schema => {
@@ -835,7 +968,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let native = S.toJSONSchema(schema$p);
       let entityIdSchema = getPropertyOf(native, "entityId");
@@ -945,7 +1079,8 @@ globalThis.describe("SuryToJsonSchema:", () => {
         metric: emptySpec_metric,
         status: undefined,
         groupBy: undefined,
-        visibility: undefined
+        visibility: undefined,
+        live: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
       globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");

package/tests/commandtopic/CommandOutcomeHookTest.res

@@ -228,6 +228,7 @@ describe("CommandTopic command-outcome hook:", () => {
       // seam already reaches, so an extension picks it up alongside the other four.
       module Accountant: RuntimeExtension.Extension = {
         let moduleUrl = "file:///pkg/accountant.res.mjs"
+        let companionModuleUrls = []
         let onColdStart = (~runtimeKind as _, ~component as _, ~plugin as _, ~platform as _) =>
           record()
       }

package/tests/commandtopic/CommandOutcomeHookTest.res.mjs

@@ -321,9 +321,11 @@ globalThis.describe("CommandTopic command-outcome hook:", () => {
       globalThis.expect(observed.contents.length).toBe(0);
     });
     globalThis.test("an out-of-tree extension can register it from onColdStart", async () => {
+      let companionModuleUrls = [];
       let onColdStart = (param, param$1, param$2, param$3) => record();
       let Accountant = {
         moduleUrl: "file:///pkg/accountant.res.mjs",
+        companionModuleUrls: companionModuleUrls,
         onColdStart: onColdStart
       };
       RuntimeExtension$ReventlessCore.use(Accountant);

package/tests/plugin/PluginStructureTest.res

@@ -666,6 +666,17 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         orderIdField->Option.flatMap(s => getProperty(s, "x-reventless-id")),
       )->toBe(None)
     })
+
+    testSync("@live(false) flows through the PPX to top-level x-reventless-live", () => {
+      expect(
+        getProperty(annotatedSchema, "x-reventless-live")->Option.flatMap(JSON.Decode.bool),
+      )->toBe(Some(false))
+    })
+
+    testSync("unannotated state-view slice (Orders) has no top-level x-reventless-live", () => {
+      let ordersSchema = structure.stateViewSlices->Array.getUnsafe(0)->parseSchema
+      expect(getProperty(ordersSchema, "x-reventless-live"))->toBe(None)
+    })
   })
 
   // The generator captures each component's chapter (source-folder grouping band)

package/tests/plugin/PluginStructureTest.res.mjs

@@ -761,6 +761,13 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       let orderIdField = getPropertyOf(ordersSchema, "orderId");
       globalThis.expect(Stdlib_Option.flatMap(orderIdField, s => getProperty(s, "x-reventless-id"))).toBe(undefined);
     });
+    globalThis.test("@live(false) flows through the PPX to top-level x-reventless-live", () => {
+      globalThis.expect(Stdlib_Option.flatMap(getProperty(annotatedSchema, "x-reventless-live"), Stdlib_JSON.Decode.bool)).toBe(false);
+    });
+    globalThis.test("unannotated state-view slice (Orders) has no top-level x-reventless-live", () => {
+      let ordersSchema = JSON.parse(structure.stateViewSlices[0].schema);
+      globalThis.expect(getProperty(ordersSchema, "x-reventless-live")).toBe(undefined);
+    });
   });
   globalThis.describe("componentChapters threading", () => {
     let chaptered = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, [PsOrdersViewSlice], [

package/tests/plugin/StateViewSlice/PsAnnotatedView.res

@@ -9,6 +9,7 @@
 type consumedEvent =
   | ItemRecorded({itemId: string, ownerId: string, version: string, name: string, total: float})
 
+@live(false)
 @schema
 type state = {
   @id itemId: string,

package/tests/plugin/StateViewSlice/PsAnnotatedView.res.mjs

@@ -81,7 +81,8 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
     ]],
   status: undefined,
   groupBy: undefined,
-  visibility: undefined
+  visibility: undefined,
+  live: false
 });
 
 let name = "AnnotatedView";