기록 레이어

버전 범위: 이 페이지는 현재 표준인 DWP 7.0.0이 기반으로 삼는 규범적 v6 기록 레이어를 다시 서술합니다. 릴리스 v7.9.0 기준 정식 출처: V6_CONTRACT.md, V6_LIFECYCLE.md. 이 페이지와 해당 파일이 다를 경우 파일이 우선합니다. v5 계획은 계획 상태 레이어를 유지하며 암묵적으로 마이그레이션되는 일은 결코 없습니다.

버전 6.0.0, 7.0.0에서 확장. 상태: 안정(Stable). 기록 레이어는 서술형 완료를 기록으로 대체합니다: 계약이 권한의 근거이고, 저널이 기억이며, 헬퍼가 기록을 작성하고, 생성된 모든 파일은 프로젝션입니다. 키워드 MUST, MUST NOT, SHOULD, SHOULD NOT, MAY는 RFC 2119에 기술된 대로 해석됩니다.

한 줄 모델

계획은 두 개의 작성된 산출물과 하나의 보호된 시퀀스로 이루어집니다. 계획 Markdown(README.md와 작업 파일)은 무엇을 할지 말합니다. 결과 계약(contract.json)은 무엇이 완료로 인정되는지, 그리고 계획이 무엇을 할 수 있는지 말합니다. 저널(journal.ndjson)은 실제로 일어난 일을 기록합니다. state.json과 views/는 저널로부터 재생성되며 손으로 편집해서는 안 됩니다(MUST NOT). 생성된 파일과 저널이 불일치하면 저널이 우선하고 파일은 재생성됩니다.

세대 감지

계획 폴더는 contract 포인터가 해석되는 manifest.json, contract.json, 또는 contracts/ 개정 체인을 갖고 있을 때, 그리고 그때에만 v6 계열 계획입니다. 감지는 이 산출물을 사용해야(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 형태로 투영됩니다.

결과 계약

계획마다 하나의 계약이 있으며, 해당 세대의 스키마를 따릅니다. 계약에는 결과 서술과 성공 정의, 인수 기준, 선행 조건·변경 표면·게이트 의도를 갖춘 작업, 계획 범위의 불변 조건, 범위(허용 경로, 명령 클래스, 금지된 작업), 리소스 한도(envelope), 스케줄링 한도, 권한, 그리고 승인 기록이 담깁니다.

식별. 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(신뢰 모드처럼 명시된 한도를 갖는 상시 허가) 중 하나입니다. 둘 다 동일하게 게이트를 통과시키며, 기록된 권한만 다릅니다.
종결 가능성. 모든 기준은 종결 가능해야(MUST) 합니다: 작업이 게이트하는 기준은 그 기준이 받아들이는 증거 등급에 따라 해당 게이트의 observed 증거나 asserted 사람의 승인으로 종결됩니다. 둘 다 받아들이지 않는 초안 기준은 거부됩니다.

구체화

계획은 손이 아니라 배포된 헬퍼(ledger.py materialize)로 구체화되며, 정확히 다음 순서를 따르고 각 단계는 멱등적이며 재개 가능합니다:

계약 포인터를 담은 manifest.json. 구체화가 중단되더라도 계획의 세대를 알 수 있도록 가장 먼저 작성됩니다.
검증되고 내용 주소화된 contract.json.
계약 id와 계획 Markdown의 다이제스트를 인용하는 approval 저널 이벤트.

작업 시작 게이트를 여는 것은 오직 이 승인 이벤트뿐입니다. 승인 이벤트 없이 손으로 복사한 계약은 작업 시작 시 거부되며, 포인터가 구체화 중인 계약과 일치하지 않는 매니페스트는 다시 쓰이지 않고 거부됩니다.

저널

journal.ndjson은 추가 전용입니다: 한 줄에 닫힌 JSON 객체 하나이며, 편집되거나 삭제되는 일은 결코 없습니다. 수정은 이후의 이벤트로 이루어집니다. 모든 이벤트는 스키마, 타입, 엄격히 증가하는 seq, 타임스탬프, 계획, contract_id, 그리고 행위자(helper, agent, host_adapter 또는 human)를 담습니다. 이벤트 카탈로그는 작업 시작, 승인, 게이트 실행, 관찰, 적응, 수정, 개입, 리소스 샘플, 대조 쌍, 스케줄러 선택, 거부, 뷰 렌더링, 조정, 저널 복구를 포괄하며, v7은 위임 이벤트를 추가합니다. 모든 거부도 그 자체로 기록됩니다.

증거 등급

증거를 담는 이벤트는 신뢰 라벨을 기록합니다:

observed — 배포된 헬퍼가 선언된 작업 디렉터리, 환경, 타임아웃, 캡처된 출력과 함께 직접 검사를 실행한 경우. observed 게이트 증거를 만들 수 있는 것은 게이트 러너(ledger.py gate)뿐이며, 자신이 보고하는 결과를 단지 적어 두는 에이전트는 이를 만들 수 없습니다.
imported — 출처가 있는 일치하는 외부 소스에서 가져온 경우. 예를 들어 증거 포인터가 해석되는, 마이그레이션된 v5 게이트 기록입니다.
asserted — 독립적인 확립 없이 진술된 경우.

각 기준은 받아들이는 등급을 선언하므로, observed 전용 기준은 주장만으로 종결될 수 없습니다. 체크섬은 바이트 동일성을 확립할 뿐 의미상의 진실을 확립하지 않습니다. 기록 레이어는 구조와 출처를 검사하며 제품의 의미를 증명하지는 않습니다.

사람의 승인

사람이 판단해야 하는 기준은 ledger.py signoff --criterion <AC> --evidence-path <artifact> --authority <who>로 종결됩니다. 승인은 asserted로 기록되고, 근거가 되는 산출물을 인용하며, 선언한 작업의 증거 창 안에서만 인정되고, asserted를 받아들이는 기준만 종결합니다. 에이전트가 사람을 대신해 승인하는 일은 결코 없습니다. 구체화 외부에서 작성되는 사람 행위자 기록은 명시적인 권한 표지(사람이 작성한 메모를 경로와 다이제스트로 기록한 것, 또는 대화형 확인)를 담습니다. 원장은 사람을 인증할 수 없으므로, 이 표지는 주장을 observed로 만드는 것이 아니라 감사 가능하게 만듭니다.

대조 기준

회귀 또는 판별 대조로 선언된 기준은 판별력 있는 대조 쌍으로만 종결됩니다: 검사가 시작 개정에서는 실패하고 새 개정에서는 통과해야 합니다. 양쪽 모두에서 통과하는 쌍은 판별력이 없는 것으로 기록되며 결코 올려 계산되지 않습니다. 시작 상태가 깨끗하지 않거나 이전 쪽을 사용할 수 없는 경우는 대조 불가로 기록되며, 결코 합성되지 않습니다.

실행과 완료

디스패치는 결정론적 스케줄러(scheduler.py ready)에서 나오며, ledger.py start는 선행 조건이 완료되지 않은 작업을 거부합니다. 각 작업 시작은 작업 트리의 지문을 기록하며, 증거는 동일한 작업과 기준에 대해 동등한 지문일 때만 재사용됩니다.

불변 조건은 계획 범위입니다. 선언된 각 불변 조건은 계획 전체에 걸쳐 유지되며, 모든 경계에서 관찰(INV-<id>: pass 또는 INV-<id>: fail: <reason>)로 평가됩니다. 일부 작업만 유지해야 하는 속성은 불변 조건이 아니라 해당 작업의 인수 기준입니다.

완료는 선언되지 않고 도출됩니다. 어떤 기준이라도 받아들여진 창 내 증거가 없거나 어떤 불변 조건이라도 새로운 통과 평가가 없는 동안에는 ledger.py complete가 거부하고, 그 거부를 기록합니다. 스냅샷은 기록이 뒷받침할 때 정확히 그때에만 작업을 완료로 표시합니다.

적응과 수정

실행 중 변경은 스케줄러에 대한 제안이며, 닫힌 집합으로 제한됩니다: split, reorder, insert, change_strategy, retry. 적응은 요건을 삭제하거나, 인수를 약화하거나 대체하거나, 범위나 권한을 확장하거나, 한도를 넘어 소비하거나, 실행되지 않은 시나리오를 완료로 표시해서는 안 됩니다(MUST NOT).

범위, 인수 기준, 권한 또는 한도의 변경은 계약 수정입니다: ledger.py amend는 수정된 계약을 다음 개정으로 준비하고, 이전 증거가 무효화되는 기준과 함께 수정을 기록하며, 사람의 권한 표지가 있는 새로운 승인을 요구하고, 그런 다음에야 라이브 계약을 전환합니다. 중단된 수정은 처음으로 빠진 단계에서 재개되며, 계획 작성 권한은 개정으로 이어지는 일이 결코 없습니다.

영수증, 뷰, 내보내기

outcomes.py receipt는 기록으로부터 계획의 결과를 다시 계산하므로 기록이 바뀌면 결과도 바뀝니다. 영수증을 손으로 쓰는 일은 결코 없습니다. views.py render는 사람이 읽을 수 있는 뷰를 재생성합니다. 사람이 편집한 뷰는 보고되며 조용히 덮어써지는 일은 결코 없고, 그 조정 자체도 기록됩니다. .dwp/는 gitignore되므로, ledger.py export --dest <dir>가 지속성을 위해 또는 다른 호스트를 위해 저널, 스냅샷, 계약 체인, 인용된 모든 증거 산출물을 묶어 줍니다.

읽기 전용 표면과 재개

status와 verify는 v6 계열 계획에 결코 쓰지 않으며, 순수 명령과 생성된 프로젝션을 통해 보고합니다. 재개하는 호스트는 정해진 순서(검사, 검증, 투영, 기록된 권한으로 렌더링)로 복구하며, 오래된 지문은 재사용 가능한 결과가 아니라 다시 실행해야 할 무효화된 증거로 취급합니다. 저널은 대화 컨텍스트로 재생되는 일이 결코 없습니다: 작업은 작업별 컨텍스트 매니페스트를 갖춘 execute 루프를 통해 재개됩니다.

공존과 마이그레이션

v5 계획과 v6 계열 계획은 하나의 .dwp/plans/ 안에 공존할 수(MAY) 있으며, 각 계획은 수명 전체 동안 자신의 세대로 실행됩니다. v5에서 v6으로 가는 유일한 경로는 검증된 백업과 롤백을 갖춘 명시적이고 미리 보기가 제공되는 마이그레이션(refine을 통해 실행되는 migrate_v6.py)입니다. 마이그레이션된 v5 이력은 증거가 해석되면 imported, 그렇지 않으면 asserted이며, 결코 observed가 아닙니다. 역방향 마이그레이션은 없습니다.