Core concepts

One contract

Each public operation defines its name and version, input and output schemas, MCP/REST/SDK surfaces, route, scope, effect, idempotency, handler, safe errors, and receipt presentation in @hivebase/api-schema.

MCP definitions, REST validation, OpenAPI, SDK types, and reference docs derive from that contract.

Visibility

Context and activity reads are evaluated for the caller. Workspace, team, leadership, private, and restrictive visibility tags are enforced before data is projected into a response.

Cursors

context.sync cursors are opaque durable values. Store and replay them exactly; do not parse timestamps or tenant information from them. If a response sets reset_required, discard context cached under the previous cursor before applying the replay because the caller's visibility has changed.

Writes and receipts

context.remember and decision.record are E1 writes. When permitted, they execute inline and return a durable WriteReceipt. If inline execution is interrupted, the background worker can recover the same intent.

Receipt states are:

accepted | processing | applied | failed | rejected | expired

A receipt exposes only safe entity, retry, error, and correction information. Private input and policy evidence are never returned.

Idempotency

Supply a caller-stable idempotency_key for retries. The same key and request return the original receipt. Reusing a key with different input returns a conflict.