Portal Control Plane Requirements

Portal Control Plane 요구사항

한 줄 규칙

Portal은 FractalOps truth plane 위에 놓인 주요 사람-워크플로 표면이다. 범용 스택 거버넌스 대시보드가 아니다.

토폴로지(service_profiles.portal)상 Portal은 portal.yamon.io(Pomerium 보호 호스트, strict_public: true)로 노출되며, 미리보기/테스트 환경 (portal-preview-{a,b,c}.yamon.io, portal-test.yamon.io)도 동일한 계약을 갖는다. 인증 없이 접근 가능한 진입 prefix는 public_auth_entry_prefixes로 한정된다 (/login, /public, /_astro, /favicon, /v1/portal/session/*, /v1/events/github, /v1/events/webhook/).

Portal이 해야 하는 일

• 현재 워크플로 경로를 보여준다: onboarding -> work -> proposal -> proof -> recovery.
• canonical truth plane과 read model을 읽는다.
• 승인된 backend 계약으로 작업을 큐잉/트리거한다.
• AgentSquad와 runtime health에 대한 operator 가시성을 노출한다.
• launch/auth/recovery continuity를 사용자가 막다른 길에 닿기 전에 보여준다.

flowchart LR
  subgraph Portal["Portal (portal.yamon.io)"]
    work["Work & Launch"]
    prop["Proposal & Recovery"]
    proof["Proof & Lineage"]
    ops["Operator & AgentSquad"]
  end
  work --> API["FractalOps API<br/>(validate / queue / record)"]
  API --> T["Temporal (heavy exec)"]
  proof --> S["Semantics / DataHub"]
  proof --> CH["ClickHouse warehouse"]
  proof --> EV["Chronicle evidence"]
  ops --> LE["portal_live_events"]
  ops --> HP["harness-projection"]

강하게 소유 vs Endpoint 표면

Portal은 이 둘을 구분해야 한다.

강하게 소유하는 실행 substrate: portal, api, worker, execution-runtime, Temporal, CNPG-backed Supabase Core / Storage / Realtime, Daytona, PlaywrightGrid.

일반 통합 endpoint: Nexus, Penpot, Dokploy, Headlamp, 대부분의 connector target.

Portal은 endpoint 시스템에 대해 launch/health affordance를 보여줄 수 있으나, product-owned 하위 plane이 아니라 URL/auth/health 계약으로 다뤄야 한다.

필수 표면 패밀리

1. Work and Launch

• pre-auth preview는 다음을 보여야 한다: project spine, session continuity, validation, next actions.
• login continuation은 route intent를 보존해야 한다.
• launch guidance는 browser-first 기대를 명시해야 한다.

2. Proposal and Recovery

• proposal은 유일한 non-read mutation gate로 남는다.
• 막힌 route는 실패를 숨기지 말고 recovery로 downshift한다.
• auth-only blocker를 product 로직 실패로 오분류하지 않는다.

3. Proof and Lineage

• proof 경로는 Semantics/FractalOps graph -> ClickHouse warehouse -> Chronicle evidence로 유지된다.
• DataHub는 catalog search/lineage discovery/impact navigation을 위한 project RDF steward report를 노출하고, ClickHouse는 같은 lifecycle을 queryable warehouse event/fact로 노출한다. DataHub 단독은 proof authority가 아니다.
• Portal은 proof closure와 lineage join을 보여주고, 대체 proof 출처를 만들지 않는다.

4. Operator and AgentSquad

• operator live truth는 portal_live_events + harness-projection에서만 온다.
• operator와 minimap은 같은 projection snapshot을 읽는다.
• 무거운 historical summary endpoint는 debug 표면이지 live truth가 아니다.
• 선택된 session detail은 compact하게 유지한다: continuity summary, source lineage, launch contract status, first tool family, practical next step.

실행 규칙

• API는 validate/queue/record만 한다.
• Temporal이 무거운 실행을 수행한다.
• Portal은 proposal-bound side effect를 동기로 수행하지 않는다.
• secret/token은 SSOT 기반 secret 계약에서 온다.
• public URL, executor URL, local/internal URL은 분리 유지한다.

Anti-Requirements (해서는 안 되는 것)

• 기본값으로 per-stack lifecycle 콘솔이 되는 것.
• client에서 여러 live truth를 합치는 것.
• stack-local 제어 명사를 제품 어휘로 의존하는 것.
• 모든 인접 도구를 FractalOps가 lifecycle을 소유한 것처럼 다루는 것.

수용 신호 (Acceptance Signals)

• 사용자가 FractalOps가 직접 소유하는 것과 단지 통합하는 것을 이해할 수 있다.
• live operator와 minimap이 모두 harness-projection을 따른다.
• launch/auth continuity가 작업 시작 전에 보인다.
• proposal과 proof가 canonical rail 위에 머문다.