Skip to content
FractalOps

FractalOps Constitution

FractalOps 헌법 (Constitution)

Section titled “FractalOps 헌법 (Constitution)”

FractalOps는 조직의 메타 컨트롤 플레인(organization meta-control plane)입니다.

이 문서는 L0, 즉 헌법(constitutional law) 입니다. 그 아래에 있는 모든 것은 L1 contract(계약) 또는 L2 execution(실행)일 뿐입니다.

1. 제품 법 (Product Law)

Section titled “1. 제품 법 (Product Law)”

FractalOps는 하나의 안정적인 운영 문법(operating grammar)을 유지하기 위해 존재합니다.

onboarding -> work -> proposal -> proof -> reflective improvement

(온보딩 -> 작업 -> 제안 -> 증명 -> 반성적 개선)

구체적인 프로젝트와 스택(예: new.yamon.io)은 이 루프를 강제하기 위한 포싱 함수(forcing function) 일 뿐, 제품 자체를 재정의하지 않습니다. 한 스택 홈페이지를 흉내 내거나 하나의 IAM 동기화 잡(job)으로 환원되는 순간, FractalOps는 제품이 아니라 잡무가 됩니다.

flowchart LR
  onboarding["onboarding\n온보딩"] --> work["work\n작업"]
  work --> proposal["proposal\nProposal Plane"]
  proposal --> proof["proof\n3면 증거 폐쇄"]
  proof --> improve["reflective improvement\nAgentSquad"]
  improve -.->|같은 Portal로 되돌림| work

2. Ownership Law (소유 법)

Section titled “2. Ownership Law (소유 법)”

FractalOps owns:

  • Portal workflow and command-center UX
  • Proposal Plane lifecycle and approval boundary
  • ontology-aligned read models and graph projection contracts
  • access topology and recovery surfaces
  • Chronicle evidence indexing and proof lookup
  • AgentSquad scheduling and Agent Control Surface

FractalOps does not allow secondary tools to become competing truth owners.

풀어 쓰면: FractalOps는 제어 계약(control contract) 의 소유자입니다. Portal 워크플로, Proposal Plane 생애주기, 온톨로지 정렬 읽기 모델, 접근 토폴로지와 복구 경로, Chronicle 증거 색인, AgentSquad 스케줄링/Agent Control Surface를 소유합니다. 인접 도구가 이 진실들의 경쟁 소유자가 되는 것을 허용하지 않습니다.

3. Non-Ownership Law (비소유 법)

Section titled “3. Non-Ownership Law (비소유 법)”

The following tools remain consumers, execution planes, or adapters:

  • Daytona
  • Penpot
  • Nexus
  • PlaywrightGrid
  • DataHub
  • ClickHouse warehouse
  • PostHog
  • OpenTelemetry

Non-ownership means these tools may expose or execute truth, but may not redefine the authoritative contract they consume.

풀어 쓰면: 위 도구들은 진실을 노출하거나 실행할 수는 있어도, 자신이 소비하는 권위 있는 계약을 재정의할 수 없습니다. 예를 들어 DataHub는 카탈로그/계보를 검색 가능하게 만들지만 변경 게이트나 증명 권위를 가질 수 없습니다.

4. 변경 법 (Mutation Law)

Section titled “4. 변경 법 (Mutation Law)”
  • Every non-read AI path must bind to a proposal.
  • Proposal Plane is the only legal mutation gate.
  • API routes may queue, validate, or reject. They may not perform proposal-bound side effects directly.
  • Temporal owns execution for proposal-bound work.
  • Temporal owns execution for proposal-bound work.

이것이 FractalOps에서 가장 자주 어겨지는 법입니다. 풀어 쓰면:

  1. 모든 비-읽기(non-read) AI 경로는 proposal에 결속(bind) 되어야 합니다.
  2. Proposal Plane이 유일한 합법적 변경 게이트입니다.
  3. API route는 큐잉(queue) / 검증(validate) / 거부(reject) 만 합니다. proposal에 결속된 부수효과(side effect)를 route에서 직접 실행하면 안 됩니다.
  4. proposal에 결속된 작업의 실행은 Temporal이 소유합니다.
sequenceDiagram
  autonumber
  participant U as Portal / API 입력
  participant R as API route<br/>(presentation)
  participant Q as 큐 / 워크플로 enqueue
  participant T as Temporal<br/>(workflow / activity)
  participant X as connector / executor
  participant E as 진실 평면<br/>(DataHub · ClickHouse · Chronicle)

  U->>R: 변경 요청 (write)
  R->>R: request 계약 검증 (Pydantic RequestIn)
  Note over R: proposal_id 누락 시<br/>validation 에러로 거부
  R->>Q: 작업 enqueue (직접 부수효과 금지)
  Q->>T: Temporal이 실행 소유
  T->>X: connector / executor 호출
  X-->>T: 결과
  T->>E: 사실 기록 / 증거 투영

코드 근거: ChangeProposal 상태 머신은 backend/src/fractalops/domain/semantics/features/proposals/models.py에 정의되어 있고, 허용된 전이만 통과합니다.

backend/src/fractalops/domain/semantics/features/proposals/models.py
CHANGE_PROPOSAL_STATUS_VALUES = (
    "draft", "proposed", "under_review", "approved", "rejected",
    "published", "applied", "verified", "rolled_back", "archived",
)


CHANGE_PROPOSAL_ALLOWED_TRANSITIONS: dict[str, set[str]] = {
    "draft": {"proposed", "archived"},
    "proposed": {"under_review", "approved", "rejected", "archived"},
    "under_review": {"approved", "rejected", "archived"},
    "approved": {"published", "rejected", "archived"},
    "rejected": {"archived"},
    "published": {"applied", "rolled_back", "archived"},
    "applied": {"verified", "rolled_back", "archived"},
    "verified": {"archived"},
    "rolled_back": {"archived"},
    "archived": set(),
}
stateDiagram-v2
  [*] --> draft
  draft --> proposed
  proposed --> under_review
  proposed --> approved
  proposed --> rejected
  under_review --> approved
  under_review --> rejected
  approved --> published
  approved --> rejected
  published --> applied
  published --> rolled_back
  applied --> verified
  applied --> rolled_back
  verified --> archived
  rejected --> archived
  rolled_back --> archived
  draft --> archived
  archived --> [*]

validate_change_proposal_transition(current_status=..., next_status=...)는 위 표에 없는 전이를 invalid_change_proposal_transition으로 거부합니다.

5. 증거 폐쇄 법 (Proof Closure Law)

Section titled “5. 증거 폐쇄 법 (Proof Closure Law)”

Proof is closed only when all three planes remain queryable:

  1. FractalOps Semantics graph/lineage identity
  2. ClickHouse warehouse fact or warehouse proof
  3. Chronicle evidence long-term provenance

No single plane may claim proof completion alone.

증명은 세 평면이 모두 조회 가능할 때만 폐쇄됩니다. 어느 한 평면도 단독으로 증명 완료를 선언할 수 없습니다. 이 3면 폐쇄는 단순한 문서 규약이 아니라 계약 스키마로 강제됩니다.

schemas/proof/schema.json
{
  "title": "FractalOps Proof Contract",
  "type": "object",
  "required": ["proposal_key", "datahub", "clickhouse_warehouse", "chronicle_evidence"],
  "properties": {
    "proposal_key": { "type": "string", "minLength": 1 },
    "datahub": { "type": "boolean" },
    "clickhouse_warehouse": { "type": "boolean" },
    "chronicle_evidence": { "type": "boolean" }
  }
}
flowchart LR
  pk["proposal_key\n(빈 문자열 불가)"] --> closure{증거 폐쇄}
  dh["DataHub\n(catalog/lineage)"] --> closure
  ch["ClickHouse warehouse\n(fact/proof)"] --> closure
  cr["Chronicle evidence\n(long-term provenance)"] --> closure
  closure -->|3면 모두 true| done["proof closed ✅"]
  closure -->|하나라도 false| open["proof open ❌"]

Proof schema는 Contract repository가 소유하고 Assembly는 pinned artifact로 검증합니다.

6. 진실 평면 법 (Truth-Plane Law)

Section titled “6. 진실 평면 법 (Truth-Plane Law)”
  • Git is the normative desired-state source.
  • OpenBao is the secret source of truth.
  • Semantics is the graph and lineage truth plane.
  • DataHub is the catalog and lineage accumulation plane fed by project RDF steward agents and may not own identity, SCIM/JIT, mutation, or proof authority.
  • ClickHouse warehouse stores the same project RDF steward lifecycle as queryable events/facts and remains the warehouse fact and warehouse proof plane.
  • PostHog and OpenTelemetry are distributed event sources. They must emit or be mapped to global ontology ids before their project-local events accumulate in ClickHouse.
  • Chronicle evidence is the long-term proof plane.
  • Portal is the primary human workflow surface.
  • AgentSquad is the reflective loop that improves the same product through compact Agent Control Surface.

풀어 쓰면, 각 진실에는 단 하나의 소유자가 있습니다. Git=원하는 코드 상태, OpenBao=비밀, Semantics=그래프/계보 의미, DataHub=검색 가능한 카탈로그, ClickHouse=웨어하우스 사실/증명, Chronicle=장기 증거. 이 경계를 흐리면 곧바로 헌법 위반입니다.

7. 바운디드 컨텍스트 법 (Bounded-Context Law)

Section titled “7. 바운디드 컨텍스트 법 (Bounded-Context Law)”

The canonical bounded contexts are:

  • Constitution
  • Proposal Plane
  • Identity
  • Access
  • Semantics
  • Evidence
  • Portal Experience
  • Orchestration
  • Policy
  • Infra Topology

Domain meaning must stay inside the correct context. Interface polish must not redefine domain contracts.

풀어 쓰면: 도메인 의미는 올바른 컨텍스트 안에 머물러야 합니다. 화면(presentation) 다듬기가 도메인 계약을 재정의해서는 안 됩니다. 코드는 backend/src/fractalops/{domain,application,adapters}/<context>/features/<outcome>/와 backend/src/fractalops/interfaces/<transport>/<context>/features/<outcome>/ 계층을 따르고 tach.toml이 경계를 강제합니다(Tach DDD / Feature Slice 표준 참고).

8. 네이밍 법 (Naming Law)

Section titled “8. 네이밍 법 (Naming Law)”

The canonical public vocabulary is:

  • Portal
  • Proposal Plane
  • Semantics
  • DataHub
  • ClickHouse warehouse
  • Chronicle evidence
  • AgentSquad
  • Agent Control Surface
  • access_recovery
  • lineage_join_gap
  • project spine
  • daytona entry

Generic DW wording is illegal in user-facing and agent-facing product grammar.

일반명사 DW(data warehouse) 같은 표현은 사용자/에이전트 대면 문법에서 금지입니다. 정규 명사 전체는 Execution Naming Glossary를 따르세요.

9. 예외 법 (Exception Law)

Section titled “9. 예외 법 (Exception Law)”

Operational exceptions are allowed only as time-bounded debt.

Every exception must declare:

  • id
  • reason
  • risk
  • owner
  • introduced_by
  • expires_at
  • removal_condition

Expired exceptions are constitutional failures.

운영 예외는 기한이 정해진 부채(time-bounded debt) 로만 허용됩니다. 위 7개 필드를 모두 선언해야 하며, 만료된 예외는 헌법 실패입니다. 예외 레지스트리는 make governance-check로 검증됩니다.

10. 머지 법정 법 (Merge Court Law)

Section titled “10. 머지 법정 법 (Merge Court Law)”

No change is merge-complete without:

  • proposal_key
  • evidence_key
  • affected_truth_planes
  • approval_class
  • rollback_class
  • adr_operating_mode
  • constitutional_pass

PRs are verdict carriers, not narrative status reports.

adr_operating_mode keeps ADR work proportional:

  • proposal-only: default path. The PR metadata and evidence are the decision record.
  • adr-required: cross-context, irreversible, stack, authorization, secret, data-contract, cost, or SLO decision.
  • adr-update: existing ADR, constitution, or operating rule changes.
  • adr-not-applicable: generated, docs-only, or no architecture decision.

PRs must not block on standalone ADR writing unless the mode is adr-required or adr-update.

PR은 서사적 상태 보고서가 아니라 판결의 운반자(verdict carrier) 입니다. 위 7개 메타데이터가 없으면 머지가 완료되지 않습니다. ADR은 기본값이 아니라 영향도에 따라 켜지는 운영 모드입니다.

11. 계층 법 (Layer Law)

Section titled “11. 계층 법 (Layer Law)”
  • L0 Constitution: product law and invariants
  • L1 Contracts: schemas, compatibility, and examples
  • L2 Execution: runtime code, adapters, workflows, UI, infra

L2 must fail if it violates L1. L1 must fail if it violates L0.

flowchart TB
  L0["L0 · Constitution\n제품 법 / 불변식\n(이 문서)"]
  L1["L1 · Contracts\nfractalops-contract · 스키마 · 호환성 · 예시"]
  L2["L2 · Execution\n런타임 코드 · 어댑터 · 워크플로 · UI · 인프라"]
  L2 -->|위반 시 실패| L1
  L1 -->|위반 시 실패| L0

관련 문서

Section titled “관련 문서”