@loom-forge/forge 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,746 @@
+import { DescriptorRegistry, CommandScope, CommandAlias, EventBinding, DefNode, BindingEngine, ResolveTreeOptions, ResolvedNode } from '@loom-forge/core';
+export { DefNode, Descriptor, DescriptorRegistry, EventBinding, ResolvedNode, createDescriptorRegistry } from '@loom-forge/core';
+import { CycleInfo } from '@tslite/graph';
+export { CycleInfo } from '@tslite/graph';
+
+/** O que se deriva de UM componente. */
+interface ComponentFacts {
+    /** tags próprias — as que o autor declarou, e as que a forma implica. */
+    ownTags: {
+        declared: readonly string[];
+        inferred: readonly string[];
+    };
+    /** arestas de saída por eixo. `contains` fica FORA do `outgoing` (containment ≠ dep). */
+    deps: Readonly<Record<DepAxis, readonly string[]>>;
+}
+/** O que se deriva de UM nó. */
+interface NodeFacts {
+    /** de-para que este nó cria. */
+    edges: readonly IrEdge[];
+    /** comportamento inferido a nível de nó (ex.: `interactive` = tem evento). */
+    tags?: readonly string[];
+}
+/** Referência a um alvo que não existe em registry nenhum. */
+interface DependencyError {
+    componentId: string;
+    code: "UNRESOLVED_TARGET";
+    target: string;
+    axis: DepAxis;
+    message: string;
+}
+interface Facts {
+    /** local, por componente. */
+    components: ReadonlyMap<string, ComponentFacts>;
+    /** local, por nó. */
+    nodes: ReadonlyMap<Address, NodeFacts>;
+    /** `uses ∪ usesRegistered ∪ actions ∪ dataRefs` — o grafo que propaga. */
+    outgoing: ReadonlyMap<string, ReadonlySet<string>>;
+    /** alvos ausentes. Fato ("não existe"), não veredito ("é proibido"). */
+    errors: readonly DependencyError[];
+    /** transitivo: dependentes ("quem usa isto") — por onde o dirty sobe. */
+    incoming?: ReadonlyMap<string, readonly string[]>;
+    /** transitivo: tags efetivas, canônicas (ordenadas, sem repetição). */
+    tags?: ReadonlyMap<string, readonly string[]>;
+    /** transitivo: componentes fortemente conexos. */
+    cycles?: CycleInfo;
+}
+/** Os fatos de um componente, ou `undefined` se ele não está no conjunto. */
+declare const factsOf: (facts: Facts, componentId: string) => ComponentFacts | undefined;
+/** Os fatos de um nó, pelo endereço. */
+declare const nodeFactsOf: (facts: Facts, address: Address) => NodeFacts | undefined;
+/** As tags EFETIVAS (próprias + herdadas) de um nó de grafo. Vazio sem o overlay. */
+declare const effectiveTags: (facts: Facts, id: string) => readonly string[];
+interface DeriveFactsOptions {
+    /** registry de descriptors — own-tags de React registrado (`meta.behavior`) + detecção de ausente. */
+    registry?: DescriptorRegistry;
+    /** tags de uma action externa (via `transparentActionProvider`). Futuro. */
+    actionTags?: (id: string) => readonly string[];
+    /** ids de actions conhecidas — habilita a detecção de ausente no eixo `actions`. */
+    knownActions?: ReadonlySet<string>;
+    /**
+     * O vocabulário de comando que o HOST instala na raiz (o `commands` do `ForgeView`). É a
+     * borda: um nome de comando que chega a um componente que o host monta é resolvido aqui, e,
+     * sem ele, vale como o id que vai para a porta.
+     */
+    commands?: CommandScope;
+    /**
+     * As camadas TRANSITIVAS. Custo zero quando ausentes: quem só quer as arestas locais não
+     * paga o ponto-fixo. Default: todas ligadas (é o que o `buildSystemIR` sempre fez).
+     */
+    overlays?: {
+        tags?: boolean;
+        incoming?: boolean;
+        cycles?: boolean;
+    };
+}
+/**
+ * Deriva os fatos de um conjunto de componentes compilados.
+ *
+ * Tudo sai da árvore normalizada — nenhum dado a mais entra. As camadas locais (arestas, deps,
+ * own-tags) são um salto; as transitivas (tags efetivas, invertido, ciclos) são ponto-fixo sobre
+ * o grafo, que TEM ciclo (um componente compõe outro que o compõe de volta) — daí o
+ * `@tslite/graph`, e não uma ordem topológica.
+ */
+declare function deriveFacts(components: Iterable<ComponentIR>, opts?: DeriveFactsOptions): Facts;
+
+type Address = string;
+declare const componentAddress: (component: string) => Address;
+/** `comp#0` = raiz do corpo; `comp#0.1.2` = caminho de índices de filho a partir da raiz. */
+declare const nodeAddress: (component: string, indexPath: readonly number[]) => Address;
+declare const parseAddress: (addr: Address) => {
+    component: string;
+    path: number[] | null;
+};
+/** Tipo declarado de uma prop/state/context. DADO (shorthand | Schema do TSLite | JSON Schema).
+ *  A resolução p/ Schema do TSLite é do `./check` — o core IR não importa TSLite. */
+type TypeRef = string | Record<string, unknown>;
+type PropsDecl = Record<string, TypeRef>;
+interface StateDecl {
+    type: TypeRef;
+    /**
+     * O que SEMEIA esta chave — expressão sobre `props` e `ctx`, avaliada **uma vez, no mount**.
+     *
+     * É a semântica do `useState(props.x)` do React: lê na montagem e o setter assume dali em
+     * diante. O escopo NÃO tem `state` (é o que está sendo definido) nem `params` (não há
+     * chamada), e o valor é provado contra o `type` declarado ao lado.
+     *
+     * Constante continua constante: `0` atravessa o bind intacto.
+     */
+    init: unknown;
+}
+/** Uma ação de UPDATE local (a DSL de estado, v1): seta campos do estado a valores/expressões
+ *  (`{{ }}` avaliado contra as raízes `props`/`state`/`params`). Vocabulário no espírito das
+ *  directives do statedelta; v1 só `set`. Port-ready: trocar o interpretador é reimplementar
+ *  `applyUpdate`. */
+/**
+ * Um EFEITO — a intenção que um componente dispara por conta própria.
+ *
+ * **É um events-out cujo gatilho é uma mudança de dependência, em vez de um gesto.** Mesma
+ * `action` (local primeiro, senão o `ActionPort` do host), mesmo `params`, mesma aresta no
+ * grafo, mesma tipagem. O que muda é quem puxa o gatilho.
+ *
+ * É o que torna o componente impuro de verdade: quem declara efeito é VIVO, e a tag
+ * `effectful` propaga pelo grafo como qualquer outra.
+ */
+interface EffectDecl {
+    /**
+     * Os CAMINHOS que disparam — `"props.id"`, `"state.aberto"`, `"ctx.tema"`.
+     *
+     * `[]` = só no mount: é a convenção do React, e sem string mágica — sem dependência, não há
+     * o que reexecutar. Caminho pontilhado; nome com ponto dentro não é suportado.
+     */
+    on: string[];
+    /** a intenção: ação LOCAL primeiro, senão o `ActionPort` do host. */
+    action: string;
+    /** os params da intenção — `event` é `undefined` aqui: um efeito não recebe nada (ADR-018). */
+    params?: unknown;
+    /**
+     * A cadeia, como num evento (ADR-018): o `then` roda quando a intenção resolve, com `event` =
+     * o `data` da ação (ou `undefined` depois de um update local); o `catch`, quando o despacho ao
+     * host falha, com `event` = o erro. É por aqui que "carregar no mount" GUARDA o que carregou.
+     */
+    then?: EventBinding;
+    catch?: EventBinding;
+    /** no unmount, e ANTES de reexecutar. Mesma forma de um `EventBinding`, cadeia inclusa. */
+    cleanup?: EventBinding;
+}
+interface UpdateDecl {
+    /** os ARGUMENTOS que este update aceita — os mesmos tipos de uma `PropsDecl`.
+     *
+     *  Sem eles, `params` é dado de fora **não declarado**: vale `unknown`, e escrevê-lo direto
+     *  num estado tipado não passa. Não é aspereza — é a mesma fronteira das props: dado que
+     *  entra sem contrato precisa ser declarado ou provado. Declará-los também tipa o call-site
+     *  do evento que o dispara. */
+    params?: PropsDecl;
+    set?: Record<string, unknown>;
+}
+/** Contrato de um SLOT de composição (children tipado). Um pai declara o que aceita como
+ *  filho — sem conhecer o filho concreto (composição ≠ dependência; o filho é opaco, só o
+ *  CONTRATO é conhecido). Checado no SITE de composição. NOVO vs React (lá todo filho é leaf
+ *  opaco). Eixos ESTRUTURAIS (puros). O eixo de PROPS (`Component<C>` por subtype) é do
+ *  `./check` e vem com a integração do tipo — ver decisão deferida. */
+interface SlotContract {
+    /** o filho deve ter categoria ∈ (declarada do filho). string ou lista. */
+    category?: string | string[];
+    /** o filho deve ter (pelo menos) estas tags de comportamento EFETIVAS (propagadas). */
+    tags?: string[];
+    /** o filho não pode ter filhos próprios no site de composição (deve ser folha). */
+    leaf?: boolean;
+    /** no máximo 1 filho neste slot (não lista). */
+    single?: boolean;
+    /** cardinalidade. */
+    min?: number;
+    max?: number;
+}
+/** Um componente custom declarado em JSON. Isomorfo a uma Action: `id + árvore` (fn JS). */
+interface ComponentDef {
+    /** nome = id do nó de grafo (estável). */
+    component: string;
+    /** público/rota vs privado (sessão interna). Default: false. */
+    entry?: boolean;
+    /** categoria arquitetural (ui/data/feature…) — eixo das regras de direção (fase 2). */
+    category?: string;
+    /** tipos das props que aceita. */
+    props?: PropsDecl;
+    /** os contextos que este componente CONSOME — nomes do catálogo do sistema. É a declaração
+     *  que põe `ctx` no escopo dele: nada entra implicitamente. */
+    context?: {
+        uses: string[];
+    };
+    /** os contextos que este componente PROVÊ para o próprio corpo — `nome → expressão`.
+     *  Açúcar para um `provides` na raiz da árvore: é um mecanismo só, em dois lugares. */
+    provides?: Record<string, unknown>;
+    /** o vocabulário de COMANDOS que este componente instala para o próprio corpo. Mesmo açúcar do
+     *  `provides`, no eixo do comportamento: uma sessão declara os comandos dela aqui. */
+    commands?: Record<string, CommandAlias>;
+    /** estado local declarado, escopado ao componente (NUNCA global). */
+    state?: Record<string, StateDecl>;
+    /** os UPDATES locais (a lógica "suja"): mutam o estado local da instância. Presença de `updates`
+     *  torna o componente VIVO → boundary React por instância; `events.action` resolve LOCAL
+     *  primeiro. NÃO é uma action no sentido do node-actions: não tem id no runtime, não entra em
+     *  palette e não tem disponibilidade. Ver ADR-014. */
+    updates?: Record<string, UpdateDecl>;
+    /** EFEITOS: intenções disparadas por MUDANÇA, não por gesto. Presença também torna o
+     *  componente VIVO — é literalmente o que o torna impuro. */
+    effects?: Record<string, EffectDecl>;
+    /** contratos dos slots de composição (children tipado). Chave = nome do slot ("children"). */
+    slots?: Record<string, SlotContract>;
+    /** tags de comportamento DECLARADAS (own.declared). */
+    tags?: string[];
+    /** gate de capability: `cap → versão | "*"`. */
+    requires?: Record<string, string>;
+    /** o corpo. */
+    body: DefNode;
+    version?: string;
+}
+/** Registry de DEFINIÇÕES de componente custom (SoT). Headless — só ComponentDefs, sem React.
+ *  É o `type → árvore` que a expansão consome no render, e o `names()` alimenta o
+ *  `CompileCtx.components` da análise. Encadeável. */
+interface ComponentDefRegistry {
+    register(def: ComponentDef): ComponentDefRegistry;
+    get(name: string): ComponentDef | undefined;
+    has(name: string): boolean;
+    list(): ComponentDef[];
+    /** os nomes registrados — uso direto como `CompileCtx.components`. */
+    names(): Set<string>;
+}
+declare function createComponentDefRegistry(initial?: ComponentDef[]): ComponentDefRegistry;
+type NodeKind = "component" | "registered" | "element";
+/** Eixos de dependência, separados (§6/decisão #1). `outgoing` = todos MENOS `contains`. */
+type DepAxis = "uses" | "usesRegistered" | "actions" | "dataRefs" | "contains";
+interface IrEdge {
+    to: string;
+    /**
+     * `action` é um id que sai para a aplicação; `update`, uma chamada interna; `command`, um nome
+     * de vocabulário que este documento NÃO resolve — o que ele executa depende de onde o
+     * componente montar, e quem responde é o componente que o monta.
+     */
+    rel: "uses" | "action" | "update" | "command" | "dataref";
+}
+/** O nó normalizado (a "diretiva" endereçável). Molde do GuideNode do overlay. */
+interface NodeIR {
+    address: Address;
+    /** id autorado (estável). */
+    id: string;
+    type: string;
+    kind: NodeKind;
+    /** props com ilhas {{}}/#expr INLINE, não avaliadas (decisão #6). */
+    props?: Record<string, unknown>;
+    events?: Record<string, EventBinding>;
+    layout?: string;
+    /** opaco pro core (lido pelo planner no resolve). */
+    placement?: unknown;
+    /** filhos por ENDEREÇO (flat, não aninhado). */
+    children: Address[];
+    /** each/when (expr inline); a EXPANSÃO acontece no resolve (decisão #6). */
+    template?: {
+        data?: unknown;
+        when?: unknown;
+    };
+    /** contextos que ESTE nó instala para a subárvore (expr inline, como as props). */
+    provides?: Record<string, unknown>;
+    /** o vocabulário de comando que ESTE nó instala para a subárvore. */
+    commands?: Record<string, CommandAlias>;
+    fallback?: "drop";
+    requires?: Record<string, string>;
+}
+/** Nível componente — o nó do grafo. */
+interface ComponentIR {
+    id: string;
+    entry: boolean;
+    /** categoria arquitetural — eixo das regras de direção (fase 2). */
+    category?: string;
+    /** superfície de tipo — formas DECLARADAS (dado). Resolução p/ Schema é do `./check`. */
+    props?: PropsDecl;
+    context: {
+        uses: string[];
+    };
+    /** o que o componente provê ao próprio corpo (`ComponentDef.provides`, inline). */
+    provides?: Record<string, unknown>;
+    /** o vocabulário de comando que o componente instala no próprio corpo (inline). */
+    commands?: Record<string, CommandAlias>;
+    /** os efeitos declarados (inline) — a fonte das arestas de ação de nível componente. */
+    effects?: Record<string, EffectDecl>;
+    /** os updates locais declarados (inline). Autorados, como `state` e `effects`. */
+    updates?: Record<string, UpdateDecl>;
+    state: Record<string, StateDecl>;
+    /** contratos dos slots de composição (children tipado). */
+    slots?: Record<string, SlotContract>;
+    /** tags de comportamento DECLARADAS pelo autor, como ele as escreveu. As PRÓPRIAS
+     *  (declaradas + inferidas) e as EFETIVAS (propagadas) são fato, e moram em `./facts`. */
+    tags?: string[];
+    requires: Record<string, string>;
+    root: Address;
+    nodes: Map<Address, NodeIR>;
+    version?: string;
+}
+interface SystemIR {
+    /** as ÁRVORES normalizadas — só o que o autor escreveu. */
+    components: Map<string, ComponentIR>;
+    /** o que se DERIVOU sobre elas: arestas, deps, tags, ciclos, alvos ausentes. Dois artefatos
+     *  que viajam juntos, não um — ver o cabeçalho de `./facts`. */
+    facts: Facts;
+}
+interface CompileCtx {
+    /** ids de componentes custom conhecidos — classifica `type` como "component". */
+    components: ReadonlySet<string>;
+    /** registry de descriptors — `type` registrado → "registered" (senão "element"). */
+    registry?: DescriptorRegistry;
+}
+/**
+ * Compila UMA definição → `ComponentIR`: a árvore **normalizada** — aninhado vira plano e
+ * endereçável, o `el` é consumido (a tag vira `type`), cada nó é classificado. PURO e
+ * data-independente.
+ *
+ * **Nada derivado sai daqui.** Arestas, deps e tags são FATO, e moram em `./facts` — a árvore
+ * tem o que o autor escreveu, em outra forma. Ver a linha no cabeçalho de `facts.ts`.
+ */
+declare function compileComponent(def: ComponentDef, ctx: CompileCtx): ComponentIR;
+
+/**
+ * Indexa os componentes compilados e **deriva os fatos** sobre eles.
+ *
+ * O artefato tem duas metades que viajam juntas: a árvore (`components`) e o que se calculou
+ * sobre ela (`facts`). Fundir as duas foi o que a decisão #7 do `IR.md` desfez.
+ */
+declare function buildSystemIR(components: Iterable<ComponentIR>, opts?: DeriveFactsOptions): SystemIR;
+
+/** O papel de um campo da definição. */
+type ComponentFieldRole = 
+/** identidade — nunca tocada. */
+"identity"
+/** dado do documento: nome, flag, versão, categoria. Não é código. */
+ | "data"
+/** DECLARAÇÃO de tipo (`PropsDecl`, `SlotContract`) — vocabulário do checker, não expressão. */
+ | "decl"
+/** carrega nó(s) — a árvore, que a tabela do core cobre. */
+ | "tree"
+/** aceita EXPRESSÃO em algum lugar dentro de si — ver `componentSlotsOf`. */
+ | "slot";
+declare const COMPONENT_FIELDS: Readonly<Record<keyof ComponentDef, ComponentFieldRole>>;
+/** Um lugar de expressão fora da árvore. O caminho É o endereço, e é o que evita duas verdades. */
+interface ComponentSlot {
+    /** `["updates", "add", "set"]` — e o endereço reportado é ele, pontilhado. */
+    readonly path: readonly string[];
+    readonly value: unknown;
+}
+/**
+ * O caminho como o autor o lê: `#0.1.props.title` na árvore (a raiz é o nó `0`), `updates.add.set`
+ * fora dela. Derivado — ninguém o lê de volta; quem precisa do caminho guarda a lista.
+ */
+declare const addressOf: (path: CompiledPath) => string;
+/**
+ * Os lugares de expressão de uma definição, FORA da árvore.
+ *
+ * A árvore é do `compile()` da linguagem, que já a percorre pela tabela do core. Isto cobre o
+ * resto — e existe separado porque quem precisa da resposta não é um só: o runtime (para avaliar),
+ * o eject (para traduzir) e a autoria (para diagnosticar no endereço certo).
+ */
+declare function componentSlotsOf(def: ComponentDef): ComponentSlot[];
+/** O caminho de um campo, como lista: índice e chave são distintos no tipo. */
+type CompiledPath = readonly (string | number)[];
+/** Algo que a linguagem endereça num nó: um diagnóstico, uma ilha. O forge só reancora. */
+interface Addressed {
+    /** o caminho a partir da raiz do nó traduzido — `[0, "props", "value", …]` na porta. */
+    readonly path: CompiledPath;
+    /** o caminho como o autor o lê. Derivado do `path`; o forge o reescreve junto. */
+    readonly address: string;
+}
+/**
+ * O que a linguagem devolve ao traduzir um nó: a forma, e — quando ela tem o que dizer — os
+ * diagnósticos e as ilhas dele. Os dois últimos são opcionais porque o port do binder
+ * (`BindingEngine.compile`) fala só `DefNode`: quem traduz pelo port não inventa listas vazias.
+ */
+interface CompiledNode<D extends Addressed = Addressed, I extends Addressed = Addressed> {
+    readonly def: DefNode;
+    readonly diagnostics?: readonly D[];
+    readonly islands?: readonly I[];
+}
+/** Traduz um nó — a metade que a LINGUAGEM sabe fazer, e que entra como função. */
+type CompileNode<D extends Addressed = Addressed, I extends Addressed = Addressed> = (node: DefNode) => CompiledNode<D, I>;
+/** A definição compilada, com o que a linguagem disse sobre ela — na árvore e fora dela. */
+interface CompiledDefinition<D extends Addressed = Addressed, I extends Addressed = Addressed> {
+    readonly def: ComponentDef;
+    /** os da árvore com o endereço de nó (`#0.1.props.x`); os de fora com o caminho do slot
+     *  (`updates.somar.set.n`). */
+    readonly diagnostics: readonly D[];
+    readonly islands: readonly I[];
+}
+/**
+ * O tradutor de um PORT — `BindingEngine.compile`, que fala só `DefNode`. Um por binder, sempre
+ * o mesmo objeto: é o que faz a memória do `compileDefinition` acertar de um render para o outro.
+ * Sem `compile` no port, o nó atravessa como está (a definição já vem compilada, ou ninguém
+ * compila).
+ */
+declare function compileNodeOf(binder: {
+    compile?(node: DefNode): DefNode;
+}): CompileNode;
+/**
+ * A definição COMPILADA: mesma forma, ilhas no lugar do texto — na árvore e fora dela —, com
+ * os diagnósticos e as ilhas que a linguagem devolveu, cada um no endereço do campo que o
+ * produziu.
+ *
+ * Simétrico ao `compile(node)` da linguagem, e o par dos dois é o artefato derivado inteiro. O
+ * SoT continua sendo a definição autorada: esta é recomputada, nunca editada à mão.
+ *
+ * Memoizado por identidade, como o `bodyOf` — montar um objeto novo a cada render derrubaria o
+ * cache de compilação do binder (ADR-109), que é memoizado do mesmo jeito.
+ */
+declare function compileDefinition<D extends Addressed = Addressed, I extends Addressed = Addressed>(def: ComponentDef, compile: CompileNode<D, I>): CompiledDefinition<D, I>;
+
+/** tipo do nó-marcador que a expansão emite no lugar de um componente VIVO; a view o materializa
+ *  num boundary React. Carrega `props: { def, callProps }`. */
+declare const STATEFUL_TYPE = "$stateful";
+/**
+ * Um componente é VIVO (sujo) se tem UPDATES locais ou efeitos.
+ *
+ * Sem nenhum dos dois, o estado nunca muda e nada dispara sozinho → expande estaticamente
+ * (`state.init` entra no escopo, como um componente puro). Com qualquer um, vira boundary React
+ * por instância — e o EFEITO é literalmente o que torna o componente impuro: ele age sem que
+ * ninguém o toque.
+ */
+declare const isLive: (def: ComponentDef) => boolean;
+/**
+ * Estado inicial: o `init` de cada chave, avaliado contra `props` e `ctx`.
+ *
+ * **Uma vez, no mount** — é a semântica do `useState(props.x)` do React, que é o padrão para
+ * SEMEAR: lê a prop na montagem e o setter assume dali em diante. O escopo NÃO tem `state` (é o
+ * que está sendo definido) nem `params` (não há chamada).
+ *
+ * Um `init` constante atravessa o bind intacto, então declarar `0` continua sendo `0`.
+ */
+declare const initState: (def: ComponentDef, scope: Readonly<Record<string, unknown>>, binder: BindingEngine) => Record<string, unknown>;
+/** Avalia um payload (os `params` de um efeito, de um cleanup) contra o escopo. */
+declare const bindPayload: (params: unknown, scope: Record<string, unknown>, binder: BindingEngine) => unknown;
+/**
+ * Aplica um update ao estado: avalia as expressões do `set` contra o escopo
+ * (`{...props, ...state, ...params}`) e devolve o novo estado (merge imutável, PARCIAL).
+ *
+ * É o port: o v1 é `set`; um interpretador de directives entra aqui.
+ */
+declare const applyUpdate: (prev: Record<string, unknown>, update: UpdateDecl, scope: Record<string, unknown>, binder: BindingEngine) => Record<string, unknown>;
+
+interface SlotViolation {
+    rule: "slot-cardinality" | "slot-leaf" | "slot-category" | "slot-tags";
+    /** o COMPOSITOR (componente onde o pai foi usado com filhos). */
+    componentId: string;
+    /** tipo do nó-pai cujo slot foi violado. */
+    parent: string;
+    /** nome do slot ("children"). */
+    slot: string;
+    /** tipo do filho infrator (quando aplicável). */
+    child?: string;
+    message: string;
+}
+interface CheckSlotsOptions {
+    /** registry de descriptors — slots/categoria/behavior de React registrado (via `meta`). */
+    registry?: DescriptorRegistry;
+}
+/**
+ * Valida cada SITE de composição contra o contrato de slot do pai. Caminha todos os nós de
+ * todos os componentes; quando um nó (cujo `type` declara slots) tem filhos, confere-os.
+ * Pai/filho podem ser custom (IR) ou React registrado (via `descriptor.meta`).
+ */
+declare function checkSlots(sys: SystemIR, opts?: CheckSlotsOptions): SlotViolation[];
+
+/** O que o documento instala num ponto da árvore, acima do que chega de fora. */
+interface MountScope {
+    /** os contextos providos — só o nome: o tipo é do catálogo, e o valor é de runtime. */
+    contexts: ReadonlySet<string>;
+    /** o vocabulário de comando, com o mais próximo já vencendo. */
+    commands: CommandScope;
+}
+/** a raiz de um componente: nada do documento ainda — tudo o que vale ali veio de fora. */
+declare const EMPTY_MOUNT: MountScope;
+/** A montagem de um SISTEMA de definições — o que cada componente instala nos próprios slots. */
+interface Mounting {
+    /**
+     * Os escopos em que os filhos de slot de um componente MONTAM, relativos ao nó de chamada —
+     * um por `$slot`. `[]` quando eles não montam em lugar nenhum; `undefined` quando o `type`
+     * não é componente deste sistema, e aí não há slot: os filhos são filhos comuns.
+     */
+    slotScopesOf(component: string): readonly MountScope[] | undefined;
+    /**
+     * Os nomes que ALGUM vocabulário do sistema declara. Um nome livre que não está aqui só pode
+     * chegar à porta; um que está depende de onde o componente montar.
+     */
+    readonly vocabulary: ReadonlySet<string>;
+}
+/**
+ * A montagem de um conjunto de componentes: onde cada um monta os filhos de slot, e que nomes
+ * algum vocabulário declara. `host` é o vocabulário que a aplicação instala na raiz.
+ */
+declare function mountingOf(components: Iterable<ComponentIR>, opts?: {
+    host?: CommandScope;
+}): Mounting;
+/** Os escopos de montagem de cada nó de uma árvore `DefNode`, por identidade do nó. */
+declare function mountScopesOf(root: DefNode, mounting: Pick<Mounting, "slotScopesOf">): Map<DefNode, readonly MountScope[]>;
+
+/** O catálogo de contextos do sistema: `nome → tipo`. O nome é NOMINAL (com namespace
+ *  quando o componente cruza a fronteira do app); o tipo é global, e o valor é posicional. */
+type ContextCatalog = Record<string, TypeRef>;
+interface ContextFacts {
+    /** por componente: o que ele exige de FORA — o próprio, mais o que escapou dos filhos. */
+    required: ReadonlyMap<string, readonly string[]>;
+    /**
+     * por nó: o que estava provido naquele ponto, contando o que o próprio nó instala. É o que o
+     * painel mostra ao selecionar. Um nó que monta em mais de um lugar mostra o que TODOS os
+     * pontos proveem; um nó que não monta não aparece.
+     */
+    providedAt: ReadonlyMap<Address, readonly string[]>;
+    /** por nó de CHAMADA: o que o chamado exige e não estava provido ali — o que escapa. */
+    unsatisfiedAt: ReadonlyMap<Address, readonly string[]>;
+}
+/**
+ * Deriva, para cada componente, o que ele exige de fora — e por qual nó cada exigência
+ * escapou.
+ *
+ * Um componente que PROVÊ um nome não precisa dele de fora: `uses ∖ provides`. As duas
+ * declarações têm direções diferentes (o que preciso × o que dou), e quando coincidem o
+ * autor está dizendo que se basta.
+ */
+declare function deriveContext(components: Iterable<ComponentIR>): ContextFacts;
+
+/** O que uma intenção executa, visto de UM lugar onde ela monta. */
+type IntentRoute = 
+/** chamada interna: um update do componente que escreveu a intenção. */
+{
+    kind: "update";
+    action: string;
+    bound?: unknown;
+}
+/** um id que sai para a aplicação. */
+ | {
+    kind: "action";
+    action: string;
+    bound?: unknown;
+}
+/** um nome de vocabulário que este lugar não resolve: depende de onde o componente monta. */
+ | {
+    kind: "command";
+    name: string;
+};
+/** O que a rota precisa saber do componente e do sistema. */
+interface RouteContext {
+    /** os updates do componente que ESCREVEU a intenção. */
+    updates: ReadonlySet<string>;
+    /** os nomes que algum vocabulário do sistema declara — ver `Mounting.vocabulary`. */
+    vocabulary: ReadonlySet<string>;
+}
+/**
+ * A rota de UMA intenção num lugar de montagem — os três degraus da expansão, sobre nomes.
+ *
+ * `bound` são os params que um alias já liga (a aplicação parcial): o disparo os recebe por baixo
+ * dos seus, e quem prova ou traduz a chamada precisa deles.
+ */
+declare function routeIntent(action: string, scope: MountScope, ctx: RouteContext): IntentRoute;
+/**
+ * A rota de uma intenção quando TODO lugar onde ela monta concorda.
+ *
+ * `undefined` quando ela não monta em lugar nenhum, ou quando dois lugares a resolvem de jeitos
+ * diferentes — aí não há UMA ação contra a qual provar ou para a qual traduzir.
+ */
+declare function settledRoute(action: string, scopes: readonly MountScope[], ctx: RouteContext): IntentRoute | undefined;
+interface CommandFacts {
+    /** por nó: o que cada intenção dele executa, em cada lugar onde ele monta. */
+    intentsAt: ReadonlyMap<Address, readonly IrEdge[]>;
+    /** por componente: os ids de ação que ele roteia para a aplicação. */
+    actions: ReadonlyMap<string, ReadonlySet<string>>;
+    /** por componente: os nomes de comando que escapam dele — quem resolve é quem o monta. */
+    free: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Deriva o roteamento de todas as intenções de um conjunto de componentes.
+ *
+ * `host` é o vocabulário que a aplicação instala na raiz — o `commands` do `ForgeView`.
+ */
+declare function deriveCommands(components: Iterable<ComponentIR>, mounting: Mounting, host?: CommandScope): CommandFacts;
+
+interface RuleViolation {
+    /** id da regra (`category-policy` / `route-entry` / `forbidden-tag`…). */
+    rule: string;
+    /** componente infrator. */
+    componentId: string;
+    message: string;
+    data?: Record<string, unknown>;
+}
+type Decision = "allow" | "deny";
+/** Categoria de um nó de grafo: custom via `ComponentIR.category`; registrado via
+ *  `descriptor.meta.category` (declarado, confiável — não se infere de React). */
+type CategoryResolver = (id: string) => string | undefined;
+declare function categoryOf(sys: SystemIR, registry?: DescriptorRegistry): CategoryResolver;
+interface CategoryPolicy {
+    categoryOf: CategoryResolver;
+    /** matriz por categoria: `matrix[from][to]` = allow|deny. */
+    matrix: Record<string, Record<string, Decision>>;
+    /** decisão quando o par não está na matriz (default: `allow` — estilo deny-list). */
+    defaultPolicy?: Decision;
+}
+/**
+ * Regra arquitetural POR ARESTA (categoria/direção): "UI pode usar Data, Data não pode usar
+ * UI". Caminha o `outgoing` (componente compõe componente/registrado); pares sem categoria
+ * são ignorados. Sem propagação — só a aresta direta (igual `analysis.policies`).
+ */
+declare function checkCategoryPolicy(sys: SystemIR, policy: CategoryPolicy): RuleViolation[];
+interface UnableSources {
+    /** capabilities indisponíveis — um componente que as `requires` fica unable. */
+    capabilities?: ReadonlySet<string>;
+    /** actions indisponíveis — um componente que as invoca fica unable. */
+    actions?: ReadonlySet<string>;
+    /** componentes explicitamente indisponíveis. */
+    components?: Iterable<string>;
+    /**
+     * A PORTA de ação — quem sabe o que pode rodar AGORA (o `isAvailable` do Tier 1).
+     *
+     * Com ela, ninguém precisa montar a lista de indisponíveis à mão: pergunta-se por ação que o
+     * grafo de fato invoca. Uma porta sem `isAvailable` não torna nada unable — não saber não é
+     * saber que não.
+     *
+     * **É um retrato, não uma assinatura.** Disponibilidade muda em runtime (cota, permissão,
+     * provider caído) e isto é análise do relógio LENTO: quem quiser acompanhar, recomputa.
+     */
+    port?: {
+        isAvailable?(id: string): boolean;
+    };
+}
+/**
+ * Availability/unable TRANSITIVO: a partir das fontes off, marca todo componente que delas
+ * depende — o Razor das Actions. Capability/action off → o componente que as exige/invoca é
+ * fonte; e todo dependente herda `unable`.
+ */
+declare function computeUnable(sys: SystemIR, off: UnableSources): Set<string>;
+/**
+ * Um id REPETIDO no documento de um componente.
+ *
+ * O id é a identidade do nó: é por ele que o editor muta, que o patch acha o alvo e que a tela
+ * liga o foco ao documento. Dois nós com o mesmo id fazem os três apontarem para o primeiro — e
+ * nada falha na hora, porque a árvore renderiza igual. O escopo é o DOCUMENTO: componentes
+ * diferentes repetem id à vontade, e a expansão os separa por instância.
+ */
+declare function checkIdentity(sys: SystemIR): RuleViolation[];
+/**
+ * Um componente no escopo não pode ter nenhuma das tags proibidas (efetivas/propagadas).
+ * Ex.: páginas (entry) não podem ser `unsafe` → `checkForbiddenTags(sys, ["unsafe"], c => c.entry)`.
+ * É a prova de que "tag declarada propaga aos dependentes e as regras caem sobre o propagado".
+ */
+declare function checkForbiddenTags(sys: SystemIR, forbidden: Iterable<string>, scope?: (comp: ComponentIR) => boolean): RuleViolation[];
+interface ContextIssue extends RuleViolation {
+    rule: "context-undeclared" | "context-unsatisfied" | "context-unused";
+    /** os nomes em questão. É o dado que a correção usa para agir sem adivinhar. */
+    data: {
+        contexts: string[];
+        node?: string;
+    };
+}
+interface CheckContextsOptions {
+    /** os contextos que o HOST provê de ambiente (`auth`, `route`…). Um componente `entry`
+     *  que exija algo fora disto não tem onde viver: é a fronteira da prova. */
+    ambient?: Iterable<string>;
+}
+/**
+ * Julga o que a análise de contexto derivou. A assimetria é a de sempre — **você só pode ser
+ * contrariado se tiver afirmado**:
+ *
+ * | declarou MENOS que a realidade | mentira → erro     |
+ * | declarou MAIS                  | desperdício → warning |
+ * | não declarou                   | a inferência decide |
+ *
+ * O erro aponta o NÓ por onde a exigência escapou, e carrega os nomes: promover a obrigação
+ * para o componente de cima é correção mecânica, e quem conserta não deve ter de re-derivar.
+ */
+declare function checkContexts(sys: SystemIR, ctx: ContextFacts, opts?: CheckContextsOptions): ContextIssue[];
+interface EffectIssue extends RuleViolation {
+    rule: "effect-loop";
+    data: {
+        effect: string;
+        action: string;
+        paths: string[];
+    };
+}
+/**
+ * Um efeito que ESCREVE o que ele OBSERVA é laço infinito — e aqui dá para provar sem rodar,
+ * porque os dois lados são declarados: o `on` diz o que ele observa, e o `set` da ação local
+ * diz o que ele escreve.
+ *
+ * O React só descobre isso em runtime, com o navegador travado. Nós descobrimos porque o
+ * programa é dado.
+ *
+ * Só ação LOCAL é julgada: o que o `ActionPort` do host faz com o estado dele não é daqui.
+ */
+declare function checkEffects(sys: SystemIR): EffectIssue[];
+
+declare const bodyOf: (def: ComponentDef) => DefNode;
+interface ExpandOptions {
+    /** boundary de entrada: componente custom PRIVADO entrado como RAIZ não expande → `unknown`. */
+    requireEntryRoot?: boolean;
+    /** os contextos de AMBIENTE — o que o host provê na raiz (`auth`, `route`…). É a fronteira
+     *  declarada: dentro da árvore a prova é total, na borda ela depende disto. */
+    contexts?: Readonly<Record<string, unknown>>;
+    /** o vocabulário de comando da RAIZ — o que a aplicação instala antes de qualquer sessão. */
+    commands?: CommandScope;
+    /**
+     * Os UPDATES do componente cujo corpo É esta raiz — só existe quando quem expande é o boundary
+     * de um componente vivo.
+     *
+     * Um nome que resolve aqui é chamada interna e não passa pelo escopo de comando. Sem isto, um
+     * alias de fora com o mesmo nome reescreveria o update local — e o boundary é o ÚNICO lugar onde
+     * updates existem, porque ter update é o que torna o componente vivo.
+     */
+    updates?: ReadonlySet<string>;
+    /** o componente cujo corpo É esta raiz — o boundary de um componente vivo o informa, para que os
+     *  nós do corpo mantenham a origem. Ausente, a raiz é do host. */
+    component?: string;
+}
+/**
+ * Expande os componentes custom de `root` (árvore já data-bound) numa árvore PURA de `DefNode`.
+ * `system` = registry de definições; `binder` = pra ligar o corpo de cada componente.
+ */
+declare function expandComponents(root: DefNode, system: ComponentDefRegistry, binder: BindingEngine, opts?: ExpandOptions): DefNode;
+interface ResolveComponentTreeOptions extends ResolveTreeOptions {
+    /** registry de definições de componente custom. Ausente → nenhum `type` é custom, e a expansão
+     *  só consome as diretivas de escopo. */
+    componentDefs?: ComponentDefRegistry;
+    requireEntryRoot?: boolean;
+    /** os contextos de AMBIENTE que o host provê na raiz. Ver `ExpandOptions.contexts`. */
+    contexts?: Readonly<Record<string, unknown>>;
+    /** o vocabulário de comando da RAIZ — repassado à expansão. */
+    commands?: CommandScope;
+    /** os updates do componente cujo corpo é esta raiz. Ver `ExpandOptions.updates`. */
+    updates?: ReadonlySet<string>;
+    /** o componente cujo corpo é esta raiz. Ver `ExpandOptions.component`. */
+    component?: string;
+}
+/**
+ * Render do construtor: `bind` (dados) → `expand` (componentes custom → árvore pura) →
+ * `resolveTree` (compositor, com `identityBinder` — a árvore já está ligada). É o que o
+ * `@loom-forge/forge-react` usa por baixo; também serve headless.
+ *
+ * **A expansão roda SEMPRE, mesmo sem `componentDefs`.** Ela não é só "trocar custom por corpo":
+ * é também onde as diretivas de ESCOPO são consumidas — o `provides` e o `commands`. Uma árvore
+ * só de componentes registrados e `el` continua tendo sessão, contexto e vocabulário de comando,
+ * e sem esta passada eles ficariam declarados e inertes, em silêncio. Sem definição nenhuma o
+ * custo é um walk, e nenhum id muda (o prefixo só cresce quando um custom é expandido).
+ */
+declare function resolveComponentTree(node: DefNode, opts: ResolveComponentTreeOptions, data?: unknown): ResolvedNode;
+
+export { type Address, type Addressed, type DeriveFactsOptions as BuildSystemOptions, COMPONENT_FIELDS, type CategoryPolicy, type CategoryResolver, type CheckContextsOptions, type CheckSlotsOptions, type CommandFacts, type CompileCtx, type CompileNode, type CompiledDefinition, type CompiledNode, type CompiledPath, type ComponentDef, type ComponentDefRegistry, type ComponentFacts, type ComponentFieldRole, type ComponentIR, type ComponentSlot, type ContextCatalog, type ContextFacts, type ContextIssue, type Decision, type DepAxis, type DependencyError, type DeriveFactsOptions, EMPTY_MOUNT, type EffectDecl, type EffectIssue, type ExpandOptions, type Facts, type IntentRoute, type IrEdge, type MountScope, type Mounting, type NodeFacts, type NodeIR, type NodeKind, type PropsDecl, type ResolveComponentTreeOptions, type RouteContext, type RuleViolation, STATEFUL_TYPE, type SlotContract, type SlotViolation, type StateDecl, type SystemIR, type TypeRef, type UnableSources, type UpdateDecl, addressOf, applyUpdate, bindPayload, bodyOf, buildSystemIR, categoryOf, checkCategoryPolicy, checkContexts, checkEffects, checkForbiddenTags, checkIdentity, checkSlots, compileComponent, compileDefinition, compileNodeOf, componentAddress, componentSlotsOf, computeUnable, createComponentDefRegistry, deriveCommands, deriveContext, deriveFacts, effectiveTags, expandComponents, factsOf, initState, isLive, mountScopesOf, mountingOf, nodeAddress, nodeFactsOf, parseAddress, resolveComponentTree, routeIntent, settledRoute };