@crvouga/atlas 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog: @crvouga/atlas
 
+## 0.9.0 (2026-10-15)
+
+### Features
+
+- accept transition metadata ([6668573](https://github.com/crvouga/atlas/commit/666857395a702b7fc3319d7a31e90caaa060e8e9))
+
 ## 0.8.0 (2026-10-15)
 
 ### Features

package/dist/core/src/lint.js

@@ -2,6 +2,7 @@ import { ChartGraph } from './graph.js';
 import { composeCharts } from './spec/compose.js';
 import { invokesOf, walkStates } from './spec/types.js';
 const STATE_KEYS = new Set(['id', 'initial', 'type', 'meta', 'states', 'on', 'invoke', 'description']);
+const TRANSITION_KEYS = new Set(['target', 'meta']);
 const INVOKE_KEYS = new Set(['src', 'id', 'onDone']);
 const REQUIRED_META = ['description'];
 const FORBIDDEN = ['entry', 'exit', 'actions', 'assign', 'after', 'always', 'context', 'guard', 'cond', 'delay', 'output', 'onError'];
@@ -26,7 +27,7 @@ function checkShape(node, name, requiredMeta, out) {
             continue;
         }
         for (const key of Object.keys(t)) {
-            if (key !== 'target')
+            if (!TRANSITION_KEYS.has(key))
                 out.push({ rule: 'pure', message: `${name} --${event}-->: "${key}" is not allowed (no guards, no actions)` });
         }
     }
@@ -47,7 +48,10 @@ function sanitized(bundle) {
             if (STATE_KEYS.has(key))
                 out[key] = value;
         if (node.on) {
-            out['on'] = Object.fromEntries(Object.entries(node.on).map(([event, t]) => [event, typeof t === 'string' ? t : { target: t.target }]));
+            out['on'] = Object.fromEntries(Object.entries(node.on).map(([event, t]) => [
+                event,
+                typeof t === 'string' ? t : { target: t.target, ...('meta' in t ? { meta: t.meta } : {}) }
+            ]));
         }
         if (node.states)
             out['states'] = Object.fromEntries(Object.entries(node.states).map(([k, v]) => [k, clean(v)]));

package/dist/core/src/spec/types.d.ts

@@ -18,7 +18,10 @@
  */
 /** The object form of a transition. `target` is a state name, optionally prefixed with `#` (a reference by name across the composed product). */
 export type TransitionConfig = {
+    /** The destination state, optionally prefixed with `#`. */
     target: string;
+    /** Declarative provenance or business metadata; ignored while executing the chart. */
+    meta?: Record<string, unknown>;
 };
 /** An `invoke` that runs another chart inside a state. It is never executed: `composeCharts` inlines the child chart statically. */
 export type InvokeConfig = {
@@ -84,7 +87,7 @@ export type StateConfig = {
     type?: 'parallel' | 'final';
     meta?: StateMeta;
     states?: Record<string, StateConfig>;
-    /** Event name (exact business wording) to its transition: a target string or `{ target }`. */
+    /** Event name (exact business wording) to its transition: a target string or `{ target, meta? }`. */
     on?: Record<string, TransitionConfig | string>;
     /** Child chart(s) that run inside this state. */
     invoke?: InvokeConfig | InvokeConfig[];

package/dist/schema/src/spec.d.ts

@@ -144,9 +144,10 @@ export declare const StateMetaSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** A parsed `StateMetaSchema` value. */
 export type StateMeta = z.infer<typeof StateMetaSchema>;
-/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`. */
 export declare const TransitionTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     target: z.ZodString;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>]>;
 /** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export declare const STATE_TYPES: readonly ["atomic", "compound", "parallel", "final"];

package/dist/schema/src/spec.js

@@ -73,10 +73,13 @@ export const StateMetaShape = {
 };
 /** `StateMetaShape` with every field optional: the `meta` of a state or of a whole chart. */
 export const StateMetaSchema = z.object(StateMetaShape).partial();
-/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`. */
+/** The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`. */
 export const TransitionTargetSchema = z.union([
     z.string().min(1),
-    z.object({ target: z.string().min(1) })
+    z.object({
+        target: z.string().min(1),
+        meta: z.record(z.string(), z.unknown()).optional()
+    })
 ]);
 /** Kinds of state in the composed map: `atomic`, `compound`, `parallel`, `final`. */
 export const STATE_TYPES = ['atomic', 'compound', 'parallel', 'final'];

package/docs/reference/core.md

@@ -2241,7 +2241,12 @@ See docs/statecharts.md
 #### `TransitionConfig`
 
 ```ts
-export type TransitionConfig = { target: string };
+export type TransitionConfig = {
+  /** The destination state, optionally prefixed with `#`. */
+  target: string;
+  /** Declarative provenance or business metadata; ignored while executing the chart. */
+  meta?: Record<string, unknown>;
+};
 ```
 
 The object form of a transition. `target` is a state name, optionally prefixed with `#` (a reference by name across the composed product).
@@ -2308,7 +2313,7 @@ export type StateConfig = {
   type?: 'parallel' | 'final';
   meta?: StateMeta;
   states?: Record<string, StateConfig>;
-  /** Event name (exact business wording) to its transition: a target string or `{ target }`. */
+  /** Event name (exact business wording) to its transition: a target string or `{ target, meta? }`. */
   on?: Record<string, TransitionConfig | string>;
   /** Child chart(s) that run inside this state. */
   invoke?: InvokeConfig | InvokeConfig[];

package/docs/reference/schema.md

@@ -1613,7 +1613,7 @@ A parsed `StateMetaSchema` value.
 export const TransitionTargetSchema = …
 ```
 
-The target of an event transition: a state name (or `#id`) written as a string, or an object with `target`.
+The target of an event transition: a state name (or `#id`) written as a string, or an object with `target` and optional declarative `meta`.
 
 #### `STATE_TYPES`
 

package/docs/statecharts.md

@@ -119,7 +119,8 @@ Atlas walks charts without running any code, so it executes only the parts of a
 are pure structure:
 
 - states, nesting (`initial`), `parallel` regions and `final` states;
-- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`);
+- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`), with
+  optional declarative metadata (`{ target: '#Open', meta: { source: ['specs/door.feature'] } }`);
 - `invoke` that names another chart (`src`, `id`, `onDone`), composed statically;
 - `meta`.
 

package/llms-full.txt

@@ -2727,7 +2727,8 @@ Atlas walks charts without running any code, so it executes only the parts of a
 are pure structure:
 
 - states, nesting (`initial`), `parallel` regions and `final` states;
-- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`);
+- event transitions, written as a target (`Opens: Open` or `{ target: '#Open' }`), with
+  optional declarative metadata (`{ target: '#Open', meta: { source: ['specs/door.feature'] } }`);
 - `invoke` that names another chart (`src`, `id`, `onDone`), composed statically;
 - `meta`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/atlas",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Atlas: specs of any kind, reported as layered evidence. Publish checks from any runner (JUnit, CTRF, a script), combine them across nodes, branches, environments and backends, gate CI on the result, and run statecharts against the real app.",
   "license": "MIT",
   "type": "module",

package/packages/schema/schemas/state-node.schema.json

@@ -225,6 +225,13 @@
               "target": {
                 "type": "string",
                 "minLength": 1
+              },
+              "meta": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
               }
             },
             "required": [