The Rail · Reference & analysis

Ori Presence believability beta runbook

Ori Presence is optional.

6sections4 minread
Markdown source
On this page
  • Owner: V10 Rail / V6 cognition operations
  • Feature: RB.2 Ori Presence
  • Default posture: off and silent
  • Last reviewed: 2026-07-18

Safety and authority invariants#

Ori Presence is optional. The Rail remains complete without it. No narration is eligible until all of these gates agree:

  1. OSHUN_V10_ORI_PRESENCE_ENABLED is exactly true.
  2. The authenticated V1 user id appears in OSHUN_V10_ORI_PRESENCE_COHORT_USER_IDS.
  3. Durable exact-scope consent resolves active for the surface and every input or output used by that request.
  4. The user subscribes to v6.ori-presence.
  5. Discretion and crisis policy permit the surface.
  6. The per-user UTC-day inference ledger can reserve the whole request.
  7. Clio citation membership and semantic entailment, Sophia grounding, Isis behavior policy, and the Iris dialogue-quality gate all pass.

Adult-ring events, producer payloads, held/pre-batch events, unsubscribed channels, and ungranted daypart, presence, or continuity fields are removed before prompt composition. Recap generation does not write Ori or Iris memory. Voice is explicit playback only, never autoplay, and is blocked during an active crisis frame even for a previously cached narration.

Required deployment configuration#

Apply the migration in libs/oshun/persistence/prisma/migrations/20260718083000_v10_ori_presence_beta to the database named by OSHUN_V1_DATABASE_URL. The BFF does not create a usable Ori runtime without this durable V1 connection.

Set a random OSHUN_V10_ORI_CONSENT_HMAC_SECRET of at least 32 characters in the secret manager. Rotation requires an explicit migration strategy because existing consent fingerprints fail closed under a new secret; do not rotate it as an ordinary rolling environment edit.

Choose and price one real provider:

  • OSHUN_V10_ORI_MODEL: provider model id.
  • OSHUN_V10_ORI_PROVIDER: anthropic, openai, google, xai, or ollama; leave unset only when the shared assistant provider's documented default is intended.
  • OSHUN_V10_ORI_PROVIDER_BASE_URL: optional compatible endpoint override.
  • OSHUN_V10_ORI_MODEL_INPUT_PER_MTOK_USD and OSHUN_V10_ORI_MODEL_OUTPUT_PER_MTOK_USD: both required and reviewed against the selected provider's current price sheet.
  • Provider credential: OPENROUTER_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY, or XAI_API_KEY as applicable. Ollama is keyless but still requires reachable infrastructure.

The optional awareness authorities are independent. A URL requires its paired bearer token:

  • OSHUN_V10_ORI_COARSE_PRESENCE_URL / _TOKEN
  • OSHUN_V10_ORI_CONTINUITY_URL / _TOKEN
  • OSHUN_V10_ORI_MEMORIAL_ELIGIBILITY_URL / _TOKEN

Missing coarse presence or continuity degrades by omitting that context. Meaningful-date creation fails loud when memorial eligibility is not configured. Set both OSHUN_ELEVENLABS_API_KEY and OSHUN_ELEVENLABS_VOICE_ID to enable explicit-playback voice; otherwise voice is visibly unavailable.

Hard budget policy#

Defaults are 12 calls, 60,000 tokens, and USD 0.50 per user per UTC day. Each request reserves no more than 20,000 total tokens and USD 0.20, with a 600-output-token cap per provider call. Configure:

text
OSHUN_V10_ORI_DAILY_CALL_LIMIT
OSHUN_V10_ORI_DAILY_TOKEN_LIMIT
OSHUN_V10_ORI_DAILY_COST_USD
OSHUN_V10_ORI_REQUEST_TOKEN_LIMIT
OSHUN_V10_ORI_OUTPUT_TOKEN_LIMIT_PER_CALL
OSHUN_V10_ORI_REQUEST_COST_USD
OSHUN_V10_ORI_NARRATION_TTL_SECONDS

Reservation is serializable and precedes provider dispatch. Successful work is settled at measured usage. A dispatch that fails after its boundary is charged at the full reservation (settled-failure). A reservation still pending after ten minutes is crash-uncertain and charged at the full reservation (settled-uncertain). This deliberately favors a hard ceiling over optimistic retry. abandoned is reserved for work proven not to have crossed dispatch.

Inspect daily cost and outstanding reservations without selecting narration or consent content:

sql
SELECT utc_date,
       count(*) AS users,
       sum(used_calls) AS calls,
       sum(used_tokens) AS tokens,
       sum(used_cost_microusd) / 1000000.0 AS cost_usd,
       sum(reserved_cost_microusd) / 1000000.0 AS pending_cost_usd
FROM ori_presence_daily_usage
WHERE utc_date >= (CURRENT_DATE - INTERVAL '7 days')::text
GROUP BY utc_date
ORDER BY utc_date DESC;

SELECT status, count(*) AS reservations,
       sum(actual_cost_microusd) / 1000000.0 AS charged_usd
FROM ori_presence_inference_reservations
WHERE created_at >= now() - INTERVAL '24 hours'
GROUP BY status
ORDER BY status;

Alert on any long-lived pending row, growth in settled-failure or settled-uncertain, daily exhaustion above the reviewed cohort expectation, or provider invoices that exceed the durable microusd ledger.

Staged rollout#

  1. Deploy schema and code with the flag false and an empty cohort. Confirm RA.9 flag-off browser coverage and zero model traffic.
  2. Configure the HMAC authority, real provider, pricing, and deliberately low hard budgets. Keep the cohort empty; verify BFF startup reports the beta as disabled.
  3. Add one internal V1 user id, then set the flag true. The user must still grant each exact permission in Rail settings. Verify recap source refs, no adult or ungranted provider bytes, no autoplay, explicit voice ducking, and audit events before expanding.
  4. Expand the comma-separated cohort in small reviewed batches. Compare quality failures, budget exhaustion, provider charges, crisis suppression, and consent withdrawal/revocation on every batch.
  5. Do not make the flag global or infer consent from cohort membership.

Privacy operators may append a revocation while the feature flag is off with:

text
POST /v1/admin/rail/ori/consents/:userId/:scope/revoke
Authorization: bearer with admin:* or admin:workspace:privacy

The event is fingerprinted, uses operator-revocation, and supersedes the previous exact-scope event. Account deletion includes consent, narration, meaningful-date, reservation, and daily-usage records in the V1 deletion fanout.

Incident rollback#

For unexpected provider spend, privacy doubt, policy regression, crisis-path failure, or grounding drift:

  1. Set OSHUN_V10_ORI_PRESENCE_ENABLED=false on every BFF instance and roll the deployment. This closes account, generation, Thread, settings, and voice routes for ordinary users; the privacy-admin revocation route remains available.
  2. Remove cohort ids as defense in depth. Do not delete consent history to disable the feature.
  3. Revoke/rotate the affected provider credential when compromise or runaway dispatch is possible. Preserve inference and run evidence.
  4. Inspect reservation states and provider invoices. Never reset daily usage to make retries possible during an incident.
  5. Use the operator route for user/scope revocations requested during the rollback. Use the account-deletion workflow for erasure; do not manually delete individual rows.
  6. Re-enable only after the focused tests, real Postgres restart test, and desktop/mobile Playwright suite pass against the remediation.

Verification commands#

Run focused gates sequentially on small hosts:

bash
pnpm exec vitest run --config libs/contracts/vitest.config.ts \
  libs/contracts/src/v10/ori-presence.spec.ts
pnpm exec vitest run \
  --config libs/v10/rail-channel-ori-presence/vitest.config.ts \
  libs/v10/rail-channel-ori-presence/src/ori-presence.spec.ts \
  libs/v10/rail-channel-ori-presence/src/narrator.spec.ts
pnpm exec tsc -p libs/v10/rail-channel-ori-presence/tsconfig.json --noEmit
pnpm exec vitest run --config libs/v10/rail-phase-a/vitest.config.ts \
  libs/v10/rail-phase-a/src/phase-a-invariants.spec.ts
pnpm --filter @oshun/bff exec vitest run \
  src/routes/v10-ori-presence.test.ts \
  src/v10/ori-presence-consent-authority.test.ts \
  src/v10/ori-presence-store.test.ts \
  src/v10/ori-presence-adapters.test.ts \
  src/v10/ori-presence-runtime.test.ts
pnpm --filter @oshun/bff test:integration -- src/v10/ori-presence.integration.test.ts
pnpm --filter @oshun/v10-web test
pnpm --filter @oshun/v10-web exec playwright test e2e/ori-presence.spec.ts \
  --project=desktop-chromium --project=mobile-chromium --workers=1

The Playwright fixture runs axe accessibility checks and responsive overflow assertions. Also run the affected lint, typecheck, build, schema/migration, privacy-deletion, cognition-gateway, Moirai-cap, Sophia, and Isis suites before a production rollout.