@semacode/cli 1.5.28 → 1.5.29

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

@@ -1,171 +1,171 @@
-# Pagamento Ponta a Ponta na Sema
-
-<!-- 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.
-
-
-Este documento descreve o vertical oficial de pagamento da Sema no fluxo público atual.
-
-O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
-
-- contrato público
-- segurança e autorizacao
-- classificacao de dados
-- segredos e proibicoes explicitas
-- regras
-- efeitos operacionais
-- execução, idempotencia, retry e compensacao
-- transicoes de estado
-- orquestração
-- erros publicos
-- testes executaveis com saída, status ou erro observavel
-
-## Arquivos de referência
-
-- `exemplos/pagamento_dominio.sema`
-- `exemplos/pagamento.sema`
-
-## Como o vertical foi dividido
-
-### `exemplos.pagamento.dominio`
-
-Centraliza os contratos compartilhados:
-
-- `entity Pagamento`
-- `enum StatusPagamento`
-- `state ciclo_pagamento`
-
-### `exemplos.pagamento`
-
-Centraliza a operação do vertical:
-
-- `task processar_pagamento`
-- `task confirmar_pagamento`
-- `task notificar_falha_pagamento`
-- `task registrar_timeout_pagamento`
-- `flow orquestracao_pagamento`
-- `route processar_pagamento_publico`
-
-## Narrativa do caso
-
-### Entrada pública
-
-A operação entra por:
-
-- `route processar_pagamento_publico`
-
-Esse contrato pública:
-
-- `pagamento_id`
-- `valor`
-- `token`
-
-É expoe:
-
-- `pagamento`
-- `status`
-- erros publicos coerentes com a `task`
-
-### Task interna
-
-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 saída
-
-### Estado e transicoes
-
-O `state ciclo_pagamento` ancora o contrato de transicao:
-
-- `PENDENTE -> AUTORIZADO`
-- `AUTORIZADO -> PROCESSADO`
-- `PENDENTE -> RECUSADO`
-
-A `task` explícita quais transicoes ela realmente usa.
-
-### Flow de orquestração
-
-O `flow orquestracao_pagamento` demonstra:
-
-- passagem de contexto
-- confirmação em caso de sucesso
-- notificação em caso de recusa
-- registro de timeout em caso de indisponibilidade
-- ramificacao por erro tipado
-
-### Efeitos operacionais
-
-O vertical usa as 5 categorias oficiais da Sema:
-
-- `persistencia`
-- `consulta`
-- `evento`
-- `notificacao`
-- `auditoria`
-
-Também usa `criticidade` para deixar claro o peso operacional do efeito.
-
-### Falhas reais
-
-O vertical cobre explicitamente:
-
-- autorizacao negada
-- saldo insuficiente
-- timeout de gateway
-
-## Fluxo de trabalho recomendado
-
-### 1. Escrever ou ajustar os arquivos `.sema`
-
-Use o domínio compartilhado em um módulo e a operação em outro módulo.
-
-### 2. Aplicar o formato canônico
-
-```bash
-sema formatar exemplos
-```
-
-### 3. Validar semanticamente
-
-```bash
-sema validar exemplos/pagamento.sema
-```
-
-### 4. Gerar código
-
-```bash
-sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
-sema compilar exemplos/pagamento.sema --alvo python --saida ./.tmp/pagamento-py
-```
-
-### 5. Verificar o vertical completo
-
-```bash
-sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamento
-```
-
-## O que esse vertical prova
-
-Se esse vertical passa, a Sema já consegue demonstrar que:
-
-- modela contrato público
-- modela superficie sensível sem deixar segurança invisível
-- modela efeitos operacionais
-- modela falhas reais
-- modulariza domínio com `use`
-- declara idempotencia e execução crítica sem criar sintaxe nova
-- gera artefatos coerentes para TypeScript e Python
-- executa testes gerados sem gambiarra conceitual
-
-Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.
+# Pagamento Ponta a Ponta na Sema
+
+<!-- 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.
+
+
+Este documento descreve o vertical oficial de pagamento da Sema no fluxo público atual.
+
+O objetivo não é mostrar um exemplo fofo. O objetivo e demonstrar que a linguagem já consegue modelar um fluxo de negócio real com:
+
+- contrato público
+- segurança e autorizacao
+- classificacao de dados
+- segredos e proibicoes explicitas
+- regras
+- efeitos operacionais
+- execução, idempotencia, retry e compensacao
+- transicoes de estado
+- orquestração
+- erros publicos
+- testes executaveis com saída, status ou erro observavel
+
+## Arquivos de referência
+
+- `exemplos/pagamento_dominio.sema`
+- `exemplos/pagamento.sema`
+
+## Como o vertical foi dividido
+
+### `exemplos.pagamento.dominio`
+
+Centraliza os contratos compartilhados:
+
+- `entity Pagamento`
+- `enum StatusPagamento`
+- `state ciclo_pagamento`
+
+### `exemplos.pagamento`
+
+Centraliza a operação do vertical:
+
+- `task processar_pagamento`
+- `task confirmar_pagamento`
+- `task notificar_falha_pagamento`
+- `task registrar_timeout_pagamento`
+- `flow orquestracao_pagamento`
+- `route processar_pagamento_publico`
+
+## Narrativa do caso
+
+### Entrada pública
+
+A operação entra por:
+
+- `route processar_pagamento_publico`
+
+Esse contrato pública:
+
+- `pagamento_id`
+- `valor`
+- `token`
+
+É expoe:
+
+- `pagamento`
+- `status`
+- erros publicos coerentes com a `task`
+
+### Task interna
+
+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 saída
+
+### Estado e transicoes
+
+O `state ciclo_pagamento` ancora o contrato de transicao:
+
+- `PENDENTE -> AUTORIZADO`
+- `AUTORIZADO -> PROCESSADO`
+- `PENDENTE -> RECUSADO`
+
+A `task` explícita quais transicoes ela realmente usa.
+
+### Flow de orquestração
+
+O `flow orquestracao_pagamento` demonstra:
+
+- passagem de contexto
+- confirmação em caso de sucesso
+- notificação em caso de recusa
+- registro de timeout em caso de indisponibilidade
+- ramificacao por erro tipado
+
+### Efeitos operacionais
+
+O vertical usa as 5 categorias oficiais da Sema:
+
+- `persistencia`
+- `consulta`
+- `evento`
+- `notificacao`
+- `auditoria`
+
+Também usa `criticidade` para deixar claro o peso operacional do efeito.
+
+### Falhas reais
+
+O vertical cobre explicitamente:
+
+- autorizacao negada
+- saldo insuficiente
+- timeout de gateway
+
+## Fluxo de trabalho recomendado
+
+### 1. Escrever ou ajustar os arquivos `.sema`
+
+Use o domínio compartilhado em um módulo e a operação em outro módulo.
+
+### 2. Aplicar o formato canônico
+
+```bash
+sema formatar exemplos
+```
+
+### 3. Validar semanticamente
+
+```bash
+sema validar exemplos/pagamento.sema
+```
+
+### 4. Gerar código
+
+```bash
+sema compilar exemplos/pagamento.sema --alvo typescript --saida ./.tmp/pagamento-ts
+sema compilar exemplos/pagamento.sema --alvo python --saida ./.tmp/pagamento-py
+```
+
+### 5. Verificar o vertical completo
+
+```bash
+sema verificar exemplos/pagamento.sema --json --saida ./.tmp/verificacao-pagamento
+```
+
+## O que esse vertical prova
+
+Se esse vertical passa, a Sema já consegue demonstrar que:
+
+- modela contrato público
+- modela superficie sensível sem deixar segurança invisível
+- modela efeitos operacionais
+- modela falhas reais
+- modulariza domínio com `use`
+- declara idempotencia e execução crítica sem criar sintaxe nova
+- gera artefatos coerentes para TypeScript e Python
+- executa testes gerados sem gambiarra conceitual
+
+Esse e o criterio pratico que sustenta o uso público do vertical de pagamento como referência para IA e geracao.

package/docs/persistencia-vendor-first.md

@@ -1,151 +1,151 @@
-# Persistência Vendor-First
-
-<!-- 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.
-
-
-Sema 1.5.28 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
-
-## Engines publicas
-
-- `postgres`
-- `mysql`
-- `sqlite`
-- `mongodb`
-- `redis`
-
-## Exemplo PostgreSQL
-
-```sema
-database principal_postgres {
-  engine: postgres
-  schema: public
-  consistency: forte
-  durability: alta
-  transaction_model: mvcc
-  query_model: sql
-  capabilities {
-    joins
-    views
-    foreign_keys
-  }
-  table pedidos {
-    entity: Pedido
-  }
-  relationship pedido_cliente {
-    from: Pedido
-    to: Cliente
-  }
-  query buscar_pedidos {
-    mode: sql
-  }
-}
-```
-
-## Exemplo MySQL
-
-```sema
-database principal_mysql {
-  engine: mysql
-  consistency: forte
-  durability: alta
-  transaction_model: bloqueio
-  query_model: sql
-  table faturamento {
-    table: faturamento
-  }
-  index faturamento_status {
-    table: faturamento
-  }
-  query buscar_faturas {
-    mode: sql
-  }
-}
-```
-
-## Exemplo SQLite
-
-```sema
-database principal_sqlite {
-  engine: sqlite
-  consistency: snapshot
-  durability: media
-  transaction_model: single_thread
-  query_model: sql
-  table cache_local {
-    table: cache_local
-  }
-  retention limpeza_local {
-    retention: "7d"
-  }
-}
-```
-
-## Exemplo MongoDB
-
-```sema
-database principal_mongodb {
-  engine: mongodb
-  consistency: eventual
-  durability: alta
-  transaction_model: documento
-  query_model: documento
-  collection pedidos {
-    collection: pedidos
-  }
-  document pedido_snapshot {
-    entity: PedidoSnapshot
-  }
-  query pipeline_pedido {
-    mode: pipeline
-  }
-}
-```
-
-## Exemplo Redis
-
-```sema
-database principal_redis {
-  engine: redis
-  consistency: eventual
-  durability: media
-  transaction_model: single_thread
-  query_model: chave_valor
-  keyspace cache_pedidos {
-    ttl: "300s"
-  }
-  stream eventos_pedido {
-    surface: fila
-  }
-  retention expurgo_cache {
-    retention: "300s"
-  }
-}
-```
-
-## Compatibilidade calculada
-
-Cada recurso recebe compatibilidade por engine:
-
-- `nativo`
-- `adaptado`
-- `parcial`
-- `invalido`
-
-Isso deixa explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
-
-- `table` em `redis`
-- `foreign_keys` em engine sem suporte equivalente
-- transação multi-documento tratada como universal
-
-## Onde isso aparece
-
-- parser e AST
-- IR canonica
-- analisador semântico
-- formatador
-- `sema drift`
-- `sema importar`
-- extensao VS Code
+# Persistência Vendor-First
+
+<!-- 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.
+
+
+Sema 1.5.29 trata banco como superficie semântica de primeira classe. Isso significa assumir diferenças reais entre engines e coloca-las no contrato, no semântico, na IR, no drift, no impact map, na renomeacao assistida, no `verificar` e na extensao. Nesta linha, o `drift` também materializa persistência local real em `Preferences`, `localStorage` e `sessionStorage` quando a task está ancorada no arquivo que usa essas APIs, preservando o framing IA-first da release atual.
+
+## Engines publicas
+
+- `postgres`
+- `mysql`
+- `sqlite`
+- `mongodb`
+- `redis`
+
+## Exemplo PostgreSQL
+
+```sema
+database principal_postgres {
+  engine: postgres
+  schema: public
+  consistency: forte
+  durability: alta
+  transaction_model: mvcc
+  query_model: sql
+  capabilities {
+    joins
+    views
+    foreign_keys
+  }
+  table pedidos {
+    entity: Pedido
+  }
+  relationship pedido_cliente {
+    from: Pedido
+    to: Cliente
+  }
+  query buscar_pedidos {
+    mode: sql
+  }
+}
+```
+
+## Exemplo MySQL
+
+```sema
+database principal_mysql {
+  engine: mysql
+  consistency: forte
+  durability: alta
+  transaction_model: bloqueio
+  query_model: sql
+  table faturamento {
+    table: faturamento
+  }
+  index faturamento_status {
+    table: faturamento
+  }
+  query buscar_faturas {
+    mode: sql
+  }
+}
+```
+
+## Exemplo SQLite
+
+```sema
+database principal_sqlite {
+  engine: sqlite
+  consistency: snapshot
+  durability: media
+  transaction_model: single_thread
+  query_model: sql
+  table cache_local {
+    table: cache_local
+  }
+  retention limpeza_local {
+    retention: "7d"
+  }
+}
+```
+
+## Exemplo MongoDB
+
+```sema
+database principal_mongodb {
+  engine: mongodb
+  consistency: eventual
+  durability: alta
+  transaction_model: documento
+  query_model: documento
+  collection pedidos {
+    collection: pedidos
+  }
+  document pedido_snapshot {
+    entity: PedidoSnapshot
+  }
+  query pipeline_pedido {
+    mode: pipeline
+  }
+}
+```
+
+## Exemplo Redis
+
+```sema
+database principal_redis {
+  engine: redis
+  consistency: eventual
+  durability: media
+  transaction_model: single_thread
+  query_model: chave_valor
+  keyspace cache_pedidos {
+    ttl: "300s"
+  }
+  stream eventos_pedido {
+    surface: fila
+  }
+  retention expurgo_cache {
+    retention: "300s"
+  }
+}
+```
+
+## Compatibilidade calculada
+
+Cada recurso recebe compatibilidade por engine:
+
+- `nativo`
+- `adaptado`
+- `parcial`
+- `invalido`
+
+Isso deixa explícito quando o contrato está pedindo portabilidade falsa, por exemplo:
+
+- `table` em `redis`
+- `foreign_keys` em engine sem suporte equivalente
+- transação multi-documento tratada como universal
+
+## Onde isso aparece
+
+- parser e AST
+- IR canonica
+- analisador semântico
+- formatador
+- `sema drift`
+- `sema importar`
+- extensao VS Code