@astrale-os/kernel-dsl 0.2.0-beta.17 → 0.2.0-beta.19

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.0-beta.19](https://github.com/astrale-os/kernel/compare/kernel-dsl-v0.2.0-beta.18...kernel-dsl-v0.2.0-beta.19) (2026-08-29)
+
+
+### Bug Fixes
+
+* **system:** clear specification diagnostic debt ([#539](https://github.com/astrale-os/kernel/issues/539)) ([2e88cf5](https://github.com/astrale-os/kernel/commit/2e88cf5a84c7026122f680249bbea20202b92ac6))
+
+## [0.2.0-beta.18](https://github.com/astrale-os/kernel/compare/kernel-dsl-v0.2.0-beta.17...kernel-dsl-v0.2.0-beta.18) (2026-08-29)
+
+
+### Features
+
+* **dsl:** make StateProperty topology portable ([#534](https://github.com/astrale-os/kernel/issues/534)) ([f71cf87](https://github.com/astrale-os/kernel/commit/f71cf879e68475ffd002cafe6688be0649eb9c49))
+
 ## [0.2.0-beta.17](https://github.com/astrale-os/kernel/compare/kernel-dsl-v0.2.0-beta.16...kernel-dsl-v0.2.0-beta.17) (2026-08-29)
 
 

package/dist/v1/builder/class/authoring.d.ts

@@ -6,12 +6,13 @@ import type { ResolvedMethod } from '../../language/callable/resolved.js';
 import type { MediaType } from '../../language/class/model/data.js';
 import type { EdgeCount } from '../../language/class/model/edge.js';
 import type { ResolvedClass, ResolvedProperty } from '../../language/class/resolved.js';
+import type { StateTopology, StateTopologyOf } from '../../language/state/topology.js';
 import type { Method, ProjectionOfCallable } from '../callable/authoring.js';
 import type { Policy } from '../policy/authoring.js';
 import type { Lazy } from '../schema/lazy.js';
 import type { ClassProjectionOfResolved } from '../schema/projection.js';
 import type { TypedValueSchema } from '../value/schema.js';
-import type { AutoProperty, Property, PropertyOptions, ValueSchemaInput } from './property.js';
+import type { AutoProperty, Property, PropertyOptions, PropertyStateMachineOf, ValueSchemaInput } from './property.js';
 import type { PropertyRecordInput } from './property.js';
 import { type AUTHORING } from '../schema/handle.js';
 declare const CLASS_TYPE: unique symbol;
@@ -88,26 +89,27 @@ export type ClassInput = ({
     readonly abstract: boolean;
 } & Omit<UndirectedEdgeInput, 'orientation'>);
 export type Class = NodeClass | EdgeClass;
-export interface AuthoredPropertyProjection<out Input = unknown, out Output = unknown, out Required extends boolean = boolean, out Name extends string = string, out Owner = 'self'> {
+export interface AuthoredPropertyProjection<out Input = unknown, out Output = unknown, out Required extends boolean = boolean, out Name extends string = string, out Owner = 'self', out State extends StateTopology | undefined = StateTopology | undefined> {
     readonly input: Input;
     readonly output: Output;
     readonly required: Required;
     readonly name: Name;
     readonly owner: Owner;
+    readonly state?: State;
 }
 export interface AuthoredMethodProjection<out Value extends Method = Method, out Name extends string = string, out Owner = 'self'> {
     readonly value: Value;
     readonly name: Name;
     readonly owner: Owner;
 }
-type PropertySchemaOf<Field> = Field extends AutoProperty<infer Value> ? PropertySchemaOf<Value> : Field extends Property<infer Schema, PropertyOptions> ? Schema : Field;
-type PropertyOptionsOf<Field> = Field extends AutoProperty<infer Value> ? PropertyOptionsOf<Value> : Field extends Property<ValueSchemaInput, infer Options> ? Options : Record<never, never>;
+type PropertySchemaOf<Field> = Field extends AutoProperty<infer Value> ? PropertySchemaOf<Value> : Field extends Property<infer Schema, PropertyOptions, unknown> ? Schema : Field;
+type PropertyOptionsOf<Field> = Field extends AutoProperty<infer Value> ? PropertyOptionsOf<Value> : Field extends Property<ValueSchemaInput, infer Options, unknown> ? Options : Record<never, never>;
 type ValueInputOf<Schema> = Schema extends TypedValueSchema<infer Value> ? Value : Schema extends z.ZodType ? z.input<Schema> : PortableValue;
 type ValueOutputOf<Schema> = Schema extends TypedValueSchema<infer Value> ? Value : Schema extends z.ZodType ? z.output<Schema> : PortableValue;
 type PropertyRequiredOf<Field> = PropertyOptionsOf<Field> extends {
     readonly required: infer Required extends boolean;
 } ? Required : undefined extends ValueInputOf<PropertySchemaOf<Field>> ? false : true;
-type PropertyProjectionOf<Name extends string, Field> = AuthoredPropertyProjection<Field extends AutoProperty ? never : ValueInputOf<PropertySchemaOf<Field>>, ValueOutputOf<PropertySchemaOf<Field>>, PropertyRequiredOf<Field>, Name>;
+type PropertyProjectionOf<Name extends string, Field> = AuthoredPropertyProjection<Field extends AutoProperty ? never : ValueInputOf<PropertySchemaOf<Field>>, ValueOutputOf<PropertySchemaOf<Field>>, PropertyRequiredOf<Field>, Name, 'self', Field extends Property ? StateTopologyOf<PropertyStateMachineOf<Field>> : undefined>;
 type PropertyProjectionsOf<Input> = Input extends Readonly<Record<string, unknown>> ? {
     readonly [Name in keyof Input]: PropertyProjectionOf<Extract<Name, string>, Input[Name]>;
 } : Readonly<Record<never, never>>;
@@ -124,7 +126,7 @@ type ParentPropertyProjectionsOf<Input> = Input extends {
 type EffectivePropertyProjectionsOf<Input> = PropertyProjectionEntriesOf<'properties' extends keyof Input ? Input extends {
     readonly properties?: infer Value;
 } ? NonNullable<Value> : never : never> | ParentPropertyProjectionsOf<Input>;
-type BindPropertyOwners<Entries, Owner> = Entries extends AuthoredPropertyProjection<infer Input, infer Output, infer Required, infer Name, infer ExistingOwner> ? AuthoredPropertyProjection<Input, Output, Required, Name, ExistingOwner extends 'self' ? Owner : ExistingOwner> : Entries;
+type BindPropertyOwners<Entries, Owner> = Entries extends AuthoredPropertyProjection<infer Input, infer Output, infer Required, infer Name, infer ExistingOwner, infer State> ? AuthoredPropertyProjection<Input, Output, Required, Name, ExistingOwner extends 'self' ? Owner : ExistingOwner, State> : Entries;
 type MethodFieldsOf<Input> = 'methods' extends keyof Input ? Input extends {
     readonly methods?: infer Methods extends Readonly<Record<string, Method>>;
 } ? NonNullable<Methods> : Readonly<Record<never, never>> : Readonly<Record<never, never>>;
@@ -208,7 +210,7 @@ type UndirectedEdgeClassIdentity<Config> = Config extends {
     readonly endpoints: Endpoints;
     readonly constraints: Constraints;
 } : never;
-type OwnerErasedPropertyProjection<Entry> = Entry extends AuthoredPropertyProjection<infer Input, infer Output, infer Required, infer Name, unknown> ? AuthoredPropertyProjection<Input, Output, Required, Name, unknown> : Entry extends ResolvedProperty<infer Value, infer Required> & {
+type OwnerErasedPropertyProjection<Entry> = Entry extends AuthoredPropertyProjection<infer Input, infer Output, infer Required, infer Name, unknown, infer State> ? AuthoredPropertyProjection<Input, Output, Required, Name, unknown, State> : Entry extends ResolvedProperty<infer Value, infer Required, infer State> & {
     readonly name: infer Name;
     readonly key: infer Key;
 } ? {
@@ -216,6 +218,7 @@ type OwnerErasedPropertyProjection<Entry> = Entry extends AuthoredPropertyProjec
     readonly required: Required;
     readonly name: Name;
     readonly key: Key;
+    readonly state?: State;
 } : never;
 type OwnerErasedMethodProjection<Entry> = Entry extends AuthoredMethodProjection<infer Value, infer Name, unknown> ? AuthoredMethodProjection<Value, Name, unknown> : Entry extends ResolvedMethod<infer Input, infer Output, infer Static, infer Inheritance, infer Auth, infer _Policy, infer Key> & {
     readonly name: infer Name;
@@ -355,11 +358,18 @@ export declare const edgeClass: Readonly<{
     directed<const Input extends Omit<DirectedEdgeInput, 'orientation'>>(input: Input & {
         readonly source: ExactEndpointInput<Input['source'], DirectedSourceInput>;
         readonly target: ExactEndpointInput<Input['target'], DirectedTargetInput>;
-    }): DirectedEdgeClass<CompactDirectedInput<Input>>;
+    } & WithoutStateProperties<Input>): DirectedEdgeClass<CompactDirectedInput<Input>>;
     undirected<const Input extends Omit<UndirectedEdgeInput, 'orientation'>>(input: Input & {
         readonly endpoints: readonly [ExactEndpointInput<Input['endpoints'][0], IncidentEndpointInput>, ExactEndpointInput<Input['endpoints'][1], IncidentEndpointInput>];
-    }): UndirectedEdgeClass<CompactUndirectedInput<Input>>;
+    } & WithoutStateProperties<Input>): UndirectedEdgeClass<CompactUndirectedInput<Input>>;
 }>;
+type WithoutStateProperties<Input> = Input extends {
+    readonly properties?: infer Properties extends Readonly<Record<string, unknown>>;
+} ? {
+    readonly properties?: {
+        readonly [Name in keyof Properties]: Properties[Name] extends Property ? [PropertyStateMachineOf<Properties[Name]>] extends [never] ? Properties[Name] : never : Properties[Name];
+    };
+} : unknown;
 export type ProjectionOfClass<Value extends Class> = Value extends NodeClass<infer Config> ? Config : Value extends DirectedEdgeClass<infer Input> ? Input : Value extends UndirectedEdgeClass<infer Input> ? Input : never;
 export declare function classConfiguration(value: NodeClass): NodeClassInput;
 export declare function classConfiguration(value: DirectedEdgeClass): Omit<DirectedEdgeInput, 'orientation'>;

package/dist/v1/builder/class/property.d.ts

@@ -1,5 +1,6 @@
 import type { z } from 'zod';
 import type { AutoEvent, AutoSet } from '../../language/class/model/property.js';
+import type { StateMachine } from '../../language/state/index.js';
 import type { JsonSchema } from '../../language/value/model/schema.js';
 import type { AUTHORING } from '../schema/handle.js';
 declare const PROPERTY_INPUT: unique symbol;
@@ -13,15 +14,17 @@ export interface AutoOptions {
     readonly on: AutoEvent | readonly AutoEvent[];
     readonly set: AutoSet;
 }
-export interface Property<out Schema extends ValueSchemaInput = ValueSchemaInput, out Options extends PropertyOptions = PropertyOptions> {
+export interface Property<out Schema extends ValueSchemaInput = ValueSchemaInput, out Options extends PropertyOptions = PropertyOptions, out Machine = unknown> {
     readonly [AUTHORING]: 'property';
     readonly [PROPERTY_INPUT]: {
         readonly schema: Schema;
         readonly options: Options;
+        readonly machine?: Machine;
     };
 }
-export type PropertySchemaOf<Value extends Property> = Value extends Property<infer Schema, PropertyOptions> ? Schema : never;
-export type PropertyOptionsOf<Value extends Property> = Value extends Property<ValueSchemaInput, infer Options> ? Options : never;
+export type PropertySchemaOf<Value extends Property> = Value extends Property<infer Schema, PropertyOptions, unknown> ? Schema : never;
+export type PropertyOptionsOf<Value extends Property> = Value extends Property<ValueSchemaInput, infer Options, unknown> ? Options : never;
+export type PropertyStateMachineOf<Value extends Property> = Value extends Property<ValueSchemaInput, PropertyOptions, infer Machine> ? Machine : never;
 export interface AutoProperty<out PropertyValue extends Property = Property> {
     readonly [AUTHORING]: 'auto';
     readonly [AUTO_INPUT]: {
@@ -32,9 +35,10 @@ export interface AutoProperty<out PropertyValue extends Property = Property> {
         };
     };
 }
-export type PropertyAuthoringInput<Value extends Property> = Value extends Property<infer Schema, infer Options> ? {
+export type PropertyAuthoringInput<Value extends Property> = Value extends Property<infer Schema, infer Options, infer Machine> ? {
     readonly schema: Schema;
     readonly options: Options;
+    readonly machine?: Machine;
 } : never;
 export declare function propertyAuthoringInput<const Value extends Property>(value: Value): PropertyAuthoringInput<Value>;
 export declare function autoPropertyAuthoringInput<const Value extends AutoProperty>(value: Value): Value extends AutoProperty<infer Property> ? {
@@ -46,6 +50,9 @@ export declare function autoPropertyAuthoringInput<const Value extends AutoPrope
 } : never;
 export type PropertyFieldInput = ValueSchemaInput | Property | AutoProperty;
 export type PropertyRecordInput = Readonly<Record<string, PropertyFieldInput>>;
-export declare function property<const Schema extends ValueSchemaInput, const Options extends PropertyOptions = Record<never, never>>(schema: Schema, options?: Options): Property<Schema, Options>;
-export declare function auto<const PropertyValue extends Property>(property: PropertyValue, options: AutoOptions): AutoProperty<PropertyValue>;
+export declare function property<const Schema extends ValueSchemaInput, const Options extends PropertyOptions = Record<never, never>>(schema: Schema, options?: Options): Property<Schema, Options, never>;
+export declare function stateProperty<const Machine extends StateMachine, const Options extends Omit<PropertyOptions, 'required'> = Record<never, never>>(machine: Machine, options?: Options & Record<Exclude<keyof Options, 'description'>, never>): Property<Machine['stateSchema'], Readonly<Options & {
+    readonly required: true;
+}>, Machine>;
+export declare function auto<const PropertyValue extends Property>(property: [PropertyStateMachineOf<PropertyValue>] extends [never] ? PropertyValue : never, options: AutoOptions): AutoProperty<PropertyValue>;
 export {};

package/dist/v1/builder/class/property.js

@@ -18,6 +18,17 @@ export function property(schema, options) {
         },
     });
 }
+export function stateProperty(machine, options) {
+    const admitted = options ?? {};
+    assertKnownKeys(admitted, ['description']);
+    return authoringValue('property', {
+        [PROPERTY_INPUT]: {
+            schema: machine.stateSchema,
+            options: { ...admitted, required: true },
+            machine,
+        },
+    });
+}
 export function auto(property, options) {
     if (isAuthoringValue(property, 'auto')) {
         fail('BUILDER_AUTO_NESTED', '', 'auto(...) cannot wrap another auto Property.');

package/dist/v1/builder/index.d.ts

@@ -4,7 +4,7 @@ export { defineClass, edgeClass, nodeClass } from './class/authoring.js';
 export { fullMatch } from './value/full-match.js';
 export { path } from './value/path.js';
 export { policy } from './policy/authoring.js';
-export { auto, property } from './class/property.js';
+export { auto, property, stateProperty } from './class/property.js';
 export { defineSchema } from './schema/define.js';
 export type { DefinedSchema } from './schema/define.js';
 export type { ResolvedDomainOfInput } from './schema/projection.js';

package/dist/v1/builder/index.js

@@ -4,7 +4,7 @@ export { defineClass, edgeClass, nodeClass } from './class/authoring.js';
 export { fullMatch } from './value/full-match.js';
 export { path } from './value/path.js';
 export { policy } from './policy/authoring.js';
-export { auto, property } from './class/property.js';
+export { auto, property, stateProperty } from './class/property.js';
 export { defineSchema } from './schema/define.js';
 export { valueSchema } from './value/schema.js';
 export { view } from './view/authoring.js';

package/dist/v1/builder/lowering/value/compile.js

@@ -40,6 +40,14 @@ export class BuilderValueSchemas {
                 ...(authoredInput?.options.description === undefined
                     ? {}
                     : { description: authoredInput.options.description }),
+                ...(authoredInput?.machine === undefined
+                    ? {}
+                    : {
+                        state: {
+                            initial: authoredInput.machine.initial,
+                            transitions: authoredInput.machine.transitions,
+                        },
+                    }),
             };
         }
         return compiled;

package/dist/v1/builder/schema/projection.d.ts

@@ -1,15 +1,17 @@
 import type { Revision } from '../../addressing/index.js';
 import type * as domain from '../../domain/model/domain.js';
 import type * as language from '../../language/index.js';
+import type { StateTopology } from '../../language/state/index.js';
 import type { DomainOfSchema, DomainSchema } from '../../schema/model/schema.js';
 import type { CallableProjection, Function, Method } from '../callable/authoring.js';
 import type { AuthoredPropertyProjection, AuthoredMethodProjection, Class, ClassIdentityProjection, ClassIdentityProjectionOf, ClassOwnerProjection, ClassOwnerProjectionOf, ClassReferenceProjection, ClassReferenceProjectionOf, DirectedEdgeClass, NodeClass, ProjectionOfClass, UndirectedEdgeClass } from '../class/authoring.js';
 import type { DomainSchemaInput } from './input.js';
-export interface PropertyProjection<Value = unknown, Required extends boolean = boolean, Name extends string = string, Key extends language.PropertyKey = language.PropertyKey> {
+export interface PropertyProjection<Value = unknown, Required extends boolean = boolean, Name extends string = string, Key extends language.PropertyKey = language.PropertyKey, State extends StateTopology | undefined = StateTopology | undefined> {
     readonly value: Value;
     readonly required: Required;
     readonly name: Name;
     readonly key: Key;
+    readonly state?: State;
 }
 export interface MethodProjection<Input = unknown, Output = unknown, Static extends boolean = boolean, Inheritance extends language.MethodInheritance = language.MethodInheritance, Auth extends language.FunctionAuth = language.FunctionAuth, Name extends string = string, Key extends language.MethodKey = language.MethodKey> {
     readonly input: Input;
@@ -256,10 +258,10 @@ type CallableAuthOf<Value extends Method | Function> = CallableConfig<Value>['au
 type MethodProjectionOfEntry<Origin extends string, OwnerName extends string, Entry> = Entry extends language.ResolvedMethod ? MethodProjectionOfResolved<Entry> : Entry extends AuthoredMethodEntry<unknown, infer Name, infer Value> ? MethodProjection<CallableInputValue<Value>, CallableOutputValue<Value>, CallableStaticOf<Value>, CallableInheritanceOf<Value>, CallableAuthOf<Value>, Name, language.MethodKey<Origin, OwnerName, Name>> : never;
 type MethodProjectionOfEntries<Origin extends string, OwnerName extends string, Entries> = Entries extends unknown ? MethodProjectionOfEntry<Origin, OwnerName, Entries> : never;
 type MethodCollectionOperation = 'byKey' | 'get';
-type PropertyProjectionOfResolved<Value> = Value extends language.ResolvedProperty<infer PropertyValue, infer Required> & {
+type PropertyProjectionOfResolved<Value> = Value extends language.ResolvedProperty<infer PropertyValue, infer Required, infer State> & {
     readonly name: infer Name extends string;
     readonly key: infer Key extends language.PropertyKey;
-} ? PropertyProjection<PropertyValue, Required, Name, Key> : never;
+} ? PropertyProjection<PropertyValue, Required, Name, Key, State> : never;
 type MethodProjectionOfResolved<Value> = Value extends language.ResolvedMethod<infer Input, infer Output, infer Static, infer Inheritance, infer Auth, infer _Policy, infer Key> & {
     readonly name: infer Name extends string;
 } ? MethodProjection<Input, Output, Static, Inheritance, Auth, Name, Key> : never;
@@ -288,12 +290,12 @@ type ShallowClassProjectionTupleOfResolved<Parents extends readonly unknown[]> =
 type ExactClass<Value> = Value extends {
     readonly key: infer Key extends language.DefinitionKey<string, 'class'>;
 } ? Key extends `${infer Origin}:class.${infer Name}` ? string extends Origin ? never : string extends Name ? never : Value : never : never;
-type OwnPropertyProjectionsOf<Origin extends string, Name extends string, Value> = OwnPropertyEntries<Value> extends infer Entry ? Entry extends AuthoredPropertyEntry<unknown, infer PropertyName, infer Field> ? Field extends AuthoredPropertyProjection<unknown, infer Output, infer Required> ? PropertyProjection<Output, Required, PropertyName, language.PropertyKey<Origin, Name, PropertyName>> : never : never : never;
+type OwnPropertyProjectionsOf<Origin extends string, Name extends string, Value> = OwnPropertyEntries<Value> extends infer Entry ? Entry extends AuthoredPropertyEntry<unknown, infer PropertyName, infer Field> ? Field extends AuthoredPropertyProjection<unknown, infer Output, infer Required, string, unknown, infer State> ? PropertyProjection<Output, Required, PropertyName, language.PropertyKey<Origin, Name, PropertyName>, State> : never : never : never;
 type EffectivePropertyEntriesOfClass<Value> = ClassInputOf<Value> extends {
     readonly effectiveProperties: infer Properties;
 } ? Properties : never;
 type OwnerNameOf<Root extends DomainSchemaInput, CurrentName extends string, Owner> = Owner extends 'self' ? CurrentName : Owner extends ClassOwnerProjection ? Extract<LocalNameOfOwner<Root, Owner>, string> : Owner extends ClassIdentityProjection ? Extract<LocalNameOfIdentity<Root, Owner>, string> : never;
-type EffectivePropertyProjectionOfEntry<Origin extends string, CurrentName extends string, Root extends DomainSchemaInput, Entry> = Entry extends language.ResolvedProperty ? PropertyProjectionOfResolved<Entry> : Entry extends AuthoredPropertyProjection<unknown, infer Output, infer Required, infer PropertyName, infer Owner> ? OwnerNameOf<Root, CurrentName, Owner> extends infer OwnerName extends string ? PropertyProjection<Output, Required, PropertyName, language.PropertyKey<Origin, OwnerName, PropertyName>> : never : never;
+type EffectivePropertyProjectionOfEntry<Origin extends string, CurrentName extends string, Root extends DomainSchemaInput, Entry> = Entry extends language.ResolvedProperty ? PropertyProjectionOfResolved<Entry> : Entry extends AuthoredPropertyProjection<unknown, infer Output, infer Required, infer PropertyName, infer Owner, infer State> ? OwnerNameOf<Root, CurrentName, Owner> extends infer OwnerName extends string ? PropertyProjection<Output, Required, PropertyName, language.PropertyKey<Origin, OwnerName, PropertyName>, State> : never : never;
 type EffectivePropertyProjectionsOf<Origin extends string, Name extends string, Value, Root extends DomainSchemaInput> = EffectivePropertyEntriesOfClass<Value> extends infer Entry ? Entry extends unknown ? EffectivePropertyProjectionOfEntry<Origin, Name, Root, Entry> : never : never;
 type OwnInstanceMethodProjectionsOf<Origin extends string, Name extends string, Value> = MethodProjectionOfEntries<Origin, Name, OwnMethodEntries<Value, false>>;
 type OwnStaticMethodProjectionsOf<Origin extends string, Name extends string, Value> = MethodProjectionOfEntries<Origin, Name, OwnMethodEntries<Value, true>>;
@@ -316,7 +318,7 @@ type ClassProjectionOfAuthoring<Origin extends string, Name extends string, Valu
 type FunctionProjectionOfAuthoring<Origin extends string, Name extends string, Value> = Value extends Function ? FunctionProjection<CallableInputValue<Value>, CallableOutputValue<Value>, CallableAuthOf<Value>, language.FunctionRef<Name> & {
     readonly origin: Origin;
 }, language.DefinitionKey<Origin, 'function', Name>> : never;
-type ResolvedPropertyOfProjection<Value> = Value extends PropertyProjection<infer PropertyValue, infer Required, infer Name, infer Key> ? language.ResolvedProperty<PropertyValue, Required> & {
+type ResolvedPropertyOfProjection<Value> = Value extends PropertyProjection<infer PropertyValue, infer Required, infer Name, infer Key, infer State> ? language.ResolvedProperty<PropertyValue, Required, State> & {
     readonly name: Name;
     readonly key: Key;
 } : never;

package/dist/v1/compiled/admission/accept.js

@@ -4,6 +4,7 @@ import { isDefinitionRef, Key } from '../../addressing/index.js';
 import { DEPENDENCY_ALIAS_PATTERN, DOMAIN_ORIGIN_PATTERN, DOMAIN_REVISION_PATTERN, MEMBER_NAME_PATTERN, } from '../../addressing/patterns.js';
 import { MEDIA_TYPE_PATTERN } from '../../language/class/model/data.js';
 import { PropertyValues } from '../../language/class/property-values.js';
+import { admitStateTopology } from '../../language/state/topology.js';
 import { classifyValueProgramOrdering } from '../../language/value/ordering.js';
 import { invalidCompiled } from '../diagnostic.js';
 import { revisionOfCompiledEntry } from './revision.js';
@@ -158,10 +159,8 @@ function compiledClass(input, values, path) {
     const parents = array(value.extends, 'Class extends', extendsPath).map((parent, index) => definitionRef(parent, 'class', 'Class parent', `${extendsPath}/${index}`));
     unique(parents.map(Key.of), 'Class parents', extendsPath);
     const propertiesPath = `${path}/properties`;
-    const properties = array(value.properties, 'Class properties', propertiesPath);
-    for (const [index, property] of properties.entries())
-        compiledProperty(property, values, `${propertiesPath}/${index}`);
-    unique(properties.map((property, index) => string(object(property, 'Compiled Property', `${propertiesPath}/${index}`).name, 'Property name', `${propertiesPath}/${index}/name`)), 'Class Properties', propertiesPath);
+    const properties = array(value.properties, 'Class properties', propertiesPath).map((property, index) => compiledProperty(property, values, value.kind === 'node', `${propertiesPath}/${index}`));
+    unique(properties.map((property) => property.name), 'Class Properties', propertiesPath);
     if (value.kind === 'node') {
         if (value.data !== undefined)
             dataDefinition(value.data, `${path}/data`);
@@ -177,7 +176,7 @@ function compiledClass(input, values, path) {
         classPolicies(value.policies, `${path}/policies`);
         edgeContract(value, path);
     }
-    return value;
+    return { ...value, properties };
 }
 function compiledFunction(input, values, path) {
     const value = object(input, 'Compiled Function', path);
@@ -185,12 +184,13 @@ function compiledFunction(input, values, path) {
     definitionRef(value.ref, 'function', 'Function ref', `${path}/ref`);
     return value;
 }
-function compiledProperty(input, values, path) {
+function compiledProperty(input, values, node, path) {
     const value = object(input, 'Compiled Property', path);
     exact(value, ['name', 'required', 'value'], 'Compiled Property', path, [
         'auto',
         'description',
         'ordering',
+        'state',
     ]);
     memberName(value.name, 'Property name', `${path}/name`);
     boolean(value.required, 'Property required', `${path}/required`);
@@ -198,9 +198,41 @@ function compiledProperty(input, values, path) {
     if (value.auto !== undefined)
         propertyAuto(value.auto, `${path}/auto`);
     const valueIndex = index(value.value, values.length, 'Property value', `${path}/value`);
+    let state;
+    if (value.state !== undefined) {
+        if (!node)
+            invalid('Property state placement', 'COMPILED_SOURCE_INVALID', `${path}/state`);
+        let topology;
+        try {
+            topology = admitStateTopology(value.state);
+        }
+        catch {
+            invalid('Property state topology', 'COMPILED_SOURCE_INVALID', `${path}/state`);
+        }
+        const program = values[valueIndex];
+        const schema = program.nodes[program.root].schema;
+        const states = Object.keys(topology.transitions);
+        const schemaObject = schema;
+        const schemaMatches = schema !== null &&
+            typeof schema === 'object' &&
+            !Array.isArray(schema) &&
+            Object.keys(schemaObject).length === 2 &&
+            schemaObject.type === 'string' &&
+            Array.isArray(schemaObject.enum) &&
+            schemaObject.enum.length === states.length &&
+            schemaObject.enum.every((state, index) => state === states[index]);
+        if (!value.required || value.auto !== undefined || !schemaMatches) {
+            invalid('Property state contract', 'COMPILED_SOURCE_INVALID', `${path}/state`);
+        }
+        state = topology;
+    }
     if (value.ordering !== classifyValueProgramOrdering(values[valueIndex])) {
         invalid('Property ordering', 'COMPILED_CANONICAL_MISMATCH', `${path}/ordering`);
     }
+    return {
+        ...value,
+        ...(state === undefined ? {} : { state }),
+    };
 }
 function compiledCallable(input, values, method, path) {
     const value = object(input, 'Compiled Callable', path);

package/dist/v1/compiled/compiler/compile.js

@@ -39,6 +39,7 @@ function compileEntry(schema, lookup) {
             required: property.required,
             ...(property.auto === undefined ? {} : { auto: property.auto }),
             ...(property.description === undefined ? {} : { description: property.description }),
+            ...(property.state === undefined ? {} : { state: property.state }),
             ...(ordering === undefined ? {} : { ordering }),
             value: add(property.schema, `${pointer}/properties/${name}/schema`),
         };

package/dist/v1/index.d.ts

@@ -1,5 +1,7 @@
 /** Stable aggregate facade for the V1 language. */
-export { auto, core, defineClass, defineSchema, edgeClass, func, fullMatch, method, nodeClass, output, path, policy, property, valueSchema, view, } from './builder/index.js';
+export { auto, core, defineClass, defineSchema, edgeClass, func, fullMatch, method, nodeClass, output, path, policy, property, stateProperty, valueSchema, view, } from './builder/index.js';
+export { stateMachine } from './language/state/index.js';
+export type { EventOf, StateMachine, StateOf } from './language/state/index.js';
 export { PropertyValues } from './language/index.js';
 export * as metadata from './language/definition/metadata.js';
 export type { AnyResolvedClass, BoundMethodOf, BoundMethodShortcutsOf, CallableResultOf, CallableInputOf, CallableOutputOf, ClassSatisfactionKeysOf, ClassDefinition, CoreDefinition, CoreEdge, FunctionAuth, FunctionDefinition, MethodDefinition, MethodInheritance, MethodOwnerKeyOf, PolicyCheckExpression, PolicyDefinition, PropertyInputOf, PropertyAccessOf, PropertyOutputOf, PropertyShortcutsOf, PropertyValuesOf, ResolvedClass, ResolvedCoreDefinition, ResolvedData, ResolvedFunction, ResolvedMethod, ResolvedMethodCollection, ResolvedPolicy, ResolvedProperty, ResolvedView, MethodAccessOf, SelfMethodsOf, SelfPropertiesOf, SelfStaticMethodsOf, StaticMethodsOf, ViewDefinition, } from './language/index.js';

package/dist/v1/index.js

@@ -1,5 +1,6 @@
 /** Stable aggregate facade for the V1 language. */
-export { auto, core, defineClass, defineSchema, edgeClass, func, fullMatch, method, nodeClass, output, path, policy, property, valueSchema, view, } from './builder/index.js';
+export { auto, core, defineClass, defineSchema, edgeClass, func, fullMatch, method, nodeClass, output, path, policy, property, stateProperty, valueSchema, view, } from './builder/index.js';
+export { stateMachine } from './language/state/index.js';
 export { PropertyValues } from './language/index.js';
 export * as metadata from './language/definition/metadata.js';
 export { acceptDefinitionRef, callableAddress, ClassKey, equalDefinitionRefs, isDefinitionRef, Key, MethodKey, PropertyKey, } from './addressing/index.js';

package/dist/v1/language/class/model/property.d.ts

@@ -9,6 +9,7 @@ export interface PropertyDefinition {
     readonly required: boolean;
     readonly auto?: PropertyAuto;
     readonly description?: string;
+    readonly state?: import('../../state/index.js').StateTopology;
 }
 export type PropertyRecord = Readonly<Record<string, PropertyDefinition>>;
 export interface PropertyFacet {

package/dist/v1/language/class/resolved.d.ts

@@ -1,18 +1,20 @@
 import type { Value as PortableValue } from '@astrale-os/kernel-dsl/value';
 import type { ClassRef, DefinitionKey, Key, PolicyRef, PropertyKey } from '../../addressing/index.js';
 import type { ResolvedMethodCollection } from '../callable/resolved.js';
+import type { StateTopology } from '../state/index.js';
 import type { Diagnostic } from '../validation/diagnostic.js';
 import type { OrderingKind } from '../value/ordering.js';
 import type { ClassDefinition, ClassKind } from './model/class.js';
 import type { DataDefinition } from './model/data.js';
 import type { PropertyDefinition } from './model/property.js';
 import type { PropertyValues } from './property-values.js';
-export interface ResolvedProperty<out Value = PortableValue, out Required extends boolean = boolean> {
+export interface ResolvedProperty<out Value = PortableValue, out Required extends boolean = boolean, out State extends StateTopology | undefined = StateTopology | undefined> {
     readonly owner: AnyResolvedClass;
     readonly name: string;
     readonly key: PropertyKey;
-    readonly definition: PropertyDefinition & {
+    readonly definition: Omit<PropertyDefinition, 'required' | 'state'> & {
         readonly required: Required;
+        readonly state?: State;
     };
     /** The one portable scalar ordering domain, when the Property is orderable. */
     readonly ordering?: OrderingKind;

package/dist/v1/language/index.d.ts

@@ -2,6 +2,8 @@ export type { ClassRef, CoreRef, DefinitionBase, DefinitionKey, DefinitionRef, F
 export type { Value as PropertyValue } from '@astrale-os/kernel-dsl/value';
 export type { JsonSchema as ValueSchema, JsonSchemaObject as ValueSchemaObject, } from './value/model/schema.js';
 export type { OrderingKind } from './value/ordering.js';
+export { stateMachine } from './state/index.js';
+export type { EventOf, StateMachine, StateOf, StateTopology } from './state/index.js';
 export type * from './callable/model/callable.js';
 export type * from './callable/resolved.js';
 export type * from './class/model/class.js';

package/dist/v1/language/index.js

@@ -1 +1,2 @@
+export { stateMachine } from './state/index.js';
 export { PropertyValues } from './class/property-values.js';

package/dist/v1/language/state/index.d.ts

@@ -0,0 +1,3 @@
+export { stateMachine } from './machine.js';
+export type { EventOf, StateMachine, StateOf } from './machine.js';
+export type { StateTopology } from './topology.js';

package/dist/v1/language/state/index.js

@@ -0,0 +1 @@
+export { stateMachine } from './machine.js';

package/dist/v1/language/state/machine.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { EventName, StateName, StateTopology, TransitionRelation, ValidTransitionRelation } from './topology.js';
+export interface StateMachine<Transitions extends TransitionRelation = any, Initial extends StateName<Transitions> = StateName<Transitions>> extends StateTopology<Transitions, Initial> {
+    readonly stateSchema: z.ZodType<StateName<Transitions>>;
+    readonly eventSchema: z.ZodType<EventName<Transitions>>;
+    eventsFrom<State extends StateName<Transitions>>(state: State): readonly EventName<Transitions, State>[];
+    decide<State extends StateName<Transitions>, Event extends EventName<Transitions>>(state: State, event: Event): TransitionDecision<Transitions, State, Event>;
+}
+export type StateOf<Machine extends StateMachine> = StateName<Machine['transitions']>;
+export type EventOf<Machine extends StateMachine, State extends StateOf<Machine> = StateOf<Machine>> = EventName<Machine['transitions'], State>;
+type TransitionDecision<Transitions extends TransitionRelation, State extends StateName<Transitions>, Event extends EventName<Transitions>> = State extends StateName<Transitions> ? Event extends EventName<Transitions> ? Event extends keyof Transitions[State] ? Readonly<{
+    kind: 'allowed';
+    transition: Readonly<{
+        from: State;
+        event: Event;
+        to: Transitions[State][Event];
+    }>;
+}> : Readonly<{
+    kind: 'rejected';
+    code: 'STATE_TRANSITION_ILLEGAL';
+    from: State;
+    event: Event;
+}> : never : never;
+export declare function stateMachine<const Transitions extends TransitionRelation, const Initial extends StateName<Transitions>>(input: Readonly<{
+    initial: Initial;
+    transitions: Transitions & ValidTransitionRelation<Transitions>;
+}>): StateMachine<Transitions, Initial>;
+export {};

package/dist/v1/language/state/machine.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { compareUnicode } from '../../addressing/ordering.js';
+import { admitStateTopology } from './topology.js';
+export function stateMachine(input) {
+    const topology = admitStateTopology(input);
+    const states = Object.keys(topology.transitions);
+    const events = [
+        ...new Set(states.flatMap((state) => Object.keys(topology.transitions[state]))),
+    ].sort(compareUnicode);
+    const stateSet = new Set(states);
+    const eventSet = new Set(events);
+    return Object.freeze({
+        ...topology,
+        stateSchema: z.enum(states),
+        eventSchema: z.enum(events),
+        eventsFrom(state) {
+            admitState(state, stateSet);
+            return Object.freeze(Object.keys(topology.transitions[state]));
+        },
+        decide(state, event) {
+            admitState(state, stateSet);
+            admitEvent(event, eventSet);
+            const target = topology.transitions[state][event];
+            return target === undefined
+                ? Object.freeze({ kind: 'rejected', code: 'STATE_TRANSITION_ILLEGAL', from: state, event })
+                : Object.freeze({
+                    kind: 'allowed',
+                    transition: Object.freeze({ from: state, event, to: target }),
+                });
+        },
+    });
+}
+function admitState(state, states) {
+    if (!states.has(state))
+        throw new TypeError(`State machine does not declare state "${state}".`);
+}
+function admitEvent(event, events) {
+    if (!events.has(event))
+        throw new TypeError(`State machine does not declare event "${event}".`);
+}

package/dist/v1/language/state/topology.d.ts

@@ -0,0 +1,14 @@
+export type TransitionRelation = Readonly<Record<string, Readonly<Record<string, string>>>>;
+export type StateName<Transitions extends TransitionRelation> = Extract<keyof Transitions, string>;
+export type EventName<Transitions extends TransitionRelation, State extends StateName<Transitions> = StateName<Transitions>> = State extends StateName<Transitions> ? Extract<keyof Transitions[State], string> : never;
+export type ValidTransitionRelation<Transitions extends TransitionRelation> = Readonly<{
+    [State in StateName<Transitions>]: Readonly<{
+        [Event in keyof Transitions[State]]: string extends StateName<Transitions> ? string : Exclude<StateName<Transitions>, State>;
+    }>;
+}>;
+export interface StateTopology<Transitions extends TransitionRelation = TransitionRelation, Initial extends StateName<Transitions> = StateName<Transitions>> {
+    readonly initial: Initial;
+    readonly transitions: Transitions;
+}
+export type StateTopologyOf<Value> = Value extends StateTopology<infer Transitions, infer Initial> ? StateTopology<Transitions, Initial> : undefined;
+export declare function admitStateTopology(input: unknown): StateTopology;

package/dist/v1/language/state/topology.js

@@ -0,0 +1,69 @@
+import { compareUnicode } from '../../addressing/ordering.js';
+export function admitStateTopology(input) {
+    if (!isRecord(input) || !exactKeys(input, ['initial', 'transitions']))
+        invalidInput();
+    const initial = input.initial;
+    const authored = input.transitions;
+    if (typeof initial !== 'string' || initial.length === 0 || !isRecord(authored))
+        invalidInput();
+    const states = Object.keys(authored);
+    if (states.length === 0)
+        throw new TypeError('State topology requires at least one state.');
+    if (states.includes(''))
+        throw new TypeError('State topology has an empty state name.');
+    if (!states.includes(initial)) {
+        throw new TypeError(`State topology initial state "${initial}" is not declared.`);
+    }
+    const declared = new Set(states);
+    const transitions = Object.create(null);
+    let transitionCount = 0;
+    for (const state of states.sort(compareUnicode)) {
+        const outgoing = authored[state];
+        if (!isRecord(outgoing))
+            throw new TypeError(`State "${state}" transitions must be an object.`);
+        const accepted = Object.create(null);
+        for (const event of Object.keys(outgoing).sort(compareUnicode)) {
+            const target = outgoing[event];
+            if (event.length === 0)
+                throw new TypeError(`State "${state}" has an empty event name.`);
+            if (typeof target !== 'string' || !declared.has(target)) {
+                throw new TypeError(`State "${state}" event "${event}" targets undeclared state "${String(target)}".`);
+            }
+            if (target === state) {
+                throw new TypeError(`State "${state}" event "${event}" is a self-transition.`);
+            }
+            accepted[event] = target;
+            transitionCount += 1;
+        }
+        transitions[state] = Object.freeze(accepted);
+    }
+    if (transitionCount === 0)
+        throw new TypeError('State topology requires at least one transition.');
+    const reachable = new Set([initial]);
+    const pending = [initial];
+    while (pending.length > 0) {
+        const state = pending.shift();
+        for (const target of Object.values(transitions[state])) {
+            if (reachable.has(target))
+                continue;
+            reachable.add(target);
+            pending.push(target);
+        }
+    }
+    for (const state of states) {
+        if (!reachable.has(state)) {
+            throw new TypeError(`State "${state}" is unreachable from initial "${initial}".`);
+        }
+    }
+    return Object.freeze({ initial, transitions: Object.freeze(transitions) });
+}
+function invalidInput() {
+    throw new TypeError('State topology must contain exactly initial and transitions.');
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function exactKeys(input, expected) {
+    const keys = Reflect.ownKeys(input);
+    return keys.length === expected.length && keys.every((key) => expected.includes(String(key)));
+}

package/dist/v1/schema/analysis/class.d.ts

@@ -3,6 +3,7 @@ import type { MethodDefinition } from '../../language/callable/model/callable.js
 import type { ClassDefinition } from '../../language/class/model/class.js';
 import type { DataDefinition } from '../../language/class/model/data.js';
 import type { PropertyAuto } from '../../language/class/model/property.js';
+import type { StateTopology } from '../../language/state/index.js';
 import type { JsonSchema } from '../../language/value/model/schema.js';
 import type { SchemaDiagnostic } from '../diagnostic.js';
 import type { DomainResolutionContext } from '../resolution/context.js';
@@ -14,6 +15,7 @@ export interface EffectiveField {
     readonly schema: JsonSchema;
     readonly required: boolean;
     readonly auto?: PropertyAuto;
+    readonly state?: StateTopology;
 }
 export interface EffectiveMethod {
     readonly identity: string;

package/dist/v1/schema/analysis/class.js

@@ -63,6 +63,7 @@ function ownFields(owner, declaration) {
             schema: property.schema,
             required: property.required,
             ...(property.auto === undefined ? {} : { auto: property.auto }),
+            ...(property.state === undefined ? {} : { state: property.state }),
         });
     }
     return result;

package/dist/v1/schema/compatibility/meaning.js

@@ -371,6 +371,7 @@ function propertyMeaning(field) {
         name: field.name,
         schema: semanticValueSchema(field.schema),
         required: field.required,
+        ...(field.state === undefined ? {} : { state: field.state }),
     };
 }
 function methodMeaning(method) {

package/dist/v1/schema/diagnostic.d.ts

@@ -1,4 +1,4 @@
-export type SchemaDiagnosticCode = 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'DV_VIEW_TARGET' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
+export type SchemaDiagnosticCode = 'DM_MEMBER_ROOT_INVALID' | 'DM_DEPENDENCY_CONTEXT_INVALID' | 'DM_DEPENDENCY_NOT_RETAINED' | 'DM_MEANING_INCONSISTENT' | 'DM_MEMBER_ORIGIN_MISMATCH' | 'DV_ACCEPTANCE_CONTEXT' | 'DV_CALLABLE_AUTH' | 'DV_CALLABLE_IO' | 'DV_CALLABLE_POLICY_AUTH' | 'DV_CLASS_ABSTRACT' | 'DV_CLASS_ACYCLIC' | 'DV_CLASS_KIND' | 'DV_CORE_EDGE_CLASS' | 'DV_CORE_EDGE_CONSTRAINTS' | 'DV_CORE_EDGE_KEY' | 'DV_CORE_EDGE_PROPERTIES' | 'DV_CORE_NODE_CLASS' | 'DV_CORE_NODE_PROPERTIES' | 'DV_CORE_REF' | 'DV_DATA_COMPOSITION' | 'DV_DEPENDENCY_ACYCLIC' | 'DV_DEPENDENCY_DIRECT' | 'DV_DEPENDENCY_EXACT' | 'DV_DEPENDENCY_LIMITS' | 'DV_DEPENDENCY_REVISION_COHERENCE' | 'DV_DEPENDENCY_UNIQUE' | 'DV_EDGE_ACCEPTS' | 'DV_EDGE_CLASS_COMPOSITION' | 'DV_EDGE_CONSTRAINT' | 'DV_EDGE_ROLE' | 'DV_EDGE_UNDIRECTED' | 'DV_JSON_VALUE' | 'DV_METHOD_ABSTRACT' | 'DV_METHOD_COMPOSITION' | 'DV_PROPERTY_AUTO' | 'DV_PROPERTY_COMPOSITION' | 'DV_PROPERTY_STATE' | 'DV_REF_RESOLVES' | 'DV_VALUE_SCHEMA' | 'DV_VIEW_TARGET' | 'PL_BUDGET' | 'PL_COMPOSITION' | 'PL_CONNECTIVITY' | 'PL_REF' | 'PL_REPEAT' | 'PL_TARGET' | 'PL_TYPING' | 'PL_USE' | 'PL_VARIABLE_SCOPE' | 'STRUCTURE_ABSTRACT_POLICY' | 'STRUCTURE_CALLABLE_POLICY_AUTH' | 'STRUCTURE_DUPLICATE_ITEM' | 'STRUCTURE_EDGE_ORIENTATION' | 'STRUCTURE_FORMAT' | 'STRUCTURE_INVALID' | 'STRUCTURE_KEY' | 'STRUCTURE_MAXIMUM' | 'STRUCTURE_MINIMUM' | 'STRUCTURE_MULTIPLE' | 'STRUCTURE_REQUIRED' | 'STRUCTURE_TYPE' | 'STRUCTURE_UNION' | 'STRUCTURE_UNKNOWN_FIELD' | 'STRUCTURE_VALUE' | 'UNSUPPORTED_DOCUMENT_FORMAT' | 'UNSUPPORTED_DSL_VERSION';
 export interface SchemaDiagnostic<out Code extends SchemaDiagnosticCode = SchemaDiagnosticCode> {
     readonly code: Code;
     readonly pointer: string;

package/dist/v1/schema/normalization/domain.js

@@ -1,6 +1,7 @@
 import { json } from '@astrale-os/kernel-dsl/value';
 import { compareDefinitionRefs, compareUnicode } from '../../addressing/ordering.js';
 import { normalizePolicyChecks, normalizePolicyExpression, } from '../../language/policy/normalization/normalize.js';
+import { admitStateTopology } from '../../language/state/topology.js';
 import { canonicalizeValueSchema } from '../../language/value/profile/canonicalize.js';
 export function normalizeDomainSchema(schema) {
     const classes = mapRecord(schema.classes, canonicalizeClass);
@@ -132,6 +133,9 @@ function canonicalizeProperty(value) {
                 },
             }),
         ...(value.description === undefined ? {} : { description: value.description }),
+        ...(value.state === undefined
+            ? {}
+            : { state: admitStateTopology(value.state) }),
     };
 }
 function canonicalizeDirectedEndpoints(value) {

package/dist/v1/schema/validation/class.js

@@ -1,5 +1,6 @@
 import { Key } from '../../addressing/key.js';
 import { definitionRefIndex } from '../../addressing/ordering.js';
+import { admitStateTopology } from '../../language/state/topology.js';
 import { classifyOrdering } from '../../language/value/ordering.js';
 import { diagnostic } from '../diagnostic.js';
 import { createValueSchemaRegistry } from '../resolution/value.registry.js';
@@ -26,15 +27,40 @@ export function validateDefinitions(environment, analysis) {
 function validateFacet(environment, declaration, pointer, diagnostics) {
     const valueRegistry = createValueSchemaRegistry(environment);
     for (const [name, property] of Object.entries(declaration.properties)) {
+        const propertyPointer = `${pointer}/properties/${escapePointer(name)}`;
+        if (property.state !== undefined) {
+            if (declaration.kind !== 'node') {
+                diagnostics.push(diagnostic('DV_PROPERTY_STATE', `${propertyPointer}/state`, 'A State Property may be declared only on a Node Class.'));
+            }
+            try {
+                const topology = admitStateTopology(property.state);
+                const expected = Object.keys(topology.transitions).sort();
+                const schema = property.schema;
+                const schemaMatches = schema !== null &&
+                    typeof schema === 'object' &&
+                    !Array.isArray(schema) &&
+                    Object.keys(schema).length === 2 &&
+                    schema.type === 'string' &&
+                    Array.isArray(schema.enum) &&
+                    schema.enum.length === expected.length &&
+                    [...schema.enum].sort().every((state, index) => state === expected[index]);
+                if (!property.required || property.auto !== undefined || !schemaMatches) {
+                    diagnostics.push(diagnostic('DV_PROPERTY_STATE', `${propertyPointer}/state`, 'A State Property is required, non-automatic, and has exactly its declared states.'));
+                }
+            }
+            catch (error) {
+                diagnostics.push(diagnostic('DV_PROPERTY_STATE', `${propertyPointer}/state`, error instanceof Error ? error.message : 'Invalid State topology.'));
+            }
+        }
         if (property.auto === undefined)
             continue;
-        const propertyPointer = `${pointer}/properties/${escapePointer(name)}/auto`;
+        const autoPointer = `${propertyPointer}/auto`;
         if (property.required && !property.auto.on.includes('create')) {
-            diagnostics.push(diagnostic('DV_PROPERTY_AUTO', `${propertyPointer}/on`, 'A required auto Property must run on create.'));
+            diagnostics.push(diagnostic('DV_PROPERTY_AUTO', `${autoPointer}/on`, 'A required auto Property must run on create.'));
         }
         if (property.auto.set === 'instant' &&
             classifyOrdering(property.schema, valueRegistry) !== 'instant') {
-            diagnostics.push(diagnostic('DV_PROPERTY_AUTO', `${propertyPointer}/set`, 'The instant setter requires an Instant value schema.'));
+            diagnostics.push(diagnostic('DV_PROPERTY_AUTO', `${autoPointer}/set`, 'The instant setter requires an Instant value schema.'));
         }
     }
     if (declaration.kind !== 'node')

package/dist/v1/schema/validation/domain.structure.js

@@ -34,6 +34,12 @@ const jsonSchemaSchema = z.union([z.boolean(), jsonObjectSchema]);
 const dataDeclarationSchema = z.strictObject({
     mediaType: z.string().regex(MEDIA_TYPE_PATTERN),
 });
+const stateNameSchema = z.string().min(1);
+const stateTransitionsSchema = z.custom(isStateTransitions);
+const stateTopologySchema = z.strictObject({
+    initial: stateNameSchema,
+    transitions: stateTransitionsSchema,
+});
 const propertyDefinitionSchema = z.strictObject({
     schema: jsonSchemaSchema,
     required: z.boolean(),
@@ -44,6 +50,7 @@ const propertyDefinitionSchema = z.strictObject({
     })
         .optional(),
     description: descriptionSchema.optional(),
+    state: stateTopologySchema.optional(),
 });
 const propertyRecordSchema = z.record(memberNameSchema, propertyDefinitionSchema);
 const domainDependencySchema = z.strictObject({
@@ -325,6 +332,30 @@ function absoluteRefSchema(kind) {
         name: memberNameSchema,
     });
 }
+function isStateTransitions(input) {
+    if (!isRecord(input))
+        return false;
+    for (const state of Reflect.ownKeys(input)) {
+        if (typeof state !== 'string' || state.length === 0)
+            return false;
+        const outgoing = Reflect.get(input, state);
+        if (!isRecord(outgoing))
+            return false;
+        for (const event of Reflect.ownKeys(outgoing)) {
+            const target = Reflect.get(outgoing, event);
+            if (typeof event !== 'string' ||
+                event.length === 0 ||
+                typeof target !== 'string' ||
+                target.length === 0) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
 function uniqueArray(element) {
     return z.array(element).superRefine((values, context) => {
         const firstIndexByValue = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-dsl",
-  "version": "0.2.0-beta.17",
+  "version": "0.2.0-beta.19",
   "description": "Astrale Kernel DSL - Schema authoring, inference, and IR serialization",
   "license": "Apache-2.0",
   "repository": {
@@ -59,6 +59,10 @@
       "types": "./dist/v1/language/index.d.ts",
       "import": "./dist/v1/language/index.js"
     },
+    "./v1/language/state": {
+      "types": "./dist/v1/language/state/index.d.ts",
+      "import": "./dist/v1/language/state/index.js"
+    },
     "./v1/schema": {
       "types": "./dist/v1/schema/index.d.ts",
       "import": "./dist/v1/schema/index.js"