Documentazione di CapDAG

Panoramica

Che cosa copre la specifica di CapDAG, come si collegano i suoi documenti, la terminologia che condividono e che cosa deve fare un’implementazione per essere conforme.

In questa sezione

Ambito

Questa specifica definisce i fondamenti semantici, il protocollo di runtime, il modello di esecuzione e i pattern di sviluppo di CapDAG. È il contratto comune e autorevole per ogni implementazione di CapDAG.

Mappa dei documenti

Fondamenti (2–5)

# Documento Scopo Dipendenze
2 Fondamenti formali Fondamento matematico, relazione di dispatch Nessuna
3 Dominio dei tagged URN Dominio di base U, normalizzazione, tabella di verità dei wildcard 2
4 Predicati Predicati derivati (accepts, conforms_to, is_comparable, is_equivalent) 3
5 Specificità Funzione di punteggio della specificità 3

Dispatch e instradamento (6–8)

# Documento Scopo Dipendenze
6 Struttura del cap URN Il cap URN come prodotto C = U × U × U × E 3, 5
7 Dispatch Il predicato di dispatch 3, 4, 6
8 Ranking Selezione fra i candidati validi 5, 7

Notazione delle macchine e tipi di dati (9–11)

# Documento Scopo Dipendenze
9 Notazione delle macchine Codifica testuale di grafi di flusso dei dati con più cap 4, 6
10 Regole di validazione Vincoli di validazione strutturale 3, 6
11 Media URN Struttura dei media URN e gli assi ext/fmt/enc 3

Protocollo (12)

# Documento Scopo Dipendenze
12.1 Architettura Topologia del sistema, ruoli dei componenti 7, 8
12.2 Protocollo dei frame Formato sul filo, tipi di frame, limiti di dimensione 12.3, 12.4
12.3 Handshake Apertura della connessione, scambio HELLO, verifica dell’identità —
12.4 Streaming Stream multiplexati, suddivisione in chunk, numerazione di sequenza —
12.5 Controllo di flusso Finestre di credito, chiusura, superamenti e statistiche del protocollo 12.2, 12.4

Runtime della cartuccia (13)

# Documento Scopo Dipendenze
13.1 Runtime della cartuccia Punto di ingresso, registrazione degli handler, modalità CLI/cartuccia 7, 12.3
13.2 Input e output InputStream, OutputStream, ricerca degli stream 13.4, 15.4
13.3 Invocazione peer Chiamate di capacità fra cartucce —
13.4 Avanzamento e logging Frame LOG, mappatura dell’avanzamento, keepalive 15.3

Host e relay (14)

# Documento Scopo Dipendenze
14.1 Runtime dell’host Ciclo di vita delle cartucce, instradamento dei frame, monitoraggio dello stato 12.3
14.2 Relay switch Multiplexer di instradamento consapevole delle cap 7, 8, 15.4
14.3 Topologia dei relay Coppie RelaySlave/RelayMaster, catene di relay su socket Unix —

Esecuzione (15)

# Documento Scopo Dipendenze
15.1 Orchestratore Parsing della notazione delle macchine, costruzione del DAG 11
15.2 Esecuzione execute_plan, pianificazione, mappe, politica dei passi 15.3
15.3 Mappatura dell’avanzamento Suddivisione deterministica dell’avanzamento —
15.4 Planner Ricerca dei percorsi, LiveCapFab, MachinePlan 15.1

Sviluppo di cartucce (16)

# Documento Scopo Dipendenze
16.1 Anatomia di una cartuccia Struttura della cartuccia, manifest, definizioni delle cap 12.3
16.2 Pattern degli handler Trait Op, estrazione degli argomenti, emissione dell’output 15.4
16.3 Cartucce di modelli Cartucce di ML, architettura in tre fasi 13.4
16.4 Cartucce di contenuti Elaborazione di documenti, pattern di cap standard 7, 16.2
16.5 Rust e Swift a confronto Differenze di implementazione, copertura dei moduli —

Errori di runtime (17)

# Documento Scopo Dipendenze
17.2 Gestione degli errori Gerarchia dei tipi di errore, pattern di propagazione 13.4

La CLI capdag (18)

# Documento Scopo Dipendenze
18.0 Installare la CLI di CapDAG Tutti i modi per installarla: Homebrew, apt, dnf, winget o il download diretto —
18.1 Riferimento della CLI di CapDAG Ogni sottocomando di capdag, opzioni, collegamento al fabric, disciplina dell’output 7, 15.2
18.2 Costruire ed eseguire una cartuccia Creare lo scheletro, installare in sviluppo, eseguire e iterare su una cartuccia; il ripiego di sviluppo locale 16.1, 18.1

Ordine di lettura

  1. 02 Fondamenti formali: fondamento matematico (facoltativo, come riferimento formale)
  2. 03 Dominio dei tagged URN: il dominio di base
  3. 04 Predicati: i quattro predicati derivati
  4. 05 Specificità: il punteggio
  5. 06 Struttura del cap URN: come i cap URN compongono quattro coordinate strutturali
  6. 07 Dispatch: la regola centrale di instradamento
  7. 08 Ranking: selezione fra i candidati validi
  8. 09 Notazione delle macchine: collegare più cap in un grafo di flusso dei dati
  9. 10 Regole di validazione: vincoli strutturali
  10. 11 Media URN: dettagli sui tipi di media
  11. 12 Protocollo: formato sul filo, apertura della connessione, streaming e controllo di flusso
  12. 13 Runtime della cartuccia: scrivere gli handler
  13. 14 Host e relay: l’infrastruttura che ospita le cartucce
  14. 15 Esecuzione: orchestrazione e pianificazione dei DAG
  15. 16 Sviluppo di cartucce: costruire cartucce
  16. 17 Errori di runtime: vocabolario degli errori e propagazione
  17. 18 La CLI capdag: lo strumento a riga di comando e il ciclo di sviluppo delle cartucce

Terminologia

Termine Definizione
Tagged URN Un URN con struttura prefix:key1=value1;key2=value2;...
Media URN Un tagged URN con prefisso media: che descrive un tipo di dati
Cap URN Un tagged URN con prefisso cap: che descrive una capacità
Pattern Un URN usato come modello o vincolo
Istanza Un URN che rappresenta un valore concreto o una richiesta
Candidato Una capacità registrata in grado di gestire richieste
Richiesta Un URN di capacità che descrive ciò che serve
Dispatch L’atto di instradare una richiesta verso un candidato valido
Specificità Un punteggio numerico che misura quanto un URN è vincolato
Wildcard Un valore speciale (*, ?, !) con una semantica di corrispondenza
Macchina Una collezione ordinata di MachineStrand collegati in grafi di flusso dei dati
MachineStrand Una componente connessa massimale di archi di cap risolti, con le loro ancore
Notazione delle macchine La codifica testuale di una macchina (vedi Notazione delle macchine)
Cartuccia Un binario autonomo che fornisce una o più capacità
Genere di cap (Cap Kind) Una classificazione logica di una cap in uno fra Identity, Source, Sink, Effect o Transform, derivata da (in, out, y, effect). Vedi Struttura del cap URN: generi di cap.
Tipo top media:, il wildcard universale per i media URN. Ogni media URN è conforme a esso. Un lato tipizzato media: si legge come “qualsiasi A”.
Tipo unità media:void, il valore nullario. Un lato tipizzato media:void si legge come “()”: lì non scorre alcun dato significativo. È distinto dal tipo top. Atomico: raffinamenti come media:void;text sono errori di parsing.

Convenzioni di notazione

Notazione della teoria degli ordini

  • a <= b: “a è almeno tanto specifico quanto b” (a raffina b)
  • a >= b: “a è almeno tanto generale quanto b” (equivalente a b <= a)

Componenti del cap URN

Un cap URN c si scrive come una quadrupla:

c = (i, o, y, e)

dove:

  • i = media URN di input (il valore del tag in)
  • o = media URN di output (il valore del tag out)
  • y = tag della cap diversi dalla direzione (op, ext, model e così via; sono tutti arbitrari e nessuno ha un privilegio funzionale)
  • e = effetto sull’identità di media/tipo a runtime

Fondamento

Questa specifica si basa sui fondamenti matematici di Fondamenti formali, che definisce la relazione di dispatch centrale:

Dispatch(p, r) <=> (i_r open \/ i_r <= i_p) /\ o_p <= o_r /\ (e_r = ? \/ e_p = e_r) /\ y_p satisfies y_r

Una richiesta è una domanda sulle cap: un lato che lascia aperto è sconosciuto, non il tipo “qualsiasi cosa”, e i tag del candidato si leggono come completi.

I documenti numerati completano i dettagli operativi: tabelle di verità dei wildcard, regole di normalizzazione, punteggio della specificità, vincoli di validazione, notazione delle macchine, protocollo, runtime, esecuzione e pattern di sviluppo.

Conformità

Un’implementazione è conforme a questa specifica se:

  1. Tutti i tagged URN si normalizzano in modo identico (secondo Dominio dei tagged URN)
  2. Tutti i predicati si calcolano in modo identico (secondo Predicati)
  3. I punteggi di specificità coincidono (secondo Specificità)
  4. La validità del dispatch coincide (secondo Dispatch)
  5. Tutte le regole di validazione vengono applicate (secondo Regole di validazione)

La policy di ranking (Ranking) può variare da un sottosistema all’altro, ma la validità del dispatch non deve variare.