{"name":"The Leo King Business Intelligence API Conformance","version":"v1","status":"public-contract","contractVersion":"2026-07-09.enterprise-trust-paid-route-ci-gate-v1","lastReviewedAt":"2026-07-09","policy":{"status":"live","cadence":["Before push or deploy that changes API contracts, docs, SDKs, auth, billing, or AI generation behavior.","After production deploys that affect gateway routing, public metadata, OpenAPI, SDKs, usage logging, or paid route behavior.","Before enterprise demos, procurement review, package publication, custom limits, or signed customer launch."],"requiredBefore":["publishing SDK packages","approving enterprise procurement packets","raising rate limits","launching a signed partner integration","declaring AI generation logic healthy after deploy"],"launchGates":["Production env guard prints READY FOR PUSH/DEPLOY for the target environment.","Public metadata routes, OpenAPI, Postman, docs, llms files, sitemap, and robots discovery all agree.","API reference smoke proves catalog examples, SDK snippets, OpenAPI paths, Postman items, and docs links agree.","SDK source, generated dist, README snippets, and public endpoint catalog stay in sync.","Dedicated gateway smoke passes against https://api.theleokingai.com.","Paid-route smoke proves one Core/no-AI route and one AI route write usage ledger evidence for the exact request_id.","GitHub API Production Release Gate stores paid-route smoke evidence before any pro-enterprise readiness claim.","Fresh AI outputs created after deploy satisfy required sections, depth, metadata, and no fallback-looking copy."],"partnerGuidance":["Run public metadata checks without an API key before generating clients.","Run one no-AI Core Compute request before wiring paid AI routes.","Preserve Idempotency-Key across retries and keep request_id for support.","Treat 429, 409, 502, and 503 according to /api/v1/errors rather than blind retry loops.","Do not publish AI output when required sections, metadata, or quality gates are missing."],"evidenceRetention":"Keep smoke outputs, request_id, endpoint, UTC timestamp, key prefix only, commit SHA, deployment URL, and sanitized payload shape for support and procurement review."},"checks":[{"id":"local-contract-suite","suite":"Local Contract Suite","status":"live","owner":"platform","target":"Source, route handlers, OpenAPI, docs, SDK helpers, robots, sitemap, and gateway config.","command":"npm run test -- --run tests/api-v1.test.ts tests/api-reference-docs.test.ts tests/robots.test.ts tests/api-gateway-config.test.ts tests/sdk-contract.test.ts","proves":"Public API metadata, docs discovery, gateway rewrites, and SDK helpers agree before deploy.","passCriteria":["All focused API-platform tests pass.","OpenAPI exposes public metadata routes without API-key auth.","Docs, sitemap, robots, SDK source, and README helper lists include the same public metadata surfaces."],"evidenceArtifacts":["Vitest focused suite output","changed file diff","OpenAPI route assertions"],"failureEscalation":"Fix contract drift before build, push, or deploy."},{"id":"api-reference-discovery-smoke","suite":"API Reference Discovery","status":"live","owner":"platform","target":"Endpoint catalog, examples endpoint, OpenAPI, Postman collection, SDK snippets, and standalone reference pages.","command":"npm run smoke:api-reference -- --base-url https://api.theleokingai.com","proves":"Every documented endpoint has parseable examples, stable reference links, SDK snippets where shipped, and matching discovery coverage across examples, Postman, OpenAPI, and docs.","passCriteria":["Every catalog endpoint has valid request/response examples with request_id, data, and usage.","Every shipped endpoint is present in live OpenAPI while planned-only endpoints stay out of shipped OpenAPI paths.","Live /v1/examples and /v1/postman cover the full endpoint catalog.","The public docs page links to every standalone endpoint reference page."],"evidenceArtifacts":["inference-smoke/api-reference-smoke.json","live /v1/examples","live /v1/postman","live /v1/openapi","docs reference links"],"failureEscalation":"Block docs, SDK, OpenAPI, Postman, or endpoint publication until discovery surfaces agree."},{"id":"sdk-source-and-dist","suite":"SDK Source And Dist","status":"live","owner":"platform","target":"Node TypeScript source/dist and Python source package.","command":"npm run smoke:sdk-release -- --skip-live","proves":"SDK public metadata helpers, authenticated route helpers, webhook helpers, package metadata, Python import behavior, and generated Node dist compile.","passCriteria":["Node TypeScript build emits dist/index.js and dist/index.d.ts.","Python package compiles with no syntax errors.","Python import smoke verifies the production base URL and webhook signature helpers.","Package metadata and README install commands match the public SDK release policy.","Generated Python __pycache__ is removed before handoff."],"evidenceArtifacts":["inference-smoke/sdk-release-smoke.json","Node SDK build output","Python compileall output","SDK contract test output"],"failureEscalation":"Block package publication and generated-client work until source and dist match."},{"id":"production-build-suite","suite":"Production Build","status":"live","owner":"platform","target":"Next.js app routes, static API metadata, docs page, and TypeScript.","command":"npm run build","proves":"The app compiles, route handlers type-check, and static public metadata routes are generated.","passCriteria":["Next build completes successfully.","Static metadata routes include /api/v1/status, /api/v1/openapi, /api/v1/procurement, and /api/v1/conformance.","No route handler or docs TypeScript errors are present."],"evidenceArtifacts":["Next build output","route list","TypeScript output"],"failureEscalation":"Do not push deploy-bound changes until build passes."},{"id":"production-env-gate","suite":"Production Env Gate","status":"live","owner":"platform","target":"Vercel production env names, Clerk Convex JWT template, and deploy preconditions.","command":"npm run prod:env:production","proves":"Required production env surfaces exist before push/deploy and Clerk JWT template is configured.","passCriteria":["Vercel production check prints READY FOR PUSH/DEPLOY.","Clerk prod check prints READY FOR PUSH/DEPLOY.","Sensitive values are presence-checked without printing raw secrets."],"evidenceArtifacts":["env guard timestamp","masked checklist","Clerk template check output"],"failureEscalation":"Output BLOCKED: ENV NOT READY and stop before push or deploy."},{"id":"dedicated-gateway-smoke","suite":"Dedicated Gateway Smoke","status":"live","owner":"platform","target":"https://api.theleokingai.com public gateway routing and discovery metadata.","command":"npm run smoke:api-gateway -- --mode final","proves":"Dedicated gateway DNS, root JSON, OpenAPI, Postman, status, and docs discovery work in production.","passCriteria":["Gateway root returns the API index.","OpenAPI and Postman routes resolve through clean gateway paths.","Public metadata routes return current contractVersion."],"evidenceArtifacts":["inference-smoke/api-gateway-smoke.json","HTTP status codes","contractVersion"],"failureEscalation":"Treat as production routing regression and publish incident if partner-impacting."},{"id":"buyer-path-usage-smoke","suite":"Buyer Path Usage Smoke","status":"beta","owner":"shared","target":"Paid Core/no-AI and AI response envelopes, credit accounting, token accounting, and Convex usageEvents reconciliation.","command":"npm run smoke:paid-routes -- --base-url https://api.theleokingai.com --output inference-smoke/paid-route-contract-YYYYMMDD.json","proves":"A scoped key can call one Core Compute route and one AI Intelligence route, and each exact request_id appears in the usage ledger.","passCriteria":["Response includes request_id, data, usage, and meta.","Core Compute proof returns usage.lane core, expected credits, deterministic model metadata, and no usage.tokens or ledger totalTokens.","AI Intelligence proof returns usage.lane ai, expected credits, model metadata, and positive usage.tokens.total.","Convex usageEvents contains each exact request_id with matching endpoint, lane, credits, billableUnits, model, and AI totalTokens before enterprise demo or launch."],"evidenceArtifacts":["paid-route contract smoke JSON","core request_id","AI request_id","Convex usageEvents proof"],"failureEscalation":"Block enterprise demo or launch until response usage and ledger proof agree."},{"id":"github-production-release-gate","suite":"GitHub Production Release Gate","status":"live","owner":"platform","target":"Protected GitHub Actions workflow that runs production env, gateway, reference, and paid-route proof after deploy.","command":"GitHub Actions > API Production Release Gate","proves":"Production API readiness claims have a durable CI artifact with Core/no-AI, AI, and Convex usageEvents proof.","passCriteria":["Workflow runs inside the protected production environment before pro-enterprise launch claims.","Required GitHub environment secrets include LEOKING_API_SMOKE_KEY, CONVEX_DEPLOY_KEY, VERCEL_TOKEN, and CLERK_SECRET_KEY.","The workflow runs npm run ci:api-production-gate and uploads inference-smoke/*.json as release evidence.","The uploaded paid-route contract artifact includes both core-natal and ai-customer-profile results with matching Convex usageEvents."],"evidenceArtifacts":["GitHub Actions run","api-production-release-gate artifact","paid-route-contract-ci.json"],"failureEscalation":"Do not claim production or enterprise readiness until the workflow is rerun and green."},{"id":"ai-output-quality-sampling","suite":"AI Output Quality Sampling","status":"beta","owner":"shared","target":"Fresh production AI outputs after generation, prompt, model, RAG, or provider changes.","command":"Inspect 1-3 fresh live outputs created after the deploy timestamp.","proves":"AI value quality is preserved, not merely that status codes and pipelines succeeded.","passCriteria":["Required sections are present for the selected product contract.","Metadata, model/provider trace, depth, and forward-looking analysis are present where promised.","No placeholder, generic fallback, local path leak, malformed schema, or thin copy is published."],"evidenceArtifacts":["request_id list","output timestamps","quality notes","incident link if failed"],"failureEscalation":"Classify fallback-looking output as product regression before adjacent improvements."}],"productionChecklist":["Production env gate prints READY FOR PUSH/DEPLOY for the target environment.","API CI passes lint, full tests, source-only API reference smoke, and production build.","GitHub API Production Release Gate passes in the protected production environment after deploy.","Dedicated gateway smoke passes in final mode on api.theleokingai.com.","Buyer-path smoke passes against the dedicated gateway with Convex proof enabled.","Core endpoints return no token usage and AI endpoints return model/token visibility.","Fresh AI outputs satisfy product quality requirements after the deploy timestamp.","Support packet includes request_id, endpoint, key prefix only, UTC timestamp, and sanitized payload shape.","Access-control review confirms server-side key custody, endpoint scope, environment separation, rotation triggers, and no public-client key exposure.","Compliance mapping review confirms public evidence links, framework-style mapping, no certification overclaim, and signed-term boundaries.","AI governance review confirms acceptable-use boundaries, prohibited/restricted use cases, human-review requirements, and no fallback-success behavior.","Conformance evidence includes local contract tests, SDK build, app build, env gate, gateway smoke, buyer-path proof, and AI output sampling when relevant.","Data-processing review confirms minimization, restricted-data boundaries, retention policy, subprocessor scope, and signed-DPA requirements.","Launch-readiness handoff includes smoke evidence, partner integration matrix, billing proof, AI quality evidence, and rollback plan."],"links":{"docs":"/api-docs","openapi":"/api/v1/openapi","status":"/api/v1/status","accessControl":"/api/v1/access-control","observability":"/api/v1/observability","onboarding":"/api/v1/onboarding","examples":"/api/v1/examples","errors":"/api/v1/errors","sdks":"/api/v1/sdks","migrations":"/api/v1/migrations","procurement":"/api/v1/procurement","dataProcessing":"/api/v1/data-processing","compliance":"/api/v1/compliance","support":"/api/v1/support"}}