Contract v1 · generated reference

RuntimeHandler.waitlist

OP-RUNTIME-WAITLIST is a http compatibility operation owned by Corporate.

Authority and transport

Actor: compatibility client
Authentication: endpoint-specific
Authorization: compatibility policy
Resource boundary: server-derived from verified payload and stored state
Transport: HTTP_COMPATIBILITY
Deployed export: waitlist
App Check: REQUIRED_MANUAL_HEADER_VERIFICATION
Canonical source: functions/src/properties/corporate/handlers.ts

Request schema

Request parameters for RuntimeHandler.waitlist
Field	Required	Schema
`body.email`	Yes	`string (normalized email)`
`body.website`	No	`string (honeypot; legitimate callers leave empty)`
`body.idempotencyKey`	Yes	`string (16–128 governed characters)`
`Origin`	Yes	`exact allowed browser origin header`
`X-Firebase-AppCheck`	Yes	`valid token for this environment`

Response schema

CorporateSubmissionResult on HTTP 200; bounded JSON error envelope otherwise

States, consistency and recovery

State path: RECEIVED → METHOD_MEDIA_SIZE_CHECK → APP_CHECK_VERIFICATION → ORIGIN_AND_INPUT_VALIDATION → RATE_LIMITED_OR_CONFLICT → PROCESSING → ACCEPTED_OR_NEUTRAL_HONEYPOT → HTTP_FAILURE_OR_RECOVERY
Reads: App Check verification, allowed-origin configuration and idempotency/rate state
Writes: server-authoritative Corporate submission, idempotency and rate records
Transaction: Corporate persistence commit after wrapper and service validation
Idempotency: required; same key and fingerprint replay the prior neutral result
Concurrency: idempotency fingerprint plus Corporate persistence transaction
Retry/replay: retry only an identical intent with the same key after the returned recovery interval
Rate limits: Daily Corporate service policy; honor RATE_LIMITED.retryAfterSeconds.
Audit: privacy-safe result family; raw email, IP and App Check token are excluded

Error contract

Exact public HTTP wrapper outcomes; domain rate limiting is returned as CorporateSubmissionResult rather than thrown. Never treat an unknown error as success.

method_not_allowed
unsupported_media_type
payload_too_large
request_verification_required
request_verification_failed
permission-denied
invalid-argument
failed-precondition
internal

Producer test references

Evidence tier: SEMANTIC_CORE_REFERENCE.

Reviewer-mapped semantic/core references

packages/backend-firebase/test/operation-contracts.test.mjs
functions/test/corporate-handler.test.js
functions/test/corporate-wrapper.test.js

Protocol or inventory references

packages/backend-firebase/test/operation-contract-detector.mjs

These references prove export, wrapper or protocol behavior only. They are not counted as complete operation semantics.

Legacy waitlist HTTP compatibility request

async function submitWaitlist(fetchSandbox) {
  const response = await fetchSandbox("https://REGION-PROJECT_ID.cloudfunctions.net/waitlist", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Firebase-AppCheck": "APP_CHECK_TOKEN",
    },
    body: JSON.stringify({
      email: "PERSON@example.test",
      website: "",
      idempotencyKey: "IDEMPOTENCY_KEY",
    }),
  });
  if (!response.ok) throw new Error(`HTTP_${response.status}`);
  return response.json();
}
globalThis.__examplePromise = submitWaitlist(globalThis.fetchSandbox);

curl --fail-with-body --request POST \
  --url https://REGION-PROJECT_ID.cloudfunctions.net/waitlist \
  --header 'Origin: https://APPROVED_SANDBOX_ORIGIN' \
  --header 'X-Firebase-AppCheck: APP_CHECK_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"email":"PERSON@example.test","website":"","idempotencyKey":"IDEMPOTENCY_KEY"}'

Common integration contract

Sandbox and Production are isolated

Run examples only in a governed sandbox or local emulator. Sandbox identities, App Check tokens, payment fixtures and data do not grant Production access. The typed ports do not ratify a public numeric quota; enforcement may be stricter. Honor RATE_LIMITED and the server's retry-after value.

Authentication and authorization

Firebase Auth proves identity. App Check proves the approved app where a callable requires it. Roles, organization membership, requester identity and resource ownership are derived and rechecked by the server.

Authentication guide

Errors and recovery

Stable error codes distinguish validation, denial, conflict, expiry, authority pending, rate limiting and temporary unavailability. Never infer success from an HTTP redirect or a browser state.

Error catalogue

Idempotency, concurrency and retry

Reuse an idempotency key only for an identical retry. A new intent needs a new key. Preserve version preconditions and reload after a conflict.

Retry guidance

Changes and escalation

Check compatibility before adopting a new contract version. Review the changelog, service status and support guidance before retrying a persistent failure.

Changelog Service status Developer support

Common failure families
Family	Client decision
Authentication / authorization	Refresh or step up only when instructed; do not retry a denial unchanged.
Validation / conflict / expiry	Correct or reload state, then obtain confirmation for a new intent.
Rate limited / unavailable	Honor retry-after and use bounded backoff; inspect service status.
Unknown / server	Fail closed and escalate with a privacy-safe correlation id.

Executable network examples are published only when the exact wire schema is producer-proven. Check the selected operation's example-availability status; an unresolved schema is a release blocker, not permission to guess.

Verified examples and local-only recovery snippets