Lakda / domain-lakda-runner

ライセンス

このバージョンは、RNA Third-Party Service Attribution License 1.0に基づくsource-availableソフトウェアです。

個人利用、研究、教育、オープンソース活動、および企業による自社内利用は無償です。

第三者向けの有償QA、テスト、開発支援、コンサルティング等で利用する場合は、顧客の技術担当者が確認できる文書に、ツール名、原開発者、公式リポジトリ、使用versionまたはcommit、改変の有無を案件単位で一度記載してください。

帰属表示を省略するホワイトラベル利用には、別途書面による商用ライセンスが必要です。

過去のMIT版は、引き続きMIT Licenseの条件で利用できます。詳細はLICENSING.mdを参照してください。

License

This version is source-available under the RNA Third-Party Service Attribution License 1.0.

Personal use, research, education, open-source activities, and internal business use are permitted without charge.

When the software is used to provide a paid QA, testing, development, consulting, managed, outsourced, or similar service to a third party, a one-time attribution notice must be provided in project documentation reasonably accessible to the Customer technical team.

Attribution-free white-label use requires a separate written commercial license.

Previously released MIT-licensed versions remain available under their original MIT terms. See LICENSING.md.

Lakdaは、Web・ゲーム・認可済みセキュリティ探索を共通の状態遷移モデルで扱うテストオーケストレーターです。Playwright、Airtest/Poco、ZAPなどの操作基盤を再実装せず、「目と手」として接続します。Lakda Coreは、安全に試す候補、踏破済み状態、再現手順、証跡を管理します。

Lakdaのrun outcomeは最終品質Gateではありません。LakdaはHATE/v1証跡までを生成し、Go／No-Goは外部のmanual-bbとQEGが判断します。

Note

現在の候補版は 0.5.0-rc.2 です。code revision 600a037efec8617d2090b1c8be408a1d1b9b1c5a の公開・非破壊reference stagingに対するQEG goは、履歴として保持しますが、現在のsource revisionを承認するものではありません。現在の候補版はfreeze SHAごとにdeterministic、adaptive、exploration、package、reference staging、実Qwen、RanD、Code-to-gate、HATE、manual-bb、QEGを再実行するまでpending_externalです。任意の本番・実機・security targetへの包括承認も示しません。詳細は品質証跡記録を参照してください。

機能

領域	Lakdaが担うこと	操作基盤	境界
Web / SaaS	DOM・URL・通信を観測し、安全な操作候補を探索・replay	Playwright	in-process adapter
ゲーム	画面・UI階層・実機入力から状態を探索	Airtest / Poco	operator管理のloopback bridgeのみ
セキュリティ	認可差分・安全な変異・手順差分を探索補助	Security bridge / ZAP等	署名済み認可v2、method/template scope、permit receipt、rate、cleanup、kill switch必須
共通コア	fingerprint、遷移graph、停止条件、oracle、replay、証跡	adapter共通	HATE/v1まで。QEG verdictは生成しない

flowchart LR
  O[観測] --> C[安全なcandidate生成]
  C --> X[安全制御・実行]
  X --> R[DOM再観測・oracle]
  R --> G[状態遷移graph・replay]
  G --> E[redacted evidence / HATE v1 manifest]
  E --> H[HATE: 自動テスト証跡の正規化]
  H --> M[manual-bb: 人間のブラックボックス確認]
  M --> Q[QEG: 最終Gate verdict / record]

Loading

品質検証の全体像

Lakda単体の成功をリリース成功とは呼びません。要件から最終判定まで、次の独立したツールを順に接続します。

ツール	人間向けの役割	このrepoとの関係
RanD	要求仮説、調査、受入条件を整理する	検証対象と期待結果の入口
Code-to-gate	静的解析、finding、risk、readinessを作る	source revisionを独立評価
HATE	JUnit、coverage、artifactを品質証跡へ正規化する	LakdaのHATE/v1 manifestを受け取る
manual-bb-test-harness	人間が実targetを確認し、Go/No-Go briefを作る	fixtureでは代替できないoracleを担当
QEG	全証跡をgraph化し、最終Gate verdictとrecordを生成する	Lakdaの外部にある最終判定者

過去revision 600a037の自己完結したQEG入力、go verdict、recordはdocs/release-gate/qeg-600a037/から辿れます。これは0.5.0-rc.2の承認ではありません。HATE export成功はQEG goと同義ではなく、QEG自身のschema-check、hash verify、Gate評価が必要です。

実装済みの機能面

機能	内容	入口	ローカル実証
決定的実行とreplay	smoke、seeded-random、回帰replayをseed付きで再現	lakda run / lakda replay	済み
適応型探索	表示・操作可能要素からcandidateを生成し、各操作後にDOMを再観測	lakda run --mode adaptive-explore	済み
自動・クロスプラットフォーム探索MVP	PC Web、mobile Web、Windows、Android、iOSを自動探索し、Airtest画像、finding、captureを統合	統合仕様	fixture runtime実装済み。Windows／Android実機／iOS実機real acceptanceはpending_external
状態graphとcoverage	fingerprint、遷移、未探索優先、plateau停止、backtrackを記録	adaptive run artifact	済み
拡張registryとLLM選択	Adapter／Generator／Oracleを内部registryで解決し、llm-selectは提示candidateまたは停止だけをstrict検証	lakda.config.json	済み
Run catalogと比較	HATE/v1を再検証してrunを読取り専用で列挙・表示し、graph／coverage／outcome差分を決定的JSON化	lakda runs list/show/compare	済み
安全制御と入力	allowlist、deny操作、予算、mutation policy、kill switch、seed付き同値・境界・異常値入力	lakda.config.json	済み
P8 組合せ探索	constraint-safeなpairwise／mixed-strength suiteを生成・検証	lakda combo gen / lakda combo verify	済み
P9 scouting	timeout、oracle failure、coverage gapなどをSignal／Leadへ正規化	lakda scout / lakda report leads	済み
P10 調査・昇格・縮約	strict replay、reproduced-only promote、安全なfailure shrinking	lakda investigate / lakda promote	済み
P11 case受入	承認targetでcase単位のreal acceptanceを実行・検証	npm run acceptance:extension:real	v2 runner/verifier実装済み。0.5.0-rc.2の実環境証跡はpending_external

P8〜P11の契約は拡張仕様書を正本とします。fixture成功を実環境受入へ昇格しません。reference stagingの実証も、実機や認可済みsecurity targetの代替にはしません。

テスト実行後のHTMLレポート

テスト終了後に、結果の概要・失敗理由・保存済みの画像や動画を確認できます。基本の使い方は次の3手順です。

1. 通常どおりlakda runなどの対応CLIでテストを実行します。HTMLは既定で自動生成されます。
2. 終了時の通知にあるdirectory内のindex.htmlをブラウザで開きます。既定の保存先は.lakda/reports配下です。
3. 結果一覧のメッセージから気になる項目を開き、全文と画像・動画を確認します。動画は再生ボタンで再生します。

概要では合否と主要な件数を確認できます。操作件数や実行時間は「操作件数・実行時間など」を開くと表示されます。結果が未確定の実行や未完了のワーカーがある場合は、概要に表示します。

結果一覧は状態やキーワードで絞り込めます。「実行失敗」は失敗した実行、「失敗項目」は個別の失敗内容です。表示名でも保存記録のコード（failed／failure）でも検索でき、「絞り込みを全解除」で一覧に戻せます。

詳細の「失敗した手順へ」と前／次のボタンから操作を確認できます。履歴一覧も選んだ手順までスクロールします。手順を選んで画像が出ない場合は、「実行全体の証跡を見る」で保存済みの画像・動画を開きます。手順との対応が未確認であることを表示し、画像は「画像を拡大」で細部を確認できます。

出力言語は生成時に日本語（既定）と英語から選べます。対応CLIに--report-language jaまたは--report-language enを付けます。既定値を保存する場合はlakda.report.jsonに{"schemaVersion":"lakda/report-config/v1","language":"en"}を設定します。CLIの指定を優先し、テストのメッセージ・ID・記録上のコードは原文を保ちます。別の言語で読みたい場合は、保存済みの実行結果から再生成できます。

保存済みrun／sessionから作り直す場合は、次のコマンドを使います。

lakda report generate --run-dir .lakda/runs/<run-directory> --out .lakda/reports/review-01
lakda report verify --report-dir .lakda/reports/review-01

英語で再生成する例:

lakda report generate --run-dir .lakda/runs/<run-directory> --out .lakda/reports/review-en --report-language en

生成後は出力フォルダーのindex.htmlを開きます。閲覧にはLakda・Node.js・Webサーバーは不要です。持ち運ぶときは画像・動画・表示用ファイルを含むフォルダー一式をコピーするか、ZIPにして展開してください。ファイル間の参照は相対パスで、外部通信なしで閲覧できます。index.htmlだけでは表示に必要なファイルが不足します。Windowsでは長すぎる保存パスで媒体を開けない場合があるため、展開先は短いパスを推奨します。確認範囲は利用フローと持ち運びの検証記録を参照してください。

再生成先は未存在フォルダーを指定してください。--session <session-directory>／--sources <report-sources.json>にも対応します。元テストのfailedとレポート生成のreadyは別状態です。操作履歴のない旧runは計画と件数未取得を表示します。

run／replay／explore run／explore resumeは終了後に自動生成します。保存先の既定は.lakda/reportsです。--report offで無効化し、--report-dir／--report-profileで保存先とprofileを指定できます。元のstdout／終了codeを維持し、生成結果とreceipt保存先はstderrに表示します。worker batchは全workerで1レポートとし、再生成用のprivate indexをsources-<UUID>/sources.jsonへ別保存します。indexにはローカル保存先が含まれるため、共有する場合はHTML bundleだけを選びます。

新規runはtarget接続前に最小の開始記録を保存します。最終manifestが存在しない場合は、この記録からlocalの診断レポートを作り「結果未確定」と表示します。開始記録だけでは実行中と異常終了を区別できず、合否・終了時刻・操作数・媒体を推定しません。開始記録もないrunや既存manifestが不正なrunは拒否します。未確定runはshareへ出力できません。

shareは、保存済みHATEに含まれる検査記録と媒体のbytesを、lakda.report.jsonのtrustStorePathで指定した鍵一覧で検証できる場合に媒体を同梱します。real sessionとそのadaptive runでは対象manifestの許可鍵・capabilityも照合します。未検査媒体は除外し、採用した媒体の詳細から検証記録を確認できます。履歴やfindingに検証できる明示参照があれば、該当項目から画像・動画を選択できます。対応記録のない媒体は実行全体の証跡として確認できます。画像は原寸以上へ拡大し、画像枠内を矢印キーで移動できます。Chrome／Edge・100%／200%の媒体40ケースと最大件数の測定をlocalで確認済みです。容量の全境界と実環境・手動受入は実装Taskで継続中です。詳細はレポート仕様を参照してください。

native v2の保存sessionは、媒体なし・textOnlyを含め、report設定のtrustStorePathと保存観測で対象の署名を検証します。現在の期限切れだけで過去の有効な証跡を拒否しません。操作結果が不明な記録は「結果未確定」と警告し、生成状態をdegradedにします。署名不正・観測欠落・証跡一覧との不一致は生成エラーになります。詳細はnative保存証跡の検証記録を参照してください。

最短のローカル検証

npm ci
npx playwright install chromium
npm run check
npm run acceptance:fixture
npm run acceptance:adaptive
npm run acceptance:exploration:fixture
npm run release:validate-profile
npm run test:contracts
npm run test:examples
npm run pack:check

この経路は、型・lint・ビルド・Playwright回帰・fixture受入・公開package境界を検証します。実サーバー、実機、実モデル、認可済みsecurity targetには接続しません。

Codex Skills（任意）

Codexで保守や受入作業を行う場合は、次のpersonal Skillsを利用できます。これらはnpm packageのruntime依存ではなく、作業手順と責務境界をCodexへ与えるための補助です。

Skill	使う場面
lakda-maintainer	Lakdaの設定、CLI、adapter、P8〜P11、real acceptance、HATE/QEG境界を変更・レビューするとき
five-tool-validation-gate	RanD → Code-to-gate → HATE → manual-bb → QEGを一続きのrelease evidenceとして実行するとき。全体フローの正本はworkflow-cookbook
manual-bb-test-harness	仕様とriskから手動ブラックボックスケース、strict Gate、Go/No-Go briefを作るとき
agent-tools-hub	Agent_tools全体の入口を選び、workflow-cookbook・manual-bb・QEGへの読み順を整理するとき
workflow-agent-evidence	workflow-cookbookのEvidence recordとLakda/HATEの証跡連携を保守するとき
local-llm-launcher	operatorが実Qwenをloopbackで起動・停止し、model IDとGGUF SHA-256を固定するとき

人間が先に読む正本はこのREADME、RUNBOOK.md、各仕様書です。Skillは正本を置き換えず、fixtureを実環境証跡へ昇格させる権限も持ちません。

使い方

診断とsmoke

doctorは読み取り専用です。許可済みのローカルまたはstaging URLだけを指定してください。

lakda doctor
lakda run --base-url http://127.0.0.1:3000 --mode smoke --seed 1

実行結果は.lakda/runs/<run-id>/に保存されます。通常runではbrowser起動中の録画も既定で有効になり、non-passではartifacts/failure.png、artifacts/trace.zip、artifacts/video/0001.webmをaction sequence、console、failure report、HATE/v1 manifestと合わせて確認できます。traceはnpx playwright show-trace .lakda/runs/<run-id>/artifacts/trace.zipで開けます。

録画を明示的に無効化する場合は、設定へ次を追加します。

{
  "artifacts": {
    "video": false
  }
}

既定の"retain-on-non-pass"はPlaywright contextを実行中録画し、passedでは削除、failed / partial / errorではartifacts/video/0001.webmとして保持します。regression-replay、実LLMのfull 90-run profile、acceptance:fixtureのfull corpusは速度・容量を優先し、設定値にかかわらずvideo: falseです。必要なfailure screenshot／traceは維持します。通常runでのvideo: trueは全runを保持します。これは直前N秒だけを残す循環録画ではなく、non-pass run全体の録画です。

適応型探索

adaptive-exploreには、対象host、adapter、停止条件、recovery、mutation方針を明示したlakda.config.jsonが必要です。既存の決定的modeとは別契約です。

lakda run --base-url <approved-base-url> --mode adaptive-explore --persona <persona> --seed <seed>

設定例、adapter capability、recovery、artifact確認はRUNBOOK.mdと適応型探索仕様を参照してください。

自動・クロスプラットフォーム探索

探索Charterを入口に、PC Web／mobile WebはPlaywright、Windows／Android／iOSはoperator管理のAirtest/Poco loopback bridgeで自動探索します。Lakdaはbridgeを起動せず、未知画面では座標を推測せずunknown-screenのcoverage debtを残します。

lakda explore run --charter examples/exploration-charter.playwright.json
lakda explore resume --session .lakda/explorations/<session-id>
lakda explore report --session .lakda/explorations/<session-id> --out .lakda/reports/exploration.json
lakda explore pause --session .lakda/explorations/<session-id>
lakda explore kill --session .lakda/explorations/<session-id>
lakda explore bookmark --session .lakda/explorations/<session-id>
lakda explore fork --session .lakda/explorations/<session-id>
lakda explore acceptance --index <exploration-acceptance-index-v1.json> --trust-store <operator-trust-store.json>

Airtest/Poco bridgeの起動例はtools/airtest-poco-bridge/README.mdにあります。通常探索は録画を開始し、finding／non-passだけ保持します。回帰replay、実LLM full profile、full fixture acceptanceは録画を強制offします。各sessionはexports/artifact-manifest.json（HATE/v1）へCharter、capability、events、checkpoint、findings、report、参照run manifestを登録します。個別のfixture／real reportはlaneの技術結果であり、五laneの署名・SHA-256・HATEをlakda explore acceptanceで集約するまで実機受入へ昇格しません。

real Charterでは、署名済みlakda/exploration-target-manifest/v1とoperator trust storeをtarget接続前に検証します。Webはmanifest指定のrevision probe、nativeはbridgeが返したapp／target revision・device alias digest・serial digestを照合し、差分時はexit 2で操作0件とします。Airtest/Pocoのtemplate corpus実bytes、capability、bridge binding、revisionが一致しない場合も操作しません。ただし同梱reference bridgeのdevice identity値はCLIで与えるoperator宣言であり、実機APIによる独立観測ではありません。real acceptanceでは実機側の取得記録とmanual-bbを別途必要とし、reference bridgeだけで実観測済みとは扱いません。real artifactのbinaryは、target manifestで許可したattestorによるlakda/binary-artifact-attestation/v1のsource/output SHA-256、scan結果、署名が揃うまでHATEへ登録しません。reference bridge自身はこのattestationを生成しないため、外部scanner／attestorがないreal binary runはfail-closedです。resumeはtrace／replay-trace／checkpoint／rate budgetを再検証し、分岐が必要な場合だけ明示的なforkを使います。

nativeの独立観測と操作証跡は署名済みtarget manifest v2で扱い、CLIの初回・draft・paused resumeへ接続しています。現在は連続撮影offの設定が対象です。再開前の保存証跡照合と新しい実観測を必須にし、連続撮影の統合と実機受入は残作業として管理しています。運用手順とnative仕様を参照してください。

Run catalogと比較

runの読取りはartifactを変更しません。showとcompareは、対象runのHATE manifest、artifact bytes／size／SHA-256、graph整合を再検証し、改竄・path逸脱・未知schemaをfail-closedで拒否します。

lakda runs list --output-dir .lakda/runs
lakda runs show --run-dir .lakda/runs/<run-id>
lakda runs compare --base-run-dir .lakda/runs/<base-run-id> --head-run-dir .lakda/runs/<head-run-id> --out <comparison.json>

sanitized設定、組合せmodel、replay sequence、pending_external target manifestはexamplesにあります。readyな実target、credential、storageState、実入力は同梱していません。

組合せ探索、scouting、調査

lakda combo gen --factor-model <factor-model.json> --seed 1 --strength 2 --case-budget 50 --out <suite.json>
lakda combo verify --factor-model <factor-model.json> --suite <suite.json> --out <coverage.json>
lakda scout --config <lakda.config.json> --suite <trace-or-suite.json> --scout-mode rule-only --out <leads.json>
lakda investigate --lead <lead.json> --trace <adaptive-trace.json> --config <lakda.config.json> --reviewer <reviewer-ref> --out <investigation.json>
lakda promote --investigation <investigation.json> --kind trace --out <promotion.json>

P10の調査は、Leadと元traceを同じ設定で一度だけ再生する人間向けの手順です。

1. lakda scout でtraceからLead reportを作る。
2. lakda investigate にLead、元のadaptive/trace.json、同じlakda.config.json、reviewer参照、出力先を明示する。
3. preflightでschema/version、Lead digest、seed、base URLとallowHosts、target kind、URL scopeを検証してから、対象へ接続する。
4. 再生中はcandidateの再解決、実行status、pre/post fingerprint、settle status、popup/iframe/new-tabを含むtarget topology、generic/product/security oracleの署名を比較する。比較は一回だけで、差分・欠落・不明はfail-closedになる。
5. status=reproduced かつreplayDigest、oracleRefs、evidenceRefsが揃った場合だけlakda promoteが成功する。not_reproduced、replay_diverged、inconclusive、artifact欠落は昇格できない。

Lakdaが生成するのはredacted artifactとHATE/v1 manifestまでです。最終のGo/No-Go、QEG record、QEG verdictは外部工程です。HATEで証跡を正規化し、QEGで最終Gateを判定してください。 factor modelは安全なfixture値と専用constraint DSLだけを受け入れます。scoutはrule-firstであり、LLMが使える場合でも提示済みLead IDの選択または停止だけが許されます。promoteはstrict replayで再現済み、かつartifact／oracle参照が揃う場合だけ成功します。

安全性と証跡

• 操作はallow host、deny操作、mutation種別、操作予算、kill switchの検査後にだけ実行します。
• screenshot、trace、videoは画面上の情報を含み得るため、承認済みtargetでartifact classificationとretentionを設定し、sanitized release bundleやGitへ含めません。
• Airtest/PocoとSecurity bridgeは、Lakdaが外部processを起動せず、operator管理のloopback endpointにだけ接続します。bridgeはredirectを追跡せず、JSON content typeと1 MiBのrequest/response上限を検査します。
• Security機能は認可済み環境の補助です。passive候補を含む全candidateで独立したenvironment、host/path、HTTP method、request template digest、capability/bridge digestを照合し、実行時はpermit receiptをbridgeへ渡します。本番への攻撃的scan、無承認mutation、LLMだけによる脆弱性認定は行いません。
• text artifactはredaction、secret/PII scan、容量判定、SHA-256、HATE/v1 exportを通します。screenshot／trace／videoはtext scan済みと偽らず、通常runではredaction_status=pending、scanはnot_applicableとして保持します。real探索でbinaryをHATEへ登録するには、target manifestで許可した外部attestorの署名付きscan結果が必須です。raw prompt、認証情報、storageState、実入力値を公開証跡へ含めません。
• mock、fixture、状態注入は補助証跡です。実サーバー・実機の受入証跡とは区別します。

受入とリリースの状態

区分	状態	意味
P8〜P10ローカル機能検証	実施済み	決定性、coverage、fail-closed、replay、promotion、redactionをfixtureで検証
P11 0.5.0-rc.2 real acceptance	未実施	承認target manifest、固定revision、case単位artifactが必要。現在はpending_external
実機・認可済みsecurity target・実ZAP	未実施	operator承認と外部環境が必要
P7 real 16 AC corpus	未実施	immutable corpus、実target、artifact再照合が必要
manual-bb / QEG final Gate	0.5.0-rc.2は未実施	過去revisionの結果は履歴のみ。0.5.0-rc.2の最終判定はpending_external

P7の環境変数、corpus、case report、suite verifierの証跡条件はP7 Real Adaptive Acceptance Runbookに固定しています。AC-AE-016はEd25519署名を検証できるlakda/target-manifest/v2と、lakda/adaptive-acceptance-case/v2のSecurity audit（policy/request counter/permit/cleanup/kill switch）を必須とします。P11を含む0.5.0-rc.2のreal acceptanceには、readyな承認target manifestとrevision-bound evidenceが必要です。実target未設定時はrunnerがexit 2でpending_externalを返し、targetへ接続しません。過去の範囲限定goと残留境界は品質証跡記録、機械可読な履歴判定はQEG gate verdictを参照してください。

P7/P11のrunnerとrunbookは開発・評価用であり、npm packageには含めません。

ドキュメントの入口

確認したいこと	正本
実行方法、環境、artifact確認、失敗時復旧	RUNBOOK.md
現行v1の要件・仕様	REQUIREMENTS.md / SPECIFICATION.md
適応型探索の要件・評価	追加要件 / 一次所有仕様・評価 / 自動探索統合仕様
P8〜P11の要件・仕様・チェックリスト	拡張要件 / 拡張仕様書
設計・安全方針	BLUEPRINT.md / GUARDRAILS.md
受入証跡	docs/acceptance/
最終品質Gate	QEG gate input / verdict / record
背景調査・原資料（非規範）	docs/reference/
外部検証ツール	HATE / QEG / five-tool workflow
実装計画・Task Seed	適応型探索計画 / 拡張計画 / docs/tasks/

仕様の正本は現行v1ではREQUIREMENTS.mdとSPECIFICATION.md、適応型探索ではREQUIREMENTS-ADAPTIVE-EXPLORATION.mdとdocs/spec/adaptive-exploration/、P8〜P11ではdocs/spec/lakda-extension/です。参考調査資料だけを根拠に公開契約を変更しないでください。