AI Des2Code - I/O Definition

This page is the official I/O contract for apps/des2code/. Any field, shape, status, or failure-mode change must be reflected here and in Test Case Design before implementation is merged.

Overview

flowchart LR
  api[guinness-backend] -->|SendMessage| Q[(SQS des2code)]
  Q --> L[AI Des2Code worker]
  L -->|scoped canonical reads| D[(DocumentDB<br/>design/code/variation/graph/index)]
  L -->|PutObject request artifact| S3[(S3 backend AI bucket)]
  L -->|POST /v1/webhooks/ai-status| api
  api -->|list latest design artifact| S3
  L -->|structured logs + metrics| Logs[(CloudWatch / logs)]

Item	Value
Trigger	SQS record on the `des2code` queue
Reads	DocumentDB `design`, `code`, `code_variation`, `code_graph`, `code_index`; design image from S3 URL
Writes	Request-scoped S3 success/failure artifact + webhook POST
RDB writes	None by the worker; the backend webhook validates scope and logs status without persisting a Des2Code run/result
Webhook	Required success/failure notification to `POST /v1/webhooks/ai-status`
Model calls	Required bounded structured matching stages when retrieval has candidates
Empty retrieval	Success with empty `matchedCodes` and `usageMatches`
Result retention	`expiresAt` is generated from `DES2CODE_RESULT_TTL_DAYS`; bucket lifecycle is infrastructure-owned

Input

SQS Message

Lambda receives a standard AWS SQS event. Records[*].body contains a JSON string with exactly the worker fields below. Both snake_case and camelCase are accepted by the worker; the backend producer uses snake_case.

{
  "Records": [
    {
      "messageId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
      "body": "{\"design_id\":\"42_hDDA9BNori9OTXSClduXqR_40002029:37033\",\"project_id\":42,\"organization_id\":1,\"request_id\":\"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b\"}"
    }
  ]
}

Field	Type	Required	Validation	Notes
`design_id`	string	Yes	non-empty; extra fields forbidden	Must equal canonical `design._id`.
`project_id`	integer	Yes	`gt=0`	Project scope for every DocumentDB read.
`organization_id`	integer	Yes	`gt=0`	Tenant scope for every DocumentDB read.
`request_id`	string	No	length `1..255`	Backend supplies UUIDv7. Fallback is SQS `messageId`, then `design_id`.

The payload does not contain schema version, operation name, code-index token, model override, prompt override, or matching bounds. Runtime configuration owns those choices.

DocumentDB `design` Read

Property	Value
Collection	`DESIGN_TABLE_NAME`, default `design`
Operation	scoped `find_one` by `_id`, `organization_id`, and `project_id`
Validation	strict `DesignDocument` storage schema through `design_to_runtime`
Missing document	failure path; persist/report failure when the SQS body is valid, then re-raise
Scope mismatch	rejected before retrieval

Fields consumed after strict storage-to-runtime adaptation:

Stored field	Runtime field	Usage
`visual.metadata.image_url`	`image_url`	Download the design image for image-aware stages
`semantics.metadata.words`	`semantic.terms`	aligned terms and compact design evidence
`semantics.vector_embedding`	`semantic.embedding`	screen semantic query and variation visual query
`structure.metadata.visible_text`	`structure.visible_text`	aligned terms and matching evidence
`structure.metadata.generic_terms`	`structure.generic_terms`	aligned terms and matching evidence
`structure.vector_embedding`	`structure.embedding`	screen code-context retrieval
`structure.metadata.regions[].vector_embedding`	`structure.regions[].embedding`	at most 32 region context/variation searches
`structure.metadata.component_instances`	`structure.component_instances`	occurrence identity, properties, hierarchy, and state evidence

Both screen embeddings and every searched region embedding must have exactly 512 finite dimensions. structure.aligned_terms is derived against the current index context for this run and is never written back to design.

DocumentDB `code` Retrieval

The worker uses five canonical collections. All reads are constrained by organization_id and project_id.

Collection	Read behavior
`code_index`	Load the single current scoped document and require `status=ready`. Read `_id`, `context.terms`, and `profile.components`.
`code`	Vector-search `semantics.vector_embedding` and `context.vector_embedding`; hydrate candidates/graph neighbors; load the full scoped catalog.
`code_variation`	Vector-search `visual.vector_embedding`; load the full scoped rendered-state catalog.
`code_graph`	Read resolved edges where retrieved code is source or target and expand neighbors.
`design`	Read the one canonical input described above.

Property	Value
Vector dimensions	`512`
Screen searches	code semantic + code context + variation visual
Region searches	code context + variation visual for at most 32 regions
Candidate bound	each vector query uses `VECTOR_SEARCH_K`; merged ranking pool is capped by `CANDIDATE_POOL_SIZE`
Atlas strategy	`$vectorSearch` with inline organization/project filter and `numCandidates=VECTOR_SEARCH_EF_SEARCH`
DocumentDB strategy	scoped `$match` before exact `$vectorSearch`; scope must not exceed `DOCUMENTDB_SCOPED_VECTOR_MAX_DOCS`; cosine score is calculated in process
Graph expansion	resolved scoped source/target neighbors only
Full catalog	all scoped `code` and `code_variation` documents for occurrence/state matching

code has no visual vector. visualSimilarity therefore remains null in the current result contract. Visual implementation-state evidence comes from code_variation and is exposed as variationSimilarity.

Runtime Configuration

Environment Variable	Type	Default	Validation	Usage
`DOCUMENTDB_CONNECTION_STRING`	string	empty	required operationally	DocumentDB/Atlas URI
`DOCUMENTDB_NAME`	string	`guinness_v2`	non-empty operationally	Database name
`DESIGN_TABLE_NAME`	string	`design`	canonical collection	Design input
`CODE_TABLE_NAME`	string	`code`	canonical collection	Code catalog/retrieval
`CODE_VARIATION_TABLE_NAME`	string	`code_variation`	canonical collection	Rendered states
`CODE_GRAPH_TABLE_NAME`	string	`code_graph`	canonical collection	Resolved dependencies
`CODE_INDEX_TABLE_NAME`	string	`code_index`	canonical collection	Current readiness/profile
`VECTOR_SEARCH_PROVIDER`	enum	`documentdb`	`documentdb` / `atlas`	Query strategy
`DOCUMENTDB_SCOPED_VECTOR_MAX_DOCS`	integer	`10000`	`1..100000`	Exact DocumentDB scope ceiling
`MAX_MATCHES`	integer	`10`	`gt=0`	Initial implementation-order cap
`VECTOR_SEARCH_K`	integer	`100`	`gt=0`	Per-query result count
`VECTOR_SEARCH_EF_SEARCH`	integer	`500`	`>= VECTOR_SEARCH_K`	Atlas `numCandidates`
`CANDIDATE_POOL_SIZE`	integer	`80`	`1..500`	Merged deterministic ranking pool
`MATCHING_MODEL`	string	none	required `provider:model`	All structured matching agents; deployed value: `openai:gpt-5.6-luna`
`MATCHING_TIMEOUT_SECONDS`	float	`300`	`0..600`	Per-model-call timeout
`MATCHING_OUTPUT_TOKENS`	integer	`14000`	`1..20000`	Model output budget
`EMBEDDING_PROVIDER`	enum	`openai`	`openai` / `openrouter`	Semantic family embeddings
`EMBEDDING_MODEL`	string	none	non-empty	Provider model ID passed unchanged
`EMBEDDING_DIMENSIONS`	integer	`512`	exactly `512`	Family embedding dimension
`AI_MAX_RETRIES`	integer	`3`	`gte=0`	Embedding provider retries
provider API key	string	empty	selected provider key required	`OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENROUTER_API_KEY`
`S3_BUCKET_NAME`	string	none	non-empty	Design image reads and result artifacts
`DES2CODE_RESULT_TTL_DAYS`	integer	`30`	`gt=0`	Artifact `expiresAt`
`WEBHOOK_BASE_URL`	string	empty	required in production	Backend AI-status URL
`WEBHOOK_API_KEY`	string	empty	required in production	`X-API-Key` webhook authentication

Processing Contract

Unwrap and strictly validate the SQS body.
Fetch and validate the canonical design in the same organization/project.
Load the current scoped code_index; fail closed when missing or stale.
Require 512-dimensional design semantic/structure/region vectors.
Derive code-aligned terms from the design and code_index.context.terms in memory.
Run screen and bounded region retrieval against code semantic/context and variation visual indexes.
Merge candidates by code_id, retaining the maximum score per evidence axis.
Expand resolved scoped code_graph neighbors and hydrate their source evidence.
Load the full scoped code and rendered-variation catalog.
Deterministically rank the bounded retrieval pool using des2code-core and the current code_index.profile.
Run the typed model workflow: candidate planning, semantic/model family resolution, retrieval reranking, occurrence matching, structural matching, and state resolution.
Validate all temporary aliases against known scoped code/node/variation IDs; add deterministic matches, suppress unsupported competitors, and deduplicate (nodeId, codeId) occurrences.
Build matchedCodes, usageMatches, retrieval diagnostics, and usage diagnostics.
Persist one success artifact at the request-scoped S3 key.
POST the success webhook with the result and artifact metadata.

No source code is generated. No Des2Code result is written to DocumentDB or PostgreSQL. The matching model and embedding provider are mandatory service configuration; callers cannot disable stages or override models.

Output

Internal Success Payload

process_record() returns this shape for tests and local scripts. The Lambda handler returns the standard SQS partial-batch-failure response.

{
  "type": "des2code",
  "recordId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "organizationId": 1,
  "status": "success",
  "result": {
    "matchedCodeCount": 1,
    "matchedCodes": [
      {
        "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
        "name": "Button",
        "semanticValue": ["button", "action", "cta"],
        "similarity": 0.92,
        "visualSimilarity": null,
        "semanticSimilarity": 0.89,
        "contextSimilarity": 0.84,
        "regionSimilarity": 0.91,
        "variationSimilarity": 0.95,
        "variationMode": "state_required",
        "evidenceCategories": ["semantic", "context", "variation"],
        "termOverlap": ["button", "submit"],
        "matchedRegions": ["40002029:37101"],
        "sourceCode": "export default Button;",
        "cssCode": ".button { ... }"
      }
    ],
    "matchedUsageCount": 1,
    "usageMatches": [
      {
        "nodeId": "40002029:37101",
        "codeId": "0192a3b4-c5d6-4e8f-9a0b-1c2d3e4f5a6b",
        "variationId": "visual_primary",
        "variationName": "Primary",
        "confidence": 0.97,
        "evidenceCategories": ["instance/property identity", "visible text"],
        "matchedTerms": ["submit", "primary"]
      }
    ],
    "retrievalDiagnostics": {
      "semanticHitCount": 20,
      "contextHitCount": 20,
      "regionSearchCount": 8,
      "variationHitCount": 40,
      "graphEdgeCount": 12,
      "candidatePoolCount": 80
    },
    "usageDiagnostics": {}
  }
}

Field	Type	Notes
`matchedCodeCount`	integer	Must equal `matchedCodes.length`.
`matchedCodes`	array	Unique selected implementations, including source/CSS for backend API clients.
`matchedUsageCount`	integer	Must equal `usageMatches.length`.
`usageMatches`	array	Concrete `(nodeId, codeId)` occurrences with optional rendered state.
`retrievalDiagnostics`	object	Bounded counts only; no secrets, prompts, or vectors.
`usageDiagnostics`	object	Stage counts/failures and reconciliation diagnostics.

S3 Result Artifact

The worker writes one logical object per request ID:

Property	Value
Bucket	`S3_BUCKET_NAME`
Success key	`{organization_id}/{project_id}/des2code/{design_id}/{request_id}.json`
Failure key	`{organization_id}/{project_id}/des2code/{design_id}/{request_id}-failed.json`
Content type	`application/json`
Object tag	`des2code_result=true`
Expiry metadata	`generatedAt + DES2CODE_RESULT_TTL_DAYS`

Success artifact shape:

{
  "type": "des2code",
  "recordId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "designId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "organizationId": 1,
  "requestId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "codeIndexId": "code-index-<scope-sha256>",
  "status": "success",
  "generatedAt": "2026-08-11T10:00:00Z",
  "expiresAt": "2026-09-10T10:00:00Z",
  "matcherConfiguration": {
    "candidatePoolSize": 80,
    "maxMatches": 10,
    "vectorSearchK": 100
  },
  "modelSummary": {
    "requestedModel": "openai:gpt-5.6-luna",
    "provider": "openai",
    "promptVersion": "des2code-production-v2",
    "allowFallbacks": false,
    "executedStages": ["planner", "reranker", "matcher", "state-resolver"]
  },
  "result": {
    "matchedCodeCount": 1,
    "matchedCodes": [],
    "matchedUsageCount": 1,
    "usageMatches": [],
    "retrievalDiagnostics": {},
    "usageDiagnostics": {}
  }
}

modelSummary is generated by the shared model policy and does not contain API keys or full prompts. codeIndexId is the stable _id of the current scoped DocumentDB index used by this run, not a version/history token.

Webhook - Success

{
  "type": "des2code",
  "recordId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "organizationId": 1,
  "status": "success",
  "result": {
    "matchedCodeCount": 1,
    "matchedCodes": [],
    "matchedUsageCount": 1,
    "usageMatches": [],
    "retrievalDiagnostics": {},
    "usageDiagnostics": {}
  },
  "artifact": {
    "bucket": "dev-guinness-backend",
    "key": "1/42/des2code/42_hDDA9BNori9OTXSClduXqR_40002029:37033/0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b.json",
    "contentType": "application/json",
    "expiresAt": "2026-09-10T10:00:00Z"
  }
}

The backend validates the PostgreSQL design/project/organization scope and logs the notification. It does not persist the result or artifact reference.

Webhook - Failure

{
  "type": "des2code",
  "recordId": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
  "projectId": 42,
  "organizationId": 1,
  "status": "failed",
  "error": {
    "message": "code index is missing or stale"
  },
  "artifact": {
    "bucket": "dev-guinness-backend",
    "key": "1/42/des2code/42_hDDA9BNori9OTXSClduXqR_40002029:37033/0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b-failed.json",
    "contentType": "application/json",
    "expiresAt": "2026-09-10T10:00:00Z"
  }
}

A failure artifact is written only when the flat SQS body can be validated and the success artifact has not already been written. When the success artifact exists but webhook delivery fails, the worker reports failure without replacing the success artifact with a failure object.

Error Handling

Condition	Artifact	Webhook	Lambda behavior
Missing `Records` envelope	None	None	raise handler error
Invalid SQS body or unknown extra field	None unless IDs validate through `SqsBody`	only when safe body is available	record is returned in `batchItemFailures`
Design missing/scope mismatch	failed artifact	failed webhook	re-raise for retry
Invalid 512-dimensional design/region vector	failed artifact	failed webhook	re-raise for retry
Missing/stale `code_index`	failed artifact	failed webhook	re-raise for retry
Scoped DocumentDB corpus exceeds exact-search ceiling	failed artifact	failed webhook	re-raise for retry
Model/reconciliation failure	failed artifact	failed webhook	re-raise for retry
S3 success write failure	best-effort failed artifact	failed webhook	re-raise for retry
Webhook failure after success write	keep success artifact	failure notification attempted without artifact	re-raise for retry

The Lambda handler processes records independently and returns only failed message IDs so successful records are not retried.

Idempotency

SQS delivery is at least once. Backend-generated request_id is stable for one trigger and becomes the artifact filename. A retry of the same SQS message writes the same object key. A separate trigger receives a new UUIDv7 and creates a separate request artifact under the same design prefix.

The backend GET route lists canonical success and -failed filenames under the authorized design prefix and returns the newest object by S3 LastModified (then key as a deterministic tie-breaker). It validates artifact org/project/ design identity and the complete success/failure contract before returning it.

Field Reference

Source	Worker usage	Artifact / API field
SQS `design_id`	scoped design lookup and artifact prefix	`recordId`, `designId`
SQS `request_id`	correlation and idempotent artifact filename	`requestId`
`code_index._id`	selected current index identity	`codeIndexId`
`code_index.context.terms`	in-memory aligned-term derivation	diagnostics only
`code_index.profile.components[].variation_mode`	identity/state policy	`matchedCodes[].variationMode`
`design.semantics.vector_embedding`	code semantic + variation visual query	not emitted
`design.structure.vector_embedding`	code context query	not emitted
`design.structure.metadata.regions[]`	region retrieval and matched region IDs	`matchedCodes[].matchedRegions`
`design.structure.metadata.component_instances[]`	occurrence/state identity	`usageMatches[].nodeId`, evidence
`code.semantics.vector_embedding`	semantic retrieval	`semanticSimilarity`
`code.context.vector_embedding`	context/region retrieval	`contextSimilarity`, `regionSimilarity`
`code_variation.visual.vector_embedding`	rendered-state retrieval	`variationSimilarity`
`code_graph` resolved edges	candidate expansion	retrieval diagnostics
Matching reconciliation	component and state selection	`matchedCodes`, `usageMatches`, diagnostics