Skip to content
← เอกสารข้อกำหนดทั้งหมด

ชั้นบันทึก

ขอบเขตเวอร์ชัน: หน้านี้เรียบเรียงชั้นบันทึก v6 เชิงบรรทัดฐานซึ่งมาตรฐานปัจจุบัน DWP 7.0.0 ต่อยอดขึ้นมา แหล่งอ้างอิงหลักในรุ่น v7.9.0: V6_CONTRACT.md และ V6_LIFECYCLE.md หากหน้านี้กับไฟล์เหล่านั้นแตกต่างกัน ให้ยึดไฟล์เป็นหลัก แผน v5 คงชั้น สถานะแผน ไว้และไม่เคยถูกย้ายโดยปริยาย

เวอร์ชัน 6.0.0 ขยายใน 7.0.0 สถานะ: เสถียร ชั้นบันทึกแทนที่การประกาศการเสร็จสิ้นด้วยคำบรรยายด้วยบันทึก: สัญญาเป็นผู้มีอำนาจ journal เป็นหน่วยความจำ helper เป็นผู้เขียน และไฟล์ที่ถูกสร้างขึ้นทุกไฟล์เป็นการฉายภาพ คำสำคัญ MUST, MUST NOT, SHOULD, SHOULD NOT และ MAY ให้ตีความตามที่อธิบายไว้ใน RFC 2119

แบบจำลองในหนึ่งบรรทัด

แผนประกอบด้วยสิ่งประดิษฐ์ที่เขียนขึ้นสองชิ้นและลำดับเหตุการณ์ที่มีการป้องกันหนึ่งชุด แผน markdown (README.md และไฟล์งาน) บอกว่าจะทำอะไร สัญญาผลลัพธ์ (contract.json) บอกว่าอะไรนับว่าเสร็จและแผนได้รับอนุญาตให้ทำอะไร journal (journal.ndjson) บันทึกสิ่งที่เกิดขึ้นจริง state.json และ views/ ถูกสร้างใหม่จาก journal และ MUST NOT ถูกแก้ไขด้วยมือ เมื่อไฟล์ที่ถูกสร้างขึ้นขัดแย้งกับ journal ให้ยึด journal และสร้างไฟล์นั้นใหม่

การตรวจจับรุ่น

โฟลเดอร์แผนเป็นแผนสาย v6 ก็ต่อเมื่อมี manifest.json ที่ตัวชี้ contract แปลงค่าได้ มี contract.json หรือมีสายการแก้ไข contracts/ เท่านั้น การตรวจจับ MUST ใช้สิ่งประดิษฐ์เหล่านี้ ไม่ใช่เวอร์ชันของแพ็กที่ติดตั้งอยู่: แพ็กปัจจุบันอาจมีแผน v5 อยู่ และแพ็กที่เก่ากว่าอาจพบแผน v6

URL schema ของสัญญาระบุ รุ่น ของมัน และ manifest กับเหตุการณ์ journal ทุกรายการสะท้อนรุ่นเดียวกัน

รุ่น สัญญา เหตุการณ์ journal Manifest สิ่งที่เพิ่ม
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 แผนไม่เคยเปลี่ยนรุ่น และ journal ที่ผสมหลายรุ่น MUST ถูกปฏิเสธ ทั้งสองรุ่นฉายเข้าสู่รูปแบบ plan-snapshot/v6 เดียวกัน

สัญญาผลลัพธ์

หนึ่งแผนมีหนึ่งสัญญา ซึ่งสอดคล้องกับ schema ของรุ่นนั้น สัญญาพกข้อความผลลัพธ์และนิยามความสำเร็จ เกณฑ์การยอมรับ งานพร้อมเงื่อนไขเบื้องต้น พื้นผิวที่แตะต้อง และเจตนาของ gate, invariant ระดับแผน ขอบเขต (พาธที่อนุญาต คลาสคำสั่ง การดำเนินการที่ห้าม) ขอบเขตทรัพยากร ข้อจำกัดการจัดตารางงาน สิทธิ์ และบันทึกการอนุญาต

  • เอกลักษณ์ contract_id คือ SHA-256 ของไบต์ canonical ของสัญญาโดยไม่รวมฟิลด์ id ทุกบันทึกที่เกิดขึ้นภายใต้สัญญาอ้างอิงค่านี้
  • การเปลี่ยนแปลงไม่ได้ เมื่อการดำเนินงานเริ่มแล้ว สัญญา MUST NOT เปลี่ยนแปลง สัญญาที่เปลี่ยนคือ revision ใหม่ภายใต้ contracts/ ที่อ้างอิง revision แม่ มีหมายเลข revision ต่อเนื่อง และมีอำนาจที่บันทึกไว้ใหม่
  • id ที่คงที่ เกณฑ์ (AC-*) invariant (INV-*) และงาน (T-*) MUST ไม่ซ้ำกัน และบันทึกอ้างอิงด้วย id ไม่ใช่ตำแหน่งในรายการ กราฟงาน MUST ไม่มีวงวน และเจตนาของ gate ทุกรายการ 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) อย่างใดอย่างหนึ่งเท่านั้น ทั้งสองผ่าน gate แบบเดียวกัน ต่างกันเพียงอำนาจที่ถูกบันทึก
  • ความสามารถในการปิด ทุกเกณฑ์ MUST ปิดได้: เกณฑ์ที่งานใช้เป็น gate ถูกปิดด้วยหลักฐาน observed จาก gate ของมัน หรือด้วยการลงนามรับรองแบบ asserted ของมนุษย์ ตามระดับหลักฐานที่เกณฑ์นั้นยอมรับ ร่างเกณฑ์ที่ไม่ยอมรับทั้งสองแบบจะถูกปฏิเสธ

Materialization

แผนถูก materialize โดย helper ที่จัดส่งมาด้วย (ledger.py materialize) ไม่ใช่ด้วยมือ ตามลำดับนี้พอดี โดยแต่ละขั้นตอน idempotent และดำเนินต่อได้

  1. manifest.json พร้อมตัวชี้สัญญา ถูกเขียนก่อนเพื่อให้ค้นพบรุ่นของแผนได้แม้ materialization ถูกขัดจังหวะ
  2. contract.json ที่ผ่านการตรวจสอบและระบุที่อยู่ด้วยเนื้อหา
  3. เหตุการณ์ journal approval ที่อ้างอิง contract id และ digest ของแผน markdown

มีเพียงเหตุการณ์ approval นั้นที่เปิด gate การเริ่มงาน สัญญาที่คัดลอกด้วยมือโดยไม่มีเหตุการณ์นี้จะถูกปฏิเสธตอนเริ่มงาน และ manifest ที่ตัวชี้ไม่ตรงกับสัญญาที่กำลัง materialize จะถูกปฏิเสธแทนที่จะถูกเขียนทับ

Journal

journal.ndjson เป็นแบบเพิ่มข้อมูลอย่างเดียว: หนึ่ง JSON object ที่ปิดสมบูรณ์ต่อหนึ่งบรรทัด ไม่เคยถูกแก้ไขหรือลบ การแก้ไขข้อผิดพลาดคือเหตุการณ์ที่ตามมาภายหลัง ทุกเหตุการณ์พก schema ประเภท seq ที่เพิ่มขึ้นอย่างเคร่งครัด timestamp แผน contract_id และผู้กระทำ (helper, agent, host_adapter หรือ human) แคตตาล็อกเหตุการณ์ครอบคลุมการเริ่มงาน การอนุมัติ การรัน gate การสังเกต การปรับเปลี่ยน การแก้ไขสัญญา การแทรกแซง ตัวอย่างทรัพยากร คู่ควบคุม การเลือกของตัวจัดตารางงาน การปฏิเสธ การเรนเดอร์ view การกระทบยอด และการซ่อมแซม journal ส่วน v7 เพิ่มเหตุการณ์การมอบหมายงาน การปฏิเสธทุกครั้งถูกบันทึกไว้ด้วยตัวมันเอง

ระดับของหลักฐาน

เหตุการณ์ที่พกหลักฐานบันทึกป้าย ความน่าเชื่อถือ ไว้

  1. observed — helper ที่จัดส่งมาด้วยรันการตรวจนั้นเอง โดยมี working directory, environment, timeout ที่ประกาศไว้และเอาต์พุตที่ถูกจับไว้ มีเพียงตัวรัน gate (ledger.py gate) เท่านั้นที่สร้างหลักฐาน gate แบบ observed ได้ เอเจนต์ที่เพียงจดผลลัพธ์ที่ตนรายงานเองไม่สามารถทำได้
  2. imported — นำมาจากแหล่งภายนอกที่จับคู่ได้พร้อมที่มา เช่น บันทึก gate ของ v5 ที่ถูกย้ายมาซึ่งตัวชี้หลักฐานแปลงค่าได้
  3. asserted — กล่าวอ้างโดยไม่มีการยืนยันอย่างเป็นอิสระ

แต่ละเกณฑ์ประกาศว่ายอมรับระดับใด ดังนั้นเกณฑ์ที่รับเฉพาะ observed จะไม่มีวันปิดด้วยคำกล่าวอ้าง checksum ยืนยันความเหมือนกันระดับไบต์ ไม่ใช่ความจริงเชิงความหมาย ชั้นบันทึกตรวจโครงสร้างและที่มา และไม่ได้พิสูจน์ความหมายของผลิตภัณฑ์

การลงนามรับรองโดยมนุษย์

เกณฑ์ที่มนุษย์ต้องเป็นผู้ตัดสินปิดผ่าน ledger.py signoff --criterion <AC> --evidence-path <artifact> --authority <who> การลงนามรับรองถูกบันทึกเป็น asserted อ้างอิงสิ่งประดิษฐ์ที่เป็นฐาน นับเฉพาะภายในช่วงหลักฐานของงานที่ประกาศ และปิดได้เฉพาะเกณฑ์ที่ยอมรับ asserted เอเจนต์ไม่เคยลงนามรับรองแทนมนุษย์ บันทึกที่ผู้กระทำเป็นมนุษย์ซึ่งเขียนนอก materialization พกเครื่องหมายอำนาจที่ระบุชัด (บันทึกที่มนุษย์เขียนซึ่งถูกบันทึกด้วยพาธและ digest หรือการยืนยันแบบโต้ตอบ) ledger ไม่สามารถยืนยันตัวตนของบุคคลได้ เครื่องหมายนี้จึงทำให้คำกล่าวอ้างตรวจสอบย้อนหลังได้ แทนที่จะเป็น observed

เกณฑ์แบบมีการควบคุม

เกณฑ์ที่ประกาศเป็นการควบคุมการถดถอยหรือการควบคุมเชิงจำแนกปิดได้เฉพาะด้วย คู่ควบคุมที่จำแนกได้: การตรวจล้มเหลวบน revision เริ่มต้นและผ่านบน revision ใหม่ คู่ที่ผ่านทั้งสองฝั่งถูกบันทึกเป็นไม่จำแนกและไม่เคยถูกปัดขึ้น จุดเริ่มต้นที่ไม่สะอาดหรือฝั่งเดิมที่ใช้ไม่ได้ถูกบันทึกเป็นการควบคุมที่ไม่พร้อมใช้ ไม่เคยถูกสังเคราะห์ขึ้น

การดำเนินงานและการเสร็จสิ้น

การส่งงานมาจากตัวจัดตารางงานแบบกำหนดได้ (scheduler.py ready) และ ledger.py start ปฏิเสธงานที่เงื่อนไขเบื้องต้นยังไม่เสร็จ การเริ่มงานแต่ละครั้งบันทึก fingerprint ของ working tree และหลักฐานถูกนำกลับมาใช้เฉพาะกับงานและเกณฑ์เดียวกันบน fingerprint ที่เทียบเท่ากันเท่านั้น

Invariant มีขอบเขตระดับแผน invariant ที่ประกาศแต่ละรายการต้องคงอยู่ตลอดทั้งแผน และถูกประเมินที่ทุกขอบเขตในฐานะการสังเกต (INV-<id>: pass หรือ INV-<id>: fail: <reason>) คุณสมบัติที่มีเพียงบางงานต้องรักษาคือเกณฑ์การยอมรับของงานเหล่านั้น ไม่ใช่ invariant

การเสร็จสิ้นถูกอนุมานได้ ไม่ใช่ถูกประกาศ ledger.py complete ปฏิเสธ และบันทึกการปฏิเสธ ตราบใดที่ยังมีเกณฑ์ใดขาดหลักฐานที่ยอมรับภายในช่วง หรือ invariant ใดขาดการประเมินที่ผ่านล่าสุด snapshot แสดงงานว่าเสร็จสิ้นก็ต่อเมื่อบันทึกรองรับเท่านั้น

การปรับเปลี่ยนและการแก้ไขสัญญา

การเปลี่ยนแปลงระหว่างการรันคือข้อเสนอต่อตัวจัดตารางงาน จำกัดอยู่ในเซตปิด: split, reorder, insert, change_strategy และ retry การปรับเปลี่ยน MUST NOT ลบข้อกำหนด ผ่อนปรนหรือทดแทนการยอมรับ ขยายขอบเขตหรือสิทธิ์ ใช้จ่ายเกินขอบเขตทรัพยากร หรือทำเครื่องหมายสถานการณ์ที่ยังไม่ถูกดำเนินการว่าเสร็จ

การเปลี่ยนแปลงขอบเขต เกณฑ์การยอมรับ สิทธิ์ หรือขอบเขตทรัพยากรคือ การแก้ไขสัญญา: ledger.py amend จัดเตรียมสัญญาที่แก้ไขเป็น revision ถัดไป บันทึกการแก้ไขพร้อมเกณฑ์ที่หลักฐานก่อนหน้าถูกทำให้เป็นโมฆะ ต้องการการอนุมัติใหม่พร้อมเครื่องหมายอำนาจของมนุษย์ แล้วจึงสลับไปใช้สัญญาใหม่ การแก้ไขที่ถูกขัดจังหวะดำเนินต่อที่ขั้นตอนแรกที่ขาดหายไป การเป็นผู้เขียนแผนไม่เคยถูกส่งต่อไปยัง revision

Receipt, view และการส่งออก

outcomes.py receipt คำนวณผลลัพธ์ของแผนใหม่จากบันทึก ดังนั้นมันจะเปลี่ยนเมื่อบันทึกเปลี่ยน และไม่เคยถูกเขียนด้วยมือ views.py render สร้าง view ที่มนุษย์อ่านได้ใหม่ view ที่มนุษย์แก้ไขจะถูกรายงาน ไม่เคยถูกเขียนทับอย่างเงียบ ๆ และการกระทบยอดก็ถูกบันทึกไว้ด้วยตัวมันเอง เนื่องจาก .dwp/ ถูก gitignore คำสั่ง ledger.py export --dest <dir> จึงรวม journal, snapshot, สายสัญญา และสิ่งประดิษฐ์หลักฐานทุกชิ้นที่ถูกอ้างอิงเป็นชุดเดียว เพื่อความคงทนหรือเพื่อโฮสต์อื่น

พื้นผิวแบบอ่านอย่างเดียวและการดำเนินต่อ

status และ verify ไม่เคยเขียนลงในแผนสาย v6 ทั้งสองรายงานผ่านคำสั่งที่บริสุทธิ์และการฉายภาพที่ถูกสร้างขึ้น โฮสต์ที่ดำเนินต่อจะกู้คืนตามลำดับที่ตายตัว (ตรวจดู ตรวจสอบ ฉายภาพ เรนเดอร์พร้อมอำนาจที่บันทึกไว้) และถือว่า fingerprint ที่ล้าสมัยเป็นหลักฐานที่เป็นโมฆะซึ่งต้องรันใหม่ ไม่ใช่ผลลัพธ์ที่นำกลับมาใช้ได้ journal ไม่เคยถูกเล่นซ้ำเป็นบริบทของบทสนทนา: งานดำเนินต่อผ่านลูป execute พร้อม context manifest ต่อหนึ่งงาน

การอยู่ร่วมกันและการย้าย

แผน v5 และแผนสาย v6 MAY อยู่ร่วมกันใน .dwp/plans/ เดียวกัน และแต่ละแผนรันภายใต้รุ่นของตนตลอดอายุของแผน เส้นทางเดียวจาก v5 ไป v6 คือการย้ายที่ชัดเจนและแสดงตัวอย่างก่อน (migrate_v6.py ซึ่งรันผ่าน refine) พร้อมการสำรองข้อมูลที่ตรวจสอบแล้วและการย้อนกลับ ประวัติ v5 ที่ถูกย้ายเป็น imported เมื่อหลักฐานแปลงค่าได้ และเป็น asserted ในกรณีอื่น ไม่เคยเป็น observed ไม่มีการย้ายแบบย้อนกลับ

ที่เกี่ยวข้อง