@routevn/creator-model 1.1.11 → 1.1.12

package/README.md

@@ -5,6 +5,9 @@ Shared RouteVN domain model package.
 Repo rules and contribution expectations are in
 [GUIDELINES.md](./GUIDELINES.md).
 
+Schema compatibility maintenance rules are in
+[docs/schema-compatibility.md](./docs/schema-compatibility.md).
+
 This repo is intended to be the single source of truth for:
 
 - state validation
@@ -79,6 +82,9 @@ Design rules:
 - pure functions whenever possible
 - command payload shape is validated separately from state-aware preconditions
 - `SCHEMA_VERSION` is the source of truth for persisted command schema versioning
+- `SCHEMA_VERSION` must stay aligned with the minor version from `package.json`
+- patch releases must not change persisted schema compatibility
+- `bun run test:compat` is the required compatibility gate for model changes
 - `processCommand()` is the authoritative state transition
 - model state should contain project-owned runtime data only
 - app-owned metadata like project id, name, and description should stay out of
@@ -190,6 +196,20 @@ YAML Puty specs use [tests/support/putyApi.js](./tests/support/putyApi.js) as a
 small adapter so the declarative `throws:` assertions can stay concise while the
 real public API returns `{ valid: ... }` result objects.
 
+Compatibility fixtures live under `tests/compat/schema-<n>/`.
+
+- `payloads/` fixtures are frozen command payload shapes for that schema version
+- `states/` fixtures are frozen persisted-state snapshots for that schema version
+- `streams/` fixtures are frozen command sequences for that schema version
+- current tests must continue to validate/replay every archived compatibility
+  fixture from the same or older schema versions
+- current schema payload coverage must include `minimal.yaml` and `full.yaml` for
+  every public command type
+
+See also:
+
+- [docs/schema-compatibility.md](./docs/schema-compatibility.md)
+
 ## Current Scope
 
 Currently implemented command types:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routevn/creator-model",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -27,10 +27,13 @@
   },
   "scripts": {
     "test": "bunx vitest run",
+    "test:compat": "bunx vitest run tests/compatibility-fixtures.test.js",
     "test:watch": "bunx vitest",
-    "bench": "bun scripts/benchmark-process-command.js"
+    "bench": "bun scripts/benchmark-process-command.js",
+    "generate:compat-fixtures": "node scripts/generate-compat-fixtures.js"
   },
   "devDependencies": {
+    "js-yaml": "^4.1.0",
     "puty": "0.1.2",
     "vitest": "^3.2.1"
   }

package/src/model.js

@@ -145,7 +145,7 @@ const LAYOUT_ELEMENT_BASE_TYPES = [
   "container-ref-confirm-dialog-ok",
   "container-ref-confirm-dialog-cancel",
 ];
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 1;
 const LAYOUT_CONTAINER_ELEMENT_TYPES = [
   "folder",
   "container",
@@ -1357,30 +1357,21 @@ const validateMaskDefinition = ({ mask, path, errorFactory }) => {
         }
       }
 
-      if (
-        item.texture !== undefined &&
-        !isNonEmptyString(item.texture)
-      ) {
+      if (item.texture !== undefined && !isNonEmptyString(item.texture)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath}.texture must be a non-empty string when provided`,
         );
       }
 
-      if (
-        item.imageId !== undefined &&
-        !isNonEmptyString(item.imageId)
-      ) {
+      if (item.imageId !== undefined && !isNonEmptyString(item.imageId)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath}.imageId must be a non-empty string when provided`,
         );
       }
 
-      if (
-        !isNonEmptyString(item.texture) &&
-        !isNonEmptyString(item.imageId)
-      ) {
+      if (!isNonEmptyString(item.texture) && !isNonEmptyString(item.imageId)) {
         return invalidFromErrorFactory(
           errorFactory,
           `${itemPath} must define texture or imageId`,
@@ -1987,7 +1978,15 @@ const validateVariableItems = ({ items, path, errorFactory }) => {
         allowedKeys:
           variableType === "folder"
             ? ["id", "type", "name", "description"]
-            : ["id", "type", "name", "description", "scope", "default", "value"],
+            : [
+                "id",
+                "type",
+                "name",
+                "description",
+                "scope",
+                "default",
+                "value",
+              ],
         path: itemPath,
         errorFactory,
       });
@@ -4502,7 +4501,9 @@ export const assertInvariants = ({ state }) => {
     }
   }
 
-  for (const [animationId, animation] of Object.entries(state.animations.items)) {
+  for (const [animationId, animation] of Object.entries(
+    state.animations.items,
+  )) {
     if (animation.type !== "animation") {
       continue;
     }