Operator Walkthrough

This is a narrated walkthrough — read it through; you don’t execute the steps yourself. A Spectral operations-team member (initially the founder, during dogfooding) bootstraps the first world model end-to-end so that /decide can route customer-agent requests to deployed action modules.

Note

Operation names below are illustrative. The canonical Operations app action surface lives in the Operations subtree; the narrative shape on this page holds regardless of naming specifics.

The scenario

The operator — call her Maya — is starting the first world model for US individual federal tax prep. Nothing exists yet in spectral.worlds: no world model, no context schema, no configuration block, no action registry, no rules, no source materials, no published version. The goal is to reach a published v0.1.0 world model with:

• A context schema covering filing-status and standard-deduction attributes
• A configuration block with the relevant TY 2025 dollar thresholds and brackets
• An action registry with the two in-scope actions (filing.determine_status, deduction.compute_standard)
• ~50 enshrined rules across both actions
• Deployed action modules in the module store keyed by (acme, us-tax-prep, action, 1)

So that the customer’s agent can consult /decide and receive the work frame it is expected to honor.

The full domain background lives in Domains — US Tax Prep. This page narrates the process, not the domain.

1 · Maya opens the Operations app and starts a world model

Maya logs in to the Operations app and starts a new world model for US federal individual tax prep. The New World Model form captures two starting decisions: tax year (2025) and action starting point (filing-status determination + standard-deduction computation per the domain selection in Domains — US Tax Prep).

• Operations invoked: create_world_model, set_world_model_metadata
• UI view: Operations app → Rulesets → New
• State change: WorldModel row created in spectral.worlds for (acme, us-tax-prep) with status draft, tax-year = 2025
• Codex detail: Operations — World Model Authoring

2 · Maya authors the context schema

Maya authors a context schema covering the supplied attributes the in-scope actions need (filing_status candidate, gross_income, marital_status, spouse_filing_choice), plus the system_generated attributes Spectral captures at request entry (request_time, request_id, authenticated_caller).

She also adds one computed attribute she wants available to predicates without each rule re-deriving: tax_year from request_time.

• Operations invoked: set_context_attribute (per attribute), set_context_schema
• UI view: Operations app → Rulesets → (this ruleset) → Rules
• State change: Context-schema attributes added to the working set; not yet version-locked
• Codex detail: World Model — Context schema

3 · Maya authors the configuration block

For TY 2025, the standard-deduction action needs dollar thresholds: standard_deduction_single, standard_deduction_mfj, standard_deduction_mfs, standard_deduction_hoh, plus age-65-additional and blind-additional adjustments.

Maya enters the official TY 2025 values from Form 1040 Instructions into the configuration block.

• Operations invoked: set_configuration_value (per value)
• UI view: Operations app → Rulesets → (this ruleset) → Rules
• State change: Configuration-block values added to the working set
• Codex detail: World Model — Configuration block

4 · Maya registers the action registry

Maya registers two actions per the scope decision:

• filing.determine_status — input: candidate filing status + spouse_filing_choice + marital_status; output: GREEN if the filing status is allowed for the taxpayer, YELLOW with gather_evidence_and_retry if more facts needed, RED if the choice is structurally disallowed (e.g., MFS-and-itemizing without considered-unmarried path).
• deduction.compute_standard — input: filing_status + age + blind + spouse_age + spouse_blind; output: GREEN with standard_deduction_amount in the work frame; RED if the taxpayer is constrained from claiming standard (e.g., MFS-and-spouse-itemizes).

Aggregation mode for both: winner_takes_all (the default).

• Operations invoked: set_action_registry_entry (per action), set_aggregation_mode
• UI view: Operations app → Rulesets → (this ruleset) → Rules
• State change: Action-registry entries added to the working set
• Codex detail: World Model — Action registry

5 · Maya ingests the source materials

Maya assembles the source inventory per Domains — Source Materials.

• Pub 501 — primary for filing-status determination + standard-deduction eligibility
• Form 1040 Instructions — authoritative for filing-status definitions and the standard-deduction worksheet
• Pub 17 — cross-reference context

She ingests each publication with provenance metadata attached (publication name, section taxonomy, TY 2025). She also adds Schedule A Instructions as a cross-reference for the MFS-with-itemizing-spouse rule.

• Operations invoked: attach_source_material, ingest_source
• UI view: Operations app → Rulesets → (this ruleset) → Sources
• State change: SourceMaterial rows created with provenance envelopes keyed by {publication, section, revision}
• Codex detail: Operations — Distillation

6 · Maya distills rule candidates against the sources

With the source set ingested, Maya runs distillation against the two in-scope actions. Each RuleCandidate carries:

• a natural-language statement of the rule
• a reference to the specific section of the source publication it was distilled from
• a proposed authoritative-source provenance tier (Authoritative for publication-direct, Curated for cross-referenced interpretation)
• a proposed tier (T1 / T2 / T3) for the severity classification
• a proposed outcome status (GREEN / GREEN-SKIP / YELLOW / RED) the rule emits when it matches
• a proposed applies_when filter where conditional activation is needed
• the action(s) the rule serves (a rule is assigned to one or more actions; here each serves one)

The first run yields ~80 candidates across both actions — the distiller is intentionally over-generative; Maya prunes. Each candidate lands in status = candidate, awaiting the review queue.

• Operations invoked: request_distillation, check_distillation_status, get_candidates
• UI view: Operations app → Rulesets → (this ruleset) → Sources (the run’s live progress and step timeline fold into the Sources tab alongside the source library)
• State change: RuleCandidate rows created
• Codex detail: Operations — Distillation, Evolution Loop

7 · World Agent generates predicate code

Before Maya reviews each candidate, the World Agent runs code generation on it. For each candidate, the World Agent generates:

• the deterministic predicate function (pure, no I/O, takes typed DecisionContext, returns { matched, reason?, trace? })
• the optional applies_when filter as a separate context-only predicate
• co-located inline tests drawn from the rule’s natural-language intent

The World Agent then runs the implementation-readiness gate on its own output: inline tests pass; semantic-equivalence between natural-language form and generated code holds; code provenance is captured; runtime-safety constraints (per ADR-083 D2) hold against AST analysis. Candidates that don’t pass cycle back for revision.

• Operations invoked: invoke_world_agent_codegen (per candidate)
• State change: Candidate gains generated_code, inline_tests, code_provenance fields; implementation-readiness gate report attached
• Codex detail: World Agent — Role, Evolution Loop — Implementation-readiness gate

8 · Maya reviews candidates in the review queue

This is the slowest and most important step. Maya works through the queue one candidate at a time in the ruleset’s Review tab — a two-pane view with the candidate queue on the left and the evidence bundle on the right. For each candidate that has passed the implementation-readiness gate, she runs the conformity gate (verifies authoritative-source citations and no contradictions with existing rules), then takes one of three actions:

• Approve — the candidate transitions RuleCandidate → Rule (status enshrined). The candidate’s metadata, applies_when, predicate code, and provenance are committed into the working rule catalog.
• Reject with reason — the candidate transitions to status = retired. The rejection reason is recorded and surfaces to the agent so future distillation runs avoid the same pattern.
• Request revision — the candidate stays in status = candidate with a revision note; the World Agent re-generates against the revised natural-language form.

Enshrinement is always a governed human gate. Every enshrinement passes through Maya’s UI click or an explicit API call she makes. The Operations app surfaces the evidence she needs — candidate summaries, source excerpts, related rules, the implementation-readiness report, and the conformity-gate status — but the promotion decision is hers.

Typical first-pass numbers on a fresh corpus:

• ~45 approved as-is

• ~20 revised (World Agent re-generates, Maya approves on second pass)

• ~15 rejected (out of scope, duplicate, or source misinterpretation)

• Operations invoked: summarize_candidate, get_source_excerpt, find_related_rules, get_implementation_readiness_report, get_conformity_gate_status, approve_candidate, reject_candidate, request_revision

• UI view: Operations app → Rulesets → (this ruleset) → Review → candidate evidence bundle

• State change: RuleCandidate → Rule with status = enshrined (on approve), status = retired (on reject), or status = candidate with a revision note; ApprovalDecision row persisted

• Codex detail: Evolution Loop

9 · Iterate until coverage is sufficient

Maya runs additional distillation passes as she notices gaps — an edge case the first pass missed, a sub-section of a publication not cited. Each pass is smaller than the first; convergence reflects each action’s input space narrowing.

She periodically asks the World Agent — summoned from the global dock, a right-side slide-over she opens with ⌘J (or the topbar button) over whatever surface she is on, running its operator-mode session per ADR-081 D3 — for a read-oriented check:

Maya: “Where do you think coverage is weakest right now?”

World Agent: “MFS-with-itemizing-spouse has one rule on filing.determine_status but the conditions that trigger the considered-unmarried path aren’t fully expressed. Consider a second rule covering Pub 501 §MFS, drawing on the Schedule A material you cross-referenced earlier.”

Tip

Operator and World Agent. Maya does the authoring — schema, configuration, registry, distillation, review, and publication. The World Agent generates predicate code and offers read-oriented reflection on coverage. Maya is the integration point.

Coverage is considered sufficient when the world model crosses the 50-enshrined-rule floor across both actions and the World Agent reports no critical coverage gaps inside the in-scope actions.

• Operations invoked: request_distillation, get_coverage_summary
• World Agent tools invoked (via the dock): coverage_report, identify_gaps, trace_provenance
• State change: Continued RuleCandidate → Rule transitions
• Codex detail: World Agent, Evolution Loop

10 · Publication: action-module minting and the World Model Card

When coverage is sufficient, Maya prepares the publication. She:

• Bundles the enshrined rules per action into a publication draft
• Writes release notes with the three-category restatement structure (configuration / rule / action) — for v0.1.0 everything is “added,” but the structure scaffolds future corrections per ADR-026
• Marks the publication as draft for a final review pass

Maya publishes. Before the mint, publish runs a vocabulary-reconciliation phase per ADR-107: holistically per action, it converges any divergent input names across that action’s rules onto the action’s canonical input ontology, surfacing a rename preview for Maya to arbitrate if two rules name one quantity differently (for a first v0.1.0 with coherent rules it is a no-op). Then the publication transaction is atomic across four artifact mints per Operations — Publication:

1. The new WorldModel version row (v0.1.0)
2. One ActionModule per registered action — for the two actions in scope, two modules are minted with embedded context-schema subsets, rule files (each carrying metadata + applies_when + predicate + inline tests), and manifests with module version, world-model version, code-provenance, embedded schema digest, and content hash per ADR-080 D1
3. The WorldModelCard via mint_world_model_card_at_publication
4. The outbox row for worlds.world_model_card.published

The action modules are written to the content-addressed module store keyed by (acme, us-tax-prep, action, 1). After commit, the World Agent emits worldmodel.version.published.

• Operations invoked: draft_publication, write_release_notes, edit_release_notes, request_publication
• Operator action: Final publish click — the last governed human gate
• UI view: Operations app → Rulesets → (this ruleset) → Publish (staged changes → type-to-confirm → success, with the version-history timeline and release notes folded in)
• State change: WorldModel v0.1.0 with status published; two ActionModule rows in the module store; WorldModelCard minted; ReleaseNotes row persisted
• Codex detail: Operations — Publication, Release Notes

11 · World Model Card and System Card become customer-facing

The World Model Card auto-generation pipeline reacts to worlds.world_model_card.published. The card is a customer-facing artifact derived from the published version per ADR-082 D2: the ~50 enshrined rules accumulated through steps 8–9, broken down by action, with provenance-tier distribution, configuration snapshot, action-registry summary, three-category restatement summary, and the methodology disclosure downstream consumers need to cite the version.

A customer bound to this (org, domain) deployment also sees their System Card — the deployment-scoped operational record per ADR-082 D3. At publication time the System Card window is empty (no decisions yet); it accrues as customers call /decide.

• State change: WorldModelCard content materialized; System Card snapshot pipeline initialized
• Codex detail: System Card, Customer Dashboard

What has been exercised

By the end of this walkthrough, the following surfaces have been operated end-to-end:

Surface	Exercised by
World-model creation	Step 1
Context-schema authoring	Step 2
Configuration-block authoring	Step 3
Action-registry authoring	Step 4
Source-material ingestion with provenance	Step 5
Distillation pipeline	Step 6
World Agent code generation + applies_when generation	Step 7
Implementation-readiness gate	Step 7
Review queue + conformity gate + governed enshrinement	Step 8
World Agent operator-mode exploration	Step 9
Publication transaction (4-artifact atomic mint)	Step 10
Module store keyed by (org, domain, action, version)	Step 10
World Model Card generation	Step 11
System Card initialization	Step 11
Operations app authoring surface	Steps 1–10

What’s next

With v0.1.0 published and the action modules in the module store, the customer’s agent can now invoke /decide with action: "filing.determine_status" or action: "deduction.compute_standard" and receive binding { status, work_frame, decision_metadata }. The decision-time path is documented in Decision Execution; the customer’s inspection surface is documented in Customer Dashboard.

Related reading

• Domains — US Tax Prep — domain reference
• Operations — the surface Maya works in
• Agent Architecture — the World Agent’s role
• World Model System — the model Maya is authoring
• Decision Execution — what happens when a customer calls /decide against the deployed modules
• How Spectral Works — the customer-side posture this walkthrough sets up