Topic e Knowledge Asset

I Topic definiscono l'obiettivo editoriale; i Knowledge Asset forniscono conoscenza riusabile. Solo record accepted in D1 possono entrare nel contesto di generazione.

Obiettivo e transizione autorevole

Un Topic o Knowledge Asset passa tra proposed, accepted e deprecated tramite una scrittura Admin esplicita. L'accettazione lo rende eleggibile, ma non avvia un job e non prenota una pubblicazione.

Input e fonti accettate

Topic: ID TOPIC-000, titolo, categoria, learning objective, rationale, tag e metadati di pianificazione.
Knowledge Asset: ID KA-000, titolo, tipo, summary, esattamente una forma di contenuto (body legacy oppure sections strutturate), tag e Topic correlati.
referenceCandidates di un Topic sono candidati di curazione: non sono automaticamente fonti accettate.
Brain e file storici non sono un catalogo runtime alternativo.

Attore e autorizzazione

Cloudflare Access autentica l'identità Admin. L'API richiede editorial:write per le mutazioni e admin:read per le letture. La UI rende visibile il catalogo, ma il Worker valida payload, stato e revisione.

Validazione e quality gate

Ogni record deve rispettare lo schema canonico. Le scritture esistenti usano expectedRevision; una revisione stantia restituisce EDITORIAL_REVISION_CONFLICT senza sovrascrivere il valore più recente. Bulk e dry-run validano lo stesso contratto.

La generazione aggiunge due gate:

il Topic selezionato deve esistere ed essere accepted;
deve esistere almeno un Knowledge Asset accepted collegato al Topic.

Responsabilità dell'AI

L'AI non propone né accetta lo stato autorevole del catalogo. Riceve soltanto la proiezione costruita dall'applicazione dopo i gate e non può promuovere un record proposed o deprecated.

Persistenza e audit in D1

D1 conserva il contenuto canonico e una revisione intera positiva. Un update significativo incrementa la revisione una sola volta; un no-op la mantiene. Slug, cursori e readback sono derivati dal repository D1, non dal browser.

Evidenza di successo

risposta Admin con contenuto canonico e revisione corrente;
stato accepted leggibile dal catalogo D1;
per la generazione, contesto con Topic esatto e almeno un Knowledge Asset accettato.

Fallimento e recupero

Schema invalido, ID non canonico, revisione stantia o relazione mancante bloccano la scrittura o il job. Rileggere la risorsa, risolvere il conflitto e salvare esplicitamente. Non correggere il catalogo dentro il retry del job.

Effetti collaterali esclusi

Accettare o modificare un Topic, Knowledge Asset o termine di glossario:

non crea un Issue;
non chiama il provider AI;
non approva o pubblica;
non prepara Campaign Draft;
non chiama Mailjet;
non distribuisce Worker.

Contratto a sezioni

ADR-042 definisce il documento canonico: o body, o sections ordinate di blocchi paragraph, list, checklist, example e image. Le due forme insieme sono invalide. L'immagine è un intento editoriale opzionale, con alt, senza URL di provider; al massimo otto intenti immagine per Knowledge Asset, e zero resta valido. Non serve una migrazione SQL: il documento resta in payload_json.

Admin, OpenAPI pubblico e MCP ammettono entrambe le forme. Un patch può sostituire body con sections o viceversa, mai entrambe insieme. La generazione Issue riceve sempre una proiezione plain-text. Il dettaglio pubblico espone body (memorizzato o derivato) e, se presenti, sections. Il rendering Astro a blocchi resta una story successiva. Nessuna conversione di massa dei record Production è autorizzata da questa story.