BVER Primitive Contracts

This document defines the contract model for the six BVER operation primitives:

• Interpreter
• Resolver
• Generator
• Validator
• Simulator
• Evaluator

These primitives are the semantic building blocks of BVER. They are not the same thing as the current repo's OperationSpec layer. OperationSpec is a transport-facing exposure surface for REST, MCP, and internal calls. A BVER primitive is the higher-level engineering definition that should later project into one or more OperationSpecs, jobs, or workflows.

This document is intentionally normative. It describes the target contract that the runtime should implement, while staying compatible with the existing bver-runtime substrate already present in this repo.

Design Goals

• Keep primitive definitions domain-agnostic at the contract level.
• Make every primitive traceable, inspectable, and safe to expose through machine-facing interfaces.
• Support both synchronous invocation and long-running execution.
• Preserve evidence, provenance, and ambiguity instead of flattening everything into one opaque result.
• Keep mutation explicit rather than implicit.

Contract Layers

Every primitive should be defined across five contract layers.

1. Definition Contract

The definition contract describes what the primitive is.

Suggested PrimitiveSpec fields:

Field	Meaning
name	Stable identifier such as electrical.symbols.interpret or site.routing.evaluate.
primitive_kind	One of interpreter, resolver, generator, validator, simulator, evaluator.
version	Semantic version for the definition contract, not just the transport endpoint.
description	Short, stable description of what the primitive does.
domain_scope	Domain pack or semantic scope such as electrical, structural, or generic.
input_schema	Structured schema for invocation payload.
output_schema	Structured schema for the primitive-specific payload.
mutates_state	Whether invocation can change persistent or canonical runtime state.
execution_mode	sync, async, or either.
determinism	deterministic, bounded_nondeterministic, or agent_guided.
requires_evidence	Whether the primitive requires evidence references in addition to normal inputs.
supports_partial	Whether partial results are valid.
tags	Discoverability tags.
action / resource	Optional authorization metadata when exposed through the runtime.

2. Invocation Contract

The invocation contract describes what a caller sends.

Suggested PrimitiveRequest fields:

Field	Meaning
request_id	Correlation identifier for tracing and replay.
primitive_name	Fully qualified primitive identifier.
subject_refs	References to the primary artifacts, entities, graphs, or models being acted on.
input	Primitive-specific payload.
evidence_refs	Optional references to supporting evidence, observations, or prior outputs.
state_ref	Optional pointer to a graph, workflow, scene, document, or runtime state object.
constraints	Hard limits such as schema, safety, scope, or domain policy constraints.
budget	Optional compute, latency, token, or cost budget.
idempotency_key	Required for mutating or asynchronous invocations.
metadata	Caller metadata such as origin, correlation, and audit hints.

3. Runtime Context Contract

The runtime context is not user payload. It is supplied by the runtime.

Suggested PrimitiveContext fields:

Field	Meaning
runtime	Access to runtime services already present in bver-runtime.
principal	Authenticated subject, if any.
policy	Policy handle used for enforcement.
trace	Trace/span hooks for observability.
refs	Reference resolution helpers.
jobs	Job queue and job status helpers for async execution.
events	Event publish helpers.
cache	Cache access for safe reuse of pure outputs.
state_loader	Helper for resolving graph/state/evidence references.
capabilities	Optional capability registry for runtime-dependent features.

4. Result Contract

Every primitive should return a common top-level envelope, even when its payload differs.

Suggested PrimitiveResult fields:

Field	Meaning
request_id	Echo of the invocation id.
primitive_name	Primitive that produced the result.
primitive_kind	Primitive type.
status	success, partial, rejected, or failed.
summary	Short human-readable summary.
output	Primitive-specific payload matching output_schema.
confidence	Optional confidence block when probabilistic or ambiguous reasoning exists.
evidence_refs	Evidence produced or consumed by the primitive.
artifact_refs	References to created or inspected artifacts.
state_effects	Explicit description of mutations, patches, or proposed changes.
diagnostics	Structured warnings, issues, and repair hints.
followups	Suggested next primitive calls or orchestration steps.
metrics	Timing, cost, or scale metadata.

5. Failure Contract

Failures should also be structured rather than ad hoc.

Suggested PrimitiveError fields:

Field	Meaning
code	Stable machine-readable error identifier.
message	Human-readable description.
phase	Where failure occurred such as input_validation, resolution, execution, or projection.
retryable	Whether the caller may safely retry.
details	Structured details for debugging or recovery.
related_refs	Relevant artifact, evidence, or state references.

Shared Rules For All Primitives

1. Primitive definitions are the source of truth. REST, MCP, and internal automation should be generated or projected from them rather than redefined by hand.
2. All important outputs must be structured. Human-readable summaries are helpful, but they cannot be the only result.
3. If a primitive can mutate state, that fact must be declared in PrimitiveSpec.mutates_state and enforced at invocation time.
4. Partial and ambiguous outputs are valid if they are explicit. BVER should preserve uncertainty rather than hiding it.
5. Long-running invocations should map to jobs or workflows instead of blocking synchronous transports.
6. Primitive results should carry enough provenance to support replay, audit, and downstream evaluation.

Primitive-Specific Contracts

Interpreter

Purpose: convert unstructured or semi-structured input into structured observations, candidates, or extracted facts.

Input Contract

• One or more source artifacts such as drawings, scenes, text, tables, sensor feeds, or external documents.
• Optional scope selectors such as regions, layers, pages, or segments.
• Optional domain profile to constrain extraction behavior.
• Optional prior evidence or hypotheses to refine interpretation.

Output Contract

• Structured observations or candidate objects.
• Evidence links back to the source material.
• Confidence and ambiguity markers.
• Optional extracted attributes or relations.

Rules

• An interpreter does not claim canonical truth on its own.
• It should preserve source locality and evidence linkage.
• It may be nondeterministic, but the output shape must remain stable.

Resolver

Purpose: map candidates, aliases, or references into canonical identities, schemas, ontologies, or object bindings.

Input Contract

• Candidate entities, observations, or symbolic references.
• Target resolution space such as an ontology, registry, schema set, or persistent catalog.
• Matching constraints and tie-break policy.

Output Contract

• Canonical matches or bindings.
• Match confidence or score.
• Explicit unresolved or conflicting items.
• Optional normalized forms for downstream use.

Rules

• A resolver may narrow ambiguity, but it must not silently invent unsupported candidates.
• If multiple canonical resolutions remain viable, the ambiguity must be returned explicitly.
• Resolver output should be stable enough to use in later graph/state updates.

Generator

Purpose: produce candidate artifacts, configurations, structures, transforms, or patches from intent plus context.

Input Contract

• Intent, goal, or request payload.
• Seed state, existing artifact refs, or domain context as needed.
• Hard constraints such as schema, safety, standards, inventory, or topology constraints.
• Optional templates or prior artifacts.

Output Contract

• One or more generated candidates, artifacts, or patches.
• Declared assumptions and unresolved dependencies.
• Optional follow-up actions for validation or simulation.

Rules

• A generator should default to proposal mode, not silent commit mode.
• If generation writes to persistent state, that must be explicit and mutation-gated.
• Generated outputs should be suitable for later validation, simulation, or evaluation.

Validator

Purpose: check artifacts, states, or transitions against rules, invariants, policies, or standards.

Input Contract

• Target artifact, state, graph, or transition.
• Validation ruleset or domain profile.
• Validation scope and severity policy.

Output Contract

• Result status such as pass, fail, or warn.
• Structured issues with severity and location.
• Optional repair hints or references to violated rules.
• Optional derived metrics relevant to compliance.

Rules

• Validators do not silently mutate the validated object.
• Hard failures must be distinct from advisory findings.
• A validator may enrich diagnostics, but not rewrite the subject under validation.

Simulator

Purpose: model system behavior over time, conditions, or coupled interactions.

Input Contract

• A system model or graph ready for simulation.
• Initial conditions, scenarios, loads, or environment assumptions.
• Time horizon, step policy, fidelity, or solver configuration.

Output Contract

• State traces, measurements, or derived behavioral facts.
• Constraint violations or instability indicators.
• Scenario-level diagnostics and metrics.
• Optional outputs consumable by validators or evaluators.

Rules

• Simulators should be side-effect free by default.
• Long-running simulation should run as an asynchronous task.
• Simulator outputs must clearly separate measured outputs from assumptions.

Evaluator

Purpose: score, compare, and rank alternatives against objectives, tradeoffs, or decision criteria.

Input Contract

• A candidate set to compare.
• An objective definition, weighting profile, or decision rubric.
• Optional constraint screen or threshold policy.

Output Contract

• Ranked candidates.
• Per-candidate scores and tradeoff notes.
• Rejection reasons or gating failures.
• Optional recommendation object for orchestration or user review.

Rules

• Evaluators compare; they do not generate new candidates as a side effect.
• If evaluation depends on validation or simulation facts, those dependencies should be explicit.
• An evaluator should return the scoring basis, not only the winner.

Expected Primitive Chain

Not every workflow uses all six primitives, but the intended execution pattern is roughly:

Interpreter -> Resolver -> Generator -> Validator -> Simulator -> Evaluator

This is a logical chain, not a hardcoded pipeline. Real workflows may loop, branch, or skip primitives.

Mapping To The Current Runtime Substrate

The current repo already provides a useful exposure and control layer through OperationSpec, OperationBroker, REST, MCP, jobs, and workflows. The intended projection is:

Primitive	Usual OperationKind projection	Notes
Interpreter	query or task	Use task when interpretation is expensive or multi-stage.
Resolver	query or task	Often synchronous, but large-batch resolution may become a task.
Generator	command or task	Proposal-only generation can be a command; heavy generation should be a task.
Validator	query or task	Small checks are queries; large standards checks may be tasks.
Simulator	task by default	Short simulations may expose a query surface, but async is the safer default.
Evaluator	query or task	Ranking small candidate sets is usually synchronous.

Important rule: this mapping is a projection, not the definition. BVER should not collapse the semantic distinction between primitives just because the current runtime exposes everything as generic operations.

Fit With The Current Repo

The current repository provides a promising substrate, but it is still earlier than the contract described here.

• bver.runtime.operations already separates transport exposure from execution, which is a good base for projecting primitive definitions later.
• OperationBroker already enforces mutation gating and policy checks, which should carry forward into primitive execution.
• workflows and refs are currently too thin to represent the richer orchestration, provenance, and canonical binding expected by these contracts.
• The existing placeholder modules for Redis, Celery, durable outbox behavior, dependency health, and several integrations suggest the runtime is still in the substrate-building phase rather than the primitive-definition phase.
• The earlier repository material in temp/ is useful as inspiration, especially around generators, validators, simulators, graph state, and interpretation workflows, but it is still exploratory and should not be treated as the final contract without cleanup.

Recommended Next Implementation Artifacts

To turn this document into code, the next concrete artifacts should be:

1. PrimitiveSpec, PrimitiveRequest, PrimitiveContext, PrimitiveResult, and PrimitiveError type definitions.
2. A primitive registry that can register and discover definitions by kind and domain.
3. A projection layer that emits one or more OperationSpecs from a primitive definition.
4. A first domain pack that proves the contract end to end with at least one primitive of each relevant kind.