Motor de wiki — arquivos com esquema, wikilinks e síntese

O motor de wiki dá a cada arquivo um modelo de instrução de três níveis: regras duras aplicadas pelo código, um prompt de esquema por arquivo (linhas-guia editoriais advisory) e campos estruturados (persona, purpose, scope). Modelo mental: schemaPrompt está para o wiki assim como um CLAUDE.md está para o código de um repo.

Funcionalidade Community. Referência operativa para o Wiki Schema Layer (Phase 187, auditada na barreira v0.25 — WIKS-01/02, verificada contra o código em execução). Fonte: docs/WIKI_SCHEMA_LAYER.md (v0.28.1). Linhas de proveniência: FACT-CENSUS.md F-WIKI-1.

O modelo de 3 níveis

Regras duras (code-enforced)

Dois mecanismos incondicionais, independentes de qualquer configuração:

1. A guarda do sistema de ficheiros. validateWritablePath (packages/server/src/utils/archivePath.ts:39-54) rejeita qualquer alvo de escrita fora de <archiveBase>/wiki/: primeiro o controlo anti-traversal (validateArchivePath), depois o controlo do prefixo wiki/ — um alvo fora de wiki/ lança Write target outside wiki/ directory: <path>. raw_sources/ is immutable. Tanto createPage como updatePage a invocam antes de qualquer fs.writeFile. Nenhum endpoint da API escreve sob raw_sources/ — é imutável por design.
2. O espelho ao nível do prompt. HARD_RULE_RAW_SOURCES (archiveConfigService.ts:52-53) é um bloco sempre ativo acrescentado a cada prompt ligado ao arquivo: o seu texto reflete a guarda (raw_sources/ is immutable), de modo que o modelo nunca sequer tenta a saída fora de wiki/ — e se o fizesse, o código garante que nada aterra.

schemaPrompt (advisory)

Um campo de texto livre persistido no JSON de configuração do arquivo:

• Esquema: schemaPrompt: z.string().max(10000).optional() em archiveConfigSchema — uma chave aditiva, zero migrações. 10000 caracteres ≈ ~2500 tokens.
• Validação: Zod em cada escrita (PUT /api/archives/:id/config); um payload acima do teto → 400 { error: "Invalid config", details.schemaPrompt }.
• Contrato de leitura: GET /api/archives/:id/config sobre um arquivo sem linha armazenada → 200 com a configuração predefinida do esquema ({ rawSourcesImmutable: true }): é o caminho de hidratação da primeira gravação; arquivos com linha devolvem o blob armazenado tal como está.
• O teto na injeção: blobs legados com mais de 10000 caracteres são truncados na injeção com a anotação (truncated at 10000 characters) — as linhas legadas nunca são revalidadas na leitura.
• Advisory por design: o bloco entra como DADO com uma etiqueta advisory explícita, nunca como uma concessão de privilégios do system prompt. Sem sanitização para além do teto de comprimento; instruções contraditórias = um risco de qualidade aceite, mitigado pelas ajuda e templates da UI.

Precedência

regras duras (código) > schemaPrompt (advisory) > campos estruturados

1. schemaPrompt nunca pode sobrepor-se às regras duras (o prompt declara-o; o código impõe-o).
2. Em conflito com os campos estruturados, schemaPrompt vence (On conflict with the structured fields (persona, purpose, scope), these guidelines take precedence over them.).
3. Um arquivo sem schemaPrompt comporta-se como baseline + regra dura — zero melhoria, zero degradação (sem seções de marcador vazias nos prompts).

Onde o bloco aterra no prompt

Dentro do system prompt: depois do bloco MANDATORY SEARCH RULE, antes do ternário systemPrompt.

wiki_query e wiki_write

Os builtins wiki_query e wiki_write são skills cujas rotas execute() nunca fazem nenhuma chamada à LLM: a escrita gera previews deterministas (wikiWriteService.ts não contém invocações LLM) — a injeção por skill não alcançaria nenhum modelo; a única superfície voltada à LLM é o system prompt do orchestrator.

rawSourcesImmutable

rawSourcesImmutable: boolean (por defeito true) em archiveConfigSchema é uma bandeira de documentação, nunca um interruptor de aplicação: a regra de imutabilidade aplica-se independentemente da bandeira (a guarda validateWritablePath + o bloco sempre ativo garantem-na).

Este guia cobre a superfície operacional do motor de wiki; a profundidade técnica vive no post gémeo:

• A profundidade técnica

Provenance

---

Referência operativa — Simmetric Chat v0.28.1 (documentos atualizados a 2026-10-02, SHA do census `aca5b8ff`).