Core Objects
Stable public primitives used across Splendor runtime surfaces.
Core Objects Reference
Splendor's public object model is intentionally small and explicit. The same concepts appear in local runs, daemon requests, SDK callbacks, trace events, state commits, and replay output.
Stable primitives
| Primitive | Purpose |
|---|---|
| Tenant | Authority boundary for policy, quotas, data scope, and audit. |
| Agent | Autonomous runtime identity inside a tenant. |
| Run | One execution of an objective. |
| Tick | One cycle inside a run. |
| Percept | Structured observation delivered to policy. |
| Action | Proposed operation mediated by the gateway. |
| StateNode | Versioned state commit or explicit state reference. |
| TraceEvent | Append-only runtime event in a run trace stream. |
| Message | Typed agent-to-agent coordination object. |
| WorkOrder | Signed, scoped authority to start or resume a run. |
| Approval | Scoped governance evidence consumed by verifiers. |
| Policy / Constraint / Verifier / Adapter | Runtime interfaces for proposal, rule evaluation, enforcement, and execution. |
| Feedback / Reward | Evaluation signals recorded after outcomes. |
Identity rules
Do not overload IDs. Public schemas keep these identity concepts distinct:
fleet_id, node_id, instance_id, tenant_id, agent_id,
runtime_context_id, run_id, tick_id, action_id,
state_node_id, trace_event_id, message_id,
work_order_id, approval_id, artifact_idIdentity fields are not authority by themselves. Authority comes from scoped tenant policy, work orders, endpoint scopes, approvals, and gateway verification.
Percept
Percept captures a structured observation delivered to the policy.
Fields
schema(String): schema name or URI describing the payload.payload(serde_json::Value): structured observation data.provenance(PerceptProvenance): source metadata.timestamp(OffsetDateTime): capture timestamp.
PerceptProvenance fields:
source(String): emitter identifier (sensor/adapter/service).detail(Option<String>): optional detail or correlation key.
Action
Action represents a candidate operation submitted to the gateway.
Fields
name(String): action identifier understood by adapters.params(serde_json::Value): structured action parameters.side_effect_class(SideEffectClass): domain classification.required_permissions(Vec<String>): permission tokens.preconditions(Vec<String>): required predicates before execution.postconditions(Vec<String>): expected predicates after execution.
SideEffectClass variants:
ReadOnly,Filesystem,Network,External,Physical, or a custom class where documented.
QuotaUsage
QuotaUsage captures per-action usage for quota enforcement.
Fields
actions(u32): action count for the tick.action_duration_ms(u64): duration in milliseconds.filesystem_read_bytes(u64): filesystem bytes read.filesystem_write_bytes(u64): filesystem bytes written.network_read_bytes(u64): network bytes read.network_write_bytes(u64): network bytes written.http_requests(u32): HTTP requests issued.
Constraint
Constraint defines hard or soft invariants enforced during a loop.
Fields
id(String): stable identifier.kind(ConstraintKind):HardorSoft.scope(ConstraintScope):Global,Action, orState.predicate(String): expression evaluated by a constraint engine.obligation(Option<String>): obligation text applied when matched.
VerificationResult
VerificationResult records allow/deny decisions with traceable detail.
Fields
allowed(bool): decision flag.reasons(Vec<String>): ordered reason codes or messages.verifier_results: structured per-verifier evidence when available.
Feedback
Feedback captures post-execution evaluation signals.
Fields
kind(String): source type (human/automated/environment).payload(serde_json::Value): structured feedback content.recorded_at(OffsetDateTime): capture timestamp.
Reward
Reward records scalar signals derived from feedback or outcomes.
Fields
value(f64): numeric reward.units(Option<String>): unit label.recorded_at(OffsetDateTime): capture timestamp.context(Option<serde_json::Value>): structured reward context.
Stable extension rule
Extension metadata can carry display hints, external references, correlation IDs, or diagnostics. It must not grant permissions, override identity, install credentials, change quotas, bypass verifiers, or authorize adapters.