Merge pull request #34 from decipherhub/33-docs-decide-pd-1pd-7-architecture-decisions

0xMuang · web-flow · commit 10c38e20e378 · 2026-07-14T14:52:01.000+09:00
Record Phase 1 architecture baseline
diff --git a/DECISIONS.md b/DECISIONS.md
@@ -254,3 +254,48 @@ Router 밖 경로는 production deployment에서 다음 중 하나로 처리해
 - `docs/security.md`
 - `ARCHITECTURE.md`
 - `docs/architecture/execution-routing.md`
+
+## D007 — PD-1~PD-7 Phase 1 architecture baseline을 확정한다
+
+Date: 2026-07-14
+
+### Context
+
+Phase 1 구현 전에 Manifest schema, Recipe evaluation, post-trade state,
+identity claim, enforcement action, governance와 lifecycle record 보존 방식에
+대한 개발팀 합의가 필요했다.
+
+이 결정들은 BUIDL-like demo나 RFQ/API 구현보다 상위의 아키텍처 baseline이다.
+
+### Decision
+
+PD-1~PD-7을 Phase 1 architecture baseline으로 확정한다.
+
+- PD-1: Manifest는 explicit core + registry-backed `RecipeBinding` 구조를 사용한다.
+- PD-2: Router/Engine은 Manifest-level multi-Recipe binding 모델을 사용한다.
+- PD-3: token transfer 기준 acquisition timestamp와 router execution context를 분리하고, post-trade commit은 idempotent하게 처리한다.
+- PD-4: investor qualification은 ERC-3643/ONCHAINID claim pipeline을 기본 인터페이스로 사용하고, Securitize/TA는 adapter boundary로 연동한다.
+- PD-5: `BLOCK`, `FLAG_ONLY`, `OPERATOR_REVIEW` 중심의 enforcement action 모델과 constrained override를 사용한다.
+- PD-6: governance authority는 외부 Safe-style multisig를 사용하고, compliance relaxation은 timelock을 요구한다.
+- PD-7: Manifest lifecycle은 semantic versioning, append-only history, central pause state와 hash-anchored record preservation을 사용한다.
+
+### Alternatives Considered
+
+- PD별 ADR을 7개로 분리: 현재 결정들이 하나의 Phase 1 구조 freeze를 구성하므로
+  단일 baseline ADR로 묶는 편이 리뷰와 추적에 더 적합해 보류한다.
+- 현행 `issuanceRecipeId + fundRecipeId` 구조 유지: BUIDL-like demo에는 충분하지만
+  future policy 조합과 path option을 표현하기 어려워 transitional 구조로만 남긴다.
+- Corner Store 전용 identity model 신설: ERC-3643/T-REX와 ONCHAINID 호환성을
+  해치고 TA/KYC provider 연동성이 떨어져 제외한다.
+
+### Consequences
+
+- PD-1~PD-7은 더 이상 열린 구조 질문이 아니며, 후속 작업은 구현 명세와 migration issue로 진행한다.
+- 현재 코드의 transitional 구조는 별도 implementation branch에서 `RecipeBinding[]`, compiled plan, lifecycle registry 등으로 이전해야 한다.
+- 실제 Securitize/TA 연동은 공식/current interface 확인 후 별도 refinement issue에서 처리한다.
+
+### Related Files
+
+- `docs/decisions/ADR-007-pd-architecture-decisions.md`
+- `docs/decisions/decision-register.md`
+- `docs/architecture/phase1-structural-decisions-proposed.md`
diff --git a/docs/architecture/phase1-structural-decisions-proposed.md b/docs/architecture/phase1-structural-decisions-proposed.md
@@ -1,12 +1,12 @@
-# Phase 1 구조 결정 — 개발팀 리뷰 (PROPOSED)
+# Phase 1 구조 결정 — 개발팀 리뷰 (ACCEPTED)
 
 ## 읽기 전에 — 이게 뭐고, 당신들이 뭘 하면 되나
 
 - **받는 사람 = 개발팀.** 아래는 컴포넌트 스펙·구현에 들어가기 *전에* 합의해야 할 **7개 "골조(아키텍처) 결정"**입니다.
 - **왜 지금 정해야 하나:** 이건 *나중에 바꾸면 라우터·스키마·거래 흐름을 통째로 다시 짜야 하는(retrofit)* 골조입니다. 반대로 *구체 부품·임계치 값*은 나중에 가산하면 됩니다(OCP). **이 문서의 목적 = 그 "지금 박을 골조"와 "나중에 가산할 구체물"을 가르는 것.**
 - **각 결정의 틀:** ① *어떤 문제인가* → ② *왜 골조인가(naive하게 짜면 나중에 뭐가 깨지나)* → ③ *제안* → ④ *trade-off(대안/안 하면)* → ⑤ *당신들이 정할 것.*
 - **증권법 세부는 몰라도 됩니다** — 구조가 *왜 이렇게 생겼는지* 이해할 만큼만 풀어 썼습니다.
-- **상태:** PD-1~6은 리걸/PM이 *방향*은 승인. 남은 건 **개발팀의 *구현 합의*(인터페이스·필드셋·파라미터)**. PD-7은 신규.
+- **상태:** PD-1~7은 ADR-007로 개발팀 구현 방향이 확정되었습니다. 이 문서는 배경 설명이고, 최종 결정문은 `docs/decisions/ADR-007-pd-architecture-decisions.md`입니다.
 
 ---
 
@@ -123,14 +123,14 @@ mapping(bytes32 => IRecipeModule) public recipeModule;  // ← 확장 지점
 | ADR-004 | Element Pool Freeze v1 | ✅ Accepted |
 | ADR-005 | §4(a)(7) 주 재판매경로·A-03 active | ✅ (general solicitation 판정만 변호사 잔여) |
 | ADR-006 | 부품 asset-agnostic | ✅ Accepted |
-| **PD-1~7** | 위 7개 골조 | 🟢 방향비준 · **개발팀 구현 합의 대기** |
+| **PD-1~7** | 위 7개 골조 | ✅ Accepted by ADR-007 |
 
 ### 최소 게이트
-**PD-1·2·3·5·7**이 컴포넌트 스펙·생애주기를 여는 *최소 토대*. PD-4·6은 병렬 합의 가능.
+**PD-1~7**은 ADR-007로 accepted. 다음 단계는 컴포넌트별 구현 명세와 migration issue 작성.
 
 ### 리뷰 요청
 - 각 PD의 *제안에 동의/수정* + ④ trade-off가 납득되나 + ⑤ 구현 디테일(필드셋·인터페이스·파라미터) 확정.
-- 합의분 → **ADR-007(Q8)·008(Q9)·009(Q10/Q10-a)·010(Q12)·011(Q13)·012(Q11)·013(Q14)** 승격(`docs/decisions/`).
+- 합의분 → **ADR-007**로 승격 완료(`docs/decisions/ADR-007-pd-architecture-decisions.md`).
 - 전체 결정 현황: [`docs/decisions/decision-register.md`](../decisions/decision-register.md).
 
 > 법률 의존 항목(reliance 충분성·audit trail·SAR·general solicitation 등)은 *별도 변호사 트랙*이며 이 문서 범위 밖. 구조 freeze는 위 PD(개발팀 합의) + *구조에 걸리는 법률 회신*만 선행.
diff --git a/docs/decisions/ADR-007-pd-architecture-decisions.md b/docs/decisions/ADR-007-pd-architecture-decisions.md
@@ -0,0 +1,241 @@
+# ADR-007: Accept PD-1~PD-7 architecture decisions
+
+Date: 2026-07-14
+
+## Status
+
+Accepted
+
+## Context
+
+Phase 1 requires implementation-level agreement on the structural decisions that shape Manifest schema, Recipe evaluation, post-trade state, identity claims, enforcement actions, governance, and lifecycle controls.
+
+These decisions are architecture-level foundations. They should be recorded separately from BUIDL-like demo work and RFQ/API implementation work.
+
+## Decision
+
+Corner Store accepts PD-1~PD-7 as the Phase 1 architecture baseline.
+
+### PD-1: Manifest schema and extensibility
+
+Use an explicit `ManifestCore` for stable, human-readable asset state, and move policy-specific requirements into registry-backed `RecipeBinding` entries.
+
+- `ManifestCore` keeps only common core fields.
+- New regulatory policies should not require adding fixed fields to `ManifestCore`.
+- Policy requirements are attached through `RecipeBinding[]`.
+- Recipe identifiers should move toward canonical `bytes32 recipeKey` values managed by a registry.
+- Raw recipe keys should not be exposed directly to normal users/operators.
+- Onboarding should use curated profiles, validation, and simulation.
+- Trade-time execution should use a precompiled compliance plan, not dynamic alias/key resolution.
+
+Open implementation details:
+
+- canonical recipe key naming convention
+- `factsPacked` bit layout ownership
+- gas-bound caps such as max recipes and max elements per evaluation
+- exact compiled plan struct shape
+
+### PD-2: Multi-Recipe evaluation model
+
+Use a Manifest-level multi-Recipe binding model.
+
+Recipes define reusable compliance checks. A Manifest decides how each Recipe is applied through `RecipeBinding`.
+
+`RecipeBinding` must support:
+
+- `REQUIRED_BLOCKING`: mandatory blocking checks. Multiple required recipes are evaluated as AND.
+- `PATH_OPTION`: alternative compliance paths. Recipes with the same `pathGroupId` form an OR group. Each path group passes if at least one recipe in that group passes. Multiple path groups are combined as AND across groups.
+- `FLAG_ONLY`: non-blocking surveillance, reporting, or warning checks. Failure does not block execution but must be logged or surfaced.
+
+Failure reporting must use deterministic `reasonCode` severity, not array order. Binding priority may be used only as a tie-breaker if needed.
+
+The current `issuanceRecipeId + fundRecipeId` layout is transitional. The target model is `RecipeBinding[]`.
+
+### PD-3: Post-trade state model and commit semantics
+
+Use a dual-path state model with post-trade commit.
+
+- Acquisition timestamp is anchored to successful token transfer.
+- Router execution timestamp is recorded separately as execution context.
+- Reliance logs use event-first recording with minimal on-chain commitment hashes.
+- Post-trade commits are idempotent by `executionId`.
+- Replaying the same commit with the same `commitHash` is a no-op.
+- Reusing the same `executionId` with different commit data must revert.
+
+### PD-4: Investor qualification claims and TA integration
+
+Use the ERC-3643/T-REX identity model as the primary interface for investor qualification.
+
+Corner Store should not invent a separate AI/QP identity model. AI, QP, KYC, AML, sanctions, and similar investor facts should be represented as required claim topics checked through the ERC-3643-style identity pipeline:
+
+- Identity Registry resolves wallet to ONCHAINID.
+- Claim Topics Registry defines which claim topics are required for a token/profile.
+- Trusted Issuers Registry defines which issuers may issue those claims.
+- ONCHAINID/IERC735 claims provide topic, issuer, signature, data, and URI.
+
+Claim topic direction:
+
+- AI and QP are explicit claim topics in the project-level claim topic registry.
+- Use ERC-3643-compatible `uint256` claim topic identifiers.
+- Do not assume AI/QP topic numbers are globally standardized.
+- Initial project topics are `ACCREDITED_INVESTOR = 1001` and `QUALIFIED_PURCHASER = 1002`.
+
+Expiry/freshness direction:
+
+- Claim data should include `issuedAt` and `expiresAt` where the issuer provides structured data.
+- Elements may also apply max-age/freshness rules by claim type.
+- If an external issuer does not expose structured expiry data, the adapter must define how freshness is derived or mark the integration as unsupported for production.
+
+Fixture and TA integration direction:
+
+- Tests should use a generic ERC-3643-style TrustedIssuer fixture.
+- BUIDL-like demos may label that fixture as a Securitize-like Transfer Agent profile for explanation only.
+- The fixture must not imply real Securitize compatibility unless an actual integration adapter is implemented and verified.
+- Securitize/DS Protocol integration should be supported through an adapter boundary, not by replacing the ERC-3643 identity model.
+- Actual Securitize/TA integration is deferred to a follow-up refinement issue because it requires official/current details for issuer addresses, claim/topic mapping, revocation, expiry, and production authorization.
+
+### PD-5: Enforcement actions and result handling
+
+Use an explicit enforcement action model with a small closed set of core actions for v1.
+
+V1 core actions:
+
+- `BLOCK`: failed result blocks execution.
+- `FLAG_ONLY`: failed result does not block execution. The finding must be surfaced through flags and events.
+- `OPERATOR_REVIEW`: v1 treats this as blocking. Pending execution or delayed approval is out of scope for v1.
+
+Default action and override:
+
+- Elements define default enforcement actions.
+- `RecipeBinding` may override enforcement only through constrained override modes.
+- Override changes how an Element result is applied; it does not modify the Element logic itself.
+- Accepted override modes are `USE_ELEMENT_DEFAULT`, `ESCALATE_TO_BLOCK`, `ESCALATE_TO_OPERATOR_REVIEW`, and `FORCE_FLAG_ONLY`.
+- Escalation is allowed by default.
+- Downgrading a blocking result to `FLAG_ONLY` is governance-restricted and must not be available through normal onboarding.
+
+`evaluate()` should return both blocking status and non-blocking findings:
+
+```solidity
+struct EvaluationResult {
+    bool allowed;
+    uint16 blockReason;
+    uint256 flagsBitmap;
+    bytes32 evaluationHash;
+}
+```
+
+Enforcement overrides must be resolved into a bounded compiled plan at registration/update time. Trade-time evaluation must not perform dynamic recipe compilation or unbounded override resolution.
+
+Core actions are intentionally not open-ended because each action has execution semantics the Router must understand. Future extensions should first use `reasonCode`, `actionDetail`, or `flagsBitmap`. New execution semantics require a versioned extension and explicit Router support.
+
+### PD-6: Governance, timelock, and emergency authority
+
+Use a role-separated governance model with multisig, timelock, and emergency guardrails.
+
+Signer configuration:
+
+- Governance authority is assigned to an external Safe-style multisig.
+- Corner Store contracts should not implement `n-of-m` signer logic directly.
+- Signer set and threshold changes are handled by the multisig itself without Corner Store contract upgrades.
+- V1 operational target is `2-of-3` for practicality.
+- Production regulated deployments should consider `3-of-5` or stronger separation across protocol, compliance, legal, operations, and external/audit roles.
+
+Governance principle:
+
+- Tightening or stopping risk may be immediate.
+- Relaxing compliance, reopening execution, or expanding trust must require timelock.
+
+Emergency pause reason codes:
+
+- `SECURITY_INCIDENT`
+- `COMPLIANCE_INCIDENT`
+- `IDENTITY_OR_CLAIM_FAILURE`
+- `LEGAL_REQUEST`
+- `MARKET_INTEGRITY`
+- `OPERATOR_ERROR`
+- `OTHER`
+
+Immediate actions are limited to tightening or stopping risk:
+
+- global pause
+- asset pause
+- venue pause
+- issuer disable
+- enforcement escalation
+
+The following require multisig plus timelock:
+
+- unpause
+- compliance relaxation
+- trusted issuer addition
+- required claim removal
+- recipe removal
+- `BLOCK` to `FLAG_ONLY` downgrade
+- router / engine / registry replacement
+- manifest major version changes
+
+All governance actions must emit append-only events with actor, old value, new value, reason code or reason hash, and effective time.
+
+### PD-7: Lifecycle versioning, pause, and record preservation
+
+Use a versioned lifecycle and record-preservation model.
+
+Manifest versioning:
+
+- Manifest version increments when compliance semantics change.
+- Non-semantic metadata changes are tracked separately.
+- Compliance semantic changes include `RecipeBinding` changes, required claim topic changes, TrustedIssuer changes, enforcement action changes, supported venue/engine changes, and manifest major profile changes.
+
+Lifecycle history events should use structured reason codes plus optional reason hashes.
+
+Recommended lifecycle reason codes:
+
+- `REGULATORY_UPDATE`
+- `LEGAL_REQUEST`
+- `ISSUER_UPDATE`
+- `CLAIM_TOPIC_UPDATE`
+- `RECIPE_UPDATE`
+- `VENUE_UPDATE`
+- `SECURITY_INCIDENT`
+- `COMPLIANCE_INCIDENT`
+- `IDENTITY_OR_CLAIM_FAILURE`
+- `OPERATOR_ERROR`
+- `MIGRATION`
+- `OTHER`
+
+All Corner Store DEX executions must enter through an approved Router. The Router is the primary enforcement point for global, asset, and venue pause checks.
+
+Pause state should be stored in a central `PauseController` or lifecycle registry so future routers/adapters share the same source of truth.
+
+Intended split:
+
+- Router: execution entrypoint and pause enforcement point.
+- PauseController / lifecycle registry: pause state and lifecycle history source of truth.
+
+On-chain record preservation is limited to critical state, hashes, and append-only events:
+
+- current manifest version
+- current manifest hash
+- old/new manifest hash events
+- reasonCode
+- reasonHash
+- actor
+- effective time
+- execution / reliance commit hash
+
+Full manifest documents, recipe details, legal/compliance memos, claim evidence, operator tickets, and indexer-exported transaction reports are preserved off-chain and anchored by hashes.
+
+## Consequences
+
+- PD-1~PD-7 are no longer open structural questions for Phase 1; remaining work is implementation specification and follow-up issues.
+- Current code that still uses transitional structures, such as `issuanceRecipeId + fundRecipeId`, should be migrated through separate implementation work.
+- Securitize/TA integration remains an adapter/refinement issue, not a hard dependency of the Phase 1 architecture baseline.
+
+## References
+
+- [Phase 1 structural decisions](../architecture/phase1-structural-decisions-proposed.md)
+- [Decision register](./decision-register.md)
+- [ERC-3643 Claim Topics Registry](https://docs.erc3643.org/erc-3643/smart-contracts-library/onchain-identities/claim-topics-registry)
+- [ERC-3643 Trusted Issuers Registry](https://docs.erc3643.org/erc-3643/smart-contracts-library/onchain-identities/trusted-issuers-registry)
+- [ERC-3643 ONCHAINID Interface](https://docs.erc3643.org/erc-3643/smart-contracts-library/onchain-identities/onchainid-interface)
+- [Securitize DS Protocol Compliance Service](https://medium.com/securitize/ds-protocol-the-compliance-service-b6fe472d625d)
diff --git a/docs/decisions/decision-register.md b/docs/decisions/decision-register.md
