Oshun Platform · Guides & deep dives

Eve Development and Change Map

Use the generated Docs Center systems catalog and repo map to resolve current project-level owners and dependency edges before changing a shared package.

6sections4 minread2tables

On this page

This map tells maintainers where Eve behavior lives and which proof should move with a change. It intentionally points to ownership seams instead of copying volatile file counts or treating every assistant-adjacent package as one monolith.

FlowchartFlowchart: 12 steps and 13 connections.yesnonoyesProposed Eve behaviorchangeResolve owning surfaceruntime policy or databoundaryDoes a contract orvocabulary change?Update types schemasclients persistence andcompatibilityChange the owningimplementationVerify identity grantsconfirmation safety privacyand groundingRun unit contractintegration and real surfacejourneysRun task-family eval costlatency and accessibilitygatesUpdate telemetry runbooksrollout rollback andrecovery evidenceUpdate focused docsdiagrams walkthrough andgenerated referenceAll current evidenceagrees?Canary promote andmaintain
Flowchart: Flowchart. Flowchart: 12 steps and 13 connections.

This picture is wider than it can be shown here. Move across it, or read it as text.

Drawn from its Mermaid source.

As text
Parts:
- Proposed Eve behavior change
- Resolve owning surface runtime policy or data boundary
- Does a contract or vocabulary change? (decision)
- Update types schemas clients persistence and compatibility
- Change the owning implementation
- Verify identity grants confirmation safety privacy and grounding
- Run unit contract integration and real surface journeys
- Run task-family eval cost latency and accessibility gates
- Update telemetry runbooks rollout rollback and recovery evidence
- Update focused docs diagrams walkthrough and generated reference
- All current evidence agrees? (decision)
- Canary promote and maintain

Connections:
- Proposed Eve behavior change to Resolve owning surface runtime policy or data boundary
- Resolve owning surface runtime policy or data boundary to Does a contract or vocabulary change?
- Does a contract or vocabulary change? to Update types schemas clients persistence and compatibility: yes
- Does a contract or vocabulary change? to Change the owning implementation: no
- Update types schemas clients persistence and compatibility to Change the owning implementation
- Change the owning implementation to Verify identity grants confirmation safety privacy and grounding
- Verify identity grants confirmation safety privacy and grounding to Run unit contract integration and real surface journeys
- Run unit contract integration and real surface journeys to Run task-family eval cost latency and accessibility gates
- Run task-family eval cost latency and accessibility gates to Update telemetry runbooks rollout rollback and recovery evidence
- Update telemetry runbooks rollout rollback and recovery evidence to Update focused docs diagrams walkthrough and generated reference
- Update focused docs diagrams walkthrough and generated reference to All current evidence agrees?
- All current evidence agrees? to Change the owning implementation: no
- All current evidence agrees? to Canary promote and maintain: yes
Show source
flowchart TD
  Change[Proposed Eve behavior change] --> Own[Resolve owning surface runtime policy or data boundary]
  Own --> Contract{Does a contract or vocabulary change?}
  Contract -- yes --> Sync[Update types schemas clients persistence and compatibility]
  Contract -- no --> Implement[Change the owning implementation]
  Sync --> Implement
  Implement --> Trust[Verify identity grants confirmation safety privacy and grounding]
  Trust --> Tests[Run unit contract integration and real surface journeys]
  Tests --> Quality[Run task-family eval cost latency and accessibility gates]
  Quality --> Ops[Update telemetry runbooks rollout rollback and recovery evidence]
  Ops --> Docs[Update focused docs diagrams walkthrough and generated reference]
  Docs --> Release{All current evidence agrees?}
  Release -- no --> Implement
  Release -- yes --> Ship[Canary promote and maintain]

The path starts with ownership and ends with current evidence. Editing a prompt, tool label, or UI component alone is not a complete behavior change.

Source map#

Concern Canonical area Typical proof
Shared assistant types, invocation, skills, tools, UI state libs/oshun/shell-assistant Unit tests for registries/guards/state; shell integration tests.
Member web shell and assistant presentation apps/oshun/web/src/components/assistant and shared shell layout Component tests, accessibility tests, customer Playwright journeys.
Builder Operations Copilot presentation apps/oshun/admin assistant/copilot components Component/integration tests, admin Playwright battery and confirmation-card flows.
Assistant HTTP/runtime path apps/oshun/bff/src/routes/assistant.ts and apps/oshun/bff/src/assistant Route, policy, router, tool, streaming, eval, and integration suites.
Workbench read/write/confirm tools apps/oshun/bff/src/workbench Contract, persistence, authorization, idempotency, integration, and UI confirmation tests.
Conversation persistence apps/oshun/bff/src/conversation Ordering, reconnect, retention, erasure, and event-consumer tests.
Iris memory libs/iris plus BFF memory adapters Scope/consent/recall/privacy tests and memory journeys.
Sophia grounding libs/sophia, evidence adapters, and BFF routes Claim/source contract, corroboration, invalidation, eval, and browser evidence tests.
Lilith policy libs/lilith policy/adapters and BFF enforcement Persona, tone, crisis, voice-abuse, cultural-safety, and no-bypass tests.
Agent plane tools/workbench-mcp/server.mjs, tools/eve-codex-agent.mjs, governed runtime MCP contract, lease, actor, sandbox, report, and verifier-separation tests.
Evaluation and maintenance apps/oshun/bff/src/assistant/evals, docs/audits, tools/eve-* Deck floors, ratchets, judge validation, cost reports, and scorecards.

Use the generated Docs Center systems catalog and repo map to resolve current project-level owners and dependency edges before changing a shared package.

Change recipes#

Add or modify an invocation point#

Update the typed registry/guard, the shell call site, context serializer, server validation, accessibility behavior, analytics event, and the relevant desktop and mobile Playwright flow. Prove out-of-scope, unauthorized, stale-context, and focus-restoration behavior.

Add a task family or routing rule#

Define the family contract, skill, toolset, grounding requirement, budget, model/escalation policy, and eval cases together. Add deterministic router tests for positive, negative, ambiguous, quoted-text, and neighboring-family language. Run the prompt hash and per-family floors.

Add a tool#

Specify typed input/output, prerequisites, actor/tenant authorization, effects and non-effects, idempotency, timeout/retry semantics, audit receipt, and UI presentation. Read tools need redaction and freshness tests. Mutation tools also need confirmation/lease, conflict, replay, transaction, and failure-recovery coverage.

Change prompts, skills, examples, or tool descriptions#

Treat all model-visible bytes as behavior. Update the string inventory/ratchet, rerun affected decks with the pinned model registry, inspect cost/latency, and record the resulting scorecard evidence. Copy review alone is not sufficient.

Change memory or grounding#

Update shared contracts, persistence/migrations, adapters, consent and deletion behavior, audit, UI disclosure, and invalidation/retraction paths. Run unit, service, integration, contract, grounded-answer evaluation, privacy/data-rights, and browser journey coverage.

Change safety or persona policy#

Version the policy, retain the no-bypass enforcement, update locale/cultural review where affected, and run the full relevant crisis/refusal/adversarial and surface suites. A presentation change can still be safety-significant if it hides disclosure, resources, or supersession state.

Change model/provider configuration#

Update the registry and configuration validation; never hardcode a silent fallback. Rebaseline only under the measurement protocol, including family floors, escalation rate, cost, latency, and provider failure behavior. Preserve rollback data.

Contract checklist#

Every new assistant contract should answer:

  • Who is the actor and tenant?
  • Which plane and presented identity apply?
  • What is the stable request/response or event schema?
  • Which values are user input, resolved server state, retrieved evidence, or model output?
  • What authorization, policy, consent, budget, and confirmation checks apply?
  • Is the operation idempotent, transactional, cancellable, and replay-safe?
  • What receipt, audit, telemetry, and user disclosure are emitted?
  • What is persisted, for how long, and how is it exported or erased?
  • How does the path behave without the provider/tool/store?
  • Which tests and evaluation cases block regression?

Verification matrix#

Change type Minimum focused automation
Pure renderer/copy with no model-visible bytes Lint/typecheck as applicable, component test, accessibility/browser flow.
Model-visible copy or routing Unit/router tests, prompt ratchet, affected family deck, browser flow.
Read tool Schema/auth/redaction unit tests, service integration, task-family eval, surfaced result flow.
Mutation tool All read-tool proof plus persistence/transaction/idempotency, confirmation/lease, audit, failure and Playwright coverage.
Memory/grounding/safety Contract, persistence, service/integration, adversarial/evaluation, data-rights/release gates, end-to-end journey.
Agent/MCP Protocol and lease tests, sandbox/actor attribution, artifact report, independent verification and recovery.

Run expensive monorepo gates according to the repository's resource-safety policy; targeted proof is preferred while iterating, but required affected gates cannot be skipped.

Documentation obligations#

Update Eve Handbook when the identity, plane model, invariant set, or canonical reading path changes. Update the focused topic for runtime, context, safety, quality, or operational changes. Update the date-stamped audit or TODO source when the shipped/gated/backlog state changes. Regenerate and verify the Docs Center so source links, search entries, and the featured rail remain correct.