> ## Documentation Index
> Fetch the complete documentation index at: https://badixth-dc85e378.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Finding Provenance: Machine-Raised and Human-Raised Findings
> Amendment C. How the platform distinguishes a finding raised by Semai from a finding raised by a person, and what that distinction costs across the four layers of the data model.
Humans on this platform can escalate a finding, demote it, contradict it, resolve it, or dismiss it. They cannot originate one. Every finding today is a `rulecard_firing`: the engine matched a rule card against the signal layer, and only then can a scout or an agronomist act on it. If the satellite cannot see it, the platform cannot record it.
That gap bites hardest where the instrument is weakest. Panel dryness on rubber [shows as a slow, block-wide NDVI decline over one to three years](/guides/Crop/Rubber/rubber-diagnosis). Phosphorus and potassium status are [indirect only](/guides/crop-health-monitoring); ion species [cannot be separated by multispectral](/guides/crop-health-monitoring). The literature documents these hazards in full and the product cannot record a conclusion about any of them.
The UI has said *Findings* since Pass 2, and the design system's `FindingCard` renders both machine and human sources the same way. The general word was in use before the general entity existed. Amendment C promotes `finding` to the general entity, adds a required `provenance` discriminator, and specifies what the rest of the model does with the human-raised case.
Amendment C is an ontology change. It touches Layer 1 (entity shape), Layer 2 (lifecycle and expiry as a modelling event), Layer 3 (guardrails and safety floor), and Layer 4 (seed). The band model retrofit cost roughly 15 phases because Layer 1 shipped without `crop`, `ecosystem`, and `stage`. Provenance is the same shape and is best resolved before the human-findings surface ships.
## Shape: one entity with a provenance discriminator
**Decision.** A finding is one entity (`finding`) with a required `provenance` discriminator, not two entities behind a shared interface.
**Argument.**
A `rulecard_firing` and a human observation share more than they differ on. Both are:
* Bound to a `field` and a `crop_cycle`.
* Placed in phenology (`stage_window` for machine; `observed_at` phenology-resolved for human).
* Consumed by [Activity & Alerts](/guides/activity-and-alerts), [Field Scouting](/guides/field-scouting), and [Verification](/guides/verification) through the same event contract.
* Rolled up by the [Aggregation Model](/concepts/aggregation-model) as hazard counts.
What differs is the **origin block** and everything derived from it. A human finding has no rule card, therefore no `drivers`, no `severity` formula, no `yield_impact` layers, and no `mitigation.window_days_by_severity`. It has an author, a rationale, and hand-attached evidence.
Two entities force every downstream consumer (the risk feed, scout task creation, verification bundle assembly, the advisor's retrieval layer) to branch on type. One entity with nullable machine fields lets every consumer read `provenance` and treat the null case honestly, which matches the product's habit of showing an em dash rather than fabricating a comparable figure.
**Cost of the choice.** Every `rulecard_firing` field the current schema treats as required (`rulecard_id`, `drivers`, `severity_formula_output`, `yield_impact_resolved`) becomes conditional on `provenance = machine`. Consumers must respect the null case. This is the same discipline the [Aggregation Model](/concepts/aggregation-model) already applies ("Never average an average") and the same discipline the [Verification Model](/concepts/verification-model) already applies to weak cross-checks.
## Vocabulary
Use this table when reading any other page in the amendment or in the downstream modules. These terms are strict; do not use them interchangeably.
| Term | Definition |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Finding** | The unified entity. One record per hazard-instance on a field-and-cycle, regardless of who raised it. |
| **Provenance** | Required enum on every finding. `machine` \| `human`. Never null, never inferred. |
| **Machine finding** | A `finding` with `provenance = machine`. Produced by the risk engine matching a rule card against the signal layer. Carries `rulecard_ref`, `drivers`, resolved `severity`, resolved `yield_impact`, and a `mitigation` window. This is the existing `rulecard_firing` shape, renamed. |
| **Human finding** | A `finding` with `provenance = human`. Raised by an authorized actor from a field visit or a desk review. Carries `author`, `rationale`, `evidence_refs`, and an `asserted_severity`. Machine fields (`rulecard_ref`, `drivers`, `yield_impact`) are null. |
| **Asserted severity** | The severity band the human author claims, chosen from the same ladder as the machine ladder (`low`, `medium`, `high`, `critical`). Subject to the raising bounds in [Severity and the safety floor](#severity-and-the-safety-floor). |
| **Effective severity** | The band the rest of the platform reads. For machine findings, computed. For human findings, `asserted_severity` once input validation has confirmed the author's role permits that band per [Who may raise, per role](#who-may-raise-per-role). |
| **Acknowledgement** | A property recorded on an already-`active` human finding: `acknowledged_by`, `acknowledged_by_role`, and `acknowledged_at`. Not a state, not a gate; see [Severity and the safety floor](#severity-and-the-safety-floor). |
| **Delivery policy** | An organisation-level setting on how a human finding reaches its audience: `immediate` (deliver every band on the routing its `severity_effective` earns) or `hold_until_acknowledged` (hold `high` up to the safety-floor mute bound, never hold `critical`, deliver every other band immediately). Snapshotted onto each human finding as `delivery_policy_at_creation`. See [Delivery policy](#delivery-policy). |
| **Corroborated** | A `resolved` human finding is corroborated when at least one of: `scout.completed` on the same hazard confirmed it, `map.applied` cleared it, or the satellite delta for the hazard's cross-check window is consistent with the observation. Uncorroborated `resolved` findings stay in the record but do not feed `farm_history`. See [Feedback into farm\_history](#feedback-into-farm_history). |
**Provenance is not "who typed it".** An agronomist who accepts a machine finding does not change its provenance. Provenance records where the **claim** originated: an engine evaluating a rule card, or a person asserting an observation. A machine finding annotated by a human is still `provenance = machine`.
## Fields
The finding record. Machine-only fields are conditional on `provenance = machine`; human-only fields are conditional on `provenance = human`. Fields without a doc source are **decided here** and marked.
| Field | Type | Applies to | Source |
| ----------------------------- | ----------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string, prefix `fnd_` | both | Decided. Follows the `fld_` / `blk_` / `ssn_` / `obs_` convention in [Field Data Model](/concepts/field-data-model). |
| `field_ref` | FK → `field` | both | [Field Data Model](/concepts/field-data-model) |
| `crop_cycle_ref` | FK → `season` | both | [Crop Cycle Models](/concepts/crop-cycle-models); a finding is always inside one cycle |
| `provenance` | enum: `machine` \| `human` | both | Decided (Amendment C, this page) |
| `category` | enum (existing rule card categories) | both | [Risk Model](/concepts/risk-model#field-reference) |
| `hazard_ref` | string (rule card id or literature ref) | both | [Risk Model](/concepts/risk-model). For machine: the fired rule card. For human: the closest matching literature page (`literature_ref`) or `unclassified`. |
| `stage_at_finding` | string | both | Resolved from planting date and observation time per [Crop Cycle Models](/concepts/crop-cycle-models) |
| `observed_at` | ISO 8601 | both | For machine: satellite pass time. For human: author's reported observation time. |
| `logged_at` | ISO 8601 | both | Envelope, per [Audit Envelope](/snippets/audit-envelope) |
| `rulecard_ref` | FK → rule card | machine only | [Risk Model](/concepts/risk-model) |
| `rulecard_version` | string | machine only | [Risk Model](/concepts/risk-model#authoring-rule-cards) |
| `drivers_snapshot` | object | machine only | [Risk Model](/concepts/risk-model#field-reference) |
| `yield_impact_resolved` | object | machine only | [Risk Model](/concepts/risk-model#yield-impact-layers) |
| `mitigation_window` | object | machine only | [Risk Model](/concepts/risk-model#days-to-mitigate) |
| `severity_computed` | enum: `low` \| `medium` \| `high` \| `critical` | machine only | [Risk Model](/concepts/risk-model) |
| `author_ref` | FK → `user` | human only | [Role Model](/snippets/role-model) |
| `author_role` | functional role snapshot | human only | [Role Model](/snippets/role-model); snapshot per [Audit Envelope](/snippets/audit-envelope) |
| `rationale` | text | human only | Decided. Free text; required, minimum length enforced by input validation. |
| `evidence_refs` | array of refs (photo, note, sensor, external doc) | human only | Decided. At least one item required at `asserted_severity ≥ medium`. |
| `asserted_severity` | enum: `low` \| `medium` \| `high` \| `critical` | human only | Decided (Amendment C, this page) |
| `severity_effective` | enum | both | [Risk Model](/concepts/risk-model); see [Severity and the safety floor](#severity-and-the-safety-floor) |
| `acknowledged_by` | FK → `user` | human only, conditional | Decided (see [Severity and the safety floor](#severity-and-the-safety-floor)). Null until acknowledged. Must not equal `author_ref`. |
| `acknowledged_by_role` | enum: `agronomist` \| `estate_manager` | human only, conditional | Decided. Role snapshot at acknowledgement. `estate_manager` records the fallback path per [Guardrails → Preconditions](#guardrails); a manager's acknowledgement is not an agronomist's and the record must not imply otherwise. |
| `acknowledged_at` | ISO 8601 | human only, conditional | Decided. Null until acknowledged. |
| `promoted_by` | FK → `user` | both, conditional | Decided. The actor who applied `promote_severity`. Null on the machine path, where the effect fires from `system` per [Risk Model → activity bindings](/concepts/risk-model#activity-bindings). Set when a human promotes, which is why the field exists: every existing use of `promote_severity` is system-driven and therefore never needed an actor. |
| `promoted_by_role` | functional role snapshot | both, conditional | Decided. Role at promotion, snapshot per [Audit Envelope](/snippets/audit-envelope). |
| `promoted_at` | ISO 8601 | both, conditional | Decided. Null until promoted. |
| `severity_before_promotion` | enum: `low` \| `medium` \| `high` \| `critical` | both, conditional | Decided. The band the finding carried before `promote_severity` applied. Preserves the original assertion so a promoted finding still shows what its author claimed. |
| `delivery_policy_at_creation` | enum: `immediate` \| `hold_until_acknowledged` | human only | Decided. Snapshot of the organisation's delivery policy at `logged_at`. Immutable per the append-only rule in [Guardrails → Refusals](#guardrails). Null on machine findings (no policy applies). |
| `corroboration_ref` | FK → event (`scout.completed`, `map.applied`, or satellite pass) | human only, conditional | Decided. Set when `state = resolved` and the finding is corroborated. See [Vocabulary](#vocabulary). |
| `expiry_reason` | enum: `unactioned_watch` \| `unactioned_urgent` \| `cycle_closed` | both, conditional | Decided. Set when `state = expired` or `state = closed_with_cycle` per [Lifecycle](#lifecycle). |
| `state` | enum: see [Lifecycle](#lifecycle) | both | [Risk Model](/concepts/risk-model); Amendment C extends the state list |
## Lifecycle
`rulecard_firing` today runs `dormant → active → frozen → resolved | dismissed`. See the `activity_bindings` effect vocabulary in [Risk Model](/concepts/risk-model#activity-bindings) for how transitions are triggered.
A human finding is never `dormant`. Nothing fires it; someone writes it. The moment it exists, it is already asserted.
### State applicability
| State | Machine | Human | Trigger |
| ------------------- | :-----: | :---: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dormant` | ✓ | — | Rule card exists for the crop and stage but drivers do not match. |
| `active` | ✓ | ✓ | Machine: `alert_bindings` fired and `drivers` matched. Human: raised at any band the actor's role permits per [Who may raise, per role](#who-may-raise-per-role). A human finding always enters `active` on raise; acknowledgement is recorded on the finding, not gated in front of it. |
| `frozen` | ✓ | ✓ | Machine: `raise_contradiction` from a scout. Human: paired machine finding on the same hazard disagrees (see [Downstream behaviour](#downstream-behaviour)). |
| `resolved` | ✓ | ✓ | Machine: `map.applied` reset. Human: author or an in-scope `agronomist` or `estate_manager` marks resolved with a `resolution_note`. Corroboration recorded on `corroboration_ref` if present. |
| `dismissed` | ✓ | ✓ | 14-day suppression per [Semai Advisor mute bounds](/guides/semai-advisor/overview#mute-bounds-by-severity). |
| `expired` | ✓ | ✓ | Finding sat in `active` past its severity-scaled expiry window without action. The clock starts at `active`. See [Expiry](#expiry). |
| `closed_with_cycle` | ✓ | ✓ | The parent `season` closed while the finding was `active` or `frozen`. Terminal. See [Cycle close](#cycle-close). |
`expired` and `closed_with_cycle` are the two new states Amendment C adds. Every other state is reused. The consumer contract (Activity & Alerts, Verification, Aggregation) already treats these states as opaque enum values, so the additions are additive.
An earlier draft of Amendment C introduced a third state, `pending_review`, that gated `critical` human claims until a peer signed. That mechanism has been withdrawn before ship in favour of the acknowledgement model in [Severity and the safety floor](#severity-and-the-safety-floor). Because Amendment C has not shipped, there is no migration: the state never existed in a running schema.
### Who acts
| Transition | Actor role | Source |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `— → active` (machine) | `system` | [Risk Model](/concepts/risk-model) |
| `— → active` (human) | Any role permitted at the asserted band per [Who may raise, per role](#who-may-raise-per-role) | [Role Model](/snippets/role-model); see [Guardrails](#guardrails) |
| Record `acknowledged_by` / `acknowledged_at` on an `active` human finding | `agronomist` in scope, not `author_ref`; `estate_manager` in scope, not `author_ref`, under the fallback rule in [Guardrails → Preconditions](#guardrails) | Decided; see [Severity and the safety floor](#severity-and-the-safety-floor) |
| `active → resolved` | `author_ref` or any `agronomist` \| `estate_manager` in scope | [Role Model](/snippets/role-model) |
| `active → frozen` | `system` on `raise_contradiction` | [Risk Model](/concepts/risk-model#activity-bindings) |
| `active → expired` | `system` on window elapse | Decided; see [Expiry](#expiry) |
| any open state → `closed_with_cycle` | `system` on `season.closed` | Decided; see [Cycle close](#cycle-close) |
### Cycle close
When the parent `season` closes per [Crop Cycle Models](/concepts/crop-cycle-models), every finding on that cycle that is still in an open state (`active`, `frozen`) transitions to `closed_with_cycle`. The transition is terminal: the finding does not fire, does not deliver notifications, and does not accept further state changes. It stays in the record for the season's history, per the [Verification](/guides/verification) audit trail and per the [Aggregation Model](/concepts/aggregation-model) rollup requirement to reproduce the season's rollups later.
`closed_with_cycle` is distinct from `resolved`: a resolved finding was acted on. A cycle-closed finding was not, and the record should not claim otherwise.
### Expiry
An unactioned finding is a modelling event, not housekeeping. The window scales with severity; expiry is disclosed on every surface that shows the finding; and expiry is audited so the [Aggregation Model reproducibility](/concepts/aggregation-model) requirement holds.
**When the clock starts.** The expiry clock starts when a finding enters `active`, which for human findings is the moment of raise. A human finding is a live signal from creation, so there is no earlier state to protect it from expiring. Acknowledgement is recorded against an already-active finding and does not gate, pause, or restart the expiry clock; the unacknowledged case is governed by the [Guardrails → Escalation](#guardrails) timer, which runs in parallel.
**Windows by effective severity.**
| `severity_effective` | Expiry window | Rationale |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `low` | 30 days | Matches the mute bound; a low-severity finding untouched for a month is normal. |
| `medium` | 14 days | Half the mute bound; unattended-medium is meaningful but not urgent. |
| `high` | 72 hours | Unrelated to the 4-hour mute bound per [Safety floor](/guides/semai-advisor/overview#safety-floor). The mute bound governs how long notification may be suppressed; this window governs how long an unactioned finding survives. Neither bounds the other. |
| `critical` | 24 hours | Every critical finding should either resolve or escalate within a day; longer than that is a workflow failure. |
**Disclosure.** Every surface that shows an expired finding must state that it expired, when, and why ("Expired unactioned on 12 Jul · window: 72 hours at high severity"). Expiry is a visible event on the [Activity & Alerts](/guides/activity-and-alerts) feed, on the field's finding list, and in any [Verification](/guides/verification) bundle that includes the finding.
**What expiry does not do in Amendment C.** Expiry does not modify the yield estimate. Whether an expired unactioned finding should count against the season's yield model is a Layer 2 question that belongs in a companion amendment; see [Open Questions](#open-questions). Amendment C lands the state, the windows, and the disclosure rule; a subsequent amendment can wire expiry into `yield_impact.resolved` once the weight function, composition rule, and machine parallel (`task.overdue` on machine findings) are decided.
## Severity and the safety floor
This is the sharpest question in the amendment. A platform where any user can manufacture an unsuppressible alert has a problem. A platform where a trained agronomist standing in the field cannot mark what they have seen as urgent has a worse one.
Amendment C resolves the question in two parts. Who may reach each band is a per-role table (below). Whether a serious claim reaches its audience immediately or waits for a peer to confirm is an organisation-level delivery policy, bounded by the safety floor (see [Delivery policy](#delivery-policy)). An earlier draft gated `critical` claims at raise time in a `pending_review` state; that mechanism has been withdrawn in favour of the model here.
### The safety floor as it stands
From [Semai Advisor Safety floor](/guides/semai-advisor/overview#safety-floor):
* Severity ≥ `high` signals cannot be suppressed, muted beyond the bounded window, or personalized away.
* The mute bound is per-severity: `critical` never, `high` 4 hours, `medium` 7 days, `low` 30 days.
* Dismissal of a specific firing is 14 days on the same rulecard + field + cycle, not subject to the mute bound.
The safety floor keys off `severity_effective` and does not distinguish provenance. Amendment C keeps that.
### Who may reach each band
A human finding may **assert** the bands its author's role permits, and enters `active` immediately on raise. The safety floor's mute bounds apply to `severity_effective`, not to provenance.
| Role | `low` / `medium` | `high` | `critical` |
| --------------------------- | :-------------------: | :-------------------: | :-------------------: |
| `scout` | ✓ | — | — |
| `regional` (agency officer) | ✓ | — | — |
| `agronomist` | ✓ | ✓ | ✓ |
| `approver` | ✓ | ✓ | ✓ |
| `estate_manager` | ✓ | ✓ | ✓ |
| `estate_admin`, `org_admin` | — | — | — |
| `viewer` (org role) | — | — | — |
| `on_call` (overlay) | inherits primary role | inherits primary role | inherits primary role |
The two cells to argue on this page, because they are the ones a future reader will second-guess:
**Why `approver` and `estate_manager` reach `high` and `critical` directly.** An estate manager runs the estate's day-to-day operations and owns overdue tasks and deviation escalations. Requiring an agronomist to countersign before that role may call a hazard serious inverts the hierarchy the platform is deployed into. `approver` sits in the same operational lane.
**Why `scout` cannot reach `high` at all.** The distinction the lede draws is between *any user* and *a trained agronomist*. A scout's documented function is ground-truth work: visits, photos, observations. Diagnosis is not in that lane. A capped scout is not silenced: they raise at `medium` with evidence and an in-scope `agronomist` promotes in one action per [Who may raise, per role](#who-may-raise-per-role).
**And why the band matters at `high`, not at `critical`.** The safety floor engages at `high`: signals at severity ≥ `high` cannot be suppressed, muted beyond the bounded window, or personalised away. `high` is where the platform's least reversible behaviour switches on, and who may reach it alone is the real question. `critical` is simply the band above it; every role who may reach `high` may reach `critical`, and every role who cannot reach `high` cannot reach `critical` either.
### Acknowledgement
Acknowledgement is not a gate. It is a property recorded on an already-active finding:
| Field | Meaning |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| `acknowledged_by` | The in-scope user who confirmed the assertion. Must not equal `author_ref`. Null until acknowledged. |
| `acknowledged_by_role` | Snapshot: `agronomist` on the normal path, `estate_manager` under the fallback. |
| `acknowledged_at` | When. Null until acknowledged. |
Who may acknowledge: an in-scope `agronomist` who is not the author. Fallback: an in-scope `estate_manager` where no other in-scope `agronomist` has been active in the preceding 24 hours. The author is barred by the not-`author_ref` rule and is excluded from the fallback test on the same reasoning: their own activity cannot count as the agronomist activity that blocks the fallback, so a single-agronomist estate always takes the fallback path. The fallback is recorded on `acknowledged_by_role` and disclosed wherever the acknowledgement is shown; a manager's acknowledgement is not an agronomist's and the record must not imply otherwise.
Acknowledgement is safety-critical for `high` and `critical` and required by the escalation guardrail below; it is not required for the finding to be live.
### Delivery policy
Whether a serious human finding reaches its audience immediately or waits for acknowledgement is organisational, not universal. The platform serves federal agencies, estate groups, cooperatives, and smallholder collectives, and their governance genuinely differs. Delivery policy is a per-organisation setting, set by an `estate_admin` alongside verification presets and notification defaults.
Two settings. Named for what the administrator is choosing, not in spec vocabulary. Enum values in the schema are `immediate` and `hold_until_acknowledged`; user-facing labels are the ones below and are the responsibility of the labels file.
| Setting | Enum value | Behaviour |
| ----------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Send immediately, confirm after** | `immediate` | Every human finding delivers on the routing its `severity_effective` earns. Acknowledgement is recorded when it happens and escalates if it does not. |
| **Confirm before sending** | `hold_until_acknowledged` | A human finding at `high` holds delivery until acknowledged, **or until its safety-floor mute bound elapses, whichever comes first**. Every other band delivers immediately. `critical` is never held. |
**The floor is the bound, and this is the load-bearing sentence:** a held finding is an active finding, so the safety floor applies to it in full. The floor's mute-bound table (`critical` never, `high` 4 hours, `medium` 7 days, `low` 30 days) then settles what may be held and for how long:
* **`critical` is never held, under either setting.** It delivers immediately, always. Acknowledgement is recorded after the fact and escalates if absent.
* **`high` may be held for at most 4 hours**, its existing mute bound, and delivers automatically when that elapses whether or not anyone has acknowledged it.
So the organisation setting is **not an exception to the safety floor. It is an instance of it.** A future reader will otherwise assume a governance toggle can override a safety rule, and it cannot.
**The gate lands on `high`, not on `critical`.** The most severe band is the one that must never wait. This reads as counter-intuitive and is not: `critical` is where noise is answered by the audit trail, by the escalation timer, and by the per-role rolling caps on `high` and `critical` raises (see [Guardrails → Rate and scope limits](#guardrails)), not by delaying the page. Since delivery is no longer gated at `critical`, those rate caps are now the primary defence against a manufactured `critical` alert, not a supporting one.
### The mode travels with the finding
The delivery policy in force at creation is snapshotted onto the finding as `delivery_policy_at_creation` and disclosed wherever the finding crosses an organisational boundary: every [Verification](/guides/verification) bundle, every rollup in the [Aggregation Model](/concepts/aggregation-model), and every dashboard in the [Effect Methodology](/concepts/effect-methodology) that mixes findings from more than one organisation.
Without this, a national dashboard aggregates findings that passed different governance bars and presents them as one number. That is the same class of error as averaging across crops, and the same discipline applies: disclose rather than hide, and never present two differently-constituted quantities as comparable without saying so.
### Interaction with dismissal
Dismissal of a human finding follows the same 14-day rule as machine dismissal: 14-day suppression on the same `hazard_ref`, `field_ref`, and `crop_cycle_ref`. A dismissed human finding whose `severity_effective` is `critical` still surfaces every re-raise on the same field during the suppression window as a new activity entry; only the notification is suppressed. This mirrors the existing rule in [Semai Advisor Safety floor](/guides/semai-advisor/overview#safety-floor).
## Guardrails
This module follows the shared [guardrails template](/snippets/guardrails-template). The agent and every non-agent write path must respect these rules. Amendment C does not introduce a ninth category.
| Category | Rule |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Input validation** | `provenance` is required. Machine writes require `rulecard_ref`, `rulecard_version`, `drivers_snapshot`, `yield_impact_resolved`, `mitigation_window`, `severity_computed`. Human writes require `author_ref`, `author_role`, `rationale` (minimum 40 characters), `hazard_ref` (rule card id or literature ref or `unclassified`), `stage_at_finding`, `asserted_severity`, and `delivery_policy_at_creation` (snapshot of the organisation setting at `logged_at`; enum `immediate` \| `hold_until_acknowledged`). Human writes at `asserted_severity ≥ medium` require at least one `evidence_ref`. `field_ref` and `crop_cycle_ref` must satisfy the actor's entitlement scope per [Role Model](/snippets/role-model). |
| **Preconditions** | Field must have an active `crop_cycle` per [Field Data Model](/concepts/field-data-model#seasons); a finding cannot exist on a closed cycle. Human writes must be made by a functional role permitted at the asserted band per [Who may raise, per role](#who-may-raise-per-role). Recording `acknowledged_by` on a human finding requires a user whose `user_ref` is not the `author_ref` and whose role is `agronomist` **whose entitlement scope includes the target estate** per [Role Model](/snippets/role-model). Fallback: where no other in-scope `agronomist` has been active in the preceding 24 hours, an `estate_manager` whose scope includes the target estate may acknowledge; the `author_ref` is excluded from the test because the author cannot acknowledge their own finding, so a single-agronomist estate always takes the fallback path; the fallback is recorded on `acknowledged_by_role` and disclosed wherever the acknowledgement is surfaced (a manager's acknowledgement is not an agronomist's and the record must not imply otherwise). |
| **Refusals** | Writing a finding on a field the actor cannot see (entitlements). Setting `provenance = machine` from any source other than `system`. Setting `provenance = human` from `system`. Any role asserting a band not permitted for it per [Who may raise, per role](#who-may-raise-per-role) (in particular, `scout` or `regional` asserting `high` or `critical`; promotion by an in-scope `agronomist` is the path upward). Acknowledging one's own finding (`acknowledged_by` must not equal `author_ref`). Editing `provenance`, `author_ref`, `rulecard_ref`, or `delivery_policy_at_creation` on an audited finding (append-only past commit). `severity_effective` is append-only with **one stated exemption**: the `promote_severity` effect defined in [Risk Model → activity bindings](/concepts/risk-model#activity-bindings), which moves severity one band up and writes an append row rather than mutating in place. Without this exemption the refusal would also forbid the existing machine promotion on `task.overdue` per [Field Scouting](/guides/field-scouting), which the platform already performs. Holding a `critical` finding's delivery under any setting. Holding a `high` finding beyond its 4-hour safety-floor mute bound. Suppressing a task that originates from a `severity_effective ≥ high` finding **whatever its origin** (this widens the existing [Field Scouting refusal](/guides/field-scouting#guardrails); see [Docs Delta](#docs-delta) AC-04). Muting a `severity_effective ≥ high` finding beyond the bounded window declared by the safety floor. |
| **Confirmations** | Raising `critical` (safety-critical). Acknowledging a finding at `severity_effective ≥ high` (safety-critical); the confirmation surfaces the `author_ref`, the `acknowledged_by_role` and scope, and whether the fallback rule was used. Dismissing a human finding whose `severity_effective ≥ high` (safety-critical). Accepting an AI-proposed merge of two human findings on the same field and hazard (cross-scope; see [Duplicate detection](#duplicate-detection)). Overriding a machine finding's `severity_effective` via a paired human finding on the same hazard (cross-scope, sets `frozen`). Raising `low` or `medium` commits optimistically with a 5-second undo. |
| **Soft warnings** | Human finding raised on a field with an open finding on the same `hazard_ref` inside the last 72 hours ("a similar finding already exists, merge?"; see [Duplicate detection](#duplicate-detection)). `asserted_severity` two or more bands above the current signal-layer state ("signal does not corroborate; evidence will be weighed at verification"). Human finding raised with `hazard_ref = unclassified` ("no rule card matched; this finding will not benefit from `activity_bindings` and will not feed `farm_history` until corroborated"). Finding raised at `high` or `critical` where no other in-scope `agronomist` has been active in the preceding 24 hours ("no other in-scope agronomist has been active in the last 24 hours; acknowledgement is available to the in-scope `estate_manager` on the fallback path and the escalation timer is running"). |
| **Rate and scope limits** | Bulk human-finding raise capped per actor per hour (org-configurable). Per-actor per-role rolling window caps on `high` and `critical` raises (org-configurable). Since delivery is not gated at `critical`, these caps are the **primary** defence against a manufactured serious alert, not a supporting one. No hard cap on read paths. |
| **Audit** | Every finding write logs actor, source (`ui` \| `api` \| `integration` \| `agent` \| `system`), `provenance`, `field_ref`, `crop_cycle_ref`, `hazard_ref`, `rulecard_ref` and `rulecard_version` if machine, `author_ref` and `author_role` if human, `asserted_severity` and `severity_effective`, `state` before and after, `promoted_by` and `promoted_by_role` and `promoted_at` and `severity_before_promotion` if promoted, `acknowledged_by` and `acknowledged_by_role` and `acknowledged_at` if applicable, whether the acknowledgement fallback was used, `delivery_policy_at_creation` for human findings, `corroboration_ref` if `resolved`, `expiry_reason` if applicable, and evidence-ref hashes. Every state transition writes one row, and a promotion writes its own row even though it is not a state transition. Rows are append-only per the [Audit Envelope](/snippets/audit-envelope). |
| **Escalation** | A human finding at `severity_effective = critical` unacknowledged for more than 2 hours escalates to `estate_manager` and copies `org_admin`. A human finding at `severity_effective = high` unacknowledged for 4 hours escalates to the in-scope `agronomist` pool. **The 4-hour figure is the safety floor's `high` mute bound; automatic delivery under `hold_until_acknowledged` and this escalation coincide because both key off that bound, and if the floor's `high` bound moved, both would move with it.** A finding transitioning to `frozen` via `raise_contradiction` between a human and a machine finding on the same hazard escalates to `agronomist` ("agronomy review") per [Role Model](/snippets/role-model). Three consecutive human findings refused by input validation from the same actor in 24 hours escalate to `estate_manager`. |
### Who may raise, per role
Roles resolve against [Role Model](/snippets/role-model). No new roles are introduced. The `regional` row reflects the "read-only for operations, not for observations" rule described below.
| Functional role | `low` / `medium` | `high` | `critical` | May acknowledge |
| --------------------------- | :-------------------: | :-------------------: | :-------------------: | :------------------------------------------------------------------------: |
| `scout` | ✓ | — | — | — |
| `agronomist` | ✓ | ✓ | ✓ | ✓ (in-scope, not `author_ref`) |
| `approver` | ✓ | ✓ | ✓ | — |
| `estate_manager` | ✓ | ✓ | ✓ | ✓ (in-scope, fallback only, per [Guardrails → Preconditions](#guardrails)) |
| `estate_admin` | — | — | — | — |
| `regional` (agency officer) | ✓ | — | — | — |
| `org_admin` | — | — | — | — |
| `on_call` (overlay) | inherits primary role | inherits primary role | inherits primary role | inherits primary role |
| `viewer` (org role) | — | — | — | — |
**Every human finding enters `active` on raise, regardless of band or role.** Acknowledgement is a property recorded on the finding, not a gate in front of it; who may record it is the "May acknowledge" column above and the rules in [Acknowledgement](#severity-and-the-safety-floor). Whether delivery holds for `high` findings until acknowledgement lands is the organisation-level [Delivery policy](#delivery-policy), bounded by the safety floor.
**Scout ceiling is `medium`.** A scout who believes what they are seeing warrants `high` or `critical` raises the finding at their ceiling and requests promotion; an in-scope `agronomist` promotes in one action.
**Promotion reuses the existing mechanism.** It is the `promote_severity` effect already defined in [Risk Model → activity bindings](/concepts/risk-model#activity-bindings) — one band up — not a parallel path invented here. What the human case adds is an actor: every existing use of `promote_severity` fires from `system` (for example `task.overdue` per [Field Scouting](/guides/field-scouting)), so the effect never needed to record who applied it.
Promotion writes an append row, never a mutation: `promoted_by`, `promoted_by_role`, `promoted_at`, and `severity_before_promotion`. **`author_ref` does not change.** The scout remains the author of the observation; the agronomist is recorded as the promoter. A promoted finding therefore shows both the band its author asserted and the band the platform now acts on, and the raising table is not circumvented — a scout still cannot assert `high`, and an agronomist taking a finding to `high` is on the record by name for having done so.
**Read-only means read-only for operations, not for observations.** The `regional` role (typically an agency officer per the [Role Model](/snippets/role-model)) cannot assign scout tasks, approve VRA maps, or export verification bundles. It can raise a human finding at `low` or `medium`, because recording what was seen on-site is an observation, not an operation. Raising `high` or `critical` is refused for `regional`; that band is reserved for actors who can also act on it.
## Downstream behaviour
This is what Layer 2 consumers do when they read a `finding` and its `provenance`.
### Activity & Alerts
A human finding lands in the [Activity & Alerts](/guides/activity-and-alerts) feed as a row of its own, marked with the provenance chip described in [Disclosure](#disclosure). Notification routing follows `severity_effective` and the recipient's [Notification Preferences](/guides/notification-preferences). Delivery timing follows the organisation's [Delivery policy](#delivery-policy): under `immediate`, every band delivers on the routing its `severity_effective` earns; under `hold_until_acknowledged`, `high` findings hold until acknowledged or until the 4-hour safety-floor mute bound elapses, whichever comes first, and every other band delivers immediately. `critical` is never held.
An unacknowledged review queue is a filter on active findings where `acknowledged_by` is null, not a state the findings live in.
The current alert-vs-notification taxonomy in [Activity & Alerts](/guides/activity-and-alerts) splits the feed by source: alerts come from data, notifications come from humans. A human-raised field-level finding is field-critical like an alert and human-sourced like a notification. It sits between the two categories. See [Docs Delta AC-05](#docs-delta).
### Activity bindings
`activity_bindings` in [Risk Model](/concepts/risk-model#activity-bindings) fire on events, not on entities. A human finding emits events on the same contract:
| Event | Fires when | Effect on paired machine finding |
| --------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `finding.human_raised` | Human finding enters `active`. | If a machine finding on the same `hazard_ref` and `field_ref` is `dormant`, promote to `active`. If already `active` and `severity` disagrees by two or more bands, `raise_contradiction` and freeze both until agronomy review. Human findings enter `active` on raise regardless of band, so `raise_contradiction` fires from the moment the human finding exists; the per-role raising table and the per-actor rolling caps in [Guardrails → Rate and scope limits](#guardrails) are what stop this event from being weaponised. |
| `finding.human_resolved` | Human `active → resolved`. Corroboration recorded on `corroboration_ref`. | If a machine finding on the same hazard is `active`, do not auto-reset; recompute from signals per the existing `map.applied` pattern only if evidence includes a `map.applied` receipt. |
| `finding.human_dismissed` | Human `active → dismissed`. | No effect on machine findings on the same hazard. |
| `finding.expired` | `active → expired` on window elapse. | Emit into the feed with disclosure per [Expiry](#expiry); no auto-effect on paired machine findings. |
| `finding.closed_with_cycle` | any open state → `closed_with_cycle` on `season.closed`. | Terminal; no downstream effect. |
A human finding does not auto-suppress a paired machine finding. The [Risk Model](/concepts/risk-model#activity-bindings) already treats the ground-truth vs signal-layer disagreement as `raise_contradiction`, not as override. Amendment C preserves that discipline.
### Duplicate detection
When a human finding is drafted on a field and hazard where an open finding of either provenance already exists, the platform proposes a merge rather than committing a second row silently. The proposal is a **Task** artifact per the [Semai Advisor overview](/guides/semai-advisor/overview) tier-1 knowledge tier: AI-proposed, human-confirmed, RBAC-gated.
| Actor | May accept the merge proposal |
| ---------------- | :--------------------------------------------------: |
| `scout` | — (may add evidence to the existing finding instead) |
| `agronomist` | ✓ |
| `estate_manager` | ✓ |
| `estate_admin` | ✓ |
The proposal is a soft warning under [Guardrails](#guardrails), not a refusal. If the author declines the merge, the second finding commits as a distinct row and both remain visible; the [Aggregation Model](/concepts/aggregation-model) hazard count carries both. Silent auto-merge is refused: two field observations are never collapsed without an accountable click.
### Repeated hazard labels become Proposals
When the same `hazard_ref = unclassified` label pattern appears on human findings across multiple fields, the advisor files a **Proposal** artifact into the human review queue per the tier-2 propose-value path in [Semai Advisor overview](/guides/semai-advisor/overview). The proposal names the pattern, the fields and observations that produced it, and the closest existing rule cards. Approval creates a new rule card via the tier-4 schema-change path; rejection dismisses the pattern and records the rejection reason for future retrieval.
This turns the human channel into a route by which the knowledge base learns what it is missing. It does not let a repeated observation become authoritative on its own; the tier-2 review gate remains.
### Field Scouting
A human finding may spawn a [scout task](/guides/field-scouting) exactly the way a machine finding does. The task's AI brief is drawn from `hazard_ref` if it points to a literature page; if `hazard_ref = unclassified`, the brief falls back to Level 2 ("downgrade artifact") per [Failure Modes](/guides/semai-advisor/failure-modes) and the task is drafted with a free-text objective and no rule-card-derived checklist.
The [Field Scouting refusal](/guides/field-scouting#guardrails) on suppressing a `severity ≥ high` task must widen from "originates from a severity ≥ high rule card" to "originates from a `severity_effective ≥ high` finding, whatever its origin". As currently written, human high findings would be suppressible while machine ones are not; see [Docs Delta AC-04](#docs-delta).
### VRA Maps
A human finding may motivate a [VRA map](/guides/prescription-maps) but cannot pre-fill agronomic rates. The map draft opens with the finding attached as evidence and the `hazard_ref` as the target; rates are authored, not inferred. This preserves the existing [Guardrails on prescription rates](/guides/prescription-maps#guardrails).
### Verification
A human finding is an eligible source event for a [Verification](/guides/verification) bundle. The [Verification Model](/concepts/verification-model#source-events) requires `event_id`, `event_type`, `field_id`, `geometry`, `occurred_at`, `logged_at`, `actor`, and `payload`; a human finding maps directly:
| Verification source-event field | Human finding source |
| ------------------------------- | ------------------------------------------------------------- |
| `event_id` | `id` |
| `event_type` | `finding.human_raised` |
| `field_id` and `geometry` | `field_ref` and its GeoJSON |
| `occurred_at` | `observed_at` |
| `logged_at` | `logged_at` |
| `actor` | `author_ref` |
| `payload` | `{ hazard_ref, asserted_severity, rationale, evidence_refs }` |
The cross-check strength grade for a human finding is bounded by the corroborating satellite pass. A human finding with no corroborating imagery is submissible at **weak** grade with the flag surfaced; the [Verification Model](/concepts/verification-model) already handles this case for cloud-blocked passes and applies identically here. This is deliberate: the hazards a human finding is most useful for (panel dryness, ion-species salinity, phosphorus deficiency) are precisely the ones where the satellite is a weak cross-check.
### Aggregation
[Aggregation Model](/concepts/aggregation-model#rollup-categories) rollups count findings by category. Amendment C adds one axis: rollups split by `provenance` so estate, regional, and national dashboards can show "12 fields at HIGH blast risk (10 machine, 2 human)". No new metric is invented; the existing hazard-count category simply carries a provenance breakdown. Area-weighted indices and distribution buckets are unaffected because they read the signal layer, not findings.
### Feedback into farm\_history
`farm_history` is the top layer of the [Risk Model yield-impact resolver](/concepts/risk-model#yield-impact-layers) and, per Amendment A, the top layer of the band resolver. Letting the wrong human finding calibrate it silently poisons every future band and yield-impact resolution on that farm.
**Decision.** Corroborated `resolved` human findings feed `farm_history` on by default. Uncorroborated `resolved` findings stay in the record for the season but do not calibrate. Estate admins can widen the default to "all resolved" via one estate-level switch; the amendment does not enable that widening for any estate automatically.
The rule rests on three guards, all of which must be in place before `farm_history` feedback ships:
1. **Dismissed, expired, and `closed_with_cycle` findings never calibrate.** Only `resolved` findings with `corroboration_ref` set contribute under the default. The switch to "all resolved" removes the corroboration requirement but not the other terminal states.
2. **A finding contradicted by a later check is excluded retroactively.** The `raise_contradiction` mechanism already exists for machine findings; Amendment C extends it so a subsequent `scout.completed` or `map.applied` that contradicts a `resolved` finding causes `farm_history` calibration derived from that finding to be recomputed. This is stated as an Amendment C requirement on `farm_history`; the exact recompute cadence is a Risk Model implementation detail.
3. **Calibration provenance is inspectable.** The `band_source` field in Amendment A already explains which layer resolved a band. Amendment C requires that `band_source: farm_history` be traceable to the specific findings that built it, and that the trace surface both `provenance` and `corroboration_ref` for each contributor. The resolver already explains itself; this extends that.
**Why on-by-default, but only for corroborated.** Symmetry with machine findings (which feed `farm_history` today without an opt-in) is honest about the platform's stance that the human channel exists for hazards the satellite cannot see. Requiring corroboration for calibration keeps `farm_history` at observation-quality (what actually happened on this farm), not claim-quality (what someone said happened). The default is on because the *corroborated* finding is observation-quality; the safety comes from the corroboration gate, not from the default.
### Semai Advisor retrieval
The advisor retrieves `hazard_ref` literature identically for both provenances. When a human finding has `hazard_ref = unclassified`, the advisor operates at Level 1 ("Answer with caveat") per [Failure Modes](/guides/semai-advisor/failure-modes) and cannot issue a Task from that finding without the user attaching a rule card reference or authoring the task manually. The [safety floor](/guides/semai-advisor/overview#safety-floor) applies to the advisor's writes identically to any other caller; a human finding at `severity_effective = high` gates advisor artifacts the same way a machine finding at the same severity does.
## Disclosure
Every surface that shows a finding must be able to say where it came from. State the rule; do not design the UI.
* The provenance is a required disclosure. A row that hides `provenance` fails the honesty test the product already applies to weak verification grades and stale imagery banners.
* Machine findings display the rule card id and version they were computed from.
* Human findings display the author's identity (identity, not just role) and the `observed_at` timestamp.
* A human finding with `acknowledged_by` null must be visually distinct from an acknowledged one on every surface that shows it, including notification bodies, the Activity feed, and Verification bundle previews. Unacknowledged is a property, not a state; the finding is live.
* An acknowledged finding displays `acknowledged_by` (identity and role) and, when the fallback rule was used, that the acknowledgement was recorded by an `estate_manager` because no other in-scope `agronomist` had been active in the preceding 24 hours.
* A human finding displays `delivery_policy_at_creation` wherever it crosses an organisational boundary: verification bundles, aggregation rollups that mix organisations, and any effect-methodology dashboard that does the same. Inside a single organisation the policy is a property of the organisation and does not need to be shown on every row.
* A held `high` finding that delivered automatically at the 4-hour mute bound without acknowledgement displays that fact and the reason: "delivered on safety-floor bound, unacknowledged at 4 hours".
* A finding whose `severity_effective` differs from the signal-layer indicator on the same field displays both, per the existing `raise_contradiction` pattern in [analytics tabs](/guides/fields-workspace/analytics-tabs).
* A finding with `hazard_ref = unclassified` displays that literally; the platform must not invent a hazard label.
* An `expired` or `closed_with_cycle` finding displays its terminal reason: "Expired unactioned on 12 Jul · window: 72 hours at high severity" or "Closed with cycle on 30 Sep · Main Season 1 · 2026".
* A `resolved` human finding displays its corroboration status: corroborated (and by what event) or uncorroborated.
The rule is that provenance is disclosed, not that it is loud. Disclosure is a data contract on every consumer, not a specification of chip colour, placement, or copy. Those decisions belong to the surface owners.
## Seed
The Layer 4 seed already covers 12 fields across the four crops. To make both provenances reachable without inventing new fields, Amendment C adds these fixtures. Fixture ids follow the human-readable convention (`fnd_` prefix per [Field Data Model](/concepts/field-data-model)); no UUIDs.
The first fixture is the one that makes the argument. The rest exercise the corners.
| Fixture id | Field | Crop | Provenance | Purpose |
| ------------------------------------------ | ---------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fnd_seed_rubber_panel_dryness_01` | `field_ldg_perak_r3` | Rubber | human, `agronomist`, `high` | **The argument.** Panel dryness observed on Panel B over roughly a fifth of the tapped length. The satellite has not flagged it and is correct not to: the literature says panel dryness surfaces over one to three years and R3's readings are inside band. A machine-only platform sees nothing here for another year. |
| `fnd_seed_rice_blb_duplicate_02` | `field_muda_b1` | Rice | human, `scout`, `medium` | **The duplicate-detection prompt.** A human finding raised on a field with an open machine finding for the same hazard (`rice_blb`). Exercises the AI-proposed merge Task per [Duplicate detection](#duplicate-detection); the fixture leaves the merge unaccepted so both rows remain. |
| `fnd_seed_rice_blast_machine_03` | Rice field 1 | Rice | machine, `high` | Baseline `rulecard_firing` for blast at booting. Exercises `activity_bindings.scout.completed` and `map.applied` paths, and pairs with the human fixture below to exercise `raise_contradiction`. |
| `fnd_seed_rice_blast_paired_04` | Rice field 1 (same as above) | Rice | human, `agronomist`, `low` | Paired with fixture 03 at a two-band gap (machine `high` versus human `low`) to force `raise_contradiction` and freeze both. The engine reads blast at `high`; the agronomist walks the field and says it is not blast. Exercises the agronomy review escalation. |
| `fnd_seed_palm_ganoderma_ack_05` | Oil palm field 1 | Oil palm | human, `agronomist`, `critical` | Enters `active` on raise and delivers immediately because `critical` is never held. An in-scope peer `agronomist` records `acknowledged_by` afterwards. Exercises immediate delivery at `critical`, the acknowledgement audit fields, and the confirmation that acknowledging a finding at `severity_effective ≥ high` is safety-critical. |
| `fnd_seed_palm_expired_06` | Oil palm field 2 | Oil palm | human, `scout`, `medium` | Raised, left unactioned, transitions to `expired` after the 14-day window. Exercises the expiry disclosure and the audit row. |
| `fnd_seed_pine_forcing_corroborated_07` | Pineapple batch 1 | Pineapple | human, `agronomist`, `low` | Raised, resolved, corroborated by a subsequent `scout.completed`. Exercises `farm_history` feedback under the default (corroborated-only). |
| `fnd_seed_pine_forcing_uncorroborated_08` | Pineapple batch 2 | Pineapple | human, `agronomist`, `low` | Raised, resolved, no corroborating event. Stays in the record; does not feed `farm_history` under the default. Exercises the widened "all resolved" switch when toggled at the estate. |
| `fnd_seed_rubber_closed_with_cycle_09` | Rubber field 2 | Rubber | human, `scout`, `medium` | Raised late in the cycle, still `active` when the parent season closes. Transitions to `closed_with_cycle` with disclosure. |
| `fnd_seed_regional_observation_10` | Rice field 3 | Rice | human, `regional` (agency officer), `low` | Exercises the "read-only for operations, not for observations" rule. Raises at `low`; refused at `high` and `critical`. |
| `fnd_seed_palm_ganoderma_ack_fallback_05b` | Oil palm field 3 | Oil palm | human, `agronomist`, `critical` (acknowledged by `estate_manager`, fallback path, single-agronomist estate) | Estate has one in-scope `agronomist` and that agronomist is the `author_ref`; no other in-scope `agronomist` has been active in the preceding 24 hours, so the in-scope `estate_manager` records the acknowledgement. Exercises the fallback rule per [Guardrails → Preconditions](#guardrails), including that the author is excluded from the fallback test (single-agronomist estates always take the fallback path when their agronomist raises), the `acknowledged_by_role = estate_manager` audit, and the disclosure that a manager's acknowledgement, not an agronomist's, is on the record. |
| `fnd_seed_rice_blast_hold_bound_11` | Rice field 2 | Rice | human, `agronomist`, `high`; organisation set to `hold_until_acknowledged` | Raised on an organisation whose `delivery_policy_at_creation = hold_until_acknowledged`. Delivery holds for 4 hours, then fires automatically at the safety-floor mute bound with `acknowledged_by` still null. Displays "delivered on safety-floor bound, unacknowledged at 4 hours" per [Disclosure](#disclosure). This is the fixture that proves the hold is bounded by the safety floor rather than by a person, and that the automatic delivery and the 4-hour escalation to the agronomist pool coincide by design. |
Coverage properties this fixture set exercises against the existing 12-field seed:
* Fixture 01 demonstrates the point of the amendment: a hazard the satellite is correct not to flag.
* Every raising role in the table appears at least once.
* Acknowledgement on the normal path fires via fixture 05 (in-scope `agronomist`); the fallback fires via fixture 05b (in-scope `estate_manager` on a single-agronomist estate, exercising the author-exclusion clause of the fallback rule).
* The delivery-policy hold and its safety-floor bound fire via fixture 11: a `high` finding on an organisation set to `hold_until_acknowledged`, held then auto-delivered at 4 hours without acknowledgement.
* `raise_contradiction` fires between fixtures 03 and 04.
* `expired` fires via fixture 06; `closed_with_cycle` fires via fixture 09.
* Corroborated (07) and uncorroborated (08) `resolved` findings both exist, exercising both `farm_history` behaviours.
* The `regional` observation lane fires via fixture 10.
* One human finding (fixture 01) is bundled through [Verification](/guides/verification) end-to-end at **weak** grade so the disclosure of the weak flag is exercised.
No fixture uses `hazard_ref = unclassified`. That path is exercised at runtime, not seeded, because seeding it would require inventing a hazard label the literature does not have.
## Docs Delta
Amendment C is silent, ambiguous, or contradictory against the current docs in the places below. Each item is enumerated, not resolved silently.
| Id | Where | Gap |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **AC-01** | [Risk Model](/concepts/risk-model) uses `rulecard_firing` as the finding shape and does not name provenance. | Rename `rulecard_firing` to `finding` with `provenance = machine`, or keep `rulecard_firing` as a view over `finding`. This page assumes the rename; the risk-model page has not been updated. |
| **AC-02** | [Semai Advisor Safety floor](/guides/semai-advisor/overview#safety-floor) states mute bounds by `severity` but does not name provenance. | Amendment C reads the floor as provenance-agnostic on `severity_effective`. The safety-floor page does not state this explicitly. |
| **AC-03** | [Field Data Model](/concepts/field-data-model) enumerates entities (Organization, Estate, Field, Block, Zone, Season, Observation) but does not enumerate `finding` or `rulecard_firing`. | The Layer 1 entity table needs a `finding` row before Amendment C ships. |
| **AC-04** | [Field Scouting Guardrails](/guides/field-scouting#guardrails) refuses "suppressing a task that originates from a severity ≥ high **rule card**". | Manual findings fall outside the refusal as written, so human high findings would be suppressible while machine ones are not. Widen to "whatever its origin" (`severity_effective ≥ high` on the source finding, regardless of `provenance`). Amendment C's Guardrails table already uses the widened wording. |
| **AC-05** | [Activity & Alerts](/guides/activity-and-alerts) splits the feed by source: alerts from data, notifications from humans. | A human-raised field-level finding is field-critical like an alert and human-sourced like a notification. The taxonomy has no slot for it. Either promote human findings to a third category, or explicitly route them into the alert lane with the provenance chip disclosing the source. |
| **AC-06** | [Verification Model](/concepts/verification-model#source-events) lists eligible `event_type` values (`scout.completed`, `map.applied`, `alert.flood`, `harvest.declared`, `yield.snapshot`). `finding.human_raised` is not listed. | Add `finding.human_raised` to the source-event enum. Routing through `scout.completed` when authored by a `scout` was considered and rejected: it would erase the author-role distinction that `regional` (agency officer) fixtures depend on. |
| **AC-07** | [Aggregation Model](/concepts/aggregation-model#rollup-categories) does not split hazard counts by provenance. | The rollup category for hazard counts needs one extra breakdown axis. The aggregation semantics do not change; the presentation does. |
| **AC-08** | [Role Model](/snippets/role-model) does not name a raising-authority table for findings. | This page adds one that resolves entirely against the eight canonical functional roles, including the "read-only for operations, not for observations" carve-out for `regional`. No new role is introduced. |
| **AC-09** | [Notification Preferences](/guides/notification-preferences) does not describe the organisation-level delivery policy or delivery timing for `expired` findings. | Amendment C states that human findings deliver per the organisation's `delivery_policy_at_creation`, bounded by the safety floor: `immediate` delivers every band on the routing its `severity_effective` earns; `hold_until_acknowledged` holds `high` findings for at most 4 hours and never holds `critical`. `expired` findings emit into the feed with disclosure but do not re-notify. The preferences page needs to reflect both rules. |
| **AC-10** | [Failure Modes](/guides/semai-advisor/failure-modes) does not cover advisor behaviour when `hazard_ref = unclassified`. | Amendment C names Level 1 ("Answer with caveat") as the applicable degradation. The failure-modes catalog should add the entry. |
| **AC-11** | [Audit Envelope](/snippets/audit-envelope) does not list `provenance`, `acknowledged_by`, `acknowledged_by_role`, `acknowledged_at`, `promoted_by`, `promoted_by_role`, `promoted_at`, `severity_before_promotion`, `delivery_policy_at_creation`, `corroboration_ref`, or `expiry_reason`. | The envelope is extensible per its "Per-module extension pattern" clause; this page names the extension fields but the envelope page has not been updated. |
| **AC-12** | [Fields Workspace](/guides/fields-workspace/overview) exposes a `New observation` FAB and a `New note` action. | `New note` is deliberately inert; `New observation` [feeds `scout.completed` semantics](/guides/fields-workspace/analytics-tabs) but the FAB can raise one with no scout task open to complete. What that event means with no task is unstated. Amendment C's human finding is the closest general model; the FAB should raise a human finding when no task is open, and the workspace docs need to say so. |
| **AC-13** | Layer 1 §3 ID conventions are referenced by the source brief but not present verbatim in the mounted docs. | This page follows the observed convention (`fld_`, `blk_`, `ssn_`, `obs_`, `evt_`, `VRF-`) and uses `fnd_`. If Layer 1 §3 specifies a different pattern, the prefix is negotiable; the ban on UUIDs is not. |
| **AC-14** | [Severity and the safety floor](#severity-and-the-safety-floor) resolves the raise-time question via a per-role raising table plus an organisation-level delivery policy. An earlier draft used a `pending_review` state gated by peer co-signature; that mechanism was withdrawn before ship. | Downstream briefs and any implementation notes should refer to the acknowledgement model and the two delivery-policy settings (`immediate`, `hold_until_acknowledged`) directly. Where a downstream page (client SDK docs, on-call handbook) references `pending_review`, co-sign, or the option comparison, it needs updating. |
| **AC-15** | [Role Model](/snippets/role-model) does not name the acknowledgement fallback: in-scope `estate_manager` when no other in-scope `agronomist` has been active in the preceding 24 hours. | The role-model page should record the fallback so the entitlement rules for acknowledgement are complete in one place, including that the `author_ref` is excluded from the test on the same reasoning as the not-`author_ref` rule (single-agronomist estates always take the fallback). Amendment C's [Guardrails → Preconditions](#guardrails) row is the current source. |
| **AC-16** | [Activity & Alerts](/guides/activity-and-alerts) does not distinguish an agronomist acknowledgement from an `estate_manager` fallback acknowledgement in the finding presentation, and does not display `delivery_policy_at_creation` on findings that cross organisational boundaries. | Every surface that shows the acknowledgement must disclose `acknowledged_by_role` and whether the fallback rule was used. Every surface that shows a finding across an organisational boundary must show `delivery_policy_at_creation`. A manager's acknowledgement is not an agronomist's; two findings from different policies are not one number. |
| **AC-17** | [Risk Model activity bindings](/concepts/risk-model#activity-bindings) does not gate `raise_contradiction` in a way that stops a low-role actor from using a manufactured counter-finding to mute a live machine alert. | Human findings enter `active` on raise regardless of band, so `raise_contradiction` fires from creation. The defence against weaponisation is the per-role raising table in this page plus the per-actor rolling caps on `high` and `critical` raises (see [Guardrails → Rate and scope limits](#guardrails)), not a state gate. The risk-model page should surface both preconditions so a reader of the bindings contract does not have to reconstruct them here. |
| **AC-18** | [Semai Advisor Safety floor](/guides/semai-advisor/overview#safety-floor) and this page both use severity-scaled windows, but the expiry-clock start condition is stated only here. | The expiry clock starts when the finding enters `active`, which for a human finding is the moment of raise. Acknowledgement does not gate, pause, or restart the clock. The safety-floor page should point at this rule so a reader following the floor's mute bounds finds the expiry rule immediately. |
| **AC-19** | [Aggregation Model](/concepts/aggregation-model) rollups do not carry `delivery_policy_at_creation`. | Amendment C requires disclosure of the delivery policy on every rollup that mixes findings from more than one organisation. Aggregating findings that passed different governance bars and presenting them as one number is the same class of error the aggregation-model page already warns against; adding the axis is additive to the existing category structure. |
| **AC-20** | [Effect Methodology](/concepts/effect-methodology) dashboards that mix findings from more than one organisation do not currently disclose `delivery_policy_at_creation`. | Same rule as AC-19 for the effect-methodology surface: disclose the delivery policy in force on the underlying findings, so `did-it-happen` and `did-it-help` claims are not silently averaged across governance bars. |
## Open Questions
These are decisions the literature did not resolve. Amendment C enumerates them; it does not answer them.
1. **Two-hour `critical` escalation timer.** Amendment C escalates an unacknowledged `severity_effective = critical` human finding to `estate_manager` (copying `org_admin`) at 2 hours. Delivery is not gated at `critical` under either policy, so this is an acknowledgement-of-record timer rather than a delivery backstop; the audience has already been paged. The number came from the page rather than from observed on-call practice. Before the module ships, the timer should be validated against how the on-call rotation actually behaves: how quickly a peer `agronomist` is typically reachable on a `critical` raise, and whether 2 hours is too long, correct, or too short. Do not change it without that evidence.
2. **Delivery policy granularity.** Amendment C sets the delivery policy per organisation. Estates within one agency may have different on-call maturity, and per-estate configurability is a defensible extension. Amendment C ships at organisation granularity; per-estate is deferred to a companion amendment.
3. **Expiry disclosure for unacknowledged findings.** An unacknowledged finding that expires on its severity-scaled window is currently treated the same as any other unactioned expiry. Whether the expiry disclosure should carry the lack of acknowledgement forward ("expired unacknowledged" rather than "expired unactioned"), or whether the two are the same event on the record, is undecided.
4. **Inline vs. export disclosure of delivery policy for `regional` readers.** A `regional` officer reading across organisations sees findings that passed different delivery policies. Amendment C requires disclosure at organisational boundaries but does not decide whether the policy chip is inline on every finding in a cross-organisation view or only on the exported bundle. Inline is more honest and noisier; export-only is quieter and easier to overlook.
5. **Expiry as a yield-model input.** Amendment C lands expiry as a lifecycle state with severity-scaled windows and disclosure. It does *not* wire expiry into `yield_impact.resolved`. A companion amendment should decide the weight function (linear in days-overdue? capped at the mitigation window?), the composition rule with the existing `yield_impact.resolved`, and the machine-finding parallel (does `task.overdue` on a machine finding also cost yield?). Until then, expiry is visible on every surface but does not move the yield forecast.
6. **`farm_history` default widening cadence.** Corroborated-only is the default. The one-switch widening to "all resolved" is per-estate; whether the platform should nudge estates toward the widened setting after N seasons of clean corroboration history is undecided.
7. **Human override of a machine finding.** When a human finding at `severity_effective = high` is paired with an `active` machine finding at `low` on the same hazard, Amendment C freezes both and routes to agronomy review. Should the human finding's severity dominate until review completes, or should both stay visible at their asserted values? The current draft picks freeze plus both visible; a "human dominates pending review" reading is defensible for time-critical hazards.
8. **Retroactive human findings.** May a human finding declare `observed_at` older than 72 hours? The [Verification Model](/concepts/verification-model#source-events) late-log rule applies to source events (72 hours), and this page inherits that bound implicitly. Whether an older `observed_at` is refused, accepted with a late-log flag, or accepted only inside the current `crop_cycle` is undecided.
9. **Bulk import of human findings.** Estate handovers, agency inspections, and cooperative onboarding all produce batches of retrospective observations. The rate limit above applies to interactive raises. A separate bulk-import path (with its own confirmations and stricter evidence requirements) is out of scope for Amendment C.
10. **Provenance for platform-authored corrections.** A `system` actor writing a correction row (per [Audit Envelope](/snippets/audit-envelope) rule 1) is neither `machine` nor `human`. The current draft treats corrections as append rows against the original finding, keeping the original `provenance`. Whether a third value (`system_correction`) is needed at the entity level is undecided.
## Related
* [Field Data Model](/concepts/field-data-model) — the entity hierarchy this page adds `finding` to.
* [Risk Model](/concepts/risk-model) — the `rulecard_firing` shape Amendment C generalises, the `activity_bindings` contract human findings emit into, and the `yield_impact` resolver `farm_history` feedback flows into.
* [Crop Cycle Models](/concepts/crop-cycle-models) — the cycle boundaries `crop_cycle_ref` resolves against and the `season.closed` event that drives `closed_with_cycle`.
* [Verification Model](/concepts/verification-model) — the source-event schema human findings map to.
* [Aggregation Model](/concepts/aggregation-model) — the hazard-count rollup that gains a provenance axis and the reproducibility requirement expiry disclosure serves.
* [Guardrails Template](/snippets/guardrails-template) — the eight categories this page fills.
* [Role Model](/snippets/role-model) — the raising and acknowledgement authority table, including the `regional` observation lane and the `estate_manager` fallback.
* [Effect Methodology](/concepts/effect-methodology) — the outcome-attribution track that inherits `delivery_policy_at_creation` disclosure at organisational boundaries.
* [Audit Envelope](/snippets/audit-envelope) — the envelope every finding write extends.
* [Semai Advisor Overview](/guides/semai-advisor/overview) — the safety floor `severity_effective` resolves against, the tier-2 Proposal path for repeated hazard labels, and the Task-artifact path for AI-proposed merges.
* [Failure Modes](/guides/semai-advisor/failure-modes) — the degradation levels the advisor applies to `hazard_ref = unclassified` findings.