pqcaton · architecture

관측 위에 판정을 얹는 구조 Judgment laid on top of observation

pqcota가 관측하고, pqcaton이 그 관측을 선언과 대조해 리뷰에 올리고 확정합니다. 두 리포는 계약(contracts/)으로만 이어집니다. 코드가 서로를 부르지 않습니다. pqcota observes; pqcaton reconciles those observations against the declaration, puts them in a review queue and finalizes them. The two repositories are joined only by contracts (contracts/) — neither calls the other's code.

01한눈에 At a glance

왼쪽이 기반(pqcota), 오른쪽이 이 리포(pqcaton)입니다. 가운데 띠가 둘 사이를 잇는 유일한 통로이고, 화살표는 그 띠를 두 번 건넙니다. 관측이 오른쪽으로 가고, 확정된 계획이 왼쪽으로 돌아갑니다. The base (pqcota) is on the left, this repository (pqcaton) on the right. The band in the middle is the only passage between them, and the arrows cross it twice: observations travel right, finalized plans come back left.

PQCOTA: 관측 · 정규화 · 전환 PQCOTA: OBSERVE · NORMALIZE · CONVERT CONTRACTS PQCATON: 대조 · 판정 · 거버넌스 PQCATON: RECONCILE · JUDGE · GOVERN proto → gen/ 어휘의 single source 단일 출처 of vocabulary 수집기: 대상 노드에서 돈다 Collectors: run on the target node collectors/{openssl, jvm, cng, network} ansible/discover.yml 이 반입·실행·회수 ansible/discover.yml ships, runs and collects them 커널: 관측을 사실로 바꾼다 Kernel: turns observation into fact kernel/posture · registry 협상된 그룹 → 양자내성 등급 negotiated group → quantum-resistance grade kernel/machineid · scope · sign 적재: 인벤토리가 되는 자리 Ingest: where it becomes an inventory discovery/{normalize, history} inventory/{ingest, profile, render} 완전성 맵 · 거절 이력 · 조직 축 completeness map · rejection history · org axis 선언 반입 Declaration import inventory/declaration 조직이 「이렇게 알고 있다」고 적은 것 what the organization wrote down as “this is what we know” 전환물 생성 · 적용 Generate and apply the conversion provisioning · pqcota-provision before 캡처 · 되돌림 before-capture · rollback 대조 엔진: 선언과 관측을 맞댄다 Reconciliation engine: declaration against observation pkg/inventory/reconcile 3-상태 · confidence 스코어링 · 리뷰 큐 · 토폴로지 three states · confidence scoring · review queue · topology CONFIRMED · UNDECLARED · UNOBSERVED UNOBSERVED는 기계가 확정하지 않는다 no machine finalizes an UNOBSERVED item 판정: 사람의 결론을 붙들어 둔다 Judgment: holds the human conclusion pkg/inventory/decision draft → in-review → finalized · append-only 근거가 바뀌면 그 판정만 델타 리뷰 when the basis changes, only that judgment goes to delta review inventory/cmd/{pqcaton-report, decide, scope, ui} 사람이 돌리고 채우는 자리: 화면 · 리포트 · 토폴로지 where a person runs and fills in: screens · reports · topology CollectionResult 관측 레인 observation lane 선언 레인 declaration lane 리뷰 큐 review queue FinalizedPlan 확정된 것만 내려간다 only what is finalized goes down
그림 1. 계약 띠를 두 번 건넙니다. 관측이 오른쪽으로, 확정된 계획이 왼쪽으로. 왼쪽 상자들은 pqcaton 없이도 그대로 돕니다. 오른쪽이 없으면 판정이 없을 뿐 관측은 끝까지 됩니다. Figure 1. The contract band is crossed twice: observations to the right, finalized plans to the left. The boxes on the left run just as they are without pqcaton. Take the right side away and you lose the judgment, not the observation.

이 그림이 알려 주는 것 하나. pqcaton은 pqcota를 감싸지 않습니다. 나란히 서서 계약으로만 주고받습니다. 그래서 pqcota를 갈아 끼워도 이 리포가 깨지지 않고, 이 리포를 지워도 pqcota는 그 자체로 완결됩니다. One thing this diagram tells you. pqcaton does not wrap pqcota. They stand side by side and exchange only what the contracts define. Swap pqcota out and this repository does not break; delete this repository and pqcota is still complete on its own.

02계약이 유일한 연결선입니다 Contracts are the only link

이 리포는 pqcota의 생성된 타입만 import합니다. 관측 로직도, 저장소 스키마도 재구현하지 않습니다. This repository imports only the generated types from pqcota. It reimplements neither the observation logic nor the storage schema.

이 리포가 쓰는 상류 Upstream this repository uses무엇을 위해 What for
gen/…/common/v1Envelope·CryptoRuntime 등 공통 어휘 Shared vocabulary such as Envelope and CryptoRuntime
gen/…/discovery/v1관측 결과(CollectionResult)를 읽는다 Reads observation results (CollectionResult)
gen/…/inventory/v1ReconState·Decision. 3-상태와 판정의 SSOT ReconState and Decision — the SSOT for the three states and for judgments
pkg/discovery/history관측 이력 저장소를 그대로 쓴다 Uses the observation history store as it is
pkg/discovery/normalize정규화된 관측을 받는다 Takes normalized observations
pkg/inventory/declaration선언(CMDB) 반입 Imports the declaration (CMDB)
pkg/kernel/posture양자내성 등급. 우리가 다시 판단하지 않는다 Quantum-resistance grading — we do not judge it again
pkg/kernel/registry결정론적 서명 매칭 데이터 Deterministic signature-matching data
pkg/kernel/scope자산 스코프 규칙. 형식과 집행을 그대로 쓴다 Asset scope rules — both the format and the enforcement are used as they are
discovery/collectors/openssl이 기계를 스캔하는 지름길이 부른다 Called by the shortcut that scans this machine
gen/…/provisioning/v1확정 계획(FinalizedPlan)의 형식 The shape of a finalized plan (FinalizedPlan)
pkg/org조직 격리 축 The organization isolation axis

internal/probe는 그 연결을 붙들어 두는 최소 코드입니다. 지워도 빌드는 되지만, 그러면 go.mod의 require가 아무 표시 없이 미사용이 됩니다. internal/probe is the smallest amount of code that holds that link in place. Delete it and the build still passes, but the require lines in go.mod quietly go unused.

03이 리포가 더하는 것 What this repository adds

모듈 Module하는 일 What it does왜 상류가 안 만들었나 Why upstream did not build it
pkg/inventory/reconcile 3-상태 대조 · confidence 스코어링 · 리뷰 큐 · 거버넌스 토폴로지 Three-state reconciliation, confidence scoring, the review queue, the governance topology 관측 도구가 “무엇이 위험한가”를 판정하기 시작하면 관측의 정직성이 무너집니다 Once an observation tool starts judging “what is risky”, the honesty of the observation is gone
pkg/inventory/decision 리뷰-확정 상태기계 · 판정 영속(append-only) · 확정 계획 The review-to-finalize state machine, append-only judgment persistence, the finalized plan 판정은 조직의 책임이고 감사 대상입니다. 혼자 쓰면 필요 없습니다 A judgment is the organization's responsibility and subject to audit. Working alone, you do not need it
inventory/cmd/* · pkg/inventory/ui 대조 실행 · 리포트와 토폴로지 렌더 · 사람이 쓰는 화면(선언 · 암호 자산 스코프 · 대조 · 판정 · 인벤토리 조회) Runs the reconciliation, renders reports and the topology, and serves the screens people use — declaration, crypto asset scope, reconciliation, judgment, inventory lookup 사람이 돌리고 사람이 채우는 자리 The place a person runs and a person fills in
saas/runner 호스팅으로 쓸 때만 필요한, 결과를 내보내는 자리 The place that sends results out, needed only when we host it 고객 인프라 안에서만 돌 때는 필요 없습니다. 05 Not needed when everything runs inside the customer's infrastructure. 05

3-상태가 이 도구의 어휘입니다 The three states are this tool's vocabulary

상태 State정의 Definition등급 Grade무엇을 뜻하나 What it means
CONFIRMED선언 ∩ 관측 declared ∩ observedAUTO신뢰도 최상 The highest confidence
UNDECLARED관측만 observed onlyAUTO조직이 모르는 통신입니다. 이 도구가 주는 첫 번째 쓸모입니다 Traffic the organization does not know about. This is the first thing the tool is good for
UNOBSERVED선언만 declared onlyMANUAL실재하는데 못 본 것인지 이미 없어진 것인지는 사람만 압니다 Whether it exists and was missed or is already gone — only a person knows

UNOBSERVED를 기계가 확정하지 않는 것이 설계의 축입니다. pqcota의 완전성 맵이 “원리상 관측 불가”와 “실제 없음”을 구분해 주고, 그 위에서 사람이 정합니다. The axis of the design is that no machine finalizes an UNOBSERVED item. pqcota's completeness map separates “cannot be observed in principle” from “really absent”, and a person decides on top of that.

04한 바퀴가 도는 길 How one full turn runs

직접 설치에서는 밖으로 나가는 것이 하나도 없습니다. 모든 단계가 고객 인프라 안에서 끝납니다. 호스팅으로 쓸 때 무엇이 달라지는지는 05절에 있습니다. In a self-hosted install nothing leaves the network. Every step finishes inside the customer's own infrastructure. What changes when we host it for you is in section 05.

선언 Declaration CMDB 반입 CMDB import 관측 Observe pqcota 3 적재 Ingest pqcota 4 조회 Look up pqcota 5 대조 Reconcile 3-상태 · confidence three states · confidence 리뷰 큐 구성 build the review queue 리뷰 · 확정 Review · finalize 사람이 판정 a person judges 승인 서명 approval signature 확정 계획 → 적용 Finalized plan → apply pqcota 6 · 7 · 8 before 캡처 · 되돌림 before-capture · rollback 관문 gate pqcaton 없이: 손으로 쓴 계획 without pqcaton: a hand-written plan 근거가 바뀐 판정만 델타 리뷰 delta review for judgments whose basis changed 재관측 · 변화 diff re-observe · diff the change
그림 2. 가운데 두 상자만 이 리포입니다. 아래 점선이 pqcaton 없이 가는 길입니다. pqcota는 확정 계획을 입력으로만 받고, 손으로 쓴 계획으로도 끝까지 돕니다. 확정 앞의 화살표가 이 제품에서 반드시 거쳐야 하는 관문입니다: finalized 전에는 적용이 돌지 않습니다. Figure 2. Only the two middle boxes are this repository. The dashed line below is the path without pqcaton: pqcota takes a finalized plan as input only, and a hand-written plan carries it through just as well. The arrow before finalization is the gate this product insists on — nothing is applied before it is finalized.

05호스팅으로 쓸 때만 붙는 것 What is added only when we host it

위 그림에는 러너가 없습니다. 자기 서버에서 돌릴 때는 필요 없기 때문입니다. pqcota-ingest가 결과를 바로 읽고, 대조와 판정이 같은 기계에서 끝납니다. There is no runner in the diagram above, because on your own servers you do not need one. pqcota-ingest reads the results directly, and reconciliation and judgment finish on the same machine.

우리가 대신 돌려 주는 호스팅에서는 관측 결과가 고객망을 나와야 하고, 그것을 내보내는 자리가 saas/runner입니다. 그 코드만 이 리포에 있는 이유는 하나입니다. 고객 서버에서 고객 권한으로 도니 무엇을 밖으로 보내는지 읽어서 확인할 수 있어야 합니다. 컨트롤 플레인 쪽 코드와 설계는 이 리포에 없습니다. When we run it for you, the observation results have to leave the customer network, and saas/runner is the place that sends them out. Only that piece lives in this repository, for one reason: it runs on the customer's servers with the customer's privileges, so what it sends must be open to reading. The control-plane code and its design are not here.