@statedelta-actions/actions 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# @statedelta-actions/actions
+
+## 0.6.0
+
+### Minor Changes
+
+- a3a818b: `HandlerDefinition` is now a discriminated union by execution mode
+
+  `HandlerDefinition<TCtx>` is `SyncHandlerDefinition<TCtx> | AsyncHandlerDefinition<TCtx> | InteractiveHandlerDefinition<TCtx>` — the `async` / `interactive` flags discriminate, and `execute` refines its return type per mode (`ApplyResult` for sync, `Promise<ApplyResult>` for async, `Generator<unknown, ApplyResult, unknown> | AsyncGenerator<unknown, ApplyResult, unknown>` for interactive). Consumers that call `handler.execute(...)` directly (tests, wrappers) — typing the handler as a subtype, or narrowing the union via the flags — no longer get the wide `ApplyResult | Promise<ApplyResult>` union for a handler they know is sync.
+
+  New exports: `HandlerBaseDefinition`, `SyncHandlerDefinition`, `AsyncHandlerDefinition`, `InteractiveHandlerDefinition`, `SyncHandlerExecute`, `AsyncHandlerExecute`, `InteractiveHandlerExecute`.
+
+  **Breaking (minor, pre-1.0):**
+  - A V2 handler that is `async` or `interactive` must now declare the `async: true` / `interactive: true` flag to satisfy the type. `{ async execute() {} }` without `async: true` no longer matches `HandlerDefinition` (it matches no subtype: sync requires a sync return, async/interactive require the flag). Runtime auto-detection via `isAsyncFunction` / `isGeneratorFunction` still works as a safety net — the type just forces the declaration to be explicit for V2.
+  - `HandlerDefinition<TCtx>["execute"]` is wider than before (it now includes the `Generator | AsyncGenerator` arm) — code that assigned `handler.execute` to `(...) => ApplyResult | Promise<ApplyResult>` needs to narrow or use a subtype. (This also fixes a latent bug: interactive handlers' `execute` previously violated the declared type silently.)
+  - V1 handlers (plain functions) and `HandlerInput<TCtx>` are unchanged.
+
+### Patch Changes
+
+- 26c579a: Polish published package metadata and READMEs
+  - `@statedelta-actions/core` now ships a README (was missing on npm).
+  - `@statedelta-actions/analyzer` README: fixed pervasive missing accents.
+  - `graph` and `events` READMEs: titles are now the package name (`# @statedelta-actions/graph` / `# @statedelta-actions/events`) instead of a conceptual name.
+  - All packages: added `keywords`, `homepage`, `bugs`; package.json keys reordered to a canonical layout.
+  - All packages: `CHANGELOG.md` added to `files` so it ships to npm; a `LICENSE` (MIT) file is included in the repo root and in each package.
+
+- Updated dependencies [26c579a]
+  - @statedelta-actions/core@0.5.1
+
+## 0.5.0
+
+### Minor Changes
+
+- f8c2b4a: Fail-fast register errors, controlled `action-not-found`, atomic registration, and events async/interactive modes
+  - **actions** — A missing handler for a directive type now throws at register
+    time (was a collected error) — fail-fast for typos and forgotten handlers.
+    Invoking an unknown action id returns `aborted: true, abortedBy:
+"action-not-found"` instead of a soft failure. `isActionAsync` is exposed on
+    the engine ref handed to handlers (symmetric with `isActionInteractive`).
+  - **rules** — `register()` is atomic: it builds a staging set, delegates to the
+    ActionEngine, then indexes locally only on success. Structural errors from the
+    ActionEngine propagate as a throw with no local state mutated.
+  - **events** — `register()`/`defineEvents()` are atomic the same way.
+    Async detection is now per-listener transitive via the ActionEngine mini-graph,
+    so hybrid engines keep `processEvents`/`processEventsAsync` viable for
+    listeners whose subtree is fully sync. New `processEventsInteractive()` returns
+    a drainable iterator (sync or async generator) — pauses from `type:"pause"` or
+    an interactive handler flow via `yield*` up to the consumer; halt scoping is
+    preserved (a pause stops the listeners of that event, following events
+    continue). New `isInteractive` getter.
+  - **core** — `ActionEngineRef` gains an optional `isActionAsync?` accessor.
+  - **sdk** — re-exports the new event types/surface; barrel deps moved to
+    `dependencies` (`workspace:^`).
+
+### Patch Changes
+
+- Updated dependencies [f8c2b4a]
+  - @statedelta-actions/core@0.5.0
+
+## 0.3.0
+
+### Minor Changes
+
+- Split types em definitions + engine em cada package; novo subpath sdk/definitions
+  - core: RegisterWarning movido pra core/types/engine.ts (tipo shared entre packages)
+  - actions: types.ts → types/definitions.ts + types/engine.ts
+  - rules: types.ts → types/definitions.ts + types/engine.ts
+  - events: types.ts → types/definitions.ts + types/engine.ts
+  - sdk: novo subpath ./definitions com re-export de definition types puros (zero runtime)
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @statedelta-actions/core@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Sync all packages to 0.2.0 (match SDK version)
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @statedelta-actions/core@0.2.0
+
+## 0.3.0
+
+### Minor Changes
+
+- Sync all packages to 0.2.0 (match SDK version)
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @statedelta-actions/core@0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson D. Rosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,6 +16,8 @@ Ações são **declarativas**. Uma action é um ID mais uma lista ordenada de di
 
 **Sem sugar no runtime.** Diretivas devem ser passadas em **forma canônica** — toda diretiva tem campo `type`. Sugar forms (shorthands de autoria) são concern do compilador JSON DSL, que normaliza antes de entregar pro engine. O engine não interpreta nem converte sugar.
 
+**Modo interactive opcional.** Actions podem **pausar entre diretivas** e aguardar input externo via generators (sync ou async). Implementado de forma ortogonal ao modo async — a granularidade é per-action transitiva via mini-graph interno. Ver [Modo Interactive](#modo-interactive) abaixo.
+
 ## Instalação
 
 ```bash
@@ -128,6 +130,47 @@ const handlers = {
 | `validate` | Register | Validação estrutural (rejeita diretivas malformadas) |
 | `execute` | Runtime | Processa a diretiva e retorna resultado |
 | `analyze` | — | Consumido pelo `ActionAnalyzer` externo, não pelo engine |
+| `async` (flag) | Construct | Marca handler como assíncrono (opt-in explícito) |
+
+### Handlers Async
+
+Handlers podem retornar `Promise<ApplyResult>`. O engine detecta async de duas formas:
+
+```typescript
+const handlers = {
+  // 1. Auto-detect via `async function` — pega quando execute é declarado async.
+  fetchUser: {
+    async execute(directive, frame) {
+      const user = await api.get(`/users/${directive.id}`);
+      return { ok: true, data: user };
+    },
+  },
+
+  // 2. Flag explícita — para wrappers que retornam Promise sem ser `async function`.
+  delegateAsync: {
+    async: true,
+    execute: (d, frame, engine) => engine.invokeAsync("inner", undefined, frame),
+  },
+};
+```
+
+**Engine híbrido.** O engine pode misturar handlers sync e async no mesmo registry. Se qualquer handler for async (ou qualquer hook for async), o engine inteiro vira async — `invoke()` lança e você passa a usar `invokeAsync()`. Mas o **JIT per-action decide sync/async por action**: actions que só usam handlers sync compilam wrapper sync, sem `await`. FPS/games com 100% handlers sync pagam zero overhead de async; ETL/business com handlers async awaita só onde precisa.
+
+```typescript
+const engine = createActionEngine({
+  handlers: {
+    update:  { execute: (d, f) => { /* sync */ return { ok: true }; } },
+    fetchDB: { async execute(d, f) { return { ok: true, data: await db.query(...) }; } },
+  },
+});
+
+engine.isAsync;          // true (fetchDB é async)
+engine.invoke("anything"); // throws — use invokeAsync
+
+// JIT compila:
+//   action que usa só `update`  → wrapper sync, zero await
+//   action que usa `fetchDB`    → wrapper async, await no handler
+```
 
 ## Ações
 
@@ -156,11 +199,13 @@ Três categorias. **Toda diretiva tem campo `type`** (forma canônica). O engine
 { type: "let", name: "total", value: "$", resolve: (ctx, scope) => ({ value: scope.subtotal * 1.1 }) }
 ```
 
-**Control** — saída antecipada:
+**Control** — saída antecipada e ramificação:
 
 ```typescript
 { type: "return", value: "done" }                     // success: true, data: "done"
 { type: "throw", message: "saldo insuficiente" }      // success: false
+{ type: "if", cond: (ctx, scope) => scope.hp > 0,
+  then: [...], else: [...] }                          // ramificação inline
 ```
 
 **Handler** — dispatch pro handler registrado:
@@ -172,7 +217,21 @@ Três categorias. **Toda diretiva tem campo `type`** (forma canônica). O engine
 
 O interpreter e JIT operam sobre formato uniforme — um único dispatch via `type` field, sem branching de categorias.
 
-Os nomes `const`, `let`, `return`, `throw` são **tipos reservados** — o engine rejeita handlers com esses nomes.
+Os nomes `const`, `let`, `return`, `throw`, `if`, `pause` são **tipos reservados** — o engine rejeita handlers com esses nomes.
+
+### `if` (then/else)
+
+`cond` aceita função `(ctx, scope) => boolean` ou boolean literal. Branches executam **no mesmo scope da action** — `const`/`let` em branch ficam visíveis depois. `return`/`throw`/`halt` em branch saem da action inteira (semântica esperada). Aninhamento livre.
+
+```typescript
+{ type: "if",
+  cond: (_ctx, scope) => scope.hp > 0,
+  then: [{ type: "state", target: "status", value: "alive" }],
+  else: [{ type: "throw", message: "dead" }],
+}
+```
+
+`cond` lança → erro coletado em `errors[]`, nenhum branch executa, prossegue. JIT emite `if/else` JS nativo unrolled (zero call overhead).
 
 Diretivas suportam:
 - **`as`** — captura `result.data` no scope: `scope["prev"] = result.data`
@@ -240,7 +299,7 @@ engine.context(ctx, () => {
   engine.invoke("combat");
 });
 
-// Async (obrigatório se algum hook for async)
+// Async (obrigatório se algum hook ou handler for async)
 const result = await engine.invokeAsync("heal", undefined, ctx);
 ```
 
@@ -353,6 +412,8 @@ createActionEngine({ handlers, mode: "auto" });       // Interpreta primeiro, pr
 | `jit` | Mais lento (compila) | `new Function` compilado | Produção, ações estáveis |
 | `auto` | Rápido | Promove per-action após threshold | Uso geral (padrão) |
 
+**Decisão sync/async é per-action.** No JIT per-action, cada action é compilada sync ou async independentemente, baseado nos handlers que ela usa. Em um engine híbrido, actions 100% sync ficam com wrapper sync e zero `await`; actions com pelo menos um handler async ficam com wrapper `async` e `await` em todos os handlers da action. Isso garante que uso fully-sync (FPS, game loops) não pague o custo de async functions só porque outro handler do mesmo engine é async.
+
 Threshold de auto-promote (padrão: 8):
 
 ```typescript
@@ -368,7 +429,7 @@ engine.compile();
 Informações de compilação:
 
 ```typescript
-engine.isAsync;          // true se hooks async detectados
+engine.isAsync;          // true se algum hook OU handler é async
 engine.compilationMode;  // "interpret" | "jit" (modo atual, não o requestado)
 ```
 
@@ -394,7 +455,7 @@ createActionEngine({
 });
 ```
 
-Hooks podem ser sync ou async. Hooks async tornam o engine async (`engine.isAsync === true`), exigindo `invokeAsync()`.
+Hooks podem ser sync ou async. Hooks async tornam o engine async (`engine.isAsync === true`), exigindo `invokeAsync()`. Handlers async (via flag `async: true` ou `async function`) também tornam o engine async — ver [Handlers Async](#handlers-async).
 
 **Custo zero quando ausente.** A compilação JIT não emite código de hook para hooks não registrados.
 
@@ -569,6 +630,22 @@ import type {
   ActionInterceptResult,
 } from "@statedelta-actions/actions";
 
+// Interactive
+import type {
+  InteractiveConfig,
+  PauseEvent,
+  InteractiveSession,
+  AsyncInteractiveSession,
+  InteractiveApplyResult,
+  Responder,
+} from "@statedelta-actions/actions";
+
+import {
+  drainSync,
+  drainAsync,
+  replayResponder,
+} from "@statedelta-actions/actions";
+
 // Register Pipeline
 import { RESERVED_TYPES } from "@statedelta-actions/actions";
 
@@ -588,6 +665,184 @@ import { buildActionExecutor } from "@statedelta-actions/actions";
 import type { GeneratedActionExecutor } from "@statedelta-actions/actions";
 ```
 
+## Modo Interactive
+
+Pausa execução de uma action e aguarda input externo do customer. Implementado via **generators** (sync ou async), ortogonal ao modo async.
+
+**Use cases:**
+- UX interativa em produção (wizards, prompts, confirmações)
+- Debug entre diretivas (futuro — modo separado)
+
+**Mecânica:**
+- **Handler interactive** declarado com `interactive: true` (espelha `async: true`) — handler é generator function
+- **Diretiva reservada `type: "pause"`** — engine emite yield direto pra confirmação/breakpoint declarativo
+- **Mini-graph interno** propaga `_interactiveActions` transitivamente (ADR-026)
+- **API**: `engine.invokeInteractive(id, params, ctx)` retorna `Iterator | AsyncIterator`
+
+### Habilitação
+
+```typescript
+const engine = createActionEngine({
+  handlers,
+  interactive: {},   // habilita modo interactive
+});
+```
+
+Sem `interactive` configurado:
+- Handler com `interactive: true` → erro no constructor (fail-fast)
+- Diretiva `type: "pause"` → erro no register
+
+### Handler interactive
+
+Handlers são **primitivas Lego** — genéricas, sem semântica de domínio (ADR-028). Vocabulário canonical pequeno (`state`, `emit`, `action`, `log`, `halt`) + handler interactive primitivo proposto: **`input`** (yield + schema + retry).
+
+> ⚠️ **Não use nomes domain-specific** (`askUser`, `confirmDelete`, `validateEmail`). Cria explosão combinatória, polui vocabulário canonical e viola o princípio Lego. Customer compõe domínio via **payload** das diretivas, não criando handlers.
+
+```typescript
+// Pattern recomendado: primitiva `input` genérica com schema + retry interno
+const handlers = {
+  input: {
+    interactive: true,
+    *execute(directive) {
+      let lastError: string | null = null;
+      let attempt = 1;
+      const max = directive.maxAttempts ?? Infinity;
+      while (attempt <= max) {
+        const answer = yield {
+          kind: "input",
+          payload: directive.payload,
+          schema: directive.schema,
+          attempt,
+          lastError,
+        };
+        if (!directive.schema) return { ok: true, data: answer };
+        const r = directive.schema.parse(answer);
+        if (r.ok) return { ok: true, data: r.data };
+        lastError = r.error;
+        attempt++;
+      }
+      return { ok: false, error: `validation failed after ${max} attempts` };
+    },
+  },
+};
+```
+
+Customer compõe actions com **payload domain-specific** sobre a primitiva:
+
+```typescript
+{ id: "register", directives: [
+  { type: "input", payload: { kind: "text", label: "Nome" }, as: "name", schema: nameSchema },
+  { type: "input", payload: { kind: "number", label: "Idade" }, as: "age", schema: ageSchema },
+  { type: "input", payload: { kind: "confirm", message: "Confirma?" }, as: "ok" },
+  { type: "state", target: "users", op: "push", value: { name: ..., age: ... } },
+]}
+```
+
+Consumer interpreta `payload.kind` — renderiza UI/CLI/voice. Framework não opina.
+
+**Schema agnóstico** — interface mínima `{ parse(raw): { ok: true, data } | { ok: false, error } }`. Customer adapta zod/valibot/json-schema/custom em 1 linha.
+
+> **`input` (intra-tick) ≠ `request` (cross-tick).** `input` pausa **dentro** de uma invocação (yield/next imediato). `request` (RealmSystem futuro, fora deste package) anota dependência declarativa, lock cross-tick. São conceitos distintos com nomes propositalmente diferentes.
+
+Auto-detect via `isGeneratorFunction(execute)` cobre `function*` e `async function*`. Use a flag `interactive: true` pra wrappers que retornam iterator sem ser generator function.
+
+### Diretiva `type: "pause"` (engine-level)
+
+```typescript
+{ type: "pause", message: "Confirmação destrutiva?", as: "ack" }
+```
+
+Engine yield direto:
+```typescript
+session.next();              // → { source: "pause", payload: { message: "..." }, ... }
+session.next("ok");          // → continua, captura "ok" em scope.ack
+session.next(false);         // → aborta (abortedBy: "pause")
+session.next("cancel");      // → aborta
+session.next("abort");       // → aborta
+```
+
+### Drenagem do iterator
+
+```typescript
+// Customer dirigindo manualmente
+const session = engine.invokeInteractive("wizard", undefined, ctx);
+const r1 = session.next();           // PauseEvent ou payload custom
+const r2 = session.next("Anderson"); // entrega resposta
+// quando r.done === true, r.value é o DirectiveResult final
+```
+
+Helpers opcionais pra "play mode":
+
+```typescript
+import { drainSync, drainAsync, replayResponder } from "@statedelta-actions/actions";
+
+// Drena com responder programático
+const result = drainSync(session, (event) => {
+  // event pode ser PauseEvent (type:"pause") ou payload custom (handler)
+  if ("prompt" in event) return responses[event.prompt];
+  if ((event as PauseEvent).source === "pause") return "ok";
+  return undefined;
+});
+
+// Replay determinístico (testes)
+const result = drainSync(session, replayResponder(["Anderson", 42, "yes"]));
+```
+
+### Sub-actions interativas (yield* propaga pausas)
+
+Quando action root invoca child interactive, pausas do child fluem pro consumer no nível raiz via `yield*`. Handler `action` (consumer-defined) decide:
+
+```typescript
+const handlers = {
+  action: {
+    execute: (d, f, e) => {
+      if (e.isActionInteractive(d.id)) {
+        // Target é interactive → propaga via iterator
+        return { ok: true, iterator: e.invokeInteractive(d.id, d.params, f) };
+      }
+      // Target sync → invoke regular
+      const r = e.invoke(d.id, d.params, f);
+      return { ok: r.success, data: r.data };
+    },
+  },
+};
+```
+
+Engine consulta mini-graph e marca actions transitivamente interativas. JIT detecta `_result.iterator` em runtime e emite `yield*` automaticamente.
+
+### Matriz async × interactive
+
+| Engine async? | Action interactive? | Compilação |
+|---------------|---------------------|------------|
+| não | não | `function ()` |
+| não | sim | `function* ()` |
+| sim | não | `async function ()` |
+| sim | sim | `async function* ()` |
+
+Granularidade per-action via mini-graph (ADR-021/025/026). FPS 100% sync com 1 action interactive isolada não paga overhead de generator nas outras.
+
+### `invoke()` per-action transitivo
+
+`invoke()` lança per-action (não global):
+
+```typescript
+engine.invoke("syncAction");           // OK — sub-árvore inteira sync
+engine.invoke("asyncAction");          // throw "use invokeAsync"
+engine.invoke("interactiveAction");    // throw "use invokeInteractive"
+```
+
+Engine híbrido (handler async + actions sync isoladas) permite `invoke()` regular nas sync. ADR-026.
+
+### Action hooks fora do generator
+
+`beforeAction` / `afterAction` (ADR-019) executam **antes** e **depois** do generator. Skip via `beforeAction` retorna `memoResult` imediatamente. `afterAction` substitui o resultado final.
+
+### Catch atômico
+
+Diretivas dentro de `catch` executam **atomicamente** (ADR-023) via `engine.runDirectives` — sem yield. Caminho de erro não pausa. Diretivas `type: "pause"` ou handler interactive dentro de catch geram warning em register-time.
+
+---
+
 ## Analyzer
 
 Funcionalidades de análise estática foram extraídas para o pacote `@statedelta-actions/analyzer`: