SOW executions

Compile a naming research SOW into an evidence-gated execution graph, queue fieldwork, and inspect completion.

A SOW execution turns contract language into a typed research plan with requirements, modules, acceptance gates, fieldwork jobs, evidence references, and a durable completion state.

Current scope

The compiler currently accepts naming-study SOWs with 12 candidate names and a primary-plus-fresh-repeat design. It rejects unsupported or incomplete research scopes instead of pretending they are executable.

Lifecycle

Compile or create

POST /api/v1/sow-executions with mode: "compile" returns a deterministic spec without writing a record. Use mode: "create" to persist a draft execution.

Supply fieldable inputs

PATCH /api/v1/sow-executions/{id} with action: "set_inputs" accepts the exact 12 candidateNames and an existing audienceId. They can be supplied together or in separate calls.

Approve

action: "approve" is refused while required inputs are missing. Approval freezes the contract that will be executed.

Start

action: "start" runs the real audience_health tool first. Health errors block execution. A passing health result and stimulus manifest complete the two gates, then the primary MaxDiff wave is queued.

Reconcile and inspect

The study worker updates module progress from linked StudyJob records, fans out the fresh repeat, runs code-only reducers, and persists artifacts. GET /api/v1/sow-executions/{id} returns the spec, runtime, completion audit, artifacts, error, and timestamps.

Execution graph

audience_health ─┬─> maxdiff_primary ─> maxdiff_repeat ─> stability ───────────────┐
stimuli_validation┘                                                                │
                   ├─> preference_crosscheck_field ─> preference_crosscheck ───────┤
                   ├─> name_diagnostics ─> diagnostic_pairwise ────────────────────┤
                   └─> open_ends ─> red_flags ──────────────────────────────────────┤
                                                                                    ├─> scoreboard
maxdiff_primary + name_diagnostics + open_ends ─> subaudience_prevalence ──────────┤
stability + preference_crosscheck + diagnostic_pairwise ─> confidence_quality ────┘
scoreboard + subaudience_prevalence + confidence_quality ─> defensibility_dossier

The compiled naming contract has 15 modules and a 26-item requirement ledger. Every required module must be complete with evidence before the execution can report complete: true.

Fieldwork plan

Every job is deliberately small enough for the bounded worker lease.

Work	Jobs	n per job	Planned assignments
Primary balanced MaxDiff	40	50	2,000
Fresh repeat MaxDiff	16	50	800
12 names × 5 diagnostics	60	50	3,000
Name-specific open ends	12	50	600
Direct-choice preference cross-check	16	50	800
Total	144		7,200

7,200 is the total number of study assignments across modules, not a claim of 7,200 unique people. The MaxDiff contract itself retains the SOW's primary n=2,000, fresh repeat n=800, and total n=2,800.

The 12-name MaxDiff design uses nine deterministic four-item blocks. Every name appears three times across the block skeleton and no pair repeats. Jobs use unique seeds and the repeat wave has its own seed range.

Built-in analysis artifacts

The worker currently computes and stores:

primary and repeat MaxDiff utilities, preference shares, best counts, worst counts, and rank
primary-versus-repeat Spearman rank agreement and stable, moved, or reversed classifications
per-name, per-dimension means and 95% intervals for recall, fit, pronounceability, distinctiveness, and connotation
all 330 diagnostic pairwise contrasts with Benjamini-Hochberg correction
direct-choice shares with Wilson intervals and all 66 corrected pairwise contrasts
open-end associations, source-row IDs, and deterministic high/medium red-flag terms

Downstream subaudience, confidence, scoreboard, and dossier modules remain evidence-gated. They do not auto-complete merely because fieldwork exists. A worker or operator must attach their required artifacts through a module transition.

Fail-closed behavior

A job is complete only when it returns:

a persisted study ID
a positive integer nFielded
aggregate IDs for quantitative work, or a persisted respondent-row artifact for qualitative work

Zero respondents, missing lineage, failed jobs, underfilled modules, missing evidence, or unmet dependencies block advancement. Retried dispatch is idempotent through the execution/job key pair.

Action	Effect
`set_inputs`	Binds names and/or the fieldable audience; regenerates deterministic job plans.
`approve`	Moves a complete draft contract to `approved`.
`start`	Runs audience health, completes the two gates, queues the primary jobs, and triggers the worker.
`transition`	Applies a module state, evidence references, completed units, or an error while enforcing dependencies and acceptance gates.
`cancel`	Cancels an execution that is not already complete.

The standalone full API reference remains available at Mavera API Reference.