Mazda Orchestrator Team Construction Plan

What Changes

• Mazda stops carrying every operation as one overloaded personal toolset.
• Mazda delegates to named stage agents through stable handoff contracts.
• Every stage writes an artifact that can be replayed, tested, audited, or resumed.
• Self-improvement is promoted from "extra tools" to a governed workflow lane.

What Does Not Change

• Finance checks that must be exact stay in Python/SQL/YAML-backed services.
• Only the storage lane writes final expense rows.
• Improvement proposals never auto-activate without gates.
• Mazda still records traces, evaluates outcomes, proposes changes, and learns.

Orchestration

interface IOrchestratorAgent {
  runDocumentJob(request: DocumentJobRequest): OrchestratorRunResult
}

interface IAgentTeamFactory {
  createTeam(profile: TeamRuntimeProfile): AgentTeam
}

interface IWorkflowRunner {
  run(workflow: IWorkflow, context: WorkflowContext): WorkflowResult
}

Agent Ports

interface IStageAgent<TIn, TOut> {
  stageName(): string
  run(input: StageEnvelope<TIn>): StageEnvelope<TOut>
}

interface IAgentTransport {
  send(agentId: AgentId, request: AgentRunRequest): AgentRunResult
}

Artifacts

interface IRunArtifactStore {
  put(runId: RunId, artifact: Artifact): ArtifactRef
  get(ref: ArtifactRef): Artifact
  list(runId: RunId): ArtifactRef[]
}

interface IStageEnvelopeValidator {
  validate(envelope: StageEnvelope<unknown>): ValidationResult
}

Deterministic Finance Services

interface IVendorMapService {
  resolve(rawDescription: string): VendorResolution
}

interface IDuplicateLookupService {
  check(candidate: CanonicalTransaction): DuplicateVerdict
}

interface ICategoryResolutionService {
  resolve(candidate: CanonicalTransaction): CategoryVerdict
}

Storage

interface IExpenseUnitOfWork {
  validate(batch: ValidatedExpenseBatch): ValidationResult
  commit(batch: ValidatedExpenseBatch): IngestResult
  rollback(snapshot: SnapshotId): RollbackResult
}

interface IStoragePolicy {
  canStore(candidate: CanonicalTransaction): PolicyVerdict
}

Self-Improvement

interface ITraceCommandService {
  record(packet: TracePacket): TraceId
}

interface IImprovementAnalystAgent {
  analyze(trace: TraceRecord): ImprovementDraft
}

interface IProposalCommandService {
  file(draft: ImprovementDraft): ProposalId
}

Evaluation + Gates

interface IEvaluationSuite {
  score(run: OrchestratorRunResult): ScoreCard
}

interface IGate {
  evaluate(candidate: ImprovementCandidate): GateVerdict
}

interface IGateChain {
  evaluate(candidate: ImprovementCandidate): FinalVerdict
}

Reporting + Learning

interface IRunReportBuilder {
  build(run: OrchestratorRunResult): HtmlReport
}

interface ILessonWriter {
  write(lesson: AcceptedLesson): LessonId
}

Workflow Order

def test_mazda_runs_canonical_workflow_order():
    team = FakeAgentTeam()
    runner = MazdaOrchestrator(team=team, services=FakeServices())

    runner.run_document_job(sample_statement_job())

    assert team.called_stages == [
        "intake", "route", "parse", "normalize_vendor_and_identity",
        "duplicate_check", "receipt_link", "categorize",
        "storage_validation", "store"
    ]

No DB Writes Outside Storage

def test_only_storage_stage_receives_expense_repository():
    factory = MazdaTeamFactory(profile="test")

    team = factory.create_team()

    assert not hasattr(team.parser_agent, "expense_repository")
    assert not hasattr(team.router_agent, "expense_repository")
    assert team.storage_agent.expense_repository is not None

Self-Improvement Gate

def test_clean_run_does_not_file_improvement():
    services = FakeServices()
    runner = MazdaOrchestrator(team=CleanRunTeam(), services=services)

    runner.run_document_job(sample_statement_job())

    assert services.trace_command.calls == 1
    assert services.proposal_command.calls == 0

Proposal Requires Trace

def test_improvement_draft_requires_trace_id():
    draft = ImprovementDraft(trace_id=None, failure_type="wrong_category")

    result = ProposalPolicy().validate(draft)

    assert result.ok is False
    assert "trace_id" in result.reason