Draft Pilot Write Endpoint Design
Purpose
This page defines future POST/PATCH/DELETE-style endpoint contracts, validation boundaries, permission gates, request and response safety rules, failure modes, and prohibited input/output categories for a possible future pull-up/push-up draft pilot.
It is planning-only. It creates no protected API routes, no protected live routes, no write handlers, no database reads, no database writes, no drafts, no accounts, no staff decisions, and no live workflows.
Current Write Boundary
Design status
planning-only
Endpoint implementation
not-implemented
Go / no-go
no-go
Protected API routes
not-created
Write handlers
not-created
Database writes
not-implemented
Why Write Endpoint Design Comes Before Write Endpoints
Write endpoints would be the first boundary where a future system could change sensitive draft, review, visibility, retention, and audit data. The boundary has to be designed before any API file, handler, route, D1 query, or storage path exists.
Future write behavior remains blocked until identity, actor, role, draft, review, visibility, retention, deletion, audit, rate/abuse, rollback, incident, schema, and staff/privacy gates are approved.
Future Write Endpoints
These endpoint contracts are future-only metadata. No API files are created, no handlers are created, no runtime API behavior is added, and no database reads or writes occur in this phase.
| Future endpoint | Purpose | Role | Status | Reason blocked |
|---|---|---|---|---|
POST /api/protected/drafts | future create draft endpoint | approved resident/submitter actor | not-implemented | protected API routes, write handlers, D1 schema activation, actor policy, role mapping policy, retention policy, audit policy, and staff/privacy approval do not exist |
PATCH /api/protected/drafts/:id | future edit draft endpoint | approved draft author actor | not-implemented | draft storage, author visibility policy, validation policy, retention policy, and audit policy are not active |
POST /api/protected/drafts/:id/submit | future submit-for-review endpoint | approved draft author actor | not-implemented | staff review procedure, review queue storage, draft storage, and audit logging are not implemented |
POST /api/protected/drafts/:id/request-revision | future request revision endpoint, staff-side only | approved staff reviewer | not-implemented | reviewer permission policy, staff review write policy, and audit policy are not active |
POST /api/protected/drafts/:id/archive | future archive draft endpoint | approved author actor or staff reviewer under policy | not-implemented | retention policy, deletion policy, audit policy, and write handlers are not active |
POST /api/protected/drafts/:id/delete | future deletion request endpoint under retention/deletion policy | approved author actor or staff reviewer under deletion policy | not-implemented | retention/deletion implementation, deletion policy, audit policy, and rollback/incident policy are not active |
POST /api/protected/review/:id/lane | future staff review lane update endpoint | approved staff reviewer | not-implemented | staff review write design, reviewer permissions, and audit logging are not implemented |
POST /api/protected/morning-sheet/:id/visibility | future Morning Sheet visibility status endpoint | approved staff reviewer or program admin | not-implemented | Morning Sheet visibility policy, staff/privacy approval, and write handlers are not active |
Request Safety Boundaries
Allowed future request categories
- draft type
- draft title
- draft body
- repair prompt
- recognition prompt
- pseudonymous author actor ref
- pseudonymous subject actor ref
- workflow scope
- draft status transition
- review lane transition
- visibility status transition
- deletion request reason
- retention category reference
Prohibited request categories
- real names
- emails
- phone numbers
- addresses
- room numbers
- case numbers
- Cloudflare Access claims
- JWTs
- tokens
- raw identity headers
- resident profile data
- staff profile data
- diagnosis details
- medication details
- legal case details
- insurance details
- trauma details unless explicitly approved under future policy
- attendance data
- participation data
- participation analytics
- scoring/ranking/compliance metrics
- AI-generated staff decisions
- automatic approval requests
- automatic Morning Sheet placement requests
Response Safety Boundaries
Allowed future response categories
- success/failure status
- draft ref
- draft status
- validation messages
- review lane status
- visibility status
- retention/deletion status
- minimal audit event ref
Prohibited response categories
- real identity
- Cloudflare claims
- hidden staff notes
- private feedback not visible to requester
- other residents' drafts
- staff-only review data unless requester is authorized
- scoring/ranking/participation/compliance data
- emails
- JWTs
- tokens
- raw identity headers
Validation Rules
- protected access boundary
- approved pseudonymous actor ref
- approved role mapping
- approved workflow scope
- allowed draft type
- content safety validation
- identity/sensitive field rejection
- staff review dependency
- Morning Sheet visibility dependency
- retention/deletion policy
- audit policy
- rate/abuse policy
- rollback/incident policy
Permission And Actor Gates
| Permission gate | Actor gate |
|---|---|
| requester has approved role mapping | actor ref required before any future write |
| requester has approved workflow scope | actor ref must be pseudonymous and opaque |
| requester may act only through approved pseudonymous actor ref | actor ref must not expose email, name, initials, room, case, Cloudflare claim, JWT, token, or raw identity header |
| staff-only endpoints require approved staff reviewer role | identity mapping must be approved before any live actor resolution |
| Morning Sheet visibility endpoints require approved staff/privacy policy | no real users are linked in this phase |
| deletion endpoints require approved retention/deletion policy | no additional actor gate |
Failure Modes
Required Gates Before Implementation
- Cloudflare Access boundary approved
- identity policy approved
- pseudonymous actor policy approved
- account role mapping policy approved
- write endpoint policy approved
- draft content policy approved
- pull-up safety policy approved
- push-up recognition policy approved
- staff review procedure approved
- Morning Sheet visibility policy approved
- retention policy approved
- deletion policy approved
- audit policy approved
- rate/abuse policy approved
- rollback/incident policy approved
- D1 schema activated under approved migration
- protected API route policy approved
- staff/privacy approval complete
- small pilot group approved
Blocked Capabilities
Recommended Next Phase
Phase 9.6 - Draft Pilot Staff Review Write Design
After write endpoint boundary design, the next safe planning step is staff review write design that still creates no review handlers, decisions, protected API routes, database writes, draft storage, Morning Sheet placement, tracking, analytics, or scoring.
Boundaries: no protected API routes; no protected live routes; no write handlers; no D1 queries; no database reads; no database writes; no active migrations; no draft storage; no account storage; no actor storage; no identity capture; no staff decisions; no Morning Sheet placement; no tracking; no analytics; no scoring.
recommended-next