World Agent

The World Agent is the internal resident of each World Model. It owns the world-model authoring path and (per ADR-081 D1) runs as a single agent definition in apps/workers rather than its own deployable. Each world model has exactly one resident World Agent; the architectural pattern is instantiated once per (org_id, domain_id) world model, with its memory and exploration history scoped to that world.

Role

The World Agent’s function is to extract proposed rules from source material, generate predicate code, propose rule-change candidates from customer-operator feedback, and maintain discovery continuity across versions. It operates continuously against the world model it resides in, working through the Evolution Loop and producing artifacts the operator decides on.

The World Agent’s responsibilities per ADR-081 and ADR-090:

• Distillation-driven rule extraction. From operator-ingested source material (web resources, statute, regulatory guidance, scholarly publication, internal customer documentation), the World Agent extracts proposed rules covering the observable domain shape, stores each document as a provenance source, and anchors per-rule provenance back to specific source-material excerpts. This is the primary authoring path per Evolution Loop — Phase 1.
• Web-research gap-filling. Bounded online research shaped by observation of the ingested corpus — query construction from gap analysis, source evaluation against authority + recency + relevance, provenance discipline distinguishing web-sourced rules from operator-provided distillation. Scope is tied to the domain being authored, not unbounded web traversal.
• Predicate code generation. From an enshrined-pending rule’s natural-language form, the World Agent generates the deterministic predicate code that runs inside the deployed action module. The generated code is constrained at generation time (AST-level static analysis rejects I/O, mutation, nondeterministic constructs) per ADR-083 D2.
• applies_when generation. When a rule needs conditional activation (multi-stage classification, scope refinement), the World Agent proposes the applies_when filter alongside the main predicate.
• Inline test proposal. The World Agent proposes inline tests co-located with the predicate, drawn from the rule’s natural-language intent. The agent owns its generated module’s verification surface (per project_eval_system_separate_from_agents memory — evals over agents are a separate parallel system, not a World Agent function).
• Provenance citation drafting. The World Agent proposes the authoritative-source citations the rule depends on, for operator verification at the conformity gate.
• Customer-operator feedback processing. Per Evolution Loop — Phase 2, the World Agent processes structured feedback from customer-side operators against historical decisions (annotations, rule-level commentary, outcome reports, flag-for-review signals) into proposed rule changes — revisions, additions, retirements — for the next publication cycle.

The World Agent is a proposer, never an enshrining authority. Every promotion of a rule to a published world-model version requires human sign-off — the World Agent participates in the pipeline that leads up to that gate, runs the implementation-readiness gate on its own outputs, and surfaces evidence; the operator runs the conformity gate and decides publication.

Processing customer-operator feedback

A single flagged decision is interesting. The same pattern of feedback recurring across the customer’s decision history is a candidate for rule revision or new rule authoring.

The World Agent aggregates customer-operator feedback (per Evolution Loop — Phase 2) across the customer’s accumulated decisions, applies an N-threshold gate (configured per world model from the Operations app authoring surface; no single hardcoded value), and routes only a recurring pattern — not a one-off signal — into the rule-change proposal flow.

This keeps idiosyncratic one-off feedback out of the world model while making genuinely recurrent gaps reachable. Decision identifiers stay attached to the underlying observations as provenance; the rule change the World Agent proposes names the recurring pattern, not a single flagged decision.

The two interaction modes

Per ADR-081 D3 the World Agent supports two caller modes that share the same agent definition and runtime, distinguished by auth scope filtering at the session boundary.

Operator mode

Operators interact with the World Agent through the Operations app as an authoring and exploration surface. Concretely, operators use the World Agent to:

• Ingest source material and surface the proposed rule set distilled from it (the Phase 1 D1 primary authoring path)
• Request additional web research on observed gaps in the ingested corpus
• Generate predicate code from natural-language rules during authoring
• Propose applies_when filters and inline tests
• Review the World Agent’s rule-change proposals derived from Phase 2 customer-operator feedback
• Probe domain coverage (“what do you understand about this slice of the action’s input space?”)
• Surface coverage gaps (“where is your knowledge weakest for this action’s edge cases?”)
• Audit provenance chains (“which rules in this action trace back to which Authoritative sources?”)

The operator-mode session has access to the full world-model authoring surface: rule corpus read/write, candidate proposal, generated-code inspection, provenance review, distillation ingestion, web research, feedback-derived proposal review.

Customer mode (post-release)

Per ADR-081 D5, the World Agent serves a post-release customer-facing affordance: an explain-this-decision chat surface keyed to the customer’s current (org_id, domain_id) world. Lands just after v0 ships as the first post-v0 dashboard expansion.

The customer-mode session is read-only over the customer’s own world: explain rule traces, walk through decision metadata, surface methodology disclosure from the System Card in natural language. The World Agent tool subset for customer-mode sessions is auth-scope-filtered per ADR-081 D3 — no operator-mode tools are exposed.

The architectural commitments are already in place:

• Session boundary is per-world (per ADR-081 D2) — a customer’s chat session is bounded to one (org_id, domain_id) world.
• Conversation persistence rides ADR-043 substrate (per ADR-078 — conversation persistence carries forward as substrate even after the Spectral Agent’s retirement).
• Audit-chain capture of customer-initiated World Agent sessions per ADR-076 D3.

The World Agent’s customer-mode answers are shaped by two first-class disciplines:

• Hedges map to provenance tier. Confidence language is grounded in the provenance tier of the rules a response draws on. An Authoritative-grounded answer speaks plainly; an Observed-grounded answer hedges explicitly. This keeps epistemic honesty legible in conversation.
• “I don’t know” is the unknown zone as a first-class response. The World Agent does not confabulate when a question lands in the unknown zone of its world model. Naming the gap is a valid — and often the most useful — answer, because the gap itself is a signal the operator can act on through Phase 2 of the Evolution Loop.

Memory architecture

The World Agent uses the universal three-tier lifecycle from agent memory primitives, parameterized for the World Agent’s role.

Interaction tier — per-interaction scope. Observations from a single World Agent interaction. Dropped at interaction completion unless promoted.

Session tier — per-session scope. Observations that persist across interactions within a single operational session (operator mode) or chat session (customer mode). Dropped at session completion unless promoted.

Persistent tier — durable across sessions, anchored to (org_id, domain_id). Exploration history, code-generation patterns, rule-candidate reasoning, discovery observations, and meta-level patterns about domain evolution live here. The tier carries world_model_version as a contextual provenance column (which world-model version was active when the agent recorded this), not as a version pin — observations survive across world-model versions per the records-vs-memory boundary.

Persistent-tier typology distribution: semantic + procedural about the world’s domain. Persistent-episodic is not produced by current agent design (the schema retains episodic in the typology enum so the cell exists; doctrine + repository wrapper enforce the distribution).

The schema is a single table per agent with joint tier + typology discriminators (worlds.world_agent_memory), plus typed junctions for rule references, contradictions, and corroborations, plus a retrievable embeddings table per ADR-038 D9. See ADR-058 for the full schema.

Runtime placement

The World Agent runs in the workers tier (apps/workers entrypoint) per ADR-081 D1 and Runtime placement — the World Agent runs in the workers entrypoint of the one Cloudflare app container per ADR-109 D3, isolated from the decision hot path. The API entrypoint is thin (auth + AgentTask dispatch via the outbox + SSE streaming proxy). Tool dependencies that cross into another context wire via DI at the workers entrypoint. Supabase event substrate locked.

WorldAgentRunner — two modes

When a framework-layer caller invokes the World Agent, the call goes through the WorldAgentRunner protocol in spectral.worlds.contracts.protocols.world_agent (callee-owned OHS Protocol per ADR-065 D3). The protocol exposes two modes:

• ask(question: str, *, world_id: str) -> str — stateless: no session, no memory write/read
• chat(message: str, *, session_id: str, world_id: str, session_scope: str) -> str — stateful: session-tier and interaction-tier memory accrue; session_scope is one of operator / customer per ADR-081 D3 and gates which tools the World Agent exposes for the session

One-shot operator questions consume ask; operator-direct chat and the post-release customer-facing chat affordance both consume chat (with different session_scope values). The implementation lives in spectral.worlds.application.world_agent_runner; the workers entrypoint composes the impl into the consuming framework deliverable’s tool factory at startup.

Rule non-memorization

The World Agent never memorizes rules. Rules are part of the world model itself — the World Agent has unrestricted read access to them at all times. Memorizing rules would create a secondary representation that could drift from the canonical rule set, degrading provenance integrity.

The World Agent’s memory contains reasoning, code-generation patterns, exploration history, and discovery observations — never rule content. This is enforced by design: the memory system has no promotion path to rule storage. Rule changes are proposed through the Evolution Loop and written to the world model’s rule store through that governed path, not through a memory promotion.

What’s next

• Evolution Loop — the two-phase governed workflow the World Agent participates in (Phase 1 onboarding + Phase 2 post-deployment iteration)
• World Model — the context schema, configuration, and action registry the World Agent generates against
• Agent Memory Primitives — universal three-tier lifecycle the World Agent’s memory is parameterized from
• Customer Dashboard — the customer surface through which the post-release chat affordance and the Phase 2 customer-operator feedback flow