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

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:

<!-- DOTB_LEAD_SCORING_START -->
...
<!-- DOTB_LEAD_SCORING_END -->

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

AI Platform sinh pack, chạy --check và --validate-fixtures, sau đó review diff.
Pack được phát hành cùng AI Platform Git commit. Commit đó là immutable input của consumer verification.
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.
Hai bên chạy sandbox verification. Chỉ sau khi provider và consumer đều pass mới promote pin vào integration branch.
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.

6.2 KiB Raw Blame History