@statedelta-actions/actions 0.2.0 → 0.5.0

package/dist/index.d.cts

@@ -1,21 +1,8 @@
-import { Directive, ExecutionFrame, DirectiveResult, RuleEngineRef, ApplyResult, HookFn, InterceptResult, AbortDecision, ActionEngineRef, FrameLimits, SlotAnalysis } from '@statedelta-actions/core';
+import { Directive, ExecutionFrame, RuleEngineRef, ApplyResult, RegisterWarning, ActionEngineRef, DirectiveResult, HookFn, InterceptResult, AbortDecision, FrameLimits, SlotAnalysis } from '@statedelta-actions/core';
+export { RegisterWarning } from '@statedelta-actions/core';
 
-type DirectiveHandler<TCtx> = (directive: Directive, frame: ExecutionFrame<TCtx>, engine: RuleEngineRef<TCtx>) => ApplyResult;
+type DirectiveHandler<TCtx> = (directive: Directive, frame: ExecutionFrame<TCtx>, engine: RuleEngineRef<TCtx>) => ApplyResult | Promise<ApplyResult>;
 type DirectiveHandlerMap<TCtx> = Record<string, DirectiveHandler<TCtx>>;
-interface DirectiveHooks<TCtx> {
-    beforeDirective?: HookFn<[
-        directive: Directive,
-        frame: ExecutionFrame<TCtx>
-    ], InterceptResult<TCtx>>;
-    afterDirective?: HookFn<[
-        directive: Directive,
-        result: ApplyResult,
-        frame: ExecutionFrame<TCtx>
-    ], AbortDecision>;
-    onDirectivesComplete?: HookFn<[result: DirectiveResult], void>;
-}
-type DirectiveExecutorFn<TCtx> = (directives: readonly Directive[], frame: ExecutionFrame<TCtx>, handlers: DirectiveHandlerMap<TCtx>, directiveHooks: DirectiveHooks<TCtx>, typeField: string, engine: RuleEngineRef<TCtx>, maxDirectives: number) => DirectiveResult | Promise<DirectiveResult>;
-type DirectiveRunnerFn<TCtx> = (directives: readonly Directive[], frame: ExecutionFrame<TCtx>) => DirectiveResult | Promise<DirectiveResult>;
 interface HandlerAnalysis {
     capabilities: string[];
     dependencies: string[];
@@ -32,8 +19,44 @@ interface HandlerDefinition<TCtx> {
     validate?: (directive: Directive) => ValidationResult | void;
     /** JIT-time: contribui código inline per-action (Fase 2c). */
     compile?: (directive: Directive, compiler: unknown) => string | void;
+    /**
+     * Marca o handler como assíncrono (opt-in explícito).
+     *
+     * Quando true (ou quando `execute` é uma `async function`), o engine:
+     * - inclui este handler no async handler set;
+     * - força `isAsync = true` no engine inteiro;
+     * - emite `await` ao invocar este handler no interpreter async e nos JITs.
+     *
+     * Auto-detecção via `isAsyncFunction(execute)` cobre `async function`.
+     * Use a flag para wrappers que retornam `Promise<ApplyResult>` sem
+     * serem `async function` (ex: factory que retorna função normal que
+     * delega pra um await internamente via `.then`).
+     *
+     * Sem flag e sem `async function`: handler é tratado como sync.
+     */
+    async?: boolean;
+    /**
+     * Marca o handler como interativo (opt-in explícito).
+     *
+     * Quando true (ou quando `execute` é uma `function*` / `async function*`),
+     * o engine:
+     * - inclui este handler no interactive handler set;
+     * - propaga transitividade `_interactiveActions` no mini-graph;
+     * - emite `yield* handler(...)` ao invocar nas actions interactive;
+     * - exige `engine.invokeInteractive()` em actions cuja sub-árvore use o handler.
+     *
+     * Auto-detecção via `isGeneratorFunction(execute)` cobre `function*` e
+     * `async function*`. Use a flag para wrappers que retornam iterator sem
+     * serem generator function.
+     *
+     * Handler com `interactive: true` em engine sem `interactive` config →
+     * erro no constructor (fail-fast).
+     *
+     * Sem flag e sem generator function: handler é tratado como regular.
+     */
+    interactive?: boolean;
     /** Runtime: executa a directive (obrigatório). */
-    execute: (directive: Directive, frame: ExecutionFrame<TCtx>, engine: ActionEngineRef<TCtx>) => ApplyResult;
+    execute: (directive: Directive, frame: ExecutionFrame<TCtx>, engine: ActionEngineRef<TCtx>) => ApplyResult | Promise<ApplyResult>;
 }
 /**
  * Aceita handler V1 (função) ou V2 (objeto com fases).
@@ -67,6 +90,20 @@ interface ActionDefinition<TCtx = unknown> {
      * Requer tierPropagator habilitado no grafo.
      */
     tier?: number;
+    /**
+     * Interactive — declaração explícita de que a action é interativa.
+     *
+     * Quando true, força `actionIsInteractive(id) === true` no mini-graph
+     * mesmo que a inferência local não detecte (ex: handler `action`
+     * dinâmico que pode invocar interactive em runtime).
+     *
+     * Pode ser inferida (sub-árvore usa handler interactive ou type:"pause").
+     * Quando declarada, o analyzer (opt-in) valida contra a inferência:
+     * declared !== inferred → DECLARATION_CONFLICT.
+     *
+     * Engine respeita declaração na propagação any_true.
+     */
+    interactive?: boolean;
     /**
      * Declarações — contratos públicos (trust boundaries).
      * Cada key = nome de um propagator registrado no grafo.
@@ -103,11 +140,7 @@ interface RegisterError {
     error: string;
     code?: string;
 }
-interface RegisterWarning {
-    actionId: string;
-    code: string;
-    message: string;
-}
+
 interface RegisterResult {
     registered: readonly string[];
     errors: readonly RegisterError[];
@@ -138,6 +171,90 @@ interface DirectivePermissionConfig {
  * String pura é equivalente a `{ pattern: string }`.
  */
 type DirectivePermissionEntry = string | DirectivePermissionConfig;
+
+/**
+ * Configuração do modo interactive.
+ *
+ * v0: estrutura mínima — habilita o modo. Controller dinâmico
+ * (`shouldPause`) pra debug arbitrário fica reservado pra evolução
+ * futura.
+ *
+ * Habilitar `interactive: {}` ativa:
+ * - mini-graph propaga `_interactiveActions` transitivo
+ * - actions cuja sub-árvore tem handler interactive ou `type:"pause"`
+ *   compilam como generator (na fase JIT correspondente)
+ * - `engine.invoke()` lança per-action transitivamente
+ * - `engine.invokeInteractive()` retorna iterator
+ *
+ * Sem `interactive` configurado:
+ * - handler com `interactive: true` → erro no constructor
+ * - diretiva `type: "pause"` → erro no register
+ */
+interface InteractiveConfig {
+}
+/**
+ * Evento yieldado durante execução de uma action interactive.
+ *
+ * - `source: "handler"` — handler interactive yieldou. `payload` é
+ *   opaco (handler controla o protocol).
+ * - `source: "pause"` — diretiva `type:"pause"` engine-level. `payload`
+ *   contém `{ message?: unknown }` extraído da diretiva.
+ */
+interface PauseEvent {
+    readonly source: "handler" | "pause";
+    readonly directive: Directive;
+    readonly frame: ExecutionFrame<unknown>;
+    readonly index: number;
+    readonly payload?: unknown;
+}
+/**
+ * Sessão interativa retornada por `engine.invokeInteractive()` em
+ * actions sync (sem handler async na sub-árvore).
+ *
+ * Drena via `next()`/`return()`/`throw()` ou `for...of`.
+ */
+interface InteractiveSession extends Iterator<PauseEvent, DirectiveResult, unknown> {
+    next(value?: unknown): IteratorResult<PauseEvent, DirectiveResult>;
+    return(): IteratorResult<PauseEvent, DirectiveResult>;
+    throw(err?: unknown): IteratorResult<PauseEvent, DirectiveResult>;
+    [Symbol.iterator](): InteractiveSession;
+}
+/**
+ * Sessão interativa async — engine async (handler async transitivo)
+ * combinado com interactive.
+ *
+ * Drena via `await session.next()` / `for await...of`.
+ */
+interface AsyncInteractiveSession extends AsyncIterator<PauseEvent, DirectiveResult, unknown> {
+    next(value?: unknown): Promise<IteratorResult<PauseEvent, DirectiveResult>>;
+    return(): Promise<IteratorResult<PauseEvent, DirectiveResult>>;
+    throw(err?: unknown): Promise<IteratorResult<PauseEvent, DirectiveResult>>;
+    [Symbol.asyncIterator](): AsyncInteractiveSession;
+}
+/**
+ * Forma alternativa de `ApplyResult` que um handler `action` pode
+ * retornar quando o target é interactive — engine detecta `iterator`
+ * e emite `yield* iterator` no JIT.
+ */
+interface InteractiveApplyResult {
+    readonly ok: true;
+    readonly iterator: Iterator<PauseEvent, ApplyResult, unknown> | AsyncIterator<PauseEvent, ApplyResult, unknown>;
+}
+
+interface DirectiveHooks<TCtx> {
+    beforeDirective?: HookFn<[
+        directive: Directive,
+        frame: ExecutionFrame<TCtx>
+    ], InterceptResult<TCtx>>;
+    afterDirective?: HookFn<[
+        directive: Directive,
+        result: ApplyResult,
+        frame: ExecutionFrame<TCtx>
+    ], AbortDecision>;
+    onDirectivesComplete?: HookFn<[result: DirectiveResult], void>;
+}
+type DirectiveExecutorFn<TCtx> = (directives: readonly Directive[], frame: ExecutionFrame<TCtx>, handlers: DirectiveHandlerMap<TCtx>, directiveHooks: DirectiveHooks<TCtx>, typeField: string, engine: RuleEngineRef<TCtx>, maxDirectives: number) => DirectiveResult | Promise<DirectiveResult>;
+type DirectiveRunnerFn<TCtx> = (directives: readonly Directive[], frame: ExecutionFrame<TCtx>) => DirectiveResult | Promise<DirectiveResult>;
 /** Resultado de interceptação do beforeAction — skip total da execução. */
 interface ActionInterceptResult {
     readonly data?: unknown;
@@ -199,6 +316,20 @@ interface IActionEngineConfig<TCtx> {
      * Diretivas estáticas (const/let/return/throw) são sempre permitidas.
      */
     blockedDirectives?: readonly DirectivePermissionEntry[];
+    /**
+     * Habilita modo interactive (generator-based pause/resume).
+     *
+     * Sem essa config:
+     * - handler com `interactive: true` → erro no constructor
+     * - diretiva `type: "pause"` em alguma action → erro no register
+     * - `engine.invokeInteractive()` lança
+     *
+     * Com `interactive: {}` ativo:
+     * - mini-graph propaga `_interactiveActions` transitivo
+     * - `engine.invoke()` lança per-action transitivo
+     * - `engine.invokeInteractive()` retorna iterator
+     */
+    interactive?: InteractiveConfig;
 }
 interface IActionEngine<TCtx> {
     /** Registra actions. Valida, analisa, indexa no grafo, compila. */
@@ -237,12 +368,98 @@ interface IActionEngine<TCtx> {
      */
     readonly directivePermissions: ReadonlyMap<string, DirectivePermission>;
     readonly isAsync: boolean;
+    readonly isInteractive: boolean;
     readonly compilationMode: "interpret" | "jit";
     compile(): void;
     readonly directiveHookSlots: ReadonlySet<string>;
     readonly asyncSlots: ReadonlySet<string>;
+    /**
+     * Action é async transitivamente?
+     * Consulta closure `_asyncActions` do mini-graph.
+     * `undefined` se id não está registrado.
+     */
+    isActionAsync(id: string): boolean | undefined;
+    /**
+     * Action é interactive transitivamente?
+     * Consulta closure `_interactiveActions` do mini-graph.
+     * `undefined` se id não está registrado.
+     */
+    isActionInteractive(id: string): boolean | undefined;
+    /**
+     * Invoca action em modo interactive — retorna iterator drenável.
+     * Lança se a action não é interactive ou se engine não tem
+     * `interactive` configurado.
+     *
+     * Variante async (AsyncInteractiveSession) é retornada quando a
+     * action é async transitivamente.
+     */
+    invokeInteractive(id: string, params?: Record<string, unknown>, ctx?: TCtx): InteractiveSession | AsyncInteractiveSession;
 }
 
+/**
+ * Helpers opcionais pra drenar `InteractiveSession` / `AsyncInteractiveSession`.
+ *
+ * `engine.invokeInteractive()` retorna iterator. Em "play mode" (sem debug),
+ * o consumer só quer o resultado final — drenar o iterator manualmente é
+ * verboso. Esses helpers fazem o trabalho.
+ *
+ * Em modo debug ou UX interativa real, o consumer dirige `next()` direto.
+ */
+/**
+ * Função do consumer pra responder a um yield do iterator. Retorna o valor
+ * que o iterator vai receber via `next(value)`.
+ *
+ * O `event` pode ser:
+ *   - `PauseEvent` (engine-level — `type:"pause"`): tem `source`, `directive`,
+ *     `frame`, `index`, `payload: { message }`.
+ *   - **Qualquer coisa** (handler interactive): handler controla 100% o
+ *     payload. Pode ser `{ prompt, options }`, `{ kind, data }`, etc.
+ *
+ * Retornos comuns:
+ *   - `undefined` ou ausente → continua / captura `undefined` em `as`
+ *   - `false` / `"abort"` / `"cancel"` → aborta `type:"pause"`
+ *   - qualquer dado → entregue ao handler ou capturado em `as`
+ */
+type Responder = (event: PauseEvent | unknown) => unknown;
+/**
+ * Drena uma `InteractiveSession` síncrona. Chama `next(value)` em loop até
+ * `done`, opcionalmente consultando `responder` em cada pausa.
+ *
+ * Sem responder: cada pausa recebe `undefined` (continua/captura `undefined`
+ * em `as`). Útil pra "play through" em testes determinísticos.
+ *
+ * @example
+ * ```ts
+ * const session = engine.invokeInteractive("foo", undefined, ctx) as InteractiveSession;
+ * const result = drainSync(session, (ev) => {
+ *   if (ev.source === "pause") return "ok";
+ *   if (ev.payload?.prompt === "Nome?") return "Anderson";
+ *   return undefined;
+ * });
+ * ```
+ */
+declare function drainSync(session: InteractiveSession, responder?: Responder): DirectiveResult;
+/**
+ * Drena uma `AsyncInteractiveSession`. Versão async de `drainSync`.
+ *
+ * Suporta responder sync ou async — se retornar Promise, é awaited.
+ */
+declare function drainAsync(session: AsyncInteractiveSession, responder?: Responder): Promise<DirectiveResult>;
+/**
+ * Cria um responder pré-programado a partir de uma lista de respostas.
+ * Cada pausa consome a próxima resposta na ordem. Ideal pra testes.
+ *
+ * @example
+ * ```ts
+ * const responder = replayResponder(["Anderson", "yes", 42]);
+ * const result = drainSync(session, responder);
+ * ```
+ *
+ * Se o iterator pausar mais vezes que a lista tem respostas, retorna
+ * `undefined` pras pausas extras (sem erro).
+ */
+declare function replayResponder(responses: readonly unknown[]): Responder;
+
 /**
  * Type-safe event emitter. Zero deps. Browser-compatible.
  *
@@ -288,7 +505,7 @@ declare class SimpleEmitter<TEvents = Record<string, unknown>> {
 }
 
 declare const RESERVED_TYPES: Set<string>;
-declare function normalizeDirectives<TCtx>(directives: readonly Directive<TCtx>[], _typeField: string): Directive<TCtx>[];
+declare function normalizeDirectives<TCtx>(directives: readonly Directive<TCtx>[], typeField: string): Directive<TCtx>[];
 
 declare function createDirectiveInterpreter<TCtx>(analysis: SlotAnalysis, isAsync: boolean): DirectiveExecutorFn<TCtx>;
 
@@ -299,13 +516,53 @@ interface GeneratedDirectiveExecutor {
     fn: RuntimeDirectiveExecutorFn;
     isAsync: boolean;
 }
-declare function buildDirectiveExecutor(analysis: SlotAnalysis): GeneratedDirectiveExecutor;
+/**
+ * Compila um executor genérico de diretivas via `new Function`.
+ *
+ * @param analysis — slot analysis dos directive hooks (filled/async).
+ * @param isAsync — se true, gera função `async ()` e prefixa `await` na chamada
+ *   do handler. Default: `analysis.hasAnyAsync` (preserva o comportamento legado
+ *   pra callers que não conhecem handler async). O engine sempre passa explícito,
+ *   computado a partir de `directiveAnalysis.hasAnyAsync || asyncHandlerSet.size > 0`.
+ */
+declare function buildDirectiveExecutor(analysis: SlotAnalysis, isAsync?: boolean): GeneratedDirectiveExecutor;
 
 type RuntimeActionExecutorFn = (frame: unknown, scope: unknown, $: unknown) => unknown;
 interface GeneratedActionExecutor {
     fn: RuntimeActionExecutorFn;
+    /** Wrapper async (`async function`/`async function*`)? */
     isAsync: boolean;
+    /** Wrapper generator (`function*`/`async function*`)? Quando true, `fn(...)` retorna Generator/AsyncGenerator. */
+    isInteractive: boolean;
 }
-declare function buildActionExecutor(directives: readonly Directive[], analysis: SlotAnalysis, typeField: string): GeneratedActionExecutor;
+/**
+ * Compila um executor unrolled per-action via `new Function`.
+ *
+ * Decisão sync/async é **por action** (ADR-021 refinado):
+ * - Action com pelo menos 1 handler async (transitivamente, via mini-graph)
+ *   ou hook async → wrapper `async ()`, `await` em todos os handlers.
+ * - Action 100% sync na sub-árvore inteira → wrapper sync `()`, zero `await`.
+ *
+ * Em um engine híbrido (alguns handlers async, outros sync), actions cuja
+ * sub-árvore inteira é sync não pagam o overhead de async functions.
+ *
+ * @param directives — diretivas normalizadas da action.
+ * @param analysis — slot analysis dos directive hooks (filled/async).
+ * @param typeField — campo de dispatch (default: "type").
+ * @param asyncHandlerSet — conjunto de tipos de handler marcados como async
+ *   (via flag `async: true` ou auto-detect `isAsyncFunction`). Se omitido,
+ *   nenhum handler é considerado async (compat backward).
+ * @param actionUsesAsyncOverride — se fornecido, substitui o cálculo local
+ *   `directives.some(asyncHandlerSet.has)`. Usado pelo engine pra passar a
+ *   info **transitiva** computada pelo mini-graph (ADR-026): action que
+ *   invoca outra action async via `{ type: "action", id: X }` é async
+ *   transitivamente, mas `asyncHandlerSet.has("action")` retorna false
+ *   (handler `action` em si não é async). Sem essa override, JIT compilaria
+ *   wrapper sync pra action async transitiva — bug.
+ *
+ *   Hooks async (`hasAnyAsync`) sempre forçam wrapper async (independente
+ *   do override) — wrapper sync não pode fazer await em hook.
+ */
+declare function buildActionExecutor(directives: readonly Directive[], analysis: SlotAnalysis, typeField: string, asyncHandlerSet?: ReadonlySet<string>, actionUsesAsyncOverride?: boolean, actionIsInteractive?: boolean, interactiveHandlerSet?: ReadonlySet<string>): GeneratedActionExecutor;
 
-export { type ActionDefinition, type ActionHooks, type ActionInterceptResult, type DirectiveExecutorFn, type DirectiveHandler, type DirectiveHandlerMap, type DirectiveHooks, type DirectivePermission, type DirectivePermissionConfig, type DirectivePermissionEntry, type DirectivePermissionStatus, type DirectiveRunnerFn, type EngineEventMap, type EngineEventName, type GeneratedActionExecutor, type GeneratedDirectiveExecutor, type HandlerAnalysis, type HandlerDefinition, type HandlerInput, type HandlerInputMap, type IActionEngine, type IActionEngineConfig, type Listener, RESERVED_TYPES, type RegisterError, type RegisterEvent, type RegisterResult, type RegisterWarning, SimpleEmitter, type UnregisterEvent, type ValidationResult, buildActionExecutor, buildDirectiveExecutor, createActionEngine, createDirectiveInterpreter, normalizeDirectives };
+export { type ActionDefinition, type ActionHooks, type ActionInterceptResult, type AsyncInteractiveSession, type DirectiveExecutorFn, type DirectiveHandler, type DirectiveHandlerMap, type DirectiveHooks, type DirectivePermission, type DirectivePermissionConfig, type DirectivePermissionEntry, type DirectivePermissionStatus, type DirectiveRunnerFn, type EngineEventMap, type EngineEventName, type GeneratedActionExecutor, type GeneratedDirectiveExecutor, type HandlerAnalysis, type HandlerDefinition, type HandlerInput, type HandlerInputMap, type IActionEngine, type IActionEngineConfig, type InteractiveApplyResult, type InteractiveConfig, type InteractiveSession, type Listener, type PauseEvent, RESERVED_TYPES, type RegisterError, type RegisterEvent, type RegisterResult, type Responder, SimpleEmitter, type UnregisterEvent, type ValidationResult, buildActionExecutor, buildDirectiveExecutor, createActionEngine, createDirectiveInterpreter, drainAsync, drainSync, normalizeDirectives, replayResponder };