AI Des2Code - マッチングアーキテクチャ

この文書は code import、variation import、design import、code-index rebuild、 Des2Code が共有する現在の matching architecture を定義します。storage は strict な current-state only で、matching は validated adapter を通じて canonical storage を既存 runtime shape に変換します。

全体フロー

flowchart LR
  backend[guinness-backend] -->|code-import| ci[SQS code-import]
  backend -->|code-variation-import| vi[SQS code-variation-import]
  backend -->|design-import| di[SQS design-import]
  backend -->|code-index| ii[SQS code-index]
  backend -->|design_id + scope + request_id| dq[SQS des2code]

  ci --> code[(DocumentDB code)]
  vi --> variation[(DocumentDB code_variation)]
  di --> design[(DocumentDB design)]
  code --> ii
  variation --> ii
  ii --> graph[(DocumentDB code_graph)]
  ii --> index[(DocumentDB code_index)]

  design --> d2c[AI Des2Code]
  code --> d2c
  variation --> d2c
  graph --> d2c
  index --> d2c
  d2c --> s3out[(S3 request artifact)]
  d2c --> webhook[Backend webhook]

PostgreSQL は backend が使う product identity/authorization source です。AI worker は PostgreSQL credential を受け取らず、Des2Code run を DocumentDB に保存しません。

Design Import 契約

Design Import は Figma design ごとに current strict design document を 1 件書きます。code index の readiness を要求せず、index を pin しません。

Input identity:

Field	Purpose
`design_id`	stable canonical `_id`
`organization_id`, `project_id`	tenant/project scope
`file_id`, `node_id`	Figma provenance
`img_url`	rendered screen image
`json_schema_url`	worker が読み検証する Figma JSON object

Persisted matching evidence:

Block	Contents
`visual.metadata`	name、image URL、layout、component type、palette、typography。vector なし
`semantics.metadata.words`	generated intent vocabulary
`semantics.vector_embedding`	512 次元 semantic vector
`structure.metadata`	visible text、generic term、bounded region、concrete component instance
`structure.vector_embedding`	512 次元 screen structure vector
`structure.metadata.regions[].vector_embedding`	512 次元 region structure vector
`processing.hash`	SHA-256 idempotency fingerprint

Design Import は Figma component/component-set identity、instance property、bounds、 hierarchy、path、visible text、summary を保持します。project-aligned term は保存せず、 Des2Code が request 時に current code_index.context.terms に対して導出します。

Code Import 契約

Code matching evidence は責務ごとに分割します。

Collection	Writer	Current content
`code`	`code-import`	source/CSS、semantic vocabulary/vector、parsed source-context/vector、non-vector visual metadata
`code_variation`	`code-variation-import`	successfully rendered Storybook state 1 件、image metadata/description、visual vector
`code_graph`	`code-index`	current resolved code reference edge
`code_index`	`code-index`	current scoped readiness 1 件、context term、per-code variation mode

effective な code / code_variation change は current code_index を stale にします。explicit rebuild は expiring single-flight lease を取得し、全 code/variation input を validate し、resolved graph edge を rebuild して ready index を transaction で publish します。

code に visual vector/embedded variation inventory はありません。render 成功した state だけを code_variation に保存し、render のない declaration は state matching に参加しません。

マッチングパイプライン

Stage	Behavior
1. Scope/readiness	exact org/project scope で design/index を読み、strict schema と `code_index.status=ready` を要求
2. Request alignment	design term と current index vocabulary を memory 上で intersect。design は mutate しない
3. Vector retrieval	screen の code semantic/context、最大 32 region の code context、screen/region の variation visual を query
4. Candidate merge	code ID で merge し semantic/context/region/variation evidence の最大値を保持
5. Graph expansion	resolved `code_graph` edge の scoped neighbor を hydrate
6. Deterministic ranking	merged bounded pool を `des2code-core` と current variation policy で rank
7. Full-catalog planning	compact aliased catalog identity を structured planner/family resolver に提示
8. Retrieval reranking	retrieved candidate のみ reorder。unknown/non-retrieved ID は order に入れない
9. Occurrence matching	image、property、text、structure、source evidence で valid Figma node を detailed aliased code に match
10. Structural ownership	layout/structural owner を resolve し supported parent/child dependency を保持
11. State resolution	state-required occurrence を known scoped `code_variation` ID に map、property から specific story を reconcile
12. Final guards	strict deterministic match、nested duplicate/unsubmittable 除去、anchor canonicalize、unsupported competitor suppress、`(nodeId, codeId)` deduplicate
13. Artifact/webhook	complete request artifact を保存し backend に通知

model-facing prompt payload は UTF-8 700,000 bytes に bound します。typed stage output は candidate/node/decision count を制限します。storage identity は temporary alias で表し、validation 後だけ元 ID に戻します。

Match Output Evidence

Implementation-level output:

Field	Meaning
`similarity`	implementation candidate の deterministic rank score
`visualSimilarity`	compatibility field。`code` に visual vector がないため現在 `null`
`semanticSimilarity`	code semantic retrieval score
`contextSimilarity`	screen-to-code context score
`regionSimilarity`	best region-to-code context score
`variationSimilarity`	parent code の best rendered-state visual score
`variationMode`	current index profile の `identity_only` / `state_required`
`evidenceCategories`, `termOverlap`, `matchedRegions`	bounded explainability evidence

Occurrence-level output:

Field	Meaning
`nodeId`, `codeId`	concrete Figma occurrence と selected implementation
`variationId`, `variationName`	resolved rendered state。absent/not required は `null`
`confidence`	validated `0..1` occurrence confidence
`evidenceCategories`, `matchedTerms`	bounded occurrence/state evidence

artifact は retrieval/usage diagnostics、current codeIndexId、effective matching bound、secret-free provider/model/prompt summary も保存します。

互換性ルール

storage contract は undeclared legacy field と invalid vector length を reject する。
canonical persisted vector は有限値 512 個である。
runtime adapter は storage を弱めず established matcher key を保持する。
codeIndexId は run が使った current scoped singleton で、historical version や PostgreSQL token ではない。
Design import は index readiness から独立し、後の code-index rebuild で design reimport は不要。
missing/stale index、scope mismatch、malformed catalog identity、unknown model ID、 invalid state identity は fail closed。
model/provider selection は environment 所有。request-level fallback/override はない。
matching は project-agnostic。hardcoded expected result ではなく imported evidence と current catalog/profile から動作する。