Propose an operation in a model search

Validates an action without changing the project. In Guide and Enforce modes, returns findings with explanations and references. A proposal binds the action to the current state version. bg_research_apply() validates it again before writing.

Usage

bg_research_propose(project, action, actor, rationale)

Arguments

project

A bg_handle.

action

A named list with kind and the fields for that operation. See vignette("research-search") for every action.

actor

Named list with id and type (human or agent).

rationale

Why this action is proposed.

Value

A proposal with version, action, actor, rationale, allowed, and findings. A finding is the rule with its severity, plus failures when a predicate failed and candidate_ids for comparisons. Enforce holds an action only for blocking findings. A configure proposal also carries the resolved policy and its policy_digest; apply resolves the requested rules again, and a different digest makes the proposal stale. An action with node_id carries the engine's derivation: the binding of a candidate, or the result and provenance of derived evidence.

Details

create and revise accept an optional node_id, which binds the candidate to the execution that produced the node's current artifact (see bg_node_pad()). That execution must have recorded a P/A/D snapshot. A bound create may omit components, which then default to the snapshot without digests; a bound revise may omit them to keep the parent's. A revise without node_id is unbound: bindings are never inherited. A revision of a bound parent must change a snapshot digest or the description, so an unchanged clone of the same run is rejected.

evidence takes exactly one of result (asserted evidence) or node_id (evidence derived from a run, for a bound candidate). Derived evidence comes from a check that evaluated the bound fit's exact output or, failing that, from the bound fit's own executions. Its check may be omitted when exactly one summary kind matches; the most recent matching summary is recorded as result, with its provenance. sbc and compare nodes are not supported yet.

Bindings, provenance, P/A/D snapshots, digests, fingerprints, artifact references, job ids, and summary ids are engine-owned: an action that uses one of these names as an action field or as a field of a P/A/D component is rejected. Data nested deeper in a description or an asserted result is opaque and never read as provenance; only the engine's own binding and provenance records are authoritative. Derived evidence authenticates which artifacts an execution consumed and produced, but trusts what the executor reports, so hosts must control executor registration.