feat(stage2): prepare S2_00 request before ingress
Add the fixed six-field request writer and two-task S2_00 projection. Refresh bound release metadata, regression coverage, and the S2_00 analysis; backend argument binding and live admission remain pending.
This commit is contained in:
@@ -0,0 +1,157 @@
|
||||
# S2_00 request 생성·저장 계획 v2
|
||||
|
||||
작성일: 2026-10-01. 상태: **계획 작성 완료 / 구현 미착수**. [v1](s2-00-request-preparation_v1.md)의 두 task 구상과 기존 request 계약을 계승한다. 이 문서는 `s2_00_request.json`의 생성 코드를 먼저 구현·시험할 수 있도록 작업 순서를 개정한 계획이다.
|
||||
|
||||
## Objective
|
||||
|
||||
`Stage_2_S2_00.yml` 작업명세서의 맨 앞에 `Task_S2_00_prepare_request`를 배치한다. 이 작업의 핵심 함수를 네 외부 인자를 받는 명시적 인터페이스로 구현하여, 기존 6필드 검증·canonical JSON 직렬화·localdocs binary 저장/read-back 방식으로 `stage2_control/s2_00_request.json`을 만든다. 함수와 task의 offline 검증은 backend의 인자 주입·스케줄링·직렬화 구현 정보가 없어도 진행한다. 실제 운영 연결은 확인된 backend 인터페이스에만 결속한다.
|
||||
|
||||
```text
|
||||
IN → Task_S2_00_prepare_request → Task_S2_00_deterministic_ingress → OUT
|
||||
4개 인자 검증 기존 request 읽기·2회 hydration
|
||||
6필드 JSON 구성
|
||||
localdocs 저장·read-back
|
||||
```
|
||||
|
||||
위 DAG는 작업명세서에서 의도하는 순서다. `nexts`·`wait_until` 선언만으로 prepare 실패 시 ingress가 실제로 차단되거나 두 실행 사이의 파일 경합이 해소되었다고 주장하지 않는다.
|
||||
|
||||
## Deliverables
|
||||
|
||||
1. 네 인자를 받아 정확히 6필드 request bytes를 생성·검증하는 작은 함수와, 검증된 bytes를 고정 경로에 write/read-back하는 준비 함수.
|
||||
2. 준비 task를 기존 ingress 앞에 둔 authoring YAML 및 빌더로 생성한 배포 YAML, 두 task의 code mirror·빌드 receipt.
|
||||
3. 변경으로 실제 영향을 받는 workflow·executor binding·schema·manifest/release·hash 참조와 정적·offline 시험.
|
||||
4. 구현 후 실제 상태에 맞춘 S2_00 분석서·IO 문서. 운영 연결이 검증되지 않았다면 그 상태를 명시한다.
|
||||
|
||||
## Scope and Non-Scope
|
||||
|
||||
현재 request의 **6필드와 고정 경로를 유지**한다. 기존 C00–C15의 자료 처리 및 정상/diagnostic 출력 계약은 변경하지 않는다. 새 request receipt 파일, 범용 실행 프레임워크, 임의 backend 변수·템플릿, 독립 잠금 서비스를 생성 코드의 선행 조건으로 두지 않는다. 기존 DEV release 제한이나 다른 Stage 2 결함의 해소는 이 작업의 완료 기준에 포함하지 않는다.
|
||||
|
||||
이 계획의 1차 완료는 **생성·검증·저장 코드와 offline 시험**이다. 같은 YAML이 실제 사건 run에서 네 인자를 어떻게 받는지, 실패 시 다음 task 호출을 어떻게 막는지, 고정 request 경로의 동시 쓰기를 어떻게 막는지는 별도의 운영 통합 완료 조건이다. 이 구분 때문에 운영 정보가 없어도 코드 작성을 중단하지 않으며, offline 결과를 live 실행 성공으로 표시하지 않는다.
|
||||
|
||||
## Known Inputs
|
||||
|
||||
`M/ = Case_02_Comparison_Research/YAML_Prompts/2. Stage_2/`, `R/ = M/Default_Agent/Stage_2_Clean/`, `W/ = localdocs가 결속한 논리 workspace root`.
|
||||
|
||||
- 정본: `M/Stage_2_S2_00_v.2.yml`; 현재 배포본: `R/agent_scripts/Stage_2_S2_00.yml`.
|
||||
- 기존 request 소비 코드는 `stage2_control/s2_00_request.json`을 먼저 읽고, 정확히 6필드·ID·canonical 상대경로를 검증하며, hydration에서 같은 원격 경로의 bytes를 두 번 비교한다.
|
||||
- 기존 runtime의 `canonical_json_bytes`, `_inline_validate_request`, `_inline_relative_path`, `write_binary_verified`가 각각 직렬화·검증·경로 검증·write/read-back 기준이다. 독립 task가 runtime `.py`를 외부 import한다고 가정하지 않는다.
|
||||
- 현재 S2_00 빌더는 정확히 1 task 및 1 code pointer를 요구하고 executor binding은 결과 root 쓰기를 명시한다. 준비 task 추가 시 관련 계약 변경이 필요하다.
|
||||
- backend의 네 인자 주입·성공 조건·workspace 직렬화 구현은 현재 확인되지 않았다. **코드 구현의 선행 차단 조건이 아니라 운영 연결의 미확인 항목**으로 둔다.
|
||||
|
||||
## Material Assumptions
|
||||
|
||||
- 네 값은 호출자가 지정한 문자열이며, 함수는 위치를 추측하거나 사건 폴더를 검색하지 않는다.
|
||||
- `request_id`와 `attempt_id`는 기존 정규식에 맞고, 두 root ref는 NFC canonical workspace 상대경로여야 한다. 문법 검증과 실제 Stage 1 run 선택·접근 권한 검증은 구별한다.
|
||||
- `write_binary_verified`의 성공은 그 호출 직후 read-back한 bytes의 일치를 뜻한다. 다른 실행의 동시 덮어쓰기까지 막는 보장은 아니다.
|
||||
- 독립 task 사이에 메모리 공유가 있다고 가정하지 않는다. 같은 인자를 후행 task에 공급할 수 있음이 확인되면 v1의 전체 expected-bytes 비교를 적용한다. 확인 전에는 그 비교를 운영상 완료했다고 주장하지 않는다.
|
||||
|
||||
## Questions That Could Change the Outcome
|
||||
|
||||
다음 사항은 **운영 연결 단계에서만** 확인한다: 실제 backend가 네 값을 task에 전달하는 형식, 실패한 prepare 이후 ingress 시작을 막는 판정 방식, 동일 workspace의 고정 경로를 보호하는 직렬화·취소 처리. 코드 작성 시 이 형식을 추측한 placeholder를 executable로 넣지 않는다. 운영 기능이 없다면 필요한 backend 변경을 기록하고 생성 코드·offline 검증 결과와 분리한다.
|
||||
|
||||
## Workstreams and Dependencies
|
||||
|
||||
### 1. 기존 계약에 맞는 순수 request 생성 함수
|
||||
|
||||
```python
|
||||
def build_request(
|
||||
request_id: str,
|
||||
attempt_id: str,
|
||||
stage1_run_root_ref: str,
|
||||
stage1_deployment_root_ref: str,
|
||||
) -> bytes:
|
||||
# 설명용 서명: 실제 함수명과 코드는 구현 시 기존 inline 규약에 맞춘다.
|
||||
...
|
||||
```
|
||||
|
||||
1. 네 인자의 타입·값을 검사한다. ID는 `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`를, root ref는 기존 `_inline_relative_path`의 NFC·상대경로·구성요소 규칙을 따른다.
|
||||
2. `schema_version = "stage2_s2_00_execution_request.v1"`, `workflow_id = "S2_00"`을 코드 상수로 넣어 **정확히 여섯 필드**를 구성한다. caller가 추가 키를 request에 넣는 우회 경로를 만들지 않는다.
|
||||
3. 기존 `canonical_json_bytes`와 동일한 규칙으로 UTF-8 bytes를 만든다. 기존 `_inline_validate_request`의 수용 여부와 byte 직렬화 규칙을 대조한다. 별도 schema framework를 만들지 않는다.
|
||||
4. 이 함수는 localdocs를 호출하지 않아 정상·오류 입력의 단위 시험이 가능해야 한다. 함수가 root의 실재나 권한을 확인했다고 표시하지 않는다.
|
||||
|
||||
### 2. localdocs 저장 함수와 선행 task 배치
|
||||
|
||||
- 준비 함수는 위 bytes를 받아 인증된 localdocs 세션에서 **고정 경로** `stage2_control/s2_00_request.json`에 `write_binary_verified` 방식으로 쓴다. write 응답과 같은 경로의 read-back bytes가 일치해야 성공한다.
|
||||
- session 초기화·종료 및 오류 응답은 기존 S2_00 inline MCP 패턴을 따른다. 종료 실패까지 성공으로 표시하지 않는다. 독립 task 코드가 필요한 helper를 포함할 때 기존 구현과 parity를 검사한다.
|
||||
- 새 task를 authoring YAML의 첫 task로 놓고 `task_procedure`를 `IN → prepare → ingress → OUT`으로 지정한다. prepare의 입력 계약에는 네 문자열 인자와 localdocs 세션을 명시한다. **실제 backend가 지원하는 전달 문법을 확인하기 전에는 임의 `run_code` parameter·환경변수·치환 토큰을 작성하지 않는다.**
|
||||
- prepare는 성공 시 최소한의 기계 판독 가능 성공/실패 결과를 내도록 설계한다. 신규 저장 receipt나 별도 버전 schema는 만들지 않는다. 오류·read-back 불일치·session 종료 실패 시 실패를 반환한다.
|
||||
- 기존 ingress는 request의 strict 검증·두 read-pass를 유지한다. 같은 네 인자를 후행에도 공급하는 연결이 확인되면 첫 읽기의 전체 bytes를 재구성한 expected bytes와 비교하는 검사를 추가한다. 이 연결이 없는 offline 단계에서는 준비 함수와 ingress validator의 호환성을 직접 시험하고, 런타임의 동일 요청 소비는 미검증으로 표시한다.
|
||||
|
||||
### 3. 변경된 task 구조에 필요한 자산만 갱신
|
||||
|
||||
| 자산 | 필요한 변경 |
|
||||
|---|---|
|
||||
| `M/Stage_2_S2_00_v.2.yml` | 준비 task를 맨 앞에 배치하고 순서·입력·성공/실패 계약 기록 |
|
||||
| `R/offline_build/build_s2_00_inline_projection.py/.txt` | 정확한 두 task ID·순서·code pointer 검증; `tasks[0]`이 ingress라는 전제 제거 |
|
||||
| `R/agent_scripts/Stage_2_S2_00.yml` 및 runtime `.py/.txt` mirror | 정본으로부터 배포본과 두 task의 code mirror 재생성·parity 확인. 기존 파일 덮어쓰기 전 원본 보존 조건 적용 |
|
||||
| `R/manifest/s2_00_inline_code_receipt.json` | 두 code pointer·hash와 task DAG 결속; 빌드 receipt에만 반영, 새 실행 receipt 파일 없음 |
|
||||
| workflow·executor binding | 준비 단계의 네 인자 계약·고정 request 쓰기 경로와 기존 ingress 결과 경로를 구별. 실제 backend 강제 여부는 별도 표시 |
|
||||
| 관련 schema·module/release/hash | task 구조·참조가 실제 바뀐 파일만 갱신하고 기존 6필드 request schema는 유지. hash 참조 순서를 확인하여 순환 결속을 만들지 않음 |
|
||||
| `M/Stage_2_00_Analysis_v1.md`, `M/Stage_2_00_IO_info.md` | 구현·검증 후 선행 task와 생성 시점, offline/운영 상태의 경계를 반영 |
|
||||
|
||||
기존 `Stage_2_S2_00_outdated_9_09.yml` 보존본과 원본 v1 계획은 변경하지 않는다. 새 task를 추가했으므로 기존 단일 task 빌드 검사를 끄거나 결과만 수동 수정하는 방식은 사용하지 않는다.
|
||||
|
||||
### 4. offline 시험과 운영 연결의 순서
|
||||
|
||||
1. 순수 함수의 정상·오류 입력과 기존 validator 호환성을 시험한다.
|
||||
2. fake localdocs 또는 격리 fixture에서 write/read-back 일치, 쓰기·읽기·session 종료 실패, 고정 경로 외 쓰기 방지를 시험한다. 실패 결과 뒤 ingress를 호출하지 않는 **로컬 호출 흐름**도 확인한다.
|
||||
3. builder `--check`, 두 code mirror/hash, 변경 schema·release 참조, 기존 S2_00 정상/diagnostic fixture 회귀를 검증한다. 같은 입력으로 반복 빌드해 bytes 차이가 없는지 확인한다.
|
||||
4. 실제 backend 인자 전달·실패 차단·workspace 직렬화가 확인되면 YAML의 실행 연결을 결속하고, 동일 요청 소비·경쟁·취소 시험을 수행한다. 이 단계가 끝나기 전에는 실제 S2_00 run 적격성을 주장하지 않는다.
|
||||
|
||||
## Source and Tool Plan
|
||||
|
||||
현재 authoring YAML·배포 코드·request schema·builder·binding을 1차 근거로 사용한다. 구현의 초기 시험은 직접 함수 호출과 격리된 localdocs 대역으로 진행한다. 운영 연결에 필요한 정보만 실제 backend 코드·명세에서 확인한다. 이 문서 작성 자체는 코드를 실행·수정하지 않는다.
|
||||
|
||||
## Validation Plan
|
||||
|
||||
| 검증 | 통과 기준 | 상태 구분 |
|
||||
|---|---|---|
|
||||
| 4인자·6필드·canonical bytes | 정상 입력의 정확한 bytes 및 기존 validator 일치; 타입·ID·경로 오류는 저장 전 거절 | 함수 단위 |
|
||||
| 저장·read-back | 저장 경로 한정, bytes 일치; 오류·응답 불일치·close 실패는 실패 | offline IO |
|
||||
| task 구조·빌드 | prepare가 첫 task, 지정 DAG, 두 code/mirror/hash 일치, 반복 빌드 동일 | 정적·offline |
|
||||
| ingress 회귀 | 기존 strict request·두 read-pass 및 정상 11+E/diagnostic 5파일 계약 유지 | offline 회귀 |
|
||||
| 실제 인자 공급·실패 차단·동시 실행 | 같은 인자의 전체 bytes 대조, prepare 실패 시 ingress 미호출, workspace 실행 경합 없음 | **backend 통합 후에만** |
|
||||
|
||||
테스트용 fixture 통과를 실사건 실행, downstream handoff 완성, 법률 검증으로 해석하지 않는다. DEV release guard를 시험 편의상 제거하지 않는다.
|
||||
|
||||
## Approval Boundaries
|
||||
|
||||
이 요청은 **v2 계획 문서 작성**이다. 구현·배포·원격 실행은 수행하지 않는다. 이후 구현 요청에서는 승인된 범위의 로컬 수정과 offline 시험을 진행하고, 실제 운영 호출·외부 쓰기가 필요한 단계의 권한을 그때 확인한다.
|
||||
|
||||
## Progress
|
||||
|
||||
- [x] v1의 Objective 이하 검토 및 backend 비의존 구현 순서로 개정
|
||||
- [x] 새 task의 첫 배치, 네 인자 함수, 저장/read-back·검증 계획 작성
|
||||
- [ ] 생성·저장 함수와 준비 task 구현
|
||||
- [ ] builder·binding·hash 갱신 및 offline 검증
|
||||
- [ ] backend 연동·동시 실행 검증
|
||||
- [ ] 구현 상태에 맞춘 분석·IO 문서 개정
|
||||
|
||||
## Decision Log
|
||||
|
||||
| 결정 | 근거 | 결과 |
|
||||
|---|---|---|
|
||||
| 생성 코드와 운영 연결을 별도 완료 조건으로 둠 | 함수는 명시적 인자와 localdocs 대역으로 검증 가능 | backend 정보 미확인 상태에서도 구현 진행 |
|
||||
| 두 task 구조와 첫 task 배치 유지 | 사용자가 지정한 Stage 2 작업명세서 순서 | 기존 단일 task 빌드 계약은 실제 구현 시 갱신 |
|
||||
| 기존 validator·serializer·verified write 재사용 | 6필드·bytes·경로 계약이 이미 존재 | 중복 구현과 새 receipt 제거 |
|
||||
| 후행 expected bytes 대조는 인자 결속 확인 후 적용 | 별개 task의 인자 동일성을 가정할 수 없음 | offline 호환성과 실제 동일 요청 소비를 구별 |
|
||||
|
||||
## Evidence Ledger
|
||||
|
||||
| 명제 | 확인된 자료 | 상태 |
|
||||
|---|---|---|
|
||||
| 기존 request는 6필드 고정 계약 | `R/runtime/s2_00_ingress.py`의 `_inline_validate_request`; `R/schemas/ingress.schema.json` | 기존 구현 확인 |
|
||||
| 기존 직렬화·저장/read-back helper가 있음 | 같은 runtime의 `canonical_json_bytes`, `_InlineLocaldocs.write_binary_verified` | 기존 구현 확인 |
|
||||
| 단일 task 빌더·고정 output 쓰기 root 변경 필요 | `R/offline_build/build_s2_00_inline_projection.py`, `R/deployment/stage2_code_executor_binding.yml` | 기존 제약 확인 |
|
||||
| 실제 backend 인자 공급·성공 게이트·직렬화 | 현재 v1 및 관련 자료에서 확인되지 않음 | **UNVERIFIED; 생성 함수 구현을 막지 않음** |
|
||||
|
||||
## Risks and Failure Modes
|
||||
|
||||
- 두 task를 YAML에 나열하기만 해서는 외부 인자 공급이나 실패 시 후행 차단이 구현되지 않는다. backend 연결 확인 전에는 offline artifact로 표시한다.
|
||||
- write/read-back은 그 순간의 bytes를 확인하지만 고정 경로의 동시 덮어쓰기를 막지 못한다. 실제 운영에는 workspace 단위 통제가 별도로 필요하다.
|
||||
- 정본·배포본·mirror·receipt·binding의 hash를 따로 갱신하면 참조 불일치가 생긴다. 변경된 참조만 함께 재결속하고 반복 빌드로 확인한다.
|
||||
- 현 release의 `DEV_FIXTURE_RELEASE / DRAFT_NOT_EXECUTABLE` 상태는 request 생성 기능의 구현만으로 바뀌지 않는다.
|
||||
|
||||
## Results and Residual Uncertainty
|
||||
|
||||
v2는 backend 기능 확인을 **생성 코드 구현의 선행 조건에서 운영 연결의 완료 조건으로 이동**시켰다. 실행 가능한 함수와 offline 저장 시험을 먼저 만들고, Stage 2 작업명세서에서 이를 첫 task로 배치하는 변경을 계획한다. 실제 인자 주입·후행 차단·동시 실행 통제의 구현 여부는 아직 확인되지 않았고, 이 계획 작성으로 request 파일이나 새 YAML이 생성된 것은 아니다.
|
||||
Reference in New Issue
Block a user