Jacquard ファウンドゥード研究プロジェクト

Jacquard は、コードの記述、レビュー、シミュレーション、およびそれらを信頼することを可能にするためのファウンドゥード（FoundMachine）研究プロジェクトです。これは単なるプログラミング言語ではなく、人間によるレビューを支援する仕組みを内包したシステムです。

注意: 現在のは研究プロトタイプ（バージョン 0.1）であり、生産環境での即時利用は想定されていません。必ず LIMITS.md を事前にお読みください。

概要と特徴

Jacquard はコンパクトな構文（

.jac

.jqd

言語が暴露する情報

多くの言語は「何を計算するか」のみを表しますが、Jacquard は以下も直接表します：

• Effects (効果): プログラムが及ぼす変化
• Uncertainty (不確実性): 有限離散的不確実性のモデル化
• Canonical Program Identity (規範的な同一性): コードの構造的等価性

これらはコメントやログではなく、言語自体に埋め込まれています。

ここしかできないこと（他言語にはない機能）

1. 即座の効果把握: 一行で関数の可能な効果を判断可能。型シグネチャ

   (text) -> {net} text

   はネットワーク効果へのアクセスを示します。デフォルトでは外部世界へのアクセスは拒否されます。
2. 多様な「世界観」での実行: 同じコードを、実際のネットワークや過去のトラフィック記録（確率モデル）など、異なるコンテキストに対して実行できます。外部ハンドラ（Handler）の交換のみでコード変更不要です。
3. 確率的な列挙処理: すべての到達可能な結果とその正確な確率をリストアップできます。証拠（Failed Tests）を扱い、各パッチが残る可能性を計算可能。
4. 再形式化による同一性保持: コメントやフォーマット、変数名の変更などは「ノイズ」として消去され、構造的なコードのみが同等と判断されます。純粋なテストは構造が変わった場合にのみ再実行されます。

インストール方法

OCaml や

opam

ビルドなしでのインストール（推奨）

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

• 対応 OS: Linux x86_64, macOS Intel, macOS Apple Silicon
• インストール場所: 通常

  ~/.local

  (PATH に含まれていることを確認)
• 使用コマンド:

  jacquard

  またはエイリアス

  jac

  のどちらでも動作します。

サンプルプログラムの実行

# ファクトリアル（階乗）の実行：期待値 120
jac run ~/.local/share/jacquard/demos/basics/m1-fact.jac

ケーススタディのデモ

確率的テレメトリーや WARP チェックを含む実行例：

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

開発者向け（For Humans）

研究プロトタイプとして構築されていますが、言語機能は実装済みです。

基本構成要素 (Core Ingredients)

• 単一表現: 全ての形式は

  (head, meta, args)

  の三つ組です。
• 代数効果とハンドラ: カルキュレーションの再開が可能で、深い多回ハンドラを扱えます。
• 明示的能力付与 (Capability Grants):

  --allow

  を指定しない限り外部世界へのアクセスは拒否されます。
• 型と効果の行: 関数の署名は効果をセットとして持ちます。
• 内容アドレス指向: 同一性の判定にはフォーマットやコメントを排除した構造ハッシュを使用します。

ハンドラの動作原理 (Multishot)

ハンドラは一次継続を複数の回再開できます。これにより、正確な確率的推論（ベイジアン）がライブラリ側で処理されます。

例：多試行実行 (

test/docs-doctest/fixtures/readme-multishot.jac

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

handle {
  match choose() {
    | True -> 1
    | False -> 2
  }
} {
  | return x -> x
  | choose() resume continue -> add(continue(True), continue(False))
}

出力:

3

プログラム修復デモ (

repair.jac

)

バグを修正する際、候補パッチに対するテストの失敗結果（証拠）を計算した確率分布として扱います。最も可能性の高い修復案だけを提示します。

# 権限なしではエラー
$ jac run demos/tooling/repair.jac
error[E0814]: this program requires the `eval` effect, which is not granted

# 明示的な許可で実行 (--allow eval)
$ jac run demos/tooling/repair.jac --allow eval

※ 権限なしの状態での挙動は仕様であり、サンドボックスとして機能します。

エージェント向け（For Agents）

エージェントがプロジェクトを自律的に扱うためのガイドラインです。

docs/SKILL.md

スキルと運用ルール

• 振る舞いの固定: トランスクリプトやゴールデンドータは変更しない。「差分を通す」ためには情報を追加し、既存のピン（制約）を弱めることは禁止されます。
• カーネルの厳密さ:

  .jac

  は 27 の形式への射影であり、

  .jqd

  は永久的にサポートされる内部言語です。スコープ外の特徴を追加しないようにしてください。
• 開発ゲートの厳格性:

  dune build @all && dune runtest && dune fmt
  git diff --exit-code  # 未変更であることを確認
  

コンパイル（ネイティブ AOT）

OCaml コードを C ベースのバイナリにコンパイルできます。これにより、VM/JIT や並列処理などの制約なく高速な実行が可能になります。

使用方法

export JACQUARD_PRELUDE=$PWD/prelude
export JACQUARD_RUNTIME=$PWD/runtime
jac build demos/tooling/word-count.jqd -o word-count
echo "some words some" | ./word-count --allow console

要件と環境設定

• C ツールチェーン:

  clang

  (推奨) または

  gcc

  。
• スタックサイズ: デフォルト 1024MB。深い非尾再帰には注意が必要です。
• キャッシュ: コンパイルされたユニットは

  .jacquard-native/

  にコンテンツハッシュ付きで保存されます。

ドキュメントマップ

初めての方の学習順序:

初心者パス (User-Facing)

1. docs/README.md

   : インデックスと推奨読書パス

2. docs/tutorial.md

   : 実行可能なユーザー向け例

3. demos/README.md

   : デモカタログ（各デモが証明する内容）

設計者・開発者パス (Implementation)

• docs/whitepaper.tex

  : 初期設計と理論的背景（ロードマップセクションは陳腐化している場合があります）

• docs/ast.md

  : カーネル AST とメタデータ仕様

• spec/jacquard-kernel-ast-m0.md

  : ソースオブトゥルース仕様の詳細

• docs/errors.md

  : エラー診断カタログ

CI / リリース情報

• docs/ci-cd.md

  : GitHub Actions ワークフローの説明

• docs/release/0.1/EVIDENCE.md

  : 構築および通過したテストのリスト

• docs/release/0.1/CLAIMS.md

  : セマンティック主張のマッピング

リポジトリマップ

メインディレクトリ構造

• .github/

  : CI、ワークフロー、PR テンプレート。

• AGENTS.md

  : エージェント運用メモ。

• bin/

  : CLI エントリーポイント。

• corpus/

  : 適合性コーパスとゴールデンドータ。

• demos/

  : 実行可能な事例集（デモ）。

• docs/

  : 設計ドキュメント、チュートリアル、リリースエビデンス。

• prelude/

  : 標準ライブラリと効果宣言。

• scripts/release/

  : リプロダシブルなリリーススクリプト。

• spec/

  : カーネル AST とシリアライゼーション仕様。

• src/

  : OCaml 実装コード。

• test/

  : Alcotest/QCheck テストスイートおよび cram トランスクリプト。

実装マッピング (

src/

)

• form.ml

  ,

  meta.ml

  : 表現とメタデータ。

• reader.ml

  ,

  printer.ml

  : 読み込み・フォーマット。

• kernel.ml

  : 型付きカーネル AST とバリデーター。

• resolve.ml

  : 名前解決（コンテンツアドレス指向）。

• canon.ml

  ,

  hash.ml

  : 規範シリアライゼーションとハッシング。

• store.ml

  : オブジェクトストア管理。

• eval.ml

  : CPS エバリューエータとハンドラ。

• types.ml

  ,

  check.ml

  : 型推論・効果チェック。

• infer_dist.ml

  : 確率的推論（列挙・尤度）。

• warp.ml

  : WARP テストフレームワークの実装。

リリースエビデンス (Release Evidence)

バージョン 0.1 のリリース候補については、完全な再現性が保証されています。

エビデンスの再生成

チェックアウトした状態から以下のスクリプトを実行することで、公開されたすべてのテストと結果を再現できます：

JACQUARD_RELEASE_REF=HEAD JACQUARD_RELEASE_BASE=738dc8e scripts/release/reproduce-0.1.sh

• ビルド・全テスト実行
• フォーマットチェック
• プライベートデモの実行
• ガントレットテスト（厳密なシナリオ系）
• バージョン情報の記録

生成された証拠は

.scratch/release/0.1/

開発ワークフロー

PR を提出する前に以下のゲート通過が必須です：

eval "$(opam env)"
opam exec -- dune build @all
opam exec -- dune runtest
opam exec -- dune fmt
git diff --exit-code

ゴールドハッシュの更新: コーパスファイルを追加した際は、以下のコマンドでテスト用データを再生成してください。

opam exec -- dune exec test/gen_goldens.exe

CI/CD ワークフロー (GitHub Actions)

1. CI / 開発ゲート: PR や main ブランチに対して、ビルド・全テスト・フォーマットチェック・リリースドキュメントの存在確認を実行。
2. リリースエビデンス: リリースブランチに対して

   scripts/release/reproduce-0.1.sh

   を実行し、結果をアップロード。
3. リリースバイナリ: タグ時に Linux/macOS ビンaries とソースアーカイブを公開。

詳細は

docs/ci-cd.md

ライセンスと所有権

• ライセンス: Apache License, Version 2.0
• コードの所有権: Jacquard は記述、レビュー、コンパイルしたという事実だけで、ソースに対する著作権を主張しません。あなたのプログラムはあなたのものです。
• 例外規定: コンパイルされた出力やランタイムを含めたネイティブバイナリであっても、ユーザープログラムおよび生成物が独自のライセンス（プロプライエタリ等）を使用することを明示的に許可します。

Jacquard の名称とアイデンティティは

TRADEMARKS.md