@astrale-os/sdk 0.5.0-beta.75 → 0.5.0-beta.76

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.0-beta.76](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.75...sdk-v0.5.0-beta.76) (2026-08-29)
+
+
+### Bug Fixes
+
+* **build:** preserve state transition authority ([#328](https://github.com/astrale-os/sdk/issues/328)) ([5ae3301](https://github.com/astrale-os/sdk/commit/5ae3301c6b72cc1dc7a5bf901e143f3235cb53ab))
+
 ## [0.5.0-beta.75](https://github.com/astrale-os/sdk/compare/sdk-v0.5.0-beta.74...sdk-v0.5.0-beta.75) (2026-08-29)
 
 

package/dist/deployment/build/material.d.ts

@@ -1,5 +1,6 @@
 import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
 import type { Runtime } from '../../application/runtime/index.js';
+import type { StatePropertyMaterial } from '../../platform/schema/state-property/material.js';
 import type { Build } from './build.js';
 import type { FrontendCompilation } from './frontend/index.js';
 export interface BuildMaterial {
@@ -13,6 +14,7 @@ export interface BuildMaterial {
         };
     };
     readonly callables: Build['callables'];
+    readonly stateProperties: readonly StatePropertyMaterial[];
     readonly requirements: Build['requirements'];
     readonly routes: Build['routes'];
     readonly frontend?: FrontendCompilation;
@@ -30,7 +32,7 @@ export interface GeneratedBuildMaterial {
 export declare function material(build: Build): BuildMaterial;
 /** Produce opaque material for execution code from one admitted Build. */
 export declare function generatedMaterial(build: Build): GeneratedBuildMaterial;
-/** Re-admit generated Build material and bind it to the exact imported Runtime value. */
+/** Re-admit detached provider-neutral Build material against the exact Runtime value. */
 export declare function restoreBuild<RuntimeValue extends Runtime>(input: BuildMaterial, runtime: RuntimeValue): Build<DomainSchema, RuntimeValue>;
 /**
  * Bind material embedded by generated release code without repeating its external admission.

package/dist/deployment/build/material.js

@@ -8,11 +8,18 @@ import { BUNDLE_MEDIA_TYPE } from '@astrale-os/kernel-protocol/publication/bundl
 import { admitRequirements, validateRequirements, } from '@astrale-os/kernel-protocol/publication/requirements';
 import * as routes from '@astrale-os/kernel-protocol/routes';
 import { admitRuntimeRegistry, isRuntime } from '../../application/runtime/index.js';
+import { restoreStatePropertyMaterial, statePropertyMaterial, } from '../../platform/schema/state-property/material.js';
 import { admitBuild, isBuild } from './admission.js';
+import { evidenceOf } from './admission.js';
+const runtimeStateProperties = new WeakMap();
 /** Detach the provider-neutral, runtime-free material embedded into generated execution code. */
 export function material(build) {
     if (!isBuild(build))
         throw new TypeError('Build material requires an admitted Build.');
+    if (!isRuntime(build.runtime))
+        throw new TypeError('Build Runtime is not admitted.');
+    const stateProperties = statePropertyMaterial(evidenceOf(build).domain);
+    bindRuntimeStateProperties(build.runtime, build.schema.bundle.ref.digest, stateProperties);
     return Object.freeze({
         format: 'astrale.sdk.build-material',
         version: 1,
@@ -24,6 +31,7 @@ export function material(build) {
             }),
         }),
         callables: build.callables,
+        stateProperties,
         requirements: build.requirements,
         routes: build.routes,
         ...(build.frontend === undefined ? {} : { frontend: build.frontend }),
@@ -39,7 +47,7 @@ export function generatedMaterial(build) {
         digest: digestOf(value),
     });
 }
-/** Re-admit generated Build material and bind it to the exact imported Runtime value. */
+/** Re-admit detached provider-neutral Build material against the exact Runtime value. */
 export function restoreBuild(input, runtime) {
     assertMaterialEnvelope(input, runtime);
     const domain = loadCompiledSchema(input.schema.compiled);
@@ -53,6 +61,9 @@ export function restoreBuild(input, runtime) {
         revision(decoded.root) !== input.schema.compiled.root.revision) {
         invalid();
     }
+    const stateProperties = snapshotStateProperties(input.stateProperties);
+    assertRuntimeStateProperties(runtime, input.schema.bundle.ref.digest, stateProperties);
+    restoreStatePropertyMaterial(domain, stateProperties);
     const registry = bindRuntime(domain, runtime, input.callables);
     const requirements = admitRequirements(input.requirements);
     validateRequirements(decoded.root, decoded.closure, requirements);
@@ -86,38 +97,48 @@ export function restoreBuild(input, runtime) {
  */
 export function restoreGeneratedBuild(input, runtime) {
     const generated = acceptGeneratedMaterial(input, runtime);
-    const domain = loadGeneratedSchema(generated.schema.compiled);
-    const registry = bindRuntime(domain, runtime, generated.callables);
-    const detached = Uint8Array.from(generated.schema.bundle.bytes);
+    const material = generated.material;
+    const domain = loadGeneratedSchema(material.schema.compiled);
+    const stateProperties = snapshotStateProperties(material.stateProperties);
+    restoreStatePropertyMaterial(domain, stateProperties);
+    bindRuntimeStateProperties(runtime, material.schema.bundle.ref.digest, stateProperties);
+    const registry = bindRuntime(domain, runtime, material.callables);
+    const detached = Uint8Array.from(material.schema.bundle.bytes);
     const build = Object.freeze({
         kind: 'build',
         schema: Object.freeze({
-            compiled: generated.schema.compiled,
+            compiled: material.schema.compiled,
             bundle: Object.freeze({
-                ref: generated.schema.bundle.ref,
+                ref: material.schema.bundle.ref,
                 bytes: () => new Uint8Array(detached),
             }),
         }),
         runtime,
-        callables: Object.freeze([...generated.callables]),
-        requirements: generated.requirements,
-        routes: generated.routes,
-        ...(generated.frontend === undefined ? {} : { frontend: generated.frontend }),
+        callables: Object.freeze([...material.callables]),
+        requirements: material.requirements,
+        routes: material.routes,
+        ...(material.frontend === undefined ? {} : { frontend: material.frontend }),
     });
     return admitBuild(build, { domain, registry });
 }
 function acceptGeneratedMaterial(input, runtime) {
+    const format = input?.format;
+    const version = input?.version;
+    const material = input?.material;
+    const digest = input?.digest;
     if (input === null ||
         typeof input !== 'object' ||
         Array.isArray(input) ||
-        input.format !== 'astrale.sdk.generated-build-material' ||
-        input.version !== 1 ||
+        format !== 'astrale.sdk.generated-build-material' ||
+        version !== 1 ||
         Reflect.ownKeys(input).some((key) => key !== 'format' && key !== 'version' && key !== 'material' && key !== 'digest') ||
-        digestOf(input.material) !== input.digest) {
+        digestOf(material) !== digest) {
         invalid();
     }
-    assertMaterialEnvelope(input.material, runtime);
-    return deepFreeze(input).material;
+    assertMaterialEnvelope(material, runtime);
+    const accepted = deepFreeze({ material });
+    deepFreeze(input);
+    return accepted;
 }
 function digestOf(input) {
     try {
@@ -127,9 +148,46 @@ function digestOf(input) {
         invalid();
     }
 }
+function bindRuntimeStateProperties(runtime, bundleDigest, stateProperties) {
+    const digest = statePropertyDigest(stateProperties);
+    const bindings = runtimeStateProperties.get(runtime) ?? new Map();
+    const existing = bindings.get(bundleDigest);
+    if (existing !== undefined && existing !== digest) {
+        throw new TypeError('Runtime has conflicting StateProperty authority for Build material.');
+    }
+    bindings.set(bundleDigest, digest);
+    runtimeStateProperties.set(runtime, bindings);
+}
+function assertRuntimeStateProperties(runtime, bundleDigest, stateProperties) {
+    const expected = runtimeStateProperties.get(runtime)?.get(bundleDigest);
+    if (expected === undefined) {
+        if (stateProperties.length === 0)
+            return;
+        throw new TypeError('Build StateProperty authority is not bound to its exact Runtime.');
+    }
+    if (statePropertyDigest(stateProperties) !== expected) {
+        throw new TypeError('Build StateProperty authority differs from its exact Runtime.');
+    }
+}
+function statePropertyDigest(input) {
+    try {
+        return artifact.identify(new TextEncoder().encode(JSON.stringify(input)), 'application/vnd.astrale.sdk.state-properties+json').digest;
+    }
+    catch {
+        invalid();
+    }
+}
+function snapshotStateProperties(input) {
+    try {
+        return deepFreeze(JSON.parse(JSON.stringify(input)));
+    }
+    catch {
+        invalid();
+    }
+}
 function assertMaterialEnvelope(input, runtime) {
     if (!isRuntime(runtime))
-        throw new TypeError('Generated Runtime is not admitted.');
+        throw new TypeError('Build Runtime is not admitted.');
     if (input === null ||
         typeof input !== 'object' ||
         Array.isArray(input) ||
@@ -139,6 +197,7 @@ function assertMaterialEnvelope(input, runtime) {
             key !== 'version' &&
             key !== 'schema' &&
             key !== 'callables' &&
+            key !== 'stateProperties' &&
             key !== 'requirements' &&
             key !== 'routes' &&
             key !== 'frontend')) {

package/dist/platform/schema/state-property/material.d.ts

@@ -0,0 +1,16 @@
+import type { Domain } from '@astrale-os/kernel-dsl/v1';
+import type { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+export interface StatePropertyMaterial {
+    readonly property: PropertyKey;
+    readonly initial: string;
+    readonly states: readonly string[];
+    readonly transitions: readonly Readonly<{
+        from: string;
+        event: string;
+        to: string;
+    }>[];
+}
+/** Capture only the portable StateProperty authority required by generated execution. */
+export declare function statePropertyMaterial(domain: Domain): readonly StatePropertyMaterial[];
+/** Restore portable StateProperty authority onto an exact compiled Domain. */
+export declare function restoreStatePropertyMaterial(domain: Domain, input: unknown): void;

package/dist/platform/schema/state-property/material.js

@@ -0,0 +1,118 @@
+import { stateMachine } from '../../../application/state/define.js';
+import { rememberResolvedStateProperties, stateMachineFor } from './registry.js';
+/** Capture only the portable StateProperty authority required by generated execution. */
+export function statePropertyMaterial(domain) {
+    const material = [];
+    for (const property of ownProperties(domain)) {
+        const machine = stateMachineFor(domain, property);
+        if (machine === undefined)
+            continue;
+        material.push(Object.freeze({
+            property: property.key,
+            initial: machine.initial,
+            states: Object.freeze([...machine.states]),
+            transitions: Object.freeze(machine.transitions.map((transition) => Object.freeze({ ...transition }))),
+        }));
+    }
+    return Object.freeze(material.sort((left, right) => compareText(left.property, right.property)));
+}
+/** Restore portable StateProperty authority onto an exact compiled Domain. */
+export function restoreStatePropertyMaterial(domain, input) {
+    if (!Array.isArray(input))
+        invalid();
+    const byKey = new Map();
+    const properties = new Map(ownProperties(domain).map((property) => [property.key, property]));
+    for (const candidate of input) {
+        if (!isRecord(candidate) ||
+            !exactKeys(candidate, ['property', 'initial', 'states', 'transitions'])) {
+            invalid();
+        }
+        const propertyKey = candidate.property;
+        const initial = candidate.initial;
+        const states = candidate.states;
+        const transitions = candidate.transitions;
+        if (typeof propertyKey !== 'string' ||
+            typeof initial !== 'string' ||
+            !Array.isArray(states) ||
+            states.some((state) => typeof state !== 'string') ||
+            !Array.isArray(transitions)) {
+            invalid();
+        }
+        const property = properties.get(propertyKey);
+        if (property === undefined || byKey.has(property.key))
+            invalid();
+        assertStateProperty(property, states);
+        const relation = Object.create(null);
+        for (const state of states)
+            relation[state] = Object.create(null);
+        for (const transition of transitions) {
+            if (!isRecord(transition) || !exactKeys(transition, ['from', 'event', 'to']))
+                invalid();
+            const { from, event, to } = transition;
+            if (typeof from !== 'string' ||
+                typeof event !== 'string' ||
+                typeof to !== 'string' ||
+                relation[from] === undefined ||
+                Object.hasOwn(relation[from], event)) {
+                invalid();
+            }
+            relation[from][event] = to;
+        }
+        const machine = Reflect.apply(stateMachine, undefined, [
+            { initial, transitions: relation },
+        ]);
+        if (!sameStrings(machine.states, states))
+            invalid();
+        byKey.set(property.key, machine);
+    }
+    rememberResolvedStateProperties(domain, byKey);
+}
+function ownProperties(domain) {
+    const properties = [];
+    const seen = new Set();
+    const visit = (selected) => {
+        if (seen.has(selected))
+            return;
+        seen.add(selected);
+        for (const definition of selected.definitions('class')) {
+            properties.push(...definition.self.properties);
+        }
+        for (const dependency of Object.values(selected.dependencies))
+            visit(dependency);
+    };
+    visit(domain);
+    return properties;
+}
+function assertStateProperty(property, states) {
+    const schema = property.definition.schema;
+    if (property.owner.kind !== 'node' ||
+        property.definition.required !== true ||
+        !isRecord(schema) ||
+        schema.type !== 'string' ||
+        !Array.isArray(schema.enum) ||
+        schema.enum.some((state) => typeof state !== 'string') ||
+        !sameStringSet(schema.enum, states)) {
+        invalid();
+    }
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sameStringSet(left, right) {
+    if (new Set(left).size !== left.length || new Set(right).size !== right.length)
+        return false;
+    return sameStrings([...left].sort(compareText), [...right].sort(compareText));
+}
+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)));
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid() {
+    throw new TypeError('StateProperty material is invalid.');
+}

package/dist/platform/schema/state-property/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Domain, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
+import type { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
 import type { Property, SchemaInput as DomainSchemaInput } from '@astrale-os/kernel-dsl/v1/builder';
 import type * as languageSchema from '@astrale-os/kernel-dsl/v1/schema';
 import type { StateMachine } from '../../../application/state/machine.js';
@@ -7,3 +8,5 @@ export declare function isStateProperty(value: unknown): boolean;
 export declare function rememberStateClass(selected: object, properties?: Readonly<Record<string, unknown>>): void;
 export declare function rememberStateSchema(source: languageSchema.DomainSchema, input: DomainSchemaInput, domain: Domain): void;
 export declare function stateMachineFor(domain: Domain, selected: ResolvedProperty<unknown>): StateMachine | undefined;
+/** Internal restoration seam for generated execution material. */
+export declare function rememberResolvedStateProperties(domain: Domain, byKey: ReadonlyMap<PropertyKey, StateMachine>): void;

package/dist/platform/schema/state-property/registry.js

@@ -1,6 +1,7 @@
 const propertyMachines = new WeakMap();
 const classProperties = new WeakMap();
 const schemaProperties = new WeakMap();
+const domainProperties = new WeakMap();
 export function rememberStateProperty(property, machine) {
     propertyMachines.set(property, machine);
 }
@@ -43,13 +44,23 @@ export function rememberStateSchema(source, input, domain) {
     const byProperty = new WeakMap();
     bindDomainProperties(domain, byKey, byProperty, new Set());
     schemaProperties.set(source, { byKey, byProperty });
+    domainProperties.set(domain, byProperty);
 }
 export function stateMachineFor(domain, selected) {
+    const retained = domainProperties.get(domain)?.get(selected);
+    if (retained !== undefined)
+        return retained;
     const source = Reflect.get(domain, 'source');
     if (typeof source !== 'object' || source === null)
         return undefined;
     return schemaProperties.get(source)?.byProperty.get(selected);
 }
+/** Internal restoration seam for generated execution material. */
+export function rememberResolvedStateProperties(domain, byKey) {
+    const byProperty = new WeakMap();
+    bindDomainProperties(domain, byKey, byProperty, new Set());
+    domainProperties.set(domain, byProperty);
+}
 function bindKey(byKey, key, machine) {
     const existing = byKey.get(key);
     if (existing !== undefined && existing !== machine) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.75",
+  "version": "0.5.0-beta.76",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",