Vai al contenuto

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, body, 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:

  1. il Topic selezionato deve esistere ed essere accepted;
  2. 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.

Riferimenti canonici