रिकॉर्ड परत

संस्करण दायरा: यह पृष्ठ उस मानक v6 रिकॉर्ड परत को पुनः प्रस्तुत करता है जिस पर वर्तमान मानक, DWP 7.0.0, आधारित है। रिलीज़ v7.9.0 पर प्रामाणिक स्रोत: V6_CONTRACT.md और V6_LIFECYCLE.md। जहाँ यह पृष्ठ और वे फ़ाइलें भिन्न हों, वहाँ फ़ाइलें मान्य होती हैं। v5 योजनाएँ योजना-स्थिति परत बनाए रखती हैं और कभी परोक्ष रूप से माइग्रेट नहीं की जातीं।

संस्करण 6.0.0, 7.0.0 में विस्तारित। स्थिति: स्थिर। रिकॉर्ड परत वर्णनात्मक पूर्णता को रिकॉर्ड से प्रतिस्थापित करती है: अनुबंध प्राधिकार है, जर्नल स्मृति है, सहायक टूल लेखन करते हैं, और हर जनित फ़ाइल एक प्रक्षेपण है। कीवर्ड MUST, MUST NOT, SHOULD, SHOULD NOT और MAY की व्याख्या RFC 2119 में वर्णित अनुसार की जानी है।

एक-पंक्ति मॉडल

एक योजना दो लिखित आर्टिफ़ैक्ट और एक संरक्षित अनुक्रम है। योजना markdown (README.md और कार्य फ़ाइलें) बताती है कि क्या किया जाएगा। परिणाम अनुबंध (contract.json) बताता है कि किसे पूर्ण माना जाएगा और योजना को क्या करने की अनुमति है। जर्नल (journal.ndjson) दर्ज करता है कि वास्तव में क्या हुआ। state.json और views/ जर्नल से पुनर्जनित होते हैं और इन्हें हाथ से संपादित MUST NOT किया जाना चाहिए; जब कोई जनित फ़ाइल और जर्नल असहमत हों, तो जर्नल मान्य होता है और फ़ाइल पुनर्जनित की जाती है।

पीढ़ी की पहचान

कोई योजना फ़ोल्डर v6-श्रृंखला की योजना है यदि और केवल यदि उसमें ऐसा manifest.json हो जिसका contract पॉइंटर हल होता हो, एक contract.json हो, या एक contracts/ संशोधन-शृंखला हो। पहचान इन्हीं आर्टिफ़ैक्ट से MUST होनी चाहिए, स्थापित पैक के संस्करण से कभी नहीं: एक वर्तमान पैक v5 योजनाएँ रख सकता है, और एक पुराना पैक v6 योजना से मिल सकता है।

अनुबंध का schema URL उसकी पीढ़ी बताता है, और मेनिफ़ेस्ट तथा हर जर्नल घटना उसी को दोहराते हैं:

पीढ़ी	अनुबंध	जर्नल घटनाएँ	मेनिफ़ेस्ट	जोड़ता है
v6	`plan-contract/v6`	`journal-event/v6`	`plan-manifest/v6`	—
v7	`plan-contract/v7`	`journal-event/v7`	`plan-manifest/v7`	`parallel_safe` और `delegation` घटना (प्रत्यायोजन)

7.x पैक द्वारा बनाई गई नई योजनाएँ डिफ़ॉल्ट रूप से v7 होती हैं; स्पष्ट v6 अनुरोध अब भी v6 अनुबंध बनाता है। कोई योजना कभी पीढ़ी नहीं बदलती, और पीढ़ियों को मिलाने वाला जर्नल अस्वीकार MUST किया जाना चाहिए। दोनों पीढ़ियाँ एक ही plan-snapshot/v6 आकार में प्रक्षेपित होती हैं।

परिणाम अनुबंध

प्रति योजना एक अनुबंध, जो अपनी पीढ़ी के स्कीमा के अनुरूप होता है। इसमें परिणाम-कथन और सफलता की परिभाषा, स्वीकृति मानदंड, पूर्वापेक्षाओं, छुई गई सतह और गेट-आशय सहित कार्य, योजना-स्तरीय अपरिवर्तनीय नियम, दायरा (अनुमत पाथ, कमांड-वर्ग, निषिद्ध संक्रियाएँ), संसाधन-सीमा, शेड्यूलिंग सीमाएँ, अनुमतियाँ और प्राधिकरण-रिकॉर्ड होते हैं।

पहचान। contract_id अनुबंध के कैनोनिकल बाइट्स (id फ़ील्ड के बिना) का SHA-256 है। अनुबंध के अंतर्गत बना हर रिकॉर्ड इसे उद्धृत करता है।
अपरिवर्तनीयता। निष्पादन शुरू होने के बाद अनुबंध MUST NOT बदलना चाहिए। बदला हुआ अनुबंध contracts/ के अंतर्गत एक नया संशोधन है, जो अपने पैरेंट को उद्धृत करता है, जिसकी संशोधन-संख्याएँ सतत होती हैं और जिसके लिए नया दर्ज प्राधिकार होता है।
स्थिर id। मानदंड (AC-*), अपरिवर्तनीय नियम (INV-*) और कार्य (T-*) अद्वितीय MUST होने चाहिए, और रिकॉर्ड id उद्धृत करते हैं, सूची-स्थान कभी नहीं। कार्य-ग्राफ़ अचक्रीय MUST होना चाहिए, और हर गेट-आशय को किसी घोषित मानदंड का संदर्भ देना MUST।
अनुमतियाँ। प्रदत्त और अप्रदत्त क्षमताएँ एक बंद समुच्चय के असंयुक्त उपसमुच्चय MUST होनी चाहिए: gate_command_exec, fs_write_plan_scope, fs_write_repo_scope, git_operations, network_access, host_adapter_metering, agent_delegation, context_export।
प्राधिकरण। तंत्र ठीक-ठीक plan_authorship (मनुष्य ने निष्पादन से पहले योजना लिखी या समीक्षित की) या pre_authorization (एक घोषित सीमा वाला स्थायी अनुदान, जैसे trust mode में) होता है। दोनों समान रूप से गेट करते हैं; केवल दर्ज प्राधिकार भिन्न होता है।
बंद-योग्यता। हर मानदंड बंद-योग्य MUST होना चाहिए: जिस मानदंड को कोई कार्य गेट करता है, वह उसके स्वीकृत साक्ष्य-वर्गों के अनुसार उसके गेट के observed साक्ष्य से या asserted मानवीय स्वीकृति से बंद होता है। जो मसौदा मानदंड दोनों में से किसी को स्वीकार नहीं करता, वह अस्वीकार किया जाता है।

मूर्तीकरण

योजना का मूर्तीकरण शिप किए गए सहायक टूल (ledger.py materialize) से होता है, कभी हाथ से नहीं, और ठीक इसी क्रम में, हर चरण idempotent और फिर से शुरू करने योग्य होता है:

अनुबंध पॉइंटर के साथ manifest.json, सबसे पहले लिखा जाता है ताकि मूर्तीकरण बाधित होने पर भी योजना की पीढ़ी खोजी जा सके।
contract.json, सत्यापित और सामग्री-आधारित पते वाला।
approval जर्नल घटना, जो अनुबंध id और योजना markdown के digest को उद्धृत करती है।

केवल यही approval घटना कार्य-आरंभ गेट खोलती है। उसके बिना हाथ से कॉपी किया गया अनुबंध कार्य-आरंभ पर अस्वीकार होता है, और जिस मेनिफ़ेस्ट का पॉइंटर मूर्त किए जा रहे अनुबंध से मेल नहीं खाता, उसे फिर से लिखने के बजाय अस्वीकार किया जाता है।

जर्नल

journal.ndjson केवल-जोड़ है: प्रति पंक्ति एक बंद JSON ऑब्जेक्ट, जिसे कभी संपादित या हटाया नहीं जाता। सुधार एक बाद की घटना है। हर घटना में उसका स्कीमा, प्रकार, सख़्ती से बढ़ता seq, टाइमस्टैम्प, योजना, contract_id और कर्ता (helper, agent, host_adapter या human) होता है। घटना-सूची में कार्य-आरंभ, अनुमोदन, गेट-रन, अवलोकन, अनुकूलन, संशोधन, हस्तक्षेप, संसाधन-नमूने, नियंत्रण-जोड़े, शेड्यूलर-चयन, अस्वीकृतियाँ, view-रेंडर, समाधान और जर्नल-मरम्मत शामिल हैं; v7 प्रत्यायोजन घटनाएँ जोड़ता है। हर अस्वीकृति स्वयं दर्ज होती है।

साक्ष्य-वर्ग

साक्ष्य ले जाने वाली घटनाएँ एक trust लेबल दर्ज करती हैं:

observed — शिप किए गए सहायक टूल ने स्वयं जाँच चलाई, घोषित कार्य-डायरेक्टरी, environment, timeout और कैप्चर किए गए आउटपुट के साथ। केवल गेट रनर (ledger.py gate) observed गेट साक्ष्य बनाता है; जो एजेंट केवल अपने बताए परिणाम को लिख देता है, वह नहीं बना सकता।
imported — मिलान किए गए बाहरी स्रोत से उत्पत्ति सहित लिया गया, जैसे माइग्रेट किया गया v5 गेट रिकॉर्ड जिसका साक्ष्य पॉइंटर हल होता है।
asserted — स्वतंत्र स्थापना के बिना कहा गया।

हर मानदंड घोषित करता है कि वह कौन-से वर्ग स्वीकार करता है, इसलिए केवल-observed मानदंड किसी दावे पर कभी बंद नहीं हो सकता। checksums बाइट-पहचान स्थापित करते हैं, अर्थगत सत्य नहीं; रिकॉर्ड परत संरचना और उत्पत्ति जाँचती है और उत्पाद के अर्थ को सिद्ध नहीं करती।

मानवीय स्वीकृति

जिस मानदंड का निर्णय किसी मनुष्य को करना हो, वह ledger.py signoff --criterion <AC> --evidence-path <artifact> --authority <who> से बंद होता है। स्वीकृति asserted के रूप में दर्ज होती है, जिस आर्टिफ़ैक्ट पर वह टिकी है उसे उद्धृत करती है, केवल घोषित करने वाले कार्य की साक्ष्य-खिड़की के भीतर गिनी जाती है, और केवल उसी मानदंड को बंद करती है जो asserted स्वीकार करता है। एजेंट कभी किसी मनुष्य की ओर से स्वीकृति नहीं देता। मूर्तीकरण के बाहर लिखे गए मानव-कर्ता रिकॉर्ड में एक स्पष्ट प्राधिकार-चिह्न होता है (मनुष्य द्वारा लिखा नोट, पाथ और digest द्वारा दर्ज, या एक इंटरैक्टिव पुष्टि); लेजर किसी व्यक्ति को प्रमाणित नहीं कर सकता, इसलिए यह चिह्न दावे को observed नहीं, बल्कि लेखापरीक्षा-योग्य बनाता है।

नियंत्रित मानदंड

regression या discrimination नियंत्रण के रूप में घोषित मानदंड केवल एक विभेदक नियंत्रण-जोड़े पर बंद होता है: जाँच आरंभिक संशोधन पर विफल और नए पर पास होती है। जो जोड़ा दोनों पक्षों पर पास होता है, वह अविभेदक के रूप में दर्ज होता है और कभी ऊपर नहीं गिना जाता; गंदी आरंभिक अवस्था या अनुपलब्ध पुराना पक्ष “नियंत्रण अनुपलब्ध” के रूप में दर्ज होता है, कभी कृत्रिम रूप से नहीं बनाया जाता।

निष्पादन और पूर्णता

डिस्पैच नियतात्मक शेड्यूलर (scheduler.py ready) से आता है, और ledger.py start ऐसे कार्य को अस्वीकार करता है जिसकी पूर्वापेक्षाएँ अपूर्ण हों। हर कार्य-आरंभ कार्य-ट्री का एक fingerprint दर्ज करता है, और साक्ष्य का पुनः उपयोग केवल उसी कार्य और मानदंड के लिए समतुल्य fingerprint पर होता है।

अपरिवर्तनीय नियम योजना-स्तरीय होते हैं। हर घोषित अपरिवर्तनीय नियम पूरी योजना में लागू रहता है और हर सीमा पर एक अवलोकन के रूप में मूल्यांकित होता है (INV-<id>: pass या INV-<id>: fail: <reason>)। जो गुण केवल कुछ कार्यों को बनाए रखना हो, वह उन कार्यों का स्वीकृति मानदंड है, कभी अपरिवर्तनीय नियम नहीं।

पूर्णता व्युत्पन्न होती है, कभी घोषित नहीं। जब तक किसी मानदंड के पास स्वीकृत, खिड़की-भीतर साक्ष्य न हो या किसी अपरिवर्तनीय नियम का ताज़ा पास मूल्यांकन न हो, ledger.py complete अस्वीकार करता है और अस्वीकृति दर्ज करता है। स्नैपशॉट किसी कार्य को ठीक तभी पूर्ण दिखाता है जब रिकॉर्ड उसका समर्थन करते हैं।

अनुकूलन और संशोधन

रन के बीच के परिवर्तन शेड्यूलर को प्रस्ताव होते हैं, जो एक बंद समुच्चय तक सीमित हैं: split, reorder, insert, change_strategy और retry। कोई अनुकूलन किसी आवश्यकता को MUST NOT हटा सकता, स्वीकृति को कमज़ोर या प्रतिस्थापित नहीं कर सकता, दायरा या अनुमतियाँ नहीं बढ़ा सकता, सीमा से अधिक व्यय नहीं कर सकता, या किसी अनिष्पादित परिदृश्य को पूर्ण चिह्नित नहीं कर सकता।

दायरे, स्वीकृति मानदंडों, अनुमतियों या सीमा में परिवर्तन एक अनुबंध संशोधन है: ledger.py amend संशोधित अनुबंध को अगले संशोधन के रूप में तैयार करता है, संशोधन को उन मानदंडों सहित दर्ज करता है जिनके पहले के साक्ष्य को वह अमान्य करता है, मानवीय प्राधिकार-चिह्न के साथ नया अनुमोदन माँगता है, और तभी सजीव अनुबंध को बदलता है। बाधित संशोधन पहले लुप्त चरण से फिर शुरू होता है; योजना-लेखकत्व कभी किसी संशोधन पर आगे नहीं जाता।

रसीदें, views और निर्यात

outcomes.py receipt रिकॉर्ड से योजना का परिणाम फिर से गणना करता है, इसलिए रिकॉर्ड बदलने पर यह बदलता है; इसे कभी हाथ से नहीं लिखा जाता। views.py render मानव-पठनीय views पुनर्जनित करता है; मनुष्य द्वारा संपादित view की रिपोर्ट की जाती है, उसे कभी चुपचाप अधिलेखित नहीं किया जाता, और समाधान स्वयं दर्ज होता है। चूँकि .dwp/ gitignored है, ledger.py export --dest <dir> टिकाऊपन या किसी अन्य होस्ट के लिए जर्नल, स्नैपशॉट, अनुबंध-शृंखला और हर उद्धृत साक्ष्य आर्टिफ़ैक्ट को बंडल करता है।

केवल-पठन सतहें और पुनरारंभ

status और verify कभी किसी v6-श्रृंखला योजना में नहीं लिखते; वे शुद्ध कमांड्स और जनित प्रक्षेपणों से रिपोर्ट करते हैं। पुनरारंभ करने वाला होस्ट एक निश्चित क्रम में पुनर्प्राप्ति करता है (निरीक्षण, सत्यापन, प्रक्षेपण, दर्ज प्राधिकार सहित रेंडर) और पुराने fingerprint को फिर से चलाने योग्य अमान्य साक्ष्य मानता है, कभी पुनः उपयोग-योग्य परिणाम नहीं। जर्नल को कभी वार्तालाप-संदर्भ के रूप में दोबारा नहीं चलाया जाता: काम प्रति-कार्य संदर्भ मेनिफ़ेस्ट के साथ execute लूप के माध्यम से फिर शुरू होता है।

सह-अस्तित्व और माइग्रेशन

v5 और v6-श्रृंखला योजनाएँ एक ही .dwp/plans/ में सह-अस्तित्व MAY रख सकती हैं, और हर एक अपने पूरे जीवनकाल अपनी पीढ़ी के अंतर्गत चलती है। v5 से v6 तक का एकमात्र रास्ता एक स्पष्ट, पूर्वावलोकित माइग्रेशन है (migrate_v6.py, refine के माध्यम से चलाया गया), सत्यापित बैकअप और rollback के साथ; माइग्रेट किया गया v5 इतिहास तब imported होता है जब उसका साक्ष्य हल होता है और अन्यथा asserted, कभी observed नहीं। कोई उल्टा माइग्रेशन नहीं है।