@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.40

package/dist/project/install-command.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ */
+export declare function installCommand(instance?: string, identity?: string): string;

package/dist/project/install-command.js

@@ -0,0 +1,9 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ */
+export function installCommand(instance = '<instance>', identity) {
+    return (`astrale domain install <url> -i ${instance}` +
+        (identity === undefined ? '' : ` --as ${identity}`));
+}

package/dist/project/project.d.ts

@@ -1,24 +1,26 @@
-import type { ApplicationIdentity } from '../application/index.js';
-import type { InstallationTarget } from '../deployment/adapter/index.js';
+import type { DomainDefinitionIdentity } from '../application/index.js';
 import type { Tests } from '../testing/index.js';
 export interface ProjectEntrypoints {
     readonly runtime: string;
 }
+/**
+ * One Environment of a Project: where and how its deployments are made. It never names an
+ * instance: a deploy installs nothing, and `astrale domain install <url>` installs a deployment.
+ */
 export interface ProjectEnvironment<DeploymentValue = unknown> {
     readonly deployment: DeploymentValue;
-    readonly installation?: InstallationTarget;
 }
 /** The complete independently executable software-product definition in astrale.config.ts. */
-export interface Project<ApplicationValue extends ApplicationIdentity = ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
+export interface Project<DomainDefinitionValue extends DomainDefinitionIdentity = DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
     readonly kind: 'project';
-    readonly application: ApplicationValue;
+    readonly domain: DomainDefinitionValue;
     readonly environments: EnvironmentsValue;
     readonly entrypoints?: ProjectEntrypoints;
     readonly tests?: TestsValue;
 }
-export type ApplicationOfProject<Value> = Value extends {
-    readonly application: infer ApplicationValue;
-} ? Extract<ApplicationValue, ApplicationIdentity> : never;
+export type DomainDefinitionOfProject<Value> = Value extends {
+    readonly domain: infer DomainDefinitionValue;
+} ? Extract<DomainDefinitionValue, DomainDefinitionIdentity> : never;
 export type EnvironmentsOfProject<Value> = Value extends {
     readonly environments: infer EnvironmentsValue;
 } ? EnvironmentsValue : never;

package/dist/testing/dataset/define.d.ts

@@ -7,7 +7,7 @@ export type AuthoredDatasetVariables = DatasetVariables | void;
 /** The exact variables record retained by a Dataset for one authored return type. */
 export type DatasetVariablesOf<Value> = [Value] extends [void] ? Readonly<Record<never, never>> : Value extends DatasetVariables ? Value : never;
 export interface DatasetInput<Schema extends schemaLanguage.DomainSchema, Variables extends AuthoredDatasetVariables> {
-    /** Stable lowercase identity, unique within one Application. */
+    /** Stable lowercase identity, unique within one Domain. */
     readonly id: string;
     readonly title?: string;
     readonly description?: string;

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

@@ -0,0 +1,121 @@
+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, DurableStepRetry, 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;
+    /**
+     * The deployment's `durable.retry`: the budget of every Step that declares none, 20 attempts by
+     * default, and with `maxAttempts` the attempts of a run failing outside any Step before it pauses.
+     */
+    readonly retry?: DurableStepRetry;
+}
+/**
+ * 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 a failed Step within its budget
+ * and fails it once the budget is spent, keeps timers on a virtual clock, buffers signals, pauses a
+ * run failing outside any Step after its last attempt and cancels cooperatively. A retry does not
+ * wait out its backoff, but the backoff it skips counts toward the Step's `maxDurationMs`.
+ */
+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: why a paused Execution paused, or what the last attempt of
+     * an exhausted Step threw, which its `STEP_EXHAUSTED` outcome does not carry.
+     */
+    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;
+    /** Times the Step ran, retries and interruptions included; a replay runs it no more. */
+    readonly attempts: number;
+    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 {};