Wiki knowledge engine — archivi con schema, wikilink e synth

Il wiki engine dà a ogni archivio tre livelli di istruzione: regole hard enforce dal codice, uno schema prompt per-archivio (linee guida editoriali advisory) e campi strutturati (persona, purpose, scope). Modello mentale: lo schemaPrompt sta al wiki come un CLAUDE.md sta al codice di una repo.

Funzione Community. Documento di riferimento operativo per il Wiki Schema Layer (Phase 187, auditato al gate v0.25 — WIKS-01/02, verificato sul codice live). Fonte: docs/WIKI_SCHEMA_LAYER.md (v0.28.1). Righe di provenienza: FACT-CENSUS.md F-WIKI-1.

Il modello a 3 livelli

Regole hard (code-enforced)

Due meccanismi incondizionati, indipendenti da qualsiasi configurazione:

1. Guardia filesystem. validateWritablePath (packages/server/src/utils/archivePath.ts:39-54) rifiuta qualunque target di scrittura fuori da <archiveBase>/wiki/: prima l'anti-traversal (validateArchivePath), poi il check sul prefisso wiki/ — un target fuori da wiki/ produce l'errore Write target outside wiki/ directory: <path>. raw_sources/ is immutable. Sia createPage che updatePage lo chiamano prima di ogni fs.writeFile. Nessun endpoint scrive sotto raw_sources/: è immutabile per design.
2. Specchio a livello di prompt. HARD_RULE_RAW_SOURCES (archiveConfigService.ts:52-53) è un blocco sempre attivo aggiunto a ogni prompt bindato all'archivio: il testo specchia la guardia (raw_sources/ is immutable), così il modello non tenta mai la via fuori da wiki/ — e se l'attentasse, il codice garantisce che non atterri nulla.

schemaPrompt (advisory)

Campo di testo libero salvato nel config JSON dell'archivio:

• Schema: schemaPrompt: z.string().max(10000).optional() su archiveConfigSchema — chiave additiva, zero migrazioni. 10000 caratteri ≈ ~2500 token.
• Validazione: Zod a ogni write (PUT /api/archives/:id/config); un payload oltre la cap → 400 { error: "Invalid config", details.schemaPrompt }.
• Read contract: GET /api/archives/:id/config su archivio senza riga → 200 con il config di default ({ rawSourcesImmutable: true }): è il path di hydratation del primo salvataggio; gli archivi con riga restituiscono il blob salvato tale e quale.
• Cap all'iniezione: i blob legacy sopra 10000 caratteri vengono troncati all'iniezione con l'annotazione (truncated at 10000 characters) — le righe legacy non vengono ri-validat* alla lettura.
• Advisory per design: il blocco entra come DATO con etichetta advisory esplicita, mai come grant di privilegio da system prompt. Niente sanitizzazione oltre la cap; istruzioni contraddittorie = rischio di qualità accettato, mitigato dai template della UI.

Precedenza

regole hard (codice) > schemaPrompt (advisory) > campi strutturati

1. Lo schemaPrompt non può mai scavalcare le regole hard (il prompt lo dichiara; il codice lo garantisce).
2. In conflitto con i campi strutturati, lo schemaPrompt vince (On conflict with the structured fields (persona, purpose, scope), these guidelines take precedence over them.).
3. Un archivio senza schemaPrompt si comporta da baseline + regola hard — zero enhancement, zero degradazione (nessuna sezione placeholder nei prompt).

Dove entra il blocco nel prompt

All'interno del system prompt: dopo il blocco MANDATORY SEARCH RULE, prima del ternario systemPrompt.

wiki_query e wiki_write

I builtin wiki_query e wiki_write sono skill whose execute() non chiama MAI la LLM: la scrittura genera preview deterministici (wikiWriteService.ts contiene zero invocazioni LLM) — l'iniezione per-skill non raggiungerebbe alcun modello: l'unica superficie LLM è il system prompt dell'orchestrator.

rawSourcesImmutable

rawSourcesImmutable: boolean (default true) su archiveConfigSchema è un flag di documentazione, mai un toggle di enforcement: la regola di immutabilità si applica a prescindere dal flag (la guardia validateWritablePath + il blocco sempre-attivo la garantiscono).

Questa guida copre la superficie operativa del motore wiki; l'approfondimento tecnico vive nel post gemello:

• L'approfondimento tecnico

Provenance

---

Riferimento operativo — Simmetric Chat v0.28.1 (docs aggiornate 2026-10-02, census SHA `aca5b8ff`).