@astrale-os/sdk 0.6.0-beta.35 → 0.6.0-beta.37

package/dist/execution/workflows/steps.js

@@ -0,0 +1,67 @@
+import { bindSession } from '../../platform/client/session/index.js';
+import { bindCapabilities } from '../invocation/capabilities/index.js';
+import { bindIntegrationAuthentication } from '../invocation/integration/index.js';
+import { stepCalls } from './integrations.js';
+/**
+ * Steps acting as the Domain through a Session of the Execution they belong to: the capabilities of
+ * an Action over the keyed Session, and the Runtime's Integration clients over the same keys.
+ */
+export function sessionSteps(input) {
+    const { executor, domain, integrations } = input;
+    return ({ execution, next, lifetime }) => {
+        const session = executor(execution.kernel, execution.id, lifetime);
+        try {
+            const bound = bindSession(session, lifetime);
+            const self = keyed(bound, domain, next);
+            const auth = bindIntegrationAuthentication(lifetime, bound);
+            const authority = Object.freeze({
+                ...bindCapabilities(domain, { self }),
+                integrations: integrations(stepCalls({ next, lifetime, auth })),
+            });
+            return Object.freeze({ authority, close: () => session.close() });
+        }
+        catch (cause) {
+            session.close();
+            throw cause;
+        }
+    };
+}
+/**
+ * Every Mutation and every `invoke` of a durable callable of one Step without its own key carries
+ * the next key of the Step's sequence. The sequence restarts with every attempt, so a retried Step
+ * replays the same keys: the Kernel answers a Mutation with its receipt and a durable call with the
+ * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
+ * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
+ */
+export function keyed(session, domain, next) {
+    const invokeSource = session.invoke;
+    const mutateSource = session.mutate;
+    const invoke = ((reference, value, options) => invokeSource(reference, value, declaredDurable(domain, reference) ? withKey(options, next) : options));
+    const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
+    return Object.freeze({ ...session, invoke, mutate });
+}
+/**
+ * Whether the Domain's Schema closure declares the referenced callable durable. An untyped Path
+ * names no declaration and a callable outside the closure has none here: both need their own key.
+ */
+function declaredDurable(domain, reference) {
+    if (reference === null || typeof reference !== 'object')
+        return false;
+    const key = reference.callable;
+    return (typeof key === 'string' && domain.callable(key)?.execution?.durable === true);
+}
+function withKey(options, next) {
+    if (options?.idempotencyKey !== undefined || options?.body !== undefined)
+        return options;
+    return { ...options, idempotencyKey: next() };
+}
+/** The key sequence of one Step of one Execution: `<execution>.<digest of the name>.<position>`. */
+export async function keySequence(execution, name) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name)));
+    const prefix = `${execution}.${Array.from(digest.subarray(0, 12), hex).join('')}`;
+    let position = 0;
+    return () => `${prefix}.${++position}`;
+}
+function hex(byte) {
+    return byte.toString(16).padStart(2, '0');
+}

package/dist/platform/schema/index.d.ts

@@ -18,7 +18,7 @@ export type { ClassIcon } from './class-icon.js';
 export type { StoredPropertyInputOf } from './property-input.js';
 export type { CallablePolicyBuilder, CallablePolicyContext, ClassRuleBuilder, ClassRuleContext, PolicyCheckContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
 export type { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
-export type { CallableExecution, ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, PropertyImmutability, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
+export type { CallableAdmission, CallableExecution, ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, PropertyImmutability, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
 export type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */
 export { AuthorityOperationOrder, AuthorityOperations, AuthorityRelations, KernelRootFunctions, OperationCore, operationOf, } from '@astrale-os/kernel-core/schema';

package/dist/testing/durable/engine.d.ts

@@ -0,0 +1,111 @@
+import type { ActionOutputOf, ResolvedDomainOf } from '../../application/action/index.js';
+import type { DeclaredErrors } from '../../application/error/index.js';
+import type { Integrations, Providers } from '../../application/integration/index.js';
+import type { CallableAtWorkflowAddress, WorkflowAddress, WorkflowDefinition } from '../../application/workflow/index.js';
+import type { ExecutionOutcome, ExecutionState } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, ResolvedMethod, schema } from '../../platform/schema/index.js';
+import type { Value } from '../../platform/value/index.js';
+import type { TestStepCapabilities } from './steps.js';
+export interface TestEngineOptions {
+    /** Start of the virtual clock, in Unix milliseconds; the current time by default. */
+    readonly now?: number;
+    /** Attempts of a run before it pauses; 20 by default, as on a Host. */
+    readonly maxAttempts?: number;
+}
+/**
+ * An in-memory workflow engine that runs durable Workflows with the receiver a Host serves: it
+ * journals each Step, replays the journal on every attempt, retries failed attempts, keeps timers
+ * on a virtual clock, buffers signals, pauses after the last attempt and cancels cooperatively.
+ */
+export interface TestEngine {
+    /** The virtual clock, in Unix milliseconds. */
+    readonly now: number;
+    /** Start one durable Execution and settle it: it ends, waits, or pauses. */
+    start<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>, Definitions extends Integrations, Errors extends DeclaredErrors>(workflow: WorkflowDefinition<Schema, Address, Definitions, Errors>, options: TestStartOptions<CallableAtWorkflowAddress<Schema, Address>, ResolvedDomainOf<Schema>, Definitions>): Promise<TestExecution<ActionOutputOf<CallableAtWorkflowAddress<Schema, Address>>>>;
+    /** Move the virtual clock forward and settle every waiting Execution. */
+    advance(durationMs: number): Promise<void>;
+}
+export type TestStartOptions<Callable, DomainValue, Definitions extends Integrations> = {
+    /** The resolved Schema the Workflow belongs to. */
+    readonly schema: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    /** The `K.Execution` id; a fresh one by default. */
+    readonly id?: NodeId;
+    /** Who started the Execution; test Identities by default. */
+    readonly initiator?: {
+        readonly principal: NodeId;
+        readonly caller: NodeId;
+    };
+    readonly capabilities?: TestStepCapabilities;
+    /** Steps whose first completion is lost before the journal records it; see `interruptAfter`. */
+    readonly interruptAfter?: readonly string[];
+} & ReceiverOf<Callable> & ProvidersOf<Definitions>;
+type ReceiverOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+type ProvidersOf<Definitions extends Integrations> = keyof Definitions extends never ? {
+    readonly providers?: never;
+} : {
+    readonly providers: Providers<Definitions>;
+};
+/** One durable Execution on a test engine. */
+export interface TestExecution<Output> {
+    readonly id: NodeId;
+    readonly state: Extract<ExecutionState, 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled'>;
+    /** Present once the Execution ended, as `Execution.result` answers it. */
+    readonly outcome: ExecutionOutcome<Output> | undefined;
+    /** What the last failed attempt threw; it is why a paused Execution paused. */
+    readonly failure: unknown;
+    /** Attempts made so far, replays included. */
+    readonly attempts: number;
+    /** The run's journal, in order. */
+    readonly journal: readonly TestJournalEntry[];
+    /**
+     * Deliver `Execution.signal({ name, value })`, then settle. False when a signal already resolved
+     * that name.
+     */
+    signal(name: string, value?: Value): Promise<boolean>;
+    /** Request cooperative cancellation, as `Execution.cancel()`, then settle. */
+    cancel(): Promise<void>;
+    /** Attempt a paused Execution again, as `Execution.resume()`, then settle. */
+    resume(): Promise<void>;
+    /**
+     * Run the Workflow once more from its journal alone, as a restart does, and fail if it runs a Step
+     * again, diverges from the journal, or reaches another outcome.
+     */
+    replay(): Promise<void>;
+    /**
+     * The next time Step `id` completes, lose its result before the journal records it, as a crash
+     * between its effect and the journal does. The engine then retries the Step.
+     */
+    interruptAfter(id: string): void;
+}
+/** One entry of a run's journal. */
+export type TestJournalEntry = {
+    readonly kind: 'run';
+    readonly name: string;
+    readonly settled: boolean;
+    readonly value?: unknown;
+    readonly error?: unknown;
+} | {
+    readonly kind: 'sleep';
+    readonly until: number;
+    readonly settled: boolean;
+} | {
+    readonly kind: 'signal';
+    readonly name: string;
+    readonly settled: boolean;
+    readonly value?: unknown;
+} | {
+    readonly kind: 'race';
+    readonly name: string;
+    readonly until: number;
+    readonly settled: boolean;
+    readonly outcome?: 'signal' | 'timeout' | 'cancelled';
+};
+/** Create an in-memory workflow engine for tests. */
+export declare function createTestEngine(options?: TestEngineOptions): TestEngine;
+export {};