Valid OAuth token (scope oneapi:access)
- SetCallbackSecurity   (no resource prerequisite; recommended before Subscribe)
- Subscribe             (requires a resolvable HTTPS callback URL)
- GetSubscription       (meaningful after a Subscribe has succeeded)
- Unsubscribe           (meaningful only if a subscription exists)

OPERATION: SetCallbackSecurity
  AUTH: oneVituOauth / oneapi:access  — REQUIRED
  PRECONDITIONS:
    - Valid access token — REQUIRED
    - Callback endpoint capable of the chosen auth mechanism — OPTIONAL (depends on mechanism)
  SIDE_EFFECTS:
    - Persists/updates callback security config used for future deliveries — REQUIRED
    - AGENT_NOTE: PUT semantics imply full replacement; merge vs. replace UNCONFIRMED.
  SUCCESS_SIGNAL: success response to the call (spec-defined). No state field returned.

OPERATION: Subscribe
  AUTH: oneVituOauth / oneapi:access  — REQUIRED
  PRECONDITIONS:
    - Valid access token — REQUIRED
    - callbackUrl is HTTPS and resolvable — REQUIRED
    - Callback security configured — OPTIONAL (required if endpoint rejects unauthenticated calls)
  SIDE_EFFECTS:
    - Registers callback URL; enables future notification delivery — REQUIRED
  SUCCESS_SIGNAL: creation-success response; confirm via GetSubscription returning the URL.

OPERATION: GetSubscription
  AUTH: oneVituOauth / oneapi:access  — REQUIRED
  PRECONDITIONS:
    - Valid access token — REQUIRED
  SIDE_EFFECTS: none (read-only)
  SUCCESS_SIGNAL: response contains the expected callbackUrl.
  AGENT_NOTE: pagination params present but response shape is single-URL; cardinality UNCONFIRMED.

OPERATION: Unsubscribe
  AUTH: oneVituOauth / oneapi:access  — REQUIRED
  PRECONDITIONS:
    - Valid access token — REQUIRED
    - An existing subscription — OPTIONAL (call may succeed as no-op if none)
  SIDE_EFFECTS:
    - Removes subscription; stops future delivery — REQUIRED
    - AGENT_NOTE: in-flight deliveries may still arrive after success.
  SUCCESS_SIGNAL: success response; GetSubscription no longer returns the URL.

ON_FAILURE_AUTH:
  MEANING: token missing, invalid, or expired.
  RETRY: yes, once, after acquiring a fresh token.
  BACKOFF: none for the token refresh itself.
  STOP_CONDITION: second consecutive auth failure → treat as credential/config error; stop.

ON_FAILURE_VALIDATION:
  MEANING: bad request (e.g. non-HTTPS or unresolvable callbackUrl).
  RETRY: no.
  STOP_CONDITION: immediate; correct input before resubmitting.

ON_FAILURE_NOT_FOUND:
  MEANING: not defined as a distinct response in the spec for these operations.
  RETRY: no.
  STOP_CONDITION: treat as validation/state error; do not retry blindly.
  AGENT_NOTE: no not-found response is declared; handle absent subscription via GetSubscription state.

ON_FAILURE_RATE_LIMIT:
  MEANING: TooManyRequests (spec-defined).
  RETRY: yes.
  BACKOFF: exponential with jitter; no Retry-After header defined in spec.
  STOP_CONDITION: bounded max attempts, then surface error.

ON_FAILURE_SERVER:
  MEANING: ServerError (spec-defined).
  RETRY: yes.
  BACKOFF: exponential with jitter.
  STOP_CONDITION: bounded max attempts, then surface error.

RECIPE: Begin receiving notifications

1. Acquire token (oneapi:access).
2. SetCallbackSecurity   # configure auth to caller's endpoint
3. Subscribe             # register HTTPS callback URL
4. GetSubscription       # verify registration
5. Await deliveries at callback URL (payload/method UNSPECIFIED in spec).

RECIPE: Rotate callback security safely

1. Acquire token.
2. Update caller's endpoint to accept both old and new credentials (if possible).
3. SetCallbackSecurity   # submit new settings
4. Retire old credentials on the endpoint.
  AGENT_NOTE: overlap window avoids delivery-auth failures; replace-vs-merge UNCONFIRMED.

RECIPE: Change callback destination

1. Acquire token.
2. GetSubscription       # capture current URL
3. Subscribe             # register new URL
4. GetSubscription       # confirm

RECIPE: Stop receiving notifications

1. Acquire token.
2. Unsubscribe
3. GetSubscription       # confirm URL no longer registered
  AGENT_NOTE: tolerate late in-flight deliveries.