diff --git a/README.ar.md b/README.ar.md new file mode 100644 index 0000000..101bea4 --- /dev/null +++ b/README.ar.md @@ -0,0 +1,80 @@ +> ترجمة مجتمعية (مسودة) — سياسة NTARI رقم P2-002، البث العالمي متعدد اللغات. المصدر: README.md (الأصل الإنجليزي، لقطة بتاريخ 2026-07-29). مسودة مجتمعية بمساعدة آلية، في انتظار مراجعة القائم بالصيانة الإقليمي وفقًا للبند §3.1 من P2-002. تبقى المواصفات التقنية الأساسية بالإنجليزية وفقًا للبند §2.2. +> +> تصحيحات الترجمة مساهمات نرحّب بها ونقدّرها كسائر المساهمات، فإذا لاحظت خطأً +> في هذه الترجمة فيمكنك إصلاحه بنفسك عبر إنشاء fork للمستودع وفتح pull +> request: https://github.com/NTARI-RAND/sohocloud-protocol + +# sohocloud-protocol + +وحدة Go المشتركة التي تُعرِّف **بروتوكول تنسيق الركيزة** لشبكة +SoHoLINK / Cloudy: التعرّف على العُقد، وسرد القدرات، وتوظيف +المهام؛ وهو البروتوكول الذي يتحدثه كل مُنسِّق وكل واجهة أمامية. + +## النطاق + +تحكم هذه الوحدة **التنسيق فقط**. وهي **ليست** اقتصاد أعضاء JFA — +فلا ضمان مالي (escrow)، ولا رصيد يُصدره الأعضاء، ولا عهد سمعة، +ولا سجل مختوم بالحوار، ولا فصل في النزاعات. تعيش هذه الأمور في كل واجهة +أمامية، وغيابها هنا مقصود. + +إنها **ورقة في شجرة الاعتماديات**: لا تستورد أي وحدة أخرى من وحدات NTARI، +ولا تستورد شيئًا غير المكتبة القياسية لـ Go. فكلٌّ من SoHoLINK (المُنسِّق +المرجعي) وCloudy (واجهة أمامية) يستورد *هذه الوحدة*؛ ولا يُستورد شيء عبرها +في الاتجاه المعاكس. وهذه الخاصية — التي يفرضها رسم بياني للاستيراد لا النصّ +النثري — هي ما يمنع أي مُنسِّق واحد من أن يصبح محورًا يجب أن تمرّ الشبكة +كلها من خلاله (المشكلة المفتوحة رقم 7). + +## الأدوار + +تتحدث الواجهات الأمامية بالسطح الخاص بجانب العُقدة — `SubmitListing` +و`Heartbeat` و`PollJobs` و`Decline` و`ReportJob` و`Fees` — بالنيابة عن +الأجهزة التي يساهم بها أعضاؤها؛ أما المُنسِّقون فينفّذون واجهة `Coordinator` +ويُنسِّقون الواجهات الأمامية (ويُقيمون بينها اتحادًا). ولا يظهر الأشخاص على +السلك أبدًا: فهوية العضو شأن يخص الواجهة الأمامية، والهوية الوحيدة التي +تعرفها هذه الوحدة هي هوية عبء العمل — أي NodeID مع ارتباطه المعياري بـ +SPIFFE في `identity/`. + +## البنية + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## الحالة (بصراحة) + +- **ما تم بناؤه:** أنواع الرسائل، وبايتات التوقيع المعيارية، والتوقيع + والتحقق بـ ed25519، وواجهة `Coordinator`، ووسيلة نقل مرجعية عبر + HTTP+JSON تحت `transport/httpjson`. +- **متجهات المطابقة:** الملف `testdata/vectors.json` هو الملف المرجعي + المعياري (fixture) لمطابقة التنفيذات عبر اللغات — 25 حالة أوّلية، + بالإضافة إلى جميع أنواع الرسائل الموقَّعة الستة مع بايتاتها المعيارية + وتوقيعات ed25519 الخاصة بها. ويكون أي تنفيذ خارجي مطابقًا إذا — وفقط + إذا — أعاد إنتاج هذا الملف بايتًا ببايت انطلاقًا من المدخلات نفسها + (`SPEC.md` §10). ويعيد اختبار `vectors/` توليد الملف المرجعي من + المُرمِّزات الحالية، ويُفشل عملية البناء عند أي انحراف. +- **وسيلة نقل مرجعية، لا البروتوكول السلكي:** الحزمة `transport/httpjson` + اختيارية ولا تستوردها أي حزمة أساسية. ويجوز لأي تنفيذ مطابق أن يتحدث + بهذه الرسائل عبر أي وسيلة نقل، وذلك بتنفيذ `coordinator.Coordinator` + مقابل البايتات المعيارية الموثَّقة في `SPEC.md`. +- **بديل مؤقت (stub) غير مبني:** الحزمة `anchor/` — طبقة مطالبات التوظيف + المشهودة (المشكلة المفتوحة رقم 6). وهي موسومة بأنها بديل مؤقت؛ راجع + وثيقة الحزمة الخاصة بها. + +## الرخصة + +AGPL-3.0-or-later. الوثيقة `SPEC.md` جزء من المشاعات: فهي موجودة لتُقرأ، +ويُعاد تنفيذها، وتُناقَش. فالمشاعات التي لا يستطيع أحد قراءتها حريةٌ لا +يستطيع أحد استخدامها. + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.es.md b/README.es.md new file mode 100644 index 0000000..54779ce --- /dev/null +++ b/README.es.md @@ -0,0 +1,78 @@ +> Traducción comunitaria (borrador) — Política P2-002 de NTARI, Difusión Multilingüe Global. Fuente: README.md (original en inglés, instantánea del 2026-07-29). Borrador comunitario asistido por máquina, pendiente de revisión por el mantenedor regional conforme a P2-002 §3.1. Las especificaciones técnicas centrales permanecen en inglés conforme al §2.2. +> +> ¿Encontraste un error en esta traducción? Tu corrección es una contribución +> bienvenida y valorada: haz un fork del repositorio y abre un pull request en +> https://github.com/NTARI-RAND/sohocloud-protocol. + +# sohocloud-protocol + +El módulo de Go compartido que define el **protocolo de coordinación del sustrato** para la +red SoHoLINK / Cloudy: reconocimiento de nodos, listado de capacidades y empleo de +trabajos, hablado por cada coordinador y cada frontend. + +## Alcance + +Este módulo rige **únicamente la coordinación**. **No** es la economía de miembros +JFA — sin depósito en garantía (escrow), sin crédito emitido por miembros, sin pacto de +reputación, sin registro sellado por diálogo, sin adjudicación de disputas. Todo eso vive en +cada frontend y está deliberadamente ausente aquí. + +Es una **hoja de dependencias**: no importa ningún otro módulo de NTARI ni nada más que +la biblioteca estándar de Go. Tanto SoHoLINK (el coordinador de referencia) como Cloudy +(un frontend) importan *este módulo*; nada se importa de vuelta a través de él. Esa propiedad +— impuesta por el grafo de importaciones, no por la prosa — es lo que impide que un +coordinador cualquiera se convierta en un concentrador (hub) por el que toda la red deba enrutarse +(problema abierto #7). + +## Roles + +Los frontends hablan la superficie del lado del nodo — `SubmitListing`, `Heartbeat`, +`PollJobs`, `Decline`, `ReportJob`, `Fees` — en nombre de las máquinas que aportan sus +miembros; los coordinadores implementan la interfaz `Coordinator` y +coordinan (y federan) los frontends. Las personas nunca aparecen en el cable (wire): +la identidad de los miembros es asunto del frontend, y la única identidad que este módulo +conoce es la identidad de carga de trabajo — el NodeID con su vínculo canónico SPIFFE en +`identity/`. + +## Estructura + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## Estado (honesto) + +- **Construido:** los tipos de mensaje, los bytes canónicos de firma, firma/verificación + ed25519, la interfaz `Coordinator` y un transporte de referencia HTTP+JSON bajo + `transport/httpjson`. +- **Vectores de conformidad:** `testdata/vectors.json` es el fixture normativo de + conformidad entre lenguajes — 25 casos primitivos más los seis tipos de mensaje + firmados con sus bytes canónicos y firmas ed25519. Una implementación externa es + conforme si y solo si reproduce el fixture byte por byte a partir de + las mismas entradas (`SPEC.md` §10). La prueba de `vectors/` regenera el fixture + a partir de los codificadores actuales y hace fallar la compilación ante cualquier desviación. +- **Transporte de referencia, no el protocolo de cable:** `transport/httpjson` es opcional y + no es importado por ningún paquete central. Una implementación conforme PUEDE hablar estos + mensajes sobre cualquier transporte implementando `coordinator.Coordinator` contra + los bytes canónicos documentados en `SPEC.md`. +- **Stub, no construido:** `anchor/` — la capa de reclamos de empleo con testigos + (problema abierto #6). Etiquetado como sustituto provisional; véase la documentación de su paquete. + +## Licencia + +AGPL-3.0-or-later. `SPEC.md` es parte del procomún: existe para ser leído, +reimplementado y disputado. Un procomún que nadie puede leer es una libertad que nadie puede +usar. + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..782a98d --- /dev/null +++ b/README.fr.md @@ -0,0 +1,85 @@ +> Traduction communautaire (version préliminaire) — politique NTARI P2-002, Diffusion multilingue mondiale. Source : README.md (original anglais, instantané du 2026-07-29). Brouillon communautaire assisté par machine, en attente de relecture par le mainteneur régional conformément à la politique P2-002 §3.1. Les spécifications techniques fondamentales restent en anglais conformément au §2.2. +> +> Vous avez remarqué une erreur de traduction ? N'hésitez pas à la corriger +> vous-même : forkez le dépôt https://github.com/NTARI-RAND/sohocloud-protocol +> et ouvrez une pull request. Les corrections de traduction sont des +> contributions précieuses, tout autant que le code. + +# sohocloud-protocol + +Le module Go partagé qui définit le **protocole de coordination du substrat** du +réseau SoHoLINK / Cloudy : reconnaissance des nœuds, déclaration des capacités +et embauche pour les tâches — un protocole parlé par chaque coordinateur et +chaque frontend. + +## Périmètre + +Ce module régit **uniquement la coordination**. Il n'est **pas** l'économie des +membres JFA : pas de séquestre, pas de crédit émis par les membres, pas +d'engagement de réputation, pas d'enregistrement scellé par le dialogue, pas +d'arbitrage des litiges. Ces éléments résident dans chaque frontend et sont +délibérément absents ici. + +C'est une **feuille de dépendances** : il n'importe aucun autre module NTARI, et +rien d'autre que la bibliothèque standard de Go. SoHoLINK (le coordinateur de +référence) comme Cloudy (un frontend) importent *ce* module ; rien n'est +réimporté à travers lui. Cette propriété — garantie par le graphe +d'importation, et non par la prose — est ce qui empêche un coordinateur +quelconque de devenir un hub par lequel tout le réseau devrait passer +(problème ouvert n° 7). + +## Rôles + +Les frontends parlent la surface côté nœud — `SubmitListing`, `Heartbeat`, +`PollJobs`, `Decline`, `ReportJob`, `Fees` — pour le compte des machines que +leurs membres mettent à disposition ; les coordinateurs implémentent l'interface +`Coordinator` et coordonnent (et fédèrent) les frontends. Les personnes +n'apparaissent jamais sur le réseau : l'identité des membres relève du +frontend, et la seule identité que connaît ce module est l'identité de charge de +travail (workload) — le NodeID et sa liaison SPIFFE canonique dans `identity/`. + +## Arborescence + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## État d'avancement (sans fard) + +- **Implémenté :** les types de messages, les octets canoniques de signature, la + signature et la vérification ed25519, l'interface `Coordinator`, et un + transport HTTP+JSON de référence sous `transport/httpjson`. +- **Vecteurs de conformité :** `testdata/vectors.json` est la fixture de + conformité normative multilangages — 25 cas primitifs plus les six types de + messages signés, avec leurs octets canoniques et leurs signatures ed25519. Une + implémentation externe est conforme si et seulement si elle reproduit la + fixture octet par octet à partir des mêmes entrées (`SPEC.md` §10). Le test + `vectors/` régénère la fixture depuis les encodeurs actuels et fait échouer le + build à la moindre divergence. +- **Transport de référence, et non le protocole de transmission :** + `transport/httpjson` est facultatif et n'est importé par aucun paquet du cœur. + Une implémentation conforme PEUT véhiculer ces messages sur n'importe quel + transport, en implémentant `coordinator.Coordinator` par rapport aux octets + canoniques documentés dans `SPEC.md`. +- **Ébauche (stub), non implémenté :** `anchor/` — la couche de revendication + d'embauche avec témoins (problème ouvert n° 6). Signalé comme provisoire ; + voir la documentation de son paquet. + +## Licence + +AGPL-3.0-or-later. `SPEC.md` fait partie des communs : il existe pour être lu, +réimplémenté et contesté. Des communs que personne ne peut lire sont une liberté +que personne ne peut exercer. + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.hi.md b/README.hi.md new file mode 100644 index 0000000..45b3c06 --- /dev/null +++ b/README.hi.md @@ -0,0 +1,84 @@ +> सामुदायिक अनुवाद (मसौदा) — NTARI नीति P2-002, Global Multilingual Broadcast। स्रोत: README.md (अंग्रेज़ी मूल, स्नैपशॉट 2026-07-29)। P2-002 §3.1 के अनुसार क्षेत्रीय अनुरक्षक (regional maintainer) की समीक्षा हेतु लंबित, मशीन-सहायता से तैयार सामुदायिक मसौदा। §2.2 के अनुसार मुख्य तकनीकी विनिर्देश अंग्रेज़ी में ही रहते हैं। +> +> अनुवाद में कोई त्रुटि दिखे तो कृपया उसे स्वयं सुधारने में मदद करें: +> रिपॉज़िटरी को फ़ॉर्क (fork) करें और अपना सुधार पुल रिक्वेस्ट (pull request) +> के रूप में भेजें — https://github.com/NTARI-RAND/sohocloud-protocol। +> अनुवाद-सुधार हमारे लिए किसी भी अन्य योगदान जितने ही मूल्यवान हैं, और उनका +> सदा स्वागत है। + +# sohocloud-protocol + +SoHoLINK / Cloudy नेटवर्क के लिए **सब्सट्रेट समन्वय प्रोटोकॉल** को परिभाषित +करने वाला साझा Go मॉड्यूल: नोड पहचान, क्षमता सूचीकरण (capability listing), +और जॉब नियोजन — जिसे हर कोऑर्डिनेटर और हर फ़्रंटएंड बोलता है। + +## दायरा + +यह मॉड्यूल केवल **समन्वय** को नियंत्रित करता है। यह JFA सदस्य अर्थव्यवस्था +**नहीं** है — न कोई एस्क्रो, न सदस्य-जारी क्रेडिट, न प्रतिष्ठा अनुबंध +(reputation covenant), न संवाद-मुद्रित रिकॉर्ड (dialog-sealed record), न +विवाद निपटान। ये सब हर फ़्रंटएंड में रहते हैं और यहाँ जान-बूझकर अनुपस्थित +हैं। + +यह एक **डिपेंडेंसी लीफ़** है: यह किसी अन्य NTARI मॉड्यूल को इम्पोर्ट नहीं +करता, और Go स्टैंडर्ड लाइब्रेरी के अलावा कुछ भी नहीं। SoHoLINK (संदर्भ +कोऑर्डिनेटर) और Cloudy (एक फ़्रंटएंड) दोनों *इसे* इम्पोर्ट करते हैं; इसके +माध्यम से कुछ भी वापस इम्पोर्ट नहीं होता। यही गुण — जो गद्य से नहीं बल्कि +इम्पोर्ट ग्राफ़ से लागू होता है — किसी एक कोऑर्डिनेटर को ऐसा हब बनने से +रोकता है जिससे होकर पूरे नेटवर्क को रूट करना पड़े (खुली समस्या #7)। + +## भूमिकाएँ + +फ़्रंटएंड नोड-पक्ष की सतह बोलते हैं — `SubmitListing`, `Heartbeat`, +`PollJobs`, `Decline`, `ReportJob`, `Fees` — उन मशीनों की ओर से जिन्हें उनके +सदस्य योगदान करते हैं; कोऑर्डिनेटर `Coordinator` इंटरफ़ेस को लागू करते हैं +और फ़्रंटएंड्स का समन्वय (तथा फ़ेडरेशन) करते हैं। व्यक्ति कभी वायर पर प्रकट +नहीं होते: सदस्य पहचान फ़्रंटएंड का विषय है, और इस मॉड्यूल को ज्ञात एकमात्र +पहचान वर्कलोड पहचान है — NodeID, अपनी कैनोनिकल SPIFFE बाइंडिंग के साथ +`identity/` में। + +## संरचना + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## स्थिति (ईमानदार) + +- **निर्मित:** संदेश प्रकार, कैनोनिकल साइनिंग बाइट्स, ed25519 साइन/वेरिफ़ाई, + `Coordinator` इंटरफ़ेस, और `transport/httpjson` के अंतर्गत एक संदर्भ + HTTP+JSON ट्रांसपोर्ट। +- **कन्फ़ॉर्मेंस वेक्टर:** `testdata/vectors.json` मानकीय (normative) + क्रॉस-लैंग्वेज कन्फ़ॉर्मेंस फ़िक्स्चर है — 25 प्रिमिटिव केस तथा सभी छह + हस्ताक्षरित संदेश प्रकार, अपने कैनोनिकल बाइट्स और ed25519 हस्ताक्षरों + सहित। कोई बाहरी कार्यान्वयन तभी और केवल तभी कन्फ़ॉर्मेंट है जब वह समान + इनपुट से फ़िक्स्चर को बाइट-दर-बाइट पुनरुत्पादित करे (`SPEC.md` §10)। + `vectors/` टेस्ट वर्तमान एनकोडरों से फ़िक्स्चर को पुनर्जनित करता है और + किसी भी विचलन (drift) पर बिल्ड विफल कर देता है। +- **संदर्भ ट्रांसपोर्ट, वायर नहीं:** `transport/httpjson` वैकल्पिक है और इसे + कोई कोर पैकेज इम्पोर्ट नहीं करता। कोई कन्फ़ॉर्मेंट कार्यान्वयन `SPEC.md` + में प्रलेखित कैनोनिकल बाइट्स के अनुसार `coordinator.Coordinator` को लागू + करके इन संदेशों को किसी भी ट्रांसपोर्ट पर बोल सकता है (MAY)। +- **स्टब, निर्मित नहीं:** `anchor/` — साक्ष्य-आधारित नियोजन-दावा परत + (witnessed employment-claim layer) (खुली समस्या #6)। स्टैंड-इन के रूप में + चिह्नित; इसका पैकेज दस्तावेज़ देखें। + +## लाइसेंस + +AGPL-3.0-or-later। `SPEC.md` कॉमन्स (साझा संपदा) का हिस्सा है: इसका अस्तित्व +इसलिए है कि इसे पढ़ा जाए, पुनः कार्यान्वित किया जाए, और चुनौती दी जाए। जिस +कॉमन्स को कोई पढ़ ही न सके, वह ऐसी स्वतंत्रता है जिसका कोई उपयोग नहीं कर +सकता। + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.pt.md b/README.pt.md new file mode 100644 index 0000000..d13df83 --- /dev/null +++ b/README.pt.md @@ -0,0 +1,81 @@ +# sohocloud-protocol + +> Tradução comunitária (rascunho) — política P2-002 da NTARI, Transmissão Multilíngue Global. Fonte: README.md (original em inglês, snapshot de 2026-07-29). Rascunho comunitário assistido por máquina, pendente de revisão por mantenedor regional conforme P2-002 §3.1. As especificações técnicas centrais permanecem em inglês conforme §2.2. +> +> Notou algum erro nesta tradução? Correções de tradução são contribuições +> valiosas e muito bem-vindas: faça um fork do repositório e abra um pull +> request em https://github.com/NTARI-RAND/sohocloud-protocol. + +O módulo Go compartilhado que define o **protocolo de coordenação do substrato** +da rede SoHoLINK / Cloudy: reconhecimento de nós, listagem de capacidades e +emprego de jobs, falado por todos os coordenadores e todos os frontends. + +## Escopo + +Este módulo governa **apenas a coordenação**. Ele **não é** a economia de +membros da JFA — sem escrow, sem crédito emitido por membros, sem pacto de +reputação, sem registro selado por diálogo, sem julgamento de disputas. Essas +coisas ficam em cada frontend e estão deliberadamente ausentes aqui. + +Ele é uma **folha de dependência**: não importa nenhum outro módulo da NTARI e +nada além da biblioteca padrão do Go. Tanto o SoHoLINK (o coordenador de +referência) quanto o Cloudy (um frontend) importam *este* módulo; nada é +importado de volta através dele. Essa propriedade — imposta pelo grafo de +importação, e não por prosa — é o que impede que um único coordenador se torne +um hub pelo qual toda a rede tenha de trafegar (problema aberto #7). + +## Papéis + +Os frontends falam a superfície do lado do nó — `SubmitListing`, `Heartbeat`, +`PollJobs`, `Decline`, `ReportJob`, `Fees` — em nome das máquinas que seus +membros contribuem; os coordenadores implementam a interface `Coordinator` e +coordenam (e federam) os frontends. Pessoas nunca aparecem no tráfego da rede: +a identidade do membro é uma questão do frontend, e a única identidade que +este módulo conhece é a identidade de carga de trabalho (workload) — o NodeID +com sua vinculação SPIFFE canônica em `identity/`. + +## Estrutura + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## Status (honesto) + +- **Implementado:** tipos de mensagem, bytes canônicos de assinatura, + assinatura/verificação ed25519, a interface `Coordinator` e um transporte + HTTP+JSON de referência em `transport/httpjson`. +- **Vetores de conformidade:** `testdata/vectors.json` é a fixture normativa + de conformidade entre linguagens — 25 casos primitivos mais todos os seis + tipos de mensagem assinada com seus bytes canônicos e assinaturas ed25519. + Uma implementação externa é conformante se e somente se reproduzir a fixture + byte a byte a partir das mesmas entradas (`SPEC.md` §10). O teste em + `vectors/` regenera a fixture a partir dos codificadores atuais e faz o build + falhar diante de qualquer divergência. +- **Transporte de referência, não o protocolo de rede:** `transport/httpjson` é + opcional e não é importado por nenhum pacote do núcleo. Uma implementação + conformante PODE falar essas mensagens sobre qualquer transporte, + implementando `coordinator.Coordinator` em relação aos bytes canônicos + documentados em `SPEC.md`. +- **Stub, não implementado:** `anchor/` — a camada testemunhada de + reivindicação de emprego (problema aberto #6). Rotulada como substituto + provisório; veja a documentação do pacote. + +## Licença + +AGPL-3.0-or-later. `SPEC.md` faz parte do commons: ele existe para ser lido, +reimplementado e contestado. Um commons que ninguém pode ler é uma liberdade +que ninguém pode usar. + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.tok.md b/README.tok.md new file mode 100644 index 0000000..a0fe7e5 --- /dev/null +++ b/README.tok.md @@ -0,0 +1,35 @@ +*toki pona:* lipu ni li lipu lili pi kulupu jan. ona li tan lawa NTARI "P2-002". lipu suli ale li lipu "README.md" pi toki Inli (tenpo suno 2026-07-29). ilo sona li pali e lipu ni; kulupu o lukin o pona e ona kepeken "P2-002" § 3.1. + +*English:* This is a condensed community rendering under NTARI policy P2-002. The complete document is the English original README.md (snapshot 2026-07-29). Machine-assisted draft pending community review per P2-002 section 3.1. + +sina lukin e pakala lon toki ni la o pona e ona: o pali e "fork" lon +https://github.com/NTARI-RAND/sohocloud-protocol, o pana e "pull request". +pana sina li pona tawa mi mute. + +# sohocloud-protocol + +## ni li seme + +ona li kulupu lipu pi toki ilo "Go". ona li pana e nasin toki wan tawa kulupu ilo "SoHoLINK" en "Cloudy": ilo li sona e ilo ante, li toki e ken pali ona, li kama jo e pali. + +## ona li lawa e nasin toki taso + +mani awen ala. sona pi pona jan ala. utala pi jan tu ala. ijo mani ni pi kulupu "JFA" li lon ilo "frontend". + +ona li kepeken taso ijo pi toki ilo "Go". ilo "SoHoLINK" en ilo "Cloudy" li kepeken ona; ona li kepeken ala ona. tan ni la ilo lawa wan li ken ala kama nena wan pi kulupu ale ("open problem" #7). + +## jan en ilo + +ilo "frontend" li toki tan ilo pi jan kulupu ona (`SubmitListing`, `Heartbeat`, `PollJobs`, `Decline`, `ReportJob`, `Fees`). ilo lawa li pali e nasin `Coordinator`, li lawa e ilo "frontend" mute. jan li lon ala nasin toki ni: lipu ni li sona e nimi pi ilo pali taso (`NodeID` kepeken nasin "SPIFFE", lon `identity/`). + +## tenpo ni la + +- pali pini: nimi toki, sitelen pi nasin wan, sitelen ken "ed25519", nasin `Coordinator`, en nasin pana "HTTP+JSON" lon `transport/httpjson` (nasin wan taso — sina ken kepeken nasin ante). +- `testdata/vectors.json` li lipu lawa pi lukin pona: ilo sin li pona la ona li pana e sitelen sama ale (`SPEC.md` §10). +- `anchor/` li nimi taso, li pali ala ("open problem" #6). + +## sina ken kama pali + +lipu `SPEC.md` li ijo pi jan ale: o lukin e ona, o pali sin e ona, o toki utala e ona. jan ale li ken ala lukin e ijo pi jan ale la, ken ni li pona ala tawa jan. lawa lipu: AGPL-3.0-or-later. + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 0000000..cc9670e --- /dev/null +++ b/README.zh.md @@ -0,0 +1,48 @@ +> 社区翻译(草案)—— NTARI 政策 P2-002《全球多语言广播》。来源:README.md(英文原版,2026-07-29 快照)。本文为机器辅助的社区草案,依据 P2-002 §3.1 尚待区域维护者审校。依据 §2.2,核心技术规范仍以英文为准。 +> +> 如发现译文有误,欢迎 fork 仓库并提交 Pull Request +> 来改进翻译:https://github.com/NTARI-RAND/sohocloud-protocol。翻译修正与代码贡献同样宝贵,我们诚挚欢迎。 + +# sohocloud-protocol + +本共享 Go 模块定义了 SoHoLINK / Cloudy 网络的**基底协调协议**(substrate coordination protocol):节点识别、能力列示与作业雇用,由每个协调器和每个前端共同遵循。 + +## 适用范围 + +本模块仅管辖**协调**层面。它**不是** JFA 会员经济体系 —— 不含资金托管(escrow)、不含会员发行的信用、不含声誉契约、不含对话封存记录、也不含争议裁决。这些均存在于各前端之中,并被有意地排除在本模块之外。 + +它是一个**依赖叶节点**(dependency leaf):除 Go 标准库外,它不导入任何其他 NTARI 模块,也不导入任何别的东西。SoHoLINK(参考协调器)和 Cloudy(一个前端)都导入*本模块*;而没有任何东西通过它被反向导入。这一特性——由导入图(import graph)而非文字约定来强制保证——正是防止任何单一协调器演变为整个网络都必须经由的中心枢纽的关键所在(开放问题 #7)。 + +## 角色 + +前端代表其成员贡献的机器,使用节点侧接口 —— `SubmitListing`、`Heartbeat`、`PollJobs`、`Decline`、`ReportJob`、`Fees`;协调器实现 `Coordinator` 接口,负责协调(并联合)各前端。自然人从不出现在线路协议中:成员身份是前端层面的事务,本模块所认知的唯一身份是工作负载身份(workload identity)—— 即 NodeID 及其在 `identity/` 中的规范 SPIFFE 绑定。 + +## 目录结构 + +``` +version.go protocol version (v0, unstable) +canon/ deterministic length-prefixed signing encoder +identity/ NodeID + the canonical SPIFFE binding predicate +listing/ CapabilityListing (node-signed) +liveness/ Heartbeat (node-signed) +employment/ Assignment (coordinator-signed); Decline, JobReport (node-signed) +fees/ FeeDeclaration (coordinator-signed) +coordinator/ the Coordinator interface — the pluggable role, no algorithm +anchor/ STUB, not built — witnessed employment-claim layer (#6) +transport/httpjson/ reference transport; imported by no core package +vectors/ conformance test: regenerates and checks testdata/vectors.json +testdata/vectors.json cross-language conformance vectors (normative fixture; see SPEC.md §10) +``` + +## 状态(如实说明) + +- **已构建:** 消息类型、规范签名字节(canonical signing bytes)、ed25519 签名/验证、`Coordinator` 接口,以及位于 `transport/httpjson` 下的参考 HTTP+JSON 传输。 +- **一致性向量:** `testdata/vectors.json` 是规范性的跨语言一致性测试夹具(fixture)—— 包含 25 个基元用例,以及全部六种带签名的消息类型及其规范字节和 ed25519 签名。当且仅当一个外部实现能够从相同输入逐字节复现该夹具时,才被视为符合一致性要求(`SPEC.md` §10)。`vectors/` 测试会用当前的编码器重新生成该夹具,一旦出现任何漂移即令构建失败。 +- **参考传输,而非线路协议本身:** `transport/httpjson` 是可选的,且不被任何核心包导入。符合一致性要求的实现可以(MAY)通过任意传输方式传递这些消息,只需针对 `SPEC.md` 中记载的规范字节实现 `coordinator.Coordinator` 即可。 +- **桩代码(stub),尚未构建:** `anchor/` —— 带见证的雇用声明层(witnessed employment-claim layer,开放问题 #6)。已标注为占位实现;参见其包文档。 + +## 许可证 + +AGPL-3.0-or-later。`SPEC.md` 是公共资源(commons)的一部分:它的存在就是为了被阅读、被重新实现、被质疑。无人能读的公共资源,就是无人能用的自由。 + +*Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org*