@01.works/reference-contracts

Design Context API, catalogue, collector가 공유하는 공개 API DTO와 portable layout manifest의 런타임 계약 패키지입니다.

pnpm add @01.works/reference-contracts

• DB row, Worker binding, HTTP client 구현은 포함하지 않습니다.
• manifest TypeScript 타입, runtime validator, canonical JSON Schema와 schema/extractor version, quality flag 분류를 한 곳에서 제공합니다.
• 런타임 dependency와 코드 생성 단계가 없습니다.
• 공개 응답 필드를 변경할 때 서버 반환 타입과 catalogue 사용처를 함께 검사합니다.

validateManifest(), validateLayoutMap(), validateSemanticEvidence()는 지원한다고 명시한 버전만 받아들이며, matchesArtifactSignature()는 artifact kind별 MIME과 최소 파일 signature·container 구조가 일치하는지 검사합니다. 이 검사는 손상된 header, 누락된 payload 같은 명백한 불일치를 거르는 ingest gate이며 CRC 검증이나 이미지의 완전한 decode 가능성을 보장하지 않습니다. LayoutManifest와 LayoutAnalysisMap은 검증 후 값의 TypeScript 표현입니다. portable 구조를 검사하는 JSON Schema는 @01.works/reference-contracts/schemas/layout-package.json, @01.works/reference-contracts/schemas/layout-map.json, @01.works/reference-contracts/schemas/visual-tile-set.json subpath로 제공합니다. 선택적 metadata.classification은 사이트 전체가 아니라 현재 대표 capture의 분류이며 version, 정확히 하나의 categories, 대표 screenshot의 evidenceSha256, classifiedAt만 저장합니다. 카테고리는 페이지의 지배적인 표현 방식 하나이며 배열은 저장 형식 호환을 위해서만 유지합니다. 미분류는 별도 enum이 아니라 classification 부재로 표현합니다. JSON Schema로 직접 표현할 수 없는 cross-field 의미 규칙인 region ID 고유성과 extraction.emitted_regions === regions.length, classification evidence와 대표 screenshot의 checksum 일치는 runtime validator가 추가로 검사합니다. JSON Schema의 format은 validator 설정에 따라 annotation으로만 처리될 수 있으므로, URL을 실제로 수락하는 경계에서는 validateManifest()를 호출해야 합니다. 런타임 validator는 optional URL의 null을 허용하되 필수 requestedUrl은 parse 가능한 HTTP(S) 문자열만 받습니다. 저장 계약의 URL은 new URL(input).href와 같은 canonical form이어야 합니다. 사용자 입력을 받는 호출자는 contract 검증 전에 별도로 정규화하며 validator 자체는 noncanonical URL을 암묵적으로 고쳐 저장하지 않습니다.

Artifact 신뢰 경계

• collector가 새 package를 만들 때 screenshot은 선택적 full-page preview와 preview/thumbnail 생성 과정에서 Sharp로 decode되며, 파생 WebP의 실제 dimensions도 Sharp metadata로 확인합니다.
• validatePackage()는 manifest/layout-map 의미, regular-file·symlink 경계, 크기, hash와 최소 signature를 검사합니다. PNG/JPEG/GIF/WebP header dimensions와 descriptor, layout-map과 viewport, wireframe SVG root와 map document dimensions도 비교하지만 모든 raster pixel이나 region별 wireframe geometry를 다시 decode·비교하지는 않습니다.
• Design Context API ingest는 scoped uploader를 신뢰 경계로 두고 크기, hash, 선언 MIME과 동일한 최소 cross-artifact 비교를 수행합니다. 임의 media를 완전한 decoder로 정화하는 API가 아닙니다. dimension parser가 없는 AVIF는 0.4 captured raster artifact에서 허용하지 않으며, favicon과 0.3 호환 artifact에서는 signature gate만 적용합니다.

Extractor 0.7 captured package는 positive document dimensions, responsive rendition과 표현 구조 측정값을 포함한 semantic evidence JSON artifact가 필수입니다. 0.7.1은 여기에 capture environment/semantic consistency 관측과 extraction coverage를 추가합니다. 이 요구는 버전 문자열 비교가 아니라 EXTRACTOR_CONTRACTS의 requireCaptureObservations와 requireExtractionCoverage capability로 dispatch합니다. 0.5는 같은 responsive image 계약을 semantic artifact 없이 유지하고, 0.4는 screenshot/preview/thumbnail descriptor dimensions를 요구합니다. 0.3 호환 package는 해당 dimension fields가 존재할 때만 header와 비교합니다. layout-map과 wireframe의 viewport/document consistency는 모든 지원 버전에 적용됩니다.

VisualTileSet은 완전한 document coverage를 가진 PNG 타일 묶음의 독립 transport 계약입니다. 각 타일은 document CSS 좌표와 원본 DPR의 bitmap dimensions, portable path, bytes, checksum을 기록합니다. runtime validator는 타일 순서·경계·경로 중복·bitmap dimensions와 2차원 전체 coverage를 검사합니다. 안정성·seam·resource readiness는 transport 바깥의 quality 판정으로 유지합니다. 이 계약은 아직 manifest extractorVersion이나 API publication capability를 승격하지 않습니다.

LayoutReferenceBundle은 /v1/layouts/:id/reference의 read-only 응답 타입입니다. LayoutDetail과 절대 resource URL만 묶으며 구현 지시, 코멘트, write-back 상태는 포함하지 않습니다. 현재 reference schema version은 1.0, kind는 layout-reference입니다.

Catalogue 전용 폴더·사용자·제출 DTO는 core reference 계약과 release surface를 분리한 @01.works/reference-contracts/catalogue subpath에서 제공합니다. 폴더 API는 목록용 CatalogueFolderSummary, 항목 페이지용 CatalogueFolderItemPage, 항목 추가 결과용 CatalogueFolderItemMutationResult를 구분합니다.

Agent setup prompt와 제품별 orchestration 정책은 이 계약 패키지에 포함하지 않습니다. 프레임워크 비종속 prompt compiler와 workflow readiness는 @01.works/reference-client가 소유하며, Catalogue 앱도 같은 공개 API를 사용합니다.

0.2에서 0.3으로 이전

0.3은 compact LayoutCardViewportAssets에 overlayAvailable을 추가합니다. 합성된 overlayUrl은 artifact 존재 여부와 무관하게 제공될 수 있으므로, 현재 viewport에서 오버레이 수정이 가능한지는 URL truthiness가 아니라 이 boolean으로 판정해야 합니다. LayoutRun과 LayoutDetail에서는 기존처럼 artifacts의 layoutMap 또는 overlay가 authoritative signal입니다.

0.1에서 0.2로 이전

0.2는 1.0 이전 계약을 정리하는 breaking release입니다. 소비자는 정확한 버전을 고정하고 다음 변경을 함께 적용합니다.

• LayoutRun.category는 categories로 바뀌었으며 공개 응답에서는 [] 또는 정확히 한 값입니다.
• manifest의 metadata.classification.category는 저장 형식 호환을 위한 단일 원소 categories tuple로 바뀌었습니다.
• category ID는 collection | overview | showcase | sequence | visualization | workspace | scene으로 교체되었습니다. 0.1 ID를 새 ID로 추측 변환하지 말고 미분류로 되돌린 뒤 필요할 때 다시 판정합니다.
• current extractor는 0.7이며 0.3, 0.4, 0.5 package를 읽기 호환합니다. 0.7 captured viewport는 responsive rendition과 semanticEvidence가 필요합니다.
• CatalogueSiteReference.id는 항상 존재합니다. 폴더 항목 수정·삭제·정렬에는 URL이나 layout ID가 아니라 이 item ID를 사용합니다.
• LayoutRun.renditions가 production DTO와 동일하게 공개 타입에 포함됩니다.
• reference bundle은 complete, 양 viewport captured, 빈 readiness reason, extractor별 필수 artifact를 만족하는 agent-ready snapshot입니다.
• artifactCount/artifactBytes는 저장된 전체 artifact 합계이므로 공개 artifacts 배열에는 equality가 아니라 하한 관계를 보장합니다.
• 공식 catalogue URL은 /layouts/:id입니다. 0.1의 /?layout=:id는 client 입력 호환 목적으로만 계속 읽습니다.

Visual composition taxonomy는 제품의 공개 reference 계약이 아니라 비공개 사례 연구입니다. @01.works/reference-contracts는 해당 registry나 enum을 export하지 않습니다.