@semacode/cli 1.5.17 → 1.5.18

package/docs/pagamento-ponta-a-ponta.md

@@ -5,12 +5,16 @@ Este documento descreve o vertical oficial de pagamento da Sema no fluxo publico
 O objetivo nao e mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem ja consegue modelar um fluxo de negocio real com:
 
 - contrato publico
+- seguranca e autorizacao
+- classificacao de dados
+- segredos e proibicoes explicitas
 - regras
 - efeitos operacionais
+- execucao, idempotencia, retry e compensacao
 - transicoes de estado
 - orquestracao
 - erros publicos
-- testes executaveis
+- testes executaveis com saida, status ou erro observavel
 
 ## Arquivos de referencia
 
@@ -62,12 +66,16 @@ E expoe:
 
 A `task processar_pagamento` faz o trabalho central:
 
+- exige `authz`
+- classifica `dados`
+- declara `segredos`, `audit` e `forbidden`
 - valida entrada
 - consulta o gateway
 - persiste o pagamento
 - emite evento
 - notifica comprovante
 - registra auditoria
+- declara `execucao` com idempotencia, timeout, retry, compensacao e criticidade
 - garante consistencia da saida
 
 ### Estado e transicoes
@@ -146,9 +154,11 @@ sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamen
 Se esse vertical passa, a Sema ja consegue demonstrar que:
 
 - modela contrato publico
+- modela superficie sensivel sem deixar seguranca invisivel
 - modela efeitos operacionais
 - modela falhas reais
 - modulariza dominio com `use`
+- declara idempotencia e execucao critica sem criar sintaxe nova
 - gera artefatos coerentes para TypeScript e Python
 - executa testes gerados sem gambiarra conceitual
 

package/docs/persistencia-vendor-first.md

@@ -1,6 +1,6 @@
 # Persistencia Vendor-First
 
-Sema 1.5.7 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, no IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` tambem materializa persistencia local real em `Preferences`, `localStorage` e `sessionStorage` quando a task esta ancorada no arquivo que usa essas APIs.
+Sema 1.5.18 trata banco como superficie semantica de primeira classe. Isso significa assumir diferencas reais entre engines e coloca-las no contrato, no semantico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` tambem materializa persistencia local real em `Preferences`, `localStorage` e `sessionStorage` quando a task esta ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
 
 ## Engines publicas
 

package/docs/prompt-base-ia-sema.md

@@ -2,18 +2,18 @@
 
 Este arquivo serve como prompt-base oficial para qualquer IA que precise ler, escrever, revisar ou transformar arquivos `.sema`.
 
-O objetivo nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA.
+O objetivo nao e fazer a IA "improvisar bonito". O objetivo e fazer a IA operar a linguagem com previsibilidade. A Sema nao foi desenhada para ergonomia humana como prioridade; ela foi desenhada para IA. Humanos escrevem, revisam e aprovam; o consumidor primario e o agente.
 
 ## Prompt-base
 
 Use o texto abaixo como base:
 
 ```text
-Voce esta trabalhando com Sema, um Protocolo de Governanca de Intencao para IA e backend vivo.
+Voce esta trabalhando com Sema, um contrato semantico IA-first para agentes operarem software vivo.
 
-Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e reduzir ambiguidade para IA, nao para substituir arquitetura, design ou curadoria humana.
+Tecnicamente, a Sema funciona como linguagem de intencao orientada a contrato. Operacionalmente, ela existe para governar semantica acima da stack e traduzir intencao operacional para IA, nao para substituir arquitetura, design ou aprovacao humana.
 
-Trate a Sema como linguagem de especificacao executavel e protocolo de governanca semantica. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
+Trate a Sema como contrato semantico executavel e protocolo de governanca IA-first. Nao invente sintaxe, palavras-chave ou blocos fora da gramatica e dos exemplos oficiais.
 
 Fontes de verdade, em ordem:
 1. se o projeto expuser `SEMA_CONTEXT.md`, comece por ele
@@ -31,6 +31,7 @@ Regras de operacao:
 - use o formatador oficial da Sema como fonte unica de estilo
 - use diagnosticos estruturados como contrato de correcao
 - use a IR como fonte de verdade semantica quando houver duvida
+- use `predicadoCanonico` como normalizacao opcional; preserve o `predicado` original
 - nao conclua uma alteracao sem validar e verificar o modulo
 - trate `importar` como bootstrap revisavel, nao como contrato final automatico
 - trate `drift` como medicao de verdade contra codigo vivo
@@ -58,7 +59,7 @@ Se algo nao estiver claro, siga a forma ja usada nos exemplos oficiais. Nao impr
 Se voce quiser um prompt menor para uso frequente:
 
 ```text
-Trabalhe com Sema como DSL semantica orientada a contrato. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
+Trabalhe com Sema como contrato semantico IA-first orientado a agente. Nao invente sintaxe. Use os exemplos oficiais e a gramatica como referencia de escrita. Use `ir --json` como fonte de verdade semantica, `diagnosticos --json` como fonte de correcao e `sema formatar` como fonte unica de estilo. Antes de encerrar, rode validacao e verificacao.
 ```
 
 Se voce quiser um prompt ainda mais curto e pronto para colar, use:

package/docs/rollback.md

@@ -20,7 +20,7 @@ npm dist-tag add @semacode/mcp@<versao-boa> latest
 ```
 
 3. Se o problema for so VSIX ou asset de release, substitua o asset no GitHub Release ou publique uma release patch.
-4. Prefira publicar patch corretivo (`1.5.10`, por exemplo) quando o pacote ja saiu para usuarios.
+4. Prefira publicar patch corretivo (`1.5.18`, por exemplo) quando o pacote ja saiu para usuarios.
 
 ## Validacao de rollback
 

package/docs/sintaxe.md

@@ -1,410 +1,212 @@
-# Sintaxe Canonica
-
-A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no contexto de IA.
-
-## Regras basicas
-
-- um arquivo `.sema` contem um `module` principal
-- cada bloco abre com palavra-chave e fecha com `}`
-- campos usam `nome: valor`
-- blocos declarativos podem aparecer aninhados quando o contrato exigir
-- `tests` usa blocos `caso`
+# Sintaxe Canonica
+
+A Sema usa blocos declarativos previsiveis para reduzir ambiguidade no parser, na IR, no drift e no contexto de IA. A escrita humana pode ser legivel, mas o alvo principal da sintaxe e gerar contrato consumivel por agente.
+
+## Regras basicas
+
+- um arquivo `.sema` contem um `module` principal
+- cada bloco abre com palavra-chave e fecha com `}`
+- campos usam `nome: valor`
+- blocos declarativos podem aparecer aninhados quando o contrato exigir
+- `tests` usa blocos `caso`
+
+## Blocos de primeira classe
+
+- `module`
+- `use`
+- `database`
+- `type`
+- `entity`
+- `enum`
+- `state`
+- `task`
+- `flow`
+- `route`
+- `worker`
+- `evento`
+- `fila`
+- `cron`
+- `webhook`
+- `cache`
+- `storage`
+- `policy`
+- `tests`
+- `docs`
+- `comments`
+
+## Subblocos comuns
+
+- `input`
+- `output`
+- `rules`
+- `effects`
+- `auth`
+- `authz`
+- `dados`
+- `audit`
+- `segredos`
+- `forbidden`
+- `impl`
+- `vinculos`
+- `execucao`
+- `guarantees`
+- `error`
+- `fields`
+- `invariants`
+- `transitions`
+- `given`
+- `when`
+- `expect`
 
-## Blocos de primeira classe
+## Tipos primitivos
 
-- `module`
-- `use`
-- `database`
-- `type`
-- `entity`
-- `enum`
-- `state`
-- `book`
-- `work`
-- `part`
-- `chapter`
-- `section`
-- `scene`
-- `character`
-- `arc`
-- `audience`
-- `thesis`
-- `argument`
-- `claim`
-- `source`
-- `concept`
-- `example`
-- `voice`
-- `style_rule`
-- `lexicon`
-- `motif`
-- `canon`
-- `agent`
-- `task`
-- `flow`
-- `route`
-- `worker`
-- `evento`
-- `fila`
-- `cron`
-- `webhook`
-- `cache`
-- `storage`
-- `policy`
-- `tests`
-- `docs`
-- `comments`
+Tipos primitivos reconhecidos diretamente:
 
-## Subblocos comuns
+- `Texto`
+- `Numero`
+- `Inteiro`
+- `Decimal`
+- `Booleano`
+- `Data`
+- `Timestamp`
+- `Objeto`
+- `Id`
+- `Email`
+- `Json`
 
-- `input`
-- `output`
-- `rules`
-- `effects`
-- `auth`
-- `authz`
-- `dados`
-- `audit`
-- `segredos`
-- `forbidden`
-- `impl`
-- `vinculos`
-- `execucao`
-- `guarantees`
-- `error`
-- `fields`
-- `invariants`
-- `transitions`
-- `given`
-- `when`
-- `expect`
+`Timestamp` e `Objeto` funcionam como aliases primitivos suportados e preservam o texto original na IR.
 
 ## Tipos compostos
-
-```sema
-input {
-  ids: Lista<Id> required
-  metadata: Mapa<Texto, Texto>
-  responsavel: Opcional<Usuario>
-  chave_publica: Texto|Id
-}
-```
-
+
+```sema
+input {
+  ids: Lista<Id> required
+  metadata: Mapa<Texto, Texto>
+  responsavel: Opcional<Usuario>
+  chave_publica: Texto|Id
+}
+```
+
 Formas suportadas:
-
-- `Lista<T>`
-- `Mapa<K, V>`
-- `Opcional<T>`
-- `T1|T2`
+
+- `Lista<T>`
+- `Mapa<K, V>`
+- `Opcional<T>`
+- `T1|T2`
 - `T?`
 
-## Profiles Author e Agents
-
-O profile Author modela obra autoral, nao apenas romance. Ele pode descrever ficcao, nao-ficcao, livro tecnico, ensaio, manual, biografia, pesquisa narrada, curso em formato de livro ou manifesto. A ideia e governar intencao, publico, promessa, voz, estrutura, argumentos, fontes, continuidade e regras de estilo.
-
-Blocos Author suportados:
-
-- `book` ou `work`: obra inteira
-- `part`, `chapter`, `section`: estrutura editorial
-- `scene`, `character`, `arc`: narrativa quando a obra tiver ficcao ou relato
-- `audience`, `thesis`, `argument`, `claim`, `source`, `concept`, `example`: nao-ficcao, ensino, pesquisa e argumentacao
-- `voice`, `style_rule`, `lexicon`, `motif`, `canon`: voz, vocabulario, repeticoes, proibicoes e continuidade
-
-`style_rule` aceita subblocos livres como `proibido`, `evitar`, `ecos`, `preferir`, `require` e `tolerancia`. Isso cobre frases cliches, muletas, ecos repetidos e limites de repeticao sem prender a linguagem a um genero literario.
-
-Todo modulo com blocos Author tambem recebe no IR a regra sintetica `regras_gerais_author`. Ela aplica automaticamente o piso editorial geral: mostrar por evidencia, causa e consequencia, cena com dupla funcao, exposicao com atrito, dialogo com subtexto, final sem slogan, morte com peso estrutural, especificidade sensorial, voz distinta e anti-cliche adaptativa. Regras locais da obra podem ser mais fortes, mas nao devem apagar esse piso.
-
-Quando a obra declara um tema sensivel ou factual, como `autismo`, `saude`, `diagnostico`, `neurodiversidade`, `educacao inclusiva`, `juridico` ou `financeiro`, o contrato deixa de ser apenas orientativo. A validacao exige `book/work`, `audience`, `claim`, `source`, `style_rule`, `agent` e um `flow` chamando esse agent. Claims sensiveis precisam declarar `source/fonte/evidencia` e `confidence/confianca`.
-
-```sema
-module livro.tecnico.ia {
-  work protocolo_ia {
-    titulo: "Sistemas para IA"
-    proposito: "ensinar governanca de agentes"
-    tipo: nao_ficcao
-  }
-
-  audience devs {
-    nivel: intermediario
-    promessa: "sair com um protocolo aplicavel"
-  }
-
-  claim contratos_reduzem_adivinhacao {
-    source: pesquisa_interna
-    confidence: media
-  }
-
-  voice didatica {
-    tom: claro
-    ritmo: progressivo
-  }
-
-  style_rule anti_texto_raso {
-    proibido {
-      frase: "de alguma forma"
-      cliche: "o tempo parecia parar"
-    }
-    ecos {
-      palavra: "eco"
-    }
-    tolerancia {
-      max_repeticao_palavra_por_trecho: 2
-    }
-  }
-
-  agent revisor_estilo {
-    role: editor_author
-    goal: cortar_cliche_e_eco
-    tools {
-      ler_contrato
-      analisar_trecho
-    }
-    memory {
-      canon
-      style_rule
-    }
-    policy {
-      nao_reescrever_sem_aprovacao
-      citar_trechos_afetados
-    }
-  }
-
-  flow revisar_secao {
-    trecho: Texto
-    etapa estilo usa revisor_estilo com trecho = trecho
-  }
-}
-```
-
-`agent` e bloco de primeira classe. Um agent precisa declarar ao menos `role`/`goal`, `tools` e `policy`; `memory` gera aviso quando ausente, porque agente sem memoria declarada tende a improvisar contexto.
-
-Exemplo de obra sensivel:
-
-```sema
-module livro.autismo {
-  work guia_autismo {
-    titulo: "Autismo sem reducionismo"
-    proposito: "orientar familias sem substituir avaliacao clinica"
-    tema: autismo
-    sensivel: verdadeiro
-  }
-
-  audience familias_e_educadores {
-    publico: pais_educadores_pessoas_autistas
-    limites: "nao substitui avaliacao clinica"
-  }
-
-  claim autismo_e_espectro {
-    texto: "autismo e um espectro com manifestacoes variadas"
-    source: dsm5_tr
-    confidence: alta
-  }
-
-  source dsm5_tr {
-    tipo: referencia_clinica
-    confianca: alta
-  }
-
-  style_rule linguagem_respeitosa {
-    proibido {
-      generalizacao: "todo autista"
-      infantilizacao: "anjinho especial"
-      promessa: "cura garantida"
-    }
-    evitar {
-      frase: "superar o autismo"
-    }
-  }
-
-  agent checador_sensibilidade {
-    role: revisor_sensibilidade
-    goal: checar_fontes_linguagem_e_generalizacoes
-    tools {
-      ler_contrato
-      verificar_claim
-      revisar_trecho
-    }
-    memory {
-      source
-      style_rule
-      audience
-    }
-    policy {
-      nao_diagnosticar
-      nao_prometer_tratamento
-      citar_trechos_afetados
-    }
-  }
-
-  flow revisar_capitulo {
-    trecho: Texto
-    etapa sensibilidade usa checador_sensibilidade com trecho = trecho
-  }
-}
-```
-
-## Persistencia vendor-first
-
-O bloco `database` modela banco e recursos persistidos sem apagar as diferencas entre engines.
-
-Estrutura base:
-
-```sema
-database principal_postgres {
-  engine: postgres
-  consistency: forte
-  durability: alta
-  transaction_model: mvcc
-  query_model: sql
-}
-```
-
-Recursos canonicamente suportados:
-
-- `table`
-- `index`
-- `relationship`
-- `query`
-- `retention`
-- `lock`
-- `replication`
-- `collection`
-- `document`
-- `keyspace`
-- `stream`
-- `capabilities`
-
-Exemplo relacional:
-
-```sema
-database principal_postgres {
-  engine: postgres
-  schema: public
-  capabilities {
-    joins
-    views
-    foreign_keys
-  }
-  table pedidos {
-    entity: Pedido
-  }
-  relationship pedido_cliente {
-    from: Pedido
-    to: Cliente
-  }
-  query buscar_pedidos {
-    mode: sql
-  }
-}
-```
-
-Exemplo documental:
-
-```sema
-database principal_mongodb {
-  engine: mongodb
-  query_model: documento
-  collection pedidos {
-    collection: pedidos
-  }
-  document pedido_snapshot {
-    entity: PedidoSnapshot
-  }
-  query pipeline_pedido {
-    mode: pipeline
-  }
-}
-```
-
-Exemplo key-value:
-
-```sema
-database principal_redis {
-  engine: redis
-  query_model: chave_valor
-  keyspace cache_pedidos {
-    ttl: "300s"
-  }
-  stream eventos_pedido {
-    surface: fila
-  }
-}
-```
-
-## Compatibilidade declarada
-
-O IR de persistencia calcula compatibilidade por recurso com quatro estados:
-
-- `nativo`
-- `adaptado`
-- `parcial`
-- `invalido`
-
-Isso existe para deixar explicito quando um contrato esta pedindo de um banco algo que ele nao entrega do mesmo jeito.
-
-O mesmo principio vale para runtime de orquestracao. Superficies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra familias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.
+## Predicados normalizados
 
-## Interop e implementacao externa
+Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor tambem `predicadoCanonico`.
 
-`use` e `impl` aceitam origens de codigo vivo quando o contrato precisa rastrear runtime real. As origens semanticas suportadas sao:
-
-- `ts`
-- `py`
-- `dart`
-- `lua`
-- `php`
-- `cs`
-- `java`
-- `go`
-- `rust`
-- `cpp`
-
-Exemplo com Lua:
-
-```sema
-module app.runtime {
-  use lua src.runtime
-
-  task processar_snapshot {
-    input {
-      payload: Json required
-    }
-    output {
-      resultado: Json
-    }
-    impl {
-      lua: src.runtime.RuntimeBridge.processSnapshot
-    }
-    guarantees {
-      resultado existe
-    }
-  }
-}
-```
-
-Para Lua, o `drift` resolve funcoes declaradas como `function nome(...)`, `local function nome(...)`, `function Tabela.metodo(...)`, `function Tabela:metodo(...)` e atribuicoes `Tabela.metodo = function(...)`. A forma com `:` e normalizada para ponto no contrato.
-
-Exemplo com PHP:
+Exemplo:
 
 ```sema
-module app.php {
-  use php App.Http.Controllers.UserController
-
-  task criar_usuario {
-    input {
-      payload: Json required
-    }
-    output {
-      resultado: Json
-    }
-    impl {
-      php: App.Http.Controllers.UserController.store
-    }
-    guarantees {
-      resultado existe
-    }
-  }
+rules {
+  email deve_ser email_valido
+  nome deve_ser preenchido
 }
 ```
 
-Para PHP, o `drift` resolve namespaces, classes, traits, interfaces, enums, metodos, funcoes, closures atribuidas, rotas Laravel/Slim (`Route::get`, `Route::post`, `$app->get`) e atributos HTTP no estilo Symfony/PHP 8 (`#[Route]`, `#[Get]`, `#[Post]`). `Route::resource` e `Route::apiResource` sao expandidos para acoes REST canonicas.
+Na IR, `email_valido` continua existindo como escrito e pode receber uma normalizacao como `valid_email`; `preenchido` pode receber `filled`. Esse campo e opcional e serve a agente/automacao, nao muda a sintaxe publica.
+
+## Persistencia vendor-first
+
+O bloco `database` modela banco e recursos persistidos sem apagar as diferencas entre engines.
+
+Estrutura base:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+}
+```
+
+Recursos canonicamente suportados:
+
+- `table`
+- `index`
+- `relationship`
+- `query`
+- `retention`
+- `lock`
+- `replication`
+- `collection`
+- `document`
+- `keyspace`
+- `stream`
+- `capabilities`
+
+Exemplo relacional:
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+Exemplo documental:
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+Exemplo key-value:
+
+```sema
+database principal_redis {
+  engine: redis
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+}
+```
+
+## Compatibilidade declarada
+
+O IR de persistencia calcula compatibilidade por recurso com quatro estados:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso existe para deixar explicito quando um contrato esta pedindo de um banco algo que ele nao entrega do mesmo jeito.
+
+O mesmo principio vale para runtime de orquestracao. Superficies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra familias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.