--- title: Lead Scoring Contract Pack v1 description: Quy trình phát hành, ghim phiên bản và kiểm chứng Contract Pack dùng chung giữa AI Platform và DotB-Omni. status: draft tags: - lead-scoring - contract-pack - integration --- # Lead Scoring Contract Pack v1 ## Quyền sở hữu và nguồn sự thật AI Platform sở hữu Contract Pack được sinh từ các Pydantic models trong `src/lead_scoring/schemas/`. DotB-Omni review và consume artifact đã phát hành, nhưng không tạo schema, payload hoặc fixture wire-format cạnh tranh. Master specification vẫn sở hữu product behavior, scope và cross-service invariants; Contract Pack sở hữu exact shape, field constraints, enum, error taxonomy và golden examples. Pack version hiện tại là `0.1.0`, ở trạng thái pre-release và nằm tại `contracts/lead-scoring-contract-pack/v1/`. API major `v1` không đồng nghĩa với việc mọi thay đổi trong pre-release đều tương thích. Consumer phải ghim cả pack version và AI Platform Git commit đã sinh pack. ## Sinh và kiểm tra ```text uv run generate-contract-pack uv run generate-contract-pack --validate-fixtures uv run generate-contract-pack --check ``` Generator tạo deterministic `openapi.json`, JSON Schemas, `contract.json`, `error-taxonomy.json`, `outcome-taxonomy.json`, `security-profile.json`, `fixture-index.json`, compatibility workflow, shared API và Marker Block fixtures cùng `SHA256SUMS`. `--check` thất bại nếu file thiếu, nội dung khác với Pydantic source of truth hoặc xuất hiện file ngoài danh sách generated. Không sửa tay các artifact trong pack. Các generator standalone cho polling và webhook vẫn được giữ để tương thích với các lát cắt đã phát hành. Pack versioned này lấy output của chúng làm một phần fixture corpus. `fixtures/tenant-unavailable.json` và `schemas/webhook-ingest-error-response.schema.json` giữ nguyên contract đã phát hành: HTTP 404 với `subscriber_tenant_unavailable` và detail cố định, không tiết lộ tenant, account hoặc mapping reason. ## Phạm vi artifact | Profile | Schema hoặc artifact chính | |---|---| | Canonical Snapshot | `schemas/canonical-snapshot.schema.json` | | Scoring Config | `schemas/scoring-config.schema.json`, `schemas/scoring-config-selection.schema.json` | | Admission | `schemas/admission-request.schema.json`, `schemas/admission-response.schema.json` | | Polling | `schemas/polling-response.schema.json` | | Review | `schemas/review-request.schema.json`, `schemas/review-response.schema.json` | | Lineage | `schemas/lineage.schema.json` | | EMS Marker Block | `fixtures/marker/` với golden input/output JSON | | Webhook events | `schemas/webhook-event-envelope.schema.json`, terminal và reviewed event schemas | | Errors and outcomes | `error-taxonomy.json`, `outcome-taxonomy.json`, `schemas/error-response.schema.json` | | API | `openapi.json` | | Examples | `fixtures/` với positive và negative corpus | `contract.json` liên kết từng profile với version và schema file. Event envelope luôn bao gồm event identity/type/version, tenant, subject, config version, `run_id`, `run_created_at`, `occurred_at` và structured data. Raw V-Key, snapshot, conversation evidence và raw PII không thuộc event fixture. ### EMS Marker Block fixtures Marker Block dùng delimiter HTML comment ổn định: ```text ... ``` Template canonical gồm `Score`, `Confidence`, `Mode`, `Degraded`, `Config`, `Run` và `Run created`, mỗi field trên một dòng. Append dùng đúng hai newline làm separator. Các fixture trong `fixtures/marker/` mô tả input description, marker input, expected output hoặc `marker_block_malformed`, và cờ `writeback`. Phạm vi chỉ là calculated pre-review score; failed run không render hoặc ghi Marker. ## Ghim và nâng cấp giữa hai repository 1. AI Platform sinh pack, chạy `--check` và `--validate-fixtures`, sau đó review diff. 2. Pack được phát hành cùng AI Platform Git commit. Commit đó là immutable input của consumer verification. 3. Omni cập nhật pin tới đúng pack version và commit, rồi chạy consumer tests trực tiếp trên cùng thư mục `fixtures/`, không copy hoặc rewrite payload. 4. Hai bên chạy sandbox verification. Chỉ sau khi provider và consumer đều pass mới promote pin vào integration branch. 5. Một release mới không được sửa nội dung của pack đã được pin. ### Thay đổi additive tương thích Giữ cùng API major, không thay đổi required fields, enum values, semantics hoặc error handling hiện có. Field mới phải optional đối với consumer cũ. Provider validation chạy fixtures hiện hành bằng schema consumer cũ và thêm fixture chứng minh field mới là optional. Commit pin chỉ được cập nhật sau khi consumer cũ vẫn pass. ### Thay đổi breaking Tạo API major directory và Contract Pack version mới. Giữ pack cũ để consumer đang ghim tiếp tục chạy. Provider và consumer phải chạy fixture corpus của version mới trong sandbox trước khi Omni đổi pin. Không dùng `--check` để hợp thức hóa việc sửa artifact của version đang được ghim. ## Provider và consumer fixture validation `fixture-index.json` đánh dấu các positive fixtures dùng chung cho provider và consumer, cùng negative fixtures phải bị từ chối. AI Platform chạy provider-side validation bằng `validate_fixture_corpus`. Omni dùng các path tương ứng để kiểm tra parser, event auth, ordering, duplicate/stale acknowledgement và writeback boundary trong repository của mình. Error text không phải contract ổn định; test phải kiểm tra error code, HTTP status và retry semantics theo taxonomy. Contract Pack không phát hành monitoring vendor, deployment platform, public replay API hoặc EMS Marker implementation. Webhook ingest acknowledgement và EMS writeback vẫn là hai lifecycle riêng; tenant-unavailable response tiếp tục dùng operational DLQ replay theo contract đã phát hành.