43. Exact HTTP, event, query, federation, and SDK contracts

Canonical bytes are not an audience view
GET /records/{recordId}/canonical returns the admitted portable bytes only to a principal authorized for that record class and representation. GET /vehicles/{assetId}/profile returns a rebuildable, redacted projection. Their ETags, digests, caching, deletion behavior and authorization are not interchangeable.

Normative append exchange
POST /v1/records:append HTTP/1.1
Content-Type: application/vnd.rtracer.record+json;version=1.3
Accept: application/vnd.rtracer.ingest-receipt+json;version=1.3
Authorization: DPoP <short-lived-token>
DPoP: <proof bound to method, URL, token and key>
RTracer-Tenant: 5abfa9c8-4ec5-4de9-b786-3b3b1b1d8ed4
RTracer-Stream: 606f60af-fb14-42b4-8677-1ea9a35c2d5b
RTracer-Expected-Sequence: 184
RTracer-Writer-Epoch: 12
Idempotency-Key: 01JAZ...client-random...
Content-Digest: sha-256=:...:

Body = exact RecordCore bytes. Detached proofs are supplied as a bounded
multipart part or by digest-addressed ProofRecord references.

201 Created
Location: /v1/records/019b.../receipt
ETag: "receipt-sha256-..."
RTracer-Record-Digest: sha256:...
RTracer-Receipt-Digest: sha256:...
RTracer-Stream-Sequence: 185
RTracer-Logical-Shard: ledger-03
RTracer-Chain-Epoch: 1
RTracer-Commit-Sequence: 93828011

Retry of same scoped key + same requestDigest returns 200 and original receipt.
Same key + different requestDigest returns 409 RTR-IDEMPOTENCY-EQUIVOCATION.

Reproducible view and confidential pagination contract
ProjectionDescriptor {
  projectionKind, projectionVersion, audienceClass, requestingPrincipalId?,
  purpose, validAt, knownAt, sourceCheckpointVector,
  policyBundleDigest, registryCheckpoint, codeDigest,
  locale, unitProfile, privacyTransformRefs[], inputRecordDigestSetDigest
}

projectionDigest = SHA256(domain("PROJECTION", version) ||
  canonicalize({descriptor, renderedSemanticObject}))

CursorBindingV1_4 {
  cursorProfile, queryDigest, requestingPrincipalId?, audienceClass,
  purpose, checkpointVector, projectionDescriptorDigest,
  codeDigest, registryCheckpoint, policyBundleDigest,
  sortPosition, expiresAt, keyEpoch
}

The client receives authenticated encryption of CursorBindingV1_4 or a random
server-side handle. Plaintext private sort tuples and tenant IDs are prohibited.
ProjectionDescriptor {
  projectionKind, projectionVersion, audienceClass, requestingPrincipalId?,
  purpose, validAt, knownAt, sourceCheckpointVector,
  policyBundleDigest, registryCheckpoint, codeDigest,
  locale, unitProfile, privacyTransformRefs[], inputRecordDigestSetDigest
}

projectionDigest = SHA256(
  domain("PROJECTION", version) ||
  canonicalize({descriptor, renderedSemanticObject})
)

Projection ETag = quoted projectionDigest.
Canonical-record ETag = quoted recordDigest.
They are never compared as equivalent validators.

CursorPayload {
  queryDigest, tenantId, principalOrAudienceBinding, purpose,
  checkpointVector, sortTuple, pageSize, policyDigest, expiresAt, nonce
}
cursor = base64url(payload) + "." + signature

A cursor is opaque, short-lived, tamper-evident and bound to the exact query,
policy and principal/audience. It is not a free-form database offset.

Bounded typed query surface
Query {
  from: closed resource family,
  where: allOf|anyOf|not|eq|in|range|exists|relationshipPath,
  validAt, knownAt, projectionPurpose,
  select: allowlisted field paths,
  orderBy: stable indexed keys ending in opaque ID,
  page: {first: 1..500, after?: signedCursor},
  consistency: CHECKPOINTED|AT_LEAST_CHECKPOINT,
  minimumCheckpoint?: vector
}

Limits: depth 16; predicates 100; IN values 1,000; relationship depth 5;
wall time 5 s interactive/60 s export; scanned-row/byte budget per tenant.
No arbitrary expression, regex over unindexed private data, user SQL, mutation,
recursive graph query or model-selected query text is accepted.

RFC 9457-compatible failure object
HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type":"urn:rtracer:problem:stream-sequence-conflict",
  "title":"Stream sequence conflict",
  "status":409,
  "code":"RTR-LEDGER-EXPECTED-SEQUENCE",
  "stage":"admission.commit",
  "correlationId":"019b...",
  "retryable":true,
  "safeContext":{"expected":"184","current":"185"}
}

Fields are closed. detail is optional and localized; clients branch on code.
Validation findings carry JSON Pointer, constraint ID and safe rejected-value
class—not the private value. Retryable never overrides idempotency semantics.

At-least-once event envelope
CloudEvent attributes:
  specversion = "1.0"
  id          = eventId (UUIDv7; stable across delivery retries)
  source      = urn:rtracer:service:<serviceId>
  type        = io.rtracer.<domain>.<event>.v1
  subject     = opaque canonical subject route; never VIN/MAC/plate/person
  time        = transaction/recorded time, not necessarily validTime
  datacontenttype = application/vnd.rtracer.event+json;version=1.3
  dataschema  = immutable schema URI containing or resolving to digest
  tenantid, shardid, shardposition, streamid, streamsequence,
  recordid?, recorddigest?, receiptdigest?, correlationid, causationid

data = canonical EventData referencing records/receipts by ID and digest.
transportAttempt, broker partition/offset, delivery time, retry count,
consumer lag and trace propagation are delivery metadata outside EventData.
CloudEvents serialization is a transport envelope, not RecordCore identity.

Disconnected capture and portable dossier contract
EdgeJournalEntry {
  edgeDeviceId, bootId, localSequence, recordId, canonicalBytes,
  recordDigest, proofRefs[], packLock, capturedAtDevice,
  priorLocalDigest, localDigest, syncState
}

Sync:
  1 authenticate device/workload and authorize exact journal scope
  2 compare server acknowledgement vector and local chain
  3 upload missing bytes/proofs with stable per-record idempotency keys
  4 admit independently; preserve conflicts/equivocation and server receipts
  5 append SyncReceipt mapping local sequence to admission disposition
  6 never rewrite edge history; append corrections/invalidation

ExportManifest pins tenant, subject selectors, purpose, policy decision,
source checkpoint, schema/vocabulary/pack locks, record and artifact digests,
encryption recipients, redactions, retention/recipient duties and signature.
Import verifies bytes first, then maps external IDs as assertions; it never
assumes imported tenant, ownership, grants or registry status are local truth.