@statedelta-axiom/sandbox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,741 @@
+import * as _statedelta_axiom_realm_system from '@statedelta-axiom/realm-system';
+import { RealmCtx, RealmSystemConfig, RealmPhysicsInput, PersistConfigInput, StepResult, RealmSnapshot, SystemEvents, SystemPhase, RealmPhysics, IRealmSystem, BootOptions, ChildFactory } from '@statedelta-axiom/realm-system';
+import { ISchemaValidator, CompilationService, ProviderRegistry, ProviderBuffer, SourceKey, BootDefinitions, BootResult, BootError } from '@statedelta-axiom/contracts';
+import { HandlerDefinition, DirectivePermissionEntry, AsyncHandlerExecute, SyncHandlerExecute } from '@statedelta-actions/sdk/actions';
+import { FrameLimits } from '@statedelta-actions/sdk/core';
+
+/**
+ * Capabilities + Environment + cascade — Fase 2.
+ *
+ * Separação cravada em ADR-032: `environment` (categoria A — ambient,
+ * não cascade) e `capabilities` (categoria B — cascade restritiva
+ * child ≤ parent, ADR-030).
+ *
+ * `async` é environment (decisão arquitetural única do ecossistema —
+ * ADR-033 RS categoria A refinada). Não cascade.
+ */
+
+/**
+ * Recursos ambient do ecossistema. Compartilhados por referência entre
+ * todas as Sandboxes do mesmo runtime. Invisíveis pro realm — preservam
+ * determinismo. Trocar não muda lógica do mundo, só performance/mecânica.
+ */
+interface SandboxEnvironment {
+    readonly schemaValidator?: ISchemaValidator;
+    readonly handlers?: Record<string, HandlerDefinition<RealmCtx>>;
+    readonly analyzer?: RealmSystemConfig["analyzer"];
+    readonly trace?: boolean;
+    readonly compilationMode?: "interpret" | "jit" | "auto";
+    readonly autoJitThreshold?: number;
+    readonly debug?: boolean;
+    /** Decisão arquitetural única do ecossistema. Viral — ou todo RS é
+     *  async, ou todo é sync. Não cascade. */
+    readonly async?: boolean;
+    /**
+     * **CompilationService** — environment capability da Persistência v2
+     * (ADR-035 raiz). Compartilhado entre Sandboxes via Manager (por ref).
+     *
+     * Quando `physics.persist.definitions: true` é declarado, esta capability
+     * é **obrigatória** — sem ela, boot falha com `SandboxBootError
+     * ENVIRONMENT_INSUFFICIENT`. Com `persist.definitions: false`, é opcional
+     * (otimização de dedupe interno — ADR-034 raiz).
+     *
+     * Pode ser injetado externamente pra compartilhar entre múltiplos Runtimes
+     * (multi-tenant); ou o Runtime cria interno como default standalone.
+     */
+    readonly compilation?: CompilationService<RealmCtx>;
+    /**
+     * **System Providers** — registry de provider hooks (ADR-038 raiz / ADR-R018).
+     * Capability ambient compartilhada por ref entre todas as Sandboxes do
+     * mesmo runtime. Cada child herda por default; restringe via
+     * `SandboxCapabilities.providers` (whitelist).
+     */
+    readonly providers?: ProviderRegistry;
+    /**
+     * **ProviderBuffer** — porta de persistência pra entries `provide`
+     * (ADR-039 raiz / ADR-080 RS). Quando ausente, providers funcionam mas
+     * não persistem (modo serviço).
+     */
+    readonly providerBuffer?: ProviderBuffer;
+}
+/**
+ * Permissões hierárquicas do parent pra child. Aplicadas via
+ * `resolveCascade` no boot. Child > parent = `SandboxBootError`.
+ */
+interface SandboxCapabilities {
+    readonly enableEvents?: boolean;
+    readonly enableViews?: boolean;
+    readonly imperatives?: boolean;
+    readonly deterministic?: boolean;
+    /** RealmSystemConfig.mode (não confundir com SandboxMode closed/governed). */
+    readonly mode?: "dev" | "runtime";
+    readonly allowedDirectives?: readonly DirectivePermissionEntry[];
+    readonly blockedDirectives?: readonly DirectivePermissionEntry[];
+    readonly limits?: Partial<FrameLimits>;
+    readonly maxEventPasses?: number;
+}
+/**
+ * Capabilities **pós-cascade** (ADR-085). Estruturalmente igual a
+ * `SandboxCapabilities` — campos permanecem opcionais. Quem produz é
+ * `resolveCascade`.
+ *
+ * **Cascaded ≠ Resolved.** O cascade apenas propaga/valida flags do
+ * parent pra child; NÃO aplica defaults. Campos que parent e child
+ * ambos omitirem ficam `undefined` aqui — defaults canônicos vivem no
+ * RS via `resolveRealmPhysics` (ADR-084).
+ *
+ * Distinção é semântica: o tipo marca a origem "veio do `resolveCascade`",
+ * útil pra leitor saber que cascade já foi validado.
+ */
+type CascadedSandboxCapabilities = SandboxCapabilities;
+type CascadeViolationKind = "boolean_restrictive" | "boolean_deterministic" | "enum_tier" | "numeric" | "list_permissive";
+interface CascadeViolation {
+    readonly flag: string;
+    readonly parent: unknown;
+    readonly child: unknown;
+    readonly kind: CascadeViolationKind;
+}
+type CascadeResult = {
+    readonly ok: true;
+    readonly value: CascadedSandboxCapabilities;
+} | {
+    readonly ok: false;
+    readonly violations: readonly CascadeViolation[];
+};
+/**
+ * Erro como dado (ADR-063 RS) — `{ code, message?, data? }`.
+ */
+declare class SandboxBootError extends Error {
+    readonly code: string;
+    readonly data?: Record<string, unknown>;
+    constructor(opts: {
+        code: string;
+        message?: string;
+        data?: Record<string, unknown>;
+    });
+}
+/**
+ * Aplica cascade restritiva — 6 regras genéricas (ADR-030).
+ *
+ * - parent omitido → declared é resolved (sem cascade — sandbox top-level)
+ * - declared omitido → herda integralmente do parent
+ * - cada flag declarada é checada contra o parent; violações acumuladas
+ *
+ * Não throw. Retorna `{ ok, value | violations }` pro caller decidir.
+ */
+declare function resolveCascade(parent: CascadedSandboxCapabilities | undefined, declared: SandboxCapabilities | undefined): CascadeResult;
+/**
+ * Traduz capabilities resolvidas em `RealmPhysics` (regras de mundo —
+ * categoria B) pro RS interno. Campos undefined são omitidos — RS aplica
+ * seus defaults. `async` NÃO entra aqui (categoria A — vai pro
+ * RealmSystemConfig via `capabilitiesToSystemConfig`).
+ */
+declare function capabilitiesToPhysics(caps: CascadedSandboxCapabilities | undefined): RealmPhysicsInput;
+/**
+ * Traduz capabilities (mode) + environment (recursos ambient + `async`)
+ * em `RealmSystemConfig` pro RS interno. Campos undefined são omitidos.
+ *
+ * `async` é categoria A (ambient — ADR-032/033 RS): viral no ecossistema,
+ * sem cascade. Vive aqui (não em `RealmPhysics`) pra refletir que NÃO é
+ * regra de mundo.
+ */
+declare function capabilitiesToSystemConfig(caps: CascadedSandboxCapabilities | undefined, env: SandboxEnvironment | undefined): RealmSystemConfig;
+/** Violation do cascade restritivo de `persist` — child reduzindo rigor do parent. */
+interface PersistCascadeViolation {
+    readonly flag: "definitions" | "effects";
+    readonly parent: true;
+    readonly child: false;
+}
+type PersistCascadeResult = {
+    readonly ok: true;
+    readonly value: PersistConfigInput | undefined;
+} | {
+    readonly ok: false;
+    readonly violations: readonly PersistCascadeViolation[];
+};
+/**
+ * Aplica cascade restritivo de `physics.persist` (ADR-031 raiz).
+ *
+ * - parent omitido → top-level; declared é o resolvido (sem cascade).
+ * - declared omitido → herda integralmente do parent (preserva rigor).
+ * - cada flag (`definitions`/`effects`): parent=true + child=false → violation.
+ *   Outros casos (parent off, child on; ambos on; ambos off) ficam OK.
+ *
+ * Não throw — retorna `{ ok, value | violations }` pro caller decidir.
+ */
+declare function resolvePersistCascade(parent: PersistConfigInput | undefined, declared: PersistConfigInput | undefined): PersistCascadeResult;
+
+type DirectiveResult = ReturnType<IRealmSystem["invoke"]>;
+type DispatchResult = ReturnType<IRealmSystem["dispatch"]>;
+type EventProcessingResult = ReturnType<IRealmSystem["processEvents"]>;
+/** Modo de operação da Sandbox (ADR-008). */
+type SandboxMode = "closed" | "governed";
+/** Convenção do projeto pra erros: code obrigatório, message/data opcionais. */
+interface SandboxError {
+    readonly code: string;
+    readonly message?: string;
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * Result tagged pra métodos que podem falhar sem throw — Sandbox precisa
+ * disso porque parent realm DSL não consegue catch via diretiva. Métodos
+ * sem retorno usam SandboxOpResult. Métodos com retorno usam SandboxOpResult&lt;T&gt;.
+ */
+type SandboxOpResult<T = void> = (T extends void ? {
+    readonly ok: true;
+} : {
+    readonly ok: true;
+    readonly value: T;
+}) | {
+    readonly ok: false;
+    readonly error: SandboxError;
+};
+/** Razão pela qual a Sandbox foi finalizada (ADR-025). */
+type SandboxFinishReason = "manual" | "ttl";
+/**
+ * Resultado consultável após `finish()`. `undefined` enquanto a Sandbox
+ * não tiver finalizado. Pipeline-style: parent finaliza child e consulta
+ * o que aconteceu.
+ */
+interface SandboxResult {
+    readonly phase: "finished";
+    readonly reason: SandboxFinishReason;
+    readonly finishedAt: number;
+}
+/**
+ * Configs de término do realm (ADR-027). Hoje só `ttl`. Sub-objeto
+ * existe pra acomodar futuras configs de lifecycle sem poluir top-level.
+ */
+interface SandboxLifecycleConfig {
+    /** Ticks até `finish()` automático. Boot não conta — começa no 1º step. */
+    readonly ttl?: number;
+}
+/**
+ * AppPort — Consumer → System → API pública do Realm (ADR-009).
+ *
+ * Sempre visível, independente do modo. Controle raso: lifecycle (step/
+ * snapshot/restore), input via effects, leitura **limitada à superfície
+ * pública do child** quando `mode === "closed"` (exports — ADR-031,
+ * implementado em `ports.ts:isFilteredOut`). Em `governed`, exports é
+ * ignorado. Imperativas e mutações diretas **não** estão aqui — isso é
+ * SystemPort.
+ */
+interface IAppPort {
+    step(): StepResult;
+    stepAsync(): Promise<StepResult>;
+    get(stateId: string, field?: string): unknown;
+    applyEffect(id: string, data: unknown): void;
+    /**
+     * Captura snapshot do realm. Falha se phase é "created" — `{ code:
+     * "SNAPSHOT_PHASE_INVALID" }`. Após dispose: `SANDBOX_DISPOSED`.
+     */
+    snapshot(): SandboxOpResult<SandboxSnapshot>;
+    /**
+     * Restaura realm a partir de snapshot. Falha em mismatch de id/mode/
+     * capabilities (`SNAPSHOT_*_MISMATCH`) ou phase inválida do RS
+     * (`RESTORE_PHASE_INVALID`). Após dispose: `SANDBOX_DISPOSED`.
+     */
+    restore(snapshot: SandboxSnapshot): SandboxOpResult;
+    on<K extends keyof SystemEvents & string>(event: K, listener: (data: SystemEvents[K]) => void): () => void;
+    /**
+     * Subscribe pra mudanças efetivas no realm — canal de persistência
+     * observacional. Listener recebe `SandboxChange` agregado por tick.
+     *
+     * Lazy subscribe: agregador só assina hooks do RS interno quando o
+     * primeiro watcher entra; desassina quando o último sai. Sem watcher
+     * = zero overhead efetivo.
+     *
+     * Watch só dispatcha em ticks que **efetivamente mudaram o realm**:
+     * STEP_LOCKED não dispatcha; TICK_EXCEPTION em deterministic
+     * (rolled back) não dispatcha; throw declarativo em deterministic
+     * idem. Halt mantém mutações → dispatcha.
+     *
+     * Retorna unsubscribe idempotente.
+     */
+    watch(listener: (change: SandboxChange) => void): () => void;
+    getPhase(): SystemPhase;
+    getTick(): number;
+    isIdle(): boolean;
+    isAsync(): boolean;
+    hasState(id: string): boolean;
+    getStateIds(): string[];
+    /** Leis imutáveis do mundo (delega ao RS interno — ADR-032 RS). */
+    getPhysics(): Readonly<RealmPhysics>;
+}
+/**
+ * Mudança no realm dispatchada pelo Watch (ADR-026 refinada). Schema
+ * enxuto pra replay determinístico — Runtime aplica `effects` + reproduz
+ * rules → state derivado idêntico. Sem `stateChanges` (state é derivado,
+ * não input).
+ *
+ * Granularidade: 1 chamada por tick. Sem buffer interno — Runtime
+ * decide se acumula em memória, log append-only, etc.
+ */
+interface SandboxChange {
+    readonly tick: number;
+    /** Inputs pra replay — effects aplicados durante este tick. */
+    readonly effects?: readonly {
+        id: string;
+        data: unknown;
+    }[];
+    /** Lifecycle markers — booted no boot, finished em finish(). */
+    readonly lifecycle?: "booted" | "finished";
+    /** Erro do tick (TICK_EXCEPTION). Em deterministic já houve rollback. */
+    readonly error?: _statedelta_axiom_realm_system.TickError;
+    /** Outputs — eventos `notify` emitidos durante o tick. */
+    readonly notify?: readonly {
+        event: string;
+        data?: unknown;
+    }[];
+    /** Outputs — requests emitidos durante o tick (pra observação). */
+    readonly requests?: readonly {
+        id: string;
+    }[];
+}
+/** Listener de `app.watch()`. */
+type SandboxChangeListener = (change: SandboxChange) => void;
+/**
+ * SystemPort — Consumer → System direto (ADR-009).
+ *
+ * Visível apenas em modo `governed`. Bypassa o contrato público do Realm
+ * (exports). Expõe tudo do AppPort + imperativas (invoke/dispatch/emit/
+ * processEvents) + consultas internas (actions, rules, events). É a porta
+ * "hack legítimo" — quem detém ela controla o System diretamente, como se
+ * fosse o próprio System.
+ *
+ * Naming nota: NÃO é a "RealmPort" do ADR-011 do RS. Aquela é a porta
+ * INTERNA do Realm pro System (via diretivas, sem objeto JS). Aqui é a
+ * porta EXTERNA do consumer pro System bypassando o contrato público.
+ */
+interface ISystemPort extends IAppPort {
+    invoke(id: string, params?: Record<string, unknown>): DirectiveResult;
+    invokeAsync(id: string, params?: Record<string, unknown>): Promise<DirectiveResult>;
+    dispatch(stateId: string, op: string, params?: Record<string, unknown>): DispatchResult;
+    emit(event: string, data?: unknown): void;
+    processEvents(): EventProcessingResult;
+    processEventsAsync(): Promise<EventProcessingResult>;
+    getActionIds(): string[];
+    hasAction(id: string): boolean;
+    getRuleCount(): number;
+    hasRule(id: string): boolean;
+}
+/**
+ * Snapshot da Sandbox — wrappa o RealmSnapshot com metadados.
+ *
+ * ADR-006: não carrega o DSL fonte literalmente. DSL vive no
+ * `CompilationService` do environment (ADR-035 raiz); o snapshot carrega
+ * apenas referências (`bootSourceKey`) pra ele.
+ * ADR-032: capabilities resolvidas serializadas pra validação no restore.
+ */
+interface SandboxSnapshot {
+    readonly id: string;
+    readonly mode: SandboxMode;
+    readonly capabilities?: CascadedSandboxCapabilities;
+    readonly realm: RealmSnapshot;
+    /**
+     * **Persistência v2 — metadados pra restore via CompilationService**
+     * (ADRs 029/035/036 raiz). Presente apenas quando o realm declarou
+     * `physics.persist.definitions: true` e o boot conhecia o `bootSourceKey`
+     * (boot via DSL via Runtime, ou boot via diretiva `sandbox create` com
+     * `boot:<DSL>`). Ausente em snapshots state-only (`persist.definitions`
+     * off, ou boot via JS direto sem source).
+     */
+    readonly persistence?: SandboxPersistenceSnapshot;
+}
+/**
+ * Metadados de Persistência v2 anexados ao `SandboxSnapshot` quando o realm
+ * declarou `physics.persist.definitions: true`.
+ *
+ * `bootSourceKey` aponta pra DSL fonte no `CompilationService` do environment.
+ * Runtime recover faz `service.getSource(bootSourceKey)` → `service.compile(dsl)`
+ * → re-boot da Sandbox com a artifact retornada → `restore(snap.realm)`.
+ */
+interface SandboxPersistenceSnapshot {
+    readonly bootSourceKey: SourceKey;
+}
+/**
+ * Opções estendidas do `Sandbox.boot()` — superset de `BootOptions` do RS.
+ * `bootSourceKey` é metadado opcional consumido pela Sandbox (não vai pro RS)
+ * — permite que o snapshot subsequente referencie o source no
+ * `CompilationService` (ADR-034 raiz).
+ */
+interface SandboxBootOptions extends BootOptions {
+    /** Hash content-addressable do BootDSL que originou estas Definitions. */
+    readonly bootSourceKey?: SourceKey;
+}
+/**
+ * Config de criação de uma Sandbox.
+ *
+ * `environment` (categoria A) e `capabilities` (categoria B) são os
+ * caminhos preferenciais — separados por semântica (ADR-032).
+ * `physics` e `systemConfig` continuam como **escape hatches** low-level
+ * pra casos específicos; quando passados, têm precedência sobre os
+ * campos derivados de `environment`/`capabilities`.
+ */
+interface SandboxConfig {
+    /** Identificador único dentro do parent scope. */
+    readonly id: string;
+    /** Modo de operação (ADR-008). Default: "closed". */
+    readonly mode?: SandboxMode;
+    /** Recursos ambient do ecossistema (categoria A — ADR-032). */
+    readonly environment?: SandboxEnvironment;
+    /** Permissões hierárquicas declaradas pela child (categoria B — ADR-030). */
+    readonly capabilities?: SandboxCapabilities;
+    /** Configs de término (ADR-027). Hoje só `ttl`. */
+    readonly lifecycle?: SandboxLifecycleConfig;
+    /** Sandbox parent — habilita cascade no boot (ADR-035, ADR-067 RS). */
+    readonly parent?: ISandbox;
+    /**
+     * Lookup pra path syntax cross-sandbox (ADR-041). Quando definido,
+     * Sandbox monta o `crossRealmGet` (ADR-071 RS) que split o `/`,
+     * resolve childId via lookup e delega pro `child.app.get(intra)` —
+     * recursão pra profundidade arbitrária. Manager injeta automaticamente
+     * em cada Sandbox criada; Sandbox standalone fica sem (paths com `/`
+     * retornam undefined).
+     */
+    readonly lookup?: SandboxLookup;
+    /**
+     * Factory de child sandboxes — injetado pelo Manager (fecha sobre Manager +
+     * esta Sandbox como parent). A Sandbox o repassa pro `systemConfig.childFactory`
+     * do RS interno, que o usa pra processar `BootDefinitions.sandboxes` (e a
+     * directive `sandbox create`) — `def.boot` já é `BootDefinitions` compilado,
+     * o factory só cria+boota. Sandbox standalone (sem Manager) fica sem —
+     * `sandboxes` declaradas → BootError.
+     */
+    readonly childFactory?: ChildFactory;
+    /** Escape hatch — physics direto. Tem precedência sobre tradução de capabilities. */
+    readonly physics?: RealmPhysicsInput;
+    /** Escape hatch — systemConfig direto. Tem precedência sobre tradução de environment/capabilities. */
+    readonly systemConfig?: RealmSystemConfig;
+}
+/** Lookup de Sandbox por id (provido pelo Manager — ADR-037, ADR-041). */
+type SandboxLookup = (id: string) => ISandbox | undefined;
+/**
+ * Sandbox — wrapper de child realm (ADR-001, ADR-028).
+ *
+ * Wrappa um RealmSystem interno. Expõe AppPort sempre e SystemPort apenas
+ * em modo governed. A assimetria é por encapsulamento (ADR-009) — em modo
+ * closed, `system` é `undefined` e não há referência pra acessar.
+ *
+ * O **realm interno** se comunica com o System via diretivas (RealmPort
+ * conceitual do ADR-011 do RS) — sem objeto JS exposto. Realm não conhece
+ * AppPort/SystemPort.
+ */
+interface ISandbox {
+    readonly id: string;
+    readonly mode: SandboxMode;
+    /** Consumer → API pública do Realm via System. Sempre disponível. */
+    readonly app: IAppPort;
+    /** Consumer → API do System direto (bypass do contrato público).
+     *  Presente apenas em modo `governed`; `undefined` em `closed`. */
+    readonly system: ISystemPort | undefined;
+    /** Boota definitions no RS interno. Idempotente quanto a phase "created". */
+    boot(definitions: BootDefinitions<RealmCtx>, options?: SandboxBootOptions): BootResult;
+    /** Phase do RS interno. */
+    getPhase(): SystemPhase;
+    /** Capabilities resolvidas pós-cascade (ADR-030). Self-aware. */
+    getEffectiveCapabilities(): CascadedSandboxCapabilities;
+    /**
+     * Encerra o realm — phase vai pra "finished". Reads/snapshot/restore
+     * continuam ok. Falha se phase != "running" (`SANDBOX_FINISH_PHASE_INVALID`)
+     * ou já disposed (`SANDBOX_DISPOSED`).
+     */
+    finish(): SandboxOpResult;
+    /**
+     * Destrói a Sandbox — derruba listeners, libera RS interno. Após
+     * dispose, todas as chamadas em sandbox/app/system retornam
+     * `SANDBOX_DISPOSED`. Idempotente: 2º dispose retorna o mesmo erro.
+     */
+    dispose(): SandboxOpResult;
+    /** True se `dispose()` já foi chamado. */
+    isDisposed(): boolean;
+    /**
+     * Resultado consultável após `finish()`. Retorna `undefined` enquanto
+     * a Sandbox não tiver finalizado.
+     */
+    getResult(): SandboxResult | undefined;
+}
+
+/**
+ * Sandbox — factory do contexto de execução isolado.
+ *
+ * Fase 1: wrappa um RealmSystem e expõe ports.
+ * Fase 2: aceita `environment` + `capabilities` + `parent` na config,
+ *         resolve cascade restritiva (ADR-030), traduz pra physics +
+ *         systemConfig do RS interno.
+ * Fase 3: lifecycle terminal (`finish`/`dispose`/TTL/getResult — ADR-025,
+ *         ADR-027). Métodos diretos na ISandbox, não nos ports — encerrar
+ *         a Sandbox é semântica do wrapper, não do realm.
+ */
+
+declare function createSandbox(config: SandboxConfig): ISandbox;
+
+/**
+ * Construção dos ports (ADR-009).
+ *
+ * AppPort e SystemPort são wrappers finos sobre o RS. A assimetria é
+ * implementada por encapsulamento: em modo closed, `buildSystemPort` nunca
+ * é chamado e a referência simplesmente não existe pro consumer.
+ *
+ * AppPort = consumer → API pública do Realm via System (sempre).
+ * SystemPort = consumer → System direto, bypass do contrato público
+ * (só em governed).
+ * RealmPort (ADR-011 do RS) = realm interno → System via diretivas
+ * (não tem objeto JS — não é construído aqui).
+ *
+ * Fase 3: snapshot/restore retornam `SandboxOpResult` (erro como dado —
+ * ADR-029). Demais métodos lançam `Error` se a Sandbox foi disposed
+ * (ADR-025). Quando handler `sandbox` (Fase 5) vier, ele traduz throw
+ * residuais pro DSL parent — consumer JS é o único que enxerga throw.
+ */
+
+/**
+ * Exports resolvidos — superfície pública do realm filtrada por
+ * AppPort em closed (ADR-031). Lookups O(1) via Set.
+ *
+ * `accessible` é a união de states + views — usada por `get` que aceita
+ * paths intra-realm de qualquer tipo (split por `:` antes do lookup).
+ */
+interface ResolvedExports {
+    readonly states: ReadonlySet<string>;
+    readonly views: ReadonlySet<string>;
+    readonly actions: ReadonlySet<string>;
+    readonly accessible: ReadonlySet<string>;
+}
+interface PortContext {
+    readonly id: string;
+    readonly mode: SandboxMode;
+    readonly rs: IRealmSystem;
+    readonly capabilities: CascadedSandboxCapabilities;
+    /** Vivo enquanto a Sandbox não foi disposed (ADR-025). */
+    readonly isDisposed: () => boolean;
+    /**
+     * Getter de exports resolvidos — preenchido pela Sandbox no boot
+     * quando `BootDefinitions.exports` declarado. AppPort filtra leitura
+     * em modo closed; SystemPort ignora (sempre vê tudo — ADR-031).
+     * Retorna undefined quando exports não declarado (default permissivo).
+     */
+    readonly getExports?: () => ResolvedExports | undefined;
+    /**
+     * Getter do `bootSourceKey` capturado no boot (Persistência v2, ADR-034 raiz).
+     * Lido por `snapshot()` pra anexar `SandboxPersistenceSnapshot` quando
+     * `physics.persist.definitions: true` + key conhecida.
+     * Retorna undefined quando o boot não trouxe a key (boot via JS cru,
+     * ou realm sem `persist.definitions`).
+     */
+    readonly getBootSourceKey?: () => string | undefined;
+    /**
+     * Hook de path syntax cross-sandbox (ADR-041 + ADR-071 RS). Quando
+     * definido, `AppPort.get` em paths com `/` desvia diretamente —
+     * mesmo caminho que o RS interno usaria via `ctx.get`. Permite que
+     * consumer JS (`parent.app.get("child/hp:value")`) bata na child
+     * sem passar pelo Router (que retornaria undefined).
+     */
+    readonly crossRealmGet?: (path: string, field?: string) => unknown;
+    /**
+     * Watch Layer (ADR-026). Função do agregador interno da Sandbox —
+     * AppPort.watch delega aqui. Retorna unsubscribe idempotente.
+     */
+    readonly watch?: (listener: SandboxChangeListener) => () => void;
+    /**
+     * Notifica o agregador do Watch quando consumer aplica effect via
+     * AppPort. Agregador acumula no buffer do tick em curso.
+     */
+    readonly recordEffect?: (id: string, data: unknown) => void;
+}
+declare function buildAppPort(ctx: PortContext): IAppPort;
+declare function buildSystemPort(ctx: PortContext, app: IAppPort): ISystemPort;
+
+/**
+ * Lifecycle terminal — Fase 3 (ADR-025, ADR-027).
+ *
+ * Wrappa um RS interno e provê:
+ * - `finish()`  — encerra realm via `rs.finish()`; preserva snapshot.
+ * - `dispose()` — destrói sandbox; desfaz listeners; libera RS.
+ * - TTL automático — decrementa após cada `step()` executado (boot
+ *   não conta); em `ttl <= 0` dispara `finish("ttl")`.
+ * - `getResult()` — consulta consultável de razão/tick após finish.
+ *
+ * Ver ADR-040 — eventos do realm child pro parent ficam deferred. Por
+ * enquanto, consumer JS observa via `rs.on("finished", ...)` (sobe direto
+ * do RS interno) e consulta `getResult()` pra saber a razão.
+ */
+
+interface LifecycleHandle {
+    finish(): SandboxOpResult;
+    dispose(): SandboxOpResult;
+    isDisposed(): boolean;
+    getResult(): SandboxResult | undefined;
+}
+declare function createLifecycle(rs: IRealmSystem, config: SandboxLifecycleConfig | undefined): LifecycleHandle;
+
+/**
+ * SandboxManager — registry + factory wrapper + cascade destroy (ADR-037).
+ *
+ * Provê hierarquia de Sandboxes. Sandbox standalone (sem Manager) NÃO cria
+ * children (ADR-036). Manager NÃO cria RS (Sandbox cria — ADR-034); apenas
+ * orquestra graph + propaga environment compartilhado (ADR-R002 do Runtime).
+ *
+ * Estrutura interna (3 Maps inspirados no legado SandboxRegistry):
+ * - sandboxes: Map<id, ISandbox>           — flat storage O(1)
+ * - parents:   Map<childId, parentId>      — quem é pai
+ * - children:  Map<parentId, Set<childId>> — quem são filhos
+ *
+ * Hierarquia mora **só no graph**, nunca no id (ADR-035 — link simbólico).
+ *
+ * Cascade dispose depth-first: folhas primeiro, depois o pai (ADR-025).
+ * Copy-before-iterate evita mutation-during-iteration.
+ */
+
+interface SandboxManagerConfig {
+    /**
+     * Environment compartilhado entre todas as Sandboxes registradas.
+     * Categoria A — propagado por referência, sem cascade (ADR-032,
+     * ADR-R002 Runtime).
+     */
+    readonly environment?: SandboxEnvironment;
+}
+/**
+ * Config aceita por `Manager.createSandbox`. Manager resolve `parent`
+ * via `parentId` (lookup no graph), em vez de aceitar ref direta.
+ * `parent` direto não é aceito — Manager é a fonte de verdade da
+ * hierarquia (ADR-035).
+ */
+interface ManagerSandboxConfig extends Omit<SandboxConfig, "parent"> {
+    /** Id do parent registrado no Manager. Manager resolve a ref. */
+    readonly parentId?: string;
+}
+interface ChildSpec {
+    readonly id: string;
+    readonly mode?: SandboxMode;
+    readonly capabilities?: SandboxCapabilities;
+    /** Boot da child — `BootDefinitions` já compilado. Ausente → child vazia. */
+    readonly definitions?: BootDefinitions<RealmCtx>;
+    /**
+     * Persistência v2 (ADR-034 raiz) — hash do BootDSL fonte. Emitido pelo
+     * compiler do Runtime quando a diretiva `sandbox create` carregava `boot:<DSL>`.
+     * Propagado pra Sandbox child via `SandboxBootOptions.bootSourceKey`. Ausente
+     * quando a child foi criada via JS direto (sem DSL fonte).
+     */
+    readonly bootSourceKey?: SourceKey;
+    readonly bootOptions?: BootOptions;
+}
+/**
+ * Cria + boota uma child sandbox sob `parentId`. Retorna `{ success, errors }`
+ * — o RS agrega `errors` no `BootResult` do parent; o handler `sandbox` adapta
+ * pra `ApplyResult`. Em qualquer falha, a child é disposed (sem órfã).
+ */
+declare function createAndBootChild(manager: ISandboxManager, parentId: string, spec: ChildSpec): {
+    readonly success: boolean;
+    readonly errors: readonly BootError[];
+};
+interface ISandboxManager {
+    /**
+     * Cria + registra Sandbox. Aplica cascade se `parentId` declarado.
+     * Throw em validações (id inválido, duplicado, parent não existe,
+     * cascade violation).
+     */
+    createSandbox(config: ManagerSandboxConfig): ISandbox;
+    /**
+     * **Dynamic Boot** (ADR-035 raiz) — `CompilationService` do environment
+     * compartilhado. Exposto pra handlers que precisam compilar DSL em runtime
+     * (ex.: `sandbox create` com `boot` expression). `undefined` quando o
+     * Manager foi criado sem `environment.compilation` (caminho legado).
+     */
+    readonly compilation?: CompilationService<RealmCtx>;
+    getSandbox(id: string): ISandbox | undefined;
+    getParent(id: string): ISandbox | undefined;
+    getChildren(id: string): readonly ISandbox[];
+    getAncestors(id: string): readonly ISandbox[];
+    getDescendants(id: string): readonly ISandbox[];
+    getDepth(id: string): number;
+    has(id: string): boolean;
+    ids(): readonly string[];
+    readonly size: number;
+    /**
+     * Dispose cascade depth-first. `id` inexistente retorna
+     * `SANDBOX_NOT_FOUND` como dado.
+     */
+    dispose(id: string): SandboxOpResult;
+    /** Dispose tudo. Itera roots; cascade pega children. */
+    clear(): void;
+}
+declare function createSandboxManager(config?: SandboxManagerConfig): ISandboxManager;
+
+/**
+ * Handler `sandbox` — protocolo DSL → JS API entre Sandboxes (ADR-017, ADR-033).
+ *
+ * Injetado pelo Manager em `systemConfig.handlers.sandbox` do RS interno
+ * de cada Sandbox criada. Permite que rules do realm parent comandem
+ * Sandboxes children via diretivas — caminho declarativo equivalente
+ * às chamadas JS `manager.getSandbox(id).app.X()`.
+ *
+ * Owner = parent automático. Handler captura o id da Sandbox dona via
+ * closure. Quando rule emite `{ type: "sandbox", op: "create", id }`,
+ * a child criada vira filha da Sandbox dona — não há `parentId` na
+ * diretiva.
+ *
+ * Erro como dado (ADR-029): `error` é string concisa (code curto);
+ * `data` carrega `SandboxError` estruturado quando aplicável. Catch da
+ * rule dispara em `ok: false`.
+ *
+ * Dual-mode (ADR-032):
+ * - `options.async = false` (default) — `execute` é função sync.
+ *   Apropriado pra ecossistema sync (FPS, game loops). Ops em variantes sync.
+ * - `options.async = true` — `execute` é `async function`. O SDK detecta via
+ *   `isAsyncFunction(execute)`, JIT compila wrapper async per-op. Variantes
+ *   async (`stepAsync`/`processEventsAsync`) preferidas. Apropriado pra
+ *   ecossistema com I/O (ETL, business com fetch/DB).
+ *
+ * Decisão arquitetural: a flag vem do Manager (categoria A — ambient,
+ * viral no ecossistema; ADR-032). Manager async → todas Sandboxes
+ * async; Manager sync → todas sync. Sem mistura no mesmo Manager.
+ *
+ * Diretiva = só **métodos de container/porta** — 8 ops:
+ *   create / step / applyEffect / snapshot / restore / finish / dispose
+ *   processEvents     (governed-only — método do SystemPort)
+ *
+ * Operar recurso interno de uma child (mutar state, invocar action, emitir
+ * evento) NÃO usa esta diretiva — é a diretiva normal do realm com path
+ * prefixado (`{ state: "c/hp", op }`, `{ action: "c/heal", ... }`, `{ emit:
+ * "c/fire", ... }`), processada pelos handlers `crossDispatch`/`crossInvoke`/
+ * `crossEmit` do RS (ADR-074 / §1.7).
+ *
+ * Estrutura modular:
+ * - `handlers/types.ts` — `SandboxDirective` shape
+ * - `handlers/with-child.ts` — wrappers de pre-checks (lookup, liveness, requireSystem)
+ * - `handlers/actions/{lifecycle,runtime,imperative}.ts` — implementação por categoria
+ * - `handlers/dispatch.ts` — `OP_TABLE` unificada sync/async
+ */
+
+interface SandboxDirectiveHandlerOptions {
+    /**
+     * Flag de ecossistema async (ADR-032 — categoria A, ambient). Quando
+     * true, `execute` é `async function` e variantes async são preferidas
+     * pelas actions que oferecem (step/invoke/processEvents). Setado pelo
+     * Manager via `environment.async`.
+     */
+    readonly async?: boolean;
+}
+/**
+ * Cria handler de diretiva `sandbox` ligado a um Manager + um owner.
+ *
+ * Tipo unificado (`HandlerDefinition`) — o actions@0.8.0 consolidou as três
+ * variantes (ver README §Handler Multi-Variant). Overloads narrowem `execute`
+ * sync/async pelo `options.async` pra ergonomia de testes/consumidores.
+ *
+ * @param manager Registry de Sandboxes do ecossistema.
+ * @param ownerSandboxId Id da Sandbox dona deste handler. Children criados
+ *   via diretiva têm essa Sandbox como parent automático.
+ * @param options Flags do ecossistema (ex: `async`).
+ */
+declare function createSandboxDirectiveHandler(manager: ISandboxManager, ownerSandboxId: string, options: SandboxDirectiveHandlerOptions & {
+    async: true;
+}): Omit<HandlerDefinition<RealmCtx>, "execute"> & {
+    execute: AsyncHandlerExecute<RealmCtx>;
+};
+declare function createSandboxDirectiveHandler(manager: ISandboxManager, ownerSandboxId: string, options?: SandboxDirectiveHandlerOptions): Omit<HandlerDefinition<RealmCtx>, "execute"> & {
+    execute: SyncHandlerExecute<RealmCtx>;
+};
+
+export { type CascadeResult, type CascadeViolation, type CascadeViolationKind, type CascadedSandboxCapabilities, type ChildSpec, type IAppPort, type ISandbox, type ISandboxManager, type ISystemPort, type LifecycleHandle, type ManagerSandboxConfig, type PersistCascadeResult, type PersistCascadeViolation, SandboxBootError, type SandboxBootOptions, type SandboxCapabilities, type SandboxChange, type SandboxChangeListener, type SandboxConfig, type SandboxEnvironment, type SandboxError, type SandboxFinishReason, type SandboxLifecycleConfig, type SandboxLookup, type SandboxManagerConfig, type SandboxMode, type SandboxOpResult, type SandboxPersistenceSnapshot, type SandboxResult, type SandboxSnapshot, buildAppPort, buildSystemPort, capabilitiesToPhysics, capabilitiesToSystemConfig, createAndBootChild, createLifecycle, createSandbox, createSandboxDirectiveHandler, createSandboxManager, resolveCascade, resolvePersistCascade };