@adea-ai/spatial 0.118.4 → 0.118.5

package/dist/sim-bridge/messages.d.ts

@@ -51,9 +51,15 @@ export type SimFrameRequestMessage = Readonly<{
     }>;
 }> | Readonly<{
     type: 'frame.character.save';
+    /**
+     * `revision` orders saves from one frame: it increases with every save request the frame
+     * makes, so the host can refuse one older than a save it already committed. Optional so
+     * frames built before it keep working.
+     */
     payload: Readonly<{
         requestId: string;
         character: string;
+        revision?: number;
     }>;
 }>;
 /** The scene channel's acknowledgements, refusals and measurements (see `scene.ts`). */

package/dist/sim-bridge/messages.js

@@ -136,11 +136,23 @@ export function parseFrameMessage(event, context) {
                 : fail('invalid_payload');
         }
         case 'frame.character.save': {
-            const body = strictRecord(payload, ['requestId', 'character']);
+            const body = strictRecord(payload, ['requestId', 'character'], ['revision']);
             const requestId = boundedString(body?.requestId, REQUEST_ID);
             const character = parseSimCharacterValue(body?.character);
+            const revision = body?.revision;
+            if (revision !== undefined &&
+                (typeof revision !== 'number' || !Number.isSafeInteger(revision) || revision < 1))
+                return fail('invalid_payload');
             return requestId && character
-                ? { ok: true, message: { type, payload: { requestId, character } } }
+                ? {
+                    ok: true,
+                    message: {
+                        type,
+                        payload: revision === undefined
+                            ? { requestId, character }
+                            : { requestId, character, revision },
+                    },
+                }
                 : fail('invalid_payload');
         }
         case 'frame.scene.ack':

package/dist/sim-bridge/save-client.d.ts

@@ -8,7 +8,10 @@ import type { SimFrameRequestMessage, SimHostMessage } from './messages';
  * `false`, so the engine never shows a saved value the host did not commit.
  */
 export type CharacterSaveClient = Readonly<{
-    save(character: string): Promise<boolean>;
+    /** `revision` (a positive integer that increases per save) lets the host refuse an older save. */
+    save(character: string, options?: Readonly<{
+        revision?: number;
+    }>): Promise<boolean>;
     /** Feed every parsed host message in; unrelated ones are ignored. */
     receive(message: SimHostMessage): void;
     /** Fails any open save. Call when the frame is torn down. */

package/dist/sim-bridge/save-client.js

@@ -15,8 +15,12 @@ export function createCharacterSaveClient(options) {
         open?.settle(false);
     }
     return {
-        save(character) {
-            if (disposed || open || parseSimCharacterValue(character) === null)
+        save(character, saveOptions) {
+            const revision = saveOptions?.revision;
+            if (disposed ||
+                open ||
+                parseSimCharacterValue(character) === null ||
+                (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1)))
                 return Promise.resolve(false);
             const requestId = mint();
             return new Promise((resolve) => {
@@ -33,7 +37,12 @@ export function createCharacterSaveClient(options) {
                 };
                 open = entry;
                 try {
-                    options.post({ type: 'frame.character.save', payload: { requestId, character } });
+                    options.post({
+                        type: 'frame.character.save',
+                        payload: revision === undefined
+                            ? { requestId, character }
+                            : { requestId, character, revision },
+                    });
                 }
                 catch {
                     entry.settle(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/spatial",
-  "version": "0.118.4",
+  "version": "0.118.5",
   "description": "Scene and asset manifest contracts plus the shell-to-engine spatial protocol for Adea workspaces: scene mount manifests, spawn URL helpers, and scene telemetry schemas. Pure types — no rendering, no binaries.",
   "keywords": [
     "assets",

package/src/sim-bridge/messages.ts

@@ -57,7 +57,12 @@ export type SimFrameRequestMessage =
     }>
   | Readonly<{
       type: 'frame.character.save'
-      payload: Readonly<{ requestId: string; character: string }>
+      /**
+       * `revision` orders saves from one frame: it increases with every save request the frame
+       * makes, so the host can refuse one older than a save it already committed. Optional so
+       * frames built before it keep working.
+       */
+      payload: Readonly<{ requestId: string; character: string; revision?: number }>
     }>
 
 /** The scene channel's acknowledgements, refusals and measurements (see `scene.ts`). */
@@ -204,11 +209,26 @@ export function parseFrameMessage(
         : fail('invalid_payload')
     }
     case 'frame.character.save': {
-      const body = strictRecord(payload, ['requestId', 'character'])
+      const body = strictRecord(payload, ['requestId', 'character'], ['revision'])
       const requestId = boundedString(body?.requestId, REQUEST_ID)
       const character = parseSimCharacterValue(body?.character)
+      const revision = body?.revision
+      if (
+        revision !== undefined &&
+        (typeof revision !== 'number' || !Number.isSafeInteger(revision) || revision < 1)
+      )
+        return fail('invalid_payload')
       return requestId && character
-        ? { ok: true, message: { type, payload: { requestId, character } } }
+        ? {
+            ok: true,
+            message: {
+              type,
+              payload:
+                revision === undefined
+                  ? { requestId, character }
+                  : { requestId, character, revision },
+            },
+          }
         : fail('invalid_payload')
     }
     case 'frame.scene.ack':

package/src/sim-bridge/save-client.ts

@@ -11,7 +11,8 @@ import type { SimFrameRequestMessage, SimHostMessage } from './messages'
  */
 
 export type CharacterSaveClient = Readonly<{
-  save(character: string): Promise<boolean>
+  /** `revision` (a positive integer that increases per save) lets the host refuse an older save. */
+  save(character: string, options?: Readonly<{ revision?: number }>): Promise<boolean>
   /** Feed every parsed host message in; unrelated ones are ignored. */
   receive(message: SimHostMessage): void
   /** Fails any open save. Call when the frame is torn down. */
@@ -48,8 +49,14 @@ export function createCharacterSaveClient(
   }
 
   return {
-    save(character) {
-      if (disposed || open || parseSimCharacterValue(character) === null)
+    save(character, saveOptions) {
+      const revision = saveOptions?.revision
+      if (
+        disposed ||
+        open ||
+        parseSimCharacterValue(character) === null ||
+        (revision !== undefined && (!Number.isSafeInteger(revision) || revision < 1))
+      )
         return Promise.resolve(false)
       const requestId = mint()
       return new Promise<boolean>((resolve) => {
@@ -65,7 +72,13 @@ export function createCharacterSaveClient(
         }
         open = entry
         try {
-          options.post({ type: 'frame.character.save', payload: { requestId, character } })
+          options.post({
+            type: 'frame.character.save',
+            payload:
+              revision === undefined
+                ? { requestId, character }
+                : { requestId, character, revision },
+          })
         } catch {
           entry.settle(false)
         }