Regole di validazione

Panoramica

Questo documento specifica tutte le regole di validazione di CapDAG. Tutte le implementazioni DEVONO applicare queste regole in modo identico.

Categorie di regole

Ordine di validazione

1. Validazione strutturale (JSON Schema)
2. Validazione dei cap URN (CU1–CU3)
3. Regole delle definizioni di cap (RULE1–RULE14)
4. Regole delle media def (MS1–MS3)
5. Validazione incrociata (XV1–XV7)

Regole dei cap URN

CU1: Specificatori di direzione obbligatori

Regola: i cap URN in forma canonica DEVONO includere i tag in e out.

Sintassi di superficie e forma canonica: gli utenti possono omettere in/out nella sintassi di superficie. Durante la normalizzazione, i tag mancanti assumono il valore predefinito media:. La validazione si applica alla forma canonica.

Forma canonica:

cap:in="<media-urn>";out="<media-urn>";<other-tags>

Esempi:

# Sintassi di superficie → Forma canonica
cap:in=media:;out=media:;transform  →  cap:in=media:;transform;out=media:   ✓ (normalizzato)

# Già canonici
cap:in="media:document;ext=pdf";extract;out="media:record"             ✓
cap:in=media:;generate;out="media:enc=utf-8"               ✓

Errore: Cap URN requires 'in' tag / Cap URN requires 'out' tag

Questo errore si verifica solo per input malformati che aggirano la normalizzazione (es. costruzione programmatica senza validazione).

CU2: Riferimenti a media URN validi

Regola: i valori degli specificatori di direzione (in e out) DEVONO essere:

• un media URN valido (che inizia con media:)
• oppure il wildcard * (che si normalizza in media:)

Esempi:

cap:in="media:bytes;document;ext=pdf";extract;out="media:record"   ✓
cap:in=*;convert;out=*                                ✓ (si normalizza in media:)
cap:in="invalid";test;out="media:enc=utf-8"            ✗

Errore: Invalid 'in' media URN: <value>. Must start with 'media:' or be '*'

CU3: Ammissibilità dell’effetto

Regola: l’effetto dichiarato di un cap URN deve essere coerente con i suoi in=/out= dichiarati (vedi Struttura dei cap URN: ammissibilità dell’effetto):

• La forma top nuda con tutti i valori predefiniti (cap: / cap:in=media:;out=media: con effetto predefinito e nessun tag) è inammissibile.
• effect=none: l’in= dichiarato deve essere conform_to rispetto all’out= dichiarato.
• effect=patch: il delta di coordinate out − in deve essere derivabile, e riapplicarlo a in= deve produrre un tipo conforme a out=.

Applicazione: alla costruzione di CapUrn (validate_admissible) in ogni implementazione. Ogni parsing di un cap URN la applica, incluso il publisher della fabric, quindi una dichiarazione di effetto incoerente non può essere pubblicata.

Esempi:

cap:effect=none                                            ✓ (identità)
cap:decimate-sequence;effect=none                          ✓ (in=media: ⊑ out=media:)
cap:in="media:document;ext=pdf";out="media:enc=utf-8";effect=none   ✗ (in ⋢ out)
cap:                                                       ✗ (top nudo)

Regole delle definizioni di cap (RULE1–RULE22)

Queste regole validano gli array args e outputs nelle definizioni di capacità. Ogni implementazione e il publisher della fabric sollevano ciascuna regola con il numero che ha qui: un numero nomina una sola regola.

Dove vengono applicate. Una definizione è vincolata a queste regole ovunque passi da un programma a un altro, dalla parte che la riceve così come da quella che la invia:

• il publisher della fabric, prima che una definizione venga servita;
• una libreria che legge una definizione da un registro, prima che venga messa in cache o restituita. Una definizione in cache che viola una regola è stata scritta secondo altre regole: il suo file di cache viene eliminato e la definizione viene recuperata di nuovo;
• una cartuccia, sul proprio manifest, prima di annunciarsi;
• un host che legge il manifest che una cartuccia annuncia. Un manifest che viene analizzato e contiene una definizione che viola una regola viene rifiutato come incompatibile, nominando la cap e la regola, e la cartuccia non viene collegata.

Due regole vengono verificate altrove per ciò di cui hanno bisogno. RULE13 viene verificata quando una definizione viene analizzata: una definizione senza alias non si deserializza. RULE16 richiede le definizioni di media rispetto a cui viene validato il valore predefinito di un argomento, che un host che legge un manifest potrebbe non avere, quindi è una regola del publisher.

RULE1: Nessun media URN duplicato

Regola: due argomenti non possono avere lo stesso media_urn.

Motivazione: ogni argomento è identificato in modo univoco dal suo media URN.

Errore: RULE1: Duplicate media_urn '<urn>'

RULE2: Le sorgenti non devono essere vuote

Regola: ogni argomento DEVE avere un array sources non vuoto.

Motivazione: un argomento senza sorgenti non può ricevere input.

Errore: RULE2: Argument '<media_urn>' has empty sources

RULE3: Al più un argomento stdin

Regola: al più un argomento può dichiarare una sorgente stdin.

Motivazione: stdin è l’unico input in pipe di una riga di comando, e l’argomento che lo dichiara è l’input principale della cap (RULE15). Non dice nulla su quanti argomenti una cap riceva dati: ogni argomento viene consegnato come uno stream proprio, e ciascuno di essi può essere alimentato dall’output di un’altra cap (Notazione delle macchine).

Errore: RULE3: Arguments '<urn1>' and '<urn2>' both declare a stdin source; a cap has one main input

RULE4: Nessun tipo di sorgente duplicato per argomento

Regola: nessun argomento può specificare lo stesso tipo di sorgente (stdin, position, cli_flag) più di una volta.

Motivazione: ogni tipo di sorgente rappresenta un singolo canale di input per argomento.

Errore: RULE4: Argument '<media_urn>' has duplicate source type '<type>'

RULE5: Nessuna posizione duplicata

Regola: due argomenti non possono avere lo stesso indice posizionale.

Motivazione: gli argomenti posizionali devono essere privi di ambiguità.

Errore: RULE5: Duplicate position <n> in argument '<media_urn>'

RULE6: Posizioni sequenziali

Regola: le posizioni devono essere sequenziali a partire da 0, senza buchi.

Motivazione: garantisce un ordinamento prevedibile degli argomenti posizionali.

Errore: RULE6: Position gap - expected <n> but found <m>

RULE7: Nessuna combinazione di posizione e flag CLI

Regola: nessun argomento può avere sia una sorgente position sia una sorgente cli_flag.

Motivazione: un argomento è posizionale oppure nominato, non entrambe le cose.

Errore: RULE7: Argument '<media_urn>' has both position and cli_flag sources

RULE8: Nessuna chiave di sorgente sconosciuta

Regola: gli oggetti sorgente possono contenere solo chiavi riconosciute: stdin, position o cli_flag.

Motivazione: previene errori di battitura e configurazioni non valide.

Applicazione: validata da JSON Schema con deny_unknown_fields.

Errore: RULE8: Argument '<media_urn>' has source with unknown keys

RULE9: Nessun flag CLI duplicato

Regola: due argomenti non possono avere lo stesso valore di cli_flag.

Motivazione: i flag CLI devono identificare gli argomenti in modo univoco.

Errore: RULE9: Duplicate cli_flag '<flag>' in argument '<media_urn>'

RULE10: Flag CLI riservati

Regola: questi flag CLI sono riservati e non possono essere usati:

• manifest
• --help
• --version
• -v
• -h

Motivazione: riservati per l’uso di sistema.

Errore: RULE10: Argument '<media_urn>' uses reserved cli_flag '<flag>'

RULE11: Uso letterale dei flag CLI

Regola: i flag CLI vengono usati esattamente come specificati (nessun prefisso -- aggiunto automaticamente).

Applicazione: per costruzione: le implementazioni usano la stringa del flag alla lettera.

RULE12: Il media URN come chiave

Regola: un argomento è identificato dal suo media_urn, e un output dal suo media_urn. Un name (RULE17, RULE19) è un’etichetta con cui una macchina può selezionarne uno; non identifica nulla.

Applicazione: i binding, la consegna degli stream, l’equivalenza e ogni ricerca sono indicizzati dal media URN. Nessuna implementazione ricava qualcosa su un URN da un nome, né su un nome da un URN.

RULE13: Alias obbligatori

Regola: ogni definizione di capacità DEVE contenere una lista aliases non vuota. Ogni alias è in minuscolo, corrisponde a [a-z0-9._-]+ e non contiene due punti.

Motivazione: aliases è l’unica fonte dei nomi di una cap rivolti alle persone (il livello DNS, usato sia dalla CLI capdag dell’intera fabric sia dalla CLI diretta della cartuccia). Una cap senza alias non ha nome ed è inammissibile.

Errore: RULE13: Capability '<urn>' has empty aliases

RULE14: Solo l’input principale può essere in streaming

Regola: un argomento può dichiarare streaming: true solo se è l’input principale della cap, cioè l’argomento la cui sorgente stdin è equivalente nei tag all’in= dell’URN (CapArg::is_main_input). Una dichiarazione streaming su qualsiasi altro argomento rende non valido lo schema della cap.

Motivazione: streaming dichiara che un argomento viene consumato senza una promessa di lunghezza: un feed (15.2 §Contratti di streaming). Gli argomenti secondari (opzioni, specifiche del modello, prompt accanto all’input principale) sono valori che il runtime demultiplexa per intero; un feed lì non ha significato e permetterebbe a uno stream illimitato di raggiungere un collettore che deve rifiutarlo (12.4 L16). Limitare lo streaming al solo input principale mantiene monodimensionale la regola dei passaggi dell’executor: un passaggio è un confine se e solo se l’output del produttore è in streaming e l’input principale del consumatore non lo è. streaming è ortogonale a is_sequence (cardinalità) e non è un asse dell’URN.

Errore: RULE14: Argument '<media_urn>' declares streaming=true but is not the main input (no stdin source equivalent to in='<in>'); only the main input may be consumed without a length promise

RULE15: L’input principale corrisponde a in=

Regola: se l’in= del cap URN è media:void, nessun argomento può dichiarare una sorgente stdin. Altrimenti esattamente un argomento ne dichiara una, e il suo URN è equivalente nei tag a in=. Quell’argomento è l’input principale della cap.

Motivazione: il cap URN dichiara che cosa la cap prende; la definizione deve poterlo ricevere, e non deve dichiarare un input che l’URN nega.

Errore: RULE15: in= is 'media:void' but <n> arg(s) declare a stdin source, oppure RULE15: in= is '<in>' but no arg declares a stdin source equivalent to it

RULE16: Un valore predefinito soddisfa la validazione del suo argomento

Regola: il default_value di un argomento deve soddisfare la validazione dichiarata dalla sua definizione di media.

Errore: RULE16: default_value <value> for '<media_urn>' <reason>

RULE17: Nomi degli argomenti

Regola: ogni argomento ha un name: non vuoto, della forma (ALPHA | "_") (ALNUM | "_" | "-")*, diverso da true, false e null, e unico fra gli argomenti della cap.

Motivazione: una macchina seleziona un argomento con questo nome dove i tipi non possono decidere (Notazione delle macchine). È un’etichetta locale alla definizione.

Errore: RULE17: Argument '<media_urn>' has no name, RULE17: Argument name '<name>' is not a valid name, oppure RULE17: Arguments '<urn1>' and '<urn2>' share the name '<name>'

RULE18: accepts solo senza stdin

Regola: un argomento può dichiarare accepts, il media URN a cui il suo stream deve essere conforme, solo se non dichiara alcuna sorgente stdin.

Motivazione: un argomento dice che cosa accetta in un solo punto. L’input principale lo dice con la sua sorgente stdin; ogni altro argomento accetta il proprio media_urn a meno che accepts dica altrimenti. accepts è ciò che permette a due argomenti di prendere valori di un solo tipo mantenendo URN distinti (RULE1).

Errore: RULE18: Argument '<media_urn>' declares both a stdin source and accepts

RULE19: Nomi degli output

Regola: ogni output ha un name, con la stessa forma e la stessa riserva di RULE17, unico fra gli output della cap.

Errore: RULE19: Output '<media_urn>' has no name, RULE19: Output name '<name>' is not a valid name, oppure RULE19: Outputs '<urn1>' and '<urn2>' share the name '<name>'

RULE20: Nessun URN di output duplicato

Regola: due output non possono avere lo stesso media_urn.

Errore: RULE20: Duplicate output media_urn '<urn>'

RULE21: Esattamente un output principale

Regola: se l’out= del cap URN è media:void, la cap non dichiara alcun output. Altrimenti il media_urn di esattamente un output è equivalente nei tag a out=. Quell’output è l’output principale della cap; il suo tipo a runtime segue l’effetto del cap URN.

Errore: RULE21: out= is 'media:void' but <n> output(s) are declared, oppure RULE21: out= is '<out>' but <n> outputs are equivalent to it; exactly one must be

RULE22: Che cosa porta un output

Regola: un output diverso da quello principale porta il proprio media_urn oppure, quando dichiara carries = "input", il tipo a runtime dell’input principale invariato. carries = "input" richiede una cap il cui in= non sia media:void. L’output principale non dichiara carries: lo decide l’effetto del cap URN.

Errore: RULE22: Output '<media_urn>' carries the input but the cap takes none, oppure RULE22: The main output '<media_urn>' declares carries

Regole delle media def (MS1–MS3)

MS1: Titolo obbligatorio

Regola: ogni media def DEVE avere un campo title.

Motivazione: i titoli forniscono un’identificazione leggibile dalle persone.

Errore: Media def '<urn>' has no title

MS2: Formato di URN valido

Regola: i media URN DEVONO iniziare con il prefisso media:.

Motivazione: distingue le media def dagli altri tipi di URN.

Errore: Invalid media URN: expected 'media:' prefix

MS3: Tipo di media obbligatorio

Regola: ogni media def DEVE avere un campo media_type (tipo MIME).

Motivazione: specifica il tipo di contenuto per una gestione corretta.

Errore: Media def '<urn>' has no media_type

Regole di validazione incrociata (XV1–XV5)

XV1: Nessun cap URN duplicato

Regola: due definizioni di capacità non possono avere lo stesso cap URN canonico.

Motivazione: i cap URN identificano le capacità in modo univoco.

Errore: Duplicate cap URN: <urn>

XV2: Nessun media URN duplicato (globale)

Regola: due definizioni di media autonome non possono avere lo stesso URN.

Motivazione: i media URN identificano le media def in modo univoco nel registro globale.

Errore: Duplicate media URN: <urn>

XV3: Risoluzione dei media URN obbligatoria

Regola: tutti i media URN a cui fanno riferimento le capacità DEVONO risolversi in una media def definita.

Ordine di risoluzione:

1. la tabella locale media_defs della capacità (definizioni inline)
2. i file di media def autonomi (registro globale)

Nessun ripiego: se un media URN non può essere risolto, la validazione FALLISCE. Nessuna generazione automatica.

Posizioni verificate:

• il valore in dalla stringa dell’URN (a meno che sia un wildcard)
• il valore out dalla stringa dell’URN (a meno che sia un wildcard)
• ogni args[].media_urn
• output.media_urn
• ogni args[].sources[].stdin (media URN nella sorgente stdin)

Errore: Unresolved media URN '<urn>' referenced in <location>

XV4: Titolo obbligatorio per le media def inline

Regola: le media def definite inline nelle tabelle media_defs delle capacità DEVONO avere un campo title.

Motivazione: come MS1: tutte le media def richiedono un titolo.

Errore: Inline media def '<urn>' in <file> has no title

XV5: Nessuna ridefinizione delle media def del registro

Regola: le media def inline NON DEVONO ridefinire media def che esistono nel registro globale.

Motivazione: il registro globale è la fonte canonica. Una ridefinizione crea conflitti.

Applicazione:

• Con rete: applicazione rigorosa. Qualsiasi conflitto con il registro = FALLIMENTO.
• Senza rete: verifica solo delle specifiche in cache. Registra un avviso se la verifica non è possibile.

Errore: XV5: Inline media def '<urn>' redefines existing registry spec

Avviso (offline): XV5: Could not verify inline spec '<urn>' against online registry (offline mode)

XV6: Univocità globale degli alias

Regola: i nomi degli alias sono univoci nell’intero snapshot. Due cap non possono condividere un alias, e nessun alias di cap può coincidere con un alias di media. L’unione degli alias di cap e degli alias di media non contiene duplicati.

Motivazione: gli alias sono il livello DNS: un nome si risolve in esattamente una cap o un media. Una collisione rende la risoluzione ambigua.

Applicazione: il publisher fallisce senza appello a qualsiasi collisione.

Errore: XV6: Duplicate alias '<alias>' (defined by <a> and <b>)

XV7: Copertura delle cap astratte

Regola: ogni cap abstract DEVE avere almeno una specializzazione concreta nello stesso snapshot: una cap concreta (non astratta) che sia is_dispatchable a partire dall’URN della cap astratta specializzato su un input concreto. Una cap astratta senza alcuna specializzazione concreta è morta.

Motivazione: una cap astratta è un ombrello di dispatch (vedi Dispatch §”Cap astratte”). Senza una specializzazione concreta non può mai effettuare il dispatch verso nulla.

Applicazione: il publisher fallisce senza appello su una cap astratta morta.

Errore: XV7: Abstract cap '<urn>' has no concrete specialization

XV8: Una cap astratta nomina il medium che le sue specializzazioni condividono

Regola: dove ogni specializzazione concreta di una cap astratta prende input di un solo medium (media:image, media:audio, media:video, media:document), l’input della cap astratta DEVE essere conforme a quel medium; lo stesso vale per il suo output. Un lato sul quale le specializzazioni non condividono alcun medium non è vincolato da questa regola.

Motivazione: un tipo è un’affermazione. cap:convert-image dichiarata media: → media: dice di convertire qualsiasi cosa, mentre ogni convertitore sotto di essa prende e produce un’immagine. L’ombrello dice che cosa le sue specializzazioni hanno in comune, niente di più.

Applicazione: il publisher fallisce senza appello su una cap astratta dichiarata più ampia delle sue specializzazioni.

Errore: XV8: Abstract cap '<urn>' declares its <input|output> as '<declared>', but all of its specializations take part as '<medium>'

XV9: I link della documentazione si risolvono

Regola: ogni link dalla documentation o dalla descrizione di una cap o di una media def verso il browser del registro (https://capdag.com/browse/<urn>) DEVE nominare un cap URN o un media URN che esiste nello stesso snapshot. L’URN collegato viene confrontato in forma canonica, quindi l’ordine dei tag e le virgolette non contano; un URN che non viene analizzato è un errore.

Motivazione: un tipo riscritto in altro modo, o una cap il cui input cambia, altrimenti lascia dietro di sé link che si aprono su “non trovato”.

Applicazione: il publisher fallisce senza appello su un link che non si risolve.

Errore: XV9: <cap|media> '<urn>' links to '<target>', which is not in the catalogue

Requisiti di implementazione

Fallire senza appello

Tutti gli errori di validazione DEVONO causare un fallimento immediato con un messaggio di errore chiaro.

• Nessun ripiego
• Nessun recupero silenzioso
• Nessun valore predefinito per i campi obbligatori

Comportamento coerente

Tutte le implementazioni (Rust, JavaScript, funzioni server) DEVONO applicare regole identiche con messaggi di errore identici.

Codici di errore

Tabella riassuntiva