arkaos 5.17.2 → 5.18.0

package/config/decisions/corpora/topic-drift.jsonl

@@ -0,0 +1,34 @@
+{"id": "td-pt-01", "lang": "pt", "prompt": "agora prepara o email de lançamento", "prior": ["corrige o bug do login"], "expected": true}
+{"id": "td-pt-02", "lang": "pt", "prompt": "escreve um post para o LinkedIn sobre o nosso novo produto", "prior": ["implementa a paginação na lista de encomendas", "adiciona testes à paginação"], "expected": true}
+{"id": "td-pt-03", "lang": "pt", "prompt": "configura o pipeline de CI no GitHub Actions", "prior": ["revê a proposta comercial para o ClienteY"], "expected": true}
+{"id": "td-pt-04", "lang": "pt", "prompt": "desenha um logótipo para a marca ProjetoX", "prior": ["analisa os custos de tokens desta semana"], "expected": true}
+{"id": "td-pt-05", "lang": "pt", "prompt": "qual é a melhor receita de bacalhau?", "prior": ["migra a base de dados para PostgreSQL 17"], "expected": true}
+{"id": "td-pt-06", "lang": "pt", "prompt": "corrige o erro de TypeScript no componente do checkout", "prior": ["prepara o orçamento do trimestre"], "expected": true}
+{"id": "td-pt-07", "lang": "pt", "prompt": "refatora o serviço de autenticação", "prior": ["escreve o guião do vídeo curto sobre produtividade"], "expected": true}
+{"id": "td-pt-08", "lang": "pt", "prompt": "faz a reconciliação das faturas de agosto", "prior": ["cria a landing page do webinar"], "expected": true}
+{"id": "td-pt-09", "lang": "pt", "prompt": "faz o planeamento financeiro do próximo ano", "prior": ["cria o componente do calendário"], "expected": true}
+{"id": "td-pt-10", "lang": "pt", "prompt": "e agora adiciona um teste para esse caso", "prior": ["corrige o bug do login"], "expected": false}
+{"id": "td-pt-11", "lang": "pt", "prompt": "usa 20 itens por página em vez de 50", "prior": ["implementa a paginação na lista de encomendas"], "expected": false}
+{"id": "td-pt-12", "lang": "pt", "prompt": "torna o assunto mais curto e direto", "prior": ["escreve o email de lançamento"], "expected": false}
+{"id": "td-pt-13", "lang": "pt", "prompt": "acrescenta uma secção de preços à proposta", "prior": ["revê a proposta para o ClienteY"], "expected": false}
+{"id": "td-pt-14", "lang": "pt", "prompt": "o job de testes falhou, vê o log", "prior": ["configura o pipeline de CI"], "expected": false}
+{"id": "td-pt-15", "lang": "pt", "prompt": "divide a análise do churn por plano", "prior": ["analisa o churn do último trimestre"], "expected": false}
+{"id": "td-pt-16", "lang": "pt", "prompt": "muda o título da landing para algo mais forte", "prior": ["cria a landing page do webinar"], "expected": false}
+{"id": "td-pt-17", "lang": "pt", "prompt": "não te esqueças dos índices na migração", "prior": ["migra a base de dados para PostgreSQL 17"], "expected": false}
+{"id": "td-pt-18", "lang": "pt", "prompt": "cria um script de backup", "prior": [], "expected": false}
+{"id": "td-pt-19", "lang": "pt", "prompt": "continua", "prior": ["corrige o bug do login", "adiciona teste ao login"], "expected": false}
+{"id": "td-pt-20", "lang": "pt", "prompt": "põe o calendário a começar à segunda-feira", "prior": ["cria o componente do calendário"], "expected": false}
+{"id": "td-en-01", "lang": "en", "prompt": "now draft the launch announcement for Twitter", "prior": ["fix the login redirect bug"], "expected": true}
+{"id": "td-en-02", "lang": "en", "prompt": "what's a good name for our podcast?", "prior": ["refactor the payment service into smaller classes"], "expected": true}
+{"id": "td-en-03", "lang": "en", "prompt": "write a cold email sequence for SaaS founders", "prior": ["set up the staging database"], "expected": true}
+{"id": "td-en-04", "lang": "en", "prompt": "debug the flaky websocket test in CI", "prior": ["review the pricing page copy"], "expected": true}
+{"id": "td-en-05", "lang": "en", "prompt": "design a colour palette for the brand refresh", "prior": ["plan the sprint backlog for next week"], "expected": true}
+{"id": "td-en-06", "lang": "en", "prompt": "negotiate the renewal terms with ClienteY", "prior": ["summarise the research notes on vector databases"], "expected": true}
+{"id": "td-en-07", "lang": "en", "prompt": "also add a regression test for it", "prior": ["fix the login redirect bug"], "expected": false}
+{"id": "td-en-08", "lang": "en", "prompt": "keep the public interface unchanged while you do it", "prior": ["refactor the payment service"], "expected": false}
+{"id": "td-en-09", "lang": "en", "prompt": "use the same credentials vault as production", "prior": ["set up the staging database"], "expected": false}
+{"id": "td-en-10", "lang": "en", "prompt": "make the headline shorter", "prior": ["review the pricing page copy"], "expected": false}
+{"id": "td-en-11", "lang": "en", "prompt": "move the auth stories to the top", "prior": ["plan the sprint backlog"], "expected": false}
+{"id": "td-en-12", "lang": "en", "prompt": "compare pgvector and Qdrant in a table", "prior": ["summarise the research notes on vector databases"], "expected": false}
+{"id": "td-en-13", "lang": "en", "prompt": "mention the new decisions layer first", "prior": ["write the release notes for v5.18"], "expected": false}
+{"id": "td-en-14", "lang": "en", "prompt": "now run the smoke tests against staging", "prior": ["deploy the api to staging"], "expected": false}

package/config/decisions/corpora/ui-in-ts.jsonl

@@ -0,0 +1,60 @@
+{"id": "ui-in-ts-01", "lang": "en", "prompt": "export {}", "context": {"path": "app/Button.styles.ts"}, "expected": true}
+{"id": "ui-in-ts-02", "lang": "en", "prompt": "export default {}", "context": {"path": "tailwind.config.ts"}, "expected": true}
+{"id": "ui-in-ts-03", "lang": "en", "prompt": "export const t = {}", "context": {"path": "src/theme.ts"}, "expected": true}
+{"id": "ui-in-ts-04", "lang": "en", "prompt": "el.className = \"btn btn-primary\"", "context": {"path": "app/render.ts"}, "expected": true}
+{"id": "ui-in-ts-05", "lang": "en", "prompt": "const Card = styled.div`padding: 4px`", "context": {"path": "app/card.ts"}, "expected": true}
+{"id": "ui-in-ts-06", "lang": "en", "prompt": "export const button = cva('btn', { variants: { size: { sm: 'h-8', lg: 'h-12' } } })", "context": {"path": "src/ui/variants.ts"}, "expected": true}
+{"id": "ui-in-ts-07", "lang": "en", "prompt": "// store do carrinho\nexport const useCart = defineStore('cart', { state: () => ({ items: [] }) })", "context": {"path": "app/stores/cart.ts"}, "expected": false}
+{"id": "ui-in-ts-08", "lang": "en", "prompt": "// cliente HTTP para a API de encomendas\nexport async function getOrders(): Promise<Order[]> {\n  const res = await fetch('/api/orders')\n  return res.json()\n}", "context": {"path": "src/api/orders.ts"}, "expected": false}
+{"id": "ui-in-ts-09", "lang": "en", "prompt": "// tipos partilhados\nexport interface Order { id: string; total: number }", "context": {"path": "src/types/order.ts"}, "expected": false}
+{"id": "ui-in-ts-10", "lang": "en", "prompt": "// script de build\nimport { build } from 'esbuild'\nawait build({ entryPoints: ['src/index.ts'], bundle: true })", "context": {"path": "scripts/build.mjs"}, "expected": false}
+{"id": "ui-in-ts-11", "lang": "en", "prompt": "// servidor Express\napp.get('/health', (_req, res) => res.json({ ok: true }))", "context": {"path": "server/index.js"}, "expected": false}
+{"id": "ui-in-ts-12", "lang": "en", "prompt": "// teste da função de soma\nimport { sum } from './sum'\ntest('soma', () => expect(sum(1, 2)).toBe(3))", "context": {"path": "src/sum.test.ts"}, "expected": false}
+{"id": "ui-in-ts-13", "lang": "pt", "prompt": "// composable que mostra um toast no ecrã\nexport function useToast() {\n  const el = document.createElement('div')\n  el.style.position = 'fixed'\n  el.style.bottom = '16px'\n  document.body.appendChild(el)\n  return (msg: string) => { el.textContent = msg }\n}", "context": {"path": "src/composables/useToast.ts"}, "expected": true}
+{"id": "ui-in-ts-14", "lang": "en", "prompt": "// animação do hero\nimport gsap from 'gsap'\ngsap.from('.hero h1', { y: 40, opacity: 0, duration: 0.8 })", "context": {"path": "src/animations/hero.ts"}, "expected": true}
+{"id": "ui-in-ts-15", "lang": "en", "prompt": "// tokens de design\nexport const colors = { zinc: { 900: '#18181b' }, rose: { 500: '#f43f5e' } }\nexport const radius = { md: '8px' }", "context": {"path": "src/design/tokens.ts"}, "expected": true}
+{"id": "ui-in-ts-16", "lang": "pt", "prompt": "// renderiza a tabela de preços\nexport function renderPricing(root: HTMLElement, plans: Plan[]) {\n  root.innerHTML = plans.map(p => `<article class=\"plan\"><h3>${p.name}</h3><p>${p.price}</p></article>`).join('')\n}", "context": {"path": "src/pricing/render.ts"}, "expected": true}
+{"id": "ui-in-ts-17", "lang": "en", "prompt": "// configuração do Vite\nimport { defineConfig } from 'vite'\nexport default defineConfig({ server: { port: 3399 } })", "context": {"path": "vite.config.ts"}, "expected": false}
+{"id": "ui-in-ts-18", "lang": "en", "prompt": "// validação com Zod\nexport const schema = z.object({ email: z.string().email() })", "context": {"path": "src/validation/signup.ts"}, "expected": false}
+{"id": "ui-in-ts-19", "lang": "en", "prompt": "// helper de datas\nexport const toIso = (d: Date) => d.toISOString().slice(0, 10)", "context": {"path": "src/utils/date.ts"}, "expected": false}
+{"id": "ui-in-ts-20", "lang": "en", "prompt": "// router do Vue\nexport default createRouter({ history: createWebHistory(), routes })", "context": {"path": "src/router/index.ts"}, "expected": false}
+{"id": "ui-in-ts-21", "lang": "en", "prompt": "// middleware de autenticação\nexport default defineNuxtRouteMiddleware((to) => { if (!useAuth().user) return navigateTo('/login') })", "context": {"path": "middleware/auth.ts"}, "expected": false}
+{"id": "ui-in-ts-22", "lang": "pt", "prompt": "// componente em render function\nimport { h } from 'vue'\nexport default { render: () => h('button', { class: 'rounded-md px-3 py-2' }, 'Guardar') }", "context": {"path": "src/components/SaveButton.ts"}, "expected": true}
+{"id": "ui-in-ts-23", "lang": "en", "prompt": "// preset do Tailwind da marca\nmodule.exports = { theme: { extend: { fontFamily: { sans: ['Space Grotesk'] } } } }", "context": {"path": "config/brand-preset.cjs"}, "expected": true}
+{"id": "ui-in-ts-24", "lang": "en", "prompt": "// variantes de classes\nexport const badge = (tone: 'ok' | 'err') => tone === 'ok' ? 'bg-emerald-100 text-emerald-800' : 'bg-rose-100 text-rose-800'", "context": {"path": "src/ui/badge.ts"}, "expected": true}
+{"id": "ui-in-ts-25", "lang": "en", "prompt": "// worker da fila de emails\nexport async function handle(job: Job) { await mailer.send(job.data) }", "context": {"path": "workers/email.ts"}, "expected": false}
+{"id": "ui-in-ts-26", "lang": "en", "prompt": "// migração de dados\nexport async function up(db: Db) { await db.schema.alterTable('orders', t => t.integer('total_cents')) }", "context": {"path": "migrations/20260924_total_cents.ts"}, "expected": false}
+{"id": "ui-in-ts-27", "lang": "en", "prompt": "import chalk from 'chalk'\nconsole.log(chalk.green('done'))", "context": {"path": "bin/cli.js"}, "expected": false}
+{"id": "ui-in-ts-28", "lang": "en", "prompt": "export function formatPrice(cents: number): string { return (cents / 100).toFixed(2) }", "context": {"path": "src/format.ts"}, "expected": false}
+{"id": "ui-in-ts-29", "lang": "en", "prompt": "const chart = new Chart(canvas, { type: 'bar', data, options: { plugins: { legend: { display: false } } } })", "context": {"path": "src/charts/revenue.ts"}, "expected": true}
+{"id": "ui-in-ts-30", "lang": "en", "prompt": "export const logger = pino({ level: process.env.LOG_LEVEL ?? 'info' })", "context": {"path": "src/logger.ts"}, "expected": false}
+{"id": "ui-in-ts-31", "lang": "en", "prompt": "document.querySelector('#menu')!.classList.toggle('open')", "context": {"path": "src/menu.js"}, "expected": true}
+{"id": "ui-in-ts-32", "lang": "en", "prompt": "export default defineEventHandler(async () => ({ status: 'ok' }))", "context": {"path": "server/api/health.ts"}, "expected": false}
+{"id": "ui-in-ts-33", "lang": "pt", "prompt": "// mostra uma mensagem quando a lista de encomendas está vazia\nimport { h, defineComponent } from 'vue'\nexport default defineComponent({ setup: () => () => h('p', { class: 'text-sm text-zinc-500' }, 'Ainda não tens encomendas.') })", "context": {"path": "src/components/EmptyState.ts"}, "expected": true}
+{"id": "ui-in-ts-34", "lang": "pt", "prompt": "export function avisar(msg: string) {\n  const el = document.createElement('div')\n  el.className = 'toast'\n  el.textContent = msg\n  document.body.append(el)\n}\navisar('As alterações foram guardadas.')", "context": {"path": "src/ui/toast.ts"}, "expected": true}
+{"id": "ui-in-ts-35", "lang": "pt", "prompt": "// cores da marca: o rosa só aparece em estados de alerta\nexport const cores = { fundo: '#09090b', texto: '#fafafa', alerta: '#f43f5e' }", "context": {"path": "src/theme/cores.ts"}, "expected": true}
+{"id": "ui-in-ts-36", "lang": "pt", "prompt": "// faz aparecer os cartões um a um quando entram no ecrã\nimport gsap from 'gsap'\ngsap.from('.cartao', { opacity: 0, y: 24, stagger: 0.1, scrollTrigger: '.grelha' })", "context": {"path": "src/animations/entrada.ts"}, "expected": true}
+{"id": "ui-in-ts-37", "lang": "pt", "prompt": "import { h } from 'vue'\nexport default { render: () => h('nav', { 'aria-label': 'Paginação' }, [h('button', { class: 'btn' }, 'Anterior'), h('button', { class: 'btn' }, 'Seguinte')]) }", "context": {"path": "src/components/Paginacao.ts"}, "expected": true}
+{"id": "ui-in-ts-38", "lang": "pt", "prompt": "// abre o diálogo de confirmação e bloqueia o scroll da página\nexport function confirmar(dialog: HTMLDialogElement) {\n  dialog.showModal()\n  document.body.style.overflow = 'hidden'\n}", "context": {"path": "src/dom/modal.ts"}, "expected": true}
+{"id": "ui-in-ts-39", "lang": "pt", "prompt": "// botão principal, com o contorno visível ao navegar pelo teclado\nexport const Botao = styled.button`\n  padding: 8px 16px;\n  &:focus-visible { outline: 2px solid #f43f5e; }\n`", "context": {"path": "src/styles/botao.ts"}, "expected": true}
+{"id": "ui-in-ts-40", "lang": "pt", "prompt": "// pago fica a verde, pendente fica a âmbar\nexport const classeEstado = (pago: boolean) =>\n  pago ? 'bg-emerald-100 text-emerald-800' : 'bg-amber-100 text-amber-800'", "context": {"path": "src/ui/estado.ts"}, "expected": true}
+{"id": "ui-in-ts-41", "lang": "pt", "prompt": "new Chart(canvas, { type: 'line', data, options: { plugins: { title: { display: true, text: 'Vendas por mês' } } } })", "context": {"path": "src/charts/vendas.ts"}, "expected": true}
+{"id": "ui-in-ts-42", "lang": "pt", "prompt": "export function montar(root: HTMLElement) {\n  root.innerHTML = `<label for=\"email\">Endereço de email</label><input id=\"email\" type=\"email\"><button>Subscrever</button>`\n}", "context": {"path": "src/forms/subscricao.ts"}, "expected": true}
+{"id": "ui-in-ts-43", "lang": "pt", "prompt": "// o título usa Space Grotesk; o texto corrido usa IBM Plex Sans\nexport default { theme: { extend: { fontFamily: { display: ['Space Grotesk'], sans: ['IBM Plex Sans'] } } } }", "context": {"path": "config/fonts.ts"}, "expected": true}
+{"id": "ui-in-ts-44", "lang": "pt", "prompt": "const banner = document.getElementById('manutencao')!\nbanner.hidden = false\nbanner.querySelector('p')!.textContent = 'Estamos em manutenção entre as 2h e as 4h.'", "context": {"path": "src/dom/banner.ts"}, "expected": true}
+{"id": "ui-in-ts-45", "lang": "pt", "prompt": "// devolve 404 quando a encomenda não existe\nexport default defineEventHandler(async (event) => {\n  const encomenda = await db.find(getRouterParam(event, 'id'))\n  if (!encomenda) throw createError({ statusCode: 404, statusMessage: 'Encomenda não encontrada' })\n  return encomenda\n})", "context": {"path": "server/api/encomendas/[id].ts"}, "expected": false}
+{"id": "ui-in-ts-46", "lang": "pt", "prompt": "// apaga os ficheiros temporários com mais de sete dias\nconst n = await removeOlderThan(tmpDir, 7)\nconsole.log(`Apaguei ${n} ficheiros temporários.`)", "context": {"path": "bin/limpar.js"}, "expected": false}
+{"id": "ui-in-ts-47", "lang": "pt", "prompt": "// guarda o utilizador autenticado e o token; não desenha nada\nexport const useSessao = defineStore('sessao', { state: () => ({ utilizador: null, token: '' }) })", "context": {"path": "src/stores/sessao.ts"}, "expected": false}
+{"id": "ui-in-ts-48", "lang": "pt", "prompt": "export const morada = z.object({\n  codigoPostal: z.string().regex(/^\\d{4}-\\d{3}$/, 'O código postal tem de ter o formato 0000-000'),\n})", "context": {"path": "src/validation/morada.ts"}, "expected": false}
+{"id": "ui-in-ts-49", "lang": "pt", "prompt": "import { comIva } from './iva'\ntest('aplica a taxa de IVA de 23 % ao preço base', () => expect(comIva(100)).toBe(123))", "context": {"path": "src/utils/iva.test.ts"}, "expected": false}
+{"id": "ui-in-ts-50", "lang": "pt", "prompt": "// gera o sitemap a partir das rotas publicadas e escreve-o em public/\nimport { writeFile } from 'node:fs/promises'\nawait writeFile('public/sitemap.xml', toXml(await rotasPublicadas()))", "context": {"path": "scripts/gerar-sitemap.mjs"}, "expected": false}
+{"id": "ui-in-ts-51", "lang": "pt", "prompt": "// envia a fatura por email quando o pagamento é confirmado\nexport async function handle(job: Job<{ faturaId: string }>) { await enviarFatura(job.data.faturaId) }", "context": {"path": "workers/faturas.ts"}, "expected": false}
+{"id": "ui-in-ts-52", "lang": "pt", "prompt": "// procura clientes pelo NIF; devolve uma lista vazia quando não há resultados\nexport async function porNif(nif: string): Promise<Cliente[]> {\n  const res = await fetch(`/api/clientes?nif=${nif}`)\n  return res.ok ? res.json() : []\n}", "context": {"path": "src/api/clientes.ts"}, "expected": false}
+{"id": "ui-in-ts-53", "lang": "pt", "prompt": "/** Estado da fatura: fica em rascunho até ser emitida e depois já não pode mudar. */\nexport type EstadoFatura = 'rascunho' | 'emitida'", "context": {"path": "src/types/fatura.ts"}, "expected": false}
+{"id": "ui-in-ts-54", "lang": "pt", "prompt": "export default defineEventHandler((event) => {\n  if (excedeuLimite(getRequestIP(event)))\n    throw createError({ statusCode: 429, statusMessage: 'Demasiados pedidos, tenta daqui a um minuto.' })\n})", "context": {"path": "server/middleware/limite.ts"}, "expected": false}
+{"id": "ui-in-ts-55", "lang": "pt", "prompt": "// regista a alteração para a auditoria, sem guardar a palavra-passe\nexport const registar = (id: string) => logger.info({ utilizador: id }, 'Palavra-passe alterada com sucesso')", "context": {"path": "src/auditoria.ts"}, "expected": false}
+{"id": "ui-in-ts-56", "lang": "pt", "prompt": "// acrescenta o código postal às moradas; as linhas antigas ficam a nulo\nexport async function up(db: Db) { await db.schema.alterTable('moradas', t => t.string('codigo_postal').nullable()) }", "context": {"path": "migrations/20260924_moradas.ts"}, "expected": false}
+{"id": "ui-in-ts-57", "lang": "pt", "prompt": "// em desenvolvimento, encaminha /api para o servidor local na porta 8000\nexport default defineConfig({ server: { proxy: { '/api': 'http://localhost:8000' } } })", "context": {"path": "vite.config.ts"}, "expected": false}
+{"id": "ui-in-ts-58", "lang": "pt", "prompt": "// formata cêntimos em euros com vírgula decimal, como se escreve em Portugal\nexport const euros = (c: number) => new Intl.NumberFormat('pt-PT', { style: 'currency', currency: 'EUR' }).format(c / 100)", "context": {"path": "src/utils/moeda.ts"}, "expected": false}
+{"id": "ui-in-ts-59", "lang": "pt", "prompt": "// todas as manhãs, lembra os clientes que têm faturas em atraso\nexport default defineTask({ meta: { name: 'lembretes' }, run: async () => ({ result: await lembrarAtrasos() }) })", "context": {"path": "server/cron/lembretes.ts"}, "expected": false}
+{"id": "ui-in-ts-60", "lang": "pt", "prompt": "// sincroniza o stock com o ERP e ignora os artigos descontinuados\nexport async function sincronizar(erp: Erp) {\n  for (const artigo of await erp.artigos())\n    if (!artigo.descontinuado) await db.stock.upsert(artigo.sku, artigo.quantidade)\n}", "context": {"path": "src/sync/stock.ts"}, "expected": false}

package/config/hooks/gate-manifest.json

@@ -681,6 +681,7 @@
     "enforcement_template": {
       "allow": true,
       "approval_state": "",
+      "bash_path": "",
       "bypass_used": false,
       "marker_found": null,
       "phase_observed": null,

package/config/models.yaml

@@ -27,8 +27,8 @@ providers:
     type: anthropic-direct  # SDK; needs ANTHROPIC_API_KEY
   ollama:
     type: ollama            # local models, http://localhost:11434
-  # openrouter:             # one key -> hundreds of models (Model Fabric PR-B)
-  #   type: openrouter
+  openrouter:               # one key -> hundreds of models; also the Jev decisions transport
+    type: openrouter        # needs OPENROUTER_API_KEY
 
 # ─── Aliases ────────────────────────────────────────────────────────────
 # `best` / `default` / `fast` resolve per provider, so roles stay readable.
@@ -68,3 +68,11 @@ fusion:
   #   - {provider: ollama, model: kimi-k2.6}
   #   - {provider: openrouter, model: deepseek/deepseek-v4-pro}
   #   - {provider: anthropic, model: best}
+
+# ─── Decisions (Jev typed classifier — not a role) ──────────────────────
+# Typed yes/no, choice and score answers for hooks, gates, Forge and
+# cognition (core/decisions/). No text generation, so never a role above.
+# Per-site modes (act | shadow | off) live in ~/.arkaos/config.json.
+decisions:
+  transport: openrouter   # only transport supported (operator decision 2026-09-23)
+  model: jev-1.13         # alias -> typesafe/jev-1.13 on OpenRouter

package/core/decisions/__init__.py

@@ -0,0 +1,8 @@
+"""Typed decisions layer — System 1 under the ArkaOS agents.
+
+A thin client for the OpenRouter Decisions endpoint (TypeSafe Jev):
+typed questions in (``noul`` / ``choice`` / ``score``), typed answers
+out, never generated text. Every call site keeps its heuristic as the
+unavailability fallback; :func:`core.decisions.engine.decide` never
+raises. See ADR ``docs/adr/2026-09-23-jev-decisions-layer.md``.
+"""

package/core/decisions/backoff.py

@@ -0,0 +1,137 @@
+"""Circuit breaker shared by every process: one JSON file under the cache.
+
+``trip`` records ``{"reason", "until"}``; ``blocked`` answers the reason
+while ``now < until``. A longer existing block is never shortened — unless
+another key set it: an ``http-401`` trip also records the key's
+fingerprint (:func:`~core.decisions.transport.key_fingerprint`), and
+rotating the key reopens the breaker at once (R-B1).
+Neither function raises — a broken breaker means "not blocked".
+
+Transport failures (``timeout`` / ``network``) trip it too, but only
+after :data:`FAILURE_TRIP_COUNT` in a row (``failures.json``, shared by
+every hook process): one slow turn is noise, three are an outage the
+next turns must not each pay for (QG r1 B2). A success clears the count;
+a count older than :data:`FAILURE_WINDOW_S` starts over.
+
+Directories this module creates are 0700 and its files 0600 (QG r1 m3).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+from core.decisions.paths import cache_root
+from core.decisions.transport import key_fingerprint
+
+# No caller trips for longer (client.py caps Retry-After at an hour); a
+# deadline further out is a corrupt or planted file, not a real trip,
+# and must neither block forever nor stop a real trip from landing.
+MAX_BLOCK_S = 3600.0
+FAILURE_TRIP_COUNT = 3
+FAILURE_BACKOFF_S = 60.0
+FAILURE_WINDOW_S = 600.0
+
+
+def _state_path() -> Path:
+    return cache_root() / "backoff.json"
+
+
+def _failures_path() -> Path:
+    return cache_root() / "failures.json"
+
+
+def ensure_private_dir(path: Path) -> None:
+    """``mkdir -p`` where every directory CREATED here is 0700."""
+    missing: list[Path] = []
+    probe = path
+    while not probe.exists() and probe != probe.parent:
+        missing.append(probe)
+        probe = probe.parent
+    for directory in reversed(missing):
+        with contextlib.suppress(FileExistsError):
+            directory.mkdir(mode=0o700)
+        os.chmod(directory, 0o700)  # mkdir's mode is masked by the umask
+
+
+def record_failure(reason: str, now: float | None = None) -> int:
+    """Count one transport failure; trip at the threshold. Never raises."""
+    ref = time.time() if now is None else now
+    try:
+        state = json.loads(_failures_path().read_text(encoding="utf-8"))
+        count = int(state["count"]) if ref - float(state["last"]) <= FAILURE_WINDOW_S else 0
+    except (OSError, ValueError, KeyError, TypeError):
+        count = 0
+    count += 1
+    if count >= FAILURE_TRIP_COUNT:
+        trip(reason, FAILURE_BACKOFF_S, now=ref)
+        record_success()
+        return count
+    with contextlib.suppress(OSError, ValueError):
+        _atomic_write(_failures_path(), {"count": count, "last": ref})
+    return count
+
+
+def record_success() -> None:
+    """A call went through: consecutive failures start from zero."""
+    with contextlib.suppress(OSError):
+        _failures_path().unlink(missing_ok=True)
+
+
+def _read() -> dict[str, object]:
+    try:
+        data = json.loads(_state_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def blocked(now: float | None = None) -> str | None:
+    """The trip reason while the breaker is open, else None."""
+    state = _read()
+    until = state.get("until")
+    if not isinstance(until, int | float) or _set_by_other_key(state):
+        return None
+    ref = time.time() if now is None else now
+    if ref >= until or until - ref > MAX_BLOCK_S:
+        return None
+    return str(state.get("reason") or "backoff")
+
+
+def trip(reason: str, seconds: float, now: float | None = None) -> None:
+    """Open the breaker for ``seconds``; keeps any later existing deadline."""
+    ref = time.time() if now is None else now
+    until = ref + min(max(0.0, float(seconds)), MAX_BLOCK_S)
+    state = _read()
+    current = state.get("until")
+    keep = not _set_by_other_key(state)
+    if keep and isinstance(current, int | float) and until < current <= ref + MAX_BLOCK_S:
+        return
+    payload: dict[str, object] = {"reason": reason, "until": until}
+    if reason == "http-401":
+        payload["key"] = key_fingerprint()
+    with contextlib.suppress(OSError, ValueError):
+        _atomic_write(_state_path(), payload)
+
+
+def _set_by_other_key(state: dict[str, object]) -> bool:
+    key = state.get("key")
+    return isinstance(key, str) and key != key_fingerprint()
+
+
+def _atomic_write(path: Path, payload: dict[str, object]) -> None:
+    ensure_private_dir(path.parent)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".backoff-", suffix=".tmp")
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise

package/core/decisions/cache.py

@@ -0,0 +1,92 @@
+"""Response cache keyed by sha256(model + prepared state + questions).
+
+Stores RESPONSES only — never the state. One file per key under
+``<cache_root>/<key[:2]>/<key>.json``, written tmp+rename with mode
+0600. Corrupt, expired or foreign files are a miss; nothing raises.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import re
+import tempfile
+import time
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from core.decisions.backoff import ensure_private_dir
+from core.decisions.models import DecisionResponse, Question, State
+from core.decisions.paths import cache_root
+
+_KEY_RE = re.compile(r"[0-9a-f]{64}")
+
+
+def cache_key(model: str, state: State, questions: dict[str, Question]) -> str:
+    """Deterministic sha256 over the canonical JSON of the request."""
+    canonical = json.dumps(
+        {
+            "model": model,
+            "state": state,
+            "questions": {k: q.to_payload() for k, q in questions.items()},
+        },
+        sort_keys=True,
+        ensure_ascii=False,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(canonical.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def _entry_path(key: str) -> Path | None:
+    if not _KEY_RE.fullmatch(key):
+        return None
+    return cache_root() / key[:2] / f"{key}.json"
+
+
+def get(key: str, ttl_s: float, now: float | None = None) -> DecisionResponse | None:
+    """The cached response while younger than ``ttl_s``, else None."""
+    path = _entry_path(key)
+    if path is None:
+        return None
+    try:
+        entry = json.loads(path.read_text(encoding="utf-8"))
+        stored_at = float(entry["stored_at"])
+        response = DecisionResponse.model_validate(entry["response"])
+    except (OSError, ValueError, KeyError, TypeError, ValidationError):
+        return None
+    ref = time.time() if now is None else now
+    if ttl_s <= 0 or ref - stored_at > ttl_s:
+        return None
+    return response
+
+
+def put(key: str, response: DecisionResponse, now: float | None = None) -> bool:
+    """Store one response atomically; False when it could not."""
+    path = _entry_path(key)
+    if path is None:
+        return False
+    stored_at = time.time() if now is None else now
+    payload = {"stored_at": stored_at, "response": response.model_dump(mode="json")}
+    try:
+        _atomic_write(path, payload)
+    except (OSError, ValueError, TypeError):
+        return False
+    return True
+
+
+def _atomic_write(path: Path, payload: dict[str, object]) -> None:
+    # Every directory created on the way is 0700, not the umask default.
+    ensure_private_dir(path.parent)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".entry-", suffix=".tmp")
+    try:
+        os.fchmod(fd, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, ensure_ascii=False)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise

package/core/decisions/client.py

@@ -0,0 +1,191 @@
+"""Stdlib client for ``POST /api/alpha/decisions``.
+
+:func:`post_decision` raises ONLY :class:`DecisionUnavailable`; its
+``reason`` is the stable telemetry vocabulary:
+
+``no-transport`` | ``bypassed`` | ``backoff`` | ``deadline`` |
+``egress-denied:<kind>`` | ``timeout`` | ``network`` | ``http-401`` |
+``http-422`` | ``http-429`` | ``http-529`` | ``http-<n>`` |
+``invalid-json`` | ``invalid-shape`` | ``redirected``.
+
+A failure decided on this machine is raised with ``local=True``; the
+replay harness reads it through :meth:`DecisionUnavailable.run_reason` as
+``<reason>:local`` (``invalid-shape:local`` for a state or body that
+cannot be serialised, ``timeout:local`` for the wall-clock deadline) and
+never counts it as a call that reached the endpoint. Live telemetry keeps
+the bare ``reason`` above.
+
+401/429/529 also trip the shared circuit breaker (``backoff.py``);
+``timeout``/``network`` count towards it (3 in a row trip it for 60 s)
+and a success clears the count.
+
+Deadline: ``urlopen(timeout=)`` bounds each socket operation, not the
+call — DNS is not covered and a server dripping one byte every 0.4 s
+held a 1 s call for 11.4 s (QG r1 B1). The exchange runs in a daemon
+thread joined against a monotonic deadline; past it the call is
+``timeout`` and the thread is abandoned. The thread only fetches bytes:
+parsing, cache, breaker and telemetry all happen on the caller's side,
+so an abandoned thread can write nothing.
+
+Redirects: urllib turns a 301/302/303 answer to a POST into a GET and
+copies every non-content header to whatever host ``Location`` names —
+the Bearer key included (reproduced against two local servers in the
+2026-09-23 security review). ``Authorization`` therefore travels as an
+UNREDIRECTED header (urllib never copies those), the body is dropped
+by urllib itself, and a response whose final URL differs from the one
+requested is refused (``redirected``) so another host cannot answer.
+307/308 to a POST already surface as ``http-307``/``http-308``.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+
+from pydantic import ValidationError
+
+from core.decisions import backoff
+from core.decisions.models import DecisionRequest, DecisionResponse
+from core.decisions.transport import Transport
+
+BACKOFF_401_S = 3600.0
+BACKOFF_429_DEFAULT_S = 60.0
+BACKOFF_529_S = 120.0
+MAX_RETRY_AFTER_S = 3600.0
+
+
+# The ``:<cause>`` suffix of a reason decided locally (see run_reason).
+LOCAL_MARK = "local"
+
+
+class DecisionUnavailable(Exception):  # noqa: N818 — contract name from the ADR
+    """No typed answer this time; the caller uses its heuristic."""
+
+    def __init__(self, reason: str, detail: str = "", *, local: bool = False) -> None:
+        super().__init__(f"{reason}: {detail}" if detail else reason)
+        self.reason = reason
+        self.detail = detail
+        self.local = local
+
+    def run_reason(self) -> str:
+        """``reason``, suffixed ``:local`` when this machine decided it."""
+        return f"{self.reason}:{LOCAL_MARK}" if self.local else self.reason
+
+
+def post_decision(
+    transport: Transport, request: DecisionRequest, timeout_s: float
+) -> tuple[DecisionResponse, int]:
+    """POST one request; ``(response, latency_ms)`` or DecisionUnavailable."""
+    try:
+        payload = {**request.to_payload(), **transport.body_extras}
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise DecisionUnavailable("invalid-shape", type(exc).__name__, local=True) from exc
+    req = _request(transport, body)
+    start = time.monotonic()
+    try:
+        raw = _send_by_deadline(req, timeout_s)
+    except DecisionUnavailable as exc:
+        if exc.reason in ("timeout", "network"):
+            backoff.record_failure(exc.reason)
+        raise
+    latency_ms = int((time.monotonic() - start) * 1000)
+    response = _parse(raw)
+    backoff.record_success()
+    return response, latency_ms
+
+
+def _request(transport: Transport, body: bytes) -> urllib.request.Request:
+    headers = {k: v for k, v in transport.headers.items() if k.lower() != "authorization"}
+    req = urllib.request.Request(transport.url, data=body, headers=headers, method="POST")
+    for name, value in transport.headers.items():
+        if name.lower() == "authorization":
+            req.add_unredirected_header(name, value)
+    return req
+
+
+def _send_by_deadline(req: urllib.request.Request, timeout_s: float) -> bytes:
+    """``_send`` bounded by wall clock, not per socket operation."""
+    box: dict[str, object] = {}
+
+    def worker() -> None:
+        try:
+            box["data"] = _send(req, timeout_s)
+        except BaseException as exc:  # handed to the caller, never lost
+            box["error"] = exc
+
+    thread = threading.Thread(target=worker, name="arka-decision", daemon=True)
+    thread.start()
+    thread.join(max(0.0, timeout_s))
+    if thread.is_alive():
+        # Not closed from here: HTTPResponse.close() waits on the reader
+        # lock the dripping read holds, so it would block the caller for
+        # the whole drip (measured: 11.7 s). The daemon thread ends with
+        # the socket or the process; it holds bytes only.
+        raise DecisionUnavailable("timeout", "deadline", local=True)
+    error = box.get("error")
+    if isinstance(error, urllib.error.HTTPError):
+        raise _map_http_error(error) from error
+    if isinstance(error, BaseException):
+        raise error
+    data = box.get("data")
+    return data if isinstance(data, bytes) else b""
+
+
+def _send(req: urllib.request.Request, timeout_s: float) -> bytes:
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            final = getattr(resp, "url", None)
+            if isinstance(final, str) and final != req.full_url:
+                raise DecisionUnavailable("redirected")
+            data: bytes = resp.read()
+            return data
+    except DecisionUnavailable:
+        raise
+    except urllib.error.HTTPError:
+        raise  # mapped on the caller's side: the breaker is never tripped late
+    except urllib.error.URLError as exc:
+        reason = "timeout" if isinstance(exc.reason, TimeoutError) else "network"
+        raise DecisionUnavailable(reason, str(exc.reason)) from exc
+    except TimeoutError as exc:
+        raise DecisionUnavailable("timeout") from exc
+    except Exception as exc:
+        raise DecisionUnavailable("network", type(exc).__name__) from exc
+
+
+def _map_http_error(exc: urllib.error.HTTPError) -> DecisionUnavailable:
+    code = int(exc.code)
+    if code == 401:
+        backoff.trip("http-401", BACKOFF_401_S)
+    elif code == 429:
+        backoff.trip("http-429", _retry_after(exc))
+    elif code == 529:
+        backoff.trip("http-529", BACKOFF_529_S)
+    return DecisionUnavailable(f"http-{code}", str(exc.reason or ""))
+
+
+def _retry_after(exc: urllib.error.HTTPError) -> float:
+    raw = exc.headers.get("Retry-After") if exc.headers is not None else None
+    try:
+        seconds = float(str(raw).strip())
+    except (TypeError, ValueError):
+        return BACKOFF_429_DEFAULT_S
+    if seconds <= 0:
+        return BACKOFF_429_DEFAULT_S
+    return min(seconds, MAX_RETRY_AFTER_S)
+
+
+def _parse(raw: bytes) -> DecisionResponse:
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise DecisionUnavailable("invalid-json", type(exc).__name__) from exc
+    if not isinstance(data, dict):
+        raise DecisionUnavailable("invalid-shape", "body is not an object")
+    try:
+        return DecisionResponse.model_validate(data)
+    except ValidationError as exc:
+        raise DecisionUnavailable("invalid-shape", f"{exc.error_count()} errors") from exc