cognitivebc 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/LICENSE +70 -0
  2. package/README.md +98 -4
  3. package/SECURITY.md +29 -0
  4. package/TERMS_OF_SERVICE.md +55 -0
  5. package/bin/cbc-cloud-bootstrap.js +108 -0
  6. package/bin/cbc-seed-projects.js +29 -0
  7. package/bin/cbc-server.js +45 -0
  8. package/bin/cognitivebc.js +251 -0
  9. package/docs/ACCESS_CONTROL.md +111 -0
  10. package/docs/ARTIFACT_AUDIT.md +36 -0
  11. package/docs/CONNECT_CLIENTS.md +116 -0
  12. package/docs/DEPLOY_AZURE.md +136 -0
  13. package/docs/INGESTION.md +29 -0
  14. package/docs/OPERATIONS.md +85 -0
  15. package/docs/PROJECT_IDENTITY.md +35 -0
  16. package/docs/RESOLVER.md +86 -0
  17. package/docs/SDK.md +96 -0
  18. package/docs/STORAGE.md +63 -0
  19. package/docs/TECHNICAL_SPECIFICATION.md +365 -0
  20. package/docs/TELEMETRY.md +119 -0
  21. package/index.js +27 -2
  22. package/package.json +45 -5
  23. package/packages/cbc-compiler/index.js +357 -0
  24. package/packages/cbc-compiler/sanitizer.js +43 -0
  25. package/packages/cbc-identity/index.js +92 -0
  26. package/packages/cbc-mcp/http-backend.js +142 -0
  27. package/packages/cbc-mcp/http-route.js +64 -0
  28. package/packages/cbc-mcp/index.js +50 -0
  29. package/packages/cbc-mcp/tools.js +122 -0
  30. package/packages/cbc-resolver/catalog-linker.js +215 -0
  31. package/packages/cbc-resolver/graph-builder.js +533 -0
  32. package/packages/cbc-resolver/index.js +548 -0
  33. package/packages/cbc-resolver/obsidian-bridge.js +564 -0
  34. package/packages/cbc-schema/index.js +194 -0
  35. package/packages/cbc-sdk-js/client.js +162 -0
  36. package/services/cbc-api/access-policy.js +130 -0
  37. package/services/cbc-api/artifact-audit.js +167 -0
  38. package/services/cbc-api/cloud.js +56 -0
  39. package/services/cbc-api/context-service.js +48 -0
  40. package/services/cbc-api/ingestion-service.js +234 -0
  41. package/services/cbc-api/pg-store.js +172 -0
  42. package/services/cbc-api/project-registry.js +343 -0
  43. package/services/cbc-api/public/app.html +123 -0
  44. package/services/cbc-api/public/graph.html +1168 -0
  45. package/services/cbc-api/public/graph2.html +455 -0
  46. package/services/cbc-api/public/graph3.html +503 -0
  47. package/services/cbc-api/public/index.html +78 -0
  48. package/services/cbc-api/public/vendor/cbc-app.js +209 -0
  49. package/services/cbc-api/public/vendor/cbc-auth.js +49 -0
  50. package/services/cbc-api/public/vendor/cbc-site.css +101 -0
  51. package/services/cbc-api/public/vendor/cose-base.js +3214 -0
  52. package/services/cbc-api/public/vendor/cytoscape-dagre.js +397 -0
  53. package/services/cbc-api/public/vendor/cytoscape-fcose.js +1549 -0
  54. package/services/cbc-api/public/vendor/cytoscape.min.js +32 -0
  55. package/services/cbc-api/public/vendor/dagre.min.js +3809 -0
  56. package/services/cbc-api/public/vendor/graphology-library.min.js +2 -0
  57. package/services/cbc-api/public/vendor/graphology.umd.min.js +2 -0
  58. package/services/cbc-api/public/vendor/layout-base.js +5230 -0
  59. package/services/cbc-api/public/vendor/pf-graph.css +86 -0
  60. package/services/cbc-api/public/vendor/pf-telemetry.js +176 -0
  61. package/services/cbc-api/public/vendor/sigma.min.js +1351 -0
  62. package/services/cbc-api/runtime-info.js +39 -0
  63. package/services/cbc-api/server.js +642 -0
  64. package/services/cbc-api/store-loader.js +269 -0
  65. package/services/cbc-api/telemetry.js +148 -0
  66. package/services/cbc-api/token-service.js +61 -0
@@ -0,0 +1,365 @@
1
+ # Documentação Técnica Oficial — CognitiveBC (`cognitivebc.io`)
2
+ **Infraestrutura de Compilação de Experiência Operacional, Decisória e Bytecode Cognitivo para Sistemas de Agentes**
3
+
4
+ > [!IMPORTANT]
5
+ > **Posicionamento Arquitetural (Modelo Produto / API-First):**
6
+ > O **Synap-se (`synap-se`)** é o **Orquestrador Soberano e Kernel do Sistema** (gerencia o ciclo de vida dos agentes, governança, máquina de estados, transições Z0–Z4, comunicação inter-agentes e despacho de tarefas).
7
+ > O **MktSquad (`mktsquad.performacia.com.br`)** opera como a **BU de Aquisição** (motor de produção audiovisual) conectada ao Synap-se via API ([ADR-0010](file:///Users/fer/Projetos/synap-se/docs/adr/0010-equipes-contratadas.md), [ADR-0013](file:///Users/fer/Projetos/synap-se/docs/adr/0013-agent-as-a-service.md), [ADR-0015](file:///Users/fer/Projetos/synap-se/docs/adr/0015-bu-aquisicao-mktsquad.md)).
8
+ > O **CognitiveBC (`cognitivebc.io`)** é um **produto e plataforma independente de infraestrutura cognitiva**, com repositório próprio (`github.com/performacia/cognitivebc`), SDK oficial publicado no npm (`cognitivebc`) e API própria (`api.cognitivebc.io`).
9
+ > O **Synap-se (Orquestrador)** e a **BU Aquisição (`mktsquad`)** consomem o CognitiveBC via API/SDK e MCP, sem duplicar lógica de compilação ou resolução em múltiplos repositórios.
10
+
11
+ > [!CAUTION]
12
+ > **Regra de Preservação Histórica:** A pasta histórica `projetos/synap-se/eeii/` (experimentos congelados `EXPERIMENT-001` a `004` e `piloto/minerar.py`) permanece **congelada e inalterada** como registro científico da origem do conceito.
13
+
14
+ ---
15
+
16
+ ## 1. Matriz de Fronteira: O Que É Produto `CognitiveBC` vs. O Que Migra para `Synap-se + Rust`
17
+
18
+ A revisão linha a linha do antigo [plano_implementacao_eeii_revisitado.md](file:///Users/fer/.gemini/antigravity/brain/897bf601-23d2-4c6e-9d29-7ba1105420c2/plano_implementacao_eeii_revisitado.md) revelou que manter um compilador em JS dentro do Synap-se (`eeii-compiler.js`) e outro em Python no Motorapps (`eeii_compiler.py`), misturados com detalhes de captura de terminal e transporte de processos locais, quebraria o isolamento de produto.
19
+
20
+ A tabela abaixo formaliza a **divisão cirúrgica em duas frentes de trabalho independentes**:
21
+
22
+ | Item Original do Plano EEII Revisitado | Destino Arquitetural Definitivo | Justificativa de Engenharia |
23
+ | :--- | :--- | :--- |
24
+ | **Fase 1 · Schema `v2` (6 dimensões de escopo, `target_roles`, `trigger_regime`) e Decomposição Tripla (`SKILL.md` + `*.cbc.yaml` + `MAP_*.md`)** | **Frente 1: Produto CognitiveBC (`cognitivebc.io`)** | É a especificação canônica da linguagem e dos artefatos do produto (`cognitivebc/v1`, retrocompatível com `synapse-eeii/v1` e `v2`). |
25
+ | **Fase 2A · Schema de Eventos do *Reasoning & Multimodal Stream* e Detector Semântico de `SilentSelfCorrectionCycle`** | **Frente 1: Produto CognitiveBC (`POST /api/v1/streams/ingest`)** | Define o contrato universal de telemetria cognitiva que qualquer cliente (Synap-se, MktSquad, Claude Code, Codex, LangGraph) envia ao CognitiveBC. |
26
+ | **Fase 2B · Instrumentação de Baixo Nível dos Hooks sem Spawn de Processo (`runtime-hook` via Socket UDS e scanner `.jsonl` mmap)** | **Transferido para Frente 2: Plano de Migração Rust (`synapse-mcp` & `synapse-cbc`)** | É otimização de infraestrutura local do hospedeiro Synap-se para eliminar `subprocess.run(['node', 'runtime-hook.js'])` e `fs.readSync(64MB)`. |
27
+ | **Fase 3 · Compilador Cognitivo de 3 Regimes + Sanitização Cross-Tenant e Promoção `Local → Global`** | **Frente 1: Produto CognitiveBC (`POST /api/v1/compile`)** | Em vez de manter dois compiladores duplicados (JS + Python), o serviço CognitiveBC centraliza a compilação e a desidentificação cross-tenant. |
28
+ | **Fase 4 · Resolvedor JIT por Escopo e Papel (`resolve_context_for_role` com teto de `600 tokens`)** | **Frente 1: Produto CognitiveBC (`POST /api/v1/resolve` + SDK `cognitivebc`)** *(com cache FFI local na Frente 2)* | A inteligência de filtragem por `Squad × Stack × Categoria × Tenant × Papel` vive no CognitiveBC; o crate Rust `synapse-cbc` apenas mantém cache $O(1)$ por SHA-256 no cliente. |
29
+ | **Fase 5A · Ferramentas Semânticas de Memória, Catálogo e Gates (`pull_cbc_experience`, `check_gate_rules`, `cbc://bytecode/*`)** | **Frente 1: Produto CognitiveBC (MCP Server Oficial `@cognitivebc/mcp`)** | São os verbos cognitivos e de contrato de domínio expostos pelo produto para dar "Liberdade Controlada" aos agentes. |
30
+ | **Fase 5B · Daemon MCP sobre Unix Domain Socket (`synapse-mcp`), `synapse-mcp-shim` (1,8 MB) e Worker Pool Headless** | **Transferido para Frente 2: Plano de Migração Rust (`synapse-core-rs`)** | É o transporte nativo de alta densidade do Synap-se para substituir os 29 processos Node `mcp-bus.js` (~2,6 GB RAM $\to$ 52 MB). |
31
+ | **Fase 6 · Benchmark Científico `EXPERIMENT-005` (Episódio 3 com Blender 5.0 real no loop)** | **Frente 1: Validação Oficial do Produto CognitiveBC integrado via API ao MktSquad** | Prova de valor empírica e comercial do produto `cognitivebc.io` operando sobre uma BU real em produção. |
32
+
33
+ ---
34
+
35
+ ## 2. Arquitetura do Produto CognitiveBC e Integração via API com Synap-se e BUs
36
+
37
+ O **CognitiveBC** fecha o ciclo completo entre **Ingestão de Stream Ao Vivo $\to$ Compilação em 3 Regimes $\to$ Decomposição Tripla Isolada por Escopo $\to$ Resolução JIT por Papel $\to$ Pull via MCP $\to$ Graduação Determinística para Gates**:
38
+
39
+ ```mermaid
40
+ flowchart TD
41
+ subgraph CLIENTS["Clientes Consumidores (Via API REST / SDK npm `cognitivebc` / MCP)"]
42
+ SYN["Engine Synap-se (Porta 4778)<br/>Kernel Builder + Orquestrador de Palco (Z0–Z4)<br/>Conector nativo: crates/synapse-cbc"]
43
+ MKT["BU Aquisição · MktSquad (mktsquad.performacia.com.br)<br/>Pipeline MktSquad (Planejador, Roteirista, Diretor, Construtor 3D, Revisor)"]
44
+ EXT["Agentes Externos / Terceiros<br/>(Claude Code, Codex, Cursor, LangGraph via SDK/MCP)"]
45
+ end
46
+
47
+ subgraph CBC["Produto CognitiveBC (api.cognitivebc.io · github.com/performacia/cognitivebc)"]
48
+ ING["1. Ingestor de Stream & Detector de Ciclos<br/>POST /api/v1/streams/ingest<br/>Detecta: ExternalCorrective · SilentSelfCorrectionCycle · PioneerDiscovery"]
49
+ COMP["2. Compilador Cognitivo de 3 Regimes + Sanitizador Cross-Tenant<br/>POST /api/v1/compile<br/>Separa IP Global do Squad/Stack de Dados Privados do Tenant + SHA-256"]
50
+ STORE["3. Tripla Store Versionada (Git/SQLite/S3)<br/>• Artefato 1: SKILL.md (Escopo Squad/Área)<br/>• Artefato 2: *.cbc.yaml (Escopo Stack/Papel)<br/>• Artefato 3: MAP_<tenant>.md (Escopo Tenant/Marca)"]
51
+ RES["4. Resolvedor JIT por Escopo × Papel<br/>POST /api/v1/resolve<br/>Filtra: Kernel × Squad × Stack × Categoria × Tenant × Role (Push <= 600 tokens)"]
52
+ GATE["5. Verificador Determinístico & Graduação de Regras<br/>POST /api/v1/gates/verify & /api/v1/gates/graduate"]
53
+
54
+ ING --> COMP --> STORE --> RES
55
+ COMP -. "Candidatas determinísticas" .-> GATE
56
+ end
57
+
58
+ SYN -- "Stream UDS → Batch Ingest / Resolve JIT" --> CBC
59
+ MKT -- "Eventos de Rodada / Resolve por Etapa / Pull MCP" --> CBC
60
+ EXT -- "SDK npm `cognitivebc` / MCP" --> CBC
61
+ ```
62
+
63
+ ---
64
+
65
+ ## 3. Especificação Canônica da Linguagem e Schema (`cognitivebc/v1`)
66
+
67
+ O CognitiveBC formaliza o schema **`cognitivebc/v1`**, mantendo **100% de retrocompatibilidade** de leitura e validação com os schemas legados `synapse-eeii/v1` e `synapse-eeii/v2` usados em [experience-memory.js](file:///Users/fer/Projetos/synap-se/experience-memory.js).
68
+
69
+ ### 3.1. O Problema do Formato Monolítico Anterior
70
+ No formato legado `synapse-eeii/v1` ([experience-memory.js](file:///Users/fer/Projetos/synap-se/experience-memory.js#L1-L63)), um único bloco YAML continha `scope` genérico sem distinção de papel (`role`) e misturava procedimentos de área, invariantes profundos de ferramenta e dados da marca do cliente. Como demonstrado no benchmark do Episódio 2 ([e2e_benchmark_summary.json](file:///Users/fer/.gemini/antigravity/brain/897bf601-23d2-4c6e-9d29-7ba1105420c2/benchmark/results/e2e_benchmark_summary.json)), injetar o bloco monolítico sem filtro de papel desperdiçou `+8.160 tokens` (`+42%` de custo) enviando invariantes de geometria Blender para o **Roteirista**.
71
+
72
+ ### 3.2. A Decomposição Tripla Ortogonal do CognitiveBC
73
+ Toda experiência compilada pelo CognitiveBC é decomposta em **3 artefatos ortogonais**, governados por velocidades de mudança e fronteiras de propriedade intelectual distintas ([ADR-0013 §8](file:///Users/fer/Projetos/synap-se/docs/adr/0013-agent-as-a-service.md#L96-L103)):
74
+
75
+ | Artefato | Formato e Identificador | Natureza Cognitiva | Escopo de Propriedade (`scope.level`) | Exemplo Real Validado |
76
+ | :--- | :--- | :--- | :--- | :--- |
77
+ | **1. Playbook Procedural (`SKILL.md`)** | Markdown estruturado com frontmatter `cbc_skill/v1` | **O "Como Fazer" Sequencial** (ordem das etapas, comandos CLI, flags de paralelismo, contrato entre etapas). | **`squad` / `area`** *(Propriedade Intelectual da BU AaaS)* | [SKILL_scientific_3d_pipeline.md](file:///Users/fer/.gemini/antigravity/brain/897bf601-23d2-4c6e-9d29-7ba1105420c2/benchmark/artifacts/SKILL_scientific_3d_pipeline.md): reduz 171 turnos exploratórios a 8 passos diretos (`roteiro → gates → revisor → preview strip --t 0.15,0.5,0.85 → render 2x → cat3d → direcao misto_3d`). |
78
+ | **2. Cognitive Bytecode (`*.cbc.yaml`)** | YAML canônico `cognitivebc/v1` assinado com SHA-256 | **Invariantes de Decisão, Restrições e Armadilhas Não-Óbvias** (`agent_constraints`, `agent_heuristics`, `experience_graph`). | **`stack` / `category`** *(Ativo técnico reutilizável entre todos os clientes da stack)* | [EEII_BYTECODE_scientific_3d.md](file:///Users/fer/.gemini/antigravity/brain/897bf601-23d2-4c6e-9d29-7ba1105420c2/benchmark/artifacts/EEII_BYTECODE_scientific_3d.md): AgX gold `(1.0, 0.50, 0.04)` em `emit <= 1.2`, `za_baked()` para `Oesophagus` Curve, `close_holes()` no `Stomach`, proibição de `o.scale`, raio de hélice `<= 0.07`, `HETATM 32M`. |
79
+ | **3. Mapa Semântico e de Recursos (`MAP_<tenant>.md`)** | Markdown + tabelas tipadas `cbc_map/v1` | **Identidade, Ontologia Visual, Fatos e Assets Auditados do Cliente** (cores por molécula, PDBs validados, regras editoriais). | **`tenant`** *(Estritamente isolado no cofre do cliente/marca)* | [MAP_diario_glp1_series.md](file:///Users/fer/.gemini/antigravity/brain/897bf601-23d2-4c6e-9d29-7ba1105420c2/benchmark/artifacts/MAP_diario_glp1_series.md): paleta fixa da série, PDBs CC0 (`6X18`, `1N1M`, `1AO6`, `4ZGM`), regra `"canetas"` nas primeiras 12 palavras e teto de `140` palavras. |
80
+
81
+ ### 3.3. Especificação Completa do Schema `cognitivebc/v1` (Compatível com `synapse-eeii/v2`)
82
+
83
+ ```yaml
84
+ schema: cognitivebc/v1 # Aceita também 'synapse-eeii/v1' e 'synapse-eeii/v2'
85
+ id: cbc:stack:scientific_3d:v1
86
+ provenance:
87
+ source_sessions:
88
+ - session_id: 3d-realpipeline-ep1-20261108
89
+ sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
90
+ compiled_at: "2026-11-08T20:30:00Z"
91
+ compiler_version: "cognitivebc@0.1.0"
92
+
93
+ # 1. Taxonomia de Escopo em 6 Dimensões (Resolve ADR-004 histórico)
94
+ scope:
95
+ level: stack # kernel | squad | stack | category | tenant | role
96
+ squad: mktsquad # opcional: id da BU/Squad AaaS
97
+ area: midias-organico # opcional: área dentro da BU (radar | organico | pago | seo | distribuicao)
98
+ stack: scientific_3d_stack # opcional: stack técnica (ex.: blender-5.0-zanatomy-pdb)
99
+ category: infoproduto # opcional: infoproduto | saas-b2b | app-b2c | servico
100
+ domain: saude-regulada # opcional: domínio regulatório
101
+ tenant: null # OBRIGATÓRIO ser null em artefatos globais (stack/squad); preenchido apenas em artefatos locais
102
+ roles: # OBRIGATÓRIO para filtro JIT: quais papéis podem receber itens deste pacote em Push
103
+ - construtor_3d
104
+ - diretor_arte
105
+ - roteirista
106
+ - revisor
107
+
108
+ # 2. Referências Cruzadas da Decomposição Tripla
109
+ companion_artifacts:
110
+ skill_playbook: skills/midias-organico/scientific_3d_pipeline/SKILL.md
111
+ tenant_maps:
112
+ diario_glp1: marcas/diario_glp1/MAP_semantic_assets.md
113
+
114
+ # 3. Seções Canônicas com Filtro granular por Papel (target_roles) e Regime de Gatilho (trigger_regime)
115
+ agent_identity:
116
+ role: specialist_scientific_3d
117
+ mission: "Construir e validar cenas biomédicas 3D anatomicamente precisas no Blender 5.0 sem artefatos visuais ou topológicos."
118
+
119
+ decision_principles:
120
+ - id: DP-3D-01
121
+ principle: "preview_strip_before_full_render"
122
+ rule: "Nunca disparar renderização completa de vídeo (.mp4) sem antes gerar e inspecionar visualmente o strip de 3 frames (--preview --t 0.15,0.5,0.85)."
123
+ target_roles: [construtor_3d]
124
+ trigger_regime: silent_multimodal
125
+
126
+ agent_constraints:
127
+ - id: AC-ED-01
128
+ type: avoid
129
+ rule: "Não citar agonistas duplos GIP/GLP-1 (tirzepatida/Mounjaro) quando o mecanismo explicado for exclusivo de agonista simples de GLP-1."
130
+ target_roles: [roteirista, revisor]
131
+ trigger_regime: external_corrective
132
+ graduation_candidate: true
133
+ deterministic_gate_hint: "regex_disallow: ['\\bmounjaro\\b', '\\btirzepatida\\b'] when mechanism == 'glp1_mono'"
134
+
135
+ - id: AC-3D-01
136
+ type: avoid
137
+ rule: "Proibido alterar obj.scale em órgãos importados do Z-Anatomy (origem compartilhada em 0,0,0 desloca o órgão da anatomia adjacente); enquadrar exclusivamente via cam_dist e lens."
138
+ target_roles: [construtor_3d]
139
+ trigger_regime: silent_multimodal
140
+ graduation_candidate: true
141
+ deterministic_gate_hint: "ast_disallow_attr_assign: 'scale' on zanatomy objects"
142
+
143
+ agent_heuristics:
144
+ - id: AH-3D-AGX-GOLD
145
+ when: "Configurando material emissivo dourado (GLP-1) no Blender 5.0 com gerenciamento de cor AgX"
146
+ then: "Usar RGB hiper-saturado (1.0, 0.50, 0.04) com emit_strength entre 0.8 e 1.2; valores >= 2.0 dessaturam para branco/creme no AgX."
147
+ scope: "blender-5.0-agx"
148
+ target_roles: [construtor_3d]
149
+ trigger_regime: silent_multimodal
150
+ evidence_count: 3
151
+
152
+ - id: AH-3D-PDB-HELIX
153
+ when: "Construindo backbone C-alfa de peptídeos PDB na escala 0.05 (passo de hélice = 0.27 BU) ou lendo 4ZGM.pdb (semaglutida)"
154
+ then: "Manter backbone_radius <= 0.07 (0.045 em complexos densos) para não fundir voltas da hélice em 'salsicha', e incluir registro HETATM resName=='32M' (Lisina-26 modificada) na leitura de C-alfa."
155
+ scope: "pdb-molecular-builder"
156
+ target_roles: [construtor_3d]
157
+ trigger_regime: silent_multimodal
158
+ evidence_count: 2
159
+
160
+ experience_graph:
161
+ - problem_id: EG-ZANATOMY-OESOPHAGUS-AND-STOMACH
162
+ symptom: "Oesophagus invisível após modificadores de malha e rasgos pretos na parede anterior do Stomach em close-up."
163
+ root_cause: "No z_anatomy_digestive.glb, Oesophagus é importado como CURVE Bezier (não MESH), e Stomach possui aberturas vasculares abertas na malha."
164
+ solutions_evaluated:
165
+ - option: "Aplicar solidify/subsurf direto no objeto importado"
166
+ outcome: rejected
167
+ reason: "Falha silenciosamente em objetos do tipo CURVE."
168
+ - option: "Converter via za_baked() (depsgraph convert CURVE -> MESH) e rodar close_holes(obj, max_sides=120) com bmesh.ops.contextual_create antes do Shade Smooth"
169
+ outcome: adopted
170
+ reason: "Elimina 100% dos rasgos topológicos e garante malha válida para corte booleano/shader."
171
+ target_roles: [construtor_3d]
172
+ trigger_regime: silent_multimodal
173
+ ```
174
+
175
+ ---
176
+
177
+ ## 4. Protocolo de Captura e Ingestão do *Reasoning & Multimodal Stream*
178
+
179
+ ### 4.1. Por Que o CognitiveBC Não Depende de `.jsonl` Pós-Sessão
180
+ Conforme provado no [EXPERIMENT-004](file:///Users/fer/Projetos/synap-se/projetos/synap-se/eeii/RFC/EXPERIMENT-004.md#L88-L93) e na auditoria de [3D_realpipeline.md](file:///Users/fer/3D_realpipeline.md):
181
+ * Nos arquivos `.jsonl` persistidos em disco pelo Claude Code, **~93% dos blocos `thinking` estão vazios** (apenas `signature`).
182
+ * Nos rollouts `.jsonl` do Codex, o `reasoning` fica em `encrypted_content`.
183
+ * Mais de **85% da inteligência acionável** de uma sessão complexa reside nos resumos de raciocínio em tempo real + chamadas de ferramentas + **ciclos de auto-inspeção visual multimodal** (`Write script → Render preview pv_*.jpg → Read image → Rewrite script`).
184
+
185
+ ### 4.2. Schema Universal de Evento (`CBCStreamEvent`)
186
+ Qualquer runtime conectado ao CognitiveBC (o daemon nativo `synapse-mcp` do Synap-se, as rotinas da BU Aquisição `mktsquad` ou o SDK `cognitivebc`) envia eventos normalizados para `POST /api/v1/streams/ingest` (ou grava no buffer local `session-stream.jsonl` sincronizado):
187
+
188
+ ```json
189
+ {
190
+ "schema": "cognitivebc-stream/v1",
191
+ "session_id": "sess_01J9X...",
192
+ "tenant": "diario_glp1",
193
+ "squad": "mktsquad",
194
+ "area": "midias-organico",
195
+ "role": "construtor_3d",
196
+ "turn_index": 42,
197
+ "timestamp": "2026-11-08T20:15:12.410Z",
198
+ "event_type": "SilentSelfCorrectionCycle",
199
+ "payload": {
200
+ "target_file": "scientific_3d_stack/build_ep1_clips.py",
201
+ "versions": [
202
+ { "version": 1, "sha256": "a1b2...", "diff_summary": "Initial emit_strength=3.5 on GLP-1 gold" },
203
+ { "version": 2, "sha256": "c3d4...", "diff_summary": "Changed color to (1.0, 0.50, 0.04) and emit_strength=1.0 after inspecting pv_ep1_01_v1.jpg" }
204
+ ],
205
+ "multimodal_inspections": [
206
+ { "file": "pv_ep1_01_v1.jpg", "sha256": "f9e8...", "media_type": "image/jpeg" }
207
+ ],
208
+ "reasoning_summaries": [
209
+ "In pv_ep1_01_v1.jpg, the gold GLP-1 spheres look washed out cream-white because Blender 5.0 AgX desaturates high emission values. Lowering emit_strength to 1.0 and deepening base RGB orange-gold."
210
+ ],
211
+ "command_executed": "blender -b -P render_clip.py -- --clip 1 --preview --t 0.15,0.5,0.85",
212
+ "exit_code": 0
213
+ }
214
+ }
215
+ ```
216
+
217
+ ### 4.3. Regras de Detecção Automática no Stream
218
+ 1. **Detecção de Inspeção Multimodal (`multimodal_inspect`):** Acionada sempre que uma ferramenta de leitura (`Read`, `view_image`, `inspect_preview`) abre `.jpg`, `.png`, `.webp` ou `.mp4`, registrando o hash SHA-256 do artefato visual inspecionado.
219
+ 2. **Detecção de Ciclo de Auto-Correção Silenciosa (`SilentSelfCorrectionCycle`):** Acionada deterministicamente quando um mesmo arquivo-alvo passa pela sequência:
220
+ $$\texttt{Write/Edit } (v_k) \longrightarrow \texttt{Execute/Render } (\text{exit } 0) \longrightarrow \texttt{MultimodalInspect / TestOutput} \longrightarrow \texttt{Write/Edit } (v_{k+1})$$
221
+ O coletor empacota automaticamente o `diff` exato entre $v_k$ e $v_{k+1}$ junto aos `reasoning_summaries` intermediários e dispara o **Regime 2** do compilador.
222
+
223
+ ---
224
+
225
+ ## 5. O Compilador Cognitivo de 3 Regimes e Sanitizador Cross-Tenant (`POST /api/v1/compile`)
226
+
227
+ O motor de compilação do CognitiveBC substitui definitivamente scripts baseados em regex de frustração humana (`minerar.py`) por um pipeline determinístico + estruturado orientado a **3 Regimes de Gatilho**:
228
+
229
+ ### 5.1. Matriz dos 3 Regimes de Compilação
230
+
231
+ | Regime | Condição Determinística de Disparo | Payload de Entrada (`CompileRequest`) | Artefatos Gerados / Atualizados (`CompileResponse`) |
232
+ | :--- | :--- | :--- | :--- |
233
+ | **Regime 1 · Corretivo Externo** | • `gates.check()` falha na rodada $r$ e passa na rodada $r+1$; **ou**<br/>• `revisao.parecer()` retorna `aprovado=False` ou `duvida=True` decidida pelo Humano ([ADR-0016](file:///Users/fer/Projetos/synap-se/docs/adr/0016-politica-de-autonomia-das-equipes.md)); **ou**<br/>• Intervenção humana (`@área`, `outra rodada`). | • Entrega reprovada ($v_r$)<br/>• Achado do Verificador/Revisor ou decisão humana<br/>• Entrega aprovada ($v_{r+1}$) | • Nova `agent_constraint` ou `agent_heuristic` tipada com `target_roles` do especialista + `revisor`.<br/>• Se binária/determinística (`graduation_candidate: true`), gera regra pronta para o `ContractGate` (`gates.py`). |
234
+ | **Regime 2 · Auto-Corretivo Silencioso / Multimodal** | • Evento `SilentSelfCorrectionCycle` recebido em `/api/v1/streams/ingest` ($\ge 2$ versões do mesmo script intercaladas por execução e inspeção de preview/saída, mesmo com `exit_code == 0`). | • Diffs unificados `v1 → v2 → v3`<br/>• `reasoning_summaries` entre versões<br/>• Metadados do preview inspecionado | • Nova heurística `when → then` em `agent_heuristics` no `*.cbc.yaml` da Stack.<br/>• Novo nó em `experience_graph` registrando as soluções rejeitadas ($v_1, v_2$) e a solução adotada ($v_3$). |
235
+ | **Regime 3 · Pioneiro / Descoberta Construtiva** | • Tarefa concluída com `aprovado=True` onde `total_tokens > 100_000` ou `turns > 40`, **ou** criação de novos builders numa pasta de stack, **ou** flag `pioneer: true`. | • Stream condensado da sessão inteira (sequência de ferramentas, diffs finais e decisões arquiteturais)<br/>• Entregas finais aprovadas | **Decomposição Tripla Completa:**<br/>1. `SKILL.md` (`scope.level = squad`)<br/>2. `<stack>.cbc.yaml` (`scope.level = stack`)<br/>3. `MAP_<tenant>.md` (`scope.level = tenant`). |
236
+
237
+ ### 5.2. Classificador de Fronteira e Sanitização Cross-Tenant (`Local → Global`)
238
+ Para garantir o fosso competitivo (*compounding moat*) do modelo **Agent as a Service** ([ADR-0013 §8](file:///Users/fer/Projetos/synap-se/docs/adr/0013-agent-as-a-service.md#L96-L103)) sem jamais vazar dados de um cliente para outro, o compilador executa um **passo obrigatório de sanitização de fronteira**:
239
+ 1. **Filtro de Dados de Tenant (`scope.level = 'tenant'`):** Nomes de marcas, produtos proprietários, promessas comerciais específicas, paleta cromática da série e caminhos de arquivos exclusivos do cliente são roteados **exclusivamente** para `MAP_<tenant>.md`.
240
+ 2. **Desidentificação para Promoção Global (`scope.level = 'stack' | 'squad'`):** Antes de gravar qualquer item em `*.cbc.yaml` ou `SKILL.md`, o sanitizador verifica a ausência de identificadores do `tenant` (substituindo menções residuais por tokens genéricos de domínio, ex.: `"molécula agonista principal"` em vez do nome comercial da marca) e incrementa `evidence_count` quando a mesma heurística é confirmada em múltiplos clientes.
241
+
242
+ ---
243
+
244
+ ## 6. O Resolvedor JIT por Escopo e Papel (`POST /api/v1/resolve`)
245
+
246
+ ### 6.1. Por Que Resolução Determinística JIT Supera RAG (Busca Vetorial)
247
+ Em linhas de montagem multi-agente (como no MktSquad: `Planejador → Roteirista → Verificador → Revisor → Diretor de Arte → Construtor 3D`), a busca vetorial (RAG) falha por dois motivos comprovados:
248
+ 1. **Unknown Unknowns:** Um agente Construtor 3D nunca fará uma query RAG por *"Oesophagus Curve vs Mesh"* antes de quebrar a malha, pois não sabe que o ativo original no GLB é uma curva Bezier.
249
+ 2. **Poluição de Contexto Cross-Role:** Enviar regras de topologia 3D para o Roteirista desperdiça milhares de tokens.
250
+
251
+ ### 6.2. Algoritmo de Resolução Hierárquica (`resolveContextForRole`)
252
+ Quando o Synap-se ou o MktSquad chama `POST /api/v1/resolve` (ou `cbc.resolve({ tenant, squad, area, role, stacks, stage })`), o motor aplica a cascata de 6 níveis (`kernel → squad → stack → category → tenant → role`) e devolve um **Pacote Push Cirúrgico (orçamento padrão $\le 600$ tokens para papéis textuais e $\le 1.200$ tokens para papéis de código/stack)** + **Ponteiros Pull MCP**:
253
+
254
+ | Papel (`role`) | Conteúdo Montado no `push_packet` (Injetado no System Prompt da Etapa) | Recursos Disponíveis em `pull_resources` (Via MCP) |
255
+ | :--- | :--- | :--- |
256
+ | **`planejador` / `coordenador`** | • Cabeçalho, pré-requisitos e árvore de decisão de estratégia da `SKILL.md` da área (ex.: quando escolher `estrategia="misto_3d"` autonomamente). | `cbc://skills/{squad}/{area}` |
257
+ | **`roteirista`** | • Seção **Regras Editoriais e Vocabulário Visual** de `MAP_<tenant>.md` (`"canetas"` nas primeiras 12 palavras, $\le 140$ palavras).<br/>• Apenas `agent_constraints` e `agent_heuristics` com `'roteirista' in target_roles`. **Zero código Blender/3D.** | `cbc://map/{tenant}/facts`<br/>`check_gate_rules(stage="roteiro")` |
258
+ | **`revisor`** *(Independente)* | • Rubrica compilada com `agent_constraints` (`'revisor' in target_roles`) + tabela de restrições científicas de `MAP_<tenant>.md` + histórico de `duvidas` já arbitradas pelo Humano ([ADR-0016](file:///Users/fer/Projetos/synap-se/docs/adr/0016-politica-de-autonomia-das-equipes.md)). | `cbc://map/{tenant}/verified-claims` |
259
+ | **`diretor_arte`** | • Regras de mapeamento de cenas da `SKILL.md` (`tipo="foto"` + `arquivo="3d:<id>"` para compatibilidade Pydantic).<br/>• Paleta semântica e resumo do catálogo de clipes 3D de `MAP_<tenant>.md`. | `cbc://catalog/3d/{tenant}` |
260
+ | **`construtor_3d`** | • **Bytecode completo da `scientific_3d_stack`** (`agent_constraints`, `agent_heuristics` e `experience_graph`: AgX gold, `za_baked`, `close_holes`, sem `o.scale`, raio $\le 0{,}07$, `HETATM 32M`).<br/>• Comandos de preview strip (`--preview --t 0.15,0.5,0.85`) e paralelismo (`2x`) da `SKILL.md`.<br/>• Tabela exata de RGBs e PDBs validados de `MAP_<tenant>.md`. | `cbc://bytecode/scientific_3d_stack`<br/>`inspect_pdb_structure`<br/>`render_preview_strip` |
261
+
262
+ ---
263
+
264
+ ## 7. Especificação da API Pública v1 (`api.cognitivebc.io`) e SDK `cognitivebc`
265
+
266
+ ### 7.1. Endpoints REST Canônicos
267
+
268
+ | Método e Rota | Descrição | Corpo da Requisição (Resumo) | Resposta (`200 OK`) |
269
+ | :--- | :--- | :--- | :--- |
270
+ | **`POST /api/v1/streams/ingest`** | Recebe lotes de eventos do `session-stream` e detecta ciclos `SilentSelfCorrectionCycle`. | `{ session_id, tenant, squad, events: [CBCStreamEvent] }` | `{ accepted: number, cycles_detected: [CycleId], triggered_compilations: [JobId] }` |
271
+ | **`POST /api/v1/compile`** | Executa o Compilador de 3 Regimes sobre um evento de correção, ciclo multimodal ou sessão pioneira. | `{ regime: "external_corrective" \| "silent_multimodal" \| "pioneer_discovery", scope, input_payload }` | `{ bytecode_artifact, skill_artifact?, map_artifact?, sha256, graduation_candidates: [...] }` |
272
+ | **`POST /api/v1/resolve`** | Resolve e empacota o contexto JIT filtrado por escopo e papel com orçamento estrito de tokens. | `{ tenant, squad, area, role, stacks: [...], max_tokens: 600 }` | `{ push_markdown, token_count, digest_sha256, applied_ids: [...], mcp_resources: [...] }` |
273
+ | **`POST /api/v1/gates/verify`** | Executa o `ContractGate` determinístico (JSON Schema + regras graduadas de `agent_constraints`). | `{ tenant, squad, stage, draft_payload }` | `{ passed: boolean, issues: [{ id, severity, field, message }] }` |
274
+ | **`GET /api/v1/artifacts/{type}/{id}`** | Recupera um artefato versionado (`bytecode`, `skill` ou `map`) com verificação de assinatura SHA-256. | Query params: `version`, `tenant` (autenticado por API Key de escopo) | `{ artifact, sha256, scope, updated_at }` |
275
+
276
+ ### 7.2. Interface do SDK Oficial (`cognitivebc` no npm e `cbc_client` em Python)
277
+
278
+ ```javascript
279
+ // SDK Node.js (pacote npm `cognitivebc` consumido pelo Synap-se)
280
+ const { CognitiveBCClient } = require('cognitivebc');
281
+
282
+ const cbc = new CognitiveBCClient({
283
+ baseUrl: process.env.COGNITIVEBC_URL || 'https://api.cognitivebc.io',
284
+ apiKey: process.env.COGNITIVEBC_API_KEY,
285
+ localFallbackDir: '/Users/fer/Projetos/synap-se/.synap-se/cbc-cache', // Offline-first cache
286
+ });
287
+
288
+ // 1. Resolução JIT em runtime-prepare.js
289
+ const packet = await cbc.resolve({
290
+ tenant: 'diario_glp1',
291
+ squad: 'mktsquad',
292
+ area: 'midias-organico',
293
+ role: 'roteirista',
294
+ stacks: ['scientific_3d_stack'],
295
+ maxTokens: 600,
296
+ });
297
+
298
+ // 2. Compilação a partir de fecho de tarefa ou ciclo detectado
299
+ const compiled = await cbc.compile({
300
+ regime: 'silent_multimodal',
301
+ scope: { squad: 'mktsquad', stack: 'scientific_3d_stack' },
302
+ inputPayload: cycleEvent,
303
+ });
304
+ ```
305
+
306
+ ---
307
+
308
+ ## 8. Liberdade Controlada via MCP (`@cognitivebc/mcp` + Ferramentas de Domínio)
309
+
310
+ Para eliminar a "caixa preta cega" (onde especialistas de pipeline faziam uma única chamada LLM sem poder consultar fatos adicionais ou pré-validar suas entregas) sem abrir `bash` irrestrito, o CognitiveBC define o padrão de **Liberdade Controlada em 3 Níveis de Permissão**:
311
+
312
+ | Camada | Conjunto de Ferramentas MCP | Ferramentas Expostas | Papéis Autorizados (`permitted_roles`) | Guardrails Determinísticos (Sandbox) |
313
+ | :--- | :--- | :--- | :--- | :--- |
314
+ | **Nível 1 · Cognição & Gates (`@cognitivebc/mcp-core`)** | Provido diretamente pelo CognitiveBC | • `cbc_pull_experience(scope, topic)`<br/>• `cbc_read_tenant_map(tenant, section)`<br/>• `cbc_check_gate_rules(stage, draft_json)` | Todos os especialistas (`planejador`, `roteirista`, `diretor_arte`, `construtor_3d`, `revisor`) | Somente leitura + validação determinística em memória (timeout `2s`, máx. `3` rodadas de tool-calling por etapa). |
315
+ | **Nível 2 · Especialista de Stack (`mcp_scientific_3d`)** | Provido pela Stack da BU (ex.: `mktsquad/scientific_3d_stack`) | • `list_3d_catalog(series)`<br/>• `inspect_pdb_structure(pdb_id)`<br/>• `inspect_zanatomy_collection(glb_name)`<br/>• `render_preview_strip(clip_id, script_path)` | `diretor_arte` (apenas catálogo) e `construtor_3d` (leitura + preview restrito à pasta `scientific_3d_stack/`) | Proibido `execute_blender_code` fora da pasta da stack; `render_preview_strip` força `--preview --t 0.15,0.5,0.85` (3 frames) com timeout de `45s`. |
316
+ | **Nível 3 · Fronteira Inter-BU (`mcp_bu_gateway`)** | Provido pelo Engine Synap-se ([ADR-0014 §6](file:///Users/fer/Projetos/synap-se/docs/adr/0014-arquitetura-de-operacao-das-bus.md#L112-L124)) | • `request_bu_deliverable(target_bu, contract_id, payload)`<br/>• `propose_external_action(capability, params, sha256_digest)` | Apenas `Coordenador` e `Heads` autorizados na matriz de conexões da BU | Exige conciliação SHA-256 e respeita a política de autonomia por etapa ([ADR-0016](file:///Users/fer/Projetos/synap-se/docs/adr/0016-politica-de-autonomia-das-equipes.md)). |
317
+
318
+ ---
319
+
320
+ ## 9. Protocolo Oficial de Validação Científica (`EXPERIMENT-005`)
321
+
322
+ Para validar o produto **CognitiveBC** de ponta a ponta sem nenhuma das 4 falhas metodológicas diagnosticadas no benchmark preliminar do Episódio 2:
323
+
324
+ 1. **Demanda Inédita Completa (Episódio 3 — *Diário GLP-1*):**
325
+ * Tema: *"O Efeito no Cérebro e no Estômago: Por que o esvaziamento gástrico lento muda a fome"*.
326
+ * Exige a **criação de código Python `bpy` novo e renderização real no Blender 5.0** de 2 clipes 3D inéditos:
327
+ * **Clipe A:** Parede do estômago (`Stomach` + `Oesophagus` do Z-Anatomy) com ondas peristálticas desacelerando e partículas douradas de GLP-1.
328
+ * **Clipe B:** Complexo molecular de semaglutida (`4ZGM.pdb`) acoplando ao receptor GLP-1R (`6X18.pdb`) com alfa-hélices visíveis em close-up.
329
+ 2. **Garantias de Rigor Experimental (As 4 Correções Obrigatórias):**
330
+ * **Blender Real no Loop:** Ambos os braços (Braço A *Cold Start* vs. Braço B *CognitiveBC API*) executam o agente `construtor_3d`, geram preview strips (`pv_*.jpg`), permitem até 2 ciclos de auto-inspeção e renderizam os `.mp4` finais antes da montagem no Remotion.
331
+ * **Igualdade Estrita de Schema desde o Turno 1:** O contrato JSON de entrada e saída é idêntico nos dois braços desde a primeira chamada, sem injetar dicas extras apenas no retry do Braço A.
332
+ * **Escolha Autônoma de Estratégia pelo Planejador:** O harness entrega apenas o briefing em linguagem natural; o Planejador do Braço B escolhe `estrategia="misto_3d"` autonomamente a partir do pacote resolvido pelo CognitiveBC.
333
+ * **Injeção JIT Filtrada por Papel via `POST /api/v1/resolve`:** O Roteirista recebe $\le 600$ tokens editoriais, eliminando o peso morto de tokens 3D no estágio textual.
334
+ 3. **Métricas de Aceite do Produto:**
335
+ * Aprovação na 1ª rodada em `gates.py` e no Revisor Grok.
336
+ * Ausência dos 6 defeitos visuais/topológicos nas imagens renderizadas pelo Blender 5.0 (dessaturação AgX, curva `Oesophagus` invisível, rasgos no `Stomach`, deslocamento por `o.scale`, hélice "salsicha" e quebra no `HETATM 32M`).
337
+ * Redução de $>80\%$ no overhead de tokens do Roteirista em comparação ao experimento sem filtro de papel, e redução de $>70\%$ no tempo/custo total de construção 3D em relação aos 429K tokens da sessão pioneira.
338
+
339
+ ---
340
+
341
+ ## 10. Estrutura do Repositório `performacia/cognitivebc` e Roadmap de Entrega
342
+
343
+ ```text
344
+ cognitivebc/ # Repositório: github.com/performacia/cognitivebc
345
+ ├── docs/
346
+ │ └── TECHNICAL_SPECIFICATION.md # Esta documentação técnica oficial
347
+ ├── packages/
348
+ │ ├── cbc-schema/ # Validador canônico cognitivebc/v1 (+ retrocompatibilidade synapse-eeii/v1 e v2)
349
+ │ ├── cbc-compiler/ # Compilador de 3 Regimes + Sanitizador Cross-Tenant + Detector de Ciclos
350
+ │ ├── cbc-resolver/ # Resolvedor JIT de 6 dimensões por Papel com Token Budgeter
351
+ │ ├── cbc-sdk-js/ # Pacote npm `cognitivebc` (Cliente HTTP + Cache Offline-First + Helpers)
352
+ │ └── cbc-mcp/ # Servidor MCP oficial (`@cognitivebc/mcp`)
353
+ ├── services/
354
+ │ └── cbc-api/ # Servidor HTTP `api.cognitivebc.io` (/api/v1/streams, /compile, /resolve, /gates)
355
+ ├── store/ # Catálogo inicial validado (Skills, Bytecodes de Stack e Templates)
356
+ └── benchmarks/
357
+ └── experiment-005/ # Suite de validação científica End-to-End (Episódio 3)
358
+ ```
359
+
360
+ | Etapa | Escopo no Produto `cognitivebc` e Conectores | Entregável Verificável |
361
+ | :--- | :--- | :--- |
362
+ | **Etapa C1** | **Core Schema `cognitivebc/v1`, Decomposição Tripla e SDK `cognitivebc@0.2.0`** | Validador suportando `cognitivebc/v1` + `synapse-eeii/v1..v2`, filtro por `target_roles` e pacote npm atualizado. |
363
+ | **Etapa C2** | **Serviço `cbc-api` (`/resolve`, `/compile`, `/streams/ingest`, `/gates/verify`)** | API rodando localmente e pronta para deploy em `api.cognitivebc.io` com os 3 artefatos da `scientific_3d_stack` carregados. |
364
+ | **Etapa C3** | **Conector no `mktsquad` (BU Aquisição) e no `synap-se`** | [perfil.py](file:///Users/fer/Projetos/mktsquad/orchestrator/perfil.py) e [producao.py](file:///Users/fer/Projetos/mktsquad/orchestrator/producao.py) no MktSquad + [experience-memory.js](file:///Users/fer/Projetos/synap-se/experience-memory.js) e [runtime-prepare.js](file:///Users/fer/Projetos/synap-se/runtime-prepare.js) no Synap-se consumindo o CognitiveBC via API/SDK com cache local. |
365
+ | **Etapa C4** | **Execução Completa do `EXPERIMENT-005`** | Geração do Episódio 3 com Blender 5.0 real no loop comprovando as métricas de qualidade, tempo e economia de tokens. |
@@ -0,0 +1,119 @@
1
+ # Graph and telemetry isolation contract
2
+
3
+ ## Graph inputs and authorization
4
+
5
+ `buildSemanticGraph(store, options)` accepts:
6
+
7
+ - `allowTenant(tenant)`: trusted caller authorization predicate. Every bytecode, map and ledger job is checked before creating roles, nodes, edges, timestamps or summaries. Missing bytecode/job tenants are passed as `null`. Default, when omitted, allows all tenants. This function does not itself authenticate requests.
8
+ - `tenant`: exact tenant selection, intersected with authorization. A selected tenant excludes unscoped artifacts/jobs. Authorization and selection are separate controls.
9
+ - `telemetry: false`: disables ledger loading, even when a file exists. An object supplies an explicit ledger with a `jobs` array.
10
+ - `telemetryFile`: explicit ledger path. Otherwise the only file considered is `<store.storeDir>/telemetry/ledger.json`. Stores without `storeDir` have no implicit ledger. No source-relative repository path is used.
11
+ - `telemetryTenantField: 'cliente'`: explicit legacy compatibility opt-in. Normally `job.tenant` is the sole tenant identity. With this option, missing `job.tenant` may use `job.cliente`. An explicit tenant always wins. There is never a first-map fallback.
12
+ - `catalog: false`: disables catalog loading. Any graph restricted by `allowTenant` or `tenant` disables the catalog entirely, including explicitly supplied catalogs, because global portfolio metadata has no tenant authorization contract.
13
+
14
+ Example for an authenticated caller:
15
+
16
+ ```js
17
+ const graph = buildSemanticGraph(store, {
18
+ allowTenant: tenant => tenant === authenticatedTenant,
19
+ tenant: authenticatedTenant,
20
+ catalog: false,
21
+ telemetryFile: configuredLedgerPath,
22
+ });
23
+ ```
24
+
25
+ Ledger jobs can include `id`, `tenant`, `titulo`, `estado`, `agentes`, `eventos_count`, `created_at`, `last_seen` and `amostra_eventos`. Deployment identity is not hardcoded. Global ledger source strings and global counters are not copied into a restricted graph. Event totals are recomputed from nonnegative safe integer `eventos_count` values on returned job nodes. They are reported counts, not proof that every event was independently audited.
26
+
27
+ Role matching is exact, never prefix-based. Every nonempty string in an authorized job's `agentes` is an observed role even without a squad or rule. Returned roles expose separate `observed` and `covered` flags. `covered` means an explicit `targets_role` edge to a returned rule/case, not evidence of successful execution. `observed_roles_count` and `covered_roles_count` summarize those edges separately. A role lens changes opacity, not authorization or node membership.
28
+
29
+ ### Explicit agents and durable observations
30
+
31
+ Durable receipt jobs can provide `project_id` and `observations: [{ agent_id, role, project_id, timestamp, event_id }]`. The graph consumes these after job tenant authorization. An observed role is created even if it has no knowledge rule or squad. An `agent` node is created only for a nonempty explicit `observation.agent_id`, with a tenant-qualified opaque ID. A role name, including legacy `job.agentes`, never establishes an agent identity. The same agent ID in different tenants yields separate nodes.
32
+
33
+ An explicit agent has `executed_session` edges to the sessions in which it was observed and `performs_role` edges to explicitly observed roles. Repeated observations do not create duplicate edges. Agent details retain its observed roles, project/session IDs, whitelisted observations and chronological first/last timestamps. `agents_count` and `observed_agents_count` count actual visible identity nodes. Roles expose their separate `observed` and `covered` flags on both nodes and the role-list response.
34
+
35
+ `/graph2` labels **Atividade observada** separately from **Cobertura de conhecimento**. Explicit agent identities use purple diamonds, while roles use green hexagons. Observed roles without an explicit rule edge have dashed borders and a detail message stating that no rule is linked in the current view. This does not mean a new role cannot resolve authorized general knowledge: the HTTP acceptance test ingests `project_id: balancing`, explicit agent `balancing-agent-1` and new role `project_balancer`, verifies the durable activity graph, then resolves a general wildcard rule successfully. General rules outside a selected graph view are not misreported as explicit role coverage.
36
+
37
+ The page preserves `tenant` and `project_id` URL parameters, provides manual refresh and reloads the graph on live activity so newly observed identities/roles can appear. Body-level explicit `role`, `agent_id` and `project_id` also survive usage telemetry recording. Missing agent identity remains null, never substituted with the role.
38
+
39
+ Unique artifact/job IDs retain their legacy graph IDs. Colliding rule IDs from different artifacts/tenants, stacks owned by different tenants, and job IDs from different tenants receive owner-qualified IDs instead of being silently merged. Consumers must treat graph IDs as opaque. IDs may differ between unrestricted and tenant-filtered views when a collision disappears.
40
+
41
+ Statistics, returned role lists and timeline bounds are computed from returned nodes/edges after portfolio selection. Inferred timestamps are assigned only after that selection, so excluded jobs do not set the visible timeline origin. `azure_jobs_count` and `azure_events_count` remain compatibility aliases of `jobs_count` and `events_count`, without implying any provider. `azure_source` is `null` rather than a stale/global source claim.
42
+
43
+ ## Local JSONL usage telemetry
44
+
45
+ `services/cbc-api/telemetry.js` writes `usage.jsonl` and `activity.jsonl` to `options.telemetryDir`, then `COGNITIVEBC_TELEMETRY_DIR`, then `~/.cognitivebc/telemetry`. Pass an isolated directory in tests. Passing `{ telemetry: false }` in the storage options disables both recording and `load`.
46
+
47
+ `load({ allowTenant, since }, storageOptions)` applies `allowTenant` to all valid records, including explicit null and missing tenants as `null`. Callers must supply their access policy. Invalid timestamps/JSON are ignored. Results are ordered chronologically, and `since` is exclusive.
48
+
49
+ `aggregate(records, { days: 30, now: Date.now() })` includes only recognized resolve/event records whose timestamps lie in the inclusive interval `[now - days * 86400000, now]`. This applies to all totals, rule/role/job/tenant counters, first/last timestamps and daily series, not just the chart. Future and expired rows are excluded. The exact end instant belongs to the final daily bucket. Invalid day counts fall back to 30, and valid counts are integers between 1 and 3660.
50
+
51
+ Token values must be nonnegative safe integers. Strings, fractions, negative numbers, infinities, NaN and out-of-range numbers contribute zero. Summation saturates at `Number.MAX_SAFE_INTEGER`. All keyed aggregate objects, including nested role/agent counters, have null prototypes, so literal `__proto__` and `constructor` identifiers are safe and serialize normally. First/last timestamps use chronological minima/maxima even for unsorted input. Aggregation does not mutate input order.
52
+
53
+ ### Compatibility correction
54
+
55
+ Previously `test/telemetry.test.js` described `rules.R1.count === 2` as a historical total even though its response declared a seven-day window containing only one resolve. The correct windowed expectation is `1`. Historical totals must be requested with a suitable explicit window, not mixed into a differently labeled window response.
56
+
57
+ ## Validation and measured scope
58
+
59
+ Run the real module/store regressions without starting an API server or writing source fixtures:
60
+
61
+ ```sh
62
+ node --test test/graph-isolation.test.js test/telemetry-contract.test.js
63
+ ```
64
+
65
+ These tests use disposable OS temporary directories and cover allowed/denied/unscoped tenants, disabled telemetry, explicit ledger paths, opt-in legacy tenant identity, exact roles, new roles without squads/rules, ID collisions, restricted catalog suppression, visible scope summaries, hostile object keys, invalid tokens, and old/future/unsorted dates.
66
+
67
+ The graph isolation test also uses real package exports and an authenticated ephemeral-port server for ingest → durable receipt → public `/api/v1/jobs` observation listing → a newly created server with a fresh `CognitiveStore` → explicit agent/new role graph → usage identity → authorized general resolve. This verifies that the graph survives server recreation rather than echoing in-memory ingestion state. The legacy `test/telemetry.test.js` is now isolated as well: its public/private stores, usage files, durable receipts and all optional ledger/export paths live under one disposable realpath temporary root, never the repository store.
68
+
69
+ Graph2 was additionally loaded from a disposable real server in an isolated headless Chrome profile. Actual rendered counts showed one explicit agent, one observed role, one session/event and zero explicit role coverage. Browser interactions opened the role details (observed, no linked rule) and the distinct agent details (explicit identity, balancing project/session and executed-session/performs-role neighbors), with no JavaScript runtime exceptions. No existing browser profile or global scripting permissions were changed.
70
+
71
+ Timestamp assignment now indexes jobs once with `Map` rather than calling `.find` for each job node. A narrow synthetic benchmark compared exported `assignTimestamps` from baseline `58b5f171a9a459b7cf66d6872d3a55e41a6e2f3f` against the changed module on macOS arm64, Node v22.23.0. Each sample used fresh legacy job nodes with empty details and matching ledger jobs, no links, one warm-up then seven timed runs. Median wall times on November 13, 2026 UTC:
72
+
73
+ | Job nodes | Baseline | Changed | Ratio |
74
+ | ---: | ---: | ---: | ---: |
75
+ | 1,000 | 7.52 ms | 1.02 ms | 7.36x |
76
+ | 5,000 | 143.59 ms | 5.36 ms | 26.78x |
77
+ | 10,000 | 515.31 ms | 9.83 ms | 52.44x |
78
+
79
+ These numbers measure only timestamp assignment on a synthetic fixture, not full graph generation, API throughput or production latency. A separate deep-equality check confirmed identical timestamp node outputs against the baseline for 1,000 legacy job nodes. No production workload was modified or benchmarked. The rest of timestamp sorting still has its existing cost.
80
+
81
+ Reproduce from the repository root, without writing files:
82
+
83
+ ```sh
84
+ node <<'NODE'
85
+ const { execFileSync } = require('child_process');
86
+ const Module = require('module');
87
+ const path = require('path');
88
+ const { performance } = require('perf_hooks');
89
+ const file = path.resolve('packages/cbc-resolver/graph-builder.js');
90
+ const baseline = new Module(file, module);
91
+ baseline.filename = file;
92
+ baseline.paths = module.paths;
93
+ baseline._compile(execFileSync('git', [
94
+ 'show', '58b5f171a9a459b7cf66d6872d3a55e41a6e2f3f:packages/cbc-resolver/graph-builder.js',
95
+ ], { encoding: 'utf8' }), file);
96
+ for (const size of [1000, 5000, 10000]) {
97
+ const jobs = Array.from({ length: size }, (_, i) => ({ id: String(i), created_at: '2026-11-01T00:00:00Z' }));
98
+ const measure = fn => {
99
+ const times = [];
100
+ for (let run = 0; run < 8; run++) {
101
+ const nodes = jobs.map(j => ({ id: `job:${j.id}`, type: 'production_job', details: {} }));
102
+ const t = performance.now();
103
+ fn(nodes, [], { jobs });
104
+ if (run) times.push(performance.now() - t);
105
+ }
106
+ return times.sort((a, b) => a - b)[3];
107
+ };
108
+ console.log({ size, before_ms: measure(baseline.exports.assignTimestamps), after_ms: measure(require(file).assignTimestamps) });
109
+ }
110
+ NODE
111
+ ```
112
+
113
+ ### Deliberate limitations
114
+
115
+ - Restricted graphs do not return portfolio metadata. Re-enabling it requires a separately defined tenant-aware catalog contract.
116
+ - Legacy unrestricted catalog linking assumes unique stack/job graph IDs. Owner-qualified collisions remain separate graph nodes, but the legacy linker does not infer portfolio attribution for these ambiguous IDs.
117
+ - Ledger job tenant declarations are authoritative input. This module does not validate an external producer's honesty or establish an upstream identity protocol.
118
+ - JSONL append errors remain best-effort and are not represented as successful durable delivery. The synchronous JSONL reader still reads the configured files in full.
119
+ - The graph lane's isolated checks do not alone represent the complete server suite. The coordinating task subsequently isolated the legacy fixtures and passed the complete 121-test suite, including a committed-source archive without uncommitted store changes. This still does not establish production daemon, LAN/proxy/firewall or live consumer-session acceptance.
package/index.js CHANGED
@@ -1,2 +1,27 @@
1
- // Cognitive Bytecode (CBC) runtime placeholder
2
- module.exports = { version: '0.1.0', schema: 'cognitivebc/v2' };
1
+ 'use strict';
2
+
3
+ const schema = require('./packages/cbc-schema');
4
+ const resolver = require('./packages/cbc-resolver');
5
+ const compiler = require('./packages/cbc-compiler');
6
+ const sdk = require('./packages/cbc-sdk-js/client');
7
+ const mcp = require('./packages/cbc-mcp');
8
+ const api = require('./services/cbc-api/server');
9
+ const { CognitiveStore } = require('./services/cbc-api/store-loader');
10
+ const { createIngestionService } = require('./services/cbc-api/ingestion-service');
11
+ const { captureRuntimeInfo } = require('./services/cbc-api/runtime-info');
12
+ const { resolveAuthorizedContext } = require('./services/cbc-api/context-service');
13
+
14
+ module.exports = {
15
+ version: '0.2.0',
16
+ schemaVersion: 'cognitivebc/v1',
17
+ ...schema,
18
+ ...resolver,
19
+ ...compiler,
20
+ ...sdk,
21
+ ...mcp,
22
+ ...api,
23
+ CognitiveStore,
24
+ createIngestionService,
25
+ captureRuntimeInfo,
26
+ resolveAuthorizedContext,
27
+ };
package/package.json CHANGED
@@ -1,12 +1,32 @@
1
1
  {
2
2
  "name": "cognitivebc",
3
- "version": "0.1.0",
4
- "description": "Cognitive Bytecode (CBC) \u2014 The Decision Encoding & Execution Substrate for Synap-se",
3
+ "version": "0.2.1",
4
+ "description": "Cognitive Bytecode (CBC) — The Decision Encoding & Execution Substrate for Synap-se",
5
5
  "main": "index.js",
6
+ "bin": {
7
+ "cognitivebc": "bin/cognitivebc.js",
8
+ "cbc-server": "bin/cbc-server.js"
9
+ },
10
+ "scripts": {
11
+ "start": "node bin/cbc-server.js",
12
+ "test": "node --test",
13
+ "benchmark": "node benchmarks/runner.js",
14
+ "benchmark:peers": "node benchmarks/peer-comparison",
15
+ "benchmark:exp005": "node benchmarks/experiment-005",
16
+ "benchmark:longmemeval": "node benchmarks/longmemeval-v2",
17
+ "benchmark:swebench": "node benchmarks/swebench-compounding",
18
+ "graph:export-obsidian": "node bin/cbc-export-obsidian.js",
19
+ "daemon:start": "./bin/cbc-daemon.sh start",
20
+ "daemon:stop": "./bin/cbc-daemon.sh stop",
21
+ "daemon:restart": "./bin/cbc-daemon.sh restart",
22
+ "daemon:status": "./bin/cbc-daemon.sh status",
23
+ "daemon:logs": "./bin/cbc-daemon.sh logs",
24
+ "cloud:bootstrap": "node bin/cbc-cloud-bootstrap.js"
25
+ },
6
26
  "homepage": "https://cognitivebc.io",
7
27
  "repository": {
8
28
  "type": "git",
9
- "url": "https://github.com/performacia/cognitivebc.git"
29
+ "url": "git+https://github.com/performacia/cognitivebc.git"
10
30
  },
11
31
  "keywords": [
12
32
  "cognitive-bytecode",
@@ -17,5 +37,25 @@
17
37
  "mcp"
18
38
  ],
19
39
  "author": "PerformacIA",
20
- "license": "MIT"
21
- }
40
+ "license": "Apache-2.0",
41
+ "files": [
42
+ "index.js",
43
+ "packages/",
44
+ "services/",
45
+ "bin/cbc-server.js",
46
+ "docs/",
47
+ "LICENSE",
48
+ "TERMS_OF_SERVICE.md",
49
+ "SECURITY.md",
50
+ "README.md",
51
+ "bin/cognitivebc.js",
52
+ "bin/cbc-cloud-bootstrap.js",
53
+ "bin/cbc-seed-projects.js"
54
+ ],
55
+ "dependencies": {
56
+ "@modelcontextprotocol/sdk": "^1.32.2",
57
+ "pg": "^8.23.1",
58
+ "yaml": "^2.9.1",
59
+ "zod": "^4.6.7"
60
+ }
61
+ }