AI Status Webhook

POST /api/v1/webhooks/ai-status は Guinness worker が X-API-Key（timing-safe comparison で検証）を付けて呼びます。Worker は PostgreSQL に write せず、backend が callback を検証して lifecycle transition を適用します。

実装済み type union:

• design-import、code-import、des2code: standard camelCase envelope。
• wf2des: WF2Des worker envelope。
• page_import: 独立した Page Import terminal envelope。
• code2des: 独立した Code2Des terminal envelope。

page-import と code2wf は discriminator として受け付けません。

Page Import

{
  "type": "page_import",
  "job_id": "page-import-id",
  "attempt": 1,
  "nonce": "enqueue-nonce",
  "status": "succeeded",
  "result_manifest_url": "s3://bucket/1/7/page-import/page-import-id/manifest.json",
  "manifest_schema_version": 1
}

status は succeeded または failed で、failure は error.message を含められます。Backend は row の nonce、manifest の bucket／tenant prefix、job ID、attempt、nonce、row_effects.page_import を検証して processing row を completed／failed に compare-and-set します。

Success row effect は result_url、capture_hash、screenshot_url を供給します。Page Import completion は Code2Des を作成・失敗・dispatch しません。Duplicate terminal callback は idempotent です。

Code2Des

{
  "type": "code2des",
  "job_id": "code2des-id",
  "attempt": 1,
  "nonce": "enqueue-nonce",
  "status": "succeeded",
  "result_manifest_url": "s3://bucket/1/7/code2des/code2des-id/manifest.json",
  "manifest_schema_version": 1
}

同じ identity／tenant-prefix guard を適用します。Success の row_effects.code2des は result_url と warning_count、failure は failure result pointer を供給し、callback は error.message を含められます。

WF2Des

wf2des generation worker は DesignSpec と result manifest を DocumentDB/S3 に書いた後、この Webhook で run の進捗を報告する。この handler は wf2des PostgreSQL row への 唯一の completion-time writer である。row を parse checkpoint へ進め、terminal status へ flip する。この Webhook を呼ぶのは 2 つの generation phase（parse, assemble）だけであり、内部 wf2des run（wf_parse, rule_process, component_sweep, component_capture）は決して呼ばない。

WF2Des は job_id（wf2des row id）、positive attempt、nonce、parse_started／parse_done／assemble_started／succeeded／failed status を使用します。Terminal state では result_manifest_url が必須で、phase signal には付きません。backend は manifest の guarded row_effects.wf2des transition を適用します。

status	wf2des row effect
parse_started	phase を parse にする
parse_done	phase を awaiting_confirm にする。row は status '0' processing のまま。auto-confirm path では送られない
assemble_started	auto-confirm path で phase を assemble にする。interactive confirm 後は no-op
succeeded	S3 manifest を読み、row_effects.wf2des の result_url ＋ flag_count とともに status を '1' completed へ flip し、phase を clear する
failed	status を '2' failed へ flip し、error と failure result pointer を記録し、phase を clear する

すべての transition は attempt-guarded で row の現在 state に gate されるため、再配送または superseded な callback は no-op になります。wf2des row が存在しない場合は 404 を返して SQS に再配送させ、manifest が読めない／不正な場合は 500 を返します。

Standard envelope

design-import、code-import、des2code は recordId、projectId、organizationId、status: success|failed、optional result、optional error.message、Des2Code の optional artifact metadata を使います。Backend は type ごとの既存処理前に tenant scope を検証します。

Response

{
  "message": "Status updated successfully",
  "type": "page_import",
  "recordId": "page-import-id",
  "status": "success"
}

名前	型	説明
message	string	人間が読める status message
type	string	request type の echo
recordId	string	request record ID の echo（wf2des などの job_id envelope では job_id を echo する）
status	string	request status を success または failed として echo

Acknowledgement は worker の succeeded（および WF2Des の phase signal）を success に normalize します。

エラーハンドリング

説明	ステータスコード	ステータス名
API key が不正または missing	401	Unauthorized
request body が不正	422	Unprocessable Entity
organization/project/record scope が見つからない	404	Not Found
内部サーバーエラー	500	Internal Server Error

worker は non-2xx webhook response を retryable processing failure として扱い、SQS が message を再配送できるようにする。