Mobility & operationsnormative v1.4.0bundle v1.4.132 blocks

32. API, event, query, SDK, and conformance implementation

Concept & directionLNK

The developer surface must make the safe path the easy path. Canonical writes are narrow; expressive reads operate over policy-bound projections; high-volume artifacts use direct upload plus manifests; events are at-least-once; every consequential action returns an auditable receipt. OpenAPI or AsyncAPI documents describe transport contracts but remain subordinate to immutable RTracer schemas and vocabularies.

#32.1 HTTP resource conventions

Surface	Request contract	Response contract
POST /v1/records	Idempotency-Key, exact Content-Type/schema, optional request signature	201 record receipt; 200 exact retry; 409 equivocation/conflict
GET /v1/records/{id}	authorization, representation media type	Canonical record or policy projection; immutable ETag
GET /v1/entities/{id}	projection, validAt, knownAt, minimumCheckpoint	Audience-specific entity view plus explanation/checkpoint
GET /v1/entities/{id}/timeline	record families, cursor snapshot, time filters and conflict mode	Stable page with next cursor bound to same ledger watermark
POST /v1/query	bounded typed query AST, cost budget, projection policy	Results, truncation/cost, input checkpoint and explanation
POST /v1/artifacts/uploads	media type, size, digest/algorithm, policy and purpose	Short-lived upload capability; no semantic record yet
POST /v1/telemetry/segments	artifact confirmation and SegmentManifest	Manifest receipt, quality disposition and checkpoint
POST /v1/actions	proposal, requested grant, confirmation mode and idempotency	Inert action ID and policy evaluation, never implicit execution
POST /v1/auctions/{id}/bids	bidder session, amount/currency, eligibility evidence and idempotency	Immutable bid admission/rejection receipt and trusted time
GET /v1/events	consumer, partition, after sequence, event kinds and projection policy	At-least-once ordered partition stream with checkpoint

#32.2 Request integrity, concurrency, and caching

Idempotency-Key is scoped to tenant, authenticated principal and operation family; reuse with different canonical request bytes is equivocation.
Mutable workflow resources use ETag/If-Match on their projection version; canonical records themselves are immutable.
HTTP message signatures may protect selected request components, but authorization still evaluates current grants and context.
GET responses identify projection/schema/policy version, validAt/knownAt and checkpoint; cache keys include all of them plus disclosure class.
Sensitive responses default to no-store or private caching. A public cache never receives private source fields before redaction.
Retries use bounded exponential delay and Retry-After where declared; clients never retry non-idempotent connector effects without a stable action ID.

#32.3 Problem response profile

Table

Problem Details-compatible error - illustrative JSON
{
  "type": "https://schemas.rtracer.example/problems/port-incompatible/v1",
  "title": "Connection ports are incompatible",
  "status": 422,
  "detail": "The requested fuel outlet cannot connect to an electrical-power inlet.",
  "instance": "urn:rtracer:problem:018f...",
  "code": "RTR-CONFIG-PORT-004",
  "stage": "graph-validation",
  "recordPath": "/body/edges/3",
  "constraintRef": "shape:rtracer.port-compatibility/v2#medium",
  "retryable": false,
  "correlationId": "018f...",
  "safeContext": {"expectedFamily": "electricalPower", "receivedFamily": "fluid"}
}

Human detail is not parsed by clients. Stable code, stage, path, constraint and retryability drive program behavior. Errors do not expose whether an inaccessible entity, bid, telemetry stream or private profile exists.

#32.4 Typed query algebra

Operator	Meaning	Required limit
entity	resolve one or more opaque entity roots	tenant/policy scope and maximum seed count
asOf	validAt and knownAt temporal slice	explicit defaults; bounded historical window
records	filter typed record families, truth lanes, status and authority	maximum result/page and stable snapshot
traverse	follow named relationship/graph edges	depth, edge kinds, node count, cycle behavior and time
configuration	select snapshot, diff, installed item or topology	exact configuration or declared current projection
matchRecipe	evaluate versioned TypeRecipe against facets	explanation and indeterminate/conflict behavior
aggregate	count/sum/min/max/histogram over permitted values	privacy threshold, unit compatibility and uncertainty rule
search	text/facet/geospatial discovery over a disclosure-safe index	ranking version, location precision and no private inference
explain	return inputs, policy decisions, derivations and truncation	redact explanation edges independently where needed

#32.5 Event contract

Table

Canonical admission-event transport v1.4
CanonicalAdmissionEvent {
  profile, eventId, eventKind: "ledger.record-admitted.v1",
  ledgerId, tenantId, logicalShardId, chainEpoch, commitSequence,
  streamId, streamSequence, recordId, recordDigest,
  receiptId, receiptDigest, correlationId?, causationId?,
  recordedAt, eventDataDigest
}

One admitted record produces exactly one canonical admission event.
brokerPartitionKey = tenantId || logicalShardId || chainEpoch
Delivery is at-least-once; retries preserve eventId and canonical bytes.
Derived stream topics MUST NOT advance canonical shard checkpoints.
ChangeEvent {
  eventId,
  tenantId,
  partition,
  ledgerSequence,
  eventKind,
  recordId,
  recordType,
  subjectIds[],
  recordedAt,
  canonicalRecordDigest,
  disclosureClass,
  transportAttempt,
  traceContext?
}

Rules: event payload never replaces the canonical record; consumers may fetch
the authorized representation. Delivery is at-least-once. Order is guaranteed
only inside the declared partition. Replays keep the same semantic event ID.

#32.6 Import and export dossier

Package part	Required content
manifest	export ID, producing system, tenant/subject scope, purpose, time, format, pack/schema lock and file digests
records	canonical records and proofs or authorized projections with loss/disclosure manifest
artifacts	included bytes, external references, unavailable/withheld markers, rights and encryption/key instructions
vocab/schema	all non-public or non-guaranteed definitions required for offline interpretation
ordering	ledger ranges, checkpoints and dependency graph so imports can detect gaps
privacy	audience, legal/purpose basis, redactions, location precision, expiry and onward-use duties
import receipt	source dossier digest, mappings, created candidates/records, conflicts, quarantines and information loss

#32.7 SDK requirements

SDK area	Contract
generated types	wire models generated from locked schemas; unknown extensions preserved as bytes/structured value
canonicalizer	official conformance vectors; reject ambiguous input before hashing or signing
validator	local schema/context/shape registry, resource limits, structured findings and no network fetch
auth client	short-lived credentials, current grant/purpose, request integrity, revocation handling and no secret logging
idempotency	automatic stable key per logical operation and durable retry state for connector effects
pagination	snapshot-bound cursors, checkpoint awareness and transparent rate/backpressure handling
telemetry	stream/chunk writer, schema lock, sequence/clock metadata, digest and resumable upload
observability	trace context and opaque correlation IDs; sensitive identifiers excluded from labels

#32.8 Conformance harness and release gates

Validate positive and negative examples for every schema and graph shape, including maximum-size and malformed-input cases.
Run canonicalization vectors across every supported language; digests and rejection outcomes must match exactly.
Run append/idempotency/outbox fault injection at every transaction boundary and verify no partial canonical state.
Replay every projection from empty state and compare canonical outputs/checkpoints with a golden corpus.
Run privacy non-interference tests: hidden fields/edges must not leak through status, count, ranking, timing, errors or cache keys.
Run agent/market authorization matrices for grant expiry, transfer, revocation, confirmation, money limits and connector retries.
Restore ledger, registry, key metadata and artifacts from independent backup; regenerate graph/search/feed views within target RTO.
Publish schema/pack/API versions, migration/loss manifests, security review, SLO changes and conformance evidence before activation.

#32.9 Reference deployment slices

Slice	Deployable boundary	Exit proof
S0 identity/evidence	entity, ledger, identifier claims, artifacts, schema registry and owner vault	KUN, RC car and blimp import/export/replay with conflicts
S1 configuration/life	snapshots, parts/ports, modification, maintenance, wash/media and condition	Complete before/after and due-history reconstruction
S2 telemetry	capture session, manifests, object/lake storage, derived metrics and privacy projection	Raw-to-summary reproducibility and clock/dropout fixtures
S3 public vehicle	profile, timeline, spotting claim, followers, grounded drafts and event discovery	No private-location or unsupported-fact leakage
S4 governed action	grant/policy engine, confirmations, connectors, ticket/training/merch and receipts	Every effect reconciles or compensates under retry
S5 market	appraisal/listing/offers/auction/bids/transaction and provider adapters	Serialized close, eligibility, authority and settlement tests
S6 ecosystem	pack registry, SDKs, federation/import/export and partner/tenant governance	Unknown pack round-trip and portable dossier restore