@semacode/cli 1.5.28 → 1.5.29

package/docs/sintaxe.md

@@ -1,218 +1,218 @@
-# Sintaxe Canonica
-
-<!-- sema:i18n -->
-> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
-> PT: Português depois, com acentos preservados.
-> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
-
-
-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`
-
-## Tipos primitivos
-
-Tipos primitivos reconhecidos diretamente:
-
-- `Texto`
-- `Numero`
-- `Inteiro`
-- `Decimal`
-- `Booleano`
-- `Data`
-- `Timestamp`
-- `Objeto`
-- `Id`
-- `Email`
-- `Json`
-
-`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
-}
-```
-
-Formas suportadas:
-
-- `Lista<T>`
-- `Mapa<K, V>`
-- `Opcional<T>`
-- `T1|T2`
-- `T?`
-
-## Predicados normalizados
-
-Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor também `predicadoCanonico`.
-
-Exemplo:
-
-```sema
-rules {
-  email deve_ser email_valido
-  nome deve_ser preenchido
-}
-```
-
-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, não muda a sintaxe pública.
-
-## Persistência vendor-first
-
-O bloco `database` modela banco e recursos persistidos sem apagar as diferenças 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 persistência calcula compatibilidade por recurso com quatro estados:
-
-- `nativo`
-- `adaptado`
-- `parcial`
-- `invalido`
-
-Isso existe para deixar explícito quando um contrato está pedindo de um banco algo que ele não entrega do mesmo jeito.
-
-O mesmo principio vale para runtime de orquestração. Superfícies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra famílias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.
+# Sintaxe Canonica
+
+<!-- sema:i18n -->
+> EN: English first. The canonical operational body below may still be in Portuguese until full translation lands.
+> PT: Português depois, com acentos preservados.
+> ES: Español al final; não traduza comandos, rotas nem sómbolos `.sema` sem contrato.
+
+
+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`
+
+## Tipos primitivos
+
+Tipos primitivos reconhecidos diretamente:
+
+- `Texto`
+- `Numero`
+- `Inteiro`
+- `Decimal`
+- `Booleano`
+- `Data`
+- `Timestamp`
+- `Objeto`
+- `Id`
+- `Email`
+- `Json`
+
+`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
+}
+```
+
+Formas suportadas:
+
+- `Lista<T>`
+- `Mapa<K, V>`
+- `Opcional<T>`
+- `T1|T2`
+- `T?`
+
+## Predicados normalizados
+
+Predicados escritos em contrato preservam o texto original em `predicado`. Quando a CLI reconhece uma forma comum, a expressao estruturada pode expor também `predicadoCanonico`.
+
+Exemplo:
+
+```sema
+rules {
+  email deve_ser email_valido
+  nome deve_ser preenchido
+}
+```
+
+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, não muda a sintaxe pública.
+
+## Persistência vendor-first
+
+O bloco `database` modela banco e recursos persistidos sem apagar as diferenças 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 persistência calcula compatibilidade por recurso com quatro estados:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso existe para deixar explícito quando um contrato está pedindo de um banco algo que ele não entrega do mesmo jeito.
+
+O mesmo principio vale para runtime de orquestração. Superfícies como `webhook`, `cron`, `worker`, `evento` e `fila` podem ser medidas contra famílias como `n8n`, mas o contrato continua canonicamente modelado em Sema, sem rebaixar a linguagem para a sintaxe do adapter alvo.