セマンティックパイプライン

セマンティックパイプラインは、契約で定義されたデータが Guida 内をどのように流れるかを記述します。データ源またはエクストラクターを、検証ゲート、マッパー、出力先へ接続し、実行前に作業内容を確認できるようにします。

パイプラインは、ワークフローフォルダー、ワーカープール、無人スケジューラーではありません。ワークフローは運用範囲を有効化し、ワーカーはキューを処理し、ワークフロー台帳は実行と項目の確定情報を永続化します。パイプラインは、明示的な来歴情報によってこれらを結び付けます。

ステージモデル

ステージ	役割
Source	入力の型またはスキーマを宣言
Extractor	名前で特定したエクストラクター契約を実行
Validator	スキーマと項目単位の限定ルールを適用
Mapper	宣言済みの契約から別の契約へ変換
Destination	キューなど、対応する出力先を指定

検証ゲート、マッパー、出力先は、それぞれ再利用可能なカタログです。データ形式や運用規則を個別スクリプトに埋め込まずに済みます。

{
  "id": "careers.example.discovery-to-fetch",
  "workflowName": "careers-crawl",
  "status": "draft",
  "stages": [
    { "id": "discover", "kind": "extractor", "extractorId": "careers.example.jobs" },
    { "id": "validate", "kind": "validator", "schema": "schemas/career-job-output.schema.json" },
    { "id": "map", "kind": "mapper", "mapperId": "careers.example.jobs.fetchPayload" },
    { "id": "enqueue", "kind": "queue", "destinationId": "careers.fetch.queue" }
  ]
}

パイプラインは直接記述するほか、テンプレートや記述子を選択するルールから生成できます。生成時の値は "extractorId": "$extractor.id" のように明示的にバインドします。Guida が ID、パス、ファイル名から会社、出力先、契約を推測することはありません。

安全に実行するまで

Draft と diff で有効な定義を解決し、ファイル変更案を表示します。
Validate で構造、参照、契約、グラフ規則を確認します。
Preflight で現在のワークスペースと運用上の前提条件を確認します。
Plan でステージ、接続、予定される変更、必要な能力、ポリシー、認証情報、来歴、復旧情報、ブロック要因、警告を確認します。
Preview で正確な提案内容のハッシュと、実行準備が整っているかを確認します。
Start では入力とキュー上限を明示します。影響の大きい操作には確認とポリシーが適用されます。

保存、削除、実行は別々の操作です。下書きを開いたり保存したりしただけで実行が始まることはありません。

実行時にはワークフロー実行との関係を明示的に作成します。キュー出力先は、独立した実行を作るか、既存の実行を使うかを宣言します。Guida はステージ状態、依存関係、出力参照、重複排除、運用結果を記録します。

workspace.pipelines.execution.lifecycle.get は、パイプラインが管理する実行状態とステージの進行状況を返します。後続処理のプレビュー、開始、制御は別々の呼び出しです。キューと台帳の結果は明示的に照合されるため、キューが空であることだけでは成功を証明できません。

Remote Ops API は、一覧、下書き、差分、検証、preflight、計画、プレビュー、開始、結果、根拠、後続処理、制御の各契約を提供します。 Guida Control はこれらを利用し、下書きの保存だけでパイプラインを開始することはありません。