David BlackmanとSebastiano Vignaが2018年に設計した疑似乱数生成器(PRNG)。Xorshift系列(XORとビットシフトの組み合わせで状態を更新するLFSRベースの高速な生成器群)の精神的後継にあたる。名前は各ラウンドを構成する3つの基本操作、XOR・SHIft・ROtateに由来する。

仕組み

256bit(64bit×4ワード)の内部状態を持つ。各ラウンドで、状態配列の各ワードを別のワードとXORし、シフトした値を次の要素にXORし、最後のワードをローテートする、という操作を経て次の状態に遷移する。状態遷移関数自体はGF(2)上で線形だが、出力段に非線形なスクランブル関数(名前の"**“は出力に2回の乗算を使うスクランブル方式を表す)を挟むことで、単純な代数攻撃を防いでいる。

周期と並列化

周期は2²⁵⁶ − 1。2¹²⁸刻みでジャンプ可能なため、独立した部分系列を多数切り出して並列計算に使える点はPhiloxと共通するが、Philoxが「カウンタ+鍵」から無記憶に出力を計算するのに対し、Xoshiro256**は状態を逐次更新しながらジャンプ操作で系列を分割する設計。

疑似乱数生成器の中での位置づけ

Mersenne Twisterの後継世代の一つで、PCGと並び高速・高品質・小さな状態サイズを両立する現代的なPRNG。設計思想はXorshift系列の発展形(XOR+shift+rotate)であり、LCG+permutationのPCG、カウンタベースのPhiloxとはアプローチが異なる。

#random

出典

• Xoshiro256** - RandomGen
• A PRNG shootout
• Open-Source PRNG Algorithm Libraries: Xoshiro vs PCG vs SplitMix vs Mersenne Twister | Pi Stack

TypeScriptコードをESLintでlintできるようにするツール群（パーサーとプラグインのモノレポプロジェクト）。ESLint本体はJavaScriptのみを解釈するため、TypeScript対応はこのプロジェクトがプラグインとして担っている。 #javascript #typescript

TSLintからの移行

かつてTypeScriptにはTSLintという専用リンターがあったが、2019年に非推奨（deprecated）となり、公式にtypescript-eslintへの移行が推奨された。以降、JavaScript/TypeScript両方のlintをESLintエコシステムに一本化するのが標準になっている。移行用に設定変換ツール（tslint-to-eslint-config）も提供された。

type-aware linting（typed linting）

typescript-eslintの特徴的な機能が、TypeScriptコンパイラの型情報を使ってコードを検査する「型認識lint（type-aware linting / typed linting）」。型情報がないと検出できない問題（例: Promiseのawait忘れ）を検出できる。ただしlint前にTypeScriptによるプロジェクトのビルド相当の処理が必要になるため、性能上のコストがかかる。

Biome v2が「TypeScriptコンパイラに依存しない型認識lint」を打ち出しているのは、このコストへの対案という文脈。

JavaScriptのリンター・フォーマッターの中での位置づけ

ESLintのプラグイン機構の上に成立している拡張であり、ESLintエコシステムの代表例。Biomeのリンターが搭載するルールの由来元のひとつでもある。

出典

• typescript-eslint
• What About TSLint? | typescript-eslint
• Typed Linting: The Most Powerful TypeScript Linting Ever | typescript-eslint

#math

関数を、1点での微分係数の情報だけを使って多項式（冪級数）で表現する手法。

点 a を中心に展開したものをテイラー級数、特に a = 0 を中心にしたものをマクローリン級数と呼ぶ。

直感 — 接線近似の高次版

微分による一次近似 f(a+h) \approx f(a) + f'(a)h（接線で代用する）の精度を、2次・3次…の項を足して上げていったもの。1次で「傾き」、2次で「曲がり具合」、と高階の導関数が形の情報を順に補っていき、次数を上げるほど元の関数に近づく。

剰余項と収束

有限次で打ち切ったテイラー多項式と元の関数との差が剰余項 R_n(x)。剰余項が n \to \infty で 0 に収束する範囲でのみ、テイラー級数は元の関数に一致する。e^x, \sin x, \cos x は全実数で収束する代表例。

用途

• 数値計算 — 関数電卓やライブラリが \sin や e^x を計算する際の基礎（実装では精度最適化した多項式近似が使われるが、発想の原点）
• 物理の近似 — 「\theta が小さいとき \sin\theta \approx \theta」のような微小量近似は、テイラー展開を1次で打ち切ったもの
• オイラーの公式 — e^{ix}, \cos x, \sin x のマクローリン級数を見比べると e^{ix} = \cos x + i \sin x が導ける。フーリエ変換の核 e^{-i\omega t} の背後にある関係式

出典

• Taylor and Maclaurin Series - UTSA
• Taylor’s Theorem with Remainder and Convergence - Lumen Learning
• An introduction to Taylor series and their applications - Parabola (UNSW)

#llm #ai #security #watermarking #google

Google DeepMind によるLLMテキスト電子透かしの本番実装。論文 “Scalable watermarking for identifying large language model outputs” は Nature（2024-10）に掲載された。生成テキスト透かしを大規模本番運用した初の事例で、Gemini / Gemini Advanced 上で数百万ユーザー規模で稼働した。

Tournament sampling

中核のアルゴリズム。次トークンを決めるときに:

1. 元の分布から候補トークンを複数サンプリングする
2. 候補をペアにして、秘密鍵由来の疑似乱数関数（PRF）のスコアが大きい方を勝ち残らせる
3. これをL層のトーナメントとして繰り返し、最後に残ったトークンを出力する

基礎に本物のサンプリングが残っているため「同じプロンプトでも毎回違う応答」という多様性が保たれる。Gumbel-max系のdistortion-free手法が抱える出力の決定化問題を回避しつつ、設定次第で:

• 非歪曲（non-distortionary）: 出力分布を保存し品質劣化なし
• 歪曲（distortionary）: 品質を少し犠牲にして検出力を上げる

の両モードを選べる。論文では両カテゴリで既存手法（KGW系・Gumbel系）より検出力が高いことを示した。

実運用上の特徴

• 学習には一切手を入れず、サンプリング手順だけを差し替える
• 検出はLLM本体を使わず軽量に実行できる
• 約2,000万件の本番トラフィックでの人間フィードバック評価で品質劣化なしを確認
• 実装はオープンソース化されており、Hugging Face Transformers にも組み込まれている

LLMテキストの電子透かしの中での位置づけ

ロジット操作型（KGW法）とサンプリング置換型（Gumbel-max）の長所を統合した実用システム。ただしトークン表層の偏りに依存する点は変わらず、強い言い換え・翻訳への耐性は限定的。

出典

• Scalable watermarking for identifying large language model outputs (Nature, 2024)
• On Google’s SynthID-Text LLM Watermarking System: Theoretical Analysis and Empirical Validation (2026) — 第三者による理論解析

もともとはOpenAPI仕様そのものの名前だったが、2016年のOpenAPI Initiativeへの寄贈・改称後は、SmartBearが保守・提供するAPI開発ツール群のブランド名として使われている。

創始者

2011年、辞書サイトWordnikの技術共同創業者Tony TamがSwagger APIプロジェクトを作成した。WordnikのAPI開発において、APIドキュメントの自動生成とクライアントSDK生成の手間が大きな課題になっていたことが動機。

仕様としてのSwagger: Swagger 2.0

OpenAPI Initiativeへ寄贈される前の最終仕様バージョンが2014年リリースのSwagger 2.0で、今も"Swagger 2.0"あるいは"OpenAPI 2.0"と呼ばれる。詳しいバージョン変遷はOpenAPIを参照。

ブランドとしてのSwagger: SmartBearのツール群

現在SmartBearが保守・開発するOSSツール群にも"Swagger"の名が残っている。

• Swagger UI / Swagger Editor — API可視化・設計エディタ
• Swagger Codegen — APIクライアントSDK・サーバースタブ生成の元祖ツール。OpenAPI 3.0に対応し、現在もOSSとして更新が続いている。openapi-generatorは2018年にこのプロジェクトからコミュニティ主導でforkされたもの
• SwaggerHub — 商用のAPI設計・コラボレーションプラットフォーム。エディタでの入力補完・スタイルバリデーターに加え、API分析・監視・テスト・バージョン管理・APIモッキング、共通OAS構文を複数API間で再利用する「Domains」機能などを統合している

名称の整理

「OpenAPI」が仕様そのものを指し、「Swagger」がSmartBearのツール群・製品ブランドを指す、という使い分けが現在の一般的な理解。OpenAPI関連ツールエコシステムの中では、Swagger系ツールはSmartBear傘下（買収後はSpectral・Prismも同傘下）という位置づけになる。

#openapi #api-documentation

出典

• Swagger (software) - Wikipedia)
• Swagger Codegen - SoftwareOne Marketplace
• SwaggerHub - GetApp

決定的なアルゴリズムによって、統計的にはランダムに見える数列を生成する仕組み(PRNG)。設計思想・状態の持ち方・並列化のしやすさで系統立てて整理できるため、代表的なアルゴリズムをまとめるハブノート。

状態逐次更新型

• Mersenne Twister — 1997年発表。624×32bitの大きな内部状態を「twist」操作で更新する。長らくの標準だったが、LinearComp検定の失敗など弱点も知られる。
• PCG — 線形合同法(LCG)に出力permutationを加えた設計。状態サイズが小さく(典型64bit)、Mersenne Twisterより高速。
• Xoshiro256** — Xorshift系列の後継。XOR・シフト・ローテートで256bit状態を更新し、非線形な出力スクランブルを加える。2¹²⁸刻みでジャンプ可能。

カウンタベース型

• Philox — 「カウンタ+鍵」のみを状態として持ち、暗号学的ハッシュに似た関数で直接出力を計算する無記憶な設計。任意のインデックスに直接ジャンプできるため並列計算との親和性が最も高く、TensorFlowのデフォルト生成器に採用。

選び方の傾向

状態逐次更新型(Mersenne Twister/PCG/Xoshiro256)は汎用用途で使われ、中でもPCG・Xoshiro256はMersenne Twisterより高速・高品質な後継として置き換えが進んでいる。カウンタベース型のPhiloxは、GPU/分散環境で「どのスレッドがどの範囲の乱数を生成するか」を厳密に制御したい場面(大規模並列シミュレーション、機械学習フレームワーク)で選ばれる。

#random #moc

カウンタベース(counter-based)方式の疑似乱数生成器(PRNG)。2011年にJohn Salmonら(D. E. Shaw Research)が発表したRandom123ライブラリに含まれる生成器の一つ。

仕組み

一般的なPRNGが内部状態を逐次更新しながら次の乱数を作るのに対し、Philoxは「カウンタ」と「鍵(key)」という2つの値だけを状態として持ち、それを暗号学的ハッシュに似た(が弱い)ブロック暗号風の関数に通して直接出力を得る。カウンタは乱数を1つ生成するたびに1ずつインクリメントされ、鍵は生成される数列そのものを決定する。異なる鍵を使えば別々の(統計的に独立とみなせる)数列が得られる。

暗号用途には向かないとされる一方、GPU上でCrush系の統計検定に耐える生成器としては最速級と言われている。

並列計算との親和性

カウンタ方式であるため、必要な乱数の個数が分かっていれば生成サイクルの任意の位置に直接ジャンプできる。jumpedメソッドで2¹²⁸個生成した状態相当に一気に進める、といった操作も可能。Mersenne TwisterやPCG、Xoshiro256**のように状態を逐次更新する系列だとストリームの分割・並列化が難しいのに対し、Philoxはインデックスさえ決まれば各スレッド/GPUコアが独立に計算できる。

この特性から、GPU/大規模並列計算との親和性が高く、TensorFlowのデフォルト乱数生成器として採用されている。NumPyのnumpy.random.Philoxなどでも利用可能。

疑似乱数生成器の中での位置づけ

状態を持たず「カウンタ+鍵→出力」という無記憶な設計思想を取る点で、Mersenne Twister・PCG・Xoshiro256**といった状態逐次更新型の系列とは根本的に異なるアプローチ。並列化のしやすさを最優先する用途(GPU計算、分散シミュレーション)で選ばれる。

#random #parallel-computing

出典

• Philox counter-based RNG — NumPy Manual
• Philox Counter-based RNG - RandomGen

線形合同法(LCG)を状態遷移関数として使い、出力段に「permutation(並べ替え)」処理を加えることでLCGの弱点を補う設計の疑似乱数生成器(PRNG)。PCG, A Family of Better Random Number Generatorsとして公開されている。

仕組み

単純なLCGは下位ビットの周期が短い・統計的な規則性が現れやすいといった弱点を持つ。PCGはLCGの生の出力をそのまま返すのではなく、下位ビットを捨てたうえで追加のpermutation関数を通して出力することで、内部状態よりもはるかにランダムに見える出力を作る。

状態サイズと性能

状態サイズは典型的に64bitと、Mersenne Twister(624×32bit)やXoshiro256**(256bit)と比べて小さい。32bit出力の生成速度でMersenne Twisterの2〜5倍(35Gb/s超 vs MTの13〜27Gb/s)というベンチマークが報告されており、Mersenne TwisterからPCGへ置き換えることでシミュレーションの実行時間が20〜40%短縮された事例もある。

Philoxと同様、暗号強度は主張しない「medium-strength」の生成器に分類される。

疑似乱数生成器の中での位置づけ

Mersenne Twisterの弱点(状態サイズの大きさ、LinearComp検定の失敗)を踏まえた後継世代の一つ。設計思想は「LCG+出力permutation」というシンプルなもので、Xoshiro256**(XOR+shift+rotate)やPhilox(カウンタベース)とは異なるアプローチで高速・高品質を両立している。

#random

出典

• PCG, A Family of Better Random Number Generators
• Permuted congruential generator — Grokipedia
• Open-Source PRNG Algorithm Libraries: Xoshiro vs PCG vs SplitMix vs Mersenne Twister | Pi Stack

JavaScriptエコシステムのOSSプロジェクトをホストする非営利財団。2019年3月にNode.js FoundationとJS Foundationが合併して発足した。Linux Foundation傘下のサブファウンデーションとして運営されている。 #javascript #oss

系譜

複数の財団の合併を重ねてできた組織。

ホストするプロジェクト

Node.js・jQuery・webpack・Appium・Node-RED・ESLint・Electronなど、約38のOSSプロジェクトをホストする（2025年時点）。設立時のメンバーにはGoogle・Microsoft・IBM・PayPal・GoDaddy・Joyentなどが名を連ねる。ドイツのSovereign Tech Fundから80万ユーロ超の資金提供を受けるなど、公的資金によるOSS支援の受け皿にもなっている。

役割

特定企業に属さない中立的な組織としてプロジェクトの商標・ガバナンスを引き受け、JavaScriptエコシステム全体の持続的な成長を支えることを使命とする。個人が始めたプロジェクトが広く使われるようになったとき、その資産（商標など）と運営を引き継ぐ受け皿として機能している（例: ESLintは2016年にjQuery Foundationに参加し、合併を経て現在はOpenJS Foundation傘下）。

出典

• OpenJS Foundation - Wikipedia
• Node.js Foundation and JS Foundation Merge to Form OpenJS Foundation - Linux Foundation
• OpenJS Foundation

Linuxカーネルの機能で、プロセスグループごとに独立したネットワークスタックを持たせる分離技術。カーネル内部では各namespaceインスタンスがstruct netで表現される。プロセス・ファイルシステム・IPCなどを分離する他のnamespace種別と並ぶ、Linux namespaces機構の一種。cgroups（control groups）によるリソース制御と組み合わせてLXCなどの軽量仮想化の基盤にもなっている。 #network #linux #kernel

namespaceごとに独立して管理されるもの

• ネットワークインターフェース（lo, eth0など）
• ルーティングテーブル（IPv4/IPv6）
• iptables/nftablesのファイアウォール設定
• netfilterの接続追跡状態
• Unixドメインソケットの名前空間
• ポート番号空間（0-65535）
• /proc/net/以下のビュー

初期化時にpernet_operationsフックを通じて、各サブシステムがper-namespace状態を初期化する。

管理コマンド: ip netns

ip netns add ns1                        # 名前空間を作成
ip netns exec ns1 <cmd>                  # 名前空間内でコマンド実行
ip link set <iface> netns ns1            # 既存インターフェースを移動
ip netns del ns1                         # 削除

veth pairによる接続

異なるnamespace同士やnamespaceとホストを繋ぐ標準的な手段がveth pair（仮想Ethernetペア）。片方に入れたフレームがもう片方から出てくる「パイプ」のように振る舞う。ペアの一端をnamespace Aに、もう一端をnamespace Bやホストに配置して接続する。実際に構築した例では、veth pairで複数のnamespaceをLinuxブリッジに接続した。

unprivileged user namespaceとの組み合わせ

unshare --user --map-root-user --netのようにuser namespaceと組み合わせることで、sudoなしでもnetwork namespaceを作成・操作できる。ただし作成したnamespaceはホストの実NICには触れられない。

出典

• Network Namespaces - Linux Kernel Internals
• Linux Network Namespaces: Isolate Network Stacks | Command in Line

1997年に松本眞・西村拓士が発表した汎用疑似乱数生成器(PRNG)。名前は周期が2¹⁹⁹³⁷ − 1というメルセンヌ素数(2^p − 1の形の素数)であることに由来する。

仕組み

内部状態として624個の32bit整数からなる配列を持つ。乱数を1つ要求されるたびに状態配列から1要素を取り出して出力用の変換を施し、624個出力し終えるごとに「twist」と呼ばれる操作で状態配列全体を更新する(アルゴリズム名の由来)。1回の生成コストはO(1)。

統計的品質と評価の変化

長らく「強いPRNG」(長い周期と統計的に一様な分布)の代表例として扱われ、Python3のrandomモジュールをはじめ多くの言語・環境の標準乱数生成器に採用されてきた。一方で、TestU01のLinearComp検定(80番・81番)には一貫して落ちることが知られており、線形性に起因する弱点を持つ。近年はPCGやXoshiro256**など、より高速かつ統計的品質の高い後継世代への置き換えが進んでいる。

内部状態サイズと並列化

内部状態が624×32bit(約2,503バイト)と大きく、PCG(典型64bit)やXoshiro256**(256bit)と比べてコピーコストが高い。状態を逐次更新する設計のため、Philoxのようにストリームの任意位置へ直接ジャンプすることはできず、並列計算での分割利用には工夫が要る。

疑似乱数生成器の中での位置づけ

CBRNG以前の世代を代表する、状態逐次更新型PRNGの標準的な選択肢だった。現在は速度・状態サイズ・並列化のしやすさの面でPCG・Xoshiro256**・Philoxといった後継世代に置き換わりつつある。

#random

出典

• Mersenne Twister — Wikipedia
• Open-Source PRNG Algorithm Libraries: Xoshiro vs PCG vs SplitMix vs Mersenne Twister | Pi Stack

Anton Kovalyov氏が2011年にJSLintをフォークして作ったJavaScriptリンター。フォークの動機は「JSLintは不快なほどオピニオン化していた（uncomfortably opinionated）」というもので、JSLintが許さなかったルールのカスタマイズをコミュニティ主導で可能にした。 #javascript

ライセンス問題の継承と解消

フォーク元のJSLint由来のコードに「Good, not Evil」条項（詳細はJSLint参照）が残っていたため、JSHintも長年Free Software Foundationから非フリー扱いされていた。2020年8月に該当コードをすべて置き換えて完全なMITライセンスとなり、問題が解消された。

JavaScriptのリンター・フォーマッターの中での位置づけ

JSリンター系譜の中間世代。JSLintの「設定不可」への反発から生まれたが、独自ルールの追加はできず、その制約への不満からESLintが生まれた。「設定可能」（JSHint）から「プラガブル」（ESLint）への進化の途中段階といえる。

出典

• JSHint - Wikipedia
• JSLint - Wikipedia

CPUのプログラム可能なインターフェースを定義する抽象モデル。ソフトウェアがハードウェアとどう相互作用するかを規定し、命令・データ型・レジスタ・アドレッシングモード・仮想メモリ・メモリ一貫性機構などを含む。ARM自身の用語集も「プロセッサのハードウェアとその上で動くソフトウェアの間の抽象インターフェース」と定義しており、ハードウェアとソフトウェアの境界を成すという位置づけで一致する。

仕様と実装の違い

ISAはマイクロアーキテクチャ(特定プロセッサでの実装技法)と明確に区別される。異なるマイクロアーキテクチャが同一のISAを共有できる点が重要で、例えばIntel PentiumとAMD Athlonは内部設計が全く異なるが、ほぼ同一のx86 ISAを実装している。

CISCとRISCの対立

「CISC」という語は「RISCに対する対比として遡及的に作られた」呼称。1970年代半ば、IBM Watson研究所のJohn CockeらによるIBM 801プロジェクトがRISC思想の先駆けとなり、1980年代前半にUC BerkeleyのDavid PattersonとDavid Ditzelが命令を単純化し固定長・レジスタ間演算中心の設計を提唱、論文"The Case for the Reduced Instruction Set Computer"(1980年)で"RISC"という語を作った。1980年代半ばにはDECの試算で「RISCの価格性能比はCISCの最大2倍」との評価が出て、SunがMotorola 68000からSPARCへ移行するなど業界に影響を与えた。

RISC-Vの設計批判で論じられている「オプション性」「命令エンコーディング」の問題は、いずれもこのRISC系ISA設計における一般的な論点(拡張の持たせ方、命令長の固定/可変)の具体例にあたる。

オプショナルな命令セット拡張

ISAは「命令や機能を追加して拡張可能であり、拡張版の実装は拡張前のコードも実行できるが、拡張命令を使うコードは対応実装でしか動かない」という一般原則がある。実例:

• x86: SSE/AVXはCPUID命令でランタイム検出する拡張機能。
• ARM: NEON(SIMD拡張)はARMv7-A/RおよびArmv8-R AArch64でオプション扱い。
• RISC-V: ベース整数ISA(RV32I/RV64Iなど)にM(乗除算)・A(アトミック)・F/D(浮動小数点)などの標準拡張を任意に組み合わせるモジュール式設計。IMAFD一式は"G"と略称される。

命令エンコーディングのトレードオフ

固定長命令は「キャッシュラインや仮想メモリページ境界をまたぐかの判定が不要」など単純で高速化しやすい一方、x86は1〜15バイトの可変長命令(プレフィックス・opcode・ModRM・SIB・displacement・immediateの可変構成)で、スーパースカラ実行時の命令境界検出が課題となる。圧縮命令セットの例として、ARM Thumbは32ビット命令2個を1ワードにパックしデコード時に展開する方式、RISC-VのC拡張(16ビット圧縮命令)は32ビット命令と自由に混在させ、コードサイズを25〜30%削減する。

出典

• Wikipedia: Instruction set architecture
• ARM: What is Instruction Set Architecture (ISA)?
• Wikipedia: Complex instruction set computer
• Patterson & Ditzel, “The Case for the Reduced Instruction Set Computer” (1980)
• ARM: Neon
• RISC-V ISA Manual — Standard Extensions
• RISC-V “C” Extension for Compressed Instructions
• OSDev Wiki: x86-64 Instruction Encoding

#isa #cpu-architecture

関数型プログラミングの国際会議 ICFP (International Conference on Functional Programming) の併設コンテストとして、1998年から毎年6〜7月頃に開催されている国際プログラミングコンテスト。結果はICFP会議の場で発表される。 #competitive-programming #functional-programming

名前が似ている ICPC とは別物で、性格もまったく違う。

競技形式

• 制限時間: 72時間。最初の24時間で締め切られる Lightning Division も併設される
• チーム人数: 無制限。参加費無料でインターネット経由で参加する
• 使用言語: 完全に自由
• 賞: 優勝チームには賞金ではなく、使用した言語が “the programming tool of choice for discriminating hackers” であると宣言される、いわゆる bragging rights（自慢する権利）が与えられる。言語・ツールの実力を示す場という側面が強い

問題の性格

ICPC のような整ったアルゴリズム問題の早解きではなく、毎年持ち回りの主催者が用意する一発ネタの大規模課題を72時間かけて攻略する総合戦。リバースエンジニアリング・最適化・謎解きなどの要素が混ざることが多い。

有名な回として、2006年のCMU主催回「The Cult of the Bound Variable」がある。仮想機械 UM-32 の仕様書とディスクイメージだけが渡され、VMを実装して起動すると架空のOS「UMIX」のログイン画面が現れ、その中に複数の課題と謎解きが仕込まれている、という凝った構成だった。365チーム・700人が少なくとも1つの課題を解いた。

ICPCとの対比

日本チームの活躍

秋葉拓哉氏らの Team Unagi が通算7回優勝している常勝チーム（2013・2015・2019・2024・2025年など）。2019年・2024年はRustを使用して優勝しており、"Rust is the programming language of choice for discriminating hackers" が宣言された。2025年は Sakana AI の進化的コード生成ツール ShinkaEvolve を人間の競技者と組み合わせて優勝したことが話題になった。

出典

• ICFP Programming Contest - Wikipedia
• ICFP Programming Contest (icfpconference.org)
• Team Unagi
• ShinkaEvolve in Action — Sakana AI
• The Cult of the Bound Variable: The 9th Annual ICFP Programming Contest (CMU)

#math #machine-learning

微分可能な関数の（局所）最小値を反復計算で探す最適化アルゴリズム。機械学習で損失関数を最小化するパラメータを求める際の基本手法。

勾配 \nabla f は微分係数の多変数版（各変数での偏微分を並べたベクトル）で、「その点で関数が最も急に増える方向」を指す。その逆方向に少しずつ進めば関数値が下がっていく、というのが全体のアイデア。霧の中で山を下るとき、足元の傾きだけを頼りに一番急な下り方向へ一歩ずつ進むのに例えられる。

学習率

ステップ幅を決める係数 \eta を学習率と呼ぶ。代表的なハイパーパラメータで、トレードオフがある。

• 小さすぎる — 収束までの反復回数が膨大になり学習が遅い
• 大きすぎる — 最小値を飛び越えて振動・発散する

バリエーション

勾配を計算するときに使うデータ量で分類される。

• バッチ勾配降下法 — 全訓練データで勾配を計算。正確だが1ステップが重い
• 確率的勾配降下法（SGD） — 1サンプルだけで勾配を近似。1ステップが軽く、ノイズが局所解からの脱出に効くこともある
• ミニバッチ勾配降下法 — 小さなサブセットで勾配を近似する折衷案。深層学習の実務ではこれが標準

学習率を自動調整する発展形として Momentum、AdaGrad、Adam などがある。

機械学習との関係

ニューラルネットワークの学習は「損失関数をパラメータで偏微分した勾配を誤差逆伝播法（backpropagation）で効率よく計算し、勾配降下法でパラメータを更新する」の反復。導関数が 0 になる点を解析的に解けない巨大な関数でも、勾配さえ計算できれば数値的に最小化へ向かえるのがポイント。

出典

• What Is Gradient Descent? - Built In
• What is Learning Rate in Machine Learning? - IBM
• A Guide to Gradient Descent and Stochastic Gradient Descent - Medium

#math

未知の関数とその導関数（微分）の間の関係を記述した方程式。普通の方程式の解が「数」なのに対し、微分方程式の解は「関数」になる。「変化のルール（変化率）から挙動そのもの（関数）を復元する」問題であり、物理・工学でのモデル記述の基本言語。

例

• 指数増殖 — \frac{dy}{dt} = ky（増加率が現在量に比例）。解は y = Ce^{kt}。人口増加・放射性崩壊・複利
• ニュートンの冷却法則 — \frac{dy}{dt} = k(A - y)（温度差に比例して冷める）
• 減衰振動 — m\frac{d^2x}{dt²} + c\frac{dx}{dt} + kx = f(t)。バネ・ダンパー系や RLC 回路がこの形

分類

• 常微分方程式（ODE） — 未知関数が1変数で、通常の導関数だけを含む。1次元の力学系のモデルに多い
• 偏微分方程式（PDE） — 未知関数が多変数で、偏導関数を含む。熱・波動・流体・電磁気・量子力学など、空間的な広がりを持つ系のモデルに多い
• 階数（order） — 含まれる導関数の最高階。上の冷却法則は1階、減衰振動は2階
• 線形/非線形 — 未知関数とその導関数について線形かどうか。線形なら解の重ね合わせが効き、理論が整っている

解き方

• 解析的に解く — 変数分離などの求積法（積分に帰着させる）、ラプラス変換（微分を代数演算に変えて機械的に解く）、フーリエ変換（偏微分方程式向き）など。ただし解析解が求まるのは限られたクラスだけ
• 数値的に解く — オイラー法・ルンゲクッタ法などで数値解を計算する。実務ではこちらが主流

出典

• Differential Equations - Definitions - Paul’s Online Notes (Lamar University)
• Classification of differential equations - University of Victoria
• Definitions and important facts regarding ODEs and PDEs - UBC

カスタムリソースとコントローラを組み合わせて、特定のアプリケーション（とその構成要素）を管理するKubernetesの拡張。「人間の運用者（operator）がサービスを管理するときに持っている知識」をコードにして自動化する、というのが名前の由来。 #kubernetes #infrastructure

構成要素

• カスタムリソース — 管理対象の設定を表す独自の型（例: SampleDB）
• コントローラ — そのカスタムリソースをwatchしてreconcileする。Kubernetes APIのクライアントとしてPodで動く
• Kubernetes本体のコードは一切変更しない。

公式ドキュメントのSampleDBの例では、Operatorが次をやる:

• ストレージ用のPersistentVolumeClaimを作る
• DBインスタンスをStatefulSetで動かす
• 初期設定をJobで流す
• 定期的にバックアップ用のPodを動かす
• DBのバージョンアップを自動で行う

ユーザー側はこれだけ:

kubectl get SampleDB                   # 設定済みのDB一覧
kubectl edit SampleDB/example-database # 設定を変える

Operatorで自動化されがちなこと

• アプリケーションのデプロイ
• バックアップの取得・リストア
• スキーマ移行を伴うアップグレード
• Kubernetes外のAPIをServiceとして公開する
• 障害のシミュレーション（耐障害性テスト）
• 分散アプリケーションのリーダー選出

実装フレームワーク

• kubebuilder（Go）
• Operator Framework（Operator SDK）
• Kopf（Python）
• Java Operator SDK
• KubeOps（.NET）
• kube-rs（Rust）
• Metacontroller（webhookベース）

歴史

2016年にCoreOSが提唱した。

「コントローラ」と「Operator」の違い

• コントローラ: 制御ループ一般。Deployment/Jobなどの組み込みのものも含む。
• Operator: カスタムリソース + それ専用のコントローラで、特定アプリの運用知識を詰め込んだもの。いわば「コントローラの使い方の一パターン」。
• 厳密な線引きがあるわけではなく、カスタムリソース用のコントローラなら何でもOperatorと呼ばれることも多い（ピザを注文するコントローラなど、Kubernetesのカスタムリソース（CRD）参照）。

Kubernetes拡張まわりの用語整理の中での位置づけ

CRDとコントローラの組み合わせ方の一パターン。用語としては一番上位（CRD・CR・コントローラをすべて含む）。

出典

• Operator pattern | Kubernetes
• Introducing Operators - CoreOS (archive)

CRD・CR・コントローラ・Operator・reconcileあたりの用語が混ざりやすいので、関係を一枚にまとめるハブノート。深掘りは各ノートで。 #kubernetes #moc

用語

関係の要点

• CRDだけでは何も起きない（データが保存されるだけ）。動かすのはコントローラ。
• 組み込みリソース（Deploymentなど）も、組み込みのコントローラが動かしているだけで、構造はCRと同じ。
• 「CRD + コントローラ」で特定アプリを管理するものがOperator。
• この仕組みをクラスタ自体に当てはめたのがCluster API、クラウド連携部分を切り出したのがCloud Controller Manager。

親ハブ: Kubernetes

クラスタの状態をwatchし、「実際の状態（current state）」を「望ましい状態（desired state）」に近づける変更を行い続けるループ。Kubernetesの動作はほぼ全部これの組み合わせでできている。 #kubernetes #infrastructure

公式ドキュメントのたとえ: サーモスタット

• 設定温度 = 望ましい状態
• 室温 = 実際の状態
• サーモスタットが暖房をON/OFFして室温を設定温度に近づける = コントローラの動作

この「差分を見て埋める」1回分の処理を reconcile（突き合わせ）と呼び、それを繰り返すのが 制御ループ（control loop） / reconcileループ。

spec と status

• コントローラは最低1種類のリソースを追跡し、その spec フィールドを望ましい状態として読む。
• 実際にやったことの結果は status に書き戻す。
• ユーザーは spec を書くだけ、status はコントローラが書く、という役割分担。

例: Jobコントローラ

• 新しい Job オブジェクトをwatchする（望ましい状態）
• 仕事を実行する Pod を作る（コンテナを自分で動かすわけではなく、API server経由で他のコンポーネントに任せる）
• 終わったら Job の status を更新する

「あるリソースを望ましい状態として読み、別のリソースを作って実現する」という分離が基本形。DeploymentコントローラもJobコントローラもPodを作るが、ラベルで自分の管理対象を区別しているので干渉しない。

2つの制御方式

1. API server経由（大半）— JobコントローラのようにKubernetesのオブジェクトを作って間接的に実現する。
2. 外部を直接操作 — クラスタ外のシステムを直接叩く。ノードを増やすオートスケーラーや、Cloud Controller ManagerのようにクラウドのAPIを叩くもの。

どこで動いているか

• Deployment / Job / ReplicaSet などの組み込みコントローラは kube-controller-manager の中でまとめて動く。
• クラウド連携系はcloud-controller-managerに分離されている。
• 自作のコントローラは普通のPodとしてクラスタ内で動かす。カスタムリソースと組み合わせたものがOperator。

設計上のポイント

• 巨大な1つのループではなく、それぞれが1つの側面を担当する小さなコントローラを多数動かす。
• クラスタは常に変化しているので、完全に安定した状態に到達しないこともある。コントローラが動いて有用な変更を続けていればそれでよい、という考え方。
• 同じパターンをクラスタそのものに適用したのがCluster API。

Kubernetes拡張まわりの用語整理の中での位置づけ

Kubernetesを動かす仕組みの中核。CRDは「型」、コントローラは「それを動かす処理」、Operatorは「その組み合わせ方の一パターン」という関係。

出典

• Controllers | Kubernetes

CustomResourceDefinition (CRD) を登録すると、Kubernetes APIに独自の型（Kind）を追加できる。登録した瞬間から kubectl get/apply/delete やwatchが組み込みリソースと同じように使える。実体は「スキーマ付きのJSONをetcdに保存し、REST APIで出し入れする仕組み」。 #kubernetes #infrastructure

CRDとコントローラは別物

用語の関係はKubernetes拡張まわりの用語整理に整理。

• CRD単体はただのデータ置き場。オブジェクトを作っても何も起きない。
• 現実に何かを起こすのはコントローラ（Operator）で、CRを watch して「望ましい状態（spec）」に「実際の状態」を近づけるreconcileループを回し、結果を status に書き戻す。
• なので「何でも登録できるか」の答えは、データとしてはJSONで書けるものなら大体何でも可。何を起こせるかはコントローラ次第で、クラスタ外の物理世界でも構わない（後述のピザ）。

カスタムリソースで管理するメリット

Kubernetes APIの機能がタダで付いてくる

CRDを登録するだけで組み込みリソースと同じ機能が使える。認証・認可・永続化・CLIを自作しなくてよい。

宣言的に管理できる

• ユーザーは spec（望ましい状態）を書くだけで手順は書かない。
• コントローラがreconcileし続けるので、手で壊されても元に戻る（自己修復・ドリフト修正）。
• 結果は status に出るので状態確認の方法が統一される。

複雑なものを1枚のYAMLに抽象化できる

apiVersion: example.com/v1
kind: Database
metadata:
  name: my-database
spec:
  engine: PostgreSQL
  version: "14"
  replicas: 3

これだけでStatefulSet・PVC・Service・バックアップJobなどが作られる、という形にできる。運用知識をコントローラ側に閉じ込め、利用者にはシンプルな入口だけ見せる。これがOperatorの価値。

既存エコシステムに乗る

• Argo CD / FluxのようなGitOps、Helm、kustomizeで他のマニフェストと同じように扱える。
• アプリもDBも証明書もクラウドリソースも、同じkubectlとYAMLで扱えるという統一感が一番大きい。

向かないケース・導入時の注意

公式ドキュメントでは、宣言的APIに当てはまらないものは独立したAPIサーバーにすることを勧めている。宣言的APIの特徴は:

• 小さなオブジェクトが比較的少数
• アプリやインフラの設定を表す
• 更新頻度が低い
• 人間が読み書きする
• 主な操作がCRUDで、オブジェクトをまたぐトランザクションが不要

逆に次のようなものは向かない:

• 「これやって」と頼んで同期的に結果を待つRPC的な操作、IDを返して別途ステータスを聞きに行く操作
• 1オブジェクト数kB超、または数千個以上のオブジェクト（サイズ上限は後述の「制約」参照）
• 毎秒数十リクエストのような高頻度アクセス
• エンドユーザーのデータ（画像・個人情報など）
• CRUDで表せない操作、オブジェクトとしてモデル化しにくいもの

ConfigMapとの使い分け

• ConfigMap — mysql.cnf のような既存フォーマットの設定ファイルを丸ごと入れ、Pod内のプログラムがファイルや環境変数として読むだけの場合。設定変更時にDeploymentのローリングアップデートで反映したい場合。
• カスタムリソース — kubectlのトップレベルで扱いたい、変更をwatchして他のオブジェクトを作る自動化をしたい、spec/status の慣習に乗りたい、複数リソースをまとめて抽象化したい、ドメイン固有のバリデーションが欲しい場合。

導入時のコスト

• コントローラという新しいコードがクラスタ内で動くので、それ自体の監視・トラブルシュートが必要になる。暴走するとクラスタの安定性に影響する。
• データはetcdに入るので、バックアップ・リストア計画とストレージ負荷を考える。
• 誰が作成・変更できるかのRBAC設計、spec内の機密情報の扱いを考える。

定義の例（公式ドキュメントのCronTab）

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com   # <plural>.<group> でなければならない
spec:
  group: stable.example.com
  versions:
    - name: v1
      served: true
      storage: true
      schema:
        openAPIV3Schema:
          type: object
          properties:
            spec:
              type: object
              properties:
                cronSpec: {type: string}
                image: {type: string}
                replicas: {type: integer}
  scope: Namespaced
  names:
    plural: crontabs
    singular: crontab
    kind: CronTab
    shortNames: [ct]

制約

• 名前: metadata.name は <plural>.<group> 形式。groupはドメイン名風（stable.example.com）。
• structural schema必須: apiextensions.k8s.io/v1 ではOpenAPI v3の構造的スキーマが必須。スキーマにないフィールドは保存前にpruning（黙って削除）される。任意のJSONを入れたい部分には x-kubernetes-preserve-unknown-fields: true を付ける。
• バリデーション: スキーマに加え、CELでフィールド間の制約をkube-apiserver内で書ける（webhook不要）。
• サイズ: etcdのリクエストサイズ上限がデフォルト1.5MiB（--max-request-bytes）なので、1オブジェクトはそれ以下に収める必要がある。エンコードやメタデータのオーバーヘッドもあるので、ギリギリを狙うのは危ない。大きなデータ・高頻度に書き換わるデータの置き場には向かない。
• CRDを消すと中身も消える: CRDを削除するとAPIエンドポイントが消え、そのCRDのカスタムオブジェクトも全部削除される。作り直しても空から。

変わった使い方の例: ピザを注文する

「宣言 → reconcile」の形に当てはまれば、クラスタ外の現実世界の状態も扱えることを示すネタ実装がいくつかある。いずれもDomino'sのAPIを叩いて本当に注文する。

• rudoi/cruster-api — kubebuilder製。PizzaOrder リソースを作るとコントローラが実際に発注し、kubectl get pizzaorders でPREP → BAKE → QUALITY CHECK → DELIVEREDの進捗を追える。誤発注防止の placeOrder フラグ、支払い情報はSecret参照。米国限定・ピザのみ。作者いわく実際の注文は1回。
• cirocosta/pizza-controller — PizzaCustomer（住所など）/ PizzaStore（店舗とメニュー）/ PizzaOrder の3種のCRD。kubectl get pizzacustomer で最寄り店舗、kubectl get pizzastore store-123 -o yaml でメニューが見られる。

kind: PizzaOrder
apiVersion: ops.tips/v1
metadata:
  name: ma-pizza
spec:
  yeahSurePlaceThisOrder: true
  storeRef: {name: store-123}
  customerRef: {name: you}
  payment:
    creditCardSecretRef: {name: cc}
  items:
    - ticker: 10SCREEN
      quantity: 1

• Crossplaneのprovider — Crossplane公式ブログで、Provider作りの題材としてDomino’s APIのproviderを作ってピザを注文している。Crossplaneがクラウドリソースを扱うのと全く同じ構造。

ほかにMinecraftサーバーを MinecraftServer リソースとして宣言するOperatorなどもある（こちらはPodを立てるので比較的まっとう）。

考えたこと

• ピザの例が面白いのは、reconcileモデルの汎用性を端的に示している点。「外部APIの向こうにある状態」を宣言的に管理するという意味では、Cluster APIがクラスタそのものをリソース化しているのと同じ発想。
• 逆に言うと、CRDは「kubectlで扱えるスキーマ付きKVS」としても使えてしまうが、etcdのサイズ上限や書き込み負荷を考えると、汎用DB代わりにするものではない。
• CRDやOperatorを試すならkind (Kubernetes in Docker)で使い捨てクラスタを立てるのが手軽。

Kubernetes拡張まわりの用語整理の中での位置づけ

「型を追加する」部分だけを担う。単体ではデータ置き場で、動作はコントローラが担う。

出典

• Extend the Kubernetes API with CustomResourceDefinitions | Kubernetes
• Custom Resources | Kubernetes
• Future of CRDs: Structural Schemas | Kubernetes
• System limits | etcd
• rudoi/cruster-api - GitHub
• cirocosta/pizza-controller - GitHub
• kubectl create pizza | ops.tips
• Providers 101: Ordering Pizza with Kubernetes and Crossplane
• JamesLaverack/kubernetes-minecraft-operator - GitHub

AnsibleのPlaybookやTerraform/OpenTofu、シェルスクリプトなどを、Webブラウザからボタン一つで実行できるようにするセルフホスト型のWeb UI + API。Go製（フロントはJavaScript）、MITライセンス。旧名は Ansible Semaphore で、当初はAnsible専用のUIだったが対応ツールが増えたため「Semaphore UI」に改名された。並行制御のセマフォとは無関係。

• リポジトリ: semaphoreui/semaphore（2026年9月時点でstar数1.4万程度）
• 対応ツール: Ansible, Terraform, OpenTofu, Terragrunt, Bash, PowerShell, Python
• DB: SQLite / MySQL / PostgreSQL。以前使えたBoltDBは非推奨で、2.17でSQL系DBへの移行ツールが入った
• インストール: Docker, バイナリ, deb/rpm, Snap, 各クラウドのマーケットプレイスVM
• 最新安定版は2.19系（2.19.12, 2026-08-30）

実行モデル

基本は「gitリポジトリをcloneして、その中のPlaybook/スクリプトをSemaphoreのホスト（またはrunner）上で実行し、ログをWebに流す」だけ。Ansible自体がagentlessなので、Semaphoreも対象ノードに何も入れない。コントロールノードをWeb化したもの、と捉えるとわかりやすい。

構成要素

プロジェクト単位で以下のリソースを持つ。

• Project — 以下のリソースをまとめる単位。チームメンバーと権限もプロジェクトごと。
• Repository — Playbook/スクリプトが入ったgitリポジトリ（GitHub, Bitbucketなど）。
• Key Store — SSH鍵、ログインパスワード、Ansible Vaultパスワードなどを暗号化して保存する。2.17からはファイルや環境変数からの読み込み（Kubernetesのsecret注入、HashiCorp Vault Agent連携）やDevolutions Serverもバックエンドに使える。
• Inventory — Ansible向けの対象ホスト一覧。Terraformの場合はworkspaceに相当するものを選ぶ。
• Variable Groups（旧Environment） — 変数・シークレットの組。テンプレートに複数組み合わせて注入できる。
• Task Template — 「どのリポジトリのどのファイルを、どのinventory・変数で実行するか」の定義。ブランチ指定、CLI引数（["-vvv"]のようなJSON配列）、実行時にユーザーへ入力を求めるsurvey変数も設定できる。
• Task — テンプレートを実際に実行した1回分。ログと結果が残る。
• Schedule — テンプレートをcronで定期実行。2.17で一回限り（日時指定）のスケジュールも追加。

テンプレートの3種類

バージョン情報などはsemaphore_vars経由でPlaybookに渡る。単なる「Playbook実行ボタン」ではなく、簡易的なビルド→デプロイのパイプラインも組めるようになっている。

Runner

タスクをSemaphore本体とは別のサーバで実行させる仕組み。

• semaphore runner registerでサーバ発行の登録トークンを使って登録し、以後はX-Runner-Tokenで認証する。
• runner側からのポーリング（デフォルト1秒間隔、check_interval_secondsで調整）で仕事を取りに行く。サーバからrunnerへ接続しに行く方式ではないので、runnerを閉じたネットワークに置きやすい。
• runnerがリポジトリをcloneしてAnsible/Terraform等を実行し、結果をサーバへ返す。
• プロジェクト単位のrunner（Project Runners）やrunnerのタグ指定はPro機能。

エディション

• Community — OSS版（GitHubのもの）。
• Pro / Enterprise — 有償（Proは月20ドル〜）。Workflows（タスクの連結）、プロジェクトrunner、runnerタグ、カスタムロールによるRBAC拡張、Redisを使ったactive-active HA（Enterprise）などが入る。

AWXとの比較

同じ「AnsibleにWeb UIを被せる」系のOSSとしてAWX（Ansible Automation Platformのupstream）がある。AWXはKubernetes上にOperatorで載せる前提の大掛かりな構成なのに対し、Semaphoreは単一のGoバイナリ（+ DB、SQLiteなら外部DBすら不要）で動く。小規模チームで「Playbookを誰でも安全に叩けるようにしたい」「定期実行したい」程度ならSemaphoreの方が導入コストが低い。一方でAnsible専用ではなくTerraform等も同列に扱う点は方向性の違い。（AWXのデプロイ方式は一般的な知識によるもので、このノート作成時に裏取りはしていない）

#ansible #infrastructure-as-code #go

出典

• semaphoreui/semaphore - GitHub
• Semaphore UI Documentation
• Task templates | Semaphore UI
• Runners | Semaphore UI
• Project runners (Pro) | Semaphore UI
• Semaphore 2.17 リリースノート
• Semaphore (software) - Wikipedia)

HPCクラスタ向けのオープンソースのジョブスケジューラ／リソースマネージャ。公式の説明は “an open source, fault-tolerant, and highly scalable cluster management and job scheduling system for large and small Linux clusters"。スパコンやGPUクラスタで「ログインノードにsshしてsbatchでジョブを投げる」あの世界の標準。

役割

公式overviewによると主な機能は3つ。

1. ユーザーに計算資源（ノード）を一定時間、排他的/非排他的に割り当てる
2. 割り当てたノード上で並列ジョブ（典型的にはMPI）を起動・監視する枠組みを提供する
3. 資源の取り合いをキュー（待ち行列）で調停する

歴史

• 2002年、Lawrence Livermore National Laboratory (LLNL) 中心に最初のリリース。元は “Simple Linux Utility for Resource Management” の略で、プロプライエタリなQuadrics RMSに触発されたもの。今は「Slurm Workload Manager」と呼ばれ、略語扱いではない。
• 2010年、元の開発者たちがSchedMDを設立し、以後SchedMDが本家ソースをメンテ。
• ライセンスはGPLv2。C言語で書かれ、約100個のオプショナルなプラグインを持つモジュラー設計。
• 2021年11月時点でTOP500の約60%のシステムで使われている（Wikipedia）。
• 2025年12月15日、NVIDIAがSchedMDを買収したと発表。NVIDIAはSlurmをオープンソース・ベンダーニュートラルなソフトウェアとして開発・配布し続けるとしている。発表時点でTOP500のトップ10・トップ100のそれぞれ半数超で使われているとのこと。

アーキテクチャ

• slurmctld — 中央のマネージャ。資源とジョブを監視・スケジュールする。バックアップを置ける。
• slurmd — 各計算ノードで動くデーモン。ジョブを実行し状態を報告する。
• slurmdbd — オプション。複数クラスタのアカウンティング情報をDBに記録する（sacctや fair share の元データ）。
• slurmrestd — オプション。REST APIでSlurmを操作するためのデーモン。

概念

• node — 計算資源の単位
• partition — ノードの論理グループ。実質ジョブキュー（例: gpu, debug, long）。パーティションごとに最大実行時間やアクセス権を設定する
• job — ユーザーに一定時間割り当てられた資源
• job step — ジョブ内で起動される並列タスクの集合（ジョブの中でsrunするたびに1ステップ）

GPUなどは GRES (generic resources) として扱い、--gres=gpu:2や--gpus=8で要求する。

主なコマンド

バッチスクリプトの例

#SBATCHコメントでオプションを書き、sbatch job.shで投げる。

#!/bin/bash
#SBATCH --job-name=train
#SBATCH --partition=gpu
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=8
#SBATCH --gres=gpu:8
#SBATCH --time=1-00:00:00      # days-hours:minutes:seconds
#SBATCH --output=logs/%j.out   # %j = ジョブID

srun python train.py

• --array=0-99%10 — ジョブ配列。100個のタスクを同時最大10個で流す。各タスクでは$SLURM_ARRAY_TASK_IDが添字、出力名は%A_%a（配列ジョブID_添字）が使える。パラメータスイープの定番。
• --dependency=afterok:<jobid> — 指定ジョブが成功したら開始。前処理→学習→評価のようなパイプラインを組める。

Kubernetesとの違い（感覚的なメモ）

Kubernetes（やその祖先のBorg）が「常駐するサービスを望ましい状態に保つ」ことを主眼にしているのに対し、Slurmは「有限時間で終わるバッチジョブに、ノードをまとめて（MPIならギャングで）割り当てる」ことに特化している。--timeで実行時間の上限を申告させるのも、それを使ってバックフィル（大きいジョブの待ち時間の隙間に短いジョブを詰める）をするためである。※この節は公式資料の対比ではなく自分の整理。

関連

• HPCクラスタでは、Slurmで割り当てたノード群から共有の並列ファイルシステム（Lustreなど）を/scratch的にマウントして読み書きするのが典型構成。

出典

• Slurm Workload Manager - Overview
• Slurm Workload Manager - sbatch
• Slurm Workload Manager - Wikipedia
• NVIDIA Acquires Open-Source Workload Management Provider SchedMD | NVIDIA Blog
• What Does Nvidia’s Acquisition of SchedMD Mean for Slurm? - HPCwire

#hpc #scheduler #infrastructure

HPC向けのオープンソース並列分散ファイルシステム。名前は Linux + cluster のかばん語。大量の計算ノードから1つのPOSIXファイルシステムとして見え、データを多数のストレージサーバーに分散（ストライピング）して集約帯域を稼ぐ。Slurmで動くスパコンの/scratchや/workの裏にいることが多い。

歴史

• 1999年、Peter J. Braam がカーネギーメロン大学で研究プロジェクトとして設計を開始。
• 2001年、Braam が Cluster File Systems, Inc. を設立。
• 2007年9月、Sun Microsystems が Cluster File Systems の資産を取得。
• 2010年12月、Sunを買収したOracleが Lustre 2.x の開発を止めると発表。これを受けてコミュニティ側で開発を続ける動きが出て、Whamcloud などが立ち上がる。
• 2012年7月、Intel が Whamcloud を買収。
• 2018年6月、DDN (DataDirect Networks) が Intel から Lustre チームを取得し、Whamcloud を独立部門として復活。
• ライセンスは GPLv2 / LGPL。
• 2005年6月以降、TOP500のトップ10の少なくとも半数、トップ100の60以上で使われている（Wikipedia）。Frontier（2022年11月の1位）もLustre。

アーキテクチャ

メタデータとデータの経路が分かれているのが肝。

• MGS / MGT — Management Server。クラスタ内のLustreファイルシステム全部の設定を保持する。MDSとHAペアで同居させることもある。
• MDS / MDT — Metadata Server / Metadata Target。ディレクトリ階層・ファイル属性・どのOSTにデータがあるか（レイアウト）を持つ。
• OSS / OST — Object Storage Server / Object Storage Target。ファイルの中身をオブジェクトとして持つ。1ファイルシステムで数百OSS・数千OSTまでスケールし、1台のOSSは通常2〜8個のOSTを担当する。
• Client — POSIXインターフェースを提供。MDSでファイルをopenしてレイアウトを得たら、あとはOSSと直接I/Oする。POSIXテストスイートがローカルext4と同様に通るとのこと。
• LNet — Lustre専用のネットワーク層。Ethernet、InfiniBand、Omni-Path、Crayのファブリックなどに対応し、RDMAも使える。

バックエンドのディスクフォーマットは ldiskfs（ext4ベース）か ZFS。上限値もこれで変わる（最大ファイルサイズ ldiskfs 31.25PB / ZFS 512PB、最大ファイルシステムサイズ 512PB / 8EB、MDTあたりのファイル数 40億 / 256兆）。

ストライピング

ファイルを1MB以上のチャンクに切り、複数OSTのオブジェクトにラウンドロビンで配置する（RAID 0と同じ考え方）。デフォルトは stripe count 1（1つのOSTだけ）、stripe size 1MB。巨大ファイルを多数ノードから並列に読み書きするならstripe countを増やすと帯域が伸びる。小さいファイル大量なら1のままが無難。

lfs setstripe -c 4 -S 4M /lustre/work/bigdir   # 以後このディレクトリに作るファイルは4 OSTに4MB単位で分散
lfs setstripe -c -1 /lustre/work/huge          # -1 = 全OSTに分散
lfs getstripe /lustre/work/bigdir/file.dat     # レイアウト確認
lfs df -h                                       # MDT/OSTごとの使用量

メタデータ側のスケール・その他の機能

• DNE (Distributed Namespace Environment) — メタデータを複数MDSに分散。ディレクトリのサブツリーを別MDTに置ける。
• PFL (Progressive File Layout) — 2.10で導入。ファイルの領域ごとに異なるレイアウトを持てる（先頭は1ストライプ、後半は多ストライプ、のように）。ファイルサイズが事前に読めなくてもそこそこ良いレイアウトになる。
• HSM — テープなどへのアーカイブ・階層ストレージ管理。

クラウドでは

AWSはマネージドLustreとして FSx for Lustre を提供していて、HPC向けと位置づけられている（S3 Filesのノート参照）。

出典

• Introduction to Lustre - Lustre Wiki
• Lustre (file system) - Wikipedia)
• Lustre Operations Manual

#hpc #filesystem #storage

Donald Knuthが1984年の論文「Literate Programming」(The Computer Journal, Vol.27 No.2, pp.97-111)で提唱したプログラミングのパラダイム。コードの中にコメントを埋め込むのではなく、人間向けの文章の中にコード片を埋め込む。プログラムを「コンピュータへの指示」ではなく「人間に向けて、何をさせたいかを説明する文章」として書く。

考え方

• 「複雑なソフトウェアは単純な部品と部品間の単純な関係からなる。プログラマの仕事はそれらを、人間の理解にとって最適な順序で述べることだ」(Knuth)。
• コンパイラが要求する順序ではなく、説明しやすい順序でコードを並べられる。
• コード片には「◯◯を初期化する」のような説明的な名前のマクロを付け、マクロの中からさらに別のマクロを参照する。Knuthは「プログラムはさまざまな部品からなる web(網)として捉えるのが最もよい」と言っており、トップダウン・ボトムアップのどちらにも縛られない。
• Knuth自身、当初はドキュメントのための仕組みと考えていたが、WEBで書いたプログラムは他の言語で書いたものより良くなった、と述べている。説明を書くことで推論を明示せざるを得なくなるため。

tangle と weave

1つのソースから2つの成果物を取り出す。

• tangle — マクロを展開し、コンパイラが要求する順序に並べ替えて、コンパイル可能なソースコードを生成する。
• weave — 組版されたドキュメント(Knuthの場合TeX)を生成する。

同じファイルから両方を作るので、コードとドキュメントがずれない。

ツール

• WEB — Knuthのオリジナル。Pascal + TeX。コンピューティング分野でまだ使われていなかった数少ない3文字の英単語、ということで命名。
• CWEB — KnuthとSilvio LevyによるC/C++版。
• noweb — 言語非依存。
• Org-mode Babel — Emacs上で多言語のコードブロックを実行・tangleできる。
• knitr / Sweave — R向け。再現可能な統計レポート用。
• Jupyter Notebook — コードセルとMarkdownセルを交互に並べる。2010年代、データサイエンス分野での計算ノートブックの普及によって文芸的プログラミングは再評価された。

Literate Computing への拡張

IPython作者のFernando Pérezは2013年に「Literate Computing」という言葉を使い、文芸的プログラミングの一歩先として位置づけた。テキストとコードと実行結果を織り交ぜ、ナラティブを生きた計算の中に直接織り込む、という考え方。Knuthの文芸的プログラミングが「プログラムを説明する文章」なのに対し、Literate Computingは「計算とその結果を説明する文章」を主眼にしている。

この流れをインフラ運用に持ち込んだのがLC4RI。

#programming #jupyter

出典

• Literate programming - Wikipedia
• IPython - Wikipedia
• IPython from the shell to a book with a single tool with Fernando Perez - MachineLearningMastery.com

ブラウザ上で、コード・Markdownテキスト・数式・実行結果(グラフやリッチメディア含む)をセルとして順に並べて書ける計算ノートブック。Project Jupyterが開発。文芸的プログラミングを実行結果まで含めて拡張した「Literate Computing」の代表的な道具。

歴史

• 2001年 — Fernando PérezがPythonの対話シェルを拡張した IPython を作る。
• 2011年 — Pérez、Brian Granger、Min Ragan-Kelley が IPython Notebook の最初のバージョンをリリース。
• 2014年 — 言語非依存の部分を IPython から切り出して Project Jupyter が発足。名前は Julia・Python・R に由来し、ガリレオが木星の衛星の観測をノートに記録したことへのオマージュでもある。
• 2017年 — ACM Software System Award を受賞。
• 2018年2月 — JupyterLab リリース。
• 2023年 — Jupyter Notebook 7 リリース。JupyterLab のコンポーネントの上に作り直され、両者でコードベースと拡張機構を共有するようになった。デバッガ、ダークモード、目次、リアルタイム共同編集などが入った。
• GitHub上のNotebookは2015年に約20万、2018年に250万、2021年1月に約1000万。

仕組み

• .ipynb — JSONのファイル形式。バージョン付きスキーマで、メタデータ・フォーマットバージョン・セルの配列からなる。セルにはMarkdown、コード、出力が入る。出力もファイルに保存されるので、実行結果ごと共有・閲覧できる。
• カーネル — フロントエンドとコード実行環境を分離したアーキテクチャ。プロセス間通信にZeroMQを使うプロトコルで、Python(IPythonカーネル)以外にもJulia、R、Haskell、Rubyなど数十言語のカーネルがある。フロントエンドとカーネルの間に中継カーネルを挟むこともでき、LC4RIのLC_wrapperはこれで出力の要約やログ保存をしている。
• フロントエンド — Classic Notebook、JupyterLab、Notebook 7。VS Codeの拡張や Google Colab、Amazon SageMaker なども Jupyter 系。
• JupyterHub — 多数のユーザーそれぞれに Notebook サーバを立ち上げて管理するマルチユーザー環境。

再現性の問題

実行順を自由に選べるセル実行は探索的な作業には便利だが、隠れた状態・実行順の依存が残りやすい。

• Pimentelら(MSR 2019)はGitHub上の約140万Notebookを分析。実行を試みた有効な(Pythonバージョンと実行順が定義された)Notebook 863,878件のうち、エラーなく実行できたのは24.11%、同じ結果を再現したのは4.03%だった。
• この結果からベストプラクティスを提案し、Notebook用linterの Julynter も作っている。

LC4RIのLC_run_through(成功セルのFreeze)やnblineage(セルの系譜追跡)は、この「状態と実行順の管理」の問題に運用手順書の側から手当てしているもの、と見ることもできる。

#jupyter #python #programming

出典

• Project Jupyter - Wikipedia
• Announcing Jupyter Notebook 7 | Jupyter Blog
• Build Jupyter Notebook v7 off of JupyterLab components (JEP 79)
• Pimentel et al., A Large-scale Study about Quality and Reproducibility of Jupyter Notebooks (MSR 2019)

「再構築可能なインフラのための文芸的コンピューティング」(文芸的プログラミングの発展形であるLiterate Computingをインフラ運用に適用したもの)。国立情報学研究所(NII)のクラウド運用チームが提唱・実践している、Jupyter Notebookを手順書兼作業証跡として使うインフラ運用の方法論。Notebookに「なぜやるか・前提・実行コマンド・結果・確認」を一緒に残し、実行可能で再現可能な手順書にする。

考え方

• 公式の説明: 自動化された運用を live code として記述し、予測される結果・再現可能な結果を、技術者と非技術者の双方がナラティブ(物語)の形で共有する。
• Automated Operation と Automation を区別する。完全に蒸留された自動化(Automation)ではなく、常に人間がループの中にいて状況に縛られた「自動化された運用」を目指す。技術は人間の専門性を置き換えるのではなく補うもの、という立場。
• CEDEC2019の講演では「過度な自動化への依存を防ぎ、チーム内でのノウハウ移転を促進する」ことで運用を強靭にする、という主張だった。
• Qiitaの解説(yacchin1205)では、自分が理解していない部分をコード化すると問題発生時にかえって理解が難しくなる、と指摘。自動化(Automation)ではなく、チーム全体で対象システムへの理解を深める(Communication)方向を重視する。

役割分担: Jupyter + Ansible

• Ansible — 対象システムへのコマンド実行を担当。
• Jupyter Notebook — 実行結果を含めた「体験」を人間が読める形で保存する。単なる実行ログではなく、運用チームで知見を共有するコミュニケーション媒体。
• すべての操作をコード化する必要はない、としている。代わりに以下を自然言語で書く:
  • 前提条件の確認(OS、パッケージバージョンなど)
  • 実行結果の確認(意図が満たされたとどう判断したか)
  • 背景(このNotebookを実施するに至った経緯)

成熟度の3段階(Qiita解説より)

1. とにかく残す — 体験を記録して共有する。
2. 単純にする — 似たパターンを整理し、「健康な状態」を定義する(診断用Notebook)。症状と対処を体系化。
3. 適用範囲を広げる — 設計→設定の流れを明示し、環境依存値を分離して再利用性を上げる。

ツール群

NII-cloud-operation がOSSとして公開しているJupyter拡張・カーネル。

実践環境をまとめたものとして OperationHub がある。小規模な運用チーム向けの、単一サーバ上のJupyterHub(ユーザーごとにDockerコンテナで分離、PAM認証、Notebook共有ディレクトリ)。

• LC_run_throughのFreezeは「一度成功した手順を二度流さない」ための仕組みで、冪等でない操作が混じる運用手順書と相性がよい。
• LC_wrapperのログ保存は、Notebookを作業証跡(エビデンス)として扱うための仕組み。

歴史・関係者

• NIIクラウド運用チーム。CEDEC2019講演者の長久勝(ライフマティックス/NII)、共同研究者として政谷好伸・谷沢智史・中川晋吾・合田憲人。
• 2019年 CEDEC「Jupyter Notebook が変える、あなたのチームの運用作業」。
• 2020年 Software Design 2020年5月号「Jupyter Notebookで解決するインフラ管理の手順書づくり LC4RI――再構築可能なインフラのための文芸的コンピューティングのすすめ」(監修: 長久勝・政谷好伸)。14のベストプラクティスを紹介。
• NIIの情報処理技術セミナー(クラウド編)でも題材になっている。

考えたこと

• DevOps/SRE文脈で「トイルは自動化せよ」と言われがちなのに対して、あえて人間を中心に置く立場。完全自動化の手前にある「手順書+半自動実行」の層をきちんと道具化したもの、と捉えられる。
• 構成管理ツールによる宣言的なIaCが「あるべき状態」を記述するのに対し、LC4RIは「その場で何をやって何が起きたか」を記述する。補完関係。
• 実行可能な手順書という点では、最近のAIエージェントに渡す手順書(SKILL.mdなど)とも発想が近い。

#devops #jupyter #infrastructure-as-code

出典

• What is LC4RI?(en) | Literate Computing for Reproducible Infrastructure
• LC4RIツール(ja) | Literate Computing for Reproducible Infrastructure
• NII-cloud-operation/Jupyter-LC_run_through
• NII-cloud-operation/Jupyter-LC_wrapper
• NII-cloud-operation/Jupyter-multi_outputs
• NII-cloud-operation/Jupyter-LC_nblineage
• NII-cloud-operation/Jupyter-LC_index
• NII-cloud-operation/sidestickies
• NII-cloud-operation/nbsearch
• NII-cloud-operation/OperationHub
• CEDEC2019: Jupyter Notebook が変える、あなたのチームの運用作業
• Software Design 2020年5月号 | 技術評論社
• Jupyter+Ansibleを使ったインフラ運用の考え方2017 - Qiita
• LC4RIに関するメモ - Qiita
• 情報処理技術セミナー（クラウド編） | 国立情報学研究所

herdrが稼働中のセッションを外部から検査・操作させるために公開しているローカルAPI。プラグイン機構やCLIの下にあるレイヤで、スクリプト・独自ツール・エージェントがここを叩く。

3つのレイヤ

ドキュメントは用途別に3レイヤを提示していて、「レイヤは同じコントロール面を共有する(The layers share the same control surface)」とされている。

「ほとんどの自動化はCLIラッパーから始めるべきで、生のソケットAPIはリクエスト/レスポンスを直接制御したい場合や、長寿命のイベント購読が必要な場合にだけ使う」という方針。プラグインも基本はCLI(HERDR_BIN_PATH)経由が推奨で、ソケットを直接叩くのは一段深い選択肢という位置づけになる。

プロトコル

改行区切りJSON(ndjson)。1行1リクエストで、レスポンスは同じidを返す。

{"id":"req_1","method":"ping","params":{}}
{"id":"req_1","result":{"type":"pong"}}

エラーはerrorにcodeとmessageが入る。

{"id":"req_1","error":{"code":"not_found","message":"pane not found"}}

JSON-RPCではなく、独自のリクエスト/レスポンス形式。

ソケットのパスと解決順

トランスポートはUnixではドメインソケット、Windowsでは名前付きパイプ。

~/.config/herdr/herdr.sock
~/.config/herdr/sessions/<name>/herdr.sock

どのソケットに繋ぐかは次の順で決まる。

1. CLIの--session <name>
2. 環境変数HERDR_SOCKET_PATH
3. 環境変数HERDR_SESSION=<name>
4. デフォルトセッションのソケット

herdrが管理するペインにはHERDR_SOCKET_PATH / HERDR_ENV=1 / HERDR_WORKSPACE_ID / HERDR_TAB_ID / HERDR_PANE_IDが注入される。呼び出し側が渡した環境変数と衝突した場合はherdr側の値が優先される。

なおドキュメントには認証機構の記述が見当たらない。ローカルソケット前提の設計に見える。

メソッド

ドット記法で領域ごとに分かれている。網羅はherdr api schemaに任せて、系統だけ挙げると、

• server.* — ping、server.stop、server.reload_config、エージェントマニフェストの再読み込み
• workspace.* / tab.* — 作成・一覧・フォーカス・リネーム・移動・クローズ
• pane.* — 分割・移動・ズーム・リサイズなどのレイアウト系に加えて、pane.send_text / pane.send_keys / pane.read / pane.wait_for_outputといった入出力系
• agent.* — agent.list / agent.read / agent.prompt / agent.wait / agent.startなど、エージェント単位の操作
• layout.* — layout.export / layout.apply
• worktree.* — worktree.list / create / open / remove
• plugin.* — プラグインのリンク・有効化・アクション実行・ペイン開閉
• events.subscribe / events.wait / session.snapshot

pane.readのソースにはvisible / recent / recent-unwrapped / detectionがあり、「今画面に出ているもの」と「最近の出力」を区別して読める。pane.send_keysはherdrのキー文字列(enter、esc、ctrl+h、shift+tab、f1、minusなど)を受け付ける。

スキーマはCLIから出せる

herdr api schema                              # サマリ
herdr api schema --json                       # 完全なJSON Schema
herdr api schema --output herdr-api.schema.json

バイナリに同梱されたスキーマが出るので、バージョンとズレない。リクエスト・成功レスポンス・エラーレスポンス・発火するイベント・購読イベントが対象。

イベント購読

events.subscribeで購読すると、最初のレスポンスが購読の確認になり、以降はイベントが push されてくる(接続は開いたまま)。

{"id":"sub_1","method":"events.subscribe","params":{"subscriptions":[
  {"type":"pane.agent_status_changed","pane_id":"w1:p1","agent_status":"blocked"}
]}}

購読時点でフィルタを指定できるのがポイントで、上の例は「このペインのエージェントがblockedになったときだけ」という絞り込み。1回だけ待つevents.waitもある。

イベントはworkspace.* / tab.* / pane.* / layout.updated / worktree.*の系統。エージェント運用で使いたくなるのはこのあたり。

• pane.agent_detected — ペイン内でエージェントが検出された
• pane.agent_status_changed — 作業中・アイドル・入力待ちなどの状態が変わった
• pane.output_matched — 出力が指定パターンにマッチした
• pane.exited — プロセスが終了した
• worktree.created / worktree.opened / worktree.removed

herdr plusがworktree作成時にレイアウトを流し込んでいるのは、このworktree.createdをプラグイン機構の[[events]]から拾っているもの。

エージェントの状態を外から報告できる

herdr本体はペインの出力からエージェントの状態を自動検出するが、ソケットAPI経由で外部から状態を申告することもできる。herdrが知らない自作のエージェントやバッチ処理をサイドバーに乗せたい場合の口。

{"id":"req_1","method":"pane.report_agent","params":{
  "pane_id":"w1:p1","source":"custom:docs","agent":"docs-bot",
  "state":"working","message":"building docs"}}

stateはidle / working / blocked / done / unknown。ほかにpane.report_agent_sessionでセッションIDを紐付けたり、pane.report_metadataで表示用のタイトルや状態ラベル、TTLを渡したりできる。

サイドバーの見せ方自体もagent.view.setで宣言的に制御でき、eq / in / exists / all / any / notのフィルタと、attentionやstate_change_seqなどでのソートを指定した「ビュー」を登録できる。

ペインへの画像描画

pane.graphics.*でペインに画像を重ねられる。pane.graphics.infoで能力(セルサイズ、ピクセルマウス対応、レイヤ上限16など)を取得し、pane.graphics.setにbase64のPNGと配置を渡す静的描画と、専用ソケットを開いてフレームごとにヘッダ＋生バイト列を流すpane.graphics.streamがある。形式はpng / rgb / rgba / bgra。

herdr-browserがペイン内にChromiumのスクリーンキャストをライブ表示できているのは、この層があるため。

#claude-code #tmux

出典

• Socket API | herdr
• Plugins | herdr

herdrがエージェント向けに配布している、herdr自身の操作方法を教えるMarkdownの指示書。ソケットAPIの3レイヤのうち、一番上の「Agent skill」レイヤに相当する。

「エージェントがherdrを操作するためのものがskillで、エージェントが人間にherdrを教えるためのものがguide」(The skill is for an agent operating Herdr; the guide is for an agent teaching a human)と役割が整理されている。

入手方法

herdr --skill

バイナリに同梱された、そのリリースに対応するコピーが出力される。GitHub上のタグ付きパスからも取れる(herdrdev/herdrのskills/herdr/SKILL.md)。

グローバルに入れる場合は、

npx skills add herdrdev/herdr --skill herdr -g

入れたうえでherdrの中からエージェントを起動する(herdr claudeのように)。

何をできるようになるか

skillを読んだエージェントは、自分が置かれているherdrセッションを操作できるようになる。

• ワークスペース・タブ・ペイン、そして隣のエージェントを検査する
• フォーカスを奪わずにペインを分割してコマンドを走らせる
• ペインの出力や最近のログを読む
• サーバーの起動、テストの完了、別のエージェントの完了を待つ
• 兄弟ペインに補助エージェントを起動する

「隣のエージェントを見る」「別のエージェントの完了を待つ」「補助エージェントを起動する」あたりが、単なるターミナル操作と違う部分。エージェントがマルチプレクサ越しに他のエージェントを観測・起動できるので、herdrがオーケストレーションの土台になる。

HERDR_ENV=1によるガード

skillの安全弁はここ。エージェントは操作の前に環境変数HERDR_ENV=1が設定されているかを確認し、設定されていなければ中断して「herdr管理下のペインで動いていない」と伝えるよう指示されている。

HERDR_ENV=1が立っているのは、herdrが管理するペインの中で動いている場合だけ。つまり「ローカルのherdrソケットに話しかけて構わない文脈かどうか」の判定を、この環境変数1つに集約している。skillを読んだエージェントがherdrの外で動いているときに、無関係なセッションを操作しに行かないための作り。

考えたこと

プラグイン機構が「CLI全体がプラグインAPI」という方針を採っているのと、このskillは同じ思想の延長にある。専用のSDKやツール定義を用意するのではなく、すでにあるCLIを説明する文書を配ることでエージェント向けのインターフェイスを済ませている。MCPサーバーのようにプロトコルを立てる方向とは対照的なアプローチで、CLIが十分に整っているならこれで足りる、という判断に見える。

#claude-code #tmux #ai-agent

出典

• Agent skill file | herdr
• Socket API | herdr

herdr本体はターミナルマルチプレクサとしての役割に絞られており、周辺機能はプラグインとして外に出す設計になっている。herdr-browserやherdr plusはいずれもこの機構の上に乗っている。

プラグインの実体は、herdr-plugin.tomlというマニフェストと、herdrが起動できるコマンドを置いたディレクトリ。herdrはそれを別プロセスとして起動するだけなので、Bash・JavaScript・Lua・Rust・PowerShellなど、マシンで実行できるものなら言語は問わない。

SDKが無い — CLIそのものがAPI

この機構の一番の特徴。専用のプラグインSDKは存在せず、

The entire Herdr CLI is the plugin API: every command in the CLI reference is available to a plugin, and anything you can run as herdr ... yourself a plugin can run too.

という方針になっている。プラグインは環境変数HERDR_BIN_PATHが指すherdrバイナリを呼び戻すことでherdrを操作する。Unixドメインソケットと Windows の名前付きパイプの差をherdr側が吸収してくれるため、プラグインの移植性はCLI経由の方が高い。

ホスト側(herdr)が責任を持つのは、インストール・マニフェスト検証・キーバインド・ペイン・イベント・呼び出しコンテキスト・ソケットアクセスといった土台の部分。

マニフェストと拡張ポイント

id = "example.layout"
name = "Layout"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Apply project layouts"
platforms = ["linux", "macos", "windows"]

[[build]]
command = ["npm", "ci"]

[[startup]]
command = ["node", "dist/restore.js"]

[[actions]]
id = "apply"
title = "Apply layout"
contexts = ["workspace"]
command = ["node", "dist/apply.js"]

[[events]]
on = "worktree.created"
command = ["herdr", "workspace", "list"]

[[panes]]
id = "board"
title = "Project board"
placement = "overlay"
command = ["herdr-board"]

[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "apply"

必須フィールドはid / name / version / min_herdr_version。拡張ポイントは5種類。

• [[startup]] — セッション復元後に一度だけ走る初期化フック。常駐サービスの供給ではない(監視・再起動はされない)
• [[actions]] — キーバインドやUIから呼べるコマンド。herdr plugin action invokeで叩ける。config側からはtype = "plugin_action"でキーに割り当てる
• [[events]] — herdrのイベントに反応するフック。on = "worktree.created"のように書く。herdr plusがworktree作成時にレイアウトを流し込んでいるのはこれ
• [[panes]] — ペインとして開くTUI。placementにoverlay / popup / split / tab / zoomedを指定できる
• [[link_handlers]] — ターミナル内のURLへの修飾クリックを正規表現でマッチさせ、アクションにルーティングする

[[build]]はインストール時に走るビルドコマンド。platformsで対象OSを絞れる。

文脈は環境変数で渡ってくる

プラグインのコマンドには、herdrから実行時の文脈が環境変数として注入される。

ほかに、アクションにはHERDR_PLUGIN_ACTION_ID、イベントフックにはHERDR_PLUGIN_EVENTとHERDR_PLUGIN_EVENT_JSON、ペインにはHERDR_PLUGIN_ENTRYPOINT_IDが渡る。

下位レイヤとしてのソケットAPI

CLIの下には、稼働中のherdrを直接叩くソケットAPIがある。改行区切りJSON(ndjson)で1行1リクエスト、レスポンスは同じidを返す。

{"id":"req_1","method":"ping","params":{}}
{"id":"req_1","result":{"type":"pong"}}

トランスポートはUnixではドメインソケット、Windowsでは名前付きパイプ。デフォルトは~/.config/herdr/herdr.sockで、名前付きセッションは~/.config/herdr/sessions/<name>/herdr.sock。

ドキュメントは「ほとんどの自動化はCLIラッパーから始めるべきで、生のソケットAPIはリクエスト/レスポンスを直接制御したい場合や、長寿命のイベント購読が必要な場合にだけ使う」としている。さらに上のレイヤとして、エージェントにherdrの操作方法を教えるagent skillファイルがある。

インストールと開発

# GitHubから入れる。リポジトリに複数プラグインがあればサブディレクトリまで指定
herdr plugin install owner/repository
herdr plugin install owner/repository/subdir

# ローカル開発用。ビルドコマンドをスキップする
herdr plugin link /path/to/plugin

インストールはクローン → プレビュー表示 → ビルドコマンド実行 → 登録、という流れ。これらのCLIはherdrサーバーが起動していなくてもレジストリに書き込み、次回起動時に読み込まれる。

躓きやすい点。

• コマンドはargv配列で、シェル展開は行われない
• 自動更新の仕組みが無い。更新したければ入れ直す
• 認証情報はチェックアウト先ではなくHERDR_PLUGIN_CONFIG_DIRに置く。GitHubからの再インストールでチェックアウトは置き換わるため

サンドボックスは無い

プラグインは自分の権限でそのまま動く普通のコードで、herdr CLIの全機能を呼べる。ドキュメントも「herdrはプラグインが何をするかをレビューもサンドボックス化もしない。サードパーティのプラグインは作者から来るものであってherdrから来るものではないので、各自で検証し、自己責任で動かすこと」と明言している。エディタ拡張やシェルスクリプトと同じ姿勢で読んでから入れるべき、という位置づけ。

#claude-code #tmux

出典

• Plugins | herdr
• Socket API | herdr
• herdr/docs/…/plugins.mdx - GitHub
• A practical guide to Herdr plugins - Flavio Copes

std::sync::OnceLock<T> は「一度だけ書き込める、スレッドセーフなセル」。Rust 1.70.0 で安定化された。static に置けるので、グローバルな遅延初期化を外部クレートなしで書くための標準的な手段になっている。 #rust #並行処理

中身は最初は空で、どのスレッドからでも一度だけ値をセットできる。セットされて以降は不変の &T として読めるだけになる。シングルスレッド専用版は std::cell::OnceCell。

典型的な使い方

use std::sync::OnceLock;

static CONFIG: OnceLock<Config> = OnceLock::new();

fn config() -> &'static Config {
    CONFIG.get_or_init(|| Config::load_from_env())
}

OnceLock::new() が const fn なので static の初期化子に書ける。get_or_init は複数スレッドが同時に呼んでもクロージャの実行は1回だけで、他のスレッドは初期化完了までブロックしてから同じ参照を受け取る。

公式ドキュメントの例:

use std::sync::OnceLock;

static CELL: OnceLock<usize> = OnceLock::new();
assert!(CELL.get().is_none());

std::thread::spawn(|| {
    let value = CELL.get_or_init(|| 12345);
    assert_eq!(value, &12345);
})
.join()
.unwrap();

assert_eq!(CELL.get(), Some(&12345));

主なメソッド

&mut self を要求する get_mut/take は、排他参照が取れている＝他スレッドと共有されていないことがコンパイル時に保証されるので、同期なしで中身をいじれるという理屈。

poisoning がない

Mutex と違い OnceLock は poisoning しない。get_or_init に渡したクロージャがパニックしても、セルは未初期化のまま残り、次に呼んだスレッドがもう一度初期化を試みる。

対して後述の LazyLock は初期化クロージャがパニックすると恒久的に poisoned になり、以降のアクセスはすべてパニックする。初期化が失敗しうる場合の挙動がまったく違うので注意。

LazyLock・Once との使い分け

Rust 1.80.0 では std::sync::LazyLock も入った。

use std::sync::LazyLock;

static CONFIG: LazyLock<Config> = LazyLock::new(|| Config::load_from_env());
// *CONFIG でアクセスすれば初回に自動で初期化される

• 初期化ロジックが宣言時に確定しているなら LazyLock。格納場所と初期化処理を1箇所にまとめられ、Deref 経由の初回アクセスで自動的に走る。公式ドキュメントも「多くのケースで static には LazyLock のほうが簡潔」としている。
• 初期化に実行時の値が必要（CLIオプションで組み立てた設定、あとから渡されるDBハンドルなど）な場合は LazyLock::new(|| ...) のクロージャに外から引数を渡せないので OnceLock + get_or_init / set を使う。初期化のタイミングを明示的に制御したい場合も同様。
• std::sync::Once は「値を持たない、処理を1回だけ実行する」ことだけを保証するプリミティブ。値を保持したいなら OnceLock を使う。

OnceLock/LazyLock はもともと外部クレート once_cell（および lazy_static! マクロ）が担っていた役割を標準ライブラリに取り込んだもので、RFC 2788 “standard lazy types” がその提案にあたる。新しく書くコードで lazy_static を持ち込む理由はほぼなくなった。

出典

• OnceLock in std::sync - Rust
• LazyLock in std::sync - Rust
• RFC 2788: standard lazy types - The Rust RFC Book