Core Objects Reference

This document describes the canonical data structures defined in crates/splendor-types.

Identity Types

TraceId derivation

TraceId = uuid_v5(NAMESPACE_OID, "{run_id}:{sequence}")

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.
• cost_estimate (Option<CostEstimate>): resource estimate for quota checks.
• 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, Custom(String).

CostEstimate fields:

• units (String): unit label (e.g., ms, bytes).
• amount (f64): numeric estimate.

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): Hard or Soft.
• scope (ConstraintScope): Global, Action, or State.
• 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.
• artifacts (serde_json::Value): structured evidence and metadata.

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.

ContentHash

ContentHash captures deterministic hashes for state nodes and snapshots.

Fields

• algorithm (HashAlgorithm): currently Blake3.
• value (String): hex-encoded digest.

String format

{algorithm}:{value}

TraceIntegrity

TraceIntegrity records per-tick integrity chain metadata.

Fields

• prev_event_hash (Option<ContentHash>): hash of the previous trace event.
• event_hash (ContentHash): hash of the current LoopTickCompleted event computed with integrity omitted.