08 — Profiles#

A profile gives application meaning to private content. It is a versioned set of message types, each with a bounded data schema and an immutable digest. A profile never changes identity verification, admission, deduplication or delivery, and installing one never grants execution authority. There is no central catalogue: official and third-party profiles use the same mechanism.

Installation and announcement#

An endpoint installs a manifest only through its local management interface. Receiving a manifest, URI, descriptor or message MUST NOT install anything, and implementations never fetch schema references or run downloaded validators. The core profile is always installed. An agent lists each other enabled profile in its descriptor profiles as {id, digest} with the profile digest (04). Two endpoints share a profile only when ID and profile digest are both equal; an equal ID with another digest is incompatible.

Implementations MAY bound installed manifests. An endpoint MUST reject a manifest that defines a message type an installed manifest already defines.

Manifest format#

A manifest is the closed object {id, messages} whose canonical JSON is at most MAX_MANIFEST_BYTES. id and every message type are namespaced identifiers (02); third-party manifests MUST NOT use the reserved ace: prefix. messages holds 1–32 closed objects {type, schema} with distinct types; each schema has type: "object". An invalid manifest is invalid_argument.

Schema dialect#

schema is a bounded subset of JSON Schema, not a general interpreter. Each schema node is a closed object with type (one of object, array, string, integer, boolean, null), an optional enum, and only these type-specific keywords:

All bounds are integers in [-(2^53-1), 2^53-1]. Schemas nest at most 8 edges below the root. enum holds 1–64 values, each matching the node without its enum; a value matches enum when its canonical JSON equals that of a member. A JSON null matches only a null schema: an optional member is omitted, never null. Unknown or inapplicable keywords, $ref and any loader or code are rejected.

Digests#

There is one digest algorithm, over canonical JSON (02):

profile digest = lowercaseHex(SHA-256(canonicalStateBytes(manifest)))
message digest = lowercaseHex(SHA-256(canonicalStateBytes({type, schema})))

The profile digest identifies a profile in descriptors and contact requests. The message digest is the schemaDigest of private content (03) and binds its type. Changing any part of a manifest changes its digest; incompatible semantics SHOULD use a new versioned ID. A digest is an agreement identifier, not evidence that a service is trustworthy.

Official manifests#

The official manifests are the files in profiles/. Every SDK bundles these exact files and computes digests from them; they are exempt from the reserved-prefix rule.

A third-party example is examples/translation-profile.json.

Profile rules#

Rules that a schema cannot express (references between messages, state machines, embedded signed objects) are profile rules. A rule governs a set of message types and sees, for each message, the event {direction: "send" | "receive", from, to, messageId, timestamp, type, threadId?} (for send, timestamp is the time the Outbox entry was created) and the body. It has two steps:

• check runs on send before the Outbox entry is persisted (before encryption for receipts and contacts, which bypass the Outbox) and on receive at pipeline step 10 (06). It reads state only and fails with an ACE error whose code becomes the rejected receipt code.
• commit applies state changes, idempotently per (from, messageId). On receive it runs inside the transaction that persists the delivery record; on send, as below.

Sender state and busy threads#

A message is governed when some installed rule lists its type. For a governed message with a threadId, the thread (peer, threadId) is busy while such a message from the local agent is pending in its Outbox. The sender:

1. runs check at enqueue; enqueueing another governed message on a busy thread fails with thread_busy before check, and nothing is stored;
2. runs commit only when the delivered receipt for the message arrives, so its state follows what the receiver applied;
3. changes no rule state on a rejected receipt; the thread is free again;
4. frees the thread without any state change when the message expires or is abandoned; the outcome is then unknown, and a late delivered receipt still runs commit (06).

On receive, a governed message on a thread that is busy towards its sender is rejected with thread_busy at step 10, before check. When both parties send on one thread at once, both messages are therefore rejected and neither side's state changes; the parties then continue from the unchanged state. A message without a threadId, or of a type no rule governs, never makes a thread busy.

The core rules for receipts and contacts are always active. Rules for official profiles are optional modules (commerce). The core pipeline contains no profile-specific branches.