Publication readiness
The current docs can serve as a baseline reference with route labels. Expanded external docs, SDKs, and production recipes need release evidence before they are promoted.
Current verdict
Baseline endpoint rendering can proceed. External-quality claims, SDK readiness, live side-effect recipes, and broad module coverage need publication review.
Who reviews publication readiness
| Reviewer | Decision |
|---|---|
| Product/API owner | Confirms the endpoint should exist as a public product contract and belongs in docs, SDKs, or onboarding flows. |
| Security and compliance | Checks PHI exposure, authentication, authorization, tenant isolation, auditability, credentials, and sensitive examples. |
| Module engineering owner | Confirms the implementation matches the documented behavior, status codes, side effects, retries, and external-service assumptions. |
| Developer experience/docs owner | Confirms examples, Copy for LLM content, endpoint grouping, SDK inclusion, and try-out access are clear and safe for external users. |
Gates
| Gate | Name | Blocks |
|---|---|---|
| E1 | Tenancy and actor contract | Quickstart, examples, wrong-org guidance, audit/correlation docs |
| E2 | Side-effect policy | Live, sandbox, queue, dry-run, and production recipe claims |
| E3 | Async and idempotency | 202, retry, polling, cancellation, and SDK retry helpers |
| E4 | Files and artifacts | Uploads, downloads, PDFs, reports, transcripts, EDI, and generated artifacts |
| E5 | PHI-safe DTOs and reporting | Broad read/detail/report/export/analytics docs |
| E6 | Route registry | Public reference grouping, compatibility routes, try-out UX, and SDK inclusion |
| E7 | Credentials and webhooks | Credential provisioning, callbacks, webhook subscriptions, and vendor webhook docs |
| E8 | Identifier policy | Cross-module workflow docs and SDK model examples |
| E9 | Release evidence | Expanded external docs, SDKs, and production readiness claims |
Readiness by docs surface
| Surface | Current | Required |
|---|---|---|
| Generated OpenAPI JSON/YAML | Baseline source only | Route class metadata, reusable components, standard headers, examples checked for sensitive data, and fresh release evidence. |
| Scalar reference and endpoint pages | Limited baseline | Visible route status, auth, side effects, async/idempotency, file policy, examples, and evidence per route. |
| Quickstart | Needs publication review | A classified safe first endpoint with validated synthetic request and response examples. |
| Workflow guides | Internal draft only | Platform primitive links, endpoint status labels, and no live side-effect overclaims. |
| SDKs | Needs publication review | Route registry, reusable OpenAPI components, validated fixtures, release checks, and excluded unsafe routes. |
Release evidence required
| Evidence | Purpose |
|---|---|
| Route registry diff | Classifies every generated, compatibility, guest, worker, webhook, legacy, private, or internal route. |
| Fresh generated artifacts | Proves docs, endpoint pages, and OpenAPI came from the same release workspace. |
| wasp build | Catches Wasp generated-type and entity-list failures that Jest can miss. |
| HTTP contract tests | Covers API-key tenancy, wrong-org behavior, safe errors, redaction, file ownership, idempotency, and webhook replay where applicable. |
| No-sensitive-data checks | Scans docs, examples, fixtures, snapshots, logs, and OpenAPI for PHI, secrets, raw payloads, storage keys, and signed URLs. |
| Known exception manifest | Records skipped routes, compatibility behavior, and approved publication exceptions. |
Blocked claims
| Claim | Reason |
|---|---|
| SDK-ready public API | Reusable OpenAPI components, route registry, examples, and release evidence are incomplete. |
| Production live execution recipes | Queue-only, validate-only, dry-run, simulated, local, and metadata-only behavior must remain labeled. |
| Public file or artifact retrieval | File content class, scanning, retention, legal hold, ownership, and URL policy are unresolved. |
| Credential or webhook setup | Credential lifecycle, masking, rotation, signing, replay, retry, and audit policy are not published. |
| Universal Idempotency-Key or rate-limit headers | The current OpenAPI baseline does not declare those global headers. |
| Stable tenant identifiers in responses | The public organizationId/meta.organizationId response policy remains unresolved. |