概要と原則

​

1. 問題

チームが自動化するとき、行き着く先はたいてい2つです。強力ではあるものの 閉じ込められたホスト型オーケストレーター（自分のラップトップでは動かせず、 fork もできず、安価にセルフホストもできない）か、ネットワークが一瞬乱れたり、 依存関係が浮いたり、それを理解していた唯一の人がいなくなったりするまでは 動く、寄せ集めのグルースクリプト群です。最初に失われるのは再現性であり、 「AI に頼んでワークフローを再生成すればよい」は再現性の説明ではありません。 それはレイテンシとコストが余計にかかるコイントスです。 難しいのは 合成 です。「価格を調べ、下がっていたら Slack に投稿し、 チケットを開く」。手順を連結するところで、多くのシステムは上の2つの失敗モードの どちらかに逆戻りします。 browser-flow は、ただ1つの確信に基づいてゼロから作られています。 プロセスの定義と、それが同じように実行されるという保証こそがプロダクトである。 それ以外のもの、つまりストレージ、トランスポート、UI、ホスティングはすべてアダプターです。

​

2. それが何であるか

これは、次の柱を備えたワークフローエンジンおよびサービスです。

​

3. それが何でないか

​

4. 設計原則

これらは支柱となる原則です。将来の判断がこのいずれかと衝突した場合、 書面で明示的に上書きされない限り、原則が優先されます。

​

T1 — 1つの真実、2つの表現

SDK と YAML は対等な存在です。どちらか一方が「本物」なのではありません。 どちらも FlowSpec にコンパイルされ、FlowSpec は YAML にラウンドトリップできます。 片方の手段でしか動かない Tool はバグです。

​

T2 — デフォルトは決定論的、effects は permission による

手順は、そうでないと宣言するまでは純粋です。time、randomness、environment、 network、filesystem、secrets、process spawning は、run context を通じて注入される capabilities であり、ambient ではありません。これにより実行は解析可能、 サンドボックス化可能、リプレイ可能になり、実行時に LLM を使わないという保証が誠実に保たれます。

​

T3 — 再現性は content-addressed である

Flow は、安定した sha256 digest を持つ canonical FlowSpec にコンパイルされます。 Flow digest、tool/pack versions、記録された inputs を pin すれば、その実行は任意の マシン上でオフラインに再現可能です。digest こそが version です。

​

T4 — portable な core、pluggable な edges

engine は少数の interfaces（Store, Clock, Random, Secrets, Logger, ToolHost, Journal）だけに依存します。すべての launcher と backend は、 それらの interface の implementation です。engine がクラウド SDK を import することはありません。

​

T5 — code は最小限、legibility は最大限

新しい Tool は、Zod-typed な input/output schema と run function を持つ小さな object です。 新しい launcher は engine.run() を包む薄い shell です。ある feature が大量の core code を 必要とするなら、それはおそらく engine ではなく Pack に属します。

​

T6 — local-first、cloud-optional

すべては infrastructure なしで動きます。state には SQLite、artifacts には filesystem、 secrets には file を使います。scale out では concepts ではなく implementations を差し替えます。 pip install / npm i で tools は動き、engine はそれらが動く場所ならどこでも動きます。

​

T7 — loud に失敗し、clean に再開する

Errors は typed（DomainError lineage）であり、原因となった手順、input、journal frame と ともに表面化します。どの実行も、完了済みの手順を再実行することなく、最後の durable checkpoint から再開します。

​

T8 — 意図的に boring に、シークレットは境界に

Stable formats、explicit versions、clever globals なし、module-level singletons なし。 secret: true と marked された inputs（cookies、tokens、credentials）は、FlowSpec、 journal、log、公開済み Pack のいずれにも入りません。その値は、secrets capability を 宣言した手順の内側でのみ、実行時にのみ resolved されます。

​

5. House conventions

この repository は、厳格で意図的に boring な engineering style に従います （browser-flow reference が使う conventions と同じなので、family として一貫して感じられます）。

• TypeScript、class なし（Error subclass は例外）。closure-held state を持つ factory functions、parameter として注入される dependencies、module-level singletons なし。
• Type trichotomy。 Data types は Zod schemas で、TS は z.infer から導出します。 behaviour/contract types（function member を持つもの）は interface、type は unions / mapped / branded constructs のために予約されています。
• Schemas は .strict() であり、schema_version literal によって versioned されます。
• pnpm + bun monorepo、Turborepo-cached な test / typecheck / build / lint（Biome）、mise によって pinned された toolchain。API は Hono on Bun （packages/web-api）、web は Next.js（apps/web）、persistence は SQLite （built-in。external database は不要）です。
• Co-located *.spec.ts、bun test。Open core、Apache-2.0、@browserflow scope、releases には Changesets。
• 作業言語は英語。committed prose artifact はすべて英語です。

これらの conventions が domain schemas をどのように形作るかは、 domain model を参照してください。

​

6. 60秒でつかむ mental model

次に domain model を読んでください。すべての box が正確に命名されています。