Jacquard

Release

Jacquard는 모델(models)이 작성하고 사람이 검토한 프로그램을 실행, 검토, 시뮬레이션 및 신뢰하기 위한 FriendMachine의 연구 프로젝트입니다. Jacquard에 대한 인간 친화적인 소개부터 시작해 보세요.

구체적으로, 이는 컴팩트한 .jac 표면 구문 (surface syntax), OCaml 체커 (checker) 및 CPS 인터프리터 (interpreter), 현재 커널 .jqd 캐리어 (carrier)를 컴파일하는 C 방출형 네이티브 AOT 백엔드 (C-emitting native AOT backend), 명령줄 도구 (command-line tool), Jacquard로 작성된 표준 라이브러리 (standard library), 그리고 Warp라고 불리는 테스트 프레임워크를 갖춘 작은 프로그래밍 언어입니다. 버전 0.1은 엔드 투 엔드 (end to end)로 작동하지만 연구용 프로토타입 (research prototype)이며, 프로덕션 언어 (production language)는 아닙니다. docs/release/0.1/LIMITS.md가 정직한 한계치입니다.

OCaml이나 opam 없이 0.1 릴리스 후보 (release candidate)를 설치하려면:

curl -fsSL https://raw.githubusercontent.com/jbwinters/jacquard-lang/jacquard-core-0.1-rc3/scripts/install.sh | sh
~/.local/bin/jac run ~/.local/share/jacquard/demos/basics/m1-fact.jac

예상 출력값은 120입니다. Linux x86-64, macOS Intel, 그리고 macOS Apple Silicon 바이너리가 배포되어 있습니다. 소스 코드로부터의 개발 방법은 아래에 문서화되어 있습니다.

그 다음, 구체적(concrete) 및 확률적(probabilistic) 텔레메트리 (telemetry) 세계에서 하나의 정책을 실행한 다음, 샘플링(sampled) 및 전수(exhaustive) Warp 체크를 수행합니다:

sh ~/.local/share/jacquard/demos/case-studies/release-risk/run.sh

인간을 위한 기능

대부분의 언어는 프로그램이 무엇을 계산하는지 알려줍니다. Jacquard는 프로그램이 수행할 수 있는 효과 (effects), 유한 이산 불확실성 (finite discrete uncertainty), 그리고 정형 프로그램 정체성 (canonical program identity)을 또한 드러냅니다. 도구들은 이 세 가지를 모두 검사할 수 있는데, 이는 이 정보들이 주석, 로그, 또는 코드베이스에 대한 당신의 기억 속에만 존재하는 것이 아니라 언어 자체에 살아있기 때문입니다.

대부분의 언어가 제공할 수 없는, 여기서 할 수 있는 것들:

• 한 줄만 읽고도 함수가 수행할 수 있는 효과 (effects)를 확인할 수 있습니다. (text) ->{net} text와 같은 시그니처 (signature)는 해당 함수가 net 효과를 수행할 수 있음을 나타냅니다. Jacquard 런타임 (runtime)은 --allow를 통해 권한이 명시적으로 부여되지 않은 경우, 동적 코드 (dynamic code)에 의해 수행되는 효과를 포함하여 처리되지 않은 월드 효과 (world effects)를 거부합니다. 이는 운영체제 샌드박스 (operating-system sandbox)를 대체하는 것이 아니라, 연구용 런타임 (research runtime)에서의 언어 수준 강제 (language-level enforcement)입니다.
• 하나의 프로그램을 여러 월드 (worlds)에 대해 실행할 수 있습니다. 동일한 코드를 실제 네트워크, 스크립트된 가짜 네트워크, 지난주 트래픽의 녹화본, 또는 서버가 통상적으로 어떻게 동작하는지에 대한 확률 모델 (probability model)에 대해 실행할 수 있습니다. 핸들러 (handler)는 프로그램의 외부 세계에 대한 요청에 응답하는 부분입니다. 핸들러를 교체하면 코드는 전혀 바뀌지 않습니다. 이는 효과 경계 (effect boundaries)에서의 많은 전통적인 모킹 (mocking)을 대체할 수 있으며, "API가 다운된다면 내 에이전트 (agent)는 어떻게 행동할까?"라는 질문을 평범한 테스트로 만들어 줍니다.
• 유한 이산 모델 (finite discrete models)에 대한 정확한 확률을 열거할 수 있습니다. 프로그램은 가중치가 부여된 선택을 샘플링 (sample)하고 증거를 기록할 수 있으며, 열거 (enumeration)는 도달 가능한 모든 결과를 각각의 정확한 확률과 함께 나열합니다. 아래의 복구 데모 (repair demo)는 실패한 테스트를 증거로 취급하여, 어떤 패치 (patches)가 여전히 가능한지, 그리고 각 패치가 얼마나 가능성이 높은지를 계산합니다.
• 정형 정체성 (canonical identity)을 변경하지 않고 이름 변경 및 재포맷을 할 수 있습니다. Jacquard는 소스 바이트 (source bytes) 대신 정형적으로 해결된 구조 (canonical resolved structure)를 해싱 (hash)합니다. 주석, 포맷팅, 출처, 그리고 일반적인 로컬 또는 용어 이름 변경은 삭제됩니다. 순수 테스트 (pure tests)는 정형 코드 (canonical code)나 의존성 (dependency) 콘텐츠가 변경될 때만 다시 실행됩니다. 이는 구조적 정체성 (structural identity)이며, 임의의 프로그램들이 행동적으로 동일하다는 증명은 아닙.

이 모든 것의 이면에 깔린 베팅 (bet): 대부분의 코드가 기계에 의해 작성될 때, 이를 검토하는 인간은 모든 줄을 읽지 않고도 "이것이 무엇을 건드릴 수 있는가, 그리고 우리는 그것을 얼마나 확신하는가"라는 질문에 답하기 위해 언어 그 자체를 필요로 한다는 것입니다.

에이전트 (Agents)를 위해

docs/SKILL.md를 먼저 읽으세요. 이 파일은 커널 (kernel), CLI, 서문 (prelude), Warp 테스트, 그리고 알려진 주의 사항 (gotchas)을 하나의 파일로 압축하며, docs/SKILL.md로부터 프로젝트 기술 (skill)로 로드됩니다. 운영 규칙은 AGENTS.md에 있습니다. 시간을 절약해 줄 사항들은 다음과 같습니다:

• 동작은 증거에 의해 고정(pinned)됩니다: test/cli/ 아래의 트랜스크립트 (transcripts), 코퍼스 골든 (corpus goldens), 데모 스크립트, 그리고 docs/release/0.1/CLAIMS.md를 참조하세요. 만약 고정(pin)이 실패한다면, 이를 당신의 변경 사항에 대한 정보로 취급해야 하며, 디프 (diff)를 통과시키기 위해 절대로 고정(pin)을 약화시키지 마세요.
• 커널 (kernel)은 27개의 형태 (forms)로 구성됩니다 (docs/ast.md). .jac는 이러한 형태들에 대한 투영 (projection)이며, 부트스트랩 (bootstrap) .jqd는 영구적으로 지원됩니다. 배포된 표면 경계 (surface boundary)와 보류 중인 후속 작업들을 고정된 문법 (frozen grammar)이 아닌 릴리스 증거 (release evidence)로 취급하세요. 범위를 벗어난 기능은 추가하지 마세요 (AGENTS.md에 목록이 있습니다).
• 개발 게이트 (development gate)는 dune build @all && dune runtest && dune fmt를 실행한 후, 깨끗한 git diff --exit-code를 확인하는 것입니다.

핵심 요소 (Core Ingredients)

프로그래밍 언어를 이해하는 독자들을 위해:

• 단일한 통일 표현 (uniform representation): 모든 형태 (form)는 (head, meta, args) 트리플 (triple)이며, 커널 (kernel) 문법은 27개의 형태를 가집니다. 인용된 코드 (Quoted code)는 일반적인 데이터입니다.

• 심층적이고 멀티샷 (multi-shot) 핸들러 (handlers)를 갖춘 대수적 효과 (Algebraic effects). 핸들러는 계산을 0번, 1번, 또는 여러 번 재개할 수 있으며, 이것이 전수 조사 (exhaustive search)와 정확한 추론 (exact inference)을 일반적인 라이브러리 코드로 만드는 핵심입니다.

• 명시적인 권한 부여 (Explicit capability grants). 런타임 (runtime)은 --allow와 함께 전달된 효과 (effects)에 대해서만 외부 세계를 위한 핸들러를 설치합니다. 주변 권한 (ambient authority)은 존재하지 않습니다.

• 타입 및 효과 로우 (Type-and-effect rows). 모든 화살표 (arrow)는 함수가 수행할 수 있는 효과 (effects)의 집합을 포함하므로, 프로그램의 추론된 로우 (inferred row)는 해당 프로그램의 권한 명세서 (authority manifest)가 됩니다.

• 라이브러리로서의 이산 확률적 프로그래밍 (Discrete probabilistic programming): sample과 observe는 효과 연산 (effect operations)이며, 각 추론 알고리즘 (inference algorithm)은 핸들러 (handler)입니다.

• 콘텐츠 주소 지정 정의 (Content-addressed definitions). 정체성 (Identity)은 비정체성 메타데이터 (non-identity metadata)가 제거된 정준적 해결 구조 (canonical resolved structure)의 해시 (hash)입니다. 따라서 포맷팅, 주석, 그리고 일반적인 로컬 또는 용어 변경 (term renames)은 다운스트림 (downstream)에 아무런 영향을 주지 않습니다.

• 위 사항들에 의존하는 툴링 (Tooling): 포매터 (formatter), 구조 인식 디퍼 (structure-aware differ), 콘텐츠 주소 지정 캐시 (content-addressed cache)를 사용하는 Warp 테스트, 레코드/리플레이 (record/replay), 그리고 재현 가능한 릴리스 증거 팩 (reproducible release evidence pack).

• C를 생성하고, 콘텐츠 해시 (content hash)별로 유닛을 특수화 및 캐싱하며, clang 및 gcc 환경에서 인터프리터와 차등 테스트 (differential-tested)를 수행하는 네이티브 AOT 경로.

프로토타입은 원래의 핵심 계획에 따라 완성이 되었으며, 이후 공개 표면 구문 (public surface syntax), 링 구조의 표준 라이브러리 (ringed standard library), Warp 속성 및 캐시, 네이티브 컴파일 (native compilation), 패키징된 바이너리 (packaged binaries), 그리고 제품 규모의 사례 연구 (product-scale case studies)가 추가되었습니다. RC1의 의미론적 경계 (semantic boundary)는 554개의 Alcotest/QCheck 케이스, 32개의 cram 트랜스크립트, 21개의 문서 예제, 네이티브 새니타이저/누수/퍼징 (sanitizer/leak/fuzz) 레인, 그리고 fresh-clone 증거 워크플로우에 의해 고정되었습니다. RC2는 바이너리 데모 패키징을 수정하였고, RC3는 명시적인 런타임/출력 라이선스 예외를 추가하고 네이티브 런타임을 패키징했습니다. 현재의 후속 배포판은 Jacquard를 Apache License 2.0으로 재라이선스하며, 해당 런타임/출력 권한을 명시적인 설명으로 유지합니다. 이러한 라이선스 및 패키징 변경 사항은 RC1에서 고정된 언어 의미론 (language semantics)을 변경하지 않습니다.

모습 (What It Looks Like)

다음은 하나의 핸들러가 하나의 연속 (continuation)을 두 번 재개하는 예시입니다. 이 블록은 test/docs-doctest/fixtures/readme-multishot.jac로 바이트 단위로 복사되어 문서 테스트 레인 (documentation test lane)에 의해 실행됩니다:

effect Choice where {
  choose : () -> Bool
}
...

$ jac run test/docs-doctest/fixtures/readme-multishot.jac
3

핸들러(handler)는 true로 한 번, false로 한 번 프로그램을 나머지 부분까지 실행한 다음, 두 결과 모두를 수집했습니다. 이렇게 여러 번 재개할 수 있는 능력 덕분에, 정확한 베이지안 추론 (exact Bayesian inference)은 런타임 기능 (runtime feature)이 아닌 라이브러리 핸들러 (library handler)로 구현됩니다. 수정 데모 (repair demo)는 이를 기반으로 합니다. 버그가 있는 프로그램의 인용된 AST (quoted AST)를 후보 패치 (candidate patches)로 변환하고, 실패하는 테스트를 관측값 (observation)으로 취급하며, 업데이트된 확률을 읽어냅니다. 후보 코드를 실행하는 것은 권한 (authority)이 필요하므로, 순수 단계 (pure step)가 여전히 실행되어 (8개의 후보 패치를 카운트함) 실행된 후, 나머지 권한을 부여할 때까지 데모는 거부됩니다:

$ jac run demos/tooling/repair.jac
8
error[E0814]: this program requires the `eval` effect, which is not granted (performed via `posterior-over-patches`)
...

권한을 부여하면, 하나의 실패하는 테스트로 인해 두 개의 생존 패치가 남습니다: 0.75 확률의 의도된 수정 사항과, 테스트 스위트를 속이는(games the suite) 0.25 확률의 패치입니다. 회귀 테스트 (regression test)를 하나 추가하면 가짜 패치를 제거(prunes)하며, 살아남은 수정 사항은 - sub + add 형태의 한 줄짜리 정형 디프 (canonical diff)로 출력됩니다. 전체 기록은 sh demos/tooling/repair.sh를 참조하세요.

릴리스 바이너리 설치

대부분의 사용자는 OCaml이나 opam이 필요하지 않습니다. 검증된 0.1 RC 바이너리를 다음 명령어로 설치하세요:

curl -fsSL https://raw.githubusercontent.com/jbwinters/jacquard-lang/jacquard-core-0.1-rc3/scripts/install.sh | sh

설치 프로그램은 OS와 CPU를 감지하고, 일치하는 아카이브와 SHA-256 체크섬을 다운로드하며, 체크섬 불일치를 거부하고, 기본적으로 ~/.local 아래에 설치합니다. ~/.local/bin이 PATH에 포함되어 있는지 확인한 후, 다음을 실행하세요:

jacquard --version
jac --version

jac는 jacquard의 짧은 별칭 (short alias)입니다. 두 명령 모두 설치된 패키지로부터 JACQUARD_PRELUDE를 설정하므로, 일반적인 실행 시에는 환경 변수가 필요하지 않습니다:

jac run ~/.local/share/jacquard/demos/basics/m1-fact.jac

내러티브 데모 (Narrative demos)에는 설치된 바이너리와 프렐류드 (prelude)를 자동으로 선택하는 런처 (launchers)가 포함되어 있습니다. 이들은 Dune을 필요로 하지 않습니다:

DEMO_ROOT="$HOME/.local/share/jacquard/demos"
sh "$DEMO_ROOT/case-studies/release-risk/run.sh"
sh "$DEMO_ROOT/worlds/agent-dream.sh"
...

확률적 모델 (probabilistic model)이나 다중 파일 엔트리포인트 (multi-file entrypoint)를 직접 실행하는 대신 이 런처 (launchers)들을 사용하세요. 런처는 관찰 (observation)이 필요한 경우 infer를 선택하며, 격리된 스크래치 공간 (scratch space)에 관련 파일들을 조립합니다.

다른 사용자 소유의 프리픽스 (prefix) 아래에 설치하려면 다음과 같이 하세요:

curl -fsSL https://raw.githubusercontent.com/jbwinters/jacquard-lang/jacquard-core-0.1-rc3/scripts/install.sh \
  | JACQUARD_INSTALL_PREFIX="$HOME/.jacquard" sh

다른 릴리스 태그 (release tag)를 설치하려면 JACQUARD_INSTALL_VERSION을 설정하세요. 지원되는 바이너리 타겟 (binary targets)은 linux-x86_64, macos-x86_64, macos-arm64이며, 다른 플랫폼은 현재 개발 환경 설정 (development setup)이 필요합니다.

릴리스 아카이브 (Release archives)는 jacquard-core-* GitHub 릴리스에 첨부되어 있습니다. 각 아카이브에는 bin/jacquard, bin/jac, libexec/jacquard/jacquard, share/jacquard/prelude, share/jacquard/demos, 네이티브 C 런타임 (native C runtime), 그리고 라이선스 (license), 고지 (notice), 예외 (exception), 상표 (trademark) 문서가 포함되어 있습니다.

개발 퀵 스타트 (Development Quick Start)

이 명령어들은 새로 클론 (clone) 했으며 opam 설치를 위해 asdf를 사용할 수 있다고 가정합니다. 이미 opam 2.5.x 버전을 가지고 있다면 로컬 스위치 (local switch) 단계부터 시작하세요. 머신에 이미 opam이 초기화되어 있다면 opam init은 건너뛰어도 됩니다.

git clone https://github.com/jbwinters/jacquard-lang.git
cd jacquard-lang

...

스위치 (switch) 단계에서는 OCaml 5.1.1을 소스에서 컴파일하므로, 첫 설정에는 약 10분 정도 소요될 것으로 예상됩니다.

마지막 git diff --exit-code는 개발 계약 (development contract)의 일부입니다. 포매팅 (formatting) 차이점을 의도적으로 커밋하지 않는 한, 워크트리 (worktree)는 깨끗한 상태를 유지해야 합니다.

설정 후 예상되는 버전:

• .tool-versions로부터의 opam 2.5.1
• 리포지토리 로컬 (repo-local) _opam/ 스위치로부터의 OCaml 5.1.1
• jacquard.opam으로부터의 dune, ocamlformat, alcotest, qcheck, digestif, menhir, cmdliner, odoc, utop, 그리고 ocaml-lsp-server

기존 체크아웃 (checkout) 내부의 새 셸 (shell)에서 다음을 실행하세요:

eval "$(opam env)"

_opam/은 의도적으로 무시됩니다. 이는 소스 코드가 아닌 로컬 빌드 아티팩트 (build artifact)입니다.

Jacquard 실행하기

개발 중에는 Dune을 통해 빌드된 바이너리를 사용하세요:

opam exec -- dune exec jac -- --help
opam exec -- dune exec jac -- --version

많은 직접적인 CLI 명령에는 프렐류드 (prelude)가 필요합니다. 리포지토리 (repository) 루트에서 다음을 실행하세요:

export JACQUARD_PRELUDE=$PWD/prelude
opam exec -- dune exec jac -- run demos/basics/m1-fact.jac

주요 명령어는 다음과 같습니다:

jac run FILE.jac [--allow fs] [--allow net] [--dry-run]
jac check FILE.jac [--print-sigs] [--manifest fs,net,console]
jac hash FILE.jac
...

.jac는 사용자가 접하는 표면 캐리어 (surface carrier)입니다. 부트스트랩 (bootstrap) .jqd는 내부/디버그 구문 (syntax), 인용 표기법 (quote notation), 그리고 레코드 (record)의 커널 포맷 (kernel format)으로서 여전히 완전히 지원됩니다. run, check, hash, fmt, diff, infer, 그리고 test는 확장자에 따라 표면 구문 (surface syntax)을 선택합니다. 네이티브 빌드 (native build), 리플레이 프로그램 (replay programs), 프렐류드 (prelude), 그리고 많은 내부 피스처 (internal fixtures)들은 계속해서 .jqd를 사용합니다.