Metadata-Version: 2.4
Name: riscon-moat
Version: 0.3.0
Summary: An evidence-led moat-building workbench for single-auditor orchestration
Author: RISCON Labs
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<51,>=46.0.7
Dynamic: license-file

# RISCON Moat · 해자 구축기

Moaticle은 **moat + particle**, 입자 단위로 만드는 해자 인사이트 파이프라인이다. 개인·기업·국가 브랜드의 관찰, 실패, 개입, 결과와 반례를 조건과 원문에 묶고, 새 과업에서 실행할 자산으로 조립한다. 완전 복제한 상대도 따라오기 어려운 결과를 만들고 새 사례에서 그 차이를 잰다. [파이프라인](skills/riscon-moat/references/particles.md) · [CLI·MCP 예제](examples/particles/README.md)

대상을 역설계하고, 공개 구현을 복제한 뒤에도 이점을 만들 수 있는 자산을 제안하고 직접 구축한다. 한 사람이 가장 강한 대안과의 차이, 갱신이 멈췄을 때의 변화, 반례의 원문을 다시 확인할 수 있다. 사이트, CLI와 Aja의 MCP가 같은 SQLite 원장을 쓴다. 작업자는 세션을 닫고도 실험 계획·인수 상태·관측 원문에서 이어서 시작할 수 있다.

## 역설계 → 제안 → 실제 구축

사이트의 **구축** 메뉴에서 대상을 등록한다. 공개 구현이 설명하는 기능과 실제 실행에서 얻은 결과를 증거에 묶는다. 앞선 관측만으로 새 사례의 예측을 동결하고, 새 결과를 붙이면 다음 과업에서 바로 조회하고 복구할 수 있는 결과 인덱스를 만든다. 공개 구현, 직전 자산, 최신 자산을 가진 복제와 갱신·출처 중단을 동일 사례에서 비교한다.

실제 CPython 설치본 다섯 개를 측정한 예제에서 100건의 실행 결과를 자산으로 만들었다. 공개 프로브가 80건 전부를 재현해 해당 해자 가설은 반박됐다. [구축 절차](docs/construction.md) · [실행 예제와 자산](examples/construction/README.md)

## 실행

Python 3.11 이상에서 설치한다. 명령은 Python 가상 환경을 활성화한 상태를 기준으로 한다.

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
riscon-moat --db .moat/demo.sqlite3 demo
riscon-moat --db .moat/demo.sqlite3 serve
```

[로컬 사이트](http://127.0.0.1:8767)를 연다. 데모의 3개 가설은 승인, 반박, 연구 중 상태를 보여 준다. 실측값과 서명키는 실험실 시연용으로 생성한다. 실제 작업은 별도 원장에 등록한다.

```sh
riscon-moat --db .moat/ledger.sqlite3 init --min-turns 100000
riscon-moat --db .moat/ledger.sqlite3 serve
```

운영 원장은 가설 계보당 100,000턴을 기본값으로 사용한다. 초기화에서 10,000–1,000,000턴을 고른다. 실측이 나오기 전에는 운영 원장과 실험실 원장 모두 조회 및 가설 작성·작업 인수·참고 기록을 지원한다. Python 모듈로 실행하려면 `riscon-moat` 대신 `python -m riscon_moat`을 쓴다.

## 숙고가 자산으로 이어지는 흐름

1. 가설에 과업, 핵심 자산, 최선 대안, 측정 지표, 최소 효과, 모방 한도, 지속 기간과 반증 조건을 등록한다. 비교 대상의 바이트 해시를 동결한다.
2. 자료 탐색과 자산 제작을 작업 큐로 나눈다. 이 단계에서는 실험 입력과 후보를 만든다. 운영 실측은 결과를 보기 전에 고정한 사례 입력의 SHA-256을 요구한다.
3. 독립 검증 경로가 같은 사례를 후보·대안과 실행하고 서명한다. 원장이 그 서명을 원문, 사례, 프로토콜, 가설 버전에 묶는다. 비교·제거·비용·지속성 실험은 서로 다른 질문을 측정한다.
4. 서명된 반례가 들어오면 승인 상태를 재평가한다. 개정 뒤에도 같은 반례와 기준을 통과할 때까지 이전 이견이 남는다. 같은 측정값을 바꿔 쓰거나 개정 때 재사용하는 방식으로 숙고량을 올릴 수 없다.
5. 현재 가설의 각 실측 조건을 확인한 뒤 대표님이 승인한다. 운영 구축률은 **현재 승인 상태인 가설의 가중치 합 ÷ 전체 등록 가설의 가중치 합**이다. 폐기한 가설의 가중치도 분모에 남는다. 화면의 가설별 조건 충족률과 실험실 구축률은 별도 값이다.

[판정 계약과 서명 예제](docs/method.md) · [실제 비교 및 제거 실험](examples/paired_trial/README.md) · [Agent Skill](skills/riscon-moat/SKILL.md) · [Aja 설정](integrations/aja/README.md)

## 장기 실행을 이어서 등록

동결한 실험을 JSONL 한 행에 하나씩 쓴다. 각 행은 `action schedule`의 JSON이며 `expected_version`을 포함한다. 운영 실측에는 `case_sha256`도 넣는다. 첫 실행은 기본 250건을 한 트랜잭션으로 등록한다. 앞선 구간을 다시 실행해도 동일 계획은 새 작업을 만들지 않는다. 수정되거나 잘못된 행이 있으면 해당 구간을 저장하지 않는다.

```sh
riscon-moat --db .moat/ledger.sqlite3 enqueue plan.jsonl --limit 250
riscon-moat --db .moat/ledger.sqlite3 enqueue plan.jsonl \
  --from-line 251 --plan-sha256 "$PLAN_SHA256" --limit 250
```

실제 이어받기에서는 응답의 `next_line`과 `plan_sha256`을 사용한다. 작업자는 사이트, CLI 또는 MCP에서 다음 작업을 인수하고 원문을 남긴다. 등록 건수와 독립적으로 관측한 턴은 각각 집계한다.

## REA · Ghidra

[네이티브 예제](examples/native/README.md)의 자체 C 바이너리로 다음 동선을 재현할 수 있다.

```sh
riscon-moat native collect ./revision.dylib --out ./native-receipt \
  --rea /path/to/rea --ghidra /path/to/ghidra/support/analyzeHeadless
riscon-moat native verify ./native-receipt --artifact ./revision.dylib
```

결과 영수증의 위치를 `structural` 작업으로 남긴다. REA가 형식과 아티팩트 식별을, Ghidra가 함수와 정적 호출 위치를 기록한다. 두 도구가 읽은 바이트가 같으면 원천은 하나다. 분석 대상은 소유하거나 공개된 로컬 ELF·thin 64-bit Mach-O다. 원본은 실행하지 않는다. Ghidra와 REA는 선택적으로 설치하는 별도 프로그램이며 패키지에 포함하지 않는다.

## 자체 호스팅

표준 경로는 하나의 사이트 프로세스와 SQLite의 영속 볼륨이다. 운영 사이트를 외부에 둘 경우 TLS를 처리하는 리버스 프록시 뒤에 놓고, 원본 Host 헤더와 지정한 공개 Origin을 일치시킨다. `MOAT_WEB_TOKEN`은 실행 환경에서 주입한다. 인증 사용자명은 `moat`다.

```sh
riscon-moat --db /path/to/ledger.sqlite3 serve \
  --host 127.0.0.1 --port 8767 --public-origin https://moat.example.org
```

컨테이너는 다음 절차로 구성한다. 공개 경로는 TLS 프록시에서 종단한다.

```sh
docker build -t riscon-moat .
docker volume create riscon-moat-data
docker run --rm -v riscon-moat-data:/data riscon-moat init --min-turns 100000
docker run --rm -p 127.0.0.1:8767:8767 -v riscon-moat-data:/data \
  -e MOAT_WEB_TOKEN riscon-moat serve \
  --host 0.0.0.0 --public-origin https://moat.example.org
```

활성 DB 백업은 SQLite의 backup API를 사용한다. 정지한 뒤 복사할 때는 WAL을 체크포인트한 후 옮긴다. 원장의 기준 해시는 DB 밖의 감사 기록에 저장한다.

## 재현

```sh
python -m unittest discover -s tests -v
PYTHONPATH=. python validation/scale.py --result /tmp/moat-scale.json
```

로컬 독립 합성 시험의 규모와 실측 방법을 검증 자료에 남겼다. 실제 해자는 프로젝트에서 별도로 축적하고 서명한 자료에 따라 판정된다. 자체 코드는 MIT이며 서체별 OFL은 `riscon_moat/site/fonts/`에서 확인할 수 있다.
