위키 · 구현 참조

공개 참조 구현

공개 저장소의 요청 제출, 워커 처리, 파일 전송 함수가 파일 handoff 계약을 어떻게 구현하는지 연결합니다. 각 동작은 독립 테스트와 합성 예제로 확인합니다.

이 문서는 공개 교육용 구현만 다룹니다. 로컬 운영 경로와 전체 경계는 구성과 범위에서 확인합니다.

모듈이 맡는 부분

파일	함수	프로토콜과의 대응
`reference/orchestrator.py`	`request_digest(request)`	요청 객체를 키 정렬·압축 JSON으로 직렬화한 바이트의 SHA-256을 계산합니다. 이 함수는 `submit`이나 워커가 호출하지 않습니다. 워커 응답의 `request_sha256`은 실제 요청 파일 바이트의 해시이므로 두 값은 다를 수 있습니다.
`reference/orchestrator.py`	`submit(request, inbox)`	필수 키와 형식, 안전한 `request_id`를 확인해 inbox에 JSON 요청을 생성합니다. 같은 파일을 다시 제출하면 동일 내용은 멱등 처리하고, 같은 ID의 다른 내용은 거부합니다.
`reference/orchestrator.py`	`collect(request_id, outbox)`	응답 파일을 읽어 요청 ID 일치와 terminal 상태(`done`, `partial`, `failed`, `blocked`)를 확인한 뒤 반환합니다.
`reference/worker.py`	`resolve_inputs(root, names)`	입력의 절대경로·상위 경로 참조를 거부하고, 해석된 파일이 허용 루트 아래의 일반 파일인지 확인합니다.
`reference/worker.py`	`process_one(request_path, outbox, allowed_root, handler)`	요청 원본 바이트의 digest를 계산하고 JSON 필드를 검증한 뒤 입력 경계를 검사합니다. 사용자 handler 또는 기본 handler를 한 번 실행하고 terminal 응답을 발행합니다. 잘못된 요청은 `blocked`, 예외는 남은 산출이 있으면 `partial`, 없으면 `failed`가 됩니다.
`reference/worker.py`	`_response(...)`, `_publish(...)`	응답에 요청·목표 ID와 revision, status, request digest, 산출 목록을 담고, 동일 요청에 이미 terminal 응답이 있으면 내용을 비교해 덮어쓰지 않습니다.
`reference/filesystem_transport.py`	`encode_json(value)`, `read_json(path)`	UTF-8 JSON object를 일관되게 인코딩·읽습니다. 최상위 값이 객체가 아니면 거부합니다.
`reference/filesystem_transport.py`	`write_json_atomic(path, value, replace=False)`	같은 디렉터리에 임시 파일을 쓰고 flush/fsync한 뒤 원자적으로 게시합니다. 기본 모드는 기존 파일을 덮지 않으며 `replace=True`일 때만 교체합니다.

한 시도의 구현 순서

orchestrator.submit(request, inbox)
  → inbox/<request_id>.json
  → worker.process_one(request_path, outbox, allowed_root, handler)
  → outbox/<request_id>.json
  → orchestrator.collect(request_id, outbox)

submit은 요청 객체의 필수 필드와 경로 토큰을 검사하며, 입력 파일의 실제 루트 경계 검사는 worker의 resolve_inputs가 수행합니다. policy 객체의 라벨만으로 운영체제 권한이 생기거나 제한되지 않습니다. worker는 허용 루트 밖으로 해석되는 입력을 막지만 프로세스 사용자·파일 권한은 호출자가 책임집니다.

요청 객체 해시와 파일 해시

request_digest(request)는 압축 JSON을 해싱합니다. submit이 쓰는 요청 파일은 encode_json의 들여쓰기 2칸과 마지막 줄바꿈을 포함하고, 워커는 그 파일에서 읽은 원본 바이트를 해싱합니다. 따라서 같은 요청 객체라도 두 해시는 다릅니다. 응답을 요청 파일과 대조할 때는 실제 제출한 파일의 바이트를 사용합니다.

import hashlib

file_digest = hashlib.sha256(request_path.read_bytes()).hexdigest()
assert response["request_sha256"] == file_digest

collect는 요청 ID와 terminal 상태를 확인합니다. 요청 파일 해시의 일치 여부는 호출자가 위와 같이 확인합니다.

테스트가 확인하는 경계

tests/test_contracts.py는 임시 디렉터리와 합성 입력만 사용합니다. 등록 멱등성·같은 ID의 내용 충돌, 안전하지 않은 ID, 원자 쓰기의 덮어쓰기 방지, 정상 제출-처리-수집, 경로 traversal 및 symlink 차단, 필수 필드·policy 형식 오류, handler 예외의 failed/partial 분류, terminal 응답 재처리 방지, 수집 시 request ID 불일치를 검사합니다. 테스트는 실제 Hermes 서비스나 권한 경계를 검증하지 않습니다.

예제에서 분리한 동작

경로	관찰하는 동작	한계
`examples/integration-check/src/integration_check.py`	`LIGHT_FILES`로 단계별 필요 파일을 비교하고, fixture를 읽어 합성 산출을 먼저 쓴 다음 누락 조건을 응답에 기록합니다. 승인 근거가 모두 있으면 `done`, 빠진 조건이 있으면 `partial`입니다.	실제 gate나 JOB을 실행하지 않고 fixture의 선언을 점검합니다.
`examples/integration-check/tests/test_integration_check.py`	요청 조건·단계 파일·승인 근거가 충족된 fixture와 조건이 빠진 fixture를 비교합니다.	합성 fixture만 대상으로 합니다.
`examples/knowledge-context-check/src/knowledge_check.py`	`inspect(request_path, lessons_path)`는 제공된 lesson 목록에서 문자열 후보를 찾고 출처·갱신일·검증·리뷰 상태를 정규화합니다. 결과에 `claim_verified: false`, `promotion_performed: false`를 명시합니다.	저장소를 검색하지 않으며 주장을 검증하거나 교훈을 승격하지 않습니다.
`examples/knowledge-context-check/tests/test_knowledge_check.py`	합성 후보의 상태값과 근거 없는 메타데이터가 `unknown` 및 비승격으로 보존되는지 검사합니다.	실제 지식 저장소의 검색·정리 작업은 수행하지 않습니다.

실행 명령

저장소 루트에서 Python 3.11 이상으로 실행합니다. make test는 reference 계약 테스트와 두 fixture 예제 테스트를 실행합니다. 개별 묶음은 아래처럼 선택합니다.

make test
make example NAME=portable-worker
make example NAME=integration-check
make example NAME=knowledge-context-check

사이트 변경까지 확인할 때는 make build 뒤 make check를 사용할 수 있습니다. 이 페이지의 명령은 공개 저장소용이며 로컬 운영 확장의 dispatcher·JOB·게이트를 실행하지 않습니다.

근거 파일

내용	공개 저장소 원본
요청 등록·응답 수집	`reference/orchestrator.py`
입력 경계·worker·응답	`reference/worker.py`
JSON 파일 게시·읽기	`reference/filesystem_transport.py`
계약 테스트	`tests/test_contracts.py`
예제 구현·테스트	`examples/integration-check/src/`, `examples/integration-check/tests/`, `examples/knowledge-context-check/src/`, `examples/knowledge-context-check/tests/`
실행 명령	`Makefile`

확인 기준: 2026-10-13. 함수와 실행 명령은 공개 저장소의 현재 파일에서 확인했습니다.