Choosing An Adoption Lane

Copy Markdown View Source

Scoria is easiest to adopt when you treat it as a layered Phoenix runtime, not a platform you have to swallow whole.

Start with the narrowest lane that solves your current problem. Expand only when the previous lane already feels boring in your host app. Start with the default runtime lane. It proves identity-aware durable runs, approvals, and operator evidence with mix test.adoption. Use mix test.runtime_to_handoff as the bounded escalation proof lane when the same durable run needs narrow same-run delegation, host-controlled projected context, and operator-visible delegated lineage.

The Four Lanes

1. Default runtime lane

Start here.

Choose it when you need:

  • canonical actor, tenant, and session identity
  • durable runs with exact run_id resume
  • approval pauses and operator evidence
  • one public facade for identity -> start -> inspect -> resume

Core APIs:

Operator surfaces:

  • /scoria
  • /scoria/workflows/:run_id

Host session identity

Host apps must set session["tenant_id"] and session["actor_id"] before mounting /scoria (or any route wired with scoria_dashboard/2). OrchestratorLive scopes PubSub to scoria:runs:{tenant_id} and uses both keys for audit refs on Workflows.approve/3. The runtime identity you pass to Scoria.start_run/2 must use the same tenant_id as the LiveView session or live trace and HITL updates will not reach the operator UI.

conn
|> put_session("tenant_id", conn.assigns.current_account.id)
|> put_session("actor_id", conn.assigns.current_user.id)

mix scoria.install does not inject auth or session keys — that contract is host-owned. When operator live broadcast is enabled, ensure Observe Telemetry and Buffer are started in your host application (see test/scoria/observe/telemetry_test.exs for the attach pattern).

Proof lane:

mix scoria.install
mix ecto.migrate
mix test.adoption

Adoption closeout exercises a packaged tarball from mix hex.build --unpack (not a monorepo root path: dep). Maintainer CI topology — PR tarball vs release registry attest — lives in docs/operator_verification.md.

If you are not sure where to start, start here.

After upgrades, run mix scoria.install --check as a no-write verification step. See Installer verification modes (upgrade-safe) for the dry-run → check → remediate → apply workflow. See Check vs apply drift detection for manifest fingerprint roles at check vs apply time.

This lane does not require semantic fast-path setup, knowledge/pgvector bootstrap, retrieval setup, or hosted onboarding setup.

2. Bounded handoff lane

Add this only when the default runtime lane is already working.

Choose it when:

  • one role needs to delegate a narrow slice of work to another role
  • the delegated role should stay under the same durable run
  • projected context must stay least-privilege and inspectable

Core API:

Key rule:

  • projected context stays narrow and host-controlled
  • broad runtime-state keys such as transcript, messages, provider_session, session, and secrets are rejected explicitly

Use this for review, critique, classification, or bounded specialist work. Do not use it to build a broad autonomous multi-agent platform by default.

Validate the base runtime lane with mix test.adoption before you intentionally expand into Scoria.start_handoff_run/3. Use mix test.runtime_to_handoff as the bounded runtime-to-handoff escalation verifier for the same Scoria.get_run_detail/1 and delegated_handoffs readback path.

3. Semantic fast-path lane

Add this only after the default runtime lane is already boring.

Choose it when:

  • you want answer reuse for explicitly safe read-only work
  • tenant partitioning and compatibility truth matter more than aggressive hit-rate chasing
  • operators need to inspect why reuse happened, missed, bypassed, or was rejected

Core API surface:

  • use Scoria.SemanticLane
  • Scoria.start_run(..., semantic_cache: [lane: MyLane], ...)

Key behavior:

  • reuse is opt-in
  • hits remain inside the normal durable run story
  • bypass, miss, reject, and stale outcomes fall through to the normal runtime path
  • lifecycle truth stays explicit as active, stale, invalidated, and writeback_rejected

Proof lane:

SCORIA_DB_PORT=55432 SCORIA_DB_PASSWORD=postgres MIX_ENV=test mix test.semantic_fast_path

Use this lane when latency and cost matter, but only if you can keep the work safe, tenant-scoped, and operator-visible.

Semantic fast path is optional troubleshooting, not a prerequisite for first adoption.

4. Optional knowledge lane

Add this only when you are intentionally validating retrieval, citations, and grounding.

Choose it when:

  • you need pgvector-backed retrieval
  • you need citation and grounding evidence
  • you are ready to own the knowledge setup in your app

Proof lane:

mix scoria.pgvector.bootstrap
mix test.knowledge

This lane is explicitly optional. It is not required to prove the core runtime, handoff, or semantic fast-path adoption story, and it is not a prerequisite for first adoption.

5. Remote connector lane

Add this only when you are intentionally validating remote MCP connector registration and operator fleet evidence.

Choose it when:

  • you need durable connector records, grants, and health state inside your Phoenix app
  • operator evidence for connector fleet and drawer surfaces matters for your integration review
  • you have already proven the default runtime lane

Proof lane:

mix test.connector

This lane does not require semantic fast-path setup, knowledge/pgvector bootstrap, retrieval setup, or hosted onboarding setup.

See connector_adoption.md for embedded-boundary framing.

A Good Default Order

Adopt Scoria in this order:

  1. identity -> start -> inspect -> resume
  2. bounded handoffs if one role truly needs delegation
  3. semantic fast path if safe read-only reuse is worth it
  4. optional knowledge lane if retrieval and grounding are part of your product
  5. remote connector lane if MCP tool surfaces are part of your product

What You Do Not Need To Adopt First

You do not need:

  • pgvector
  • broad multi-agent orchestration
  • a hosted control plane
  • external semantic cache backends
  • advanced ANN tuning

Start narrow. Expand only when the current lane already feels boring.