@astrale-os/sdk 0.6.0-beta.1 → 0.6.0-beta.10

package/README.md

@@ -78,6 +78,13 @@ Authenticated handlers use Domain self authority for `kernel`, `graph`, `query`,
 with the incoming caller Grant. Explicit authority remains on `kernel` and `graph`; the former
 handler `client` is removed. See [the API and migration guide](docs/handler-dependencies.md).
 
+## Durable Workflows
+
+A callable declared with `execution: { durable: true }` is implemented by `defineWorkflow` and runs
+on the Kernel's workflow engine: a call returns its `K.Execution` at once, and the run survives
+restarts with journaled Steps, durable timers and signals. Serve it with `serve({ durable })`. See
+[the durable Workflow guide](docs/durable-workflows.md).
+
 ## Node Class icons
 
 Every Node Class authored through the SDK must explicitly declare a self-contained SVG icon.
@@ -213,6 +220,21 @@ Disabled rules are skipped before evaluation and remain visible in lint coverage
 project rule disable does not bypass generic Oxlint, project admission, type-universe checks, or
 linter tool failures.
 
+A committed tree that is not Domain source, such as client mockups or a preview harness, can be
+excluded from `astrale-domain lint` with root-relative globs:
+
+```json
+{
+  "ignore": ["mockups/**", "prototypes/**"]
+}
+```
+
+Ignored paths are pruned before discovery: they are never read, parsed, counted against source
+limits, included in the source snapshot digest, or passed to generic Oxlint. Each glob starts with a
+literal root entry and may use `*` and `?` within a segment and `**` as a whole segment; a matched
+directory excludes everything below it. A glob that would cover a declared layer (including a
+remapped `sourcePath`) or a governed root file is rejected, so `ignore` cannot bypass the layout.
+
 Structured review [issues](issues/README.md) retain observation-first evidence and later governance
 attachments without becoming current contract authority.
 
@@ -246,6 +268,54 @@ URL, size, and ETag checks. Concurrent publication and snapshot observations sha
 cancelling one observer does not cancel another. `session.snapshot()` remains the complete,
 coherent Publication, bundle, and View catalog observation.
 
+## Headless scripts and Domain callables
+
+Function admission requires the principal itself to be able to use the Function. A credential
+minted for a user or key, such as `astrale token`, carries that identity as principal: it passes
+Kernel callables, but a Domain callable that the identity reaches only through a Policy fails with
+`2004`. The Session `exchange` option presents each Domain callable with a credential its declaring
+Domain exchanged for the caller instead. The Domain becomes the principal, and the Policy is still
+evaluated against the caller. Kernel callables, including graph reads and writes, keep the source
+credential.
+
+```ts
+import { connect, createSessionCredentialProvider } from '@astrale-os/sdk/client/session'
+
+const session = connect({
+  url: 'https://instance.example/api',
+  auth: createSessionCredentialProvider({
+    ttlSeconds: 60,
+    // Return { credential, expiresAt } with expiresAt in Unix milliseconds.
+    mint: (signal) => mintSourceCredential(signal),
+  }),
+  exchange: {},
+})
+
+await session.call({ target: '/:orders.example:class.Order:create', input }) // Domain callable
+await session.graph.get('@order-id') // Kernel callable: the source credential
+```
+
+- **Hold the source in a provider.** Domain credentials are cached per source credential, so a
+  `resolve` that returns a new token on every call also exchanges on every call. The provider also
+  lets the Session renew a source that is too close to expiry to feed a Domain credential.
+- **Lifetimes.** `exchange.ttlSeconds` (default 300) must exceed the provider's `ttlSeconds` plus a
+  5-second settlement skew. A Domain credential never outlives its source.
+- **Reading as a Domain.** To call Kernel callables as a Domain, for example to read Shell-owned
+  Classes, feed a second Session from an explicit exchange:
+  `createSessionCredentialProvider({ ttlSeconds: 60, mint: (signal) => session.exchange(shellIssuer, { signal }) })`.
+  `session.exchange(issuer)` caches nothing.
+- **Current identity.** Use `session.auth.whoami()`; `@self` is a CLI shorthand.
+- **Failures.** A failed exchange raises `ExchangeError` from `@astrale-os/sdk/client`. Its
+  `failure` names the reason (`discovery`, `unsupported`, `unavailable`, `rejected`,
+  `invalid-response` or `source-exhausted`); a `rejected` error carries the Domain's public error
+  as its cause. Branch on `failure`, not on the message.
+
+| Credential presented | Principal | Kernel callable | Domain callable reached by Policy |
+| --- | --- | --- | --- |
+| Source credential (minted or key) | the identity | ✅ | ❌ `2004`, unless the identity holds `can_use` on it through a Group |
+| Session with `exchange` | the declaring Domain, for Domain callables | ✅ with the source credential | ✅ Policy evaluated against the identity |
+| `session.exchange(issuer)` held by a second Session | that Domain | ✅ as that Domain | only what that Domain may use |
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.

package/dist/application/action/action.d.ts

@@ -29,6 +29,12 @@ export type ActionAddressOf<Callable> = Callable extends {
 export type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
 /** SDK Action address derived mechanically from the canonical local callable key. */
 export type ActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<LocalCallable<ResolvedDomainOf<Schema>>>;
+/** Address of a callable an Action may implement: a durable callable needs a Workflow. */
+export type ImmediateActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<Exclude<LocalCallable<ResolvedDomainOf<Schema>>, {
+    readonly execution: {
+        readonly durable: true;
+    };
+}>>;
 export type CallableAtAddress<Schema extends schema.DomainSchema, Address extends string> = LocalCallable<ResolvedDomainOf<Schema>> extends infer Callable ? Callable extends unknown ? ActionAddressOf<Callable> extends Address ? Callable : never : never : never;
 export type Action<Callable extends ResolvedCallable, Definitions extends Integrations = Readonly<Record<never, never>>, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = (context: ActionContext<Callable, DomainValue, Definitions, Errors>) => Promise<ActionOutputOf<Callable>>;
 declare const ACTION_SCHEMA: unique symbol;

package/dist/application/action/authoring.d.ts

@@ -1,5 +1,5 @@
 export { defineAction } from './define.js';
 export type { Action, ActionDefinition } from './action.js';
-export type { ActionContext, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, } from './context.js';
+export type { ActionContext, ActionBinaryInput, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, } from './context.js';
 export type { ActionBinary, ActionOutputOf } from './output.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/action/context.d.ts

@@ -1,7 +1,7 @@
 import type { AuthenticationEvidence, Grant, IdentityId } from '../../platform/auth/index.js';
 import type { BoundClientSession } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
-import type { CallableInputOf, Domain, ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
+import type { CallableInputOf, CallableInputModeOf, Domain, ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
 import type { HandlerDependencies } from '../dependency/index.js';
 import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { IntegrationClients, Integrations } from '../integration/index.js';
@@ -34,6 +34,16 @@ export interface ActionExecution {
         body(): Uint8Array;
     };
 }
+/** One admitted, single-consumer binary Function request body. */
+export interface ActionBinaryInput {
+    readonly body: ReadableStream<Uint8Array>;
+    readonly length: number;
+}
+type BinaryInputOf<Callable> = CallableInputModeOf<Callable> extends 'binary' ? {
+    readonly body: ActionBinaryInput;
+} : {
+    readonly body?: never;
+};
 export interface DomainGraphExecutor<DomainValue extends Domain = Domain> {
     readonly query: QueryExecutor<DomainValue>;
     readonly mutate: MutationExecutor<DomainValue>;
@@ -83,5 +93,5 @@ export type ActionContext<Callable extends ResolvedCallable, DomainValue extends
     readonly execution: ActionExecution;
     /** Construct one implementation-declared safe business error for `throw error(...)`. */
     readonly error: DeclaredErrorFactory<Errors>;
-} & AuthorityOf<Callable, DomainValue> & SelfOf<Callable>;
+} & AuthorityOf<Callable, DomainValue> & SelfOf<Callable> & BinaryInputOf<Callable>;
 export {};

package/dist/application/action/define.d.ts

@@ -1,12 +1,12 @@
 import type { schema } from '../../platform/schema/index.js';
 import type { DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
-import type { Action, ActionAddress, ActionDefinition, CallableAtAddress, ResolvedDomainOf } from './action.js';
+import type { Action, ActionDefinition, CallableAtAddress, ImmediateActionAddress, ResolvedDomainOf } from './action.js';
 import type { ResolvedCallable } from './context.js';
 /** Define one simple single-step implementation by its SDK Action address. */
 export declare function defineAction<Schema extends schema.DomainSchema, Definitions extends Integrations = Readonly<Record<never, never>>>(): {
-    <const Address extends ActionAddress<Schema>>(address: Address, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): ActionDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
-    <const Address extends ActionAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, Errors>): ActionDefinition<Schema, Address, Definitions, Errors>;
+    <const Address extends ImmediateActionAddress<Schema>>(address: Address, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): ActionDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
+    <const Address extends ImmediateActionAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>, Errors>): ActionDefinition<Schema, Address, Definitions, Errors>;
 };
 /** True only for an Action produced by defineAction in this SDK package root. */
 export declare function isAction(input: unknown): input is ActionDefinition;

package/dist/application/action/index.d.ts

@@ -1,5 +1,5 @@
 export { defineAction, isAction } from './define.js';
 export type { Action, ActionAddress, ActionAddressOf, ActionDefinition, CallableAtAddress, LocalCallable, ResolvedDomainOf, } from './action.js';
-export type { ActionContext, ActionExecution, AnonymousCaller, AuthenticatedCaller, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, ResolvedCallable, } from './context.js';
+export type { ActionContext, ActionBinaryInput, ActionExecution, AnonymousCaller, AuthenticatedCaller, Caller, DomainGraphExecutor, DomainGraphExecutors, DomainKernelSessions, ResolvedCallable, } from './context.js';
 export type { ActionBinary, ActionOutputOf } from './output.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/dependency/index.d.ts

@@ -1 +1 @@
-export type { DependencyCallOptions, DependencyInvoker, HandlerDependencies } from './invoker.js';
+export type { DependencyBinaryCallOptions, DependencyCallOptions, DependencyInvoker, HandlerDependencies, } from './invoker.js';

package/dist/application/dependency/invoker.d.ts

@@ -1,18 +1,23 @@
 import type { Binary, Input } from '../../platform/client/index.js';
-import type { SessionRequestOptions } from '../../platform/client/session/index.js';
+import type { SessionRequestOptions, SessionRequestOptionsWithBody } from '../../platform/client/session/index.js';
 import type { NodeId } from '../../platform/graph/node/index.js';
-import type { CallableInputOf, CallableOutputOf, CallableResultOf, Domain, ResolvedMethod, KernelSchema, schema } from '../../platform/schema/index.js';
+import type { CallableInputOf, CallableInputModeOf, CallableOutputOf, CallableResultOf, Domain, ResolvedFunction, ResolvedMethod, KernelSchema, schema } from '../../platform/schema/index.js';
 import type { LocalCallable } from '../action/index.js';
-export type DependencyCallOptions = Pick<SessionRequestOptions, 'timeoutMs' | 'idempotencyKey'>;
+export type DependencyCallOptions = Pick<SessionRequestOptions, 'timeoutMs' | 'idempotencyKey' | 'body'>;
+export type DependencyBinaryCallOptions = Pick<SessionRequestOptionsWithBody, 'timeoutMs' | 'idempotencyKey' | 'body'>;
 type InstanceMethodOf<D extends Domain> = Extract<LocalCallable<D>, ResolvedMethod<unknown, unknown, false>>;
 type FunctionOrStaticMethodOf<D extends Domain> = Exclude<LocalCallable<D>, ResolvedMethod<unknown, unknown, false>>;
+type WithInputMode<C, Mode extends 'value' | 'binary'> = C extends unknown ? CallableInputModeOf<C> extends Mode ? C : never : never;
+type ValueFunctionOrStaticMethodOf<D extends Domain> = WithInputMode<FunctionOrStaticMethodOf<D>, 'value'>;
+type BinaryFunctionOf<D extends Domain> = WithInputMode<Extract<LocalCallable<D>, ResolvedFunction>, 'binary'>;
 type DependencyInputOf<C> = C extends unknown ? unknown extends CallableInputOf<C> ? Input : [CallableInputOf<C>] extends [void] ? undefined : CallableInputOf<C> : never;
 type DependencyResultOf<C> = unknown extends CallableOutputOf<C> ? unknown : CallableResultOf<C, Binary>;
 /** One declared dependency, bound to one explicitly selected invocation authority. */
 export interface DependencyInvoker<D extends Domain> {
     readonly invoke: {
-        <const C extends FunctionOrStaticMethodOf<D>>(select: (domain: D) => C, input: NoInfer<DependencyInputOf<C>>, options?: DependencyCallOptions): Promise<DependencyResultOf<C>>;
+        <const C extends ValueFunctionOrStaticMethodOf<D>>(select: (domain: D) => C, input: NoInfer<DependencyInputOf<C>>, options?: DependencyCallOptions): Promise<DependencyResultOf<C>>;
         <const C extends InstanceMethodOf<D>>(select: (domain: D) => C, instance: NodeId, input: NoInfer<DependencyInputOf<C>>, options?: DependencyCallOptions): Promise<DependencyResultOf<C>>;
+        <const C extends BinaryFunctionOf<D>>(select: (domain: D) => C, metadata: NoInfer<DependencyInputOf<C>>, options: DependencyBinaryCallOptions): Promise<DependencyResultOf<C>>;
     };
 }
 /**

package/dist/application/mutation/authoring/properties.d.ts

@@ -1,9 +1,11 @@
 import type { MutationPropsInput } from '@astrale-os/kernel-core/graph/mutate';
 import type { PropertyInputOf, ResolvedClass, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
+import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
+import type { StoredPropertyInputOf } from '../../../platform/schema/property-input.js';
 export type RichPropertyInput<Class> = PropertyInputOf<Class>;
 export type RichPropertyName<Class> = Extract<keyof PropertyInputOf<Class>, string>;
 export interface RichPropertyConditions<Class> {
-    readonly equals?: RichPropertyInput<Class>;
+    readonly equals?: StoredPropertyInputOf<Class>;
     readonly absent?: readonly RichPropertyName<Class>[];
 }
 export interface RichPropertyDelta<Class> {
@@ -12,11 +14,11 @@ export interface RichPropertyDelta<Class> {
 }
 export declare function properties<Class extends ResolvedClass>(selected: Class, input: RichPropertyInput<Class>): MutationPropsInput;
 export declare function conditions<Class extends ResolvedClass>(selected: Class, input: RichPropertyConditions<Class>): Readonly<{
-    equals?: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/value").Value>> | undefined;
+    equals?: PropertyValues | undefined;
     absent?: readonly `${string}:class.${string}.property.${string}`[] | undefined;
 }>;
 export declare function delta<Class extends ResolvedClass>(selected: Class, input: RichPropertyDelta<Class>): Readonly<{
-    set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/value").Value>>;
+    set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/v1/language").PropertyValue>>;
     unset: readonly `${string}:class.${string}.property.${string}`[];
 }>;
 export declare function resolvedProperty<Class extends ResolvedClass>(selected: Class, name: RichPropertyName<Class>): ResolvedProperty;

package/dist/application/mutation/authoring/properties.js

@@ -1,10 +1,39 @@
 import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { PropertyValues } from '@astrale-os/kernel-dsl/v1/language';
 export function properties(selected, input) {
-    return selected.properties.from(input);
+    const ordinary = Object.create(null);
+    const receipts = [];
+    const sources = new Map();
+    for (const [name, value] of Object.entries(input)) {
+        const property = resolvedProperty(selected, name);
+        const previous = sources.get(property.key);
+        if (previous !== undefined) {
+            throw new TypeError(`Property ${property.key} is supplied through both ${JSON.stringify(previous)} and ${JSON.stringify(name)}.`);
+        }
+        sources.set(property.key, name);
+        if (isBlobProperty(property)) {
+            if (typeof value !== 'string') {
+                throw new TypeError(`Blob Property ${property.key} requires an upload receipt.`);
+            }
+            receipts.push([property.key, value]);
+        }
+        else {
+            ordinary[name] = value;
+        }
+    }
+    // Blob receipts are admitted by the Kernel executor. A property's ordinary validator expects
+    // the stored Ref, so run it only for ordinary write values before combining the two sets.
+    const admitted = selected.properties.from(ordinary);
+    return receipts.length === 0
+        ? admitted
+        : PropertyValues.create([
+            ...Object.entries(admitted).map(([key, value]) => [PropertyKey(key), value]),
+            ...receipts,
+        ]);
 }
 export function conditions(selected, input) {
     return Object.freeze({
-        ...(input.equals === undefined ? {} : { equals: properties(selected, input.equals) }),
+        ...(input.equals === undefined ? {} : { equals: selected.properties.from(input.equals) }),
         ...(input.absent === undefined
             ? {}
             : {
@@ -12,6 +41,10 @@ export function conditions(selected, input) {
             }),
     });
 }
+function isBlobProperty(property) {
+    const contract = property.definition.schema;
+    return (contract !== null && typeof contract === 'object' && contract['x-astrale-value-kind'] === 'blob');
+}
 export function delta(selected, input) {
     return Object.freeze({
         set: properties(selected, input.set ?? {}),

package/dist/application/mutation/authoring/transition.js

@@ -49,7 +49,10 @@ export function authorStateTransition(core, input) {
         class: selectedClassKey,
         props: conditions(selectedClass, {
             ...(suppliedAbsent === undefined ? {} : { absent: suppliedAbsent }),
-            equals: { ...suppliedEquals, ...from },
+            equals: {
+                ...suppliedEquals,
+                ...from,
+            },
         }),
     });
     core.updateNode({

package/dist/application/runtime/actions.js

@@ -16,6 +16,9 @@ export function admitActions(callables, input) {
         if (callable === undefined) {
             throw new TypeError(`Runtime Action ${definition.address} is not root-local and executable.`);
         }
+        if (callable.execution?.durable === true) {
+            throw new TypeError(`Runtime Action ${definition.address} is durable; implement it with defineWorkflow.`);
+        }
         return Object.freeze({
             kind: 'action',
             address: definition.address,

package/dist/application/runtime/workflows.d.ts

@@ -6,6 +6,8 @@ export interface RuntimeWorkflow {
     readonly address: string;
     readonly callable: ResolvedCallable;
     readonly definition: WorkflowDefinition;
+    /** Declared `execution: { durable: true }`: runs on the workflow engine, never inline. */
+    readonly durable: boolean;
 }
 /** Associate admitted Workflows with their exact authenticated value callables. */
 export declare function admitWorkflows(callables: readonly RuntimeCallable[], input: unknown): readonly RuntimeWorkflow[];

package/dist/application/runtime/workflows.js

@@ -22,11 +22,16 @@ export function admitWorkflows(callables, input) {
         if (callable.output.mode !== 'value') {
             throw new TypeError(`Runtime Workflow ${definition.address} must have value output.`);
         }
+        const durable = callable.execution?.durable === true;
+        if (!durable && definition.compat !== undefined) {
+            throw new TypeError(`Runtime Workflow ${definition.address} declares compat but its callable is not durable.`);
+        }
         return Object.freeze({
             kind: 'workflow',
             address: definition.address,
             callable,
             definition,
+            durable,
         });
     });
     return Object.freeze(workflows);

package/dist/application/workflow/authoring.d.ts

@@ -1,4 +1,5 @@
 export { defineWorkflow } from './define.js';
-export type { WorkflowContext } from './context.js';
-export type { Workflow, WorkflowAddress, WorkflowDefinition } from './workflow.js';
+export type { InlineWorkflowContext, WorkflowContext } from './context.js';
+export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableWorkflowContext, } from './durable.js';
+export type { Workflow, WorkflowAddress, WorkflowDefinition, WorkflowOptions } from './workflow.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/workflow/context.d.ts

@@ -2,8 +2,14 @@ import type { Domain } from '../../platform/schema/index.js';
 import type { ActionContext, ResolvedCallable } from '../action/index.js';
 import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
+import type { DurableCallable, DurableWorkflowContext } from './durable.js';
 import type { WorkflowStep } from './step/index.js';
-/** Exact multi-step Workflow context for one authenticated value-output callable. */
-export type WorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = ActionContext<Callable, DomainValue, Definitions, Errors> & {
+/** Multi-step context of one authenticated value-output callable run inside its invocation. */
+export type InlineWorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = ActionContext<Callable, DomainValue, Definitions, Errors> & {
     readonly step: WorkflowStep;
 };
+/**
+ * Exact Workflow context for one callable: engine-journaled when its Schema declares
+ * `execution: { durable: true }`, otherwise run inside its invocation.
+ */
+export type WorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = Callable extends DurableCallable ? DurableWorkflowContext<Callable, DomainValue, Errors> : InlineWorkflowContext<Callable, DomainValue, Definitions, Errors>;

package/dist/application/workflow/define.d.ts

@@ -1,11 +1,11 @@
 import type { schema } from '../../platform/schema/index.js';
 import type { ResolvedDomainOf } from '../action/index.js';
-import type { DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
+import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
-import type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowDefinition } from './workflow.js';
+import type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowDefinition, WorkflowOptions } from './workflow.js';
 /** Define one authenticated multi-step value-output implementation by its SDK Action address. */
 export declare function defineWorkflow<Schema extends schema.DomainSchema, Definitions extends Integrations = Readonly<Record<never, never>>>(): {
     <const Address extends WorkflowAddress<Schema>>(address: Address, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): WorkflowDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
-    <const Address extends WorkflowAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>): WorkflowDefinition<Schema, Address, Definitions, Errors>;
+    <const Address extends WorkflowAddress<Schema>, const Errors extends DeclaredErrors = NoDeclaredErrors>(address: Address, options: WorkflowOptions<Errors>, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>): WorkflowDefinition<Schema, Address, Definitions, Errors>;
 };
 export declare function isWorkflow(input: unknown): input is WorkflowDefinition;

package/dist/application/workflow/define.js

@@ -1,11 +1,12 @@
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import { rememberDeclaredErrors } from '../error/index.js';
 const admittedWorkflows = new WeakSet();
+const COMPAT_TOKEN = /^[A-Za-z0-9._~-]{1,64}$/u;
 /** Define one authenticated multi-step value-output implementation by its SDK Action address. */
 export function defineWorkflow() {
     return function define(address, optionsOrRun, possibleRun) {
         acceptWorkflowAddress(address);
-        const options = possibleRun === undefined ? undefined : optionsOrRun;
+        const options = possibleRun === undefined ? undefined : acceptOptions(optionsOrRun);
         const run = possibleRun ?? optionsOrRun;
         if (typeof run !== 'function')
             throw new TypeError('Workflow run must be a function.');
@@ -13,13 +14,28 @@ export function defineWorkflow() {
             kind: 'workflow',
             address,
             run,
+            ...(options?.compat === undefined ? {} : { compat: options.compat }),
         });
-        if (options !== undefined)
-            rememberDeclaredErrors(workflow, options);
+        if (options?.errors !== undefined)
+            rememberDeclaredErrors(workflow, { errors: options.errors });
         admittedWorkflows.add(workflow);
         return workflow;
     };
 }
+function acceptOptions(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).some((key) => key !== 'errors' && key !== 'compat')) {
+        throw new TypeError('Workflow options accept only errors and compat.');
+    }
+    const options = input;
+    if (options.compat !== undefined &&
+        (typeof options.compat !== 'string' || !COMPAT_TOKEN.test(options.compat))) {
+        throw new TypeError(`Invalid Workflow compat token: ${JSON.stringify(options.compat)}.`);
+    }
+    return options;
+}
 export function isWorkflow(input) {
     return input !== null && typeof input === 'object' && admittedWorkflows.has(input);
 }

package/dist/application/workflow/durable.d.ts

@@ -0,0 +1,83 @@
+import type { IssuerId } from '../../platform/auth/index.js';
+import type { BoundClientSession, ExecutionOutcome, ExecutionRef } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, Domain, ResolvedMethod } from '../../platform/schema/index.js';
+import type { Value } from '../../platform/value/index.js';
+import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
+import type { Mutation, MutationExecutor } from '../mutation/index.js';
+import type { QueryExecutor } from '../query/index.js';
+/** A callable whose Schema declares `execution: { durable: true }`. */
+export interface DurableCallable {
+    readonly execution: {
+        readonly durable: true;
+    };
+}
+/** Attested facts of the running Execution. They are data, never authority. */
+export interface DurableExecution {
+    /** The `K.Execution` node recording this call. */
+    readonly id: NodeId;
+    readonly function: {
+        readonly id: NodeId;
+        readonly version: `sha256:${string}`;
+    };
+    /** Kernel that recorded the Execution; every Step calls it back as the Domain. */
+    readonly kernel: IssuerId;
+    /** Who started the Execution. The Workflow never receives their credential. */
+    readonly initiator: {
+        readonly principal: NodeId;
+        readonly caller: NodeId;
+    };
+    /** Receiver of a durable instance Method. */
+    readonly receiver?: NodeId;
+}
+/**
+ * The Domain's own authority inside one Step. Kernel access exists only here, so every Kernel call
+ * belongs to a journaled Step and a replay never repeats it.
+ */
+export interface DurableStepAuthority<DomainValue extends Domain = Domain> {
+    /**
+     * Kernel Session acting as the Domain. Each `invoke` without an explicit `idempotencyKey` carries
+     * one derived from the Execution, the Step and its position, so a retried Step reaches the same
+     * durable child Execution.
+     */
+    readonly kernel: BoundClientSession;
+    readonly query: QueryExecutor<DomainValue>;
+    /** Each Mutation carries a key derived from the Execution, the Step and its position. */
+    readonly mutate: MutationExecutor<DomainValue>;
+}
+export interface DurableStep<DomainValue extends Domain = Domain> {
+    /**
+     * Run `execute` once and journal its portable output; a replay returns the journaled output. A
+     * Step may run again when its outcome was not journaled, so its effects must be idempotent.
+     */
+    run<Output>(id: string, execute: (authority: DurableStepAuthority<DomainValue>) => Output | Promise<Output>): Promise<Output>;
+    /**
+     * One journaled Mutation. Give it a zero-match precondition on a natural key (for example the
+     * Execution id) and map that failure in `reject`, so a Step replayed after its commit finds its
+     * own effect instead of repeating it.
+     */
+    mutate<Input, Output>(id: string, mutation: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type DurableSelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+/** Context of a durable Workflow: engine-journaled, acting as its Domain. */
+export type DurableWorkflowContext<Callable, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = {
+    readonly domain: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    readonly execution: DurableExecution;
+    /** Construct one implementation-declared safe business error for `throw error(...)`. */
+    readonly error: DeclaredErrorFactory<Errors>;
+    readonly step: DurableStep<DomainValue>;
+    /** Durable timer kept by the engine, even while the Domain is idle or down. */
+    sleep(durationMs: number): Promise<void>;
+    /** Resolve once `Execution.signal({ name, value })` delivers `name`, before or during the wait. */
+    promise<Signal extends Value = Value>(name: string): Promise<Signal>;
+    /** Whether `error` is the engine's cooperative cancellation, which the Workflow may compensate. */
+    cancelled(error: unknown): boolean;
+    /** Wait durably for another Execution to end, by journaled polling of its `result`. */
+    awaitExecution<Output>(execution: ExecutionRef<Output>): Promise<ExecutionOutcome<Output>>;
+} & DurableSelfOf<Callable>;
+export {};

package/dist/application/workflow/durable.js

@@ -0,0 +1 @@
+export {};

package/dist/application/workflow/index.d.ts

@@ -1,6 +1,7 @@
 export { defineWorkflow, isWorkflow } from './define.js';
-export type { WorkflowContext } from './context.js';
-export type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowCallable, WorkflowDefinition, } from './workflow.js';
+export type { InlineWorkflowContext, WorkflowContext } from './context.js';
+export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableWorkflowContext, } from './durable.js';
+export type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowCallable, WorkflowDefinition, WorkflowOptions, } from './workflow.js';
 export * as step from './step/index.js';
 export * as runner from './runner/index.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/workflow/runner/inline.js

@@ -1,11 +1,12 @@
-import * as value from '../../../platform/value/index.js';
 import { acceptStepId } from '../step/index.js';
+import { acceptStepOutput } from '../step/output.js';
 /** Process-local runner for tests and explicitly non-durable embeddings. */
 export function createInlineWorkflowRunner() {
     async function run(workflow, context) {
         const execution = createInlineStep(context.execution.signal);
         const complete = Object.freeze({ ...context, step: execution.step });
         try {
+            // Runtime dispatches only non-durable Workflows inline; durable ones run on the engine.
             return await workflow.run(complete);
         }
         finally {
@@ -37,10 +38,8 @@ function createInlineStep(signal) {
             started.add(accepted);
             execution = (async () => {
                 const output = await execute();
-                if (output === undefined)
-                    return output;
                 try {
-                    return value.accept(output);
+                    return acceptStepOutput(output);
                 }
                 catch (cause) {
                     throw new TypeError(`Workflow Step ${accepted} output must be portable.`, {

package/dist/application/workflow/runner/runner.d.ts

@@ -2,9 +2,9 @@ import type { Domain, schema } from '../../../platform/schema/index.js';
 import type { ActionOutputOf, ResolvedCallable, ResolvedDomainOf } from '../../action/index.js';
 import type { DeclaredErrors, NoDeclaredErrors } from '../../error/index.js';
 import type { Integrations } from '../../integration/index.js';
-import type { WorkflowContext } from '../context.js';
+import type { InlineWorkflowContext } from '../context.js';
 import type { CallableAtWorkflowAddress, WorkflowAddress, WorkflowDefinition } from '../workflow.js';
-export type WorkflowExecutionContext<Callable extends ResolvedCallable, Definitions extends Integrations, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = Omit<WorkflowContext<Callable, DomainValue, Definitions, Errors>, 'step'>;
+export type WorkflowExecutionContext<Callable extends ResolvedCallable, Definitions extends Integrations, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = Omit<InlineWorkflowContext<Callable, DomainValue, Definitions, Errors>, 'step'>;
 export interface WorkflowRunner {
     run<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>, Definitions extends Integrations, Errors extends DeclaredErrors, Callable extends CallableAtWorkflowAddress<Schema, Address> = CallableAtWorkflowAddress<Schema, Address>>(workflow: WorkflowDefinition<Schema, Address, Definitions, Errors>, context: WorkflowExecutionContext<Callable, Definitions, ResolvedDomainOf<Schema>, Errors>): Promise<ActionOutputOf<Callable>>;
 }

package/dist/application/workflow/step/output.d.ts

@@ -0,0 +1,2 @@
+/** Capture optional Object fields as absence without changing portable Array or scalar semantics. */
+export declare function acceptStepOutput<Output>(input: Output): Output;