Policy reference

A rule is a policy row. This page is the schema of that row, the grammar of its condition, the behaviour of each action, and the attention arithmetic those actions feed. Numbers here are the defaults in code; a program can override the attention ones in its spec.attention_config.

Routes: GET /api/v1/policies (filters project_id, episode_profile_id, status, trigger_type), POST /api/v1/policies, GET, PUT and DELETE /api/v1/policies/{policy_id}, POST /api/v1/policies/{policy_id}/test, GET /api/v1/policies/{policy_id}/executions. Reads need the Read scope; writes need Write.

The rule schema

Rules are environment-bound: a rule authored in the sandbox never evaluates a production observation.

Triggers

An observation only reaches observation_create rules after it is linked to an active episode, and it is linked only when the episode's program lists that signal in required_signals. The public POST /api/v1/observations write links to the episode_ids you pass explicitly and does not evaluate rules; device paths (the cellular webhook, wearable syncs, the DSP pipeline) link and evaluate.

The condition grammar

The expression language is deliberately small:

• Comparisons: >=, <=, >, <, ==, !=
• Logic: AND, OR, NOT, parentheses
• Arithmetic: +, -, *, /
• Null checks: state.start_ts != null
• Variables: signal names (hr, hrv_rmssd, spo2, systolic), state.<key>, baseline.<key>
• Thresholds: {thresholds.systolic_high} or $systolic_high, substituted from condition_params before parsing

On an observation_create trigger the reading is bound as follows: LOINC 8867-4 becomes hr, 80404-7 becomes hrv_rmssd, 59408-5 becomes spo2, any other coded scalar becomes observation_value, and each numeric component of a panel observation is bound under its own name (a blood-pressure panel exposes systolic and diastolic).

POST /api/v1/policies/{policy_id}/test evaluates the condition against signals, state and baselines you supply, with the rule's own condition_params as thresholds, and returns condition_matched without executing anything.

Actions

Each action is an object with a type and the fields below. Attention actions require an episode in context; without one they record success: false with "error": "No episode context" and the rule moves on.

Every evaluation that passes the trigger filter is recorded in the rule's execution history, matched or not: trigger_type, trigger_ref, condition_result, actions_executed, actions_failed, evaluation_duration_ms, executed_at. A rule in cooldown, or a reading outside the rule's trigger filter, is skipped before evaluation and leaves no execution row.

Rules the program materializes

Two kinds of rule are derived from a program's spec on every save, so the authored document and the running rule cannot drift:

• Each agent with an on_schedule trigger gets a schedule rule whose action is enqueue_agent for that agent.
• A symptom_protocol.trigger gets an observation_create rule scoped to the program, filtered to the trigger's biosignal_slugs, with the trigger's expression, thresholds as condition_params, cooldown_seconds, max_sessions_per_episode as the execution cap, max_reading_age_minutes as the data-age guard, and a single start_symptom_session action naming the protocol's id.

Materialized rules appear in GET /api/v1/policies like any other and are re-synced when the program is saved.

Attention

Attention is computed, never stored as an opinion. The calculator reads the episode's active contributions, decays each one, sums the ones still above a minimum, multiplies for converging signals, caps at 100, and applies the floor:

current(c)  = c.points × 0.5 ^ (hours_since(c.created_at) / c.half_life_hours)
base_sum    = Σ current(c)  for active c with current(c) ≥ min_contribution_threshold
attention   = max(floor, min(100, base_sum × correlation_multiplier))

correlation_multiplier is chosen by the largest signals list on any single active contribution: one signal 1.0, two signals 1.25, three or more 1.5.

Defaults, and where a program overrides them

All of these live in spec.attention_config; a program without the block uses the defaults.

The floor and acknowledgment

A floor is set by a rule (set_attention_floor) and is the minimum attention until a person acknowledges. POST /api/v1/episodes/{id}/attention/acknowledge takes new_floor (must be less than or equal to the current floor), reason, and optional action_taken and notes; it writes an acknowledgment record with the previous floor and the attention at that moment, then lowers the floor and recomputes. A floor cannot be raised through acknowledgment.

Who else writes the ledger

• The symptom agent adds a contribution when a closed interview surfaces something a person should see; reviewing that agent run clears it.
• A care hand-off routed by a protocol rule adds a contribution sourced care_handoff; resolving the hand-off clears it.
• Every recompute that changes the level also emits an attention_level observation on the episode, so attention over time is queryable like any other signal.

GET /api/v1/episodes/{id}/attention returns level, level_label, floor, base_sum, correlation_multiplier, active_contributions, top_reason, the per-contribution breakdown, and config_source (profile:<slug> or system_default). GET /api/v1/episodes?attention_gte=61 lists the episodes at or above a level.