Learn Alembic Complete v3 · Visual Course

Glossário visual — 24 termos da casa

O vocabulário vivo do Alembic em cartões: definição de duas frases + um ícone-diagrama por termo + a âncora que prova. Busque, filtre por grupo, e cobre este vocabulário de qualquer PR que entrar.

alembic-completo · 0008-glossario-visual · s0

Você sai daqui sabendo

Usar os 24 termos com o significado EXATO da casa (residue não é lixo; learning não é fato).
Apontar a âncora de cada termo (arquivo:linha ou comando) quando alguém duvidar.
Agrupar o vocabulário em três famílias: funil/conhecimento, employee/memória, operação/invariantes.

Como usar

Cada cartão tem três andares: o ícone-diagrama (a forma do conceito), a definição em duas frases (o que é + o detalhe que evita o erro comum) e a âncora (onde provar). Vocabulário compartilhado é o que deixa um time — humano ou de agentes — discutir sem tradução.

Pense como… a parede de ferramentas de uma oficina: cada silhueta desenhada atrás do gancho diz o que mora ali. Onde quebra: ferramenta emprestada volta; termo mal usado se espalha — por isso cada cartão traz a âncora.

Os 24 termos

Funil & Conhecimento

funil funil

O pipeline de destilação em tiers: T0 determinístico e $0 toca 100% do corpus, e cada tier acima toca cada vez menos, cada vez mais caro. O desenho inteiro existe para o modelo caro ver só o que sobreviveu aos filtros baratos.

alembic distill <corpus> --offline · packages/harness/src/funnel.ts

residue funil

O que o T0 não resolveu com confiança e sobe para o T1 carregando a proveniência junto — sobra qualificada, não lixo. Residue 0 num corpus grande é sintoma (family-prefix), não sucesso.

funnel.ts:117 (extraído no T1) · funnel.ts:195 (proveniência)

signal funil

A unidade da cadeia de NEGÓCIO: uma oportunidade extraída do corpus e emitida como aresta em Business/opportunity-graph.jsonl (hoje 2.589). É fato de pipeline com dono e origem — não confundir com learning, que é conhecimento.

alembic status · Business/opportunity-graph.jsonl (2.589)

learning funil

A unidade da SEGUNDA cadeia (ADR-0002): um aprendizado destilado com sourceRefs+hash de proveniência, gravado em Skills/learning/learnings.jsonl. A primeira produção real (06-07) rendeu 1.022 únicos, confidence μ0.94, isolados em ~/.alembic-learnings-bkm.

alembic distill … --learnings-budget <usd> · linha learnings-route:

family-prefix funil

A família de um item vem do primeiro segmento do path relativo ao corpus — por isso o distill aponta no PAI de Resources. Apontar na raiz da própria família rebaixa tudo a Unknown ⇒ residue 0, silencioso (o gotcha que custou o primeiro run da rota learnings).

prova: distill no PAI vs na raiz da família · escopo 1 família = truque cpio

tie-break funil

Empate de custo no registry não sorteia: o reduce de pickCheapestForTier usa < estrito, então o primeiro declarado vence. Foi o prereq do PR #157 — declarar gemini-3.5-flash antes do deepseek-v4-pro (AccessDenied) no empate de 0.0005.

packages/contracts/src/registry.ts:244-257 (entryCost < bestCost)

RAG read-path funil

A leitura do RAG offline: alembic search embeda a query com o MESMO backend do índice e ranqueia por cosseno, determinístico e $0 (desempate por chunk_id). Índice ausente é resultado vazio, não erro; embed-index escreve, search lê.

packages/embeddings/src/query.ts:10-13 · alembic search "<q>" <família>

ContextPack L0–L7 funil

O pacote de contexto em 8 camadas (L0–L7) do alembic context-pack, com createdAt vindo do clock do CLI. Retrieval é OPT-IN: --retrieve injeta os chunks mais próximos no L3 (com --rerank mmr opcional); sem a flag, o pack é byte-idêntico ao de antes.

alembic context-pack <files> --retrieve "<q>" --family Bookmarks

Employee & Memória

harness · 0006-contexto-memoria-rag · s0

soul employee

A identidade do employee: quem ele é, como fala e que modelos prefere. O modelId do turno resolve soul.modelPreferences.primary ?? fallback ?? local-default — e como employee run não tem failover em runtime, o modelo que funciona PRECISA ser o primary.

alembic employee show <id> · ~/.alembic/employees (43 hoje)

skill playbook employee

O CORPO completo de cada skill bindada, injetado no prompt como seção ## Skill Playbooks via SkillStore — para o modelo seguir as regras, não só ver os nomes. Best-effort: skill que não carrega é pulada; sem skills bindadas, a seção não existe.

packages/hermes/src/employee/run.ts:162, :281 (composeSkillsText)

substore employee

Uma das cinco lojas append-only da memória multi-store: episodic | semantic | procedural | decision | transcript, cada uma um JSONL em <dataDir>/memory/. O turno do employee consulta SÓ os substores bindados — o resto não vaza.

alembic memory <substore> add|list · <dataDir>/memory/<substore>.jsonl

A3b employee

O write-back honesto do turno --online: UM registro episódico com o goal REAL e um excerpt REAL da resposta — nunca um "learning" fabricado. Opt-in (sem binding episódico = no-op), --no-memory-write desliga, e falha de escrita jamais quebra o turno.

packages/hermes/src/employee/writeback.ts:5-14 (recordEmployeeTurn)

A4 / A4c employee

A4 mapeia schedule[] do employee em manifests automation.toml com id emp-<id>-<i>, cron como rrule e status PAUSED — registrável, nunca auto-roda. A4c (automation run, PR #159) EXECUTA um manifest: dry-run default, --online roda o turno e appenda 1 registro honesto ao journal; não é daemon.

apps/cli/src/employee-schedule.ts:42 (PAUSED), :75 (emp-<id>-<i>)

journal employee

O diário append-only de uma automation: o memory.md que recebe UM registro honesto por execução --online — o que rodou e o que o modelo respondeu, nunca uma ação inventada. É o mesmo princípio do journal do swarm: registrar antes de confiar.

alembic automation show <id> · journal memory.md (A4c, PR #159)

STATE file employee

O coração da gramática comum das 28 loop-skills: um estado append-only que carrega cadência, a regra de UMA unidade por run, stop rules e tiers green/yellow/red. A skill não "lembra" — ela relê o STATE e decide a próxima unidade a partir dele.

biblioteca de 28 loop-skills (8 marketing + 8 receita + 7 ops + 3 frameworks)

tier de autonomia employee

A escala de quanta supervisão humana uma unidade exige: T1/T2 rodam autônomos no modelo mais barato do tier, T3 passa por council, e T4 não roda — estaciona para decisão humana. Tier é sobre risco e reversibilidade, não sobre tamanho do modelo.

Tier enum @alembic/contracts · h.agent(prompt, { tier: 'T2' })

Operação & Invariantes

proof gate operação

Cada string de unit.proof[] vira uma task bash -c dependente da unidade; exit não-zero derruba o run, fail-closed. As provas ficam persistidas em units/<id>/proof-results.jsonl — progresso sem prova não existe.

packages/coda/src/proof.ts · units/<id>/proof-results.jsonl

T4 park operação

O destino de tarefa irreversível/sensível: classifyPark a estaciona em vez de rodar, e ela só volta pelo humano — alembic approve/reject (gravados em approvals.jsonl/rejections.jsonl) ou alembic propose para reabrir como proposta. Autonomia PARA na fronteira do irreversível.

alembic propose <run-id> · approve/reject --task-id <unit-id>

coordinated operação

O passe opt-in --coordinated: um veredito multi-lens por risco, ADITIVO, gravado em units/<id>/coordinated-verdict.json. Ele NUNCA muda a decisão do council e NUNCA falha o run — é observação extra, não gate novo.

packages/coda/src/coordinated-validator.ts · alembic run --coordinated

floor operação

O piso determinístico do veredito coordinated: sem adapter offline disponível, o gate roda floor-only — entrega o mínimo garantido em vez de fingir uma lente que não rodou. Degradar com honestidade é melhor que enfeitar com fabricação.

runCoordinatedValidatorGate (floor-only when offline adapter absent)

dupla trava operação

O contrato de gasto da marketing factory: renderização paga exige --approve E --yes juntos — uma flag sozinha continua no preview $0 com estimateCost primeiro. Duas chaves porque dinheiro não volta: é a versão financeira do fail-closed.

packages/marketing-factory/src/ads.ts:173 (?? true), :245 (|| !approve)

medias ROLED operação

O desbloqueio das referências reais no gemini_omni: o CLI rejeita --image flat, então o caminho pago anexa cada asset como medias:[{role:'image',…}] pela API direta da Higgsfield. Provado na fronteira — a parede e o logo REAIS do escritório da C.D apareceram no render 720×1280.

packages/marketing-factory/src/higgsfield-api.ts:19-21, :81-93

derive-counts operação

A disciplina de nunca digitar contagens: scripts/derive-counts.mjs (PR #158) deriva os números da fonte e compara com os docs. Nasceu do digest #1 do failure-historian e pegou drift vivo na primeira execução — docs diziam 32; o real era 33 comandos / 47 formas.

node scripts/derive-counts.mjs · ciclo autonômico (spec item 8)

squash-illusion operação

O efeito colateral do squash-merge: a história da branch é achatada num commit novo, então git merge-base --is-ancestor e git cherry respondem ERRADO sobre "já está na main?". A única testemunha confiável é o log da própria main (procure o título do PR).

git log main --oneline | grep "<título do PR>" (nunca is-ancestor pós-squash)

Camada técnica

# percorra o vocabulário na fronteira real ($0)
alembic status                                        # signal/learning stores
alembic search "budget fail-closed" Bookmarks         # RAG read-path
alembic memory semantic list --limit 3                # substore + provenance distilled:
alembic employee explain <id> --goal "triagem"        # observed/inferred/unknown
alembic runs list && alembic tail <run-id>            # proof gate + T4 park ao vivo
node scripts/derive-counts.mjs                        # derive-counts

Checagem rápida

Dois flashes de vocabulário

Um relatório de run mostra residue: 0 num corpus de 330GB. Qual termo do glossário explica o provável culpado?

Residue 0 + exit 0 + corpus grande = assinatura do family-prefix: a família saiu do 1º segmento errado, virou Unknown, nada roteou. O tie-break derrubaria o T2 (não o residue), e proof gate é do runner de missões, não do funil.

Qual par de termos separa FATO de INTERPRETAÇÃO na memória do sistema?

O transcript importado é o que FOI dito (fato, id determinístico, at da fonte); o registro destilado é interpretação de modelo e nasce marcado: session:+distilled: à prova de spoof e confidence 0.4 (≤ 0.5). Signal e learning são de cadeias diferentes, mas ambos têm proveniência — não é esse o eixo.

Acertos: 0/2

Feche o ciclo: escolha 3 termos que você usaria errado ontem e conte a alguém a diferença. Próxima parada: Drills do operador — os cenários onde este vocabulário vira decisão às 2h da manhã.